theorum 0.1.2 → 0.1.4

package/src/guardrails/injection.ts

@@ -0,0 +1,254 @@
+/**
+ * Prompt-injection span detection.
+ *
+ * These utilities return spans that can be redacted from untrusted user text
+ * before provider submission.
+ *
+ * @module
+ */
+
+import { blobAt, type RedactSpan, spansFromPatterns } from '../observability/spans.ts';
+
+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: string): RedactSpan[] {
+  return spansFromPatterns(text, INJECTION_PATTERNS, 'injection');
+}
+
+function sortedLetters(value: string): string {
+  return [...value].sort().join('');
+}
+
+function firstLast(word: string): { first: string | undefined; last: string | undefined } {
+  return { first: word.at(0), last: word.at(-1) };
+}
+
+function isTypoglycemia(word: string, target: string): boolean {
+  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: string): string {
+  return text.replace(WORD, (word) => {
+    for (const target of TYPO_TARGETS) {
+      if (isTypoglycemia(word, target)) {
+        return target;
+      }
+    }
+    return word;
+  });
+}
+
+function isMostlyPrintable(value: string): boolean {
+  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: string): boolean {
+  if (!isMostlyPrintable(decoded)) {
+    return false;
+  }
+  return injectionSpansOn(decoded).length > 0;
+}
+
+function tryBase64(blob: string): string | undefined {
+  try {
+    return atob(blob);
+  } catch {
+    return undefined;
+  }
+}
+
+function tryHex(blob: string): string | undefined {
+  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: string,
+  pattern: RegExp,
+  decode: (blob: string) => string | undefined,
+): RedactSpan[] {
+  const spans: RedactSpan[] = [];
+  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: string): RedactSpan[] {
+  return [...encodedFrom(text, BASE64_BLOB, tryBase64), ...encodedFrom(text, HEX_BLOB, tryHex)];
+}
+
+function spacedSpans(text: string): RedactSpan[] {
+  const spans: RedactSpan[] = [];
+  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: string): RedactSpan[] {
+  const shadow = typoNormalize(text);
+  let typo: RedactSpan[] = [];
+  if (shadow !== text) {
+    typo = injectionSpansOn(shadow);
+  }
+  return [...injectionSpansOn(text), ...typo, ...encodedSpans(text), ...spacedSpans(text)];
+}
+
+export { injectionSpans };

package/src/guardrails/mod.ts

@@ -0,0 +1,40 @@
+/**
+ * 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
+ */
+
+export {
+  PUBLIC_ACTION,
+  PUBLIC_CANARY,
+  PUBLIC_FILE_COUNT,
+  PUBLIC_FILE_SIZE,
+  PUBLIC_FILE_TYPE,
+  PUBLIC_GENERIC,
+  PUBLIC_IMAGE_SIZE,
+  PUBLIC_UNAVAILABLE,
+  publicError,
+  TheorumError,
+  UPSTREAM_FAILED,
+} from './error.ts';
+export { injectionSpans } from './injection.ts';
+export type { QuotaSlotStatus } from './quota.ts';
+export {
+  clientIp,
+  quotaMessage,
+  releaseSlot,
+  resetSlots,
+  skipQuota,
+  takeSlot,
+} from './quota.ts';
+export {
+  PROJECT_ID_MAX,
+  sanitizeProjectId,
+  sanitizeText,
+  sanitizeTurnRequest,
+} from './sanitize.ts';
+export { sensitiveSpans } from './sensitive.ts';

package/src/guardrails/quota.ts

