Plan: Broker Authorization Code Grant

Why

The broker today advertises device_code + refresh_token only and ships a stub /oauth/authorize that returns unsupported_response_type (see tools/demarkus-broker/internal/broker/oauth_authorize.go:39). The stub was a probe: if Claude Code's MCP SDK pivoted to device flow on its own, we were done. Observation as of 2026-05-26: it does not — it opens the browser at the advertised authorization_endpoint, gets the JSON 400, and surfaces it as an opaque error to the user. The path forward called out in oauth_authorize.go:23-28 is the one we now take: implement a real authorization-code grant inside the broker, mediating between the MCP client and the upstream IdP, while continuing to keep IdP details invisible to the MCP client.

This is a follow-on to the universe-onboarding sequence (PR3/PR4/PR5 + DCR PR #153). Same layering, same constraints: no protocol or server changes; all work in tools/demarkus-broker/. The MCP client only ever sees the broker as its OAuth AS; the IdP only ever sees the broker as its OAuth client.

Goal

After this plan ships, the following sequence works end-to-end with stock Claude Code:

1. User adds the broker as an MCP server (via /knowledge-join or claude mcp add).
2. Claude Code's MCP SDK fetches the broker's discovery doc, sees authorization_code in grant_types_supported, and starts an auth-code flow.
3. SDK hits /oauth/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256&redirect_uri=http://localhost:PORT/callback&state=...&scope=....
4. Broker redirects through /auth/login → IdP → /auth/callback, exactly as the device-flow shim does today.
5. Broker mints an authorization code, redirects to http://localhost:PORT/callback?code=...&state=....
6. SDK POSTs to the token endpoint with grant_type=authorization_code + code + code_verifier. Broker validates PKCE, issues access_token + id_token + refresh_token (broker-signed for both).
7. SDK uses the access_token as a bearer on all subsequent MCP gateway calls. Refresh via the existing refresh_token grant.

The device-flow surface (/device/*) stays — it is the right shape for tools/demarkus-join and for any non-browser agent. Auth-code is added alongside, not in place of.

Non-Negotiables

• PKCE required. code_challenge_method=S256 only. No plain. No bare auth-code flow without PKCE. OAuth 2.1 + the MCP authorization spec both require this; we have no legacy client to coddle.
• redirect_uri MUST be loopback per RFC 8252. Accept http://127.0.0.1:PORT/... and http://localhost:PORT/... with any port. Reject everything else — no public redirect URIs, no urn:ietf:wg:oauth:2.0:oob, no custom URI schemes (those belong to native mobile clients which are not in scope). The DCR endpoint already rubber-stamps any client; the redirect_uri restriction is the only meaningful constraint on where the code lands.
• No client authentication at /token for auth-code. Public clients per OAuth 2.1; PKCE is the binding. Matches the device-flow surface which is also unauthenticated by client_id.
• One-shot codes. Each authorization code is single-use; second use revokes the refresh token issued from it (defense-in-depth per OAuth 2.1 §4.1.3).
• No silent IdP details leaking. The broker is still the only OAuth AS the MCP client sees. IdP-specific scopes, claims, redirect rules all stay internal to the broker.
• No core changes. Same precedent as the universe-onboarding work: every change lives under tools/demarkus-broker/.

Architecture

The auth-code flow reuses 80% of the device-flow machinery already in device.go/oidc.go/server.go. The differences are:

Store shape

New file auth_code_store.go. Two indices, both in-memory with a janitor goroutine like deviceStore:

• pending (keyed by internal opaque id): the in-flight grant before the user authenticates. Holds client_id, redirect_uri, state (client-supplied), scope, code_challenge, code_challenge_method, expires_at. Created by Begin() at /oauth/authorize. Resolved into code-keyed entry by Bind() after /auth/callback completes the IdP exchange.
• codes (keyed by issued authorization code): the bindable result the SDK redeems at /token. Holds the resolved ExchangeResult, the PKCE challenge it must satisfy, the issuing client_id + redirect_uri (re-checked at /token per RFC 6749 §4.1.3), and a single-use sentinel.

Both have short TTLs: pending = ~10 min (the user might take a while to sign in), codes = 60 seconds (RFC 6749 §4.1.2 says ≤10 min; OAuth 2.1 BCP says ≤1 min — we follow the tighter bound).

State extension

session.go's State struct currently holds Nonce, ExpiresAt, DeviceCode. We add AuthCodeID. Signed-cookie roundtrip is unchanged; existing tests cover the round-trip — we extend with cases that exercise AuthCodeID.

Handlers

• oauth_authorize.go — gutted of the stub, replaced with the real handler:

  • Parse response_type (must be code), client_id, redirect_uri, state, scope, code_challenge, code_challenge_method.
  • Validate redirect_uri is loopback per RFC 8252 (allow 127.0.0.1 and localhost with any port and any path).
  • Validate code_challenge_method=S256 and code_challenge is present.
  • For any error that happens BEFORE we trust the redirect_uri: return JSON 400 with the OAuth error code (same shape as today's stub).
  • For any error that happens AFTER redirect_uri is validated: redirect to redirect_uri?error=...&state=... per RFC 6749 §4.1.2.1.
  • On success: authCodeStore.Begin(...), build a signed State{Nonce, AuthCodeID, ExpiresAt} cookie, set it on /auth/callback, 302 to verifier.AuthCodeURL(nonce).

• server.go authCallback — add a parallel branch alongside the existing DeviceCode dispatch:

  if state.AuthCodeID != "" {
      s.authCodeCallback(w, r, state.AuthCodeID)
      return
  }
  

  The new authCodeCallback (in oauth_authorize.go or a new oauth_callback.go) runs verifier.Exchange, calls authCodeStore.Bind(authCodeID, exchange) which issues a fresh authorization code, then 302s to pending.redirect_uri?code=<authCode>&state=<pending.state>.

• device.go deviceToken — extend the grant_type switch to dispatch authorization_code to a new deviceTokenAuthCode handler. (The file name is misleading now — could rename to token.go later but that is post-shipping cleanup.) The handler:

  • Reads code, redirect_uri, client_id, code_verifier.
  • authCodeStore.Redeem(code) — single-use; returns the stored exchange + PKCE challenge + issuing client_id/redirect_uri.
  • Re-checks client_id and redirect_uri match what was bound (RFC 6749 §4.1.3).
  • SHA-256(code_verifier) base64url-no-pad → compare to stored code_challenge. Mismatch → invalid_grant.
  • Mint refresh_token via refreshStore (same path as device-flow today).
  • Mint a broker-signed id_token via idTokenSigner (same path as device-flow refresh today; PR4 wiring).
  • Return access_token = id_token (same convention the refresh path uses, per device.go:269-273).

• discovery.go applyDiscoveryOverrides:

  • Add "authorization_code" to grant_types_supported.
  • Add response_types_supported: ["code"] (currently absent; required for MCP clients to confirm).
  • Add code_challenge_methods_supported: ["S256"].
  • Leave authorization_endpoint pointing at /oauth/authorize (unchanged URL, real handler now).
  • Leave token_endpoint pointing at /device/token (unchanged; same endpoint dispatches all three grants by grant_type).