oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant

[stackbilt-admin]

Problem

The Claude Code MCP client connects to `mcp.stackbilt.dev/mcp` via OAuth successfully. The session is authenticated and appears healthy. But every `generate`-gated tool call fails with:

```
MCP error -32600: Tool "scaffold_create" requires one of these scopes: generate. Your token has: (none).
```

Same error for `scaffold_classify` and `scaffold_status` (`read` or `generate`).

Root cause

`src/oauth-handler.ts` line 609-622 (and again at line 709-721) threads `oauthReqInfo.scope` directly into `props.scopes`:

```ts
// C-1a remediation: thread the actual OAuth scope grant through
// to the gateway's apiHandler so resolveAuth can enforce it at
// call time (instead of hardcoding ['generate','read']).
scopes: oauthReqInfo.scope,
```

Claude Code's MCP client doesn't include `scope` in its OAuth initiate, so `oauthReqInfo.scope` is empty, `props.scopes` is empty, and every scope-gated tool is unreachable.

The C-1a remediation correctly removed the hardcoded scope grant as a security fix — but it has the unintended consequence of locking out the assistant that is supposed to drive the engine for dogfooding.

Impact

This makes the scaffold engine effectively unreachable from inside Claude Code — which is exactly the environment where we want to build, iterate, and test the engine. Every run requires shelling out to the tarotscript repo locally, defeating the point of having the MCP in the first place.

Proposed fix (pick one or combine)

Option A — Client allow-list default scopes

Add a hardcoded allow-list for known trusted clients:

```ts
const DEFAULT_SCOPES_BY_CLIENT: Record<string, string[]> = {
'claude-code': ['read', 'generate'],
'claude-desktop': ['read', 'generate'],
// etc.
};

const scopes = oauthReqInfo.scope.length > 0
? oauthReqInfo.scope
: (DEFAULT_SCOPES_BY_CLIENT[oauthReqInfo.clientId] ?? []);
```

Pros: no security regression for unknown clients; dogfooding works.
Cons: hardcoded list needs maintenance; `clientId` is client-controlled.

Option B — Static-bearer bypass via API key

Accept `ea_`-prefixed keys from edge-auth in `auth.ts` `isApiKey()` (currently only matches `sb_live_`/`sb_test_*`), mint a generate-scoped key via edge-auth, and configure it as a static bearer in `.mcp.json`. Bypasses OAuth entirely.

Pros: explicit, auditable, scoped to our control; no security regression.
Cons: requires `isApiKey()` patch AND a matching edge-auth issue for minting. Requires us to not lose the key.

Option C — Opt-in via wider consent screen

On the OAuth initiate, if no scope is requested, default to showing the consent screen with `['read', 'generate']` pre-checked. User approves explicitly.

Pros: user is in the loop; no hardcoded grants.
Cons: Claude Code's MCP flow may not route through the consent screen if it's auto-approved elsewhere.

Recommendation

Start with Option B (static bearer) for immediate unblock. File a companion issue in edge-auth to mint the key. Follow up with Option A (client allow-list) for a cleaner long-term OAuth path.

Repro

```

Any scaffold_create call via the stackbilt MCP

mcp__stackbilt__scaffold_create(intention="test", project_type="api")

→ MCP error -32600: Tool "scaffold_create" requires one of these scopes: generate. Your token has: (none).

```

Related

