fix(connect): preserve CLI OAuth parameters through browser sign-in

[juliusmarminge]

What Changed

Route the CLI's browser (loopback) OAuth flow through the hosted /connect page instead of opening Clerk's /oauth/authorize directly. The printed URL now carries the loopback callback port in the URL fragment (/connect#state=…&challenge=…&port=34338); after the page confirms a Clerk session it forwards to /oauth/authorize with the loopback redirect_uri, so the authorization code still lands on the waiting CLI at http://127.0.0.1:34338/callback. The out-of-band (headless) flow is unchanged. Added strict validation + tests for the port parameter, dropped the now-unused authorizationEndpoint from the CLI OAuth config, and updated the Connect internals doc.

Why

Fixes #5051.

npx t3 connect sent a possibly signed-out browser straight to clerk.t3.codes/oauth/authorize. Clerk then bounces through its sign-in redirect mid-flow, and that round-trip does not reliably preserve the authorize query parameters — the request comes back with only client_id and redirect_uri, so Clerk redirects to the loopback with error=unsupported_response_type and an empty state. The CLI's callback handler rejects that as Invalid T3 Connect authorization callback and times out. This is exactly why the reporter found --headless working on the same machine/account: the headless flow already signs in on app.t3.codes before touching /oauth/authorize. This PR makes the loopback flow session-first the same way, which also removes the terminal→browser URL-mangling failure class (a truncated copied URL now fails fast with the "incomplete link" page instead of a 10-minute timeout).

Related (same surface, not fixed here): #5130 — the /connect page not auto-advancing after passkey sign-in.

No Clerk dashboard changes needed: both http://127.0.0.1:34338/callback and https://app.t3.codes/connect/callback are already registered. Deploy note: the hosted web bundle must ship before/with the CLI release — an older bundle ignores the port fragment and would fall back to showing the paste-code page while the CLI waits on the loopback.

UI Changes

The /connect page shows "Browser authorization" instead of "Step 1 of 2 · Browser authorization" for loopback requests (there is no browser step 2 in that flow). No screenshots required.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

High Risk
Changes CLI OAuth authorize/redirect behavior and loopback redirect URI selection, which are authentication-critical paths. Invalid port handling or redirect mismatches could break or misroute authorization codes.

Overview
Fixes CLI OAuth failures where opening Clerk /oauth/authorize while signed out dropped PKCE/state params across Clerk's sign-in redirect (#5051).

The loopback login path now prints a hosted /connect URL (via buildConnectAuthorizeRequestUrl) that includes the callback port in the fragment. After a Clerk session exists, the hosted page forwards to /oauth/authorize with a loopback redirect_uri so the code returns to 127.0.0.1; out-of-band flows still omit the port and use /connect/callback.

CloudCliOAuthConfig drops authorizationEndpoint (CLI only hits /oauth/token directly) and exposes loopbackPort. Shared helpers validate the port, and connect UI copy distinguishes the one-step loopback flow from the two-step hosted handoff.

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

Note

Preserve CLI OAuth parameters through the hosted /connect page during browser sign-in

• Routes CLI browser auth through the hosted /connect page instead of directly to Clerk's /oauth/authorize, carrying state, code_challenge, and loopbackPort as fragment parameters.
• Adds an optional loopbackPort field to ConnectAuthorizeRequest in connectAuth.ts; when present, the Clerk authorize URL targets the CLI's local loopback callback (http://127.0.0.1:<port>/callback) instead of the hosted /connect/callback.
• Replaces authorizationEndpoint with loopbackPort in CloudCliOAuthConfig and removes buildConnectClerkAuthorizeUrl from the server-side login flow in CliTokenManager.ts.
• Adds strict numeric validation for the port fragment parameter in readConnectAuthorizeRequest; malformed values cause the function to return null.
• Behavioral Change: the CLI login flow no longer opens Clerk's authorize endpoint directly; users are sent to the hosted /connect page which then redirects to Clerk.

^{Macroscope summarized 41e519a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 37b4fa13-de7f-4185-a12d-d868f1f6230d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	11.3 KiB	−14 B (−0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+2 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−16 B (−0.3%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	11.3 KiB	−11 B (−0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	−3 B (−0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−8 B (−0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 5a84614 · PR result: 41e519a · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR modifies OAuth authentication flow logic (how CLI authorization routes through Clerk), which requires human review regardless of change simplicity. The fix alters how authorization URLs are built and how redirect URIs are determined during CLI sign-in.

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