Skip to content

fix(oauth): make stdio token refresh waits cancellable - #3893

Open
jonxsong wants to merge 2 commits into
github:mainfrom
jonxsong:codex/fix-oauth-refresh-cancellation
Open

jonxsong wants to merge 2 commits into
github:mainfrom
jonxsong:codex/fix-oauth-refresh-cancellation

Conversation

@jonxsong

Copy link
Copy Markdown

Summary

Let canceled stdio MCP requests stop waiting for an OAuth token refresh. Concurrent requests can still receive the result of the same refresh and reuse the rotated credentials.

Why

When the session token expired, the stdio tool guard called HasToken, which synchronously called oauth2.TokenSource.Token. Authorization resume and the outbound bearer provider could enter the same path. The source uses an independent HTTP context for refresh. That is appropriate for the shared exchange, but it also meant a canceled caller could not return until the exchange released it.

A gated token source reproduced the problem on df32d7ec5786. Both Authenticate and AwaitToken remained blocked after cancellation while the refresh was held. An already-canceled call entered the source and returned success instead of context.Canceled. Installing a newer authorization also left waiters blocked on the old source.

What changed

  • Share one in-flight refresh for the current OAuth token source. Each request waits with its own context. A valid cached token takes the synchronous path.
  • Keep the refresh exchange on the existing bounded OAuth token source. GitHub may rotate the refresh token, so a canceled waiter can leave while the session saves the replacement credentials for other requests.
  • Wake blocked waiters when a new authorization installs a token. The previous exchange cannot overwrite the new token or satisfy an obsolete authorization flow.
  • Carry the caller's context through the stdio tool guard and the REST, GraphQL, and raw-content bearer lookups.

MCP impact

  • No tool or API changes. This adjusts cancellation handling in stdio OAuth and uses the existing tool registrations and OAuth prompt protocol.

Prompts tested (tool changes only)

The authorization tests use synthetic tokens and a gated refresh source. The outbound tests use the configured clients against a local HTTP fixture for REST, GraphQL, and raw content.

Security / limits

  • Auth / permissions considered. The OAuth request path delegates bearer attachment to the existing host-scoped transport. Tests verify caller cancellation, a healthy peer, body closure before dispatch, and suppression of the bearer header for an unlisted host.

Tool renaming

  • I am not renaming tools as part of this PR.

Lint & tests

  • Linted locally with ./script/lint on Linux with golangci-lint v2.14.0.
  • Tested locally with ./script/test (go test -race ./...) on Linux.
  • Windows, Go 1.27.4 — go test -v ./..., the snapshot suite with UPDATE_TOOLSNAPS=true, and a CLI build. The verbose suite passed 32 packages, 1,225 top-level tests, and 7,997 subtests. The new OAuth manager and stdio transport tests each passed 100 consecutive runs. The tagged end-to-end package compiled with execution disabled.
  • Linux, Go 1.27.4 — 100 runs of the focused OAuth tests under the race detector, go mod tidy -diff, a CLI build, and regenerated documentation validation.

Docs

  • Updated the OAuth login guide to describe refresh ownership and request cancellation.

Skills

  • Confirmed no bundled skill applies to the stdio authentication lifecycle.

Related work includes the stdio OAuth introduction, multi-round-trip OAuth migration, and GitHub's refresh token rotation documentation.

AI assistance was used to investigate and reproduce the defect, author the fix and tests, review the diff, and draft this description.

Coalesce refreshes for the current token source and let each OAuth caller wait with its own context. Wake waiters when a newer authorization supplies a token and keep bearer lookup cancellable across the stdio GitHub clients.
@jonxsong
jonxsong requested a review from a team as a code owner November 19, 2026 00:11
Copilot AI adaptive review requested due to automatic review settings November 19, 2026 00:11

Copilot AI 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.

🟡 Changes recommended

The tool guard lacks a cancellation regression test, leaving ignored HasTokenContext errors or use of a non-cancelable context undetected.

1 open issue
What changed in this PR

Makes stdio OAuth token-refresh waits cancellable while allowing the shared refresh to finish and preserve rotated credentials for the session.

Changes:

  • Shares in-flight refreshes and wakes waiters when a newer authorization installs a token.
  • Passes request contexts through the tool guard and REST, GraphQL, and raw-content token lookups.
  • Adds cancellation and transport regression tests, and documents refresh ownership.
File Description
internal/​oauth/​refresh_cancellation_test.go Tests cancellation, shared refreshes, and authorization replacement.
internal/​oauth/​manager.go Adds context-aware token waits and shared-refresh coordination.
internal/​ghmcp/​server.go Connects request contexts to outbound OAuth bearer lookups.
internal/​ghmcp/​server_test.go Updates client setup for the OAuth provider parameter.
internal/​ghmcp/​oauth.go Makes the tool guard’s token check cancellable.
internal/​ghmcp/​oauth_test.go Updates authentication fakes and client setup.
internal/​ghmcp/​oauth_refresh_transport_test.go Tests request cancellation, body closure, and host-scoped bearer handling.
docs/​oauth-login.md Explains shared refreshes and canceled request waits.

Review effort: Max (adaptive)

Comment thread internal/ghmcp/oauth.go
Comment on lines +140 to +143
hasToken, err := mgr.HasTokenContext(ctx)
if err != nil {
return nil, err
}

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Addressed in 1419bf09. I added a regression test for the OAuth tool guard that passes an already-canceled request context and verifies that the guard returns context.Canceled with a nil result, skips authentication, and never calls the tool handler.

I verified that the test fails if the guard drops the token-check error or substitutes context.Background() for the request context. The full Windows Go suite, Linux race suite, and lint passed.

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