Implement core authentication infrastructure for vMCP (#2393)

* Add context helpers for Identity propagation in vmcp auth

Adds several context-related helpers that will be used to propagate
Identity through vMCP.

Related: #2377

* Add OIDC incoming authenticator for vmcp

Implement IncomingAuthenticator interface using existing TokenValidator from
pkg/auth. This adapter validates JWT tokens from clients connecting to the
Virtual MCP Server and extracts identity information.

Related: #2377

* Add a registry of outgoing auth strategies with a stub of AuthenticateRequest()

Implement OutgoingAuthenticator interface with pluggable authentication
strategies for backend MCP server connections.

The actual strategies will be implemented in a follow-up commit.

Fixes: #2377

* Add token redaction to Identity serialization

Implement String() and MarshalJSON() methods on the Identity struct to
prevent accidental token leakage when logging or serializing identities.

* Document Groups field design decision

Add concise documentation explaining why Identity.Groups is intentionally
not populated by OIDCIncomingAuthenticator. This clarifies that group
extraction is an authorization concern handled via the Claims map, as
different OIDC providers use different claim names.

* Document thread-safety guarantees for outgoing auth

Add explicit documentation that RegisterStrategy and AuthenticateRequest
are safe for concurrent use, and that Strategy implementations must be
thread-safe.

* Add metadata validation to AuthenticateRequest

Call strategy.Validate() before strategy.Authenticate() to catch invalid
or malicious metadata early. This prevents type confusion, injection
attacks, and panics from invalid metadata in strategy implementations.

Changes:
- Add Validate() call in AuthenticateRequest()
- Proper error wrapping with strategy name
- Add test verifying validation is enforced
- Update existing tests to expect Validate() calls

* Add Claims-to-Identity conversion for vMCP auth

Implement new authentication layer that converts JWT claims from
pkg/auth.TokenValidator to vMCP's Identity domain type.

Changes:
- Add ClaimsToIdentity() to convert JWT claims to Identity struct
  * Validates required 'sub' claim per OIDC Core 1.0 § 5.1
  * Preserves original Bearer token for passthrough scenarios
  * Intentionally does not populate Groups field (stays in Claims)
- Add IdentityMiddleware() to apply conversion in HTTP middleware chain
  * Runs after TokenValidator.Middleware() which stores Claims
  * Passes through unauthenticated requests unchanged
- Add NewOIDCAuthMiddleware() factory helper
  * Composes TokenValidator + IdentityMiddleware into single chain
  * Returns authInfo handler for OIDC discovery endpoint
- Add comprehensive test coverage for conversion logic

This establishes the foundation for simplified vMCP authentication that
reuses pkg/auth.GetAuthenticationMiddleware() instead of duplicating
token validation logic.

Affected components:
- pkg/vmcp/auth (new files)

* Add authentication middleware support to vMCP server

Update server configuration and routing to support optional authentication
middleware for MCP endpoints while keeping health endpoints unauthenticated.

* Wire OIDC authentication in vMCP serve command

Integrate NewOIDCAuthMiddleware() into the serve command to enable
authentication based on configuration.

* Remove old OIDCIncomingAuthenticator implementation

Remove the now-unused OIDCIncomingAuthenticator that wrapped
TokenValidator, along with its interfaces and tests. This code
is replaced by the simpler NewOIDCAuthMiddleware() helper that
directly composes pkg/auth middleware with IdentityMiddleware.

* Add reusable well-known OAuth discovery handler

Create NewWellKnownHandler() in pkg/auth to provide RFC 9728 compliant
routing for /.well-known/oauth-protected-resource endpoints.

This fixes a bug where vMCP server only matched exact paths, causing
requests to subpaths like /.well-known/oauth-protected-resource/mcp
to fall through to authenticated routes and return 401.

* Use NewWellKnownHandler in vMCP and transparent proxy

Replace inline well-known handler implementations with the reusable
auth.NewWellKnownHandler() to eliminate code duplication.

This fixes a bug in vMCP server where only the exact path
/.well-known/oauth-protected-resource was registered, causing requests
to subpaths (e.g., /mcp) to fall through to authenticated routes and
return 401 instead of discovery metadata.

The reusable handler ensures consistent behavior across both components
and maintains the requirement that discovery endpoints remain
unauthenticated.

* Add Resource parameter to vMCP OIDC config

Add support for OAuth 2.0 resource indicators (RFC 8707) in vMCP
incoming authentication configuration.

The Resource field is used in WWW-Authenticate headers and OAuth
discovery metadata per RFC 9728. When not specified, it defaults to
the Audience value for backward compatibility.

This allows operators to explicitly configure the resource identifier
that appears in 401 responses, separate from the token audience claim
validation.

* Pass Resource parameter to OIDC auth middleware

Wire the Resource field from config through to the TokenValidator by
using it as the ResourceURL in TokenValidatorConfig.

The ResourceURL is used in WWW-Authenticate challenge headers when
authentication fails. This allows operators to specify a different
resource identifier than the audience claim being validated.

* Simplify Identity.String

Author: jhrozek

cmd/vmcp/app/commands.go

@@ -12,6 +12,7 @@ import (
 	"github.com/stacklok/toolhive/pkg/groups"
 	"github.com/stacklok/toolhive/pkg/logger"
 	"github.com/stacklok/toolhive/pkg/vmcp/aggregator"
+	vmcpauth "github.com/stacklok/toolhive/pkg/vmcp/auth"
 	vmcpclient "github.com/stacklok/toolhive/pkg/vmcp/client"
 	"github.com/stacklok/toolhive/pkg/vmcp/config"
 	vmcprouter "github.com/stacklok/toolhive/pkg/vmcp/router"
@@ -260,12 +261,24 @@ func runServe(cmd *cobra.Command, _ []string) error {
 	// Create router
 	rtr := vmcprouter.NewDefaultRouter()
 
+	// Setup authentication middleware
+	logger.Infof("Setting up incoming authentication (type: %s)", cfg.IncomingAuth.Type)
+
+	authMiddleware, authInfoHandler, err := vmcpauth.NewIncomingAuthMiddleware(ctx, cfg.IncomingAuth)
+	if err != nil {
+		return fmt.Errorf("failed to create authentication middleware: %w", err)
+	}
+
+	logger.Infof("Incoming authentication configured: %s", cfg.IncomingAuth.Type)
+
 	// Create server configuration
 	serverCfg := &vmcpserver.Config{
-		Name:    cfg.Name,
-		Version: getVersion(),
-		Host:    "127.0.0.1", // TODO: Make configurable
-		Port:    4483,        // TODO: Make configurable
+		Name:            cfg.Name,
+		Version:         getVersion(),
+		Host:            "127.0.0.1", // TODO: Make configurable
+		Port:            4483,        // TODO: Make configurable
+		AuthMiddleware:  authMiddleware,
+		AuthInfoHandler: authInfoHandler,
 	}
 
 	// Create server

cmd/vmcp/example-config.yaml

@@ -30,6 +30,7 @@ incoming_auth:
   #   client_id: "vmcp-client"
   #   client_secret_env: "VMCP_CLIENT_SECRET"
   #   audience: "vmcp"
+  #   resource: "http://localhost:4483/mcp"
   #   scopes: ["openid", "profile", "email"]
 
 # ===== OUTGOING AUTHENTICATION (Virtual MCP → Backends) =====

pkg/auth/well_known.go

@@ -0,0 +1,60 @@
+// Package auth provides authentication and authorization utilities.
+package auth
+
+import (
+	"net/http"
+	"strings"
+)
+
+// WellKnownOAuthResourcePath is the RFC 9728 standard path for OAuth Protected Resource metadata.
+// Per RFC 9728 Section 3, this endpoint and any subpaths under it should be accessible
+// without authentication to enable OIDC/OAuth discovery.
+//
+// Example valid paths:
+//   - /.well-known/oauth-protected-resource
+//   - /.well-known/oauth-protected-resource/mcp
+//   - /.well-known/oauth-protected-resource/v1/metadata
+const WellKnownOAuthResourcePath = "/.well-known/oauth-protected-resource"
+
+// NewWellKnownHandler creates an HTTP handler that routes requests under the
+// /.well-known/ path space to the appropriate handler.
+//
+// Per RFC 9728, the /.well-known/oauth-protected-resource endpoint and any subpaths
+// under it must be accessible without authentication. This handler ensures proper
+// routing of discovery requests while returning 404 for unknown paths.
+//
+// If authInfoHandler is nil, this function returns nil (no handler registration needed).
+//
+// Usage:
+//
+//	authInfoHandler := auth.NewAuthInfoHandler(issuer, jwksURL, resourceURL, scopes)
+//	wellKnownHandler := auth.NewWellKnownHandler(authInfoHandler)
+//	if wellKnownHandler != nil {
+//	    mux.Handle("/.well-known/", wellKnownHandler)
+//	}
+//
+// This handler matches:
+//   - /.well-known/oauth-protected-resource (exact)
+//   - /.well-known/oauth-protected-resource/* (subpaths)
+//
+// Returns 404 for other /.well-known/* paths.
+func NewWellKnownHandler(authInfoHandler http.Handler) http.Handler {
+	if authInfoHandler == nil {
+		return nil
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// RFC 9728: Match /.well-known/oauth-protected-resource and any subpaths
+		// Examples:
+		//   ✓ /.well-known/oauth-protected-resource
+		//   ✓ /.well-known/oauth-protected-resource/mcp
+		//   ✗ /.well-known/other-endpoint
+		if strings.HasPrefix(r.URL.Path, WellKnownOAuthResourcePath) {
+			authInfoHandler.ServeHTTP(w, r)
+			return
+		}
+
+		// Unknown .well-known path
+		http.NotFound(w, r)
+	})
+}

pkg/auth/well_known_test.go

@@ -0,0 +1,281 @@
+package auth
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewWellKnownHandler(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name            string
+		authInfoHandler http.Handler
+		expectedNil     bool
+		testRequests    []testRequest
+	}{
+		{
+			name:            "nil authInfoHandler returns nil",
+			authInfoHandler: nil,
+			expectedNil:     true,
+		},
+		{
+			name: "exact path /.well-known/oauth-protected-resource routes to authInfoHandler",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("auth-info"))
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:           "/.well-known/oauth-protected-resource",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "auth-info",
+				},
+			},
+		},
+		{
+			name: "subpath /.well-known/oauth-protected-resource/mcp routes to authInfoHandler",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("auth-info-mcp"))
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:           "/.well-known/oauth-protected-resource/mcp",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "auth-info-mcp",
+				},
+			},
+		},
+		{
+			name: "subpath /.well-known/oauth-protected-resource/v1/metadata routes to authInfoHandler",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("auth-info-v1"))
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:           "/.well-known/oauth-protected-resource/v1/metadata",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "auth-info-v1",
+				},
+			},
+		},
+		{
+			name: "other .well-known paths return 404",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("should-not-reach"))
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:           "/.well-known/openid-configuration",
+					expectedStatus: http.StatusNotFound,
+					expectedBody:   "404 page not found\n",
+				},
+				{
+					path:           "/.well-known/other",
+					expectedStatus: http.StatusNotFound,
+					expectedBody:   "404 page not found\n",
+				},
+			},
+		},
+		{
+			name: "RFC 9728 compliance - all oauth-protected-resource paths work",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte("discovered"))
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:           "/.well-known/oauth-protected-resource",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "discovered",
+				},
+				{
+					path:           "/.well-known/oauth-protected-resource/",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "discovered",
+				},
+				{
+					path:           "/.well-known/oauth-protected-resource/any/deep/path",
+					expectedStatus: http.StatusOK,
+					expectedBody:   "discovered",
+				},
+			},
+		},
+		{
+			name: "handler preserves request context and headers",
+			authInfoHandler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				// Verify request is passed through correctly
+				if r.Header.Get("X-Test-Header") == "test-value" {
+					w.Header().Set("X-Response-Header", "response-value")
+					w.WriteHeader(http.StatusOK)
+					_, _ = w.Write([]byte("headers-ok"))
+				} else {
+					w.WriteHeader(http.StatusBadRequest)
+				}
+			}),
+			expectedNil: false,
+			testRequests: []testRequest{
+				{
+					path:            "/.well-known/oauth-protected-resource",
+					headers:         map[string]string{"X-Test-Header": "test-value"},
+					expectedStatus:  http.StatusOK,
+					expectedBody:    "headers-ok",
+					expectedHeaders: map[string]string{"X-Response-Header": "response-value"},
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			handler := NewWellKnownHandler(tt.authInfoHandler)
+
+			if tt.expectedNil {
+				assert.Nil(t, handler, "expected nil handler")
+				return
+			}
+
+			require.NotNil(t, handler, "expected non-nil handler")
+
+			// Test each request scenario
+			for _, req := range tt.testRequests {
+				t.Run(req.path, func(t *testing.T) {
+					request := httptest.NewRequest(http.MethodGet, req.path, nil)
+
+					// Add test headers
+					for key, value := range req.headers {
+						request.Header.Set(key, value)
+					}
+
+					recorder := httptest.NewRecorder()
+					handler.ServeHTTP(recorder, request)
+
+					assert.Equal(t, req.expectedStatus, recorder.Code, "status code mismatch")
+					assert.Equal(t, req.expectedBody, recorder.Body.String(), "body mismatch")
+
+					// Check expected response headers
+					for key, value := range req.expectedHeaders {
+						assert.Equal(t, value, recorder.Header().Get(key), "header %s mismatch", key)
+					}
+				})
+			}
+		})
+	}
+}
+
+func TestWellKnownHandler_HTTPMethods(t *testing.T) {
+	t.Parallel()
+
+	authInfoHandler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		// Echo back the HTTP method
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(req.Method))
+	})
+
+	handler := NewWellKnownHandler(authInfoHandler)
+	require.NotNil(t, handler)
+
+	methods := []string{
+		http.MethodGet,
+		http.MethodPost,
+		http.MethodPut,
+		http.MethodDelete,
+		http.MethodPatch,
+		http.MethodOptions,
+	}
+
+	for _, method := range methods {
+		t.Run(method, func(t *testing.T) {
+			t.Parallel()
+
+			request := httptest.NewRequest(method, "/.well-known/oauth-protected-resource", nil)
+			recorder := httptest.NewRecorder()
+
+			handler.ServeHTTP(recorder, request)
+
+			assert.Equal(t, http.StatusOK, recorder.Code)
+			assert.Equal(t, method, recorder.Body.String())
+		})
+	}
+}
+
+func TestWellKnownHandler_EdgeCases(t *testing.T) {
+	t.Parallel()
+
+	authInfoHandler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("ok"))
+	})
+
+	handler := NewWellKnownHandler(authInfoHandler)
+	require.NotNil(t, handler)
+
+	tests := []struct {
+		name           string
+		path           string
+		expectedStatus int
+		expectedBody   string
+	}{
+		{
+			name:           "path with query parameters routes correctly",
+			path:           "/.well-known/oauth-protected-resource?format=json",
+			expectedStatus: http.StatusOK,
+			expectedBody:   "ok",
+		},
+		{
+			name:           "path with trailing slash routes correctly",
+			path:           "/.well-known/oauth-protected-resource/",
+			expectedStatus: http.StatusOK,
+			expectedBody:   "ok",
+		},
+		{
+			name:           "different .well-known path returns 404",
+			path:           "/.well-known/jwks.json", // Different endpoint
+			expectedStatus: http.StatusNotFound,
+			expectedBody:   "404 page not found\n",
+		},
+		{
+			name:           "path prefix match is not sufficient",
+			path:           "/.well-known/oauth", // Prefix but not full path
+			expectedStatus: http.StatusNotFound,
+			expectedBody:   "404 page not found\n",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			request := httptest.NewRequest(http.MethodGet, tt.path, nil)
+			recorder := httptest.NewRecorder()
+
+			handler.ServeHTTP(recorder, request)
+
+			assert.Equal(t, tt.expectedStatus, recorder.Code)
+			assert.Equal(t, tt.expectedBody, recorder.Body.String())
+		})
+	}
+}
+
+// testRequest defines a test request scenario
+type testRequest struct {
+	path            string
+	headers         map[string]string
+	expectedStatus  int
+	expectedBody    string
+	expectedHeaders map[string]string
+}