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]

@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.

[findleyr]

Thanks @rolandshoemaker.

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

[jba]

@findleyr I'm going to take another day to look at this more carefully, just to make sure we're not adding too much that could be done in a simpler way. Will finish tomorrow.