theorum 0.1.4 → 0.1.6

package/esm/src/guardrails/error.js

@@ -0,0 +1,149 @@
+/**
+ * Public-safe error mapping for THEORUM.
+ *
+ * Kernel internals may contain provider status text, tool names, or exception
+ * details. This module maps those failures to stable user-safe strings.
+ *
+ * @module
+ */
+/** Error class used for expected THEORUM contract failures. */
+class TheorumError extends Error {
+    constructor(message = '', options) {
+        super(message, options);
+        this.name = 'TheorumError';
+    }
+}
+/** Internal marker for provider or transport failure. */
+const UPSTREAM_FAILED = 'upstream failed';
+/** Generic safe fallback shown when details must not be surfaced. */
+const PUBLIC_GENERIC = 'Something went wrong. Try again.';
+/** Safe copy for transient provider unavailability. */
+const PUBLIC_UNAVAILABLE = 'The model is unavailable. Try again.';
+/** Safe copy for canary or egress disclosure violations. */
+const PUBLIC_CANARY = "That reply wasn't safe to show. Try again.";
+/** Safe copy for tool or permission denials. */
+const PUBLIC_ACTION = "That action isn't available.";
+/** Safe copy for unsupported MIME types. */
+const PUBLIC_FILE_TYPE = "That file type isn't supported.";
+/** Safe copy for oversized files. */
+const PUBLIC_FILE_SIZE = 'That file is too large.';
+/** Safe copy for too many files in one turn. */
+const PUBLIC_FILE_COUNT = 'Too many files for one message.';
+/** Safe copy for unsupported generated image dimensions. */
+const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
+const EXACT = {
+    [UPSTREAM_FAILED]: PUBLIC_UNAVAILABLE,
+    'empty Gemini stream': PUBLIC_UNAVAILABLE,
+    'canary leaked': PUBLIC_CANARY,
+    'Turn withheld: egress disclosure violation': PUBLIC_CANARY,
+    'expected JSON object': 'Something was wrong with that request.',
+    'user input cannot be placed in the system block': PUBLIC_GENERIC,
+    'attachment data must be base64': PUBLIC_FILE_TYPE,
+    'attachment is too large': PUBLIC_FILE_SIZE,
+    'attachments exceed the per-turn budget': PUBLIC_FILE_SIZE,
+    'askUser.kind must be confirm, choice, or text': "That question isn't valid.",
+    'askUser.prompt is required': 'That question needs a prompt.',
+    'This profile does not accept text input': PUBLIC_ACTION,
+};
+const RULES = [
+    {
+        match: (t) => /^(Gemini|OpenRouter|TTS|OpenRouter TTS|Speech) HTTP/.test(t) ||
+            t.includes('TTS HTTP') ||
+            t.includes('Speech HTTP'),
+        resolve: () => PUBLIC_UNAVAILABLE,
+    },
+    {
+        match: (t) => t.includes('not gated') ||
+            t.includes('not allowed') ||
+            t.includes('has no kernel executor') ||
+            t.includes('Unknown model select') ||
+            t.includes('Grounding tools'),
+        resolve: () => PUBLIC_ACTION,
+    },
+    {
+        match: (t) => t.includes('MIME') ||
+            t.includes('does not accept attachments') ||
+            t.includes('does not accept voice'),
+        resolve: () => PUBLIC_FILE_TYPE,
+    },
+    {
+        match: (t) => t.startsWith('At most'),
+        resolve: () => PUBLIC_FILE_COUNT,
+    },
+    {
+        match: (t) => (t.startsWith('Only ') && t.includes('file')) ||
+            t.startsWith('Each file must be') ||
+            t.startsWith('Those files together'),
+        resolve: (t) => t,
+    },
+    {
+        match: (t) => t.includes('attachment'),
+        resolve: () => PUBLIC_FILE_SIZE,
+    },
+    {
+        match: (t) => t.includes('aspect or size'),
+        resolve: () => PUBLIC_IMAGE_SIZE,
+    },
+    {
+        match: (t) => t.includes('must pin thinking') || t.includes('has no models'),
+        resolve: () => PUBLIC_GENERIC,
+    },
+];
+const ALREADY_PUBLIC = new Set([
+    PUBLIC_GENERIC,
+    PUBLIC_UNAVAILABLE,
+    PUBLIC_CANARY,
+    PUBLIC_ACTION,
+    PUBLIC_FILE_TYPE,
+    PUBLIC_FILE_SIZE,
+    PUBLIC_FILE_COUNT,
+    PUBLIC_IMAGE_SIZE,
+]);
+function publicText(text) {
+    if (ALREADY_PUBLIC.has(text)) {
+        return text;
+    }
+    const exact = EXACT[text];
+    if (exact) {
+        return exact;
+    }
+    for (const rule of RULES) {
+        if (rule.match(text)) {
+            return rule.resolve(text);
+        }
+    }
+    return PUBLIC_GENERIC;
+}
+/** Convert an unknown thrown value or internal message to user-safe text. */
+function publicError(err) {
+    if (typeof err === 'string') {
+        return publicText(err);
+    }
+    if (err instanceof TheorumError) {
+        return publicText(err.message);
+    }
+    return PUBLIC_UNAVAILABLE;
+}
+/** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
+function describeError(err) {
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err instanceof Error && err.message) {
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Stream error event with a public-safe `error` and a preserved `errorInternal`.
+ * Providers and the runner should emit this instead of public-only error strings
+ * so traces and host logs are never a black box.
+ */
+function toErrorEvent(err) {
+    return {
+        type: 'error',
+        error: publicError(err),
+        errorInternal: describeError(err),
+    };
+}
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };

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

