Skip to content

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

🏝️ feat: Scope YAML Custom Endpoints by Tenant (#16537)

Danny Avila2aea0d6684fa
diff --git a/librechat.example.yaml b/librechat.example.yaml
index fcacb78c34..81322cae58 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -906,6 +906,8 @@ endpoints:
# https://docs.x.ai/developers/grok-4-7
# Set XAI_API_KEY in your environment. No separate SpaceXAI provider is needed.
- name: 'xai'
+ # Optional: expose this endpoint only to users in the named tenant.
+ # tenantId: 'your-tenant-id'
apiKey: '${XAI_API_KEY}'
baseURL: 'https://api.x.ai/v1'
models:
diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.ts
index ee813ed8d2..6da766b76a 100644
--- a/packages/api/src/app/service.spec.ts
+++ b/packages/api/src/app/service.spec.ts
@@ -1,10 +1,12 @@
import { getMaxSubagents, setMaxSubagents } from 'librechat-data-provider';
+import { AppService, getTenantId, tenantStorage, SYSTEM_TENANT_ID } from '@librechat/data-schemas';
import type { AppConfig } from '@librechat/data-schemas';
import {
createAppConfigService,
_resetOverrideStrictCache,
getAppConfigOptionsFromUser,
} from './service';
+import { getProviderConfig } from '~/endpoints/config/providers';
/** Extends AppConfig with mock fields used by merge behavior tests. */
interface TestConfig extends AppConfig {
@@ -97,6 +99,459 @@ describe('createAppConfigService', () => {
expect(config).toEqual(deps._baseConfig);
});
+ it('serves tenant-scoped YAML custom endpoints only to their tenant', async () => {
+ const custom = [
+ { name: 'Global', apiKey: 'global-key', baseURL: 'https://global.example' },
+ {
+ name: 'ClickHouse',
+ tenantId: 'dwh-org',
+ apiKey: 'dwh-key',
+ baseURL: 'https://dwh.example',
+ },
+ ];
+ const modelSpecs = {
+ list: [
+ { name: 'global-spec', preset: { endpoint: 'Global' } },
+ { name: 'dwh-spec', softDefault: true, preset: { endpoint: 'ClickHouse' } },
+ ],
+ addedEndpoints: ['agents', 'ClickHouse'],
+ };
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue({
+ endpoints: { custom },
+ modelSpecs,
+ config: { endpoints: { custom }, modelSpecs },
+ }),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+
+ const base = await getAppConfig({ baseOnly: true });
+ const tenantBase = await getAppConfig({ baseOnly: true, tenantId: 'dwh-org' });
+ const dwh = await getAppConfig({ role: 'USER', tenantId: 'dwh-org' });
+ const other = await getAppConfig({ role: 'USER', tenantId: 'other-org' });
+ const staleUserTenant = await tenantStorage.run({ tenantId: 'other-org' }, () =>
+ getAppConfig({ role: 'USER', tenantId: 'dwh-org' }),
+ );
+
+ expect(base.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual(['Global']);
+ expect(tenantBase.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual([
+ 'Global',
+ 'ClickHouse',
+ ]);
+ expect(dwh.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual([
+ 'Global',
+ 'ClickHouse',
+ ]);
+ expect(other.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual(['Global']);
+ expect(other.config.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual(['Global']);
+ expect(base.modelSpecs?.list?.map((spec) => spec.name)).toEqual(['global-spec']);
+ expect(tenantBase.modelSpecs?.list?.map((spec) => spec.name)).toEqual([
+ 'global-spec',
+ 'dwh-spec',
+ ]);
+ expect(other.modelSpecs?.addedEndpoints).toEqual(['agents']);
+ expect(other.config.modelSpecs?.list?.map((spec) => spec.name)).toEqual(['global-spec']);
+ expect(staleUserTenant.modelSpecs?.list?.map((spec) => spec.name)).toEqual(['global-spec']);
+ expect(staleUserTenant.endpoints?.custom?.map((endpoint) => endpoint.name)).toEqual([
+ 'Global',
+ ]);
+ expect(
+ getProviderConfig({ provider: 'ClickHouse', appConfig: dwh }).customEndpointConfig?.baseURL,
+ ).toBe('https://dwh.example');
+ expect(() => getProviderConfig({ provider: 'ClickHouse', appConfig: other })).toThrow(
+ 'Provider ClickHouse not supported',
+ );
+ expect(custom).toHaveLength(2);
+ });
+
+ it('removes a prioritized spec when its only endpoint belongs to another tenant', async () => {
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue({
+ endpoints: { custom: [{ name: 'ClickHouse', tenantId: 'dwh-org' }] },
+ modelSpecs: {
+ prioritize: true,
+ list: [{ name: 'dwh-spec', preset: { endpoint: 'ClickHouse' } }],
+ },
+ }),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+
+ const config = await getAppConfig({ role: 'USER', tenantId: 'other-org' });
+
+ expect(config.endpoints?.custom).toEqual([]);
+ expect(config.modelSpecs).toBeUndefined();
+ });
+
+ describe('tenant isolation invariants', () => {
+ async function tenantBase(interfaceConfig?: AppConfig['interfaceConfig']) {
+ return AppService({
+ config: {
+ interface: interfaceConfig,
+ endpoints: {
+ custom: [
+ {
+ name: 'Private Gateway',
+ tenantId: 'tenant-a',
+ apiKey: 'private-gateway-key',
+ baseURL: 'https://private.example',
+ models: { default: ['private-model'] },
+ },
+ ],
+ },
+ modelSpecs: {
+ enforce: true,
+ prioritize: true,
+ list: [
+ { name: 'private-spec', label: 'Private', preset: { endpoint: 'Private Gateway' } },
+ ],
+ },
+ },
+ });
+ }
+
+ it('restores no-spec interface defaults without mutating the shared YAML base', async () => {
+ const base = await tenantBase();
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ const { getAppConfig } = createAppConfigService(deps);
+ const [owner, other, anonymous] = await Promise.all([
+ getAppConfig({ baseOnly: true, tenantId: 'tenant-a' }),
+ getAppConfig({ baseOnly: true, tenantId: 'tenant-b' }),
+ getAppConfig({ baseOnly: true }),
+ ]);
+ expect(owner.modelSpecs?.list).toHaveLength(1);
+ expect(owner.interfaceConfig).toMatchObject({
+ modelSelect: false,
+ parameters: false,
+ presets: false,
+ });
+ for (const config of [other, anonymous]) {
+ expect(config.modelSpecs).toBeUndefined();
+ expect(config.config.modelSpecs).toBeUndefined();
+ expect(config.interfaceConfig).toMatchObject({
+ modelSelect: true,
+ parameters: true,
+ presets: true,
+ });
+ expect(config.endpoints?.custom).toEqual([]);
+ }
+ expect(base.modelSpecs?.list).toHaveLength(1);
+ expect(base.config.endpoints?.custom).toHaveLength(1);
+ expect(base.interfaceConfig?.modelSelect).toBe(false);
+ });
+
+ it.each(['yaml', 'override'])(
+ 'preserves explicit %s interface restrictions after dropping the last spec',
+ async (source) => {
+ const explicit = {
+ modelSelect: false,
+ parameters: false,
+ presets: false,
+ customWelcome: 'Welcome',
+ };
+ const base = await tenantBase(source === 'yaml' ? explicit : undefined);
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue(base),
+ getApplicableConfigs: jest
+ .fn()
+ .mockResolvedValue(
+ source === 'override'
+ ? [{ priority: 10, overrides: { interface: explicit }, isActive: true }]
+ : [],
+ ),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ for (let i = 0; i < 2; i++) {
+ const config = await getAppConfig({ role: 'USER', tenantId: 'tenant-b' });
+ expect(config.modelSpecs).toBeUndefined();
+ expect(config.interfaceConfig).toMatchObject(explicit);
+ }
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);
+ },
+ );
+
+ it('recomputes model selection when only the added custom endpoint is hidden', async () => {
+ const base = await tenantBase();
+ base.modelSpecs = {
+ list: [{ name: 'public-spec', label: 'Public', preset: { endpoint: 'openAI' } }],
+ addedEndpoints: ['Private Gateway'],
+ };
+ base.config.modelSpecs = base.modelSpecs;
+ base.interfaceConfig = { modelSelect: true, parameters: false, presets: false };
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ const { getAppConfig } = createAppConfigService(deps);
+ const other = await getAppConfig({ tenantId: 'tenant-b' });
+ expect(other.modelSpecs?.list).toHaveLength(1);
+ expect(other.modelSpecs?.addedEndpoints).toEqual([]);
+ expect(other.interfaceConfig).toMatchObject({
+ modelSelect: false,
+ parameters: false,
+ presets: false,
+ });
+ });
+
+ it('uses the ambient tenant for override reads, cache writes, hits, and invalidation despite stale user IDs', async () => {
+ const deps = createDeps({
+ getApplicableConfigs: jest
+ .fn()
+ .mockImplementation(async () => [
+ { priority: 10, overrides: { x: getTenantId() }, isActive: true },
+ ]),
+ });
+ const { getAppConfig, clearOverrideCache } = createAppConfigService(deps);
+ const read = (tenant: string, stale: string) =>
+ tenantStorage.run({ tenantId: tenant }, () =>
+ getAppConfig({ role: 'USER', tenantId: stale }),
+ );
+ expect(((await read('tenant-a', 'tenant-b')) as TestConfig).x).toBe('tenant-a');
+ expect(((await read('tenant-b', 'tenant-a')) as TestConfig).x).toBe('tenant-b');
+ expect(((await read('tenant-a', 'tenant-b')) as TestConfig).x).toBe('tenant-a');
+ expect(((await read('tenant-b', 'tenant-a')) as TestConfig).x).toBe('tenant-b');
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);
+ await clearOverrideCache('tenant-a');
+ await read('tenant-b', 'tenant-a');
+ await read('tenant-a', 'tenant-b');
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(3);
+ });
+
+ it('separates a real __default__ tenant from requests without a tenant, including invalidation', async () => {
+ const deps = createDeps({
+ getApplicableConfigs: jest
+ .fn()
+ .mockImplementation(async () => [
+ { priority: 10, overrides: { x: getTenantId() ?? 'global' }, isActive: true },
+ ]),
+ });
+ const { getAppConfig, clearOverrideCache } = createAppConfigService(deps);
+ const global = () => getAppConfig({ role: 'USER' });
+ const tenant = () => getAppConfig({ role: 'USER', tenantId: '__default__' });
+ expect(((await global()) as TestConfig).x).toBe('global');
+ expect(((await tenant()) as TestConfig).x).toBe('__default__');
+ expect(((await global()) as TestConfig).x).toBe('global');
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);
+ await clearOverrideCache('__default__');
+ await global();
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);
+ expect(((await tenant()) as TestConfig).x).toBe('__default__');
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(3);
+ });
+
+ it('ignores override cache entries written by heads with stale tenant-key selection', async () => {
+ const deps = createDeps();
+ await deps._cache.set('_OVERRIDE_:tenant-a:USER', { x: 'tenant-b' });
+ const { getAppConfig } = createAppConfigService(deps);
+ const config = await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
+ getAppConfig({ role: 'USER' }),
+ );
+ expect((config as TestConfig).x).toBeUndefined();
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);
+ });
+
+ it.each([undefined, SYSTEM_TENANT_ID])(
+ 'applies an explicit tenant to database and runtime lookups from %s context',
+ async (ambient) => {
+ const observed: Array<string | undefined> = [];
+ const deps = createDeps({
+ getApplicableConfigs: jest.fn().mockImplementation(async () => {
+ observed.push(getTenantId());
+ return [];
+ }),
+ augmentConfig: jest.fn(async ({ appConfig, options }) => {
+ expect(options.tenantId).toBe(getTenantId());
+ observed.push(getTenantId());
+ return appConfig;
+ }),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ await tenantStorage.run({ tenantId: ambient, requestId: 'request-1' }, async () => {
+ await getAppConfig({ role: 'USER', tenantId: 'tenant-a' });
+ await getAppConfig({ role: 'USER', tenantId: 'tenant-b' });
+ expect(getTenantId()).toBe(ambient);
+ expect(tenantStorage.getStore()?.requestId).toBe('request-1');
+ });
+ expect(observed).toEqual(['tenant-a', 'tenant-a', 'tenant-b', 'tenant-b']);
+ },
+ );
+
+ it('never treats the system sentinel as a tenant-owned endpoint selector', async () => {
+ const base = await tenantBase();
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ const { getAppConfig } = createAppConfigService(deps);
+ const config = await tenantStorage.run({ tenantId: SYSTEM_TENANT_ID }, () =>
+ getAppConfig({ baseOnly: true, tenantId: SYSTEM_TENANT_ID }),
+ );
+ expect(config.endpoints?.custom).toEqual([]);
+ expect(config.modelSpecs).toBeUndefined();
+ });
+
+ it.each(['principals', 'overrides', 'augmentation'])(
+ 'keeps fallback configuration scoped on %s failure',
+ async (stage) => {
+ const base = await tenantBase();
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ if (stage === 'principals')
+ deps.getUserPrincipals.mockRejectedValue(new Error('unavailable'));
+ if (stage === 'overrides')
+ deps.getApplicableConfigs.mockRejectedValue(new Error('unavailable'));
+ const { getAppConfig } = createAppConfigService({
+ ...deps,
+ ...(stage === 'augmentation' && {
+ augmentConfig: jest.fn().mockRejectedValue(new Error('unavailable')),
+ }),
+ });
+ const config = await getAppConfig({ userId: 'uid1', role: 'USER', tenantId: 'tenant-b' });
+ expect(config.endpoints?.custom).toEqual([]);
+ expect(config.config.endpoints?.custom).toEqual([]);
+ expect(config.modelSpecs).toBeUndefined();
+ expect(config.interfaceConfig).toMatchObject({
+ modelSelect: true,
+ parameters: true,
+ presets: true,
+ });
+ },
+ );
+
+ it('does not let an override reassign a hidden YAML endpoint or inherit its credentials', async () => {
+ const base = await tenantBase();
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue(base),
+ getApplicableConfigs: jest.fn().mockResolvedValue([
+ {
+ priority: 10,
+ isActive: true,
+ overrides: {
+ endpoints: { custom: [{ name: 'Private Gateway', tenantId: 'tenant-b' }] },
+ modelSpecs: {
+ list: [
+ {
+ name: 'injected',
+ label: 'Injected',
+ preset: { endpoint: 'Private Gateway' },
+ },
+ ],
+ },
+ },
+ },
+ ]),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ for (let i = 0; i < 2; i++) {
+ const config = await getAppConfig({ role: 'USER', tenantId: 'tenant-b' });
+ expect(config.endpoints?.custom).toEqual([]);
+ expect(config.modelSpecs).toBeUndefined();
+ expect(JSON.stringify(config)).not.toContain('private-gateway-key');
+ }
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps tenant-owned YAML fields available to partial admin overrides', async () => {
+ const base = await tenantBase();
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue(base),
+ getApplicableConfigs: jest.fn().mockResolvedValue([
+ {
+ priority: 10,
+ isActive: true,
+ overrides: {
+ endpoints: {
+ custom: [{ name: 'Private Gateway', baseURL: 'https://override.example' }],
+ },
+ },
+ },
+ ]),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ const owner = await getAppConfig({ role: 'USER', tenantId: 'tenant-a' });
+ expect(owner.endpoints?.custom?.[0]).toMatchObject({
+ tenantId: 'tenant-a',
+ apiKey: 'private-gateway-key',
+ baseURL: 'https://override.example',
+ });
+ expect(owner.modelSpecs?.list).toHaveLength(1);
+ const yaml = await getAppConfig({ tenantId: 'tenant-a', baseOnly: true });
+ expect(yaml.config.endpoints?.custom?.[0].baseURL).toBe('https://private.example');
+ });
+
+ it('revokes a cached endpoint when a successful YAML reload changes its tenant', async () => {
+ const original = await tenantBase();
+ const updated = await tenantBase();
+ for (const endpoint of updated.endpoints?.custom ?? []) endpoint.tenantId = 'tenant-b';
+ for (const endpoint of updated.config.endpoints?.custom ?? [])
+ endpoint.tenantId = 'tenant-b';
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValueOnce(original).mockResolvedValue(updated),
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ const owner = await getAppConfig({ role: 'USER', tenantId: 'tenant-a' });
+ expect(owner.endpoints?.custom).toHaveLength(1);
+ await getAppConfig({ tenantId: 'tenant-b', baseOnly: true, refresh: true });
+ const revoked = await getAppConfig({ role: 'USER', tenantId: 'tenant-a' });
+ expect(revoked.endpoints?.custom).toEqual([]);
+ expect(revoked.modelSpecs).toBeUndefined();
+ expect(JSON.stringify(revoked)).not.toContain('private-gateway-key');
+ expect(revoked.interfaceConfig).toMatchObject({
+ modelSelect: true,
+ parameters: true,
+ presets: true,
+ });
+ expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(2);
+ });
+
+ it('passes only scoped inputs to augmentation and blocks hidden endpoint resurrection', async () => {
+ const base = await tenantBase();
+ const augmentConfig = jest.fn(async ({ appConfig, baseConfig, options }) => {
+ expect(baseConfig.endpoints?.custom).toEqual([]);
+ expect(appConfig.config.endpoints?.custom).toEqual([]);
+ expect(options.tenantId).toBe('tenant-b');
+ return {
+ ...appConfig,
+ endpoints: { custom: [{ ...base.endpoints?.custom?.[0], tenantId: 'tenant-b' }] },
+ };
+ });
+ const deps = createDeps({
+ loadBaseConfig: jest.fn().mockResolvedValue(base),
+ augmentConfig,
+ });
+ const { getAppConfig } = createAppConfigService(deps);
+ const config = await tenantStorage.run({ tenantId: 'tenant-b' }, () =>
+ getAppConfig({ role: 'USER', tenantId: 'tenant-a' }),
+ );
+ expect(config.endpoints?.custom).toEqual([]);
+ expect(augmentConfig).toHaveBeenCalledTimes(1);
+ });
+
+ it('preserves an unscoped endpoint and its specs when a hidden endpoint shares its normalized name', async () => {
+ const base = await tenantBase();
+ const global = {
+ ...base.endpoints?.custom?.[0],
+ tenantId: undefined,
+ apiKey: 'global-key',
+ };
+ base.endpoints?.custom?.push(global);
+ if (base.config.endpoints?.custom !== base.endpoints?.custom) {
+ base.config.endpoints?.custom?.push(global);
+ }
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ const { getAppConfig } = createAppConfigService(deps);
+ const config = await getAppConfig({ tenantId: 'tenant-b' });
+ expect(config.endpoints?.custom).toEqual([global]);
+ expect(config.modelSpecs?.list).toHaveLength(1);
+ expect(
+ getProviderConfig({ provider: 'Private Gateway', appConfig: config }).customEndpointConfig
+ ?.apiKey,
+ ).toBe('global-key');
+ });
+
+ it('keeps source-only hidden specs out when the effective custom endpoint array is empty', async () => {
+ const base = await tenantBase();
+ base.endpoints = { custom: [] };
+ const deps = createDeps({ loadBaseConfig: jest.fn().mockResolvedValue(base) });
+ const { getAppConfig } = createAppConfigService(deps);
+ const config = await getAppConfig({ baseOnly: true, tenantId: 'tenant-b' });
+ expect(config.config.endpoints?.custom).toEqual([]);
+ expect(config.modelSpecs).toBeUndefined();
+ });
+ });
+
it('reloads base config when refresh is true', async () => {
const deps = createDeps();
const { getAppConfig } = createAppConfigService(deps);
@@ -316,7 +771,9 @@ describe('createAppConfigService', () => {
const cachedKeys = [...deps._cache._store.keys()];
const overrideKey = cachedKeys.find((k) => k.includes('_OVERRIDE_:'));
- expect(overrideKey).toBe('app_config:_OVERRIDE_:__default__:uid1');
+ expect(overrideKey).toMatch(
+ /^app_config:_OVERRIDE_:__default__:global:uid1:tenant-v1:[a-f0-9]{64}$/,
+ );
});
it('tenantId is included in cache key to prevent cross-tenant contamination', async () => {
@@ -481,7 +938,9 @@ describe('createAppConfigService', () => {
const overrideKey = [...deps._cache._store.keys()].find((k: string) =>
k.includes('_OVERRIDE_:'),
);
- expect(overrideKey).toBe('app_config:_OVERRIDE_:tenant-a:USER');
+ expect(overrideKey).toMatch(
+ /^app_config:_OVERRIDE_:tenant-a:tenant:USER:tenant-v1:[a-f0-9]{64}$/,
+ );
expect(overrideKey).not.toContain('__default__');
});
@@ -683,7 +1142,11 @@ describe('createAppConfigService', () => {
expect(deps.getUserPrincipals).toHaveBeenCalledTimes(2);
expect(deps.getApplicableConfigs).toHaveBeenCalledTimes(1);
expect([...deps._cache._store.keys()]).toEqual(
- expect.arrayContaining(['app_config:_OVERRIDE_:__default__:USER:uid1']),
+ expect.arrayContaining([
+ expect.stringMatching(
+ /^app_config:_OVERRIDE_:__default__:global:USER:uid1:tenant-v1:[a-f0-9]{64}$/,
+ ),
+ ]),
);
});
diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.ts
index ebc4da01f9..44a4750bd3 100644
--- a/packages/api/src/app/service.ts
+++ b/packages/api/src/app/service.ts
@@ -1,13 +1,19 @@
+import { createHash } from 'node:crypto';
import {
PrincipalType,
materializeModelSpecEndpoints,
+ getConfigDefaults,
+ normalizeEndpointName,
setMaxSubagents,
} from 'librechat-data-provider';
import {
logger,
getTenantId,
mergeConfigOverrides,
+ loadDefaultInterface,
+ tenantStorage,
BASE_CONFIG_PRINCIPAL_ID,
+ SYSTEM_TENANT_ID,
} from '@librechat/data-schemas';
import type { AppConfig, IConfig } from '@librechat/data-schemas';
import type { Types } from 'mongoose';
@@ -15,6 +21,127 @@ import type { CustomConfigLoadMode } from './loader';
const BASE_CONFIG_KEY = '_BASE_';
+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 scoped = endpoints.filter(
+ (endpoint) =>
+ (!endpoint.tenantId || endpoint.tenantId === tenantId) &&
+ !hiddenEndpoints.has(normalizeEndpointName(endpoint.name ?? '')),
+ );
+ return scoped.length === endpoints.length ? endpoints : scoped;
+}
+
+function scopeModelSpecs(
+ specs: AppConfig['modelSpecs'],
+ hiddenEndpoints: ReadonlySet<string>,
+): AppConfig['modelSpecs'] {
+ if (!specs || hiddenEndpoints.size === 0) {
+ return specs;
+ }
+ const list = specs.list?.filter(
+ (spec) => !hiddenEndpoints.has(normalizeEndpointName(spec.preset?.endpoint ?? '')),
+ );
+ const addedEndpoints = specs.addedEndpoints?.filter(
+ (endpoint) => !hiddenEndpoints.has(normalizeEndpointName(endpoint)),
+ );
+ if (
+ list?.length === specs.list?.length &&
+ addedEndpoints?.length === specs.addedEndpoints?.length
+ ) {
+ return specs;
+ }
+ if (specs.list?.length && list?.length === 0) {
+ return undefined;
+ }
+ return { ...specs, list, addedEndpoints };
+}
+
+/** 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 }),
+ },
+ }),
+ };
+}
+
+/** Re-derive only spec-dependent controls before principal overrides are applied. */
+async function scopeBaseConfig(config: AppConfig, tenantId?: string): Promise<AppConfig> {
+ const scoped = scopeCustomEndpoints(config, tenantId);
+ if (scoped.modelSpecs === config.modelSpecs || !config.interfaceConfig) {
+ return scoped;
+ }
+ const defaults = await loadDefaultInterface({
+ config: { ...scoped.config, modelSpecs: scoped.modelSpecs },
+ configDefaults: getConfigDefaults(),
+ });
+ return {
+ ...scoped,
+ interfaceConfig: {
+ ...config.interfaceConfig,
+ modelSelect: defaults?.modelSelect,
+ parameters: defaults?.parameters,
+ presets: defaults?.presets,
+ },
+ };
+}
+
export type AppConfigPrincipal = {
principalType: string;
principalId?: string | Types.ObjectId;
@@ -132,21 +259,17 @@ export function _resetOverrideStrictCache(): void {
_warnedNoTenantInStrictMode = false;
}
-function overrideCacheKey(role?: string, userId?: string, tenantId?: string): string {
- // Fall back to the ALS tenant context before `__default__`: callers that rely on the
- // tenant middleware (the common path) pass no explicit tenantId, so without this the
- // entry is keyed under the shared `__default__` bucket and leaks across tenants.
- const tenant = tenantId || getTenantId() || '__default__';
- if (userId) {
- if (role) {
- return `_OVERRIDE_:${tenant}:${role}:${userId}`;
- }
- return `_OVERRIDE_:${tenant}:${userId}`;
- }
- if (role) {
- return `_OVERRIDE_:${tenant}:${role}`;
- }
- return `_OVERRIDE_:${tenant}:${BASE_CONFIG_PRINCIPAL_ID}`;
+/** Versioned so older heads cannot supply override entries built under a stale tenant ID. */
+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}:tenant-v1:${scopeVersion}`;
}
// ── Service factory ──────────────────────────────────────────────────
@@ -277,7 +400,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
* `getApplicableConfigs` queries the DB for matching overrides and merges them by priority.
*
* When `baseOnly` is true, returns the YAML-derived config without any DB queries.
- * `role`, `userId`, and `tenantId` are ignored in this mode.
+ * `role` and `userId` are ignored; tenantId still scopes YAML custom endpoints.
* Use this for startup, auth strategies, and other pre-tenant code paths.
*/
async function getAppConfig(options: GetAppConfigOptions = {}): Promise<AppConfig> {
@@ -293,10 +416,21 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
skipRuntimeAugmentation,
} = options;
- const baseConfig = await ensureBaseConfig(refresh);
+ 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 baseConfig = await ensureBaseConfig(refresh);
+ const scopedBaseConfig = await scopeBaseConfig(baseConfig, effectiveTenantId);
+ const hiddenEndpoints = hiddenCustomEndpoints(baseConfig, effectiveTenantId);
if (baseOnly) {
- return baseConfig;
+ return scopedBaseConfig;
}
const principals =
@@ -307,7 +441,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
return null;
}));
if (principals === null) {
- return baseConfig;
+ return scopedBaseConfig;
}
// Strict isolation + no tenant anywhere (neither param nor ALS) is pathological: a
@@ -316,7 +450,7 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
// 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 baseConfig;
+ return scopedBaseConfig;
}
if (!tenantId && !getTenantId() && isStrictOverrideMode() && !_warnedNoTenantInStrictMode) {
@@ -328,17 +462,40 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
}
const augment = async (appConfig: AppConfig): Promise<AppConfig> => {
- if (augmentConfig == null || skipRuntimeAugmentation === true) return appConfig;
+ const scopedConfig = scopeCustomEndpoints(appConfig, effectiveTenantId, hiddenEndpoints);
+ if (augmentConfig == null || skipRuntimeAugmentation === true) return scopedConfig;
try {
- return await augmentConfig({ appConfig, baseConfig, principals, options });
+ 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 appConfig;
+ return scopedConfig;
}
};
- const cacheKey = overrideCacheKey(role, userId, tenantId);
+ const scopeVersion = createHash('sha256')
+ .update(
+ JSON.stringify([
+ baseConfig.endpoints?.custom?.map(({ name, tenantId }) => [name, tenantId]),
+ baseConfig.config?.endpoints?.custom?.map(({ name, tenantId }) => [name, tenantId]),
+ ]),
+ )
+ .digest('hex');
+ const cacheKey = overrideCacheKey(
+ role,
+ userId,
+ ambientTenantId ?? effectiveTenantId,
+ scopeVersion,
+ );
if (!refresh) {
const cachedMerged = (await cache.get(cacheKey)) as AppConfig | undefined;
if (cachedMerged) {
@@ -346,16 +503,20 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
}
}
- let merged = baseConfig;
+ let merged = scopedBaseConfig;
try {
const configs = await getApplicableConfigs(principals);
if (configs.length > 0) {
- merged = materializeConfigModelSpecs(mergeConfigOverrides(baseConfig, configs));
+ merged = scopeCustomEndpoints(
+ materializeConfigModelSpecs(mergeConfigOverrides(scopedBaseConfig, configs)),
+ effectiveTenantId,
+ hiddenEndpoints,
+ );
}
} catch (error) {
if (failClosed) throw error;
logger.error('[getAppConfig] Error resolving config overrides, falling back to base:', error);
- return baseConfig;
+ return scopedBaseConfig;
}
await cache.set(cacheKey, merged, overrideCacheTtl);
@@ -374,12 +535,12 @@ export function createAppConfigService(deps: AppConfigServiceDeps): {
/**
* Clear per-principal override caches. When `tenantId` is provided, only caches
- * matching `_OVERRIDE_:${tenantId}:*` are deleted. When omitted, ALL override
+ * matching `_OVERRIDE_:${tenantId}:tenant:*` are deleted. When omitted, ALL override
* caches are cleared.
*/
async function clearOverrideCache(tenantId?: string): Promise<void> {
const namespace = cacheKeys.APP_CONFIG;
- const overrideSegment = tenantId ? `_OVERRIDE_:${tenantId}:` : '_OVERRIDE_:';
+ 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
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 1521d5ffd6..dfc4bf8a03 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -9,6 +9,7 @@ import {
codeEnvironmentUserConfigSchema,
CODE_ENVIRONMENT_ADMISSION_MAX_MS,
excludedKeys,
+ endpointSchema,
resolveEndpointType,
webSearchSchema,
} from './config';
@@ -26,6 +27,52 @@ const endpointsConfig: TEndpointsConfig = {
Gemini: { type: EModelEndpoint.custom, userProvide: false, order: 9999 },
};
+describe('tenant-scoped custom endpoints', () => {
+ const endpoint = {
+ name: 'Private Gateway',
+ apiKey: 'test-key',
+ baseURL: 'https://gateway.example',
+ models: { default: ['test-model'] },
+ };
+
+ it('keeps unscoped endpoints backward compatible', () => {
+ expect(endpointSchema.parse(endpoint)).not.toHaveProperty('tenantId');
+ });
+
+ it.each(['tenant-a', 'tenant_123.example', '-tenant', 'a'.repeat(128)])(
+ 'preserves the exact valid tenant ID %s',
+ (tenantId) => {
+ expect(endpointSchema.parse({ ...endpoint, tenantId }).tenantId).toBe(tenantId);
+ expect(
+ configSchema.parse({ version: '1.2.1', endpoints: { custom: [{ ...endpoint, tenantId }] } })
+ .endpoints?.custom?.[0].tenantId,
+ ).toBe(tenantId);
+ },
+ );
+
+ it.each([
+ '',
+ ' ',
+ ' tenant-a',
+ 'tenant-a ',
+ 'tenant a',
+ 'tenant/a',
+ 'tenant:a',
+ 'tenant\\a',
+ 'tenant😀',
+ '__SYSTEM__',
+ 'a'.repeat(129),
+ ])('rejects the unreachable tenant ID %j', (tenantId) => {
+ expect(endpointSchema.safeParse({ ...endpoint, tenantId }).success).toBe(false);
+ expect(
+ configSchema.safeParse({
+ version: '1.2.1',
+ endpoints: { custom: [{ ...endpoint, tenantId }] },
+ }).success,
+ ).toBe(false);
+ });
+});
+
describe('agent model response timeouts', () => {
it('ships finite defaults and accepts explicit overrides including disabled timeouts', () => {
expect(agentsEndpointSchema.parse({})).toMatchObject({
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 697537a677..a8e86e9dfe 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -1731,6 +1731,14 @@ export const endpointSchema = baseEndpointSchema.merge(
EModelEndpoint,
).join(', ')}`,
}),
+ /** Limit this YAML custom endpoint to one tenant. Omit for deployment-wide endpoints. */
+ tenantId: z
+ .string()
+ .min(1)
+ .max(128)
+ .regex(/^[-a-zA-Z0-9_.]+$/, 'must be a valid tenant id without whitespace')
+ .refine((tenantId) => tenantId !== '__SYSTEM__', 'system tenant is not allowed')
+ .optional(),
apiKey: z.string(),
/** Masked preview of the API key, stored at write time so admin
* reads can show which key is configured without returning the secret. */