fix(oauth): route empty-scope initiates through consent screen (closes #28)

[stackbilt-admin]

Summary

Closes #28 — the grant-creation side of the OAuth scope cluster. Implements Option C from the issue body (consent screen with default scopes) and explicitly rejects Option A (client allowlist) in the commit message so it can't be resurrected later.

The bug

C-1a remediation (256ba06, 2026-04-10) correctly removed the hardcoded ['generate','read'] grant from completeAuthorization() calls. Before C-1a, any OAuth-authed caller silently inherited full access regardless of their token claim — the C-1 privilege escalation.

Post-C-1a, scopes come from oauthReqInfo.scope. The gap: MCP clients (Claude Code, Claude.ai) don't include scope in their OAuth initiate, so the resulting grants are empty at every level (grant.scope AND encryptedProps.scopes). Every subsequent tool call fails with (none) scopes. That's the failure mode #28, #30, and this morning's dogfood session all ran into.

The fix (Option C — consent screen with defaults)

1. New constant DEFAULT_CONSENT_SCOPES = ['read', 'generate'] with a long comment explaining why it exists and why it's not silently applied.
2. handleGetAuthorize auto-approve branch: when oauthReqInfo.scope is empty AND the identity token is valid, render the (previously unreachable) renderConsentPage with DEFAULT_CONSENT_SCOPES. User sees the scopes and explicitly clicks approve.
3. handlePostAuthorize approve branch: substitute DEFAULT_CONSENT_SCOPES when the POSTed scope is empty — matches exactly what the consent page showed. Non-empty client-requested scope is preserved verbatim.

Why this shape

• Preserves C-1a's invariant — the user explicitly consents to every scope that enters the grant. Nothing is silent.
• Preserves the zero-latency auto-approve path for clients that DO request scope (Claude Code callback timeout argument from the original auto-approve comment still holds — we only add the consent hop for the edge case of empty-scope initiates).
• Reuses dead UI infrastructure — renderConsentPage was defined but never called anywhere. This PR makes it reachable for the exact failure mode it was designed to handle.

Rejected alternatives (explicit in commit message)

• Option A — client allowlist keyed on clientId: REJECTED. clientId is attacker-controlled at OAuth client registration. Anyone can register a client with clientId: "claude-code" and inherit the allowlist's scopes. Same class as C-1, reskinned.
• Silent default injection at auto-approve: REJECTED. Loses the "user explicitly consented" property that C-1a exists to preserve. One extra hop for this edge case is the right tradeoff.

What this does NOT fix

• Legacy grants with stale encryptedProps.scopes — that's oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29's read-side fallback in gateway.ts resolveAuth. Separate PR when it lands.
• Static-bearer (ea_*) API key path — covered by PR fix(auth): accept ea_* prefix in isApiKey — unblocks static-bearer path for #28 #31 (fix/auth-ea-prefix → main, Phase 0 unblock). This PR and fix(auth): accept ea_* prefix in isApiKey — unblocks static-bearer path for #28 #31 are orthogonal and can merge in either order.

Test plan

• 5 new test cases in test/oauth-handler.test.ts under OAuth handler — #28 empty-scope consent flow:
  • Renders consent page when scope is empty (asserts completeAuthorization was NOT called)
  • Auto-approves when scope is non-empty (regression guard for the zero-latency path)
  • handlePostAuthorize injects DEFAULT_CONSENT_SCOPES when approving an empty-scope grant
  • handlePostAuthorize preserves client-requested scopes verbatim (regression guard)
  • Deny action still works for empty-scope initiates (no grant minted)
• npm run test — 125/125 green (up from 120)
• npx -y tsc --noEmit — clean
• Post-merge smoke: deploy, fresh Claude Code OAuth initiate, verify consent screen renders + tool calls succeed with ['read','generate'] scopes after approval

Related

• oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28 — this PR closes it (grant-creation side)
• oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 — legacy-grant read-side fallback, separate PR
• OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30 — Claude.ai bug, almost certainly dupe of oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28; should resolve after this ships + deploy
• PR fix(auth): accept ea_* prefix in isApiKey — unblocks static-bearer path for #28 #31 — ea_* static bearer path, Phase 0 unblock, orthogonal
• 256ba06 — C-1a remediation that created this gap