@@ -0,0 +1,12 @@
+/**
+ * Prompt-injection span detection.
+ *
+ * These utilities return spans that can be redacted from untrusted user text
+ * before provider submission.
+ *
+ * @module
+ */
+import { type RedactSpan } from '../observability/spans.js';
+/** Detect prompt-injection spans in a string. */
+declare function injectionSpans(text: string): RedactSpan[];
+export { injectionSpans };

package/esm/src/guardrails/injection.js

@@ -0,0 +1,220 @@
+/**
+ * Prompt-injection span detection.
+ *
+ * These utilities return spans that can be redacted from untrusted user text
+ * before provider submission.
+ *
+ * @module
+ */
+import { blobAt, spansFromPatterns } from '../observability/spans.js';
+const IGNORE_PREVIOUS = /ignore\s+(all\s+)?(previous|prior)\s+((?:safety|security|system|operational|internal|core|original|initial|existing|given|stated|provided|defined|specified|established)\s+)?(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const DISREGARD_INSTRUCTIONS = /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const FORGET_INSTRUCTIONS = /forget\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const NEW_INSTRUCTIONS = /new\s+instructions?:/gi;
+const DO_NOT_FOLLOW = /do\s+not\s+follow\s+(the\s+)?(system|developer|previous|original)/gi;
+const SUPERSEDE_INSTRUCTIONS = /supersedes?\s+(all\s+)?(prior|previous)\s+(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const VOID_INSTRUCTIONS = /(all\s+)?(previous|prior)\s+instructions?\s+(are|is)\s+(void|invalid|null|obsolete|cancelled|revoked)/gi;
+const DEVELOPER_MODE = /you\s+are\s+now\s+(in\s+)?developer\s+mode/gi;
+const ENTER_SPECIAL_MODE = /enter\s+(developer|admin|debug|maintenance)\s+mode/gi;
+const ACTIVATE_SPECIAL_MODE = /activate\s+(developer|admin|debug|jailbreak)\s+mode/gi;
+const SYSTEM_OVERRIDE = /\bsystem\s+override\b/gi;
+const OVERRIDE_INSTRUCTIONS = /override\s+(your\s+)?(instructions?|rules?|guidelines?|constraints?|directives?)/gi;
+const REVEAL_PROMPT = /reveal\s+((?:your?|yoru|yuor|the|my|its|his|her|our|their)\s+)?((?:(?:full|hidden|complete|internal|secret|original|entire|exact|actual|real)\s+){0,2})((?:system|systme|sysetm|systemp?)\s+)?prompt\b/gi;
+const SHOW_PROMPT = /show\s+(me\s+)?((?:your?|yoru|yuor|the|my|its|his|her|our|their)\s+)((?:system|systme|sysetm|systemp?)\s+)?prompt\b/gi;
+const WHAT_INSTRUCTIONS = /what\s+(are|were)\s+(your\s+)?(exact\s+)?instructions/gi;
+const REPEAT_INSTRUCTIONS = /repeat\s+(the\s+)?(text|instructions?)\s+(above|before)/gi;
+const OUTPUT_PROMPT = /output\s+(your\s+)?(initial|original|system)\s+(prompt|instructions?)/gi;
+const REMOVE_RESTRICTIONS = /you\s+are\s+no\s+longer\s+(bound|restricted|limited)/gi;
+const ACT_UNBOUND = /act\s+as\s+if\s+(you('re|\s+are)\s+)?not\s+bound/gi;
+const PRETEND_DIFFERENT = /pretend\s+(you('re|\s+are)\s+)?(a\s+)?different\s+(ai|assistant|model)/gi;
+const IDENTITY_HIJACK = /you\s+are\s+now\s+(?:(?:a|an)\s+)?\w+.{0,40}(without\s+(any\s+)?restrict|ignor\w*\s+(all|any|every|prev)|bypass|unrestrict|unlimit|obey\s+only|no\s+(rules|limits|restrict|boundari))/gi;
+const DAN_JAILBREAK = /\bDAN\b[\s\S]{0,120}\bdo\s+anything\s+now\b/g;
+const JAILBREAK_MODE = /jailbreak(ed)?\s+(mode|prompt)/gi;
+const DO_ANYTHING_NOW = /\bdo\s+anything\s+now\b/gi;
+const BYPASS_SAFETY = /bypass\s+(your\s+)?(safety|security|content|ethical)\s+(filters?|measures?|guidelines?|restrictions?)/gi;
+const DISABLE_SAFETY = /disable\s+(your\s+)?(safety|security|content)\s+(filters?|measures?)/gi;
+const IGNORE_SAFETY = /(ignore|disregard)\s+(all\s+)?(your\s+)?(safety|security|ethical|content)\s+(guidelines?|rules?|restrictions?|measures?|filters?|polic(?:y|ies)|protocols?)/gi;
+const SYSTEM_TAG = /<\s*\/?\s*system\s*\/?>/gi;
+const ROLE_TAG = /<\s*\/?\s*(assistant|developer|tool|function)\s*\/?>/gi;
+const ROLE_DELIMITER = /\]\s*\n\s*\[?(system|assistant|user)\]?:/gi;
+const BRACKETED_ROLE = /\[\s*(System\s*Message|System|Assistant|Internal)\s*\]/gi;
+const SYSTEM_YOU_ARE = /^\s*System:\s+(you\s+are|ignore|override)/gim;
+const CONTROL_TOKEN = /<\|(?:im_start|im_end|eot_id|start_header_id|end_header_id|endoftext)\|>/g;
+const DEEPSEEK_CONTROL = /<\uFF5C(?:end\u2581of\u2581sentence|begin\u2581of\u2581sentence)\uFF5C>/g;
+const LLAMA_INST = /\[\/?INST\]/gi;
+const IGNORE_YOUR_INSTRUCTIONS = /ignore\s+(all\s+)?(your\s+)?(instructions?|rules?)\b/gi;
+const UNRESTRICTED_MODE = /\bunrestricted\s+(ai|mode|model)\b/gi;
+const INJECTION_PATTERNS = [
+    IGNORE_PREVIOUS,
+    DISREGARD_INSTRUCTIONS,
+    FORGET_INSTRUCTIONS,
+    NEW_INSTRUCTIONS,
+    DO_NOT_FOLLOW,
+    SUPERSEDE_INSTRUCTIONS,
+    VOID_INSTRUCTIONS,
+    DEVELOPER_MODE,
+    ENTER_SPECIAL_MODE,
+    ACTIVATE_SPECIAL_MODE,
+    SYSTEM_OVERRIDE,
+    OVERRIDE_INSTRUCTIONS,
+    REVEAL_PROMPT,
+    SHOW_PROMPT,
+    WHAT_INSTRUCTIONS,
+    REPEAT_INSTRUCTIONS,
+    OUTPUT_PROMPT,
+    REMOVE_RESTRICTIONS,
+    ACT_UNBOUND,
+    PRETEND_DIFFERENT,
+    IDENTITY_HIJACK,
+    DAN_JAILBREAK,
+    JAILBREAK_MODE,
+    DO_ANYTHING_NOW,
+    BYPASS_SAFETY,
+    DISABLE_SAFETY,
+    IGNORE_SAFETY,
+    SYSTEM_TAG,
+    ROLE_TAG,
+    ROLE_DELIMITER,
+    BRACKETED_ROLE,
+    SYSTEM_YOU_ARE,
+    CONTROL_TOKEN,
+    DEEPSEEK_CONTROL,
+    LLAMA_INST,
+    IGNORE_YOUR_INSTRUCTIONS,
+    UNRESTRICTED_MODE,
+];
+const TYPO_TARGETS = [
+    'ignore',
+    'bypass',
+    'override',
+    'reveal',
+    'delete',
+    'system',
+    'prompt',
+    'instructions',
+];
+const BASE64_BLOB = /[A-Za-z0-9+/]{16,}={0,2}/g;
+const HEX_BLOB = /(?:[0-9a-f]{2}[\s]?){8,}/gi;
+const SPACED_LETTERS = /\b(?:[A-Za-z] ){3,}[A-Za-z]\b/g;
+const WORD = /\b[A-Za-z]{4,}\b/g;
+const PRINTABLE_MIN = 0.85;
+const CODE_TAB = 9;
+const CODE_LF = 10;
+const CODE_CR = 13;
+const CODE_SPACE = 32;
+const CODE_DEL = 127;
+const HEX_RADIX = 16;
+const HEX_STEP = 2;
+function injectionSpansOn(text) {
+    return spansFromPatterns(text, INJECTION_PATTERNS, 'injection');
+}
+function sortedLetters(value) {
+    return [...value].sort().join('');
+}
+function firstLast(word) {
+    return { first: word.at(0), last: word.at(-1) };
+}
+function isTypoglycemia(word, target) {
+    if (word.length !== target.length) {
+        return false;
+    }
+    const lower = word.toLowerCase();
+    if (lower === target) {
+        return false;
+    }
+    const wordEnds = firstLast(lower);
+    const targetEnds = firstLast(target);
+    if (wordEnds.first !== targetEnds.first || wordEnds.last !== targetEnds.last) {
+        return false;
+    }
+    return sortedLetters(lower.slice(1, -1)) === sortedLetters(target.slice(1, -1));
+}
+function typoNormalize(text) {
+    return text.replace(WORD, (word) => {
+        for (const target of TYPO_TARGETS) {
+            if (isTypoglycemia(word, target)) {
+                return target;
+            }
+        }
+        return word;
+    });
+}
+function isMostlyPrintable(value) {
+    if (!value) {
+        return false;
+    }
+    let ok = 0;
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        const control = code === CODE_TAB || code === CODE_LF || code === CODE_CR;
+        const visible = code >= CODE_SPACE && code < CODE_DEL;
+        if (control || visible) {
+            ok += 1;
+        }
+    }
+    return ok / value.length >= PRINTABLE_MIN;
+}
+function decodedHits(decoded) {
+    if (!isMostlyPrintable(decoded)) {
+        return false;
+    }
+    return injectionSpansOn(decoded).length > 0;
+}
+function tryBase64(blob) {
+    try {
+        return atob(blob);
+    }
+    catch {
+        return undefined;
+    }
+}
+function tryHex(blob) {
+    const hex = blob.replaceAll(/\s/g, '');
+    if (hex.length % HEX_STEP !== 0) {
+        return undefined;
+    }
+    let out = '';
+    for (let i = 0; i < hex.length; i += HEX_STEP) {
+        out += String.fromCodePoint(Number.parseInt(hex.slice(i, i + HEX_STEP), HEX_RADIX));
+    }
+    return out;
+}
+function encodedFrom(text, pattern, decode) {
+    const spans = [];
+    for (const match of text.matchAll(pattern)) {
+        const found = blobAt(match);
+        if (found) {
+            const decoded = decode(found.blob);
+            if (decoded && decodedHits(decoded)) {
+                spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'injection' });
+            }
+        }
+    }
+    return spans;
+}
+function encodedSpans(text) {
+    return [...encodedFrom(text, BASE64_BLOB, tryBase64), ...encodedFrom(text, HEX_BLOB, tryHex)];
+}
+function spacedSpans(text) {
+    const spans = [];
+    for (const match of text.matchAll(SPACED_LETTERS)) {
+        const found = blobAt(match);
+        if (found) {
+            const collapsed = found.blob.replaceAll(' ', '');
+            if (injectionSpansOn(`${collapsed} previous instructions`).length > 0) {
+                spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'injection' });
+            }
+        }
+    }
+    return spans;
+}
+/** Detect prompt-injection spans in a string. */
+function injectionSpans(text) {
+    const shadow = typoNormalize(text);
+    let typo = [];
+    if (shadow !== text) {
+        typo = injectionSpansOn(shadow);
+    }
+    return [...injectionSpansOn(text), ...typo, ...encodedSpans(text), ...spacedSpans(text)];
+}
+export { injectionSpans };

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

