diff --git a/e2e/specs/mock/scenarios/native-search-warning.spec.ts b/e2e/specs/mock/scenarios/native-search-warning.spec.ts new file mode 100644 index 0000000000..98119246c8 --- /dev/null +++ b/e2e/specs/mock/scenarios/native-search-warning.spec.ts @@ -0,0 +1,80 @@ +import { expect, test } from '@playwright/test'; +import { logger } from '@librechat/data-schemas'; +import { Permissions, PermissionTypes } from 'librechat-data-provider'; +import type { IRole, AppConfig } from '@librechat/data-schemas'; +import { updateInterfacePermissions } from '../../../../packages/api/src/app/permissions'; + +/** + * Startup runs `updateInterfacePermissions` once against the stored USER and ADMIN roles. + * It is called here in-process with stubbed role reads and writes, so no shared role + * document of this run is changed while other specs are using it. + */ + +const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } }; +const plainSpec = { name: 'plain', label: 'Plain', preset: {} }; + +async function startupWarnings({ + webSearch, + list = [nativeSpec], + storedUse, +}: { + webSearch?: boolean; + list?: unknown[]; + storedUse?: boolean; +}): Promise { + const config = { interface: webSearch === undefined ? {} : { webSearch } }; + const appConfig = { + config, + interfaceConfig: { webSearch }, + modelSpecs: { list }, + } as unknown as AppConfig; + const getRoleByName = async (name: string) => + storedUse === undefined + ? null + : ({ + name, + permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: storedUse } }, + } as unknown as IRole); + + const messages: string[] = []; + const original = logger.warn; + logger.warn = ((message: unknown) => { + messages.push(String(message)); + return logger; + }) as typeof logger.warn; + try { + await updateInterfacePermissions({ + appConfig, + getRoleByName, + updateAccessPermissions: async () => undefined, + }); + } finally { + logger.warn = original; + } + return messages.filter((message) => message.includes('provider-native web search')); +} + +test.describe('native web search startup warning', () => { + test('an operator who sets interface.webSearch false is told which native search specs it blocks @scenario:explicit-websearch-false-warns-native-search-specs', async () => { + const warnings = await startupWarnings({ webSearch: false }); + expect(warnings).toHaveLength(1); + expect(warnings[0]).toContain('`interface.webSearch: false` denies'); + expect(warnings[0]).toContain('gpt-native'); + expect(warnings[0]).toContain('endpoints.agents.capabilities'); + expect(warnings[0]).toContain('UPGRADING.md'); + }); + + test('an operator who removed interface.webSearch is told the stored role still blocks native search @scenario:stored-websearch-denial-warns-when-key-unset', async () => { + const warnings = await startupWarnings({ storedUse: false }); + expect(warnings).toHaveLength(1); + expect(warnings[0]).toContain('stored role permission keeps denying'); + expect(warnings[0]).toContain('gpt-native'); + }); + + test('startup stays silent when web search is allowed or no spec requests native search @scenario:allowed-websearch-or-no-native-specs-stays-silent', async () => { + expect(await startupWarnings({ webSearch: true })).toHaveLength(0); + expect(await startupWarnings({})).toHaveLength(0); + expect(await startupWarnings({ webSearch: true, storedUse: false })).toHaveLength(0); + expect(await startupWarnings({ webSearch: false, list: [plainSpec] })).toHaveLength(0); + }); +}); diff --git a/packages/api/src/app/permissions.spec.ts b/packages/api/src/app/permissions.spec.ts index 36743d4a5d..a67e96d1d1 100644 --- a/packages/api/src/app/permissions.spec.ts +++ b/packages/api/src/app/permissions.spec.ts @@ -1,4 +1,4 @@ -import { loadDefaultInterface } from '@librechat/data-schemas'; +import { logger, loadDefaultInterface } from '@librechat/data-schemas'; import { SystemRoles, Permissions, @@ -3062,3 +3062,69 @@ describe('updateInterfacePermissions - web search recovery', () => { expect(grants()).toEqual([false, false]); }); }); + +describe('updateInterfacePermissions - native web search warning', () => { + const nativeSpec = { name: 'gpt-native', label: 'GPT', preset: { web_search: true } }; + + const run = async (webSearch: boolean | undefined, list: unknown[] = [nativeSpec]) => { + const config = { interface: webSearch === undefined ? {} : { webSearch } }; + const configDefaults = { interface: {} } as TConfigDefaults; + const interfaceConfig = await loadDefaultInterface({ config, configDefaults }); + const appConfig = { config, interfaceConfig, modelSpecs: { list } } as unknown as AppConfig; + await updateInterfacePermissions({ + appConfig, + getRoleByName: mockGetRoleByName, + updateAccessPermissions: mockUpdateAccessPermissions, + }); + }; + + const nativeWarnings = () => + warnSpy.mock.calls.filter(([message]) => + String(message).includes('provider-native web search'), + ); + + let warnSpy: jest.SpyInstance; + + beforeEach(() => { + jest.clearAllMocks(); + mockGetRoleByName.mockResolvedValue(null); + warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => logger); + }); + + afterEach(() => { + warnSpy.mockRestore(); + }); + + it('warns when interface.webSearch: false blocks model specs that request native search', async () => { + await run(false); + const warnings = nativeWarnings(); + expect(warnings).toHaveLength(1); + expect(warnings[0][0]).toContain('`interface.webSearch: false` denies'); + expect(warnings[0][0]).toContain('gpt-native'); + expect(warnings[0][0]).toContain('endpoints.agents.capabilities'); + }); + + it('warns when the key is unset but a stored role still denies WEB_SEARCH', async () => { + mockGetRoleByName.mockImplementation(async (roleName: string) => ({ + name: roleName, + permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } }, + })); + await run(undefined); + const warnings = nativeWarnings(); + expect(warnings).toHaveLength(1); + expect(warnings[0][0]).toContain('stored role permission keeps denying'); + expect(warnings[0][0]).toContain(SystemRoles.USER); + }); + + it('does not warn when web search is allowed or no spec requests native search', async () => { + await run(true); + await run(undefined); + await run(false, [{ name: 'plain', label: 'Plain', preset: {} }]); + mockGetRoleByName.mockImplementation(async (roleName: string) => ({ + name: roleName, + permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: false } }, + })); + await run(true); + expect(nativeWarnings()).toHaveLength(0); + }); +}); diff --git a/packages/api/src/app/permissions.ts b/packages/api/src/app/permissions.ts index c4ea6ed610..9a5960a8e7 100644 --- a/packages/api/src/app/permissions.ts +++ b/packages/api/src/app/permissions.ts @@ -67,6 +67,35 @@ function hasExplicitConfig( } } +/** + * `WEB_SEARCH.USE` gates provider-native search (the `web_search` model parameter) as well as + * LibreChat's `web_search` tool. Warns when model specs ask for native search that a role's + * effective permission blocks, whether `interface.webSearch: false` sets it or a stored role keeps it. + */ +function warnNativeWebSearchDenied( + appConfig: AppConfig, + deniedRoles: string[], + isExplicitlyConfigured: boolean, +): void { + if (deniedRoles.length === 0) { + return; + } + const specs = (appConfig.modelSpecs?.list ?? []) + .filter((spec) => spec.preset?.web_search === true) + .map((spec) => spec.name); + if (specs.length === 0) { + return; + } + const source = isExplicitlyConfigured + ? '`interface.webSearch: false` denies' + : '`interface.webSearch` is not set, and the stored role permission keeps denying'; + logger.warn( + `Model specs request provider-native web search (\`preset.web_search: true\`), but ${source} the \`WEB_SEARCH\` permission for roles ${deniedRoles.join(', ')}, which also blocks native search: ${specs.join(', ')}. ` + + "To offer native search without LibreChat's search tool, set `interface.webSearch: true` and remove `web_search` from `endpoints.agents.capabilities`. " + + 'Removing `interface.webSearch` alone keeps the stored role permission; set it explicitly or update the role in the admin settings. See "Native-only web search" in UPGRADING.md.', + ); +} + export async function updateInterfacePermissions({ appConfig, getRoleByName, @@ -124,6 +153,7 @@ export async function updateInterfacePermissions({ }; const defaults = getConfigDefaults().interface; + const webSearchDeniedRoles: string[] = []; // Permission precedence order: // 1. Explicit user configuration (from librechat.yaml) @@ -767,9 +797,22 @@ export async function updateInterfacePermissions({ } } + const webSearchUse = + permissionsToUpdate[PermissionTypes.WEB_SEARCH]?.[Permissions.USE] ?? + existingPermissions?.[PermissionTypes.WEB_SEARCH]?.[Permissions.USE]; + if (webSearchUse === false) { + webSearchDeniedRoles.push(roleName); + } + // Update permissions if any need updating if (Object.keys(permissionsToUpdate).length > 0) { await updateAccessPermissions(roleName, permissionsToUpdate, existingRole); } } + + warnNativeWebSearchDenied( + appConfig, + webSearchDeniedRoles, + hasExplicitConfig(interfaceConfig, PermissionTypes.WEB_SEARCH), + ); }