Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🗄️ 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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, overrideCacheTtl
db.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.ts
index 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.ts
index 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.ts
index 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, handlers
expect(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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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): boolean
return 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): unknow
return 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: ReadableSe
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/dat
import 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.ts
index 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 collect
expect(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 collect
expect(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 collect
const 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.ts
index 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').getConfigSecretInputEr
let 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 expiry
await 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.ts
index 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.ts
index 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.md
index 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 invisible
until someone thought to look for its class; here the engine adjudicates
whatever 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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;