@@ -0,0 +1,87 @@
+import type { Profile } from '../kernel/types.ts';
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+
+interface Slot {
+  day: string;
+  count: number;
+  busy: boolean;
+}
+
+type QuotaSlotStatus = 'ok' | 'busy' | 'quota' | 'not_configured';
+
+const slots = new Map<string, Slot>();
+
+function utcDay(now: number): string {
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function isLoopback(peer: string): boolean {
+  return LOOPBACK.has(peer);
+}
+
+function cfConnectingIp(req: Request): string {
+  return req.headers.get('cf-connecting-ip')?.trim() ?? '';
+}
+
+function slotKey(profileId: string, ip: string): string {
+  return `${profileId}:${ip}`;
+}
+
+function skipQuota(peer: string, req: Request): boolean {
+  return isLoopback(peer) && !cfConnectingIp(req);
+}
+
+function clientIp(peer: string, req: Request): string {
+  if (isLoopback(peer)) {
+    const cf = cfConnectingIp(req);
+    if (cf) {
+      return cf;
+    }
+  }
+  if (peer) {
+    return peer;
+  }
+  return 'unknown';
+}
+
+function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus {
+  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: Profile, ip: string): void {
+  const slot = slots.get(slotKey(profile.id, ip));
+  if (slot) {
+    slot.busy = false;
+  }
+}
+
+function quotaMessage(profile: Profile): string {
+  return `Enjoying ${profile.identity.handle}? You've reached today's limit`;
+}
+
+function resetSlots(): void {
+  slots.clear();
+}
+
+export type { QuotaSlotStatus };
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };

package/src/guardrails/sanitize.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.ts';
+import { sanitizeTurnBlobsForProfile } from '../kernel/registry/attachments.ts';
+import { getProfile } from '../kernel/registry/profiles.ts';
+import type { NormalizedTurnRequest, TurnRequest } from '../kernel/types.ts';
+import { applySpans } from '../observability/spans.ts';
+import { injectionSpans } from './injection.ts';
+import { sensitiveSpans } from './sensitive.ts';
+
+/** Sanitize one text value using prompt-injection and sensitive-data detectors. */
+function sanitizeText(
+  text: string,
+  options?: { sanitizeInput?: boolean; redactSensitive?: boolean },
+): string {
+  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: Record<string, string> | undefined,
+  options?: { sanitizeInput?: boolean; redactSensitive?: boolean },
+): Record<string, string> | undefined {
+  if (!slots) {
+    return slots;
+  }
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(slots)) {
+    out[key] = sanitizeText(value, options);
+  }
+  return out;
+}
+
+function sanitizeArgs(
+  args: Record<string, unknown>,
+  options?: { sanitizeInput?: boolean; redactSensitive?: boolean },
+): Record<string, unknown> {
+  const next = mapStrings(args, (t) => sanitizeText(t, options));
+  if (next && typeof next === 'object' && !Array.isArray(next)) {
+    return next as Record<string, unknown>;
+  }
+  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: string | undefined): string | undefined {
+  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: import('../kernel/types.ts').TurnRepairRequest | undefined,
+  options?: { sanitizeInput?: boolean; redactSensitive?: boolean },
+): import('../kernel/types.ts').TurnRepairRequest | undefined {
+  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: import('../kernel/types.ts').TurnHistoryMessage[] | undefined,
+  options?: { sanitizeInput?: boolean; redactSensitive?: boolean },
+): import('../kernel/types.ts').TurnHistoryMessage[] | undefined {
+  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: TurnRequest): NormalizedTurnRequest {
+  let profileGuardrails: { sanitizeInput?: boolean; redactSensitive?: boolean } | undefined;
+  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/src/guardrails/sensitive.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 { blobAt, type RedactSpan, spansFromPatterns } from '../observability/spans.ts';
+
+const SSN = /\b\d{3}-\d{2}-\d{4}\b/g;
+const ITIN = /\b9\d{2}-\d{2}-\d{4}\b/g;
+const EIN = /\b\d{2}-\d{7}\b/g;
+const IBAN = /\b[A-Z]{2}\d{2}[A-Z0-9]{13,30}\b/g;
+const IPV4 = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g;
+const IPV6 = /\b(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}\b/gi;
+const AWS_ACCESS = /\bAKIA[0-9A-Z]{16}\b/g;
+const GOOGLE_API = /\bAIza[0-9A-Za-z_-]{35}\b/g;
+const OPENAI_KEY = /\bsk-[A-Za-z0-9]{20,}\b/g;
+const ANTHROPIC_KEY = /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g;
+const OPENROUTER_KEY = /\bsk-or-[A-Za-z0-9_-]{20,}\b/g;
+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;
+const CARD_CANDIDATE = /\b(?:\d[ -]*?){13,19}\b/g;
+
+const KEY_PATTERNS = [
+  SSN,
+  ITIN,
+  EIN,
+  IBAN,
+  IPV4,
+  IPV6,
+  AWS_ACCESS,
+  GOOGLE_API,
+  OPENAI_KEY,
+  ANTHROPIC_KEY,
+  OPENROUTER_KEY,
+  GITHUB_PAT,
+  GITHUB_TOKEN,
+  SLACK_TOKEN,
+  BEARER,
+  PEM_KEY,
+];
+
+const LUHN_DOUBLE = 2;
+const LUHN_NINE = 9;
+const LUHN_TEN = 10;
+const CARD_MIN_DIGITS = 13;
+const CARD_MAX_DIGITS = 19;
+
+function luhnOk(digits: string): boolean {
+  let sum = 0;
+  let doubleIt = false;
+  for (let i = digits.length - 1; i >= 0; i -= 1) {
+    const ch = digits[i];
+    if (ch === undefined) {
+      return false;
+    }
+    let n = Number(ch);
+    if (doubleIt) {
+      n *= LUHN_DOUBLE;
+      if (n > LUHN_NINE) {
+        n -= LUHN_NINE;
+      }
+    }
+    sum += n;
+    doubleIt = !doubleIt;
+  }
+  return sum % LUHN_TEN === 0;
+}
+
+function cardSpans(text: string): RedactSpan[] {
+  const spans: RedactSpan[] = [];
+  for (const match of text.matchAll(CARD_CANDIDATE)) {
+    const found = blobAt(match);
+    if (found) {
+      const digits = found.blob.replaceAll(/[^\d]/g, '');
+      const inRange = digits.length >= CARD_MIN_DIGITS && digits.length <= CARD_MAX_DIGITS;
+      if (inRange && luhnOk(digits)) {
+        spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'sensitive' });
+      }
+    }
+  }
+  return spans;
+}
+
+/** Detect sensitive-data spans in a string. */
+function sensitiveSpans(text: string): RedactSpan[] {
+  return [...spansFromPatterns(text, KEY_PATTERNS, 'sensitive'), ...cardSpans(text)];
+}
+
+export { sensitiveSpans };

