PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection)

[IgorShevchik]

Context

PR #216 (PR-2c) landed the OAuth install/callback handshake + the B24OAuth factory + dispatcher wiring. After it merges an operator can flip NUXT_BITRIX24_OAUTH_ENABLED=true, complete /api/oauth/install → /api/oauth/callback, and receive a Bearer — but /mcp doesn't accept that Bearer yet. It still authenticates with NUXT_MCP_AUTH_TOKEN. The callback HTML page warns the user about this explicitly ("⚠ Not active yet"), but the wire-up is the load-bearing missing piece of the whole OAuth stack.

This issue tracks that final connection. Split out of #216 to keep that PR's review focused (the middleware touches defineMcpHandler, a different architectural plane).

Scope

1. MCP Bearer middleware. Extend the MCP handler (server/mcp/index.ts / wherever defineMcpHandler is registered) with a middleware hook that:

   • extracts the Authorization: Bearer <token> header,
   • hashes it (sha256-<hex>) and looks it up via findByBearerHash,
   • on hit, wraps the request in runWithTenant({ memberId, userId, requestId }, () => next()) (the requestId is a fresh 16-byte hex generated here — this is the getRequestId() consumer PR-2c: requestId — populate unconditionally + getRequestId() throwing helper #214 added),
   • on miss / revoked / orphan, returns 401 with the §11 mcp.auth.deny.* event + errorCode.

2. Flag-gated. When NUXT_BITRIX24_OAUTH_ENABLED=false, the middleware is a no-op and /mcp keeps using NUXT_MCP_AUTH_TOKEN exactly as today (webhook-only forks unchanged).

3. §11 events (already in the taxonomy, marked "deferred" — flip them to live):

   • mcp.auth.deny.bearer-unknown
   • mcp.auth.deny.bearer-revoked
   • mcp.auth.deny.bearer-orphan

4. getRequestId() becomes reachable — this is the first production caller. Add the test that proves getRequestId() returns a 32-char hex inside a real middleware-wrapped request.

Acceptance

• /mcp with a valid minted Bearer (flag on) → tenant context populated, tool call resolves through useBitrix24OAuth.
• /mcp with an unknown / revoked Bearer → 401 + the matching mcp.auth.deny.* event.
• /mcp with NUXT_BITRIX24_OAUTH_ENABLED=false → unchanged (NUXT_MCP_AUTH_TOKEN path).
• requestId populated unconditionally; getRequestId() returns it; the throw path is unreachable in production.
• Update OAUTH-DESIGN.md §11: flip the mcp.auth.deny.* block from "(deferred)" to live; update the §10 rollout table row.
• Update the callback HTML page: remove the "⚠ Not active yet" warning once the middleware is live.

Blocks

This is the gate for the OAuth flow being end-to-end usable. The full stack (#58 design, #209 scaffold, #210 token store, #213 tool swap, #216 install/callback) is functionally inert for end users until this lands.

Spawned from PR #216 round-3 review (CTO agent — flagged the missing tracking issue).

[IgorShevchik]

🎉 The last wire is soldered — /mcp now accepts OAuth Bearers!

Landed in #218 (squash-merged to main as 1541f0a). This was the load-bearing follow-up split out of #216, and with it the OAuth flow is end-to-end usable:

/api/oauth/install  →  Bitrix24 consent  →  /api/oauth/callback  →  Bearer minted  →  /mcp accepts it  ✅

Flip the switch and the multi-tenant flow is live:

NUXT_BITRIX24_OAUTH_ENABLED=true

…and webhook-only forks (flag off) see zero behaviour change — the existing NUXT_MCP_AUTH_TOKEN constant-time compare is untouched.

What actually shipped

• server/mcp/index.ts — the toolkit defineMcpHandler({ middleware }) seam (the only place that can enclose next() in an AsyncLocalStorage scope). It pulls Authorization: Bearer, sha256-hashes it, resolves the tenant, and wraps the request in runWithTenant({ memberId, userId, requestId }) so every tool downstream just knows who's calling.
• Three honest deny states via the new TokenStore.inspectBearer verb — because "401" alone is a support nightmare:
  • mcp.auth.deny.bearer-unknown — never minted (or no header)
  • mcp.auth.deny.bearer-revoked — minted, then revoked
  • mcp.auth.deny.bearer-orphan — alive Bearer, vanished parent (logged loud — CASCADE should make this impossible, but a manual SQLite edit could conjure it)
• A grep-able 401. Every rejection carries an RFC 6750 §3 header:

  WWW-Authenticate: Bearer error="invalid_token", errorCode="BEARER-REVOKED", error_description="Bearer revoked - re-authorise at /api/oauth/install"
  

  So the string a user pastes into Slack is the same string the operator greps in the JSONL audit log. No more "it just says 401" tickets. 🔍

Try it

Boot with NUXT_BITRIX24_OAUTH_ENABLED=true, complete /api/oauth/install, grab the Bearer from the callback page, then point your MCP client at /mcp with Authorization: Bearer <token> and ask it: "list my recent CRM deals" — the tool now dispatches under your portal's tenant context automatically.

Docs

• docs/OAUTH-DESIGN.md §6 (mcp-auth split), §7 (inspectBearer), §10 (rollout — PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection) #217 marked as the last wire), §11 (the mcp.auth.* taxonomy, now live instead of "deferred", plus the new mcp.auth.ok).

Closing this one out. Thanks for driving the whole rollout — s.hevchik 🙏

— closing #217 ✅

---

Generated by Claude Code