Implement SEP-985: OAuth Protected Resource Metadata discovery fallback

[cbcoutinho]

Summary

Implements SEP-985 to align OAuth 2.0 Protected Resource Metadata discovery with RFC 9728. This update makes WWW-Authenticate headers optional and adds support for well-known URI fallback, enabling more flexible server deployment models.

Changes

• Discovery State Management: Added discovery_urls and discovery_index fields to OAuthContext to track fallback URL attempts
• Multi-Step Discovery: Implemented _build_protected_resource_discovery_urls() to generate ordered list of discovery URLs:
  1. WWW-Authenticate header resource_metadata parameter (if present)
  2. Path-based well-known URI: /.well-known/oauth-protected-resource/{path}
  3. Root-based well-known URI: /.well-known/oauth-protected-resource
• Fallback Logic: Updated async_auth_flow() to loop through discovery URLs until one succeeds or all are exhausted
• Response Handling: Modified _handle_protected_resource_response() to return boolean indicating success, enabling automatic fallback on 404 or validation errors

Test Coverage

Added comprehensive TestSEP985Discovery test class with three scenarios:

• Path-based well-known URI fallback when WWW-Authenticate header is absent
• Root-based well-known URI fallback when path-based returns 404
• WWW-Authenticate header priority over well-known URIs

All existing tests pass (92 passed, 1 xfailed as expected).

Motivation

SEP-985 addresses deployment challenges in large-scale, multi-tenant environments where injecting WWW-Authenticate headers from backend services is complex due to separation of concerns. By making headers optional and requiring well-known URI support, servers can choose the discovery mechanism that best fits their architecture.

Test Plan

• Run client auth tests: pytest tests/client/test_auth.py
• Run server auth tests: pytest tests/server/auth/
• Verify all SEP-985 specific tests pass
• Confirm no regressions in existing tests
• Test backward compatibility with servers using only WWW-Authenticate headers

References

• Closes Implement SEP-985: Align OAuth 2.0 Protected Resource Metadata with RFC 9728 #1341
• Spec PR: SEP-985: Updating the Authorization spec to fallback to WWW-Authenticate when Protected Resource Metadata is not found modelcontextprotocol#971 (merged)
• RFC 9728: https://datatracker.ietf.org/doc/html/rfc9728

[pcarleton]

thanks @cbcoutinho ! I added a few tweaks to be more similar to OAuth Authorization Server metadata discovery (step 3) and eliminate additions to context.