fix(mcp): recover an MCP OAuth refresh whose response never reached the client

AG
3h ago
+504-44

What

A hosted MCP connector lost its connection roughly a day after each reconnect: a timeout, then HTTP 401 on every call until the user reconnected.

A refresh rotates the token pair before the response is written. When that response never reaches the client and the client retries with the refresh token it still holds more than 30 seconds later, the server treated the retry as refresh-token reuse and revoked the whole grant. This is the self-hosted twin of the same fix on the hosted edition, and it follows the same rules.

Change

  • Each rotation records the exact successor refresh-token hash and the retired token's own expiry on the retired-token row.
  • Bearer admission records the first authenticated use of each pair (mcp_oauth_sessions.current_pair_used_at). Rotation clears it.
  • A retired refresh token is recoverable when its client and resource match, the grant is live, its recorded successor pair has never been used as a bearer token, its own expiry has not passed, and at most 36 hours have passed since the first rotation. The server then rotates the undelivered pair again, under a row lock, and returns the new pair on the same grant, agent identity and scopes. The re-issued pair keeps its refresh expiry, so recovery never extends the grant.
  • A retry within 30 seconds of the rotation, or within 30 seconds of a recovery, is refused with invalid_grant and revokes nothing (two retries racing each other).
  • Reuse of a retired token whose successor pair was used still revokes the grant, as before.
  • Each refresh decision is logged as mcp_oauth_refresh with an outcome and reason and no token material.

Behaviour changes to review

  1. Migration 0084 adds mcp_oauth_sessions.current_pair_used_at and, on mcp_oauth_retired_refresh_tokens, successor_token_hash, refresh_token_expires_at and reissued_at. All nullable, no backfill. The verifier schema manifest is refreshed in its own commit.
  2. Revocation endpoint: revoking a retired refresh token now ends its grant (before, an unknown-token no-op). A client mismatch is still ignored.
  3. Bearer admission fails closed on a lost race: a request whose access token was rotated or re-issued away between the session read and the first-use mark is refused with 401 instead of being admitted on the old pair. Without this an unused pair could be both used and re-issued.
  4. Kept difference from the hosted edition: a retired token presented by the wrong client is answered invalid_grant, and one for the wrong resource invalid_target, in both cases without revoking and before the 30-second check. The hosted edition revokes on such a mismatch after 30 seconds. This keeps the existing self-hosted answers.
  5. Rolling upgrade: pairs rotated before the upgrade have no recorded successor and are never re-issued, so they keep the previous behaviour. During a rolling upgrade an old replica does not mark first use; a pair first used only through an old replica can be re-issued once by a new one. Run the migration before the new image, as usual.

The agent identity and the relay inbox position are untouched: recovery keeps the grant, and both are bound to the grant.

Checks

Local, on this head, one suite at a time:

  • tsc --noEmit: pass
  • test/mcp-oauth-token-flow.test.ts: 36/36 (20 new cases: a lost response is re-issued, and re-issued again when that response is lost too; a retry racing a recovery or the rotation is refused without revoking; two concurrent recoveries; recovery refused once the successor pair was used, past 36 hours, past the retired token's own expiry, for another client id, and for a retired row from before the upgrade; only the exact successor session is re-issued on a grant with several sessions; re-issue keeps the refresh expiry; revoking a retired token ends its grant)
  • test/mcp-oauth-sessions.test.ts: 10 pass, 1 skipped
  • mcp-oauth-admission 57/57, mcp-oauth-store 11/11, mcp-oauth-http 16/16, mcp-oauth-public-handlers 5/5, mcp-oauth-departure 4/4, mcp-oauth-oidc 6/6, grok-routines 21/21, migrations 11/11, mcp 61/61
  • Import verifier dry run against PostgreSQL 15 with the refreshed manifest: 109/109. The manifest diff is the 0084 hash, the four new columns and the seal.
  • mcp-oauth-postgres (4) and cloud-import-verify (21) need a PostgreSQL URL and are skipped locally; CI runs them.

One case in test/mcp-oauth-sessions.test.ts needs a PostgreSQL URL and is skipped locally, as on main.

Held for the owner's merge decision.

🤖 Generated with Claude Code


Proof this PR
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Fixes MCP OAuth connections being revoked when a refresh response never reached the client.

Previously a refresh rotated the token pair before the response was written; if that response was lost and the client retried more than 30 seconds later with the refresh token it still held, the retry counted as token reuse and revoked the entire grant, forcing a reconnect.

Now each rotation records its exact successor token hash on the retired token, and bearer admission records first use of each pair. If the successor pair has never been used, a retired refresh token re-rotates that pair and returns the new pair on the same grant, for up to 36 hours after the first rotation and never past the retired token's own expiry. Re-issued pairs keep their refresh expiry, so recovery never extends the grant. A retry within 30 seconds of a rotation or recovery is refused without revoking; reuse after the successor pair was used still revokes the grant. Revoking a retired refresh token at the revocation endpoint now ends its grant. Each refresh logs one mcp_oauth_refresh line with outcome and reason, never token material.

Behavior changes

  • Migration 0084 adds the tracking columns, all nullable, no backfill.
  • Pairs rotated before the upgrade have no recorded successor and keep the previous behavior; run the migration before deploying the new image.
  • Bearer admission refuses a token rotated or re-issued away between the session read and the first-use mark, so an unused pair is never both used and re-issued.
  • A retired token presented by the wrong client is answered invalid_grant, one for the wrong resource invalid_target, without revoking — keeping the existing self-hosted answers.
  • During a rolling upgrade, a pair first used only through an old replica can be re-issued once by a new one.