Dev-Mode Silent Pairing

T3 Code contributor DX — auto-authenticate the web UI on localhost dev servers without exposing the WebSocket/HTTP API to drive-by attacks. Fully invisible to humans and agents. v3, 2026-07-13.

1. Problem & goals

The dev startup pairing credential is one-time and 5-minute TTL (PairingGrantStore.ts → DEFAULT_ONE_TIME_TOKEN_TTL_MINUTES). Working on multiple T3 Code changes in parallel means every fresh browser context — a new worktree's auto-opened tab, incognito, and especially an agent's Playwright/headless profile — needs a fresh /pair#token=… URL scraped from interleaved dev-runner stdout. Agents routinely give up on browser verification because of this.

• Goal: a fresh browser context that loads the dev web app on localhost is authenticated automatically, with zero setup, zero visible tokens, zero log-scraping. Humans and agents never think about pairing in dev.
• Goal: no weakening of the auth model — a malicious webpage must still be unable to reach the WebSocket or authenticated HTTP API, which can spawn full-access coding agents (connect = RCE). Note /api/orchestration/dispatch is reachable with standard scopes over plain HTTP, so the WS upgrade is not the only surface to protect.
• Non-goal: changing prod, desktop, remote-access, or hosted-app pairing. The /pair screen remains as fallback and keeps precedence when an explicit token is present.
• Non-goal: defending against malicious local processes — they can already read ~/.t3/dev/secrets directly.

2. Threat model — why not just disable auth

Loopback binding does not protect a dev server from the browser you are using. Any webpage can open ws://localhost:13773 — WebSocket handshakes are exempt from CORS — and plain fetch() requests to localhost also send fine cross-origin (CORS gates reading, not sending). The session cookie (+ WS ticket) requirement is currently the only barrier between an ad iframe and a full-access provider session. Drive-by localhost attacks are a well-worn class (Selenium, Jupyter, and Ollama all grew token auth for this reason). So "pairing off in dev" is off the table; instead we make pairing automatic for legitimate same-origin clients.

3. Auth boundary: Origin as primary gate, CORS as backstop

Dev-only endpoint that mints a normal one-time pairing credential. Three layers, outermost first:

1. Eligibility (mount-time facts, checked per-request): the endpoint only does work when the server is a local web-dev server: mode === "web", auth policy exactly loopback-browser, devUrl set and devUrl.hostname loopback. This excludes prod (no devUrl), desktop dev (desktop-managed-local policy — its renderer origins are CORS-allowlisted, so the old "not remote-reachable" guard would have leaked the response to Electron contexts), LAN-bound dev (remote-reachable), and a hostile --dev-url (which today becomes a credentialed CORS origin with no hostname validation — this design must not turn it into an authentication root).
2. Request authentication (per-request, primary): non-simple POST (JSON body → preflighted) requiring Origin to exactly equal devUrl.origin, and the parsed request Host to be loopback. Browsers attach Origin to all POSTs, including same-origin ones, and cannot forge it; it survives the Vite proxy unmodified. The Host check stays as anti-rebinding defense for non-proxied direct requests.
3. Response opacity (backstop): the existing browserApiCorsLayer allowlists only devUrl.origin + desktop renderer origins, so even a response that slipped the above would be unreadable cross-origin. No longer load-bearing on its own — the proxy path bypasses it — but it keeps the direct-fetch drive-by dead even if a guard regresses.

4. Complete flow

Sequence in words:

5. Server changes

New contract endpoint: POST /api/auth/dev-pairing-token

Auth routes are a typed EnvironmentHttpApi group (packages/contracts/src/environmentHttp.ts:380) with one required handler chain in apps/server/src/auth/http.ts:200 — so this is a declared contract endpoint (success + error schemas in contracts), not an ad-hoc raw route. The handler is always mounted; ineligibility is an explicit typed 404-equivalent response. Relying on conditional non-registration is wrong in this codebase: the wildcard GET route 302-redirects to Vite in dev and serves the SPA index.html as fallback in prod (apps/server/src/http.ts:222–290), so an absent route would produce redirect loops or a 200 HTML page instead of a 404.

Eligibility (any failure → typed not-available error, mapped to 404):
  config.mode === "web"
  config.devUrl !== undefined
  isLoopbackHost(config.devUrl.hostname)        // --dev-url must not become an auth root
  descriptor.policy === "loopback-browser"      // excludes desktop dev + remote-reachable

Request authentication (failure → 403 + server log):
  request method POST, JSON content-type        // non-simple → preflight, Origin always present
  request.headers.origin === config.devUrl.origin   // exact match; primary gate, survives Vite proxy
  parseRequestHost(request.headers.host) is loopback // anti-rebinding for direct (non-proxied) requests

Then:
  mint one-time credential — AuthAdministrativeScopes, subject "dev-auto-bootstrap",
  default 5-min TTL, label "dev-auto"
Respond:
  { credential, expiresAt }    (Cache-Control: no-store)

