Consolidate bearer token extraction into utility (#2410)

Extract bearer token extraction logic from three different locations into
a single, utility function to avoid code duplication.

Author: jhrozek

pkg/auth/token.go

@@ -867,24 +867,14 @@ func (v *TokenValidator) buildWWWAuthenticate(includeError bool, errDescription
 // Middleware creates an HTTP middleware that validates JWT tokens.
 func (v *TokenValidator) Middleware(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		// Get the token from the Authorization header
-		authHeader := r.Header.Get("Authorization")
-		if authHeader == "" {
-			w.Header().Set("WWW-Authenticate", v.buildWWWAuthenticate(false, ""))
-			http.Error(w, "Authorization header required", http.StatusUnauthorized)
-			return
-		}
-
-		// Check if the Authorization header has the Bearer prefix
-		if !strings.HasPrefix(authHeader, "Bearer ") {
+		// Extract the bearer token from the Authorization header
+		tokenString, err := ExtractBearerToken(r)
+		if err != nil {
 			w.Header().Set("WWW-Authenticate", v.buildWWWAuthenticate(false, ""))
-			http.Error(w, "Invalid Authorization header format", http.StatusUnauthorized)
+			http.Error(w, err.Error(), http.StatusUnauthorized)
 			return
 		}
 
-		// Extract the token
-		tokenString := strings.TrimPrefix(authHeader, "Bearer ")
-
 		// Validate the token
 		claims, err := v.ValidateToken(r.Context(), tokenString)
 		if err != nil {

pkg/auth/tokenexchange/middleware.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"net/http"
 	"os"
-	"strings"
 
 	"github.com/golang-jwt/jwt/v5"
 	"golang.org/x/oauth2"
@@ -313,16 +312,9 @@ func createTokenExchangeMiddleware(
 				tokenProvider = subjectTokenProvider
 			} else {
 				// otherwise, extract token from incoming request's Authorization header
-				authHeader := r.Header.Get("Authorization")
-				if authHeader == "" || !strings.HasPrefix(authHeader, "Bearer ") {
-					logger.Debug("No valid Bearer token found, proceeding without token exchange")
-					next.ServeHTTP(w, r)
-					return
-				}
-
-				subjectToken := strings.TrimPrefix(authHeader, "Bearer ")
-				if subjectToken == "" {
-					logger.Debug("Empty Bearer token, proceeding without token exchange")
+				subjectToken, err := auth.ExtractBearerToken(r)
+				if err != nil {
+					logger.Debugf("No valid Bearer token found (%v), proceeding without token exchange", err)
 					next.ServeHTTP(w, r)
 					return
 				}

pkg/auth/utils.go

@@ -3,6 +3,7 @@ package auth
 
 import (
 	"context"
+	"errors"
 	"net/http"
 	"os/user"
 	"strings"
@@ -12,6 +13,52 @@ import (
 	"github.com/stacklok/toolhive/pkg/logger"
 )
 
+// bearerTokenType defines the expected token type for Bearer authentication.
+const bearerTokenType = "Bearer"
+
+// Common Bearer token extraction errors
+var (
+	ErrAuthHeaderMissing       = errors.New("authorization header required")
+	ErrInvalidAuthHeaderFormat = errors.New("invalid authorization header format, expected 'Bearer <token>'")
+	ErrEmptyBearerToken        = errors.New("empty token in authorization header")
+)
+
+// ExtractBearerToken extracts and validates a Bearer token from the Authorization header.
+// It performs the following validations:
+//  1. Verifies the Authorization header is present
+//  2. Checks for the "Bearer " prefix (case-sensitive per RFC 6750)
+//  3. Ensures the token is not empty after removing the prefix
+//
+// The function returns the token string (without "Bearer " prefix) and any validation error.
+// Callers are responsible for further token validation (JWT parsing, introspection, etc.)
+// and for converting errors to appropriate HTTP responses.
+//
+// This function implements RFC 6750 Section 2.1 (Bearer Token Authorization Header).
+// See: https://datatracker.ietf.org/doc/html/rfc6750#section-2.1
+func ExtractBearerToken(r *http.Request) (string, error) {
+	// Get the Authorization header
+	authHeader := r.Header.Get("Authorization")
+	if authHeader == "" {
+		return "", ErrAuthHeaderMissing
+	}
+
+	// Check for the Bearer prefix (case-sensitive per RFC 6750)
+	bearerPrefix := bearerTokenType + " "
+	if !strings.HasPrefix(authHeader, bearerPrefix) {
+		return "", ErrInvalidAuthHeaderFormat
+	}
+
+	// Extract the token
+	tokenString := strings.TrimPrefix(authHeader, bearerPrefix)
+
+	// Check for empty token (handles "Bearer " with no token or only whitespace)
+	if strings.TrimSpace(tokenString) == "" {
+		return "", ErrEmptyBearerToken
+	}
+
+	return tokenString, nil
+}
+
 // GetClaimsFromContext retrieves the claims from the request context.
 // This is a helper function that can be used by authorization policies
 // to access the claims regardless of which middleware was used (JWT, anonymous, or local).

pkg/auth/utils_test.go

@@ -2,6 +2,7 @@ package auth
 
 import (
 	"context"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -13,6 +14,97 @@ import (
 	"github.com/stacklok/toolhive/pkg/logger"
 )
 
+func TestExtractBearerToken(t *testing.T) {
+	t.Parallel()
+
+	testCases := []struct {
+		name          string
+		authHeader    string
+		expectedToken string
+		expectedError error
+	}{
+		{
+			name:          "valid_bearer_token",
+			authHeader:    "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+			expectedToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+			expectedError: nil,
+		},
+		{
+			name:          "missing_authorization_header",
+			authHeader:    "",
+			expectedToken: "",
+			expectedError: ErrAuthHeaderMissing,
+		},
+		{
+			name:          "invalid_format_no_bearer_prefix",
+			authHeader:    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+			expectedToken: "",
+			expectedError: ErrInvalidAuthHeaderFormat,
+		},
+		{
+			name:          "lowercase_bearer",
+			authHeader:    "bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
+			expectedToken: "",
+			expectedError: ErrInvalidAuthHeaderFormat,
+		},
+		{
+			name:          "empty_token_after_prefix",
+			authHeader:    "Bearer ",
+			expectedToken: "",
+			expectedError: ErrEmptyBearerToken,
+		},
+		{
+			name:          "empty_token_with_trailing_spaces",
+			authHeader:    "Bearer    ",
+			expectedToken: "",
+			expectedError: ErrEmptyBearerToken,
+		},
+		{
+			name:          "token_with_spaces_valid_per_rfc",
+			authHeader:    "Bearer token with spaces",
+			expectedToken: "token with spaces",
+			expectedError: nil,
+		},
+		{
+			name:          "basic_auth_instead_of_bearer",
+			authHeader:    "Basic dXNlcjpwYXNz",
+			expectedToken: "",
+			expectedError: ErrInvalidAuthHeaderFormat,
+		},
+		{
+			name:          "token_with_special_characters",
+			authHeader:    "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0In0.abc-def_ghi",
+			expectedToken: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0In0.abc-def_ghi",
+			expectedError: nil,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Create a test request with the authorization header
+			req := httptest.NewRequest("GET", "/test", nil)
+			if tc.authHeader != "" {
+				req.Header.Set("Authorization", tc.authHeader)
+			}
+
+			// Extract the bearer token
+			token, err := ExtractBearerToken(req)
+
+			// Check the error
+			if tc.expectedError != nil {
+				require.Error(t, err)
+				assert.True(t, errors.Is(err, tc.expectedError), "Expected error %v, got %v", tc.expectedError, err)
+				assert.Empty(t, token)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tc.expectedToken, token)
+			}
+		})
+	}
+}
+
 func TestGetClaimsFromContext(t *testing.T) {
 	t.Parallel()
 	// Test with claims in context