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).

Error mapping

Security checklist

• Code-substitution defense. Authorization codes are 32-byte random base64url; bound to the issuing client_id + redirect_uri; single-use; replay revokes the issued refresh_token.
• PKCE. S256 only. Stored challenge compared with constant-time equality (subtle.ConstantTimeCompare).
• State cookie integrity. Reuses the signed-cookie pattern that already gates DeviceCode dispatch — same HMAC, same nonce, same TTL.
• Open-redirect defense. Pre-redirect validation rejects any redirect_uri that is not a loopback URI. The 302 at the end of the IdP dance can only land on a loopback that we verified before the user ever left.
• Mix-up defense. iss parameter (RFC 9207) added to the redirect query so SDKs that check it (Claude Code's MCP SDK does) accept the response. Cheap, one extra param.
• Rate limiting. /oauth/authorize already sits behind ipRateLimit (server.go:238). Add the same wrapping around the new authorization_code branch at /device/token (already there — mux.Handle("POST /device/token", s.ipRateLimit(...))).

PR sequence

Each PR is independently testable and ships a coherent slice. Total estimate: 3 PRs, ~3 working days.

PR1 — Auth-code store + state extension

• tools/demarkus-broker/internal/broker/auth_code_store.go (new): AuthCodeStore with Begin / Bind / Redeem / janitor and tests. Mirrors device_store.go shape; uses clock injection for deterministic TTL tests.
• session.go: add AuthCodeID string to State. Update signer tests to cover the new field.
• server.go: construct s.authCodeStore alongside s.deviceStore; janitor goroutine started in the same place.
• Scope: ~350 lines + ~250 lines tests. ~1 day.

PR2 — Handlers + discovery + dispatch

• oauth_authorize.go: replace the stub with the real handler. Add authCodeCallback (or new oauth_callback.go if it cleans up). Update existing oauth_authorize_test.go: the unsupported_response_type test stays for missing/invalid response_type; everything else is new positive + negative cases.
• server.go authCallback: add the state.AuthCodeID != "" dispatch branch.
• device.go deviceToken: add authorization_code to the grant_type switch; new deviceTokenAuthCode method.
• discovery.go applyDiscoveryOverrides: extend the three lists. Update discovery_test.go assertions accordingly.
• Scope: ~550 lines + ~600 lines tests. ~1.5 days.

PR3 — End-to-end + kind harness coverage

• tools/demarkus-broker/internal/broker/oauth_authorize_test.go (new file, separate from the unit cases above): full happy-path integration test running the broker in-process against a fake Verifier, driving GET /oauth/authorize → simulated /auth/callback → POST /device/token with the correct PKCE verifier. Negative paths: bad PKCE, replayed code, mismatched redirect_uri, expired pending grant, expired code.
• deploy/kind/up.sh: add a stage that runs an in-cluster smoke driving the auth-code path against the deployed broker against mock-oauth2-server. Reuses the existing mock-oidc fixture; mock-oauth2-server supports standard authorization_code out of the box (unlike its device flow which was the PR3 risk).
• Plugin smoke: nothing to change in the Claude Code plugin code itself — the SDK drives the flow on Claude Code's side. But add a journal/2026-MM-DD.md entry capturing one manual /knowledge-join against the live broker.knowledge.demarkus.io to confirm the original error is gone.
• Scope: ~400 lines integration test + ~150 lines kind smoke + journal. ~0.5 day.

Open questions

1. Should the authorization_endpoint URL change from /oauth/authorize? No — Claude Code (and any MCP client) is already fetching the discovery doc, so the path is irrelevant to clients. Keeping /oauth/authorize means existing mcp_oauth.go / mcp_auth.go references stay intact.
2. Does Claude Code's MCP SDK respect iss (RFC 9207)? Best to ship the param defensively — it costs nothing if ignored. Verify against the SDK source before final review; if it strictly validates and we get the issuer string wrong, that's a footgun.
3. Should we rotate refresh tokens on the auth-code path? Current device-flow path does not rotate (see device.go:266-267). Keeping parity is the cheapest choice. If the MCP SDK rotates aggressively and the broker doesn't, no harm — the same refresh_token continues to work. Open to revisit if OAuth 2.1 rotation guidance shifts.
4. The device.go filename becomes misleading once it dispatches three grants. Defer rename until after shipping; the diff churn isn't worth blocking a PR on.

Out of scope

• Confidential clients / client_secret. Public clients + PKCE only.
• response_mode=form_post or fragment. Query-string redirects only — that is what RFC 8252 native apps use.
• Custom URI schemes / mobile deep links. No claudecode:// redirect_uri.
• Hybrid flow (response_type=code id_token). Not in the OAuth 2.1 catalog; no MCP client needs it.
• Refresh token rotation on this path. Inherits device-flow behavior; revisit holistically if rotation policy changes.
• UI changes to /auth/login or /device. This plan does not touch the user-facing pages. The IdP-browser dance is byte-identical.

Sequencing & Status

Plan v1, 2026-05-26. Pending Fritz review before any code is written.

After approval: PR1 → PR2 → PR3 in strict sequence (PR2 depends on the store from PR1; PR3 depends on the handlers from PR2). Each PR runs the standard bash pre-commit.sh before commit; make test for the tools/demarkus-broker/ module must be green at every step.

When resuming cold: refetch this plan, /index.md, /patterns.md, /guidelines.md. Inspect git log for already-shipped PRs against tools/demarkus-broker/internal/broker/{auth_code_store.go,oauth_authorize.go,discovery.go,device.go,session.go} and pick up at the next-unshipped PR.

Status

• PR1 shipped 2026-05-26 as PR #155 (commit 985554d). authCodeStore + State.AuthCodeID + janitor wiring landed; ~580 LOC including tests. One CodeRabbit nit addressed in the same PR (documenting consumption semantics on Redeem validation failures).
• PR2 in flight on branch broker-auth-code-handler.
• PR3 pending PR2.

Status correction (2026-05-31) — core grant SHIPPED, PR3 deliverables outstanding

The "PR2 in flight / PR3 pending" status above is stale. PR1 (#155, authCodeStore) and PR2 (#156, wire handlers + discovery) are MERGED (2026-05-27). The full RFC 6749 authorization_code + PKCE/S256 grant is implemented and unit/in-process tested:

• oauth_authorize.go — the unsupported_response_type stub is gone; real /oauth/authorize validates response_type=code, loopback-only redirect_uri (RFC 8252), required S256 code_challenge.
• authCodeCallback dispatch (server.go) → deviceTokenAuthCode token-endpoint exchange with verifyPKCE constant-time compare (device.go, auth_code_store.go).
• Discovery advertises authorization_code, response_types_supported: ["code"], code_challenge_methods_supported: ["S256"].
• 9 tests incl. end-to-end happy path + replay / bad-PKCE / mismatch / expiry negatives, all green.

Outstanding (plan's PR3):

1. A kind smoke stage that actually exercises the broker's auth-code flow — deploy/kind/up.sh currently drives only the device-flow mint path and never hits GET /oauth/authorize?response_type=code with a PKCE verifier end-to-end against a deployed broker.
2. A journal entry recording one live manual /knowledge-join against broker.knowledge.demarkus.io confirming the original unsupported_response_type error is gone.

DECISION NEEDED: complete PR3, or descope it (the grant is production-shipped and well-tested) and close. Left OPEN pending that call.

PR3 progress (2026-05-31) — kind smoke implemented + live surface verified

Closing the PR3 gap from the status correction above.

Kind smoke (deliverable 1) — IMPLEMENTED (uncommitted, pending Fritz commit). Added an auth-code + PKCE stage to the --with-mcp-smoke path in deploy/kind/up.sh, after the existing 3 MCP-gateway checks. A new authcode-smoke curl pod drives the full chain against the broker's :8080 OAuth surface:

1. GET /oauth/authorize with S256 PKCE → 302 to mock IdP (state cookie set).
2. Mock IdP (interactiveLogin=false) auto-approves → broker /auth/callback.
3. Callback (state cookie replayed, re-targeted at the in-cluster Service) → 302 to the loopback redirect_uri with a broker-minted code; asserts state echoed (CSRF) + iss present (RFC 9207).
4. Negative: POST /device/token with a wrong code_verifier → 400 invalid_grant (proves PKCE is enforced; one-shot code survives a failed verify).
5. Positive: correct verifier → 200 Bearer token (shape-only assertion; no token material in logs).
6. Replay: re-presenting the consumed code → 400 (one-shot).

PKCE verifier/challenge computed host-side via openssl (already a harness requirement) and passed into the pod — the curlimages/curl pod has no guaranteed openssl. Derivation cross-checked against a Python reference (base64url-nopad(sha256(verifier))) → exact match. server.insecureCookies=true set via --set on the local-chart install only (so the Secure state cookie replays over plain HTTP in-pod); plain Stage 2 untouched. bash -n clean; pre-commit.sh green (shell-only change, no Go touched). Not yet executed in a live kind cluster (requires image build + cluster spin-up).

Live verification (deliverable 2) — read-only probe done; interactive login still Fritz's. Probed https://broker.knowledge.demarkus.io (GET-only):

• Discovery advertises authorization_code, response_types_supported:[code], code_challenge_methods_supported:[S256], authorization_endpoint:/oauth/authorize.
• /oauth/authorize missing client_id → 400 invalid_request (real handler).
• response_type=token + loopback redirect → 302 with error=unsupported_response_type (the new two-phase redirect, not the old direct-stub).
• Valid PKCE request → 302 to accounts.google.com (full flow live; stub replaced).

This is strong evidence the original unsupported_response_type stub is gone in prod. The full interactive /knowledge-join (real Google login → token mint) remains a manual confirmation for Fritz; not automatable here.

Remaining to close the plan: commit the up.sh change; optionally run deploy/kind/up.sh --with-broker --with-mcp-smoke once to see the stage green; optionally one manual /knowledge-join. After commit, move this plan to Completed in /index.md.

PR3 kind smoke — EXECUTED GREEN in-cluster (2026-05-31)

Committed (branch broker-auth-code-kind-smoke, dc7e50e) and run live: deploy/kind/up.sh --with-broker --with-mcp-smoke against a real kind cluster. Broker image built from the committed checkout (v0.7.1-180-gdc7e50e), sideloaded, local chart installed with server.insecureCookies=true. All four auth-code assertions passed against the running broker:

• /oauth/authorize → broker authorization code (state echoed, iss present)
• wrong code_verifier → invalid_grant (PKCE enforced)
• correct verifier → 200 Bearer token minted
• consumed code replay → rejected (one-shot)

The positive mint confirms refreshStore.Issue is wired in Stage 2 (not only Stage 4) — the grant produced a real Bearer end-to-end. MCP gateway checks (RFC 9728/8414 + 401 challenge) also green. Exit 0.

PR3 deliverable 1 (kind smoke) is now implemented AND verified live. Deliverable 2 (interactive /knowledge-join) remains an optional manual step, already evidenced read-only against prod above. This plan is ready to move to Completed once the branch merges.

COMPLETE — merged to main 2026-05-31 (PR #169, a380e8f)

PR3's kind-smoke deliverable merged. Full plan status:

• Core grant (RFC 6749 authorization_code + PKCE/S256): PR1 #155 + PR2 #156 (2026-05-27).
• PR3 kind smoke: PR #169 (a380e8f) — auth-code + PKCE end-to-end stage in deploy/kind/up.sh --with-mcp-smoke; executed green in-cluster (authorize→code, negative PKCE, positive mint, one-shot replay). One CodeRabbit finding addressed in review (tightened the access_token assertion regex against an empty-value false-pass) + PR title clarified.
• Live prod surface verified read-only against broker.knowledge.demarkus.io (stub gone, full flow redirects to Google).

Only optional follow-up: a manual interactive /knowledge-join (real Google login) — not automatable, already evidenced read-only. Plan closed; moved to Completed in /index.md.

Related documents

• Universe onboarding: parent sequence this grant follows on from
• Universe onboarding PR3: device-flow shim reused by the callback path
• Universe onboarding PR4: id-token signer wiring the token exchange reuses
• Universe onboarding PR5: preceding broker onboarding slice
• Journal 2026-05-31: PR3 kind smoke run and plan closure