From ceecedaf7aab53c844e0a3dab7b2a800d92dbc8e Mon Sep 17 00:00:00 2001 From: "lia-by-librechat[bot]" <328778573+lia-by-librechat[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 08:28:14 -0400 Subject: [PATCH] =?UTF-8?q?=E2=98=94=20fix:=20Preserve=20MCP=20Authorizati?= =?UTF-8?q?on=20During=20Token=20Endpoint=20Outages=20(#16126)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Classify HTTP 408, 429, and 5xx before legacy body-message classifiers can invalidate client registration or start consent. Preserve typed temporary failures across refresh storage and verify retry with the existing grant against the real SDK test provider. Keep permanent grant errors and existing UI retry behavior intact. Co-authored-by: Lia --- .../__tests__/useMCPServerManager.spec.tsx | 65 +++++++++ ...ectionFactory.oauthSdk.integration.test.ts | 136 ++++++++++++++++++ .../__tests__/MCPOAuthTokenStorage.test.ts | 41 ++++++ .../__tests__/handler.refreshScope.test.ts | 65 +++++++++ .../mcp/__tests__/helpers/oauthTestServer.ts | 10 ++ packages/api/src/mcp/oauth/handler.ts | 25 +++- packages/api/src/mcp/oauth/tokens.ts | 8 +- 7 files changed, 347 insertions(+), 3 deletions(-) diff --git a/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx b/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx index 263382214b..34a3b2b47c 100644 --- a/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx +++ b/client/src/hooks/MCP/__tests__/useMCPServerManager.spec.tsx @@ -6,6 +6,9 @@ import { QueryClient, QueryClientProvider, QueryObserver } from '@tanstack/react import type { MCPReinitializeResponse } from 'librechat-data-provider'; import { useMCPServerManager } from '../useMCPServerManager'; +const mockOpenInNewTab = jest.fn(); +jest.mock('~/utils', () => ({ openInNewTab: (...args: unknown[]) => mockOpenInNewTab(...args) })); + const mockShowToast = jest.fn(); const mockSetMCPValues = jest.fn(); const mockReinitialize = jest.fn(); @@ -48,6 +51,68 @@ function deferred() { } describe('useMCPServerManager initialization', () => { + it.each(['response', 'http'] as const)( + 'clears the spinner after a transient %s failure and lets retry succeed without OAuth', + async (failure) => { + mockReinitialize.mockReset(); + mockSetMCPValues.mockClear(); + mockShowToast.mockClear(); + mockOpenInNewTab.mockClear(); + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + const wrapper = ({ children }: { children: React.ReactNode }) => ( + + {children} + + ); + const { result, unmount } = renderHook(() => useMCPServerManager(), { wrapper }); + const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined); + try { + if (failure === 'http') { + mockReinitialize.mockRejectedValueOnce(new Error('Service temporarily unavailable')); + } else { + mockReinitialize.mockResolvedValueOnce({ + success: false, + serverName: 'test-server', + oauthRequired: false, + failureReason: 'initialization_failed', + }); + } + await act(async () => { + await result.current.initializeServer('test-server'); + }); + expect(result.current.isInitializing('test-server')).toBe(false); + expect(result.current.isCancellable('test-server')).toBe(false); + expect(mockOpenInNewTab).not.toHaveBeenCalled(); + expect(mockSetMCPValues).not.toHaveBeenCalled(); + expect(mockShowToast).toHaveBeenLastCalledWith({ + message: 'com_ui_mcp_init_failed', + status: 'error', + }); + + mockReinitialize.mockResolvedValueOnce({ + success: true, + serverName: 'test-server', + oauthRequired: false, + }); + await act(async () => { + await result.current.initializeServer('test-server'); + }); + expect(mockReinitialize).toHaveBeenCalledTimes(2); + expect(result.current.isInitializing('test-server')).toBe(false); + expect(mockOpenInNewTab).not.toHaveBeenCalled(); + expect(mockSetMCPValues).toHaveBeenCalledWith(['test-server']); + expect(mockShowToast).toHaveBeenLastCalledWith({ + message: 'com_ui_mcp_initialized_success', + status: 'success', + }); + } finally { + consoleError.mockRestore(); + unmount(); + queryClient.clear(); + } + }, + ); + it('keeps passive authorization observers opt-in for shared hook callers', () => { const queryClient = new QueryClient(); const wrapper = ({ children }: { children: React.ReactNode }) => ( diff --git a/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts b/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts index 180d4ae4ae..c723985eca 100644 --- a/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts +++ b/packages/api/src/mcp/__tests__/MCPConnectionFactory.oauthSdk.integration.test.ts @@ -313,6 +313,142 @@ describe('MCPConnectionFactory OAuth against real SDK Streamable HTTP server', ( expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(1); }); + it.each([ + { + status: 503, + error: 'temporarily_unavailable', + scope: 'read', + discovery: false, + coordinate: false, + }, + { status: 503, error: 'invalid_client', scope: 'read', discovery: false, coordinate: false }, + { status: 429, error: 'invalid_grant', scope: '', discovery: false, coordinate: false }, + { status: 429, error: 'invalid_scope', scope: 'read', discovery: true, coordinate: true }, + { status: 503, error: 'invalid_client', scope: 'read', discovery: true, coordinate: true }, + { status: 408, error: 'invalid_grant', scope: '', discovery: false, coordinate: true }, + ])( + 'preserves authorization through HTTP $status ($error, discovery=$discovery), then retries without consent', + async ({ status, error, scope, discovery, coordinate }) => { + let unavailable = true; + server = await createOAuthMCPServer({ + issueRefreshTokens: true, + rotateRefreshTokens: true, + requireResourceParameter: true, + refreshFailure: () => + unavailable ? { status, body: JSON.stringify({ error }) } : undefined, + }); + const initial = await issueTokens(server, scope); + await storeTokens(tokenStore, server, { ...initial, expires_at: Date.now() - 1000 }, scope); + const flowManager = createFlowManager(); + const oauthStart = jest.fn(); + const tokenMethods = { + findToken: tokenStore.findToken, + createToken: tokenStore.createToken, + updateToken: tokenStore.updateToken, + deleteTokens: tokenStore.deleteTokens, + }; + const snapshot = () => + Promise.all([ + tokenStore.findToken({ + userId: USER_ID, + type: 'mcp_oauth_refresh', + identifier: `mcp:${SERVER_NAME}:refresh`, + }), + tokenStore.findToken({ + userId: USER_ID, + type: 'mcp_oauth_client', + identifier: `mcp:${SERVER_NAME}:client`, + }), + ]); + const before = await snapshot(); + const basic = { + serverName: SERVER_NAME, + serverConfig: { + type: 'streamable-http' as const, + url: server.url, + initTimeout: 15000, + requiresOAuth: true, + oauthRefreshCoordination: coordinate, + }, + }; + const options = { + useOAuth: true as const, + user: { id: USER_ID } as IUser, + flowManager, + tokenMethods, + oauthStart, + returnOnOAuth: true, + }; + const attempt = () => + discovery + ? MCPConnectionFactory.discoverTools(basic, options) + : MCPConnectionFactory.create(basic, options); + await expect(attempt()).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' }); + expect(oauthStart).not.toHaveBeenCalled(); + expect(await snapshot()).toEqual(before); + expect(server.issuedRefreshTokens.has(initial.refresh_token!)).toBe(true); + expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(1); + + unavailable = false; + const recovered = await attempt(); + connection = 'connection' in recovered ? recovered.connection : recovered; + expect(connection).not.toBeNull(); + expect(await connection!.isConnected()).toBe(true); + expect((await connection!.fetchTools()).some((tool) => tool.name === 'echo')).toBe(true); + expect(oauthStart).not.toHaveBeenCalled(); + expect(server.tokenRequests.filter((r) => r.grantType === 'authorization_code')).toHaveLength( + 1, + ); + expect(server.tokenRequests.filter((r) => r.grantType === 'refresh_token')).toHaveLength(2); + const [rotated] = await snapshot(); + expect(rotated?.token).not.toBe(before[0]?.token); + expect(server.issuedRefreshTokens.has(rotated!.token.replace(/^enc:/, ''))).toBe(true); + }, + ); + + it.each(['invalid_client', 'invalid_grant'])( + 'still requests consent for a permanent HTTP 400 %s', + async (error) => { + server = await createOAuthMCPServer({ + issueRefreshTokens: true, + refreshFailure: () => ({ status: 400, body: JSON.stringify({ error }) }), + }); + const initial = await issueTokens(server); + await storeTokens(tokenStore, server, { ...initial, expires_at: Date.now() - 1000 }); + const oauthStart = jest.fn(); + const flowManager = createFlowManager(); + try { + await expect( + MCPConnectionFactory.create( + { + serverName: SERVER_NAME, + serverConfig: { type: 'streamable-http', url: server.url, requiresOAuth: true }, + }, + { + useOAuth: true, + user: { id: USER_ID } as IUser, + flowManager, + returnOnOAuth: true, + oauthStart, + tokenMethods: { + findToken: tokenStore.findToken, + createToken: tokenStore.createToken, + updateToken: tokenStore.updateToken, + deleteTokens: tokenStore.deleteTokens, + }, + }, + ), + ).rejects.toThrow('OAuth flow initiated'); + expect(oauthStart).toHaveBeenCalledTimes(1); + } finally { + await flowManager.deleteFlow( + MCPOAuthHandler.generateFlowId(USER_ID, SERVER_NAME), + 'mcp_oauth', + ); + } + }, + ); + it('silently refreshes a server-rejected token and reconnects with the MCP resource parameter', async () => { server = await createOAuthMCPServer({ issueRefreshTokens: true, diff --git a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts index e635d9f140..454d7014aa 100644 --- a/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts +++ b/packages/api/src/mcp/__tests__/MCPOAuthTokenStorage.test.ts @@ -1174,6 +1174,47 @@ describe('MCPTokenStorage', () => { ); }); + it.each(['invalid_client', 'invalid_grant', 'invalid_scope', 'unauthorized_client'])( + 'preserves a typed temporary failure even when its message contains %s', + async (serverName) => { + await createBoundToken(store, { + userId: 'u1', + type: 'mcp_oauth', + identifier: 'mcp:srv1', + token: 'enc:expired-token', + expiresIn: -1, + }); + await createBoundToken(store, { + userId: 'u1', + type: 'mcp_oauth_refresh', + identifier: 'mcp:srv1:refresh', + token: 'enc:rt', + expiresIn: 86400, + }); + const failure = new MCPTokenRefreshUnavailableError(serverName, new Error('HTTP 503')); + const deleteTokens = jest.fn(store.deleteTokens); + await expect( + MCPTokenStorage.getTokens({ + userId: 'u1', + serverName: 'srv1', + findToken: store.findToken, + createToken: store.createToken, + updateToken: store.updateToken, + deleteTokens, + refreshTokens: jest.fn().mockRejectedValue(failure), + }), + ).rejects.toBe(failure); + expect(deleteTokens).not.toHaveBeenCalled(); + expect( + await store.findToken({ + userId: 'u1', + type: 'mcp_oauth_refresh', + identifier: 'mcp:srv1:refresh', + }), + ).toMatchObject({ token: 'enc:rt' }); + }, + ); + it('reports transient refresh failures separately from reauthentication', async () => { await createBoundToken(store, { userId: 'u1', diff --git a/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts b/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts index cb80058d6b..5ecc613b15 100644 --- a/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts +++ b/packages/api/src/mcp/__tests__/handler.refreshScope.test.ts @@ -100,6 +100,71 @@ describe('MCPOAuthHandler.refreshOAuthTokens โ€” scope parameter fallback', () = global.fetch = originalFetch; }); + it.each([408, 429, 500, 502, 503, 504])( + 'keeps HTTP %i retryable without reading or logging misleading scope/client errors', + async (status) => { + const cancel = jest.fn().mockResolvedValue(undefined); + const text = jest.fn(async () => 'invalid_client invalid_grant invalid_scope not supported'); + responseQueue = [{ status, ok: false, text, body: { cancel } } as unknown as Response]; + await expect( + MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}), + ).rejects.toMatchObject({ + name: 'MCPTokenRefreshUnavailableError', + cause: { message: `Token refresh temporarily unavailable (HTTP ${status})` }, + }); + expect(sentBodies).toHaveLength(1); + expect(text).not.toHaveBeenCalled(); + expect(cancel).toHaveBeenCalledTimes(1); + }, + ); + + it('keeps an outage after the scope fallback retryable', async () => { + responseQueue = [scopeRejection, new Response('{"error":"invalid_client"}', { status: 503 })]; + await expect( + MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}), + ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' }); + expect(sentBodies).toHaveLength(2); + expect(sentBodies[1]).not.toContain('scope='); + }); + + it('keeps an outage retryable even when cancelling its response stream fails', async () => { + responseQueue = [ + { + status: 503, + body: { + cancel: async () => { + throw new Error('invalid_client'); + }, + }, + } as unknown as Response, + ]; + await expect( + MCPOAuthHandler.refreshOAuthTokens(refreshToken, metadata, {}, {}), + ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' }); + }); + + it.each(['configured', 'discovered'] as const)( + 'preserves outage status in the %s refresh path', + async (mode) => { + responseQueue = [new Response('{"error":"invalid_grant"}', { status: 503 })]; + await expect( + MCPOAuthHandler.refreshOAuthTokens( + refreshToken, + { serverName: metadata.serverName, serverUrl: metadata.serverUrl }, + {}, + mode === 'configured' + ? { + token_url: discovered.token_endpoint, + client_id: 'configured-client', + scope: 'read', + } + : {}, + ), + ).rejects.toMatchObject({ name: 'MCPTokenRefreshUnavailableError' }); + expect(sentBodies).toHaveLength(1); + }, + ); + it('retries without scope when the server rejects the scope parameter, then succeeds', async () => { responseQueue = [scopeRejection, success]; diff --git a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts index 422fda3911..5975b678c3 100644 --- a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts +++ b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts @@ -72,6 +72,8 @@ export interface OAuthTestServerOptions { requireResourceParameter?: boolean; /** Number of refresh-grant access tokens the MCP resource should reject after issuance. */ rejectRefreshTokens?: number; + /** Injects an endpoint failure before redemption; undefined resumes normal refresh behavior. */ + refreshFailure?: () => { status: number; body: string } | undefined; /** Optional test hook for controlling echo-tool completion. */ echoHandler?: (message: string) => string | Promise; } @@ -142,6 +144,7 @@ export async function createOAuthMCPServer( requireResourceParameter = false, rejectRefreshTokens = 0, echoHandler, + refreshFailure, } = options; const sessions = new Map(); @@ -397,6 +400,13 @@ export async function createOAuthMCPServer( } if (grantType === 'refresh_token' && issueRefreshTokens) { + const failure = refreshFailure?.(); + if (failure) { + res.writeHead(failure.status, { 'Content-Type': 'application/json' }); + res.end(failure.body); + return; + } + const refreshToken = params.get('refresh_token'); if (!refreshToken || !issuedRefreshTokens.has(refreshToken)) { res.writeHead(400, { 'Content-Type': 'application/json' }); diff --git a/packages/api/src/mcp/oauth/handler.ts b/packages/api/src/mcp/oauth/handler.ts index 6dcf8a5653..3123163cdf 100644 --- a/packages/api/src/mcp/oauth/handler.ts +++ b/packages/api/src/mcp/oauth/handler.ts @@ -33,10 +33,10 @@ import { inferClientAuthMethod, } from './methods'; import { isSSRFTarget, resolveHostnameSSRF, isOAuthUrlAllowed } from '~/auth'; +import { MCPTokenStorage, MCPTokenRefreshUnavailableError } from './tokens'; import { probeResourceMetadataHint } from './resourceHint'; import { createHardenedOAuthFetch } from './hardenedFetch'; import { sanitizeUrlForLogging } from '~/mcp/utils'; -import { MCPTokenStorage } from './tokens'; import { getOAuthUrlPort } from './url'; /** Type for the OAuth metadata from the SDK */ @@ -1720,6 +1720,23 @@ export class MCPOAuthHandler { } as MCPOAuthTokens; } + /** HTTP outage/rate-limit status is authoritative, even if a proxy body names a bad grant. */ + private static async assertRefreshEndpointAvailable( + response: Response, + serverName: string, + ): Promise { + if (!(response.status === 408 || response.status === 429 || response.status >= 500)) { + return; + } + // Do not feed an outage body into the legacy invalid_client/invalid_grant message classifiers, + // or log provider-controlled text that may contain credentials. No automatic redemption retry. + await response.body?.cancel().catch(() => undefined); + throw new MCPTokenRefreshUnavailableError( + serverName, + new Error(`Token refresh temporarily unavailable (HTTP ${response.status})`), + ); + } + /** * Posts a `refresh_token` grant, transparently retrying without the `scope` * parameter when โ€” and only when โ€” the authorization server rejects the request @@ -1747,6 +1764,7 @@ export class MCPOAuthHandler { serverName, ); const response = await oauthFetch(tokenUrl, { method: 'POST', headers, body, signal }); + await this.assertRefreshEndpointAvailable(response, serverName); if (response.ok || !body.has('scope')) { return response; } @@ -1763,7 +1781,9 @@ export class MCPOAuthHandler { `[MCPOAuth] ${serverName} rejected the scope parameter on token refresh (HTTP ${response.status}); retrying without scope per RFC 6749 ยง6`, ); body.delete('scope'); - return oauthFetch(tokenUrl, { method: 'POST', headers, body, signal }); + const retried = await oauthFetch(tokenUrl, { method: 'POST', headers, body, signal }); + await this.assertRefreshEndpointAvailable(retried, serverName); + return retried; } /** @@ -2185,6 +2205,7 @@ export class MCPOAuthHandler { }, ); + await this.assertRefreshEndpointAvailable(response, metadata.serverName); if (!response.ok) { const errorText = await response.text(); throw new Error( diff --git a/packages/api/src/mcp/oauth/tokens.ts b/packages/api/src/mcp/oauth/tokens.ts index be0fbf6357..ce58734728 100644 --- a/packages/api/src/mcp/oauth/tokens.ts +++ b/packages/api/src/mcp/oauth/tokens.ts @@ -1658,6 +1658,9 @@ export class MCPTokenStorage { try { newTokens = await refreshTokens(decryptedRefreshToken, metadata, signal); } catch (error) { + if (error instanceof MCPTokenRefreshUnavailableError) { + throw error; + } // These endpoint responses reject the refresh request permanently; a new grant can recover. // Classify only provider failures here, never a similarly worded persistence failure. const message = error instanceof Error ? error.message : String(error); @@ -1743,7 +1746,10 @@ export class MCPTokenStorage { return storedTokens; } catch (refreshError) { logger.error(`${logPrefix} Failed to refresh tokens`, refreshError); - if (refreshError instanceof ReauthenticationRequiredError) { + if ( + refreshError instanceof ReauthenticationRequiredError || + refreshError instanceof MCPTokenRefreshUnavailableError + ) { throw refreshError; } if (