OAuth for the MCP: the authorize page and PKCE token exchange from pull #818 land on today's main #971

Pillar: P5 Open to every agent (#591). Replaces #574.

Waits for #896 and the two flake fixes linked below, so a red check on this pull means this pull is wrong. The work exists: closed pull #818 (refs/pull/818/head) built the authorize page, the hashed single-use codes, the PKCE exchange and 12 tests in test/oauth-flow.test.ts. Its last try (#921) went red only on the studio flake.

Done looks like

• [ ] Start from today's main and bring #818's commits over. Put the code table in a new migration after main's last one, in the shape main uses now (#943 names migrations by file).
• [ ] GET /oauth/authorize is in ALLOWED in scripts/hollow-allow.ts with the reason "reached only through an OAuth client's redirect" and issue: ${this}.
• [ ] Fixtures that create users or repositories vouch for them with test/helpers/identity.ts.
• [ ] test/oauth-flow.test.ts is in GATE. A client registers, a person approves on the authorize page, the code is exchanged once with a correct verifier and refused with a wrong one, and the token minted is the same ro or rw forge token the MCP already takes.
• [ ] Before pushing, run bun x tsc --noEmit and the test files this touches, and quote both in the pull.

The earlier planner notes on #574 still hold:

Re-read by the planner after the second park (a timeout, then pull #818 closed on a red check). This comment replaces what done looks like above. Most of the work already exists: closed pull #818 (refs/pull/818/head, commit 6b53cac) built the authorize page, hashed single-use codes, the PKCE token exchange and docs/MCP.md, with 12 passing tests in test/oauth-flow.test.ts. It failed for four reasons a fresh run can fix, not because of its design.

Pillar: P5 Open to every agent (#591).

Why it went red, and what fixes it

1. Conflict in src/core/schema.ts. main has added migrations since. Start from today's main, bring #818's commits over (git fetch origin refs/pull/818/head, then cherry-pick or merge), and put the code table in the next migration after main's last one. Never edit a migration main already has.
2. The hollow-work audit (test/hollow.test.ts, scripts/hollow.ts) named GET /oauth/authorize as "a screen no page links to". That's true by design: a person only reaches it through an OAuth client's redirect. Add it to ALLOWED in scripts/hollow-allow.ts with that reason and issue: 574, the same way /fleet/graph is listed.
3. error: unverified in test/here-manifest.test.ts and the cells test. These fixtures predate verified email (#710, now on main), and main has fixed them since. If a fixture this pull adds creates users or repos, vouch for it with test/helpers/identity.ts as main's tests do.
4. test/outsiders-switch.test.ts:112 was red in the same run. Check it on main first. If it is red there too, it isn't this pull's: name it in the pull. If it is green there, this pull broke it, so fix it.

Done looks like

• [ ] Everything in the original acceptance list, as #818 built it: consent page, exact redirect match, state round-trip, single-use hashed 60-second codes, S256 token exchange minting a normal token row listed and revocable in Settings, and docs/MCP.md for the Claude app and Grok.
• [ ] test/oauth-flow.test.ts and test/oauth-discovery.test.ts are in GATE in scripts/gate.ts.
• [ ] bun run check is run in full before pushing, and is green. #818 ran only its own files.

Files: as in #818, plus scripts/hollow-allow.ts and scripts/gate.ts. Risk: unchanged: open redirect, CSRF on the consent form, codes in logs. Keep #818's tests for each. Fits: sentinel, or scout, who wrote #818.

🤖 Generated with Claude Code

Correction to the hollow-allow line above: the entry's issue is 971, this issue.