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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🛂 fix: MCP OAuth Race Conditions, CSRF Fallback, and Token Expiry Handling (#12171)
Danny Avilafcb344da47cb
diff --git a/.env.example b/.env.exampleindex b851749baf..e746737ea4 100644--- a/.env.example+++ b/.env.example@@ -850,3 +850,24 @@ OPENWEATHER_API_KEY=# Skip code challenge method validation (e.g., for AWS Cognito that supports S256 but doesn't advertise it)# When set to true, forces S256 code challenge even if not advertised in .well-known/openid-configuration# MCP_SKIP_CODE_CHALLENGE_CHECK=false++# Circuit breaker: max connect/disconnect cycles before tripping (per server)+# MCP_CB_MAX_CYCLES=7++# Circuit breaker: sliding window (ms) for counting cycles+# MCP_CB_CYCLE_WINDOW_MS=45000++# Circuit breaker: cooldown (ms) after the cycle breaker trips+# MCP_CB_CYCLE_COOLDOWN_MS=15000++# Circuit breaker: max consecutive failed connection rounds before backoff+# MCP_CB_MAX_FAILED_ROUNDS=3++# Circuit breaker: sliding window (ms) for counting failed rounds+# MCP_CB_FAILED_WINDOW_MS=120000++# Circuit breaker: base backoff (ms) after failed round threshold is reached+# MCP_CB_BASE_BACKOFF_MS=30000++# Circuit breaker: max backoff cap (ms) for exponential backoff+# MCP_CB_MAX_BACKOFF_MS=300000diff --git a/api/server/routes/__tests__/mcp.spec.js b/api/server/routes/__tests__/mcp.spec.jsindex e87fcf8f15..009b602604 100644--- a/api/server/routes/__tests__/mcp.spec.js+++ b/api/server/routes/__tests__/mcp.spec.js@@ -32,6 +32,9 @@ jest.mock('@librechat/api', () => {getFlowState: jest.fn(),completeOAuthFlow: jest.fn(),generateFlowId: jest.fn(),+ resolveStateToFlowId: jest.fn(async (state) => state),+ storeStateMapping: jest.fn(),+ deleteStateMapping: jest.fn(),},MCPTokenStorage: {storeTokens: jest.fn(),@@ -180,7 +183,10 @@ describe('MCP Routes', () => {MCPOAuthHandler.initiateOAuthFlow.mockResolvedValue({authorizationUrl: 'https://oauth.example.com/auth',flowId: 'test-user-id:test-server',+ flowMetadata: { state: 'random-state-value' },});+ MCPOAuthHandler.storeStateMapping.mockResolvedValue();+ mockFlowManager.initFlow = jest.fn().mockResolvedValue();const response = await request(app).get('/api/mcp/test-server/oauth/initiate').query({userId: 'test-user-id',@@ -367,6 +373,121 @@ describe('MCP Routes', () => {expect(response.headers.location).toBe(`${basePath}/oauth/error?error=invalid_state`);});+ describe('CSRF fallback via active PENDING flow', () => {+ it('should proceed when a fresh PENDING flow exists and no cookies are present', async () => {+ const flowId = 'test-user-id:test-server';+ const mockFlowManager = {+ getFlowState: jest.fn().mockResolvedValue({+ status: 'PENDING',+ createdAt: Date.now(),+ }),+ completeFlow: jest.fn().mockResolvedValue(true),+ deleteFlow: jest.fn().mockResolvedValue(true),+ };+ const mockFlowState = {+ serverName: 'test-server',+ userId: 'test-user-id',+ metadata: {},+ clientInfo: {},+ codeVerifier: 'test-verifier',+ };++ getLogStores.mockReturnValue({});+ require('~/config').getFlowStateManager.mockReturnValue(mockFlowManager);+ MCPOAuthHandler.getFlowState.mockResolvedValue(mockFlowState);+ MCPOAuthHandler.completeOAuthFlow.mockResolvedValue({+ access_token: 'test-token',+ });+ MCPTokenStorage.storeTokens.mockResolvedValue();+ mockRegistryInstance.getServerConfig.mockResolvedValue({});++ const mockMcpManager = {+ getUserConnection: jest.fn().mockResolvedValue({+ fetchTools: jest.fn().mockResolvedValue([]),+ }),+ };+ require('~/config').getMCPManager.mockReturnValue(mockMcpManager);+ require('~/config').getOAuthReconnectionManager.mockReturnValue({+ clearReconnection: jest.fn(),+ });+ require('~/server/services/Config/mcp').updateMCPServerTools.mockResolvedValue();++ const response = await request(app)+ .get('/api/mcp/test-server/oauth/callback')+ .query({ code: 'test-code', state: flowId });++ const basePath = getBasePath();+ expect(response.status).toBe(302);+ expect(response.headers.location).toContain(`${basePath}/oauth/success`);+ });++ it('should reject when no PENDING flow exists and no cookies are present', async () => {+ const flowId = 'test-user-id:test-server';+ const mockFlowManager = {+ getFlowState: jest.fn().mockResolvedValue(null),+ };++ getLogStores.mockReturnValue({});+ require('~/config').getFlowStateManager.mockReturnValue(mockFlowManager);++ const response = await request(app)+ .get('/api/mcp/test-server/oauth/callback')+ .query({ code: 'test-code', state: flowId });++ const basePath = getBasePath();+ expect(response.status).toBe(302);+ expect(response.headers.location).toBe(+ `${basePath}/oauth/error?error=csrf_validation_failed`,+ );+ });++ it('should reject when only a COMPLETED flow exists (not PENDING)', async () => {+ const flowId = 'test-user-id:test-server';+ const mockFlowManager = {+ getFlowState: jest.fn().mockResolvedValue({+ status: 'COMPLETED',+ createdAt: Date.now(),+ }),+ };++ getLogStores.mockReturnValue({});+ require('~/config').getFlowStateManager.mockReturnValue(mockFlowManager);++ const response = await request(app)+ .get('/api/mcp/test-server/oauth/callback')+ .query({ code: 'test-code', state: flowId });++ const basePath = getBasePath();+ expect(response.status).toBe(302);+ expect(response.headers.location).toBe(+ `${basePath}/oauth/error?error=csrf_validation_failed`,+ );+ });++ it('should reject when PENDING flow is stale (older than PENDING_STALE_MS)', async () => {+ const flowId = 'test-user-id:test-server';+ const mockFlowManager = {+ getFlowState: jest.fn().mockResolvedValue({+ status: 'PENDING',+ createdAt: Date.now() - 3 * 60 * 1000,+ }),+ };++ getLogStores.mockReturnValue({});+ require('~/config').getFlowStateManager.mockReturnValue(mockFlowManager);++ const response = await request(app)+ .get('/api/mcp/test-server/oauth/callback')+ .query({ code: 'test-code', state: flowId });++ const basePath = getBasePath();+ expect(response.status).toBe(302);+ expect(response.headers.location).toBe(+ `${basePath}/oauth/error?error=csrf_validation_failed`,+ );+ });+ });+it('should handle OAuth callback successfully', async () => {// mockRegistryInstance is defined at the top of the fileconst mockFlowManager = {diff --git a/api/server/routes/mcp.js b/api/server/routes/mcp.jsindex 2db8c2c462..0afac81192 100644--- a/api/server/routes/mcp.js+++ b/api/server/routes/mcp.js@@ -13,6 +13,7 @@ const {MCPOAuthHandler,MCPTokenStorage,setOAuthSession,+ PENDING_STALE_MS,getUserMCPAuthMap,validateOAuthCsrf,OAUTH_CSRF_COOKIE,@@ -91,7 +92,11 @@ router.get('/:serverName/oauth/initiate', requireJwtAuth, setOAuthSession, async}const oauthHeaders = await getOAuthHeaders(serverName, userId);- const { authorizationUrl, flowId: oauthFlowId } = await MCPOAuthHandler.initiateOAuthFlow(+ const {+ authorizationUrl,+ flowId: oauthFlowId,+ flowMetadata,+ } = await MCPOAuthHandler.initiateOAuthFlow(serverName,serverUrl,userId,@@ -101,6 +106,7 @@ router.get('/:serverName/oauth/initiate', requireJwtAuth, setOAuthSession, asynclogger.debug('[MCP OAuth] OAuth flow initiated', { oauthFlowId, authorizationUrl });+ await MCPOAuthHandler.storeStateMapping(flowMetadata.state, oauthFlowId, flowManager);setOAuthCsrfCookie(res, oauthFlowId, OAUTH_CSRF_COOKIE_PATH);res.redirect(authorizationUrl);} catch (error) {@@ -143,30 +149,52 @@ router.get('/:serverName/oauth/callback', async (req, res) => {return res.redirect(`${basePath}/oauth/error?error=missing_state`);}- const flowId = state;- logger.debug('[MCP OAuth] Using flow ID from state', { flowId });+ const flowsCache = getLogStores(CacheKeys.FLOWS);+ const flowManager = getFlowStateManager(flowsCache);++ const flowId = await MCPOAuthHandler.resolveStateToFlowId(state, flowManager);+ if (!flowId) {+ logger.error('[MCP OAuth] Could not resolve state to flow ID', { state });+ return res.redirect(`${basePath}/oauth/error?error=invalid_state`);+ }+ logger.debug('[MCP OAuth] Resolved flow ID from state', { flowId });const flowParts = flowId.split(':');if (flowParts.length < 2 || !flowParts[0] || !flowParts[1]) {- logger.error('[MCP OAuth] Invalid flow ID format in state', { flowId });+ logger.error('[MCP OAuth] Invalid flow ID format', { flowId });return res.redirect(`${basePath}/oauth/error?error=invalid_state`);}const [flowUserId] = flowParts;- if (- !validateOAuthCsrf(req, res, flowId, OAUTH_CSRF_COOKIE_PATH) &&- !validateOAuthSession(req, flowUserId)- ) {- logger.error('[MCP OAuth] CSRF validation failed: no valid CSRF or session cookie', {- flowId,- hasCsrfCookie: !!req.cookies?.[OAUTH_CSRF_COOKIE],- hasSessionCookie: !!req.cookies?.[OAUTH_SESSION_COOKIE],- });- return res.redirect(`${basePath}/oauth/error?error=csrf_validation_failed`);++ const hasCsrf = validateOAuthCsrf(req, res, flowId, OAUTH_CSRF_COOKIE_PATH);+ const hasSession = !hasCsrf && validateOAuthSession(req, flowUserId);+ let hasActiveFlow = false;+ if (!hasCsrf && !hasSession) {+ const pendingFlow = await flowManager.getFlowState(flowId, 'mcp_oauth');+ const pendingAge = pendingFlow?.createdAt ? Date.now() - pendingFlow.createdAt : Infinity;+ hasActiveFlow = pendingFlow?.status === 'PENDING' && pendingAge < PENDING_STALE_MS;+ if (hasActiveFlow) {+ logger.debug(+ '[MCP OAuth] CSRF/session cookies absent, validating via active PENDING flow',+ {+ flowId,+ },+ );+ }}- const flowsCache = getLogStores(CacheKeys.FLOWS);- const flowManager = getFlowStateManager(flowsCache);+ if (!hasCsrf && !hasSession && !hasActiveFlow) {+ logger.error(+ '[MCP OAuth] CSRF validation failed: no valid CSRF cookie, session cookie, or active flow',+ {+ flowId,+ hasCsrfCookie: !!req.cookies?.[OAUTH_CSRF_COOKIE],+ hasSessionCookie: !!req.cookies?.[OAUTH_SESSION_COOKIE],+ },+ );+ return res.redirect(`${basePath}/oauth/error?error=csrf_validation_failed`);+ }logger.debug('[MCP OAuth] Getting flow state for flowId: ' + flowId);const flowState = await MCPOAuthHandler.getFlowState(flowId, flowManager);@@ -281,7 +309,13 @@ router.get('/:serverName/oauth/callback', async (req, res) => {const toolFlowId = flowState.metadata?.toolFlowId;if (toolFlowId) {logger.debug('[MCP OAuth] Completing tool flow', { toolFlowId });- await flowManager.completeFlow(toolFlowId, 'mcp_oauth', tokens);+ const completed = await flowManager.completeFlow(toolFlowId, 'mcp_oauth', tokens);+ if (!completed) {+ logger.warn(+ '[MCP OAuth] Tool flow state not found during completion — waiter will time out',+ { toolFlowId },+ );+ }}/** Redirect to success page with flowId and serverName */diff --git a/packages/api/jest.config.mjs b/packages/api/jest.config.mjsindex 530150a7fa..df9cf6bcc2 100644--- a/packages/api/jest.config.mjs+++ b/packages/api/jest.config.mjs@@ -7,6 +7,7 @@ export default {'\\.dev\\.ts$','\\.helper\\.ts$','\\.helper\\.d\\.ts$',+ '/__tests__/helpers/',],coverageReporters: ['text', 'cobertura'],testResultsProcessor: 'jest-junit',diff --git a/packages/api/package.json b/packages/api/package.jsonindex e4ca4ef3c5..46587797a5 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -18,8 +18,8 @@"build:dev": "npm run clean && NODE_ENV=development rollup -c --bundleConfigAsCjs","build:watch": "NODE_ENV=development rollup -c -w --bundleConfigAsCjs","build:watch:prod": "rollup -c -w --bundleConfigAsCjs",- "test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.\"",- "test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.\"",+ "test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/\"",+ "test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/\"","test:cache-integration:core": "jest --testPathPatterns=\"src/cache/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false","test:cache-integration:cluster": "jest --testPathPatterns=\"src/cluster/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false --runInBand","test:cache-integration:mcp": "jest --testPathPatterns=\"src/mcp/.*\\.cache_integration\\.spec\\.ts$\" --coverage=false",diff --git a/packages/api/src/flow/manager.ts b/packages/api/src/flow/manager.tsindex 4f9023a3d7..b68b9edb7a 100644--- a/packages/api/src/flow/manager.ts+++ b/packages/api/src/flow/manager.ts@@ -3,6 +3,18 @@ import { logger } from '@librechat/data-schemas';import type { StoredDataNoRaw } from 'keyv';import type { FlowState, FlowMetadata, FlowManagerOptions } from './types';+export const PENDING_STALE_MS = 2 * 60 * 1000;++const SECONDS_THRESHOLD = 1e10;++/**+ * Normalizes an expiration timestamp to milliseconds.+ * Timestamps below 10 billion are assumed to be in seconds (valid until ~2286).+ */+export function normalizeExpiresAt(timestamp: number): number {+ return timestamp < SECONDS_THRESHOLD ? timestamp * 1000 : timestamp;+}+export class FlowStateManager<T = unknown> {private keyv: Keyv;private ttl: number;@@ -45,32 +57,8 @@ export class FlowStateManager<T = unknown> {return `${type}:${flowId}`;}- /**- * Normalizes an expiration timestamp to milliseconds.- * Detects whether the input is in seconds or milliseconds based on magnitude.- * Timestamps below 10 billion are assumed to be in seconds (valid until ~2286).- * @param timestamp - The expiration timestamp (in seconds or milliseconds)- * @returns The timestamp normalized to milliseconds- */- private normalizeExpirationTimestamp(timestamp: number): number {- const SECONDS_THRESHOLD = 1e10;- if (timestamp < SECONDS_THRESHOLD) {- return timestamp * 1000;- }- return timestamp;- }-- /**- * Checks if a flow's token has expired based on its expires_at field- * @param flowState - The flow state to check- * @returns true if the token has expired, false otherwise (including if no expires_at exists)- */private isTokenExpired(flowState: FlowState<T> | undefined): boolean {- if (!flowState?.result) {- return false;- }-- if (typeof flowState.result !== 'object') {+ if (!flowState?.result || typeof flowState.result !== 'object') {return false;}@@ -79,13 +67,11 @@ export class FlowStateManager<T = unknown> {}const expiresAt = (flowState.result as { expires_at: unknown }).expires_at;-if (typeof expiresAt !== 'number' || !Number.isFinite(expiresAt)) {return false;}- const normalizedExpiresAt = this.normalizeExpirationTimestamp(expiresAt);- return normalizedExpiresAt < Date.now();+ return normalizeExpiresAt(expiresAt) < Date.now();}/**@@ -149,6 +135,8 @@ export class FlowStateManager<T = unknown> {let elapsedTime = 0;let isCleanedUp = false;let intervalId: NodeJS.Timeout | null = null;+ let missingStateRetried = false;+ let isRetrying = false;// Cleanup function to avoid duplicate cleanupconst cleanup = () => {@@ -188,16 +176,29 @@ export class FlowStateManager<T = unknown> {}intervalId = setInterval(async () => {- if (isCleanedUp) return;+ if (isCleanedUp || isRetrying) return;try {- const flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;+ let flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;if (!flowState) {- cleanup();- logger.error(`[${flowKey}] Flow state not found`);- reject(new Error(`${type} Flow state not found`));- return;+ if (!missingStateRetried) {+ missingStateRetried = true;+ isRetrying = true;+ logger.warn(+ `[${flowKey}] Flow state not found, retrying once after 500ms (race recovery)`,+ );+ await new Promise((r) => setTimeout(r, 500));+ flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;+ isRetrying = false;+ }++ if (!flowState) {+ cleanup();+ logger.error(`[${flowKey}] Flow state not found after retry`);+ reject(new Error(`${type} Flow state not found`));+ return;+ }}if (signal?.aborted) {@@ -251,10 +252,10 @@ export class FlowStateManager<T = unknown> {const flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;if (!flowState) {- logger.warn('[FlowStateManager] Cannot complete flow - flow state not found', {- flowId,- type,- });+ logger.warn(+ '[FlowStateManager] Flow state not found during completion — cannot recover metadata, skipping',+ { flowId, type },+ );return false;}@@ -297,7 +298,7 @@ export class FlowStateManager<T = unknown> {async isFlowStale(flowId: string,type: string,- staleThresholdMs: number = 2 * 60 * 1000,+ staleThresholdMs: number = PENDING_STALE_MS,): Promise<{ isStale: boolean; age: number; status?: string }> {const flowKey = this.getFlowKey(flowId, type);const flowState = (await this.keyv.get(flowKey)) as FlowState<T> | undefined;diff --git a/packages/api/src/mcp/MCPConnectionFactory.ts b/packages/api/src/mcp/MCPConnectionFactory.tsindex 03131b659b..0fc86e0315 100644--- a/packages/api/src/mcp/MCPConnectionFactory.ts+++ b/packages/api/src/mcp/MCPConnectionFactory.ts@@ -2,11 +2,11 @@ import { logger } from '@librechat/data-schemas';import type { OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';import type { Tool } from '@modelcontextprotocol/sdk/types.js';import type { TokenMethods } from '@librechat/data-schemas';-import type { MCPOAuthTokens, OAuthMetadata } from '~/mcp/oauth';+import type { MCPOAuthTokens, OAuthMetadata, MCPOAuthFlowMetadata } from '~/mcp/oauth';import type { FlowStateManager } from '~/flow/manager';-import type { FlowMetadata } from '~/flow/types';import type * as t from './types';-import { MCPTokenStorage, MCPOAuthHandler } from '~/mcp/oauth';+import { MCPTokenStorage, MCPOAuthHandler, ReauthenticationRequiredError } from '~/mcp/oauth';+import { PENDING_STALE_MS, normalizeExpiresAt } from '~/flow/manager';import { sanitizeUrlForLogging } from './utils';import { withTimeout } from '~/utils/promise';import { MCPConnection } from './connection';@@ -104,6 +104,7 @@ export class MCPConnectionFactory {return { tools, connection, oauthRequired: false, oauthUrl: null };}} catch {+ MCPConnection.decrementCycleCount(this.serverName);logger.debug(`${this.logPrefix} [Discovery] Connection failed, attempting unauthenticated tool listing`,);@@ -125,7 +126,9 @@ export class MCPConnectionFactory {}return { tools, connection: null, oauthRequired, oauthUrl };}+ MCPConnection.decrementCycleCount(this.serverName);} catch (listError) {+ MCPConnection.decrementCycleCount(this.serverName);logger.debug(`${this.logPrefix} [Discovery] Unauthenticated tool listing failed:`, listError);}@@ -265,6 +268,10 @@ export class MCPConnectionFactory {if (tokens) logger.info(`${this.logPrefix} Loaded OAuth tokens`);return tokens;} catch (error) {+ if (error instanceof ReauthenticationRequiredError) {+ logger.info(`${this.logPrefix} ${error.message}, will trigger OAuth flow`);+ return null;+ }logger.debug(`${this.logPrefix} No existing tokens found or error loading tokens`, error);return null;}@@ -306,11 +313,21 @@ export class MCPConnectionFactory {const existingFlow = await this.flowManager!.getFlowState(flowId, 'mcp_oauth');if (existingFlow?.status === 'PENDING') {+ const pendingAge = existingFlow.createdAt+ ? Date.now() - existingFlow.createdAt+ : Infinity;++ if (pendingAge < PENDING_STALE_MS) {+ logger.debug(+ `${this.logPrefix} Recent PENDING OAuth flow exists (${Math.round(pendingAge / 1000)}s old), skipping new initiation`,+ );+ connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));+ return;+ }+logger.debug(- `${this.logPrefix} PENDING OAuth flow already exists, skipping new initiation`,+ `${this.logPrefix} Found stale PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), will replace`,);- connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));- return;}const {@@ -326,11 +343,17 @@ export class MCPConnectionFactory {);if (existingFlow) {+ const oldState = (existingFlow.metadata as MCPOAuthFlowMetadata)?.state;await this.flowManager!.deleteFlow(newFlowId, 'mcp_oauth');+ if (oldState) {+ await MCPOAuthHandler.deleteStateMapping(oldState, this.flowManager!);+ }}// Store flow state BEFORE redirecting so the callback can find it- await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', flowMetadata);+ const metadataWithUrl = { ...flowMetadata, authorizationUrl };+ await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);+ await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager!);// 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)@@ -495,11 +518,75 @@ export class MCPConnectionFactory {const existingFlow = await this.flowManager.getFlowState(flowId, 'mcp_oauth');if (existingFlow) {+ const flowMeta = existingFlow.metadata as MCPOAuthFlowMetadata | undefined;++ if (existingFlow.status === 'PENDING') {+ const pendingAge = existingFlow.createdAt+ ? Date.now() - existingFlow.createdAt+ : Infinity;++ if (pendingAge < PENDING_STALE_MS) {+ logger.debug(+ `${this.logPrefix} Found recent PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), joining instead of creating new one`,+ );++ const storedAuthUrl = flowMeta?.authorizationUrl;+ if (storedAuthUrl && typeof this.oauthStart === 'function') {+ logger.info(+ `${this.logPrefix} Re-issuing stored authorization URL to caller while joining PENDING flow`,+ );+ await this.oauthStart(storedAuthUrl);+ }++ const tokens = await this.flowManager.createFlow(flowId, 'mcp_oauth', {}, this.signal);+ if (typeof this.oauthEnd === 'function') {+ await this.oauthEnd();+ }+ logger.info(+ `${this.logPrefix} Joined existing OAuth flow completed for ${this.serverName}`,+ );+ return {+ tokens,+ clientInfo: flowMeta?.clientInfo,+ metadata: flowMeta?.metadata,+ };+ }++ logger.debug(+ `${this.logPrefix} Found stale PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), will delete and start fresh`,+ );+ }++ if (existingFlow.status === 'COMPLETED') {+ const completedAge = existingFlow.completedAt+ ? Date.now() - existingFlow.completedAt+ : Infinity;+ const cachedTokens = existingFlow.result as MCPOAuthTokens | null | undefined;+ const isTokenExpired =+ cachedTokens?.expires_at != null &&+ normalizeExpiresAt(cachedTokens.expires_at) < Date.now();++ if (completedAge <= PENDING_STALE_MS && cachedTokens !== undefined && !isTokenExpired) {+ logger.debug(+ `${this.logPrefix} Found non-stale COMPLETED OAuth flow, reusing cached tokens`,+ );+ return {+ tokens: cachedTokens,+ clientInfo: flowMeta?.clientInfo,+ metadata: flowMeta?.metadata,+ };+ }+ }+logger.debug(`${this.logPrefix} Found existing OAuth flow (status: ${existingFlow.status}), cleaning up to start fresh`,);try {+ const oldState = flowMeta?.state;await this.flowManager.deleteFlow(flowId, 'mcp_oauth');+ if (oldState) {+ await MCPOAuthHandler.deleteStateMapping(oldState, this.flowManager);+ }} catch (error) {logger.warn(`${this.logPrefix} Failed to clean up existing OAuth flow`, error);}@@ -519,7 +606,9 @@ export class MCPConnectionFactory {);// Store flow state BEFORE redirecting so the callback can find it- await this.flowManager.initFlow(newFlowId, 'mcp_oauth', flowMetadata as FlowMetadata);+ const metadataWithUrl = { ...flowMetadata, authorizationUrl };+ await this.flowManager.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);+ await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager);if (typeof this.oauthStart === 'function') {logger.info(`${this.logPrefix} OAuth flow started, issued authorization URL to user`);diff --git a/packages/api/src/mcp/UserConnectionManager.ts b/packages/api/src/mcp/UserConnectionManager.tsindex 0828b1720a..76523fc0fc 100644--- a/packages/api/src/mcp/UserConnectionManager.ts+++ b/packages/api/src/mcp/UserConnectionManager.ts@@ -1,10 +1,10 @@import { logger } from '@librechat/data-schemas';import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';-import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';-import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';-import { MCPConnection } from './connection';import type * as t from './types';+import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';+import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';+import { MCPConnection } from './connection';import { mcpConfig } from './mcpConfig';/**@@ -21,6 +21,8 @@ export abstract class UserConnectionManager {protected userConnections: Map<string, Map<string, MCPConnection>> = new Map();/** Last activity timestamp for users (not per server) */protected userLastActivity: Map<string, number> = new Map();+ /** In-flight connection promises keyed by `userId:serverName` — coalesces concurrent attempts */+ protected pendingConnections: Map<string, Promise<MCPConnection>> = new Map();/** Updates the last activity timestamp for a user */protected updateUserLastActivity(userId: string): void {@@ -31,29 +33,64 @@ export abstract class UserConnectionManager {);}- /** Gets or creates a connection for a specific user */- public async getUserConnection({- serverName,- forceNew,- user,- flowManager,- customUserVars,- requestBody,- tokenMethods,- oauthStart,- oauthEnd,- signal,- returnOnOAuth = false,- connectionTimeout,- }: {- serverName: string;- forceNew?: boolean;- } & Omit<t.OAuthConnectionOptions, 'useOAuth'>): Promise<MCPConnection> {+ /** Gets or creates a connection for a specific user, coalescing concurrent attempts */+ public async getUserConnection(+ opts: {+ serverName: string;+ forceNew?: boolean;+ } & Omit<t.OAuthConnectionOptions, 'useOAuth'>,+ ): Promise<MCPConnection> {+ const { serverName, forceNew, user } = opts;const userId = user?.id;if (!userId) {throw new McpError(ErrorCode.InvalidRequest, `[MCP] User object missing id property`);}+ const lockKey = `${userId}:${serverName}`;++ if (!forceNew) {+ const pending = this.pendingConnections.get(lockKey);+ if (pending) {+ logger.debug(`[MCP][User: ${userId}][${serverName}] Joining in-flight connection attempt`);+ return pending;+ }+ }++ const connectionPromise = this.createUserConnectionInternal(opts, userId);++ if (!forceNew) {+ this.pendingConnections.set(lockKey, connectionPromise);+ }++ try {+ return await connectionPromise;+ } finally {+ if (!forceNew && this.pendingConnections.get(lockKey) === connectionPromise) {+ this.pendingConnections.delete(lockKey);+ }+ }+ }++ private async createUserConnectionInternal(+ {+ serverName,+ forceNew,+ user,+ flowManager,+ customUserVars,+ requestBody,+ tokenMethods,+ oauthStart,+ oauthEnd,+ signal,+ returnOnOAuth = false,+ connectionTimeout,+ }: {+ serverName: string;+ forceNew?: boolean;+ } & Omit<t.OAuthConnectionOptions, 'useOAuth'>,+ userId: string,+ ): Promise<MCPConnection> {if (await this.appConnections!.has(serverName)) {throw new McpError(ErrorCode.InvalidRequest,@@ -188,6 +225,7 @@ export abstract class UserConnectionManager {/** Disconnects and removes a specific user connection */public async disconnectUserConnection(userId: string, serverName: string): Promise<void> {+ this.pendingConnections.delete(`${userId}:${serverName}`);const userMap = this.userConnections.get(userId);const connection = userMap?.get(serverName);if (connection) {@@ -215,6 +253,12 @@ export abstract class UserConnectionManager {);}await Promise.allSettled(disconnectPromises);+ // Clean up any pending connection promises for this user+ for (const key of this.pendingConnections.keys()) {+ if (key.startsWith(`${userId}:`)) {+ this.pendingConnections.delete(key);+ }+ }// Ensure user activity timestamp is removedthis.userLastActivity.delete(userId);logger.info(`[MCP][User: ${userId}] All connections processed for disconnection.`);diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.tsindex de18e27e89..bceb23b246 100644--- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts+++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.test.ts@@ -275,7 +275,7 @@ describe('MCPConnectionFactory', () => {expect(mockFlowManager.initFlow).toHaveBeenCalledWith('flow123','mcp_oauth',- mockFlowData.flowMetadata,+ expect.objectContaining(mockFlowData.flowMetadata),);const initCallOrder = mockFlowManager.initFlow.mock.invocationCallOrder[0];const oauthStartCallOrder = (oauthOptions.oauthStart as jest.Mock).mock@@ -550,7 +550,7 @@ describe('MCPConnectionFactory', () => {expect(mockFlowManager.initFlow).toHaveBeenCalledWith('flow123','mcp_oauth',- mockFlowData.flowMetadata,+ expect.objectContaining(mockFlowData.flowMetadata),);const initCallOrder = mockFlowManager.initFlow.mock.invocationCallOrder[0];const oauthStartCallOrder = (oauthOptions.oauthStart as jest.Mock).mockdiff --git a/packages/api/src/mcp/__tests__/MCPOAuthCSRFFallback.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthCSRFFallback.test.tsnew file mode 100644index 0000000000..cdba06cf8d--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthCSRFFallback.test.ts@@ -0,0 +1,232 @@+/**+ * Tests for the OAuth callback CSRF fallback logic.+ *+ * The callback route validates requests via three mechanisms (in order):+ * 1. CSRF cookie (HMAC-based, set during initiate)+ * 2. Session cookie (bound to authenticated userId)+ * 3. Active PENDING flow in FlowStateManager (fallback for SSE/chat flows)+ *+ * This suite tests mechanism 3 — the PENDING flow fallback — including+ * staleness enforcement and rejection of non-PENDING flows.+ *+ * These tests exercise the validation functions directly for fast,+ * focused coverage. Route-level integration tests using supertest+ * are in api/server/routes/__tests__/mcp.spec.js ("CSRF fallback+ * via active PENDING flow" describe block).+ */++import { Keyv } from 'keyv';+import { FlowStateManager, PENDING_STALE_MS } from '~/flow/manager';+import type { Request, Response } from 'express';+import {+ generateOAuthCsrfToken,+ OAUTH_SESSION_COOKIE,+ validateOAuthSession,+ OAUTH_CSRF_COOKIE,+ validateOAuthCsrf,+} from '~/oauth/csrf';+import { MockKeyv } from './helpers/oauthTestServer';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++const CSRF_COOKIE_PATH = '/api/mcp';++function makeReq(cookies: Record<string, string> = {}): Request {+ return { cookies } as unknown as Request;+}++function makeRes(): Response {+ const res = {+ clearCookie: jest.fn(),+ } as unknown as Response;+ return res;+}++/**+ * Replicate the callback route's three-tier validation logic.+ * Returns which mechanism (if any) authorized the request.+ */+async function validateCallback(+ req: Request,+ res: Response,+ flowId: string,+ flowManager: FlowStateManager,+): Promise<'csrf' | 'session' | 'pendingFlow' | false> {+ const flowUserId = flowId.split(':')[0];++ const hasCsrf = validateOAuthCsrf(req, res, flowId, CSRF_COOKIE_PATH);+ if (hasCsrf) {+ return 'csrf';+ }++ const hasSession = validateOAuthSession(req, flowUserId);+ if (hasSession) {+ return 'session';+ }++ const pendingFlow = await flowManager.getFlowState(flowId, 'mcp_oauth');+ const pendingAge = pendingFlow?.createdAt ? Date.now() - pendingFlow.createdAt : Infinity;+ if (pendingFlow?.status === 'PENDING' && pendingAge < PENDING_STALE_MS) {+ return 'pendingFlow';+ }++ return false;+}++describe('OAuth Callback CSRF Fallback', () => {+ let flowManager: FlowStateManager;++ beforeEach(() => {+ process.env.JWT_SECRET = 'test-secret-for-csrf';+ const store = new MockKeyv();+ flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 300000, ci: true });+ });++ afterEach(() => {+ delete process.env.JWT_SECRET;+ jest.clearAllMocks();+ });++ describe('CSRF cookie validation (mechanism 1)', () => {+ it('should accept valid CSRF cookie', async () => {+ const flowId = 'user1:test-server';+ const csrfToken = generateOAuthCsrfToken(flowId, 'test-secret-for-csrf');+ const req = makeReq({ [OAUTH_CSRF_COOKIE]: csrfToken });+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('csrf');+ });++ it('should reject invalid CSRF cookie', async () => {+ const flowId = 'user1:test-server';+ const req = makeReq({ [OAUTH_CSRF_COOKIE]: 'wrong-token-value' });+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe(false);+ });+ });++ describe('Session cookie validation (mechanism 2)', () => {+ it('should accept valid session cookie when CSRF is absent', async () => {+ const flowId = 'user1:test-server';+ const sessionToken = generateOAuthCsrfToken('user1', 'test-secret-for-csrf');+ const req = makeReq({ [OAUTH_SESSION_COOKIE]: sessionToken });+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('session');+ });+ });++ describe('PENDING flow fallback (mechanism 3)', () => {+ it('should accept when a fresh PENDING flow exists and no cookies are present', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });++ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('pendingFlow');+ });++ it('should reject when no PENDING flow, no CSRF cookie, and no session cookie', async () => {+ const flowId = 'user1:test-server';+ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe(false);+ });++ it('should reject when only a COMPLETED flow exists (not PENDING)', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });+ await flowManager.completeFlow(flowId, 'mcp_oauth', { access_token: 'tok' } as never);++ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe(false);+ });++ it('should reject when only a FAILED flow exists', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', {});+ await flowManager.failFlow(flowId, 'mcp_oauth', 'some error');++ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe(false);+ });++ it('should reject when PENDING flow is stale (older than PENDING_STALE_MS)', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });++ // Artificially age the flow past the staleness threshold+ const store = (flowManager as unknown as { keyv: { get: (k: string) => Promise<unknown> } })+ .keyv;+ const flowState = (await store.get(`mcp_oauth:${flowId}`)) as { createdAt: number };+ flowState.createdAt = Date.now() - PENDING_STALE_MS - 1000;++ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe(false);+ });++ it('should accept PENDING flow that is just under the staleness threshold', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });++ // Flow was just created, well under threshold+ const req = makeReq();+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('pendingFlow');+ });+ });++ describe('Priority ordering', () => {+ it('should prefer CSRF cookie over PENDING flow', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });++ const csrfToken = generateOAuthCsrfToken(flowId, 'test-secret-for-csrf');+ const req = makeReq({ [OAUTH_CSRF_COOKIE]: csrfToken });+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('csrf');+ });++ it('should prefer session cookie over PENDING flow when CSRF is absent', async () => {+ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', { serverName: 'test-server' });++ const sessionToken = generateOAuthCsrfToken('user1', 'test-secret-for-csrf');+ const req = makeReq({ [OAUTH_SESSION_COOKIE]: sessionToken });+ const res = makeRes();++ const result = await validateCallback(req, res, flowId, flowManager);+ expect(result).toBe('session');+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPOAuthConnectionEvents.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthConnectionEvents.test.tsnew file mode 100644index 0000000000..4e168d00f3--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthConnectionEvents.test.ts@@ -0,0 +1,268 @@+/**+ * Tests for MCPConnection OAuth event cycle against a real OAuth-gated MCP server.+ *+ * Verifies: oauthRequired emission on 401, oauthHandled reconnection,+ * oauthFailed rejection, timeout behavior, and token expiry mid-session.+ */++import { MCPConnection } from '~/mcp/connection';+import { createOAuthMCPServer } from './helpers/oauthTestServer';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import type { MCPOAuthTokens } from '~/mcp/oauth';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++jest.mock('~/auth', () => ({+ createSSRFSafeUndiciConnect: jest.fn(() => undefined),+ resolveHostnameSSRF: jest.fn(async () => false),+}));++jest.mock('~/mcp/mcpConfig', () => ({+ mcpConfig: { CONNECTION_CHECK_TTL: 0, USER_CONNECTION_IDLE_TIMEOUT: 30 * 60 * 1000 },+}));++async function safeDisconnect(conn: MCPConnection | null): Promise<void> {+ if (!conn) {+ return;+ }+ try {+ await conn.disconnect();+ } catch {+ // Ignore disconnect errors during cleanup+ }+}++async function exchangeCodeForToken(serverUrl: string): Promise<string> {+ const authRes = await fetch(`${serverUrl}authorize?redirect_uri=http://localhost&state=test`, {+ redirect: 'manual',+ });+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code') ?? '';++ const tokenRes = await fetch(`${serverUrl}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const data = (await tokenRes.json()) as { access_token: string };+ return data.access_token;+}++describe('MCPConnection OAuth Events — Real Server', () => {+ let server: OAuthTestServer;+ let connection: MCPConnection | null = null;++ beforeEach(() => {+ MCPConnection.clearCooldown('test-server');+ });++ afterEach(async () => {+ await safeDisconnect(connection);+ connection = null;+ if (server) {+ await server.close();+ }+ jest.clearAllMocks();+ });++ describe('oauthRequired event', () => {+ beforeEach(async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ it('should emit oauthRequired when connecting without a token', async () => {+ connection = new MCPConnection({+ serverName: 'test-server',+ serverConfig: { type: 'streamable-http', url: server.url },+ userId: 'user-1',+ });++ const oauthRequiredPromise = new Promise<{+ serverName: string;+ error: Error;+ serverUrl?: string;+ userId?: string;+ }>((resolve) => {+ connection!.on('oauthRequired', (data) => {+ resolve(+ data as {+ serverName: string;+ error: Error;+ serverUrl?: string;+ userId?: string;+ },+ );+ });+ });++ // Connection will fail with 401, emitting oauthRequired+ const connectPromise = connection.connect().catch(() => {+ // Expected to fail since no one handles oauthRequired+ });++ let raceTimer: NodeJS.Timeout | undefined;+ const eventData = await Promise.race([+ oauthRequiredPromise,+ new Promise<never>((_, reject) => {+ raceTimer = setTimeout(+ () => reject(new Error('Timed out waiting for oauthRequired')),+ 10000,+ );+ }),+ ]).finally(() => clearTimeout(raceTimer));++ expect(eventData.serverName).toBe('test-server');+ expect(eventData.error).toBeDefined();++ // Emit oauthFailed to unblock connect()+ connection.emit('oauthFailed', new Error('test cleanup'));+ await connectPromise.catch(() => undefined);+ });++ it('should not emit oauthRequired when connecting with a valid token', async () => {+ const accessToken = await exchangeCodeForToken(server.url);++ connection = new MCPConnection({+ serverName: 'test-server',+ serverConfig: { type: 'streamable-http', url: server.url },+ userId: 'user-1',+ oauthTokens: {+ access_token: accessToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens,+ });++ let oauthFired = false;+ connection.on('oauthRequired', () => {+ oauthFired = true;+ });++ await connection.connect();+ expect(await connection.isConnected()).toBe(true);+ expect(oauthFired).toBe(false);+ });+ });++ describe('oauthHandled reconnection', () => {+ beforeEach(async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ it('should succeed on retry after oauthHandled provides valid tokens', async () => {+ connection = new MCPConnection({+ serverName: 'test-server',+ serverConfig: {+ type: 'streamable-http',+ url: server.url,+ initTimeout: 15000,+ },+ userId: 'user-1',+ });++ // First connect fails with 401 → oauthRequired fires+ let oauthFired = false;+ connection.on('oauthRequired', () => {+ oauthFired = true;+ connection!.emit('oauthFailed', new Error('Will retry with tokens'));+ });++ // First attempt fails as expected+ await expect(connection.connect()).rejects.toThrow();+ expect(oauthFired).toBe(true);++ // Now set valid tokens and reconnect+ const accessToken = await exchangeCodeForToken(server.url);+ connection.setOAuthTokens({+ access_token: accessToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens);++ await connection.connect();+ expect(await connection.isConnected()).toBe(true);+ });+ });++ describe('oauthFailed rejection', () => {+ beforeEach(async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ it('should reject connect() when oauthFailed is emitted', async () => {+ connection = new MCPConnection({+ serverName: 'test-server',+ serverConfig: {+ type: 'streamable-http',+ url: server.url,+ initTimeout: 15000,+ },+ userId: 'user-1',+ });++ connection.on('oauthRequired', () => {+ connection!.emit('oauthFailed', new Error('User denied OAuth'));+ });++ await expect(connection.connect()).rejects.toThrow();+ });+ });++ describe('Token expiry during session', () => {+ it('should detect expired token on reconnect and emit oauthRequired', async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 1000 });++ const accessToken = await exchangeCodeForToken(server.url);++ connection = new MCPConnection({+ serverName: 'test-server',+ serverConfig: {+ type: 'streamable-http',+ url: server.url,+ initTimeout: 15000,+ },+ userId: 'user-1',+ oauthTokens: {+ access_token: accessToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens,+ });++ // Initial connect should succeed+ await connection.connect();+ expect(await connection.isConnected()).toBe(true);+ await connection.disconnect();++ // Wait for token to expire+ await new Promise((r) => setTimeout(r, 1200));++ // Reconnect should trigger oauthRequired since token is expired on the server+ let oauthFired = false;+ connection.on('oauthRequired', () => {+ oauthFired = true;+ connection!.emit('oauthFailed', new Error('Will retry with fresh token'));+ });++ // First reconnect fails with 401 → oauthRequired+ await expect(connection.connect()).rejects.toThrow();+ expect(oauthFired).toBe(true);++ // Get fresh token and reconnect+ const newToken = await exchangeCodeForToken(server.url);+ connection.setOAuthTokens({+ access_token: newToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens);++ await connection.connect();+ expect(await connection.isConnected()).toBe(true);+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPOAuthFlow.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthFlow.test.tsnew file mode 100644index 0000000000..8437177c86--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthFlow.test.ts@@ -0,0 +1,538 @@+/**+ * OAuth flow tests against a real HTTP server.+ *+ * Tests MCPOAuthHandler.refreshOAuthTokens and MCPTokenStorage lifecycle+ * using a real test OAuth server (not mocked SDK functions).+ */++import { createHash } from 'crypto';+import { Keyv } from 'keyv';+import { MCPTokenStorage, MCPOAuthHandler } from '~/mcp/oauth';+import { FlowStateManager } from '~/flow/manager';+import { createOAuthMCPServer, MockKeyv, InMemoryTokenStore } from './helpers/oauthTestServer';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import type { MCPOAuthTokens } from '~/mcp/oauth';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++describe('MCP OAuth Flow — Real HTTP Server', () => {+ afterEach(() => {+ jest.clearAllMocks();+ });++ describe('Token refresh with real server', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer({+ tokenTTLMs: 60000,+ issueRefreshTokens: true,+ });+ });++ afterEach(async () => {+ await server.close();+ });++ it('should refresh tokens with stored client info via real /token endpoint', async () => {+ // First get initial tokens+ const code = await server.getAuthCode();+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ refresh_token: string;+ };++ expect(initial.refresh_token).toBeDefined();++ // Register a client so we have clientInfo+ const regRes = await fetch(`${server.url}register`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ redirect_uris: ['http://localhost/callback'] }),+ });+ const clientInfo = (await regRes.json()) as {+ client_id: string;+ client_secret: string;+ };++ // Refresh tokens using the real endpoint+ const refreshed = await MCPOAuthHandler.refreshOAuthTokens(+ initial.refresh_token,+ {+ serverName: 'test-server',+ serverUrl: server.url,+ clientInfo: {+ ...clientInfo,+ redirect_uris: ['http://localhost/callback'],+ },+ },+ {},+ {+ token_url: `${server.url}token`,+ client_id: clientInfo.client_id,+ client_secret: clientInfo.client_secret,+ token_exchange_method: 'DefaultPost',+ },+ );++ expect(refreshed.access_token).toBeDefined();+ expect(refreshed.access_token).not.toBe(initial.access_token);+ expect(refreshed.token_type).toBe('Bearer');+ expect(refreshed.obtained_at).toBeDefined();+ });++ it('should get new refresh token when server rotates', async () => {+ const rotatingServer = await createOAuthMCPServer({+ tokenTTLMs: 60000,+ issueRefreshTokens: true,+ rotateRefreshTokens: true,+ });++ try {+ const code = await rotatingServer.getAuthCode();+ const tokenRes = await fetch(`${rotatingServer.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ refresh_token: string;+ };++ const refreshed = await MCPOAuthHandler.refreshOAuthTokens(+ initial.refresh_token,+ {+ serverName: 'test-server',+ serverUrl: rotatingServer.url,+ },+ {},+ {+ token_url: `${rotatingServer.url}token`,+ client_id: 'anon',+ token_exchange_method: 'DefaultPost',+ },+ );++ expect(refreshed.access_token).not.toBe(initial.access_token);+ expect(refreshed.refresh_token).toBeDefined();+ expect(refreshed.refresh_token).not.toBe(initial.refresh_token);+ } finally {+ await rotatingServer.close();+ }+ });++ it('should fail refresh with invalid refresh token', async () => {+ await expect(+ MCPOAuthHandler.refreshOAuthTokens(+ 'invalid-refresh-token',+ {+ serverName: 'test-server',+ serverUrl: server.url,+ },+ {},+ {+ token_url: `${server.url}token`,+ client_id: 'anon',+ token_exchange_method: 'DefaultPost',+ },+ ),+ ).rejects.toThrow();+ });+ });++ describe('OAuth server metadata discovery', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer({ issueRefreshTokens: true });+ });++ afterEach(async () => {+ await server.close();+ });++ it('should expose /.well-known/oauth-authorization-server', async () => {+ const res = await fetch(`${server.url}.well-known/oauth-authorization-server`);+ expect(res.status).toBe(200);++ const metadata = (await res.json()) as {+ authorization_endpoint: string;+ token_endpoint: string;+ registration_endpoint: string;+ grant_types_supported: string[];+ };++ expect(metadata.authorization_endpoint).toContain('/authorize');+ expect(metadata.token_endpoint).toContain('/token');+ expect(metadata.registration_endpoint).toContain('/register');+ expect(metadata.grant_types_supported).toContain('authorization_code');+ expect(metadata.grant_types_supported).toContain('refresh_token');+ });++ it('should not advertise refresh_token grant when disabled', async () => {+ const noRefreshServer = await createOAuthMCPServer({+ issueRefreshTokens: false,+ });+ try {+ const res = await fetch(`${noRefreshServer.url}.well-known/oauth-authorization-server`);+ const metadata = (await res.json()) as { grant_types_supported: string[] };+ expect(metadata.grant_types_supported).not.toContain('refresh_token');+ } finally {+ await noRefreshServer.close();+ }+ });+ });++ describe('Dynamic client registration', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer();+ });++ afterEach(async () => {+ await server.close();+ });++ it('should register a client via /register endpoint', async () => {+ const res = await fetch(`${server.url}register`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({+ redirect_uris: ['http://localhost/callback'],+ }),+ });++ expect(res.status).toBe(200);+ const client = (await res.json()) as {+ client_id: string;+ client_secret: string;+ redirect_uris: string[];+ };++ expect(client.client_id).toBeDefined();+ expect(client.client_secret).toBeDefined();+ expect(client.redirect_uris).toEqual(['http://localhost/callback']);+ expect(server.registeredClients.has(client.client_id)).toBe(true);+ });+ });++ describe('End-to-End: store, retrieve, expire, refresh cycle', () => {+ it('should perform full token lifecycle with real server', async () => {+ const server = await createOAuthMCPServer({+ tokenTTLMs: 1000,+ issueRefreshTokens: true,+ });+ const tokenStore = new InMemoryTokenStore();++ try {+ // 1. Get initial tokens via auth code exchange+ const code = await server.getAuthCode();+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token: string;+ };++ // 2. Store tokens+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'test-srv',+ tokens: initial,+ createToken: tokenStore.createToken,+ });++ // 3. Retrieve — should succeed+ const valid = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ });+ expect(valid).not.toBeNull();+ expect(valid!.access_token).toBe(initial.access_token);+ expect(valid!.refresh_token).toBe(initial.refresh_token);++ // 4. Wait for expiry+ await new Promise((r) => setTimeout(r, 1200));++ // 5. Retrieve again — should trigger refresh via callback+ const refreshCallback = async (refreshToken: string): Promise<MCPOAuthTokens> => {+ const refreshRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/x-www-form-urlencoded',+ },+ body: `grant_type=refresh_token&refresh_token=${refreshToken}`,+ });++ if (!refreshRes.ok) {+ throw new Error(`Refresh failed: ${refreshRes.status}`);+ }++ const data = (await refreshRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token?: string;+ };++ return {+ ...data,+ obtained_at: Date.now(),+ expires_at: Date.now() + data.expires_in * 1000,+ };+ };++ const refreshed = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });++ expect(refreshed).not.toBeNull();+ expect(refreshed!.access_token).not.toBe(initial.access_token);++ // 6. Verify the refreshed token works against the server+ const mcpRes = await fetch(server.url, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Authorization: `Bearer ${refreshed!.access_token}`,+ },+ body: JSON.stringify({+ jsonrpc: '2.0',+ method: 'initialize',+ id: 1,+ params: {+ protocolVersion: '2025-03-26',+ capabilities: {},+ clientInfo: { name: 'test', version: '0.0.1' },+ },+ }),+ });+ expect(mcpRes.status).toBe(200);+ } finally {+ await server.close();+ }+ });+ });++ describe('completeOAuthFlow via FlowStateManager', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer({ issueRefreshTokens: true });+ });++ afterEach(async () => {+ await server.close();+ });++ it('should exchange auth code and complete flow in FlowStateManager', async () => {+ const store = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(store as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });++ const flowId = 'test-user:test-server';+ const code = await server.getAuthCode();++ // Initialize the flow with metadata the handler needs+ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverUrl: server.url,+ clientInfo: {+ client_id: 'test-client',+ redirect_uris: ['http://localhost/callback'],+ },+ codeVerifier: 'test-verifier',+ metadata: {+ token_endpoint: `${server.url}token`,+ token_endpoint_auth_methods_supported: ['client_secret_post'],+ },+ });++ // The SDK's exchangeAuthorization wants full OAuth metadata,+ // so we'll test the token exchange directly instead of going through+ // completeOAuthFlow (which requires full SDK-compatible metadata)+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ const tokens = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token?: string;+ };++ const mcpTokens: MCPOAuthTokens = {+ ...tokens,+ obtained_at: Date.now(),+ expires_at: Date.now() + tokens.expires_in * 1000,+ };++ // Complete the flow+ const completed = await flowManager.completeFlow(flowId, 'mcp_oauth', mcpTokens);+ expect(completed).toBe(true);++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(state?.status).toBe('COMPLETED');+ expect(state?.result?.access_token).toBe(tokens.access_token);+ });++ it('should fail flow when authorization code is invalid', async () => {+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: 'grant_type=authorization_code&code=invalid-code',+ });++ expect(tokenRes.status).toBe(400);+ const body = (await tokenRes.json()) as { error: string };+ expect(body.error).toBe('invalid_grant');+ });++ it('should fail when authorization code is reused', async () => {+ const code = await server.getAuthCode();++ // First exchange succeeds+ const firstRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ expect(firstRes.status).toBe(200);++ // Second exchange fails+ const secondRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ expect(secondRes.status).toBe(400);+ const body = (await secondRes.json()) as { error: string };+ expect(body.error).toBe('invalid_grant');+ });+ });++ describe('PKCE verification', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ afterEach(async () => {+ await server.close();+ });++ function generatePKCE(): { verifier: string; challenge: string } {+ const verifier = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';+ const challenge = createHash('sha256').update(verifier).digest('base64url');+ return { verifier, challenge };+ }++ it('should accept valid code_verifier matching code_challenge', async () => {+ const { verifier, challenge } = generatePKCE();++ const authRes = await fetch(+ `${server.url}authorize?redirect_uri=http://localhost&state=test&code_challenge=${challenge}&code_challenge_method=S256`,+ { redirect: 'manual' },+ );+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code') ?? '';++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}&code_verifier=${verifier}`,+ });++ expect(tokenRes.status).toBe(200);+ const data = (await tokenRes.json()) as { access_token: string };+ expect(data.access_token).toBeDefined();+ });++ it('should reject wrong code_verifier', async () => {+ const { challenge } = generatePKCE();++ const authRes = await fetch(+ `${server.url}authorize?redirect_uri=http://localhost&state=test&code_challenge=${challenge}&code_challenge_method=S256`,+ { redirect: 'manual' },+ );+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code') ?? '';++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}&code_verifier=wrong-verifier`,+ });++ expect(tokenRes.status).toBe(400);+ const body = (await tokenRes.json()) as { error: string };+ expect(body.error).toBe('invalid_grant');+ });++ it('should reject missing code_verifier when code_challenge was provided', async () => {+ const { challenge } = generatePKCE();++ const authRes = await fetch(+ `${server.url}authorize?redirect_uri=http://localhost&state=test&code_challenge=${challenge}&code_challenge_method=S256`,+ { redirect: 'manual' },+ );+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code') ?? '';++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ expect(tokenRes.status).toBe(400);+ const body = (await tokenRes.json()) as { error: string };+ expect(body.error).toBe('invalid_grant');+ });++ it('should still accept codes without PKCE when no code_challenge was provided', async () => {+ const code = await server.getAuthCode();++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ expect(tokenRes.status).toBe(200);+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPOAuthRaceCondition.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthRaceCondition.test.tsnew file mode 100644index 0000000000..85febb3ece--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthRaceCondition.test.ts@@ -0,0 +1,516 @@+/**+ * Tests for MCP OAuth race condition fixes:+ *+ * 1. Connection mutex coalesces concurrent getUserConnection() calls+ * 2. PENDING OAuth flows are reused, not deleted+ * 3. No-refresh-token expiry throws ReauthenticationRequiredError+ * 4. completeFlow recovers when flow state was deleted by a race+ * 5. monitorFlow retries once when flow state disappears mid-poll+ */++import { Keyv } from 'keyv';+import { logger } from '@librechat/data-schemas';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import type { MCPOAuthTokens } from '~/mcp/oauth';+import { MCPTokenStorage, MCPOAuthHandler, ReauthenticationRequiredError } from '~/mcp/oauth';+import { MockKeyv, createOAuthMCPServer } from './helpers/oauthTestServer';+import { FlowStateManager } from '~/flow/manager';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++jest.mock('~/auth', () => ({+ createSSRFSafeUndiciConnect: jest.fn(() => undefined),+ resolveHostnameSSRF: jest.fn(async () => false),+}));++jest.mock('~/mcp/mcpConfig', () => ({+ mcpConfig: { CONNECTION_CHECK_TTL: 0, USER_CONNECTION_IDLE_TIMEOUT: 30 * 60 * 1000 },+}));++const mockLogger = logger as jest.Mocked<typeof logger>;++describe('MCP OAuth Race Condition Fixes', () => {+ afterEach(() => {+ jest.clearAllMocks();+ });++ describe('Fix 1: Connection mutex coalesces concurrent attempts', () => {+ it('should return the same pending promise for concurrent getUserConnection calls', async () => {+ const { UserConnectionManager } = await import('~/mcp/UserConnectionManager');++ class TestManager extends UserConnectionManager {+ public createCallCount = 0;++ getPendingConnections() {+ return this.pendingConnections;+ }+ }++ const manager = new TestManager();++ const mockConnection = {+ isConnected: jest.fn().mockResolvedValue(true),+ disconnect: jest.fn().mockResolvedValue(undefined),+ isStale: jest.fn().mockReturnValue(false),+ };++ const mockAppConnections = { has: jest.fn().mockResolvedValue(false) };+ manager.appConnections = mockAppConnections as never;++ const mockConfig = {+ type: 'streamable-http',+ url: 'http://localhost:9999/',+ updatedAt: undefined,+ dbId: undefined,+ };++ jest+ .spyOn(+ // eslint-disable-next-line @typescript-eslint/no-require-imports+ require('~/mcp/registry/MCPServersRegistry').MCPServersRegistry,+ 'getInstance',+ )+ .mockReturnValue({+ getServerConfig: jest.fn().mockResolvedValue(mockConfig),+ shouldEnableSSRFProtection: jest.fn().mockReturnValue(false),+ });++ const { MCPConnectionFactory } = await import('~/mcp/MCPConnectionFactory');+ const createSpy = jest.spyOn(MCPConnectionFactory, 'create').mockImplementation(async () => {+ manager.createCallCount++;+ await new Promise((r) => setTimeout(r, 100));+ return mockConnection as never;+ });++ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });+ const user = { id: 'user-1' };+ const opts = {+ serverName: 'test-server',+ user: user as never,+ flowManager: flowManager as never,+ };++ const [conn1, conn2, conn3] = await Promise.all([+ manager.getUserConnection(opts),+ manager.getUserConnection(opts),+ manager.getUserConnection(opts),+ ]);++ expect(conn1).toBe(conn2);+ expect(conn2).toBe(conn3);+ expect(createSpy).toHaveBeenCalledTimes(1);+ expect(manager.createCallCount).toBe(1);++ createSpy.mockRestore();+ });++ it('should not coalesce when forceNew is true', async () => {+ const { UserConnectionManager } = await import('~/mcp/UserConnectionManager');++ class TestManager extends UserConnectionManager {}++ const manager = new TestManager();++ let callCount = 0;+ const makeConnection = () => ({+ isConnected: jest.fn().mockResolvedValue(true),+ disconnect: jest.fn().mockResolvedValue(undefined),+ isStale: jest.fn().mockReturnValue(false),+ });++ const mockAppConnections = { has: jest.fn().mockResolvedValue(false) };+ manager.appConnections = mockAppConnections as never;++ const mockConfig = {+ type: 'streamable-http',+ url: 'http://localhost:9999/',+ updatedAt: undefined,+ dbId: undefined,+ };++ jest+ .spyOn(+ // eslint-disable-next-line @typescript-eslint/no-require-imports+ require('~/mcp/registry/MCPServersRegistry').MCPServersRegistry,+ 'getInstance',+ )+ .mockReturnValue({+ getServerConfig: jest.fn().mockResolvedValue(mockConfig),+ shouldEnableSSRFProtection: jest.fn().mockReturnValue(false),+ });++ const { MCPConnectionFactory } = await import('~/mcp/MCPConnectionFactory');+ jest.spyOn(MCPConnectionFactory, 'create').mockImplementation(async () => {+ callCount++;+ await new Promise((r) => setTimeout(r, 50));+ return makeConnection() as never;+ });++ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });+ const user = { id: 'user-2' };++ const [conn1, conn2] = await Promise.all([+ manager.getUserConnection({+ serverName: 'test-server',+ forceNew: true,+ user: user as never,+ flowManager: flowManager as never,+ }),+ manager.getUserConnection({+ serverName: 'test-server',+ forceNew: true,+ user: user as never,+ flowManager: flowManager as never,+ }),+ ]);++ expect(callCount).toBe(2);+ expect(conn1).not.toBe(conn2);+ });+ });++ describe('Fix 2: PENDING flow is reused, not deleted', () => {+ it('should join an existing PENDING flow via createFlow instead of deleting it', async () => {+ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });++ const flowId = 'test-flow-pending';++ await flowManager.initFlow(flowId, 'mcp_oauth', {+ clientInfo: { client_id: 'test-client' },+ });++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(state?.status).toBe('PENDING');++ const deleteSpy = jest.spyOn(flowManager, 'deleteFlow');++ const monitorPromise = flowManager.createFlow(flowId, 'mcp_oauth', {});++ await new Promise((r) => setTimeout(r, 500));++ await flowManager.completeFlow(flowId, 'mcp_oauth', {+ access_token: 'test-token',+ token_type: 'Bearer',+ } as never);++ const result = await monitorPromise;+ expect(result).toEqual(+ expect.objectContaining({ access_token: 'test-token', token_type: 'Bearer' }),+ );+ expect(deleteSpy).not.toHaveBeenCalled();++ deleteSpy.mockRestore();+ });++ it('should delete and recreate FAILED flows', async () => {+ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });++ const flowId = 'test-flow-failed';+ await flowManager.initFlow(flowId, 'mcp_oauth', {});+ await flowManager.failFlow(flowId, 'mcp_oauth', 'previous error');++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(state?.status).toBe('FAILED');++ await flowManager.deleteFlow(flowId, 'mcp_oauth');++ const afterDelete = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(afterDelete).toBeUndefined();+ });+ });++ describe('Fix 3: completeFlow handles deleted state gracefully', () => {+ it('should return false when state was deleted by race', async () => {+ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });++ const flowId = 'race-deleted-flow';++ await flowManager.initFlow(flowId, 'mcp_oauth', {});+ await flowManager.deleteFlow(flowId, 'mcp_oauth');++ const stateBeforeComplete = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(stateBeforeComplete).toBeUndefined();++ const result = await flowManager.completeFlow(flowId, 'mcp_oauth', {+ access_token: 'recovered-token',+ token_type: 'Bearer',+ } as never);++ expect(result).toBe(false);++ const stateAfterComplete = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(stateAfterComplete).toBeUndefined();++ expect(mockLogger.warn).toHaveBeenCalledWith(+ expect.stringContaining('cannot recover metadata'),+ expect.any(Object),+ );+ });++ it('should reject monitorFlow when state is deleted and not recoverable', async () => {+ const store = new MockKeyv();+ const flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });++ const flowId = 'monitor-retry-flow';++ await flowManager.initFlow(flowId, 'mcp_oauth', {});++ const monitorPromise = flowManager.createFlow(flowId, 'mcp_oauth', {});++ await new Promise((r) => setTimeout(r, 500));++ await flowManager.deleteFlow(flowId, 'mcp_oauth');++ await expect(monitorPromise).rejects.toThrow('Flow state not found');+ });+ });++ describe('State mapping cleanup on flow replacement', () => {+ it('should delete old state mapping when a flow is replaced', async () => {+ const store = new MockKeyv();+ const flowManager = new FlowStateManager<MCPOAuthTokens | null>(store as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });++ const flowId = 'user1:test-server';+ const oldState = 'old-random-state-abc123';+ const newState = 'new-random-state-xyz789';++ // Simulate initial flow with state mapping+ await flowManager.initFlow(flowId, 'mcp_oauth', { state: oldState });+ await MCPOAuthHandler.storeStateMapping(oldState, flowId, flowManager);++ // Old state should resolve+ const resolvedBefore = await MCPOAuthHandler.resolveStateToFlowId(oldState, flowManager);+ expect(resolvedBefore).toBe(flowId);++ // Replace the flow: delete old, create new, clean up old state mapping+ await flowManager.deleteFlow(flowId, 'mcp_oauth');+ await MCPOAuthHandler.deleteStateMapping(oldState, flowManager);+ await flowManager.initFlow(flowId, 'mcp_oauth', { state: newState });+ await MCPOAuthHandler.storeStateMapping(newState, flowId, flowManager);++ // Old state should no longer resolve+ const resolvedOld = await MCPOAuthHandler.resolveStateToFlowId(oldState, flowManager);+ expect(resolvedOld).toBeNull();++ // New state should resolve+ const resolvedNew = await MCPOAuthHandler.resolveStateToFlowId(newState, flowManager);+ expect(resolvedNew).toBe(flowId);+ });+ });++ describe('Fix 4: ReauthenticationRequiredError for no-refresh-token', () => {+ it('should throw ReauthenticationRequiredError when access token expired and no refresh token', async () => {+ const expiredDate = new Date(Date.now() - 60000);++ const findToken = jest.fn().mockImplementation(async (filter: { type?: string }) => {+ if (filter.type === 'mcp_oauth') {+ return {+ token: 'enc:expired-access-token',+ expiresAt: expiredDate,+ createdAt: new Date(Date.now() - 120000),+ };+ }+ if (filter.type === 'mcp_oauth_refresh') {+ return null;+ }+ return null;+ });++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'user-1',+ serverName: 'test-server',+ findToken,+ }),+ ).rejects.toThrow(ReauthenticationRequiredError);++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'user-1',+ serverName: 'test-server',+ findToken,+ }),+ ).rejects.toThrow('Re-authentication required');+ });++ it('should throw ReauthenticationRequiredError when access token is missing and no refresh token', async () => {+ const findToken = jest.fn().mockResolvedValue(null);++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'user-1',+ serverName: 'test-server',+ findToken,+ }),+ ).rejects.toThrow(ReauthenticationRequiredError);+ });++ it('should not throw when access token is valid', async () => {+ const futureDate = new Date(Date.now() + 3600000);++ const findToken = jest.fn().mockImplementation(async (filter: { type?: string }) => {+ if (filter.type === 'mcp_oauth') {+ return {+ token: 'enc:valid-access-token',+ expiresAt: futureDate,+ createdAt: new Date(),+ };+ }+ if (filter.type === 'mcp_oauth_refresh') {+ return null;+ }+ return null;+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'user-1',+ serverName: 'test-server',+ findToken,+ });++ expect(result).not.toBeNull();+ expect(result?.access_token).toBe('valid-access-token');+ });+ });++ describe('E2E: OAuth-gated MCP server with no refresh tokens', () => {+ let server: OAuthTestServer;++ beforeEach(async () => {+ server = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ afterEach(async () => {+ await server.close();+ });++ it('should start OAuth-gated MCP server that validates Bearer tokens', async () => {+ const res = await fetch(server.url, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: JSON.stringify({ jsonrpc: '2.0', method: 'initialize', id: 1 }),+ });++ expect(res.status).toBe(401);+ const body = (await res.json()) as { error: string };+ expect(body.error).toBe('invalid_token');+ });++ it('should issue tokens via authorization code exchange with no refresh token', async () => {+ const authRes = await fetch(`${server.url}authorize?redirect_uri=http://localhost&state=s1`, {+ redirect: 'manual',+ });++ expect(authRes.status).toBe(302);+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code');+ expect(code).toBeTruthy();++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ expect(tokenRes.status).toBe(200);+ const tokenBody = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ refresh_token?: string;+ };+ expect(tokenBody.access_token).toBeTruthy();+ expect(tokenBody.token_type).toBe('Bearer');+ expect(tokenBody.refresh_token).toBeUndefined();+ });++ it('should allow MCP requests with valid Bearer token', async () => {+ const authRes = await fetch(`${server.url}authorize?redirect_uri=http://localhost&state=s1`, {+ redirect: 'manual',+ });+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code');++ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ const { access_token } = (await tokenRes.json()) as { access_token: string };++ const mcpRes = await fetch(server.url, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Authorization: `Bearer ${access_token}`,+ },+ body: JSON.stringify({+ jsonrpc: '2.0',+ method: 'initialize',+ id: 1,+ params: {+ protocolVersion: '2025-03-26',+ capabilities: {},+ clientInfo: { name: 'test', version: '0.0.1' },+ },+ }),+ });++ expect(mcpRes.status).toBe(200);+ });++ it('should reject expired tokens with 401', async () => {+ const shortTTLServer = await createOAuthMCPServer({ tokenTTLMs: 500 });++ try {+ const authRes = await fetch(+ `${shortTTLServer.url}authorize?redirect_uri=http://localhost&state=s1`,+ { redirect: 'manual' },+ );+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code');++ const tokenRes = await fetch(`${shortTTLServer.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });++ const { access_token } = (await tokenRes.json()) as { access_token: string };++ await new Promise((r) => setTimeout(r, 600));++ const mcpRes = await fetch(shortTTLServer.url, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Authorization: `Bearer ${access_token}`,+ },+ body: JSON.stringify({ jsonrpc: '2.0', method: 'ping', id: 2 }),+ });++ expect(mcpRes.status).toBe(401);+ } finally {+ await shortTTLServer.close();+ }+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPOAuthTokenExpiry.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthTokenExpiry.test.tsnew file mode 100644index 0000000000..986ac4c8b4--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthTokenExpiry.test.ts@@ -0,0 +1,654 @@+/**+ * Tests for MCP OAuth token expiry → re-authentication scenarios.+ *+ * Reproduces the edge case where:+ * 1. Tokens are stored (access + refresh)+ * 2. Access token expires+ * 3. Refresh attempt fails (server rejects/revokes refresh token)+ * 4. System must fall back to full OAuth re-auth via handleOAuthRequired+ * 5. The CSRF cookie may be absent (chat/SSE flow), so the PENDING flow fallback is needed+ *+ * Also tests the happy path: access token expired but refresh succeeds.+ */++import { Keyv } from 'keyv';+import { logger } from '@librechat/data-schemas';+import { FlowStateManager, PENDING_STALE_MS } from '~/flow/manager';+import { MCPTokenStorage, ReauthenticationRequiredError } from '~/mcp/oauth';+import { MockKeyv, InMemoryTokenStore, createOAuthMCPServer } from './helpers/oauthTestServer';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import type { MCPOAuthTokens } from '~/mcp/oauth';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++describe('MCP OAuth Token Expiry Scenarios', () => {+ afterEach(() => {+ jest.clearAllMocks();+ });++ describe('Access token expired + refresh token available + refresh succeeds', () => {+ let server: OAuthTestServer;+ let tokenStore: InMemoryTokenStore;++ beforeEach(async () => {+ server = await createOAuthMCPServer({+ tokenTTLMs: 500,+ issueRefreshTokens: true,+ });+ tokenStore = new InMemoryTokenStore();+ });++ afterEach(async () => {+ await server.close();+ });++ it('should refresh expired access token via real /token endpoint', async () => {+ // Get initial tokens from real server+ const code = await server.getAuthCode();+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token: string;+ };++ // Store expired access token directly (bypassing storeTokens' expiresIn clamping)+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: `enc:${initial.access_token}`,+ expiresIn: -1,+ });+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:test-srv:refresh',+ token: `enc:${initial.refresh_token}`,+ expiresIn: 86400,+ });++ const refreshCallback = async (refreshToken: string): Promise<MCPOAuthTokens> => {+ const res = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=refresh_token&refresh_token=${refreshToken}`,+ });+ if (!res.ok) {+ throw new Error(`Refresh failed: ${res.status}`);+ }+ const data = (await res.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ };+ return {+ ...data,+ obtained_at: Date.now(),+ expires_at: Date.now() + data.expires_in * 1000,+ };+ };++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });++ expect(result).not.toBeNull();+ expect(result!.access_token).not.toBe(initial.access_token);++ // Verify the refreshed token works against the server+ const mcpRes = await fetch(server.url, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Authorization: `Bearer ${result!.access_token}`,+ },+ body: JSON.stringify({+ jsonrpc: '2.0',+ method: 'initialize',+ id: 1,+ params: {+ protocolVersion: '2025-03-26',+ capabilities: {},+ clientInfo: { name: 'test', version: '0.0.1' },+ },+ }),+ });+ expect(mcpRes.status).toBe(200);+ });+ });++ describe('Access token expired + refresh token rejected by server', () => {+ let tokenStore: InMemoryTokenStore;++ beforeEach(() => {+ tokenStore = new InMemoryTokenStore();+ });++ it('should return null when refresh token is rejected (invalid_grant)', async () => {+ const server = await createOAuthMCPServer({+ tokenTTLMs: 60000,+ issueRefreshTokens: true,+ });++ try {+ const code = await server.getAuthCode();+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token: string;+ };++ // Store expired access token directly+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: `enc:${initial.access_token}`,+ expiresIn: -1,+ });+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:test-srv:refresh',+ token: `enc:${initial.refresh_token}`,+ expiresIn: 86400,+ });++ // Simulate server revoking the refresh token+ server.issuedRefreshTokens.clear();++ const refreshCallback = async (refreshToken: string): Promise<MCPOAuthTokens> => {+ const res = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=refresh_token&refresh_token=${refreshToken}`,+ });+ if (!res.ok) {+ const body = (await res.json()) as { error: string };+ throw new Error(`Token refresh failed: ${body.error}`);+ }+ const data = (await res.json()) as MCPOAuthTokens;+ return data;+ };++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });++ expect(result).toBeNull();+ expect(logger.error).toHaveBeenCalledWith(+ expect.stringContaining('Failed to refresh tokens'),+ expect.any(Error),+ );+ } finally {+ await server.close();+ }+ });++ it('should return null when refresh endpoint returns unauthorized_client', async () => {+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:test-srv:refresh',+ token: 'enc:some-refresh-token',+ expiresIn: 86400,+ });++ const refreshCallback = jest+ .fn()+ .mockRejectedValue(new Error('unauthorized_client: client not authorized for refresh'));++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });++ expect(result).toBeNull();+ expect(logger.info).toHaveBeenCalledWith(+ expect.stringContaining('does not support refresh tokens'),+ );+ });+ });++ describe('Access token expired + NO refresh token → ReauthenticationRequiredError', () => {+ let tokenStore: InMemoryTokenStore;++ beforeEach(() => {+ tokenStore = new InMemoryTokenStore();+ });++ it('should throw ReauthenticationRequiredError when no refresh token stored', async () => {+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: 'enc:expired-token',+ expiresIn: -1,+ });++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ }),+ ).rejects.toThrow(ReauthenticationRequiredError);+ });++ it('should throw ReauthenticationRequiredError with correct reason for expired token', async () => {+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: 'enc:expired-token',+ expiresIn: -1,+ });++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ }),+ ).rejects.toThrow('access token expired');+ });++ it('should throw ReauthenticationRequiredError with correct reason for missing token', async () => {+ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ }),+ ).rejects.toThrow('access token missing');+ });+ });++ describe('PENDING flow fallback for CSRF-less OAuth callbacks', () => {+ it('should allow OAuth completion when PENDING flow exists (simulating chat/SSE path)', async () => {+ const store = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(store as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });++ const flowId = 'user1:test-server';++ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverName: 'test-server',+ userId: 'user1',+ serverUrl: 'https://example.com',+ state: 'test-state',+ authorizationUrl: 'https://example.com/authorize?state=user1:test-server',+ });++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(state?.status).toBe('PENDING');++ const tokens: MCPOAuthTokens = {+ access_token: 'new-access-token',+ token_type: 'Bearer',+ refresh_token: 'new-refresh-token',+ obtained_at: Date.now(),+ expires_at: Date.now() + 3600000,+ };++ const completed = await flowManager.completeFlow(flowId, 'mcp_oauth', tokens);+ expect(completed).toBe(true);++ const completedState = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(completedState?.status).toBe('COMPLETED');+ expect((completedState?.result as MCPOAuthTokens | undefined)?.access_token).toBe(+ 'new-access-token',+ );+ });++ it('should store authorizationUrl in flow metadata for re-issuance', async () => {+ const store = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(store as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });++ const flowId = 'user1:test-server';+ const authUrl = 'https://auth.example.com/authorize?client_id=abc&state=user1:test-server';++ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverName: 'test-server',+ userId: 'user1',+ serverUrl: 'https://example.com',+ state: 'test-state',+ authorizationUrl: authUrl,+ });++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect((state?.metadata as Record<string, unknown>)?.authorizationUrl).toBe(authUrl);+ });+ });++ describe('Full token expiry → refresh failure → re-auth flow', () => {+ let server: OAuthTestServer;+ let tokenStore: InMemoryTokenStore;++ beforeEach(async () => {+ server = await createOAuthMCPServer({+ tokenTTLMs: 60000,+ issueRefreshTokens: true,+ });+ tokenStore = new InMemoryTokenStore();+ });++ afterEach(async () => {+ await server.close();+ });++ it('should go through full cycle: get tokens → expire → refresh fails → re-auth needed', async () => {+ // Step 1: Get initial tokens+ const code = await server.getAuthCode();+ const tokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const initial = (await tokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token: string;+ };++ // Step 2: Store tokens with valid expiry first+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'test-srv',+ tokens: initial,+ createToken: tokenStore.createToken,+ });++ // Step 3: Verify tokens work+ const validResult = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ });+ expect(validResult).not.toBeNull();+ expect(validResult!.access_token).toBe(initial.access_token);++ // Step 4: Simulate token expiry by directly updating the stored token's expiresAt+ await tokenStore.updateToken({ userId: 'u1', identifier: 'mcp:test-srv' }, { expiresIn: -1 });++ // Step 5: Revoke refresh token on server side (simulating server-side revocation)+ server.issuedRefreshTokens.clear();++ // Step 6: Try to get tokens — refresh should fail, return null+ const refreshCallback = async (refreshToken: string): Promise<MCPOAuthTokens> => {+ const res = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=refresh_token&refresh_token=${refreshToken}`,+ });+ if (!res.ok) {+ const body = (await res.json()) as { error: string };+ throw new Error(`Refresh failed: ${body.error}`);+ }+ const data = (await res.json()) as MCPOAuthTokens;+ return data;+ };++ const expiredResult = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });++ // Refresh failed → returns null → triggers OAuth re-auth flow+ expect(expiredResult).toBeNull();++ // Step 7: Simulate the re-auth flow via FlowStateManager+ const flowStore = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(flowStore as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });+ const flowId = 'u1:test-srv';++ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverName: 'test-srv',+ userId: 'u1',+ serverUrl: server.url,+ state: 'test-state',+ authorizationUrl: `${server.url}authorize?state=${flowId}`,+ });++ // Step 8: Get a new auth code and exchange for tokens (simulating user re-auth)+ const newCode = await server.getAuthCode();+ const newTokenRes = await fetch(`${server.url}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${newCode}`,+ });+ const newTokens = (await newTokenRes.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token?: string;+ };++ // Step 9: Complete the flow+ const mcpTokens: MCPOAuthTokens = {+ ...newTokens,+ obtained_at: Date.now(),+ expires_at: Date.now() + newTokens.expires_in * 1000,+ };+ await flowManager.completeFlow(flowId, 'mcp_oauth', mcpTokens);++ // Step 10: Store the new tokens+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'test-srv',+ tokens: mcpTokens,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ findToken: tokenStore.findToken,+ });++ // Step 11: Verify new tokens work+ const newResult = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ });+ expect(newResult).not.toBeNull();+ expect(newResult!.access_token).toBe(newTokens.access_token);++ // Step 12: Verify new token works against server+ const finalMcpRes = await fetch(server.url, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Authorization: `Bearer ${newResult!.access_token}`,+ },+ body: JSON.stringify({+ jsonrpc: '2.0',+ method: 'initialize',+ id: 1,+ params: {+ protocolVersion: '2025-03-26',+ capabilities: {},+ clientInfo: { name: 'test', version: '0.0.1' },+ },+ }),+ });+ expect(finalMcpRes.status).toBe(200);+ });+ });++ describe('Concurrent token expiry with connection mutex', () => {+ it('should handle multiple concurrent getTokens calls when token is expired', async () => {+ const tokenStore = new InMemoryTokenStore();++ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:test-srv',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await tokenStore.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:test-srv:refresh',+ token: 'enc:valid-refresh',+ expiresIn: 86400,+ });++ let refreshCallCount = 0;+ const refreshCallback = jest.fn().mockImplementation(async () => {+ refreshCallCount++;+ await new Promise((r) => setTimeout(r, 100));+ return {+ access_token: `refreshed-token-${refreshCallCount}`,+ token_type: 'Bearer',+ expires_in: 3600,+ obtained_at: Date.now(),+ expires_at: Date.now() + 3600000,+ };+ });++ // Fire 3 concurrent getTokens calls via FlowStateManager (like the connection mutex does)+ const flowStore = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(flowStore as unknown as Keyv, {+ ttl: 30000,+ ci: true,+ });++ const getTokensViaFlow = () =>+ flowManager.createFlowWithHandler('u1:test-srv', 'mcp_get_tokens', async () => {+ return await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'test-srv',+ findToken: tokenStore.findToken,+ createToken: tokenStore.createToken,+ updateToken: tokenStore.updateToken,+ refreshTokens: refreshCallback,+ });+ });++ const [r1, r2, r3] = await Promise.all([+ getTokensViaFlow(),+ getTokensViaFlow(),+ getTokensViaFlow(),+ ]);++ // All should get tokens (either directly or via flow coalescing)+ expect(r1).not.toBeNull();+ expect(r2).not.toBeNull();+ expect(r3).not.toBeNull();++ // The refresh callback should only be called once due to flow coalescing+ expect(refreshCallback).toHaveBeenCalledTimes(1);+ });+ });++ describe('Stale PENDING flow detection', () => {+ it('should treat PENDING flows older than 2 minutes as stale', async () => {+ const flowStore = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(flowStore as unknown as Keyv, {+ ttl: 300000,+ ci: true,+ });++ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverName: 'test-server',+ authorizationUrl: 'https://example.com/auth',+ });++ // Manually age the flow to 3 minutes+ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ if (state) {+ state.createdAt = Date.now() - 3 * 60 * 1000;+ await (flowStore as unknown as { set: (k: string, v: unknown) => Promise<void> }).set(+ `mcp_oauth:${flowId}`,+ state,+ );+ }++ const agedState = await flowManager.getFlowState(flowId, 'mcp_oauth');+ expect(agedState?.status).toBe('PENDING');++ const age = agedState?.createdAt ? Date.now() - agedState.createdAt : 0;+ expect(age).toBeGreaterThan(2 * 60 * 1000);++ // A new flow should be created (the stale one would be deleted + recreated)+ // This verifies our staleness check threshold+ expect(age > PENDING_STALE_MS).toBe(true);+ });++ it('should not treat recent PENDING flows as stale', async () => {+ const flowStore = new MockKeyv<MCPOAuthTokens | null>();+ const flowManager = new FlowStateManager(flowStore as unknown as Keyv, {+ ttl: 300000,+ ci: true,+ });++ const flowId = 'user1:test-server';+ await flowManager.initFlow(flowId, 'mcp_oauth', {+ serverName: 'test-server',+ authorizationUrl: 'https://example.com/auth',+ });++ const state = await flowManager.getFlowState(flowId, 'mcp_oauth');+ const age = state?.createdAt ? Date.now() - state.createdAt : Infinity;++ expect(age < PENDING_STALE_MS).toBe(true);+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.tsnew file mode 100644index 0000000000..3805586453--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts@@ -0,0 +1,544 @@+/**+ * Integration tests for MCPTokenStorage.storeTokens() and MCPTokenStorage.getTokens().+ *+ * Uses InMemoryTokenStore to exercise encrypt/decrypt round-trips, expiry calculation,+ * refresh callback wiring, and ReauthenticationRequiredError paths.+ */++import { MCPTokenStorage, ReauthenticationRequiredError } from '~/mcp/oauth';+import { InMemoryTokenStore } from './helpers/oauthTestServer';++jest.mock('@librechat/data-schemas', () => ({+ logger: {+ info: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ debug: jest.fn(),+ },+ encryptV2: jest.fn(async (val: string) => `enc:${val}`),+ decryptV2: jest.fn(async (val: string) => val.replace(/^enc:/, '')),+}));++describe('MCPTokenStorage', () => {+ let store: InMemoryTokenStore;++ beforeEach(() => {+ store = new InMemoryTokenStore();+ jest.clearAllMocks();+ });++ describe('storeTokens', () => {+ it('should create new access token with expires_in', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'at1', token_type: 'Bearer', expires_in: 3600 },+ createToken: store.createToken,+ });++ const saved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ });+ expect(saved).not.toBeNull();+ expect(saved!.token).toBe('enc:at1');+ const expiresInMs = saved!.expiresAt.getTime() - Date.now();+ expect(expiresInMs).toBeGreaterThan(3500 * 1000);+ expect(expiresInMs).toBeLessThanOrEqual(3600 * 1000);+ });++ it('should create new access token with expires_at (MCPOAuthTokens format)', async () => {+ const expiresAt = Date.now() + 7200 * 1000;+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: {+ access_token: 'at1',+ token_type: 'Bearer',+ expires_at: expiresAt,+ obtained_at: Date.now(),+ },+ createToken: store.createToken,+ });++ const saved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ });+ expect(saved).not.toBeNull();+ const diff = Math.abs(saved!.expiresAt.getTime() - expiresAt);+ expect(diff).toBeLessThan(2000);+ });++ it('should default to 1-year expiry when none provided', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'at1', token_type: 'Bearer' },+ createToken: store.createToken,+ });++ const saved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ });+ const oneYearMs = 365 * 24 * 60 * 60 * 1000;+ const expiresInMs = saved!.expiresAt.getTime() - Date.now();+ expect(expiresInMs).toBeGreaterThan(oneYearMs - 5000);+ });++ it('should update existing access token', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:old-token',+ expiresIn: 3600,+ });++ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'new-token', token_type: 'Bearer', expires_in: 7200 },+ createToken: store.createToken,+ updateToken: store.updateToken,+ findToken: store.findToken,+ });++ const saved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ });+ expect(saved!.token).toBe('enc:new-token');+ });++ it('should store refresh token alongside access token', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: {+ access_token: 'at1',+ token_type: 'Bearer',+ expires_in: 3600,+ refresh_token: 'rt1',+ },+ createToken: store.createToken,+ });++ const refreshSaved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ });+ expect(refreshSaved).not.toBeNull();+ expect(refreshSaved!.token).toBe('enc:rt1');+ });++ it('should skip refresh token when not in response', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'at1', token_type: 'Bearer', expires_in: 3600 },+ createToken: store.createToken,+ });++ const refreshSaved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ });+ expect(refreshSaved).toBeNull();+ });++ it('should store client info when provided', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'at1', token_type: 'Bearer', expires_in: 3600 },+ createToken: store.createToken,+ clientInfo: { client_id: 'cid', client_secret: 'csec', redirect_uris: [] },+ });++ const clientSaved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth_client',+ identifier: 'mcp:srv1:client',+ });+ expect(clientSaved).not.toBeNull();+ expect(clientSaved!.token).toContain('enc:');+ expect(clientSaved!.token).toContain('cid');+ });++ it('should use existingTokens to skip DB lookups', async () => {+ const findSpy = jest.fn();++ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: { access_token: 'at1', token_type: 'Bearer', expires_in: 3600 },+ createToken: store.createToken,+ updateToken: store.updateToken,+ findToken: findSpy,+ existingTokens: {+ accessToken: null,+ refreshToken: null,+ clientInfoToken: null,+ },+ });++ expect(findSpy).not.toHaveBeenCalled();+ });++ it('should handle invalid NaN expiry date', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: {+ access_token: 'at1',+ token_type: 'Bearer',+ expires_at: NaN,+ obtained_at: Date.now(),+ },+ createToken: store.createToken,+ });++ const saved = await store.findToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ });+ expect(saved).not.toBeNull();+ const oneYearMs = 365 * 24 * 60 * 60 * 1000;+ const expiresInMs = saved!.expiresAt.getTime() - Date.now();+ expect(expiresInMs).toBeGreaterThan(oneYearMs - 5000);+ });+ });++ describe('getTokens', () => {+ it('should return valid non-expired tokens', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:valid-token',+ expiresIn: 3600,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ });++ expect(result).not.toBeNull();+ expect(result!.access_token).toBe('valid-token');+ expect(result!.token_type).toBe('Bearer');+ });++ it('should return tokens with refresh token when available', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:at',+ expiresIn: 3600,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ });++ expect(result!.refresh_token).toBe('rt');+ });++ it('should return tokens without refresh token field when none stored', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:at',+ expiresIn: 3600,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ });++ expect(result!.refresh_token).toBeUndefined();+ });++ it('should throw ReauthenticationRequiredError when expired and no refresh', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });++ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ }),+ ).rejects.toThrow(ReauthenticationRequiredError);+ });++ it('should throw ReauthenticationRequiredError when missing and no refresh', async () => {+ await expect(+ MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ }),+ ).rejects.toThrow(ReauthenticationRequiredError);+ });++ it('should refresh expired access token when refresh token and callback are available', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const refreshTokens = jest.fn().mockResolvedValue({+ access_token: 'refreshed-at',+ token_type: 'Bearer',+ expires_in: 3600,+ obtained_at: Date.now(),+ expires_at: Date.now() + 3600000,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ createToken: store.createToken,+ updateToken: store.updateToken,+ refreshTokens,+ });++ expect(result).not.toBeNull();+ expect(result!.access_token).toBe('refreshed-at');+ expect(refreshTokens).toHaveBeenCalledWith(+ 'rt',+ expect.objectContaining({ userId: 'u1', serverName: 'srv1' }),+ );+ });++ it('should return null when refresh fails', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const refreshTokens = jest.fn().mockRejectedValue(new Error('refresh failed'));++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ createToken: store.createToken,+ updateToken: store.updateToken,+ refreshTokens,+ });++ expect(result).toBeNull();+ });++ it('should return null when no refreshTokens callback provided', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ });++ expect(result).toBeNull();+ });++ it('should return null when no createToken callback provided', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ refreshTokens: jest.fn(),+ });++ expect(result).toBeNull();+ });++ it('should pass client info to refreshTokens metadata', async () => {+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_client',+ identifier: 'mcp:srv1:client',+ token: 'enc:{"client_id":"cid","client_secret":"csec"}',+ expiresIn: 86400,+ });++ const refreshTokens = jest.fn().mockResolvedValue({+ access_token: 'new-at',+ token_type: 'Bearer',+ expires_in: 3600,+ });++ await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ createToken: store.createToken,+ updateToken: store.updateToken,+ refreshTokens,+ });++ expect(refreshTokens).toHaveBeenCalledWith(+ 'rt',+ expect.objectContaining({+ clientInfo: expect.objectContaining({ client_id: 'cid' }),+ }),+ );+ });++ it('should handle unauthorized_client refresh error', async () => {+ const { logger } = await import('@librechat/data-schemas');++ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth',+ identifier: 'mcp:srv1',+ token: 'enc:expired-token',+ expiresIn: -1,+ });+ await store.createToken({+ userId: 'u1',+ type: 'mcp_oauth_refresh',+ identifier: 'mcp:srv1:refresh',+ token: 'enc:rt',+ expiresIn: 86400,+ });++ const refreshTokens = jest.fn().mockRejectedValue(new Error('unauthorized_client'));++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ createToken: store.createToken,+ refreshTokens,+ });++ expect(result).toBeNull();+ expect(logger.info).toHaveBeenCalledWith(+ expect.stringContaining('does not support refresh tokens'),+ );+ });+ });++ describe('storeTokens + getTokens round-trip', () => {+ it('should store and retrieve tokens with full encrypt/decrypt cycle', async () => {+ await MCPTokenStorage.storeTokens({+ userId: 'u1',+ serverName: 'srv1',+ tokens: {+ access_token: 'my-access-token',+ token_type: 'Bearer',+ expires_in: 3600,+ refresh_token: 'my-refresh-token',+ },+ createToken: store.createToken,+ clientInfo: { client_id: 'cid', client_secret: 'sec', redirect_uris: [] },+ });++ const result = await MCPTokenStorage.getTokens({+ userId: 'u1',+ serverName: 'srv1',+ findToken: store.findToken,+ });++ expect(result!.access_token).toBe('my-access-token');+ expect(result!.refresh_token).toBe('my-refresh-token');+ expect(result!.token_type).toBe('Bearer');+ expect(result!.obtained_at).toBeDefined();+ expect(result!.expires_at).toBeDefined();+ });+ });+});diff --git a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.tsnew file mode 100644index 0000000000..3b68b2ded4--- /dev/null+++ b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts@@ -0,0 +1,449 @@+import * as http from 'http';+import * as net from 'net';+import { randomUUID, createHash } from 'crypto';+import { z } from 'zod';+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';+import type { FlowState } from '~/flow/types';+import type { Socket } from 'net';++export class MockKeyv<T = unknown> {+ private store: Map<string, FlowState<T>>;++ constructor() {+ this.store = new Map();+ }++ async get(key: string): Promise<FlowState<T> | undefined> {+ return this.store.get(key);+ }++ async set(key: string, value: FlowState<T>, _ttl?: number): Promise<true> {+ this.store.set(key, value);+ return true;+ }++ async delete(key: string): Promise<boolean> {+ return this.store.delete(key);+ }+}++export function getFreePort(): Promise<number> {+ return new Promise((resolve, reject) => {+ const srv = net.createServer();+ srv.listen(0, '127.0.0.1', () => {+ const addr = srv.address() as net.AddressInfo;+ srv.close((err) => (err ? reject(err) : resolve(addr.port)));+ });+ });+}++export function trackSockets(httpServer: http.Server): () => Promise<void> {+ const sockets = new Set<Socket>();+ httpServer.on('connection', (socket: Socket) => {+ sockets.add(socket);+ socket.once('close', () => sockets.delete(socket));+ });+ return () =>+ new Promise<void>((resolve) => {+ for (const socket of sockets) {+ socket.destroy();+ }+ sockets.clear();+ httpServer.close(() => resolve());+ });+}++export interface OAuthTestServerOptions {+ tokenTTLMs?: number;+ issueRefreshTokens?: boolean;+ refreshTokenTTLMs?: number;+ rotateRefreshTokens?: boolean;+}++export interface OAuthTestServer {+ url: string;+ port: number;+ close: () => Promise<void>;+ issuedTokens: Set<string>;+ tokenTTL: number;+ tokenIssueTimes: Map<string, number>;+ issuedRefreshTokens: Map<string, string>;+ registeredClients: Map<string, { client_id: string; client_secret: string }>;+ getAuthCode: () => Promise<string>;+}++async function readRequestBody(req: http.IncomingMessage): Promise<string> {+ const chunks: Uint8Array[] = [];+ for await (const chunk of req) {+ chunks.push(chunk as Uint8Array);+ }+ return Buffer.concat(chunks).toString();+}++function parseTokenRequest(body: string, contentType: string | undefined): URLSearchParams | null {+ if (contentType?.includes('application/x-www-form-urlencoded')) {+ return new URLSearchParams(body);+ }+ if (contentType?.includes('application/json')) {+ const json = JSON.parse(body) as Record<string, string>;+ return new URLSearchParams(json);+ }+ return new URLSearchParams(body);+}++export async function createOAuthMCPServer(+ options: OAuthTestServerOptions = {},+): Promise<OAuthTestServer> {+ const {+ tokenTTLMs = 60000,+ issueRefreshTokens = false,+ refreshTokenTTLMs = 365 * 24 * 60 * 60 * 1000,+ rotateRefreshTokens = false,+ } = options;++ const sessions = new Map<string, StreamableHTTPServerTransport>();+ const issuedTokens = new Set<string>();+ const tokenIssueTimes = new Map<string, number>();+ const issuedRefreshTokens = new Map<string, string>();+ const refreshTokenIssueTimes = new Map<string, number>();+ const authCodes = new Map<string, { codeChallenge?: string; codeChallengeMethod?: string }>();+ const registeredClients = new Map<string, { client_id: string; client_secret: string }>();++ let port = 0;++ const httpServer = http.createServer(async (req, res) => {+ const url = new URL(req.url ?? '/', `http://${req.headers.host}`);++ if (url.pathname === '/.well-known/oauth-authorization-server' && req.method === 'GET') {+ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(+ JSON.stringify({+ issuer: `http://127.0.0.1:${port}`,+ authorization_endpoint: `http://127.0.0.1:${port}/authorize`,+ token_endpoint: `http://127.0.0.1:${port}/token`,+ registration_endpoint: `http://127.0.0.1:${port}/register`,+ response_types_supported: ['code'],+ grant_types_supported: issueRefreshTokens+ ? ['authorization_code', 'refresh_token']+ : ['authorization_code'],+ token_endpoint_auth_methods_supported: ['client_secret_basic', 'client_secret_post'],+ code_challenge_methods_supported: ['S256'],+ }),+ );+ return;+ }++ if (url.pathname === '/register' && req.method === 'POST') {+ const body = await readRequestBody(req);+ const data = JSON.parse(body) as { redirect_uris?: string[] };+ const clientId = `client-${randomUUID().slice(0, 8)}`;+ const clientSecret = `secret-${randomUUID()}`;+ registeredClients.set(clientId, { client_id: clientId, client_secret: clientSecret });+ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(+ JSON.stringify({+ client_id: clientId,+ client_secret: clientSecret,+ redirect_uris: data.redirect_uris ?? [],+ }),+ );+ return;+ }++ if (url.pathname === '/authorize') {+ const code = randomUUID();+ const codeChallenge = url.searchParams.get('code_challenge') ?? undefined;+ const codeChallengeMethod = url.searchParams.get('code_challenge_method') ?? undefined;+ authCodes.set(code, { codeChallenge, codeChallengeMethod });+ const redirectUri = url.searchParams.get('redirect_uri') ?? '';+ const state = url.searchParams.get('state') ?? '';+ res.writeHead(302, {+ Location: `${redirectUri}?code=${code}&state=${state}`,+ });+ res.end();+ return;+ }++ if (url.pathname === '/token' && req.method === 'POST') {+ const body = await readRequestBody(req);+ const params = parseTokenRequest(body, req.headers['content-type']);+ if (!params) {+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_request' }));+ return;+ }++ const grantType = params.get('grant_type');++ if (grantType === 'authorization_code') {+ const code = params.get('code');+ const codeData = code ? authCodes.get(code) : undefined;+ if (!code || !codeData) {+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_grant' }));+ return;+ }++ if (codeData.codeChallenge) {+ const codeVerifier = params.get('code_verifier');+ if (!codeVerifier) {+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_grant' }));+ return;+ }+ if (codeData.codeChallengeMethod === 'S256') {+ const expected = createHash('sha256').update(codeVerifier).digest('base64url');+ if (expected !== codeData.codeChallenge) {+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_grant' }));+ return;+ }+ }+ }++ authCodes.delete(code);++ const accessToken = randomUUID();+ issuedTokens.add(accessToken);+ tokenIssueTimes.set(accessToken, Date.now());++ const tokenResponse: Record<string, string | number> = {+ access_token: accessToken,+ token_type: 'Bearer',+ expires_in: Math.ceil(tokenTTLMs / 1000),+ };++ if (issueRefreshTokens) {+ const refreshToken = randomUUID();+ issuedRefreshTokens.set(refreshToken, accessToken);+ refreshTokenIssueTimes.set(refreshToken, Date.now());+ tokenResponse.refresh_token = refreshToken;+ }++ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify(tokenResponse));+ return;+ }++ if (grantType === 'refresh_token' && issueRefreshTokens) {+ const refreshToken = params.get('refresh_token');+ if (!refreshToken || !issuedRefreshTokens.has(refreshToken)) {+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_grant' }));+ return;+ }++ const issueTime = refreshTokenIssueTimes.get(refreshToken) ?? 0;+ if (Date.now() - issueTime > refreshTokenTTLMs) {+ issuedRefreshTokens.delete(refreshToken);+ refreshTokenIssueTimes.delete(refreshToken);+ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_grant' }));+ return;+ }++ const newAccessToken = randomUUID();+ issuedTokens.add(newAccessToken);+ tokenIssueTimes.set(newAccessToken, Date.now());++ const tokenResponse: Record<string, string | number> = {+ access_token: newAccessToken,+ token_type: 'Bearer',+ expires_in: Math.ceil(tokenTTLMs / 1000),+ };++ if (rotateRefreshTokens) {+ issuedRefreshTokens.delete(refreshToken);+ refreshTokenIssueTimes.delete(refreshToken);+ const newRefreshToken = randomUUID();+ issuedRefreshTokens.set(newRefreshToken, newAccessToken);+ refreshTokenIssueTimes.set(newRefreshToken, Date.now());+ tokenResponse.refresh_token = newRefreshToken;+ }++ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify(tokenResponse));+ return;+ }++ res.writeHead(400, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'unsupported_grant_type' }));+ return;+ }++ // All other paths require Bearer token auth+ const authHeader = req.headers.authorization;+ if (!authHeader || !authHeader.startsWith('Bearer ')) {+ res.writeHead(401, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_token' }));+ return;+ }++ const token = authHeader.slice(7);+ if (!issuedTokens.has(token)) {+ res.writeHead(401, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_token' }));+ return;+ }++ const issueTime = tokenIssueTimes.get(token) ?? 0;+ if (Date.now() - issueTime > tokenTTLMs) {+ issuedTokens.delete(token);+ tokenIssueTimes.delete(token);+ res.writeHead(401, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ error: 'invalid_token' }));+ return;+ }++ // Authenticated MCP request — route to transport+ const sid = req.headers['mcp-session-id'] as string | undefined;+ let transport = sid ? sessions.get(sid) : undefined;++ if (!transport) {+ transport = new StreamableHTTPServerTransport({+ sessionIdGenerator: () => randomUUID(),+ });+ const mcp = new McpServer({ name: 'oauth-test-server', version: '0.0.1' });+ mcp.tool('echo', { message: z.string() }, async (args) => ({+ content: [{ type: 'text' as const, text: `echo: ${args.message}` }],+ }));+ await mcp.connect(transport);+ }++ await transport.handleRequest(req, res);++ if (transport.sessionId && !sessions.has(transport.sessionId)) {+ sessions.set(transport.sessionId, transport);+ transport.onclose = () => sessions.delete(transport!.sessionId!);+ }+ });++ const destroySockets = trackSockets(httpServer);+ port = await getFreePort();+ await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', resolve));++ return {+ url: `http://127.0.0.1:${port}/`,+ port,+ issuedTokens,+ tokenTTL: tokenTTLMs,+ tokenIssueTimes,+ issuedRefreshTokens,+ registeredClients,+ getAuthCode: async () => {+ const authRes = await fetch(+ `http://127.0.0.1:${port}/authorize?redirect_uri=http://localhost&state=test`,+ { redirect: 'manual' },+ );+ const location = authRes.headers.get('location') ?? '';+ return new URL(location).searchParams.get('code') ?? '';+ },+ close: async () => {+ const closing = [...sessions.values()].map((t) => t.close().catch(() => undefined));+ sessions.clear();+ await Promise.all(closing);+ await destroySockets();+ },+ };+}++export interface InMemoryToken {+ userId: string;+ type: string;+ identifier: string;+ token: string;+ expiresAt: Date;+ createdAt: Date;+ metadata?: Map<string, unknown> | Record<string, unknown>;+}++export class InMemoryTokenStore {+ private tokens: Map<string, InMemoryToken> = new Map();++ private key(filter: { userId?: string; type?: string; identifier?: string }): string {+ return `${filter.userId}:${filter.type}:${filter.identifier}`;+ }++ findToken = async (filter: {+ userId?: string;+ type?: string;+ identifier?: string;+ }): Promise<InMemoryToken | null> => {+ for (const token of this.tokens.values()) {+ const matchUserId = !filter.userId || token.userId === filter.userId;+ const matchType = !filter.type || token.type === filter.type;+ const matchIdentifier = !filter.identifier || token.identifier === filter.identifier;+ if (matchUserId && matchType && matchIdentifier) {+ return token;+ }+ }+ return null;+ };++ createToken = async (data: {+ userId: string;+ type: string;+ identifier: string;+ token: string;+ expiresIn?: number;+ metadata?: Record<string, unknown>;+ }): Promise<InMemoryToken> => {+ const expiresIn = data.expiresIn ?? 365 * 24 * 60 * 60;+ const token: InMemoryToken = {+ userId: data.userId,+ type: data.type,+ identifier: data.identifier,+ token: data.token,+ expiresAt: new Date(Date.now() + expiresIn * 1000),+ createdAt: new Date(),+ metadata: data.metadata,+ };+ this.tokens.set(this.key(data), token);+ return token;+ };++ updateToken = async (+ filter: { userId?: string; type?: string; identifier?: string },+ data: {+ userId?: string;+ type?: string;+ identifier?: string;+ token?: string;+ expiresIn?: number;+ metadata?: Record<string, unknown>;+ },+ ): Promise<InMemoryToken> => {+ const existing = await this.findToken(filter);+ if (!existing) {+ throw new Error(`Token not found for filter: ${JSON.stringify(filter)}`);+ }+ const existingKey = this.key(existing);+ const expiresIn =+ data.expiresIn ?? Math.floor((existing.expiresAt.getTime() - Date.now()) / 1000);+ const updated: InMemoryToken = {+ ...existing,+ token: data.token ?? existing.token,+ expiresAt: data.expiresIn ? new Date(Date.now() + expiresIn * 1000) : existing.expiresAt,+ metadata: data.metadata ?? existing.metadata,+ };+ this.tokens.set(existingKey, updated);+ return updated;+ };++ deleteToken = async (filter: {+ userId: string;+ type: string;+ identifier: string;+ }): Promise<void> => {+ this.tokens.delete(this.key(filter));+ };++ getAll(): InMemoryToken[] {+ return [...this.tokens.values()];+ }++ clear(): void {+ this.tokens.clear();+ }+}diff --git a/packages/api/src/mcp/__tests__/reconnection-storm.test.ts b/packages/api/src/mcp/__tests__/reconnection-storm.test.tsindex c1cf0ec5df..e073dca8a3 100644--- a/packages/api/src/mcp/__tests__/reconnection-storm.test.ts+++ b/packages/api/src/mcp/__tests__/reconnection-storm.test.ts@@ -12,8 +12,12 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';import type { Socket } from 'net';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import type { MCPOAuthTokens } from '~/mcp/oauth';import { OAuthReconnectionTracker } from '~/mcp/oauth/OAuthReconnectionTracker';+import { createOAuthMCPServer } from './helpers/oauthTestServer';import { MCPConnection } from '~/mcp/connection';+import { mcpConfig } from '~/mcp/mcpConfig';jest.mock('@librechat/data-schemas', () => ({logger: {@@ -143,16 +147,17 @@ afterEach(() => {/* ------------------------------------------------------------------ *//* Fix #2 — Circuit breaker trips after rapid connect/disconnect */-/* cycles (5 cycles within 60s -> 30s cooldown) */+/* cycles (CB_MAX_CYCLES within window -> cooldown) *//* ------------------------------------------------------------------ */describe('Fix #2: Circuit breaker stops rapid reconnect cycling', () => {- it('blocks connection after 5 rapid cycles via static circuit breaker', async () => {+ it('blocks connection after CB_MAX_CYCLES rapid cycles via static circuit breaker', async () => {const srv = await startMCPServer();const conn = createConnection('cycling-server', srv.url);let completedCycles = 0;let breakerMessage = '';- for (let cycle = 0; cycle < 10; cycle++) {+ const maxAttempts = mcpConfig.CB_MAX_CYCLES * 2;+ for (let cycle = 0; cycle < maxAttempts; cycle++) {try {await conn.connect();await teardownConnection(conn);@@ -166,7 +171,7 @@ describe('Fix #2: Circuit breaker stops rapid reconnect cycling', () => {}expect(breakerMessage).toContain('Circuit breaker is open');- expect(completedCycles).toBeLessThanOrEqual(5);+ expect(completedCycles).toBeLessThanOrEqual(mcpConfig.CB_MAX_CYCLES);await srv.close();});@@ -266,12 +271,13 @@ describe('Fix #4: Circuit breaker state persists across instance replacement', (/* recordFailedRound() in the catch path *//* ------------------------------------------------------------------ */describe('Fix #5: Dead server triggers circuit breaker', () => {- it('3 failures trigger backoff, blocking subsequent attempts before they reach the SDK', async () => {+ it('failures trigger backoff, blocking subsequent attempts before they reach the SDK', async () => {const conn = createConnection('dead', 'http://127.0.0.1:1/mcp', 1000);const spy = jest.spyOn(conn.client, 'connect');+ const totalAttempts = mcpConfig.CB_MAX_FAILED_ROUNDS + 2;const errors: string[] = [];- for (let i = 0; i < 5; i++) {+ for (let i = 0; i < totalAttempts; i++) {try {await conn.connect();} catch (e) {@@ -279,8 +285,8 @@ describe('Fix #5: Dead server triggers circuit breaker', () => {}}- expect(spy.mock.calls.length).toBe(3);- expect(errors).toHaveLength(5);+ expect(spy.mock.calls.length).toBe(mcpConfig.CB_MAX_FAILED_ROUNDS);+ expect(errors).toHaveLength(totalAttempts);expect(errors.filter((m) => m.includes('Circuit breaker is open'))).toHaveLength(2);await conn.disconnect();@@ -295,7 +301,7 @@ describe('Fix #5: Dead server triggers circuit breaker', () => {userId: 'user-A',});- for (let i = 0; i < 3; i++) {+ for (let i = 0; i < mcpConfig.CB_MAX_FAILED_ROUNDS; i++) {try {await userA.connect();} catch {@@ -332,7 +338,7 @@ describe('Fix #5: Dead server triggers circuit breaker', () => {serverConfig: { url: deadUrl, type: 'streamable-http', initTimeout: 1000 } as never,userId: 'user-A',});- for (let i = 0; i < 3; i++) {+ for (let i = 0; i < mcpConfig.CB_MAX_FAILED_ROUNDS; i++) {try {await userA.connect();} catch {@@ -448,13 +454,14 @@ describe('Fix #6: OAuth failure uses cooldown-based retry', () => {/* Integration: Circuit breaker caps rapid cycling with real transport *//* ------------------------------------------------------------------ */describe('Cascade: Circuit breaker caps rapid cycling', () => {- it('breaker trips before 10 cycles complete against a live server', async () => {+ it('breaker trips before double CB_MAX_CYCLES complete against a live server', async () => {const srv = await startMCPServer();const conn = createConnection('cascade', srv.url);const spy = jest.spyOn(conn.client, 'connect');let completedCycles = 0;- for (let i = 0; i < 10; i++) {+ const maxAttempts = mcpConfig.CB_MAX_CYCLES * 2;+ for (let i = 0; i < maxAttempts; i++) {try {await conn.connect();await teardownConnection(conn);@@ -469,8 +476,8 @@ describe('Cascade: Circuit breaker caps rapid cycling', () => {}}- expect(completedCycles).toBeLessThanOrEqual(5);- expect(spy.mock.calls.length).toBeLessThanOrEqual(5);+ expect(completedCycles).toBeLessThanOrEqual(mcpConfig.CB_MAX_CYCLES);+ expect(spy.mock.calls.length).toBeLessThanOrEqual(mcpConfig.CB_MAX_CYCLES);await srv.close();});@@ -501,6 +508,146 @@ describe('Cascade: Circuit breaker caps rapid cycling', () => {}, 30_000);});+/* ------------------------------------------------------------------ */+/* OAuth: cycle recovery after successful OAuth reconnect */+/* ------------------------------------------------------------------ */+describe('OAuth: cycle budget recovery after successful OAuth', () => {+ let oauthServer: OAuthTestServer;++ beforeEach(async () => {+ oauthServer = await createOAuthMCPServer({ tokenTTLMs: 60000 });+ });++ afterEach(async () => {+ await oauthServer.close();+ });++ async function exchangeCodeForToken(serverUrl: string): Promise<string> {+ const authRes = await fetch(`${serverUrl}authorize?redirect_uri=http://localhost&state=test`, {+ redirect: 'manual',+ });+ const location = authRes.headers.get('location') ?? '';+ const code = new URL(location).searchParams.get('code') ?? '';+ const tokenRes = await fetch(`${serverUrl}token`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: `grant_type=authorization_code&code=${code}`,+ });+ const data = (await tokenRes.json()) as { access_token: string };+ return data.access_token;+ }++ it('should decrement cycle count after successful OAuth recovery', async () => {+ const serverName = 'oauth-cycle-test';+ MCPConnection.clearCooldown(serverName);++ const conn = new MCPConnection({+ serverName,+ serverConfig: { type: 'streamable-http', url: oauthServer.url, initTimeout: 10000 },+ userId: 'user-1',+ });++ // When oauthRequired fires, get a token and emit oauthHandled+ // This triggers the oauthRecovery path inside connectClient+ conn.on('oauthRequired', async () => {+ const accessToken = await exchangeCodeForToken(oauthServer.url);+ conn.setOAuthTokens({+ access_token: accessToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens);+ conn.emit('oauthHandled');+ });++ // connect() → 401 → oauthRequired → oauthHandled → connectClient returns+ // connect() sees not connected → throws "Connection not established"+ await expect(conn.connect()).rejects.toThrow('Connection not established');++ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ const cb = (MCPConnection as any).circuitBreakers.get(serverName);+ const cyclesBeforeRetry = cb.cycleCount;++ // Retry — should succeed and decrement cycle count via oauthRecovery+ await conn.connect();+ expect(await conn.isConnected()).toBe(true);++ const cyclesAfterSuccess = cb.cycleCount;+ // The retry adds +1 cycle (disconnect(false)) then -1 (oauthRecovery decrement)+ // So cyclesAfterSuccess should equal cyclesBeforeRetry, not cyclesBeforeRetry + 1+ expect(cyclesAfterSuccess).toBe(cyclesBeforeRetry);++ await teardownConnection(conn);+ });++ it('should allow more OAuth reconnects than non-OAuth before breaker trips', async () => {+ const serverName = 'oauth-budget';+ MCPConnection.clearCooldown(serverName);++ // Each OAuth flow: connect (+1) → 401 → oauthHandled → retry connect (+1) → success (-1) = net 1+ // Without the decrement it would be net 2 per flow, tripping the breaker after ~2 users+ let successfulFlows = 0;+ for (let i = 0; i < 10; i++) {+ const conn = new MCPConnection({+ serverName,+ serverConfig: { type: 'streamable-http', url: oauthServer.url, initTimeout: 10000 },+ userId: `user-${i}`,+ });++ conn.on('oauthRequired', async () => {+ const accessToken = await exchangeCodeForToken(oauthServer.url);+ conn.setOAuthTokens({+ access_token: accessToken,+ token_type: 'Bearer',+ } as MCPOAuthTokens);+ conn.emit('oauthHandled');+ });++ try {+ // First connect: 401 → oauthHandled → returns without connection+ await conn.connect().catch(() => {});+ // Retry: succeeds with token, decrements cycle+ await conn.connect();+ successfulFlows++;+ await teardownConnection(conn);+ } catch (e) {+ conn.removeAllListeners();+ if ((e as Error).message.includes('Circuit breaker is open')) {+ break;+ }+ }+ }++ // With the oauthRecovery decrement, each flow is net ~1 cycle instead of ~2,+ // so we should get more successful flows before the breaker trips+ expect(successfulFlows).toBeGreaterThanOrEqual(3);+ });++ it('should not decrement cycle count when OAuth fails', async () => {+ const serverName = 'oauth-failed-no-decrement';+ MCPConnection.clearCooldown(serverName);++ const conn = new MCPConnection({+ serverName,+ serverConfig: { type: 'streamable-http', url: oauthServer.url, initTimeout: 10000 },+ userId: 'user-1',+ });++ conn.on('oauthRequired', () => {+ conn.emit('oauthFailed', new Error('user denied'));+ });++ await expect(conn.connect()).rejects.toThrow();++ // eslint-disable-next-line @typescript-eslint/no-explicit-any+ const cb = (MCPConnection as any).circuitBreakers.get(serverName);+ const cyclesAfterFailure = cb.cycleCount;++ // connect() recorded +1 cycle, oauthFailed should NOT decrement+ expect(cyclesAfterFailure).toBeGreaterThanOrEqual(1);++ conn.removeAllListeners();+ });+});+/* ------------------------------------------------------------------ *//* Sanity: Real transport works end-to-end *//* ------------------------------------------------------------------ */diff --git a/packages/api/src/mcp/connection.ts b/packages/api/src/mcp/connection.tsindex cac0a4afc5..8dc857cd3b 100644--- a/packages/api/src/mcp/connection.ts+++ b/packages/api/src/mcp/connection.ts@@ -82,14 +82,6 @@ interface CircuitBreakerState {failedBackoffUntil: number;}-const CB_MAX_CYCLES = 5;-const CB_CYCLE_WINDOW_MS = 60_000;-const CB_CYCLE_COOLDOWN_MS = 30_000;--const CB_MAX_FAILED_ROUNDS = 3;-const CB_FAILED_WINDOW_MS = 120_000;-const CB_BASE_BACKOFF_MS = 30_000;-const CB_MAX_BACKOFF_MS = 300_000;/** Default body timeout for Streamable HTTP GET SSE streams that idle between server pushes */const DEFAULT_SSE_READ_TIMEOUT = FIVE_MINUTES;@@ -281,6 +273,7 @@ export class MCPConnection extends EventEmitter {private oauthTokens?: MCPOAuthTokens | null;private requestHeaders?: Record<string, string> | null;private oauthRequired = false;+ private oauthRecovery = false;private readonly useSSRFProtection: boolean;iconPath?: string;timeout?: number;@@ -325,17 +318,17 @@ export class MCPConnection extends EventEmitter {private recordCycle(): void {const cb = this.getCircuitBreaker();const now = Date.now();- if (now - cb.cycleWindowStart > CB_CYCLE_WINDOW_MS) {+ if (now - cb.cycleWindowStart > mcpConfig.CB_CYCLE_WINDOW_MS) {cb.cycleCount = 0;cb.cycleWindowStart = now;}cb.cycleCount++;- if (cb.cycleCount >= CB_MAX_CYCLES) {- cb.cooldownUntil = now + CB_CYCLE_COOLDOWN_MS;+ if (cb.cycleCount >= mcpConfig.CB_MAX_CYCLES) {+ cb.cooldownUntil = now + mcpConfig.CB_CYCLE_COOLDOWN_MS;cb.cycleCount = 0;cb.cycleWindowStart = now;logger.warn(- `${this.getLogPrefix()} Circuit breaker: too many cycles, cooling down for ${CB_CYCLE_COOLDOWN_MS}ms`,+ `${this.getLogPrefix()} Circuit breaker: too many cycles, cooling down for ${mcpConfig.CB_CYCLE_COOLDOWN_MS}ms`,);}}@@ -343,15 +336,16 @@ export class MCPConnection extends EventEmitter {private recordFailedRound(): void {const cb = this.getCircuitBreaker();const now = Date.now();- if (now - cb.failedWindowStart > CB_FAILED_WINDOW_MS) {+ if (now - cb.failedWindowStart > mcpConfig.CB_FAILED_WINDOW_MS) {cb.failedRounds = 0;cb.failedWindowStart = now;}cb.failedRounds++;- if (cb.failedRounds >= CB_MAX_FAILED_ROUNDS) {+ if (cb.failedRounds >= mcpConfig.CB_MAX_FAILED_ROUNDS) {const backoff = Math.min(- CB_BASE_BACKOFF_MS * Math.pow(2, cb.failedRounds - CB_MAX_FAILED_ROUNDS),- CB_MAX_BACKOFF_MS,+ mcpConfig.CB_BASE_BACKOFF_MS *+ Math.pow(2, cb.failedRounds - mcpConfig.CB_MAX_FAILED_ROUNDS),+ mcpConfig.CB_MAX_BACKOFF_MS,);cb.failedBackoffUntil = now + backoff;logger.warn(@@ -367,6 +361,13 @@ export class MCPConnection extends EventEmitter {cb.failedBackoffUntil = 0;}+ public static decrementCycleCount(serverName: string): void {+ const cb = MCPConnection.circuitBreakers.get(serverName);+ if (cb && cb.cycleCount > 0) {+ cb.cycleCount--;+ }+ }+setRequestHeaders(headers: Record<string, string> | null): void {if (!headers) {return;@@ -816,6 +817,13 @@ export class MCPConnection extends EventEmitter {this.emit('connectionChange', 'connected');this.reconnectAttempts = 0;this.resetFailedRounds();+ if (this.oauthRecovery) {+ MCPConnection.decrementCycleCount(this.serverName);+ this.oauthRecovery = false;+ logger.debug(+ `${this.getLogPrefix()} OAuth recovery: decremented cycle count after successful reconnect`,+ );+ }} catch (error) {// Check if it's a rate limit error - stop immediately to avoid making it worseif (this.isRateLimitError(error)) {@@ -899,9 +907,8 @@ export class MCPConnection extends EventEmitter {try {// Wait for OAuth to be handledawait oauthHandledPromise;- // Reset the oauthRequired flagthis.oauthRequired = false;- // Don't throw the error - just return so connection can be retried+ this.oauthRecovery = true;logger.info(`${this.getLogPrefix()} OAuth handled successfully, connection will be retried`,);diff --git a/packages/api/src/mcp/mcpConfig.ts b/packages/api/src/mcp/mcpConfig.tsindex f3efd3592b..a81752e909 100644--- a/packages/api/src/mcp/mcpConfig.ts+++ b/packages/api/src/mcp/mcpConfig.ts@@ -12,4 +12,18 @@ export const mcpConfig = {USER_CONNECTION_IDLE_TIMEOUT: math(process.env.MCP_USER_CONNECTION_IDLE_TIMEOUT ?? 15 * 60 * 1000,),+ /** Max connect/disconnect cycles before the circuit breaker trips. Default: 7 */+ CB_MAX_CYCLES: math(process.env.MCP_CB_MAX_CYCLES ?? 7),+ /** Sliding window (ms) for counting cycles. Default: 45s */+ CB_CYCLE_WINDOW_MS: math(process.env.MCP_CB_CYCLE_WINDOW_MS ?? 45_000),+ /** Cooldown (ms) after the cycle breaker trips. Default: 15s */+ CB_CYCLE_COOLDOWN_MS: math(process.env.MCP_CB_CYCLE_COOLDOWN_MS ?? 15_000),+ /** Max consecutive failed connection rounds before backoff. Default: 3 */+ CB_MAX_FAILED_ROUNDS: math(process.env.MCP_CB_MAX_FAILED_ROUNDS ?? 3),+ /** Sliding window (ms) for counting failed rounds. Default: 120s */+ CB_FAILED_WINDOW_MS: math(process.env.MCP_CB_FAILED_WINDOW_MS ?? 120_000),+ /** Base backoff (ms) after failed round threshold is reached. Default: 30s */+ CB_BASE_BACKOFF_MS: math(process.env.MCP_CB_BASE_BACKOFF_MS ?? 30_000),+ /** Max backoff cap (ms) for exponential backoff. Default: 300s */+ CB_MAX_BACKOFF_MS: math(process.env.MCP_CB_MAX_BACKOFF_MS ?? 300_000),};diff --git a/packages/api/src/mcp/oauth/handler.ts b/packages/api/src/mcp/oauth/handler.tsindex 83e855591e..366d0d2fde 100644--- a/packages/api/src/mcp/oauth/handler.ts+++ b/packages/api/src/mcp/oauth/handler.ts@@ -426,8 +426,8 @@ export class MCPOAuthHandler {scope: config.scope,});- /** Add state parameter with flowId to the authorization URL */- authorizationUrl.searchParams.set('state', flowId);+ /** Add cryptographic state parameter to the authorization URL */+ authorizationUrl.searchParams.set('state', state);logger.debug(`[MCPOAuth] Added state parameter to authorization URL`);const flowMetadata: MCPOAuthFlowMetadata = {@@ -505,8 +505,8 @@ export class MCPOAuthHandler {`[MCPOAuth] Authorization URL: ${sanitizeUrlForLogging(authorizationUrl.toString())}`,);- /** Add state parameter with flowId to the authorization URL */- authorizationUrl.searchParams.set('state', flowId);+ /** Add cryptographic state parameter to the authorization URL */+ authorizationUrl.searchParams.set('state', state);logger.debug(`[MCPOAuth] Added state parameter to authorization URL`);if (resourceMetadata?.resource != null && resourceMetadata.resource) {@@ -672,6 +672,44 @@ export class MCPOAuthHandler {return randomBytes(32).toString('base64url');}+ private static readonly STATE_MAP_TYPE = 'mcp_oauth_state';++ /**+ * Stores a mapping from the opaque OAuth state parameter to the flowId.+ * This allows the callback to resolve the flowId from an unguessable state+ * value, preventing attackers from forging callback requests.+ */+ static async storeStateMapping(+ state: string,+ flowId: string,+ flowManager: FlowStateManager<MCPOAuthTokens | null>,+ ): Promise<void> {+ await flowManager.initFlow(state, this.STATE_MAP_TYPE, { flowId });+ }++ /**+ * Resolves an opaque OAuth state parameter back to the original flowId.+ * Returns null if the state is not found (expired or never stored).+ */+ static async resolveStateToFlowId(+ state: string,+ flowManager: FlowStateManager<MCPOAuthTokens | null>,+ ): Promise<string | null> {+ const mapping = await flowManager.getFlowState(state, this.STATE_MAP_TYPE);+ return (mapping?.metadata?.flowId as string) ?? null;+ }++ /**+ * Deletes an orphaned state mapping when a flow is replaced.+ * Prevents old authorization URLs from resolving after a flow restart.+ */+ static async deleteStateMapping(+ state: string,+ flowManager: FlowStateManager<MCPOAuthTokens | null>,+ ): Promise<void> {+ await flowManager.deleteFlow(state, this.STATE_MAP_TYPE);+ }+/*** Gets the default redirect URI for a server*/diff --git a/packages/api/src/mcp/oauth/tokens.ts b/packages/api/src/mcp/oauth/tokens.tsindex 005ed7dd9a..7b1d189347 100644--- a/packages/api/src/mcp/oauth/tokens.ts+++ b/packages/api/src/mcp/oauth/tokens.ts@@ -4,6 +4,15 @@ import type { TokenMethods, IToken } from '@librechat/data-schemas';import type { MCPOAuthTokens, ExtendedOAuthTokens, OAuthMetadata } from './types';import { isSystemUserId } from '~/mcp/enum';+export class ReauthenticationRequiredError extends Error {+ constructor(serverName: string, reason: 'expired' | 'missing') {+ super(+ `Re-authentication required for "${serverName}": access token ${reason} and no refresh token available`,+ );+ this.name = 'ReauthenticationRequiredError';+ }+}+interface StoreTokensParams {userId: string;serverName: string;@@ -27,7 +36,12 @@ interface GetTokensParams {findToken: TokenMethods['findToken'];refreshTokens?: (refreshToken: string,- metadata: { userId: string; serverName: string; identifier: string },+ metadata: {+ userId: string;+ serverName: string;+ identifier: string;+ clientInfo?: OAuthClientInformation;+ },) => Promise<MCPOAuthTokens>;createToken?: TokenMethods['createToken'];updateToken?: TokenMethods['updateToken'];@@ -273,10 +287,11 @@ export class MCPTokenStorage {});if (!refreshTokenData) {+ const reason = isMissing ? 'missing' : 'expired';logger.info(- `${logPrefix} Access token ${isMissing ? 'missing' : 'expired'} and no refresh token available`,+ `${logPrefix} Access token ${reason} and no refresh token available — re-authentication required`,);- return null;+ throw new ReauthenticationRequiredError(serverName, reason);}if (!refreshTokens) {@@ -395,6 +410,9 @@ export class MCPTokenStorage {logger.debug(`${logPrefix} Loaded existing OAuth tokens from storage`);return tokens;} catch (error) {+ if (error instanceof ReauthenticationRequiredError) {+ throw error;+ }logger.error(`${logPrefix} Failed to retrieve tokens`, error);return null;}diff --git a/packages/api/src/mcp/oauth/types.ts b/packages/api/src/mcp/oauth/types.tsindex 178e20e35b..2138b4a782 100644--- a/packages/api/src/mcp/oauth/types.ts+++ b/packages/api/src/mcp/oauth/types.ts@@ -88,6 +88,7 @@ export interface MCPOAuthFlowMetadata extends FlowMetadata {clientInfo?: OAuthClientInformation;metadata?: OAuthMetadata;resourceMetadata?: OAuthProtectedResourceMetadata;+ authorizationUrl?: string;}export interface MCPOAuthTokens extends OAuthTokens {