oauth: fall back to grant.scope when ctx.props.scopes is empty (fixes legacy grants)

[stackbilt-admin]

Problem

Grants created before the C-1a remediation (commit `256ba06`, 2026-04-10) have empty `scopes` inside their `encryptedProps` blob. When Claude Code's MCP client does a refresh-token exchange against one of these older grants, the new access token inherits the stale encrypted props — so `ctx.props.scopes` arrives at the gateway as `undefined` even though the grant's top-level `scope` field is correctly populated with `["generate", "read"]`.

The gateway treats this as "no scopes granted" and denies every scope-gated tool call. This silently locks out every user whose OAuth grant predates 2026-04-10.

Evidence (2026-04-11)

Dogfood session this morning:

• Kurt's admin grants: `grant:g5aL4ksbGjWkaG30tibfDrpsVgaVxE9Z:*` — authorizedAt 2026-03-24 through 2026-03-27, all have `scope: ["generate","read"]` at the top level ✓
• Kurt's personal grant: `grant:HWU9BjPldLkdBMchp2BQ8bnL8QrsXdD4:Wt9W21jbypueUS5e` — authorizedAt 2026-04-08, same shape ✓
• Every `mcp_session:*` record cached from those grants: `scopes: []` ✗

All four active sessions had to be manually patched in KV to restore the scopes and unblock MCP dogfooding. The patch has a 30-minute TTL; after that the sessions expire, `recoverSession` re-runs, `auth.scopes` re-resolves to `[]`, and we're back to square one.

Root cause

`src/gateway.ts` `resolveAuth` line 1014:

```ts
// C-1a remediation: thread through the actual scopes the OAuth token
// was issued with. Previously hardcoded to ['generate', 'read']...
scopes: oauthProps.scopes ?? [],
```

This only reads from `props.scopes` (the encrypted blob). It never falls back to the grant's top-level `scope` field, which is where the OAuth Provider library actually stores the authoritative scope list and which is always populated correctly regardless of whether the grant predates C-1a.

Proposed fix

When `oauthProps.scopes` is empty or missing but `oauthProps.userId` is set (meaning OAuth validation succeeded), look up the grant's top-level `scope` and use that. Options:

1. Via OAuth Provider API: if `env.OAUTH_PROVIDER` exposes a `lookupGrant(grantId)` (or similar), read `grant.scope` from there. Ideal, but depends on library surface.
2. Via direct KV read: thread `grantId` into `ctx.props` at `completeAuthorization` time, then read `grant::` from `OAUTH_KV` at request time. More brittle but works today.
3. Backfill migration: run a one-shot script that reads every `grant:*` KV record, decrypts `encryptedProps`, injects `scopes: grant.scope` into the props blob, re-encrypts, writes back. One-time fix for existing grants; doesn't prevent the issue for any grants created between now and the code fix.

Option 3 is the cleanest one-shot remediation for the existing population. Option 1 or 2 is the code fix that prevents this from recurring.

Why this matters

The gateway's scope model is correct; the C-1a fix was correct. The bug is that legacy grants exist that the post-C-1a code can't read scopes from, and refresh-token exchange silently inherits the stale state forever. Without a fix, every pre-2026-04-10 OAuth user is broken — and they have no visible error that tells them why, because OAuth itself succeeds and the gateway only fails at tool call time.

Related

• Partially addressed `oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28` (Option A — OAuth client allow-list defaults). That issue's fix would also unblock NEW grants; this issue is specifically about existing grants that already have stale encrypted props.
• Closes the last gap in the MCP path for the dogfood loop.

[stackbilt-admin]

Review — fallback fix closes legacy cohort only; new Claude Code grants still broken

Verified against sprint-2-hardening HEAD. The fallback-to-grant.scope fix is correct for legacy grants, but there's a distinction worth making explicit before the remediation lands:

Legacy vs new grants

• Legacy grants (pre-256ba06, 2026-04-10) were created when completeAuthorization({ scope: ['generate','read'], ... }) was hardcoded. They have grant.scope = ['generate','read'] at the top level. They have empty props.scopes because the old code never wrote that field. ✅ Fallback-to-grant.scope rescues these.

• Post-C-1a grants from empty-scope clients (Claude Code today) run through the new code at oauth-handler.ts:606-623 and :706-722, which passes oauthReqInfo.scope (empty) into both the top-level scope: arg and props.scopes:. These grants are empty top-to-bottom. ❌ Fallback-to-grant.scope does nothing — there's nothing to fall back to.

