From 44dafe34792c276c7a5eb31876af456d89175601 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Thu, 27 Aug 2026 12:08:46 +0300 Subject: [PATCH 1/2] fix(oauth): make the redirect_uri pin actually reachable, diagnosable and validated MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #1069 made the per-server `oauth.redirect_uri` field load-bearing for the first time. QA of the merged change found five defects on that newly-live path. - An `::1` pin was accepted, blessed by a test and advertised in the docs, but the callback listener was hard-coded to `net.Listen("tcp", "127.0.0.1:PORT")`. The provider was handed a `[::1]` URL nothing listened on, so the browser redirect was refused and the login hung to the callback timeout. The pin now carries its host: `localhost` and `127.0.0.1` bind IPv4, `::1` binds IPv6. - Every log line in `createOAuthConfigInternal` and in the callback-server manager went to `zap.L()`, which this repo never replaces, so all of it was discarded — including #1069's new "fail loudly" errors, and the docs claim that they appear in the logs. The connection's own logger is threaded in. - A malformed pin was a permanent connect failure reported as "failed to create OAuth config - server may not support OAuth", which never names the culprit. The parse error and the "pinned port unavailable" reason now reach the user-visible error, and the write surfaces (REST config API, MCP `upstream_servers`) reject a bad value up front. The boot path deliberately does not: a value already on disk must not stop the daemon from starting. The Gemini importer no longer copies a callback URL mcpproxy cannot honor. - `StartCallbackServer` returned a cached server without honoring the requested port, so a pinned reconnect after a timed-out flow failed against a free port. It now re-binds — but only when the cached server has no waiter parked on it, preserving the invariant #1068 established. - The pinned path skipped the stored-credential read, so Spec-022 legacy cleanup never ran and a DCR registration issued against a different port was reused forever. The read always runs now; only the port choice short-circuits. Docs: correct the wildcard-callback advice in mcp-go-oauth.md (GitHub OAuth Apps reject `http://127.0.0.1:*`), drop the non-existent `redirect_port` field from the callback-mismatch error page, fix the `:8080` example that collided with mcpproxy's own listener, and resolve the port-allocation contradiction. Follow-up to #1069. Refs #975, #1066. --- docs/configuration.md | 43 +- docs/errors/MCPX_OAUTH_CALLBACK_MISMATCH.md | 20 +- docs/features/oauth-authentication.md | 2 +- docs/mcp-go-oauth.md | 66 +-- internal/config/config.go | 55 ++- .../oauth_redirect_uri_validation_test.go | 162 +++++++ internal/config/oauth_validation.go | 100 ++++ internal/configimport/mapper.go | 12 + internal/configimport/mapper_test.go | 47 +- internal/oauth/config.go | 446 +++++++++++++----- internal/oauth/redirect_uri_followup_test.go | 399 ++++++++++++++++ internal/server/mcp.go | 8 + internal/upstream/core/client.go | 27 ++ internal/upstream/core/connection_oauth.go | 48 +- 14 files changed, 1262 insertions(+), 173 deletions(-) create mode 100644 internal/config/oauth_redirect_uri_validation_test.go create mode 100644 internal/oauth/redirect_uri_followup_test.go diff --git a/docs/configuration.md b/docs/configuration.md index 855960dc2..18b89f6d3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -529,7 +529,7 @@ explicitly to one of `http`, `sse`, or `streamable-http`. "oauth": { "client_id": "your-client-id", "client_secret": "secret-reference", - "redirect_uri": "http://localhost:8080/oauth/callback", + "redirect_uri": "http://127.0.0.1:54108/oauth/callback", "scopes": ["repo", "user"], "pkce_enabled": true } @@ -546,10 +546,12 @@ explicitly to one of `http`, `sse`, or `streamable-http`. #### Pinning the callback port with `redirect_uri` -By default mcpproxy allocates a fresh loopback port for the OAuth callback on -every login. Some providers — notably GitHub OAuth Apps — require the callback +By default mcpproxy asks the OS for a free loopback port on the first OAuth +login, then persists that port and tries to reuse it. If the saved port is taken +next time, a different one is allocated — so the callback URL is not guaranteed +to stay put. Some providers — notably GitHub OAuth Apps — require the callback URL to match the registered one **exactly** and reject wildcards, so the port -must not move. +must not move at all. Set `redirect_uri` to pin it. mcpproxy then binds that exact port and sends that exact string to the provider as `redirect_uri`: @@ -565,13 +567,40 @@ exact string to the provider as `redirect_uri`: The value must be an RFC 8252 loopback redirect: `http` scheme, a loopback host (`127.0.0.1`, `localhost` or `::1`), an explicit port, and the -`/oauth/callback` path. A malformed value, or a pinned port that is already in -use, fails the login with an explicit error in the logs rather than silently -falling back to a random port. Register the same URL with the provider. +`/oauth/callback` path. Register the same URL with the provider. + +Prefer `127.0.0.1`. `localhost` is accepted, and the string is sent to the +provider exactly as written, but the listener binds `127.0.0.1` — on a host +whose browser resolves `localhost` to `::1` without falling back, the redirect +would reach a closed port. Write `http://[::1]:PORT/oauth/callback` if you want +the IPv6 loopback; mcpproxy then binds `::1` itself. + +A malformed value, or a pinned port that is already in use, fails the login with +an explicit error rather than silently falling back to a random port. The error +appears in three places: + +- the connection error and the server's `health.detail` (it names + `oauth.redirect_uri` and the reason), +- `mcpproxy upstream logs ` (the per-server log), and +- the main log (`~/Library/Logs/mcpproxy/main.log` on macOS, + `~/.mcpproxy/logs/main.log` on Linux), under the `oauth` logger name. + +A malformed value is also rejected up front by the write surfaces — the REST +config API (`POST /api/v1/config/validate`, `POST /api/v1/config/apply`, +`PATCH /api/v1/config`), the Web UI that calls them, and the MCP +`upstream_servers` tool. Hand-editing `mcp_config.json` bypasses that check by +design: a bad value already on disk must not stop the daemon from booting, so it +is reported at connect time instead. When `redirect_uri` is not set, mcpproxy persists the port used by the first successful login and reuses it for subsequent logins. +If the server previously logged in without a pin, its client registration was +issued through Dynamic Client Registration against that old port. Adding a +`redirect_uri` with a different port clears that registration automatically so +the next login re-registers against the pinned URL; a statically configured +`client_id` is never cleared. + See [OAuth Documentation](mcp-go-oauth.md) for complete details. --- diff --git a/docs/errors/MCPX_OAUTH_CALLBACK_MISMATCH.md b/docs/errors/MCPX_OAUTH_CALLBACK_MISMATCH.md index 36d4a6367..fad2a200d 100644 --- a/docs/errors/MCPX_OAUTH_CALLBACK_MISMATCH.md +++ b/docs/errors/MCPX_OAUTH_CALLBACK_MISMATCH.md @@ -35,25 +35,31 @@ persisted port). Add that exact URI to your OAuth client's allowed redirect URIs in the provider's developer console. For most providers wildcards aren't allowed; you'll need to register the exact -port. mcpproxy persists the port in the upstream config — see -[`oauth_redirect_port`](../configuration/upstream-servers.md) — so you can -register a stable URI. +port. When `oauth.redirect_uri` is not set, mcpproxy allocates a loopback port +on the first login and persists it, reusing it on subsequent logins — so the +callback URL is usually stable, but it is not guaranteed if that port is taken +later. -### Re-pin the redirect port +### Pin the redirect URI -If you previously used a different port and want to restore it, set -`oauth_redirect_port` explicitly: +If the provider requires an exact callback URL, pin it with `oauth.redirect_uri`: ```json { "name": "my-server", "oauth": { "client_id": "...", - "redirect_port": 53412 + "redirect_uri": "http://127.0.0.1:53412/oauth/callback" } } ``` +mcpproxy binds that exact port and sends that exact string to the provider. The +value must be an RFC 8252 loopback redirect: `http` scheme, a loopback host, an +explicit port, and the `/oauth/callback` path. A malformed value, or a pinned +port already in use, fails the login with an explicit error naming +`redirect_uri` rather than falling back to a random port. + Then re-register that exact URI on the provider side. ### If a reverse proxy is in front diff --git a/docs/features/oauth-authentication.md b/docs/features/oauth-authentication.md index 4d230b6ec..0adeaae9b 100644 --- a/docs/features/oauth-authentication.md +++ b/docs/features/oauth-authentication.md @@ -46,7 +46,7 @@ OAuth authentication is used when connecting to MCP servers that require authori |--------|------|-------------| | `client_id` | string | OAuth client identifier (uses Dynamic Client Registration if empty) | | `client_secret` | string | OAuth client secret (optional, can reference secure storage) | -| `redirect_uri` | string | OAuth redirect URI (auto-generated if not provided) | +| `redirect_uri` | string | Pins the loopback callback URL. Must be `http`, a loopback host, an explicit port and the `/oauth/callback` path (e.g. `http://127.0.0.1:54108/oauth/callback`); register the identical URL with the provider. Omit it to let mcpproxy allocate a port and persist it. See [Pinning the callback port](../configuration.md#pinning-the-callback-port-with-redirect_uri). | | `scopes` | array | Requested OAuth scopes | | `pkce_enabled` | boolean | PKCE is always enabled for security; this flag is currently ignored | | `extra_params` | object | Additional authorization parameters (e.g., RFC 8707 resource) | diff --git a/docs/mcp-go-oauth.md b/docs/mcp-go-oauth.md index 570bbbe27..31b7cbfc5 100644 --- a/docs/mcp-go-oauth.md +++ b/docs/mcp-go-oauth.md @@ -26,7 +26,7 @@ RFC 7591-compliant DCR enables MCP clients to self-register with authorization s To prevent malicious registrations, MCP servers should require initial access tokens during registration, issued through out-of-band mechanisms. Metadata validation must enforce: - Scope restrictions limiting client permissions -- Redirect URI pattern whitelisting +- Redirect URI pattern whitelisting - Software statement assertions for authenticity The `godoc-mcp` server exemplifies this by binding client registrations to PKCE-enhanced OAuth flows, ensuring only user-authorized agents gain access. @@ -51,7 +51,7 @@ Post-registration, the client uses issued credentials for subsequent OAuth flows For local callback servers, Go implementations should: 1. Bind to `localhost:0` to auto-assign ports -2. Pass the derived port to redirect URIs +2. Pass the derived port to redirect URIs 3. Handle OS port conflicts via retries As RFC 8252 notes, servers must accept any loopback port, requiring MCP servers to validate URIs using pattern matching (e.g., `http://127.0.0.1:*`) rather than exact matches. @@ -86,7 +86,7 @@ This dynamically assigns ports, passing the URI to OAuth requests while handling RFC 8414 defines the `/.well-known/oauth-authorization-server` endpoint for disclosing OAuth configuration. MCP servers must publish: - `authorization_endpoint` -- `token_endpoint` +- `token_endpoint` - `registration_endpoint` - `jwks_uri` @@ -203,16 +203,26 @@ This enables runtime onboarding of AI agents. **Problem**: Authorization servers reject dynamically generated URIs. -**Solution**: -- Configure auth servers with wildcard redirect patterns (`http://127.0.0.1:*`) -- Use Cloudflare Workers for fixed-domain callbacks +**Solution** depends on what the provider accepts: + +- Providers that allow a loopback wildcard or prefix match (some self-hosted + authorization servers, and the pattern RFC 8252 §7.3 recommends) can register + `http://127.0.0.1:*` and let mcpproxy allocate a port per login. +- Providers that require an **exact** callback URL — GitHub OAuth Apps among + them — reject wildcards outright. For those, pin the port with the per-server + `oauth.redirect_uri` setting and register that exact string with the provider. + See [Pinning the callback port](configuration.md#pinning-the-callback-port-with-redirect_uri). +- Use Cloudflare Workers for fixed-domain callbacks. -**Go Code**: +**Go Code** (authorization-server side, only for servers that permit wildcards): ```go // Auth server config AllowedRedirectURIs: []string{"http://127.0.0.1:*", "http://[::1]:*"} ``` +> Do not assume a wildcard registration will work against a public provider — +> verify it in that provider's developer console first. + ### 7.2 Token Management Failures **Problem**: Access token expiration disrupts MCP sessions. @@ -292,19 +302,19 @@ func (m *CallbackServerManager) StartCallbackServer(serverName string) (*Callbac if err != nil { return nil, fmt.Errorf("failed to allocate dynamic port: %w", err) } - + // Extract port and create redirect URI addr := listener.Addr().(*net.TCPAddr) port := addr.Port redirectURI := fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", port) - + // Create dedicated HTTP server for this callback mux := http.NewServeMux() server := &http.Server{ Addr: fmt.Sprintf("127.0.0.1:%d", port), Handler: mux, } - + // Start server with proper callback handling callbackServer := &CallbackServer{ Port: port, @@ -313,13 +323,13 @@ func (m *CallbackServerManager) StartCallbackServer(serverName string) (*Callbac CallbackChan: make(chan map[string]string, 1), logger: m.logger.With(zap.String("server", serverName)), } - + // Set up callback handler mux.HandleFunc("/oauth/callback", callbackServer.handleCallback) - + // Start server on the allocated port go server.Serve(listener) - + return callbackServer, nil } ``` @@ -333,7 +343,7 @@ func CreateOAuthConfig(serverConfig *config.ServerConfig) *client.OAuthConfig { logger.Error("Failed to start OAuth callback server", zap.Error(err)) return nil } - + // Use the exact redirect URI in OAuth config return &client.OAuthConfig{ ClientID: "", // Dynamic Client Registration @@ -354,20 +364,20 @@ func (c *Client) handleOAuthFlow(oauthHandler *client.OAuthHandler) error { if err := oauthHandler.RegisterClient(ctx, "mcpproxy-go"); err != nil { return fmt.Errorf("DCR failed: %w", err) } - + // Step 2: Generate PKCE and state parameters codeVerifier, _ := client.GenerateCodeVerifier() codeChallenge := client.GenerateCodeChallenge(codeVerifier) state, _ := client.GenerateState() - + // Step 3: Get authorization URL (uses exact redirect URI from DCR) authURL, _ := oauthHandler.GetAuthorizationURL(ctx, state, codeChallenge) - + // Step 4: Open browser and wait for callback openBrowser(authURL) - + callbackServer, _ := oauth.GetGlobalCallbackManager().GetCallbackServer(c.config.Name) - + // Step 5: Wait for authorization code on our callback server select { case authParams := <-callbackServer.CallbackChan: @@ -375,8 +385,8 @@ func (c *Client) handleOAuthFlow(oauthHandler *client.OAuthHandler) error { if authParams["state"] != state { return fmt.Errorf("OAuth state mismatch") } - - return oauthHandler.ProcessAuthorizationResponse(ctx, + + return oauthHandler.ProcessAuthorizationResponse(ctx, authParams["code"], state, codeVerifier) case <-time.After(5 * time.Minute): return fmt.Errorf("OAuth authorization timeout") @@ -405,11 +415,11 @@ MCPProxy's implementation successfully handles: **Example Log Output:** ``` -2025-07-13T09:30:07.119 | INFO | OAuth callback server started successfully | +2025-07-13T09:30:07.119 | INFO | OAuth callback server started successfully | {"server": "cloudflare_autorag", "redirect_uri": "http://127.0.0.1:64020/oauth/callback", "port": 64020} -2025-07-13T09:30:07.119 | INFO | Opening browser for OAuth authentication | +2025-07-13T09:30:07.119 | INFO | Opening browser for OAuth authentication | {"auth_url": "https://autorag.mcp.cloudflare.com/oauth/authorize?...&redirect_uri=http%3A%2F%2F127.0.0.1%3A64020%2Foauth%2Fcallback..."} -2025-07-13T09:30:56.674 | INFO | OAuth callback received | +2025-07-13T09:30:56.674 | INFO | OAuth callback received | {"params": {"code": "...", "state": "..."}} 2025-07-13T09:30:57.507 | INFO | OAuth authentication completed successfully ``` @@ -421,7 +431,7 @@ The integration of OAuth 2.1 with MCP servers in Go requires strict adherence to ### ✅ **Successfully Implemented Solutions** 1. **Redirect URI Exact Matching**: **SOLVED** through our Global Callback Server Manager with dynamic port allocation and perfect URI consistency -2. **RFC 8252 Compliance**: **ACHIEVED** with `127.0.0.1` loopback interface and OS-assigned ephemeral ports +2. **RFC 8252 Compliance**: **ACHIEVED** with `127.0.0.1` loopback interface and OS-assigned ephemeral ports 3. **PKCE Security**: **IMPLEMENTED** with mandatory PKCE-S256 for all OAuth flows 4. **Dynamic Client Registration**: **WORKING** seamlessly with Cloudflare and other OAuth providers 5. **Token Management**: **AUTOMATED** with refresh token handling and secure storage @@ -430,7 +440,7 @@ The integration of OAuth 2.1 with MCP servers in Go requires strict adherence to **For Cloudflare MCP OAuth** (and other strict providers): - ✅ **Perfect URI matching** with callback server coordination -- ✅ **Zero port conflicts** through dedicated servers per OAuth flow +- ✅ **Zero port conflicts** through dedicated servers per OAuth flow - ✅ **Automatic retry** post-OAuth for seamless MCP connection - ✅ **Production-tested** with Cloudflare AutoRAG OAuth flows - ✅ **RFC 8252 compliant** with enhanced security @@ -459,8 +469,8 @@ MCPProxy's architecture enables future enhancements: MCPProxy serves as a **reference implementation** for OAuth 2.1 with MCP servers, demonstrating: - How to solve the critical redirect URI exact matching challenge -- Production-ready callback server coordination patterns +- Production-ready callback server coordination patterns - Seamless integration with the `mcp-go` library's OAuth capabilities - RFC 8252 compliance in real-world deployment scenarios -The patterns documented and implemented in MCPProxy establish **secure, scalable MCP-OAuth integrations** for Go-based AI agent ecosystems, successfully balancing user consent with operational security while meeting the strict requirements of modern OAuth providers like Cloudflare. \ No newline at end of file +The patterns documented and implemented in MCPProxy establish **secure, scalable MCP-OAuth integrations** for Go-based AI agent ecosystems, successfully balancing user consent with operational security while meeting the strict requirements of modern OAuth providers like Cloudflare. diff --git a/internal/config/config.go b/internal/config/config.go index 4e1ac5584..e4f9b4c96 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -2100,8 +2100,49 @@ func (v ValidationError) Error() string { return fmt.Sprintf("%s: %s", v.Field, v.Message) } -// ValidateDetailed performs detailed validation and returns all errors +// ValidateDetailed performs detailed validation and returns all errors. +// +// It is the shared gate for every *write* surface: the REST config API +// (POST /api/v1/config/validate, POST /api/v1/config/apply, PATCH /api/v1/config +// all funnel through Runtime.ValidateConfig / Runtime.ApplyConfig) and the MCP +// `upstream_servers` tool. Anything appended here is therefore rejected before +// it is persisted. +// +// The boot path is deliberately NOT this function — see Validate(), which runs +// validateDetailedCore() so that a pre-existing bad value on disk cannot brick +// a load that has nothing to do with the offending server. func (c *Config) ValidateDetailed() []ValidationError { + return append(c.validateDetailedCore(), c.oauthRedirectURIErrors()...) +} + +// oauthRedirectURIErrors reports every per-server `oauth.redirect_uri` that the +// loopback callback listener cannot honor. +// +// Kept separate from validateDetailedCore because the two callers want opposite +// behavior: a write surface must reject the value (it is a permanent connect +// failure otherwise, with an error that never names redirect_uri), while +// config.Load must tolerate one already on disk and let it fail loudly at +// connect time instead. +func (c *Config) oauthRedirectURIErrors() []ValidationError { + var errors []ValidationError + for i, server := range c.Servers { + if server == nil || server.OAuth == nil { + continue + } + if strings.TrimSpace(server.OAuth.RedirectURI) == "" { + continue + } + if _, _, err := ParseLoopbackRedirectURI(server.OAuth.RedirectURI); err != nil { + errors = append(errors, ValidationError{ + Field: fmt.Sprintf("mcpServers[%d].oauth.redirect_uri", i), + Message: err.Error(), + }) + } + } + return errors +} + +func (c *Config) validateDetailedCore() []ValidationError { var errors []ValidationError // Validate listen address format @@ -2482,8 +2523,16 @@ func (c *Config) Validate() error { c.RoutingMode = RoutingModeRetrieveTools } - // Then perform detailed validation - errors := c.ValidateDetailed() + // Then perform detailed validation. + // + // validateDetailedCore(), NOT ValidateDetailed(): a malformed per-server + // `oauth.redirect_uri` must not brick the boot. Failing the load would take + // every other server down with it over a field only one server uses, and the + // value is already surfaced loudly at connect time (internal/oauth returns an + // explicit "invalid oauth.redirect_uri for server X" error). The write + // surfaces reject it via ValidateDetailed() instead — that is where the + // operator is actually typing it. + errors := c.validateDetailedCore() if len(errors) > 0 { // Return first error for backward compatibility return fmt.Errorf("%s", errors[0].Error()) diff --git a/internal/config/oauth_redirect_uri_validation_test.go b/internal/config/oauth_redirect_uri_validation_test.go new file mode 100644 index 000000000..4f3f27b5b --- /dev/null +++ b/internal/config/oauth_redirect_uri_validation_test.go @@ -0,0 +1,162 @@ +package config + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func TestParseLoopbackRedirectURI(t *testing.T) { + tests := []struct { + name string + uri string + wantHost string + wantPort int + wantErr string + }{ + {name: "loopback ipv4", uri: "http://127.0.0.1:54108/oauth/callback", wantHost: LoopbackIPv4Host, wantPort: 54108}, + {name: "localhost binds ipv4", uri: "http://localhost:8123/oauth/callback", wantHost: LoopbackIPv4Host, wantPort: 8123}, + {name: "ipv6 loopback binds ipv6", uri: "http://[::1]:8123/oauth/callback", wantHost: LoopbackIPv6Host, wantPort: 8123}, + {name: "whitespace tolerated", uri: " http://127.0.0.1:54108/oauth/callback ", wantHost: LoopbackIPv4Host, wantPort: 54108}, + {name: "empty", uri: "", wantErr: "empty"}, + {name: "not a url", uri: "://nope", wantErr: "not a valid URL"}, + {name: "https scheme", uri: "https://127.0.0.1:54108/oauth/callback", wantErr: "http scheme"}, + {name: "ftp scheme", uri: "ftp://nope/oauth/callback", wantErr: "http scheme"}, + {name: "non-loopback host", uri: "https://evil.example.com/nope", wantErr: "http scheme"}, + {name: "non-loopback http host", uri: "http://evil.example.com/oauth/callback", wantErr: "loopback host"}, + {name: "gemini callback path", uri: "http://localhost:7777/oauth2callback", wantErr: "callback path"}, + {name: "no port", uri: "http://127.0.0.1/oauth/callback", wantErr: "explicit port"}, + {name: "port zero", uri: "http://127.0.0.1:0/oauth/callback", wantErr: "invalid port"}, + {name: "query string", uri: "http://127.0.0.1:54108/oauth/callback?x=1", wantErr: "query string or fragment"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + host, port, err := ParseLoopbackRedirectURI(tt.uri) + if tt.wantErr != "" { + if err == nil { + t.Fatalf("expected error containing %q, got nil", tt.wantErr) + } + if !strings.Contains(err.Error(), tt.wantErr) { + t.Fatalf("expected error containing %q, got %q", tt.wantErr, err.Error()) + } + return + } + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + if host != tt.wantHost || port != tt.wantPort { + t.Fatalf("got (%q, %d), want (%q, %d)", host, port, tt.wantHost, tt.wantPort) + } + }) + } +} + +func TestOAuthConfigValidate_RejectsMalformedRedirectURI(t *testing.T) { + o := &OAuthConfig{RedirectURI: "https://evil.example.com/nope"} + err := o.Validate() + if err == nil { + t.Fatal("expected a malformed redirect_uri to be rejected") + } + if !strings.Contains(err.Error(), "oauth.redirect_uri") { + t.Fatalf("error must name the field, got %q", err.Error()) + } + + if err := (&OAuthConfig{RedirectURI: "http://127.0.0.1:54108/oauth/callback"}).Validate(); err != nil { + t.Fatalf("a valid pin must pass: %v", err) + } + if err := (&OAuthConfig{}).Validate(); err != nil { + t.Fatalf("an absent redirect_uri must pass: %v", err) + } +} + +// TestValidateDetailed_RejectsMalformedRedirectURI covers the REST write +// surfaces: POST /api/v1/config/validate, POST /api/v1/config/apply and +// PATCH /api/v1/config all funnel through Runtime.ValidateConfig / +// Runtime.ApplyConfig, which call ValidateDetailed. Before this the same value +// that MCP's upstream_servers rejected was accepted and persisted via REST. +func TestValidateDetailed_RejectsMalformedRedirectURI(t *testing.T) { + cfg := &Config{ + Servers: []*ServerConfig{ + {Name: "ok", URL: "https://example.com/mcp", Protocol: "http"}, + { + Name: "bad-pin", + URL: "https://example.com/mcp", + Protocol: "http", + OAuth: &OAuthConfig{RedirectURI: "https://evil.example.com/nope"}, + }, + }, + } + + var found bool + for _, e := range cfg.ValidateDetailed() { + if e.Field == "mcpServers[1].oauth.redirect_uri" { + found = true + if !strings.Contains(e.Message, "http scheme") { + t.Fatalf("unexpected message: %q", e.Message) + } + } + } + if !found { + t.Fatalf("ValidateDetailed must flag the malformed pin, got %+v", cfg.ValidateDetailed()) + } + + // A valid pin must not be flagged. + cfg.Servers[1].OAuth.RedirectURI = "http://127.0.0.1:54108/oauth/callback" + for _, e := range cfg.ValidateDetailed() { + if strings.Contains(e.Field, "redirect_uri") { + t.Fatalf("a valid pin must not be flagged: %+v", e) + } + } +} + +// TestLoadStillBootsWithMalformedRedirectURI is the other half of the contract: +// a bad value already on disk must NOT brick the boot. Failing the load would +// take every other server down over a field one server uses, and the value is +// already surfaced loudly at connect time. +func TestLoadStillBootsWithMalformedRedirectURI(t *testing.T) { + dir := t.TempDir() + path := filepath.Join(dir, "mcp_config.json") + body := `{ + "listen": "127.0.0.1:8080", + "mcpServers": [ + { + "name": "bad-pin", + "url": "https://example.com/mcp", + "protocol": "http", + "enabled": true, + "oauth": {"redirect_uri": "https://evil.example.com/nope"} + } + ] + }` + if err := os.WriteFile(path, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + + cfg, err := LoadFromFile(path) + if err != nil { + t.Fatalf("a pre-existing malformed oauth.redirect_uri must not fail the load: %v", err) + } + if len(cfg.Servers) != 1 { + t.Fatalf("expected the server to survive the load, got %d", len(cfg.Servers)) + } + if cfg.Servers[0].OAuth == nil || cfg.Servers[0].OAuth.RedirectURI != "https://evil.example.com/nope" { + t.Fatalf("the value must be preserved verbatim for the connect-time diagnostic") + } + + // The split is load-bearing: the same config that Validate() (boot) tolerates + // must be rejected by ValidateDetailed() (every write surface). + if err := cfg.Validate(); err != nil { + t.Fatalf("Validate (boot path) must tolerate the value: %v", err) + } + var flagged bool + for _, e := range cfg.ValidateDetailed() { + if strings.Contains(e.Field, "redirect_uri") { + flagged = true + } + } + if !flagged { + t.Fatal("ValidateDetailed (write surfaces) must still reject the value") + } +} diff --git a/internal/config/oauth_validation.go b/internal/config/oauth_validation.go index 394b127a9..81cea9dcb 100644 --- a/internal/config/oauth_validation.go +++ b/internal/config/oauth_validation.go @@ -2,9 +2,27 @@ package config import ( "fmt" + "net/url" + "strconv" "strings" ) +// OAuthCallbackPath is the loopback path mcpproxy's OAuth callback server +// listens on. +// +// It lives here rather than in internal/oauth because internal/oauth imports +// this package (never the other way round) and the config layer has to validate +// `oauth.redirect_uri` where the operator types it. internal/oauth aliases it as +// DefaultRedirectPath. +const OAuthCallbackPath = "/oauth/callback" + +// LoopbackIPv4Host / LoopbackIPv6Host are the addresses the callback listener +// binds for the two loopback families a pinned redirect URI can name. +const ( + LoopbackIPv4Host = "127.0.0.1" + LoopbackIPv6Host = "::1" +) + // Reserved OAuth 2.0 parameters that cannot be overridden via extra_params var reservedOAuthParams = map[string]bool{ "client_id": true, @@ -41,6 +59,78 @@ func ValidateOAuthExtraParams(params map[string]string) error { return nil } +// LoopbackBindHost maps the hostname of a pinned redirect URI onto the address +// the callback listener must bind. +// +// "localhost" deliberately binds 127.0.0.1 rather than resolving it: the URI +// string sent to the provider keeps the operator's spelling (providers match it +// literally), while the listener stays on the family mcpproxy can guarantee. +// Mainstream browsers fall back from ::1 to 127.0.0.1 via Happy Eyeballs, and +// docs/configuration.md steers operators to 127.0.0.1 for that reason. +func LoopbackBindHost(hostname string) string { + if hostname == LoopbackIPv6Host { + return LoopbackIPv6Host + } + return LoopbackIPv4Host +} + +// ParseLoopbackRedirectURI validates an operator-pinned OAuth redirect URI (the +// per-server `oauth.redirect_uri` config field) and returns the loopback host to +// bind and the port it pins. +// +// Providers such as GitHub OAuth Apps require the callback URL to match the +// registered one exactly and reject wildcards, so operators need a way to nail +// the loopback port down instead of letting mcpproxy allocate a fresh one per +// login. The URI must therefore be an RFC 8252 loopback redirect with an +// explicit port and mcpproxy's callback path, e.g. +// +// http://127.0.0.1:54108/oauth/callback +// +// Anything else is rejected with an actionable error rather than silently +// downgraded to dynamic allocation. +func ParseLoopbackRedirectURI(rawURI string) (bindHost string, port int, err error) { + trimmed := strings.TrimSpace(rawURI) + if trimmed == "" { + return "", 0, fmt.Errorf("oauth.redirect_uri is empty") + } + + parsed, err := url.Parse(trimmed) + if err != nil { + return "", 0, fmt.Errorf("oauth.redirect_uri %q is not a valid URL: %w", trimmed, err) + } + + if parsed.Scheme != "http" { + return "", 0, fmt.Errorf("oauth.redirect_uri %q must use the http scheme for a loopback redirect (RFC 8252), got %q", trimmed, parsed.Scheme) + } + + hostname := parsed.Hostname() + switch hostname { + case LoopbackIPv4Host, "localhost", LoopbackIPv6Host: + default: + return "", 0, fmt.Errorf("oauth.redirect_uri %q must use a loopback host (127.0.0.1, localhost or ::1), got %q", trimmed, hostname) + } + + if parsed.Path != OAuthCallbackPath { + return "", 0, fmt.Errorf("oauth.redirect_uri %q must use the callback path %q, got %q", trimmed, OAuthCallbackPath, parsed.Path) + } + + if parsed.RawQuery != "" || parsed.Fragment != "" { + return "", 0, fmt.Errorf("oauth.redirect_uri %q must not contain a query string or fragment", trimmed) + } + + portStr := parsed.Port() + if portStr == "" { + return "", 0, fmt.Errorf("oauth.redirect_uri %q must include an explicit port to pin (e.g. http://127.0.0.1:54108%s)", trimmed, OAuthCallbackPath) + } + + parsedPort, err := strconv.Atoi(portStr) + if err != nil || parsedPort < 1 || parsedPort > 65535 { + return "", 0, fmt.Errorf("oauth.redirect_uri %q has an invalid port %q (expected 1-65535)", trimmed, portStr) + } + + return LoopbackBindHost(hostname), parsedPort, nil +} + // Validate performs validation on OAuthConfig func (o *OAuthConfig) Validate() error { if o == nil { @@ -52,5 +142,15 @@ func (o *OAuthConfig) Validate() error { return fmt.Errorf("oauth config validation failed: %w", err) } + // A malformed redirect_uri is a permanent, undiagnosable connect failure + // (the provider rejects a callback URL that does not match the registered + // one, and mcpproxy refuses to silently downgrade to a random port). + // Reject it where the operator is typing it instead. + if strings.TrimSpace(o.RedirectURI) != "" { + if _, _, err := ParseLoopbackRedirectURI(o.RedirectURI); err != nil { + return fmt.Errorf("oauth config validation failed: %w", err) + } + } + return nil } diff --git a/internal/configimport/mapper.go b/internal/configimport/mapper.go index 1165477a5..028eddf4a 100644 --- a/internal/configimport/mapper.go +++ b/internal/configimport/mapper.go @@ -1,6 +1,7 @@ package configimport import ( + "fmt" "time" "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" @@ -63,6 +64,17 @@ func MapToServerConfig(parsed *ParsedServer, now time.Time) (*config.ServerConfi } case FormatGemini: if oauth := mapGeminiOAuth(parsed.Fields); oauth != nil { + // Gemini's redirect_uri uses its own callback path (typically + // http://localhost:7777/oauth2callback), which mcpproxy's loopback + // callback server cannot serve. Copying it verbatim turned an + // importable server into a permanent connect failure, so drop the + // value and let mcpproxy allocate its own callback instead. + if oauth.RedirectURI != "" { + if err := oauth.Validate(); err != nil { + warnings = append(warnings, fmt.Sprintf("oauth.redirect_uri %q is not usable by mcpproxy and was dropped (%v); mcpproxy will allocate its own callback URL", oauth.RedirectURI, err)) + oauth.RedirectURI = "" + } + } server.OAuth = oauth warnings = append(warnings, "OAuth credentials imported; you may need to reconfigure") } diff --git a/internal/configimport/mapper_test.go b/internal/configimport/mapper_test.go index 2b57af0ee..6b35fa2b6 100644 --- a/internal/configimport/mapper_test.go +++ b/internal/configimport/mapper_test.go @@ -1,6 +1,7 @@ package configimport import ( + "strings" "testing" "time" ) @@ -170,7 +171,7 @@ func TestMapToServerConfig(t *testing.T) { }, } - server, _, _ := MapToServerConfig(parsed, now) + server, _, warnings := MapToServerConfig(parsed, now) if server.OAuth == nil { t.Fatal("OAuth should be set") @@ -178,8 +179,48 @@ func TestMapToServerConfig(t *testing.T) { if server.OAuth.ClientID != "gemini-client" { t.Errorf("OAuth.ClientID = %s, want gemini-client", server.OAuth.ClientID) } - if server.OAuth.RedirectURI != "http://localhost:3000/callback" { - t.Errorf("OAuth.RedirectURI = %s, want http://localhost:3000/callback", server.OAuth.RedirectURI) + // Gemini's redirect_uri uses its own callback path, which mcpproxy's + // loopback callback server does not serve. Since oauth.redirect_uri + // became load-bearing it PINS the callback URL, so copying such a value + // verbatim turns an importable server into a permanent connect failure + // ("must use the callback path \"/oauth/callback\""). Drop it and let + // mcpproxy allocate its own callback URL instead. + if server.OAuth.RedirectURI != "" { + t.Errorf("OAuth.RedirectURI = %s, want it dropped as unusable", server.OAuth.RedirectURI) + } + var warned bool + for _, w := range warnings { + if strings.Contains(w, "redirect_uri") && strings.Contains(w, "dropped") { + warned = true + } + } + if !warned { + t.Errorf("dropping redirect_uri must be warned about, got %v", warnings) + } + }) + + t.Run("gemini_oauth_usable_redirect_uri_preserved", func(t *testing.T) { + parsed := &ParsedServer{ + Name: "oauth-server", + SourceFormat: FormatGemini, + Fields: map[string]interface{}{ + "url": "http://localhost:8080", + "protocol": "http", + "oauth": &GeminiOAuth{ + Enabled: true, + ClientID: "gemini-client", + RedirectURI: "http://127.0.0.1:54108/oauth/callback", + }, + }, + } + + server, _, _ := MapToServerConfig(parsed, now) + if server.OAuth == nil { + t.Fatal("OAuth should be set") + } + // A value mcpproxy CAN honor is a deliberate pin and must survive import. + if server.OAuth.RedirectURI != "http://127.0.0.1:54108/oauth/callback" { + t.Errorf("OAuth.RedirectURI = %s, want it preserved", server.OAuth.RedirectURI) } }) diff --git a/internal/oauth/config.go b/internal/oauth/config.go index f5142241e..bd679b62b 100644 --- a/internal/oauth/config.go +++ b/internal/oauth/config.go @@ -24,8 +24,18 @@ import ( const ( // Default OAuth redirect URI base - port will be dynamically assigned - DefaultRedirectURIBase = "http://127.0.0.1" - DefaultRedirectPath = "/oauth/callback" + DefaultRedirectURIBase = "http://" + config.LoopbackIPv4Host + // DefaultRedirectPath aliases the canonical callback path. The constant is + // defined in internal/config because `oauth.redirect_uri` has to be + // validated where the operator types it, and internal/config cannot import + // this package. + DefaultRedirectPath = config.OAuthCallbackPath + + // oauthLoggerName is the logger name every record in this package carries. + // Log filters and runbooks are written against it, so it is applied exactly + // once (see namedOAuthLogger). + oauthLoggerName = "oauth" + oauthCallbackLoggerName = "oauth-callback" // Rate limit retry constants for resource auto-detection resourceDetectMaxRetries = 3 // Maximum retry attempts on 429 @@ -38,63 +48,74 @@ const ( // per-server `oauth.redirect_uri` config field) and returns the loopback port it // pins. // -// Providers such as GitHub OAuth Apps require the callback URL to match the -// registered one exactly and reject wildcards, so operators need a way to nail -// the loopback port down instead of letting mcpproxy allocate a fresh one per -// login. The URI must therefore be an RFC 8252 loopback redirect with an -// explicit port and mcpproxy's callback path, e.g. -// -// http://127.0.0.1:54108/oauth/callback -// -// Anything else is rejected with an actionable error rather than silently -// downgraded to dynamic allocation. +// The rules live in internal/config (ParseLoopbackRedirectURI) so that the REST +// config API, the MCP `upstream_servers` tool and this flow all reject exactly +// the same values. See that function for the rationale. func ParsePinnedRedirectURI(rawURI string) (int, error) { - trimmed := strings.TrimSpace(rawURI) - if trimmed == "" { - return 0, fmt.Errorf("oauth.redirect_uri is empty") - } + _, port, err := config.ParseLoopbackRedirectURI(rawURI) + return port, err +} - parsed, err := url.Parse(trimmed) - if err != nil { - return 0, fmt.Errorf("oauth.redirect_uri %q is not a valid URL: %w", trimmed, err) - } +// ParsePinnedRedirectURIBinding is ParsePinnedRedirectURI plus the loopback host +// the callback listener must bind. A pinned `http://[::1]:PORT/oauth/callback` +// is only honored if something actually listens on ::1 — binding 127.0.0.1 for +// it produced an authorize URL nobody could call back to. +func ParsePinnedRedirectURIBinding(rawURI string) (bindHost string, port int, err error) { + return config.ParseLoopbackRedirectURI(rawURI) +} - if parsed.Scheme != "http" { - return 0, fmt.Errorf("oauth.redirect_uri %q must use the http scheme for a loopback redirect (RFC 8252), got %q", trimmed, parsed.Scheme) - } +// namedOAuthLogger returns logger tagged with this package's logger name. +// +// It is idempotent: applying it twice must not produce "oauth.oauth" and break +// every filter written against the documented name. A nil logger falls back to +// the zap global, which is what the pre-logger-threading call sites used. +func namedOAuthLogger(logger *zap.Logger) *zap.Logger { + if logger == nil { + return zap.L().Named(oauthLoggerName) + } + name := logger.Name() + if name == oauthLoggerName || strings.HasSuffix(name, "."+oauthLoggerName) { + return logger + } + return logger.Named(oauthLoggerName) +} - switch parsed.Hostname() { - case "127.0.0.1", "localhost", "::1": - default: - return 0, fmt.Errorf("oauth.redirect_uri %q must use a loopback host (127.0.0.1, localhost or ::1), got %q", trimmed, parsed.Hostname()) - } +// CallbackServerManager manages OAuth callback servers for dynamic port allocation +type CallbackServerManager struct { + servers map[string]*CallbackServer + mu sync.RWMutex - if parsed.Path != DefaultRedirectPath { - return 0, fmt.Errorf("oauth.redirect_uri %q must use the callback path %q, got %q", trimmed, DefaultRedirectPath, parsed.Path) - } + // logger is guarded by mu. It starts as the zap global, which in this + // binary is the NO-OP logger (zap.ReplaceGlobals is never called), so every + // record the callback surface emits would be silently discarded — the + // tear-down of a live listener, a dropped waiter, a failed bind on a pinned + // port, and "did the callback ever arrive?" all vanish. SetLogger (and the + // logger threaded through StartCallbackServerOnHost) replaces it with the + // caller's real logger the first time a flow runs. + logger *zap.Logger +} - if parsed.RawQuery != "" || parsed.Fragment != "" { - return 0, fmt.Errorf("oauth.redirect_uri %q must not contain a query string or fragment", trimmed) +// SetLogger installs a real logger on the manager. Safe to call repeatedly; a +// nil logger is ignored so a caller without one cannot blind the manager again. +func (m *CallbackServerManager) SetLogger(logger *zap.Logger) { + if logger == nil { + return } + m.mu.Lock() + defer m.mu.Unlock() + m.adoptLoggerLocked(logger) +} - portStr := parsed.Port() - if portStr == "" { - return 0, fmt.Errorf("oauth.redirect_uri %q must include an explicit port to pin (e.g. %s:54108%s)", trimmed, DefaultRedirectURIBase, DefaultRedirectPath) +// adoptLoggerLocked records the caller's logger as the manager logger and +// returns the logger to use for this call. m.mu must be held. +func (m *CallbackServerManager) adoptLoggerLocked(logger *zap.Logger) *zap.Logger { + if logger != nil { + m.logger = logger.Named(oauthCallbackLoggerName) } - - port, err := strconv.Atoi(portStr) - if err != nil || port < 1 || port > 65535 { - return 0, fmt.Errorf("oauth.redirect_uri %q has an invalid port %q (expected 1-65535)", trimmed, portStr) + if m.logger == nil { + m.logger = zap.L().Named(oauthCallbackLoggerName) } - - return port, nil -} - -// CallbackServerManager manages OAuth callback servers for dynamic port allocation -type CallbackServerManager struct { - servers map[string]*CallbackServer - mu sync.RWMutex - logger *zap.Logger + return m.logger } // CallbackServer represents an active OAuth callback server. @@ -109,7 +130,12 @@ type CallbackServer struct { RedirectURI string Server *http.Server ServerName string - logger *zap.Logger + // BindHost is the loopback address the listener is actually bound to + // ("127.0.0.1" or "::1"). A pinned `http://[::1]:PORT/oauth/callback` is + // only honored when the listener is on the same family, so the binding is + // recorded rather than assumed. + BindHost string + logger *zap.Logger waitersMu sync.Mutex waiters map[string]chan map[string]string @@ -117,7 +143,7 @@ type CallbackServer struct { var globalCallbackManager = &CallbackServerManager{ servers: make(map[string]*CallbackServer), - logger: zap.L().Named("oauth-callback"), + logger: zap.L().Named(oauthCallbackLoggerName), } // Global token store manager to persist tokens across client instances @@ -441,7 +467,21 @@ func (m *TokenStoreManager) HasValidToken(ctx context.Context, serverName string // 2. Auto-detected resource from RFC 9728 Protected Resource Metadata // 3. Fallback to server URL if metadata is unavailable or lacks resource field func CreateOAuthConfigWithExtraParams(ctx context.Context, serverConfig *config.ServerConfig, storage *storage.BoltDB) (*client.OAuthConfig, map[string]string) { - logger := zap.L().Named("oauth") + cfg, extraParams, _ := CreateOAuthConfigWithExtraParamsAndLogger(ctx, serverConfig, storage, nil) + return cfg, extraParams +} + +// CreateOAuthConfigWithExtraParamsAndLogger is CreateOAuthConfigWithExtraParams +// with the caller's logger and the reason it failed. +// +// Both additions exist because this package used to log through zap.L(), and +// zap.ReplaceGlobals is never called in this binary — so zap.L() is the NO-OP +// logger and every diagnostic here was silently discarded, including the one +// that names a malformed `oauth.redirect_uri`. Callers now pass a real logger +// and surface the returned error instead of reporting the generic "server may +// not support OAuth". +func CreateOAuthConfigWithExtraParamsAndLogger(ctx context.Context, serverConfig *config.ServerConfig, storage *storage.BoltDB, logger *zap.Logger) (*client.OAuthConfig, map[string]string, error) { + logger = namedOAuthLogger(logger) // Initialize extraParams map extraParams := make(map[string]string) @@ -467,9 +507,9 @@ func CreateOAuthConfigWithExtraParams(ctx context.Context, serverConfig *config. } // Create the base OAuth config, passing extraParams for transport wrapper injection - oauthConfig := createOAuthConfigInternal(serverConfig, storage, extraParams) + oauthConfig, err := createOAuthConfigInternal(serverConfig, storage, extraParams, logger) - return oauthConfig, extraParams + return oauthConfig, extraParams, err } // parseRateLimitWait extracts wait duration from a 429 response. @@ -722,20 +762,47 @@ func handleUnauthorizedResponse(resp *http.Response, body []byte, serverConfig * // Note: For zero-config OAuth with auto-detected resource parameter, use // CreateOAuthConfigWithExtraParams() instead, which returns both config and extraParams. func CreateOAuthConfig(serverConfig *config.ServerConfig, storage *storage.BoltDB) *client.OAuthConfig { + cfg, _ := CreateOAuthConfigWithLogger(serverConfig, storage, nil) + return cfg +} + +// CreateOAuthConfigWithLogger is CreateOAuthConfig with the caller's logger and +// the reason it failed. See CreateOAuthConfigWithExtraParamsAndLogger. +func CreateOAuthConfigWithLogger(serverConfig *config.ServerConfig, storage *storage.BoltDB, logger *zap.Logger) (*client.OAuthConfig, error) { // Extract manual extra_params from config for backward compatibility var extraParams map[string]string if serverConfig.OAuth != nil && len(serverConfig.OAuth.ExtraParams) > 0 { extraParams = serverConfig.OAuth.ExtraParams } - return createOAuthConfigInternal(serverConfig, storage, extraParams) + return createOAuthConfigInternal(serverConfig, storage, extraParams, logger) +} + +// clearOAuthCredentials drops a DCR registration so the next login re-registers. +func clearOAuthCredentials(logger *zap.Logger, storage *storage.BoltDB, serverKey, serverName string) { + if storage == nil { + return + } + if err := storage.ClearOAuthClientCredentials(serverKey); err != nil { + logger.Warn("Failed to clear DCR credentials", + zap.String("server", serverName), + zap.Error(err)) + } } // createOAuthConfigInternal is the internal implementation that accepts extraParams // for transport wrapper injection. This enables both manual and auto-detected params // to be injected into token exchange and refresh requests. -func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *storage.BoltDB, extraParams map[string]string) *client.OAuthConfig { +func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *storage.BoltDB, extraParams map[string]string, logger *zap.Logger) (*client.OAuthConfig, error) { startTime := time.Now() - logger := zap.L().Named("oauth") + // Applied exactly once per record: namedOAuthLogger is idempotent, so the + // wrappers above may have named it already without producing "oauth.oauth". + logger = namedOAuthLogger(logger) + + // Hand the real logger to the callback-server manager, whose own default is + // the no-op zap global. Without this the entire callback surface — the bind + // attempt on a pinned port, a tear-down, a dropped waiter, the arrival of + // the callback itself — is invisible in main.log and the per-server log. + globalCallbackManager.SetLogger(logger) logger.Debug("🚀 Starting OAuth config creation", zap.String("server", serverConfig.Name), @@ -858,8 +925,9 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora // wildcards, so an operator must be able to nail the port down (issue #975). var pinnedRedirectURI string var pinnedPort int + bindHost := config.LoopbackIPv4Host if serverConfig.OAuth != nil && strings.TrimSpace(serverConfig.OAuth.RedirectURI) != "" { - port, err := ParsePinnedRedirectURI(serverConfig.OAuth.RedirectURI) + host, port, err := ParsePinnedRedirectURIBinding(serverConfig.OAuth.RedirectURI) if err != nil { // Fail loudly: silently falling back to a random port would leave the // operator believing they pinned the callback URL when they had not. @@ -868,17 +936,38 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.String("redirect_uri", serverConfig.OAuth.RedirectURI), zap.Error(err), zap.String("expected_format", "http://127.0.0.1:"+DefaultRedirectPath)) - return nil + // Returned, not just logged: the caller's "server may not support + // OAuth" message never mentions redirect_uri, which made a typo here + // a permanent, undiagnosable connect failure. + return nil, fmt.Errorf("invalid oauth.redirect_uri for server %q: %w", serverConfig.Name, err) } pinnedRedirectURI = strings.TrimSpace(serverConfig.OAuth.RedirectURI) pinnedPort = port + // Bind the family the operator pinned. Binding 127.0.0.1 for a pinned + // `http://[::1]:PORT/...` produced an authorize URL whose callback hit a + // closed port, and the login then hung to the callback timeout. + bindHost = host } // Check for stored callback port from previous DCR (Spec 022: OAuth Redirect URI Port Persistence) + // + // The stored record is read whether or not a port is pinned. A pin only + // short-circuits the PORT CHOICE; it must not short-circuit the Spec 022 + // credential hygiene below, because a DCR client_id is registered against + // the redirect_uri it was created with. Skipping the read meant a stale + // registration was reused forever under a new pin, producing a permanent + // redirect_uri_mismatch that no retry could clear. var preferredPort int var serverKey string + var storedClientID string + var storedPort int if storage != nil { serverKey = GenerateServerKey(serverConfig.Name, serverConfig.URL) + var storedErr error + storedClientID, _, storedPort, storedErr = storage.GetOAuthClientCredentials(serverKey) + if storedErr != nil { + storedClientID, storedPort = "", 0 + } } switch { @@ -887,31 +976,40 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora logger.Info("📌 Using operator-pinned OAuth callback port from oauth.redirect_uri", zap.String("server", serverConfig.Name), zap.String("redirect_uri", pinnedRedirectURI), + zap.String("bind_host", bindHost), + zap.Int("preferred_port", preferredPort)) + case storedPort > 0: + preferredPort = storedPort + logger.Info("🔄 Found stored callback port from previous OAuth login", + zap.String("server", serverConfig.Name), zap.Int("preferred_port", preferredPort)) - case storage != nil: - storedClientID, _, storedPort, err := storage.GetOAuthClientCredentials(serverKey) + } + + // Spec 022 credential hygiene, independent of the pin. Only DCR-issued + // credentials are ever cleared: a static client_id is operator-supplied, + // cannot be re-registered, and clearing it would only destroy configuration. + if storage != nil && storedClientID != "" && !hasStaticClientID { switch { - case err == nil && storedPort > 0: - preferredPort = storedPort - logger.Info("🔄 Found stored callback port from previous OAuth login", - zap.String("server", serverConfig.Name), - zap.Int("preferred_port", preferredPort)) - case err == nil && storedClientID != "" && storedPort == 0 && hasStaticClientID: - // Static credentials are configured by hand; there is nothing to - // re-register, so keep the record and let this login persist its port. - logger.Debug("Static OAuth client has no stored callback port yet; keeping credentials", - zap.String("server", serverConfig.Name)) - case err == nil && storedClientID != "" && storedPort == 0: - // Spec 022: Legacy DCR credentials exist but port is unknown - // Clear them to force fresh registration with port tracking + case storedPort == 0: + // Legacy DCR credentials exist but the port is unknown. Clear them to + // force fresh registration with port tracking. logger.Warn("⚠️ Legacy DCR credentials found without stored port, clearing for re-registration", zap.String("server", serverConfig.Name), zap.String("client_id", storedClientID)) - if clearErr := storage.ClearOAuthClientCredentials(serverKey); clearErr != nil { - logger.Warn("Failed to clear legacy DCR credentials", - zap.String("server", serverConfig.Name), - zap.Error(clearErr)) - } + clearOAuthCredentials(logger, storage, serverKey, serverConfig.Name) + case pinnedPort > 0 && storedPort != pinnedPort: + // The registration was created for a different callback port than the + // one now pinned, so the provider will reject the redirect_uri this + // client_id is paired with. This is the feature's most likely upgrade + // path: log in unpinned (DCR registers port A), then add + // oauth.redirect_uri with port B because the moving port was rejected. + // Re-register rather than fail forever. + logger.Warn("⚠️ Stored DCR credentials were registered for a different callback port than oauth.redirect_uri pins, clearing for re-registration", + zap.String("server", serverConfig.Name), + zap.String("client_id", storedClientID), + zap.Int("stored_port", storedPort), + zap.Int("pinned_port", pinnedPort)) + clearOAuthCredentials(logger, storage, serverKey, serverConfig.Name) } } @@ -922,12 +1020,17 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.String("approach", "MCPProxy callback server coordination for exact URI matching")) // Start our own callback server to get exact port for Cloudflare OAuth - callbackServer, err := globalCallbackManager.StartCallbackServer(serverConfig.Name, preferredPort) + callbackServer, err := globalCallbackManager.StartCallbackServerOnHost(serverConfig.Name, CallbackBinding{ + Host: bindHost, + Port: preferredPort, + Pinned: pinnedPort > 0, + Logger: logger, + }) if err != nil { logger.Error("Failed to start OAuth callback server", zap.String("server", serverConfig.Name), zap.Error(err)) - return nil + return nil, fmt.Errorf("failed to start OAuth callback server for %q: %w", serverConfig.Name, err) } // Spec 022: Detect port conflict and clear DCR credentials if port changed @@ -943,12 +1046,13 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.Int("pinned_port", pinnedPort), zap.Int("bound_port", callbackServer.Port), zap.String("hint", "free the pinned port, or change oauth.redirect_uri (and the provider's callback URL) to a free one")) - if stopErr := globalCallbackManager.StopCallbackServer(serverConfig.Name); stopErr != nil { + if stopErr := globalCallbackManager.StopCallbackServerWithLogger(serverConfig.Name, logger); stopErr != nil { logger.Warn("Failed to stop callback server bound to the wrong port", zap.String("server", serverConfig.Name), zap.Error(stopErr)) } - return nil + return nil, fmt.Errorf("pinned OAuth callback port %d for server %q is unavailable (bound %d instead); free it or change oauth.redirect_uri and the provider's callback URL", + pinnedPort, serverConfig.Name, callbackServer.Port) case hasStaticClientID: // Static credentials are not re-registerable, so clearing them would // only destroy the operator's configuration for no benefit. @@ -962,13 +1066,7 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.String("server", serverConfig.Name), zap.Int("stored_port", preferredPort), zap.Int("new_port", callbackServer.Port)) - if storage != nil { - if err := storage.ClearOAuthClientCredentials(serverKey); err != nil { - logger.Warn("Failed to clear DCR credentials after port change", - zap.String("server", serverConfig.Name), - zap.Error(err)) - } - } + clearOAuthCredentials(logger, storage, serverKey, serverConfig.Name) } } @@ -1084,9 +1182,11 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.String("server", serverConfig.Name), zap.String("client_id", clientID)) } else { - // Try to load persisted DCR credentials for token refresh + // Try to load persisted DCR credentials for token refresh. + // Re-read rather than reuse the earlier snapshot: the Spec 022 hygiene + // above may have just cleared a registration that is no longer valid for + // this callback port. if storage != nil { - serverKey := GenerateServerKey(serverConfig.Name, serverConfig.URL) persistedClientID, persistedClientSecret, _, err := storage.GetOAuthClientCredentials(serverKey) if err == nil && persistedClientID != "" { clientID = persistedClientID @@ -1136,25 +1236,117 @@ func createOAuthConfigInternal(serverConfig *config.ServerConfig, storage *stora zap.String("discovery_mode", "explicit metadata URL"), // Using explicit metadata URL to avoid discovery timeouts zap.String("token_store", "shared")) // Using shared token store for token persistence - return oauthConfig + return oauthConfig, nil +} + +// CallbackBinding describes the loopback endpoint a flow needs its OAuth +// callback server on. +type CallbackBinding struct { + // Host is the loopback address to listen on ("127.0.0.1" or "::1"). + // Empty means 127.0.0.1. + Host string + // Port is the port to try first. 0 means dynamic allocation. + Port int + // Pinned reports whether Port came from an operator's `oauth.redirect_uri` + // rather than from the Spec 022 stored-port record. + // + // It is carried explicitly instead of being inferred from Port > 0 because + // the two cases need opposite handling when a cached server is already + // bound elsewhere: a pin CANNOT be satisfied by another port (the provider + // rejects the mismatched redirect_uri), whereas a stored port is only a + // preference and must never cost a live flow its listener. + Pinned bool + // Logger is the caller's real logger. Without it the callback surface logs + // into the no-op zap global and the whole flow is invisible. + Logger *zap.Logger +} + +func (b CallbackBinding) host() string { + if b.Host == "" { + return config.LoopbackIPv4Host + } + return b.Host } // StartCallbackServer starts a new OAuth callback server for the given server name. // If preferredPort > 0, it attempts to bind to that port first for redirect URI persistence (Spec 022). // Falls back to dynamic allocation if the preferred port is unavailable. +// +// Deprecated in favour of StartCallbackServerOnHost, which can bind IPv6 +// loopback and carries the caller's logger. Kept for callers that have neither. func (m *CallbackServerManager) StartCallbackServer(serverName string, preferredPort int) (*CallbackServer, error) { + return m.StartCallbackServerOnHost(serverName, CallbackBinding{Port: preferredPort}) +} + +// StartCallbackServerOnHost starts (or reuses) the OAuth callback server for a +// server name on the requested loopback binding. +// +// Reuse rules, in order: +// +// - A cached server that already satisfies the binding is reused. Reuse must +// preserve parked waiters: callbacks are dispatched by `state` (issue #975), +// so several flows can safely share one listener. +// - A cached server bound elsewhere is REPLACED only when that cannot strand a +// live flow — i.e. when nothing is parked on it — or when the caller pinned +// the port, in which case reusing the wrong port would hand the provider a +// redirect_uri it rejects and the flow could never complete anyway. +// - Otherwise the cached server is reused despite the mismatch, and the +// mismatch is logged. This is the case that matters for a static client_id +// whose stored port is occupied by another process: attempt 1 falls back to +// a dynamic port and parks a waiter, attempt 2 still prefers the stored +// port, and tearing down attempt 1's listener would make that server +// impossible to log into for as long as the stored port stays occupied. +func (m *CallbackServerManager) StartCallbackServerOnHost(serverName string, binding CallbackBinding) (*CallbackServer, error) { m.mu.Lock() defer m.mu.Unlock() + logger := m.adoptLoggerLocked(binding.Logger) + bindHost := binding.host() + preferredPort := binding.Port + // Check if we already have a server for this name if existing, exists := m.servers[serverName]; exists { - // No draining here (issue #975): params are dispatched per `state`, so a - // stale callback can no longer be mistaken for this attempt's, and a - // waiter already parked on this server must survive the reuse. - m.logger.Debug("Reusing existing callback server", - zap.String("server", serverName), - zap.Int("port", existing.Port)) - return existing, nil + matchesBinding := existing.BindHost == bindHost && + (preferredPort == 0 || existing.Port == preferredPort) + + switch { + case matchesBinding: + // No draining here (issue #975): params are dispatched per `state`, so a + // stale callback can no longer be mistaken for this attempt's, and a + // waiter already parked on this server must survive the reuse. + logger.Debug("Reusing existing callback server", + zap.String("server", serverName), + zap.String("bind_host", existing.BindHost), + zap.Int("port", existing.Port)) + return existing, nil + + case existing.waiterCount() == 0 || binding.Pinned: + logger.Warn("Replacing stale OAuth callback server that does not match the requested binding", + zap.String("server", serverName), + zap.String("cached_bind_host", existing.BindHost), + zap.Int("cached_port", existing.Port), + zap.String("requested_bind_host", bindHost), + zap.Int("requested_port", preferredPort), + zap.Bool("pinned", binding.Pinned), + zap.Int("waiters_dropped", existing.waiterCount())) + if err := m.stopCallbackServerLocked(serverName, logger); err != nil { + logger.Warn("Failed to stop stale OAuth callback server", + zap.String("server", serverName), + zap.Error(err)) + } + + default: + // A flow is parked on the cached listener. Dropping it would send a + // user's browser to a closed port; the preference is not worth that. + logger.Warn("Keeping the existing OAuth callback server: a flow is still waiting on it", + zap.String("server", serverName), + zap.String("cached_bind_host", existing.BindHost), + zap.Int("cached_port", existing.Port), + zap.Int("requested_port", preferredPort), + zap.Int("waiters", existing.waiterCount()), + zap.String("hint", "free the preferred port and retry once the pending login finishes or times out")) + return existing, nil + } } var listener net.Listener @@ -1162,37 +1354,43 @@ func (m *CallbackServerManager) StartCallbackServer(serverName string, preferred // Try preferred port first if specified (Spec 022: OAuth Redirect URI Port Persistence) if preferredPort > 0 { - listener, err = net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", preferredPort)) + listener, err = net.Listen("tcp", net.JoinHostPort(bindHost, strconv.Itoa(preferredPort))) if err != nil { - m.logger.Warn("Preferred port unavailable, falling back to dynamic allocation", + logger.Warn("Preferred port unavailable, falling back to dynamic allocation", zap.String("server", serverName), + zap.String("bind_host", bindHost), zap.Int("preferred_port", preferredPort), + zap.Bool("pinned", binding.Pinned), zap.Error(err)) // Fall through to dynamic allocation } else { - m.logger.Info("✅ Using preferred port for OAuth callback (port persistence)", + logger.Info("✅ Using preferred port for OAuth callback (port persistence)", zap.String("server", serverName), + zap.String("bind_host", bindHost), zap.Int("port", preferredPort)) } } // Fall back to dynamic port allocation if no listener yet if listener == nil { - listener, err = net.Listen("tcp", "127.0.0.1:0") + listener, err = net.Listen("tcp", net.JoinHostPort(bindHost, "0")) if err != nil { - return nil, fmt.Errorf("failed to allocate dynamic port: %w", err) + return nil, fmt.Errorf("failed to allocate dynamic port on %s: %w", bindHost, err) } } // Extract the dynamically allocated port addr := listener.Addr().(*net.TCPAddr) port := addr.Port - redirectURI := fmt.Sprintf("%s:%d%s", DefaultRedirectURIBase, port, DefaultRedirectPath) + listenAddr := net.JoinHostPort(bindHost, strconv.Itoa(port)) + // JoinHostPort brackets an IPv6 literal, which is what the redirect URI + // needs too ("http://[::1]:PORT/oauth/callback"). + redirectURI := fmt.Sprintf("http://%s%s", listenAddr, DefaultRedirectPath) // Create HTTP server with dedicated mux mux := http.NewServeMux() server := &http.Server{ - Addr: fmt.Sprintf("127.0.0.1:%d", port), + Addr: listenAddr, Handler: mux, ReadHeaderTimeout: 10 * time.Second, // Security: prevent Slowloris attacks ReadTimeout: 30 * time.Second, // Extended timeout for OAuth discovery @@ -1205,7 +1403,8 @@ func (m *CallbackServerManager) StartCallbackServer(serverName string, preferred RedirectURI: redirectURI, Server: server, ServerName: serverName, - logger: m.logger.With(zap.String("server", serverName), zap.Int("port", port)), + BindHost: bindHost, + logger: logger.With(zap.String("server", serverName), zap.String("bind_host", bindHost), zap.Int("port", port)), waiters: make(map[string]chan map[string]string), } @@ -1237,7 +1436,7 @@ func (m *CallbackServerManager) StartCallbackServer(serverName string, preferred

