From babf6f908bde3099f12de951ea82dd16f24f4b82 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sat, 24 Oct 2026 10:01:13 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=BE=20feat:=20Admin=20Config=20Write?= =?UTF-8?q?=20Report,=20Structured=20Issues=20and=20Deployment-Only=20Path?= =?UTF-8?q?s=20(#17395)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🧾 feat: Admin Config Write Report, Structured Issues and Deployment-Only Paths Admin config writes dropped what the API never stores (base-only sections, interface permissions, dedicated sections) with a 200 and no word of it, stored values nothing reads (boot-time and operator-only settings, overrides of MCP servers librechat.yaml runs as local processes, tombstones inside arrays), answered most 4xx without a stable code, returned validation issues without the bound or option that failed, and refused every admin write once the terms-acceptance modal was on for an admin who had not accepted it, including the write that turns it off. PUT, PATCH /fields, POST /fields/tombstone and DELETE /fields now answer with `applied` and `skipped` (with a reason per location); a whole `interface` PATCH keeps its UI fields; base-only paths are skipped on every route. A new DEPLOYMENT_ONLY_CONFIG_PATHS list (rate limits, CloudFront, permission leases, OpenAPI, skill deletion, the tool filters, the agents and MCP boot settings, `cache`) is skipped on write, kept at librechat.yaml's value by the merge and published in GET /meta. Writes and tombstones inside a librechat.yaml stdio MCP server answer 400 PROCESS_MCP_SERVER_OVERRIDE, and a whole-section value leaves those servers out. GET of a document lists what the merge leaves out of it (`ignored`, `ignoredBasis`). Validation issues carry allowlisted `params`; each refused allowedAddresses entry is one issue with a `reason`; agent recursion limits must be whole numbers of at least 1, and the runtime ignores any other value. The config handlers' 4xx carry a `code`, the capability middleware adds AUTH_REQUIRED/FORBIDDEN, and the admin config router opts out of the terms gate. PATCH checks a section manager on every section it names, skipped entries included, as /changes does. New meta flags: writeReport, issueParams, adminTermsExempt. * 🧪 test: Expect Issue Params in the Whole-Document Override Validation Scenario Validation issues now carry `params` (here the expected and received types), so the scenario that asserts the exact issue list for a rejected PUT expects them too. * 🧪 test: Cover Merged Read Codes, Tenant-Scoped Read Reports and Deployment-Only Resolution --- api/server/routes/admin/config.js | 4 +- api/server/routes/admin/config.test.js | 43 +- .../config-override-validation.spec.ts | 8 +- packages/api/src/admin/catalog.spec.ts | 2 + packages/api/src/admin/catalog.ts | 22 +- .../admin/config.changes.integration.spec.ts | 64 +- .../admin/config.dotted.integration.spec.ts | 1 + packages/api/src/admin/config.handler.spec.ts | 103 +- .../config.precedence.integration.spec.ts | 42 + packages/api/src/admin/config.report.spec.ts | 761 ++++++++++++ packages/api/src/admin/config.store.spec.ts | 5 +- packages/api/src/admin/config.ts | 1062 ++++++++++++----- packages/api/src/admin/meta.spec.ts | 159 ++- packages/api/src/admin/meta.ts | 5 + .../src/admin/resolved.integration.spec.ts | 2 + packages/api/src/admin/resolved.ts | 10 +- .../api/src/admin/secrets.integration.spec.ts | 2 +- packages/api/src/agents/config.spec.ts | 31 + packages/api/src/agents/config.ts | 51 +- .../api/src/middleware/capabilities.spec.ts | 7 +- packages/api/src/middleware/capabilities.ts | 6 +- packages/api/src/middleware/terms.spec.ts | 47 +- packages/api/src/middleware/terms.ts | 30 +- packages/data-provider/src/config.spec.ts | 134 +++ packages/data-provider/src/config.ts | 129 +- .../src/app/resolution.layers.spec.ts | 17 + .../data-schemas/src/app/resolution.spec.ts | 340 +++++- packages/data-schemas/src/app/resolution.ts | 487 ++++++-- packages/data-schemas/src/types/admin.ts | 265 +++- 29 files changed, 3336 insertions(+), 503 deletions(-) create mode 100644 packages/api/src/admin/config.report.spec.ts 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; + }>; }; 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 { + canReadSection, + getCapabilityUser, + validatePrincipalType, + forbiddenResponse, + authRequiredResponse, + principalNotFoundResponse, +} from './config'; import { parseEnvAllowlist, collectEnvReferenceSections, collectDefaultEnvReferenceSections, } from '~/app/allowlist'; -import { - canReadSection, - getCapabilityUser, - validatePrincipalType, - principalNotFoundResponse, -} from './config'; 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; +type AdminConfigHandlers = ReturnType; +type AdminConfigDeps = Parameters[0]; +type Handler = (req: ServerRequest, res: Response) => Promise; +type Location = { path: string; segments: string[]; reason?: string; kind?: string }; + +interface MockRes { + statusCode: number; + body: undefined | Record; + 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 = {}): ServerRequest { + return { + user: { id: 'u1', role: 'ADMIN', _id: { toString: () => 'u1' } }, + params: {}, + body: {}, + query: {}, + ...overrides, + } as Partial 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 as Response & MockRes; +} + +function createHandlers(overrides: Partial = {}): 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): Promise { + 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, + tombstones: string[] = [], +): Promise { + 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]> = [ + [ + '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]> = [ + ['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, +): PatchStep[] { + const steps: PatchStep[] = []; + let run: Array<{ target: FieldTarget; value: unknown }> = []; + const pending = { ...fields }; + const flush = () => { + const runFields: Record = {}; + 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, + 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> = { 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 = 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): Set { + 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) { + 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, +): 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 = {}; + for (const [name, server] of Object.entries(value as Record)) { + 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, + 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, +): 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): 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 = new Set([ 'rename', ]); -/** Changes that leave an override in place, which the runtime merge may then drop. */ -const IGNORABLE_OPS: ReadonlySet = new Set([ +/** + * 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 = new Set([ '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; - baseOnlyPaths: ReadonlyArray; + heldPaths: readonly YamlHeldPath[]; } -function getYamlHeld(base: Partial): 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, 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, ): IgnoredPart[] { - const [section, name] = change.target.segments; - if (section !== 'mcpServers' || processServers.size === 0 || !IGNORABLE_OPS.has(change.op)) { + const { segments } = change.target; + if (change.op !== 'tombstone' || segments.length !== 1 || segments[0] !== 'mcpServers') { 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)) { - 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, +): { 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 { 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> { 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 = baseConfig?.config ?? {}; return runConfigMutation( { @@ -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 | null> { + if (!baseConfig) { + return null; + } + try { + const baseYaml: Partial = 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).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; 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), - } as Partial; - for (const section of BASE_ONLY_OVERRIDE_SECTIONS) { - if (section in filteredOverrides) { - delete (filteredOverrides as Record)[section]; - logger.warn( - `[adminConfig] Stripping base-only config section "${section}" - configure it in librechat.yaml instead`, - ); + /** What the API never stores is cut out section by section, and reported as skipped. */ + const skipped: SkippedPart[] = []; + const filteredOverrides: Record = {}; + for (const [section, value] of Object.entries(rawOverrides)) { + const skipReason = getFieldSkipReason(section) ?? getHeldPathSkipReason([section]); + if (skipReason) { + skipped.push({ segments: [section], reason: skipReason }); + continue; } - } - for (const key of Object.keys(filteredOverrides)) { - const section = getTopLevelSection(key); - if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(section)) { - delete (filteredOverrides as Record)[key]; - logger.warn( - `[adminConfig] Stripping dedicated tenant-wide config section "${key}" from the generic config API`, - ); - } - } - const iface = (overrides as Record).interface; - if (isPlainRecord(iface)) { - const { value, stripped } = filterInterfaceOverride(iface); - for (const path of stripped) { - logSkippedField('Stripping', ['interface', ...path].join('.'), 'interface_permission'); - } - if (value) { - (filteredOverrides as Record).interface = value; - } else { - delete (filteredOverrides as Record).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)[section], + const scope = await resolveWriteScope(principalType, principalId); + const baseConfig = + Object.keys(filteredOverrides).length > 0 + ? await getBaseAppConfig(scope.tenantId) + : undefined; + const baseYaml: Partial = 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 = 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(); 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' }); + return authRequiredResponse(res); } - 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; - }); + /** + * 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 seenTargets = new Set(); + 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', + ); } - } - - const seenPaths = new Set(); - const seenSegments = new Set(); - const fields: Record = {}; - 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}` }); - } - 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 = 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 = {}; + 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 Promise> = { audited[2].outcome === 'failure' ); }, + async writeReport() { + const base = { + config: { + mcpServers: { local: { type: 'stdio', command: 'node', args: ['server.js'] } }, + }, + } as Partial as AppConfig; + const getAppConfig = jest.fn().mockResolvedValue(base); + const writeConfigDocument = jest.fn( + async (_type: string, _id: string, draft: ConfigDraft): Promise => + 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 => { + 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 = { 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(); + +/** + * 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 | 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 | 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(); + +/** + * 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 => { 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 | undefined = node + ? (unwrap(node).shape as Record | 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([...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> = { + 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> = { + 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 }; + ]; - 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, path: string): unknown { + return path + .split('.') + .reduce((node, key) => (node as Record | undefined)?.[key], target); + } + + function put(target: Record, 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 | undefined) ?? {}; + node = node[key] as Record; + } + node[keys[keys.length - 1]] = value; + } + + it('keeps librechat.yaml’s value at every deployment-only path, whatever a layer stores', () => { + const base: Record = { config: {} }; + const overrides: Record = {}; + 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; + 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 }; + }; + 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; + + const reasons = (entries: ReturnType) => + 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(['filters', ...BASE_ONLY_CONFIG_SECTIONS]); const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set(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; +} + +/** + * 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; @@ -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, + 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(); 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; @@ -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, @@ -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( initial: T, initialRaw: Partial, configs: readonly ConfigOverrideLayer[], afterLayer?: (step: FoldStep) => T, - tracker?: FoldTracker, + { + sink, + tracker, + isHeldValueSet = (held) => getPath(initialRaw, [...held.segments]) !== undefined, + }: FoldObservers = {}, ): { merged: T; raw: Partial; 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( 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; - 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; + 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( 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( 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( // 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( } } } + 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; 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): 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, + layer: ConfigOverrideLayer, + below: readonly ConfigOverrideLayer[] = [], + resolved?: AppConfig, +): AdminConfigIgnoredOverride[] { + const found = new Map(); + 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(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; +}; + +/** + * 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; + +/** + * 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; + 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; + /** `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; @@ -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; secretFields: AdminConfigSecretFieldRule[]; arraySecretFields: AdminConfigArraySecretFieldRule[]; /** Secrets of record entries, kept and encrypted per entry like array secrets. */