feat: OAuth 2.0 Protected Resource Metadata handler - RFC 9728

[orius123]

auth: add OAuth 2.0 Protected Resource Metadata handler with CORS support

This change adds support for RFC 9728 (OAuth 2.0 Protected Resource Metadata)
by introducing a new ProtectedResourceMetadataHandler that serves the
.well-known/oauth-protected-resource endpoint.

The handler includes built-in CORS support with Access-Control-Allow-Origin: *
by default, as OAuth metadata is public information meant for client discovery.
Documentation includes examples for using custom CORS policies with popular
middleware libraries (github.com/rs/cors and github.com/jub0bs/cors).

Changes:

• Added ProtectedResourceMetadata struct and ProtectedResourceMetadataHandler
  function in auth/auth.go
• Added comprehensive tests for the new handler in auth/auth_test.go
• Updated auth-middleware example with OAuth metadata endpoint and CORS
  documentation in examples/server/auth-middleware/
• Updated protocol documentation to describe the OAuth 2.0 integration

The implementation follows RFC 9728 §3.1 for OAuth 2.0 Authorization Server
Metadata discovery, enabling clients to discover protected resource capabilities
and authentication requirements.

[jba]

LGTM. Just going to have a security person take a look.

[jba]

@rolandshoemaker can you confirm that the CORS policy is acceptable?

[jba]

@wagnerjt Do you think this is a useful addition to the API?

[wagnerjt]

Hey @jba thanks for tagging me!

I have code very similar to the server I have defined in the protocol.md to create the endpoint (the part that just dumps the struct to json).

metadata := &oauthex.ProtectedResourceMetadata{
    Resource: "https://example.com/mcp",
    AuthorizationServers: []string{
        "https://auth.example.com/.well-known/openid-configuration",
    },
    ScopesSupported: []string{"read", "write"},
}
http.Handle("/.well-known/oauth-protected-resource",
    auth.ProtectedResourceMetadataHandler(metadata))

For the CORS element, as described within the example of usage, there are plenty of ways to do it within go as well as other infra depending on how it is hosted. I personally leverage external infra/tooling for cors policy. So I will leave it up to you all on this helper

[findleyr]

@jba are we just waiting on @rolandshoemaker's review for this? I can nudge.

[rolandshoemaker]

CORS policy seems reasonable to me.

[findleyr]

Thanks @rolandshoemaker.

@jba, could you confirm this is good to go? Otherwise, I'll review next week.