agent-sanitizer 2.2.2 → 2.4.0

package/claude-hooks/sanitize-user-prompt.mjs

@@ -0,0 +1,164 @@
+/**
+ * UserPromptSubmit: gate user prompts on payload-capable invisible Unicode
+ * and ANSI escapes. A prompt pasted from a tampered web page can carry tag
+ * characters or zero-width sequences that the LLM reads but the user cannot
+ * see. The PostToolUse sanitizer never runs on user input, so this is the
+ * only line of defense.
+ *
+ * UserPromptSubmit cannot rewrite the prompt — `additionalContext` is added
+ * alongside the original, not in place of it — so the only way to neutralize
+ * a payload is to block. Thresholds match scan-invisible-chars (SessionStart)
+ * for UX consistency.
+ *
+ * One carve-out: a prompt whose only escape content is SGR color/style codes
+ * (ESC [ params m) passes with a note instead of blocking. Pasting colored
+ * terminal output (test runs, build logs) is the single most common debugging
+ * action, and SGR is display-only by the ECMA-48 grammar — it cannot move the
+ * cursor, erase the screen, or carry an OSC payload. Anything beyond SGR
+ * (cursor movement, erase, OSC title-set, DCS/APC/PM) still blocks, as do the
+ * invisible-char thresholds, which are the actual web-paste payload defense.
+ */
+import { readStdinJson, safeErrMessage, isMain } from "./lib/hook-io.mjs";
+import { controlPlane, runJudgeCli } from "./lib/control-plane.mjs";
+import { trace, TraceEvent } from "./lib/trace.mjs";
+// classifyPrompt (the user-prompt verdict) and stripAnsiFully (its ANSI stripper)
+// come from the agent-sanitizer package. They are bound by a *caught* dynamic
+// import, never a bare top-level `import … from "…"`: a static npm import
+// resolves before any try/catch, so a missing node_modules would crash this hook
+// at load and let the prompt through UNSANITIZED (fail-open). A failed load
+// leaves the bindings undefined, which main()'s typeof guard turns into a
+// fail-closed block.
+/** @type {typeof import("agent-sanitizer/prompt").classifyPrompt} */
+export let classifyPrompt;
+/** @type {typeof import("agent-sanitizer").stripAnsiFully} */
+let stripAnsiFully;
+
+const BLOCK_CONTEXT =
+  "User prompt blocked: payload-capable invisible/ANSI characters detected.";
+const SGR_NOTE =
+  "The prompt contains ANSI SGR color codes (pasted terminal output). They are display-only formatting noise; read through them.";
+
+/* c8 ignore start — module-load boundary: the imports resolve in every real
+ * run, and their failure (the package absent) can't be simulated in-process, so
+ * neither arm is observable to the in-process tests. main()'s typeof guard
+ * converts an undefined stripper into a fail-closed block — that guard IS tested. */
+// Stryker disable all
+try {
+  // The /prompt subpath is imported first: if it fails, the catch fires before
+  // stripAnsiFully is assigned, so a half-load can never leave the stripper set
+  // while the classifier is missing (main guards on the stripper alone).
+  ({ classifyPrompt } = await import("agent-sanitizer/prompt"));
+  ({ stripAnsiFully } = await import("agent-sanitizer"));
+} catch {
+  // Leave classifyPrompt/stripAnsiFully undefined so main()'s typeof guard fails
+  // closed — the prompt is blocked, never passed through with the package
+  // half-loaded.
+}
+// Stryker restore all
+/* c8 ignore stop */
+
+/**
+ * Judge a normalized prompt-submit event. Agent-agnostic: consumes the
+ * control-plane ToolCallEvent and returns a Verdict, so the same prompt gate
+ * renders through any agent adapter, not just Claude's. Throws (into the
+ * calling hook's catch) when the sanitizer package never loaded — this hook is
+ * the only defense on user input, so a prompt it cannot classify must block,
+ * never pass through.
+ * @param {import("agent-control-plane-core").ToolCallEvent} event
+ * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
+ *   to the package's stripAnsiFully; injectable so the fail-closed path is testable)
+ * @returns {import("agent-control-plane-core").Verdict}
+ */
+export function judgeSanitizeUserPrompt(event, strip = stripAnsiFully) {
+  const { Decision, EventKind } = controlPlane();
+  // A payload the adapter cannot classify carries no readable prompt, so an
+  // abstain would fail OPEN on harness contract drift; this gate's posture is
+  // deny-when-blind. (Renders through the adapter's top-level decision:"block"
+  // channel — a non-PRE_TOOL event has no permissionDecision body — which Claude
+  // honors on UserPromptSubmit.)
+  if (event.event === EventKind.UNKNOWN)
+    return {
+      decision: Decision.DENY,
+      reason: "User prompt blocked (fail-closed): unrecognized hook payload.",
+    };
+  if (event.event !== EventKind.PROMPT_SUBMIT)
+    return { decision: Decision.ALLOW };
+  // The module-load guard: a missing stripper means agent-sanitizer never
+  // loaded. Guarding on the stripper alone is sufficient — it loads AFTER
+  // classifyPrompt in the same try, so a present stripper proves the classifier
+  // loaded too.
+  if (typeof strip !== "function")
+    throw new Error("agent-sanitizer is unavailable");
+  // The contract guarantees a string here: every adapter normalizes the
+  // prompt-submit input (Claude's parse coerces a missing/non-string prompt to
+  // "" via asString), so a defensive typeof re-check is a dead branch.
+  const prompt = /** @type {string} */ (event.input.prompt);
+  if (!prompt) return { decision: Decision.ALLOW };
+  const verdict = classifyPrompt(prompt, strip);
+  if (verdict.action === "pass") return { decision: Decision.ALLOW };
+  if (verdict.action === "note")
+    return { decision: Decision.ALLOW, additional_context: SGR_NOTE };
+  // block: carry the reason AND a context note — UserPromptSubmit can't rewrite
+  // the prompt, so the context is the only forward signal about why it dropped.
+  return {
+    decision: Decision.DENY,
+    reason: verdict.reason,
+    additional_context: BLOCK_CONTEXT,
+  };
+}
+
+/**
+ * @param {() => Promise<any> | any} read
+ * @param {(chunk: string) => void} write
+ * @param {((s: string) => string) | null} [strip]  the ANSI stripper (defaults
+ *   to the package's stripAnsiFully; injectable so the fail-closed path is testable)
+ * @returns {Promise<void>}
+ */
+export async function main(read, write, strip = stripAnsiFully) {
+  // Delegate the parse → judge → render → write contract to the shared
+  // runJudgeCli so this hook doesn't re-implement the control-plane boundary:
+  // runJudgeCli reads stdin BEFORE loading the control-plane package, so a
+  // load failure fails to this hook's posture (the onError block) instead of
+  // leaving stdin unread. The fail-closed onError writes the UserPromptSubmit
+  // `decision:"block"` envelope by hand because the adapter that would render it
+  // is exactly what may have failed to load.
+  await runJudgeCli(
+    "sanitize-user-prompt",
+    (event) => {
+      const verdict = judgeSanitizeUserPrompt(event, strip);
+      // Announce engagement on the trace channel like the other stdin hooks —
+      // a prompt gate that silently stopped running is otherwise invisible.
+      trace(TraceEvent.HOOK_RAN, {
+        hook: "sanitize-user-prompt",
+        outcome:
+          verdict.decision === controlPlane().Decision.DENY
+            ? "deny"
+            : verdict.additional_context
+              ? "note"
+              : "allow",
+      });
+      return verdict;
+    },
+    {
+      readInput: read,
+      write,
+      onError: (err) =>
+        write(
+          JSON.stringify({
+            decision: "block",
+            reason: `sanitize-user-prompt hook failed (fail-closed): ${safeErrMessage(err)}`,
+          }),
+        ),
+    },
+  );
+}
+
+/* c8 ignore start — CLI entry runs only in the spawned subprocess; main/render/
+ * classifyPrompt are mutation-tested via the in-process tests that call them. */
+// Stryker disable all: same subprocess-only boundary as the c8 ignore — the
+// direct-run guard can't be observed in-process.
+if (isMain(import.meta.url)) {
+  void main(readStdinJson, (chunk) => process.stdout.write(chunk));
+}
+/* c8 ignore stop */
+// Stryker restore all

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

