all: client side OAuth support (#785)

This PR introduces client-side OAuth support.

# Overall design philosophy

The main new interface introduced to support client-side OAuth is the
`OAuthHandler`. Contrary to its counter-parts in some other SDKs, it is
intentionally small and generic so that it can support most of the OAuth
authorization flow variants. The main `mcp` package purposefully
delegates almost all auth handling to `OAuthHandler` implementations.
This way, the `mcp` package continues to be largely OAuth agnostic.

The `auth` package comes with a default `OAuthHandler` implementation –
`AuthorizationCodeHandler`, which implements the authorization flow
for the `authorization_code` grant type, as defined in the [MCP
specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
It is expected that the `OAuthHandler` implementation granularity will
be roughly per grant type, as this parameter influences the
authorization flow the most.

# Detailed design

## `OAuthHandler` (auth/client.go)

The main interface for the integration consists of two methods:

```go
type OAuthHandler interface {
	// TokenSource returns a token source to be used for outgoing requests.
	// Returned token source might be nil. In that case, the transport will not
	// add any authorization headers to the request.
	TokenSource(context.Context) (oauth2.TokenSource, error)

	// Authorize is called when an HTTP request results in an error that may
	// be addressed by the authorization flow (currently 401 Unauthorized and 403 Forbidden).
	// It is responsible for performing the OAuth flow to obtain an access token.
	// The arguments are the request that failed and the response that was received for it.
	// The headers of the request are available, but the body will have already been consumed
	// when Authorize is called.
	// If the returned error is nil, TokenSource is expected to return a non-nil token source.
	// After a successful call to Authorize, the HTTP request will be retried by the transport.
	// The function is responsible for closing the response body.
	Authorize(context.Context, *http.Request, *http.Response) error
}
```

`StreamableClientTransport` accepts this interface as a field and uses
the `TokenSource` method to add an `Authorization: Bearer` header to
outgoing requests to the MCP server. If the request fails with `401:
Unauthorized` or `403: Forbidden`, the transport calls `Authorize` to
perform the authorization flow. If `Authorize` returns a non-nil error,
the request is retried once. `Authorize` errors do not result in
termination of the client session (unless they happen during
connection initialization), as some OAuth flows are multi-legged and it should be
acceptable to retry for example when the authorization grant was
received.

*Note:* There was already an `OAuthHandler` type defined as part of a
previous iteration of OAuth support. It was renamed to
`OAuthHandlerLegacy`. This is the only backwards incompatible API change
in the experimental client `auth` part (protected by the
`mcp_go_client_oauth` Go build tag). The cost of replacing previous
usages is deemed worthwhile to maintain clear naming, under the
assumption that the experimental client `auth` part was not widely used.

## `AuthorizationCodeHandler` (auth/authorization_code.go)

This is the `OAuthHandler` implementation that fulfills the [MCP
specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
In particular, in supports:

- Protected Resource Metadata discovery and fetching
- Authorization Server Metadata discovery and fetching
- Client registration
  - OpenID Connect metadata document
  - Pre-registration
  - Dynamic Client Registration
- PKCE
- `client_secret_post`, `client_secret_basic` token endpoint
auth methods
- Automatic refresh of tokens

### Authorization Server redirect

As part of the flow for the `authorization_code` grant type, the client
needs to point the user to the authorization URL, so that they confirm
the access request. This design proposes that it will be supported via a
pluggable dependency that will initiate this process in an
application-specific way:

```go
type AuthorizationCodeHandler struct {
	...

	// AuthorizationCodeFetcher is a required function called to initiate the authorization flow.
	// It is responsible for opening the URL in a browser for the user to start the authorization process.
	// It should return the authorization code and state once the Authorization Server
	// redirects back to the RedirectURL.
	AuthorizationCodeFetcher func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error)

	...
}
```

The function is supposed perform any application specific logic to handle the redirect
from the Authorization Server and return the resulting code and state.

## `oauthex` changes

Some additional/adjusted building blocks that may be useful when
creating `OAuthHandler` implementations are present in the `oauthex`
package:

- `auth_meta.go`: Authorization Server Metadata utilities:
  - `GetAuthServerMeta`: get Authorization Server Metadata from a URL
- `dcr.go`: Dynamic Client Registration utilities (unchanged)
- `resource_meta.go`: Protected Resource Metadata utilities:
- `GetProtectedResourceMetadata`: get Protected Resource Metadata from a
URL
  - `ParseWWWAuthenticate` – as per name (unchanged)
- [deprecated] `GetProtectedResourceMetadataFromID` and
`GetProtectedResourceMetadataFromHeader` in favor of more generic
`GetProtectedResourceMetadata`. They will be kept under the Go build tag
and removed one version of the SDK in the future.

oauthex/auth_meta.go

@@ -14,6 +14,9 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"net/url"
+
+	"github.com/modelcontextprotocol/go-sdk/internal/util"
 )
 
 // AuthServerMeta represents the metadata for an OAuth 2.0 authorization server,
@@ -28,8 +31,6 @@ import (
 //
 // [RFC 8414]: https://tools.ietf.org/html/rfc8414)
 type AuthServerMeta struct {
-	// GENERATED BY GEMINI 2.5.
-
 	// Issuer is the REQUIRED URL identifying the authorization server.
 	Issuer string `json:"issuer"`
 
@@ -113,51 +114,61 @@ type AuthServerMeta struct {
 	// CodeChallengeMethodsSupported is a RECOMMENDED JSON array of strings containing a list of
 	// PKCE code challenge methods supported by this authorization server.
 	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported,omitempty"`
-}
 
-var wellKnownPaths = []string{
-	"/.well-known/oauth-authorization-server",
-	"/.well-known/openid-configuration",
+	// ClientIDMetadataDocumentSupported is a boolean indicating whether the authorization server
+	// supports client ID metadata documents.
+	ClientIDMetadataDocumentSupported bool `json:"client_id_metadata_document_supported,omitempty"`
 }
 
 // GetAuthServerMeta issues a GET request to retrieve authorization server metadata
-// from an OAuth authorization server with the given issuerURL.
+// from an OAuth authorization server with the given metadataURL.
 //
 // It follows [RFC 8414]:
-//   - The well-known paths specified there are inserted into the URL's path, one at time.
-//     The first to succeed is used.
-//   - The Issuer field is checked against issuerURL.
+//   - The metadataURL must use HTTPS or be a local address.
+//   - The Issuer field is checked against metadataURL.Issuer.
+//
+// It also verifies that the authorization server supports PKCE and that the URLs
+// in the metadata don't use dangerous schemes.
+//
+// It returns an error if the request fails with a non-4xx status code or the fetched
+// metadata doesn't pass security validations.
+// It returns nil if the request fails with a 4xx status code.
 //
 // [RFC 8414]: https://tools.ietf.org/html/rfc8414
-func GetAuthServerMeta(ctx context.Context, issuerURL string, c *http.Client) (*AuthServerMeta, error) {
-	var errs []error
-	for _, p := range wellKnownPaths {
-		u, err := prependToPath(issuerURL, p)
-		if err != nil {
-			// issuerURL is bad; no point in continuing.
-			return nil, err
-		}
-		asm, err := getJSON[AuthServerMeta](ctx, c, u, 1<<20)
-		if err == nil {
-			if asm.Issuer != issuerURL { // section 3.3
-				// Security violation; don't keep trying.
-				return nil, fmt.Errorf("metadata issuer %q does not match issuer URL %q", asm.Issuer, issuerURL)
-			}
-
-			if len(asm.CodeChallengeMethodsSupported) == 0 {
-				return nil, fmt.Errorf("authorization server at %s does not implement PKCE", issuerURL)
-			}
-
-			// Validate endpoint URLs to prevent XSS attacks (see #526).
-			if err := validateAuthServerMetaURLs(asm); err != nil {
-				return nil, err
-			}
-
-			return asm, nil
-		}
-		errs = append(errs, err)
+func GetAuthServerMeta(ctx context.Context, metadataURL, issuer string, c *http.Client) (*AuthServerMeta, error) {
+	u, err := url.Parse(metadataURL)
+	if err != nil {
+		return nil, err
 	}
-	return nil, fmt.Errorf("failed to get auth server metadata from %q: %w", issuerURL, errors.Join(errs...))
+	// Only allow HTTP for local addresses (testing or development purposes).
+	if !util.IsLoopback(u.Host) && u.Scheme != "https" {
+		return nil, fmt.Errorf("metadataURL %q does not use HTTPS", metadataURL)
+	}
+	asm, err := getJSON[AuthServerMeta](ctx, c, metadataURL, 1<<20)
+	if err != nil {
+		var httpErr *httpStatusError
+		if errors.As(err, &httpErr) {
+			if 400 <= httpErr.StatusCode && httpErr.StatusCode < 500 {
+				return nil, nil
+			}
+		}
+		return nil, fmt.Errorf("%v", err) // Do not expose error types.
+	}
+	if asm.Issuer != issuer {
+		// Validate the Issuer field (see RFC 8414, section 3.3).
+		return nil, fmt.Errorf("metadata issuer %q does not match issuer URL %q", asm.Issuer, issuer)
+	}
+
+	if len(asm.CodeChallengeMethodsSupported) == 0 {
+		return nil, fmt.Errorf("authorization server at %s does not implement PKCE", issuer)
+	}
+
+	// Validate endpoint URLs to prevent XSS attacks (see #526).
+	if err := validateAuthServerMetaURLs(asm); err != nil {
+		return nil, err
+	}
+
+	return asm, nil
 }
 
 // validateAuthServerMetaURLs validates all URL fields in AuthServerMeta