fix(mcp): validate opaque credentials before OAuth sessions

[fahreddinozcan]

Summary

• reject bearer values that do not match a supported Context7 API-key or OAuth-token format
• validate recognized opaque credentials through Context7's existing authenticated whoami endpoint before entering the MCP handler
• fail closed before MCP initialization, tool listing, or tool calls when validation fails or is unavailable
• use short bounded positive/negative caches keyed by credential hashes
• preserve JWT validation, valid OAuth/API-key access, and anonymous access through /mcp

Security

Fixes the authentication bypass reported in Cobalt finding PT38659_11. Previously any bearer value that was not shaped like a JWT skipped validation and reached the MCP handler. Format recognition is only an early rejection gate: supported opaque formats still require explicit backend approval, so a well-shaped fake API key is rejected with 401 before MCP initialization.

Linear: CTX7-2021 (child of CTX7-2019)

Validation

• pnpm run typecheck
• pnpm run lint:check
• pnpm test (6 files, 102 tests)
• Prettier check on changed TypeScript files

[linear-code]

CTX7-2021

[context7]

Docs7 preview for context7.com

Status	Commit	Updated (UTC)
✅ Ready (visit preview)	d6918d7	2026-08-24 08:16