@@ -0,0 +1,313 @@
+/**
+ * SessionStart: scan CLAUDE.md and .claude/ markdown for runs of invisible
+ * Unicode that may encode hidden instructions. Pasted markdown can embed
+ * 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.
+ */
+import { readFileSync, globSync, writeFileSync, unlinkSync } from "node:fs";
+import { join, relative } from "node:path";
+import { isMain, lazyImport, writeFileNoFollow } from "./lib/hook-io.mjs";
+import {
+  ALERT_FILE,
+  ALERT_ACK_FILE,
+  PROJECT_DIR,
+} from "./lib/invisible-alert.mjs";
+import { trace, TraceEvent } from "./lib/trace.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, and cliMain's guard
+// below fails loud rather than silently passing.
+const {
+  LONG_RUN_RE,
+  LONG_RUN_THRESHOLD,
+  SCATTERED_THRESHOLD: TOTAL_INVISIBLE_THRESHOLD,
+  STRIP,
+  stripInvisible,
+} = /** @type {typeof import("agent-sanitizer/invisible")} */ (
+  await lazyImport("agent-sanitizer/invisible")
+);
+
+// Decoder
+
+/**
+ * @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(" "),
+  };
+}
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findMdFiles(dir) {
+  return globSync("**/*.md", {
+    cwd: dir,
+    exclude: (name) => name === "node_modules",
+  }).map((name) => join(dir, name));
+}
+
+/**
+ * Every subdirectory instruction file (CLAUDE.md, CLAUDE.local.md, AGENTS.md)
+ * under `dir`. Claude Code loads these as project instructions on entry to their
+ * containing directory — a load path that bypasses the PostToolUse sanitizer — so
+ * a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model uncleaned
+ * unless it is scanned here. Skips node_modules; `**` skips dot directories by
+ * default (`.git`, and `.claude`, which the caller scans separately).
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findInstructionFiles(dir) {
+  return globSync(["**/CLAUDE.md", "**/CLAUDE.local.md", "**/AGENTS.md"], {
+    cwd: dir,
+    exclude: (name) => name === "node_modules",
+  }).map((name) => join(dir, name));
+}
+
+// Scanner
+
+/**
+ * @param {string} filePath
+ * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ */
+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;
+}
+
+export {
+  decodeRun,
+  findMdFiles,
+  findInstructionFiles,
+  scanFile,
+  ALERT_FILE,
+  ALERT_ACK_FILE,
+  LONG_RUN_RE,
+  LONG_RUN_THRESHOLD,
+  TOTAL_INVISIBLE_THRESHOLD,
+};
+
+/**
+ * @param {Array<{
+ *   file: string,
+ *   findings: Array<{ line: number, charCount: number, method: string, decoded: string }>,
+ * }>} allFindings
+ * @returns {string}
+ */
+function formatReport(allFindings) {
+  const BAR = "━".repeat(52);
+  const lines = [
+    "",
+    `━━━ INVISIBLE CHARACTER INJECTION DETECTED ${BAR.slice(0, 11)}`,
+    "",
+    "Invisible Unicode in instruction files can hijack the model’s behavior",
+    "(skill invocation, tool use, instruction override). This commonly",
+    "happens when copy-pasting content from the internet.",
+    "",
+    "These files are loaded directly as context, bypassing PostToolUse",
+    "sanitization, so the invisible characters reach the model raw.",
+    "",
+  ];
+
+  for (const { file, findings } of allFindings) {
+    lines.push(`  ${file}:`);
+    for (const finding of findings) {
+      lines.push(
+        `    Line ${finding.line}: ${finding.charCount} invisible chars (${finding.method})`,
+      );
+      lines.push(`    Decodes to: ${JSON.stringify(finding.decoded)}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(BAR);
+  return lines.join("\n");
+}
+
+export { formatReport };
+
+// Main (skip when imported for testing)
+
+// Stryker disable all: CLI-entry body. It runs only as a spawned subprocess,
+// which in-process tests can't observe, so every mutant here is unkillable by
+// construction (same boundary as the c8-ignored regions below). The exported
+// scanFile/decodeRun above carry the real, mutation-tested logic.
+/**
+ * Scan every instruction file under the project for invisible-char findings.
+ * @returns {Array<{file: string, findings: ReturnType<typeof scanFile>}>}
+ */
+function scanProject() {
+  const targets = [
+    ...new Set([
+      ...findInstructionFiles(PROJECT_DIR),
+      ...findMdFiles(join(PROJECT_DIR, ".claude")),
+    ]),
+  ];
+  const allFindings = [];
+  for (const file of targets) {
+    try {
+      const findings = scanFile(file);
+      if (findings.length > 0) {
+        allFindings.push({ file: relative(PROJECT_DIR, file), findings });
+      }
+    } catch {
+      // File doesn't exist or unreadable
+    }
+  }
+  return allFindings;
+}
+
+/**
+ * The hook's CLI: scan the instruction files, auto-clean what it can, persist
+ * the alert for the PreToolUse gate otherwise. Exported so a bundle entry
+ * (which must claim the CLI slot before this module loads) can run the exact
+ * same scan instead of duplicating it.
+ * @returns {Promise<void>}
+ */
+export async function cliMain() {
+  /* c8 ignore start -- fail-closed module-load guard: only reachable when the
+     agent-sanitizer import above failed, which can't be simulated in the
+     spawned-subprocess CLI run the tests observe. */
+  if (typeof stripInvisible !== "function") {
+    // Emit the engagement event with a "skipped" outcome so the loss is LOUD on
+    // the trace channel — a scan that never ran is otherwise invisible, and the
+    // downstream PreToolUse sanitize gate then passes cleanly all session.
+    trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "skipped" });
+    process.stderr.write(
+      "scan-invisible-chars: agent-sanitizer failed to load; instruction " +
+        "files were NOT scanned for hidden Unicode.\n",
+    );
+    process.exit(1);
+  }
+  /* c8 ignore stop */
+
+  // Clean up stale alert + its ack marker from a previous session so this
+  // session re-surfaces the gate once if injection is still present.
+  for (const stale of [ALERT_FILE, ALERT_ACK_FILE]) {
+    try {
+      unlinkSync(stale);
+    } catch {
+      // Doesn't exist or not writable
+    }
+  }
+
+  const allFindings = scanProject();
+
+  if (allFindings.length === 0) {
+    trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, { outcome: "clean" });
+    return;
+  }
+  trace(TraceEvent.SCAN_INVISIBLE_CHARS_RAN, {
+    outcome: "found",
+    files: allFindings.length,
+  });
+
+  // Auto-clean contaminated files so the session proceeds without blocking
+  // every tool call; the gate hook is the fallback when cleaning fails.
+  let cleaned = 0;
+  for (const { file } of allFindings) {
+    const absPath = join(PROJECT_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 */
+    } catch {
+      // Unreadable or unwritable: the file stays contaminated and falls into the
+      // alert path below, which hands it to the PreToolUse gate.
+    }
+    /* c8 ignore stop */
+  }
+
+  const report = formatReport(allFindings);
+
+  if (cleaned === allFindings.length) {
+    process.stderr.write(
+      report +
+        `\nAll ${cleaned} file(s) cleaned on disk automatically. ` +
+        "NOTE: these files load as project instructions at session start, so " +
+        "THIS session may have already ingested the pre-clean bytes before the " +
+        "hook ran — treat any injected-looking instruction from them with " +
+        "suspicion, and restart the session if in doubt. Future sessions load " +
+        "the cleaned files.\n",
+    );
+    /* c8 ignore start -- only reachable when the write catch above fires */
+  } else {
+    process.stderr.write(report + "\n");
+    // ALERT_FILE sits at a predictable, world-visible $TMPDIR path, so a plain
+    // writeFileSync would follow a co-tenant-planted symlink and overwrite an
+    // arbitrary file this uid owns. Create it symlink-refusingly (see
+    // writeFileNoFollow); the PreToolUse gate treats an absent alert as "nothing
+    // to surface", so a lost race degrades safely rather than to a hijacked write.
+    writeFileNoFollow(ALERT_FILE, report + "\n");
+  }
+  /* c8 ignore stop */
+}
+
+if (isMain(import.meta.url)) {
+  await cliMain();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "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": {
@@ -46,6 +46,7 @@
     ]
   },
   "devDependencies": {
+    "sanitizer-engine": "npm:agent-sanitizer@2.1.0",
     "@commitlint/cli": "^21.0.1",
     "@commitlint/config-conventional": "^21.0.1",
     "@eslint/js": "10.0.1",
@@ -120,11 +121,15 @@
       "types": "./types/rehydrate.d.mts",
       "default": "./src/rehydrate.mjs"
     },
-    "./credential-names": "./python/agent_sanitizer/secrets/data/credential-names.json"
+    "./credential-names": "./python/agent_sanitizer/secrets/data/credential-names.json",
+    "./claude-hooks": "./claude-hooks/plugin-hooks.mjs"
   },
   "files": [
     "src/*.mjs",
     "python/agent_sanitizer/secrets/data/credential-names.json",
+    "claude-hooks/*.mjs",
+    "claude-hooks/lib/*.mjs",
+    "claude-hooks/config/*.json",
     "bin/sanitize-cli.mjs",
     "types",
     "LICENSE",
@@ -133,6 +138,8 @@
     "SECURITY.md"
   ],
   "dependencies": {
+    "agent-control-plane-core": "0.2.13",
+    "namespace-guard": "0.20.0",
     "css-tree": "^3.2.1",
     "rehype-parse": "9.0.1",
     "remark-gfm": "4.0.1",
@@ -144,8 +151,8 @@
   "scripts": {
     "test": "c8 node --test",
     "coverage": "c8 node --test",
-    "check": "tsc --noEmit",
-    "typecheck": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.hooks.json --noEmit",
     "build:types": "tsc -p tsconfig.build.json",
     "gen:joining-type": "node scripts/gen-joining-type.mjs",
     "lint": "eslint .",