Skip to content

fix(oauth): make the redirect_uri pin actually reachable, diagnosable and validated - #1070

Merged
github-actions[bot] merged 2 commits into
mainfrom
fix/oauth-redirect-uri-followup
Aug 27, 2026
Merged

github-actions[bot] merged 2 commits into
mainfrom
fix/oauth-redirect-uri-followup

Conversation

@Dumbris

@Dumbris Dumbris commented Aug 27, 2026

Copy link
Copy Markdown
Member

Follow-up to #1069, which made the per-server oauth.redirect_uri field load-bearing for the first time. A QA sweep of the merged change — unit, adversarial review, and live end-to-end against tests/oauthserver with DCR disabled — found five defects on that newly-live path. Each was independently verified before being fixed.

What was broken

# Defect Effect
D1 ::1 pins were accepted, blessed by a test and advertised in the docs, but the listener was hard-coded to net.Listen("tcp", "127.0.0.1:PORT") The provider got a [::1] URL nothing listened on. The browser redirect was refused and the login hung to the callback timeout, with no diagnostic.
D2 createOAuthConfigInternal and the callback-server manager logged to zap.L(), which this repo never replaces Every line was discarded — including #1069's new "fail loudly" errors. docs/configuration.md claimed the opposite.
D3 A malformed pin was a permanent connect failure reported as failed to create OAuth config - server may not support OAuth The error never named redirect_uri, and nothing rejected the value at write time. Reachable without typing anything: the Gemini importer copied http://localhost:7777/oauth2callback verbatim.
D4 StartCallbackServer returned a cached server without honoring the requested port After a timed-out flow, a pinned reconnect failed against a port that was actually free.
D5 The pinned path skipped the stored-credential read Spec-022 legacy cleanup never ran, so a DCR registration issued against a different port was reused forever.

What changed

  • D1 — the pin carries its host. ParsePinnedRedirectURI returns (host, port), StartCallbackServerOnHost binds it: localhost and 127.0.0.1 bind IPv4, ::1 binds IPv6. The listener address, http.Server.Addr and CallbackServer.RedirectURI are all built from what was actually bound, so the unpinned path stays consistent too.
  • D2 — the connection's own logger is threaded into createOAuthConfigInternal and the callback-server manager. The old exported signatures are kept as wrappers.
  • D3 — the parse error and the "pinned port unavailable" reason reach the user-visible error. OAuthConfig.Validate() gains a redirect_uri check wired into ValidateDetailed(), so every write surface (REST config API, MCP upstream_servers) rejects a bad value. The boot path deliberately does not: Validate() runs validateDetailedCore(), so a value already on disk cannot brick a load that has nothing to do with the offending server — it fails loudly at connect time instead. The Gemini importer drops a callback URL mcpproxy cannot honor and warns.
  • D4 — re-bind on a port/host mismatch, but only when the cached server has no waiter parked on it, preserving the invariant fix(oauth): dispatch callbacks by state and stop faking success #1068 established.
  • D5 — the storage read always runs; only the port choice short-circuits on a pin. Stale DCR credentials registered against a different port are cleared.

Parsing lives in internal/config.ParsePinnedRedirectURI and internal/oauth delegates to it, so validation and the OAuth flow cannot diverge.

Docs

  • mcp-go-oauth.md §7.1 told operators to register http://127.0.0.1:*. GitHub OAuth Apps reject wildcard callback URLs — this is the advice that sent the reporter of GitHub MCP OAuth DCR opens authorization URL with empty client_id #975 down a dead end. Corrected to distinguish providers that permit a wildcard from those that require an exact URL.
  • errors/MCPX_OAUTH_CALLBACK_MISMATCH.md documented a redirect_port config field that does not exist.
  • configuration.md: the example pinned :8080, mcpproxy's own default listener, so copying it verbatim broke every login; and the section contradicted itself on port allocation.
  • features/oauth-authentication.md still described redirect_uri as cosmetic.

Verification

Live E2E against the in-tree fake provider (DCR disabled, GitHub-shaped), isolated core, headless:

  • R1 static client_id, no pin — port 58007 held across a full core restart (regression guard for fix(oauth): keep the loopback callback port stable for static clients #1069).
  • R2 pinned 127.0.0.1:18942 — sent verbatim, bound exactly, login completed.
  • R3 pinned [::1]:18943 — lsof shows TCP [::1]:18943 (LISTEN); an AF_INET6 connect succeeds while AF_INET to 127.0.0.1:18943 is refused, proving a real IPv6 bind and not dual-stack. The full login completed through the [::1] callback URL.
  • R4 pinned localhost:18944 — binds IPv4, spelling preserved, login completed.
  • R5/R6 malformed pin and occupied pinned port — the log now names redirect_uri, and so does the user-visible error.
  • R7 the REST config API rejects a malformed value at write time; a config file that already contains one still boots and serves every other server.

go build (both editions), gofmt, go test -race across internal/oauth, internal/config, internal/configimport, internal/upstream/..., and golangci-lint v2 with the CI config: all green, 0 issues.

Refs #975, #1066.

Algis Dumbris added 2 commits August 27, 2026 12:08
… and validated

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.
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.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 27, 2026 •

Copy link
Copy Markdown

Deploying mcpproxy-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: d341298
Status:🚫  Build failed.

View logs

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved (Model B): Paperclip review verdicts = ACCEPT and qa-gate green at this head SHA. Arming auto-merge; GitHub merges when all required checks pass.

@github-actions
github-actions Bot enabled auto-merge (squash) August 27, 2026 09:12
@github-actions

Copy link
Copy Markdown
Contributor

📦 Build Artifacts

Workflow Run: View Run
Branch: fix/oauth-redirect-uri-followup

Available Artifacts

  • archive-darwin-amd64 (29 MB)
  • archive-darwin-arm64 (26 MB)
  • archive-linux-amd64 (17 MB)
  • archive-linux-arm64 (15 MB)
  • archive-windows-amd64 (29 MB)
  • archive-windows-arm64 (26 MB)
  • frontend-dist-pr (0 MB)
  • installer-dmg-darwin-amd64 (23 MB)
  • installer-dmg-darwin-arm64 (21 MB)

How to Download

Option 1: GitHub Web UI (easiest)

  1. Go to the workflow run page linked above
  2. Scroll to the bottom "Artifacts" section
  3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 33057272937 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

@codecov-commenter

codecov-commenter commented Aug 27, 2026 •

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 72.76596% with 64 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
internal/oauth/config.go 80.95% 22 Missing and 6 partials ⚠️
internal/upstream/core/connection_oauth.go 0.00% 24 Missing ⚠️
internal/upstream/core/client.go 0.00% 8 Missing ⚠️
internal/server/mcp.go 0.00% 3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

@github-actions
github-actions Bot merged commit 088fc35 into main Aug 27, 2026
37 of 39 checks passed
github-actions Bot pushed a commit that referenced this pull request Aug 27, 2026
#1071)

The `redirect_uri` pin was documented only in `docs/configuration.md`, which is
not in the Docusaurus include list, so the link added in #1070 resolved to
nothing and broke the docs build on main.

Move the guidance to `configuration/upstream-servers.md`, which is the
per-server page the site actually publishes, and point both links at it.
Verified with a local `npm run build` — no broken links.

Co-authored-by: Algis Dumbris <gordon.greatests@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants