Integrate token exchange middleware

Adds OAuth 2.0 Token Exchange (RFC 8693) support to both 'thv proxy'
and 'thv run' commands for secure downstream token swapping.

Changes include:
- New token exchange configuration flags in RemoteAuthFlags
- Refactored secret resolution into reusable resolveSecretFromSources
- Token exchange middleware registration in runner config builder
- Conditional middleware application based on configuration

When token exchange is configured via --token-exchange-url, the
middleware exchanges the user's bearer token for a downstream token
suitable for backend authentication.

Fixes: #2066

Author: jhrozek

cmd/thv/app/auth_flags.go

@@ -5,6 +5,8 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/stacklok/toolhive/pkg/auth/tokenexchange"
+	"github.com/stacklok/toolhive/pkg/logger"
 	"github.com/stacklok/toolhive/pkg/runner"
 )
 
@@ -21,6 +23,56 @@ type RemoteAuthFlags struct {
 	RemoteAuthIssuer           string
 	RemoteAuthAuthorizeURL     string
 	RemoteAuthTokenURL         string
+
+	// Token Exchange Configuration
+	TokenExchangeURL              string
+	TokenExchangeClientID         string
+	TokenExchangeClientSecret     string
+	TokenExchangeClientSecretFile string
+	TokenExchangeAudience         string
+	TokenExchangeScopes           []string
+	TokenExchangeHeaderName       string
+}
+
+// BuildTokenExchangeConfig creates a TokenExchangeConfig from the RemoteAuthFlags
+// Returns nil if TokenExchangeURL is empty (token exchange is not configured)
+func (f *RemoteAuthFlags) BuildTokenExchangeConfig() *tokenexchange.Config {
+	// Only create config if token exchange URL is provided
+	if f.TokenExchangeURL == "" {
+		return nil
+	}
+
+	// Resolve token exchange client secret from multiple sources
+	clientSecret, err := resolveSecretFromSources(
+		f.TokenExchangeClientSecret,
+		f.TokenExchangeClientSecretFile,
+		envTokenExchangeClientSecret,
+		"token exchange client secret",
+	)
+	if err != nil {
+		logger.Warnf("Failed to resolve token exchange client secret: %v", err)
+		clientSecret = ""
+	}
+
+	// Determine header strategy based on whether custom header name is provided
+	var headerStrategy string
+	var externalTokenHeaderName string
+	if f.TokenExchangeHeaderName != "" {
+		headerStrategy = tokenexchange.HeaderStrategyCustom
+		externalTokenHeaderName = f.TokenExchangeHeaderName
+	} else {
+		headerStrategy = tokenexchange.HeaderStrategyReplace
+	}
+
+	return &tokenexchange.Config{
+		TokenURL:                f.TokenExchangeURL,
+		ClientID:                f.TokenExchangeClientID,
+		ClientSecret:            clientSecret,
+		Audience:                f.TokenExchangeAudience,
+		Scopes:                  f.TokenExchangeScopes,
+		HeaderStrategy:          headerStrategy,
+		ExternalTokenHeaderName: externalTokenHeaderName,
+	}
 }
 
 // AddRemoteAuthFlags adds the common remote authentication flags to a command
@@ -47,4 +99,20 @@ func AddRemoteAuthFlags(cmd *cobra.Command, config *RemoteAuthFlags) {
 		"OAuth authorization endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)")
 	cmd.Flags().StringVar(&config.RemoteAuthTokenURL, "remote-auth-token-url", "",
 		"OAuth token endpoint URL (alternative to --remote-auth-issuer for non-OIDC OAuth)")
+
+	// Token Exchange flags
+	cmd.Flags().StringVar(&config.TokenExchangeURL, "token-exchange-url", "",
+		"OAuth 2.0 token exchange endpoint URL (enables token exchange when provided)")
+	cmd.Flags().StringVar(&config.TokenExchangeClientID, "token-exchange-client-id", "",
+		"OAuth client ID for token exchange operations")
+	cmd.Flags().StringVar(&config.TokenExchangeClientSecret, "token-exchange-client-secret", "",
+		"OAuth client secret for token exchange operations")
+	cmd.Flags().StringVar(&config.TokenExchangeClientSecretFile, "token-exchange-client-secret-file", "",
+		"Path to file containing OAuth client secret for token exchange (alternative to --token-exchange-client-secret)")
+	cmd.Flags().StringVar(&config.TokenExchangeAudience, "token-exchange-audience", "",
+		"Target audience for exchanged tokens")
+	cmd.Flags().StringSliceVar(&config.TokenExchangeScopes, "token-exchange-scopes", []string{},
+		"Scopes to request for exchanged tokens")
+	cmd.Flags().StringVar(&config.TokenExchangeHeaderName, "token-exchange-header-name", "",
+		"Custom header name for injecting exchanged token (default: replaces Authorization header)")
 }

