theorum 1.0.0 → 1.1.3

package/esm/src/guardrails/network.js

@@ -0,0 +1,234 @@
+/**
+ * Network SSRF guardrails for HTTP and remote MCP tools.
+ *
+ * Enforces URL scheme safety and blocks loopback, private RFC 1918,
+ * link-local (cloud metadata 169.254.x.x), and multicast targets unless
+ * explicitly permitted by profile guardrail configuration.
+ *
+ * @module
+ */
+import { TheorumError } from './error.js';
+const PRIVATE_OR_LOCAL_IPV4_MATCHES = [
+    (b0) => b0 === 0, // 0.0.0.0/8
+    (b0) => b0 === 127, // 127.0.0.0/8 (loopback)
+    (b0) => b0 === 10, // 10.0.0.0/8
+    (b0, b1) => b0 === 100 && b1 >= 64 && b1 <= 127, // 100.64.0.0/10 (CGNAT)
+    (b0, b1) => b0 === 172 && b1 >= 16 && b1 <= 31, // 172.16.0.0/12
+    (b0, b1) => b0 === 192 && b1 === 168, // 192.168.0.0/16
+    (b0, b1) => b0 === 169 && b1 === 254, // 169.254.0.0/16 (link-local)
+    (b0, b1, b2) => b0 === 192 && b1 === 0 && (b2 === 0 || b2 === 2), // 192.0.0.0/24, 192.0.2.0/24
+    (b0, b1) => b0 === 198 && (b1 === 18 || b1 === 19), // 198.18.0.0/15
+    (b0, b1, b2) => b0 === 198 && b1 === 51 && b2 === 100, // 198.51.100.0/24
+    (b0, b1, b2) => b0 === 203 && b1 === 0 && b2 === 113, // 203.0.113.0/24
+    (b0) => b0 >= 224, // Multicast & Reserved (224.0.0.0/4, 240.0.0.0/4)
+];
+function isPrivateOrLocalIPv4Parts(b0, b1, b2, _b3) {
+    return PRIVATE_OR_LOCAL_IPV4_MATCHES.some((match) => match(b0, b1, b2));
+}
+function isPrivateOrLocalIPv4(ip) {
+    const parts = ip.split('.').map((p) => Number.parseInt(p, 10));
+    if (parts.length !== 4) {
+        return false;
+    }
+    const b0 = parts[0];
+    const b1 = parts[1];
+    const b2 = parts[2];
+    const b3 = parts[3];
+    if (b0 === undefined ||
+        b1 === undefined ||
+        b2 === undefined ||
+        b3 === undefined ||
+        Number.isNaN(b0) ||
+        Number.isNaN(b1) ||
+        Number.isNaN(b2) ||
+        Number.isNaN(b3) ||
+        b0 < 0 ||
+        b0 > 255 ||
+        b1 < 0 ||
+        b1 > 255 ||
+        b2 < 0 ||
+        b2 > 255 ||
+        b3 < 0 ||
+        b3 > 255) {
+        return false;
+    }
+    return isPrivateOrLocalIPv4Parts(b0, b1, b2, b3);
+}
+function parseIPv6Words(ip) {
+    const trimmed = ip.toLowerCase().trim();
+    const lastColon = trimmed.lastIndexOf(':');
+    let ipv4Words = [];
+    let v6Str = trimmed;
+    if (lastColon !== -1) {
+        const potentialV4 = trimmed.slice(lastColon + 1);
+        if (potentialV4.includes('.')) {
+            const v4Parts = potentialV4.split('.').map((p) => Number.parseInt(p, 10));
+            if (v4Parts.length !== 4 || v4Parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+                return null;
+            }
+            const b0 = v4Parts[0] ?? 0;
+            const b1 = v4Parts[1] ?? 0;
+            const b2 = v4Parts[2] ?? 0;
+            const b3 = v4Parts[3] ?? 0;
+            ipv4Words = [(b0 << 8) | b1, (b2 << 8) | b3];
+            v6Str = trimmed.slice(0, lastColon);
+        }
+    }
+    const parts = v6Str.split('::');
+    if (parts.length > 2)
+        return null;
+    const left = parts[0] ? parts[0].split(':').filter(Boolean) : [];
+    const right = parts.length === 2 && parts[1] ? parts[1].split(':').filter(Boolean) : [];
+    const needed = 8 - ipv4Words.length;
+    if (parts.length === 1) {
+        if (left.length !== needed)
+            return null;
+    }
+    else {
+        if (left.length + right.length >= needed)
+            return null;
+    }
+    const zerosNeeded = needed - (left.length + right.length);
+    const mid = new Array(zerosNeeded).fill(0);
+    const parseHex = (s) => (/^[0-9a-f]{1,4}$/.test(s) ? Number.parseInt(s, 16) : null);
+    const leftWords = [];
+    for (const s of left) {
+        const w = parseHex(s);
+        if (w === null)
+            return null;
+        leftWords.push(w);
+    }
+    const rightWords = [];
+    for (const s of right) {
+        const w = parseHex(s);
+        if (w === null)
+            return null;
+        rightWords.push(w);
+    }
+    return [...leftWords, ...mid, ...rightWords, ...ipv4Words];
+}
+/**
+ * Checks if an IPv6 address is in a private, loopback, or link-local range:
+ * - Loopback: ::1
+ * - Unspecified: ::
+ * - Link-local: fe80::/10
+ * - Unique Local (ULA): fc00::/7 (fc00:: - fdff::)
+ * - Multicast: ff00::/8
+ * - Documentation: 2001:db8::/32
+ * - Discard: 100::/64
+ * - IPv4-mapped (::ffff:0:0/96), IPv4-compatible (::/96), and NAT64 (64:ff9b::/96)
+ */
+function isPrivateOrLocalIPv6(ip) {
+    const words = parseIPv6Words(ip);
+    if (words?.length !== 8) {
+        return false;
+    }
+    const w0 = words[0] ?? 0;
+    const w1 = words[1] ?? 0;
+    // Unspecified ::
+    if (words.every((w) => w === 0))
+        return true;
+    // Loopback ::1
+    if (words.slice(0, 7).every((w) => w === 0) && words[7] === 1)
+        return true;
+    // Link-local unicast (fe80::/10)
+    if ((w0 & 0xffc0) === 0xfe80)
+        return true;
+    // Unique local address (fc00::/7)
+    if ((w0 & 0xfe00) === 0xfc00)
+        return true;
+    // Multicast (ff00::/8)
+    if ((w0 & 0xff00) === 0xff00)
+        return true;
+    // Documentation (2001:db8::/32)
+    if (w0 === 0x2001 && w1 === 0x0db8)
+        return true;
+    // Discard prefix (100::/64)
+    if (w0 === 0x0100 && words.slice(1, 4).every((w) => w === 0))
+        return true;
+    // IPv4-mapped (::ffff:0:0/96)
+    const isV4Mapped = words.slice(0, 5).every((w) => w === 0) && words[5] === 0xffff;
+    // IPv4-compatible (::/96)
+    const isV4Compatible = words.slice(0, 6).every((w) => w === 0);
+    // NAT64 well-known prefix (64:ff9b::/96)
+    const isNat64 = w0 === 0x0064 && w1 === 0xff9b && words.slice(2, 6).every((w) => w === 0);
+    if (isV4Mapped || isV4Compatible || isNat64) {
+        const w6 = words[6] ?? 0;
+        const w7 = words[7] ?? 0;
+        const b0 = (w6 >> 8) & 0xff;
+        const b1 = w6 & 0xff;
+        const b2 = (w7 >> 8) & 0xff;
+        const b3 = w7 & 0xff;
+        return isPrivateOrLocalIPv4Parts(b0, b1, b2, b3);
+    }
+    return false;
+}
+/** Check if hostname represents localhost or private domain names */
+export function isLocalhostName(hostname) {
+    let lower = hostname.toLowerCase();
+    while (lower.endsWith('.')) {
+        lower = lower.slice(0, -1);
+    }
+    return (lower === 'localhost' ||
+        lower.endsWith('.localhost') ||
+        lower === 'local' ||
+        lower.endsWith('.local') ||
+        lower === 'internal' ||
+        lower.endsWith('.internal') ||
+        lower === 'lan' ||
+        lower.endsWith('.lan') ||
+        lower === 'home.arpa' ||
+        lower.endsWith('.home.arpa') ||
+        lower === 'localdomain' ||
+        lower.endsWith('.localdomain') ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower === '[::1]');
+}
+/** Check if an IP address string is loopback or private IPv4/IPv6 */
+export function isPrivateOrLocalAddress(ipOrHost) {
+    const stripped = ipOrHost.startsWith('[') && ipOrHost.endsWith(']') ? ipOrHost.slice(1, -1) : ipOrHost;
+    return isPrivateOrLocalIPv4(stripped) || isPrivateOrLocalIPv6(stripped);
+}
+/**
+ * Validates a target URL against network guardrail policy.
+ * Throws a `TheorumError` if the URL is blocked.
+ */
+export function assertSafeUrl(urlStr, policy) {
+    let parsed;
+    try {
+        parsed = new URL(urlStr);
+    }
+    catch {
+        throw new TheorumError(`Invalid URL provided: "${urlStr}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const allowPrivate = policy?.allowPrivateNetworks ?? false;
+    const allowedHosts = policy?.allowedHosts?.map((h) => h.toLowerCase()) ?? [];
+    const hostname = parsed.hostname.toLowerCase();
+    // If host is explicitly whitelisted, allow it
+    if (allowedHosts.includes(hostname)) {
+        return parsed;
+    }
+    // Scheme validation
+    const defaultSchemes = allowPrivate ? ['http:', 'https:'] : ['https:'];
+    const allowedSchemes = policy?.allowedSchemes
+        ? policy.allowedSchemes.map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`))
+        : defaultSchemes;
+    if (!allowedSchemes.includes(parsed.protocol)) {
+        throw new TheorumError(`URL scheme "${parsed.protocol}" is not permitted by network policy. Allowed: ${allowedSchemes.join(', ')}`);
+    }
+    // Unless private networks are allowed, block localhost and private subnets
+    if (!allowPrivate) {
+        if (isLocalhostName(hostname)) {
+            throw new TheorumError(`Access to loopback target "${hostname}" blocked by network guardrail. Enable allowPrivateNetworks to permit local addresses.`);
+        }
+        if (isPrivateOrLocalIPv4(hostname)) {
+            throw new TheorumError(`Access to private IPv4 address "${hostname}" blocked by network guardrail.`);
+        }
+        const strippedV6 = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+        if (isPrivateOrLocalIPv6(strippedV6)) {
+            throw new TheorumError(`Access to private IPv6 address "${hostname}" blocked by network guardrail.`);
+        }
+    }
+    return parsed;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Guardrail policy resolution — one place where profile switches become defaults.
+ *
+ * Every ingress and egress path resolves through here so the turn engine and Live
+ * ingress cannot drift apart on what "unset" means.
+ *
+ * @module
+ */
+import type { ProfileGuardrailsSpec, ResolvedGuardrailPolicy, TrustLevel } from './types.js';
+/** Detection switches for one piece of text, after trust is taken into account. */
+export interface DetectionOptions {
+    sanitizeInput: boolean;
+    redactSensitive: boolean;
+}
+/**
+ * Apply kernel defaults to a profile's guardrail switches.
+ *
+ * Sanitization, sensitive redaction, and canary default on. Set `canary: false`
+ * to opt out of minting a per-turn token into the system prompt.
+ */
+declare function resolveGuardrailPolicy(spec: ProfileGuardrailsSpec | undefined): ResolvedGuardrailPolicy;
+/**
+ * Narrow a resolved policy to the detectors that may run against text of a given
+ * origin, on the way to the provider.
+ *
+ * Trusted text is author-time profile copy. Injection redaction would strip the
+ * host's own anti-injection instructions, and sensitive redaction would rewrite a
+ * prompt that legitimately shows a key or address format — so trusted text is
+ * passed to the provider verbatim. Trace safety does not depend on this: the trace
+ * writer redacts independently on every path.
+ *
+ * Assembled and untrusted text take whatever the profile enabled.
+ */
+declare function detectionForTrust(policy: ResolvedGuardrailPolicy, trust: TrustLevel): DetectionOptions;
+export { detectionForTrust, resolveGuardrailPolicy };

package/esm/src/guardrails/policy.js

@@ -0,0 +1,50 @@
+/**
+ * Guardrail policy resolution — one place where profile switches become defaults.
+ *
+ * Every ingress and egress path resolves through here so the turn engine and Live
+ * ingress cannot drift apart on what "unset" means.
+ *
+ * @module
+ */
+/**
+ * Apply kernel defaults to a profile's guardrail switches.
+ *
+ * Sanitization, sensitive redaction, and canary default on. Set `canary: false`
+ * to opt out of minting a per-turn token into the system prompt.
+ */
+function resolveGuardrailPolicy(spec) {
+    const canarySpec = spec?.canary;
+    return {
+        sanitizeInput: spec?.sanitizeInput ?? true,
+        redactSensitive: spec?.redactSensitive ?? true,
+        // Object form configures the bind note; minting stays on.
+        canary: typeof canarySpec === 'boolean' ? canarySpec : true,
+        canaryBindNote: typeof canarySpec === 'object' ? canarySpec.bindNote : undefined,
+        egress: spec?.egress,
+        network: spec?.network,
+        quota: spec?.quota,
+        taint: spec?.taint,
+    };
+}
+/**
+ * Narrow a resolved policy to the detectors that may run against text of a given
+ * origin, on the way to the provider.
+ *
+ * Trusted text is author-time profile copy. Injection redaction would strip the
+ * host's own anti-injection instructions, and sensitive redaction would rewrite a
+ * prompt that legitimately shows a key or address format — so trusted text is
+ * passed to the provider verbatim. Trace safety does not depend on this: the trace
+ * writer redacts independently on every path.
+ *
+ * Assembled and untrusted text take whatever the profile enabled.
+ */
+function detectionForTrust(policy, trust) {
+    if (trust === 'trusted') {
+        return { sanitizeInput: false, redactSensitive: false };
+    }
+    return {
+        sanitizeInput: policy.sanitizeInput,
+        redactSensitive: policy.redactSensitive,
+    };
+}
+export { detectionForTrust, resolveGuardrailPolicy };

package/esm/src/guardrails/progressive-yield.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Progressive-yield outbound gate — stream cleared prefixes while holding a
+ * lookback window so canary / sensitive / boundary / injection (and optional
+ * host `egress.enforce`) can inspect split-token matches before release.
+ *
+ * @module
+ */
+import type { EgressEnforcer, GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
+/** Default lookback for span detectors that are not canary-sized. */
+declare const DEFAULT_HOLDBACK = 256;
+export type ProgressiveYieldOk = {
+    blocked: false;
+    emit: string;
+};
+export type ProgressiveYieldBlocked = {
+    blocked: true;
+    hits: GuardrailHit[];
+};
+export type ProgressiveYieldResult = ProgressiveYieldOk | ProgressiveYieldBlocked;
+export interface ProgressiveYieldGateOptions {
+    /** Stage facts handed to `enforce`; also carries the turn canary. */
+    context: GuardrailContext;
+    /** When set, each step runs this policy on the accumulated window before emit. */
+    enforce?: EgressEnforcer;
+    /** Floor for lookback beyond canary overlap (characters). */
+    holdback?: number;
+}
+interface ProgressiveYieldGate {
+    process: (fragment: string) => Promise<ProgressiveYieldResult>;
+    flush: () => Promise<ProgressiveYieldResult>;
+    /** Full window inspected so far (for end-of-attempt egress / repair). */
+    accumulated: () => string;
+    /** Lookback tail not yet released to the host. Peek only. */
+    unreleased: () => string;
+    /**
+     * Take the tail not yet released and mark it released.
+     *
+     * Used when the runner records withheld text for the egress window: without
+     * advancing the cursor a later `flush` re-releases the same range and the
+     * attempt buffer ends up holding the text twice.
+     */
+    drainUnreleased: () => string;
+}
+declare function createProgressiveYieldGate(options: ProgressiveYieldGateOptions): ProgressiveYieldGate;
+/**
+ * Shared constructor for runTurn + Live: gate when canary and/or egress.enforce
+ * is active. `context.canary` is set only when the profile enabled canary minting.
+ */
+declare function createOutboundProgressiveGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext): ProgressiveYieldGate | null;
+export type { ProgressiveYieldGate };
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK };

