feat: silent pairing for local web-dev servers

[t3dotgg]

What

Local web-dev servers now authenticate the web UI automatically — no more scraping one-time /pair#token=… URLs out of dev-runner stdout for every fresh browser context. This was the main DX friction for working on multiple T3 Code changes in parallel, and the reason coding agents kept giving up on browser verification.

Design doc (reviewed by gpt-5.6-sol, findings incorporated): https://xaxuzu0q3o8s.postplan.dev

How

New endpoint POST /api/auth/dev-pairing-token mints an ordinary one-time, 5-minute administrative pairing credential (subject dev-auto-bootstrap, hidden from pairing-link listings) that the web app immediately exchanges through the existing browser-session flow.

Security model (why this doesn't reopen the drive-by-localhost hole the pairing codes exist to close):

• Eligibility: endpoint answers 404 dev_pairing_not_available unless the server is web-mode + loopback-bound (loopback-browser policy) + configured with a loopback dev URL. Prod, desktop, LAN-bound dev, and hostile --dev-url values are all ineligible. The handler is always mounted — conditional non-registration would fall into the SPA/302 wildcard route instead of 404ing.
• Per-request: browser-attached Origin must exactly equal the dev origin (survives the Vite /api proxy, which rewrites Host but not Origin — Host/CORS-only guards are defeated by the proxy path), plus a loopback Host header check against DNS rebinding on direct requests. JSON payload forces a CORS preflight, so unauthorized web origins can't even trigger credential issuance.
• Admin scopes match what startup pairing grants today, so Settings → Connections keeps working in dev.

Startup: eligible dev servers open the plain dev URL instead of minting a startup /pair#token credential the silent path would leave unconsumed in terminal scrollback. All other startup shapes unchanged.

Web: the auth-gate bootstrap tries the endpoint when unauthenticated in dev — never in hosted/desktop contexts, never when an explicit #token is present (manual/remote pairing keeps precedence) — and falls back to the pairing screen silently on any failure. import.meta.env.DEV keeps it out of prod bundles.

Extracted netHost.ts host-header parsing (the existing isLoopbackHostname mishandles Host: localhost:13773, and importing it into auth/http.ts would create a module cycle).

Docs: AGENTS.md "Verifying Changes in the Browser" section for agents/contributors, dev-instance auth notes in scripts.md (+ stale T3CODE_STATE_DIR fix), security spec in environment-auth.md.

Verification

• vp check, vp run typecheck green; server 1427 passed, web 1288 passed, contracts 179 passed
• New tests: guard unit tests (Origin/Host/eligibility incl. port + IPv6 + rebinding shapes), 7 endpoint integration tests (incl. a raw node:http rebound-Host request and admin-scope/listing-exclusion assertions), 4 startup-target tests, 5 web-gate tests (incl. explicit-token precedence and reauth retry)
• Live check against a running dev instance: mint 200 with dev origin (direct + through Vite proxy), 403 for foreign/missing Origin and rebound Host
• E2E: fresh cookie-less Playwright profile loads the dev web port and lands authenticated with zero interaction:

🤖 Generated with Claude Code

---

Note

High Risk
Introduces an unauthenticated endpoint that issues administrative credentials; safety depends on narrow eligibility and Origin/Host guards—misconfiguration or guard bypass would be serious.

Overview
Adds silent dev pairing so local web dev servers can authenticate the UI without manual pairing codes or scraping /pair#token URLs from stdout.

Server: New unauthenticated POST /api/auth/dev-pairing-token mints a one-time administrative bootstrap credential (dev-auto-bootstrap, hidden from pairing-link listings). It returns 404 when the server is not web-mode + loopback loopback-browser policy + loopback devUrl, and 403 when Origin does not exactly match the dev origin or Host is not loopback. Startup opens the plain dev URL (no startup pairing token) when eligible.

Web: On load in import.meta.env.DEV, the auth gate calls the endpoint and exchanges the credential via the existing browser-session flow, with silent fallback to the pairing screen; skipped for explicit #token, desktop bridge, and hosted static apps.

Shared: Loopback/host parsing moves to netHost.ts (stricter 127.0.0.0/8 and Host: port handling). Docs and agent guidance updated for auto-auth on localhost dev.

^{Reviewed by Cursor Bugbot for commit 929d35a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add silent pairing for local web dev servers via new /api/auth/dev-pairing-token endpoint

• Adds a new POST /api/auth/dev-pairing-token endpoint that issues a one-time administrative pairing credential for eligible local dev requests, returning 404 or 403 for ineligible configurations or invalid headers.
• The web client silently authenticates against local dev servers during development using shouldAttemptDevPairing in auth.ts, skipping the pairing screen when on a loopback host in dev mode without an explicit token.
• Startup no longer mints a pairing URL for eligible dev servers; resolveStartupBrowserTarget in serverRuntimeStartup.ts now returns a plain base URL with requiresPairing=false instead.
• Adds host parsing and loopback validation utilities in netHost.ts; the startupAccess.ts loopback check is now stricter (exact IPv4 match instead of startsWith("127.")).
• Behavioral Change: listPairingLinks excludes dev-auto-bootstrap subjects by default, so dev pairing credentials do not appear in pairing-links listings.

^{Macroscope summarized 929d35a.}

Summary by CodeRabbit

• New Features

  • Development servers can now authenticate browsers silently on eligible localhost configurations, avoiding manual pairing.
  • Startup automatically opens the development server or requests pairing when authentication is required.
  • Added secure validation for development pairing requests and one-time administrative credentials.

• Documentation

  • Added guidance for browser verification, development-instance authentication, shared state, and localhost cookie behavior.
  • Documented the development silent-pairing endpoint and its eligibility rules.

• Tests

  • Added coverage for pairing security, loopback hosts, startup authentication, and silent browser authentication.

[coderabbitai]

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: silent pairing for local web-dev servers.
Description check	✅ Passed	The description is detailed and covers what changed, why, behavior, docs, and verification, so it is mostly complete despite missing the exact template headings.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/disable-pairing-codes

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new authentication endpoint that mints administrative credentials for dev servers. An unresolved review comment identifies a potential security bypass when Vite is LAN-exposed, allowing remote Origin forgery. Auth changes with open security concerns warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 929d35a. Configure here.}

[cursor]

Proxied Origin forge bypass

Medium Severity

The Host loopback check is defeated for requests through the Vite /api proxy because changeOrigin rewrites Host to the loopback upstream. Eligibility only constrains the server bind address, not the Vite listen address. If Vite is LAN-exposed (HOST=0.0.0.0), a remote client can forge Origin to the configured devUrl origin and mint an administrative pairing credential without local filesystem access.

Additional Locations (1)

• apps/server/src/auth/http.ts#L353-L367

 

^{Reviewed by Cursor Bugbot for commit 929d35a. Configure here.}

[t3dotgg]

Closing because the dev-auth direction has been overtaken by isolated worktree state and single-origin sharing in #4555/#4556 plus explicit fresh pairing in #4955. That path is simpler and avoids preserving a reusable silent administrative bootstrap surface.