agent-sanitizer 2.27.0 → 2.28.1

package/README.md

@@ -35,6 +35,10 @@ const { cleaned, found, warnings, notes } = await sanitize(untrustedText);
 
 // Opt into the HTML layers for web ingress (lazy-loads ~200 ms of deps):
 const result = await sanitize(pageSource, { html: true });
+
+// Layer 3 alone: flag exfil-shaped URLs without splicing anything (for text
+// that must stay byte-faithful, e.g. a PR diff). Implied by `html: true`.
+const scanned = await sanitize(diffText, { exfilScan: true });
 ```
 
 `sanitize` never throws and never silently drops content—any change comes with

package/bin/sanitize-cli.mjs

@@ -77,17 +77,22 @@ function maxInputBytes() {
 const errorMessage = (err) =>
   /** @type {{ message?: string }} */ (err)?.message ?? String(err);
 
-/** Throw if `text` exceeds the configured byte cap. The message names the limit
- * and the env var so a caller can act on it.
+/** The one oversize-rejection message, for every path that enforces the cap.
+ * Names the limit and the env var so a caller can act on it; `size` is included
+ * when the rejecting path knows it (the streaming paths discard the input
+ * unbuffered, so they only know the cap was crossed).
+ * @param {number} limit @param {number} [size] */
+const oversizeMessage = (limit, size) =>
+  `request too large: ${size === undefined ? "input" : `${size} bytes`} ` +
+  `exceeds the ${limit}-byte limit ` +
+  "(raise AGENT_SANITIZER_MAX_INPUT_BYTES to accept it)";
+
+/** Throw if `text` exceeds the configured byte cap.
  * @param {string} text */
 function enforceSizeLimit(text) {
   const limit = maxInputBytes();
   const size = Buffer.byteLength(text, "utf8");
-  if (size > limit)
-    throw new Error(
-      `request too large: ${size} bytes exceeds the ${limit}-byte limit ` +
-        "(raise AGENT_SANITIZER_MAX_INPUT_BYTES to accept it)",
-    );
+  if (size > limit) throw new Error(oversizeMessage(limit, size));
 }
 
 /** Read a required string field, throwing when it is absent or the wrong type.
@@ -105,7 +110,7 @@ function requireString(req, key) {
 /** Operations the CLI exposes. Each takes the parsed request, returns the JSON
  * payload object. Non-`sanitize` modules are imported lazily so a caller that
  * only ever sanitizes never loads prompt/output/instructions code. */
-const OPS = {
+export const OPS = {
   /** @param {Record<string, unknown>} req */
   async sanitize(req) {
     const text = requireString(req, "text");
@@ -203,11 +208,7 @@ async function readAll(stream) {
   let bytes = 0;
   for await (const chunk of stream) {
     bytes += Buffer.byteLength(chunk, "utf8");
-    if (bytes > limit)
-      throw new Error(
-        `request too large: input exceeds the ${limit}-byte limit ` +
-          "(raise AGENT_SANITIZER_MAX_INPUT_BYTES to accept it)",
-      );
+    if (bytes > limit) throw new Error(oversizeMessage(limit));
     text += chunk;
   }
   return text;
@@ -339,11 +340,7 @@ function createLineSplitter(limit) {
 
 /** @param {number} limit */
 const OVERSIZE_ERROR = (limit) =>
-  JSON.stringify({
-    error:
-      `request too large: input exceeds the ${limit}-byte limit ` +
-      "(raise AGENT_SANITIZER_MAX_INPUT_BYTES to accept it)",
-  });
+  JSON.stringify({ error: oversizeMessage(limit) });
 
 async function runWorker() {
   // Stream raw bytes (no encoding) so the splitter tracks UTF-8 byte length, not
@@ -417,6 +414,11 @@ function invokedAsScript() {
     return false;
   }
 }
+// Derived from OPS (the dispatch table is the SSOT) so adding or renaming an
+// op can never leave the help text advertising a stale set.
+const OPS_SENTENCE = Object.keys(OPS)
+  .map((op) => (op === "sanitize" ? "sanitize (default)" : op))
+  .join(", ");
 export const USAGE = `sanitize-cli — sanitize untrusted text before an LLM sees it.
 
 Reads JSON on stdin, writes one JSON response line on stdout.
@@ -426,8 +428,8 @@ Usage:
   sanitize-cli --worker   worker: read newline-delimited requests until EOF, one response per line
   sanitize-cli --help     show this help
 
