☔ fix: Preserve MCP Authorization During Token Endpoint Outages (#16126)
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions

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 <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-20 08:28:14 -04:00 • committed by GitHub
parent d281c31d54
commit ceecedaf7a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 347 additions and 3 deletions

View file

@ -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<T>() {
}
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 }) => (
<Provider>
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
</Provider>
);
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 }) => (

View file

@ -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,

View file

@ -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',

View file

@ -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];

View file

@ -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<string>;
}
@ -142,6 +144,7 @@ export async function createOAuthMCPServer(
requireResourceParameter = false,
rejectRefreshTokens = 0,
echoHandler,
refreshFailure,
} = options;
const sessions = new Map<string, StreamableHTTPServerTransport>();
@ -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' });

View file

@ -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<void> {
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(

View file

@ -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 (