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

🔑 fix: Use Admin-Stored Web Search Credentials at Runtime (#17323)

Danny Avila9ea3c5647dc9
diff --git a/api/server/routes/admin/config.test.js b/api/server/routes/admin/config.test.js
index 7ecaa644e3..62a9f79e7d 100644
--- a/api/server/routes/admin/config.test.js
+++ b/api/server/routes/admin/config.test.js
@@ -148,6 +148,8 @@ describe('admin config routes', () => {
expect.anything(),
{ 'endpoints.bedrock.inferenceProfiles': { [PROFILE]: ARN } },
expect.any(Number),
+ undefined,
+ undefined,
);
expect(response.body.config.overrides.endpoints.bedrock.inferenceProfiles).toEqual({
[PROFILE]: ARN,
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 1be31bf6c1..15215eb6e8 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -1511,6 +1511,14 @@ endpoints:
# # https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/assistants_endpoint
# Web Search Configuration (optional)
+# Keys and URLs are usually `${ENV_VAR}` references. A literal value, or a key saved
+# through the admin config API (encrypted at rest), is used as a system credential.
+# A key reaches a URL written in config only when both are set in the same place
+# (this file, or one admin config profile), and a later profile that changes, blanks
+# or removes that URL without storing the key again drops it. An environment key or
+# a user's own key never reaches a URL written in config. Reference both from the
+# environment, or set both together. The admin config API asks for a stored key
+# again when a write changes or removes the URL beside it.
# webSearch:
# # Jina Reranking Configuration
# jinaApiKey: '${JINA_API_KEY}' # Your Jina API key
diff --git a/packages/api/src/admin/binding.ts b/packages/api/src/admin/binding.ts
new file mode 100644
index 0000000000..1f7df1d334
--- /dev/null
+++ b/packages/api/src/admin/binding.ts
@@ -0,0 +1,184 @@
+import isPlainObject from 'lodash/isPlainObject';
+import { webSearchPairedFields, getRebindingWebSearchKeys } from '@librechat/data-schemas';
+import type { Config, ConfigOverrideIssue } from '@librechat/data-schemas';
+
+/** Issue code for a URL a write changed while the secret stored beside it stays. */
+export const SECRET_REENTRY_REQUIRED = 'secret_reentry_required';
+
+/** A URL whose stored secret must be entered again in the same write. */
+export interface SecretReentryIssue extends ConfigOverrideIssue {
+ /** Dot-path of the stored secret to enter again. */
+ secretPath: string;
+}
+
+/** The parts of a stored config document a re-entry check reads. */
+export type StoredConfigState = Pick<Config, 'overrides' | 'tombstones'> | null | undefined;
+
+type ConfigFields = Record<string, unknown>;
+
+const WEB_SEARCH = 'webSearch';
+const WEB_SEARCH_PREFIX = `${WEB_SEARCH}.`;
+const PAIRED_FIELDS: ReadonlySet<string> = new Set(webSearchPairedFields);
+
+function getRecord(value: unknown): ConfigFields | undefined {
+ return isPlainObject(value) ? (value as ConfigFields) : undefined;
+}
+
+function getWebSearch(overrides: unknown): ConfigFields | undefined {
+ return getRecord(getRecord(overrides)?.[WEB_SEARCH]);
+}
+
+/** The paired web search field a dot-path names directly, such as `searxngInstanceUrl`. */
+function getPairedField(fieldPath: string): string | undefined {
+ if (!fieldPath.startsWith(WEB_SEARCH_PREFIX)) {
+ return undefined;
+ }
+ const field = fieldPath.slice(WEB_SEARCH_PREFIX.length);
+ return PAIRED_FIELDS.has(field) ? field : undefined;
+}
+
+/**
+ * A document's own web search values as the re-entry rule compares them. A
+ * paired field the document tombstones and does not set reads as `null`,
+ * since the tombstone suppresses the inherited value as a `null` would.
+ */
+function getWebSearchView(
+ webSearch: ConfigFields | undefined,
+ tombstones: readonly string[] = [],
+): ConfigFields | undefined {
+ const suppressed: readonly string[] = tombstones.includes(WEB_SEARCH)
+ ? webSearchPairedFields
+ : tombstones.flatMap((path) => getPairedField(path) ?? []);
+ if (suppressed.length === 0) {
+ return webSearch;
+ }
+ const view: ConfigFields = {};
+ for (const field of suppressed) {
+ view[field] = null;
+ }
+ return { ...view, ...webSearch };
+}
+
+function toReentryIssues(
+ stored: ConfigFields | undefined,
+ next: ConfigFields | undefined,
+ written: ReadonlySet<string>,
+): SecretReentryIssue[] {
+ return getRebindingWebSearchKeys(stored, next, written).map(({ url, apiKey }) => ({
+ path: `${WEB_SEARCH_PREFIX}${url}`,
+ segments: [WEB_SEARCH, url],
+ code: SECRET_REENTRY_REQUIRED,
+ secretPath: `${WEB_SEARCH_PREFIX}${apiKey}`,
+ }));
+}
+
+/**
+ * Whether writing, removing or tombstoning this path can change where a
+ * stored web search key is sent. Such a write must apply to the document
+ * version its re-entry check read.
+ */
+export function isWebSearchBindingPath(fieldPath: string): boolean {
+ return fieldPath === WEB_SEARCH || getPairedField(fieldPath) != null;
+}
+
+/** Whether a full replace of a document's overrides writes its web search section. */
+export function hasWebSearchSection(overrides: unknown): boolean {
+ return getRecord(overrides)?.[WEB_SEARCH] !== undefined;
+}
+
+/**
+ * Re-entry issues for a write that replaces a document's overrides. Its
+ * tombstones stay as stored.
+ * @param stored - The document before the write.
+ * @param input - The overrides the request supplied.
+ * @param next - The overrides the write would store, omitted secrets preserved.
+ */
+export function getReplaceReentryIssues(
+ stored: StoredConfigState,
+ input: unknown,
+ next: unknown,
+): SecretReentryIssue[] {
+ const tombstones = stored?.tombstones;
+ const written = new Set(Object.keys(getWebSearch(input) ?? {}));
+ return toReentryIssues(
+ getWebSearchView(getWebSearch(stored?.overrides), tombstones),
+ getWebSearchView(getWebSearch(next), tombstones),
+ written,
+ );
+}
+
+/**
+ * Re-entry issues for a field patch, which sets each dot-path on the stored
+ * document and clears the tombstone at each written path.
+ * @param stored - The document before the write.
+ * @param input - The field paths and values the request supplied.
+ * @param next - The field paths and values the write would set, omitted secrets preserved.
+ */
+export function getPatchReentryIssues(
+ stored: StoredConfigState,
+ input: ConfigFields,
+ next: ConfigFields,
+): SecretReentryIssue[] {
+ const storedWebSearch = getWebSearch(stored?.overrides);
+ let nextWebSearch = storedWebSearch;
+ const written = new Set<string>();
+ if (WEB_SEARCH in next) {
+ nextWebSearch = getRecord(next[WEB_SEARCH]);
+ for (const field of Object.keys(getRecord(input[WEB_SEARCH]) ?? {})) {
+ written.add(field);
+ }
+ }
+ for (const [path, value] of Object.entries(next)) {
+ const field = path.startsWith(WEB_SEARCH_PREFIX) ? path.slice(WEB_SEARCH_PREFIX.length) : '';
+ if (field === '' || field.includes('.')) {
+ continue;
+ }
+ nextWebSearch = { ...nextWebSearch, [field]: value };
+ if (path in input) {
+ written.add(field);
+ }
+ }
+ if (nextWebSearch === storedWebSearch) {
+ return [];
+ }
+ const tombstones = stored?.tombstones ?? [];
+ return toReentryIssues(
+ getWebSearchView(storedWebSearch, tombstones),
+ getWebSearchView(
+ nextWebSearch,
+ tombstones.filter((path) => !(path in next)),
+ ),
+ written,
+ );
+}
+
+/**
+ * Re-entry issues for removing one field path from a document: a field delete
+ * unsets the value and clears tombstones at and below the path, and a
+ * tombstone unsets the value and suppresses the inherited one.
+ * @param stored - The document before the write.
+ * @param fieldPath - The dot-path the write removes.
+ * @param tombstone - Whether the write tombstones the path rather than deleting it.
+ */
+export function getRemovalReentryIssues(
+ stored: StoredConfigState,
+ fieldPath: string,
+ tombstone: boolean,
+): SecretReentryIssue[] {
+ const field = getPairedField(fieldPath);
+ if (field == null) {
+ return [];
+ }
+ const storedWebSearch = getWebSearch(stored?.overrides);
+ const nextWebSearch = { ...storedWebSearch };
+ delete nextWebSearch[field];
+ const tombstones = stored?.tombstones ?? [];
+ const nextTombstones = tombstone
+ ? [...tombstones, fieldPath]
+ : tombstones.filter((path) => path !== fieldPath && !path.startsWith(`${fieldPath}.`));
+ return toReentryIssues(
+ getWebSearchView(storedWebSearch, tombstones),
+ getWebSearchView(nextWebSearch, nextTombstones),
+ new Set(),
+ );
+}
diff --git a/packages/api/src/admin/config.dotted.integration.spec.ts b/packages/api/src/admin/config.dotted.integration.spec.ts
index 57377ddbd4..fd83f3034a 100644
--- a/packages/api/src/admin/config.dotted.integration.spec.ts
+++ b/packages/api/src/admin/config.dotted.integration.spec.ts
@@ -368,6 +368,22 @@ describe('admin config writes on an engine that cannot store dotted keys', () =>
},
}),
],
+ [
+ 'a version-checked PATCH',
+ (role: string) =>
+ patchFields(role, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: 'https://searx.example.com' },
+ { fieldPath: 'endpoints.bedrock.inferenceProfiles', value: { [PROFILE]: ARN } },
+ ]),
+ ],
+ [
+ 'a version-checked PUT',
+ (role: string) =>
+ putOverrides(role, {
+ webSearch: { safeSearch: 2 },
+ endpoints: { bedrock: { inferenceProfiles: { [PROFILE]: ARN } } },
+ }),
+ ],
])('answers %s with 422 CONFIG_KEY_NOT_STORABLE, not an uncoded 500', async (_label, write) => {
const role = nextRole();
const response = await write(role).expect(422);
diff --git a/packages/api/src/admin/config.handler.spec.ts b/packages/api/src/admin/config.handler.spec.ts
index 30072d6e49..fb2d9ccce3 100644
--- a/packages/api/src/admin/config.handler.spec.ts
+++ b/packages/api/src/admin/config.handler.spec.ts
@@ -820,7 +820,13 @@ describe('createAdminConfigHandlers', () => {
await handlers.deleteConfigField(req, res);
- expect(deps.unsetConfigField).toHaveBeenCalledWith('role', 'admin', 'interface.modelSelect');
+ expect(deps.unsetConfigField).toHaveBeenCalledWith(
+ 'role',
+ 'admin',
+ 'interface.modelSelect',
+ undefined,
+ undefined,
+ );
});
it('allows deleting mcpServers UI sub-key paths', async () => {
@@ -838,6 +844,8 @@ describe('createAdminConfigHandlers', () => {
'role',
'admin',
'interface.mcpServers.placeholder',
+ undefined,
+ undefined,
);
});
@@ -901,6 +909,8 @@ describe('createAdminConfigHandlers', () => {
'role',
'admin',
'skillSync.github.enabled',
+ undefined,
+ undefined,
);
});
@@ -915,7 +925,13 @@ describe('createAdminConfigHandlers', () => {
await handlers.deleteConfigField(req, res);
expect(res.statusCode).toBe(200);
- expect(deps.unsetConfigField).toHaveBeenCalledWith('role', 'admin', 'interface.modelSelect');
+ expect(deps.unsetConfigField).toHaveBeenCalledWith(
+ 'role',
+ 'admin',
+ 'interface.modelSelect',
+ undefined,
+ undefined,
+ );
});
it('ignores tenant-wide Langfuse deletes through the generic config API', async () => {
@@ -993,6 +1009,8 @@ describe('createAdminConfigHandlers', () => {
expect.anything(),
'mcpServers.github',
10,
+ undefined,
+ undefined,
);
});
@@ -1014,6 +1032,8 @@ describe('createAdminConfigHandlers', () => {
expect.anything(),
'mcpServers.github',
42,
+ undefined,
+ undefined,
);
});
@@ -2461,9 +2481,43 @@ describe('createAdminConfigHandlers', () => {
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
+ expect(getAppConfig).toHaveBeenCalledTimes(1);
expect(getAppConfig).toHaveBeenCalledWith(expect.objectContaining({ baseOnly: true }));
});
+ it('previews a plaintext secret an override stored, never one librechat.yaml supplies', async () => {
+ const yaml = {
+ webSearch: {
+ serperApiKey: 'serper-yaml-literal-0001',
+ keenableApiKey: '${KEENABLE_API_KEY}',
+ },
+ };
+ const merged = {
+ webSearch: {
+ serperApiKey: 'serper-yaml-literal-0001',
+ keenableApiKey: 'kn-legacy-plain-0002',
+ },
+ };
+ const getAppConfig = jest.fn(async ({ baseOnly }: { baseOnly?: boolean }) =>
+ baseOnly ? yaml : merged,
+ );
+ const { handlers } = createHandlers({ getAppConfig });
+
+ const res = mockRes();
+ await handlers.getBaseConfig(mockReq(), res);
+ const baseOnlyRes = mockRes();
+ await handlers.getBaseConfig(mockReq({ query: { baseOnly: 'true' } }), baseOnlyRes);
+
+ expect(res.statusCode).toBe(200);
+ expect(JSON.stringify(res.body)).not.toContain('kn-legacy-plain-0002');
+ expect((res.body!.config as typeof merged).webSearch).toEqual({
+ keenableApiKeyPreview: '...0002',
+ });
+ expect((baseOnlyRes.body!.config as typeof yaml).webSearch).toEqual({
+ keenableApiKey: '${KEENABLE_API_KEY}',
+ });
+ });
+
it('forwards baseOnly=false when the query param is missing, non-"true", or an array', async () => {
const cases: Array<Record<string, unknown>> = [
{},
@@ -2483,7 +2537,10 @@ describe('createAdminConfigHandlers', () => {
await handlers.getBaseConfig(req, res);
expect(res.statusCode).toBe(200);
- expect(getAppConfig).toHaveBeenCalledWith(expect.objectContaining({ baseOnly: false }));
+ expect(getAppConfig).toHaveBeenNthCalledWith(
+ 1,
+ expect.objectContaining({ baseOnly: false }),
+ );
}
});
});
diff --git a/packages/api/src/admin/config.ts b/packages/api/src/admin/config.ts
index f56d301a59..1716eb2978 100644
--- a/packages/api/src/admin/config.ts
+++ b/packages/api/src/admin/config.ts
@@ -20,17 +20,19 @@ import {
isProcessMCPServerField,
} from 'librechat-data-provider';
import type {
+ IConfig,
AppConfig,
ConfigSection,
- IConfig,
SystemCapability,
ConfigOverrideIssue,
+ ConfigWritePrecondition,
} from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
import type { Types, ClientSession } from 'mongoose';
import type { Response } from 'express';
import type { AdminAuditEvent, RecordAuditEntry } from './audit';
import type { CapabilityUser } from '~/middleware/capabilities';
+import type { SecretReentryIssue } from './binding';
import type { ServerRequest } from '~/types/http';
import {
encryptConfigSecretFields,
@@ -44,6 +46,13 @@ import {
preserveConfigSecrets,
redactConfigSecrets,
} from './secrets';
+import {
+ hasWebSearchSection,
+ getPatchReentryIssues,
+ isWebSearchBindingPath,
+ getRemovalReentryIssues,
+ getReplaceReentryIssues,
+} from './binding';
import { DEFAULT_OVERRIDE_CACHE_TTL } from '~/app/service';
import { getSafeErrorMetadata } from '~/utils/errors';
import { createAdminAuditEmitter } from './audit';
@@ -200,8 +209,9 @@ export interface AdminConfigDeps {
overrides: Partial<TCustomConfig>,
priority: number,
session?: ClientSession,
- options?: { expectEmpty?: boolean; preservePriority?: boolean },
+ options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,
) => Promise<IConfig | null>;
+ /** Resolves to `null` only when `options.expectedVersion` no longer holds. */
patchConfigFields: (
principalType: PrincipalType,
principalId: string | Types.ObjectId,
@@ -209,6 +219,7 @@ export interface AdminConfigDeps {
fields: Record<string, unknown>,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
tombstoneConfigField: (
principalType: PrincipalType,
@@ -217,12 +228,14 @@ export interface AdminConfigDeps {
fieldPath: string,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
unsetConfigField: (
principalType: PrincipalType,
principalId: string | Types.ObjectId,
fieldPath: string,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
deleteConfig: (
principalType: PrincipalType,
@@ -433,14 +446,20 @@ function collectAppConfigSections(appConfig: AppConfig): string[] {
function redactConfigForResponse(config: IConfig): IConfig {
const safeConfig = JSON.parse(JSON.stringify(config)) as IConfig;
if (safeConfig.overrides) {
- redactConfigSecrets(safeConfig.overrides);
+ redactConfigSecrets(safeConfig.overrides, { previewPlaintext: true });
}
return safeConfig;
}
-function redactAppConfigForResponse(appConfig: AppConfig): AppConfig {
+/**
+ * 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);
+ redactConfigSecrets(safeConfig, { previewPlaintext: yamlConfig != null, yamlConfig });
if (safeConfig.config != null && typeof safeConfig.config === 'object') {
redactConfigSecrets(safeConfig.config);
}
@@ -474,6 +493,40 @@ function unstorableKeyResponse(res: Response, operation: string): Response {
});
}
+/**
+ * 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,
+ })),
+ });
+}
+
+/**
+ * Rejects a write whose re-entry check read a document version another write
+ * has since replaced, so the check never approves a state it did not see.
+ */
+function versionConflictResponse(res: Response): Response {
+ return res.status(409).json({
+ error: 'The config changed while this write was being checked. Reload it and try again.',
+ code: 'CONFIG_VERSION_CONFLICT',
+ });
+}
+
+/** The version a binding write must apply to: the one read, or `null` when no document existed. */
+function readVersion(config: IConfig | null | undefined): ConfigWritePrecondition {
+ return { expectedVersion: config?.configVersion ?? null };
+}
+
function preservePatchedConfigSecretFields(
fields: Record<string, unknown>,
existingOverrides?: unknown,
@@ -616,15 +669,17 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
const baseOnly = (req.query as Record<string, unknown>).baseOnly === 'true';
- const appConfig = await getAppConfig({
- tenantId: user.tenantId,
- baseOnly,
- });
+ const [appConfig, yamlConfig] = await Promise.all([
+ getAppConfig({ tenantId: user.tenantId, baseOnly }),
+ 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) });
+ 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' });
@@ -862,6 +917,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
encryptedOverrides,
existingConfig?.overrides,
);
+ const reentryIssues = getReplaceReentryIssues(stored, filteredOverrides, preservedOverrides);
+ if (reentryIssues.length > 0) {
+ return secretReentryResponse(res, reentryIssues);
+ }
+ const precondition: ConfigWritePrecondition = hasWebSearchSection(filteredOverrides)
+ ? readVersion(stored)
+ : {};
if (needsProtectedBaseSections) {
for (const section of BASE_PRINCIPAL_OVERRIDE_SECTIONS) {
const storedSection = (
@@ -879,8 +941,11 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
preservedOverrides,
requestedPriority,
undefined,
- upsertOptions,
+ { ...upsertOptions, ...precondition },
);
+ if (!config && precondition.expectedVersion !== undefined) {
+ return versionConflictResponse(res);
+ }
if (!config && !hasBroadManage) {
return res.status(403).json({ error: 'Insufficient permissions' });
}
@@ -1064,6 +1129,13 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
encryptedFields,
existing?.overrides,
);
+ const reentryIssues = getPatchReentryIssues(existing, fields, preservedFields);
+ if (reentryIssues.length > 0) {
+ return secretReentryResponse(res, reentryIssues);
+ }
+ const precondition = Object.keys(fields).some(isWebSearchBindingPath)
+ ? readVersion(existing)
+ : undefined;
const config = await patchConfigFields(
principalType,
@@ -1071,7 +1143,12 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
principalModel(principalType),
preservedFields,
requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,
+ undefined,
+ precondition,
);
+ if (!config && precondition) {
+ return versionConflictResponse(res);
+ }
invalidateConfigCaches?.(user.tenantId)?.catch((err) =>
logger.error('[adminConfig] Cache invalidation failed after patch:', err),
@@ -1177,23 +1254,35 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
}
const requestedPriority = hasBroadManage ? priority : undefined;
+ const binding = isWebSearchBindingPath(fieldPath);
const existing =
- requestedPriority == null
+ requestedPriority == null || binding
? await findConfigByPrincipal(principalType, principalId, { includeInactive: true })
: null;
+ const reentryIssues = getRemovalReentryIssues(existing, fieldPath, true);
+ if (reentryIssues.length > 0) {
+ return secretReentryResponse(res, reentryIssues);
+ }
+ const precondition = binding ? readVersion(existing) : undefined;
let config: IConfig | null = null;
/** Each write bumps configVersion, so creation is read off the first write only. */
let created = false;
try {
- for (const path of getConfigSecretMutationPaths(fieldPath)) {
+ const paths = getConfigSecretMutationPaths(fieldPath);
+ for (let i = 0; i < paths.length; i++) {
const fieldConfig = await writeConfigTombstone(
principalType,
principalId,
principalModel(principalType),
- path,
+ paths[i],
requestedPriority ?? existing?.priority ?? DEFAULT_PRIORITY,
+ undefined,
+ i === 0 ? precondition : undefined,
);
+ if (!fieldConfig && i === 0 && precondition) {
+ return versionConflictResponse(res);
+ }
if (fieldConfig) {
created ||= config == null && fieldConfig.configVersion === 1;
config = fieldConfig;
@@ -1304,10 +1393,33 @@ export function createAdminConfigHandlers(deps: AdminConfigDeps): {
return res.status(200).json({ message: 'No actionable field path provided' });
}
+ const binding = isWebSearchBindingPath(fieldPath);
+ const existing = binding
+ ? await findConfigByPrincipal(principalType, principalId, { includeInactive: true })
+ : undefined;
+ if (binding && !existing) {
+ return res.status(404).json({ error: 'Config not found' });
+ }
+ const reentryIssues = getRemovalReentryIssues(existing, fieldPath, false);
+ if (reentryIssues.length > 0) {
+ return secretReentryResponse(res, reentryIssues);
+ }
+ const precondition = binding ? readVersion(existing) : undefined;
+
let config: IConfig | null = null;
try {
- for (const path of getConfigSecretMutationPaths(fieldPath)) {
- const fieldConfig = await unsetConfigField(principalType, principalId, path);
+ const paths = getConfigSecretMutationPaths(fieldPath);
+ for (let i = 0; i < paths.length; i++) {
+ const fieldConfig = await unsetConfigField(
+ principalType,
+ principalId,
+ paths[i],
+ undefined,
+ i === 0 ? precondition : undefined,
+ );
+ if (!fieldConfig && i === 0 && precondition) {
+ return versionConflictResponse(res);
+ }
if (fieldConfig) {
config = fieldConfig;
}
diff --git a/packages/api/src/admin/meta.spec.ts b/packages/api/src/admin/meta.spec.ts
index 0f134f16e7..79001ab72d 100644
--- a/packages/api/src/admin/meta.spec.ts
+++ b/packages/api/src/admin/meta.spec.ts
@@ -1,10 +1,17 @@
import { join } from 'path';
import { readFileSync } from 'fs';
import mongoSanitize from 'express-mongo-sanitize';
-import { mergeConfigOverrides, getConfigOverrideIssues } from '@librechat/data-schemas';
+import {
+ loadWebSearchConfig,
+ mergeConfigOverrides,
+ getConfigOverrideIssues,
+} from '@librechat/data-schemas';
import {
Constants,
configSchema,
+ RerankerTypes,
+ SearchProviders,
+ ScraperProviders,
PERMISSION_SUB_KEYS,
BASE_ONLY_CONFIG_PATHS,
BASE_ONLY_CONFIG_SECTIONS,
@@ -23,9 +30,16 @@ import type { Request, Response } from 'express';
import type { ServerRequest } from '~/types/http';
import type { AdminConfigDeps } from './config';
import { createRequestSanitizer, rejectUnsafeConfigKeys } from '~/middleware/sanitize';
+import { redactConfigSecrets, encryptConfigSecretFields } from './secrets';
import { createAdminConfigHandlers } from './config';
-import { redactConfigSecrets } from './secrets';
import { ADMIN_CONFIG_FEATURES } from './meta';
+import { loadWebSearchAuth } from '~/web';
+
+/** Encryption reads `CREDS_KEY` when data-schemas loads, before any spec code runs. */
+jest.mock('@librechat/data-schemas', () => {
+ process.env.CREDS_KEY ??= '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+ return jest.requireActual('@librechat/data-schemas');
+});
type Doc = Record<string, unknown>;
type ResponseBody = { config?: { overrides: Doc }; [key: string]: unknown };
@@ -151,6 +165,7 @@ describe('GET /api/admin/config/meta', () => {
'dottedKeys',
'readFilteredWriteResponses',
'sectionAllowlist',
+ 'webSearchStoredKeys',
]);
expect(meta.limits).toEqual({ maxPatchEntries: 100, overrideCacheTtlMs: 60_000 });
expect(Object.keys(meta.rules).sort()).toEqual([
@@ -335,6 +350,45 @@ const FEATURE_PROBES: Record<AdminConfigFeatureFlag, () => Promise<boolean>> = {
const overrides = res.body?.config?.overrides;
return res.statusCode === 200 && overrides != null && !('memory' in overrides);
},
+ async webSearchStoredKeys() {
+ const keys = {
+ 'webSearch.serperApiKey': 'serper-admin-secret',
+ 'webSearch.searxngApiKey': 'searxng-admin-secret',
+ 'webSearch.keenableApiKey': 'keenable-admin-secret',
+ };
+ const stored = encryptConfigSecretFields(keys);
+ const encrypted = Object.keys(keys).every((path) => String(stored[path]).startsWith('v3:'));
+
+ const { authenticated, authResult } = await loadWebSearchAuth({
+ userId: 'meta-spec',
+ webSearchConfig: loadWebSearchConfig({
+ searchProvider: SearchProviders.SERPER,
+ scraperProvider: ScraperProviders.KEENABLE,
+ rerankerType: RerankerTypes.NONE,
+ keenableApiUrl: '',
+ serperApiKey: stored['webSearch.serperApiKey'] as string,
+ }),
+ loadAuthValues: jest.fn().mockResolvedValue({}),
+ });
+ const usesStoredKey = authenticated && authResult.serperApiKey === 'serper-admin-secret';
+
+ const rebinding = await patch(
+ [{ fieldPath: 'webSearch.searxngInstanceUrl', value: 'https://collector.example.com' }],
+ {
+ findConfigByPrincipal: jest.fn().mockResolvedValue(
+ storedConfig({
+ webSearch: {
+ searxngInstanceUrl: 'https://searx.example.com',
+ searxngApiKey: stored['webSearch.searxngApiKey'],
+ },
+ }),
+ ),
+ },
+ );
+ const requiresReentry =
+ rebinding.statusCode === 400 && rebinding.body?.code === 'CONFIG_SECRET_REENTRY_REQUIRED';
+ return encrypted && usesStoredKey && requiresReentry;
+ },
};
describe('meta feature flags', () => {
diff --git a/packages/api/src/admin/meta.ts b/packages/api/src/admin/meta.ts
index 3838255959..022c482fa2 100644
--- a/packages/api/src/admin/meta.ts
+++ b/packages/api/src/admin/meta.ts
@@ -23,6 +23,7 @@ export const ADMIN_CONFIG_FEATURES: Readonly<AdminConfigFeatures> = {
dottedKeys: true,
sectionAllowlist: false,
readFilteredWriteResponses: false,
+ webSearchStoredKeys: true,
};
/**
diff --git a/packages/api/src/admin/secrets.integration.spec.ts b/packages/api/src/admin/secrets.integration.spec.ts
index 8743eac7c0..93d1fd0bce 100644
--- a/packages/api/src/admin/secrets.integration.spec.ts
+++ b/packages/api/src/admin/secrets.integration.spec.ts
@@ -18,6 +18,11 @@ let handlers: AdminConfigHandlers;
let basePrincipalId: string;
let decryptV3: DataSchemas['decryptV3'];
let patchConfigFields: ConfigMethods['patchConfigFields'];
+let configMethods: ConfigMethods;
+/** Builds handlers on the real methods, optionally reading configs through `findConfigByPrincipal`. */
+let createHandlers: (
+ findConfigByPrincipal?: ConfigMethods['findConfigByPrincipal'],
+) => AdminConfigHandlers;
let getSecretPreview: typeof import('./secrets').getSecretPreview;
let encryptConfigSecretFields: typeof import('./secrets').encryptConfigSecretFields;
@@ -110,16 +115,16 @@ const SECRET_FIELD_CASES: SecretFieldCase[] = [
previewPath: 'webSearch.searxngApiKeyPreview',
section: 'webSearch',
object: { searxngApiKey: SECRET, searxngInstanceUrl: 'https://searx.example.com' },
- siblingPath: 'webSearch.searxngInstanceUrl',
- siblingValue: 'https://searx2.example.com',
+ siblingPath: 'webSearch.safeSearch',
+ siblingValue: 2,
},
{
path: 'webSearch.firecrawlApiKey',
previewPath: 'webSearch.firecrawlApiKeyPreview',
section: 'webSearch',
object: { firecrawlApiKey: SECRET, firecrawlApiUrl: 'https://api.firecrawl.dev' },
- siblingPath: 'webSearch.firecrawlApiUrl',
- siblingValue: 'https://api2.firecrawl.dev',
+ siblingPath: 'webSearch.firecrawlVersion',
+ siblingValue: 'v2',
},
{
path: 'webSearch.tavilyApiKey',
@@ -129,13 +134,21 @@ const SECRET_FIELD_CASES: SecretFieldCase[] = [
siblingPath: 'webSearch.scraperTimeout',
siblingValue: 8000,
},
+ {
+ path: 'webSearch.keenableApiKey',
+ previewPath: 'webSearch.keenableApiKeyPreview',
+ section: 'webSearch',
+ object: { keenableApiKey: SECRET, keenableApiUrl: 'https://api.keenable.ai' },
+ siblingPath: 'webSearch.scraperTimeout',
+ siblingValue: 9000,
+ },
{
path: 'webSearch.jinaApiKey',
previewPath: 'webSearch.jinaApiKeyPreview',
section: 'webSearch',
object: { jinaApiKey: SECRET, jinaApiUrl: 'https://r.jina.ai' },
- siblingPath: 'webSearch.jinaApiUrl',
- siblingValue: 'https://r2.jina.ai',
+ siblingPath: 'webSearch.rerankerType',
+ siblingValue: 'jina',
},
{
path: 'webSearch.cohereApiKey',
@@ -168,6 +181,7 @@ const PLACEHOLDER_CASES = [
{ path: 'ocr.apiKey', placeholder: '${OCR_API_KEY}' },
{ path: 'speech.tts.openai.apiKey', placeholder: '${TTS_API_KEY}' },
{ path: 'webSearch.serperApiKey', placeholder: '${SERPER_API_KEY}' },
+ { path: 'webSearch.keenableApiKey', placeholder: '${KEENABLE_API_KEY}' },
{ path: 'endpoints.assistants.apiKey', placeholder: '${ASSISTANTS_API_KEY}' },
];
@@ -250,21 +264,24 @@ beforeAll(async () => {
await mongoose.connect(mongoServer.getUri());
dataSchemas.createModels(mongoose);
const methods = dataSchemas.createMethods(mongoose);
+ configMethods = methods;
({ patchConfigFields } = methods);
- handlers = createAdminConfigHandlers({
- listAllConfigs: methods.listAllConfigs,
- findConfigByPrincipal: methods.findConfigByPrincipal,
- upsertConfig: methods.upsertConfig,
- patchConfigFields: methods.patchConfigFields,
- tombstoneConfigField: methods.tombstoneConfigField,
- unsetConfigField: methods.unsetConfigField,
- deleteConfig: methods.deleteConfig,
- toggleConfigActiveTracked: methods.toggleConfigActiveTracked,
- hasConfigCapability: async () => true,
- hasAnyConfigReadAccess: async () => true,
- hasCapability: async () => true,
- });
+ createHandlers = (findConfigByPrincipal = methods.findConfigByPrincipal) =>
+ createAdminConfigHandlers({
+ listAllConfigs: methods.listAllConfigs,
+ findConfigByPrincipal,
+ upsertConfig: methods.upsertConfig,
+ patchConfigFields: methods.patchConfigFields,
+ tombstoneConfigField: methods.tombstoneConfigField,
+ unsetConfigField: methods.unsetConfigField,
+ deleteConfig: methods.deleteConfig,
+ toggleConfigActiveTracked: methods.toggleConfigActiveTracked,
+ hasConfigCapability: async () => true,
+ hasAnyConfigReadAccess: async () => true,
+ hasCapability: async () => true,
+ });
+ handlers = createHandlers();
});
afterAll(async () => {
@@ -657,8 +674,9 @@ describe('config secret registry — real handlers against a real Config collect
});
describe('legacy plaintext literals stored before encryption existed', () => {
- it('never returns a plaintext literal stored directly on the config document', async () => {
- const principalId = nextPrincipalId();
+ const LEGACY_KEENABLE_KEY = 'kn-legacy-plain-0002';
+
+ async function createLegacyConfig(principalId: string): Promise<void> {
await mongoose.models.Config.create({
principalType: 'role',
principalId,
@@ -667,27 +685,613 @@ describe('config secret registry — real handlers against a real Config collect
overrides: {
speech: { tts: { openai: { apiKey: SECRET, model: 'tts-1' } } },
ocr: { apiKey: SECRET },
- webSearch: { serperApiKey: SECRET, searchProvider: 'serper' },
+ webSearch: {
+ serperApiKey: SECRET,
+ searchProvider: 'serper',
+ keenableApiKey: LEGACY_KEENABLE_KEY,
+ keenableApiUrl: 'https://keenable.example.com',
+ },
},
});
+ }
+ async function readOverrides(principalId: string): Promise<Record<string, unknown>> {
const getRes = mockRes();
await handlers.getConfig(mockReq({ params: { principalType: 'role', principalId } }), getRes);
expect(getRes.statusCode).toBe(200);
expect(JSON.stringify(getRes.body)).not.toContain(SECRET);
- const overrides = (getRes.body!.config as { overrides: Record<string, unknown> }).overrides;
+ expect(JSON.stringify(getRes.body)).not.toContain(LEGACY_KEENABLE_KEY);
+ return (getRes.body!.config as { overrides: Record<string, unknown> }).overrides;
+ }
+
+ it('shows a plaintext literal stored on the config document as set, never its value', async () => {
+ const principalId = nextPrincipalId();
+ await createLegacyConfig(principalId);
+
+ const overrides = await readOverrides(principalId);
expect(getAtPath(overrides, 'speech.tts.openai.model')).toBe('tts-1');
expect(getAtPath(overrides, 'webSearch.searchProvider')).toBe('serper');
- // Documents written before this field existed have no preview companion at all.
- // Redaction must not fabricate one — it only ever copies forward a companion
- // that a prior encrypt actually wrote.
- expect(getAtPath(overrides, 'speech.tts.openai.apiKeyPreview')).toBeUndefined();
- expect(getAtPath(overrides, 'ocr.apiKeyPreview')).toBeUndefined();
- expect(getAtPath(overrides, 'webSearch.serperApiKeyPreview')).toBeUndefined();
+ // The runtime still reads these values, so the read shows the preview their next save writes.
+ expect(getAtPath(overrides, 'speech.tts.openai.apiKeyPreview')).toBe(
+ getSecretPreview(SECRET),
+ );
+ expect(getAtPath(overrides, 'ocr.apiKeyPreview')).toBe(getSecretPreview(SECRET));
+ expect(getAtPath(overrides, 'webSearch.serperApiKeyPreview')).toBe(getSecretPreview(SECRET));
+ expect(getAtPath(overrides, 'webSearch.keenableApiKey')).toBeUndefined();
+ expect(getAtPath(overrides, 'webSearch.keenableApiKeyPreview')).toBe('...0002');
const listRes = mockRes();
await handlers.listConfigs(mockReq(), listRes);
expect(JSON.stringify(listRes.body)).not.toContain(SECRET);
+ expect(JSON.stringify(listRes.body)).not.toContain(LEGACY_KEENABLE_KEY);
+ });
+
+ it('keeps showing a legacy Keenable key after an unrelated patch, and encrypts it on a section save', async () => {
+ const principalId = nextPrincipalId();
+ await createLegacyConfig(principalId);
+
+ const patchRes = mockRes();
+ await handlers.patchConfigField(
+ mockReq({
+ params: { principalType: 'role', principalId },
+ body: { entries: [{ fieldPath: 'webSearch.scraperTimeout', value: 9000 }] },
+ }),
+ patchRes,
+ );
+ expect(patchRes.statusCode).toBe(200);
+ expect(JSON.stringify(patchRes.body)).not.toContain(LEGACY_KEENABLE_KEY);
+ expect(
+ getAtPath(
+ (patchRes.body!.config as { overrides: Record<string, unknown> }).overrides,
+ 'webSearch.keenableApiKeyPreview',
+ ),
+ ).toBe('...0002');
+ expect(getAtPath(await readOverrides(principalId), 'webSearch.keenableApiKeyPreview')).toBe(
+ '...0002',
+ );
+
+ const webSearch = getAtPath(await readOverrides(principalId), 'webSearch');
+ const saveRes = mockRes();
+ await handlers.patchConfigField(
+ mockReq({
+ params: { principalType: 'role', principalId },
+ body: { entries: [{ fieldPath: 'webSearch', value: webSearch }] },
+ }),
+ saveRes,
+ );
+ expect(saveRes.statusCode).toBe(200);
+
+ const raw = await readRawOverrides(principalId);
+ expect(getAtPath(raw, 'webSearch.keenableApiKey')).toMatch(/^v3:/);
+ expect(decryptV3(getAtPath(raw, 'webSearch.keenableApiKey') as string)).toBe(
+ LEGACY_KEENABLE_KEY,
+ );
+ expect(getAtPath(raw, 'webSearch.keenableApiKeyPreview')).toBe('...0002');
+ });
+ });
+
+ describe('a write that sends a stored web search key to a new URL', () => {
+ const STORED_KEY = 'sx-stored-secret-0001';
+ const STORED_URL = 'https://searx.example.com/base';
+ const NEW_URL = 'https://collector.example.com';
+ const SEARXNG_REENTRY = {
+ path: 'webSearch.searxngInstanceUrl',
+ segments: ['webSearch', 'searxngInstanceUrl'],
+ code: 'secret_reentry_required',
+ secretPath: 'webSearch.searxngApiKey',
+ };
+
+ type Entry = { fieldPath: string; value: unknown };
+
+ async function patch(principalId: string, entries: Entry[]): Promise<MockRes> {
+ const res = mockRes();
+ await handlers.patchConfigField(
+ mockReq({ params: { principalType: 'role', principalId }, body: { entries } }),
+ res,
+ );
+ return res;
+ }
+
+ async function replace(principalId: string, overrides: Record<string, unknown>) {
+ const res = mockRes();
+ await handlers.upsertConfigOverrides(
+ mockReq({ params: { principalType: 'role', principalId }, body: { overrides } }),
+ res,
+ );
+ return res;
+ }
+
+ async function storeSearxng(principalId: string): Promise<RawConfig> {
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: STORED_URL },
+ { fieldPath: 'webSearch.searxngApiKey', value: STORED_KEY },
+ ]);
+ expect(res.statusCode).toBe(200);
+ return readRawConfig(principalId);
+ }
+
+ /** The response a rejected write must give: paths and a stable code, never the key or the new URL. */
+ function reentryRequired(issues: Array<typeof SEARXNG_REENTRY>) {
+ return {
+ statusCode: 400,
+ body: { error: expect.any(String), code: 'CONFIG_SECRET_REENTRY_REQUIRED', issues },
+ payload: expect.not.stringMatching(new RegExp(`${STORED_KEY}|${NEW_URL}`)),
+ };
+ }
+
+ function response(res: MockRes) {
+ return { statusCode: res.statusCode, body: res.body, payload: JSON.stringify(res.body) };
+ }
+
+ it('rejects a dotted patch that changes only the URL and writes nothing', async () => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ ]);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects a section patch that changes the URL and omits the key', async () => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch', value: { searxngInstanceUrl: NEW_URL, safeSearch: 2 } },
+ ]);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects a full replace that changes the URL and omits the key', async () => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await replace(principalId, { webSearch: { searxngInstanceUrl: NEW_URL } });
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects adding a URL beside a key the document already stores', async () => {
+ const principalId = nextPrincipalId();
+ expect(
+ (await patch(principalId, [{ fieldPath: 'webSearch.searxngApiKey', value: STORED_KEY }]))
+ .statusCode,
+ ).toBe(200);
+ const before = await readRawConfig(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ ]);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('names the shared Tavily key once for each URL that changed', async () => {
+ const principalId = nextPrincipalId();
+ const stored = await patch(principalId, [
+ { fieldPath: 'webSearch.tavilySearchUrl', value: 'https://tavily.example.com/search' },
+ { fieldPath: 'webSearch.tavilyExtractUrl', value: 'https://tavily.example.com/extract' },
+ { fieldPath: 'webSearch.tavilyApiKey', value: STORED_KEY },
+ ]);
+ expect(stored.statusCode).toBe(200);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.tavilySearchUrl', value: `${NEW_URL}/search` },
+ { fieldPath: 'webSearch.tavilyExtractUrl', value: `${NEW_URL}/extract` },
+ ]);
+
+ expect(response(res)).toEqual(
+ reentryRequired([
+ {
+ path: 'webSearch.tavilySearchUrl',
+ segments: ['webSearch', 'tavilySearchUrl'],
+ code: 'secret_reentry_required',
+ secretPath: 'webSearch.tavilyApiKey',
+ },
+ {
+ path: 'webSearch.tavilyExtractUrl',
+ segments: ['webSearch', 'tavilyExtractUrl'],
+ code: 'secret_reentry_required',
+ secretPath: 'webSearch.tavilyApiKey',
+ },
+ ]),
+ );
+ });
+
+ it('rejects a URL change beside a plaintext key stored before encryption existed', async () => {
+ const principalId = nextPrincipalId();
+ await mongoose.models.Config.create({
+ principalType: 'role',
+ principalId,
+ principalModel: 'Role',
+ priority: 10,
+ overrides: {
+ webSearch: {
+ keenableApiKey: 'kn-legacy-plain-0003',
+ keenableApiUrl: 'https://keenable.example.com',
+ },
+ },
+ });
+ const before = await readRawConfig(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.keenableApiUrl', value: NEW_URL },
+ ]);
+
+ expect(res.statusCode).toBe(400);
+ expect(res.body!.issues).toEqual([
+ {
+ path: 'webSearch.keenableApiUrl',
+ segments: ['webSearch', 'keenableApiUrl'],
+ code: 'secret_reentry_required',
+ secretPath: 'webSearch.keenableApiKey',
+ },
+ ]);
+ expect(JSON.stringify(res.body)).not.toContain('kn-legacy-plain-0003');
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('stores a new URL with the key entered again in the same write', async () => {
+ const principalId = nextPrincipalId();
+ await storeSearxng(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ { fieldPath: 'webSearch.searxngApiKey', value: 'sx-reentered-0002' },
+ ]);
+
+ expect(res.statusCode).toBe(200);
+ const overrides = await readRawOverrides(principalId);
+ expect(getAtPath(overrides, 'webSearch.searxngInstanceUrl')).toBe(NEW_URL);
+ expect(decryptV3(getAtPath(overrides, 'webSearch.searxngApiKey') as string)).toBe(
+ 'sx-reentered-0002',
+ );
+ });
+
+ it('stores a new URL in a full replace that enters the key again', async () => {
+ const principalId = nextPrincipalId();
+ await storeSearxng(principalId);
+
+ const res = await replace(principalId, {
+ webSearch: { searxngInstanceUrl: NEW_URL, searxngApiKey: 'sx-reentered-0003' },
+ });
+
+ expect(res.statusCode).toBe(200);
+ const overrides = await readRawOverrides(principalId);
+ expect(decryptV3(getAtPath(overrides, 'webSearch.searxngApiKey') as string)).toBe(
+ 'sx-reentered-0003',
+ );
+ });
+
+ it.each([
+ {
+ name: 'points the URL at the environment',
+ entries: [{ fieldPath: 'webSearch.searxngInstanceUrl', value: '${SEARXNG_INSTANCE_URL}' }],
+ },
+ {
+ name: 'blanks the URL',
+ entries: [{ fieldPath: 'webSearch.searxngInstanceUrl', value: '' }],
+ },
+ {
+ name: 'replaces the section without the URL',
+ entries: [{ fieldPath: 'webSearch', value: { safeSearch: 2 } }],
+ },
+ ])('rejects a write that $name while the key stays', async ({ entries }) => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await patch(principalId, entries);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects a full replace whose section drops the URL while the key stays', async () => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await replace(principalId, { webSearch: { safeSearch: 2 } });
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects pointing an environment URL at another variable beside a stored key', async () => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: '${SEARXNG_INSTANCE_URL}' },
+ { fieldPath: 'webSearch.searxngApiKey', value: STORED_KEY },
+ ]);
+ const before = await readRawConfig(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: '${OTHER_SERVICE_URL}' },
+ ]);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it.each([
+ {
+ name: 'clears the key',
+ entries: [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ { fieldPath: 'webSearch.searxngApiKey', value: '' },
+ ],
+ },
+ {
+ name: 'turns the key into an environment reference',
+ entries: [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ { fieldPath: 'webSearch.searxngApiKey', value: '${SEARXNG_API_KEY}' },
+ ],
+ },
+ {
+ name: 'points the URL at the environment and enters the key again',
+ entries: [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: '${SEARXNG_INSTANCE_URL}' },
+ { fieldPath: 'webSearch.searxngApiKey', value: 'sx-reentered-0004' },
+ ],
+ },
+ {
+ name: 'writes the same URL again',
+ entries: [{ fieldPath: 'webSearch.searxngInstanceUrl', value: STORED_URL }],
+ },
+ {
+ name: 'replaces the section with the URL and without the key',
+ entries: [
+ { fieldPath: 'webSearch', value: { searxngInstanceUrl: STORED_URL, safeSearch: 2 } },
+ ],
+ },
+ ])('accepts a write that $name', async ({ entries }) => {
+ const principalId = nextPrincipalId();
+ await storeSearxng(principalId);
+
+ const res = await patch(principalId, entries);
+
+ expect(res.statusCode).toBe(200);
+ expect(JSON.stringify(res.body)).not.toContain(STORED_KEY);
+ });
+
+ async function removeField(
+ principalId: string,
+ fieldPath: string,
+ tombstone: boolean,
+ ): Promise<MockRes> {
+ const res = mockRes();
+ const params = { principalType: 'role', principalId };
+ if (tombstone) {
+ await handlers.tombstoneConfigField(mockReq({ params, body: { fieldPath } }), res);
+ } else {
+ await handlers.deleteConfigField(mockReq({ params, query: { fieldPath } }), res);
+ }
+ return res;
+ }
+
+ it.each([
+ { name: 'deleting', tombstone: false },
+ { name: 'tombstoning', tombstone: true },
+ ])('rejects $name the URL beside a stored key and writes nothing', async ({ tombstone }) => {
+ const principalId = nextPrincipalId();
+ const before = await storeSearxng(principalId);
+
+ const res = await removeField(principalId, 'webSearch.searxngInstanceUrl', tombstone);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects deleting a URL tombstone, which restores the inherited URL, beside a stored key', async () => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [{ fieldPath: 'webSearch.searxngApiKey', value: STORED_KEY }]);
+ await configMethods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ principalId,
+ PrincipalModel.ROLE,
+ 'webSearch.searxngInstanceUrl',
+ 10,
+ );
+ const before = await readRawConfig(principalId);
+
+ const res = await removeField(principalId, 'webSearch.searxngInstanceUrl', false);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it('rejects setting a URL the document tombstones beside a stored key', async () => {
+ const principalId = nextPrincipalId();
+ await configMethods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ principalId,
+ PrincipalModel.ROLE,
+ 'webSearch.searxngInstanceUrl',
+ 10,
+ );
+ expect(
+ (await patch(principalId, [{ fieldPath: 'webSearch.searxngApiKey', value: STORED_KEY }]))
+ .statusCode,
+ ).toBe(200);
+ const before = await readRawConfig(principalId);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ ]);
+
+ expect(response(res)).toEqual(reentryRequired([SEARXNG_REENTRY]));
+ expect(await readRawConfig(principalId)).toEqual(before);
+ });
+
+ it.each([
+ { name: 'deletes', tombstone: false },
+ { name: 'tombstones', tombstone: true },
+ ])('$name the URL once the key is removed first', async ({ tombstone }) => {
+ const principalId = nextPrincipalId();
+ await storeSearxng(principalId);
+
+ expect((await removeField(principalId, 'webSearch.searxngApiKey', false)).statusCode).toBe(
+ 200,
+ );
+ const res = await removeField(principalId, 'webSearch.searxngInstanceUrl', tombstone);
+
+ expect(res.statusCode).toBe(200);
+ const overrides = await readRawOverrides(principalId);
+ expect(getAtPath(overrides, 'webSearch.searxngInstanceUrl')).toBeUndefined();
+ expect(getAtPath(overrides, 'webSearch.searxngApiKey')).toBeUndefined();
+ });
+
+ it('removes the whole section with its key', async () => {
+ const principalId = nextPrincipalId();
+ await storeSearxng(principalId);
+
+ const res = await removeField(principalId, 'webSearch', false);
+
+ expect(res.statusCode).toBe(200);
+ expect(getAtPath(await readRawOverrides(principalId), 'webSearch')).toBeUndefined();
+ });
+
+ it('accepts a URL change where no key is stored beside it', async () => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: STORED_URL },
+ { fieldPath: 'webSearch.searxngApiKey', value: '${SEARXNG_API_KEY}' },
+ ]);
+
+ const res = await patch(principalId, [
+ { fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL },
+ ]);
+
+ expect(res.statusCode).toBe(200);
+ expect(getAtPath(await readRawOverrides(principalId), 'webSearch.searxngInstanceUrl')).toBe(
+ NEW_URL,
+ );
+ });
+
+ describe('when another admin stores a key between the check and the write', () => {
+ const VICTIM_URL = 'https://searx.example.com/victim';
+ const VICTIM_KEY = 'sx-victim-key-0005';
+
+ /** Handlers whose next config read is followed by another admin's URL-and-key write. */
+ function racedHandlers(principalId: string): AdminConfigHandlers {
+ let raced = false;
+ return createHandlers(async (...args) => {
+ const config = await configMethods.findConfigByPrincipal(...args);
+ if (!raced) {
+ raced = true;
+ await configMethods.patchConfigFields(
+ PrincipalType.ROLE,
+ principalId,
+ PrincipalModel.ROLE,
+ encryptConfigSecretFields({
+ 'webSearch.searxngInstanceUrl': VICTIM_URL,
+ 'webSearch.searxngApiKey': VICTIM_KEY,
+ }),
+ 10,
+ );
+ }
+ return config;
+ });
+ }
+
+ /** The response and the stored URL and key once the raced write returned. */
+ async function outcome(principalId: string, res: MockRes) {
+ const overrides = await readRawOverrides(principalId);
+ const key = getAtPath(overrides, 'webSearch.searxngApiKey');
+ return {
+ statusCode: res.statusCode,
+ body: res.body,
+ url: getAtPath(overrides, 'webSearch.searxngInstanceUrl'),
+ key: typeof key === 'string' ? decryptV3(key) : key,
+ };
+ }
+
+ const VICTIM_KEPT = {
+ statusCode: 409,
+ body: { error: expect.any(String), code: 'CONFIG_VERSION_CONFLICT' },
+ url: VICTIM_URL,
+ key: VICTIM_KEY,
+ };
+
+ const params = (principalId: string) => ({ principalType: 'role', principalId });
+
+ it.each([
+ { name: 'on an existing document', existing: true },
+ { name: 'on a document created meanwhile', existing: false },
+ ])('rejects a URL-only patch $name', async ({ existing }) => {
+ const principalId = nextPrincipalId();
+ if (existing) {
+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);
+ }
+ const res = mockRes();
+
+ await racedHandlers(principalId).patchConfigField(
+ mockReq({
+ params: params(principalId),
+ body: { entries: [{ fieldPath: 'webSearch.searxngInstanceUrl', value: NEW_URL }] },
+ }),
+ res,
+ );
+
+ expect(await outcome(principalId, res)).toEqual(VICTIM_KEPT);
+ });
+
+ it('rejects a full replace that sets only the URL', async () => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);
+ const res = mockRes();
+
+ await racedHandlers(principalId).upsertConfigOverrides(
+ mockReq({
+ params: params(principalId),
+ body: { overrides: { webSearch: { searxngInstanceUrl: NEW_URL } } },
+ }),
+ res,
+ );
+
+ expect(await outcome(principalId, res)).toEqual(VICTIM_KEPT);
+ });
+
+ it.each([
+ { name: 'deleting', handler: 'deleteConfigField' as const },
+ { name: 'tombstoning', handler: 'tombstoneConfigField' as const },
+ ])('rejects $name the URL', async ({ handler }) => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);
+ const res = mockRes();
+ const fieldPath = 'webSearch.searxngInstanceUrl';
+
+ await racedHandlers(principalId)[handler](
+ mockReq({ params: params(principalId), query: { fieldPath }, body: { fieldPath } }),
+ res,
+ );
+
+ expect(await outcome(principalId, res)).toEqual(VICTIM_KEPT);
+ });
+
+ it('lets a write to another section proceed', async () => {
+ const principalId = nextPrincipalId();
+ await patch(principalId, [{ fieldPath: 'webSearch.safeSearch', value: 1 }]);
+ const res = mockRes();
+
+ await racedHandlers(principalId).patchConfigField(
+ mockReq({
+ params: params(principalId),
+ body: { entries: [{ fieldPath: 'webSearch.safeSearch', value: 2 }] },
+ }),
+ res,
+ );
+
+ expect(res.statusCode).toBe(200);
+ expect(getAtPath(await readRawOverrides(principalId), 'webSearch.safeSearch')).toBe(2);
+ });
});
});
@@ -734,6 +1338,7 @@ describe('config secret registry — real handlers against a real Config collect
expect(getAtPath(config, 'speech.tts.openai.model')).toBe('tts-1');
expect(getAtPath(config, 'speech.tts.openai.apiKey')).toBeUndefined();
expect(getAtPath(config, 'speech.tts.openai.apiKeyPreview')).toBe(getSecretPreview(SECRET));
+ expect(getAtPath(config, 'webSearch.serperApiKeyPreview')).toBeUndefined();
expect(getAtPath(config, 'langfuse.secretKeyPreview')).toBe('*********');
expect(getAtPath(config, 'config.speech.tts.openai.apiKey')).toBeUndefined();
});
diff --git a/packages/api/src/admin/secrets.runtime.spec.ts b/packages/api/src/admin/secrets.runtime.spec.ts
new file mode 100644
index 0000000000..83105877c3
--- /dev/null
+++ b/packages/api/src/admin/secrets.runtime.spec.ts
@@ -0,0 +1,241 @@
+import http from 'node:http';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readFileSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { loadWebSearchConfig } from '@librechat/data-schemas';
+import { RerankerTypes, SearchProviders, ScraperProviders } from 'librechat-data-provider';
+import type {
+ AppConfig,
+ TWebSearchKeys,
+ AdminConfigArraySecretFieldRule,
+} from '@librechat/data-schemas';
+import type { TWebSearchConfigInput } from 'librechat-data-provider';
+import type { AddressInfo } from 'node:net';
+import { encryptConfigSecretFields, getConfigSecretRules } from './secrets';
+import { resolveTenantCredentials } from '~/langfuse/utils';
+import { uploadMistralOCR } from '~/files/mistral/crud';
+import { getCustomEndpointConfig } from '~/app/config';
+import { loadWebSearchAuth } from '~/web';
+
+/** Encryption reads `CREDS_KEY` when data-schemas loads, before any spec code runs. */
+jest.mock('@librechat/data-schemas', () => {
+ process.env.CREDS_KEY ??= '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+ return jest.requireActual('@librechat/data-schemas');
+});
+
+const REPO_ROOT = join(__dirname, '../../../..');
+const DECRYPTING_CALL =
+ /\b(?:resolveConfigSecret|resolveStoredConfigSecret|decryptConfigSecret|resolveCustomEndpointSecrets)\(/;
+
+interface RuntimeReader {
+ /** Repo-relative module that reads the merged config value when the feature runs. */
+ module: string;
+ /**
+ * Runs the real reader on the value the admin config API stores and returns
+ * what it would send. Readers under `/api` (TTS and STT) cannot load in this
+ * workspace, so for them this spec only checks that the module source calls a
+ * decrypting function; their own specs cover each provider's key.
+ */
+ probe?: (stored: string) => Promise<string | undefined>;
+}
+
+const KEYLESS_WEB_SEARCH: TWebSearchConfigInput = {
+ searchProvider: SearchProviders.KEENABLE,
+ scraperProvider: ScraperProviders.KEENABLE,
+ rerankerType: RerankerTypes.NONE,
+ keenableApiUrl: '',
+};
+
+/** Runs web search auth with one stored credential and the service that reads it selected. */
+function webSearchReader(key: TWebSearchKeys, selection: TWebSearchConfigInput): RuntimeReader {
+ return {
+ module: 'packages/api/src/web/web.ts',
+ probe: async (stored) => {
+ const { authResult } = await loadWebSearchAuth({
+ userId: 'runtime-reader-spec',
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS_WEB_SEARCH,
+ ...selection,
+ [key]: stored,
+ }),
+ loadAuthValues: async () => ({}),
+ });
+ return authResult[key];
+ },
+ };
+}
+
+/**
+ * A local OCR provider that records the bearer token of each request and
+ * fails it, so an upload stops after the reader has sent its key.
+ */
+const ocrProvider = {
+ tokens: [] as string[],
+ baseURL: '',
+ allowedAddress: '',
+ server: http.createServer((req, res) => {
+ ocrProvider.tokens.push(req.headers.authorization?.replace(/^Bearer /, '') ?? '');
+ req.resume();
+ req.on('end', () => {
+ res.statusCode = 503;
+ res.end();
+ });
+ }),
+};
+
+/** Uploads a document through the real Mistral OCR reader and returns the key it sent. */
+async function sendOCRUpload(stored: string): Promise<string | undefined> {
+ const dir = await mkdtemp(join(tmpdir(), 'ocr-runtime-reader-'));
+ const path = join(dir, 'document.pdf');
+ await writeFile(path, '%PDF-1.4');
+ const context = {
+ req: {
+ user: { id: 'runtime-reader-spec' },
+ config: {
+ ocr: {
+ apiKey: stored,
+ baseURL: ocrProvider.baseURL,
+ allowedAddresses: [ocrProvider.allowedAddress],
+ },
+ },
+ },
+ file: { path, originalname: 'document.pdf', mimetype: 'application/pdf' },
+ loadAuthValues: async () => ({}),
+ } as unknown as Parameters<typeof uploadMistralOCR>[0];
+ try {
+ await expect(uploadMistralOCR(context)).rejects.toThrow();
+ } finally {
+ await rm(dir, { recursive: true, force: true });
+ }
+ return ocrProvider.tokens.shift();
+}
+
+const CUSTOM_ENDPOINT_NAME = 'runtime-reader';
+
+const { secretFields, arraySecretFields } = getConfigSecretRules();
+
+/** Array-item secrets are listed as `<arrayPath>[].<secretKey>`. */
+const ARRAY_SECRET_FIELDS = new Map<string, AdminConfigArraySecretFieldRule>(
+ arraySecretFields.map((field) => [`${field.arrayPath}[].${field.secretKey}`, field]),
+);
+
+/** The value the admin config API stores for a registered secret. */
+function storeSecret(path: string, secret: string): unknown {
+ const arrayField = ARRAY_SECRET_FIELDS.get(path);
+ if (!arrayField) {
+ return encryptConfigSecretFields({ [path]: secret })[path];
+ }
+ const { arrayPath, identityKey, secretKey } = arrayField;
+ const item = { [identityKey]: CUSTOM_ENDPOINT_NAME, [secretKey]: secret };
+ const [stored] = encryptConfigSecretFields({ [arrayPath]: [item] })[arrayPath] as Array<
+ Record<string, string>
+ >;
+ return stored[secretKey];
+}
+
+const TTS_SERVICE = { module: 'api/server/services/Files/Audio/TTSService.js' };
+const STT_SERVICE = { module: 'api/server/services/Files/Audio/STTService.js' };
+
+/**
+ * Every registered secret path and the runtime reader that decrypts it. A path
+ * the registry encrypts but nothing decrypts silently disables its feature, so
+ * a new registry entry needs a row here (or in `UNREAD_SECRET_FIELDS`).
+ */
+const RUNTIME_READERS: Readonly<Record<string, RuntimeReader>> = {
+ 'langfuse.secretKey': {
+ module: 'packages/api/src/langfuse/utils.ts',
+ probe: async (stored) =>
+ resolveTenantCredentials({ publicKey: 'pk-lf-runtime', secretKey: stored })?.secretKey,
+ },
+ 'ocr.apiKey': { module: 'packages/api/src/files/mistral/crud.ts', probe: sendOCRUpload },
+ 'speech.tts.openai.apiKey': TTS_SERVICE,
+ 'speech.tts.azureOpenAI.apiKey': TTS_SERVICE,
+ 'speech.tts.elevenlabs.apiKey': TTS_SERVICE,
+ 'speech.tts.localai.apiKey': TTS_SERVICE,
+ 'speech.stt.openai.apiKey': STT_SERVICE,
+ 'speech.stt.azureOpenAI.apiKey': STT_SERVICE,
+ 'webSearch.serperApiKey': webSearchReader('serperApiKey', {
+ searchProvider: SearchProviders.SERPER,
+ }),
+ 'webSearch.searxngApiKey': webSearchReader('searxngApiKey', {
+ searchProvider: SearchProviders.SEARXNG,
+ searxngInstanceUrl: 'https://searx.example.com',
+ }),
+ 'webSearch.firecrawlApiKey': webSearchReader('firecrawlApiKey', {
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ }),
+ 'webSearch.tavilyApiKey': webSearchReader('tavilyApiKey', {
+ searchProvider: SearchProviders.TAVILY,
+ }),
+ 'webSearch.keenableApiKey': webSearchReader('keenableApiKey', {}),
+ 'webSearch.jinaApiKey': webSearchReader('jinaApiKey', { rerankerType: RerankerTypes.JINA }),
+ 'webSearch.cohereApiKey': webSearchReader('cohereApiKey', {
+ rerankerType: RerankerTypes.COHERE,
+ }),
+ 'endpoints.custom[].apiKey': {
+ module: 'packages/api/src/app/config.ts',
+ probe: async (stored) => {
+ const custom = [
+ {
+ name: CUSTOM_ENDPOINT_NAME,
+ apiKey: stored,
+ baseURL: 'https://custom.example.com/v1',
+ models: { default: ['runtime-model'] },
+ },
+ ];
+ const appConfig = { endpoints: { custom } } as AppConfig;
+ return getCustomEndpointConfig({ endpoint: CUSTOM_ENDPOINT_NAME, appConfig })?.apiKey;
+ },
+ },
+};
+
+/**
+ * Registered paths that no runtime code reads: they are encrypted and redacted
+ * like any secret, but setting them changes nothing. Each needs a reader before
+ * an admin UI can present it as working.
+ */
+const UNREAD_SECRET_FIELDS: Readonly<Record<string, string>> = {
+ 'endpoints.assistants.apiKey':
+ 'Assistants initialize from ASSISTANTS_API_KEY; the endpoint config apiKey is never read.',
+ 'endpoints.azureAssistants.apiKey':
+ 'Azure Assistants initialize from AZURE_ASSISTANTS_API_KEY or azureOpenAI groups; the endpoint config apiKey is never read.',
+};
+
+describe('config secret registry runtime readers', () => {
+ beforeAll(async () => {
+ await new Promise<void>((resolve) => ocrProvider.server.listen(0, '127.0.0.1', resolve));
+ const { port } = ocrProvider.server.address() as AddressInfo;
+ ocrProvider.allowedAddress = `127.0.0.1:${port}`;
+ ocrProvider.baseURL = `http://${ocrProvider.allowedAddress}/v1`;
+ });
+
+ afterAll(async () => {
+ await new Promise<void>((resolve) => ocrProvider.server.close(() => resolve()));
+ });
+
+ const registered = [...secretFields.map(({ path }) => path), ...ARRAY_SECRET_FIELDS.keys()];
+
+ it('pairs every registered secret path with a runtime reader or a documented gap', () => {
+ const listed = [...Object.keys(RUNTIME_READERS), ...Object.keys(UNREAD_SECRET_FIELDS)];
+
+ expect(new Set(listed).size).toBe(listed.length);
+ expect([...listed].sort()).toEqual([...registered].sort());
+ });
+
+ it.each(Object.entries(RUNTIME_READERS))('%s is read by a module that decrypts', (_, reader) => {
+ const source = readFileSync(join(REPO_ROOT, reader.module), 'utf8');
+
+ expect(source).toMatch(DECRYPTING_CALL);
+ });
+
+ it.each(
+ Object.entries(RUNTIME_READERS).flatMap(([path, { probe }]) => (probe ? [[path, probe]] : [])),
+ )('%s reaches its reader as plaintext', async (path, probe) => {
+ const secret = `${path}-runtime-secret-0001`;
+ const stored = storeSecret(path, secret);
+
+ expect(stored).toMatch(/^v3:/);
+ await expect(probe(stored as string)).resolves.toBe(secret);
+ });
+});
diff --git a/packages/api/src/admin/secrets.spec.ts b/packages/api/src/admin/secrets.spec.ts
index 6d2064ba23..a81ec79db1 100644
--- a/packages/api/src/admin/secrets.spec.ts
+++ b/packages/api/src/admin/secrets.spec.ts
@@ -15,6 +15,8 @@ let isConfigSecretDescendantPath: typeof import('./secrets').isConfigSecretDesce
let preserveConfigSecrets: typeof import('./secrets').preserveConfigSecrets;
let redactConfigSecrets: typeof import('./secrets').redactConfigSecrets;
let resolveConfigSecret: typeof import('./secrets').resolveConfigSecret;
+let resolveStoredConfigSecret: typeof import('./secrets').resolveStoredConfigSecret;
+let getConfigSecretRules: typeof import('./secrets').getConfigSecretRules;
let resolveCustomEndpointSecrets: typeof import('./secrets').resolveCustomEndpointSecrets;
let decryptV3: typeof import('@librechat/data-schemas').decryptV3;
@@ -32,6 +34,8 @@ beforeAll(async () => {
preserveConfigSecrets,
redactConfigSecrets,
resolveConfigSecret,
+ resolveStoredConfigSecret,
+ getConfigSecretRules,
resolveCustomEndpointSecrets,
} = await import('./secrets'));
({ decryptV3 } = await import('@librechat/data-schemas'));
@@ -208,6 +212,33 @@ describe('Langfuse config secrets', () => {
});
});
+ it('previews a stored plaintext secret only when reading stored overrides', () => {
+ const encrypted = encryptConfigSecretFields({ 'webSearch.serperApiKey': 'serper-key-00001' });
+ const stored = () => ({
+ webSearch: {
+ keenableApiKey: ' kn-legacy-plain-0002 ',
+ searxngApiKey: 'short',
+ tavilyApiKey: 'tvly-legacy-plain-0003',
+ tavilyApiKeyPreview: '...kept',
+ serperApiKey: encrypted['webSearch.serperApiKey'],
+ jinaApiKey: '${JINA_API_KEY}',
+ cohereApiKey: '',
+ },
+ });
+
+ expect(redactConfigSecrets(stored(), { previewPlaintext: true })).toEqual({
+ webSearch: {
+ keenableApiKeyPreview: '...0002',
+ searxngApiKeyPreview: '*****',
+ tavilyApiKeyPreview: '...kept',
+ jinaApiKey: '${JINA_API_KEY}',
+ },
+ });
+ expect(redactConfigSecrets(stored())).toEqual({
+ webSearch: { tavilyApiKeyPreview: '...kept', jinaApiKey: '${JINA_API_KEY}' },
+ });
+ });
+
it('masks Langfuse header values while keeping their names', () => {
const redacted = redactConfigSecrets({
langfuse: {
@@ -597,6 +628,35 @@ describe('Config secret registry fields', () => {
expect(resolveConfigSecret('v3:provider-literal-token')).toBe('v3:provider-literal-token');
});
+ it('resolveStoredConfigSecret decrypts and passes every other value through verbatim', () => {
+ const encrypted = encryptConfigSecrets({ webSearch: { keenableApiKey: 'kn-stored' } }).webSearch
+ .keenableApiKey;
+ expect(resolveStoredConfigSecret(encrypted)).toBe('kn-stored');
+
+ process.env.SECRETS_SPEC_TEST_KEY = 'sk-from-env';
+ expect(resolveStoredConfigSecret('${SECRETS_SPEC_TEST_KEY}')).toBe('${SECRETS_SPEC_TEST_KEY}');
+ expect(resolveStoredConfigSecret('kn-${SECRETS_SPEC_TEST_KEY}')).toBe(
+ 'kn-${SECRETS_SPEC_TEST_KEY}',
+ );
+ delete process.env.SECRETS_SPEC_TEST_KEY;
+
+ expect(resolveStoredConfigSecret('kn-plain-literal')).toBe('kn-plain-literal');
+ expect(resolveStoredConfigSecret('v3:provider-literal-token')).toBe(
+ 'v3:provider-literal-token',
+ );
+ });
+
+ it('registers the Keenable web search key with its preview companion', () => {
+ expect(getConfigSecretRules().secretFields).toContainEqual({
+ path: 'webSearch.keenableApiKey',
+ previewPath: 'webSearch.keenableApiKeyPreview',
+ allowEnvPlaceholder: true,
+ });
+ const out = encryptConfigSecretFields({ 'webSearch.keenableApiKey': 'kn-0123456789abcdef' });
+ expect(decryptV3(out['webSearch.keenableApiKey'] as string)).toBe('kn-0123456789abcdef');
+ expect(out['webSearch.keenableApiKeyPreview']).toBe('...cdef');
+ });
+
it('reports mutation paths (including the preview companion) and ancestor/descendant checks for registry fields', () => {
expect(getConfigSecretMutationPaths('speech.tts.openai.apiKey')).toEqual([
'speech.tts.openai.apiKey',
@@ -647,6 +707,7 @@ describe('Config secret registry fields', () => {
'speech.stt.azureOpenAI.apiKeyPreview',
'webSearch.serperApiKeyPreview',
'webSearch.cohereApiKeyPreview',
+ 'webSearch.keenableApiKeyPreview',
'endpoints.assistants.apiKeyPreview',
'endpoints.azureAssistants.apiKeyPreview',
'langfuse.secretKeyPreview',
diff --git a/packages/api/src/admin/secrets.ts b/packages/api/src/admin/secrets.ts
index 84d6505bc4..f284e9924c 100644
--- a/packages/api/src/admin/secrets.ts
+++ b/packages/api/src/admin/secrets.ts
@@ -24,8 +24,9 @@ interface ConfigSecretField extends ConfigSecretFieldInput {
* config API encrypt these at rest, reads redact them, and omitting them on a
* subsequent write preserves the stored encrypted value. Each secret's
* masked-preview companion is derived as `<path>Preview` — recognizing a new
- * sensitive field is a one-line path addition (plus the `<field>Preview`
- * companion in the config schema).
+ * sensitive field is a one-line path addition, plus the `<field>Preview`
+ * companion in the config schema and a runtime reader that decrypts the stored
+ * value (`secrets.runtime.spec.ts` lists them).
*/
const CONFIG_SECRET_FIELDS: readonly ConfigSecretField[] = (
[
@@ -41,6 +42,7 @@ const CONFIG_SECRET_FIELDS: readonly ConfigSecretField[] = (
{ path: 'webSearch.searxngApiKey', allowEnvPlaceholder: true },
{ path: 'webSearch.firecrawlApiKey', allowEnvPlaceholder: true },
{ path: 'webSearch.tavilyApiKey', allowEnvPlaceholder: true },
+ { path: 'webSearch.keenableApiKey', allowEnvPlaceholder: true },
{ path: 'webSearch.jinaApiKey', allowEnvPlaceholder: true },
{ path: 'webSearch.cohereApiKey', allowEnvPlaceholder: true },
{ path: 'endpoints.assistants.apiKey', allowEnvPlaceholder: true },
@@ -266,10 +268,6 @@ export function decryptConfigSecret(value: unknown): string | undefined {
}
}
-/**
- * Resolves a config credential for runtime use: decrypts encrypted values and
- * resolves `${ENV_VAR}` placeholders, passing plain literals through unchanged.
- */
/**
* Whether a value has the exact shape `encryptV3` produces
* (`v3:<32-hex-iv>:<hex-ciphertext>`). Runtime resolution uses this strict
@@ -281,6 +279,10 @@ export function isEncryptedSecretPayload(value: string): boolean {
return ENCRYPTED_PAYLOAD_REGEX.test(value.trim());
}
+/**
+ * Resolves a config credential for runtime use: decrypts encrypted values and
+ * resolves `${ENV_VAR}` placeholders, passing plain literals through unchanged.
+ */
export function resolveConfigSecret(value?: string): string | undefined {
if (value == null || value === '') {
return value;
@@ -291,6 +293,19 @@ export function resolveConfigSecret(value?: string): string | undefined {
return extractEnvVariable(value);
}
+/**
+ * Resolves a stored config credential without consulting the environment:
+ * decrypts an encrypted value and returns any other value verbatim, so a
+ * stored value never splices `${ENV_VAR}` references into a request. A failed
+ * decryption yields undefined, never the ciphertext.
+ */
+export function resolveStoredConfigSecret(value: string): string | undefined {
+ if (isEncryptedSecretPayload(value)) {
+ return decryptConfigSecret(value);
+ }
+ return value;
+}
+
export function getConfigSecretMutationPaths(fieldPath: string): string[] {
const field = SECRET_FIELDS_BY_PATH.get(fieldPath);
if (field?.previewPath) {
@@ -886,13 +901,41 @@ function redactSecretMapFields(rootRecord: Record<string, unknown>): void {
}
}
+/**
+ * Gives a plaintext secret without a preview the one its next save would
+ * write. A value stored before its path joined the registry stays plaintext
+ * until its section is saved again, and the runtime still reads it, so a read
+ * must show it as set.
+ */
+function previewLegacyPlaintext(
+ section: Record<string, unknown>,
+ previewKey: string,
+ value: unknown,
+): void {
+ const plaintext = normalizeSecretString(value);
+ if (!plaintext || section[previewKey] || isEncryptedSecretPayload(plaintext)) {
+ return;
+ }
+ section[previewKey] = getSecretPreview(plaintext);
+}
+
+interface RedactConfigSecretsOptions {
+ /** Gives a plaintext secret without a preview the one its next save would write. */
+ previewPlaintext?: boolean;
+ /** The librechat.yaml config a merged `root` came from; plaintext values it supplies get no preview. */
+ yamlConfig?: unknown;
+}
+
/**
* Deletes registered secret values from `root` in place so admin reads never
* return them (encrypted or plaintext). Preview companions and plain
* `${ENV_VAR}` references (for fields that allow them) are preserved.
* Secret *maps* are masked value-by-value. The caller passes a cloned object.
*/
-export function redactConfigSecrets<T>(root: T): T {
+export function redactConfigSecrets<T>(
+ root: T,
+ { previewPlaintext = false, yamlConfig }: RedactConfigSecretsOptions = {},
+): T {
const rootRecord = getPlainRecord(root);
if (!rootRecord) {
return root;
@@ -929,6 +972,9 @@ export function redactConfigSecrets<T>(root: T): T {
if (field.allowEnvPlaceholder && typeof value === 'string' && isEnvPlaceholder(value)) {
continue;
}
+ if (previewPlaintext && walkToParent(yamlConfig, segments)?.[key] !== value) {
+ previewLegacyPlaintext(section, previewKey, value);
+ }
delete section[key];
}
diff --git a/packages/api/src/app/checks.spec.ts b/packages/api/src/app/checks.spec.ts
index 0d570acbb7..3f2d5e3775 100644
--- a/packages/api/src/app/checks.spec.ts
+++ b/packages/api/src/app/checks.spec.ts
@@ -96,61 +96,97 @@ describe('checkWebSearchConfig', () => {
});
});
- describe('when config values are actual values instead of environment variable references', () => {
- it('should warn when serperApiKey contains actual API key', () => {
- const config = {
- serperApiKey: 'sk-1234567890abcdef',
- };
+ describe('when config values are literals instead of environment variable references', () => {
+ const { extractVariableName: actualExtractVariableName } =
+ jest.requireActual<typeof import('librechat-data-provider')>('librechat-data-provider');
- extractVariableName.mockReturnValue(null);
+ beforeEach(() => {
+ extractVariableName.mockImplementation(actualExtractVariableName);
+ });
- checkWebSearchConfig(config);
+ it('warns that a literal API key is a shared credential without repeating it', () => {
+ checkWebSearchConfig({ serperApiKey: 'sk-1234567890abcdef' });
- expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining(
- '❗ Web search configuration error: serperApiKey contains an actual value',
- ),
- );
- expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining('Current value: "sk-1234567..."'),
+ expect(logger.warn).toHaveBeenCalledTimes(1);
+ const [message] = (logger.warn as jest.Mock).mock.calls[0];
+ expect(message).toContain('Web search serperApiKey holds a literal credential');
+ expect(message).toContain(
+ 'More info: https://www.librechat.ai/docs/configuration/librechat_yaml/web_search',
);
+ expect(message).not.toContain('sk-123');
expect(logger.debug).not.toHaveBeenCalled();
});
- it('should warn when firecrawlApiUrl contains actual URL', () => {
- const config = {
- firecrawlApiUrl: 'https://api.firecrawl.dev',
- };
+ it('accepts a literal URL whose API key variable is unset', () => {
+ delete process.env.FIRECRAWL_API_KEY;
+ checkWebSearchConfig({
+ firecrawlApiUrl: 'https://firecrawl.internal.example.com',
+ firecrawlApiKey: '${FIRECRAWL_API_KEY}',
+ searxngInstanceUrl: 'https://searx.example.com',
+ });
+
+ expect(logger.warn).not.toHaveBeenCalled();
+ });
- extractVariableName.mockReturnValue(null);
+ it.each([
+ { name: 'an environment key', envValue: 'fc-env-key' },
+ { name: "each user's saved key", envValue: 'user_provided' },
+ ])('warns when a literal URL is kept from $name', ({ envValue }) => {
+ process.env.FIRECRAWL_API_KEY = envValue;
- checkWebSearchConfig(config);
+ checkWebSearchConfig({
+ firecrawlApiUrl: 'https://firecrawl.internal.example.com',
+ firecrawlApiKey: '${FIRECRAWL_API_KEY}',
+ });
- expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining(
- '❗ Web search configuration error: firecrawlApiUrl contains an actual value',
- ),
+ expect(logger.warn).toHaveBeenCalledTimes(1);
+ const [message] = (logger.warn as jest.Mock).mock.calls[0];
+ expect(message).toContain(
+ "Web search firecrawlApiUrl is set in librechat.yaml, but firecrawlApiKey comes from the environment or from each user's saved key",
);
- expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining('Current value: "https://ap..."'),
+ expect(message).toContain(
+ "firecrawlApiUrl is ignored and firecrawlApiKey goes to the provider's default URL",
);
+ expect(message).not.toContain('firecrawl.internal.example.com');
+ expect(message).not.toContain('fc-env-key');
});
- it('should include documentation link in warning message', () => {
- const config = {
- firecrawlApiKey: 'fc-actual-key',
- };
+ it('warns that a required literal URL gets no key from outside config', () => {
+ process.env.SEARXNG_API_KEY = 'sx-env-key';
- extractVariableName.mockReturnValue(null);
+ checkWebSearchConfig({ searxngInstanceUrl: 'https://searx.example.com' });
- checkWebSearchConfig(config);
+ expect(logger.warn).toHaveBeenCalledTimes(1);
+ const [message] = (logger.warn as jest.Mock).mock.calls[0];
+ expect(message).toContain('requests to searxngInstanceUrl carry no searxngApiKey');
+ expect(message).not.toContain('sx-env-key');
+ });
+
+ it('reads the default key reference when librechat.yaml leaves the key out', () => {
+ process.env.KEENABLE_API_KEY = 'kn-env-key';
+
+ checkWebSearchConfig({ keenableApiUrl: 'https://keenable.example.com/v1/search' });
+
+ expect(logger.warn).toHaveBeenCalledTimes(1);
+ const [message] = (logger.warn as jest.Mock).mock.calls[0];
+ expect(message).toContain(
+ "keenableApiUrl is ignored and keenableApiKey goes to the provider's default URL",
+ );
+ });
+
+ it('warns that a user_provided literal is never read', () => {
+ checkWebSearchConfig({ jinaApiKey: 'user_provided' });
expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining(
- 'More info: https://www.librechat.ai/docs/configuration/librechat_yaml/web_search',
- ),
+ expect.stringContaining('Web search jinaApiKey is "user_provided"'),
);
});
+
+ it('ignores literal values that need no explanation', () => {
+ checkWebSearchConfig({ firecrawlVersion: 'v2', keenableApiUrl: '' });
+
+ expect(logger.warn).not.toHaveBeenCalled();
+ });
});
describe('when config contains mixed value types', () => {
@@ -189,20 +225,6 @@ describe('checkWebSearchConfig', () => {
expect(logger.debug).not.toHaveBeenCalled();
expect(logger.warn).not.toHaveBeenCalled();
});
-
- it('should truncate long values in warning messages', () => {
- const config = {
- serperApiKey: 'this-is-a-very-long-api-key-that-should-be-truncated-in-the-warning-message',
- };
-
- extractVariableName.mockReturnValue(null);
-
- checkWebSearchConfig(config);
-
- expect(logger.warn).toHaveBeenCalledWith(
- expect.stringContaining('Current value: "this-is-a-..."'),
- );
- });
});
});
diff --git a/packages/api/src/app/checks.ts b/packages/api/src/app/checks.ts
index f42cc6ee74..97eff08639 100644
--- a/packages/api/src/app/checks.ts
+++ b/packages/api/src/app/checks.ts
@@ -1,8 +1,14 @@
import mongoose from 'mongoose';
-import { logger, webSearchKeys } from '@librechat/data-schemas';
-import { Constants, extractVariableName } from 'librechat-data-provider';
+import { AuthType, Constants, extractVariableName } from 'librechat-data-provider';
+import {
+ logger,
+ webSearchAuth,
+ webSearchKeys,
+ loadWebSearchConfig,
+ webSearchUrlApiKeys,
+} from '@librechat/data-schemas';
+import type { AppConfig, TWebSearchKeys } from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
-import type { AppConfig } from '@librechat/data-schemas';
import type { CredentialFingerprintRecord } from '~/credentials';
import {
credentialMetadataCollection,
@@ -386,10 +392,66 @@ Latest version: ${Constants.CONFIG_VERSION}
}
}
+const WEB_SEARCH_DOCS_URL = 'https://www.librechat.ai/docs/configuration/librechat_yaml/web_search';
+
+/** Whether a service cannot run without `field`; a required URL has no provider default. */
+function isRequiredWebSearchField(field: TWebSearchKeys): boolean {
+ return Object.values(webSearchAuth).some((services: Record<string, Record<string, number>>) =>
+ Object.values(services).some((fields) => fields[field] === 1),
+ );
+}
+
+/**
+ * Whether a `${VAR}` reference supplies a key from outside config: the
+ * operator's environment value, or each user's saved key when the variable is
+ * `user_provided`.
+ */
+function readsOutsideKey(value: unknown): boolean {
+ if (typeof value !== 'string') {
+ return false;
+ }
+ const varName = extractVariableName(value);
+ return !!(varName && process.env[varName]?.trim());
+}
+
/**
- * Checks web search configuration values to ensure they are environment variable references.
- * Warns if actual API keys or URLs are used instead of environment variable references.
- * Logs debug information for properly configured environment variable references.
+ * Explains a web search value that is not a `${VAR}` reference. Such values are
+ * used as written, so this only flags what an operator may not expect, and it
+ * never repeats the value itself.
+ */
+function getLiteralValueWarning(
+ key: TWebSearchKeys,
+ value: string,
+ runtimeConfig: TCustomConfig['webSearch'],
+): string | null {
+ const trimmed = value.trim();
+ if (trimmed === '') {
+ return null;
+ }
+ if (trimmed === AuthType.USER_PROVIDED) {
+ return `Web search ${key} is "user_provided", which web search does not read. To let users supply it, reference an environment variable set to user_provided instead: ${key}: "\${YOUR_ENV_VAR_NAME}".`;
+ }
+ const apiKey = webSearchUrlApiKeys.get(key);
+ if (apiKey != null) {
+ if (!readsOutsideKey(runtimeConfig?.[apiKey])) {
+ return null;
+ }
+ const outcome = isRequiredWebSearchField(key)
+ ? `requests to ${key} carry no ${apiKey}`
+ : `${key} is ignored and ${apiKey} goes to the provider's default URL`;
+ return `Web search ${key} is set in librechat.yaml, but ${apiKey} comes from the environment or from each user's saved key, and neither is sent to a URL set in config: ${outcome}. Reference ${key} from the environment as well, or set ${apiKey} in librechat.yaml.`;
+ }
+ if (key.endsWith('ApiKey')) {
+ return `Web search ${key} holds a literal credential in librechat.yaml, used for every user's searches. Prefer an environment variable reference so the secret stays out of the file: ${key}: "\${YOUR_ENV_VAR_NAME}".`;
+ }
+ return null;
+}
+
+/**
+ * Logs how each web search value in librechat.yaml resolves: debug lines for
+ * environment variable references, and warnings for literal values that are
+ * ignored, shared as credentials, or kept from an API key that config does not
+ * store (an environment key or a user's saved key).
* @param webSearchConfig - The loaded web search configuration object.
*/
export function checkWebSearchConfig(
@@ -399,37 +461,29 @@ export function checkWebSearchConfig(
return;
}
- webSearchKeys.forEach((key) => {
- const value = webSearchConfig[key as keyof typeof webSearchConfig];
-
- if (typeof value === 'string') {
- const varName = extractVariableName(value);
+ /** Fields librechat.yaml leaves out fall back to their default `${VAR}` references at runtime. */
+ const runtimeConfig = loadWebSearchConfig(webSearchConfig);
+ for (const key of webSearchKeys) {
+ const value = webSearchConfig[key];
+ if (typeof value !== 'string') {
+ continue;
+ }
- if (varName) {
- // This is a proper environment variable reference
- const actualValue = process.env[varName];
- if (actualValue) {
- logger.debug(`Web search ${key}: Using environment variable ${varName} with value set`);
- } else {
- logger.debug(
- `Web search ${key}: Using environment variable ${varName} (not set in environment, user provided value)`,
- );
- }
+ const varName = extractVariableName(value);
+ if (varName) {
+ if (process.env[varName]) {
+ logger.debug(`Web search ${key}: Using environment variable ${varName} with value set`);
} else {
- // This is not an environment variable reference - warn user
- logger.warn(
- `❗ Web search configuration error: ${key} contains an actual value instead of an environment variable reference.
-
- Current value: "${value.substring(0, 10)}..."
-
- This is incorrect! You should use environment variable references in your librechat.yaml file, such as:
- ${key}: "\${YOUR_ENV_VAR_NAME}"
-
- Then set the actual API key in your .env file or environment variables.
-
- More info: https://www.librechat.ai/docs/configuration/librechat_yaml/web_search`,
+ logger.debug(
+ `Web search ${key}: Using environment variable ${varName} (not set in environment, user provided value)`,
);
}
+ continue;
}
- });
+
+ const warning = getLiteralValueWarning(key, value, runtimeConfig);
+ if (warning) {
+ logger.warn(`❗ ${warning}\n\nMore info: ${WEB_SEARCH_DOCS_URL}`);
+ }
+ }
}
diff --git a/packages/api/src/web/web.integration.spec.ts b/packages/api/src/web/web.integration.spec.ts
new file mode 100644
index 0000000000..49a7d0fadf
--- /dev/null
+++ b/packages/api/src/web/web.integration.spec.ts
@@ -0,0 +1,450 @@
+import http from 'node:http';
+import { createSearchTool } from '@librechat/agents';
+import {
+ AuthType,
+ RerankerTypes,
+ SearchProviders,
+ ScraperProviders,
+} from 'librechat-data-provider';
+import {
+ logger,
+ loadWebSearchConfig,
+ mergeConfigOverrides,
+ BASE_CONFIG_PRINCIPAL_ID,
+} from '@librechat/data-schemas';
+import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provider';
+import type { AppConfig, IConfig } from '@librechat/data-schemas';
+import type { AddressInfo } from 'node:net';
+import { encryptConfigSecretFields } from '~/admin/secrets';
+import { resolveWebSearchSSRFAgents } from './agent';
+import { loadWebSearchAuth } from './web';
+
+/** Encryption reads `CREDS_KEY` when data-schemas loads, before any spec code runs. */
+jest.mock('@librechat/data-schemas', () => {
+ process.env.CREDS_KEY ??= '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+ return jest.requireActual('@librechat/data-schemas');
+});
+
+const PLATFORM_KEY = 'platform-env-key-0001';
+const ENV_NAMES = [
+ 'KEENABLE_API_KEY',
+ 'KEENABLE_API_URL',
+ 'KEENABLE_FETCH_URL',
+ 'SEARXNG_API_KEY',
+ 'SEARXNG_INSTANCE_URL',
+] as const;
+
+interface CapturedRequest {
+ path: string;
+ apiKey: string | null;
+}
+
+/**
+ * Runs web search the way `handleTools` does — auth resolution, connect-time
+ * SSRF agents, then the search library's own clients — against a local
+ * endpoint that records the API key each request carries.
+ */
+describe('web search credentials reach the search library', () => {
+ const requests: CapturedRequest[] = [];
+ /** Search hits the endpoint returns; a hit makes the scraper fetch its page. */
+ let results: Array<{ title: string; url: string; snippet: string }> = [];
+ const server = http.createServer((req, res) => {
+ const apiKey = req.headers['x-api-key'];
+ requests.push({ path: req.url ?? '', apiKey: typeof apiKey === 'string' ? apiKey : null });
+ req.resume();
+ req.on('end', () => {
+ res.setHeader('Content-Type', 'application/json');
+ res.end(JSON.stringify({ results, content: 'Scraped page content.' }));
+ });
+ });
+ let endpoint = '';
+ let allowedAddress = '';
+ let originalEnv: NodeJS.ProcessEnv;
+
+ beforeAll(async () => {
+ await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+ const { port } = server.address() as AddressInfo;
+ allowedAddress = `127.0.0.1:${port}`;
+ endpoint = `http://${allowedAddress}/v1/search`;
+ });
+
+ afterAll(async () => {
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ });
+
+ beforeEach(() => {
+ originalEnv = process.env;
+ process.env = { ...originalEnv };
+ for (const name of ENV_NAMES) {
+ delete process.env[name];
+ }
+ process.env.KEENABLE_API_KEY = PLATFORM_KEY;
+ process.env.SEARXNG_API_KEY = PLATFORM_KEY;
+ requests.length = 0;
+ results = [];
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ /** The value the admin config API stores for a web search secret. */
+ function stored(path: string, secret: string): string {
+ return encryptConfigSecretFields({ [path]: secret })[path] as string;
+ }
+
+ /** Mirrors `loadAuthValues`: a set environment value wins, otherwise the user's saved value. */
+ function authValuesFor(userValues: Record<string, string>) {
+ return async ({ authFields }: { authFields: string[] }) => {
+ const values: Record<string, string> = {};
+ for (const field of authFields) {
+ const envValue = process.env[field];
+ const value =
+ envValue && envValue.trim() !== '' && envValue !== AuthType.USER_PROVIDED
+ ? envValue
+ : userValues[field];
+ if (value != null) {
+ values[field] = value;
+ }
+ }
+ return values;
+ };
+ }
+
+ function withDefaults(config: TWebSearchConfigInput): TWebSearchConfigInput {
+ return {
+ scraperProvider: ScraperProviders.KEENABLE,
+ rerankerType: RerankerTypes.NONE,
+ allowedAddresses: [allowedAddress],
+ ...config,
+ };
+ }
+
+ async function search(
+ config: TWebSearchConfigInput,
+ userValues: Record<string, string> = {},
+ ): Promise<CapturedRequest[]> {
+ return searchWith(loadWebSearchConfig(withDefaults(config)), userValues);
+ }
+
+ async function searchWith(
+ webSearchConfig: TCustomConfig['webSearch'],
+ userValues: Record<string, string> = {},
+ ): Promise<CapturedRequest[]> {
+ const { authenticated, authResult } = await loadWebSearchAuth({
+ userId: 'web-integration-user',
+ webSearchConfig,
+ loadAuthValues: authValuesFor(userValues),
+ });
+ expect(authenticated).toBe(true);
+
+ /** Firecrawl's option block is typed looser than the library's and no case here scrapes with it. */
+ const { firecrawlOptions: _firecrawlOptions, ...searchConfig } = authResult;
+ const agents = resolveWebSearchSSRFAgents(authResult, webSearchConfig?.allowedAddresses);
+ const tool = createSearchTool({ ...searchConfig, ...agents, logger });
+ await tool.invoke({ query: 'librechat' });
+ return requests.splice(0);
+ }
+
+ it('sends the environment key to an endpoint the environment supplies', async () => {
+ process.env.KEENABLE_API_URL = endpoint;
+
+ const sent = await search({ searchProvider: SearchProviders.KEENABLE });
+
+ expect(sent).toEqual([{ path: '/v1/search', apiKey: PLATFORM_KEY }]);
+ });
+
+ it.each([
+ {
+ name: 'Keenable',
+ config: (url: string): TWebSearchConfigInput => ({
+ searchProvider: SearchProviders.KEENABLE,
+ keenableApiUrl: url,
+ keenableApiKey: stored('webSearch.keenableApiKey', 'keenable-admin-key-0001'),
+ }),
+ secret: 'keenable-admin-key-0001',
+ },
+ {
+ name: 'SearXNG',
+ config: (url: string): TWebSearchConfigInput => ({
+ searchProvider: SearchProviders.SEARXNG,
+ searxngInstanceUrl: url,
+ searxngApiKey: stored('webSearch.searxngApiKey', 'searxng-admin-key-0001'),
+ }),
+ secret: 'searxng-admin-key-0001',
+ },
+ ])('sends an admin-stored $name key to the URL stored beside it', async ({ config, secret }) => {
+ const sent = await search(config(endpoint));
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBe(secret);
+ });
+
+ it.each([
+ {
+ name: 'a SearXNG URL stored in config',
+ config: (url: string): TWebSearchConfigInput => ({
+ searchProvider: SearchProviders.SEARXNG,
+ searxngInstanceUrl: url,
+ }),
+ },
+ {
+ name: 'a SearXNG URL stored in config beside a blank key',
+ config: (url: string): TWebSearchConfigInput => ({
+ searchProvider: SearchProviders.SEARXNG,
+ searxngInstanceUrl: url,
+ searxngApiKey: '',
+ }),
+ },
+ ])('never sends the environment key to $name', async ({ config }) => {
+ const sent = await search(config(endpoint));
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBeNull();
+ });
+
+ it("never sends a user's saved SearXNG key to a URL stored in config", async () => {
+ process.env.SEARXNG_API_KEY = AuthType.USER_PROVIDED;
+
+ const sent = await search(
+ { searchProvider: SearchProviders.SEARXNG, searxngInstanceUrl: endpoint },
+ { SEARXNG_API_KEY: 'user-own-searxng-key-0001' },
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBeNull();
+ });
+
+ it.each([
+ {
+ name: 'the environment key',
+ env: PLATFORM_KEY,
+ userValues: {} as Record<string, string>,
+ key: PLATFORM_KEY,
+ },
+ {
+ name: "a user's saved key",
+ env: AuthType.USER_PROVIDED,
+ userValues: { KEENABLE_API_KEY: 'user-own-keenable-key-0001' },
+ key: 'user-own-keenable-key-0001',
+ },
+ ])(
+ 'sends $name to the Keenable URL the environment supplies, never to one stored in config',
+ async ({ env, userValues, key }) => {
+ process.env.KEENABLE_API_KEY = env;
+ process.env.KEENABLE_API_URL = `http://${allowedAddress}/operator/v1/search`;
+ process.env.KEENABLE_FETCH_URL = `http://${allowedAddress}/v1/fetch`;
+ results = [{ title: 'LibreChat', url: 'https://www.librechat.ai/', snippet: 'Open source' }];
+
+ const sent = await search(
+ {
+ searchProvider: SearchProviders.KEENABLE,
+ keenableApiUrl: `http://${allowedAddress}/stored-in-config/v1/search`,
+ },
+ userValues,
+ );
+
+ expect(sent.map(({ path, apiKey }) => [path.split('?')[0], apiKey])).toEqual([
+ ['/operator/v1/search', key],
+ ['/v1/fetch', key],
+ ]);
+ },
+ );
+
+ it('never sends the environment key to a user-provided Keenable URL', async () => {
+ process.env.KEENABLE_API_URL = AuthType.USER_PROVIDED;
+
+ const sent = await search(
+ { searchProvider: SearchProviders.KEENABLE },
+ { KEENABLE_API_URL: endpoint },
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBeNull();
+ });
+
+ it('never sends an admin-stored key to a user-provided Keenable URL', async () => {
+ delete process.env.KEENABLE_API_KEY;
+ process.env.KEENABLE_API_URL = AuthType.USER_PROVIDED;
+
+ const sent = await search(
+ {
+ searchProvider: SearchProviders.KEENABLE,
+ keenableApiKey: stored('webSearch.keenableApiKey', 'keenable-admin-key-0002'),
+ },
+ { KEENABLE_API_URL: endpoint },
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBeNull();
+ });
+
+ it('keeps the environment key for the Keenable scraper beside a user-provided search URL', async () => {
+ process.env.KEENABLE_API_URL = AuthType.USER_PROVIDED;
+ process.env.KEENABLE_FETCH_URL = `http://${allowedAddress}/v1/fetch`;
+ results = [{ title: 'LibreChat', url: 'https://www.librechat.ai/', snippet: 'Open source' }];
+
+ const sent = await search(
+ { searchProvider: SearchProviders.KEENABLE },
+ { KEENABLE_API_URL: endpoint },
+ );
+
+ expect(sent.map(({ path, apiKey }) => [path.split('?')[0], apiKey])).toEqual([
+ ['/v1/search', null],
+ ['/v1/fetch', PLATFORM_KEY],
+ ]);
+ });
+
+ describe('keys and URLs set by different config layers', () => {
+ const SEARXNG_BASE_KEY = 'sx-base-secret-0001';
+
+ function profile(
+ principalId: string,
+ priority: number,
+ webSearch: TWebSearchConfigInput,
+ ): IConfig {
+ return {
+ principalType: 'role',
+ principalId,
+ principalModel: 'Role',
+ priority,
+ overrides: { webSearch },
+ isActive: true,
+ configVersion: 1,
+ } as unknown as IConfig;
+ }
+
+ /** The merged config a user with the ADMIN role gets, as `getAppConfig` builds it. */
+ function mergedWebSearch(
+ yaml: TWebSearchConfigInput,
+ ...configs: IConfig[]
+ ): TCustomConfig['webSearch'] {
+ const config = withDefaults(yaml);
+ const base = { config: { webSearch: config }, webSearch: loadWebSearchConfig(config) };
+ return mergeConfigOverrides(base as AppConfig, configs).webSearch;
+ }
+
+ it('never sends a base-profile key to a URL only a role profile set', async () => {
+ const sent = await searchWith(
+ mergedWebSearch(
+ { searchProvider: SearchProviders.SEARXNG },
+ profile(BASE_CONFIG_PRINCIPAL_ID, 0, {
+ searxngInstanceUrl: `http://${allowedAddress}/base`,
+ searxngApiKey: stored('webSearch.searxngApiKey', SEARXNG_BASE_KEY),
+ }),
+ profile('ADMIN', 10, { searxngInstanceUrl: endpoint }),
+ ),
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0]).toEqual({ path: expect.stringMatching(/^\/v1\/search/), apiKey: null });
+ });
+
+ it('never sends a librechat.yaml key to a URL a config override set', async () => {
+ const sent = await searchWith(
+ mergedWebSearch(
+ {
+ searchProvider: SearchProviders.KEENABLE,
+ keenableApiUrl: `http://${allowedAddress}/operator`,
+ keenableApiKey: 'kn-yaml-literal-0001',
+ },
+ profile(BASE_CONFIG_PRINCIPAL_ID, 0, { keenableApiUrl: endpoint }),
+ ),
+ );
+
+ expect(sent).toEqual([{ path: '/v1/search', apiKey: null }]);
+ });
+
+ it('never sends a base-profile key to an environment URL a role profile chose', async () => {
+ delete process.env.SEARXNG_API_KEY;
+ process.env.LC3_OTHER_SERVICE_URL = endpoint;
+
+ try {
+ const sent = await searchWith(
+ mergedWebSearch(
+ { searchProvider: SearchProviders.SEARXNG },
+ profile(BASE_CONFIG_PRINCIPAL_ID, 0, {
+ searxngInstanceUrl: `http://${allowedAddress}/base`,
+ searxngApiKey: stored('webSearch.searxngApiKey', SEARXNG_BASE_KEY),
+ }),
+ profile('ADMIN', 10, { searxngInstanceUrl: '${LC3_OTHER_SERVICE_URL}' }),
+ ),
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0]).toEqual({ path: expect.stringMatching(/^\/v1\/search/), apiKey: null });
+ } finally {
+ delete process.env.LC3_OTHER_SERVICE_URL;
+ }
+ });
+
+ it('never sends a base-profile key to the default URL once a role profile blanks it', async () => {
+ delete process.env.KEENABLE_API_KEY;
+ process.env.KEENABLE_API_URL = endpoint;
+
+ const sent = await searchWith(
+ mergedWebSearch(
+ { searchProvider: SearchProviders.KEENABLE },
+ profile(BASE_CONFIG_PRINCIPAL_ID, 0, {
+ keenableApiUrl: `http://${allowedAddress}/base`,
+ keenableApiKey: stored('webSearch.keenableApiKey', 'kn-base-secret-0003'),
+ }),
+ profile('ADMIN', 10, { keenableApiUrl: '' }),
+ ),
+ );
+
+ expect(sent).toEqual([{ path: '/v1/search', apiKey: null }]);
+ });
+
+ it("never sends a user's saved key to a URL a role profile set", async () => {
+ process.env.SEARXNG_API_KEY = AuthType.USER_PROVIDED;
+
+ const sent = await searchWith(
+ mergedWebSearch(
+ { searchProvider: SearchProviders.SEARXNG },
+ profile('ADMIN', 10, { searxngInstanceUrl: endpoint }),
+ ),
+ { SEARXNG_API_KEY: 'user-own-searxng-key-0001' },
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0]).toEqual({ path: expect.stringMatching(/^\/v1\/search/), apiKey: null });
+ });
+
+ it('sends a key to the URL the same profile set beside it', async () => {
+ const sent = await searchWith(
+ mergedWebSearch(
+ { searchProvider: SearchProviders.SEARXNG },
+ profile(BASE_CONFIG_PRINCIPAL_ID, 0, {
+ searxngInstanceUrl: `http://${allowedAddress}/base`,
+ searxngApiKey: stored('webSearch.searxngApiKey', SEARXNG_BASE_KEY),
+ }),
+ profile('ADMIN', 10, {
+ searxngInstanceUrl: endpoint,
+ searxngApiKey: stored('webSearch.searxngApiKey', 'sx-admin-role-0002'),
+ }),
+ ),
+ );
+
+ expect(sent).toHaveLength(1);
+ expect(sent[0].apiKey).toBe('sx-admin-role-0002');
+ });
+ });
+
+ it('never lets a provider option block redirect the environment key', async () => {
+ process.env.KEENABLE_API_URL = endpoint;
+ process.env.KEENABLE_FETCH_URL = `http://${allowedAddress}/v1/fetch`;
+ results = [{ title: 'LibreChat', url: 'https://www.librechat.ai/', snippet: 'Open source' }];
+ const keenableScraperOptions = {
+ attributionTitle: 'LibreChat',
+ apiUrl: `http://${allowedAddress}/stored-in-config`,
+ };
+
+ const sent = await search({ searchProvider: SearchProviders.KEENABLE, keenableScraperOptions });
+
+ expect(sent.map(({ path, apiKey }) => [path.split('?')[0], apiKey])).toEqual([
+ ['/v1/search', PLATFORM_KEY],
+ ['/v1/fetch', PLATFORM_KEY],
+ ]);
+ });
+});
diff --git a/packages/api/src/web/web.spec.ts b/packages/api/src/web/web.spec.ts
index 1a8ae5ceda..c3b1c17c03 100644
--- a/packages/api/src/web/web.spec.ts
+++ b/packages/api/src/web/web.spec.ts
@@ -1,4 +1,8 @@
-import { webSearchAuth, webSearchSelectionFields } from '@librechat/data-schemas';
+import {
+ webSearchAuth,
+ loadWebSearchConfig,
+ webSearchSelectionFields,
+} from '@librechat/data-schemas';
import {
AuthType,
RerankerTypes,
@@ -8,12 +12,20 @@ import {
ScraperProviders,
} from 'librechat-data-provider';
import type { TWebSearchConfig, TCustomConfig } from 'librechat-data-provider';
+import type { TWebSearchKeys } from '@librechat/data-schemas';
import {
loadWebSearchAuth,
extractWebSearchEnvVars,
getWebSearchInstallEntries,
getWebSearchUninstallFields,
} from './web';
+import { encryptConfigSecretFields } from '~/admin/secrets';
+
+/** Encryption reads `CREDS_KEY` when data-schemas loads, before any spec code runs. */
+jest.mock('@librechat/data-schemas', () => {
+ process.env.CREDS_KEY ??= '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
+ return { ...jest.requireActual('@librechat/data-schemas') };
+});
// Mock the extractVariableName function
jest.mock('../utils', () => ({
@@ -651,7 +663,7 @@ describe('web.ts', () => {
});
expect(result.authResult.keenableApiUrl).toBe('https://user-keenable.example.com');
- expect(result.authResult.keenableApiKey).toBeUndefined();
+ expect(result.authResult.keenableApiKey).toBe('');
expect(result.authTypes).toEqual([
['providers', AuthType.USER_PROVIDED],
['scrapers', AuthType.USER_PROVIDED],
@@ -805,7 +817,7 @@ describe('web.ts', () => {
});
expect(result.authResult.keenableApiUrl).toBe('https://user-keenable.example.com');
- expect(result.authResult.keenableApiKey).toBeUndefined();
+ expect(result.authResult.keenableApiKey).toBe('');
} finally {
if (originalApiKey == null) {
delete process.env.KEENABLE_API_KEY;
@@ -1761,7 +1773,7 @@ describe('web.ts', () => {
expect(result.authenticated).toBe(true);
expect(result.authResult.searxngInstanceUrl).toBe('https://user-provider.example.com');
- expect(result.authResult.searxngApiKey).toBe(apiKey);
+ expect(result.authResult.searxngApiKey).toBe('');
expect(result.authTypes).toContainEqual([
SearchCategories.PROVIDERS,
AuthType.USER_PROVIDED,
@@ -3261,4 +3273,588 @@ describe('web.ts', () => {
}
});
});
+
+ describe('credentials stored in config', () => {
+ const userId = 'test-user-id';
+ const ENV_NAMES = [
+ 'SERPER_API_KEY',
+ 'SEARXNG_INSTANCE_URL',
+ 'SEARXNG_API_KEY',
+ 'FIRECRAWL_API_KEY',
+ 'FIRECRAWL_API_URL',
+ 'FIRECRAWL_VERSION',
+ 'TAVILY_API_KEY',
+ 'TAVILY_SEARCH_URL',
+ 'TAVILY_EXTRACT_URL',
+ 'KEENABLE_API_KEY',
+ 'KEENABLE_API_URL',
+ 'JINA_API_KEY',
+ 'JINA_API_URL',
+ 'COHERE_API_KEY',
+ ];
+ /** Keyless fillers so each case authenticates on the service under test alone. */
+ const KEYLESS = {
+ searchProvider: SearchProviders.KEENABLE,
+ scraperProvider: ScraperProviders.KEENABLE,
+ rerankerType: RerankerTypes.NONE,
+ };
+ let originalEnv: NodeJS.ProcessEnv;
+
+ beforeEach(() => {
+ originalEnv = process.env;
+ process.env = { ...originalEnv };
+ for (const name of ENV_NAMES) {
+ delete process.env[name];
+ }
+ mockIsSSRFTarget.mockReturnValue(false);
+ mockResolveHostnameSSRF.mockResolvedValue(false);
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ /** Mirrors `loadAuthValues`: a set environment value wins, otherwise the user's saved value. */
+ function authValuesFor(userValues: Record<string, string> = {}) {
+ return jest.fn(async ({ authFields }: { authFields: string[] }) => {
+ const values: Record<string, string> = {};
+ for (const field of authFields) {
+ const envValue = process.env[field];
+ const value =
+ envValue && envValue.trim() !== '' && envValue !== AuthType.USER_PROVIDED
+ ? envValue
+ : userValues[field];
+ if (value != null) {
+ values[field] = value;
+ }
+ }
+ return values;
+ });
+ }
+
+ /** The value the admin config API stores for a web search secret. */
+ function stored(key: TWebSearchKeys, secret: string): string {
+ const path = `webSearch.${key}`;
+ const value = encryptConfigSecretFields({ [path]: secret })[path];
+ expect(value).toMatch(/^v3:/);
+ return value as string;
+ }
+
+ function requestedFields(loadAuthValues: jest.Mock): string[] {
+ return loadAuthValues.mock.calls.flatMap(([params]) => params.authFields);
+ }
+
+ it.each([
+ { key: 'serperApiKey', category: SearchCategories.PROVIDERS, searchProvider: 'serper' },
+ {
+ key: 'searxngApiKey',
+ category: SearchCategories.PROVIDERS,
+ searchProvider: 'searxng',
+ searxngInstanceUrl: 'https://searx.example.com',
+ },
+ { key: 'tavilyApiKey', category: SearchCategories.PROVIDERS, searchProvider: 'tavily' },
+ {
+ key: 'keenableApiKey',
+ category: SearchCategories.PROVIDERS,
+ searchProvider: 'keenable',
+ keenableApiUrl: '',
+ },
+ { key: 'firecrawlApiKey', category: SearchCategories.SCRAPERS, scraperProvider: 'firecrawl' },
+ { key: 'jinaApiKey', category: SearchCategories.RERANKERS, rerankerType: 'jina' },
+ { key: 'cohereApiKey', category: SearchCategories.RERANKERS, rerankerType: 'cohere' },
+ ] as const)(
+ 'authenticates with an encrypted $key stored by the admin config API',
+ async ({ key, category, ...selection }) => {
+ const secret = `${key}-admin-secret-0001`;
+ const loadAuthValues = authValuesFor();
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ ...selection,
+ [key]: stored(key, secret),
+ } as TWebSearchConfig),
+ loadAuthValues,
+ });
+
+ expect(result.authenticated).toBe(true);
+ expect(result.authResult[key]).toBe(secret);
+ expect(result.authTypes).toContainEqual([category, AuthType.SYSTEM_DEFINED]);
+ expect(JSON.stringify(result.authResult)).not.toContain('v3:');
+ expect(requestedFields(loadAuthValues)).not.toContain(`${key}`);
+ },
+ );
+
+ it('uses librechat.yaml literals as system credentials, each on its own key', async () => {
+ const loadAuthValues = authValuesFor();
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ searchProvider: SearchProviders.SERPER,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ rerankerType: RerankerTypes.COHERE,
+ serperApiKey: 'serper-yaml-literal',
+ firecrawlApiKey: 'firecrawl-yaml-literal',
+ firecrawlApiUrl: 'https://firecrawl.internal.example.com',
+ firecrawlVersion: 'v2',
+ cohereApiKey: 'cohere-yaml-literal',
+ }),
+ loadAuthValues,
+ });
+
+ expect(result.authenticated).toBe(true);
+ expect(result.authResult).toMatchObject({
+ serperApiKey: 'serper-yaml-literal',
+ firecrawlApiKey: 'firecrawl-yaml-literal',
+ firecrawlApiUrl: 'https://firecrawl.internal.example.com',
+ firecrawlVersion: 'v2',
+ cohereApiKey: 'cohere-yaml-literal',
+ });
+ expect(result.authTypes).toEqual([
+ [SearchCategories.PROVIDERS, AuthType.SYSTEM_DEFINED],
+ [SearchCategories.SCRAPERS, AuthType.SYSTEM_DEFINED],
+ [SearchCategories.RERANKERS, AuthType.SYSTEM_DEFINED],
+ ]);
+ expect(loadAuthValues).not.toHaveBeenCalled();
+ });
+
+ it('keeps an environment-resolved value on its own key beside a literal sibling', async () => {
+ process.env.FIRECRAWL_API_KEY = 'firecrawl-env-key';
+ process.env.FIRECRAWL_VERSION = 'v1';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ firecrawlApiUrl: '',
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authResult.firecrawlApiKey).toBe('firecrawl-env-key');
+ expect(result.authResult.firecrawlVersion).toBe('v1');
+ expect(result.authResult.firecrawlApiUrl).toBeUndefined();
+ });
+
+ it('uses a literal Keenable key as a system key', async () => {
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ keenableApiKey: 'keenable-literal-key',
+ keenableApiUrl: '',
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authenticated).toBe(true);
+ expect(result.authResult.keenableApiKey).toBe('keenable-literal-key');
+ expect(result.authTypes).toEqual([
+ [SearchCategories.PROVIDERS, AuthType.SYSTEM_DEFINED],
+ [SearchCategories.SCRAPERS, AuthType.SYSTEM_DEFINED],
+ [SearchCategories.RERANKERS, AuthType.SYSTEM_DEFINED],
+ ]);
+ });
+
+ it.each([
+ {
+ name: 'Firecrawl',
+ apiKey: 'firecrawlApiKey',
+ apiUrl: 'firecrawlApiUrl',
+ urlField: 'FIRECRAWL_API_URL',
+ selection: { scraperProvider: ScraperProviders.FIRECRAWL },
+ authenticated: true,
+ expectedUrl: undefined,
+ },
+ {
+ name: 'SearXNG',
+ apiKey: 'searxngApiKey',
+ apiUrl: 'searxngInstanceUrl',
+ urlField: 'SEARXNG_INSTANCE_URL',
+ selection: { searchProvider: SearchProviders.SEARXNG },
+ authenticated: false,
+ expectedUrl: undefined,
+ },
+ {
+ name: 'Jina',
+ apiKey: 'jinaApiKey',
+ apiUrl: 'jinaApiUrl',
+ urlField: 'JINA_API_URL',
+ selection: { rerankerType: RerankerTypes.JINA },
+ authenticated: true,
+ expectedUrl: 'https://api.jina.ai/v1/rerank',
+ },
+ {
+ name: 'Tavily search (operator opt-in)',
+ apiKey: 'tavilyApiKey',
+ apiUrl: 'tavilySearchUrl',
+ urlField: 'TAVILY_SEARCH_URL',
+ selection: { searchProvider: SearchProviders.TAVILY },
+ authenticated: true,
+ expectedUrl: undefined,
+ },
+ {
+ name: 'Tavily extract (operator opt-in)',
+ apiKey: 'tavilyApiKey',
+ apiUrl: 'tavilyExtractUrl',
+ urlField: 'TAVILY_EXTRACT_URL',
+ selection: { scraperProvider: ScraperProviders.TAVILY },
+ authenticated: true,
+ expectedUrl: undefined,
+ },
+ ] as const)(
+ 'never sends a stored $name key to a user-provided URL',
+ async ({ apiKey, apiUrl, urlField, selection, authenticated, expectedUrl }) => {
+ process.env[urlField] = AuthType.USER_PROVIDED;
+ const userUrl = 'https://user-provider.example.com';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ ...selection,
+ [apiKey]: stored(apiKey, 'admin-stored-secret-0001'),
+ }),
+ loadAuthValues: authValuesFor({ [urlField]: userUrl }),
+ });
+
+ expect(result.authenticated).toBe(authenticated);
+ expect(result.authResult[apiUrl]).toBe(expectedUrl);
+ expect(JSON.stringify(result.authResult)).not.toContain(userUrl);
+ },
+ );
+
+ it('withholds a stored Keenable key from a user-provided Keenable URL', async () => {
+ const userUrl = 'https://user-keenable.example.com';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ keenableApiKey: stored('keenableApiKey', 'keenable-admin-secret-0001'),
+ }),
+ loadAuthValues: authValuesFor({ KEENABLE_API_URL: userUrl }),
+ });
+
+ expect(result.authenticated).toBe(true);
+ expect(result.authResult.keenableApiUrl).toBe(userUrl);
+ expect(result.authResult.keenableApiKey).toBe('');
+ });
+
+ it.each([
+ {
+ origin: 'an environment key',
+ env: {
+ FIRECRAWL_API_KEY: 'firecrawl-outside-key',
+ TAVILY_API_KEY: 'tavily-outside-key',
+ SEARXNG_API_KEY: 'searxng-outside-key',
+ KEENABLE_API_KEY: 'keenable-outside-key',
+ },
+ userValues: {} as Record<string, string>,
+ authType: AuthType.SYSTEM_DEFINED,
+ },
+ {
+ origin: "a user's saved key",
+ env: {
+ FIRECRAWL_API_KEY: AuthType.USER_PROVIDED,
+ TAVILY_API_KEY: AuthType.USER_PROVIDED,
+ SEARXNG_API_KEY: AuthType.USER_PROVIDED,
+ KEENABLE_API_KEY: AuthType.USER_PROVIDED,
+ },
+ userValues: {
+ FIRECRAWL_API_KEY: 'firecrawl-outside-key',
+ TAVILY_API_KEY: 'tavily-outside-key',
+ SEARXNG_API_KEY: 'searxng-outside-key',
+ KEENABLE_API_KEY: 'keenable-outside-key',
+ },
+ authType: AuthType.USER_PROVIDED,
+ },
+ ])('never sends $origin to a URL stored in config', async ({ env, userValues, authType }) => {
+ Object.assign(process.env, env);
+ const configUrl = 'https://config-host.example.com';
+
+ const keyed = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ searchProvider: SearchProviders.TAVILY,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ rerankerType: RerankerTypes.NONE,
+ tavilySearchUrl: configUrl,
+ firecrawlApiUrl: configUrl,
+ }),
+ loadAuthValues: authValuesFor(userValues),
+ });
+ expect(keyed.authenticated).toBe(true);
+ expect(keyed.authResult).toMatchObject({
+ tavilyApiKey: 'tavily-outside-key',
+ firecrawlApiKey: 'firecrawl-outside-key',
+ });
+ expect(keyed.authResult.tavilySearchUrl).toBeUndefined();
+ expect(keyed.authResult.firecrawlApiUrl).toBeUndefined();
+ expect(keyed.authTypes).toContainEqual([SearchCategories.PROVIDERS, authType]);
+
+ const searxng = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ searchProvider: SearchProviders.SEARXNG,
+ searxngInstanceUrl: configUrl,
+ }),
+ loadAuthValues: authValuesFor(userValues),
+ });
+ expect(searxng.authenticated).toBe(true);
+ expect(searxng.authResult.searxngInstanceUrl).toBe(configUrl);
+ expect(searxng.authResult.searxngApiKey).toBe('');
+ expect(JSON.stringify(searxng.authResult)).not.toContain('searxng-outside-key');
+
+ /** Keenable has a default endpoint, so the stored URL is ignored as it was before stored URLs were read. */
+ const keenable = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({ ...KEYLESS, keenableApiUrl: configUrl }),
+ loadAuthValues: authValuesFor(userValues),
+ });
+ expect(keenable.authenticated).toBe(true);
+ expect(keenable.authResult.keenableApiUrl).toBeUndefined();
+ expect(keenable.authResult.keenableApiKey).toBe('keenable-outside-key');
+ expect(keenable.authResult.keenableScraperOptions).toBeUndefined();
+ expect(JSON.stringify(keenable.authResult)).not.toContain(configUrl);
+ });
+
+ it('keeps a Keenable URL stored in config when no key sits beside it', async () => {
+ const configUrl = 'https://config-host.example.com';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({ ...KEYLESS, keenableApiUrl: configUrl }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authResult.keenableApiUrl).toBe(configUrl);
+ expect(result.authResult.keenableApiKey).toBe('');
+ });
+
+ it('sends a stored key to a URL stored beside it', async () => {
+ process.env.FIRECRAWL_API_KEY = 'firecrawl-env-key';
+ const configUrl = 'https://firecrawl.admin.example.com';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ firecrawlApiKey: stored('firecrawlApiKey', 'firecrawl-admin-secret-0001'),
+ firecrawlApiUrl: configUrl,
+ keenableApiKey: stored('keenableApiKey', 'keenable-admin-secret-0001'),
+ keenableApiUrl: configUrl,
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authResult).toMatchObject({
+ firecrawlApiKey: 'firecrawl-admin-secret-0001',
+ firecrawlApiUrl: configUrl,
+ keenableApiKey: 'keenable-admin-secret-0001',
+ keenableApiUrl: configUrl,
+ });
+ });
+
+ it('treats an undecryptable stored key as missing and never forwards ciphertext', async () => {
+ const serperApiKey = stored('serperApiKey', 'serper-admin-secret-0001');
+ const dataSchemas =
+ jest.requireMock<typeof import('@librechat/data-schemas')>('@librechat/data-schemas');
+ const decrypt = jest.spyOn(dataSchemas, 'decryptV3').mockImplementation(() => {
+ throw new Error('Invalid key length');
+ });
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ searchProvider: SearchProviders.SERPER,
+ serperApiKey,
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(decrypt).toHaveBeenCalledWith(serperApiKey);
+
+ expect(result.authenticated).toBe(false);
+ expect(result.authResult.serperApiKey).toBeUndefined();
+ expect(JSON.stringify(result.authResult)).not.toContain('v3:');
+ });
+
+ it('never expands environment references inside a stored value', async () => {
+ process.env.SPEC_PLATFORM_SECRET = 'platform-secret-value';
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ firecrawlApiKey: 'fc-${SPEC_PLATFORM_SECRET}',
+ firecrawlApiUrl: 'https://firecrawl.example.com/${SPEC_PLATFORM_SECRET}',
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authResult.firecrawlApiKey).toBe('fc-${SPEC_PLATFORM_SECRET}');
+ expect(result.authResult.firecrawlApiUrl).toBe(
+ 'https://firecrawl.example.com/${SPEC_PLATFORM_SECRET}',
+ );
+ expect(JSON.stringify(result.authResult)).not.toContain('platform-secret-value');
+ });
+
+ it.each(['user_provided', '', ' '])(
+ 'leaves a required key of %p unresolved, as before',
+ async (serperApiKey) => {
+ const loadAuthValues = authValuesFor({ SERPER_API_KEY: 'user-serper-key' });
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ searchProvider: SearchProviders.SERPER,
+ serperApiKey,
+ }),
+ loadAuthValues,
+ });
+
+ expect(result.authenticated).toBe(false);
+ expect(result.authResult.serperApiKey).toBeUndefined();
+ expect(requestedFields(loadAuthValues)).not.toContain('SERPER_API_KEY');
+ },
+ );
+
+ it('never sends a stored "user_provided" as a key', async () => {
+ const result = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ searchProvider: SearchProviders.SERPER,
+ serperApiKey: stored('serperApiKey', AuthType.USER_PROVIDED),
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(result.authenticated).toBe(false);
+ expect(result.authResult.serperApiKey).toBeUndefined();
+ });
+
+ it('passes only schema-defined fields of each provider option block', async () => {
+ const configUrl = 'https://config-host.example.com';
+ const destination = { apiUrl: configUrl, apiKey: 'option-block-key', httpAgent: {} };
+ const keenableScraperOptions = {
+ attributionTitle: 'LibreChat',
+ timeout: 9000,
+ ...destination,
+ };
+ const tavilyScraperOptions = { extractDepth: 'advanced' as const, ...destination };
+ const firecrawlOptions = { formats: ['markdown'], waitFor: 100, ...destination };
+ const searxngSearchOptions = { language: 'en', ...destination };
+ const tavilySearchOptions = { maxResults: 3, ...destination };
+ const keenableSearchOptions = { site: 'librechat.ai', ...destination };
+
+ const { authResult } = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ keenableScraperOptions,
+ tavilyScraperOptions,
+ firecrawlOptions,
+ searxngSearchOptions,
+ tavilySearchOptions,
+ keenableSearchOptions,
+ }),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(authResult.keenableScraperOptions).toEqual({
+ attributionTitle: 'LibreChat',
+ timeout: 9000,
+ });
+ expect(authResult.tavilyScraperOptions).toEqual({ extractDepth: 'advanced' });
+ expect(authResult.firecrawlOptions).toEqual({ formats: ['markdown'], waitFor: 100 });
+ expect(authResult.searxngSearchOptions).toEqual({ language: 'en' });
+ expect(authResult.tavilySearchOptions).toEqual({ maxResults: 3 });
+ expect(authResult.keenableSearchOptions).toEqual({ site: 'librechat.ai' });
+ expect(JSON.stringify(authResult)).not.toContain(configUrl);
+ expect(JSON.stringify(authResult)).not.toContain('option-block-key');
+ });
+
+ describe('Keenable scraper key', () => {
+ const SEARCH_URL = 'https://keenable.example.com';
+
+ it.each([
+ {
+ name: 'a user-provided search URL',
+ env: { KEENABLE_API_KEY: 'platform-key-0001', KEENABLE_API_URL: AuthType.USER_PROVIDED },
+ config: {},
+ scraperKey: 'platform-key-0001',
+ },
+ {
+ name: 'a user-provided search URL beside a stored key',
+ env: { KEENABLE_API_URL: AuthType.USER_PROVIDED },
+ config: { keenableApiKey: stored('keenableApiKey', 'kn-admin-key-0001') },
+ scraperKey: 'kn-admin-key-0001',
+ },
+ ])(
+ 'gives the Keenable scraper the key kept from $name',
+ async ({ env, config, scraperKey }) => {
+ Object.assign(process.env, env);
+
+ const { authResult } = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ keenableScraperOptions: { attributionTitle: 'LibreChat' },
+ ...config,
+ }),
+ loadAuthValues: authValuesFor({ KEENABLE_API_URL: SEARCH_URL }),
+ });
+
+ expect(authResult.keenableApiUrl).toBe(SEARCH_URL);
+ expect(authResult.keenableApiKey).toBe('');
+ expect(authResult.keenableScraperOptions).toEqual({
+ attributionTitle: 'LibreChat',
+ apiKey: scraperKey,
+ });
+ },
+ );
+
+ it('keeps the key out of the option block when another scraper runs', async () => {
+ process.env.KEENABLE_API_KEY = 'platform-key-0001';
+ process.env.KEENABLE_API_URL = AuthType.USER_PROVIDED;
+ process.env.FIRECRAWL_API_KEY = 'firecrawl-key-0001';
+
+ const { authResult } = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig({
+ ...KEYLESS,
+ scraperProvider: ScraperProviders.FIRECRAWL,
+ }),
+ loadAuthValues: authValuesFor({ KEENABLE_API_URL: SEARCH_URL }),
+ });
+
+ expect(authResult.scraperProvider).toBe(ScraperProviders.FIRECRAWL);
+ expect(authResult.keenableApiKey).toBe('');
+ expect(JSON.stringify(authResult)).not.toContain('platform-key-0001');
+ });
+
+ it('leaves the option block alone when the search sends the key itself', async () => {
+ process.env.KEENABLE_API_KEY = 'platform-key-0001';
+ process.env.KEENABLE_API_URL = SEARCH_URL;
+
+ const { authResult } = await loadWebSearchAuth({
+ userId,
+ webSearchConfig: loadWebSearchConfig(KEYLESS),
+ loadAuthValues: authValuesFor(),
+ });
+
+ expect(authResult.keenableApiKey).toBe('platform-key-0001');
+ expect(authResult.keenableScraperOptions).toBeUndefined();
+ });
+ });
+
+ it('does not let a user save a value over a stored credential', () => {
+ const entries = getWebSearchInstallEntries({
+ auth: { serperApiKey: 'user-serper-key', jinaApiKey: 'user-jina-key' },
+ config: loadWebSearchConfig({ serperApiKey: stored('serperApiKey', 'admin-key-0001') }),
+ });
+
+ expect(entries).toEqual([['JINA_API_KEY', 'user-jina-key']]);
+ });
+ });
});
diff --git a/packages/api/src/web/web.ts b/packages/api/src/web/web.ts
index ca3372a1c5..5abd8bca31 100644
--- a/packages/api/src/web/web.ts
+++ b/packages/api/src/web/web.ts
@@ -1,4 +1,9 @@
-import { webSearchAuth, webSearchKeys, webSearchSelectionFields } from '@librechat/data-schemas';
+import {
+ webSearchAuth,
+ webSearchKeys,
+ webSearchUrlApiKeys,
+ webSearchSelectionFields,
+} from '@librechat/data-schemas';
import {
AuthType,
RerankerTypes,
@@ -6,20 +11,14 @@ import {
SearchCategories,
SearchProviders,
ScraperProviders,
+ webSearchSchema,
extractVariableName,
} from 'librechat-data-provider';
import type { TWebSearchKeys, TWebSearchCategories } from '@librechat/data-schemas';
import type { TCustomConfig, TWebSearchConfig } from 'librechat-data-provider';
+import type { KeenableScraperConfig } from '@librechat/agents';
import { isSSRFTarget, resolveHostnameSSRF, getEffectivePort } from '../auth';
-
-/**
- * User-provided URL keys and their paired API keys, checked after SSRF preflight.
- */
-const USER_PROVIDED_URL_KEYS = new Map<TWebSearchKeys, TWebSearchKeys>([
- ['searxngInstanceUrl', 'searxngApiKey'],
- ['firecrawlApiUrl', 'firecrawlApiKey'],
- ['jinaApiUrl', 'jinaApiKey'],
-]);
+import { resolveStoredConfigSecret } from '~/admin/secrets';
/**
* URL keys that require explicit admin opt-in before user-provided values may pass through.
@@ -29,6 +28,57 @@ const USER_PROVIDED_OPT_IN_URL_KEYS = new Set<TWebSearchKeys>([
'tavilyExtractUrl',
]);
+/**
+ * Where a configured credential is read from. A `${VAR}` reference resolves
+ * through the server environment or, when that is unset, the user's saved
+ * value; any other value is stored in config itself, as a librechat.yaml
+ * literal or a value the admin config API encrypted at rest.
+ */
+type CredentialSource = { kind: 'env'; field: string } | { kind: 'config'; value: string };
+
+/** `env` and `config` values are the deployment's; `user` values are the requesting user's. */
+type CredentialOrigin = 'env' | 'user' | 'config';
+
+interface ServiceCredential {
+ key: TWebSearchKeys;
+ required: boolean;
+ source: CredentialSource;
+}
+
+interface ResolvedCredential {
+ key: TWebSearchKeys;
+ required: boolean;
+ origin: CredentialOrigin;
+ value?: string;
+ /** Environment or plugin-auth field the value was looked up under; absent for config values. */
+ field?: string;
+}
+
+type WebSearchOptionBlock =
+ | 'firecrawlOptions'
+ | 'searxngSearchOptions'
+ | 'tavilySearchOptions'
+ | 'tavilyScraperOptions'
+ | 'keenableSearchOptions'
+ | 'keenableScraperOptions';
+
+const WEB_SEARCH_OPTION_BLOCKS: readonly WebSearchOptionBlock[] = [
+ 'firecrawlOptions',
+ 'searxngSearchOptions',
+ 'tavilySearchOptions',
+ 'tavilyScraperOptions',
+ 'keenableSearchOptions',
+ 'keenableScraperOptions',
+];
+
+/** The fields `webSearchSchema` defines for each provider option block. */
+const WEB_SEARCH_OPTION_FIELDS = new Map<WebSearchOptionBlock, ReadonlySet<string>>(
+ WEB_SEARCH_OPTION_BLOCKS.map((block) => [
+ block,
+ new Set(Object.keys(webSearchSchema.shape[block].unwrap().shape)),
+ ]),
+);
+
const SEARCH_PROVIDER_VALUES = new Set<string>(Object.values(SearchProviders));
const SCRAPER_PROVIDER_VALUES = new Set<string>(Object.values(ScraperProviders));
const RERANKER_VALUES = new Set<string>(Object.values(RerankerTypes));
@@ -88,6 +138,172 @@ export function extractWebSearchEnvVars({
return authFields;
}
+/** Classifies a configured credential; blank, `user_provided` and undecryptable values yield nothing. */
+function getCredentialSource(value?: string): CredentialSource | undefined {
+ if (typeof value !== 'string') {
+ return undefined;
+ }
+ const field = extractVariableName(value);
+ if (field) {
+ return { kind: 'env', field };
+ }
+ const resolved = resolveStoredConfigSecret(value.trim());
+ if (!resolved || resolved === AuthType.USER_PROVIDED) {
+ return undefined;
+ }
+ return { kind: 'config', value: resolved };
+}
+
+/**
+ * Whether a key config did not store would travel to a URL stored in config.
+ * An environment key belongs to the operator's own endpoint and a user's saved
+ * key to the endpoint the user saved it for, so a config write must not be
+ * able to redirect either to another host.
+ */
+function isOutsideKeyForConfigUrl(url?: ResolvedCredential, apiKey?: ResolvedCredential): boolean {
+ return (
+ url?.origin === 'config' &&
+ !!url.value &&
+ apiKey != null &&
+ apiKey.origin !== 'config' &&
+ !!apiKey.value
+ );
+}
+
+/**
+ * Gives every URL the environment did not supply an explicit API key. The
+ * search library reads its default environment key (`SEARXNG_API_KEY`,
+ * `KEENABLE_API_KEY`) whenever the key it receives is undefined, so a withheld
+ * or unset key becomes an empty string that it sends as no key at all.
+ */
+function blockEnvironmentKeyFallback(
+ authResult: Partial<TWebSearchConfig>,
+ entries: Iterable<{ key: TWebSearchKeys; origin: CredentialOrigin }>,
+): void {
+ for (const { key, origin } of entries) {
+ const apiKey = webSearchUrlApiKeys.get(key);
+ if (apiKey != null && origin !== 'env' && authResult[key] && authResult[apiKey] == null) {
+ authResult[apiKey] = '';
+ }
+ }
+}
+
+/**
+ * Keeps only the fields the schema defines in a provider option block. The
+ * search library spreads these blocks into its clients, where an `apiUrl` or
+ * `apiKey` would replace the destination or credential resolved here, and a
+ * config override can store keys the schema does not define.
+ */
+function pickOptionFields<B extends WebSearchOptionBlock>(
+ block: B,
+ value: Partial<TWebSearchConfig>[B],
+): Partial<TWebSearchConfig>[B] {
+ const fields = WEB_SEARCH_OPTION_FIELDS.get(block);
+ if (value == null || fields == null) {
+ return undefined;
+ }
+ return Object.fromEntries(
+ Object.entries(value).filter(([field]) => fields.has(field)),
+ ) as Partial<TWebSearchConfig>[B];
+}
+
+/**
+ * Whether a resolved credential may be sent. A user-supplied URL must pass the
+ * SSRF preflight and never receives a key the deployment supplied, except a
+ * Tavily URL, which needs the operator's `user_provided` opt-in and then
+ * receives the environment key by design; a key stored in config never goes
+ * to a user-supplied URL. Neither an environment key nor a user's saved key
+ * reaches a URL stored in config: an optional key is withheld, otherwise the
+ * URL is dropped so the provider's default endpoint is used. A key stored in
+ * config reaches a URL stored in config only when one config document set
+ * both: `mergeConfigOverrides` drops a stored key whose stored URL another
+ * layer set, or whose URL a later layer changed, blanked or removed, and the
+ * admin config API asks for the key again when a write changes or removes the
+ * URL beside it.
+ */
+async function isCredentialUsable(
+ credential: ResolvedCredential,
+ credentials: ReadonlyMap<TWebSearchKeys, ResolvedCredential>,
+ allowedAddresses?: string[] | null,
+): Promise<boolean> {
+ const { key, field, value, origin } = credential;
+ const apiKeyName = webSearchUrlApiKeys.get(key);
+ if (apiKeyName == null) {
+ if (origin === 'config' || credential.required) {
+ return true;
+ }
+ for (const candidate of credentials.values()) {
+ if (
+ webSearchUrlApiKeys.get(candidate.key) === key &&
+ isOutsideKeyForConfigUrl(candidate, credential)
+ ) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ const apiKey = credentials.get(apiKeyName);
+ if (origin === 'config') {
+ return !(apiKey?.required && isOutsideKeyForConfigUrl(credential, apiKey));
+ }
+ if (origin !== 'user' || value == null) {
+ return true;
+ }
+ const isOptIn = USER_PROVIDED_OPT_IN_URL_KEYS.has(key);
+ if (isOptIn && (field == null || !isUserProvidedEnabled(field))) {
+ return false;
+ }
+ if (await isSSRFUrl(value, allowedAddresses)) {
+ return false;
+ }
+ if (!apiKey?.value || apiKey.origin === 'user') {
+ return true;
+ }
+ return isOptIn && apiKey.origin === 'env';
+}
+
+/** A service's configured credentials, required first, or undefined when a required one is unset. */
+function getServiceCredentials(
+ requiredKeys: TWebSearchKeys[],
+ optionalKeys: TWebSearchKeys[],
+ config: TCustomConfig['webSearch'] | undefined,
+): ServiceCredential[] | undefined {
+ const credentials: ServiceCredential[] = [];
+ for (const key of requiredKeys) {
+ const source = getCredentialSource(config?.[key]);
+ if (!source) {
+ return undefined;
+ }
+ credentials.push({ key, required: true, source });
+ }
+ for (const key of optionalKeys) {
+ const source = getCredentialSource(config?.[key]);
+ if (source) {
+ credentials.push({ key, required: false, source });
+ }
+ }
+ return credentials;
+}
+
+/** Attaches each credential's value; a looked-up value that differs from the environment is the user's. */
+function resolveCredentials(
+ credentials: ServiceCredential[],
+ authValues: Record<string, string>,
+): Map<TWebSearchKeys, ResolvedCredential> {
+ const resolved = new Map<TWebSearchKeys, ResolvedCredential>();
+ for (const { key, required, source } of credentials) {
+ if (source.kind === 'config') {
+ resolved.set(key, { key, required, origin: 'config', value: source.value });
+ continue;
+ }
+ const value = authValues[source.field];
+ const origin = value != null && process.env[source.field] !== value ? 'user' : 'env';
+ resolved.set(key, { key, required, origin, value, field: source.field });
+ }
+ return resolved;
+}
+
function mapWebSearchSelection(key: string, value: string): [string, string] | undefined {
if (key === 'selectedProvider' && SEARCH_PROVIDER_VALUES.has(value)) {
return [webSearchSelectionFields.selectedProvider, value];
@@ -141,6 +357,15 @@ export function getWebSearchUninstallFields(config: TCustomConfig['webSearch']):
];
}
+/**
+ * Settings for the search tool. The Keenable scraper option block may carry a
+ * deployment key withheld from the Keenable search URL.
+ */
+export type WebSearchAuthValues = Omit<Partial<TWebSearchConfig>, 'keenableScraperOptions'> & {
+ keenableScraperOptions?: Partial<TWebSearchConfig>['keenableScraperOptions'] &
+ Pick<KeenableScraperConfig, 'apiKey'>;
+};
+
/**
* Type for web search authentication result
*/
@@ -150,7 +375,7 @@ export interface WebSearchAuthResult {
/** Authentication type (user_provided or system_defined) by category */
authTypes: [TWebSearchCategories, AuthType][];
/** Original authentication values mapped to their respective keys */
- authResult: Partial<TWebSearchConfig>;
+ authResult: WebSearchAuthValues;
}
interface KeenableAuthResolution {
@@ -160,6 +385,22 @@ interface KeenableAuthResolution {
lookupFailed: boolean;
}
+/**
+ * The Keenable scraper option block, carrying a deployment key kept from a
+ * search URL the user supplied. The scraper fetches from `KEENABLE_FETCH_URL`
+ * or Keenable's own host, never a URL from config or the user (the option block
+ * holds only schema fields), so the key may still go there.
+ */
+function getKeenableScraperOptions(
+ options: Partial<TWebSearchConfig>['keenableScraperOptions'],
+ withheldApiKey?: string,
+): WebSearchAuthValues['keenableScraperOptions'] {
+ if (!withheldApiKey) {
+ return options;
+ }
+ return { ...options, apiKey: withheldApiKey };
+}
+
/**
* Loads and verifies web search authentication values
* @param params - Authentication parameters
@@ -183,7 +424,9 @@ export async function loadWebSearchAuth({
throwError?: boolean;
}): Promise<WebSearchAuthResult> {
let authenticated = true;
- const authResult: Partial<TWebSearchConfig> = {};
+ const authResult: WebSearchAuthValues = {};
+ /** A deployment Keenable key kept from a user's search URL, still usable by the Keenable scraper. */
+ let keenableScraperApiKey: string | undefined;
/**
* Keenable is keyless by default: both its search and its page fetch work
@@ -206,14 +449,18 @@ export async function loadWebSearchAuth({
? ['keenableApiKey', 'keenableApiUrl']
: ['keenableApiKey'];
const authEntries: Array<{ key: TWebSearchKeys; field: string }> = [];
+ const resolvedEntries: Array<{
+ key: TWebSearchKeys;
+ value: string;
+ origin: CredentialOrigin;
+ }> = [];
for (const originalKey of keenableKeys) {
- const [field] = extractWebSearchEnvVars({
- keys: [originalKey],
- config: webSearchConfig,
- });
- if (field) {
- authEntries.push({ key: originalKey, field });
+ const source = getCredentialSource(webSearchConfig?.[originalKey]);
+ if (source?.kind === 'env') {
+ authEntries.push({ key: originalKey, field: source.field });
+ } else if (source?.kind === 'config') {
+ resolvedEntries.push({ key: originalKey, value: source.value, origin: 'config' });
}
}
@@ -236,11 +483,6 @@ export async function loadWebSearchAuth({
};
}
- const resolvedEntries: Array<{
- key: TWebSearchKeys;
- value: string;
- isFieldUserProvided: boolean;
- }> = [];
for (const { key: originalKey, field } of authEntries) {
const value = authValues[field];
const envValue = process.env[field];
@@ -265,7 +507,11 @@ export async function loadWebSearchAuth({
rejectedUserApiUrl = true;
continue;
}
- resolvedEntries.push({ key: originalKey, value, isFieldUserProvided });
+ resolvedEntries.push({
+ key: originalKey,
+ value,
+ origin: isFieldUserProvided ? 'user' : 'env',
+ });
}
if (rejectedUserApiUrl) {
@@ -277,20 +523,32 @@ export async function loadWebSearchAuth({
};
}
- const hasUserProvidedApiUrl = resolvedEntries.some(
- ({ key, isFieldUserProvided }) => key === 'keenableApiUrl' && isFieldUserProvided,
- );
- for (const { key: originalKey, value, isFieldUserProvided } of resolvedEntries) {
- // Never forward an administrator's secret to an endpoint controlled by
- // the user. Keenable remains functional without the key at that URL.
- if (originalKey === 'keenableApiKey' && !isFieldUserProvided && hasUserProvidedApiUrl) {
+ const apiUrlOrigin = resolvedEntries.find(({ key }) => key === 'keenableApiUrl')?.origin;
+ const apiKeyOrigin = resolvedEntries.find(({ key }) => key === 'keenableApiKey')?.origin;
+ for (const { key: originalKey, value, origin } of resolvedEntries) {
+ // An environment key or the user's own key never goes to a URL stored in
+ // config. The URL is ignored instead, so the key reaches `KEENABLE_API_URL`
+ // or Keenable's own endpoint, as it did before stored URLs were read.
+ if (
+ originalKey === 'keenableApiUrl' &&
+ origin === 'config' &&
+ apiKeyOrigin != null &&
+ apiKeyOrigin !== 'config'
+ ) {
+ continue;
+ }
+ // Never forward a deployment key to an endpoint the user controls. Keenable
+ // stays functional without the key at that URL.
+ if (originalKey === 'keenableApiKey' && origin !== 'user' && apiUrlOrigin === 'user') {
+ keenableScraperApiKey = value;
continue;
}
authResult[originalKey] = value;
- if (originalKey === 'keenableApiKey' && !isFieldUserProvided) {
+ if (originalKey === 'keenableApiKey' && origin !== 'user') {
hasSystemApiKey = true;
}
}
+ blockEnvironmentKeyFallback(authResult, resolvedEntries);
return {
isUserProvided: keenableUserProvided,
@@ -459,95 +717,51 @@ export async function loadWebSearchAuth({
if (requiredKeys.length === 0) continue;
- const requiredAuthFields = extractWebSearchEnvVars({
- keys: requiredKeys,
- config: webSearchConfig,
- });
- const optionalAuthFields = extractWebSearchEnvVars({
- keys: optionalKeys,
- config: webSearchConfig,
- });
- if (requiredAuthFields.length !== requiredKeys.length) continue;
+ const credentials = getServiceCredentials(requiredKeys, optionalKeys, webSearchConfig);
+ if (!credentials) continue;
- const allKeys = [...requiredKeys, ...optionalKeys];
- const allAuthFields = [...requiredAuthFields, ...optionalAuthFields];
- const optionalSet = new Set(optionalAuthFields);
+ const authFields: string[] = [];
+ const optionalFields = new Set<string>();
+ for (const { required, source } of credentials) {
+ if (source.kind !== 'env') {
+ continue;
+ }
+ authFields.push(source.field);
+ if (!required) {
+ optionalFields.add(source.field);
+ }
+ }
try {
- const authValues = await loadAuthValues({
- userId,
- authFields: allAuthFields,
- optional: optionalSet,
- throwError,
- });
-
- const jinaApiKeyIndex = allKeys.indexOf('jinaApiKey');
- const jinaApiKeyField = allAuthFields[jinaApiKeyIndex];
- const jinaApiKeyValue = jinaApiKeyField ? authValues[jinaApiKeyField] : undefined;
+ const authValues =
+ authFields.length > 0
+ ? await loadAuthValues({ userId, authFields, optional: optionalFields, throwError })
+ : {};
+ const resolved = resolveCredentials(credentials, authValues);
let allFieldsAuthenticated = true;
- for (let j = 0; j < allAuthFields.length; j++) {
- const field = allAuthFields[j];
- const value = authValues[field];
- const originalKey = allKeys[j];
-
- if (!optionalSet.has(field) && !value) {
+ for (const credential of resolved.values()) {
+ if (credential.required && !credential.value) {
allFieldsAuthenticated = false;
break;
}
-
- const isFieldUserProvided = value != null && process.env[field] !== value;
- const isUserProvidedUrlKey =
- originalKey != null && USER_PROVIDED_URL_KEYS.has(originalKey);
- const isUserProvidedOptInUrlKey =
- originalKey != null && USER_PROVIDED_OPT_IN_URL_KEYS.has(originalKey);
- const isUserProvidedUrlEnabled =
- isUserProvidedUrlKey || (isUserProvidedOptInUrlKey && isUserProvidedEnabled(field));
- let contributed = false;
-
- if (isUserProvidedOptInUrlKey && isFieldUserProvided && !isUserProvidedUrlEnabled) {
- if (!optionalSet.has(field)) {
- allFieldsAuthenticated = false;
- break;
- }
- continue;
- }
-
if (
- isUserProvidedUrlEnabled &&
- isFieldUserProvided &&
- (await isSSRFUrl(value, webSearchConfig?.allowedAddresses))
+ !(await isCredentialUsable(credential, resolved, webSearchConfig?.allowedAddresses))
) {
- if (!optionalSet.has(field)) {
+ if (credential.required) {
allFieldsAuthenticated = false;
break;
}
continue;
}
-
- if (isUserProvidedUrlKey && isFieldUserProvided) {
- const apiKey = USER_PROVIDED_URL_KEYS.get(originalKey);
- const apiKeyField = apiKey ? allAuthFields[allKeys.indexOf(apiKey)] : undefined;
- const apiKeyValue = apiKeyField ? authValues[apiKeyField] : undefined;
- if (apiKeyField && apiKeyValue && process.env[apiKeyField] === apiKeyValue) {
- if (!optionalSet.has(field)) {
- allFieldsAuthenticated = false;
- break;
- }
- continue;
- }
- }
- if (originalKey) {
- authResult[originalKey] = value;
- contributed = true;
- }
-
- if (!isUserProvided && isFieldUserProvided && contributed) {
+ authResult[credential.key] = credential.value;
+ if (credential.origin === 'user') {
isUserProvided = true;
}
}
+ blockEnvironmentKeyFallback(authResult, resolved.values());
- if (jinaApiKeyValue && authResult.jinaApiUrl == null) {
+ if (resolved.get('jinaApiKey')?.value && authResult.jinaApiUrl == null) {
authResult.jinaApiUrl = DEFAULT_JINA_API_URL;
}
@@ -656,12 +870,30 @@ export async function loadWebSearchAuth({
authResult.safeSearch = webSearchConfig?.safeSearch ?? SafeSearchTypes.MODERATE;
}
authResult.scraperTimeout = webSearchConfig?.scraperTimeout ?? scraperOptionsTimeout ?? 7500;
- authResult.firecrawlOptions = webSearchConfig?.firecrawlOptions;
- authResult.searxngSearchOptions = webSearchConfig?.searxngSearchOptions;
- authResult.tavilySearchOptions = webSearchConfig?.tavilySearchOptions;
- authResult.tavilyScraperOptions = webSearchConfig?.tavilyScraperOptions;
- authResult.keenableSearchOptions = webSearchConfig?.keenableSearchOptions;
- authResult.keenableScraperOptions = webSearchConfig?.keenableScraperOptions;
+ authResult.firecrawlOptions = pickOptionFields(
+ 'firecrawlOptions',
+ webSearchConfig?.firecrawlOptions,
+ );
+ authResult.searxngSearchOptions = pickOptionFields(
+ 'searxngSearchOptions',
+ webSearchConfig?.searxngSearchOptions,
+ );
+ authResult.tavilySearchOptions = pickOptionFields(
+ 'tavilySearchOptions',
+ webSearchConfig?.tavilySearchOptions,
+ );
+ authResult.tavilyScraperOptions = pickOptionFields(
+ 'tavilyScraperOptions',
+ webSearchConfig?.tavilyScraperOptions,
+ );
+ authResult.keenableSearchOptions = pickOptionFields(
+ 'keenableSearchOptions',
+ webSearchConfig?.keenableSearchOptions,
+ );
+ authResult.keenableScraperOptions = getKeenableScraperOptions(
+ pickOptionFields('keenableScraperOptions', webSearchConfig?.keenableScraperOptions),
+ scraperProvider === ScraperProviders.KEENABLE ? keenableScraperApiKey : undefined,
+ );
return {
authTypes,
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 2dd32be302..642ebb37e9 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -3598,6 +3598,7 @@ export const webSearchSchema = z.object({
tavilySearchUrl: z.string().optional().default('${TAVILY_SEARCH_URL}'),
tavilyExtractUrl: z.string().optional().default('${TAVILY_EXTRACT_URL}'),
keenableApiKey: z.string().optional().default('${KEENABLE_API_KEY}'),
+ keenableApiKeyPreview: apiKeyPreviewSchema,
keenableApiUrl: z.string().optional().default('${KEENABLE_API_URL}'),
jinaApiKey: z.string().optional().default('${JINA_API_KEY}'),
jinaApiKeyPreview: apiKeyPreviewSchema,
diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.ts
index 173dbf0075..73cffd4e63 100644
--- a/packages/data-schemas/src/app/resolution.spec.ts
+++ b/packages/data-schemas/src/app/resolution.spec.ts
@@ -1,5 +1,9 @@
-import { INTERFACE_PERMISSION_FIELDS, PermissionTypes } from 'librechat-data-provider';
-import type { TCustomConfig } from 'librechat-data-provider';
+import {
+ PermissionTypes,
+ SearchProviders,
+ INTERFACE_PERMISSION_FIELDS,
+} from 'librechat-data-provider';
+import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provider';
import type { AppConfig, IConfig } from '~/types';
import {
getConfigMergeRules,
@@ -10,6 +14,8 @@ import {
getConfigOverrideIssues,
} from './resolution';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
+import { loadWebSearchConfig } from './web';
+import logger from '~/config/winston';
function fakeConfig(
overrides: Record<string, unknown>,
@@ -1248,6 +1254,178 @@ describe('mergeConfigOverrides: invalid stored overrides', () => {
});
});
+describe('mergeConfigOverrides: web search keys follow the layer that set their URL', () => {
+ type WebSearch = Record<string, string | number | undefined>;
+ const yaml = {
+ searchProvider: SearchProviders.KEENABLE,
+ keenableApiUrl: 'https://keenable.operator.example.com',
+ keenableApiKey: 'kn-yaml-literal-0001',
+ } satisfies TWebSearchConfigInput;
+ const base = {
+ config: { webSearch: yaml },
+ webSearch: loadWebSearchConfig(yaml),
+ } as unknown as AppConfig;
+
+ function baseProfile(webSearch: WebSearch, tombstones?: string[]): IConfig {
+ return fakeConfig({ webSearch }, 0, tombstones, BASE_CONFIG_PRINCIPAL_ID);
+ }
+
+ function roleProfile(webSearch: WebSearch, tombstones?: string[]): IConfig {
+ return fakeConfig({ webSearch }, 10, tombstones, 'ADMIN');
+ }
+
+ function mergedWebSearch(...configs: IConfig[]): WebSearch {
+ return mergeConfigOverrides(base, configs).webSearch as WebSearch;
+ }
+
+ let warn: jest.SpyInstance;
+ beforeEach(() => {
+ warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+ });
+
+ afterEach(() => {
+ warn.mockRestore();
+ });
+
+ it('drops a key stored in the base profile when a role profile sets only its URL', () => {
+ const webSearch = mergedWebSearch(
+ baseProfile({
+ searxngInstanceUrl: 'https://searx.operator.example.com',
+ searxngApiKey: 'sx-base-secret-0001',
+ }),
+ roleProfile({ searxngInstanceUrl: 'https://capture.example.com' }),
+ );
+
+ expect(webSearch.searxngInstanceUrl).toBe('https://capture.example.com');
+ expect(webSearch).not.toHaveProperty('searxngApiKey');
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining(
+ `webSearch.searxngApiKey from role/${BASE_CONFIG_PRINCIPAL_ID}: webSearch.searxngInstanceUrl is set by role/ADMIN`,
+ ),
+ );
+ expect(JSON.stringify(warn.mock.calls)).not.toContain('sx-base-secret-0001');
+ });
+
+ it('drops a librechat.yaml key when an override sets its URL', () => {
+ const webSearch = mergedWebSearch(
+ baseProfile({ keenableApiUrl: 'https://capture.example.com' }),
+ );
+
+ expect(webSearch.keenableApiUrl).toBe('https://capture.example.com');
+ expect(webSearch).not.toHaveProperty('keenableApiKey');
+ });
+
+ it('drops a key a layer stores for a URL it inherits', () => {
+ const webSearch = mergedWebSearch(roleProfile({ keenableApiKey: 'kn-role-0001' }));
+
+ expect(webSearch.keenableApiUrl).toBe(yaml.keenableApiUrl);
+ expect(webSearch).not.toHaveProperty('keenableApiKey');
+ });
+
+ it('keeps a key stored in the same layer as its URL', () => {
+ expect(mergedWebSearch(roleProfile({ safeSearch: 0 }))).toMatchObject({
+ keenableApiUrl: yaml.keenableApiUrl,
+ keenableApiKey: yaml.keenableApiKey,
+ });
+ expect(
+ mergedWebSearch(
+ baseProfile({
+ searxngInstanceUrl: 'https://searx.operator.example.com',
+ searxngApiKey: 'sx-base-secret-0001',
+ }),
+ roleProfile({
+ keenableApiUrl: 'https://keenable.role.example.com',
+ keenableApiKey: 'kn-role-0001',
+ }),
+ ),
+ ).toMatchObject({
+ searxngInstanceUrl: 'https://searx.operator.example.com',
+ searxngApiKey: 'sx-base-secret-0001',
+ keenableApiUrl: 'https://keenable.role.example.com',
+ keenableApiKey: 'kn-role-0001',
+ });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ { name: 'points it at an environment variable', url: '${OTHER_SERVICE_URL}' },
+ { name: 'blanks it', url: '' },
+ ])('drops a base profile key when a role profile $name', ({ url }) => {
+ const webSearch = mergedWebSearch(
+ baseProfile({
+ searxngInstanceUrl: 'https://searx.operator.example.com',
+ searxngApiKey: 'sx-base-secret-0001',
+ }),
+ roleProfile({ searxngInstanceUrl: url }),
+ );
+
+ expect(webSearch.searxngInstanceUrl).toBe(url);
+ expect(webSearch).not.toHaveProperty('searxngApiKey');
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining('webSearch.searxngInstanceUrl is set by role/ADMIN'),
+ );
+ });
+
+ it('drops a librechat.yaml key when an override points its URL at the environment', () => {
+ const webSearch = mergedWebSearch(
+ baseProfile({ keenableApiUrl: '${KEENABLE_API_URL}' }),
+ roleProfile({ firecrawlApiUrl: 'https://firecrawl.role.example.com' }),
+ );
+
+ expect(webSearch.keenableApiUrl).toBe('${KEENABLE_API_URL}');
+ expect(webSearch).not.toHaveProperty('keenableApiKey');
+ expect(webSearch.searxngApiKey).toBe('${SEARXNG_API_KEY}');
+ });
+
+ it('drops the key when a later layer tombstones its URL', () => {
+ const webSearch = mergedWebSearch(roleProfile({}, ['webSearch.keenableApiUrl']));
+
+ expect(webSearch).not.toHaveProperty('keenableApiUrl');
+ expect(webSearch).not.toHaveProperty('keenableApiKey');
+ expect(warn).toHaveBeenCalledWith(
+ expect.stringContaining(
+ 'webSearch.keenableApiKey from the base config: webSearch.keenableApiUrl is removed by role/ADMIN',
+ ),
+ );
+ expect(JSON.stringify(warn.mock.calls)).not.toContain(yaml.keenableApiKey);
+ });
+
+ it('keeps a key a profile stores over an environment URL it inherits', () => {
+ expect(
+ mergedWebSearch(
+ baseProfile({ firecrawlApiKey: 'fc-base-0001' }),
+ roleProfile({ safeSearch: 0 }),
+ ),
+ ).toMatchObject({ firecrawlApiUrl: '${FIRECRAWL_API_URL}', firecrawlApiKey: 'fc-base-0001' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('keeps a key the same profile stores beside its own tombstone of the URL', () => {
+ const webSearch = mergedWebSearch(
+ roleProfile({ keenableApiKey: 'kn-role-0001' }, ['webSearch.keenableApiUrl']),
+ );
+
+ expect(webSearch).not.toHaveProperty('keenableApiUrl');
+ expect(webSearch.keenableApiKey).toBe('kn-role-0001');
+ });
+
+ it('keeps a key a later profile stores with the URL a lower profile removed', () => {
+ const webSearch = mergedWebSearch(
+ baseProfile({}, ['webSearch']),
+ roleProfile({
+ keenableApiUrl: 'https://keenable.role.example.com',
+ keenableApiKey: 'kn-role-0001',
+ }),
+ );
+
+ expect(webSearch).toMatchObject({
+ keenableApiUrl: 'https://keenable.role.example.com',
+ keenableApiKey: 'kn-role-0001',
+ });
+ expect(warn).not.toHaveBeenCalled();
+ });
+});
+
describe('INTERFACE_PERMISSION_FIELDS', () => {
it('contains all expected permission fields', () => {
const expected = [
diff --git a/packages/data-schemas/src/app/resolution.ts b/packages/data-schemas/src/app/resolution.ts
index 99c9c86ac9..b0a2f426da 100644
--- a/packages/data-schemas/src/app/resolution.ts
+++ b/packages/data-schemas/src/app/resolution.ts
@@ -9,7 +9,8 @@ import {
configSchema,
} from 'librechat-data-provider';
import type { TCustomConfig } from 'librechat-data-provider';
-import type { AdminConfigMergeRules, AppConfig, IConfig } from '~/types';
+import type { AdminConfigMergeRules, AppConfig, IConfig, TWebSearchKeys } from '~/types';
+import { webSearchPairedFields, unbindWebSearchKeys } from './web';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
import { getTombstonePathsToClear } from '~/methods/config';
import logger from '~/config/winston';
@@ -866,11 +867,90 @@ function filterMCPServerOverrides(value: unknown, current: unknown): AnyObject {
return filtered;
}
+/** The override document that last set or removed a paired web search field, and its merge position. */
+interface WebSearchWriter {
+ config: IConfig;
+ order: number;
+ removed: boolean;
+}
+
+type WebSearchWriters = Map<TWebSearchKeys, WebSearchWriter>;
+
+const WEB_SEARCH_TOMBSTONE_PREFIX = 'webSearch.';
+
+/** Records `writer` for each paired web search field its applied overrides set. */
+function recordWebSearchWrites(
+ writers: WebSearchWriters,
+ section: unknown,
+ writer: WebSearchWriter,
+): void {
+ if (!isPlainObject(section)) {
+ return;
+ }
+ for (const field of webSearchPairedFields) {
+ if (hasOwn(section, field)) {
+ writers.set(field, writer);
+ }
+ }
+}
+
+/** Records `writer` for each paired web search field an applied tombstone removes. */
+function recordWebSearchTombstone(
+ writers: WebSearchWriters,
+ path: string,
+ writer: WebSearchWriter,
+): void {
+ if (path === 'webSearch') {
+ for (const field of webSearchPairedFields) {
+ writers.set(field, writer);
+ }
+ return;
+ }
+ if (!path.startsWith(WEB_SEARCH_TOMBSTONE_PREFIX)) {
+ return;
+ }
+ const field = path.slice(WEB_SEARCH_TOMBSTONE_PREFIX.length) as TWebSearchKeys;
+ if (webSearchPairedFields.includes(field)) {
+ writers.set(field, writer);
+ }
+}
+
+function describeLayer(writer?: WebSearchWriter): string {
+ return writer ? `${writer.config.principalType}/${writer.config.principalId}` : 'the base config';
+}
+
+/**
+ * Withholds each stored web search key whose URL a layer other than the key's
+ * own decides (`unbindWebSearchKeys`), so a layer that overrides only a URL
+ * never sends on a key it cannot read. `writers` lists the override document
+ * behind each field; unlisted fields come from the base config.
+ */
+function bindWebSearchKeys(merged: AppConfig, writers: WebSearchWriters): AppConfig {
+ const { webSearch, unbound } = unbindWebSearchKeys(
+ merged.webSearch,
+ (field) => writers.get(field)?.order,
+ );
+ if (unbound.length === 0) {
+ return merged;
+ }
+ for (const { url, apiKey } of unbound) {
+ const urlWriter = writers.get(url);
+ logger.warn(
+ `[mergeConfigOverrides] Ignoring webSearch.${apiKey} from ${describeLayer(writers.get(apiKey))}: ` +
+ `webSearch.${url} is ${urlWriter?.removed ? 'removed' : 'set'} by ${describeLayer(urlWriter)}. ` +
+ 'Store the key in the same config as the URL.',
+ );
+ }
+ return { ...merged, webSearch };
+}
+
/**
* Merge DB config overrides into a base AppConfig.
*
* Configs are sorted by priority ascending (lowest first, highest wins).
* Each config's `overrides` is deep-merged into the base config in order.
+ * A stored web search key is dropped when a layer other than its own decides
+ * the URL it is sent to.
*/
export function mergeConfigOverrides(baseConfig: AppConfig, configs: IConfig[]): AppConfig {
if (!configs || configs.length === 0) {
@@ -882,9 +962,12 @@ export function mergeConfigOverrides(baseConfig: AppConfig, configs: IConfig[]):
let merged = { ...baseConfig };
/** The YAML-shaped config the next override lands on, for validating it in place. */
let raw: Partial<TCustomConfig> = baseConfig.config ?? {};
- for (const config of sorted) {
+ const webSearchWriters: WebSearchWriters = new Map();
+ for (let order = 0; order < sorted.length; order++) {
+ const config = sorted[order];
const isBasePrincipal = config.principalId?.toString() === BASE_CONFIG_PRINCIPAL_ID;
if (Array.isArray(config.tombstones)) {
+ const removal: WebSearchWriter = { config, order, removed: true };
for (const path of config.tombstones) {
if (
typeof path === 'string' &&
@@ -893,6 +976,7 @@ export function mergeConfigOverrides(baseConfig: AppConfig, configs: IConfig[]):
) {
merged = deleteConfigPath(merged, remapOverridePath(path));
raw = deletePath(raw as AnyObject, path) as Partial<TCustomConfig>;
+ recordWebSearchTombstone(webSearchWriters, path, removal);
}
}
}
@@ -958,9 +1042,15 @@ export function mergeConfigOverrides(baseConfig: AppConfig, configs: IConfig[]):
}
merged = deepMerge(merged, remapped);
raw = deepMerge(raw as AnyObject, applied) as Partial<TCustomConfig>;
+ recordWebSearchWrites(webSearchWriters, applied.webSearch, {
+ config,
+ order,
+ removed: false,
+ });
}
}
+ merged = bindWebSearchKeys(merged, webSearchWriters);
return preserveBaseOnlyPaths(baseConfig, preserveRuntimeStops(baseConfig, merged));
}
diff --git a/packages/data-schemas/src/app/web.spec.ts b/packages/data-schemas/src/app/web.spec.ts
index fd073ca0ef..08c7d5c9e5 100644
--- a/packages/data-schemas/src/app/web.spec.ts
+++ b/packages/data-schemas/src/app/web.spec.ts
@@ -1,6 +1,15 @@
import { SafeSearchTypes, SearchProviders, ScraperProviders } from 'librechat-data-provider';
import type { TCustomConfig } from 'librechat-data-provider';
-import { loadWebSearchConfig, webSearchAuth, getWebSearchKeys } from './web';
+import {
+ webSearchAuth,
+ getWebSearchKeys,
+ loadWebSearchConfig,
+ webSearchUrlApiKeys,
+ unbindWebSearchKeys,
+ webSearchPairedFields,
+ isStoredWebSearchValue,
+ getRebindingWebSearchKeys,
+} from './web';
describe('loadWebSearchConfig', () => {
describe('firecrawlVersion', () => {
@@ -252,4 +261,261 @@ describe('webSearchAuth', () => {
expect(keys.filter((key) => key === 'keenableApiKey')).toHaveLength(1);
expect(keys).toContain('keenableApiUrl');
});
+
+ it('pairs every service URL with the API key of a service that reads both', () => {
+ const services = Object.values(webSearchAuth).flatMap((category) => Object.values(category));
+ const urlKeys = getWebSearchKeys().filter((key) => key.endsWith('Url'));
+
+ expect([...webSearchUrlApiKeys.keys()].sort()).toEqual([...urlKeys].sort());
+ for (const [urlKey, apiKey] of webSearchUrlApiKeys) {
+ expect(services.some((service) => urlKey in service && apiKey in service)).toBe(true);
+ }
+ });
+});
+
+describe('isStoredWebSearchValue', () => {
+ it.each(['https://searx.example.com', 'sk-literal-0001', 'v3:00:ff'])(
+ 'counts %s as stored in config',
+ (value) => {
+ expect(isStoredWebSearchValue(value)).toBe(true);
+ },
+ );
+
+ it.each(['', ' ', 'user_provided', ' user_provided ', '${SEARXNG_API_KEY}', undefined, 5])(
+ 'does not count %p as stored in config',
+ (value) => {
+ expect(isStoredWebSearchValue(value)).toBe(false);
+ },
+ );
+});
+
+describe('unbindWebSearchKeys', () => {
+ /** Merge positions by field; an unlisted field comes from the base config. */
+ const layers = (byField: Partial<Record<string, number>>) => (field: string) => byField[field];
+
+ it('lists every paired URL and key once', () => {
+ expect(new Set(webSearchPairedFields).size).toBe(webSearchPairedFields.length);
+ expect([...webSearchPairedFields].sort()).toEqual(
+ [...new Set([...webSearchUrlApiKeys.keys(), ...webSearchUrlApiKeys.values()])].sort(),
+ );
+ });
+
+ it('drops a stored key whose stored URL a later layer set', () => {
+ const webSearch = {
+ searxngInstanceUrl: 'https://attacker.example.com',
+ searxngApiKey: 'sx-base-secret-0001',
+ serperApiKey: 'serper-literal-0001',
+ };
+
+ const result = unbindWebSearchKeys(webSearch, layers({ searxngInstanceUrl: 1 }));
+
+ expect(result.webSearch).toEqual({
+ searxngInstanceUrl: 'https://attacker.example.com',
+ serperApiKey: 'serper-literal-0001',
+ });
+ expect(result.unbound).toEqual([{ url: 'searxngInstanceUrl', apiKey: 'searxngApiKey' }]);
+ expect(webSearch.searxngApiKey).toBe('sx-base-secret-0001');
+ });
+
+ it('drops a key a layer stores for a stored URL it inherits', () => {
+ const webSearch = { keenableApiUrl: 'https://k.example.com', keenableApiKey: 'kn-0001' };
+
+ const result = unbindWebSearchKeys(webSearch, layers({ keenableApiKey: 2 }));
+
+ expect(result.webSearch).toEqual({ keenableApiUrl: 'https://k.example.com' });
+ expect(result.unbound).toEqual([{ url: 'keenableApiUrl', apiKey: 'keenableApiKey' }]);
+ });
+
+ it('keeps a stored key the layer that set its URL also stored', () => {
+ const webSearch = { keenableApiUrl: 'https://k.example.com', keenableApiKey: 'kn-0001' };
+
+ const result = unbindWebSearchKeys(webSearch, layers({ keenableApiUrl: 1, keenableApiKey: 1 }));
+
+ expect(result.webSearch).toBe(webSearch);
+ expect(result.unbound).toEqual([]);
+ });
+
+ it.each([
+ { name: 'points it at an environment reference', url: '${OTHER_SERVICE_URL}' },
+ { name: 'blanks it', url: '' },
+ { name: 'sets it to null', url: null },
+ { name: 'leaves it to users', url: 'user_provided' },
+ { name: 'removes it', url: undefined },
+ ])('drops a stored key when a later layer $name', ({ url }) => {
+ const webSearch = { firecrawlApiUrl: url, firecrawlApiKey: 'fc-literal-0001' };
+
+ const result = unbindWebSearchKeys(
+ webSearch,
+ layers({ firecrawlApiKey: 0, firecrawlApiUrl: 1 }),
+ );
+
+ expect(result.webSearch).not.toHaveProperty('firecrawlApiKey');
+ expect(result.unbound).toEqual([{ url: 'firecrawlApiUrl', apiKey: 'firecrawlApiKey' }]);
+ });
+
+ it('keeps a stored key written over an inherited environment URL', () => {
+ const webSearch = {
+ firecrawlApiUrl: '${FIRECRAWL_API_URL}',
+ firecrawlApiKey: 'fc-literal-0001',
+ jinaApiUrl: '${JINA_API_URL}',
+ jinaApiKey: 'jina-literal-0001',
+ };
+
+ const result = unbindWebSearchKeys(
+ webSearch,
+ layers({ firecrawlApiKey: 1, jinaApiUrl: 0, jinaApiKey: 2 }),
+ );
+
+ expect(result.webSearch).toBe(webSearch);
+ expect(result.unbound).toEqual([]);
+ });
+
+ it('leaves environment and user keys to the runtime rules', () => {
+ const webSearch = {
+ searxngInstanceUrl: 'https://searx.example.com',
+ searxngApiKey: '${SEARXNG_API_KEY}',
+ jinaApiUrl: 'https://jina.example.com',
+ jinaApiKey: 'user_provided',
+ };
+
+ const result = unbindWebSearchKeys(webSearch, layers({ searxngInstanceUrl: 1, jinaApiUrl: 1 }));
+
+ expect(result.webSearch).toBe(webSearch);
+ expect(result.unbound).toEqual([]);
+ });
+
+ it('drops a shared key when either of its URLs comes from another layer', () => {
+ const webSearch = {
+ tavilySearchUrl: 'https://tavily.example.com/search',
+ tavilyExtractUrl: 'https://elsewhere.example.com/extract',
+ tavilyApiKey: 'tvly-0001',
+ };
+
+ const result = unbindWebSearchKeys(
+ webSearch,
+ layers({ tavilySearchUrl: 0, tavilyApiKey: 0, tavilyExtractUrl: 1 }),
+ );
+
+ expect(result.webSearch).toEqual({
+ tavilySearchUrl: 'https://tavily.example.com/search',
+ tavilyExtractUrl: 'https://elsewhere.example.com/extract',
+ });
+ expect(result.unbound).toEqual([{ url: 'tavilyExtractUrl', apiKey: 'tavilyApiKey' }]);
+ });
+});
+
+describe('getRebindingWebSearchKeys', () => {
+ const STORED_KEY = 'v3:00112233445566778899aabbccddeeff:abcdef';
+ const stored = {
+ searxngInstanceUrl: 'https://searx.example.com',
+ searxngApiKey: STORED_KEY,
+ serperApiKey: STORED_KEY,
+ };
+ const SEARXNG = [{ url: 'searxngInstanceUrl', apiKey: 'searxngApiKey' }];
+
+ it.each([
+ { name: 'changes it', url: 'https://attacker.example.com' },
+ { name: 'points it at an environment reference', url: '${SEARXNG_INSTANCE_URL}' },
+ { name: 'blanks it', url: '' },
+ { name: 'tombstones it', url: null },
+ { name: 'leaves it to users', url: 'user_provided' },
+ ])('lists a stored key the write kept when it $name', ({ url }) => {
+ const next = { ...stored, searxngInstanceUrl: url };
+
+ expect(getRebindingWebSearchKeys(stored, next, new Set(['searxngInstanceUrl']))).toEqual(
+ SEARXNG,
+ );
+ });
+
+ it('lists a stored key whose URL the write removes', () => {
+ const next = { searxngApiKey: STORED_KEY, serperApiKey: STORED_KEY };
+
+ expect(getRebindingWebSearchKeys(stored, next, new Set())).toEqual(SEARXNG);
+ });
+
+ it('lists a URL a write adds beside a key the document already stores', () => {
+ const keyOnly = { firecrawlApiKey: STORED_KEY };
+ const next = { ...keyOnly, firecrawlApiUrl: '${FIRECRAWL_API_URL}' };
+
+ expect(getRebindingWebSearchKeys(keyOnly, next, new Set(['firecrawlApiUrl']))).toEqual([
+ { url: 'firecrawlApiUrl', apiKey: 'firecrawlApiKey' },
+ ]);
+ });
+
+ it.each([
+ { name: 'a literal URL replaces it', url: 'https://keenable.example.com' },
+ { name: 'it names another variable', url: '${OTHER_SERVICE_URL}' },
+ ])('lists a key beside an environment URL when $name', ({ url }) => {
+ const fromEnv = { keenableApiUrl: '${KEENABLE_API_URL}', keenableApiKey: STORED_KEY };
+ const next = { ...fromEnv, keenableApiUrl: url };
+
+ expect(getRebindingWebSearchKeys(fromEnv, next, new Set(['keenableApiUrl']))).toEqual([
+ { url: 'keenableApiUrl', apiKey: 'keenableApiKey' },
+ ]);
+ });
+
+ it('lists the shared Tavily key once per changed URL', () => {
+ const tavily = {
+ tavilySearchUrl: 'https://tavily.example.com/search',
+ tavilyExtractUrl: 'https://tavily.example.com/extract',
+ tavilyApiKey: STORED_KEY,
+ };
+ const next = { ...tavily, tavilyExtractUrl: 'https://elsewhere.example.com/extract' };
+
+ expect(getRebindingWebSearchKeys(tavily, next, new Set())).toEqual([
+ { url: 'tavilyExtractUrl', apiKey: 'tavilyApiKey' },
+ ]);
+ });
+
+ const moved = { ...stored, searxngInstanceUrl: 'https://attacker.example.com' };
+ it.each([
+ {
+ name: 'the write enters the key again beside the new URL',
+ before: stored,
+ next: { ...moved, searxngApiKey: 'sx-new-key' },
+ written: ['searxngInstanceUrl', 'searxngApiKey'],
+ },
+ {
+ name: 'the write clears the key',
+ before: stored,
+ next: { ...moved, searxngApiKey: '' },
+ written: ['searxngInstanceUrl', 'searxngApiKey'],
+ },
+ {
+ name: 'the key becomes an environment reference',
+ before: stored,
+ next: { ...moved, searxngApiKey: '${SEARXNG_API_KEY}' },
+ written: ['searxngInstanceUrl', 'searxngApiKey'],
+ },
+ {
+ name: 'the URL is spelled differently',
+ before: stored,
+ next: { ...stored, searxngInstanceUrl: ' HTTPS://Searx.Example.com ' },
+ written: ['searxngInstanceUrl'],
+ },
+ {
+ name: 'the same environment reference is written again',
+ before: { ...stored, searxngInstanceUrl: '${SEARXNG_INSTANCE_URL}' },
+ next: { ...stored, searxngInstanceUrl: ' ${SEARXNG_INSTANCE_URL}' },
+ written: ['searxngInstanceUrl'],
+ },
+ {
+ name: 'a tombstoned URL is blanked instead',
+ before: { ...stored, searxngInstanceUrl: null },
+ next: { ...stored, searxngInstanceUrl: ' ' },
+ written: ['searxngInstanceUrl'],
+ },
+ {
+ name: 'only another field changes',
+ before: stored,
+ next: { ...stored, safeSearch: 2 },
+ written: ['safeSearch'],
+ },
+ ])('lists nothing when $name', ({ before, next, written }) => {
+ expect(getRebindingWebSearchKeys(before, next, new Set(written))).toEqual([]);
+ });
+
+ it('lists nothing when no web search section remains', () => {
+ expect(getRebindingWebSearchKeys(stored, undefined, new Set())).toEqual([]);
+ });
});
diff --git a/packages/data-schemas/src/app/web.ts b/packages/data-schemas/src/app/web.ts
index c30ace3ac4..74bf9ae4a8 100644
--- a/packages/data-schemas/src/app/web.ts
+++ b/packages/data-schemas/src/app/web.ts
@@ -1,4 +1,9 @@
-import { SafeSearchTypes, normalizeSearxngEngines } from 'librechat-data-provider';
+import {
+ AuthType,
+ SafeSearchTypes,
+ extractVariableName,
+ normalizeSearxngEngines,
+} from 'librechat-data-provider';
import type { TCustomConfig, TWebSearchConfigInput } from 'librechat-data-provider';
import type { TWebSearchKeys, TWebSearchCategories } from '~/types/web';
@@ -79,6 +84,141 @@ export function getWebSearchKeys(): TWebSearchKeys[] {
export const webSearchKeys: TWebSearchKeys[] = getWebSearchKeys();
+/** Each configurable service URL and the API key sent to it. */
+export const webSearchUrlApiKeys: ReadonlyMap<TWebSearchKeys, TWebSearchKeys> = new Map<
+ TWebSearchKeys,
+ TWebSearchKeys
+>([
+ ['searxngInstanceUrl', 'searxngApiKey'],
+ ['firecrawlApiUrl', 'firecrawlApiKey'],
+ ['jinaApiUrl', 'jinaApiKey'],
+ ['tavilySearchUrl', 'tavilyApiKey'],
+ ['tavilyExtractUrl', 'tavilyApiKey'],
+ ['keenableApiUrl', 'keenableApiKey'],
+]);
+
+/** Every web search URL that receives an API key, and every key sent to one. */
+export const webSearchPairedFields: readonly TWebSearchKeys[] = [
+ ...new Set([...webSearchUrlApiKeys.keys(), ...webSearchUrlApiKeys.values()]),
+];
+
+/**
+ * Whether a web search value is stored in config itself, as a librechat.yaml
+ * literal or a value the admin config API saved, rather than a `${VAR}`
+ * reference to the environment. Blank and `user_provided` values supply nothing.
+ */
+export function isStoredWebSearchValue(value: unknown): value is string {
+ if (typeof value !== 'string') {
+ return false;
+ }
+ const trimmed = value.trim();
+ return (
+ trimmed !== '' && trimmed !== AuthType.USER_PROVIDED && extractVariableName(trimmed) == null
+ );
+}
+
+/** A web search URL and the stored API key a binding rule keeps from it. */
+export interface WebSearchKeyBinding {
+ url: TWebSearchKeys;
+ apiKey: TWebSearchKeys;
+}
+
+/**
+ * Removes each stored API key that would reach a destination it was not
+ * entered for:
+ * - a later layer than the key's own set or removed its paired URL, whatever
+ * the new value (a literal, a `${VAR}` reference, blank or a tombstone);
+ * - the paired URL is stored in config and another layer set it, which covers
+ * a key stored for a URL it inherits.
+ *
+ * A key stored over an inherited `${VAR}` URL is kept. `${VAR}` keys are left
+ * to web search's runtime rules, which never send an environment key or a
+ * user's own key to a URL stored in config.
+ * @param layerOf - The merge position of the layer that last set or removed a field; `undefined` for the base config, which merges first.
+ */
+export function unbindWebSearchKeys<T extends Partial<Record<TWebSearchKeys, unknown>>>(
+ webSearch: T | undefined,
+ layerOf: (field: TWebSearchKeys) => number | undefined,
+): { webSearch: T | undefined; unbound: WebSearchKeyBinding[] } {
+ if (webSearch == null) {
+ return { webSearch, unbound: [] };
+ }
+ const unbound: WebSearchKeyBinding[] = [];
+ for (const [url, apiKey] of webSearchUrlApiKeys) {
+ if (!isStoredWebSearchValue(webSearch[apiKey])) {
+ continue;
+ }
+ const urlLayer = layerOf(url) ?? -1;
+ const keyLayer = layerOf(apiKey) ?? -1;
+ if (urlLayer > keyLayer || (urlLayer !== keyLayer && isStoredWebSearchValue(webSearch[url]))) {
+ unbound.push({ url, apiKey });
+ }
+ }
+ if (unbound.length === 0) {
+ return { webSearch, unbound };
+ }
+ const bound: T = { ...webSearch };
+ for (const { apiKey } of unbound) {
+ delete bound[apiKey];
+ }
+ return { webSearch: bound, unbound };
+}
+
+/**
+ * A URL as a request destination, so spellings of the same address compare
+ * equal. Blank and `null` both read as `null`: each suppresses the inherited
+ * URL, as a tombstone does.
+ */
+function toDestination(value: unknown): unknown {
+ if (typeof value !== 'string') {
+ return value;
+ }
+ const trimmed = value.trim();
+ if (trimmed === '') {
+ return null;
+ }
+ try {
+ return new URL(trimmed).href;
+ } catch {
+ return trimmed;
+ }
+}
+
+/**
+ * Lists each stored API key that a write to one config document would send to
+ * a new destination without the key being entered again: the write sets,
+ * changes, blanks or removes the paired URL in that document, including a
+ * change to or from a `${VAR}` reference, and leaves the stored key in place.
+ * This is the admin config tier's form of the re-entry rule MCP servers apply
+ * to stored credentials (`getChangedApiKeyBindingFields`).
+ *
+ * Pass each state as the document's own view: its stored values, with `null`
+ * for a field it tombstones and does not set.
+ * @param stored - The document's web search view before the write.
+ * @param next - The document's web search view after the write, omitted secrets preserved.
+ * @param written - The web search fields the write itself supplied.
+ */
+export function getRebindingWebSearchKeys(
+ stored: Partial<Record<TWebSearchKeys, unknown>> | undefined,
+ next: Partial<Record<TWebSearchKeys, unknown>> | undefined,
+ written: ReadonlySet<string>,
+): WebSearchKeyBinding[] {
+ if (next == null) {
+ return [];
+ }
+ const rebinding: WebSearchKeyBinding[] = [];
+ for (const [url, apiKey] of webSearchUrlApiKeys) {
+ if (
+ !written.has(apiKey) &&
+ isStoredWebSearchValue(next[apiKey]) &&
+ toDestination(next[url]) !== toDestination(stored?.[url])
+ ) {
+ rebinding.push({ url, apiKey });
+ }
+ }
+ return rebinding;
+}
+
export const webSearchSelectionFields = {
selectedProvider: 'LIBRECHAT_WEB_SEARCH_PROVIDER',
selectedScraper: 'LIBRECHAT_WEB_SEARCH_SCRAPER',
diff --git a/packages/data-schemas/src/methods/config.spec.ts b/packages/data-schemas/src/methods/config.spec.ts
index d0eba53048..3acbc3e767 100644
--- a/packages/data-schemas/src/methods/config.spec.ts
+++ b/packages/data-schemas/src/methods/config.spec.ts
@@ -688,3 +688,228 @@ describe('toggleConfigActiveTracked', () => {
expect(missing).toBeNull();
});
});
+
+describe('expectedVersion write precondition', () => {
+ const ROLE = 'precondition-role';
+
+ async function seed(): Promise<IConfig> {
+ const config = await methods.patchConfigFields(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ { 'webSearch.searxngInstanceUrl': 'https://searx.example.com' },
+ 10,
+ );
+ return config!;
+ }
+
+ async function readStored(): Promise<Record<string, unknown> | null> {
+ return mongoose.models.Config.findOne({ principalId: ROLE }).lean<Record<string, unknown>>();
+ }
+
+ type Write = (expectedVersion: number | null) => Promise<IConfig | null>;
+ const writes: Array<{ name: string; write: Write }> = [
+ {
+ name: 'patchConfigFields',
+ write: (expectedVersion) =>
+ methods.patchConfigFields(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ { 'webSearch.searxngInstanceUrl': 'https://attacker.example.com' },
+ 10,
+ undefined,
+ { expectedVersion },
+ ),
+ },
+ {
+ name: 'upsertConfig',
+ write: (expectedVersion) =>
+ methods.upsertConfig(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ { webSearch: { searxngInstanceUrl: 'https://attacker.example.com' } },
+ 10,
+ undefined,
+ { expectedVersion },
+ ),
+ },
+ {
+ name: 'tombstoneConfigField',
+ write: (expectedVersion) =>
+ methods.tombstoneConfigField(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ 'webSearch.searxngInstanceUrl',
+ 10,
+ undefined,
+ { expectedVersion },
+ ),
+ },
+ ];
+
+ it.each(writes)('$name applies at the version the caller read', async ({ write }) => {
+ const seeded = await seed();
+
+ const result = await write(seeded.configVersion);
+
+ expect(result).not.toBeNull();
+ expect(result!.configVersion).toBe(seeded.configVersion + 1);
+ });
+
+ it.each(writes)(
+ '$name changes nothing once another write moved the version',
+ async ({ write }) => {
+ const seeded = await seed();
+ await methods.patchConfigFields(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ { 'webSearch.searxngApiKey': 'v3:concurrent' },
+ 10,
+ );
+ const before = await readStored();
+
+ expect(await write(seeded.configVersion)).toBeNull();
+ expect(await readStored()).toEqual(before);
+ },
+ );
+
+ it.each(writes)('$name creates the document the caller saw absent', async ({ write }) => {
+ const result = await write(null);
+
+ expect(result).not.toBeNull();
+ expect(result!.configVersion).toBe(1);
+ expect(result!.createdAt).toBeInstanceOf(Date);
+ expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(1);
+ });
+
+ it('detects a document that appeared without relying on the unique index', async () => {
+ const Config = mongoose.models.Config;
+ await seed();
+ await Config.collection.dropIndexes();
+ try {
+ expect(await writes[0].write(null)).toBeNull();
+ expect(await Config.countDocuments({ principalId: ROLE })).toBe(1);
+ } finally {
+ await Config.syncIndexes();
+ }
+ });
+
+ it.each(writes)(
+ '$name changes nothing when a document appeared after the caller saw none',
+ async ({ write }) => {
+ await seed();
+ const before = await readStored();
+
+ expect(await write(null)).toBeNull();
+ expect(await readStored()).toEqual(before);
+ },
+ );
+
+ it.each(writes)(
+ '$name does not recreate a document deleted since the read',
+ async ({ write }) => {
+ const seeded = await seed();
+ await methods.deleteConfig(PrincipalType.ROLE, ROLE);
+
+ expect(await write(seeded.configVersion)).toBeNull();
+ expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(0);
+ },
+ );
+
+ /**
+ * Makes the database refuse the version-checked write, the way an engine that cannot store a
+ * key name does, after `beforeRefusal` runs. The created empty document's upsert still lands.
+ */
+ function refuseVersionedWrites(beforeRefusal: () => Promise<void> = async () => undefined) {
+ const collection = mongoose.models.Config.collection;
+ const findOneAndUpdate = collection.findOneAndUpdate.bind(collection);
+ jest.spyOn(collection, 'findOneAndUpdate').mockImplementation((async (
+ filter: Record<string, unknown>,
+ update: { $inc?: Record<string, number> },
+ options: Record<string, unknown>,
+ ) => {
+ if (update.$inc == null) {
+ return findOneAndUpdate(filter, update, options);
+ }
+ await beforeRefusal();
+ throw new mongoose.mongo.MongoServerError({
+ ok: 0,
+ code: 57,
+ errmsg: "The dotted field 'us.a.b' in 'overrides' is not valid for storage.",
+ });
+ }) as unknown as typeof collection.findOneAndUpdate);
+ }
+
+ it.each(writes)(
+ '$name leaves no document when the database refuses a write the caller saw absent',
+ async ({ write }) => {
+ refuseVersionedWrites();
+
+ await expect(write(null)).rejects.toMatchObject({ code: 57 });
+ expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(0);
+ },
+ );
+
+ it('reports a failed cleanup instead of the refusal, since the created document remains', async () => {
+ refuseVersionedWrites();
+ const collection = mongoose.models.Config.collection;
+ jest.spyOn(collection, 'deleteOne').mockRejectedValueOnce(new Error('connection reset'));
+
+ await expect(writes[0].write(null)).rejects.toThrow('connection reset');
+ expect(await mongoose.models.Config.countDocuments({ principalId: ROLE })).toBe(1);
+ });
+
+ it('keeps a document another write changed before the database refused this one', async () => {
+ refuseVersionedWrites(async () => {
+ await mongoose.models.Config.updateOne(
+ { principalId: ROLE },
+ { $set: { 'overrides.webSearch.safeSearch': 2 }, $inc: { configVersion: 1 } },
+ );
+ });
+
+ await expect(writes[0].write(null)).rejects.toMatchObject({ code: 57 });
+ expect(await readStored()).toMatchObject({
+ configVersion: 1,
+ overrides: { webSearch: { safeSearch: 2 } },
+ });
+ });
+
+ it('unsetConfigField removes a field only at the version the caller read', async () => {
+ const seeded = await seed();
+ const unset = (expectedVersion: number) =>
+ methods.unsetConfigField(
+ PrincipalType.ROLE,
+ ROLE,
+ 'webSearch.searxngInstanceUrl',
+ undefined,
+ { expectedVersion },
+ );
+
+ expect(await unset(seeded.configVersion + 1)).toBeNull();
+ expect(await readStored()).toMatchObject({
+ overrides: { webSearch: { searxngInstanceUrl: 'https://searx.example.com' } },
+ });
+
+ const result = await unset(seeded.configVersion);
+ expect(result!.configVersion).toBe(seeded.configVersion + 1);
+ expect(result!.overrides).toEqual({ webSearch: {} });
+ });
+
+ it('keeps upsertConfig retrying a duplicate insert when no precondition is given', async () => {
+ await seed();
+
+ const result = await methods.upsertConfig(
+ PrincipalType.ROLE,
+ ROLE,
+ PrincipalModel.ROLE,
+ { webSearch: { safeSearch: 1 } },
+ 10,
+ );
+
+ expect(result!.overrides).toEqual({ webSearch: { safeSearch: 1 } });
+ });
+});
diff --git a/packages/data-schemas/src/methods/config.ts b/packages/data-schemas/src/methods/config.ts
index fe8fc157fd..6e0c046fde 100644
--- a/packages/data-schemas/src/methods/config.ts
+++ b/packages/data-schemas/src/methods/config.ts
@@ -1,8 +1,8 @@
import { Types } from 'mongoose';
import { PrincipalType, PrincipalModel } from 'librechat-data-provider';
-import type { FilterQuery, Model, ClientSession } from 'mongoose';
+import type { FilterQuery, UpdateQuery, Model, ClientSession } from 'mongoose';
import type { TCustomConfig } from 'librechat-data-provider';
-import type { IConfig } from '~/types';
+import type { IConfig, ConfigWritePrecondition } from '~/types';
import { BASE_CONFIG_PRINCIPAL_ID } from '~/admin/capabilities';
import { escapeRegExp } from '~/utils/string';
@@ -19,6 +19,10 @@ function getPathAndDescendantsRegex(fieldPath: string): RegExp {
return new RegExp(`^${escapeRegExp(fieldPath)}(?:\\.|$)`);
}
+function isDuplicateKeyError(error: unknown): boolean {
+ return (error as { code?: number } | null)?.code === 11000;
+}
+
export function createConfigMethods(mongoose: typeof import('mongoose')): {
listAllConfigs: (filter?: { isActive?: boolean }, session?: ClientSession) => Promise<IConfig[]>;
findConfigByPrincipal: (
@@ -38,7 +42,7 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
overrides: Partial<TCustomConfig>,
priority: number,
session?: ClientSession,
- options?: { expectEmpty?: boolean; preservePriority?: boolean },
+ options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,
) => Promise<IConfig | null>;
patchConfigFields: (
principalType: PrincipalType,
@@ -47,6 +51,7 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
fields: Record<string, unknown>,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
tombstoneConfigField: (
principalType: PrincipalType,
@@ -55,12 +60,14 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
fieldPath: string,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
unsetConfigField: (
principalType: PrincipalType,
principalId: string | Types.ObjectId,
fieldPath: string,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
) => Promise<IConfig | null>;
deleteConfig: (
principalType: PrincipalType,
@@ -151,6 +158,88 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
.lean<IConfig[]>();
}
+ /**
+ * The filter a write with a version precondition applies to, or `null` when
+ * the precondition no longer holds. A caller that saw no document gets an
+ * empty one created first, at version 0, so its write cannot land on a
+ * document another writer created after the read.
+ */
+ async function getPreconditionFilter(
+ principalType: PrincipalType,
+ principalId: string | Types.ObjectId,
+ onInsert: { principalModel: PrincipalModel; priority: number },
+ expectedVersion: number | null,
+ session?: ClientSession,
+ ): Promise<FilterQuery<IConfig> | null> {
+ const filter = { principalType, principalId: principalId.toString() };
+ if (expectedVersion != null) {
+ return { ...filter, configVersion: expectedVersion };
+ }
+ const Config = mongoose.models.Config as Model<IConfig>;
+ const now = new Date();
+ try {
+ /** Timestamps are written on insert only, so a document that already exists is left untouched. */
+ const result = await Config.findOneAndUpdate(
+ filter,
+ { $setOnInsert: { ...onInsert, createdAt: now, updatedAt: now } },
+ {
+ upsert: true,
+ new: true,
+ timestamps: false,
+ setDefaultsOnInsert: true,
+ includeResultMetadata: true,
+ ...(session ? { session } : {}),
+ },
+ );
+ if (result.value == null || result.lastErrorObject?.updatedExisting === true) {
+ return null;
+ }
+ return { ...filter, configVersion: result.value.configVersion };
+ } catch (error) {
+ if (isDuplicateKeyError(error)) {
+ return null;
+ }
+ throw error;
+ }
+ }
+
+ /** Applies `update` only to the document version the caller read; `null` once it no longer matches. */
+ async function updateAtVersion(
+ principalType: PrincipalType,
+ principalId: string | Types.ObjectId,
+ onInsert: { principalModel: PrincipalModel; priority: number },
+ expectedVersion: number | null,
+ update: UpdateQuery<IConfig>,
+ session?: ClientSession,
+ ): Promise<IConfig | null> {
+ const filter = await getPreconditionFilter(
+ principalType,
+ principalId,
+ onInsert,
+ expectedVersion,
+ session,
+ );
+ if (filter == null) {
+ return null;
+ }
+ const Config = mongoose.models.Config as Model<IConfig>;
+ const sessionOption = session ? { session } : {};
+ try {
+ return await Config.findOneAndUpdate(filter, update, { new: true, ...sessionOption });
+ } catch (error) {
+ if (expectedVersion === null) {
+ /**
+ * Removes the empty document created above, so a write the database refused (such as a
+ * key name the engine cannot store) stores nothing. The filter carries the created
+ * version, so a document another write has since changed stays. A failure here
+ * replaces the refusal: the caller must not report that nothing was stored.
+ */
+ await Config.deleteOne(filter, sessionOption);
+ }
+ throw error;
+ }
+ }
+
async function upsertConfig(
principalType: PrincipalType,
principalId: string | Types.ObjectId,
@@ -158,20 +247,10 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
overrides: Partial<TCustomConfig>,
priority: number,
session?: ClientSession,
- options?: { expectEmpty?: boolean; preservePriority?: boolean },
+ options?: { expectEmpty?: boolean; preservePriority?: boolean } & ConfigWritePrecondition,
): Promise<IConfig | null> {
const Config = mongoose.models.Config as Model<IConfig>;
-
- const query: FilterQuery<IConfig> = {
- principalType,
- principalId: principalId.toString(),
- };
- if (options?.expectEmpty) {
- query.$and = [
- { $or: [{ overrides: { $eq: {} } }, { overrides: { $exists: false } }] },
- { $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },
- ];
- }
+ const expectedVersion = options?.expectedVersion;
const update = {
$set: {
@@ -184,6 +263,28 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
$inc: { configVersion: 1 },
};
+ if (expectedVersion !== undefined) {
+ return await updateAtVersion(
+ principalType,
+ principalId,
+ { principalModel, priority },
+ expectedVersion,
+ update,
+ session,
+ );
+ }
+
+ const query: FilterQuery<IConfig> = {
+ principalType,
+ principalId: principalId.toString(),
+ };
+ if (options?.expectEmpty) {
+ query.$and = [
+ { $or: [{ overrides: { $eq: {} } }, { overrides: { $exists: false } }] },
+ { $or: [{ tombstones: { $size: 0 } }, { tombstones: { $exists: false } }] },
+ ];
+ }
+
const mongoOptions = {
upsert: true,
new: true,
@@ -194,7 +295,7 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
try {
return await Config.findOneAndUpdate(query, update, mongoOptions);
} catch (err: unknown) {
- if ((err as { code?: number }).code === 11000) {
+ if (isDuplicateKeyError(err)) {
if (options?.expectEmpty) {
return null;
}
@@ -215,8 +316,10 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
fields: Record<string, unknown>,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
): Promise<IConfig | null> {
const Config = mongoose.models.Config as Model<IConfig>;
+ const expectedVersion = options?.expectedVersion;
const setPayload: { principalModel: PrincipalModel; priority: number; [key: string]: unknown } =
{
@@ -230,13 +333,6 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
const tombstonesToClear = [...new Set(Object.keys(fields).flatMap(getTombstonePathsToClear))];
- const options = {
- upsert: true,
- new: true,
- setDefaultsOnInsert: true,
- ...(session ? { session } : {}),
- };
-
const update: Record<string, unknown> = {
$set: setPayload,
$inc: { configVersion: 1 },
@@ -245,10 +341,21 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
update.$pull = { tombstones: { $in: tombstonesToClear } };
}
+ if (expectedVersion !== undefined) {
+ return await updateAtVersion(
+ principalType,
+ principalId,
+ { principalModel, priority },
+ expectedVersion,
+ update,
+ session,
+ );
+ }
+
return await Config.findOneAndUpdate(
{ principalType, principalId: principalId.toString() },
update,
- options,
+ { upsert: true, new: true, setDefaultsOnInsert: true, ...(session ? { session } : {}) },
);
}
@@ -259,28 +366,36 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
fieldPath: string,
priority: number,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
): Promise<IConfig | null> {
const Config = mongoose.models.Config as Model<IConfig>;
+ const expectedVersion = options?.expectedVersion;
- const options = {
- upsert: true,
- new: true,
- setDefaultsOnInsert: true,
- ...(session ? { session } : {}),
+ const update = {
+ $set: {
+ principalModel,
+ priority,
+ },
+ $unset: { [`overrides.${fieldPath}`]: '' },
+ $addToSet: { tombstones: fieldPath },
+ $inc: { configVersion: 1 },
};
+ if (expectedVersion !== undefined) {
+ return await updateAtVersion(
+ principalType,
+ principalId,
+ { principalModel, priority },
+ expectedVersion,
+ update,
+ session,
+ );
+ }
+
return await Config.findOneAndUpdate(
{ principalType, principalId: principalId.toString() },
- {
- $set: {
- principalModel,
- priority,
- },
- $unset: { [`overrides.${fieldPath}`]: '' },
- $addToSet: { tombstones: fieldPath },
- $inc: { configVersion: 1 },
- },
- options,
+ update,
+ { upsert: true, new: true, setDefaultsOnInsert: true, ...(session ? { session } : {}) },
);
}
@@ -289,22 +404,26 @@ export function createConfigMethods(mongoose: typeof import('mongoose')): {
principalId: string | Types.ObjectId,
fieldPath: string,
session?: ClientSession,
+ options?: ConfigWritePrecondition,
): Promise<IConfig | null> {
const Config = mongoose.models.Config as Model<IConfig>;
-
- const options = {
- new: true,
- ...(session ? { session } : {}),
- };
+ const expectedVersion = options?.expectedVersion;
+ if (expectedVersion === null) {
+ return null;
+ }
return await Config.findOneAndUpdate(
- { principalType, principalId: principalId.toString() },
+ {
+ principalType,
+ principalId: principalId.toString(),
+ ...(expectedVersion !== undefined ? { configVersion: expectedVersion } : {}),
+ },
{
$unset: { [`overrides.${fieldPath}`]: '' },
$pull: { tombstones: { $regex: getPathAndDescendantsRegex(fieldPath) } },
$inc: { configVersion: 1 },
},
- options,
+ { new: true, ...(session ? { session } : {}) },
);
}
diff --git a/packages/data-schemas/src/types/admin.ts b/packages/data-schemas/src/types/admin.ts
index 51fd3adc66..e565b1ac60 100644
--- a/packages/data-schemas/src/types/admin.ts
+++ b/packages/data-schemas/src/types/admin.ts
@@ -53,11 +53,19 @@ export type AdminConfigDeleteResponse = {
* - `sectionAllowlist`: writes to a top-level key `configSchema` does not define are rejected,
* and stored ones are ignored at merge.
* - `readFilteredWriteResponses`: write responses are filtered by the caller's read access.
+ * - `webSearchStoredKeys`: web search uses a key stored in config (encrypted by the admin API,
+ * or a `librechat.yaml` literal) at runtime, not only a `${VAR}` reference, and stores
+ * `webSearch.keenableApiKey` encrypted like the other web search keys. A stored key reaches a
+ * URL stored in config only when the same layer set both; it is kept over an inherited
+ * `${VAR}` or default URL. A later layer that changes, blanks or removes the paired URL drops
+ * the key, and a write that changes or removes the URL beside a stored key must enter the key
+ * again (400 `CONFIG_SECRET_REENTRY_REQUIRED`).
*/
export type AdminConfigFeatureFlag =
| 'dottedKeys'
| 'sectionAllowlist'
- | 'readFilteredWriteResponses';
+ | 'readFilteredWriteResponses'
+ | 'webSearchStoredKeys';
export type AdminConfigFeatures = Record<AdminConfigFeatureFlag, boolean>;
diff --git a/packages/data-schemas/src/types/config.ts b/packages/data-schemas/src/types/config.ts
index b980a70993..e4ccf2495a 100644
--- a/packages/data-schemas/src/types/config.ts
+++ b/packages/data-schemas/src/types/config.ts
@@ -32,6 +32,15 @@ export type Config = {
updatedAt?: Date;
};
+/**
+ * A write that applies only to the document the caller read: its
+ * `configVersion` then, or `null` when the principal had no document. A write
+ * whose precondition no longer holds changes nothing and resolves to `null`.
+ */
+export type ConfigWritePrecondition = {
+ expectedVersion?: number | null;
+};
+
export type IConfig = Config &
Document & {
_id: Types.ObjectId;