Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes (#17326)
Danny Avila0b4dc238b383
diff --git a/api/server/routes/__tests__/admin-config-reload.spec.js b/api/server/routes/__tests__/admin-config-reload.spec.jsnew file mode 100644index 0000000000..f14480f382--- /dev/null+++ b/api/server/routes/__tests__/admin-config-reload.spec.js@@ -0,0 +1,157 @@+/**+ * Admin config writes through the real router, handlers, database methods, config service and+ * cache invalidation reload librechat.yaml, which is how a running server picks up an edit to a+ * base-only section such as `filters`. A request with nothing to write commits nothing and+ * reloads nothing; the e2e content-filter helpers rely on a write that always commits.+ * Only the caller's identity and capabilities and the structured-tool scan are stubbed.+ */+const fs = require('fs');+const os = require('os');+const path = require('path');+const yaml = require('js-yaml');+const express = require('express');+const request = require('supertest');+const mongoose = require('mongoose');+const { MongoMemoryServer } = require('mongodb-memory-server');+const { createModels } = require('@librechat/data-schemas');+const { Constants } = require('librechat-data-provider');++const mockAdmin = { id: new mongoose.Types.ObjectId().toString(), role: 'ADMIN' };++jest.mock('~/server/middleware', () => ({+ requireJwtAuth: (req, _res, next) => {+ req.user = mockAdmin;+ next();+ },+}));++jest.mock('~/server/middleware/roles/capabilities', () => ({+ requireCapability: () => (_req, _res, next) => next(),+ hasCapability: async () => true,+ hasConfigCapability: async () => true,+ hasAnyConfigReadAccess: async () => true,+ getReadableConfigSections: async (_user, sections) => ({+ broad: true,+ sections: new Set(sections),+ }),+}));++jest.mock('~/server/services/start/tools', () => ({+ loadAndFormatTools: jest.fn(() => ({})),+}));++const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'librechat-admin-config-reload-'));+const configPath = path.join(configDir, 'librechat.yaml');+const previousConfigPath = process.env.CONFIG_PATH;+process.env.CONFIG_PATH = configPath;++/** Each YAML edit marks the base it produces with its own `maxMatches`. */+function writeYaml(maxMatches) {+ const filters = { prompts: { pii: { action: 'block', fields: ['name'], maxMatches } } };+ fs.writeFileSync(configPath, yaml.dump({ version: Constants.CONFIG_VERSION, filters }));+}++const principal = '/api/admin/config/user/reload-sentinel';++let app;+let mongoServer;++beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+ /** Building every model's indexes takes longer than the suite; only the config store's count. */+ mongoose.set('autoIndex', false);+ createModels(mongoose);+ await mongoose.models.Config.createIndexes();+ writeYaml(1);+ app = express();+ app.use(express.json());+ app.use('/api/admin/config', require('../admin/config'));+});++afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer.stop();+ if (previousConfigPath === undefined) {+ delete process.env.CONFIG_PATH;+ } else {+ process.env.CONFIG_PATH = previousConfigPath;+ }+ fs.rmSync(configDir, { recursive: true, force: true });+});++/** The `maxMatches` GET /base serves, base-only and merged with the Base profile. */+async function served() {+ const responses = await Promise.all([+ request(app).get('/api/admin/config/base').query({ baseOnly: 'true' }),+ request(app).get('/api/admin/config/base'),+ ]);+ return responses.map(({ status, body }) =>+ status === 200 ? body.config.filters?.prompts?.pii?.maxMatches : status,+ );+}++describe('admin config writes and librechat.yaml', () => {+ /** Ordered: each write acts on the document the previous one left. */+ const writes = [+ ['PUT a document', 201, (agent) => agent.put(principal).send({ overrides: {}, priority: 10 })],+ [+ 'PATCH a field',+ 200,+ (agent) =>+ agent+ .patch(`${principal}/fields`)+ .send({ entries: [{ fieldPath: 'interface.customWelcome', value: 'hi' }] }),+ ],+ [+ 'tombstone a field',+ 200,+ (agent) => agent.post(`${principal}/fields/tombstone`).send({ fieldPath: 'webSearch' }),+ ],+ [+ 'DELETE a field',+ 200,+ (agent) =>+ agent.delete(`${principal}/fields`).query({ fieldPath: 'interface.customWelcome' }),+ ],+ [+ 'deactivate the document',+ 200,+ (agent) => agent.patch(`${principal}/active`).send({ isActive: false }),+ ],+ ['DELETE the document', 200, (agent) => agent.delete(principal)],+ ];++ it('serves the librechat.yaml that was on disk at startup', async () => {+ expect(await served()).toEqual([1, 1]);+ });++ it.each(writes.map((write, index) => [...write, index + 2]))(+ 'reloads librechat.yaml after the write: %s',+ async (_label, status, send, maxMatches) => {+ writeYaml(maxMatches);+ expect(await served()).toEqual([maxMatches - 1, maxMatches - 1]);++ const response = await send(request(app));++ expect(response.status).toBe(status);+ expect(await served()).toEqual([maxMatches, maxMatches]);+ },+ );++ it('does not reload for a request with nothing to write', async () => {+ const committed = writes.length + 1;+ writeYaml(committed + 1);++ const noop = await request(app).put(principal).send({ overrides: {} });++ expect(noop.status).toBe(200);+ expect(noop.body.message).toBe('No actionable override sections provided');+ expect(await served()).toEqual([committed, committed]);++ const write = await request(app).put(principal).send({ overrides: {}, priority: 10 });++ expect(write.status).toBe(201);+ expect(await served()).toEqual([committed + 1, committed + 1]);+ });+});diff --git a/api/server/routes/admin/config.js b/api/server/routes/admin/config.jsindex 51aae02cc5..398b752e83 100644--- a/api/server/routes/admin/config.js+++ b/api/server/routes/admin/config.js@@ -23,8 +23,7 @@ const requireAdminAccess = requireCapability(SystemCapabilities.ACCESS_ADMIN);const handlers = createAdminConfigHandlers({listAllConfigs: db.listAllConfigs,findConfigByPrincipal: db.findConfigByPrincipal,- upsertConfig: db.upsertConfig,- patchConfigFields: db.patchConfigFields,+ writeConfigDocument: db.writeConfigDocument,tombstoneConfigField: db.tombstoneConfigField,unsetConfigField: db.unsetConfigField,deleteConfig: db.deleteConfig,diff --git a/api/server/routes/admin/config.test.js b/api/server/routes/admin/config.test.jsindex 62a9f79e7d..b01eab3d25 100644--- a/api/server/routes/admin/config.test.js+++ b/api/server/routes/admin/config.test.js@@ -20,8 +20,7 @@ const mockRequireCapability = jest.fn(() => (_req, res, next) => {const mockDb = {listAllConfigs: jest.fn(),findConfigByPrincipal: jest.fn(),- upsertConfig: jest.fn(),- patchConfigFields: jest.fn(),+ writeConfigDocument: jest.fn(),tombstoneConfigField: jest.fn(),unsetConfigField: jest.fn(),deleteConfig: jest.fn(),@@ -78,17 +77,12 @@ describe('admin config routes', () => {beforeEach(() => {hasAdminAccess = true;mockDb.findConfigByPrincipal.mockResolvedValue(null);- mockDb.patchConfigFields.mockImplementation(async (principalType, principalId, _m, fields) => ({+ mockDb.writeConfigDocument.mockImplementation(async (principalType, principalId, draft) => ({+ _id: 'c1',principalType,principalId,- priority: 10,- isActive: true,configVersion: 1,- overrides: {- endpoints: {- bedrock: { inferenceProfiles: fields['endpoints.bedrock.inferenceProfiles'] },- },- },+ ...draft,}));});@@ -103,7 +97,7 @@ describe('admin config routes', () => {.expect(401);expect(response.body).toEqual({ message: 'Unauthorized' });- expect(mockDb.patchConfigFields).not.toHaveBeenCalled();+ expect(mockDb.writeConfigDocument).not.toHaveBeenCalled();});it('answers 403 before the key guard without admin access', async () => {@@ -115,7 +109,7 @@ describe('admin config routes', () => {.send(unsafeBody).expect(403);- expect(mockDb.patchConfigFields).not.toHaveBeenCalled();+ expect(mockDb.writeConfigDocument).not.toHaveBeenCalled();});it.each([@@ -130,7 +124,7 @@ describe('admin config routes', () => {expect(response.body.code).toBe('CONFIG_UNSAFE_KEY');expect(JSON.stringify(response.body)).not.toMatch(/\$where|__proto__/);- expect(mockDb.upsertConfig).not.toHaveBeenCalled();+ expect(mockDb.writeConfigDocument).not.toHaveBeenCalled();});it('delivers dotted record keys to the write method intact', async () => {@@ -142,14 +136,13 @@ describe('admin config routes', () => {}).expect(200);- expect(mockDb.patchConfigFields).toHaveBeenCalledWith(+ expect(mockDb.writeConfigDocument).toHaveBeenCalledWith('role','USER',- expect.anything(),- { 'endpoints.bedrock.inferenceProfiles': { [PROFILE]: ARN } },- expect.any(Number),- undefined,- undefined,+ expect.objectContaining({+ overrides: { endpoints: { bedrock: { inferenceProfiles: { [PROFILE]: ARN } } } },+ }),+ 'absent',);expect(response.body.config.overrides.endpoints.bedrock.inferenceProfiles).toEqual({[PROFILE]: ARN,diff --git a/api/server/services/Config/__tests__/invalidateConfigCaches.reload.spec.js b/api/server/services/Config/__tests__/invalidateConfigCaches.reload.spec.jsnew file mode 100644index 0000000000..1207273c5d--- /dev/null+++ b/api/server/services/Config/__tests__/invalidateConfigCaches.reload.spec.js@@ -0,0 +1,79 @@+/**+ * The admin config write path with the real YAML loader, AppService, config service and cache+ * invalidation: a base-only section edited in librechat.yaml reaches the running server on the+ * next admin config write. Only the database methods and the structured-tool scan are stubbed;+ * neither contributes to the base config under test.+ */+const fs = require('fs');+const os = require('os');+const path = require('path');+const yaml = require('js-yaml');+const { Constants } = require('librechat-data-provider');++jest.mock('~/server/services/start/tools', () => ({+ loadAndFormatTools: jest.fn(() => ({})),+}));++jest.mock('~/models', () => ({+ initializeMessageBudget: jest.fn(),+ getApplicableConfigs: jest.fn().mockResolvedValue([]),+ getUserPrincipals: jest.fn().mockResolvedValue([]),+}));++const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'librechat-config-reload-'));+const configPath = path.join(configDir, 'librechat.yaml');+const previousConfigPath = process.env.CONFIG_PATH;+process.env.CONFIG_PATH = configPath;++const filters = {+ prompts: { pii: { action: 'block', fields: ['name'] } },+};++/** @param {Record<string, unknown>} config */+function writeYaml(config) {+ fs.writeFileSync(configPath, yaml.dump({ version: Constants.CONFIG_VERSION, ...config }));+}++writeYaml({});++const { getAppConfig, invalidateConfigCaches } = require('../app');++afterAll(() => {+ if (previousConfigPath === undefined) {+ delete process.env.CONFIG_PATH;+ } else {+ process.env.CONFIG_PATH = previousConfigPath;+ }+ fs.rmSync(configDir, { recursive: true, force: true });+});++describe('admin config writes and librechat.yaml', () => {+ it('serve base-only sections edited in librechat.yaml after the next write', async () => {+ const before = await getAppConfig({ baseOnly: true });+ const effectiveBefore = await getAppConfig({ role: 'USER' });+ expect(before.filters).toBeUndefined();+ expect(effectiveBefore.filters).toBeUndefined();++ writeYaml({ filters });+ expect((await getAppConfig({ baseOnly: true })).filters).toBeUndefined();++ await invalidateConfigCaches();++ const after = await getAppConfig({ baseOnly: true });+ const effectiveAfter = await getAppConfig({ role: 'USER' });+ expect(after.filters?.prompts?.pii).toEqual(expect.objectContaining(filters.prompts.pii));+ expect(effectiveAfter.filters).toEqual(after.filters);+ });++ it('serve a section removed from librechat.yaml as gone after the next write', async () => {+ writeYaml({ filters });+ await invalidateConfigCaches();+ expect((await getAppConfig({ baseOnly: true })).filters).toBeDefined();++ writeYaml({});+ await invalidateConfigCaches();++ expect((await getAppConfig({ baseOnly: true })).filters).toBeUndefined();+ expect((await getAppConfig({ role: 'USER' })).filters).toBeUndefined();+ });+});diff --git a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.jsindex 4b99cd28a8..46b419a95e 100644--- a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js+++ b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js@@ -33,6 +33,14 @@ jest.mock('../getCachedTools', () => ({}));const mockClearMcpConfigCache = jest.fn().mockResolvedValue(undefined);+const mockCreateRedisPubSub = jest.fn(() => undefined);+/** The invalidation the module composes; its own behavior is covered in packages/api. */+const mockCreateConfigCacheInvalidation = jest.fn(({ clears }) => ({+ invalidate: async (tenantId) => {+ await Promise.allSettled(clears.map(({ clear }) => clear(tenantId)));+ },+ close: async () => undefined,+}));jest.mock('@librechat/api', () => ({createAppConfigService: jest.fn(() => ({getAppConfig: jest.fn().mockResolvedValue({ availableTools: {} }),@@ -40,6 +48,10 @@ jest.mock('@librechat/api', () => ({clearOverrideCache: mockClearOverrideCache,})),clearMcpConfigCache: mockClearMcpConfigCache,+ createConfigCacheInvalidation: mockCreateConfigCacheInvalidation,+ createRedisConfigInvalidationPubSub: mockCreateRedisPubSub,+ ioredisClient: null,+ cacheConfig: { USE_REDIS: false, REDIS_KEY_PREFIX: 'deploy-a' },createCodeEnvironmentRegistry: jest.fn(() => ({})),mergeAccessibleCodeEnvironments: jest.fn(({ appConfig }) => appConfig),}));@@ -50,6 +62,8 @@ const { getAppConfig, invalidateConfigCaches } = require('../app');const { initializeMessageBudget } = require('~/models');// Capture module-composition calls before clearMocks resets the spy history.const budgetInitializations = [...initializeMessageBudget.mock.calls];+const invalidationOptions = mockCreateConfigCacheInvalidation.mock.calls[0][0];+const pubSubOptions = mockCreateRedisPubSub.mock.calls[0][0];test('Config supplies its actual reader exactly once during composition', () => {expect(budgetInitializations).toEqual([[getAppConfig]]);@@ -60,75 +74,34 @@ describe('invalidateConfigCaches', () => {jest.clearAllMocks();});- it('clears all caches', async () => {+ it('clears the YAML base config, the override caches and the MCP config caches', async () => {await invalidateConfigCaches();+ const labels = invalidationOptions.clears.map(({ label }) => label);+ expect(labels).toHaveLength(3);+ expect(labels).toEqual(+ expect.arrayContaining(['clearAppConfigCache', 'clearOverrideCache', 'clearMcpConfigCache']),+ );expect(mockClearAppConfigCache).toHaveBeenCalledTimes(1);expect(mockClearOverrideCache).toHaveBeenCalledTimes(1);- expect(mockInvalidateCachedTools).toHaveBeenCalledWith({ invalidateGlobal: true });expect(mockClearMcpConfigCache).toHaveBeenCalledTimes(1);});- it('passes tenantId through to clearOverrideCache', async () => {+ it('leaves the global tool cache for the base reload to republish', async () => {await invalidateConfigCaches('tenant-a');- expect(mockClearOverrideCache).toHaveBeenCalledWith('tenant-a');expect(mockClearAppConfigCache).toHaveBeenCalledTimes(1);- expect(mockInvalidateCachedTools).toHaveBeenCalledWith({ invalidateGlobal: true });+ expect(mockInvalidateCachedTools).not.toHaveBeenCalled();});- it('all operations run in parallel (not sequentially)', async () => {- const order = [];-- mockClearAppConfigCache.mockImplementation(- () =>- new Promise((r) =>- setTimeout(() => {- order.push('base');- r();- }, 10),- ),- );- mockClearOverrideCache.mockImplementation(- () =>- new Promise((r) =>- setTimeout(() => {- order.push('override');- r();- }, 10),- ),- );- mockInvalidateCachedTools.mockImplementation(- () =>- new Promise((r) =>- setTimeout(() => {- order.push('tools');- r();- }, 10),- ),- );- mockClearMcpConfigCache.mockImplementation(- () =>- new Promise((r) =>- setTimeout(() => {- order.push('mcp');- r();- }, 10),- ),- );-- await invalidateConfigCaches();+ it('passes tenantId through to clearOverrideCache', async () => {+ await invalidateConfigCaches('tenant-a');- expect(order).toHaveLength(4);- expect(new Set(order)).toEqual(new Set(['base', 'override', 'tools', 'mcp']));+ expect(mockClearOverrideCache).toHaveBeenCalledWith('tenant-a');});- it('resolves even when clearAppConfigCache throws (partial failure)', async () => {- mockClearAppConfigCache.mockRejectedValueOnce(new Error('cache connection lost'));-- await expect(invalidateConfigCaches()).resolves.not.toThrow();-- expect(mockClearOverrideCache).toHaveBeenCalledTimes(1);- expect(mockInvalidateCachedTools).toHaveBeenCalledWith({ invalidateGlobal: true });+ it('asks for the Redis pub/sub with the deployment settings, and broadcasts nothing without it', () => {+ expect(pubSubOptions).toEqual({ useRedis: false, client: null, namespace: 'deploy-a' });+ expect(invalidationOptions.pubsub).toBeUndefined();});});diff --git a/api/server/services/Config/app.js b/api/server/services/Config/app.jsindex 7a70db520d..3492c0dffe 100644--- a/api/server/services/Config/app.js+++ b/api/server/services/Config/app.js@@ -1,15 +1,18 @@const mongoose = require('mongoose');const { CacheKeys } = require('librechat-data-provider');-const { AppService, logger } = require('@librechat/data-schemas');+const { AppService } = require('@librechat/data-schemas');const {createAppConfigService,clearMcpConfigCache,createCodeEnvironmentRegistry,+ createConfigCacheInvalidation,+ createRedisConfigInvalidationPubSub,mergeAccessibleCodeEnvironments,+ ioredisClient,cacheConfig,standardCache,} = require('@librechat/api');-const { setCachedTools, invalidateCachedTools } = require('./getCachedTools');+const { setCachedTools } = require('./getCachedTools');const { loadAndFormatTools } = require('~/server/services/start/tools');const loadCustomConfig = require('./loadCustomConfig');const getLogStores = require('~/cache/getLogStores');@@ -74,29 +77,32 @@ const { getAppConfig, clearAppConfigCache, clearOverrideCache, overrideCacheTtldb.initializeMessageBudget(getAppConfig);/**- * Invalidate all config-related caches after an admin config mutation.- * Clears the base config, per-principal override caches, tool caches,- * and the MCP config-source server cache.+ * Admin config writes clear the per-principal override caches, the MCP config-source servers+ * and the YAML base config. Base-only sections such as `filters` and `messageFilter` exist only+ * in librechat.yaml, and an admin write is how a running server picks up an edit to them: the+ * next read reloads the YAML (keeping the last good config if it fails) and republishes the+ * tools derived from it. With Redis, the clear is broadcast so every instance reloads its YAML+ * and drops its in-process merged config.+ */+const configCacheInvalidation = createConfigCacheInvalidation({+ clears: [+ { label: 'clearAppConfigCache', clear: () => clearAppConfigCache() },+ { label: 'clearOverrideCache', clear: clearOverrideCache },+ { label: 'clearMcpConfigCache', clear: () => clearMcpConfigCache() },+ ],+ pubsub: createRedisConfigInvalidationPubSub({+ useRedis: cacheConfig.USE_REDIS,+ client: ioredisClient,+ namespace: cacheConfig.REDIS_KEY_PREFIX,+ }),+});++/**+ * Invalidate the config caches an admin config mutation affects, on every instance.* @param {string} [tenantId] - Optional tenant ID to scope override cache clearing.*/-async function invalidateConfigCaches(tenantId) {- const results = await Promise.allSettled([- clearAppConfigCache(),- clearOverrideCache(tenantId),- invalidateCachedTools({ invalidateGlobal: true }),- clearMcpConfigCache(),- ]);- const labels = [- 'clearAppConfigCache',- 'clearOverrideCache',- 'invalidateCachedTools',- 'clearMcpConfigCache',- ];- for (let i = 0; i < results.length; i++) {- if (results[i].status === 'rejected') {- logger.error(`[invalidateConfigCaches] ${labels[i]} failed:`, results[i].reason);- }- }+function invalidateConfigCaches(tenantId) {+ return configCacheInvalidation.invalidate(tenantId);}module.exports = {diff --git a/e2e/specs/mock/content-filters.helpers.ts b/e2e/specs/mock/content-filters.helpers.tsindex efd714da53..59c9cccb8a 100644--- a/e2e/specs/mock/content-filters.helpers.ts+++ b/e2e/specs/mock/content-filters.helpers.ts@@ -179,6 +179,11 @@ function getConfigFromResult(result: RequestResult): RuntimeConfig {return result.body.config as RuntimeConfig;}+/**+ * A committed admin config write is what makes the server reload librechat.yaml; a request with+ * nothing to write reloads nothing. A PUT that carries `priority` always writes the sentinel,+ * and the returned `config` confirms it did (a no-op answers with only a message).+ */async function triggerConfigReload(request: APIRequestContext, token: string): Promise<void> {const result = await requestResult(request, {path: RELOAD_SENTINEL_PATH,diff --git a/packages/api/src/admin/binding.ts b/packages/api/src/admin/binding.tsindex 1f7df1d334..96133db111 100644--- a/packages/api/src/admin/binding.ts+++ b/packages/api/src/admin/binding.ts@@ -1,6 +1,6 @@import isPlainObject from 'lodash/isPlainObject';import { webSearchPairedFields, getRebindingWebSearchKeys } from '@librechat/data-schemas';-import type { Config, ConfigOverrideIssue } from '@librechat/data-schemas';+import type { Config, ConfigFieldWrite, ConfigOverrideIssue } from '@librechat/data-schemas';/** Issue code for a URL a write changed while the secret stored beside it stays. */export const SECRET_REENTRY_REQUIRED = 'secret_reentry_required';@@ -81,11 +81,6 @@ export function isWebSearchBindingPath(fieldPath: string): boolean {return fieldPath === WEB_SEARCH || getPairedField(fieldPath) != null;}-/** Whether a full replace of a document's overrides writes its web search section. */-export function hasWebSearchSection(overrides: unknown): boolean {- return getRecord(overrides)?.[WEB_SEARCH] !== undefined;-}-/*** Re-entry issues for a write that replaces a document's overrides. Its* tombstones stay as stored.@@ -108,46 +103,38 @@ export function getReplaceReentryIssues(}/**- * Re-entry issues for a field patch, which sets each dot-path on the stored- * document and clears the tombstone at each written path.+ * Re-entry issues for a field patch, judged on the document the patch would+ * store. Writes apply in request order, so a later write can replace what an+ * earlier one set (a whole `webSearch` after one of its fields); only the+ * planned document says which URL a stored key ends up beside.* @param stored - The document before the write.- * @param input - The field paths and values the request supplied.- * @param next - The field paths and values the write would set, omitted secrets preserved.+ * @param writes - The field writes the request supplied, in order.+ * @param next - The overrides and tombstones the write would store, omitted secrets preserved.*/export function getPatchReentryIssues(stored: StoredConfigState,- input: ConfigFields,- next: ConfigFields,+ writes: readonly ConfigFieldWrite[],+ next: StoredConfigState,): SecretReentryIssue[] {- const storedWebSearch = getWebSearch(stored?.overrides);- let nextWebSearch = storedWebSearch;const written = new Set<string>();- if (WEB_SEARCH in next) {- nextWebSearch = getRecord(next[WEB_SEARCH]);- for (const field of Object.keys(getRecord(input[WEB_SEARCH]) ?? {})) {- written.add(field);- }- }- for (const [path, value] of Object.entries(next)) {- const field = path.startsWith(WEB_SEARCH_PREFIX) ? path.slice(WEB_SEARCH_PREFIX.length) : '';- if (field === '' || field.includes('.')) {+ let touched = false;+ for (const { segments, value } of writes) {+ if (segments[0] !== WEB_SEARCH) {continue;}- nextWebSearch = { ...nextWebSearch, [field]: value };- if (path in input) {- written.add(field);+ touched = true;+ if (segments.length === 1) {+ Object.keys(getRecord(value) ?? {}).forEach((field) => written.add(field));+ } else if (segments.length === 2) {+ written.add(segments[1]);}}- if (nextWebSearch === storedWebSearch) {+ if (!touched) {return [];}- const tombstones = stored?.tombstones ?? [];return toReentryIssues(- getWebSearchView(storedWebSearch, tombstones),- getWebSearchView(- nextWebSearch,- tombstones.filter((path) => !(path in next)),- ),+ getWebSearchView(getWebSearch(stored?.overrides), stored?.tombstones),+ getWebSearchView(getWebSearch(next?.overrides), next?.tombstones),written,);}diff --git a/packages/api/src/admin/config.dotted.integration.spec.ts b/packages/api/src/admin/config.dotted.integration.spec.tsindex fd83f3034a..45eba93354 100644--- a/packages/api/src/admin/config.dotted.integration.spec.ts+++ b/packages/api/src/admin/config.dotted.integration.spec.ts@@ -47,8 +47,7 @@ beforeAll(async () => {const handlers = createAdminConfigHandlers({listAllConfigs: methods.listAllConfigs,findConfigByPrincipal: methods.findConfigByPrincipal,- upsertConfig: methods.upsertConfig,- patchConfigFields: methods.patchConfigFields,+ writeConfigDocument: methods.writeConfigDocument,tombstoneConfigField: methods.tombstoneConfigField,unsetConfigField: methods.unsetConfigField,deleteConfig: methods.deleteConfig,@@ -138,8 +137,10 @@ describe('admin config writes keep dotted record keys (real sanitizer, handlers{ fieldPath: 'endpoints.bedrock.inferenceProfiles', value: profiles },]).expect(200);- const raw = await readRaw(role);- expect(getIn(raw?.overrides, ['endpoints', 'bedrock', 'inferenceProfiles'])).toEqual(profiles);+ /** Stored raw where the engine accepts dotted names, as servers before the key encoding read them. */+ expect(+ getIn((await readRaw(role))?.overrides, ['endpoints', 'bedrock', 'inferenceProfiles']),+ ).toEqual(profiles);const read = await getOverrides(role);expect(getIn(read, ['endpoints', 'bedrock', 'inferenceProfiles'])).toEqual(profiles);expect(getIn(merge(read), ['endpoints', 'bedrock', 'inferenceProfiles'])).toEqual(profiles);@@ -204,6 +205,8 @@ describe('admin config writes keep dotted record keys (real sanitizer, handlersexpect(stored.headers).toEqual({ 'x-portkey.config': 'cfg' });expect(stored.apiKey).toMatch(/^v3:/);expect(decryptV3(stored.apiKey as string)).toBe(API_KEY);+ const [read] = getIn(await getOverrides(role), ['endpoints', 'custom']) as Doc[];+ expect(read.headers).toEqual({ 'x-portkey.config': 'cfg' });});it('removes a dotted record whole through its own field path', async () => {@@ -306,14 +309,18 @@ function findDottedKey(value: unknown): string | undefined {/*** Turns the in-memory MongoDB into an engine that refuses dotted field names inside stored- * documents, the way MongoDB before 3.6 did, instead of storing them. `$set` paths stay dotted;- * only keys inside the values are judged.+ * documents, the way MongoDB before 3.6 did, instead of storing them. `$set` and `$setOnInsert`+ * paths stay dotted; only keys inside the values are judged.*/function refuseDottedFieldNames(): () => void {const collection = mongoose.models.Config.collection;const findOneAndUpdate = collection.findOneAndUpdate.bind(collection);- collection.findOneAndUpdate = (async (filter: Doc, update: { $set?: Doc }, options: Doc) => {- const key = Object.values(update.$set ?? {})+ collection.findOneAndUpdate = (async (+ filter: Doc,+ update: { $set?: Doc; $setOnInsert?: Doc },+ options: Doc,+ ) => {+ const key = [...Object.values(update.$set ?? {}), ...Object.values(update.$setOnInsert ?? {})].map(findDottedKey).find((found) => found != null);if (key) {@@ -354,6 +361,9 @@ describe('admin config writes on an engine that cannot store dotted keys', () =>patchFields(role, [{ fieldPath: 'endpoints.bedrock.inferenceProfiles', value: { [PROFILE]: ARN } },]),+ 200,+ ['endpoints', 'bedrock', 'inferenceProfiles'],+ { [PROFILE]: ARN },],['PUT',@@ -367,36 +377,43 @@ describe('admin config writes on an engine that cannot store dotted keys', () =>},},}),+ 201,+ ['endpoints', 'azureOpenAI', 'groups', '0', 'models'],+ { 'gpt-4.1': true },],[- 'a version-checked PATCH',+ 'a PATCH that also moves a web search URL',(role: string) =>patchFields(role, [{ fieldPath: 'webSearch.searxngInstanceUrl', value: 'https://searx.example.com' },{ fieldPath: 'endpoints.bedrock.inferenceProfiles', value: { [PROFILE]: ARN } },]),+ 200,+ ['endpoints', 'bedrock', 'inferenceProfiles'],+ { [PROFILE]: ARN },],[- 'a version-checked PUT',+ 'a PUT that also writes the web search section',(role: string) =>putOverrides(role, {webSearch: { safeSearch: 2 },endpoints: { bedrock: { inferenceProfiles: { [PROFILE]: ARN } } },}),+ 201,+ ['endpoints', 'bedrock', 'inferenceProfiles'],+ { [PROFILE]: ARN },],- ])('answers %s with 422 CONFIG_KEY_NOT_STORABLE, not an uncoded 500', async (_label, write) => {- const role = nextRole();- const response = await write(role).expect(422);-- expect(response.body).toEqual({- error: 'The database cannot store a key name in this config',- code: 'CONFIG_KEY_NOT_STORABLE',- });- const logged = JSON.stringify(warn.mock.calls);- expect(logged).toContain('rejected a key name');- expect(logged).not.toMatch(/us\.anthropic|gpt-4\.1/);- expect(await readRaw(role)).toBeNull();- });+ ])(+ 'stores a %s whose record keys hold dots, encoded so the engine sees none',+ async (_label, write, status, path, expected) => {+ const role = nextRole();+ await write(role).expect(status);++ expect(findDottedKey((await readRaw(role))?.overrides)).toBeUndefined();+ expect(getIn(await getOverrides(role), path)).toEqual(expected);+ expect(JSON.stringify(warn.mock.calls)).not.toContain('rejected a key name');+ },+ );it('still stores writes without dotted keys', async () => {const role = nextRole();diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.tsindex fb2d9ccce3..cb949fa8c1 100644--- a/packages/api/src/admin/config.handler.spec.ts+++ b/packages/api/src/admin/config.handler.spec.ts@@ -1,3 +1,4 @@+import type { ConfigDraft, ConfigRecord } from '@librechat/data-schemas';import type { Response } from 'express';import type { ServerRequest } from '~/types/http';@@ -11,9 +12,17 @@ jest.mock('@librechat/data-schemas', () => {return {...actual,encryptV3: jest.fn((value: string) => `v3:test:${value}`),+ /** Spies that keep the real validation, to see which document it was shown. */+ getConfigOverrideIssues: jest.fn(actual.getConfigOverrideIssues),+ getConfigFieldIssues: jest.fn(actual.getConfigFieldIssues),};});+import {+ getConfigFieldIssues,+ getConfigOverrideIssues,+ ConfigRevisionConflictError,+} from '@librechat/data-schemas';import { createAdminConfigHandlers } from './config';function mockReq(overrides = {}) {@@ -49,20 +58,51 @@ function mockRes() {return res as Partial<Response> as Response & MockRes;}+/** The document a whole-document write stores: version 1 on create, else one past the revision. */+function writtenDocument(+ principalType: string,+ principalId: string,+ draft: ConfigDraft,+ expected: string,+): ConfigRecord {+ const configVersion = expected === 'absent' ? 1 : Number(expected.split(':')[1]) + 1;+ return {+ _id: 'c1',+ principalType: principalType as ConfigRecord['principalType'],+ principalId,+ ...draft,+ configVersion,+ };+}++/** The draft the handler wrote with its `n`-th whole-document write. */+function writtenDraft(deps: { writeConfigDocument: jest.Mock }, call = 0) {+ return deps.writeConfigDocument.mock.calls[call][2] as Record<string, unknown> & {+ overrides: Record<string, unknown>;+ tombstones: string[];+ priority: number;+ isActive: boolean;+ };+}++/** The value the handler's first whole-document write stored at a dotted path. */+function writtenField(deps: { writeConfigDocument: jest.Mock }, fieldPath: string): unknown {+ return fieldPath+ .split('.')+ .reduce<unknown>(+ (node, key) => (node as Record<string, unknown> | undefined)?.[key],+ writtenDraft(deps).overrides,+ );+}+function createHandlers(overrides = {}) {const deps = {listAllConfigs: jest.fn().mockResolvedValue([]),findConfigByPrincipal: jest.fn().mockResolvedValue(null),- upsertConfig: jest.fn().mockResolvedValue({- _id: 'c1',- principalType: 'role',- principalId: 'admin',- overrides: {},- configVersion: 1,- }),- patchConfigFields: jest- .fn()- .mockResolvedValue({ _id: 'c1', overrides: { registration: { enabled: false } } }),+ writeConfigDocument: jest.fn(+ async (principalType: string, principalId: string, draft: ConfigDraft, expected: string) =>+ writtenDocument(principalType, principalId, draft, expected),+ ),tombstoneConfigField: jest.fn().mockResolvedValue({ _id: 'c1', tombstones: ['mcpServers.github'] }),@@ -158,7 +198,7 @@ describe('createAdminConfigHandlers', () => {await handlers.getConfig(req, res);expect(res.statusCode).toBe(200);- expect(res.body!.config).toEqual(config);+ expect(res.body!.config).toEqual({ ...config, revision: 'c1:0' });});it('returns 400 for invalid principalType', async () => {@@ -373,9 +413,7 @@ describe('createAdminConfigHandlers', () => {describe('upsertConfigOverrides', () => {it('returns 201 when creating a new config (configVersion === 1)', async () => {- const { handlers } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- });+ const { handlers } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: { overrides: { interface: { modelSelect: false } } },@@ -389,7 +427,9 @@ describe('createAdminConfigHandlers', () => {it('returns 200 when updating an existing config (configVersion > 1)', async () => {const { handlers } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 5 }),+ findConfigByPrincipal: jest+ .fn()+ .mockResolvedValue({ _id: 'c1', configVersion: 5, overrides: {}, tombstones: [] }),});const req = mockReq({params: { principalType: 'role', principalId: 'admin' },@@ -435,7 +475,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body).toEqual({error: 'Process-backed MCP servers can only be configured in librechat.yaml',});- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects Langfuse header overrides, which cannot be encrypted at rest', async () => {@@ -456,7 +496,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body).toEqual({error: 'Langfuse request headers can only be configured in librechat.yaml',});- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it.each([@@ -479,7 +519,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body).toEqual({error: 'Langfuse request headers can only be configured in librechat.yaml',});- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects process-backed MCP servers supplied through the runtime config alias', async () => {@@ -499,13 +539,11 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(400);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('strips permission fields from interface overrides but keeps UI fields', async () => {- const { handlers, deps } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: {@@ -519,14 +557,12 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];+ const savedOverrides = writtenDraft(deps).overrides;expect(savedOverrides.interface).toEqual({ modelSelect: false });});it('collapses an explicit schedules disable to the boolean form in overrides', async () => {- const { handlers, deps } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: {@@ -538,14 +574,12 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];+ const savedOverrides = writtenDraft(deps).overrides;expect(savedOverrides.interface).toEqual({ schedules: false });});it('preserves skillSync sections in admin overrides', async () => {- const { handlers, deps } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: {@@ -560,7 +594,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];+ const savedOverrides = writtenDraft(deps).overrides;expect(savedOverrides.skillSync).toEqual({ github: { enabled: true } });expect(savedOverrides.interface).toEqual({ modelSelect: false });});@@ -583,8 +617,11 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(200);- expect(res.body).toEqual({ message: 'No actionable override sections provided' });- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(res.body).toEqual({+ message: 'No actionable override sections provided',+ revision: null,+ });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects a dotted section name instead of reading it as a path', async () => {@@ -610,7 +647,7 @@ describe('createAdminConfigHandlers', () => {{ path: 'langfuse.secretKey', segments: ['langfuse.secretKey'], code: 'dotted_key' },],});- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it.each([@@ -631,7 +668,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(403);expect(res.body).toEqual({ error: 'Insufficient permissions' });- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('preserves stored Langfuse settings during a full base-config replacement', async () => {@@ -646,13 +683,9 @@ describe('createAdminConfigHandlers', () => {const { handlers, deps } = createHandlers({findConfigByPrincipal: jest.fn().mockResolvedValue({_id: 'c1',+ configVersion: 1,overrides: { langfuse: storedLangfuse },}),- upsertConfig: jest.fn(async (_type, _id, _model, overrides) => ({- _id: 'c1',- configVersion: 2,- overrides,- })),});const req = mockReq({params: { principalType: 'role', principalId: '__base__' },@@ -672,7 +705,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(200);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];+ const savedOverrides = writtenDraft(deps).overrides;expect(savedOverrides).toEqual({interface: { modelSelect: false },langfuse: storedLangfuse,@@ -680,13 +713,7 @@ describe('createAdminConfigHandlers', () => {});it('encrypts custom endpoint API keys on full override writes and redacts responses', async () => {- const { handlers, deps } = createHandlers({- upsertConfig: jest.fn(async (_type, _id, _model, overrides) => ({- _id: 'c1',- configVersion: 1,- overrides,- })),- });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: {@@ -709,8 +736,10 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];- const [saved, envRef] = savedOverrides.endpoints.custom as Array<Record<string, string>>;+ const savedOverrides = writtenDraft(deps).overrides;+ const [saved, envRef] = (+ savedOverrides.endpoints as { custom: Array<Record<string, string>> }+ ).custom;expect(saved.apiKey).toBe('v3:test:sk-or-secret-key');expect(saved.apiKeyPreview).toBe('...-key');expect(envRef.apiKey).toBe('${OPENROUTER_KEY}');@@ -740,12 +769,10 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(400);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('preserves UI sub-keys in composite permission fields like mcpServers', async () => {- const { handlers, deps } = createHandlers({- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: {@@ -766,7 +793,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- const savedOverrides = deps.upsertConfig.mock.calls[0][3];+ const savedOverrides = writtenDraft(deps).overrides;const mcp = (savedOverrides as Record<string, unknown>).interface as Record<string, unknown>;expect((mcp.mcpServers as Record<string, unknown>).placeholder).toBe('Search MCP...');expect((mcp.mcpServers as Record<string, unknown>).trustCheckbox).toEqual({ label: 'Trust' });@@ -790,7 +817,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body!.message).toBeDefined();- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('returns 200 with message when only permission fields in interface', async () => {@@ -805,7 +832,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body!.message).toBeDefined();- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});});@@ -823,9 +850,11 @@ describe('createAdminConfigHandlers', () => {expect(deps.unsetConfigField).toHaveBeenCalledWith('role','admin',- 'interface.modelSelect',- undefined,+ ['interface.modelSelect'],undefined,+ {+ expectedRevision: undefined,+ },);});@@ -843,9 +872,11 @@ describe('createAdminConfigHandlers', () => {expect(deps.unsetConfigField).toHaveBeenCalledWith('role','admin',- 'interface.mcpServers.placeholder',- undefined,+ ['interface.mcpServers.placeholder'],undefined,+ {+ expectedRevision: undefined,+ },);});@@ -908,9 +939,11 @@ describe('createAdminConfigHandlers', () => {expect(deps.unsetConfigField).toHaveBeenCalledWith('role','admin',- 'skillSync.github.enabled',- undefined,+ ['skillSync.github.enabled'],undefined,+ {+ expectedRevision: undefined,+ },);});@@ -928,9 +961,11 @@ describe('createAdminConfigHandlers', () => {expect(deps.unsetConfigField).toHaveBeenCalledWith('role','admin',- 'interface.modelSelect',- undefined,+ ['interface.modelSelect'],undefined,+ {+ expectedRevision: undefined,+ },);});@@ -945,7 +980,7 @@ describe('createAdminConfigHandlers', () => {await handlers.deleteConfigField(req, res);expect(res.statusCode).toBe(200);- expect(res.body).toEqual({ message: 'No actionable field path provided' });+ expect(res.body).toEqual({ message: 'No actionable field path provided', revision: null });expect(deps.unsetConfigField).not.toHaveBeenCalled();});@@ -1007,33 +1042,47 @@ describe('createAdminConfigHandlers', () => {'role','admin',expect.anything(),- 'mcpServers.github',- 10,+ ['mcpServers.github'],undefined,undefined,+ { expectedRevision: undefined },);});- it('uses the existing config priority when priority is omitted', async () => {- const { handlers, deps } = createHandlers({- findConfigByPrincipal: jest.fn().mockResolvedValue({ _id: 'c1', priority: 42 }),+ it('lets the store keep the existing priority when priority is omitted', async () => {+ const { handlers, deps } = createHandlers();+ const req = mockReq({+ params: { principalType: 'role', principalId: 'admin' },+ body: { fieldPath: 'mcpServers.github', priority: 42 },});+ const res = mockRes();++ await handlers.tombstoneConfigField(req, res);++ expect(deps.tombstoneConfigField.mock.calls[0][4]).toBe(42);+ expect(deps.findConfigByPrincipal).not.toHaveBeenCalled();+ });++ it('suppresses a secret and its preview companion in one write', async () => {+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },- body: { fieldPath: 'mcpServers.github' },+ body: { fieldPath: 'ocr.apiKey', expectedRevision: '64b000000000000000000001:3' },});const res = mockRes();await handlers.tombstoneConfigField(req, res);+ expect(res.statusCode).toBe(200);+ expect(deps.tombstoneConfigField).toHaveBeenCalledTimes(1);expect(deps.tombstoneConfigField).toHaveBeenCalledWith('role','admin',expect.anything(),- 'mcpServers.github',- 42,+ ['ocr.apiKey', 'ocr.apiKeyPreview'],undefined,undefined,+ { expectedRevision: '64b000000000000000000001:3' },);});@@ -1048,7 +1097,7 @@ describe('createAdminConfigHandlers', () => {await handlers.tombstoneConfigField(req, res);expect(res.statusCode).toBe(200);- expect(res.body).toEqual({ message: 'No actionable field path provided' });+ expect(res.body).toEqual({ message: 'No actionable field path provided', revision: null });expect(deps.tombstoneConfigField).not.toHaveBeenCalled();});@@ -1143,9 +1192,8 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const patchedFields = deps.patchConfigFields.mock.calls[0][3];- expect(patchedFields['interface.modelSelect']).toBe(false);- expect(patchedFields['interface.prompts']).toBeUndefined();+ expect(writtenField(deps, 'interface.modelSelect')).toBe(false);+ expect(writtenField(deps, 'interface.prompts')).toBeUndefined();});/** `use` is both a permission bit and the runtime disable for dual-purpose fields.@@ -1164,8 +1212,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const patchedFields = deps.patchConfigFields.mock.calls[0][3];- expect(patchedFields['interface.schedules']).toBe(false);+ expect(writtenField(deps, 'interface.schedules')).toBe(false);});it('keeps a schedules object that only narrows limits', async () => {@@ -1181,8 +1228,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const patchedFields = deps.patchConfigFields.mock.calls[0][3];- expect(patchedFields['interface.schedules']).toEqual({ maxPerUser: 2 });+ expect(writtenField(deps, 'interface.schedules')).toEqual({ maxPerUser: 2 });});it('preserves skillSync field entries in patches', async () => {@@ -1201,9 +1247,8 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const patchedFields = deps.patchConfigFields.mock.calls[0][3];- expect(patchedFields['skillSync.github.enabled']).toBe(true);- expect(patchedFields['interface.modelSelect']).toBe(false);+ expect(writtenField(deps, 'skillSync.github.enabled')).toBe(true);+ expect(writtenField(deps, 'interface.modelSelect')).toBe(false);});it('rejects process-backed MCP server field patches', async () => {@@ -1222,7 +1267,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body).toEqual({error: 'Process-backed MCP servers can only be configured in librechat.yaml',});- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects Langfuse header field patches, including a single header path', async () => {@@ -1243,7 +1288,7 @@ describe('createAdminConfigHandlers', () => {error: 'Langfuse request headers can only be configured in librechat.yaml',});}- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects process-backed MCP field patches through the runtime config alias', async () => {@@ -1259,7 +1304,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects array-valued Langfuse secret ancestors', async () => {@@ -1280,7 +1325,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('does not allow tenant-wide Langfuse patches through the generic config API', async () => {@@ -1296,8 +1341,8 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- expect(res.body).toEqual({ message: 'No actionable field entries provided' });- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(res.body).toEqual({ message: 'No actionable field entries provided', revision: null });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects direct display secret key patch entries', async () => {@@ -1313,7 +1358,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects encrypted Langfuse secret values on patch entries', async () => {@@ -1329,7 +1374,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects patch entries below protected Langfuse secret paths', async () => {@@ -1345,7 +1390,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects patch entries below protected Langfuse secretKeyPreview paths', async () => {@@ -1361,7 +1406,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(400);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('blocks peoplePicker permission sub-key paths', async () => {@@ -1378,7 +1423,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body!.message).toBeDefined();- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('allows mcpServers UI sub-key paths but blocks permission sub-key paths', async () => {@@ -1397,9 +1442,8 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const patchedFields = deps.patchConfigFields.mock.calls[0][3];- expect(patchedFields['interface.mcpServers.placeholder']).toBe('Search...');- expect(patchedFields['interface.mcpServers.use']).toBeUndefined();+ expect(writtenField(deps, 'interface.mcpServers.placeholder')).toBe('Search...');+ expect(writtenField(deps, 'interface.mcpServers.use')).toBeUndefined();});it('returns 200 with message when all entries are permission fields', async () => {@@ -1414,7 +1458,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body!.message).toBeDefined();- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('returns 401 when unauthenticated even if all entries are permission fields', async () => {@@ -1480,7 +1524,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.patchConfigFields.mock.calls[0];+ const priorityArg = writtenDraft(deps).priority;expect(priorityArg).toBe(7);});@@ -1501,7 +1545,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.patchConfigFields.mock.calls[0];+ const priorityArg = writtenDraft(deps).priority;expect(priorityArg).toBe(10);});@@ -1521,7 +1565,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.patchConfigFields.mock.calls[0];+ const priorityArg = writtenDraft(deps).priority;expect(priorityArg).toBe(999);/** Read once to validate the write on top of the stored fields, not for its priority. */expect(deps.findConfigByPrincipal).toHaveBeenCalledTimes(1);@@ -1543,7 +1587,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.patchConfigFields.mock.calls[0];+ const priorityArg = writtenDraft(deps).priority;expect(priorityArg).toBe(0);});@@ -1566,36 +1610,16 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.patchConfigFields.mock.calls[0];+ const priorityArg = writtenDraft(deps).priority;expect(priorityArg).toBe(0);});});describe('tombstoneConfigField: section-scoped priority preservation', () => {+ /** The store keeps the stored priority (or the default on create) when none is passed. */it('ignores request-supplied priority when caller lacks broad manage:configs', async () => {const { handlers, deps } = createHandlers({hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),- findConfigByPrincipal: jest- .fn()- .mockResolvedValue({ _id: 'c1', priority: 7, overrides: {} }),- });- const req = mockReq({- params: { principalType: 'role', principalId: 'admin' },- body: { fieldPath: 'memory.context', priority: 999 },- });- const res = mockRes();-- await handlers.tombstoneConfigField(req, res);-- expect(res.statusCode).toBe(200);- const [, , , , priorityArg] = deps.tombstoneConfigField.mock.calls[0];- expect(priorityArg).toBe(7);- });-- it('falls back to default priority when no existing doc and caller lacks broad manage', async () => {- const { handlers, deps } = createHandlers({- hasConfigCapability: jest.fn(async (_user, section) => section === 'memory'),- findConfigByPrincipal: jest.fn().mockResolvedValue(null),});const req = mockReq({params: { principalType: 'role', principalId: 'admin' },@@ -1607,7 +1631,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);const [, , , , priorityArg] = deps.tombstoneConfigField.mock.calls[0];- expect(priorityArg).toBe(10);+ expect(priorityArg).toBeUndefined();});it('honors request-supplied priority when caller holds broad manage:configs', async () => {@@ -1649,14 +1673,7 @@ describe('createAdminConfigHandlers', () => {describe('upsertConfigOverrides — empty-overrides scope creation', () => {it('creates config document when overrides is empty but priority is provided', async () => {- const upsertConfig = jest.fn().mockResolvedValue({- _id: 'c1',- principalType: 'role',- principalId: 'admin',- overrides: {},- configVersion: 1,- });- const { handlers } = createHandlers({ upsertConfig });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: { overrides: {}, priority: 5 },@@ -1666,22 +1683,18 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- expect(res.body).toHaveProperty('config');expect(res.body?.config).toHaveProperty('_id', 'c1');- expect(upsertConfig).toHaveBeenCalledWith(+ expect(res.body?.config).toHaveProperty('revision', 'c1:1');+ expect(deps.writeConfigDocument).toHaveBeenCalledWith('role','admin',- expect.anything(),- {},- 5,- undefined,- expect.objectContaining({ expectEmpty: expect.any(Boolean) }),+ { principalModel: 'Role', priority: 5, overrides: {}, tombstones: [], isActive: true },+ 'absent',);});it('returns no-op message when overrides is empty and no priority is provided', async () => {- const upsertConfig = jest.fn().mockResolvedValue(null);- const { handlers } = createHandlers({ upsertConfig });+ const { handlers, deps } = createHandlers();const req = mockReq({params: { principalType: 'role', principalId: 'admin' },body: { overrides: {} },@@ -1692,7 +1705,7 @@ describe('createAdminConfigHandlers', () => {expect(res.statusCode).toBe(200);expect(res.body).toHaveProperty('message', 'No actionable override sections provided');- expect(upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('calls general manage check exactly once when overrides is empty with priority', async () => {@@ -1807,21 +1820,23 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- expect(deps.upsertConfig).toHaveBeenCalledWith(+ expect(deps.writeConfigDocument).toHaveBeenCalledWith('role','admin',- expect.anything(),- {},- 10,- undefined,- { expectEmpty: true, preservePriority: true },+ { principalModel: 'Role', priority: 10, overrides: {}, tombstones: [], isActive: true },+ 'absent',);});- it('requests atomic priority preservation for ASSIGN_CONFIGS-only empty-overrides upsert', async () => {- const findConfigByPrincipal = jest- .fn()- .mockResolvedValue({ _id: 'c1', priority: 7, overrides: {} });+ it('keeps the stored priority and reactivates an empty profile for an ASSIGN_CONFIGS-only caller', async () => {+ const findConfigByPrincipal = jest.fn().mockResolvedValue({+ _id: 'c1',+ priority: 7,+ configVersion: 2,+ isActive: false,+ overrides: { balance: {} },+ tombstones: [],+ });const { handlers, deps } = createHandlers({hasConfigCapability: jest.fn().mockResolvedValue(false),hasCapability: jest.fn().mockResolvedValue(true),@@ -1835,17 +1850,13 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);- expect(res.statusCode).toBe(201);- expect(deps.upsertConfig).toHaveBeenCalledWith(+ expect(res.statusCode).toBe(200);+ expect(deps.writeConfigDocument).toHaveBeenCalledWith('role','admin',- expect.anything(),- {},- 10,- undefined,- { expectEmpty: true, preservePriority: true },+ { principalModel: 'Role', priority: 7, overrides: {}, tombstones: [], isActive: true },+ 'c1:2',);- expect(findConfigByPrincipal).not.toHaveBeenCalled();});it('rejects non-empty overrides for ASSIGN_CONFIGS-only caller', async () => {@@ -1862,7 +1873,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects empty-overrides scope creation when caller has neither grant', async () => {@@ -1879,7 +1890,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});});@@ -1964,14 +1975,8 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- expect(deps.upsertConfig).toHaveBeenCalledWith(- 'role',- 'admin',- expect.anything(),- {},- 10,- undefined,- { expectEmpty: true, preservePriority: true },+ expect(writtenDraft(deps)).toEqual(+ expect.objectContaining({ overrides: {}, priority: 10, isActive: true }),);});@@ -1989,7 +1994,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('queries hasCapability with the principalType-parameterized form', async () => {@@ -2026,7 +2031,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('delete against __base__ returns 403 for assign-only caller', async () => {@@ -2075,7 +2080,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- expect(deps.upsertConfig).toHaveBeenCalled();+ expect(deps.writeConfigDocument).toHaveBeenCalled();});it('patch against __base__ returns 403 for a section-scoped manager', async () => {@@ -2091,7 +2096,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(403);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('tombstone against __base__ returns 403 for a section-scoped manager', async () => {@@ -2139,17 +2144,20 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- expect(deps.patchConfigFields).toHaveBeenCalled();+ expect(deps.writeConfigDocument).toHaveBeenCalled();});});describe('scope-lifecycle: atomic empty-state guard for assign-only callers', () => {- it('empty-overrides upsert is rejected when atomic filter mismatches (existing doc not empty)', async () => {+ it('empty-overrides upsert is rejected when the stored profile is not empty', async () => {const { handlers, deps } = createHandlers({hasConfigCapability: jest.fn().mockResolvedValue(false),hasCapability: jest.fn().mockResolvedValue(true),- upsertConfig: jest.fn(async (_pt, _pi, _pm, _o, _p, _session, opts) => {- return opts?.expectEmpty ? null : { _id: 'c1', configVersion: 1 };+ findConfigByPrincipal: jest.fn().mockResolvedValue({+ _id: 'c1',+ configVersion: 3,+ overrides: { memory: { disabled: true } },+ tombstones: [],}),});const req = mockReq({@@ -2161,15 +2169,32 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).toHaveBeenCalledWith(- expect.anything(),- expect.anything(),- expect.anything(),- expect.anything(),- expect.anything(),- undefined,- { expectEmpty: true, preservePriority: true },+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ it('empty-overrides upsert is rejected when the stored profile only holds tombstones', async () => {+ const { handlers, deps } = createHandlers({+ hasConfigCapability: jest.fn().mockResolvedValue(false),+ hasCapability: jest.fn().mockResolvedValue(true),+ findConfigByPrincipal: jest.fn().mockResolvedValue({+ _id: 'c1',+ configVersion: 3,+ overrides: {},+ tombstones: ['mcpServers.github'],+ }),+ });+ const res = mockRes();++ await handlers.upsertConfigOverrides(+ mockReq({+ params: { principalType: 'role', principalId: 'admin' },+ body: { overrides: {}, priority: 5 },+ }),+ res,);++ expect(res.statusCode).toBe(403);+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('delete is rejected with 403 when atomic filter mismatches and doc still exists', async () => {@@ -2293,8 +2318,7 @@ describe('createAdminConfigHandlers', () => {const deps = {listAllConfigs: jest.fn().mockResolvedValue([]),findConfigByPrincipal: jest.fn().mockResolvedValue(null),- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1 }),- patchConfigFields: jest.fn(),+ writeConfigDocument: jest.fn(),tombstoneConfigField: jest.fn(),unsetConfigField: jest.fn(),deleteConfig: jest.fn().mockResolvedValue({ _id: 'c1' }),@@ -2314,7 +2338,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(403);- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});});@@ -2570,7 +2594,7 @@ describe('createAdminConfigHandlers', () => {},],});- expect(deps.upsertConfig).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('validates a whole-document write on the base its retained tombstones leave', async () => {@@ -2589,9 +2613,12 @@ describe('createAdminConfigHandlers', () => {const tombstoned = createHandlers({getAppConfig: jest.fn().mockResolvedValue(base),- findConfigByPrincipal: jest- .fn()- .mockResolvedValue({ overrides: {}, tombstones: ['cloudfront.imageSigning'] }),+ findConfigByPrincipal: jest.fn().mockResolvedValue({+ _id: 'c1',+ configVersion: 1,+ overrides: {},+ tombstones: ['cloudfront.imageSigning'],+ }),});const tombstonedRes = mockRes();await tombstoned.handlers.upsertConfigOverrides(mockReq({ params, body }), tombstonedRes);@@ -2599,7 +2626,7 @@ describe('createAdminConfigHandlers', () => {expect(tombstonedRes.body?.issues).toEqual([expect.objectContaining({ path: 'cloudfront.requireSignedAccess' }),]);- expect(tombstoned.deps.upsertConfig).not.toHaveBeenCalled();+ expect(tombstoned.deps.writeConfigDocument).not.toHaveBeenCalled();});it('accepts a partial section whose provided fields are valid', async () => {@@ -2619,7 +2646,7 @@ describe('createAdminConfigHandlers', () => {await handlers.upsertConfigOverrides(req, res);expect(res.statusCode).toBe(201);- expect(deps.upsertConfig).toHaveBeenCalledTimes(1);+ expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);});it('rejects a field patch with an invalid value and writes no entry', async () => {@@ -2641,7 +2668,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body?.issues).toEqual([expect.objectContaining({ path: 'registration.oauthStateTtlMs' }),]);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('validates an object patch as a partial of the addressed section', async () => {@@ -2658,7 +2685,7 @@ describe('createAdminConfigHandlers', () => {expect(res.body?.issues).toEqual([expect.objectContaining({ path: 'interface.schedules.maxPerUser' }),]);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('rejects a patch that addresses a custom endpoint by index', async () => {@@ -2679,7 +2706,7 @@ describe('createAdminConfigHandlers', () => {code: 'indexed_merge_key_write',},]);- expect(deps.patchConfigFields).not.toHaveBeenCalled();+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();});it('accepts a secret field cleared with a non-string value', async () => {@@ -2693,7 +2720,7 @@ describe('createAdminConfigHandlers', () => {await handlers.patchConfigField(req, res);expect(res.statusCode).toBe(200);- expect(deps.patchConfigFields).toHaveBeenCalledTimes(1);+ expect(deps.writeConfigDocument).toHaveBeenCalledTimes(1);});});@@ -2701,39 +2728,59 @@ describe('createAdminConfigHandlers', () => {const target = { type: 'config', id: 'role:editor', name: 'role:editor' };const params = { principalType: 'role', principalId: 'editor' };- it('records a partial secret-field delete when the preview write fails', async () => {+ it('removes a secret and its preview in one write and records one entry', async () => {const recordAuditEntry = jest.fn().mockResolvedValue(undefined);const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);- const { handlers } = createHandlers({- recordAuditEntry,- invalidateConfigCaches,- unsetConfigField: jest- .fn()- .mockResolvedValueOnce({ _id: 'c1', overrides: {} })- .mockRejectedValueOnce(new Error('preview write failed')),- });+ const { handlers, deps } = createHandlers({ recordAuditEntry, invalidateConfigCaches });const req = mockReq({ params, query: { fieldPath: 'ocr.apiKey' } });const res = mockRes();await handlers.deleteConfigField(req, res);- expect(res.statusCode).toBe(500);- expect(invalidateConfigCaches).toHaveBeenCalled();+ expect(res.statusCode).toBe(200);+ expect(deps.unsetConfigField).toHaveBeenCalledTimes(1);+ expect(deps.unsetConfigField).toHaveBeenCalledWith(+ 'role',+ 'editor',+ ['ocr.apiKey', 'ocr.apiKeyPreview'],+ undefined,+ { expectedRevision: undefined },+ );+ expect(invalidateConfigCaches).toHaveBeenCalledTimes(1);+ expect(recordAuditEntry).toHaveBeenCalledTimes(1);expect(recordAuditEntry).toHaveBeenCalledWith(expect.objectContaining({action: 'config.updated',target,- metadata: { operation: 'unset', fieldPath: 'ocr.apiKey', partial: true },+ metadata: { operation: 'unset', fieldPath: 'ocr.apiKey' },}),);});- it('records config.created for a new override document', async () => {+ it('records nothing and invalidates nothing when the write fails', async () => {const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const invalidateConfigCaches = jest.fn().mockResolvedValue(undefined);const { handlers } = createHandlers({recordAuditEntry,- upsertConfig: jest.fn().mockResolvedValue({ _id: 'c1', configVersion: 1, priority: 10 }),+ invalidateConfigCaches,+ unsetConfigField: jest.fn().mockRejectedValue(new Error('write failed')),});+ const res = mockRes();++ await handlers.deleteConfigField(+ mockReq({ params, query: { fieldPath: 'ocr.apiKey' } }),+ res,+ );++ expect(res.statusCode).toBe(500);+ expect(res.body).toEqual({ error: 'Failed to delete config field' });+ expect(invalidateConfigCaches).not.toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });++ it('records config.created for a new override document', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers } = createHandlers({ recordAuditEntry });const req = mockReq({params,body: { overrides: { interface: { modelSelect: false } } },@@ -2894,4 +2941,511 @@ describe('createAdminConfigHandlers', () => {expect(recordAuditEntry).not.toHaveBeenCalled();});});++ describe('revision preconditions', () => {+ const params = { principalType: 'role', principalId: 'editor' };+ const stored = {+ _id: '64b000000000000000000001',+ principalType: 'role',+ principalId: 'editor',+ priority: 10,+ configVersion: 4,+ isActive: true,+ overrides: { interface: { customWelcome: 'stored' } },+ tombstones: [],+ };+ const storedRevision = '64b000000000000000000001:4';++ it.each([+ ['upsertConfigOverrides', { body: { overrides: {}, priority: 1, expectedRevision: 'v4' } }],+ [+ 'patchConfigField',+ { body: { entries: [{ fieldPath: 'a.b', value: 1 }], expectedRevision: 4 } },+ ],+ ['tombstoneConfigField', { body: { fieldPath: 'memory', expectedRevision: 'abc:-1' } }],+ ['deleteConfigField', { query: { fieldPath: 'memory', expectedRevision: '' } }],+ ['deleteConfigOverrides', { query: { expectedRevision: 'abc' } }],+ ['toggleConfig', { body: { isActive: false, expectedRevision: { $ne: null } } }],+ ] as const)('%s rejects a malformed expectedRevision with 400', async (name, overrides) => {+ const { handlers, deps } = createHandlers();+ const res = mockRes();++ await handlers[name](mockReq({ params, ...overrides }), res);++ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'expectedRevision must be "absent" or a revision returned by the config API',+ code: 'INVALID_EXPECTED_REVISION',+ });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ it('returns 409 with the stored revision when the precondition does not match', async () => {+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({+ params,+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'mine' }],+ expectedRevision: '64b000000000000000000001:3',+ },+ }),+ res,+ );++ expect(res.statusCode).toBe(409);+ expect(res.body).toEqual({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: storedRevision,+ });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ it('returns 409 with a null revision for a create-only write when the profile exists, and for a revision of a missing one', async () => {+ const exists = createHandlers({ findConfigByPrincipal: jest.fn().mockResolvedValue(stored) });+ const existsRes = mockRes();+ await exists.handlers.upsertConfigOverrides(+ mockReq({ params, body: { overrides: {}, priority: 5, expectedRevision: 'absent' } }),+ existsRes,+ );+ expect(existsRes.statusCode).toBe(409);+ expect(existsRes.body?.currentRevision).toBe(storedRevision);++ const missing = createHandlers();+ const missingRes = mockRes();+ await missing.handlers.upsertConfigOverrides(+ mockReq({ params, body: { overrides: {}, priority: 5, expectedRevision: storedRevision } }),+ missingRes,+ );+ expect(missingRes.statusCode).toBe(409);+ expect(missingRes.body?.currentRevision).toBeNull();+ expect(missing.deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ it('writes on the precondition the client sent and returns the new revision', async () => {+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({+ params,+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'mine' }],+ expectedRevision: storedRevision,+ },+ }),+ res,+ );++ expect(res.statusCode).toBe(200);+ expect(deps.writeConfigDocument).toHaveBeenCalledWith(+ 'role',+ 'editor',+ expect.objectContaining({ overrides: { interface: { customWelcome: 'mine' } } }),+ storedRevision,+ );+ expect((res.body?.config as { revision: string }).revision).toBe('c1:5');+ });++ it('re-reads and re-validates when a write without a precondition loses a race', async () => {+ const rotated = { ...stored, configVersion: 5, overrides: { interface: { a: 1 } } };+ const findConfigByPrincipal = jest+ .fn()+ .mockResolvedValueOnce(stored)+ .mockResolvedValueOnce(rotated);+ const writeConfigDocument = jest+ .fn()+ .mockRejectedValueOnce(new ConfigRevisionConflictError())+ .mockImplementation(async (type, id, draft, expected) =>+ writtenDocument(type, id, draft, expected),+ );+ const { handlers } = createHandlers({ findConfigByPrincipal, writeConfigDocument });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({+ params,+ body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'x' }] },+ }),+ res,+ );++ expect(res.statusCode).toBe(200);+ expect(findConfigByPrincipal).toHaveBeenCalledTimes(2);+ expect(writeConfigDocument).toHaveBeenCalledTimes(2);+ expect(writeConfigDocument.mock.calls[1][2].overrides).toEqual({+ interface: { a: 1, customWelcome: 'x' },+ });+ expect(writeConfigDocument.mock.calls[1][3]).toBe('64b000000000000000000001:5');+ });++ it('answers 409 once the retry budget is spent', async () => {+ const findConfigByPrincipal = jest.fn().mockResolvedValue(stored);+ const writeConfigDocument = jest.fn().mockRejectedValue(new ConfigRevisionConflictError());+ const { handlers } = createHandlers({ findConfigByPrincipal, writeConfigDocument });+ const res = mockRes();++ await handlers.upsertConfigOverrides(+ mockReq({ params, body: { overrides: { interface: { customWelcome: 'x' } } } }),+ res,+ );++ expect(res.statusCode).toBe(409);+ expect(res.body?.code).toBe('CONFIG_VERSION_CONFLICT');+ expect(writeConfigDocument).toHaveBeenCalledTimes(3);+ expect(res.body?.currentRevision).toBe(storedRevision);+ });++ it('passes the precondition through to tombstone, field delete, delete and toggle', async () => {+ const { handlers, deps } = createHandlers();++ await handlers.tombstoneConfigField(+ mockReq({ params, body: { fieldPath: 'memory', expectedRevision: storedRevision } }),+ mockRes(),+ );+ await handlers.deleteConfigField(+ mockReq({ params, query: { fieldPath: 'memory', expectedRevision: storedRevision } }),+ mockRes(),+ );+ await handlers.deleteConfigOverrides(+ mockReq({ params, query: { expectedRevision: storedRevision } }),+ mockRes(),+ );+ await handlers.toggleConfig(+ mockReq({ params, body: { isActive: false, expectedRevision: storedRevision } }),+ mockRes(),+ );++ const options = { expectedRevision: storedRevision };+ expect(deps.tombstoneConfigField.mock.calls[0][6]).toEqual(options);+ expect(deps.unsetConfigField.mock.calls[0][4]).toEqual(options);+ expect(deps.deleteConfig.mock.calls[0][3]).toEqual({ expectEmpty: false, ...options });+ expect(deps.toggleConfigActiveTracked.mock.calls[0][3]).toEqual({+ expectEmpty: false,+ ...options,+ });+ });++ it.each([+ ['tombstoneConfigField', { body: { fieldPath: 'memory' } }, 'tombstoneConfigField'],+ ['deleteConfigField', { query: { fieldPath: 'memory' } }, 'unsetConfigField'],+ ['deleteConfigOverrides', {}, 'deleteConfig'],+ ['toggleConfig', { body: { isActive: true } }, 'toggleConfigActiveTracked'],+ ] as const)('%s maps a store conflict to 409', async (name, overrides, method) => {+ const { handlers } = createHandlers({+ [method]: jest.fn().mockRejectedValue(new ConfigRevisionConflictError(storedRevision)),+ });+ const res = mockRes();++ await handlers[name](mockReq({ params, ...overrides }), res);++ expect(res.statusCode).toBe(409);+ expect(res.body?.currentRevision).toBe(storedRevision);+ });++ it('reports the stored revision on a write with nothing to apply', async () => {+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({ params, body: { entries: [{ fieldPath: 'interface.prompts', value: false }] } }),+ res,+ );++ expect(res.statusCode).toBe(200);+ expect(res.body).toEqual({+ message: 'No actionable field entries provided',+ revision: storedRevision,+ });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ describe('on a write with nothing to apply', () => {+ const noops = [+ ['upsertConfigOverrides', 'body', { overrides: { filters: {} } }],+ [+ 'patchConfigField',+ 'body',+ { entries: [{ fieldPath: 'interface.prompts', value: false }] },+ ],+ ['tombstoneConfigField', 'body', { fieldPath: 'interface.prompts' }],+ ['deleteConfigField', 'query', { fieldPath: 'interface.prompts' }],+ ] as const;++ it.each(noops)(+ '%s answers 409 when the stored document is not at expectedRevision',+ async (name, location, input) => {+ const exists = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const createOnly = mockRes();+ await exists.handlers[name](+ mockReq({ params, [location]: { ...input, expectedRevision: 'absent' } }),+ createOnly,+ );+ expect(createOnly.statusCode).toBe(409);+ expect(createOnly.body).toEqual({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: storedRevision,+ });++ const stale = mockRes();+ await exists.handlers[name](+ mockReq({+ params,+ [location]: { ...input, expectedRevision: '64b000000000000000000001:3' },+ }),+ stale,+ );+ expect(stale.statusCode).toBe(409);+ expect(stale.body?.currentRevision).toBe(storedRevision);++ const missing = createHandlers();+ const gone = mockRes();+ await missing.handlers[name](+ mockReq({ params, [location]: { ...input, expectedRevision: storedRevision } }),+ gone,+ );+ expect(gone.statusCode).toBe(409);+ expect(gone.body?.currentRevision).toBeNull();+ for (const deps of [exists.deps, missing.deps]) {+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ expect(deps.tombstoneConfigField).not.toHaveBeenCalled();+ expect(deps.unsetConfigField).not.toHaveBeenCalled();+ }+ },+ );++ it.each(noops)(+ '%s answers 200 with the revision when the precondition holds',+ async (name, location, input) => {+ const exists = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const matched = mockRes();+ await exists.handlers[name](+ mockReq({ params, [location]: { ...input, expectedRevision: storedRevision } }),+ matched,+ );+ expect(matched.statusCode).toBe(200);+ expect(matched.body?.revision).toBe(storedRevision);++ const missing = createHandlers();+ const absent = mockRes();+ await missing.handlers[name](+ mockReq({ params, [location]: { ...input, expectedRevision: 'absent' } }),+ absent,+ );+ expect(absent.statusCode).toBe(200);+ expect(absent.body?.revision).toBeNull();+ },+ );+ });++ it('returns revisions on reads', async () => {+ const { handlers } = createHandlers({+ listAllConfigs: jest.fn().mockResolvedValue([stored]),+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const listRes = mockRes();+ const getRes = mockRes();++ await handlers.listConfigs(mockReq(), listRes);+ await handlers.getConfig(mockReq({ params }), getRes);++ expect((listRes.body?.configs as Array<{ revision: string }>)[0].revision).toBe(+ storedRevision,+ );+ expect((getRes.body?.config as { revision: string }).revision).toBe(storedRevision);+ });+ });++ describe('write pipeline', () => {+ const params = { principalType: 'role', principalId: 'editor' };++ it('keeps an omitted custom endpoint key before validating, so a required secret can be omitted', async () => {+ const stored = {+ _id: '64b000000000000000000002',+ configVersion: 2,+ overrides: {+ endpoints: {+ custom: [+ {+ name: 'Private',+ apiKey: 'v3:test:sk-stored',+ apiKeyPreview: '...ored',+ baseURL: 'https://private.example.com/v1',+ models: { default: ['m'] },+ },+ ],+ },+ },+ tombstones: [],+ };+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const res = mockRes();++ await handlers.upsertConfigOverrides(+ mockReq({+ params,+ body: {+ overrides: {+ endpoints: {+ custom: [+ {+ name: 'Private',+ baseURL: 'https://private.example.com/v2',+ models: { default: ['m'] },+ },+ ],+ },+ },+ },+ }),+ res,+ );++ expect(res.statusCode).toBe(200);+ const [entry] = (+ writtenDraft(deps).overrides.endpoints as { custom: Array<Record<string, string>> }+ ).custom;+ expect(entry.apiKey).toBe('v3:test:sk-stored');+ expect(entry.baseURL).toBe('https://private.example.com/v2');+ /** Validation saw the document the write stores, with the kept secret in place. */+ const overrideCalls = jest.mocked(getConfigOverrideIssues).mock.calls;+ const validated = overrideCalls[overrideCalls.length - 1][0] as {+ endpoints: { custom: Array<Record<string, string>> };+ };+ expect(validated.endpoints.custom[0].apiKey).toBe('v3:test:sk-stored');+ });++ it('validates a patch with the secrets it omits already restored', async () => {+ const stored = {+ _id: '64b000000000000000000004',+ configVersion: 1,+ overrides: {+ speech: { tts: { openai: { apiKey: 'v3:test:sk-tts', apiKeyPreview: '...-tts' } } },+ },+ tombstones: [],+ };+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue(stored),+ });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({+ params,+ body: {+ entries: [+ { fieldPath: 'speech.tts.openai', value: { model: 'tts-1', voices: ['alloy'] } },+ ],+ },+ }),+ res,+ );++ expect(res.statusCode).toBe(200);+ const fieldCalls = jest.mocked(getConfigFieldIssues).mock.calls;+ const [validatedFields] = fieldCalls[fieldCalls.length - 1];+ expect(validatedFields).toEqual([+ {+ segments: ['speech', 'tts', 'openai'],+ value: {+ model: 'tts-1',+ voices: ['alloy'],+ apiKey: 'v3:test:sk-tts',+ apiKeyPreview: '...-tts',+ },+ },+ ]);+ expect(writtenField(deps, 'speech.tts.openai.apiKey')).toBe('v3:test:sk-tts');+ });++ it('rejects a patch the stored document cannot take with CONFIG_PATH_INVALID', async () => {+ const { handlers, deps } = createHandlers({+ findConfigByPrincipal: jest.fn().mockResolvedValue({+ _id: '64b000000000000000000003',+ configVersion: 1,+ overrides: { interface: { customWelcome: 'hi' } },+ tombstones: [],+ }),+ });+ const res = mockRes();++ await handlers.patchConfigField(+ mockReq({+ params,+ body: { entries: [{ fieldPath: 'interface.customWelcome.nested', value: 'x' }] },+ }),+ res,+ );++ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Config path cannot be applied to the stored config',+ code: 'CONFIG_PATH_INVALID',+ reason: 'scalar_parent',+ });+ expect(deps.writeConfigDocument).not.toHaveBeenCalled();+ });++ it('waits for cache invalidation before responding', async () => {+ let release: () => void = () => undefined;+ const invalidateConfigCaches = jest.fn(+ () => new Promise<void>((resolve) => (release = resolve)),+ );+ const { handlers } = createHandlers({ invalidateConfigCaches });+ const res = mockRes();++ const pending = handlers.patchConfigField(+ mockReq({+ params,+ body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'x' }] },+ }),+ res,+ );+ await new Promise((resolve) => setImmediate(resolve));++ expect(invalidateConfigCaches).toHaveBeenCalledTimes(1);+ expect(res.json).not.toHaveBeenCalled();+ release();+ await pending;+ expect(res.statusCode).toBe(200);+ });++ it('still answers 200 when invalidation fails after the write committed', async () => {+ const { handlers } = createHandlers({+ invalidateConfigCaches: jest.fn().mockRejectedValue(new Error('cache down')),+ });+ const res = mockRes();++ await handlers.toggleConfig(mockReq({ params, body: { isActive: false } }), res);++ expect(res.statusCode).toBe(200);+ });++ it('reads GET /base around the merged-config cache', async () => {+ const getAppConfig = jest.fn().mockResolvedValue({ interface: { modelSelect: true } });+ const { handlers } = createHandlers({ getAppConfig });++ await handlers.getBaseConfig(mockReq(), mockRes());++ expect(getAppConfig).toHaveBeenCalledWith(+ expect.objectContaining({ bypassOverrideCache: true }),+ );+ });+ });});diff --git a/packages/api/src/admin/config.store.spec.ts b/packages/api/src/admin/config.store.spec.tsnew file mode 100644index 0000000000..f9d9baf1f0--- /dev/null+++ b/packages/api/src/admin/config.store.spec.ts@@ -0,0 +1,667 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type { Response } from 'express';+import type { ServerRequest } from '~/types/http';++process.env.CREDS_KEY =+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';+process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';++type DataSchemas = typeof import('@librechat/data-schemas');+type Methods = ReturnType<DataSchemas['createMethods']>;+type AdminConfigHandlers = ReturnType<typeof import('./config').createAdminConfigHandlers>;+type AdminConfigDeps = Parameters<typeof import('./config').createAdminConfigHandlers>[0];++interface MockRes {+ statusCode: number;+ body: undefined | Record<string, unknown>;+ status: jest.Mock;+ json: jest.Mock;+}++let mongoServer: MongoMemoryServer;+let methods: Methods;+let decryptV3: DataSchemas['decryptV3'];+let maxPathDepth: DataSchemas['MAX_CONFIG_PATH_DEPTH'];+let createAdminConfigHandlers: typeof import('./config').createAdminConfigHandlers;++function mockReq(overrides: Record<string, unknown> = {}): ServerRequest {+ return {+ user: { id: 'u1', role: 'ADMIN', _id: { toString: () => 'u1' } },+ params: {},+ body: {},+ query: {},+ ...overrides,+ } as Partial<ServerRequest> as ServerRequest;+}++function mockRes(): Response & MockRes {+ const res: MockRes = {+ statusCode: 200,+ body: undefined,+ status: jest.fn((code: number) => {+ res.statusCode = code;+ return res;+ }),+ json: jest.fn((data: MockRes['body']) => {+ res.body = data;+ return res;+ }),+ };+ return res as Partial<Response> as Response & MockRes;+}++function createHandlers(overrides: Partial<AdminConfigDeps> = {}): AdminConfigHandlers {+ return createAdminConfigHandlers({+ listAllConfigs: methods.listAllConfigs,+ findConfigByPrincipal: methods.findConfigByPrincipal,+ writeConfigDocument: methods.writeConfigDocument,+ tombstoneConfigField: methods.tombstoneConfigField,+ unsetConfigField: methods.unsetConfigField,+ deleteConfig: methods.deleteConfig,+ toggleConfigActiveTracked: methods.toggleConfigActiveTracked,+ hasConfigCapability: async () => true,+ hasAnyConfigReadAccess: async () => true,+ hasCapability: async () => true,+ ...overrides,+ });+}++const raw = () => mongoose.connection.db!.collection('configs');++let counter = 0;+function nextParams(): { principalType: string; principalId: string } {+ counter += 1;+ return { principalType: 'role', principalId: `store-${counter}` };+}++async function call(+ handler: (req: ServerRequest, res: Response) => Promise<Response>,+ request: Record<string, unknown>,+): Promise<MockRes> {+ const res = mockRes();+ await handler(mockReq(request), res);+ return res;+}++const configOf = (res: MockRes) =>+ res.body?.config as {+ overrides: Record<string, unknown>;+ revision: string;+ tombstones: string[];+ };++/**+ * Booting mongod and importing data-schemas and the handlers (after `CREDS_KEY` is set) run in+ * parallel, and get a budget well past the 60s other suites use: on a saturated runner the+ * imports alone have exceeded it.+ */+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;+ ({ decryptV3, MAX_CONFIG_PATH_DEPTH: maxPathDepth } = dataSchemas);+ ({ 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('admin config handlers on the portable store (real Config collection)', () => {+ it('round-trips dotted record keys through PATCH and GET, stored raw where the engine accepts them', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const profiles = {+ 'us.anthropic.claude-sonnet-4-5': 'arn:aws:bedrock:us-east-1:1:inference-profile/x',+ 'eu.meta.llama3-70b': 'arn:aws:bedrock:eu-west-1:1:inference-profile/y',+ };++ const patched = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'endpoints.bedrock.inferenceProfiles', value: profiles }] },+ });+ expect(patched.statusCode).toBe(200);++ const read = await call(handlers.getConfig, { params });+ expect(configOf(read).overrides).toEqual({+ endpoints: { bedrock: { inferenceProfiles: profiles } },+ });+ const stored = await raw().findOne({ principalId: params.principalId });+ expect(Object.keys(stored!.overrides.endpoints.bedrock.inferenceProfiles)).toEqual([+ 'us.anthropic.claude-sonnet-4-5',+ 'eu.meta.llama3-70b',+ ]);+ expect(stored!.keyEncoding).toBeUndefined();++ const [applied] = await methods.getApplicableConfigs([+ { principalType: 'role', principalId: params.principalId },+ ]);+ expect(applied.overrides).toEqual({ endpoints: { bedrock: { inferenceProfiles: profiles } } });+ });++ it('does not let a write planned on a stale read copy old ciphertext over a rotated secret', async () => {+ const params = nextParams();+ const handlers = createHandlers();+ await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [+ {+ fieldPath: 'webSearch',+ value: { serperApiKey: 'sk-old-secret', searchProvider: 'serper' },+ },+ ],+ },+ });+ const beforeRotation = await methods.findConfigByPrincipal(+ 'role' as never,+ params.principalId,+ {+ includeInactive: true,+ },+ );+ await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'webSearch.serperApiKey', value: 'sk-rotated-secret' }] },+ });++ /** The stale admin's read happens before the rotation; its write lands after it. */+ const findConfigByPrincipal = jest+ .fn<+ ReturnType<Methods['findConfigByPrincipal']>,+ Parameters<Methods['findConfigByPrincipal']>+ >()+ .mockResolvedValueOnce(beforeRotation)+ .mockImplementation(methods.findConfigByPrincipal);+ const stale = createHandlers({ findConfigByPrincipal });+ const echoed = await call(stale.patchConfigField, {+ params,+ body: {+ entries: [+ { fieldPath: 'webSearch', value: { searchProvider: 'serper', scraperTimeout: 9000 } },+ ],+ },+ });++ expect(echoed.statusCode).toBe(200);+ expect(findConfigByPrincipal).toHaveBeenCalledTimes(2);+ const stored = await raw().findOne({ principalId: params.principalId });+ expect(decryptV3(stored!.overrides.webSearch.serperApiKey)).toBe('sk-rotated-secret');+ expect(stored!.overrides.webSearch.scraperTimeout).toBe(9000);+ });++ it('honors a client revision, answering 409 with the current revision once it is stale', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const created = await call(handlers.upsertConfigOverrides, {+ params,+ body: { overrides: { interface: { customWelcome: 'v1' } }, expectedRevision: 'absent' },+ });+ expect(created.statusCode).toBe(201);+ const firstRevision = configOf(created).revision;++ const updated = await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'v2' }],+ expectedRevision: firstRevision,+ },+ });+ expect(updated.statusCode).toBe(200);+ const secondRevision = configOf(updated).revision;+ expect(secondRevision).not.toBe(firstRevision);++ const stale = await call(handlers.deleteConfigField, {+ params,+ query: { fieldPath: 'interface.customWelcome', expectedRevision: firstRevision },+ });+ expect(stale.statusCode).toBe(409);+ expect(stale.body).toEqual({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: secondRevision,+ });++ const again = await call(handlers.upsertConfigOverrides, {+ params,+ body: { overrides: {}, priority: 3, expectedRevision: 'absent' },+ });+ expect(again.statusCode).toBe(409);+ expect((await call(handlers.getConfig, { params })).body).toEqual(+ expect.objectContaining({ config: expect.objectContaining({ revision: secondRevision }) }),+ );+ });++ it('refuses a revision of a profile that was deleted and recreated (ABA)', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const created = await call(handlers.upsertConfigOverrides, {+ params,+ body: { overrides: { interface: { customWelcome: 'old' } } },+ });+ const oldRevision = configOf(created).revision;+ await call(handlers.deleteConfigOverrides, { params });+ await call(handlers.upsertConfigOverrides, {+ params,+ body: { overrides: { interface: { customWelcome: 'new' } } },+ });++ const res = await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'stale' }],+ expectedRevision: oldRevision,+ },+ });++ expect(res.statusCode).toBe(409);+ expect(configOf(await call(handlers.getConfig, { params })).overrides).toEqual({+ interface: { customWelcome: 'new' },+ });+ });++ it('loses no update when unconditioned patches race', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'seed' }] },+ });++ /** Three attempts absorb two competing writers: each round, one of them commits. */+ const results = await Promise.all(+ ['modelSelect', 'parameters', 'presets'].map((field) =>+ call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: `interface.${field}`, value: false }] },+ }),+ ),+ );++ expect(results.map((res) => res.statusCode)).toEqual([200, 200, 200]);+ expect(configOf(await call(handlers.getConfig, { params })).overrides).toEqual({+ interface: { customWelcome: 'seed', modelSelect: false, parameters: false, presets: false },+ });+ });++ it('refuses an index past the end of a stored array instead of growing it', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const capabilities = ['endpoints', 'agents', 'capabilities'];+ const seeded = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: capabilities.join('.'), value: ['tools'] }] },+ });+ expect(seeded.statusCode).toBe(200);++ const refused = await Promise.all([+ call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: `${capabilities.join('.')}.10000000`, value: 'tools' }] },+ }),+ call(handlers.patchConfigField, {+ params,+ body: { entries: [{ segments: [...capabilities, '4294967296'], value: 'tools' }] },+ }),+ ]);++ for (const res of refused) {+ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Config path cannot be applied to the stored config',+ code: 'CONFIG_PATH_INVALID',+ reason: 'array_index',+ });+ }+ const appended = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: `${capabilities.join('.')}.1`, value: 'actions' }] },+ });+ expect(appended.statusCode).toBe(200);+ expect(configOf(appended).overrides).toEqual({+ endpoints: { agents: { capabilities: ['tools', 'actions'] } },+ });+ expect(configOf(appended).revision).toMatch(/:2$/);+ });++ it('prunes parents a reset empties and keeps tombstones beside them', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'mcpServers.docs.title', value: 'Docs' }] },+ });+ await call(handlers.tombstoneConfigField, { params, body: { fieldPath: 'mcpServers.github' } });++ const reset = await call(handlers.deleteConfigField, {+ params,+ query: { fieldPath: 'mcpServers.docs.title' },+ });++ expect(reset.statusCode).toBe(200);+ expect(configOf(reset).overrides).toEqual({});+ expect(configOf(reset).tombstones).toEqual(['mcpServers.github']);+ });++ it('clears a secret and its preview together in one version', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const set = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'ocr.apiKey', value: 'sk-ocr-secret-value-123' }] },+ });+ const [, before] = configOf(set).revision.split(':');++ const cleared = await call(handlers.tombstoneConfigField, {+ params,+ body: { fieldPath: 'ocr.apiKey' },+ });++ const [, after] = configOf(cleared).revision.split(':');+ expect(Number(after)).toBe(Number(before) + 1);+ expect(configOf(cleared).overrides).toEqual({});+ expect(configOf(cleared).tombstones).toEqual(['ocr.apiKey', 'ocr.apiKeyPreview']);+ });++ it('lets an assign-only caller delete a legacy profile that holds only empty shells', async () => {+ const params = nextParams();+ await raw().insertOne({+ principalType: 'role',+ principalId: params.principalId,+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ configVersion: 4,+ tombstones: [],+ overrides: { balance: {}, interface: {} },+ });+ const assignOnly = createHandlers({ hasConfigCapability: async () => false });++ const res = await call(assignOnly.deleteConfigOverrides, { params });++ expect(res.statusCode).toBe(200);+ expect(await raw().countDocuments({ principalId: params.principalId })).toBe(0);+ });++ it('reads a legacy document verbatim and keeps its keys raw on the next write', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ await raw().insertOne({+ principalType: 'role',+ principalId: params.principalId,+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ tombstones: [],+ overrides: {+ endpoints: { azureOpenAI: { titleModel: 'gpt-4.1' } },+ fileConfig: { 'a.b': 1 },+ },+ });++ const read = await call(handlers.getConfig, { params });+ expect(configOf(read).overrides).toEqual({+ endpoints: { azureOpenAI: { titleModel: 'gpt-4.1' } },+ fileConfig: { 'a.b': 1 },+ });+ expect(configOf(read).revision).toMatch(/:0$/);++ await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'hi' }],+ expectedRevision: configOf(read).revision,+ },+ });++ const stored = await raw().findOne({ principalId: params.principalId });+ expect(stored!.keyEncoding).toBeUndefined();+ expect(stored!.overrides.fileConfig).toEqual({ 'a.b': 1 });+ expect(configOf(await call(handlers.getConfig, { params })).overrides).toEqual({+ endpoints: { azureOpenAI: { titleModel: 'gpt-4.1' } },+ fileConfig: { 'a.b': 1 },+ interface: { customWelcome: 'hi' },+ });+ });+});++describe('segment addressing on the field routes', () => {+ const profiles = ['endpoints', 'bedrock', 'inferenceProfiles'];+ const usProfile = [...profiles, 'us.anthropic.claude-sonnet-4-5'];++ it('sets and removes one dotted record key by its segments, keeping its siblings', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: profiles.join('.'), value: { 'eu.meta.llama': 'arn:eu' } }] },+ });++ const set = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ segments: usProfile, value: 'arn:us' }] },+ });++ expect(set.statusCode).toBe(200);+ expect(configOf(set).overrides).toEqual({+ endpoints: {+ bedrock: { inferenceProfiles: { 'eu.meta.llama': 'arn:eu', [usProfile[3]]: 'arn:us' } },+ },+ });+ const stored = await raw().findOne({ principalId: params.principalId });+ expect(Object.keys(stored!.overrides.endpoints.bedrock.inferenceProfiles)).toEqual([+ 'eu.meta.llama',+ 'us.anthropic.claude-sonnet-4-5',+ ]);++ const removed = await call(handlers.deleteConfigField, {+ params,+ query: {+ segments: JSON.stringify([...profiles, 'eu.meta.llama']),+ expectedRevision: configOf(set).revision,+ },+ });++ expect(removed.statusCode).toBe(200);+ expect(configOf(removed).overrides).toEqual({+ endpoints: { bedrock: { inferenceProfiles: { [usProfile[3]]: 'arn:us' } } },+ });+ });++ it('applies segment and fieldPath entries in request order', async () => {+ const handlers = createHandlers();+ const parentThenKey = nextParams();+ const keyThenParent = nextParams();+ const parent = { fieldPath: profiles.join('.'), value: { 'eu.x': 'a' } };+ const key = { segments: usProfile, value: 'b' };++ await call(handlers.patchConfigField, {+ params: parentThenKey,+ body: { entries: [parent, key] },+ });+ await call(handlers.patchConfigField, {+ params: keyThenParent,+ body: { entries: [key, parent] },+ });++ const profilesOf = async (params: { principalType: string; principalId: string }) =>+ (+ configOf(await call(handlers.getConfig, { params })).overrides as {+ endpoints: { bedrock: { inferenceProfiles: Record<string, string> } };+ }+ ).endpoints.bedrock.inferenceProfiles;+ expect(await profilesOf(parentThenKey)).toEqual({ 'eu.x': 'a', [usProfile[3]]: 'b' });+ expect(await profilesOf(keyThenParent)).toEqual({ 'eu.x': 'a' });+ });++ it('sends dot-free segments through the same secret pipeline as a fieldPath', async () => {+ const handlers = createHandlers();+ const params = nextParams();++ const res = await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [{ segments: ['webSearch', 'serperApiKey'], value: 'sk-serper-0123456789' }],+ },+ });++ expect(res.statusCode).toBe(200);+ const stored = await raw().findOne({ principalId: params.principalId });+ expect(decryptV3(stored!.overrides.webSearch.serperApiKey)).toBe('sk-serper-0123456789');+ expect(stored!.overrides.webSearch.serperApiKeyPreview).toBe('...6789');+ expect(JSON.stringify(res.body)).not.toContain('sk-serper-0123456789');++ const tombstoned = await call(handlers.tombstoneConfigField, {+ params,+ body: { segments: ['webSearch', 'serperApiKey'] },+ });+ expect(configOf(tombstoned).tombstones).toEqual([+ 'webSearch.serperApiKey',+ 'webSearch.serperApiKeyPreview',+ ]);+ });++ it.each([+ [+ 'a tombstone naming a dotted key',+ 'tombstoneConfigField',+ { body: { segments: usProfile } },+ 'dotted_segment',+ ],+ [+ 'a dotted key inside an MCP server',+ 'patchConfigField',+ { body: { entries: [{ segments: ['mcpServers', 'docs', 'headers', 'X.Id'], value: 'v' }] } },+ 'dotted_segment',+ ],+ [+ 'a dotted key where a secret-bearing array item sits',+ 'patchConfigField',+ { body: { entries: [{ segments: ['endpoints', 'custom', 'a.b'], value: { apiKey: 'k' } }] } },+ 'dotted_segment',+ ],+ [+ 'a dotted section',+ 'patchConfigField',+ { body: { entries: [{ segments: ['interface.customWelcome'], value: 'x' }] } },+ 'dotted_segment',+ ],+ [+ 'a `$` key',+ 'patchConfigField',+ { body: { entries: [{ segments: ['interface', '$set'], value: 'x' }] } },+ 'unsafe_segment',+ ],+ [+ 'segments that are not JSON in a query',+ 'deleteConfigField',+ { query: { segments: 'interface.customWelcome' } },+ 'empty_path',+ ],+ ] as const)('refuses %s and writes nothing', async (_label, handler, request, reason) => {+ const handlers = createHandlers();+ const params = nextParams();++ const res = await call(handlers[handler], { params, ...request });++ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual(expect.objectContaining({ code: 'CONFIG_PATH_INVALID', reason }));+ expect(await raw().countDocuments({ principalId: params.principalId })).toBe(0);+ });++ it('caps a dotted fieldPath at the depth segments are capped at, on every field route', async () => {+ const handlers = createHandlers();+ const params = nextParams();+ const atLimit = ['interface', ...Array<string>(maxPathDepth - 1).fill('a')].join('.');+ const deep = ['interface', ...Array<string>(20_000).fill('a')].join('.');++ const refused = await Promise.all([+ call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: `${atLimit}.a`, value: 1 }] },+ }),+ call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: deep, value: 1 }] },+ }),+ call(handlers.tombstoneConfigField, { params, body: { fieldPath: deep } }),+ call(handlers.deleteConfigField, { params, query: { fieldPath: deep } }),+ ]);++ for (const res of refused) {+ expect(res.statusCode).toBe(400);+ expect(res.body).toEqual({+ error: 'Field path is too deep',+ code: 'CONFIG_PATH_INVALID',+ reason: 'too_deep',+ });+ }+ expect(await raw().countDocuments({ principalId: params.principalId })).toBe(0);++ const accepted = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: atLimit, value: 1 }] },+ });+ expect(accepted.statusCode).toBe(200);+ });++ it('refuses an entry naming both a fieldPath and segments, and duplicate segments', async () => {+ const handlers = createHandlers();+ const params = nextParams();++ const both = await call(handlers.patchConfigField, {+ params,+ body: { entries: [{ fieldPath: 'interface.customWelcome', segments: ['a'], value: 'x' }] },+ });+ const duplicate = await call(handlers.patchConfigField, {+ params,+ body: {+ entries: [+ { segments: usProfile, value: 'a' },+ { segments: usProfile, value: 'b' },+ ],+ },+ });++ expect(both.statusCode).toBe(400);+ expect(duplicate.statusCode).toBe(400);+ expect(duplicate.body).toEqual({ error: 'Duplicate field path segments' });+ expect(await raw().countDocuments({ principalId: params.principalId })).toBe(0);+ });++ it('checks section grants on the first segment', async () => {+ const endpointsOnly = createHandlers({+ hasConfigCapability: async (_user, section) => section === 'endpoints',+ });+ const params = nextParams();++ const allowed = await call(endpointsOnly.patchConfigField, {+ params,+ body: { entries: [{ segments: usProfile, value: 'arn:us' }] },+ });+ const denied = await call(endpointsOnly.patchConfigField, {+ params,+ body: {+ entries: [{ segments: ['fileConfig', 'endpoints', 'agents.v2', 'fileLimit'], value: 1 }],+ },+ });++ expect(allowed.statusCode).toBe(200);+ expect(denied.statusCode).toBe(403);+ });+});diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.tsindex 1716eb2978..8f146afbc1 100644--- a/packages/api/src/admin/config.ts+++ b/packages/api/src/admin/config.ts@@ -1,12 +1,3 @@-import {- logger,- isFieldNameRejection,- getConfigFieldIssues,- applyConfigTombstones,- getDottedSectionIssues,- getConfigOverrideIssues,- BASE_CONFIG_PRINCIPAL_ID,-} from '@librechat/data-schemas';import {BASE_PRINCIPAL_CONFIG_SECTIONS,BASE_ONLY_CONFIG_SECTIONS,@@ -19,16 +10,47 @@ import {isProcessMCPServerConfig,isProcessMCPServerField,} from 'librechat-data-provider';+import {+ logger,+ isDotFreePath,+ parseFieldPath,+ setConfigFields,+ unsetConfigPaths,+ getConfigRevision,+ isConfigRevision,+ isConfigPathError,+ isFieldNameRejection,+ getDottedSectionIssues,+ runConfigMutation,+ getConfigFieldIssues,+ toConfigOverrideState,+ tombstoneConfigPaths,+ applyConfigTombstones,+ replaceConfigOverrides,+ parseConfigPathSegments,+ getConfigOverrideIssues,+ getExpectedRevision,+ MAX_CONFIG_PATH_DEPTH,+ DEFAULT_CONFIG_PRIORITY,+ BASE_CONFIG_PRINCIPAL_ID,+ isConfigRevisionConflict,+ isConfigOverrideStateEmpty,+} from '@librechat/data-schemas';import type {- IConfig,AppConfig,+ ConfigDraft,+ ConfigRecord,ConfigSection,+ ConfigRevision,+ ConfigFieldWrite,SystemCapability,+ ConfigPathError,+ ConfigPathInputs,ConfigOverrideIssue,- ConfigWritePrecondition,+ ConfigPathErrorReason,+ ConfigMutationOutcome,} from '@librechat/data-schemas';import type { TCustomConfig } from 'librechat-data-provider';-import type { Types, ClientSession } from 'mongoose';import type { Response } from 'express';import type { AdminAuditEvent, RecordAuditEntry } from './audit';import type { CapabilityUser } from '~/middleware/capabilities';@@ -43,11 +65,11 @@ import {isConfigSecretAncestorPath,isConfigSecretDescendantPath,isConfigSecretPreservablePatch,+ isConfigSecretRelatedSegments,preserveConfigSecrets,redactConfigSecrets,} from './secrets';import {- hasWebSearchSection,getPatchReentryIssues,isWebSearchBindingPath,getRemovalReentryIssues,@@ -60,7 +82,6 @@ import { buildAdminConfigMeta } from './meta';const UNSAFE_SEGMENTS = /(?:^|\.)(__[\w]*|constructor|prototype)(?:\.|$)/;const MAX_PATCH_ENTRIES = 100;-const DEFAULT_PRIORITY = 10;const BASE_ONLY_OVERRIDE_SECTIONS = new Set<string>(BASE_ONLY_CONFIG_SECTIONS);const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set<string>(BASE_PRINCIPAL_CONFIG_SECTIONS);const PROCESS_MCP_CONFIG_ERROR =@@ -134,6 +155,118 @@ function isProcessMCPServerFieldPath(fieldPath: string, value: unknown): booleanreturn isProcessMCPServerField(field) || (field === 'type' && value === 'stdio');}+/** Sections whose guards read dotted paths, so a segment that contains a dot is refused there. */+const DOT_FREE_SECTIONS = new Set(['mcpServers', 'mcpConfig', 'langfuse']);++/**+ * Where a field write, removal or tombstone lands. `fieldPath` is the dotted spelling that the+ * section, permission and secret guards read; it names exactly `segments` when `dotFree`.+ */+interface FieldTarget {+ segments: string[];+ fieldPath: string;+ dotFree: boolean;+}++type FieldTargetRead =+ | { ok: true; target: FieldTarget }+ | { ok: false; error: string; reason?: ConfigPathErrorReason };++/**+ * Reads a target from exactly one of `fieldPath` (validated as it always was) and `segments`.+ * Both spellings share the {@link MAX_CONFIG_PATH_DEPTH} cap. A segment that contains a dot is+ * refused wherever a guard would split it: as the section, inside sections whose guards read+ * dotted paths, and on a registered secret's path.+ */+function readFieldTarget(fieldPath: unknown, segments: unknown): FieldTargetRead {+ if (segments === undefined) {+ if (typeof fieldPath !== 'string' || !isValidFieldPath(fieldPath)) {+ return { ok: false, error: `Invalid or unsafe field path: ${String(fieldPath)}` };+ }+ const parsed = parseFieldPath(fieldPath);+ if (parsed.length > MAX_CONFIG_PATH_DEPTH) {+ return { ok: false, error: 'Field path is too deep', reason: 'too_deep' };+ }+ return { ok: true, target: { segments: parsed, fieldPath, dotFree: true } };+ }+ if (fieldPath !== undefined) {+ return { ok: false, error: 'Provide either fieldPath or segments, not both' };+ }+ const parsed = parseConfigPathSegments(segments);+ if (!parsed.ok) {+ return { ok: false, error: 'Invalid or unsafe field path segments', reason: parsed.reason };+ }+ const target: FieldTarget = {+ segments: parsed.segments,+ fieldPath: parsed.segments.join('.'),+ dotFree: isDotFreePath(parsed.segments),+ };+ const [section] = target.segments;+ if (+ !target.dotFree &&+ (section.includes('.') ||+ DOT_FREE_SECTIONS.has(section) ||+ isConfigSecretRelatedSegments(target.segments))+ ) {+ return {+ ok: false,+ error: 'This path cannot address a key that contains a dot',+ reason: 'dotted_segment',+ };+ }+ return { ok: true, target };+}++function fieldTargetErrorResponse(+ res: Response,+ failure: { error: string; reason?: ConfigPathErrorReason },+): Response {+ const { error, reason } = failure;+ return res.status(400).json(reason ? { error, code: 'CONFIG_PATH_INVALID', reason } : { error });+}++/** How a target is named in audit metadata: its dotted path, or its segments when lossy. */+function describeFieldTarget(target: FieldTarget): string {+ return target.dotFree ? target.fieldPath : JSON.stringify(target.segments);+}++/** `segments` in a query string is a JSON-encoded array; anything else is passed on to fail. */+function readSegmentsQuery(value: unknown): unknown {+ if (typeof value !== 'string') {+ return value;+ }+ try {+ return JSON.parse(value);+ } catch {+ return value;+ }+}++/**+ * The field writes in request order: each dot-free entry as encryption and secret+ * preservation left it (one they dropped is skipped), each dotted entry as sent, then any+ * field the secret pipeline added, such as a preview companion.+ */+function toOrderedWrites(+ entries: ReadonlyArray<{ target: FieldTarget; value: unknown }>,+ fields: Record<string, unknown>,+): ConfigFieldWrite[] {+ const pending = new Map(Object.entries(fields));+ const writes: ConfigFieldWrite[] = [];+ for (const { target, value } of entries) {+ if (!target.dotFree) {+ writes.push({ segments: target.segments, value });+ } else if (pending.has(target.fieldPath)) {+ writes.push({ segments: target.segments, value: pending.get(target.fieldPath) });+ pending.delete(target.fieldPath);+ }+ }+ for (const [fieldPath, value] of pending) {+ writes.push({ segments: parseFieldPath(fieldPath), value });+ }+ return writes;+}+/*** Returns true if `fieldPath` targets an interface permission field or permission sub-key.*@@ -194,62 +327,77 @@ function normalizeInterfaceFieldPatch(fieldPath: string, value: unknown): unknowreturn normalizeRuntimeInterfaceValue(parts[1], value);}+/**+ * Positional slot where config methods once took a Mongoose `ClientSession`; the portable+ * config store does not join transactions.+ */+type NoSession = undefined;++/** Options of the principal-scoped config writes the handlers delegate whole. */+interface ConfigWriteOptions {+ /** Write only when the stored document is at this revision (`absent`: only if none exists). */+ expectedRevision?: ConfigRevision;+}++interface ConfigLifecycleOptions extends ConfigWriteOptions {+ /** Act only on a document that holds nothing; otherwise resolve to `null`. */+ expectEmpty?: boolean;+}+export interface AdminConfigDeps {- listAllConfigs: (filter?: { isActive?: boolean }, session?: ClientSession) => Promise<IConfig[]>;+ listAllConfigs: (filter?: { isActive?: boolean }, session?: NoSession) => Promise<ConfigRecord[]>;findConfigByPrincipal: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,options?: { includeInactive?: boolean },- session?: ClientSession,- ) => Promise<IConfig | null>;- upsertConfig: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- overrides: Partial<TCustomConfig>,- priority: number,- session?: ClientSession,- options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,- ) => Promise<IConfig | null>;- /** Resolves to `null` only when `options.expectedVersion` no longer holds. */- patchConfigFields: (+ session?: NoSession,+ ) => Promise<ConfigRecord | null>;+ /**+ * Writes the principal's whole document when it is still at `expected` (`absent`: only when+ * none exists), or throws a `ConfigRevisionConflictError`. PUT and PATCH plan the next+ * document from the one they read, so validation and secret preservation see exactly what the+ * write replaces.+ */+ writeConfigDocument: (principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- fields: Record<string, unknown>,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;+ principalId: string,+ draft: ConfigDraft,+ expected: ConfigRevision,+ ) => Promise<ConfigRecord>;+ /** Tombstones every path in one write; an omitted `priority` keeps the stored one. */tombstoneConfigField: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,principalModel: PrincipalModel,- fieldPath: string,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;+ fieldPaths: ConfigPathInputs,+ priority?: number,+ session?: NoSession,+ options?: ConfigWriteOptions,+ ) => Promise<ConfigRecord>;+ /**+ * Removes every path (dotted, or `{ segments }` for keys that contain dots) in one write,+ * pruning parents left empty; `null` when there is no document.+ */unsetConfigField: (principalType: PrincipalType,- principalId: string | Types.ObjectId,- fieldPath: string,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;+ principalId: string,+ fieldPaths: ConfigPathInputs,+ session?: NoSession,+ options?: ConfigWriteOptions,+ ) => Promise<ConfigRecord | null>;deleteConfig: (principalType: PrincipalType,- principalId: string | Types.ObjectId,- session?: ClientSession,- options?: { expectEmpty?: boolean },- ) => Promise<IConfig | null>;+ principalId: string,+ session?: NoSession,+ options?: ConfigLifecycleOptions,+ ) => Promise<ConfigRecord | null>;/** Resolves to the post-write document and whether this write changed `isActive`. */toggleConfigActiveTracked: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,isActive: boolean,- options?: { expectEmpty?: boolean },- ) => Promise<{ config: IConfig; changed: boolean } | null>;+ options?: ConfigLifecycleOptions,+ ) => Promise<{ config: ConfigRecord; changed: boolean } | null>;hasConfigCapability: (user: CapabilityUser,section: ConfigSection | null,@@ -268,8 +416,10 @@ export interface AdminConfigDeps {userId?: string;tenantId?: string;baseOnly?: boolean;+ /** Read the overrides from the store instead of the per-principal merged-config cache. */+ bypassOverrideCache?: boolean;}) => Promise<AppConfig>;- /** Invalidate all config-related caches after a mutation. */+ /** Invalidate the config caches a mutation affects; awaited before the response is sent. */invalidateConfigCaches?: (tenantId?: string) => Promise<void>;/** Optional audit emission for override mutations; fail-open unless `auditFailClosed`. */recordAuditEntry?: RecordAuditEntry;@@ -387,7 +537,10 @@ function filterSectionsByReadAccess<T extends Record<string, unknown>>(return result as T;}-function filterConfigDocForReadAccess(config: IConfig, readable: ReadableSections): IConfig {+function filterConfigDocForReadAccess(+ config: ConfigRecord,+ readable: ReadableSections,+): ConfigRecord {const canRead = (section: string): boolean => canReadSection(readable, section);const filteredOverrides = filterSectionsByReadAccess((config.overrides ?? {}) as Record<string, unknown>,@@ -403,7 +556,7 @@ function filterConfigDocForReadAccess(config: IConfig, readable: ReadableSection...config,overrides: filteredOverrides as Partial<TCustomConfig>,tombstones: filteredTombstones,- } as IConfig;+ };}function filterAppConfigForReadAccess(appConfig: AppConfig, readable: ReadableSections): AppConfig {@@ -426,8 +579,8 @@ function filterAppConfigForReadAccess(appConfig: AppConfig, readable: ReadableSereturn filtered as unknown as AppConfig;}-/** All section names an `IConfig` document's overrides/tombstones could reference. */-function collectConfigSections(config: IConfig): string[] {+/** All section names a config document's overrides/tombstones could reference. */+function collectConfigSections(config: ConfigRecord): string[] {return [...Object.keys(config.overrides ?? {}),...(config.tombstones ?? []).map(getTopLevelSection),@@ -443,12 +596,15 @@ function collectAppConfigSections(appConfig: AppConfig): string[] {return [...topLevel, ...(nested ? Object.keys(nested) : [])];}-function redactConfigForResponse(config: IConfig): IConfig {- const safeConfig = JSON.parse(JSON.stringify(config)) as IConfig;+type ConfigResponse = ConfigRecord & { revision: ConfigRevision };++/** The document as the admin API returns it: secrets redacted, with its revision. */+function redactConfigForResponse(config: ConfigRecord): ConfigResponse {+ const safeConfig = JSON.parse(JSON.stringify(config)) as ConfigRecord;if (safeConfig.overrides) {redactConfigSecrets(safeConfig.overrides, { previewPlaintext: true });}- return safeConfig;+ return { ...safeConfig, revision: getConfigRevision(config) };}/**@@ -511,20 +667,32 @@ function secretReentryResponse(res: Response, issues: SecretReentryIssue[]): Res});}-/**- * Rejects a write whose re-entry check read a document version another write- * has since replaced, so the check never approves a state it did not see.- */-function versionConflictResponse(res: Response): Response {- return res.status(409).json({- error: 'The config changed while this write was being checked. Reload it and try again.',- code: 'CONFIG_VERSION_CONFLICT',- });+const INVALID_EXPECTED_REVISION_ERROR =+ 'expectedRevision must be "absent" or a revision returned by the config API';++/** A client precondition: absent (none given), a well-formed revision, or malformed. */+function readExpectedRevision(+ value: unknown,+): { ok: true; value?: ConfigRevision } | { ok: false } {+ if (value === undefined || value === null) {+ return { ok: true };+ }+ return isConfigRevision(value) ? { ok: true, value } : { ok: false };}-/** The version a binding write must apply to: the one read, or `null` when no document existed. */-function readVersion(config: IConfig | null | undefined): ConfigWritePrecondition {- return { expectedVersion: config?.configVersion ?? null };+function invalidExpectedRevisionResponse(res: Response): Response {+ return res+ .status(400)+ .json({ error: INVALID_EXPECTED_REVISION_ERROR, code: 'INVALID_EXPECTED_REVISION' });+}++/** Reports why a path cannot apply to the stored document, without echoing the path. */+function invalidPathResponse(res: Response, error: ConfigPathError): Response {+ return res.status(400).json({+ error: 'Config path cannot be applied to the stored config',+ code: 'CONFIG_PATH_INVALID',+ reason: error.reason,+ });}function preservePatchedConfigSecretFields(@@ -557,8 +725,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const {listAllConfigs,findConfigByPrincipal,- upsertConfig,- patchConfigFields,+ writeConfigDocument,tombstoneConfigField: writeConfigTombstone,unsetConfigField,deleteConfig,@@ -590,6 +757,131 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const meta = buildAdminConfigMeta({ maxPatchEntries: MAX_PATCH_ENTRIES, overrideCacheTtlMs });+ function readStoredConfig(+ principalType: PrincipalType,+ principalId: string,+ ): Promise<ConfigRecord | null> {+ return findConfigByPrincipal(principalType, principalId, { includeInactive: true });+ }++ /**+ * Clears the caches a write affects before the response goes out, so the caller's next read+ * sees the write. A failure is logged, not surfaced: the write itself has committed.+ */+ async function invalidateCaches(tenantId: string | undefined, operation: string): Promise<void> {+ try {+ await invalidateConfigCaches?.(tenantId);+ } catch (error) {+ logger.error(+ `[adminConfig] Cache invalidation failed after ${operation}:`,+ getSafeErrorMetadata(error),+ );+ }+ }++ /**+ * 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.+ */+ async function noopResponse(+ res: Response,+ message: string,+ principalType: PrincipalType,+ principalId: string,+ expectedRevision: ConfigRevision | undefined,+ ): Promise<Response> {+ const stored = await readStoredConfig(principalType, principalId);+ const revision = stored ? getConfigRevision(stored) : null;+ if (expectedRevision && expectedRevision !== getExpectedRevision(stored)) {+ return conflictResponse(res, revision, principalType, principalId);+ }+ return res.status(200).json({ message, revision });+ }++ async function conflictResponse(+ res: Response,+ knownRevision: ConfigRevision | null | undefined,+ principalType: PrincipalType,+ principalId: string,+ ): Promise<Response> {+ let currentRevision = knownRevision;+ if (currentRevision === undefined) {+ const stored = await readStoredConfig(principalType, principalId);+ currentRevision = stored ? getConfigRevision(stored) : null;+ }+ return res.status(409).json({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision,+ });+ }++ /** Maps the expected failures of a write to their responses; anything else is rethrown. */+ async function writeFailureResponse(+ res: Response,+ error: unknown,+ principalType: PrincipalType,+ principalId: string,+ ): Promise<Response> {+ if (isConfigRevisionConflict(error)) {+ return conflictResponse(res, error.currentRevision, principalType, principalId);+ }+ if (isConfigPathError(error)) {+ return invalidPathResponse(res, error);+ }+ throw error;+ }++ /**+ * Unsets or tombstones a web search URL (or the whole section) in a write planned from the+ * document it replaces, so the re-entry check judges exactly the revision the write lands on.+ * A write that lands in between is re-read and re-checked, or answers 409 under+ * `expectedRevision`. Stops with the re-entry issues, or with `null` when an unset finds no+ * document.+ */+ function removeWebSearchBinding(+ principalType: PrincipalType,+ principalId: string,+ fieldPath: string,+ removal: { tombstone: true; priority?: number } | { tombstone: false },+ expectedRevision: ConfigRevision | undefined,+ ): Promise<ConfigMutationOutcome<SecretReentryIssue[] | null>> {+ const paths = getConfigSecretMutationPaths(fieldPath).map(parseFieldPath);+ return runConfigMutation<SecretReentryIssue[] | null>(+ {+ read: () => readStoredConfig(principalType, principalId),+ write: (draft, revision) =>+ writeConfigDocument(principalType, principalId, draft, revision),+ },+ (stored) => {+ if (!stored && !removal.tombstone) {+ return { draft: null, result: null };+ }+ const reentry = getRemovalReentryIssues(stored, fieldPath, removal.tombstone);+ if (reentry.length > 0) {+ return { draft: null, result: reentry };+ }+ const current = toConfigOverrideState(stored);+ const state = removal.tombstone+ ? tombstoneConfigPaths(current, paths)+ : unsetConfigPaths(current, paths);+ return {+ draft: {+ principalModel: stored?.principalModel ?? principalModel(principalType),+ priority:+ (removal.tombstone ? removal.priority : undefined) ??+ stored?.priority ??+ DEFAULT_CONFIG_PRIORITY,+ overrides: state.overrides,+ tombstones: state.tombstones,+ isActive: stored?.isActive ?? true,+ },+ };+ },+ { expectedRevision },+ );+ }+/** The deployment's `librechat.yaml` config, which overrides are validated on top of. */async function getBaseYamlConfig(tenantId?: string): Promise<Partial<TCustomConfig>> {if (!getAppConfig) {@@ -670,7 +962,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const baseOnly = (req.query as Record<string, unknown>).baseOnly === 'true';const [appConfig, yamlConfig] = await Promise.all([- getAppConfig({ tenantId: user.tenantId, baseOnly }),+ getAppConfig({ tenantId: user.tenantId, baseOnly, bypassOverrideCache: true }),baseOnly ? undefined : getAppConfig({ tenantId: user.tenantId, baseOnly: true }),]);const sections = collectAppConfigSections(appConfig) as ConfigSection[];@@ -750,6 +1042,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: 'overrides must be a plain object' });}+ const expected = readExpectedRevision(+ (req.body as { expectedRevision?: unknown }).expectedRevision,+ );+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);+ }+const rawOverrides = overrides as Record<string, unknown>;if (hasProcessMCPServerConfig(rawOverrides.mcpServers) ||@@ -859,7 +1158,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {const overrideSections = Object.keys(filteredOverrides);if (overrideSections.length === 0 && priority == null) {- return res.status(200).json({ message: 'No actionable override sections provided' });+ return noopResponse(+ res,+ 'No actionable override sections provided',+ principalType,+ principalId,+ expected.value,+ );}if (overrideSections.length > 0 && !hasBroadManage) {@@ -872,11 +1177,6 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {);}- const requestedPriority = hasBroadManage ? (priority ?? DEFAULT_PRIORITY) : DEFAULT_PRIORITY;- const upsertOptions = hasBroadManage- ? { expectEmpty: false }- : { expectEmpty: true, preservePriority: true };-for (const section of getConfigSecretSections()) {const secretInputError = getConfigSecretInputError(section,@@ -888,85 +1188,101 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const encryptedOverrides = encryptConfigSecrets(filteredOverrides);- const needsExistingSecrets = getConfigSecretSections().some((section) =>- isConfigSecretPreservablePatch(- section,- (filteredOverrides as Record<string, unknown>)[section],- ),- );- const needsProtectedBaseSections =- principalId === BASE_CONFIG_PRINCIPAL_ID &&- (overrideSections.length > 0 || priority != null);- const needsExisting = needsExistingSecrets || needsProtectedBaseSections;- const [stored, baseYaml] = await Promise.all([- overrideSections.length > 0 || needsExisting- ? findConfigByPrincipal(principalType, principalId, { includeInactive: true })- : null,- overrideSections.length > 0 ? getBaseYamlConfig(user.tenantId) : {},- ]);- /** A full replace keeps the principal's tombstones, so they shape the base it lands on. */- const overrideIssues = getConfigOverrideIssues(- encryptedOverrides,- applyConfigTombstones(baseYaml, stored?.tombstones),- );- if (overrideIssues.length > 0) {- return invalidOverrideResponse(res, overrideIssues);+ const baseYaml = overrideSections.length > 0 ? await getBaseYamlConfig(user.tenantId) : {};++ type PutStop =+ | { status: 403 }+ | { status: 400; issues: ConfigOverrideIssue[] }+ | { status: 400; reentry: SecretReentryIssue[] };+ let outcome;+ try {+ outcome = await runConfigMutation<PutStop>(+ {+ read: () => readStoredConfig(principalType, principalId),+ write: (draft, revision) =>+ writeConfigDocument(principalType, principalId, draft, revision),+ },+ (stored) => {+ /** Assign-only callers manage the profile's lifecycle, never its contents. */+ if (+ !hasBroadManage &&+ stored &&+ !isConfigOverrideStateEmpty(toConfigOverrideState(stored))+ ) {+ return { draft: null, result: { status: 403 } };+ }+ /** Secrets an object omits are kept before validation sees the document. */+ const preserved = preserveConfigSecrets(encryptedOverrides, stored?.overrides);+ /** A full replace keeps the principal's tombstones, so they shape its base. */+ const issues = getConfigOverrideIssues(+ preserved,+ applyConfigTombstones(baseYaml, stored?.tombstones),+ );+ if (issues.length > 0) {+ return { draft: null, result: { status: 400, issues } };+ }+ /** A changed URL beside a stored key that stays needs that key entered again. */+ const reentry = getReplaceReentryIssues(stored, filteredOverrides, preserved);+ if (reentry.length > 0) {+ return { draft: null, result: { status: 400, reentry } };+ }+ const next = { ...preserved } as Record<string, unknown>;+ if (principalId === BASE_CONFIG_PRINCIPAL_ID) {+ for (const section of BASE_PRINCIPAL_OVERRIDE_SECTIONS) {+ const storedSection = (stored?.overrides as Record<string, unknown> | undefined)?.[+ section+ ];+ if (storedSection !== undefined) {+ next[section] = storedSection;+ }+ }+ }+ const state = replaceConfigOverrides(+ toConfigOverrideState(stored),+ next as Partial<TCustomConfig>,+ );+ return {+ draft: {+ principalModel: principalModel(principalType),+ priority: hasBroadManage+ ? (priority ?? DEFAULT_CONFIG_PRIORITY)+ : (stored?.priority ?? DEFAULT_CONFIG_PRIORITY),+ overrides: state.overrides,+ tombstones: state.tombstones,+ isActive: true,+ },+ };+ },+ { expectedRevision: expected.value },+ );+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);}- const existingConfig = needsExisting ? stored : null;- const preservedOverrides = preserveConfigSecrets(- encryptedOverrides,- existingConfig?.overrides,- );- const reentryIssues = getReplaceReentryIssues(stored, filteredOverrides, preservedOverrides);- if (reentryIssues.length > 0) {- return secretReentryResponse(res, reentryIssues);- }- const precondition: ConfigWritePrecondition = hasWebSearchSection(filteredOverrides)- ? readVersion(stored)- : {};- if (needsProtectedBaseSections) {- for (const section of BASE_PRINCIPAL_OVERRIDE_SECTIONS) {- const storedSection = (- existingConfig?.overrides as Record<string, unknown> | undefined- )?.[section];- if (storedSection !== undefined) {- (preservedOverrides as Record<string, unknown>)[section] = storedSection;- }++ if (!outcome.written) {+ const stop = outcome.result;+ if (stop.status === 403) {+ return res.status(403).json({ error: 'Insufficient permissions' });}- }- const config = await upsertConfig(- principalType,- principalId,- principalModel(principalType),- preservedOverrides,- requestedPriority,- undefined,- { ...upsertOptions, ...precondition },- );- if (!config && precondition.expectedVersion !== undefined) {- return versionConflictResponse(res);- }- if (!config && !hasBroadManage) {- return res.status(403).json({ error: 'Insufficient permissions' });+ if ('reentry' in stop) {+ return secretReentryResponse(res, stop.reentry);+ }+ return invalidOverrideResponse(res, stop.issues);}- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after upsert:', err),- );- if (config) {- await emitAudit(req, {- action: config.configVersion === 1 ? 'config.created' : 'config.updated',- target: configTarget(principalType, principalId),- metadata: {- operation: 'replace',- sections: overrideSections.join(','),- priority: config.priority,- },- });- }- return res.status(config?.configVersion === 1 ? 201 : 200).json({- config: config ? redactConfigForResponse(config) : config,+ const { record: config, previous } = outcome;+ const created = previous == null;+ await invalidateCaches(user.tenantId, 'upsert');+ await emitAudit(req, {+ action: created ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: {+ operation: 'replace',+ sections: overrideSections.join(','),+ priority: config.priority,+ },});+ return res.status(created ? 201 : 200).json({ config: redactConfigForResponse(config) });} catch (error) {if (isFieldNameRejection(error)) {return unstorableKeyResponse(res, 'upsertConfigOverrides');@@ -995,7 +1311,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const { entries, priority } = req.body as {- entries?: Array<{ fieldPath: string; value: unknown }>;+ entries?: Array<{ fieldPath?: unknown; segments?: unknown; value: unknown } | null>;priority?: number;};@@ -1003,6 +1319,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: 'priority must be a non-negative number' });}+ const expected = readExpectedRevision(+ (req.body as { expectedRevision?: unknown }).expectedRevision,+ );+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);+ }+if (!Array.isArray(entries) || entries.length === 0) {return res.status(400).json({ error: 'entries array is required and must not be empty' });}@@ -1013,32 +1336,35 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {.json({ error: `entries array exceeds maximum of ${MAX_PATCH_ENTRIES}` });}+ const targets: Array<{ target: FieldTarget; value: unknown }> = [];for (const entry of entries) {- if (!isValidFieldPath(entry.fieldPath)) {- return res- .status(400)- .json({ error: `Invalid or unsafe field path: ${entry.fieldPath}` });+ const read = readFieldTarget(entry?.fieldPath, entry?.segments);+ if (!read.ok) {+ return fieldTargetErrorResponse(res, read);}- if (isProcessMCPServerFieldPath(entry.fieldPath, entry.value)) {+ const { fieldPath } = read.target;+ const value = entry?.value;+ if (isProcessMCPServerFieldPath(fieldPath, value)) {return res.status(400).json({ error: PROCESS_MCP_CONFIG_ERROR });}- if (isLangfuseHeadersFieldPath(entry.fieldPath)) {+ if (isLangfuseHeadersFieldPath(fieldPath)) {return res.status(400).json({ error: LANGFUSE_HEADERS_CONFIG_ERROR });}- if (isConfigSecretDescendantPath(entry.fieldPath)) {+ if (isConfigSecretDescendantPath(fieldPath)) {return res.status(400)- .json({ error: `Cannot patch inside protected secret path: ${entry.fieldPath}` });+ .json({ error: `Cannot patch inside protected secret path: ${fieldPath}` });}- const secretInputError = getConfigSecretInputError(entry.fieldPath, entry.value);+ const secretInputError = getConfigSecretInputError(fieldPath, value);if (secretInputError) {return res.status(400).json({ error: secretInputError });}- if (Array.isArray(entry.value) && isConfigSecretAncestorPath(entry.fieldPath)) {+ if (Array.isArray(value) && isConfigSecretAncestorPath(fieldPath)) {return res.status(400).json({- error: `Cannot patch protected secret ancestor as an array: ${entry.fieldPath}`,+ error: `Cannot patch protected secret ancestor as an array: ${fieldPath}`,});}+ targets.push({ target: read.target, value });}const user = getCapabilityUser(req);@@ -1046,27 +1372,27 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(401).json({ error: 'Authentication required' });}- const validEntries = entries- .map((entry) => ({- ...entry,- value: normalizeInterfaceFieldPatch(entry.fieldPath, entry.value),+ const validEntries = targets+ .map(({ target, value }) => ({+ target,+ value: normalizeInterfaceFieldPatch(target.fieldPath, value),}))- .filter((entry) => {- if (isBaseOnlyFieldPath(entry.fieldPath)) {+ .filter(({ target: { fieldPath } }) => {+ if (isBaseOnlyFieldPath(fieldPath)) {logger.warn(- `[adminConfig] Stripping base-only config field "${entry.fieldPath}" - configure it in librechat.yaml instead`,+ `[adminConfig] Stripping base-only config field "${fieldPath}" - configure it in librechat.yaml instead`,);return false;}- if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(getTopLevelSection(entry.fieldPath))) {+ if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(getTopLevelSection(fieldPath))) {logger.warn(- `[adminConfig] Stripping dedicated tenant-wide config field "${entry.fieldPath}" from the generic config API`,+ `[adminConfig] Stripping dedicated tenant-wide config field "${fieldPath}" from the generic config API`,);return false;}- if (isInterfacePermissionPath(entry.fieldPath)) {+ if (isInterfacePermissionPath(fieldPath)) {logger.warn(- `[adminConfig] Stripping interface permission field "${entry.fieldPath}" — use role permissions instead`,+ `[adminConfig] Stripping interface permission field "${fieldPath}" — use role permissions instead`,);return false;}@@ -1083,11 +1409,19 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {if (!hasBroadManage) {return res.status(403).json({ error: 'Insufficient permissions' });}- return res.status(200).json({ message: 'No actionable field entries provided' });+ return noopResponse(+ res,+ 'No actionable field entries provided',+ principalType,+ principalId,+ expected.value,+ );}if (!hasBroadManage) {- const sections = [...new Set(validEntries.map((e) => getTopLevelSection(e.fieldPath)))];+ const sections = [+ ...new Set(validEntries.map(({ target }) => getTopLevelSection(target.fieldPath))),+ ];const allowed = await Promise.all(sections.map((s) => hasConfigCapability(user, s as ConfigSection, 'manage')),);@@ -1099,14 +1433,23 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}}- const seen = new Set<string>();+ const seenPaths = new Set<string>();+ const seenSegments = new Set<string>();const fields: Record<string, unknown> = {};- for (const entry of validEntries) {- if (seen.has(entry.fieldPath)) {- return res.status(400).json({ error: `Duplicate fieldPath: ${entry.fieldPath}` });+ 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}` });}- seen.add(entry.fieldPath);- fields[entry.fieldPath] = entry.value;+ seenPaths.add(target.fieldPath);+ fields[target.fieldPath] = value;}if (priority != null && !hasBroadManage) {@@ -1116,51 +1459,72 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const requestedPriority = hasBroadManage ? priority : undefined;- const [existing, baseYaml] = await Promise.all([- findConfigByPrincipal(principalType, principalId, { includeInactive: true }),- getBaseYamlConfig(user.tenantId),- ]);+ const baseYaml = await getBaseYamlConfig(user.tenantId);const encryptedFields = encryptConfigSecretFields(fields);- const fieldIssues = getConfigFieldIssues(encryptedFields, baseYaml, existing);- if (fieldIssues.length > 0) {- return invalidOverrideResponse(res, fieldIssues);- }- const preservedFields = preservePatchedConfigSecretFields(- encryptedFields,- existing?.overrides,- );- const reentryIssues = getPatchReentryIssues(existing, fields, preservedFields);- if (reentryIssues.length > 0) {- return secretReentryResponse(res, reentryIssues);- }- const precondition = Object.keys(fields).some(isWebSearchBindingPath)- ? readVersion(existing)- : undefined;-- const config = await patchConfigFields(- principalType,- principalId,- principalModel(principalType),- preservedFields,- requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,- undefined,- precondition,- );- if (!config && precondition) {- return versionConflictResponse(res);+ const requested = validEntries.map(({ target, value }) => ({+ segments: target.segments,+ value,+ }));++ type PatchStop = { issues: ConfigOverrideIssue[] } | { reentry: SecretReentryIssue[] };+ let outcome;+ try {+ outcome = await runConfigMutation<PatchStop>(+ {+ read: () => readStoredConfig(principalType, principalId),+ write: (draft, revision) =>+ writeConfigDocument(principalType, principalId, draft, revision),+ },+ (stored) => {+ /** Secrets an object omits are kept before validation sees the document. */+ const writes = toOrderedWrites(+ validEntries,+ preservePatchedConfigSecretFields(encryptedFields, stored?.overrides),+ );+ const fieldIssues = getConfigFieldIssues(writes, baseYaml, stored);+ if (fieldIssues.length > 0) {+ return { draft: null, result: { issues: fieldIssues } };+ }+ const state = setConfigFields(toConfigOverrideState(stored), writes);+ /** A changed URL beside a stored key that stays needs that key entered again. */+ const reentry = getPatchReentryIssues(stored, requested, state);+ if (reentry.length > 0) {+ return { draft: null, result: { reentry } };+ }+ return {+ draft: {+ principalModel: principalModel(principalType),+ priority: requestedPriority ?? stored?.priority ?? DEFAULT_CONFIG_PRIORITY,+ overrides: state.overrides,+ tombstones: state.tombstones,+ isActive: stored?.isActive ?? true,+ },+ };+ },+ { expectedRevision: expected.value },+ );+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);}- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after patch:', err),- );- if (config) {- await emitAudit(req, {- action: config.configVersion === 1 ? 'config.created' : 'config.updated',- target: configTarget(principalType, principalId),- metadata: { operation: 'patch', fieldPaths: Object.keys(fields).join(',') },- });+ if (!outcome.written) {+ const stop = outcome.result;+ return 'reentry' in stop+ ? secretReentryResponse(res, stop.reentry)+ : invalidOverrideResponse(res, stop.issues);}- return res.status(200).json({ config: config ? redactConfigForResponse(config) : config });++ const { record: config, previous } = outcome;+ await invalidateCaches(user.tenantId, 'patch');+ await emitAudit(req, {+ action: previous == null ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: {+ operation: 'patch',+ fieldPaths: validEntries.map(({ target }) => describeFieldTarget(target)).join(','),+ },+ });+ return res.status(200).json({ config: redactConfigForResponse(config) });} catch (error) {if (isFieldNameRejection(error)) {return unstorableKeyResponse(res, 'patchConfigField');@@ -1184,12 +1548,17 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: `Invalid principalType: ${principalType}` });}- const { fieldPath, priority } = req.body as {- fieldPath?: string;+ const {+ fieldPath: rawFieldPath,+ segments,+ priority,+ } = req.body as {+ fieldPath?: unknown;+ segments?: unknown;priority?: number;};- if (!fieldPath || typeof fieldPath !== 'string') {+ if (segments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {return res.status(400).json({ error: 'fieldPath is required' });}@@ -1197,9 +1566,25 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: 'priority must be a non-negative number' });}- if (!isValidFieldPath(fieldPath)) {- return res.status(400).json({ error: `Invalid or unsafe field path: ${fieldPath}` });+ const expected = readExpectedRevision(+ (req.body as { expectedRevision?: unknown }).expectedRevision,+ );+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);}++ const read = readFieldTarget(rawFieldPath, segments);+ if (!read.ok) {+ return fieldTargetErrorResponse(res, read);+ }+ /** Tombstones are stored as dotted paths, so they cannot name a key that contains a dot. */+ if (!read.target.dotFree) {+ return fieldTargetErrorResponse(res, {+ error: 'A tombstone cannot name a key that contains a dot',+ reason: 'dotted_segment',+ });+ }+ const { fieldPath } = read.target;const secretInputError = getConfigSecretInputError(fieldPath, undefined);if (secretInputError) {return res.status(400).json({ error: secretInputError });@@ -1231,20 +1616,38 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {logger.warn(`[adminConfig] Ignoring tombstone for base-only config field "${fieldPath}" - configure it in librechat.yaml instead`,);- return res.status(200).json({ message: 'No actionable field path provided' });+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}if (isInterfacePermissionPath(fieldPath)) {logger.warn(`[adminConfig] Ignoring tombstone for interface permission field "${fieldPath}" — use role permissions instead`,);- return res.status(200).json({ message: 'No actionable field path provided' });+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(section)) {logger.warn(`[adminConfig] Ignoring dedicated tenant-wide config tombstone "${fieldPath}" in the generic config API`,);- return res.status(200).json({ message: 'No actionable field path provided' });+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}if (priority != null && !hasBroadManage) {@@ -1254,69 +1657,43 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const requestedPriority = hasBroadManage ? priority : undefined;- const binding = isWebSearchBindingPath(fieldPath);- const existing =- requestedPriority == null || binding- ? await findConfigByPrincipal(principalType, principalId, { includeInactive: true })- : null;- const reentryIssues = getRemovalReentryIssues(existing, fieldPath, true);- if (reentryIssues.length > 0) {- return secretReentryResponse(res, reentryIssues);- }- const precondition = binding ? readVersion(existing) : undefined;-- let config: IConfig | null = null;- /** Each write bumps configVersion, so creation is read off the first write only. */- let created = false;+ let config: ConfigRecord;try {- const paths = getConfigSecretMutationPaths(fieldPath);- for (let i = 0; i < paths.length; i++) {- const fieldConfig = await writeConfigTombstone(+ if (isWebSearchBindingPath(fieldPath)) {+ const outcome = await removeWebSearchBinding(principalType,principalId,- principalModel(principalType),- paths[i],- requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,- undefined,- i === 0 ? precondition : undefined,+ fieldPath,+ { tombstone: true, priority: requestedPriority },+ expected.value,);- if (!fieldConfig && i === 0 && precondition) {- return versionConflictResponse(res);+ if (!outcome.written) {+ return secretReentryResponse(res, outcome.result ?? []);}- if (fieldConfig) {- created ||= config == null && fieldConfig.configVersion === 1;- config = fieldConfig;- }- }- } catch (writeError) {- /** An earlier path in the loop may already have been written. */- if (config) {- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error(- '[adminConfig] Cache invalidation failed after partial write:',- getSafeErrorMetadata(err),- ),+ config = outcome.record;+ } else {+ /** A secret and its preview companion are suppressed together, in one write. */+ config = await writeConfigTombstone(+ principalType,+ principalId,+ principalModel(principalType),+ getConfigSecretMutationPaths(fieldPath),+ requestedPriority,+ undefined,+ { expectedRevision: expected.value },);- await emitAudit(req, {- action: created ? 'config.created' : 'config.updated',- target: configTarget(principalType, principalId),- metadata: { operation: 'tombstone', fieldPath, partial: true },- });}- throw writeError;+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);}- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after field tombstone:', err),- );- if (config) {- await emitAudit(req, {- action: created ? 'config.created' : 'config.updated',- target: configTarget(principalType, principalId),- metadata: { operation: 'tombstone', fieldPath },- });- }- return res.status(200).json({ config: config ? redactConfigForResponse(config) : config });+ await invalidateCaches(user.tenantId, 'field tombstone');+ await emitAudit(req, {+ action: config.configVersion === 1 ? 'config.created' : 'config.updated',+ target: configTarget(principalType, principalId),+ metadata: { operation: 'tombstone', fieldPath },+ });+ return res.status(200).json({ config: redactConfigForResponse(config) });} catch (error) {logger.error('[adminConfig] tombstoneConfigField error:', getSafeErrorMetadata(error));return res.status(500).json({ error: 'Failed to tombstone config field' });@@ -1325,6 +1702,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {/*** DELETE /:principalType/:principalId/fields?fieldPath=dotted.path+ * (or `?segments=<JSON array>` for a path whose keys contain dots)*/async function deleteConfigField(req: ServerRequest, res: Response): Promise<Response> {try {@@ -1336,15 +1714,26 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: `Invalid principalType: ${principalType}` });}- const fieldPath = req.query.fieldPath as string | undefined;+ const { fieldPath: rawFieldPath, segments: rawSegments } = req.query;- if (!fieldPath || typeof fieldPath !== 'string') {+ if (rawSegments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {return res.status(400).json({ error: 'fieldPath query parameter is required' });}- if (!isValidFieldPath(fieldPath)) {- return res.status(400).json({ error: `Invalid or unsafe field path: ${fieldPath}` });+ const expected = readExpectedRevision(req.query.expectedRevision);+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);}++ const read = readFieldTarget(+ rawFieldPath,+ rawSegments === undefined ? undefined : readSegmentsQuery(rawSegments),+ );+ if (!read.ok) {+ return fieldTargetErrorResponse(res, read);+ }+ const { target } = read;+ const { fieldPath } = target;const secretInputError = getConfigSecretInputError(fieldPath, undefined);if (secretInputError) {return res.status(400).json({ error: secretInputError });@@ -1376,82 +1765,82 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {logger.warn(`[adminConfig] Ignoring delete for base-only config field "${fieldPath}" - configure it in librechat.yaml instead`,);- return res.status(200).json({ message: 'No actionable field path provided' });+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(section)) {logger.warn(`[adminConfig] Ignoring dedicated tenant-wide config delete "${fieldPath}" in the generic config API`,);- return res.status(200).json({ message: 'No actionable field path provided' });+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}if (isInterfacePermissionPath(fieldPath)) {logger.warn(`[adminConfig] Ignoring delete for interface permission field "${fieldPath}" — use role permissions instead`,);- return res.status(200).json({ message: 'No actionable field path provided' });- }-- const binding = isWebSearchBindingPath(fieldPath);- const existing = binding- ? await findConfigByPrincipal(principalType, principalId, { includeInactive: true })- : undefined;- if (binding && !existing) {- return res.status(404).json({ error: 'Config not found' });- }- const reentryIssues = getRemovalReentryIssues(existing, fieldPath, false);- if (reentryIssues.length > 0) {- return secretReentryResponse(res, reentryIssues);+ return noopResponse(+ res,+ 'No actionable field path provided',+ principalType,+ principalId,+ expected.value,+ );}- const precondition = binding ? readVersion(existing) : undefined;- let config: IConfig | null = null;+ let config: ConfigRecord | null;try {- const paths = getConfigSecretMutationPaths(fieldPath);- for (let i = 0; i < paths.length; i++) {- const fieldConfig = await unsetConfigField(+ if (target.dotFree && isWebSearchBindingPath(fieldPath)) {+ const outcome = await removeWebSearchBinding(principalType,principalId,- paths[i],- undefined,- i === 0 ? precondition : undefined,+ fieldPath,+ { tombstone: false },+ expected.value,);- if (!fieldConfig && i === 0 && precondition) {- return versionConflictResponse(res);- }- if (fieldConfig) {- config = fieldConfig;+ if (!outcome.written && outcome.result) {+ return secretReentryResponse(res, outcome.result);}- }- } catch (writeError) {- /** An earlier path in the loop may already have been written. */- if (config) {- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error(- '[adminConfig] Cache invalidation failed after partial write:',- getSafeErrorMetadata(err),- ),+ config = outcome.written ? outcome.record : null;+ } else {+ /**+ * A secret and its preview companion are removed together, in one write. A path with+ * a dotted key never names a secret, so it goes by its segments alone.+ */+ config = await unsetConfigField(+ principalType,+ principalId,+ target.dotFree+ ? getConfigSecretMutationPaths(fieldPath)+ : [{ segments: target.segments }],+ undefined,+ { expectedRevision: expected.value },);- await emitAudit(req, {- action: 'config.updated',- target: configTarget(principalType, principalId),- metadata: { operation: 'unset', fieldPath, partial: true },- });}- throw writeError;+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);}if (!config) {return res.status(404).json({ error: 'Config not found' });}- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after field delete:', err),- );+ await invalidateCaches(user.tenantId, 'field delete');await emitAudit(req, {action: 'config.updated',target: configTarget(principalType, principalId),- metadata: { operation: 'unset', fieldPath },+ metadata: { operation: 'unset', fieldPath: describeFieldTarget(target) },});return res.status(200).json({ config: redactConfigForResponse(config) });} catch (error) {@@ -1474,6 +1863,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: `Invalid principalType: ${principalType}` });}+ const expected = readExpectedRevision(req.query.expectedRevision);+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);+ }+const user = getCapabilityUser(req);if (!user) {return res.status(401).json({ error: 'Authentication required' });@@ -1492,9 +1886,15 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(403).json({ error: 'Insufficient permissions' });}- const config = await deleteConfig(principalType, principalId, undefined, {- expectEmpty: !hasBroadManage,- });+ let config: ConfigRecord | null;+ try {+ config = await deleteConfig(principalType, principalId, undefined, {+ expectEmpty: !hasBroadManage,+ expectedRevision: expected.value,+ });+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);+ }if (!config) {if (!hasBroadManage) {const exists = await findConfigByPrincipal(principalType, principalId, {@@ -1507,9 +1907,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(404).json({ error: 'Config not found' });}- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after config delete:', err),- );+ await invalidateCaches(user.tenantId, 'config delete');await emitAudit(req, {action: 'config.deleted',severity: 'warning',@@ -1541,6 +1939,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(400).json({ error: 'isActive boolean is required' });}+ const expected = readExpectedRevision(+ (req.body as { expectedRevision?: unknown }).expectedRevision,+ );+ if (!expected.ok) {+ return invalidExpectedRevisionResponse(res);+ }+const user = getCapabilityUser(req);if (!user) {return res.status(401).json({ error: 'Authentication required' });@@ -1559,9 +1964,15 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {return res.status(403).json({ error: 'Insufficient permissions' });}- const toggled = await toggleConfigActiveTracked(principalType, principalId, isActive, {- expectEmpty: !hasBroadManage,- });+ let toggled: { config: ConfigRecord; changed: boolean } | null;+ try {+ toggled = await toggleConfigActiveTracked(principalType, principalId, isActive, {+ expectEmpty: !hasBroadManage,+ expectedRevision: expected.value,+ });+ } catch (error) {+ return await writeFailureResponse(res, error, principalType, principalId);+ }if (!toggled) {if (!hasBroadManage) {const exists = await findConfigByPrincipal(principalType, principalId, {@@ -1575,9 +1986,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {}const { config, changed } = toggled;- invalidateConfigCaches?.(user.tenantId)?.catch((err) =>- logger.error('[adminConfig] Cache invalidation failed after toggle:', err),- );+ await invalidateCaches(user.tenantId, 'toggle');/** A retry that finds the requested state already set changed nothing and is not recorded. */if (changed) {await emitAudit(req, {diff --git a/packages/api/src/admin/groups.ts b/packages/api/src/admin/groups.tsindex 0697594079..474dc2a2d1 100644--- a/packages/api/src/admin/groups.ts+++ b/packages/api/src/admin/groups.ts@@ -4,7 +4,7 @@ import { logger, isValidObjectIdString } from '@librechat/data-schemas';import type {IGroup,IUser,- IConfig,+ ConfigRecord,CreateGroupRequest,UpdateGroupRequest,GroupFilterOptions,@@ -84,21 +84,21 @@ export interface AdminGroupsDeps {deleteConfig: (principalType: PrincipalType,principalId: string | Types.ObjectId,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;deleteAclEntries: (filter: {principalType: PrincipalType;principalId: string | Types.ObjectId;}) => Promise<DeleteResult>;/** Re-creates a removed config override in full, only if none exists, when the group* deletion cannot finish. ACL entries are never restored. Resolves to whether it inserted. */- restoreConfig?: (snapshot: Record<string, unknown>) => Promise<boolean>;+ restoreConfig?: (snapshot: ConfigRecord) => Promise<boolean>;/** Reads the override before it is removed, so a rejected removal whose commit was* lost in transit can still be put back. */findConfigByPrincipal?: (principalType: PrincipalType,principalId: string,options?: { includeInactive?: boolean },- ) => Promise<object | null>;+ ) => Promise<ConfigRecord | null>;/** Optional audit emission for group mutations; fail-open unless `auditFailClosed`. */recordAuditEntry?: RecordAuditEntry;/** When true, a failed audit write surfaces as a 5xx after the mutation has@@ -424,10 +424,9 @@ export function createAdminGroupsHandlers(deps: AdminGroupsDeps): {if (!config) {return;}- const snapshot = (config as { toObject?: () => unknown }).toObject?.() ?? config;let restored: boolean;try {- restored = await restoreConfig(snapshot as Record<string, unknown>);+ restored = await restoreConfig(config);restoreFailed = false;} catch (error) {restoreFailed = true;diff --git a/packages/api/src/admin/langfuse.handler.spec.ts b/packages/api/src/admin/langfuse.handler.spec.tsindex 9327121fbc..a955cf7d37 100644--- a/packages/api/src/admin/langfuse.handler.spec.ts+++ b/packages/api/src/admin/langfuse.handler.spec.ts@@ -7,6 +7,7 @@ import type { ServerRequest } from '~/types/http';// Loaded via dynamic import in beforeAll so the crypto module initializes// after CREDS_KEY is set above (encryptV3 reads the key at module load).let encryptV3: typeof import('@librechat/data-schemas').encryptV3;+let ConfigRevisionConflictError: typeof import('@librechat/data-schemas').ConfigRevisionConflictError;let createAdminLangfuseHandlers: typeof import('./langfuse').createAdminLangfuseHandlers;let getLangfuseDestinationId: typeof import('../langfuse/destinations').getLangfuseDestinationId;const realFetch = global.fetch;@@ -20,7 +21,7 @@ function projectResponse(projectId = 'project-1') {}beforeAll(async () => {- ({ encryptV3 } = await import('@librechat/data-schemas'));+ ({ encryptV3, ConfigRevisionConflictError } = await import('@librechat/data-schemas'));({ createAdminLangfuseHandlers } = await import('./langfuse'));({ getLangfuseDestinationId } = await import('../langfuse/destinations'));});@@ -834,6 +835,38 @@ describe('createAdminLangfuseHandlers', () => {});});+ describe('updateConnection write conflict', () => {+ it('answers 409 when the base config keeps changing under the write', async () => {+ const recordAuditEntry = jest.fn().mockResolvedValue(undefined);+ const { handlers, deps } = createHandlers({+ patchConfigFields: jest.fn().mockRejectedValue(new ConfigRevisionConflictError('cfg1:4')),+ recordAuditEntry,+ });+ const res = mockRes();++ await handlers.updateConnection(+ mockReq({+ body: {+ enabled: true,+ destination: 'eu',+ publicKey: 'pk-lf-1',+ secretKey: 'sk-lf-secret',+ },+ }),+ res,+ );++ expect(res.statusCode).toBe(409);+ expect(res.body).toEqual({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ });+ expect(deps.toggleConfigActive).not.toHaveBeenCalled();+ expect(deps.recordConnectionUpdate).not.toHaveBeenCalled();+ expect(recordAuditEntry).not.toHaveBeenCalled();+ });+ });+describe('updateConnection activation failure', () => {it('still audits and invalidates caches when activation fails after the patch committed', async () => {const inactive = {diff --git a/packages/api/src/admin/langfuse.ts b/packages/api/src/admin/langfuse.tsindex ea6721cb1f..e693853073 100644--- a/packages/api/src/admin/langfuse.ts+++ b/packages/api/src/admin/langfuse.ts@@ -1,5 +1,9 @@import { PrincipalType, PrincipalModel } from 'librechat-data-provider';-import { logger, BASE_CONFIG_PRINCIPAL_ID } from '@librechat/data-schemas';+import {+ logger,+ BASE_CONFIG_PRINCIPAL_ID,+ isConfigRevisionConflict,+} from '@librechat/data-schemas';import type {TCustomConfig,TLangfuseConnectionStatus,@@ -9,8 +13,7 @@ import type {TLangfuseConnectionTestResponse,TLangfuseSessionLinkResponse,} from 'librechat-data-provider';-import type { IConfig, MessageMethods } from '@librechat/data-schemas';-import type { Types, ClientSession } from 'mongoose';+import type { ConfigRecord, MessageMethods } from '@librechat/data-schemas';import type { Response } from 'express';import type { LangfuseTenantDestination } from '~/langfuse/tenantDestinations';import type { ServerRequest } from '~/types/http';@@ -24,6 +27,7 @@ import { decryptConfigSecret, encryptConfigSecretFields } from './secrets';import { scopeHeadersToDestination } from '~/langfuse/destinations';import { isLangfuseConnectionAvailable } from '~/langfuse/policy';import { resolveLangfuseSession } from '~/langfuse/session';+import { getSafeErrorMetadata } from '~/utils/errors';import { createAdminAuditEmitter } from './audit';import { mergeHeaders } from '~/utils/headers';@@ -54,24 +58,22 @@ export interface LangfuseConnectionEvent {export interface AdminLangfuseDeps {findConfigByPrincipal: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,options?: { includeInactive?: boolean },- session?: ClientSession,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;+ /** Sets the fields in one compare-and-swap write, re-reading on a concurrent change. */patchConfigFields: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,principalModel: PrincipalModel,fields: Record<string, unknown>,priority: number,- session?: ClientSession,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;toggleConfigActive: (principalType: PrincipalType,- principalId: string | Types.ObjectId,+ principalId: string,isActive: boolean,- session?: ClientSession,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;getMessages: MessageMethods['getMessages'];invalidateConfigCaches?: (tenantId?: string) => Promise<void>;recordConnectionUpdate?: (event: LangfuseConnectionEvent) => void;@@ -87,12 +89,12 @@ function getTenantId(req: ServerRequest): string | undefined {/** Reads from the stored override tree, so this is `TCustomConfig`'s* `DeepPartial` view of the section rather than the standalone* `LangfuseConfig` — record-valued fields carry optional values here. */-function readStoredLangfuse(config: IConfig | null): TCustomConfig['langfuse'] {+function readStoredLangfuse(config: ConfigRecord | null): TCustomConfig['langfuse'] {const overrides = config?.overrides as Partial<TCustomConfig> | undefined;return overrides?.langfuse;}-function buildStatus(config: IConfig | null): TLangfuseConnectionStatus {+function buildStatus(config: ConfigRecord | null): TLangfuseConnectionStatus {const stored = readStoredLangfuse(config);const configured = Boolean(stored?.publicKey && stored?.secretKey);return {@@ -308,7 +310,7 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {logPrefix: '[adminLangfuse]',});- function findBaseConfig(options?: { includeInactive?: boolean }): Promise<IConfig | null> {+ function findBaseConfig(options?: { includeInactive?: boolean }): Promise<ConfigRecord | null> {return options? findConfigByPrincipal(PrincipalType.ROLE, BASE_CONFIG_PRINCIPAL_ID, options): findConfigByPrincipal(PrincipalType.ROLE, BASE_CONFIG_PRINCIPAL_ID);@@ -500,11 +502,17 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {changes,verification_result: verificationResult,});- invalidateConfigCaches?.(getTenantId(req))?.catch((err) =>- logger.error('[adminLangfuse] Cache invalidation failed after update:', err),- );+ /** Settled before responding, so the caller's next read sees the update. */+ try {+ await invalidateConfigCaches?.(getTenantId(req));+ } catch (err) {+ logger.error(+ '[adminLangfuse] Cache invalidation failed after update:',+ getSafeErrorMetadata(err),+ );+ }- /** Recorded after the cache invalidation starts so audit latency never delays it. Records which parts changed, never the keys themselves. */+ /** Recorded after the cache invalidation so audit latency never delays it. Records which parts changed, never the keys themselves. */await emitAudit(req, {action: 'langfuse.updated',severity: 'warning',@@ -522,6 +530,12 @@ export function createAdminLangfuseHandlers(deps: AdminLangfuseDeps): {}return res.status(200).json(status);} catch (error) {+ if (isConfigRevisionConflict(error)) {+ return res.status(409).json({+ error: 'Config was modified by another request',+ code: 'CONFIG_VERSION_CONFLICT',+ });+ }logger.error('[adminLangfuse] updateConnection error:', error);return res.status(500).json({ error: 'Failed to update Langfuse connection' });}diff --git a/packages/api/src/admin/meta.spec.ts b/packages/api/src/admin/meta.spec.tsindex 79001ab72d..036cae7c60 100644--- a/packages/api/src/admin/meta.spec.ts+++ b/packages/api/src/admin/meta.spec.ts@@ -4,10 +4,14 @@ import mongoSanitize from 'express-mongo-sanitize';import {loadWebSearchConfig,mergeConfigOverrides,+ createConfigOperations,getConfigOverrideIssues,+ isConfigOverrideStateEmpty,} from '@librechat/data-schemas';import {Constants,+ PrincipalType,+ PrincipalModel,configSchema,RerankerTypes,SearchProviders,@@ -23,14 +27,17 @@ import {import type {AdminConfigFeatureFlag,AdminConfigMeta,+ ConfigRecord,+ ConfigStore,+ ConfigDraft,AppConfig,- IConfig,} from '@librechat/data-schemas';import type { Request, Response } from 'express';import type { ServerRequest } from '~/types/http';import type { AdminConfigDeps } from './config';import { createRequestSanitizer, rejectUnsafeConfigKeys } from '~/middleware/sanitize';import { redactConfigSecrets, encryptConfigSecretFields } from './secrets';+import { createAppConfigService } from '~/app/service';import { createAdminConfigHandlers } from './config';import { ADMIN_CONFIG_FEATURES } from './meta';import { loadWebSearchAuth } from '~/web';@@ -42,7 +49,7 @@ jest.mock('@librechat/data-schemas', () => {});type Doc = Record<string, unknown>;-type ResponseBody = { config?: { overrides: Doc }; [key: string]: unknown };+type ResponseBody = { config?: { overrides: Doc; revision?: string }; [key: string]: unknown };type MockRes = Response & { statusCode: number; body: ResponseBody | undefined };type MockReqInit = Omit<Partial<ServerRequest>, 'body'> & { body?: object };type PatchEntry = { fieldPath: string; value: unknown };@@ -74,8 +81,10 @@ function createHandlers(overrides: Partial<AdminConfigDeps> = {}) {return createAdminConfigHandlers({listAllConfigs: jest.fn().mockResolvedValue([]),findConfigByPrincipal: jest.fn().mockResolvedValue(null),- upsertConfig: jest.fn().mockResolvedValue(null),- patchConfigFields: jest.fn().mockResolvedValue(null),+ writeConfigDocument: jest.fn(+ async (_type: string, _id: string, draft: ConfigDraft): Promise<ConfigRecord> =>+ storedConfig(draft.overrides ?? {}),+ ),tombstoneConfigField: jest.fn().mockResolvedValue(null),unsetConfigField: jest.fn().mockResolvedValue(null),deleteConfig: jest.fn().mockResolvedValue(null),@@ -106,14 +115,17 @@ async function patch(return res;}-function storedConfig(overrides: Doc): IConfig {+function storedConfig(overrides: Doc): ConfigRecord {return {+ _id: 'c1',principalType: 'role',principalId: 'r1',priority: 10,overrides,+ tombstones: [],isActive: true,- } as Partial<IConfig> as IConfig;+ configVersion: 1,+ } as Partial<ConfigRecord> as ConfigRecord;}function setIn(target: Doc, segments: string[], value: unknown): Doc {@@ -123,6 +135,11 @@ function setIn(target: Doc, segments: string[], value: unknown): Doc {return { ...target, [head]: rest.length === 0 ? value : setIn(parent, rest, value) };}+/** Lets every pending promise settle, so a handler runs until it waits on something unresolved. */+function settle(): Promise<void> {+ return new Promise((resolve) => setImmediate(resolve));+}+function getIn(target: object, path: string): unknown {return path.split('.')@@ -162,7 +179,10 @@ 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([+ 'awaitedInvalidation','dottedKeys',+ 'expectedRevision',+ 'prunesEmptyParents','readFilteredWriteResponses','sectionAllowlist','webSearchStoredKeys',@@ -270,12 +290,12 @@ describe('meta rules equal the rules the server applies', () => {});it('drops writes to base-only sections', async () => {- const patchConfigFields = jest.fn();+ const writeConfigDocument = jest.fn();for (const section of meta.rules.baseOnlySections) {- const res = await patch([{ fieldPath: `${section}.x`, value: 1 }], { patchConfigFields });- expect(res.body).toEqual({ message: 'No actionable field entries provided' });+ const res = await patch([{ fieldPath: `${section}.x`, value: 1 }], { writeConfigDocument });+ expect(res.body).toEqual({ message: 'No actionable field entries provided', revision: null });}- expect(patchConfigFields).not.toHaveBeenCalled();+ expect(writeConfigDocument).not.toHaveBeenCalled();});it('requires the listed merge key on items of every merged array', () => {@@ -340,7 +360,7 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {async (_user, section, verb = 'manage') => verb === 'manage' && section === 'endpoints',),getReadableConfigSections: jest.fn().mockResolvedValue({ broad: false, sections: new Set() }),- patchConfigFields: jest.fn().mockResolvedValue(+ writeConfigDocument: jest.fn().mockResolvedValue(storedConfig({endpoints: { openAI: { titleModel: 'gpt-4o-mini' } },memory: { disabled: true },@@ -389,6 +409,128 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {rebinding.statusCode === 400 && rebinding.body?.code === 'CONFIG_SECRET_REENTRY_REQUIRED';return encrypted && usesStoredKey && requiresReentry;},+ async expectedRevision() {+ const writeConfigDocument = jest.fn(+ async (+ _type: string,+ _id: string,+ draft: ConfigDraft,+ _expected: string,+ ): Promise<ConfigRecord> => ({ ...storedConfig(draft.overrides ?? {}), configVersion: 2 }),+ );+ const write = async (expectedRevision: unknown) => {+ const res = mockRes();+ await createHandlers({+ findConfigByPrincipal: jest+ .fn()+ .mockResolvedValue(storedConfig({ interface: { customWelcome: 'v1' } })),+ writeConfigDocument,+ }).patchConfigField(+ mockReq({+ params: { principalType: 'role', principalId: 'r1' },+ body: {+ entries: [{ fieldPath: 'interface.customWelcome', value: 'v2' }],+ expectedRevision,+ },+ }),+ res,+ );+ return res;+ };++ const stale = await write('c1:0');+ const malformed = await write('c1');+ const current = await write('c1:1');+ return (+ stale.statusCode === 409 &&+ stale.body?.code === 'CONFIG_VERSION_CONFLICT' &&+ stale.body?.currentRevision === 'c1:1' &&+ malformed.statusCode === 400 &&+ malformed.body?.code === 'INVALID_EXPECTED_REVISION' &&+ current.statusCode === 200 &&+ current.body?.config?.revision === 'c1:2' &&+ writeConfigDocument.mock.calls.length === 1 &&+ writeConfigDocument.mock.calls[0][3] === 'c1:1'+ );+ },+ async prunesEmptyParents() {+ let record: ConfigRecord = storedConfig({+ balance: { startBalance: 5 },+ interface: { theme: { name: 'x' } },+ endpoints: { custom: [{ name: 'gw', headers: { A: 'a' } }] },+ });+ const store = {+ read: async () => record,+ write: async (_principal: unknown, draft: ConfigDraft) =>+ (record = { ...record, ...draft, configVersion: record.configVersion + 1 }),+ } as Partial<ConfigStore> as ConfigStore;+ const operations = createConfigOperations(store);+ const principal = { principalType: PrincipalType.ROLE, principalId: 'r1' };++ await operations.unsetFields(principal, [+ 'balance.startBalance',+ 'endpoints.custom.0.headers.A',+ ]);+ await operations.tombstoneFields(principal, PrincipalModel.ROLE, 'interface.theme.name');+ return (+ JSON.stringify(record.overrides) ===+ JSON.stringify({ endpoints: { custom: [{ name: 'gw' }] } }) &&+ record.tombstones.includes('interface.theme.name') &&+ isConfigOverrideStateEmpty({ overrides: { balance: {} }, tombstones: [] })+ );+ },+ async awaitedInvalidation() {+ let release: () => void = () => undefined;+ const invalidateConfigCaches = jest.fn(+ () => new Promise<void>((resolve) => (release = resolve)),+ );+ const res = mockRes();+ const written = createHandlers({ invalidateConfigCaches }).patchConfigField(+ mockReq({+ params: { principalType: 'role', principalId: 'r1' },+ body: { entries: [{ fieldPath: 'interface.customWelcome', value: 'hi' }] },+ }),+ res,+ );+ await settle();+ const held = invalidateConfigCaches.mock.calls.length === 1 && res.body === undefined;+ release();+ await written;++ const getAppConfig = jest.fn().mockResolvedValue({ config: {} });+ await createHandlers({ getAppConfig }).getBaseConfig(mockReq(), mockRes());+ const bypassed = getAppConfig.mock.calls.some(+ ([options]) => (options as { bypassOverrideCache?: boolean }).bypassOverrideCache === true,+ );++ const entries = new Map<string, unknown>();+ let releaseRead: (configs: ConfigRecord[]) => void = () => undefined;+ const getApplicableConfigs = jest+ .fn()+ .mockImplementationOnce(() => new Promise((resolve) => (releaseRead = resolve)))+ .mockResolvedValue([]);+ const service = createAppConfigService({+ loadBaseConfig: async () => ({ config: {} }) as AppConfig,+ setCachedTools: async () => undefined,+ getCache: () => ({+ get: async (key: string) => entries.get(key),+ set: async (key: string, value: unknown) => entries.set(key, value),+ delete: async (key: string) => entries.delete(key),+ }),+ cacheKeys: { APP_CONFIG: 'app_config' },+ getApplicableConfigs,+ getUserPrincipals: async () => [],+ });+ const merging = service.getAppConfig({ role: 'ADMIN' });+ await settle();+ await service.clearOverrideCache();+ releaseRead([storedConfig({ x: 'stale' })]);+ await merging;+ await service.getAppConfig({ role: 'ADMIN' });+ const dropsStaleMerge = getApplicableConfigs.mock.calls.length === 2;++ return held && res.statusCode === 200 && bypassed && dropsStaleMerge;+ },};describe('meta feature flags', () => {diff --git a/packages/api/src/admin/meta.ts b/packages/api/src/admin/meta.tsindex 022c482fa2..331054c3c2 100644--- a/packages/api/src/admin/meta.ts+++ b/packages/api/src/admin/meta.ts@@ -24,6 +24,9 @@ export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {sectionAllowlist: false,readFilteredWriteResponses: false,webSearchStoredKeys: true,+ expectedRevision: true,+ prunesEmptyParents: true,+ awaitedInvalidation: true,};/**diff --git a/packages/api/src/admin/roles.ts b/packages/api/src/admin/roles.tsindex 64bc58d6a3..60de35dabc 100644--- a/packages/api/src/admin/roles.ts+++ b/packages/api/src/admin/roles.ts@@ -3,7 +3,7 @@ import { logger, isValidObjectIdString, RoleConflictError } from '@librechat/datimport type {IRole,IUser,- IConfig,+ ConfigRecord,AdminMember,ISystemGrant,AuditSeverity,@@ -127,7 +127,7 @@ export interface AdminRolesDeps {deleteConfig: (principalType: PrincipalType,principalId: string | Types.ObjectId,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;/** Removes all ACL entries scoped to this principal. */deleteAclEntries: (filter: {principalType: PrincipalType;@@ -156,10 +156,10 @@ export interface AdminRolesDeps {principalType: PrincipalType,principalId: string,options?: { includeInactive?: boolean },- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;/** Re-creates a deleted config document in full, only if none exists. Resolves* to whether it inserted. */- restoreConfig?: (snapshot: Record<string, unknown>) => Promise<boolean>;+ restoreConfig?: (snapshot: ConfigRecord) => Promise<boolean>;/** Optional audit emission for role mutations and the grants removed by the* role-deletion cascade. Failure is logged unless `auditFailClosed` is set. */recordAuditEntry?: RecordAuditEntry;@@ -576,8 +576,7 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps): {return;}/** Insert-only: an override written after the snapshot is kept. */- const plain = (config as { toObject?: () => unknown }).toObject?.() ?? config;- const restored = await restoreConfig(plain as Record<string, unknown>);+ const restored = await restoreConfig(config);if (!restored) {logger.warn('[adminRoles] config restore skipped, override exists:', name);}diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.tsindex 93d1fd0bce..efd48f0a4d 100644--- a/packages/api/src/admin/secrets.integration.spec.ts+++ b/packages/api/src/admin/secrets.integration.spec.ts@@ -271,8 +271,7 @@ beforeAll(async () => {createAdminConfigHandlers({listAllConfigs: methods.listAllConfigs,findConfigByPrincipal,- upsertConfig: methods.upsertConfig,- patchConfigFields: methods.patchConfigFields,+ writeConfigDocument: methods.writeConfigDocument,tombstoneConfigField: methods.tombstoneConfigField,unsetConfigField: methods.unsetConfigField,deleteConfig: methods.deleteConfig,@@ -835,6 +834,19 @@ describe('config secret registry — real handlers against a real Config collectexpect(await readRawConfig(principalId)).toEqual(before);});+ it('judges a patch by the URL it stores when a later entry replaces an earlier one', async () => {+ const principalId = nextPrincipalId();+ const before = await storeSearxng(principalId);++ const res = await patch(principalId, [+ { fieldPath: 'webSearch.searxngInstanceUrl', value: STORED_URL },+ { fieldPath: 'webSearch', value: { searxngInstanceUrl: NEW_URL } },+ ]);++ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));+ expect(await readRawConfig(principalId)).toEqual(before);+ });+it('rejects a section patch that changes the URL and omits the key', async () => {const principalId = nextPrincipalId();const before = await storeSearxng(principalId);@@ -1213,15 +1225,35 @@ describe('config secret registry — real handlers against a real Config collect};}+ /**+ * The write lost the compare-and-swap, re-read the document and re-ran the check, which+ * now sees the other admin's key beside the URL this write changes.+ */const VICTIM_KEPT = {+ statusCode: 400,+ body: expect.objectContaining({ code: 'CONFIG_SECRET_REENTRY_REQUIRED' }),+ url: VICTIM_URL,+ key: VICTIM_KEY,+ };++ /** A write pinned to the revision it read answers 409 instead of re-checking. */+ const VICTIM_KEPT_PINNED = {statusCode: 409,- body: { error: expect.any(String), code: 'CONFIG_VERSION_CONFLICT' },+ body: expect.objectContaining({ code: 'CONFIG_VERSION_CONFLICT' }),url: VICTIM_URL,key: VICTIM_KEY,};const params = (principalId: string) => ({ principalType: 'role', principalId });+ /** The revision the next write is pinned to: the document as stored now. */+ async function currentRevision(principalId: string): Promise<string> {+ const stored = await configMethods.findConfigByPrincipal(PrincipalType.ROLE, principalId, {+ includeInactive: true,+ });+ return stored ? `${stored._id}:${stored.configVersion}` : 'absent';+ }+it.each([{ name: 'on an existing document', existing: true },{ name: 'on a document created meanwhile', existing: false },@@ -1276,6 +1308,56 @@ describe('config secret registry — real handlers against a real Config collectexpect(await outcome(principalId, res)).toEqual(VICTIM_KEPT);});+ it.each([+ { name: 'on an existing document', existing: true },+ { name: 'on a document created meanwhile', existing: false },+ ])(+ 'answers 409 to a URL-only patch pinned to the revision it read $name',+ async ({ existing }) => {+ const principalId = nextPrincipalId();+ if (existing) {+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);+ }+ const expectedRevision = await currentRevision(principalId);+ const res = mockRes();++ await racedHandlers(principalId).patchConfigField(+ mockReq({+ params: params(principalId),+ body: {+ entries: [{ fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL }],+ expectedRevision,+ },+ }),+ res,+ );++ expect(await outcome(principalId, res)).toEqual(VICTIM_KEPT_PINNED);+ },+ );++ it.each([+ { name: 'deleting', handler: 'deleteConfigField' as const },+ { name: 'tombstoning', handler: 'tombstoneConfigField' as const },+ ])('answers 409 to $name the URL pinned to the revision it read', async ({ handler }) => {+ const principalId = nextPrincipalId();+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);+ const expectedRevision = await currentRevision(principalId);+ const res = mockRes();+ const fieldPath = 'webSearch.searxngInstanceUrl';++ await racedHandlers(principalId)[handler](+ mockReq({+ params: params(principalId),+ query: { fieldPath, expectedRevision },+ body: { fieldPath, expectedRevision },+ }),+ res,+ );++ expect(await outcome(principalId, res)).toEqual(VICTIM_KEPT_PINNED);+ });+it('lets a write to another section proceed', async () => {const principalId = nextPrincipalId();await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);@@ -1315,9 +1397,12 @@ describe('config secret registry — real handlers against a real Config collectconst baseHandlers = createAdminConfigHandlers({listAllConfigs: async () => [],findConfigByPrincipal: async () => null,- upsertConfig: async () => null,- patchConfigFields: async () => null,- tombstoneConfigField: async () => null,+ writeConfigDocument: async () => {+ throw new Error('not written in this test');+ },+ tombstoneConfigField: async () => {+ throw new Error('not written in this test');+ },unsetConfigField: async () => null,deleteConfig: async () => null,toggleConfigActiveTracked: async () => null,diff --git a/packages/api/src/admin/secrets.spec.ts b/packages/api/src/admin/secrets.spec.tsindex a81ec79db1..c0468c8a35 100644--- a/packages/api/src/admin/secrets.spec.ts+++ b/packages/api/src/admin/secrets.spec.ts@@ -11,6 +11,9 @@ let getConfigSecretInputError: typeof import('./secrets').getConfigSecretInputErlet getConfigSecretMutationPaths: typeof import('./secrets').getConfigSecretMutationPaths;let getConfigSecretSections: typeof import('./secrets').getConfigSecretSections;let isConfigSecretAncestorPath: typeof import('./secrets').isConfigSecretAncestorPath;+let getSecretAncestorPatterns: typeof import('./secrets').getSecretAncestorPatterns;+let matchesSecretPattern: typeof import('./secrets').matchesSecretPattern;+let isConfigSecretRelatedSegments: typeof import('./secrets').isConfigSecretRelatedSegments;let isConfigSecretDescendantPath: typeof import('./secrets').isConfigSecretDescendantPath;let preserveConfigSecrets: typeof import('./secrets').preserveConfigSecrets;let redactConfigSecrets: typeof import('./secrets').redactConfigSecrets;@@ -30,6 +33,9 @@ beforeAll(async () => {getConfigSecretMutationPaths,getConfigSecretSections,isConfigSecretAncestorPath,+ getSecretAncestorPatterns,+ matchesSecretPattern,+ isConfigSecretRelatedSegments,isConfigSecretDescendantPath,preserveConfigSecrets,redactConfigSecrets,@@ -686,6 +692,50 @@ describe('Config secret registry fields', () => {expect(isConfigSecretDescendantPath('speech.tts.openai.model')).toBe(false);});+ it('derives ancestors from array secret containers as well as scalar secrets', () => {+ expect(isConfigSecretAncestorPath('endpoints')).toBe(true);+ expect(isConfigSecretAncestorPath('endpoints.custom')).toBe(false);+ expect(isConfigSecretAncestorPath('endpoints.assistants')).toBe(true);+ expect(isConfigSecretAncestorPath('endpoints.azureOpenAI')).toBe(false);++ expect(+ getSecretAncestorPatterns(['speech.tts.openai.apiKey', 'endpoints.custom']).sort(),+ ).toEqual(['endpoints', 'speech', 'speech.tts', 'speech.tts.openai']);+ });++ it('keeps dynamic segments in derived ancestors and matches them segment by segment', () => {+ expect(+ getSecretAncestorPatterns(['mcpServers.*.oauth.client_secret', 'mcpServers.*.apiKey.key']),+ ).toEqual(['mcpServers', 'mcpServers.*', 'mcpServers.*.oauth', 'mcpServers.*.apiKey']);++ expect(matchesSecretPattern('mcpServers.github.oauth', 'mcpServers.*.oauth')).toBe(true);+ expect(matchesSecretPattern('mcpServers.github', 'mcpServers.*')).toBe(true);+ expect(matchesSecretPattern('mcpServers.github.oauth.x', 'mcpServers.*.oauth')).toBe(false);+ expect(matchesSecretPattern('mcpServers', 'mcpServers.*')).toBe(false);+ expect(matchesSecretPattern('mcpSettings.github.oauth', 'mcpServers.*.oauth')).toBe(false);+ });++ it('relates a segment path to a secret it is, holds, or lies inside, comparing whole keys', () => {+ expect(isConfigSecretRelatedSegments(['webSearch'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['webSearch', 'serperApiKey'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['webSearch', 'serperApiKeyPreview'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['webSearch', 'serperApiKey', 'x'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['langfuse', 'displaySecretKey'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['endpoints', 'custom'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['endpoints', 'custom', 'my.endpoint'])).toBe(true);+ expect(isConfigSecretRelatedSegments(['endpoints', 'custom', '0', 'apiKey'])).toBe(true);++ expect(isConfigSecretRelatedSegments(['webSearch', 'searchProvider'])).toBe(false);+ expect(isConfigSecretRelatedSegments(['webSearch', 'serperApiKey.x'])).toBe(false);+ expect(isConfigSecretRelatedSegments(['speech', 'tts.openai'])).toBe(false);+ expect(isConfigSecretRelatedSegments(['endpoints', 'custom', '0', 'headers', 'X.Id'])).toBe(+ false,+ );+ expect(+ isConfigSecretRelatedSegments(['endpoints', 'bedrock', 'inferenceProfiles', 'us.a.b']),+ ).toBe(false);+ });+it('rejects encrypted submissions at registry paths and inside ancestor objects', () => {expect(getConfigSecretInputError('webSearch.serperApiKey', 'v3:attacker')).toContain('Encrypted config secret values',diff --git a/packages/api/src/admin/secrets.ts b/packages/api/src/admin/secrets.tsindex f284e9924c..9e7404e7a8 100644--- a/packages/api/src/admin/secrets.ts+++ b/packages/api/src/admin/secrets.ts@@ -98,13 +98,53 @@ const PREVIEW_PATHS = new Set<string>([...LEGACY_PREVIEW_PATHS.values(),]);+/** One dynamic key in a secret location pattern, such as a record entry name. */+const ANY_SEGMENT = '*';++/**+ * Every proper ancestor of the given secret locations. A write of an object at one of them can+ * carry a secret, so the write path walks it for encryption, preservation and redaction. A+ * location may use `*` for a dynamic key (a record entry such as an MCP server name); its+ * ancestors keep the wildcard.+ */+export function getSecretAncestorPatterns(locations: readonly string[]): string[] {+ const ancestors = new Set<string>();+ for (const location of locations) {+ const segments = location.split('.');+ for (let length = 1; length < segments.length; length++) {+ ancestors.add(segments.slice(0, length).join('.'));+ }+ }+ return [...ancestors];+}++/**+ * Ancestors of every registered location: scalar secrets and the containers of array secrets+ * (an array container itself is matched by `ARRAY_SECRET_FIELDS`, since it must stay an array).+ */+const ANCESTOR_PATTERNS = getSecretAncestorPatterns([+ ...CONFIG_SECRET_FIELDS.map((field) => field.path),+ ...ARRAY_SECRET_FIELDS.map((field) => field.arrayPath),+]);++const isWildcardPattern = (pattern: string): boolean => pattern.split('.').includes(ANY_SEGMENT);+const ANCESTOR_PATHS = new Set<string>(- CONFIG_SECRET_FIELDS.flatMap((field) => {- const segments = field.path.split('.');- return segments.slice(0, -1).map((_, index) => segments.slice(0, index + 1).join('.'));- }),+ ANCESTOR_PATTERNS.filter((pattern) => !isWildcardPattern(pattern)),);+const ANCESTOR_WILDCARDS: readonly string[] = ANCESTOR_PATTERNS.filter(isWildcardPattern);++/** Whether a dotted path matches a location pattern segment for segment. */+export function matchesSecretPattern(fieldPath: string, pattern: string): boolean {+ const segments = fieldPath.split('.');+ const expected = pattern.split('.');+ return (+ segments.length === expected.length &&+ expected.every((segment, index) => segment === ANY_SEGMENT || segment === segments[index])+ );+}+const SECRET_SECTIONS: readonly string[] = [...new Set([...CONFIG_SECRET_FIELDS.map((field) => field.path.split('.')[0]),@@ -252,7 +292,7 @@ function isConfigSecretRelatedPath(fieldPath: string): boolean {) {return true;}- return ANCESTOR_PATHS.has(fieldPath) || isConfigSecretDescendantPath(fieldPath);+ return isConfigSecretAncestorPath(fieldPath) || isConfigSecretDescendantPath(fieldPath);}export function decryptConfigSecret(value: unknown): string | undefined {@@ -327,7 +367,46 @@ export function isConfigSecretDescendantPath(fieldPath: string): boolean {}export function isConfigSecretAncestorPath(fieldPath: string): boolean {- return ANCESTOR_PATHS.has(fieldPath);+ if (ANCESTOR_PATHS.has(fieldPath)) {+ return true;+ }+ return ANCESTOR_WILDCARDS.some((pattern) => matchesSecretPattern(fieldPath, pattern));+}++/**+ * Every registered secret location as segments: scalar secrets with their previews (legacy+ * spellings included), and the secret and preview keys of any item of an array secret+ * container, where `*` stands for the item index.+ */+const SECRET_LOCATIONS: ReadonlyArray<readonly string[]> = [+ ...[+ ...CONFIG_SECRET_FIELDS.flatMap((field) => [field.path, field.previewPath]),+ ...LEGACY_PREVIEW_PATHS.values(),+ ].map((path) => path.split('.')),+ ...ARRAY_SECRET_FIELDS.flatMap((field) => {+ const container = field.arrayPath.split('.');+ return [+ [...container, ANY_SEGMENT, field.secretKey],+ [...container, ANY_SEGMENT, field.previewKey],+ ];+ }),+];++/**+ * Whether a write at `segments` touches a registered secret: the secret's own location or its+ * preview's, an ancestor that can carry it, or a path inside it. Segments are compared one by+ * one, so a key that contains a dot is never mistaken for the path its dots would spell.+ */+export function isConfigSecretRelatedSegments(segments: readonly string[]): boolean {+ return SECRET_LOCATIONS.some((location) => {+ const shared = Math.min(location.length, segments.length);+ for (let index = 0; index < shared; index++) {+ if (location[index] !== ANY_SEGMENT && location[index] !== segments[index]) {+ return false;+ }+ }+ return true;+ });}export function getConfigSecretInputError(fieldPath: string, value: unknown): string | null {diff --git a/packages/api/src/admin/users.ts b/packages/api/src/admin/users.tsindex d28569e50a..20fbd519c4 100644--- a/packages/api/src/admin/users.ts+++ b/packages/api/src/admin/users.ts@@ -4,7 +4,7 @@ import { PrincipalType, SystemRoles } from 'librechat-data-provider';import { logger, isValidObjectIdString, buildUserSearchFilter } from '@librechat/data-schemas';import type {IUser,- IConfig,+ ConfigRecord,AdminUserListItem,AdminUserSearchResult,UserDeleteResult,@@ -107,7 +107,7 @@ export interface AdminUsersDeps {deleteConfig: (principalType: PrincipalType,principalId: string | Types.ObjectId,- ) => Promise<IConfig | null>;+ ) => Promise<ConfigRecord | null>;deleteAclEntries: (filter: {principalType: PrincipalType;principalId: string | Types.ObjectId;diff --git a/packages/api/src/app/index.ts b/packages/api/src/app/index.tsindex 03b9edb3de..9198f02baa 100644--- a/packages/api/src/app/index.ts+++ b/packages/api/src/app/index.ts@@ -1,4 +1,5 @@export * from './service';+export * from './invalidation';export * from './loader';export * from './config';export * from './metrics';diff --git a/packages/api/src/app/invalidation.redis.spec.ts b/packages/api/src/app/invalidation.redis.spec.tsnew file mode 100644index 0000000000..b05f739bee--- /dev/null+++ b/packages/api/src/app/invalidation.redis.spec.ts@@ -0,0 +1,210 @@+import Redis from 'ioredis';+import { Keyv } from 'keyv';+import { logger } from '@librechat/data-schemas';+import type { AppConfig } from '@librechat/data-schemas';+import type { ConfigCacheInvalidation, ConfigInvalidationPubSub } from './invalidation';+import type { RespServer } from '~/cache/__tests__/resp.helper';+import { createConfigCacheInvalidation, createRedisConfigInvalidationPubSub } from './invalidation';+import { startRespServer, waitFor } from '~/cache/__tests__/resp.helper';+import { createAppConfigService } from './service';++/**+ * Cross-instance invalidation over real ioredis connections: each instance owns the publisher+ * and subscriber `createRedisConfigInvalidationPubSub` duplicates from its shared client, the+ * way two LibreChat processes would, against a RESP server that fans PUBLISH out.+ */+describe('createRedisConfigInvalidationPubSub', () => {+ let server: RespServer;+ let clients: Redis[];+ let opened: Array<{ invalidation: ConfigCacheInvalidation; pubsub: ConfigInvalidationPubSub }>;++ beforeEach(async () => {+ server = await startRespServer();+ clients = [];+ opened = [];+ });++ afterEach(async () => {+ for (const { invalidation, pubsub } of opened) {+ await invalidation.close().catch(() => undefined);+ (pubsub.publisher as Redis).disconnect();+ (pubsub.subscriber as Redis).disconnect();+ }+ for (const client of clients) {+ client.disconnect();+ }+ await server.close();+ });++ /** Connects eagerly like the production client, so its duplicates connect on creation too. */+ async function connect(): Promise<Redis> {+ const client = new Redis(server.url, { maxRetriesPerRequest: 1 });+ client.on('error', () => undefined);+ clients.push(client);+ await waitFor(() => client.status === 'ready');+ return client;+ }++ async function startInstance(namespace?: string) {+ return startInstanceOn(await connect(), namespace);+ }++ async function startInstanceOn(client: Redis, namespace?: string) {+ const clearOverrides = jest.fn(async (_tenantId?: string) => undefined);+ const pubsub = createRedisConfigInvalidationPubSub({+ useRedis: true,+ client,+ namespace,+ });+ if (!pubsub) {+ throw new Error('expected a Redis pub/sub pair');+ }+ const invalidation = createConfigCacheInvalidation({+ clears: [{ label: 'clearOverrideCache', clear: clearOverrides }],+ pubsub,+ });+ opened.push({ invalidation, pubsub });+ return { invalidation, clearOverrides, pubsub };+ }++ const subscribed = (channel: string, count: number) => () =>+ server.commands.filter(+ (frame) => frame[0]?.toUpperCase() === 'SUBSCRIBE' && frame[1] === channel,+ ).length >= count;++ it('clears the other instances of a deployment, scoped to the tenant, and not other deployments', async () => {+ const first = await startInstance('deploy-a');+ const second = await startInstance('deploy-a');+ const other = await startInstance('deploy-b');+ expect(first.pubsub.channel).toBe('librechat:config:invalidate:deploy-a');+ await waitFor(subscribed('librechat:config:invalidate:deploy-a', 2));+ await waitFor(subscribed('librechat:config:invalidate:deploy-b', 1));++ await first.invalidation.invalidate('tenant-a');++ expect(first.clearOverrides).toHaveBeenCalledTimes(1);+ await waitFor(() => second.clearOverrides.mock.calls.length === 1);+ expect(second.clearOverrides).toHaveBeenCalledWith('tenant-a');+ expect(first.clearOverrides).toHaveBeenCalledTimes(1);+ expect(other.clearOverrides).not.toHaveBeenCalled();+ });++ /**+ * Composed like `api/server/services/Config/app.js`: the base clear rides the broadcast, so a+ * write taken by one instance makes every instance reload librechat.yaml.+ */+ it('reloads librechat.yaml on the other instances of the deployment', async () => {+ let yamlVersion = 'v1';+ const startServiceInstance = async () => {+ const store = new Map<string, unknown>();+ const keyv = new Keyv({ store, namespace: 'APP_CONFIG' });+ const cache = {+ get: (key: string) => keyv.get(key),+ set: (key: string, value: unknown, ttl?: number) => keyv.set(key, value, ttl),+ delete: (key: string) => keyv.delete(key),+ opts: { store: { keys: () => store.keys() } },+ };+ const service = createAppConfigService({+ loadBaseConfig: async () => ({ config: { version: yamlVersion } }) as AppConfig,+ setCachedTools: async () => undefined,+ getCache: () => cache,+ cacheKeys: { APP_CONFIG: 'APP_CONFIG' },+ getApplicableConfigs: async () => [],+ getUserPrincipals: async () => [],+ });+ const clearBase = jest.fn(service.clearAppConfigCache);+ const pubsub = createRedisConfigInvalidationPubSub({+ useRedis: true,+ client: await connect(),+ namespace: 'deploy-a',+ });+ if (!pubsub) {+ throw new Error('expected a Redis pub/sub pair');+ }+ const invalidation = createConfigCacheInvalidation({+ clears: [+ { label: 'clearAppConfigCache', clear: () => clearBase() },+ { label: 'clearOverrideCache', clear: service.clearOverrideCache },+ ],+ pubsub,+ });+ opened.push({ invalidation, pubsub });+ const readVersion = async () =>+ (await service.getAppConfig({ baseOnly: true })).config?.version;+ return { invalidation, clearBase, readVersion };+ };+ const writer = await startServiceInstance();+ const reader = await startServiceInstance();+ await waitFor(subscribed('librechat:config:invalidate:deploy-a', 2));+ expect(await writer.readVersion()).toBe('v1');+ expect(await reader.readVersion()).toBe('v1');++ yamlVersion = 'v2';+ expect(await reader.readVersion()).toBe('v1');+ await writer.invalidation.invalidate();++ expect(await writer.readVersion()).toBe('v2');+ await waitFor(() => reader.clearBase.mock.calls.length === 1);+ expect(await reader.readVersion()).toBe('v2');+ });++ it('uses the default channel when the deployment has no key prefix', async () => {+ const instance = await startInstance(' ');++ expect(instance.pubsub.channel).toBe('librechat:config:invalidate:default');+ });++ it('fails the broadcast fast while Redis is unreachable instead of holding the write', async () => {+ const error = jest.spyOn(logger, 'error').mockReturnValue(logger);+ const instance = await startInstance('deploy-a');+ await waitFor(() => (instance.pubsub.publisher as Redis).status === 'ready');+ await server.close();+ await waitFor(() => (instance.pubsub.publisher as Redis).status !== 'ready');++ const started = Date.now();+ await expect(instance.invalidation.invalidate()).resolves.toBeUndefined();++ expect(Date.now() - started).toBeLessThan(1000);+ expect(instance.clearOverrides).toHaveBeenCalledTimes(1);+ expect(error).toHaveBeenCalledWith(+ expect.stringContaining('Publishing to other instances failed'),+ expect.anything(),+ );+ server = await startRespServer();+ });++ it('subscribes once Redis comes back when the first SUBSCRIBE failed during an outage', async () => {+ const error = jest.spyOn(logger, 'error').mockReturnValue(logger);+ const channel = 'librechat:config:invalidate:deploy-a';+ const client = await connect();+ const { port } = server;+ await server.close();+ await waitFor(() => client.status !== 'ready');++ const late = await startInstanceOn(client, 'deploy-a');+ await waitFor(+ () =>+ error.mock.calls.some(([message]) =>+ String(message).includes('Subscribing to cross-instance invalidations failed'),+ ),+ 5000,+ );++ server = await startRespServer(port);+ await waitFor(subscribed(channel, 1), 5000);+ const writer = await startInstance('deploy-a');+ await waitFor(subscribed(channel, 2));++ await writer.invalidation.invalidate('tenant-a');++ await waitFor(() => late.clearOverrides.mock.calls.length === 1);+ expect(late.clearOverrides).toHaveBeenCalledWith('tenant-a');+ });++ it('returns no pub/sub without Redis', async () => {+ const client = await connect();++ expect(createRedisConfigInvalidationPubSub({ useRedis: false, client })).toBeUndefined();+ expect(createRedisConfigInvalidationPubSub({ useRedis: true, client: null })).toBeUndefined();+ });+});diff --git a/packages/api/src/app/invalidation.spec.ts b/packages/api/src/app/invalidation.spec.tsnew file mode 100644index 0000000000..f50d631814--- /dev/null+++ b/packages/api/src/app/invalidation.spec.ts@@ -0,0 +1,245 @@+import { EventEmitter } from 'events';+import { logger } from '@librechat/data-schemas';+import type { ConfigInvalidationPublisher, ConfigInvalidationSubscriber } from './invalidation';+import { CONFIG_INVALIDATION_CHANNEL, createConfigCacheInvalidation } from './invalidation';++/**+ * An in-process stand-in for Redis pub/sub: every subscribed connection receives every message+ * published on a channel it subscribed to, including the publisher's own instance.+ */+function createBroker() {+ const subscribers = new Set<{ channels: Set<string>; events: EventEmitter }>();+ return {+ publisher(): ConfigInvalidationPublisher & { publish: jest.Mock } {+ return {+ publish: jest.fn(async (channel: string, message: string) => {+ let delivered = 0;+ for (const subscriber of subscribers) {+ if (subscriber.channels.has(channel)) {+ delivered += 1;+ subscriber.events.emit('message', channel, message);+ }+ }+ return delivered;+ }),+ };+ },+ /** `failSubscribes` rejects that many SUBSCRIBE calls first, as Redis being down would. */+ subscriber(+ failSubscribes = 0,+ ): ConfigInvalidationSubscriber & { events: EventEmitter; subscribe: jest.Mock } {+ const state = { channels: new Set<string>(), events: new EventEmitter() };+ subscribers.add(state);+ let failures = failSubscribes;+ return {+ events: state.events,+ subscribe: jest.fn(async (channel: string) => {+ if (failures > 0) {+ failures -= 1;+ throw new Error('Reached the max retries per request limit');+ }+ return state.channels.add(channel);+ }),+ unsubscribe: async (channel: string) => state.channels.delete(channel),+ on: (event: string, listener: (...args: string[]) => void) =>+ state.events.on(event, listener),+ off: (event: string, listener: (...args: string[]) => void) =>+ state.events.off(event, listener),+ };+ },+ };+}++const flush = () => new Promise((resolve) => setImmediate(resolve));++function createInstance(+ broker: ReturnType<typeof createBroker>,+ instanceId: string,+ failSubscribes = 0,+) {+ const clearOverrides = jest.fn(async (_tenantId?: string) => undefined);+ const clearMcp = jest.fn(async () => undefined);+ const publisher = broker.publisher();+ const subscriber = broker.subscriber(failSubscribes);+ const invalidation = createConfigCacheInvalidation({+ clears: [+ { label: 'clearOverrideCache', clear: clearOverrides },+ { label: 'clearMcpConfigCache', clear: clearMcp },+ ],+ pubsub: { publisher, subscriber },+ instanceId,+ });+ return { invalidation, clearOverrides, clearMcp, publisher, subscriber };+}++describe('createConfigCacheInvalidation', () => {+ it('runs every clear concurrently and passes the tenant through', async () => {+ const events: string[] = [];+ const tracked = (label: string) =>+ jest.fn(async () => {+ events.push(`start:${label}`);+ await flush();+ events.push(`end:${label}`);+ });+ const overrides = tracked('override');+ const mcp = tracked('mcp');+ const invalidation = createConfigCacheInvalidation({+ clears: [+ { label: 'override', clear: overrides },+ { label: 'mcp', clear: mcp },+ ],+ });++ await invalidation.invalidate('tenant-a');++ expect(events.slice(0, 2).sort()).toEqual(['start:mcp', 'start:override']);+ expect(events).toHaveLength(4);+ expect(overrides).toHaveBeenCalledWith('tenant-a');+ });++ it('resolves when a clear fails, logging which one without its message', async () => {+ const error = jest.spyOn(logger, 'error').mockReturnValue(logger);+ const other = jest.fn().mockResolvedValue(undefined);+ const invalidation = createConfigCacheInvalidation({+ clears: [+ {+ label: 'clearOverrideCache',+ clear: jest.fn().mockRejectedValue(new Error('secret-ish')),+ },+ { label: 'clearMcpConfigCache', clear: other },+ ],+ });++ await expect(invalidation.invalidate()).resolves.toBeUndefined();++ expect(other).toHaveBeenCalledTimes(1);+ expect(error).toHaveBeenCalledWith(+ '[invalidateConfigCaches] clearOverrideCache failed:',+ expect.not.objectContaining({ message: 'secret-ish' }),+ );+ });++ it('clears another instance when one invalidates, scoped to the same tenant', async () => {+ const broker = createBroker();+ const first = createInstance(broker, 'first');+ const second = createInstance(broker, 'second');+ await flush();++ await first.invalidation.invalidate('tenant-a');+ await flush();++ expect(first.clearOverrides).toHaveBeenCalledTimes(1);+ expect(second.clearOverrides).toHaveBeenCalledWith('tenant-a');+ expect(second.clearMcp).toHaveBeenCalledTimes(1);+ expect(first.publisher.publish).toHaveBeenCalledWith(+ CONFIG_INVALIDATION_CHANNEL,+ JSON.stringify({ origin: 'first', tenantId: 'tenant-a' }),+ );+ });++ it('broadcasts a clear of every tenant without a tenant id', async () => {+ const broker = createBroker();+ const first = createInstance(broker, 'first');+ const second = createInstance(broker, 'second');+ await flush();++ await first.invalidation.invalidate();+ await flush();++ expect(second.clearOverrides).toHaveBeenCalledWith(undefined);+ });++ it('ignores its own broadcast, malformed messages and other channels', async () => {+ const broker = createBroker();+ const only = createInstance(broker, 'only');+ const listener = broker.subscriber();+ await flush();+ const publisher = broker.publisher();++ await only.invalidation.invalidate();+ await publisher.publish(CONFIG_INVALIDATION_CHANNEL, 'not json');+ await publisher.publish(CONFIG_INVALIDATION_CHANNEL, JSON.stringify({ origin: 1 }));+ await publisher.publish(+ CONFIG_INVALIDATION_CHANNEL,+ JSON.stringify({ origin: 'x', tenantId: { $ne: '' } }),+ );+ await listener.subscribe('another-channel');+ await publisher.publish('another-channel', JSON.stringify({ origin: 'x' }));+ await flush();++ expect(only.clearOverrides).toHaveBeenCalledTimes(1);+ });++ it('stops listening once closed', async () => {+ const broker = createBroker();+ const first = createInstance(broker, 'first');+ const second = createInstance(broker, 'second');+ await flush();++ await second.invalidation.close();+ await first.invalidation.invalidate();+ await flush();++ expect(second.clearOverrides).not.toHaveBeenCalled();+ });++ it('subscribes again when the subscriber becomes ready after a failed SUBSCRIBE', async () => {+ const error = jest.spyOn(logger, 'error').mockReturnValue(logger);+ const broker = createBroker();+ const first = createInstance(broker, 'first');+ const second = createInstance(broker, 'second', 1);+ await flush();++ expect(error).toHaveBeenCalledWith(+ expect.stringContaining('Subscribing to cross-instance invalidations failed'),+ expect.anything(),+ );+ await first.invalidation.invalidate('tenant-a');+ await flush();+ expect(second.clearOverrides).not.toHaveBeenCalled();++ second.subscriber.events.emit('ready');+ await flush();+ await first.invalidation.invalidate('tenant-a');+ await flush();++ expect(second.subscriber.subscribe).toHaveBeenCalledTimes(2);+ expect(second.clearOverrides).toHaveBeenCalledWith('tenant-a');+ });++ it('leaves resubscribing to the client once subscribed, and stops retrying once closed', async () => {+ const broker = createBroker();+ const subscribed = createInstance(broker, 'subscribed');+ const closed = createInstance(broker, 'closed', 1);+ await flush();++ subscribed.subscriber.events.emit('ready');+ await closed.invalidation.close();+ closed.subscriber.events.emit('ready');+ await flush();++ expect(subscribed.subscriber.subscribe).toHaveBeenCalledTimes(1);+ expect(closed.subscriber.subscribe).toHaveBeenCalledTimes(1);+ });++ it('keeps the local clear when publishing fails', async () => {+ const error = jest.spyOn(logger, 'error').mockReturnValue(logger);+ const clear = jest.fn().mockResolvedValue(undefined);+ const broker = createBroker();+ const invalidation = createConfigCacheInvalidation({+ clears: [{ label: 'clearOverrideCache', clear }],+ pubsub: {+ publisher: { publish: jest.fn().mockRejectedValue(new Error('redis down')) },+ subscriber: broker.subscriber(),+ },+ });++ await expect(invalidation.invalidate()).resolves.toBeUndefined();++ expect(clear).toHaveBeenCalledTimes(1);+ expect(error).toHaveBeenCalledWith(+ expect.stringContaining('Publishing to other instances failed'),+ expect.anything(),+ );+ });+});diff --git a/packages/api/src/app/invalidation.ts b/packages/api/src/app/invalidation.tsnew file mode 100644index 0000000000..f6804a6eee--- /dev/null+++ b/packages/api/src/app/invalidation.ts@@ -0,0 +1,204 @@+import { randomUUID } from 'crypto';+import { logger } from '@librechat/data-schemas';+import type { Cluster, Redis } from 'ioredis';+import { createIoRedisSubscriber, duplicateIoRedisClient } from '~/cache/redisUtils';+import { getSafeErrorMetadata } from '~/utils/errors';++/** Pub/sub channel every instance listens on for admin config cache invalidations. */+export const CONFIG_INVALIDATION_CHANNEL = 'librechat:config:invalidate';++/** The publishing half of a pub/sub client (an ioredis client in production). */+export interface ConfigInvalidationPublisher {+ publish(channel: string, message: string): Promise<number>;+}++/**+ * A dedicated subscriber connection (a client in subscribe mode cannot publish). It emits+ * `ready` each time its connection is established, as an ioredis client does.+ */+export interface ConfigInvalidationSubscriber {+ subscribe(channel: string): Promise<unknown>;+ unsubscribe(channel: string): Promise<unknown>;+ on(event: 'message', listener: (channel: string, message: string) => void): unknown;+ on(event: 'ready', listener: () => void): unknown;+ off(event: 'message', listener: (channel: string, message: string) => void): unknown;+ off(event: 'ready', listener: () => void): unknown;+}++/** The connections and channel cross-instance invalidation runs on. */+export interface ConfigInvalidationPubSub {+ publisher: ConfigInvalidationPublisher;+ subscriber: ConfigInvalidationSubscriber;+ channel?: string;+}++/** One cache a config write invalidates; `tenantId` scopes it when the cache supports that. */+export interface ConfigCacheClear {+ label: string;+ clear: (tenantId?: string) => Promise<void>;+}++export interface ConfigCacheInvalidation {+ /**+ * Clears this instance's config caches and tells every other instance to do the same.+ * Resolves once the local clears settle; failures are logged, never thrown, because the+ * write that triggered them has already committed.+ */+ invalidate(tenantId?: string): Promise<void>;+ /** Stops listening for other instances' invalidations. */+ close(): Promise<void>;+}++interface InvalidationMessage {+ origin: string;+ tenantId?: string;+}++function parseMessage(message: string): InvalidationMessage | null {+ try {+ const parsed: unknown = JSON.parse(message);+ if (parsed == null || typeof parsed !== 'object') {+ return null;+ }+ const { origin, tenantId } = parsed as Record<string, unknown>;+ if (typeof origin !== 'string' || (tenantId !== undefined && typeof tenantId !== 'string')) {+ return null;+ }+ return tenantId === undefined ? { origin } : { origin, tenantId };+ } catch {+ return null;+ }+}++/**+ * Admin config cache invalidation for one instance, and across instances when a pub/sub pair+ * is supplied. The merged-config cache is per process, so without the pub/sub another instance+ * keeps serving a pre-write merge until its TTL expires.+ */+export function createConfigCacheInvalidation(params: {+ clears: readonly ConfigCacheClear[];+ pubsub?: ConfigInvalidationPubSub;+ /** Identifies this instance, so it ignores its own broadcasts. */+ instanceId?: string;+}): ConfigCacheInvalidation {+ const { clears, pubsub } = params;+ const instanceId = params.instanceId ?? randomUUID();+ const channel = pubsub?.channel ?? CONFIG_INVALIDATION_CHANNEL;++ async function clearLocal(tenantId?: string): Promise<void> {+ const results = await Promise.allSettled(clears.map(({ clear }) => clear(tenantId)));+ results.forEach((result, index) => {+ if (result.status === 'rejected') {+ logger.error(+ `[invalidateConfigCaches] ${clears[index].label} failed:`,+ getSafeErrorMetadata(result.reason),+ );+ }+ });+ }++ const onMessage = (received: string, message: string): void => {+ if (received !== channel) {+ return;+ }+ const parsed = parseMessage(message);+ if (!parsed || parsed.origin === instanceId) {+ return;+ }+ void clearLocal(parsed.tenantId);+ };++ let subscribed = false;+ let subscribing = false;+ let closed = false;++ /**+ * Subscribes until one SUBSCRIBE succeeds; from then on the client resubscribes by itself+ * after a reconnect. A SUBSCRIBE that fails (Redis unreachable at startup, the client's+ * retries spent) is sent again the next time the subscriber becomes ready, so a transient+ * outage does not leave this instance deaf to other instances' writes until it restarts.+ */+ const subscribe = (): void => {+ if (!pubsub || subscribed || subscribing || closed) {+ return;+ }+ subscribing = true;+ pubsub.subscriber.subscribe(channel).then(+ () => {+ subscribing = false;+ subscribed = true;+ },+ (error: unknown) => {+ subscribing = false;+ logger.error(+ '[invalidateConfigCaches] Subscribing to cross-instance invalidations failed; retrying when the subscriber reconnects. Until then this instance may serve cached config until it expires:',+ getSafeErrorMetadata(error),+ );+ },+ );+ };++ if (pubsub) {+ pubsub.subscriber.on('message', onMessage);+ pubsub.subscriber.on('ready', subscribe);+ subscribe();+ }++ async function invalidate(tenantId?: string): Promise<void> {+ await clearLocal(tenantId);+ if (!pubsub) {+ return;+ }+ const message: InvalidationMessage = tenantId+ ? { origin: instanceId, tenantId }+ : { origin: instanceId };+ try {+ await pubsub.publisher.publish(channel, JSON.stringify(message));+ } catch (error) {+ logger.error(+ '[invalidateConfigCaches] Publishing to other instances failed; they may serve cached config until it expires:',+ getSafeErrorMetadata(error),+ );+ }+ }++ async function close(): Promise<void> {+ if (!pubsub) {+ return;+ }+ closed = true;+ pubsub.subscriber.off('ready', subscribe);+ pubsub.subscriber.off('message', onMessage);+ await pubsub.subscriber.unsubscribe(channel);+ }++ return { invalidate, close };+}++/**+ * The Redis connections cross-instance invalidation needs, or `undefined` when Redis is off (each+ * instance then relies on its own clears and the override cache TTL). The subscriber is a+ * dedicated connection, as subscribe mode requires; the publisher is one without the offline+ * queue, so a write's awaited invalidation fails fast and is logged while Redis is unreachable+ * instead of holding the admin response until it reconnects. `namespace` (the deployment's+ * Redis key prefix) keeps deployments that share one Redis from clearing each other.+ */+export function createRedisConfigInvalidationPubSub(params: {+ useRedis: boolean;+ client: Redis | Cluster | null | undefined;+ namespace?: string;+}): ConfigInvalidationPubSub | undefined {+ const { useRedis, client, namespace } = params;+ if (!useRedis || client == null) {+ return undefined;+ }+ const publisher = duplicateIoRedisClient(client, { enableOfflineQueue: false });+ publisher.on('error', (error: Error) => {+ logger.error('[ConfigInvalidation] publisher error:', getSafeErrorMetadata(error));+ });+ return {+ publisher,+ subscriber: createIoRedisSubscriber(client, '[ConfigInvalidation] subscriber'),+ channel: `${CONFIG_INVALIDATION_CHANNEL}:${namespace?.trim() || 'default'}`,+ };+}diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.tsindex a27bcd3ba4..12d7cbba14 100644--- a/packages/api/src/app/service.spec.ts+++ b/packages/api/src/app/service.spec.ts@@ -1344,6 +1344,166 @@ describe('createAppConfigService', () => {await getAppConfig();expect(deps.loadBaseConfig).toHaveBeenCalledTimes(2);});++ /** A reload that read librechat.yaml before a clear must not be what the clear leaves cached. */+ describe('while a reload is in flight', () => {+ const tick = () => new Promise((resolve) => setImmediate(resolve));+ const stale = { x: 'stale', availableTools: { staleTool: {} } } as unknown as TestConfig;+ const fresh = { x: 'fresh', availableTools: { freshTool: {} } } as unknown as TestConfig;++ async function startStaleReload() {+ const deps = createDeps();+ const service = createAppConfigService(deps);+ await service.getAppConfig({ baseOnly: true });+ await service.clearAppConfigCache();+ let settleStale: (outcome: AppConfig | Error) => void = () => undefined;+ deps.loadBaseConfig+ .mockImplementationOnce(+ () =>+ new Promise<AppConfig>((resolve, reject) => {+ settleStale = (outcome) =>+ outcome instanceof Error ? reject(outcome) : resolve(outcome);+ }),+ )+ .mockResolvedValue(fresh);+ const staleRead = service.getAppConfig({ baseOnly: true });+ await tick();+ await service.clearAppConfigCache();+ return { deps, service, staleRead, settleStale };+ }++ it('starts a new reload once the stale one settles, and caches only the new one', async () => {+ const { deps, service, staleRead, settleStale } = await startStaleReload();++ const freshRead = service.getAppConfig({ baseOnly: true });+ await tick();+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(2);+ settleStale(stale);++ expect(((await staleRead) as TestConfig).x).toBe('stale');+ expect(((await freshRead) as TestConfig).x).toBe('fresh');+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(3);+ expect(((await service.getAppConfig({ baseOnly: true })) as TestConfig).x).toBe('fresh');+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(3);+ expect(deps.setCachedTools).not.toHaveBeenCalledWith(stale.availableTools);+ expect(deps.setCachedTools).toHaveBeenLastCalledWith(fresh.availableTools);+ });++ it('leaves the base uncached when the stale reload settles first', async () => {+ const { deps, service, staleRead, settleStale } = await startStaleReload();++ settleStale(stale);+ await staleRead;++ expect(deps._cache._store.has('app_config:_BASE_')).toBe(false);+ expect(((await service.getAppConfig({ baseOnly: true })) as TestConfig).x).toBe('fresh');+ });++ it('does not restore the last good config over the clear when the stale reload fails', async () => {+ const { deps, service, staleRead, settleStale } = await startStaleReload();++ settleStale(new Error('remote fetch failure'));++ expect(await staleRead).toEqual(deps._baseConfig);+ expect(deps._cache._store.has('app_config:_BASE_')).toBe(false);+ expect(((await service.getAppConfig({ baseOnly: true })) as TestConfig).x).toBe('fresh');+ });+ });++ /** An async store (Redis) can land a write after the delete of a clear that overtook it. */+ describe('when the cache write lands after the clear', () => {+ const tick = () => new Promise((resolve) => setImmediate(resolve));++ function holdNextSet(cache: ReturnType<typeof createMockCache>, prefix: string) {+ let release: (() => void) | undefined;+ cache.set.mockImplementationOnce((setKey, value) => {+ expect(setKey.startsWith(prefix)).toBe(true);+ return new Promise((resolve) => {+ release = () => {+ cache._store.set(`app_config:${setKey}`, value);+ resolve(undefined);+ };+ });+ });+ return async () => {+ while (!release) {+ await tick();+ }+ return release;+ };+ }++ it('removes the overtaken base so the next read reloads', async () => {+ const deps = createDeps({+ loadBaseConfig: jest+ .fn()+ .mockResolvedValueOnce({ x: 'first' })+ .mockResolvedValueOnce({ x: 'stale' })+ .mockResolvedValue({ x: 'fresh' }),+ });+ const service = createAppConfigService(deps);+ await service.getAppConfig({ baseOnly: true });+ await service.clearAppConfigCache();+ const held = holdNextSet(deps._cache, '_BASE_');++ const staleRead = service.getAppConfig({ baseOnly: true });+ const release = await held();+ await service.clearAppConfigCache();+ release();++ expect(((await staleRead) as TestConfig).x).toBe('stale');+ expect(deps._cache._store.has('app_config:_BASE_')).toBe(false);+ expect(((await service.getAppConfig({ baseOnly: true })) as TestConfig).x).toBe('fresh');+ });++ it('removes the overtaken merge so the next read merges again', async () => {+ const deps = createDeps({+ getApplicableConfigs: jest+ .fn()+ .mockResolvedValueOnce([{ priority: 10, overrides: { x: 'stale' }, isActive: true }])+ .mockResolvedValue([{ priority: 10, overrides: { x: 'fresh' }, isActive: true }]),+ });+ const service = createAppConfigService(deps);+ await service.getAppConfig({ baseOnly: true });+ const held = holdNextSet(deps._cache, '_OVERRIDE_:__default__:global:ADMIN:');++ const staleRead = service.getAppConfig({ role: 'ADMIN' });+ const release = await held();+ await service.clearOverrideCache();+ release();++ expect(((await staleRead) as TestConfig).x).toBe('stale');+ expect(((await service.getAppConfig({ role: 'ADMIN' })) as TestConfig).x).toBe('fresh');+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);+ });+ });++ it('does not cache a merge built on the base it read before the clear', async () => {+ let releasePrincipals: (principals: unknown[]) => void = () => undefined;+ const principals = [{ principalType: 'role', principalId: 'USER' }];+ const deps = createDeps({+ loadBaseConfig: jest+ .fn()+ .mockResolvedValueOnce({ x: 'before' })+ .mockResolvedValue({ x: 'after' }),+ getUserPrincipals: jest+ .fn()+ .mockImplementationOnce(() => new Promise((resolve) => (releasePrincipals = resolve)))+ .mockResolvedValue(principals),+ });+ const { getAppConfig, clearAppConfigCache } = createAppConfigService(deps);+ await getAppConfig({ baseOnly: true });++ const inFlight = getAppConfig({ role: 'USER', userId: 'uid1' });+ await new Promise((resolve) => setImmediate(resolve));+ await clearAppConfigCache();+ releasePrincipals(principals);+ expect(((await inFlight) as TestConfig).x).toBe('before');++ const next = (await getAppConfig({ role: 'USER', userId: 'uid1' })) as TestConfig;++ expect(next.x).toBe('after');+ });});describe('clearOverrideCache', () => {@@ -1410,6 +1570,112 @@ describe('createAppConfigService', () => {// Should not throw — logs warning and relies on TTL expiryawait expect(clearOverrideCache()).resolves.toBeUndefined();});++ /** A merge that read the database before a clear must not be cached after it. */+ it.each([+ ['every tenant', undefined, 'tenant-a'],+ ['the same tenant', 'tenant-a', 'tenant-a'],+ ])('drops a merge read before a clear of %s', async (_label, cleared, tenantId) => {+ let releaseRead: (configs: unknown[]) => void = () => undefined;+ const stale = [{ priority: 10, overrides: { x: 'stale' }, isActive: true }];+ const fresh = [{ priority: 10, overrides: { x: 'fresh' }, isActive: true }];+ const deps = createDeps({+ getApplicableConfigs: jest+ .fn()+ .mockImplementationOnce(() => new Promise((resolve) => (releaseRead = resolve)))+ .mockResolvedValue(fresh),+ });+ const { getAppConfig, clearOverrideCache } = createAppConfigService(deps);++ const inFlight = getAppConfig({ role: 'ADMIN', tenantId });+ await new Promise((resolve) => setImmediate(resolve));+ await clearOverrideCache(cleared);+ releaseRead(stale);+ expect(((await inFlight) as TestConfig).x).toBe('stale');++ const next = (await getAppConfig({ role: 'ADMIN', tenantId })) as TestConfig;++ expect(next.x).toBe('fresh');+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);+ });++ it('still caches a merge when only another tenant was cleared meanwhile', async () => {+ let releaseRead: (configs: unknown[]) => void = () => undefined;+ const deps = createDeps({+ getApplicableConfigs: jest+ .fn()+ .mockImplementationOnce(() => new Promise((resolve) => (releaseRead = resolve)))+ .mockResolvedValue([]),+ });+ const { getAppConfig, clearOverrideCache } = createAppConfigService(deps);++ const inFlight = getAppConfig({ role: 'ADMIN', tenantId: 'tenant-a' });+ await new Promise((resolve) => setImmediate(resolve));+ await clearOverrideCache('tenant-b');+ releaseRead([{ priority: 10, overrides: { x: 1 }, isActive: true }]);+ await inFlight;+ await getAppConfig({ role: 'ADMIN', tenantId: 'tenant-a' });++ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);+ });+ });++ describe('bypassOverrideCache', () => {+ it('merges the stored overrides now and neither reads nor fills the cache', async () => {+ const deps = createDeps({+ getApplicableConfigs: jest+ .fn()+ .mockResolvedValueOnce([{ priority: 10, overrides: { x: 'first' }, isActive: true }])+ .mockResolvedValueOnce([{ priority: 10, overrides: { x: 'second' }, isActive: true }])+ .mockResolvedValue([{ priority: 10, overrides: { x: 'third' }, isActive: true }]),+ });+ const { getAppConfig } = createAppConfigService(deps);++ const cached = (await getAppConfig({ role: 'ADMIN' })) as TestConfig;+ deps._cache.set.mockClear();+ const bypassed = (await getAppConfig({+ role: 'ADMIN',+ bypassOverrideCache: true,+ })) as TestConfig;+ const again = (await getAppConfig({ role: 'ADMIN' })) as TestConfig;++ expect(cached.x).toBe('first');+ expect(bypassed.x).toBe('second');+ expect(again.x).toBe('first');+ expect(deps._cache.set).not.toHaveBeenCalled();+ expect(deps.loadBaseConfig).toHaveBeenCalledTimes(1);+ });+ });++ describe('resolvedPrincipals without a user id', () => {+ it('is never served from or written to the role-keyed cache', async () => {+ const deps = createDeps({+ getApplicableConfigs: jest+ .fn()+ .mockResolvedValue([{ priority: 10, overrides: { x: 1 }, isActive: true }]),+ });+ const { getAppConfig } = createAppConfigService(deps);+ const resolvedPrincipals = [{ principalType: 'group', principalId: 'g1' }];++ await getAppConfig({ role: 'ADMIN' });+ deps._cache.set.mockClear();+ await getAppConfig({ role: 'ADMIN', resolvedPrincipals } as never);++ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);+ expect(deps.getApplicableConfigs).toHaveBeenLastCalledWith(resolvedPrincipals);+ expect(deps._cache.set).not.toHaveBeenCalled();+ });++ it('is cached under the key of the user it was resolved for', async () => {+ const deps = createDeps();+ const { getAppConfig } = createAppConfigService(deps);+ const resolvedPrincipals = [{ principalType: 'user', principalId: 'uid1' }];++ await getAppConfig({ role: 'USER', userId: 'uid1', resolvedPrincipals } as never);+ await getAppConfig({ role: 'USER', userId: 'uid1', resolvedPrincipals } as never);++ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);+ });});describe('overrideCacheTtl', () => {diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.tsindex cfb4cf85be..7503f989eb 100644--- a/packages/api/src/app/service.ts+++ b/packages/api/src/app/service.ts@@ -15,7 +15,7 @@ import {BASE_CONFIG_PRINCIPAL_ID,SYSTEM_TENANT_ID,} from '@librechat/data-schemas';-import type { AppConfig, IConfig } from '@librechat/data-schemas';+import type { AppConfig, ConfigOverrideLayer } from '@librechat/data-schemas';import type { Types } from 'mongoose';import type { CustomConfigLoadMode } from './loader';import { checkAppConfigTheme } from './theme';@@ -226,7 +226,7 @@ export interface AppConfigServiceDeps {/** The CacheKeys constants from librechat-data-provider. */cacheKeys: { APP_CONFIG: string };/** Fetch applicable DB config overrides for a set of principals. */- getApplicableConfigs: (principals?: AppConfigPrincipal[]) => Promise<IConfig[]>;+ getApplicableConfigs: (principals?: AppConfigPrincipal[]) => Promise<ConfigOverrideLayer[]>;/** Resolve full principal list (user + role + groups) from userId/role. */getUserPrincipals: (params: {userId: string | Types.ObjectId;@@ -258,6 +258,12 @@ export interface GetAppConfigOptions {resolvedPrincipals?: AppConfigPrincipal[];/** Skip mutable runtime augmentation when the caller has already loaded that data. */skipRuntimeAugmentation?: boolean;+ /**+ * Merge the overrides as stored now, neither reading nor writing the per-principal merged+ * cache. Admin reads use it so they never show a merge from before their own write. Unlike+ * `refresh`, the YAML base config is not reloaded.+ */+ bypassOverrideCache?: boolean;}export interface AppConfigUserLike {@@ -367,7 +373,40 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {const cache = getCache(cacheKeys.APP_CONFIG);let lastGoodBaseConfig: AppConfig | undefined;- let baseConfigFlight: Promise<AppConfig> | undefined;+ let baseConfigFlight: { promise: Promise<AppConfig>; generation: number } | undefined;++ /**+ * Base-config generation: `clearAppConfigCache` bumps it before deleting `_BASE_`. A reload+ * publishes its result (the cached base, the tools and the last good config) only if no clear+ * happened while it ran, and a read after a clear never joins a reload started before it, so a+ * reload that read the old librechat.yaml cannot re-cache it after a later write's clear.+ */+ let baseGeneration = 0;++ /**+ * Override-cache generations: a clear bumps the cleared tenant's (or, for a clear of every+ * tenant, the global) counter before deleting entries. A merge captures the generation, base+ * generation included, before it reads the base config or the database, and is cached only if+ * no clear happened meanwhile, so a request that read just before an admin write cannot+ * re-cache the old merge, or a merge built on the old base, just after the write's clears.+ * The check runs again once the write lands, since an async store can apply it after a+ * clear's delete.+ */+ let globalOverrideGeneration = 0;+ const tenantOverrideGenerations = new Map<string, number>();++ function getOverrideGeneration(tenantId: string | undefined): string {+ const tenant = tenantId ? (tenantOverrideGenerations.get(tenantId) ?? 0) : 0;+ return `${baseGeneration}:${globalOverrideGeneration}:${tenant}`;+ }++ function bumpOverrideGeneration(tenantId: string | undefined): void {+ if (!tenantId) {+ globalOverrideGeneration += 1;+ return;+ }+ tenantOverrideGenerations.set(tenantId, (tenantOverrideGenerations.get(tenantId) ?? 0) + 1);+ }async function buildPrincipals(role?: string,@@ -391,7 +430,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {return principals;}- async function restoreLastGoodBaseConfig(error: unknown): Promise<AppConfig> {+ async function restoreLastGoodBaseConfig(error: unknown, generation: number): Promise<AppConfig> {const lastGood = lastGoodBaseConfig;if (!lastGood) {throw error;@@ -402,6 +441,9 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {'[ensureBaseConfig] Failed to reload base configuration; keeping the last good configuration.',error,);+ if (generation !== baseGeneration) {+ return lastGood;+ }const restorations = [cache.set(BASE_CONFIG_KEY, lastGood)];if (lastGood.availableTools) {restorations.push(setCachedTools(lastGood.availableTools));@@ -412,10 +454,24 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {logger.error('[ensureBaseConfig] Failed to restore last-good config state:', result.reason);}}+ if (generation !== baseGeneration) {+ await cache.delete(BASE_CONFIG_KEY).catch((deleteError: unknown) => {+ logger.error('[ensureBaseConfig] Failed to drop an overtaken restoration:', deleteError);+ });+ }return lastGood;}- async function loadAndCacheBaseConfig(mode: CustomConfigLoadMode): Promise<AppConfig> {+ /**+ * Loads the base config and, unless a clear made `generation` stale while it loaded, publishes+ * it. A stale load still answers the reads that joined it, which started before the clear.+ * An async store (Redis) can land the write after a clear's delete, so a write a clear+ * overtook in flight is removed again.+ */+ async function loadAndCacheBaseConfig(+ mode: CustomConfigLoadMode,+ generation: number,+ ): Promise<AppConfig> {try {logger.info('[ensureBaseConfig] Loading base configuration...');const loaded = await loadBaseConfig(mode);@@ -424,23 +480,37 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {}const baseConfig = materializeConfigModelSpecs(loaded);+ if (generation !== baseGeneration) {+ return baseConfig;+ }if (baseConfig.availableTools) {await setCachedTools(baseConfig.availableTools);}+ if (generation !== baseGeneration) {+ return baseConfig;+ }await cache.set(BASE_CONFIG_KEY, baseConfig);+ if (generation !== baseGeneration) {+ await cache.delete(BASE_CONFIG_KEY);+ return baseConfig;+ }lastGoodBaseConfig = baseConfig;return baseConfig;} catch (error) {if (mode === 'startup') {throw error;}- return restoreLastGoodBaseConfig(error);+ return restoreLastGoodBaseConfig(error, generation);}}/*** Ensure the YAML-derived base config is loaded and cached.* Returns the `_BASE_` config (YAML + AppService). No DB queries.+ *+ * Reads join the load in flight for the current generation. A load for a newer generation+ * starts once the stale one settles, so the loader's process-wide side effects (such as the+ * subagent cap) end with the newest librechat.yaml rather than whichever read finished last.*/async function ensureBaseConfig(refresh?: boolean): Promise<AppConfig> {const cached = (await cache.get(BASE_CONFIG_KEY)) as AppConfig | undefined;@@ -451,15 +521,19 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {}}- if (baseConfigFlight) {- return baseConfigFlight;+ const generation = baseGeneration;+ const previous = baseConfigFlight;+ if (previous?.generation === generation) {+ return previous.promise;}const mode: CustomConfigLoadMode = lastGoodBaseConfig ? 'reload' : 'startup';- const flight = loadAndCacheBaseConfig(mode);+ const load = () => loadAndCacheBaseConfig(mode, generation);+ const promise = previous ? previous.promise.then(load, load) : load();+ const flight = { promise, generation };baseConfigFlight = flight;try {- return await flight;+ return await promise;} finally {if (baseConfigFlight === flight) {baseConfigFlight = undefined;@@ -489,6 +563,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {failClosed,resolvedPrincipals,skipRuntimeAugmentation,+ bypassOverrideCache,} = options;const ambientTenantId = getTenantId();@@ -501,6 +576,8 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {);}+ const cacheTenantId = ambientTenantId ?? effectiveTenantId;+ const generation = getOverrideGeneration(cacheTenantId);const baseConfig = await ensureBaseConfig(refresh);const scopedBaseConfig = await scopeBaseConfig(baseConfig, effectiveTenantId);const hiddenEndpoints = hiddenCustomEndpoints(baseConfig, effectiveTenantId);@@ -565,13 +642,13 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {]),).digest('hex');- const cacheKey = overrideCacheKey(- role,- userId,- ambientTenantId ?? effectiveTenantId,- scopeVersion,- );- if (!refresh) {+ const cacheKey = overrideCacheKey(role, userId, cacheTenantId, scopeVersion);+ /**+ * The key names a role and user, not a principal set: principals resolved elsewhere are+ * cached only when a user id ties them to the key.+ */+ const cacheable = bypassOverrideCache !== true && (resolvedPrincipals == null || !!userId);+ if (cacheable && !refresh) {const cachedMerged = (await cache.get(cacheKey)) as AppConfig | undefined;if (cachedMerged) {return await augment(cachedMerged);@@ -597,7 +674,12 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {return scopedBaseConfig;}- await cache.set(cacheKey, merged, overrideCacheTtl);+ if (cacheable && getOverrideGeneration(cacheTenantId) === generation) {+ await cache.set(cacheKey, merged, overrideCacheTtl);+ if (getOverrideGeneration(cacheTenantId) !== generation) {+ await cache.delete(cacheKey);+ }+ }return await augment(merged);}@@ -606,8 +688,10 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {* are NOT flushed — they expire naturally via `overrideCacheTtl`. After calling this,* the base config will be reloaded from YAML on the next `getAppConfig` call, but* users with cached overrides may see stale merged configs for up to `overrideCacheTtl` ms.+ * Reloads and merges already in flight are not cached afterwards.*/async function clearAppConfigCache(): Promise<void> {+ baseGeneration += 1;await cache.delete(BASE_CONFIG_KEY);}@@ -617,6 +701,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {* caches are cleared.*/async function clearOverrideCache(tenantId?: string): Promise<void> {+ bumpOverrideGeneration(tenantId);const namespace = cacheKeys.APP_CONFIG;const overrideSegment = tenantId ? `_OVERRIDE_:${tenantId}:tenant:` : '_OVERRIDE_:';diff --git a/packages/api/src/cache/__tests__/resp.helper.ts b/packages/api/src/cache/__tests__/resp.helper.tsindex 99bf497960..51597e2bb9 100644--- a/packages/api/src/cache/__tests__/resp.helper.ts+++ b/packages/api/src/cache/__tests__/resp.helper.ts@@ -5,7 +5,8 @@ import type { AddressInfo, Socket } from 'node:net';* Minimal RESP2 server standing in for a Redis node whose role can be flipped* between master and demoted replica. Real node-redis and ioredis clients speak* to it over TCP, which is what a READONLY failover scenario needs: the socket- * stays open and healthy while every write is rejected.+ * stays open and healthy while every write is rejected. PUBLISH fans out to the+ * connections subscribed to the channel, so pub/sub between clients works too.*/export type RespServer = {url: string;@@ -87,7 +88,43 @@ export async function startRespServer(port = 0): Promise<RespServer> {const sockets = new Set<Socket>();const state = { connections: 0, readonly: false, silent: false, commands: [] as string[][] };- const reply = (args: string[]): string => {+ const subscriptions = new Map<Socket, Set<string>>();++ const channelsOf = (socket: Socket): Set<string> => {+ let channels = subscriptions.get(socket);+ if (!channels) {+ channels = new Set();+ subscriptions.set(socket, channels);+ }+ return channels;+ };++ const publish = (channel: string, message: string): number => {+ let delivered = 0;+ for (const [subscriber, channels] of subscriptions) {+ if (channels.has(channel)) {+ delivered += 1;+ subscriber.write(`*3\r\n$7\r\nmessage\r\n${encodeBulk(channel)}${encodeBulk(message)}`);+ }+ }+ return delivered;+ };++ const subscriptionReply = (socket: Socket, kind: string, names: string[]): string => {+ const channels = channelsOf(socket);+ return names+ .map((name) => {+ if (kind === 'subscribe') {+ channels.add(name);+ } else {+ channels.delete(name);+ }+ return `*3\r\n${encodeBulk(kind)}${encodeBulk(name)}:${channels.size}\r\n`;+ })+ .join('');+ };++ const reply = (socket: Socket, args: string[]): string => {const command = args[0]?.toUpperCase() ?? '';if (state.readonly && WRITE_COMMANDS.has(command)) {return READONLY_REPLY;@@ -96,7 +133,11 @@ export async function startRespServer(port = 0): Promise<RespServer> {case 'PING':return '+PONG\r\n';case 'SUBSCRIBE':- return `*3\r\n$9\r\nsubscribe\r\n${encodeBulk(args[1])}:1\r\n`;+ return subscriptionReply(socket, 'subscribe', args.slice(1));+ case 'UNSUBSCRIBE':+ return subscriptionReply(socket, 'unsubscribe', args.slice(1));+ case 'PUBLISH':+ return `:${publish(args[1], args[2])}\r\n`;case 'INFO':return encodeBulk('# Server\r\nredis_version:7.2.4\r\nloading:0\r\n');case 'GET':@@ -127,11 +168,14 @@ export async function startRespServer(port = 0): Promise<RespServer> {for (const frame of frames) {state.commands.push(frame);if (!state.silent) {- socket.write(reply(frame));+ socket.write(reply(socket, frame));}}});- socket.on('close', () => sockets.delete(socket));+ socket.on('close', () => {+ sockets.delete(socket);+ subscriptions.delete(socket);+ });socket.on('error', () => undefined);});diff --git a/packages/data-schemas/misc/documentdb/documentdb-compat.md b/packages/data-schemas/misc/documentdb/documentdb-compat.mdindex 8424dc444e..63e25673cd 100644--- a/packages/data-schemas/misc/documentdb/documentdb-compat.md+++ b/packages/data-schemas/misc/documentdb/documentdb-compat.md@@ -348,20 +348,78 @@ This sweep exists because every incompatibility found so far was invisibleuntil someone thought to look for its class; here the engine adjudicateswhatever each method emits, known class or not.-## Dotted keys in admin config overrides (2026-10-20, DocumentDB pending)+## Admin config overrides — key encoding (2026-10-21)++Admin config override documents (`configs.overrides`) are free-form JSON whose+record keys legitimately contain `.` (Bedrock inference profiles such as+`us.anthropic.claude-sonnet-4-5`, Azure model names such as `gpt-4.1`, MIME+patterns, header names) and can start with `$`. MongoDB 5+ stores such field+names but cannot address them in an update; DocumentDB, Cosmos DB (MongoDB+API) and FerretDB restrict them further. Whether DocumentDB 5.0 and Cosmos+accept dotted names inside a Mixed subdocument was never adjudicated live.++The question no longer needs an answer. Config persistence goes through the+portable store contract (`src/app/store.ts`, conformance suite+`src/app/conformance.ts`), and the Mongoose binding (`src/methods/config.ts`)+writes every document whole with plain `$set`. Its keys go raw when the engine+stores them, and reversibly percent-escaped (`%`, `.`, `$` and NUL in every+object key, `src/methods/encoding.ts`) when the engine refuses a raw name. An+engine that cannot store a dotted or `$`-prefixed field name therefore never+holds one, so DocumentDB and Cosmos are covered whichever way their field-name+rules turn out. Values are never rewritten.++- Write form: the binding sends the keys raw first. When the engine refuses a+ field name (`isFieldNameRejection`), the refused write changed nothing, and+ it is sent again encoded under the same revision precondition; that process+ then encodes every later write that holds such a key. A document is also+ written encoded when its keys spell escape sequences (`%2E`, `%24`, `%25`,+ `%00`) while none holds a raw `.`, `$` or NUL, since a raw read would decode+ them. An encoded document carries `keyEncoding: 1`; a raw write clears it.+- Reads decode a marked document, and an unmarked one unless some key holds a+ raw `.`, `$` or NUL (no encoded document does). The decoder rewrites only the+ four sequences above, so raw keys an older server adds to an encoded+ document, or writes under a marker it left in place, read as stored.+- Rolling upgrades and rollback: servers before the encoding read every key+ literally. On MongoDB 4.4+ (dotted names) and 5.0+ (`$` names inside a+ value) the binding keeps writing raw keys, so an older server reads exactly+ what it wrote. Only on an engine that refuses raw names does an older server+ meet encoded keys, and those are entries it could not store itself (it+ answered 422 `CONFIG_KEY_NOT_STORABLE`): it reads them as+ `us%2Eanthropic%2Eclaude-sonnet-4-5` until it is upgraded. An older server's+ group or role deletion that restores a config document drops the+ `keyEncoding` field its schema lacks; the read rule above still decodes that+ document. The one key a read can misread is a raw key that literally spells+ one of the four escape sequences, in a document an older server wrote with no+ dotted or `$` key.+- No dotted-path `$set`/`$unset` or `$pull`/`$addToSet` touches `overrides` or+ `tombstones`; every mutation is a pure transform followed by one+ compare-and-swap on `{_id, configVersion}`, which every engine supports.+- Pre-release check on a real cluster: run the conformance runner+ (`misc/ferretdb/configStore.ferretdb.spec.ts`, any MongoDB-compatible URI in+ `FERRETDB_URI`) against DocumentDB 5.0 and Cosmos. It passes 24/24 against+ mongod 8.2 and mongodb-memory-server; FerretDB and the managed engines were+ not available when this was written.+- The runner is destructive: it deletes every document in the target+ database's `configs` collection before each case and drops the collection+ at teardown. Give it a throwaway database on the cluster (for example+ `.../config_store_test`), never a database a deployment uses. It refuses to+ start when `configs` already holds documents.+- `compat.documentdb.spec.ts` › "admin config overrides with dotted record keys"+ writes through `patchConfigFields` and `upsertConfig`, which store keys raw+ or, on an engine that refuses them, encoded, so on DocumentDB and Cosmos it+ checks whichever round trip the engine takes:+ `npx jest --config misc/documentdb/jest.documentdb.config.mjs -t 'dotted record keys'`.+- The 422 `CONFIG_KEY_NOT_STORABLE` answer (`isFieldNameRejection`) remains+ for a key name the engine refuses in both forms, such as an empty key.-The admin config API keeps dotted record keys in write bodies: Bedrock-inference profiles (`us.anthropic.claude-sonnet-4-6`), model names-(`gpt-4.1`), MIME types and header names. They land in the `overrides` Mixed-subdocument through two write shapes: `patchConfigFields` sets a dotted-`overrides.<path>` whose value carries dotted keys, and `upsertConfig` sets-the whole `overrides` object. Dots in path segments are never written as-paths; only keys inside values hold them.+### Before the encoding: raw dotted keys (2026-10-20)-`compat.documentdb.spec.ts` › "admin config overrides with dotted record keys"-covers both shapes and records whether the engine stores a `$`-prefixed key-inside a value. Local runs used the whole compat suite against a single-node-replica set of each server (16 of 16 passing on every version):+Before the store encoded keys, dotted record keys reached the engine verbatim+through a dotted `$set` path and a whole-object `$set`. Documents written then+carry no `keyEncoding` marker and still hold raw dotted names, which the+binding reads verbatim and keeps raw on engines that store them. Local runs of+the compat suite against a single-node replica set of each server (16 of 16+passing on every version):| Engine | Dotted keys, `$set` path | Dotted keys, whole `$set` | `$` key inside a value || --------------------------- | ------------------------ | ------------------------- | ---------------------- |@@ -372,14 +430,3 @@ replica set of each server (16 of 16 passing on every version):| MongoDB 8.2.6 (local) | supported | supported | stored || Amazon DocumentDB 5.0 | **not yet run** | **not yet run** | **not yet run** || Azure Cosmos DB for MongoDB | **not yet run** | **not yet run** | **not yet run** |--- MongoDB 5.0 and later store a `$` key inside a value, so the admin config- router's post-auth guard (`CONFIG_UNSAFE_KEY`) is the only `$` check there.-- Before a release that advertises `dottedKeys`, run the block against a- DocumentDB 5.0 cluster (and Cosmos DB where it is supported):- `npx jest --config misc/documentdb/jest.documentdb.config.mjs -t 'dotted record keys'`.-- If an engine rejects the writes, the request fails with 422- `CONFIG_KEY_NOT_STORABLE` (`isFieldNameRejection` recognizes the engine's- error) and nothing is stored; nothing is silently dropped. The fallback is- reversible key encoding at the data-schemas storage boundary (escape `.`, a- leading `$` and the escape character on write; decode on read).diff --git a/packages/data-schemas/misc/ferretdb/configStore.ferretdb.spec.ts b/packages/data-schemas/misc/ferretdb/configStore.ferretdb.spec.tsnew file mode 100644index 0000000000..61492984fd--- /dev/null+++ b/packages/data-schemas/misc/ferretdb/configStore.ferretdb.spec.ts@@ -0,0 +1,72 @@+import mongoose from 'mongoose';+import type { ConfigStoreHarness } from '~/app/conformance';+import { describeConfigStoreConformance } from '~/app/conformance';+import { createConfigStore } from '~/methods/config';+import { createConfigModel } from '~/models/config';++/**+ * The portable config store contract against a live engine: FerretDB (PostgreSQL + DocumentDB+ * extension), or any MongoDB-compatible server for parity. The binding stores override keys raw+ * where the engine accepts them and encoded where it refuses a dotted or `$`-prefixed field name,+ * so no engine ever holds a name it cannot store; this run proves the round trip on an engine+ * stricter than mongod.+ *+ * Run against FerretDB (see docker-compose.ferretdb.yml):+ * FERRETDB_URI="mongodb://ferretdb:[email protected]:27020/config_store_test" \+ * npx jest --config misc/ferretdb/jest.ferretdb.config.mjs configStore.ferretdb+ *+ * Run against MongoDB (for parity):+ * FERRETDB_URI="mongodb://127.0.0.1:27017/config_store_test" \+ * npx jest --config misc/ferretdb/jest.ferretdb.config.mjs configStore.ferretdb+ *+ * AWS DocumentDB and Azure Cosmos DB (MongoDB API) may restrict field names the same way and are+ * covered by the same fallback; they cannot be run locally.+ *+ * Destructive: the run deletes every document in the database's `configs` collection before each+ * case and drops the collection at teardown. Point `FERRETDB_URI` at a throwaway database, never+ * at one a LibreChat deployment uses. Setup refuses a `configs` collection that already holds+ * documents; after an interrupted run, drop that collection by hand.+ */++const FERRETDB_URI = process.env.FERRETDB_URI;++/** Set once setup has seen an empty `configs` collection; nothing is dropped before that. */+let owned = false;++const harness: ConfigStoreHarness = {+ name: `mongoose on ${FERRETDB_URI ? new URL(FERRETDB_URI).host : 'FERRETDB_URI (unset)'}`,++ async setup() {+ await mongoose.connect(FERRETDB_URI as string);+ const configs = mongoose.connection.db?.collection('configs');+ if (!configs || (await configs.countDocuments({}, { limit: 1 })) > 0) {+ throw new Error(+ 'The configs collection at FERRETDB_URI already holds documents; this runner deletes them. Use a throwaway database.',+ );+ }+ owned = true;+ await createConfigModel(mongoose).init();+ return createConfigStore(mongoose);+ },++ async teardown() {+ if (owned) {+ await mongoose.connection.dropCollection('configs').catch(() => undefined);+ }+ await mongoose.disconnect();+ },++ async reset() {+ await mongoose.models.Config.deleteMany({});+ },+};++if (FERRETDB_URI) {+ describeConfigStoreConformance(harness);+} else {+ describe.skip('config store conformance (set FERRETDB_URI to run)', () => {+ it('runs against a live engine', () => {+ expect(FERRETDB_URI).toBeDefined();+ });+ });+}diff --git a/packages/data-schemas/src/app/conformance.memory.spec.ts b/packages/data-schemas/src/app/conformance.memory.spec.tsnew file mode 100644index 0000000000..82c55d2f36--- /dev/null+++ b/packages/data-schemas/src/app/conformance.memory.spec.ts@@ -0,0 +1,120 @@+import { PrincipalType, PrincipalModel } from 'librechat-data-provider';+import type { ConfigStore, ConfigRecord, ConfigPrincipal } from './store';+import type { ConfigStoreHarness } from './conformance';+import {+ ABSENT_CONFIG_REVISION,+ ConfigRevisionConflictError,+ createConfigOperations,+ compareConfigRecords,+ getConfigRevision,+} from './store';+import { describeConfigStoreConformance } from './conformance';++/**+ * A reference engine with no storage behind it: a map of JSON strings. It proves the suite+ * asks only for the contract (nothing Mongo-shaped leaks into it) and documents the minimum a+ * new engine implements. Each operation finishes its compare-and-swap without yielding, which+ * is the atomicity a real engine gets from a conditional update.+ */+function createMemoryConfigStore(): ConfigStore & { clear(): void } {+ const documents = new Map<string, string>();+ let sequence = 0;++ const keyOf = ({ principalType, principalId }: ConfigPrincipal): string =>+ `${principalType}\u0000${principalId}`;+ const load = (key: string): ConfigRecord | null => {+ const stored = documents.get(key);+ return stored ? (JSON.parse(stored) as ConfigRecord) : null;+ };+ const save = (record: ConfigRecord): ConfigRecord => {+ documents.set(keyOf(record), JSON.stringify(record));+ return load(keyOf(record)) as ConfigRecord;+ };+ const all = (): ConfigRecord[] =>+ [...documents.keys()].map((key) => load(key) as ConfigRecord).sort(compareConfigRecords);++ return {+ clear: () => documents.clear(),++ async read(principal) {+ return load(keyOf(principal));+ },++ async list(filter) {+ return all().filter(+ (record) => filter?.isActive === undefined || record.isActive === filter.isActive,+ );+ },++ async listActive(principals) {+ const wanted = new Set(principals.map(keyOf));+ return all().filter((record) => record.isActive && wanted.has(keyOf(record)));+ },++ async write(principal, draft, expected) {+ const current = load(keyOf(principal));+ if (expected !== (current ? getConfigRevision(current) : ABSENT_CONFIG_REVISION)) {+ throw new ConfigRevisionConflictError();+ }+ sequence += 1;+ return save({+ ...draft,+ principalType: principal.principalType,+ principalId: principal.principalId,+ _id: current?._id ?? sequence.toString(16).padStart(24, '0'),+ configVersion: (current?.configVersion ?? 0) + 1,+ });+ },++ async remove(principal, expected) {+ const current = load(keyOf(principal));+ if (expected !== undefined) {+ const revision = current ? getConfigRevision(current) : ABSENT_CONFIG_REVISION;+ if (expected !== revision) {+ throw new ConfigRevisionConflictError(current ? revision : null);+ }+ }+ documents.delete(keyOf(principal));+ return current;+ },++ async restore(snapshot) {+ if (documents.has(keyOf(snapshot))) {+ return false;+ }+ save(snapshot);+ return true;+ },+ };+}++const store = createMemoryConfigStore();++const harness: ConfigStoreHarness = {+ name: 'memory reference engine',+ setup: async () => store,+ teardown: async () => undefined,+ reset: async () => store.clear(),+};++describeConfigStoreConformance(harness);++describe('unconditioned writes on the memory reference engine', () => {+ it('lands a burst of concurrent writers by pausing between retries', async () => {+ const operations = createConfigOperations(createMemoryConfigStore());+ const principal = { principalType: PrincipalType.ROLE, principalId: 'burst' };+ const fields = Array.from({ length: 8 }, (_, index) => `field${index}`);++ await Promise.all(+ fields.map((field) =>+ operations.setFields(principal, PrincipalModel.ROLE, { [`interface.${field}`]: field }),+ ),+ );++ const stored = await operations.findConfig(principal);+ expect(stored?.configVersion).toBe(fields.length);+ expect(stored?.overrides).toEqual({+ interface: Object.fromEntries(fields.map((field) => [field, field])),+ });+ });+});diff --git a/packages/data-schemas/src/app/conformance.mongoose.spec.ts b/packages/data-schemas/src/app/conformance.mongoose.spec.tsnew file mode 100644index 0000000000..3fd93f21f8--- /dev/null+++ b/packages/data-schemas/src/app/conformance.mongoose.spec.ts@@ -0,0 +1,36 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import type { ConfigStoreHarness } from './conformance';+import { describeConfigStoreConformance } from './conformance';+import { createConfigStore } from '~/methods/config';+import { createConfigModel } from '~/models/config';++/**+ * The Mongoose binding's answer to the portable config store contract, on a real mongod.+ * Key encoding and legacy-document behaviour specific to this engine are covered in+ * `methods/config.spec.ts`.+ */++let server: MongoMemoryServer;++const harness: ConfigStoreHarness = {+ name: 'mongoose',++ async setup() {+ server = await MongoMemoryServer.create();+ await mongoose.connect(server.getUri());+ await createConfigModel(mongoose).init();+ return createConfigStore(mongoose);+ },++ async teardown() {+ await mongoose.disconnect();+ await server.stop();+ },++ async reset() {+ await mongoose.models.Config.deleteMany({});+ },+};++describeConfigStoreConformance(harness);diff --git a/packages/data-schemas/src/app/conformance.ts b/packages/data-schemas/src/app/conformance.tsnew file mode 100644index 0000000000..3b5a0200a1--- /dev/null+++ b/packages/data-schemas/src/app/conformance.ts@@ -0,0 +1,492 @@+/* eslint-disable jest/no-export -- This file is a shared contract-test suite, not a+ spec: it exports the harness interface and the suite factory that each engine's+ own spec imports. The rule guards against accidental exports from spec files. */+/**+ * The portable admin-config store contract, as tests.+ *+ * `./store` defines the contract and the operations built on it. This suite checks what only+ * an engine can be asked: that it stores override documents verbatim whatever their keys, that+ * every write is a compare-and-swap on a revision, and that listing is deterministic. An+ * engine satisfies the contract by implementing `ConfigStoreHarness` and calling+ * `describeConfigStoreConformance` from a spec: Mongoose against mongodb-memory-server today+ * (`conformance.mongoose.spec.ts`, and `misc/ferretdb` against FerretDB or a real mongod), a+ * PostgreSQL/JSONB engine later.+ *+ * Engine-specific behaviour (key encoding at rest, legacy documents) stays in the engine's own+ * spec. Tenant isolation has its own contract in `~/tenant/conformance`.+ */++import { PrincipalType, PrincipalModel } from 'librechat-data-provider';+import type { TCustomConfig } from 'librechat-data-provider';+import type { ConfigDraft, ConfigStore, ConfigRecord, ConfigPrincipal } from './store';+import {+ ABSENT_CONFIG_REVISION,+ createConfigOperations,+ isConfigRevisionConflict,+ getConfigRevision,+} from './store';+import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';++export interface ConfigStoreHarness {+ readonly name: string;+ /** Prepares the engine and returns the store under test. */+ setup(): Promise<ConfigStore>;+ teardown(): Promise<void>;+ /** Removes every document. */+ reset(): Promise<void>;+}++const role = (principalId: string): ConfigPrincipal => ({+ principalType: PrincipalType.ROLE,+ principalId,+});++const group = (principalId: string): ConfigPrincipal => ({+ principalType: PrincipalType.GROUP,+ principalId,+});++function draft(+ overrides: Record<string, unknown> = {},+ extra: Partial<ConfigDraft> = {},+): ConfigDraft {+ return {+ principalModel: PrincipalModel.ROLE,+ priority: 10,+ overrides: overrides as Partial<TCustomConfig>,+ tombstones: [],+ isActive: true,+ ...extra,+ };+}++/** Keys that MongoDB-compatible engines cannot address or store as field names, at every depth. */+const AWKWARD_KEYS = [+ 'us.anthropic.claude-sonnet-4-5',+ 'gpt-4.1',+ '.leading',+ 'trailing.',+ 'a..b',+ '$set',+ '$',+ 'price$',+ 'mid$dle',+ '%',+ '%25',+ '%2E',+ '%2e',+ '%24',+ '%00',+ '%%',+ '100%',+ 'ünïcödé',+ '模型.名称',+ '🔑.emoji',+ 'é',+ 'image/*',+ 'text/plain; charset=utf-8',+];++function keyedObject(depth: number): Record<string, unknown> {+ const leaf = Object.fromEntries(AWKWARD_KEYS.map((key, index) => [key, index]));+ let value: Record<string, unknown> = leaf;+ for (let level = 0; level < depth; level++) {+ value = { [AWKWARD_KEYS[level % AWKWARD_KEYS.length]]: value, plain: level };+ }+ return value;+}++export function describeConfigStoreConformance(harness: ConfigStoreHarness): void {+ describe(`config store conformance: ${harness.name}`, () => {+ let store: ConfigStore;++ beforeAll(async () => {+ store = await harness.setup();+ });+ afterAll(() => harness.teardown());+ beforeEach(() => harness.reset());++ const conflictOf = async (promise: Promise<unknown>): Promise<unknown> => {+ try {+ await promise;+ } catch (error) {+ return error;+ }+ throw new Error('expected a revision conflict');+ };++ describe('documents', () => {+ it('reads nothing for a principal without a document', async () => {+ expect(await store.read(role('nobody'))).toBeNull();+ });++ it('creates a document at version 1 and reads back exactly what was written', async () => {+ const written = await store.write(+ role('editor'),+ draft({ interface: { customWelcome: 'hi' } }, { tombstones: ['memory.agent'] }),+ ABSENT_CONFIG_REVISION,+ );++ expect(written).toEqual(+ expect.objectContaining({+ principalType: PrincipalType.ROLE,+ principalId: 'editor',+ principalModel: PrincipalModel.ROLE,+ priority: 10,+ isActive: true,+ configVersion: 1,+ overrides: { interface: { customWelcome: 'hi' } },+ tombstones: ['memory.agent'],+ }),+ );+ expect(typeof written._id).toBe('string');+ expect(getConfigRevision(written)).toBe(`${written._id}:1`);+ expect(await store.read(role('editor'))).toEqual(written);+ });++ it('round-trips dotted, `$`, escape-like and unicode keys at every depth', async () => {+ const overrides = {+ ...Object.fromEntries(AWKWARD_KEYS.map((key) => [key, { nested: key }])),+ endpoints: {+ bedrock: { inferenceProfiles: keyedObject(0) },+ azureOpenAI: {+ groups: [{ group: 'g', models: { 'gpt-4.1': true, '$x.y': { 'a.b': 1 } } }],+ },+ custom: [+ {+ name: 'c',+ headers: { 'X.Trace': '${TRACE}', $ref: 'v' },+ addParams: keyedObject(3),+ },+ ],+ },+ fileConfig: { endpoints: { 'agents.v2': { supportedMimeTypes: ['image/.*', '$'] } } },+ deep: keyedObject(12),+ };++ const written = await store.write(role('keys'), draft(overrides), ABSENT_CONFIG_REVISION);++ expect(written.overrides).toEqual(overrides);+ expect((await store.read(role('keys')))?.overrides).toEqual(overrides);+ expect((await store.list())[0].overrides).toEqual(overrides);+ expect((await store.listActive([role('keys')]))[0].overrides).toEqual(overrides);+ });++ it('never rewrites values, only keys', async () => {+ const overrides = {+ interface: { customWelcome: 'a.b $c %2E %25 %24 ${VAR} 模型' },+ list: ['a.b', '$c', '%2E', { 'k.k': ['%24', null, true, 1.5] }],+ };++ await store.write(role('values'), draft(overrides), ABSENT_CONFIG_REVISION);++ expect((await store.read(role('values')))?.overrides).toEqual(overrides);+ });++ it('keeps empty objects and arrays, which carry meaning (an empty theme replaces the base one)', async () => {+ const overrides = {+ interface: { theme: {} },+ endpoints: { custom: [] },+ list: [{}, []],+ deep: { a: { b: {} } },+ };++ await store.write(role('empty'), draft(overrides), ABSENT_CONFIG_REVISION);++ expect((await store.read(role('empty')))?.overrides).toEqual(overrides);+ });++ it('keeps tombstones as written', async () => {+ const tombstones = ['mcpServers.github', 'memory.agent.id', 'endpoints.custom'];++ await store.write(role('hidden'), draft({}, { tombstones }), ABSENT_CONFIG_REVISION);++ expect((await store.read(role('hidden')))?.tombstones).toEqual(tombstones);+ });++ it('reads inactive documents', async () => {+ await store.write(role('off'), draft({}, { isActive: false }), ABSENT_CONFIG_REVISION);++ expect((await store.read(role('off')))?.isActive).toBe(false);+ });+ });++ describe('compare-and-swap', () => {+ it('replaces the whole document at the current revision and bumps the version', async () => {+ const first = await store.write(+ role('cas'),+ draft({ a: { b: 1 }, keep: true }, { tombstones: ['x.y'] }),+ ABSENT_CONFIG_REVISION,+ );++ const second = await store.write(+ role('cas'),+ draft({ a: { c: 2 } }, { priority: 30, isActive: false }),+ getConfigRevision(first),+ );++ expect(second._id).toBe(first._id);+ expect(second.configVersion).toBe(2);+ expect(second.overrides).toEqual({ a: { c: 2 } });+ expect(second.tombstones).toEqual([]);+ expect(second.priority).toBe(30);+ expect(second.isActive).toBe(false);+ });++ it('refuses a create when the principal already has a document', async () => {+ const first = await store.write(role('dup'), draft({ a: 1 }), ABSENT_CONFIG_REVISION);++ const error = await conflictOf(+ store.write(role('dup'), draft({ a: 2 }), ABSENT_CONFIG_REVISION),+ );++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(await store.read(role('dup'))).toEqual(first);+ });++ it('refuses a stale revision and leaves the document unchanged', async () => {+ const first = await store.write(role('stale'), draft({ a: 1 }), ABSENT_CONFIG_REVISION);+ const second = await store.write(role('stale'), draft({ a: 2 }), getConfigRevision(first));++ const error = await conflictOf(+ store.write(role('stale'), draft({ a: 3 }), getConfigRevision(first)),+ );++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(await store.read(role('stale'))).toEqual(second);+ });++ it('never creates a document when a write names a revision of one that does not exist', async () => {+ const gone = await store.write(role('gone'), draft(), ABSENT_CONFIG_REVISION);+ await store.remove(role('gone'));++ const error = await conflictOf(store.write(role('gone'), draft(), getConfigRevision(gone)));++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(await store.read(role('gone'))).toBeNull();+ });++ it('refuses a revision of a deleted document after the principal is recreated (ABA)', async () => {+ const original = await store.write(+ role('aba'),+ draft({ v: 'old' }),+ ABSENT_CONFIG_REVISION,+ );+ await store.remove(role('aba'));+ const recreated = await store.write(+ role('aba'),+ draft({ v: 'new' }),+ ABSENT_CONFIG_REVISION,+ );+ expect(recreated.configVersion).toBe(original.configVersion);++ const error = await conflictOf(+ store.write(role('aba'), draft({ v: 'stale' }), getConfigRevision(original)),+ );++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect((await store.read(role('aba')))?.overrides).toEqual({ v: 'new' });+ });++ it('lets exactly one of two concurrent writes at the same revision win', async () => {+ const base = await store.write(role('race'), draft({ n: 0 }), ABSENT_CONFIG_REVISION);++ const results = await Promise.allSettled([+ store.write(role('race'), draft({ n: 1 }), getConfigRevision(base)),+ store.write(role('race'), draft({ n: 2 }), getConfigRevision(base)),+ ]);++ const fulfilled = results.filter((result) => result.status === 'fulfilled');+ const rejected = results.filter(+ (result): result is PromiseRejectedResult => result.status === 'rejected',+ );+ expect(fulfilled).toHaveLength(1);+ expect(rejected).toHaveLength(1);+ expect(isConfigRevisionConflict(rejected[0].reason)).toBe(true);+ const stored = await store.read(role('race'));+ expect(stored?.configVersion).toBe(2);+ expect(stored).toEqual((fulfilled[0] as PromiseFulfilledResult<ConfigRecord>).value);+ });++ it('lets exactly one of two concurrent creates win', async () => {+ const results = await Promise.allSettled([+ store.write(role('first'), draft({ n: 1 }), ABSENT_CONFIG_REVISION),+ store.write(role('first'), draft({ n: 2 }), ABSENT_CONFIG_REVISION),+ ]);++ expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);+ expect((await store.list()).length).toBe(1);+ });++ it('rejects a malformed revision as a conflict without writing', async () => {+ await store.write(role('odd'), draft({ a: 1 }), ABSENT_CONFIG_REVISION);++ const error = await conflictOf(store.write(role('odd'), draft({ a: 2 }), 'not-a-revision'));++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect((await store.read(role('odd')))?.overrides).toEqual({ a: 1 });+ });+ });++ describe('remove and restore', () => {+ it('removes and returns the document; a missing one is null', async () => {+ const written = await store.write(role('rm'), draft({ a: 1 }), ABSENT_CONFIG_REVISION);++ expect(await store.remove(role('rm'))).toEqual(written);+ expect(await store.remove(role('rm'))).toBeNull();+ expect(await store.read(role('rm'))).toBeNull();+ });++ it('removes only at the expected revision', async () => {+ const first = await store.write(role('rmcas'), draft({ a: 1 }), ABSENT_CONFIG_REVISION);+ const second = await store.write(role('rmcas'), draft({ a: 2 }), getConfigRevision(first));++ const error = await conflictOf(store.remove(role('rmcas'), getConfigRevision(first)));+ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(await store.read(role('rmcas'))).toEqual(second);++ expect(await store.remove(role('rmcas'), getConfigRevision(second))).toEqual(second);+ expect(await store.remove(role('rmcas'), ABSENT_CONFIG_REVISION)).toBeNull();+ });++ it('restores a removed document as it was, and never over a newer one', async () => {+ const written = await store.write(+ role('restore'),+ draft({ 'gpt-4.1': { $x: 1 } }, { tombstones: ['a.b'], isActive: false, priority: 7 }),+ ABSENT_CONFIG_REVISION,+ );+ const removed = await store.remove(role('restore'));++ expect(await store.restore(removed as ConfigRecord)).toBe(true);+ const restored = await store.read(role('restore'));+ expect(restored).toEqual(written);+ expect(getConfigRevision(restored as ConfigRecord)).toBe(getConfigRevision(written));++ const newer = await store.write(+ role('restore'),+ draft({ v: 2 }),+ getConfigRevision(written),+ );+ expect(await store.restore(removed as ConfigRecord)).toBe(false);+ expect(await store.read(role('restore'))).toEqual(newer);+ });+ });++ describe('listing', () => {+ async function seed(): Promise<ConfigRecord[]> {+ const records: ConfigRecord[] = [];+ for (const [principal, priority, isActive] of [+ [role('b'), 20, true],+ [role(BASE_CONFIG_PRINCIPAL_ID), 0, true],+ [group('g2'), 20, true],+ [role('a'), 20, true],+ [group('g1'), 5, false],+ [role('c'), 100, true],+ ] as Array<[ConfigPrincipal, number, boolean]>) {+ records.push(+ await store.write(principal, draft({}, { priority, isActive }), ABSENT_CONFIG_REVISION),+ );+ }+ return records;+ }++ const ids = (records: ConfigRecord[]): string[] =>+ records.map((record) => `${record.principalType}:${record.principalId}`);++ it('orders by priority, then identity, the same way every time', async () => {+ const records = await seed();+ const tied = records+ .filter((record) => record.priority === 20)+ .sort((left, right) => (left._id < right._id ? -1 : 1));++ const listed = await store.list();+ expect(listed.map((record) => record.priority)).toEqual([0, 5, 20, 20, 20, 100]);+ expect(listed.slice(2, 5).map((record) => record._id)).toEqual(+ tied.map((record) => record._id),+ );+ expect(ids(await store.list())).toEqual(ids(listed));+ });++ it('filters the full list by active state', async () => {+ await seed();++ expect(ids(await store.list({ isActive: false }))).toEqual(['group:g1']);+ expect(await store.list({ isActive: true })).toHaveLength(5);+ });++ it('lists only the active documents of the requested principals, in store order', async () => {+ await seed();++ const listed = await store.listActive([+ role('c'),+ group('g1'),+ role(BASE_CONFIG_PRINCIPAL_ID),+ role('a'),+ group('missing'),+ ]);++ expect(ids(listed)).toEqual([`role:${BASE_CONFIG_PRINCIPAL_ID}`, 'role:a', 'role:c']);+ expect(await store.listActive([])).toEqual([]);+ });+ });++ describe('operations on this engine', () => {+ it('tombstones remove the override subtree, prune emptied parents, and are cleared by a write', async () => {+ const operations = createConfigOperations(store);+ await operations.setFields(role('ops'), PrincipalModel.ROLE, {+ 'mcpServers.github.title': 'GitHub',+ 'balance.enabled': true,+ });++ const hidden = await operations.tombstoneFields(role('ops'), PrincipalModel.ROLE, [+ 'mcpServers.github',+ 'memory.agent',+ ]);+ expect(hidden.overrides).toEqual({ balance: { enabled: true } });+ expect(hidden.tombstones).toEqual(['mcpServers.github', 'memory.agent']);++ const reset = await operations.unsetFields(role('ops'), 'balance.enabled');+ expect(reset?.overrides).toEqual({});+ expect(reset?.tombstones).toEqual(['mcpServers.github', 'memory.agent']);++ const shown = await operations.setFields(role('ops'), PrincipalModel.ROLE, {+ 'mcpServers.github.title': 'Again',+ });+ expect(shown.tombstones).toEqual(['memory.agent']);+ expect(shown.configVersion).toBe(4);+ });++ it('surfaces a conflict when a caller-supplied revision is stale', async () => {+ const operations = createConfigOperations(store);+ const first = await operations.setFields(role('stale-op'), PrincipalModel.ROLE, {+ 'a.b': 1,+ });+ await operations.setFields(role('stale-op'), PrincipalModel.ROLE, { 'a.b': 2 });++ const error = await conflictOf(+ operations.setFields(role('stale-op'), PrincipalModel.ROLE, { 'a.b': 3 }, undefined, {+ expectedRevision: getConfigRevision(first),+ }),+ );++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect((await store.read(role('stale-op')))?.overrides).toEqual({ a: { b: 2 } });+ });++ it('absorbs concurrent writes without a revision so none is lost', async () => {+ const operations = createConfigOperations(store);+ await operations.setFields(role('merge'), PrincipalModel.ROLE, { seed: true });++ await Promise.all(+ ['a', 'b'].map((key) =>+ operations.setFields(role('merge'), PrincipalModel.ROLE, { [`fields.${key}`]: key }),+ ),+ );++ const stored = await store.read(role('merge'));+ expect(stored?.overrides).toEqual({ seed: true, fields: { a: 'a', b: 'b' } });+ expect(stored?.configVersion).toBe(3);+ });+ });+ });+}diff --git a/packages/data-schemas/src/app/index.ts b/packages/data-schemas/src/app/index.tsindex bb53ff151c..ba0d00d0c2 100644--- a/packages/data-schemas/src/app/index.ts+++ b/packages/data-schemas/src/app/index.ts@@ -7,3 +7,6 @@ export * from './turnstile';export * from './vertex';export * from './web';export * from './resolution';+export * from './paths';+export * from './mutations';+export * from './store';diff --git a/packages/data-schemas/src/app/mutations.spec.ts b/packages/data-schemas/src/app/mutations.spec.tsnew file mode 100644index 0000000000..0cbe187f05--- /dev/null+++ b/packages/data-schemas/src/app/mutations.spec.ts@@ -0,0 +1,170 @@+import type { ConfigOverrideState } from './mutations';+import {+ setConfigFields,+ unsetConfigPaths,+ toConfigOverrideState,+ tombstoneConfigPaths,+ replaceConfigOverrides,+ isConfigOverrideStateEmpty,+} from './mutations';+import { isConfigPathError, parseFieldPath } from './paths';++function state(overrides: Record<string, unknown>, tombstones: string[] = []): ConfigOverrideState {+ return { overrides, tombstones };+}++const at = (fieldPath: string): string[] => parseFieldPath(fieldPath);++describe('setConfigFields', () => {+ it('applies writes in order and clears the tombstones they write over', () => {+ const input = state({ a: { x: 1 } }, ['memory', 'memory.agent', 'mcpServers.github', 'a.b']);++ const next = setConfigFields(input, [+ { segments: at('a.b'), value: { c: 1 } },+ { segments: at('a.b.c'), value: 2 },+ { segments: at('memory.agent.provider'), value: 'openAI' },+ ]);++ expect(next.overrides).toEqual({+ a: { x: 1, b: { c: 2 } },+ memory: { agent: { provider: 'openAI' } },+ });+ expect(next.tombstones).toEqual(['memory', 'mcpServers.github']);+ expect(input.overrides).toEqual({ a: { x: 1 } });+ });++ it('writes a record whose keys contain dots at its own path', () => {+ const next = setConfigFields(state({}), [+ {+ segments: ['endpoints', 'azureOpenAI', 'groups'],+ value: [{ models: { 'gpt-4.1': true } }],+ },+ ]);++ expect(next.overrides).toEqual({+ endpoints: { azureOpenAI: { groups: [{ models: { 'gpt-4.1': true } }] } },+ });+ });++ it('refuses a write below a stored scalar', () => {+ let caught: unknown;+ try {+ setConfigFields(state({ interface: { modelSelect: true } }), [+ { segments: at('interface.modelSelect.nested'), value: 1 },+ ]);+ } catch (error) {+ caught = error;+ }++ expect(isConfigPathError(caught)).toBe(true);+ });+});++describe('unsetConfigPaths', () => {+ it('prunes parents a reset leaves empty and keeps siblings', () => {+ expect(+ unsetConfigPaths(state({ balance: { startBalance: 5 } }), [at('balance.startBalance')])+ .overrides,+ ).toEqual({});+ expect(+ unsetConfigPaths(state({ balance: { a: 1, b: 2 } }), [at('balance.a')]).overrides,+ ).toEqual({+ balance: { b: 2 },+ });+ expect(+ unsetConfigPaths(+ state({ endpoints: { anthropic: { models: { x: 1 } }, openAI: { a: 1 } } }),+ [at('endpoints.anthropic.models.x')],+ ).overrides,+ ).toEqual({ endpoints: { openAI: { a: 1 } } });+ });++ it('prunes inside an array element without removing or nulling the element', () => {+ const next = unsetConfigPaths(+ state({ endpoints: { custom: [{ name: 'a', headers: { A: '1' } }] } }),+ [at('endpoints.custom.0.headers.A')],+ );++ expect(next.overrides).toEqual({ endpoints: { custom: [{ name: 'a' }] } });+ });++ it('drops tombstones at or below the path and keeps the rest, even under a pruned parent', () => {+ const next = unsetConfigPaths(+ state({ mcpServers: { foo: { title: 'Foo' } } }, [+ 'mcpServers.github',+ 'mcpServers.foo.url',+ 'mcpServers.foo',+ ]),+ [at('mcpServers.foo')],+ );++ expect(next.overrides).toEqual({});+ expect(next.tombstones).toEqual(['mcpServers.github']);+ });++ it('removes a secret and its preview companion together and prunes once', () => {+ const next = unsetConfigPaths(state({ ocr: { apiKey: 'v3:x', apiKeyPreview: '...abcd' } }), [+ at('ocr.apiKey'),+ at('ocr.apiKeyPreview'),+ ]);++ expect(next.overrides).toEqual({});+ });++ it('prunes an emptied atomic theme, so the base theme is inherited again', () => {+ const next = unsetConfigPaths(state({ interface: { theme: { primary: '#000' } } }), [+ at('interface.theme.primary'),+ ]);++ expect(next.overrides).toEqual({});+ });+});++describe('tombstoneConfigPaths', () => {+ it('removes the subtree, prunes, and records each tombstone once', () => {+ const next = tombstoneConfigPaths(+ state({ mcpServers: { github: { title: 'GH' } }, memory: { agent: { id: 'x' } } }, [+ 'memory.agent',+ ]),+ [at('mcpServers.github'), at('memory.agent')],+ );++ expect(next.overrides).toEqual({});+ expect(next.tombstones).toEqual(['memory.agent', 'mcpServers.github']);+ });++ it('refuses a path a tombstone cannot name', () => {+ let caught: unknown;+ try {+ tombstoneConfigPaths(state({}), [['endpoints', 'gpt-4.1']]);+ } catch (error) {+ caught = error;+ }++ expect(isConfigPathError(caught)).toBe(true);+ });+});++describe('replaceConfigOverrides and emptiness', () => {+ it('replaces overrides and keeps tombstones', () => {+ expect(replaceConfigOverrides(state({ a: 1 }, ['x.y']), { b: 2 } as never)).toEqual(+ state({ b: 2 }, ['x.y']),+ );+ });++ it('counts shells-only documents without tombstones as empty', () => {+ expect(isConfigOverrideStateEmpty(state({}))).toBe(true);+ expect(isConfigOverrideStateEmpty(state({ balance: {}, endpoints: { custom: {} } }))).toBe(+ true,+ );+ expect(isConfigOverrideStateEmpty(state({}, ['memory']))).toBe(false);+ expect(isConfigOverrideStateEmpty(state({ balance: { enabled: false } }))).toBe(false);+ });++ it('reads a missing or malformed document as the empty state', () => {+ expect(toConfigOverrideState(null)).toEqual(state({}));+ expect(toConfigOverrideState({ overrides: [], tombstones: ['a', 3] })).toEqual(+ state({}, ['a']),+ );+ });+});diff --git a/packages/data-schemas/src/app/mutations.ts b/packages/data-schemas/src/app/mutations.tsnew file mode 100644index 0000000000..918a125b16--- /dev/null+++ b/packages/data-schemas/src/app/mutations.ts@@ -0,0 +1,135 @@+import type { TCustomConfig } from 'librechat-data-provider';+import type { ConfigPathSegments } from './paths';+import {+ setAtPath,+ unsetAtPath,+ isPlainRecord,+ isEffectivelyEmpty,+ formatTombstonePath,+ pruneEmptyAncestors,+ getClearedTombstones,+ isTombstoneAtOrBelow,+} from './paths';++/**+ * The part of a principal's config document that override mutations change. Every mutation in+ * this module is a pure transform of it: the result is a new state, and the input is untouched.+ * Persisting the result is the store's job, in one compare-and-swap write.+ */+export interface ConfigOverrideState {+ overrides: Partial<TCustomConfig>;+ /** Dotted paths that suppress inherited values during resolution. */+ tombstones: string[];+}++/** One field written by {@link setConfigFields}. */+export interface ConfigFieldWrite {+ segments: ConfigPathSegments;+ value: unknown;+}++type JsonRecord = { [key: string]: unknown };++export const EMPTY_CONFIG_OVERRIDE_STATE: Readonly<ConfigOverrideState> = Object.freeze({+ overrides: {},+ tombstones: [],+});++/** The mutable part of a stored document, or the empty state when there is none. */+export function toConfigOverrideState(+ document?: { overrides?: unknown; tombstones?: unknown } | null,+): ConfigOverrideState {+ const overrides = isPlainRecord(document?.overrides) ? document.overrides : {};+ const tombstones = Array.isArray(document?.tombstones)+ ? document.tombstones.filter((path): path is string => typeof path === 'string')+ : [];+ return { overrides: overrides as Partial<TCustomConfig>, tombstones };+}++function asRecord(overrides: Partial<TCustomConfig>): JsonRecord {+ return overrides as JsonRecord;+}++/**+ * Sets each field in order, then drops the tombstones the writes clear: each written path and+ * its ancestors below the section. A path that continues below a scalar or into a named key of+ * an array throws a `ConfigPathError` instead of replacing what is stored.+ */+export function setConfigFields(+ state: ConfigOverrideState,+ writes: readonly ConfigFieldWrite[],+): ConfigOverrideState {+ let overrides = asRecord(state.overrides);+ const cleared = new Set<string>();+ for (const { segments, value } of writes) {+ overrides = setAtPath(overrides, segments, value);+ for (const path of getClearedTombstones(segments)) {+ cleared.add(path);+ }+ }+ return {+ overrides: overrides as Partial<TCustomConfig>,+ tombstones: state.tombstones.filter((path) => !cleared.has(path)),+ };+}++/** Removes each path, then the objects the removals left empty. */+function removePaths(overrides: JsonRecord, paths: readonly ConfigPathSegments[]): JsonRecord {+ const removed = paths.reduce((current, segments) => unsetAtPath(current, segments), overrides);+ return paths.reduce((current, segments) => pruneEmptyAncestors(current, segments), removed);+}++/**+ * Removes each path and prunes the objects the removals left empty, so a reset leaves no `{}`+ * shells behind (sibling values and array elements are never removed). Tombstones at or below+ * each path are dropped too, and tombstones elsewhere, including under a pruned ancestor, stay.+ */+export function unsetConfigPaths(+ state: ConfigOverrideState,+ paths: readonly ConfigPathSegments[],+): ConfigOverrideState {+ return {+ overrides: removePaths(asRecord(state.overrides), paths) as Partial<TCustomConfig>,+ tombstones: state.tombstones.filter(+ (tombstone) => !paths.some((segments) => isTombstoneAtOrBelow(tombstone, segments)),+ ),+ };+}++/**+ * Suppresses each path: its override is removed (with the emptied ancestors, as in+ * {@link unsetConfigPaths}) and the path is recorded as a tombstone once. A segment that+ * contains a dot cannot be named by a tombstone and throws a `ConfigPathError`.+ */+export function tombstoneConfigPaths(+ state: ConfigOverrideState,+ paths: readonly ConfigPathSegments[],+): ConfigOverrideState {+ const added = paths.map(formatTombstonePath);+ const tombstones = [...state.tombstones];+ for (const path of added) {+ if (!tombstones.includes(path)) {+ tombstones.push(path);+ }+ }+ return {+ overrides: removePaths(asRecord(state.overrides), paths) as Partial<TCustomConfig>,+ tombstones,+ };+}++/** Replaces the overrides whole. Tombstones stay, so they keep shaping the inherited base. */+export function replaceConfigOverrides(+ state: ConfigOverrideState,+ overrides: Partial<TCustomConfig>,+): ConfigOverrideState {+ return { overrides, tombstones: [...state.tombstones] };+}++/**+ * Whether a document holds nothing: no tombstones, and overrides that are empty or hold only+ * empty objects (shells an older server's field reset left behind).+ */+export function isConfigOverrideStateEmpty(state: ConfigOverrideState): boolean {+ return state.tombstones.length === 0 && isEffectivelyEmpty(state.overrides);+}diff --git a/packages/data-schemas/src/app/paths.spec.ts b/packages/data-schemas/src/app/paths.spec.tsnew file mode 100644index 0000000000..1c0032bb63--- /dev/null+++ b/packages/data-schemas/src/app/paths.spec.ts@@ -0,0 +1,224 @@+import {+ getAtPath,+ setAtPath,+ unsetAtPath,+ parseFieldPath,+ isDotFreePath,+ isConfigPathError,+ isSegmentPrefix,+ isEffectivelyEmpty,+ formatTombstonePath,+ pruneEmptyAncestors,+ getClearedTombstones,+ isTombstoneAtOrBelow,+ MAX_CONFIG_PATH_DEPTH,+ parseConfigPathSegments,+ getTombstonePathsToClear,+} from './paths';++function reasonOf(fn: () => unknown): string | undefined {+ try {+ fn();+ } catch (error) {+ return isConfigPathError(error) ? error.reason : 'unexpected';+ }+ return undefined;+}++describe('setAtPath', () => {+ it('creates missing objects and leaves the input untouched', () => {+ const root = { a: { keep: 1 } };++ const next = setAtPath(root, ['a', 'b', 'c'], 2);++ expect(next).toEqual({ a: { keep: 1, b: { c: 2 } } });+ expect(root).toEqual({ a: { keep: 1 } });+ });++ it('treats a dotted key as one segment', () => {+ const next = setAtPath(+ {},+ ['endpoints', 'bedrock', 'inferenceProfiles', 'us.anthropic.x'],+ 'arn',+ );++ expect(next).toEqual({+ endpoints: { bedrock: { inferenceProfiles: { 'us.anthropic.x': 'arn' } } },+ });+ });++ it('replaces or appends array elements by index', () => {+ expect(setAtPath({ list: ['a'] }, ['list', '0'], 'b')).toEqual({ list: ['b'] });+ expect(setAtPath({ list: ['a'] }, ['list', '1'], 'b')).toEqual({ list: ['a', 'b'] });+ expect(setAtPath({ list: [{ x: 1 }] }, ['list', '0', 'y'], 2)).toEqual({+ list: [{ x: 1, y: 2 }],+ });+ });++ it('refuses an index past the end of an array instead of padding it', () => {+ const root = { list: ['a'] };++ expect(reasonOf(() => setAtPath(root, ['list', '2'], 'c'))).toBe('array_index');+ expect(reasonOf(() => setAtPath(root, ['list', '2', 'x'], 1))).toBe('array_index');+ expect(reasonOf(() => setAtPath({ list: [] }, ['list', '10000000'], 'x'))).toBe('array_index');+ expect(reasonOf(() => setAtPath(root, ['list', '9'.repeat(400)], 'x'))).toBe('array_index');+ expect(root).toEqual({ list: ['a'] });+ });++ it('treats a numeric segment below an object or a missing key as a record key', () => {+ expect(setAtPath({ map: {} }, ['map', '10000000'], 1)).toEqual({ map: { '10000000': 1 } });+ expect(setAtPath({}, ['map', '10000000'], 1)).toEqual({ map: { '10000000': 1 } });+ });++ it('refuses to continue below a scalar or null instead of replacing it', () => {+ expect(reasonOf(() => setAtPath({ a: 5 }, ['a', 'b'], 1))).toBe('scalar_parent');+ expect(reasonOf(() => setAtPath({ a: null }, ['a', 'b'], 1))).toBe('scalar_parent');+ });++ it('refuses a named key inside an array and an empty path or segment', () => {+ expect(reasonOf(() => setAtPath({ list: [] }, ['list', 'name'], 1))).toBe('array_key');+ expect(reasonOf(() => setAtPath({}, [], 1))).toBe('empty_path');+ expect(reasonOf(() => setAtPath({}, ['a', ''], 1))).toBe('empty_path');+ });++ it('stores a `__proto__` segment as an own key without touching any prototype', () => {+ const next = setAtPath({}, ['headers', '__proto__'], { polluted: true });++ expect(Object.prototype.hasOwnProperty.call(next.headers, '__proto__')).toBe(true);+ expect(({} as { polluted?: boolean }).polluted).toBeUndefined();+ });+});++describe('unsetAtPath', () => {+ it('removes a key and copies only the path it changes', () => {+ const sibling = { untouched: true };+ const root = { a: { b: 1, c: 2 }, sibling };++ const next = unsetAtPath(root, ['a', 'b']);++ expect(next).toEqual({ a: { c: 2 }, sibling });+ expect(next.sibling).toBe(sibling);+ expect(root.a).toEqual({ b: 1, c: 2 });+ });++ it('returns the input for a missing path', () => {+ const root = { a: { b: 1 } };++ expect(unsetAtPath(root, ['a', 'x', 'y'])).toBe(root);+ expect(unsetAtPath(root, ['a', 'b', 'c'])).toBe(root);+ });++ it('removes inside array elements but refuses to remove an element itself', () => {+ const root = { custom: [{ name: 'a', headers: { A: '1', B: '2' } }] };++ expect(unsetAtPath(root, ['custom', '0', 'headers', 'A'])).toEqual({+ custom: [{ name: 'a', headers: { B: '2' } }],+ });+ expect(reasonOf(() => unsetAtPath(root, ['custom', '0']))).toBe('array_element');+ expect(unsetAtPath(root, ['custom', '5'])).toBe(root);+ });+});++describe('pruneEmptyAncestors', () => {+ it('removes the chain of emptied objects up to the section', () => {+ expect(pruneEmptyAncestors({ balance: {} }, ['balance', 'startBalance'])).toEqual({});+ expect(pruneEmptyAncestors({ a: { b: { c: {} } } }, ['a', 'b', 'c', 'd'])).toEqual({});+ });++ it('stops at the first ancestor that still holds a value', () => {+ expect(pruneEmptyAncestors({ a: { b: {}, keep: 1 } }, ['a', 'b', 'c'])).toEqual({+ a: { keep: 1 },+ });+ });++ it('never removes an array element', () => {+ expect(+ pruneEmptyAncestors({ custom: [{ headers: {} }] }, ['custom', '0', 'headers', 'A']),+ ).toEqual({ custom: [{}] });+ expect(pruneEmptyAncestors({ custom: [{}] }, ['custom', '0', 'x'])).toEqual({ custom: [{}] });+ });+});++describe('tombstone addressing', () => {+ it('formats dot-free segments and refuses a dotted one', () => {+ expect(formatTombstonePath(['mcpServers', 'github'])).toBe('mcpServers.github');+ expect(reasonOf(() => formatTombstonePath(['endpoints', 'gpt-4.1']))).toBe('dotted_segment');+ });++ it('clears the written path and its ancestors below the section', () => {+ expect(getTombstonePathsToClear('memory')).toEqual(['memory']);+ expect(getTombstonePathsToClear('memory.agent.provider')).toEqual([+ 'memory.agent',+ 'memory.agent.provider',+ ]);+ });++ it('clears only the dot-free prefix of a path with a dotted segment', () => {+ expect(+ getClearedTombstones(['endpoints', 'azureOpenAI', 'models', 'gpt-4.1', 'deploymentName']),+ ).toEqual(['endpoints.azureOpenAI', 'endpoints.azureOpenAI.models']);+ });++ it('matches tombstones at or below a path segment by segment', () => {+ expect(isTombstoneAtOrBelow('mcpServers.github', ['mcpServers'])).toBe(true);+ expect(isTombstoneAtOrBelow('mcpServers.github', ['mcpServers', 'github'])).toBe(true);+ expect(isTombstoneAtOrBelow('mcpServers.githubber', ['mcpServers', 'github'])).toBe(false);+ expect(isTombstoneAtOrBelow('a.b.c', ['a', 'b.c'])).toBe(false);+ expect(isSegmentPrefix(['a'], ['a', 'b'])).toBe(true);+ expect(isSegmentPrefix(['a', 'b'], ['a'])).toBe(false);+ });+});++describe('getAtPath and isEffectivelyEmpty', () => {+ it('reads own keys only', () => {+ expect(getAtPath({ a: [{ 'b.c': 1 }] }, ['a', '0', 'b.c'])).toBe(1);+ expect(getAtPath({}, ['toString'])).toBeUndefined();+ expect(getAtPath({ a: 1 }, parseFieldPath('a.b'))).toBeUndefined();+ });++ it('treats objects holding only empty objects as empty', () => {+ expect(isEffectivelyEmpty({})).toBe(true);+ expect(isEffectivelyEmpty({ a: {}, b: { c: {} } })).toBe(true);+ expect(isEffectivelyEmpty({ a: { b: false } })).toBe(false);+ expect(isEffectivelyEmpty({ a: [] })).toBe(false);+ });+});++describe('client segment paths', () => {+ it('accepts keys that contain dots or `$` past the first character, as one segment each', () => {+ const segments = [+ 'endpoints',+ 'bedrock',+ 'inferenceProfiles',+ 'us.anthropic.claude-sonnet-4-5',+ ];+ const parsed = parseConfigPathSegments(segments);++ expect(parsed).toEqual({ ok: true, segments });+ expect(parsed.ok && parsed.segments).not.toBe(segments);+ expect(parseConfigPathSegments(['addParams', 'price$'])).toEqual({+ ok: true,+ segments: ['addParams', 'price$'],+ });+ expect(isDotFreePath(segments)).toBe(false);+ expect(isDotFreePath(['interface', 'customWelcome'])).toBe(true);+ });++ it.each([+ ['not an array', 'interface.customWelcome', 'empty_path'],+ ['an empty list', [], 'empty_path'],+ ['an empty segment', ['interface', ''], 'empty_path'],+ ['a non-string segment', ['endpoints', 'custom', 0], 'empty_path'],+ ['a `$` key', ['interface', '$set'], 'unsafe_segment'],+ ['`__proto__`', ['__proto__', 'polluted'], 'unsafe_segment'],+ ['`constructor`', ['interface', 'constructor'], 'unsafe_segment'],+ ['`prototype`', ['prototype'], 'unsafe_segment'],+ ['a path deeper than the limit', Array(MAX_CONFIG_PATH_DEPTH + 1).fill('a'), 'too_deep'],+ ])('refuses %s', (_label, value, reason) => {+ expect(parseConfigPathSegments(value)).toEqual({ ok: false, reason });+ });++ it('accepts a path exactly at the depth limit', () => {+ expect(parseConfigPathSegments(Array(MAX_CONFIG_PATH_DEPTH).fill('a')).ok).toBe(true);+ });+});diff --git a/packages/data-schemas/src/app/paths.ts b/packages/data-schemas/src/app/paths.tsnew file mode 100644index 0000000000..7bdbd266eb--- /dev/null+++ b/packages/data-schemas/src/app/paths.ts@@ -0,0 +1,304 @@+/**+ * Segment addressing inside a config overrides document.+ *+ * A path is a list of keys, so a record key that contains a dot is still one segment. A dotted+ * `fieldPath` is an edge format: `parseFieldPath` splits it, which is lossless only when no key+ * on the path contains a dot. Tombstones are stored as dotted strings, so they can only name+ * paths whose segments contain no dots.+ *+ * Every helper is pure: it never mutates its input and copies only the containers along the+ * path it changes.+ */++export type ConfigPathSegments = readonly string[];++type JsonRecord = { [key: string]: unknown };++/** Why a path cannot be applied to the document it was addressed against. */+export type ConfigPathErrorReason =+ /** The path has no segments, or a segment is empty. */+ | 'empty_path'+ /** The path continues below a value that is neither an object nor an array. */+ | 'scalar_parent'+ /** The path names a key inside an array; arrays are addressed by index only. */+ | 'array_key'+ /** The path names an array index past the end; a write may only replace or append one. */+ | 'array_index'+ /** The path ends on an array element, which a removal would leave as `null`. */+ | 'array_element'+ /** A tombstone (or another dotted-path consumer) would have to split a segment with a dot. */+ | 'dotted_segment'+ /** A segment starts with `$` or names a reserved key (`__*`, `constructor`, `prototype`). */+ | 'unsafe_segment'+ /** The path is longer than {@link MAX_CONFIG_PATH_DEPTH} segments. */+ | 'too_deep';++/** The deepest path a client may address; config schemas nest far less than this. */+export const MAX_CONFIG_PATH_DEPTH = 32;++const UNSAFE_SEGMENT = /^(?:\$|__)|^(?:constructor|prototype)$/;++/**+ * A path that cannot be applied to the document as stored. The message never echoes the path,+ * which can carry submitted keys; callers that report it use `code` and `reason`.+ */+export class ConfigPathError extends Error {+ readonly code = 'CONFIG_PATH_INVALID';++ constructor(+ readonly segments: string[],+ readonly reason: ConfigPathErrorReason,+ ) {+ super(`Config path cannot be applied: ${reason}`);+ this.name = 'ConfigPathError';+ }+}++export function isConfigPathError(error: unknown): error is ConfigPathError {+ return (+ error instanceof ConfigPathError ||+ (error instanceof Error && (error as { code?: unknown }).code === 'CONFIG_PATH_INVALID')+ );+}++export function isPlainRecord(value: unknown): value is JsonRecord {+ return value != null && typeof value === 'object' && !Array.isArray(value);+}++function hasOwn(target: JsonRecord, key: string): boolean {+ return Object.prototype.hasOwnProperty.call(target, key);+}++function isArrayIndex(segment: string): boolean {+ return /^(?:0|[1-9]\d*)$/.test(segment);+}++function assertSegments(segments: ConfigPathSegments): void {+ if (segments.length === 0 || segments.some((segment) => segment === '')) {+ throw new ConfigPathError([...segments], 'empty_path');+ }+}++/** Splits a dotted field path into segments. Lossless only for keys that contain no dot. */+export function parseFieldPath(fieldPath: string): string[] {+ return fieldPath.split('.');+}++/**+ * Validates a client-supplied segment path: 1 to {@link MAX_CONFIG_PATH_DEPTH} non-empty+ * strings, none starting with `$` or naming a reserved key. A segment may contain dots, which+ * is what segments are for: addressing a record key such as `us.anthropic.claude-sonnet-4-5`.+ */+export function parseConfigPathSegments(+ value: unknown,+): { ok: true; segments: string[] } | { ok: false; reason: ConfigPathErrorReason } {+ if (!Array.isArray(value) || value.length === 0) {+ return { ok: false, reason: 'empty_path' };+ }+ if (value.length > MAX_CONFIG_PATH_DEPTH) {+ return { ok: false, reason: 'too_deep' };+ }+ for (const segment of value) {+ if (typeof segment !== 'string' || segment === '') {+ return { ok: false, reason: 'empty_path' };+ }+ if (UNSAFE_SEGMENT.test(segment)) {+ return { ok: false, reason: 'unsafe_segment' };+ }+ }+ return { ok: true, segments: [...(value as string[])] };+}++/** Whether a segment path can be written as a dotted field path without losing a key. */+export function isDotFreePath(segments: ConfigPathSegments): boolean {+ return segments.every((segment) => !segment.includes('.'));+}++/** Joins segments into the dotted form tombstones are stored in. */+export function formatTombstonePath(segments: ConfigPathSegments): string {+ assertSegments(segments);+ if (!isDotFreePath(segments)) {+ throw new ConfigPathError([...segments], 'dotted_segment');+ }+ return segments.join('.');+}++/** Whether `prefix` addresses `segments` itself or one of its ancestors. */+export function isSegmentPrefix(prefix: ConfigPathSegments, segments: ConfigPathSegments): boolean {+ return (+ prefix.length <= segments.length &&+ prefix.every((segment, index) => segment === segments[index])+ );+}++/** Whether a stored tombstone names `segments` itself or a path below it. */+export function isTombstoneAtOrBelow(tombstone: string, segments: ConfigPathSegments): boolean {+ return isSegmentPrefix(segments, parseFieldPath(tombstone));+}++export function getAtPath(root: unknown, segments: ConfigPathSegments): unknown {+ let current = root;+ for (const segment of segments) {+ if (Array.isArray(current) && isArrayIndex(segment)) {+ current = current[Number(segment)];+ } else if (isPlainRecord(current) && hasOwn(current, segment)) {+ current = current[segment];+ } else {+ return undefined;+ }+ }+ return current;+}++function setInto(+ container: unknown,+ segments: ConfigPathSegments,+ depth: number,+ value: unknown,+): unknown {+ if (depth === segments.length) {+ return value;+ }+ const segment = segments[depth];+ if (Array.isArray(container)) {+ if (!isArrayIndex(segment)) {+ throw new ConfigPathError(segments.slice(0, depth + 1), 'array_key');+ }+ const index = Number(segment);+ if (index > container.length) {+ throw new ConfigPathError(segments.slice(0, depth + 1), 'array_index');+ }+ const next: unknown[] = [...container];+ next[index] = setInto(next[index], segments, depth + 1, value);+ return next;+ }+ if (container !== undefined && !isPlainRecord(container)) {+ throw new ConfigPathError(segments.slice(0, depth), 'scalar_parent');+ }+ const next: JsonRecord = { ...(container ?? {}) };+ const child = hasOwn(next, segment) ? next[segment] : undefined;+ /** Defined rather than assigned, so a `__proto__` key stays data instead of a prototype. */+ Object.defineProperty(next, segment, {+ value: setInto(child, segments, depth + 1, value),+ enumerable: true,+ writable: true,+ configurable: true,+ });+ return next;+}++/**+ * Sets `value` at `segments` the way a document store's field set does: missing objects on the+ * way are created and array elements are addressed by index. A path that continues below a+ * scalar, `null`, or a named key of an array is refused instead of silently replacing what is+ * there, and so is an index past the end of an array: an element can be replaced or appended,+ * never reached by padding the array with `null`, so the size of a write is bounded by the+ * document it lands on rather than by a number in the path.+ */+export function setAtPath(+ root: JsonRecord,+ segments: ConfigPathSegments,+ value: unknown,+): JsonRecord {+ assertSegments(segments);+ return setInto(root, segments, 0, value) as JsonRecord;+}++function removeFrom(container: unknown, segments: ConfigPathSegments, depth: number): unknown {+ const segment = segments[depth];+ const isLast = depth === segments.length - 1;+ if (Array.isArray(container)) {+ if (!isArrayIndex(segment) || Number(segment) >= container.length) {+ return container;+ }+ if (isLast) {+ throw new ConfigPathError([...segments], 'array_element');+ }+ const index = Number(segment);+ const child = removeFrom(container[index], segments, depth + 1);+ if (child === container[index]) {+ return container;+ }+ const next = [...container];+ next[index] = child;+ return next;+ }+ if (!isPlainRecord(container) || !hasOwn(container, segment)) {+ return container;+ }+ if (isLast) {+ const next = { ...container };+ delete next[segment];+ return next;+ }+ const child = removeFrom(container[segment], segments, depth + 1);+ if (child === container[segment]) {+ return container;+ }+ return { ...container, [segment]: child };+}++/**+ * Removes the value at `segments`. A missing path is a no-op (the input is returned as is). A+ * path ending on an existing array element is refused: removing it would either shift the+ * elements after it or leave a `null` hole, and arrays are written whole.+ */+export function unsetAtPath(root: JsonRecord, segments: ConfigPathSegments): JsonRecord {+ assertSegments(segments);+ return removeFrom(root, segments, 0) as JsonRecord;+}++function isEmptyRecord(value: unknown): boolean {+ return isPlainRecord(value) && Object.keys(value).length === 0;+}++/**+ * Removes the objects on the way to `segments` that hold nothing, deepest first, so a removed+ * leaf does not leave `{}` shells behind. It stops at the first ancestor that still holds a+ * value, at an array (an element is never removed), and at the document root, which stays.+ */+export function pruneEmptyAncestors(root: JsonRecord, segments: ConfigPathSegments): JsonRecord {+ let result = root;+ for (let depth = segments.length - 1; depth >= 1; depth--) {+ const ancestor = segments.slice(0, depth);+ if (!isEmptyRecord(getAtPath(result, ancestor))) {+ break;+ }+ if (!isPlainRecord(getAtPath(result, ancestor.slice(0, -1)))) {+ break;+ }+ result = removeFrom(result, ancestor, 0) as JsonRecord;+ }+ return result;+}++/** Whether `value` is an object that holds only objects that hold nothing (`{}`, `{ a: {} }`). */+export function isEffectivelyEmpty(value: unknown): boolean {+ return isPlainRecord(value) && Object.values(value).every(isEffectivelyEmpty);+}++/**+ * The stored tombstones a field write at `segments` clears: the written path and its ancestors+ * below the section, so a whole-section tombstone survives a nested write. Only the dot-free+ * prefix of the path can match a tombstone.+ */+export function getClearedTombstones(segments: ConfigPathSegments): string[] {+ const dotted = segments.findIndex((segment) => segment.includes('.'));+ const addressable = dotted === -1 ? segments : segments.slice(0, dotted);+ if (addressable.length === 0) {+ return [];+ }+ if (segments.length === 1) {+ return [addressable[0]];+ }+ const paths: string[] = [];+ for (let length = 2; length <= addressable.length; length++) {+ paths.push(addressable.slice(0, length).join('.'));+ }+ return paths;+}++/** {@link getClearedTombstones} for a dotted field path. */+export function getTombstonePathsToClear(fieldPath: string): string[] {+ return getClearedTombstones(parseFieldPath(fieldPath));+}diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.tsindex 73cffd4e63..0eca4e8a61 100644--- a/packages/data-schemas/src/app/resolution.spec.ts+++ b/packages/data-schemas/src/app/resolution.spec.ts@@ -1771,6 +1771,20 @@ describe('getConfigFieldIssues', () => {).toEqual(['registration.oauthStateTtlMs']);});+ it('checks segment writes, which address keys that contain dots', () => {+ const profile = ['endpoints', 'bedrock', 'inferenceProfiles', 'us.anthropic.claude-sonnet-4-5'];+ const stored = {+ overrides: { endpoints: { bedrock: { inferenceProfiles: { 'eu.x': 'a' } } } },+ };++ expect(getConfigFieldIssues([{ segments: profile, value: 'arn:aws:x' }], {}, stored)).toEqual(+ [],+ );+ expect(getConfigFieldIssues([{ segments: profile, value: 5 }], {}, stored)).toEqual([+ expect.objectContaining({ segments: profile }),+ ]);+ });+it('applies a record refinement to a single written key', () => {const base = {endpoints: {@@ -1889,6 +1903,26 @@ describe('getConfigFieldIssues', () => {expect(getConfigFieldIssues({ 'registration.unknownField.foo': 1 })).toEqual([]);});+ it('refuses an index past the end of a stored array before building anything', () => {+ const stored = { overrides: { endpoints: { agents: { capabilities: ['tools'] } } } };+ const started = performance.now();++ expect(() =>+ getConfigFieldIssues({ 'endpoints.agents.capabilities.10000000': 'tools' }, {}, stored),+ ).toThrow(expect.objectContaining({ code: 'CONFIG_PATH_INVALID', reason: 'array_index' }));+ expect(() =>+ getConfigFieldIssues(+ [{ segments: ['endpoints', 'agents', 'capabilities', '1'.repeat(400)], value: 'x' }],+ {},+ stored,+ ),+ ).toThrow(expect.objectContaining({ reason: 'array_index' }));+ expect(performance.now() - started).toBeLessThan(1000);+ expect(+ getConfigFieldIssues({ 'endpoints.agents.capabilities.1': 'actions' }, {}, stored),+ ).toEqual([]);+ });+it('rejects an indexed write into a merged-by-name array', () => {expect(getConfigFieldIssues({ 'endpoints.custom.0.models': { default: ['m'] } }).map(diff --git a/packages/data-schemas/src/app/resolution.ts b/packages/data-schemas/src/app/resolution.tsindex b0a2f426da..14f0525ab9 100644--- a/packages/data-schemas/src/app/resolution.ts+++ b/packages/data-schemas/src/app/resolution.ts@@ -9,14 +9,22 @@ import {configSchema,} from 'librechat-data-provider';import type { TCustomConfig } from 'librechat-data-provider';-import type { AdminConfigMergeRules, AppConfig, IConfig, TWebSearchKeys } from '~/types';+import type { AdminConfigMergeRules, AppConfig, Config, TWebSearchKeys } from '~/types';+import type { ConfigFieldWrite } from './mutations';+import { setConfigFields, toConfigOverrideState } from './mutations';import { webSearchPairedFields, unbindWebSearchKeys } from './web';import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';-import { getTombstonePathsToClear } from '~/methods/config';+import { parseFieldPath } from './paths';import logger from '~/config/winston';type AnyObject = { [key: string]: unknown };+/** The parts of a principal's config document the merge reads, whichever store returned it. */+export type ConfigOverrideLayer = Pick<Config, 'principalType' | 'priority' | 'overrides'> & {+ principalId: { toString(): string };+ tombstones?: readonly unknown[];+};+const MAX_MERGE_DEPTH = 10;const MAX_STRIP_PASSES = 16;const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);@@ -673,7 +681,7 @@ export function getConfigOverrideIssues(return issues;}-/** Sets a dot-path the way a Mongo `$set` on `overrides.<path>` does, without mutating. */+/** Sets a path without mutating, replacing whatever is in the way. */function setPath(target: unknown, segments: string[], value: unknown): unknown {if (segments.length === 0) {return value;@@ -709,26 +717,28 @@ export function applyConfigTombstones(}/**- * Checks dot-path field writes on top of the principal's stored config, building the- * result the way `patchConfigFields` stores it: a Mongo `$set` on each `overrides.<path>`,- * clearing the tombstones those paths clear. The principal's remaining tombstones are- * applied to the base. An issue is reported when it touches a written path, or when the- * write introduced it elsewhere (a related field the write made invalid); issues the stored- * config already had are left to merge time so they do not block an unrelated write.+ * Checks field writes on top of the principal's stored config, building the result with the+ * same transform the write stores (`setConfigFields`): each path set in order, and the+ * tombstones those paths clear removed. `fields` is either a map of dotted field paths or a+ * list of segment writes (which can address keys that contain dots). A path the stored+ * document cannot take (below a scalar, or a named key of an array) throws a+ * `ConfigPathError`. The principal's remaining tombstones are applied to the base. An issue is+ * reported when it touches a written path, or when the write introduced it elsewhere (a+ * related field the write made invalid); issues the stored config already had are left to+ * merge time so they do not block an unrelated write.*/export function getConfigFieldIssues(- fields: Record<string, unknown>,+ fields: Record<string, unknown> | readonly ConfigFieldWrite[],base: Partial<TCustomConfig> = {},stored?: { overrides?: unknown; tombstones?: unknown[] } | null,): ConfigOverrideIssue[] {- const written = Object.keys(fields).map((fieldPath) => fieldPath.split('.'));- const cleared = new Set(Object.keys(fields).flatMap(getTombstonePathsToClear));- const effectiveBase = applyConfigTombstones(base, stored?.tombstones, cleared);- const storedOverrides = isPlainObject(stored?.overrides) ? stored.overrides : {};- const candidate = Object.entries(fields).reduce<unknown>(- (current, [fieldPath, value]) => setPath(current, fieldPath.split('.'), value),- storedOverrides,- );+ const writes: readonly ConfigFieldWrite[] = Array.isArray(fields)+ ? fields+ : Object.entries(fields).map(([fieldPath, value]) => ({+ segments: parseFieldPath(fieldPath),+ value,+ }));+ const written = writes.map(({ segments }) => [...segments]);/*** An item of a merged-by-key array is identified by its key, not its position: an indexed* write can rename the stored item, which the runtime merge then treats as a new one.@@ -745,10 +755,14 @@ export function getConfigFieldIssues(if (indexed.length > 0) {return indexed;}+ const storedState = toConfigOverrideState(stored);+ const candidate = setConfigFields(storedState, writes);+ const effectiveBase = applyConfigTombstones(base, candidate.tombstones);+ const storedOverrides = storedState.overrides;const existing = new Set(getConfigOverrideIssues(storedOverrides, effectiveBase).map((issue) => issue.path),);- return getConfigOverrideIssues(candidate, effectiveBase).filter(+ return getConfigOverrideIssues(candidate.overrides, effectiveBase).filter((issue) =>!existing.has(issue.path) ||written.some((segments) => isRelatedPath(issue.segments, segments)),@@ -791,7 +805,10 @@ function omitPath(target: unknown, segments: string[]): unknown {* fails once layered over other overrides) leaves the value beneath it in place. A layer* is not judged on what it leaves out, since a higher-priority layer may supply it.*/-function stripInvalidOverrides(config: IConfig, base: Partial<TCustomConfig>): AnyObject {+function stripInvalidOverrides(+ config: ConfigOverrideLayer,+ base: Partial<TCustomConfig>,+): AnyObject {const principal = `${config.principalType}/${config.principalId}`;let stripped: unknown = config.overrides;/**@@ -869,7 +886,7 @@ function filterMCPServerOverrides(value: unknown, current: unknown): AnyObject {/** The override document that last set or removed a paired web search field, and its merge position. */interface WebSearchWriter {- config: IConfig;+ config: ConfigOverrideLayer;order: number;removed: boolean;}@@ -952,7 +969,10 @@ function bindWebSearchKeys(merged: AppConfig, writers: WebSearchWriters): AppCon* A stored web search key is dropped when a layer other than its own decides* the URL it is sent to.*/-export function mergeConfigOverrides(baseConfig: AppConfig, configs: IConfig[]): AppConfig {+export function mergeConfigOverrides(+ baseConfig: AppConfig,+ configs: readonly ConfigOverrideLayer[],+): AppConfig {if (!configs || configs.length === 0) {return baseConfig;}diff --git a/packages/data-schemas/src/app/store.spec.ts b/packages/data-schemas/src/app/store.spec.tsnew file mode 100644index 0000000000..97ca91f3b0--- /dev/null+++ b/packages/data-schemas/src/app/store.spec.ts@@ -0,0 +1,118 @@+import { PrincipalType, PrincipalModel } from 'librechat-data-provider';+import type { ConfigDraft, ConfigRecord, ConfigMutationIO } from './store';+import {+ runConfigMutation,+ getConfigRevision,+ getConfigRetryDelay,+ CONFIG_WRITE_ATTEMPTS,+ ABSENT_CONFIG_REVISION,+ isConfigRevisionConflict,+ ConfigRevisionConflictError,+} from './store';++const draft: ConfigDraft = {+ principalModel: PrincipalModel.ROLE,+ priority: 10,+ overrides: {},+ tombstones: [],+ isActive: true,+};++function toRecord(next: ConfigDraft, configVersion: number): ConfigRecord {+ return {+ ...next,+ _id: 'doc',+ principalType: PrincipalType.ROLE,+ principalId: 'editor',+ configVersion,+ };+}++/**+ * One document behind the {@link ConfigMutationIO} contract. The first `losses` writes find+ * that another writer got there first (the stored version moves on), as a concurrent admin+ * would cause; every read and write is timestamped.+ */+function createContendedDocument(losses: number) {+ let stored: ConfigRecord | null = null;+ let remaining = losses;+ const reads: number[] = [];+ const conflicts: number[] = [];+ const io: ConfigMutationIO = {+ async read() {+ reads.push(performance.now());+ return stored;+ },+ async write(next, expected) {+ if (remaining > 0) {+ remaining -= 1;+ stored = toRecord(draft, (stored?.configVersion ?? 0) + 1);+ conflicts.push(performance.now());+ throw new ConfigRevisionConflictError(getConfigRevision(stored));+ }+ const current = stored ? getConfigRevision(stored) : ABSENT_CONFIG_REVISION;+ if (expected !== current) {+ throw new ConfigRevisionConflictError(stored ? current : null);+ }+ stored = toRecord(next, (stored?.configVersion ?? 0) + 1);+ return stored;+ },+ };+ return { io, reads, conflicts };+}++describe('getConfigRetryDelay', () => {+ it.each([+ [1, 10, 20],+ [2, 20, 40],+ [3, 40, 80],+ [4, 80, 160],+ [5, 100, 200],+ [12, 100, 200],+ ])('pauses retry %i between %i and %i ms', (attempt, low, high) => {+ expect(getConfigRetryDelay(attempt, () => 0)).toBe(low);+ expect(getConfigRetryDelay(attempt, () => 1)).toBe(high);+ const sampled = getConfigRetryDelay(attempt);+ expect(sampled).toBeGreaterThanOrEqual(low);+ expect(sampled).toBeLessThanOrEqual(high);+ });++ it('spreads writers that lost the same race', () => {+ const delays = new Set(Array.from({ length: 50 }, () => getConfigRetryDelay(1)));++ expect(delays.size).toBeGreaterThan(1);+ });+});++describe('runConfigMutation retries', () => {+ it('pauses before re-reading after a lost race, then writes on the fresh revision', async () => {+ const { io, reads, conflicts } = createContendedDocument(1);++ const outcome = await runConfigMutation(io, () => ({ draft }));++ expect(outcome.written).toBe(true);+ expect(reads).toHaveLength(2);+ expect(reads[1] - conflicts[0]).toBeGreaterThanOrEqual(9);+ expect(outcome.written && outcome.record.configVersion).toBe(2);+ });++ it('gives up with a conflict once every attempt has lost', async () => {+ const { io, reads } = createContendedDocument(CONFIG_WRITE_ATTEMPTS);++ const error = await runConfigMutation(io, () => ({ draft })).catch((caught) => caught);++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(reads).toHaveLength(CONFIG_WRITE_ATTEMPTS);+ });++ it('does not retry a write conditioned on a client revision', async () => {+ const { io, reads } = createContendedDocument(1);++ const error = await runConfigMutation(io, () => ({ draft }), {+ expectedRevision: ABSENT_CONFIG_REVISION,+ }).catch((caught) => caught);++ expect(isConfigRevisionConflict(error)).toBe(true);+ expect(reads).toHaveLength(1);+ });+});diff --git a/packages/data-schemas/src/app/store.ts b/packages/data-schemas/src/app/store.tsnew file mode 100644index 0000000000..2c1e3b0826--- /dev/null+++ b/packages/data-schemas/src/app/store.ts@@ -0,0 +1,561 @@+import { PrincipalType } from 'librechat-data-provider';+import type { PrincipalModel, TCustomConfig } from 'librechat-data-provider';+import type { ConfigOverrideState } from './mutations';+import type { ConfigPathSegments } from './paths';+import {+ setConfigFields,+ unsetConfigPaths,+ toConfigOverrideState,+ tombstoneConfigPaths,+ replaceConfigOverrides,+ isConfigOverrideStateEmpty,+} from './mutations';+import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';+import { parseFieldPath } from './paths';++/**+ * The portable admin-config store contract.+ *+ * Override documents are plain JSON: record keys may contain `.` or start with `$`, and no+ * engine-specific operator appears in the override semantics. An engine stores and returns+ * documents verbatim (any key encoding is the engine's own business), and every write is a+ * whole-document compare-and-swap against a revision. Mutations are pure transforms+ * (`./mutations`) applied between a read and that write, so a second engine (PostgreSQL/JSONB)+ * implements five operations and inherits the rest.+ *+ * `./conformance` is the suite an engine must pass.+ */++/** Precondition meaning "the principal must not have a document yet" (create-only). */+export const ABSENT_CONFIG_REVISION = 'absent';++/** Priority a principal's document gets when a write creates it without one. */+export const DEFAULT_CONFIG_PRIORITY = 10;++/** How many times a write without a client precondition re-reads and retries on a conflict. */+export const CONFIG_WRITE_ATTEMPTS = 3;++/** The longest pause before the first retry; it doubles for each later one. */+const CONFIG_RETRY_BASE_DELAY_MS = 20;++/** The longest pause before any retry. */+const CONFIG_RETRY_MAX_DELAY_MS = 200;++/** `<document id>:<configVersion>`, or {@link ABSENT_CONFIG_REVISION}. */+export type ConfigRevision = string;++const REVISION_PATTERN = /^([A-Za-z0-9_-]{1,64}):(0|[1-9]\d{0,14})$/;++export interface ConfigPrincipal {+ principalType: PrincipalType;+ principalId: string;+}++/** A principal's override document as every engine returns it. */+export interface ConfigRecord {+ /** The engine's identity for the document; changes when a document is deleted and recreated. */+ _id: string;+ principalType: PrincipalType;+ principalId: string;+ principalModel: PrincipalModel;+ priority: number;+ overrides: Partial<TCustomConfig>;+ tombstones: string[];+ isActive: boolean;+ /** Incremented by every write; `0` for a legacy document that never had it. */+ configVersion: number;+ tenantId?: string;+ createdAt?: Date;+ updatedAt?: Date;+}++/** Everything a write sets. Identity, version, tenant and timestamps belong to the engine. */+export type ConfigDraft = Pick<+ ConfigRecord,+ 'principalModel' | 'priority' | 'overrides' | 'tombstones' | 'isActive'+>;++export interface ConfigStore {+ /** The principal's document, active or not, or `null` when it has none. */+ read(principal: ConfigPrincipal): Promise<ConfigRecord | null>;+ /** Every document (optionally only active or inactive ones), in {@link compareConfigRecords} order. */+ list(filter?: { isActive?: boolean }): Promise<ConfigRecord[]>;+ /** The active documents of exactly these principals, in {@link compareConfigRecords} order. */+ listActive(principals: readonly ConfigPrincipal[]): Promise<ConfigRecord[]>;+ /**+ * Writes the whole document when the stored one is at `expected` (or, for+ * {@link ABSENT_CONFIG_REVISION}, when none exists), incrementing `configVersion`. Any other+ * state throws {@link ConfigRevisionConflictError} and changes nothing.+ */+ write(+ principal: ConfigPrincipal,+ draft: ConfigDraft,+ expected: ConfigRevision,+ ): Promise<ConfigRecord>;+ /**+ * Deletes the principal's document and returns it, or returns `null` when there is none. With+ * `expected`, deletes only a document at that revision and throws+ * {@link ConfigRevisionConflictError} for any other state.+ */+ remove(principal: ConfigPrincipal, expected?: ConfigRevision): Promise<ConfigRecord | null>;+ /**+ * Re-inserts a deleted document as it was (identity and version included) only when the+ * principal has none, so a document written since is never replaced. Returns whether it did.+ */+ restore(snapshot: ConfigRecord): Promise<boolean>;+}++/**+ * The stored document is not at the revision a write was conditioned on. `currentRevision` is+ * the revision found (`null` when there is no document), when the failing step knew it.+ */+export class ConfigRevisionConflictError extends Error {+ readonly code = 'CONFIG_VERSION_CONFLICT';+ readonly currentRevision: ConfigRevision | null | undefined;++ constructor(currentRevision?: ConfigRevision | null) {+ super('Config was modified by another request');+ this.name = 'ConfigRevisionConflictError';+ this.currentRevision = currentRevision;+ }+}++export function isConfigRevisionConflict(error: unknown): error is ConfigRevisionConflictError {+ return (+ error instanceof ConfigRevisionConflictError ||+ (error instanceof Error && (error as { code?: unknown }).code === 'CONFIG_VERSION_CONFLICT')+ );+}++export function getConfigRevision(record: {+ _id: { toString(): string };+ configVersion?: number | null;+}): ConfigRevision {+ return `${record._id.toString()}:${record.configVersion ?? 0}`;+}++/** The revision a write must be conditioned on to replace `record` (or to create it). */+export function getExpectedRevision(record: ConfigRecord | null): ConfigRevision {+ return record ? getConfigRevision(record) : ABSENT_CONFIG_REVISION;+}++/** Splits a document revision into identity and version; `null` for anything else. */+export function parseConfigRevision(+ revision: ConfigRevision,+): { id: string; configVersion: number } | null {+ const match = REVISION_PATTERN.exec(revision);+ return match ? { id: match[1], configVersion: Number(match[2]) } : null;+}++/** Whether a client-supplied precondition is well formed: `absent` or a document revision. */+export function isConfigRevision(value: unknown): value is ConfigRevision {+ return (+ typeof value === 'string' &&+ (value === ABSENT_CONFIG_REVISION || parseConfigRevision(value) != null)+ );+}++/** Store order: ascending priority, then the engine identity, so equal priorities never shuffle. */+export function compareConfigRecords(+ left: Pick<ConfigRecord, '_id' | 'priority'>,+ right: Pick<ConfigRecord, '_id' | 'priority'>,+): number {+ if (left.priority !== right.priority) {+ return left.priority - right.priority;+ }+ if (left._id === right._id) {+ return 0;+ }+ return left._id < right._id ? -1 : 1;+}++/**+ * The pause in milliseconds before retry `attempt` (1-based) of a write that lost a race: a random+ * point in the upper half of a ceiling that doubles per retry (20, 40, 80 ms, up to 200), so+ * writers that lost the same race re-read at different times instead of colliding again.+ */+export function getConfigRetryDelay(attempt: number, random: () => number = Math.random): number {+ const ceiling = Math.min(+ CONFIG_RETRY_MAX_DELAY_MS,+ CONFIG_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1),+ );+ return Math.round(ceiling / 2 + random() * (ceiling / 2));+}++function pauseBeforeRetry(attempt: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, getConfigRetryDelay(attempt)));+}++/** What one attempt of {@link runConfigMutation} decided: write `draft`, or stop with `result`. */+export type ConfigMutationPlan<T> = { draft: ConfigDraft; result?: T } | { draft: null; result: T };++export type ConfigMutationOutcome<T> =+ | { written: true; record: ConfigRecord; previous: ConfigRecord | null; result?: T }+ | { written: false; current: ConfigRecord | null; result: T };++export interface ConfigMutationIO {+ read(): Promise<ConfigRecord | null>;+ write(draft: ConfigDraft, expected: ConfigRevision): Promise<ConfigRecord>;+}++/**+ * Read, plan, compare-and-swap. `plan` sees the document as stored and returns the whole next+ * draft (or a reason to stop), so validation and secret preservation always run against what+ * the write replaces.+ *+ * With `expectedRevision` the write happens only on that revision: a mismatch at read or at+ * write throws {@link ConfigRevisionConflictError}. Without it, a concurrent write is absorbed+ * by pausing ({@link getConfigRetryDelay}), re-reading and re-planning, up to `attempts` times,+ * and only then throws.+ */+export async function runConfigMutation<T = never>(+ io: ConfigMutationIO,+ plan: (current: ConfigRecord | null) => ConfigMutationPlan<T> | Promise<ConfigMutationPlan<T>>,+ options: { expectedRevision?: ConfigRevision; attempts?: number } = {},+): Promise<ConfigMutationOutcome<T>> {+ const { expectedRevision } = options;+ const attempts = expectedRevision ? 1 : Math.max(1, options.attempts ?? CONFIG_WRITE_ATTEMPTS);+ for (let attempt = 1; ; attempt++) {+ const current = await io.read();+ const currentRevision = current ? getConfigRevision(current) : null;+ if (expectedRevision && expectedRevision !== (currentRevision ?? ABSENT_CONFIG_REVISION)) {+ throw new ConfigRevisionConflictError(currentRevision);+ }+ const next = await plan(current);+ if (next.draft == null) {+ return { written: false, current, result: next.result as T };+ }+ try {+ const record = await io.write(next.draft, getExpectedRevision(current));+ return { written: true, record, previous: current, result: next.result };+ } catch (error) {+ if (!isConfigRevisionConflict(error) || attempt >= attempts) {+ throw error;+ }+ }+ await pauseBeforeRetry(attempt);+ }+}++/** Options every principal-scoped write accepts. */+export interface ConfigWriteOptions {+ /** Write only when the stored document is at this revision (`absent`: only when none exists). */+ expectedRevision?: ConfigRevision;+}++export interface ConfigLifecycleOptions extends ConfigWriteOptions {+ /**+ * Act only on a document that holds nothing (see `isConfigOverrideStateEmpty`); otherwise+ * resolve to `null` and leave it unchanged. Assign-only callers manage profiles they cannot+ * edit, so they may only touch empty ones.+ */+ expectEmpty?: boolean;+}++/**+ * A path a removal or tombstone addresses: a dotted field path, which cannot name a key that+ * contains a dot, or the path's segments, which can.+ */+export type ConfigPathInput = string | { segments: ConfigPathSegments };++/** One path, or several removed or tombstoned in the same write. */+export type ConfigPathInputs = ConfigPathInput | readonly ConfigPathInput[];++function isEmptyRecord(record: ConfigRecord): boolean {+ return isConfigOverrideStateEmpty(toConfigOverrideState(record));+}++function toDraft(+ current: ConfigRecord | null,+ state: ConfigOverrideState,+ defaults: Pick<ConfigDraft, 'principalModel'> & { priority?: number },+): ConfigDraft {+ return {+ principalModel: defaults.principalModel,+ priority: defaults.priority ?? current?.priority ?? DEFAULT_CONFIG_PRIORITY,+ overrides: state.overrides,+ tombstones: state.tombstones,+ isActive: current?.isActive ?? true,+ };+}++/** The record a plan that always drafts has written. */+function writtenRecord(outcome: ConfigMutationOutcome<never>): ConfigRecord {+ if (!outcome.written) {+ throw new Error('Config mutation planned no write');+ }+ return outcome.record;+}++function toSegments(path: ConfigPathInput): ConfigPathSegments {+ return typeof path === 'string' ? parseFieldPath(path) : path.segments;+}++function toPathList(paths: ConfigPathInputs): ConfigPathSegments[] {+ return Array.isArray(paths) ? paths.map(toSegments) : [toSegments(paths as ConfigPathInput)];+}++type ActiveToggle = { config: ConfigRecord; changed: boolean };++export interface ConfigOperations {+ findConfig(+ principal: ConfigPrincipal,+ options?: { includeInactive?: boolean },+ ): Promise<ConfigRecord | null>;+ getApplicableConfigs(+ principals?: ReadonlyArray<{ principalType: string; principalId?: { toString(): string } }>,+ ): Promise<ConfigRecord[]>;+ replaceOverrides(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ overrides: Partial<TCustomConfig>,+ priority: number,+ options?: ConfigLifecycleOptions & { preservePriority?: boolean },+ ): Promise<ConfigRecord | null>;+ setFields(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ fields: Record<string, unknown>,+ priority?: number,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord>;+ tombstoneFields(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ fieldPaths: ConfigPathInputs,+ priority?: number,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord>;+ unsetFields(+ principal: ConfigPrincipal,+ fieldPaths: ConfigPathInputs,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord | null>;+ deleteConfig(+ principal: ConfigPrincipal,+ options?: ConfigLifecycleOptions,+ ): Promise<ConfigRecord | null>;+ setActive(+ principal: ConfigPrincipal,+ isActive: boolean,+ options?: ConfigLifecycleOptions,+ ): Promise<ActiveToggle | null>;+}++/**+ * The principal-scoped operations every caller uses, built only on the {@link ConfigStore}+ * contract, so each engine gets identical override semantics. A dotted `fieldPath` argument is+ * split into segments and so cannot address a key that itself contains a dot; removals take+ * `{ segments }` for that, and `setFields` callers write such a record whole at its own path.+ */+export function createConfigOperations(store: ConfigStore): ConfigOperations {+ function mutate<T = never>(+ principal: ConfigPrincipal,+ plan: (current: ConfigRecord | null) => ConfigMutationPlan<T>,+ options?: ConfigWriteOptions,+ ): Promise<ConfigMutationOutcome<T>> {+ return runConfigMutation<T>(+ {+ read: () => store.read(principal),+ write: (draft, expected) => store.write(principal, draft, expected),+ },+ plan,+ { expectedRevision: options?.expectedRevision },+ );+ }++ async function findConfig(+ principal: ConfigPrincipal,+ options?: { includeInactive?: boolean },+ ): Promise<ConfigRecord | null> {+ const record = await store.read(principal);+ if (!record || (!options?.includeInactive && !record.isActive)) {+ return null;+ }+ return record;+ }++ /** Base first in the query, then every principal that has an id; inactive documents excluded. */+ function getApplicableConfigs(+ principals?: ReadonlyArray<{ principalType: string; principalId?: { toString(): string } }>,+ ): Promise<ConfigRecord[]> {+ const query: ConfigPrincipal[] = [+ { principalType: PrincipalType.ROLE, principalId: BASE_CONFIG_PRINCIPAL_ID },+ ];+ for (const principal of principals ?? []) {+ if (principal.principalId !== undefined) {+ query.push({+ principalType: principal.principalType as PrincipalType,+ principalId: principal.principalId.toString(),+ });+ }+ }+ return store.listActive(query);+ }++ /** Replaces the overrides whole and activates the document; tombstones stay. */+ async function replaceOverrides(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ overrides: Partial<TCustomConfig>,+ priority: number,+ options?: ConfigLifecycleOptions & { preservePriority?: boolean },+ ): Promise<ConfigRecord | null> {+ const outcome = await mutate<null>(+ principal,+ (current) => {+ if (options?.expectEmpty && current && !isEmptyRecord(current)) {+ return { draft: null, result: null };+ }+ const state = replaceConfigOverrides(toConfigOverrideState(current), overrides);+ const keptPriority = options?.preservePriority ? (current?.priority ?? priority) : priority;+ return {+ draft: {+ ...toDraft(current, state, { principalModel, priority: keptPriority }),+ isActive: true,+ },+ };+ },+ options,+ );+ return outcome.written ? outcome.record : null;+ }++ /** Sets dotted field paths, clearing the tombstones they write over. Creates the document. */+ async function setFields(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ fields: Record<string, unknown>,+ priority?: number,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord> {+ const writes = Object.entries(fields).map(([fieldPath, value]) => ({+ segments: parseFieldPath(fieldPath),+ value,+ }));+ const outcome = await mutate(+ principal,+ (current) => ({+ draft: toDraft(current, setConfigFields(toConfigOverrideState(current), writes), {+ principalModel,+ priority,+ }),+ }),+ options,+ );+ return writtenRecord(outcome);+ }++ /** Tombstones every path in one write (a secret and its preview companion together). */+ async function tombstoneFields(+ principal: ConfigPrincipal,+ principalModel: PrincipalModel,+ fieldPaths: ConfigPathInputs,+ priority?: number,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord> {+ const paths = toPathList(fieldPaths);+ const outcome = await mutate(+ principal,+ (current) => ({+ draft: toDraft(current, tombstoneConfigPaths(toConfigOverrideState(current), paths), {+ principalModel,+ priority,+ }),+ }),+ options,+ );+ return writtenRecord(outcome);+ }++ /** Removes every path in one write, pruning emptied parents. `null` when there is no document. */+ async function unsetFields(+ principal: ConfigPrincipal,+ fieldPaths: ConfigPathInputs,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord | null> {+ const paths = toPathList(fieldPaths);+ const outcome = await mutate<null>(+ principal,+ (current) => {+ if (!current) {+ return { draft: null, result: null };+ }+ const state = unsetConfigPaths(toConfigOverrideState(current), paths);+ return { draft: toDraft(current, state, current) };+ },+ options,+ );+ return outcome.written ? outcome.record : null;+ }++ /** Deletes the principal's document; `null` when there is none (or `expectEmpty` refused). */+ async function deleteConfig(+ principal: ConfigPrincipal,+ options?: ConfigLifecycleOptions,+ ): Promise<ConfigRecord | null> {+ if (!options?.expectEmpty && !options?.expectedRevision) {+ return store.remove(principal);+ }+ for (let attempt = 1; ; attempt++) {+ const current = await store.read(principal);+ const currentRevision = current ? getConfigRevision(current) : null;+ if (+ options.expectedRevision &&+ options.expectedRevision !== (currentRevision ?? ABSENT_CONFIG_REVISION)+ ) {+ throw new ConfigRevisionConflictError(currentRevision);+ }+ if (!current || (options.expectEmpty && !isEmptyRecord(current))) {+ return null;+ }+ try {+ return await store.remove(principal, getConfigRevision(current));+ } catch (error) {+ if (+ !isConfigRevisionConflict(error) ||+ options.expectedRevision ||+ attempt >= CONFIG_WRITE_ATTEMPTS+ ) {+ throw error;+ }+ }+ await pauseBeforeRetry(attempt);+ }+ }++ /** Sets `isActive`, reporting whether this write changed it. `null` when there is no document. */+ async function setActive(+ principal: ConfigPrincipal,+ isActive: boolean,+ options?: ConfigLifecycleOptions,+ ): Promise<ActiveToggle | null> {+ const outcome = await mutate<ActiveToggle | null>(+ principal,+ (current) => {+ if (!current || (options?.expectEmpty && !isEmptyRecord(current))) {+ return { draft: null, result: null };+ }+ if (current.isActive === isActive) {+ return { draft: null, result: { config: current, changed: false } };+ }+ return {+ draft: { ...toDraft(current, toConfigOverrideState(current), current), isActive },+ };+ },+ options,+ );+ return outcome.written ? { config: outcome.record, changed: true } : outcome.result;+ }++ return {+ findConfig,+ getApplicableConfigs,+ replaceOverrides,+ setFields,+ tombstoneFields,+ unsetFields,+ deleteConfig,+ setActive,+ };+}diff --git a/packages/data-schemas/src/methods/config.spec.ts b/packages/data-schemas/src/methods/config.spec.tsindex 3acbc3e767..25e7721c94 100644--- a/packages/data-schemas/src/methods/config.spec.ts+++ b/packages/data-schemas/src/methods/config.spec.ts@@ -1,6 +1,7 @@import mongoose, { Types } from 'mongoose';import { MongoMemoryServer } from 'mongodb-memory-server';import { PrincipalType, PrincipalModel } from 'librechat-data-provider';+import type { ConfigRecord } from '~/app/store';import type { IConfig } from '~/types';import { createConfigMethods } from './config';import configSchema from '~/schema/config';@@ -33,7 +34,7 @@ describe('restoreConfig', () => {await methods.tombstoneConfigField(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, 'a.b', 10);await methods.toggleConfigActive(PrincipalType.ROLE, 'admin', false);const deleted = await methods.deleteConfig(PrincipalType.ROLE, 'admin');- const snapshot = deleted!.toObject() as Record<string, unknown>;+ const snapshot = { ...deleted! };expect(await methods.restoreConfig(snapshot)).toBe(true);const restored = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'admin', {@@ -689,29 +690,686 @@ describe('toggleConfigActiveTracked', () => {});});-describe('expectedVersion write precondition', () => {- const ROLE = 'precondition-role';+const raw = () => mongoose.connection.db!.collection('configs');++function collectKeys(value: unknown, keys: string[] = []): string[] {+ if (Array.isArray(value)) {+ value.forEach((item) => collectKeys(item, keys));+ } else if (value != null && typeof value === 'object') {+ for (const [key, child] of Object.entries(value)) {+ keys.push(key);+ collectKeys(child, keys);+ }+ }+ return keys;+}++describe('key encoding at rest', () => {+ const dotted = {+ endpoints: {+ bedrock: { inferenceProfiles: { 'us.anthropic.claude-sonnet-4-5': 'arn:aws:x' } },+ azureOpenAI: { groups: [{ group: 'g', models: { 'gpt-4.1': { deploymentName: 'd' } } }] },+ },+ fileConfig: { endpoints: { custom: { supportedMimeTypes: ['image/.*'] } } },+ $top: { 'a.b': '$value.stays' },+ };++ /** Makes the engine refuse a dotted or `$` field name anywhere in a stored value, as DocumentDB, Cosmos or MongoDB 4.4 may. */+ function refuseRawKeyNames() {+ const collection = mongoose.models.Config.collection;+ const findOneAndUpdate = collection.findOneAndUpdate.bind(collection);+ const hasRawName = (value: unknown) =>+ collectKeys(value).some((key) => key.includes('.') || key.startsWith('$'));+ return jest.spyOn(collection, 'findOneAndUpdate').mockImplementation((async (+ filter: Record<string, unknown>,+ update: { $set?: Record<string, unknown>; $setOnInsert?: Record<string, unknown> },+ options: Record<string, unknown>,+ ) => {+ if (hasRawName(update.$set?.overrides) || hasRawName(update.$setOnInsert?.overrides)) {+ throw new mongoose.mongo.MongoServerError({+ ok: 0,+ code: 57,+ errmsg: "The dotted field 'us.a.b' in 'overrides' is not valid for storage.",+ });+ }+ return findOneAndUpdate(filter, update as never, options);+ }) as unknown as typeof collection.findOneAndUpdate);+ }++ it('stores record keys raw where the engine accepts them, as servers before the encoding read them', async () => {+ await methods.upsertConfig(PrincipalType.ROLE, 'enc', PrincipalModel.ROLE, dotted as never, 10);++ const stored = await raw().findOne({ principalId: 'enc' });+ expect(stored!.overrides).toEqual(dotted);+ expect(stored!.keyEncoding).toBeUndefined();++ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'enc');+ expect(read!.overrides).toEqual(dotted);+ expect(+ (await methods.getApplicableConfigs([{ principalType: 'role', principalId: 'enc' }]))[0]+ .overrides,+ ).toEqual(dotted);+ });++ it('encodes keys once the engine refuses a raw key name, and reads them back decoded', async () => {+ const refusing = createConfigMethods(mongoose);+ const findOneAndUpdate = refuseRawKeyNames();++ await refusing.upsertConfig(+ PrincipalType.ROLE,+ 'enc',+ PrincipalModel.ROLE,+ dotted as never,+ 10,+ );++ const stored = await raw().findOne({ principalId: 'enc' });+ expect(+ collectKeys(stored!.overrides).filter((key) => key.includes('.') || key.startsWith('$')),+ ).toEqual([]);+ expect(stored!.keyEncoding).toBe(1);+ expect(stored!.overrides['%24top']).toEqual({ 'a%2Eb': '$value.stays' });+ expect((await refusing.findConfigByPrincipal(PrincipalType.ROLE, 'enc'))!.overrides).toEqual(+ dotted,+ );++ findOneAndUpdate.mockClear();+ const patched = await refusing.patchConfigFields(+ PrincipalType.ROLE,+ 'enc',+ PrincipalModel.ROLE,+ {+ 'endpoints.bedrock.inferenceProfiles': { 'eu.meta.llama': 'arn:eu' },+ },+ );+ expect(findOneAndUpdate).toHaveBeenCalledTimes(1);+ expect(patched.overrides.endpoints).toMatchObject({+ bedrock: { inferenceProfiles: { 'eu.meta.llama': 'arn:eu' } },+ });+ });++ it('restores a deleted document with dotted keys in the form the engine accepts', async () => {+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'snap',+ PrincipalModel.ROLE,+ dotted as never,+ 10,+ );+ const deleted = await methods.deleteConfig(PrincipalType.ROLE, 'snap');++ expect(await methods.restoreConfig(deleted!)).toBe(true);+ expect((await raw().findOne({ principalId: 'snap' }))!.overrides).toEqual(dotted);++ const refusing = createConfigMethods(mongoose);+ const updateOne = jest+ .spyOn(mongoose.models.Config.collection, 'updateOne')+ .mockRejectedValueOnce(+ new mongoose.mongo.MongoServerError({+ ok: 0,+ code: 57,+ errmsg: "The dotted field 'us.a.b' in 'overrides' is not valid for storage.",+ }),+ );+ const again = await refusing.deleteConfig(PrincipalType.ROLE, 'snap');++ expect(await refusing.restoreConfig(again!)).toBe(true);+ expect(updateOne).toHaveBeenCalledTimes(2);+ const stored = await raw().findOne({ principalId: 'snap' });+ expect(stored!.keyEncoding).toBe(1);+ expect(stored!.overrides['%24top']).toEqual({ 'a%2Eb': '$value.stays' });+ expect((await refusing.findConfigByPrincipal(PrincipalType.ROLE, 'snap'))!.overrides).toEqual(+ dotted,+ );+ });++ it('keeps a field under a dotted record key raw when it is patched by segments of its parent', async () => {+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'enc2',+ PrincipalModel.ROLE,+ dotted as never,+ 10,+ );++ const patched = await methods.patchConfigFields(+ PrincipalType.ROLE,+ 'enc2',+ PrincipalModel.ROLE,+ { 'endpoints.bedrock.inferenceProfiles': { 'eu.meta.llama': 'arn:eu' } },+ 10,+ );++ expect(patched.overrides).toEqual({+ ...dotted,+ endpoints: {+ ...dotted.endpoints,+ bedrock: { inferenceProfiles: { 'eu.meta.llama': 'arn:eu' } },+ },+ });+ const stored = await raw().findOne({ principalId: 'enc2' });+ expect(stored!.overrides.endpoints.bedrock.inferenceProfiles).toEqual({+ 'eu.meta.llama': 'arn:eu',+ });+ });++ it('removes dotted record keys by their segments, pruning what they empty, in one write', async () => {+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'enc3',+ PrincipalModel.ROLE,+ dotted as never,+ 10,+ );+ const profile = ['endpoints', 'bedrock', 'inferenceProfiles', 'us.anthropic.claude-sonnet-4-5'];++ const removed = await methods.unsetConfigField(PrincipalType.ROLE, 'enc3', [+ { segments: profile },+ { segments: ['endpoints', 'azureOpenAI', 'groups', '0', 'models', 'gpt-4.1'] },+ ]);++ expect(removed!.overrides).toEqual({+ endpoints: { azureOpenAI: { groups: [{ group: 'g' }] } },+ fileConfig: dotted.fileConfig,+ $top: dotted.$top,+ });+ expect(removed!.configVersion).toBe(2);+ const stored = await raw().findOne({ principalId: 'enc3' });+ expect(stored!.overrides.endpoints).toEqual({ azureOpenAI: { groups: [{ group: 'g' }] } });+ });++ it('reads a legacy document without the marker verbatim, even keys that look encoded', async () => {+ await raw().insertOne({+ principalType: 'role',+ principalId: 'legacy',+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ configVersion: 3,+ tombstones: [],+ overrides: { endpoints: { azureOpenAI: { 'gpt-4.1': true, 'literal%2Ekey': 1 } } },+ });++ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'legacy');++ expect(read!.overrides).toEqual({+ endpoints: { azureOpenAI: { 'gpt-4.1': true, 'literal%2Ekey': 1 } },+ });+ });++ it('keeps a legacy document raw on its next write without changing its keys', async () => {+ const legacyOverrides = {+ endpoints: { azureOpenAI: { 'gpt-4.1': true, 'literal%2Ekey': 1 } },+ interface: { customWelcome: 'hi' },+ };+ await raw().insertOne({+ principalType: 'role',+ principalId: 'lazy',+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ tombstones: [],+ overrides: legacyOverrides,+ });++ const written = await methods.patchConfigFields(+ PrincipalType.ROLE,+ 'lazy',+ PrincipalModel.ROLE,+ { 'interface.customWelcome': 'hello' },+ );- async function seed(): Promise<IConfig> {- const config = await methods.patchConfigFields(+ const expected = { ...legacyOverrides, interface: { customWelcome: 'hello' } };+ expect(written.overrides).toEqual(expected);+ expect(written.configVersion).toBe(1);+ const stored = await raw().findOne({ principalId: 'lazy' });+ expect(stored!.keyEncoding).toBeUndefined();+ expect(stored!.overrides).toEqual(expected);+ expect((await methods.findConfigByPrincipal(PrincipalType.ROLE, 'lazy'))!.overrides).toEqual(+ expected,+ );+ });++ it('encodes a document whose raw keys a read would take for escape sequences', async () => {+ const overrides = { endpoints: { custom: [{ name: 'gw', headers: { 'X-Ratio%25': 'a' } }] } };++ await methods.upsertConfig(PrincipalType.ROLE,- ROLE,+ 'pct',PrincipalModel.ROLE,- { 'webSearch.searxngInstanceUrl': 'https://searx.example.com' },+ overrides as never,10,);- return config!;++ const stored = await raw().findOne({ principalId: 'pct' });+ expect(stored!.keyEncoding).toBe(1);+ expect(stored!.overrides.endpoints.custom[0].headers).toEqual({ 'X-Ratio%2525': 'a' });+ expect((await methods.findConfigByPrincipal(PrincipalType.ROLE, 'pct'))!.overrides).toEqual(+ overrides,+ );+ });++ describe('documents an older server wrote over', () => {+ const encoded = {+ endpoints: { bedrock: { inferenceProfiles: { 'us%2Eanthropic%2Eclaude': 'arn:aws:x' } } },+ '%24top': { 'a%2Eb': 1 },+ };+ const decoded = {+ endpoints: { bedrock: { inferenceProfiles: { 'us.anthropic.claude': 'arn:aws:x' } } },+ $top: { 'a.b': 1 },+ };++ async function insert(principalId: string, document: Record<string, unknown>) {+ await raw().insertOne({+ principalType: 'role',+ principalId,+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ configVersion: 2,+ tombstones: [],+ ...document,+ });+ }++ it('decodes an encoded document whose marker an older server dropped', async () => {+ /** A pre-encoding schema has no `keyEncoding`, so its restore re-inserts the keys without it. */+ await insert('dropped', { overrides: encoded });++ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'dropped');++ expect(read!.overrides).toEqual(decoded);+ });++ it('reads raw keys an older server wrote under a marker it left in place', async () => {+ await insert('stale', {+ keyEncoding: 1,+ overrides: { endpoints: { azureOpenAI: { 'gpt-4.1': true } }, interface: { a: 1 } },+ });++ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'stale');++ expect(read!.overrides).toEqual({+ endpoints: { azureOpenAI: { 'gpt-4.1': true } },+ interface: { a: 1 },+ });+ });++ it('reads raw keys an older server added beside encoded ones', async () => {+ await insert('mixed', { keyEncoding: 1, overrides: encoded });+ await raw().updateOne(+ { principalId: 'mixed' },+ {+ $set: {+ 'overrides.interface.contextCost': true,+ 'overrides.endpoints.azureOpenAI': { models: { 'gpt-4.1': true } },+ },+ },+ );++ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'mixed');++ expect(read!.overrides).toEqual({+ ...decoded,+ endpoints: { ...decoded.endpoints, azureOpenAI: { models: { 'gpt-4.1': true } } },+ interface: { contextCost: true },+ });+ });++ it('rewrites an encoded document raw on its next write and clears the marker', async () => {+ await insert('rewrite', { keyEncoding: 1, overrides: encoded });++ await methods.patchConfigFields(PrincipalType.ROLE, 'rewrite', PrincipalModel.ROLE, {+ 'interface.customWelcome': 'hi',+ });++ const stored = await raw().findOne({ principalId: 'rewrite' });+ expect(stored!.keyEncoding).toBeUndefined();+ expect(stored!.overrides).toEqual({ ...decoded, interface: { customWelcome: 'hi' } });+ });+ });+});++describe('revision preconditions', () => {+ const revisionOf = (config: { _id: string; configVersion: number }) =>+ `${config._id}:${config.configVersion}`;++ async function seed(principalId: string) {+ return methods.patchConfigFields(PrincipalType.ROLE, principalId, PrincipalModel.ROLE, {+ 'interface.customWelcome': 'v1',+ });}- async function readStored(): Promise<Record<string, unknown> | null> {- return mongoose.models.Config.findOne({ principalId: ROLE }).lean<Record<string, unknown>>();+ it('writes at the matching revision and bumps the version by one', async () => {+ const first = await seed('rev');++ const next = await methods.patchConfigFields(+ PrincipalType.ROLE,+ 'rev',+ PrincipalModel.ROLE,+ { 'interface.customWelcome': 'v2' },+ undefined,+ undefined,+ { expectedRevision: revisionOf(first) },+ );++ expect(next.configVersion).toBe(first.configVersion + 1);+ expect(next._id).toBe(first._id);+ });++ it('refuses a stale revision with a typed conflict and changes nothing', async () => {+ const first = await seed('stale');+ const second = await methods.patchConfigFields(+ PrincipalType.ROLE,+ 'stale',+ PrincipalModel.ROLE,+ {+ 'interface.customWelcome': 'v2',+ },+ );++ await expect(+ methods.unsetConfigField(PrincipalType.ROLE, 'stale', 'interface.customWelcome', undefined, {+ expectedRevision: revisionOf(first),+ }),+ ).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: revisionOf(second),+ });+ expect((await methods.findConfigByPrincipal(PrincipalType.ROLE, 'stale'))!.configVersion).toBe(+ 2,+ );+ });++ it('never creates a document for a revision of one that does not exist', async () => {+ await expect(+ methods.tombstoneConfigField(+ PrincipalType.ROLE,+ 'ghost',+ PrincipalModel.ROLE,+ 'memory',+ 10,+ undefined,+ {+ expectedRevision: `${new Types.ObjectId().toString()}:4`,+ },+ ),+ ).rejects.toMatchObject({ code: 'CONFIG_VERSION_CONFLICT', currentRevision: null });+ expect(await raw().countDocuments({ principalId: 'ghost' })).toBe(0);+ });++ it("creates with 'absent' and then conflicts on a second create", async () => {+ const created = await methods.upsertConfig(+ PrincipalType.ROLE,+ 'once',+ PrincipalModel.ROLE,+ {},+ 10,+ undefined,+ {+ expectedRevision: 'absent',+ },+ );+ expect(created!.configVersion).toBe(1);++ await expect(+ methods.upsertConfig(+ PrincipalType.ROLE,+ 'once',+ PrincipalModel.ROLE,+ { a: 1 } as never,+ 10,+ undefined,+ {+ expectedRevision: 'absent',+ },+ ),+ ).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: revisionOf(created!),+ });+ });++ it('matches a legacy document without configVersion at version 0', async () => {+ const { insertedId } = await raw().insertOne({+ principalType: 'role',+ principalId: 'old',+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ overrides: { a: { b: 1 } },+ });+ const read = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'old');+ expect(revisionOf(read!)).toBe(`${insertedId.toString()}:0`);++ const written = await methods.unsetConfigField(PrincipalType.ROLE, 'old', 'a.b', undefined, {+ expectedRevision: `${insertedId.toString()}:0`,+ });++ expect(written!.configVersion).toBe(1);+ expect(written!.overrides).toEqual({});+ });++ it('lets exactly one of two concurrent conditioned patches win', async () => {+ const first = await seed('race');++ const results = await Promise.allSettled(+ ['a', 'b'].map((value) =>+ methods.patchConfigFields(+ PrincipalType.ROLE,+ 'race',+ PrincipalModel.ROLE,+ { 'interface.customWelcome': value },+ undefined,+ undefined,+ { expectedRevision: revisionOf(first) },+ ),+ ),+ );++ expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);+ expect((await methods.findConfigByPrincipal(PrincipalType.ROLE, 'race'))!.configVersion).toBe(+ 2,+ );+ });++ it('keeps every concurrent unconditioned patch by re-reading on conflict', async () => {+ await seed('merge');++ await Promise.all(+ ['a', 'b', 'c'].map((key) =>+ methods.patchConfigFields(PrincipalType.ROLE, 'merge', PrincipalModel.ROLE, {+ [`speech.${key}`]: key,+ }),+ ),+ );++ const stored = await methods.findConfigByPrincipal(PrincipalType.ROLE, 'merge');+ expect((stored!.overrides as Record<string, unknown>).speech).toEqual({+ a: 'a',+ b: 'b',+ c: 'c',+ });+ expect(stored!.configVersion).toBe(4);+ });++ it('refuses a revision of a deleted and recreated document (ABA)', async () => {+ const original = await seed('aba');+ await methods.deleteConfig(PrincipalType.ROLE, 'aba');+ await seed('aba');++ await expect(+ methods.patchConfigFields(+ PrincipalType.ROLE,+ 'aba',+ PrincipalModel.ROLE,+ { 'a.b': 1 },+ 10,+ undefined,+ {+ expectedRevision: revisionOf(original),+ },+ ),+ ).rejects.toMatchObject({ code: 'CONFIG_VERSION_CONFLICT' });+ });++ it('deletes and toggles only at the expected revision; toggling bumps the version', async () => {+ const first = await seed('life');++ const toggled = await methods.toggleConfigActiveTracked(PrincipalType.ROLE, 'life', false, {+ expectedRevision: revisionOf(first),+ });+ expect(toggled).toMatchObject({ changed: true, config: { isActive: false, configVersion: 2 } });++ await expect(+ methods.deleteConfig(PrincipalType.ROLE, 'life', undefined, {+ expectedRevision: revisionOf(first),+ }),+ ).rejects.toMatchObject({ code: 'CONFIG_VERSION_CONFLICT' });+ const deleted = await methods.deleteConfig(PrincipalType.ROLE, 'life', undefined, {+ expectedRevision: revisionOf(toggled!.config),+ });+ expect(deleted!._id).toBe(first._id);+ });+});++describe('pruning emptied parents', () => {+ const read = (principalId: string) =>+ methods.findConfigByPrincipal(PrincipalType.ROLE, principalId, { includeInactive: true });++ it('removes the parents a field reset leaves empty, keeping siblings', async () => {+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'prune',+ PrincipalModel.ROLE,+ { balance: { startBalance: 5 }, interface: { a: 1, b: 2 } } as never,+ 10,+ );++ await methods.unsetConfigField(PrincipalType.ROLE, 'prune', 'balance.startBalance');+ await methods.unsetConfigField(PrincipalType.ROLE, 'prune', 'interface.a');++ expect((await read('prune'))!.overrides).toEqual({ interface: { b: 2 } });+ });++ it('prunes inside an array element without nulling it', async () => {+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'arr',+ PrincipalModel.ROLE,+ { endpoints: { custom: [{ name: 'a', headers: { A: '1' } }] } } as never,+ 10,+ );++ await methods.unsetConfigField(PrincipalType.ROLE, 'arr', 'endpoints.custom.0.headers.A');++ expect((await read('arr'))!.overrides).toEqual({ endpoints: { custom: [{ name: 'a' }] } });+ await expect(+ methods.unsetConfigField(PrincipalType.ROLE, 'arr', 'endpoints.custom.0'),+ ).rejects.toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'array_element' });+ expect((await read('arr'))!.overrides).toEqual({ endpoints: { custom: [{ name: 'a' }] } });+ });++ it('keeps a sibling tombstone when its parent is pruned', async () => {+ await methods.patchConfigFields(PrincipalType.ROLE, 'tomb', PrincipalModel.ROLE, {+ 'mcpServers.foo.title': 'Foo',+ });+ await methods.tombstoneConfigField(+ PrincipalType.ROLE,+ 'tomb',+ PrincipalModel.ROLE,+ 'mcpServers.github',+ 10,+ );++ const result = await methods.unsetConfigField(PrincipalType.ROLE, 'tomb', 'mcpServers.foo');++ expect(result!.overrides).toEqual({});+ expect(result!.tombstones).toEqual(['mcpServers.github']);+ });++ it('prunes on tombstone and removes a secret with its preview in one write', async () => {+ const seeded = await methods.patchConfigFields(+ PrincipalType.ROLE,+ 'secret',+ PrincipalModel.ROLE,+ {+ 'ocr.apiKey': 'v3:cipher',+ 'ocr.apiKeyPreview': '...abcd',+ },+ );++ const result = await methods.tombstoneConfigField(+ PrincipalType.ROLE,+ 'secret',+ PrincipalModel.ROLE,+ ['ocr.apiKey', 'ocr.apiKeyPreview'],+ );++ expect(result.overrides).toEqual({});+ expect(result.tombstones).toEqual(['ocr.apiKey', 'ocr.apiKeyPreview']);+ expect(result.configVersion).toBe(seeded.configVersion + 1);+ expect(result.priority).toBe(seeded.priority);+ });++ it('treats a document holding only shells as empty for assign-only lifecycle calls', async () => {+ await raw().insertOne({+ principalType: 'role',+ principalId: 'shells',+ principalModel: 'Role',+ priority: 10,+ isActive: true,+ configVersion: 2,+ tombstones: [],+ overrides: { balance: {}, interface: { theme: {} } },+ });++ expect(+ await methods.toggleConfigActive(PrincipalType.ROLE, 'shells', false, undefined, {+ expectEmpty: true,+ }),+ ).toMatchObject({ isActive: false });+ expect(+ await methods.upsertConfig(+ PrincipalType.ROLE,+ 'shells',+ PrincipalModel.ROLE,+ {},+ 10,+ undefined,+ {+ expectEmpty: true,+ preservePriority: true,+ },+ ),+ ).toMatchObject({ isActive: true, overrides: {} });+ expect(+ await methods.deleteConfig(PrincipalType.ROLE, 'shells', undefined, { expectEmpty: true }),+ ).not.toBeNull();+ });+});++/** The write preconditions web search binding writes rely on, carried by store revisions. */+describe('web search write preconditions', () => {+ const ROLE = 'precondition-role';+ const revisionOf = (config: { _id: string; configVersion: number }) =>+ `${config._id}:${config.configVersion}`;++ function seed(): Promise<ConfigRecord> {+ return methods.patchConfigFields(PrincipalType.ROLE, ROLE, PrincipalModel.ROLE, {+ 'webSearch.searxngInstanceUrl': 'https://searx.example.com',+ });}- type Write = (expectedVersion: number | null) => Promise<IConfig | null>;+ function readStored() {+ return raw().findOne({ principalId: ROLE });+ }++ type Write = (expectedRevision: string) => Promise<ConfigRecord | null>;const writes: Array<{ name: string; write: Write }> = [{name: 'patchConfigFields',- write: (expectedVersion) =>+ write: (expectedRevision) =>methods.patchConfigFields(PrincipalType.ROLE,ROLE,@@ -719,12 +1377,12 @@ describe('expectedVersion write precondition', () => {{ 'webSearch.searxngInstanceUrl': 'https://attacker.example.com' },10,undefined,- { expectedVersion },+ { expectedRevision },),},{name: 'upsertConfig',- write: (expectedVersion) =>+ write: (expectedRevision) =>methods.upsertConfig(PrincipalType.ROLE,ROLE,@@ -732,12 +1390,12 @@ describe('expectedVersion write precondition', () => {{ webSearch: { searxngInstanceUrl: 'https://attacker.example.com' } },10,undefined,- { expectedVersion },+ { expectedRevision },),},{name: 'tombstoneConfigField',- write: (expectedVersion) =>+ write: (expectedRevision) =>methods.tombstoneConfigField(PrincipalType.ROLE,ROLE,@@ -745,25 +1403,38 @@ describe('expectedVersion write precondition', () => {'webSearch.searxngInstanceUrl',10,undefined,- { expectedVersion },+ { expectedRevision },),},];- it.each(writes)('$name applies at the version the caller read', async ({ write }) => {+ /** Makes the database refuse every write, after `beforeRefusal` runs. */+ function refuseWrites(beforeRefusal: () => Promise<void> = async () => undefined) {+ const collection = mongoose.models.Config.collection;+ jest.spyOn(collection, 'findOneAndUpdate').mockImplementation((async () => {+ await beforeRefusal();+ throw new mongoose.mongo.MongoServerError({+ ok: 0,+ code: 57,+ errmsg: "The dotted field 'us.a.b' in 'overrides' is not valid for storage.",+ });+ }) as unknown as typeof collection.findOneAndUpdate);+ }++ it.each(writes)('$name applies at the revision the caller read', async ({ write }) => {const seeded = await seed();- const result = await write(seeded.configVersion);+ const result = await write(revisionOf(seeded));- expect(result).not.toBeNull();expect(result!.configVersion).toBe(seeded.configVersion + 1);+ expect(result!._id).toBe(seeded._id);});it.each(writes)(- '$name changes nothing once another write moved the version',+ '$name changes nothing once another write moved the revision',async ({ write }) => {const seeded = await seed();- await methods.patchConfigFields(+ const moved = await methods.patchConfigFields(PrincipalType.ROLE,ROLE,PrincipalModel.ROLE,@@ -772,30 +1443,20 @@ describe('expectedVersion write precondition', () => {);const before = await readStored();- expect(await write(seeded.configVersion)).toBeNull();+ await expect(write(revisionOf(seeded))).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: revisionOf(moved),+ });expect(await readStored()).toEqual(before);},);it.each(writes)('$name creates the document the caller saw absent', async ({ write }) => {- const result = await write(null);+ const result = await write('absent');- expect(result).not.toBeNull();expect(result!.configVersion).toBe(1);expect(result!.createdAt).toBeInstanceOf(Date);- expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(1);- });-- it('detects a document that appeared without relying on the unique index', async () => {- const Config = mongoose.models.Config;- await seed();- await Config.collection.dropIndexes();- try {- expect(await writes[0].write(null)).toBeNull();- expect(await Config.countDocuments({ principalId: ROLE })).toBe(1);- } finally {- await Config.syncIndexes();- }+ expect(await raw().countDocuments({ principalId: ROLE })).toBe(1);});it.each(writes)(@@ -804,7 +1465,7 @@ describe('expectedVersion write precondition', () => {await seed();const before = await readStored();- expect(await write(null)).toBeNull();+ await expect(write('absent')).rejects.toMatchObject({ code: 'CONFIG_VERSION_CONFLICT' });expect(await readStored()).toEqual(before);},);@@ -815,101 +1476,125 @@ describe('expectedVersion write precondition', () => {const seeded = await seed();await methods.deleteConfig(PrincipalType.ROLE, ROLE);- expect(await write(seeded.configVersion)).toBeNull();- expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(0);+ await expect(write(revisionOf(seeded))).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: null,+ });+ expect(await raw().countDocuments({ principalId: ROLE })).toBe(0);},);- /**- * Makes the database refuse the version-checked write, the way an engine that cannot store a- * key name does, after `beforeRefusal` runs. The created empty document's upsert still lands.- */- function refuseVersionedWrites(beforeRefusal: () => Promise<void> = async () => undefined) {- const collection = mongoose.models.Config.collection;- const findOneAndUpdate = collection.findOneAndUpdate.bind(collection);- jest.spyOn(collection, 'findOneAndUpdate').mockImplementation((async (- filter: Record<string, unknown>,- update: { $inc?: Record<string, number> },- options: Record<string, unknown>,- ) => {- if (update.$inc == null) {- return findOneAndUpdate(filter, update, options);- }- await beforeRefusal();- throw new mongoose.mongo.MongoServerError({- ok: 0,- code: 57,- errmsg: "The dotted field 'us.a.b' in 'overrides' is not valid for storage.",+ it('detects a document that appeared without relying on the unique index', async () => {+ const seeded = await seed();+ const before = await readStored();+ const Config = mongoose.models.Config;+ await Config.collection.dropIndexes();+ try {+ await expect(+ methods.writeConfigDocument(+ PrincipalType.ROLE,+ ROLE,+ {+ principalModel: PrincipalModel.ROLE,+ priority: 10,+ overrides: { webSearch: { searxngInstanceUrl: 'https://attacker.example.com' } },+ tombstones: [],+ isActive: true,+ },+ 'absent',+ ),+ ).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ currentRevision: revisionOf(seeded),});- }) as unknown as typeof collection.findOneAndUpdate);- }+ expect(await raw().countDocuments({ principalId: ROLE })).toBe(1);+ expect(await readStored()).toEqual(before);+ } finally {+ await Config.syncIndexes();+ }+ });it.each(writes)('$name leaves no document when the database refuses a write the caller saw absent',async ({ write }) => {- refuseVersionedWrites();+ refuseWrites();- await expect(write(null)).rejects.toMatchObject({ code: 57 });- expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(0);+ await expect(write('absent')).rejects.toMatchObject({ code: 57 });+ expect(await raw().countDocuments({ principalId: ROLE })).toBe(0);},);- it('reports a failed cleanup instead of the refusal, since the created document remains', async () => {- refuseVersionedWrites();- const collection = mongoose.models.Config.collection;- jest.spyOn(collection, 'deleteOne').mockRejectedValueOnce(new Error('connection reset'));-- await expect(writes[0].write(null)).rejects.toThrow('connection reset');- expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(1);- });-- it('keeps a document another write changed before the database refused this one', async () => {- refuseVersionedWrites(async () => {- await mongoose.models.Config.updateOne(- { principalId: ROLE },- { $set: { 'overrides.webSearch.safeSearch': 2 }, $inc: { configVersion: 1 } },- );+ it('keeps a document another write created before the database refused this one', async () => {+ refuseWrites(async () => {+ await raw().insertOne({+ principalType: PrincipalType.ROLE,+ principalId: ROLE,+ principalModel: PrincipalModel.ROLE,+ priority: 10,+ isActive: true,+ configVersion: 1,+ overrides: { webSearch: { safeSearch: 2 } },+ });});- await expect(writes[0].write(null)).rejects.toMatchObject({ code: 57 });+ await expect(writes[0].write('absent')).rejects.toMatchObject({ code: 57 });expect(await readStored()).toMatchObject({configVersion: 1,overrides: { webSearch: { safeSearch: 2 } },});});- it('unsetConfigField removes a field only at the version the caller read', async () => {+ it.each(writes)(+ '$name leaves the stored document as it was when the database refuses the write',+ async ({ write }) => {+ const seeded = await seed();+ const before = await readStored();+ refuseWrites();++ await expect(write(revisionOf(seeded))).rejects.toMatchObject({ code: 57 });+ expect(await readStored()).toEqual(before);+ },+ );++ it('unsetConfigField removes a field only at the revision the caller read', async () => {const seeded = await seed();- const unset = (expectedVersion: number) =>+ const unset = (expectedRevision: string) =>methods.unsetConfigField(PrincipalType.ROLE,ROLE,'webSearch.searxngInstanceUrl',undefined,- { expectedVersion },+ { expectedRevision },);- expect(await unset(seeded.configVersion + 1)).toBeNull();+ await expect(unset(`${seeded._id}:${seeded.configVersion + 1}`)).rejects.toMatchObject({+ code: 'CONFIG_VERSION_CONFLICT',+ });expect(await readStored()).toMatchObject({overrides: { webSearch: { searxngInstanceUrl: 'https://searx.example.com' } },});- const result = await unset(seeded.configVersion);+ const result = await unset(revisionOf(seeded));expect(result!.configVersion).toBe(seeded.configVersion + 1);- expect(result!.overrides).toEqual({ webSearch: {} });+ expect(result!.overrides).toEqual({});});- it('keeps upsertConfig retrying a duplicate insert when no precondition is given', async () => {- await seed();-- const result = await methods.upsertConfig(- PrincipalType.ROLE,- ROLE,- PrincipalModel.ROLE,- { webSearch: { safeSearch: 1 } },- 10,+ it('keeps unconditioned upsertConfig calls that race to create the document', async () => {+ const results = await Promise.all(+ [1, 2].map((safeSearch) =>+ methods.upsertConfig(+ PrincipalType.ROLE,+ ROLE,+ PrincipalModel.ROLE,+ { webSearch: { safeSearch } },+ 10,+ ),+ ),);- expect(result!.overrides).toEqual({ webSearch: { safeSearch: 1 } });+ expect(results.map((result) => result!.configVersion).sort()).toEqual([1, 2]);+ expect(await raw().countDocuments({ principalId: ROLE })).toBe(1);+ const stored = await methods.findConfigByPrincipal(PrincipalType.ROLE, ROLE);+ expect(stored!.configVersion).toBe(2);});});diff --git a/packages/data-schemas/src/methods/config.ts b/packages/data-schemas/src/methods/config.tsindex 6e0c046fde..2813bc2721 100644--- a/packages/data-schemas/src/methods/config.ts+++ b/packages/data-schemas/src/methods/config.ts@@ -1,535 +1,476 @@import { Types } from 'mongoose';-import { PrincipalType, PrincipalModel } from 'librechat-data-provider';-import type { FilterQuery, UpdateQuery, Model, ClientSession } from 'mongoose';-import type { TCustomConfig } from 'librechat-data-provider';-import type { IConfig, ConfigWritePrecondition } from '~/types';-import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';-import { escapeRegExp } from '~/utils/string';--/** Tombstones a field write clears: the written path and its ancestors below the section. */-export function getTombstonePathsToClear(fieldPath: string): string[] {- const parts = fieldPath.split('.');- if (parts.length <= 1) {- return [fieldPath];+import type { PrincipalType, PrincipalModel, TCustomConfig } from 'librechat-data-provider';+import type { Model } from 'mongoose';+import type {+ ConfigDraft,+ ConfigStore,+ ConfigRecord,+ ConfigRevision,+ ConfigPrincipal,+ ConfigPathInputs,+ ConfigWriteOptions,+ ConfigLifecycleOptions,+} from '~/app/store';+import type { StoredKeyForm } from './encoding';+import type { IConfig } from '~/types';+import {+ ABSENT_CONFIG_REVISION,+ ConfigRevisionConflictError,+ createConfigOperations,+ getConfigRevision,+ parseConfigRevision,+} from '~/app/store';+import {+ toStoredKeys,+ readStoredKeys,+ getStoredKeyForms,+ CONFIG_KEY_ENCODING_VERSION,+} from './encoding';+import { isFieldNameRejection } from '~/utils/fields';+import logger from '~/config/winston';++/** A config document as MongoDB returns it, before the binding decodes it. */+interface StoredConfig {+ _id: Types.ObjectId | string;+ principalType: PrincipalType;+ principalId: Types.ObjectId | string;+ principalModel: PrincipalModel;+ priority: number;+ overrides?: Partial<TCustomConfig>;+ tombstones?: string[];+ isActive?: boolean;+ configVersion?: number | null;+ keyEncoding?: number;+ tenantId?: string;+ createdAt?: Date;+ updatedAt?: Date;+}++/** Engine order for {@link ConfigStore.list}: ascending priority, then identity. */+const STORE_ORDER = { priority: 1, _id: 1 } as const;++function toRecord(document: StoredConfig): ConfigRecord {+ const overrides = document.overrides ?? {};+ const record: ConfigRecord = {+ _id: document._id.toString(),+ principalType: document.principalType,+ principalId: document.principalId.toString(),+ principalModel: document.principalModel,+ priority: document.priority,+ overrides: readStoredKeys(overrides, document.keyEncoding === CONFIG_KEY_ENCODING_VERSION),+ tombstones: Array.isArray(document.tombstones) ? document.tombstones : [],+ isActive: document.isActive === true,+ configVersion: document.configVersion ?? 0,+ };+ if (document.tenantId != null) {+ record.tenantId = document.tenantId;+ }+ if (document.createdAt != null) {+ record.createdAt = document.createdAt;}- return parts.slice(1).map((_, index) => parts.slice(0, index + 2).join('.'));+ if (document.updatedAt != null) {+ record.updatedAt = document.updatedAt;+ }+ return record;+}++function principalFilter(principal: ConfigPrincipal): ConfigPrincipal {+ return { principalType: principal.principalType, principalId: principal.principalId };}-function getPathAndDescendantsRegex(fieldPath: string): RegExp {- return new RegExp(`^${escapeRegExp(fieldPath)}(?:\\.|$)`);+/** A legacy document may predate `configVersion`; version 0 matches it too. */+function versionFilter(configVersion: number): number | { $in: Array<number | null> } {+ return configVersion === 0 ? { $in: [0, null] } : configVersion;+}++function toObjectId(id: unknown): unknown {+ if (id instanceof Types.ObjectId) {+ return id;+ }+ return typeof id === 'string' && Types.ObjectId.isValid(id) ? new Types.ObjectId(id) : id;}function isDuplicateKeyError(error: unknown): boolean {- return (error as { code?: number } | null)?.code === 11000;+ return (error as { code?: unknown } | null)?.code === 11000;}-export function createConfigMethods(mongoose: typeof import('mongoose')): {- listAllConfigs: (filter?: { isActive?: boolean }, session?: ClientSession) => Promise<IConfig[]>;- findConfigByPrincipal: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- options?: { includeInactive?: boolean },- session?: ClientSession,- ) => Promise<IConfig | null>;- getApplicableConfigs: (- principals?: Array<{ principalType: string; principalId?: string | Types.ObjectId }>,- session?: ClientSession,- ) => Promise<IConfig[]>;- upsertConfig: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,+/** The filter that pins a document revision, or `null` when the revision can never match. */+function revisionFilter(+ principal: ConfigPrincipal,+ revision: ConfigRevision,+): Record<string, unknown> | null {+ const parsed = parseConfigRevision(revision);+ if (!parsed || !Types.ObjectId.isValid(parsed.id)) {+ return null;+ }+ return {+ ...principalFilter(principal),+ _id: new Types.ObjectId(parsed.id),+ configVersion: versionFilter(parsed.configVersion),+ };+}++/** Override keys in the form one write stores them, and whether that form carries the marker. */+interface StoredKeys {+ overrides: Partial<TCustomConfig>;+ encoded: boolean;+}++/**+ * The Mongoose engine for the portable config store. Override keys are stored raw where the+ * engine accepts them and encoded where it refuses them (see `./encoding`), and every read+ * decodes them. Queries run through the `Config` model, so the tenant-isolation plugin scopes+ * every read and write.+ */+export function createConfigStore(mongoose: typeof import('mongoose')): ConfigStore {+ const model = () => mongoose.models.Config as Model<IConfig>;+ /** Set once the engine refuses a raw key name, so later writes encode without asking again. */+ let refusesRawKeys = false;++ /**+ * Runs `write` with the overrides raw, or encoded when a raw read could not return them+ * unchanged. When the engine refuses a raw key name, the refused write changed nothing, so it+ * runs once more encoded, under the same precondition.+ */+ async function storeKeys<T>(overrides: Partial<TCustomConfig>,- priority: number,- session?: ClientSession,- options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,- ) => Promise<IConfig | null>;- patchConfigFields: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- fields: Record<string, unknown>,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;- tombstoneConfigField: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- fieldPath: string,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;- unsetConfigField: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- fieldPath: string,- session?: ClientSession,- options?: ConfigWritePrecondition,- ) => Promise<IConfig | null>;- deleteConfig: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- session?: ClientSession,- options?: { expectEmpty?: boolean },- ) => Promise<IConfig | null>;- restoreConfig: (snapshot: Record<string, unknown>) => Promise<boolean>;- toggleConfigActive: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- isActive: boolean,- session?: ClientSession,- options?: { expectEmpty?: boolean },- ) => Promise<IConfig | null>;- /** Like `toggleConfigActive`, but also reports whether this write changed `isActive`. */- toggleConfigActiveTracked: (- principalType: PrincipalType,- principalId: string | Types.ObjectId,- isActive: boolean,- options?: { expectEmpty?: boolean },- ) => Promise<{ config: IConfig; changed: boolean } | null>;-} {- async function findConfigByPrincipal(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- options?: { includeInactive?: boolean },- session?: ClientSession,- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const filter: { principalType: PrincipalType; principalId: string; isActive?: boolean } = {- principalType,- principalId: principalId.toString(),- };- if (!options?.includeInactive) {- filter.isActive = true;+ write: (keys: StoredKeys) => Promise<T>,+ ): Promise<T> {+ const [form, fallback] = getStoredKeyForms(overrides, refusesRawKeys);+ const run = (next: StoredKeyForm) =>+ write({ overrides: toStoredKeys(overrides, next), encoded: next === 'encoded' });+ try {+ return await run(form);+ } catch (error) {+ if (!fallback || !isFieldNameRejection(error)) {+ throw error;+ }+ refusesRawKeys = true;+ logger.warn(+ '[configStore] The database refused a raw key name in config overrides; storing override keys encoded from now on',+ );+ return run(fallback);}- return await Config.findOne(filter)- .session(session ?? null)- .lean<IConfig>();}- async function listAllConfigs(- filter?: { isActive?: boolean },- session?: ClientSession,- ): Promise<IConfig[]> {- const Config = mongoose.models.Config as Model<IConfig>;+ async function read(principal: ConfigPrincipal): Promise<ConfigRecord | null> {+ const document = await model().findOne(principalFilter(principal)).lean<StoredConfig>();+ return document ? toRecord(document) : null;+ }++ async function list(filter?: { isActive?: boolean }): Promise<ConfigRecord[]> {const where: { isActive?: boolean } = {};if (filter?.isActive !== undefined) {where.isActive = filter.isActive;}- return await Config.find(where)- .sort({ priority: 1 })- .session(session ?? null)- .lean<IConfig[]>();+ const documents = await model().find(where).sort(STORE_ORDER).lean<StoredConfig[]>();+ return documents.map(toRecord);}- async function getApplicableConfigs(- principals?: Array<{ principalType: string; principalId?: string | Types.ObjectId }>,- session?: ClientSession,- ): Promise<IConfig[]> {- const Config = mongoose.models.Config as Model<IConfig>;-- const basePrincipal = {- principalType: PrincipalType.ROLE as string,- principalId: BASE_CONFIG_PRINCIPAL_ID,- };-- const principalsQuery = [basePrincipal];-- if (principals && principals.length > 0) {- for (const p of principals) {- if (p.principalId !== undefined) {- principalsQuery.push({- principalType: p.principalType,- principalId: p.principalId.toString(),- });- }- }+ async function listActive(principals: readonly ConfigPrincipal[]): Promise<ConfigRecord[]> {+ if (principals.length === 0) {+ return [];}-- return await Config.find({- $or: principalsQuery,- isActive: true,- })- .sort({ priority: 1 })- .session(session ?? null)- .lean<IConfig[]>();+ const documents = await model()+ .find({ $or: principals.map(principalFilter), isActive: true })+ .sort(STORE_ORDER)+ .lean<StoredConfig[]>();+ return documents.map(toRecord);}/**- * The filter a write with a version precondition applies to, or `null` when- * the precondition no longer holds. A caller that saw no document gets an- * empty one created first, at version 0, so its write cannot land on a- * document another writer created after the read.+ * Inserts the principal's document only when it has none. An existing document matches the+ * principal filter, `$setOnInsert` leaves it untouched, and the `_id` it returns is not the one+ * offered, so the conflict is seen without relying on the unique principal index (which some+ * engines, such as DocumentDB elastic clusters, do not enforce); the index still turns two+ * racing inserts into a duplicate-key conflict. Timestamps are set here because Mongoose would+ * otherwise `$set` `updatedAt` on the document it found.*/- async function getPreconditionFilter(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- onInsert: { principalModel: PrincipalModel; priority: number },- expectedVersion: number | null,- session?: ClientSession,- ): Promise<FilterQuery<IConfig> | null> {- const filter = { principalType, principalId: principalId.toString() };- if (expectedVersion != null) {- return { ...filter, configVersion: expectedVersion };- }- const Config = mongoose.models.Config as Model<IConfig>;+ async function create(+ principal: ConfigPrincipal,+ fields: Record<string, unknown>,+ ): Promise<ConfigRecord> {+ const _id = new Types.ObjectId();const now = new Date();try {- /** Timestamps are written on insert only, so a document that already exists is left untouched. */- const result = await Config.findOneAndUpdate(- filter,- { $setOnInsert: { ...onInsert, createdAt: now, updatedAt: now } },- {- upsert: true,- new: true,- timestamps: false,- setDefaultsOnInsert: true,- includeResultMetadata: true,- ...(session ? { session } : {}),- },- );- if (result.value == null || result.lastErrorObject?.updatedExisting === true) {- return null;+ const document = await model()+ .findOneAndUpdate(+ principalFilter(principal),+ {+ $setOnInsert: { ...fields, _id, configVersion: 1, createdAt: now, updatedAt: now },+ },+ { upsert: true, new: true, timestamps: false, setDefaultsOnInsert: true },+ )+ .lean<StoredConfig>();+ if (!document) {+ throw new ConfigRevisionConflictError();}- return { ...filter, configVersion: result.value.configVersion };- } catch (error) {- if (isDuplicateKeyError(error)) {- return null;+ const record = toRecord(document);+ if (record._id !== _id.toString()) {+ throw new ConfigRevisionConflictError(getConfigRevision(record));}- throw error;- }- }-- /** Applies `update` only to the document version the caller read; `null` once it no longer matches. */- async function updateAtVersion(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- onInsert: { principalModel: PrincipalModel; priority: number },- expectedVersion: number | null,- update: UpdateQuery<IConfig>,- session?: ClientSession,- ): Promise<IConfig | null> {- const filter = await getPreconditionFilter(- principalType,- principalId,- onInsert,- expectedVersion,- session,- );- if (filter == null) {- return null;- }- const Config = mongoose.models.Config as Model<IConfig>;- const sessionOption = session ? { session } : {};- try {- return await Config.findOneAndUpdate(filter, update, { new: true, ...sessionOption });+ return record;} catch (error) {- if (expectedVersion === null) {- /**- * Removes the empty document created above, so a write the database refused (such as a- * key name the engine cannot store) stores nothing. The filter carries the created- * version, so a document another write has since changed stays. A failure here- * replaces the refusal: the caller must not report that nothing was stored.- */- await Config.deleteOne(filter, sessionOption);+ if (isDuplicateKeyError(error)) {+ throw new ConfigRevisionConflictError();}throw error;}}- async function upsertConfig(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- overrides: Partial<TCustomConfig>,- priority: number,- session?: ClientSession,- options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const expectedVersion = options?.expectedVersion;-- const update = {- $set: {- principalModel,- overrides,- ...(options?.preservePriority ? {} : { priority }),- isActive: true,- },- ...(options?.preservePriority ? { $setOnInsert: { priority } } : {}),- $inc: { configVersion: 1 },- };-- if (expectedVersion !== undefined) {- return await updateAtVersion(- principalType,- principalId,- { principalModel, priority },- expectedVersion,- update,- session,- );+ async function write(+ principal: ConfigPrincipal,+ draft: ConfigDraft,+ expected: ConfigRevision,+ ): Promise<ConfigRecord> {+ const fields = (keys: StoredKeys): Record<string, unknown> => ({+ principalModel: draft.principalModel,+ priority: draft.priority,+ overrides: keys.overrides,+ tombstones: [...draft.tombstones],+ isActive: draft.isActive,+ ...(keys.encoded ? { keyEncoding: CONFIG_KEY_ENCODING_VERSION } : {}),+ });+ if (expected === ABSENT_CONFIG_REVISION) {+ return storeKeys(draft.overrides ?? {}, (keys) => create(principal, fields(keys)));}-- const query: FilterQuery<IConfig> = {- principalType,- principalId: principalId.toString(),- };- if (options?.expectEmpty) {- query.$and = [- { $or: [{ overrides: { $eq: {} } }, { overrides: { $exists: false } }] },- { $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },- ];+ const filter = revisionFilter(principal, expected);+ if (!filter) {+ throw new ConfigRevisionConflictError();}-- const mongoOptions = {- upsert: true,- new: true,- setDefaultsOnInsert: true,- ...(session ? { session } : {}),- };-- try {- return await Config.findOneAndUpdate(query, update, mongoOptions);- } catch (err: unknown) {- if (isDuplicateKeyError(err)) {- if (options?.expectEmpty) {- return null;- }- return await Config.findOneAndUpdate(- { principalType, principalId: principalId.toString() },- { $set: update.$set, $inc: update.$inc },- { new: true, ...(session ? { session } : {}) },- );- }- throw err;+ const configVersion = (parseConfigRevision(expected)?.configVersion ?? 0) + 1;+ const updated = await storeKeys(draft.overrides ?? {}, (keys) =>+ model()+ .findOneAndUpdate(+ filter,+ {+ $set: { ...fields(keys), configVersion },+ /** A raw write clears a marker an earlier encoded write left. */+ ...(keys.encoded ? {} : { $unset: { keyEncoding: '' } }),+ },+ { new: true },+ )+ .lean<StoredConfig>(),+ );+ if (!updated) {+ throw new ConfigRevisionConflictError();}+ return toRecord(updated);}- async function patchConfigFields(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- fields: Record<string, unknown>,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const expectedVersion = options?.expectedVersion;-- const setPayload: { principalModel: PrincipalModel; priority: number; [key: string]: unknown } =- {- principalModel,- priority,- };-- for (const [path, value] of Object.entries(fields)) {- setPayload[`overrides.${path}`] = value;+ async function remove(+ principal: ConfigPrincipal,+ expected?: ConfigRevision,+ ): Promise<ConfigRecord | null> {+ if (expected === undefined) {+ const deleted = await model()+ .findOneAndDelete(principalFilter(principal))+ .lean<StoredConfig>();+ return deleted ? toRecord(deleted) : null;}-- const tombstonesToClear = [...new Set(Object.keys(fields).flatMap(getTombstonePathsToClear))];-- const update: Record<string, unknown> = {- $set: setPayload,- $inc: { configVersion: 1 },- };- if (tombstonesToClear.length > 0) {- update.$pull = { tombstones: { $in: tombstonesToClear } };- }-- if (expectedVersion !== undefined) {- return await updateAtVersion(- principalType,- principalId,- { principalModel, priority },- expectedVersion,- update,- session,- );+ if (expected === ABSENT_CONFIG_REVISION) {+ const current = await read(principal);+ if (current) {+ throw new ConfigRevisionConflictError(getConfigRevision(current));+ }+ return null;}-- return await Config.findOneAndUpdate(- { principalType, principalId: principalId.toString() },- update,- { upsert: true, new: true, setDefaultsOnInsert: true, ...(session ? { session } : {}) },- );- }-- async function tombstoneConfigField(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- principalModel: PrincipalModel,- fieldPath: string,- priority: number,- session?: ClientSession,- options?: ConfigWritePrecondition,- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const expectedVersion = options?.expectedVersion;-- const update = {- $set: {- principalModel,- priority,- },- $unset: { [`overrides.${fieldPath}`]: '' },- $addToSet: { tombstones: fieldPath },- $inc: { configVersion: 1 },- };-- if (expectedVersion !== undefined) {- return await updateAtVersion(- principalType,- principalId,- { principalModel, priority },- expectedVersion,- update,- session,- );+ const filter = revisionFilter(principal, expected);+ const deleted = filter ? await model().findOneAndDelete(filter).lean<StoredConfig>() : null;+ if (!deleted) {+ throw new ConfigRevisionConflictError();}-- return await Config.findOneAndUpdate(- { principalType, principalId: principalId.toString() },- update,- { upsert: true, new: true, setDefaultsOnInsert: true, ...(session ? { session } : {}) },- );+ return toRecord(deleted);}- async function unsetConfigField(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- fieldPath: string,- session?: ClientSession,- options?: ConfigWritePrecondition,- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const expectedVersion = options?.expectedVersion;- if (expectedVersion === null) {- return null;- }-- return await Config.findOneAndUpdate(- {- principalType,- principalId: principalId.toString(),- ...(expectedVersion !== undefined ? { configVersion: expectedVersion } : {}),- },- {- $unset: { [`overrides.${fieldPath}`]: '' },- $pull: { tombstones: { $regex: getPathAndDescendantsRegex(fieldPath) } },- $inc: { configVersion: 1 },- },- { new: true, ...(session ? { session } : {}) },+ /** `snapshot` is a decoded record, as `read` and `remove` return it; it is stored like a write. */+ async function restore(snapshot: ConfigRecord): Promise<boolean> {+ const { _id, overrides, ...rest } = snapshot;+ const principalId = snapshot.principalId.toString();+ const result = await storeKeys(overrides ?? {}, (keys) =>+ model().updateOne(+ { principalType: snapshot.principalType, principalId },+ {+ $setOnInsert: {+ ...rest,+ principalId,+ _id: toObjectId(_id),+ overrides: keys.overrides,+ ...(keys.encoded ? { keyEncoding: CONFIG_KEY_ENCODING_VERSION } : {}),+ },+ },+ { upsert: true, timestamps: false },+ ),);+ return result.upsertedCount > 0;}- async function deleteConfig(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- session?: ClientSession,- options?: { expectEmpty?: boolean },- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- const filter: FilterQuery<IConfig> = {- principalType,- principalId: principalId.toString(),- };- if (options?.expectEmpty) {- filter.$and = [- { $or: [{ overrides: { $eq: {} } }, { overrides: { $exists: false } }] },- { $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },- ];- }- return await Config.findOneAndDelete(filter).session(session ?? null);- }+ return { read, list, listActive, write, remove, restore };+}- function toggleFilter(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- options?: { expectEmpty?: boolean },- extra: FilterQuery<IConfig> = {},- ): FilterQuery<IConfig> {- const filter: FilterQuery<IConfig> = {- principalType,- principalId: principalId.toString(),- ...extra,- };- if (options?.expectEmpty) {- filter.$and = [- { $or: [{ overrides: { $eq: {} } }, { overrides: { $exists: false } }] },- { $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },- ];- }- return filter;- }+type ConfigPrincipalId = string | Types.ObjectId;- async function toggleConfigActive(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- isActive: boolean,- session?: ClientSession,- options?: { expectEmpty?: boolean },- ): Promise<IConfig | null> {- const Config = mongoose.models.Config as Model<IConfig>;- return await Config.findOneAndUpdate(- toggleFilter(principalType, principalId, options),- { $set: { isActive } },- { new: true, ...(session ? { session } : {}) },- );- }+/**+ * Positional slot where these methods once took a Mongoose `ClientSession`. The portable store+ * does not join transactions, so only `undefined` is accepted; the slot stays so existing call+ * sites keep their argument positions.+ */+type NoSession = undefined;- async function toggleConfigActiveTracked(- principalType: PrincipalType,- principalId: string | Types.ObjectId,- isActive: boolean,- options?: { expectEmpty?: boolean },- ): Promise<{ config: IConfig; changed: boolean } | null> {- const Config = mongoose.models.Config as Model<IConfig>;- /** The filter matches only a document that differs, so a match is exactly one real change. */- const changed = await Config.findOneAndUpdate(- toggleFilter(principalType, principalId, options, { isActive: { $ne: isActive } }),- { $set: { isActive } },- { new: true },- );- if (changed) {- return { config: changed, changed: true };- }- const current = await Config.findOne(toggleFilter(principalType, principalId, options));- return current ? { config: current, changed: false } : null;- }+function toPrincipal(+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+): ConfigPrincipal {+ return { principalType, principalId: principalId.toString() };+}- /**- * Re-creates a deleted config document exactly as it was (tombstones, active flag,- * version), only when no document exists for the principal. Returns whether it- * inserted, so a document written after the snapshot is never overwritten.- */- async function restoreConfig(snapshot: Record<string, unknown>): Promise<boolean> {- const Config = mongoose.models.Config as Model<IConfig>;- const { principalType, principalId } = snapshot;- const result = await Config.updateOne(- { principalType, principalId },- { $setOnInsert: snapshot },- { upsert: true, timestamps: false },- );- return result.upsertedCount > 0;- }+/**+ * Config methods for callers, backed by the Mongoose store. Every write reads the document,+ * applies a pure transform and stores it with one compare-and-swap; a concurrent write is+ * re-read and re-applied, and `expectedRevision` turns any mismatch into a+ * `ConfigRevisionConflictError`.+ */+export function createConfigMethods(mongoose: typeof import('mongoose')) {+ const store = createConfigStore(mongoose);+ const operations = createConfigOperations(store);return {- listAllConfigs,- findConfigByPrincipal,- getApplicableConfigs,- upsertConfig,- patchConfigFields,- tombstoneConfigField,- unsetConfigField,- deleteConfig,- restoreConfig,- toggleConfigActive,- toggleConfigActiveTracked,+ listAllConfigs: (+ filter?: { isActive?: boolean },+ _session?: NoSession,+ ): Promise<ConfigRecord[]> => store.list(filter),++ findConfigByPrincipal: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ options?: { includeInactive?: boolean },+ _session?: NoSession,+ ): Promise<ConfigRecord | null> =>+ operations.findConfig(toPrincipal(principalType, principalId), options),++ getApplicableConfigs: (+ principals?: Array<{ principalType: string; principalId?: ConfigPrincipalId }>,+ _session?: NoSession,+ ): Promise<ConfigRecord[]> => operations.getApplicableConfigs(principals),++ /** Replaces the overrides whole and activates the document; tombstones stay. */+ upsertConfig: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ principalModel: PrincipalModel,+ overrides: Partial<TCustomConfig>,+ priority: number,+ _session?: NoSession,+ options?: ConfigLifecycleOptions & { preservePriority?: boolean },+ ): Promise<ConfigRecord | null> =>+ operations.replaceOverrides(+ toPrincipal(principalType, principalId),+ principalModel,+ overrides,+ priority,+ options,+ ),++ /** Sets dotted field paths; an omitted `priority` keeps the stored one. */+ patchConfigFields: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ principalModel: PrincipalModel,+ fields: Record<string, unknown>,+ priority?: number,+ _session?: NoSession,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord> =>+ operations.setFields(+ toPrincipal(principalType, principalId),+ principalModel,+ fields,+ priority,+ options,+ ),++ /** Tombstones one path, or several in one write; an omitted `priority` keeps the stored one. */+ tombstoneConfigField: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ principalModel: PrincipalModel,+ fieldPaths: ConfigPathInputs,+ priority?: number,+ _session?: NoSession,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord> =>+ operations.tombstoneFields(+ toPrincipal(principalType, principalId),+ principalModel,+ fieldPaths,+ priority,+ options,+ ),++ /**+ * Removes one path, or several in one write, pruning the parents left empty. A path is a+ * dotted field path or `{ segments }`, which can name a key that contains a dot.+ */+ unsetConfigField: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ fieldPaths: ConfigPathInputs,+ _session?: NoSession,+ options?: ConfigWriteOptions,+ ): Promise<ConfigRecord | null> =>+ operations.unsetFields(toPrincipal(principalType, principalId), fieldPaths, options),++ deleteConfig: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ _session?: NoSession,+ options?: ConfigLifecycleOptions,+ ): Promise<ConfigRecord | null> =>+ operations.deleteConfig(toPrincipal(principalType, principalId), options),++ /**+ * Re-creates a deleted config document exactly as it was (tombstones, active flag,+ * version), only when no document exists for the principal. Returns whether it+ * inserted, so a document written after the snapshot is never overwritten.+ */+ restoreConfig: (snapshot: ConfigRecord): Promise<boolean> => store.restore(snapshot),++ toggleConfigActive: async (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ isActive: boolean,+ _session?: NoSession,+ options?: ConfigLifecycleOptions,+ ): Promise<ConfigRecord | null> => {+ const toggled = await operations.setActive(+ toPrincipal(principalType, principalId),+ isActive,+ options,+ );+ return toggled?.config ?? null;+ },++ /** Like `toggleConfigActive`, but also reports whether this write changed `isActive`. */+ toggleConfigActiveTracked: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ isActive: boolean,+ options?: ConfigLifecycleOptions,+ ): Promise<{ config: ConfigRecord; changed: boolean } | null> =>+ operations.setActive(toPrincipal(principalType, principalId), isActive, options),++ /**+ * Writes a principal's whole document when it is still at `expected` (`absent`: only when+ * none exists). The admin API plans the next document from the one it read, so validation+ * and secret preservation see exactly what the write replaces.+ */+ writeConfigDocument: (+ principalType: PrincipalType,+ principalId: ConfigPrincipalId,+ draft: ConfigDraft,+ expected: ConfigRevision,+ ): Promise<ConfigRecord> =>+ store.write(toPrincipal(principalType, principalId), draft, expected),};}diff --git a/packages/data-schemas/src/methods/encoding.spec.ts b/packages/data-schemas/src/methods/encoding.spec.tsnew file mode 100644index 0000000000..a4b9225e1a--- /dev/null+++ b/packages/data-schemas/src/methods/encoding.spec.ts@@ -0,0 +1,141 @@+import { runInNewContext } from 'vm';+import {+ toStoredKeys,+ readStoredKeys,+ decodeStoredKey,+ encodeStoredKey,+ decodeStoredKeys,+ encodeStoredKeys,+ getStoredKeyForms,+} from './encoding';++const NUL = String.fromCharCode(0);++describe('config key encoding', () => {+ it.each([+ ['gpt-4.1', 'gpt-4%2E1'],+ ['$set', '%24set'],+ ['price$', 'price%24'],+ ['%', '%25'],+ ['%2E', '%252E'],+ ['%25', '%2525'],+ ['a.b$c%d', 'a%2Eb%24c%25d'],+ [`nul${NUL}key`, 'nul%00key'],+ ['模型.名称', '模型%2E名称'],+ ['plain', 'plain'],+ ])('encodes %j as %j and back', (key, encoded) => {+ expect(encodeStoredKey(key)).toBe(encoded);+ expect(decodeStoredKey(encoded)).toBe(key);+ });++ it('never emits a dot, a dollar sign or NUL', () => {+ const keys = ['.', '..', '$', '$$.$', `${NUL}.$%`];++ for (const key of keys) {+ expect(encodeStoredKey(key)).not.toMatch(/[.$]/);+ expect(encodeStoredKey(key)).not.toContain(NUL);+ expect(decodeStoredKey(encodeStoredKey(key))).toBe(key);+ }+ });++ it('decodes keys without escape sequences unchanged, including unknown `%` sequences', () => {+ for (const key of ['plain', 'gpt-4.1', '100%', '%2e', '%41', '%']) {+ expect(decodeStoredKey(key)).toBe(key);+ }+ });++ it('encodes keys at every depth, inside arrays, and never values', () => {+ const value = {+ 'a.b': [{ $c: 'd.e', list: ['$x', { 'f.g': null }] }],+ nested: { deeper: { 'h.i': '%2E' } },+ };++ const encoded = encodeStoredKeys(value);++ expect(encoded).toEqual({+ 'a%2Eb': [{ '%24c': 'd.e', list: ['$x', { 'f%2Eg': null }] }],+ nested: { deeper: { 'h%2Ei': '%2E' } },+ });+ expect(decodeStoredKeys(encoded)).toEqual(value);+ });++ it('returns untouched containers as they are and follows JSON for undefined', () => {+ const plain = { a: { b: [1, { c: 2 }] } };++ expect(encodeStoredKeys(plain)).toBe(plain);+ expect(encodeStoredKeys({ a: undefined, b: [undefined, 1] })).toEqual({ b: [null, 1] });+ });++ it('leaves non-plain objects such as dates alone', () => {+ const date = new Date(0);++ expect(encodeStoredKeys({ 'a.b': date })).toEqual({ 'a%2Eb': date });+ });++ it('encodes objects built in another realm', () => {+ const foreign = runInNewContext('({ groups: [{ models: { "gpt-4.1": true } }] })');++ expect(JSON.stringify(encodeStoredKeys({ endpoints: foreign }))).toBe(+ JSON.stringify({ endpoints: { groups: [{ models: { 'gpt-4%2E1': true } }] } }),+ );+ });++ describe('the form a write stores', () => {+ it.each([+ ['plain keys', { a: { b: 1 } }, ['raw']],+ ['a `%` that spells no escape sequence', { headers: { '100%': 1 } }, ['raw']],+ ['a dotted key', { models: { 'gpt-4.1': true } }, ['raw', 'encoded']],+ ['a `$` key', { $top: 1 }, ['raw', 'encoded']],+ ['a dotted key beside an escape-like one', { 'a.b': 1, 'c%2Ed': 2 }, ['raw', 'encoded']],+ ['escape-like keys and no raw-only key', { headers: { 'X%2E': 1 } }, ['encoded']],+ ])('writes %s as %j', (_label, value, forms) => {+ expect(getStoredKeyForms(value, false)).toEqual(forms);+ });++ it('skips the raw attempt once the engine has refused one', () => {+ expect(getStoredKeyForms({ 'gpt-4.1': true }, true)).toEqual(['encoded']);+ expect(getStoredKeyForms({ plain: true }, true)).toEqual(['raw']);+ });++ it('reads back every form it writes, marked only when encoded', () => {+ const values = [+ { a: { b: 1 } },+ { headers: { '100%': 1 } },+ { models: { 'gpt-4.1': true }, $top: { 'x.y': '%2E' } },+ { 'a.b': 1, 'c%2Ed': 2 },+ { headers: { 'X%2E': 1, 'Y%25': 2 } },+ ];+ for (const value of values) {+ for (const form of getStoredKeyForms(value, false)) {+ const stored = toStoredKeys(value, form);+ expect(readStoredKeys(stored, form === 'encoded')).toEqual(value);+ }+ }+ });+ });++ describe('reading a stored document', () => {+ it('decodes a marked document, leaving raw keys an older writer added', () => {+ expect(readStoredKeys({ 'gpt-4%2E1': 1, 'raw.key': 2, plain: 3 }, true)).toEqual({+ 'gpt-4.1': 1,+ 'raw.key': 2,+ plain: 3,+ });+ });++ it('decodes an unmarked document that holds no raw-only key, as one whose marker was dropped', () => {+ expect(readStoredKeys({ 'us%2Eanthropic': 1, '%24top': 2 }, false)).toEqual({+ 'us.anthropic': 1,+ $top: 2,+ });+ });++ it('reads an unmarked document with a raw dotted or `$` key verbatim', () => {+ const raw = { 'gpt-4.1': 1, 'literal%2Ekey': 2 };+ const dollar = { $top: { 'literal%24': 1 } };++ expect(readStoredKeys(raw, false)).toBe(raw);+ expect(readStoredKeys(dollar, false)).toBe(dollar);+ });+ });+});diff --git a/packages/data-schemas/src/methods/encoding.ts b/packages/data-schemas/src/methods/encoding.tsnew file mode 100644index 0000000000..ce7236a861--- /dev/null+++ b/packages/data-schemas/src/methods/encoding.ts@@ -0,0 +1,175 @@+/**+ * Reversible object-key encoding for config overrides stored through Mongoose.+ *+ * MongoDB-compatible engines disagree about field names: MongoDB 4.4+ stores a dotted name+ * inside a document (5.0+ also a `$`-prefixed one), while DocumentDB, Cosmos DB, FerretDB and+ * older MongoDB may refuse them. The encoding keeps a refusing engine from ever storing one:+ * `%`, `.`, `$` and NUL are percent-escaped wherever they appear in a key, and nothing else+ * changes. Values are never touched. A PostgreSQL/JSONB engine stores plain JSON and needs+ * none of this, which is why it lives in the Mongoose binding only.+ *+ * Keys are written raw whenever the engine stores them and a raw read returns them unchanged,+ * so servers that predate the encoding (and read every key literally) keep reading what they+ * wrote during a rolling upgrade. A document is written encoded, with the marker, only when+ * the engine refused a raw key name, or when its keys look like escape sequences while none+ * holds a raw `.`, `$` or NUL (a raw read would decode them).+ *+ * Reads decode a marked document, including raw keys an older server added to it or a raw+ * replacement it wrote under a stale marker: the decoder only rewrites the four sequences this+ * module emits, so a raw key without one is unchanged. An unmarked document is decoded unless+ * some key holds a raw `.`, `$` or NUL, which no encoded document contains; that reads an+ * encoded document whose marker an older server dropped (its schema lacks the field), and+ * reads every raw document as stored. The one key such a reading can misread is a raw key+ * that literally spells `%25`, `%2E`, `%24` or `%00` in a document with no dotted key.+ */++/** Stored on a config document whose override keys are encoded. */+export const CONFIG_KEY_ENCODING_VERSION = 1;++const NUL = String.fromCharCode(0);++const ENCODED: Readonly<Record<string, string>> = {+ '%': '%25',+ '.': '%2E',+ $: '%24',+};++const DECODED: Readonly<Record<string, string>> = {+ '%25': '%',+ '%2E': '.',+ '%24': '$',+ '%00': NUL,+};++const ENCODE_PATTERN = /[%.$]/g;+const DECODE_PATTERN = /%(?:25|2E|24|00)/g;+/** A character only an unencoded key holds: the encoding escapes every one of them. */+const RAW_ONLY_PATTERN = /[.$\0]/;+const ESCAPE_PATTERN = /%(?:25|2E|24|00)/;++/** `%` is escaped first, so the `%` an escape introduces is never escaped again. */+export function encodeStoredKey(key: string): string {+ const escaped = key.replace(ENCODE_PATTERN, (character) => ENCODED[character]);+ return escaped.includes(NUL) ? escaped.split(NUL).join('%00') : escaped;+}++export function decodeStoredKey(key: string): string {+ return key.includes('%') ? key.replace(DECODE_PATTERN, (sequence) => DECODED[sequence]) : key;+}++/**+ * A JSON-style object: its prototype is `null` or a root `Object.prototype`, from any realm.+ * Comparing with this realm's `Object.prototype` would skip an object built in another one+ * (`structuredClone` under Jest returns the host realm's objects), and a skipped object keeps+ * its dotted keys raw at rest.+ */+function isPlainObject(value: unknown): value is Record<string, unknown> {+ if (value == null || typeof value !== 'object' || Array.isArray(value)) {+ return false;+ }+ const prototype = Object.getPrototypeOf(value);+ return prototype === null || Object.getPrototypeOf(prototype) === null;+}++/**+ * Rewrites every key of every plain object below `value`, keeping JSON semantics: an+ * `undefined` property is dropped and an `undefined` array element becomes `null`. Containers+ * nothing changed in are returned as they are.+ */+function mapKeys(value: unknown, mapKey: (key: string) => string): unknown {+ if (Array.isArray(value)) {+ let changed = false;+ const next = value.map((item) => {+ const mapped = item === undefined ? null : mapKeys(item, mapKey);+ changed ||= mapped !== item;+ return mapped;+ });+ return changed ? next : value;+ }+ if (!isPlainObject(value)) {+ return value;+ }+ let changed = false;+ const entries: Array<[string, unknown]> = [];+ for (const [key, child] of Object.entries(value)) {+ if (child === undefined) {+ changed = true;+ continue;+ }+ const nextKey = mapKey(key);+ const nextChild = mapKeys(child, mapKey);+ changed ||= nextKey !== key || nextChild !== child;+ entries.push([nextKey, nextChild]);+ }+ return changed ? Object.fromEntries(entries) : value;+}++/** Encodes every key below `value` for storage. */+export function encodeStoredKeys<T>(value: T): T {+ return mapKeys(value, encodeStoredKey) as T;+}++/** Decodes every key below `value` that {@link encodeStoredKeys} wrote. */+export function decodeStoredKeys<T>(value: T): T {+ return mapKeys(value, decodeStoredKey) as T;+}++/** Decodes nothing; applies the same JSON rules as the encoding to a raw write. */+function normalizeStoredKeys<T>(value: T): T {+ return mapKeys(value, (key) => key) as T;+}++/** What the keys below a value hold: a raw-only character, and an escape sequence. */+interface StoredKeyScan {+ raw: boolean;+ escaped: boolean;+}++function scanKeys(value: unknown, scan: StoredKeyScan): StoredKeyScan {+ if (scan.raw && scan.escaped) {+ return scan;+ }+ if (Array.isArray(value)) {+ for (const item of value) {+ scanKeys(item, scan);+ }+ return scan;+ }+ if (!isPlainObject(value)) {+ return scan;+ }+ for (const [key, child] of Object.entries(value)) {+ scan.raw ||= RAW_ONLY_PATTERN.test(key);+ scan.escaped ||= ESCAPE_PATTERN.test(key);+ scanKeys(child, scan);+ }+ return scan;+}++/** The overrides as a read returns them: see the module comment for when they are decoded. */+export function readStoredKeys<T>(value: T, marked: boolean): T {+ return marked || !scanKeys(value, { raw: false, escaped: false }).raw+ ? decodeStoredKeys(value)+ : value;+}++/** How overrides go to the engine: `raw` keys as written, or `encoded` with the marker. */+export type StoredKeyForm = 'raw' | 'encoded';++/**+ * The forms to try, in order, for writing `value`: raw when a raw read returns it unchanged,+ * falling back to encoded when its keys hold a name an engine may refuse (`.`, `$`, NUL) and+ * the engine does refuse it. `refusesRawKeys` skips the raw attempt once the engine has.+ */+export function getStoredKeyForms(value: unknown, refusesRawKeys: boolean): StoredKeyForm[] {+ const { raw, escaped } = scanKeys(value, { raw: false, escaped: false });+ if (!raw) {+ return [escaped ? 'encoded' : 'raw'];+ }+ return refusesRawKeys ? ['encoded'] : ['raw', 'encoded'];+}++/** The keys below `value` in `form`. */+export function toStoredKeys<T>(value: T, form: StoredKeyForm): T {+ return form === 'encoded' ? encodeStoredKeys(value) : normalizeStoredKeys(value);+}diff --git a/packages/data-schemas/src/schema/config.ts b/packages/data-schemas/src/schema/config.tsindex bc8654e9df..179feff87c 100644--- a/packages/data-schemas/src/schema/config.ts+++ b/packages/data-schemas/src/schema/config.ts@@ -43,6 +43,10 @@ const configSchema: Schema<IConfig> = new Schema<IConfig>(type: Number,default: 0,},+ /** Set once `overrides` keys are stored encoded; documents without it are read verbatim. */+ keyEncoding: {+ type: Number,+ },tenantId: {type: String,index: true,diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.tsindex e565b1ac60..18d31fa0fe 100644--- a/packages/data-schemas/src/types/admin.ts+++ b/packages/data-schemas/src/types/admin.ts@@ -20,8 +20,15 @@ export type AdminConfig = {principalModel: PrincipalModel;priority: number;overrides: Partial<TCustomConfig>;+ /** Dotted paths this principal suppresses from the layers below it. */+ tombstones?: string[];isActive: boolean;configVersion: number;+ /**+ * `<_id>:<configVersion>`. Sent back as `expectedRevision`, it makes a write apply only to+ * this exact document; `absent` instead means "only if the principal has no document".+ */+ revision?: string;tenantId?: string;createdAt?: string;updatedAt?: string;@@ -35,10 +42,57 @@ export type AdminConfigResponse = {config: AdminConfig;};+/** A write the server had nothing to apply for; `revision` is the stored document's, if any. */+export type AdminConfigNoopResponse = {+ message: string;+ revision: string | null;+};++/** 409: the stored document is not at the `expectedRevision` the write named. */+export type AdminConfigConflictResponse = {+ error: string;+ code: 'CONFIG_VERSION_CONFLICT';+ /** The revision now stored, or `null` when the principal has no document. */+ currentRevision: string | null;+};+export type AdminConfigDeleteResponse = {success: boolean;};+/* ── Admin API request types ────────────────────────────────────────── */++/**+ * Where a field write lands: a dotted `fieldPath`, which cannot name a key that contains a dot,+ * or the path's `segments`, which can (`['endpoints', 'bedrock', 'inferenceProfiles',+ * 'us.anthropic.claude-sonnet-4-5']`). Segments are 1 to 32 non-empty strings, none starting with+ * `$` or naming `__*`, `constructor` or `prototype`. A segment with a dot is refused (400+ * `CONFIG_PATH_INVALID`, reason `dotted_segment`) in tombstones, in `mcpServers`, `mcpConfig` and+ * `langfuse`, and wherever it would split a registered secret's location. DELETE `/fields` takes+ * `segments` as a JSON-encoded array in the query string.+ */+export type AdminConfigFieldTarget =+ | { fieldPath: string; segments?: never }+ | { segments: string[]; fieldPath?: never };++/** Optional write precondition: `absent`, or a `revision` the config API returned. */+export type AdminConfigWritePrecondition = {+ /** A mismatch answers 409 `CONFIG_VERSION_CONFLICT`; a malformed value 400. */+ expectedRevision?: string;+};++/** PATCH `/:principalType/:principalId/fields` */+export type AdminConfigPatchRequest = AdminConfigWritePrecondition & {+ entries: Array<AdminConfigFieldTarget & { value: unknown }>;+ priority?: number;+};++/** POST `/:principalType/:principalId/fields/tombstone` */+export type AdminConfigTombstoneRequest = AdminConfigWritePrecondition &+ AdminConfigFieldTarget & {+ priority?: number;+ };+/* ── Admin config contract (GET /api/admin/config/meta) ─────────────── *//**@@ -60,12 +114,30 @@ export type AdminConfigDeleteResponse = {* `${VAR}` or default URL. A later layer that changes, blanks or removes the paired URL drops* the key, and a write that changes or removes the URL beside a stored key must enter the key* again (400 `CONFIG_SECRET_REENTRY_REQUIRED`).+ * - `expectedRevision`: every config document a response returns carries `revision`+ * (`<id>:<configVersion>`), and a write with nothing to apply answers `{ message, revision }`.+ * PUT, PATCH `/fields`, POST `/fields/tombstone` and PATCH `/active` take `expectedRevision` in+ * the body, and both DELETE routes take it in the query: `absent` (create-only) or a returned+ * revision. A mismatch answers 409 `CONFIG_VERSION_CONFLICT` with `currentRevision` and changes+ * nothing; a malformed value answers 400 `INVALID_EXPECTED_REVISION`. Without one, a write that+ * loses a race re-reads the document and applies itself again, answering 409 after 3 attempts.+ * - `prunesEmptyParents`: a field delete or tombstone also removes the objects it leaves empty,+ * stopping at arrays (whose elements stay), so no `{}` shell remains; tombstones elsewhere stay.+ * A document holding only such shells counts as empty for assign-only lifecycle calls.+ * - `awaitedInvalidation`: a write answers only after this server has cleared its config caches+ * (and, with Redis, told the other instances to clear theirs); GET `/base` merges the stored+ * overrides rather than a cached merge, and a merge read before a clear is never cached. A read+ * after a write's response therefore shows it; another instance shows it once the broadcast+ * arrives, or, without Redis, within `limits.overrideCacheTtlMs`.*/export type AdminConfigFeatureFlag =| 'dottedKeys'| 'sectionAllowlist'| 'readFilteredWriteResponses'- | 'webSearchStoredKeys';+ | 'webSearchStoredKeys'+ | 'expectedRevision'+ | 'prunesEmptyParents'+ | 'awaitedInvalidation';export type AdminConfigFeatures = Record<AdminConfigFeatureFlag, boolean>;diff --git a/packages/data-schemas/src/types/config.ts b/packages/data-schemas/src/types/config.tsindex e4ccf2495a..e1c6e44ddf 100644--- a/packages/data-schemas/src/types/config.ts+++ b/packages/data-schemas/src/types/config.ts@@ -24,6 +24,8 @@ export type Config = {isActive: boolean;/** Version number for cache invalidation, auto-increments on overrides change */configVersion: number;+ /** Storage detail of the Mongoose binding: set when `overrides` keys are stored encoded */+ keyEncoding?: number;/** Tenant identifier for multi-tenancy isolation */tenantId?: string;/** When this config was created */@@ -32,15 +34,6 @@ export type Config = {updatedAt?: Date;};-/**- * A write that applies only to the document the caller read: its- * `configVersion` then, or `null` when the principal had no document. A write- * whose precondition no longer holds changes nothing and resolves to `null`.- */-export type ConfigWritePrecondition = {- expectedVersion?: number | null;-};-export type IConfig = Config &Document & {_id: Types.ObjectId;