Skip to content

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

🧾 feat: Admin Config Write Report, Structured Issues and Deployment-Only Paths (#17395)

Danny Avilababf6f908bde
diff --git a/api/server/routes/admin/config.js b/api/server/routes/admin/config.js
index 8c4d4ef38c..5bb1061bb3 100644
--- a/api/server/routes/admin/config.js
+++ b/api/server/routes/admin/config.js
@@ -2,6 +2,7 @@ const express = require('express');
const {
rejectUnsafeConfigKeys,
createAdminConfigHandlers,
+ allowBeforeTermsAcceptance,
createAdminConfigReadHandlers,
createAdminConfigCatalogHandlers,
} = require('@librechat/api');
@@ -82,7 +83,8 @@ const catalogHandlers = createAdminConfigCatalogHandlers({
overrideEnvAllowlist: process.env.CONFIG_OVERRIDE_ENV_ALLOWLIST,
});
-router.use(requireJwtAuth, requireAdminAccess, rejectUnsafeConfigKeys);
+/** Config reads and writes stay open to an admin who has not accepted the terms. */
+router.use(allowBeforeTermsAcceptance, requireJwtAuth, requireAdminAccess, rejectUnsafeConfigKeys);
router.get('/', handlers.listConfigs);
router.get('/meta', handlers.getConfigMeta);
diff --git a/api/server/routes/admin/config.test.js b/api/server/routes/admin/config.test.js
index 55d9183ae4..6a1b8f927a 100644
--- a/api/server/routes/admin/config.test.js
+++ b/api/server/routes/admin/config.test.js
@@ -4,12 +4,21 @@ const mongoSanitize = require('express-mongo-sanitize');
const { createRequestSanitizer } = require('@librechat/api');
let hasAdminAccess;
+/** Whether the deployment asks for terms acceptance, which the signed-in admin has not given. */
+let mockTermsRequired = false;
+/** Authenticates, then runs the real terms gate, as `requireJwtAuth` chains it. */
const mockRequireJwtAuth = jest.fn((req, res, next) => {
if (req.headers.authorization !== 'Bearer admin') {
return res.status(401).json({ message: 'Unauthorized' });
}
- req.user = { id: 'user-1', _id: 'user-1', role: 'ADMIN' };
- next();
+ req.user = { id: 'user-1', _id: 'user-1', role: 'ADMIN', termsAccepted: !mockTermsRequired };
+ const { createTermsAcceptanceGate } = require('@librechat/api');
+ const gate = createTermsAcceptanceGate({
+ getAppConfig: async () => ({
+ interfaceConfig: { termsOfService: { modalAcceptance: mockTermsRequired } },
+ }),
+ });
+ return gate(req, res, next);
});
const mockRequireCapability = jest.fn(() => (_req, res, next) => {
if (!hasAdminAccess) {
@@ -87,6 +96,7 @@ describe('admin config routes', () => {
beforeEach(() => {
hasAdminAccess = true;
+ mockTermsRequired = false;
mockDb.listAllConfigs.mockResolvedValue([]);
mockDb.findConfigByPrincipal.mockResolvedValue(null);
mockDb.writeConfigDocument.mockImplementation(async (principalType, principalId, draft) => ({
@@ -161,6 +171,35 @@ describe('admin config routes', () => {
});
});
+ it('takes config writes from an admin who has not accepted the terms, unlike other routes', async () => {
+ mockTermsRequired = true;
+ const gated = express();
+ gated.use(express.json());
+ gated.post('/api/agents/chat', mockRequireJwtAuth, (_req, res) => res.json({ ok: true }));
+
+ const chat = await request(gated)
+ .post('/api/agents/chat')
+ .set('authorization', 'Bearer admin')
+ .send({})
+ .expect(403);
+ expect(chat.body.code).toBe('terms_not_accepted');
+
+ const response = await request(app)
+ .patch('/api/admin/config/role/__base__/fields')
+ .set('authorization', 'Bearer admin')
+ .send({
+ entries: [{ fieldPath: 'interface.termsOfService.modalAcceptance', value: false }],
+ })
+ .expect(200);
+ expect(response.body.applied).toEqual([
+ {
+ path: 'interface.termsOfService.modalAcceptance',
+ segments: ['interface', 'termsOfService', 'modalAcceptance'],
+ },
+ ]);
+ expect(mockDb.writeConfigDocument).toHaveBeenCalledTimes(1);
+ });
+
it('serves the config contract behind the same auth', async () => {
await request(app).get('/api/admin/config/meta').expect(401);
diff --git a/e2e/specs/mock/scenarios/config-override-validation.spec.ts b/e2e/specs/mock/scenarios/config-override-validation.spec.ts
index 471e48a3ed..fdeb739bd1 100644
--- a/e2e/specs/mock/scenarios/config-override-validation.spec.ts
+++ b/e2e/specs/mock/scenarios/config-override-validation.spec.ts
@@ -122,7 +122,12 @@ test.describe('Principal config override validation', () => {
expect(res.status()).toBe(400);
const body = (await res.json()) as {
code: string;
- issues: Array<{ path: string; segments: string[]; code: string }>;
+ issues: Array<{
+ path: string;
+ segments: string[];
+ code: string;
+ params?: Record<string, unknown>;
+ }>;
};
expect(body.code).toBe('CONFIG_OVERRIDE_INVALID');
expect(body.issues).toEqual([
@@ -130,6 +135,7 @@ test.describe('Principal config override validation', () => {
path: 'interface.contextCost',
segments: ['interface', 'contextCost'],
code: 'invalid_type',
+ params: { expected: 'boolean', received: 'string' },
},
]);
diff --git a/packages/api/src/admin/catalog.spec.ts b/packages/api/src/admin/catalog.spec.ts
index 8488efdb9a..c8ba8f2e66 100644
--- a/packages/api/src/admin/catalog.spec.ts
+++ b/packages/api/src/admin/catalog.spec.ts
@@ -473,6 +473,7 @@ describe('GET /catalog', () => {
it('answers 403 without config read access, 400 for a half-named principal, 404 for a missing one', async () => {
const forbidden = await catalog({}, { hasAnyConfigReadAccess: async () => false });
expect(forbidden.res.statusCode).toBe(403);
+ expect(forbidden.res.body?.code).toBe('FORBIDDEN');
expect((await catalog({ principalType: ROLE })).res.statusCode).toBe(400);
expect((await catalog({ principalType: 'tenant', principalId: 'x' })).res.statusCode).toBe(400);
const missing = await catalog({ principalType: ROLE, principalId: 'ghost' });
@@ -561,5 +562,6 @@ describe('GET /env-status', () => {
it('answers 403 without config read access', async () => {
const { res } = await envStatus({ hasAnyConfigReadAccess: async () => false });
expect(res.statusCode).toBe(403);
+ expect(res.body?.code).toBe('FORBIDDEN');
});
});
diff --git a/packages/api/src/admin/catalog.ts b/packages/api/src/admin/catalog.ts
index b126f0e2d6..95b848c5ec 100644
--- a/packages/api/src/admin/catalog.ts
+++ b/packages/api/src/admin/catalog.ts
@@ -36,17 +36,19 @@ import type { CapabilityUser } from '~/middleware/capabilities';
import type { GetAppConfigOptions } from '~/app/service';
import type { ManifestTool } from '~/tools/available';
import type { ServerRequest } from '~/types/http';
-import {
- parseEnvAllowlist,
- collectEnvReferenceSections,
- collectDefaultEnvReferenceSections,
-} from '~/app/allowlist';
import {
canReadSection,
getCapabilityUser,
validatePrincipalType,
+ forbiddenResponse,
+ authRequiredResponse,
principalNotFoundResponse,
} from './config';
+import {
+ parseEnvAllowlist,
+ collectEnvReferenceSections,
+ collectDefaultEnvReferenceSections,
+} from '~/app/allowlist';
import { resolveServedCustomEndpoints } from '~/endpoints/custom/config';
import { listAvailableTools } from '~/tools/available';
import { getSafeErrorMetadata } from '~/utils/errors';
@@ -493,10 +495,10 @@ export function createAdminConfigCatalogHandlers(deps: AdminConfigCatalogDeps):
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const isBase = isBaseConfigPrincipal({ principalType, principalId });
const [readable, exists] = await Promise.all([
@@ -576,10 +578,10 @@ export function createAdminConfigCatalogHandlers(deps: AdminConfigCatalogDeps):
try {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const [baseConfig, overrides] = await Promise.all([
getAppConfig({ tenantId: user.tenantId, baseOnly: true }),
diff --git a/packages/api/src/admin/config.changes.integration.spec.ts b/packages/api/src/admin/config.changes.integration.spec.ts
index 23b2dbfc28..9592da35b6 100644
--- a/packages/api/src/admin/config.changes.integration.spec.ts
+++ b/packages/api/src/admin/config.changes.integration.spec.ts
@@ -285,6 +285,7 @@ describe('POST …/changes: one atomic write', () => {
path: 'mcpServers.new.title',
segments: ['mcpServers', 'new', 'title'],
code: 'invalid_type',
+ params: { expected: 'string', received: 'number' },
},
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
@@ -1279,32 +1280,52 @@ describe('POST …/changes: entries librechat.yaml owns', () => {
path: 'endpoints.custom.2.baseURL',
segments: ['endpoints', 'custom', '2', 'baseURL'],
code: 'invalid_type',
+ params: { expected: 'string', received: 'number' },
},
]);
});
- it('reports writes to a YAML stdio server as applied but ignored at runtime', async () => {
+ it('refuses a write inside a YAML stdio server, and leaves one out of a whole-section value', async () => {
const params = nextParams();
- const { status, body } = await send(
+ const refused = await send(
{
ops: [
- { op: 'set', fieldPath: 'mcpServers.yaml-stdio.title', value: 'Local' },
{ op: 'set', fieldPath: 'mcpServers.yaml-http.title', value: 'Remote' },
+ { op: 'set', fieldPath: 'mcpServers.yaml-stdio.title', value: 'Local' },
],
},
params,
);
+ expect(refused.status).toBe(400);
+ expect(refused.body).toMatchObject({ code: 'PROCESS_MCP_SERVER_OVERRIDE', opIndex: 1 });
+ expect(await storedDocument(params.principalId)).toBeNull();
+ const { status, body } = await send(
+ {
+ ops: [
+ {
+ op: 'set',
+ fieldPath: 'mcpServers',
+ value: { 'yaml-stdio': { title: 'Local' }, 'yaml-http': { title: 'Remote' } },
+ },
+ ],
+ },
+ params,
+ );
expect(status).toBe(200);
- expect(body.applied).toHaveLength(2);
- expect(body.ignored).toEqual([
+ expect(body.applied).toEqual([{ opIndex: 0, op: 'set', segments: ['mcpServers'] }]);
+ expect(body.skipped).toEqual([
{
opIndex: 0,
op: 'set',
- segments: ['mcpServers', 'yaml-stdio', 'title'],
+ segments: ['mcpServers', 'yaml-stdio'],
reason: 'process_mcp_server',
},
]);
+ expect(body.ignored).toEqual([]);
+ expect((await storedDocument(params.principalId))!.overrides).toEqual({
+ mcpServers: { 'yaml-http': { title: 'Remote' } },
+ });
});
it('reports the YAML stdio servers a whole-section tombstone leaves in place as ignored', async () => {
@@ -1364,7 +1385,7 @@ describe('POST …/changes: entries librechat.yaml owns', () => {
expect((await storedDocument(params.principalId))!.tombstones).toEqual(['endpoints.agents']);
});
- it('reports a rename under a YAML stdio server as ignored, but not an unset there', async () => {
+ it('refuses a rename under a YAML stdio server, but not an unset there', async () => {
const params = nextParams();
await seedDocument(
params.principalId,
@@ -1379,7 +1400,7 @@ describe('POST …/changes: entries librechat.yaml owns', () => {
[],
);
- const { status, body } = await send(
+ const rename = await send(
{
ops: [
{
@@ -1388,24 +1409,22 @@ describe('POST …/changes: entries librechat.yaml owns', () => {
from: 'OLD',
to: 'NEW',
},
- { op: 'unset', fieldPath: 'mcpServers.yaml-stdio.title' },
],
},
params,
);
+ expect(rename.status).toBe(400);
+ expect(rename.body).toMatchObject({ code: 'PROCESS_MCP_SERVER_OVERRIDE', opIndex: 0 });
+ const { status, body } = await send(
+ { ops: [{ op: 'unset', fieldPath: 'mcpServers.yaml-stdio.title' }] },
+ params,
+ );
expect(status).toBe(200);
- expect(body.applied.map((ref) => ref.opIndex)).toEqual([0, 1]);
- expect(body.ignored).toEqual([
- {
- opIndex: 0,
- op: 'rename',
- segments: ['mcpServers', 'yaml-stdio', 'customUserVars'],
- reason: 'process_mcp_server',
- },
- ]);
+ expect(body.applied.map((ref) => ref.opIndex)).toEqual([0]);
+ expect(body.ignored).toEqual([]);
expect((await storedDocument(params.principalId))!.overrides).toEqual({
- mcpServers: { 'yaml-stdio': { customUserVars: { NEW: { title: 'T', description: 'D' } } } },
+ mcpServers: { 'yaml-stdio': { customUserVars: { OLD: { title: 'T', description: 'D' } } } },
});
});
@@ -1897,7 +1916,12 @@ describe('POST …/changes: no-ops, dry runs and preconditions', () => {
);
expect(rewritten.status).toBe(400);
expect(rewritten.body.issues).toEqual([
- { path: 'balance.startBalance', segments: ['balance', 'startBalance'], code: 'invalid_type' },
+ {
+ path: 'balance.startBalance',
+ segments: ['balance', 'startBalance'],
+ code: 'invalid_type',
+ params: { expected: 'number', received: 'string' },
+ },
]);
});
diff --git a/packages/api/src/admin/config.dotted.integration.spec.ts b/packages/api/src/admin/config.dotted.integration.spec.ts
index 2c9deaaed7..eeacb9da17 100644
--- a/packages/api/src/admin/config.dotted.integration.spec.ts
+++ b/packages/api/src/admin/config.dotted.integration.spec.ts
@@ -286,6 +286,7 @@ describe('admin config writes refuse keys that cannot be config', () => {
path: `endpoints.bedrock.inferenceProfiles.${PROFILE}`,
segments: ['endpoints', 'bedrock', 'inferenceProfiles', PROFILE],
code: 'invalid_type',
+ params: { expected: 'string', received: 'number' },
},
]);
expect(await readRaw(role)).toBeNull();
diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.ts
index d441c959c1..7c53532a76 100644
--- a/packages/api/src/admin/config.handler.spec.ts
+++ b/packages/api/src/admin/config.handler.spec.ts
@@ -473,6 +473,7 @@ describe('createAdminConfigHandlers', () => {
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();
});
@@ -494,6 +495,7 @@ describe('createAdminConfigHandlers', () => {
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();
});
@@ -517,6 +519,7 @@ describe('createAdminConfigHandlers', () => {
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();
});
@@ -624,6 +627,9 @@ describe('createAdminConfigHandlers', () => {
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();
});
@@ -671,7 +677,7 @@ describe('createAdminConfigHandlers', () => {
await handlers.upsertConfigOverrides(req, res);
expect(res.statusCode).toBe(403);
- expect(res.body).toEqual({ error: 'Insufficient permissions' });
+ expect(res.body).toEqual({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
@@ -984,7 +990,19 @@ describe('createAdminConfigHandlers', () => {
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
- expect(res.body).toEqual({ message: 'No actionable field path provided', revision: null });
+ 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();
});
@@ -1128,7 +1146,19 @@ describe('createAdminConfigHandlers', () => {
await handlers.tombstoneConfigField(req, res);
expect(res.statusCode).toBe(200);
- expect(res.body).toEqual({ message: 'No actionable field path provided', revision: null });
+ 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();
});
@@ -1297,6 +1327,7 @@ describe('createAdminConfigHandlers', () => {
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();
});
@@ -1317,6 +1348,7 @@ describe('createAdminConfigHandlers', () => {
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();
@@ -1373,7 +1405,19 @@ describe('createAdminConfigHandlers', () => {
await handlers.patchConfigField(req, res);
expect(res.statusCode).toBe(200);
- expect(res.body).toEqual({ message: 'No actionable field entries provided', revision: null });
+ 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();
});
@@ -2764,7 +2808,7 @@ describe('createAdminConfigHandlers', () => {
const req = mockReq({
params: { principalType: 'role', principalId: 'admin' },
body: {
- overrides: { registration: { oauthStateTtlMs: 5 }, interface: { modelSelect: false } },
+ overrides: { githubCompare: { timeoutMs: 0 }, interface: { modelSelect: false } },
},
});
const res = mockRes();
@@ -2777,9 +2821,10 @@ describe('createAdminConfigHandlers', () => {
code: 'CONFIG_OVERRIDE_INVALID',
issues: [
{
- path: 'registration.oauthStateTtlMs',
- segments: ['registration', 'oauthStateTtlMs'],
+ path: 'githubCompare.timeoutMs',
+ segments: ['githubCompare', 'timeoutMs'],
code: 'too_small',
+ params: { minimum: 1, inclusive: true, exact: false, type: 'number' },
},
],
});
@@ -2787,18 +2832,19 @@ describe('createAdminConfigHandlers', () => {
});
it('validates a whole-document write on the base its retained tombstones leave', async () => {
- const base = {
- config: {
- cloudfront: { domain: 'https://cdn.example.com', imageSigning: 'cookies' },
- },
- };
- const body = { overrides: { cloudfront: { requireSignedAccess: true } } };
+ /** 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(201);
+ 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),
@@ -2806,16 +2852,13 @@ describe('createAdminConfigHandlers', () => {
_id: 'c1',
configVersion: 1,
overrides: {},
- tombstones: ['cloudfront.imageSigning'],
+ tombstones: ['balance.refillMode'],
}),
});
const tombstonedRes = mockRes();
await tombstoned.handlers.upsertConfigOverrides(mockReq({ params, body }), tombstonedRes);
- expect(tombstonedRes.statusCode).toBe(400);
- expect(tombstonedRes.body?.issues).toEqual([
- expect.objectContaining({ path: 'cloudfront.requireSignedAccess' }),
- ]);
- expect(tombstoned.deps.writeConfigDocument).not.toHaveBeenCalled();
+ expect(tombstonedRes.statusCode).toBe(200);
+ expect(tombstoned.deps.writeConfigDocument).toHaveBeenCalledTimes(1);
});
it('accepts a partial section whose provided fields are valid', async () => {
@@ -2824,7 +2867,7 @@ describe('createAdminConfigHandlers', () => {
params: { principalType: 'role', principalId: 'admin' },
body: {
overrides: {
- registration: { oauthStateTtlMs: 120_000 },
+ registration: { allowedDomains: ['example.com'] },
mcpServers: { github: { timeout: 5000 } },
endpoints: { custom: [{ name: 'groq', apiKey: 'sk-test' }] },
},
@@ -2954,7 +2997,7 @@ describe('createAdminConfigHandlers', () => {
body: {
entries: [
{ fieldPath: 'interface.customWelcome', value: 'hi' },
- { fieldPath: 'registration.oauthStateTtlMs', value: 'soon' },
+ { fieldPath: 'githubCompare.timeoutMs', value: 'soon' },
],
},
});
@@ -2964,7 +3007,12 @@ describe('createAdminConfigHandlers', () => {
expect(res.statusCode).toBe(400);
expect(res.body?.issues).toEqual([
- expect.objectContaining({ path: 'registration.oauthStateTtlMs' }),
+ {
+ path: 'githubCompare.timeoutMs',
+ segments: ['githubCompare', 'timeoutMs'],
+ code: 'invalid_type',
+ params: { expected: 'number', received: 'string' },
+ },
]);
expect(deps.writeConfigDocument).not.toHaveBeenCalled();
});
@@ -4203,6 +4251,15 @@ describe('createAdminConfigHandlers', () => {
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();
});
diff --git a/packages/api/src/admin/config.precedence.integration.spec.ts b/packages/api/src/admin/config.precedence.integration.spec.ts
index f866a57513..f45ddac88e 100644
--- a/packages/api/src/admin/config.precedence.integration.spec.ts
+++ b/packages/api/src/admin/config.precedence.integration.spec.ts
@@ -571,6 +571,48 @@ describe('validation on the Base floor (W2-3)', () => {
expect(res.statusCode).toBe(200);
expect(res.body?.ignored).toEqual(dropped);
}
+
+ /** A read judges the stored profile over the same Base the writes judged it on. */
+ const read = await call(handlers.getConfig, { params: group });
+ expect(read.statusCode).toBe(200);
+ expect(read.body?.ignoredBasis).toBe('base');
+ expect(read.body?.ignored).toEqual(dropped);
+ });
+
+ it("keeps the stdio servers that tenant's librechat.yaml runs out of PUT and tombstones", async () => {
+ const getAppConfig = yamlByTenant({
+ mcpServers: { local: { type: 'stdio', command: 'node', args: ['server.js'] } },
+ } as never);
+ const handlers = createHandlers({}, { getAppConfig });
+ const group = await tenantProfile(handlers, 'group');
+
+ const replaced = await call(handlers.upsertConfigOverrides, {
+ params: group,
+ body: {
+ overrides: {
+ interface: { customWelcome: 'hi' },
+ mcpServers: { local: { title: 'Local' } },
+ },
+ },
+ });
+ const tombstoned = await call(handlers.tombstoneConfigField, {
+ params: group,
+ body: { fieldPath: 'mcpServers.local' },
+ });
+
+ expect(replaced.statusCode).toBe(200);
+ expect(replaced.body?.skipped).toEqual([
+ {
+ path: 'mcpServers.local',
+ segments: ['mcpServers', 'local'],
+ reason: 'process_mcp_server',
+ },
+ ]);
+ expect(tombstoned.statusCode).toBe(400);
+ expect(tombstoned.body?.code).toBe('PROCESS_MCP_SERVER_OVERRIDE');
+ const kept = await stored(group.principalType, group.principalId);
+ expect(kept?.overrides).toEqual({ interface: { customWelcome: 'hi' } });
+ expect(kept?.tombstones ?? []).toEqual([]);
});
});
diff --git a/packages/api/src/admin/config.report.spec.ts b/packages/api/src/admin/config.report.spec.ts
new file mode 100644
index 0000000000..71bd73476e
--- /dev/null
+++ b/packages/api/src/admin/config.report.spec.ts
@@ -0,0 +1,761 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import type { AdminConfigReadResponse } from '@librechat/data-schemas';
+import type { Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+
+process.env.CREDS_KEY =
+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';
+
+type DataSchemas = typeof import('@librechat/data-schemas');
+type Methods = ReturnType<DataSchemas['createMethods']>;
+type AdminConfigHandlers = ReturnType<typeof import('./config').createAdminConfigHandlers>;
+type AdminConfigDeps = Parameters<typeof import('./config').createAdminConfigHandlers>[0];
+type Handler = (req: ServerRequest, res: Response) => Promise<Response>;
+type Location = { path: string; segments: string[]; reason?: string; kind?: string };
+
+interface MockRes {
+ statusCode: number;
+ body: undefined | Record<string, unknown>;
+ status: jest.Mock;
+ json: jest.Mock;
+}
+
+let mongoServer: MongoMemoryServer;
+let methods: Methods;
+let createAdminConfigHandlers: typeof import('./config').createAdminConfigHandlers;
+
+/** librechat.yaml: a stdio server, a remote one, and fields only librechat.yaml sets. */
+const YAML = {
+ mcpServers: {
+ local: { type: 'stdio', command: 'node', args: ['server.js'] },
+ remote: { type: 'streamable-http', url: 'https://mcp.example.com/mcp' },
+ },
+ endpoints: {
+ agents: {
+ pullRequests: { provider: 'github' },
+ eventDriven: { deadLetterRetentionDays: 7 },
+ },
+ },
+ memory: { agent: { id: 'agent_1' } },
+};
+
+function mockReq(overrides: Record<string, unknown> = {}): ServerRequest {
+ return {
+ user: { id: 'u1', role: 'ADMIN', _id: { toString: () => 'u1' } },
+ params: {},
+ body: {},
+ query: {},
+ ...overrides,
+ } as Partial<ServerRequest> as ServerRequest;
+}
+
+function mockRes(): Response & 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;
+}
+
+function createHandlers(overrides: Partial<AdminConfigDeps> = {}): AdminConfigHandlers {
+ return createAdminConfigHandlers({
+ listAllConfigs: methods.listAllConfigs,
+ findConfigByPrincipal: methods.findConfigByPrincipal,
+ writeConfigDocument: methods.writeConfigDocument,
+ unsetConfigField: methods.unsetConfigField,
+ deleteConfig: methods.deleteConfig,
+ toggleConfigActiveTracked: methods.toggleConfigActiveTracked,
+ hasConfigCapability: async () => true,
+ hasAnyConfigReadAccess: async () => true,
+ hasCapability: async () => true,
+ getAppConfig: async () => ({ config: structuredClone(YAML) }) as never,
+ ...overrides,
+ });
+}
+
+let counter = 0;
+function nextParams(): { principalType: string; principalId: string } {
+ counter += 1;
+ return { principalType: 'role', principalId: `report-${counter}` };
+}
+
+async function call(handler: Handler, request: Record<string, unknown>): Promise<MockRes> {
+ const res = mockRes();
+ await handler(mockReq(request), res);
+ return res;
+}
+
+/** Stores a document as an older server or another writer left it, with no write-time checks. */
+async function seed(
+ params: { principalType: string; principalId: string },
+ overrides: Record<string, unknown>,
+ tombstones: string[] = [],
+): Promise<void> {
+ await methods.writeConfigDocument(
+ params.principalType as never,
+ params.principalId,
+ { principalModel: 'Role' as never, priority: 10, overrides, tombstones, isActive: true },
+ 'absent',
+ );
+}
+
+async function stored(params: { principalType: string; principalId: string }) {
+ return methods.findConfigByPrincipal(params.principalType as never, params.principalId, {
+ includeInactive: true,
+ });
+}
+
+/** `kind:path:reason`, sorted, for comparing report lists whatever their order. */
+function describeAll(list: unknown): string[] {
+ return ((list as Location[] | undefined) ?? [])
+ .map(({ path, reason, kind }) => [kind, path, reason].filter(Boolean).join(':'))
+ .sort();
+}
+
+const LIFECYCLE_TIMEOUT_MS = 180_000;
+
+beforeAll(async () => {
+ const [dataSchemas, handlersModule, server] = await Promise.all([
+ import('@librechat/data-schemas'),
+ import('./config'),
+ MongoMemoryServer.create(),
+ ]);
+ mongoServer = server;
+ ({ createAdminConfigHandlers } = handlersModule);
+ jest.spyOn(dataSchemas.logger, 'error').mockReturnValue(dataSchemas.logger);
+ jest.spyOn(dataSchemas.logger, 'warn').mockReturnValue(dataSchemas.logger);
+ jest.spyOn(dataSchemas.logger, 'info').mockReturnValue(dataSchemas.logger);
+
+ await mongoose.connect(mongoServer.getUri());
+ dataSchemas.createModels(mongoose);
+ await mongoose.models.Config.init();
+ methods = dataSchemas.createMethods(mongoose);
+}, LIFECYCLE_TIMEOUT_MS);
+
+afterAll(async () => {
+ await mongoose.disconnect();
+ await mongoServer?.stop();
+}, LIFECYCLE_TIMEOUT_MS);
+
+describe('write report', () => {
+ it('PATCH stores what it can and reports each part it skipped, at its own location', async () => {
+ const params = nextParams();
+ const res = await call(createHandlers().patchConfigField, {
+ params,
+ body: {
+ entries: [
+ { fieldPath: 'interface', value: { prompts: false, modelSelect: true } },
+ {
+ fieldPath: 'endpoints.agents',
+ value: { pullRequests: { provider: 'gitlab' }, recursionLimit: 20 },
+ },
+ { fieldPath: 'rateLimits.fileUploads.ipMax', value: 1 },
+ { fieldPath: 'filters.x', value: 1 },
+ ],
+ },
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.applied).toEqual([
+ { path: 'interface', segments: ['interface'] },
+ { path: 'endpoints.agents', segments: ['endpoints', 'agents'] },
+ ]);
+ expect(describeAll(res.body?.skipped)).toEqual([
+ 'endpoints.agents.pullRequests.provider:base_only_path',
+ 'filters.x:base_only_section',
+ 'interface.prompts:interface_permission',
+ 'rateLimits.fileUploads.ipMax:deployment_only_path',
+ ]);
+ expect((await stored(params))?.overrides).toEqual({
+ interface: { modelSelect: true },
+ endpoints: { agents: { recursionLimit: 20 } },
+ });
+ });
+
+ it('PATCH resets a path whose whole value is skipped, as a written value replaces it', async () => {
+ const params = nextParams();
+ await seed(params, { interface: { customWelcome: 'stored' }, memory: { disabled: true } });
+
+ const res = await call(createHandlers().patchConfigField, {
+ params,
+ body: { entries: [{ fieldPath: 'interface', value: { prompts: false } }] },
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.applied).toEqual([{ path: 'interface', segments: ['interface'] }]);
+ expect(describeAll(res.body?.skipped)).toEqual(['interface.prompts:interface_permission']);
+ expect((await stored(params))?.overrides).toEqual({ memory: { disabled: true } });
+ });
+
+ it('PATCH applies a reset where the request puts it, as a written value would land', async () => {
+ const later = nextParams();
+ const handlers = createHandlers();
+ const resetLast = await call(handlers.patchConfigField, {
+ params: later,
+ body: {
+ entries: [
+ { fieldPath: 'interface.modelSelect', value: true },
+ { fieldPath: 'interface', value: { prompts: false } },
+ { fieldPath: 'memory.disabled', value: true },
+ ],
+ },
+ });
+ expect(resetLast.statusCode).toBe(200);
+ expect((await stored(later))?.overrides).toEqual({ memory: { disabled: true } });
+
+ const earlier = nextParams();
+ const resetFirst = await call(handlers.patchConfigField, {
+ params: earlier,
+ body: {
+ entries: [
+ { fieldPath: 'interface', value: { prompts: false } },
+ { fieldPath: 'interface.modelSelect', value: true },
+ ],
+ },
+ });
+ expect(resetFirst.statusCode).toBe(200);
+ expect((await stored(earlier))?.overrides).toEqual({ interface: { modelSelect: true } });
+ });
+
+ it('PATCH answers a section manager whose every entry is skipped as a write, not a 403', async () => {
+ const params = nextParams();
+ await seed(params, {
+ endpoints: { agents: { recursionLimit: 5 } },
+ memory: { disabled: true },
+ });
+ const sectionManager = createHandlers({
+ hasConfigCapability: async (_user, section) => section === 'endpoints',
+ hasCapability: async () => false,
+ });
+
+ const res = await call(sectionManager.patchConfigField, {
+ params,
+ body: {
+ entries: [
+ { fieldPath: 'endpoints.agents.eventDriven', value: { deadLetterRetentionDays: 3 } },
+ { fieldPath: 'endpoints.agents.pullRequests.provider', value: 'gitlab' },
+ ],
+ },
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toMatchObject({
+ message: 'No actionable field entries provided',
+ applied: [],
+ config: { overrides: { endpoints: { agents: { recursionLimit: 5 } } } },
+ });
+ expect(res.body?.config).not.toHaveProperty('overrides.memory');
+ expect(describeAll(res.body?.skipped)).toEqual([
+ 'endpoints.agents.eventDriven:deployment_only_path',
+ 'endpoints.agents.pullRequests.provider:base_only_path',
+ ]);
+
+ for (const entries of [
+ [{ fieldPath: 'rateLimits.fileUploads.ipMax', value: 1 }],
+ [
+ { fieldPath: 'endpoints.agents.recursionLimit', value: 9 },
+ { fieldPath: 'rateLimits.fileUploads.ipMax', value: 1 },
+ ],
+ ]) {
+ const denied = await call(sectionManager.patchConfigField, { params, body: { entries } });
+ expect([denied.statusCode, denied.body?.code, denied.body?.section]).toEqual([
+ 403,
+ 'FORBIDDEN_SECTION',
+ 'rateLimits',
+ ]);
+ }
+ expect((await stored(params))?.overrides).toEqual({
+ endpoints: { agents: { recursionLimit: 5 } },
+ memory: { disabled: true },
+ });
+ });
+
+ it('PUT leaves out every field only librechat.yaml sets, Base included', async () => {
+ const base = { principalType: 'role', principalId: '__base__' };
+ const res = await call(createHandlers().upsertConfigOverrides, {
+ params: base,
+ body: {
+ overrides: {
+ cloudfront: { domain: 'https://cdn.example.com' },
+ permissions: { leaseTtlMs: 1000 },
+ endpoints: {
+ agents: {
+ toolApproval: { hooks: [{ module: './hooks.js' }] },
+ pullRequests: { host: 'ghe.example.com' },
+ disableBuilder: true,
+ },
+ },
+ registration: { openidDiscovery: { startupAttempts: 2 }, allowedDomains: ['a.com'] },
+ interface: { modelSelect: false, agents: { use: false } },
+ },
+ },
+ });
+
+ expect(res.statusCode).toBe(201);
+ expect(res.body?.applied).toEqual([
+ { path: 'endpoints', segments: ['endpoints'] },
+ { path: 'registration', segments: ['registration'] },
+ { path: 'interface', segments: ['interface'] },
+ ]);
+ expect(describeAll(res.body?.skipped)).toEqual([
+ 'cloudfront:deployment_only_path',
+ 'endpoints.agents.pullRequests.host:base_only_path',
+ 'endpoints.agents.toolApproval.hooks:deployment_only_path',
+ 'interface.agents.use:interface_permission',
+ 'permissions:deployment_only_path',
+ 'registration.openidDiscovery:deployment_only_path',
+ ]);
+ expect((await stored(base))?.overrides).toEqual({
+ endpoints: { agents: { disableBuilder: true } },
+ registration: { allowedDomains: ['a.com'] },
+ interface: { modelSelect: false },
+ });
+ await methods.deleteConfig('role' as never, '__base__');
+ });
+
+ it('a tombstone of a field only librechat.yaml sets is skipped; deleting a stored one is cleanup', async () => {
+ const params = nextParams();
+ await seed(params, { rateLimits: { fileUploads: { ipMax: 1 } }, memory: { disabled: true } });
+ const handlers = createHandlers();
+
+ for (const fieldPath of ['rateLimits', 'endpoints.agents.pullRequests.provider', 'openapi']) {
+ const res = await call(handlers.tombstoneConfigField, { params, body: { fieldPath } });
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toMatchObject({
+ message: 'No actionable field path provided',
+ applied: [],
+ config: expect.objectContaining({ overrides: expect.any(Object) }),
+ });
+ expect(describeAll(res.body?.skipped)).toEqual([
+ `${fieldPath}:${fieldPath === 'endpoints.agents.pullRequests.provider' ? 'base_only_path' : 'deployment_only_path'}`,
+ ]);
+ }
+ expect((await stored(params))?.tombstones).toEqual([]);
+
+ const cleanup = await call(handlers.deleteConfigField, {
+ params,
+ query: { fieldPath: 'rateLimits' },
+ });
+ expect(cleanup.statusCode).toBe(200);
+ expect(cleanup.body?.applied).toEqual([{ path: 'rateLimits', segments: ['rateLimits'] }]);
+ expect(cleanup.body?.skipped).toEqual([]);
+ expect((await stored(params))?.overrides).toEqual({ memory: { disabled: true } });
+ });
+
+ it('refuses a tombstone at an array element, which would hide nothing', async () => {
+ const params = nextParams();
+ const res = await call(createHandlers().tombstoneConfigField, {
+ params,
+ body: { fieldPath: 'endpoints.custom.0' },
+ });
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'inside_array' });
+ expect(await stored(params)).toBeNull();
+ });
+
+ it('reports a tombstone as applied', async () => {
+ const params = nextParams();
+ const handlers = createHandlers();
+ const tombstone = await call(handlers.tombstoneConfigField, {
+ params,
+ body: { fieldPath: 'memory.agent' },
+ });
+ expect(tombstone.statusCode).toBe(200);
+ expect(tombstone.body?.applied).toEqual([
+ { path: 'memory.agent', segments: ['memory', 'agent'] },
+ ]);
+ expect(tombstone.body?.skipped).toEqual([]);
+ });
+
+ it.each([
+ [0, 'too_small', { minimum: 1, inclusive: true, exact: false, type: 'number' }],
+ [2.5, 'invalid_type', { expected: 'integer', received: 'float' }],
+ ])('refuses a recursionLimit of %s with its bound', async (value, code, params) => {
+ const res = await call(createHandlers().patchConfigField, {
+ params: nextParams(),
+ body: { entries: [{ fieldPath: 'endpoints.agents.recursionLimit', value }] },
+ });
+ expect(res.statusCode).toBe(400);
+ expect(res.body?.issues).toEqual([
+ {
+ path: 'endpoints.agents.recursionLimit',
+ segments: ['endpoints', 'agents', 'recursionLimit'],
+ code,
+ params,
+ },
+ ]);
+ });
+});
+
+describe('MCP servers librechat.yaml runs as local processes', () => {
+ it('refuses a field write or tombstone inside one, and keeps the process-field refusal', async () => {
+ const params = nextParams();
+ const handlers = createHandlers();
+
+ const title = await call(handlers.patchConfigField, {
+ params,
+ body: { entries: [{ fieldPath: 'mcpServers.local.title', value: 'Local' }] },
+ });
+ expect(title.statusCode).toBe(400);
+ expect(title.body).toEqual({
+ error:
+ 'An MCP server librechat.yaml runs as a local process can only be configured in librechat.yaml',
+ code: 'PROCESS_MCP_SERVER_OVERRIDE',
+ });
+
+ const args = await call(handlers.patchConfigField, {
+ params,
+ body: { entries: [{ fieldPath: 'mcpServers.local.args', value: ['x'] }] },
+ });
+ expect(args.statusCode).toBe(400);
+ expect(args.body?.code).toBe('PROCESS_MCP_CONFIG');
+
+ for (const fieldPath of ['mcpServers.local', 'mcpServers.local.timeout']) {
+ const tombstone = await call(handlers.tombstoneConfigField, { params, body: { fieldPath } });
+ expect(tombstone.statusCode).toBe(400);
+ expect(tombstone.body?.code).toBe('PROCESS_MCP_SERVER_OVERRIDE');
+ }
+ expect(await stored(params)).toBeNull();
+
+ const remote = await call(handlers.patchConfigField, {
+ params,
+ body: { entries: [{ fieldPath: 'mcpServers.remote.title', value: 'Remote' }] },
+ });
+ expect(remote.statusCode).toBe(200);
+ });
+
+ it('a whole-document or whole-section write leaves one out, so a stored no-op round-trips', async () => {
+ const params = nextParams();
+ await seed(params, {
+ mcpServers: { local: { title: 'Local' }, remote: { title: 'Remote' } },
+ });
+ const handlers = createHandlers();
+
+ const read = await call(handlers.getConfig, { params });
+ expect(describeAll(read.body?.ignored)).toEqual([
+ 'override:mcpServers.local:process_mcp_server',
+ ]);
+
+ const put = await call(handlers.upsertConfigOverrides, {
+ params,
+ body: { overrides: (read.body?.config as { overrides: object }).overrides },
+ });
+ expect(put.statusCode).toBe(200);
+ expect(describeAll(put.body?.skipped)).toEqual(['mcpServers.local:process_mcp_server']);
+ expect((await stored(params))?.overrides).toEqual({
+ mcpServers: { remote: { title: 'Remote' } },
+ });
+
+ const section = await call(handlers.patchConfigField, {
+ params,
+ body: { entries: [{ fieldPath: 'mcpServers', value: { local: { title: 'L' } } }] },
+ });
+ expect(section.statusCode).toBe(200);
+ expect(describeAll(section.body?.skipped)).toEqual(['mcpServers.local:process_mcp_server']);
+ expect((await stored(params))?.overrides).toEqual({});
+ });
+
+ it('still lets a field delete clean up what an older server stored there', async () => {
+ const params = nextParams();
+ await seed(params, { mcpServers: { local: { title: 'Local' } } });
+
+ const res = await call(createHandlers().deleteConfigField, {
+ params,
+ query: { fieldPath: 'mcpServers.local.title' },
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect((await stored(params))?.overrides).toEqual({});
+ });
+});
+
+describe('GET reports what the merge leaves out of a stored document', () => {
+ it('lists each stored part by location, reason and kind, judged over the Base floor', async () => {
+ const params = nextParams();
+ await seed(
+ params,
+ {
+ paths: { uploads: '/tmp' },
+ rateLimits: { fileUploads: { ipMax: 1 } },
+ interface: { prompts: false, modelSelect: true },
+ githubCompare: { timeoutMs: 40_000 },
+ endpoints: { agents: { pullRequests: { provider: 'gitlab' } } },
+ },
+ ['filters', 'endpoints.agents'],
+ );
+
+ const res = await call(createHandlers().getConfig, { params });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.ignoredBasis).toBe('base');
+ expect(describeAll(res.body?.ignored)).toEqual([
+ 'override:endpoints.agents.pullRequests.provider:base_only_path',
+ 'override:githubCompare.timeoutMs:invalid',
+ 'override:interface.prompts:interface_permission',
+ 'override:paths:unknown_section',
+ 'override:rateLimits:deployment_only_path',
+ 'tombstone:endpoints.agents.eventDriven:deployment_only_path',
+ 'tombstone:endpoints.agents.pullRequests.provider:base_only_path',
+ 'tombstone:filters:base_only_section',
+ ]);
+ });
+
+ it('judges a profile on the active Base, and Base on librechat.yaml alone', async () => {
+ const base = { principalType: 'role', principalId: '__base__' };
+ await seed(base, { memory: { agent: { provider: 'openAI', model: 'gpt-4o' } } }, [
+ 'memory.agent.id',
+ ]);
+ const params = nextParams();
+ await seed(params, { memory: { agent: { model: 'gpt-4.1' } } });
+ const handlers = createHandlers();
+
+ const profile = await call(handlers.getConfig, { params });
+ expect(profile.body?.ignored).toEqual([]);
+
+ const baseRead = await call(handlers.getConfig, { params: base });
+ expect(baseRead.body?.ignoredBasis).toBe('yaml');
+ expect(baseRead.body?.ignored).toEqual([]);
+
+ await methods.deleteConfig('role' as never, '__base__');
+ const withoutBase = await call(handlers.getConfig, { params });
+ expect(describeAll(withoutBase.body?.ignored)).toEqual(['override:memory.agent.model:invalid']);
+ });
+
+ it('shows a section-scoped reader only the sections it can read', async () => {
+ const params = nextParams();
+ await seed(params, { rateLimits: { fileUploads: { ipMax: 1 } }, filters: { x: 1 } });
+
+ const res = await call(
+ createHandlers({
+ getReadableConfigSections: async () => ({ broad: false, sections: new Set(['filters']) }),
+ }).getConfig,
+ { params },
+ );
+
+ expect(describeAll(res.body?.ignored)).toEqual(['override:filters:base_only_section']);
+ });
+
+ it('still answers with the document when the Base document cannot be read', async () => {
+ const params = nextParams();
+ await seed(params, { rateLimits: { fileUploads: { ipMax: 1 } } });
+
+ const res = await call(
+ createHandlers({
+ findConfigByPrincipal: async (principalType, principalId, options) => {
+ if (principalId === '__base__') {
+ throw new Error('base unavailable');
+ }
+ return methods.findConfigByPrincipal(principalType, principalId, options);
+ },
+ }).getConfig,
+ { params },
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect((res.body?.config as { overrides: object }).overrides).toEqual({
+ rateLimits: { fileUploads: { ipMax: 1 } },
+ });
+ expect(res.body).not.toHaveProperty('ignored');
+ });
+
+ it('leaves the report out, rather than claiming nothing is ignored, when it cannot judge', async () => {
+ const params = nextParams();
+ await seed(params, { rateLimits: { fileUploads: { ipMax: 1 } } });
+
+ const res = await call(
+ createHandlers({
+ getAppConfig: async () => {
+ throw new Error('yaml unavailable');
+ },
+ }).getConfig,
+ { params },
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body).not.toHaveProperty('ignored');
+ const noBase = await call(createHandlers({ getAppConfig: undefined }).getConfig, { params });
+ expect(noBase.statusCode).toBe(200);
+ expect(noBase.body).not.toHaveProperty('ignored');
+ expect(noBase.body).not.toHaveProperty('ignoredBasis');
+ /** The read contract types this answer: a document whose report is left out. */
+ const unjudged: AdminConfigReadResponse = {
+ config: noBase.body?.config as AdminConfigReadResponse['config'],
+ };
+ expect(noBase.body).toEqual(unjudged);
+ });
+});
+
+describe('every 4xx a config handler answers carries a stable code', () => {
+ const params = { principalType: 'role', principalId: 'codes' };
+ const cases: Array<[string, keyof AdminConfigHandlers, Record<string, unknown>, string]> = [
+ [
+ 'bad principal type',
+ 'getConfig',
+ { params: { ...params, principalType: 'x' } },
+ 'INVALID_PRINCIPAL_TYPE',
+ ],
+ ['missing document', 'getConfig', { params }, 'CONFIG_NOT_FOUND'],
+ [
+ 'overrides not an object',
+ 'upsertConfigOverrides',
+ { params, body: { overrides: [] } },
+ 'INVALID_OVERRIDES',
+ ],
+ [
+ 'bad priority',
+ 'upsertConfigOverrides',
+ { params, body: { overrides: {}, priority: -1 } },
+ 'INVALID_PRIORITY',
+ ],
+ [
+ 'bad revision',
+ 'upsertConfigOverrides',
+ { params, body: { overrides: {}, expectedRevision: 'x' } },
+ 'INVALID_EXPECTED_REVISION',
+ ],
+ [
+ 'process server config',
+ 'upsertConfigOverrides',
+ { params, body: { overrides: { mcpServers: { s: { command: 'x' } } } } },
+ 'PROCESS_MCP_CONFIG',
+ ],
+ ['no entries', 'patchConfigField', { params, body: { entries: [] } }, 'ENTRIES_REQUIRED'],
+ [
+ 'too many entries',
+ 'patchConfigField',
+ {
+ params,
+ body: {
+ entries: Array.from({ length: 101 }, (_, i) => ({
+ fieldPath: `interface.x${i}`,
+ value: 1,
+ })),
+ },
+ },
+ 'PATCH_TOO_LARGE',
+ ],
+ [
+ 'unsafe path',
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'a..b', value: 1 }] } },
+ 'INVALID_FIELD_PATH',
+ ],
+ [
+ 'unknown section',
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'paths.uploads', value: 1 }] } },
+ 'UNKNOWN_SECTION',
+ ],
+ [
+ 'duplicate path',
+ 'patchConfigField',
+ {
+ params,
+ body: {
+ entries: [
+ { fieldPath: 'interface.a', value: 1 },
+ { fieldPath: 'interface.a', value: 2 },
+ ],
+ },
+ },
+ 'DUPLICATE_FIELD_PATH',
+ ],
+ [
+ 'langfuse headers',
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'langfuse.headers', value: {} }] } },
+ 'LANGFUSE_HEADERS_CONFIG',
+ ],
+ [
+ 'secret preview',
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'langfuse.secretKeyPreview', value: 'x' }] } },
+ 'SECRET_PATH',
+ ],
+ [
+ 'invalid value',
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'githubCompare.timeoutMs', value: 0 }] } },
+ 'CONFIG_OVERRIDE_INVALID',
+ ],
+ [
+ 'tombstone without a path',
+ 'tombstoneConfigField',
+ { params, body: {} },
+ 'INVALID_FIELD_PATH',
+ ],
+ ['delete without a path', 'deleteConfigField', { params, query: {} }, 'INVALID_FIELD_PATH'],
+ [
+ 'delete of a missing document',
+ 'deleteConfigField',
+ { params, query: { fieldPath: 'memory.disabled' } },
+ 'CONFIG_NOT_FOUND',
+ ],
+ ['toggle without isActive', 'toggleConfig', { params, body: {} }, 'INVALID_IS_ACTIVE'],
+ [
+ 'toggle of a missing document',
+ 'toggleConfig',
+ { params, body: { isActive: false } },
+ 'CONFIG_NOT_FOUND',
+ ],
+ ['delete of a missing profile', 'deleteConfigOverrides', { params }, 'CONFIG_NOT_FOUND'],
+ ['no ops', 'applyConfigChanges', { params, body: { ops: [] } }, 'OPS_REQUIRED'],
+ ];
+
+ it.each(cases)('%s', async (_label, handler, request, code) => {
+ const res = await call(createHandlers()[handler], request);
+ expect(res.statusCode).toBeGreaterThanOrEqual(400);
+ expect(res.statusCode).toBeLessThan(500);
+ expect(res.body).toMatchObject({ code, error: expect.any(String) });
+ });
+
+ it('answers 401 and 403 with codes on every route', async () => {
+ const denied = createHandlers({
+ hasConfigCapability: async () => false,
+ hasAnyConfigReadAccess: async () => false,
+ hasCapability: async () => false,
+ });
+ const routes: Array<[keyof AdminConfigHandlers, Record<string, unknown>]> = [
+ ['listConfigs', {}],
+ ['getConfigMeta', {}],
+ ['getBaseConfig', {}],
+ ['getConfig', { params }],
+ ['upsertConfigOverrides', { params, body: { overrides: { memory: {} } } }],
+ [
+ 'patchConfigField',
+ { params, body: { entries: [{ fieldPath: 'memory.disabled', value: true }] } },
+ ],
+ ['tombstoneConfigField', { params, body: { fieldPath: 'memory.disabled' } }],
+ ['deleteConfigField', { params, query: { fieldPath: 'memory.disabled' } }],
+ ['applyConfigChanges', { params, body: { ops: [{ op: 'unset', fieldPath: 'memory' }] } }],
+ ['deleteConfigOverrides', { params }],
+ ['toggleConfig', { params, body: { isActive: true } }],
+ ['updateConfigPriority', { params, body: { priority: 1 } }],
+ ['reloadConfig', {}],
+ ];
+ for (const [handler, request] of routes) {
+ const forbidden = await call(denied[handler], request);
+ expect([handler, forbidden.statusCode, forbidden.body?.code]).toEqual([
+ handler,
+ 403,
+ expect.stringMatching(/^FORBIDDEN/),
+ ]);
+ const anonymous = await call(denied[handler], { ...request, user: undefined });
+ expect([handler, anonymous.statusCode, anonymous.body?.code]).toEqual([
+ handler,
+ 401,
+ 'AUTH_REQUIRED',
+ ]);
+ }
+ });
+});
diff --git a/packages/api/src/admin/config.store.spec.ts b/packages/api/src/admin/config.store.spec.ts
index 89415b6ba1..66e55cf591 100644
--- a/packages/api/src/admin/config.store.spec.ts
+++ b/packages/api/src/admin/config.store.spec.ts
@@ -651,7 +651,10 @@ describe('segment addressing on the field routes', () => {
expect(both.statusCode).toBe(400);
expect(duplicate.statusCode).toBe(400);
- expect(duplicate.body).toEqual({ error: 'Duplicate field path segments' });
+ expect(duplicate.body).toEqual({
+ error: 'Duplicate field path segments',
+ code: 'DUPLICATE_FIELD_PATH',
+ });
expect(await raw().countDocuments({ principalId: params.principalId })).toBe(0);
});
diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.ts
index f8123d97bc..87120101a4 100644
--- a/packages/api/src/admin/config.ts
+++ b/packages/api/src/admin/config.ts
@@ -1,7 +1,6 @@
import {
BASE_PRINCIPAL_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_SECTIONS,
- BASE_ONLY_CONFIG_PATHS,
configSchema,
PrincipalType,
PrincipalModel,
@@ -56,6 +55,8 @@ import {
replaceConfigOverrides,
parseConfigPathSegments,
getConfigOverrideIssues,
+ getIgnoredConfigOverrides,
+ YAML_HELD_PATHS,
getExpectedRevision,
MAX_CONFIG_PATH_DEPTH,
getDefaultConfigPriority,
@@ -91,6 +92,11 @@ import type {
AdminConfigSkipReason,
AdminConfigIgnoreReason,
AdminConfigIgnoredSecret,
+ AdminConfigLocation,
+ AdminConfigWriteReport,
+ AdminConfigErrorCode,
+ AdminConfigIgnoredOverride,
+ AdminConfigInvalidResponse,
AdminConfigChangesResponse,
AdminConfigChangeErrorResponse,
AdminConfigReloadResponse,
@@ -98,6 +104,7 @@ import type {
ConfigMutationOutcome,
ConfigMutationPlan,
ConfigIdentityStep,
+ YamlHeldPath,
} from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
import type { Response } from 'express';
@@ -299,7 +306,9 @@ function fieldTargetErrorResponse(
failure: { error: string; reason?: ConfigPathErrorReason },
): Response {
const { error, reason } = failure;
- return res.status(400).json(reason ? { error, code: 'CONFIG_PATH_INVALID', reason } : { error });
+ return reason
+ ? errorResponse(res, 400, 'CONFIG_PATH_INVALID', error, { reason })
+ : errorResponse(res, 400, 'INVALID_FIELD_PATH', error);
}
/** How a target is named in audit metadata: its dotted path, or its segments when lossy. */
@@ -353,6 +362,87 @@ function toOrderedWrites(
return writes;
}
+/** One step of a field patch: a write, or the reset of a path (a secret with its preview). */
+type PatchStep = { write: ConfigFieldWrite } | { reset: string[][] };
+
+/**
+ * A field patch's steps in request order: each entry's writes as {@link toOrderedWrites} orders
+ * them, and in its place each entry whose whole value was cut out, as the reset of its path.
+ */
+function toOrderedSteps(
+ entries: ReadonlyArray<{ target: FieldTarget; value: unknown; reset: boolean }>,
+ fields: Record<string, unknown>,
+): PatchStep[] {
+ const steps: PatchStep[] = [];
+ let run: Array<{ target: FieldTarget; value: unknown }> = [];
+ const pending = { ...fields };
+ const flush = () => {
+ const runFields: Record<string, unknown> = {};
+ for (const { target } of run) {
+ for (const fieldPath of target.dotFree
+ ? getConfigSecretMutationPaths(target.fieldPath)
+ : []) {
+ if (Object.prototype.hasOwnProperty.call(pending, fieldPath)) {
+ runFields[fieldPath] = pending[fieldPath];
+ delete pending[fieldPath];
+ }
+ }
+ }
+ steps.push(...toOrderedWrites(run, runFields).map((write) => ({ write })));
+ run = [];
+ };
+ for (const entry of entries) {
+ if (!entry.reset) {
+ run.push(entry);
+ continue;
+ }
+ flush();
+ steps.push({ reset: getRemovalPaths(entry.target) });
+ }
+ flush();
+ steps.push(...toOrderedWrites([], pending).map((write) => ({ write })));
+ return steps;
+}
+
+function toStepWrites(steps: readonly PatchStep[]): ConfigFieldWrite[] {
+ return steps.flatMap((step) => ('write' in step ? [step.write] : []));
+}
+
+/**
+ * Validation of a patch with resets, as `getConfigFieldIssues` judges writes alone: the end
+ * state the steps leave, with issues on every written or reset path, and those it introduced.
+ */
+function getPatchStepIssues(
+ steps: readonly PatchStep[],
+ floor: Partial<TCustomConfig>,
+ stored: ConfigRecord | null,
+): ConfigOverrideIssue[] {
+ const written = steps.flatMap((step) =>
+ 'write' in step ? [[...step.write.segments]] : step.reset,
+ );
+ const indexed = getIndexedMergeKeyIssues(written);
+ if (indexed.length > 0) {
+ return indexed;
+ }
+ const lifted = toStepWrites(steps)
+ .map(({ segments }) => [...segments])
+ .filter(isDotFreePath)
+ .map((segments) => segments.join('.'));
+ const candidate = applyPatchSteps(toConfigOverrideState(stored), steps);
+ return getConfigChangeIssues(candidate, floor, stored, written, lifted);
+}
+
+/** Applies a patch's steps in order to the stored document's state. */
+function applyPatchSteps(state: ConfigOverrideState, steps: readonly PatchStep[]) {
+ return steps.reduce(
+ (current, step) =>
+ 'write' in step
+ ? setConfigFields(current, [step.write])
+ : unsetConfigPaths(current, step.reset),
+ state,
+ );
+}
+
/**
* Returns true if `fieldPath` targets an interface permission field or permission sub-key.
*
@@ -522,8 +612,10 @@ function getFieldSkipReason(fieldPath: string): AdminConfigSkipReason | null {
const SKIP_DESCRIPTIONS: Readonly<Record<AdminConfigSkipReason, string>> = {
base_only_section: 'base-only config field %s - configure it in librechat.yaml instead',
base_only_path: 'base-only config path %s - configure it in librechat.yaml instead',
+ deployment_only_path: 'deployment-only config path %s - configure it in librechat.yaml instead',
dedicated_section: 'dedicated tenant-wide config field %s in the generic config API',
interface_permission: 'interface permission field %s — use role permissions instead',
+ process_mcp_server: 'override of process-backed MCP server %s - configure it in librechat.yaml',
};
/** Logs a skipped path; `action` is how the route words it (`Stripping`, `Ignoring tombstone for`). */
@@ -533,28 +625,32 @@ function logSkippedField(action: string, fieldPath: string, reason: AdminConfigS
);
}
-/** Fields of overridable sections only librechat.yaml sets, as segments. */
-const BASE_ONLY_PATHS: ReadonlyArray<readonly string[]> = BASE_ONLY_CONFIG_PATHS.map((path) =>
- path.split('.'),
-);
+/**
+ * Why a write or tombstone at `segments` is skipped because the path is, or lies inside, a field
+ * only librechat.yaml sets. Removing a stored value there is cleanup and is never skipped.
+ */
+function getHeldPathSkipReason(segments: readonly string[]): YamlHeldPath['reason'] | null {
+ return YAML_HELD_PATHS.find((held) => isSegmentPrefix(held.segments, segments))?.reason ?? null;
+}
-/** Whether `segments` is a base-only field or lies inside one. */
-function isBaseOnlyPath(segments: readonly string[]): boolean {
- return BASE_ONLY_PATHS.some((path) => isSegmentPrefix(path, segments));
+/** A part of a written value the API does not store, at its full location. */
+interface SkippedPart {
+ segments: string[];
+ reason: AdminConfigSkipReason;
}
/**
- * Removes the base-only fields below `segments` from a value written there (`endpoints.agents`
- * carrying `pullRequests.provider`), with the objects that leaves empty. Returns the value to
- * store and the full paths it removed.
+ * Removes the fields only librechat.yaml sets below `segments` from a value written there
+ * (`endpoints.agents` carrying `pullRequests.provider` or `eventDriven`), with the objects that
+ * leaves empty. Returns the value to store and the parts it removed.
*/
-function stripBaseOnlyPaths(
+function stripHeldPaths(
segments: readonly string[],
value: unknown,
-): { value: unknown; stripped: string[][] } {
+): { value: unknown; stripped: SkippedPart[] } {
let result = value;
- const stripped: string[][] = [];
- for (const path of BASE_ONLY_PATHS) {
+ const stripped: SkippedPart[] = [];
+ for (const { segments: path, reason } of YAML_HELD_PATHS) {
if (path.length <= segments.length || !isSegmentPrefix(segments, path)) {
continue;
}
@@ -563,11 +659,117 @@ function stripBaseOnlyPaths(
continue;
}
result = pruneEmptyAncestors(unsetAtPath(result, relative), relative);
- stripped.push([...path]);
+ stripped.push({ segments: [...path], reason });
}
return { value: result, stripped };
}
+const PROCESS_MCP_SERVER_OVERRIDE_ERROR =
+ 'An MCP server librechat.yaml runs as a local process can only be configured in librechat.yaml';
+
+/** The MCP servers librechat.yaml (`base`) runs as local processes, by name. */
+function getProcessServerNames(base: Partial<TCustomConfig>): Set<string> {
+ const servers = (base as { mcpServers?: unknown }).mcpServers;
+ if (!isPlainRecord(servers)) {
+ return new Set();
+ }
+ return new Set(
+ Object.entries(servers)
+ .filter(([, serverConfig]) => isProcessMCPServerConfig(serverConfig))
+ .map(([name]) => name),
+ );
+}
+
+/**
+ * Whether `segments` names an MCP server librechat.yaml runs as a local process, or a path inside
+ * one. The merge never applies an override or tombstone there (the process is shared by every
+ * user), so a write or tombstone there is refused rather than stored with no effect.
+ */
+function isProcessServerPath(segments: readonly string[], processServers: ReadonlySet<string>) {
+ return segments.length >= 2 && segments[0] === 'mcpServers' && processServers.has(segments[1]);
+}
+
+/** What a written value stores once the parts the API does not store are cut out. */
+interface FilteredValue {
+ value: unknown;
+ skipped: SkippedPart[];
+ /** Something was cut out and nothing of the value is left: the write resets its path. */
+ emptied: boolean;
+}
+
+function isEmptied(value: unknown): boolean {
+ return value === undefined || (isPlainRecord(value) && Object.keys(value).length === 0);
+}
+
+/**
+ * Removes the servers librechat.yaml runs as local processes from a whole `mcpServers` value
+ * (any other value is returned as is), so a client that writes back the section it read, stored
+ * no-ops included, still succeeds. Applied once librechat.yaml is loaded, after
+ * {@link filterWrittenValue}.
+ */
+function stripProcessServers(
+ segments: readonly string[],
+ value: unknown,
+ processServers: ReadonlySet<string>,
+): FilteredValue {
+ const names =
+ segments.length === 1 && segments[0] === 'mcpServers' && isPlainRecord(value)
+ ? Object.keys(value).filter((name) => processServers.has(name))
+ : [];
+ if (names.length === 0) {
+ return { value, skipped: [], emptied: false };
+ }
+ const kept: Record<string, unknown> = {};
+ for (const [name, server] of Object.entries(value as Record<string, unknown>)) {
+ if (!processServers.has(name)) {
+ defineKey(kept, name, server);
+ }
+ }
+ return {
+ value: kept,
+ skipped: names.map((name) => ({
+ segments: ['mcpServers', name],
+ reason: 'process_mcp_server',
+ })),
+ emptied: isEmptied(kept),
+ };
+}
+
+/**
+ * Cuts out of a value written at `segments` what the generic config API never stores there,
+ * whatever librechat.yaml holds: role-permission fields of a whole `interface`, and fields only
+ * librechat.yaml sets. PUT, PATCH and change batches share it, so each reports the same parts as
+ * skipped.
+ */
+function filterWrittenValue(segments: readonly string[], value: unknown): FilteredValue {
+ const skipped: SkippedPart[] = [];
+ let next = value;
+ if (segments.length === 1 && segments[0] === 'interface' && isPlainRecord(next)) {
+ const filtered = filterInterfaceOverride(next);
+ for (const path of filtered.stripped) {
+ skipped.push({ segments: ['interface', ...path], reason: 'interface_permission' });
+ }
+ if (filtered.stripped.length > 0 && !filtered.value) {
+ return { value: undefined, skipped, emptied: true };
+ }
+ next = filtered.value ?? next;
+ }
+ const held = stripHeldPaths(segments, next);
+ skipped.push(...held.stripped);
+ return { value: held.value, skipped, emptied: skipped.length > 0 && isEmptied(held.value) };
+}
+
+/** A skipped part as the write report names it. */
+function toSkippedLocation(part: SkippedPart): AdminConfigLocation & {
+ reason: AdminConfigSkipReason;
+} {
+ return { path: part.segments.join('.'), segments: part.segments, reason: part.reason };
+}
+
+function toLocation(segments: readonly string[]): AdminConfigLocation {
+ return { path: segments.join('.'), segments: [...segments] };
+}
+
/**
* Positional slot where config methods once took a Mongoose `ClientSession`; the portable
* config store does not join transactions.
@@ -930,21 +1132,93 @@ function toWrittenSectionsAccess(
return hasBroadManage ? FULL_READ_ACCESS : { broad: false, sections: new Set(managedSections) };
}
-/** A write's response: the written document as a read shows it, and what its layer drops. */
+/**
+ * A write's response: the written document as a read shows it, what the write applied and
+ * skipped (`report`, for the field writes), and what its layer drops.
+ */
function sendWrittenConfig(
res: Response,
status: number,
config: ConfigRecord,
access: ReadableSections,
ignoredSecrets: readonly AdminConfigIgnoredSecret[] = [],
+ report?: AdminConfigWriteReport,
): Response {
const ignored = filterIgnoredForReadAccess(ignoredSecrets, access);
return res.status(status).json({
config: toWrittenConfig(config, access),
+ ...report,
...(ignored.length > 0 && { ignored }),
});
}
+/** The write report of a request: the locations it applied, and the parts it skipped. */
+function toWriteReport(
+ applied: ReadonlyArray<readonly string[]>,
+ skipped: readonly SkippedPart[],
+): AdminConfigWriteReport {
+ return { applied: applied.map(toLocation), skipped: skipped.map(toSkippedLocation) };
+}
+
+/** Logs each skipped part; `action` is how the route words it (`Stripping`, `Ignoring tombstone for`). */
+function logSkippedParts(action: string, skipped: readonly SkippedPart[]): void {
+ for (const { segments, reason } of skipped) {
+ logSkippedField(action, segments.join('.'), reason);
+ }
+}
+
+/** A 4xx of the admin config API: a message and a stable code, plus any route-specific fields. */
+function errorResponse(
+ res: Response,
+ status: number,
+ code: AdminConfigErrorCode,
+ error: string,
+ extra?: Record<string, unknown>,
+): Response {
+ return res.status(status).json({ error, code, ...extra });
+}
+
+export function authRequiredResponse(res: Response): Response {
+ return errorResponse(res, 401, 'AUTH_REQUIRED', 'Authentication required');
+}
+
+export function forbiddenResponse(res: Response): Response {
+ return errorResponse(res, 403, 'FORBIDDEN', 'Insufficient permissions');
+}
+
+function forbiddenSectionResponse(res: Response, section: string): Response {
+ return errorResponse(
+ res,
+ 403,
+ 'FORBIDDEN_SECTION',
+ `Insufficient permissions for config section: ${section}`,
+ { section },
+ );
+}
+
+function invalidPrincipalTypeResponse(res: Response, principalType: string): Response {
+ return errorResponse(
+ res,
+ 400,
+ 'INVALID_PRINCIPAL_TYPE',
+ `Invalid principalType: ${principalType}`,
+ );
+}
+
+function configNotFoundResponse(res: Response): Response {
+ return errorResponse(res, 404, 'CONFIG_NOT_FOUND', 'Config not found');
+}
+
+function processServerOverrideResponse(res: Response, extra?: Record<string, unknown>): Response {
+ return errorResponse(
+ res,
+ 400,
+ 'PROCESS_MCP_SERVER_OVERRIDE',
+ PROCESS_MCP_SERVER_OVERRIDE_ERROR,
+ extra,
+ );
+}
+
/**
* Field writes must address a section `configSchema` defines: anything else (`paths`, the raw
* `config`, an AppService alias such as `interfaceConfig`) would reach runtime state. The path
@@ -955,8 +1229,9 @@ function unknownSectionResponse(res: Response): Response {
}
/**
- * Reports only locations and stable codes: schema messages can echo the submitted values.
- * `segments` names the location key by key, since `path` is ambiguous once a record key
+ * Reports only locations, stable codes and the schema's own bounds and options (`params`, from
+ * an allowlist that never copies the submitted value): schema messages can echo the submitted
+ * values. `segments` names the location key by key, since `path` is ambiguous once a record key
* itself holds a dot. `report` adds what a route reports alongside them (a batch's `skipped`).
*/
function invalidOverrideResponse(
@@ -967,9 +1242,11 @@ function invalidOverrideResponse(
return res.status(400).json({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
- issues: issues.map(({ path, segments, code }) => ({ path, segments, code })),
+ issues: issues.map(({ path, segments, code, params }) =>
+ params ? { path, segments, code, params } : { path, segments, code },
+ ),
...report,
- });
+ } satisfies AdminConfigInvalidResponse);
}
/**
@@ -1092,7 +1369,7 @@ function removalStopResponse(res: Response, stop: RemovalStop): Response {
}
return stop.missing === 'principal'
? principalNotFoundResponse(res)
- : res.status(404).json({ error: 'Config not found' });
+ : configNotFoundResponse(res);
}
const INVALID_EXPECTED_REVISION_ERROR =
@@ -1354,8 +1631,11 @@ const INDEXED_PATH_OPS: ReadonlySet<ChangeOpKind> = new Set<ChangeOpKind>([
'rename',
]);
-/** Changes that leave an override in place, which the runtime merge may then drop. */
-const IGNORABLE_OPS: ReadonlySet<ChangeOpKind> = new Set<ChangeOpKind>([
+/**
+ * Changes that leave an override or tombstone at their path, refused inside an MCP server
+ * librechat.yaml runs as a local process (an `unset` there is cleanup).
+ */
+const SERVER_WRITE_OPS: ReadonlySet<ChangeOpKind> = new Set<ChangeOpKind>([
'set',
'tombstone',
'rename',
@@ -1477,30 +1757,19 @@ function prepareSet(
if (skipReason) {
return { ok: true, change: null, skipped: [{ ...ref, reason: skipReason }] };
}
- let value = normalizeInterfaceFieldPatch(target.fieldPath, raw.value);
- const skipped: SkippedChange[] = [];
- if (target.segments.length === 1 && target.segments[0] === 'interface' && isPlainRecord(value)) {
- const filtered = filterInterfaceOverride(value);
- for (const path of filtered.stripped) {
- skipped.push({ ...ref, segments: ['interface', ...path], reason: 'interface_permission' });
- }
- if (filtered.stripped.length > 0 && !filtered.value) {
- return { ok: true, change: { ...base, paths: getRemovalPaths(target) }, skipped };
- }
- value = filtered.value ?? value;
- }
- const stripped = stripBaseOnlyPaths(target.segments, value);
- for (const segments of stripped.stripped) {
- skipped.push({ ...ref, segments, reason: 'base_only_path' });
- }
- if (
- stripped.stripped.length > 0 &&
- isPlainRecord(stripped.value) &&
- Object.keys(stripped.value).length === 0
- ) {
+ const filtered = filterWrittenValue(
+ target.segments,
+ normalizeInterfaceFieldPatch(target.fieldPath, raw.value),
+ );
+ const skipped: SkippedChange[] = filtered.skipped.map(({ segments, reason }) => ({
+ ...ref,
+ segments,
+ reason,
+ }));
+ if (filtered.emptied) {
return { ok: true, change: { ...base, paths: getRemovalPaths(target) }, skipped };
}
- value = stripped.value;
+ const { value } = filtered;
const fields = target.dotFree
? encryptConfigSecretFields({ [target.fieldPath]: value })
: undefined;
@@ -1651,11 +1920,7 @@ function prepareChange(raw: unknown, index: number): PreparedRead {
| PreparedRead
| { ok: true; change: PreparedChange | null; skipped: SkippedChange[] };
if (op === 'set') {
- prepared = prepareSet(
- raw,
- base,
- sectionSkip ?? (isBaseOnlyPath(target.segments) ? 'base_only_path' : null),
- );
+ prepared = prepareSet(raw, base, sectionSkip ?? getHeldPathSkipReason(target.segments));
} else if (isEntryOp(op)) {
prepared = prepareEntryChange(raw, base, sectionSkip);
} else {
@@ -1679,10 +1944,9 @@ function prepareChange(raw: unknown, index: number): PreparedRead {
if (removalError) {
return changeFailure(index, removalError.error, removalError.code);
}
- /** Unsetting a stored base-only field is cleanup, so only a tombstone of one is skipped. */
+ /** Unsetting a stored field only librechat.yaml sets is cleanup: only a tombstone is skipped. */
const skipReason =
- sectionSkip ??
- (op === 'tombstone' && isBaseOnlyPath(target.segments) ? 'base_only_path' : null);
+ sectionSkip ?? (op === 'tombstone' ? getHeldPathSkipReason(target.segments) : null);
prepared = skipReason
? { ok: true, change: null, skipped: [{ ...toChangeRef(base), reason: skipReason }] }
: { ok: true, change: { ...base, paths: getRemovalPaths(target) }, skipped: [] };
@@ -1755,62 +2019,50 @@ function isYamlEntry(base: unknown, change: PreparedChange, name: string): boole
/**
* What `librechat.yaml` keeps whatever an override does: the MCP servers it runs as local
- * processes, and the base-only fields it sets.
+ * processes, and the base-only and deployment-only fields that have a value the merge puts back:
+ * set in `base`, or in `resolved`, the AppConfig librechat.yaml resolves to (defaults included).
*/
interface YamlHeld {
processServers: ReadonlySet<string>;
- baseOnlyPaths: ReadonlyArray<readonly string[]>;
+ heldPaths: readonly YamlHeldPath[];
}
-function getYamlHeld(base: Partial<TCustomConfig>): YamlHeld {
- const servers = (base as { mcpServers?: unknown }).mcpServers;
- const processServers = isPlainRecord(servers)
- ? Object.entries(servers)
- .filter(([, serverConfig]) => isProcessMCPServerConfig(serverConfig))
- .map(([name]) => name)
- : [];
+function getYamlHeld(base: Partial<TCustomConfig>, resolved?: AppConfig): YamlHeld {
return {
- processServers: new Set(processServers),
- baseOnlyPaths: BASE_ONLY_PATHS.filter((path) => getAtPath(base, path) !== undefined),
+ processServers: getProcessServerNames(base),
+ heldPaths: YAML_HELD_PATHS.filter(
+ ({ segments }) =>
+ getAtPath(base, segments) !== undefined || getAtPath(resolved, segments) !== undefined,
+ ),
};
}
type IgnoredPart = { segments: string[]; reason: AdminConfigIgnoreReason };
/**
- * The parts of an applied change under an MCP server librechat.yaml runs as a process, whose
- * overrides the merge never applies: a write, rename or tombstone there, and each such server a
- * tombstone of the whole section leaves in place. An `unset` there is not one: it asks for the
- * YAML value, which is what runs. A rename of a server itself never names a YAML one, which the
- * handler refuses.
+ * The MCP servers librechat.yaml runs as local processes that a tombstone of the whole
+ * `mcpServers` section leaves in place. A change inside one is refused before it applies, and a
+ * whole-section value leaves them out, so this is the only change that reaches one.
*/
function getProcessServerParts(
change: PreparedChange,
processServers: ReadonlySet<string>,
): IgnoredPart[] {
- const [section, name] = change.target.segments;
- if (section !== 'mcpServers' || processServers.size === 0 || !IGNORABLE_OPS.has(change.op)) {
- return [];
- }
- const reason = 'process_mcp_server';
- if (name !== undefined) {
- return processServers.has(name) ? [{ segments: [...change.target.segments], reason }] : [];
- }
- if (change.op === 'tombstone') {
- return [...processServers].map((server) => ({ segments: ['mcpServers', server], reason }));
- }
- if (!isPlainRecord(change.value)) {
+ const { segments } = change.target;
+ if (change.op !== 'tombstone' || segments.length !== 1 || segments[0] !== 'mcpServers') {
return [];
}
- return Object.keys(change.value)
- .filter((server) => processServers.has(server))
- .map((server) => ({ segments: ['mcpServers', server], reason }));
+ return [...processServers].map((server) => ({
+ segments: ['mcpServers', server],
+ reason: 'process_mcp_server',
+ }));
}
/**
- * The parts of an applied change the runtime merge drops: those under a YAML stdio MCP server,
- * and the base-only fields librechat.yaml sets below a tombstone (a tombstone of one itself is
- * skipped), which the merge puts back so the tombstone hides only the rest.
+ * The parts of an applied change the runtime merge drops: the YAML stdio MCP servers a tombstone
+ * of the whole section leaves in place, and the base-only and deployment-only fields
+ * librechat.yaml sets below a tombstone (a tombstone of one itself is skipped), which the merge
+ * puts back so the tombstone hides only the rest.
*/
function getIgnoredParts(change: PreparedChange, held: YamlHeld): IgnoredPart[] {
const parts = getProcessServerParts(change, held.processServers);
@@ -1818,10 +2070,46 @@ function getIgnoredParts(change: PreparedChange, held: YamlHeld): IgnoredPart[]
return parts;
}
const { segments } = change.target;
- const baseOnly = held.baseOnlyPaths
- .filter((path) => path.length > segments.length && isSegmentPrefix(segments, path))
- .map((path): IgnoredPart => ({ segments: [...path], reason: 'base_only_path' }));
- return [...parts, ...baseOnly];
+ const kept = held.heldPaths
+ .filter((path) => path.segments.length > segments.length)
+ .filter((path) => isSegmentPrefix(segments, path.segments))
+ .map((path): IgnoredPart => ({ segments: [...path.segments], reason: path.reason }));
+ return [...parts, ...kept];
+}
+
+/**
+ * A `set` of a whole `mcpServers` value without the servers librechat.yaml runs as local
+ * processes, re-encrypted, and the parts it left out; with nothing left, it resets the path. Any
+ * other change is returned as is.
+ */
+function withoutProcessServers(
+ change: PreparedChange,
+ processServers: ReadonlySet<string>,
+): { change: PreparedChange; skipped: SkippedChange[] } {
+ if (change.op !== 'set' || change.paths) {
+ return { change, skipped: [] };
+ }
+ const filtered = stripProcessServers(change.target.segments, change.value, processServers);
+ if (filtered.skipped.length === 0) {
+ return { change, skipped: [] };
+ }
+ const ref = toChangeRef(change);
+ const skipped = filtered.skipped.map(({ segments, reason }) => ({ ...ref, segments, reason }));
+ if (filtered.emptied) {
+ return {
+ change: {
+ ...change,
+ value: undefined,
+ fields: undefined,
+ paths: getRemovalPaths(change.target),
+ },
+ skipped,
+ };
+ }
+ const fields = change.target.dotFree
+ ? encryptConfigSecretFields({ [change.target.fieldPath]: filtered.value })
+ : undefined;
+ return { change: { ...change, value: filtered.value, fields }, skipped };
}
/** How an applied change is named in audit metadata: its path, plus the entry it addressed. */
@@ -2055,8 +2343,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
/**
- * 200 for a write with nothing to apply, reporting the stored revision. The precondition
- * still holds: a document that is not at `expectedRevision` answers 409, as the write would.
+ * 200 for a write with nothing to apply, reporting the stored revision and, for a field write,
+ * the parts it skipped and the stored document as a read under `access` shows it (`null` when
+ * there is none). The precondition still holds: a document that is not at `expectedRevision`
+ * answers 409, as the write would.
*/
async function noopResponse(
res: Response,
@@ -2064,13 +2354,21 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalType: PrincipalType,
principalId: string,
expectedRevision: ConfigRevision | undefined,
+ report?: { skipped: readonly SkippedPart[]; access: ReadableSections },
): Promise<Response> {
const stored = await readStoredConfig(principalType, principalId);
const revision = stored ? getConfigRevision(stored) : null;
if (expectedRevision && expectedRevision !== getExpectedRevision(stored)) {
return conflictResponse(res, revision, principalType, principalId);
}
- return res.status(200).json({ message, revision });
+ return res.status(200).json({
+ message,
+ revision,
+ ...(report && {
+ config: stored ? toWrittenConfig(stored, report.access) : null,
+ ...toWriteReport([], report.skipped),
+ }),
+ });
}
async function conflictResponse(
@@ -2120,7 +2418,8 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
* destination beside its stored key, or a field of an MCP server that keeps a stored credential
* (judged over librechat.yaml as the document's partition resolves it, as on every write). A
* write that lands in between is re-read and re-checked, or answers 409 under
- * `expectedRevision`. An unset stops when there is no document.
+ * `expectedRevision`. An unset stops when there is no document. `loadedBase` is the base config
+ * the caller already read, if any.
*/
async function removeConfigPath(
principalType: PrincipalType,
@@ -2129,14 +2428,16 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
removal: { tombstone: true; priority?: number } | { tombstone: false },
expectedRevision: ConfigRevision | undefined,
scope: WriteScope,
+ loadedBase?: AppConfig,
): Promise<ConfigMutationOutcome<RemovalStop>> {
const paths = getRemovalPaths(target);
- const baseConfig =
+ const needsBase =
MCP_SECTIONS.has(target.segments[0]) ||
isAzureGroupPath(target.segments) ||
- isBoundKeyPath(target.segments)
- ? await getBaseAppConfig(scope.tenantId)
- : undefined;
+ isBoundKeyPath(target.segments);
+ const baseConfig = needsBase
+ ? (loadedBase ?? (await getBaseAppConfig(scope.tenantId)))
+ : undefined;
const base: Partial<TCustomConfig> = baseConfig?.config ?? {};
return runConfigMutation<RemovalStop>(
{
@@ -2263,6 +2564,70 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
}
+ /**
+ * librechat.yaml and, for any principal but Base, the active Base document of one partition,
+ * to judge a stored document on (`reportStoredIgnored`). A read that fails is logged and comes
+ * back `undefined`, so the document reads without the report rather than with a wrong one.
+ */
+ function loadJudgement(
+ tenantId: string | undefined,
+ isBase: boolean,
+ ): Promise<[AppConfig | undefined, ConfigRecord | null | undefined]> {
+ return Promise.all([
+ getBaseAppConfig(tenantId).catch((error: unknown) => {
+ logger.error(
+ '[adminConfig] getConfig could not load the base config to judge the document:',
+ getSafeErrorMetadata(error),
+ );
+ return undefined;
+ }),
+ isBase
+ ? null
+ : readActiveBase(tenantId).catch((error: unknown) => {
+ logger.error(
+ '[adminConfig] getConfig could not read the Base document to judge the document:',
+ getSafeErrorMetadata(error),
+ );
+ return undefined;
+ }),
+ ]);
+ }
+
+ /**
+ * What the merge leaves out of a stored document's layer (`getIgnoredConfigOverrides`): parts
+ * no merge applies, values set back to librechat.yaml's, values invalid where the merge applies
+ * them, and the credentials it drops (`reportIgnored`), judged over librechat.yaml and, for any
+ * principal but Base, the active Base document (`base`). `null` when there is no base config to
+ * judge on or the judgement fails, which a read reports by leaving `ignored` out rather than
+ * claiming nothing is ignored.
+ */
+ async function reportStoredIgnored(
+ stored: ConfigRecord,
+ tenantId: string | undefined,
+ baseConfig: AppConfig | undefined,
+ base: ConfigRecord | null,
+ ): Promise<Array<AdminConfigIgnoredOverride | AdminConfigIgnoredSecret> | null> {
+ if (!baseConfig) {
+ return null;
+ }
+ try {
+ const baseYaml: Partial<TCustomConfig> = baseConfig.config ?? {};
+ const overrides = getIgnoredConfigOverrides(baseYaml, stored, base ? [base] : [], baseConfig);
+ const secrets = await reportIgnored(stored, tenantId, {
+ baseConfig,
+ envPolicy: getEnvPolicy(baseYaml),
+ base,
+ });
+ return [...overrides, ...secrets];
+ } catch (error) {
+ logger.error(
+ '[adminConfig] Failed to judge what a stored config leaves out:',
+ getSafeErrorMetadata(error),
+ );
+ return null;
+ }
+ }
+
/**
* Binds the keys a planned document holds to the destinations they were entered for
* (`bindSecretDestinations`): a key the request entered, to where the merge sends it over the
@@ -2503,11 +2868,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
try {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const configs = await listAllConfigs();
@@ -2532,11 +2897,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
try {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const baseConfig = await getBaseAppConfig(user.tenantId);
@@ -2561,7 +2926,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
try {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!getAppConfig) {
@@ -2569,7 +2934,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const baseOnly = (req.query as Record<string, unknown>).baseOnly === 'true';
@@ -2601,30 +2966,49 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
- const config = await findConfigByPrincipal(principalType, principalId, {
- includeInactive: true,
- });
+ const isBase = isBaseConfigPrincipal({ principalType, principalId });
+ /**
+ * The document is judged in the partition it merges in, as writes judge it: the caller's,
+ * read beside the document, or, for a group or user document a caller without a tenant
+ * reads from a tenant, that tenant's, read once the document names it.
+ */
+ const activePartition = getActivePartition();
+ const [config, judgedInActive] = await Promise.all([
+ findConfigByPrincipal(principalType, principalId, { includeInactive: true }),
+ loadJudgement(activePartition, isBase),
+ ]);
if (!config) {
- return res.status(404).json({ error: 'Config not found' });
+ return configNotFoundResponse(res);
}
+ const partition = getConfigPartition(config);
+ const [baseConfig, base] =
+ partition === activePartition ? judgedInActive : await loadJudgement(partition, isBase);
const sections = collectConfigSections(config) as ConfigSection[];
const readable = await getReadableConfigSections(user, sections);
const filteredConfig = filterConfigDocForReadAccess(config, readable);
+ const ignored =
+ base === undefined ? null : await reportStoredIgnored(config, partition, baseConfig, base);
- return res.status(200).json({ config: redactConfigForResponse(filteredConfig) });
+ return res.status(200).json({
+ config: redactConfigForResponse(filteredConfig),
+ ...(ignored && {
+ ignored: ignored.filter(({ segments }) => canReadSection(readable, segments[0] ?? '')),
+ ignoredBasis: isBase ? 'yaml' : 'base',
+ }),
+ });
} catch (error) {
logger.error('[adminConfig] getConfig error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to get config' });
@@ -2642,7 +3026,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const { overrides, priority } = req.body as {
@@ -2651,7 +3035,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
- return res.status(400).json({ error: 'overrides must be a plain object' });
+ return errorResponse(res, 400, 'INVALID_OVERRIDES', 'overrides must be a plain object');
}
const expected = readExpectedRevision(
@@ -2668,11 +3052,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const rawOverrides = overrides as Record<string, unknown>;
if (hasProcessMCPServerConfig(rawOverrides.mcpServers)) {
- return res.status(400).json({ error: PROCESS_MCP_CONFIG_ERROR });
+ return errorResponse(res, 400, 'PROCESS_MCP_CONFIG', PROCESS_MCP_CONFIG_ERROR);
}
if (hasLangfuseHeadersOverride(rawOverrides)) {
- return res.status(400).json({ error: LANGFUSE_HEADERS_CONFIG_ERROR });
+ return errorResponse(res, 400, 'LANGFUSE_HEADERS_CONFIG', LANGFUSE_HEADERS_CONFIG_ERROR);
}
if (priority != null && !isValidPriority(priority)) {
@@ -2681,13 +3065,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const hasAssignConfigs =
@@ -2695,7 +3079,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!hasAssignConfigs) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
/**
@@ -2706,58 +3090,46 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (dottedSectionIssues.length > 0) {
return hasBroadManage
? invalidOverrideResponse(res, dottedSectionIssues)
- : res.status(403).json({ error: 'Insufficient permissions' });
+ : forbiddenResponse(res);
}
- const filteredOverrides = {
- ...(overrides as Record<string, unknown>),
- } as Partial<TCustomConfig>;
- for (const section of BASE_ONLY_OVERRIDE_SECTIONS) {
- if (section in filteredOverrides) {
- delete (filteredOverrides as Record<string, unknown>)[section];
- logger.warn(
- `[adminConfig] Stripping base-only config section "${section}" - configure it in librechat.yaml instead`,
- );
- }
- }
- for (const key of Object.keys(filteredOverrides)) {
- const section = getTopLevelSection(key);
- if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(section)) {
- delete (filteredOverrides as Record<string, unknown>)[key];
- logger.warn(
- `[adminConfig] Stripping dedicated tenant-wide config section "${key}" from the generic config API`,
- );
- }
- }
- const iface = (overrides as Record<string, unknown>).interface;
- if (isPlainRecord(iface)) {
- const { value, stripped } = filterInterfaceOverride(iface);
- for (const path of stripped) {
- logSkippedField('Stripping', ['interface', ...path].join('.'), 'interface_permission');
+ /** What the API never stores is cut out section by section, and reported as skipped. */
+ const skipped: SkippedPart[] = [];
+ const filteredOverrides: Record<string, unknown> = {};
+ for (const [section, value] of Object.entries(rawOverrides)) {
+ const skipReason = getFieldSkipReason(section) ?? getHeldPathSkipReason([section]);
+ if (skipReason) {
+ skipped.push({ segments: [section], reason: skipReason });
+ continue;
}
- if (value) {
- (filteredOverrides as Record<string, unknown>).interface = value;
- } else {
- delete (filteredOverrides as Record<string, unknown>).interface;
+ const filtered = filterWrittenValue([section], value);
+ skipped.push(...filtered.skipped);
+ if (!filtered.emptied) {
+ defineKey(filteredOverrides, section, filtered.value);
}
}
- const overrideSections = Object.keys(filteredOverrides);
/** A create-only request is a lifecycle write even when it carries nothing. */
const createOnly = expected.value === ABSENT_CONFIG_REVISION;
+ const noopReport = {
+ skipped,
+ access: hasBroadManage ? FULL_READ_ACCESS : NO_READ_ACCESS,
+ };
- if (overrideSections.length === 0 && priority == null && !createOnly) {
+ if (Object.keys(filteredOverrides).length === 0 && priority == null && !createOnly) {
+ logSkippedParts('Stripping', skipped);
return noopResponse(
res,
'No actionable override sections provided',
principalType,
principalId,
expected.value,
+ noopReport,
);
}
- if (overrideSections.length > 0 && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ if (Object.keys(filteredOverrides).length > 0 && !hasBroadManage) {
+ return forbiddenResponse(res);
}
if (priority != null && !hasBroadManage) {
@@ -2766,20 +3138,48 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
);
}
- for (const section of getConfigSecretSections()) {
- const secretInputError = getConfigSecretInputError(
- section,
- (filteredOverrides as Record<string, unknown>)[section],
+ const scope = await resolveWriteScope(principalType, principalId);
+ const baseConfig =
+ Object.keys(filteredOverrides).length > 0
+ ? await getBaseAppConfig(scope.tenantId)
+ : undefined;
+ const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
+
+ /** A stdio server librechat.yaml runs is left out, so a read written back still succeeds. */
+ const processes = stripProcessServers(
+ ['mcpServers'],
+ filteredOverrides.mcpServers,
+ getProcessServerNames(baseYaml),
+ );
+ if (processes.skipped.length > 0) {
+ skipped.push(...processes.skipped);
+ if (processes.emptied) {
+ delete filteredOverrides.mcpServers;
+ } else {
+ filteredOverrides.mcpServers = processes.value;
+ }
+ }
+ logSkippedParts('Stripping', skipped);
+
+ const overrideSections = Object.keys(filteredOverrides);
+ if (overrideSections.length === 0 && priority == null && !createOnly) {
+ return noopResponse(
+ res,
+ 'No actionable override sections provided',
+ principalType,
+ principalId,
+ expected.value,
+ noopReport,
);
+ }
+
+ for (const section of getConfigSecretSections()) {
+ const secretInputError = getConfigSecretInputError(section, filteredOverrides[section]);
if (secretInputError) {
- return res.status(400).json({ error: secretInputError });
+ return errorResponse(res, 400, 'SECRET_PATH', secretInputError);
}
}
- const scope = await resolveWriteScope(principalType, principalId);
- const baseConfig =
- overrideSections.length > 0 ? await getBaseAppConfig(scope.tenantId) : undefined;
- const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
const envPolicy = getEnvPolicy(baseYaml);
const envIssues = getEnvReferenceIssues(filteredOverrides, envPolicy);
if (envIssues.length > 0) {
@@ -2892,7 +3292,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (!outcome.written) {
const stop = outcome.result;
if (stop.status === 403) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
if (stop.status === 404) {
return principalNotFoundResponse(res);
@@ -2928,6 +3328,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
config,
hasBroadManage ? FULL_READ_ACCESS : NO_READ_ACCESS,
await reportIgnored(config, scope.tenantId, { baseConfig, envPolicy, base: outcome.base }),
+ toWriteReport(
+ overrideSections.map((section) => [section]),
+ skipped,
+ ),
);
} catch (error) {
if (isFieldNameRejection(error)) {
@@ -2953,7 +3357,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const { entries, priority } = req.body as {
@@ -2978,101 +3382,120 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
if (!Array.isArray(entries) || entries.length === 0) {
- return res.status(400).json({ error: 'entries array is required and must not be empty' });
+ return errorResponse(
+ res,
+ 400,
+ 'ENTRIES_REQUIRED',
+ 'entries array is required and must not be empty',
+ );
}
if (entries.length > MAX_PATCH_ENTRIES) {
- return res
- .status(400)
- .json({ error: `entries array exceeds maximum of ${MAX_PATCH_ENTRIES}` });
+ return errorResponse(
+ res,
+ 400,
+ 'PATCH_TOO_LARGE',
+ `entries array exceeds maximum of ${MAX_PATCH_ENTRIES}`,
+ );
}
const targets: Array<{ target: FieldTarget; value: unknown }> = [];
+ /**
+ * Every entry's section, a skipped entry's included: the caller must manage each section it
+ * names, as on `/changes` and the tombstone route, and a write there that the API skips
+ * answers 200 with the report.
+ */
+ const sections = new Set<string>();
for (const entry of entries) {
const read = readFieldTarget(entry?.fieldPath, entry?.segments);
if (!read.ok) {
return fieldTargetErrorResponse(res, read);
}
- if (!isAcceptedOverrideSection(getTopLevelSection(read.target.fieldPath))) {
+ const section = getTopLevelSection(read.target.fieldPath);
+ if (!isAcceptedOverrideSection(section)) {
return unknownSectionResponse(res);
}
const value = entry?.value;
const guardError = getFieldWriteError(read.target.fieldPath, value);
if (guardError) {
- return res.status(400).json({ error: guardError.error });
+ return errorResponse(res, 400, guardError.code, guardError.error);
}
+ sections.add(section);
targets.push({ target: read.target, value });
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
- }
-
- const validEntries = targets
- .map(({ target, value }) => ({
- target,
- value: normalizeInterfaceFieldPatch(target.fieldPath, value),
- }))
- .filter(({ target: { fieldPath } }) => {
- const skipReason = getFieldSkipReason(fieldPath);
- if (skipReason) {
- logSkippedField('Stripping', fieldPath, skipReason);
- }
- return skipReason == null;
- });
+ return authRequiredResponse(res);
+ }
+
+ /**
+ * What the API never stores is cut out entry by entry and reported as skipped. An entry
+ * whose whole value is cut out resets its path (`reset`), as a whole value replaces what
+ * is stored there; every entry applies in request order.
+ */
+ const skipped: SkippedPart[] = [];
+ /** The entries that change the document, in request order. */
+ let ordered: Array<{ target: FieldTarget; value: unknown; reset: boolean }> = [];
+ for (const { target, value } of targets) {
+ const skipReason =
+ getFieldSkipReason(target.fieldPath) ?? getHeldPathSkipReason(target.segments);
+ if (skipReason) {
+ skipped.push({ segments: [...target.segments], reason: skipReason });
+ continue;
+ }
+ const filtered = filterWrittenValue(
+ target.segments,
+ normalizeInterfaceFieldPatch(target.fieldPath, value),
+ );
+ skipped.push(...filtered.skipped);
+ ordered.push({ target, value: filtered.value, reset: filtered.emptied });
+ }
+ const actionable = ordered.map(({ target }) => target);
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
- if (validEntries.length === 0) {
- if (!hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ const managedSections = [...sections];
+ if (!hasBroadManage) {
+ const allowed = await Promise.all(
+ managedSections.map((s) => hasConfigCapability(user, s as ConfigSection, 'manage')),
+ );
+ const denied = managedSections.find((_, i) => !allowed[i]);
+ if (denied) {
+ return forbiddenSectionResponse(res, denied);
}
+ }
+
+ if (ordered.length === 0) {
+ logSkippedParts('Stripping', skipped);
return noopResponse(
res,
'No actionable field entries provided',
principalType,
principalId,
expected.value,
+ { skipped, access: await resolveWriteReadAccess(user, hasBroadManage, managedSections) },
);
}
- const writtenSections = [
- ...new Set(validEntries.map(({ target }) => getTopLevelSection(target.fieldPath))),
- ];
- if (!hasBroadManage) {
- const allowed = await Promise.all(
- writtenSections.map((s) => hasConfigCapability(user, s as ConfigSection, 'manage')),
- );
- const denied = writtenSections.find((_, i) => !allowed[i]);
- if (denied) {
- return res.status(403).json({
- error: `Insufficient permissions for config section: ${denied}`,
- });
- }
- }
-
- const seenPaths = new Set<string>();
- const seenSegments = new Set<string>();
- const fields: Record<string, unknown> = {};
- for (const { target, value } of validEntries) {
- if (!target.dotFree) {
- const key = JSON.stringify(target.segments);
- if (seenSegments.has(key)) {
- return res.status(400).json({ error: 'Duplicate field path segments' });
- }
- seenSegments.add(key);
- continue;
- }
- if (seenPaths.has(target.fieldPath)) {
- return res.status(400).json({ error: `Duplicate fieldPath: ${target.fieldPath}` });
+ const seenTargets = new Set<string>();
+ for (const target of actionable) {
+ const key = target.dotFree ? target.fieldPath : JSON.stringify(target.segments);
+ if (seenTargets.has(key)) {
+ return errorResponse(
+ res,
+ 400,
+ 'DUPLICATE_FIELD_PATH',
+ target.dotFree
+ ? `Duplicate fieldPath: ${target.fieldPath}`
+ : 'Duplicate field path segments',
+ );
}
- seenPaths.add(target.fieldPath);
- fields[target.fieldPath] = value;
+ seenTargets.add(key);
}
if (priority != null && !hasBroadManage) {
@@ -3084,9 +3507,37 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const [{ scope, baseConfig }, access] = await Promise.all([
loadWriteScope(principalType, principalId),
- resolveWriteReadAccess(user, hasBroadManage, writtenSections),
+ resolveWriteReadAccess(user, hasBroadManage, managedSections),
]);
const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
+
+ /**
+ * librechat.yaml's stdio servers are shared processes no override changes: a write inside
+ * one is refused, and one in a whole `mcpServers` value is left out (and reported).
+ */
+ const processServers = getProcessServerNames(baseYaml);
+ if (actionable.some((target) => isProcessServerPath(target.segments, processServers))) {
+ return processServerOverrideResponse(res);
+ }
+ ordered = ordered.map((entry) => {
+ if (entry.reset) {
+ return entry;
+ }
+ const filtered = stripProcessServers(entry.target.segments, entry.value, processServers);
+ skipped.push(...filtered.skipped);
+ return { target: entry.target, value: filtered.value, reset: filtered.emptied };
+ });
+ logSkippedParts('Stripping', skipped);
+
+ const validEntries = ordered.filter(({ reset }) => !reset);
+ const hasResets = validEntries.length < ordered.length;
+ const fields: Record<string, unknown> = {};
+ for (const { target, value } of validEntries) {
+ if (target.dotFree) {
+ fields[target.fieldPath] = value;
+ }
+ }
+
const envPolicy = getEnvPolicy(baseYaml);
const envIssues = validEntries.flatMap(({ target, value }) =>
getEnvReferenceIssues(value, envPolicy, target.segments),
@@ -3131,12 +3582,15 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
carryRenamedConfigSecrets(value, stored?.overrides, renames.renames, fieldPath);
}
}
- const writes = toOrderedWrites(validEntries, preservedFields);
- const fieldIssues = getConfigFieldIssues(writes, floor, stored);
+ const steps = toOrderedSteps(ordered, preservedFields);
+ const writes = toStepWrites(steps);
+ const fieldIssues = hasResets
+ ? getPatchStepIssues(steps, floor, stored)
+ : getConfigFieldIssues(writes, floor, stored);
if (fieldIssues.length > 0) {
return { draft: null, result: { status: 400, issues: fieldIssues } };
}
- const state = setConfigFields(toConfigOverrideState(stored), writes);
+ const state = applyPatchSteps(toConfigOverrideState(stored), steps);
/** A changed URL beside a stored key that stays needs that key entered again. */
const reentry = getKeptKeyReentryIssues(stored, state, entered, baseConfig);
if (reentry.length > 0) {
@@ -3204,7 +3658,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
target: configTarget(principalType, principalId),
metadata: {
operation: 'patch',
- fieldPaths: validEntries.map(({ target }) => describeFieldTarget(target)).join(','),
+ fieldPaths: actionable.map(describeFieldTarget).join(','),
...(renames.renames.length > 0 && { renames: describeRenames(renames.renames) }),
},
});
@@ -3214,6 +3668,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
config,
access,
await reportIgnored(config, scope.tenantId, { baseConfig, envPolicy, base: outcome.base }),
+ toWriteReport(
+ actionable.map((target) => target.segments),
+ skipped,
+ ),
);
} catch (error) {
if (isFieldNameRejection(error)) {
@@ -3235,7 +3693,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const {
@@ -3249,7 +3707,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (segments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {
- return res.status(400).json({ error: 'fieldPath is required' });
+ return errorResponse(res, 400, 'INVALID_FIELD_PATH', 'fieldPath is required');
}
if (priority != null && !isValidPriority(priority)) {
@@ -3279,20 +3737,27 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (!isAcceptedOverrideSection(section)) {
return unknownSectionResponse(res);
}
+ /** The merge hides inherited values in objects only, so a tombstone there would do nothing. */
+ if (isConfigArrayItemPath(read.target.segments)) {
+ return fieldTargetErrorResponse(res, {
+ error: 'A tombstone can hide a whole array, not an element or a path inside one',
+ reason: 'inside_array',
+ });
+ }
const removalError = getFieldRemovalError(fieldPath);
if (removalError) {
- return res.status(400).json({ error: removalError.error });
+ return errorResponse(res, 400, removalError.code, removalError.error);
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const [canManageSection, access] = await Promise.all([
@@ -3300,12 +3765,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
resolveWriteReadAccess(user, hasBroadManage, [section]),
]);
if (!canManageSection) {
- return res.status(403).json({
- error: `Insufficient permissions for config section: ${section}`,
- });
+ return forbiddenSectionResponse(res, section);
}
- const skipReason = getFieldSkipReason(fieldPath);
+ const skipReason =
+ getFieldSkipReason(fieldPath) ?? getHeldPathSkipReason(read.target.segments);
if (skipReason) {
logSkippedField('Ignoring tombstone for', fieldPath, skipReason);
return noopResponse(
@@ -3314,9 +3778,19 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalType,
principalId,
expected.value,
+ { skipped: [{ segments: [...read.target.segments], reason: skipReason }], access },
);
}
+ /** A stdio server librechat.yaml runs cannot be hidden, nor can its fields be removed. */
+ const scope = await resolveWriteScope(principalType, principalId);
+ const mcpBase = MCP_SECTIONS.has(section)
+ ? await getBaseAppConfig(scope.tenantId)
+ : undefined;
+ if (isProcessServerPath(read.target.segments, getProcessServerNames(mcpBase?.config ?? {}))) {
+ return processServerOverrideResponse(res);
+ }
+
if (priority != null && !hasBroadManage) {
logger.warn(
`[adminConfig] Ignoring caller-supplied priority on section-scoped tombstone for ${principalType}/${principalId}: only broad manage:configs may modify document priority`,
@@ -3332,7 +3806,8 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
read.target,
{ tombstone: true, priority: requestedPriority },
expected.value,
- await resolveWriteScope(principalType, principalId),
+ scope,
+ mcpBase,
);
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
@@ -3351,7 +3826,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const ignored = isBoundSecretSection(parseFieldPath(fieldPath)[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
- return sendWrittenConfig(res, 200, config, access, ignored);
+ return sendWrittenConfig(
+ res,
+ 200,
+ config,
+ access,
+ ignored,
+ toWriteReport([read.target.segments], []),
+ );
} catch (error) {
logger.error('[adminConfig] tombstoneConfigField error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to tombstone config field' });
@@ -3373,13 +3855,18 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalId: string;
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const { fieldPath: rawFieldPath, segments: rawSegments } = req.query;
if (rawSegments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {
- return res.status(400).json({ error: 'fieldPath query parameter is required' });
+ return errorResponse(
+ res,
+ 400,
+ 'INVALID_FIELD_PATH',
+ 'fieldPath query parameter is required',
+ );
}
const expected = readExpectedRevision(req.query.expectedRevision);
@@ -3398,12 +3885,12 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const { fieldPath } = target;
const removalError = getFieldRemovalError(fieldPath);
if (removalError) {
- return res.status(400).json({ error: removalError.error });
+ return errorResponse(res, 400, removalError.code, removalError.error);
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const section = getTopLevelSection(fieldPath);
@@ -3411,7 +3898,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const [canManageSection, access] = await Promise.all([
@@ -3419,9 +3906,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
resolveWriteReadAccess(user, hasBroadManage, [section]),
]);
if (!canManageSection) {
- return res.status(403).json({
- error: `Insufficient permissions for config section: ${section}`,
- });
+ return forbiddenSectionResponse(res, section);
}
const skipReason = getFieldSkipReason(fieldPath);
@@ -3433,6 +3918,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalType,
principalId,
expected.value,
+ { skipped: [{ segments: [...target.segments], reason: skipReason }], access },
);
}
@@ -3470,7 +3956,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!config) {
- return res.status(404).json({ error: 'Config not found' });
+ return configNotFoundResponse(res);
}
await invalidateCaches(user.tenantId, 'field delete');
@@ -3482,7 +3968,14 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const ignored = isBoundSecretSection(target.segments[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
- return sendWrittenConfig(res, 200, config, access, ignored);
+ return sendWrittenConfig(
+ res,
+ 200,
+ config,
+ access,
+ ignored,
+ toWriteReport([target.segments], []),
+ );
} catch (error) {
logger.error('[adminConfig] deleteConfigField error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to delete config field' });
@@ -3573,13 +4066,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
+ return forbiddenResponse(res);
}
const managedSections = [...sections];
@@ -3591,11 +4084,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
);
const denied = managedSections.find((_, i) => !allowed[i]);
if (denied) {
- return res.status(403).json({
- error: `Insufficient permissions for config section: ${denied}`,
- code: 'FORBIDDEN_SECTION',
- section: denied,
- });
+ return forbiddenSectionResponse(res, denied);
}
}
@@ -3630,7 +4119,24 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
});
}
}
- const yamlHeld = getYamlHeld(baseYaml);
+ const yamlHeld = getYamlHeld(baseYaml, baseConfig);
+ /**
+ * librechat.yaml's stdio servers are shared processes no override changes: a change inside
+ * one is refused, and one in a whole `mcpServers` value is left out (and reported). An
+ * `unset` there is cleanup, as DELETE `/fields` is.
+ */
+ for (let index = 0; index < changes.length; index++) {
+ const change = changes[index];
+ if (
+ SERVER_WRITE_OPS.has(change.op) &&
+ isProcessServerPath(change.target.segments, yamlHeld.processServers)
+ ) {
+ return processServerOverrideResponse(res, { opIndex: change.index });
+ }
+ const stripped = withoutProcessServers(change, yamlHeld.processServers);
+ changes[index] = stripped.change;
+ skipped.push(...stripped.skipped);
+ }
interface ChangesReport {
applied: AdminConfigChangeRef[];
@@ -3909,7 +4415,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const expected = readExpectedRevision(req.query.expectedRevision);
@@ -3919,20 +4425,20 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const allowed =
hasBroadManage ||
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!allowed) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
let config: ConfigRecord | null;
@@ -3950,10 +4456,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
includeInactive: true,
});
if (exists) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
}
- return res.status(404).json({ error: 'Config not found' });
+ return configNotFoundResponse(res);
}
await invalidateCaches(user.tenantId, 'config delete');
@@ -4006,11 +4512,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required', code: 'AUTH_REQUIRED' });
+ return authRequiredResponse(res);
}
if (!(await hasConfigCapability(user, null, 'manage'))) {
- return res.status(403).json({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
+ return forbiddenResponse(res);
}
if (!setConfigPriority) {
@@ -4026,7 +4532,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!updated) {
- return res.status(404).json({ error: 'Config not found', code: 'CONFIG_NOT_FOUND' });
+ return configNotFoundResponse(res);
}
const { config, changed } = updated;
@@ -4065,18 +4571,20 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
try {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required', code: 'AUTH_REQUIRED' });
+ return authRequiredResponse(res);
}
if (user.tenantId) {
- return res.status(403).json({
- error: 'Only an admin without a tenant can reload librechat.yaml',
- code: 'FORBIDDEN',
- });
+ return errorResponse(
+ res,
+ 403,
+ 'FORBIDDEN',
+ 'Only an admin without a tenant can reload librechat.yaml',
+ );
}
if (!(await hasConfigCapability(user, null, 'manage'))) {
- return res.status(403).json({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
+ return forbiddenResponse(res);
}
if (!reloadConfigCaches) {
@@ -4121,12 +4629,12 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
};
if (!validatePrincipalType(principalType)) {
- return res.status(400).json({ error: `Invalid principalType: ${principalType}` });
+ return invalidPrincipalTypeResponse(res, principalType);
}
const { isActive } = req.body as { isActive?: boolean };
if (typeof isActive !== 'boolean') {
- return res.status(400).json({ error: 'isActive boolean is required' });
+ return errorResponse(res, 400, 'INVALID_IS_ACTIVE', 'isActive boolean is required');
}
const expected = readExpectedRevision(
@@ -4138,20 +4646,20 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
const allowed =
hasBroadManage ||
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!allowed) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
let toggled: { config: ConfigRecord; changed: boolean } | null;
@@ -4169,10 +4677,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
includeInactive: true,
});
if (exists) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
}
- return res.status(404).json({ error: 'Config not found' });
+ return configNotFoundResponse(res);
}
const { config, changed } = toggled;
diff --git a/packages/api/src/admin/meta.spec.ts b/packages/api/src/admin/meta.spec.ts
index a0622d41c6..0b09a69ce5 100644
--- a/packages/api/src/admin/meta.spec.ts
+++ b/packages/api/src/admin/meta.spec.ts
@@ -29,6 +29,7 @@ import {
BASE_ONLY_CONFIG_PATHS,
BASE_ONLY_CONFIG_SECTIONS,
PROCESS_MCP_SERVER_FIELDS,
+ DEPLOYMENT_ONLY_CONFIG_PATHS,
INTERFACE_PERMISSION_FIELDS,
mapModelToAzureConfig,
BASE_PRINCIPAL_CONFIG_SECTIONS,
@@ -59,6 +60,7 @@ import {
encryptConfigSecretFields,
resolveRuntimeConfigSecrets,
} from './secrets';
+import { allowBeforeTermsAcceptance, createTermsAcceptanceGate } from '~/middleware/terms';
import { createRequestSanitizer, rejectUnsafeConfigKeys } from '~/middleware/sanitize';
import { resolvePreAuthAppConfig, resolvePreLoginAppConfig } from '~/app/resolve';
import { MCPServersRegistry } from '~/mcp/registry/MCPServersRegistry';
@@ -271,7 +273,7 @@ describe('GET /api/admin/config/meta', () => {
const forbidden = mockRes();
await createHandlers({ hasAnyConfigReadAccess }).getConfigMeta(mockReq(), forbidden);
expect(forbidden.statusCode).toBe(403);
- expect(forbidden.body).toEqual({ error: 'Insufficient permissions' });
+ expect(forbidden.body).toEqual({ error: 'Insufficient permissions', code: 'FORBIDDEN' });
expect(hasAnyConfigReadAccess).toHaveBeenCalledWith(expect.objectContaining({ id: 'u1' }));
});
@@ -300,6 +302,7 @@ describe('GET /api/admin/config/meta', () => {
expect(meta.metaVersion).toBe(1);
expect(Object.keys(meta.versions)).toEqual(['librechat', 'dataProvider', 'configSchema']);
expect(Object.keys(meta.features).sort()).toEqual([
+ 'adminTermsExempt',
'awaitedInvalidation',
'azureGroupSecrets',
'catalogApi',
@@ -309,6 +312,7 @@ describe('GET /api/admin/config/meta', () => {
'envAllowlist',
'envStatus',
'expectedRevision',
+ 'issueParams',
'preAuthBaseOverrides',
'principalCheck',
'priorityRoute',
@@ -321,6 +325,7 @@ describe('GET /api/admin/config/meta', () => {
'secretRebinding',
'sectionAllowlist',
'webSearchStoredKeys',
+ 'writeReport',
'yamlMcpHide',
'yamlSecretPreview',
]);
@@ -338,6 +343,7 @@ describe('GET /api/admin/config/meta', () => {
'baseOnlyPaths',
'baseOnlySections',
'basePrincipalSections',
+ 'deploymentOnlyPaths',
'interface',
'overrideKeyMap',
'processMcpFields',
@@ -374,6 +380,9 @@ describe('GET /api/admin/config/meta', () => {
catalogApi: true,
envStatus: true,
reloadRoute: true,
+ writeReport: true,
+ issueParams: true,
+ adminTermsExempt: true,
});
});
@@ -408,6 +417,7 @@ describe('meta rules equal the rules the server applies', () => {
expect(meta.rules.baseOnlySections).toEqual([...BASE_ONLY_CONFIG_SECTIONS]);
expect(meta.rules.basePrincipalSections).toEqual([...BASE_PRINCIPAL_CONFIG_SECTIONS]);
expect(meta.rules.baseOnlyPaths).toEqual([...BASE_ONLY_CONFIG_PATHS]);
+ expect(meta.rules.deploymentOnlyPaths).toEqual({ ...DEPLOYMENT_ONLY_CONFIG_PATHS });
expect(meta.rules.processMcpFields).toEqual([...PROCESS_MCP_SERVER_FIELDS]);
expect(meta.rules.interface).toEqual({
permissionFields: [...INTERFACE_PERMISSION_FIELDS],
@@ -508,7 +518,28 @@ describe('meta rules equal the rules the server applies', () => {
const writeConfigDocument = jest.fn();
for (const section of meta.rules.baseOnlySections) {
const res = await patch([{ fieldPath: `${section}.x`, value: 1 }], { writeConfigDocument });
- expect(res.body).toEqual({ message: 'No actionable field entries provided', revision: null });
+ expect(res.body).toEqual({
+ message: 'No actionable field entries provided',
+ revision: null,
+ config: null,
+ applied: [],
+ skipped: [{ path: `${section}.x`, segments: [section, 'x'], reason: 'base_only_section' }],
+ });
+ }
+ expect(writeConfigDocument).not.toHaveBeenCalled();
+ });
+
+ it('skips writes to every listed deployment-only path, and the merge keeps the YAML value', async () => {
+ const writeConfigDocument = jest.fn();
+ for (const path of Object.keys(meta.rules.deploymentOnlyPaths)) {
+ const res = await patch([{ fieldPath: path, value: 1 }], { writeConfigDocument });
+ expect(res.body?.skipped).toEqual([
+ { path, segments: path.split('.'), reason: 'deployment_only_path' },
+ ]);
+ const merged = mergeConfigOverrides({ config: {} } as AppConfig, [
+ storedConfig(setIn({}, path.split('.'), 1)),
+ ]);
+ expect([path, getIn(merged, path)]).toEqual([path, undefined]);
}
expect(writeConfigDocument).not.toHaveBeenCalled();
});
@@ -1806,6 +1837,130 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {
audited[2].outcome === 'failure'
);
},
+ async writeReport() {
+ const base = {
+ config: {
+ mcpServers: { local: { type: 'stdio', command: 'node', args: ['server.js'] } },
+ },
+ } as Partial<AppConfig> as AppConfig;
+ const getAppConfig = jest.fn().mockResolvedValue(base);
+ const writeConfigDocument = jest.fn(
+ async (_type: string, _id: string, draft: ConfigDraft): Promise<ConfigRecord> =>
+ storedConfig(draft.overrides ?? {}, draft.tombstones),
+ );
+ const written = await patch(
+ [
+ { fieldPath: 'interface', value: { prompts: false, modelSelect: true } },
+ {
+ fieldPath: 'endpoints.agents',
+ value: { eventDriven: { deadLetterRetentionDays: 1 }, recursionLimit: 20 },
+ },
+ { fieldPath: 'rateLimits.fileUploads.ipMax', value: 1 },
+ ],
+ { getAppConfig, writeConfigDocument },
+ );
+ const stdio = await patch([{ fieldPath: 'mcpServers.local.title', value: 'Local' }], {
+ getAppConfig,
+ writeConfigDocument,
+ });
+ const stored = storedConfig(
+ { rateLimits: { fileUploads: { ipMax: 1 } }, mcpServers: { local: { title: 'Local' } } },
+ ['filters'],
+ );
+ const read = mockRes();
+ await createHandlers({
+ getAppConfig,
+ findConfigByPrincipal: jest.fn(async (_type: PrincipalType, id: string) =>
+ id === 'r1' ? stored : null,
+ ),
+ }).getConfig(mockReq({ params: { principalType: 'role', principalId: 'r1' } }), read);
+ const invalid = await write('patchConfigField', {
+ params: { principalType: 'nobody', principalId: 'r1' },
+ body: { entries: [] },
+ });
+ const summarize = (list: unknown) =>
+ (list as Array<{ path: string; reason?: string; kind?: string }>)
+ .map(({ path, reason, kind }) => [kind, path, reason].filter(Boolean).join(':'))
+ .sort();
+ return (
+ written.statusCode === 200 &&
+ JSON.stringify(summarize(written.body?.applied)) ===
+ JSON.stringify(['endpoints.agents', 'interface']) &&
+ JSON.stringify(summarize(written.body?.skipped)) ===
+ JSON.stringify([
+ 'endpoints.agents.eventDriven:deployment_only_path',
+ 'interface.prompts:interface_permission',
+ 'rateLimits.fileUploads.ipMax:deployment_only_path',
+ ]) &&
+ JSON.stringify(writeConfigDocument.mock.calls[0]?.[2].overrides) ===
+ JSON.stringify({
+ interface: { modelSelect: true },
+ endpoints: { agents: { recursionLimit: 20 } },
+ }) &&
+ stdio.statusCode === 400 &&
+ stdio.body?.code === 'PROCESS_MCP_SERVER_OVERRIDE' &&
+ writeConfigDocument.mock.calls.length === 1 &&
+ read.body?.ignoredBasis === 'base' &&
+ JSON.stringify(summarize(read.body?.ignored)) ===
+ JSON.stringify([
+ 'override:mcpServers.local:process_mcp_server',
+ 'override:rateLimits:deployment_only_path',
+ 'tombstone:filters:base_only_section',
+ ]) &&
+ invalid.statusCode === 400 &&
+ invalid.body?.code === 'INVALID_PRINCIPAL_TYPE'
+ );
+ },
+ async issueParams() {
+ const res = await patch([
+ { fieldPath: 'endpoints.agents.recursionLimit', value: 0 },
+ { fieldPath: 'endpoints.allowedAddresses', value: ['localhost'] },
+ ]);
+ const issues = [...((res.body?.issues as Array<{ path: string }>) ?? [])].sort((a, b) =>
+ a.path.localeCompare(b.path),
+ );
+ return (
+ res.statusCode === 400 &&
+ JSON.stringify(issues) ===
+ JSON.stringify([
+ {
+ path: 'endpoints.agents.recursionLimit',
+ segments: ['endpoints', 'agents', 'recursionLimit'],
+ code: 'too_small',
+ params: { minimum: 1, inclusive: true, exact: false, type: 'number' },
+ },
+ {
+ path: 'endpoints.allowedAddresses.0',
+ segments: ['endpoints', 'allowedAddresses', '0'],
+ code: 'custom',
+ params: { reason: 'missing_port' },
+ },
+ ])
+ );
+ },
+ async adminTermsExempt() {
+ const gate = createTermsAcceptanceGate({
+ getAppConfig: jest.fn().mockResolvedValue({
+ interfaceConfig: { termsOfService: { modalAcceptance: true } },
+ }),
+ });
+ const passes = async (optedOut: boolean): Promise<boolean> => {
+ const req = {
+ method: 'PATCH',
+ baseUrl: '/api/admin/config',
+ path: '/role/r1/fields',
+ user: { id: 'u1', role: 'ADMIN', termsAccepted: false },
+ } as unknown as Request;
+ if (optedOut) {
+ allowBeforeTermsAcceptance(req, mockRes(), jest.fn());
+ }
+ const next = jest.fn();
+ const res = mockRes();
+ await gate(req, res, next);
+ return next.mock.calls.length === 1 && res.body === undefined;
+ };
+ return (await passes(true)) && !(await passes(false));
+ },
};
describe('meta feature flags', () => {
diff --git a/packages/api/src/admin/meta.ts b/packages/api/src/admin/meta.ts
index 23be8bbf92..0affa14f12 100644
--- a/packages/api/src/admin/meta.ts
+++ b/packages/api/src/admin/meta.ts
@@ -5,6 +5,7 @@ import {
PERMISSION_SUB_KEYS,
BASE_ONLY_CONFIG_PATHS,
DATA_PROVIDER_VERSION,
+ DEPLOYMENT_ONLY_CONFIG_PATHS,
BASE_ONLY_CONFIG_SECTIONS,
PROCESS_MCP_SERVER_FIELDS,
INTERFACE_PERMISSION_FIELDS,
@@ -52,6 +53,9 @@ export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {
catalogApi: true,
envStatus: true,
reloadRoute: true,
+ writeReport: true,
+ issueParams: true,
+ adminTermsExempt: true,
};
/**
@@ -73,6 +77,7 @@ export function buildAdminConfigMeta(limits: AdminConfigMeta['limits']): AdminCo
baseOnlySections: [...BASE_ONLY_CONFIG_SECTIONS],
basePrincipalSections: [...BASE_PRINCIPAL_CONFIG_SECTIONS],
baseOnlyPaths: [...BASE_ONLY_CONFIG_PATHS],
+ deploymentOnlyPaths: { ...DEPLOYMENT_ONLY_CONFIG_PATHS },
...getConfigMergeRules(),
...getConfigSecretRules(),
processMcpFields: [...PROCESS_MCP_SERVER_FIELDS],
diff --git a/packages/api/src/admin/resolved.integration.spec.ts b/packages/api/src/admin/resolved.integration.spec.ts
index 21a2febde4..87f7d6bb2f 100644
--- a/packages/api/src/admin/resolved.integration.spec.ts
+++ b/packages/api/src/admin/resolved.integration.spec.ts
@@ -361,6 +361,7 @@ describe('GET /resolved/:principalType/:principalId', () => {
hasAnyConfigReadAccess: async () => false,
});
expect(forbidden.statusCode).toBe(403);
+ expect(forbidden.body?.code).toBe('FORBIDDEN');
const invalid = await getResolved('tenant', 'x');
expect(invalid.statusCode).toBe(400);
});
@@ -439,6 +440,7 @@ describe('GET /effective?userId=', () => {
hasCapability: async (_user, capability: SystemCapability) => capability === 'read:users',
});
expect(withoutGroups.statusCode).toBe(403);
+ expect(withoutGroups.body?.code).toBe('FORBIDDEN');
const withoutConfigs = await getEffective(userId, {
hasAnyConfigReadAccess: async () => false,
});
diff --git a/packages/api/src/admin/resolved.ts b/packages/api/src/admin/resolved.ts
index 614f11ae76..c184ffeae0 100644
--- a/packages/api/src/admin/resolved.ts
+++ b/packages/api/src/admin/resolved.ts
@@ -28,6 +28,8 @@ import {
collectConfigSections,
validatePrincipalType,
redactConfigForResponse,
+ forbiddenResponse,
+ authRequiredResponse,
principalNotFoundResponse,
filterSectionsByReadAccess,
filterConfigDocForReadAccess,
@@ -188,10 +190,10 @@ export function createAdminConfigReadHandlers(deps: AdminConfigReadDeps): {
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
if (!resolveConfigLayers) {
return res.status(501).json({ error: 'Resolved config is not available' });
@@ -245,7 +247,7 @@ export function createAdminConfigReadHandlers(deps: AdminConfigReadDeps): {
}
const user = getCapabilityUser(req);
if (!user) {
- return res.status(401).json({ error: 'Authentication required' });
+ return authRequiredResponse(res);
}
const [canReadConfigs, canReadUsers, canReadGroups] = await Promise.all([
hasAnyConfigReadAccess(user),
@@ -253,7 +255,7 @@ export function createAdminConfigReadHandlers(deps: AdminConfigReadDeps): {
hasCapability(user, SystemCapabilities.READ_GROUPS),
]);
if (!canReadConfigs || !canReadUsers || !canReadGroups) {
- return res.status(403).json({ error: 'Insufficient permissions' });
+ return forbiddenResponse(res);
}
if (
!resolveConfigLayers ||
diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.ts
index 7db0338e08..fffadf0bda 100644
--- a/packages/api/src/admin/secrets.integration.spec.ts
+++ b/packages/api/src/admin/secrets.integration.spec.ts
@@ -3980,7 +3980,7 @@ describe('a document an MCP removal creates', () => {
expect(tombstoned.statusCode).toBe(404);
expect(tombstoned.body).toMatchObject({ code: 'PRINCIPAL_NOT_FOUND' });
expect(unset.statusCode).toBe(404);
- expect(unset.body).toEqual({ error: 'Config not found' });
+ expect(unset.body).toEqual({ error: 'Config not found', code: 'CONFIG_NOT_FOUND' });
expect(await mongoose.models.Config.findOne({ principalId })).toBeNull();
},
);
diff --git a/packages/api/src/agents/config.spec.ts b/packages/api/src/agents/config.spec.ts
index 1c6ee4c9af..5ec1bccd96 100644
--- a/packages/api/src/agents/config.spec.ts
+++ b/packages/api/src/agents/config.spec.ts
@@ -1,3 +1,4 @@
+import { logger } from '@librechat/data-schemas';
import type { TAgentsEndpoint } from 'librechat-data-provider';
import {
resolveStreamLimits,
@@ -60,6 +61,36 @@ describe('resolveRecursionLimit', () => {
expect(resolveRecursionLimit(config, { recursion_limit: 30 })).toBe(30);
});
+ it.each([0, -5, 2.5])('treats a yaml recursionLimit of %s as unset', (recursionLimit) => {
+ const config = { recursionLimit } as TAgentsEndpoint;
+ expect(resolveRecursionLimit(config, {})).toBe(50);
+ expect(resolveRecursionLimit(config, { recursion_limit: 20 })).toBe(20);
+ });
+
+ it.each([0.5, 2.5, -1])('ignores a maxRecursionLimit of %s', (maxRecursionLimit) => {
+ const config = { recursionLimit: 100, maxRecursionLimit } as TAgentsEndpoint;
+ expect(resolveRecursionLimit(config, {})).toBe(100);
+ expect(resolveRecursionLimit(config, { recursion_limit: 200 })).toBe(200);
+ });
+
+ it('ignores a fractional agent.recursion_limit', () => {
+ const config = { recursionLimit: 100 } as TAgentsEndpoint;
+ expect(resolveRecursionLimit(config, { recursion_limit: 2.5 })).toBe(100);
+ });
+
+ it('warns once per unusable config value', () => {
+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ const config = { recursionLimit: 0.25, maxRecursionLimit: 0.75 } as TAgentsEndpoint;
+ resolveRecursionLimit(config, {});
+ resolveRecursionLimit(config, {});
+ expect(warn).toHaveBeenCalledTimes(2);
+ expect(warn.mock.calls.map(([message]) => String(message))).toEqual([
+ expect.stringContaining('endpoints.agents.recursionLimit: 0.25'),
+ expect.stringContaining('endpoints.agents.maxRecursionLimit: 0.75'),
+ ]);
+ warn.mockRestore();
+ });
+
it('does not cap when agent.recursion_limit equals maxRecursionLimit', () => {
const config = { recursionLimit: 50, maxRecursionLimit: 150 } as TAgentsEndpoint;
expect(resolveRecursionLimit(config, { recursion_limit: 150 })).toBe(150);
diff --git a/packages/api/src/agents/config.ts b/packages/api/src/agents/config.ts
index 62f28f3d5f..a04c5f5058 100644
--- a/packages/api/src/agents/config.ts
+++ b/packages/api/src/agents/config.ts
@@ -1,3 +1,4 @@
+import { logger } from '@librechat/data-schemas';
import {
DEFAULT_AGENT_MODEL_RESPONSE_BODY_TIMEOUT_MS,
DEFAULT_AGENT_MODEL_RESPONSE_HEADERS_TIMEOUT_MS,
@@ -32,28 +33,58 @@ export function resolveModelTransportTimeouts(
*/
const SUBAGENT_RECURSION_MULTIPLIER = 3;
+/** Whether a recursion limit can bound a run: a whole number of steps, at least one. */
+function isStepLimit(value: unknown): value is number {
+ return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+}
+
+/** Config fields already warned about, by field and value, so a bad value warns once. */
+const warnedLimits = new Set<string>();
+
+/**
+ * An `endpoints.agents` recursion field as a step limit, or `undefined` when unset or unusable:
+ * 0, a negative or a fractional value would make every run fail at once, so it is treated as
+ * unset (with one warning), as the schema now refuses it.
+ */
+function readConfigStepLimit(
+ agentsEConfig: Partial<TAgentsEndpoint> | undefined,
+ field: 'recursionLimit' | 'maxRecursionLimit',
+): number | undefined {
+ const value = agentsEConfig?.[field];
+ if (value == null || isStepLimit(value)) {
+ return value ?? undefined;
+ }
+ const key = `${field}:${String(value)}`;
+ if (!warnedLimits.has(key)) {
+ warnedLimits.add(key);
+ logger.warn(
+ `[resolveRecursionLimit] Ignoring endpoints.agents.${field}: ${String(value)} is not a whole number of at least 1`,
+ );
+ }
+ return undefined;
+}
+
/**
* Resolves the effective recursion limit for an agent run via a 3-step cascade:
* 1. YAML endpoint config default (falls back to 50)
- * 2. Per-agent DB override (if set and positive)
- * 3. Global max cap from YAML (if set and positive)
+ * 2. Per-agent DB override (if set to a whole number of at least 1)
+ * 3. Global max cap from YAML (if set to a whole number of at least 1)
+ *
+ * A config value that is not a whole number of at least 1 counts as unset.
*/
export function resolveRecursionLimit(
agentsEConfig: Partial<TAgentsEndpoint> | undefined,
agent: { recursion_limit?: number } | undefined,
): number {
- let limit = agentsEConfig?.recursionLimit ?? DEFAULT_RECURSION_LIMIT;
+ let limit = readConfigStepLimit(agentsEConfig, 'recursionLimit') ?? DEFAULT_RECURSION_LIMIT;
- if (typeof agent?.recursion_limit === 'number' && agent.recursion_limit > 0) {
+ if (isStepLimit(agent?.recursion_limit)) {
limit = agent.recursion_limit;
}
- if (
- typeof agentsEConfig?.maxRecursionLimit === 'number' &&
- agentsEConfig.maxRecursionLimit > 0 &&
- limit > agentsEConfig.maxRecursionLimit
- ) {
- limit = agentsEConfig.maxRecursionLimit;
+ const maxLimit = readConfigStepLimit(agentsEConfig, 'maxRecursionLimit');
+ if (maxLimit != null && limit > maxLimit) {
+ limit = maxLimit;
}
return limit;
diff --git a/packages/api/src/middleware/capabilities.spec.ts b/packages/api/src/middleware/capabilities.spec.ts
index 3800189d8f..74c97ea709 100644
--- a/packages/api/src/middleware/capabilities.spec.ts
+++ b/packages/api/src/middleware/capabilities.spec.ts
@@ -231,7 +231,7 @@ describe('generateCapabilityCheck', () => {
expect(mockNext).not.toHaveBeenCalled();
expect(statusMock).toHaveBeenCalledWith(403);
- expect(jsonMock).toHaveBeenCalledWith({ message: 'Forbidden' });
+ expect(jsonMock).toHaveBeenCalledWith({ message: 'Forbidden', code: 'FORBIDDEN' });
});
it('returns 401 when no user is present', async () => {
@@ -242,7 +242,10 @@ describe('generateCapabilityCheck', () => {
expect(mockNext).not.toHaveBeenCalled();
expect(statusMock).toHaveBeenCalledWith(401);
- expect(jsonMock).toHaveBeenCalledWith({ message: 'Authentication required' });
+ expect(jsonMock).toHaveBeenCalledWith({
+ message: 'Authentication required',
+ code: 'AUTH_REQUIRED',
+ });
});
it('returns 500 on unexpected error', async () => {
diff --git a/packages/api/src/middleware/capabilities.ts b/packages/api/src/middleware/capabilities.ts
index 97a45f1aee..5179ecf57f 100644
--- a/packages/api/src/middleware/capabilities.ts
+++ b/packages/api/src/middleware/capabilities.ts
@@ -279,13 +279,13 @@ export function generateCapabilityCheck(deps: CapabilityDeps): {
return async (req: ServerRequest, res: Response, next: NextFunction) => {
try {
if (!req.user) {
- res.status(401).json({ message: 'Authentication required' });
+ res.status(401).json({ message: 'Authentication required', code: 'AUTH_REQUIRED' });
return;
}
const id = req.user.id ?? req.user._id?.toString();
if (!id) {
- res.status(401).json({ message: 'Authentication required' });
+ res.status(401).json({ message: 'Authentication required', code: 'AUTH_REQUIRED' });
return;
}
@@ -305,7 +305,7 @@ export function generateCapabilityCheck(deps: CapabilityDeps): {
`missing-capability:${id}:${capability}`,
`[requireCapability] Forbidden: user ${id} missing capability '${capability}'`,
);
- res.status(403).json({ message: 'Forbidden' });
+ res.status(403).json({ message: 'Forbidden', code: 'FORBIDDEN' });
} catch (err) {
logger.error(`[requireCapability] Error checking capability: ${capability}`, err);
res.status(500).json({ message: 'Internal Server Error' });
diff --git a/packages/api/src/middleware/terms.spec.ts b/packages/api/src/middleware/terms.spec.ts
index 0213986795..0ad6bdfba7 100644
--- a/packages/api/src/middleware/terms.spec.ts
+++ b/packages/api/src/middleware/terms.spec.ts
@@ -1,7 +1,12 @@
import { TERMS_NOT_ACCEPTED_CODE } from 'librechat-data-provider';
import type { NextFunction, Request, Response } from 'express';
import type { AppConfig } from '@librechat/data-schemas';
-import { afterTermsGate, createTermsAcceptanceGate, createTermsBlockCheck } from './terms';
+import {
+ afterTermsGate,
+ createTermsBlockCheck,
+ createTermsAcceptanceGate,
+ allowBeforeTermsAcceptance,
+} from './terms';
const configWith = (modalAcceptance?: boolean): AppConfig =>
({ interfaceConfig: { termsOfService: { modalAcceptance } } }) as unknown as AppConfig;
@@ -166,6 +171,46 @@ describe('createTermsAcceptanceGate', () => {
});
});
+describe('allowBeforeTermsAcceptance', () => {
+ it('lets a router that opts out take writes from a user who has not accepted', async () => {
+ const req = createRequest('PATCH', '/api/admin/config/role/USER/fields', {
+ id: 'admin-1',
+ role: 'ADMIN',
+ termsAccepted: false,
+ });
+ const marked = jest.fn();
+ allowBeforeTermsAcceptance(req, createResponse(), marked as NextFunction);
+ expect(marked).toHaveBeenCalledWith();
+
+ const { getAppConfig, ...result } = await run(req);
+ expect(outcome(result)).toBe('allowed');
+ expect(getAppConfig).not.toHaveBeenCalled();
+ });
+
+ it('holds only inside the router that opted out, not one the request reaches after it', async () => {
+ const req = createRequest('POST', '/admin/config/role/USER/fields', {
+ id: 'admin-1',
+ role: 'ADMIN',
+ termsAccepted: false,
+ });
+ req.baseUrl = '/api/admin/config';
+ allowBeforeTermsAcceptance(req, createResponse(), jest.fn() as NextFunction);
+
+ req.baseUrl = '/api';
+ expect(outcome(await run(req))).toBe('blocked');
+ req.baseUrl = '/api/admin/config';
+ expect(outcome(await run(req))).toBe('allowed');
+ });
+
+ it('keeps every request it did not mark gated, on the same path and any other', async () => {
+ const user = { id: 'admin-1', role: 'ADMIN', termsAccepted: false };
+ const sameRoute = createRequest('PATCH', '/api/admin/config/role/USER/fields', user);
+ const chat = createRequest('POST', '/api/agents/chat/agents', user);
+ expect(outcome(await run(sameRoute))).toBe('blocked');
+ expect(outcome(await run(chat))).toBe('blocked');
+ });
+});
+
describe('createTermsBlockCheck', () => {
const check = (config: AppConfig | undefined) =>
createTermsBlockCheck({ getAppConfig: jest.fn().mockResolvedValue(config) });
diff --git a/packages/api/src/middleware/terms.ts b/packages/api/src/middleware/terms.ts
index 894f7fcf67..9974f4f3fa 100644
--- a/packages/api/src/middleware/terms.ts
+++ b/packages/api/src/middleware/terms.ts
@@ -28,6 +28,31 @@ const EXEMPT_POSTS = new Set([
'/api/agents/chat/abort',
]);
+/**
+ * Requests whose router opted out of the gate (`allowBeforeTermsAcceptance`), with the mount path
+ * of that router, so the opt-out holds only while the request is inside it.
+ */
+const routeOptOuts = new WeakMap<Request, string>();
+
+/**
+ * The gate's explicit opt-out, mounted ahead of authentication on a router whose requests the
+ * gate must let through: the admin config API, so an admin who has not accepted the terms can
+ * still read the config and turn off the setting that asks for them. It marks the request object
+ * itself, which no client input reaches, rather than matching a path, and only for the router it
+ * is mounted on: a request that leaves that router unhandled and reaches another is gated there.
+ * Every other route (end-user routes, and admin routes that start work such as skill sync runs or
+ * code pairings) stays gated, and the router's own authentication and capability checks still run.
+ */
+export function allowBeforeTermsAcceptance(req: Request, _res: Response, next: NextFunction): void {
+ routeOptOuts.set(req, req.baseUrl ?? '');
+ next();
+}
+
+/** Whether the request is inside the router that opted it out of the gate. */
+function isOptedOut(req: Request): boolean {
+ return routeOptOuts.has(req) && routeOptOuts.get(req) === (req.baseUrl ?? '');
+}
+
function isExempt(method: string, pathname: string): boolean {
if (method === 'POST') {
return EXEMPT_POSTS.has(pathname);
@@ -59,7 +84,8 @@ export function createTermsBlockCheck(deps: TermsAcceptanceGateDependencies) {
/**
* Enforces `interface.termsOfService.modalAcceptance` on the server: an authenticated user who has
* not accepted the terms may read but not write, so a client that skips the modal cannot start
- * chats, uploads or any other processing. Runs after authentication and reads `termsAccepted` from
+ * chats, uploads or any other processing. A router that mounts `allowBeforeTermsAcceptance`
+ * opts its requests out. Runs after authentication and reads `termsAccepted` from
* the user document already on the request; the config is resolved only for a user who has not
* accepted and is attempting a write.
*/
@@ -70,7 +96,7 @@ export function createTermsAcceptanceGate(
const isBlocked = createTermsBlockCheck(deps);
return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
const user = req.user as TermsUser | undefined;
- if (SAFE_METHODS.has(req.method) || isExempt(req.method, getPathname(req))) {
+ if (SAFE_METHODS.has(req.method) || isOptedOut(req) || isExempt(req.method, getPathname(req))) {
next();
return;
}
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index e7662fb55f..4b22aa5164 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -3,6 +3,10 @@ import type { TEndpointsConfig } from './types';
import {
allowedAddressesSchema,
agentsEndpointSchema,
+ BASE_ONLY_CONFIG_PATHS,
+ BASE_ONLY_CONFIG_SECTIONS,
+ DEPLOYMENT_ONLY_CONFIG_PATHS,
+ getAllowedAddressEntryIssue,
DEFAULT_RETAINED_ANSWER_TOKENS,
DEFAULT_HISTORY_CACHE_MAX_BYTES,
DEFAULT_MAX_RETAINED_TOOL_COUNT_CHARS,
@@ -2093,6 +2097,70 @@ describe('allowedAddressesSchema', () => {
});
});
+ describe('one issue per refused entry', () => {
+ it.each([
+ ['', 'empty'],
+ [' ', 'empty'],
+ ['http://localhost:11434', 'format'],
+ ['10.0.0.0/24', 'format'],
+ ['10.0.0.5 ', 'format'],
+ ['localhost', 'missing_port'],
+ ['10.0.0.5', 'missing_port'],
+ ['localhost:0', 'missing_port'],
+ ['8.8.8.8:53', 'public_ip'],
+ ['[2001:4860:4860::8888]:443', 'public_ip'],
+ ])('reports "%s" once, as %s', (entry, reason) => {
+ expect(getAllowedAddressEntryIssue(entry)).toBe(reason);
+ const result = allowedAddressesSchema.safeParse([entry]);
+ expect(result.success).toBe(false);
+ if (result.success) {
+ return;
+ }
+ expect(result.error.issues).toHaveLength(1);
+ expect(result.error.issues[0]).toMatchObject({
+ code: 'custom',
+ path: [0],
+ params: { reason },
+ });
+ });
+
+ it.each([['localhost:11434'], ['10.0.0.5:11434'], ['[::1]:8080'], ['ollama.internal:443']])(
+ 'accepts "%s" without an issue',
+ (entry) => {
+ expect(getAllowedAddressEntryIssue(entry)).toBeNull();
+ },
+ );
+
+ it('keeps the message of the rule an entry fails', () => {
+ const messages = ['', 'http://x', 'localhost', '8.8.8.8:53'].map((entry) => {
+ const result = allowedAddressesSchema.safeParse([entry]);
+ return result.success ? undefined : result.error.issues[0]?.message;
+ });
+ expect(messages).toEqual([
+ 'allowedAddresses entries must be non-empty',
+ 'allowedAddresses entries must be host:port pairs — no URLs, paths, CIDR ranges, or whitespace',
+ 'allowedAddresses entries must include a port, for example localhost:11434 or [::1]:11434',
+ 'allowedAddresses is scoped to private IP space — public IP literals are not permitted (use hostname:port if it resolves to a private IP)',
+ ]);
+ });
+
+ it('reports a bare host in a config section once', () => {
+ const result = configSchema.safeParse({
+ version: '1.0',
+ endpoints: { allowedAddresses: ['localhost'] },
+ });
+ expect(result.success).toBe(false);
+ if (!result.success) {
+ expect(result.error.issues).toEqual([
+ expect.objectContaining({
+ path: ['endpoints', 'allowedAddresses', 0],
+ params: { reason: 'missing_port' },
+ }),
+ ]);
+ }
+ });
+ });
+
describe('integration with configSchema', () => {
it('accepts the field on endpoints', () => {
const result = configSchema.safeParse({
@@ -3129,3 +3197,69 @@ describe('GitHub comparison configuration', () => {
).toBe(false);
});
});
+
+describe('agent recursion limits', () => {
+ it.each(['recursionLimit', 'maxRecursionLimit'])(
+ '%s takes a whole number of at least 1',
+ (field) => {
+ for (const value of [1, 50, 500]) {
+ expect(agentsEndpointSchema.safeParse({ [field]: value }).success).toBe(true);
+ }
+ for (const value of [0, -5, 2.5, 0.5]) {
+ expect(agentsEndpointSchema.safeParse({ [field]: value }).success).toBe(false);
+ }
+ expect(agentsEndpointSchema.parse({})[field as 'recursionLimit']).toBeUndefined();
+ },
+ );
+});
+
+describe('DEPLOYMENT_ONLY_CONFIG_PATHS', () => {
+ type Node = { _def: { typeName?: string; innerType?: Node; schema?: Node }; shape?: unknown };
+
+ /** The object schema beneath optional, default and refinement wrappers. */
+ function unwrap(node: Node): Node {
+ let current = node;
+ while (current._def.innerType ?? current._def.schema) {
+ current = (current._def.innerType ?? current._def.schema) as Node;
+ }
+ return current;
+ }
+
+ function hasSchemaPath(path: string): boolean {
+ let node: Node | undefined = configSchema as unknown as Node;
+ for (const segment of path.split('.')) {
+ const shape: Record<string, Node> | undefined = node
+ ? (unwrap(node).shape as Record<string, Node> | undefined)
+ : undefined;
+ node = shape?.[segment];
+ if (!node) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ it('names fields configSchema defines', () => {
+ const paths = Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS);
+ expect(paths.length).toBeGreaterThan(0);
+ expect(paths.filter((path) => !hasSchemaPath(path))).toEqual([]);
+ });
+
+ it('declares the tool filters deployment-only', () => {
+ expect(DEPLOYMENT_ONLY_CONFIG_PATHS).toMatchObject({
+ includedTools: 'operator',
+ filteredTools: 'operator',
+ 'endpoints.agents.toolApproval.hooks': 'operator',
+ cache: 'unused',
+ });
+ });
+
+ it('overlaps neither the base-only sections nor the base-only paths', () => {
+ const baseOnly = new Set<string>([...BASE_ONLY_CONFIG_SECTIONS, ...BASE_ONLY_CONFIG_PATHS]);
+ for (const path of Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS)) {
+ const segments = path.split('.');
+ const prefixes = segments.map((_, index) => segments.slice(0, index + 1).join('.'));
+ expect(prefixes.filter((prefix) => baseOnly.has(prefix))).toEqual([]);
+ }
+ });
+});
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 65a5184966..79e5aeae05 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -138,6 +138,45 @@ export const BASE_ONLY_CONFIG_PATHS = [
* `endpoints.catalogModelsTtlMs` sets it: the two minutes a provider's model list is cached for. */
export const DEFAULT_CATALOG_MODELS_TTL_MS = 120_000;
+/**
+ * Why a deployment-only path is set in librechat.yaml only:
+ * - `startup`: read once when the server starts, so a stored value would never apply.
+ * - `operator`: an operator boundary (signed access, rate limits, permission leases, code
+ * modules, which tools load), read from librechat.yaml itself.
+ * - `unused`: nothing reads it any more.
+ */
+export type DeploymentOnlyConfigReason = 'startup' | 'operator' | 'unused';
+
+/**
+ * Paths of overridable sections that only librechat.yaml sets, as YAML key paths. No config
+ * document, Base included, stores them: admin writes skip them, and the merge keeps
+ * librechat.yaml's value. Unlike `BASE_ONLY_CONFIG_PATHS`, their readers never took a value from
+ * the merged config (apart from the tool filters, which only gated `ask_user_question` there), so
+ * a stored override had no effect rather than a dangerous one.
+ */
+export const DEPLOYMENT_ONLY_CONFIG_PATHS: Readonly<Record<string, DeploymentOnlyConfigReason>> = {
+ rateLimits: 'operator',
+ cloudfront: 'operator',
+ permissions: 'operator',
+ openapi: 'operator',
+ skillDeletion: 'startup',
+ includedTools: 'operator',
+ filteredTools: 'operator',
+ 'registration.openidDiscovery': 'startup',
+ 'registration.oauthStateTtlMs': 'startup',
+ 'endpoints.agents.subagentActivity': 'startup',
+ 'endpoints.agents.eventDriven': 'startup',
+ 'endpoints.agents.backgroundTasks.shutdownInterruptGraceMs': 'startup',
+ 'endpoints.agents.backgroundTasks.completionResultBatchSize': 'startup',
+ 'endpoints.agents.backgroundTasks.completionReceiptBatching': 'startup',
+ 'endpoints.agents.toolApproval.hooks': 'operator',
+ 'mcpSettings.catalogRecovery.maxStateEntries': 'startup',
+ 'mcpSettings.catalogRecovery.maxDetachedDiscoveries': 'startup',
+ 'mcpSettings.catalogRecovery.authorizationFenceRetryIntervalMs': 'startup',
+ 'mcpSettings.catalogRecovery.authorizationFenceRetryBatchSize': 'startup',
+ cache: 'unused',
+};
+
export const defaultRetrievalModels = [
'gpt-4o',
'o1-preview-2024-09-12',
@@ -314,36 +353,60 @@ function parseAllowedAddressEntry(entry: string): { address: string; port: strin
return { address, port };
}
-const allowedAddressEntrySchema = z
- .string()
- .refine((entry) => entry.length > 0 && entry.trim().length > 0, {
- message: 'allowedAddresses entries must be non-empty',
- })
- .refine((entry) => !entry.includes('://') && !entry.includes('/') && !/\s/.test(entry), {
- message:
- 'allowedAddresses entries must be host:port pairs — no URLs, paths, CIDR ranges, or whitespace',
- })
- .refine((entry) => parseAllowedAddressEntry(entry) != null, {
- message:
- 'allowedAddresses entries must include a port, for example localhost:11434 or [::1]:11434',
- })
- .refine(
- (entry) => {
- const parsed = parseAllowedAddressEntry(entry);
- if (!parsed) return false;
- const stripped = parsed.address;
- const isIPv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(stripped);
- const isIPv6 = !isIPv4 && stripped.includes(':');
- if (!isIPv4 && !isIPv6) {
- return true; // hostname — checked at runtime via DNS
- }
- return isIPv4 ? isPrivateIPv4Literal(stripped) : isPrivateIPv6Literal(stripped);
- },
- {
- message:
- 'allowedAddresses is scoped to private IP space — public IP literals are not permitted (use hostname:port if it resolves to a private IP)',
- },
- );
+/**
+ * Why an `allowedAddresses` entry is refused, as the `reason` param of its validation issue:
+ * - `empty`: the entry is empty or only whitespace.
+ * - `format`: a URL, path, CIDR range or whitespace instead of a `host:port` pair.
+ * - `missing_port`: no valid port (`localhost`, `10.0.0.5`).
+ * - `public_ip`: an IP literal outside private, loopback and link-local space.
+ */
+export type AllowedAddressIssue = 'empty' | 'format' | 'missing_port' | 'public_ip';
+
+const ALLOWED_ADDRESS_ISSUE_MESSAGES: Readonly<Record<AllowedAddressIssue, string>> = {
+ empty: 'allowedAddresses entries must be non-empty',
+ format:
+ 'allowedAddresses entries must be host:port pairs — no URLs, paths, CIDR ranges, or whitespace',
+ missing_port:
+ 'allowedAddresses entries must include a port, for example localhost:11434 or [::1]:11434',
+ public_ip:
+ 'allowedAddresses is scoped to private IP space — public IP literals are not permitted (use hostname:port if it resolves to a private IP)',
+};
+
+/**
+ * The first rule an `allowedAddresses` entry fails, checked in the order above, or `null` for an
+ * entry the schema accepts. A hostname passes: its resolved IP is checked at runtime.
+ */
+export function getAllowedAddressEntryIssue(entry: string): AllowedAddressIssue | null {
+ if (entry.trim().length === 0) {
+ return 'empty';
+ }
+ if (entry.includes('://') || entry.includes('/') || /\s/.test(entry)) {
+ return 'format';
+ }
+ const parsed = parseAllowedAddressEntry(entry);
+ if (!parsed) {
+ return 'missing_port';
+ }
+ const { address } = parsed;
+ const isIPv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.test(address);
+ if (!isIPv4 && !address.includes(':')) {
+ return null;
+ }
+ const isPrivate = isIPv4 ? isPrivateIPv4Literal(address) : isPrivateIPv6Literal(address);
+ return isPrivate ? null : 'public_ip';
+}
+
+/** One issue per refused entry, with its message and `params.reason`. */
+const allowedAddressEntrySchema = z.string().superRefine((entry, ctx) => {
+ const reason = getAllowedAddressEntryIssue(entry);
+ if (reason) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ message: ALLOWED_ADDRESS_ISSUE_MESSAGES[reason],
+ params: { reason },
+ });
+ }
+});
export const allowedAddressesSchema = z.array(allowedAddressEntrySchema).optional();
@@ -1615,7 +1678,8 @@ export const agentsEndpointSchema = baseEndpointSchema
message: 'Use 0 to disable, or at least 1000 ms',
})
.default(DEFAULT_STREAM_KEEPALIVE_INTERVAL_MS),
- recursionLimit: z.number().optional(),
+ /** Graph steps an agent run may take; a run with fewer than 1 cannot take a step. */
+ recursionLimit: z.number().int().min(1).optional(),
disableBuilder: z.boolean().optional().default(false),
/** Optional workspace guidance acquisition budget, separate from command execution. */
repositoryInstructions: z
@@ -1655,7 +1719,8 @@ export const agentsEndpointSchema = baseEndpointSchema
.default({}),
})
.optional(),
- maxRecursionLimit: z.number().optional(),
+ /** Cap on any agent's `recursion_limit` and on `recursionLimit`. */
+ maxRecursionLimit: z.number().int().min(1).optional(),
/** Max cumulative bytes a single streamed tool call's arguments may reach before the run
* aborts. Defaults to 64 KiB in the agents SDK; `0` disables the guard. */
maxToolCallArgBytes: z.number().optional(),
diff --git a/packages/data-schemas/src/app/resolution.layers.spec.ts b/packages/data-schemas/src/app/resolution.layers.spec.ts
index 3f75944dcf..cb8ffa4a6b 100644
--- a/packages/data-schemas/src/app/resolution.layers.spec.ts
+++ b/packages/data-schemas/src/app/resolution.layers.spec.ts
@@ -391,6 +391,23 @@ describe('resolveConfigLayers', () => {
]);
});
+ it('keeps deployment-only fields at their librechat.yaml value, for writes and tombstones', () => {
+ const configs = [
+ role({ cache: false, rateLimits: { fileUploads: { ipMax: 1 } } }),
+ group({ interface: { customWelcome: 'Hi group' } }, ['cache']),
+ ];
+ const resolution = resolveConfigLayers(appConfig, configs);
+ expect(resolution.merged).toEqual(mergeConfigOverrides(appConfig, configs));
+ expect(resolution.resolved.cache).toBe(true);
+ expect(resolution.resolved).not.toHaveProperty('rateLimits');
+ expect(resolution.resolved.interface?.customWelcome).toBe('Hi group');
+ expect(reasons(ignoredOf(resolution, 0))).toEqual([
+ ['rateLimits', 'deployment_only_path'],
+ ['cache', 'deployment_only_path'],
+ ]);
+ expect(ignoredOf(resolution, 1)).toEqual([toIgnoredTombstone('cache', 'deployment_only_path')]);
+ });
+
it('keeps Azure groups as written and reports groups the Azure clients never read', () => {
const configs = PARITY_CASES.find(([name]) => name.startsWith('Azure groups'))![1]();
const resolution = resolveConfigLayers(appConfig, configs);
diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.ts
index e4cc5239ca..4d26f2793e 100644
--- a/packages/data-schemas/src/app/resolution.spec.ts
+++ b/packages/data-schemas/src/app/resolution.spec.ts
@@ -1,7 +1,9 @@
+import { z } from 'zod';
import {
PermissionTypes,
SearchProviders,
INTERFACE_PERMISSION_FIELDS,
+ DEPLOYMENT_ONLY_CONFIG_PATHS,
} from 'librechat-data-provider';
import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provider';
import type { AppConfig, IConfig } from '~/types';
@@ -21,6 +23,8 @@ import {
getConfigOverrideIssues,
combineFoldedConfigItems,
getIndexedMergeKeyIssues,
+ getConfigIssueParams,
+ getIgnoredConfigOverrides,
} from './resolution';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
import { toConfigOverrideState } from './mutations';
@@ -1269,6 +1273,7 @@ describe('mergeConfigOverrides: invalid stored overrides', () => {
path: 'endpoints.custom.1.baseURL',
segments: ['endpoints', 'custom', '1', 'baseURL'],
code: 'invalid_type',
+ params: { expected: 'string', received: 'number' },
},
]);
@@ -1376,7 +1381,7 @@ describe('mergeConfigOverrides: invalid stored overrides', () => {
});
it('keeps a lower layer that relies on a higher layer for a required field', () => {
- const merged = mergeConfigOverrides({} as AppConfig, [
+ const layers = [
fakeConfig(
{
cloudfront: {
@@ -1388,14 +1393,17 @@ describe('mergeConfigOverrides: invalid stored overrides', () => {
10,
),
fakeConfig({ cloudfront: { domain: 'https://cdn.example.com' } }, 20, undefined, 'other'),
- ]) as unknown as { cloudfront: Record<string, unknown> };
+ ];
- expect(merged.cloudfront).toEqual({
+ expect(resolveRawConfig({}, layers).cloudfront).toEqual({
imageSigning: 'cookies',
cookieDomain: '.example.com',
requireSignedAccess: true,
domain: 'https://cdn.example.com',
});
+ /** `cloudfront` is deployment-only: the served config keeps librechat.yaml's (none here). */
+ const merged = mergeConfigOverrides({} as AppConfig, layers) as { cloudfront?: unknown };
+ expect(merged.cloudfront).toBeUndefined();
});
it('lets a lower-priority valid override survive a higher-priority invalid one', () => {
@@ -2046,6 +2054,7 @@ describe('endpoints.custom: names the runtime folds together', () => {
path: 'endpoints.custom.0.models',
segments: ['endpoints', 'custom', '0', 'models'],
code: 'invalid_type',
+ params: { expected: 'object', received: 'number' },
},
]);
expect(
@@ -3423,6 +3432,7 @@ describe('getConfigChangeIssues', () => {
path: 'endpoints.bedrock.inferenceProfiles.eu.a.b',
segments: ['endpoints', 'bedrock', 'inferenceProfiles', 'eu.a.b'],
code: 'invalid_type',
+ params: { expected: 'string', received: 'number' },
},
]);
});
@@ -3515,3 +3525,327 @@ describe('isAcceptedOverrideSection', () => {
}
});
});
+
+describe('issue params', () => {
+ const firstIssue = (schema: z.ZodTypeAny, value: unknown) => {
+ const result = schema.safeParse(value);
+ if (result.success) {
+ throw new Error('expected a failure');
+ }
+ return result.error.issues[0];
+ };
+
+ it('carries the schema side of each failure, never the submitted value', () => {
+ const issues = getConfigOverrideIssues({
+ interface: { contextCost: 'no' },
+ fileStrategy: 'sentinel-fs',
+ githubCompare: { timeoutMs: 40_000 },
+ endpoints: { agents: { recursionLimit: 0 }, allowedAddresses: ['localhost'] },
+ });
+ const byPath = Object.fromEntries(issues.map(({ path, params }) => [path, params]));
+ expect(byPath['interface.contextCost']).toEqual({ expected: 'boolean', received: 'string' });
+ expect(byPath.fileStrategy).toEqual({
+ options: expect.arrayContaining(['local', 's3']),
+ });
+ expect(byPath['githubCompare.timeoutMs']).toEqual({
+ maximum: 30_000,
+ inclusive: true,
+ exact: false,
+ type: 'number',
+ });
+ expect(byPath['endpoints.agents.recursionLimit']).toEqual({
+ minimum: 1,
+ inclusive: true,
+ exact: false,
+ type: 'number',
+ });
+ expect(byPath['endpoints.allowedAddresses.0']).toEqual({ reason: 'missing_port' });
+ });
+
+ it('names the integer expectation of a fractional step limit', () => {
+ expect(getConfigOverrideIssues({ endpoints: { agents: { maxRecursionLimit: 2.5 } } })).toEqual([
+ {
+ path: 'endpoints.agents.maxRecursionLimit',
+ segments: ['endpoints', 'agents', 'maxRecursionLimit'],
+ code: 'invalid_type',
+ params: { expected: 'integer', received: 'float' },
+ },
+ ]);
+ });
+
+ it('keeps record keys with dots as one segment beside the params', () => {
+ const [issue] = getConfigOverrideIssues({
+ endpoints: { bedrock: { inferenceProfiles: { 'us.a.b': 5 } } },
+ });
+ expect(issue.segments).toEqual(['endpoints', 'bedrock', 'inferenceProfiles', 'us.a.b']);
+ expect(issue.params).toEqual({ expected: 'string', received: 'number' });
+ });
+
+ it('leaves params off an issue attributed above the node that failed', () => {
+ const issues = getConfigOverrideIssues({ modelSpecs: { list: [{ name: 'only-name' }] } });
+ expect(issues.length).toBeGreaterThan(0);
+ for (const issue of issues) {
+ expect(issue.segments).toEqual(['modelSpecs', 'list', '0']);
+ expect(issue.params).toBeUndefined();
+ }
+ });
+
+ it('maps each zod issue code through its allowlist', () => {
+ expect(getConfigIssueParams(firstIssue(z.literal('a'), 'sentinel'))).toEqual({
+ expected: 'a',
+ });
+ expect(getConfigIssueParams(firstIssue(z.string().url(), 'sentinel'))).toEqual({
+ validation: 'url',
+ });
+ expect(getConfigIssueParams(firstIssue(z.string().startsWith('x'), 'sentinel'))).toEqual({
+ validation: 'startsWith',
+ });
+ expect(getConfigIssueParams(firstIssue(z.number().multipleOf(5), 7))).toEqual({
+ multipleOf: 5,
+ });
+ expect(getConfigIssueParams(firstIssue(z.array(z.string()).min(2), ['a']))).toEqual({
+ minimum: 2,
+ inclusive: true,
+ exact: false,
+ type: 'array',
+ });
+ expect(
+ getConfigIssueParams(firstIssue(z.date().min(new Date(1000)), new Date(5))),
+ ).toMatchObject({ minimum: 1000, type: 'date' });
+ const union = z.discriminatedUnion('type', [
+ z.object({ type: z.literal('a') }),
+ z.object({ type: z.literal('b') }),
+ ]);
+ expect(getConfigIssueParams(firstIssue(union, { type: 'sentinel' }))).toEqual({
+ options: ['a', 'b'],
+ });
+ expect(
+ getConfigIssueParams(
+ firstIssue(
+ z.string().refine(() => false, { params: { reason: 'not_allowed' } }),
+ 'x',
+ ),
+ ),
+ ).toEqual({ reason: 'not_allowed' });
+ expect(
+ getConfigIssueParams(
+ firstIssue(
+ z.string().refine(() => false, { params: { reason: 'echoes sentinel value' } }),
+ 'x',
+ ),
+ ),
+ ).toBeUndefined();
+ expect(
+ getConfigIssueParams(
+ firstIssue(
+ z.string().refine(() => false),
+ 'x',
+ ),
+ ),
+ ).toBeUndefined();
+ });
+
+ it('drops a bigint bound, so the issue still serializes', () => {
+ const params = getConfigIssueParams(firstIssue(z.bigint().min(BigInt(5)), BigInt(1)));
+ expect(params).toEqual({ inclusive: true, exact: false, type: 'bigint' });
+ expect(() => JSON.stringify(params)).not.toThrow();
+ });
+
+ it('never returns a sentinel written into any failing field', () => {
+ const sentinel = 'sentinel_0f3a9c';
+ const issues = getConfigOverrideIssues({
+ interface: { contextCost: sentinel, customWelcome: 5 },
+ fileStrategy: sentinel,
+ endpoints: {
+ allowedAddresses: [sentinel, `http://${sentinel}`, `${sentinel}:0`],
+ agents: { recursionLimit: sentinel, titleMethod: sentinel },
+ custom: [{ name: sentinel, baseURL: 5, titleMethod: sentinel }],
+ },
+ memory: { agent: { id: 5, provider: sentinel } },
+ webSearch: { searchProvider: sentinel },
+ githubCompare: { enabled: sentinel, timeoutMs: sentinel },
+ [`${sentinel}.section`]: 1,
+ });
+ expect(issues.length).toBeGreaterThan(5);
+ expect(issues.some((issue) => issue.params)).toBe(true);
+ const leaked = issues.filter(({ code, params }) =>
+ JSON.stringify({ code, params }).includes(sentinel),
+ );
+ expect(leaked).toEqual([]);
+ });
+});
+
+describe('deployment-only paths in the merge', () => {
+ const yamlValue = (path: string) => `yaml:${path}`;
+
+ function at(target: Record<string, unknown>, path: string): unknown {
+ return path
+ .split('.')
+ .reduce<unknown>((node, key) => (node as Record<string, unknown> | undefined)?.[key], target);
+ }
+
+ function put(target: Record<string, unknown>, path: string, value: unknown) {
+ const keys = path.split('.');
+ let node = target;
+ for (const key of keys.slice(0, -1)) {
+ node[key] = (node[key] as Record<string, unknown> | undefined) ?? {};
+ node = node[key] as Record<string, unknown>;
+ }
+ node[keys[keys.length - 1]] = value;
+ }
+
+ it('keeps librechat.yaml’s value at every deployment-only path, whatever a layer stores', () => {
+ const base: Record<string, unknown> = { config: {} };
+ const overrides: Record<string, unknown> = {};
+ for (const path of Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS)) {
+ put(base, path, yamlValue(path));
+ put(overrides, path, `override:${path}`);
+ }
+ const merged = mergeConfigOverrides(base as unknown as AppConfig, [
+ fakeConfig(overrides, 0, undefined, BASE_CONFIG_PRINCIPAL_ID),
+ fakeConfig(overrides, 10, undefined, 'editor'),
+ ]) as unknown as Record<string, unknown>;
+ for (const path of Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS)) {
+ expect([path, at(merged, path)]).toEqual([path, yamlValue(path)]);
+ }
+ });
+
+ it('puts librechat.yaml’s value back below a tombstone of the parent, and hides the rest', () => {
+ const base = {
+ config: {},
+ endpoints: { agents: { eventDriven: { idlePolling: true }, recursionLimit: 20 } },
+ } as unknown as AppConfig;
+ const merged = mergeConfigOverrides(base, [fakeConfig({}, 10, ['endpoints.agents'])]) as {
+ endpoints?: { agents?: Record<string, unknown> };
+ };
+ expect(merged.endpoints?.agents).toEqual({ eventDriven: { idlePolling: true } });
+ });
+
+ it('keeps the tool filters librechat.yaml sets, so a profile cannot gate tools', () => {
+ const base = { config: {}, filteredTools: ['dalle'] } as unknown as AppConfig;
+ const merged = mergeConfigOverrides(base, [
+ fakeConfig({ filteredTools: ['ask_user_question'], includedTools: ['calculator'] }, 10),
+ ]);
+ expect(merged.filteredTools).toEqual(['dalle']);
+ expect(merged.includedTools).toBeUndefined();
+ });
+});
+
+describe('getIgnoredConfigOverrides', () => {
+ const yaml = {
+ endpoints: {
+ agents: { pullRequests: { provider: 'github' }, eventDriven: { deadLetterRetentionDays: 7 } },
+ },
+ mcpServers: {
+ local: { type: 'stdio', command: 'node', args: ['server.js'] },
+ remote: { type: 'streamable-http', url: 'https://mcp.example.com' },
+ },
+ memory: { agent: { id: 'agent_1' } },
+ } as unknown as Partial<TCustomConfig>;
+
+ const reasons = (entries: ReturnType<typeof getIgnoredConfigOverrides>) =>
+ entries.map(({ path, reason, kind }) => `${kind}:${path}:${reason}`).sort();
+
+ it('lists every stored part the merge leaves out, by location and reason', () => {
+ const layer = fakeConfig(
+ {
+ paths: { uploads: '/tmp' },
+ filters: { x: 1 },
+ langfuse: { publicKey: 'pk' },
+ interface: {
+ prompts: false,
+ mcpServers: { use: false, placeholder: 'p' },
+ modelSelect: true,
+ },
+ mcpServers: { local: { title: 'Local' }, remote: { title: 'Remote' } },
+ endpoints: {
+ agents: {
+ pullRequests: { provider: 'gitlab' },
+ eventDriven: { deadLetterRetentionDays: 30 },
+ },
+ },
+ rateLimits: { fileUploads: { ipMax: 1 } },
+ githubCompare: { timeoutMs: 40_000 },
+ },
+ 10,
+ ['config', 'filters', 'langfuse.publicKey', 'mcpServers.local', 'cloudfront'],
+ 'editor',
+ );
+ expect(reasons(getIgnoredConfigOverrides(yaml, layer))).toEqual(
+ [
+ 'override:paths:unknown_section',
+ 'tombstone:config:unknown_section',
+ 'override:filters:base_only_section',
+ 'tombstone:filters:base_only_section',
+ 'override:langfuse:dedicated_section',
+ 'tombstone:langfuse.publicKey:dedicated_section',
+ 'override:interface.prompts:interface_permission',
+ 'override:interface.mcpServers.use:interface_permission',
+ 'override:mcpServers.local:process_mcp_server',
+ 'tombstone:mcpServers.local:process_mcp_server',
+ 'override:endpoints.agents.pullRequests.provider:base_only_path',
+ 'override:endpoints.agents.eventDriven:deployment_only_path',
+ 'override:rateLimits:deployment_only_path',
+ 'tombstone:cloudfront:deployment_only_path',
+ 'override:githubCompare.timeoutMs:invalid',
+ ].sort(),
+ );
+ });
+
+ it('reports what librechat.yaml keeps below a tombstone, and each stdio server a section tombstone leaves', () => {
+ const layer = fakeConfig({}, 10, ['endpoints.agents', 'mcpServers'], 'editor');
+ expect(reasons(getIgnoredConfigOverrides(yaml, layer))).toEqual(
+ [
+ 'tombstone:endpoints.agents.pullRequests.provider:base_only_path',
+ 'tombstone:endpoints.agents.eventDriven:deployment_only_path',
+ 'tombstone:mcpServers.local:process_mcp_server',
+ ].sort(),
+ );
+ });
+
+ it('reports the defaults the merge puts back below a tombstone when given the resolved base', () => {
+ const resolved = {
+ config: yaml,
+ mcpSettings: { catalogRecovery: { maxStateEntries: 10_000, discoveryTimeoutMs: 3_000 } },
+ } as unknown as AppConfig;
+ const layer = fakeConfig({}, 10, ['mcpSettings'], 'editor');
+ expect(reasons(getIgnoredConfigOverrides(yaml, layer))).toEqual([]);
+ expect(reasons(getIgnoredConfigOverrides(yaml, layer, [], resolved))).toEqual([
+ 'tombstone:mcpSettings.catalogRecovery.maxStateEntries:deployment_only_path',
+ ]);
+ });
+
+ it('keeps dedicated sections for Base and reports nothing for a document the merge applies whole', () => {
+ const base = fakeConfig(
+ { langfuse: { publicKey: 'pk' }, interface: { modelSelect: false } },
+ 0,
+ undefined,
+ BASE_CONFIG_PRINCIPAL_ID,
+ );
+ expect(getIgnoredConfigOverrides(yaml, base)).toEqual([]);
+ });
+
+ it('judges values on the layers below, as the merge does', () => {
+ const memorySwitch = fakeConfig(
+ { memory: { agent: { provider: 'openAI', model: 'gpt-4o' } } },
+ 0,
+ ['memory.agent.id'],
+ BASE_CONFIG_PRINCIPAL_ID,
+ );
+ const layer = fakeConfig({ memory: { agent: { model: 'gpt-4.1' } } }, 10, undefined, 'editor');
+ expect(reasons(getIgnoredConfigOverrides(yaml, layer))).toEqual([
+ 'override:memory.agent.model:invalid',
+ ]);
+ expect(getIgnoredConfigOverrides(yaml, layer, [memorySwitch])).toEqual([]);
+ });
+
+ it('does not log the merge warnings it reports', () => {
+ const warn = jest.spyOn(logger, 'warn');
+ getIgnoredConfigOverrides(
+ yaml,
+ fakeConfig({ paths: {}, githubCompare: { timeoutMs: 40_000 } }, 10, ['config'], 'editor'),
+ );
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
+ });
+});
diff --git a/packages/data-schemas/src/app/resolution.ts b/packages/data-schemas/src/app/resolution.ts
index 6c2cc8bd3b..72e6d5c6f9 100644
--- a/packages/data-schemas/src/app/resolution.ts
+++ b/packages/data-schemas/src/app/resolution.ts
@@ -2,6 +2,7 @@ import {
BASE_PRINCIPAL_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_PATHS,
+ DEPLOYMENT_ONLY_CONFIG_PATHS,
INTERFACE_PERMISSION_FIELDS,
RUNTIME_CONFIG_INTERFACE_FIELDS,
PERMISSION_SUB_KEYS,
@@ -13,8 +14,11 @@ import {
import type { TCustomConfig } from 'librechat-data-provider';
import type {
AdminConfigLayerIgnoreReason,
+ AdminConfigIgnoredOverride,
+ AdminConfigIgnoreReason,
AdminConfigLayerIgnored,
AdminConfigMergeRules,
+ ConfigIssueParams,
TWebSearchKeys,
AppConfig,
Config,
@@ -28,9 +32,9 @@ import {
resolveAzureGroups,
} from './azure';
import { isBaseConfigPrincipal, sortByConfigPrecedence } from './precedence';
+import { parseFieldPath, isDotFreePath, isSegmentPrefix } from './paths';
import { setConfigFields, toConfigOverrideState } from './mutations';
import { webSearchPairedFields, unbindWebSearchKeys } from './web';
-import { parseFieldPath, isDotFreePath } from './paths';
import logger from '~/config/winston';
type AnyObject = { [key: string]: unknown };
@@ -53,6 +57,40 @@ const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
const BASE_ONLY_OVERRIDE_SECTIONS = new Set<string>(['filters', ...BASE_ONLY_CONFIG_SECTIONS]);
const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set<string>(BASE_PRINCIPAL_CONFIG_SECTIONS);
+/** A field only librechat.yaml sets, as YAML key segments, and why the merge keeps its value. */
+export interface YamlHeldPath {
+ segments: readonly string[];
+ reason: Extract<AdminConfigIgnoreReason, 'base_only_path' | 'deployment_only_path'>;
+}
+
+/**
+ * Every field the merge sets back to librechat.yaml's value whatever a layer stores or
+ * tombstones there: `BASE_ONLY_CONFIG_PATHS`, which per-request code reads from the merged
+ * config, and `DEPLOYMENT_ONLY_CONFIG_PATHS`, read at startup or from librechat.yaml itself.
+ */
+export const YAML_HELD_PATHS: readonly YamlHeldPath[] = [
+ ...BASE_ONLY_CONFIG_PATHS.map(
+ (path): YamlHeldPath => ({ segments: path.split('.'), reason: 'base_only_path' }),
+ ),
+ ...Object.keys(DEPLOYMENT_ONLY_CONFIG_PATHS).map(
+ (path): YamlHeldPath => ({ segments: path.split('.'), reason: 'deployment_only_path' }),
+ ),
+];
+
+/** Told about each stored override or tombstone of `layer` that a fold leaves out. */
+type IgnoredSink = (layer: ConfigOverrideLayer, entry: AdminConfigIgnoredOverride) => void;
+
+/** {@link IgnoredSink} bound to the layer being folded. */
+type LayerIgnoredSink = (entry: AdminConfigIgnoredOverride) => void;
+
+function toIgnored(
+ segments: readonly string[],
+ reason: AdminConfigIgnoreReason,
+ kind: AdminConfigIgnoredOverride['kind'],
+): AdminConfigIgnoredOverride {
+ return { path: segments.join('.'), segments: [...segments], reason, kind };
+}
+
/** Where the resolved Azure config sits in an AppConfig. */
const AZURE_CONFIG_PATH = `endpoints.${EModelEndpoint.azureOpenAI}`;
@@ -344,7 +382,7 @@ export function combineFoldedConfigItems(arrayPath: string, items: unknown[]): u
}
/** `combineFoldedConfigItems` over every folded array of a stored overrides document. */
-function combineStoredFoldedItems(overrides: unknown, principal: string): unknown {
+function combineStoredFoldedItems(overrides: unknown, principal: string, quiet = false): unknown {
let result = overrides;
for (const arrayPath of Object.keys(MERGE_KEY_FOLDS)) {
const segments = arrayPath.split('.');
@@ -356,9 +394,11 @@ function combineStoredFoldedItems(overrides: unknown, principal: string): unknow
if (combined === items) {
continue;
}
- logger.warn(
- `[mergeConfigOverrides] Combining "${arrayPath}" items that name one entry in different spellings for ${principal}; a write of this list must name each entry once`,
- );
+ if (!quiet) {
+ logger.warn(
+ `[mergeConfigOverrides] Combining "${arrayPath}" items that name one entry in different spellings for ${principal}; a write of this list must name each entry once`,
+ );
+ }
result = setPath(result, segments, combined);
}
return result;
@@ -496,6 +536,12 @@ export type ConfigOverrideIssue = {
* because they can echo the submitted values.
*/
code: string;
+ /**
+ * What the schema expected, for a zod issue attributed to the exact node that failed
+ * (`getConfigIssueParams`); absent when the issue is reported on an ancestor the override
+ * supplies, where the bound would describe a node the override did not write.
+ */
+ params?: ConfigIssueParams;
};
type IssuePath = Array<string | number>;
@@ -518,8 +564,100 @@ export function isAcceptedOverrideSection(key: string): boolean {
return hasOwn(configSchema.shape, key);
}
-function toIssue(segments: string[], code: string): ConfigOverrideIssue {
- return { path: segments.join('.'), segments, code };
+function toIssue(
+ segments: string[],
+ code: string,
+ params?: ConfigIssueParams,
+): ConfigOverrideIssue {
+ return params
+ ? { path: segments.join('.'), segments, code, params }
+ : { path: segments.join('.'), segments, code };
+}
+
+type IssuePrimitive = string | number | boolean | null;
+
+const CUSTOM_REASON = /^[a-z][a-z0-9_]*$/;
+
+function isIssuePrimitive(value: unknown): value is IssuePrimitive {
+ return (
+ value === null ||
+ typeof value === 'string' ||
+ typeof value === 'boolean' ||
+ (typeof value === 'number' && Number.isFinite(value))
+ );
+}
+
+/** A numeric bound as JSON can carry it: a date as epoch milliseconds, never a bigint. */
+function toIssueNumber(value: unknown): number | undefined {
+ if (value instanceof Date) {
+ const time = value.getTime();
+ return Number.isFinite(time) ? time : undefined;
+ }
+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+/** The bound fields of a `too_small` or `too_big` issue, always with `inclusive`, `exact`, `type`. */
+function getBoundParams(
+ bound: 'minimum' | 'maximum',
+ value: unknown,
+ issue: { inclusive: boolean; exact?: boolean; type: string },
+): ConfigIssueParams {
+ const number = toIssueNumber(value);
+ return {
+ ...(number !== undefined && { [bound]: number }),
+ inclusive: issue.inclusive,
+ exact: issue.exact ?? false,
+ type: issue.type,
+ };
+}
+
+/**
+ * The parts of a zod issue that describe the schema rather than the submitted value, by an
+ * allowlist per issue code: expected types and literals, accepted options, numeric bounds, the
+ * failed string check, a multiple, and a refinement's stable `reason`. A value the client sent
+ * is never copied (no `received` literal or enum value, no message), so the result is safe to
+ * return. `undefined` when the issue carries none of these.
+ */
+export function getConfigIssueParams(issue: SchemaIssue): ConfigIssueParams | undefined {
+ let params: ConfigIssueParams | undefined;
+ switch (issue.code) {
+ case 'invalid_type':
+ params = { expected: String(issue.expected), received: String(issue.received) };
+ break;
+ case 'invalid_literal':
+ params = isIssuePrimitive(issue.expected) ? { expected: issue.expected } : undefined;
+ break;
+ case 'invalid_enum_value':
+ case 'invalid_union_discriminator':
+ params = { options: (issue.options as unknown[]).filter(isIssuePrimitive) };
+ break;
+ case 'too_small':
+ params = getBoundParams('minimum', issue.minimum, issue);
+ break;
+ case 'too_big':
+ params = getBoundParams('maximum', issue.maximum, issue);
+ break;
+ case 'invalid_string': {
+ const { validation } = issue;
+ params = {
+ validation: typeof validation === 'string' ? validation : Object.keys(validation)[0],
+ };
+ break;
+ }
+ case 'not_multiple_of': {
+ const multipleOf = toIssueNumber(issue.multipleOf);
+ params = multipleOf !== undefined ? { multipleOf } : undefined;
+ break;
+ }
+ case 'custom': {
+ const reason: unknown = issue.params?.reason;
+ params = typeof reason === 'string' && CUSTOM_REASON.test(reason) ? { reason } : undefined;
+ break;
+ }
+ default:
+ params = undefined;
+ }
+ return params && Object.keys(params).length > 0 ? params : undefined;
}
/**
@@ -977,7 +1115,11 @@ export function getConfigOverrideIssues(
const result = shape[section as keyof typeof shape].safeParse(merged[section]);
const shapeIssues = findShapeIssues(schema, merged[section], []);
const schemaIssues = result.success ? [] : expandUnionIssues(result.error.issues);
- for (const issue of [...shapeIssues, ...schemaIssues]) {
+ const located: Array<{ issue: ShapeIssue | SchemaIssue; params: boolean }> = [
+ ...shapeIssues.map((issue) => ({ issue, params: false })),
+ ...schemaIssues.map((issue) => ({ issue, params: true })),
+ ];
+ for (const { issue, params } of located) {
if (issue.code === 'unrecognized_keys') {
continue;
}
@@ -994,7 +1136,14 @@ export function getConfigOverrideIssues(
continue;
}
seen.add(path);
- issues.push(toIssue(segments, issue.code));
+ const exact = params && segments.length === issuePath.length;
+ issues.push(
+ toIssue(
+ segments,
+ issue.code,
+ exact ? getConfigIssueParams(issue as SchemaIssue) : undefined,
+ ),
+ );
}
}
return issues;
@@ -1215,10 +1364,11 @@ function omitPath(target: unknown, segments: string[]): unknown {
function stripInvalidOverrides(
config: ConfigOverrideLayer,
base: Partial<TCustomConfig>,
+ sink?: LayerIgnoredSink,
onStripped?: (issue: ConfigOverrideIssue) => void,
): AnyObject {
const principal = `${config.principalType}/${config.principalId}`;
- let stripped: unknown = combineStoredFoldedItems(config.overrides, principal);
+ let stripped: unknown = combineStoredFoldedItems(config.overrides, principal, sink != null);
/**
* Removing a field can make a related field it supplies fail, so check again while
* removals make progress. If they stop, only the sections that still fail are dropped.
@@ -1229,16 +1379,26 @@ function stripInvalidOverrides(
return stripped as AnyObject;
}
if (issues.some((issue) => issue.segments.length === 0)) {
- logger.warn(`[mergeConfigOverrides] Ignoring malformed overrides document for ${principal}`);
+ if (sink) {
+ sink(toIgnored([], 'invalid', 'override'));
+ } else {
+ logger.warn(
+ `[mergeConfigOverrides] Ignoring malformed overrides document for ${principal}`,
+ );
+ }
onStripped?.(toIssue([], issues.find((issue) => issue.segments.length === 0)?.code ?? ''));
return {};
}
const before = stripped;
for (let index = issues.length - 1; index >= 0; index--) {
const { path, segments, code } = issues[index];
- logger.warn(
- `[mergeConfigOverrides] Ignoring invalid override "${path}" for ${principal} (${code})`,
- );
+ if (sink) {
+ sink(toIgnored(segments, 'invalid', 'override'));
+ } else {
+ logger.warn(
+ `[mergeConfigOverrides] Ignoring invalid override "${path}" for ${principal} (${code})`,
+ );
+ }
stripped = omitPath(stripped, segments);
onStripped?.(issues[index]);
}
@@ -1252,9 +1412,13 @@ function stripInvalidOverrides(
failing.set(issue.segments[0], issue.code);
}
}
- logger.warn(
- `[mergeConfigOverrides] Ignoring still-invalid sections ${[...failing.keys()].join(', ')} for ${principal}`,
- );
+ if (sink) {
+ failing.forEach((_code, section) => sink(toIgnored([section], 'invalid', 'override')));
+ } else {
+ logger.warn(
+ `[mergeConfigOverrides] Ignoring still-invalid sections ${[...failing.keys()].join(', ')} for ${principal}`,
+ );
+ }
for (const [section, code] of failing) {
onStripped?.(toIssue([section], code));
}
@@ -1263,7 +1427,15 @@ function stripInvalidOverrides(
);
}
-function filterMCPServerOverrides(value: unknown, current: unknown): AnyObject {
+/**
+ * A layer's `mcpServers` without the servers `current` (the merged MCP config below it) runs as
+ * a local process, or that the override would turn into one; `onDropped` is told each name.
+ */
+function filterMCPServerOverrides(
+ value: unknown,
+ current: unknown,
+ onDropped?: (serverName: string) => void,
+): AnyObject {
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return {};
}
@@ -1283,6 +1455,8 @@ function filterMCPServerOverrides(value: unknown, current: unknown): AnyObject {
) {
if (!isProcessMCPServerConfig(currentServer)) {
filtered[serverName] = serverOverride;
+ } else {
+ onDropped?.(serverName);
}
continue;
}
@@ -1294,6 +1468,8 @@ function filterMCPServerOverrides(value: unknown, current: unknown): AnyObject {
const resolved = deepMerge(baseServer, serverOverride as AnyObject);
if (!isProcessMCPServerConfig(resolved)) {
filtered[serverName] = serverOverride;
+ } else {
+ onDropped?.(serverName);
}
}
@@ -1457,7 +1633,10 @@ function describePrincipal(config: ConfigOverrideLayer): string {
* checked (or by another writer) and would reach runtime state no override may set, so it is
* dropped here, which neutralizes it without a migration. One warning per document.
*/
-function withAcceptedSections(config: ConfigOverrideLayer): ConfigOverrideLayer {
+function withAcceptedSections(
+ config: ConfigOverrideLayer,
+ sink?: LayerIgnoredSink,
+): ConfigOverrideLayer {
const ignored = new Set<string>();
let overrides = config.overrides;
if (isPlainObject(overrides)) {
@@ -1467,6 +1646,7 @@ function withAcceptedSections(config: ConfigOverrideLayer): ConfigOverrideLayer
accepted[key] = value;
} else {
ignored.add(key);
+ sink?.(toIgnored([key], 'unknown_section', 'override'));
}
}
overrides = accepted as Partial<TCustomConfig>;
@@ -1482,12 +1662,16 @@ function withAcceptedSections(config: ConfigOverrideLayer): ConfigOverrideLayer
return true;
}
ignored.add(section);
+ sink?.(toIgnored(path.split('.'), 'unknown_section', 'tombstone'));
return false;
});
}
if (ignored.size === 0) {
return config;
}
+ if (sink) {
+ return { ...config, overrides, tombstones };
+ }
logger.warn(
`[mergeConfigOverrides] Ignoring unknown config sections ${[...ignored].join(', ')} for ${describePrincipal(config)}`,
);
@@ -1506,6 +1690,7 @@ function withAcceptedSections(config: ConfigOverrideLayer): ConfigOverrideLayer
function resolveLayerAzureGroups(
endpoints: unknown,
config: ConfigOverrideLayer,
+ sink?: LayerIgnoredSink,
): AnyObject | null {
if (!isPlainObject(endpoints)) {
return null;
@@ -1516,9 +1701,13 @@ function resolveLayerAzureGroups(
}
const resolved = resolveAzureGroups(azure.groups);
if (!resolved.isValid) {
- logger.warn(
- `[mergeConfigOverrides] Ignoring ${AZURE_CONFIG_PATH}.groups for ${describePrincipal(config)}: ${resolved.errors.join('; ')}`,
- );
+ if (sink) {
+ sink(toIgnored(AZURE_GROUPS_PATH.split('.'), 'invalid', 'override'));
+ } else {
+ logger.warn(
+ `[mergeConfigOverrides] Ignoring ${AZURE_CONFIG_PATH}.groups for ${describePrincipal(config)}: ${resolved.errors.join('; ')}`,
+ );
+ }
return null;
}
const next: AnyObject = { ...azure };
@@ -1602,7 +1791,7 @@ interface FoldTracker {
layers: LayerTrack[];
}
-function toIgnored(
+function toLayerIgnored(
segments: readonly string[],
reason: AdminConfigLayerIgnoreReason,
extra?: Pick<AdminConfigLayerIgnored, 'code' | 'tombstone'>,
@@ -1643,13 +1832,13 @@ function startLayerTrack(
if (isPlainObject(layer.overrides)) {
for (const key of Object.keys(layer.overrides)) {
if (!isAcceptedOverrideSection(key)) {
- ignored.push(toIgnored([key], 'unknown_section'));
+ ignored.push(toLayerIgnored([key], 'unknown_section'));
}
}
}
for (const path of Array.isArray(layer.tombstones) ? layer.tombstones : []) {
if (typeof path === 'string' && !isAcceptedOverrideSection(path.split('.')[0])) {
- ignored.push(toIgnored(path.split('.'), 'unknown_section', { tombstone: true }));
+ ignored.push(toLayerIgnored(path.split('.'), 'unknown_section', { tombstone: true }));
}
}
}
@@ -1678,6 +1867,52 @@ function getInterfacePermissionRemovals(value: AnyObject): string[][] {
return removed;
}
+/**
+ * Reports what a tombstone leaves in place: a field only librechat.yaml sets, at or below the
+ * tombstone (the whole tombstone) or below it where the base config has a value the merge puts
+ * back (`isHeldValueSet`), and the MCP servers librechat.yaml runs as local processes (`merged`
+ * is the config below the layer).
+ */
+function reportTombstoneHeld(
+ path: string,
+ merged: AnyObject,
+ isHeldValueSet: (held: YamlHeldPath) => boolean,
+ sink: LayerIgnoredSink,
+): void {
+ const segments = path.split('.');
+ for (const held of YAML_HELD_PATHS) {
+ if (isSegmentPrefix(held.segments, segments)) {
+ sink(toIgnored(segments, held.reason, 'tombstone'));
+ } else if (isSegmentPrefix(segments, held.segments) && isHeldValueSet(held)) {
+ sink(toIgnored(held.segments, held.reason, 'tombstone'));
+ }
+ }
+ const servers = merged.mcpConfig;
+ if (segments[0] !== 'mcpServers' || !isPlainObject(servers)) {
+ return;
+ }
+ const names = segments.length > 1 ? [segments[1]] : Object.keys(servers);
+ for (const name of names) {
+ if (isProcessMCPServerConfig(servers[name])) {
+ const location = segments.length > 1 ? segments : ['mcpServers', name];
+ sink(toIgnored(location, 'process_mcp_server', 'tombstone'));
+ }
+ }
+}
+
+/** What a fold reports beside its result (`foldConfigLayers`). */
+interface FoldObservers {
+ /** Told about each stored override or tombstone a layer's fold leaves out. */
+ sink?: IgnoredSink;
+ /**
+ * For the `sink`: whether the merge puts back a held field below a tombstone; by default,
+ * whether the initial raw config (librechat.yaml) sets it.
+ */
+ isHeldValueSet?: (held: YamlHeldPath) => boolean;
+ /** Keeps the YAML-shaped result and each layer's unapplied parts. */
+ tracker?: FoldTracker;
+}
+
/**
* Folds override layers, in merge precedence order (`compareConfigPrecedence`), into
* `merged`, the served config, and `raw`, the YAML-shaped config each layer is validated on
@@ -1686,23 +1921,30 @@ function getInterfacePermissionRemovals(value: AnyObject): string[][] {
* `groups` resolve into the fields the Azure clients read (`resolveLayerAzureGroups`).
* `webSearchWriters` names the layer behind each paired web search field, by its position in
* that order. `afterLayer` runs after each layer lands, and the next layer folds onto what it
- * returns. With a `tracker`, the fold also keeps the YAML-shaped result the served config
- * corresponds to, and what of each layer it did not apply (`resolveConfigLayers`).
+ * returns. With a `sink`, the fold tells it what of each stored layer it leaves out
+ * (`getIgnoredConfigOverrides`); with a `tracker`, it also keeps the YAML-shaped result the served
+ * config corresponds to, and what of each layer it did not apply (`resolveConfigLayers`).
*/
function foldConfigLayers<T extends AnyObject>(
initial: T,
initialRaw: Partial<TCustomConfig>,
configs: readonly ConfigOverrideLayer[],
afterLayer?: (step: FoldStep<T>) => T,
- tracker?: FoldTracker,
+ {
+ sink,
+ tracker,
+ isHeldValueSet = (held) => getPath(initialRaw, [...held.segments]) !== undefined,
+ }: FoldObservers = {},
): { merged: T; raw: Partial<TCustomConfig>; webSearchWriters: WebSearchWriters } {
const sorted = sortByConfigPrecedence(configs);
let merged = initial;
let raw = initialRaw;
const webSearchWriters: WebSearchWriters = new Map();
for (let order = 0; order < sorted.length; order++) {
- const config = withAcceptedSections(sorted[order]);
- const track = tracker && startLayerTrack(tracker, sorted[order], config);
+ const source = sorted[order];
+ const layerSink: LayerIgnoredSink | undefined = sink && ((entry) => sink(source, entry));
+ const config = withAcceptedSections(source, layerSink);
+ const track = tracker && startLayerTrack(tracker, source, config);
const below = merged;
let contributed: AnyObject = {};
const removed: string[] = [];
@@ -1713,33 +1955,37 @@ function foldConfigLayers<T extends AnyObject>(
if (typeof path !== 'string') {
continue;
}
- if (
- !isBaseOnlyOverridePath(path) &&
- (isBasePrincipal || !BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(path.split('.')[0]))
- ) {
- for (const removedPath of getTombstoneRemovals(path)) {
- const mappedPath = remapOverridePath(removedPath);
- removed.push(mappedPath);
- merged = deleteConfigPath(merged, mappedPath);
- raw = deletePath(raw as AnyObject, removedPath) as Partial<TCustomConfig>;
- if (tracker) {
- tracker.resolved = deleteConfigPath(tracker.resolved, mappedPath);
- }
- }
- if (path === AZURE_GROUPS_PATH) {
- merged = withoutAzureGroups(merged);
- }
- track?.tombstoned.push(path);
- recordWebSearchTombstone(webSearchWriters, path, removal);
- } else if (track) {
- track.ignored.push(
- toIgnored(
- path.split('.'),
- isBaseOnlyOverridePath(path) ? 'base_only_section' : 'base_principal_section',
- { tombstone: true },
- ),
+ if (isBaseOnlyOverridePath(path)) {
+ layerSink?.(toIgnored(path.split('.'), 'base_only_section', 'tombstone'));
+ track?.ignored.push(
+ toLayerIgnored(path.split('.'), 'base_only_section', { tombstone: true }),
);
+ continue;
}
+ if (!isBasePrincipal && BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(path.split('.')[0])) {
+ layerSink?.(toIgnored(path.split('.'), 'dedicated_section', 'tombstone'));
+ track?.ignored.push(
+ toLayerIgnored(path.split('.'), 'base_principal_section', { tombstone: true }),
+ );
+ continue;
+ }
+ if (layerSink) {
+ reportTombstoneHeld(path, merged, isHeldValueSet, layerSink);
+ }
+ for (const removedPath of getTombstoneRemovals(path)) {
+ const mappedPath = remapOverridePath(removedPath);
+ removed.push(mappedPath);
+ merged = deleteConfigPath(merged, mappedPath);
+ raw = deletePath(raw as AnyObject, removedPath) as Partial<TCustomConfig>;
+ if (tracker) {
+ tracker.resolved = deleteConfigPath(tracker.resolved, mappedPath);
+ }
+ }
+ if (path === AZURE_GROUPS_PATH) {
+ merged = withoutAzureGroups(merged);
+ }
+ track?.tombstoned.push(path);
+ recordWebSearchTombstone(webSearchWriters, path, removal);
}
}
@@ -1751,35 +1997,39 @@ function foldConfigLayers<T extends AnyObject>(
const valid = stripInvalidOverrides(
config,
raw,
+ layerSink,
track &&
((issue) =>
track.ignored.push(
- toIgnored(issue.segments, 'invalid_override', { code: issue.code }),
+ toLayerIgnored(issue.segments, 'invalid_override', { code: issue.code }),
)),
);
for (const [key, value] of Object.entries(valid)) {
- if (
- BASE_ONLY_OVERRIDE_SECTIONS.has(key) ||
- (!isBasePrincipal && BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(key))
- ) {
- track?.ignored.push(
- toIgnored(
- [key],
- BASE_ONLY_OVERRIDE_SECTIONS.has(key) ? 'base_only_section' : 'base_principal_section',
- ),
- );
+ if (BASE_ONLY_OVERRIDE_SECTIONS.has(key)) {
+ layerSink?.(toIgnored([key], 'base_only_section', 'override'));
+ track?.ignored.push(toLayerIgnored([key], 'base_only_section'));
+ continue;
+ }
+ if (!isBasePrincipal && BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(key)) {
+ layerSink?.(toIgnored([key], 'dedicated_section', 'override'));
+ track?.ignored.push(toLayerIgnored([key], 'base_principal_section'));
continue;
}
applied[key] = value;
const mappedKey = OVERRIDE_KEY_MAP[key as keyof typeof OVERRIDE_KEY_MAP] ?? key;
if (mappedKey === 'mcpConfig') {
- remapped[mappedKey] = filterMCPServerOverrides(value, merged[mappedKey]);
+ remapped[mappedKey] = filterMCPServerOverrides(
+ value,
+ merged[mappedKey],
+ layerSink &&
+ ((name) => layerSink(toIgnored([key, name], 'process_mcp_server', 'override'))),
+ );
/** A server the filter removed must not complete a later layer's partial of it. */
applied[key] = remapped[mappedKey];
if (track && isPlainObject(value)) {
for (const name of Object.keys(value)) {
if (!hasOwn(remapped[mappedKey] as AnyObject, name)) {
- track.ignored.push(toIgnored([key, name], 'process_mcp_server'));
+ track.ignored.push(toLayerIgnored([key, name], 'process_mcp_server'));
}
}
}
@@ -1804,6 +2054,8 @@ function foldConfigLayers<T extends AnyObject>(
for (const [sub, subVal] of Object.entries(fieldVal as AnyObject)) {
if (!PERMISSION_SUB_KEYS.has(sub)) {
uiOnly[sub] = subVal;
+ } else {
+ layerSink?.(toIgnored([key, field, sub], 'interface_permission', 'override'));
}
}
if (Object.keys(uiOnly).length > 0) {
@@ -1813,22 +2065,26 @@ function foldConfigLayers<T extends AnyObject>(
// Dual-purpose field: the boolean form is a runtime disable, not a
// permission toggle, so preserve it (e.g. schedules: false).
filtered[field] = fieldVal;
+ } else {
+ // other boolean permission fields (e.g. runCode: false) are fully stripped
+ layerSink?.(toIgnored([key, field], 'interface_permission', 'override'));
}
- // other boolean permission fields (e.g. runCode: false) are fully stripped
}
if (Object.keys(filtered).length > 0) {
remapped[mappedKey] = filtered;
}
for (const segments of track ? getInterfacePermissionRemovals(value as AnyObject) : []) {
- track?.ignored.push(toIgnored(segments, 'interface_permission'));
+ track?.ignored.push(toLayerIgnored(segments, 'interface_permission'));
}
} else if (key === 'endpoints') {
- const resolved = resolveLayerAzureGroups(value, config);
+ const resolved = resolveLayerAzureGroups(value, config, layerSink);
remapped[mappedKey] = resolved ?? value;
replacesAzureGroups = resolved != null;
writtenEndpoints = value;
if (track && resolved == null && hasAzureGroups(value)) {
- track.ignored.push(toIgnored(AZURE_GROUPS_PATH.split('.'), 'azure_groups_unresolved'));
+ track.ignored.push(
+ toLayerIgnored(AZURE_GROUPS_PATH.split('.'), 'azure_groups_unresolved'),
+ );
}
} else {
remapped[mappedKey] = value;
@@ -1843,6 +2099,13 @@ function foldConfigLayers<T extends AnyObject>(
}
}
}
+ if (layerSink) {
+ for (const held of YAML_HELD_PATHS) {
+ if (getPath(applied, [...held.segments]) !== undefined) {
+ layerSink(toIgnored(held.segments, held.reason, 'override'));
+ }
+ }
+ }
merged = deepMerge(merged, remapped);
raw = deepMerge(raw as AnyObject, applied) as Partial<TCustomConfig>;
recordWebSearchWrites(webSearchWriters, applied.webSearch, {
@@ -1938,7 +2201,7 @@ function replayAzureServed(tracker: FoldTracker, before: AppConfig, after: AppCo
? getWriters(tracker, segments)
: getWriters(tracker, [...segments, field]);
for (const track of writers) {
- track.ignored.push(toIgnored([...segments, field], 'azure_unserved'));
+ track.ignored.push(toLayerIgnored([...segments, field], 'azure_unserved'));
}
}
}
@@ -1967,35 +2230,37 @@ function replayRuntimeStops(tracker: FoldTracker, baseConfig: AppConfig): void {
);
const segments = ['interface', key];
for (const track of getWriters(tracker, ['interfaceConfig', key])) {
- track.ignored.push(toIgnored(segments, 'runtime_stop'));
+ track.ignored.push(toLayerIgnored(segments, 'runtime_stop'));
}
for (const track of getTombstoners(tracker, segments.join('.'), true)) {
- track.ignored.push(toIgnored(segments, 'runtime_stop', { tombstone: true }));
+ track.ignored.push(toLayerIgnored(segments, 'runtime_stop', { tombstone: true }));
}
}
}
/**
* Replays on the YAML-shaped result what {@link preserveBaseOnlyPaths} did to the served config:
- * each base-only field keeps the value `librechat.yaml` gives it. A layer is told when it wrote
- * one, tombstoned one or anything below it, or tombstoned anything above one `librechat.yaml`
- * sets, as write responses tell it (`base_only_path`).
+ * each field only librechat.yaml sets (`YAML_HELD_PATHS`: base-only and deployment-only) keeps
+ * the value `librechat.yaml` gives it. A layer is told when it wrote one, tombstoned one or
+ * anything below it, or tombstoned anything above one `librechat.yaml` sets, as write responses
+ * tell it (`base_only_path`, `deployment_only_path`).
*/
function replayBaseOnlyPaths(tracker: FoldTracker, baseYaml: Partial<TCustomConfig>): void {
- for (const path of BASE_ONLY_CONFIG_PATHS) {
- const segments = path.split('.');
- const value = getPath(baseYaml, segments);
- const writers = getWriters(tracker, segments);
+ for (const { segments, reason } of YAML_HELD_PATHS) {
+ const path = segments.join('.');
+ const appSegments = remapOverridePath(path).split('.');
+ const value = getPath(baseYaml, [...segments]);
+ const writers = getWriters(tracker, appSegments);
const tombstoners = getTombstoners(tracker, path, value !== undefined);
if (writers.length === 0 && tombstoners.length === 0) {
continue;
}
- setResolved(tracker, segments, value);
+ setResolved(tracker, appSegments, value);
for (const track of writers) {
- track.ignored.push(toIgnored(segments, 'base_only_path'));
+ track.ignored.push(toLayerIgnored(segments, reason));
}
for (const track of tombstoners) {
- track.ignored.push(toIgnored(segments, 'base_only_path', { tombstone: true }));
+ track.ignored.push(toLayerIgnored(segments, reason, { tombstone: true }));
}
}
}
@@ -2038,7 +2303,7 @@ function mergeLayers(
},
});
}),
- tracker,
+ { tracker },
);
const served = withServedAzureModels(folded.merged, configs);
if (tracker) {
@@ -2058,7 +2323,7 @@ function mergeLayers(
setResolved(tracker, ['webSearch', apiKey], bound.webSearch?.[apiKey]);
tracker.layers
.find((track) => track.accepted === layer)
- ?.ignored.push(toIgnored(['webSearch', apiKey], 'secret_rebinding'));
+ ?.ignored.push(toLayerIgnored(['webSearch', apiKey], 'secret_rebinding'));
}
replayRuntimeStops(tracker, baseConfig);
replayBaseOnlyPaths(tracker, baseConfig.config ?? {});
@@ -2138,6 +2403,45 @@ export function resolveRawConfig(
return foldConfigLayers({ mcpConfig: baseYaml.mcpServers ?? null }, baseYaml, configs).raw;
}
+/**
+ * What the merge leaves out of `layer`'s stored overrides and tombstones, each at its own
+ * location: the parts no merge applies (unknown, base-only and dedicated sections, interface
+ * permissions, MCP servers librechat.yaml runs as processes), the values it sets back to
+ * librechat.yaml's (base-only and deployment-only fields), and the values that fail validation
+ * where it applies them. Judged exactly as the merge folds the layer over `baseYaml`
+ * (librechat.yaml) and the layers in `below` (those that merge first, such as the active Base),
+ * through the same steps. A field below a tombstone counts as put back when librechat.yaml sets
+ * it or `resolved`, the AppConfig librechat.yaml resolves to, holds it (defaults included). Each location is listed once per reason and kind; nothing about a value
+ * is returned.
+ */
+export function getIgnoredConfigOverrides(
+ baseYaml: Partial<TCustomConfig>,
+ layer: ConfigOverrideLayer,
+ below: readonly ConfigOverrideLayer[] = [],
+ resolved?: AppConfig,
+): AdminConfigIgnoredOverride[] {
+ const found = new Map<string, AdminConfigIgnoredOverride>();
+ foldConfigLayers(
+ { mcpConfig: baseYaml.mcpServers ?? null },
+ baseYaml,
+ [...below, layer],
+ undefined,
+ {
+ sink: (source, entry) => {
+ const key = JSON.stringify([entry.kind, entry.reason, entry.segments]);
+ if (source === layer && !found.has(key)) {
+ found.set(key, entry);
+ }
+ },
+ isHeldValueSet: (held) =>
+ getPath(baseYaml, [...held.segments]) !== undefined ||
+ (resolved != null &&
+ getPath(resolved, remapOverridePath(held.segments.join('.')).split('.')) !== undefined),
+ },
+ );
+ return [...found.values()];
+}
+
function getPath(target: unknown, segments: string[]): unknown {
let current = target;
for (const segment of segments) {
@@ -2148,13 +2452,14 @@ function getPath(target: unknown, segments: string[]): unknown {
}
/**
- * Puts back the base value of every `BASE_ONLY_CONFIG_PATHS` field, whatever an override set or a
- * tombstone removed on the way, so every reader of the merged config sees the operator's value.
+ * Puts back the base value of every field only librechat.yaml sets (`YAML_HELD_PATHS`: the
+ * base-only and deployment-only paths), whatever an override set or a tombstone removed on the
+ * way, so every reader of the merged config sees the operator's value.
*/
function preserveBaseOnlyPaths<T extends AppConfig>(baseConfig: AppConfig, merged: T): T {
let result: unknown = merged;
- for (const path of BASE_ONLY_CONFIG_PATHS) {
- const segments = path.split('.');
+ for (const held of YAML_HELD_PATHS) {
+ const segments = remapOverridePath(held.segments.join('.')).split('.');
const value = getPath(baseConfig, segments);
if (getPath(result, segments) !== value) result = setPath(result, segments, value);
}
diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.ts
index b030aa33fa..fa6dd0c0e8 100644
--- a/packages/data-schemas/src/types/admin.ts
+++ b/packages/data-schemas/src/types/admin.ts
@@ -2,6 +2,7 @@ import type {
PrincipalType,
PrincipalModel,
TCustomConfig,
+ DeploymentOnlyConfigReason,
TConfig,
} from 'librechat-data-provider';
@@ -47,10 +48,169 @@ export type AdminConfigResponse = {
config: AdminConfig;
};
-/** A write the server had nothing to apply for; `revision` is the stored document's, if any. */
+/** A location in a config document: its dotted `path`, and the same location key by key. */
+export type AdminConfigLocation = {
+ path: string;
+ /** Unambiguous where a record key itself holds a dot (`gpt-4.1`). */
+ segments: string[];
+};
+
+/**
+ * What a write did with each location it addressed (`writeReport`): stored or removed
+ * (`applied`), or left alone because the generic config API never stores it there (`skipped`,
+ * with the reason). A skipped part of a written value is listed at its own location, and the
+ * rest of the value is stored.
+ */
+export type AdminConfigWriteReport = {
+ applied: AdminConfigLocation[];
+ skipped: Array<AdminConfigLocation & { reason: AdminConfigSkipReason }>;
+};
+
+/**
+ * 200 or 201 from PUT, PATCH `/fields`, POST `/fields/tombstone` and DELETE `/fields`: the
+ * written document as a read shows it, the write report, and the credentials the document's
+ * layer drops at merge (`secretRebinding`).
+ */
+export type AdminConfigWriteResponse = AdminConfigResponse &
+ AdminConfigWriteReport & {
+ ignored?: AdminConfigIgnoredSecret[];
+ };
+
+/**
+ * A write the server had nothing to apply for; `revision` is the stored document's, if any.
+ * With `writeReport`, a write whose every location was skipped also carries the report and the
+ * stored document (`null` when the principal has none).
+ */
export type AdminConfigNoopResponse = {
message: string;
revision: string | null;
+} & Partial<AdminConfigWriteReport & { config: AdminConfig | null }>;
+
+/**
+ * A stored override, or tombstone, that the runtime merge leaves out (`writeReport`), at its own
+ * location. `kind` says which of the document's parts holds it: removing the override (DELETE
+ * `/fields` at `path`) or the tombstone clears it.
+ */
+export type AdminConfigIgnoredOverride = AdminConfigLocation & {
+ reason: AdminConfigIgnoreReason;
+ kind: 'override' | 'tombstone';
+};
+
+/**
+ * GET `/:principalType/:principalId`. `ignored` lists what the document stores that the merge
+ * does not apply, judged as the merge applies the document: over librechat.yaml for Base
+ * (`ignoredBasis: 'yaml'`), and over librechat.yaml and the active Base document for any other
+ * principal (`ignoredBasis: 'base'`), whose users can hold other profiles in between that change
+ * the result. Limited to the sections the caller can read. Both are left out together, rather
+ * than claiming nothing is ignored, when the server cannot judge the document: librechat.yaml
+ * (the base config) or, for a principal other than Base, the Base document cannot be read, or
+ * building the report fails. A missing `ignored` means unknown, not empty.
+ */
+export type AdminConfigReadResponse = AdminConfigResponse & {
+ ignored?: Array<AdminConfigIgnoredOverride | AdminConfigIgnoredSecret>;
+ ignoredBasis?: 'yaml' | 'base';
+};
+
+/**
+ * Bounds and options a zod issue names, copied from the schema and never from the submitted
+ * value, so they are safe to return (`issueParams`). Present only where the issue is attributed
+ * to the exact node that failed.
+ */
+export type ConfigIssueParams = {
+ /** `invalid_type`: the type the schema expects. `invalid_literal`: the literal it expects. */
+ expected?: string | number | boolean | null;
+ /** `invalid_type`: the type that was found: a type name, never the value. */
+ received?: string;
+ /** `invalid_enum_value`, `invalid_union_discriminator`: the values the schema accepts. */
+ options?: Array<string | number | boolean | null>;
+ /** `too_small`: the bound, when it is a number (a date bound in epoch milliseconds). */
+ minimum?: number;
+ /** `too_big`: the bound, when it is a number (a date bound in epoch milliseconds). */
+ maximum?: number;
+ /** `too_small`, `too_big`: whether the bound itself is allowed. */
+ inclusive?: boolean;
+ /** `too_small`, `too_big`: whether the length or size must equal the bound. */
+ exact?: boolean;
+ /** `too_small`, `too_big`: what is bounded (`number`, `string`, `array`, `set`, `date`). */
+ type?: string;
+ /** `invalid_string`: the check that failed (`url`, `email`, `regex`, `startsWith`, ...). */
+ validation?: string;
+ /** `not_multiple_of`: the step the value must be a multiple of. */
+ multipleOf?: number;
+ /** `custom`: the stable reason a refinement names (`missing_port`), never its message. */
+ reason?: string;
+};
+
+/** One validation issue as the admin API returns it: a location, a stable code, safe params. */
+export type AdminConfigIssue = AdminConfigLocation & {
+ code: string;
+ params?: ConfigIssueParams;
+};
+
+/**
+ * 400 `CONFIG_OVERRIDE_INVALID`: the written document fails validation. Messages are never
+ * returned, because schema messages can echo the submitted values.
+ */
+export type AdminConfigInvalidResponse = {
+ error: string;
+ code: 'CONFIG_OVERRIDE_INVALID';
+ issues: AdminConfigIssue[];
+ /** `POST …/changes` only: the batch's skipped report. */
+ skipped?: AdminConfigChangesResponse['skipped'];
+};
+
+/**
+ * The stable `code` the admin config API's own 4xx responses carry (`writeReport`), beside a
+ * human-readable `error`: every handler response, the unsafe-key check, and the capability
+ * middleware, which answers `AUTH_REQUIRED` and `FORBIDDEN` with a `message` instead of
+ * `error`. Shared layers in front of them answer without a `code`: the session check (401
+ * `{ message }` for a missing, invalid or expired token; read it as `AUTH_REQUIRED`), body
+ * parsing (400 for malformed JSON, 413 for an oversized body) and an unmatched route (404
+ * `Endpoint not found`).
+ */
+export type AdminConfigErrorCode =
+ | 'AUTH_REQUIRED'
+ | 'FORBIDDEN'
+ | 'FORBIDDEN_SECTION'
+ | 'INVALID_PRINCIPAL_TYPE'
+ | 'INVALID_OVERRIDES'
+ | 'INVALID_FIELD_PATH'
+ | 'DUPLICATE_FIELD_PATH'
+ | 'ENTRIES_REQUIRED'
+ | 'PATCH_TOO_LARGE'
+ | 'OPS_REQUIRED'
+ | 'TOO_MANY_OPS'
+ | 'INVALID_CHANGE'
+ | 'INVALID_DRY_RUN'
+ | 'INVALID_PRIORITY'
+ | 'INVALID_IS_ACTIVE'
+ | 'INVALID_EXPECTED_REVISION'
+ | 'PROCESS_MCP_CONFIG'
+ | 'PROCESS_MCP_SERVER_OVERRIDE'
+ | 'LANGFUSE_HEADERS_CONFIG'
+ | 'SECRET_PATH'
+ | 'UNKNOWN_SECTION'
+ | 'CONFIG_UNSAFE_KEY'
+ | 'CONFIG_PATH_INVALID'
+ | 'CONFIG_ENTRY_INVALID'
+ | 'CONFIG_RENAME_INVALID'
+ | 'CONFIG_OVERRIDE_INVALID'
+ | 'CONFIG_SECRET_REENTRY_REQUIRED'
+ | 'MCP_API_KEY_REENTRY_REQUIRED'
+ | 'MCP_OAUTH_SECRET_REENTRY_REQUIRED'
+ | 'CONFIG_NOT_FOUND'
+ | 'PRINCIPAL_NOT_FOUND'
+ | 'CONFIG_VERSION_CONFLICT'
+ | 'CONFIG_KEY_NOT_STORABLE'
+ | 'INVALID_PRINCIPAL'
+ | 'INVALID_USER_ID'
+ | 'USER_NOT_FOUND'
+ | 'CONFIG_RELOAD_INVALID';
+
+/** A 4xx of the admin config API. Route-specific fields (`section`, `opIndex`, `reason`, ...) ride beside. */
+export type AdminConfigErrorResponse = {
+ error: string;
+ code: AdminConfigErrorCode;
};
/** 409: the stored document is not at the `expectedRevision` the write named. */
@@ -187,30 +347,58 @@ export type AdminConfigChangesRequest = AdminConfigWritePrecondition & {
};
/**
- * Why a change, or part of a `set` value, was not stored. The rest of the batch still applies.
+ * Why a write, a change, or part of a written value, was not stored. The rest of the request
+ * still applies, and it answers 200 (owner decision: skip and report, never 400).
* - `base_only_section`: a section only `librechat.yaml` configures (`filters`, …).
* - `base_only_path`: a field of an overridable section only `librechat.yaml` sets
- * (`endpoints.agents.pullRequests.provider`, …).
+ * (`endpoints.agents.pullRequests.provider`, …, `rules.baseOnlyPaths`), Base included.
+ * - `deployment_only_path`: a field only `librechat.yaml` sets because it is read at startup or
+ * is an operator boundary (`rateLimits`, `cloudfront`, the tool filters, …,
+ * `rules.deploymentOnlyPaths`), Base included.
* - `dedicated_section`: a section with its own admin API (`langfuse`).
* - `interface_permission`: an interface field that is a role permission.
+ * - `process_mcp_server`: a whole-document (PUT) or whole-section (`mcpServers`) write's entry
+ * for an MCP server `librechat.yaml` runs as a local process, whose configuration overrides
+ * never change. A write to a path inside such a server is refused instead (400
+ * `PROCESS_MCP_SERVER_OVERRIDE`).
+ *
+ * Removing a stored value (DELETE `/fields`, an `unset` change) is cleanup and is never skipped
+ * for `base_only_path`, `deployment_only_path` or `process_mcp_server`.
*/
export type AdminConfigSkipReason =
| 'base_only_section'
| 'base_only_path'
+ | 'deployment_only_path'
| 'dedicated_section'
- | 'interface_permission';
+ | 'interface_permission'
+ | 'process_mcp_server';
/**
- * Why a stored change, or part of one (at its own `segments`), has no effect at runtime.
- * - `process_mcp_server`: a `set`, `tombstone` or `rename` addresses an MCP server
- * `librechat.yaml` runs as a local process, whose configuration overrides never change, or a
- * whole-section `mcpServers` tombstone leaves that server in place. An `unset` there is not
- * reported: it asks for the YAML value, which is what runs.
- * - `base_only_path`: a `tombstone` above a base-only field `librechat.yaml` sets
- * (`endpoints.agents.pullRequests.provider`, …) leaves that field in place and hides only the
- * rest.
+ * Why a stored override, tombstone, change or part of one (at its own `segments`) has no effect
+ * at runtime. `POST …/changes` reports `process_mcp_server`, `base_only_path` and
+ * `deployment_only_path` for the changes it applies; GET `/:principalType/:principalId` reports
+ * every reason for what the document stores.
+ * - `process_mcp_server`: an override or tombstone of an MCP server `librechat.yaml` runs as a
+ * local process, whose configuration overrides never change, or each such server a
+ * whole-section `mcpServers` tombstone leaves in place.
+ * - `base_only_path`, `deployment_only_path`: a value stored at such a field (the merge keeps
+ * `librechat.yaml`'s), or a field of either kind `librechat.yaml` sets below a tombstone, which
+ * the merge puts back so the tombstone hides only the rest.
+ * - `invalid`: a value that fails validation where the merge applies it, so the value beneath
+ * stays (stored before validation existed, or valid only over other layers).
+ * - `unknown_section`: a top-level key `configSchema` does not define (`sectionAllowlist`).
+ * - `base_only_section`, `dedicated_section`, `interface_permission`: as in
+ * {@link AdminConfigSkipReason}, for a value or tombstone already stored.
*/
-export type AdminConfigIgnoreReason = 'process_mcp_server' | 'base_only_path';
+export type AdminConfigIgnoreReason =
+ | 'process_mcp_server'
+ | 'base_only_path'
+ | 'deployment_only_path'
+ | 'invalid'
+ | 'unknown_section'
+ | 'base_only_section'
+ | 'dedicated_section'
+ | 'interface_permission';
/**
* A credential the runtime merge leaves out of a document's layer, or a destination it sets back,
@@ -283,7 +471,7 @@ export type AdminConfigChangeErrorResponse = {
code: string;
opIndex?: number;
reason?: string;
- issues?: Array<{ path: string; segments: string[]; code: string }>;
+ issues?: AdminConfigIssue[];
skipped?: AdminConfigChangesResponse['skipped'];
};
@@ -299,6 +487,8 @@ export type AdminConfigChangeErrorResponse = {
* - `base_principal_section`: a section only the Base document holds (`langfuse`), in another.
* - `base_only_path`: a field only `librechat.yaml` sets (`rules.baseOnlyPaths`); it keeps the
* `librechat.yaml` value.
+ * - `deployment_only_path`: a field only `librechat.yaml` sets, read at startup or from
+ * `librechat.yaml` itself (`rules.deploymentOnlyPaths`); it keeps the `librechat.yaml` value.
* - `process_mcp_server`: an MCP server `librechat.yaml` runs as a local process.
* - `interface_permission`: an interface field that is a role permission.
* - `runtime_stop`: an interface feature `librechat.yaml` turns off, which stays off.
@@ -320,6 +510,7 @@ export type AdminConfigLayerIgnoreReason =
| 'base_only_section'
| 'base_principal_section'
| 'base_only_path'
+ | 'deployment_only_path'
| 'process_mcp_server'
| 'interface_permission'
| 'runtime_stop'
@@ -335,8 +526,9 @@ export type AdminConfigLayerIgnoreReason =
* Part of a layer the merge does not apply as written. `segments` locate it in librechat.yaml
* keys: in the document's overrides (array items by index), or for a credential or destination
* the merge drops or sets back, as write responses name it (a custom endpoint by its name). A
- * tombstone above a `base_only_path` field or a `runtime_stop` feature names that field, which
- * the merge keeps while it removes the rest (write responses name a base-only field the same way).
+ * tombstone above a `base_only_path` or `deployment_only_path` field or a `runtime_stop` feature
+ * names that field, which the merge keeps while it removes the rest (write responses name such a
+ * field the same way).
*/
export type AdminConfigLayerIgnored = {
path: string;
@@ -712,6 +904,36 @@ export type AdminConfigEnvStatusResponse = {
* restarts. Every reload that runs is audited as `config.reloaded` with `metadata.broadcast`, a
* failed one with outcome `failure` and its `code`. A committed config write still reloads the
* file too, on the next read.
+ * - `writeReport`: PUT, PATCH `/fields`, POST `/fields/tombstone` and DELETE `/fields` answer with
+ * `applied` and `skipped` beside `config` (`AdminConfigWriteResponse`), and a write whose every
+ * location is skipped answers 200 with `message`, `revision`, the stored `config` (or `null`)
+ * and the report. Skipped (`AdminConfigSkipReason`), Base included: base-only and dedicated
+ * sections, interface permissions (a whole `interface` value keeps its other fields), base-only
+ * and deployment-only fields (`rules.baseOnlyPaths`, `rules.deploymentOnlyPaths`; a write above
+ * one stores the rest of its value, a removal of one is cleanup and applies), and in a PUT or a
+ * whole `mcpServers` value the servers librechat.yaml runs as local processes. A value cut out
+ * whole resets its path, in request order among a PATCH's entries. A write, rename
+ * or tombstone inside such a server answers 400 `PROCESS_MCP_SERVER_OVERRIDE` on PATCH, POST
+ * `/fields/tombstone` and `/changes` (with `opIndex`); DELETE `/fields` and `unset` stay
+ * allowed. POST `/fields/tombstone` at an array element or inside one answers 400
+ * `CONFIG_PATH_INVALID` (`inside_array`), as `/changes` does. The merge keeps librechat.yaml's
+ * value at every deployment-only field. GET `/:principalType/:principalId` adds `ignored` and
+ * `ignoredBasis` (`AdminConfigReadResponse`): every stored override or tombstone the merge
+ * leaves out, with its `kind` and reason, and the credentials it drops (`secret_rebinding`);
+ * both are left out when the server cannot judge the document. The config API's own 4xx
+ * responses carry a stable `code` (`AdminConfigErrorCode`); the capability middleware adds
+ * `AUTH_REQUIRED` and `FORBIDDEN` beside its `message`. The session check's 401 (an invalid
+ * or expired token) and an unmatched route's 404 carry none.
+ * - `issueParams`: `CONFIG_OVERRIDE_INVALID` issues carry `params` (`ConfigIssueParams`) where
+ * the issue is attributed to the exact node that failed: the expected type or literal, the
+ * accepted options, numeric bounds with `inclusive`, `exact` and `type`, the failed string
+ * check, the multiple, or a refinement's stable `reason`; never a submitted value or a
+ * message. Each refused `allowedAddresses` entry is one `custom` issue with `reason` `empty`,
+ * `format`, `missing_port` or `public_ip`.
+ * - `adminTermsExempt`: the admin config API (`/api/admin/config`, its reads and writes and
+ * `POST /reload`) stays open to an admin who has not accepted the terms of service
+ * (`interface.termsOfService.modalAcceptance`), so they can turn the setting off. Every other
+ * route, admin routes that start work included, still answers 403 `terms_not_accepted`.
*/
export type AdminConfigFeatureFlag =
| 'dottedKeys'
@@ -736,7 +958,10 @@ export type AdminConfigFeatureFlag =
| 'resolvedApi'
| 'catalogApi'
| 'envStatus'
- | 'reloadRoute';
+ | 'reloadRoute'
+ | 'writeReport'
+ | 'issueParams'
+ | 'adminTermsExempt';
export type AdminConfigFeatures = Record<AdminConfigFeatureFlag, boolean>;
@@ -786,6 +1011,12 @@ export type AdminConfigRules = AdminConfigMergeRules & {
basePrincipalSections: string[];
/** Fields inside overridable sections that only `librechat.yaml` sets. */
baseOnlyPaths: string[];
+ /**
+ * Fields only `librechat.yaml` sets because they are read at startup (`startup`), are an
+ * operator boundary (`operator`) or are no longer read (`unused`). Writes skip them
+ * (`deployment_only_path`), Base included, and the merge keeps `librechat.yaml`'s value.
+ */
+ deploymentOnlyPaths: Record<string, DeploymentOnlyConfigReason>;
secretFields: AdminConfigSecretFieldRule[];
arraySecretFields: AdminConfigArraySecretFieldRule[];
/** Secrets of record entries, kept and encrypted per entry like array secrets. */