• `src/auth.ts` lines 7-9 (`isApiKey` prefix check — edge-auth mismatch)
• `src/oauth-handler.ts` lines 602-623, 702-722 (C-1a remediation)
• Feedback context: `aegis-daemon/artifacts/callsentinel-scaffold-feedback.md` (issue [auto] Add seed-determinism test for scaffold materializer #8)

[stackbilt-admin]

Review — recommend Option C, reject Option A

Read through against sprint-2-hardening HEAD. Confirming the root cause: oauth-handler.ts passes oauthReqInfo.scope into both scope: and props.scopes: on completeAuthorization() at two call sites (lines 606-623 auto-approve branch, 706-722 manual consent branch). When the client sends an empty-scope initiate, the grant ends up empty at every level — top-level scope AND encryptedProps.scopes. Nothing to fall back to.

Option A — reject (security)

clientId is attacker-controlled at the OAuth initiate. An attacker registers a client with clientId: "claude-code" and inherits the allowlist's scope grant. This is the same class of bug as C-1, just reskinned. Unless the allowlist is keyed on a verified client identity (client secret, not clientId), Option A reintroduces exactly what C-1a closed. Hard no.

Option B — ship as immediate unblock

auth.ts:13 already accepts ea_ prefix (commit b63ac84). Path is unblocked, but:

• validateBearerToken passes scopes: result.scopes ?? [] at auth.ts:53. If edge-auth mints the key with empty scopes, you hit the same (none) wall via the API key path instead of OAuth. Confirm the minted key has explicit ["read", "generate"] scopes before dropping it in .mcp.json.
• Blocker: only works if sprint-2-hardening is deployed. If main is still pre-b63ac84, cherry-pick first.

Option C — the real fix

Route empty-scope initiates through the consent screen with default scopes pre-populated. Preserves the explicit-consent property and doesn't add any hardcoded client trust.

Implementation: in the auto-approve branch at lines 602-625, add an early return before completeAuthorization is called:

if (!oauthReqInfo.scope?.length) {
  // Force consent hop even when identity token is valid — we need the
  // user to explicitly grant scope the client forgot to request.
  return consentResponse(oauthParams, identity, { defaultScopes: ['read'] });
}

'generate' should require the client to request it explicitly, or the consent screen to have it unchecked by default. 'read' is the minimum safe default.

Edge case worth testing: what happens if the identity token's redirectUri points at a client that can't render the consent screen (e.g., a CLI that expects auto-redirect)? Those clients should be fixed upstream to send explicit scope, not special-cased here.

Recommended order

1. Today — mint ea_* key with explicit scopes, use as static bearer (Option B). Immediate unblock.
2. This week — land Option C as the code fix. Closes this issue and probably OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30 (pending trace).
3. Test: add an L4 case for OAuth initiate with empty scope → asserts consent-screen redirect (not completeAuthorization call, not silent empty grant).

The fact that C-1a shipped without a test for "what happens when the client doesn't request scope" is the meta-gap worth closing too — it would have caught this plus #29 plus probably #30 in CI.

Related

• oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 covers the legacy-grant side (different bug, different fix, same symptom)
• OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30 is likely a manifestation of this + oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 from Claude.ai; confirm via trace before closing as dupe

[stackbilt-admin]

Cross-scale verdict — the three issues (#28, #29, #30) collapse into one invariant fix

After looking at all three together, the lever that unlocks all of them is the same:

Fix the grant CREATION invariant, not the grant READ path. Require non-empty scope at completeAuthorization() call time. Once every new grant has non-empty scope, #29's read-side fallback becomes dead code for new grants (it only serves the shrinking legacy cohort), and the backfill run + a week of warn-log silence lets you retire the fallback entirely.

Recommended execution order

1. Unblock first — confirm sprint-2-hardening deploy status. The fastest workaround (ea_* static bearer, Option B) depends entirely on b63ac84 being live in prod. If it's not, either deploy the branch or cherry-pick b63ac84 to main. Nothing else moves until this is answered.

2. Run the OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30 trace — 15 min to capture oauthReqInfo.scope for a fresh Claude.ai session at oauth-handler.ts:606. Three outcomes: dupe of oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28 → close; dupe of oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 → close; third bug → keep open with evidence. Don't close OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30 as dupe before the trace confirms.

3. Ship this issue (oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28) as Option C — single-file change in oauth-handler.ts routing empty-scope initiates through the consent screen with a ['read'] default. Closes this issue, almost certainly closes OAuth token minted for Claude.ai sessions has empty scope set — blocks all Stackbilt MCP tool calls #30.

4. Then oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants) #29 — deploy the resolveAuth fallback first, run the one-shot backfill second. After a week of warn-log silence, retire the fallback.

Meta follow-up — missing test pattern (worth a separate tracking item)

The root cause of all three bugs is that C-1a shipped without an L4 test for "what does the new code do with empty/zero inputs?" A single fixture that runs every scope-gated path against scope = [] would have caught all three before dogfooding.

This is a generalizable pattern: security fixes that remove hardcoded values need a matching empty-input test — otherwise the new code silently fails the happy path for any caller that didn't previously need to care about the removed-hardcoded behavior.

Worth adding test/empty-scope-inputs.test.ts (or equivalent) as a dedicated L4 fixture. Every new scope-gated path goes into it as a default-deny case. Happy to break this out as a separate issue if that's useful — tell me if you want it filed.

Option A reject — restating for the PR description

When the fix PR goes up, the description should explicitly reject Option A (client allowlist keyed on clientId) and explain why. clientId is attacker-controlled at OAuth client registration — anyone can register a client with clientId: "claude-code" and inherit the allowlist's hardcoded scopes. That's the same class of bug as C-1, just reskinned. Writing the rejection into the PR description keeps a future engineer from resurrecting it.

[stackbilt-admin]

Correction + Phase 0 unblock in flight

Correcting my earlier comment: I was reading b63ac84 from a local checkout and assumed it was on the sprint-2-hardening remote branch. It wasn't — the commit was local-only. So the prior "Phase 0 is unlocked code-wise" framing was incorrect. ea_* tokens would have fallen through to validateJwt and failed on prod.

Now fixed by PR #31 (fix/auth-ea-prefix → main) which cherry-picks that same patch onto main as a standalone one-commit PR, orthogonal to PR #27 (sprint-2 hardening). Test plan: 120/120 tests green, tsc clean, surgical 9-line change to isApiKey() in src/auth.ts.

Once PR #31 merges and main gets a fresh wrangler deploy, the ea_* static-bearer path is fully open. At that point:

1. Mint an ea_* key from edge-auth with explicit ['read', 'generate'] scopes
2. Drop it in .mcp.json as the static bearer
3. Skip the OAuth flow entirely

Reproducible bug evidence from a fresh Claude Code session while drafting this PR:

MCP error -32600: Tool "image_list_models" requires one of these scopes: read, generate. Your token has: (none).

That error is only reachable if 256ba06 (C-1a) is already deployed — hardcoded pre-C-1a code would have succeeded. So main is currently live at the C-1a state and the gap is exactly what #28 describes. Deploying PR #31 on top takes no extra risk.

The OAuth grant-creation fix (Option C from the earlier comment, the real fix for this issue) still needs to ship separately. This PR is Phase 0 unblock only.

[stackbilt-admin]

Real fix landed as PR #32 — fix/oauth-empty-scope-consent → main. Implements Option C (consent screen with ['read','generate'] defaults), 5 new tests, 125/125 green, tsc clean. Explicitly rejects Option A in the commit message. Orthogonal to #31 (Phase 0 unblock), either can merge first.