extauth: add ClientCredentialsHandler for OAuth client credentials grant

Add an implementation of auth.OAuthHandler that uses the OAuth 2.0
Client Credentials grant (RFC 6749 Section 4.4) for service-to-service
authentication with pre-registered credentials. This bypasses both
dynamic client registration and the authorization code flow.

The handler supports two modes:
- Direct token endpoint URL
- Metadata discovery via AuthServerURL (RFC 8414)

Also adds client_credentials grant type support to the fake
authorization server in internal/oauthtest for testing.

Refs #627

Author: ravyg

auth/extauth/client_credentials.go

@@ -0,0 +1,153 @@
+// Copyright 2026 The Go MCP SDK Authors. All rights reserved.
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package extauth
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/modelcontextprotocol/go-sdk/auth"
+	"github.com/modelcontextprotocol/go-sdk/oauthex"
+	"golang.org/x/oauth2"
+	"golang.org/x/oauth2/clientcredentials"
+)
+
+// ClientCredentialsHandlerConfig is the configuration for [ClientCredentialsHandler].
+type ClientCredentialsHandlerConfig struct {
+	// Credentials contains the pre-registered client ID and secret.
+	// REQUIRED. Both ClientID and ClientSecretAuth must be set, since the
+	// client credentials grant requires a confidential client.
+	Credentials *oauthex.ClientCredentials
+
+	// Scopes is the list of scopes to request at the authorization server.
+	// OPTIONAL.
+	Scopes []string
+
+	// AuthServerURL is the authorization server issuer URL.
+	// If set, the token endpoint is discovered via OAuth 2.0 Authorization
+	// Server Metadata (RFC 8414). Either AuthServerURL or TokenEndpoint must
+	// be provided, but not both.
+	AuthServerURL string
+
+	// TokenEndpoint is the token endpoint URL to use directly, skipping
+	// metadata discovery. Either AuthServerURL or TokenEndpoint must be
+	// provided, but not both.
+	TokenEndpoint string
+
+	// HTTPClient is an optional HTTP client for customization.
+	// If nil, http.DefaultClient is used.
+	// OPTIONAL.
+	HTTPClient *http.Client
+}
+
+// ClientCredentialsHandler is an implementation of [auth.OAuthHandler] that
+// uses the OAuth 2.0 Client Credentials grant (RFC 6749 Section 4.4) to
+// obtain access tokens.
+//
+// This handler is intended for service-to-service authentication where the
+// client has pre-registered credentials (client ID and secret) and does not
+// require user interaction. It bypasses both dynamic client registration and
+// the authorization code flow.
+//
+// See the ext-auth specification SEP-1046 for details.
+type ClientCredentialsHandler struct {
+	config      *ClientCredentialsHandlerConfig
+	tokenSource oauth2.TokenSource
+}
+
+// Compile-time check that ClientCredentialsHandler implements auth.OAuthHandler.
+var _ auth.OAuthHandler = (*ClientCredentialsHandler)(nil)
+
+// NewClientCredentialsHandler creates a new ClientCredentialsHandler.
+// It validates the configuration and returns an error if invalid.
+func NewClientCredentialsHandler(config *ClientCredentialsHandlerConfig) (*ClientCredentialsHandler, error) {
+	if config == nil {
+		return nil, fmt.Errorf("config must be provided")
+	}
+	if config.Credentials == nil {
+		return nil, fmt.Errorf("credentials is required")
+	}
+	if err := config.Credentials.Validate(); err != nil {
+		return nil, fmt.Errorf("invalid credentials: %w", err)
+	}
+	if config.Credentials.ClientSecretAuth == nil {
+		return nil, fmt.Errorf("clientSecretAuth is required for client credentials grant")
+	}
+	if config.AuthServerURL == "" && config.TokenEndpoint == "" {
+		return nil, fmt.Errorf("either authServerURL or tokenEndpoint must be provided")
+	}
+	if config.AuthServerURL != "" && config.TokenEndpoint != "" {
+		return nil, fmt.Errorf("authServerURL and tokenEndpoint are mutually exclusive")
+	}
+	return &ClientCredentialsHandler{config: config}, nil
+}
+
+// TokenSource returns the token source for outgoing requests.
+// Returns nil if authorization has not been performed yet.
+func (h *ClientCredentialsHandler) TokenSource(ctx context.Context) (oauth2.TokenSource, error) {
+	return h.tokenSource, nil
+}
+
+// Authorize performs the Client Credentials grant to obtain an access token.
+// It is called when a request fails with 401 or 403.
+func (h *ClientCredentialsHandler) Authorize(ctx context.Context, req *http.Request, resp *http.Response) error {
+	defer resp.Body.Close()
+	defer io.Copy(io.Discard, resp.Body)
+
+	httpClient := h.config.HTTPClient
+	if httpClient == nil {
+		httpClient = http.DefaultClient
+	}
+
+	tokenEndpoint := h.config.TokenEndpoint
+	if tokenEndpoint == "" {
+		// Discover token endpoint via authorization server metadata.
+		meta, err := auth.GetAuthServerMetadata(ctx, h.config.AuthServerURL, httpClient)
+		if err != nil {
+			return fmt.Errorf("failed to discover auth server metadata: %w", err)
+		}
+		if meta == nil {
+			return fmt.Errorf("no authorization server metadata found for: %s", h.config.AuthServerURL)
+		}
+		tokenEndpoint = meta.TokenEndpoint
+		if tokenEndpoint == "" {
+			return fmt.Errorf("token_endpoint not found in authorization server metadata")
+		}
+	}
+
+	creds := h.config.Credentials
+	cfg := &clientcredentials.Config{
+		ClientID:     creds.ClientID,
+		ClientSecret: creds.ClientSecretAuth.ClientSecret,
+		TokenURL:     tokenEndpoint,
+		Scopes:       h.config.Scopes,
+	}
+
+	ctxWithClient := context.WithValue(ctx, oauth2.HTTPClient, httpClient)
+	h.tokenSource = cfg.TokenSource(ctxWithClient)
+
+	// Eagerly fetch a token to surface errors immediately.
+	if _, err := h.tokenSource.Token(); err != nil {
+		h.tokenSource = nil
+		return fmt.Errorf("client credentials token request failed: %w", err)
+	}
+	return nil
+}
+
+// AuthStyle returns the recommended auth style based on a list of supported
+// token endpoint auth methods from the authorization server metadata.
+// Returns [oauth2.AuthStyleInHeader] (HTTP Basic) by default, which is the
+// recommended method per RFC 6749 Section 2.3.1.
+func AuthStyle(methods []string) oauth2.AuthStyle {
+	for _, m := range methods {
+		if strings.EqualFold(m, "client_secret_post") {
+			return oauth2.AuthStyleInParams
+		}
+	}
+	return oauth2.AuthStyleInHeader
+}