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
import { Types } from 'mongoose';
import { CacheKeys } from 'librechat-data-provider';
import { logger, buildAuthUserDocEvictionFenceKey } from '@librechat/data-schemas';
import {
AUTH_USER_DOC_CACHE_TTL_MS,
buildAuthUserDocCacheKey,
buildAuthUserDocReverseIndexKey,
getAuthUserDocCacheMode,
getCachedAuthUserDoc,
getCurrentCachedAuthUserDoc,
isAuthUserAdmissible,
AUTH_USER_FRESHNESS_PROJECTION,
invalidateCachedAuthUserDoc,
setCachedAuthUserDoc,
timeAuthUserLookup,
} from './userDocCache';
import { cacheConfig } from '~/cache/cacheConfig';
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
logger: {
warn: jest.fn(),
},
}));
const ORIGINAL_ENV = {
AUTH_USER_CACHE_MODE: process.env.AUTH_USER_CACHE_MODE,
};
const ORIGINAL_CACHE_CONFIG = {
USE_REDIS: cacheConfig.USE_REDIS,
FORCED_IN_MEMORY_CACHE_NAMESPACES: [...cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES],
};
function restoreEnv() {
for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
if (value === undefined) {
delete process.env[key];
} else {
process.env[key] = value;
}
}
cacheConfig.USE_REDIS = ORIGINAL_CACHE_CONFIG.USE_REDIS;
cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES = [
...ORIGINAL_CACHE_CONFIG.FORCED_IN_MEMORY_CACHE_NAMESPACES,
];
}
function makeStore() {
const values = new Map<string, unknown>();
return {
values,
get: async <T = unknown>(key: string) => values.get(key) as T | undefined,
set: jest.fn(async (key: string, value: unknown, _ttl?: number) => {
values.set(key, value);
return true;
}),
delete: jest.fn(async (key: string) => values.delete(key)),
};
}
describe('auth user document cache helpers', () => {
beforeEach(() => {
jest.clearAllMocks();
restoreEnv();
});
afterAll(() => {
restoreEnv();
});
it('only enables user request burst caching when Redis backs the auth user namespace', () => {
process.env.AUTH_USER_CACHE_MODE = 'on';
cacheConfig.USE_REDIS = false;
expect(getAuthUserDocCacheMode()).toBe('off');
expect(logger.warn).toHaveBeenCalledWith(
'[authUserDocCache] User request burst caching requires Redis; disabling auth user cache',
);
cacheConfig.USE_REDIS = true;
cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES = [CacheKeys.AUTH_USER_DOC];
expect(getAuthUserDocCacheMode()).toBe('off');
cacheConfig.FORCED_IN_MEMORY_CACHE_NAMESPACES = [CacheKeys.APP_CONFIG];
expect(getAuthUserDocCacheMode()).toBe('on');
process.env.AUTH_USER_CACHE_MODE = 'shadow';
expect(getAuthUserDocCacheMode()).toBe('off');
process.env.AUTH_USER_CACHE_MODE = 'invalid';
expect(getAuthUserDocCacheMode()).toBe('off');
});
it('builds stable keys from strategy, subject, issuer, tenant, user, and scope', () => {
const key = buildAuthUserDocCacheKey({
strategy: ' OpenID-JWT ',
subject: 'subject-1',
issuer: 'https://issuer.example.com/',
tenantId: 'Tenant-A',
userId: 'User-A',
scope: ' Org-A ',
});
const equivalent = buildAuthUserDocCacheKey({
strategy: 'openid-jwt',
subject: 'subject-1',
issuer: 'https://issuer.example.com',
tenantId: 'Tenant-A',
userId: 'User-A',
scope: 'org-a',
});
const otherTenant = buildAuthUserDocCacheKey({
strategy: 'openid-jwt',
subject: 'subject-1',
issuer: 'https://issuer.example.com',
tenantId: 'Tenant-B',
userId: 'User-A',
scope: 'org-a',
});
const caseVariantTenant = buildAuthUserDocCacheKey({
strategy: 'openid-jwt',
subject: 'subject-1',
issuer: 'https://issuer.example.com',
tenantId: 'tenant-a',
userId: 'User-A',
scope: 'org-a',
});
const otherUser = buildAuthUserDocCacheKey({
strategy: 'openid-jwt',
subject: 'subject-1',
issuer: 'https://issuer.example.com',
tenantId: 'Tenant-A',
userId: 'User-B',
scope: 'org-a',
});
const otherScope = buildAuthUserDocCacheKey({
strategy: 'openid-jwt',
subject: 'subject-1',
issuer: 'https://issuer.example.com',
tenantId: 'Tenant-A',
userId: 'User-A',
scope: 'org-b',
});
expect(key).toMatch(/^auth-user-doc:v2:/);
expect(key).toBe(equivalent);
expect(key).not.toBe(otherTenant);
expect(key).not.toBe(caseVariantTenant);
expect(key).not.toBe(otherUser);
expect(key).not.toBe(otherScope);
expect(buildAuthUserDocCacheKey({ strategy: '', subject: 'subject-1' })).toBeUndefined();
expect(buildAuthUserDocCacheKey({ strategy: 'openid-jwt' })).toBeUndefined();
});
it('sanitizes sensitive fields and remembers cache keys by user id', async () => {
const store = makeStore();
const cacheKey = 'auth-user-doc:v2:key';
const userId = new Types.ObjectId();
await setCachedAuthUserDoc(
store,
cacheKey,
{
_id: userId,
id: userId.toString(),
email: '[email protected]',
provider: 'openid',
password: 'secret',
refreshToken: [{ refreshToken: 'secret' }],
federatedTokens: { access_token: 'secret' },
openidTokens: { access_token: 'secret' },
totpSecret: 'secret',
backupCodes: [{ codeHash: 'secret', used: false }],
},
Date.now(),
);
const cached = store.values.get(cacheKey) as { user: Record<string, unknown> };
expect(cached.user).toMatchObject({
_id: userId.toString(),
id: userId.toString(),
email: '[email protected]',
});
expect(cached.user.password).toBeUndefined();
expect(cached.user.refreshToken).toBeUndefined();
expect(cached.user.federatedTokens).toBeUndefined();
expect(cached.user.openidTokens).toBeUndefined();
expect(cached.user.totpSecret).toBeUndefined();
expect(cached.user.backupCodes).toBeUndefined();
expect(store.set).toHaveBeenCalledWith(
cacheKey,
expect.objectContaining({ version: 2, user: expect.any(Object) }),
AUTH_USER_DOC_CACHE_TTL_MS,
);
expect(store.values.get(buildAuthUserDocReverseIndexKey(userId.toString()))).toEqual([
cacheKey,
]);
expect(store.set).toHaveBeenCalledWith(
buildAuthUserDocReverseIndexKey(userId.toString()),
[cacheKey],
AUTH_USER_DOC_CACHE_TTL_MS * 2,
);
});
it('does not cache a document the reverse index could not record', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const indexKey = buildAuthUserDocReverseIndexKey(userId.toString());
store.set.mockImplementation(async (key: string, value: unknown) => {
if (key === indexKey) {
throw new Error('redis unavailable');
}
store.values.set(key, value);
return true;
});
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:orphan',
{
_id: userId,
email: '[email protected]',
},
Date.now(),
);
expect(store.values.has('auth-user-doc:v2:orphan')).toBe(false);
expect(logger.warn).toHaveBeenCalledWith('[authUserDocCache] Cache write failed', {
error: 'redis unavailable',
});
});
it('deduplicates reverse-index keys and caps the remembered set', async () => {
const store = makeStore();
const objectId = new Types.ObjectId();
const userId = objectId.toString();
const indexKey = buildAuthUserDocReverseIndexKey(userId);
store.values.set(
indexKey,
Array.from({ length: 20 }, (_value, index) => `existing-key-${index}`),
);
await setCachedAuthUserDoc(
store,
'existing-key-10',
{
_id: objectId,
email: '[email protected]',
},
Date.now(),
);
await setCachedAuthUserDoc(
store,
'new-key',
{
_id: objectId,
email: '[email protected]',
},
Date.now(),
);
const indexed = store.values.get(indexKey);
expect(indexed).toHaveLength(20);
expect(indexed).not.toContain('existing-key-0');
expect(indexed).toContain('existing-key-10');
expect(indexed).toContain('new-key');
});
it('returns cached user documents only for the current cache version', async () => {
const store = makeStore();
store.values.set('current', {
version: 2,
cachedAt: Date.now(),
expiresAt: Date.now() + AUTH_USER_DOC_CACHE_TTL_MS,
user: { id: 'user-1' },
});
store.values.set('stale', { version: 1, cachedAt: Date.now(), user: { id: 'user-2' } });
await expect(getCachedAuthUserDoc(store, 'current')).resolves.toEqual({ id: 'user-1' });
await expect(getCachedAuthUserDoc(store, 'stale')).resolves.toBeUndefined();
});
it('invalidates explicit and reverse-indexed cache keys', async () => {
const store = makeStore();
store.values.set(buildAuthUserDocReverseIndexKey('user-1'), ['key-a', 'key-b']);
await invalidateCachedAuthUserDoc(store, { userId: 'user-1', cacheKey: 'key-c' });
expect(store.delete).toHaveBeenCalledWith(buildAuthUserDocReverseIndexKey('user-1'));
expect(store.delete).toHaveBeenCalledWith('key-a');
expect(store.delete).toHaveBeenCalledWith('key-b');
expect(store.delete).toHaveBeenCalledWith('key-c');
});
it('does not serve a document read before an eviction and written after it', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const lookupStartedAt = Date.now();
await invalidateCachedAuthUserDoc(store, { userId: userId.toString() });
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:late',
{ _id: userId, email: '[email protected]' },
lookupStartedAt,
);
expect(store.values.has('auth-user-doc:v2:late')).toBe(true);
await expect(getCachedAuthUserDoc(store, 'auth-user-doc:v2:late')).resolves.toBeUndefined();
});
it('hides a cached document the reverse index lost once the user is evicted', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const user = { _id: userId, email: '[email protected]' };
await setCachedAuthUserDoc(store, 'auth-user-doc:v2:lost', user, Date.now());
await setCachedAuthUserDoc(store, 'auth-user-doc:v2:kept', user, Date.now());
/** A concurrent read-modify-write of the index dropped the first key. */
store.values.set(buildAuthUserDocReverseIndexKey(userId.toString()), ['auth-user-doc:v2:kept']);
await invalidateCachedAuthUserDoc(store, { userId: userId.toString() });
expect(store.values.has('auth-user-doc:v2:lost')).toBe(true);
expect(store.values.has('auth-user-doc:v2:kept')).toBe(false);
await expect(getCachedAuthUserDoc(store, 'auth-user-doc:v2:lost')).resolves.toBeUndefined();
});
it('serves a document again once the eviction fence expires', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
await invalidateCachedAuthUserDoc(store, { userId: userId.toString() });
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:fresh',
{ _id: userId, email: '[email protected]' },
Date.now(),
);
await expect(getCachedAuthUserDoc(store, 'auth-user-doc:v2:fresh')).resolves.toBeUndefined();
store.values.delete(buildAuthUserDocEvictionFenceKey(userId.toString()));
await expect(getCachedAuthUserDoc(store, 'auth-user-doc:v2:fresh')).resolves.toMatchObject({
email: '[email protected]',
});
});
it('does not cache a lookup slower than the cache TTL', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:slow',
{ _id: userId, email: '[email protected]' },
Date.now() - AUTH_USER_DOC_CACHE_TTL_MS - 1,
);
expect(store.set).not.toHaveBeenCalled();
});
it('skips a cached document whose eviction fence cannot be read', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:key',
{ _id: userId, email: '[email protected]' },
Date.now(),
);
const fenceKey = buildAuthUserDocEvictionFenceKey(userId.toString());
const get = store.get;
store.get = async <T = unknown>(key: string) => {
if (key === fenceKey) {
throw new Error('redis unavailable');
}
return get<T>(key);
};
await expect(getCachedAuthUserDoc(store, 'auth-user-doc:v2:key')).resolves.toBeUndefined();
});
describe('when the write stalls after the lookup', () => {
let now: number;
beforeEach(() => {
now = 1_000_000;
jest.spyOn(Date, 'now').mockImplementation(() => now);
});
afterEach(() => {
jest.restoreAllMocks();
});
/** The index write stalls while an eviction lands, then the stale document is written. */
function stallIndexWrite(store: ReturnType<typeof makeStore>, userId: string, stallMs: number) {
const indexKey = buildAuthUserDocReverseIndexKey(userId);
store.set.mockImplementation(async (key: string, value: unknown) => {
if (key === indexKey) {
await invalidateCachedAuthUserDoc(store, { userId });
now += stallMs;
}
store.values.set(key, value);
return true;
});
}
it('anchors the expiry of a late stale document to its lookup, not to the write', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const lookupStartedAt = now;
now += 4_000;
stallIndexWrite(store, userId.toString(), 5_500);
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:stalled',
{ _id: userId, email: '[email protected]' },
lookupStartedAt,
);
const ttl = store.set.mock.calls.find(([key]) => key === 'auth-user-doc:v2:stalled')?.[2];
expect(ttl).toBe(lookupStartedAt + AUTH_USER_DOC_CACHE_TTL_MS * 2 - now);
await expect(
getCachedAuthUserDoc(store, 'auth-user-doc:v2:stalled'),
).resolves.toBeUndefined();
/** Even with the eviction fence gone and the entry somehow kept, it is past its expiry. */
store.values.delete(buildAuthUserDocEvictionFenceKey(userId.toString()));
now = lookupStartedAt + AUTH_USER_DOC_CACHE_TTL_MS * 2 + 1;
await expect(
getCachedAuthUserDoc(store, 'auth-user-doc:v2:stalled'),
).resolves.toBeUndefined();
});
it('does not serve a document that expired while its fence read stalled', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const lookupStartedAt = now;
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:unindexed',
{ _id: userId, email: '[email protected]' },
lookupStartedAt,
);
const fenceKey = buildAuthUserDocEvictionFenceKey(userId.toString());
const get = store.get;
/** The fence GET returns only after the fence and the document have both expired. */
store.get = async <T = unknown>(key: string) => {
if (key === fenceKey) {
now = lookupStartedAt + AUTH_USER_DOC_CACHE_TTL_MS * 3 + 1;
return undefined as T | undefined;
}
return get<T>(key);
};
await expect(
getCachedAuthUserDoc(store, 'auth-user-doc:v2:unindexed'),
).resolves.toBeUndefined();
});
it('does not write a document whose lookup is two TTLs old once the index write returns', async () => {
const store = makeStore();
const userId = new Types.ObjectId();
const lookupStartedAt = now;
stallIndexWrite(store, userId.toString(), AUTH_USER_DOC_CACHE_TTL_MS * 2);
await setCachedAuthUserDoc(
store,
'auth-user-doc:v2:expired',
{ _id: userId, email: '[email protected]' },
lookupStartedAt,
);
expect(store.values.has('auth-user-doc:v2:expired')).toBe(false);
});
});
it('stamps a lookup with the time before it ran', async () => {
let ranAt = 0;
const before = Date.now();
const { result, lookupStartedAt } = await timeAuthUserLookup(async () => {
ranAt = Date.now();
return { user: 'found' };
});
expect(result).toEqual({ user: 'found' });
expect(lookupStartedAt).toBeGreaterThanOrEqual(before);
expect(lookupStartedAt).toBeLessThanOrEqual(ranAt);
});
it('logs cache failures without throwing', async () => {
const store = {
get: async <T = unknown>(): Promise<T | undefined> => {
throw new Error('redis unavailable');
},
set: jest.fn(),
delete: jest.fn(),
};
await expect(getCachedAuthUserDoc(store, 'key')).resolves.toBeUndefined();
expect(logger.warn).toHaveBeenCalledWith(
'[authUserDocCache] Cache read failed; falling back to user lookup',
{ error: 'redis unavailable' },
);
});
it('serves a cached document only while the stored updatedAt and fence still match', async () => {
const store = makeStore();
const updatedAt = '2026-10-20T00:00:00.000Z';
store.values.set('key', {
version: 2,
cachedAt: Date.now(),
expiresAt: Date.now() + 60_000,
user: { _id: 'user-1', id: 'user-1', updatedAt },
});
const readStored = jest.fn();
readStored.mockResolvedValueOnce({ _id: 'user-1', updatedAt: new Date(updatedAt) });
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toMatchObject({
_id: 'user-1',
});
expect(readStored).toHaveBeenCalledWith({ _id: 'user-1' }, AUTH_USER_FRESHNESS_PROJECTION);
/** A mutation after the cached read moved updatedAt. */
readStored.mockResolvedValueOnce({ _id: 'user-1', updatedAt: new Date('2026-10-27') });
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toBeUndefined();
readStored.mockResolvedValueOnce({
_id: 'user-1',
updatedAt: new Date(updatedAt),
agentTriggerDeletionStartedAt: new Date(),
});
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toBeUndefined();
readStored.mockResolvedValueOnce(null);
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toBeUndefined();
/** A password reset stamped in the same millisecond as the write before it. */
readStored.mockResolvedValueOnce({
_id: 'user-1',
updatedAt: new Date(updatedAt),
credentialsChangedAt: new Date(updatedAt),
});
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toBeUndefined();
readStored.mockResolvedValueOnce({
_id: 'user-1',
updatedAt: new Date(updatedAt),
role: 'ADMIN',
});
await expect(
getCurrentCachedAuthUserDoc(store, 'key', { findUser: readStored }),
).resolves.toBeUndefined();
});
it('skips the freshness read on a cache miss', async () => {
const readStored = jest.fn();
await expect(
getCurrentCachedAuthUserDoc(makeStore(), 'missing', { findUser: readStored }),
).resolves.toBeUndefined();
expect(readStored).not.toHaveBeenCalled();
});
it('reads the deletion fence only for users the cache did not vouch for', async () => {
const isPrincipalActive = jest.fn(async () => false);
await expect(
isAuthUserAdmissible('user-1', { fenceChecked: true, isPrincipalActive }),
).resolves.toBe(true);
expect(isPrincipalActive).not.toHaveBeenCalled();
await expect(
isAuthUserAdmissible('user-1', { fenceChecked: false, isPrincipalActive }),
).resolves.toBe(false);
expect(isPrincipalActive).toHaveBeenCalledWith('user-1');
});
});