Skip to content

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

🏷️ feat: Hide and Rename Custom Endpoints by Name in Config Profiles (#17396)

Danny Avila0716094734ff
diff --git a/api/server/routes/admin/config.test.js b/api/server/routes/admin/config.test.js
index 6a1b8f927a..c36bf34e28 100644
--- a/api/server/routes/admin/config.test.js
+++ b/api/server/routes/admin/config.test.js
@@ -213,6 +213,7 @@ describe('admin config routes', () => {
expect(response.body.limits).toEqual({
maxPatchEntries: 100,
maxChangeOps: 1000,
+ maxEntryKeyLength: 256,
overrideCacheTtlMs: 15_000,
catalogModelsTtlMs: 120_000,
});
diff --git a/docs/endpoint-overrides.md b/docs/endpoint-overrides.md
new file mode 100644
index 0000000000..395c20589c
--- /dev/null
+++ b/docs/endpoint-overrides.md
@@ -0,0 +1,168 @@
+# Custom endpoints in config profiles
+
+Config profiles (the `__base__` document and role, group and user documents written through
+`/api/admin/config`) merge over `librechat.yaml`. `endpoints.custom` merges entry by entry on
+`name`: a profile's entry changes the inherited entry of the same name, and a new name adds an
+endpoint. Names compare as the runtime serves them, so `ollama` in any case is the `Ollama`
+entry.
+
+A profile can also take away what a lower layer defined: hide a whole endpoint, remove one of its
+fields, or remove one key of a record map such as `headers`. All three are tombstones that name
+the entry by its key.
+
+## Keyed paths
+
+A keyed path names one entry of an array merged by key (`rules.arrayMergeKeys` in
+`GET /api/admin/config/meta`, today `endpoints.custom`), then optionally a path inside it:
+
+```text
+endpoints.custom["<name>"]
+endpoints.custom["<name>"].<field>
+endpoints.custom["<name>"].<record>.<key>
+```
+
+`<name>` is a JSON string literal, so any name works: build it with `JSON.stringify(name)`. A name
+may hold dots, spaces, quotes or brackets (`endpoints.custom["api.example.com \"v2\""]`). It may be
+up to `limits.maxEntryKeyLength` (256) characters and may not start with `$` or `__` or be
+`constructor` or `prototype`. The path inside the entry is dotted, so a header name that contains a
+dot cannot be addressed. Tombstones are stored in this canonical form.
+
+| Method | Path | Body / query |
+| ------ | ---------------------------------------------------------------- | -------------------------------------------------- |
+| POST | `/api/admin/config/:principalType/:principalId/fields/tombstone` | `{ "fieldPath": "endpoints.custom[\"Name\"]…" }` |
+| DELETE | `/api/admin/config/:principalType/:principalId/fields` | `?fieldPath=` the URL-encoded keyed path |
+| POST | `/api/admin/config/:principalType/:principalId/changes` | `{ "op": "tombstone" \| "unset", "fieldPath": … }` |
+
+A keyed path hides or resets; it never writes. Write an entry whole with an `upsertEntry` change,
+or write the `endpoints.custom` array. A keyed path in a PATCH entry, a `set`, or as the collection
+of an entry change answers 400 `CONFIG_PATH_INVALID` with reason `keyed_path`. Only a `fieldPath`
+is read as keyed: a `segments` target names each key as written, so a segment such as
+`custom["Name"]` is a key of that spelling, and a write by it clears none of the entry's
+tombstones.
+
+## Hiding an endpoint
+
+`fieldPath: 'endpoints.custom["Name"]'` hides the endpoint for every principal the profile applies
+to. The profile's own entry of that name, and any key it stored on it, is removed. Everything that
+offers the endpoint goes with it, so the principals are not offered an endpoint they are not
+served:
+
+- the model specs that select it (`preset.endpoint`);
+- its name in `modelSpecs.addedEndpoints`;
+- its name in `endpoints.agents.allowedProviders`.
+
+This holds whether `librechat.yaml` or a lower profile (such as `__base__`) defines the endpoint.
+Nothing else goes: when the hidden endpoint selected every spec, the spec list is empty and the
+other `addedEndpoints` stay. An empty `addedEndpoints` or `allowedProviders` allows every endpoint,
+so a list that names only hidden endpoints stays as it is; those names match no endpoint the
+principals are served, so it allows none. With every spec hidden, `modelSpecs.enforce` no longer
+applies, as for a `librechat.yaml` with an empty spec list.
+
+A tombstone in the `__base__` profile applies to every principal. Every other profile merges after
+`__base__`.
+
+Hiding is undone by:
+
+- deleting the tombstone (`DELETE …/fields?fieldPath=endpoints.custom%5B%22Name%22%5D`);
+- writing the entry again in the same profile, with `upsertEntry` or a write of the
+ `endpoints.custom` array (PUT, which replaces the overrides and keeps every tombstone, does not);
+- a higher profile that writes the entry. It gets only what that profile wrote, merged onto nothing,
+ so write the complete definition (`baseURL`, `apiKey`, `models` and the rest), as for an endpoint
+ that does not exist in `librechat.yaml`.
+
+## Removing inherited values
+
+`fieldPath: 'endpoints.custom["Name"].<field>'` removes a field a lower layer set, and
+`'endpoints.custom["Name"].headers.<key>'` removes one key of a record map and keeps its siblings.
+This works for `headers`, `addParams` and any other object of the entry:
+
+```json
+{ "fieldPath": "endpoints.custom[\"Gateway\"].headers.X-Team" }
+```
+
+These tombstones behave as follows:
+
+- The profile's own value at the path is removed with it; an own entry left with nothing but its
+ name is removed.
+- Writing the entry in the same profile keeps the tombstone. A value the profile writes for the
+ same key is used over the tombstone, which keeps hiding the inherited one.
+- `DELETE …/fields?fieldPath=<same path>` removes that tombstone and restores the inherited value.
+- `DELETE …/fields?fieldPath=endpoints.custom["Name"].headers` resets the profile's own headers of
+ that entry and the key tombstones under them. A keyed path of the whole entry resets the
+ profile's own entry and every keyed tombstone of it, and `fieldPath=endpoints.custom` resets the
+ whole list and every keyed tombstone under it.
+- A higher profile can supply the value again.
+
+Refused with 400:
+
+- the entry's `name`, which identifies it (reason `merge_key`): hide the whole entry instead;
+- `apiKey`, `apiKeyPreview` and the stored destination fingerprint (`SECRET_PATH`): an entry's key
+ is entered, kept and removed with the entry;
+- an element of one of the entry's arrays, such as `models.default.0` (`inside_array`): a tombstone
+ hides a whole array.
+
+A tombstone at a position in the list (`endpoints.custom.0.headers`) is refused too
+(`inside_array`). Before keyed paths, POST `/fields/tombstone` stored it, and the merge never
+applied it.
+
+Removing a field the endpoint needs (`baseURL`, `models`) is not reported. The runtime does not
+serve a custom endpoint without them, so it disappears for those principals.
+
+## Stored keys
+
+A tombstone never sends a key anywhere new:
+
+- Hiding a profile's own entry removes the key it stored. Showing the entry again does not bring the
+ key back; enter it again.
+- Removing where the profile's own entry sends its stored key (`baseURL`, `provider`, or a
+ destination option in `addParams`) answers 400 `CONFIG_SECRET_REENTRY_REQUIRED`, with the
+ changed field and `secretPath`, on DELETE, tombstones and `/changes`.
+- Removing it from an inherited entry drops the inherited key at merge, and the write lists the
+ key in `ignored` with reason `secret_rebinding`.
+- An inherited endpoint whose users enter their own keys (`user_provided`, `customUserVars`) keeps
+ its destination: the merge sets the removed field back and the write lists it in `ignored`.
+
+## Renaming
+
+A profile renames one of its own entries, with the key stored on it, in either of two ways:
+
+- a `rename` change in `/changes`: `{ "op": "rename", "fieldPath": "endpoints.custom", "from":
+ "draft", "to": "final" }`;
+- a `renames` hint on PUT or PATCH beside a write of the list that has the entry under its new name
+ and not under the old one, without its `apiKey`:
+
+ ```json
+ {
+ "entries": [{ "fieldPath": "endpoints.custom", "value": [{ "name": "final", "baseURL": "…" }] }],
+ "renames": [{ "path": "endpoints.custom", "previousName": "draft", "name": "final" }]
+ }
+ ```
+
+Either way, the key keeps its stored ciphertext and preview, and the keyed tombstones of the old
+name move to the new one. The key stays bound to its destination: a renamed entry that sends it
+somewhere else answers 400 `CONFIG_SECRET_REENTRY_REQUIRED`. A key the profile entered for an
+endpoint `__base__` defines keeps the destination fingerprint it was entered with.
+
+Entries `librechat.yaml` defines cannot be renamed, and no entry can take their name. A hint that
+cannot apply answers 400 `CONFIG_RENAME_INVALID` with `reason`:
+
+| Reason | When |
+| ---------------------- | -------------------------------------------------------------------- |
+| `inherited_entry` | either name is a `librechat.yaml` entry |
+| `source_not_found` | the profile stores no entry named `previousName` |
+| `target_exists` | the profile already stores an entry named `name` |
+| `target_not_written` | the write does not write an entry named `name` |
+| `source_still_written` | the write still writes `previousName`; swap names with `rename` ops |
+| `duplicate_source` | two hints rename the same entry |
+| `duplicate_target` | two hints rename to the same name |
+| `invalid_name` | a name a keyed path cannot address, or two spellings of one entry |
+
+Without a hint, a renamed entry is a new entry: it keeps no key, and the tombstones stay on the old
+name.
+
+## After upgrading
+
+Before keyed paths, a tombstone such as `endpoints.custom["Name"]` was accepted and stored but had
+no effect. Stored ones now hide that entry. Clients send keyed paths only when
+`features.keyedTombstones` is true in `GET /api/admin/config/meta`, and endpoint rename hints when
+`features.renameHints` is.
diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.ts
index 7c53532a76..bd802aa327 100644
--- a/packages/api/src/admin/config.handler.spec.ts
+++ b/packages/api/src/admin/config.handler.spec.ts
@@ -860,7 +860,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
- ['interface.modelSelect'],
+ [{ segments: ['interface', 'modelSelect'] }],
undefined,
{
expectedRevision: undefined,
@@ -882,7 +882,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
- ['interface.mcpServers.placeholder'],
+ [{ segments: ['interface', 'mcpServers', 'placeholder'] }],
undefined,
{
expectedRevision: undefined,
@@ -949,7 +949,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
- ['skillSync.github.enabled'],
+ [{ segments: ['skillSync', 'github', 'enabled'] }],
undefined,
{
expectedRevision: undefined,
@@ -971,7 +971,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'admin',
- ['interface.modelSelect'],
+ [{ segments: ['interface', 'modelSelect'] }],
undefined,
{
expectedRevision: undefined,
@@ -3178,7 +3178,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'__base__',
- ['turnstileConfig.siteKey'],
+ [{ segments: ['turnstileConfig', 'siteKey'] }],
undefined,
{ expectedRevision: undefined },
);
@@ -3238,7 +3238,7 @@ describe('createAdminConfigHandlers', () => {
expect(deps.unsetConfigField).toHaveBeenCalledWith(
'role',
'editor',
- ['ocr.apiKey', 'ocr.apiKeyPreview'],
+ [{ segments: ['ocr', 'apiKey'] }, { segments: ['ocr', 'apiKeyPreview'] }],
undefined,
{ expectedRevision: undefined },
);
@@ -3569,9 +3569,15 @@ describe('createAdminConfigHandlers', () => {
await handlers.deleteConfigField(mockReq({ params, query: { fieldPath: 'paths' } }), res);
expect(res.statusCode).toBe(200);
- expect(deps.unsetConfigField).toHaveBeenCalledWith('role', 'admin', ['paths'], undefined, {
- expectedRevision: undefined,
- });
+ expect(deps.unsetConfigField).toHaveBeenCalledWith(
+ 'role',
+ 'admin',
+ [{ segments: ['paths'] }],
+ undefined,
+ {
+ expectedRevision: undefined,
+ },
+ );
});
it('does not let a section-scoped manager remove a value under an unknown section', async () => {
diff --git a/packages/api/src/admin/config.keyed.integration.spec.ts b/packages/api/src/admin/config.keyed.integration.spec.ts
new file mode 100644
index 0000000000..89b232752e
--- /dev/null
+++ b/packages/api/src/admin/config.keyed.integration.spec.ts
@@ -0,0 +1,1045 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { PrincipalModel, PrincipalType } from 'librechat-data-provider';
+import type { AppConfig, ConfigDraft } from '@librechat/data-schemas';
+import type { Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+
+process.env.CREDS_KEY =
+ process.env.CREDS_KEY ?? '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+process.env.CREDS_IV = process.env.CREDS_IV ?? '0123456789abcdef0123456789abcdef';
+
+type DataSchemas = typeof import('@librechat/data-schemas');
+type Methods = ReturnType<DataSchemas['createMethods']>;
+type AdminConfigDeps = Parameters<typeof import('./config').createAdminConfigHandlers>[0];
+type Handlers = ReturnType<typeof import('./config').createAdminConfigHandlers>;
+type Doc = Record<string, unknown>;
+type Endpoint = Record<string, unknown> & { name: string };
+
+interface MockRes {
+ statusCode: number;
+ body: undefined | Doc;
+ status: jest.Mock;
+ json: jest.Mock;
+}
+
+let mongoServer: MongoMemoryServer;
+let methods: Methods;
+let dataSchemas: DataSchemas;
+let createAdminConfigHandlers: typeof import('./config').createAdminConfigHandlers;
+let createAppConfigService: typeof import('~/app/service').createAppConfigService;
+let resolveCustomEndpointSecrets: typeof import('./secrets').resolveCustomEndpointSecrets;
+
+const YAML_LITERAL_KEY = 'sk-yaml-literal-key-0123456789';
+
+/** The deployment's librechat.yaml: two custom endpoints, each selected by a model spec. */
+const YAML = {
+ endpoints: {
+ custom: [
+ {
+ name: 'My Endpoint',
+ apiKey: '${MY_ENDPOINT_KEY}',
+ baseURL: 'https://my.example.com/v1',
+ models: { default: ['m'] },
+ headers: { 'X-Team': 'yaml', 'X-Trace': 'on' },
+ },
+ {
+ name: 'Literal',
+ apiKey: YAML_LITERAL_KEY,
+ baseURL: 'https://literal.example.com/v1',
+ models: { default: ['m'] },
+ },
+ {
+ name: 'Own Keys',
+ apiKey: 'user_provided',
+ baseURL: 'https://own-keys.example.com/v1',
+ models: { default: ['m'] },
+ },
+ ],
+ },
+ modelSpecs: {
+ list: [
+ { name: 'mine', label: 'Mine', preset: { endpoint: 'My Endpoint', model: 'm' } },
+ { name: 'literal', label: 'Literal', preset: { endpoint: 'Literal', model: 'm' } },
+ ],
+ },
+};
+
+const baseAppConfig = {
+ config: YAML,
+ endpoints: { custom: structuredClone(YAML.endpoints.custom) },
+ modelSpecs: structuredClone(YAML.modelSpecs),
+} as unknown as AppConfig;
+
+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 createDeps(overrides: Partial<AdminConfigDeps> = {}): AdminConfigDeps {
+ return {
+ listAllConfigs: methods.listAllConfigs,
+ findConfigByPrincipal: methods.findConfigByPrincipal,
+ writeConfigDocument: methods.writeConfigDocument,
+ unsetConfigField: methods.unsetConfigField,
+ deleteConfig: methods.deleteConfig,
+ toggleConfigActiveTracked: methods.toggleConfigActiveTracked,
+ hasConfigCapability: async () => true,
+ hasAnyConfigReadAccess: async () => true,
+ hasCapability: async () => true,
+ getAppConfig: async () => baseAppConfig,
+ invalidateConfigCaches: jest.fn(async () => undefined),
+ recordAuditEntry: jest.fn(async () => undefined),
+ overrideEnvAllowlist: 'MY_ENDPOINT_KEY',
+ ...overrides,
+ };
+}
+
+let handlers: Handlers;
+let counter = 0;
+function nextRole(): string {
+ counter += 1;
+ return `keyed-${counter}`;
+}
+
+const params = (principalId: string) => ({ principalType: 'role', principalId });
+
+async function call(
+ handler: keyof Handlers,
+ principalId: string,
+ init: { body?: Doc; query?: Doc },
+ using: Handlers = handlers,
+): Promise<MockRes> {
+ const res = mockRes();
+ await using[handler](mockReq({ params: params(principalId), ...init }), res);
+ return res;
+}
+
+const tombstone = (principalId: string, fieldPath: string, using?: Handlers) =>
+ call('tombstoneConfigField', principalId, { body: { fieldPath } }, using);
+const remove = (principalId: string, fieldPath: string, using?: Handlers) =>
+ call('deleteConfigField', principalId, { query: { fieldPath } }, using);
+const patch = (principalId: string, body: Doc, using?: Handlers) =>
+ call('patchConfigField', principalId, { body }, using);
+const put = (principalId: string, body: Doc, using?: Handlers) =>
+ call('upsertConfigOverrides', principalId, { body }, using);
+const changes = (principalId: string, body: Doc, using?: Handlers) =>
+ call('applyConfigChanges', principalId, { body }, using);
+
+const raw = () => mongoose.connection.db!.collection('configs');
+const storedDocument = (principalId: string) => raw().findOne({ principalId });
+
+async function storedEndpoint(principalId: string, name: string): Promise<Endpoint | undefined> {
+ const document = await storedDocument(principalId);
+ return (document?.overrides?.endpoints?.custom as Endpoint[] | undefined)?.find(
+ (entry) => entry.name === name,
+ );
+}
+
+/** Stores a role document as is, past every API guard. */
+async function seed(principalId: string, overrides: Doc, tombstones: string[] = []) {
+ const draft: ConfigDraft = {
+ principalModel: PrincipalModel.ROLE,
+ priority: 10,
+ isActive: true,
+ overrides: overrides as ConfigDraft['overrides'],
+ tombstones,
+ };
+ await methods.writeConfigDocument(PrincipalType.ROLE, principalId, draft, 'absent');
+}
+
+/** The effective config a principal of `role` is served, through the real config service. */
+async function servedConfig(role: string, base: AppConfig = baseAppConfig): Promise<AppConfig> {
+ const entries = new Map<string, unknown>();
+ const { getAppConfig } = createAppConfigService({
+ loadBaseConfig: async () => structuredClone(base),
+ 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: (principals) => methods.getApplicableConfigs(principals),
+ getUserPrincipals: async () => [],
+ overrideEnvAllowlist: 'MY_ENDPOINT_KEY',
+ });
+ return getAppConfig({ role });
+}
+
+const servedNames = (config: AppConfig) =>
+ (config.endpoints?.custom ?? []).map((entry) => (entry as Endpoint).name);
+const specNames = (config: AppConfig) => (config.modelSpecs?.list ?? []).map((spec) => spec.name);
+
+const endpoint = (name: string, extra: Doc = {}): Endpoint => ({
+ name,
+ baseURL: `https://${name.replace(/[^a-z0-9]/gi, '-')}.example.com/v1`,
+ models: { default: ['m'] },
+ ...extra,
+});
+
+const LIFECYCLE_TIMEOUT_MS = 180_000;
+
+beforeAll(async () => {
+ const [schemas, handlersModule, serviceModule, secretsModule, server] = await Promise.all([
+ import('@librechat/data-schemas'),
+ import('./config'),
+ import('~/app/service'),
+ import('./secrets'),
+ MongoMemoryServer.create(),
+ ]);
+ dataSchemas = schemas;
+ mongoServer = server;
+ ({ createAdminConfigHandlers } = handlersModule);
+ ({ createAppConfigService } = serviceModule);
+ ({ resolveCustomEndpointSecrets } = secretsModule);
+ jest.spyOn(schemas.logger, 'error').mockReturnValue(schemas.logger);
+ jest.spyOn(schemas.logger, 'warn').mockReturnValue(schemas.logger);
+ jest.spyOn(schemas.logger, 'info').mockReturnValue(schemas.logger);
+
+ await mongoose.connect(mongoServer.getUri());
+ schemas.createModels(mongoose);
+ await mongoose.models.Config.init();
+ methods = schemas.createMethods(mongoose);
+ handlers = createAdminConfigHandlers(createDeps());
+}, LIFECYCLE_TIMEOUT_MS);
+
+afterAll(async () => {
+ await mongoose.disconnect();
+ await mongoServer.stop();
+}, LIFECYCLE_TIMEOUT_MS);
+
+describe('hiding librechat.yaml custom endpoints by key', () => {
+ it('a tombstone hides the endpoint and the model specs that select it, for that profile only', async () => {
+ const hidden = nextRole();
+ const other = nextRole();
+ await seed(other, { interface: { customWelcome: 'hi' } });
+
+ const res = await tombstone(hidden, 'endpoints.custom["My Endpoint"]');
+
+ expect(res.statusCode).toBe(200);
+ expect((await storedDocument(hidden))?.tombstones).toEqual(['endpoints.custom["My Endpoint"]']);
+ const served = await servedConfig(hidden);
+ expect(servedNames(served)).toEqual(['Literal', 'Own Keys']);
+ expect(specNames(served)).toEqual(['literal']);
+ const unaffected = await servedConfig(other);
+ expect(servedNames(unaffected)).toEqual(['My Endpoint', 'Literal', 'Own Keys']);
+ expect(specNames(unaffected)).toEqual(['mine', 'literal']);
+ });
+
+ it('a profile that adds a hidden endpoint back keeps its model specs', async () => {
+ const role = nextRole();
+ await seed(role, {}, ['endpoints.custom["My Endpoint"]']);
+ expect(specNames(await servedConfig(role))).toEqual(['literal']);
+
+ const readd = await changes(role, {
+ ops: [
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: endpoint('My Endpoint', { apiKey: '${MY_ENDPOINT_KEY}' }),
+ },
+ ],
+ });
+
+ expect(readd.statusCode).toBe(200);
+ expect((await storedDocument(role))?.tombstones).toEqual([]);
+ expect(specNames(await servedConfig(role))).toEqual(['mine', 'literal']);
+ });
+
+ it('hides the model specs of an endpoint a Base profile defines, as of a librechat.yaml one', async () => {
+ const role = nextRole();
+ const base = dataSchemas.BASE_CONFIG_PRINCIPAL_ID;
+ const spec = (name: string, endpointName: string) => ({
+ name,
+ label: name,
+ preset: { endpoint: endpointName, model: 'm' },
+ });
+ const written = await changes(base, {
+ ops: [
+ { op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: endpoint('Team') },
+ {
+ op: 'set',
+ fieldPath: 'modelSpecs.list',
+ value: [spec('team', 'Team'), spec('mine', 'My Endpoint'), spec('literal', 'Literal')],
+ },
+ ],
+ });
+ expect(written.statusCode).toBe(200);
+ try {
+ for (const path of ['endpoints.custom["Team"]', 'endpoints.custom["My Endpoint"]']) {
+ expect((await tombstone(role, path)).statusCode).toBe(200);
+ }
+
+ const served = await servedConfig(role);
+ expect(servedNames(served)).toEqual(['Literal', 'Own Keys']);
+ expect(specNames(served)).toEqual(['literal']);
+ expect(specNames(await servedConfig(nextRole()))).toEqual(['team', 'mine', 'literal']);
+ } finally {
+ await methods.deleteConfig(PrincipalType.ROLE, base);
+ }
+ });
+
+ it('a stored bracket tombstone, a silent no-op before, now takes effect at merge', async () => {
+ const role = nextRole();
+ await seed(role, {}, ['endpoints.custom["Literal"]']);
+
+ expect(servedNames(await servedConfig(role))).toEqual(['My Endpoint', 'Own Keys']);
+ });
+
+ describe('the endpoint lists a hidden endpoint is named in', () => {
+ const spec = (name: string, endpointName: string) => ({
+ name,
+ label: name,
+ preset: { endpoint: endpointName, model: 'm' },
+ });
+ /** The base config with these model specs and agent providers, as librechat.yaml loads them. */
+ const baseWith = (
+ modelSpecs: { list: ReturnType<typeof spec>[]; addedEndpoints?: string[] },
+ allowedProviders?: string[],
+ ) =>
+ ({
+ ...structuredClone(baseAppConfig),
+ endpoints: {
+ custom: structuredClone(YAML.endpoints.custom),
+ ...(allowedProviders && { agents: { allowedProviders } }),
+ },
+ modelSpecs,
+ }) as unknown as AppConfig;
+
+ it('keeps the unrelated added endpoints when the hidden endpoint owned every spec', async () => {
+ const role = nextRole();
+ await seed(role, {}, ['endpoints.custom["My Endpoint"]']);
+ const base = baseWith({
+ list: [spec('mine', 'My Endpoint')],
+ addedEndpoints: ['agents', 'My Endpoint', 'Literal'],
+ });
+
+ const served = await servedConfig(role, base);
+
+ expect(served.modelSpecs?.list).toEqual([]);
+ expect(served.modelSpecs?.addedEndpoints).toEqual(['agents', 'Literal']);
+ expect((await servedConfig(nextRole(), base)).modelSpecs).toEqual(base.modelSpecs);
+ });
+
+ it('takes the hidden endpoint out of the agent provider allow-list', async () => {
+ const role = nextRole();
+ await seed(role, {}, ['endpoints.custom["My Endpoint"]']);
+ const base = baseWith({ list: [] }, ['My Endpoint', 'openAI', 'Literal']);
+
+ const served = await servedConfig(role, base);
+
+ expect(served.endpoints?.agents?.allowedProviders).toEqual(['openAI', 'Literal']);
+ expect((await servedConfig(nextRole(), base)).endpoints?.agents?.allowedProviders).toEqual([
+ 'My Endpoint',
+ 'openAI',
+ 'Literal',
+ ]);
+ });
+
+ it('never empties an allow-list, which would allow every endpoint', async () => {
+ const role = nextRole();
+ await seed(role, {}, ['endpoints.custom["My Endpoint"]']);
+ const base = baseWith(
+ { list: [spec('literal', 'Literal')], addedEndpoints: ['My Endpoint'] },
+ ['My Endpoint'],
+ );
+
+ const served = await servedConfig(role, base);
+
+ expect(servedNames(served)).toEqual(['Literal', 'Own Keys']);
+ expect(specNames(served)).toEqual(['literal']);
+ expect(served.modelSpecs?.addedEndpoints).toEqual(['My Endpoint']);
+ expect(served.endpoints?.agents?.allowedProviders).toEqual(['My Endpoint']);
+ });
+ });
+
+ it('DELETE of the keyed path shows the endpoint again', async () => {
+ const role = nextRole();
+ await tombstone(role, 'endpoints.custom["My Endpoint"]');
+
+ const res = await remove(role, 'endpoints.custom["My Endpoint"]');
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.applied).toEqual([
+ {
+ path: 'endpoints.custom["My Endpoint"]',
+ segments: ['endpoints', 'custom'],
+ key: 'My Endpoint',
+ },
+ ]);
+ expect((await storedDocument(role))?.tombstones).toEqual([]);
+ expect(servedNames(await servedConfig(role))).toEqual(['My Endpoint', 'Literal', 'Own Keys']);
+ });
+});
+
+describe('writes by segments that spell a keyed path', () => {
+ it('a PATCH or set by such segments keeps the hide of the entry and the hides inside it', async () => {
+ const role = nextRole();
+ const hides = ['endpoints.custom["Literal"]', 'endpoints.custom["My Endpoint"].headers.X-Team'];
+ for (const path of hides) {
+ expect((await tombstone(role, path)).statusCode).toBe(200);
+ }
+
+ const responses = [
+ await patch(role, {
+ entries: [{ segments: ['endpoints', 'custom["Literal"]'], value: { titleModel: 'x' } }],
+ }),
+ await changes(role, {
+ ops: [
+ {
+ op: 'set',
+ segments: ['endpoints', 'custom["My Endpoint"]', 'headers', 'X-Team'],
+ value: 'role',
+ },
+ ],
+ }),
+ ];
+
+ for (const res of responses) {
+ expect(res.statusCode).toBe(200);
+ }
+ expect((await storedDocument(role))?.tombstones).toEqual(hides);
+ const served = await servedConfig(role);
+ expect(servedNames(served)).toEqual(['My Endpoint', 'Own Keys']);
+ const mine = (served.endpoints?.custom ?? []).find(
+ (entry) => (entry as Endpoint).name === 'My Endpoint',
+ );
+ expect(mine?.headers).toEqual({ 'X-Trace': 'on' });
+ });
+});
+
+describe('removing an inherited key of a custom endpoint record', () => {
+ const headersOf = async (role: string) =>
+ ((await servedConfig(role)).endpoints?.custom ?? []).find(
+ (entry) => (entry as Endpoint).name === 'My Endpoint',
+ )?.headers;
+
+ it('hides one header, keeps its siblings and the profile own edits, and DELETE restores it', async () => {
+ const role = nextRole();
+ const hidden = await tombstone(role, 'endpoints.custom["My Endpoint"].headers.X-Team');
+ expect(hidden.statusCode).toBe(200);
+ expect(hidden.body?.applied).toEqual([
+ {
+ path: 'endpoints.custom["My Endpoint"].headers.X-Team',
+ segments: ['endpoints', 'custom'],
+ key: 'My Endpoint',
+ entryPath: ['headers', 'X-Team'],
+ },
+ ]);
+ expect(hidden.body?.skipped).toEqual([]);
+ expect(await headersOf(role)).toEqual({ 'X-Trace': 'on' });
+
+ const edited = await changes(role, {
+ ops: [
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: { name: 'My Endpoint', headers: { 'X-Own': 'role' } },
+ },
+ ],
+ });
+ expect(edited.statusCode).toBe(200);
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["My Endpoint"].headers.X-Team',
+ ]);
+ expect(await headersOf(role)).toEqual({ 'X-Trace': 'on', 'X-Own': 'role' });
+
+ const restored = await remove(role, 'endpoints.custom["My Endpoint"].headers.X-Team');
+ expect(restored.statusCode).toBe(200);
+ expect(await headersOf(role)).toEqual({ 'X-Team': 'yaml', 'X-Trace': 'on', 'X-Own': 'role' });
+ });
+
+ it('DELETE of the whole record resets the profile keys and the key tombstones under it', async () => {
+ const role = nextRole();
+ await seed(
+ role,
+ { endpoints: { custom: [{ name: 'My Endpoint', headers: { 'X-Own': 'r' } }] } },
+ [
+ 'endpoints.custom["My Endpoint"].headers.X-Team',
+ 'endpoints.custom["My Endpoint"].headers.X-Trace',
+ 'endpoints.custom["Literal"]',
+ ],
+ );
+
+ const res = await remove(role, 'endpoints.custom["My Endpoint"].headers');
+
+ expect(res.statusCode).toBe(200);
+ const document = await storedDocument(role);
+ expect(document?.overrides).toEqual({});
+ expect(document?.tombstones).toEqual(['endpoints.custom["Literal"]']);
+ expect(await headersOf(role)).toEqual({ 'X-Team': 'yaml', 'X-Trace': 'on' });
+
+ const collection = await remove(role, 'endpoints.custom');
+ expect(collection.statusCode).toBe(200);
+ expect((await storedDocument(role))?.tombstones).toEqual([]);
+ });
+});
+
+describe('keyed paths the API refuses', () => {
+ const refusals: Array<[string, Doc]> = [
+ ['endpoints.custom["My Endpoint"', { code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' }],
+ ['modelSpecs.list["mine"]', { code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' }],
+ ['endpoints.custom["__proto__"]', { code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' }],
+ ['endpoints.custom["My Endpoint"].name', { code: 'CONFIG_PATH_INVALID', reason: 'merge_key' }],
+ ['endpoints.custom["My Endpoint"].apiKey', { code: 'SECRET_PATH' }],
+ ['endpoints.custom["My Endpoint"].apiKeyPreview', { code: 'SECRET_PATH' }],
+ ['endpoints.custom["My Endpoint"].apiKeyBinding', { code: 'SECRET_PATH' }],
+ ];
+
+ it.each(refusals)(
+ 'refuses %s on every route that hides or resets, storing nothing',
+ async (path, expected) => {
+ const role = nextRole();
+ const responses = [
+ await tombstone(role, path),
+ await remove(role, path),
+ await changes(role, { ops: [{ op: 'tombstone', fieldPath: path }] }),
+ await changes(role, { ops: [{ op: 'unset', fieldPath: path }] }),
+ ];
+ for (const res of responses) {
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject(expected);
+ expect(JSON.stringify(res.body)).not.toContain('My Endpoint');
+ }
+ expect(await storedDocument(role)).toBeNull();
+ },
+ );
+
+ it('refuses a tombstone into an array of the entry, or into a collection by position', async () => {
+ const role = nextRole();
+ for (const path of [
+ 'endpoints.custom["My Endpoint"].models.default.0',
+ 'endpoints.custom.0.headers',
+ 'endpoints.custom.1',
+ ]) {
+ for (const res of [
+ await tombstone(role, path),
+ await changes(role, { ops: [{ op: 'tombstone', fieldPath: path }] }),
+ ]) {
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'inside_array' });
+ }
+ }
+ expect(await storedDocument(role)).toBeNull();
+ });
+
+ it('refuses a tombstone whose segments a later read would take for a keyed path', async () => {
+ const role = nextRole();
+ const segments = ['endpoints', 'custom["Literal"]'];
+ for (const res of [
+ await call('tombstoneConfigField', role, { body: { segments } }),
+ await changes(role, { ops: [{ op: 'tombstone', segments }] }),
+ ]) {
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' });
+ }
+ expect(await storedDocument(role)).toBeNull();
+ });
+
+ it('refuses a keyed path in a write: PATCH, set, and the collection of an entry op', async () => {
+ const role = nextRole();
+ const path = 'endpoints.custom["My Endpoint"].titleModel';
+ const responses = [
+ await patch(role, { entries: [{ fieldPath: path, value: 'x' }] }),
+ await changes(role, { ops: [{ op: 'set', fieldPath: path, value: 'x' }] }),
+ await changes(role, {
+ ops: [{ op: 'upsertEntry', fieldPath: path, entry: endpoint('x') }],
+ }),
+ await changes(role, { ops: [{ op: 'removeEntry', fieldPath: path, key: 'x' }] }),
+ ];
+ for (const res of responses) {
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' });
+ }
+ expect(await storedDocument(role)).toBeNull();
+ });
+});
+
+describe('keyed changes in a batch', () => {
+ it('hides an endpoint and removes a header of another in one write, named by key', async () => {
+ const role = nextRole();
+ const recordAuditEntry = jest.fn(async () => undefined);
+ const audited = createAdminConfigHandlers(createDeps({ recordAuditEntry }));
+
+ const res = await changes(
+ role,
+ {
+ ops: [
+ { op: 'tombstone', fieldPath: 'endpoints.custom["Literal"]' },
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: endpoint('gw', { headers: { A: 'a' } }),
+ },
+ { op: 'tombstone', fieldPath: 'endpoints.custom["gw"].headers.A' },
+ { op: 'unset', fieldPath: 'endpoints.custom["absent"]' },
+ ],
+ },
+ audited,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toMatchObject({
+ written: true,
+ applied: [
+ { opIndex: 0, op: 'tombstone', segments: ['endpoints', 'custom'], key: 'Literal' },
+ { opIndex: 1, op: 'upsertEntry', segments: ['endpoints', 'custom'], key: 'gw' },
+ {
+ opIndex: 2,
+ op: 'tombstone',
+ segments: ['endpoints', 'custom'],
+ key: 'gw',
+ entryPath: ['headers', 'A'],
+ },
+ ],
+ unchanged: [{ opIndex: 3, op: 'unset', segments: ['endpoints', 'custom'], key: 'absent' }],
+ });
+ const document = await storedDocument(role);
+ expect(document?.overrides).toEqual({ endpoints: { custom: [endpoint('gw')] } });
+ expect(document?.tombstones).toEqual([
+ 'endpoints.custom["Literal"]',
+ 'endpoints.custom["gw"].headers.A',
+ ]);
+ expect(recordAuditEntry).toHaveBeenCalledWith(
+ expect.objectContaining({
+ metadata: expect.objectContaining({
+ tombstone: 'endpoints.custom["Literal"],endpoints.custom["gw"].headers.A',
+ }),
+ }),
+ );
+ });
+
+ it('refuses two changes of one whole entry, by the key the merge folds it to', async () => {
+ const role = nextRole();
+ const res = await changes(role, {
+ ops: [
+ { op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: endpoint('Ollama') },
+ { op: 'tombstone', fieldPath: 'endpoints.custom["ollama"]' },
+ ],
+ });
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({ code: 'DUPLICATE_FIELD_PATH', opIndex: 1 });
+ });
+
+ it('a dry run reports a keyed hide without writing it', async () => {
+ const role = nextRole();
+ const res = await changes(role, {
+ dryRun: true,
+ ops: [{ op: 'tombstone', fieldPath: 'endpoints.custom["Literal"].headers' }],
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body).toMatchObject({ written: false, dryRun: true });
+ expect(await storedDocument(role)).toBeNull();
+ });
+});
+
+describe('stored keys of entries a profile hides or renames', () => {
+ async function storeOwnKey(role: string, name: string, extra: Doc = {}): Promise<Endpoint> {
+ const res = await changes(role, {
+ ops: [
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: endpoint(name, { apiKey: 'sk-profile-own-key-0123456789', ...extra }),
+ },
+ ],
+ });
+ expect(res.statusCode).toBe(200);
+ const stored = await storedEndpoint(role, name);
+ expect(String(stored?.apiKey)).toMatch(/^v3:/);
+ return stored as Endpoint;
+ }
+
+ it('hiding a profile own endpoint removes its stored key; showing it again does not bring it back', async () => {
+ const role = nextRole();
+ await storeOwnKey(role, 'gw');
+
+ expect((await tombstone(role, 'endpoints.custom["gw"]')).statusCode).toBe(200);
+ expect(await storedEndpoint(role, 'gw')).toBeUndefined();
+
+ expect((await remove(role, 'endpoints.custom["gw"]')).statusCode).toBe(200);
+ const readded = await changes(role, {
+ ops: [{ op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: endpoint('gw') }],
+ });
+ expect(readded.statusCode).toBe(200);
+ expect((await storedEndpoint(role, 'gw'))?.apiKey).toBeUndefined();
+ });
+
+ it('a keyed reset or hide of the base URL beside a stored key needs the key entered again', async () => {
+ const role = nextRole();
+ const before = await storeOwnKey(role, 'gw');
+
+ for (const res of [
+ await remove(role, 'endpoints.custom["gw"].baseURL'),
+ await tombstone(role, 'endpoints.custom["gw"].baseURL'),
+ await changes(role, { ops: [{ op: 'unset', fieldPath: 'endpoints.custom["gw"].baseURL' }] }),
+ ]) {
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({
+ code: 'CONFIG_SECRET_REENTRY_REQUIRED',
+ issues: [expect.objectContaining({ secretPath: 'endpoints.custom.0.apiKey' })],
+ });
+ }
+ expect(await storedEndpoint(role, 'gw')).toEqual(before);
+
+ const header = await remove(role, 'endpoints.custom["gw"].headers');
+ expect(header.statusCode).toBe(200);
+ });
+
+ it('a DELETE by segments removes the key a segment holds as written, never a field of an entry', async () => {
+ const role = nextRole();
+ const base = dataSchemas.BASE_CONFIG_PRINCIPAL_ID;
+ const team = endpoint('Team', { apiKey: 'sk-base-team-key-0123456789' });
+ const inherited = await changes(base, {
+ ops: [{ op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: team }],
+ });
+ expect(inherited.statusCode).toBe(200);
+ try {
+ const own = await storeOwnKey(role, 'gw');
+ const entered = await changes(role, {
+ ops: [
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: { name: 'Team', apiKey: 'sk-role-own-team-key-0123456789' },
+ },
+ ],
+ });
+ expect(entered.statusCode).toBe(200);
+ const bound = await storedEndpoint(role, 'Team');
+ expect(bound?.apiKeyBinding).toEqual(expect.any(String));
+ await raw().updateOne(
+ { principalId: role },
+ { $set: { 'overrides.endpoints.custom["gw"]': { baseURL: 'https://junk.example.com' } } },
+ );
+
+ for (const [name, field] of [
+ ['gw', 'baseURL'],
+ ['gw', 'name'],
+ ['Team', 'apiKeyBinding'],
+ ]) {
+ const segment = `custom[${JSON.stringify(name)}]`;
+ const res = await call('deleteConfigField', role, {
+ query: { segments: JSON.stringify(['endpoints', segment, field]) },
+ });
+ expect(res.statusCode).toBe(200);
+ expect(await storedEndpoint(role, 'gw')).toEqual(own);
+ expect(await storedEndpoint(role, 'Team')).toEqual(bound);
+ }
+ const endpoints = (await storedDocument(role))?.overrides?.endpoints as Doc;
+ expect(Object.keys(endpoints)).toEqual(['custom']);
+ } finally {
+ await methods.deleteConfig(PrincipalType.ROLE, base);
+ }
+ });
+
+ it('a keyed hide of an inherited destination drops the inherited key and reports it', async () => {
+ const role = nextRole();
+
+ const res = await tombstone(role, 'endpoints.custom["Literal"].baseURL');
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.ignored).toEqual([
+ {
+ path: 'endpoints.custom["Literal"].apiKey',
+ segments: ['endpoints', 'custom', 'Literal', 'apiKey'],
+ reason: 'secret_rebinding',
+ },
+ ]);
+ const literal = ((await servedConfig(role)).endpoints?.custom ?? []).find(
+ (entry) => (entry as Endpoint).name === 'Literal',
+ );
+ expect(literal?.apiKey ?? '').toBe('');
+ });
+
+ it('a keyed hide of the destination users send their own keys to is set back and reported', async () => {
+ const role = nextRole();
+
+ const res = await tombstone(role, 'endpoints.custom["Own Keys"].baseURL');
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.ignored).toEqual([
+ {
+ path: 'endpoints.custom["Own Keys"].baseURL',
+ segments: ['endpoints', 'custom', 'Own Keys', 'baseURL'],
+ reason: 'secret_rebinding',
+ },
+ ]);
+ const ownKeys = ((await servedConfig(role)).endpoints?.custom ?? []).find(
+ (entry) => (entry as Endpoint).name === 'Own Keys',
+ );
+ expect(ownKeys?.baseURL).toBe('https://own-keys.example.com/v1');
+ });
+
+ describe('a rename hint', () => {
+ async function seedDraft(role: string): Promise<Endpoint> {
+ const draft = await storeOwnKey(role, 'draft');
+ expect((await tombstone(role, 'endpoints.custom["draft"].headers.X-Legacy')).statusCode).toBe(
+ 200,
+ );
+ return draft;
+ }
+ const renamed = (draft: Endpoint, extra: Doc = {}) => ({
+ ...endpoint('final'),
+ baseURL: draft.baseURL,
+ ...extra,
+ });
+ const hint = [{ path: 'endpoints.custom', previousName: 'draft', name: 'final' }];
+
+ it('on PATCH carries the stored key to the renamed entry and moves its keyed tombstones', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+
+ const res = await patch(role, {
+ entries: [{ fieldPath: 'endpoints.custom', value: [renamed(draft)] }],
+ renames: hint,
+ });
+
+ expect(res.statusCode).toBe(200);
+ const final = await storedEndpoint(role, 'final');
+ expect(final?.apiKey).toBe(draft.apiKey);
+ expect(final?.apiKeyPreview).toBe(draft.apiKeyPreview);
+ expect(await storedEndpoint(role, 'draft')).toBeUndefined();
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["final"].headers.X-Legacy',
+ ]);
+ const served = ((await servedConfig(role)).endpoints?.custom ?? []).find(
+ (entry) => (entry as Endpoint).name === 'final',
+ );
+ expect(served && resolveCustomEndpointSecrets(served).apiKey).toBe(
+ 'sk-profile-own-key-0123456789',
+ );
+ });
+
+ it('on a PATCH that also resets a path, does the same', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+
+ const res = await patch(role, {
+ entries: [
+ { fieldPath: 'interface', value: { prompts: false } },
+ { fieldPath: 'endpoints.custom', value: [renamed(draft)] },
+ ],
+ renames: hint,
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body?.skipped).toEqual([
+ {
+ path: 'interface.prompts',
+ segments: ['interface', 'prompts'],
+ reason: 'interface_permission',
+ },
+ ]);
+ expect((await storedEndpoint(role, 'final'))?.apiKey).toBe(draft.apiKey);
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["final"].headers.X-Legacy',
+ ]);
+ });
+
+ it('on PUT does the same for a whole replace', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+
+ const res = await put(role, {
+ overrides: { endpoints: { custom: [renamed(draft)] } },
+ renames: hint,
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect((await storedEndpoint(role, 'final'))?.apiKey).toBe(draft.apiKey);
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["final"].headers.X-Legacy',
+ ]);
+ });
+
+ it('without a hint, the renamed entry keeps no key and the tombstones stay on the old name', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+
+ const res = await patch(role, {
+ entries: [{ fieldPath: 'endpoints.custom', value: [renamed(draft)] }],
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect((await storedEndpoint(role, 'final'))?.apiKey).toBeUndefined();
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["draft"].headers.X-Legacy',
+ ]);
+ });
+
+ it('that sends the carried key somewhere else needs it entered again', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+
+ const res = await patch(role, {
+ entries: [
+ {
+ fieldPath: 'endpoints.custom',
+ value: [renamed(draft, { baseURL: 'https://collector.example.com/v1' })],
+ },
+ ],
+ renames: hint,
+ });
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toMatchObject({
+ code: 'CONFIG_SECRET_REENTRY_REQUIRED',
+ issues: [expect.objectContaining({ path: 'endpoints.custom.0.baseURL' })],
+ });
+ expect(await storedEndpoint(role, 'draft')).toEqual(draft);
+ });
+
+ it('is refused when it cannot apply, storing nothing', async () => {
+ const role = nextRole();
+ const draft = await seedDraft(role);
+ await changes(role, {
+ ops: [{ op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: endpoint('taken') }],
+ });
+ const before = await storedDocument(role);
+ const write = (custom: Endpoint[], renames: unknown) =>
+ patch(role, { entries: [{ fieldPath: 'endpoints.custom', value: custom }], renames });
+ const final = renamed(draft);
+
+ const cases: Array<[Endpoint[], unknown, string]> = [
+ [
+ [final],
+ [{ path: 'endpoints.custom', previousName: 'Literal', name: 'final' }],
+ 'inherited_entry',
+ ],
+ [
+ [endpoint('Literal')],
+ [{ path: 'endpoints.custom', previousName: 'draft', name: 'Literal' }],
+ 'inherited_entry',
+ ],
+ [
+ [final],
+ [{ path: 'endpoints.custom', previousName: 'missing', name: 'final' }],
+ 'source_not_found',
+ ],
+ [
+ [endpoint('taken')],
+ [{ path: 'endpoints.custom', previousName: 'draft', name: 'taken' }],
+ 'target_exists',
+ ],
+ [[endpoint('other')], hint, 'target_not_written'],
+ [[final, { ...draft, apiKey: undefined }], hint, 'source_still_written'],
+ [
+ [final],
+ [{ path: 'endpoints.custom', previousName: 'Ollama', name: 'ollama' }],
+ 'invalid_name',
+ ],
+ [
+ [final],
+ [{ path: 'endpoints.custom', previousName: 'draft', name: '$final' }],
+ 'invalid_name',
+ ],
+ [
+ [final, renamed(draft, { name: 'copy' })],
+ [...hint, { path: 'endpoints.custom', previousName: 'draft', name: 'copy' }],
+ 'duplicate_source',
+ ],
+ ];
+ for (const [custom, renames, reason] of cases) {
+ const res = await write(custom, renames);
+ expect(res.statusCode).toBe(400);
+ expect(res.body).toEqual({
+ error: 'Invalid rename hint',
+ code: 'CONFIG_RENAME_INVALID',
+ reason,
+ });
+ }
+ expect(await storedDocument(role)).toEqual(before);
+ });
+ });
+
+ it('a batch rename moves the keyed tombstones and keeps the key', async () => {
+ const role = nextRole();
+ const draft = await storeOwnKey(role, 'draft');
+ await tombstone(role, 'endpoints.custom["draft"].headers.X-Legacy');
+
+ const res = await changes(role, {
+ ops: [{ op: 'rename', fieldPath: 'endpoints.custom', from: 'draft', to: 'final' }],
+ });
+
+ expect(res.statusCode).toBe(200);
+ expect((await storedEndpoint(role, 'final'))?.apiKey).toBe(draft.apiKey);
+ expect((await storedDocument(role))?.tombstones).toEqual([
+ 'endpoints.custom["final"].headers.X-Legacy',
+ ]);
+ const refused = await changes(role, {
+ ops: [{ op: 'rename', fieldPath: 'endpoints.custom', from: 'final', to: '$final' }],
+ });
+ expect(refused.statusCode).toBe(400);
+ expect(refused.body).toMatchObject({ code: 'CONFIG_ENTRY_INVALID', reason: 'invalid_entry' });
+ });
+
+ it('a rename keeps the destination fingerprint of a key entered over a Base endpoint', async () => {
+ const role = nextRole();
+ const base = dataSchemas.BASE_CONFIG_PRINCIPAL_ID;
+ const team = endpoint('Team', { apiKey: 'sk-base-team-key-0123456789' });
+ expect(
+ (
+ await changes(base, {
+ ops: [{ op: 'upsertEntry', fieldPath: 'endpoints.custom', entry: team }],
+ })
+ ).statusCode,
+ ).toBe(200);
+ try {
+ const entered = await changes(role, {
+ ops: [
+ {
+ op: 'upsertEntry',
+ fieldPath: 'endpoints.custom',
+ entry: { name: 'Team', apiKey: 'sk-role-own-team-key-0123456789' },
+ },
+ ],
+ });
+ expect(entered.statusCode).toBe(200);
+ expect(entered.body?.ignored).toEqual([]);
+ const own = await storedEndpoint(role, 'Team');
+ expect(own?.apiKeyBinding).toEqual(expect.any(String));
+
+ const res = await patch(role, {
+ entries: [
+ {
+ fieldPath: 'endpoints.custom',
+ value: [{ name: 'Team 2', baseURL: team.baseURL, models: team.models }],
+ },
+ ],
+ renames: [{ path: 'endpoints.custom', previousName: 'Team', name: 'Team 2' }],
+ });
+
+ expect(res.statusCode).toBe(200);
+ const moved = await storedEndpoint(role, 'Team 2');
+ expect(moved?.apiKey).toBe(own?.apiKey);
+ expect(moved?.apiKeyBinding).toBe(own?.apiKeyBinding);
+ } finally {
+ await methods.deleteConfig(PrincipalType.ROLE, base);
+ }
+ });
+});
diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.ts
index 87120101a4..c505ec2a36 100644
--- a/packages/api/src/admin/config.ts
+++ b/packages/api/src/admin/config.ts
@@ -35,9 +35,11 @@ import {
isConfigArrayItemPath,
isAcceptedOverrideSection,
MAX_CONFIG_CHANGE_OPS,
+ MAX_CONFIG_ENTRY_KEY_LENGTH,
getConfigChangeIssues,
getConfigArrayMergeKey,
getIndexedMergeKeyIssues,
+ getLiftedConfigTombstones,
getConfigBatchWrittenPaths,
isSameConfigValue,
isConfigRevision,
@@ -69,6 +71,12 @@ import {
toConfigIdentityPath,
renameConfigIdentityPath,
resolveConfigIdentityPath,
+ parseConfigPath,
+ formatKeyedPath,
+ isConfigEntryKey,
+ isKeyedConfigPath,
+ isConfigEntryArrayItemPath,
+ renameConfigEntriesTombstones,
} from '@librechat/data-schemas';
import type {
AppConfig,
@@ -92,6 +100,7 @@ import type {
AdminConfigSkipReason,
AdminConfigIgnoreReason,
AdminConfigIgnoredSecret,
+ AdminConfigAppliedLocation,
AdminConfigLocation,
AdminConfigWriteReport,
AdminConfigErrorCode,
@@ -104,6 +113,9 @@ import type {
ConfigMutationOutcome,
ConfigMutationPlan,
ConfigIdentityStep,
+ ConfigEntryStep,
+ ConfigLocation,
+ ConfigEntryRename,
YamlHeldPath,
} from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
@@ -117,6 +129,8 @@ import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import type { SecretReentry } from './reentry';
import {
+ RENAME_HINT_PATHS,
+ getArraySecretKey,
encryptConfigSecretFields,
encryptConfigSecrets,
carryRenamedConfigSecrets,
@@ -133,20 +147,21 @@ import {
redactConfigSecrets,
redactResolvedConfigSecrets,
} from './secrets';
-import {
- parseEnvAllowlist,
- getEnvReferenceIssues,
- createEnvReferencePolicy,
- ENV_REFERENCE_NOT_ALLOWED,
- hasDisallowedStoredReference,
-} from '~/app/allowlist';
import {
SECRET_BINDINGS,
REBINDING_SECTIONS,
+ getSecretBindingKey,
getRebindingIdentity,
toIgnoredSecretOverride,
withoutStoredSecretBindings,
} from '~/app/rebinding';
+import {
+ parseEnvAllowlist,
+ getEnvReferenceIssues,
+ createEnvReferencePolicy,
+ ENV_REFERENCE_NOT_ALLOWED,
+ hasDisallowedStoredReference,
+} from '~/app/allowlist';
import {
MCP_SERVER_SECTIONS,
findSecretReentry,
@@ -244,26 +259,57 @@ 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`.
+ * section, permission and secret guards read; it names exactly `segments` when `dotFree`. With
+ * `entry`, the target is one entry of the array merged by key at `segments`, by its key, or a
+ * path inside it, and `fieldPath` is its canonical keyed path (`endpoints.custom["Name"]`).
*/
interface FieldTarget {
segments: string[];
fieldPath: string;
dotFree: boolean;
+ entry?: ConfigEntryStep;
}
type FieldTargetRead =
| { ok: true; target: FieldTarget }
| { ok: false; error: string; reason?: ConfigPathErrorReason };
+const KEYED_PATH_ERROR =
+ 'Invalid keyed path: an entry is named by a JSON string key right after an array merged by key, as in endpoints.custom["Name"].headers';
+
+/**
+ * Reads a keyed `fieldPath` (`endpoints.custom["Name"].headers.X`): one entry of an array
+ * merged by key, by its key, and a path inside it. Nothing submitted is echoed back.
+ */
+function readKeyedTarget(fieldPath: string): FieldTargetRead {
+ const location = parseConfigPath(fieldPath);
+ if (!location?.entry || !getConfigArrayMergeKey(location.segments)) {
+ return { ok: false, error: KEYED_PATH_ERROR, reason: 'keyed_path' };
+ }
+ const { key, rest } = location.entry;
+ return {
+ ok: true,
+ target: {
+ segments: [...location.segments],
+ fieldPath: formatKeyedPath(location.segments, key, rest),
+ dotFree: true,
+ entry: { key, rest: [...rest] },
+ },
+ };
+}
+
/**
* 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.
+ * dotted paths, and on a registered secret's path. A `fieldPath` holding an entry key step
+ * (`["`) is read as a keyed path ({@link readKeyedTarget}).
*/
function readFieldTarget(fieldPath: unknown, segments: unknown): FieldTargetRead {
if (segments === undefined) {
+ if (typeof fieldPath === 'string' && isKeyedConfigPath(fieldPath)) {
+ return readKeyedTarget(fieldPath);
+ }
if (typeof fieldPath !== 'string' || !isValidFieldPath(fieldPath)) {
return { ok: false, error: `Invalid or unsafe field path: ${String(fieldPath)}` };
}
@@ -363,7 +409,7 @@ function toOrderedWrites(
}
/** One step of a field patch: a write, or the reset of a path (a secret with its preview). */
-type PatchStep = { write: ConfigFieldWrite } | { reset: string[][] };
+type PatchStep = { write: ConfigFieldWrite } | { reset: ConfigLocation[] };
/**
* A field patch's steps in request order: each entry's writes as {@link toOrderedWrites} orders
@@ -410,25 +456,27 @@ function toStepWrites(steps: readonly PatchStep[]): ConfigFieldWrite[] {
/**
* Validation of a patch with resets, as `getConfigFieldIssues` judges writes alone: the end
- * state the steps leave, with issues on every written or reset path, and those it introduced.
+ * state the steps leave, with the keyed tombstones of each renamed entry (`renames`) moved to
+ * its new key, and issues on every written or reset path, and those it introduced.
*/
function getPatchStepIssues(
steps: readonly PatchStep[],
floor: Partial<TCustomConfig>,
stored: ConfigRecord | null,
+ renames: readonly ConfigEntryRename[],
): ConfigOverrideIssue[] {
const written = steps.flatMap((step) =>
- 'write' in step ? [[...step.write.segments]] : step.reset,
+ 'write' in step ? [[...step.write.segments]] : step.reset.map(({ segments }) => [...segments]),
);
const indexed = getIndexedMergeKeyIssues(written);
if (indexed.length > 0) {
return indexed;
}
- const lifted = toStepWrites(steps)
- .map(({ segments }) => [...segments])
- .filter(isDotFreePath)
- .map((segments) => segments.join('.'));
- const candidate = applyPatchSteps(toConfigOverrideState(stored), steps);
+ const lifted = getLiftedConfigTombstones(toStepWrites(steps).map(({ segments }) => segments));
+ const candidate = renameConfigEntriesTombstones(
+ applyPatchSteps(toConfigOverrideState(stored), steps),
+ renames,
+ );
return getConfigChangeIssues(candidate, floor, stored, written, lifted);
}
@@ -770,6 +818,24 @@ function toLocation(segments: readonly string[]): AdminConfigLocation {
return { path: segments.join('.'), segments: [...segments] };
}
+/**
+ * The report of a write at one field target: a keyed target by its keyed path, its collection,
+ * the entry key and the path inside the entry, as a change ref names it.
+ */
+function toTargetReport(target: FieldTarget): AdminConfigWriteReport {
+ if (!target.entry) {
+ return { applied: [toLocation(target.segments)], skipped: [] };
+ }
+ const { key, rest } = target.entry;
+ const applied: AdminConfigAppliedLocation = {
+ path: target.fieldPath,
+ segments: [...target.segments],
+ key,
+ ...(rest.length > 0 && { entryPath: [...rest] }),
+ };
+ return { applied: [applied], skipped: [] };
+}
+
/**
* Positional slot where config methods once took a Mongoose `ClientSession`; the portable
* config store does not join transactions.
@@ -1419,10 +1485,30 @@ const UNSAFE_NAME = /^(?:\$|__)|^(?:constructor|prototype)$/;
type RenamesRead = { ok: true; renames: ConfigSecretRename[] } | { ok: false; reason: string };
+const RENAME_PATHS: ReadonlySet<string> = new Set(RENAME_HINT_PATHS);
+
+function isRenamePath(path: unknown): path is ConfigSecretRename['path'] {
+ return typeof path === 'string' && RENAME_PATHS.has(path);
+}
+
+/** Whether a hint renames entries of an array merged by key, rather than keys of a record. */
+function isEntryRename(rename: ConfigSecretRename): boolean {
+ return getConfigArrayMergeKey(parseFieldPath(rename.path)) !== undefined;
+}
+
+/** How a hint's name is compared with the others of its path: an entry key by its identity. */
+function getRenameIdentity(path: ConfigSecretRename['path'], name: string): string {
+ return getConfigEntryIdentity(parseFieldPath(path), name);
+}
+
/**
- * Reads the body's `renames` hint: `[{ path: 'mcpServers', previousName, name }]`, telling the
- * write that the server it writes as `name` was renamed (or duplicated) from the stored
- * `previousName`, so secrets it omits are carried from there. Never stored.
+ * Reads the body's `renames` hint: `[{ path, previousName, name }]` for `mcpServers` (a server
+ * renamed or duplicated from the stored `previousName`) or `endpoints.custom` (a custom endpoint
+ * renamed from the stored entry named `previousName`), telling the write to carry the secrets the
+ * entry it writes as `name` omits from there. Never stored. A custom endpoint name must be one a
+ * keyed path can address (`isConfigEntryKey`), since the entry's keyed tombstones move with it,
+ * and one entry is renamed once per write (`duplicate_source`): its tombstones move to one name.
+ * A server may be duplicated, so several hints may share its `previousName`.
*/
function readRenames(value: unknown): RenamesRead {
if (value === undefined || value === null) {
@@ -1433,9 +1519,10 @@ function readRenames(value: unknown): RenamesRead {
}
const renames: ConfigSecretRename[] = [];
const targets = new Set<string>();
+ const sources = new Set<string>();
for (const item of value) {
const { path, previousName, name } = (item ?? {}) as Record<string, unknown>;
- if (path !== 'mcpServers') {
+ if (!isRenamePath(path)) {
return { ok: false, reason: 'unsupported_path' };
}
if (
@@ -1443,21 +1530,41 @@ function readRenames(value: unknown): RenamesRead {
typeof name !== 'string' ||
previousName === '' ||
name === '' ||
- previousName === name ||
UNSAFE_NAME.test(previousName) ||
- UNSAFE_NAME.test(name)
+ UNSAFE_NAME.test(name) ||
+ getRenameIdentity(path, previousName) === getRenameIdentity(path, name)
) {
return { ok: false, reason: 'invalid_name' };
}
- if (targets.has(name)) {
+ const rename: ConfigSecretRename = { path, previousName, name };
+ const entry = isEntryRename(rename);
+ if (entry && (!isConfigEntryKey(previousName) || !isConfigEntryKey(name))) {
+ return { ok: false, reason: 'invalid_name' };
+ }
+ const target = JSON.stringify([path, getRenameIdentity(path, name)]);
+ if (targets.has(target)) {
return { ok: false, reason: 'duplicate_target' };
}
- targets.add(name);
- renames.push({ path, previousName, name });
+ targets.add(target);
+ const source = JSON.stringify([path, getRenameIdentity(path, previousName)]);
+ if (entry && sources.has(source)) {
+ return { ok: false, reason: 'duplicate_source' };
+ }
+ sources.add(source);
+ renames.push(rename);
}
return { ok: true, renames };
}
+/** The entry renames a hint carries out, which move the old entries' keyed tombstones. */
+function toEntryRenames(renames: readonly ConfigSecretRename[]): ConfigEntryRename[] {
+ return renames.filter(isEntryRename).map(({ path, previousName, name }) => ({
+ segments: parseFieldPath(path),
+ from: previousName,
+ to: name,
+ }));
+}
+
function invalidRenameResponse(res: Response, reason: string): Response {
return res
.status(400)
@@ -1475,15 +1582,85 @@ function writesTarget(writes: readonly ConfigFieldWrite[], target: readonly stri
}
/**
- * Why a rename hint cannot apply to this write: its source is not a stored server, or the write
- * does not write its target.
+ * The entries `writes` leave in the merged-by-key array at `segments`: those of the last write
+ * that covers it, or `undefined` when none does or it leaves no array there.
+ */
+function getWrittenArray(
+ writes: readonly ConfigFieldWrite[],
+ segments: readonly string[],
+): unknown[] | undefined {
+ let items: unknown[] | undefined;
+ let covered = false;
+ for (const write of writes) {
+ if (isSegmentPrefix(write.segments, segments)) {
+ const value = getAtPath(write.value, segments.slice(write.segments.length));
+ items = Array.isArray(value) ? value : undefined;
+ covered = true;
+ }
+ }
+ return covered ? items : undefined;
+}
+
+/** Whether `items` holds an entry of the merged-by-key array at `segments` keyed `name`. */
+function holdsEntry(items: unknown, segments: readonly string[], name: string): boolean {
+ const keyField = getConfigArrayMergeKey(segments);
+ return (
+ keyField !== undefined &&
+ Array.isArray(items) &&
+ items.some(getConfigEntryMatcher(segments, keyField, name))
+ );
+}
+
+/**
+ * Why an entry rename hint cannot apply to this write: either name is one librechat.yaml
+ * defines (`inherited_entry`, as for a batch `rename`), `previousName` is not a stored entry of
+ * the principal (`source_not_found`), `name` already is one (`target_exists`), the write does not
+ * write `name` (`target_not_written`) or still writes `previousName` (`source_still_written`).
+ */
+function getEntryRenameIssue(
+ { path, previousName, name }: ConfigSecretRename,
+ stored: { overrides?: unknown } | null,
+ writes: readonly ConfigFieldWrite[],
+ base: Partial<TCustomConfig>,
+): string | null {
+ const segments = parseFieldPath(path);
+ const yamlItems = getAtPath(base, segments);
+ if (holdsEntry(yamlItems, segments, previousName) || holdsEntry(yamlItems, segments, name)) {
+ return 'inherited_entry';
+ }
+ const storedItems = getAtPath(stored?.overrides, segments);
+ if (!holdsEntry(storedItems, segments, previousName)) {
+ return 'source_not_found';
+ }
+ if (holdsEntry(storedItems, segments, name)) {
+ return 'target_exists';
+ }
+ const written = getWrittenArray(writes, segments);
+ if (!holdsEntry(written, segments, name)) {
+ return 'target_not_written';
+ }
+ return holdsEntry(written, segments, previousName) ? 'source_still_written' : null;
+}
+
+/**
+ * Why a rename hint cannot apply to this write: for a server, its source is not a stored server,
+ * or the write does not write its target; for a custom endpoint, see {@link getEntryRenameIssue}.
*/
function getRenameIssue(
renames: readonly ConfigSecretRename[],
stored: { overrides?: unknown } | null,
writes: readonly ConfigFieldWrite[],
+ base: Partial<TCustomConfig>,
): string | null {
- for (const { path, previousName, name } of renames) {
+ for (const rename of renames) {
+ if (isEntryRename(rename)) {
+ const issue = getEntryRenameIssue(rename, stored, writes, base);
+ if (issue) {
+ return issue;
+ }
+ continue;
+ }
+ const { path, previousName, name } = rename;
const storedRecord = (stored?.overrides as Record<string, unknown> | undefined)?.[path];
if (
storedRecord == null ||
@@ -1675,10 +1852,10 @@ interface PreparedChange {
/** `upsertEntry`: the entry with secrets encrypted. */
entry?: Record<string, unknown>;
/**
- * `unset` and `tombstone`: the paths removed together (a secret and its preview). `set`: the
- * paths it resets instead, when nothing of its value is stored.
+ * `unset` and `tombstone`: the paths removed together (a secret and its preview), or the keyed
+ * location. `set`: the paths it resets instead, when nothing of its value is stored.
*/
- paths?: string[][];
+ paths?: ConfigLocation[];
}
type PreparedRead =
@@ -1716,6 +1893,9 @@ function toChangeRef(
if (change.key !== undefined && change.op !== 'rename') {
ref.key = change.key;
}
+ if (change.target.entry && change.target.entry.rest.length > 0) {
+ ref.entryPath = [...change.target.entry.rest];
+ }
return ref;
}
@@ -1727,11 +1907,69 @@ function isNonEmptyString(value: unknown): value is string {
return typeof value === 'string' && value !== '';
}
-/** The paths an `unset` of `target` removes together: a secret and its preview companion. */
-function getRemovalPaths(target: FieldTarget): string[][] {
+/**
+ * The locations an `unset` of `target` removes together: a secret and its preview companion,
+ * or a keyed target's entry location.
+ */
+function getRemovalPaths(target: FieldTarget): ConfigLocation[] {
+ if (target.entry) {
+ return [{ segments: target.segments, entry: target.entry }];
+ }
return target.dotFree
- ? getConfigSecretMutationPaths(target.fieldPath).map(parseFieldPath)
- : [target.segments];
+ ? getConfigSecretMutationPaths(target.fieldPath).map((path) => ({
+ segments: parseFieldPath(path),
+ }))
+ : [{ segments: target.segments }];
+}
+
+const INSIDE_ARRAY_TOMBSTONE_ERROR =
+ 'A tombstone can hide a whole array, not an element or a path inside one; hide an entry of a collection merged by key by its key, as in endpoints.custom["Name"]';
+
+const KEYED_WRITE_ERROR =
+ 'A keyed path can be hidden (tombstone) or reset (unset), not written: write the entry in its collection';
+
+/** A 400 a keyed target answers with: a message, a stable code and a reason. */
+interface KeyedTargetError {
+ error: string;
+ code: 'CONFIG_PATH_INVALID' | 'SECRET_PATH';
+ reason?: ConfigPathErrorReason;
+}
+
+/**
+ * Why a keyed target cannot be hidden or reset, checked before anything is read: it names the
+ * entry's key field (hide the whole entry instead), the entry's registered secret, its preview
+ * or its destination fingerprint, or for a tombstone, a path inside one of the entry's own
+ * arrays, which the merge cannot hide part of.
+ */
+function getKeyedTargetError(target: FieldTarget, tombstone: boolean): KeyedTargetError | null {
+ const { segments, entry } = target;
+ if (!entry) {
+ return null;
+ }
+ const [field] = entry.rest;
+ if (field !== undefined && field === getConfigArrayMergeKey(segments)) {
+ return {
+ error: "An entry's key cannot be removed: hide or reset the whole entry instead",
+ code: 'CONFIG_PATH_INVALID',
+ reason: 'merge_key',
+ };
+ }
+ const secretKey = getArraySecretKey(segments.join('.'));
+ const removalError = getFieldRemovalError(target.fieldPath);
+ if (removalError || (secretKey && field === getSecretBindingKey(secretKey))) {
+ return {
+ error: 'Secret fields of an entry cannot be addressed by key: write the entry instead',
+ code: 'SECRET_PATH',
+ };
+ }
+ if (tombstone && isConfigEntryArrayItemPath(segments, entry.rest)) {
+ return {
+ error: 'A tombstone can hide a whole array, not an element or a path inside one',
+ code: 'CONFIG_PATH_INVALID',
+ reason: 'inside_array',
+ };
+ }
+ return null;
}
/**
@@ -1794,6 +2032,14 @@ function prepareEntryChange(
'invalid_entry',
);
}
+ if (keyField && !isConfigEntryKey(raw.to)) {
+ return changeFailure(
+ index,
+ 'An entry renamed in a collection merged by key needs a name a keyed path can address',
+ 'CONFIG_ENTRY_INVALID',
+ 'invalid_entry',
+ );
+ }
if (!keyField) {
if (!isConfigRecordPath(target.segments)) {
return changeFailure(
@@ -1862,17 +2108,29 @@ function prepareEntryChange(
function getChangeIdentity(
raw: Record<string, unknown>,
op: ChangeOpKind,
- segments: readonly string[],
+ target: FieldTarget,
): string {
- if (!isEntryOp(op)) {
- return JSON.stringify(['path', segments]);
- }
+ const { segments, entry } = target;
const toEntry = (key: unknown): string =>
JSON.stringify([
'entry',
segments,
typeof key === 'string' ? getConfigEntryIdentity(segments, key) : null,
]);
+ /** A keyed change of a whole entry addresses what an entry change of that key does. */
+ if (entry) {
+ return entry.rest.length === 0
+ ? toEntry(entry.key)
+ : JSON.stringify([
+ 'entry',
+ segments,
+ getConfigEntryIdentity(segments, entry.key),
+ entry.rest,
+ ]);
+ }
+ if (!isEntryOp(op)) {
+ return JSON.stringify(['path', segments]);
+ }
if (op === 'rename') {
return toEntry(raw.from);
}
@@ -1914,6 +2172,9 @@ function prepareChange(raw: unknown, index: number): PreparedRead {
if (op !== 'unset' && !isAcceptedOverrideSection(section)) {
return changeFailure(index, 'Unknown config section', 'UNKNOWN_SECTION');
}
+ if (target.entry && op !== 'unset' && op !== 'tombstone') {
+ return changeFailure(index, KEYED_WRITE_ERROR, 'CONFIG_PATH_INVALID', 'keyed_path');
+ }
const sectionSkip = getFieldSkipReason(target.fieldPath);
let prepared:
@@ -1932,31 +2193,41 @@ function prepareChange(raw: unknown, index: number): PreparedRead {
'dotted_segment',
);
}
- if (op === 'tombstone' && isConfigArrayItemPath(target.segments)) {
+ const keyedError = getKeyedTargetError(target, op === 'tombstone');
+ if (keyedError) {
+ return changeFailure(index, keyedError.error, keyedError.code, keyedError.reason);
+ }
+ if (op === 'tombstone' && !target.entry && isConfigArrayItemPath(target.segments)) {
return changeFailure(
index,
- 'A tombstone can hide a whole array, not an element or a path inside one',
+ INSIDE_ARRAY_TOMBSTONE_ERROR,
'CONFIG_PATH_INVALID',
'inside_array',
);
}
- const removalError = target.dotFree ? getFieldRemovalError(target.fieldPath) : null;
+ const removalError =
+ target.dotFree && !target.entry ? getFieldRemovalError(target.fieldPath) : null;
if (removalError) {
return changeFailure(index, removalError.error, removalError.code);
}
/** Unsetting a stored field only librechat.yaml sets is cleanup: only a tombstone is skipped. */
const skipReason =
sectionSkip ?? (op === 'tombstone' ? getHeldPathSkipReason(target.segments) : null);
+ const change: PreparedChange = {
+ ...base,
+ key: target.entry?.key,
+ paths: getRemovalPaths(target),
+ };
prepared = skipReason
- ? { ok: true, change: null, skipped: [{ ...toChangeRef(base), reason: skipReason }] }
- : { ok: true, change: { ...base, paths: getRemovalPaths(target) }, skipped: [] };
+ ? { ok: true, change: null, skipped: [{ ...toChangeRef(change), reason: skipReason }] }
+ : { ok: true, change, skipped: [] };
}
if (!prepared.ok) {
return prepared;
}
return {
ok: true,
- identity: getChangeIdentity(raw, op, target.segments),
+ identity: getChangeIdentity(raw, op, target),
section,
change: prepared.change,
skipped: prepared.skipped,
@@ -1969,7 +2240,7 @@ function expandChange(change: PreparedChange, overrides: unknown): ConfigChange[
switch (change.op) {
case 'set': {
if (change.paths) {
- return change.paths.map((path) => ({ op: 'unset', segments: path }));
+ return change.paths.map((path) => ({ op: 'unset', segments: path.segments }));
}
if (!change.fields) {
return [{ op: 'set', segments, value: change.value }];
@@ -1982,8 +2253,8 @@ function expandChange(change: PreparedChange, overrides: unknown): ConfigChange[
}
case 'unset':
case 'tombstone':
- return (change.paths ?? [segments]).map(
- (path) => ({ op: change.op, segments: path }) as ConfigChange,
+ return (change.paths ?? [{ segments }]).map(
+ (path) => ({ op: change.op, segments: path.segments, entry: path.entry }) as ConfigChange,
);
case 'upsertEntry': {
/** An entry that omits its secret keeps the one stored on the entry of the same key. */
@@ -2115,6 +2386,9 @@ function withoutProcessServers(
/** How an applied change is named in audit metadata: its path, plus the entry it addressed. */
function describeChange(change: PreparedChange): string {
const path = describeFieldTarget(change.target);
+ if (change.target.entry) {
+ return path;
+ }
if (change.op === 'rename') {
return `${path}[${JSON.stringify(change.key)}->${JSON.stringify(change.to)}]`;
}
@@ -2908,6 +3182,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const meta = buildAdminConfigMeta({
maxPatchEntries: MAX_PATCH_ENTRIES,
maxChangeOps: MAX_CONFIG_CHANGE_OPS,
+ maxEntryKeyLength: MAX_CONFIG_ENTRY_KEY_LENGTH,
overrideCacheTtlMs,
catalogModelsTtlMs: getCatalogModelsTtlMs(baseConfig),
});
@@ -3219,23 +3494,27 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
) {
return { draft: null, result: { status: 403 } };
}
- const renameIssue = getRenameIssue(renames.renames, stored, requestWrites);
+ const renameIssue = getRenameIssue(renames.renames, stored, requestWrites, baseYaml);
if (renameIssue) {
return { draft: null, result: { status: 400, renameIssue } };
}
/** Secrets an object omits are kept before validation sees the document. */
const preserved = preserveConfigSecrets(encryptedOverrides, stored?.overrides);
carryRenamedConfigSecrets(preserved, stored?.overrides, renames.renames);
- /** A full replace keeps the principal's tombstones, so they shape its base. */
+ /** A full replace keeps the principal's tombstones (a renamed entry's move with it). */
+ const storedState = renameConfigEntriesTombstones(
+ toConfigOverrideState(stored),
+ toEntryRenames(renames.renames),
+ );
const issues = getConfigOverrideIssues(
preserved,
- applyConfigTombstones(floor, stored?.tombstones),
+ applyConfigTombstones(floor, storedState.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 candidate = replaceConfigOverrides(toConfigOverrideState(stored), preserved);
+ const candidate = replaceConfigOverrides(storedState, preserved);
const reentry = getKeptKeyReentryIssues(stored, candidate, entered, baseConfig);
if (reentry.length > 0) {
return { draft: null, result: { status: 400, reentry } };
@@ -3259,10 +3538,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalType,
principalId,
stored,
- candidate: replaceConfigOverrides(
- toConfigOverrideState(stored),
- next as Partial<TCustomConfig>,
- ),
+ candidate: replaceConfigOverrides(storedState, next as Partial<TCustomConfig>),
entered,
base,
baseConfig,
@@ -3411,6 +3687,9 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (!read.ok) {
return fieldTargetErrorResponse(res, read);
}
+ if (read.target.entry) {
+ return fieldTargetErrorResponse(res, { error: KEYED_WRITE_ERROR, reason: 'keyed_path' });
+ }
const section = getTopLevelSection(read.target.fieldPath);
if (!isAcceptedOverrideSection(section)) {
return unknownSectionResponse(res);
@@ -3568,7 +3847,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (!stored && !(await canCreateFor(principalType, principalId))) {
return { draft: null, result: { status: 404 } };
}
- const renameIssue = getRenameIssue(renames.renames, stored, requestWrites);
+ const renameIssue = getRenameIssue(renames.renames, stored, requestWrites, baseYaml);
if (renameIssue) {
return { draft: null, result: { status: 400, renameIssue } };
}
@@ -3584,13 +3863,18 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
const steps = toOrderedSteps(ordered, preservedFields);
const writes = toStepWrites(steps);
+ /** A renamed custom endpoint's keyed tombstones move to its new name. */
+ const entryRenames = toEntryRenames(renames.renames);
const fieldIssues = hasResets
- ? getPatchStepIssues(steps, floor, stored)
- : getConfigFieldIssues(writes, floor, stored);
+ ? getPatchStepIssues(steps, floor, stored, entryRenames)
+ : getConfigFieldIssues(writes, floor, stored, entryRenames);
if (fieldIssues.length > 0) {
return { draft: null, result: { status: 400, issues: fieldIssues } };
}
- const state = applyPatchSteps(toConfigOverrideState(stored), steps);
+ const state = renameConfigEntriesTombstones(
+ applyPatchSteps(toConfigOverrideState(stored), steps),
+ entryRenames,
+ );
/** A changed URL beside a stored key that stays needs that key entered again. */
const reentry = getKeptKeyReentryIssues(stored, state, entered, baseConfig);
if (reentry.length > 0) {
@@ -3684,6 +3968,10 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
/**
* POST /:principalType/:principalId/fields/tombstone — Suppress an inherited config path.
+ *
+ * An entry of an array merged by key is hidden by its key (`endpoints.custom["Name"]`, or a
+ * path inside it); a path into an array by position is refused, since the merge removes
+ * inherited values from objects only and would never apply it.
*/
async function tombstoneConfigField(req: ServerRequest, res: Response): Promise<Response> {
try {
@@ -3737,14 +4025,18 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
if (!isAcceptedOverrideSection(section)) {
return unknownSectionResponse(res);
}
- /** The merge hides inherited values in objects only, so a tombstone there would do nothing. */
- if (isConfigArrayItemPath(read.target.segments)) {
+ const keyedError = getKeyedTargetError(read.target, true);
+ if (keyedError) {
+ return res.status(400).json(keyedError);
+ }
+ /** The merge hides inherited values in objects only: an entry is hidden by its key. */
+ if (!read.target.entry && isConfigArrayItemPath(read.target.segments)) {
return fieldTargetErrorResponse(res, {
- error: 'A tombstone can hide a whole array, not an element or a path inside one',
+ error: INSIDE_ARRAY_TOMBSTONE_ERROR,
reason: 'inside_array',
});
}
- const removalError = getFieldRemovalError(fieldPath);
+ const removalError = read.target.entry ? null : getFieldRemovalError(fieldPath);
if (removalError) {
return errorResponse(res, 400, removalError.code, removalError.error);
}
@@ -3826,14 +4118,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const ignored = isBoundSecretSection(parseFieldPath(fieldPath)[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
- return sendWrittenConfig(
- res,
- 200,
- config,
- access,
- ignored,
- toWriteReport([read.target.segments], []),
- );
+ return sendWrittenConfig(res, 200, config, access, ignored, toTargetReport(read.target));
} catch (error) {
logger.error('[adminConfig] tombstoneConfigField error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to tombstone config field' });
@@ -3842,7 +4127,9 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
/**
* DELETE /:principalType/:principalId/fields?fieldPath=dotted.path
- * (or `?segments=<JSON array>` for a path whose keys contain dots)
+ * (or `?segments=<JSON array>` for a path whose keys contain dots, or a keyed path such as
+ * `endpoints.custom["Name"].headers`, which resets the principal's own entry or path and the
+ * keyed tombstones of that entry at or below it)
*
* Unlike the writes, a path under an unknown section is accepted: removing it only clears
* what an earlier write stored there (the merge ignores it either way), and it is the only
@@ -3883,7 +4170,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
const { target } = read;
const { fieldPath } = target;
- const removalError = getFieldRemovalError(fieldPath);
+ const keyedError = getKeyedTargetError(target, false);
+ if (keyedError) {
+ return res.status(400).json(keyedError);
+ }
+ const removalError = target.entry ? null : getFieldRemovalError(fieldPath);
if (removalError) {
return errorResponse(res, 400, removalError.code, removalError.error);
}
@@ -3924,7 +4215,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
let config: ConfigRecord | null;
try {
- if (isBoundRemoval(target)) {
+ if (target.entry || isBoundRemoval(target)) {
const outcome = await removeConfigPath(
principalType,
principalId,
@@ -3939,15 +4230,15 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
config = outcome.record;
} 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.
+ * A secret and its preview companion are removed together, in one write. Every path
+ * goes by its segments: the store reads a dotted string holding `["` as a keyed path,
+ * so a `segments` key such as `custom["Name"]` would otherwise reach an entry past the
+ * guards of the branch above. By segments it names that key as written.
*/
config = await unsetConfigField(
principalType,
principalId,
- target.dotFree
- ? getConfigSecretMutationPaths(fieldPath)
- : [{ segments: target.segments }],
+ getRemovalPaths(target),
undefined,
{ expectedRevision: expected.value },
);
@@ -3968,14 +4259,7 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
const ignored = isBoundSecretSection(target.segments[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
- return sendWrittenConfig(
- res,
- 200,
- config,
- access,
- ignored,
- toWriteReport([target.segments], []),
- );
+ return sendWrittenConfig(res, 200, config, access, ignored, toTargetReport(target));
} catch (error) {
logger.error('[adminConfig] deleteConfigField error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to delete config field' });
diff --git a/packages/api/src/admin/meta.spec.ts b/packages/api/src/admin/meta.spec.ts
index 0b09a69ce5..a850e1030d 100644
--- a/packages/api/src/admin/meta.spec.ts
+++ b/packages/api/src/admin/meta.spec.ts
@@ -15,6 +15,8 @@ import {
BASE_CONFIG_PRINCIPAL_ID,
isConfigOverrideStateEmpty,
ConfigRevisionConflictError,
+ MAX_CONFIG_ENTRY_KEY_LENGTH,
+ formatKeyedPath,
} from '@librechat/data-schemas';
import {
Constants,
@@ -313,6 +315,7 @@ describe('GET /api/admin/config/meta', () => {
'envStatus',
'expectedRevision',
'issueParams',
+ 'keyedTombstones',
'preAuthBaseOverrides',
'principalCheck',
'priorityRoute',
@@ -320,6 +323,7 @@ describe('GET /api/admin/config/meta', () => {
'readFilteredWriteResponses',
'recordSecrets',
'reloadRoute',
+ 'renameHints',
'resolvedApi',
'roleRenameMovesProfile',
'secretRebinding',
@@ -332,6 +336,7 @@ describe('GET /api/admin/config/meta', () => {
expect(meta.limits).toEqual({
maxPatchEntries: 100,
maxChangeOps: 1000,
+ maxEntryKeyLength: 256,
overrideCacheTtlMs: 60_000,
catalogModelsTtlMs: 120_000,
});
@@ -349,6 +354,7 @@ describe('GET /api/admin/config/meta', () => {
'processMcpFields',
'recordSecretFields',
'refusedMaps',
+ 'renameHintPaths',
'secretFields',
'titleResolution',
]);
@@ -383,6 +389,8 @@ describe('GET /api/admin/config/meta', () => {
writeReport: true,
issueParams: true,
adminTermsExempt: true,
+ keyedTombstones: true,
+ renameHints: true,
});
});
@@ -414,6 +422,8 @@ describe('meta rules equal the rules the server applies', () => {
it('lists the sections and paths of the live constants', () => {
expect(meta.rules.acceptedSections).toEqual(Object.keys(configSchema.shape));
+ expect(meta.rules.renameHintPaths).toEqual(['mcpServers', 'endpoints.custom']);
+ expect(meta.limits.maxEntryKeyLength).toBe(MAX_CONFIG_ENTRY_KEY_LENGTH);
expect(meta.rules.baseOnlySections).toEqual([...BASE_ONLY_CONFIG_SECTIONS]);
expect(meta.rules.basePrincipalSections).toEqual([...BASE_PRINCIPAL_CONFIG_SECTIONS]);
expect(meta.rules.baseOnlyPaths).toEqual([...BASE_ONLY_CONFIG_PATHS]);
@@ -1961,6 +1971,144 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {
};
return (await passes(true)) && !(await passes(false));
},
+ async keyedTombstones() {
+ const name = 'api.example.com "v2" [eu]';
+ const hiddenPath = formatKeyedPath(['endpoints', 'custom'], name);
+ const entry = (entryName: string): Doc => ({
+ name: entryName,
+ apiKey: '${GATEWAY_KEY}',
+ baseURL: 'https://gateway.example.com/v1',
+ models: { default: ['m'] },
+ headers: { 'X-Team': 'yaml', 'X-Trace': 'on' },
+ });
+ const yaml = {
+ endpoints: { custom: [entry(name), entry('kept')] },
+ modelSpecs: { list: [{ name: 's', label: 'S', preset: { endpoint: name, model: 'm' } }] },
+ };
+ const base = {
+ config: yaml,
+ endpoints: { custom: structuredClone(yaml.endpoints.custom) },
+ modelSpecs: structuredClone(yaml.modelSpecs),
+ } as Partial<AppConfig> as AppConfig;
+ const store = createMapStore();
+ const handlers = createHandlers({
+ ...storeDeps(store),
+ getAppConfig: jest.fn().mockResolvedValue(base),
+ });
+ const principal = { principalType: PrincipalType.ROLE, principalId: 'r1' };
+ const run = async (
+ handler: 'tombstoneConfigField' | 'deleteConfigField' | 'applyConfigChanges',
+ init: MockReqInit,
+ ) => {
+ const res = mockRes();
+ await handlers[handler](mockReq({ params: principal, ...init }), res);
+ return res;
+ };
+
+ const hidden = await run('tombstoneConfigField', { body: { fieldPath: hiddenPath } });
+ const header = await run('applyConfigChanges', {
+ body: { ops: [{ op: 'tombstone', fieldPath: 'endpoints.custom["kept"].headers.X-Team' }] },
+ });
+ const record = await store.read(principal);
+ if (hidden.statusCode !== 200 || header.statusCode !== 200 || !record) {
+ return false;
+ }
+ const merged = mergeConfigOverrides(base, [record]);
+ const served = (merged.endpoints?.custom ?? []) as Doc[];
+ const hides =
+ served.length === 1 &&
+ served[0].name === 'kept' &&
+ JSON.stringify(served[0].headers) === JSON.stringify({ 'X-Trace': 'on' });
+
+ const { getAppConfig } = createAppConfigService({
+ loadBaseConfig: async () => base,
+ setCachedTools: async () => undefined,
+ getCache: () => ({
+ get: async () => undefined,
+ set: async () => undefined,
+ delete: async () => true,
+ }),
+ cacheKeys: { APP_CONFIG: 'app_config' },
+ getApplicableConfigs: jest.fn().mockResolvedValue([record]),
+ getUserPrincipals: jest.fn().mockResolvedValue([]),
+ overrideEnvAllowlist: 'GATEWAY_KEY',
+ });
+ const specsHidden = !(await getAppConfig({ role: 'r1' })).modelSpecs?.list?.length;
+
+ const refused = await Promise.all(
+ [
+ ['endpoints.custom["kept"', 'keyed_path'],
+ ['modelSpecs.list["s"]', 'keyed_path'],
+ ['endpoints.custom["kept"].name', 'merge_key'],
+ ['endpoints.custom.0.headers', 'inside_array'],
+ ].map(async ([fieldPath, reason]) => {
+ const res = await run('tombstoneConfigField', { body: { fieldPath } });
+ return res.statusCode === 400 && res.body?.reason === reason;
+ }),
+ );
+ const secret = await run('tombstoneConfigField', {
+ body: { fieldPath: 'endpoints.custom["kept"].apiKey' },
+ });
+
+ const restored = await run('deleteConfigField', { query: { fieldPath: 'endpoints.custom' } });
+ return (
+ JSON.stringify(record.tombstones) ===
+ JSON.stringify([hiddenPath, 'endpoints.custom["kept"].headers.X-Team']) &&
+ hides &&
+ specsHidden &&
+ refused.every(Boolean) &&
+ secret.statusCode === 400 &&
+ secret.body?.code === 'SECRET_PATH' &&
+ restored.statusCode === 200 &&
+ (await store.read(principal))?.tombstones.length === 0
+ );
+ },
+ async renameHints() {
+ const { meta } = await getMeta();
+ const draft = {
+ name: 'draft',
+ baseURL: 'https://gateway.example.com/v1',
+ models: { default: ['m'] },
+ };
+ const [stored] = encryptConfigSecretFields({
+ 'endpoints.custom': [{ ...draft, apiKey: 'sk-endpoint-admin-secret' }],
+ })['endpoints.custom'] as Doc[];
+ const store = createMapStore();
+ const principal = { principalType: PrincipalType.ROLE, principalId: 'r1' };
+ await store.write(
+ principal,
+ {
+ principalModel: PrincipalModel.ROLE,
+ priority: 10,
+ isActive: true,
+ overrides: { endpoints: { custom: [stored] } } as ConfigDraft['overrides'],
+ tombstones: ['endpoints.custom["draft"].headers.X-Legacy'],
+ },
+ ABSENT_CONFIG_REVISION,
+ );
+ const res = mockRes();
+ await createHandlers(storeDeps(store)).patchConfigField(
+ mockReq({
+ params: principal,
+ body: {
+ entries: [{ fieldPath: 'endpoints.custom', value: [{ ...draft, name: 'final' }] }],
+ renames: [{ path: 'endpoints.custom', previousName: 'draft', name: 'final' }],
+ },
+ }),
+ res,
+ );
+ const record = await store.read(principal);
+ const [final] = (getIn(record?.overrides ?? {}, 'endpoints.custom') as Doc[] | undefined) ?? [];
+ return (
+ meta.rules.renameHintPaths.includes('endpoints.custom') &&
+ res.statusCode === 200 &&
+ final?.name === 'final' &&
+ final.apiKey === stored.apiKey &&
+ final.apiKeyPreview === stored.apiKeyPreview &&
+ JSON.stringify(record?.tombstones) ===
+ JSON.stringify(['endpoints.custom["final"].headers.X-Legacy'])
+ );
+ },
};
describe('meta feature flags', () => {
diff --git a/packages/api/src/admin/meta.ts b/packages/api/src/admin/meta.ts
index 0affa14f12..a8058a6c6b 100644
--- a/packages/api/src/admin/meta.ts
+++ b/packages/api/src/admin/meta.ts
@@ -14,7 +14,7 @@ import {
RUNTIME_CONFIG_INTERFACE_FIELDS,
} from 'librechat-data-provider';
import type { AppConfig, AdminConfigFeatures, AdminConfigMeta } from '@librechat/data-schemas';
-import { getConfigSecretRules } from './secrets';
+import { RENAME_HINT_PATHS, getConfigSecretRules } from './secrets';
/**
* How long `GET /catalog` reuses a scope's model lists while its endpoint config is unchanged:
@@ -56,6 +56,8 @@ export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {
writeReport: true,
issueParams: true,
adminTermsExempt: true,
+ keyedTombstones: true,
+ renameHints: true,
};
/**
@@ -74,6 +76,7 @@ export function buildAdminConfigMeta(limits: AdminConfigMeta['limits']): AdminCo
limits: { ...limits },
rules: {
acceptedSections: Object.keys(configSchema.shape),
+ renameHintPaths: [...RENAME_HINT_PATHS],
baseOnlySections: [...BASE_ONLY_CONFIG_SECTIONS],
basePrincipalSections: [...BASE_PRINCIPAL_CONFIG_SECTIONS],
baseOnlyPaths: [...BASE_ONLY_CONFIG_PATHS],
diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.ts
index fffadf0bda..8f8ae414ea 100644
--- a/packages/api/src/admin/secrets.integration.spec.ts
+++ b/packages/api/src/admin/secrets.integration.spec.ts
@@ -2098,6 +2098,30 @@ describe('MCP server credentials — real handlers against a real Config collect
expect(res.body).toMatchObject({ code: 'MCP_API_KEY_REENTRY_REQUIRED', server: 'code' });
});
+ it('duplicates a server to two names from one stored source', async () => {
+ const principalId = await seed();
+ const source = await storedServer(principalId, 'github');
+
+ const res = await patch(
+ principalId,
+ [
+ { fieldPath: 'mcpServers.code', value: renamed() },
+ { fieldPath: 'mcpServers.copy', value: renamed() },
+ ],
+ {
+ renames: [
+ { path: 'mcpServers', previousName: 'github', name: 'code' },
+ { path: 'mcpServers', previousName: 'github', name: 'copy' },
+ ],
+ },
+ );
+
+ expect(res.statusCode).toBe(200);
+ for (const name of ['code', 'copy']) {
+ expect((await storedServer(principalId, name)).apiKey.key).toBe(source.apiKey.key);
+ }
+ });
+
it('without a hint, a renamed server keeps no credential', async () => {
const principalId = await seed();
@@ -2113,7 +2137,11 @@ describe('MCP server credentials — real handlers against a real Config collect
const write = [{ fieldPath: 'mcpServers.code', value: renamed() }];
const cases: Array<[unknown, string]> = [
- [[{ path: 'endpoints.custom', previousName: 'github', name: 'code' }], 'unsupported_path'],
+ [
+ [{ path: 'endpoints.azureOpenAI.groups', previousName: 'github', name: 'code' }],
+ 'unsupported_path',
+ ],
+ [[{ path: 'endpoints.custom', previousName: 'github', name: 'code' }], 'source_not_found'],
[[{ path: 'mcpServers', previousName: 'github', name: 'github' }], 'invalid_name'],
[[{ path: 'mcpServers', previousName: '__proto__', name: 'code' }], 'invalid_name'],
[[{ path: 'mcpServers', previousName: 'missing', name: 'code' }], 'source_not_found'],
diff --git a/packages/api/src/admin/secrets.spec.ts b/packages/api/src/admin/secrets.spec.ts
index 9239881463..761b896ac4 100644
--- a/packages/api/src/admin/secrets.spec.ts
+++ b/packages/api/src/admin/secrets.spec.ts
@@ -1432,6 +1432,92 @@ describe('MCP server secrets (record registry)', () => {
});
});
+describe('custom endpoint secrets of keyed paths and renames', () => {
+ type Entry = Record<string, string>;
+ const customOf = (root: unknown): Entry[] =>
+ (root as { endpoints: { custom: Entry[] } }).endpoints.custom;
+ const entry = (name: string, extra: Entry = {}): Entry => ({
+ name,
+ baseURL: `https://${name}.example.com/v1`,
+ ...extra,
+ });
+
+ it('refuses a keyed path to an entry secret or its preview, and nothing else of the entry', () => {
+ for (const field of ['apiKey', 'apiKeyPreview']) {
+ expect(getConfigSecretInputError(`endpoints.custom["My EP"].${field}`, undefined)).toMatch(
+ /by entry key/,
+ );
+ }
+ expect(getConfigSecretInputError('endpoints.custom["My EP"]', undefined)).toBeNull();
+ expect(getConfigSecretInputError('endpoints.custom["My EP"].headers.X', undefined)).toBeNull();
+ expect(getConfigSecretInputError('endpoints.custom["apiKey"]', undefined)).toBeNull();
+ });
+
+ it('checks a path holding `["` that names no entry by key as the plain path it is', () => {
+ const ciphertext = encryptV3('sk-real');
+ for (const server of ['mcpServers.ab', 'mcpServers.a["b']) {
+ expect(getConfigSecretInputError(`${server}.oauth.client_secret`, ciphertext)).toContain(
+ 'Encrypted config secret values',
+ );
+ expect(getConfigSecretInputError(`${server}.oauth.client_secretPreview`, 'x')).toContain(
+ 'protected secret preview',
+ );
+ expect(getConfigSecretInputError(server, { oauth: { client_secret: ciphertext } })).toContain(
+ 'Encrypted config secret values',
+ );
+ }
+ expect(getConfigSecretInputError('modelSpecs.list["x"].apiKey', undefined)).toBeNull();
+ });
+
+ it('carries a stored endpoint key with its preview to the entry a rename names, by folded name', () => {
+ const existing = encryptConfigSecrets({
+ endpoints: { custom: [entry('Ollama', { apiKey: 'sk-ollama-0001' })] },
+ });
+ const next = { endpoints: { custom: [entry('local'), entry('other')] } };
+
+ carryRenamedConfigSecrets(next, existing, [
+ { path: 'endpoints.custom', previousName: 'ollama', name: 'local' },
+ ]);
+
+ const [stored] = customOf(existing);
+ expect(customOf(next)[0]).toEqual({
+ ...entry('local'),
+ apiKey: stored.apiKey,
+ apiKeyPreview: stored.apiKeyPreview,
+ });
+ expect(customOf(next)[1]).toEqual(entry('other'));
+ });
+
+ it('carries into a patch of the array, never over an entered key, and never a reference', () => {
+ const existing = {
+ endpoints: {
+ custom: [
+ entry('legacy', { apiKey: 'sk-legacy-plaintext-0002' }),
+ entry('ref', { apiKey: '${REF_KEY}' }),
+ entry('kept', { apiKey: 'sk-kept-0003' }),
+ ],
+ },
+ };
+ const value = [entry('a'), entry('b'), entry('c', { apiKey: 'v3:entered' })];
+
+ carryRenamedConfigSecrets(
+ value,
+ existing,
+ [
+ { path: 'endpoints.custom', previousName: 'legacy', name: 'a' },
+ { path: 'endpoints.custom', previousName: 'ref', name: 'b' },
+ { path: 'endpoints.custom', previousName: 'kept', name: 'c' },
+ ],
+ 'endpoints.custom',
+ );
+
+ expect(decryptV3(value[0].apiKey)).toBe('sk-legacy-plaintext-0002');
+ expect(value[0].apiKeyPreview).toBe('...0002');
+ expect(value[1].apiKey).toBeUndefined();
+ expect(value[2].apiKey).toBe('v3:entered');
+ });
+});
+
describe('Azure OpenAI group secrets (array registry)', () => {
const group = (name: string, apiKey?: string) => ({
group: name,
diff --git a/packages/api/src/admin/secrets.ts b/packages/api/src/admin/secrets.ts
index 22a97e5dca..e4ad6a719e 100644
--- a/packages/api/src/admin/secrets.ts
+++ b/packages/api/src/admin/secrets.ts
@@ -5,10 +5,13 @@ import {
encryptV3,
decryptV3,
setAtPath,
+ parseConfigPath,
+ isKeyedConfigPath,
foldConfigMergeKey,
+ getConfigArrayMergeKey,
combineFoldedConfigItems,
} from '@librechat/data-schemas';
-import type { AdminConfigRules, ConfigFieldWrite } from '@librechat/data-schemas';
+import type { AdminConfigRules, ConfigFieldWrite, ConfigLocation } from '@librechat/data-schemas';
import { isUserProvided } from '~/utils/common';
const ENCRYPTED_PREFIX = 'v3:';
@@ -782,6 +785,10 @@ export function isConfigSecretKeyRename(
}
export function getConfigSecretInputError(fieldPath: string, value: unknown): string | null {
+ const entryPath = readEntryPath(fieldPath);
+ if (entryPath) {
+ return getKeyedSecretPathError(entryPath);
+ }
if (PREVIEW_PATHS.has(fieldPath)) {
return `Cannot write protected secret preview path: ${fieldPath}`;
}
@@ -1002,7 +1009,50 @@ function isArrayIndexSegment(segment: string): boolean {
return /^\d+$/.test(segment) || segment.includes('$');
}
+/** The secret key each entry of the array at `arrayPath` holds (`apiKey`), or `undefined`. */
+export function getArraySecretKey(arrayPath: string): string | undefined {
+ return ARRAY_SECRET_FIELDS.find((field) => field.arrayPath === arrayPath)?.secretKey;
+}
+
+/**
+ * A keyed path that names an entry of an array merged by key (`endpoints.custom["Name"].x`, see
+ * `parseConfigPath`), or `null`. Any other path holding `["` (a malformed keyed path, or a record
+ * key such as an MCP server named `a["b` joined from `segments`) is checked as a plain path.
+ */
+function readEntryPath(fieldPath: string): ConfigLocation | null {
+ if (!isKeyedConfigPath(fieldPath)) {
+ return null;
+ }
+ const location = parseConfigPath(fieldPath);
+ return location?.entry && getConfigArrayMergeKey(location.segments) ? location : null;
+}
+
+/**
+ * A keyed path (`endpoints.custom["Name"].apiKey`) naming an entry's registered secret or its
+ * preview: an entry's secret is written, kept and removed with the entry, never by its key, so
+ * the secret pipeline never meets a path it does not encrypt, preserve or redact.
+ */
+function getKeyedSecretPathError(location: ConfigLocation): string | null {
+ const field = location.entry?.rest[0];
+ if (field === undefined) {
+ return null;
+ }
+ const arrayPath = location.segments.join('.');
+ const secret = ARRAY_SECRET_FIELDS.find(
+ (candidate) =>
+ candidate.arrayPath === arrayPath &&
+ (field === candidate.secretKey || field === candidate.previewKey),
+ );
+ return secret
+ ? `Cannot address ${secret.arrayPath}[].${field} by entry key. Write the ${secret.arrayPath} entry instead`
+ : null;
+}
+
function getArraySecretPathError(fieldPath: string): string | null {
+ const entryPath = readEntryPath(fieldPath);
+ if (entryPath) {
+ return getKeyedSecretPathError(entryPath);
+ }
for (const field of ARRAY_SECRET_FIELDS) {
const prefix = `${field.arrayPath}.`;
if (!fieldPath.startsWith(prefix)) {
@@ -1267,20 +1317,99 @@ function redactRecordSecrets(rootRecord: Record<string, unknown>): void {
}
}
-/** A secret carried across a server rename: from the stored entry it had, to the new name. */
+/** Where a `renames` hint may name entries: MCP servers by name, custom endpoints by `name`. */
+export const RENAME_HINT_PATHS = ['mcpServers', 'endpoints.custom'] as const;
+
+/**
+ * A secret carried across a rename: from the stored entry it had, to the new name. For
+ * `mcpServers` the name is a server's record key, for `endpoints.custom` an endpoint's `name`.
+ */
export interface ConfigSecretRename {
- path: 'mcpServers';
+ path: (typeof RENAME_HINT_PATHS)[number];
previousName: string;
name: string;
}
/**
- * Fills secrets a renamed entry omits from the stored entry it was renamed from. Copy semantics:
- * the stored entry keeps its own secret, so a client that renames by writing the new entry and
- * then deleting the old one loses nothing. Runs after {@link preserveConfigSecrets}, which keeps
- * a secret the entry already has under its own name. A carried credential keeps its stored
- * ciphertext (legacy plaintext is encrypted on the way), so the re-entry rule (`reentry.ts`)
- * finds the server it came from by value.
+ * Copies a stored array entry's secret, with its preview, into an entry that omits it, as
+ * {@link carryStoredRecordSecret} does for a record entry: ciphertext as is, legacy plaintext
+ * encrypted on the way, a reference the read returned not at all.
+ */
+function carryStoredArraySecret(
+ entry: Record<string, unknown>,
+ stored: Record<string, unknown> | null,
+ field: ArraySecretField,
+): void {
+ const storedSecret = normalizeSecretString(stored?.[field.secretKey]);
+ if (!stored || !storedSecret || field.isPassthroughValue(storedSecret)) {
+ return;
+ }
+ if (!isEncryptedConfigSecret(storedSecret)) {
+ entry[field.secretKey] = encryptV3(storedSecret);
+ entry[field.previewKey] = getSecretPreview(storedSecret);
+ return;
+ }
+ entry[field.secretKey] = storedSecret;
+ const storedPreview = stored[field.previewKey];
+ if (typeof storedPreview === 'string') {
+ entry[field.previewKey] = normalizeStoredPreview(storedPreview);
+ } else {
+ delete entry[field.previewKey];
+ }
+}
+
+/** The stored entry of an array secret field whose key has the identity of `name`. */
+function findStoredSecretEntry(
+ existing: unknown,
+ field: ArraySecretField,
+ name: string,
+): Record<string, unknown> | null {
+ const identity = foldConfigMergeKey(field.arrayPath, name);
+ for (const item of getStoredSecretEntries(existing, field) ?? []) {
+ const entry = getPlainRecord(item);
+ if (entry && getEntryIdentity(entry, field) === identity) {
+ return entry;
+ }
+ }
+ return null;
+}
+
+/** Fills the array entries named `name` that omit their secret from the stored entry `previousName`. */
+function carryRenamedArraySecrets(
+ next: unknown,
+ existing: unknown,
+ renames: readonly ConfigSecretRename[],
+ basePath: string,
+): void {
+ for (const field of ARRAY_SECRET_FIELDS) {
+ const entries = getSecretArray(next, field, basePath);
+ if (!entries) {
+ continue;
+ }
+ for (const { previousName, name, path } of renames) {
+ if (path !== field.arrayPath) {
+ continue;
+ }
+ const identity = foldConfigMergeKey(field.arrayPath, name);
+ const stored = findStoredSecretEntry(existing, field, previousName);
+ for (const item of entries) {
+ const entry = getPlainRecord(item);
+ if (entry && !(field.secretKey in entry) && getEntryIdentity(entry, field) === identity) {
+ carryStoredArraySecret(entry, stored, field);
+ }
+ }
+ }
+ }
+}
+
+/**
+ * Fills secrets a renamed entry omits from the stored entry it was renamed from: an MCP server's
+ * credentials (by record key), or a custom endpoint's `apiKey` (by `name`, folded as the merge
+ * folds it). Copy semantics: the stored entry keeps its own secret, so a client that renames by
+ * writing the new entry and then deleting the old one loses nothing. Runs after
+ * {@link preserveConfigSecrets}, which keeps a secret the entry already has under its own name.
+ * A carried credential keeps its stored ciphertext (legacy plaintext is encrypted on the way), so
+ * the re-entry rules (`reentry.ts`) find the server or endpoint it came from by value.
*/
export function carryRenamedConfigSecrets(
next: unknown,
@@ -1291,6 +1420,7 @@ export function carryRenamedConfigSecrets(
if (renames.length === 0) {
return;
}
+ carryRenamedArraySecrets(next, existing, renames, basePath);
for (const field of RECORD_SECRET_FIELDS) {
const key = getRecordSecretKey(field);
const parents = collectRecordSecretParents(next, field, basePath, false);
diff --git a/packages/api/src/app/layers.spec.ts b/packages/api/src/app/layers.spec.ts
index b90dfb3df4..64972b5e3b 100644
--- a/packages/api/src/app/layers.spec.ts
+++ b/packages/api/src/app/layers.spec.ts
@@ -359,6 +359,36 @@ describe('createAppConfigService().resolveConfigLayers', () => {
]);
});
+ it('leaves out what selects an endpoint a profile hides by key, as getAppConfig does', async () => {
+ const configs: ConfigOverrideLayer[] = [
+ {
+ ...role({
+ modelSpecs: {
+ list: [
+ { name: 'hidden', label: 'Hidden', preset: { endpoint: 'Gateway', model: 'gpt-4o' } },
+ { name: 'kept', label: 'Kept', preset: { endpoint: 'openAI', model: 'gpt-4o' } },
+ ],
+ },
+ endpoints: { agents: { allowedProviders: ['Gateway', 'openAI'] } },
+ }),
+ tombstones: ['endpoints.custom["Gateway"]'],
+ },
+ ];
+ const service = createService(configs);
+ const served = await service.getAppConfig({
+ role: 'editors',
+ bypassOverrideCache: true,
+ skipRuntimeAugmentation: true,
+ });
+ const resolution = await service.resolveConfigLayers({ configs });
+ expect(resolution.merged).toEqual(served);
+ expect(served.modelSpecs?.list?.map((spec) => spec.name)).toEqual(['kept']);
+ expect(served.endpoints?.agents?.allowedProviders).toEqual(['openAI']);
+ expect(resolution.resolved.endpoints?.custom ?? []).toEqual([]);
+ expect(resolution.resolved.modelSpecs?.list?.map((spec) => spec.name)).toEqual(['kept']);
+ expect(resolution.resolved.endpoints?.agents?.allowedProviders).toEqual(['openAI']);
+ });
+
it('shows the librechat.yaml theme where a profile theme fails the client rules', async () => {
const configs = [role({ interface: { customWelcome: 'Role', theme: INVALID_THEME } })];
const resolution = await createService(configs).resolveConfigLayers({ configs });
diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.ts
index a325f52ec2..2cec1c953c 100644
--- a/packages/api/src/app/service.spec.ts
+++ b/packages/api/src/app/service.spec.ts
@@ -241,6 +241,23 @@ describe('createAppConfigService', () => {
expect(config.modelSpecs).toBeUndefined();
});
+ it('keeps the other added endpoints when another tenant owns every spec', async () => {
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue({
+ endpoints: { custom: [{ name: 'ClickHouse', tenantId: 'dwh-org' }] },
+ modelSpecs: {
+ list: [{ name: 'dwh-spec', preset: { endpoint: 'ClickHouse' } }],
+ addedEndpoints: ['agents', 'ClickHouse'],
+ },
+ }),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+
+ const config = await getAppConfig({ role: 'USER', tenantId: 'other-org' });
+
+ expect(config.modelSpecs).toEqual({ list: [], addedEndpoints: ['agents'] });
+ });
+
describe('tenant isolation invariants', () => {
async function tenantBase(interfaceConfig?: AppConfig['interfaceConfig']) {
return AppService({
diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.ts
index 565d337e58..7483762f1f 100644
--- a/packages/api/src/app/service.ts
+++ b/packages/api/src/app/service.ts
@@ -89,9 +89,36 @@ function scopeEndpointList<T extends { name?: string; tenantId?: string }>(
return selected.length === endpoints.length ? endpoints : selected;
}
+/** `names` without the hidden endpoints; the same array when it names none. */
+function withoutHiddenNames<T extends string>(
+ names: T[] | undefined,
+ hiddenEndpoints: ReadonlySet<string>,
+): T[] | undefined {
+ const kept = names?.filter((name) => !hiddenEndpoints.has(normalizeEndpointName(name)));
+ return kept?.length === names?.length ? names : kept;
+}
+
+/**
+ * An endpoint allow-list (`modelSpecs.addedEndpoints`, `endpoints.agents.allowedProviders`)
+ * without the hidden endpoints, kept as it is when it names nothing else: an empty list allows
+ * every endpoint, while names the principal is not served allow none.
+ */
+function scopeAllowList<T extends string>(
+ names: T[] | undefined,
+ hiddenEndpoints: ReadonlySet<string>,
+): T[] | undefined {
+ const kept = withoutHiddenNames(names, hiddenEndpoints);
+ return kept?.length === 0 ? names : kept;
+}
+
+/**
+ * `specs` without the specs that select a hidden endpoint, and with `addedEndpoints` scoped by
+ * `scopeAddedEndpoints`. Collapses to `undefined` only when no spec and no added endpoint is left.
+ */
function scopeModelSpecs(
specs: AppConfig['modelSpecs'],
hiddenEndpoints: ReadonlySet<string>,
+ scopeAddedEndpoints: typeof withoutHiddenNames = withoutHiddenNames,
): AppConfig['modelSpecs'] {
if (!specs || hiddenEndpoints.size === 0) {
return specs;
@@ -99,21 +126,105 @@ function scopeModelSpecs(
const list = specs.list?.filter(
(spec) => !hiddenEndpoints.has(normalizeEndpointName(spec.preset?.endpoint ?? '')),
);
- const addedEndpoints = specs.addedEndpoints?.filter(
- (endpoint) => !hiddenEndpoints.has(normalizeEndpointName(endpoint)),
- );
- if (
- list?.length === specs.list?.length &&
- addedEndpoints?.length === specs.addedEndpoints?.length
- ) {
+ const addedEndpoints = scopeAddedEndpoints(specs.addedEndpoints, hiddenEndpoints);
+ if (list?.length === specs.list?.length && addedEndpoints === specs.addedEndpoints) {
return specs;
}
- if (specs.list?.length && list?.length === 0) {
+ if (specs.list?.length && list?.length === 0 && !addedEndpoints?.length) {
return undefined;
}
return { ...specs, list, addedEndpoints };
}
+/** Adds the folded name of each entry in `endpoints` that `served` lacks to `hidden`. */
+function addUnservedEndpointNames(
+ endpoints: ReadonlyArray<{ name?: string } | null> | undefined,
+ served: ReadonlySet<string>,
+ hidden: Set<string>,
+): void {
+ if (!Array.isArray(endpoints)) {
+ return;
+ }
+ for (const endpoint of endpoints) {
+ const name = typeof endpoint?.name === 'string' ? normalizeEndpointName(endpoint.name) : '';
+ if (name !== '' && !served.has(name)) {
+ hidden.add(name);
+ }
+ }
+}
+
+/**
+ * The folded names of the custom endpoints the merge removed: ones librechat.yaml or any applied
+ * override layer (Base included) defines that the merged config no longer serves.
+ */
+function getUnservedEndpointNames(
+ base: AppConfig,
+ layers: readonly ConfigOverrideLayer[],
+ merged: AppConfig,
+): Set<string> {
+ const served = new Set(
+ (merged.endpoints?.custom ?? []).map((endpoint) => normalizeEndpointName(endpoint.name ?? '')),
+ );
+ const hidden = new Set<string>();
+ addUnservedEndpointNames(base.endpoints?.custom, served, hidden);
+ for (const layer of layers) {
+ addUnservedEndpointNames(layer.overrides?.endpoints?.custom, served, hidden);
+ }
+ return hidden;
+}
+
+/** The parts of a config that name endpoints, in the served config and its YAML-shaped resolution alike. */
+interface EndpointReferences {
+ modelSpecs?: AppConfig['modelSpecs'];
+ endpoints?: { agents?: { allowedProviders?: string[] } };
+}
+
+/**
+ * `config` without its references to the `hidden` endpoints: the model specs that select one,
+ * and its name in `modelSpecs.addedEndpoints` and `endpoints.agents.allowedProviders`. Unrelated
+ * added endpoints stay when no spec is left, and an allow-list naming only hidden endpoints stays
+ * as it is ({@link scopeAllowList}).
+ */
+function scopeEndpointReferences<T extends EndpointReferences>(
+ config: T,
+ hidden: ReadonlySet<string>,
+): T {
+ const agents = config.endpoints?.agents;
+ const modelSpecs = scopeModelSpecs(config.modelSpecs, hidden, scopeAllowList);
+ const allowedProviders = scopeAllowList(agents?.allowedProviders, hidden);
+ const agentsChanged = allowedProviders !== agents?.allowedProviders;
+ if (modelSpecs === config.modelSpecs && !agentsChanged) {
+ return config;
+ }
+ return {
+ ...config,
+ ...(modelSpecs !== config.modelSpecs && { modelSpecs }),
+ ...(agentsChanged && {
+ endpoints: { ...config.endpoints, agents: { ...agents, allowedProviders } },
+ }),
+ };
+}
+
+/**
+ * `merged` without the references to custom endpoints the merge removed
+ * ({@link getUnservedEndpointNames}). A profile that hides an endpoint (a keyed
+ * `endpoints.custom["Name"]` tombstone, or a tombstone of all of them) also hides the model specs
+ * that select it and its name in `modelSpecs.addedEndpoints` and
+ * `endpoints.agents.allowedProviders`, rather than offering its principals an endpoint they are
+ * not served. Only the references are scoped, never the endpoint list, so an endpoint a later
+ * layer adds back keeps them.
+ */
+function scopeHiddenEndpointReferences(
+ base: AppConfig,
+ layers: readonly ConfigOverrideLayer[],
+ merged: AppConfig,
+): AppConfig {
+ if (!merged.modelSpecs && !merged.endpoints?.agents?.allowedProviders?.length) {
+ return merged;
+ }
+ return scopeEndpointReferences(merged, getUnservedEndpointNames(base, layers, merged));
+}
+
/** Keep tenant-scoped YAML endpoints out of every other tenant's effective config. */
function scopeCustomEndpoints(
config: AppConfig,
@@ -921,7 +1032,14 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
onRebinding: warnRebinding,
});
merged = scopeCustomEndpoints(
- checkOverrideTheme(scopedBaseConfig, completeEffectiveConfig(layered)),
+ checkOverrideTheme(
+ scopedBaseConfig,
+ scopeHiddenEndpointReferences(
+ scopedBaseConfig,
+ configs,
+ completeEffectiveConfig(layered),
+ ),
+ ),
effectiveTenantId,
hiddenEndpoints,
);
@@ -977,7 +1095,11 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
onRebinding: warnRebinding,
});
const completed = completeEffectiveConfig(resolution.merged);
- const checked = checkOverrideTheme(scopedBaseConfig, completed);
+ const unserved = getUnservedEndpointNames(scopedBaseConfig, configs, completed);
+ const checked = checkOverrideTheme(
+ scopedBaseConfig,
+ scopeEndpointReferences(completed, unserved),
+ );
const baseTheme = scopedBaseConfig.interfaceConfig?.theme;
let resolved = resolution.resolved;
if (
@@ -987,7 +1109,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
resolved = replayThemeFallback(resolved, resolution.layers, yaml);
}
resolved = scopeResolvedEndpoints(
- resolved,
+ scopeEndpointReferences(resolved, unserved),
resolution.layers,
effectiveTenantId,
hiddenCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints),
diff --git a/packages/data-schemas/src/app/changes.spec.ts b/packages/data-schemas/src/app/changes.spec.ts
index 5d40414cff..c715dd1564 100644
--- a/packages/data-schemas/src/app/changes.spec.ts
+++ b/packages/data-schemas/src/app/changes.spec.ts
@@ -704,3 +704,132 @@ describe('isSameConfigValue', () => {
expect(isSameConfigValue(null, {})).toBe(false);
});
});
+
+describe('keyed changes: entries of an array merged by key, by key', () => {
+ const keyedChange = (op: 'unset' | 'tombstone', key: string, rest: string[] = []) =>
+ ({ op, segments: CUSTOM, entry: { key, rest } }) as ConfigChange;
+
+ it('hides an entry, then shows it again when the same batch upserts it', () => {
+ const stored = deepFreeze(state({ endpoints: { custom: [endpoint('gw')] } }));
+ const { state: hidden } = applyConfigChanges(stored, [keyedChange('tombstone', 'gw')]);
+ expect(hidden).toEqual(state({}, ['endpoints.custom["gw"]']));
+
+ const { state: shown, changed } = applyConfigChanges(hidden, [
+ { op: 'upsertEntry', segments: CUSTOM, entry: endpoint('gw') },
+ ]);
+ expect(changed).toEqual([true]);
+ expect(shown).toEqual(state({ endpoints: { custom: [endpoint('gw')] } }));
+ });
+
+ it('an upsert of an entry clears its hide even when the stored entry is already the same', () => {
+ const hiddenWithEntry = state({ endpoints: { custom: [endpoint('gw')] } }, [
+ 'endpoints.custom["gw"]',
+ 'endpoints.custom["gw"].headers.A',
+ ]);
+ const next = applyConfigChange(hiddenWithEntry, {
+ op: 'upsertEntry',
+ segments: CUSTOM,
+ entry: endpoint('gw'),
+ });
+ expect(next.tombstones).toEqual(['endpoints.custom["gw"].headers.A']);
+ const set = applyConfigChange(hiddenWithEntry, {
+ op: 'set',
+ segments: CUSTOM,
+ value: [endpoint('gw')],
+ });
+ expect(set).not.toBe(hiddenWithEntry);
+ expect(set.tombstones).toEqual(['endpoints.custom["gw"].headers.A']);
+ });
+
+ it('keeps a tombstone inside an entry through an edit of the entry in the same batch', () => {
+ const stored = state({ endpoints: { custom: [endpoint('gw', { headers: { A: 'a' } })] } });
+ const { state: next } = applyConfigChanges(stored, [
+ { op: 'upsertEntry', segments: CUSTOM, entry: endpoint('gw', { titleModel: 't' }) },
+ keyedChange('tombstone', 'gw', ['headers', 'B']),
+ ]);
+ expect(next).toEqual(
+ state({ endpoints: { custom: [endpoint('gw', { titleModel: 't' })] } }, [
+ 'endpoints.custom["gw"].headers.B',
+ ]),
+ );
+ });
+
+ it('resets an entry by key with its keyed tombstones, and reports no change when there is none', () => {
+ const stored = state({ endpoints: { custom: [endpoint('Ollama')] } }, [
+ 'endpoints.custom["Ollama"].headers.A',
+ ]);
+ expect(applyConfigChange(stored, keyedChange('unset', 'ollama'))).toEqual(state({}));
+ const untouched = state({ endpoints: { custom: [endpoint('gw')] } });
+ expect(applyConfigChange(untouched, keyedChange('unset', 'gw', ['headers', 'A']))).toBe(
+ untouched,
+ );
+ expect(applyConfigChange(untouched, keyedChange('unset', 'other'))).toBe(untouched);
+ });
+
+ it('moves the keyed tombstones of an entry a batch renames', () => {
+ const stored = state({ endpoints: { custom: [endpoint('draft')] } }, [
+ 'endpoints.custom["draft"].headers.A',
+ ]);
+ const next = applyConfigChange(stored, {
+ op: 'rename',
+ segments: CUSTOM,
+ from: 'draft',
+ to: 'final',
+ });
+ expect(next).toEqual(
+ state({ endpoints: { custom: [endpoint('draft', { name: 'final' })] } }, [
+ 'endpoints.custom["final"].headers.A',
+ ]),
+ );
+ });
+
+ it('counts a set that only shows an entry it writes again as a write of the collection', () => {
+ const stored = state({ endpoints: { custom: [endpoint('gw')] } }, ['endpoints.custom["gw"]']);
+ const batch: ConfigChange[] = [{ op: 'set', segments: CUSTOM, value: [endpoint('gw')] }];
+ const { state: result } = applyConfigChanges(stored, batch);
+ expect(result.tombstones).toEqual([]);
+ expect(getConfigBatchWrittenPaths(batch, result, stored)).toEqual([CUSTOM]);
+ });
+
+ it('a set or record rename by segments that only spell an entry keeps its keyed tombstones', () => {
+ const stored = state({ endpoints: { junk: { a: 1 } } }, [
+ 'endpoints.custom["GPT"]',
+ 'endpoints.custom["OR"].headers.X',
+ ]);
+ const set = applyConfigChange(stored, {
+ op: 'set',
+ segments: ['endpoints', 'custom["OR"]', 'headers', 'X'],
+ value: 'v',
+ });
+ expect(set.tombstones).toEqual(stored.tombstones);
+ const renamed = applyConfigChange(stored, {
+ op: 'rename',
+ segments: ['endpoints'],
+ from: 'junk',
+ to: 'custom["GPT"]',
+ });
+ expect(renamed).toEqual(state({ endpoints: { 'custom["GPT"]': { a: 1 } } }, stored.tombstones));
+ });
+
+ it('refuses a keyed change whose path inside the entry its stored tombstone could not name', () => {
+ const stored = state({ endpoints: { custom: [endpoint('K', { headers: { 'a.b': 'x' } })] } });
+ for (const op of ['tombstone', 'unset'] as const) {
+ const error = errorOf(() =>
+ applyConfigChange(stored, keyedChange(op, 'K', ['headers', 'a.b'])),
+ );
+ expect(isConfigPathError(error) && error.reason).toBe('dotted_segment');
+ }
+ });
+
+ it('names a keyed change by the own entry it leaves, or by nothing once it removed it', () => {
+ const stored = state({
+ endpoints: { custom: [endpoint('a'), endpoint('gw', { headers: { A: 'a', B: 'b' } })] },
+ });
+ const inside = keyedChange('tombstone', 'gw', ['headers', 'A']);
+ expect(getConfigChangeWrittenPaths(inside, applyConfigChange(stored, inside))).toEqual([
+ ['endpoints', 'custom', '1'],
+ ]);
+ const whole = keyedChange('tombstone', 'gw');
+ expect(getConfigChangeWrittenPaths(whole, applyConfigChange(stored, whole))).toEqual([]);
+ });
+});
diff --git a/packages/data-schemas/src/app/changes.ts b/packages/data-schemas/src/app/changes.ts
index 0f22a82f06..9e93ea28ee 100644
--- a/packages/data-schemas/src/app/changes.ts
+++ b/packages/data-schemas/src/app/changes.ts
@@ -1,23 +1,30 @@
import type { TCustomConfig } from 'librechat-data-provider';
+import type { ConfigEntryStep, ConfigPathSegments } from './paths';
import type { ConfigOverrideState } from './mutations';
-import type { ConfigPathSegments } from './paths';
+import {
+ setConfigFields,
+ unsetConfigPaths,
+ tombstoneConfigPaths,
+ getPathClearedTombstones,
+ getWriteClearedTombstones,
+ renameConfigEntryTombstones,
+} from './mutations';
+import {
+ getConfigEntryIdentity,
+ getConfigArrayMergeKey,
+ isConfigEntryTombstone,
+ getConfigTombstoneSegments,
+} from './collections';
import {
getAtPath,
setAtPath,
unsetAtPath,
isPlainRecord,
- parseFieldPath,
ConfigPathError,
isSegmentPrefix,
pruneEmptyAncestors,
- getClearedTombstones,
} from './paths';
-import {
- getConfigEntryIdentity,
- getConfigArrayMergeKey,
- combineFoldedConfigEntries,
-} from './resolution';
-import { setConfigFields, unsetConfigPaths, tombstoneConfigPaths } from './mutations';
+import { combineFoldedConfigEntries } from './resolution';
/**
* Atomic batches of override changes.
@@ -42,15 +49,24 @@ export const MAX_CONFIG_CHANGE_OPS = 1000;
export type ConfigChange =
/** Writes `value` at the path and clears the tombstones the write covers. */
| { op: 'set'; segments: ConfigPathSegments; value: unknown }
- /** Removes the override at the path, its emptied parents, and tombstones at or below it. */
- | { op: 'unset'; segments: ConfigPathSegments }
- /** Removes the override at the path and records a tombstone that hides inherited values. */
- | { op: 'tombstone'; segments: ConfigPathSegments }
+ /**
+ * Removes the override at the path, its emptied parents, and tombstones at or below it. With
+ * `entry`, `segments` is an array merged by key, and the change resets the principal's own
+ * entry with that key (by identity), or the path inside it, and the keyed tombstones of that
+ * entry at or below it.
+ */
+ | { op: 'unset'; segments: ConfigPathSegments; entry?: ConfigEntryStep }
+ /**
+ * Removes the override at the path and records a tombstone that hides inherited values. With
+ * `entry`, it hides the inherited entry with that key of the merged-by-key array at
+ * `segments`, or the path inside it, and removes the principal's own entry or that path.
+ */
+ | { op: 'tombstone'; segments: ConfigPathSegments; entry?: ConfigEntryStep }
/**
* Replaces the principal's own entry of a merged-by-key array whose key matches the entry's
- * (every own entry with that key), or appends it. The array is created when missing. Entry
- * keys of every entry change match by identity (`getConfigEntryMatcher`): `ollama` addresses
- * a stored `Ollama`.
+ * (every own entry with that key), or appends it. The array is created when missing, and a
+ * tombstone hiding that whole entry is cleared. Entry keys of every entry change match by
+ * identity (`getConfigEntryMatcher`): `ollama` addresses a stored `Ollama`.
*/
| { op: 'upsertEntry'; segments: ConfigPathSegments; entry: Record<string, unknown> }
/** Removes the principal's own entries of a merged-by-key array that have this key. */
@@ -59,7 +75,8 @@ export type ConfigChange =
* Renames one of the principal's own entries, moving everything stored on it (encrypted
* secrets included): an entry of a merged-by-key array gets a new key value in place (one
* stored in two spellings of its key is combined first, as the runtime merge combines it),
- * and a record key is moved with its value, keeping the record's key order.
+ * with the keyed tombstones of the old key moved to the new one, and a record key is moved
+ * with its value, keeping the record's key order.
*/
| { op: 'rename'; segments: ConfigPathSegments; from: string; to: string };
@@ -157,11 +174,10 @@ function applySet(
segments: ConfigPathSegments,
value: unknown,
): ConfigOverrideState {
- const cleared = new Set(getClearedTombstones(segments));
const unchanged =
hasPath(state.overrides, segments) &&
isSameConfigValue(getAtPath(state.overrides, segments), value) &&
- !state.tombstones.some((path) => cleared.has(path));
+ getWriteClearedTombstones(state.tombstones, segments, value).length === 0;
return unchanged ? state : setConfigFields(state, [{ segments, value }]);
}
@@ -250,7 +266,13 @@ function applyUpsertEntry(
}
return isEntry(item) ? [] : [item];
});
- return isSameConfigValue(items, next) ? state : writeKeyedArray(state, segments, next);
+ const tombstones = state.tombstones.filter(
+ (tombstone) => !isConfigEntryTombstone(tombstone, segments, key),
+ );
+ if (isSameConfigValue(items, next) && tombstones.length === state.tombstones.length) {
+ return state;
+ }
+ return writeKeyedArray({ overrides: state.overrides, tombstones }, segments, next);
}
function applyRemoveEntry(
@@ -294,7 +316,7 @@ function renameKeyedEntry(
}
return position === index ? [renamed(combined[0])] : [];
});
- return writeKeyedArray(state, segments, next);
+ return renameConfigEntryTombstones(writeKeyedArray(state, segments, next), segments, from, to);
}
/** Moves record key `from` to `to`, keeping the key order. */
@@ -324,7 +346,7 @@ function renameRecordKey(
configurable: true,
});
}
- const cleared = new Set(getClearedTombstones([...segments, to]));
+ const cleared = new Set(getPathClearedTombstones([...segments, to]));
return {
overrides: setAtPath(asRecord(state), segments, renamed) as Partial<TCustomConfig>,
tombstones: state.tombstones.filter((path) => !cleared.has(path)),
@@ -365,9 +387,15 @@ export function applyConfigChange(
case 'set':
return applySet(state, change.segments, change.value);
case 'unset':
- return keepIfSame(state, unsetConfigPaths(state, [change.segments]));
+ return keepIfSame(
+ state,
+ unsetConfigPaths(state, [{ segments: change.segments, entry: change.entry }]),
+ );
case 'tombstone':
- return keepIfSame(state, tombstoneConfigPaths(state, [change.segments]));
+ return keepIfSame(
+ state,
+ tombstoneConfigPaths(state, [{ segments: change.segments, entry: change.entry }]),
+ );
case 'upsertEntry':
return applyUpsertEntry(state, change.segments, change.entry);
case 'removeEntry':
@@ -489,6 +517,25 @@ export function renameConfigIdentityPath(
return next;
}
+/**
+ * Where a keyed change leaves the principal's own entry with key `key`: the entry by its index
+ * in `result`, or nothing once the change removed it (hiding or resetting it whole, or emptying
+ * it down to its key).
+ */
+function getEntryWrittenPaths(
+ segments: ConfigPathSegments,
+ key: string,
+ result: ConfigOverrideState,
+): string[][] {
+ const keyField = getConfigArrayMergeKey(segments);
+ const items = getAtPath(result.overrides, segments);
+ const index =
+ keyField && Array.isArray(items)
+ ? items.findIndex(getConfigEntryMatcher(segments, keyField, key))
+ : -1;
+ return index === -1 ? [] : [[...segments, String(index)]];
+}
+
/**
* The paths a change writes, for attributing validation issues to it: the path itself, or for
* an entry change, the entry by its index in `result`'s own array. A removed entry is gone, so
@@ -501,6 +548,9 @@ export function getConfigChangeWrittenPaths(
result: ConfigOverrideState,
): string[][] {
const segments = [...change.segments];
+ if ((change.op === 'unset' || change.op === 'tombstone') && change.entry) {
+ return getEntryWrittenPaths(change.segments, change.entry.key, result);
+ }
if (change.op === 'set' || change.op === 'unset' || change.op === 'tombstone') {
return [segments];
}
@@ -554,14 +604,17 @@ function getStoredCounterpart(
return counterpart;
}
-/** The tombstones at, above or below `segments`: the ones that decide what it inherits. */
+/**
+ * The tombstones at, above or below `segments`: the ones that decide what it inherits. A keyed
+ * tombstone counts by its array, so any change to the entries it hides relates to the array.
+ */
function getRelatedTombstones(
tombstones: readonly string[],
segments: ConfigPathSegments,
): Set<string> {
return new Set(
tombstones.filter((path) => {
- const tombstone = parseFieldPath(path);
+ const tombstone = getConfigTombstoneSegments(path);
return isSegmentPrefix(tombstone, segments) || isSegmentPrefix(segments, tombstone);
}),
);
diff --git a/packages/data-schemas/src/app/collections.spec.ts b/packages/data-schemas/src/app/collections.spec.ts
new file mode 100644
index 0000000000..a344934fa0
--- /dev/null
+++ b/packages/data-schemas/src/app/collections.spec.ts
@@ -0,0 +1,28 @@
+import { isConfigTombstoneAtOrBelow, getConfigTombstoneSegments } from './collections';
+
+const CUSTOM = ['endpoints', 'custom'];
+
+describe('stored tombstones compared with a path', () => {
+ it('counts a keyed tombstone below a path at or above its array, never below a position in it', () => {
+ const keyed = 'endpoints.custom["a.b"].headers';
+ const below = (segments: string[]) => isConfigTombstoneAtOrBelow(keyed, { segments });
+ expect(below(['endpoints'])).toBe(true);
+ expect(below(CUSTOM)).toBe(true);
+ expect(below(['endpoints', 'custom', '0'])).toBe(false);
+ expect(below(['endpoints', 'openAI'])).toBe(false);
+ expect(isConfigTombstoneAtOrBelow('endpoints.custom["broken', { segments: CUSTOM })).toBe(
+ false,
+ );
+ expect(
+ isConfigTombstoneAtOrBelow('endpoints.custom["broken', { segments: ['endpoints'] }),
+ ).toBe(true);
+ });
+
+ it('splits a tombstone holding `["` after anything but an array merged by key on its dots', () => {
+ const legacy = 'mcpServers.a["b"]';
+ expect(getConfigTombstoneSegments(legacy)).toEqual(['mcpServers', 'a["b"]']);
+ expect(getConfigTombstoneSegments('endpoints.custom["a.b"]')).toEqual(CUSTOM);
+ expect(isConfigTombstoneAtOrBelow(legacy, { segments: ['mcpServers', 'a["b"]'] })).toBe(true);
+ expect(isConfigTombstoneAtOrBelow(legacy, { segments: ['mcpServers', 'a'] })).toBe(false);
+ });
+});
diff --git a/packages/data-schemas/src/app/collections.ts b/packages/data-schemas/src/app/collections.ts
new file mode 100644
index 0000000000..5d84eb713f
--- /dev/null
+++ b/packages/data-schemas/src/app/collections.ts
@@ -0,0 +1,200 @@
+import { normalizeEndpointName } from 'librechat-data-provider';
+import type { TCustomConfig } from 'librechat-data-provider';
+import type { ConfigEntryStep, ConfigLocation, ConfigPathSegments } from './paths';
+import type { AppConfig } from '~/types';
+import { parseFieldPath, isSegmentPrefix, parseConfigPath } from './paths';
+
+/**
+ * Arrays of config entries merged by a key field, and how entries of one are addressed.
+ *
+ * Paths here use AppConfig key names (after `OVERRIDE_KEY_MAP` remapping), not YAML-level key
+ * names: `interfaceConfig.x`, not `interface.x`. Functions that take override (YAML) segments
+ * remap them first.
+ */
+
+/**
+ * Paths within the config tree where arrays of objects should be merged by a key field rather
+ * than replaced wholesale. The merge matches items by the given key, deep-merges matching pairs,
+ * preserves unmatched base items, and appends new override-only items.
+ */
+export const ARRAY_MERGE_KEYS: Readonly<Record<string, string>> = {
+ 'endpoints.custom': 'name',
+};
+
+/**
+ * How a merge key is folded before items are matched, by `ARRAY_MERGE_KEYS` path: two
+ * spellings the runtime serves as one item are one item to the merge too. Custom endpoint
+ * names fold through `normalizeEndpointName`, so an override `ollama` lands on the YAML
+ * `Ollama` instead of serving beside it with a different baseURL and key.
+ */
+export const MERGE_KEY_FOLDS: Readonly<Record<string, (key: string) => string>> = {
+ 'endpoints.custom': normalizeEndpointName,
+};
+
+/**
+ * Maps YAML-level override keys (TCustomConfig) to their AppConfig equivalents. Overrides are
+ * stored with YAML keys but merged into the already-processed AppConfig, where AppService
+ * renamed some fields. When AppService renames a field, add the mapping here; entries are
+ * type-checked (keys are TCustomConfig fields, values AppConfig fields).
+ */
+export const OVERRIDE_KEY_MAP: Readonly<Partial<Record<keyof TCustomConfig, keyof AppConfig>>> = {
+ mcpServers: 'mcpConfig',
+ interface: 'interfaceConfig',
+ turnstile: 'turnstileConfig',
+};
+
+function hasOwn(target: object, key: string): boolean {
+ return Object.prototype.hasOwnProperty.call(target, key);
+}
+
+/** An override (YAML) dot-path under AppConfig section names. */
+export function remapOverridePath(path: string): string {
+ const [first, ...rest] = path.split('.');
+ const mappedFirst = OVERRIDE_KEY_MAP[first as keyof typeof OVERRIDE_KEY_MAP] ?? first;
+ return [mappedFirst, ...rest].join('.');
+}
+
+/** The `ARRAY_MERGE_KEYS` path of the merged-by-key array at an override (YAML) path. */
+export function getConfigMergeArrayPath(segments: readonly string[]): string | undefined {
+ if (segments.length === 0 || segments.some((segment) => segment.includes('.'))) {
+ return undefined;
+ }
+ const appConfigPath = remapOverridePath(segments.join('.'));
+ return hasOwn(ARRAY_MERGE_KEYS, appConfigPath) ? appConfigPath : undefined;
+}
+
+/**
+ * The key field that identifies entries of the merged-by-key array at an override (YAML) path,
+ * such as `name` for `endpoints.custom`; `undefined` for any other path.
+ */
+export function getConfigArrayMergeKey(segments: readonly string[]): string | undefined {
+ const arrayPath = getConfigMergeArrayPath(segments);
+ return arrayPath === undefined ? undefined : ARRAY_MERGE_KEYS[arrayPath];
+}
+
+/**
+ * Folds a merge key of the merged-by-key array at `arrayPath` into the identity layers match
+ * on (`Ollama` and `ollama` are one custom endpoint); other keys come back unchanged. Code that
+ * pairs items across writes, such as secret preservation, matches on the same identity.
+ */
+export function foldConfigMergeKey(arrayPath: string, key: string): string {
+ return hasOwn(MERGE_KEY_FOLDS, arrayPath) ? MERGE_KEY_FOLDS[arrayPath](key) : key;
+}
+
+/**
+ * The identity entry key `key` of the merged-by-key array at an override (YAML) path has: the
+ * key as the runtime merge folds it (`foldConfigMergeKey`), so `Ollama` and `ollama` name one
+ * custom endpoint to entry changes as they do to the merge. A key at any other path is its own
+ * identity.
+ */
+export function getConfigEntryIdentity(segments: readonly string[], key: string): string {
+ const arrayPath = getConfigMergeArrayPath(segments);
+ return arrayPath === undefined ? key : foldConfigMergeKey(arrayPath, key);
+}
+
+/** A keyed location whose array is merged by key, with its key field and the key's identity. */
+export interface ConfigEntryLocation {
+ segments: ConfigPathSegments;
+ entry: ConfigEntryStep;
+ keyField: string;
+ identity: string;
+}
+
+/**
+ * A keyed location ({@link ConfigLocation} with `entry`) whose array is merged by key, or
+ * `null` for any other location: an unkeyed path, or a key step after an array the merge
+ * replaces, which no entry can be matched in.
+ */
+export function toConfigEntryLocation(location: ConfigLocation): ConfigEntryLocation | null {
+ if (!location.entry) {
+ return null;
+ }
+ const keyField = getConfigArrayMergeKey(location.segments);
+ if (!keyField) {
+ return null;
+ }
+ return {
+ segments: location.segments,
+ entry: location.entry,
+ keyField,
+ identity: getConfigEntryIdentity(location.segments, location.entry.key),
+ };
+}
+
+/** A stored tombstone as an entry location, or `null` when it is not a keyed tombstone the merge applies. */
+export function readConfigEntryTombstone(tombstone: string): ConfigEntryLocation | null {
+ const location = parseConfigPath(tombstone);
+ return location ? toConfigEntryLocation(location) : null;
+}
+
+/** Whether `item` is an entry of the array at `location` with the key `location` names. */
+export function isConfigEntryAt(location: ConfigEntryLocation, item: unknown): boolean {
+ if (item == null || typeof item !== 'object' || Array.isArray(item)) {
+ return false;
+ }
+ const key = (item as Record<string, unknown>)[location.keyField];
+ return (
+ typeof key === 'string' && getConfigEntryIdentity(location.segments, key) === location.identity
+ );
+}
+
+/**
+ * The segments a stored tombstone names, for comparing it with a path: a keyed tombstone of an
+ * array merged by key by its array's segments, so a path at or above the array covers it
+ * whatever its key. Any other one is split on its dots, as it was stored, so a tombstone stored
+ * before keyed paths existed (a record key such as an MCP server named `a["b"]`) keeps its
+ * meaning.
+ */
+export function getConfigTombstoneSegments(tombstone: string): ConfigPathSegments {
+ return readConfigEntryTombstone(tombstone)?.segments ?? parseFieldPath(tombstone);
+}
+
+function isSameArray(left: ConfigPathSegments, right: ConfigPathSegments): boolean {
+ return left.length === right.length && isSegmentPrefix(left, right);
+}
+
+/**
+ * Whether stored tombstone `tombstone` is at or below `location`: for a dotted location, the
+ * plain tombstones below it and every keyed one under an array at or below it; for a keyed
+ * location, the keyed tombstones of the same entry (by identity, so `ollama` covers `Ollama`)
+ * whose path inside the entry is at or below its own.
+ */
+export function isConfigTombstoneAtOrBelow(tombstone: string, location: ConfigLocation): boolean {
+ const target = toConfigEntryLocation(location);
+ if (!target) {
+ return (
+ !location.entry && isSegmentPrefix(location.segments, getConfigTombstoneSegments(tombstone))
+ );
+ }
+ const stored = readConfigEntryTombstone(tombstone);
+ return (
+ stored != null &&
+ stored.identity === target.identity &&
+ isSameArray(stored.segments, target.segments) &&
+ isSegmentPrefix(target.entry.rest, stored.entry.rest)
+ );
+}
+
+/** Whether `tombstone` hides the whole entry `key` of the merged-by-key array at `segments`. */
+export function isConfigEntryTombstone(
+ tombstone: string,
+ segments: ConfigPathSegments,
+ key: string,
+): boolean {
+ const stored = readConfigEntryTombstone(tombstone);
+ return (
+ stored != null &&
+ stored.entry.rest.length === 0 &&
+ isSameArray(stored.segments, segments) &&
+ stored.identity === getConfigEntryIdentity(segments, key)
+ );
+}
+
+/** The override (YAML) segments of every array merged by key. */
+export function getConfigMergeArrays(): string[][] {
+ return Object.keys(ARRAY_MERGE_KEYS).map((path) => {
+ const [first, ...rest] = path.split('.');
+ const section = Object.entries(OVERRIDE_KEY_MAP).find(([, appKey]) => appKey === first)?.[0];
+ return [section ?? first, ...rest];
+ });
+}
diff --git a/packages/data-schemas/src/app/conformance.ts b/packages/data-schemas/src/app/conformance.ts
index 785a58aa6f..348a956b42 100644
--- a/packages/data-schemas/src/app/conformance.ts
+++ b/packages/data-schemas/src/app/conformance.ts
@@ -232,6 +232,18 @@ export function describeConfigStoreConformance(harness: ConfigStoreHarness): voi
expect((await store.read(role('hidden')))?.tombstones).toEqual(tombstones);
});
+ it('keeps keyed tombstones as written, whatever the entry key holds', async () => {
+ const tombstones = [
+ 'endpoints.custom["api.example.com"]',
+ 'endpoints.custom["$cost ~ \\"quoted\\" [x]"].headers.X-Key',
+ 'endpoints.custom["名前 🚀"].addParams.anthropicApiUrl',
+ ];
+
+ await store.write(role('keyed'), draft({}, { tombstones }), ABSENT_CONFIG_REVISION);
+
+ expect((await store.read(role('keyed')))?.tombstones).toEqual(tombstones);
+ });
+
it('reads inactive documents', async () => {
await store.write(role('off'), draft({}, { isActive: false }), ABSENT_CONFIG_REVISION);
@@ -498,6 +510,34 @@ export function describeConfigStoreConformance(harness: ConfigStoreHarness): voi
expect(shown.configVersion).toBe(4);
});
+ it('keyed tombstones hide an entry by its key, and an entry write or a reset clears them', async () => {
+ const operations = createConfigOperations(store);
+ await operations.setFields(role('keyed-ops'), PrincipalModel.ROLE, {
+ 'endpoints.custom': [{ name: 'a.b', baseURL: 'https://a', headers: { X: 'x', Y: 'y' } }],
+ });
+
+ const hidden = await operations.tombstoneFields(role('keyed-ops'), PrincipalModel.ROLE, [
+ 'endpoints.custom["a.b"].headers.X',
+ 'endpoints.custom["yaml one"]',
+ ]);
+ expect(hidden.overrides).toEqual({
+ endpoints: { custom: [{ name: 'a.b', baseURL: 'https://a', headers: { Y: 'y' } }] },
+ });
+ expect(hidden.tombstones).toEqual([
+ 'endpoints.custom["a.b"].headers.X',
+ 'endpoints.custom["yaml one"]',
+ ]);
+
+ const shown = await operations.setFields(role('keyed-ops'), PrincipalModel.ROLE, {
+ 'endpoints.custom': [{ name: 'yaml one', titleModel: 't' }],
+ });
+ expect(shown.tombstones).toEqual(['endpoints.custom["a.b"].headers.X']);
+
+ const reset = await operations.unsetFields(role('keyed-ops'), 'endpoints.custom');
+ expect(reset?.overrides).toEqual({});
+ expect(reset?.tombstones).toEqual([]);
+ });
+
it('lists the active documents tombstoned at or below a path, in store order, without overrides', async () => {
const operations = createConfigOperations(store);
const tombstone = (principalId: string, fieldPath: string, priority?: number) =>
diff --git a/packages/data-schemas/src/app/index.ts b/packages/data-schemas/src/app/index.ts
index c13ed9efd2..272c7ed01d 100644
--- a/packages/data-schemas/src/app/index.ts
+++ b/packages/data-schemas/src/app/index.ts
@@ -9,6 +9,7 @@ export * from './turnstile';
export * from './vertex';
export * from './web';
export * from './resolution';
+export { foldConfigMergeKey, getConfigEntryIdentity, getConfigArrayMergeKey } from './collections';
export * from './precedence';
export * from './paths';
export * from './mutations';
diff --git a/packages/data-schemas/src/app/mutations.spec.ts b/packages/data-schemas/src/app/mutations.spec.ts
index 0cbe187f05..9b39dbfabf 100644
--- a/packages/data-schemas/src/app/mutations.spec.ts
+++ b/packages/data-schemas/src/app/mutations.spec.ts
@@ -5,7 +5,10 @@ import {
toConfigOverrideState,
tombstoneConfigPaths,
replaceConfigOverrides,
+ getWriteClearedTombstones,
isConfigOverrideStateEmpty,
+ renameConfigEntryTombstones,
+ renameConfigEntriesTombstones,
} from './mutations';
import { isConfigPathError, parseFieldPath } from './paths';
@@ -102,6 +105,15 @@ describe('unsetConfigPaths', () => {
expect(next.tombstones).toEqual(['mcpServers.github']);
});
+ it('drops a stored tombstone of a record key holding `["` by that key, as it was written', () => {
+ const legacy = state({}, ['mcpServers.a["b"]']);
+
+ expect(unsetConfigPaths(legacy, [['mcpServers', 'a']]).tombstones).toEqual([
+ 'mcpServers.a["b"]',
+ ]);
+ expect(unsetConfigPaths(legacy, [['mcpServers', 'a["b"]']]).tombstones).toEqual([]);
+ });
+
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'),
@@ -168,3 +180,215 @@ describe('replaceConfigOverrides and emptiness', () => {
);
});
});
+
+describe('keyed locations: entries of an array merged by key', () => {
+ const CUSTOM = ['endpoints', 'custom'];
+ const keyed = (key: string, rest: string[] = []) => ({ segments: CUSTOM, entry: { key, rest } });
+ const own = (name: string, extra: Record<string, unknown> = {}) => ({
+ name,
+ baseURL: `https://${name}.example.com`,
+ ...extra,
+ });
+
+ it('hides an inherited entry on a document with no array, storing the canonical keyed path', () => {
+ const next = tombstoneConfigPaths(state({}), [keyed('My "Gateway" v1.2')]);
+ expect(next).toEqual({
+ overrides: {},
+ tombstones: ['endpoints.custom["My \\"Gateway\\" v1.2"]'],
+ });
+ });
+
+ it('removes the own entry (every stored spelling) when hiding it, and the array once empty', () => {
+ const input = state({ endpoints: { custom: [own('Ollama'), own('ollama')] } });
+ const next = tombstoneConfigPaths(input, [keyed('OLLAMA')]);
+ expect(next.overrides).toEqual({});
+ expect(next.tombstones).toEqual(['endpoints.custom["OLLAMA"]']);
+ });
+
+ it('hides a path inside an entry and removes it from the own entry, keeping the rest', () => {
+ const input = state({
+ endpoints: { custom: [own('gw', { headers: { A: 'a', B: 'b' } }), own('other')] },
+ });
+ const next = tombstoneConfigPaths(input, [keyed('gw', ['headers', 'A'])]);
+ expect(next.overrides).toEqual({
+ endpoints: { custom: [own('gw', { headers: { B: 'b' } }), own('other')] },
+ });
+ expect(next.tombstones).toEqual(['endpoints.custom["gw"].headers.A']);
+ });
+
+ it('drops an own entry left holding only its key, which overrides nothing', () => {
+ const input = state({ endpoints: { custom: [{ name: 'gw', headers: { A: 'a' } }] } });
+ const next = tombstoneConfigPaths(input, [keyed('gw', ['headers', 'A'])]);
+ expect(next.overrides).toEqual({});
+ });
+
+ it('stores a keyed tombstone once per entry identity and path', () => {
+ const input = state({}, ['endpoints.custom["Ollama"].headers']);
+ expect(tombstoneConfigPaths(input, [keyed('ollama', ['headers'])]).tombstones).toEqual([
+ 'endpoints.custom["Ollama"].headers',
+ ]);
+ expect(tombstoneConfigPaths(input, [keyed('ollama')]).tombstones).toEqual([
+ 'endpoints.custom["Ollama"].headers',
+ 'endpoints.custom["ollama"]',
+ ]);
+ });
+
+ it('refuses a keyed location after an array that is not merged by key', () => {
+ const error = (() => {
+ try {
+ tombstoneConfigPaths(state({}), [
+ { segments: ['modelSpecs', 'list'], entry: { key: 'x', rest: [] } },
+ ]);
+ } catch (caught) {
+ return caught;
+ }
+ })();
+ expect(isConfigPathError(error) && error.reason).toBe('keyed_path');
+ });
+
+ it('unsets an own entry or a path inside it with the keyed tombstones at or below it', () => {
+ const input = state(
+ { endpoints: { custom: [own('Ollama', { headers: { A: 'a', B: 'b' } })] } },
+ [
+ 'endpoints.custom["OLLAMA"].headers.A',
+ 'endpoints.custom["Ollama"].addParams',
+ 'endpoints.custom["other"].headers.A',
+ 'endpoints.custom["ollama2"].headers.A',
+ 'memory.agent',
+ ],
+ );
+ const headers = unsetConfigPaths(input, [keyed('ollama', ['headers'])]);
+ expect(headers.overrides).toEqual({ endpoints: { custom: [own('Ollama')] } });
+ expect(headers.tombstones).toEqual([
+ 'endpoints.custom["Ollama"].addParams',
+ 'endpoints.custom["other"].headers.A',
+ 'endpoints.custom["ollama2"].headers.A',
+ 'memory.agent',
+ ]);
+
+ const whole = unsetConfigPaths(
+ state(
+ input.overrides,
+ input.tombstones.filter((path) => !path.includes('ollama2')),
+ ),
+ [keyed('ollama')],
+ );
+ expect(whole.overrides).toEqual({});
+ expect(whole.tombstones).toEqual(['endpoints.custom["other"].headers.A', 'memory.agent']);
+ });
+
+ it('clears every keyed tombstone under an unset of the collection or an ancestor', () => {
+ const input = state({}, [
+ 'endpoints.custom["a"]',
+ 'endpoints.custom["b.c"].headers.X',
+ 'endpoints.openAI',
+ ]);
+ expect(unsetConfigPaths(input, [CUSTOM]).tombstones).toEqual(['endpoints.openAI']);
+ expect(unsetConfigPaths(input, [['endpoints']]).tombstones).toEqual([]);
+ expect(unsetConfigPaths(input, [['endpoints', 'custom', '0']]).tombstones).toEqual(
+ input.tombstones,
+ );
+ });
+
+ it('a write of an entry clears the tombstone that hides it whole, never those inside it', () => {
+ const input = state({}, [
+ 'endpoints.custom["Ollama"]',
+ 'endpoints.custom["Ollama"].headers.A',
+ 'endpoints.custom["kept"]',
+ ]);
+ const written = setConfigFields(input, [{ segments: CUSTOM, value: [own('ollama')] }]);
+ expect(written.tombstones).toEqual([
+ 'endpoints.custom["Ollama"].headers.A',
+ 'endpoints.custom["kept"]',
+ ]);
+ const viaSection = setConfigFields(input, [
+ { segments: ['endpoints'], value: { custom: [own('kept')] } },
+ ]);
+ expect(viaSection.tombstones).toEqual([
+ 'endpoints.custom["Ollama"]',
+ 'endpoints.custom["Ollama"].headers.A',
+ ]);
+ expect(getWriteClearedTombstones(input.tombstones, ['endpoints', 'openAI'], {})).toEqual([]);
+ });
+
+ it('a write by segments that only spell an entry keeps the keyed tombstones of that entry', () => {
+ const input = state({}, [
+ 'endpoints.custom["GPT"]',
+ 'endpoints.custom["OR"].headers.X',
+ 'mcpServers.a["b"]',
+ ]);
+ const entry = setConfigFields(input, [
+ { segments: ['endpoints', 'custom["GPT"]'], value: { titleModel: 'x' } },
+ ]);
+ expect(entry).toEqual(
+ state({ endpoints: { 'custom["GPT"]': { titleModel: 'x' } } }, input.tombstones),
+ );
+ const header = setConfigFields(input, [
+ { segments: ['endpoints', 'custom["OR"]', 'headers', 'X'], value: 'v' },
+ ]);
+ expect(header.tombstones).toEqual(input.tombstones);
+ expect(
+ getWriteClearedTombstones(input.tombstones, ['endpoints', 'custom["OR"]', 'headers'], {}),
+ ).toEqual([]);
+ const legacy = setConfigFields(input, [{ segments: ['mcpServers', 'a["b"]'], value: {} }]);
+ expect(legacy.tombstones).toEqual(input.tombstones.slice(0, 2));
+ });
+
+ it.each([
+ ['a dotted step inside the entry', keyed('K', ['headers', 'a.b']), 'dotted_segment'],
+ ['a key step inside the entry', keyed('K', ['headers', 'x["y"]']), 'keyed_path'],
+ ['an unsafe step inside the entry', keyed('K', ['__proto__']), 'unsafe_segment'],
+ ['an empty step inside the entry', keyed('K', ['headers', '']), 'empty_path'],
+ ['an empty key', keyed(''), 'keyed_path'],
+ ['an unsafe key', keyed('$where'), 'keyed_path'],
+ ['a key past the length limit', keyed('k'.repeat(257)), 'keyed_path'],
+ [
+ 'a key step in the array',
+ { segments: ['endpoints', 'custom["x"]'], entry: { key: 'K', rest: [] } },
+ 'keyed_path',
+ ],
+ [
+ 'too deep a path',
+ keyed(
+ 'K',
+ Array.from({ length: 30 }, (_, index) => `s${index}`),
+ ),
+ 'too_deep',
+ ],
+ ])('refuses a keyed location with %s on a hide and a reset', (_label, location, reason) => {
+ const input = state({ endpoints: { custom: [own('K', { headers: { 'a.b': 'own' } })] } });
+ const refused = (run: () => unknown) => {
+ try {
+ run();
+ } catch (caught) {
+ return isConfigPathError(caught) && caught.reason;
+ }
+ return 'applied';
+ };
+ expect(refused(() => tombstoneConfigPaths(input, [location]))).toBe(reason);
+ expect(refused(() => unsetConfigPaths(input, [location]))).toBe(reason);
+ });
+
+ it('moves the keyed tombstones of a renamed entry to its new key, and drops a hide of the new key', () => {
+ const input = state({}, [
+ 'endpoints.custom["ollama"].headers.A',
+ 'endpoints.custom["Ollama"].addParams',
+ 'endpoints.custom["Old"].headers.B',
+ 'endpoints.custom["new"]',
+ 'endpoints.custom["new"].addParams',
+ 'endpoints.custom["other"]',
+ ]);
+ const moved = renameConfigEntryTombstones(input, CUSTOM, 'OLLAMA', 'new');
+ expect(moved.tombstones).toEqual([
+ 'endpoints.custom["new"].headers.A',
+ 'endpoints.custom["new"].addParams',
+ 'endpoints.custom["Old"].headers.B',
+ 'endpoints.custom["other"]',
+ ]);
+ const untouched = state({}, ['endpoints.custom["other"]']);
+ expect(renameConfigEntryTombstones(untouched, CUSTOM, 'old', 'new')).toBe(untouched);
+ expect(
+ renameConfigEntriesTombstones(input, [{ segments: CUSTOM, from: 'ollama', to: 'new' }]),
+ ).toEqual(moved);
+ });
+});
diff --git a/packages/data-schemas/src/app/mutations.ts b/packages/data-schemas/src/app/mutations.ts
index 918a125b16..67ba2f989a 100644
--- a/packages/data-schemas/src/app/mutations.ts
+++ b/packages/data-schemas/src/app/mutations.ts
@@ -1,15 +1,30 @@
import type { TCustomConfig } from 'librechat-data-provider';
-import type { ConfigPathSegments } from './paths';
+import type { ConfigLocation, ConfigPathSegments } from './paths';
+import type { ConfigEntryLocation } from './collections';
import {
+ getAtPath,
setAtPath,
unsetAtPath,
isPlainRecord,
+ isSegmentPrefix,
+ formatKeyedPath,
+ ConfigPathError,
isEffectivelyEmpty,
- formatTombstonePath,
pruneEmptyAncestors,
+ formatConfigLocation,
getClearedTombstones,
- isTombstoneAtOrBelow,
+ getKeyedLocationError,
} from './paths';
+import {
+ isConfigEntryAt,
+ getConfigMergeArrays,
+ toConfigEntryLocation,
+ isConfigEntryTombstone,
+ getConfigArrayMergeKey,
+ getConfigEntryIdentity,
+ readConfigEntryTombstone,
+ isConfigTombstoneAtOrBelow,
+} from './collections';
/**
* The part of a principal's config document that override mutations change. Every mutation in
@@ -50,74 +65,289 @@ function asRecord(overrides: Partial<TCustomConfig>): JsonRecord {
return overrides as JsonRecord;
}
+/** A path a removal or tombstone lands on: its segments, or a location that may be keyed. */
+export type ConfigRemoval = ConfigPathSegments | ConfigLocation;
+
+function isLocation(removal: ConfigRemoval): removal is ConfigLocation {
+ return !Array.isArray(removal);
+}
+
+function toLocation(removal: ConfigRemoval): ConfigLocation {
+ return isLocation(removal) ? removal : { segments: removal };
+}
+
+/**
+ * A keyed location whose array is merged by key and whose stored form names it exactly
+ * (`getKeyedLocationError`); any other keyed location throws a `ConfigPathError`, so a
+ * tombstone never names a different path from the one removed.
+ */
+function requireEntryLocation(location: ConfigLocation): ConfigEntryLocation {
+ const reason = location.entry ? getKeyedLocationError(location.segments, location.entry) : null;
+ if (reason) {
+ throw new ConfigPathError([...location.segments], reason);
+ }
+ const entry = toConfigEntryLocation(location);
+ if (!entry) {
+ throw new ConfigPathError([...location.segments], 'keyed_path');
+ }
+ return entry;
+}
+
+/**
+ * The entries a write of `value` at `segments` writes into arrays merged by key, by key: the
+ * write is the array itself or one of its ancestors (`endpoints` holding `custom`).
+ */
+function getWrittenEntries(
+ segments: ConfigPathSegments,
+ value: unknown,
+): Array<{ segments: string[]; key: string }> {
+ return getConfigMergeArrays().flatMap((array) => {
+ if (!isSegmentPrefix(segments, array)) {
+ return [];
+ }
+ const items = getAtPath(value, array.slice(segments.length));
+ const keyField = getConfigArrayMergeKey(array);
+ if (!Array.isArray(items) || !keyField) {
+ return [];
+ }
+ return items.flatMap((item) => {
+ const key = isPlainRecord(item) ? item[keyField] : undefined;
+ return typeof key === 'string' && key !== '' ? [{ segments: array, key }] : [];
+ });
+ });
+}
+
+/**
+ * The tombstones a write at `segments` clears by path ({@link getClearedTombstones}: the path and
+ * its ancestors below the section), leaving out any that would read as a keyed tombstone.
+ * Segments name keys as written, so a segment `custom["Name"]` is a key of that spelling and never
+ * entry `Name`, whose tombstones only a write of the entry itself clears.
+ */
+export function getPathClearedTombstones(segments: ConfigPathSegments): string[] {
+ return getClearedTombstones(segments).filter((path) => readConfigEntryTombstone(path) == null);
+}
+
/**
- * 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.
+ * The stored tombstones a field write clears: the written path and its ancestors below the
+ * section (so a whole-section tombstone survives a nested write), and for each entry the write
+ * puts in an array merged by key, the tombstone that hides that whole entry
+ * (`endpoints.custom["Name"]`). Tombstones inside an entry (`endpoints.custom["Name"].headers.X`)
+ * stay, as a tombstone below any other written path does, and a keyed tombstone is never cleared
+ * by a segment that only spells its path ({@link getPathClearedTombstones}).
+ */
+export function getWriteClearedTombstones(
+ tombstones: readonly string[],
+ segments: ConfigPathSegments,
+ value: unknown,
+): string[] {
+ const cleared = new Set(getPathClearedTombstones(segments));
+ const entries = getWrittenEntries(segments, value);
+ return tombstones.filter(
+ (tombstone) =>
+ cleared.has(tombstone) ||
+ entries.some((entry) => isConfigEntryTombstone(tombstone, entry.segments, entry.key)),
+ );
+}
+
+/**
+ * Sets each field in order, dropping the tombstones each write clears
+ * ({@link getWriteClearedTombstones}). 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>();
+ let tombstones = state.tombstones;
for (const { segments, value } of writes) {
overrides = setAtPath(overrides, segments, value);
- for (const path of getClearedTombstones(segments)) {
- cleared.add(path);
+ const cleared = new Set(getWriteClearedTombstones(tombstones, segments, value));
+ if (cleared.size > 0) {
+ tombstones = tombstones.filter((path) => !cleared.has(path));
}
}
- return {
- overrides: overrides as Partial<TCustomConfig>,
- tombstones: state.tombstones.filter((path) => !cleared.has(path)),
- };
+ return { overrides: overrides as Partial<TCustomConfig>, tombstones: [...tombstones] };
}
-/** Removes each path, then the objects the removals left empty. */
-function removePaths(overrides: JsonRecord, paths: readonly ConfigPathSegments[]): JsonRecord {
+/** Writes `items` back at `segments`, removing the array (and emptied parents) once empty. */
+function writeEntries(overrides: JsonRecord, segments: ConfigPathSegments, items: unknown[]) {
+ if (items.length > 0) {
+ return setAtPath(overrides, segments, items);
+ }
+ return pruneEmptyAncestors(unsetAtPath(overrides, segments), segments);
+}
+
+/** Whether an entry holds nothing but its key, so it overrides nothing it is merged onto. */
+function holdsOnlyKey(entry: unknown, keyField: string): boolean {
+ return isPlainRecord(entry) && Object.keys(entry).every((key) => key === keyField);
+}
+
+/**
+ * Removes a keyed location from the principal's own entries: every entry with its key (by
+ * identity), or the path inside each, with the objects that leaves empty. An entry left with
+ * nothing but its key goes too, and the array once it is empty.
+ */
+function removeEntryLocation(overrides: JsonRecord, location: ConfigEntryLocation): JsonRecord {
+ const items = getAtPath(overrides, location.segments);
+ if (!Array.isArray(items) || !items.some((item) => isConfigEntryAt(location, item))) {
+ return overrides;
+ }
+ const { rest } = location.entry;
+ let changed = false;
+ const next = items.flatMap((item) => {
+ if (!isConfigEntryAt(location, item)) {
+ return [item];
+ }
+ const trimmed =
+ rest.length === 0 ? null : pruneEmptyAncestors(unsetAtPath(item as JsonRecord, rest), rest);
+ if (trimmed === item) {
+ return [item];
+ }
+ changed = true;
+ return trimmed == null || holdsOnlyKey(trimmed, location.keyField) ? [] : [trimmed];
+ });
+ return changed ? writeEntries(overrides, location.segments, next) : overrides;
+}
+
+/** Removes each location, then the objects the removals left empty. */
+function removeLocations(overrides: JsonRecord, locations: readonly ConfigLocation[]): JsonRecord {
+ const paths = locations.filter((location) => !location.entry).map(({ segments }) => segments);
const removed = paths.reduce((current, segments) => unsetAtPath(current, segments), overrides);
- return paths.reduce((current, segments) => pruneEmptyAncestors(current, segments), removed);
+ const pruned = paths.reduce(
+ (current, segments) => pruneEmptyAncestors(current, segments),
+ removed,
+ );
+ return locations
+ .filter((location) => location.entry)
+ .reduce(
+ (current, location) => removeEntryLocation(current, requireEntryLocation(location)),
+ pruned,
+ );
}
/**
* 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.
+ *
+ * A keyed location (`endpoints.custom["Name"]`, or a path inside the entry) resets the
+ * principal's own entry of that key, or the path inside it, and drops the keyed tombstones of the
+ * same entry at or below it; a path at or above the array drops every keyed tombstone under it.
*/
export function unsetConfigPaths(
state: ConfigOverrideState,
- paths: readonly ConfigPathSegments[],
+ paths: readonly ConfigRemoval[],
): ConfigOverrideState {
+ const locations = paths.map(toLocation);
return {
- overrides: removePaths(asRecord(state.overrides), paths) as Partial<TCustomConfig>,
+ overrides: removeLocations(asRecord(state.overrides), locations) as Partial<TCustomConfig>,
tombstones: state.tombstones.filter(
- (tombstone) => !paths.some((segments) => isTombstoneAtOrBelow(tombstone, segments)),
+ (tombstone) => !locations.some((location) => isConfigTombstoneAtOrBelow(tombstone, location)),
),
};
}
+/** Whether a stored tombstone names exactly `location`, a keyed one by its key's identity. */
+function isSameTombstone(tombstone: string, location: ConfigLocation, formatted: string): boolean {
+ if (!location.entry) {
+ return tombstone === formatted;
+ }
+ const stored = readConfigEntryTombstone(tombstone);
+ return (
+ stored != null &&
+ isConfigTombstoneAtOrBelow(tombstone, location) &&
+ stored.entry.rest.length === location.entry.rest.length
+ );
+}
+
/**
* 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`.
+ *
+ * A keyed location hides the inherited entry of that key, or the path inside it, and removes
+ * the principal's own entry, or that path from it. Its tombstone is stored as a canonical keyed
+ * path (`formatKeyedPath`), once per entry identity and path. A keyed location after an array
+ * not merged by key throws a `ConfigPathError` (`keyed_path`).
*/
export function tombstoneConfigPaths(
state: ConfigOverrideState,
- paths: readonly ConfigPathSegments[],
+ paths: readonly ConfigRemoval[],
): ConfigOverrideState {
- const added = paths.map(formatTombstonePath);
+ const locations = paths.map(toLocation);
const tombstones = [...state.tombstones];
- for (const path of added) {
- if (!tombstones.includes(path)) {
- tombstones.push(path);
+ for (const location of locations) {
+ if (location.entry) {
+ requireEntryLocation(location);
+ }
+ const formatted = formatConfigLocation(location);
+ if (!tombstones.some((tombstone) => isSameTombstone(tombstone, location, formatted))) {
+ tombstones.push(formatted);
}
}
return {
- overrides: removePaths(asRecord(state.overrides), paths) as Partial<TCustomConfig>,
+ overrides: removeLocations(asRecord(state.overrides), locations) as Partial<TCustomConfig>,
tombstones,
};
}
+/** A rename of one of the principal's own entries of the merged-by-key array at `segments`. */
+export interface ConfigEntryRename {
+ segments: ConfigPathSegments;
+ from: string;
+ to: string;
+}
+
+/** {@link renameConfigEntryTombstones} for each rename, in order. */
+export function renameConfigEntriesTombstones(
+ state: ConfigOverrideState,
+ renames: readonly ConfigEntryRename[],
+): ConfigOverrideState {
+ return renames.reduce(
+ (current, { segments, from, to }) => renameConfigEntryTombstones(current, segments, from, to),
+ state,
+ );
+}
+
+/**
+ * Moves the keyed tombstones of entry `from` of the merged-by-key array at `segments` to entry
+ * `to`, as a rename of the principal's own entry carries what it hides: each keeps its path
+ * inside the entry. The tombstone that hides `to` whole goes, since the principal's own entry
+ * now has that key, and a moved tombstone that `to` already has is kept once.
+ */
+export function renameConfigEntryTombstones(
+ state: ConfigOverrideState,
+ segments: ConfigPathSegments,
+ from: string,
+ to: string,
+): ConfigOverrideState {
+ const fromIdentity = getConfigEntryIdentity(segments, from);
+ const tombstones: string[] = [];
+ let changed = false;
+ for (const tombstone of state.tombstones) {
+ const stored = readConfigEntryTombstone(tombstone);
+ const moves =
+ stored != null &&
+ stored.identity === fromIdentity &&
+ stored.segments.length === segments.length &&
+ isSegmentPrefix(stored.segments, segments);
+ const next = moves ? formatKeyedPath(segments, to, stored.entry.rest) : tombstone;
+ const location = readConfigEntryTombstone(next);
+ const kept =
+ !isConfigEntryTombstone(next, segments, to) &&
+ !tombstones.some((path) =>
+ location ? isSameTombstone(path, location, next) : path === next,
+ );
+ if (kept) {
+ tombstones.push(next);
+ }
+ if (!kept || next !== tombstone) {
+ changed = true;
+ }
+ }
+ return changed ? { overrides: state.overrides, tombstones } : state;
+}
/** Replaces the overrides whole. Tombstones stay, so they keep shaping the inherited base. */
export function replaceConfigOverrides(
state: ConfigOverrideState,
diff --git a/packages/data-schemas/src/app/paths.spec.ts b/packages/data-schemas/src/app/paths.spec.ts
index 1c0032bb63..3905ced940 100644
--- a/packages/data-schemas/src/app/paths.spec.ts
+++ b/packages/data-schemas/src/app/paths.spec.ts
@@ -14,6 +14,12 @@ import {
MAX_CONFIG_PATH_DEPTH,
parseConfigPathSegments,
getTombstonePathsToClear,
+ parseConfigPath,
+ formatKeyedPath,
+ isConfigEntryKey,
+ isKeyedConfigPath,
+ formatConfigLocation,
+ MAX_CONFIG_ENTRY_KEY_LENGTH,
} from './paths';
function reasonOf(fn: () => unknown): string | undefined {
@@ -222,3 +228,92 @@ describe('client segment paths', () => {
expect(parseConfigPathSegments(Array(MAX_CONFIG_PATH_DEPTH).fill('a')).ok).toBe(true);
});
});
+
+describe('keyed config paths', () => {
+ const CUSTOM = ['endpoints', 'custom'];
+
+ it('reads a dotted path as its segments and a keyed one as an entry and a path inside it', () => {
+ expect(parseConfigPath('mcpServers.github.headers')).toEqual({
+ segments: ['mcpServers', 'github', 'headers'],
+ });
+ expect(parseConfigPath('endpoints.custom["Gateway"]')).toEqual({
+ segments: CUSTOM,
+ entry: { key: 'Gateway', rest: [] },
+ });
+ expect(parseConfigPath('endpoints.custom["Gateway"].headers.X-Key')).toEqual({
+ segments: CUSTOM,
+ entry: { key: 'Gateway', rest: ['headers', 'X-Key'] },
+ });
+ });
+
+ it('takes any character in a key, since it is a JSON string, and round-trips it', () => {
+ const names = [
+ 'My Endpoint',
+ 'api.example.com',
+ 'quote " inside',
+ 'bracket ] and [ "',
+ 'back\\slash',
+ 'trailing.',
+ 'a..b',
+ 'cost$',
+ 'Ünïcødé 名前 🚀',
+ 'line\nbreak',
+ ];
+ for (const name of names) {
+ const path = formatKeyedPath(CUSTOM, name, ['headers', 'X-Key']);
+ expect(isKeyedConfigPath(path)).toBe(true);
+ expect(parseConfigPath(path)).toEqual({
+ segments: CUSTOM,
+ entry: { key: name, rest: ['headers', 'X-Key'] },
+ });
+ }
+ expect(parseConfigPath('endpoints.custom["\\u0041"]')?.entry?.key).toBe('A');
+ expect(formatKeyedPath(CUSTOM, 'A')).toBe('endpoints.custom["A"]');
+ });
+
+ it('refuses a malformed keyed path instead of reading part of it', () => {
+ const malformed = [
+ 'endpoints.custom["Gateway"',
+ 'endpoints.custom["Gateway]',
+ 'endpoints.custom["Gateway"]headers',
+ 'endpoints.custom["Gateway"].',
+ 'endpoints.custom["Gateway"]..headers',
+ 'endpoints.custom["a"]["b"]',
+ 'endpoints.custom["a"].headers["b"]',
+ 'endpoints.custom[""]',
+ '["Gateway"]',
+ '.custom["Gateway"]',
+ 'endpoints..custom["Gateway"]',
+ 'endpoints.custom["__proto__"]',
+ 'endpoints.custom["constructor"]',
+ 'endpoints.custom["$where"]',
+ 'endpoints.custom["Gateway"].__proto__',
+ 'endpoints.custom["Gateway"].$set',
+ 'endpoints.$custom["Gateway"]',
+ 'endpoints.custom["bad \\x escape"]',
+ `endpoints.custom[${JSON.stringify('n'.repeat(MAX_CONFIG_ENTRY_KEY_LENGTH + 1))}]`,
+ `endpoints.custom["a"].${Array.from({ length: MAX_CONFIG_PATH_DEPTH }, () => 'x').join('.')}`,
+ ];
+ for (const path of malformed) {
+ expect(parseConfigPath(path)).toBeNull();
+ }
+ expect(parseConfigPath(`endpoints.custom[${JSON.stringify('n'.repeat(256))}]`)).not.toBeNull();
+ expect(isConfigEntryKey('$x')).toBe(false);
+ expect(isConfigEntryKey('x$')).toBe(true);
+ });
+
+ it('treats only `["` as a key step, so other brackets stay part of a dotted key', () => {
+ expect(isKeyedConfigPath('endpoints.custom[0]')).toBe(false);
+ expect(parseConfigPath('endpoints.custom[0]')).toEqual({
+ segments: ['endpoints', 'custom[0]'],
+ });
+ });
+
+ it('never stores a dotted tombstone a later read would take for a keyed one', () => {
+ expect(reasonOf(() => formatTombstonePath(['endpoints', 'custom["x"]']))).toBe('keyed_path');
+ expect(formatConfigLocation({ segments: CUSTOM, entry: { key: 'x', rest: ['a'] } })).toBe(
+ 'endpoints.custom["x"].a',
+ );
+ expect(formatConfigLocation({ segments: ['memory', 'agent'] })).toBe('memory.agent');
+ });
+});
diff --git a/packages/data-schemas/src/app/paths.ts b/packages/data-schemas/src/app/paths.ts
index c88b0596be..acb4c410ea 100644
--- a/packages/data-schemas/src/app/paths.ts
+++ b/packages/data-schemas/src/app/paths.ts
@@ -4,7 +4,8 @@
* 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.
+ * paths whose segments contain no dots, or one entry of an array merged by key by its key
+ * (`endpoints.custom["Name"].headers`, read with `parseConfigPath`), whatever the key holds.
*
* Every helper is pure: it never mutates its input and copies only the containers along the
* path it changes.
@@ -33,7 +34,14 @@ export type ConfigPathErrorReason =
/** 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';
+ | 'too_deep'
+ /**
+ * An entry key step (`["name"]`) is malformed, follows something other than an array merged by
+ * key, or appears where only a whole path is accepted (a write, or `segments`).
+ */
+ | 'keyed_path'
+ /** A keyed path names the key field of its entry, which identifies the entry itself. */
+ | 'merge_key';
/** The deepest path a client may address; config schemas nest far less than this. */
export const MAX_CONFIG_PATH_DEPTH = 32;
@@ -116,15 +124,181 @@ export function isDotFreePath(segments: ConfigPathSegments): boolean {
return segments.every((segment) => !segment.includes('.'));
}
-/** Joins segments into the dotted form tombstones are stored in. */
+/**
+ * Joins segments into the dotted form tombstones are stored in. A segment holding `["` is
+ * refused: stored tombstones read that as an entry key step ({@link parseConfigPath}).
+ */
export function formatTombstonePath(segments: ConfigPathSegments): string {
assertSegments(segments);
if (!isDotFreePath(segments)) {
throw new ConfigPathError([...segments], 'dotted_segment');
}
+ if (segments.some((segment) => segment.includes(KEY_STEP_OPEN))) {
+ throw new ConfigPathError([...segments], 'keyed_path');
+ }
return segments.join('.');
}
+/** An entry of a merged-by-key array, by its key, and a path inside it. */
+export interface ConfigEntryStep {
+ /** The entry's key (a custom endpoint's `name`), as written. */
+ key: string;
+ /** The path inside the entry; empty for the whole entry. */
+ rest: ConfigPathSegments;
+}
+
+/**
+ * Where a removal or tombstone lands: `segments`, or with `entry`, one entry of the array at
+ * `segments` (merged by key) and a path inside it.
+ */
+export interface ConfigLocation {
+ segments: ConfigPathSegments;
+ entry?: ConfigEntryStep;
+}
+
+/** The longest entry key a keyed path can address. */
+export const MAX_CONFIG_ENTRY_KEY_LENGTH = 256;
+
+const KEY_STEP_OPEN = '["';
+
+/**
+ * Whether a dotted path holds an entry key step (`endpoints.custom["Name"]`). Such a path is
+ * read with {@link parseConfigPath}, never split on its dots.
+ */
+export function isKeyedConfigPath(path: string): boolean {
+ return path.includes(KEY_STEP_OPEN);
+}
+
+/** Dotted segments that are each non-empty and safe, and hold no entry key step. */
+function readDottedSegments(text: string): string[] | null {
+ const segments = text.split('.');
+ const valid = segments.every(
+ (segment) =>
+ segment !== '' && !UNSAFE_SEGMENT.test(segment) && !segment.includes(KEY_STEP_OPEN),
+ );
+ return valid ? segments : null;
+}
+
+/** Index of the quote that closes the JSON string starting at `start`, or -1. */
+function findStringEnd(text: string, start: number): number {
+ for (let index = start + 1; index < text.length; index++) {
+ if (text[index] === '\\') {
+ index++;
+ } else if (text[index] === '"') {
+ return index;
+ }
+ }
+ return -1;
+}
+
+/**
+ * Whether a keyed path can name an entry by `key`: 1 to {@link MAX_CONFIG_ENTRY_KEY_LENGTH}
+ * characters, not starting with `$` or `__`, and not `constructor` or `prototype`.
+ */
+export function isConfigEntryKey(key: string): boolean {
+ return key !== '' && key.length <= MAX_CONFIG_ENTRY_KEY_LENGTH && !UNSAFE_SEGMENT.test(key);
+}
+
+/** The entry key a JSON string literal holds, or `null` when it is not one a path may name. */
+function readEntryKey(literal: string): string | null {
+ let key: unknown;
+ try {
+ key = JSON.parse(literal);
+ } catch {
+ return null;
+ }
+ return typeof key === 'string' && isConfigEntryKey(key) ? key : null;
+}
+
+/**
+ * Reads a stored tombstone or a client's `fieldPath`: a dotted path (split on its dots), or a
+ * keyed path `<array>["<key>"](.<path>)?`, which names one entry of an array merged by key by
+ * its key, a JSON string literal (so a name may hold dots, quotes, brackets or any other
+ * character), and optionally a dotted path inside it. A keyed path has one key step, dot-free
+ * segments that are non-empty and safe, a key of 1 to {@link MAX_CONFIG_ENTRY_KEY_LENGTH}
+ * characters that does not start with `$` or `__` and is not `constructor` or `prototype`, and
+ * at most {@link MAX_CONFIG_PATH_DEPTH} steps. `null` when a keyed path breaks any of these.
+ * Whether the array is merged by key is the caller's to check.
+ */
+export function parseConfigPath(path: string): ConfigLocation | null {
+ const open = path.indexOf(KEY_STEP_OPEN);
+ if (open === -1) {
+ return { segments: parseFieldPath(path) };
+ }
+ const segments = readDottedSegments(path.slice(0, open));
+ const close = findStringEnd(path, open + 1);
+ if (!segments || close === -1 || path[close + 1] !== ']') {
+ return null;
+ }
+ const key = readEntryKey(path.slice(open + 1, close + 1));
+ const after = path.slice(close + 2);
+ if (key == null || (after !== '' && !after.startsWith('.'))) {
+ return null;
+ }
+ const rest = after === '' ? [] : readDottedSegments(after.slice(1));
+ if (!rest || segments.length + 1 + rest.length > MAX_CONFIG_PATH_DEPTH) {
+ return null;
+ }
+ return { segments, entry: { key, rest } };
+}
+
+/** Why one step of a keyed location cannot be written in its stored form, or `null`. */
+function getKeyedStepError(segment: string): ConfigPathErrorReason | null {
+ if (segment === '') {
+ return 'empty_path';
+ }
+ if (UNSAFE_SEGMENT.test(segment)) {
+ return 'unsafe_segment';
+ }
+ if (segment.includes('.')) {
+ return 'dotted_segment';
+ }
+ return segment.includes(KEY_STEP_OPEN) ? 'keyed_path' : null;
+}
+
+/**
+ * Why a keyed location cannot be stored as the keyed path it names, or `null` when it can: its
+ * stored form must read back as itself ({@link parseConfigPath}), so the array's segments and
+ * the path inside the entry hold only non-empty, safe, dot-free steps with no key step, the key
+ * is one {@link isConfigEntryKey} accepts, and the whole is at most
+ * {@link MAX_CONFIG_PATH_DEPTH} steps deep.
+ */
+export function getKeyedLocationError(
+ segments: ConfigPathSegments,
+ entry: ConfigEntryStep,
+): ConfigPathErrorReason | null {
+ if (segments.length === 0) {
+ return 'empty_path';
+ }
+ if (segments.length + 1 + entry.rest.length > MAX_CONFIG_PATH_DEPTH) {
+ return 'too_deep';
+ }
+ for (const segment of [...segments, ...entry.rest]) {
+ const reason = getKeyedStepError(segment);
+ if (reason) {
+ return reason;
+ }
+ }
+ return isConfigEntryKey(entry.key) ? null : 'keyed_path';
+}
+
+/** The canonical keyed path of an entry and a path inside it (see {@link parseConfigPath}). */
+export function formatKeyedPath(
+ segments: ConfigPathSegments,
+ key: string,
+ rest: ConfigPathSegments = [],
+): string {
+ const entry = `${segments.join('.')}[${JSON.stringify(key)}]`;
+ return rest.length === 0 ? entry : `${entry}.${rest.join('.')}`;
+}
+
+/** A location in its stored form: a dotted path, or a canonical keyed path. */
+export function formatConfigLocation(location: ConfigLocation): string {
+ return location.entry
+ ? formatKeyedPath(location.segments, location.entry.key, location.entry.rest)
+ : formatTombstonePath(location.segments);
+}
+
/** Whether `prefix` addresses `segments` itself or one of its ancestors. */
export function isSegmentPrefix(prefix: ConfigPathSegments, segments: ConfigPathSegments): boolean {
return (
@@ -133,7 +307,11 @@ export function isSegmentPrefix(prefix: ConfigPathSegments, segments: ConfigPath
);
}
-/** Whether a stored tombstone names `segments` itself or a path below it. */
+/**
+ * Whether a dotted tombstone names `segments` itself or a path below it, split on its dots. A
+ * keyed tombstone is compared by its array with `isConfigTombstoneAtOrBelow` (`collections.ts`),
+ * which knows the arrays merged by key.
+ */
export function isTombstoneAtOrBelow(tombstone: string, segments: ConfigPathSegments): boolean {
return isSegmentPrefix(segments, parseFieldPath(tombstone));
}
diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.ts
index 4d26f2793e..5440394d37 100644
--- a/packages/data-schemas/src/app/resolution.spec.ts
+++ b/packages/data-schemas/src/app/resolution.spec.ts
@@ -9,7 +9,6 @@ import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provid
import type { AppConfig, IConfig } from '~/types';
import {
resolveRawConfig,
- foldConfigMergeKey,
isConfigRecordPath,
getConfigMergeRules,
mergeConfigOverrides,
@@ -18,18 +17,20 @@ import {
getConfigFieldIssues,
applyConfigTombstones,
getConfigChangeIssues,
- getConfigArrayMergeKey,
getDottedSectionIssues,
getConfigOverrideIssues,
combineFoldedConfigItems,
getIndexedMergeKeyIssues,
getConfigIssueParams,
getIgnoredConfigOverrides,
+ isConfigEntryArrayItemPath,
} from './resolution';
+import { foldConfigMergeKey, getConfigArrayMergeKey } from './collections';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
import { toConfigOverrideState } from './mutations';
import { applyConfigChanges } from './changes';
import { loadWebSearchConfig } from './web';
+import { formatKeyedPath } from './paths';
import logger from '~/config/winston';
function fakeConfig(
@@ -3849,3 +3850,145 @@ describe('getIgnoredConfigOverrides', () => {
warn.mockRestore();
});
});
+
+/**
+ * Keyed tombstones hide one entry of a merged-by-key array, or a path inside it, by the entry's
+ * key: `endpoints.custom["Name"]` and `endpoints.custom["Name"].headers.X-Key`.
+ */
+describe('mergeConfigOverrides: keyed tombstones of custom endpoints', () => {
+ type CustomItem = Record<string, unknown>;
+ const customOf = (config: AppConfig): CustomItem[] | undefined =>
+ (config as unknown as { endpoints?: { custom?: CustomItem[] } }).endpoints?.custom;
+ const entry = (name: string, extra: CustomItem = {}): CustomItem => ({
+ name,
+ apiKey: '${KEY}',
+ baseURL: `https://${encodeURIComponent(name)}.example.com/v1`,
+ models: { default: ['m'] },
+ ...extra,
+ });
+ const awkward = ['My Endpoint', 'api.example.com', 'quote " inside', 'bracket ] [ "x"'];
+ const yaml = [
+ ...awkward.map((name) => entry(name)),
+ entry('Ollama', { headers: { 'X-Team': 'a', 'X-Trace': 'b' } }),
+ ];
+ const base = { endpoints: { custom: yaml }, config: { endpoints: { custom: yaml } } };
+ const hide = (path: string, priority = 10, principalId = 'role') =>
+ fakeConfig({}, priority, [path], principalId);
+
+ it('hides an entry by its key, whatever characters the name holds', () => {
+ for (const name of awkward) {
+ const merged = mergeConfigOverrides(base as unknown as AppConfig, [
+ hide(formatKeyedPath(['endpoints', 'custom'], name)),
+ ]);
+ expect(customOf(merged)?.map((item) => item.name)).toEqual(
+ yaml.map((item) => item.name).filter((other) => other !== name),
+ );
+ }
+ });
+
+ it('hides the entry under the spelling the merge folds it to', () => {
+ const merged = mergeConfigOverrides(base as unknown as AppConfig, [
+ hide('endpoints.custom["OLLAMA"]'),
+ ]);
+ expect(customOf(merged)?.map((item) => item.name)).toEqual(awkward);
+ });
+
+ it('removes one inherited header and keeps its siblings (record-key tombstone)', () => {
+ const merged = mergeConfigOverrides(base as unknown as AppConfig, [
+ hide('endpoints.custom["Ollama"].headers.X-Team'),
+ ]);
+ expect(customOf(merged)?.find((item) => item.name === 'Ollama')?.headers).toEqual({
+ 'X-Trace': 'b',
+ });
+ expect(customOf(base as unknown as AppConfig)?.[4].headers).toEqual({
+ 'X-Team': 'a',
+ 'X-Trace': 'b',
+ });
+ });
+
+ it('keeps a key tombstone through a sibling write, and lets a higher layer re-add the key', () => {
+ const role = fakeConfig(
+ { endpoints: { custom: [{ name: 'Ollama', headers: { 'X-Other': 'c' } }] } },
+ 10,
+ ['endpoints.custom["Ollama"].headers.X-Team'],
+ );
+ const headersOf = (configs: IConfig[]) =>
+ customOf(mergeConfigOverrides(base as unknown as AppConfig, configs))?.find(
+ (item) => item.name === 'Ollama',
+ )?.headers;
+ expect(headersOf([role])).toEqual({ 'X-Trace': 'b', 'X-Other': 'c' });
+
+ const user = fakeConfig(
+ { endpoints: { custom: [{ name: 'Ollama', headers: { 'X-Team': 'user' } }] } },
+ 100,
+ [],
+ 'user',
+ );
+ expect(headersOf([role, user])).toEqual({ 'X-Trace': 'b', 'X-Other': 'c', 'X-Team': 'user' });
+ });
+
+ it('lets a higher layer add a hidden entry back, as its own definition', () => {
+ const readd = fakeConfig({ endpoints: { custom: [entry('My Endpoint')] } }, 20, [], 'group');
+ const merged = mergeConfigOverrides(base as unknown as AppConfig, [
+ hide('endpoints.custom["My Endpoint"]'),
+ readd,
+ ]);
+ expect(customOf(merged)?.map((item) => item.name)).toEqual([
+ ...awkward.slice(1),
+ 'Ollama',
+ 'My Endpoint',
+ ]);
+ });
+
+ it('applies to the YAML-shaped config each layer is validated on', () => {
+ expect(
+ applyConfigTombstones(base.config, ['endpoints.custom["api.example.com"]']).endpoints?.custom,
+ ).toHaveLength(yaml.length - 1);
+ expect(
+ resolveRawConfig(base.config as Partial<TCustomConfig>, [
+ hide('endpoints.custom["Ollama"]'),
+ ]).endpoints?.custom?.map((item) => item.name),
+ ).toEqual(awkward);
+ });
+
+ it('ignores a keyed tombstone of an array the merge replaces, or a malformed one', () => {
+ const specs = {
+ ...base,
+ modelSpecs: { list: [{ name: 'a', label: 'A', preset: { endpoint: 'openAI' } }] },
+ };
+ const merged = mergeConfigOverrides(specs as unknown as AppConfig, [
+ fakeConfig({}, 10, [
+ 'modelSpecs.list["a"]',
+ 'endpoints.custom["Ollama"',
+ 'endpoints.custom[0]',
+ ]),
+ ]);
+ expect(merged.modelSpecs?.list).toHaveLength(1);
+ expect(customOf(merged)).toHaveLength(yaml.length);
+ });
+
+ it('reads a tombstone holding `["` after anything but an array merged by key as a dotted path', () => {
+ const servers = {
+ 'a["b"]': { type: 'streamable-http', url: 'https://quoted.example.com' },
+ a: { type: 'streamable-http', url: 'https://plain.example.com' },
+ };
+ const mcpBase = { mcpConfig: servers, config: { mcpServers: servers } };
+ const merged = mergeConfigOverrides(mcpBase as unknown as AppConfig, [
+ hide('mcpServers.a["b"]'),
+ ]);
+ expect(Object.keys(merged.mcpConfig ?? {})).toEqual(['a']);
+ const raw = applyConfigTombstones(mcpBase.config as Partial<TCustomConfig>, [
+ 'mcpServers.a["b"]',
+ ]);
+ expect(Object.keys(raw.mcpServers ?? {})).toEqual(['a']);
+ });
+
+ it('tells a path inside an entry that runs into one of its own arrays', () => {
+ expect(isConfigEntryArrayItemPath(['endpoints', 'custom'], ['models', 'default'])).toBe(false);
+ expect(isConfigEntryArrayItemPath(['endpoints', 'custom'], ['models', 'default', '0'])).toBe(
+ true,
+ );
+ expect(isConfigEntryArrayItemPath(['endpoints', 'custom'], ['headers', 'X-Key'])).toBe(false);
+ expect(isConfigArrayItemPath(['endpoints', 'custom', '0', 'headers'])).toBe(true);
+ });
+});
diff --git a/packages/data-schemas/src/app/resolution.ts b/packages/data-schemas/src/app/resolution.ts
index 72e6d5c6f9..c387021b1a 100644
--- a/packages/data-schemas/src/app/resolution.ts
+++ b/packages/data-schemas/src/app/resolution.ts
@@ -7,7 +7,6 @@ import {
RUNTIME_CONFIG_INTERFACE_FIELDS,
PERMISSION_SUB_KEYS,
isProcessMCPServerConfig,
- normalizeEndpointName,
EModelEndpoint,
configSchema,
} from 'librechat-data-provider';
@@ -23,17 +22,30 @@ import type {
AppConfig,
Config,
} from '~/types';
+import type { ConfigEntryRename, ConfigFieldWrite } from './mutations';
+import type { ConfigEntryLocation } from './collections';
import type { AzureResolvedGroupField } from './azure';
-import type { ConfigFieldWrite } from './mutations';
+import {
+ MERGE_KEY_FOLDS,
+ ARRAY_MERGE_KEYS,
+ OVERRIDE_KEY_MAP,
+ remapOverridePath,
+ foldConfigMergeKey,
+ isConfigEntryAt,
+ readConfigEntryTombstone,
+ getConfigEntryIdentity,
+ getConfigArrayMergeKey,
+ getConfigMergeArrayPath,
+} from './collections';
import {
AZURE_RESOLVED_GROUP_FIELDS,
lacksAzureAssistantModels,
narrowAzureServedModels,
resolveAzureGroups,
} from './azure';
+import { setConfigFields, toConfigOverrideState, renameConfigEntriesTombstones } from './mutations';
+import { parseFieldPath, isDotFreePath, isSegmentPrefix, isKeyedConfigPath } from './paths';
import { isBaseConfigPrincipal, sortByConfigPrecedence } from './precedence';
-import { parseFieldPath, isDotFreePath, isSegmentPrefix } from './paths';
-import { setConfigFields, toConfigOverrideState } from './mutations';
import { webSearchPairedFields, unbindWebSearchKeys } from './web';
import logger from '~/config/winston';
@@ -133,29 +145,6 @@ function withoutAzureGroups<T extends AnyObject>(merged: T): T {
return setPath(merged, segments, { ...azure, ...empty }) as T;
}
-/**
- * Paths within the config tree where arrays of objects should be merged by
- * a key field rather than replaced wholesale. `deepMerge` matches items by
- * the given key, deep-merges matching pairs, preserves unmatched base items,
- * and appends new override-only items.
- *
- * Paths use AppConfig key names (post-OVERRIDE_KEY_MAP remapping),
- * not YAML-level key names. E.g. use `interfaceConfig.x`, not `interface.x`.
- */
-const ARRAY_MERGE_KEYS: Record<string, string> = {
- 'endpoints.custom': 'name',
-};
-
-/**
- * How a merge key is folded before items are matched, by `ARRAY_MERGE_KEYS` path: two
- * spellings the runtime serves as one item are one item to the merge too. Custom endpoint
- * names fold through `normalizeEndpointName`, so an override `ollama` lands on the YAML
- * `Ollama` instead of serving beside it with a different baseURL and key.
- */
-const MERGE_KEY_FOLDS: Record<string, (key: string) => string> = {
- 'endpoints.custom': normalizeEndpointName,
-};
-
/**
* Object-valued paths an override replaces whole instead of merging into. A theme
* definition is one coherent value: merging two would keep the base theme's modes,
@@ -163,22 +152,6 @@ const MERGE_KEY_FOLDS: Record<string, (key: string) => string> = {
*/
const ATOMIC_MERGE_PATHS = new Set<string>(['interfaceConfig.theme']);
-/**
- * Maps YAML-level override keys (TCustomConfig) to their AppConfig equivalents.
- * Overrides are stored with YAML keys but merged into the already-processed AppConfig
- * where some fields have been renamed by AppService.
- *
- * When AppService renames a field, add the mapping here. Map entries are
- * type-checked: keys must be valid TCustomConfig fields, values must be
- * valid AppConfig fields. The runtime lookup casts string keys to satisfy
- * strict indexing — unknown keys safely fall through via the ?? fallback.
- */
-const OVERRIDE_KEY_MAP: Partial<Record<keyof TCustomConfig, keyof AppConfig>> = {
- mcpServers: 'mcpConfig',
- interface: 'interfaceConfig',
- turnstile: 'turnstileConfig',
-};
-
/** AppConfig key → the override (YAML) section merged into it, the inverse of `OVERRIDE_KEY_MAP`. */
const OVERRIDE_SECTION_BY_APP_KEY = new Map<string, string>(
Object.entries(OVERRIDE_KEY_MAP).flatMap(([section, appKey]) =>
@@ -218,35 +191,6 @@ function isSafePath(path: string): boolean {
return true;
}
-/**
- * The key field that identifies entries of the merged-by-key array at an override (YAML) path,
- * such as `name` for `endpoints.custom`; `undefined` for any other path.
- */
-export function getConfigArrayMergeKey(segments: readonly string[]): string | undefined {
- const arrayPath = getMergeArrayPath(segments);
- return arrayPath === undefined ? undefined : ARRAY_MERGE_KEYS[arrayPath];
-}
-
-/** The `ARRAY_MERGE_KEYS` path of the merged-by-key array at an override (YAML) path. */
-function getMergeArrayPath(segments: readonly string[]): string | undefined {
- if (segments.length === 0 || segments.some((segment) => segment.includes('.'))) {
- return undefined;
- }
- const appConfigPath = remapOverridePath(segments.join('.'));
- return hasOwn(ARRAY_MERGE_KEYS, appConfigPath) ? appConfigPath : undefined;
-}
-
-/**
- * The identity entry key `key` of the merged-by-key array at an override (YAML) path has: the
- * key as the runtime merge folds it (`foldConfigMergeKey`), so `Ollama` and `ollama` name one
- * custom endpoint to entry changes as they do to the merge. A key at any other path is its own
- * identity.
- */
-export function getConfigEntryIdentity(segments: readonly string[], key: string): string {
- const arrayPath = getMergeArrayPath(segments);
- return arrayPath === undefined ? key : foldConfigMergeKey(arrayPath, key);
-}
-
/**
* `combineFoldedConfigItems` for the merged-by-key array at an override (YAML) path: stored
* items naming one entry in two spellings, combined as the runtime merge combines them.
@@ -255,21 +199,26 @@ export function combineFoldedConfigEntries(
segments: readonly string[],
items: unknown[],
): unknown[] {
- const arrayPath = getMergeArrayPath(segments);
+ const arrayPath = getConfigMergeArrayPath(segments);
return arrayPath === undefined ? items : combineFoldedConfigItems(arrayPath, items);
}
-function remapOverridePath(path: string): string {
- const [first, ...rest] = path.split('.');
- const mappedFirst = OVERRIDE_KEY_MAP[first as keyof typeof OVERRIDE_KEY_MAP] ?? first;
- return [mappedFirst, ...rest].join('.');
-}
-
function isBaseOnlyOverridePath(path: string): boolean {
return BASE_ONLY_OVERRIDE_SECTIONS.has(path.split('.')[0]);
}
+/**
+ * Removes a path from `target`, stopping at arrays. A keyed path (`endpoints.custom["Name"]`)
+ * reaches into an array merged by key instead: it removes every entry whose key has the same
+ * identity (`Ollama` and `ollama` alike), or with a path inside the entry, that path from each
+ * of them. Any other path holding `["` is split on its dots, as before keyed paths existed, so a
+ * stored tombstone of a record key such as an MCP server named `a["b"]` keeps hiding it.
+ */
function deletePath<T extends AnyObject>(target: T, path: string): T {
+ const entry = isKeyedConfigPath(path) ? readConfigEntryTombstone(path) : null;
+ if (entry) {
+ return deleteEntryPath(target, entry);
+ }
if (!isSafePath(path)) {
return target;
}
@@ -293,6 +242,22 @@ function deletePath<T extends AnyObject>(target: T, path: string): T {
return result as T;
}
+function deleteEntryPath<T extends AnyObject>(target: T, location: ConfigEntryLocation): T {
+ const segments = [...location.segments];
+ const items = getPath(target, segments);
+ if (!Array.isArray(items) || !items.some((item) => isConfigEntryAt(location, item))) {
+ return target;
+ }
+ const inside = location.entry.rest.join('.');
+ const next =
+ inside === ''
+ ? items.filter((item) => !isConfigEntryAt(location, item))
+ : items.map((item) =>
+ isConfigEntryAt(location, item) ? deletePath(item as AnyObject, inside) : item,
+ );
+ return setPath(target, segments, next) as T;
+}
+
function deleteConfigPath<T extends AnyObject>(target: T, path: string): T {
const [section, serverName] = path.split('.');
if (section !== 'mcpConfig') {
@@ -319,15 +284,6 @@ function deleteConfigPath<T extends AnyObject>(target: T, path: string): T {
return { ...target, mcpConfig: processServers } as T;
}
-/**
- * Folds a merge key of the merged-by-key array at `arrayPath` into the identity layers match
- * on (`Ollama` and `ollama` are one custom endpoint); other keys come back unchanged. Code that
- * pairs items across writes, such as secret preservation, matches on the same identity.
- */
-export function foldConfigMergeKey(arrayPath: string, key: string): string {
- return hasOwn(MERGE_KEY_FOLDS, arrayPath) ? MERGE_KEY_FOLDS[arrayPath](key) : key;
-}
-
/** The identity an item of the merged-by-key array at `arrayPath` matches on. */
function getMergeKey(item: AnyObject, keyField: string, arrayPath: string): unknown {
const key = item[keyField];
@@ -896,9 +852,13 @@ function isArrayStep(node: SchemaNode, segment: string, depth = 0): boolean {
* define it), and whether the path continues past an array on the way. Below a field of a
* known section that the schema does not define (a key it does not know, or what an
* intersection or `any` holds), the stored value decides the shape, so an index segment there
- * is taken to name an array element.
+ * is taken to name an array element. Only steps from index `from` of `segments` on count toward
+ * `throughArray`, so a path inside an array entry can be judged on the entry's own arrays.
*/
-function resolveConfigSchemaPath(segments: readonly string[]): {
+function resolveConfigSchemaPath(
+ segments: readonly string[],
+ from = 0,
+): {
node?: SchemaNode;
throughArray: boolean;
} {
@@ -909,13 +869,16 @@ function resolveConfigSchemaPath(segments: readonly string[]): {
}
let node: SchemaNode | undefined = shape[section];
let throughArray = false;
- for (const segment of rest) {
+ for (let index = 0; index < rest.length; index++) {
+ const segment = rest[index];
+ /** `from` counts in `segments`, where `rest[index]` is `segments[index + 1]`. */
+ const counts = index + 1 >= from;
if (!node || OPAQUE_SCHEMA_TYPES.has(unwrapSchema(node)._def.typeName ?? '')) {
node = undefined;
- throughArray = throughArray || ARRAY_INDEX.test(segment);
+ throughArray = throughArray || (counts && ARRAY_INDEX.test(segment));
continue;
}
- throughArray = throughArray || isArrayStep(node, segment);
+ throughArray = throughArray || (counts && isArrayStep(node, segment));
node = getChildSchema(node, segment);
}
return { node, throughArray };
@@ -942,6 +905,18 @@ export function isConfigArrayItemPath(segments: readonly string[]): boolean {
return resolveConfigSchemaPath(segments).throughArray;
}
+/**
+ * {@link isConfigArrayItemPath} for a path inside an entry of the merged-by-key array at
+ * `segments`: whether `rest` continues past an array of the entry's own schema (`models.default.0`),
+ * which a keyed tombstone cannot hide part of either.
+ */
+export function isConfigEntryArrayItemPath(
+ segments: readonly string[],
+ rest: readonly string[],
+): boolean {
+ return resolveConfigSchemaPath([...segments, '0', ...rest], segments.length + 1).throughArray;
+}
+
/**
* The combined fixed shape of an intersection of objects (`a.and(b)`), or `undefined` when a
* side is not an object, so nothing is judged on a shape the walk cannot see whole.
@@ -1303,11 +1278,17 @@ export function getConfigChangeIssues(
* field, then reset the old ones). A tombstone a deeper write clears as a side effect does
* not: setting `memory.agent.enabled` under a hidden `memory.agent` brings the inherited agent
* back, and a conflict with the stored fields is reported instead of being dropped at merge.
+ * Nor does a keyed tombstone, which a write never clears by its spelled path
+ * (`getPathClearedTombstones`): a segment `custom["Name"]` is a key of that spelling.
+ *
+ * `renames` are the entry renames the write carries out (a `renames` hint), which move the keyed
+ * tombstones of each old entry key to its new one (`renameConfigEntryTombstones`).
*/
export function getConfigFieldIssues(
fields: Record<string, unknown> | readonly ConfigFieldWrite[],
base: Partial<TCustomConfig> = {},
stored?: { overrides?: unknown; tombstones?: unknown[] } | null,
+ renames: readonly ConfigEntryRename[] = [],
): ConfigOverrideIssue[] {
const writes: readonly ConfigFieldWrite[] = Array.isArray(fields)
? fields
@@ -1320,9 +1301,29 @@ export function getConfigFieldIssues(
if (indexed.length > 0) {
return indexed;
}
- const candidate = setConfigFields(toConfigOverrideState(stored), writes);
- const lifted = written.filter(isDotFreePath).map((segments) => segments.join('.'));
- return getConfigChangeIssues(candidate, base, stored, written, lifted);
+ const candidate = renameConfigEntriesTombstones(
+ setConfigFields(toConfigOverrideState(stored), writes),
+ renames,
+ );
+ return getConfigChangeIssues(
+ candidate,
+ base,
+ stored,
+ written,
+ getLiftedConfigTombstones(written),
+ );
+}
+
+/**
+ * The stored tombstones writes at `written` replace with their own values, as
+ * {@link getConfigFieldIssues} lifts them: each dot-free path, unless its spelling reads as a
+ * keyed tombstone, which a write never clears by its spelled path.
+ */
+export function getLiftedConfigTombstones(written: readonly (readonly string[])[]): string[] {
+ return written.flatMap((segments) => {
+ const path = segments.join('.');
+ return isDotFreePath(segments) && readConfigEntryTombstone(path) == null ? [path] : [];
+ });
}
function omitPath(target: unknown, segments: string[]): unknown {
diff --git a/packages/data-schemas/src/app/store.ts b/packages/data-schemas/src/app/store.ts
index c6711743f5..c2935a48b5 100644
--- a/packages/data-schemas/src/app/store.ts
+++ b/packages/data-schemas/src/app/store.ts
@@ -1,7 +1,7 @@
import { PrincipalType } from 'librechat-data-provider';
import type { PrincipalModel, TCustomConfig } from 'librechat-data-provider';
+import type { ConfigLocation, ConfigPathSegments } from './paths';
import type { ConfigOverrideState } from './mutations';
-import type { ConfigPathSegments } from './paths';
import {
setConfigFields,
unsetConfigPaths,
@@ -15,9 +15,9 @@ import {
sortByConfigPrecedence,
getDefaultConfigPriority,
} from './precedence';
+import { parseFieldPath, parseConfigPath, ConfigPathError } from './paths';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
import { getSafeErrorFields } from '~/utils/errors';
-import { parseFieldPath } from './paths';
import logger from '~/config/winston';
/**
@@ -329,7 +329,8 @@ export interface ConfigLifecycleOptions extends ConfigWriteOptions {
/**
* 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.
+ * contains a dot, or the path's segments, which can. A dotted path may name an entry of an
+ * array merged by key by its key (`endpoints.custom["Name"].headers`, see `parseConfigPath`).
*/
export type ConfigPathInput = string | { segments: ConfigPathSegments };
@@ -377,12 +378,20 @@ function writtenRecord(outcome: ConfigMutationOutcome<never>): ConfigRecord {
return outcome.record;
}
-function toSegments(path: ConfigPathInput): ConfigPathSegments {
- return typeof path === 'string' ? parseFieldPath(path) : path.segments;
+/** A path input as a location; a malformed keyed path throws a `ConfigPathError`. */
+function toLocation(path: ConfigPathInput): ConfigLocation {
+ if (typeof path !== 'string') {
+ return { segments: path.segments };
+ }
+ const location = parseConfigPath(path);
+ if (!location) {
+ throw new ConfigPathError(parseFieldPath(path), 'keyed_path');
+ }
+ return location;
}
-function toPathList(paths: ConfigPathInputs): ConfigPathSegments[] {
- return Array.isArray(paths) ? paths.map(toSegments) : [toSegments(paths as ConfigPathInput)];
+function toPathList(paths: ConfigPathInputs): ConfigLocation[] {
+ return Array.isArray(paths) ? paths.map(toLocation) : [toLocation(paths as ConfigPathInput)];
}
function isPathOrDescendant(path: string, fieldPath: string): boolean {
diff --git a/packages/data-schemas/src/methods/config.spec.ts b/packages/data-schemas/src/methods/config.spec.ts
index 924dceed6f..7885497d97 100644
--- a/packages/data-schemas/src/methods/config.spec.ts
+++ b/packages/data-schemas/src/methods/config.spec.ts
@@ -1014,6 +1014,122 @@ describe('MCP record-key tombstones', () => {
});
});
+describe('keyed tombstones of custom endpoints', () => {
+ const HIDE = 'endpoints.custom["My \\"Gateway\\" v1.2"]';
+ const own = { name: 'gw', baseURL: 'https://gw.example.com', headers: { A: 'a', B: 'b' } };
+
+ async function stored(): Promise<ConfigRecord | null> {
+ return methods.findConfigByPrincipal(PrincipalType.ROLE, 'admin');
+ }
+
+ it('hides an entry on a document with no array, storing the canonical keyed path as is', async () => {
+ const result = await methods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ 'admin',
+ PrincipalModel.ROLE,
+ 'endpoints.custom["My \\u0022Gateway\\u0022 v1.2"]',
+ 10,
+ );
+
+ expect(result.tombstones).toEqual([HIDE]);
+ expect(result.overrides).toEqual({});
+ const raw = await mongoose.models.Config.collection.findOne({ principalId: 'admin' });
+ expect(raw?.tombstones).toEqual([HIDE]);
+ });
+
+ it('removes a path inside an entry an earlier write created, and keeps the rest of it', async () => {
+ await methods.patchConfigFields(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, {
+ 'endpoints.custom': [own],
+ });
+
+ const result = await methods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ 'admin',
+ PrincipalModel.ROLE,
+ 'endpoints.custom["gw"].headers.A',
+ );
+
+ expect(result.overrides).toEqual({
+ endpoints: { custom: [{ ...own, headers: { B: 'b' } }] },
+ });
+ expect(result.tombstones).toEqual(['endpoints.custom["gw"].headers.A']);
+ });
+
+ it('clears the hide of an entry the profile writes again, keeping the tombstones inside it', async () => {
+ await methods.tombstoneConfigField(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, [
+ 'endpoints.custom["gw"]',
+ 'endpoints.custom["gw"].headers.A',
+ 'endpoints.custom["other"]',
+ ]);
+
+ const result = await methods.patchConfigFields(
+ PrincipalType.ROLE,
+ 'admin',
+ PrincipalModel.ROLE,
+ { 'endpoints.custom': [{ name: 'gw', titleModel: 'x' }] },
+ );
+
+ expect(result.tombstones).toEqual([
+ 'endpoints.custom["gw"].headers.A',
+ 'endpoints.custom["other"]',
+ ]);
+ });
+
+ it('unsets an entry by key, and the collection with every keyed tombstone under it', async () => {
+ await methods.patchConfigFields(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, {
+ 'endpoints.custom': [own, { name: 'kept', baseURL: 'https://kept' }],
+ });
+ await methods.tombstoneConfigField(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, [
+ 'endpoints.custom["gw"].headers.A',
+ 'endpoints.custom["yaml"]',
+ 'memory.agent',
+ ]);
+
+ const entry = await methods.unsetConfigField(
+ PrincipalType.ROLE,
+ 'admin',
+ 'endpoints.custom["gw"]',
+ );
+ expect(entry!.overrides).toEqual({
+ endpoints: { custom: [{ name: 'kept', baseURL: 'https://kept' }] },
+ });
+ expect(entry!.tombstones).toEqual(['endpoints.custom["yaml"]', 'memory.agent']);
+
+ const collection = await methods.unsetConfigField(
+ PrincipalType.ROLE,
+ 'admin',
+ 'endpoints.custom',
+ );
+ expect(collection!.overrides).toEqual({});
+ expect(collection!.tombstones).toEqual(['memory.agent']);
+ });
+
+ it('counts a document holding only keyed tombstones as not empty', async () => {
+ await methods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ 'admin',
+ PrincipalModel.ROLE,
+ 'endpoints.custom["gw"]',
+ );
+
+ const deleted = await methods.deleteConfig(PrincipalType.ROLE, 'admin', undefined, {
+ expectEmpty: true,
+ });
+
+ expect(deleted).toBeNull();
+ expect((await stored())?.tombstones).toEqual(['endpoints.custom["gw"]']);
+ });
+
+ it('refuses a malformed keyed path, or one after an array not merged by key', async () => {
+ for (const path of ['endpoints.custom["gw"', 'modelSpecs.list["a"]']) {
+ await expect(
+ methods.tombstoneConfigField(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, path),
+ ).rejects.toMatchObject({ code: 'CONFIG_PATH_INVALID', reason: 'keyed_path' });
+ }
+ expect(await stored()).toBeNull();
+ });
+});
+
describe('deleteConfig', () => {
it('deletes and returns the config', async () => {
await methods.upsertConfig(PrincipalType.ROLE, 'admin', PrincipalModel.ROLE, {}, 10);
diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.ts
index fa6dd0c0e8..3980398006 100644
--- a/packages/data-schemas/src/types/admin.ts
+++ b/packages/data-schemas/src/types/admin.ts
@@ -55,6 +55,16 @@ export type AdminConfigLocation = {
segments: string[];
};
+/**
+ * A location a write applied at. A keyed `fieldPath` (`keyedTombstones`) is named as sent in
+ * `path`, by its collection in `segments`, and by the entry `key` and, for a path inside the
+ * entry, `entryPath`, as a change ref names it.
+ */
+export type AdminConfigAppliedLocation = AdminConfigLocation & {
+ key?: string;
+ entryPath?: string[];
+};
+
/**
* What a write did with each location it addressed (`writeReport`): stored or removed
* (`applied`), or left alone because the generic config API never stores it there (`skipped`,
@@ -62,7 +72,7 @@ export type AdminConfigLocation = {
* rest of the value is stored.
*/
export type AdminConfigWriteReport = {
- applied: AdminConfigLocation[];
+ applied: AdminConfigAppliedLocation[];
skipped: Array<AdminConfigLocation & { reason: AdminConfigSkipReason }>;
};
@@ -263,7 +273,10 @@ export type AdminConfigReloadErrorResponse = {
* `$` 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.
+ * `segments` as a JSON-encoded array in the query string. A segment is a key as written: one such
+ * as `custom["Name"]` never names an entry by key (only a keyed `fieldPath` does), so a write by it
+ * clears none of that entry's tombstones, and a tombstone refuses it (`keyed_path`), since its
+ * stored dotted form would read as one.
*/
export type AdminConfigFieldTarget =
| { fieldPath: string; segments?: never }
@@ -300,7 +313,10 @@ export type AdminConfigTombstoneRequest = AdminConfigWritePrecondition &
* - `tombstone` removes the override and hides inherited values at the path. Tombstones are
* stored as dotted paths, so no segment may contain a dot, and hide whole arrays only: a path
* to an element or inside one is refused, and so is an index segment below a field
- * `configSchema` does not define, which may name an array element.
+ * `configSchema` does not define, which may name an array element. An entry of an array merged
+ * by key is hidden by its key instead: `fieldPath: 'endpoints.custom["Name"]'`, or a path
+ * inside it (`'endpoints.custom["Name"].headers.X-Key'`), which `unset` resets the same way
+ * (`keyedTombstones`).
*
* Only sections `configSchema` defines can be written or hidden; `unset` may also remove what
* an older server stored outside them. Entries of a merged-by-key array are addressed by key,
@@ -420,9 +436,12 @@ export type AdminConfigChangeRef = {
/** Index of the change in the request's `ops`. */
opIndex: number;
op: AdminConfigChangeOp['op'];
+ /** The path, or for an entry change or a keyed `unset`/`tombstone`, the collection. */
segments: string[];
- /** The entry key of an `upsertEntry` or `removeEntry`. */
+ /** The entry key of an `upsertEntry` or `removeEntry`, or of a keyed `unset` or `tombstone`. */
key?: string;
+ /** For a keyed `unset` or `tombstone` of a path inside an entry, that path within the entry. */
+ entryPath?: string[];
};
/** 200 from `POST …/changes`. */
@@ -934,6 +953,43 @@ export type AdminConfigEnvStatusResponse = {
* `POST /reload`) stays open to an admin who has not accepted the terms of service
* (`interface.termsOfService.modalAcceptance`), so they can turn the setting off. Every other
* route, admin routes that start work included, still answers 403 `terms_not_accepted`.
+ * - `keyedTombstones`: POST `/fields/tombstone`, DELETE `/fields` and the `tombstone` and `unset`
+ * ops of `/changes` take a keyed `fieldPath`, `<collection>["<key>"]` or
+ * `<collection>["<key>"].<path>`, for an array merged by key (`rules.arrayMergeKeys`, such as
+ * `endpoints.custom`): the key is a JSON string (up to `limits.maxEntryKeyLength` characters,
+ * not starting with `$` or `__`, not `constructor` or `prototype`), compared as the merge folds
+ * it (`ollama` names `Ollama`). A tombstone hides the inherited entry
+ * (`endpoints.custom["Name"]`), or a path inside it (`endpoints.custom["Name"].headers.X-Key`),
+ * for the profile's principals, and removes the profile's own entry or path. An unset removes
+ * the profile's own entry or path and the keyed tombstones of that entry at or below it; an
+ * unset of the collection or an ancestor removes every keyed tombstone under it. Writing an
+ * entry (`upsertEntry`, or a PATCH or `set` of the collection or an ancestor; not PUT, which
+ * keeps tombstones) clears the tombstone that hides it whole, and tombstones inside it stay.
+ * A hidden custom endpoint, whether librechat.yaml or a lower profile (such as `__base__`)
+ * defines it, also hides the model specs that select it and its name in
+ * `modelSpecs.addedEndpoints` and `endpoints.agents.allowedProviders`, unless a later layer
+ * adds the endpoint back; other added endpoints stay when no spec is left, and an allow-list
+ * that names only hidden endpoints stays whole. Refused with 400 `CONFIG_PATH_INVALID`: a
+ * malformed keyed path, or one after an array not merged by key, and a keyed path in a write
+ * (PATCH, `set`, or an entry op's collection), reason `keyed_path`; the entry's key field,
+ * `merge_key`; a tombstone into an array of the entry, `inside_array`. The entry's registered
+ * secret, its preview and its destination fingerprint answer 400 `SECRET_PATH`. POST
+ * `/fields/tombstone` also refuses a path into an array by position (`endpoints.custom.0`,
+ * `inside_array`), which the merge never applied. A change ref names a keyed change by its
+ * collection (`segments`), `key` and, inside the entry, `entryPath`, and the write report of
+ * POST `/fields/tombstone` and DELETE `/fields` names a keyed location the same way, with the
+ * keyed path in `path` (`AdminConfigAppliedLocation`).
+ * - `renameHints`: the `renames` hint of PUT and PATCH also takes
+ * `{ path: 'endpoints.custom', previousName, name }` (`rules.renameHintPaths`): the written
+ * entry `name` that omits `apiKey` gets the key the principal stores on entry `previousName`
+ * (ciphertext and preview), and the keyed tombstones of `previousName` move to `name`. The
+ * carried key stays bound to its destination: a renamed entry that sends it elsewhere answers
+ * 400 `CONFIG_SECRET_REENTRY_REQUIRED`. A hint that cannot apply answers 400
+ * `CONFIG_RENAME_INVALID` with `reason`: `inherited_entry` (either name is a librechat.yaml
+ * entry), `source_not_found`, `target_exists` (the principal already stores `name`),
+ * `target_not_written`, `source_still_written` (the write keeps `previousName`; swap names with
+ * `/changes` `rename` ops), `duplicate_source` (two hints rename one entry), `duplicate_target`
+ * or `invalid_name`. A `/changes` `rename` of a custom endpoint moves its keyed tombstones too.
*/
export type AdminConfigFeatureFlag =
| 'dottedKeys'
@@ -961,7 +1017,9 @@ export type AdminConfigFeatureFlag =
| 'reloadRoute'
| 'writeReport'
| 'issueParams'
- | 'adminTermsExempt';
+ | 'adminTermsExempt'
+ | 'keyedTombstones'
+ | 'renameHints';
export type AdminConfigFeatures = Record<AdminConfigFeatureFlag, boolean>;
@@ -1005,6 +1063,8 @@ export type AdminConfigMergeRules = {
export type AdminConfigRules = AdminConfigMergeRules & {
/** Top-level sections `configSchema` defines; enforced on writes when `sectionAllowlist`. */
acceptedSections: string[];
+ /** The `path` values a `renames` hint takes (`recordSecrets`, `renameHints`). */
+ renameHintPaths: string[];
/** Sections only `librechat.yaml` sets; writes to them are dropped. */
baseOnlySections: string[];
/** Sections only the base (`__base__`) document may hold, through their dedicated APIs. */
@@ -1053,6 +1113,8 @@ export type AdminConfigMeta = {
maxPatchEntries: number;
/** Most ops one `POST /changes` accepts. */
maxChangeOps: number;
+ /** Longest entry key a keyed path (`keyedTombstones`) or an entry rename hint can name. */
+ maxEntryKeyLength: number;
/**
* The app config service's `overrideCacheTtl`: how long another server instance may serve
* resolved config from before a write.