🔐 fix: Resolve Tool Grants Once Per Request and Pair Every Capability Gate

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.
This commit is contained in:
Claude 2026-09-07 04:50:22 +00:00
parent 4b8c86af4e
commit a0b38c3196
No known key found for this signature in database
13 changed files with 337 additions and 27 deletions

View file

@ -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];

View file

@ -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

View file

@ -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),
},
{

View file

@ -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(

View file

@ -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(

View file

@ -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],

View file

@ -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;
},

View file

@ -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);

View file

@ -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');
}

View file

@ -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) });
});
});

View file

@ -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<typeof resolveToolRoleGrants>[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. */

View file

@ -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,
});
});
});

View file

@ -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<ToolRoleGrants> {
const cache = req as
| (ServerRequest & { [toolRoleGrantsKey]?: Promise<ToolRoleGrants> })
| 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;
}