cmd/thv/app/proxy.go

@@ -18,6 +18,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/auth"
 	"github.com/stacklok/toolhive/pkg/auth/discovery"
 	"github.com/stacklok/toolhive/pkg/auth/oauth"
+	"github.com/stacklok/toolhive/pkg/auth/tokenexchange"
 	"github.com/stacklok/toolhive/pkg/logger"
 	"github.com/stacklok/toolhive/pkg/networking"
 	"github.com/stacklok/toolhive/pkg/transport"
@@ -121,6 +122,8 @@ var (
 const (
 	// #nosec G101 - this is an environment variable name, not a credential
 	envOAuthClientSecret = "TOOLHIVE_REMOTE_OAUTH_CLIENT_SECRET"
+	// #nosec G101 - this is an environment variable name, not a credential
+	envTokenExchangeClientSecret = "TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET"
 )
 
 func init() {
@@ -227,8 +230,19 @@ func proxyCmdFunc(cmd *cobra.Command, args []string) error {
 	}
 	middlewares = append(middlewares, authMiddleware)
 
-	// Add OAuth token injection middleware for outgoing requests if we have an access token
-	if tokenSource != nil {
+	// Add OAuth token injection or token exchange middleware for outgoing requests
+	if remoteAuthFlags.TokenExchangeURL != "" {
+		// Use token exchange middleware when token exchange is configured
+		tokenExchangeConfig := createTokenExchangeConfig()
+		if tokenExchangeConfig != nil {
+			tokenExchangeMiddleware, teMwErr := tokenexchange.CreateTokenExchangeMiddlewareFromClaims(*tokenExchangeConfig)
+			if teMwErr != nil {
+				return fmt.Errorf("failed to create token exchange middleware: %v", teMwErr)
+			}
+			middlewares = append(middlewares, tokenExchangeMiddleware)
+		}
+	} else if tokenSource != nil {
+		// Fallback to direct token injection when no token exchange is configured
 		tokenMiddleware := createTokenInjectionMiddleware(tokenSource)
 		middlewares = append(middlewares, tokenMiddleware)
 	}
@@ -346,43 +360,70 @@ func handleOutgoingAuthentication(ctx context.Context) (*oauth2.TokenSource, *oa
 	return nil, nil, nil // No authentication required
 }
 
-// resolveClientSecret resolves the OAuth client secret from multiple sources
-// Priority: 1. Flag value, 2. File, 3. Environment variable
-func resolveClientSecret() (string, error) {
+// resolveSecretFromSources resolves a secret from multiple sources with priority ordering
+// Priority: 1. Direct value (flag), 2. File path, 3. Environment variable
+// Returns empty string if no source provides a value (not an error)
+func resolveSecretFromSources(directValue, filePath, envVarName, secretType string) (string, error) {
 	// 1. Check if provided directly via flag
-	if remoteAuthFlags.RemoteAuthClientSecret != "" {
-		logger.Debug("Using client secret from command-line flag")
-		return remoteAuthFlags.RemoteAuthClientSecret, nil
+	if directValue != "" {
+		logger.Debugf("Using %s from command-line flag", secretType)
+		return directValue, nil
 	}
 
 	// 2. Check if provided via file
-	if remoteAuthFlags.RemoteAuthClientSecretFile != "" {
+	if filePath != "" {
 		// Clean the file path to prevent path traversal
-		cleanPath := filepath.Clean(remoteAuthFlags.RemoteAuthClientSecretFile)
-		logger.Debugf("Reading client secret from file: %s", cleanPath)
+		cleanPath := filepath.Clean(filePath)
+		logger.Debugf("Reading %s from file: %s", secretType, cleanPath)
 		// #nosec G304 - file path is cleaned above
 		secretBytes, err := os.ReadFile(cleanPath)
 		if err != nil {
-			return "", fmt.Errorf("failed to read client secret file %s: %w", cleanPath, err)
+			return "", fmt.Errorf("failed to read %s file %s: %w", secretType, cleanPath, err)
 		}
 		secret := strings.TrimSpace(string(secretBytes))
 		if secret == "" {
-			return "", fmt.Errorf("client secret file %s is empty", cleanPath)
+			return "", fmt.Errorf("%s file %s is empty", secretType, cleanPath)
 		}
 		return secret, nil
 	}
 
 	// 3. Check environment variable
-	if secret := os.Getenv(envOAuthClientSecret); secret != "" {
-		logger.Debugf("Using client secret from %s environment variable", envOAuthClientSecret)
-		return secret, nil
+	if envVarName != "" {
+		if secret := os.Getenv(envVarName); secret != "" {
+			logger.Debugf("Using %s from %s environment variable", secretType, envVarName)
+			return secret, nil
+		}
 	}
 
-	// No client secret found - this is acceptable for PKCE flows
-	logger.Debug("No client secret provided - using PKCE flow")
+	// No secret found - return empty string (caller decides if this is an error)
+	logger.Debugf("No %s provided", secretType)
 	return "", nil
 }
 
+// resolveClientSecret resolves the OAuth client secret from multiple sources
+// Priority: 1. Flag value, 2. File, 3. Environment variable
+func resolveClientSecret() (string, error) {
+	secret, err := resolveSecretFromSources(
+		remoteAuthFlags.RemoteAuthClientSecret,
+		remoteAuthFlags.RemoteAuthClientSecretFile,
+		envOAuthClientSecret,
+		"client secret",
+	)
+	if err != nil {
+		return "", err
+	}
+	if secret == "" {
+		// No client secret found - this is acceptable for PKCE flows
+		logger.Debug("No client secret provided - using PKCE flow")
+	}
+	return secret, nil
+}
+
+// createTokenExchangeConfig creates a TokenExchangeConfig from remoteAuthFlags
+func createTokenExchangeConfig() *tokenexchange.Config {
+	return remoteAuthFlags.BuildTokenExchangeConfig()
+}
+
 // createTokenInjectionMiddleware creates a middleware that injects the OAuth token into requests
 func createTokenInjectionMiddleware(tokenSource *oauth2.TokenSource) types.MiddlewareFunction {
 	return func(next http.Handler) http.Handler {

cmd/thv/app/run_flags.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/stacklok/toolhive/pkg/auth"
+	"github.com/stacklok/toolhive/pkg/auth/tokenexchange"
 	"github.com/stacklok/toolhive/pkg/authz"
 	"github.com/stacklok/toolhive/pkg/cli"
 	cfg "github.com/stacklok/toolhive/pkg/config"
@@ -458,10 +459,12 @@ func buildRunnerConfig(
 	opts = append(opts, runner.WithToolsOverride(toolsOverride))
 	// Configure middleware from flags
 	// Use computed serverName and transportType for correct telemetry labels
+	tokenExchangeConfig := getTokenExchangeConfigFromRunFlags(runFlags)
 	opts = append(
 		opts,
 		runner.WithMiddlewareFromFlags(
 			oidcConfig,
+			tokenExchangeConfig,
 			runFlags.ToolsFilter,
 			toolsOverride,
 			telemetryConfig,
@@ -605,6 +608,11 @@ func getRemoteAuthFromRunFlags(runFlags *RunFlags) *runner.RemoteAuthConfig {
 	}
 }
 
+// getTokenExchangeConfigFromRunFlags creates TokenExchangeConfig from RunFlags
+func getTokenExchangeConfigFromRunFlags(runFlags *RunFlags) *tokenexchange.Config {
+	return runFlags.RemoteAuthFlags.BuildTokenExchangeConfig()
+}
+
 // getOidcFromFlags extracts OIDC configuration from command flags
 func getOidcFromFlags(cmd *cobra.Command) (string, string, string, string, string, string) {
 	oidcIssuer := GetStringFlagOrEmpty(cmd, "oidc-issuer")