Port: %d

- `, r.URL.Path, DefaultRedirectPath, serverName, port) + `, html.EscapeString(r.URL.Path), DefaultRedirectPath, html.EscapeString(serverName), port) if _, err := w.Write([]byte(debugPage)); err != nil { callbackServer.logger.Error("Error writing debug page", zap.Error(err)) } @@ -1299,6 +1498,16 @@ func (c *CallbackServer) UnregisterState(state string) { } } +// waiterCount reports how many flows are currently parked on this server. +// Used to decide whether a cached server may be torn down: replacing one that +// still has a waiter drops a live flow, whose browser then lands on a closed +// port (see StartCallbackServerOnHost). +func (c *CallbackServer) waiterCount() int { + c.waitersMu.Lock() + defer c.waitersMu.Unlock() + return len(c.waiters) +} + // HasState reports whether a flow is currently waiting for this state. func (c *CallbackServer) HasState(state string) bool { c.waitersMu.Lock() @@ -1468,9 +1677,21 @@ func GetCallbackServer(serverName string) (*CallbackServer, bool) { // StopCallbackServer stops and removes the callback server for a given server name func (m *CallbackServerManager) StopCallbackServer(serverName string) error { + return m.StopCallbackServerWithLogger(serverName, nil) +} + +// StopCallbackServerWithLogger is StopCallbackServer with the caller's logger, +// so the tear-down (and any waiter it drops) is actually recorded. +func (m *CallbackServerManager) StopCallbackServerWithLogger(serverName string, logger *zap.Logger) error { m.mu.Lock() defer m.mu.Unlock() + return m.stopCallbackServerLocked(serverName, m.adoptLoggerLocked(logger)) +} + +// stopCallbackServerLocked shuts the server down and removes it from the map. +// m.mu must be held. +func (m *CallbackServerManager) stopCallbackServerLocked(serverName string, logger *zap.Logger) error { server, exists := m.servers[serverName] if !exists { return nil // Already stopped or never started @@ -1481,7 +1702,7 @@ func (m *CallbackServerManager) StopCallbackServer(serverName string) error { defer cancel() if err := server.Server.Shutdown(ctx); err != nil { - m.logger.Error("Error shutting down OAuth callback server", + logger.Error("Error shutting down OAuth callback server", zap.String("server", serverName), zap.Error(err)) } @@ -1490,7 +1711,7 @@ func (m *CallbackServerManager) StopCallbackServer(serverName string) error { // the channels are left unclosed so a parked flow never mistakes a // zero-value receive for a real callback. if dropped := server.dropAllWaiters(); dropped > 0 { - m.logger.Warn("Stopped OAuth callback server while flows were still waiting", + logger.Warn("Stopped OAuth callback server while flows were still waiting", zap.String("server", serverName), zap.Int("waiters", dropped)) } @@ -1498,8 +1719,9 @@ func (m *CallbackServerManager) StopCallbackServer(serverName string) error { // Remove from map delete(m.servers, serverName) - m.logger.Info("OAuth callback server stopped", + logger.Info("OAuth callback server stopped", zap.String("server", serverName), + zap.String("bind_host", server.BindHost), zap.Int("port", server.Port)) return nil diff --git a/internal/oauth/redirect_uri_followup_test.go b/internal/oauth/redirect_uri_followup_test.go new file mode 100644 index 000000000..c9cd8d873 --- /dev/null +++ b/internal/oauth/redirect_uri_followup_test.go @@ -0,0 +1,399 @@ +package oauth + +import ( + "fmt" + "net" + "testing" + + "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "go.uber.org/zap" + "go.uber.org/zap/zapcore" + "go.uber.org/zap/zaptest/observer" +) + +// observedLogger returns a real logger plus the records it captured, and +// restores the global callback manager's logger afterwards (it is process-wide). +func observedLogger(t *testing.T) (*zap.Logger, *observer.ObservedLogs) { + t.Helper() + core, logs := observer.New(zapcore.DebugLevel) + logger := zap.New(core) + + mgr := GetGlobalCallbackManager() + mgr.mu.RLock() + previous := mgr.logger + mgr.mu.RUnlock() + t.Cleanup(func() { + mgr.mu.Lock() + mgr.logger = previous + mgr.mu.Unlock() + }) + return logger, logs +} + +func reserveIPv6LoopbackPort(t *testing.T) int { + t.Helper() + ln, err := net.Listen("tcp", "[::1]:0") + if err != nil { + t.Skipf("host has no usable IPv6 loopback: %v", err) + } + port := ln.Addr().(*net.TCPAddr).Port + require.NoError(t, ln.Close()) + return port +} + +// --- D1: an ::1 pin must actually be bound on ::1 ------------------------- + +// TestPinnedIPv6RedirectURI_IsActuallyBound covers D1: ParsePinnedRedirectURI +// accepts "::1" and the URI is sent to the provider verbatim, but the callback +// listener used to be hard-coded to 127.0.0.1. The authorize URL then named a +// host nothing was listening on and the login hung to the callback timeout. +func TestPinnedIPv6RedirectURI_IsActuallyBound(t *testing.T) { + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + port := reserveIPv6LoopbackPort(t) + pinned := fmt.Sprintf("http://[::1]:%d/oauth/callback", port) + + serverName := "ipv6-pinned-server" + stopCallbackServer(t, serverName) + + oauthConfig := CreateOAuthConfig(&config.ServerConfig{ + Name: serverName, + URL: upstream.URL + "/mcp", + OAuth: &config.OAuthConfig{ClientID: "static-client", RedirectURI: pinned}, + }, store) + require.NotNil(t, oauthConfig) + assert.Equal(t, pinned, oauthConfig.RedirectURI) + + cb, ok := GetCallbackServer(serverName) + require.True(t, ok) + assert.Equal(t, config.LoopbackIPv6Host, cb.BindHost, "an ::1 pin must bind ::1") + assert.Equal(t, port, cb.Port) + + conn, err := net.Dial("tcp", fmt.Sprintf("[::1]:%d", port)) + require.NoError(t, err, "the pinned ::1 endpoint must accept connections") + require.NoError(t, conn.Close()) +} + +// TestDefaultCallbackBinding_StaysIPv4 guards the unpinned default: no config +// change should move the callback server off 127.0.0.1. +func TestDefaultCallbackBinding_StaysIPv4(t *testing.T) { + serverName := "default-binding-server" + stopCallbackServer(t, serverName) + + cb, err := GetGlobalCallbackManager().StartCallbackServer(serverName, 0) + require.NoError(t, err) + assert.Equal(t, config.LoopbackIPv4Host, cb.BindHost) + assert.Contains(t, cb.RedirectURI, "http://127.0.0.1:") +} + +// --- Blocking #1 (D2): the callback surface must reach a real logger ------ + +// TestCallbackManagerLogsThroughCallerLogger covers the half of D2 that the +// first pass missed: createOAuthConfigInternal got a real logger, but the +// global callback manager kept zap.L() — the NO-OP logger, since +// zap.ReplaceGlobals is never called in this binary. Every record describing +// the callback server was therefore discarded at all levels, including the +// tear-down of a live listener, a dropped waiter and a failed bind on a pinned +// port. +func TestCallbackManagerLogsThroughCallerLogger(t *testing.T) { + logger, logs := observedLogger(t) + + serverName := "logged-callback-server" + stopCallbackServer(t, serverName) + mgr := GetGlobalCallbackManager() + + // Occupy a port, then ask for it: the fallback must be recorded. + squatter, err := net.Listen("tcp", "127.0.0.1:0") + require.NoError(t, err) + defer squatter.Close() + occupied := squatter.Addr().(*net.TCPAddr).Port + + cb, err := mgr.StartCallbackServerOnHost(serverName, CallbackBinding{ + Port: occupied, + Pinned: false, + Logger: logger, + }) + require.NoError(t, err) + require.NotEqual(t, occupied, cb.Port, "the occupied port cannot be bound") + + assert.NotEmpty(t, logs.FilterMessage("Preferred port unavailable, falling back to dynamic allocation").All(), + "the only record of WHY a preferred port could not be bound must be emitted") + assert.NotEmpty(t, logs.FilterMessage("OAuth callback server started successfully").All(), + "the started/redirect_uri record must be emitted") + + // A tear-down that drops a parked waiter must be recorded too. + cb.RegisterState("state-being-dropped") + require.NoError(t, mgr.StopCallbackServerWithLogger(serverName, logger)) + assert.NotEmpty(t, logs.FilterMessage("Stopped OAuth callback server while flows were still waiting").All(), + "dropping a live waiter must be visible in the logs") +} + +// TestManagerLoggerIsNotNoOpAfterConfigCreation asserts the manager stops being +// blind once a real flow has run through createOAuthConfigInternal. +func TestManagerLoggerIsNotNoOpAfterConfigCreation(t *testing.T) { + logger, _ := observedLogger(t) + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "manager-logger-server" + stopCallbackServer(t, serverName) + + _, err := CreateOAuthConfigWithLogger(&config.ServerConfig{ + Name: serverName, + URL: upstream.URL + "/mcp", + OAuth: &config.OAuthConfig{ClientID: "static-client"}, + }, store, logger) + require.NoError(t, err) + + mgr := GetGlobalCallbackManager() + mgr.mu.RLock() + got := mgr.logger + mgr.mu.RUnlock() + require.NotNil(t, got) + assert.NotEqual(t, zap.NewNop().Core(), got.Core(), + "the callback manager must not still be writing into the no-op logger") +} + +// TestOAuthLoggerNameAppliedOnce guards against the "oauth.oauth" logger name, +// which breaks every filter written against the documented name. +func TestOAuthLoggerNameAppliedOnce(t *testing.T) { + core, logs := observer.New(zapcore.DebugLevel) + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "logger-name-server" + stopCallbackServer(t, serverName) + _, restore := swapManagerLogger(t) + defer restore() + + _, err := CreateOAuthConfigWithLogger(&config.ServerConfig{ + Name: serverName, + URL: upstream.URL + "/mcp", + OAuth: &config.OAuthConfig{ClientID: "static-client"}, + }, store, zap.New(core)) + require.NoError(t, err) + + entries := logs.All() + require.NotEmpty(t, entries) + // Only two names are legitimate: the package logger and the callback + // sub-logger derived from it. "oauth.oauth" means namedOAuthLogger ran twice. + allowed := map[string]bool{ + oauthLoggerName: true, + oauthLoggerName + "." + oauthCallbackLoggerName: true, + } + for _, e := range entries { + assert.True(t, allowed[e.LoggerName], + "unexpected logger name %q — namedOAuthLogger must be idempotent", e.LoggerName) + } +} + +func swapManagerLogger(t *testing.T) (*zap.Logger, func()) { + t.Helper() + mgr := GetGlobalCallbackManager() + mgr.mu.RLock() + previous := mgr.logger + mgr.mu.RUnlock() + return previous, func() { + mgr.mu.Lock() + mgr.logger = previous + mgr.mu.Unlock() + } +} + +// --- Blocking #2: a live waiter must survive a binding mismatch ----------- + +// TestCachedCallbackServerWithLiveWaiterIsNotReplaced covers the regression the +// first pass introduced: an unconditional "replace on binding mismatch" guard +// tore down a listener a flow was parked on. Reachable with a static client_id +// whose stored callback port is occupied by another process — attempt 1 falls +// back to a dynamic port, attempt 2 still prefers the stored port, and the +// server could never finish a login while that port stayed occupied. +func TestCachedCallbackServerWithLiveWaiterIsNotReplaced(t *testing.T) { + logger, _ := observedLogger(t) + serverName := "live-waiter-server" + stopCallbackServer(t, serverName) + mgr := GetGlobalCallbackManager() + + first, err := mgr.StartCallbackServerOnHost(serverName, CallbackBinding{Logger: logger}) + require.NoError(t, err) + portA := first.Port + first.RegisterState("live-state-123") + + portB := reserveLoopbackPort(t) + require.NotEqual(t, portA, portB) + + second, err := mgr.StartCallbackServerOnHost(serverName, CallbackBinding{ + Port: portB, + Pinned: false, + Logger: logger, + }) + require.NoError(t, err) + + assert.Same(t, first, second, "the cached server must be reused, not replaced") + assert.True(t, first.HasState("live-state-123"), "the parked waiter must survive") + + conn, dialErr := net.Dial("tcp", fmt.Sprintf("127.0.0.1:%d", portA)) + require.NoError(t, dialErr, "the live listener must still accept connections") + require.NoError(t, conn.Close()) +} + +// TestStaleCallbackServerWithoutWaitersIsReplaced covers the case the guard was +// written for (D4): a timed-out flow leaves a cached server on the old port, and +// a later pinned reconnect must get the pinned port rather than the stale one. +func TestStaleCallbackServerWithoutWaitersIsReplaced(t *testing.T) { + logger, _ := observedLogger(t) + serverName := "stale-server" + stopCallbackServer(t, serverName) + mgr := GetGlobalCallbackManager() + + stale, err := mgr.StartCallbackServerOnHost(serverName, CallbackBinding{Logger: logger}) + require.NoError(t, err) + require.Zero(t, stale.waiterCount()) + + pinnedPort := reserveLoopbackPort(t) + require.NotEqual(t, stale.Port, pinnedPort) + + fresh, err := mgr.StartCallbackServerOnHost(serverName, CallbackBinding{ + Port: pinnedPort, + Pinned: true, + Logger: logger, + }) + require.NoError(t, err) + assert.Equal(t, pinnedPort, fresh.Port, "a pinned reconnect must not inherit the stale port") + assert.NotSame(t, stale, fresh) +} + +// --- Blocking #3 / D5: DCR hygiene must not be skipped by a pin ----------- + +// TestPinnedPortClearsDCRCredentialsRegisteredForAnotherPort covers the +// feature's most likely upgrade path: log in unpinned (DCR registers port A), +// then add oauth.redirect_uri with port B because the provider rejected the +// moving port. Reusing the port-A registration under a port-B redirect_uri is a +// permanent redirect_uri_mismatch that no retry clears. +func TestPinnedPortClearsDCRCredentialsRegisteredForAnotherPort(t *testing.T) { + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "stale-dcr-under-pin" + stopCallbackServer(t, serverName) + serverURL := upstream.URL + "/mcp" + serverKey := GenerateServerKey(serverName, serverURL) + + storedPort := reserveLoopbackPort(t) + pinnedPort := reserveLoopbackPort(t) + require.NotEqual(t, storedPort, pinnedPort) + require.NoError(t, store.UpdateOAuthClientCredentials(serverKey, "dcr-registered-for-storedPort", "secret", storedPort)) + + oauthConfig := CreateOAuthConfig(&config.ServerConfig{ + Name: serverName, + URL: serverURL, + OAuth: &config.OAuthConfig{ + RedirectURI: fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", pinnedPort), + }, + }, store) + require.NotNil(t, oauthConfig) + + assert.Empty(t, oauthConfig.ClientID, + "a DCR client registered for another port must not be shipped with the new pinned redirect_uri") + storedClientID, _, _, err := store.GetOAuthClientCredentials(serverKey) + require.NoError(t, err) + assert.Empty(t, storedClientID, "the stale DCR record must be cleared so the next login re-registers") +} + +// TestPinnedPortClearsLegacyDCRCredentials covers D5 proper: the pinned branch +// used to short-circuit the storage read entirely, so the Spec 022 legacy +// cleanup never ran for a pinned server. +func TestPinnedPortClearsLegacyDCRCredentials(t *testing.T) { + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "legacy-dcr-under-pin" + stopCallbackServer(t, serverName) + serverURL := upstream.URL + "/mcp" + serverKey := GenerateServerKey(serverName, serverURL) + + require.NoError(t, store.UpdateOAuthClientCredentials(serverKey, "dcr-old", "secret", 0)) + + pinnedPort := reserveLoopbackPort(t) + oauthConfig := CreateOAuthConfig(&config.ServerConfig{ + Name: serverName, + URL: serverURL, + OAuth: &config.OAuthConfig{ + RedirectURI: fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", pinnedPort), + }, + }, store) + require.NotNil(t, oauthConfig) + + storedClientID, _, _, err := store.GetOAuthClientCredentials(serverKey) + require.NoError(t, err) + assert.Empty(t, storedClientID, "legacy DCR credentials must be cleared even when a port is pinned") +} + +// TestPinnedPortKeepsStaticCredentials guards the other side: a static +// client_id is operator-supplied and can never be re-registered, so a pin that +// disagrees with the stored port must not wipe it. +func TestPinnedPortKeepsStaticCredentials(t *testing.T) { + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "static-under-pin" + stopCallbackServer(t, serverName) + serverURL := upstream.URL + "/mcp" + serverKey := GenerateServerKey(serverName, serverURL) + + storedPort := reserveLoopbackPort(t) + require.NoError(t, store.UpdateOAuthClientCredentials(serverKey, "static-client", "static-secret", storedPort)) + + pinnedPort := reserveLoopbackPort(t) + require.NotEqual(t, storedPort, pinnedPort) + + oauthConfig := CreateOAuthConfig(&config.ServerConfig{ + Name: serverName, + URL: serverURL, + OAuth: &config.OAuthConfig{ + ClientID: "static-client", + RedirectURI: fmt.Sprintf("http://127.0.0.1:%d/oauth/callback", pinnedPort), + }, + }, store) + require.NotNil(t, oauthConfig) + assert.Equal(t, "static-client", oauthConfig.ClientID) + + storedClientID, _, _, err := store.GetOAuthClientCredentials(serverKey) + require.NoError(t, err) + assert.Equal(t, "static-client", storedClientID, "static credentials must never be cleared") +} + +// --- D3: the failure names redirect_uri ------------------------------------ + +// TestMalformedPinReturnsActionableError covers D3: the caller's message +// ("failed to create OAuth config - server may not support OAuth") never +// mentioned redirect_uri, which made a typo a permanent undiagnosable failure. +func TestMalformedPinReturnsActionableError(t *testing.T) { + logger, logs := observedLogger(t) + upstream := newUnreachableUpstream(t) + store := setupTestStorage(t) + + serverName := "bad-pin-server" + stopCallbackServer(t, serverName) + + cfg, err := CreateOAuthConfigWithLogger(&config.ServerConfig{ + Name: serverName, + URL: upstream.URL + "/mcp", + OAuth: &config.OAuthConfig{ClientID: "static", RedirectURI: "https://evil.example.com/nope"}, + }, store, logger) + + assert.Nil(t, cfg) + require.Error(t, err) + assert.Contains(t, err.Error(), "oauth.redirect_uri") + assert.Contains(t, err.Error(), serverName) + + assert.NotEmpty(t, logs.FilterMessageSnippet("Invalid oauth.redirect_uri").All(), + "the diagnostic must reach a real logger, not zap.L()") + + _, ok := GetCallbackServer(serverName) + assert.False(t, ok, "no callback server should be started for a malformed pin") +} diff --git a/internal/server/mcp.go b/internal/server/mcp.go index 069e41dcc..74ebbda12 100644 --- a/internal/server/mcp.go +++ b/internal/server/mcp.go @@ -4601,6 +4601,11 @@ func (p *MCPProxyServer) handleAddUpstream(ctx context.Context, request mcp.Call if err := json.Unmarshal([]byte(oauthJSON), &oauthConfig); err != nil { return mcp.NewToolResultError(fmt.Sprintf("Invalid oauth_json format: %v", err)), nil } + // Reject a malformed oauth.redirect_uri here, where the caller is + // typing it: it is otherwise a permanent connect failure. + if err := oauthConfig.Validate(); err != nil { + return mcp.NewToolResultError(fmt.Sprintf("Invalid oauth_json: %v", err)), nil + } oauth = &oauthConfig } @@ -5194,6 +5199,9 @@ func (p *MCPProxyServer) buildPatchConfigFromRequest(request mcp.CallToolRequest if err := json.Unmarshal([]byte(oauthJSON), &oauth); err != nil { return nil, opts, fmt.Errorf("invalid oauth_json format: %v", err) } + if err := oauth.Validate(); err != nil { + return nil, opts, fmt.Errorf("invalid oauth_json: %w", err) + } patch.OAuth = &oauth } } diff --git a/internal/upstream/core/client.go b/internal/upstream/core/client.go index ca7da50b6..2b119adeb 100644 --- a/internal/upstream/core/client.go +++ b/internal/upstream/core/client.go @@ -28,6 +28,7 @@ import ( "github.com/mark3labs/mcp-go/client/transport" "github.com/mark3labs/mcp-go/mcp" "go.uber.org/zap" + "go.uber.org/zap/zapcore" ) // Client implements basic MCP client functionality without state management @@ -877,3 +878,29 @@ func containsString(str, substr string) bool { } return false } + +// oauthLogger returns the logger the OAuth layer should write through. +// +// It tees the main logger and this upstream's own per-server log. Both halves +// matter: +// +// - c.logger reaches main.log, where operators and the docs look first. +// - c.upstreamLogger writes server-.log, which is what +// `mcpproxy upstream logs ` serves. docs/configuration.md points the +// operator at that command for a redirect_uri failure, so the records have +// to actually be there — otherwise they find nothing and conclude the +// diagnostic does not exist. +// +// Before this, internal/oauth logged through zap.L(), which is the no-op logger +// in this binary (zap.ReplaceGlobals is never called), so neither destination +// got anything at all. +func (c *Client) oauthLogger() *zap.Logger { + switch { + case c.upstreamLogger == nil: + return c.logger + case c.logger == nil: + return c.upstreamLogger + default: + return zap.New(zapcore.NewTee(c.logger.Core(), c.upstreamLogger.Core())) + } +} diff --git a/internal/upstream/core/connection_oauth.go b/internal/upstream/core/connection_oauth.go index d9254aec7..1306a1a9c 100644 --- a/internal/upstream/core/connection_oauth.go +++ b/internal/upstream/core/connection_oauth.go @@ -226,15 +226,15 @@ func (c *Client) tryOAuthAuth(ctx context.Context) error { logger.Debug("🔧 Creating OAuth config with resource auto-detection") // Create OAuth config with auto-detected extra params (RFC 8707 resource) - oauthConfig, extraParams := oauth.CreateOAuthConfigWithExtraParams(ctx, c.config, c.storage) + oauthConfig, extraParams, oauthConfigErr := oauth.CreateOAuthConfigWithExtraParamsAndLogger(ctx, c.config, c.storage, c.oauthLogger()) c.logger.Debug("OAuth config created", zap.Bool("config_nil", oauthConfig == nil), zap.Int("extra_params_count", len(extraParams))) if oauthConfig == nil { - c.logger.Error("🚨 OAUTH CONFIG IS NIL - RETURNING ERROR") - oauthErr = fmt.Errorf("failed to create OAuth config") + c.logger.Error("🚨 OAUTH CONFIG IS NIL - RETURNING ERROR", zap.Error(oauthConfigErr)) + oauthErr = wrapOAuthConfigError(oauthConfigErr) return oauthErr } @@ -666,9 +666,10 @@ func (c *Client) trySSEOAuthAuth(ctx context.Context) error { } // Create OAuth config with auto-detected extra params (RFC 8707 resource) - oauthConfig, extraParams := oauth.CreateOAuthConfigWithExtraParams(ctx, c.config, c.storage) + oauthConfig, extraParams, oauthConfigErr := oauth.CreateOAuthConfigWithExtraParamsAndLogger(ctx, c.config, c.storage, c.oauthLogger()) if oauthConfig == nil { - oauthErr = fmt.Errorf("failed to create OAuth config") + c.logger.Error("🚨 Failed to create OAuth config", zap.Error(oauthConfigErr)) + oauthErr = wrapOAuthConfigError(oauthConfigErr) return oauthErr } @@ -1809,12 +1810,13 @@ func (c *Client) StartOAuthFlowQuick(ctx context.Context) (*OAuthStartResult, er } // Create OAuth config - oauthConfig, extraParams := oauth.CreateOAuthConfigWithExtraParams(ctx, c.config, c.storage) + oauthConfig, extraParams, oauthConfigErr := oauth.CreateOAuthConfigWithExtraParamsAndLogger(ctx, c.config, c.storage, c.oauthLogger()) if oauthConfig == nil { c.logger.Error("❌ Failed to create OAuth config", zap.String("server", c.config.Name), - zap.String("correlation_id", result.CorrelationID)) - return result, fmt.Errorf("failed to create OAuth config - server may not support OAuth") + zap.String("correlation_id", result.CorrelationID), + zap.Error(oauthConfigErr)) + return result, wrapOAuthConfigError(oauthConfigErr) } // Phase 2 (Spec 020): Pre-flight OAuth metadata validation @@ -2287,12 +2289,31 @@ func (c *Client) ForceOAuthFlowWithResult(ctx context.Context) (*OAuthStartResul } } +// wrapOAuthConfigError turns a nil OAuth config into an error the operator can +// act on. +// +// The historical message — "failed to create OAuth config - server may not +// support OAuth" — never mentioned the actual cause. A malformed +// `oauth.redirect_uri` is the common one, and it is a PERMANENT failure: the +// operator saw a generic "server may not support OAuth" forever, with no hint +// that a field they typed was to blame. When internal/oauth reports a reason, +// carry it through so it reaches the connection error and the health detail. +func wrapOAuthConfigError(err error) error { + if err != nil { + return fmt.Errorf("failed to create OAuth config: %w", err) + } + return fmt.Errorf("failed to create OAuth config - server may not support OAuth") +} + // forceHTTPOAuthFlowWithResult forces OAuth flow for HTTP transport and returns auth URL/browser status. func (c *Client) forceHTTPOAuthFlowWithResult(ctx context.Context) (*OAuthStartResult, error) { // Create OAuth config with auto-detected extra params (RFC 8707 resource) - oauthConfig, extraParams := oauth.CreateOAuthConfigWithExtraParams(ctx, c.config, c.storage) + oauthConfig, extraParams, oauthConfigErr := oauth.CreateOAuthConfigWithExtraParamsAndLogger(ctx, c.config, c.storage, c.oauthLogger()) if oauthConfig == nil { - return nil, fmt.Errorf("failed to create OAuth config - server may not support OAuth") + c.logger.Error("❌ Failed to create OAuth config", + zap.String("server", c.config.Name), + zap.Error(oauthConfigErr)) + return nil, wrapOAuthConfigError(oauthConfigErr) } c.logger.Info("🌐 Starting manual HTTP OAuth flow with result tracking...", @@ -2355,9 +2376,12 @@ func (c *Client) forceHTTPOAuthFlowWithResult(ctx context.Context) (*OAuthStartR // forceSSEOAuthFlowWithResult forces OAuth flow for SSE transport and returns auth URL/browser status. func (c *Client) forceSSEOAuthFlowWithResult(ctx context.Context) (*OAuthStartResult, error) { // Create OAuth config with auto-detected extra params (RFC 8707 resource) - oauthConfig, extraParams := oauth.CreateOAuthConfigWithExtraParams(ctx, c.config, c.storage) + oauthConfig, extraParams, oauthConfigErr := oauth.CreateOAuthConfigWithExtraParamsAndLogger(ctx, c.config, c.storage, c.oauthLogger()) if oauthConfig == nil { - return nil, fmt.Errorf("failed to create OAuth config - server may not support OAuth") + c.logger.Error("❌ Failed to create OAuth config", + zap.String("server", c.config.Name), + zap.Error(oauthConfigErr)) + return nil, wrapOAuthConfigError(oauthConfigErr) } c.logger.Info("🌐 Starting manual SSE OAuth flow with result tracking...", From d34129869734280b59d578e6ef8afbc691ceca81 Mon Sep 17 00:00:00 2001 From: Algis Dumbris Date: Thu, 27 Aug 2026 12:10:14 +0300 Subject: [PATCH 2/2] docs(oauth): correct the GitHub wildcard-matching claim GitHub added per-callback-URL wildcard matching in August 2026, so "rejects wildcards" is no longer accurate. The argument for pinning the port is unchanged and is what GitHub actually documents: wildcard matching covers subdomains and subdirectory paths, while the host and port must still match the registered callback exactly. --- docs/configuration.md | 7 ++++--- docs/mcp-go-oauth.md | 6 ++++-- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 18b89f6d3..93154b078 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -549,9 +549,10 @@ explicitly to one of `http`, `sse`, or `streamable-http`. By default mcpproxy asks the OS for a free loopback port on the first OAuth login, then persists that port and tries to reuse it. If the saved port is taken next time, a different one is allocated — so the callback URL is not guaranteed -to stay put. Some providers — notably GitHub OAuth Apps — require the callback -URL to match the registered one **exactly** and reject wildcards, so the port -must not move at all. +to stay put. Some providers require the port to match the registered callback +URL exactly, so it must not move at all. GitHub OAuth Apps are the common case: +even with GitHub's wildcard matching enabled, that matching covers subdomains +and subdirectory paths only — the host and port must still match exactly. Set `redirect_uri` to pin it. mcpproxy then binds that exact port and sends that exact string to the provider as `redirect_uri`: diff --git a/docs/mcp-go-oauth.md b/docs/mcp-go-oauth.md index 31b7cbfc5..11b2ffee9 100644 --- a/docs/mcp-go-oauth.md +++ b/docs/mcp-go-oauth.md @@ -208,8 +208,10 @@ This enables runtime onboarding of AI agents. - Providers that allow a loopback wildcard or prefix match (some self-hosted authorization servers, and the pattern RFC 8252 §7.3 recommends) can register `http://127.0.0.1:*` and let mcpproxy allocate a port per login. -- Providers that require an **exact** callback URL — GitHub OAuth Apps among - them — reject wildcards outright. For those, pin the port with the per-server +- Providers that require an **exact** port. GitHub OAuth Apps are the common + case: GitHub's wildcard matching covers subdomains and subdirectory paths, but + the host and port must still match the registered callback exactly, and + `http://127.0.0.1:*` is not valid syntax there. For those, pin the port with the per-server `oauth.redirect_uri` setting and register that exact string with the provider. See [Pinning the callback port](configuration.md#pinning-the-callback-port-with-redirect_uri). - Use Cloudflare Workers for fixed-domain callbacks.