LibreChat/packages/api/src/flow/manager.test.ts
Danny Avila c27d6b85a4
🤫 refactor: Silent MCP OAuth Refresh on Mid-Session 401 (#13369)
* 🤫 fix: Silent MCP OAuth Refresh on Mid-Session 401

Avoids the hourly interactive re-auth prompt when an MCP server
(e.g. Azure Entra ID) returns 401 mid-session by attempting a refresh
token exchange first, and only falling back to the interactive OAuth
flow when no refresh token is stored or the refresh server rejects it.

Resolves #13364.

* fix: Use distinct flow type for silent token refresh to avoid cache hit

Addresses the Codex review on PR #13369: `attemptSilentTokenRefresh` was
reusing the `'mcp_get_tokens'` flow type, so
`FlowStateManager.createFlowWithHandler` would short-circuit and return
the same tokens cached by an earlier `getOAuthTokens` call — the very
tokens the server just rejected — without executing the forced-refresh
handler.

Switch silent refresh to the distinct `'mcp_force_refresh_tokens'` flow
type so coalescing still works but stale `mcp_get_tokens` cache entries
are not reused. After a successful refresh, invalidate the
`mcp_get_tokens` flow cache so the next `getOAuthTokens` call reads the
freshly persisted tokens from storage rather than the stale cached
value.

Add a regression test that simulates the real
`FlowStateManager.createFlowWithHandler` cache-hit behavior for
`mcp_get_tokens` and verifies the silent refresh handler still runs and
returns the freshly refreshed tokens.

* fix: Address Codex round-2 review on silent MCP OAuth refresh

Three follow-up findings from Codex on PR #13369:

1. The new `mcp_force_refresh_tokens` flow type was itself cached by
   `FlowStateManager.createFlowWithHandler`, so a subsequent 401 within
   the refreshed token's `expires_at` could re-serve the just-rejected
   token without ever re-running the refresh handler.

2. The factory's `oauthRequired` listener was removed immediately after
   the initial `attemptToConnect` succeeded, so a real mid-session 401
   emitted by `MCPConnection.connectClient` during transport recovery
   had no listener — the OAuth handled-promise would simply time out
   instead of triggering the silent refresh.

3. Routing the silent refresh through a distinct flow type broke
   coalescing with the `mcp_get_tokens` lock used by `getOAuthTokens`,
   letting two paths concurrently redeem the same stored refresh token.
   For providers that rotate refresh tokens (e.g. Azure Entra) the
   second redemption is rejected, kicking the user back into interactive
   OAuth despite a successful refresh elsewhere.

Resolution:

- Drop `FlowStateManager` from the silent-refresh path entirely. Replace
  with a process-local `inflightSilentRefreshes` Map keyed by
  `userId:serverName` that holds only the in-flight Promise (no cached
  result), so every fresh 401 after settlement triggers a fresh
  redemption while concurrent 401s for the same user/server still share
  one redemption.
- Stop calling `cleanupOAuthHandlers()` on successful initial connect,
  keeping the OAuth handler attached for the connection's lifetime so
  mid-session 401s actually reach `attemptSilentTokenRefresh`.
- Add a regression test reproducing the stale-cache scenario by faking
  the `mcp_get_tokens` cache hit and asserting silent refresh still runs
  against storage and returns the fresh tokens.
- Add a coalescing test asserting two concurrent oauthRequired events
  for the same user/server result in a single `forceRefreshTokens` call.
- Clear `inflightSilentRefreshes` in `beforeEach` to prevent
  cross-test leakage; switch the silent-refresh test mocks to
  `mockResolvedValueOnce` / `mockImplementationOnce` so leftover mock
  state cannot leak into later test cases.

Acknowledged remaining gap: the silent refresh still races
`getOAuthTokens`'s `mcp_get_tokens` flow when both run concurrently
(narrow window when an existing connection's local `expires_at` is
still valid but the server invalidated the token, and a new connection
is being created in parallel). The race is self-healing on the next
401 and documented inline.

* fix: Address Codex round-3 review on silent MCP OAuth refresh

Three more findings from Codex on PR #13369:

1. The in-flight silent-refresh promise was unbounded. If
   `forceRefreshTokens()` ever hung (slow provider, dropped TCP), the
   `inflightSilentRefreshes` lock stayed occupied forever and every
   later 401 for the same user/server joined the stuck promise instead
   of starting a fresh attempt or falling back to interactive OAuth.

2. The interactive-OAuth fallback didn't invalidate the
   `mcp_get_tokens` flow cache after persisting fresh tokens. For
   providers that don't issue refresh tokens (so silent refresh
   returns null), the old cache could still feed stale access tokens
   to the next `getOAuthTokens` call until its TTL expired — causing
   an immediate reconnect with the same just-rejected token.

