Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import {
BASE_PRINCIPAL_CONFIG_SECTIONS,
BASE_ONLY_CONFIG_SECTIONS,
DERIVED_CONFIG_PATHS,
configSchema,
PrincipalType,
PrincipalModel,
INTERFACE_PERMISSION_FIELDS,
RUNTIME_CONFIG_INTERFACE_FIELDS,
PERMISSION_SUB_KEYS,
hasProcessMCPServerConfig,
isProcessMCPServerConfig,
isProcessMCPServerField,
EModelEndpoint,
} from 'librechat-data-provider';
import {
logger,
getAtPath,
unsetAtPath,
isPlainRecord,
isDotFreePath,
isSegmentPrefix,
parseFieldPath,
setConfigFields,
applyConfigChange,
getConfigEntryKey,
getConfigEntryMatcher,
getConfigEntryIdentity,
unsetConfigPaths,
getConfigRevision,
isConfigEntryError,
isConfigRecordPath,
pruneEmptyAncestors,
isConfigArrayItemPath,
isAcceptedOverrideSection,
MAX_CONFIG_CHANGE_OPS,
MAX_CONFIG_ENTRY_KEY_LENGTH,
getConfigChangeIssues,
getConfigArrayMergeKey,
getIndexedMergeKeyIssues,
getLiftedConfigTombstones,
getConfigBatchWrittenPaths,
isSameConfigValue,
isConfigRevision,
isConfigPathError,
resolveRawConfig,
isFieldNameRejection,
getDottedSectionIssues,
runConfigMutation,
getConfigFieldIssues,
toConfigOverrideState,
tombstoneConfigPaths,
applyConfigTombstones,
isBaseConfigPrincipal,
ABSENT_CONFIG_REVISION,
replaceConfigOverrides,
parseConfigPathSegments,
getConfigOverrideIssues,
getIgnoredConfigOverrides,
YAML_HELD_PATHS,
getExpectedRevision,
MAX_CONFIG_PATH_DEPTH,
getDefaultConfigPriority,
BASE_CONFIG_PRINCIPAL_ID,
isConfigRevisionConflict,
ConfigRevisionConflictError,
isConfigOverrideStateEmpty,
isVertexConfigured,
toConfigDraft,
toConfigIdentityPath,
renameConfigIdentityPath,
resolveConfigIdentityPath,
parseConfigPath,
formatKeyedPath,
isConfigEntryKey,
isKeyedConfigPath,
isConfigEntryArrayItemPath,
renameConfigEntriesTombstones,
} from '@librechat/data-schemas';
import type {
AppConfig,
ConfigDraft,
ConfigChange,
ConfigRecord,
ConfigSection,
ConfigWriteOutcome,
ConfigRevision,
ConfigFieldWrite,
SystemCapability,
ConfigPathError,
ConfigPathInputs,
ConfigOverrideIssue,
ConfigPathErrorReason,
ConfigOverrideState,
ConfigOverrideLayer,
ConfigEntryError,
AdminConfigChangeOp,
AdminConfigChangeRef,
AdminConfigSkipReason,
AdminConfigIgnoreReason,
AdminConfigIgnoredSecret,
AdminConfigAppliedLocation,
AdminConfigLocation,
AdminConfigWriteReport,
AdminConfigErrorCode,
AdminConfigIgnoredOverride,
AdminConfigInvalidResponse,
AdminConfigChangesResponse,
AdminConfigChangeErrorResponse,
AdminConfigReloadResponse,
AdminConfigReloadErrorResponse,
ConfigMutationOutcome,
ConfigMutationPlan,
ConfigIdentityStep,
ConfigDerivation,
ConfigEntryStep,
ConfigLocation,
ConfigEntryRename,
YamlHeldPath,
} from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
import type { Response } from 'express';
import type { CapabilityUser } from '~/middleware/capabilities';
import type { ConfigReloadReport } from '~/app/invalidation';
import type { EnvReferencePolicy } from '~/app/allowlist';
import type { ConfigSecretRename } from './secrets';
import type { SecretReentryIssue } from './binding';
import type { ServerRequest } from '~/types/http';
import type { RecordAuditEntry } from './audit';
import type { SecretReentry } from './reentry';
import {
RENAME_HINT_PATHS,
getArraySecretKey,
encryptConfigSecretFields,
encryptConfigSecrets,
carryRenamedConfigSecrets,
getEnteredConfigSecrets,
getConfigSecretMutationPaths,
getConfigSecretInputError,
getConfigSecretSections,
isConfigSecretAncestorPath,
isConfigSecretDescendantPath,
isConfigSecretKeyRename,
isConfigSecretPreservablePatch,
isConfigSecretRelatedSegments,
preserveConfigSecrets,
redactConfigSecrets,
redactResolvedConfigSecrets,
} from './secrets';
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,
getBoundKeyReentryIssues,
getAzureGroupReentryIssues,
} from './reentry';
import {
entersBoundSecret,
bindSecretDestinations,
isWebSearchBindingPath,
getWebSearchReentryIssues,
} from './binding';
import { getConfigPartition, getActivePartition, runInPartition } from './partition';
import { buildAdminConfigMeta, getCatalogModelsTtlMs } from './meta';
import { createAdminAuditEmitter, configTarget } from './audit';
import { DEFAULT_OVERRIDE_CACHE_TTL } from '~/app/service';
import { getSafeErrorMetadata } from '~/utils/errors';
import { mergeOverrideLayers } from '~/app/overrides';
import { expandCustomEndpoint } from '~/app/params';
const UNSAFE_SEGMENTS = /(?:^|\.)(__[\w]*|constructor|prototype)(?:\.|$)/;
const MAX_PATCH_ENTRIES = 100;
/** The audit target of a reload: the file every instance loads again. */
const CONFIG_FILE_TARGET = 'librechat.yaml';
const RELOAD_AUDIT_TARGET = { type: 'config', id: CONFIG_FILE_TARGET, name: CONFIG_FILE_TARGET };
const BASE_ONLY_OVERRIDE_SECTIONS = new Set<string>(BASE_ONLY_CONFIG_SECTIONS);
const BASE_PRINCIPAL_OVERRIDE_SECTIONS = new Set<string>(BASE_PRINCIPAL_CONFIG_SECTIONS);
const PROCESS_MCP_CONFIG_ERROR =
'Process-backed MCP servers can only be configured in librechat.yaml';
const LANGFUSE_HEADERS_CONFIG_ERROR =
'Langfuse request headers can only be configured in librechat.yaml';
/**
* Langfuse export headers carry proxy/gateway credentials, but they are a map
* of values rather than one scalar path, so the config secret registry cannot
* encrypt them at rest or mask them on read. Keeping them out of stored
* overrides is what makes them deployment-level: an admin-written map would sit
* in Mongo in plaintext and come back in plaintext, unlike `langfuse.secretKey`.
*/
function isLangfuseHeadersFieldPath(fieldPath: string): boolean {
return fieldPath === 'langfuse.headers' || fieldPath.startsWith('langfuse.headers.');
}
/**
* Whether an overrides payload carries Langfuse headers under any spelling.
*
* `overrides` is a Mixed document written wholesale, so a dotted property name
* survives verbatim: `{ langfuse: { "headers.X-Token": "..." } }` and
* `{ "langfuse.headers": {...} }` both persist a credential that the nested-map
* redactor never walks, and a later read returns it unchanged.
*/
function hasLangfuseHeadersOverride(rawOverrides: Record<string, unknown>): boolean {
for (const key of Object.keys(rawOverrides)) {
if (key === 'langfuse.headers' || key.startsWith('langfuse.headers.')) {
return true;
}
}
const rawLangfuse = rawOverrides.langfuse;
if (rawLangfuse == null || typeof rawLangfuse !== 'object' || Array.isArray(rawLangfuse)) {
return false;
}
return Object.keys(rawLangfuse).some((key) => key === 'headers' || key.startsWith('headers.'));
}
export function isValidFieldPath(path: string): boolean {
return (
typeof path === 'string' &&
path.length > 0 &&
!path.startsWith('.') &&
!path.endsWith('.') &&
!path.includes('..') &&
!path.includes('$') &&
!UNSAFE_SEGMENTS.test(path)
);
}
export function getTopLevelSection(fieldPath: string): string {
return fieldPath.split('.')[0];
}
function isProcessMCPServerFieldPath(fieldPath: string, value: unknown): boolean {
const [section, _serverName, field] = fieldPath.split('.');
if (section !== 'mcpServers') {
return false;
}
if (field == null) {
return fieldPath === section
? hasProcessMCPServerConfig(value)
: isProcessMCPServerConfig(value);
}
return isProcessMCPServerField(field) || (field === 'type' && value === 'stdio');
}
/** Sections whose guards read dotted paths, so a segment that contains a dot is refused there. */
const DOT_FREE_SECTIONS = new Set(['mcpServers', 'mcpConfig', 'langfuse']);
/**
* Where a field write, removal or tombstone lands. `fieldPath` is the dotted spelling that the
* section, permission and secret guards read; it names exactly `segments` when `dotFree`. 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. 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)}` };
}
const parsed = parseFieldPath(fieldPath);
if (parsed.length > MAX_CONFIG_PATH_DEPTH) {
return { ok: false, error: 'Field path is too deep', reason: 'too_deep' };
}
return { ok: true, target: { segments: parsed, fieldPath, dotFree: true } };
}
if (fieldPath !== undefined) {
return { ok: false, error: 'Provide either fieldPath or segments, not both' };
}
const parsed = parseConfigPathSegments(segments);
if (!parsed.ok) {
return { ok: false, error: 'Invalid or unsafe field path segments', reason: parsed.reason };
}
const target: FieldTarget = {
segments: parsed.segments,
fieldPath: parsed.segments.join('.'),
dotFree: isDotFreePath(parsed.segments),
};
const [section] = target.segments;
if (
!target.dotFree &&
(section.includes('.') ||
DOT_FREE_SECTIONS.has(section) ||
isConfigSecretRelatedSegments(target.segments))
) {
return {
ok: false,
error: 'This path cannot address a key that contains a dot',
reason: 'dotted_segment',
};
}
return { ok: true, target };
}
function fieldTargetErrorResponse(
res: Response,
failure: { error: string; reason?: ConfigPathErrorReason },
): Response {
const { error, reason } = failure;
return reason
? errorResponse(res, 400, 'CONFIG_PATH_INVALID', error, { reason })
: errorResponse(res, 400, 'INVALID_FIELD_PATH', error);
}
/** How a target is named in audit metadata: its dotted path, or its segments when lossy. */
function describeFieldTarget(target: FieldTarget): string {
return target.dotFree ? target.fieldPath : JSON.stringify(target.segments);
}
/** `segments` in a query string is a JSON-encoded array; anything else is passed on to fail. */
function readSegmentsQuery(value: unknown): unknown {
if (typeof value !== 'string') {
return value;
}
try {
return JSON.parse(value);
} catch {
return value;
}
}
/**
* The field writes in request order: each dot-free entry as encryption and secret
* preservation left it (one they dropped is skipped), right after it the preview companion
* the secret pipeline wrote for it, each dotted entry as sent, then any other field the
* pipeline added. A preview travels with its secret, so a later write of an ancestor that
* puts the stored secret back replaces both, and no preview ever describes another key.
*/
function toOrderedWrites(
entries: ReadonlyArray<{ target: FieldTarget; value: unknown }>,
fields: Record<string, unknown>,
): ConfigFieldWrite[] {
const pending = new Map(Object.entries(fields));
const writes: ConfigFieldWrite[] = [];
for (const { target, value } of entries) {
if (!target.dotFree) {
writes.push({ segments: target.segments, value });
continue;
}
if (!pending.has(target.fieldPath)) {
continue;
}
for (const fieldPath of getConfigSecretMutationPaths(target.fieldPath)) {
if (pending.has(fieldPath)) {
writes.push({ segments: parseFieldPath(fieldPath), value: pending.get(fieldPath) });
pending.delete(fieldPath);
}
}
}
for (const [fieldPath, value] of pending) {
writes.push({ segments: parseFieldPath(fieldPath), value });
}
return writes;
}
/** One step of a field patch: a write, or the reset of a path (a secret with its preview). */
type PatchStep = { write: ConfigFieldWrite } | { reset: ConfigLocation[] };
/**
* A field patch's steps in request order: each entry's writes as {@link toOrderedWrites} orders
* them, and in its place each entry whose whole value was cut out, as the reset of its path.
*/
function toOrderedSteps(
entries: ReadonlyArray<{ target: FieldTarget; value: unknown; reset: boolean }>,
fields: Record<string, unknown>,
): PatchStep[] {
const steps: PatchStep[] = [];
let run: Array<{ target: FieldTarget; value: unknown }> = [];
const pending = { ...fields };
const flush = () => {
const runFields: Record<string, unknown> = {};
for (const { target } of run) {
for (const fieldPath of target.dotFree
? getConfigSecretMutationPaths(target.fieldPath)
: []) {
if (Object.prototype.hasOwnProperty.call(pending, fieldPath)) {
runFields[fieldPath] = pending[fieldPath];
delete pending[fieldPath];
}
}
}
steps.push(...toOrderedWrites(run, runFields).map((write) => ({ write })));
run = [];
};
for (const entry of entries) {
if (!entry.reset) {
run.push(entry);
continue;
}
flush();
steps.push({ reset: getRemovalPaths(entry.target) });
}
flush();
steps.push(...toOrderedWrites([], pending).map((write) => ({ write })));
return steps;
}
function toStepWrites(steps: readonly PatchStep[]): ConfigFieldWrite[] {
return steps.flatMap((step) => ('write' in step ? [step.write] : []));
}
/**
* Validation of a patch with resets, as `getConfigFieldIssues` judges writes alone: the end
* state the steps leave, with 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[],
derivation: ConfigDerivation,
): ConfigOverrideIssue[] {
const written = steps.flatMap((step) =>
'write' in step ? [[...step.write.segments]] : step.reset.map(({ segments }) => [...segments]),
);
const indexed = getIndexedMergeKeyIssues(written);
if (indexed.length > 0) {
return indexed;
}
const lifted = getLiftedConfigTombstones(toStepWrites(steps).map(({ segments }) => segments));
const candidate = renameConfigEntriesTombstones(
applyPatchSteps(toConfigOverrideState(stored), steps),
renames,
);
return getConfigChangeIssues(candidate, floor, stored, written, lifted, derivation);
}
/** Applies a patch's steps in order to the stored document's state. */
function applyPatchSteps(state: ConfigOverrideState, steps: readonly PatchStep[]) {
return steps.reduce(
(current, step) =>
'write' in step
? setConfigFields(current, [step.write])
: unsetConfigPaths(current, step.reset),
state,
);
}
/**
* Returns true if `fieldPath` targets an interface permission field or permission sub-key.
*
* - `"interface.prompts"` → true (boolean permission field)
* - `"interface.agents.use"` → true (permission sub-key)
* - `"interface.mcpServers"` → true (entire composite field)
* - `"interface.mcpServers.use"` → true (permission sub-key)
* - `"interface.mcpServers.placeholder"` → false (UI-only sub-key)
* - `"interface.peoplePicker.users"` → true (all peoplePicker sub-keys are permissions)
* - `"interface.modelSelect"` → false (UI-only field)
*/
function isInterfacePermissionPath(fieldPath: string): boolean {
const parts = fieldPath.split('.');
if (parts[0] !== 'interface' || parts.length < 2) {
return false;
}
if (!INTERFACE_PERMISSION_FIELDS.has(parts[1])) {
return false;
}
// "interface.<permField>" with no sub-key → permission (blocks the whole field),
// EXCEPT dual-purpose runtime fields (e.g. schedules) whose bare top-level value
// is a runtime enable toggle, not a permission — those must pass through so admin
// field patches/tombstones can set or clear them (their .use/.create permission
// sub-keys are still blocked below).
if (parts.length === 2) {
return !RUNTIME_CONFIG_INTERFACE_FIELDS.has(parts[1]);
}
// "interface.<permField>.<subKey>" → only block if sub-key is a permission bit
return PERMISSION_SUB_KEYS.has(parts[2]);
}
/**
* Collapses an explicit disable on a dual-purpose runtime interface field (e.g. `schedules`)
* to its boolean form.
*
* For these fields `use` is BOTH a permission bit — stripped from DB overrides — and the
* runtime disable signal. Stripping it alone would leave `{ maxPerUser: 2 }`, which
* `getLimits` reads as ENABLED because an object opts in unless it sets `use: false`. An
* override written to stop scheduled billing for a principal would therefore start it.
* Other object forms are left alone so a principal can still narrow limits.
*/
function normalizeRuntimeInterfaceValue(field: string, value: unknown): unknown {
if (!RUNTIME_CONFIG_INTERFACE_FIELDS.has(field)) {
return value;
}
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
return value;
}
return (value as Record<string, unknown>).use === false ? false : value;
}
/** Applies {@link normalizeRuntimeInterfaceValue} to a bare `interface.<field>` patch. */
function normalizeInterfaceFieldPatch(fieldPath: string, value: unknown): unknown {
const parts = fieldPath.split('.');
if (parts[0] !== 'interface' || parts.length !== 2) {
return value;
}
return normalizeRuntimeInterfaceValue(parts[1], value);
}
/** Sets a key as data, so a submitted `__proto__` key never becomes a prototype. */
function defineKey(target: Record<string, unknown>, key: string, value: unknown): void {
Object.defineProperty(target, key, {
value,
enumerable: true,
writable: true,
configurable: true,
});
}
/**
* Drops the role-permission fields from a whole `interface` override: a composite permission
* field keeps its UI-only sub-keys, a runtime field keeps its boolean form, and runtime disables
* are normalized. Returns what is left (`undefined` when nothing is) and the dropped paths
* relative to `interface`.
*/
function filterInterfaceOverride(iface: Record<string, unknown>): {
value?: Record<string, unknown>;
stripped: string[][];
} {
const value: Record<string, unknown> = {};
const stripped: string[][] = [];
for (const [field, rawValue] of Object.entries(iface)) {
const fieldValue = normalizeRuntimeInterfaceValue(field, rawValue);
if (!INTERFACE_PERMISSION_FIELDS.has(field)) {
defineKey(value, field, fieldValue);
continue;
}
if (isPlainRecord(fieldValue)) {
const uiOnly: Record<string, unknown> = {};
for (const [sub, subValue] of Object.entries(fieldValue)) {
if (PERMISSION_SUB_KEYS.has(sub)) {
stripped.push([field, sub]);
} else {
defineKey(uiOnly, sub, subValue);
}
}
if (Object.keys(uiOnly).length > 0) {
defineKey(value, field, uiOnly);
}
continue;
}
if (RUNTIME_CONFIG_INTERFACE_FIELDS.has(field)) {
defineKey(value, field, fieldValue);
continue;
}
stripped.push([field]);
}
return { value: Object.keys(value).length > 0 ? value : undefined, stripped };
}
/** A failure a field guard answers with 400: a message and a stable code. */
interface FieldGuardError {
error: string;
code: 'PROCESS_MCP_CONFIG' | 'LANGFUSE_HEADERS_CONFIG' | 'SECRET_PATH';
}
/** Why a field write at `fieldPath` is refused outright, checked before anything is read. */
function getFieldWriteError(fieldPath: string, value: unknown): FieldGuardError | null {
if (isProcessMCPServerFieldPath(fieldPath, value)) {
return { error: PROCESS_MCP_CONFIG_ERROR, code: 'PROCESS_MCP_CONFIG' };
}
if (isLangfuseHeadersFieldPath(fieldPath)) {
return { error: LANGFUSE_HEADERS_CONFIG_ERROR, code: 'LANGFUSE_HEADERS_CONFIG' };
}
if (isConfigSecretDescendantPath(fieldPath)) {
return {
error: `Cannot patch inside protected secret path: ${fieldPath}`,
code: 'SECRET_PATH',
};
}
const secretInputError = getConfigSecretInputError(fieldPath, value);
if (secretInputError) {
return { error: secretInputError, code: 'SECRET_PATH' };
}
if (Array.isArray(value) && isConfigSecretAncestorPath(fieldPath)) {
return {
error: `Cannot patch protected secret ancestor as an array: ${fieldPath}`,
code: 'SECRET_PATH',
};
}
return null;
}
/** Why a removal or tombstone at `fieldPath` is refused outright. */
function getFieldRemovalError(fieldPath: string): FieldGuardError | null {
const secretInputError = getConfigSecretInputError(fieldPath, undefined);
return secretInputError ? { error: secretInputError, code: 'SECRET_PATH' } : null;
}
/**
* Why the generic config API leaves a path alone instead of changing it: a section only
* librechat.yaml configures, a section with its own admin API, or an interface permission. The
* request still succeeds (owner decision: skip and report, never 400).
*/
function getFieldSkipReason(fieldPath: string): AdminConfigSkipReason | null {
const section = getTopLevelSection(fieldPath);
if (BASE_ONLY_OVERRIDE_SECTIONS.has(section)) {
return 'base_only_section';
}
if (BASE_PRINCIPAL_OVERRIDE_SECTIONS.has(section)) {
return 'dedicated_section';
}
return isInterfacePermissionPath(fieldPath) ? 'interface_permission' : null;
}
const SKIP_DESCRIPTIONS: Readonly<Record<AdminConfigSkipReason, string>> = {
base_only_section: 'base-only config field %s - configure it in librechat.yaml instead',
base_only_path: 'base-only config path %s - configure it in librechat.yaml instead',
deployment_only_path: 'deployment-only config path %s - configure it in librechat.yaml instead',
dedicated_section: 'dedicated tenant-wide config field %s in the generic config API',
interface_permission: 'interface permission field %s — use role permissions instead',
process_mcp_server: 'override of process-backed MCP server %s - configure it in librechat.yaml',
derived_path:
'derived config path %s - the server derives it from the field it resolves, write that instead',
};
/** Logs a skipped path; `action` is how the route words it (`Stripping`, `Ignoring tombstone for`). */
function logSkippedField(action: string, fieldPath: string, reason: AdminConfigSkipReason): void {
logger.warn(
`[adminConfig] ${action} ${SKIP_DESCRIPTIONS[reason].replace('%s', JSON.stringify(fieldPath))}`,
);
}
/** A field the generic config API never stores a value at, and why. */
interface HeldPath {
segments: readonly string[];
reason: YamlHeldPath['reason'] | 'derived_path';
}
/** Fields the server derives from another one (`rules.derivedPaths`), which the merge never applies. */
const DERIVED_HELD_PATHS: readonly HeldPath[] = DERIVED_CONFIG_PATHS.map((path) => ({
segments: path.split('.'),
reason: 'derived_path',
}));
let writeHeldPaths: readonly HeldPath[] | undefined;
/**
* Fields only librechat.yaml sets (`YAML_HELD_PATHS`) and derived fields: no write stores them.
* Built on first use rather than at import, as the other readers of `YAML_HELD_PATHS` do.
*/
function getWriteHeldPaths(): readonly HeldPath[] {
writeHeldPaths ??= [...YAML_HELD_PATHS, ...DERIVED_HELD_PATHS];
return writeHeldPaths;
}
/**
* Why a write or tombstone at `segments` is skipped because the path is, or lies inside, a field
* only librechat.yaml sets or one the server derives. Removing a stored value there is cleanup
* and is never skipped.
*/
function getHeldPathSkipReason(segments: readonly string[]): HeldPath['reason'] | null {
return (
getWriteHeldPaths().find((held) => isSegmentPrefix(held.segments, segments))?.reason ?? null
);
}
/** A part of a written value the API does not store, at its full location. */
interface SkippedPart {
segments: string[];
reason: AdminConfigSkipReason;
}
/**
* Removes the fields only librechat.yaml sets, and the derived ones, below `segments` from a value
* written there (`endpoints.agents` carrying `pullRequests.provider` or `eventDriven`,
* `endpoints.anthropic` carrying `vertexConfig`), with the objects that leaves empty. Returns the
* value to store and the parts it removed.
*/
function stripHeldPaths(
segments: readonly string[],
value: unknown,
): { value: unknown; stripped: SkippedPart[] } {
let result = value;
const stripped: SkippedPart[] = [];
for (const { segments: path, reason } of getWriteHeldPaths()) {
if (path.length <= segments.length || !isSegmentPrefix(segments, path)) {
continue;
}
const relative = path.slice(segments.length);
if (!isPlainRecord(result) || getAtPath(result, relative) === undefined) {
continue;
}
result = pruneEmptyAncestors(unsetAtPath(result, relative), relative);
stripped.push({ segments: [...path], reason });
}
return { value: result, stripped };
}
const PROCESS_MCP_SERVER_OVERRIDE_ERROR =
'An MCP server librechat.yaml runs as a local process can only be configured in librechat.yaml';
/** The MCP servers librechat.yaml (`base`) runs as local processes, by name. */
function getProcessServerNames(base: Partial<TCustomConfig>): Set<string> {
const servers = (base as { mcpServers?: unknown }).mcpServers;
if (!isPlainRecord(servers)) {
return new Set();
}
return new Set(
Object.entries(servers)
.filter(([, serverConfig]) => isProcessMCPServerConfig(serverConfig))
.map(([name]) => name),
);
}
/**
* Whether `segments` names an MCP server librechat.yaml runs as a local process, or a path inside
* one. The merge never applies an override or tombstone there (the process is shared by every
* user), so a write or tombstone there is refused rather than stored with no effect.
*/
function isProcessServerPath(segments: readonly string[], processServers: ReadonlySet<string>) {
return segments.length >= 2 && segments[0] === 'mcpServers' && processServers.has(segments[1]);
}
/** What a written value stores once the parts the API does not store are cut out. */
interface FilteredValue {
value: unknown;
skipped: SkippedPart[];
/** Something was cut out and nothing of the value is left: the write resets its path. */
emptied: boolean;
}
function isEmptied(value: unknown): boolean {
return value === undefined || (isPlainRecord(value) && Object.keys(value).length === 0);
}
/**
* Removes the servers librechat.yaml runs as local processes from a whole `mcpServers` value
* (any other value is returned as is), so a client that writes back the section it read, stored
* no-ops included, still succeeds. Applied once librechat.yaml is loaded, after
* {@link filterWrittenValue}.
*/
function stripProcessServers(
segments: readonly string[],
value: unknown,
processServers: ReadonlySet<string>,
): FilteredValue {
const names =
segments.length === 1 && segments[0] === 'mcpServers' && isPlainRecord(value)
? Object.keys(value).filter((name) => processServers.has(name))
: [];
if (names.length === 0) {
return { value, skipped: [], emptied: false };
}
const kept: Record<string, unknown> = {};
for (const [name, server] of Object.entries(value as Record<string, unknown>)) {
if (!processServers.has(name)) {
defineKey(kept, name, server);
}
}
return {
value: kept,
skipped: names.map((name) => ({
segments: ['mcpServers', name],
reason: 'process_mcp_server',
})),
emptied: isEmptied(kept),
};
}
/**
* Cuts out of a value written at `segments` what the generic config API never stores there,
* whatever librechat.yaml holds: role-permission fields of a whole `interface`, and fields only
* librechat.yaml sets. PUT, PATCH and change batches share it, so each reports the same parts as
* skipped.
*/
function filterWrittenValue(segments: readonly string[], value: unknown): FilteredValue {
const skipped: SkippedPart[] = [];
let next = value;
if (segments.length === 1 && segments[0] === 'interface' && isPlainRecord(next)) {
const filtered = filterInterfaceOverride(next);
for (const path of filtered.stripped) {
skipped.push({ segments: ['interface', ...path], reason: 'interface_permission' });
}
if (filtered.stripped.length > 0 && !filtered.value) {
return { value: undefined, skipped, emptied: true };
}
next = filtered.value ?? next;
}
const held = stripHeldPaths(segments, next);
skipped.push(...held.stripped);
return { value: held.value, skipped, emptied: skipped.length > 0 && isEmptied(held.value) };
}
/** A skipped part as the write report names it. */
function toSkippedLocation(part: SkippedPart): AdminConfigLocation & {
reason: AdminConfigSkipReason;
} {
return { path: part.segments.join('.'), segments: part.segments, reason: part.reason };
}
function toLocation(segments: readonly string[]): AdminConfigLocation {
return { path: segments.join('.'), segments: [...segments] };
}
/**
* 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.
*/
type NoSession = undefined;
/** Options of the principal-scoped config writes the handlers delegate whole. */
interface ConfigWriteOptions {
/** Write only when the stored document is at this revision (`absent`: only if none exists). */
expectedRevision?: ConfigRevision;
}
interface ConfigLifecycleOptions extends ConfigWriteOptions {
/** Act only on a document that holds nothing; otherwise resolve to `null`. */
expectEmpty?: boolean;
}
export interface AdminConfigDeps {
listAllConfigs: (filter?: { isActive?: boolean }, session?: NoSession) => Promise<ConfigRecord[]>;
findConfigByPrincipal: (
principalType: PrincipalType,
principalId: string,
options?: { includeInactive?: boolean },
session?: NoSession,
) => Promise<ConfigRecord | null>;
/**
* Writes the principal's whole document when it is still at `expected` (`absent`: only when
* none exists), or throws a `ConfigRevisionConflictError`. PUT, PATCH, POST `/changes`,
* tombstones and web search unsets plan the next document from the one they read, so
* validation, the principal check and secret preservation see exactly what the write replaces.
*/
writeConfigDocument: (
principalType: PrincipalType,
principalId: string,
draft: ConfigDraft,
expected: ConfigRevision,
) => Promise<ConfigRecord>;
/**
* Removes every path (dotted, or `{ segments }` for keys that contain dots) in one write,
* pruning parents left empty; `null` when there is no document.
*/
unsetConfigField: (
principalType: PrincipalType,
principalId: string,
fieldPaths: ConfigPathInputs,
session?: NoSession,
options?: ConfigWriteOptions,
) => Promise<ConfigRecord | null>;
deleteConfig: (
principalType: PrincipalType,
principalId: string,
session?: NoSession,
options?: ConfigLifecycleOptions,
) => Promise<ConfigRecord | null>;
/** Resolves to the post-write document and whether this write changed `isActive`. */
toggleConfigActiveTracked: (
principalType: PrincipalType,
principalId: string,
isActive: boolean,
options?: ConfigLifecycleOptions,
) => Promise<{ config: ConfigRecord; changed: boolean } | null>;
/**
* Sets only the document's priority in the caller's tenant partition (platform-level without
* a tenant, never a tenant's document for the same principal); resolves to it and whether
* this write changed it, or `null` when the principal has none there. Without it the priority
* route answers 501.
*/
setConfigPriority?: (
principalType: PrincipalType,
principalId: string,
priority: number,
options?: ConfigWriteOptions,
) => Promise<ConfigWriteOutcome | null>;
/**
* Whether the role (exact name), group or user (ObjectId) exists in the caller's tenant
* partition: the caller's tenant, or without one only platform-level principals. A write that
* would create a principal's first document refuses one that does not (404
* `PRINCIPAL_NOT_FOUND`), since that profile would never apply to anyone. Without this
* lookup nothing is checked.
*/
principalExists?: (principalType: PrincipalType, principalId: string) => Promise<boolean>;
hasConfigCapability: (
user: CapabilityUser,
section: ConfigSection | null,
verb?: 'manage' | 'read',
) => Promise<boolean>;
/** Pre-flight-only: whether the caller holds any config-read capability at all (broad or any section), so a zero-access caller 403s before a DB fetch. */
hasAnyConfigReadAccess?: (user: CapabilityUser) => Promise<boolean>;
/** Resolves which of a set of sections the caller can read in a single batched query. */
getReadableConfigSections?: (
user: CapabilityUser,
sections: ConfigSection[],
) => Promise<{ broad: boolean; sections: Set<string> }>;
hasCapability?: (user: CapabilityUser, capability: SystemCapability) => Promise<boolean>;
getAppConfig?: (options?: {
role?: string;
userId?: string;
tenantId?: string;
baseOnly?: boolean;
/** Read the overrides from the store instead of the per-principal merged-config cache. */
bypassOverrideCache?: boolean;
}) => Promise<AppConfig>;
/** Invalidate the config caches a mutation affects; awaited before the response is sent. */
invalidateConfigCaches?: (tenantId?: string) => Promise<void>;
/**
* The same clear for `POST /reload`, then librechat.yaml loaded again on this instance and,
* once it loaded, the broadcast, resolving with what each step reached instead of only logging
* a failure, so the route can answer for it.
*/
reloadConfigCaches?: (tenantId?: string) => Promise<ConfigReloadReport>;
/** Optional audit emission for override mutations; fail-open unless `auditFailClosed`. */
recordAuditEntry?: RecordAuditEntry;
/** When true, a failed audit write surfaces as a 5xx after the mutation has
* been persisted. Defaults to fail-open. */
auditFailClosed?: boolean;
/**
* The `overrideCacheTtl` the app config service runs with, which `GET /meta` reports.
* Defaults to the service's own default.
*/
overrideCacheTtlMs?: number;
/**
* Extra env names override values may reference (`CONFIG_OVERRIDE_ENV_ALLOWLIST`), beyond
* those librechat.yaml references and the built-in endpoint credentials. Must match what the
* app config service is given, so a write is judged by the policy its values resolve under.
*/
overrideEnvAllowlist?: string;
/**
* Whether the app config service derives Azure groups, Vertex AI and the Azure Assistants
* endpoint from overrides again (`CONFIG_REDERIVE_ENDPOINTS`): `GET /meta` reports it as
* `features.endpointRederive`, and write responses judge what a write drops by the same merge.
*/
rederiveEndpoints?: boolean;
}
/**
* What writes over `yaml` (librechat.yaml) are checked against beyond the schema: the custom
* endpoint parameter definitions startup would expand (`invalid_param_definitions`), and whether
* librechat.yaml configures the Vertex AI a write may turn on, besides the derived checks the
* store always runs (Azure groups, Vertex AI, model spec endpoints).
*/
function getWriteDerivation(yaml: Partial<TCustomConfig> | null): ConfigDerivation {
return { expandCustomEndpoint, vertexConfigured: isVertexConfigured(yaml) };
}
// ── Validation helpers ───────────────────────────────────────────────
const CONFIG_PRINCIPAL_TYPES = new Set([
PrincipalType.USER,
PrincipalType.GROUP,
PrincipalType.ROLE,
]);
export function validatePrincipalType(value: string): value is PrincipalType {
return CONFIG_PRINCIPAL_TYPES.has(value as PrincipalType);
}
const INVALID_PRIORITY_ERROR = 'priority must be a non-negative number';
function isValidPriority(value: unknown): value is number {
return typeof value === 'number' && Number.isFinite(value) && value >= 0;
}
function invalidPriorityResponse(res: Response): Response {
return res.status(400).json({ error: INVALID_PRIORITY_ERROR, code: 'INVALID_PRIORITY' });
}
export function principalNotFoundResponse(res: Response): Response {
return res.status(404).json({ error: 'Principal not found', code: 'PRINCIPAL_NOT_FOUND' });
}
function principalModel(type: PrincipalType): PrincipalModel {
switch (type) {
case PrincipalType.USER:
return PrincipalModel.USER;
case PrincipalType.GROUP:
return PrincipalModel.GROUP;
case PrincipalType.ROLE:
return PrincipalModel.ROLE;
case PrincipalType.PUBLIC:
return PrincipalModel.ROLE;
default: {
const _exhaustive: never = type;
logger.warn(`[adminConfig] Unmapped PrincipalType: ${String(_exhaustive)}`);
return PrincipalModel.ROLE;
}
}
}
export function getCapabilityUser(req: ServerRequest): CapabilityUser | null {
if (!req.user) {
return null;
}
return {
id: req.user.id ?? req.user._id?.toString() ?? '',
role: req.user.role ?? '',
tenantId: (req.user as { tenantId?: string }).tenantId,
};
}
/**
* `AppConfig` keys exempt from the generic per-key `read:configs:<section>`
* lookup in `filterSectionsByReadAccess`, for three distinct reasons:
* - `paths` is a server-computed constant (resolved at module load), not a
* `TCustomConfig` section, so no `read:configs:<section>` grant could ever
* apply to it.
* - `config` is the nested container whose contents are filtered separately
* below; checking the outer key against a nonexistent `read:configs:config`
* grant would always fail and strip the whole object, including sections
* the caller legitimately holds.
* - `availableTools` is derived from the `filteredTools`/`includedTools`
* sections plus a filesystem scan, not itself a grantable section. It gets
* its own explicit check below, gated on those two source sections, rather
* than a lookup against the nonexistent `read:configs:availableTools`.
* Real `TCustomConfig` sections (e.g. `fileStrategy`) must never be added
* here: exempting one would return it to every caller regardless of grants.
*/
const STRUCTURAL_APP_CONFIG_KEYS = new Set(['paths', 'availableTools', 'config']);
/**
* Top-level `AppConfig` response field → canonical `ConfigSection` name.
* `getAppConfig` renames a few sections in the resolved payload
* (`interface` → `interfaceConfig`, `turnstile` → `turnstileConfig`,
* `mcpServers` → `mcpConfig`). The read-grant capability is keyed by the
* canonical section name, so the top-level filter must normalize through
* this map before calling `canRead`. Otherwise a caller holding
* `read:configs:interface` gets `interfaceConfig` incorrectly stripped
* because no section named "interfaceConfig" exists to grant.
*/
const APP_CONFIG_FIELD_TO_SECTION: Readonly<Record<string, string>> = {
interfaceConfig: 'interface',
turnstileConfig: 'turnstile',
mcpConfig: 'mcpServers',
};
export type ReadableSections = { broad: boolean; sections: ReadonlySet<string> };
/** Every section `configSchema` defines: a write resolves read access to all of them before it commits. */
const CONFIG_SCHEMA_SECTIONS = Object.keys(configSchema.shape) as ConfigSection[];
const FULL_READ_ACCESS: ReadableSections = { broad: true, sections: new Set() };
/** Shows no section: an assign-only write stores an empty document. */
const NO_READ_ACCESS: ReadableSections = { broad: false, sections: new Set() };
export function canReadSection(readable: ReadableSections, section: string): boolean {
return readable.broad || readable.sections.has(section);
}
/** Strips every top-level key not in `preserveKeys` that `canRead` rejects. */
export function filterSectionsByReadAccess<T extends Record<string, unknown>>(
obj: T,
canRead: (section: string) => boolean,
preserveKeys: Set<string> = new Set(),
): T {
const result: Record<string, unknown> = { ...obj };
for (const key of Object.keys(result)) {
if (!preserveKeys.has(key) && !canRead(key)) {
delete result[key];
}
}
return result as T;
}
export function filterConfigDocForReadAccess<T extends ConfigRecord>(
config: T,
readable: ReadableSections,
): T {
const canRead = (section: string): boolean => canReadSection(readable, section);
const filteredOverrides = filterSectionsByReadAccess(
(config.overrides ?? {}) as Record<string, unknown>,
canRead,
);
let filteredTombstones = config.tombstones;
if (config.tombstones?.length) {
filteredTombstones = config.tombstones.filter((path) => canRead(getTopLevelSection(path)));
}
return {
...config,
overrides: filteredOverrides as Partial<TCustomConfig>,
tombstones: filteredTombstones,
};
}
function filterAppConfigForReadAccess(appConfig: AppConfig, readable: ReadableSections): AppConfig {
const canRead = (section: string): boolean => canReadSection(readable, section);
const canReadTopLevelField = (field: string): boolean =>
canRead(APP_CONFIG_FIELD_TO_SECTION[field] ?? field);
const filtered = filterSectionsByReadAccess(
appConfig as unknown as Record<string, unknown>,
canReadTopLevelField,
STRUCTURAL_APP_CONFIG_KEYS,
);
if (!canRead('filteredTools') && !canRead('includedTools')) {
delete (filtered as { availableTools?: unknown }).availableTools;
}
const nestedConfig = (filtered as { config?: Record<string, unknown> }).config;
if (nestedConfig != null && typeof nestedConfig === 'object') {
(filtered as { config?: unknown }).config = filterSectionsByReadAccess(nestedConfig, canRead);
}
return filtered as unknown as AppConfig;
}
/** All section names a config document's overrides/tombstones could reference. */
export function collectConfigSections(config: ConfigRecord): string[] {
return [
...Object.keys(config.overrides ?? {}),
...(config.tombstones ?? []).map(getTopLevelSection),
];
}
/** All section names an `AppConfig` response could reference, normalized to canonical section names. */
function collectAppConfigSections(appConfig: AppConfig): string[] {
const topLevel = Object.keys(appConfig)
.filter((key) => !STRUCTURAL_APP_CONFIG_KEYS.has(key))
.map((key) => APP_CONFIG_FIELD_TO_SECTION[key] ?? key);
const nested = (appConfig as unknown as { config?: Record<string, unknown> }).config;
return [...topLevel, ...(nested ? Object.keys(nested) : [])];
}
type ConfigResponse = ConfigRecord & { revision: ConfigRevision };
/** The document as the admin API returns it: secrets redacted, with its revision. */
export function redactConfigForResponse(config: ConfigRecord): ConfigResponse {
const safeConfig = JSON.parse(JSON.stringify(config)) as ConfigRecord;
if (safeConfig.overrides) {
safeConfig.overrides = withoutStoredSecretBindings(safeConfig.overrides);
redactConfigSecrets(safeConfig.overrides, { previewPlaintext: true });
}
return { ...safeConfig, revision: getConfigRevision(config) };
}
/**
* Redacts an `AppConfig` for an admin read. For a config merged with overrides,
* `yamlConfig` is the librechat.yaml config beneath them: a plaintext secret an
* override stored before its path was registered gets a preview, like a read
* of the override document itself.
*/
function redactAppConfigForResponse(appConfig: AppConfig, yamlConfig?: AppConfig): AppConfig {
const safeConfig = JSON.parse(JSON.stringify(appConfig)) as AppConfig & { config?: unknown };
redactConfigSecrets(safeConfig, { previewPlaintext: yamlConfig != null, yamlConfig });
redactResolvedConfigSecrets(safeConfig);
if (safeConfig.config != null && typeof safeConfig.config === 'object') {
redactConfigSecrets(safeConfig.config);
redactResolvedConfigSecrets(safeConfig.config);
}
return safeConfig;
}
/**
* A written document the way a read would return it: filtered to the read access resolved
* before the write, then redacted, with the revision of the whole stored document so the next
* write can be conditioned on it.
*/
function toWrittenConfig(config: ConfigRecord, access: ReadableSections): ConfigResponse {
const readable = access.broad ? config : filterConfigDocForReadAccess(config, access);
return redactConfigForResponse(readable);
}
/**
* The credentials a written document's layer drops at merge (`secretRebinding`), limited to the
* sections the response may show: each path names a server, endpoint or group of its section.
*/
function filterIgnoredForReadAccess(
ignored: readonly AdminConfigIgnoredSecret[],
access: ReadableSections,
): AdminConfigIgnoredSecret[] {
return ignored.filter(({ segments }) => canReadSection(access, segments[0]));
}
/** Read access to only the sections a write manages, for a response that resolves no other. */
function toWrittenSectionsAccess(
hasBroadManage: boolean,
managedSections: readonly string[],
): ReadableSections {
return hasBroadManage ? FULL_READ_ACCESS : { broad: false, sections: new Set(managedSections) };
}
/**
* A write's response: the written document as a read shows it, what the write applied and
* skipped (`report`, for the field writes), and what its layer drops.
*/
function sendWrittenConfig(
res: Response,
status: number,
config: ConfigRecord,
access: ReadableSections,
ignoredSecrets: readonly AdminConfigIgnoredSecret[] = [],
report?: AdminConfigWriteReport,
): Response {
const ignored = filterIgnoredForReadAccess(ignoredSecrets, access);
return res.status(status).json({
config: toWrittenConfig(config, access),
...report,
...(ignored.length > 0 && { ignored }),
});
}
/** The write report of a request: the locations it applied, and the parts it skipped. */
function toWriteReport(
applied: ReadonlyArray<readonly string[]>,
skipped: readonly SkippedPart[],
): AdminConfigWriteReport {
return { applied: applied.map(toLocation), skipped: skipped.map(toSkippedLocation) };
}
/** Logs each skipped part; `action` is how the route words it (`Stripping`, `Ignoring tombstone for`). */
function logSkippedParts(action: string, skipped: readonly SkippedPart[]): void {
for (const { segments, reason } of skipped) {
logSkippedField(action, segments.join('.'), reason);
}
}
/** A 4xx of the admin config API: a message and a stable code, plus any route-specific fields. */
function errorResponse(
res: Response,
status: number,
code: AdminConfigErrorCode,
error: string,
extra?: Record<string, unknown>,
): Response {
return res.status(status).json({ error, code, ...extra });
}
export function authRequiredResponse(res: Response): Response {
return errorResponse(res, 401, 'AUTH_REQUIRED', 'Authentication required');
}
export function forbiddenResponse(res: Response): Response {
return errorResponse(res, 403, 'FORBIDDEN', 'Insufficient permissions');
}
function forbiddenSectionResponse(res: Response, section: string): Response {
return errorResponse(
res,
403,
'FORBIDDEN_SECTION',
`Insufficient permissions for config section: ${section}`,
{ section },
);
}
function invalidPrincipalTypeResponse(res: Response, principalType: string): Response {
return errorResponse(
res,
400,
'INVALID_PRINCIPAL_TYPE',
`Invalid principalType: ${principalType}`,
);
}
function configNotFoundResponse(res: Response): Response {
return errorResponse(res, 404, 'CONFIG_NOT_FOUND', 'Config not found');
}
function processServerOverrideResponse(res: Response, extra?: Record<string, unknown>): Response {
return errorResponse(
res,
400,
'PROCESS_MCP_SERVER_OVERRIDE',
PROCESS_MCP_SERVER_OVERRIDE_ERROR,
extra,
);
}
/**
* Field writes must address a section `configSchema` defines: anything else (`paths`, the raw
* `config`, an AppService alias such as `interfaceConfig`) would reach runtime state. The path
* is not echoed back.
*/
function unknownSectionResponse(res: Response): Response {
return res.status(400).json({ error: 'Unknown config section', code: 'UNKNOWN_SECTION' });
}
/**
* Reports only locations, stable codes and the schema's own bounds and options (`params`, from
* an allowlist that never copies the submitted value): schema messages can echo the submitted
* values. `segments` names the location key by key, since `path` is ambiguous once a record key
* itself holds a dot. `report` adds what a route reports alongside them (a batch's `skipped`).
*/
function invalidOverrideResponse(
res: Response,
issues: ConfigOverrideIssue[],
report?: Pick<AdminConfigChangeErrorResponse, 'skipped'>,
): Response {
return res.status(400).json({
error: 'Invalid config override',
code: 'CONFIG_OVERRIDE_INVALID',
issues: issues.map(({ path, segments, code, params }) =>
params ? { path, segments, code, params } : { path, segments, code },
),
...report,
} satisfies AdminConfigInvalidResponse);
}
/**
* The database refused a key name in the written overrides, such as a dotted record key on an
* engine that cannot store one. Nothing was written; the key is not echoed.
*/
function unstorableKeyResponse(res: Response, operation: string): Response {
logger.warn(
`[adminConfig] ${operation}: the database rejected a key name in the overrides, such as a dotted record key this engine cannot store`,
);
return res.status(422).json({
error: 'The database cannot store a key name in this config',
code: 'CONFIG_KEY_NOT_STORABLE',
});
}
/**
* The answer to a reload that did not load librechat.yaml on this instance or did not reach
* every instance, or `null` when it did. A refused file is reported first, since retrying cannot
* fix it; its issues carry locations and zod codes only.
*/
function getReloadFailure(
report: ConfigReloadReport,
): { status: number; body: AdminConfigReloadErrorResponse } | null {
const loadFailure = report.loaded?.ok === false ? report.loaded.error : undefined;
if (loadFailure?.code === 'CONFIG_INVALID') {
return {
status: 422,
body: {
error: 'librechat.yaml failed to load; the last good config is still served',
code: 'CONFIG_RELOAD_INVALID',
issues: loadFailure.issues.map(({ path, segments, code }) => ({ path, segments, code })),
},
};
}
if (!report.cleared || loadFailure) {
return {
status: 500,
body: { error: 'Failed to reload config', code: 'CONFIG_RELOAD_FAILED' },
};
}
if (report.broadcast !== 'failed') {
return null;
}
return {
status: 503,
body: {
error: 'Config reloaded on this instance only; the other instances could not be notified',
code: 'CONFIG_RELOAD_BROADCAST_FAILED',
},
};
}
/**
* Rejects a write that would send a stored secret to a destination it was not
* entered for. Reports only locations and stable codes, never a value; `segments`
* names the location key by key, as other config issues do.
*/
function secretReentryResponse(res: Response, issues: SecretReentryIssue[]): Response {
return res.status(400).json({
error: 'Enter the stored API key again when changing the URL it is sent to',
code: 'CONFIG_SECRET_REENTRY_REQUIRED',
issues: issues.map(({ path, segments, code, secretPath }) => ({
path,
segments,
code,
secretPath,
})),
});
}
/**
* A write run on the validation floor, with the active Base document it was last judged on
* (`undefined` when the write read none: Base itself, or a write with nothing to validate).
*/
type FloorOutcome<T> = ConfigMutationOutcome<T> & { base?: ConfigRecord | null };
/**
* The tenant partitions a write to one principal's document involves. `tenantId` is the one the
* document merges in (`undefined`: the deployment's own, tenantless), so the write is judged on
* librechat.yaml as that partition resolves it and on that partition's Base. `activeTenantId` is
* the request's own (the caller's), where the store addresses role documents and creates a
* document the write makes.
*/
interface WriteScope {
tenantId: string | undefined;
activeTenantId: string | undefined;
}
/**
* Why a planned unset or tombstone wrote nothing: no document to unset, no principal to create
* one for, or a stored credential it would send elsewhere without entering it again.
*/
type RemovalStop =
| { status: 404; missing: 'config' | 'principal' }
| { status: 400; reentry: SecretReentryIssue[] }
| { status: 400; mcpReentry: SecretReentry };
function removalStopResponse(res: Response, stop: RemovalStop): Response {
if ('reentry' in stop) {
return secretReentryResponse(res, stop.reentry);
}
if ('mcpReentry' in stop) {
return mcpReentryResponse(res, stop.mcpReentry);
}
return stop.missing === 'principal'
? principalNotFoundResponse(res)
: configNotFoundResponse(res);
}
const INVALID_EXPECTED_REVISION_ERROR =
'expectedRevision must be "absent" or a revision returned by the config API';
/** A client precondition: absent (none given), a well-formed revision, or malformed. */
function readExpectedRevision(
value: unknown,
): { ok: true; value?: ConfigRevision } | { ok: false } {
if (value === undefined || value === null) {
return { ok: true };
}
return isConfigRevision(value) ? { ok: true, value } : { ok: false };
}
function invalidExpectedRevisionResponse(res: Response): Response {
return res
.status(400)
.json({ error: INVALID_EXPECTED_REVISION_ERROR, code: 'INVALID_EXPECTED_REVISION' });
}
/** Reports why a path cannot apply to the stored document, without echoing the path. */
function invalidPathResponse(res: Response, error: ConfigPathError): Response {
return res.status(400).json({
error: 'Config path cannot be applied to the stored config',
code: 'CONFIG_PATH_INVALID',
reason: error.reason,
});
}
function preservePatchedConfigSecretFields(
fields: Record<string, unknown>,
existingOverrides?: unknown,
): Record<string, unknown> {
const result = { ...fields };
for (const [fieldPath, value] of Object.entries(result)) {
if (isConfigSecretPreservablePatch(fieldPath, value)) {
result[fieldPath] = preserveConfigSecrets(value, existingOverrides, fieldPath);
}
}
return result;
}
/** Most rename hints one write accepts. */
const MAX_RENAMES = 50;
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, 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) {
return { ok: true, renames: [] };
}
if (!Array.isArray(value) || value.length > MAX_RENAMES) {
return { ok: false, reason: 'invalid_renames' };
}
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 (!isRenamePath(path)) {
return { ok: false, reason: 'unsupported_path' };
}
if (
typeof previousName !== 'string' ||
typeof name !== 'string' ||
previousName === '' ||
name === '' ||
UNSAFE_NAME.test(previousName) ||
UNSAFE_NAME.test(name) ||
getRenameIdentity(path, previousName) === getRenameIdentity(path, name)
) {
return { ok: false, reason: 'invalid_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(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)
.json({ error: 'Invalid rename hint', code: 'CONFIG_RENAME_INVALID', reason });
}
/** Whether a write sets the value at `target`: at it, below it, or at an ancestor whose value reaches it. */
function writesTarget(writes: readonly ConfigFieldWrite[], target: readonly string[]): boolean {
return writes.some(
({ segments, value }) =>
isSegmentPrefix(target, segments) ||
(isSegmentPrefix(segments, target) &&
getAtPath(value, target.slice(segments.length)) !== undefined),
);
}
/**
* 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 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 ||
typeof storedRecord !== 'object' ||
!Object.prototype.hasOwnProperty.call(storedRecord, previousName)
) {
return 'source_not_found';
}
if (!writesTarget(writes, [path, name])) {
return 'target_not_written';
}
}
return null;
}
function mcpReentryResponse(res: Response, reentry: SecretReentry): Response {
const { message, code, server, fields } = reentry;
return res.status(400).json({ error: message, code, server, fields });
}
/** Describes rename hints for the audit record: paths and names, never values. */
function describeRenames(renames: readonly ConfigSecretRename[]): string {
return renames.map(({ path, previousName, name }) => `${path}:${previousName}>${name}`).join(',');
}
/**
* Whether removing a field in `section` can change where a bound secret is sent: only then does a
* field removal or tombstone report what it drops.
*/
function isBoundSecretSection(section: string | undefined): boolean {
return section != null && REBINDING_SECTIONS.includes(section);
}
/** Whether a document overrides or tombstones anything in a section with bound secrets. */
function touchesBoundSecretSections(
record: Pick<ConfigOverrideLayer, 'overrides' | 'tombstones'>,
): boolean {
const overrides = (record.overrides ?? {}) as Record<string, unknown>;
return REBINDING_SECTIONS.some(
(section) =>
section in overrides ||
(record.tombstones ?? []).some(
(path) => typeof path === 'string' && path.split('.')[0] === section,
),
);
}
const MCP_SECTIONS = new Set<string>(MCP_SERVER_SECTIONS);
/** A removal enters no secret: whatever credential it leaves in place was kept. */
const NO_ENTERED_SECRETS: ReadonlySet<string> = new Set();
/** Whether a path holds Azure groups or anything in them: `endpoints`, and all of its Azure section. */
function isAzureGroupPath(segments: readonly string[]): boolean {
return (
segments[0] === 'endpoints' &&
(segments.length === 1 || segments[1] === EModelEndpoint.azureOpenAI)
);
}
/** Sections whose keys sit beside their own destination: OCR's and each speech service's. */
const SCALAR_BOUND_SECTIONS = new Set<string>(['ocr', 'speech']);
/** Whether a path names an OCR or speech key itself, or its preview: removing it moves nothing. */
function isScalarSecretPath(segments: readonly string[]): boolean {
return SECRET_BINDINGS.some(
({ path, secretKey }) =>
segments.length === path.length + 1 &&
path.every((segment, index) => segments[index] === segment) &&
(segments[path.length] === secretKey || segments[path.length] === `${secretKey}Preview`),
);
}
/**
* Whether a path holds a key bound to the destination beside it, or that destination: OCR,
* speech, or a custom endpoint (and `endpoints` whole). The key itself is not such a path.
*/
function isBoundKeyPath(segments: readonly string[]): boolean {
if (isScalarSecretPath(segments)) {
return false;
}
return (
SCALAR_BOUND_SECTIONS.has(segments[0]) ||
(segments[0] === 'endpoints' && (segments.length === 1 || segments[1] === 'custom'))
);
}
/**
* Whether removing or tombstoning `target` can change where a stored credential is sent: a web
* search URL (or the whole section) beside a stored key, any field of an MCP server, anything an
* Azure group's key and destination sit in, or anything an OCR, speech or custom endpoint key
* and its destination sit in.
*/
function isBoundRemoval(target: FieldTarget): boolean {
return (
(target.dotFree && isWebSearchBindingPath(target.fieldPath)) ||
MCP_SECTIONS.has(target.segments[0]) ||
isAzureGroupPath(target.segments) ||
isBoundKeyPath(target.segments)
);
}
/**
* The stored keys a planned document keeps beside a destination it changes, which the request
* must enter again: web search keys, Azure group keys (compared over librechat.yaml's resolved
* groups, from `baseConfig`), and custom endpoint, OCR and speech keys (compared as the document
* alone sends them over librechat.yaml). MCP credentials answer with their own error
* (`findSecretReentry`).
*/
function getKeptKeyReentryIssues(
stored: ConfigRecord | null | undefined,
candidate: ConfigOverrideState,
entered: ReadonlySet<string>,
baseConfig: AppConfig | undefined,
): SecretReentryIssue[] {
return [
...getWebSearchReentryIssues(stored, candidate, entered),
...getAzureGroupReentryIssues({
stored,
candidate,
entered,
base: {
groups: baseConfig?.config?.endpoints?.[EModelEndpoint.azureOpenAI]?.groups,
groupMap: baseConfig?.endpoints?.[EModelEndpoint.azureOpenAI]?.groupMap,
},
}),
...getBoundKeyReentryIssues({ stored, candidate, entered, baseConfig }),
];
}
// ── Change batches ───────────────────────────────────────────────────
type ChangeOpKind = AdminConfigChangeOp['op'];
const CHANGE_OPS: ReadonlySet<string> = new Set<ChangeOpKind>([
'set',
'unset',
'tombstone',
'upsertEntry',
'removeEntry',
'rename',
]);
/** Changes whose own path may not reach into a merged-by-key array entry by position. */
const INDEXED_PATH_OPS: ReadonlySet<ChangeOpKind> = new Set<ChangeOpKind>([
'set',
'unset',
'rename',
]);
/**
* Changes that leave an override or tombstone at their path, refused inside an MCP server
* librechat.yaml runs as a local process (an `unset` there is cleanup).
*/
const SERVER_WRITE_OPS: ReadonlySet<ChangeOpKind> = new Set<ChangeOpKind>([
'set',
'tombstone',
'rename',
]);
type SkippedChange = AdminConfigChangeRef & { reason: AdminConfigSkipReason };
type IgnoredChange = AdminConfigChangeRef & { reason: AdminConfigIgnoreReason };
/** A 400 for one change of a batch; `opIndex` names it and nothing submitted is echoed. */
interface ChangeFailure {
error: string;
code: string;
opIndex: number;
reason?: string;
}
/**
* A change of a batch, checked and prepared before the stored document is read: guards run,
* skipped parts are cut out, and submitted secrets are encrypted once. What depends on the
* stored document (secrets an object omits, entries to rename) is resolved while applying.
*/
interface PreparedChange {
index: number;
op: ChangeOpKind;
target: FieldTarget;
/** The entry key of `upsertEntry` and `removeEntry`; the old key of `rename`. */
key?: string;
/** The new key of `rename`. */
to?: string;
/**
* `set`: the value to store, after normalization and stripping. `upsertEntry`: the entry as
* submitted, before its secrets are encrypted.
*/
value?: unknown;
/** `set` on a dot-free path: `value` with secrets encrypted, plus any preview companion. */
fields?: Record<string, unknown>;
/** `upsertEntry`: the entry with secrets encrypted. */
entry?: Record<string, unknown>;
/**
* `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?: ConfigLocation[];
}
type PreparedRead =
| {
ok: true;
/** Two changes with the same identity address the same location. */
identity: string;
section: string;
/** `null` when the whole change is skipped. */
change: PreparedChange | null;
skipped: SkippedChange[];
}
| { ok: false; failure: ChangeFailure };
function changeFailure(
opIndex: number,
error: string,
code: string,
reason?: string,
): PreparedRead {
return {
ok: false,
failure: reason ? { error, code, opIndex, reason } : { error, code, opIndex },
};
}
function toChangeRef(
change: Pick<PreparedChange, 'index' | 'op' | 'target' | 'key'>,
): AdminConfigChangeRef {
const ref: AdminConfigChangeRef = {
opIndex: change.index,
op: change.op,
segments: [...change.target.segments],
};
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;
}
function isEntryOp(op: ChangeOpKind): boolean {
return op === 'upsertEntry' || op === 'removeEntry' || op === 'rename';
}
function isNonEmptyString(value: unknown): value is string {
return typeof value === 'string' && value !== '';
}
/**
* 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((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;
}
/**
* Prepares a `set`: refuses what PATCH refuses, skips what PATCH strips, filters a whole
* `interface` object and base-only fields out of the value (reporting each), and encrypts it.
* A set replaces what is stored at its path with what is left of its value, so one whose
* whole value is filtered out resets the path, as an `unset` does.
*/
function prepareSet(
raw: Record<string, unknown>,
base: Pick<PreparedChange, 'index' | 'op' | 'target'>,
skipReason: AdminConfigSkipReason | null,
): PreparedRead | { ok: true; change: PreparedChange | null; skipped: SkippedChange[] } {
const { index, target } = base;
if (!Object.prototype.hasOwnProperty.call(raw, 'value') || raw.value === undefined) {
return changeFailure(index, 'A set change needs a value', 'INVALID_CHANGE');
}
const guardError = getFieldWriteError(target.fieldPath, raw.value);
if (guardError) {
return changeFailure(index, guardError.error, guardError.code);
}
const ref = toChangeRef(base);
if (skipReason) {
return { ok: true, change: null, skipped: [{ ...ref, reason: skipReason }] };
}
const filtered = filterWrittenValue(
target.segments,
normalizeInterfaceFieldPatch(target.fieldPath, raw.value),
);
const skipped: SkippedChange[] = filtered.skipped.map(({ segments, reason }) => ({
...ref,
segments,
reason,
}));
if (filtered.emptied) {
return { ok: true, change: { ...base, paths: getRemovalPaths(target) }, skipped };
}
const { value } = filtered;
const fields = target.dotFree
? encryptConfigSecretFields({ [target.fieldPath]: value })
: undefined;
return { ok: true, change: { ...base, value, fields }, skipped };
}
/** Prepares an entry change: the path must hold a merged-by-key array (or, to rename, a record). */
function prepareEntryChange(
raw: Record<string, unknown>,
base: Pick<PreparedChange, 'index' | 'op' | 'target'>,
skipReason: AdminConfigSkipReason | null,
): PreparedRead | { ok: true; change: PreparedChange | null; skipped: SkippedChange[] } {
const { index, op, target } = base;
const keyField = getConfigArrayMergeKey(target.segments);
let change: PreparedChange;
if (op === 'rename') {
if (!isNonEmptyString(raw.from) || !isNonEmptyString(raw.to)) {
return changeFailure(
index,
'A rename needs non-empty from and to',
'CONFIG_ENTRY_INVALID',
'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(
index,
'A rename addresses a collection merged by key or a record of named entries',
'CONFIG_ENTRY_INVALID',
'not_collection',
);
}
for (const name of [raw.from, raw.to]) {
const keyTarget = readFieldTarget(undefined, [...target.segments, name]);
if (!keyTarget.ok) {
return changeFailure(index, keyTarget.error, 'CONFIG_PATH_INVALID', keyTarget.reason);
}
}
if (isConfigSecretKeyRename(target.segments, raw.from, raw.to)) {
return changeFailure(index, 'A rename cannot move a registered secret', 'SECRET_PATH');
}
}
change = { ...base, key: raw.from, to: raw.to };
} else if (!keyField) {
return changeFailure(
index,
'Entry changes address a collection merged by key, such as endpoints.custom',
'CONFIG_ENTRY_INVALID',
'not_collection',
);
} else if (op === 'removeEntry') {
if (!isNonEmptyString(raw.key)) {
return changeFailure(
index,
'removeEntry needs a non-empty key',
'CONFIG_ENTRY_INVALID',
'invalid_entry',
);
}
change = { ...base, key: raw.key };
} else {
const key = getConfigEntryKey(raw.entry, keyField);
if (key === undefined) {
return changeFailure(
index,
`upsertEntry needs an entry object with a non-empty ${keyField}`,
'CONFIG_ENTRY_INVALID',
'invalid_entry',
);
}
const guardError = getFieldWriteError(target.fieldPath, [raw.entry]);
if (guardError) {
return changeFailure(index, guardError.error, guardError.code);
}
const [entry] = encryptConfigSecrets([raw.entry as Record<string, unknown>], target.fieldPath);
change = { ...base, key, entry, value: raw.entry };
}
if (skipReason) {
return { ok: true, change: null, skipped: [{ ...toChangeRef(change), reason: skipReason }] };
}
return { ok: true, change, skipped: [] };
}
/**
* What a change addresses, for refusing two changes of a batch that address the same thing: a
* path, or one entry of a collection (by its key's identity, so `Ollama` and `ollama` are one
* custom endpoint; a rename by the key it starts from).
*/
function getChangeIdentity(
raw: Record<string, unknown>,
op: ChangeOpKind,
target: FieldTarget,
): string {
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);
}
if (op === 'removeEntry') {
return toEntry(raw.key);
}
const keyField = getConfigArrayMergeKey(segments);
return toEntry(keyField ? getConfigEntryKey(raw.entry, keyField) : null);
}
/**
* Reads and checks one change of a batch without touching the stored document. A change
* refused outright fails the whole batch (400, by `opIndex`); one the API never stores
* (decision #2: base-only, deployment-owned, dedicated, interface permission) is reported as
* skipped and the rest of the batch still applies.
*/
function prepareChange(raw: unknown, index: number): PreparedRead {
if (!isPlainRecord(raw) || typeof raw.op !== 'string' || !CHANGE_OPS.has(raw.op)) {
return changeFailure(
index,
'Each change needs an op: set, unset, tombstone, upsertEntry, removeEntry or rename',
'INVALID_CHANGE',
);
}
const op = raw.op as ChangeOpKind;
const read = readFieldTarget(raw.fieldPath, raw.segments);
if (!read.ok) {
return changeFailure(
index,
read.error,
read.reason ? 'CONFIG_PATH_INVALID' : 'INVALID_FIELD_PATH',
read.reason,
);
}
const { target } = read;
const base = { index, op, target };
const section = target.segments[0];
/** Unsetting what an older server stored outside configSchema is cleanup, as DELETE allows. */
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:
| PreparedRead
| { ok: true; change: PreparedChange | null; skipped: SkippedChange[] };
if (op === 'set') {
prepared = prepareSet(raw, base, sectionSkip ?? getHeldPathSkipReason(target.segments));
} else if (isEntryOp(op)) {
prepared = prepareEntryChange(raw, base, sectionSkip);
} else {
if (op === 'tombstone' && !target.dotFree) {
return changeFailure(
index,
'A tombstone cannot name a key that contains a dot',
'CONFIG_PATH_INVALID',
'dotted_segment',
);
}
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,
INSIDE_ARRAY_TOMBSTONE_ERROR,
'CONFIG_PATH_INVALID',
'inside_array',
);
}
const removalError =
target.dotFree && !target.entry ? getFieldRemovalError(target.fieldPath) : null;
if (removalError) {
return changeFailure(index, removalError.error, removalError.code);
}
/** Unsetting a stored held or derived field 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(change), reason: skipReason }] }
: { ok: true, change, skipped: [] };
}
if (!prepared.ok) {
return prepared;
}
return {
ok: true,
identity: getChangeIdentity(raw, op, target),
section,
change: prepared.change,
skipped: prepared.skipped,
};
}
/** The changes a prepared change applies, resolved against the document as it stands. */
function expandChange(change: PreparedChange, overrides: unknown): ConfigChange[] {
const { segments } = change.target;
switch (change.op) {
case 'set': {
if (change.paths) {
return change.paths.map((path) => ({ op: 'unset', segments: path.segments }));
}
if (!change.fields) {
return [{ op: 'set', segments, value: change.value }];
}
/** Secrets an object omits are kept from the document before this change. */
const fields = preservePatchedConfigSecretFields(change.fields, overrides);
return toOrderedWrites([{ target: change.target, value: change.value }], fields).map(
(write) => ({ op: 'set', segments: write.segments, value: write.value }),
);
}
case 'unset':
case 'tombstone':
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. */
const [entry] = preserveConfigSecrets(
[change.entry ?? {}],
overrides,
change.target.fieldPath,
);
return [{ op: 'upsertEntry', segments, entry }];
}
case 'removeEntry':
return [{ op: 'removeEntry', segments, key: change.key ?? '' }];
case 'rename':
return [{ op: 'rename', segments, from: change.key ?? '', to: change.to ?? '' }];
}
}
/**
* Whether `librechat.yaml` itself defines entry `name` of the collection a change addresses:
* an entry of a merged-by-key array by its identity, so `ollama` names the YAML `Ollama`.
*/
function isYamlEntry(base: unknown, change: PreparedChange, name: string): boolean {
const node = getAtPath(base, change.target.segments);
const keyField = getConfigArrayMergeKey(change.target.segments);
if (keyField) {
return (
Array.isArray(node) &&
node.some(getConfigEntryMatcher(change.target.segments, keyField, name))
);
}
return isPlainRecord(node) && Object.prototype.hasOwnProperty.call(node, name);
}
/**
* What `librechat.yaml` keeps whatever an override does: the MCP servers it runs as local
* processes, and the base-only and deployment-only fields that have a value the merge puts back:
* set in `base`, or in `resolved`, the AppConfig librechat.yaml resolves to (defaults included).
*/
interface YamlHeld {
processServers: ReadonlySet<string>;
heldPaths: readonly YamlHeldPath[];
}
function getYamlHeld(base: Partial<TCustomConfig>, resolved?: AppConfig): YamlHeld {
return {
processServers: getProcessServerNames(base),
heldPaths: YAML_HELD_PATHS.filter(
({ segments }) =>
getAtPath(base, segments) !== undefined || getAtPath(resolved, segments) !== undefined,
),
};
}
type IgnoredPart = { segments: string[]; reason: AdminConfigIgnoreReason };
/**
* The MCP servers librechat.yaml runs as local processes that a tombstone of the whole
* `mcpServers` section leaves in place. A change inside one is refused before it applies, and a
* whole-section value leaves them out, so this is the only change that reaches one.
*/
function getProcessServerParts(
change: PreparedChange,
processServers: ReadonlySet<string>,
): IgnoredPart[] {
const { segments } = change.target;
if (change.op !== 'tombstone' || segments.length !== 1 || segments[0] !== 'mcpServers') {
return [];
}
return [...processServers].map((server) => ({
segments: ['mcpServers', server],
reason: 'process_mcp_server',
}));
}
/**
* The parts of an applied change the runtime merge drops: the YAML stdio MCP servers a tombstone
* of the whole section leaves in place, and the base-only and deployment-only fields
* librechat.yaml sets below a tombstone (a tombstone of one itself is skipped), which the merge
* puts back so the tombstone hides only the rest.
*/
function getIgnoredParts(change: PreparedChange, held: YamlHeld): IgnoredPart[] {
const parts = getProcessServerParts(change, held.processServers);
if (change.op !== 'tombstone') {
return parts;
}
const { segments } = change.target;
const kept = held.heldPaths
.filter((path) => path.segments.length > segments.length)
.filter((path) => isSegmentPrefix(segments, path.segments))
.map((path): IgnoredPart => ({ segments: [...path.segments], reason: path.reason }));
return [...parts, ...kept];
}
const AZURE_GROUPS_SEGMENTS = ['endpoints', EModelEndpoint.azureOpenAI, 'groups'];
function isAzureGroupsTarget(segments: readonly string[]): boolean {
return (
segments.length === AZURE_GROUPS_SEGMENTS.length &&
isSegmentPrefix(AZURE_GROUPS_SEGMENTS, segments)
);
}
/**
* The parts of an applied change the merge leaves inert where the deployment does not resolve
* Azure groups (`CONFIG_REDERIVE_ENDPOINTS` off; `endpoint_rederive_off`): a `set` of the groups,
* or of an object whose value holds them, an `upsertEntry` or `rename` of a group, and a tombstone
* of the groups or of one of them (keyed). An `unset` or `removeEntry` only clears what is stored.
*/
function getInertGroupParts(change: PreparedChange): IgnoredPart[] {
const { segments } = change.target;
const whole: IgnoredPart[] = [{ segments: [...segments], reason: 'endpoint_rederive_off' }];
if (change.op === 'tombstone' || change.op === 'upsertEntry' || change.op === 'rename') {
return isAzureGroupsTarget(segments) ? whole : [];
}
if (change.op !== 'set' || change.paths) {
return [];
}
if (isSegmentPrefix(AZURE_GROUPS_SEGMENTS, segments)) {
return whole;
}
const inside = AZURE_GROUPS_SEGMENTS.slice(segments.length);
return isSegmentPrefix(segments, AZURE_GROUPS_SEGMENTS) &&
Array.isArray(getAtPath(change.value, inside))
? [{ segments: [...AZURE_GROUPS_SEGMENTS], reason: 'endpoint_rederive_off' }]
: [];
}
/**
* A `set` of a whole `mcpServers` value without the servers librechat.yaml runs as local
* processes, re-encrypted, and the parts it left out; with nothing left, it resets the path. Any
* other change is returned as is.
*/
function withoutProcessServers(
change: PreparedChange,
processServers: ReadonlySet<string>,
): { change: PreparedChange; skipped: SkippedChange[] } {
if (change.op !== 'set' || change.paths) {
return { change, skipped: [] };
}
const filtered = stripProcessServers(change.target.segments, change.value, processServers);
if (filtered.skipped.length === 0) {
return { change, skipped: [] };
}
const ref = toChangeRef(change);
const skipped = filtered.skipped.map(({ segments, reason }) => ({ ...ref, segments, reason }));
if (filtered.emptied) {
return {
change: {
...change,
value: undefined,
fields: undefined,
paths: getRemovalPaths(change.target),
},
skipped,
};
}
const fields = change.target.dotFree
? encryptConfigSecretFields({ [change.target.fieldPath]: filtered.value })
: undefined;
return { change: { ...change, value: filtered.value, fields }, skipped };
}
/** How an applied change is named in audit metadata: its path, plus the entry it addressed. */
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)}]`;
}
return change.key !== undefined ? `${path}[${JSON.stringify(change.key)}]` : path;
}
/**
* Where the value an applied change sends sits in the document it leaves (`next`): a set's path,
* or an upserted entry at its position in its collection. `null` for a change that sends none.
*/
function getSentLocation(change: PreparedChange, next: ConfigOverrideState): string[] | null {
const { segments } = change.target;
if (change.op === 'set' && !change.paths) {
return [...segments];
}
if (change.op !== 'upsertEntry') {
return null;
}
const keyField = getConfigArrayMergeKey(segments);
const entries = getAtPath(next.overrides, segments);
const index =
keyField && Array.isArray(entries)
? entries.findIndex(getConfigEntryMatcher(segments, keyField, change.key ?? ''))
: -1;
return index >= 0 ? [...segments, String(index)] : null;
}
/**
* Env reference issues in the value an applied change sent, by identity
* (`toConfigIdentityPath`): each location is named in the document the change left, with every
* entry of a merged-by-key array by its key, so the issue still names that entry however later
* changes of the batch move, add or remove other entries.
*/
function getSentEnvIssuePaths(
change: PreparedChange,
next: ConfigOverrideState,
policy: EnvReferencePolicy,
): ConfigIdentityStep[][] {
const location = getSentLocation(change, next);
if (!location) {
return [];
}
return getEnvReferenceIssues(change.value, policy, location).map(({ segments }) =>
toConfigIdentityPath(next.overrides, segments),
);
}
/**
* Env reference issues for the values a batch's changes sent, judged on the document the batch
* leaves as its other issues are. Each is held by identity (`getSentEnvIssuePaths`), carried
* through the batch's later renames, and named where the batch leaves the value; it counts only
* when the end state still holds a disallowed reference there (as stored, ciphertext by its
* plaintext) at a location the batch changed (`written`). A reference a later change removed or
* replaced, or one that leaves the stored value as it was, does not.
*/
function getBatchEnvIssues(
sent: ReadonlyArray<readonly ConfigIdentityStep[]>,
state: ConfigOverrideState,
written: ReadonlyArray<readonly string[]>,
policy: EnvReferencePolicy,
): ConfigOverrideIssue[] {
const reported = new Set<string>();
return sent.flatMap((path): ConfigOverrideIssue[] => {
const segments = resolveConfigIdentityPath(state.overrides, path);
if (!segments) {
return [];
}
const kept = getAtPath(state.overrides, segments);
const key = segments.join('\u0000');
if (
reported.has(key) ||
typeof kept !== 'string' ||
!hasDisallowedStoredReference(kept, policy, segments) ||
!written.some((writtenPath) => isSegmentPrefix(writtenPath, segments))
) {
return [];
}
reported.add(key);
return [{ path: segments.join('.'), segments, code: ENV_REFERENCE_NOT_ALLOWED }];
});
}
/**
* The secret values a batch's changes entered, encrypted, before secret preservation fills in
* what they omit (see `getEnteredConfigSecrets`).
*/
function getEnteredChangeSecrets(changes: readonly PreparedChange[]): Set<string> {
return getEnteredConfigSecrets(
changes.flatMap((change): ConfigFieldWrite[] => {
if (change.op === 'upsertEntry' && change.entry) {
return [{ segments: change.target.segments, value: [change.entry] }];
}
if (change.op !== 'set' || !change.fields) {
return [];
}
return Object.entries(change.fields).map(([fieldPath, value]) => ({
segments: parseFieldPath(fieldPath),
value,
}));
}),
);
}
// ── Handler factory ──────────────────────────────────────────────────
export function createAdminConfigHandlers(deps: AdminConfigDeps): {
listConfigs: (req: ServerRequest, res: Response) => Promise<Response>;
getConfigMeta: (req: ServerRequest, res: Response) => Promise<Response>;
getBaseConfig: (req: ServerRequest, res: Response) => Promise<Response>;
getConfig: (req: ServerRequest, res: Response) => Promise<Response>;
upsertConfigOverrides: (req: ServerRequest, res: Response) => Promise<Response>;
patchConfigField: (req: ServerRequest, res: Response) => Promise<Response>;
tombstoneConfigField: (req: ServerRequest, res: Response) => Promise<Response>;
deleteConfigField: (req: ServerRequest, res: Response) => Promise<Response>;
applyConfigChanges: (req: ServerRequest, res: Response) => Promise<Response>;
deleteConfigOverrides: (req: ServerRequest, res: Response) => Promise<Response>;
toggleConfig: (req: ServerRequest, res: Response) => Promise<Response>;
updateConfigPriority: (req: ServerRequest, res: Response) => Promise<Response>;
reloadConfig: (req: ServerRequest, res: Response) => Promise<Response>;
} {
const {
listAllConfigs,
findConfigByPrincipal,
writeConfigDocument,
unsetConfigField,
deleteConfig,
toggleConfigActiveTracked,
setConfigPriority,
principalExists,
hasConfigCapability,
hasAnyConfigReadAccess = async () => false,
getReadableConfigSections = async (u, sections) => {
if (await hasConfigCapability(u, null, 'read')) {
return { broad: true, sections: new Set(sections) };
}
const held = await Promise.all(
sections.map((section) => hasConfigCapability(u, section, 'read')),
);
return { broad: false, sections: new Set(sections.filter((_, i) => held[i])) };
},
hasCapability = async () => false,
getAppConfig,
invalidateConfigCaches,
reloadConfigCaches,
recordAuditEntry,
auditFailClosed,
overrideCacheTtlMs = DEFAULT_OVERRIDE_CACHE_TTL,
overrideEnvAllowlist,
rederiveEndpoints = false,
} = deps;
const envAllowlist = parseEnvAllowlist(overrideEnvAllowlist);
const emitAudit = createAdminAuditEmitter({
recordAuditEntry,
failClosed: auditFailClosed,
logPrefix: '[adminConfig]',
});
function readStoredConfig(
principalType: PrincipalType,
principalId: string,
): Promise<ConfigRecord | null> {
return findConfigByPrincipal(principalType, principalId, { includeInactive: true });
}
/**
* The partitions a write to the principal's document involves (`WriteScope`). A caller inside
* a tenant reaches only that tenant's documents, and a role's document is always the one in
* the caller's partition. A caller without a tenant addresses group and user documents by id,
* whichever tenant holds them, so the stored document names the partition the write is
* judged in: a profile merges over the Base of its own partition, not the caller's.
*/
async function resolveWriteScope(
principalType: PrincipalType,
principalId: string,
): Promise<WriteScope> {
const activeTenantId = getActivePartition();
if (activeTenantId || principalType === PrincipalType.ROLE) {
return { tenantId: activeTenantId, activeTenantId };
}
const stored = await readStoredConfig(principalType, principalId);
return { tenantId: stored ? getConfigPartition(stored) : undefined, activeTenantId };
}
/** The write's scope and librechat.yaml as the partition it is judged in resolves it. */
async function loadWriteScope(
principalType: PrincipalType,
principalId: string,
): Promise<{ scope: WriteScope; baseConfig: AppConfig | undefined }> {
const scope = await resolveWriteScope(principalType, principalId);
return { scope, baseConfig: await getBaseAppConfig(scope.tenantId) };
}
/**
* Reads the document a write plans from, in the partition the write is judged in: the stored
* document's own, or the caller's for a document the write would create. A document that no
* longer lands there (removed and created again in another partition since the scope was
* resolved) answers a revision conflict rather than being judged on another partition's Base.
*/
async function readScopedConfig(
principalType: PrincipalType,
principalId: string,
scope: WriteScope,
): Promise<ConfigRecord | null> {
const stored = await readStoredConfig(principalType, principalId);
const partition = stored ? getConfigPartition(stored) : scope.activeTenantId;
if (partition !== scope.tenantId) {
throw new ConfigRevisionConflictError(stored ? getConfigRevision(stored) : null);
}
return stored;
}
/**
* Clears the caches a write affects before the response goes out, so the caller's next read
* sees the write. A failure is logged, not surfaced: the write itself has committed.
*/
async function invalidateCaches(tenantId: string | undefined, operation: string): Promise<void> {
try {
await invalidateConfigCaches?.(tenantId);
} catch (error) {
logger.error(
`[adminConfig] Cache invalidation failed after ${operation}:`,
getSafeErrorMetadata(error),
);
}
}
/**
* 200 for a write with nothing to apply, reporting the stored revision and, for a field write,
* the parts it skipped and the stored document as a read under `access` shows it (`null` when
* there is none). The precondition still holds: a document that is not at `expectedRevision`
* answers 409, as the write would.
*/
async function noopResponse(
res: Response,
message: string,
principalType: PrincipalType,
principalId: string,
expectedRevision: ConfigRevision | undefined,
report?: { skipped: readonly SkippedPart[]; access: ReadableSections },
): Promise<Response> {
const stored = await readStoredConfig(principalType, principalId);
const revision = stored ? getConfigRevision(stored) : null;
if (expectedRevision && expectedRevision !== getExpectedRevision(stored)) {
return conflictResponse(res, revision, principalType, principalId);
}
return res.status(200).json({
message,
revision,
...(report && {
config: stored ? toWrittenConfig(stored, report.access) : null,
...toWriteReport([], report.skipped),
}),
});
}
async function conflictResponse(
res: Response,
knownRevision: ConfigRevision | null | undefined,
principalType: PrincipalType,
principalId: string,
): Promise<Response> {
let currentRevision = knownRevision;
if (currentRevision === undefined) {
const stored = await readStoredConfig(principalType, principalId);
currentRevision = stored ? getConfigRevision(stored) : null;
}
return res.status(409).json({
error: 'Config was modified by another request',
code: 'CONFIG_VERSION_CONFLICT',
currentRevision,
});
}
/**
* Maps the expected failures of a write to their responses; anything else is rethrown. A
* conflict that does not carry the current revision rereads it from the document the write
* addressed (for a role, in the caller's tenant partition).
*/
async function writeFailureResponse(
res: Response,
error: unknown,
principalType: PrincipalType,
principalId: string,
): Promise<Response> {
if (isConfigRevisionConflict(error)) {
return conflictResponse(res, error.currentRevision, principalType, principalId);
}
if (isConfigPathError(error)) {
return invalidPathResponse(res, error);
}
throw error;
}
/**
* Unsets or tombstones a path (a dot-free secret together with its preview) in a write
* planned from the document it replaces, so each check judges exactly the revision the write
* lands on: a tombstone that creates the principal's first document needs the principal
* (`canCreateFor`), and a removal that changes where a stored credential is sent needs it
* entered again, as a write would: a web search URL beside a stored key, an Azure group's
* destination beside its stored key, or a field of an MCP server that keeps a stored credential
* (judged over librechat.yaml as the document's partition resolves it, as on every write). A
* write that lands in between is re-read and re-checked, or answers 409 under
* `expectedRevision`. An unset stops when there is no document. `loadedBase` is the base config
* the caller already read, if any.
*/
async function removeConfigPath(
principalType: PrincipalType,
principalId: string,
target: FieldTarget,
removal: { tombstone: true; priority?: number } | { tombstone: false },
expectedRevision: ConfigRevision | undefined,
scope: WriteScope,
loadedBase?: AppConfig,
): Promise<ConfigMutationOutcome<RemovalStop>> {
const paths = getRemovalPaths(target);
const needsBase =
MCP_SECTIONS.has(target.segments[0]) ||
isAzureGroupPath(target.segments) ||
isBoundKeyPath(target.segments);
const baseConfig = needsBase
? (loadedBase ?? (await getBaseAppConfig(scope.tenantId)))
: undefined;
const base: Partial<TCustomConfig> = baseConfig?.config ?? {};
return runConfigMutation<RemovalStop>(
{
read: () => readScopedConfig(principalType, principalId, scope),
write: (draft, revision) =>
writeConfigDocument(principalType, principalId, draft, revision),
},
async (stored) => {
if (!stored && !removal.tombstone) {
return { draft: null, result: { status: 404, missing: 'config' } };
}
if (!stored && !(await canCreateFor(principalType, principalId))) {
return { draft: null, result: { status: 404, missing: 'principal' } };
}
const current = toConfigOverrideState(stored);
const state = removal.tombstone
? tombstoneConfigPaths(current, paths)
: unsetConfigPaths(current, paths);
const reentry = getKeptKeyReentryIssues(stored, state, NO_ENTERED_SECRETS, baseConfig);
if (reentry.length > 0) {
return { draft: null, result: { status: 400, reentry } };
}
const mcpReentry = findSecretReentry({
stored,
candidate: state,
base,
entered: NO_ENTERED_SECRETS,
});
if (mcpReentry) {
return { draft: null, result: { status: 400, mcpReentry } };
}
const bound = bindSecretDestinations({
stored,
candidate: state,
entered: NO_ENTERED_SECRETS,
});
return {
draft: {
principalModel: stored?.principalModel ?? principalModel(principalType),
priority:
(removal.tombstone ? removal.priority : undefined) ??
stored?.priority ??
getDefaultConfigPriority({ principalType, principalId }),
overrides: bound.overrides,
tombstones: bound.tombstones,
isActive: stored?.isActive ?? true,
},
};
},
{ expectedRevision },
);
}
/**
* The deployment's resolved `librechat.yaml` config. Its raw `config` is what overrides are
* validated on top of, and what decides which env names they may reference.
*/
async function getBaseAppConfig(tenantId?: string): Promise<AppConfig | undefined> {
if (!getAppConfig) {
return undefined;
}
return getAppConfig({ tenantId, baseOnly: true });
}
function getEnvPolicy(baseYaml: Partial<TCustomConfig>): EnvReferencePolicy {
return createEnvReferencePolicy({ config: baseYaml, allowlist: envAllowlist });
}
/**
* The secrets the written document's layer drops at merge (`app/rebinding.ts`): inherited ones
* it sends somewhere new, and its own whose destination a layer below changed. Judged on the
* Base floor: librechat.yaml, then the active Base profile (for any other principal; Base
* always merges first), then this document. A user or group can have other profiles in
* between, so this is what the document does over the floor. PUT, PATCH and change batches
* report it (a dry run for the document it plans) on the Base their write was last judged on
* (`base`), and field removals and tombstones in a section with bound secrets read it, in the
* partition the document merges in (`tenantId`); the base config is loaded only when the
* document overrides or tombstones such a section. A failure is logged and reports nothing:
* the write itself has committed.
*/
async function reportIgnored(
written: ConfigOverrideLayer,
tenantId: string | undefined,
loaded?: {
baseConfig: AppConfig | undefined;
envPolicy: EnvReferencePolicy;
base?: ConfigRecord | null;
},
): Promise<AdminConfigIgnoredSecret[]> {
if (!touchesBoundSecretSections(written)) {
return [];
}
try {
const baseConfig = loaded ? loaded.baseConfig : await getBaseAppConfig(tenantId);
if (!baseConfig) {
return [];
}
const envPolicy = loaded?.envPolicy ?? getEnvPolicy(baseConfig.config ?? {});
const writtenId = written.principalId?.toString();
const isBase = isBaseConfigPrincipal(written);
let floor: ConfigRecord | null = null;
if (!isBase) {
floor = loaded?.base !== undefined ? loaded.base : await readActiveBase(tenantId);
}
const ignored: AdminConfigIgnoredSecret[] = [];
mergeOverrideLayers(baseConfig, floor ? [floor, written] : [written], {
envPolicy,
rederiveEndpoints,
onRebinding: (rebinding) => {
if (
rebinding.layer.principalType === written.principalType &&
rebinding.layer.principalId?.toString() === writtenId
) {
ignored.push(toIgnoredSecretOverride(rebinding));
}
},
});
return ignored;
} catch (error) {
logger.error(
'[adminConfig] Failed to report ignored overrides:',
getSafeErrorMetadata(error),
);
return [];
}
}
/**
* librechat.yaml and, for any principal but Base, the active Base document of one partition,
* to judge a stored document on (`reportStoredIgnored`). A read that fails is logged and comes
* back `undefined`, so the document reads without the report rather than with a wrong one.
*/
function loadJudgement(
tenantId: string | undefined,
isBase: boolean,
): Promise<[AppConfig | undefined, ConfigRecord | null | undefined]> {
return Promise.all([
getBaseAppConfig(tenantId).catch((error: unknown) => {
logger.error(
'[adminConfig] getConfig could not load the base config to judge the document:',
getSafeErrorMetadata(error),
);
return undefined;
}),
isBase
? null
: readActiveBase(tenantId).catch((error: unknown) => {
logger.error(
'[adminConfig] getConfig could not read the Base document to judge the document:',
getSafeErrorMetadata(error),
);
return undefined;
}),
]);
}
/**
* What the merge leaves out of a stored document's layer (`getIgnoredConfigOverrides`): parts
* no merge applies, values set back to librechat.yaml's, values invalid where the merge applies
* them, and the credentials it drops (`reportIgnored`), judged over librechat.yaml and, for any
* principal but Base, the active Base document (`base`). `null` when there is no base config to
* judge on or the judgement fails, which a read reports by leaving `ignored` out rather than
* claiming nothing is ignored.
*/
async function reportStoredIgnored(
stored: ConfigRecord,
tenantId: string | undefined,
baseConfig: AppConfig | undefined,
base: ConfigRecord | null,
): Promise<Array<AdminConfigIgnoredOverride | AdminConfigIgnoredSecret> | null> {
if (!baseConfig) {
return null;
}
try {
const baseYaml: Partial<TCustomConfig> = baseConfig.config ?? {};
const overrides = getIgnoredConfigOverrides(
baseYaml,
stored,
base ? [base] : [],
baseConfig,
{ expandCustomEndpoint, rederiveEndpoints },
);
const secrets = await reportIgnored(stored, tenantId, {
baseConfig,
envPolicy: getEnvPolicy(baseYaml),
base,
});
return [...overrides, ...secrets];
} catch (error) {
logger.error(
'[adminConfig] Failed to judge what a stored config leaves out:',
getSafeErrorMetadata(error),
);
return null;
}
}
/**
* Binds the keys a planned document holds to the destinations they were entered for
* (`bindSecretDestinations`): a key the request entered, to where the merge sends it over the
* active Base when that is not where librechat.yaml and the document alone send it, as the
* rebinding guard reports it (`SecretRebinding.binding`); a key it kept, to what is stored
* beside it. A profile can then enter its own key for an endpoint, server or service Base
* defines without restating the destination, and the key is dropped again once Base, or any
* layer below the profile, moves that destination. Base merges first, so nothing moves its
* keys from below. Destinations are judged as with `CONFIG_REDERIVE_ENDPOINTS` on, whatever
* this deployment runs with, so a key entered for an Azure group while the groups are inert
* keeps its destination once they apply.
*/
function bindPlannedSecrets(params: {
principalType: PrincipalType;
principalId: string;
stored: ConfigRecord | null;
candidate: ConfigOverrideState;
entered: ReadonlySet<string>;
base: ConfigRecord | null;
baseConfig: AppConfig | undefined;
envPolicy: EnvReferencePolicy;
}): ConfigOverrideState {
const { principalType, principalId, stored, candidate, entered, base } = params;
const kept = bindSecretDestinations({ stored, candidate, entered });
if (
base == null ||
isBaseConfigPrincipal({ principalType, principalId }) ||
!entersBoundSecret(kept, entered)
) {
return kept;
}
const destinations = new Map<string, string>();
const layer: ConfigOverrideLayer = {
principalType,
principalId,
priority: getDefaultConfigPriority({ principalType, principalId }),
overrides: kept.overrides,
tombstones: kept.tombstones,
};
mergeOverrideLayers(params.baseConfig ?? ({} as AppConfig), [base, layer], {
envPolicy: params.envPolicy,
rederiveEndpoints: true,
onRebinding: (rebinding) => {
if (
rebinding.binding != null &&
rebinding.layer.principalType === principalType &&
rebinding.layer.principalId?.toString() === principalId
) {
destinations.set(getRebindingIdentity(rebinding.segments), rebinding.binding);
}
},
});
if (destinations.size === 0) {
return kept;
}
return bindSecretDestinations({ stored, candidate: kept, entered, destinations });
}
/**
* The active Base document of one tenant partition (`undefined`: the deployment's own). The
* config store addresses every role document in the active partition, so another tenant's
* Base is read in that tenant's context; the partition rules themselves stay the store's.
*/
function readActiveBase(tenantId: string | undefined): Promise<ConfigRecord | null> {
return runInPartition(tenantId, () =>
findConfigByPrincipal(PrincipalType.ROLE, BASE_CONFIG_PRINCIPAL_ID),
);
}
/**
* Takes back a write this request made, only while the document is still at the revision the
* write produced: the document it replaced is written back, or the one it created removed. A
* write that landed since throws a revision conflict, and is left as it is.
*/
async function withdrawWrite(
principalType: PrincipalType,
principalId: string,
written: ConfigRecord,
previous: ConfigRecord | null,
): Promise<ConfigRecord | null> {
const revision = getConfigRevision(written);
if (previous) {
return writeConfigDocument(principalType, principalId, toConfigDraft(previous), revision);
}
await deleteConfig(principalType, principalId, undefined, { expectedRevision: revision });
return null;
}
/**
* Reads Base again after a profile write committed and, when it is no longer `read` (the Base
* the write was planned on), judges the request on it. `null` when Base did not move, or when
* that cannot be told: the committed write then stands, as it would had Base moved just after
* it, and is never turned into a failure.
*/
async function judgeOnLandedBase<T>(
tenantId: string | undefined,
read: ConfigRecord | null,
judge: (landed: ConfigRecord | null) => Promise<ConfigMutationPlan<T>>,
): Promise<ConfigMutationPlan<T> | null> {
try {
const landed = await readActiveBase(tenantId);
if ((landed && getConfigRevision(landed)) === (read && getConfigRevision(read))) {
return null;
}
return await judge(landed);
} catch (error) {
logger.warn(
'[adminConfig] A profile write could not be checked on the Base it landed over; it stands',
getSafeErrorMetadata(error),
);
return null;
}
}
/**
* Runs a write that validates on the config the principal's overrides land on, before its own
* tombstones (the floor): `librechat.yaml` with the active Base document resolved over it,
* exactly as the merge layers Base under every profile (Base always merges first), or
* `librechat.yaml` alone for Base itself. The principal's other profiles vary per user and
* are left to the merge. Base is read from the partition the document merges in
* (`scope.tenantId`): the caller's for a role, and for a group or user document a caller
* without a tenant addresses by id, the tenant that holds it, whose Base that profile merges
* over; each attempt reads the document in that partition only (`readScopedConfig`). `yaml` is
* librechat.yaml as that partition resolves it. With `yaml` `null`
* the write does not validate on the floor, and `plan` gets an empty one. `plan` also gets the
* Base document itself (`null` for Base, or when none is active), which binds the keys the
* write enters to the destinations they are sent to over it (`bindPlannedSecrets`).
*
* Base is its own document, which the profile's compare-and-swap does not cover. So each
* attempt reads Base beside the profile (a retry never reuses a Base a concurrent write has
* replaced), and once the write commits Base is read again. When it moved meanwhile, the
* request is judged once more, `plan` on the document the write replaced, on the Base the
* write landed over (`judgeOnLandedBase`): a write still valid there stands, and one that is
* not is withdrawn (`withdrawWrite`) and answered with that judgement.
*
* The outcome carries the Base it was last judged on (`base`, `undefined` when none was
* read), so what the written or planned document drops at merge (`reportIgnored`) is judged
* on the same Base without reading it again.
*/
async function runOnValidationFloor<T>(
principalType: PrincipalType,
principalId: string,
scope: WriteScope,
yaml: Partial<TCustomConfig> | null,
plan: (
stored: ConfigRecord | null,
floor: Partial<TCustomConfig>,
base: ConfigRecord | null,
) => Promise<ConfigMutationPlan<T>>,
expectedRevision: ConfigRevision | undefined,
): Promise<FloorOutcome<T>> {
const readsBase = yaml != null && !isBaseConfigPrincipal({ principalType, principalId });
const attempt: { base: ConfigRecord | null } = { base: null };
const floorOver = (base: ConfigRecord | null): Partial<TCustomConfig> => {
if (yaml == null) {
return {};
}
return base ? resolveRawConfig(yaml, [base], getWriteDerivation(yaml)) : yaml;
};
const outcome = await runConfigMutation<T>(
{
read: async () => {
const [stored, base] = await Promise.all([
readScopedConfig(principalType, principalId, scope),
readsBase ? readActiveBase(scope.tenantId) : null,
]);
attempt.base = base;
return stored;
},
write: (draft, revision) =>
writeConfigDocument(principalType, principalId, draft, revision),
},
(stored) => plan(stored, floorOver(attempt.base), attempt.base),
{ expectedRevision },
);
if (!readsBase) {
return outcome;
}
if (!outcome.written) {
return { ...outcome, base: attempt.base };
}
const judged = await judgeOnLandedBase(scope.tenantId, attempt.base, (landed) => {
attempt.base = landed;
return plan(outcome.previous, floorOver(landed), landed);
});
if (judged == null || judged.draft != null) {
return { ...outcome, base: attempt.base };
}
const current = await withdrawWrite(
principalType,
principalId,
outcome.record,
outcome.previous,
);
await invalidateCaches(scope.activeTenantId, 'withdrawn write');
return { written: false, current, result: judged.result, base: attempt.base };
}
/**
* Whether a write may create the principal's first document: it must exist in the caller's
* tenant partition. Base always may, and nothing is checked without `principalExists`.
*/
async function canCreateFor(principalType: PrincipalType, principalId: string): Promise<boolean> {
if (!principalExists || isBaseConfigPrincipal({ principalType, principalId })) {
return true;
}
return principalExists(principalType, principalId);
}
/**
* Resolves which sections a write's response may show: the ones the caller can read. Those
* already include each section it manages, because the grant layer resolves
* `read:configs:<section>` from the same section's `manage:configs:<section>`, so a GET shows a
* section manager that whole section. The written sections are added anyway, so the reply
* always carries what was stored. It covers every schema section in one batched lookup, so it
* runs alongside the write's other pre-reads, and a failed lookup fails the request before
* anything is stored instead of turning a committed write into a 500. Broad managers can read
* every section and skip it.
*/
async function resolveWriteReadAccess(
user: CapabilityUser,
hasBroadManage: boolean,
managedSections: readonly string[],
): Promise<ReadableSections> {
if (hasBroadManage) {
return FULL_READ_ACCESS;
}
const readable = await getReadableConfigSections(user, CONFIG_SCHEMA_SECTIONS);
return {
broad: readable.broad,
sections: new Set([...readable.sections, ...managedSections]),
};
}
/**
* GET / — List all active config overrides.
*/
async function listConfigs(req: ServerRequest, res: Response): Promise<Response> {
try {
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
return forbiddenResponse(res);
}
const configs = await listAllConfigs();
const sections = [...new Set(configs.flatMap(collectConfigSections))] as ConfigSection[];
const readable = await getReadableConfigSections(user, sections);
const filtered = configs.map((config) => filterConfigDocForReadAccess(config, readable));
const safeConfigs = filtered.map(redactConfigForResponse);
return res.status(200).json({ configs: safeConfigs });
} catch (error) {
logger.error('[adminConfig] listConfigs error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to list configs' });
}
}
/**
* GET /meta — The contract this server applies to config writes: feature flags, limits,
* versions and the rules a client mirrors. An older server answers 404, which a client reads
* as every feature off.
*/
async function getConfigMeta(req: ServerRequest, res: Response): Promise<Response> {
try {
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
return forbiddenResponse(res);
}
const baseConfig = await getBaseAppConfig(user.tenantId);
const meta = buildAdminConfigMeta(
{
maxPatchEntries: MAX_PATCH_ENTRIES,
maxChangeOps: MAX_CONFIG_CHANGE_OPS,
maxEntryKeyLength: MAX_CONFIG_ENTRY_KEY_LENGTH,
overrideCacheTtlMs,
catalogModelsTtlMs: getCatalogModelsTtlMs(baseConfig),
},
{ rederiveEndpoints },
);
return res.status(200).json(meta);
} catch (error) {
logger.error('[adminConfig] getConfigMeta error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to get config meta' });
}
}
/**
* GET /base — Return the raw AppConfig (YAML + DB base merged).
* This is the full config structure admins can edit, NOT the startup payload.
*/
async function getBaseConfig(req: ServerRequest, res: Response): Promise<Response> {
try {
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (!getAppConfig) {
return res.status(501).json({ error: 'Base config endpoint not configured' });
}
if (!(await hasAnyConfigReadAccess(user))) {
return forbiddenResponse(res);
}
const baseOnly = (req.query as Record<string, unknown>).baseOnly === 'true';
const [appConfig, yamlConfig] = await Promise.all([
getAppConfig({ tenantId: user.tenantId, baseOnly, bypassOverrideCache: true }),
baseOnly ? undefined : getAppConfig({ tenantId: user.tenantId, baseOnly: true }),
]);
const sections = collectAppConfigSections(appConfig) as ConfigSection[];
const readable = await getReadableConfigSections(user, sections);
const filteredAppConfig = filterAppConfigForReadAccess(appConfig, readable);
return res
.status(200)
.json({ config: redactAppConfigForResponse(filteredAppConfig, yamlConfig) });
} catch (error) {
logger.error('[adminConfig] getBaseConfig error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to get base config' });
}
}
/**
* GET /:principalType/:principalId — Get config for a specific principal.
*/
async function getConfig(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (!(await hasAnyConfigReadAccess(user))) {
return forbiddenResponse(res);
}
const isBase = isBaseConfigPrincipal({ principalType, principalId });
/**
* The document is judged in the partition it merges in, as writes judge it: the caller's,
* read beside the document, or, for a group or user document a caller without a tenant
* reads from a tenant, that tenant's, read once the document names it.
*/
const activePartition = getActivePartition();
const [config, judgedInActive] = await Promise.all([
findConfigByPrincipal(principalType, principalId, { includeInactive: true }),
loadJudgement(activePartition, isBase),
]);
if (!config) {
return configNotFoundResponse(res);
}
const partition = getConfigPartition(config);
const [baseConfig, base] =
partition === activePartition ? judgedInActive : await loadJudgement(partition, isBase);
const sections = collectConfigSections(config) as ConfigSection[];
const readable = await getReadableConfigSections(user, sections);
const filteredConfig = filterConfigDocForReadAccess(config, readable);
const ignored =
base === undefined ? null : await reportStoredIgnored(config, partition, baseConfig, base);
return res.status(200).json({
config: redactConfigForResponse(filteredConfig),
...(ignored && {
ignored: ignored.filter(({ segments }) => canReadSection(readable, segments[0] ?? '')),
ignoredBasis: isBase ? 'yaml' : 'base',
}),
});
} catch (error) {
logger.error('[adminConfig] getConfig error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to get config' });
}
}
/**
* PUT /:principalType/:principalId — Replace entire overrides for a principal.
*/
async function upsertConfigOverrides(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const { overrides, priority } = req.body as {
overrides?: Partial<TCustomConfig>;
priority?: number;
};
if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
return errorResponse(res, 400, 'INVALID_OVERRIDES', 'overrides must be a plain object');
}
const expected = readExpectedRevision(
(req.body as { expectedRevision?: unknown }).expectedRevision,
);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const renames = readRenames((req.body as { renames?: unknown }).renames);
if (!renames.ok) {
return invalidRenameResponse(res, renames.reason);
}
const rawOverrides = overrides as Record<string, unknown>;
if (hasProcessMCPServerConfig(rawOverrides.mcpServers)) {
return errorResponse(res, 400, 'PROCESS_MCP_CONFIG', PROCESS_MCP_CONFIG_ERROR);
}
if (hasLangfuseHeadersOverride(rawOverrides)) {
return errorResponse(res, 400, 'LANGFUSE_HEADERS_CONFIG', LANGFUSE_HEADERS_CONFIG_ERROR);
}
if (priority != null && !isValidPriority(priority)) {
return invalidPriorityResponse(res);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const hasAssignConfigs =
hasBroadManage ||
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!hasAssignConfigs) {
return forbiddenResponse(res);
}
/**
* Checked before any section rule or secret encryption reads a dotted key as a path. A
* dotted key is a section write, which only broad manage may make.
*/
const dottedSectionIssues = getDottedSectionIssues(rawOverrides);
if (dottedSectionIssues.length > 0) {
return hasBroadManage
? invalidOverrideResponse(res, dottedSectionIssues)
: forbiddenResponse(res);
}
/** What the API never stores is cut out section by section, and reported as skipped. */
const skipped: SkippedPart[] = [];
const filteredOverrides: Record<string, unknown> = {};
for (const [section, value] of Object.entries(rawOverrides)) {
const skipReason = getFieldSkipReason(section) ?? getHeldPathSkipReason([section]);
if (skipReason) {
skipped.push({ segments: [section], reason: skipReason });
continue;
}
const filtered = filterWrittenValue([section], value);
skipped.push(...filtered.skipped);
if (!filtered.emptied) {
defineKey(filteredOverrides, section, filtered.value);
}
}
/** A create-only request is a lifecycle write even when it carries nothing. */
const createOnly = expected.value === ABSENT_CONFIG_REVISION;
const noopReport = {
skipped,
access: hasBroadManage ? FULL_READ_ACCESS : NO_READ_ACCESS,
};
if (Object.keys(filteredOverrides).length === 0 && priority == null && !createOnly) {
logSkippedParts('Stripping', skipped);
return noopResponse(
res,
'No actionable override sections provided',
principalType,
principalId,
expected.value,
noopReport,
);
}
if (Object.keys(filteredOverrides).length > 0 && !hasBroadManage) {
return forbiddenResponse(res);
}
if (priority != null && !hasBroadManage) {
logger.warn(
`[adminConfig] Ignoring caller-supplied priority on assign-only scope lifecycle upsert to ${principalType}/${principalId}: only broad manage:configs may modify document priority`,
);
}
const scope = await resolveWriteScope(principalType, principalId);
const baseConfig =
Object.keys(filteredOverrides).length > 0
? await getBaseAppConfig(scope.tenantId)
: undefined;
const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
/** A stdio server librechat.yaml runs is left out, so a read written back still succeeds. */
const processes = stripProcessServers(
['mcpServers'],
filteredOverrides.mcpServers,
getProcessServerNames(baseYaml),
);
if (processes.skipped.length > 0) {
skipped.push(...processes.skipped);
if (processes.emptied) {
delete filteredOverrides.mcpServers;
} else {
filteredOverrides.mcpServers = processes.value;
}
}
logSkippedParts('Stripping', skipped);
const overrideSections = Object.keys(filteredOverrides);
if (overrideSections.length === 0 && priority == null && !createOnly) {
return noopResponse(
res,
'No actionable override sections provided',
principalType,
principalId,
expected.value,
noopReport,
);
}
for (const section of getConfigSecretSections()) {
const secretInputError = getConfigSecretInputError(section, filteredOverrides[section]);
if (secretInputError) {
return errorResponse(res, 400, 'SECRET_PATH', secretInputError);
}
}
const envPolicy = getEnvPolicy(baseYaml);
const envIssues = getEnvReferenceIssues(filteredOverrides, envPolicy);
if (envIssues.length > 0) {
return invalidOverrideResponse(res, envIssues);
}
const encryptedOverrides = encryptConfigSecrets(filteredOverrides);
/** What the request itself supplies, before secret preservation fills in what it omits. */
const requestWrites: ConfigFieldWrite[] = [{ segments: [], value: encryptedOverrides }];
const entered = getEnteredConfigSecrets(requestWrites);
/** A write without override sections (create-only or priority-only) validates nothing. */
const yaml = overrideSections.length > 0 ? baseYaml : null;
type PutStop =
| { status: 403 }
| { status: 404 }
| { status: 400; issues: ConfigOverrideIssue[] }
| { status: 400; renameIssue: string }
| { status: 400; reentry: SecretReentryIssue[] }
| { status: 400; mcpReentry: SecretReentry };
let outcome;
try {
outcome = await runOnValidationFloor<PutStop>(
principalType,
principalId,
scope,
yaml,
async (stored, floor, base) => {
if (!stored && !(await canCreateFor(principalType, principalId))) {
return { draft: null, result: { status: 404 } };
}
/** Assign-only callers manage the profile's lifecycle, never its contents. */
if (
!hasBroadManage &&
stored &&
!isConfigOverrideStateEmpty(toConfigOverrideState(stored))
) {
return { draft: null, result: { status: 403 } };
}
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 (a renamed entry's move with it). */
const storedState = renameConfigEntriesTombstones(
toConfigOverrideState(stored),
toEntryRenames(renames.renames),
);
const issues = getConfigOverrideIssues(
preserved,
applyConfigTombstones(floor, storedState.tombstones),
getWriteDerivation(yaml),
);
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(storedState, preserved);
const reentry = getKeptKeyReentryIssues(stored, candidate, entered, baseConfig);
if (reentry.length > 0) {
return { draft: null, result: { status: 400, reentry } };
}
const mcpReentry = findSecretReentry({ stored, candidate, base: baseYaml, entered });
if (mcpReentry) {
return { draft: null, result: { status: 400, mcpReentry } };
}
const next = { ...preserved } as Record<string, unknown>;
if (principalId === BASE_CONFIG_PRINCIPAL_ID) {
for (const section of BASE_PRINCIPAL_OVERRIDE_SECTIONS) {
const storedSection = (stored?.overrides as Record<string, unknown> | undefined)?.[
section
];
if (storedSection !== undefined) {
next[section] = storedSection;
}
}
}
const state = bindPlannedSecrets({
principalType,
principalId,
stored,
candidate: replaceConfigOverrides(storedState, next as Partial<TCustomConfig>),
entered,
base,
baseConfig,
envPolicy,
});
/** An omitted priority keeps the stored one, so a replace never reorders profiles. */
const requestedPriority = hasBroadManage ? priority : undefined;
return {
draft: {
principalModel: principalModel(principalType),
priority:
requestedPriority ??
stored?.priority ??
getDefaultConfigPriority({ principalType, principalId }),
overrides: state.overrides,
tombstones: state.tombstones,
isActive: true,
},
};
},
expected.value,
);
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!outcome.written) {
const stop = outcome.result;
if (stop.status === 403) {
return forbiddenResponse(res);
}
if (stop.status === 404) {
return principalNotFoundResponse(res);
}
if ('renameIssue' in stop) {
return invalidRenameResponse(res, stop.renameIssue);
}
if ('reentry' in stop) {
return secretReentryResponse(res, stop.reentry);
}
if ('mcpReentry' in stop) {
return mcpReentryResponse(res, stop.mcpReentry);
}
return invalidOverrideResponse(res, stop.issues);
}
const { record: config, previous } = outcome;
const created = previous == null;
await invalidateCaches(user.tenantId, 'upsert');
await emitAudit(req, {
action: created ? 'config.created' : 'config.updated',
target: configTarget(principalType, principalId),
metadata: {
operation: 'replace',
sections: overrideSections.join(','),
priority: config.priority,
...(renames.renames.length > 0 && { renames: describeRenames(renames.renames) }),
},
});
return sendWrittenConfig(
res,
created ? 201 : 200,
config,
hasBroadManage ? FULL_READ_ACCESS : NO_READ_ACCESS,
await reportIgnored(config, scope.tenantId, { baseConfig, envPolicy, base: outcome.base }),
toWriteReport(
overrideSections.map((section) => [section]),
skipped,
),
);
} catch (error) {
if (isFieldNameRejection(error)) {
return unstorableKeyResponse(res, 'upsertConfigOverrides');
}
logger.error('[adminConfig] upsertConfigOverrides error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to upsert config' });
}
}
/**
* PATCH /:principalType/:principalId/fields — Set individual fields via dot-paths.
*
* A `fieldPath` (here, and for tombstones and unsets) is split on dots, so it cannot address
* a record key that holds one, such as a Bedrock inference profile or a `gpt-4.1` model
* entry: write that record whole at its own path (`endpoints.bedrock.inferenceProfiles`).
*/
async function patchConfigField(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const { entries, priority } = req.body as {
entries?: Array<{ fieldPath?: unknown; segments?: unknown; value: unknown } | null>;
priority?: number;
};
if (priority != null && !isValidPriority(priority)) {
return invalidPriorityResponse(res);
}
const expected = readExpectedRevision(
(req.body as { expectedRevision?: unknown }).expectedRevision,
);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const renames = readRenames((req.body as { renames?: unknown }).renames);
if (!renames.ok) {
return invalidRenameResponse(res, renames.reason);
}
if (!Array.isArray(entries) || entries.length === 0) {
return errorResponse(
res,
400,
'ENTRIES_REQUIRED',
'entries array is required and must not be empty',
);
}
if (entries.length > MAX_PATCH_ENTRIES) {
return errorResponse(
res,
400,
'PATCH_TOO_LARGE',
`entries array exceeds maximum of ${MAX_PATCH_ENTRIES}`,
);
}
const targets: Array<{ target: FieldTarget; value: unknown }> = [];
/**
* Every entry's section, a skipped entry's included: the caller must manage each section it
* names, as on `/changes` and the tombstone route, and a write there that the API skips
* answers 200 with the report.
*/
const sections = new Set<string>();
for (const entry of entries) {
const read = readFieldTarget(entry?.fieldPath, entry?.segments);
if (!read.ok) {
return fieldTargetErrorResponse(res, read);
}
if (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);
}
const value = entry?.value;
const guardError = getFieldWriteError(read.target.fieldPath, value);
if (guardError) {
return errorResponse(res, 400, guardError.code, guardError.error);
}
sections.add(section);
targets.push({ target: read.target, value });
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
/**
* What the API never stores is cut out entry by entry and reported as skipped. An entry
* whose whole value is cut out resets its path (`reset`), as a whole value replaces what
* is stored there; every entry applies in request order.
*/
const skipped: SkippedPart[] = [];
/** The entries that change the document, in request order. */
let ordered: Array<{ target: FieldTarget; value: unknown; reset: boolean }> = [];
for (const { target, value } of targets) {
const skipReason =
getFieldSkipReason(target.fieldPath) ?? getHeldPathSkipReason(target.segments);
if (skipReason) {
skipped.push({ segments: [...target.segments], reason: skipReason });
continue;
}
const filtered = filterWrittenValue(
target.segments,
normalizeInterfaceFieldPatch(target.fieldPath, value),
);
skipped.push(...filtered.skipped);
ordered.push({ target, value: filtered.value, reset: filtered.emptied });
}
const actionable = ordered.map(({ target }) => target);
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const managedSections = [...sections];
if (!hasBroadManage) {
const allowed = await Promise.all(
managedSections.map((s) => hasConfigCapability(user, s as ConfigSection, 'manage')),
);
const denied = managedSections.find((_, i) => !allowed[i]);
if (denied) {
return forbiddenSectionResponse(res, denied);
}
}
if (ordered.length === 0) {
logSkippedParts('Stripping', skipped);
return noopResponse(
res,
'No actionable field entries provided',
principalType,
principalId,
expected.value,
{ skipped, access: await resolveWriteReadAccess(user, hasBroadManage, managedSections) },
);
}
const seenTargets = new Set<string>();
for (const target of actionable) {
const key = target.dotFree ? target.fieldPath : JSON.stringify(target.segments);
if (seenTargets.has(key)) {
return errorResponse(
res,
400,
'DUPLICATE_FIELD_PATH',
target.dotFree
? `Duplicate fieldPath: ${target.fieldPath}`
: 'Duplicate field path segments',
);
}
seenTargets.add(key);
}
if (priority != null && !hasBroadManage) {
logger.warn(
`[adminConfig] Ignoring caller-supplied priority on section-scoped patch to ${principalType}/${principalId}: only broad manage:configs may modify document priority`,
);
}
const requestedPriority = hasBroadManage ? priority : undefined;
const [{ scope, baseConfig }, access] = await Promise.all([
loadWriteScope(principalType, principalId),
resolveWriteReadAccess(user, hasBroadManage, managedSections),
]);
const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
/**
* librechat.yaml's stdio servers are shared processes no override changes: a write inside
* one is refused, and one in a whole `mcpServers` value is left out (and reported).
*/
const processServers = getProcessServerNames(baseYaml);
if (actionable.some((target) => isProcessServerPath(target.segments, processServers))) {
return processServerOverrideResponse(res);
}
ordered = ordered.map((entry) => {
if (entry.reset) {
return entry;
}
const filtered = stripProcessServers(entry.target.segments, entry.value, processServers);
skipped.push(...filtered.skipped);
return { target: entry.target, value: filtered.value, reset: filtered.emptied };
});
logSkippedParts('Stripping', skipped);
const validEntries = ordered.filter(({ reset }) => !reset);
const hasResets = validEntries.length < ordered.length;
const fields: Record<string, unknown> = {};
for (const { target, value } of validEntries) {
if (target.dotFree) {
fields[target.fieldPath] = value;
}
}
const envPolicy = getEnvPolicy(baseYaml);
const envIssues = validEntries.flatMap(({ target, value }) =>
getEnvReferenceIssues(value, envPolicy, target.segments),
);
if (envIssues.length > 0) {
return invalidOverrideResponse(res, envIssues);
}
const encryptedFields = encryptConfigSecretFields(fields);
/** What the request itself supplies, before secret preservation fills in what it omits. */
const requestWrites = toOrderedWrites(validEntries, encryptedFields);
const entered = getEnteredConfigSecrets(requestWrites);
type PatchStop =
| { status: 404 }
| { status: 400; issues: ConfigOverrideIssue[] }
| { status: 400; renameIssue: string }
| { status: 400; reentry: SecretReentryIssue[] }
| { status: 400; mcpReentry: SecretReentry };
let outcome;
try {
outcome = await runOnValidationFloor<PatchStop>(
principalType,
principalId,
scope,
baseYaml,
async (stored, floor, base) => {
if (!stored && !(await canCreateFor(principalType, principalId))) {
return { draft: null, result: { status: 404 } };
}
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 preservedFields = preservePatchedConfigSecretFields(
encryptedFields,
stored?.overrides,
);
for (const [fieldPath, value] of Object.entries(preservedFields)) {
if (isConfigSecretPreservablePatch(fieldPath, value)) {
carryRenamedConfigSecrets(value, stored?.overrides, renames.renames, fieldPath);
}
}
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, entryRenames, getWriteDerivation(baseYaml))
: getConfigFieldIssues(
writes,
floor,
stored,
entryRenames,
getWriteDerivation(baseYaml),
);
if (fieldIssues.length > 0) {
return { draft: null, result: { status: 400, issues: fieldIssues } };
}
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) {
return { draft: null, result: { status: 400, reentry } };
}
const mcpReentry = findSecretReentry({
stored,
candidate: state,
base: baseYaml,
entered,
});
if (mcpReentry) {
return { draft: null, result: { status: 400, mcpReentry } };
}
const bound = bindPlannedSecrets({
principalType,
principalId,
stored,
candidate: state,
entered,
base,
baseConfig,
envPolicy,
});
return {
draft: {
principalModel: principalModel(principalType),
priority:
requestedPriority ??
stored?.priority ??
getDefaultConfigPriority({ principalType, principalId }),
overrides: bound.overrides,
tombstones: bound.tombstones,
isActive: stored?.isActive ?? true,
},
};
},
expected.value,
);
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!outcome.written) {
const stop = outcome.result;
if (stop.status === 404) {
return principalNotFoundResponse(res);
}
if ('renameIssue' in stop) {
return invalidRenameResponse(res, stop.renameIssue);
}
if ('reentry' in stop) {
return secretReentryResponse(res, stop.reentry);
}
if ('mcpReentry' in stop) {
return mcpReentryResponse(res, stop.mcpReentry);
}
return invalidOverrideResponse(res, stop.issues);
}
const { record: config, previous } = outcome;
await invalidateCaches(user.tenantId, 'patch');
await emitAudit(req, {
action: previous == null ? 'config.created' : 'config.updated',
target: configTarget(principalType, principalId),
metadata: {
operation: 'patch',
fieldPaths: actionable.map(describeFieldTarget).join(','),
...(renames.renames.length > 0 && { renames: describeRenames(renames.renames) }),
},
});
return sendWrittenConfig(
res,
200,
config,
access,
await reportIgnored(config, scope.tenantId, { baseConfig, envPolicy, base: outcome.base }),
toWriteReport(
actionable.map((target) => target.segments),
skipped,
),
);
} catch (error) {
if (isFieldNameRejection(error)) {
return unstorableKeyResponse(res, 'patchConfigField');
}
logger.error('[adminConfig] patchConfigField error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to patch config fields' });
}
}
/**
* 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 {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const {
fieldPath: rawFieldPath,
segments,
priority,
} = req.body as {
fieldPath?: unknown;
segments?: unknown;
priority?: number;
};
if (segments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {
return errorResponse(res, 400, 'INVALID_FIELD_PATH', 'fieldPath is required');
}
if (priority != null && !isValidPriority(priority)) {
return invalidPriorityResponse(res);
}
const expected = readExpectedRevision(
(req.body as { expectedRevision?: unknown }).expectedRevision,
);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const read = readFieldTarget(rawFieldPath, segments);
if (!read.ok) {
return fieldTargetErrorResponse(res, read);
}
/** Tombstones are stored as dotted paths, so they cannot name a key that contains a dot. */
if (!read.target.dotFree) {
return fieldTargetErrorResponse(res, {
error: 'A tombstone cannot name a key that contains a dot',
reason: 'dotted_segment',
});
}
const { fieldPath } = read.target;
const section = getTopLevelSection(fieldPath);
if (!isAcceptedOverrideSection(section)) {
return unknownSectionResponse(res);
}
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: INSIDE_ARRAY_TOMBSTONE_ERROR,
reason: 'inside_array',
});
}
const removalError = read.target.entry ? null : getFieldRemovalError(fieldPath);
if (removalError) {
return errorResponse(res, 400, removalError.code, removalError.error);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const [canManageSection, access] = await Promise.all([
hasBroadManage || hasConfigCapability(user, section as ConfigSection, 'manage'),
resolveWriteReadAccess(user, hasBroadManage, [section]),
]);
if (!canManageSection) {
return forbiddenSectionResponse(res, section);
}
const skipReason =
getFieldSkipReason(fieldPath) ?? getHeldPathSkipReason(read.target.segments);
if (skipReason) {
logSkippedField('Ignoring tombstone for', fieldPath, skipReason);
return noopResponse(
res,
'No actionable field path provided',
principalType,
principalId,
expected.value,
{ skipped: [{ segments: [...read.target.segments], reason: skipReason }], access },
);
}
/** A stdio server librechat.yaml runs cannot be hidden, nor can its fields be removed. */
const scope = await resolveWriteScope(principalType, principalId);
const mcpBase = MCP_SECTIONS.has(section)
? await getBaseAppConfig(scope.tenantId)
: undefined;
if (isProcessServerPath(read.target.segments, getProcessServerNames(mcpBase?.config ?? {}))) {
return processServerOverrideResponse(res);
}
if (priority != null && !hasBroadManage) {
logger.warn(
`[adminConfig] Ignoring caller-supplied priority on section-scoped tombstone for ${principalType}/${principalId}: only broad manage:configs may modify document priority`,
);
}
const requestedPriority = hasBroadManage ? priority : undefined;
let outcome: ConfigMutationOutcome<RemovalStop>;
try {
outcome = await removeConfigPath(
principalType,
principalId,
read.target,
{ tombstone: true, priority: requestedPriority },
expected.value,
scope,
mcpBase,
);
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!outcome.written) {
return removalStopResponse(res, outcome.result);
}
const { record: config, previous } = outcome;
await invalidateCaches(user.tenantId, 'field tombstone');
await emitAudit(req, {
action: previous == null ? 'config.created' : 'config.updated',
target: configTarget(principalType, principalId),
metadata: { operation: 'tombstone', fieldPath },
});
const ignored = isBoundSecretSection(parseFieldPath(fieldPath)[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
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' });
}
}
/**
* DELETE /:principalType/:principalId/fields?fieldPath=dotted.path
* (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
* way to drop such a tombstone without deleting the whole document.
*/
async function deleteConfigField(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const { fieldPath: rawFieldPath, segments: rawSegments } = req.query;
if (rawSegments === undefined && (!rawFieldPath || typeof rawFieldPath !== 'string')) {
return errorResponse(
res,
400,
'INVALID_FIELD_PATH',
'fieldPath query parameter is required',
);
}
const expected = readExpectedRevision(req.query.expectedRevision);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const read = readFieldTarget(
rawFieldPath,
rawSegments === undefined ? undefined : readSegmentsQuery(rawSegments),
);
if (!read.ok) {
return fieldTargetErrorResponse(res, read);
}
const { target } = read;
const { fieldPath } = target;
const 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);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const section = getTopLevelSection(fieldPath);
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const [canManageSection, access] = await Promise.all([
hasBroadManage || hasConfigCapability(user, section as ConfigSection, 'manage'),
resolveWriteReadAccess(user, hasBroadManage, [section]),
]);
if (!canManageSection) {
return forbiddenSectionResponse(res, section);
}
const skipReason = getFieldSkipReason(fieldPath);
if (skipReason) {
logSkippedField('Ignoring delete for', fieldPath, skipReason);
return noopResponse(
res,
'No actionable field path provided',
principalType,
principalId,
expected.value,
{ skipped: [{ segments: [...target.segments], reason: skipReason }], access },
);
}
let config: ConfigRecord | null;
try {
if (target.entry || isBoundRemoval(target)) {
const outcome = await removeConfigPath(
principalType,
principalId,
target,
{ tombstone: false },
expected.value,
await resolveWriteScope(principalType, principalId),
);
if (!outcome.written) {
return removalStopResponse(res, outcome.result);
}
config = outcome.record;
} else {
/**
* 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,
getRemovalPaths(target),
undefined,
{ expectedRevision: expected.value },
);
}
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!config) {
return configNotFoundResponse(res);
}
await invalidateCaches(user.tenantId, 'field delete');
await emitAudit(req, {
action: 'config.updated',
target: configTarget(principalType, principalId),
metadata: { operation: 'unset', fieldPath: describeFieldTarget(target) },
});
const ignored = isBoundSecretSection(target.segments[0])
? await reportIgnored(config, getConfigPartition(config))
: [];
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' });
}
}
/**
* POST /:principalType/:principalId/changes — Apply a batch of changes atomically.
*
* Every change is checked before anything is read; then the stored document is read, the
* changes are applied in order as pure transforms (secrets an object omits are kept from the
* document as it stands before each change), the end state is validated on the deployment's
* librechat.yaml without the principal's tombstones, and the result is written with one
* compare-and-swap. Any failure leaves the document as it was.
*/
async function applyChanges(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return res.status(400).json({
error: `Invalid principalType: ${principalType}`,
code: 'INVALID_PRINCIPAL_TYPE',
});
}
const body = (req.body ?? {}) as {
ops?: unknown;
priority?: unknown;
dryRun?: unknown;
expectedRevision?: unknown;
};
const { ops, priority } = body;
if (priority != null && !isValidPriority(priority)) {
return invalidPriorityResponse(res);
}
if (body.dryRun !== undefined && typeof body.dryRun !== 'boolean') {
return res.status(400).json({ error: 'dryRun must be a boolean', code: 'INVALID_DRY_RUN' });
}
const dryRun = body.dryRun === true;
const expected = readExpectedRevision(body.expectedRevision);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
if (!Array.isArray(ops) || ops.length === 0) {
return res
.status(400)
.json({ error: 'ops array is required and must not be empty', code: 'OPS_REQUIRED' });
}
if (ops.length > MAX_CONFIG_CHANGE_OPS) {
return res.status(400).json({
error: `ops array exceeds maximum of ${MAX_CONFIG_CHANGE_OPS}`,
code: 'TOO_MANY_OPS',
});
}
const changes: PreparedChange[] = [];
const skipped: SkippedChange[] = [];
const identities = new Set<string>();
const sections = new Set<string>();
for (let index = 0; index < ops.length; index++) {
const prepared = prepareChange(ops[index], index);
if (!prepared.ok) {
return res.status(400).json(prepared.failure);
}
if (identities.has(prepared.identity)) {
return res.status(400).json({
error: 'Two changes address the same path or entry',
code: 'DUPLICATE_FIELD_PATH',
opIndex: index,
});
}
identities.add(prepared.identity);
sections.add(prepared.section);
skipped.push(...prepared.skipped);
if (prepared.change) {
changes.push(prepared.change);
}
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const managedSections = [...sections];
if (!hasBroadManage) {
const allowed = await Promise.all(
managedSections.map((section) =>
hasConfigCapability(user, section as ConfigSection, 'manage'),
),
);
const denied = managedSections.find((_, i) => !allowed[i]);
if (denied) {
return forbiddenSectionResponse(res, denied);
}
}
if (priority != null && !hasBroadManage) {
logger.warn(
`[adminConfig] Ignoring caller-supplied priority on section-scoped changes to ${principalType}/${principalId}: only broad manage:configs may modify document priority`,
);
}
const requestedPriority = hasBroadManage ? (priority as number | undefined) : undefined;
/** A dry run returns no document, so it resolves no read access: it shows only what it writes. */
const [{ scope, baseConfig }, access] = await Promise.all([
loadWriteScope(principalType, principalId),
dryRun
? toWrittenSectionsAccess(hasBroadManage, managedSections)
: resolveWriteReadAccess(user, hasBroadManage, managedSections),
]);
const baseYaml: Partial<TCustomConfig> = baseConfig?.config ?? {};
const envPolicy = getEnvPolicy(baseYaml);
for (const change of changes) {
if (
change.op === 'rename' &&
(isYamlEntry(baseYaml, change, change.key ?? '') ||
isYamlEntry(baseYaml, change, change.to ?? ''))
) {
return res.status(400).json({
error:
'An entry librechat.yaml defines cannot be renamed, and no entry can take its name',
code: 'CONFIG_ENTRY_INVALID',
reason: 'inherited_entry',
opIndex: change.index,
});
}
}
const yamlHeld = getYamlHeld(baseYaml, baseConfig);
/**
* librechat.yaml's stdio servers are shared processes no override changes: a change inside
* one is refused, and one in a whole `mcpServers` value is left out (and reported). An
* `unset` there is cleanup, as DELETE `/fields` is.
*/
for (let index = 0; index < changes.length; index++) {
const change = changes[index];
if (
SERVER_WRITE_OPS.has(change.op) &&
isProcessServerPath(change.target.segments, yamlHeld.processServers)
) {
return processServerOverrideResponse(res, { opIndex: change.index });
}
const stripped = withoutProcessServers(change, yamlHeld.processServers);
changes[index] = stripped.change;
skipped.push(...stripped.skipped);
}
interface ChangesReport {
applied: AdminConfigChangeRef[];
unchanged: AdminConfigChangeRef[];
ignored: IgnoredChange[];
appliedChanges: PreparedChange[];
/** The document the batch plans, which a dry run reports dropped credentials for. */
planned?: ConfigOverrideState;
}
type ChangesStop =
| { kind: 'principal' }
| { kind: 'issues'; issues: ConfigOverrideIssue[] }
| { kind: 'reentry'; issues: SecretReentryIssue[] }
| { kind: 'mcpReentry'; reentry: SecretReentry }
| { kind: 'change'; failure: ChangeFailure };
type ChangesResult = { report: ChangesReport; stop?: never } | { stop: ChangesStop };
const plan = async (
stored: ConfigRecord | null,
floor: Partial<TCustomConfig>,
base: ConfigRecord | null,
): Promise<ConfigMutationPlan<ChangesResult>> => {
if (!stored && !(await canCreateFor(principalType, principalId))) {
return { draft: null, result: { stop: { kind: 'principal' } } };
}
const report: ChangesReport = {
applied: [],
unchanged: [],
ignored: [],
appliedChanges: [],
};
const appliedSteps: ConfigChange[] = [];
/** Env issues in the values the applied changes sent, by identity, followed through renames. */
let sent: ConfigIdentityStep[][] = [];
let state: ConfigOverrideState = toConfigOverrideState(stored);
for (const change of changes) {
const steps = expandChange(change, state.overrides);
let next = state;
try {
for (const step of steps) {
next = applyConfigChange(next, step);
}
} catch (error) {
if (!isConfigPathError(error) && !isConfigEntryError(error)) {
throw error;
}
const failure: ChangeFailure = {
error: 'Config change cannot be applied to the stored config',
code: (error as ConfigPathError | ConfigEntryError).code,
reason: (error as ConfigPathError | ConfigEntryError).reason,
opIndex: change.index,
};
return { draft: null, result: { stop: { kind: 'change', failure } } };
}
const ref = toChangeRef(change);
if (next === state) {
report.unchanged.push(ref);
continue;
}
appliedSteps.push(...steps);
report.applied.push(ref);
report.appliedChanges.push(change);
if (change.op === 'rename') {
sent = sent.map((path) =>
renameConfigIdentityPath(
path,
change.target.segments,
change.key ?? '',
change.to ?? '',
),
);
}
sent.push(...getSentEnvIssuePaths(change, next, envPolicy));
for (const part of getIgnoredParts(change, yamlHeld)) {
report.ignored.push({ ...ref, ...part });
}
if (!rederiveEndpoints) {
for (const part of getInertGroupParts(change)) {
report.ignored.push({ ...ref, ...part });
}
}
state = next;
}
const storedState = toConfigOverrideState(stored);
const written = getConfigBatchWrittenPaths(appliedSteps, state, storedState);
const envIssues = getBatchEnvIssues(sent, state, written, envPolicy);
if (envIssues.length > 0) {
return { draft: null, result: { stop: { kind: 'issues', issues: envIssues } } };
}
/** Entries of a merged-by-key array are named by key: a write, a removal or a record
* rename that reaches into one by position is refused, since the position can name
* another entry by the time the batch is applied. */
const indexed = getIndexedMergeKeyIssues(
changes
.filter((change) => INDEXED_PATH_OPS.has(change.op))
.map((change) => change.target.segments),
);
if (indexed.length > 0) {
return { draft: null, result: { stop: { kind: 'issues', issues: indexed } } };
}
/** Changes that cancel out (a set, then an unset of its parent) leave nothing to write. */
const documentChanged =
report.applied.length > 0 &&
!(
isSameConfigValue(state.overrides, storedState.overrides) &&
isSameConfigValue(state.tombstones, storedState.tombstones)
);
if (!documentChanged && report.applied.length > 0) {
report.unchanged = [...report.applied, ...report.unchanged].sort(
(left, right) => left.opIndex - right.opIndex,
);
report.applied = [];
report.ignored = [];
report.appliedChanges = [];
}
/** As on PUT, a priority for an existing principal without a document creates one that
* holds it. */
const priorityChanged = requestedPriority != null && requestedPriority !== stored?.priority;
if (!documentChanged && !priorityChanged) {
return { draft: null, result: { report } };
}
let planned = state;
if (documentChanged) {
/**
* Only an unset reaches a section configSchema does not define (`prepareChange` refuses
* every other op there), and it only removes what an older server stored. What it leaves
* of the section is the document's own `unknown_section` issue, which the merge ignores
* and which must not be blamed on the removal.
*/
const attributable = written.filter((segments) => isAcceptedOverrideSection(segments[0]));
const issues = getConfigChangeIssues(
state,
floor,
stored,
attributable,
[],
getWriteDerivation(baseYaml),
);
if (issues.length > 0) {
return { draft: null, result: { stop: { kind: 'issues', issues } } };
}
/** Judged on the values the batch ends up storing: a credential a change kept,
* carried or renamed from the stored document was not entered again. */
const entered = getEnteredChangeSecrets(report.appliedChanges);
const reentry = getKeptKeyReentryIssues(stored, state, entered, baseConfig);
if (reentry.length > 0) {
return { draft: null, result: { stop: { kind: 'reentry', issues: reentry } } };
}
const mcpReentry = findSecretReentry({
stored,
candidate: state,
base: baseYaml,
entered,
});
if (mcpReentry) {
return { draft: null, result: { stop: { kind: 'mcpReentry', reentry: mcpReentry } } };
}
planned = bindPlannedSecrets({
principalType,
principalId,
stored,
candidate: state,
entered,
base,
baseConfig,
envPolicy,
});
}
if (dryRun) {
return { draft: null, result: { report: { ...report, planned } } };
}
return {
draft: {
principalModel: principalModel(principalType),
priority:
requestedPriority ??
stored?.priority ??
getDefaultConfigPriority({ principalType, principalId }),
overrides: planned.overrides,
tombstones: planned.tombstones,
isActive: stored?.isActive ?? true,
},
result: { report },
};
};
let outcome;
try {
outcome = await runOnValidationFloor<ChangesResult>(
principalType,
principalId,
scope,
baseYaml,
plan,
expected.value,
);
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
const result = outcome.result as ChangesResult;
if (result.stop?.kind === 'principal') {
return principalNotFoundResponse(res);
}
if (result.stop?.kind === 'change') {
return res.status(400).json(result.stop.failure);
}
if (result.stop?.kind === 'reentry') {
return secretReentryResponse(res, result.stop.issues);
}
if (result.stop?.kind === 'mcpReentry') {
return mcpReentryResponse(res, result.stop.reentry);
}
if (result.stop) {
return invalidOverrideResponse(res, result.stop.issues, { skipped });
}
const { report } = result;
const config = outcome.written ? outcome.record : outcome.current;
/** What the written (or, on a dry run, planned) document sends somewhere new is dropped. */
const rebound = outcome.written
? outcome.record
: report.planned && {
principalType,
principalId,
priority:
requestedPriority ??
config?.priority ??
getDefaultConfigPriority({ principalType, principalId }),
overrides: report.planned.overrides,
tombstones: report.planned.tombstones,
};
const ignoredSecrets = rebound
? await reportIgnored(rebound, scope.tenantId, {
baseConfig,
envPolicy,
base: outcome.base,
})
: [];
if (outcome.written) {
await invalidateCaches(user.tenantId, 'changes');
const paths = new Map<string, string[]>();
for (const change of report.appliedChanges) {
paths.set(change.op, [...(paths.get(change.op) ?? []), describeChange(change)]);
}
await emitAudit(req, {
action: outcome.previous == null ? 'config.created' : 'config.updated',
target: configTarget(principalType, principalId),
metadata: {
operation: 'batch',
changes: report.applied.length,
priority: outcome.record.priority,
...Object.fromEntries([...paths].map(([op, described]) => [op, described.join(',')])),
},
});
}
return res.status(200).json({
...(dryRun
? {}
: {
config: config ? toWrittenConfig(config, access) : null,
}),
revision: config ? getConfigRevision(config) : null,
written: outcome.written,
dryRun,
applied: report.applied,
skipped,
ignored: [...report.ignored, ...filterIgnoredForReadAccess(ignoredSecrets, access)],
unchanged: report.unchanged,
} satisfies Omit<AdminConfigChangesResponse, 'config'> & { config?: ConfigResponse | null });
} catch (error) {
logger.error('[adminConfig] applyConfigChanges error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to apply config changes' });
}
}
/**
* DELETE /:principalType/:principalId — Delete an entire config override.
*/
async function deleteConfigOverrides(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const expected = readExpectedRevision(req.query.expectedRevision);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const allowed =
hasBroadManage ||
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!allowed) {
return forbiddenResponse(res);
}
let config: ConfigRecord | null;
try {
config = await deleteConfig(principalType, principalId, undefined, {
expectEmpty: !hasBroadManage,
expectedRevision: expected.value,
});
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!config) {
if (!hasBroadManage) {
const exists = await findConfigByPrincipal(principalType, principalId, {
includeInactive: true,
});
if (exists) {
return forbiddenResponse(res);
}
}
return configNotFoundResponse(res);
}
await invalidateCaches(user.tenantId, 'config delete');
await emitAudit(req, {
action: 'config.deleted',
severity: 'warning',
target: configTarget(principalType, principalId),
});
return res.status(200).json({ success: true });
} catch (error) {
logger.error('[adminConfig] deleteConfigOverrides error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to delete config' });
}
}
/**
* PATCH /:principalType/:principalId/priority — Set only the document's priority.
*
* Overrides, tombstones and `isActive` stay as stored, so a priority change never re-sends
* (and so never risks clobbering) a profile's contents. Broad `manage:configs` only, like
* every other priority change. An unchanged priority is not written or audited. Only the
* caller's tenant partition is addressed, so a caller without a tenant reorders a
* platform-level profile and gets 404 for one that only a tenant holds.
*/
async function updateConfigPriority(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return res.status(400).json({
error: `Invalid principalType: ${principalType}`,
code: 'INVALID_PRINCIPAL_TYPE',
});
}
const { priority } = req.body as { priority?: unknown };
if (!isValidPriority(priority)) {
return invalidPriorityResponse(res);
}
const expected = readExpectedRevision(
(req.body as { expectedRevision?: unknown }).expectedRevision,
);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (!(await hasConfigCapability(user, null, 'manage'))) {
return forbiddenResponse(res);
}
if (!setConfigPriority) {
return res.status(501).json({ error: 'Priority updates are not configured' });
}
let updated: ConfigWriteOutcome | null;
try {
updated = await setConfigPriority(principalType, principalId, priority, {
expectedRevision: expected.value,
});
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!updated) {
return configNotFoundResponse(res);
}
const { config, changed } = updated;
if (changed) {
await invalidateCaches(user.tenantId, 'priority');
await emitAudit(req, {
action: 'config.updated',
target: configTarget(principalType, principalId),
metadata: { operation: 'priority', priority: config.priority },
});
}
return res.status(200).json({ config: redactConfigForResponse(config) });
} catch (error) {
logger.error('[adminConfig] updateConfigPriority error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to update config priority' });
}
}
/**
* POST /reload — Reload librechat.yaml on every instance without a config write.
*
* Runs the clear every committed config write runs, for every tenant: this instance drops its
* cached librechat.yaml, its merged configs and its MCP config-source servers. It then loads
* the file again here before answering, so a file the loader refuses is reported (422, with
* the issues' locations) instead of only logged; that instance keeps its last good config, as
* any reload does, and the other instances are not told. Once the file loaded, the clear is
* published to every other instance with Redis, which load the file on their next read. A
* write only logs a failed clear or publish, having committed already; here the reload is the
* whole operation, so the response reports it. An instance that misses the publish keeps its
* cached librechat.yaml, which never expires, so a 503 tells the operator to retry rather than
* wait. Only an admin without a tenant with broad `manage:configs` may reload: the file, the
* MCP servers it defines and the caches dropped belong to every tenant, and a tenant admin
* cannot edit the file.
*/
async function reloadConfig(req: ServerRequest, res: Response): Promise<Response> {
try {
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
if (user.tenantId) {
return errorResponse(
res,
403,
'FORBIDDEN',
'Only an admin without a tenant can reload librechat.yaml',
);
}
if (!(await hasConfigCapability(user, null, 'manage'))) {
return forbiddenResponse(res);
}
if (!reloadConfigCaches) {
return res.status(501).json({ error: 'Config reload is not configured' });
}
const report = await reloadConfigCaches();
const failure = getReloadFailure(report);
if (failure) {
await emitAudit(req, {
action: 'config.reloaded',
outcome: 'failure',
target: RELOAD_AUDIT_TARGET,
metadata: { code: failure.body.code, broadcast: report.broadcast },
});
return res.status(failure.status).json(failure.body);
}
await emitAudit(req, {
action: 'config.reloaded',
target: RELOAD_AUDIT_TARGET,
metadata: { broadcast: report.broadcast },
});
const body: AdminConfigReloadResponse = {
success: true,
broadcast: report.broadcast === 'sent',
};
return res.status(200).json(body);
} catch (error) {
logger.error('[adminConfig] reloadConfig error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to reload config' });
}
}
/**
* PATCH /:principalType/:principalId/active — Toggle isActive.
*/
async function toggleConfig(req: ServerRequest, res: Response): Promise<Response> {
try {
const { principalType, principalId } = req.params as {
principalType: string;
principalId: string;
};
if (!validatePrincipalType(principalType)) {
return invalidPrincipalTypeResponse(res, principalType);
}
const { isActive } = req.body as { isActive?: boolean };
if (typeof isActive !== 'boolean') {
return errorResponse(res, 400, 'INVALID_IS_ACTIVE', 'isActive boolean is required');
}
const expected = readExpectedRevision(
(req.body as { expectedRevision?: unknown }).expectedRevision,
);
if (!expected.ok) {
return invalidExpectedRevisionResponse(res);
}
const user = getCapabilityUser(req);
if (!user) {
return authRequiredResponse(res);
}
const hasBroadManage = await hasConfigCapability(user, null, 'manage');
if (principalId === BASE_CONFIG_PRINCIPAL_ID && !hasBroadManage) {
return forbiddenResponse(res);
}
const allowed =
hasBroadManage ||
(await hasCapability(user, `assign:configs:${principalType}` as SystemCapability));
if (!allowed) {
return forbiddenResponse(res);
}
let toggled: { config: ConfigRecord; changed: boolean } | null;
try {
toggled = await toggleConfigActiveTracked(principalType, principalId, isActive, {
expectEmpty: !hasBroadManage,
expectedRevision: expected.value,
});
} catch (error) {
return await writeFailureResponse(res, error, principalType, principalId);
}
if (!toggled) {
if (!hasBroadManage) {
const exists = await findConfigByPrincipal(principalType, principalId, {
includeInactive: true,
});
if (exists) {
return forbiddenResponse(res);
}
}
return configNotFoundResponse(res);
}
const { config, changed } = toggled;
await invalidateCaches(user.tenantId, 'toggle');
/** A retry that finds the requested state already set changed nothing and is not recorded. */
if (changed) {
await emitAudit(req, {
action: 'config.toggled',
severity: 'warning',
target: configTarget(principalType, principalId),
metadata: { isActive },
});
}
return sendWrittenConfig(
res,
200,
config,
hasBroadManage ? FULL_READ_ACCESS : NO_READ_ACCESS,
);
} catch (error) {
logger.error('[adminConfig] toggleConfig error:', getSafeErrorMetadata(error));
return res.status(500).json({ error: 'Failed to toggle config' });
}
}
return {
listConfigs,
getConfigMeta,
getBaseConfig,
getConfig,
upsertConfigOverrides,
patchConfigField,
tombstoneConfigField,
deleteConfigField,
applyConfigChanges: applyChanges,
deleteConfigOverrides,
toggleConfig,
updateConfigPriority,
reloadConfig,
};
}