theorum 0.1.15 → 1.1.3

package/esm/src/guardrails/tool-directives.js

@@ -0,0 +1,124 @@
+/**
+ * Directive detection for tool ingress.
+ *
+ * Tool results carry a different threat than user text. The jailbreak phrasings in
+ * `injection.ts` name the thing they attack — "ignore previous instructions",
+ * "reveal your system prompt" — and real indirect injection rarely does. It reads
+ * like a status update or a helpful next step, and pattern-matching for the word
+ * "instructions" misses all of it.
+ *
+ * What is anomalous in *data* is content that behaves like an instruction: naming
+ * a tool the agent can call, issuing an imperative at the agent, or claiming an
+ * authority the content does not have.
+ *
+ * A signal only counts when it co-occurs with a concrete external destination —
+ * an address or URL. Directive language alone is far too common in legitimate
+ * output to act on. These signals raise the turn's taint rather than rewriting the text. A page
+ * documenting an email API legitimately says "call send_email"; redacting that
+ * would corrupt content the model needs. Being wrong here should cost a refused
+ * write — recoverable and visible — not silently damaged input.
+ *
+ * @module
+ */
+import { normalizeForDetection } from './normalize.js';
+/** Rule ids emitted by tool-ingress directive detection. */
+export const DIRECTIVE_RULES = {
+    toolName: 'tool_result.names-callable-tool',
+    imperative: 'tool_result.imperative',
+    authority: 'tool_result.authority-claim',
+};
+/**
+ * Imperatives aimed at an agent rather than a reader.
+ *
+ * Bounded quantifiers throughout: tool results can be large, and an unbounded
+ * scanner on attacker-controlled bytes is a denial-of-service surface.
+ */
+const IMPERATIVES = [
+    /\b(?:next|final|remaining)\s+steps?\s*[:—-]/gi,
+    /\byou\s+(?:must|should|need\s+to|are\s+required\s+to)\s+(?:now\s+)?\w{2,20}/gi,
+    /\bto\s+(?:complete|finish|fulfil|fulfill)\s+(?:this|the)\s+\w{2,20}/gi,
+    /\b(?:call|invoke|run|execute)\s+(?:the\s+)?[\w.-]{2,40}\s+(?:tool|function)\b/gi,
+    /\b(?:send|forward|email|transfer|upload|post)\s+(?:the\s+|all\s+|your\s+)?[\w\s]{2,40}\s+to\s+\S{3,80}/gi,
+    /\b(?:delete|remove|drop|purge)\s+(?:the\s+|all\s+)?[\w\s]{2,40}\b/gi,
+];
+/**
+ * A concrete external destination — the thing exfiltration needs and ordinary
+ * process prose almost never carries.
+ *
+ * This is the discriminator. Directive language on its own is everywhere in
+ * legitimate tool output: documentation says "you must be an admin", support
+ * articles say "to remove a user", status reports say "the user has approved".
+ * Measured on a benign sample, directive signals alone produced false positives
+ * on most of it. Pairing a signal with a destination removed all of them.
+ */
+const EXFIL_TARGET = /\b[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,4}\b|\bhttps?:\/\/\S{4,120}/i;
+/** Claims of permission or provenance the content cannot actually hold. */
+const AUTHORITY = [
+    /\b(?:the\s+)?user\s+has\s+(?:already\s+)?(?:approved|authorised|authorized|confirmed|requested)\b/gi,
+    /\b(?:system|admin|operator)\s+(?:note|notice|message|override|instruction)s?\s*[:—-]/gi,
+    /\bon\s+behalf\s+of\s+the\s+(?:user|operator|admin)\b/gi,
+    /\bthis\s+(?:is|was)\s+(?:pre-?)?(?:approved|authorised|authorized)\b/gi,
+];
+function matches(patterns, text) {
+    return patterns.some((pattern) => {
+        pattern.lastIndex = 0;
+        return pattern.test(text);
+    });
+}
+/** Word-boundary match for a tool name, escaped so registry names cannot inject. */
+function mentionsTool(text, tool) {
+    if (tool.length < 3) {
+        return false;
+    }
+    const escaped = tool.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?:^|[^\\w-])${escaped}(?:$|[^\\w-])`, 'i').test(text);
+}
+/**
+ * Detect instruction-shaped content in a tool result.
+ *
+ * `callableTools` is the set the model can actually invoke this turn. A result
+ * naming one is the highest-precision signal available — ordinary data has no
+ * reason to name the agent's tools, and no generic content filter can check it
+ * because it requires the turn's registry.
+ */
+function directiveHits(text, callableTools = []) {
+    if (!text || !EXFIL_TARGET.test(text)) {
+        // No destination, no exfiltration. Action-shaped attacks that carry no target
+        // are left to the taint gate, which does not depend on reading the content.
+        return [];
+    }
+    const normalized = normalizeForDetection(text);
+    const hits = [];
+    // One hit per named tool — several names is a stronger signal than one.
+    for (const _tool of callableTools.filter((tool) => mentionsTool(normalized, tool))) {
+        hits.push({ rule: DIRECTIVE_RULES.toolName, severity: 'high' });
+    }
+    if (matches(IMPERATIVES, normalized)) {
+        hits.push({ rule: DIRECTIVE_RULES.imperative, severity: 'medium' });
+    }
+    if (matches(AUTHORITY, normalized)) {
+        hits.push({ rule: DIRECTIVE_RULES.authority, severity: 'medium' });
+    }
+    return hits;
+}
+/** True when a result looked like it was trying to steer the agent. */
+function looksDirective(hits) {
+    return hits.length > 0;
+}
+/**
+ * Strength of the signals, read off the hits rather than invented.
+ *
+ * Naming a tool the model can call is the sharpest signal available, so it alone
+ * reaches `high`; so does agreement between two different signal kinds.
+ */
+function advisoryLevel(hits) {
+    if (hits.length === 0) {
+        return 'none';
+    }
+    const kinds = new Set(hits.map((hit) => hit.rule));
+    if (kinds.has(DIRECTIVE_RULES.toolName) || kinds.size > 1) {
+        return 'high';
+    }
+    return 'elevated';
+}
+export { advisoryLevel, directiveHits, looksDirective };

package/esm/src/guardrails/tool-result.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Tool boundary guardrails — the surface where untrusted bytes re-enter the
+ * model's context carrying the model's own authority.
+ *
+ * A tool result is not user text: the model asked for it, so it arrives looking
+ * like something the turn already trusts. Remote HTTP and MCP servers control
+ * their own response bodies (including their error strings), and a delegated
+ * agent answers in prose that reads as authoritative. Everything crossing this
+ * boundary is therefore fenced, detected, and labelled with where it came from.
+ *
+ * @module
+ */
+import type { AdvisoryLevel, GuardrailEvent, GuardrailHit, Provenance, ResolvedGuardrailPolicy, ToolOrigin, TurnTaint, Verdict } from './types.js';
+declare const TOOL_CLOSE = "</tool_data>";
+/** True when a result's bytes came from outside the host's own code. */
+declare function isRemoteOrigin(origin: ToolOrigin): boolean;
+/**
+ * Wrap tool output so the model reads it as data and can see where it came from.
+ *
+ * The origin is on the tag rather than in prose so a result cannot claim a
+ * friendlier provenance than it has by writing one into its own body.
+ */
+declare function wrapToolData(text: string, provenance: Provenance, advisory?: AdvisoryLevel, guidance?: string): string;
+export interface GuardedToolText {
+    /** Text to hand the model, fenced and redacted. */
+    text: string;
+    /** Emitted when the guard did anything worth recording. */
+    event?: GuardrailEvent;
+    /**
+     * Directive signals found in the content.
+     *
+     * Reported, never redacted: legitimate tool output is frequently
+     * instruction-shaped, so rewriting on this signal would corrupt real data.
+     * These raise the turn's taint instead.
+     */
+    suspicious?: GuardrailHit[];
+}
+/**
+ * Compose the model-facing text for a tool result.
+ *
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+declare function composeToolText(finding: string, data: unknown): string;
+/**
+ * Guard one tool result on its way into the model's context.
+ *
+ * Local host tools are still detected — a host tool reading a database returns
+ * data the host did not write — but only remote origins are fenced, because
+ * fencing a local tool's output would change prompts hosts have already tuned.
+ */
+declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, callableTools?: readonly string[]): GuardedToolText;
+/**
+ * Guard a tool failure message.
+ *
+ * A remote server authors its own error strings, so an unguarded failure message
+ * is the cleanest injection path across this boundary: it reaches the model
+ * verbatim and is framed by the kernel as a system report.
+ */
+declare function guardToolFailureText(message: string, provenance: Provenance, policy: ResolvedGuardrailPolicy): GuardedToolText;
+/**
+ * Inspect model-supplied tool arguments before the call runs.
+ *
+ * Arguments are model-authored, so the risk is not instruction smuggling but
+ * exfiltration: a credential lifted from context and posted outward as a
+ * parameter. Detection reports rather than rewrites — silently altering a tool
+ * argument would make the call succeed against something the model did not ask
+ * for.
+ */
+declare function inspectToolArguments(args: unknown, policy: ResolvedGuardrailPolicy): Verdict;
+/** Guardrail event for a flagged tool call, for the runner to emit. */
+declare function toolCallEvent(verdict: Verdict, provenance: Provenance): GuardrailEvent | undefined;
+/**
+ * Record a tool result against the turn's taint.
+ *
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+declare function recordTaint(taint: TurnTaint | undefined, provenance: Provenance, suspicious?: GuardrailHit[]): TurnTaint;
+/** True when the turn has already read attacker-influenceable content. */
+declare function isTainted(taint: TurnTaint | undefined): boolean;
+/** True when remote content this turn read looked like it was steering the agent. */
+declare function isSuspicious(taint: TurnTaint | undefined): boolean;
+/**
+ * Decide whether a tool call may proceed given what the turn has already read.
+ *
+ * A `flag` says the call is happening on a tainted turn and is worth recording; a
+ * `block` says the profile asked for it to be refused. Reporting happens whether
+ * or not enforcement is configured, so the risk is visible before a host opts in.
+ */
+declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy): Verdict;
+export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };

package/esm/src/guardrails/tool-result.js

@@ -0,0 +1,276 @@
+/**
+ * Tool boundary guardrails — the surface where untrusted bytes re-enter the
+ * model's context carrying the model's own authority.
+ *
+ * A tool result is not user text: the model asked for it, so it arrives looking
+ * like something the turn already trusts. Remote HTTP and MCP servers control
+ * their own response bodies (including their error strings), and a delegated
+ * agent answers in prose that reads as authoritative. Everything crossing this
+ * boundary is therefore fenced, detected, and labelled with where it came from.
+ *
+ * @module
+ */
+import { lexiconText } from './lexicon.js';
+import { detectionForTrust } from './policy.js';
+import { sanitizeText } from './sanitize.js';
+import { textForScan } from './serialize.js';
+import { advisoryLevel, directiveHits } from './tool-directives.js';
+const TOOL_CLOSE = '</tool_data>';
+const TOOL_OPEN = '<tool_data';
+/** Origins whose bytes the host does not author and cannot vouch for. */
+const REMOTE_ORIGINS = new Set(['http', 'mcp', 'delegated']);
+/** True when a result's bytes came from outside the host's own code. */
+function isRemoteOrigin(origin) {
+    return REMOTE_ORIGINS.has(origin);
+}
+/**
+ * Strip fence markers a tool result tried to forge before wrapping it.
+ * Linear scan — avoids polynomial regex on forged `<tool_data…>` runs.
+ */
+function stripToolFences(text) {
+    const lower = text.toLowerCase();
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const openAt = lower.indexOf(TOOL_OPEN, i);
+        const closeAt = lower.indexOf(TOOL_CLOSE, i);
+        let next = -1;
+        let kind = null;
+        if (openAt >= 0 && (closeAt < 0 || openAt <= closeAt)) {
+            next = openAt;
+            kind = 'open';
+        }
+        else if (closeAt >= 0) {
+            next = closeAt;
+            kind = 'close';
+        }
+        if (next < 0 || kind === null) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, next);
+        if (kind === 'close') {
+            i = next + TOOL_CLOSE.length;
+            continue;
+        }
+        const gt = text.indexOf('>', next + TOOL_OPEN.length);
+        if (gt < 0) {
+            out += text.slice(next);
+            break;
+        }
+        i = gt + 1;
+    }
+    return out;
+}
+/**
+ * Wrap tool output so the model reads it as data and can see where it came from.
+ *
+ * The origin is on the tag rather than in prose so a result cannot claim a
+ * friendlier provenance than it has by writing one into its own body.
+ */
+function wrapToolData(text, provenance, advisory = 'none', guidance) {
+    const attrs = `tool="${provenance.tool}" origin="${provenance.origin}"` +
+        (advisory === 'none' ? '' : ` advisory="${advisory}"`);
+    const notice = advisory === 'none' ? '' : `${advisoryNotice(advisory)}${guidance ? ` ${guidance}` : ''}\n`;
+    return `<${'tool_data'} ${attrs}>\n${notice}${stripToolFences(text)}\n${TOOL_CLOSE}`;
+}
+/**
+ * The kernel's own statement of what it observed.
+ *
+ * Deliberately an observation, not an instruction: what the agent should do about
+ * it is product behaviour, supplied by the host as `advisoryGuidance`. Emitted
+ * only when signals fired, so it stays rare enough to carry weight — a warning on
+ * every fetch is one the model learns to skip.
+ */
+function advisoryNotice(advisory) {
+    return lexiconText(advisory === 'high' ? 'advisory.notice_high' : 'advisory.notice_elevated');
+}
+/**
+ * Compose the model-facing text for a tool result.
+ *
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+function composeToolText(finding, data) {
+    if (data === undefined) {
+        return finding;
+    }
+    const rendered = textForScan(data);
+    if (rendered.unscannable) {
+        return finding;
+    }
+    return `${finding}\n${rendered.text}`;
+}
+/**
+ * Guard one tool result on its way into the model's context.
+ *
+ * Local host tools are still detected — a host tool reading a database returns
+ * data the host did not write — but only remote origins are fenced, because
+ * fencing a local tool's output would change prompts hosts have already tuned.
+ */
+function guardToolResult(finding, data, provenance, policy, callableTools = []) {
+    const composed = composeToolText(finding, data);
+    const options = detectionForTrust(policy, 'untrusted');
+    const redacted = sanitizeText(composed, options);
+    const changed = redacted !== composed;
+    // Directive detection runs on remote content only: a local tool's output is
+    // bytes the host's own code produced.
+    const remote = isRemoteOrigin(provenance.origin);
+    const suspicious = remote ? directiveHits(composed, callableTools) : [];
+    const advisory = advisoryLevel(suspicious);
+    const fenced = remote
+        ? wrapToolData(redacted, provenance, advisory, policy.taint?.advisoryGuidance)
+        : redacted;
+    const hits = [
+        ...(changed ? [{ rule: 'tool_result.redacted', severity: 'medium' }] : []),
+        ...suspicious,
+    ];
+    if (hits.length === 0) {
+        return { text: fenced };
+    }
+    return {
+        text: fenced,
+        ...(suspicious.length > 0 ? { suspicious } : {}),
+        event: {
+            stage: 'tool_result',
+            trust: 'untrusted',
+            // Redaction changed the text; directive signals only annotate it.
+            action: changed ? 'redact' : 'flag',
+            hits,
+            provenance,
+        },
+    };
+}
+/**
+ * Guard a tool failure message.
+ *
+ * A remote server authors its own error strings, so an unguarded failure message
+ * is the cleanest injection path across this boundary: it reaches the model
+ * verbatim and is framed by the kernel as a system report.
+ */
+function guardToolFailureText(message, provenance, policy) {
+    const options = detectionForTrust(policy, 'untrusted');
+    const redacted = sanitizeText(stripToolFences(message), options);
+    if (redacted === message) {
+        return { text: redacted };
+    }
+    return {
+        text: redacted,
+        event: {
+            stage: 'tool_result',
+            trust: 'untrusted',
+            action: 'redact',
+            hits: [{ rule: 'tool_failure.redacted', severity: 'medium' }],
+            provenance,
+        },
+    };
+}
+/**
+ * Inspect model-supplied tool arguments before the call runs.
+ *
+ * Arguments are model-authored, so the risk is not instruction smuggling but
+ * exfiltration: a credential lifted from context and posted outward as a
+ * parameter. Detection reports rather than rewrites — silently altering a tool
+ * argument would make the call succeed against something the model did not ask
+ * for.
+ */
+function inspectToolArguments(args, policy) {
+    if (!policy.redactSensitive) {
+        return { action: 'allow' };
+    }
+    const rendered = textForScan(args);
+    if (rendered.unscannable) {
+        return { action: 'allow' };
+    }
+    const options = { sanitizeInput: false, redactSensitive: true };
+    if (sanitizeText(rendered.text, options) === rendered.text) {
+        return { action: 'allow' };
+    }
+    return {
+        action: 'flag',
+        hits: [{ rule: 'tool_call.sensitive-argument', severity: 'high' }],
+    };
+}
+/** Guardrail event for a flagged tool call, for the runner to emit. */
+function toolCallEvent(verdict, provenance) {
+    if (verdict.action === 'allow') {
+        return undefined;
+    }
+    return {
+        stage: 'tool_call',
+        trust: 'untrusted',
+        action: verdict.action,
+        hits: verdict.hits,
+        provenance,
+    };
+}
+/**
+ * Record a tool result against the turn's taint.
+ *
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+function recordTaint(taint, provenance, suspicious = []) {
+    const sources = taint?.sources ?? [];
+    const prior = taint?.suspicious ?? [];
+    if (!isRemoteOrigin(provenance.origin)) {
+        return { sources, suspicious: prior };
+    }
+    return { sources: [...sources, provenance], suspicious: [...prior, ...suspicious] };
+}
+/** True when the turn has already read attacker-influenceable content. */
+function isTainted(taint) {
+    return (taint?.sources.length ?? 0) > 0;
+}
+/** True when remote content this turn read looked like it was steering the agent. */
+function isSuspicious(taint) {
+    return (taint?.suspicious.length ?? 0) > 0;
+}
+/** Capability rank, so a single threshold can express "this and anything worse". */
+const CAPABILITY_RANK = {
+    'read-only': 0,
+    'read-write': 1,
+    destructive: 2,
+};
+const GATE_RANK = {
+    off: Number.POSITIVE_INFINITY,
+    destructive: 2,
+    write: 1,
+};
+/**
+ * Decide whether a tool call may proceed given what the turn has already read.
+ *
+ * A `flag` says the call is happening on a tainted turn and is worth recording; a
+ * `block` says the profile asked for it to be refused. Reporting happens whether
+ * or not enforcement is configured, so the risk is visible before a host opts in.
+ */
+function checkTaintGate(taint, access, policy) {
+    if (!isTainted(taint)) {
+        return { action: 'allow' };
+    }
+    const rank = CAPABILITY_RANK[access] ?? 0;
+    if (rank === 0) {
+        return { action: 'allow' };
+    }
+    const suspicious = isSuspicious(taint);
+    const hits = [
+        {
+            rule: suspicious ? 'tool_call.steered-turn' : 'tool_call.tainted-turn',
+            severity: 'high',
+        },
+    ];
+    // Gated on origin alone. Whether the content looked directive changes the rule
+    // reported, never whether the call is refused.
+    if (rank < GATE_RANK[policy.taint?.afterRemoteRead ?? 'off']) {
+        return { action: 'flag', hits };
+    }
+    const read = taint?.sources.map((s) => s.tool).join(', ') ?? '';
+    const reason = lexiconText(suspicious ? 'taint.reason_steered' : 'taint.reason_tainted');
+    return {
+        action: 'block',
+        hits,
+        rejection: lexiconText('taint.blocked', { access, sources: read, reason }),
+    };
+}
+export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };