MCP OAuth Stage 5: withMCPAuth bearer-token guard (#95)

[heskew]

Stage 5 of the MCP OAuth epic (#86). A plugin-provided guard for app-owned MCP routes: it validates the bearer access token and returns the spec-mandated 401 + WWW-Authenticate: Bearer resource_metadata="..." so apps don't reimplement the (security-sensitive) RFC 9728 discovery contract. Bearer-token counterpart to withOAuthValidation.

Closes #95.

What it does

withMCPAuth(handler, options?) wraps an app MCP handler so every request must present a valid RS256 access token (minted by Stage 4's issuer) before the handler runs:

• Verifies the Authorization: Bearer token: RS256 signature against the published JWKS (key selected by kid), exp/nbf, and aud bound to mcp.resource (RFC 8707).
• On any failure returns 401 with WWW-Authenticate: Bearer resource_metadata="<issuer>/.well-known/oauth-protected-resource" (RFC 9728).
• On success attaches request.mcp = { sub, client_id, aud, scope } and invokes the handler, returning its response verbatim.
• Fails closed (MCP disabled / no token / no keys / malformed / bad claims). Header-only token extraction per RFC 6750 — query-string tokens are ignored.

Registration — the load-bearing detail (and a correction to the #95 example)

Harper core auth is a default-group middleware that consumes Authorization: Bearer and 401s any non-Harper token with WWW-Authenticate: Basic, which breaks MCP discovery. The wrapper supports both registration models so it always owns its route's response; docs lead with the first:

• urlPath subroute (recommended): server.http(withMCPAuth(handler), { urlPath: '/mcp' }). In harper 5.1.x, routed dispatch (server/middlewareChain.ts buildRoutedChain) runs only the matched subroute's chain — core auth (default group) never runs for it, the same isolation /.well-known/* relies on. No runFirst needed.
• Default-group fallback: server.http(withMCPAuth(handler, { path: '/mcp' }), { before: 'authentication' }). When the route shares the default chain with auth, path scopes the guard (other paths fall through) and before: 'authentication' runs it ahead of core auth — the static.ts precedent.

Note: the issue #95 example server.http('/mcp', withMCPAuth(h)) is incorrect for this Harper version — server.http is (listener, options) and needs the urlPath/ordering hint above. The plan's original runFirst: true framing was modeled on an older middleware chain; runFirst is not the mechanism here.

Changes

• NEW src/lib/mcp/withMCPAuth.ts — the guard.
• src/lib/mcp/tokenIssuer.ts — verifyAccessTokenWithKeySet (kid selection: unknown kid throws, no kid uses the sole key; RS256-pinned to block alg confusion; aud+iss enforced).
• src/lib/mcp/wellKnown.ts — export PRM_PATH (challenge URL stays in sync by construction).
• src/types.ts — MCPRequestClaims + Request.mcp.
• Exports wired in src/lib/mcp/index.ts and the top-level src/index.ts.
• Unit tests (withMCPAuth.test.js + verifyAccessTokenWithKeySet cases) and an integration test + fixture (mcp-auth.test.ts / mcp-auth-app) asserting the Bearer challenge survives core auth for both registration models (runs on CI — needs loopback aliases).
• README + docs/configuration.md.

Testing

• Unit: 686 pass, 0 fail. Build + lint + format clean.
• Integration: added; runs on CI (loopback aliases aren't configured locally).

Cross-model review (pre-PR, HEG step 10)

Codex + Harper-domain reviewer (Gemini/agy leg skipped — exfiltration-blocked for this repo; CI's gemini bot covers it). No blockers. One fix applied before this PR: onAuthError's fallback used ??, but the documented contract promises any falsy return fails closed — changed to || and added a falsy-return regression test. No-action notes: the deny-path resource_metadata URL derives from the Host header when mcp.issuer is unset (already documented as "pin mcp.issuer in production"; the fixture pins it); the undefined-pathname default-group fall-through is benign.

🤖 Generated with Claude Code

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[github-actions]

Reviewed; no blockers found.

Suggestions (non-blocking)

• src/lib/mcp/withMCPAuth.ts:251 — consider extracting the deny response construction to a helper if more rejection branches are added in the future, though it's currently clean enough as a local closure.
• src/lib/mcp/withMCPAuth.ts:167 — verify if request.pathname is always segment-normalized in Harper v5 (e.g., whether /mcp/ and /mcp both reach this point). The pathOwned helper handles trailing slashes, but consistent normalization at the entry would be even more robust.

[claude]

Reviewed; no blockers found.

[jcohen-hdb]

Real-world validation: withMCPAuth works end-to-end against a live Claude.ai remote connector (Harper 5.1.x) 🎉

Pulled this branch into a staging deploy and connected it as a custom remote MCP connector from Claude.ai (full browser OAuth: discovery → DCR → Google → consent → token → tool list). The connector authenticated and listed all 17 of the app's tools — the bearer guard validated a real Claude-issued token cleanly.

Registration that worked: the urlPath subroute model, exactly as your module header recommends:

server.http(withMCPAuth(handler, { getConfig, logger, onAuthError }), { urlPath: '/mcp' });

Confirmed the key behavior: POST /mcp with no/invalid token returns 401 WWW-Authenticate: Bearer resource_metadata="…" (not core auth's Basic) — the routed-dispatch isolation holds, and the RFC 9728 loop closes. The onAuthError deny reasons were spot-on ("missing or malformed Authorization: Bearer header" during discovery; "…not issued for this resource" for a stale cached token).

One scenario worth a doc note — cross-component usage. Our setup differs from the integration fixture: the component that declares @harperfast/oauth (and owns the host-global routes / token issuance) is separate from the app component that exposes the MCP tools. To make withMCPAuth work from the consumer component, two things mattered:

• getConfig had to be injected. OAuthResource.mcpConfig is a module-local static, and the consumer resolves its own node_modules copy of the package, so mcpConfig is undefined there. We injected getConfig returning { enabled: true, issuer, resource } with the issuer pinned to the provider's mcp.issuer so the iss/aud checks match the minted tokens.
• The default MCPKeyStore worked as-is — it reads databases.oauth.harper_oauth_mcp_keys, which is cluster-global, so the consumer verifies against the same JWKS the provider mints with. 👍
• Importing withMCPAuth as a function (no config.yaml declaration in the consumer) correctly does not spin up a second plugin instance.

Might be worth a short "consuming withMCPAuth from a different component than the plugin" section in the docs (inject getConfig; keys come from the shared oauth DB). Or, if you'd prefer consumers not hardcode the issuer, withMCPAuth could optionally resolve config from the published AS metadata as a fallback.

Test caveat: we ran this combined with the Harper-5.1.x fixes in #133 (well-known relative-urlPath + {status,body} envelope) plus a path-aware RFC 9728 PRM (Claude fetches /.well-known/oauth-protected-resource/mcp, the resource-path-appended form). On a 5.1.x base without those, discovery 404s before the token step — so #134 lands cleanest on top of #133. Happy to share our combined branch or more logs if useful.

[heskew]

Updated now that #133 is merged. Two changes:

1. Rebased onto main (picks up fix: MCP OAuth endpoints broken on Harper 5.1.x (well-known 404 + response envelope) #133's Harper-5.1.x discovery fixes + path-aware PRM, and the chore(ci): bump ai-review-prompts to 1bbc562 (week-of-06-15 calibration + log-count fix) #135 AI-review-prompts bump). Clean rebase — wellKnown.ts auto-merged (MCP OAuth Stage 5: withMCPAuth bearer-token guard (#95) #134's export PRM_PATH + fix: MCP OAuth endpoints broken on Harper 5.1.x (well-known 404 + response envelope) #133's path-aware handler).
2. Closed the challenge-emit half (d899d8a): withMCPAuth's WWW-Authenticate: Bearer resource_metadata="…" now points at the RFC 9728 §3.1 path-appended PRM (<resource-origin>/.well-known/oauth-protected-resource/<resource-path>) that fix: MCP OAuth endpoints broken on Harper 5.1.x (well-known 404 + response envelope) #133 serves — via a new exported protectedResourceMetadataUrl() shared as the single source of truth with the serving side. Also added a "using withMCPAuth from a different component than the plugin" docs section (inject getConfig; keys come from the shared oauth DB) per @jcohen-hdb's field report.

Cross-model review of the emit delta (Codex + Harper-domain pass; Gemini skipped — exfiltration-blocked, CI bot covers): no blockers, no significant concerns. Confirmed emit==serve across edge cases (trailing slash, multi-segment, root, query/fragment), fail-closed preserved, no audience-binding drift. One pre-existing config-hygiene note (schemeless mcp.issuer — already documented as "pin to a full origin in prod"), not introduced here.

Tests: 701 total, 699 pass, 2 skipped. Build/lint/format clean.

With #133 merged, the discovery loop now closes end-to-end (serve + emit). Ready to flip out of draft once CI is green.

[kriszyp]

Approving — the withMCPAuth bearer guard fails closed throughout (missing / malformed / expired / wrong-scheme all denied), verification is pinned to RS256 (no alg-confusion), and the deny paths are well covered by tests. A few minor suggestions in the thread, none blocking. Nice work @heskew!

— 🤖 KrAIs (Kris's review assistant)

[heskew]

One fail-closed edge worth closing:

withMCPAuth() defaults to OAuthResource.mcpConfig as its config source, but updateConfiguration() only refreshes that static through OAuthResource.configure() when at least one provider is valid. If a live config reload removes/invalidates all providers, the plugin swaps in the "No valid OAuth providers" resource but leaves the previous OAuthResource.mcpConfig in place. I reproduced that by starting with mcp.enabled: true, reloading to providers: {}, and observing OAuthResource.mcpConfig still report the old enabled config.

That means a same-component withMCPAuth(handler) route can keep issuing Bearer challenges and verifying tokens against stale MCP config after the plugin config no longer has a valid provider set. Please clear/update OAuthResource.mcpConfig on every config update, including the zero-provider branch, or make the default getter fail closed when provider configuration is invalid.

---

🤖 Posted by Codex (gpt-5.5) on Nathan's behalf

[kriszyp]

Approving — the new commit closes a real fail-open hole: a live config reload to zero providers previously left the stale enabled:true mcpConfig in place, so the MCP surface kept verifying tokens / serving discovery. Nulling the static in the zero-provider branch makes the guard's first gate deny everything. Re-checked the auth invariants: still fails closed at every branch, RS256 pinning untouched, no deny path weakened, and the regression test exercises the real config-listener path. The 3 earlier suggestions (key-store hoist, default-group next doc, payload: any cast) are cosmetic — fine to defer. Nice catch @heskew!

— 🤖 KrAIs (Kris's review assistant)