@jamaynor/hal-config 1.0.1

package/security/redactor.js

@@ -0,0 +1,129 @@
+/**
+ * security/redactor.js
+ *
+ * Responsibility: Strip secrets and PII from outbound text before delivery.
+ * All functions are pure: no side effects, no I/O, no API calls.
+ *
+ * Public Interface:
+ * redactor
+ * ├── redactSecrets(text) → string
+ * ├── redactPii(text, config) → string
+ * └── redactNotification(text, config) → string
+ */
+
+// Secret patterns covering 8+ common API key and auth token formats.
+const SECRET_PATTERNS = [
+  // OpenAI  (sk-... and sk-proj-...)
+  /sk-(?:proj-)?[A-Za-z0-9_-]{20,}/g,
+  // Google API keys
+  /AIza[0-9A-Za-z_-]{35}/g,
+  // xAI keys (xai-...)
+  /xai-[A-Za-z0-9_-]{20,}/g,
+  // Slack bot and user tokens
+  /xox[bpoa]-[0-9A-Za-z-]{10,}/g,
+  // GitHub personal access tokens (classic and fine-grained)
+  /gh[pousr]_[A-Za-z0-9_]{36,}/g,
+  // Telegram bot tokens  (<digits>:<alphanumeric>)
+  /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/g,
+  // Generic Bearer tokens in Authorization header format
+  /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi,
+  // Generic long hex secrets (32–64 hex chars preceded by a word boundary)
+  /\b[0-9a-fA-F]{32,64}\b/g,
+];
+
+const REDACTED_SECRET = '[REDACTED_SECRET]';
+const REDACTED_EMAIL = '[REDACTED_EMAIL]';
+const REDACTED_PHONE = '[REDACTED_PHONE]';
+const REDACTED_AMOUNT = '[REDACTED_AMOUNT]';
+
+// Default list of personal email providers whose addresses are treated as PII.
+const DEFAULT_PERSONAL_PROVIDERS = [
+  'gmail.com',
+  'yahoo.com',
+  'hotmail.com',
+  'outlook.com',
+  'icloud.com',
+  'protonmail.com',
+];
+
+// Phone number patterns covering common North American and international formats.
+const PHONE_PATTERNS = [
+  // (NNN) NNN-NNNN  or  NNN-NNN-NNNN
+  /\(?\d{3}\)?[\s.-]?\d{3}[\s.-]\d{4}/g,
+  // 1-800-NNN-NNNN  (toll-free with country code)
+  /1[-.\s]\d{3}[-.\s]\d{3}[-.\s]\d{4}/g,
+  // +1 NNN NNN NNNN  (E.164-style)
+  /\+\d{1,3}[\s.-]\d{3}[\s.-]\d{3}[\s.-]\d{4}/g,
+];
+
+const DOLLAR_AMOUNT_PATTERN = /\$\d[\d,]*(?:\.\d{2})?/g;
+
+/**
+ * Resolve the personal provider list from config, falling back to the default list.
+ * @param {object} config - Skill config object (may be undefined/empty).
+ * @returns {string[]} Array of lowercase domain strings.
+ */
+function resolveProviders(config) {
+  return config?.redactor?.personalEmailProviders ?? DEFAULT_PERSONAL_PROVIDERS;
+}
+
+/**
+ * Build a regex that matches email addresses whose domain is one of the personal providers.
+ * @param {string[]} providers - Array of domain strings.
+ * @returns {RegExp}
+ */
+function buildPersonalEmailPattern(providers) {
+  const escapedDomains = providers.map((d) => d.replace(/\./g, '\\.'));
+  const domainAlternation = escapedDomains.join('|');
+  return new RegExp(`[A-Za-z0-9._%+\\-]+@(?:${domainAlternation})`, 'gi');
+}
+
+/**
+ * Replace all recognized API key and auth token patterns with [REDACTED_SECRET].
+ * Pure function — returns a new string; does not mutate input.
+ * @param {string} text
+ * @returns {string}
+ */
+export function redactSecrets(text) {
+  let result = text;
+  for (const pattern of SECRET_PATTERNS) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, REDACTED_SECRET);
+  }
+  return result;
+}
+
+/**
+ * Replace personal email addresses, phone numbers, and dollar amounts with
+ * their respective placeholders. Work-domain addresses are not affected.
+ * Pure function — returns a new string; does not mutate input.
+ * @param {string} text
+ * @param {object} config - Skill config (may be undefined/empty).
+ * @returns {string}
+ */
+export function redactPii(text, config) {
+  const providers = resolveProviders(config);
+  const personalEmailPattern = buildPersonalEmailPattern(providers);
+
+  let result = text.replace(personalEmailPattern, REDACTED_EMAIL);
+
+  for (const pattern of PHONE_PATTERNS) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, REDACTED_PHONE);
+  }
+
+  result = result.replace(DOLLAR_AMOUNT_PATTERN, REDACTED_AMOUNT);
+
+  return result;
+}
+
+/**
+ * Chain redactSecrets then redactPii in a single call.
+ * Pure function — returns a new string; does not mutate input.
+ * @param {string} text
+ * @param {object} config - Skill config (may be undefined/empty).
+ * @returns {string}
+ */
+export function redactNotification(text, config) {
+  return redactPii(redactSecrets(text), config);
+}