package/esm/src/guardrails/progressive-yield.js

@@ -0,0 +1,98 @@
+/**
+ * Progressive-yield outbound gate — stream cleared prefixes while holding a
+ * lookback window so canary / sensitive / boundary / injection (and optional
+ * host `egress.enforce`) can inspect split-token matches before release.
+ *
+ * @module
+ */
+import { collectEgressHits, runEnforcer } from './egress.js';
+/** Default lookback for span detectors that are not canary-sized. */
+const DEFAULT_HOLDBACK = 256;
+const PEM_BEGIN = '-----BEGIN';
+function resolveHoldback(canary, holdback) {
+    const canaryHold = canary ? Math.max(0, canary.length - 1) : 0;
+    return Math.max(canaryHold, holdback ?? DEFAULT_HOLDBACK);
+}
+function holdbackForWindow(window, base) {
+    // Incomplete PEM bodies can be large; do not release past BEGIN until END/flush.
+    const begin = window.lastIndexOf(PEM_BEGIN);
+    if (begin < 0)
+        return base;
+    const fromBegin = window.slice(begin);
+    if (/-----END (?:RSA )?PRIVATE KEY-----/.test(fromBegin))
+        return base;
+    return Math.max(base, window.length - begin);
+}
+function createProgressiveYieldGate(options) {
+    const { context } = options;
+    const baseHoldback = resolveHoldback(context.canary, options.holdback);
+    let accumulated = '';
+    let emitted = 0;
+    async function scan(window) {
+        if (options.enforce) {
+            // Mid-stream the gate can only release or stop: emitted prefixes cannot be
+            // rewritten, so `redact` stops here and end-of-attempt egress applies the
+            // full verdict. `flag` is advisory and keeps the stream flowing.
+            const verdict = await runEnforcer(options.enforce, { text: window }, context);
+            if (verdict.action === 'block' || verdict.action === 'redact') {
+                return verdict.hits.length > 0
+                    ? verdict.hits
+                    : [{ rule: 'egress.blocked', severity: 'high' }];
+            }
+            // Host enforce is authoritative when present (matches end-of-attempt egress).
+            return null;
+        }
+        const hits = collectEgressHits(window, context.canary);
+        return hits.length > 0 ? hits : null;
+    }
+    async function release(releaseTail) {
+        const hits = await scan(accumulated);
+        if (hits) {
+            return { blocked: true, hits };
+        }
+        if (releaseTail) {
+            const emit = accumulated.slice(emitted);
+            emitted = accumulated.length;
+            return { blocked: false, emit };
+        }
+        const hold = holdbackForWindow(accumulated, baseHoldback);
+        const safeEnd = Math.max(emitted, accumulated.length - hold);
+        const emit = accumulated.slice(emitted, safeEnd);
+        emitted = safeEnd;
+        return { blocked: false, emit };
+    }
+    return {
+        async process(fragment) {
+            if (!fragment) {
+                return { blocked: false, emit: '' };
+            }
+            accumulated += fragment;
+            return await release(false);
+        },
+        async flush() {
+            return await release(true);
+        },
+        accumulated: () => accumulated,
+        unreleased: () => accumulated.slice(emitted),
+        drainUnreleased() {
+            const tail = accumulated.slice(emitted);
+            emitted = accumulated.length;
+            return tail;
+        },
+    };
+}
+/**
+ * Shared constructor for runTurn + Live: gate when canary and/or egress.enforce
+ * is active. `context.canary` is set only when the profile enabled canary minting.
+ */
+function createOutboundProgressiveGate(policy, context) {
+    const enforce = policy.egress?.enforce;
+    if (!enforce && !context.canary) {
+        return null;
+    }
+    return createProgressiveYieldGate({
+        context,
+        ...(enforce ? { enforce } : {}),
+    });
+}
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK };

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

