From a0b38c3196846671f66e7bc2b9fbd89e14d06e65 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 7 Sep 2026 04:50:22 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=90=20fix:=20Resolve=20Tool=20Grants?= =?UTF-8?q?=20Once=20Per=20Request=20and=20Pair=20Every=20Capability=20Gat?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four review rounds found thirteen issues, all one class: a boundary the permission check had not been copied into. Rounds 2 and 3 each found gaps created by the previous round's fix, and a manual sweep of tool constructors and upload routes still missed the `codeEnvAvailable` family entirely — because the thing worth enumerating is not "paths that reach a tool" but "reads of the capability". There are 28 such reads. This replaces per-site permission checks with one resolution per request, pairs every read that is a gate, and pins the list so a new one cannot be added silently. - `resolveToolRoleGrants` resolves `RUN_CODE` and `FILE_SEARCH` together and memoizes on the request. Both perf findings disappear by construction: gates share one role read instead of each issuing its own. - Newly paired gates: `codeEnvAvailable` in the OpenAI-compatible, Responses and memory-agent initializers (`initializeAgent` rebuilds `bash_tool`, `read_file` and the workspace file tools from it, and hands their handlers the code environment); the capability checks in agent upload processing and in agent-management upload purposes; and the library chat-completion service, behind an optional `getRoleByName` dependency so embedders are not broken. - The v1 Knowledge upload posts `assistant_id` with no `tool_resource`, so there is no resource to authorize. It now reads the assistant's own native tools and requires their grants, instead of treating a missing resource as unrestricted. - The startup role read moved off the critical path into the existing `Promise.all`, and the direct tool-call check passes `req` so the shared loader gate reuses its result rather than repeating the lookup. - `toolCapabilityGates.spec.js` pins every file that reads either capability with a count and a reason. A new read fails the suite until it is classified, so the next boundary announces itself instead of waiting for a reviewer. --- .../agents/__tests__/openai.spec.js | 2 + .../agents/__tests__/responses.unit.spec.js | 2 + api/server/controllers/agents/client.js | 12 +- api/server/controllers/agents/openai.js | 13 +- api/server/controllers/agents/responses.js | 13 +- api/server/controllers/tools.js | 4 + api/server/routes/agents/management.js | 7 +- .../services/Endpoints/agents/initialize.js | 36 +++--- api/server/services/Files/process.js | 28 ++++- .../__tests__/toolCapabilityGates.spec.js | 113 ++++++++++++++++++ packages/api/src/agents/openai/service.ts | 17 ++- .../api/src/tools/rolePermissions.spec.ts | 49 ++++++++ packages/api/src/tools/rolePermissions.ts | 68 +++++++++++ 13 files changed, 337 insertions(+), 27 deletions(-) create mode 100644 api/server/services/__tests__/toolCapabilityGates.spec.js diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js index 5a764ef7cc..494ed4e3b5 100644 --- a/api/server/controllers/agents/__tests__/openai.spec.js +++ b/api/server/controllers/agents/__tests__/openai.spec.js @@ -174,6 +174,8 @@ jest.mock('@librechat/agents', () => ({ jest.mock('@librechat/api', () => ({ createAgentExecutionContext: (context) => context, + /** Grants both by default; the capability set is what these specs vary. */ + resolveToolRoleGrants: jest.fn(async () => ({ runCode: true, fileSearch: true })), collectReachableAgents: (roots) => { const agents = []; const pending = [...roots]; diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js index 31421b3644..31d1eecbad 100644 --- a/api/server/controllers/agents/__tests__/responses.unit.spec.js +++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js @@ -197,6 +197,8 @@ jest.mock('@librechat/agents', () => ({ jest.mock('@librechat/api', () => ({ createAgentExecutionContext: (context) => context, + /** Grants both by default; the capability set is what these specs vary. */ + resolveToolRoleGrants: jest.fn(async () => ({ runCode: true, fileSearch: true })), SAFE_CONVERSATION_TITLE: 'New Chat', resolveConversationTitle: (...args) => mockResolveConversationTitle(...args), /** Pass-through: the controller strips UI-only activity-label parts diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index b9df554879..3c158f6506 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -148,6 +148,7 @@ const { resolveRunFadingTiers, createContextMetaPublisher, selectRunContextMetaToPublish, + resolveToolRoleGrants, } = require('@librechat/api'); const { Run, @@ -2870,6 +2871,14 @@ class AgentClient extends BaseClient { * tool registered unconditionally; without this passthrough the * memory path would silently lose code-execution tooling). */ const memoryCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities); + /** Same pairing as the chat initializers: the capability is the deployment + * switch, the grant is the role's. Request-memoized, so on the usual path + * this joins the lookup the tool loader already made. */ + const memoryToolGrants = await resolveToolRoleGrants({ + req: this.options.req, + getRoleByName: db.getRoleByName, + context: 'memoryAgent', + }); const agent = await initializeAgent( { req: this.options.req, @@ -2881,7 +2890,8 @@ class AgentClient extends BaseClient { ? EModelEndpoint.agents : memoryConfig.agent?.provider, }, - codeEnvAvailable: memoryCapabilities.has(AgentCapabilities.execute_code), + codeEnvAvailable: + memoryCapabilities.has(AgentCapabilities.execute_code) && memoryToolGrants.runCode, statefulSessionsAvailable: memoryCapabilities.has(AgentCapabilities.stateful_code_sessions), }, { diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js index 0706e42cdb..712e7a27a2 100644 --- a/api/server/controllers/agents/openai.js +++ b/api/server/controllers/agents/openai.js @@ -65,6 +65,7 @@ const { stripActivityLabelParts, executeAgentRun, waitForAgentExecutionWrites, + resolveToolRoleGrants, } = require('@librechat/api'); const { buildSummarizationHandlers, @@ -489,12 +490,20 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => { }; const enabledCapabilities = new Set(agentsEConfig?.capabilities); + /** Started before the memory read rather than awaited on its own line, so + * the role lookup overlaps that query instead of preceding it. */ + const toolRoleGrants = resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName }); const memoryAvailable = await resolveMemoryAvailability({ enabledCapabilities, memoryConfig: appConfig?.memory, user: req.user, getRoleByName: db.getRoleByName, }); + /** The deployment switch AND the role grant: `initializeAgent` rebuilds + * `bash_tool`, `read_file` and the workspace file tools from this flag, + * and forwards the code-environment context to their handlers. */ + const codeEnvAvailable = + enabledCapabilities.has(AgentCapabilities.execute_code) && (await toolRoleGrants).runCode; const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills); const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true; const accessibleSkillIds = skillsCapabilityEnabled @@ -559,7 +568,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => { skillsCapabilityEnabled, ephemeralSkillsToggle, }), - codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code), + codeEnvAvailable, backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background), toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents), statefulSessionsAvailable: enabledCapabilities.has( @@ -638,7 +647,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => { }), skillStates, defaultActiveOnShare, - codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code), + codeEnvAvailable, backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background), toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents), statefulSessionsAvailable: enabledCapabilities.has( diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js index 0056598338..48b405548b 100644 --- a/api/server/controllers/agents/responses.js +++ b/api/server/controllers/agents/responses.js @@ -80,6 +80,7 @@ const { CHILD_THREAD_READ_ONLY_ERROR, executeAgentRun, waitForAgentExecutionWrites, + resolveToolRoleGrants, } = require('@librechat/api'); const { createResponsesToolEndCallback, @@ -736,12 +737,20 @@ const executeResponse = async (envelope, { req, res }) => { }; const enabledCapabilities = new Set(agentsEConfig?.capabilities); + /** Started before the memory read rather than awaited on its own line, so + * the role lookup overlaps that query instead of preceding it. */ + const toolRoleGrants = resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName }); const memoryAvailable = await resolveMemoryAvailability({ enabledCapabilities, memoryConfig: appConfig?.memory, user: req.user, getRoleByName: db.getRoleByName, }); + /** The deployment switch AND the role grant: `initializeAgent` rebuilds + * `bash_tool`, `read_file` and the workspace file tools from this flag, + * and forwards the code-environment context to their handlers. */ + const codeEnvAvailable = + enabledCapabilities.has(AgentCapabilities.execute_code) && (await toolRoleGrants).runCode; const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills); const ephemeralSkillsToggle = request.ephemeralAgent?.skills === true; const accessibleSkillIds = skillsCapabilityEnabled @@ -806,7 +815,7 @@ const executeResponse = async (envelope, { req, res }) => { skillsCapabilityEnabled, ephemeralSkillsToggle, }), - codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code), + codeEnvAvailable, backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background), toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents), statefulSessionsAvailable: enabledCapabilities.has( @@ -885,7 +894,7 @@ const executeResponse = async (envelope, { req, res }) => { }), skillStates, defaultActiveOnShare, - codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code), + codeEnvAvailable, backgroundToolsAvailable: enabledCapabilities.has(AgentCapabilities.run_in_background), toolIntentsAvailable: enabledCapabilities.has(AgentCapabilities.tool_intents), statefulSessionsAvailable: enabledCapabilities.has( diff --git a/api/server/controllers/tools.js b/api/server/controllers/tools.js index c2298c5fb4..ac59da27e4 100644 --- a/api/server/controllers/tools.js +++ b/api/server/controllers/tools.js @@ -131,7 +131,11 @@ const callTool = async (req, res) => { logger.debug(`[${toolId}/call] User: ${req.user.id}`); let hasAccess = true; if (toolAccessPermType[toolId]) { + /** `req` is what puts this read in the request cache, so the shared + * `loadTools` gate below resolves the same grant for free instead of + * issuing a second serial role lookup before the sandbox call. */ hasAccess = await checkAccess({ + req, user: req.user, permissionType: toolAccessPermType[toolId], permissions: [Permissions.USE], diff --git a/api/server/routes/agents/management.js b/api/server/routes/agents/management.js index 1673c70b77..17be28ba25 100644 --- a/api/server/routes/agents/management.js +++ b/api/server/routes/agents/management.js @@ -19,6 +19,7 @@ const { ioredisClient, mapAgentManagementError, restoreTenantContextFromReq, + resolveToolRoleGrants, } = require('@librechat/api'); const { checkBan, configMiddleware, createFileLimiters } = require('~/server/middleware'); const { hasCapability } = require('~/server/middleware/roles/capabilities'); @@ -96,10 +97,12 @@ const fileHandlers = createAgentManagementFileHandlers({ return await checkCapability(req, AgentCapabilities.context); } if (purpose === EToolResources.execute_code) { - return await checkCapability(req, AgentCapabilities.execute_code); + const grants = await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName }); + return (await checkCapability(req, AgentCapabilities.execute_code)) && grants.runCode; } if (purpose === EToolResources.file_search) { - return await checkCapability(req, AgentCapabilities.file_search); + const grants = await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName }); + return (await checkCapability(req, AgentCapabilities.file_search)) && grants.fileSearch; } return true; }, diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js index 3db341aef0..3f29d28d30 100644 --- a/api/server/services/Endpoints/agents/initialize.js +++ b/api/server/services/Endpoints/agents/initialize.js @@ -25,7 +25,7 @@ const { buildSubagentThreadTaskConfig, backgroundCompletionWakeupsEnabled, createLazyAgentHistoryResolver, - checkToolRolePermission, + resolveToolRoleGrants, } = require('@librechat/api'); const { ResourceType, @@ -39,7 +39,6 @@ const { MAX_SUBAGENT_GRAPH_NODES, MAX_SUBAGENT_RUN_CONFIGS, isEphemeralAgentId, - PermissionTypes, resolveAllowedStatefulCodeEnvironments, } = require('librechat-data-provider'); const { @@ -228,21 +227,15 @@ const initializeClient = async ({ * allowlist with the toggle on = full accessible catalog. */ const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities); const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills); - /** Capability alone is not enough: `initializeAgent` rebuilds `bash_tool`, - * `read_file` and the workspace file tools from this flag, after the tool - * loader has already dropped `execute_code` for a denied role. Those handlers - * read and write the attached code environment, so the grant has to travel - * with the flag. Short-circuits before the role read when the deployment has - * the capability off. */ - const codeEnvAvailable = - enabledCapabilities.has(AgentCapabilities.execute_code) && - (await checkToolRolePermission({ - req, - user: req?.user, - permissionType: PermissionTypes.RUN_CODE, - getRoleByName: db.getRoleByName, - context: 'initializeClient', - })); + const codeCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.execute_code); + /** Started here but joined into the startup `Promise.all` below rather than + * awaited inline: `codeEnvAvailable` is not read until agent construction, so + * the role lookup overlaps the memory, skill and conversation queries instead + * of delaying them. Skipped entirely when the deployment has the capability + * off, since the flag is false either way. */ + const toolRoleGrantsPromise = codeCapabilityEnabled + ? resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName, context: 'initializeClient' }) + : null; const backgroundToolsAvailable = enabledCapabilities.has(AgentCapabilities.run_in_background); const toolIntentsAvailable = enabledCapabilities.has(AgentCapabilities.tool_intents); const deferredToolsAvailable = enabledCapabilities.has(AgentCapabilities.deferred_tools); @@ -525,6 +518,7 @@ const initializeClient = async ({ { skillStates, defaultActiveOnShare }, { primaryAgent, modelsConfig }, requestConversation, + toolRoleGrants, ] = await Promise.all([ memoryAvailablePromise, accessibleSkillIdsPromise, @@ -533,9 +527,17 @@ const initializeClient = async ({ skillStatesPromise, validatedPrimaryAgentPromise, requestConversationPromise, + toolRoleGrantsPromise, ]); delete endpointOption.agent; + /** The deployment switch AND the role grant. `initializeAgent` rebuilds + * `bash_tool`, `read_file` and the workspace file tools from this flag after + * the tool loader has already dropped `execute_code` for a denied role, and + * forwards the code-environment context to their handlers — so the grant has + * to travel with the flag, not just with the tool list. */ + const codeEnvAvailable = codeCapabilityEnabled && toolRoleGrants?.runCode === true; + const agentConfigs = new Map(); const allowedProviders = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.allowedProviders); diff --git a/api/server/services/Files/process.js b/api/server/services/Files/process.js index c4fac9bf63..9702fcc103 100644 --- a/api/server/services/Files/process.js +++ b/api/server/services/Files/process.js @@ -36,6 +36,8 @@ const { contentFilterBlockResponse, sweepExpiredFiles: sweepExpiredFilesWithDeps, startExpiredFileSweep: startExpiredFileSweepWithDeps, + resolveAssistantToolPermissions, + resolveToolRoleGrants, } = require('@librechat/api'); const { convertImage, @@ -606,6 +608,22 @@ const processFileUpload = async ({ req, res, metadata, sseStream }) => { }); if (isAssistantUpload && !metadata.message_file && !metadata.tool_resource) { + /** A v1 Knowledge upload posts `assistant_id` with no `tool_resource`, so + * there is no resource name to authorize against. The assistant's own + * native tools are what the file will feed, so read those and require the + * grant for each: otherwise a denied role attaches new inputs to an + * assistant that still carries `retrieval` or `code_interpreter`, without + * passing either writer's filter. */ + const assistant = await openai.beta.assistants.retrieve(metadata.assistant_id); + const isNativeToolPermitted = await resolveAssistantToolPermissions({ + req, + tools: assistant?.tools, + getRoleByName: db.getRoleByName, + }); + const deniedTool = (assistant?.tools ?? []).find((tool) => !isNativeToolPermitted(tool)); + if (deniedTool) { + throw new Error(`Forbidden: Insufficient permissions for ${deniedTool.type}`); + } await openai.beta.assistants.files.create(metadata.assistant_id, { file_id: id, }); @@ -702,7 +720,10 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => { const entity_id = messageAttachment === true ? undefined : agent_id; const basePath = mime.getType(file.originalname)?.startsWith('image') ? 'images' : 'uploads'; if (tool_resource === EToolResources.execute_code) { - const isCodeEnabled = await checkCapability(req, AgentCapabilities.execute_code); + const isCodeEnabled = + (await checkCapability(req, AgentCapabilities.execute_code)) && + (await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName, context: 'fileUpload' })) + .runCode; if (!isCodeEnabled) { throw new Error('Code execution is not enabled for Agents'); } @@ -746,7 +767,10 @@ const processAgentFileUpload = async ({ req, res, metadata, sseStream }) => { executionProfile: 'default', }); } else if (tool_resource === EToolResources.file_search) { - const isFileSearchEnabled = await checkCapability(req, AgentCapabilities.file_search); + const isFileSearchEnabled = + (await checkCapability(req, AgentCapabilities.file_search)) && + (await resolveToolRoleGrants({ req, getRoleByName: db.getRoleByName, context: 'fileUpload' })) + .fileSearch; if (!isFileSearchEnabled) { throw new Error('File search is not enabled for Agents'); } diff --git a/api/server/services/__tests__/toolCapabilityGates.spec.js b/api/server/services/__tests__/toolCapabilityGates.spec.js new file mode 100644 index 0000000000..ccad21b00f --- /dev/null +++ b/api/server/services/__tests__/toolCapabilityGates.spec.js @@ -0,0 +1,113 @@ +const fs = require('fs'); +const path = require('path'); + +/** + * `FILE_SEARCH` and `RUN_CODE` are enforced by pairing each read of the matching + * `AgentCapabilities` entry with the role grant from `resolveToolRoleGrants`. + * The capability is the deployment switch; the grant is the per-role half. A + * read that gets one without the other is a hole — which is how every gap in + * this area has been found: a boundary nobody knew existed. + * + * So the boundary list is pinned here. Adding a read of either capability fails + * this test until it is classified below, which is the point: the classification + * is the review, and it cannot be skipped by not knowing the site exists. + */ + +const REPO_ROOT = path.resolve(__dirname, '../../../..'); +const SEARCH_ROOTS = ['api/app', 'api/server', 'packages/api/src', 'packages/data-provider/src']; +const CAPABILITY_PATTERN = + /AgentCapabilities\.(execute_code|file_search)\b|EToolResources\.code_interpreter\b/; + +/** + * Every file holding at least one read, with the count and why each is sound. + * Counts rather than line numbers so ordinary edits above a gate don't churn it. + */ +const CLASSIFIED = { + // -- Gates: capability AND grant -------------------------------------------- + /** 7 gates + 2 map entries + 2 warning-list entries. */ + 'api/server/services/ToolService.js': 11, + /** `codeEnvAvailable`, paired after the startup batch. */ + 'api/server/services/Endpoints/agents/initialize.js': 1, + /** `codeEnvAvailable` for the OpenAI-compatible route. */ + 'api/server/controllers/agents/openai.js': 1, + /** `codeEnvAvailable` for the Responses route. */ + 'api/server/controllers/agents/responses.js': 1, + /** `codeEnvAvailable` for the memory-agent initializer. */ + 'api/server/controllers/agents/client.js': 1, + /** Upload processing: the code-environment and file-search branches. */ + 'api/server/services/Files/process.js': 2, + /** Agent-management upload purposes. */ + 'api/server/routes/agents/management.js': 2, + /** One gate, paired when the embedder wires `getRoleByName`; one in a comment. */ + 'packages/api/src/agents/openai/service.ts': 2, + + // -- Not gates --------------------------------------------------------------- + /** The upload-resource map entry, and one mention in a doc comment. */ + 'packages/api/src/tools/rolePermissions.ts': 2, + /** `recordCapabilityToolNames` bookkeeping — describes what was built, does + * not decide whether to build it. */ + 'packages/api/src/agents/initialize.ts': 2, + /** Default capability list shipped in config. */ + 'packages/data-provider/src/config.ts': 2, + /** Config normalization only: strips stale `tool_options` when the capability + * is off. Execution is gated by the loaders, so this needs no grant. */ + 'api/server/controllers/agents/v1.js': 1, +}; + +/** @returns {string[]} repo-relative files under `dir`, excluding tests. */ +function walk(dir) { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + return entries.flatMap((entry) => { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + return entry.name === 'node_modules' || entry.name === 'dist' ? [] : walk(full); + } + if (!/\.(js|ts)$/.test(entry.name) || /\.(test|spec)\.[jt]s$/.test(entry.name)) { + return []; + } + return [full]; + }); +} + +function collectReads() { + const found = {}; + for (const root of SEARCH_ROOTS) { + for (const file of walk(path.join(REPO_ROOT, root))) { + const matches = fs + .readFileSync(file, 'utf8') + .split('\n') + .filter((line) => CAPABILITY_PATTERN.test(line)); + if (matches.length > 0) { + found[path.relative(REPO_ROOT, file)] = matches.length; + } + } + } + return found; +} + +describe('FILE_SEARCH / RUN_CODE capability reads are all classified', () => { + const found = collectReads(); + + it('has no unclassified file reading a role-gated capability', () => { + const unclassified = Object.keys(found) + .filter((file) => CLASSIFIED[file] == null) + .sort(); + + expect({ + unclassified, + hint: 'A new read of AgentCapabilities.execute_code / file_search or EToolResources.code_interpreter. Pair it with resolveToolRoleGrants, then record it in CLASSIFIED with why it is sound.', + }).toEqual({ unclassified: [], hint: expect.any(String) }); + }); + + it('has no classified file whose read count drifted', () => { + const drifted = Object.entries(CLASSIFIED) + .filter(([file, expected]) => (found[file] ?? 0) !== expected) + .map(([file, expected]) => `${file}: expected ${expected}, found ${found[file] ?? 0}`) + .sort(); + + expect({ + drifted, + hint: 'A capability read was added or removed. If added, pair it with the grant before updating the count.', + }).toEqual({ drifted: [], hint: expect.any(String) }); + }); +}); diff --git a/packages/api/src/agents/openai/service.ts b/packages/api/src/agents/openai/service.ts index eb5e7ddad7..92243b040c 100644 --- a/packages/api/src/agents/openai/service.ts +++ b/packages/api/src/agents/openai/service.ts @@ -72,6 +72,7 @@ import { } from '~/middleware/modelBoundContent'; import { contentFilterBlockResponse, isContentFilterError } from '~/middleware/contentFilter'; import { contentFilterUninspectableResponse } from '~/protection/files'; +import { resolveToolRoleGrants } from '../../tools/rolePermissions'; import { createMCPRuntimeRequestBody } from '~/mcp/request'; import { getUserFacingProviderError } from '../errors'; import { collectReachableAgents } from '../traversal'; @@ -119,6 +120,12 @@ export interface ChatCompletionDependencies { * keep tenant tracing and code execution working. */ appConfig?: AppConfig; + /** + * Supply to have `codeEnvAvailable` respect the caller's `RUN_CODE` grant as + * well as the deployment capability. Optional so existing embedders keep + * their current behavior; without it this route is gated by capability alone. + */ + getRoleByName?: Parameters[0]['getRoleByName']; /** Tool execute options for event-driven tool execution */ toolExecuteOptions?: ToolExecuteOptions; } @@ -668,7 +675,15 @@ export async function createAgentChatCompletion( agentsConfig != null && typeof agentsConfig === 'object' ? ((agentsConfig as { capabilities?: string[] }).capabilities ?? []).includes(capability) : undefined; - const codeEnvAvailable = capabilityEnabled(AgentCapabilities.execute_code); + const capabilityAllowsCodeEnv = capabilityEnabled(AgentCapabilities.execute_code); + /** Paired with the role grant when the embedder wires `getRoleByName`; + * `initializeAgent` rebuilds `bash_tool`, `read_file` and the workspace + * file tools from this flag, so a denied role would otherwise keep the + * code environment's file handlers. */ + const codeEnvAvailable = + capabilityAllowsCodeEnv === true && deps.getRoleByName != null + ? (await resolveToolRoleGrants({ req, getRoleByName: deps.getRoleByName })).runCode + : capabilityAllowsCodeEnv; /** Mirror `codeEnvAvailable` for the stateful-session gate so this route * also carries each agent's trusted stateful endpoint/profile selection * into tool loading and prewarming. */ diff --git a/packages/api/src/tools/rolePermissions.spec.ts b/packages/api/src/tools/rolePermissions.spec.ts index b36a947ede..c4bb86384c 100644 --- a/packages/api/src/tools/rolePermissions.spec.ts +++ b/packages/api/src/tools/rolePermissions.spec.ts @@ -7,6 +7,7 @@ import { resolveToolRolePermissions, toolResourceRolePermissions, assistantToolRolePermissions, + resolveToolRoleGrants, resolveAssistantToolPermissions, checkToolResourceUploadPermission, } from './rolePermissions'; @@ -261,3 +262,51 @@ describe('resolveAssistantToolPermissions', () => { expect(permitted(undefined)).toBe(true); }); }); + +describe('resolveToolRoleGrants', () => { + it('reports both grants from one role read', async () => { + const getRoleByName = jest.fn().mockResolvedValue(buildRole()); + + await expect(resolveToolRoleGrants({ req: buildReq(), getRoleByName })).resolves.toEqual({ + runCode: true, + fileSearch: true, + }); + expect(getRoleByName).toHaveBeenCalledTimes(1); + }); + + it('reports each grant independently', async () => { + const getRoleByName = jest + .fn() + .mockResolvedValue(buildRole({ [PermissionTypes.RUN_CODE]: { [Permissions.USE]: false } })); + + await expect(resolveToolRoleGrants({ req: buildReq(), getRoleByName })).resolves.toEqual({ + runCode: false, + fileSearch: true, + }); + }); + + /** The whole point of centralizing: several gates on one request must not + * each pay their own role lookup. */ + it('memoizes on the request across repeat callers', async () => { + const getRoleByName = jest.fn().mockResolvedValue(buildRole()); + const req = buildReq(); + + const [first, second] = await Promise.all([ + resolveToolRoleGrants({ req, getRoleByName }), + resolveToolRoleGrants({ req, getRoleByName }), + ]); + await resolveToolRoleGrants({ req, getRoleByName }); + + expect(first).toBe(second); + expect(getRoleByName).toHaveBeenCalledTimes(1); + }); + + it('fails both grants closed when the role lookup throws', async () => { + const getRoleByName = jest.fn().mockRejectedValue(new Error('unreachable')); + + await expect(resolveToolRoleGrants({ req: buildReq(), getRoleByName })).resolves.toEqual({ + runCode: false, + fileSearch: false, + }); + }); +}); diff --git a/packages/api/src/tools/rolePermissions.ts b/packages/api/src/tools/rolePermissions.ts index 2d859c9c00..388a879e0d 100644 --- a/packages/api/src/tools/rolePermissions.ts +++ b/packages/api/src/tools/rolePermissions.ts @@ -224,3 +224,71 @@ export async function resolveAssistantToolPermissions({ return type == null || !denied.has(type); }; } + +/** Memoizes the resolved grants for the lifetime of one request. */ +const toolRoleGrantsKey = Symbol.for('librechat.toolRoleGrants'); + +export interface ToolRoleGrants { + /** `RUN_CODE.USE` — the sandbox, its file tools, and PTC. */ + runCode: boolean; + /** `FILE_SEARCH.USE` — the search tool and its uploads. */ + fileSearch: boolean; +} + +export interface ResolveToolRoleGrantsParams { + req?: ServerRequest; + getRoleByName: CheckAccessParams['getRoleByName']; + context?: string; +} + +/** + * Resolves both tool grants for a request, once. + * + * Every gate on `AgentCapabilities.execute_code` / `file_search` reads its role + * half from here, so a boundary is authorized by pairing the capability with a + * field of this object rather than by repeating a permission check. The two + * lookups run together and the result is memoized on the request, so a startup + * that consults several gates — the tool loader, the agent initializer, an + * upload handler — pays one role read between them. + * + * Callers that want the read off their critical path can start it early without + * awaiting; the memoized promise is what later callers join. + * + * Fails closed: a missing user or a check that throws denies both. + */ +export function resolveToolRoleGrants({ + req, + getRoleByName, + context = 'toolRoleGrants', +}: ResolveToolRoleGrantsParams): Promise { + const cache = req as + | (ServerRequest & { [toolRoleGrantsKey]?: Promise }) + | undefined; + const memoized = cache?.[toolRoleGrantsKey]; + if (memoized) { + return memoized; + } + + const pending = Promise.all([ + checkToolRolePermission({ + req, + user: req?.user as CheckAccessParams['user'], + permissionType: PermissionTypes.RUN_CODE, + getRoleByName, + context, + }), + checkToolRolePermission({ + req, + user: req?.user as CheckAccessParams['user'], + permissionType: PermissionTypes.FILE_SEARCH, + getRoleByName, + context, + }), + ]).then(([runCode, fileSearch]) => ({ runCode, fileSearch })); + + if (cache) { + Object.defineProperty(cache, toolRoleGrantsKey, { value: pending, enumerable: false }); + } + + return pending; +}