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
🥊 test: Prove MCP Refresh Coordination Across Replica Processes (#16131)
lia-by-librechat[bot]1ff694b3985b
diff --git a/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.tsnew file mode 100644index 0000000000..373bd7a626--- /dev/null+++ b/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts@@ -0,0 +1,445 @@+/**+ * MCP OAuth guarantees that only a multi-process deployment can establish.+ *+ * Existing coverage runs two instances inside one Jest process, where a process-local single-flight+ * map can satisfy an assertion production cannot: real replicas share only Redis, Mongo and the+ * provider. These tests therefore fork REAL worker processes (`helpers/mcpOAuthWorkerBoot.cjs`) that+ * use the production adapters, and assert the outcomes a user experiences: one redemption per+ * rotation, an adopted result on the peer, and recovery after a replica dies.+ *+ * The negative control matters as much as the positive one. With coordination disabled the same+ * harness must produce TWO redemptions while the provider holds the first response open; without+ * that, a passing coordinated run could simply mean the workers never overlapped.+ */++import path from 'path';+import mongoose from 'mongoose';+import { randomUUID } from 'crypto';+import { fork } from 'child_process';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type { ChildProcess } from 'child_process';+import type { OAuthTestServer } from './helpers/oauthTestServer';+import { createOAuthMCPServer } from './helpers/oauthTestServer';++const WORKER_BOOT = path.join(__dirname, 'helpers', 'mcpOAuthWorkerBoot.cjs');+const CLIENT_ID = 'librechat-multiprocess-harness';+/** Test-only material; the worker encrypts with the production helpers, which require both. */+const CREDS_KEY = 'a'.repeat(64);+const CREDS_IV = 'b'.repeat(32);+const BOOT_TIMEOUT_MS = 60_000;+const SETTLE_MS = 750;++interface WorkerReply {+ id: number;+ ok: boolean;+ result?: unknown;+ /** Errors cross IPC as plain data; Error instances do not survive structured cloning. */+ error?: { name?: string; message?: string; stack?: string };+}++interface TokenOutcome {+ obtained: boolean;+ /** Which side of the coordination this replica took, from `getTokens`' own hooks. */+ role: 'refreshed' | 'adopted' | null;+ expiredAtEntry?: boolean;+ resourceStatus: number | null;+ refreshDigest: string | null;+ credentialSetId?: string | null;+}++/** One replica: a real child process speaking a small request/response protocol over IPC. */+class ReplicaProcess {+ private readonly pending = new Map<+ number,+ { resolve: (value: unknown) => void; reject: (error: Error) => void }+ >();++ private nextId = 1;+ private exited = false;+ /** Unsolicited worker notifications, used to establish overlap instead of assuming it. */+ public readonly progress: string[] = [];++ private constructor(+ public readonly name: string,+ private readonly child: ChildProcess,+ private readonly stderr: string[],+ ) {+ child.on('message', (message) => {+ const notification = message as { progress?: string };+ if (notification.progress) {+ this.progress.push(notification.progress);+ return;+ }+ const reply = message as WorkerReply;+ const waiter = this.pending.get(reply.id);+ if (!waiter) {+ return;+ }+ this.pending.delete(reply.id);+ if (reply.ok) {+ waiter.resolve(reply.result);+ } else {+ const failure = new Error(`[${name}] ${reply.error?.message ?? 'worker command failed'}`);+ failure.name = reply.error?.name ?? 'Error';+ if (reply.error?.stack) {+ failure.stack = `${failure.name}: ${failure.message}\n${reply.error.stack}`;+ }+ waiter.reject(failure);+ }+ });+ child.on('exit', (code, signal) => {+ this.exited = true;+ const reason = `[${name}] exited (code ${code ?? 'null'}, signal ${signal ?? 'null'})`;+ for (const waiter of this.pending.values()) {+ waiter.reject(new Error(reason));+ }+ this.pending.clear();+ });+ }++ static async start(options: {+ name: string;+ mongoUri: string;+ providerUrl: string;+ userId: string;+ serverName: string;+ flowNamespace: string;+ coordinate: boolean;+ }): Promise<ReplicaProcess> {+ const child = fork(WORKER_BOOT, [], {+ stdio: ['ignore', 'pipe', 'pipe', 'ipc'],+ env: {+ ...process.env,+ NODE_ENV: 'test',+ USE_REDIS: 'true',+ CREDS_KEY,+ CREDS_IV,+ MCP_TEST_MONGO_URI: options.mongoUri,+ MCP_TEST_PROVIDER_URL: options.providerUrl,+ MCP_TEST_USER_ID: options.userId,+ MCP_TEST_SERVER_NAME: options.serverName,+ MCP_TEST_CLIENT_ID: CLIENT_ID,+ MCP_TEST_FLOW_NAMESPACE: options.flowNamespace,+ MCP_TEST_COORDINATE: String(options.coordinate),+ },+ });++ /** Keep worker stderr; silence is what makes a process harness hard to debug. */+ const stderr: string[] = [];+ child.stderr?.on('data', (chunk) => stderr.push(String(chunk)));+ child.stdout?.resume();++ const replica = new ReplicaProcess(options.name, child, stderr);+ try {+ await new Promise<void>((resolve, reject) => {+ const timer = setTimeout(() => {+ reject(+ new Error(+ `[${options.name}] not ready in ${BOOT_TIMEOUT_MS}ms. stderr: ${stderr.join('').slice(-2000)}`,+ ),+ );+ }, BOOT_TIMEOUT_MS);+ child.once('message', (message) => {+ clearTimeout(timer);+ if ((message as { ready?: boolean }).ready) {+ resolve();+ } else {+ reject(+ new Error(+ `[${options.name}] failed to initialize: ${(message as { error?: { message?: string } }).error?.message ?? 'no ready signal'}`,+ ),+ );+ }+ });+ child.once('exit', () => {+ clearTimeout(timer);+ reject(+ new Error(+ `[${options.name}] exited during boot. stderr: ${stderr.join('').slice(-2000)}`,+ ),+ );+ });+ });+ } catch (error) {+ /**+ * A worker that never reported ready is still running, holding Mongo and Redis connections+ * that would outlive this suite and interfere with the rest of the integration lane. Reap it+ * before surfacing the boot failure.+ */+ await replica.kill();+ throw error;+ }+ return replica;+ }++ send<T = unknown>(command: string, payload?: Record<string, unknown>): Promise<T> {+ if (this.exited) {+ return Promise.reject(new Error(`[${this.name}] is no longer running`));+ }+ const id = this.nextId++;+ return new Promise<T>((resolve, reject) => {+ this.pending.set(id, {+ resolve: resolve as (value: unknown) => void,+ reject,+ });+ this.child.send({ id, command, payload });+ });+ }++ /** Terminates without shutdown, standing in for a replica that dies mid-operation. */+ async kill(): Promise<void> {+ if (this.exited) {+ return;+ }+ const stopped = new Promise<void>((resolve) => this.child.once('exit', () => resolve()));+ this.child.kill('SIGKILL');+ await stopped;+ }++ async stop(): Promise<void> {+ if (this.exited) {+ return;+ }+ await this.send('shutdown').catch(() => undefined);+ const stopped = new Promise<void>((resolve) => this.child.once('exit', () => resolve()));+ this.child.kill('SIGTERM');+ await stopped;+ }+}++async function waitFor(+ condition: () => boolean,+ description: string,+ timeoutMs = 20_000,+): Promise<void> {+ const deadline = Date.now() + timeoutMs;+ while (!condition()) {+ if (Date.now() > deadline) {+ throw new Error(`Timed out waiting for ${description}`);+ }+ await new Promise((resolve) => setTimeout(resolve, 25));+ }+}++const describeWithRedis = process.env.REDIS_URI ? describe : describe.skip;++describeWithRedis('MCP OAuth credential lifecycle across separate replica processes', () => {+ let mongod: MongoMemoryServer;+ let server: OAuthTestServer;+ const replicas: ReplicaProcess[] = [];+ let holdRefresh = false;+ let releaseRefresh: (() => void) | undefined;+ let gatePromise: Promise<void> | undefined;++ const refreshGrants = () =>+ server.tokenRequests.filter((request) => request.grantType === 'refresh_token').length;+ const consentGrants = () =>+ server.tokenRequests.filter((request) => request.grantType === 'authorization_code').length;++ beforeAll(async () => {+ /**+ * `--nounixsocket` keeps mongod off its hardcoded /tmp socket path, which a read-only root+ * filesystem rejects with an opaque fassert failure. It changes nothing about the server.+ */+ mongod = await MongoMemoryServer.create({ instance: { args: ['--nounixsocket'] } });+ }, BOOT_TIMEOUT_MS);++ afterAll(async () => {+ await mongod?.stop();+ });++ beforeEach(async () => {+ holdRefresh = false;+ gatePromise = new Promise<void>((resolve) => {+ releaseRefresh = resolve;+ });+ server = await createOAuthMCPServer({+ issueRefreshTokens: true,+ rotateRefreshTokens: true,+ refreshGate: () => (holdRefresh ? gatePromise : undefined),+ });+ });++ afterEach(async () => {+ releaseRefresh?.();+ await Promise.all(replicas.splice(0).map((replica) => replica.stop()));+ await server?.close();+ });++ /** Each scenario owns its principal, server name and flow namespace, so state never bleeds. */+ const scenario = () => {+ const suffix = randomUUID().slice(0, 8);+ return {+ userId: new mongoose.Types.ObjectId().toString(),+ serverName: `multiprocess-server-${suffix}`,+ flowNamespace: `MCPOAuthMultiProcess-${process.pid}-${suffix}`,+ };+ };++ const startReplica = async (+ name: string,+ context: ReturnType<typeof scenario>,+ coordinate: boolean,+ ): Promise<ReplicaProcess> => {+ const replica = await ReplicaProcess.start({+ name,+ mongoUri: mongod.getUri(),+ providerUrl: server.url,+ coordinate,+ ...context,+ });+ replicas.push(replica);+ return replica;+ };++ it(+ 'redeems a rotating refresh token once when both replicas refresh together',+ async () => {+ const context = scenario();+ const [replicaA, replicaB] = await Promise.all([+ startReplica('replica-A', context, true),+ startReplica('replica-B', context, true),+ ]);++ await replicaA.send('authorize');+ await replicaA.send('expireAccess');+ expect(consentGrants()).toBe(1);++ /** Hold the provider's response so the two reads genuinely overlap. */+ holdRefresh = true;+ const readA = replicaA.send<TokenOutcome>('getTokens');+ const readB = replicaB.send<TokenOutcome>('getTokens');++ /**+ * Establish the overlap before releasing anything. Waiting only for a provider hit would let+ * a slow peer arrive after the winner had already persisted, read a fresh credential, and+ * never contend: the redemption count would still be 1 and the assertion would pass while+ * proving nothing. Both replicas must have entered the refresh path on an expired credential.+ */+ await waitFor(() => refreshGrants() >= 1, 'the first replica to reach the provider');+ await waitFor(+ () => replicaA.progress.includes('entered-refresh-path'),+ 'replica A to enter the refresh path',+ );+ await waitFor(+ () => replicaB.progress.includes('entered-refresh-path'),+ 'replica B to enter the refresh path',+ );+ /** The peer must wait for the winner, not start a second redemption of the same token. */+ await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));+ expect(refreshGrants()).toBe(1);++ releaseRefresh?.();+ const [outcomeA, outcomeB] = await Promise.all([readA, readB]);++ expect(outcomeA.obtained).toBe(true);+ expect(outcomeB.obtained).toBe(true);+ /** Both saw an expired credential, so neither read was a cache hit on a fresh token. */+ expect(outcomeA.expiredAtEntry).toBe(true);+ expect(outcomeB.expiredAtEntry).toBe(true);+ /**+ * `getTokens` reports which side each replica took. Exactly one redeemed and the other+ * adopted what it published: that pair is the coordination itself, and it cannot be produced+ * by a replica that merely arrived late and loaded an already-valid credential.+ */+ expect([outcomeA.role, outcomeB.role].sort()).toEqual(['adopted', 'refreshed']);+ /** Both replicas hold a credential the resource server accepts. */+ expect(outcomeA.resourceStatus).toBe(200);+ expect(outcomeB.resourceStatus).toBe(200);+ /** Both converged on one rotated credential, and consent was never requested again. */+ expect(outcomeB.refreshDigest).toBe(outcomeA.refreshDigest);+ expect(refreshGrants()).toBe(1);+ expect(consentGrants()).toBe(1);++ /**+ * The rotation that was actually persisted has to be the one the provider now expects, so a+ * later cycle must succeed. A lost replacement would only surface here.+ */+ await replicaB.send('expireAccess');+ const nextCycle = await replicaB.send<TokenOutcome>('getTokens');+ expect(nextCycle.obtained).toBe(true);+ expect(nextCycle.resourceStatus).toBe(200);+ expect(nextCycle.refreshDigest).not.toBe(outcomeA.refreshDigest);+ expect(refreshGrants()).toBe(2);+ expect(consentGrants()).toBe(1);+ },+ BOOT_TIMEOUT_MS * 2,+ );++ it(+ 'observes two redemptions without coordination, proving the replicas truly overlap',+ async () => {+ const context = scenario();+ const [replicaA, replicaB] = await Promise.all([+ startReplica('replica-A', context, false),+ startReplica('replica-B', context, false),+ ]);++ await replicaA.send('authorize');+ await replicaA.send('expireAccess');++ holdRefresh = true;+ const readA = replicaA.send<TokenOutcome>('getTokens').catch(() => null);+ const readB = replicaB.send<TokenOutcome>('getTokens').catch(() => null);++ /**+ * This is the control for the test above: uncoordinated replicas reach the provider twice+ * while the first response is still open. If this ever stops happening, the coordinated+ * assertion is no longer evidence of coordination.+ */+ await waitFor(+ () => replicaA.progress.includes('entered-refresh-path'),+ 'replica A to enter the refresh path',+ );+ await waitFor(+ () => replicaB.progress.includes('entered-refresh-path'),+ 'replica B to enter the refresh path',+ );+ await waitFor(+ () => refreshGrants() >= 2,+ 'both uncoordinated replicas to reach the provider',+ );+ expect(refreshGrants()).toBe(2);++ releaseRefresh?.();+ await Promise.all([readA, readB]);+ },+ BOOT_TIMEOUT_MS * 2,+ );++ it(+ 'recovers on a replacement replica after the authorizing replica is killed',+ async () => {+ const context = scenario();+ const original = await startReplica('replica-original', context, true);++ await original.send('authorize');+ await original.send('expireAccess');+ const rotated = await original.send<TokenOutcome>('getTokens');+ expect(rotated.obtained).toBe(true);+ expect(refreshGrants()).toBe(1);++ /** No graceful shutdown: nothing in memory survives, only what was persisted. */+ await original.kill();++ const replacement = await startReplica('replica-replacement', context, true);+ /** The durable claim: credentials outlived the process that obtained them. */+ const restored = await replacement.send<TokenOutcome & { hasClient: boolean }>('readStored');+ expect(restored.obtained).toBe(true);+ expect(restored.hasClient).toBe(true);+ expect(restored.refreshDigest).toEqual(expect.any(String));+ expect(restored.credentialSetId).toEqual(expect.any(String));++ await replacement.send('expireAccess');+ const afterRestart = await replacement.send<TokenOutcome>('getTokens');++ /** Recovery came from durable credentials alone: still one consent for the whole scenario. */+ expect(afterRestart.obtained).toBe(true);+ expect(afterRestart.resourceStatus).toBe(200);+ expect(afterRestart.refreshDigest).not.toBe(rotated.refreshDigest);+ expect(refreshGrants()).toBe(2);+ expect(consentGrants()).toBe(1);+ },+ BOOT_TIMEOUT_MS * 2,+ );+});diff --git a/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjsnew file mode 100644index 0000000000..b3a2172ec9--- /dev/null+++ b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs@@ -0,0 +1,32 @@+'use strict';++/**+ * Bootstrap for the MCP OAuth multi-process harness.+ *+ * The worker must be a REAL separate process, not a second in-process instance: process-local+ * single-flight maps, connection caches and module state would otherwise satisfy a cross-replica+ * assertion that production cannot satisfy. Jest's transform is unavailable outside the test+ * process, so compile the TypeScript worker with ts-node and resolve the package's `~/*` alias+ * the same way tsconfig.json declares it.+ *+ * Nothing here fakes a production adapter. Mongo, Redis, encryption and the OAuth handler are the+ * real implementations; only the provider and the stores are test-owned.+ */++const path = require('path');++const apiRoot = path.resolve(__dirname, '../../../..');++require('ts-node').register({+ transpileOnly: true,+ esm: false,+ project: path.join(apiRoot, 'tsconfig.json'),+ compilerOptions: { module: 'commonjs', moduleResolution: 'node' },+});++require('tsconfig-paths').register({+ baseUrl: apiRoot,+ paths: { '~/*': ['./src/*'] },+});++require('./mcpOAuthWorkerMain.ts');diff --git a/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.tsnew file mode 100644index 0000000000..e17815df00--- /dev/null+++ b/packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts@@ -0,0 +1,334 @@+/**+ * One replica of the MCP OAuth multi-process harness.+ *+ * Runs in its own process with production adapters: a real Mongo connection and the real token+ * methods (so credentials are encrypted and persisted exactly as deployed), a real Redis-backed+ * `FlowStateManager` (so refresh coordination and the persistence fence are distributed rather+ * than process-local), and the real `MCPTokenStorage` / `MCPOAuthHandler`. Only the OAuth provider+ * and the stores are test-owned.+ *+ * Secrets never leave this process: the parent receives digests and HTTP statuses, never a token.+ */++import mongoose from 'mongoose';+import { createHash } from 'crypto';+import { createMethods, createModels, decryptV2 } from '@librechat/data-schemas';+import type { TokenMethods } from '@librechat/data-schemas';+import type {+ MCPOAuthTokens,+ OAuthClientInformation,+ OAuthStoredClientMetadata,+} from '~/mcp/oauth';+import { MCPOAuthHandler, MCPTokenStorage } from '~/mcp/oauth';+import { standardCache } from '~/cache/cacheFactory';+import { FlowStateManager } from '~/flow/manager';++interface WorkerRequest {+ id: number;+ command: string;+ payload?: Record<string, unknown>;+}++const env = (name: string): string => {+ const value = process.env[name];+ if (!value) {+ throw new Error(`Worker requires ${name}`);+ }+ return value;+};++const providerUrl = env('MCP_TEST_PROVIDER_URL');+const userId = env('MCP_TEST_USER_ID');+const serverName = env('MCP_TEST_SERVER_NAME');+const clientId = env('MCP_TEST_CLIENT_ID');+const flowNamespace = env('MCP_TEST_FLOW_NAMESPACE');+const coordinateRefresh = process.env.MCP_TEST_COORDINATE === 'true';+/** The provider listens on loopback, which the SSRF gate blocks unless explicitly allowed. */+const allowedAddresses = [new URL(providerUrl).host];+const identifier = `mcp:${serverName}`;++let tokenMethods: TokenMethods;+let flowManager: FlowStateManager<MCPOAuthTokens | null>;++/** Digest so the parent can compare rotation without a credential crossing the IPC channel. */+const digest = (value: string): string =>+ createHash('sha256').update(value).digest('hex').slice(0, 16);++const clientInfo: OAuthClientInformation = {+ client_id: clientId,+ redirect_uris: ['http://localhost'],+ grant_types: ['authorization_code', 'refresh_token'],+ response_types: ['code'],+ token_endpoint_auth_method: 'none',+};++const storedMetadata = (): OAuthStoredClientMetadata =>+ ({+ issuer: providerUrl.replace(/\/$/, ''),+ authorization_endpoint: new URL('authorize', providerUrl).href,+ token_endpoint: new URL('token', providerUrl).href,+ response_types_supported: ['code'],+ grant_types_supported: ['authorization_code', 'refresh_token'],+ token_endpoint_auth_methods_supported: ['none'],+ server_url: providerUrl,+ client_source: 'dynamic',+ }) as OAuthStoredClientMetadata;++async function init(): Promise<void> {+ createModels(mongoose);+ tokenMethods = createMethods(mongoose) as unknown as TokenMethods;+ await mongoose.connect(env('MCP_TEST_MONGO_URI'), { autoIndex: false });+ flowManager = new FlowStateManager<MCPOAuthTokens | null>(standardCache(flowNamespace, 60_000), {+ ttl: 60_000,+ });+}++/** Completes a real authorization-code grant against the provider. */+async function exchangeAuthorizationCode(): Promise<MCPOAuthTokens> {+ const authUrl = new URL('authorize', providerUrl);+ authUrl.searchParams.set('redirect_uri', 'http://localhost');+ authUrl.searchParams.set('state', `multiprocess-${process.pid}`);+ authUrl.searchParams.set('client_id', clientId);++ const authResponse = await fetch(authUrl, { redirect: 'manual' });+ const location = authResponse.headers.get('location');+ if (!location) {+ throw new Error(`Authorization failed with HTTP ${authResponse.status}`);+ }+ const code = new URL(location).searchParams.get('code');+ if (!code) {+ throw new Error('Authorization response carried no code');+ }++ const tokenResponse = await fetch(new URL('token', providerUrl), {+ method: 'POST',+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },+ body: new URLSearchParams({+ grant_type: 'authorization_code',+ code,+ client_id: clientId,+ }),+ });+ if (!tokenResponse.ok) {+ throw new Error(`Token exchange failed with HTTP ${tokenResponse.status}`);+ }+ const body = (await tokenResponse.json()) as {+ access_token: string;+ token_type: string;+ expires_in: number;+ refresh_token?: string;+ };+ return {+ ...body,+ obtained_at: Date.now(),+ expires_at: Date.now() + body.expires_in * 1000,+ } as MCPOAuthTokens;+}++/** Proves a credential is accepted by the protected resource, without revealing it. */+async function probeResource(accessToken: string): Promise<number> {+ const response = await fetch(providerUrl, {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ Accept: 'application/json, text/event-stream',+ Authorization: `Bearer ${accessToken}`,+ },+ body: JSON.stringify({+ jsonrpc: '2.0',+ id: 1,+ method: 'initialize',+ params: {+ protocolVersion: '2025-03-26',+ capabilities: {},+ clientInfo: { name: 'multiprocess-harness', version: '0.0.1' },+ },+ }),+ });+ return response.status;+}++/** Token metadata is a Mongoose Map on a hydrated document and a plain object once lean. */+function readCredentialSetId(record: { metadata?: unknown } | null): string | null {+ const metadata = record?.metadata as Map<string, unknown> | Record<string, unknown> | undefined;+ if (!metadata) {+ return null;+ }+ const value =+ metadata instanceof Map+ ? metadata.get('credential_set_id')+ : (metadata as Record<string, unknown>).credential_set_id;+ return typeof value === 'string' && value.length > 0 ? value : null;+}++/** Digest of the persisted refresh credential, so the parent can observe rotation. */+async function storedRefreshDigest(): Promise<string | null> {+ const record = await tokenMethods.findToken({+ userId,+ type: 'mcp_oauth_refresh',+ identifier: `${identifier}:refresh`,+ });+ return record ? digest(await decryptV2(record.token)) : null;+}++const commands: Record<string, (payload: Record<string, unknown>) => Promise<unknown>> = {+ /** Interactive authorization, persisted through the production storage path. */+ async authorize() {+ const tokens = await exchangeAuthorizationCode();+ const stored = await MCPTokenStorage.storeTokens({+ userId,+ serverName,+ tokens,+ createToken: tokenMethods.createToken,+ updateToken: tokenMethods.updateToken,+ deleteTokens: tokenMethods.deleteTokens,+ findToken: tokenMethods.findToken,+ clientInfo,+ metadata: storedMetadata(),+ flowManager,+ });+ return { credentialSetId: stored.credential_set_id };+ },++ /** Ages the stored access record so the next read must refresh, as elapsed time would. */+ async expireAccess() {+ await tokenMethods.updateToken({ userId, type: 'mcp_oauth', identifier }, { expiresIn: -60 });+ return { expired: true };+ },++ /** The production read path: refresh when expired, coordinating across replicas. */+ async getTokens() {+ /**+ * Confirm the credential this replica is about to read is actually expired, then tell the+ * parent. A concurrency assertion that only counts provider hits can pass vacuously when one+ * replica arrives after the winner already persisted: it would simply load a fresh token and+ * never contend. The parent waits for this signal from BOTH replicas before releasing the+ * provider, so the overlap is established rather than assumed from a fixed delay.+ */+ const accessBefore = await tokenMethods.findToken({ userId, type: 'mcp_oauth', identifier });+ const expiredAtEntry =+ accessBefore?.expiresAt != null && new Date() >= new Date(accessBefore.expiresAt);+ process.send?.({ progress: 'entered-refresh-path', expiredAtEntry });++ /**+ * `getTokens` invokes exactly one of these per call, so they report which side of the+ * coordination this replica took: the redeemer, or a peer adopting what the redeemer+ * published. Asserting the pair is what makes the test non-vacuous regardless of timing.+ */+ let role: 'refreshed' | 'adopted' | null = null;++ const tokens = await MCPTokenStorage.getTokens({+ userId,+ serverName,+ onRefreshSuccess: async () => {+ role = 'refreshed';+ },+ onTokensAdopted: async () => {+ role = 'adopted';+ },+ findToken: tokenMethods.findToken,+ createToken: tokenMethods.createToken,+ updateToken: tokenMethods.updateToken,+ deleteTokens: tokenMethods.deleteTokens,+ coordinateRefresh,+ flowManager,+ refreshTokens: async (refreshToken, metadata, signal) =>+ MCPOAuthHandler.refreshOAuthTokens(+ refreshToken,+ {+ serverName: metadata.serverName,+ serverUrl: metadata.storedServerUrl ?? providerUrl,+ clientInfo: metadata.clientInfo,+ storedTokenEndpoint: metadata.storedTokenEndpoint,+ storedAuthMethods: metadata.storedAuthMethods,+ storedServerUrl: metadata.storedServerUrl,+ clientSource: metadata.clientSource,+ resource: metadata.resource,+ },+ {},+ undefined,+ null,+ allowedAddresses,+ signal,+ ),+ });+ if (!tokens) {+ return {+ obtained: false,+ role,+ expiredAtEntry,+ resourceStatus: null,+ refreshDigest: await storedRefreshDigest(),+ };+ }+ return {+ obtained: true,+ role,+ expiredAtEntry,+ accessDigest: digest(tokens.access_token),+ credentialSetId: tokens.credential_set_id ?? null,+ /** Proves the credential is accepted by the protected resource, not merely non-null. */+ resourceStatus: await probeResource(tokens.access_token),+ refreshDigest: await storedRefreshDigest(),+ };+ },++ /** Persisted-state digests, so the parent can assert rotation and survival. */+ async readStored() {+ const [access, refresh, client] = await Promise.all([+ tokenMethods.findToken({ userId, type: 'mcp_oauth', identifier }),+ tokenMethods.findToken({+ userId,+ type: 'mcp_oauth_refresh',+ identifier: `${identifier}:refresh`,+ }),+ tokenMethods.findToken({+ userId,+ type: 'mcp_oauth_client',+ identifier: `${identifier}:client`,+ }),+ ]);+ return {+ obtained: access != null,+ accessDigest: access ? digest(await decryptV2(access.token)) : null,+ refreshDigest: refresh ? digest(await decryptV2(refresh.token)) : null,+ credentialSetId: readCredentialSetId(access) ?? readCredentialSetId(client),+ hasClient: client != null,+ role: null,+ resourceStatus: null,+ };+ },+};++process.on('message', (raw: unknown) => {+ const request = raw as WorkerRequest;+ void (async () => {+ try {+ const handler = commands[request.command];+ if (!handler) {+ throw new Error(`Unknown worker command: ${request.command}`);+ }+ const result = await handler(request.payload ?? {});+ process.send?.({ id: request.id, ok: true, result });+ } catch (error) {+ process.send?.({+ id: request.id,+ ok: false,+ error: {+ name: error instanceof Error ? error.name : 'Error',+ message: error instanceof Error ? error.message : String(error),+ stack: error instanceof Error ? error.stack : undefined,+ },+ });+ }+ })();+});++void init().then(+ () => process.send?.({ ready: true, pid: process.pid }),+ (error: unknown) =>+ process.send?.({+ ready: false,+ error: { message: error instanceof Error ? error.message : String(error) },+ }),+);diff --git a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.tsindex 5975b678c3..3956ea2fa9 100644--- a/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts+++ b/packages/api/src/mcp/__tests__/helpers/oauthTestServer.ts@@ -74,6 +74,11 @@ export interface OAuthTestServerOptions {rejectRefreshTokens?: number;/** Injects an endpoint failure before redemption; undefined resumes normal refresh behavior. */refreshFailure?: () => { status: number; body: string } | undefined;+ /**+ * Awaited after a refresh grant is recorded but before it is redeemed, so a test can hold+ * concurrent refreshes open and observe how many redemptions the callers actually attempt.+ */+ refreshGate?: () => Promise<void> | undefined;/** Optional test hook for controlling echo-tool completion. */echoHandler?: (message: string) => string | Promise<string>;}@@ -145,6 +150,7 @@ export async function createOAuthMCPServer(rejectRefreshTokens = 0,echoHandler,refreshFailure,+ refreshGate,} = options;const sessions = new Map<string, StreamableHTTPServerTransport>();@@ -400,6 +406,7 @@ export async function createOAuthMCPServer(}if (grantType === 'refresh_token' && issueRefreshTokens) {+ await refreshGate?.();const failure = refreshFailure?.();if (failure) {res.writeHead(failure.status, { 'Content-Type': 'application/json' });