feat: expose auth context and MCP scope challenge primitives

[mattzcarey]

Problem

MCP 2026-07-28 adds clearer requirements and recommendations around scope discovery and step-up authorization:

• The initial 401 challenge should identify scopes needed for the protected resource.
• Runtime 403 insufficient_scope challenges should include all scopes needed for the current operation.
• Resource servers must account for configured scope hierarchies when deciding whether a token is sufficient.

The provider currently adds resource_metadata to the initial challenge but has no route-level or request-level way to add scope. OAuthError.requiredScopes can build a runtime challenge only when resolveExternalToken throws. API handlers do not receive a standard authentication context containing the effective token scope, audience, client ID, and grant ID. ctx.props is application data and may represent grant-level values rather than a downscoped access token.

OAuthHelpers.unwrapToken() is a partial workaround for internally issued tokens, but it performs another lookup and does not cover external tokens.

Proposal

Add protected-resource authorization primitives that work consistently for internal and external tokens.

Acceptance criteria

• Expose the effective access-token scope and audience to API handlers without requiring a second token lookup.
• Include useful client/grant identifiers where available without exposing secrets.
• Allow protected routes to provide initial scope guidance in the 401 WWW-Authenticate challenge.
• Provide a standard way for an API handler to return 403 insufficient_scope with scope and resource_metadata challenge parameters.
• Support dynamically computed operation scopes.
• Define how applications configure broader scopes that imply narrower scopes, or provide a policy callback for that decision.
• Keep application props separate from trusted token authorization data.
• Add tests for internal tokens, external tokens, downscoped tokens, initial challenges, runtime step-up challenges, deduplication, and scope hierarchies.

References

• https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#scope-selection-strategy
• https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#scope-challenge-handling
• https://datatracker.ietf.org/doc/html/rfc6750#section-3.1