-Request: { "op"?: string, ...fields }. Ops: sanitize (default), sanitizeText,
-classifyPrompt, scanInstructionFiles, cleanFile. A failure response is { "error": string }.
+Request: { "op"?: string, ...fields }. Ops: ${OPS_SENTENCE}.
+A failure response is { "error": string }.
 `;
 
 /**

package/claude-hooks/config/inference-key-vars.json

@@ -1,6 +1,5 @@
 {
-  "description": "Inference-provider API-key env vars whose VALUES the redactor masks by exact match, plus the placeholder floor below which a configured value is treated as a doc stub rather than a real key. Mirrors agent_sanitizer.secrets.config.DEFAULT_MIN_SECRET_LEN; the hooks send these names' current values to the redactor daemon per request (see lib/redactor-client.mjs).",
-  "min_secret_len": 16,
+  "description": "Inference-provider API-key env vars whose VALUES the redactor masks by exact match; the hooks send these names' current values to the redactor daemon per request (see lib/redactor-client.mjs). The placeholder floor lives in python/agent_sanitizer/secrets/data/redaction-floor.json — the one physical file both ecosystems read — not here.",
   "vars": [
     "ANTHROPIC_API_KEY",
     "ANTHROPIC_AUTH_TOKEN",

package/claude-hooks/lib/env-config.mjs

@@ -22,6 +22,7 @@
 import { credentialNameMatcher } from "agent-sanitizer/credential-names-matcher";
 
 import credentialNames from "../../python/agent_sanitizer/secrets/data/credential-names.json" with { type: "json" };
+import redactionFloor from "../../python/agent_sanitizer/secrets/data/redaction-floor.json" with { type: "json" };
 import inferenceKeys from "../config/inference-key-vars.json" with { type: "json" };
 import scrubbed from "../config/scrubbed-env-vars.json" with { type: "json" };
 
@@ -102,7 +103,10 @@ function hostSource() {
  */
 export function minEnvSecretLen() {
   const hostLen = hostSource()?.minSecretLen;
-  if (hostLen === undefined) return inferenceKeys.min_secret_len;
+  // The package floor comes from the same physical file
+  // agent_sanitizer.secrets.config reads (DEFAULT_MIN_SECRET_LEN), so the JS
+  // pre-gate and the Python daemon cannot drift apart on it.
+  if (hostLen === undefined) return redactionFloor.min_secret_len;
   if (!Number.isInteger(hostLen) || hostLen <= 0)
     throw new Error(
       `${HOST_SOURCE_LABEL}: minSecretLen must be a positive integer, got ${JSON.stringify(hostLen)}`,

package/claude-hooks/lib/secret-annotate.mjs

@@ -5,33 +5,70 @@
  */
 import { minEnvSecretLen, envBoundSecretVars } from "./env-config.mjs";
 
-// Zero-width / format (Cf) characters an attacker can splice between a value's
-// characters to break an exact-substring pre-gate while the daemon's redactor
-// still matches across them. This is a curated subset of the common bidi /
-// zero-width controls, NOT an exact copy of the daemon's full dynamic Cf set — it
-// is a defense-in-depth backstop, because Layer 1 (applyLayer1) strips every Cf
-// splice from the text BEFORE this pre-gate runs, so hasEnvBoundSecret already
-// sees the plain value. A run of zero-or-more is allowed at each interior gap, so
-// the plain value still matches (a superset of `includes`). Required literals
-// between every gap keep the pattern linear — no ReDoS.
+// The generated cross-language charset SSOT, imported as a module like
+// env-config.mjs's JSON configs: esbuild inlines it into the plugin bundle
+// (which ships with no data directory beside it) and Node resolves it from the
+// package when the hooks run from source. A DATA import, deliberately not a
+// static `agent-sanitizer/invisible` import — a top-level package import in a
+// hook lib aborts the process before the consuming hook's fail-closed catch
+// installs, which is a fail OPEN on the module that withholds secrets.
+import charset from "../../python/agent_sanitizer/data/invisible-charset.json" with { type: "json" };
+
+// Invisible characters an attacker can splice between a value's characters to
+// break an exact-substring pre-gate while the daemon's redactor still matches
+// across them. Built from the SAME pinned charset Layer 1 strips and the daemon
+// tolerates (`invisible_run_pattern` in agent_sanitizer.secrets.invisible
+// builds the same shape from the same set), not a hand-curated subset: a subset
+// pre-gate silently under-matches whenever this gate runs on text Layer 1 has
+// not already stripped (the module is exported and callable on its own), and a
+// value spliced with a code point in the gap then never reaches the daemon at
+// all. A run of zero-or-more is allowed at each interior gap, so the plain
+// value still matches (a superset of `includes`). The required literals between
+// every gap are what bound the match — a `*` gap is never adjacent to another
+// gap, so there is no ambiguity to backtrack over and no ReDoS. (The class size
+// is irrelevant to that: a character class matches in O(1) whether it holds one
+// member or all 435.)
 const ENV_INVIS_RUN =
-  "[\\u200b\\u200c\\u200d\\u2060\\ufeff\\u00ad\\u180e\\u200e\\u200f\\u202a-\\u202e\\u2066-\\u2069]*";
+  "[" +
+  [...new Set([...charset.cf_codepoints, ...charset.extra_codepoints])]
+    .sort((a, b) => a - b)
+    .map((cp) => `\\u{${cp.toString(16)}}`)
+    .join("") +
+  "]*";
 
 /**
  * Regex matching `value` tolerating invisible chars spliced between its
  * characters (mirrors the engine's env-value regex). Code-point split so
- * an astral character is escaped whole, not as two surrogate halves.
+ * an astral character is escaped whole, not as two surrogate halves — and the
+ * `u` flag, which the astral `\u{…}` class members in {@link ENV_INVIS_RUN}
+ * require.
+ * Memoized per distinct value: {@link ENV_INVIS_RUN} renders ~435 code points
+ * as ~4 KB of source and is joined at EVERY interior gap, so a 20-char secret
+ * compiles a ~75 KB pattern — and `hasEnvBoundSecret` builds one per configured
+ * var on every PostToolUse output. Env values are stable for the process's
+ * lifetime, so the cache is bounded by the number of distinct values. Sharing an
+ * instance is safe because the regex carries no `g`/`y` flag, hence no
+ * `lastIndex` state to leak between calls.
  * @param {string} value
  * @returns {RegExp}
  */
 export function envValueRegex(value) {
-  return new RegExp(
-    [...value]
-      .map((ch) => ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-      .join(ENV_INVIS_RUN),
-  );
+  let re = ENV_VALUE_REGEX_CACHE.get(value);
+  if (re === undefined) {
+    re = new RegExp(
+      [...value]
+        .map((ch) => ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(ENV_INVIS_RUN),
+      "u",
+    );
+    ENV_VALUE_REGEX_CACHE.set(value, re);
+  }
+  return re;
 }
 
+/** value → compiled matcher; see {@link envValueRegex}. */
+const ENV_VALUE_REGEX_CACHE = new Map();
+
 /**
  * True when tool output contains the literal value of a configured env-bound
  * secret. The shape-based secret hint can't match a prefix-less key or a host

package/claude-hooks/plugin-hooks.mjs

@@ -65,6 +65,7 @@ const LAZY_LOADERS = {
     import("agent-control-plane-core/claude"),
   "agent-sanitizer": () => import("agent-sanitizer"),
   "agent-sanitizer/confusables": () => import("agent-sanitizer/confusables"),
+  "agent-sanitizer/instructions": () => import("agent-sanitizer/instructions"),
   "agent-sanitizer/invisible": () => import("agent-sanitizer/invisible"),
   "agent-sanitizer/output": () => import("agent-sanitizer/output"),
   "agent-sanitizer/prompt": () => import("agent-sanitizer/prompt"),

package/claude-hooks/scan-invisible-chars.mjs

@@ -4,8 +4,17 @@
  * invisible sequences (tag chars, zero-width encodings) that hijack the model's
  * behavior — invisible in an editor but read by the LLM. These files load as
  * project instructions at session start, bypassing the PostToolUse sanitizer.
+ *
+ * The scan/decode/clean LOGIC lives in `agent-sanitizer/instructions` — this
+ * hook is glue (target discovery, accounting, alert persistence, fault
+ * posture) over that SSOT. A hand-written twin used to live here and drifted
+ * three ways at once: its report re-emitted the decoded payload with no
+ * `untrusted data` framing or escaping (re-injecting the very instruction the
+ * scan exists to catch), its scattered counter re-grew the linguistic-joiner
+ * false positive the SSOT had already fixed, and its clean path was a bare
+ * `writeFileSync` with none of cleanFile's symlink/UTF-8/TOCTOU guards.
  */
-import { readFileSync, globSync, writeFileSync, unlinkSync } from "node:fs";
+import { readFileSync, globSync, unlinkSync } from "node:fs";
 import { join, relative } from "node:path";
 import {
   awaitLazyDependency,
@@ -44,35 +53,43 @@ import {
   excludeFromContextScan,
 } from "../src/claude-context.mjs";
 
-// Layer-1 primitives, bound via lazyImport (see its doc for the fail-OPEN
-// hazard of a bare static npm import — here the instruction files would load
-// UNSCANNED). A failed load leaves the bindings undefined; on a cold container
-// (node deps not yet installed) cliMain's guard below waits out session-setup
-// before giving up, and fails loud rather than silently passing.
+// Layer-1 primitives + the instruction-scanner SSOT, bound via lazyImport (see
+// its doc for the fail-OPEN hazard of a bare static npm import — here the
+// instruction files would load UNSCANNED). A failed load leaves the bindings
+// undefined; on a cold container (node deps not yet installed) cliMain's guard
+// below waits out session-setup before giving up, and fails loud rather than
+// silently passing.
 // `let`, not `const`: the cold-start poll re-binds these once the package loads.
 let {
   LONG_RUN_RE,
   LONG_RUN_THRESHOLD,
   SCATTERED_THRESHOLD: TOTAL_INVISIBLE_THRESHOLD,
-  STRIP,
-  stripInvisible,
 } = /** @type {typeof import("agent-sanitizer/invisible")} */ (
   await lazyImport("agent-sanitizer/invisible")
 );
+let {
+  decodeRun: instrDecodeRun,
+  scanText,
+  cleanFile,
+} = /** @type {typeof import("agent-sanitizer/instructions")} */ (
+  await lazyImport("agent-sanitizer/instructions")
+);
 
 /**
- * Re-attempt the sanitizer import, waiting out an in-flight session-setup before
- * giving up. On a cold container the node deps this hook needs are still being
- * installed when SessionStart fires; without this wait `stripInvisible` is
- * undefined, the scan is skipped, and the instruction files load UNSCANNED for the
- * whole session (fail open) — silently. Reuses the control-plane poll (marker +
- * PID liveness) so the wait bound matches every other cold-start-aware gate.
+ * Re-attempt the sanitizer imports, waiting out an in-flight session-setup
+ * before giving up. On a cold container the node deps this hook needs are still
+ * being installed when SessionStart fires; without this wait `scanText` is
+ * undefined, the scan is skipped, and the instruction files load UNSCANNED for
+ * the whole session (fail open) — silently. Reuses the control-plane poll
+ * (marker + PID liveness) so the wait bound matches every other
+ * cold-start-aware gate.
  * @returns {Promise<boolean>} whether the sanitizer is now bound
  */
 async function ensureSanitizerLoaded() {
-  if (typeof stripInvisible === "function") return true;
+  if (typeof scanText === "function" && typeof cleanFile === "function")
+    return true;
   /* c8 ignore start -- cold-start reload: only runs when the top-level
-     agent-sanitizer import above failed (node deps not yet installed), which
+     agent-sanitizer imports above failed (node deps not yet installed), which
      can't be simulated in-process or in the spawned-subprocess CLI run the tests
      observe (the test env always has the deps, so the guard above early-returns).
      The reload reuses awaitLazyDependency / markerIsTrusted /
@@ -80,20 +97,28 @@ async function ensureSanitizerLoaded() {
   const marker = hookgateMarkerPath();
   const reloaded = await awaitLazyDependency({
     tryImport: async () => {
-      const mod = await lazyImport("agent-sanitizer/invisible");
-      return typeof mod.stripInvisible === "function" ? mod : null;
+      const invisible = await lazyImport("agent-sanitizer/invisible");
+      const instructions = await lazyImport("agent-sanitizer/instructions");
+      return typeof instructions.scanText === "function" &&
+        typeof instructions.cleanFile === "function" &&
+        invisible.LONG_RUN_RE !== undefined
+        ? { invisible, instructions }
+        : null;
     },
     markerPresent: () => markerIsTrusted(marker),
     setupAlive: () => probeSetupAlive(marker),
   });
   if (!reloaded) return false;
+  const bound = /** @type {{
+    invisible: typeof import("agent-sanitizer/invisible"),
+    instructions: typeof import("agent-sanitizer/instructions"),
+  }} */ (reloaded);
   ({
     LONG_RUN_RE,
     LONG_RUN_THRESHOLD,
     SCATTERED_THRESHOLD: TOTAL_INVISIBLE_THRESHOLD,
-    STRIP,
-    stripInvisible,
-  } = /** @type {typeof import("agent-sanitizer/invisible")} */ (reloaded));
+  } = bound.invisible);
+  ({ decodeRun: instrDecodeRun, scanText, cleanFile } = bound.instructions);
   return true;
   /* c8 ignore stop */
 }
@@ -164,46 +189,29 @@ function persistAlert(parts) {
 // Decoder
 
 /**
+ * The SSOT decoder, re-exported through a lazy-bound wrapper (the binding is
+ * `let` and may be re-bound by the cold-start reload, so the export must read
+ * it at call time). A hand-written twin used to live here; it decoded tag
+ * characters to RAW bytes — including actual C0 controls for U+E0001–U+E001F —
+ * with no `untrusted data, not instructions:` framing or escaping, so the
+ * hook's own report re-injected the hidden payload it had just caught.
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
  */
 function decodeRun(run) {
-  const cps = [...run].map((ch) => /** @type {number} */ (ch.codePointAt(0)));
-
-  // Tag characters U+E0001-U+E007F map directly to ASCII
-  const tagAscii = cps
-    .filter((cp) => cp >= 0xe0001 && cp <= 0xe007f)
-    // Stryker disable next-line ArithmeticOperator: cp - 0xe0000 → cp + 0xe0000 is equivalent — 0xe0000 is a multiple of 2^16 and String.fromCharCode truncates to 16 bits, so both yield the same character.
-    .map((cp) => String.fromCharCode(cp - 0xe0000))
-    .join("");
-
-  if (tagAscii.length > 0) {
-    return { method: "Unicode tag characters → ASCII", decoded: tagAscii };
-  }
-
-  // Zero-width binary encoding: ZWSP=0, ZWNJ=1, ZWJ=group separator.
-  const ZW_BIT = new Map([
-    [0x200b, "0"],
-    [0x200c, "1"],
-    [0x200d, "|"],
-  ]);
-  if (cps.every((cp) => ZW_BIT.has(cp))) {
-    const bits = cps.map((cp) => ZW_BIT.get(cp)).join("");
-    return {
-      method: "zero-width binary encoding",
-      decoded: `[${cps.length} zero-width chars: ${bits.slice(0, 80)}]`,
-    };
-  }
-
-  // Mixed/unknown
-  return {
-    method: "invisible Unicode sequence",
-    decoded: cps
-      .map((cp) => `U+${cp.toString(16).toUpperCase().padStart(4, "0")}`)
-      .join(" "),
-  };
+  return instrDecodeRun(run);
 }
 
+// Target discovery stays hook-local glue, NOT a copy of the SSOT's
+// containment-checked `findInstructionFiles`: the two have different contracts.
+// The SSOT finder silently DROPS a target it cannot resolve (dangling symlink,
+// out-of-tree symlink), which is right for a pure scan API — but this hook's
+// accounting invariant (scanned + skipped === targets, see scanProject)
+// requires unreadable targets to stay LISTED so they are reported as unvetted
+// rather than vanishing into an "all clean" announcement. The write-side
+// symlink hazard the SSOT finder guards against is covered here by cleanFile's
+// own O_NOFOLLOW open.
+
 /**
  * Every file under `dir` that Claude Code loads as model context: the
  * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
@@ -230,37 +238,17 @@ function findInstructionFiles(dir) {
 // Scanner
 
 /**
+ * Read one file and run the SSOT scan over it. The scan logic itself (long-run
+ * decode + scattered threshold-evasion counting) is `scanText`'s — a local
+ * mirror used to re-count scatter from the raw STRIP match count, silently
+ * re-growing the linguistic-joiner/VS15 false positive `scanText`'s carve-out
+ * counter had already fixed.
  * @param {string} filePath
- * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ * @returns {ReturnType<typeof import("agent-sanitizer/instructions").scanText>}
+ *   `line` is 1-based, or `null` for the whole-file scattered-chars finding.
  */
 function scanFile(filePath) {
-  const content = readFileSync(filePath, "utf-8");
-  const findings = [];
-  LONG_RUN_RE.lastIndex = 0;
-  let match;
-  let runChars = 0;
-  while ((match = LONG_RUN_RE.exec(content)) !== null) {
-    const lineNum = content.slice(0, match.index).split("\n").length;
-    const charCount = [...match[0]].length;
-    runChars += charCount;
-    findings.push({ line: lineNum, charCount, ...decodeRun(match[0]) });
-  }
-
-  // Threshold-evasion: scattered invisible chars not in a long run can still be
-  // a payload. Always evaluated; chars already in a run are excluded so they
-  // aren't double-counted.
-  const allInvisible = content.match(STRIP);
-  const scattered = (allInvisible ? allInvisible.length : 0) - runChars;
-  if (scattered >= TOTAL_INVISIBLE_THRESHOLD) {
-    findings.push({
-      line: 0,
-      charCount: scattered,
-      method: "scattered invisible chars (possible threshold evasion)",
-      decoded: `[${scattered} invisible chars distributed across file]`,
-    });
-  }
-
-  return findings;
+  return scanText(readFileSync(filePath, "utf-8"));
 }
 
 export {
@@ -282,7 +270,7 @@ export {
 /**
  * @param {Array<{
  *   file: string,
- *   findings: Array<{ line: number, charCount: number, method: string, decoded: string }>,
+ *   findings: Array<{ line: number | null, charCount: number, method: string, decoded: string }>,
  * }>} allFindings
  * @returns {string}
  */
@@ -304,8 +292,12 @@ function formatReport(allFindings) {
   for (const { file, findings } of allFindings) {
     lines.push(`  ${file}:`);
     for (const finding of findings) {
+      // `line` is null for the whole-file scattered-chars finding, which is
+      // not tied to any single line.
+      const where =
+        finding.line === null ? "Whole file" : `Line ${finding.line}`;
       lines.push(
-        `    Line ${finding.line}: ${finding.charCount} invisible chars (${finding.method})`,
+        `    ${where}: ${finding.charCount} invisible chars (${finding.method})`,
       );
       lines.push(`    Decodes to: ${JSON.stringify(finding.decoded)}`);
     }
@@ -548,20 +540,29 @@ function autoCleanFindings(allFindings, dir) {
   for (const { file } of allFindings) {
     const absPath = join(dir, file);
     try {
-      const original = readFileSync(absPath, "utf-8");
-      const stripped = stripInvisible(original);
-      if (stripped !== original) {
-        writeFileSync(absPath, stripped);
-        cleaned++;
-      }
-      /* c8 ignore start -- only fires on a file this uid cannot rewrite, which the test run cannot create */
+      // The SSOT clean: O_NOFOLLOW open, UTF-8 round-trip check, TOCTOU
+      // recheck, atomic rename + fsync, mode preservation. The bare
+      // readFileSync/writeFileSync pair that lived here had none of those
+      // guards — on the one hook that REWRITES instruction files.
+      //
+      // Counted ONLY on `true` (bytes changed), matching the old
+      // `stripped !== original` gate. `false` means cleanFile re-scanned and
+      // found nothing to strip in a file this run flagged — the file was
+      // changed under us, or the flagged run is one the stripper PRESERVES —
+      // so it is not a file we cleaned, and leaving `cleaned` short is what
+      // routes it to the alert below instead of an "all clean" report.
+      if (cleanFile(absPath)) cleaned++;
+      /* c8 ignore start -- only fires on a file cleanFile refuses (symlink,
+         non-UTF-8, concurrent write) or cannot rewrite, which the test run
+         does not create */
     } catch (err) {
-      // Narrowed to filesystem errnos, and the reason is REPORTED rather than
-      // swallowed: an unwritable file legitimately falls through to the alert
-      // path below, but a throw from stripInvisible is a bug in the sanitizer
-      // and must not be laundered into "this file resisted cleaning".
-      if (/** @type {NodeJS.ErrnoException} */ (err).code === undefined)
-        throw err;
+      // The reason is REPORTED rather than swallowed: a refusal or an
+      // unwritable file legitimately falls through to the alert path below. A
+      // TypeError is the one throw that still propagates — an unbound lazy
+      // import, i.e. a bug in THIS hook, which must not be laundered into
+      // "this file resisted cleaning". (The scan phase has already exercised
+      // the same bindings, so this is a belt-and-braces rethrow.)
+      if (err instanceof TypeError) throw err;
       process.stderr.write(
         `scan-invisible-chars: could not clean ${file}: ${safeErrMessage(err)}\n`,
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.27.0",
+  "version": "2.28.1",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {
@@ -186,7 +186,9 @@
   },
   "files": [
     "src/*.mjs",
+    "python/agent_sanitizer/data/invisible-charset.json",
     "python/agent_sanitizer/secrets/data/credential-names.json",
+    "python/agent_sanitizer/secrets/data/redaction-floor.json",
     "claude-hooks/*.mjs",
     "claude-hooks/lib/*.mjs",
     "claude-hooks/config/*.json",

package/python/agent_sanitizer/data/invisible-charset.json

@@ -0,0 +1,481 @@
+{
+  "_comment": "SSOT for the payload-capable invisible code points, generated by scripts/gen-invisible-charset.mjs. `extra_codepoints` are the non-Cf extras (variation selectors, blank-rendering fillers, zero-width combining marks) from src/invisible.mjs (VS + BLANK_NON_CF). `cf_codepoints` is the general-category Cf set PINNED from Node's Unicode data at generation time (see `unicode_version`) — NOT resolved live per consumer, because Node and CPython ship different Unicode versions and a live-Cf split let a code point in the version delta escape one layer. The deletion set is the UNION of the two lists. `control_introducers` is the raw ANSI control-introducer set (ESC + the C1 block) from src/ansi.mjs, which Layer 1 sweeps and the Python textstrip port must sweep identically. Consumers in other languages read this file instead of forking the lists — a fork is a silent security regression.",
+  "unicode_version": "17.0",
+  "extra_codepoints": [
+    847,
+    4447,
+    4448,
+    6068,
+    6069,
+    6155,
+    6156,
+    6157,
+    6159,
+    10240,
+    12644,
+    65024,
+    65025,
+    65026,
+    65027,
+    65028,
+    65029,
+    65030,
+    65031,
+    65032,
+    65033,
+    65034,
+    65035,
+    65036,
+    65037,
+    65038,
+    65039,
+    65440,
+    917760,
+    917761,
+    917762,
+    917763,
+    917764,
+    917765,
+    917766,
+    917767,
+    917768,
+    917769,
+    917770,
+    917771,
+    917772,
+    917773,
+    917774,
+    917775,
+    917776,
+    917777,
+    917778,
+    917779,
+    917780,
+    917781,
+    917782,
+    917783,
+    917784,
+    917785,
+    917786,
+    917787,
+    917788,
+    917789,
+    917790,
+    917791,
+    917792,
+    917793,
+    917794,
+    917795,
+    917796,
+    917797,
+    917798,
+    917799,
+    917800,
+    917801,
+    917802,
+    917803,
+    917804,
+    917805,
+    917806,
+    917807,
+    917808,
+    917809,
+    917810,
+    917811,
+    917812,
+    917813,
+    917814,
+    917815,
+    917816,
+    917817,
+    917818,
+    917819,
+    917820,
+    917821,
+    917822,
+    917823,
+    917824,
+    917825,
+    917826,
+    917827,
+    917828,
+    917829,
+    917830,
+    917831,
+    917832,
+    917833,
+    917834,
+    917835,
+    917836,
+    917837,
+    917838,
+    917839,
+    917840,
+    917841,
+    917842,
+    917843,
+    917844,
+    917845,
+    917846,
+    917847,
+    917848,
+    917849,
+    917850,
+    917851,
+    917852,
+    917853,
+    917854,
+    917855,
+    917856,
+    917857,
+    917858,
+    917859,
+    917860,
+    917861,
+    917862,
+    917863,
+    917864,
+    917865,
+    917866,
+    917867,
+    917868,
+    917869,
+    917870,
+    917871,
+    917872,
+    917873,
+    917874,
+    917875,
+    917876,
+    917877,
+    917878,
+    917879,
+    917880,
+    917881,
+    917882,
+    917883,
+    917884,
+    917885,
+    917886,
+    917887,
+    917888,
+    917889,
+    917890,
+    917891,
+    917892,
+    917893,
+    917894,
+    917895,
+    917896,
+    917897,
+    917898,
+    917899,
+    917900,
+    917901,
+    917902,
+    917903,
+    917904,
+    917905,
+    917906,
+    917907,
+    917908,
+    917909,
+    917910,
+    917911,
+    917912,
+    917913,
+    917914,
+    917915,
+    917916,
+    917917,
+    917918,
+    917919,
+    917920,
+    917921,
+    917922,
+    917923,
+    917924,
+    917925,
+    917926,
+    917927,
+    917928,
+    917929,
+    917930,
+    917931,
+    917932,
+    917933,
+    917934,
+    917935,
+    917936,
+    917937,
+    917938,
+    917939,
+    917940,
+    917941,
+    917942,
+    917943,
+    917944,
+    917945,
+    917946,
+    917947,
+    917948,
+    917949,
+    917950,
+    917951,
+    917952,
+    917953,
+    917954,
+    917955,
+    917956,
+    917957,
+    917958,
+    917959,
+    917960,
+    917961,
+    917962,
+    917963,
+    917964,
+    917965,
+    917966,
+    917967,
+    917968,
+    917969,
+    917970,
+    917971,
+    917972,
+    917973,
+    917974,
+    917975,
+    917976,
+    917977,
+    917978,
+    917979,
+    917980,
+    917981,
+    917982,
+    917983,
+    917984,
+    917985,
+    917986,
+    917987,
+    917988,
+    917989,
+    917990,
+    917991,
+    917992,
+    917993,
+    917994,
+    917995,
+    917996,
+    917997,
+    917998,
+    917999
+  ],
+  "cf_codepoints": [
+    173,
+    1536,
+    1537,
+    1538,
+    1539,
+    1540,
+    1541,
+    1564,
+    1757,
+    1807,
+    2192,
+    2193,
+    2274,
+    6158,
+    8203,
+    8204,
+    8205,
+    8206,
+    8207,
+    8234,
+    8235,
+    8236,
+    8237,
+    8238,
+    8288,
+    8289,
+    8290,
+    8291,
+    8292,
+    8294,
+    8295,
+    8296,
+    8297,
+    8298,
+    8299,
+    8300,
+    8301,
+    8302,
+    8303,
+    65279,
+    65529,
+    65530,
+    65531,
+    69821,
+    69837,
+    78896,
+    78897,
+    78898,
+    78899,
+    78900,
+    78901,
+    78902,
+    78903,
+    78904,
+    78905,
+    78906,
+    78907,
+    78908,
+    78909,
+    78910,
+    78911,
+    113824,
+    113825,
+    113826,
+    113827,
+    119155,
+    119156,
+    119157,
+    119158,
+    119159,
+    119160,
+    119161,
+    119162,
+    917505,
+    917536,
+    917537,
+    917538,
+    917539,
+    917540,
+    917541,
+    917542,
+    917543,
+    917544,
+    917545,
+    917546,
+    917547,
+    917548,
+    917549,
+    917550,
+    917551,
+    917552,
+    917553,
+    917554,
+    917555,
+    917556,
+    917557,
+    917558,
+    917559,
+    917560,
+    917561,
+    917562,
+    917563,
+    917564,
+    917565,
+    917566,
+    917567,
+    917568,
+    917569,
+    917570,
+    917571,
+    917572,
+    917573,
+    917574,
+    917575,
+    917576,
+    917577,
+    917578,
+    917579,
+    917580,
+    917581,
+    917582,
+    917583,
+    917584,
+    917585,
+    917586,
+    917587,
+    917588,
+    917589,
+    917590,
+    917591,
+    917592,
+    917593,
+    917594,
+    917595,
+    917596,
+    917597,
+    917598,
+    917599,
+    917600,
+    917601,
+    917602,
+    917603,
+    917604,
+    917605,
+    917606,
+    917607,
+    917608,
+    917609,
+    917610,
+    917611,
+    917612,
+    917613,
+    917614,
+    917615,
+    917616,
+    917617,
+    917618,
+    917619,
+    917620,
+    917621,
+    917622,
+    917623,
+    917624,
+    917625,
+    917626,
+    917627,
+    917628,
+    917629,
+    917630,
+    917631
+  ],
+  "control_introducers": [
+    27,
+    128,
+    129,
+    130,
+    131,
+    132,
+    133,
+    134,
+    135,
+    136,
+    137,
+    138,
+    139,
+    140,
+    141,
+    142,
+    143,
+    144,
+    145,
+    146,
+    147,
+    148,
+    149,
+    150,
+    151,
+    152,
+    153,
+    154,
+    155,
+    156,
+    157,
+    158,
+    159
+  ]
+}

package/python/agent_sanitizer/secrets/data/redaction-floor.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Floor below which a configured env value is treated as a doc stub / placeholder rather than a real key, so a var set to a short test value ('fake', 'sk-test') never blanks unrelated output. ONE physical file backs both ecosystems, exactly like credential-names.json beside it: agent_sanitizer.secrets.config reads DEFAULT_MIN_SECRET_LEN from here, and claude-hooks/lib/env-config.mjs imports it for the Layer-4 pre-gate — there is no second copy to drift.",
+  "min_secret_len": 16
+}

package/src/ansi.mjs

@@ -25,13 +25,27 @@
 // DCS/SOS/PM/APC string the grammar does not consume still loses its introducer
 // and terminator, so no terminal can hide-render its body as a control payload.
 //
+// The introducer set as DATA, so a non-JS consumer can share it: the generator
+// (scripts/gen-invisible-charset.mjs) pins these code points into
+// data/invisible-charset.json's `control_introducers`, which the Python port
+// (python/agent_sanitizer/textstrip.py) sweeps. Before that, the Python side
+// hand-wrote `\x1b` alone and the whole C1 block survived its strip — the exact
+// fork this module's header says must not recur, one language over.
+export const CONTROL_INTRODUCER_CODEPOINTS = Object.freeze([
+  0x1b,
+  ...Array.from({ length: 0x9f - 0x80 + 1 }, (_, i) => 0x80 + i),
+]);
+
 // A SOURCE STRING, not a literal: three call sites need it with different flags
 // (`g` for the Layer-1 sweep, unflagged for the prompt gate, `g` again to drive
 // the scan below), and spelling the class out at each site is how the three
 // copies came to spell the same byte two different ways — which defeats a
-// grep-based drift check as well. Building from `\uXXXX` escapes keeps every
-// raw control byte out of the source (no `no-control-regex` disable needed).
-export const CONTROL_INTRODUCER_SOURCE = "[\\u001b\\u0080-\\u009f]";
+// grep-based drift check as well. Derived from the code-point list above so the
+// regex and the exported data cannot disagree; `\uXXXX` escapes keep every raw
+// control byte out of the source (no `no-control-regex` disable needed).
+export const CONTROL_INTRODUCER_SOURCE = `[${CONTROL_INTRODUCER_CODEPOINTS.map(
+  (cp) => `\\u${cp.toString(16).padStart(4, "0")}`,
+).join("")}]`;
 
 // SGR (Select Graphic Rendition): colors, bold, reset. The grammar is closed:
 // params are [0-9;:]* and the final byte is `m`, so a match can only restyle

package/src/index.mjs

@@ -87,20 +87,26 @@ export {
  * to the four fields this entry promises — `modified`/`sgrNote`
  * describe the tool-output pipeline's banner, and `reveal` is produced only by
  * options this facade does not expose. `html` selects Layers 2 AND 3 together
- * here, which is the surface this entry has always had; `sanitizeText` takes
- * them as separate flags for the tool-output pipeline, which needs Layer 3's
- * detection without Layer 2's splice.
+ * here, which is the surface this entry has always had; `exfilScan` exposes
+ * Layer 3's non-destructive detection on its own (unconditionally implied by
+ * `html`, which it can add to but never switch off) for
+ * callers that must keep the visible bytes intact — e.g. a PR diff where the
+ * Layer-2 splice would corrupt legitimate markup — matching the separate
+ * flags `sanitizeText` takes for the tool-output pipeline.
  * @param {string} text
- * @param {{ html?: boolean } | null} [options]
+ * @param {{ html?: boolean, exfilScan?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[] }>}
  */
 export async function sanitize(text, options) {
   if (typeof text !== "string")
     throw new TypeError("sanitize(text, options): text must be a string");
-  const { html = false } = options ?? {};
+  const { html = false, exfilScan = false } = options ?? {};
   const { cleaned, found, warnings, notes } = await sanitizeText(text, {
     html,
-    exfilScan: html,
+    // `html` implies the scan unconditionally, and `exfilScan` can only ADD it:
+    // an opt-OUT would make `{ html: true, exfilScan: false }` splice Layer 2
+    // while silently dropping Layer 3's report — a fail-open the docs deny.
+    exfilScan: exfilScan || html,
   });
   return { cleaned, found, warnings, notes };
 }

package/src/instructions.mjs

@@ -450,11 +450,15 @@ export function atomicReplaceFile(
 /**
  * Strip payload-capable invisible characters from `absPath` in place. Returns
  * `true` when the file's bytes actually changed (a payload {@link scanText}
- * flags was removed), `false` when {@link scanText} reports nothing, and `null`
- * when scan flagged a payload but {@link stripInvisible} removes nothing — a
- * fail-closed signal that the flagged run was PRESERVED (e.g. a well-formed
- * emoji-tag sequence the stripper keeps), so the caller must not treat it as
- * cleaned. `true` means and only means "bytes changed".
+ * flags was removed) and `false` when {@link scanText} reports nothing to
+ * strip. `true` means and only means "bytes changed", so a caller that flagged
+ * this file and gets `false` back must NOT record it as cleaned — the file
+ * changed under it, or the flagged run is one {@link stripInvisible}
+ * preserves (a well-formed emoji-tag sequence), and either way the payload it
+ * flagged is still there. There is no third return value: the `null` arm this
+ * doc once described was dropped as dead (`stripInvisible` cannot leave the
+ * bytes identical for anything `scanText` flags), and callers must branch on
+ * the boolean rather than testing against `null`, which is vacuously true.
  *
  * Contract (scan/clean coherence): clean strips exactly what scan flags. A
  * write happens ONLY when `scanText` reports a finding, so the "scan, then

package/types/ansi.d.mts

@@ -55,7 +55,8 @@ export function scanAnsi(text: string): AnsiToken[];
  * Same precedent (and same reason) as `cf-charset.mjs`: a dependency-free leaf
  * module both layers read from.
  */
-export const CONTROL_INTRODUCER_SOURCE: "[\\u001b\\u0080-\\u009f]";
+export const CONTROL_INTRODUCER_CODEPOINTS: readonly number[];
+export const CONTROL_INTRODUCER_SOURCE: string;
 /**
  * Public alias kept for compatibility (re-exported by `invisible.mjs` and the
  * package root). It is now DERIVED: {@link scanAnsi} classifies a token as SGR

package/types/claude-hooks/lib/secret-annotate.d.mts

@@ -1,7 +1,16 @@
 /**
  * Regex matching `value` tolerating invisible chars spliced between its
  * characters (mirrors the engine's env-value regex). Code-point split so
- * an astral character is escaped whole, not as two surrogate halves.
+ * an astral character is escaped whole, not as two surrogate halves — and the
+ * `u` flag, which the astral `\u{…}` class members in {@link ENV_INVIS_RUN}
+ * require.
+ * Memoized per distinct value: {@link ENV_INVIS_RUN} renders ~435 code points
+ * as ~4 KB of source and is joined at EVERY interior gap, so a 20-char secret
+ * compiles a ~75 KB pattern — and `hasEnvBoundSecret` builds one per configured
+ * var on every PostToolUse output. Env values are stable for the process's
+ * lifetime, so the cache is bounded by the number of distinct values. Sharing an
+ * instance is safe because the regex carries no `g`/`y` flag, hence no
+ * `lastIndex` state to leak between calls.
  * @param {string} value
  * @returns {RegExp}
  */

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -72,18 +72,25 @@ export function cliMain(opts?: {
     scan?: () => ReturnType<typeof scanProject>;
 }): Promise<void>;
 /**
+ * Read one file and run the SSOT scan over it. The scan logic itself (long-run
+ * decode + scattered threshold-evasion counting) is `scanText`'s — a local
+ * mirror used to re-count scatter from the raw STRIP match count, silently
+ * re-growing the linguistic-joiner/VS15 false positive `scanText`'s carve-out
+ * counter had already fixed.
  * @param {string} filePath
- * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ * @returns {ReturnType<typeof import("agent-sanitizer/instructions").scanText>}
+ *   `line` is 1-based, or `null` for the whole-file scattered-chars finding.
  */
-export function scanFile(filePath: string): Array<{
-    line: number;
-    charCount: number;
-    method: string;
-    decoded: string;
-}>;
+export function scanFile(filePath: string): ReturnType<typeof import("agent-sanitizer/instructions").scanText>;
 import { CLAUDE_CONTEXT_SUBDIRS } from "../src/claude-context.mjs";
 import { CLAUDE_INSTRUCTION_GLOBS } from "../src/claude-context.mjs";
 /**
+ * The SSOT decoder, re-exported through a lazy-bound wrapper (the binding is
+ * `let` and may be re-bound by the cold-start reload, so the export must read
+ * it at call time). A hand-written twin used to live here; it decoded tag
+ * characters to RAW bytes — including actual C0 controls for U+E0001–U+E001F —
+ * with no `untrusted data, not instructions:` framing or escaping, so the
+ * hook's own report re-injected the hidden payload it had just caught.
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
  */
@@ -116,14 +123,14 @@ export let TOTAL_INVISIBLE_THRESHOLD: 30;
 /**
  * @param {Array<{
  *   file: string,
- *   findings: Array<{ line: number, charCount: number, method: string, decoded: string }>,
+ *   findings: Array<{ line: number | null, charCount: number, method: string, decoded: string }>,
  * }>} allFindings
  * @returns {string}
  */
 export function formatReport(allFindings: Array<{
     file: string;
     findings: Array<{
-        line: number;
+        line: number | null;
         charCount: number;
         method: string;
         decoded: string;

package/types/index.d.mts

@@ -24,15 +24,19 @@
  * to the four fields this entry promises — `modified`/`sgrNote`
  * describe the tool-output pipeline's banner, and `reveal` is produced only by
  * options this facade does not expose. `html` selects Layers 2 AND 3 together
- * here, which is the surface this entry has always had; `sanitizeText` takes
- * them as separate flags for the tool-output pipeline, which needs Layer 3's
- * detection without Layer 2's splice.
+ * here, which is the surface this entry has always had; `exfilScan` exposes
+ * Layer 3's non-destructive detection on its own (unconditionally implied by
+ * `html`, which it can add to but never switch off) for
+ * callers that must keep the visible bytes intact — e.g. a PR diff where the
+ * Layer-2 splice would corrupt legitimate markup — matching the separate
+ * flags `sanitizeText` takes for the tool-output pipeline.
  * @param {string} text
- * @param {{ html?: boolean } | null} [options]
+ * @param {{ html?: boolean, exfilScan?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[] }>}
  */
 export function sanitize(text: string, options?: {
     html?: boolean;
+    exfilScan?: boolean;
 } | null): Promise<{
     cleaned: string;
     found: string[];

package/types/instructions.d.mts

@@ -100,11 +100,15 @@ export function atomicReplaceFile(absPath: string, data: string, mode: number, t
 /**
  * Strip payload-capable invisible characters from `absPath` in place. Returns
  * `true` when the file's bytes actually changed (a payload {@link scanText}
- * flags was removed), `false` when {@link scanText} reports nothing, and `null`
- * when scan flagged a payload but {@link stripInvisible} removes nothing — a
- * fail-closed signal that the flagged run was PRESERVED (e.g. a well-formed
- * emoji-tag sequence the stripper keeps), so the caller must not treat it as
- * cleaned. `true` means and only means "bytes changed".
+ * flags was removed) and `false` when {@link scanText} reports nothing to
+ * strip. `true` means and only means "bytes changed", so a caller that flagged
+ * this file and gets `false` back must NOT record it as cleaned — the file
+ * changed under it, or the flagged run is one {@link stripInvisible}
+ * preserves (a well-formed emoji-tag sequence), and either way the payload it
+ * flagged is still there. There is no third return value: the `null` arm this
+ * doc once described was dropped as dead (`stripInvisible` cannot leave the
+ * bytes identical for anything `scanText` flags), and callers must branch on
+ * the boolean rather than testing against `null`, which is vacuously true.
  *
  * Contract (scan/clean coherence): clean strips exactly what scan flags. A
  * write happens ONLY when `scanText` reports a finding, so the "scan, then