So this issue's fix cleans up the legacy cohort but does not close the ongoing bleed of new broken grants from Claude Code. That's #28's territory.

Implementation note on the fallback

Prereq: grantId needs to be threaded into props at grant creation time (oauth-handler.ts:614 and :715). That's a small additive change:

props: {
  userId: identity.userId,
  email: identity.email,
  name: identity.name,
  scopes: oauthReqInfo.scope,
  grantId: oauthReqInfo.grantId, // new — or whatever the library exposes
},

Then resolveAuth can:

let scopes = oauthProps.scopes ?? [];
if (scopes.length === 0 && oauthProps.grantId) {
  const grant = await env.OAUTH_PROVIDER.lookupGrant(oauthProps.grantId);
  if (grant?.scope?.length) {
    scopes = grant.scope;
    console.warn(`[gateway] legacy grant ${oauthProps.grantId} — falling back to grant.scope`);
  }
}

The warn log is load-bearing — it tells you how many legacy grants are still out there and when the fallback can be retired.

Backfill sequencing

Deploy the read-side fallback (Option 1/2) BEFORE running the backfill (Option 3). Otherwise a partial backfill run leaves some grants on the new encrypted-blob format and some on the old, and any in-flight sessions that mix them will 500. With the fallback in place, the backfill becomes a nice-to-have rather than load-bearing.

Also worth checking: the backfill needs to handle mcp_session:* cached records too, not just grant:*. The cached sessions have their own copy of the encrypted props and will re-run resolveAuth → auth.scopes = [] after the 30-min TTL expires, exactly as this issue describes.

Relationship to #28

This issue and #28 are different fixes in different files but share the same symptom. Both need to ship for Claude Code dogfooding to work end-to-end:

• This issue: gateway.ts resolveAuth fallback + one-shot backfill → rescues legacy grants
• oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28: oauth-handler.ts consent-screen path for empty-scope initiates → prevents new broken grants

Either alone leaves half the population broken.

Test to add

L1 unit test for resolveAuth with a mocked grant where props.scopes = [] but grant.scope = ['read', 'generate'] → returns ['read', 'generate'] and emits the warn log. Regression guard.

[stackbilt-admin]

Sequencing follow-up — this fallback becomes dead code for new grants once #28 ships

One more framing note after looking at #28 and #30 alongside this issue:

The resolveAuth fallback proposed here is the right fix for the legacy cohort, but it has a natural end-of-life. Once #28's grant-creation fix lands (route empty-scope initiates through consent screen with a default ['read']), every NEW grant has non-empty scope at creation, so this fallback only services grants created before 2026-04-10.

That shapes the rollout:

1. Ship oauth: Claude Code MCP client gets zero scopes — scaffold_create unreachable from the assistant #28 first to stop the bleed of new broken grants from Claude Code / Claude.ai clients.
2. Ship this issue's fallback second so legacy-grant users stop getting silently locked out and operators stop having to patch KV sessions manually.
3. Run the backfill third — with the fallback live, the backfill is a nice-to-have (migrates stale encrypted blobs to match grant.scope) rather than a load-bearing fix. If the backfill hits snags, the fallback holds the line.
4. Retire the fallback after a week of warn-log silence from [gateway] legacy grant ... — falling back to grant.scope. That's the signal that every remaining legacy grant has either expired or been rotated.

The ordering is load-bearing. If this issue ships before #28, it fixes the legacy population but Claude Code continues creating new broken grants forever. If the backfill runs before the fallback is deployed, mixed encrypted-blob versions on in-flight sessions can 500. If the backfill runs without this fallback AND without #28, you're back to manual KV patches every 30 minutes.

Test to add alongside the fix

L1 unit test for resolveAuth that encodes the fallback invariant:

it('falls back to grant.scope when props.scopes is empty (legacy grant)', async () => {
  const mockGrant = { scope: ['read', 'generate'] };
  mockEnv.OAUTH_PROVIDER.lookupGrant.mockResolvedValue(mockGrant);

  const result = await resolveAuth(request, mockEnv, {
    userId: 'u1',
    grantId: 'g1',
    scopes: [], // stale encrypted props
  });

  expect(result.authenticated).toBe(true);
  expect(result.scopes).toEqual(['read', 'generate']);
  expect(console.warn).toHaveBeenCalledWith(
    expect.stringContaining('legacy grant g1'),
  );
});

Plus a negative case: lookupGrant returns null or scope: [] → resolveAuth returns empty scopes (doesn't invent scopes out of thin air).