From 1ff694b3985b22b8f584b47ebcb8f2fa69ee58a8 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 10:29:53 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=A5=8A=20test:=20Prove=20MCP=20Refresh=20?= =?UTF-8?q?Coordination=20Across=20Replica=20Processes=20(#16131)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🥊 test: Prove MCP Refresh Coordination Across Replica Processes Fork real replica processes with production Mongo, Redis, encryption and OAuth adapters, and assert one redemption per rotation, peer adoption, and recovery after the authorizing replica is killed. A negative control with coordination disabled observes two redemptions, so a green coordinated run cannot pass on timing alone. Adds a refreshGate hook to the shared OAuth test provider so concurrent refreshes can be held open. No production code changes. * test: Establish Replica Overlap Instead of Assuming It The coordinated assertion counted provider redemptions after a fixed delay, so a peer that arrived once the winner had already persisted would read a fresh credential, never contend, and still leave one redemption: the test would have passed while proving nothing. Both replicas now report entering the refresh path on a credential they observed expired, and getTokens own onRefreshSuccess/onTokensAdopted hooks report which side each took, so the pair (one redeemed, one adopted) is asserted rather than inferred from timing. A worker that never signalled ready was also left running with live Mongo and Redis connections, which would outlive the suite and disturb the rest of the integration lane; boot failures now reap the child and report the workers own initialization error. --------- Co-authored-by: Lia --- .../MCPOAuthMultiProcess.integration.test.ts | 445 ++++++++++++++++++ .../__tests__/helpers/mcpOAuthWorkerBoot.cjs | 32 ++ .../__tests__/helpers/mcpOAuthWorkerMain.ts | 334 +++++++++++++ .../mcp/__tests__/helpers/oauthTestServer.ts | 7 + 4 files changed, 818 insertions(+) create mode 100644 packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts create mode 100644 packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerBoot.cjs create mode 100644 packages/api/src/mcp/__tests__/helpers/mcpOAuthWorkerMain.ts diff --git a/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts b/packages/api/src/mcp/__tests__/MCPOAuthMultiProcess.integration.test.ts new file mode 100644 index 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 { + 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((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(command: string, payload?: Record): Promise { + if (this.exited) { + return Promise.reject(new Error(`[${this.name}] is no longer running`)); + } + const id = this.nextId++; + return new Promise((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 { + if (this.exited) { + return; + } + const stopped = new Promise((resolve) => this.child.once('exit', () => resolve())); + this.child.kill('SIGKILL'); + await stopped; + } + + async stop(): Promise { + if (this.exited) { + return; + } + await this.send('shutdown').catch(() => undefined); + const stopped = new Promise((resolve) => this.child.once('exit', () => resolve())); + this.child.kill('SIGTERM'); + await stopped; + } +} + +async function waitFor( + condition: () => boolean, + description: string, + timeoutMs = 20_000, +): Promise { + 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 | 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((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, + coordinate: boolean, + ): Promise => { + 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('getTokens'); + const readB = replicaB.send('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('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('getTokens').catch(() => null); + const readB = replicaB.send('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('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('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('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.cjs new file mode 100644 index 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.ts new file mode 100644 index 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; +} + +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; + +/** 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 { + createModels(mongoose); + tokenMethods = createMethods(mongoose) as unknown as TokenMethods; + await mongoose.connect(env('MCP_TEST_MONGO_URI'), { autoIndex: false }); + flowManager = new FlowStateManager(standardCache(flowNamespace, 60_000), { + ttl: 60_000, + }); +} + +/** Completes a real authorization-code grant against the provider. */ +async function exchangeAuthorizationCode(): Promise { + 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 { + 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 | Record | undefined; + if (!metadata) { + return null; + } + const value = + metadata instanceof Map + ? metadata.get('credential_set_id') + : (metadata as Record).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 { + const record = await tokenMethods.findToken({ + userId, + type: 'mcp_oauth_refresh', + identifier: `${identifier}:refresh`, + }); + return record ? digest(await decryptV2(record.token)) : null; +} + +const commands: Record) => Promise> = { + /** 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.ts index 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 | undefined; /** Optional test hook for controlling echo-tool completion. */ echoHandler?: (message: string) => string | Promise; } @@ -145,6 +150,7 @@ export async function createOAuthMCPServer( rejectRefreshTokens = 0, echoHandler, refreshFailure, + refreshGate, } = options; const sessions = new Map(); @@ -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' });