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 type { ConfigDraft, ConfigRecord } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { ConfigReloadReport } from '~/app/invalidation';
import type { ServerRequest } from '~/types/http';
process.env.CREDS_KEY =
process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
jest.mock('@librechat/data-schemas', () => {
process.env.CREDS_KEY =
process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
const actual = jest.requireActual('@librechat/data-schemas');
return {
...actual,
encryptV3: jest.fn((value: string) => `v3:test:${value}`),
/** Spies that keep the real validation, to see which document it was shown. */
getConfigOverrideIssues: jest.fn(actual.getConfigOverrideIssues),
getConfigFieldIssues: jest.fn(actual.getConfigFieldIssues),
};
});
import { configSchema } from 'librechat-data-provider';
import {
getConfigFieldIssues,
getConfigOverrideIssues,
ConfigRevisionConflictError,
} from '@librechat/data-schemas';
import { createAdminConfigHandlers } from './config';
function mockReq(overrides = {}) {
return {
user: { id: 'u1', role: 'ADMIN', _id: { toString: () => 'u1' } },
params: {},
body: {},
query: {},
...overrides,
} as Partial<ServerRequest> as ServerRequest;
}
interface MockRes {
statusCode: number;
body: undefined | { config?: unknown; error?: string; [key: string]: unknown };
status: jest.Mock;
json: jest.Mock;
}
function mockRes() {
const res: MockRes = {
statusCode: 200,
body: undefined,
status: jest.fn((code: number) => {
res.statusCode = code;
return res;
}),
json: jest.fn((data: MockRes['body']) => {
res.body = data;
return res;
}),
};
return res as Partial<Response> as Response & MockRes;
}
/** The document a whole-document write stores: version 1 on create, else one past the revision. */
function writtenDocument(
principalType: string,
principalId: string,
draft: ConfigDraft,
expected: string,
): ConfigRecord {
const configVersion = expected === 'absent' ? 1 : Number(expected.split(':')[1]) + 1;
return {
_id: 'c1',
principalType: principalType as ConfigRecord['principalType'],
principalId,
...draft,
configVersion,
};
}
/** The draft the handler wrote with its `n`-th whole-document write. */
function writtenDraft(deps: { writeConfigDocument: jest.Mock }, call = 0) {
return deps.writeConfigDocument.mock.calls[call][2] as Record<string, unknown> & {
overrides: Record<string, unknown>;
tombstones: string[];
priority: number;
isActive: boolean;
};
}
/** The value the handler's first whole-document write stored at a dotted path. */
function writtenField(deps: { writeConfigDocument: jest.Mock }, fieldPath: string): unknown {
return fieldPath
.split('.')
.reduce<unknown>(
(node, key) => (node as Record<string, unknown> | undefined)?.[key],
writtenDraft(deps).overrides,
);
}
function createHandlers(overrides = {}) {
const deps = {
listAllConfigs: jest.fn().mockResolvedValue([]),
findConfigByPrincipal: jest.fn().mockResolvedValue(null),
writeConfigDocument: jest.fn(
async (principalType: string, principalId: string, draft: ConfigDraft, expected: string) =>
writtenDocument(principalType, principalId, draft, expected),
),
unsetConfigField: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {} }),
deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1' }),
toggleConfigActiveTracked: jest
.fn()
.mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: true }),
hasConfigCapability: jest.fn().mockResolvedValue(true),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(true),
hasCapability: jest.fn().mockResolvedValue(true),
getAppConfig: jest.fn().mockResolvedValue({ interface: { modelSelect: true } }),
...overrides,
};
const handlers = createAdminConfigHandlers(deps);
return { handlers, deps };
}
describe('createAdminConfigHandlers', () => {
describe('listConfigs', () => {
it('redacts secret fields from config list responses', async () => {
const { handlers } = createHandlers({
listAllConfigs: jest.fn().mockResolvedValue([
{
_id: 'c1',
principalType: 'role',
principalId: 'admin',
overrides: {
langfuse: {
publicKey: 'pk-lf-1',
secretKey: 'v3:encrypted',
secretKeyPreview: 'sk-lf-...cret',
},
},
},
]),
});
const req = mockReq();
const res = mockRes();
await handlers.listConfigs(req, res);
expect(res.statusCode).toBe(200);
const configs = res.body!.configs as Array<{
overrides: { langfuse: Record<string, string> };
}>;
expect(configs[0].overrides.langfuse).toEqual({
publicKey: 'pk-lf-1',
secretKeyPreview: '*************',
});
});
});
describe('getConfig', () => {
it('returns 403 before DB lookup when user lacks READ_CONFIGS', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(false),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(403);
expect(deps.findConfigByPrincipal).not.toHaveBeenCalled();
});
it('returns 404 when config does not exist', async () => {
const { handlers } = createHandlers();
const req = mockReq({ params: { principalType: 'role', principalId: 'nonexistent' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(404);
});
it('returns config when authorized and exists', async () => {
const config = {
_id: 'c1',
principalType: 'role',
principalId: 'admin',
overrides: { x: 1 },
};
const { handlers } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(config),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.config).toEqual({ ...config, revision: 'c1:0' });
});
it('returns 400 for invalid principalType', async () => {
const { handlers } = createHandlers();
const req = mockReq({ params: { principalType: 'invalid', principalId: 'x' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(400);
});
it('rejects public principalType — not usable for config overrides', async () => {
const { handlers } = createHandlers();
const req = mockReq({ params: { principalType: 'public', principalId: 'x' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(400);
});
});
describe('read handlers: section-scoped-only caller (no broad read:configs)', () => {
function sectionOnlyDeps(section: string, overrides: Record<string, unknown> = {}) {
return {
hasConfigCapability: jest.fn(
async (_user: unknown, s: string | null, verb = 'manage') =>
verb === 'read' && s === section,
),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(true),
...overrides,
};
}
it('getConfig: returns 200 with only the held section, other sections stripped', async () => {
const config = {
_id: 'c1',
principalType: 'role',
principalId: 'admin',
overrides: { memory: { charLimit: 500 }, endpoints: { allowedAddresses: ['10.0.0.1'] } },
tombstones: ['memory.tokenLimit', 'endpoints.allowedAddresses'],
};
const { handlers } = createHandlers(
sectionOnlyDeps('memory', { findConfigByPrincipal: jest.fn().mockResolvedValue(config) }),
);
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.getConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as { overrides: Record<string, unknown>; tombstones: string[] };
expect(body.overrides.memory).toEqual({ charLimit: 500 });
expect(body.overrides.endpoints).toBeUndefined();
expect(body.tombstones).toEqual(['memory.tokenLimit']);
});
it('listConfigs: strips non-held sections from every listed config', async () => {
const configs = [
{ _id: 'c1', principalType: 'role', principalId: 'admin', overrides: { memory: {} } },
{
_id: 'c2',
principalType: 'user',
principalId: 'u1',
overrides: { endpoints: {}, memory: { charLimit: 10 } },
},
];
const { handlers } = createHandlers(
sectionOnlyDeps('memory', { listAllConfigs: jest.fn().mockResolvedValue(configs) }),
);
const req = mockReq();
const res = mockRes();
await handlers.listConfigs(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.configs as Array<{ overrides: Record<string, unknown> }>;
expect(body[0].overrides).toEqual({ memory: {} });
expect(body[1].overrides).toEqual({ memory: { charLimit: 10 } });
});
it('getBaseConfig: strips top-level sections and the nested config field to only the held section', async () => {
const appConfig = {
memory: { charLimit: 500 },
endpoints: { allowedAddresses: ['10.0.0.1'] },
fileStrategy: 's3',
config: { memory: { charLimit: 500 }, endpoints: { allowedAddresses: ['10.0.0.1'] } },
paths: { uploads: '/tmp' },
availableTools: { foo: {} },
};
const { handlers } = createHandlers(
sectionOnlyDeps('memory', { getAppConfig: jest.fn().mockResolvedValue(appConfig) }),
);
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as Record<string, unknown>;
expect(body.memory).toEqual({ charLimit: 500 });
expect(body.endpoints).toBeUndefined();
expect(body.fileStrategy).toBeUndefined();
expect((body.config as Record<string, unknown>).memory).toEqual({ charLimit: 500 });
expect((body.config as Record<string, unknown>).endpoints).toBeUndefined();
expect(body.paths).toEqual({ uploads: '/tmp' });
expect(body.availableTools).toBeUndefined();
});
it('getBaseConfig: strips availableTools when the caller holds neither of its source sections', async () => {
const appConfig = {
memory: { charLimit: 500 },
filteredTools: ['dalle'],
includedTools: ['google'],
availableTools: { google: {} },
paths: { uploads: '/tmp' },
};
const { handlers } = createHandlers(
sectionOnlyDeps('memory', { getAppConfig: jest.fn().mockResolvedValue(appConfig) }),
);
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as Record<string, unknown>;
expect(body.availableTools).toBeUndefined();
expect(body.filteredTools).toBeUndefined();
expect(body.includedTools).toBeUndefined();
});
it.each(['filteredTools', 'includedTools'])(
'getBaseConfig: returns availableTools to a caller holding read:configs:%s',
async (section) => {
const appConfig = {
filteredTools: ['dalle'],
includedTools: ['google'],
availableTools: { google: {} },
paths: { uploads: '/tmp' },
};
const { handlers } = createHandlers(
sectionOnlyDeps(section, { getAppConfig: jest.fn().mockResolvedValue(appConfig) }),
);
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as Record<string, unknown>;
expect(body.availableTools).toEqual({ google: {} });
},
);
it('getBaseConfig: returns fileStrategy only to a caller holding read:configs:fileStrategy', async () => {
const appConfig = {
fileStrategy: 's3',
memory: { charLimit: 500 },
paths: { uploads: '/tmp' },
availableTools: {},
};
const { handlers } = createHandlers(
sectionOnlyDeps('fileStrategy', { getAppConfig: jest.fn().mockResolvedValue(appConfig) }),
);
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as Record<string, unknown>;
expect(body.fileStrategy).toBe('s3');
expect(body.memory).toBeUndefined();
});
it('getBaseConfig: normalizes renamed top-level fields to their canonical section before checking read access', async () => {
// getAppConfig renames interface -> interfaceConfig, turnstile -> turnstileConfig,
// and mcpServers -> mcpConfig in the resolved payload. A caller holding
// read:configs:interface and read:configs:turnstile (but not mcpServers) must
// still see interfaceConfig/turnstileConfig, since checking the raw field name
// against a nonexistent "interfaceConfig"/"turnstileConfig" section would wrongly
// strip them.
const appConfig = {
interfaceConfig: { modelSelect: true },
turnstileConfig: { siteKey: 'abc' },
mcpConfig: { docs: {} },
paths: { uploads: '/tmp' },
availableTools: {},
};
const { handlers } = createHandlers({
hasConfigCapability: jest.fn(
async (_user: unknown, s: string | null, verb = 'manage') =>
verb === 'read' && (s === 'interface' || s === 'turnstile'),
),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(true),
getAppConfig: jest.fn().mockResolvedValue(appConfig),
});
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const body = res.body!.config as Record<string, unknown>;
expect(body.interfaceConfig).toEqual({ modelSelect: true });
expect(body.turnstileConfig).toEqual({ siteKey: 'abc' });
expect(body.mcpConfig).toBeUndefined();
});
});
describe('upsertConfigOverrides', () => {
it('returns 201 when creating a new config (configVersion === 1)', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: { interface: { modelSelect: false } } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
});
it('returns 200 when updating an existing config (configVersion > 1)', async () => {
const { handlers } = createHandlers({
findConfigByPrincipal: jest
.fn()
.mockResolvedValue({ _id: 'c1', configVersion: 5, overrides: {}, tombstones: [] }),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: { interface: { modelSelect: false } } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
});
it('returns 400 when overrides is missing', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
});
it('rejects process-backed MCP servers in database overrides', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: {
overrides: {
mcpServers: {
injected: { type: 'stdio', command: '/bin/sh', args: ['-c', 'id'] },
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Process-backed MCP servers can only be configured in librechat.yaml',
code: 'PROCESS_MCP_CONFIG',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects Langfuse header overrides, which cannot be encrypted at rest', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: {
overrides: {
langfuse: { enabled: true, headers: { 'X-Proxy-Token': 'leaked' } },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Langfuse request headers can only be configured in librechat.yaml',
code: 'LANGFUSE_HEADERS_CONFIG',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it.each([
['nested dotted key', { langfuse: { 'headers.X-Proxy-Token': 'credential' } }],
['root dotted path', { 'langfuse.headers': { 'X-Proxy-Token': 'credential' } }],
['root dotted header path', { 'langfuse.headers.X-Proxy-Token': 'credential' }],
])('rejects Langfuse headers supplied as a %s', async (_label, overrides) => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({ params: { principalType: 'user', principalId: 'u1' }, body: { overrides } }),
res,
);
/** `overrides` is a Mixed document written wholesale, so a dotted key
* persists verbatim and the nested-map redactor never walks it — the
* credential would come back in plaintext on the next read. */
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Langfuse request headers can only be configured in librechat.yaml',
code: 'LANGFUSE_HEADERS_CONFIG',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects process-backed MCP servers supplied through the runtime config alias', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: {
overrides: {
mcpConfig: {
injected: { command: '/bin/sh', args: ['-c', 'id'] },
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
issues: [{ path: 'mcpConfig', segments: ['mcpConfig'], code: 'unknown_section' }],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('strips permission fields from interface overrides but keeps UI fields', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
interface: { modelSelect: false, prompts: false, agents: { use: false } },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
const savedOverrides = writtenDraft(deps).overrides;
expect(savedOverrides.interface).toEqual({ modelSelect: false });
});
it('collapses an explicit schedules disable to the boolean form in overrides', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: { interface: { schedules: { use: false, maxPerUser: 2 } } },
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
const savedOverrides = writtenDraft(deps).overrides;
expect(savedOverrides.interface).toEqual({ schedules: false });
});
it('preserves skillSync sections in admin overrides', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
skillSync: { github: { enabled: true } },
interface: { modelSelect: false },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
const savedOverrides = writtenDraft(deps).overrides;
expect(savedOverrides.skillSync).toEqual({ github: { enabled: true } });
expect(savedOverrides.interface).toEqual({ modelSelect: false });
});
it('does not allow tenant-wide Langfuse settings through the generic config API', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: {
overrides: {
langfuse: {
enabled: false,
publicKey: 'pk-role',
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
message: 'No actionable override sections provided',
revision: null,
config: null,
applied: [],
skipped: [{ path: 'langfuse', segments: ['langfuse'], reason: 'dedicated_section' }],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects a dotted section name instead of reading it as a path', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: {
overrides: {
langfuse: { enabled: false },
'langfuse.secretKey': 'sk-role',
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
issues: [
{ path: 'langfuse.secretKey', segments: ['langfuse.secretKey'], code: 'dotted_key' },
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it.each([
['no config capability', false],
['only assign:configs for the principal type', true],
])('answers 403 before judging a dotted section name with %s', async (_label, canAssign) => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(canAssign),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'editor' },
body: { overrides: { 'webSearch.serperApiKey': 'sk-serper' } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(res.body).toEqual({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('preserves stored Langfuse settings during a full base-config replacement', async () => {
const storedLangfuse = {
enabled: true,
destination: 'eu',
publicKey: 'pk-stored',
secretKey: 'v3:test:sk-stored',
secretKeyPreview: 'sk-sto...ored',
projectId: 'project-stored',
};
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
configVersion: 1,
overrides: { langfuse: storedLangfuse },
}),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: {
overrides: {
interface: { modelSelect: false },
langfuse: {
enabled: false,
publicKey: 'pk-caller',
projectId: 'project-caller',
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
const savedOverrides = writtenDraft(deps).overrides;
expect(savedOverrides).toEqual({
interface: { modelSelect: false },
langfuse: storedLangfuse,
});
});
it('encrypts custom endpoint API keys on full override writes and redacts responses', async () => {
const { handlers, deps } = createHandlers({ overrideEnvAllowlist: 'OPENROUTER_KEY' });
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
endpoints: {
custom: [
{
name: 'OpenRouter',
apiKey: 'sk-or-secret-key',
baseURL: 'https://openrouter.ai/api/v1',
},
{ name: 'EnvRef', apiKey: '${OPENROUTER_KEY}' },
],
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
const savedOverrides = writtenDraft(deps).overrides;
const [saved, envRef] = (
savedOverrides.endpoints as { custom: Array<Record<string, string>> }
).custom;
expect(saved.apiKey).toBe('v3:test:sk-or-secret-key');
expect(saved.apiKeyPreview).toBe('...-key');
expect(envRef.apiKey).toBe('${OPENROUTER_KEY}');
expect(envRef.apiKeyPreview).toBeUndefined();
const responseConfig = res.body!.config as {
overrides: { endpoints: { custom: Array<Record<string, string>> } };
};
expect(responseConfig.overrides.endpoints.custom[0].apiKey).toBeUndefined();
expect(responseConfig.overrides.endpoints.custom[0].apiKeyPreview).toBe('...-key');
expect(responseConfig.overrides.endpoints.custom[1].apiKey).toBe('${OPENROUTER_KEY}');
});
it('rejects encrypted custom endpoint API key submissions on full override writes', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
endpoints: {
custom: [{ name: 'A', apiKey: 'v3:attacker-controlled' }],
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('preserves UI sub-keys in composite permission fields like mcpServers', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
interface: {
mcpServers: {
use: true,
create: false,
placeholder: 'Search MCP...',
trustCheckbox: { label: 'Trust' },
},
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
const savedOverrides = writtenDraft(deps).overrides;
const mcp = (savedOverrides as Record<string, unknown>).interface as Record<string, unknown>;
expect((mcp.mcpServers as Record<string, unknown>).placeholder).toBe('Search MCP...');
expect((mcp.mcpServers as Record<string, unknown>).trustCheckbox).toEqual({ label: 'Trust' });
expect((mcp.mcpServers as Record<string, unknown>).use).toBeUndefined();
expect((mcp.mcpServers as Record<string, unknown>).create).toBeUndefined();
});
it('strips peoplePicker permission sub-keys in upsert', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
interface: { peoplePicker: { users: false, groups: true, roles: true } },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('returns 200 with message when only permission fields in interface', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: { interface: { prompts: false, agents: false } } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
});
describe('deleteConfigField', () => {
it('reads fieldPath from query parameter', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.modelSelect' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
[{ segments: ['interface', 'modelSelect'] }],
undefined,
{
expectedRevision: undefined,
},
);
});
it('allows deleting mcpServers UI sub-key paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.mcpServers.placeholder' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
[{ segments: ['interface', 'mcpServers', 'placeholder'] }],
undefined,
{
expectedRevision: undefined,
},
);
});
it('blocks deleting mcpServers permission sub-key paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.mcpServers.use' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('blocks deleting peoplePicker permission sub-key paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.peoplePicker.users' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('returns 200 no-op for interface permission field path', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.prompts' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('allows deleting skillSync field paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'skillSync.github.enabled' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
[{ segments: ['skillSync', 'github', 'enabled'] }],
undefined,
{
expectedRevision: undefined,
},
);
});
it('allows deleting interface UI field paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.modelSelect' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
[{ segments: ['interface', 'modelSelect'] }],
undefined,
{
expectedRevision: undefined,
},
);
});
it('ignores tenant-wide Langfuse deletes through the generic config API', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
query: { fieldPath: 'langfuse.enabled' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
message: 'No actionable field path provided',
revision: null,
config: null,
applied: [],
skipped: [
{
path: 'langfuse.enabled',
segments: ['langfuse', 'enabled'],
reason: 'dedicated_section',
},
],
});
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('rejects deletes of the displayed secret key', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'langfuse.secretKeyPreview' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('returns 400 when fieldPath query param is missing', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: {},
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body!.error).toContain('query parameter');
});
it('rejects unsafe field paths', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: '__proto__.polluted' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(400);
});
});
describe('tombstoneConfigField', () => {
const storedAdmin = {
_id: '64b000000000000000000001',
principalType: 'role',
principalId: 'admin',
principalModel: 'Role',
priority: 7,
configVersion: 3,
isActive: false,
overrides: { mcpServers: { github: { url: 'https://example.com/mcp' } } },
tombstones: ['memory'],
};
it('writes an explicit tombstone for a valid field path', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'mcpServers.github' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
expect(deps.writeConfigDocument.mock.calls[0].slice(0, 2)).toEqual(['role', 'admin']);
expect(deps.writeConfigDocument.mock.calls[0][3]).toBe('absent');
expect(writtenDraft(deps)).toEqual({
principalModel: 'Role',
priority: 10,
overrides: {},
tombstones: ['mcpServers.github'],
isActive: true,
});
});
it('writes over the stored document, keeping its priority unless one is requested', async () => {
const kept = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(storedAdmin),
});
await kept.handlers.tombstoneConfigField(
mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'mcpServers.github' },
}),
mockRes(),
);
expect(kept.deps.writeConfigDocument.mock.calls[0][3]).toBe('64b000000000000000000001:3');
expect(writtenDraft(kept.deps)).toEqual({
principalModel: 'Role',
priority: 7,
overrides: {},
tombstones: ['memory', 'mcpServers.github'],
isActive: false,
});
const requested = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(storedAdmin),
});
await requested.handlers.tombstoneConfigField(
mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'mcpServers.github', priority: 42 },
}),
mockRes(),
);
expect(writtenDraft(requested.deps).priority).toBe(42);
});
it('suppresses a secret and its preview companion in one write', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(storedAdmin),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'ocr.apiKey', expectedRevision: '64b000000000000000000001:3' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
expect(deps.writeConfigDocument.mock.calls[0][3]).toBe('64b000000000000000000001:3');
expect(writtenDraft(deps).tombstones).toEqual(['memory', 'ocr.apiKey', 'ocr.apiKeyPreview']);
});
it('ignores tenant-wide Langfuse tombstones through the generic config API', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { fieldPath: 'langfuse.enabled' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
message: 'No actionable field path provided',
revision: null,
config: null,
applied: [],
skipped: [
{
path: 'langfuse.enabled',
segments: ['langfuse', 'enabled'],
reason: 'dedicated_section',
},
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects tombstones of the displayed secret key', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'langfuse.secretKeyPreview' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('blocks interface permission paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'interface.mcpServers.use' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('ignores tombstones for base-only filter policy', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'filters.messages.pii' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects unsafe field paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: '__proto__.polluted' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
});
describe('patchConfigField', () => {
it('returns 403 when user lacks capability for section', async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'registration.enabled', value: false }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(403);
});
it('strips interface permission field entries but keeps UI field entries', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [
{ fieldPath: 'interface.modelSelect', value: false },
{ fieldPath: 'interface.prompts', value: false },
],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'interface.modelSelect')).toBe(false);
expect(writtenField(deps, 'interface.prompts')).toBeUndefined();
});
/** `use` is both a permission bit and the runtime disable for dual-purpose fields.
* Stripping it alone leaves an object, which `getLimits` reads as ENABLED — so an
* override meant to stop scheduled billing would start it. */
it('collapses an explicit schedules disable to the boolean form in patches', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'interface.schedules', value: { use: false, maxPerUser: 2 } }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'interface.schedules')).toBe(false);
});
it('keeps a schedules object that only narrows limits', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'interface.schedules', value: { maxPerUser: 2 } }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'interface.schedules')).toEqual({ maxPerUser: 2 });
});
it('preserves skillSync field entries in patches', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [
{ fieldPath: 'skillSync.github.enabled', value: true },
{ fieldPath: 'interface.modelSelect', value: false },
],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'skillSync.github.enabled')).toBe(true);
expect(writtenField(deps, 'interface.modelSelect')).toBe(false);
});
it('rejects process-backed MCP server field patches', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: {
entries: [{ fieldPath: 'mcpServers.injected.command', value: '/bin/sh' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Process-backed MCP servers can only be configured in librechat.yaml',
code: 'PROCESS_MCP_CONFIG',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects Langfuse header field patches, including a single header path', async () => {
const { handlers, deps } = createHandlers();
for (const fieldPath of ['langfuse.headers', 'langfuse.headers.X-Proxy-Token']) {
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: { entries: [{ fieldPath, value: 'leaked' }] },
}),
res,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Langfuse request headers can only be configured in librechat.yaml',
code: 'LANGFUSE_HEADERS_CONFIG',
});
}
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects process-backed MCP field patches through the runtime config alias', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'user', principalId: 'u1' },
body: {
entries: [{ fieldPath: 'mcpConfig.injected.command', value: '/bin/sh' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({ error: 'Unknown config section', code: 'UNKNOWN_SECTION' });
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects array-valued Langfuse secret ancestors', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [
{
fieldPath: 'langfuse',
value: [{ secretKey: 'sk-lf-secret' }],
},
],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('does not allow tenant-wide Langfuse patches through the generic config API', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: {
entries: [{ fieldPath: 'langfuse.enabled', value: false }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
message: 'No actionable field entries provided',
revision: null,
config: null,
applied: [],
skipped: [
{
path: 'langfuse.enabled',
segments: ['langfuse', 'enabled'],
reason: 'dedicated_section',
},
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects direct display secret key patch entries', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'langfuse.secretKeyPreview', value: 'spoofed' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects encrypted Langfuse secret values on patch entries', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'langfuse.secretKey', value: 'v3:attacker-controlled' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects patch entries below protected Langfuse secret paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'langfuse.secretKey.hidden', value: 'sk-lf-secret' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects patch entries below protected Langfuse secretKeyPreview paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'langfuse.secretKeyPreview.hidden', value: 'spoofed' }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('blocks peoplePicker permission sub-key paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'interface.peoplePicker.users', value: false }],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('allows mcpServers UI sub-key paths but blocks permission sub-key paths', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [
{ fieldPath: 'interface.mcpServers.placeholder', value: 'Search...' },
{ fieldPath: 'interface.mcpServers.use', value: true },
],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'interface.mcpServers.placeholder')).toBe('Search...');
expect(writtenField(deps, 'interface.mcpServers.use')).toBeUndefined();
});
it('returns 200 with message when all entries are permission fields', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'interface.prompts', value: false }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.message).toBeDefined();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('returns 401 when unauthenticated even if all entries are permission fields', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'interface.prompts', value: false }] },
user: undefined,
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(401);
});
it('returns 403 when unauthorized even if all entries are permission fields', async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'interface.prompts', value: false }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(403);
});
it('rejects entries with unsafe field paths (prototype pollution)', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: '__proto__.polluted', value: true }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
});
});
/**
* A stored credential and its URL, and a patch that enters a decoy key at the credential's path
* and then writes an ancestor without it: secret preservation fills the ancestor in from the
* stored document, so the stored key, not the decoy, is what the document keeps.
*/
describe('patchConfigField: a decoy key before an ancestor that keeps the stored one', () => {
const GOOD = 'https://good.example.com/mcp';
const EVIL = 'https://evil.example.com/mcp';
/** `encryptV3` is mocked as `v3:test:<plaintext>` in this file. */
const STORED_MCP_KEY = 'v3:test:sk-original-mcp-1111';
const STORED_FIRECRAWL_KEY = 'v3:test:fc-original-key-2222';
const DECOY = 'sk-decoy-key-0000';
const stored: ConfigRecord = {
_id: 'c1',
principalType: 'role' as ConfigRecord['principalType'],
principalId: 'admin',
principalModel: 'Role' as ConfigRecord['principalModel'],
priority: 10,
isActive: true,
configVersion: 1,
tombstones: [],
overrides: {
mcpServers: {
probe: {
type: 'streamable-http',
url: GOOD,
apiKey: {
source: 'admin',
authorization_type: 'bearer',
key: STORED_MCP_KEY,
keyPreview: '...1111',
},
},
},
webSearch: {
firecrawlApiUrl: 'https://fc-good.example.com',
firecrawlApiKey: STORED_FIRECRAWL_KEY,
firecrawlApiKeyPreview: '...2222',
},
} as ConfigRecord['overrides'],
};
const keyless = (url: string) => ({
type: 'streamable-http',
url,
apiKey: { source: 'admin', authorization_type: 'bearer' },
});
async function patchStored(entries: Array<{ fieldPath: string; value: unknown }>) {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn(async (_type: string, principalId: string) =>
principalId === 'admin' ? structuredClone(stored) : null,
),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({ params: { principalType: 'role', principalId: 'admin' }, body: { entries } }),
res,
);
return { res, deps };
}
it('refuses moving a stored MCP key that a decoy entry did not replace', async () => {
const { res, deps } = await patchStored([
{ fieldPath: 'mcpServers.probe.apiKey.key', value: DECOY },
{ fieldPath: 'mcpServers.probe', value: keyless(EVIL) },
]);
expect(res.statusCode).toBe(400);
expect(res.body).toMatchObject({
code: 'MCP_API_KEY_REENTRY_REQUIRED',
server: 'probe',
fields: ['url'],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('refuses moving a stored web search key that a decoy entry did not replace', async () => {
const { res, deps } = await patchStored([
{ fieldPath: 'webSearch.firecrawlApiKey', value: DECOY },
{ fieldPath: 'webSearch', value: { firecrawlApiUrl: 'https://fc-evil.example.com' } },
]);
expect(res.statusCode).toBe(400);
expect(res.body).toMatchObject({
code: 'CONFIG_SECRET_REENTRY_REQUIRED',
issues: [
expect.objectContaining({
path: 'webSearch.firecrawlApiUrl',
secretPath: 'webSearch.firecrawlApiKey',
}),
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it("keeps the stored key's own preview when the decoy is overwritten in place", async () => {
const { res, deps } = await patchStored([
{ fieldPath: 'mcpServers.probe.apiKey.key', value: DECOY },
{ fieldPath: 'mcpServers.probe', value: keyless(GOOD) },
{ fieldPath: 'webSearch.firecrawlApiKey', value: DECOY },
{ fieldPath: 'webSearch', value: { firecrawlApiUrl: 'https://fc-good.example.com' } },
]);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'mcpServers.probe.apiKey')).toEqual({
source: 'admin',
authorization_type: 'bearer',
key: STORED_MCP_KEY,
keyPreview: '...1111',
});
expect(writtenField(deps, 'webSearch.firecrawlApiKey')).toBe(STORED_FIRECRAWL_KEY);
expect(writtenField(deps, 'webSearch.firecrawlApiKeyPreview')).toBe('...2222');
});
it('stores the decoy, with its preview, when it is written after the ancestor', async () => {
const { res, deps } = await patchStored([
{ fieldPath: 'mcpServers.probe', value: keyless(EVIL) },
{ fieldPath: 'mcpServers.probe.apiKey.key', value: DECOY },
]);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'mcpServers.probe.apiKey.key')).toBe(`v3:test:${DECOY}`);
expect(writtenField(deps, 'mcpServers.probe.apiKey.keyPreview')).toBe('...0000');
expect(writtenField(deps, 'mcpServers.probe.url')).toBe(EVIL);
});
});
describe('patchConfigField: section-scoped priority preservation', () => {
it('ignores request-supplied priority when caller lacks broad manage:configs', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),
findConfigByPrincipal: jest
.fn()
.mockResolvedValue({ _id: 'c1', priority: 7, overrides: {} }),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'memory.context', value: 'updated' }],
priority: 999,
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
const priorityArg = writtenDraft(deps).priority;
expect(priorityArg).toBe(7);
});
it('falls back to default priority when no existing doc and caller lacks broad manage', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),
findConfigByPrincipal: jest.fn().mockResolvedValue(null),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'memory.context', value: 'updated' }],
priority: 999,
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
const priorityArg = writtenDraft(deps).priority;
expect(priorityArg).toBe(10);
});
it('honors request-supplied priority when caller holds broad manage:configs', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'memory.context', value: 'updated' }],
priority: 999,
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
const priorityArg = writtenDraft(deps).priority;
expect(priorityArg).toBe(999);
/**
* The target is read once, to validate the write on top of its stored fields (not for its
* priority); Base is read beside it (the store keeps role documents to the caller's
* partition) as the floor the write lands on, and once more after the write, to see that
* the floor did not move.
*/
expect(deps.findConfigByPrincipal).toHaveBeenCalledTimes(3);
expect(deps.findConfigByPrincipal).toHaveBeenCalledWith('role', 'admin', {
includeInactive: true,
});
expect(deps.findConfigByPrincipal).toHaveBeenCalledWith('role', '__base__');
});
it('preserves priority 0 when broad caller supplies it', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'memory.context', value: 'updated' }],
priority: 0,
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
const priorityArg = writtenDraft(deps).priority;
expect(priorityArg).toBe(0);
});
it('preserves existing priority 0 for section-scoped callers', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),
findConfigByPrincipal: jest
.fn()
.mockResolvedValue({ _id: 'c1', priority: 0, overrides: {} }),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [{ fieldPath: 'memory.context', value: 'updated' }],
priority: 999,
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
const priorityArg = writtenDraft(deps).priority;
expect(priorityArg).toBe(0);
});
});
describe('tombstoneConfigField: section-scoped priority preservation', () => {
const storedAt = (priority: number) =>
jest.fn().mockResolvedValue({
_id: 'c1',
principalType: 'role',
principalId: 'admin',
priority,
configVersion: 1,
isActive: true,
overrides: {},
tombstones: [],
});
it('ignores request-supplied priority when caller lacks broad manage:configs', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),
findConfigByPrincipal: storedAt(15),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'memory.context', priority: 999 },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenDraft(deps).priority).toBe(15);
});
it('honors request-supplied priority when caller holds broad manage:configs', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
findConfigByPrincipal: storedAt(15),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'memory.context', priority: 999 },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(writtenDraft(deps).priority).toBe(999);
});
});
describe('upsertConfigOverrides — Bug 2 regression', () => {
it('returns 403 for empty overrides when user lacks MANAGE_CONFIGS', async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {} },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
});
});
describe('upsertConfigOverrides — empty-overrides scope creation', () => {
it('creates config document when overrides is empty but priority is provided', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(res.body?.config).toHaveProperty('_id', 'c1');
expect(res.body?.config).toHaveProperty('revision', 'c1:1');
expect(deps.writeConfigDocument).toHaveBeenCalledWith(
'role',
'admin',
{ principalModel: 'Role', priority: 5, overrides: {}, tombstones: [], isActive: true },
'absent',
);
});
it('returns no-op message when overrides is empty and no priority is provided', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {} },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(res.body).toHaveProperty('message', 'No actionable override sections provided');
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('calls general manage check exactly once when overrides is empty with priority', async () => {
const hasConfigCapability = jest.fn().mockResolvedValue(true);
const { handlers } = createHandlers({ hasConfigCapability });
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 3 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(hasConfigCapability).toHaveBeenCalledTimes(1);
expect(hasConfigCapability).toHaveBeenCalledWith(expect.anything(), null, 'manage');
expect(res.statusCode).toBe(201);
expect(res.body).toHaveProperty('config');
});
it('returns 403 for empty overrides with priority when user lacks MANAGE_CONFIGS', async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
});
it('returns 401 for empty overrides with priority when unauthenticated', async () => {
const { handlers } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
user: undefined,
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(401);
});
});
// ── Invariant tests: rules that must hold across ALL handlers ──────
const MUTATION_HANDLERS: Array<{
name: string;
reqOverrides: Record<string, unknown>;
}> = [
{
name: 'upsertConfigOverrides',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: { interface: { modelSelect: false } } },
},
},
{
name: 'patchConfigField',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'interface.modelSelect', value: false }] },
},
},
{
name: 'deleteConfigField',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
query: { fieldPath: 'interface.modelSelect' },
},
},
{
name: 'tombstoneConfigField',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
body: { fieldPath: 'mcpServers.github' },
},
},
{
name: 'deleteConfigOverrides',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
},
},
{
name: 'toggleConfig',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
body: { isActive: false },
},
},
{
name: 'applyConfigChanges',
reqOverrides: {
params: { principalType: 'role', principalId: 'admin' },
body: { ops: [{ op: 'set', fieldPath: 'interface.modelSelect', value: false }] },
},
},
{ name: 'reloadConfig', reqOverrides: {} },
];
describe('upsertConfigOverrides: scope-lifecycle auth (ASSIGN_CONFIGS)', () => {
it('allows empty-overrides scope creation when caller has ASSIGN_CONFIGS only', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(deps.writeConfigDocument).toHaveBeenCalledWith(
'role',
'admin',
{ principalModel: 'Role', priority: 10, overrides: {}, tombstones: [], isActive: true },
'absent',
);
});
it('keeps the stored priority and reactivates an empty profile for an ASSIGN_CONFIGS-only caller', async () => {
const findConfigByPrincipal = jest.fn().mockResolvedValue({
_id: 'c1',
priority: 7,
configVersion: 2,
isActive: false,
overrides: { balance: {} },
tombstones: [],
});
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
findConfigByPrincipal,
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 999 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledWith(
'role',
'admin',
{ principalModel: 'Role', priority: 7, overrides: {}, tombstones: [], isActive: true },
'c1:2',
);
});
it('rejects non-empty overrides for ASSIGN_CONFIGS-only caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: { memory: { enabled: true } } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects empty-overrides scope creation when caller has neither grant', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
});
describe('deleteConfigOverrides: accepts ASSIGN_CONFIGS', () => {
it('allows delete when caller has ASSIGN_CONFIGS only', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(deps.deleteConfig).toHaveBeenCalled();
});
it('rejects delete when caller has neither broad manage nor ASSIGN_CONFIGS', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.deleteConfig).not.toHaveBeenCalled();
});
});
describe('toggleConfig: accepts ASSIGN_CONFIGS', () => {
it('allows toggle when caller has ASSIGN_CONFIGS only', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { isActive: false },
});
const res = mockRes();
await handlers.toggleConfig(req, res);
expect(res.statusCode).toBe(200);
expect(deps.toggleConfigActiveTracked).toHaveBeenCalled();
});
it('rejects toggle when caller has neither broad manage nor ASSIGN_CONFIGS', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { isActive: false },
});
const res = mockRes();
await handlers.toggleConfig(req, res);
expect(res.statusCode).toBe(403);
expect(deps.toggleConfigActiveTracked).not.toHaveBeenCalled();
});
});
describe('scope-lifecycle: parameterized assign:configs check', () => {
it('allows upsert when caller holds assign:configs:<principalType>', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn(async (_user, cap) => cap === 'assign:configs:role'),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(writtenDraft(deps)).toEqual(
expect.objectContaining({ overrides: {}, priority: 10, isActive: true }),
);
});
it('rejects upsert when parameterized grant targets a different principalType', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn(async (_user, cap) => cap === 'assign:configs:user'),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('queries hasCapability with the principalType-parameterized form', async () => {
const hasCap = jest.fn().mockResolvedValue(true);
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: hasCap,
});
const req = mockReq({
params: { principalType: 'group', principalId: 'engineers' },
body: { isActive: false },
});
const res = mockRes();
await handlers.toggleConfig(req, res);
const queriedCapabilities = hasCap.mock.calls.map((call) => call[1]);
expect(queriedCapabilities).toContain('assign:configs:group');
});
});
describe('invariant: __base__ requires broad manage:configs', () => {
it('upsert against __base__ returns 403 for assign-only caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('delete against __base__ returns 403 for assign-only caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
});
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.deleteConfig).not.toHaveBeenCalled();
});
it('toggle against __base__ returns 403 for assign-only caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { isActive: false },
});
const res = mockRes();
await handlers.toggleConfig(req, res);
expect(res.statusCode).toBe(403);
expect(deps.toggleConfigActiveTracked).not.toHaveBeenCalled();
});
it('upsert against __base__ succeeds for broad-manage caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(deps.writeConfigDocument).toHaveBeenCalled();
});
it('patch against __base__ returns 403 for a section-scoped manager', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { entries: [{ fieldPath: 'memory.context', value: 'updated' }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('tombstone against __base__ returns 403 for a section-scoped manager', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { fieldPath: 'memory.context' },
});
const res = mockRes();
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('field delete against __base__ returns 403 for a section-scoped manager', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
query: { fieldPath: 'memory.context' },
});
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(403);
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('patch against __base__ succeeds for a broad-manage caller', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
});
const req = mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: { entries: [{ fieldPath: 'memory.context', value: 'updated' }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalled();
});
});
describe('scope-lifecycle: atomic empty-state guard for assign-only callers', () => {
it('empty-overrides upsert is rejected when the stored profile is not empty', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
configVersion: 3,
overrides: { memory: { disabled: true } },
tombstones: [],
}),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('empty-overrides upsert is rejected when the stored profile only holds tombstones', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
configVersion: 3,
overrides: {},
tombstones: ['mcpServers.github'],
}),
});
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
}),
res,
);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('delete is rejected with 403 when atomic filter mismatches and doc still exists', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
deleteConfig: jest.fn(async (_pt, _pi, _session, opts) => {
return opts?.expectEmpty ? null : { _id: 'c1' };
}),
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
overrides: { endpoints: { custom: true } },
}),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.deleteConfig).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
undefined,
{ expectEmpty: true },
);
});
it('toggle is rejected with 403 when atomic filter mismatches and doc still exists', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
toggleConfigActiveTracked: jest.fn(async (_pt, _pi, _isActive, opts) => {
return opts?.expectEmpty
? null
: { config: { _id: 'c1', isActive: false }, changed: true };
}),
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
tombstones: ['endpoints.openai.apiKey'],
}),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { isActive: false },
});
const res = mockRes();
await handlers.toggleConfig(req, res);
expect(res.statusCode).toBe(403);
expect(deps.toggleConfigActiveTracked).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.anything(),
{ expectEmpty: true },
);
});
it('delete returns 404 when atomic filter mismatches and doc does not exist', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
deleteConfig: jest.fn().mockResolvedValue(null),
findConfigByPrincipal: jest.fn().mockResolvedValue(null),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(404);
expect(deps.findConfigByPrincipal).toHaveBeenCalled();
});
it('delete succeeds for assign-only caller when atomic filter matches', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(true),
deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {} }),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(deps.deleteConfig).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
undefined,
{ expectEmpty: true },
);
});
it('broad-manage caller calls destructive op without expectEmpty option', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(true),
deleteConfig: jest.fn().mockResolvedValue({
_id: 'c1',
overrides: { endpoints: { custom: true } },
}),
});
const req = mockReq({ params: { principalType: 'role', principalId: 'admin' } });
const res = mockRes();
await handlers.deleteConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(deps.deleteConfig).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
undefined,
{ expectEmpty: false },
);
});
});
describe('AdminConfigDeps.hasCapability is optional', () => {
it('factory accepts deps without hasCapability and falls back to broad-manage-only auth', async () => {
const deps = {
listAllConfigs: jest.fn().mockResolvedValue([]),
findConfigByPrincipal: jest.fn().mockResolvedValue(null),
writeConfigDocument: jest.fn(),
unsetConfigField: jest.fn(),
deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1' }),
/** The document as it was before the write. */
toggleConfigActiveTracked: jest
.fn()
.mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: true }),
hasConfigCapability: jest.fn().mockResolvedValue(false),
};
const handlers = createAdminConfigHandlers(deps);
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { overrides: {}, priority: 5 },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
});
describe('invariant: all mutation handlers return 401 without auth', () => {
for (const { name, reqOverrides } of MUTATION_HANDLERS) {
it(`${name} returns 401 when user is missing`, async () => {
const { handlers } = createHandlers();
const req = mockReq({ ...reqOverrides, user: undefined });
const res = mockRes();
await (handlers as Record<string, (...args: unknown[]) => Promise<unknown>>)[name](
req,
res,
);
expect(res.statusCode).toBe(401);
});
}
});
describe('invariant: all mutation handlers return 403 without capability', () => {
for (const { name, reqOverrides } of MUTATION_HANDLERS) {
it(`${name} returns 403 when user lacks capability`, async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const req = mockReq(reqOverrides);
const res = mockRes();
await (handlers as Record<string, (...args: unknown[]) => Promise<unknown>>)[name](
req,
res,
);
expect(res.statusCode).toBe(403);
});
}
});
describe('invariant: all read handlers return 403 without capability', () => {
const READ_HANDLERS: Array<{ name: string; reqOverrides: Record<string, unknown> }> = [
{ name: 'listConfigs', reqOverrides: {} },
{ name: 'getBaseConfig', reqOverrides: {} },
{
name: 'getConfig',
reqOverrides: { params: { principalType: 'role', principalId: 'admin' } },
},
];
for (const { name, reqOverrides } of READ_HANDLERS) {
it(`${name} returns 403 when user lacks capability`, async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(false),
});
const req = mockReq(reqOverrides);
const res = mockRes();
await (handlers as Record<string, (...args: unknown[]) => Promise<unknown>>)[name](
req,
res,
);
expect(res.statusCode).toBe(403);
});
}
});
describe('invariant: all read handlers return 401 without auth', () => {
const READ_HANDLERS: Array<{ name: string; reqOverrides: Record<string, unknown> }> = [
{ name: 'listConfigs', reqOverrides: {} },
{ name: 'getBaseConfig', reqOverrides: {} },
{
name: 'getConfig',
reqOverrides: { params: { principalType: 'role', principalId: 'admin' } },
},
];
for (const { name, reqOverrides } of READ_HANDLERS) {
it(`${name} returns 401 when user is missing`, async () => {
const { handlers } = createHandlers();
const req = mockReq({ ...reqOverrides, user: undefined });
const res = mockRes();
await (handlers as Record<string, (...args: unknown[]) => Promise<unknown>>)[name](
req,
res,
);
expect(res.statusCode).toBe(401);
});
}
});
describe('getBaseConfig', () => {
it('returns 403 when user lacks READ_CONFIGS', async () => {
const { handlers } = createHandlers({
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasAnyConfigReadAccess: jest.fn().mockResolvedValue(false),
});
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(403);
});
it('returns the full AppConfig', async () => {
const { handlers } = createHandlers();
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
expect(res.body!.config).toEqual({ interface: { modelSelect: true } });
});
it('redacts Langfuse secrets from top-level and raw nested base config', async () => {
const { handlers } = createHandlers({
getAppConfig: jest.fn().mockResolvedValue({
langfuse: {
publicKey: 'pk-lf-1',
secretKey: 'sk-lf-secret',
secretKeyPreview: 'sk-lf-...cret',
},
config: {
langfuse: {
publicKey: 'pk-lf-1',
secretKey: 'sk-lf-raw-secret',
secretKeyPreview: 'sk-lf-...cret',
},
},
}),
});
const req = mockReq();
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
const responseConfig = res.body!.config as {
langfuse: Record<string, string>;
config: { langfuse: Record<string, string> };
};
expect(responseConfig.langfuse).toEqual({
publicKey: 'pk-lf-1',
secretKeyPreview: '*************',
});
expect(responseConfig.config.langfuse).toEqual({
publicKey: 'pk-lf-1',
secretKeyPreview: '*************',
});
});
it('forwards baseOnly=true to getAppConfig when query param is the literal string "true"', async () => {
const getAppConfig = jest.fn().mockResolvedValue({ interface: { modelSelect: true } });
const { handlers } = createHandlers({ getAppConfig });
const req = mockReq({ query: { baseOnly: 'true' } });
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
expect(getAppConfig).toHaveBeenCalledTimes(1);
expect(getAppConfig).toHaveBeenCalledWith(expect.objectContaining({ baseOnly: true }));
});
it('previews a plaintext secret an override stored by its value, and a librechat.yaml one only with the fixed mask', async () => {
const yaml = {
webSearch: {
serperApiKey: 'serper-yaml-literal-0001',
keenableApiKey: '${KEENABLE_API_KEY}',
},
};
const merged = {
webSearch: {
serperApiKey: 'serper-yaml-literal-0001',
keenableApiKey: 'kn-legacy-plain-0002',
},
};
const getAppConfig = jest.fn(async ({ baseOnly }: { baseOnly?: boolean }) =>
baseOnly ? yaml : merged,
);
const { handlers } = createHandlers({ getAppConfig });
const res = mockRes();
await handlers.getBaseConfig(mockReq(), res);
const baseOnlyRes = mockRes();
await handlers.getBaseConfig(mockReq({ query: { baseOnly: 'true' } }), baseOnlyRes);
expect(res.statusCode).toBe(200);
expect(JSON.stringify(res.body)).not.toContain('kn-legacy-plain-0002');
expect(JSON.stringify(res.body)).not.toContain('0001');
expect((res.body!.config as typeof merged).webSearch).toEqual({
keenableApiKeyPreview: '...0002',
serperApiKeyPreview: '********',
});
expect((baseOnlyRes.body!.config as typeof yaml).webSearch).toEqual({
keenableApiKey: '${KEENABLE_API_KEY}',
serperApiKeyPreview: '********',
});
});
it('forwards baseOnly=false when the query param is missing, non-"true", or an array', async () => {
const cases: Array<Record<string, unknown>> = [
{},
{ baseOnly: 'false' },
{ baseOnly: '1' },
{ baseOnly: ['true'] },
{ baseOnly: ['true', 'true'] },
{ baseOnly: { nested: 'true' } },
];
for (const query of cases) {
const getAppConfig = jest.fn().mockResolvedValue({ interface: { modelSelect: true } });
const { handlers } = createHandlers({ getAppConfig });
const req = mockReq({ query });
const res = mockRes();
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
expect(getAppConfig).toHaveBeenNthCalledWith(
1,
expect.objectContaining({ baseOnly: false }),
);
}
});
});
describe('override validation against configSchema', () => {
it('rejects a whole-document write with an invalid field and stores nothing', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: { githubCompare: { timeoutMs: 0 }, interface: { modelSelect: false } },
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
issues: [
{
path: 'githubCompare.timeoutMs',
segments: ['githubCompare', 'timeoutMs'],
code: 'too_small',
params: { minimum: 1, inclusive: true, exact: false, type: 'number' },
},
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('validates a whole-document write on the base its retained tombstones leave', async () => {
/** A reset refill needs a whole interval; only a stored tombstone of the mode lifts that. */
const base = { config: { balance: { refillMode: 'reset' } } };
const body = { overrides: { balance: { refillIntervalValue: 1.5 } } };
const params = { principalType: 'role', principalId: 'admin' };
const kept = createHandlers({ getAppConfig: jest.fn().mockResolvedValue(base) });
const keptRes = mockRes();
await kept.handlers.upsertConfigOverrides(mockReq({ params, body }), keptRes);
expect(keptRes.statusCode).toBe(400);
expect(keptRes.body?.issues).toEqual([
expect.objectContaining({ path: 'balance.refillIntervalValue', code: 'custom' }),
]);
expect(kept.deps.writeConfigDocument).not.toHaveBeenCalled();
const tombstoned = createHandlers({
getAppConfig: jest.fn().mockResolvedValue(base),
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
configVersion: 1,
overrides: {},
tombstones: ['balance.refillMode'],
}),
});
const tombstonedRes = mockRes();
await tombstoned.handlers.upsertConfigOverrides(mockReq({ params, body }), tombstonedRes);
expect(tombstonedRes.statusCode).toBe(200);
expect(tombstoned.deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('accepts a partial section whose provided fields are valid', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
registration: { allowedDomains: ['example.com'] },
mcpServers: { github: { timeout: 5000 } },
endpoints: { custom: [{ name: 'groq', apiKey: 'sk-test' }] },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('rejects one write that names a custom endpoint twice in spellings the runtime folds', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
endpoints: {
custom: [
{ name: 'Ollama', baseURL: 'http://first:11434/v1' },
{ name: 'ollama', baseURL: 'http://second:11434/v1' },
],
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(400);
expect(res.body?.issues).toEqual([
{
path: 'endpoints.custom.0',
segments: ['endpoints', 'custom', '0'],
code: 'duplicate_merge_key',
},
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('accepts an override spelled `ollama` onto the YAML `Ollama` it merges into', async () => {
const { handlers, deps } = createHandlers({
getAppConfig: jest.fn().mockResolvedValue({
config: {
endpoints: {
custom: [
{
name: 'Ollama',
apiKey: 'ollama',
baseURL: 'http://yaml-host:11434/v1',
models: { default: ['llama3'] },
},
],
},
},
}),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
endpoints: { custom: [{ name: 'ollama', modelDisplayLabel: 'Local' }] },
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('keeps the key a stored two-spelling `Ollama` document applies when a write omits it', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
configVersion: 1,
priority: 10,
overrides: {
endpoints: {
custom: [
{
name: 'Ollama',
baseURL: 'http://override-first:11434/v1',
apiKey: 'v3:test:sk-ollama-first-key',
apiKeyPreview: '...-key',
},
{ name: 'ollama', modelDisplayLabel: 'legacy-second' },
],
},
},
}),
});
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
endpoints: {
custom: [{ name: 'ollama', baseURL: 'http://override-first:11434/v1' }],
},
},
},
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(200);
expect(writtenField(deps, 'endpoints.custom')).toEqual([
{
name: 'ollama',
baseURL: 'http://override-first:11434/v1',
apiKey: 'v3:test:sk-ollama-first-key',
apiKeyPreview: '...-key',
},
]);
});
it('rejects a field patch with an invalid value and writes no entry', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
entries: [
{ fieldPath: 'interface.customWelcome', value: 'hi' },
{ fieldPath: 'githubCompare.timeoutMs', value: 'soon' },
],
},
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body?.issues).toEqual([
{
path: 'githubCompare.timeoutMs',
segments: ['githubCompare', 'timeoutMs'],
code: 'invalid_type',
params: { expected: 'number', received: 'string' },
},
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('validates an object patch as a partial of the addressed section', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'interface.schedules', value: { maxPerUser: 'x' } }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body?.issues).toEqual([
expect.objectContaining({ path: 'interface.schedules.maxPerUser' }),
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('rejects a Base policy link that would run script and stores nothing', async () => {
const { handlers, deps } = createHandlers();
const params = { principalType: 'role', principalId: '__base__' };
const documentRes = mockRes();
const fieldRes = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params,
body: {
overrides: {
interface: {
privacyPolicy: { externalUrl: 'javascript:alert(document.domain)' },
termsOfService: { externalUrl: 'https://example.com/terms' },
},
},
},
}),
documentRes,
);
await handlers.patchConfigField(
mockReq({
params,
body: {
entries: [
{
fieldPath: 'interface.termsOfService.externalUrl',
value: '\u00a0JavaScript:alert(document.domain)',
},
],
},
}),
fieldRes,
);
expect(documentRes.statusCode).toBe(400);
expect(documentRes.body?.issues).toEqual([
{
path: 'interface.privacyPolicy.externalUrl',
segments: ['interface', 'privacyPolicy', 'externalUrl'],
code: 'custom',
},
]);
expect(fieldRes.statusCode).toBe(400);
expect(fieldRes.body?.issues).toEqual([
{
path: 'interface.termsOfService.externalUrl',
segments: ['interface', 'termsOfService', 'externalUrl'],
code: 'custom',
},
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('keeps accepting http(s), relative and blank policy links', async () => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params: { principalType: 'role', principalId: '__base__' },
body: {
overrides: {
interface: {
privacyPolicy: { externalUrl: 'https://example.com/privacy', openNewTab: true },
termsOfService: { externalUrl: '/terms', modalAcceptance: true },
},
},
},
}),
res,
);
expect(res.statusCode).toBe(201);
expect(writtenDraft(deps).overrides.interface).toEqual({
privacyPolicy: { externalUrl: 'https://example.com/privacy', openNewTab: true },
termsOfService: { externalUrl: '/terms', modalAcceptance: true },
});
});
it('skips a Turnstile write to Base, which stays on librechat.yaml', async () => {
const { handlers, deps } = createHandlers();
const params = { principalType: 'role', principalId: '__base__' };
const documentRes = mockRes();
const fieldRes = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params,
body: {
overrides: { turnstile: { siteKey: 'stored-key' }, interface: { modelSelect: false } },
},
}),
documentRes,
);
await handlers.patchConfigField(
mockReq({ params, body: { entries: [{ fieldPath: 'turnstile.siteKey', value: 'k' }] } }),
fieldRes,
);
const removals = [mockRes(), mockRes()];
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'turnstile' } }),
removals[0],
);
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'turnstile.siteKey' } }),
removals[1],
);
expect(documentRes.statusCode).toBe(201);
expect(writtenDraft(deps).overrides).toEqual({ interface: { modelSelect: false } });
expect(fieldRes.statusCode).toBe(200);
expect(removals.map((res) => res.statusCode)).toEqual([200, 200]);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
it('refuses a Turnstile tombstone under its AppConfig name and removes a stored one', async () => {
const { handlers, deps } = createHandlers({
unsetConfigField: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {}, tombstones: [] }),
});
const params = { principalType: 'role', principalId: '__base__' };
const tombstoneRes = mockRes();
const deleteRes = mockRes();
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'turnstileConfig' } }),
tombstoneRes,
);
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'turnstileConfig.siteKey' } }),
deleteRes,
);
expect(tombstoneRes.statusCode).toBe(400);
expect(tombstoneRes.body).toEqual({
error: 'Unknown config section',
code: 'UNKNOWN_SECTION',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deleteRes.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'__base__',
[{ segments: ['turnstileConfig', 'siteKey'] }],
undefined,
{ expectedRevision: undefined },
);
});
it('rejects a patch that addresses a custom endpoint by index', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'endpoints.custom.0.models', value: { default: ['m'] } }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(400);
expect(res.body?.issues).toEqual([
{
path: 'endpoints.custom',
segments: ['endpoints', 'custom'],
code: 'indexed_merge_key_write',
},
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('accepts a secret field cleared with a non-string value', async () => {
const { handlers, deps } = createHandlers();
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: { entries: [{ fieldPath: 'ocr.apiKey', value: null }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
});
describe('audit entries', () => {
const target = { type: 'config', id: 'role:editor', name: 'role:editor' };
const params = { principalType: 'role', principalId: 'editor' };
it('removes a secret and its preview in one write and records one entry', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);
const { handlers, deps } = createHandlers({ recordAuditEntry, invalidateConfigCaches });
const req = mockReq({ params, query: { fieldPath: 'ocr.apiKey' } });
const res = mockRes();
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledTimes(1);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'editor',
[{ segments: ['ocr', 'apiKey'] }, { segments: ['ocr', 'apiKeyPreview'] }],
undefined,
{ expectedRevision: undefined },
);
expect(invalidateConfigCaches).toHaveBeenCalledTimes(1);
expect(recordAuditEntry).toHaveBeenCalledTimes(1);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.updated',
target,
metadata: { operation: 'unset', fieldPath: 'ocr.apiKey' },
}),
);
});
it('records nothing and invalidates nothing when the write fails', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
invalidateConfigCaches,
unsetConfigField: jest.fn().mockRejectedValue(new Error('write failed')),
});
const res = mockRes();
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'ocr.apiKey' } }),
res,
);
expect(res.statusCode).toBe(500);
expect(res.body).toEqual({ error: 'Failed to delete config field' });
expect(invalidateConfigCaches).not.toHaveBeenCalled();
expect(recordAuditEntry).not.toHaveBeenCalled();
});
it('records config.created for a new override document', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({ recordAuditEntry });
const req = mockReq({
params,
body: { overrides: { interface: { modelSelect: false } } },
});
const res = mockRes();
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(201);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.created',
actor: expect.objectContaining({ type: 'user', id: 'u1' }),
target,
metadata: { operation: 'replace', sections: 'interface', priority: 10 },
}),
);
});
it('records config.updated for a patch with field paths but no values', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
findConfigByPrincipal: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {} }),
});
const req = mockReq({
params,
body: { entries: [{ fieldPath: 'registration.enabled', value: false }] },
});
const res = mockRes();
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.updated',
target,
metadata: { operation: 'patch', fieldPaths: 'registration.enabled' },
}),
);
});
it('records config.created when the first tombstone creates the document', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({ recordAuditEntry });
const res = mockRes();
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'mcpServers.github' } }),
res,
);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({ action: 'config.created' }),
);
});
it('records tombstone and unset field operations', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: 'c1',
principalType: 'role',
principalId: 'editor',
priority: 10,
configVersion: 2,
isActive: true,
overrides: {},
tombstones: [],
}),
});
const tombstoneRes = mockRes();
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'mcpServers.github' } }),
tombstoneRes,
);
const unsetRes = mockRes();
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'registration.enabled' } }),
unsetRes,
);
expect(tombstoneRes.statusCode).toBe(200);
expect(unsetRes.statusCode).toBe(200);
expect(recordAuditEntry).toHaveBeenNthCalledWith(
1,
expect.objectContaining({
action: 'config.updated',
metadata: { operation: 'tombstone', fieldPath: 'mcpServers.github' },
}),
);
expect(recordAuditEntry).toHaveBeenNthCalledWith(
2,
expect.objectContaining({
action: 'config.updated',
metadata: { operation: 'unset', fieldPath: 'registration.enabled' },
}),
);
});
it('records config.deleted and config.toggled', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({ recordAuditEntry });
await handlers.deleteConfigOverrides(mockReq({ params }), mockRes());
await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), mockRes());
expect(recordAuditEntry).toHaveBeenNthCalledWith(
1,
expect.objectContaining({ action: 'config.deleted', target }),
);
expect(recordAuditEntry).toHaveBeenNthCalledWith(
2,
expect.objectContaining({
action: 'config.toggled',
target,
metadata: { isActive: false },
}),
);
});
it('does not record a toggle that leaves isActive unchanged', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
toggleConfigActiveTracked: jest
.fn()
.mockResolvedValue({ config: { _id: 'c1', isActive: false }, changed: false }),
});
const res = mockRes();
await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), res);
expect(res.statusCode).toBe(200);
expect(recordAuditEntry).not.toHaveBeenCalled();
});
it('does not record when the override document is missing', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
deleteConfig: jest.fn().mockResolvedValue(null),
});
const res = mockRes();
await handlers.deleteConfigOverrides(mockReq({ params }), res);
expect(res.statusCode).toBe(404);
expect(recordAuditEntry).not.toHaveBeenCalled();
});
it('does not record a denied mutation', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
recordAuditEntry,
hasConfigCapability: jest.fn().mockResolvedValue(false),
hasCapability: jest.fn().mockResolvedValue(false),
});
const res = mockRes();
await handlers.toggleConfig(mockReq({ params, body: { isActive: true } }), res);
expect(res.statusCode).toBe(403);
expect(recordAuditEntry).not.toHaveBeenCalled();
});
});
describe('override sections outside configSchema', () => {
/** Runtime state AppService builds that `configSchema` does not define, so no override may set it. */
const RUNTIME_KEYS = [
'paths',
'config',
'availableTools',
'interfaceConfig',
'turnstileConfig',
'mcpConfig',
];
const MARKER = '/tmp/attacker-controlled';
const params = { principalType: 'role', principalId: 'admin' };
const UNKNOWN_SECTION = { error: 'Unknown config section', code: 'UNKNOWN_SECTION' };
it.each(RUNTIME_KEYS)('rejects a whole-document write holding `%s`', async (key) => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params,
body: { overrides: { [key]: { uploads: MARKER }, registration: { enabled: false } } },
}),
res,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
issues: [{ path: key, segments: [key], code: 'unknown_section' }],
});
expect(JSON.stringify(res.body)).not.toContain(MARKER);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it.each([
'paths.uploads',
'config.permissions',
'config',
'interfaceConfig.prompts',
'turnstileConfig.siteKey',
'mcpConfig.remote.url',
'availableTools.calculator',
])('rejects a field write to `%s` without echoing the path', async (fieldPath) => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.patchConfigField(
mockReq({ params, body: { entries: [{ fieldPath, value: MARKER }] } }),
res,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual(UNKNOWN_SECTION);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deps.findConfigByPrincipal).not.toHaveBeenCalled();
});
it('rejects the whole batch when any entry addresses an unknown section', async () => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: {
entries: [
{ fieldPath: 'registration.enabled', value: false },
{ fieldPath: 'paths.uploads', value: MARKER },
],
},
}),
res,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual(UNKNOWN_SECTION);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('still accepts keys the schema does not define inside a known section', async () => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'registration.futureOption', value: 1 }] },
}),
res,
);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
expect(writtenDraft(deps).overrides).toEqual({ registration: { futureOption: 1 } });
});
it.each(['paths', 'paths.uploads', 'config.permissions', 'interfaceConfig.prompts'])(
'rejects a tombstone on `%s`',
async (fieldPath) => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.tombstoneConfigField(mockReq({ params, body: { fieldPath } }), res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual(UNKNOWN_SECTION);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deps.findConfigByPrincipal).not.toHaveBeenCalled();
},
);
it('lets a broad manager remove a value stored under an unknown section', async () => {
const { handlers, deps } = createHandlers({
unsetConfigField: jest.fn().mockResolvedValue({ _id: 'c1', overrides: {}, tombstones: [] }),
});
const res = mockRes();
await handlers.deleteConfigField(mockReq({ params, query: { fieldPath: 'paths' } }), res);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
[{ segments: ['paths'] }],
undefined,
{
expectedRevision: undefined,
},
);
});
it('does not let a section-scoped manager remove a value under an unknown section', async () => {
const { handlers, deps } = createHandlers({
hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),
});
const res = mockRes();
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'paths.uploads' } }),
res,
);
expect(res.statusCode).toBe(403);
expect(deps.unsetConfigField).not.toHaveBeenCalled();
});
});
describe('write responses: filtered by read access', () => {
const params = { principalType: 'role', principalId: 'editors' };
function writtenDoc() {
return {
_id: 'c1',
principalType: 'role',
principalId: 'editors',
priority: 10,
configVersion: 2,
isActive: true,
overrides: {
endpoints: {
agents: { disableBuilder: true },
custom: [{ name: 'groq', apiKey: 'v3:endpoint-cipher', apiKeyPreview: '...abcd' }],
},
memory: { charLimit: 500 },
webSearch: {
searchProvider: 'serper',
serperApiKey: 'v3:serper-cipher',
serperApiKeyPreview: '...wxyz',
},
},
tombstones: ['endpoints.bedrock', 'memory.tokenLimit', 'webSearch.jinaApiUrl'],
};
}
/** A caller holding only the listed `<verb>:configs:<section>` grants, never the broad ones. */
function scopedCapability(grants: string[]) {
return jest.fn(
async (_user: unknown, section: string | null, verb = 'manage') =>
section != null && grants.includes(`${verb}:${section}`),
);
}
type WrittenBody = { overrides: Record<string, unknown>; tombstones: string[] };
it('PATCH: a section manager sees only the sections it wrote', async () => {
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
expect(res.statusCode).toBe(200);
const body = res.body!.config as WrittenBody;
expect(Object.keys(body.overrides)).toEqual(['endpoints']);
expect(body.tombstones).toEqual(['endpoints.bedrock']);
expect(body).toMatchObject({ principalId: 'editors', priority: 10, configVersion: 2 });
expect(JSON.stringify(res.body)).not.toMatch(/charLimit|serper|cipher/);
});
it('PATCH: adds the other sections the caller can read', async () => {
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints', 'read:memory']),
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
const body = res.body!.config as WrittenBody;
expect(Object.keys(body.overrides).sort()).toEqual(['endpoints', 'memory']);
expect(body.tombstones).toEqual(['endpoints.bedrock', 'memory.tokenLimit']);
});
it('PATCH: uses the batched read lookup, once and before the write', async () => {
const getReadableConfigSections = jest
.fn()
.mockResolvedValue({ broad: false, sections: new Set(['webSearch']) });
const writeConfigDocument = jest.fn().mockResolvedValue(writtenDoc());
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
getReadableConfigSections,
writeConfigDocument,
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
expect(getReadableConfigSections).toHaveBeenCalledTimes(1);
expect([...getReadableConfigSections.mock.calls[0][1]].sort()).toEqual(
Object.keys(configSchema.shape).sort(),
);
expect(getReadableConfigSections.mock.invocationCallOrder[0]).toBeLessThan(
writeConfigDocument.mock.invocationCallOrder[0],
);
const body = res.body!.config as WrittenBody;
expect(Object.keys(body.overrides).sort()).toEqual(['endpoints', 'webSearch']);
expect(body.overrides.webSearch).toEqual({
searchProvider: 'serper',
serperApiKeyPreview: '...wxyz',
});
});
it('PATCH: resolves read access alongside the base config read, not after it', async () => {
let releaseBase: (appConfig: { config: object }) => void = () => undefined;
const getAppConfig = jest.fn(
() => new Promise<{ config: object }>((resolve) => (releaseBase = resolve)),
);
const getReadableConfigSections = jest
.fn()
.mockResolvedValue({ broad: false, sections: new Set<string>() });
const writeConfigDocument = jest.fn().mockResolvedValue(writtenDoc());
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
getAppConfig,
getReadableConfigSections,
writeConfigDocument,
});
const res = mockRes();
const pending = handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
await new Promise((resolve) => setImmediate(resolve));
expect(getAppConfig).toHaveBeenCalledTimes(1);
expect(getReadableConfigSections).toHaveBeenCalledTimes(1);
expect(writeConfigDocument).not.toHaveBeenCalled();
releaseBase({ config: {} });
await pending;
expect(res.statusCode).toBe(200);
expect(writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('/changes: resolves read access with the base config read, then filters the reply', async () => {
let releaseBase: (appConfig: { config: object }) => void = () => undefined;
const getAppConfig = jest.fn(
() => new Promise<{ config: object }>((resolve) => (releaseBase = resolve)),
);
const getReadableConfigSections = jest
.fn()
.mockResolvedValue({ broad: false, sections: new Set(['webSearch']) });
const writeConfigDocument = jest.fn().mockResolvedValue(writtenDoc());
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
getAppConfig,
getReadableConfigSections,
writeConfigDocument,
});
const res = mockRes();
const pending = handlers.applyConfigChanges(
mockReq({
params,
body: { ops: [{ op: 'set', fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
await new Promise((resolve) => setImmediate(resolve));
expect(getAppConfig).toHaveBeenCalledTimes(1);
expect(getReadableConfigSections).toHaveBeenCalledTimes(1);
expect([...getReadableConfigSections.mock.calls[0][1]].sort()).toEqual(
Object.keys(configSchema.shape).sort(),
);
expect(writeConfigDocument).not.toHaveBeenCalled();
releaseBase({ config: {} });
await pending;
expect(res.statusCode).toBe(200);
expect(writeConfigDocument).toHaveBeenCalledTimes(1);
expect(getReadableConfigSections).toHaveBeenCalledTimes(1);
expect(res.body).toMatchObject({ written: true, revision: 'c1:2' });
const body = res.body!.config as WrittenBody & { revision: string };
expect(Object.keys(body.overrides).sort()).toEqual(['endpoints', 'webSearch']);
expect(body.overrides.webSearch).toEqual({
searchProvider: 'serper',
serperApiKeyPreview: '...wxyz',
});
expect(body.tombstones).toEqual(['endpoints.bedrock', 'webSearch.jinaApiUrl']);
expect(body.revision).toBe('c1:2');
expect(JSON.stringify(res.body)).not.toMatch(/charLimit|cipher/);
});
it('/changes: a dry run returns no document and resolves no read access', async () => {
const getReadableConfigSections = jest.fn();
const { handlers, deps } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
getReadableConfigSections,
});
const res = mockRes();
await handlers.applyConfigChanges(
mockReq({
params,
body: {
ops: [{ op: 'set', fieldPath: 'endpoints.agents.disableBuilder', value: true }],
dryRun: true,
},
}),
res,
);
expect(res.statusCode).toBe(200);
expect(res.body).toMatchObject({ written: false, dryRun: true });
expect(res.body).not.toHaveProperty('config');
expect(getReadableConfigSections).not.toHaveBeenCalled();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it.each([
[
'PATCH',
'writeConfigDocument',
(h: ReturnType<typeof createHandlers>['handlers'], res: Response) =>
h.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
),
],
[
'tombstone',
'writeConfigDocument',
(h: ReturnType<typeof createHandlers>['handlers'], res: Response) =>
h.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'endpoints.bedrock' } }),
res,
),
],
[
'field delete',
'unsetConfigField',
(h: ReturnType<typeof createHandlers>['handlers'], res: Response) =>
h.deleteConfigField(mockReq({ params, query: { fieldPath: 'endpoints.bedrock' } }), res),
],
[
'/changes',
'writeConfigDocument',
(h: ReturnType<typeof createHandlers>['handlers'], res: Response) =>
h.applyConfigChanges(
mockReq({
params,
body: {
ops: [{ op: 'set', fieldPath: 'endpoints.agents.disableBuilder', value: true }],
},
}),
res,
),
],
] as const)(
'%s: a failed read lookup fails the request before anything is written',
async (_label, write, run) => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);
const { handlers, deps } = createHandlers({
hasConfigCapability: scopedCapability(['manage:endpoints']),
getReadableConfigSections: jest.fn().mockRejectedValue(new Error('grant lookup down')),
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
unsetConfigField: jest.fn().mockResolvedValue(writtenDoc()),
recordAuditEntry,
invalidateConfigCaches,
});
const res = mockRes();
await run(handlers, res);
expect(res.statusCode).toBe(500);
expect((deps as Record<string, jest.Mock>)[write]).not.toHaveBeenCalled();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(recordAuditEntry).not.toHaveBeenCalled();
expect(invalidateConfigCaches).not.toHaveBeenCalled();
},
);
it('a broad manager gets the whole redacted document without a read lookup', async () => {
const hasConfigCapability = jest.fn().mockResolvedValue(true);
const getReadableConfigSections = jest.fn();
const { handlers } = createHandlers({
hasConfigCapability,
getReadableConfigSections,
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'endpoints.agents.disableBuilder', value: true }] },
}),
res,
);
const body = res.body!.config as WrittenBody;
expect(Object.keys(body.overrides).sort()).toEqual(['endpoints', 'memory', 'webSearch']);
expect(body.tombstones).toHaveLength(3);
expect(JSON.stringify(res.body)).not.toContain('cipher');
expect(getReadableConfigSections).not.toHaveBeenCalled();
expect(hasConfigCapability.mock.calls.every(([, , verb]) => verb !== 'read')).toBe(true);
});
it('tombstone: a section manager sees only the tombstoned section', async () => {
const { handlers } = createHandlers({
hasConfigCapability: scopedCapability(['manage:memory']),
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
});
const res = mockRes();
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'memory.tokenLimit' } }),
res,
);
expect(res.statusCode).toBe(200);
const body = res.body!.config as WrittenBody;
expect(body.overrides).toEqual({ memory: { charLimit: 500 } });
expect(body.tombstones).toEqual(['memory.tokenLimit']);
});
it('field delete: a section manager sees only that section, secrets redacted', async () => {
const before = writtenDoc();
const { handlers, deps } = createHandlers({
hasConfigCapability: scopedCapability(['manage:webSearch']),
findConfigByPrincipal: jest.fn().mockResolvedValue({
...before,
configVersion: 1,
overrides: {
...before.overrides,
webSearch: { ...before.overrides.webSearch, jinaApiUrl: 'https://jina.example.com' },
},
}),
writeConfigDocument: jest.fn().mockResolvedValue(writtenDoc()),
});
const res = mockRes();
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'webSearch.jinaApiUrl' } }),
res,
);
expect(res.statusCode).toBe(200);
expect(deps.unsetConfigField).not.toHaveBeenCalled();
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
expect(deps.writeConfigDocument.mock.calls[0][3]).toBe('c1:1');
expect(writtenDraft(deps).overrides.webSearch).not.toHaveProperty('jinaApiUrl');
const body = res.body!.config as WrittenBody;
expect(body.overrides).toEqual({
webSearch: { searchProvider: 'serper', serperApiKeyPreview: '...wxyz' },
});
expect(body.tombstones).toEqual(['webSearch.jinaApiUrl']);
});
it('toggle and scope creation: an assign-only caller sees no section it cannot read', async () => {
const getReadableConfigSections = jest.fn();
const deps = {
hasConfigCapability: scopedCapability([]),
getReadableConfigSections,
hasCapability: jest.fn().mockResolvedValue(true),
writeConfigDocument: jest.fn().mockResolvedValue({ ...writtenDoc(), configVersion: 1 }),
toggleConfigActiveTracked: jest
.fn()
.mockResolvedValue({ config: writtenDoc(), changed: true }),
};
const { handlers } = createHandlers(deps);
const toggled = mockRes();
await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), toggled);
const created = mockRes();
await handlers.upsertConfigOverrides(
mockReq({ params, body: { overrides: {}, priority: 5 } }),
created,
);
expect(toggled.statusCode).toBe(200);
expect(created.statusCode).toBe(201);
for (const res of [toggled, created]) {
const body = res.body!.config as WrittenBody;
expect(body.overrides).toEqual({});
expect(body.tombstones).toEqual([]);
expect(body).toMatchObject({ principalId: 'editors', isActive: true });
}
expect(getReadableConfigSections).not.toHaveBeenCalled();
});
});
describe('revision preconditions', () => {
const params = { principalType: 'role', principalId: 'editor' };
const stored = {
_id: '64b000000000000000000001',
principalType: 'role',
principalId: 'editor',
priority: 10,
configVersion: 4,
isActive: true,
overrides: { interface: { customWelcome: 'stored' } },
tombstones: [],
};
const storedRevision = '64b000000000000000000001:4';
it.each([
['upsertConfigOverrides', { body: { overrides: {}, priority: 1, expectedRevision: 'v4' } }],
[
'patchConfigField',
{ body: { entries: [{ fieldPath: 'a.b', value: 1 }], expectedRevision: 4 } },
],
['tombstoneConfigField', { body: { fieldPath: 'memory', expectedRevision: 'abc:-1' } }],
['deleteConfigField', { query: { fieldPath: 'memory', expectedRevision: '' } }],
['deleteConfigOverrides', { query: { expectedRevision: 'abc' } }],
['toggleConfig', { body: { isActive: false, expectedRevision: { $ne: null } } }],
] as const)('%s rejects a malformed expectedRevision with 400', async (name, overrides) => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers[name](mockReq({ params, ...overrides }), res);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'expectedRevision must be "absent" or a revision returned by the config API',
code: 'INVALID_EXPECTED_REVISION',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('returns 409 with the stored revision when the precondition does not match', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: {
entries: [{ fieldPath: 'interface.customWelcome', value: 'mine' }],
expectedRevision: '64b000000000000000000001:3',
},
}),
res,
);
expect(res.statusCode).toBe(409);
expect(res.body).toEqual({
error: 'Config was modified by another request',
code: 'CONFIG_VERSION_CONFLICT',
currentRevision: storedRevision,
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('returns 409 with a null revision for a create-only write when the profile exists, and for a revision of a missing one', async () => {
const exists = createHandlers({ findConfigByPrincipal: jest.fn().mockResolvedValue(stored) });
const existsRes = mockRes();
await exists.handlers.upsertConfigOverrides(
mockReq({ params, body: { overrides: {}, priority: 5, expectedRevision: 'absent' } }),
existsRes,
);
expect(existsRes.statusCode).toBe(409);
expect(existsRes.body?.currentRevision).toBe(storedRevision);
const missing = createHandlers();
const missingRes = mockRes();
await missing.handlers.upsertConfigOverrides(
mockReq({ params, body: { overrides: {}, priority: 5, expectedRevision: storedRevision } }),
missingRes,
);
expect(missingRes.statusCode).toBe(409);
expect(missingRes.body?.currentRevision).toBeNull();
expect(missing.deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('writes on the precondition the client sent and returns the new revision', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: {
entries: [{ fieldPath: 'interface.customWelcome', value: 'mine' }],
expectedRevision: storedRevision,
},
}),
res,
);
expect(res.statusCode).toBe(200);
expect(deps.writeConfigDocument).toHaveBeenCalledWith(
'role',
'editor',
expect.objectContaining({ overrides: { interface: { customWelcome: 'mine' } } }),
storedRevision,
);
expect((res.body?.config as { revision: string }).revision).toBe('c1:5');
});
it('re-reads and re-validates when a write without a precondition loses a race', async () => {
const rotated = { ...stored, configVersion: 5, overrides: { interface: { a: 1 } } };
const reads = [stored, rotated];
/**
* Base (the validation floor) has no document. Each attempt reads it beside the target,
* and the committed write reads it once more.
*/
const findConfigByPrincipal = jest.fn(async (_type: string, principalId: string) =>
principalId === '__base__' ? null : reads.shift(),
);
const writeConfigDocument = jest
.fn()
.mockRejectedValueOnce(new ConfigRevisionConflictError())
.mockImplementation(async (type, id, draft, expected) =>
writtenDocument(type, id, draft, expected),
);
const { handlers } = createHandlers({ findConfigByPrincipal, writeConfigDocument });
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'x' }] },
}),
res,
);
expect(res.statusCode).toBe(200);
expect(reads).toHaveLength(0);
expect(findConfigByPrincipal).toHaveBeenCalledTimes(5);
expect(writeConfigDocument).toHaveBeenCalledTimes(2);
expect(writeConfigDocument.mock.calls[1][2].overrides).toEqual({
interface: { a: 1, customWelcome: 'x' },
});
expect(writeConfigDocument.mock.calls[1][3]).toBe('64b000000000000000000001:5');
});
it('keeps a committed write when Base cannot be read again to check it', async () => {
let baseReads = 0;
const findConfigByPrincipal = jest.fn(async (_type: string, principalId: string) => {
if (principalId !== '__base__') {
return stored;
}
baseReads += 1;
if (baseReads > 1) {
throw new Error('connection reset');
}
return null;
});
const { handlers, deps } = createHandlers({ findConfigByPrincipal });
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'kept' }] },
}),
res,
);
expect(res.statusCode).toBe(200);
expect(baseReads).toBe(2);
expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('answers 409 once the retry budget is spent', async () => {
const findConfigByPrincipal = jest.fn().mockResolvedValue(stored);
const writeConfigDocument = jest.fn().mockRejectedValue(new ConfigRevisionConflictError());
const { handlers } = createHandlers({ findConfigByPrincipal, writeConfigDocument });
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({ params, body: { overrides: { interface: { customWelcome: 'x' } } } }),
res,
);
expect(res.statusCode).toBe(409);
expect(res.body?.code).toBe('CONFIG_VERSION_CONFLICT');
expect(writeConfigDocument).toHaveBeenCalledTimes(3);
expect(res.body?.currentRevision).toBe(storedRevision);
});
it('passes the precondition through to tombstone, field delete, delete and toggle', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
await handlers.tombstoneConfigField(
mockReq({ params, body: { fieldPath: 'memory', expectedRevision: storedRevision } }),
mockRes(),
);
await handlers.deleteConfigField(
mockReq({ params, query: { fieldPath: 'memory', expectedRevision: storedRevision } }),
mockRes(),
);
await handlers.deleteConfigOverrides(
mockReq({ params, query: { expectedRevision: storedRevision } }),
mockRes(),
);
await handlers.toggleConfig(
mockReq({ params, body: { isActive: false, expectedRevision: storedRevision } }),
mockRes(),
);
const options = { expectedRevision: storedRevision };
expect(deps.writeConfigDocument.mock.calls[0][3]).toBe(storedRevision);
expect(deps.unsetConfigField.mock.calls[0][4]).toEqual(options);
expect(deps.deleteConfig.mock.calls[0][3]).toEqual({ expectEmpty: false, ...options });
expect(deps.toggleConfigActiveTracked.mock.calls[0][3]).toEqual({
expectEmpty: false,
...options,
});
});
it.each([
['tombstoneConfigField', { body: { fieldPath: 'memory' } }, 'writeConfigDocument'],
['deleteConfigField', { query: { fieldPath: 'memory' } }, 'unsetConfigField'],
['deleteConfigOverrides', {}, 'deleteConfig'],
['toggleConfig', { body: { isActive: true } }, 'toggleConfigActiveTracked'],
] as const)('%s maps a store conflict to 409', async (name, overrides, method) => {
const { handlers } = createHandlers({
[method]: jest.fn().mockRejectedValue(new ConfigRevisionConflictError(storedRevision)),
});
const res = mockRes();
await handlers[name](mockReq({ params, ...overrides }), res);
expect(res.statusCode).toBe(409);
expect(res.body?.currentRevision).toBe(storedRevision);
});
it('reports the stored revision on a write with nothing to apply', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({ params, body: { entries: [{ fieldPath: 'interface.prompts', value: false }] } }),
res,
);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({
message: 'No actionable field entries provided',
revision: storedRevision,
config: expect.objectContaining({ revision: storedRevision }),
applied: [],
skipped: [
{
path: 'interface.prompts',
segments: ['interface', 'prompts'],
reason: 'interface_permission',
},
],
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
describe('on a write with nothing to apply', () => {
const noops = [
['upsertConfigOverrides', 'body', { overrides: { filters: {} } }],
[
'patchConfigField',
'body',
{ entries: [{ fieldPath: 'interface.prompts', value: false }] },
],
['tombstoneConfigField', 'body', { fieldPath: 'interface.prompts' }],
['deleteConfigField', 'query', { fieldPath: 'interface.prompts' }],
] as const;
it.each(noops)(
'%s answers 409 when the stored document is not at expectedRevision',
async (name, location, input) => {
const exists = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const createOnly = mockRes();
await exists.handlers[name](
mockReq({ params, [location]: { ...input, expectedRevision: 'absent' } }),
createOnly,
);
expect(createOnly.statusCode).toBe(409);
expect(createOnly.body).toEqual({
error: 'Config was modified by another request',
code: 'CONFIG_VERSION_CONFLICT',
currentRevision: storedRevision,
});
const stale = mockRes();
await exists.handlers[name](
mockReq({
params,
[location]: { ...input, expectedRevision: '64b000000000000000000001:3' },
}),
stale,
);
expect(stale.statusCode).toBe(409);
expect(stale.body?.currentRevision).toBe(storedRevision);
const missing = createHandlers();
const gone = mockRes();
await missing.handlers[name](
mockReq({ params, [location]: { ...input, expectedRevision: storedRevision } }),
gone,
);
expect(gone.statusCode).toBe(409);
expect(gone.body?.currentRevision).toBeNull();
for (const deps of [exists.deps, missing.deps]) {
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deps.unsetConfigField).not.toHaveBeenCalled();
}
},
);
it.each(noops)(
'%s answers 200 with the revision when the precondition holds',
async (name, location, input) => {
const exists = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const matched = mockRes();
await exists.handlers[name](
mockReq({ params, [location]: { ...input, expectedRevision: storedRevision } }),
matched,
);
expect(matched.statusCode).toBe(200);
expect(matched.body?.revision).toBe(storedRevision);
},
);
it.each(noops.filter(([name]) => name !== 'upsertConfigOverrides'))(
'%s answers 200 with no revision under absent when there is no document',
async (name, location, input) => {
const missing = createHandlers();
const absent = mockRes();
await missing.handlers[name](
mockReq({ params, [location]: { ...input, expectedRevision: 'absent' } }),
absent,
);
expect(absent.statusCode).toBe(200);
expect(absent.body?.revision).toBeNull();
},
);
it('upsertConfigOverrides under absent creates the empty profile, as a create-only PUT does', async () => {
const missing = createHandlers();
const absent = mockRes();
await missing.handlers.upsertConfigOverrides(
mockReq({ params, body: { overrides: { filters: {} }, expectedRevision: 'absent' } }),
absent,
);
expect(absent.statusCode).toBe(201);
expect(missing.deps.writeConfigDocument).toHaveBeenCalledWith(
params.principalType,
params.principalId,
expect.objectContaining({ overrides: {}, tombstones: [], isActive: true }),
'absent',
);
});
});
it('returns revisions on reads', async () => {
const { handlers } = createHandlers({
listAllConfigs: jest.fn().mockResolvedValue([stored]),
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const listRes = mockRes();
const getRes = mockRes();
await handlers.listConfigs(mockReq(), listRes);
await handlers.getConfig(mockReq({ params }), getRes);
expect((listRes.body?.configs as Array<{ revision: string }>)[0].revision).toBe(
storedRevision,
);
expect((getRes.body?.config as { revision: string }).revision).toBe(storedRevision);
});
});
describe('write pipeline', () => {
const params = { principalType: 'role', principalId: 'editor' };
it('keeps an omitted custom endpoint key before validating, so a required secret can be omitted', async () => {
const stored = {
_id: '64b000000000000000000002',
configVersion: 2,
overrides: {
endpoints: {
custom: [
{
name: 'Private',
apiKey: 'v3:test:sk-stored',
apiKeyPreview: '...ored',
baseURL: 'https://private.example.com/v1',
models: { default: ['m'] },
},
],
},
},
tombstones: [],
};
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params,
body: {
overrides: {
endpoints: {
custom: [
{
name: 'Private',
baseURL: 'https://private.example.com/v1',
models: { default: ['m', 'n'] },
},
],
},
},
},
}),
res,
);
expect(res.statusCode).toBe(200);
const [entry] = (
writtenDraft(deps).overrides.endpoints as {
custom: Array<Record<string, string> & { models: { default: string[] } }>;
}
).custom;
expect(entry.apiKey).toBe('v3:test:sk-stored');
expect(entry.models.default).toEqual(['m', 'n']);
/** Validation saw the document the write stores, with the kept secret in place. */
const overrideCalls = jest.mocked(getConfigOverrideIssues).mock.calls;
const validated = overrideCalls[overrideCalls.length - 1][0] as {
endpoints: { custom: Array<Record<string, string>> };
};
expect(validated.endpoints.custom[0].apiKey).toBe('v3:test:sk-stored');
});
it('validates a patch with the secrets it omits already restored', async () => {
const stored = {
_id: '64b000000000000000000004',
configVersion: 1,
overrides: {
speech: { tts: { openai: { apiKey: 'v3:test:sk-tts', apiKeyPreview: '...-tts' } } },
},
tombstones: [],
};
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue(stored),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: {
entries: [
{ fieldPath: 'speech.tts.openai', value: { model: 'tts-1', voices: ['alloy'] } },
],
},
}),
res,
);
expect(res.statusCode).toBe(200);
const fieldCalls = jest.mocked(getConfigFieldIssues).mock.calls;
const [validatedFields] = fieldCalls[fieldCalls.length - 1];
expect(validatedFields).toEqual([
{
segments: ['speech', 'tts', 'openai'],
value: {
model: 'tts-1',
voices: ['alloy'],
apiKey: 'v3:test:sk-tts',
apiKeyPreview: '...-tts',
},
},
]);
expect(writtenField(deps, 'speech.tts.openai.apiKey')).toBe('v3:test:sk-tts');
});
it('rejects a patch the stored document cannot take with CONFIG_PATH_INVALID', async () => {
const { handlers, deps } = createHandlers({
findConfigByPrincipal: jest.fn().mockResolvedValue({
_id: '64b000000000000000000003',
configVersion: 1,
overrides: { interface: { customWelcome: 'hi' } },
tombstones: [],
}),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'interface.customWelcome.nested', value: 'x' }] },
}),
res,
);
expect(res.statusCode).toBe(400);
expect(res.body).toEqual({
error: 'Config path cannot be applied to the stored config',
code: 'CONFIG_PATH_INVALID',
reason: 'scalar_parent',
});
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
it('waits for cache invalidation before responding', async () => {
let release: () => void = () => undefined;
const invalidateConfigCaches = jest.fn(
() => new Promise<void>((resolve) => (release = resolve)),
);
const { handlers } = createHandlers({ invalidateConfigCaches });
const res = mockRes();
const pending = handlers.patchConfigField(
mockReq({
params,
body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'x' }] },
}),
res,
);
await new Promise((resolve) => setImmediate(resolve));
expect(invalidateConfigCaches).toHaveBeenCalledTimes(1);
expect(res.json).not.toHaveBeenCalled();
release();
await pending;
expect(res.statusCode).toBe(200);
});
it('still answers 200 when invalidation fails after the write committed', async () => {
const { handlers } = createHandlers({
invalidateConfigCaches: jest.fn().mockRejectedValue(new Error('cache down')),
});
const res = mockRes();
await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), res);
expect(res.statusCode).toBe(200);
});
it('reads GET /base around the merged-config cache', async () => {
const getAppConfig = jest.fn().mockResolvedValue({ interface: { modelSelect: true } });
const { handlers } = createHandlers({ getAppConfig });
await handlers.getBaseConfig(mockReq(), mockRes());
expect(getAppConfig).toHaveBeenCalledWith(
expect.objectContaining({ bypassOverrideCache: true }),
);
});
});
describe('reloadConfig', () => {
const admin = { id: 'u1', role: 'ADMIN', _id: { toString: () => 'u1' } };
const target = { type: 'config', id: 'librechat.yaml', name: 'librechat.yaml' };
it('clears the config caches before answering, writes nothing and audits the reload', async () => {
let release: () => void = () => undefined;
const reloadConfigCaches = jest.fn(
() =>
new Promise<ConfigReloadReport>(
(resolve) => (release = () => resolve({ cleared: true, broadcast: 'sent' })),
),
);
const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers, deps } = createHandlers({
reloadConfigCaches,
invalidateConfigCaches,
recordAuditEntry,
});
const res = mockRes();
const reloading = handlers.reloadConfig(mockReq({ user: admin }), res);
await new Promise((resolve) => setImmediate(resolve));
expect(reloadConfigCaches).toHaveBeenCalledWith();
expect(res.status).not.toHaveBeenCalled();
release();
await reloading;
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({ success: true, broadcast: true });
expect(invalidateConfigCaches).not.toHaveBeenCalled();
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
expect(deps.hasConfigCapability).toHaveBeenCalledWith(
expect.objectContaining({ id: 'u1', tenantId: undefined }),
null,
'manage',
);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.reloaded',
target,
metadata: { broadcast: 'sent' },
}),
);
expect(recordAuditEntry.mock.calls[0][0].outcome).toBeUndefined();
});
it('refuses a tenant admin with broad manage, since the reload reaches every tenant', async () => {
const reloadConfigCaches = jest.fn().mockResolvedValue({ cleared: true, broadcast: 'sent' });
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({ reloadConfigCaches, recordAuditEntry });
const res = mockRes();
await handlers.reloadConfig(mockReq({ user: { ...admin, tenantId: 'tenant-a' } }), res);
expect(res.statusCode).toBe(403);
expect(res.body).toEqual({ error: expect.any(String), code: 'FORBIDDEN' });
expect(reloadConfigCaches).not.toHaveBeenCalled();
expect(recordAuditEntry).not.toHaveBeenCalled();
});
it('answers 422 CONFIG_RELOAD_INVALID with the issue locations when librechat.yaml is refused', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const issues = [
{ path: 'bogusTopLevelKey', segments: ['bogusTopLevelKey'], code: 'unrecognized_keys' },
];
const report: ConfigReloadReport = {
cleared: true,
loaded: { ok: false, error: { code: 'CONFIG_INVALID', issues } },
broadcast: 'skipped',
};
const { handlers } = createHandlers({
reloadConfigCaches: jest.fn().mockResolvedValue(report),
recordAuditEntry,
});
const res = mockRes();
await handlers.reloadConfig(mockReq(), res);
expect(res.statusCode).toBe(422);
expect(res.body).toEqual({
error: expect.any(String),
code: 'CONFIG_RELOAD_INVALID',
issues,
});
expect(recordAuditEntry).toHaveBeenCalledTimes(1);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.reloaded',
outcome: 'failure',
target,
metadata: { code: 'CONFIG_RELOAD_INVALID', broadcast: 'skipped' },
}),
);
});
it('answers broadcast: false when there is no pub/sub to tell other instances', async () => {
const { handlers } = createHandlers({
reloadConfigCaches: jest.fn().mockResolvedValue({ cleared: true, broadcast: 'none' }),
});
const res = mockRes();
await handlers.reloadConfig(mockReq(), res);
expect(res.statusCode).toBe(200);
expect(res.body).toEqual({ success: true, broadcast: false });
});
it.each([
{
name: 'the publish to the other instances failed',
report: { cleared: true, broadcast: 'failed' },
status: 503,
code: 'CONFIG_RELOAD_BROADCAST_FAILED',
},
{
name: 'a clear on this instance failed',
report: { cleared: false, broadcast: 'sent' },
status: 500,
code: 'CONFIG_RELOAD_FAILED',
},
{
name: 'both failed',
report: { cleared: false, broadcast: 'failed' },
status: 500,
code: 'CONFIG_RELOAD_FAILED',
},
{
name: 'building the config from the loaded file failed',
report: {
cleared: true,
loaded: { ok: false, error: { code: 'LOAD_FAILED' } },
broadcast: 'skipped',
},
status: 500,
code: 'CONFIG_RELOAD_FAILED',
},
])(
'answers $status $code and audits a failure when $name',
async ({ report, status, code }) => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
reloadConfigCaches: jest.fn().mockResolvedValue(report),
recordAuditEntry,
});
const res = mockRes();
await handlers.reloadConfig(mockReq(), res);
expect(res.statusCode).toBe(status);
expect(res.body).toEqual({ error: expect.any(String), code });
expect(res.body).not.toHaveProperty('success');
expect(recordAuditEntry).toHaveBeenCalledTimes(1);
expect(recordAuditEntry).toHaveBeenCalledWith(
expect.objectContaining({
action: 'config.reloaded',
outcome: 'failure',
target,
metadata: { code, broadcast: report.broadcast },
}),
);
},
);
it('refuses a section-scoped manager, and answers 501 without the reload dependency', async () => {
const reloadConfigCaches = jest.fn().mockResolvedValue({ cleared: true, broadcast: 'sent' });
const scoped = createHandlers({
reloadConfigCaches,
hasConfigCapability: jest.fn(
async (_user: unknown, section: string | null) => section != null,
),
});
const forbidden = mockRes();
await scoped.handlers.reloadConfig(mockReq(), forbidden);
const unconfigured = mockRes();
await createHandlers({
invalidateConfigCaches: jest.fn().mockResolvedValue(undefined),
}).handlers.reloadConfig(mockReq(), unconfigured);
expect(forbidden.statusCode).toBe(403);
expect(forbidden.body).toEqual({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
expect(reloadConfigCaches).not.toHaveBeenCalled();
expect(unconfigured.statusCode).toBe(501);
});
it('answers 500 without echoing the failure, and audits nothing, when the reload throws', async () => {
const recordAuditEntry = jest.fn().mockResolvedValue(undefined);
const { handlers } = createHandlers({
reloadConfigCaches: jest.fn().mockRejectedValue(new Error('redis://secret@host down')),
recordAuditEntry,
});
const res = mockRes();
await handlers.reloadConfig(mockReq(), res);
expect(res.statusCode).toBe(500);
expect(res.body).toEqual({ error: 'Failed to reload config' });
expect(recordAuditEntry).not.toHaveBeenCalled();
});
});
describe('updateConfigPriority', () => {
const params = { principalType: 'role', principalId: 'editor' };
const document = {
_id: '64b000000000000000000001',
principalType: 'role',
principalId: 'editor',
priority: 30,
overrides: { webSearch: { serperApiKey: 'v3:cipher', serperApiKeyPreview: 'sk-...1234' } },
tombstones: [],
isActive: true,
configVersion: 4,
};
it('rejects a bad principal type, priority or revision before touching anything', async () => {
const setConfigPriority = jest.fn();
const { handlers } = createHandlers({ setConfigPriority });
const cases: Array<[Record<string, unknown>, Record<string, unknown>, string]> = [
[{ principalType: 'public', principalId: 'x' }, { priority: 1 }, 'INVALID_PRINCIPAL_TYPE'],
[params, {}, 'INVALID_PRIORITY'],
[params, { priority: -1 }, 'INVALID_PRIORITY'],
[params, { priority: '3' }, 'INVALID_PRIORITY'],
[params, { priority: 1, expectedRevision: 'nope' }, 'INVALID_EXPECTED_REVISION'],
];
for (const [reqParams, body, code] of cases) {
const res = mockRes();
await handlers.updateConfigPriority(mockReq({ params: reqParams, body }), res);
expect(res.statusCode).toBe(400);
expect(res.body?.code).toBe(code);
}
expect(setConfigPriority).not.toHaveBeenCalled();
});
it('requires an authenticated broad manager', async () => {
const setConfigPriority = jest.fn();
const unauthenticated = mockRes();
const { handlers } = createHandlers({ setConfigPriority });
await handlers.updateConfigPriority(
mockReq({ params, body: { priority: 1 }, user: undefined }),
unauthenticated,
);
const sectionScoped = createHandlers({
setConfigPriority,
hasConfigCapability: jest.fn(async (_user: unknown, section: string | null) => !!section),
});
const forbidden = mockRes();
await sectionScoped.handlers.updateConfigPriority(
mockReq({ params, body: { priority: 1 } }),
forbidden,
);
expect(unauthenticated.statusCode).toBe(401);
expect(forbidden.statusCode).toBe(403);
expect(setConfigPriority).not.toHaveBeenCalled();
});
it('answers 501 when the server did not wire the priority write', async () => {
const { handlers } = createHandlers();
const res = mockRes();
await handlers.updateConfigPriority(mockReq({ params, body: { priority: 1 } }), res);
expect(res.statusCode).toBe(501);
});
it('passes the revision through and redacts the stored secrets in the response', async () => {
const setConfigPriority = jest
.fn()
.mockResolvedValue({ config: { ...document, priority: 5 }, changed: true });
const { handlers } = createHandlers({ setConfigPriority });
const res = mockRes();
await handlers.updateConfigPriority(
mockReq({ params, body: { priority: 5, expectedRevision: '64b000000000000000000001:4' } }),
res,
);
expect(res.statusCode).toBe(200);
expect(setConfigPriority).toHaveBeenCalledWith('role', 'editor', 5, {
expectedRevision: '64b000000000000000000001:4',
});
const config = res.body?.config as { overrides: { webSearch: Record<string, unknown> } };
expect(config.overrides.webSearch.serperApiKey).toBeUndefined();
expect(JSON.stringify(res.body)).not.toContain('v3:cipher');
});
it('answers 409 with the current revision when the precondition is stale', async () => {
const setConfigPriority = jest
.fn()
.mockRejectedValue(new ConfigRevisionConflictError('64b000000000000000000001:5'));
const { handlers } = createHandlers({ setConfigPriority });
const res = mockRes();
await handlers.updateConfigPriority(
mockReq({ params, body: { priority: 5, expectedRevision: '64b000000000000000000001:4' } }),
res,
);
expect(res.statusCode).toBe(409);
expect(res.body).toEqual({
error: 'Config was modified by another request',
code: 'CONFIG_VERSION_CONFLICT',
currentRevision: '64b000000000000000000001:5',
});
});
});
describe('principal existence on create', () => {
const entry = { entries: [{ fieldPath: 'interface.customWelcome', value: 'hi' }] };
it('does not look the principal up when its document already exists', async () => {
const principalExists = jest.fn().mockResolvedValue(false);
const { handlers } = createHandlers({
principalExists,
findConfigByPrincipal: jest.fn(async (_type: string, principalId: string) =>
principalId === '__base__'
? null
: { _id: '64b000000000000000000001', priority: 10, overrides: {}, configVersion: 1 },
),
});
const res = mockRes();
await handlers.patchConfigField(
mockReq({ params: { principalType: 'role', principalId: 'retired' }, body: entry }),
res,
);
expect(res.statusCode).toBe(200);
expect(principalExists).not.toHaveBeenCalled();
});
it('never looks Base up, and refuses a principal the lookup does not find', async () => {
const principalExists = jest.fn().mockResolvedValue(false);
const { handlers } = createHandlers({ principalExists });
const base = mockRes();
await handlers.patchConfigField(
mockReq({ params: { principalType: 'role', principalId: '__base__' }, body: entry }),
base,
);
const group = mockRes();
await handlers.patchConfigField(
mockReq({
params: { principalType: 'group', principalId: 'grp_engineering' },
body: entry,
}),
group,
);
expect(base.statusCode).toBe(200);
expect(group.statusCode).toBe(404);
expect(group.body?.code).toBe('PRINCIPAL_NOT_FOUND');
expect(principalExists).toHaveBeenCalledTimes(1);
expect(principalExists).toHaveBeenCalledWith('group', 'grp_engineering');
});
});
describe('create-only PUT', () => {
it('writes an empty create-only request instead of answering it as a no-op', async () => {
const { handlers, deps } = createHandlers();
const res = mockRes();
await handlers.upsertConfigOverrides(
mockReq({
params: { principalType: 'user', principalId: '64b000000000000000000009' },
body: { overrides: {}, expectedRevision: 'absent' },
}),
res,
);
expect(res.statusCode).toBe(201);
expect(deps.writeConfigDocument).toHaveBeenCalledWith(
'user',
'64b000000000000000000009',
{ principalModel: 'User', priority: 100, overrides: {}, tombstones: [], isActive: true },
'absent',
);
});
});
});