3. When silent refresh failed, the handler fell through to
   `handleOAuthRequired()` whose recent-completion fast path can
   reuse a COMPLETED `mcp_oauth` flow within `PENDING_STALE_MS`. Those
   cached tokens are exactly the ones the server just rejected, so
   the connection would keep adopting them and looping on 401s until
   the cache aged out.

Resolution:

- Wrap `runSilentRefresh()` with a 60-second `withTimeout` (well under
  `connectClient`'s 120s OAuth timeout). On timeout the `.catch`
  resolves to null and the `finally` clears the in-flight entry, so
  the next 401 starts fresh and falls through to interactive OAuth.
- Extract two helpers — `invalidateGetTokensFlow` and
  `invalidateCompletedOAuthFlow` — and call them from the right
  branches: clear `mcp_get_tokens` after silent-refresh success AND
  after interactive-OAuth `storeTokens`; clear the COMPLETED
  `mcp_oauth` state (plus its CSRF mapping) before falling through to
  interactive OAuth so the fast-reuse path can't re-serve the
  rejected tokens.
- Add three regression tests: hung refresh release-the-lock under
  fake timers, completed-OAuth cache invalidation pre-fallback, and
  `mcp_get_tokens` invalidation after interactive token store.

* fix: Address Codex round-4 review on silent MCP OAuth refresh

Three more findings from Codex on PR #13369:

1. (P1) The silent-refresh in-flight lock keyed only by
   `userId:serverName`. In multi-tenant setups where two tenants share a
   userId (e.g. username-based IDs) and the same MCP server name, a
   concurrent mid-session 401 from tenant B would join tenant A's
   in-flight refresh and adopt tenant A's freshly minted tokens onto a
   tenant-B connection — a cross-tenant credential leak.

2. (P2) `invalidateGetTokensFlow` deleted the `mcp_get_tokens` flow
   state regardless of its status. When another connection was
   currently in `getOAuthTokens()` (PENDING flow) and joiners were
   monitoring it, the unconditional delete made those waiters see
   "Flow state not found" and unnecessarily fall back to interactive
   OAuth — even though fresh tokens were already being written.

3. (P2) The 60s `withTimeout` wrapping `runSilentRefresh()` only races
   the promise; it does not cancel the underlying `forceRefreshTokens`
   /  refresh-token HTTP request. If the request returned after a
   subsequent interactive OAuth had stored newer tokens, the late
   completion would `storeTokens` over the newer state. This requires
   a provider that doesn't rotate refresh tokens AND a refresh slower
   than 60s AND a successful interactive OAuth in that window — narrow
   but real.

Resolution:

- Capture `getTenantId()` into a new `factory.tenantId` field at
  factory construction time (before the OAuth handler closes over it
  outside the original request's async context) and include it in the
  silent-refresh lock key as `tenantId:userId:serverName`.
- `invalidateGetTokensFlow` now calls `getFlowState` first and only
  deletes when `status === 'COMPLETED'`. PENDING lookups are left
  alone so concurrent `getOAuthTokens` waiters via `monitorFlow` can
  still settle.
- For (3), document the race as a known limitation inline. Fully
  closing it requires threading an `AbortSignal` through
  `MCPTokenStorage.forceRefreshTokens` and the OAuth refresh handler
  to skip the late `storeTokens` after timeout — out of scope for this
  PR's surgical change.
- Add `getTenantId` to the `MCPOAuthConnectionEvents` test's
  `@librechat/data-schemas` mock so the factory constructor doesn't
  blow up under that suite.
- Add three regression tests: per-tenant lock isolation, PENDING-state
  preservation under `invalidateGetTokensFlow`, and (reused) the
  existing interactive-store invalidation test now driven through
  `getFlowState` returning the COMPLETED state.

* fix: Address silent MCP OAuth refresh review

Restore captured tenant context around token storage and OAuth fallback paths so mid-session callbacks do not lose tenant scope.

Thread AbortSignal through forced refresh and OAuth token requests, cap silent refresh by the connection OAuth timeout, and prevent timed-out refreshes from writing stale credentials after fallback.

Complete pending mcp_get_tokens flows with fresh tokens, add missing FlowState createdAt test fixtures, and cover the new tenant/abort/cache behaviors.

* fix: Tighten tenant-scoped MCP token refresh

Cap silent refresh by both the factory connect timeout and the connection OAuth wait timeout so fallback OAuth wins before the outer connect attempt expires.

Tenant-scope mcp_get_tokens flow ids for both token lookup and refresh invalidation, preventing cross-tenant flow completion or cache deletion when tenants share user ids and server names.

Add regression tests for the omitted initTimeout budget and tenant-prefixed token flow locks.

* fix: Reserve MCP OAuth fallback budget

* fix: Harden MCP OAuth refresh races

* fix: Keep MCP OAuth fallback route-compatible

* test: Add SDK MCP OAuth refresh repro

* fix: Address MCP OAuth refresh review findings

* fix: Address MCP OAuth tenant review findings

* fix: Close MCP OAuth route tenant gaps

* fix: Preserve MCP OAuth refresh flow guards

* fix: Avoid reprocessing MCP OAuth reauth config

* fix: Release timed-out MCP refresh locks

* fix: Release MCP OAuth request callbacks

* fix: Tenant-scope remaining MCP OAuth flow lookups

* ci: Sort imports in MCP OAuth test suites
2026-06-10 13:12:42 -04:00

1091 lines
36 KiB
TypeScript

import { Keyv } from 'keyv';
import { FlowStateManager, PENDING_STALE_MS } from './manager';
import { FlowState } from './types';
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
logger: {
info: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
debug: jest.fn(),
},
}));
/** Mock class without extending Keyv */
class MockKeyv<T = string> {
private store: Map<string, FlowState<T>>;
constructor() {
this.store = new Map();
}
async get(key: string): Promise<FlowState<T> | undefined> {
return this.store.get(key);
}
async set(key: string, value: FlowState<T>, _ttl?: number): Promise<true> {
this.store.set(key, value);
return true;
}
async delete(key: string): Promise<boolean> {
return this.store.delete(key);
}
}
describe('FlowStateManager', () => {
let flowManager: FlowStateManager<string>;
let store: MockKeyv;
beforeEach(() => {
store = new MockKeyv();
// Type assertion here since we know our mock implements the necessary methods
flowManager = new FlowStateManager(store as unknown as Keyv, { ttl: 30000, ci: true });
});
afterEach(() => {
jest.clearAllMocks();
});
describe('Concurrency Tests', () => {
it('should handle concurrent flow creation and return same result', async () => {
const flowId = 'test-flow';
const type = 'test-type';
// Start two concurrent flow creations
const flow1Promise = flowManager.createFlowWithHandler(flowId, type, async () => {
await new Promise((resolve) => setTimeout(resolve, 100));
return 'result';
});
const flow2Promise = flowManager.createFlowWithHandler(flowId, type, async () => {
await new Promise((resolve) => setTimeout(resolve, 50));
return 'different-result';
});
// Both should resolve to the same result from the first handler
const [result1, result2] = await Promise.all([flow1Promise, flow2Promise]);
expect(result1).toBe('result');
expect(result2).toBe('result');
});
it('should return the externally completed result when handler loses completion race', async () => {
const flowId = 'race-flow';
const type = 'test-type';
const result = await flowManager.createFlowWithHandler(flowId, type, async () => {
await flowManager.completeFlow(flowId, type, 'fresh-result');
return 'stale-result';
});
expect(result).toBe('fresh-result');
await expect(flowManager.getFlowState(flowId, type)).resolves.toEqual(
expect.objectContaining({
status: 'COMPLETED',
result: 'fresh-result',
}),
);
});
it('should handle flow timeout correctly', async () => {
const flowId = 'timeout-flow';
const type = 'test-type';
// Create flow with very short TTL
const shortTtlManager = new FlowStateManager(store as unknown as Keyv, {
ttl: 100,
ci: true,
});
const flowPromise = shortTtlManager.createFlow(flowId, type);
await expect(flowPromise).rejects.toThrow('test-type flow timed out');
});
it('should maintain flow state consistency under high concurrency', async () => {
const flowId = 'concurrent-flow';
const type = 'test-type';
// Create multiple concurrent operations
const operations = [];
for (let i = 0; i < 10; i++) {
operations.push(
flowManager.createFlowWithHandler(flowId, type, async () => {
await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));
return `result-${i}`;
}),
);
}
// All operations should resolve to the same result
const results = await Promise.all(operations);
const firstResult = results[0];
results.forEach((result: string) => {
expect(result).toBe(firstResult);
});
});
it('should handle race conditions in flow completion', async () => {
const flowId = 'test-flow';
const type = 'test-type';
// Create initial flow
const flowPromise = flowManager.createFlow(flowId, type);
// Increase delay to ensure flow is properly created
await new Promise((resolve) => setTimeout(resolve, 500));
// Complete the flow
await flowManager.completeFlow(flowId, type, 'result1');
const result = await flowPromise;
expect(result).toBe('result1');
}, 15000);
it('should handle concurrent flow monitoring', async () => {
const flowId = 'test-flow';
const type = 'test-type';
// Create initial flow
const flowPromise = flowManager.createFlow(flowId, type);
// Increase delay
await new Promise((resolve) => setTimeout(resolve, 500));
// Complete the flow
await flowManager.completeFlow(flowId, type, 'success');
const result = await flowPromise;
expect(result).toBe('success');
}, 15000);
it('should handle concurrent success and failure attempts', async () => {
const flowId = 'race-flow';
const type = 'test-type';
const flowPromise = flowManager.createFlow(flowId, type);
// Increase delay
await new Promise((resolve) => setTimeout(resolve, 500));
// Fail the flow
await flowManager.failFlow(flowId, type, new Error('failure'));
await expect(flowPromise).rejects.toThrow('failure');
}, 15000);
it('should not overwrite a completed flow with a late failure', async () => {
const flowId = 'completed-race-flow';
const type = 'test-type';
const flowKey = `${type}:${flowId}`;
await flowManager.initFlow(flowId, type);
await flowManager.completeFlow(flowId, type, 'success');
const result = await flowManager.failFlow(flowId, type, new Error('late failure'));
const state = await store.get(flowKey);
expect(result).toBe(true);
expect(state).toMatchObject({
status: 'COMPLETED',
result: 'success',
});
expect(state?.error).toBeUndefined();
});
});
describe('initFlow', () => {
const flowId = 'init-test-flow';
const type = 'test-type';
const flowKey = `${type}:${flowId}`;
it('stores a PENDING flow state in the cache', async () => {
await flowManager.initFlow(flowId, type, { serverName: 'test' });
const state = await store.get(flowKey);
expect(state).toBeDefined();
expect(state!.status).toBe('PENDING');
expect(state!.type).toBe(type);
expect(state!.metadata).toEqual({ serverName: 'test' });
expect(state!.createdAt).toBeGreaterThan(0);
});
it('overwrites an existing flow state', async () => {
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: { old: true },
createdAt: Date.now() - 10000,
});
await flowManager.initFlow(flowId, type, { new: true });
const state = await store.get(flowKey);
expect(state!.status).toBe('PENDING');
expect(state!.metadata).toEqual({ new: true });
});
it('allows createFlow to find and monitor the pre-stored state', async () => {
// initFlow stores the PENDING state
await flowManager.initFlow(flowId, type, { preStored: true });
// createFlow should find the existing state and start monitoring
const flowPromise = flowManager.createFlow(flowId, type);
// Complete the flow so the monitor resolves
await new Promise((resolve) => setTimeout(resolve, 500));
await flowManager.completeFlow(flowId, type, 'success');
const result = await flowPromise;
expect(result).toBe('success');
}, 15000);
it('passes the configured TTL to keyv.set', async () => {
const setSpy = jest.spyOn(store, 'set');
await flowManager.initFlow(flowId, type, { serverName: 'test' });
expect(setSpy).toHaveBeenCalledWith(
flowKey,
expect.objectContaining({ status: 'PENDING' }),
30000,
);
});
it('propagates store write failures', async () => {
jest.spyOn(store, 'set').mockRejectedValueOnce(new Error('Store write failed'));
await expect(flowManager.initFlow(flowId, type)).rejects.toThrow('Store write failed');
});
});
describe('deleteFlow', () => {
const flowId = 'test-flow-123';
const type = 'test-type';
const flowKey = `${type}:${flowId}`;
it('deletes an existing flow', async () => {
await store.set(flowKey, { type, status: 'PENDING', metadata: {}, createdAt: Date.now() });
expect(await store.get(flowKey)).toBeDefined();
const result = await flowManager.deleteFlow(flowId, type);
expect(result).toBe(true);
expect(await store.get(flowKey)).toBeUndefined();
});
it('returns false if the deletion errors', async () => {
jest.spyOn(store, 'delete').mockRejectedValue(new Error('Deletion failed'));
const result = await flowManager.deleteFlow(flowId, type);
expect(result).toBe(false);
});
it('does nothing if the flow does not exist', async () => {
expect(await store.get(flowKey)).toBeUndefined();
const result = await flowManager.deleteFlow(flowId, type);
expect(result).toBe(true);
});
});
describe('createFlowWithHandler - token expiration', () => {
const flowId = 'token-flow';
const type = 'mcp_get_tokens';
const flowKey = `${type}:${flowId}`;
type TokenResult = {
access_token: string;
refresh_token: string;
expires_at?: number;
};
let tokenFlowManager: FlowStateManager<TokenResult>;
let tokenStore: MockKeyv<TokenResult>;
beforeEach(() => {
tokenStore = new MockKeyv<TokenResult>();
tokenFlowManager = new FlowStateManager(tokenStore as unknown as Keyv, {
ttl: 30000,
ci: true,
});
});
it('should execute handler when existing flow has expired token', async () => {
const expiredTokenResult: TokenResult = {
access_token: 'expired_token',
refresh_token: 'refresh_token',
expires_at: Date.now() - 1000, // Expired 1 second ago
};
// Create flow with expired token
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: expiredTokenResult,
} as FlowState<TokenResult>);
const newTokenResult: TokenResult = {
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
};
const handlerSpy = jest.fn().mockResolvedValue(newTokenResult);
const result = await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
// Handler should be called because token is expired
expect(handlerSpy).toHaveBeenCalled();
expect(result).toEqual(newTokenResult);
});
it('should reuse existing flow when token is still valid', async () => {
const validTokenResult: TokenResult = {
access_token: 'valid_token',
refresh_token: 'refresh_token',
expires_at: Date.now() + 3600000, // Expires in 1 hour
};
// Create flow with valid token
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: validTokenResult,
} as FlowState<TokenResult>);
const handlerSpy = jest.fn().mockResolvedValue({
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
});
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
// Complete the monitored flow
await new Promise((resolve) => setTimeout(resolve, 500));
const result = await resultPromise;
// Handler should NOT be called because token is still valid
expect(handlerSpy).not.toHaveBeenCalled();
expect(result).toEqual(validTokenResult);
}, 15000);
it('should reuse existing flow when no expires_at field exists', async () => {
const tokenResultWithoutExpiry: TokenResult = {
access_token: 'token_without_expiry',
refresh_token: 'refresh_token',
// No expires_at field - handles flows without expiration metadata
};
// Create flow without expires_at
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: tokenResultWithoutExpiry,
} as FlowState<TokenResult>);
const handlerSpy = jest.fn().mockResolvedValue({
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
});
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
// Wait for flow monitoring
await new Promise((resolve) => setTimeout(resolve, 500));
const result = await resultPromise;
// Handler should NOT be called - flows without expires_at are treated as valid/non-expired
expect(handlerSpy).not.toHaveBeenCalled();
expect(result).toEqual(tokenResultWithoutExpiry);
}, 15000);
it('should treat NaN expires_at as non-expired and reuse existing flow', async () => {
const tokenResultWithNaN: TokenResult = {
access_token: 'token_with_nan',
refresh_token: 'refresh_token',
expires_at: NaN,
};
// Create flow with NaN expires_at
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: tokenResultWithNaN,
} as FlowState<TokenResult>);
const handlerSpy = jest.fn().mockResolvedValue({
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
});
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
// Wait for flow monitoring
await new Promise((resolve) => setTimeout(resolve, 500));
const result = await resultPromise;
// Handler should NOT be called - NaN is treated as invalid expiration (non-expired)
expect(handlerSpy).not.toHaveBeenCalled();
expect(result).toEqual(tokenResultWithNaN);
}, 15000);
it('should handle expires_at in seconds format (Unix timestamp)', async () => {
const expiredSecondsTimestamp = Math.floor(Date.now() / 1000) - 60;
const expiredTokenResult: TokenResult = {
access_token: 'expired_token_seconds',
refresh_token: 'refresh_token',
expires_at: expiredSecondsTimestamp,
};
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: expiredTokenResult,
} as FlowState<TokenResult>);
const newTokenResult: TokenResult = {
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
};
const handlerSpy = jest.fn().mockResolvedValue(newTokenResult);
const result = await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
// Handler SHOULD be called - token in seconds format is expired
expect(handlerSpy).toHaveBeenCalled();
expect(result).toEqual(newTokenResult);
});
it('should reuse flow when expires_at in seconds format is still valid', async () => {
const validSecondsTimestamp = Math.floor(Date.now() / 1000) + 3600;
const validTokenResult: TokenResult = {
access_token: 'valid_token_seconds',
refresh_token: 'refresh_token',
expires_at: validSecondsTimestamp,
};
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
completedAt: Date.now() - 4000,
result: validTokenResult,
} as FlowState<TokenResult>);
const handlerSpy = jest.fn().mockResolvedValue({
access_token: 'new_token',
refresh_token: 'new_refresh',
expires_at: Date.now() + 3600000,
});
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
const result = await resultPromise;
// Handler should NOT be called - seconds-format token is still valid
expect(handlerSpy).not.toHaveBeenCalled();
expect(result).toEqual(validTokenResult);
}, 15000);
});
describe('Timestamp normalization', () => {
const SECONDS_THRESHOLD = 1e10;
const flowId = 'normalization-test';
const type = 'timestamp_test';
const flowKey = `${type}:${flowId}`;
type TokenResult = {
access_token: string;
expires_at: number;
};
let tokenFlowManager: FlowStateManager<TokenResult>;
let tokenStore: MockKeyv<TokenResult>;
beforeEach(() => {
tokenStore = new MockKeyv<TokenResult>();
tokenFlowManager = new FlowStateManager(tokenStore as unknown as Keyv, {
ttl: 30000,
ci: true,
});
});
describe('Seconds format detection (values < 1e10)', () => {
it('should normalize current Unix timestamp in seconds (Dec 2024: ~1734000000)', async () => {
const currentSeconds = Math.floor(Date.now() / 1000);
const expiredSecondsAgo = currentSeconds - 60;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: expiredSecondsAgo },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle Sept 2001 timestamp in seconds (1000000000)', async () => {
const sept2001Seconds = 1000000000;
expect(sept2001Seconds).toBeLessThan(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: sept2001Seconds },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle year 2000 timestamp in seconds (946684800)', async () => {
const year2000Seconds = 946684800;
expect(year2000Seconds).toBeLessThan(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: year2000Seconds },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle May 2033 timestamp in seconds (2000000000) - future but still seconds format', async () => {
const may2033Seconds = 2000000000;
expect(may2033Seconds).toBeLessThan(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: may2033Seconds },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
await resultPromise;
expect(handlerSpy).not.toHaveBeenCalled();
}, 15000);
it('should handle edge case: just below threshold (9999999999 - ~Nov 2286 in seconds)', async () => {
const justBelowThreshold = 9999999999;
expect(justBelowThreshold).toBeLessThan(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: justBelowThreshold },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
await resultPromise;
expect(handlerSpy).not.toHaveBeenCalled();
}, 15000);
});
describe('Milliseconds format detection (values >= 1e10)', () => {
it('should recognize current timestamp in milliseconds (Dec 2024: ~1734000000000)', async () => {
const currentMs = Date.now();
const expiredMsAgo = currentMs - 60000;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: expiredMsAgo },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle Sept 2001 timestamp in milliseconds (1000000000000)', async () => {
const sept2001Ms = 1000000000000;
expect(sept2001Ms).toBeGreaterThanOrEqual(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: sept2001Ms },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle edge case: exactly at threshold (10000000000 - ~April 1970 in ms)', async () => {
const exactlyAtThreshold = 10000000000;
expect(exactlyAtThreshold).toEqual(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: exactlyAtThreshold },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle edge case: just above threshold (10000000001)', async () => {
const justAboveThreshold = 10000000001;
expect(justAboveThreshold).toBeGreaterThan(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: justAboveThreshold },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle future timestamp in milliseconds (2000000000000 - May 2033)', async () => {
const may2033Ms = 2000000000000;
expect(may2033Ms).toBeGreaterThanOrEqual(SECONDS_THRESHOLD);
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: may2033Ms },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
await resultPromise;
expect(handlerSpy).not.toHaveBeenCalled();
}, 15000);
});
describe('Real-world OAuth provider timestamp formats', () => {
it('should handle Google/MCP OAuth style (milliseconds, current + expires_in * 1000)', async () => {
const expiresIn = 3600;
const googleStyleExpiry = Date.now() + expiresIn * 1000;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'google_token', expires_at: googleStyleExpiry },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 7200000 });
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
await resultPromise;
expect(handlerSpy).not.toHaveBeenCalled();
}, 15000);
it('should handle OIDC style (seconds, Unix epoch)', async () => {
const oidcStyleExpiry = Math.floor(Date.now() / 1000) + 3600;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'oidc_token', expires_at: oidcStyleExpiry },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 7200000 });
const resultPromise = tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
await new Promise((resolve) => setTimeout(resolve, 500));
await resultPromise;
expect(handlerSpy).not.toHaveBeenCalled();
}, 15000);
it('should handle expired Google/MCP OAuth style token', async () => {
const expiredGoogleStyle = Date.now() - 60000;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 70000,
result: { access_token: 'expired_google', expires_at: expiredGoogleStyle },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
it('should handle expired OIDC style token', async () => {
const expiredOidcStyle = Math.floor(Date.now() / 1000) - 60;
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 70000,
result: { access_token: 'expired_oidc', expires_at: expiredOidcStyle },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
});
describe('Threshold boundary validation', () => {
/**
* The threshold (1e10 = 10 billion) was chosen because:
* - In SECONDS: 10 billion seconds from epoch = ~year 2286
* - In MILLISECONDS: 10 billion ms from epoch = ~April 1970
*
* So any reasonable timestamp:
* - Less than 10 billion -> must be seconds (we haven't reached year 2286 yet)
* - Greater than or equal to 10 billion -> must be milliseconds (we're past April 1970)
*/
it('should correctly identify threshold represents ~April 1970 in milliseconds', () => {
const thresholdAsDate = new Date(SECONDS_THRESHOLD);
expect(thresholdAsDate.getFullYear()).toBe(1970);
expect(thresholdAsDate.getMonth()).toBe(3);
});
it('should correctly identify threshold represents ~year 2286 in seconds', () => {
const thresholdAsSecondsDate = new Date(SECONDS_THRESHOLD * 1000);
expect(thresholdAsSecondsDate.getFullYear()).toBe(2286);
});
it('should handle token expiring exactly at threshold boundary', async () => {
await tokenStore.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 5000,
result: { access_token: 'test', expires_at: SECONDS_THRESHOLD },
} as FlowState<TokenResult>);
const handlerSpy = jest
.fn()
.mockResolvedValue({ access_token: 'new', expires_at: Date.now() + 3600000 });
await tokenFlowManager.createFlowWithHandler(flowId, type, handlerSpy);
expect(handlerSpy).toHaveBeenCalled();
});
});
});
describe('isFlowStale', () => {
const flowId = 'test-flow-stale';
const type = 'test-type';
const flowKey = `${type}:${flowId}`;
it('returns not stale for non-existent flow', async () => {
const result = await flowManager.isFlowStale(flowId, type);
expect(result).toEqual({
isStale: false,
age: 0,
});
});
it('returns not stale for PENDING flow regardless of age', async () => {
const oldTimestamp = Date.now() - 10 * 60 * 1000; // 10 minutes ago
await store.set(flowKey, {
type,
status: 'PENDING',
metadata: {},
createdAt: oldTimestamp,
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result).toEqual({
isStale: false,
age: 0,
status: 'PENDING',
});
});
it('returns not stale for recently COMPLETED flow', async () => {
const recentTimestamp = Date.now() - 30 * 1000; // 30 seconds ago
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 60 * 1000,
completedAt: recentTimestamp,
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(false);
expect(result.status).toBe('COMPLETED');
expect(result.age).toBeGreaterThan(0);
expect(result.age).toBeLessThan(60 * 1000);
});
it('returns stale for old COMPLETED flow', async () => {
const oldTimestamp = Date.now() - 5 * 60 * 1000; // 5 minutes ago
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 10 * 60 * 1000,
completedAt: oldTimestamp,
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(true);
expect(result.status).toBe('COMPLETED');
expect(result.age).toBeGreaterThan(2 * 60 * 1000);
});
it('returns not stale for recently FAILED flow', async () => {
const recentTimestamp = Date.now() - 30 * 1000; // 30 seconds ago
await store.set(flowKey, {
type,
status: 'FAILED',
metadata: {},
createdAt: Date.now() - 60 * 1000,
failedAt: recentTimestamp,
error: 'Test error',
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(false);
expect(result.status).toBe('FAILED');
expect(result.age).toBeGreaterThan(0);
expect(result.age).toBeLessThan(60 * 1000);
});
it('returns stale for old FAILED flow', async () => {
const oldTimestamp = Date.now() - 5 * 60 * 1000; // 5 minutes ago
await store.set(flowKey, {
type,
status: 'FAILED',
metadata: {},
createdAt: Date.now() - 10 * 60 * 1000,
failedAt: oldTimestamp,
error: 'Test error',
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(true);
expect(result.status).toBe('FAILED');
expect(result.age).toBeGreaterThan(2 * 60 * 1000);
});
it('uses custom stale threshold', async () => {
const timestamp = Date.now() - 90 * 1000; // 90 seconds ago
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - 2 * 60 * 1000,
completedAt: timestamp,
});
// 90 seconds old, threshold 60 seconds = stale
const result1 = await flowManager.isFlowStale(flowId, type, 60 * 1000);
expect(result1.isStale).toBe(true);
// 90 seconds old, threshold 120 seconds = not stale
const result2 = await flowManager.isFlowStale(flowId, type, 120 * 1000);
expect(result2.isStale).toBe(false);
});
it('uses the default PENDING_STALE_MS threshold when not specified', async () => {
const timestamp = Date.now() - (PENDING_STALE_MS + 60 * 1000); // just past the default
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: Date.now() - (PENDING_STALE_MS + 3 * 60 * 1000),
completedAt: timestamp,
});
// Should use the default PENDING_STALE_MS threshold
const result = await flowManager.isFlowStale(flowId, type);
expect(result.isStale).toBe(true);
expect(result.age).toBeGreaterThan(PENDING_STALE_MS);
});
it('falls back to createdAt when completedAt/failedAt are not present', async () => {
const createdTimestamp = Date.now() - 5 * 60 * 1000; // 5 minutes ago
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: createdTimestamp,
// No completedAt or failedAt
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(true);
expect(result.status).toBe('COMPLETED');
expect(result.age).toBeGreaterThan(2 * 60 * 1000);
});
it('handles flow with no timestamps', async () => {
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
// No timestamps at all
} as FlowState<string>);
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
expect(result.isStale).toBe(false);
expect(result.age).toBe(0);
expect(result.status).toBe('COMPLETED');
});
it('prefers completedAt over createdAt for age calculation', async () => {
const createdTimestamp = Date.now() - 10 * 60 * 1000; // 10 minutes ago
const completedTimestamp = Date.now() - 30 * 1000; // 30 seconds ago
await store.set(flowKey, {
type,
status: 'COMPLETED',
metadata: {},
createdAt: createdTimestamp,
completedAt: completedTimestamp,
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
// Should use completedAt (30s) not createdAt (10m)
expect(result.isStale).toBe(false);
expect(result.age).toBeLessThan(60 * 1000);
});
it('prefers failedAt over createdAt for age calculation', async () => {
const createdTimestamp = Date.now() - 10 * 60 * 1000; // 10 minutes ago
const failedTimestamp = Date.now() - 30 * 1000; // 30 seconds ago
await store.set(flowKey, {
type,
status: 'FAILED',
metadata: {},
createdAt: createdTimestamp,
failedAt: failedTimestamp,
error: 'Test error',
});
const result = await flowManager.isFlowStale(flowId, type, 2 * 60 * 1000);
// Should use failedAt (30s) not createdAt (10m)
expect(result.isStale).toBe(false);
expect(result.age).toBeLessThan(60 * 1000);
});
});
});