# Network · Authentication

> How 2plot.ai acts as the Clerk PRIMARY for the whole domain galaxy — the satellite whitelist, the returnTo round trip, and the signup webhook.

---

.. toc::

## One account, every app

2plot.ai is the network's Clerk **primary** instance. Satellite apps
(2plot.media, 2plot.xyz, cast.2plot.net, …) run in satellite mode and
send visitors here to sign in; after auth the visitor lands back on the
exact page that sent them.

The round trip:

1. A satellite deep-links to `https://2plot.ai/onboarding?returnTo=<url>`.
2. The hub validates `returnTo` against the **satellite whitelist** —
   the same origin list handed to Clerk itself, so there is exactly one
   place a redirect can be authorized (`lib/auth.py`,
   `allowed_redirect_origins()`; env-overridable via
   `CLERK_ALLOWED_REDIRECT_ORIGINS` so a new satellite needs no deploy).
3. The sign-in modal opens with force-redirect URLs pointing back to the
   validated origin. Invalid or missing `returnTo` falls through to the
   hub home — never an open redirect.

.. admonition::Fully optional in dev
    :icon: tabler:flask
    :color: yellow

    With zero `CLERK_*` keys in the environment the entire auth layer
    no-ops: the app runs unauthenticated, owner gates open up, and no
    network calls are made. Identical code path, zero configuration.

## The signup webhook

`POST /webhooks/clerk` (Svix-verified, fail-closed) receives Clerk
events. On `user.created` the hub provisions the new account's welcome
wallet on piratesbargain.com through an HMAC-signed cross-app call — and
records the outcome (with a privacy-hashed account reference) to the
heartbeat, which is the first sensor of the future ledger-of-record
flow.


```python
# File: lib/auth.py

"""Optional Clerk authentication gate (dash-clerk-auth, vendored).

The integration is FULLY OPTIONAL: with no CLERK_* keys in the environment (or
the package missing) the app runs exactly as before — the package's dash hooks
no-op, no script/store is injected, no session machinery or routes register.
The single source of truth for "is auth on" lives here; run.py
(register/configure), the header avatar chip, and the navbar's owner-gated
Analytics reveal all call `clerk_enabled()`.

Env vars (set all three to enable):
  CLERK_SECRET_KEY       sk_...   backend SDK key (never exposed to the client)
  CLERK_PUBLISHABLE_KEY  pk_...   embedded in the injected <script>
  CLERK_SIGN_IN_URL      https://<app>.clerk.accounts.dev/sign-in
REQUIRED in prod (run.py warns loudly when missing):
  SESSION_SECRET         signs the session + __dca_identity cookies — without it
                         the package falls back to a PUBLIC dev default string.
  CLERK_FRONTEND_API     https://<app>.clerk.accounts.dev — origin clerk.browser.js
                         is served from; read by the package straight from the env
                         (not gated here). Dev *.accounts.dev instances can derive
                         it from CLERK_SIGN_IN_URL, but production custom-domain
                         instances CANNOT (their Account Portal doesn't proxy
                         /npm/@clerk/clerk-js) — set it explicitly in prod.

NOTE: read keys at CALL time (not import time) — lib/backend's load_dotenv must
have run first, and tests blank env vars per-process.
"""
import os

# The app owner's Clerk account — gates the owner-only surfaces (/traffic and
# the navbar Analytics section). Checked CLIENTSIDE against the clerk-auth-store
# email for the nav reveal and SERVER-SIDE by lib/security_block's /traffic
# gate. Env-overridable per deployment.
OWNER_EMAIL = os.getenv("OWNER_EMAIL", "pipinstallpython@gmail.com")


def clerk_keys():
    return (os.getenv("CLERK_SECRET_KEY"),
            os.getenv("CLERK_PUBLISHABLE_KEY"),
            os.getenv("CLERK_SIGN_IN_URL"))


def clerk_enabled():
    """True only when all three CLERK_* env vars are set AND the package imports."""
    if not all(clerk_keys()):
        return False
    try:
        import dash_clerk_auth  # noqa: F401
        return True
    except Exception:
        return False


# Satellite origins the PRIMARY (2plot.ai) may redirect a user back to after a
# Clerk sign-in. The vendored dash_clerk_auth applies this list to Clerk.load()
# on the primary ONLY (gated on !isSatellite) — it is the whitelist that lets a
# satellite's signInForceRedirectUrl actually complete. A missing/malformed
# entry silently strands the user on the primary's home (the 2026-06 prod bug:
# two entries lacked a scheme, and 2plot.net was absent).
_DEFAULT_SATELLITE_ORIGINS = (
    "https://2plot.media", "https://www.2plot.media",
    "https://2plot.net",   "https://www.2plot.net",
    "https://2plot.xyz",   "https://www.2plot.xyz",
    "https://cast.2plot.net",
    "https://2plot.dev",   "https://2plot.me",
    "https://2plot.world", "https://2plot.shop",
    # scheduler-docs origin added here once it has a domain
)


def allowed_redirect_origins():
    """Origins the primary Clerk instance may redirect back to after sign-in.

    Env-first via CLERK_ALLOWED_REDIRECT_ORIGINS (comma-separated) so a NEW
    satellite can be whitelisted without a redeploy; otherwise the galaxy
    default above. Bare hosts are coerced to https:// (a missing scheme is
    what silently dropped 2plot.world/2plot.shop in prod) and trailing slashes
    are stripped (Clerk matches on origin). De-duplicated, order preserved.
    """
    raw = os.getenv("CLERK_ALLOWED_REDIRECT_ORIGINS", "").strip()
    items = [x.strip() for x in raw.split(",") if x.strip()] if raw \
        else list(_DEFAULT_SATELLITE_ORIGINS)
    seen, out = set(), []
    for it in items:
        if not it.startswith(("http://", "https://")):
            it = "https://" + it
        it = it.rstrip("/")
        if it not in seen:
            seen.add(it)
            out.append(it)
    return out


def identify_request_user(cookies):
    """Display name of the signed-in Clerk user for THIS request, or None.

    Reads the package's signed `__dca_identity` cookie (minted after a Clerk
    session verifies) — a cheap itsdangerous signature check, no Clerk
    roundtrip. Anonymous visitors, auth-off deployments, missing/blank
    SESSION_SECRET, and stale/tampered cookies all return None. Used by the
    analytics tracker to stamp authenticated visits for the /traffic log book.
    """
    if not clerk_enabled():
        return None
    secret = os.getenv("SESSION_SECRET") or ""
    token = (cookies or {}).get("__dca_identity")
    if not token or not secret:
        return None
    try:
        from dash_clerk_auth._identity_cookie import verify
        user = verify(token, secret, max_age=7 * 86400)
    except Exception:
        return None
    if not user:
        return None
    name = " ".join(x for x in (user.first_name, user.last_name) if x) or user.email or user.user_id
    return str(name)[:60]
```

    :defaultExpanded: false
    :withExpandedButton: true

## Who sees what

| Surface | Audience |
| --- | --- |
| Home, onboarding, docs, changelog | Everyone |
| Activity cockpit (header), `/activity/<job>` | Signed-in accounts |
| `/admin/heartbeat`, `/admin/heartbeat/tasks`, `/traffic` | Owner only |

Owner gating rides the signed identity cookie (no Clerk round trip per
request) — see `lib/security_block.py`.

.. llms_copy::Network · Authentication


---

*Source: /docs/network-auth*