theorum 0.1.15 → 1.1.3

package/esm/src/guardrails/sanitize.js

@@ -1,60 +1,60 @@
 /**
  * Request sanitization utilities for THEORUM.
  *
- * Sanitization removes inbound prompt-injection spans and sensitive-data spans
- * according to the active profile guardrail flags. The host remains responsible
- * for domain policy.
- *
  * @module
  */
-import { mapStrings } from '../kernel/engine/tree.js';
 import { sanitizeTurnBlobsForProfile } from '../kernel/registry/attachments.js';
 import { getProfile } from '../kernel/registry/profiles.js';
 import { applySpans } from '../observability/spans.js';
+import { guardrailFromHits } from './events.js';
+import { hitFromSpan } from './hits.js';
 import { injectionSpans } from './injection.js';
+import { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
 import { sensitiveSpans } from './sensitive.js';
-/** Sanitize one text value using prompt-injection and sensitive-data detectors. */
-function sanitizeText(text, options) {
+/**
+ * Detect and redact injection / sensitive spans. Returns hits for observability
+ * (rule + offsets + optional `match` preview for debugging).
+ */
+function detectText(text, options) {
     const sanitizeInput = options?.sanitizeInput ?? true;
     const redactSensitive = options?.redactSensitive ?? true;
     if (!sanitizeInput && !redactSensitive) {
-        return text;
+        return { text, hits: [] };
     }
     const spans = [
         ...(sanitizeInput ? injectionSpans(text) : []),
         ...(redactSensitive ? sensitiveSpans(text) : []),
     ];
-    return applySpans(text, spans);
+    const hits = spans.map((span) => hitFromSpan(text, span, span.kind === 'injection' ? 'sanitize.injection' : 'sanitize.sensitive', 'high'));
+    return { text: applySpans(text, spans), hits };
 }
-/** Redact only sensitive data (credentials, PII) — skip injection patterns.
- *  Use for model output text that never contained user-authored injection attempts. */
+/** Sanitize one text value using prompt-injection and sensitive-data detectors. */
+function sanitizeText(text, options) {
+    return detectText(text, options).text;
+}
+/** Redact only sensitive data (credentials, PII) — skip injection patterns. */
 function redactSensitiveOnly(text) {
-    const spans = sensitiveSpans(text);
-    if (spans.length === 0)
-        return text;
-    return applySpans(text, spans);
+    return detectText(text, { sanitizeInput: false, redactSensitive: true }).text;
+}
+function appendHits(into, hits) {
+    for (const hit of hits) {
+        into.push(hit);
+    }
 }
-function sanitizeSlots(slots, options) {
+function sanitizeSlots(slots, options, hits) {
     if (!slots) {
         return slots;
     }
     const out = {};
     for (const [key, value] of Object.entries(slots)) {
-        out[key] = sanitizeText(value, options);
+        const detected = detectText(value, options);
+        appendHits(hits, detected.hits);
+        out[key] = detected.text;
     }
     return out;
 }
-function sanitizeArgs(args, options) {
-    const next = mapStrings(args, (t) => sanitizeText(t, options));
-    if (next && typeof next === 'object' && !Array.isArray(next)) {
-        return next;
-    }
-    return args;
-}
-/** Maximum retained length for trace-safe host project ids. */
 const PROJECT_ID_MAX = 128;
 const PROJECT_ID_OK = /^[A-Za-z0-9._-]+$/;
-/** Return a trace-safe project id or `undefined` when the input is unsafe. */
 function sanitizeProjectId(id) {
     if (!id) {
         return undefined;
@@ -65,95 +65,178 @@ function sanitizeProjectId(id) {
     }
     return trimmed;
 }
-function sanitizeRepair(repair, options) {
+function sanitizeRepair(repair, options, hits) {
     if (!repair) {
         return repair;
     }
+    const previous = detectText(repair.previousOutput, options);
+    const rejection = detectText(repair.rejection, options);
+    appendHits(hits, previous.hits);
+    appendHits(hits, rejection.hits);
+    let guidance = repair.guidance;
+    if (guidance) {
+        const detected = detectText(guidance, options);
+        appendHits(hits, detected.hits);
+        guidance = detected.text;
+    }
     return {
-        previousOutput: sanitizeText(repair.previousOutput, options),
-        rejection: sanitizeText(repair.rejection, options),
-        guidance: repair.guidance ? sanitizeText(repair.guidance, options) : undefined,
+        previousOutput: previous.text,
+        rejection: rejection.text,
+        ...(guidance ? { guidance } : {}),
     };
 }
-function sanitizeHistory(history, options) {
-    if (!history) {
-        return history;
-    }
-    return history.map((m) => ({
-        role: m.role,
-        ...(m.content !== undefined ? { content: sanitizeText(m.content, options) } : {}),
-        ...(m.parts
-            ? {
-                parts: m.parts.map((p) => p.type === 'text' ? { ...p, text: sanitizeText(p.text, options) } : p),
-            }
-            : {}),
-        ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
-        ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
-        ...(m.name ? { name: m.name } : {}),
-        ...(m.metadata ? { metadata: m.metadata } : {}),
-    }));
+/**
+ * Sanitize the text of each history message; tool calls, ids, and metadata pass
+ * through untouched.
+ *
+ * Exported because every path that injects messages into a turn needs it — turn
+ * history, and host steer injects mid-turn. A second copy would drift.
+ */
+function sanitizeHistory(history, options, hits = []) {
+    return history.map((m) => {
+        let content = m.content;
+        if (content !== undefined) {
+            const detected = detectText(content, options);
+            appendHits(hits, detected.hits);
+            content = detected.text;
+        }
+        let parts = m.parts;
+        if (parts) {
+            parts = parts.map((p) => {
+                if (p.type !== 'text') {
+                    return p;
+                }
+                const detected = detectText(p.text, options);
+                appendHits(hits, detected.hits);
+                return { ...p, text: detected.text };
+            });
+        }
+        return {
+            role: m.role,
+            ...(content !== undefined ? { content } : {}),
+            ...(parts ? { parts } : {}),
+            ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
+            ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
+            ...(m.name ? { name: m.name } : {}),
+            ...(m.metadata ? { metadata: m.metadata } : {}),
+        };
+    });
 }
-function sanitizeDynamicTool(decl, options) {
-    const clean = { ...decl };
-    if (clean.description !== undefined) {
-        clean.description = sanitizeText(clean.description, options);
+/**
+ * Detection switches for one profile at one trust level.
+ *
+ * Falls back to full detection when the profile is not registered yet, so an
+ * unknown id never silently disables guardrails.
+ */
+function detectionForProfile(profileId, trust) {
+    let spec;
+    try {
+        spec = getProfile(profileId)?.guardrails;
     }
-    if (clean.parameters !== undefined) {
-        clean.parameters = sanitizeArgs(clean.parameters, options);
+    catch {
+        // If profile not registered yet, default to full guardrails.
     }
-    return clean;
+    return detectionForTrust(resolveGuardrailPolicy(spec), trust);
 }
-/** Sanitize description and parameter schema text in dynamic tool declarations. */
-function sanitizeDynamicTools(tools, options) {
-    if (!tools || tools.length === 0) {
-        return tools;
+function pushStageEvent(events, stage, trust, hits) {
+    const event = guardrailFromHits(stage, trust, hits, 'redact');
+    if (event) {
+        events.push(event);
     }
-    return tools.map((decl) => sanitizeDynamicTool(decl, options));
 }
-/** Sanitize all user-controlled text and blobs in a turn request. */
-function sanitizeTurnRequest(req) {
-    let profileGuardrails;
-    try {
-        profileGuardrails = getProfile(req.profile)?.guardrails;
-    }
-    catch {
-        // If profile not registered yet, default to full guardrails
-    }
-    const options = {
-        sanitizeInput: profileGuardrails?.sanitizeInput ?? true,
-        redactSensitive: profileGuardrails?.redactSensitive ?? true,
-    };
+/**
+ * Sanitize user-controlled text fields; leave attachments/voice untouched.
+ *
+ * Returns `{ type: 'guardrail' }` events for stages that redacted something.
+ * Clean surfaces emit nothing.
+ *
+ * `req.system` is host-assembled per turn — it interpolates retrieval and user
+ * data, so it is treated as `assembled`, not trusted. `identity.system` never
+ * reaches this path and stays verbatim.
+ */
+function sanitizeTurnRequestText(req, profileId) {
+    const untrusted = detectionForProfile(profileId, 'untrusted');
+    const assembled = detectionForProfile(profileId, 'assembled');
     const input = req.input ?? {};
-    const { toolInvoke } = req;
+    const events = [];
+    const inputHits = [];
+    const historyHits = [];
+    const systemHits = [];
     const { text: rawText } = input;
-    let invoke = toolInvoke;
-    if (toolInvoke) {
-        invoke = { ...toolInvoke, arguments: sanitizeArgs(toolInvoke.arguments, options) };
-    }
     let text = rawText;
     if (rawText !== undefined) {
-        text = sanitizeText(rawText, options);
+        const detected = detectText(rawText, untrusted);
+        appendHits(inputHits, detected.hits);
+        text = detected.text;
     }
     let system = req.system;
     if (system !== undefined) {
-        system = sanitizeText(system, options);
-    }
+        const detected = detectText(system, assembled);
+        appendHits(systemHits, detected.hits);
+        system = detected.text;
+    }
+    const slots = sanitizeSlots(input.slots, untrusted, inputHits);
+    const repair = sanitizeRepair(input.repair, untrusted, inputHits);
+    const history = input.history
+        ? sanitizeHistory(input.history, untrusted, historyHits)
+        : undefined;
+    pushStageEvent(events, 'input', 'untrusted', inputHits);
+    pushStageEvent(events, 'history', 'untrusted', historyHits);
+    pushStageEvent(events, 'system', 'assembled', systemHits);
+    return {
+        request: {
+            ...req,
+            system,
+            projectId: sanitizeProjectId(req.projectId),
+            input: {
+                ...input,
+                text,
+                slots,
+                repair,
+                history,
+            },
+        },
+        events,
+    };
+}
+/** Sanitize all user-controlled text and blobs in a turn request. */
+function sanitizeTurnRequest(req) {
+    return sanitizeTurnRequestWithEvents(req).request;
+}
+/**
+ * Sanitize a turn request and return guardrail events for any redactionsactions spans.
+ * Attachments/voice are validated but do not emit content-span events.
+ */
+function sanitizeTurnRequestWithEvents(req) {
+    const { request: textSafe, events } = sanitizeTurnRequestText(req, req.profile);
+    const input = textSafe.input ?? {};
     const { attachments, voice } = sanitizeTurnBlobsForProfile(req.profile, input.attachments, input.voice);
     return {
-        ...req,
-        system,
-        projectId: sanitizeProjectId(req.projectId),
-        dynamicTools: sanitizeDynamicTools(req.dynamicTools, options),
-        input: {
-            ...input,
-            text,
-            slots: sanitizeSlots(input.slots, options),
-            attachments,
-            voice,
-            repair: sanitizeRepair(input.repair, options),
-            history: sanitizeHistory(input.history, options),
+        request: {
+            ...textSafe,
+            input: {
+                ...input,
+                attachments,
+                voice,
+            },
         },
-        toolInvoke: invoke,
+        events,
     };
 }
-export { PROJECT_ID_MAX, redactSensitiveOnly, sanitizeDynamicTools, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, };
+/**
+ * Trace-safe request sanitize. Prefers full `sanitizeTurnRequest`; if blob/policy
+ * checks throw, still redacts text and keeps attachments for hashing — never invents empty input.
+ */
+function sanitizeTurnRequestForTrace(req) {
+    try {
+        return { request: sanitizeTurnRequest(req) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            request: sanitizeTurnRequestText(req, req.profile).request,
+            sanitizeError: message,
+        };
+    }
+}
+export { detectionForProfile, detectText, PROJECT_ID_MAX, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestForTrace, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sensitive.js

@@ -23,7 +23,8 @@ const GITHUB_PAT = /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g;
 const GITHUB_TOKEN = /\bghp_[A-Za-z0-9]{36}\b/g;
 const SLACK_TOKEN = /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g;
 const BEARER = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
-const PEM_KEY = /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]+?-----END (?:RSA )?PRIVATE KEY-----/g;
+/** Bounded payload so PEM redaction cannot ReDoS on repeated BEGIN markers. */
+const PEM_KEY = /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]{0,16384}?-----END (?:RSA )?PRIVATE KEY-----/g;
 const CARD_CANDIDATE = /\b(?:\d[\s.-]*?){13,19}\b/g;
 const KEY_PATTERNS = [
     SSN,

package/esm/src/guardrails/serialize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Serialization for guardrail scanning.
+ *
+ * Detectors work on strings, so non-text event payloads (structured output, tool
+ * arguments, grounding metadata) must be flattened before they can be inspected.
+ * A guardrail must never be the thing that throws, so this never propagates a
+ * serializer error: cycles and bigints are represented rather than fatal, and a
+ * payload that still cannot be rendered is reported so the caller can fail closed.
+ *
+ * @module
+ */
+/** Marker substituted for a repeated reference so a cycle terminates. */
+declare const CIRCULAR = "[circular]";
+export interface ScanText {
+    text: string;
+    /** True when the payload could not be rendered and was not inspected. */
+    unscannable: boolean;
+}
+/**
+ * Flatten an arbitrary payload to text for detector scanning.
+ *
+ * Cycles collapse to `[circular]` and bigints render as digits, so the common
+ * unserializable shapes still get inspected instead of aborting the turn. Only a
+ * payload that defeats that (a throwing `toJSON`, for instance) comes back
+ * `unscannable`.
+ */
+declare function textForScan(value: unknown): ScanText;
+/**
+ * Scan-ready text, discarding the unscannable signal.
+ *
+ * For callers whose only question is "does this contain X" and for whom an
+ * unrenderable payload is the same as no match.
+ */
+declare function scanTextOf(value: unknown): string;
+export { CIRCULAR, scanTextOf, textForScan };

package/esm/src/guardrails/serialize.js

@@ -0,0 +1,58 @@
+/**
+ * Serialization for guardrail scanning.
+ *
+ * Detectors work on strings, so non-text event payloads (structured output, tool
+ * arguments, grounding metadata) must be flattened before they can be inspected.
+ * A guardrail must never be the thing that throws, so this never propagates a
+ * serializer error: cycles and bigints are represented rather than fatal, and a
+ * payload that still cannot be rendered is reported so the caller can fail closed.
+ *
+ * @module
+ */
+/** Marker substituted for a repeated reference so a cycle terminates. */
+const CIRCULAR = '[circular]';
+/**
+ * Flatten an arbitrary payload to text for detector scanning.
+ *
+ * Cycles collapse to `[circular]` and bigints render as digits, so the common
+ * unserializable shapes still get inspected instead of aborting the turn. Only a
+ * payload that defeats that (a throwing `toJSON`, for instance) comes back
+ * `unscannable`.
+ */
+function textForScan(value) {
+    if (value === undefined) {
+        return { text: '', unscannable: false };
+    }
+    if (typeof value === 'string') {
+        return { text: value, unscannable: false };
+    }
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'bigint') {
+                return val.toString();
+            }
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return CIRCULAR;
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+        return { text: json ?? '', unscannable: false };
+    }
+    catch {
+        return { text: '', unscannable: true };
+    }
+}
+/**
+ * Scan-ready text, discarding the unscannable signal.
+ *
+ * For callers whose only question is "does this contain X" and for whom an
+ * unrenderable payload is the same as no match.
+ */
+function scanTextOf(value) {
+    return textForScan(value).text;
+}
+export { CIRCULAR, scanTextOf, textForScan };

package/esm/src/guardrails/testing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Guardrails testing surface — adversarial corpus, fuzz runners, live attack builders.
+ *
+ * Import via `theorum/guardrails/testing` (not published on the production guardrails entry).
+ *
+ * @module
+ */
+/** lexicon-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export type { CanaryEgressAttack, CanaryEgressCatalogEntry, InboundFuzzPayload, InboundFuzzResult, LiveAttack, } from './corpus/mod.js';
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';
+export type { CorpusSample, CorpusSource } from './eval/corpus.js';
+export { createCorpusCache, parseLabelledCsv, recordsFromYaml, SOURCES } from './eval/corpus.js';
+export type { EvalOptions, EvalReport } from './eval/mod.js';
+export { DETECTORS, formatReport, runGuardrailEval } from './eval/mod.js';
+export type { DetectorScore, EvalDetector } from './eval/score.js';
+export { formatScores, scoreAll, scoreDetector } from './eval/score.js';

package/esm/src/guardrails/testing.js

@@ -0,0 +1,13 @@
+/**
+ * Guardrails testing surface — adversarial corpus, fuzz runners, live attack builders.
+ *
+ * Import via `theorum/guardrails/testing` (not published on the production guardrails entry).
+ *
+ * @module
+ */
+/** lexicon-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';
+export { createCorpusCache, parseLabelledCsv, recordsFromYaml, SOURCES } from './eval/corpus.js';
+export { DETECTORS, formatReport, runGuardrailEval } from './eval/mod.js';
+export { formatScores, scoreAll, scoreDetector } from './eval/score.js';

package/esm/src/guardrails/theorum-error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Contract-failure error class for THEORUM.
+ *
+ * Lives in its own module so `lexicon.ts` can throw it without importing
+ * `error.ts` (which resolves public copy through the lexicon).
+ *
+ * @module
+ */
+/** Error class used for expected THEORUM contract failures. */
+export declare class TheorumError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}

package/esm/src/guardrails/theorum-error.js

@@ -0,0 +1,15 @@
+/**
+ * Contract-failure error class for THEORUM.
+ *
+ * Lives in its own module so `lexicon.ts` can throw it without importing
+ * `error.ts` (which resolves public copy through the lexicon).
+ *
+ * @module
+ */
+/** Error class used for expected THEORUM contract failures. */
+export class TheorumError extends Error {
+    constructor(message = '', options) {
+        super(message, options);
+        this.name = 'TheorumError';
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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 type { AdvisoryLevel, GuardrailHit } from './types.js';
+/** Rule ids emitted by tool-ingress directive detection. */
+export declare const DIRECTIVE_RULES: {
+    readonly toolName: "tool_result.names-callable-tool";
+    readonly imperative: "tool_result.imperative";
+    readonly authority: "tool_result.authority-claim";
+};
+/**
+ * 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.
+ */
+declare function directiveHits(text: string, callableTools?: readonly string[]): GuardrailHit[];
+/** True when a result looked like it was trying to steer the agent. */
+declare function looksDirective(hits: GuardrailHit[]): boolean;
+/**
+ * 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.
+ */
+declare function advisoryLevel(hits: GuardrailHit[]): AdvisoryLevel;
+export { advisoryLevel, directiveHits, looksDirective };