package/src/host/mint-trace.ts

@@ -0,0 +1,54 @@
+/**
+ * Host cutout-trace helpers for apps that mint a final audit row after an
+ * upstream side effect (for example image cutout).
+ *
+ * Prefer importing from `theorum/host`.
+ *
+ * @module
+ */
+
+import { publicError, UPSTREAM_FAILED } from '../guardrails/error.ts';
+import { noopSink, type TraceSink, writeTrace } from '../observability/trace.ts';
+import type { TraceRecord } from '../observability/trace-record.ts';
+
+interface CutoutTape {
+  ok: boolean;
+  ms: number;
+  url?: string;
+  inSha256?: string;
+  outSha256?: string;
+  http?: unknown;
+  error?: string;
+}
+
+function attachMint(row: TraceRecord, app: Record<string, unknown>, cutout: CutoutTape): void {
+  row.app = app;
+  row.cutout = cutout;
+  row.ms = Date.now() - row.ts;
+  if (!cutout.ok) {
+    row.ok = false;
+    const { error: cutoutError } = cutout;
+    let error = cutoutError;
+    if (!error) {
+      error = publicError(UPSTREAM_FAILED);
+    }
+    row.error = error;
+  }
+}
+
+async function flushMintTrace(args: {
+  held: TraceRecord[];
+  app: Record<string, unknown>;
+  cutout: CutoutTape;
+  sink?: TraceSink;
+}): Promise<void> {
+  const [row] = args.held;
+  if (!row) {
+    return;
+  }
+  attachMint(row, args.app, args.cutout);
+  await writeTrace(args.sink ?? noopSink(), Promise.resolve(row));
+}
+
+export type { CutoutTape };
+export { flushMintTrace };