Add environment variable support for token exchange client secret (#2148)

Add support for reading the OAuth client secret from the
TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET environment variable when not
provided in the middleware configuration. This enables secure secret
injection via Kubernetes Secrets without embedding plaintext secrets
in ConfigMaps.

The middleware will:
1. First check if client_secret is provided in the config
2. If empty, read from TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET env var
3. Fall back to empty string if neither is provided

The implementation uses dependency injection for testability, with an
internal envGetter function that can be overridden in tests. This
allows comprehensive unit testing of all environment variable
scenarios without relying on actual environment manipulation.

This follows ToolHive's naming convention of prefixing all environment
variables with TOOLHIVE_ and is consistent with other secret handling
patterns in the codebase such as TOOLHIVE_REMOTE_OAUTH_CLIENT_SECRET.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: JAORMX

pkg/auth/tokenexchange/middleware.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"os"
 	"strings"
 
 	"github.com/golang-jwt/jwt/v5"
@@ -27,8 +28,23 @@ const (
 	HeaderStrategyCustom = "custom"
 )
 
+// Environment variable names
+const (
+	// EnvClientSecret is the environment variable name for the OAuth client secret
+	// This corresponds to the "client_secret" field in the token exchange configuration
+	//nolint:gosec // G101: This is an environment variable name, not a credential
+	EnvClientSecret = "TOOLHIVE_TOKEN_EXCHANGE_CLIENT_SECRET"
+)
+
 var errUnknownStrategy = errors.New("unknown token injection strategy")
 
+// envGetter is a function that retrieves environment variables
+// This can be overridden for testing
+type envGetter func(string) string
+
+// defaultEnvGetter is the default environment variable getter using os.Getenv
+var defaultEnvGetter envGetter = os.Getenv
+
 // MiddlewareParams represents the parameters for token exchange middleware
 type MiddlewareParams struct {
 	TokenExchangeConfig *Config `json:"token_exchange_config,omitempty"`
@@ -155,6 +171,12 @@ func createCustomInjector(headerName string) injectionFunc {
 // from the auth middleware to perform token exchange.
 // This is a public function for direct usage in proxy commands.
 func CreateTokenExchangeMiddlewareFromClaims(config Config) (types.MiddlewareFunction, error) {
+	return createTokenExchangeMiddlewareFromClaims(config, defaultEnvGetter)
+}
+
+// createTokenExchangeMiddlewareFromClaims is the internal implementation that accepts an envGetter
+// This allows for dependency injection in tests
+func createTokenExchangeMiddlewareFromClaims(config Config, getEnv envGetter) (types.MiddlewareFunction, error) {
 	// Determine injection strategy at startup time
 	strategy := config.HeaderStrategy
 	if strategy == "" {
@@ -171,11 +193,21 @@ func CreateTokenExchangeMiddlewareFromClaims(config Config) (types.MiddlewareFun
 		return nil, fmt.Errorf("%w: invalid header injection strategy %s", errUnknownStrategy, strategy)
 	}
 
+	// Resolve client secret from config or environment variable
+	clientSecret := config.ClientSecret
+	if clientSecret == "" {
+		// If not provided in config, try to read from environment variable
+		if envSecret := getEnv(EnvClientSecret); envSecret != "" {
+			clientSecret = envSecret
+			logger.Debug("Using client secret from environment variable")
+		}
+	}
+
 	// Create base exchange config at startup time with all static fields
 	baseExchangeConfig := ExchangeConfig{
 		TokenURL:     config.TokenURL,
 		ClientID:     config.ClientID,
-		ClientSecret: config.ClientSecret,
+		ClientSecret: clientSecret,
 		Audience:     config.Audience,
 		Scopes:       config.Scopes,
 		// SubjectTokenProvider will be set per request

pkg/auth/tokenexchange/middleware_test.go

@@ -619,3 +619,116 @@ func TestMiddleware_Methods(t *testing.T) {
 	err := mw.Close()
 	assert.NoError(t, err)
 }
+
+// TestCreateTokenExchangeMiddlewareFromClaims_EnvironmentVariable tests client secret from environment variable.
+func TestCreateTokenExchangeMiddlewareFromClaims_EnvironmentVariable(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                 string
+		configClientSecret   string
+		envClientSecret      string
+		expectedClientSecret string
+		description          string
+	}{
+		{
+			name:                 "config secret takes precedence over env var",
+			configClientSecret:   "config-secret",
+			envClientSecret:      "env-secret",
+			expectedClientSecret: "config-secret",
+			description:          "should use client secret from config when provided",
+		},
+		{
+			name:                 "env var used when config secret is empty",
+			configClientSecret:   "",
+			envClientSecret:      "env-secret",
+			expectedClientSecret: "env-secret",
+			description:          "should fallback to environment variable when config is empty",
+		},
+		{
+			name:                 "empty when both are empty",
+			configClientSecret:   "",
+			envClientSecret:      "",
+			expectedClientSecret: "",
+			description:          "should be empty when neither config nor env var is set",
+		},
+		{
+			name:                 "config secret used when env var is empty",
+			configClientSecret:   "config-secret",
+			envClientSecret:      "",
+			expectedClientSecret: "config-secret",
+			description:          "should use config secret when env var is empty",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Track which client secret was actually used in the request
+			var receivedClientSecret string
+
+			// Create mock OAuth server that captures the client secret
+			exchangeServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				// Extract client secret from Basic Auth header
+				_, password, ok := r.BasicAuth()
+				if ok {
+					receivedClientSecret = password
+				}
+
+				resp := response{
+					AccessToken:     "exchanged-token",
+					TokenType:       "Bearer",
+					IssuedTokenType: "urn:ietf:params:oauth:token-type:access_token",
+					ExpiresIn:       3600,
+				}
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(http.StatusOK)
+				_ = json.NewEncoder(w).Encode(resp)
+			}))
+			defer exchangeServer.Close()
+
+			// Mock environment getter
+			mockEnvGetter := func(key string) string {
+				if key == EnvClientSecret {
+					return tt.envClientSecret
+				}
+				return ""
+			}
+
+			config := Config{
+				TokenURL:     exchangeServer.URL,
+				ClientID:     "test-client-id",
+				ClientSecret: tt.configClientSecret,
+				Audience:     "https://api.example.com",
+			}
+
+			// Use the internal function with mock env getter
+			middleware, err := createTokenExchangeMiddlewareFromClaims(config, mockEnvGetter)
+			require.NoError(t, err)
+
+			// Test handler
+			testHandler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+			})
+
+			// Create request with claims and token
+			req := httptest.NewRequest(http.MethodGet, "/test", nil)
+			req.Header.Set("Authorization", "Bearer original-token")
+			claims := jwt.MapClaims{
+				"sub": "user123",
+				"aud": "test-audience",
+			}
+			ctx := context.WithValue(req.Context(), auth.ClaimsContextKey{}, claims)
+			req = req.WithContext(ctx)
+
+			// Execute middleware
+			rec := httptest.NewRecorder()
+			handler := middleware(testHandler)
+			handler.ServeHTTP(rec, req)
+
+			assert.Equal(t, http.StatusOK, rec.Code)
+			assert.Equal(t, tt.expectedClientSecret, receivedClientSecret, tt.description)
+		})
+	}
+}