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 { createHash } from 'node:crypto';
import {
PrincipalType,
materializeModelSpecEndpoints,
normalizeEndpointName,
setMaxSubagents,
} from 'librechat-data-provider';
import {
logger,
getTenantId,
tenantStorage,
deriveSpecInterface,
SPEC_INTERFACE_FIELDS,
BASE_CONFIG_PRINCIPAL_ID,
SYSTEM_TENANT_ID,
} from '@librechat/data-schemas';
import type {
AppConfig,
SpecInterfaceField,
ConfigOverrideLayer,
ConfigLayerResolution,
AdminConfigLayerIgnored,
} from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
import type { Types } from 'mongoose';
import type { CustomConfigLoadMode, ConfigLoadFailure, ConfigLoadResult } from './loader';
import type { EnvReferencePolicy } from './allowlist';
import type { SecretRebinding } from './rebinding';
import { resolveOverrideLayers, mergeOverrideLayersWithSource } from './overrides';
import { createEnvReferencePolicy, parseEnvAllowlist } from './allowlist';
import { resolveRuntimeConfigSecrets } from '~/admin/secrets';
import { normalizeEndpointReferences } from './references';
import { getSafeErrorMetadata } from '~/utils/errors';
import { getConfigLoadFailure } from './loader';
import { checkAppConfigTheme } from './theme';
const BASE_CONFIG_KEY = '_BASE_';
/** A base-config load: the config it serves, and why it failed when that is the last good one. */
interface BaseConfigLoad {
config: AppConfig;
failure?: ConfigLoadFailure;
}
function hiddenCustomEndpoints(
config: AppConfig,
tenantId?: string,
inherited?: ReadonlySet<string>,
): Set<string> {
const hidden = new Set(inherited);
const custom = config.endpoints?.custom;
const sourceCustom = config.config?.endpoints?.custom;
for (const endpoints of [custom, sourceCustom]) {
for (const endpoint of endpoints ?? []) {
if (endpoint.tenantId && endpoint.tenantId !== tenantId) {
hidden.add(normalizeEndpointName(endpoint.name ?? ''));
}
}
}
for (const endpoint of custom ?? sourceCustom ?? []) {
const name = normalizeEndpointName(endpoint.name ?? '');
if ((!endpoint.tenantId || endpoint.tenantId === tenantId) && !inherited?.has(name)) {
hidden.delete(name);
}
}
return hidden;
}
function scopeEndpointList<T extends { name?: string; tenantId?: string }>(
endpoints: T[] | undefined,
tenantId: string | undefined,
hiddenEndpoints: ReadonlySet<string>,
): T[] | undefined {
if (!endpoints) return endpoints;
const tenantNames = new Set<string>();
const scoped = endpoints.filter((endpoint) => {
const name = normalizeEndpointName(endpoint.name ?? '');
if ((endpoint.tenantId && endpoint.tenantId !== tenantId) || hiddenEndpoints.has(name)) {
return false;
}
if (endpoint.tenantId) tenantNames.add(name);
return true;
});
const selected =
tenantNames.size === 0
? scoped
: scoped.filter(
(endpoint) =>
endpoint.tenantId || !tenantNames.has(normalizeEndpointName(endpoint.name ?? '')),
);
return selected.length === endpoints.length ? endpoints : selected;
}
/** `names` without the hidden endpoints; the same array when it names none. */
function withoutHiddenNames<T extends string>(
names: T[] | undefined,
hiddenEndpoints: ReadonlySet<string>,
): T[] | undefined {
const kept = names?.filter((name) => !hiddenEndpoints.has(normalizeEndpointName(name)));
return kept?.length === names?.length ? names : kept;
}
/**
* An endpoint allow-list (`modelSpecs.addedEndpoints`, `endpoints.agents.allowedProviders`)
* without the hidden endpoints, kept as it is when it names nothing else: an empty list allows
* every endpoint, while names the principal is not served allow none.
*/
function scopeAllowList<T extends string>(
names: T[] | undefined,
hiddenEndpoints: ReadonlySet<string>,
): T[] | undefined {
const kept = withoutHiddenNames(names, hiddenEndpoints);
return kept?.length === 0 ? names : kept;
}
/**
* `specs` without the specs that select a hidden endpoint, and with `addedEndpoints` scoped by
* `scopeAddedEndpoints`. Collapses to `undefined` only when no spec and no added endpoint is left.
*/
function scopeModelSpecs(
specs: AppConfig['modelSpecs'],
hiddenEndpoints: ReadonlySet<string>,
scopeAddedEndpoints: typeof withoutHiddenNames = withoutHiddenNames,
): AppConfig['modelSpecs'] {
if (!specs || hiddenEndpoints.size === 0) {
return specs;
}
const list = specs.list?.filter(
(spec) => !hiddenEndpoints.has(normalizeEndpointName(spec.preset?.endpoint ?? '')),
);
const addedEndpoints = scopeAddedEndpoints(specs.addedEndpoints, hiddenEndpoints);
if (list?.length === specs.list?.length && addedEndpoints === specs.addedEndpoints) {
return specs;
}
if (specs.list?.length && list?.length === 0 && !addedEndpoints?.length) {
return undefined;
}
return { ...specs, list, addedEndpoints };
}
/** Adds the folded name of each entry in `endpoints` that `served` lacks to `hidden`. */
function addUnservedEndpointNames(
endpoints: ReadonlyArray<{ name?: string } | null> | undefined,
served: ReadonlySet<string>,
hidden: Set<string>,
): void {
if (!Array.isArray(endpoints)) {
return;
}
for (const endpoint of endpoints) {
const name = typeof endpoint?.name === 'string' ? normalizeEndpointName(endpoint.name) : '';
if (name !== '' && !served.has(name)) {
hidden.add(name);
}
}
}
/**
* The folded names of the custom endpoints the merge removed: ones librechat.yaml or any applied
* override layer (Base included) defines that the merged config no longer serves.
*/
function getUnservedEndpointNames(
base: AppConfig,
layers: readonly ConfigOverrideLayer[],
merged: AppConfig,
): Set<string> {
const served = new Set(
(merged.endpoints?.custom ?? []).map((endpoint) => normalizeEndpointName(endpoint.name ?? '')),
);
const hidden = new Set<string>();
addUnservedEndpointNames(base.endpoints?.custom, served, hidden);
for (const layer of layers) {
addUnservedEndpointNames(layer.overrides?.endpoints?.custom, served, hidden);
}
return hidden;
}
/** The parts of a config that name endpoints, in the served config and its YAML-shaped resolution alike. */
interface EndpointReferences {
modelSpecs?: AppConfig['modelSpecs'];
endpoints?: { agents?: { allowedProviders?: string[] } };
}
/**
* `config` without its references to the `hidden` endpoints: the model specs that select one,
* and its name in `modelSpecs.addedEndpoints` and `endpoints.agents.allowedProviders`. Unrelated
* added endpoints stay when no spec is left, and an allow-list naming only hidden endpoints stays
* as it is ({@link scopeAllowList}).
*/
function scopeEndpointReferences<T extends EndpointReferences>(
config: T,
hidden: ReadonlySet<string>,
): T {
const agents = config.endpoints?.agents;
const modelSpecs = scopeModelSpecs(config.modelSpecs, hidden, scopeAllowList);
const allowedProviders = scopeAllowList(agents?.allowedProviders, hidden);
const agentsChanged = allowedProviders !== agents?.allowedProviders;
if (modelSpecs === config.modelSpecs && !agentsChanged) {
return config;
}
return {
...config,
...(modelSpecs !== config.modelSpecs && { modelSpecs }),
...(agentsChanged && {
endpoints: { ...config.endpoints, agents: { ...agents, allowedProviders } },
}),
};
}
/**
* `merged` without the references to custom endpoints the merge removed
* ({@link getUnservedEndpointNames}). A profile that hides an endpoint (a keyed
* `endpoints.custom["Name"]` tombstone, or a tombstone of all of them) also hides the model specs
* that select it and its name in `modelSpecs.addedEndpoints` and
* `endpoints.agents.allowedProviders`, rather than offering its principals an endpoint they are
* not served. Only the references are scoped, never the endpoint list, so an endpoint a later
* layer adds back keeps them.
*/
function scopeHiddenEndpointReferences(
base: AppConfig,
layers: readonly ConfigOverrideLayer[],
merged: AppConfig,
): AppConfig {
if (!merged.modelSpecs && !merged.endpoints?.agents?.allowedProviders?.length) {
return merged;
}
return scopeEndpointReferences(merged, getUnservedEndpointNames(base, layers, merged));
}
/** Keep tenant-scoped YAML endpoints out of every other tenant's effective config. */
function scopeCustomEndpoints(
config: AppConfig,
tenantId?: string,
inherited?: ReadonlySet<string>,
): AppConfig {
const hiddenEndpoints = hiddenCustomEndpoints(config, tenantId, inherited);
const custom = config.endpoints?.custom;
const scoped = scopeEndpointList(custom, tenantId, hiddenEndpoints);
const sourceCustom = config.config?.endpoints?.custom;
const scopedSource = scopeEndpointList(sourceCustom, tenantId, hiddenEndpoints);
const modelSpecs = scopeModelSpecs(config.modelSpecs, hiddenEndpoints);
const sourceModelSpecs = scopeModelSpecs(config.config?.modelSpecs, hiddenEndpoints);
if (
scoped === custom &&
scopedSource === sourceCustom &&
modelSpecs === config.modelSpecs &&
sourceModelSpecs === config.config?.modelSpecs
) {
return config;
}
return {
...config,
...(modelSpecs !== config.modelSpecs && { modelSpecs }),
...(scoped !== custom && { endpoints: { ...config.endpoints, custom: scoped } }),
...((scopedSource !== sourceCustom || sourceModelSpecs !== config.config?.modelSpecs) && {
config: {
...config.config,
...(scopedSource !== sourceCustom && {
endpoints: { ...config.config.endpoints, custom: scopedSource },
}),
...(sourceModelSpecs !== config.config?.modelSpecs && { modelSpecs: sourceModelSpecs }),
},
}),
};
}
/** What decides the spec-dependent interface controls: whether specs are served, and added endpoints. */
function getSpecState(modelSpecs: AppConfig['modelSpecs']): string {
const hasSpecs = (modelSpecs?.list?.length ?? 0) > 0;
return `${hasSpecs}:${(modelSpecs?.addedEndpoints?.length ?? 0) > 0}`;
}
/**
* The spec-dependent interface controls a merge may have changed against `base`, whose own are
* already derived for the specs it serves: all of them when the specs served change, else those
* whose final librechat.yaml-shaped value (`explicit`) or served value differs from `base`'s. A
* control a layer sets and a higher layer tombstones is back to librechat.yaml's value in
* `explicit`, but the tombstone removed its served value, so it is derived again too.
*/
function getChangedSpecFields(
base: AppConfig,
merged: AppConfig,
explicit: TCustomConfig['interface'] | undefined,
): SpecInterfaceField[] {
if (getSpecState(base.modelSpecs) !== getSpecState(merged.modelSpecs)) {
return [...SPEC_INTERFACE_FIELDS];
}
const written = base.config?.interface;
return SPEC_INTERFACE_FIELDS.filter(
(field) =>
explicit?.[field] !== written?.[field] ||
merged.interfaceConfig?.[field] !== base.interfaceConfig?.[field],
);
}
/**
* `config` with the interface controls model specs decide (`deriveSpecInterface`) derived for the
* specs it serves, where `explicit` (the librechat.yaml-shaped interface) leaves them unset: the
* `fields` given, all three by default.
*/
function withSpecInterface(
config: AppConfig,
explicit: TCustomConfig['interface'] | undefined,
fields: readonly SpecInterfaceField[] = SPEC_INTERFACE_FIELDS,
): AppConfig {
if (fields.length === 0) {
return config;
}
const interfaceConfig = deriveSpecInterface(config.interfaceConfig, explicit, config.modelSpecs, {
fields,
});
return interfaceConfig === config.interfaceConfig ? config : { ...config, interfaceConfig };
}
/** Re-derive only spec-dependent controls before principal overrides are applied. */
function scopeBaseConfig(config: AppConfig, tenantId?: string): AppConfig {
const scoped = scopeCustomEndpoints(config, tenantId);
if (scoped.modelSpecs === config.modelSpecs) {
return scoped;
}
return withSpecInterface(scoped, scoped.config?.interface);
}
export type AppConfigPrincipal = {
principalType: string;
principalId?: string | Types.ObjectId;
};
/**
* Applies the loader's theme rules to a theme a DB override replaced. Unknown colors are left
* out as they are for the YAML theme; an override theme the client would reject counts as unset,
* so the principal keeps the base theme instead of losing its theme to a bad override.
*/
function checkOverrideTheme(baseConfig: AppConfig, merged: AppConfig): AppConfig {
const baseTheme = baseConfig.interfaceConfig?.theme;
if (merged.interfaceConfig?.theme === baseTheme) {
return merged;
}
const { appConfig, errors, warnings } = checkAppConfigTheme(merged);
if (warnings.length > 0) {
logger.warn(
'[getAppConfig] interface.theme from a config override names tokens this version ignores:\n' +
warnings.map((warning) => `- ${warning}`).join('\n'),
);
}
if (errors.length === 0) {
return appConfig;
}
logger.warn(
'[getAppConfig] Ignoring interface.theme from a config override; the base theme applies instead:\n' +
errors.map((error) => `- ${error}`).join('\n'),
);
return { ...merged, interfaceConfig: { ...merged.interfaceConfig, theme: baseTheme } };
}
function toLayerIgnored(
segments: string[],
reason: AdminConfigLayerIgnored['reason'],
): AdminConfigLayerIgnored {
return { path: segments.join('.'), segments, reason };
}
function asList(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
function entryName(value: unknown, field: string): string | undefined {
const name =
value != null && typeof value === 'object' ? (value as Record<string, unknown>)[field] : null;
return typeof name === 'string' ? name : undefined;
}
/**
* A librechat.yaml-shaped resolution with the theme `checkOverrideTheme` set back: when the
* served merge fell back to the base theme because an override's theme fails the client's
* rules, the resolution shows librechat.yaml's theme, and the last layer that wrote one says so.
*/
function replayThemeFallback(
resolved: Partial<TCustomConfig>,
layers: ConfigLayerResolution[],
yaml: Partial<TCustomConfig>,
): Partial<TCustomConfig> {
const writer = [...layers]
.reverse()
.find(({ layer }) => (layer.overrides as Partial<TCustomConfig>)?.interface?.theme != null);
writer?.ignored.push(toLayerIgnored(['interface', 'theme'], 'invalid_theme'));
const { theme: _rejected, ...rest } = resolved.interface ?? {};
const theme = yaml.interface?.theme;
return {
...resolved,
interface: theme === undefined ? rest : { ...rest, theme },
} as Partial<TCustomConfig>;
}
/**
* A librechat.yaml-shaped resolution scoped to the tenant as `scopeCustomEndpoints` scopes the
* served merge: custom endpoints `hidden` names, or another tenant's, are left out, with the
* model specs that use them, and each layer that wrote one of those says so.
*/
function scopeResolvedEndpoints(
resolved: Partial<TCustomConfig>,
layers: ConfigLayerResolution[],
tenantId: string | undefined,
hidden: ReadonlySet<string>,
): Partial<TCustomConfig> {
const custom = resolved.endpoints?.custom;
const scoped = scopeEndpointList(custom, tenantId, hidden);
const modelSpecs = scopeModelSpecs(resolved.modelSpecs as AppConfig['modelSpecs'], hidden);
if (scoped === custom && modelSpecs === resolved.modelSpecs) {
return resolved;
}
const kept = new Set(scoped ?? []);
const removed = new Set(
(custom ?? [])
.filter((endpoint) => !kept.has(endpoint))
.map((endpoint) => normalizeEndpointName(endpoint.name ?? '')),
);
const isHidden = (name: string | undefined) =>
name != null &&
(removed.has(normalizeEndpointName(name)) || hidden.has(normalizeEndpointName(name)));
for (const { layer, ignored } of layers) {
const overrides = layer.overrides as Partial<TCustomConfig> | undefined;
asList(overrides?.endpoints?.custom).forEach((entry, index) => {
if (isHidden(entryName(entry, 'name'))) {
ignored.push(toLayerIgnored(['endpoints', 'custom', String(index)], 'tenant_hidden'));
}
});
asList(overrides?.modelSpecs?.list).forEach((spec, index) => {
const preset = (spec as { preset?: unknown } | null)?.preset;
if (isHidden(entryName(preset, 'endpoint'))) {
ignored.push(toLayerIgnored(['modelSpecs', 'list', String(index)], 'tenant_hidden'));
}
});
}
return {
...resolved,
...(scoped !== custom && { endpoints: { ...resolved.endpoints, custom: scoped } }),
...(modelSpecs !== resolved.modelSpecs && { modelSpecs }),
} as Partial<TCustomConfig>;
}
/**
* Materializes inferable model-spec fields (an omitted `preset.endpoint` for
* agent specs) so every consumer of the effective config reads complete specs.
*/
function materializeConfigModelSpecs(config: AppConfig): AppConfig {
const modelSpecs = materializeModelSpecEndpoints(config.modelSpecs);
if (modelSpecs === config.modelSpecs) {
return config;
}
return { ...config, modelSpecs };
}
/**
* Completes the effective config: inferred spec endpoints, and endpoint references in the
* names the runtime serves. Runs at both assembly points — YAML base load and DB-override
* merge — because override documents contribute specs and references the base never saw.
*/
function completeEffectiveConfig(config: AppConfig): AppConfig {
return normalizeEndpointReferences(materializeConfigModelSpecs(config));
}
export const DEFAULT_OVERRIDE_CACHE_TTL = 60_000;
// ── Types ────────────────────────────────────────────────────────────
interface CacheStore {
get: (key: string) => Promise<unknown>;
set: (key: string, value: unknown, ttl?: number) => Promise<unknown>;
delete: (key: string) => Promise<boolean>;
/** Keyv options — used for key enumeration when clearing override caches. */
opts?: {
store?: {
keys?: () => IterableIterator<string>;
};
};
}
export interface AppConfigServiceDeps {
/** Load the base AppConfig from YAML + AppService processing. */
loadBaseConfig: (mode?: CustomConfigLoadMode) => Promise<AppConfig | undefined>;
/** Synchronous process-wide effects, after tools and the current base config publish. */
onBaseConfigPublished?: (config: AppConfig) => void;
/** Cache tools after base config is loaded. */
setCachedTools: (tools: Record<string, unknown>) => Promise<boolean | void>;
/** Get a cache store by key. */
getCache: (key: string) => CacheStore;
/** The CacheKeys constants from librechat-data-provider. */
cacheKeys: { APP_CONFIG: string };
/** Fetch applicable DB config overrides for a set of principals. */
getApplicableConfigs: (principals?: AppConfigPrincipal[]) => Promise<ConfigOverrideLayer[]>;
/** Resolve full principal list (user + role + groups) from userId/role. */
getUserPrincipals: (params: {
userId: string | Types.ObjectId;
role?: string | null;
idOnTheSource?: string | null;
}) => Promise<AppConfigPrincipal[]>;
/** Add mutable principal-scoped runtime configuration after cached overrides are resolved. */
augmentConfig?: (context: {
appConfig: AppConfig;
baseConfig: AppConfig;
principals: AppConfigPrincipal[];
options: GetAppConfigOptions;
}) => Promise<AppConfig>;
/** TTL in ms for per-user/role merged config caches. Defaults to 60 000. */
overrideCacheTtl?: number;
/**
* Extra env names override values may reference (`CONFIG_OVERRIDE_ENV_ALLOWLIST`: names
* separated by commas or whitespace), beyond those librechat.yaml references and the built-in
* endpoint credentials.
*/
overrideEnvAllowlist?: string;
/**
* Whether config overrides of Azure `groups`, Vertex AI (`endpoints.anthropic.vertex`) and the
* Azure Assistants switch derive the served endpoints again (`CONFIG_REDERIVE_ENDPOINTS=true`).
* Off, those overrides stay inert, as before.
*/
rederiveEndpoints?: boolean;
}
export interface GetAppConfigOptions {
role?: string;
userId?: string;
idOnTheSource?: string | null;
tenantId?: string;
refresh?: boolean;
/** When true, return only the YAML-derived base config — no DB override queries. */
baseOnly?: boolean;
/** Propagate principal, override, and augmentation failures for security-sensitive callers. */
failClosed?: boolean;
/** Reuse principals already resolved by another authorization query in the same request. */
resolvedPrincipals?: AppConfigPrincipal[];
/** Skip mutable runtime augmentation when the caller has already loaded that data. */
skipRuntimeAugmentation?: boolean;
/**
* Merge the overrides as stored now, neither reading nor writing the per-principal merged
* cache. Admin reads use it so they never show a merge from before their own write. Unlike
* `refresh`, the YAML base config is not reloaded.
*/
bypassOverrideCache?: boolean;
}
/** What `resolveConfigLayers` resolves: one set of override documents, as `getAppConfig` merges them. */
export interface ResolveConfigLayersOptions {
tenantId?: string;
/** The documents to merge, active ones only, as `getApplicableConfigs` returns them. */
configs: readonly ConfigOverrideLayer[];
}
/** A merge of override documents, served and in librechat.yaml shape, and what each layer lost. */
export interface ResolvedConfigLayers {
/**
* librechat.yaml as the tenant sees it (the raw config, without YAML custom endpoints and
* model specs scoped to another tenant): what every layer merges over.
*/
yaml: Partial<TCustomConfig>;
/**
* What `getAppConfig` serves for these documents, before runtime augmentation, with stored
* secrets as stored (not decrypted).
*/
merged: AppConfig;
/** The same merge in librechat.yaml shape. */
resolved: Partial<TCustomConfig>;
/** Each document, in merge order, with what the merge does not apply of it. */
layers: ConfigLayerResolution[];
}
export interface AppConfigUserLike {
/** Resolved app user id. */
id?: string;
role?: string;
tenantId?: string;
idOnTheSource?: string | null;
}
export function getAppConfigOptionsFromUser(
user?: AppConfigUserLike | null,
tenantId?: string,
): GetAppConfigOptions {
const userId = user?.id;
const hasSourceIdentity =
user != null && Object.prototype.hasOwnProperty.call(user, 'idOnTheSource');
return {
role: user?.role,
userId,
idOnTheSource: userId && hasSourceIdentity ? (user.idOnTheSource ?? null) : undefined,
tenantId: tenantId ?? user?.tenantId ?? getTenantId(),
};
}
/**
* A route that decides policy from the resolved configuration must not be handed the base
* configuration when principal or override resolution fails, because the base can be broader
* than the scope that should have decided. The caller supplies the reader, so the selection
* of that policy lives here rather than in the middleware that assigns the result.
*/
export function resolveStrictAppConfig(
getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig | undefined>,
user?: AppConfigUserLike | null,
): Promise<AppConfig | undefined> {
return getAppConfig({ ...getAppConfigOptionsFromUser(user), failClosed: true });
}
// ── Helpers ──────────────────────────────────────────────────────────
let _strictOverride: boolean | undefined;
function isStrictOverrideMode(): boolean {
return (_strictOverride ??= process.env.TENANT_ISOLATION_STRICT === 'true');
}
let _warnedNoTenantInStrictMode = false;
/** @internal Resets the memoized strict-override flag and one-time no-tenantId warning gate. Exposed for test teardown only. */
export function _resetOverrideStrictCache(): void {
_strictOverride = undefined;
_warnedNoTenantInStrictMode = false;
}
/** Versioned so older heads cannot supply entries built without the local base identity. */
function overrideCacheKey(
role: string | undefined,
userId: string | undefined,
tenantId: string | undefined,
scopeVersion: string,
): string {
const tenant = tenantId ? `${tenantId}:tenant` : '__default__:global';
const principal =
userId && role ? `${role}:${userId}` : userId || role || BASE_CONFIG_PRINCIPAL_ID;
return `_OVERRIDE_:${tenant}:${principal}:base-v2:${scopeVersion}`;
}
/**
* Per-host late binding for method adapters constructed before the config service. The service
* installs its reader during composition; no module-global registry or cached budget is involved.
*/
export function createMessageBudgetReader(): {
initialize: (reader: (options?: GetAppConfigOptions) => Promise<AppConfig>) => void;
getBudget: () => Promise<number | undefined>;
} {
let readConfig: ((options?: GetAppConfigOptions) => Promise<AppConfig>) | undefined;
return {
initialize(reader) {
readConfig = reader;
},
async getBudget() {
if (!readConfig) throw new Error('Message App budget reader has not been initialized');
const config = await readConfig({ baseOnly: true });
return config.mcpAppSandbox?.maxPersistedMessageBytes;
},
};
}
/** Most distinct rebinding warnings remembered before the record starts over. */
const MAX_REBINDING_WARNINGS = 1000;
/**
* Logs each secret a layer drops for being sent somewhere other than where it was entered, and
* each destination it sets back, once per principal and path for the process's lifetime
* (bounded), since every uncached merge does it again.
*/
function createRebindingWarner(): (rebinding: SecretRebinding) => void {
const warned = new Set<string>();
return ({ layer, kind, path }) => {
const principal = `${layer.principalType}/${layer.principalId?.toString()}`;
const key = `${principal}:${path}`;
if (warned.has(key)) {
return;
}
if (warned.size >= MAX_REBINDING_WARNINGS) {
warned.clear();
}
warned.add(key);
if (kind === 'destination') {
logger.warn(
`[getAppConfig] Ignoring "${path}" for ${principal}: it would send a credential to a destination that was not chosen for it`,
);
return;
}
logger.warn(
`[getAppConfig] Dropping secret "${path}" for ${principal}: the merged config sends it somewhere other than the destination it was entered for`,
);
};
}
// ── Service factory ──────────────────────────────────────────────────
export function createAppConfigService(deps: AppConfigServiceDeps): {
getAppConfig: (options?: GetAppConfigOptions) => Promise<AppConfig>;
/** One set of override documents merged as `getAppConfig` merges them, layer by layer. */
resolveConfigLayers: (options: ResolveConfigLayersOptions) => Promise<ResolvedConfigLayers>;
clearAppConfigCache: () => Promise<void>;
clearOverrideCache: (tenantId?: string) => Promise<void>;
/** Loads librechat.yaml again on this instance and resolves with the outcome; never rejects. */
reloadBaseConfig: () => Promise<ConfigLoadResult>;
/** The TTL in ms this service caches per-principal merged configs for. */
overrideCacheTtl: number;
/** Whether this service derives Azure groups, Vertex AI and Azure Assistants again. */
rederiveEndpoints: boolean;
} {
const {
loadBaseConfig,
onBaseConfigPublished,
setCachedTools,
getCache,
cacheKeys,
getApplicableConfigs,
getUserPrincipals,
augmentConfig,
overrideCacheTtl = DEFAULT_OVERRIDE_CACHE_TTL,
overrideEnvAllowlist,
rederiveEndpoints = false,
} = deps;
const cache = getCache(cacheKeys.APP_CONFIG);
const envAllowlist = parseEnvAllowlist(overrideEnvAllowlist);
const envPolicies = new WeakMap<AppConfig, Map<string, EnvReferencePolicy>>();
const scopeVersions = new WeakMap<AppConfig, string>();
const warnRebinding = createRebindingWarner();
const runtimeConfigs = new WeakMap<AppConfig, AppConfig>();
/**
* A merged config with its stored credentials decrypted for runtime readers. The override cache
* (shared through Redis when `APP_CONFIG` is not kept in memory) holds the config as merged,
* with ciphertext; each read decrypts it, once per cached object.
*/
function withRuntimeSecrets(merged: AppConfig): AppConfig {
let resolved = runtimeConfigs.get(merged);
if (!resolved) {
resolved = resolveRuntimeConfigSecrets(merged);
runtimeConfigs.set(merged, resolved);
}
return resolved;
}
/**
* The env reference policy for a tenant, built once per loaded librechat.yaml and tenant from
* the YAML that tenant sees, so a name only another tenant's endpoint references is not
* allowed in this tenant's overrides.
*/
function getEnvPolicy(
baseConfig: AppConfig,
scopedBaseConfig: AppConfig,
tenantId: string | undefined,
): EnvReferencePolicy {
let byTenant = envPolicies.get(baseConfig);
if (!byTenant) {
byTenant = new Map();
envPolicies.set(baseConfig, byTenant);
}
const key = tenantId ?? '';
let policy = byTenant.get(key);
if (!policy) {
policy = createEnvReferencePolicy({
config: scopedBaseConfig.config,
allowlist: envAllowlist,
});
byTenant.set(key, policy);
}
return policy;
}
let lastGoodBaseConfig: AppConfig | undefined;
let publishedBaseGeneration = -1;
let baseConfigFlight: { promise: Promise<BaseConfigLoad>; generation: number } | undefined;
/**
* Base-config generation: `clearAppConfigCache` bumps it before deleting `_BASE_`. A reload
* publishes its result (the cached base, the tools and the last good config) only if no clear
* happened while it ran, and a read after a clear never joins a reload started before it, so a
* reload that read the old librechat.yaml cannot re-cache it after a later write's clear.
*/
let baseGeneration = 0;
/**
* Override-cache generations: a clear bumps the cleared tenant's (or, for a clear of every
* tenant, the global) counter before deleting entries. A merge captures the generation, base
* generation included, before it reads the base config or the database, and is cached only if
* no clear happened meanwhile, so a request that read just before an admin write cannot
* re-cache the old merge, or a merge built on the old base, just after the write's clears.
* The check runs again once the write lands, since an async store can apply it after a
* clear's delete.
*/
let globalOverrideGeneration = 0;
const tenantOverrideGenerations = new Map<string, number>();
function getOverrideGeneration(tenantId: string | undefined): string {
const tenant = tenantId ? (tenantOverrideGenerations.get(tenantId) ?? 0) : 0;
return `${baseGeneration}:${globalOverrideGeneration}:${tenant}`;
}
function bumpOverrideGeneration(tenantId: string | undefined): void {
if (!tenantId) {
globalOverrideGeneration += 1;
return;
}
tenantOverrideGenerations.set(tenantId, (tenantOverrideGenerations.get(tenantId) ?? 0) + 1);
}
async function buildPrincipals(
role?: string,
userId?: string,
idOnTheSource?: string | null,
): Promise<AppConfigPrincipal[]> {
if (userId) {
const params: { userId: string; role?: string | null; idOnTheSource?: string | null } = {
userId,
role,
};
if (idOnTheSource !== undefined) {
params.idOnTheSource = idOnTheSource;
}
return getUserPrincipals(params);
}
const principals: AppConfigPrincipal[] = [];
if (role) {
principals.push({ principalType: PrincipalType.ROLE, principalId: role });
}
return principals;
}
async function restoreLastGoodBaseConfig(error: unknown, generation: number): Promise<AppConfig> {
const lastGood = lastGoodBaseConfig;
if (!lastGood) {
throw error;
}
setMaxSubagents(lastGood.config?.endpoints?.agents?.maxSubagents);
logger.error(
'[ensureBaseConfig] Failed to reload base configuration; keeping the last good configuration.',
error,
);
if (generation !== baseGeneration) {
return lastGood;
}
publishedBaseGeneration = -1;
const restorations = [cache.set(BASE_CONFIG_KEY, lastGood)];
if (lastGood.availableTools) {
restorations.push(setCachedTools(lastGood.availableTools));
}
const results = await Promise.allSettled(restorations);
for (const result of results) {
if (result.status === 'rejected') {
logger.error(
'[ensureBaseConfig] Failed to restore last-good config state:',
getSafeErrorMetadata(result.reason),
);
} else if (result.value === false) {
logger.error('[ensureBaseConfig] Cache refused last-good config restoration.');
}
}
if (generation !== baseGeneration) {
await cache.delete(BASE_CONFIG_KEY).catch((deleteError: unknown) => {
logger.error('[ensureBaseConfig] Failed to drop an overtaken restoration:', deleteError);
});
} else if (results.every((result) => result.status === 'fulfilled' && result.value !== false)) {
publishedBaseGeneration = generation;
}
return lastGood;
}
/**
* Loads the base config and, unless a clear made `generation` stale while it loaded, publishes
* it. A stale load still answers the reads that joined it, which started before the clear.
* An async store (Redis) can land the write after a clear's delete, so a write a clear
* overtook in flight is removed again.
*/
async function publishBaseConfig(
mode: CustomConfigLoadMode,
generation: number,
): Promise<AppConfig> {
logger.info('[ensureBaseConfig] Loading base configuration...');
const loaded = await loadBaseConfig(mode);
if (!loaded) {
throw new Error('Failed to initialize app configuration through AppService.');
}
const baseConfig = completeEffectiveConfig(loaded);
if (generation !== baseGeneration) {
return baseConfig;
}
if (baseConfig.availableTools && (await setCachedTools(baseConfig.availableTools)) === false) {
throw new Error('Tool cache refused base configuration publication.');
}
if (generation !== baseGeneration) {
return baseConfig;
}
if ((await cache.set(BASE_CONFIG_KEY, baseConfig)) === false) {
throw new Error('Base cache refused configuration publication.');
}
if (generation !== baseGeneration) {
await cache.delete(BASE_CONFIG_KEY);
return baseConfig;
}
onBaseConfigPublished?.(loaded);
lastGoodBaseConfig = baseConfig;
publishedBaseGeneration = generation;
return baseConfig;
}
/** `publishBaseConfig`, keeping the last good config, and saying why, when a reload fails. */
async function loadAndCacheBaseConfig(
mode: CustomConfigLoadMode,
generation: number,
): Promise<BaseConfigLoad> {
try {
return { config: await publishBaseConfig(mode, generation) };
} catch (error) {
if (mode === 'startup') {
throw error;
}
const config = await restoreLastGoodBaseConfig(error, generation);
return { config, failure: getConfigLoadFailure(error) };
}
}
/**
* Reads join the load in flight for the current generation. A load for a newer generation
* starts once the stale one settles, so the loader's process-wide side effects (such as the
* subagent cap) end with the newest librechat.yaml rather than whichever read finished last.
*/
async function loadBase(refresh?: boolean): Promise<BaseConfigLoad> {
// Another process's cached YAML cannot replace this process's runtime configuration.
if (!refresh && lastGoodBaseConfig && publishedBaseGeneration === baseGeneration) {
return { config: lastGoodBaseConfig };
}
const generation = baseGeneration;
const previous = baseConfigFlight;
if (previous?.generation === generation) {
return previous.promise;
}
const mode: CustomConfigLoadMode = lastGoodBaseConfig ? 'reload' : 'startup';
const load = () => loadAndCacheBaseConfig(mode, generation);
const promise = previous ? previous.promise.then(load, load) : load();
const flight = { promise, generation };
baseConfigFlight = flight;
try {
return await promise;
} finally {
if (baseConfigFlight === flight) {
baseConfigFlight = undefined;
}
}
}
/**
* Ensure the YAML-derived base config is loaded and cached.
* Returns the `_BASE_` config (YAML + AppService). No DB queries.
*/
async function ensureBaseConfig(refresh?: boolean): Promise<AppConfig> {
return (await loadBase(refresh)).config;
}
/**
* Loads librechat.yaml again on this instance (or joins the load of it in flight), as the next
* read after `clearAppConfigCache` would, and resolves with the outcome instead of only logging
* a failure, so the admin reload route can answer for it. A failed load keeps the last good
* config, as every reload does. Never rejects.
*/
async function reloadBaseConfig(): Promise<ConfigLoadResult> {
try {
const { failure } = await loadBase(true);
return failure ? { ok: false, error: failure } : { ok: true };
} catch (error) {
logger.error('[reloadBaseConfig] Failed to load the base configuration:', error);
return { ok: false, error: getConfigLoadFailure(error) };
}
}
/**
* Get the app configuration, optionally merged with DB overrides for the given principal.
*
* The base config (from YAML + AppService) is cached indefinitely. Per-principal merged
* configs are cached with a short TTL (`overrideCacheTtl`, default 60s). On cache miss,
* `getApplicableConfigs` queries the DB for matching overrides, which merge in precedence
* order (`compareConfigPrecedence`): Base first, then ascending priority, then role < group <
* user, then document identity, the last layer winning.
*
* When `baseOnly` is true, returns the YAML-derived config without any DB queries.
* `role` and `userId` are ignored; tenantId still scopes YAML custom endpoints.
* Use this for startup and other paths that must not read overrides; sign-in decisions
* read the `__base__` override through `resolvePreAuthAppConfig`.
*/
async function getAppConfig(options: GetAppConfigOptions = {}): Promise<AppConfig> {
const {
role,
userId,
idOnTheSource,
tenantId,
refresh,
baseOnly,
failClosed,
resolvedPrincipals,
skipRuntimeAugmentation,
bypassOverrideCache,
} = options;
const ambientTenantId = getTenantId();
const requestedTenantId = tenantId === SYSTEM_TENANT_ID ? undefined : tenantId;
const effectiveTenantId =
ambientTenantId && ambientTenantId !== SYSTEM_TENANT_ID ? ambientTenantId : requestedTenantId;
if (effectiveTenantId && effectiveTenantId !== ambientTenantId) {
return tenantStorage.run({ ...tenantStorage.getStore(), tenantId: effectiveTenantId }, () =>
getAppConfig(options),
);
}
const cacheTenantId = ambientTenantId ?? effectiveTenantId;
const generation = getOverrideGeneration(cacheTenantId);
const baseConfig = await ensureBaseConfig(refresh);
const scopedBaseConfig = scopeBaseConfig(baseConfig, effectiveTenantId);
const hiddenEndpoints = hiddenCustomEndpoints(baseConfig, effectiveTenantId);
if (baseOnly) {
return scopedBaseConfig;
}
const principals =
resolvedPrincipals ??
(await buildPrincipals(role, userId, idOnTheSource).catch((error: unknown) => {
if (failClosed) throw error;
logger.error('[getAppConfig] Error building principals, falling back to base:', error);
return null;
}));
if (principals === null) {
return scopedBaseConfig;
}
// Strict isolation + no tenant anywhere (neither param nor ALS): a middleware bypass,
// or a signed-out request that named no tenant (strict mode refuses config reads without
// one). Admin calls carry an explicit tenantId. Return the base config
// without caching it under the shared `__default__` bucket. When ALS has a tenant,
// overrideCacheKey scopes the key to it, so we fall through and cache per-tenant.
if (principals.length === 0 && !tenantId && !getTenantId() && isStrictOverrideMode()) {
return scopedBaseConfig;
}
if (!tenantId && !getTenantId() && isStrictOverrideMode() && !_warnedNoTenantInStrictMode) {
_warnedNoTenantInStrictMode = true;
logger.warn(
'[getAppConfig] No tenantId in strict mode — falling back to __default__. ' +
'This likely indicates a code path that bypasses the tenant context middleware.',
);
}
const augment = async (appConfig: AppConfig): Promise<AppConfig> => {
const scopedConfig = scopeCustomEndpoints(appConfig, effectiveTenantId, hiddenEndpoints);
if (augmentConfig == null || skipRuntimeAugmentation === true) return scopedConfig;
try {
return scopeCustomEndpoints(
await augmentConfig({
appConfig: scopedConfig,
baseConfig: scopedBaseConfig,
principals,
options: { ...options, tenantId: effectiveTenantId },
}),
effectiveTenantId,
hiddenEndpoints,
);
} catch (error) {
if (failClosed) throw error;
logger.error('[getAppConfig] Error augmenting principal config:', error);
return scopedConfig;
}
};
let scopeVersion = scopeVersions.get(baseConfig);
if (!scopeVersion) {
// Hash once per local base, including derived settings and override policy, never values in keys.
scopeVersion = createHash('sha256')
.update(JSON.stringify([baseConfig, rederiveEndpoints, overrideEnvAllowlist]))
.digest('hex');
scopeVersions.set(baseConfig, scopeVersion);
}
const cacheKey = overrideCacheKey(role, userId, cacheTenantId, scopeVersion);
/**
* The key names a role and user, not a principal set: principals resolved elsewhere are
* cached only when a user id ties them to the key.
*/
let cacheable = bypassOverrideCache !== true && (resolvedPrincipals == null || !!userId);
if (cacheable && !refresh) {
let cachedMerged: AppConfig | undefined;
try {
cachedMerged = (await cache.get(cacheKey)) as AppConfig | undefined;
} catch (error) {
cacheable = false;
logger.warn(
'[getAppConfig] Failed to read merged config cache; resolving uncached.',
getSafeErrorMetadata(error),
);
}
if (cachedMerged) {
return await augment(withRuntimeSecrets(cachedMerged));
}
}
let merged = scopedBaseConfig;
try {
const configs = await getApplicableConfigs(principals);
if (configs.length > 0) {
const { appConfig: layered, raw } = mergeOverrideLayersWithSource(
scopedBaseConfig,
configs,
{
envPolicy: getEnvPolicy(baseConfig, scopedBaseConfig, effectiveTenantId),
onRebinding: warnRebinding,
rederiveEndpoints,
},
);
const scopedMerge = scopeCustomEndpoints(
checkOverrideTheme(
scopedBaseConfig,
scopeHiddenEndpointReferences(
scopedBaseConfig,
configs,
completeEffectiveConfig(layered),
),
),
effectiveTenantId,
hiddenEndpoints,
);
/** Spec-dependent controls follow the specs served once tenant scoping has settled them. */
merged = withSpecInterface(
scopedMerge,
raw.interface,
getChangedSpecFields(scopedBaseConfig, scopedMerge, raw.interface),
);
}
} catch (error) {
if (failClosed) throw error;
logger.error('[getAppConfig] Error resolving config overrides, falling back to base:', error);
return scopedBaseConfig;
}
if (cacheable && getOverrideGeneration(cacheTenantId) === generation) {
try {
await cache.set(cacheKey, merged, overrideCacheTtl);
if (getOverrideGeneration(cacheTenantId) !== generation) {
await cache.delete(cacheKey);
}
} catch (error) {
logger.warn(
'[getAppConfig] Failed to cache merged config; serving the resolved configuration.',
getSafeErrorMetadata(error),
);
}
}
return await augment(withRuntimeSecrets(merged));
}
/**
* Merges `configs` exactly as `getAppConfig` merges a principal's documents (the same base
* config, tenant scoping, env policy and secret rebinding, theme check and endpoint scoping),
* never reading or writing the override cache, and reports the merge in librechat.yaml shape
* with what each layer could not apply (`resolveOverrideLayers`). Admin reads use it to show
* what a profile, or a user, resolves to. The YAML-shaped result replays the theme fallback and
* the tenant scoping; spec endpoint materialization and endpoint reference normalization rename
* values for the runtime and are left out of it, as are the interface defaults AppService
* derives.
*/
async function resolveConfigLayers(
options: ResolveConfigLayersOptions,
): Promise<ResolvedConfigLayers> {
const { tenantId, configs } = options;
const ambientTenantId = getTenantId();
const requestedTenantId = tenantId === SYSTEM_TENANT_ID ? undefined : tenantId;
const effectiveTenantId =
ambientTenantId && ambientTenantId !== SYSTEM_TENANT_ID ? ambientTenantId : requestedTenantId;
if (effectiveTenantId && effectiveTenantId !== ambientTenantId) {
return tenantStorage.run({ ...tenantStorage.getStore(), tenantId: effectiveTenantId }, () =>
resolveConfigLayers(options),
);
}
const baseConfig = await ensureBaseConfig();
const scopedBaseConfig = await scopeBaseConfig(baseConfig, effectiveTenantId);
const yaml: Partial<TCustomConfig> = scopedBaseConfig.config ?? {};
if (configs.length === 0) {
return { yaml, merged: scopedBaseConfig, resolved: yaml, layers: [] };
}
const hiddenEndpoints = hiddenCustomEndpoints(baseConfig, effectiveTenantId);
const resolution = resolveOverrideLayers(scopedBaseConfig, configs, {
envPolicy: getEnvPolicy(baseConfig, scopedBaseConfig, effectiveTenantId),
onRebinding: warnRebinding,
rederiveEndpoints,
});
const completed = completeEffectiveConfig(resolution.merged);
const unserved = getUnservedEndpointNames(scopedBaseConfig, configs, completed);
const checked = checkOverrideTheme(
scopedBaseConfig,
scopeEndpointReferences(completed, unserved),
);
const baseTheme = scopedBaseConfig.interfaceConfig?.theme;
let resolved = resolution.resolved;
if (
checked.interfaceConfig?.theme === baseTheme &&
completed.interfaceConfig?.theme !== baseTheme
) {
resolved = replayThemeFallback(resolved, resolution.layers, yaml);
}
resolved = scopeResolvedEndpoints(
scopeEndpointReferences(resolved, unserved),
resolution.layers,
effectiveTenantId,
hiddenCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints),
);
const scopedMerge = scopeCustomEndpoints(checked, effectiveTenantId, hiddenEndpoints);
const explicit = resolution.raw.interface;
return {
yaml,
merged: withSpecInterface(
scopedMerge,
explicit,
getChangedSpecFields(scopedBaseConfig, scopedMerge, explicit),
),
resolved,
layers: resolution.layers,
};
}
/**
* Clear the base config cache. Per-user/role override caches (`_OVERRIDE_:*`)
* are NOT flushed — they expire naturally via `overrideCacheTtl`. After calling this,
* the base config will be reloaded from YAML on the next `getAppConfig` call, but
* users with cached overrides may see stale merged configs for up to `overrideCacheTtl` ms.
* Reloads and merges already in flight are not cached afterwards.
*/
async function clearAppConfigCache(): Promise<void> {
baseGeneration += 1;
await cache.delete(BASE_CONFIG_KEY);
}
/**
* Clear per-principal override caches. When `tenantId` is provided, only caches
* matching `_OVERRIDE_:${tenantId}:tenant:*` are deleted. When omitted, ALL override
* caches are cleared.
*/
async function clearOverrideCache(tenantId?: string): Promise<void> {
bumpOverrideGeneration(tenantId);
const namespace = cacheKeys.APP_CONFIG;
const overrideSegment = tenantId ? `_OVERRIDE_:${tenantId}:tenant:` : '_OVERRIDE_:';
// In-memory store — enumerate keys directly.
// APP_CONFIG defaults to FORCED_IN_MEMORY_CACHE_NAMESPACES, so this is the
// standard path. Redis SCAN is intentionally avoided here — it can cause 60s+
// stalls under concurrent load (see #12410). When APP_CONFIG is Redis-backed
// and store.keys() is unavailable, overrides expire naturally via TTL.
const store = (cache as CacheStore).opts?.store;
if (store && typeof store.keys === 'function') {
// Keyv stores keys with a namespace prefix (e.g. "APP_CONFIG:_OVERRIDE_:...").
// We match on the namespaced key but delete using the un-namespaced key
// because Keyv.delete() auto-prepends the namespace.
const namespacedPrefix = `${namespace}:${overrideSegment}`;
const toDelete: string[] = [];
for (const key of store.keys()) {
if (key.startsWith(namespacedPrefix)) {
toDelete.push(key.slice(namespace.length + 1));
}
}
if (toDelete.length > 0) {
await Promise.all(toDelete.map((key) => cache.delete(key)));
logger.info(
`[clearOverrideCache] Cleared ${toDelete.length} override cache entries` +
(tenantId ? ` for tenant ${tenantId}` : ''),
);
}
return;
}
logger.warn(
'[clearOverrideCache] Cache store does not support key enumeration. ' +
'Override caches will expire naturally via TTL (%dms). ' +
'This is expected when APP_CONFIG is Redis-backed — Redis SCAN is avoided ' +
'for performance reasons (see #12410).',
overrideCacheTtl,
);
}
return {
getAppConfig,
resolveConfigLayers,
clearAppConfigCache,
clearOverrideCache,
reloadBaseConfig,
overrideCacheTtl,
rederiveEndpoints,
};
}
export type AppConfigService = ReturnType<typeof createAppConfigService>;