MCP OAuth Stage 3: /oauth/mcp/authorize endpoint (PKCE-S256)

[heskew]

Drafted by Claude (Opus 4.7, 1M context) on Nathan's behalf, following the harper-engineering-guidelines development lifecycle. Code, tests, the pre-push Gemini cross-review, and this description are all agent-authored; pushed under Nathan's account because the agent runs locally on his machine. Human review expected before merge.

Closes #93. Sub-issue of #86.

Summary

Stage 3 of MCP OAuth. Adds the user-facing authorize endpoint plus the surrounding plumbing — auth-code table with native TTL, bridge through the existing upstream IdP flow, callback branch that mints the code and redirects to the MCP client. No JWTs yet (that's Stage 4 / #94).

Where to look

• src/lib/mcp/authorize.ts — handleAuthorize with two-phase validation per OAuth 2.1 §3.1.2.5: client_id + redirect_uri must validate before any redirect; everything else routes errors to the verified redirect_uri. The interesting helper is redirectUriMatches — implements RFC 8252 §7.3 loopback port flexibility for 127.0.0.1 / [::1] / localhost. Native MCP clients bind dynamic ports at runtime and can't pre-register them.
• src/lib/handlers.ts — handleCallback restructured. CSRF state is now verified BEFORE the upstream error param is processed, so MCP-initiated errors (user denied at GitHub, etc.) route back to the MCP client's redirect_uri with OAuth-spec error codes instead of bouncing to the Harper app's default path. The legacy "no state, has error" UX is preserved for human-OAuth flows. On the success path, the onLogin-mapped username (hookData?.user ?? user.username) flows into the auth-code record, so Stage 4's JWT inherits the mapped identity.
• src/lib/mcp/callback.ts — the MCP branch from handleCallback. Mints the code with crypto.randomBytes(32).toString('base64url'), persists the binding fields (client_id, user, resource, PKCE challenge, redirect_uri, scope), redirects to the client URI. No Harper session is created on this branch (independent MCP/human lifecycle per Add MCP OAuth flow support #86 resolved decision). Asserts no upstream IdP token leaks into the redirect URL.
• src/lib/mcp/authCodeStore.ts — CRUD against the new mcp_auth_codes table. Explicit field access in encode/decode (CLAUDE.md tracked-object spread gotcha).
• schema/oauth.graphql — new mcp_auth_codes table with @table(database: "oauth", expiration: 300) for native TTL.
• src/types.ts — MCPAuthorizeState (carried through CSRF metadata) and MCPAuthCodeRecord. New mcp.providers config field.

Design decisions worth flagging

• Single-provider constraint for v1. mcp.providers (or, when unset, the full registry) must resolve to exactly one effective provider; 0 or >1 returns server_error. Multi-provider chooser UI is v1.1. Documented in the selectMCPProvider helper.
• resource param exact match. Validated against resolveResource(request, mcpConfig) from Stage 2 (same Host-header caveat applies — pin mcp.resource in production).
• Auth code storage. Single Harper table with expiration: 300 — 5-minute TTL is a safety net; Stage 4's /token will read-then-delete on exchange for one-time use.

What was reviewed

Gemini CLI 0.42.0 cross-reviewed the pre-push diff. Four real findings, all addressed before push:

1. RFC 8252 §7.3 loopback port flexibility — original code did exact-string match on redirect_uri, breaking native clients. Now uses port-flexible matching on loopback hosts. Tests added covering all loopback variants.
2. onLogin username mapping lost in MCP branch — auth code was binding the raw OAuth username, ignoring the mapped identity from the hook. Now passes hookData?.user ?? user.username through.
3. handleCallback error ordering — upstream IdP error was handled before CSRF verification, so MCP errors bounced to the Harper default path instead of the MCP client. CSRF verify is now first; legacy no-state UX preserved.
4. MCP-unaware error redirects — the cross-provider mismatch and catch blocks ignored tokenData.mcp and used originalUrl || postLoginRedirect (undefined for MCP flows). Both branches now route to the MCP client redirect_uri when mcpState is present.

One Gemini point (resource URI stability via Host header) was informational — already covered by Stage 2's documentation.

Test plan

• 603 unit tests pass locally (npm test); +51 from this PR
• npm run lint clean
• npm run format:check clean
• No regression in the human-OAuth callback path — existing handleCallback tests cover the legacy behavior including the "no state, has error" preservation
• End-to-end verification deferred to Stage 7 (MCP OAuth Stage 7: end-to-end integration fixture #97) — mcp-remote driving the full discovery → DCR → authorize → token → bearer call is the conformance proof

Out of scope

• /oauth/mcp/token exchange (Stage 4, MCP OAuth Stage 4: /oauth/mcp/token endpoint + JWT issuer #94) — codes from this PR are unused until that lands
• JWT signing keys + JWKS population (Stage 4)
• withMCPAuth wrapper that consumes Stage 4 tokens (Stage 5, MCP OAuth Stage 5: withMCPAuth wrapper #95)
• Audit hooks (Stage 6, MCP OAuth Stage 6: audit logging + onMCPTokenIssued hook #96)
• Multi-provider chooser UI (v1.1)

🤖 Generated with Claude Code

[github-actions]

Reviewed; no blockers found.

The PR successfully implements the MCP Authorization Server flow (Stage 2 of issue #86), including the core /oauth/mcp/authorize endpoint with proper Phase 1/Phase 2 validation separation and RFC 8252 loopback port flexibility. The implementation respects Harper's Resource API v2 and maintains strict security boundaries between MCP and human-session lifecycles.

Surfaces verified:

• Authorization Flow: Traced /oauth/mcp/authorize from OAuthResource dispatch to handleAuthorize. Confirmed that Phase 1 (client/redirect-URI) fails with 400 JSON while Phase 2 (protocol/PKCE/resource) correctly redirects back to the client with error parameters.
• Callback Handling: Verified the branching in handleCallback to handleMCPCallback. Confirmed that the onLogin hook is preserved and that the issued auth code is bound to the correctly mapped Harper identity.
• Security Invariants: Validated RFC 8707 resource binding, PKCE S256 requirement, and the 2048-character path limit. Confirmed that cross-provider CSRF protection is correctly routed back to the MCP client.
• Storage Safety: Verified that MCPAuthCodeStore and MCPClientStore use explicit field copying to avoid the GenericTrackedObject spread gotcha.
• Testing: The new test suites are thorough, especially in simulating Harper's Proxy-based tracked objects and verifying RFC-specific edge cases like loopback port selection.

[claude]

Reviewed; no blockers found.

[heskew]

No blockers.

---

🤖 Posted by Antigravity on Nathan's behalf