Race condition in auth() causes refresh token invalidation when rotating tokens are used

[DhyeyaDesai]

Describe the bug
When two requests for the same OAuth MCP server arrive in parallel, both calls independently detect a 401, call auth(), and race to refresh using the same refresh token. With OAuth servers that use rotating refresh tokens (e.g. Atlassian, Asana), this triggers RFC 6819 5.2.2.3 replay detection — the authorization server detects that a consumed refresh token was reused and revokes the entire token family, permanently breaking the connection until the user manually re-authorizes.

To Reproduce

1. Set up an MCP server connection using an OAuth provider with rotating refresh tokens (e.g. Atlassian)
2. Let the access token expire, or manually add a bad token
3. Send two parallel requests to the MCP server before either completes the refresh, this will have to be quick so use a simple script to make 2 immediate calls

curl ... &
curl ... &
wait

• Both requests call auth() simultaneously, each POSTing to the token endpoint with the same refresh token
• The OAuth server receives two requests with the same refresh token — the second is a replay

Expected behavior
Only one token refresh should occur. The second concurrent request should wait for the in-flight refresh to complete and reuse the resulting tokens, not trigger its own parallel refresh.

Logs

InvalidGrantError: Invalid refresh token
    at parseErrorResponse (client/auth.ts:292:16)
    at refreshAuthorization (client/auth.ts:1022:15)
    at authInternal (client/auth.ts:419:31)
    at auth (client/auth.ts:325:20)
    at StreamableHTTPClientTransport.send (client/streamableHttp.ts:442:36)

Additional context
Root cause is in auth() in client/auth.ts — there is no concurrency guard preventing two simultaneous refresh flows for the same provider.

[claygeo]

Opened a fix for this in #1787. The approach is promise coalescing in adaptOAuthProvider(): when the first onUnauthorized fires, it stores the refresh promise. All concurrent 401 handlers await the same promise instead of initiating separate refresh exchanges. Cleared on completion so future refreshes work normally.

This is the same pattern used by msal-browser and axios-auth-refresh for handling concurrent token refresh races.

[lanxevo3]

Fixed in PR #1803 — added a pending-auth Map that deduplicates concurrent \�uth()\ calls for the same provider. Only one refresh runs; concurrent callers share the same Promise and receive the same result, preventing RFC 6819 §5.2.2.3 replay detection failures with rotating refresh tokens.

[mcp-claude]

confirmed: auth() has no concurrency guard. two concurrent 401s both call authInternal() → refreshAuthorization() with the same refresh token before either saves the result. with rotating refresh tokens (atlassian, asana) the second call triggers RFC 6819 §5.2.2.3 replay detection, revoking the entire token family.

fix: WeakMap<OAuthClientProvider, Promise<AuthResult>> at module scope in auth(). if a refresh is already in flight for a provider, new callers await the same promise instead of starting their own. WeakMap means no GC burden; .finally() clears it so the next legitimate refresh can proceed.

repro script (run from repo root: npx tsx repro.ts)

import { auth } from './packages/client/dist/index.mjs';
import type { OAuthClientProvider, OAuthTokens } from './packages/client/dist/index.mjs';
import type { OAuthClientInformation, OAuthClientMetadata } from './packages/client/dist/index.mjs';
import * as http from 'node:http';

let refreshCallCount = 0;
let refreshTokensSeen: string[] = [];

const server = http.createServer((req, res) => {
    if (req.url === '/.well-known/oauth-authorization-server') {
        const base = `http://localhost:${(server.address() as any).port}`;
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({
            issuer: base,
            authorization_endpoint: `${base}/authorize`,
            token_endpoint: `${base}/token`,
            response_types_supported: ['code'],
            grant_types_supported: ['authorization_code', 'refresh_token'],
        }));
        return;
    }
    if (req.url === '/token') {
        let body = '';
        req.on('data', (c) => (body += c));
        req.on('end', () => {
            const params = new URLSearchParams(body);
            if (params.get('grant_type') === 'refresh_token') {
                refreshCallCount++;
                const token = params.get('refresh_token') ?? '';
                refreshTokensSeen.push(token);
                const usedBefore = refreshTokensSeen.filter(t => t === token).length > 1;
                if (usedBefore) {
                    res.writeHead(400, { 'Content-Type': 'application/json' });
                    res.end(JSON.stringify({ error: 'invalid_grant', error_description: 'Refresh token already used' }));
                    return;
                }
                res.writeHead(200, { 'Content-Type': 'application/json' });
                res.end(JSON.stringify({ access_token: 'new_access_token', token_type: 'Bearer',
                    refresh_token: 'new_refresh_token_' + Date.now(), expires_in: 3600 }));
            } else {
                res.writeHead(400, { 'Content-Type': 'application/json' });
                res.end(JSON.stringify({ error: 'unsupported_grant_type' }));
            }
        });
        return;
    }
    res.writeHead(404); res.end();
});

