🔦 fix: Skip Unselected Tool Schemas Under Legacy PII (#18158)

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-11-14 12:20:16 -05:00 • committed by GitHub
parent e7669c147b
commit f2b4a58b0e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 375 additions and 15 deletions

View file

@ -217,6 +217,40 @@ describe('AgentClient retained answers', () => {
getMessages.mockResolvedValue([]);
});
it.each([false, true])(
'builds a first-turn prompt under legacy PII with a large catalog (deferred: %s)',
async (deferred) => {
const client = makeClient();
client.options.req.config.messageFilter = {
pii: { starterPatterns: ['sk_prefix', 'bearer_header', 'api_key_header'] },
};
client.options.agent.toolDefinitions = Array.from({ length: 1_000 }, (_, index) => ({
name: `mcp_tool_${index}`,
defer_loading: deferred,
parameters: {
type: 'object',
properties: {
value: { type: 'string', description: 'A safe value', enum: ['one', 'two'] },
},
},
}));
const firstMessage = {
...latestUserMessage(),
messageId: 'u1',
parentMessageId: null,
text: 'Hello',
};
await expect(client.buildMessages([firstMessage], null, {})).resolves.toEqual(
expect.objectContaining({ prompt: expect.any(Array) }),
);
client.options.req.config.filters = { toolArguments: { pii: { fields: ['arguments'] } } };
await expect(client.buildMessages([firstMessage], null, {})).rejects.toMatchObject({
code: 'content_filter_uninspectable',
});
},
);
it('completes the branch the history read cut at the summary and quotes the answer in the user turn', async () => {
const client = makeClient();
client.user = 'user-123';

View file

@ -22,6 +22,27 @@ const filters: FiltersConfig = {
},
};
const makeLargeToolCatalog = (deferred = false, length = 1_000) =>
Array.from({ length }, (_, index) => ({
name: `mcp_tool_${index}`,
description: `Tool ${index}`,
defer_loading: deferred,
parameters: {
type: 'object',
properties: Object.fromEntries(
Array.from({ length: 4 }, (_, field) => [
`field_${field}`,
{ type: 'string', enum: ['one', 'two', 'three'], description: 'A value' },
]),
),
},
}));
const legacyPii = {
starterPatterns: [],
customPatterns: [{ id: 'private', label: 'private value', regex: 'PRIVATE-[A-Z]+' }],
};
const makeTraversalOverflowContent = () => [
{
type: 'custom',
@ -2151,6 +2172,186 @@ describe('assertModelBoundContent', () => {
).toThrow('Submitted content contains a private value');
});
it.each([false, true])(
'allows a new conversation with a large legacy-only tool catalog (deferred: %s)',
(deferred) => {
const toolDefinitions = makeLargeToolCatalog(deferred);
expect(() =>
assertModelBoundContent({
legacyPii: { starterPatterns: ['sk_prefix', 'bearer_header', 'api_key_header'] },
submittedMessages: [{ role: 'user', content: 'Hello' }],
agents: [{ name: 'Large Catalog Agent', instructions: 'Be helpful.', toolDefinitions }],
}),
).not.toThrow();
},
);
it('does not apply legacy blocking to an exhausted tool-definition array', () => {
expect(() =>
assertModelBoundContent({
legacyPii,
agents: [{ toolDefinitions: makeLargeToolCatalog(false, 4_200) }],
}),
).not.toThrow();
});
it.each([false, true])(
'keeps large schema catalogs fail-closed under new argument policy (legacy: %s)',
(legacy) => {
expect(() =>
assertModelBoundContent({
legacyPii: legacy ? legacyPii : undefined,
filters: { toolArguments: { pii: { ...legacyPii, fields: ['arguments'] } } },
agents: [{ toolDefinitions: makeLargeToolCatalog(true) }],
}),
).toThrow('Submitted content could not be completely inspected before processing.');
},
);
it.each(['name', 'description'] as const)(
'inspects later tool %s without spending its budget on unselected schemas',
(field) => {
const toolDefinitions = makeLargeToolCatalog();
toolDefinitions[999][field] = 'PRIVATE-LATE';
expect(() =>
assertModelBoundContent({
legacyPii,
filters: { agentInstructions: { pii: { ...legacyPii, fields: [field] } } },
agents: [{ toolDefinitions }],
}),
).toThrow('Submitted content contains a private value');
},
);
it('does not let argument schemas consume a tool-name-only inspection budget', () => {
const toolDefinitions = makeLargeToolCatalog();
toolDefinitions[999].name = 'PRIVATE-NAME';
expect(() =>
assertModelBoundContent({
legacyPii,
filters: { toolArguments: { pii: { ...legacyPii, fields: ['name'] } } },
agents: [{ toolDefinitions }],
}),
).toThrow('Submitted content contains a private value');
});
it('keeps selected catalog metadata fail-closed at the array bound', () => {
expect(() =>
assertModelBoundContent({
legacyPii,
filters: { agentInstructions: { pii: { ...legacyPii, fields: ['description'] } } },
agents: [{ toolDefinitions: makeLargeToolCatalog(false, 4_200) }],
}),
).toThrow('Submitted content could not be completely inspected before processing.');
});
it('keeps model parameters protected after unselected schemas', () => {
expect(() =>
assertModelBoundContent({
legacyPii,
filters: { modelParameters: { pii: { ...legacyPii, fields: ['stop'] } } },
agents: [{ toolDefinitions: makeLargeToolCatalog(), stop: ['PRIVATE-STOP'] }],
}),
).toThrow('Submitted content contains a private value');
});
it.each(['submitted', 'stored'] as const)(
'keeps legacy %s message PII protected with large catalogs',
(source) => {
expect(() =>
assertModelBoundContent({
legacyPii,
...(source === 'submitted'
? { submittedMessages: [{ role: 'user', content: 'PRIVATE-MESSAGE' }] }
: {
storedMessages: [{ role: 'user', isCreatedByUser: true, text: 'PRIVATE-MESSAGE' }],
}),
agents: [{ toolDefinitions: makeLargeToolCatalog() }],
}),
).toThrow('Submitted content contains a private value');
},
);
it.each([
['depth', () => makeDeepModelParameter()],
['nodes', () => Array.from({ length: 4_200 }, () => 'safe')],
[
'accessor',
() =>
Object.defineProperty({}, 'value', {
enumerable: true,
get() {
throw new Error('blocked');
},
}),
],
[
'reflection',
() =>
new Proxy(
{},
{
ownKeys() {
throw new Error('blocked');
},
},
),
],
] as const)(
'preserves the selected schema %s boundary without legacy-only schema inspection',
(_label, makeParameters) => {
const agent = { toolDefinitions: [{ name: 'tool', parameters: makeParameters() }] };
expect(() => assertModelBoundContent({ legacyPii, agents: [agent] })).not.toThrow();
expect(() =>
assertModelBoundContent({
legacyPii,
filters: { toolArguments: { pii: { ...legacyPii, fields: ['arguments'] } } },
agents: [agent],
}),
).toThrow('Submitted content could not be completely inspected before processing.');
},
);
it('never reads a schema accessor under legacy-only policy', () => {
const readParameters = jest.fn(() => {
throw new Error('unselected schema');
});
const tool = Object.defineProperty({ name: 'tool' }, 'parameters', { get: readParameters });
expect(() =>
assertModelBoundContent({ legacyPii, agents: [{ toolDefinitions: [tool] }] }),
).not.toThrow();
expect(readParameters).not.toHaveBeenCalled();
});
it('still audits selected schemas alongside legacy protection', () => {
const infoSpy = jest.spyOn(logger, 'info').mockImplementation(() => logger);
try {
expect(() =>
assertModelBoundContent({
legacyPii,
filters: {
toolArguments: { pii: { ...legacyPii, fields: ['arguments'], action: 'audit' } },
},
agents: [
{
toolDefinitions: [
{ name: 'tool', parameters: { description: 'PRIVATE-SCHEMA' } },
...makeLargeToolCatalog(),
],
},
],
}),
).not.toThrow();
expect(infoSpy).toHaveBeenCalledWith(
expect.stringContaining('"ruleId":"private"'),
expect.objectContaining({ source: 'tool_argument', action: 'audit' }),
);
} finally {
infoSpy.mockRestore();
}
});
it('blocks initialized action schemas before they become model-bound', () => {
expect(() =>
assertModelBoundContent({

View file

@ -3884,14 +3884,14 @@ function inspectModelBoundContent(
messageCount: input.storedMessages?.length ?? 0,
}),
);
appendExtractedContent(() => extractAgentContent(agent));
appendExtractedContent(() => extractAgentContent(agent, inspector?.shouldInspect));
}
for (const assistant of input.assistants ?? []) {
assertInspectableFileInput(input.filters, assistant);
appendExtractedContent(() => extractAssistantContent(assistant));
appendExtractedContent(() => extractAssistantContent(assistant, inspector?.shouldInspect));
}
for (const action of input.actions ?? []) {
appendExtractedContent(() => extractAssistantActionContent(action));
appendExtractedContent(() => extractAssistantActionContent(action, inspector?.shouldInspect));
}
for (const skill of input.skills ?? []) {
appendExtractedContent(() => extractSkillContent(skill));

View file

@ -50,6 +50,36 @@ describe('visitNestedStrings', () => {
});
describe('isContentTraversalProtected', () => {
it('excludes catalog traversal only from legacy protection, not selected new policies', () => {
const error = new ContentTraversalLimitError(
[],
[{ source: 'tool_argument', fields: ['arguments'], legacyPii: false }],
);
const legacyPii = { starterPatterns: ['sk_prefix'] };
expect(isContentTraversalProtected({ error, legacyPii })).toBe(false);
expect(
isContentTraversalProtected({
error,
legacyPii,
filters: {
toolArguments: { pii: { fields: ['arguments'], starterPatterns: ['sk_prefix'] } },
},
}),
).toBe(true);
expect(
isContentTraversalProtected({
error: new ContentTraversalLimitError(
[],
[
{ source: 'tool_argument', fields: ['arguments'], legacyPii: false },
{ source: 'message', fields: ['content_part'] },
],
),
legacyPii,
}),
).toBe(true);
});
it.each([
{
source: 'prompt' as const,

View file

@ -106,6 +106,8 @@ export interface UninspectableNestedContentResponse {
export type ContentTraversalScope = {
[Source in ContentSource]: {
readonly source: Source;
/** False when this scope cannot contain a legacy-inspected fragment. */
readonly legacyPii?: false;
readonly fields: readonly ContentFieldMap[Source][];
};
}[ContentSource];
@ -355,10 +357,11 @@ export function isContentTraversalProtected(params: {
hasActivePatterns(params.legacyPii) &&
scopes.some(
(scope) =>
scope.source === 'message' ||
scope.source === 'assembled_context' ||
(scope.source === 'tool_argument' &&
(scope.fields.includes('arguments') || scope.fields.includes('output'))),
scope.legacyPii !== false &&
(scope.source === 'message' ||
scope.source === 'assembled_context' ||
(scope.source === 'tool_argument' &&
(scope.fields.includes('arguments') || scope.fields.includes('output')))),
)
) {
return true;

View file

@ -540,7 +540,7 @@ describe('submitted content adapters', () => {
}),
);
expect(getContentTraversalScopes(parameterError)).toEqual([
{ source: 'tool_argument', fields: ['arguments'] },
{ source: 'tool_argument', fields: ['arguments'], legacyPii: false },
]);
expect(getContentTraversalFragments(parameterError)).toEqual(
expect.arrayContaining([

View file

@ -668,6 +668,7 @@ function appendAgentDefinitionContent(
export function extractAgentContent(
input: AgentContentInput | null | undefined,
shouldInspect?: (fragment: TextContentFragment) => boolean,
): readonly TextContentFragment[] {
const fragments: TextContentFragment[] = [];
const traversalErrors: ContentTraversalLimitError[] = [];
@ -679,6 +680,7 @@ export function extractAgentContent(
'/toolDefinitions',
traversalErrors,
traversalBudget,
shouldInspect,
);
collectTraversalAwareContent(fragments, traversalErrors, () =>
extractModelParameterContent(input),
@ -692,6 +694,7 @@ function extractFunctionToolContent(
tool: FunctionToolContentInput | null | undefined,
path: JsonPointer,
traversalBudget: VisitNestedStringsBudget,
shouldInspect?: (fragment: TextContentFragment) => boolean,
): void {
const definition = tool?.function ?? tool;
if (definition == null) {
@ -718,6 +721,21 @@ function extractFunctionToolContent(
field: 'description',
});
const parameterId = `function-tool.parameters.${fragments.length}`;
if (
shouldInspect?.(
fragment(
parameterId,
`${definitionPath}/parameters` as JsonPointer,
'',
'tool_argument',
'arguments',
'json',
'inspect_only',
),
) === false
) {
return;
}
fragments.push(
...extractSubmittedValueContent(
definition.parameters,
@ -733,7 +751,7 @@ function extractFunctionToolContent(
'inspect_only',
),
],
[{ source: 'tool_argument', fields: ['arguments'] }],
[{ source: 'tool_argument', fields: ['arguments'], legacyPii: false }],
traversalBudget,
),
);
@ -761,6 +779,7 @@ function appendFunctionToolsContent(
path: JsonPointer,
traversalErrors: ContentTraversalLimitError[],
traversalBudget: VisitNestedStringsBudget,
shouldInspect?: (fragment: TextContentFragment) => boolean,
): void {
const complete = visitBoundedSubmittedArray<string | FunctionToolContentInput>(
tools,
@ -775,6 +794,7 @@ function appendFunctionToolsContent(
tool,
`${path}/${index}` as JsonPointer,
traversalBudget,
shouldInspect,
);
} catch (error) {
if (!(error instanceof ContentTraversalLimitError)) {
@ -789,7 +809,7 @@ function appendFunctionToolsContent(
traversalErrors.push(
new ContentTraversalLimitError(fragments, [
{ source: 'agent_instruction', fields: ['name', 'description'] },
{ source: 'tool_argument', fields: ['name', 'arguments'] },
{ source: 'tool_argument', fields: ['name', 'arguments'], legacyPii: false },
]),
);
}
@ -810,6 +830,7 @@ function throwCollectedTraversalErrors(
export function extractAssistantContent(
input: AssistantContentInput | null | undefined,
shouldInspect?: (fragment: TextContentFragment) => boolean,
): readonly TextContentFragment[] {
const fragments: TextContentFragment[] = [];
const traversalErrors: ContentTraversalLimitError[] = [];
@ -821,8 +842,16 @@ export function extractAssistantContent(
'/toolDefinitions',
traversalErrors,
traversalBudget,
shouldInspect,
);
appendFunctionToolsContent(
fragments,
input?.tools,
'/tools',
traversalErrors,
traversalBudget,
shouldInspect,
);
appendFunctionToolsContent(fragments, input?.tools, '/tools', traversalErrors, traversalBudget);
collectTraversalAwareContent(fragments, traversalErrors, () =>
extractModelParameterContent(input),
);
@ -832,6 +861,7 @@ export function extractAssistantContent(
export function extractAssistantActionContent(
input: AssistantActionContentInput | null | undefined,
shouldInspect?: (fragment: TextContentFragment) => boolean,
): readonly TextContentFragment[] {
const fragments: TextContentFragment[] = [];
const traversalErrors: ContentTraversalLimitError[] = [];
@ -842,6 +872,7 @@ export function extractAssistantActionContent(
'/functions',
traversalErrors,
traversalBudget,
shouldInspect,
);
collectTraversalAwareContent(fragments, traversalErrors, () =>
extractSubmittedValueContent(

View file

@ -9,6 +9,7 @@ import {
inspectContentWithTraversal,
} from './runtime';
import { ContentTraversalLimitError } from './adapters/nested';
import { extractChatContent } from './adapters/chat';
jest.mock('@librechat/data-schemas', () => ({
logger: { warn: jest.fn(), error: jest.fn(), info: jest.fn(), debug: jest.fn() },
@ -49,6 +50,55 @@ describe('configured content inspection', () => {
expect(inspectContent([fragment('message', 'text')], {})).toBeNull();
});
it('selects schema traversal from compiled rules rather than legacy source overlap', () => {
const schema = { ...fragment('tool_argument', 'arguments'), id: 'function-tool.parameters.0' };
const decision = { ...schema, id: 'chat.decision.0.arguments' };
const legacyPii = { starterPatterns: [], customPatterns: [BLOCK_PATTERN] };
const legacy = createConfiguredContentInspector({ legacyPii });
expect(legacy?.shouldInspect(schema)).toBe(false);
expect(legacy?.shouldInspect(decision)).toBe(true);
expect(
createConfiguredContentInspector({
legacyPii,
filters: { toolArguments: { pii: { ...legacyPii, fields: ['name'] } } },
})?.shouldInspect(schema),
).toBe(false);
expect(
createConfiguredContentInspector({
legacyPii,
filters: {
toolArguments: { pii: { ...legacyPii, fields: ['arguments'], action: 'audit' } },
},
})?.shouldInspect(schema),
).toBe(true);
expect(
createConfiguredContentInspector({
legacyPii,
filters: { toolArguments: { pii: { starterPatterns: [] } } },
})?.shouldInspect(schema),
).toBe(false);
});
it.each([
{ arguments: { value: 'ORG-SECRET' }, finding: true },
{ arguments: Array.from({ length: 4_200 }, () => 'safe'), finding: false },
])(
'preserves legacy user-edited argument inspection and traversal limits %#',
({ arguments: editedArguments, finding }) => {
const result = inspectContentWithTraversal(
() => extractChatContent({ decisions: [{ editedArguments }] }),
{ legacyPii: { starterPatterns: [], customPatterns: [BLOCK_PATTERN] } },
);
if (finding) {
expect(result.finding).toMatchObject({ source: 'tool_argument', field: 'arguments' });
expect(result.traversalError).toBeNull();
} else {
expect(result.finding).toBeNull();
expect(result.traversalError).toBeInstanceOf(ContentTraversalLimitError);
}
},
);
it('blocks a partial fragment before returning its traversal failure', () => {
const filters: FiltersConfig = {
skills: {

View file

@ -48,6 +48,8 @@ export interface ContentInspectionConfig {
export interface ConfiguredContentInspector {
readonly hasAuditRules: boolean;
/** Selects extraction work using the same compiled rules as inspection. */
shouldInspect(fragment: TextContentFragment): boolean;
createSession(): ConfiguredContentInspectionSession;
inspect(fragments: Iterable<TextContentFragment>): ProtectionFinding | null;
}
@ -303,6 +305,12 @@ function compilePlans(plans: readonly FilterCompilationPlan[]): readonly Compile
return compiled;
}
function selectsFragment(rule: CompiledFilter, fragment: TextContentFragment): boolean {
return (
(rule.fields == null || rule.fields.has(fragment.field)) && rule.applies?.(fragment) !== false
);
}
function createInspector(rules: readonly CompiledFilter[]): ConfiguredContentInspector {
const hasAuditRules = rules.some((rule) => rule.action === 'audit');
const rulesBySource = new Map<ContentSource, Array<readonly [number, CompiledFilter]>>();
@ -328,10 +336,7 @@ function createInspector(rules: readonly CompiledFilter[]): ConfiguredContentIns
}
let firstBlockingFinding: ProtectionFinding | null = null;
for (const [ruleIndex, rule] of sourceRules) {
if (rule.fields != null && !rule.fields.has(fragment.field)) {
continue;
}
if (rule.applies?.(fragment) === false) {
if (!selectsFragment(rule, fragment)) {
continue;
}
const inspectedText = (inspectedTextByRule[ruleIndex] ??= new Set<string>());
@ -396,6 +401,12 @@ function createInspector(rules: readonly CompiledFilter[]): ConfiguredContentIns
return {
hasAuditRules,
shouldInspect(fragment) {
return (
rulesBySource.get(fragment.source)?.some(([, rule]) => selectsFragment(rule, fragment)) ===
true
);
},
createSession,
inspect(fragments) {
return inspect(fragments, new Array(rules.length));