@@ -0,0 +1,16 @@
+/**
+ * Generic inbound and outbound guardrail primitives.
+ *
+ * This entrypoint exposes public-safe error mapping, prompt-injection span
+ * detection, sensitive-data span detection, and request sanitization. App-
+ * specific policy remains host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { injectionSpans } from './injection.js';
+export type { QuotaSlotStatus } from './quota.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
+export { sensitiveSpans } from './sensitive.js';

package/esm/src/guardrails/mod.js

@@ -0,0 +1,15 @@
+/**
+ * Generic inbound and outbound guardrail primitives.
+ *
+ * This entrypoint exposes public-safe error mapping, prompt-injection span
+ * detection, sensitive-data span detection, and request sanitization. App-
+ * specific policy remains host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { describeError, PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
+export { injectionSpans } from './injection.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
+export { sensitiveSpans } from './sensitive.js';

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

@@ -0,0 +1,10 @@
+import type { Profile } from '../kernel/types.js';
+type QuotaSlotStatus = 'ok' | 'busy' | 'quota' | 'not_configured';
+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;
+declare function resetSlots(): void;
+export type { QuotaSlotStatus };
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/quota.js

@@ -0,0 +1,64 @@
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+const slots = new Map();
+function utcDay(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+function isLoopback(peer) {
+    return LOOPBACK.has(peer);
+}
+function cfConnectingIp(req) {
+    return req.headers.get('cf-connecting-ip')?.trim() ?? '';
+}
+function slotKey(profileId, ip) {
+    return `${profileId}:${ip}`;
+}
+function skipQuota(peer, req) {
+    return isLoopback(peer) && !cfConnectingIp(req);
+}
+function clientIp(peer, req) {
+    if (isLoopback(peer)) {
+        const cf = cfConnectingIp(req);
+        if (cf) {
+            return cf;
+        }
+    }
+    if (peer) {
+        return peer;
+    }
+    return 'unknown';
+}
+function takeSlot(profile, ip, now) {
+    const quota = profile.guardrails.quota;
+    if (!quota) {
+        return 'not_configured';
+    }
+    const day = utcDay(now);
+    const key = slotKey(profile.id, ip);
+    let slot = slots.get(key);
+    if (!slot || slot.day !== day) {
+        slot = { day, count: 0, busy: false };
+        slots.set(key, slot);
+    }
+    if (slot.busy) {
+        return 'busy';
+    }
+    if (slot.count >= quota.perDay) {
+        return 'quota';
+    }
+    slot.busy = true;
+    slot.count += 1;
+    return 'ok';
+}
+function releaseSlot(profile, ip) {
+    const slot = slots.get(slotKey(profile.id, ip));
+    if (slot) {
+        slot.busy = false;
+    }
+}
+function quotaMessage(profile) {
+    return `Enjoying ${profile.identity.handle}? You've reached today's limit`;
+}
+function resetSlots() {
+    slots.clear();
+}
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };

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

@@ -0,0 +1,22 @@
+/**
+ * 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 type { NormalizedTurnRequest, TurnRequest } from '../kernel/types.js';
+/** Sanitize one text value using prompt-injection and sensitive-data detectors. */
+declare function sanitizeText(text: string, options?: {
+    sanitizeInput?: boolean;
+    redactSensitive?: boolean;
+}): string;
+/** Maximum retained length for trace-safe host project ids. */
+declare const PROJECT_ID_MAX = 128;
+/** Return a trace-safe project id or `undefined` when the input is unsafe. */
+declare function sanitizeProjectId(id: string | undefined): string | undefined;
+/** Sanitize all user-controlled text and blobs in a turn request. */
+declare function sanitizeTurnRequest(req: TurnRequest): NormalizedTurnRequest;
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest };

