Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔑 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.jsindex 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.yamlindex 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 keydiff --git a/packages/api/src/admin/binding.ts b/packages/api/src/admin/binding.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 collectoverrides: {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 collectexpect(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.tsnew file mode 100644index 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.tsindex 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').isConfigSecretDescelet 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 functionjest.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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;