package/security/sanitizer.js

@@ -0,0 +1,571 @@
+/**
+ * security/sanitizer.js
+ *
+ * Responsibility: Deterministic text sanitizer — synchronous 11-step pipeline
+ * that strips injection vectors from untrusted string fields before any LLM sees them.
+ * Returns cleaned text alongside per-step detection stats. Makes no API calls.
+ * Never blocks; blocking decisions belong to the ingestion gate.
+ *
+ * CAVEAT: Unicode stripping is aggressive and optimized for English-language workloads.
+ * Emoji-heavy or multilingual input may have legitimate characters stripped. Use a
+ * more selective configuration for non-English workloads.
+ *
+ * Public Interface:
+ * sanitizer
+ * └── sanitize(text, opts?) → { cleaned: string, stats: SanitizeStats }
+ *
+ * SanitizeStats:
+ * {
+ *   invisibleStripped:     number,
+ *   walletDrainStripped:   number,
+ *   lookalikesNormalized:  number,
+ *   tokenBudgetTruncated:  boolean,
+ *   encodingsDecoded:      number,
+ *   anomalyFlagged:        boolean,
+ *   patternMatches: {
+ *     roleMarkers:         number,
+ *     jailbreakCommands:   number,
+ *     overridePhrases:     number,
+ *   },
+ *   codeBlocksStripped:    number,
+ *   hardLimitTruncated:    boolean,
+ * }
+ */
+
+// ---------------------------------------------------------------------------
+// Default configuration — overridden by opts passed to sanitize()
+// ---------------------------------------------------------------------------
+const DEFAULTS = {
+  tokenBudget: 2000,
+  hardCharLimit: 20_000,
+  anomalySigmaThreshold: 3.0,
+};
+
+// ---------------------------------------------------------------------------
+// Step 1 — Invisible character sets
+// Zero-width joiners, non-joiners, non-breaking spaces, soft hyphens, etc.
+// ---------------------------------------------------------------------------
+const INVISIBLE_CHARS_REGEX = new RegExp(
+  '[' +
+    '\u00AD' +   // soft hyphen
+    '\u200B' +   // zero-width space
+    '\u200C' +   // zero-width non-joiner
+    '\u200D' +   // zero-width joiner
+    '\u200E' +   // left-to-right mark
+    '\u200F' +   // right-to-left mark
+    '\u2028' +   // line separator
+    '\u2029' +   // paragraph separator
+    '\u202A' +   // left-to-right embedding
+    '\u202B' +   // right-to-left embedding
+    '\u202C' +   // pop directional formatting
+    '\u202D' +   // left-to-right override
+    '\u202E' +   // right-to-left override
+    '\u2060' +   // word joiner
+    '\u2061' +   // function application
+    '\u2062' +   // invisible times
+    '\u2063' +   // invisible separator
+    '\u2064' +   // invisible plus
+    '\uFEFF' +   // zero-width no-break space (BOM)
+    '\u180E' +   // mongolian vowel separator
+    '\u00A0' +   // non-breaking space
+  ']',
+  'g'
+);
+
+// ---------------------------------------------------------------------------
+// Step 2 — Wallet-drain characters (TOKEN80M8/TOKENADE catalog)
+// Unicode code points known to tokenize to 3–10+ tokens each, inflating
+// API cost dramatically when included in bulk.
+// ---------------------------------------------------------------------------
+const WALLET_DRAIN_RANGES = [
+  [0x1F300, 0x1F9FF],  // Misc symbols, emoticons, transport, maps, supplemental
+  [0x2600,  0x27BF],   // Misc symbols, dingbats
+  [0x2B50,  0x2BFF],   // Misc symbols and arrows
+  [0x3000,  0x303F],   // CJK symbols and punctuation
+  [0x3040,  0x309F],   // Hiragana
+  [0x30A0,  0x30FF],   // Katakana
+  [0x4E00,  0x9FFF],   // CJK unified ideographs (common)
+  [0xAC00,  0xD7AF],   // Hangul syllables
+  [0xFFF0,  0xFFFF],   // Specials (object replacement, etc.)
+  [0x10000, 0x1007F],  // Linear B syllabary
+  [0x1D400, 0x1D7FF],  // Mathematical alphanumeric symbols (high token cost)
+  [0x1EE00, 0x1EEFF],  // Arabic mathematical alphabetic symbols
+];
+
+function isWalletDrainCodePoint(cp) {
+  for (const [lo, hi] of WALLET_DRAIN_RANGES) {
+    if (cp >= lo && cp <= hi) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Step 3 — Lookalike normalization (~40 non-Latin → ASCII pairs)
+// Covers Cyrillic, Greek, and fullwidth Latin lookalikes most commonly used
+// to bypass ASCII-only pattern matching.
+// ---------------------------------------------------------------------------
+const LOOKALIKE_MAP = {
+  // Cyrillic lookalikes
+  '\u0410': 'A',  // А
+  '\u0412': 'B',  // В
+  '\u0421': 'C',  // С
+  '\u0415': 'E',  // Е
+  '\u041D': 'H',  // Н
+  '\u0406': 'I',  // І
+  '\u0408': 'J',  // Ј
+  '\u041A': 'K',  // К
+  '\u041C': 'M',  // М
+  '\u041E': 'O',  // О
+  '\u0420': 'R',  // Р
+  '\u0422': 'T',  // Т
+  '\u0425': 'X',  // Х
+  '\u0423': 'Y',  // У
+  '\u0430': 'a',  // а
+  '\u0441': 'c',  // с
+  '\u0435': 'e',  // е
+  '\u0456': 'i',  // і
+  '\u0458': 'j',  // ј
+  '\u043E': 'o',  // о
+  '\u0440': 'r',  // р
+  '\u0455': 's',  // ѕ  ← Cyrillic-S specifically called out in task spec
+  '\u0443': 'u',  // у
+  '\u0445': 'x',  // х
+  // Greek lookalikes
+  '\u0391': 'A',  // Α
+  '\u0392': 'B',  // Β
+  '\u0395': 'E',  // Ε
+  '\u0396': 'Z',  // Ζ
+  '\u0397': 'H',  // Η
+  '\u0399': 'I',  // Ι
+  '\u039A': 'K',  // Κ
+  '\u039C': 'M',  // Μ
+  '\u039D': 'N',  // Ν
+  '\u039F': 'O',  // Ο
+  '\u03A1': 'R',  // Ρ
+  '\u03A4': 'T',  // Τ
+  '\u03A7': 'X',  // Χ
+  '\u03B1': 'a',  // α
+  '\u03B2': 'b',  // β (approx)
+  '\u03B5': 'e',  // ε
+  '\u03B7': 'n',  // η (approx)
+  '\u03B9': 'i',  // ι
+  '\u03BF': 'o',  // ο
+  '\u03C1': 'p',  // ρ (approx)
+  '\u03C5': 'u',  // υ
+  '\u03C7': 'x',  // χ
+  // Fullwidth Latin (Unicode "full-width" equivalents)
+  '\uFF21': 'A', '\uFF22': 'B', '\uFF23': 'C', '\uFF24': 'D', '\uFF25': 'E',
+  '\uFF26': 'F', '\uFF27': 'G', '\uFF28': 'H', '\uFF29': 'I', '\uFF2A': 'J',
+  '\uFF2B': 'K', '\uFF2C': 'L', '\uFF2D': 'M', '\uFF2E': 'N', '\uFF2F': 'O',
+  '\uFF30': 'P', '\uFF31': 'Q', '\uFF32': 'R', '\uFF33': 'S', '\uFF34': 'T',
+  '\uFF35': 'U', '\uFF36': 'V', '\uFF37': 'W', '\uFF38': 'X', '\uFF39': 'Y',
+  '\uFF3A': 'Z',
+  '\uFF41': 'a', '\uFF42': 'b', '\uFF43': 'c', '\uFF44': 'd', '\uFF45': 'e',
+  '\uFF46': 'f', '\uFF47': 'g', '\uFF48': 'h', '\uFF49': 'i', '\uFF4A': 'j',
+  '\uFF4B': 'k', '\uFF4C': 'l', '\uFF4D': 'm', '\uFF4E': 'n', '\uFF4F': 'o',
+  '\uFF50': 'p', '\uFF51': 'q', '\uFF52': 'r', '\uFF53': 's', '\uFF54': 't',
+  '\uFF55': 'u', '\uFF56': 'v', '\uFF57': 'w', '\uFF58': 'x', '\uFF59': 'y',
+  '\uFF5A': 'z',
+};
+
+const LOOKALIKE_REGEX = new RegExp(
+  Object.keys(LOOKALIKE_MAP).join('|'),
+  'g'
+);
+
+// ---------------------------------------------------------------------------
+// Step 4 — Token budget: rough estimate at ~4 chars/token for ASCII prose
+// ---------------------------------------------------------------------------
+const CHARS_PER_TOKEN = 4;
+
+// ---------------------------------------------------------------------------
+// Step 5 — Combining mark cleanup
+// Unicode combining diacritics range: U+0300–U+036F
+// Strip any base character that has more than 2 combining marks following it.
+// ---------------------------------------------------------------------------
+const COMBINING_MARK_REGEX = /\u0300-\u036F/;
+
+// ---------------------------------------------------------------------------
+// Step 6 — Encoding decode helpers
+// ---------------------------------------------------------------------------
+const HTML_ENTITY_REGEX = /&#(\d+);|&#x([0-9a-fA-F]+);|&([a-zA-Z]+);/g;
+const BASE64_BLOCK_REGEX = /(?:[A-Za-z0-9+/]{4}){4,}(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?/g;
+const PERCENT_ENCODED_REGEX = /%[0-9A-Fa-f]{2}/g;
+const HEX_BLOCK_REGEX = /\\x[0-9A-Fa-f]{2}/g;
+
+const HTML_NAMED_ENTITIES = {
+  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+};
+
+function decodeHtmlEntities(text) {
+  return text.replace(HTML_ENTITY_REGEX, (match, dec, hex, named) => {
+    if (dec) return String.fromCodePoint(parseInt(dec, 10));
+    if (hex) return String.fromCodePoint(parseInt(hex, 16));
+    if (named) return HTML_NAMED_ENTITIES[named.toLowerCase()] ?? match;
+    return match;
+  });
+}
+
+function tryBase64Decode(candidate) {
+  try {
+    const decoded = Buffer.from(candidate, 'base64').toString('utf8');
+    // Only accept if decoded result is printable ASCII-like text
+    if (/^[\x20-\x7E\n\r\t]+$/.test(decoded) && decoded.length < candidate.length) {
+      return decoded;
+    }
+  } catch {
+    // not valid base64
+  }
+  return null;
+}
+
+function decodePercentEncoded(text) {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+}
+
+function decodeHexEscapes(text) {
+  return text.replace(HEX_BLOCK_REGEX, (match) => {
+    return String.fromCodePoint(parseInt(match.slice(2), 16));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Step 7 — Statistical anomaly detection
+// Computes character category distribution and flags if any category
+// deviates beyond sigma threshold from expected English prose baseline.
+// ---------------------------------------------------------------------------
+// Expected proportions in English prose (approximate)
+const EXPECTED_DIST = {
+  lowercase: 0.60,
+  uppercase: 0.05,
+  digit: 0.04,
+  space: 0.15,
+  punctuation: 0.08,
+  other: 0.08,
+};
+
+function charCategory(ch) {
+  const cp = ch.codePointAt(0);
+  if (cp >= 0x61 && cp <= 0x7A) return 'lowercase';
+  if (cp >= 0x41 && cp <= 0x5A) return 'uppercase';
+  if (cp >= 0x30 && cp <= 0x39) return 'digit';
+  if (cp === 0x20 || cp === 0x09 || cp === 0x0A || cp === 0x0D) return 'space';
+  if (cp >= 0x21 && cp <= 0x2F) return 'punctuation';
+  if (cp >= 0x3A && cp <= 0x40) return 'punctuation';
+  if (cp >= 0x5B && cp <= 0x60) return 'punctuation';
+  if (cp >= 0x7B && cp <= 0x7E) return 'punctuation';
+  return 'other';
+}
+
+function detectAnomaly(text, sigmaThreshold) {
+  if (text.length === 0) return false;
+
+  const counts = { lowercase: 0, uppercase: 0, digit: 0, space: 0, punctuation: 0, other: 0 };
+  for (const ch of text) {
+    counts[charCategory(ch)]++;
+  }
+
+  const total = text.length;
+  for (const [cat, expected] of Object.entries(EXPECTED_DIST)) {
+    const observed = counts[cat] / total;
+    const stdDev = Math.sqrt(expected * (1 - expected) / total);
+    if (stdDev === 0) continue;
+    const sigma = Math.abs(observed - expected) / stdDev;
+    if (sigma > sigmaThreshold) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Step 8 — Pattern matching
+// L1B3RT4S jailbreak catalog: role markers, jailbreak commands, override phrases
+// ---------------------------------------------------------------------------
+const ROLE_MARKER_PATTERNS = [
+  /\bSystem\s*:/gi,
+  /\bUser\s*:/gi,
+  /\bAssistant\s*:/gi,
+  /\[SYSTEM\]/gi,
+  /\[USER\]/gi,
+  /\[ASSISTANT\]/gi,
+  /<\s*system\s*>/gi,
+  /<\s*user\s*>/gi,
+  /<\s*assistant\s*>/gi,
+];
+
+const JAILBREAK_COMMAND_PATTERNS = [
+  /L1B3RT4S/gi,
+  /DAN\s+mode/gi,
+  /jailbreak/gi,
+  /do\s+anything\s+now/gi,
+  /you\s+are\s+now\s+in\s+(?:developer|debug|admin|god|unrestricted)\s+mode/gi,
+  /pretend\s+you\s+(?:have\s+no\s+restrictions|are\s+(?:an?\s+)?(?:evil|uncensored|unfiltered))/gi,
+  /act\s+as\s+(?:an?\s+)?(?:uncensored|unfiltered|evil|unrestricted)/gi,
+  /\[?JAILBREAK\]?/gi,
+  /opposite\s+mode/gi,
+  /token\s*ade/gi,
+  /TOKEN80M8/gi,
+  /P4RS3LT0NGV3/gi,
+  /grandma\s+exploit/gi,
+  /virtual\s+(?:AI|assistant|LLM)\s+with\s+no\s+restrictions/gi,
+];
+
+const OVERRIDE_PHRASE_PATTERNS = [
+  /ignore\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+instructions/gi,
+  /disregard\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+instructions/gi,
+  /forget\s+(?:all\s+)?(?:previous|prior|above|earlier)\s+instructions/gi,
+  /override\s+(?:your\s+)?(?:instructions|programming|directives|constraints|safety)/gi,
+  /new\s+(?:primary\s+)?(?:instructions|directive|objective|mission|goal)\s*:/gi,
+  /you\s+are\s+now\s+in\s+(?:audit|maintenance|debug|developer)\s+mode/gi,
+  /your\s+(?:true|real|actual)\s+(?:instructions|purpose|mission|goal)\s+(?:is|are)/gi,
+  /send\s+me\s+(?:your\s+)?(?:hidden\s+)?(?:prompt|api\s+key|secret)/gi,
+  /reveal\s+(?:your\s+)?(?:system\s+prompt|instructions|context|api\s+key)/gi,
+  /print\s+(?:your\s+)?(?:system\s+prompt|instructions)/gi,
+  /what\s+(?:are|were)\s+your\s+(?:original\s+)?instructions/gi,
+  /translate\s+(?:your\s+)?(?:system\s+)?(?:prompt|instructions)\s+to/gi,
+];
+
+function countPatternMatches(text, patterns) {
+  let count = 0;
+  for (const pattern of patterns) {
+    const matches = text.match(pattern);
+    if (matches) count += matches.length;
+    // Reset lastIndex for global regex after match
+    pattern.lastIndex = 0;
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Step 9 — Code block stripping
+// ---------------------------------------------------------------------------
+const CODE_BLOCK_REGEX = /```[\s\S]*?```|~~~[\s\S]*?~~~/g;
+
+// ---------------------------------------------------------------------------
+// Core steps — run on a text string, mutating stats in place
+// Returning the transformed text after each step.
+// ---------------------------------------------------------------------------
+
+function step1_stripInvisible(text, stats) {
+  const before = text.length;
+  const cleaned = text.replace(INVISIBLE_CHARS_REGEX, '');
+  stats.invisibleStripped += before - cleaned.length;
+  return cleaned;
+}
+
+function step2_stripWalletDrain(text, stats) {
+  let cleaned = '';
+  let stripped = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    if (isWalletDrainCodePoint(cp)) {
+      stripped++;
+    } else {
+      cleaned += ch;
+    }
+  }
+  stats.walletDrainStripped += stripped;
+  return cleaned;
+}
+
+function step3_normalizeLookalikes(text, stats) {
+  let normalized = 0;
+  const cleaned = text.replace(LOOKALIKE_REGEX, (match) => {
+    const replacement = LOOKALIKE_MAP[match];
+    if (replacement !== undefined) {
+      normalized++;
+      return replacement;
+    }
+    return match;
+  });
+  stats.lookalikesNormalized += normalized;
+  return cleaned;
+}
+
+function step4_enforceTokenBudget(text, stats, budget) {
+  const estimatedTokens = Math.ceil(text.length / CHARS_PER_TOKEN);
+  if (estimatedTokens <= budget) return text;
+  const maxChars = budget * CHARS_PER_TOKEN;
+  stats.tokenBudgetTruncated = true;
+  return text.slice(0, maxChars);
+}
+
+function step5_cleanCombiningMarks(text) {
+  // Decompose to NFD so combining marks are separate code points,
+  // then strip excess marks (more than 2 consecutive combining marks per base char).
+  const nfd = text.normalize('NFD');
+  let result = '';
+  let markCount = 0;
+  for (const ch of nfd) {
+    const cp = ch.codePointAt(0);
+    const isCombining = cp >= 0x0300 && cp <= 0x036F;
+    if (isCombining) {
+      markCount++;
+      if (markCount <= 2) result += ch;
+    } else {
+      markCount = 0;
+      result += ch;
+    }
+  }
+  // Re-compose to NFC
+  return result.normalize('NFC');
+}
+
+function step6_decodeEncodings(text, stats, runSteps1to5) {
+  let decoded = text;
+  let decodings = 0;
+
+  // HTML entities
+  const afterEntities = decodeHtmlEntities(decoded);
+  if (afterEntities !== decoded) {
+    decodings++;
+    decoded = afterEntities;
+  }
+
+  // Hex escape sequences (\xNN)
+  const afterHex = decodeHexEscapes(decoded);
+  if (afterHex !== decoded) {
+    decodings++;
+    decoded = afterHex;
+  }
+
+  // Percent-encoded sequences (%NN)
+  const afterPercent = decodePercentEncoded(decoded);
+  if (afterPercent !== decoded) {
+    decodings++;
+    decoded = afterPercent;
+  }
+
+  // Base64 blocks — replace only when decoded result looks like readable text
+  const afterBase64 = decoded.replace(BASE64_BLOCK_REGEX, (match) => {
+    const result = tryBase64Decode(match);
+    if (result) {
+      decodings++;
+      return result;
+    }
+    return match;
+  });
+  decoded = afterBase64;
+
+  stats.encodingsDecoded += decodings;
+
+  // Re-run steps 1–5 on decoded content if anything changed
+  if (decodings > 0) {
+    decoded = runSteps1to5(decoded);
+  }
+
+  return decoded;
+}
+
+function step7_detectAnomaly(text, stats, sigmaThreshold) {
+  if (detectAnomaly(text, sigmaThreshold)) {
+    stats.anomalyFlagged = true;
+  }
+  return text;
+}
+
+function step8_matchPatterns(text, stats) {
+  stats.patternMatches.roleMarkers += countPatternMatches(text, ROLE_MARKER_PATTERNS);
+  stats.patternMatches.jailbreakCommands += countPatternMatches(text, JAILBREAK_COMMAND_PATTERNS);
+  stats.patternMatches.overridePhrases += countPatternMatches(text, OVERRIDE_PHRASE_PATTERNS);
+  return text;
+}
+
+function step9_stripCodeBlocks(text, stats) {
+  let count = 0;
+  const cleaned = text.replace(CODE_BLOCK_REGEX, () => {
+    count++;
+    return '';
+  });
+  stats.codeBlocksStripped += count;
+  return cleaned;
+}
+
+function step10_hardCharLimit(text, stats, hardLimit) {
+  if (text.length <= hardLimit) return text;
+  stats.hardLimitTruncated = true;
+  return text.slice(0, hardLimit);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * sanitize(text, opts?) — synchronous 11-step sanitization pipeline.
+ *
+ * opts: {
+ *   tokenBudget?: number          — max estimated tokens; default 2000
+ *   hardCharLimit?: number        — max character count; default 20000
+ *   anomalySigmaThreshold?: number — sigma deviation threshold; default 3.0
+ * }
+ *
+ * Returns:
+ * {
+ *   cleaned: string,
+ *   stats: {
+ *     invisibleStripped, walletDrainStripped, lookalikesNormalized,
+ *     tokenBudgetTruncated, encodingsDecoded, anomalyFlagged,
+ *     patternMatches: { roleMarkers, jailbreakCommands, overridePhrases },
+ *     codeBlocksStripped, hardLimitTruncated
+ *   }
+ * }
+ */
+export function sanitize(text, opts = {}) {
+  const tokenBudget = opts.tokenBudget ?? DEFAULTS.tokenBudget;
+  const hardCharLimit = opts.hardCharLimit ?? DEFAULTS.hardCharLimit;
+  const anomalySigmaThreshold = opts.anomalySigmaThreshold ?? DEFAULTS.anomalySigmaThreshold;
+
+  const stats = {
+    invisibleStripped: 0,
+    walletDrainStripped: 0,
+    lookalikesNormalized: 0,
+    tokenBudgetTruncated: false,
+    encodingsDecoded: 0,
+    anomalyFlagged: false,
+    patternMatches: {
+      roleMarkers: 0,
+      jailbreakCommands: 0,
+      overridePhrases: 0,
+    },
+    codeBlocksStripped: 0,
+    hardLimitTruncated: false,
+  };
+
+  if (typeof text !== 'string' || text.length === 0) {
+    return { cleaned: text ?? '', stats };
+  }
+
+  // Steps 1–5 as a composable inner function, used by step 6 for re-checking
+  function runSteps1to5(input) {
+    let t = step1_stripInvisible(input, stats);
+    t = step2_stripWalletDrain(t, stats);
+    t = step3_normalizeLookalikes(t, stats);
+    t = step4_enforceTokenBudget(t, stats, tokenBudget);
+    t = step5_cleanCombiningMarks(t);
+    return t;
+  }
+
+  let cleaned = runSteps1to5(text);
+
+  // Step 6 — decode encodings and re-run steps 1–5 on decoded content
+  cleaned = step6_decodeEncodings(cleaned, stats, runSteps1to5);
+
+  // Step 7 — statistical anomaly detection (non-mutating; sets flag only)
+  step7_detectAnomaly(cleaned, stats, anomalySigmaThreshold);
+
+  // Step 8 — pattern matching (non-mutating; records counts only)
+  step8_matchPatterns(cleaned, stats);
+
+  // Step 9 — strip fenced code blocks
+  cleaned = step9_stripCodeBlocks(cleaned, stats);
+
+  // Step 10 — hard character limit fallback
+  cleaned = step10_hardCharLimit(cleaned, stats, hardCharLimit);
+
+  // Step 11 — return cleaned text and stats
+  return { cleaned, stats };
+}