package/esm/src/guardrails/sanitize.js

@@ -0,0 +1,133 @@
+/**
+ * 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 { injectionSpans } from './injection.js';
+import { sensitiveSpans } from './sensitive.js';
+/** Sanitize one text value using prompt-injection and sensitive-data detectors. */
+function sanitizeText(text, options) {
+    const sanitizeInput = options?.sanitizeInput ?? true;
+    const redactSensitive = options?.redactSensitive ?? true;
+    if (!sanitizeInput && !redactSensitive) {
+        return text;
+    }
+    const spans = [
+        ...(sanitizeInput ? injectionSpans(text) : []),
+        ...(redactSensitive ? sensitiveSpans(text) : []),
+    ];
+    return applySpans(text, spans);
+}
+function sanitizeSlots(slots, options) {
+    if (!slots) {
+        return slots;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(slots)) {
+        out[key] = sanitizeText(value, options);
+    }
+    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;
+    }
+    const trimmed = id.trim().slice(0, PROJECT_ID_MAX);
+    if (!PROJECT_ID_OK.test(trimmed)) {
+        return undefined;
+    }
+    return trimmed;
+}
+function sanitizeRepair(repair, options) {
+    if (!repair) {
+        return repair;
+    }
+    return {
+        previousOutput: sanitizeText(repair.previousOutput, options),
+        rejection: sanitizeText(repair.rejection, options),
+        guidance: repair.guidance ? sanitizeText(repair.guidance, options) : undefined,
+    };
+}
+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 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,
+    };
+    const input = req.input ?? {};
+    const { toolInvoke } = req;
+    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);
+    }
+    let system = req.system;
+    if (system !== undefined) {
+        system = sanitizeText(system, options);
+    }
+    const { attachments, voice } = sanitizeTurnBlobsForProfile(req.profile, input.attachments, input.voice);
+    return {
+        ...req,
+        system,
+        projectId: sanitizeProjectId(req.projectId),
+        input: {
+            ...input,
+            text,
+            slots: sanitizeSlots(input.slots, options),
+            attachments,
+            voice,
+            repair: sanitizeRepair(input.repair, options),
+            history: sanitizeHistory(input.history, options),
+        },
+        toolInvoke: invoke,
+    };
+}
+export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest };

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

@@ -0,0 +1,12 @@
+/**
+ * Sensitive-data span detection.
+ *
+ * Detects common credentials, tokens, card numbers, SSNs, and network secrets
+ * so host profiles can redact them before provider submission.
+ *
+ * @module
+ */
+import { type RedactSpan } from '../observability/spans.js';
+/** Detect sensitive-data spans in a string. */
+declare function sensitiveSpans(text: string): RedactSpan[];
+export { sensitiveSpans };