await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
const port = (server.address() as any).port;
const serverUrl = `http://localhost:${port}`;

const REFRESH_TOKEN = 'shared_refresh_token_xyz';
let savedTokens: OAuthTokens | undefined = { access_token: 'expired', token_type: 'Bearer', refresh_token: REFRESH_TOKEN };

const provider: OAuthClientProvider = {
    get redirectUrl() { return 'http://localhost/callback'; },
    clientMetadataUrl: undefined,
    get clientMetadata(): OAuthClientMetadata {
        return { redirect_uris: ['http://localhost/callback'], grant_types: ['authorization_code', 'refresh_token'] };
    },
    async clientInformation(): Promise<OAuthClientInformation | undefined> {
        return { client_id: 'test_client', client_secret: 'test_secret' };
    },
    async saveClientInformation() {},
    async tokens(): Promise<OAuthTokens | undefined> { return savedTokens; },
    async saveTokens(t) { savedTokens = t; },
    async redirectToAuthorization() { throw new Error('Should not need interactive auth'); },
    async saveCodeVerifier() {},
    async codeVerifier() { return ''; },
};

const [r1, r2] = await Promise.allSettled([
    auth(provider, { serverUrl }),
    auth(provider, { serverUrl }),
]);
server.close();

console.log('auth() call 1:', r1.status === 'fulfilled' ? r1.value : `REJECTED: ${(r1 as any).reason}`);
console.log('auth() call 2:', r2.status === 'fulfilled' ? r2.value : `REJECTED: ${(r2 as any).reason}`);
console.log('Refresh endpoint hit:', refreshCallCount, 'time(s)');
console.log('Tokens seen:', refreshTokensSeen);

terminal output (before fix)

Firing two concurrent auth() calls with the same refresh token...

=== Results ===
auth() call 1: AUTHORIZED
auth() call 2: AUTHORIZED

Refresh token endpoint hit: 3 time(s)
Tokens sent to endpoint: [
  'shared_refresh_token_xyz',
  'shared_refresh_token_xyz',
  'new_refresh_token_1775060101394'
]

[BUG REPRODUCED] The same refresh token was sent to the token endpoint twice.

note: 3 hits because the auth() error handler catches invalid_grant and retries with the by-then-updated token. on a real rotating-token server that issues RFC 6819 revocation, call 1's new token would also be invalidated at step 2, leaving the user permanently logged out.

code path

StreamableHTTPClientTransport.send() ×2  (streamableHttp.ts:442)
  └─ onUnauthorized() ×2                 (auth.ts:128 via adaptOAuthProvider)
       └─ handleOAuthUnauthorized() ×2   (auth.ts:103)
            └─ auth() ×2                 (auth.ts:540)  ← no coalescing here
                 └─ authInternal() ×2    (auth.ts:601)
                      └─ provider.tokens() ×2            both read same refresh_token
                      └─ refreshAuthorization() ×2       (auth.ts:768) both POST to /token

suggested fix

// packages/client/src/client/auth.ts
+// Coalesces concurrent auth() calls for the same provider so only one refresh
+// exchange runs at a time. Prevents rotating-refresh-token replay (RFC 6819 §5.2.2.3).
+const pendingAuth = new WeakMap<OAuthClientProvider, Promise<AuthResult>>();
+
 export async function auth(
     provider: OAuthClientProvider,
     options: { ... }
 ): Promise<AuthResult> {
-    try {
-        return await authInternal(provider, options);
-    } catch (error) {
-        if (error instanceof OAuthError) { ... }
-        throw error;
-    }
+    const inflight = pendingAuth.get(provider);
+    if (inflight) {
+        return inflight;
+    }
+
+    const promise = (async () => {
+        try {
+            return await authInternal(provider, options);
+        } catch (error) {
+            if (error instanceof OAuthError) { ... }
+            throw error;
+        }
+    })().finally(() => {
+        pendingAuth.delete(provider);
+    });
+
+    pendingAuth.set(provider, promise);
+    return promise;
 }

test to verify: two concurrent auth() calls with a valid refresh token must result in exactly one POST to the token endpoint (token endpoint hit count assertion in packages/client/test/client/auth.test.ts, "coalesces concurrent auth() calls so the token endpoint is only hit once per refresh").

bug is present on both main (53fb84b) and v1.x (9edbab7) — needs backport. PRs #1787 and #1803 addressed this but were closed without merging.