Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧱 fix: Close MCP OAuth Teardown Races (#15716)

Danny Avila8fa59637c895
diff --git a/api/server/controllers/UserController.js b/api/server/controllers/UserController.js
index 79defb5df4..6a5199f844 100644
--- a/api/server/controllers/UserController.js
+++ b/api/server/controllers/UserController.js
@@ -287,6 +287,23 @@ const updateUserPluginsController = async (req, res) => {
);
({ status, message } = normalizeHttpError(authService));
}
+ const serverName = pluginKey.replace(Constants.mcp_prefix, '');
+ try {
+ await invalidateCachedTools({ userId: user.id, serverName });
+ } catch (error) {
+ logger.error(
+ `[updateUserPluginsController] Error fencing MCP connection before OAuth teardown for user ${user.id}:`,
+ error,
+ );
+ }
+ try {
+ await getMCPManager()?.disconnectUserConnection(user.id, serverName);
+ } catch (error) {
+ logger.error(
+ `[updateUserPluginsController] Error disconnecting MCP connection before OAuth teardown for user ${user.id}:`,
+ error,
+ );
+ }
try {
// if the MCP server uses OAuth, perform a full cleanup and token revocation
await maybeUninstallOAuthMCP(user.id, pluginKey, appConfig);
@@ -295,6 +312,8 @@ const updateUserPluginsController = async (req, res) => {
`[updateUserPluginsController] Error uninstalling OAuth MCP for ${pluginKey}:`,
error,
);
+ status = 503;
+ message = 'OAuth credential cleanup is temporarily unavailable';
}
} else {
// This handles:
diff --git a/api/server/controllers/__tests__/UserController.mcpOAuth.spec.js b/api/server/controllers/__tests__/UserController.mcpOAuth.spec.js
index 1c16b7e0d1..a869113e22 100644
--- a/api/server/controllers/__tests__/UserController.mcpOAuth.spec.js
+++ b/api/server/controllers/__tests__/UserController.mcpOAuth.spec.js
@@ -141,6 +141,10 @@ function createRequest() {
function setupMCPMocks() {
const flowManager = {
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 1,
+ release: jest.fn().mockResolvedValue(undefined),
+ }),
deleteFlow: jest.fn().mockResolvedValue(true),
};
const mcpManager = {
@@ -236,6 +240,9 @@ describe('updateUserPluginsController MCP OAuth cleanup', () => {
serverName: 'test-server',
findToken: expect.any(Function),
});
+ expect(mcpManager.disconnectUserConnection.mock.invocationCallOrder[0]).toBeLessThan(
+ MCPTokenStorage.getClientInfoAndMetadata.mock.invocationCallOrder[0],
+ );
expect(MCPTokenStorage.deleteUserTokens).toHaveBeenCalledWith({
userId: 'user-1',
serverName: 'test-server',
diff --git a/api/server/controllers/__tests__/maybeUninstallOAuthMCP.spec.js b/api/server/controllers/__tests__/maybeUninstallOAuthMCP.spec.js
index 6c46ea509b..defbca7f9d 100644
--- a/api/server/controllers/__tests__/maybeUninstallOAuthMCP.spec.js
+++ b/api/server/controllers/__tests__/maybeUninstallOAuthMCP.spec.js
@@ -69,6 +69,10 @@ jest.mock('librechat-data-provider', () => ({
jest.mock('~/config', () => ({
getMCPManager: jest.fn(),
getFlowStateManager: jest.fn(() => ({
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 1,
+ release: jest.fn().mockResolvedValue(undefined),
+ }),
deleteFlow: (...args) => mockDeleteFlow(...args),
})),
getMCPServersRegistry: jest.fn(() => ({
diff --git a/packages/api/src/flow/manager.test.ts b/packages/api/src/flow/manager.test.ts
index 74248f428a..3b90f2b87a 100644
--- a/packages/api/src/flow/manager.test.ts
+++ b/packages/api/src/flow/manager.test.ts
@@ -75,6 +75,33 @@ describe('FlowStateManager', () => {
});
});
+ it('treats an expired in-memory envelope as missing during a guarded mutation', async () => {
+ const keyv = new Keyv({
+ namespace: 'flow-expiry-test',
+ serialize: JSON.stringify,
+ deserialize: JSON.parse,
+ });
+ const manager = new FlowStateManager<string>(keyv, { ttl: 30000, ci: true });
+ await manager.initFlow('oauth-flow', 'mcp_oauth', { state: 'expected-state' });
+ const flow = await manager.getFlowState('oauth-flow', 'mcp_oauth');
+ const memoryStore = keyv.store as Map<string, string>;
+ const [storedKey, raw] = [...memoryStore.entries()][0];
+ const envelope = JSON.parse(raw);
+ envelope.expires = Date.now() - 1;
+ memoryStore.set(storedKey, JSON.stringify(envelope));
+
+ await expect(
+ manager.completeFlowIfCurrent(
+ 'oauth-flow',
+ 'mcp_oauth',
+ flow!.createdAt,
+ 'expected-state',
+ 'late-result',
+ ),
+ ).resolves.toBe('missing');
+ expect(memoryStore.has(storedKey)).toBe(false);
+ });
+
it('does not delete a replacement OAuth attempt', async () => {
await flowManager.initFlow('oauth-flow', 'mcp_oauth', { state: 'new-state' });
@@ -398,6 +425,15 @@ describe('FlowStateManager', () => {
});
});
+ it('does not recreate a missing flow when monitoring a published attempt', async () => {
+ await expect(
+ flowManager.createFlow('deleted-oauth-flow', 'mcp_oauth', {}, undefined, false),
+ ).rejects.toThrow('mcp_oauth flow not found');
+ await expect(
+ flowManager.getFlowState('deleted-oauth-flow', 'mcp_oauth'),
+ ).resolves.toBeUndefined();
+ });
+
describe('deleteFlow', () => {
const flowId = 'test-flow-123';
const type = 'test-type';
@@ -1225,4 +1261,68 @@ describe('FlowStateManager', () => {
expect(result.age).toBeLessThan(60 * 1000);
});
});
+
+ describe('cross-replica leases', () => {
+ it('rejects stale work after teardown advances the generation', async () => {
+ const generation = await flowManager.getLeaseGeneration('user:server');
+ if (generation === null) {
+ throw new Error('lease unexpectedly active');
+ }
+ const teardown = await flowManager.acquireLease('user:server', {
+ advanceGeneration: true,
+ });
+
+ expect(teardown?.generation).toBe(generation + 1);
+ await expect(flowManager.getLeaseGeneration('user:server')).resolves.toBeNull();
+ await teardown?.release();
+ await expect(
+ flowManager.acquireLease('user:server', { expectedGeneration: generation }),
+ ).resolves.toBeNull();
+ });
+
+ it('serializes holders and preserves the generation after release', async () => {
+ const first = await flowManager.acquireLease('shared-owner');
+ expect(first).not.toBeNull();
+ await expect(flowManager.getLeaseGeneration('shared-owner')).resolves.toBe(first?.generation);
+ await expect(flowManager.acquireLease('shared-owner', { waitMs: 0 })).resolves.toBeNull();
+
+ await first?.release();
+ const second = await flowManager.acquireLease('shared-owner', {
+ expectedGeneration: first?.generation,
+ });
+ expect(second?.generation).toBe(first?.generation);
+ await second?.release();
+ });
+
+ it('expires released in-memory generations after the stale-work horizon', async () => {
+ const now = Date.now();
+ const clock = jest.spyOn(Date, 'now').mockReturnValue(now);
+ const teardown = await flowManager.acquireLease('expiring-owner', {
+ advanceGeneration: true,
+ });
+ await teardown?.release();
+ expect(await flowManager.getLeaseGeneration('expiring-owner')).toBe(1);
+
+ clock.mockReturnValue(now + 24 * 60 * 60_000 + 1);
+ expect(await flowManager.getLeaseGeneration('expiring-owner')).toBe(0);
+ clock.mockRestore();
+ });
+
+ it('treats an active pre-purpose lease as teardown during rolling upgrades', async () => {
+ const leases = (
+ FlowStateManager as unknown as {
+ inMemoryLeases: Map<string, Record<string, unknown>>;
+ }
+ ).inMemoryLeases;
+ leases.set('lease:legacy-owner', {
+ generation: 4,
+ owner: 'old-replica',
+ leaseUntil: Date.now() + 60_000,
+ expiresAt: Date.now() + 60_000,
+ });
+
+ await expect(flowManager.getLeaseGeneration('legacy-owner')).resolves.toBeNull();
+ leases.delete('lease:legacy-owner');
+ });
+ });
});
diff --git a/packages/api/src/flow/manager.ts b/packages/api/src/flow/manager.ts
index 7b0a26187c..cffc521c9b 100644
--- a/packages/api/src/flow/manager.ts
+++ b/packages/api/src/flow/manager.ts
@@ -1,4 +1,5 @@
import { Keyv } from 'keyv';
+import { randomUUID } from 'crypto';
import { logger } from '@librechat/data-schemas';
import type { StoredDataNoRaw } from 'keyv';
import type { FlowState, FlowMetadata, FlowManagerOptions } from './types';
@@ -7,6 +8,19 @@ import { math } from '~/utils/math';
type GuardedMutationResult = 'updated' | 'stale' | 'missing';
+export interface FlowLease {
+ generation: number;
+ release: () => Promise<void>;
+}
+
+interface InMemoryLeaseState {
+ generation: number;
+ owner?: string;
+ purpose?: 'operation' | 'teardown';
+ leaseUntil?: number;
+ expiresAt?: number;
+}
+
interface KeyvRedisStore {
constructor: { name: string };
namespace?: string;
@@ -62,6 +76,41 @@ redis.call('SET', KEYS[1], cjson.encode(data), 'PX', ARGV[5])
return 1
`;
+const READ_LEASE_GENERATION = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local data = cjson.decode(raw)
+if data.owner and data.purpose ~= 'operation' and data.leaseUntil and data.leaseUntil > tonumber(ARGV[1]) then return -1 end
+return data.generation or 0
+`;
+
+const ACQUIRE_LEASE = `
+local raw = redis.call('GET', KEYS[1])
+local data = raw and cjson.decode(raw) or { generation = 0 }
+local now = tonumber(ARGV[2])
+if data.owner and data.leaseUntil and data.leaseUntil > now then return -2 end
+local expected = tonumber(ARGV[3])
+if expected >= 0 and data.generation ~= expected then return -1 end
+if ARGV[4] == '1' then data.generation = data.generation + 1 end
+data.owner = ARGV[1]
+data.purpose = ARGV[7]
+data.leaseUntil = now + tonumber(ARGV[5])
+redis.call('SET', KEYS[1], cjson.encode(data), 'PX', ARGV[6])
+return data.generation
+`;
+
+const RELEASE_LEASE = `
+local raw = redis.call('GET', KEYS[1])
+if not raw then return 0 end
+local data = cjson.decode(raw)
+if data.owner ~= ARGV[1] then return -1 end
+data.owner = nil
+data.purpose = nil
+data.leaseUntil = nil
+redis.call('SET', KEYS[1], cjson.encode(data), 'PX', ARGV[2])
+return 1
+`;
+
/**
* Lifetime of a PENDING OAuth flow: how long the auth button stays valid and an
* in-flight flow can be reused before it is replaced. Mirrors
@@ -83,6 +132,16 @@ export function normalizeExpiresAt(timestamp: number): number {
}
export class FlowStateManager<T = unknown> {
+ private static readonly inMemoryLeases = new Map<string, InMemoryLeaseState>();
+
+ private static evictExpiredInMemoryLeases(now: number): void {
+ for (const [key, lease] of this.inMemoryLeases) {
+ if (lease.expiresAt != null && lease.expiresAt <= now) {
+ this.inMemoryLeases.delete(key);
+ }
+ }
+ }
+
private keyv: Keyv;
private ttl: number;
private monitorTimeout: number;
@@ -139,6 +198,106 @@ export class FlowStateManager<T = unknown> {
return `${type}:${flowId}`;
}
+ /** Reads the generation used to reject work that crossed a teardown boundary. */
+ async getLeaseGeneration(leaseId: string): Promise<number | null> {
+ const flowKey = this.getFlowKey(leaseId, 'lease');
+ const inMemoryKey = this.keyv.namespace ? `${this.keyv.namespace}:${flowKey}` : flowKey;
+ const redisKey = this.getRedisKey(flowKey);
+ if (redisKey) {
+ const result = Number(
+ await this.evalRedisScript(READ_LEASE_GENERATION, redisKey, [String(Date.now())]),
+ );
+ return result < 0 ? null : result;
+ }
+ const now = Date.now();
+ FlowStateManager.evictExpiredInMemoryLeases(now);
+ const current = FlowStateManager.inMemoryLeases.get(inMemoryKey);
+ if (current?.owner && current.purpose !== 'operation' && (current.leaseUntil ?? 0) > now) {
+ return null;
+ }
+ return current?.generation ?? 0;
+ }
+
+ /**
+ * Acquires a cross-replica lease. `expectedGeneration` rejects an operation that started
+ * before teardown; `advanceGeneration` is the teardown linearization point.
+ */
+ async acquireLease(
+ leaseId: string,
+ options: {
+ expectedGeneration?: number;
+ advanceGeneration?: boolean;
+ leaseMs?: number;
+ waitMs?: number;
+ } = {},
+ ): Promise<FlowLease | null> {
+ const flowKey = this.getFlowKey(leaseId, 'lease');
+ const inMemoryKey = this.keyv.namespace ? `${this.keyv.namespace}:${flowKey}` : flowKey;
+ const redisKey = this.getRedisKey(flowKey);
+ const owner = randomUUID();
+ const leaseMs = options.leaseMs ?? 15 * 60_000;
+ const waitUntil = Date.now() + (options.waitMs ?? 15_000);
+ const retentionMs = 24 * 60 * 60_000;
+ while (true) {
+ const now = Date.now();
+ FlowStateManager.evictExpiredInMemoryLeases(now);
+ let result: number;
+ if (redisKey) {
+ result = Number(
+ await this.evalRedisScript(ACQUIRE_LEASE, redisKey, [
+ owner,
+ String(now),
+ String(options.expectedGeneration ?? -1),
+ options.advanceGeneration ? '1' : '0',
+ String(leaseMs),
+ String(retentionMs),
+ options.advanceGeneration ? 'teardown' : 'operation',
+ ]),
+ );
+ } else {
+ const current = FlowStateManager.inMemoryLeases.get(inMemoryKey) ?? { generation: 0 };
+ if (current.owner && (current.leaseUntil ?? 0) > now) {
+ result = -2;
+ } else if (
+ options.expectedGeneration !== undefined &&
+ current.generation !== options.expectedGeneration
+ ) {
+ result = -1;
+ } else {
+ result = current.generation + (options.advanceGeneration ? 1 : 0);
+ FlowStateManager.inMemoryLeases.set(inMemoryKey, {
+ generation: result,
+ owner,
+ purpose: options.advanceGeneration ? 'teardown' : 'operation',
+ leaseUntil: now + leaseMs,
+ expiresAt: now + retentionMs,
+ });
+ }
+ }
+ if (result === -1) return null;
+ if (result >= 0) {
+ return {
+ generation: result,
+ release: async () => {
+ if (redisKey) {
+ await this.evalRedisScript(RELEASE_LEASE, redisKey, [owner, String(retentionMs)]);
+ return;
+ }
+ const current = FlowStateManager.inMemoryLeases.get(inMemoryKey);
+ if (current?.owner === owner) {
+ FlowStateManager.inMemoryLeases.set(inMemoryKey, {
+ generation: current.generation,
+ expiresAt: Date.now() + retentionMs,
+ });
+ }
+ },
+ };
+ }
+ if (Date.now() >= waitUntil) return null;
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ }
+ }
+
private getRedisKey(flowKey: string): string | null {
const store = this.keyv.store as KeyvRedisStore;
if (store?.constructor?.name !== 'KeyvRedis' || typeof store.createKeyPrefix !== 'function') {
@@ -191,10 +350,15 @@ export class FlowStateManager<T = unknown> {
if (typeof raw !== 'string') {
return null;
}
+ const envelope = JSON.parse(raw) as { value: FlowState<T>; expires?: number };
+ if (envelope.expires != null && envelope.expires <= Date.now()) {
+ this.keyv.store.delete(key);
+ return null;
+ }
return {
store: this.keyv.store as Map<string, string>,
key,
- envelope: JSON.parse(raw) as { value: FlowState<T>; expires?: number },
+ envelope,
};
}
@@ -400,6 +564,7 @@ export class FlowStateManager<T = unknown> {
type: string,
metadata: FlowMetadata = {},
signal?: AbortSignal,
+ createIfMissing = true,
): Promise<T> {
const flowKey = this.getFlowKey(flowId, type);
@@ -417,6 +582,10 @@ export class FlowStateManager<T = unknown> {
return this.monitorFlow(flowKey, type, signal);
}
+ if (!createIfMissing) {
+ throw new Error(`${type} flow not found`);
+ }
+
const initialState: FlowState = {
type,
status: 'PENDING',
diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.ts
index 6e764f77a2..00ed13e81e 100644
--- a/packages/api/src/mcp/MCPConnectionFactory.ts
+++ b/packages/api/src/mcp/MCPConnectionFactory.ts
@@ -19,6 +19,7 @@ import {
MCPTokenStorage,
MCPOAuthHandler,
getMCPServerGeneration,
+ getMCPOAuthLeaseId,
OboTokenResolutionError,
ReauthenticationRequiredError,
resolveOboToken,
@@ -746,6 +747,7 @@ export class MCPConnectionFactory {
deleteTokens: this.tokenMethods!.deleteTokens,
refreshTokens: this.createRefreshTokensFunction(),
singleFlightScope: this.getOAuthBindingDigest(),
+ flowManager: this.flowManager,
}),
);
},
@@ -938,6 +940,7 @@ export class MCPConnectionFactory {
onRefreshSuccess: async (refreshed) => {
await this.invalidateGetTokensFlow(refreshed);
},
+ flowManager: this.flowManager,
}),
);
@@ -1236,6 +1239,19 @@ export class MCPConnectionFactory {
return;
}
+ const oauthLeaseId = getMCPOAuthLeaseId(this.userId!, this.serverName, this.tenantId);
+ let oauthLeaseGeneration: number | null;
+ try {
+ oauthLeaseGeneration = await this.flowManager!.getLeaseGeneration(oauthLeaseId);
+ } catch {
+ connection.emit('oauthFailed', new Error('OAuth teardown fence unavailable'));
+ return;
+ }
+ if (oauthLeaseGeneration === null) {
+ connection.emit('oauthFailed', new Error('OAuth teardown in progress'));
+ return;
+ }
+
if (isRequestRecovery && recoveryPhase === 'terminal') {
logger.warn(`${this.logPrefix} OAuth recovery phase budget exhausted`);
connection.emit('oauthFailed', new Error('OAuth recovery phase budget exhausted'));
@@ -1258,6 +1274,16 @@ export class MCPConnectionFactory {
recoveryPhase = 'terminal';
}
+ /** Teardown holds this gate until its credential and flow cleanup finishes. A refresh
+ * suppressed by that gate must not fall through and create a replacement OAuth flow. */
+ if (
+ this.userId &&
+ MCPTokenStorage.isRefreshTeardownActive(this.userId, this.serverName, this.tenantId)
+ ) {
+ connection.emit('oauthFailed', new Error('OAuth teardown in progress'));
+ return;
+ }
+
// Silent refresh failed and we're about to fall through to interactive
// OAuth. Invalidate any COMPLETED `mcp_oauth` flow first so
// `handleOAuthRequired`'s recent-completion fast path can't re-serve the
@@ -1295,7 +1321,18 @@ export class MCPConnectionFactory {
logger.info(
`${this.logPrefix} Re-issuing stored authorization URL while reusing PENDING flow`,
);
- await this.oauthStart(storedAuthUrl, { expiresAt });
+ const replayLease = await this.flowManager!.acquireLease(oauthLeaseId, {
+ expectedGeneration: oauthLeaseGeneration,
+ });
+ if (!replayLease) {
+ connection.emit('oauthFailed', new Error('OAuth replay superseded by teardown'));
+ return;
+ }
+ try {
+ await this.oauthStart(storedAuthUrl, { expiresAt });
+ } finally {
+ await replayLease.release();
+ }
}
connection.emit('oauthFailed', new Error('Pending OAuth flow reused - return early'));
return;
@@ -1341,12 +1378,27 @@ export class MCPConnectionFactory {
tenantId: this.tenantId,
serverGeneration: getMCPServerGeneration(this.serverDefinition as t.ParsedServerConfig),
};
- await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
- await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager!);
+ const publicationLease = await this.flowManager!.acquireLease(oauthLeaseId, {
+ expectedGeneration: oauthLeaseGeneration,
+ });
+ if (!publicationLease) {
+ connection.emit('oauthFailed', new Error('OAuth initiation superseded by teardown'));
+ return;
+ }
+ try {
+ await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
+ await MCPOAuthHandler.storeStateMapping(
+ flowMetadata.state,
+ newFlowId,
+ this.flowManager!,
+ );
+ } finally {
+ await publicationLease.release();
+ }
// Start monitoring in background — createFlow will find the existing PENDING state
// written by initFlow above, so metadata arg is unused (pass {} to make that explicit)
- this.flowManager!.createFlow(newFlowId, 'mcp_oauth', {}).catch(async (error) => {
+ this.waitForSharedOAuthFlow(newFlowId).catch(async (error) => {
logger.debug(`${this.logPrefix} OAuth flow monitor ended`);
await this.clearStaleClientIfRejected(flowMetadata.reusedClientCredentialSetId, error);
});
@@ -1366,7 +1418,7 @@ export class MCPConnectionFactory {
}
// Normal OAuth handling - wait for completion
- const result = await this.handleOAuthRequired();
+ const result = await this.handleOAuthRequired(oauthLeaseGeneration);
if (result?.tokens) {
const { tokens } = result;
@@ -1593,7 +1645,7 @@ export class MCPConnectionFactory {
}
/** Manages OAuth flow initiation and completion */
- protected async handleOAuthRequired(): Promise<{
+ protected async handleOAuthRequired(expectedLeaseGeneration?: number): Promise<{
tokens: MCPOAuthTokens | null;
clientInfo?: OAuthClientInformation;
metadata?: OAuthMetadata;
@@ -1616,6 +1668,13 @@ export class MCPConnectionFactory {
return null;
}
+ const oauthLeaseId = getMCPOAuthLeaseId(this.userId!, this.serverName, this.tenantId);
+ const oauthLeaseGeneration =
+ expectedLeaseGeneration ?? (await this.flowManager.getLeaseGeneration(oauthLeaseId));
+ if (oauthLeaseGeneration === null) {
+ throw new Error('OAuth teardown in progress');
+ }
+
let reusedStoredClient = false;
let reusedClientCredentialSetId: string | undefined;
@@ -1650,7 +1709,17 @@ export class MCPConnectionFactory {
logger.info(
`${this.logPrefix} Re-issuing stored authorization URL to caller while joining PENDING flow`,
);
- await this.oauthStart(storedAuthUrl, { expiresAt });
+ const replayLease = await this.flowManager.acquireLease(oauthLeaseId, {
+ expectedGeneration: oauthLeaseGeneration,
+ });
+ if (!replayLease) {
+ throw new Error('OAuth replay superseded by teardown');
+ }
+ try {
+ await this.oauthStart(storedAuthUrl, { expiresAt });
+ } finally {
+ await replayLease.release();
+ }
}
reusedStoredClient = flowMeta?.reusedStoredClient === true;
@@ -1691,18 +1760,28 @@ export class MCPConnectionFactory {
!isTokenExpired &&
this.isCurrentServerOAuthFlow(flowMeta)
) {
+ const reuseLease = await this.flowManager.acquireLease(oauthLeaseId, {
+ expectedGeneration: oauthLeaseGeneration,
+ });
+ if (!reuseLease) {
+ throw new Error('Cached OAuth result superseded by teardown');
+ }
logger.debug(
`${this.logPrefix} Found non-stale COMPLETED OAuth flow, reusing cached tokens`,
);
- return {
- tokens: cachedTokens,
- clientInfo: flowMeta?.clientInfo,
- metadata: flowMeta?.metadata,
- resourceMetadata: flowMeta?.resourceMetadata,
- clientSource: flowMeta?.clientSource,
- reusedStoredClient: flowMeta?.reusedStoredClient,
- reusedClientCredentialSetId: flowMeta?.reusedClientCredentialSetId,
- };
+ try {
+ return {
+ tokens: cachedTokens,
+ clientInfo: flowMeta?.clientInfo,
+ metadata: flowMeta?.metadata,
+ resourceMetadata: flowMeta?.resourceMetadata,
+ clientSource: flowMeta?.clientSource,
+ reusedStoredClient: flowMeta?.reusedStoredClient,
+ reusedClientCredentialSetId: flowMeta?.reusedClientCredentialSetId,
+ };
+ } finally {
+ await reuseLease.release();
+ }
}
}
@@ -1749,8 +1828,18 @@ export class MCPConnectionFactory {
tenantId: this.tenantId,
serverGeneration: getMCPServerGeneration(this.serverDefinition as t.ParsedServerConfig),
};
- await this.flowManager.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
- await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager);
+ const publicationLease = await this.flowManager.acquireLease(oauthLeaseId, {
+ expectedGeneration: oauthLeaseGeneration,
+ });
+ if (!publicationLease) {
+ throw new Error('OAuth initiation superseded by teardown');
+ }
+ try {
+ await this.flowManager.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
+ await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager);
+ } finally {
+ await publicationLease.release();
+ }
if (typeof this.oauthStart === 'function') {
logger.info(`${this.logPrefix} OAuth flow started, issued authorization URL to user`);
@@ -1785,7 +1874,7 @@ export class MCPConnectionFactory {
}
private waitForSharedOAuthFlow(flowId: string): Promise<MCPOAuthTokens | null> {
- const flow = this.flowManager!.createFlow(flowId, 'mcp_oauth', {});
+ const flow = this.flowManager!.createFlow(flowId, 'mcp_oauth', {}, undefined, false);
const signal = this.signal;
if (!signal) {
return flow;
diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
index d08e179de3..d8c9f9ad76 100644
--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts
@@ -106,6 +106,7 @@ describe('MCPConnectionFactory', () => {
// Cached runtime handlers now delegate before attempting their own refresh,
// so queued one-shot refresh results must not leak into the next test.
mockMCPTokenStorage.forceRefreshTokens.mockReset();
+ mockMCPTokenStorage.isRefreshTeardownActive.mockReset().mockReturnValue(false);
// Clear process-local silent-refresh in-flight map so a leftover entry
// from a prior test (e.g. one that errored before its `finally` ran)
// cannot cause a later test to join a stale promise.
@@ -124,6 +125,11 @@ describe('MCPConnectionFactory', () => {
} as t.MCPOptions;
mockFlowManager = {
+ getLeaseGeneration: jest.fn().mockResolvedValue(0),
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 0,
+ release: jest.fn().mockResolvedValue(undefined),
+ }),
initFlow: jest.fn().mockResolvedValue(undefined),
createFlow: jest.fn(),
createFlowWithHandler: jest.fn(),
@@ -257,7 +263,13 @@ describe('MCPConnectionFactory', () => {
const resultPromise = factory.handleOAuthRequiredForTest();
await new Promise((resolve) => setImmediate(resolve));
- expect(mockFlowManager.createFlow).toHaveBeenCalledWith('user123:test-server', 'mcp_oauth', {});
+ expect(mockFlowManager.createFlow).toHaveBeenCalledWith(
+ 'user123:test-server',
+ 'mcp_oauth',
+ {},
+ undefined,
+ false,
+ );
abortController.abort(abortReason);
@@ -1356,7 +1368,13 @@ describe('MCPConnectionFactory', () => {
expect(initCallOrder).toBeLessThan(createCallOrder);
// createFlow should receive {} since initFlow already persisted metadata
- expect(mockFlowManager.createFlow).toHaveBeenCalledWith('flow123', 'mcp_oauth', {});
+ expect(mockFlowManager.createFlow).toHaveBeenCalledWith(
+ 'flow123',
+ 'mcp_oauth',
+ {},
+ undefined,
+ false,
+ );
});
it('should delete stale flow and create new OAuth flow when existing flow is COMPLETED', async () => {
@@ -1443,6 +1461,8 @@ describe('MCPConnectionFactory', () => {
'user123:test-server',
'mcp_oauth',
{},
+ undefined,
+ false,
);
});
@@ -1521,7 +1541,7 @@ describe('MCPConnectionFactory', () => {
expect(mockMCPOAuthHandler.initiateOAuthFlow).not.toHaveBeenCalled();
});
- it('should fall back to interactive OAuth when silent refresh returns null', async () => {
+ it('suppresses interactive OAuth during teardown, then falls back after release', async () => {
const sseConfig = {
...mockServerConfig,
url: 'https://api.example.com',
@@ -1594,6 +1614,12 @@ describe('MCPConnectionFactory', () => {
// Expected to fail
}
+ mockMCPTokenStorage.isRefreshTeardownActive.mockReturnValue(true);
+ await oauthRequiredHandler!({ serverUrl: 'https://api.example.com' });
+
+ expect(mockMCPOAuthHandler.initiateOAuthFlow).not.toHaveBeenCalled();
+
+ mockMCPTokenStorage.isRefreshTeardownActive.mockReturnValue(false);
await oauthRequiredHandler!({ serverUrl: 'https://api.example.com' });
// Silent refresh was attempted, but yielded no tokens.
diff --git a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts
index 451d782de7..d5a89d4190 100644
--- a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts
+++ b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts
@@ -2050,6 +2050,144 @@ describe('MCPTokenStorage', () => {
expect(storedRefresh!.token).toBe('enc:rt-2');
});
+ it('rechecks single-flight ownership after the asynchronous generation read', async () => {
+ await seedRefreshableTokens('generation-yield-srv');
+ const refreshTokens = jest.fn().mockResolvedValue(rotatedTokens(2));
+ const flowManager = {
+ getLeaseGeneration: jest.fn(async () => {
+ await new Promise((resolve) => setImmediate(resolve));
+ return 0;
+ }),
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 0,
+ release: jest.fn().mockResolvedValue(undefined),
+ }),
+ };
+ const params = {
+ ...refreshParams(refreshTokens, 'generation-yield-srv'),
+ flowManager: flowManager as never,
+ };
+
+ const [first, second] = await Promise.all([
+ MCPTokenStorage.forceRefreshTokens(params),
+ MCPTokenStorage.forceRefreshTokens(params),
+ ]);
+
+ expect(refreshTokens).toHaveBeenCalledTimes(1);
+ expect(first).toMatchObject({ access_token: 'at-2' });
+ expect(second).toMatchObject({ access_token: 'at-2' });
+ });
+
+ it('aborts and joins an in-flight refresh before teardown continues', async () => {
+ await seedRefreshableTokens('teardown-srv');
+ const refreshTokens = jest.fn(
+ (_token, _metadata, signal) =>
+ new Promise<MCPOAuthTokens>((_resolve, reject) => {
+ signal?.addEventListener('abort', () => reject(new Error('teardown fence')), {
+ once: true,
+ });
+ }),
+ );
+
+ const refresh = MCPTokenStorage.forceRefreshTokens(
+ refreshParams(refreshTokens, 'teardown-srv'),
+ );
+ await waitFor(() => refreshTokens.mock.calls.length > 0);
+ const release = await MCPTokenStorage.beginRefreshTeardown('u1', 'teardown-srv');
+
+ await expect(refresh).resolves.toBeNull();
+ await expect(
+ MCPTokenStorage.forceRefreshTokens(refreshParams(refreshTokens, 'teardown-srv')),
+ ).resolves.toBeNull();
+ release();
+ expect(
+ await store.findToken({
+ userId: 'u1',
+ type: 'mcp_oauth_refresh',
+ identifier: 'mcp:teardown-srv:refresh',
+ }),
+ ).toMatchObject({ token: 'enc:rt-1' });
+ });
+
+ it('discards a remote refresh response after teardown advances the durable generation', async () => {
+ await seedRefreshableTokens('remote-teardown-srv');
+ const refreshTokens = jest.fn().mockResolvedValue(rotatedTokens(2));
+ const flowManager = {
+ getLeaseGeneration: jest.fn().mockResolvedValue(7),
+ acquireLease: jest.fn().mockResolvedValue(null),
+ };
+
+ await expect(
+ MCPTokenStorage.forceRefreshTokens({
+ ...refreshParams(refreshTokens, 'remote-teardown-srv'),
+ flowManager: flowManager as never,
+ }),
+ ).resolves.toBeNull();
+
+ expect(flowManager.acquireLease).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({ expectedGeneration: 7 }),
+ );
+ expect(
+ await store.findToken({
+ userId: 'u1',
+ type: 'mcp_oauth_refresh',
+ identifier: 'mcp:remote-teardown-srv:refresh',
+ }),
+ ).toMatchObject({ token: 'enc:rt-1' });
+ });
+
+ it('returns committed refresh tokens when distributed lease release fails', async () => {
+ await seedRefreshableTokens('release-failure-srv');
+ const refreshTokens = jest.fn().mockResolvedValue(rotatedTokens(2));
+ const flowManager = {
+ getLeaseGeneration: jest.fn().mockResolvedValue(3),
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 3,
+ release: jest.fn().mockRejectedValue(new Error('redis unavailable')),
+ }),
+ };
+
+ await expect(
+ MCPTokenStorage.forceRefreshTokens({
+ ...refreshParams(refreshTokens, 'release-failure-srv'),
+ flowManager: flowManager as never,
+ }),
+ ).resolves.toMatchObject({ access_token: 'at-2' });
+
+ expect(
+ await store.findToken({
+ userId: 'u1',
+ type: 'mcp_oauth_refresh',
+ identifier: 'mcp:release-failure-srv:refresh',
+ }),
+ ).toMatchObject({ token: 'enc:rt-2' });
+ });
+
+ it('does not fence a colon-prefixed sibling server', async () => {
+ await seedRefreshableTokens('foo:bar');
+ let resolveRefresh!: (tokens: MCPOAuthTokens) => void;
+ let refreshSignal: AbortSignal | undefined;
+ const refreshTokens = jest.fn(
+ (_token, _metadata, signal) =>
+ new Promise<MCPOAuthTokens>((resolve) => {
+ refreshSignal = signal;
+ resolveRefresh = resolve;
+ }),
+ );
+
+ const siblingRefresh = MCPTokenStorage.forceRefreshTokens(
+ refreshParams(refreshTokens, 'foo:bar'),
+ );
+ await waitFor(() => refreshTokens.mock.calls.length > 0);
+ const release = await MCPTokenStorage.beginRefreshTeardown('u1', 'foo');
+
+ expect(refreshSignal?.aborted).toBe(false);
+ resolveRefresh(rotatedTokens(2));
+ await expect(siblingRefresh).resolves.toMatchObject({ access_token: 'at-2' });
+ release();
+ });
+
it('getTokens joins an in-flight refresh instead of replaying the consumed refresh token', async () => {
// Mirrors issue #14583: a silent refresh (401-triggered) is mid-redemption
// when an expired-token read fires its own refresh. Without single-flight,
diff --git a/packages/api/src/mcp/oauth/cleanup.test.ts b/packages/api/src/mcp/oauth/cleanup.test.ts
index 53c8b08f2a..218aa7a71e 100644
--- a/packages/api/src/mcp/oauth/cleanup.test.ts
+++ b/packages/api/src/mcp/oauth/cleanup.test.ts
@@ -1,6 +1,14 @@
import type { ParsedServerConfig } from '~/mcp/types';
import { cleanupMCPServerOAuth, getMCPServerGeneration } from './cleanup';
+const createFlowManager = () => ({
+ acquireLease: jest.fn().mockResolvedValue({
+ generation: 1,
+ release: jest.fn().mockResolvedValue(undefined),
+ }),
+ deleteFlow: jest.fn(),
+});
+
describe('getMCPServerGeneration', () => {
it('includes the durable database identity for user servers', () => {
const config = { type: 'streamable-http', url: 'https://example.com', dbId: 'server-1' };
@@ -55,7 +63,7 @@ describe('cleanupMCPServerOAuth', () => {
userId: 'user-1',
pluginKey: 'mcp_test-server',
dependencies: {
- flowManager: { deleteFlow: jest.fn() } as never,
+ flowManager: createFlowManager() as never,
oauthHandler: {
generateFlowId: jest.fn(),
generateTokenFlowId: jest.fn(),
@@ -122,7 +130,7 @@ describe('cleanupMCPServerOAuth', () => {
pluginKey: 'mcp_test-server',
serverConfigOverride: { type: 'streamable-http', url: 'https://example.com/mcp' },
dependencies: {
- flowManager: { deleteFlow: jest.fn() } as never,
+ flowManager: createFlowManager() as never,
oauthHandler: {
generateFlowId: jest.fn(() => 'user-1:test-server'),
generateTokenFlowId: jest.fn(() => 'user-1:test-server'),
@@ -151,9 +159,15 @@ describe('cleanupMCPServerOAuth', () => {
it('deletes only token records snapshotted before flow cancellation', async () => {
const deleteTokens = jest.fn();
- const findToken = jest.fn(async ({ type }: { type?: string }) =>
- type === 'mcp_oauth' ? ({ token: 'encrypted-old-access' } as never) : null,
- );
+ const findToken = jest.fn(async ({ type }: { type?: string }) => {
+ if (type === 'mcp_oauth') {
+ return {
+ token: 'encrypted-old-access',
+ metadata: { credential_set_id: 'partially-versioned' },
+ } as never;
+ }
+ return type === 'mcp_oauth_refresh' ? ({ token: 'encrypted-legacy-refresh' } as never) : null;
+ });
const deleteUserTokens = jest.fn(
async ({
userId,
@@ -192,7 +206,7 @@ describe('cleanupMCPServerOAuth', () => {
oauth: {},
},
dependencies: {
- flowManager: { deleteFlow: jest.fn() } as never,
+ flowManager: createFlowManager() as never,
oauthHandler: {
generateFlowId: jest.fn(() => 'user-1:test-server'),
generateTokenFlowId: jest.fn(() => 'user-1:test-server'),
@@ -212,7 +226,7 @@ describe('cleanupMCPServerOAuth', () => {
},
});
- expect(deleteTokens).toHaveBeenCalledTimes(1);
+ expect(deleteTokens).toHaveBeenCalledTimes(2);
expect(deleteTokens).toHaveBeenCalledWith({
userId: 'user-1',
type: 'mcp_oauth',
@@ -239,7 +253,7 @@ describe('cleanupMCPServerOAuth', () => {
oauth: {},
},
dependencies: {
- flowManager: { deleteFlow: jest.fn() } as never,
+ flowManager: createFlowManager() as never,
oauthHandler: {
generateFlowId: jest.fn(() => 'user-1:test-server'),
generateTokenFlowId: jest.fn(() => 'user-1:test-server'),
diff --git a/packages/api/src/mcp/oauth/cleanup.ts b/packages/api/src/mcp/oauth/cleanup.ts
index 0bfec66f23..7a89e9687b 100644
--- a/packages/api/src/mcp/oauth/cleanup.ts
+++ b/packages/api/src/mcp/oauth/cleanup.ts
@@ -5,9 +5,9 @@ import type { FlowStateManager } from '~/flow/manager';
import type { ParsedServerConfig } from '~/mcp/types';
import type { MCPOAuthTokens } from './types';
import { getMCPAppToolsPublicationGeneration } from '~/mcp/toolsChanged';
+import { getMCPOAuthLeaseId, MCPTokenStorage } from './tokens';
import { MCPOAuthHandler } from './handler';
import { isOAuthServer } from '~/mcp/utils';
-import { MCPTokenStorage } from './tokens';
export function getMCPServerGeneration(config: ParsedServerConfig): string {
const definitionGeneration = getMCPAppToolsPublicationGeneration(config);
@@ -119,14 +119,26 @@ export async function cleanupDeletedMCPServerOAuthUsers({
const batch = affectedUserIds.slice(offset, offset + OAUTH_CLEANUP_CONCURRENCY);
const results = await Promise.allSettled(
batch.map(async (userId) => {
- await fenceAndDisconnectUser?.(userId);
- const { allowedDomains, allowedAddresses } = await resolveAllowlists(userId);
- await uninstallOAuthMCP?.(
- userId,
- `${Constants.mcp_prefix}${serverName}`,
- { mcpSettings: { allowedDomains, allowedAddresses } },
- serverConfig,
- );
+ const userFailures: unknown[] = [];
+ try {
+ await fenceAndDisconnectUser?.(userId);
+ } catch (error) {
+ userFailures.push(error);
+ }
+ try {
+ const { allowedDomains, allowedAddresses } = await resolveAllowlists(userId);
+ await uninstallOAuthMCP?.(
+ userId,
+ `${Constants.mcp_prefix}${serverName}`,
+ { mcpSettings: { allowedDomains, allowedAddresses } },
+ serverConfig,
+ );
+ } catch (error) {
+ userFailures.push(error);
+ }
+ if (userFailures.length > 0) {
+ throw new Error(`OAuth cleanup failed for user ${userId}`);
+ }
}),
);
for (const result of results) {
@@ -153,7 +165,8 @@ export interface MCPOAuthCleanupDependencies {
tokenStorage: Pick<
typeof MCPTokenStorage,
'deleteUserTokens' | 'getClientInfoAndMetadata' | 'getTokens' | 'assertCredentialSetBinding'
- >;
+ > &
+ Partial<Pick<typeof MCPTokenStorage, 'beginRefreshTeardown'>>;
findToken: TokenMethods['findToken'];
deleteTokens: TokenMethods['deleteTokens'];
getServerConfig: (serverName: string, userId: string) => Promise<MCPOptions | undefined>;
@@ -256,17 +269,48 @@ interface UninstallParams {
dependencies: MCPOAuthCleanupDependencies;
}
-export async function cleanupMCPServerOAuth({
+export async function cleanupMCPServerOAuth(params: UninstallParams): Promise<void> {
+ const { userId, pluginKey, dependencies } = params;
+ if (!pluginKey.startsWith(Constants.mcp_prefix)) {
+ return;
+ }
+ const serverName = pluginKey.replace(Constants.mcp_prefix, '');
+ const releaseRefreshTeardown =
+ (await dependencies.tokenStorage.beginRefreshTeardown?.(userId, serverName)) ?? (() => {});
+ let teardownLease: Awaited<ReturnType<typeof dependencies.flowManager.acquireLease>> = null;
+ let leaseError: unknown;
+ try {
+ try {
+ teardownLease = await dependencies.flowManager.acquireLease(
+ getMCPOAuthLeaseId(userId, serverName),
+ { advanceGeneration: true, waitMs: 60_000 },
+ );
+ if (!teardownLease) {
+ leaseError = new Error(`Unable to acquire OAuth teardown lease for ${serverName}`);
+ }
+ } catch (error) {
+ leaseError = error;
+ }
+ await cleanupMCPServerOAuthWithFenceHeld(params);
+ if (leaseError) {
+ throw leaseError;
+ }
+ } finally {
+ try {
+ await teardownLease?.release();
+ } finally {
+ releaseRefreshTeardown();
+ }
+ }
+}
+
+async function cleanupMCPServerOAuthWithFenceHeld({
userId,
pluginKey,
appConfig,
serverConfigOverride,
dependencies,
}: UninstallParams): Promise<void> {
- if (!pluginKey.startsWith(Constants.mcp_prefix)) {
- return;
- }
-
const serverName = pluginKey.replace(Constants.mcp_prefix, '');
/** Snapshot exact encrypted values before cancelling the flow. Later cleanup can then remove
* this authorization without matching credentials written by a replacement attempt. */
@@ -284,6 +328,7 @@ export async function cleanupMCPServerOAuth({
return typeof metadata.credential_set_id === 'string' ? metadata.credential_set_id : undefined;
};
let tokenRecords = new Map<string, TokenRecord>();
+ let snapshotSupportsRevocation = false;
/** The client record is the credential-set commit marker. Bookending the remaining reads with
* it prevents teardown from combining records on opposite sides of a concurrent callback. */
for (let attempt = 0; attempt < 3; attempt++) {
@@ -309,11 +354,11 @@ export async function cleanupMCPServerOAuth({
const clientUnchanged =
clientBefore?.token === clientAfter?.token &&
getCredentialSetId(clientBefore) === getCredentialSetId(clientAfter);
- const generationCoherent =
- generations.length === 0 ||
- (generations.length === presentRecords.length && new Set(generations).size === 1);
+ const generationCoherent = new Set(generations).size <= 1;
if (clientUnchanged && generationCoherent) {
tokenRecords = candidate;
+ snapshotSupportsRevocation =
+ presentRecords.length > 0 && generations.length === presentRecords.length;
break;
}
}
@@ -359,6 +404,7 @@ export async function cleanupMCPServerOAuth({
});
const clientKey = `mcp_oauth_client:mcp:${serverName}:client`;
if (
+ !snapshotSupportsRevocation ||
clientTokenData?.clientMetadata.credential_set_id !== tokenGenerationSnapshot.get(clientKey)
) {
clientTokenData = null;
diff --git a/packages/api/src/mcp/oauth/tokens.ts b/packages/api/src/mcp/oauth/tokens.ts
index 3419a68211..898b5c7a32 100644
--- a/packages/api/src/mcp/oauth/tokens.ts
+++ b/packages/api/src/mcp/oauth/tokens.ts
@@ -9,6 +9,7 @@ import type {
} from '@librechat/data-schemas';
import type { OAuthTokens, OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';
import type { MCPOAuthTokens, ExtendedOAuthTokens, OAuthStoredClientMetadata } from './types';
+import type { FlowLease, FlowStateManager } from '~/flow/manager';
import { isInvalidClientMessage } from '~/mcp/utils';
import { isSystemUserId } from '~/mcp/enum';
@@ -39,6 +40,8 @@ interface StoreTokensParams {
metadata?: Partial<OAuthStoredClientMetadata>;
/** Existing generation that must still own every stored record before a refresh is persisted. */
expectedCredentialSetId?: string;
+ /** Internal refresh-teardown fence; interactive authorization writes omit it. */
+ signal?: AbortSignal;
/** Optional: Pass existing token state to avoid duplicate DB calls */
existingTokens?: {
accessToken?: IToken | null;
@@ -80,8 +83,16 @@ interface GetTokensParams {
onRefreshSuccess?: (tokens: MCPOAuthTokens) => Promise<void>;
/** Separates in-flight redemptions for the same named server under different OAuth bindings. */
singleFlightScope?: string;
+ /** Shared cache-backed fence used to serialize refresh persistence with server teardown. */
+ flowManager?: Pick<FlowStateManager, 'getLeaseGeneration' | 'acquireLease'>;
}
+export const getMCPOAuthLeaseId = (
+ userId: string,
+ serverName: string,
+ tenantId: string | undefined = getTenantId(),
+): string => JSON.stringify([tenantId ?? '', userId, serverName]);
+
/**
* Reads the `exp` claim (RFC 7519 §4.1.4 / RFC 9068) from a JWT-format access
* token, returned as epoch milliseconds. Returns null for opaque (non-JWT)
@@ -148,6 +159,9 @@ export class MCPTokenStorage {
* after settlement triggers a fresh redemption.
*/
private static inflightRefreshes = new Map<string, Promise<MCPOAuthTokens | null>>();
+ private static inflightRefreshControllers = new Map<string, AbortController>();
+ private static inflightRefreshOwners = new Map<string, string>();
+ private static refreshTeardownCounts = new Map<string, number>();
/**
* How long an in-flight redemption may run before it is aborted. Generous
@@ -164,6 +178,51 @@ export class MCPTokenStorage {
: `[MCP][User: ${userId}][${serverName}]`;
}
+ private static getRefreshOwnerKey(
+ userId: string,
+ serverName: string,
+ tenantId: string | undefined = getTenantId(),
+ ): string {
+ return JSON.stringify([tenantId ?? '', userId, serverName]);
+ }
+
+ static isRefreshTeardownActive(
+ userId: string,
+ serverName: string,
+ tenantId: string | undefined = getTenantId(),
+ ): boolean {
+ return this.refreshTeardownCounts.has(this.getRefreshOwnerKey(userId, serverName, tenantId));
+ }
+
+ /** Holds a per-user/server gate, then aborts and joins every process-local refresh that entered
+ * before it. The returned release keeps successor refreshes out until teardown finishes. */
+ static async beginRefreshTeardown(userId: string, serverName: string): Promise<() => void> {
+ const ownerKey = this.getRefreshOwnerKey(userId, serverName);
+ this.refreshTeardownCounts.set(ownerKey, (this.refreshTeardownCounts.get(ownerKey) ?? 0) + 1);
+ const refreshes: Promise<MCPOAuthTokens | null>[] = [];
+ for (const [key, refresh] of this.inflightRefreshes) {
+ if (this.inflightRefreshOwners.get(key) !== ownerKey) {
+ continue;
+ }
+ this.inflightRefreshControllers.get(key)?.abort();
+ refreshes.push(refresh);
+ }
+ await Promise.allSettled(refreshes);
+ let released = false;
+ return () => {
+ if (released) {
+ return;
+ }
+ released = true;
+ const remaining = (this.refreshTeardownCounts.get(ownerKey) ?? 1) - 1;
+ if (remaining > 0) {
+ this.refreshTeardownCounts.set(ownerKey, remaining);
+ } else {
+ this.refreshTeardownCounts.delete(ownerKey);
+ }
+ };
+ }
+
/** Returns whether storage contains a currently usable, generation-bound authorization. */
static async hasStoredAuthorization({
userId,
@@ -313,6 +372,7 @@ export class MCPTokenStorage {
existingTokens,
metadata,
expectedCredentialSetId,
+ signal,
}: StoreTokensParams): Promise<MCPOAuthTokens> {
const logPrefix = this.getLogPrefix(userId, serverName);
const rollbackWrites: Array<() => Promise<void>> = [];
@@ -651,6 +711,9 @@ export class MCPTokenStorage {
: plannedWrites;
for (const write of orderedWrites) {
+ if (signal?.aborted) {
+ throw new Error('Token storage aborted by OAuth teardown');
+ }
if (findToken && updateToken && write.existingToken) {
await updateIfCurrent(
write.existingToken,
@@ -747,10 +810,28 @@ export class MCPTokenStorage {
existingAccessToken?: IToken | null;
},
): Promise<MCPOAuthTokens | null> {
- const { userId, serverName, refreshTokens, createToken, signal, singleFlightScope } = params;
+ const {
+ userId,
+ serverName,
+ refreshTokens,
+ createToken,
+ signal,
+ singleFlightScope,
+ flowManager,
+ } = params;
const logPrefix = this.getLogPrefix(userId, serverName);
- const refreshKey = `${getTenantId() ?? ''}:${userId}:${serverName}:${singleFlightScope ?? ''}`;
+ const ownerKey = this.getRefreshOwnerKey(userId, serverName);
+ if (this.refreshTeardownCounts.has(ownerKey)) {
+ logger.debug(`${logPrefix} Skipping token refresh during OAuth teardown`);
+ return null;
+ }
+ const refreshKey = JSON.stringify([
+ getTenantId() ?? '',
+ userId,
+ serverName,
+ singleFlightScope ?? '',
+ ]);
const inflight = this.inflightRefreshes.get(refreshKey);
if (inflight) {
logger.debug(`${logPrefix} Joining in-flight token refresh`);
@@ -767,6 +848,7 @@ export class MCPTokenStorage {
return null;
}
+ const leaseId = getMCPOAuthLeaseId(userId, serverName);
/**
* The shared redemption is owner-neutral: no caller's `AbortSignal` is
* threaded into the execution, so an impatient waiter (e.g. the silent
@@ -775,15 +857,36 @@ export class MCPTokenStorage {
* execution itself is bounded by the internal stale-abort controller below.
*/
const executionController = new AbortController();
- const refreshPromise = this.executeTokenRefresh({
- ...params,
- refreshTokens,
- createToken,
- signal: executionController.signal,
- }).finally(() => {
- clearTimeout(staleTimer);
+ const staleTimerRef: { current?: NodeJS.Timeout } = {};
+ /** Reserve the local single-flight slot before the asynchronous distributed-fence read. */
+ const refreshPromise = (async () => {
+ const leaseGeneration = flowManager
+ ? await flowManager.getLeaseGeneration(leaseId)
+ : undefined;
+ if (leaseGeneration === null) {
+ logger.debug(`${logPrefix} Skipping token refresh while OAuth teardown owns the lease`);
+ return null;
+ }
+ if (this.refreshTeardownCounts.has(ownerKey)) {
+ logger.debug(`${logPrefix} Skipping token refresh during OAuth teardown`);
+ return null;
+ }
+ return this.executeTokenRefresh({
+ ...params,
+ refreshTokens,
+ createToken,
+ signal: executionController.signal,
+ leaseId,
+ leaseGeneration,
+ });
+ })().finally(() => {
+ if (staleTimerRef.current) {
+ clearTimeout(staleTimerRef.current);
+ }
if (this.inflightRefreshes.get(refreshKey) === refreshPromise) {
this.inflightRefreshes.delete(refreshKey);
+ this.inflightRefreshControllers.delete(refreshKey);
+ this.inflightRefreshOwners.delete(refreshKey);
}
});
/**
@@ -805,7 +908,7 @@ export class MCPTokenStorage {
* same re-authentication the proactive deletion would force on every
* stall, while deletion would also foreclose the silent recovery paths.
*/
- const staleTimer = setTimeout(() => {
+ staleTimerRef.current = setTimeout(() => {
if (this.inflightRefreshes.get(refreshKey) === refreshPromise) {
logger.warn(
`${logPrefix} Aborting stalled in-flight token refresh after ${MCPTokenStorage.INFLIGHT_REFRESH_STALE_MS}ms`,
@@ -813,8 +916,10 @@ export class MCPTokenStorage {
executionController.abort();
}
}, MCPTokenStorage.INFLIGHT_REFRESH_STALE_MS);
- staleTimer.unref?.();
+ staleTimerRef.current.unref?.();
this.inflightRefreshes.set(refreshKey, refreshPromise);
+ this.inflightRefreshControllers.set(refreshKey, executionController);
+ this.inflightRefreshOwners.set(refreshKey, ownerKey);
return this.raceWithAbort(refreshPromise, signal);
}
@@ -868,12 +973,17 @@ export class MCPTokenStorage {
existingAccessToken,
onRefreshSuccess,
signal,
+ flowManager,
+ leaseId,
+ leaseGeneration,
}: GetTokensParams & {
existingAccessToken?: IToken | null;
refreshTokens: NonNullable<GetTokensParams['refreshTokens']>;
createToken: NonNullable<GetTokensParams['createToken']>;
/** Internal stale-abort signal owned by `forceRefreshTokens` — never a caller's. */
signal: AbortSignal;
+ leaseId: string;
+ leaseGeneration?: number;
}): Promise<MCPOAuthTokens | null> {
const logPrefix = this.getLogPrefix(userId, serverName);
const identifier = `mcp:${serverName}`;
@@ -981,25 +1091,52 @@ export class MCPTokenStorage {
expires_at: newTokens.expires_at,
});
+ if (signal.aborted) {
+ throw new Error('Token refresh aborted before storing refreshed credentials');
+ }
+
+ let persistenceLease: FlowLease | null = null;
+ if (flowManager && leaseGeneration !== undefined) {
+ persistenceLease = await flowManager.acquireLease(leaseId, {
+ expectedGeneration: leaseGeneration,
+ });
+ if (!persistenceLease) {
+ logger.debug(`${logPrefix} Discarding refresh response superseded by OAuth teardown`);
+ return null;
+ }
+ }
+
// Store the refreshed tokens (handles both create and update)
// Pass existing token state to avoid duplicate DB calls
- const storedTokens = await this.storeTokens({
- userId,
- serverName,
- tokens: newTokens,
- createToken,
- updateToken,
- deleteTokens,
- findToken,
- clientInfo,
- existingTokens: {
- accessToken: existingAccessToken ?? undefined,
- refreshToken: refreshTokenData,
- clientInfoToken: clientInfoData,
- },
- metadata: storedClientMetadata,
- expectedCredentialSetId: refreshCredentialSetId,
- });
+ let storedTokens: MCPOAuthTokens;
+ try {
+ storedTokens = await this.storeTokens({
+ userId,
+ serverName,
+ tokens: newTokens,
+ createToken,
+ updateToken,
+ deleteTokens,
+ findToken,
+ clientInfo,
+ existingTokens: {
+ accessToken: existingAccessToken ?? undefined,
+ refreshToken: refreshTokenData,
+ clientInfoToken: clientInfoData,
+ },
+ metadata: storedClientMetadata,
+ expectedCredentialSetId: refreshCredentialSetId,
+ signal,
+ });
+ } finally {
+ try {
+ await persistenceLease?.release();
+ } catch (releaseError) {
+ logger.warn(`${logPrefix} Failed to release OAuth refresh persistence lease`, {
+ error: releaseError,
+ });
+ }
+ }
if (onRefreshSuccess) {
try {
@@ -1071,6 +1208,7 @@ export class MCPTokenStorage {
deleteTokens,
refreshTokens,
singleFlightScope,
+ flowManager,
}: GetTokensParams): Promise<MCPOAuthTokens | null> {
const logPrefix = this.getLogPrefix(userId, serverName);
@@ -1119,6 +1257,7 @@ export class MCPTokenStorage {
deleteTokens,
refreshTokens,
singleFlightScope,
+ flowManager,
existingAccessToken: accessTokenData,
});
}