@@ -4,7 +4,21 @@ declare function skipQuota(peer: string, req: Request): boolean;
 declare function clientIp(peer: string, req: Request): string;
 declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
 declare function releaseSlot(profile: Profile, ip: string): void;
-declare function quotaMessage(profile: Profile): string;
+/**
+ * Structured quota-trip report. The kernel authors no copy here: `message` is
+ * present if and only if the host set `guardrails.quota.message`.
+ */
+interface QuotaExhausted {
+    code: 'quota_exhausted';
+    perDay: number;
+    message?: string;
+}
+/**
+ * Structured data for a tripped quota, or `undefined` when the profile has no
+ * quota configured. Hosts render their own copy from `code` / `perDay` /
+ * `message` — there is no English fallback in the kernel.
+ */
+declare function quotaExhausted(profile: Profile): QuotaExhausted | undefined;
 declare function resetSlots(): void;
-export type { QuotaSlotStatus };
-export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };
+export type { QuotaExhausted, QuotaSlotStatus };
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/quota.js

@@ -1,3 +1,4 @@
+import { resolveGuardrailPolicy } from './policy.js';
 const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
 const slots = new Map();
 function utcDay(now) {
@@ -28,7 +29,7 @@ function clientIp(peer, req) {
     return 'unknown';
 }
 function takeSlot(profile, ip, now) {
-    const quota = profile.guardrails?.quota;
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
     if (!quota) {
         return 'not_configured';
     }
@@ -55,10 +56,23 @@ function releaseSlot(profile, ip) {
         slot.busy = false;
     }
 }
-function quotaMessage(profile) {
-    return `Enjoying ${profile.identity.handle}? You've reached today's limit`;
+/**
+ * Structured data for a tripped quota, or `undefined` when the profile has no
+ * quota configured. Hosts render their own copy from `code` / `perDay` /
+ * `message` — there is no English fallback in the kernel.
+ */
+function quotaExhausted(profile) {
+    const quota = resolveGuardrailPolicy(profile.guardrails).quota;
+    if (!quota) {
+        return undefined;
+    }
+    return {
+        code: 'quota_exhausted',
+        perDay: quota.perDay,
+        ...(quota.message !== undefined ? { message: quota.message } : {}),
+    };
 }
 function resetSlots() {
     slots.clear();
 }
-export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };

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

@@ -3,18 +3,48 @@
  *
  * @module
  */
-import type { NormalizedTurnRequest, TurnRequest } from '../kernel/types.js';
+import type { NormalizedTurnRequest, TurnEvent, TurnRequest } from '../kernel/types.js';
+import { type DetectionOptions } from './policy.js';
+import type { GuardrailHit, TrustLevel } from './types.js';
+/**
+ * Detect and redact injection / sensitive spans. Returns hits for observability
+ * (rule + offsets + optional `match` preview for debugging).
+ */
+declare function detectText(text: string, options?: Partial<DetectionOptions>): {
+    text: string;
+    hits: GuardrailHit[];
+};
 /** Sanitize one text value using prompt-injection and sensitive-data detectors. */
-declare function sanitizeText(text: string, options?: {
-    sanitizeInput?: boolean;
-    redactSensitive?: boolean;
-}): string;
+declare function sanitizeText(text: string, options?: Partial<DetectionOptions>): string;
 /** Redact only sensitive data (credentials, PII) — skip injection patterns. */
 declare function redactSensitiveOnly(text: string): string;
 declare const PROJECT_ID_MAX = 128;
 declare function sanitizeProjectId(id: string | undefined): string | undefined;
+/**
+ * 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.
+ */
+declare function sanitizeHistory(history: import('../kernel/types.js').TurnHistoryMessage[], options: DetectionOptions, hits?: GuardrailHit[]): import('../kernel/types.js').TurnHistoryMessage[];
+/**
+ * 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.
+ */
+declare function detectionForProfile(profileId: string, trust: TrustLevel): DetectionOptions;
 /** Sanitize all user-controlled text and blobs in a turn request. */
 declare function sanitizeTurnRequest(req: TurnRequest): NormalizedTurnRequest;
+/**
+ * Sanitize a turn request and return guardrail events for any redactionsactions spans.
+ * Attachments/voice are validated but do not emit content-span events.
+ */
+declare function sanitizeTurnRequestWithEvents(req: TurnRequest): {
+    request: NormalizedTurnRequest;
+    events: TurnEvent[];
+};
 /**
  * Trace-safe request sanitize. Prefers full `sanitizeTurnRequest`; if blob/policy
  * checks throw, still redacts text and keeps attachments for hashing — never invents empty input.
@@ -23,4 +53,4 @@ declare function sanitizeTurnRequestForTrace(req: TurnRequest): {
     request: NormalizedTurnRequest;
     sanitizeError?: string;
 };
-export { PROJECT_ID_MAX, redactSensitiveOnly, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestForTrace, };
+export { detectionForProfile, detectText, PROJECT_ID_MAX, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestForTrace, sanitizeTurnRequestWithEvents, };