Support RFC 9728 well-known paths with resource components (#2197)

The previous implementation used exact path matching for the well-known
OAuth protected resource metadata endpoint, which only accepted:
  /.well-known/oauth-protected-resource

This broke RFC 9728 Section 3.1 compliance for resources with path
components. When a resource is identified as "https://server.com/mcp",
clients must fetch metadata from:
  /.well-known/oauth-protected-resource/mcp

But the exact match would return 404, preventing proper OAuth discovery
for MCP servers with path-based resource identifiers.

Changed to prefix matching to support both:
- /.well-known/oauth-protected-resource (base path)
- /.well-known/oauth-protected-resource/mcp (with resource component)
- /.well-known/oauth-protected-resource/resource1 (multi-tenant)

This enables multi-tenant hosting configurations as specified in
RFC 9728 and ensures OAuth discovery works correctly for MCP servers
regardless of their path structure.

Note: The current implementation accepts all paths under the prefix
(e.g., /.well-known/oauth-protected-resource/*). In the future, this
could be tightened by having NewAuthInfoHandler parse the request path,
extract the resource component, and validate it matches the resourceURL
path before returning metadata. This would enforce stricter path
matching while maintaining RFC 9728 compliance.

Author: jhrozek

pkg/transport/proxy/transparent/transparent_proxy.go

@@ -362,15 +362,18 @@ func (p *TransparentProxy) Start(ctx context.Context) error {
 	if p.authInfoHandler != nil {
 		// Create a handler that routes .well-known requests
 		wellKnownHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			switch r.URL.Path {
-			case "/.well-known/oauth-protected-resource":
+			// Per RFC 9728, match /.well-known/oauth-protected-resource and any subpaths
+			// e.g., /.well-known/oauth-protected-resource/mcp
+			if strings.HasPrefix(r.URL.Path, "/.well-known/oauth-protected-resource") {
 				p.authInfoHandler.ServeHTTP(w, r)
-			default:
+			} else {
 				http.NotFound(w, r)
 			}
 		})
 		mux.Handle("/.well-known/", wellKnownHandler)
 		logger.Info("Well-known discovery endpoints enabled at /.well-known/ (no middlewares)")
+	} else {
+		logger.Info("No auth info handler provided; skipping /.well-known/ endpoint")
 	}
 
 	// Create the server

pkg/transport/proxy/transparent/transparent_test.go

@@ -199,3 +199,155 @@ func TestTracePropagationHeaders(t *testing.T) {
 	// Verify the request still works normally
 	assert.Equal(t, http.StatusOK, recorder.Code)
 }
+
+func TestWellKnownPathPrefixMatching(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name               string
+		requestPath        string
+		expectedStatusCode int
+		shouldCallHandler  bool
+		description        string
+	}{
+		{
+			name:               "base path without resource component",
+			requestPath:        "/.well-known/oauth-protected-resource",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "RFC 9728 base path should route to authInfoHandler",
+		},
+		{
+			name:               "path with single resource component",
+			requestPath:        "/.well-known/oauth-protected-resource/mcp",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Path with /mcp resource component should route to authInfoHandler",
+		},
+		{
+			name:               "path with multiple resource components",
+			requestPath:        "/.well-known/oauth-protected-resource/api/v1/service",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Path with multiple resource components should route to authInfoHandler",
+		},
+		{
+			name:               "path with different resource name",
+			requestPath:        "/.well-known/oauth-protected-resource/resource1",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Path with arbitrary resource component should route to authInfoHandler",
+		},
+		{
+			name:               "non-matching well-known path",
+			requestPath:        "/.well-known/other-endpoint",
+			expectedStatusCode: http.StatusNotFound,
+			shouldCallHandler:  false,
+			description:        "Different well-known endpoint should return 404",
+		},
+		{
+			name:               "path without leading dot",
+			requestPath:        "/well-known/oauth-protected-resource",
+			expectedStatusCode: http.StatusNotFound,
+			shouldCallHandler:  false,
+			description:        "Path without leading dot should return 404",
+		},
+		{
+			name:               "similar but non-matching path with suffix",
+			requestPath:        "/.well-known/oauth-protected-resource-other",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Per RFC 9728, prefix matching means this should match",
+		},
+		{
+			name:               "path with trailing slash",
+			requestPath:        "/.well-known/oauth-protected-resource/",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Path with trailing slash should route to authInfoHandler",
+		},
+		{
+			name:               "path with query parameters",
+			requestPath:        "/.well-known/oauth-protected-resource?param=value",
+			expectedStatusCode: http.StatusOK,
+			shouldCallHandler:  true,
+			description:        "Path with query parameters should route to authInfoHandler",
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt // capture range variable
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			// Track whether the auth info handler was called
+			handlerCalled := false
+			authHandler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+				handlerCalled = true
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(`{"authorized": true}`))
+			})
+
+			// Create the well-known handler directly (same logic as in transparent_proxy.go)
+			wellKnownHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				// Per RFC 9728, match /.well-known/oauth-protected-resource and any subpaths
+				// e.g., /.well-known/oauth-protected-resource/mcp
+				if strings.HasPrefix(r.URL.Path, "/.well-known/oauth-protected-resource") {
+					authHandler.ServeHTTP(w, r)
+				} else {
+					http.NotFound(w, r)
+				}
+			})
+
+			// Create a mux and register the well-known handler (same as in transparent_proxy.go)
+			mux := http.NewServeMux()
+			mux.Handle("/.well-known/", wellKnownHandler)
+
+			// Create a test request
+			req := httptest.NewRequest("GET", tt.requestPath, nil)
+			recorder := httptest.NewRecorder()
+
+			// Serve the request through the mux
+			mux.ServeHTTP(recorder, req)
+
+			// Verify status code
+			assert.Equal(t, tt.expectedStatusCode, recorder.Code,
+				"%s: expected status %d but got %d", tt.description, tt.expectedStatusCode, recorder.Code)
+
+			// Verify whether handler was called
+			assert.Equal(t, tt.shouldCallHandler, handlerCalled,
+				"%s: handler call mismatch (expected=%v, actual=%v)", tt.description, tt.shouldCallHandler, handlerCalled)
+
+			// For successful cases, verify response body
+			if tt.shouldCallHandler && recorder.Code == http.StatusOK {
+				assert.Contains(t, recorder.Body.String(), "authorized",
+					"%s: expected response body to contain auth info", tt.description)
+			}
+		})
+	}
+}
+
+func TestWellKnownPathWithoutAuthHandler(t *testing.T) {
+	t.Parallel()
+
+	// Test that when authInfoHandler is nil, the well-known route is not registered
+	// Create a mux without registering the well-known handler (simulating authInfoHandler == nil case)
+	mux := http.NewServeMux()
+
+	// Only register a default handler that returns 404 for everything
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		http.NotFound(w, r)
+	})
+
+	// Create a test request to well-known path
+	req := httptest.NewRequest("GET", "/.well-known/oauth-protected-resource", nil)
+	recorder := httptest.NewRecorder()
+
+	// Serve the request
+	mux.ServeHTTP(recorder, req)
+
+	// When no auth handler is provided, the well-known route should not be registered
+	// The request should fall through to the default handler which returns 404
+	assert.Equal(t, http.StatusNotFound, recorder.Code,
+		"Without auth handler, well-known path should return 404")
+}