• Host parsing needs a new helper. isLoopbackHostname() (http.ts:66) matches only exact localhost/127.0.0.1/::1 and does not strip ports — a raw Host: localhost:13773 would fail, making the feature dead on arrival. And auth/http.ts cannot import it anyway: http.ts already imports from auth/http.ts, so that would be a module cycle. Extract one canonical parseRequestHost + loopback predicate into a dependency-neutral module (e.g. alongside startupAccess.ts's isLoopbackHost, which already accepts 127.*), and use it here; test raw Host values with ports, brackets, and malformed input.
• Scopes/subject: mint via a dedicated EnvironmentAuth method (sibling of issueStartupPairingCredential) so the admin-scope + internal-subject combination is explicit and the subject is excluded from the Settings pairing-link listing like INTERNAL_ADMINISTRATIVE_BOOTSTRAP_SUBJECT is today.
• Flooding: every mint persists a pairing-link row and there is no pruning path (AuthPairingLinks.ts filters expired rows from listings but never deletes). The Origin-checked POST means unauthorized pages can no longer trigger the write at all (preflight fails before the request executes). Optional hardening, not required for v1: prune expired one-time rows on issuance.

CORS — no change, now backstop only

browserApiCorsLayer (apps/server/src/http.ts:49) already allowlists only config.devUrl.origin + the two desktop renderer origins, with credentials. The new route sits behind it. Keep the test asserting the response never carries ACAO: * — but note the desktop renderer origins being allowlisted is exactly why CORS opacity alone was insufficient as a guard (§3, eligibility check excludes desktop by policy instead).

6. Startup flow change (required)

Upgraded from "optional follow-up" after review. Today every non-desktop browser startup mints an administrative one-time token and opens /pair#token=… (serverRuntimeStartup.ts:252, resolveStartupBrowserTarget). With silent pairing, the gate authenticates before the /pair route consumes that token, and /pair then redirects away (pair.tsx:9) — leaving an unconsumed admin credential live for 5 minutes in the opened URL, terminal scrollback, and browser history. Two coordinated changes:

• Server: when the silent-pairing eligibility conditions hold (web dev mode, loopback, loopback-browser policy), resolveStartupBrowserTarget opens the plain dev URL and skips minting the startup credential. Headless output, prod, and remote flows keep today's behavior.
• Web: the gate skips the silent path whenever an explicit pairing token is present in the URL (covers manual /pair#token links, remote pairing, hosted pairing), so explicit credentials are always consumed and never preempted.

7. Web changes

In apps/web/src/environments/primary/auth.ts and the root-route gate. The auth module already has a bootstrap state machine — bootstrapPromise dedup, cached auth state, and reset points used by backend swaps and tests (auth.ts:151, 510, 535). The silent attempt is modeled inside that state machine, not as a separate module-level latch: a standalone latch would survive reauthenticatePrimaryEnvironment and test resets, so one early 404 would disable the feature until a full page reload.

• Add fetchDevPairingCredential() next to the other primary-environment requests: POST the endpoint, treat any non-200 / network error as "not available" and return null. Never surface an error.
• In the bootstrap flow: when session state resolves unauthenticated and the attempt is warranted, try fetch → exchangeBootstrapCredential → re-resolve, before yielding the pairing-required state. Attempt-once per bootstrap cycle, reset alongside the existing bootstrap fields (so backend restarts / HMR / reauth get a fresh attempt).
• When to attempt: import.meta.env.DEV (dead-code-eliminated from prod bundles), not isHostedStaticApp(), not a desktop-bridge context (don't rely on gate ordering to keep Electron off this path — its origins are CORS-allowlisted), and no explicit pairing token in the URL (§6).
• Concurrent-tab race: two fresh tabs may both mint; each gets its own one-time token, both exchanges succeed independently. No coordination needed.
• The /pair route and surface are untouched.

8. Attack analysis

9. Parallel dev instances

This composes with the existing multi-instance setup (T3CODE_DEV_INSTANCE=<name> bun run dev, ports hashed from the name):

• Each dev server mints its own credentials — no cross-instance coordination.
• Web-dev instances that share a T3CODE_HOME (the default ~/.t3) share ~/.t3/dev: same session DB, same signing secret. The t3_session cookie is port-independent but host-scoped: sessions are shared across instances only when they use the same T3CODE_HOME and the same hostname — localhost and 127.0.0.1 do not share cookies, and two isolated homes on the same hostname will overwrite each other's cookie with mutually unverifiable tokens (the silent path then just re-pairs, which masks the collision harmlessly in dev).
• Agents get the full win regardless of cookie sharing: headless profiles start cookie-less, silently pair on first page.goto, and need zero token plumbing.

10. Test plan

vp check and vp run typecheck green per AGENTS.md.

11. Docs / AGENTS.md

Short additions, high leverage for agents:

• AGENTS.md — new "Verifying changes in the browser" section:
  • Starting a dev server to verify changes is expected and allowed: T3CODE_DEV_INSTANCE=<worktree-name> bun run dev picks non-conflicting ports deterministically (server 13773+, web 5733+; runner probes for free ports and prints the chosen pair).
  • On localhost dev servers the web UI authenticates automatically — no pairing code needed; just load the web port.
  • Dev instances sharing the default T3CODE_HOME share state; a browser session carries across instances on the same hostname (use localhost consistently — it does not share cookies with 127.0.0.1).
• docs/reference/scripts.md: extend "Running multiple dev instances" with the auto-auth note and the hostname/cookie qualification; fix the stale T3CODE_STATE_DIR reference while in there (the env var no longer exists — state dir derives from T3CODE_HOME).
• docs/cloud/environment-auth.md: one section documenting the dev fast-path, its guards (Origin-checked POST, loopback-browser policy, loopback devUrl, Host parse), the admin-scopes decision, and the startup-flow change.

12. Open questions & scope

Size estimate (revised after review)

• Contracts: endpoint declaration + schemas — ~30–50 lines
• Server: handler + eligibility/Origin/Host guards + dedicated issuance method + extracted host parser + startup-flow change — ~120–180 lines
• Web: bootstrap-integrated silent attempt + guards — ~40–60 lines
• Tests: server (incl. real Vite-proxy test), startup, web gate — ~250–400 lines (the bulk, and the part that must not regress)
• Docs: ~25 lines

Pairing UX, grant store, session store, CORS layer, desktop/prod/remote flows: untouched. The startup browser-open path changes in dev only (§6).