feat(auth): bearer middleware - /mcp accepts oauth bearers (closes #217)

[IgorShevchik]

Summary

The last wire of the OAuth rollout. After this lands the OAuth flow is end-to-end usable: /install → /callback → Bearer → /mcp accepts it. Operators flip NUXT_BITRIX24_OAUTH_ENABLED=true and the multi-tenant flow is live; webhook-only forks (flag off) see zero behaviour change.

Architecture

• server/middleware/mcp-auth.ts (existing h3 global middleware) — early-returns when NUXT_BITRIX24_OAUTH_ENABLED=true. Webhook-only forks keep the existing NUXT_MCP_AUTH_TOKEN constant-time compare exactly as today.
• server/mcp/index.ts (NEW) — defineMcpHandler({ middleware }) is the toolkit seam that lets us enclose next() in an AsyncLocalStorage scope (an h3 middleware can THROW or CONTINUE, but it cannot wrap). The middleware extracts Authorization: Bearer, hashes with sha256, resolves via the new TokenStore.inspectBearer verb, and on the happy path calls runWithTenant({memberId, userId, requestId}, () => next()).
• TokenStore.inspectBearer(hash) (NEW verb) — does NOT filter revoked rows. Returns { memberId, userId, revokedAt: number | null } | undefined so the middleware can distinguish the three §11 deny branches:
  • mcp.auth.deny.bearer-unknown — no row at all, or no Bearer header.
  • mcp.auth.deny.bearer-revoked — row exists, revoked_at set.
  • mcp.auth.deny.bearer-orphan — row active, oauth_tokens parent missing (CASCADE prevents this, but a manual SQLite edit could create the state; logged ERROR per §11).
• Every 401 carries a WWW-Authenticate: Bearer error="invalid_token", errorCode="…" header (RFC 6750 §3) so the user pasting the error into Slack and the operator greping the JSONL log find the same string.

Side effects

• Removed the "⚠ Not active yet" warning from bearerSuccessPage in callback.get.ts — the warning was correct in PR feat(auth): oauth install/callback handshake + b24oauth factory (PR-2c) #216 but is now stale: the Bearer IS active immediately after mint.
• docs/OAUTH-DESIGN.md §11 — flipped the mcp.auth.* taxonomy from "(deferred)" to live; added mcp.auth.ok for the happy path. §10 rollout marks PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection) #217 as the last wire.
• skills/run-manual-qa/references/issue-scaffold.md — updated the OAuth-scaffolding paragraph to reflect that /mcp now accepts the Bearer (the old text said "still pending PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection) #217").
• scripts/manual-qa-pr2c.{sh,ps1} — added a /mcp probe asserting 401 + WWW-Authenticate: BEARER-UNKNOWN.

What's in the diff

File	Change
server/mcp/index.ts (NEW, ~140 lines)	defineMcpHandler({ middleware }) — the Bearer resolver + ALS wrap
server/middleware/mcp-auth.ts	Early-return when flag on
server/utils/token-store.ts	inspectBearer verb + BearerInspection interface + prepared statement
server/api/oauth/callback.get.ts	Removed "Not active yet" warning
docs/OAUTH-DESIGN.md §10/§11	Taxonomy flipped to live, rollout table updated
skills/run-manual-qa/references/issue-scaffold.md	OAuth paragraph rewritten
scripts/manual-qa-pr2c.{sh,ps1}	/mcp Bearer-auth probe
tests/unit/mcp/auth-middleware.test.ts (NEW, 7 cases)	flag-off pass-through, 4 deny branches, happy path proves runWithTenant scope, requestId is 32-char hex, no Bearer in any log, distinct requestIds per request
tests/unit/middleware/mcp-auth.test.ts (+1 case)	Early-return on flag
tests/unit/utils/token-store.test.ts (+3 cases)	inspectBearer revokedAt semantics

663 unit tests passed (+11 vs main), typecheck + eslint + bash syntax clean.

Test plan

• npx vitest run — 663 passed.
• npx nuxt typecheck — clean.
• npx eslint . — clean.
• bash -n scripts/manual-qa-pr2c.sh — clean.
• Reviewer manual: boot with flag=true + a valid Bearer + run an MCP tool → tenant context populated, tool dispatches through useBitrix24Tenant → useBitrix24OAuth.
• Reviewer manual: boot with flag=true + an unknown Bearer → 401 + WWW-Authenticate: ... errorCode="BEARER-UNKNOWN".
• Reviewer manual: boot with flag=false → existing NUXT_MCP_AUTH_TOKEN flow unchanged.

Refs / closes

• Closes PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection) #217 (the load-bearing follow-up split out of PR feat(auth): oauth install/callback handshake + b24oauth factory (PR-2c) #216).
• ✅ Builds on PR docs(auth): add oauth 2.0 + multi-tenant design doc (draft, no code) #58 (design) + feat(auth): wire oauth scaffolding — ALS, tenant dispatcher, env (PR-2a) #209 (PR-2a) + feat(security): oauth token store — sqlite-backed CRUD + audit-first invariant (PR-2b) #210 (PR-2b) + refactor(auth): swap tool catalogue to useBitrix24Tenant + §11 observability contract (PR-2d) #213 (PR-2d) + feat(auth): oauth install/callback handshake + b24oauth factory (PR-2c) #216 (PR-2c) — all in main.
• Soft-blocker for the test:unit:oauth CI matrix: Migrate ~30 tool tests to mock useBitrix24Tenant (not useBitrix24) #215 (tool-test migration).

Changelog framing (no BREAKING CHANGE)

• Feature → Auth: /mcp now accepts OAuth Bearers minted via /api/oauth/callback when the flag is on (the wire that completes the multi-tenant flow). Webhook-only forks unchanged.
• Security: every Bearer-auth 401 carries a WWW-Authenticate header with the §11 errorCode so support tickets land with a grep-able identifier.

---

Generated by Claude Code