11-25-2025 compliant Auth

[wdawson]

Bring the SDK's OAuth implementation into compliance with MCP Authorization Spec 2025-11-25 and wire up automatic scope selection and upgrade flows.

As discussed with @alexhancock in #641

Motivation and Context

The SDK's OAuth implementation targeted the 2025-03-26 spec and was missing several features from the 2025-11-25 revision:

• RFC 8707 resource parameter binding (MUST per spec)
• PKCE S256 support verification against server metadata
• WWW-Authenticate error/error_description parsing
• Scope selection priority (WWW-Authenticate > PRM > AS metadata > defaults)
• 403 insufficient_scope handling and step-up authorization (SEP-835)
• Protected Resource Metadata scopes_supported (RFC 9728)

SDK consumers also had to manually manage scope selection and handle scope upgrade flows. This change makes those automatic.

How Has This Been Tested?

• 42 auth-specific unit tests covering header parsing, server validation, scope union, upgrade tracking, authorization URL generation, and state store operations
• All 132 rmcp lib unit tests pass (cargo test -p rmcp --lib --all-features)
• Server and client examples build cleanly
• Not yet tested end-to-end against a live server (@alexhancock offered to do this)

Breaking Changes

• AuthorizationMetadata has a new field code_challenge_methods_supported: Option<Vec<String>>. Code that constructs this struct with explicit fields (not ..Default::default()) will need to add the field. The complex_auth_streamhttp example has been updated accordingly.
• handle_response() now returns AuthError::InsufficientScope on 403 with error="insufficient_scope" in the WWW-Authenticate header, and AuthError::AuthorizationFailed("Forbidden") for other 403 responses. Previously all non-401 responses were passed through as Ok.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

This incorporates work from PR #595 by @fizy069 (SEP-835 scope handling). The relevant commits include a Co-authored-by trailer to preserve attribution.

Security vs compatibility philosophy: the SDK defaults to correct spec behavior but falls back gracefully for non-compliant servers, except where the fallback would be insecure. PKCE S256 is always enforced (never falls back to plain or no challenge). RFC 8707 resource parameter is always sent but the flow continues if the server ignores it.

The select_scopes() priority chain follows SEP-835:

1. scope from WWW-Authenticate header
2. scopes_supported from Protected Resource Metadata (RFC 9728)
3. scopes_supported from AS metadata
4. Caller-provided defaults

Passing empty scopes to start_authorization() triggers auto-selection using this chain.

[nbarbettini]

Idea: conformance could be used to test against a live server. Some of the other SDK projects test against it in CI, e.g. https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/workflows/conformance.yml

[wdawson]

Idea: conformance could be used to test against a live server. Some of the other SDK projects test against it in CI, e.g. https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/workflows/conformance.yml

Will leave this up to @alexhancock to tackle in a separate PR probably. Unless you'd like me to add here. Don't want it to be bigger than it needs to be