agent-sanitizer 2.67.2 → 2.69.0

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

@@ -17,70 +17,25 @@ import charset from "../../python/agent_sanitizer/data/invisible-charset.json" w
 // 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.) That argument holds only while no literal is itself a
-// member of the class, so {@link envValueRegex} drops the value's own invisible
-// code points before it splices: `a<ZWSP>a` would otherwise build
-// `a[…]*<ZWSP>[…]*a`, whose two stars share the literal and backtrack
-// quadratically over a long run of ZWSP.
-const ENV_INVIS_CODEPOINTS = [
-  ...new Set([...charset.cf_codepoints, ...charset.extra_codepoints]),
-].sort((a, b) => a - b);
-const ENV_INVIS_SET = new Set(ENV_INVIS_CODEPOINTS);
-const ENV_INVIS_RUN =
+// tolerates (`_env_value_spans` in agent_sanitizer.secrets.engine), not
+// a hand-curated subset: a subset pre-gate silently under-matches whenever this
+// gate runs on text Layer 1 has not already stripped, and a value spliced with a
+// code point in the gap then never reaches the daemon at all.
+const ENV_INVIS_RE = new RegExp(
   "[" +
-  ENV_INVIS_CODEPOINTS.map((cp) => `\\u{${cp.toString(16)}}`).join("") +
-  "]*";
-
-/** @param {string} ch */
-const escapeLiteral = (ch) => ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    [...new Set([...charset.cf_codepoints, ...charset.extra_codepoints])]
+      .map((cp) => `\\u{${cp.toString(16)}}`)
+      .join("") +
+    "]",
+  "gu",
+);
 
 /**
- * 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 — 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}
+ * `s` with every charset invisible removed.
+ * @param {string} s
+ * @returns {string}
  */
-export function envValueRegex(value) {
-  let re = ENV_VALUE_REGEX_CACHE.get(value);
-  if (re === undefined) {
-    const visible = [...value].filter(
-      (ch) => !ENV_INVIS_SET.has(/** @type {number} */ (ch.codePointAt(0))),
-    );
-    // A value made only of invisibles has no literal to anchor a gap on: match
-    // it exactly rather than build a pattern that is nothing but gaps.
-    re = new RegExp(
-      visible.length > 0
-        ? visible.map(escapeLiteral).join(ENV_INVIS_RUN)
-        : [...value].map(escapeLiteral).join(""),
-      "u",
-    );
-    ENV_VALUE_REGEX_CACHE.set(value, re);
-  }
-  return re;
-}
-
-/** value → compiled matcher; see {@link envValueRegex}. */
-const ENV_VALUE_REGEX_CACHE = new Map();
+const stripInvisibles = (s) => s.replace(ENV_INVIS_RE, "");
 
 /**
  * True when tool output contains the literal value of a configured env-bound
@@ -88,19 +43,34 @@ const ENV_VALUE_REGEX_CACHE = new Map();
  * credential, so the pre-gate must also fire on the value itself — otherwise
  * the engine's env-bound redaction never runs. Invisible-tolerant so a
  * value with spliced Cf chars (which the daemon still redacts) trips it too.
+ *
+ * Both sides are stripped and compared as substrings, which is exactly
+ * equivalent: the value's visible characters appear contiguously in the
+ * stripped text iff they appear in the original separated only by invisibles.
+ * It is linear and independent of the value's length — a regex with an
+ * invisible class at every gap grows ~4 KB per character, and a long secret (a
+ * PEM key) overflows V8's regex size limit and throws on every output.
+ *
+ * Callers pass post-Layer-1 text: terminal escapes are already gone, so a value
+ * split by one is contiguous here. Raw text spliced with an escape is not
+ * matched.
  * @param {string} text
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {boolean}
  */
 export function hasEnvBoundSecret(text, env = process.env) {
   const minLen = minEnvSecretLen();
+  /** @type {string | undefined} */
+  let strippedText;
   return envBoundSecretVars(env).some((name) => {
     const value = env[name];
-    // Code-point length to match envValueRegex's code-point split — an astral
-    // char counts once, not as two UTF-16 units, so minLen means the same thing
-    // on both sides of the gate.
-    return (
-      value && [...value].length >= minLen && envValueRegex(value).test(text)
-    );
+    // Code-point length, so an astral char counts once, not as two UTF-16 units.
+    if (!value || [...value].length < minLen) return false;
+    const needle = stripInvisibles(value);
+    // A value made only of invisibles has no visible character to anchor on:
+    // match it exactly rather than as the empty string, which matches anything.
+    if (needle === "") return text.includes(value);
+    strippedText ??= stripInvisibles(text);
+    return strippedText.includes(needle);
   });
 }

package/claude-hooks/lib/secret-drop-guard.mjs

@@ -1,5 +1,6 @@
 /**
- * Clobber-by-omission guard for whole-file Writes.
+ * Clobber-by-omission guard for whole-file Writes, and the confirm-by-exact-
+ * re-issue sentinel it shares with every other releasable PreToolUse refusal.
  *
  * Rehydration (agent-sanitizer/rehydrate) only engages when a Write's content
  * carries a placeholder; a Write that REGENERATES a secret-bearing file and
@@ -65,12 +66,62 @@ export const CONFIRM_TTL_MS = 10 * 60_000;
  * @returns {string}
  */
 export function dropFingerprint(filePath, content, dropped = []) {
-  const digest = createHash("sha256").update(filePath).update("\0");
+  const digest = createHash("sha256").update("drop\0").update(filePath);
+  digest.update("\0");
   digest.update(content);
   for (const secret of dropped) digest.update("\0").update(secret);
   return digest.digest("hex").slice(0, 32);
 }
 
+/**
+ * Fingerprint of one refusal of one exact tool call — same refusing site, same
+ * tool, same input — released by re-issuing that call. Keyed on the site too, so
+ * a call refused by two sites in turn needs a confirmation for each and one
+ * re-issue never releases a refusal the model was not shown. The input is
+ * hashed in canonical key order, so a re-issue whose keys arrive reordered is
+ * still the same call. Distinct domain tags keep it disjoint from
+ * {@link dropFingerprint}.
+ * @param {string} site
+ * @param {unknown} tool
+ * @param {unknown} toolInput
+ * @returns {string}
+ */
+export function reissueFingerprint(site, tool, toolInput) {
+  return createHash("sha256")
+    .update("reissue\0")
+    .update(canonicalJson([site, tool ?? null, toolInput ?? null]))
+    .digest("hex")
+    .slice(0, 32);
+}
+
+/**
+ * JSON with every object's keys sorted, so two encodings of one value agree.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function canonicalJson(value) {
+  return JSON.stringify(value, (_key, v) =>
+    v !== null && typeof v === "object" && !Array.isArray(v)
+      ? Object.fromEntries(
+          Object.keys(v)
+            .sort()
+            .map((k) => [k, v[k]]),
+        )
+      : v,
+  );
+}
+
+/**
+ * Record a confirm sentinel for `fingerprint`, so the identical re-issue is
+ * approved by {@link consumeConfirm}. False when it could not be recorded: the
+ * caller then must not refuse, because nothing could ever release the refusal.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+export function recordConfirm(fingerprint) {
+  return writeSentinelFile(confirmMarkerPath(fingerprint));
+}
+
 /**
  * The confirm sentinel's path for one fingerprint. Predictable and
  * world-visible like the alert markers, hence the markerIsTrusted read.
@@ -81,6 +132,9 @@ export function confirmMarkerPath(fingerprint) {
   return join(tmpdir(), `.claude-secret-drop-${PROJECT_HASH}-${fingerprint}`);
 }
 
+/** readdir codes meaning the confirm store's directory cannot be used at all. */
+const UNUSABLE_DIR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
+
 /**
  * Delete this project's confirm sentinels older than {@link CONFIRM_TTL_MS}.
  *
@@ -95,7 +149,18 @@ export function sweepStaleConfirms() {
   const dir = tmpdir();
   const prefix = `.claude-secret-drop-${PROJECT_HASH}-`;
   const cutoff = Date.now() - CONFIRM_TTL_MS;
-  for (const name of readdirSync(dir)) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch (err) {
+    // An unusable $TMPDIR holds no sentinel to sweep, and recordConfirm already
+    // answers for it on every call; letting it throw here would abort the
+    // SessionStart scan this sweep merely rides along with.
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (UNUSABLE_DIR_CODES.has(String(code))) return;
+    throw err;
+  }
+  for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     const path = join(dir, name);
     try {
@@ -150,14 +215,34 @@ export function gitTracked(filePath, spawn = spawnSync) {
 /**
  * @param {number} count
  * @param {string} filePath
+ * @param {boolean} [confirmable] false when no confirmation could be recorded,
+ *   so the reason must not offer a re-issue that would only be refused again
  * @returns {string}
  */
-function dropDeny(count, filePath) {
-  return (
+function dropDeny(count, filePath, confirmable = true) {
+  const head =
     `this Write removes ${count} redacted secret value(s) from ${filePath}, and the ` +
-    `file is not tracked by git, so the secrets may be unrecoverable. If removing ` +
-    `them is intended, re-issue this exact Write to confirm; otherwise keep each ` +
-    `[REDACTED…] placeholder (or its secret's line) in the new content`
+    `file is not tracked by git, so the secrets may be unrecoverable. `;
+  const placeholders = `[REDACTED…] placeholder (or its secret's line) in the new content`;
+  return confirmable
+    ? `${head}If removing them is intended, re-issue this exact Write to confirm; ` +
+        `otherwise keep each ${placeholders}`
+    : `${head}Keep each ${placeholders}, or ask the user to remove them`;
+}
+
+/**
+ * The `fault` a drop deny carries when its confirmation could not be recorded:
+ * the deny could then never be released by a re-issue, so it is a sanitizer
+ * fault rather than a verdict, and the hook's fault posture decides it.
+ * @param {number} count
+ * @param {string} filePath
+ * @returns {string}
+ */
+function dropUnconfirmable(count, filePath) {
+  return (
+    `the secret-drop confirmation could not be recorded under ${tmpdir()}, so ` +
+    `this Write removes ${count} redacted secret value(s) from untracked ` +
+    `${filePath} without a confirmed re-issue`
   );
 }
 
@@ -167,22 +252,22 @@ function dropDeny(count, filePath) {
  * rehydration substituted any placeholders — so a preserved secret shows up as
  * its real value in `content`. `io` is the rehydrate-shaped I/O bag (readFile /
  * redact / redactMap). Injectable seams: `isTracked` (the git probe),
- * `confirmSeen`/`recordConfirm` (the sentinel state).
+ * `confirmSeen`/`recordConfirm` (the sentinel state). A deny whose confirmation
+ * could not be recorded carries `fault` (see {@link dropUnconfirmable}).
  * @param {{file_path?: unknown, content?: unknown}} toolInput
  * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
  * @param {{
  *   isTracked?: (filePath: string) => boolean,
  *   confirmSeen?: (fingerprint: string) => boolean,
- *   recordConfirm?: (fingerprint: string) => void,
+ *   recordConfirm?: (fingerprint: string) => boolean,
  * }} [opts]
- * @returns {Promise<{deny: string} | null>}
+ * @returns {Promise<{deny: string, fault?: string} | null>}
  */
 export async function secretDropGuard(toolInput, io, opts = {}) {
   const {
     isTracked = gitTracked,
     confirmSeen = consumeConfirm,
-    recordConfirm = (fingerprint) =>
-      writeSentinelFile(confirmMarkerPath(fingerprint)),
+    recordConfirm: record = recordConfirm,
   } = opts;
   const { file_path: filePath, content } = toolInput ?? {};
   if (typeof filePath !== "string" || typeof content !== "string") return null;
@@ -225,8 +310,11 @@ export async function secretDropGuard(toolInput, io, opts = {}) {
   // context, or a marker left by an abandoned attempt becomes a standing
   // auto-approval for a Write the user never saw.
   if (confirmSeen(fingerprint)) return null;
-  recordConfirm(fingerprint);
-  return { deny: dropDeny(dropped.length, filePath) };
+  if (record(fingerprint)) return { deny: dropDeny(dropped.length, filePath) };
+  return {
+    deny: dropDeny(dropped.length, filePath, false),
+    fault: dropUnconfirmable(dropped.length, filePath),
+  };
 }
 
 /**
@@ -235,8 +323,12 @@ export async function secretDropGuard(toolInput, io, opts = {}) {
  * substitution — so a rehydrated secret counts as preserved and only a
  * genuinely dropped one can trip it. A rehydrate deny short-circuits (the
  * guard never runs), non-Write tools skip the guard entirely, and a guard
- * deny wins over a pass/rewrite result.
- * @typedef {{updatedInput: any, context: string} | {deny: string} | null} RehydrateResult
+ * deny wins over a pass/rewrite result. A guard FAULT deny carries the
+ * rewrite as `release`: the open posture lets that call proceed, and it must
+ * proceed rehydrated, or every secret the rewrite restored is overwritten by
+ * its placeholder.
+ * @typedef {{updatedInput: any, context: string}} RehydrateRewrite
+ * @typedef {RehydrateRewrite | {deny: string, fault?: string, release?: RehydrateRewrite} | null} RehydrateResult
  * @param {(tool: string, toolInput: any) => Promise<RehydrateResult>} rehydrate
  * @param {import("agent-sanitizer/rehydrate").RehydrateIo} io
  * @param {typeof secretDropGuard} [guard]
@@ -250,33 +342,29 @@ export function withSecretDropGuard(rehydrate, io, guard = secretDropGuard) {
     const finalInput =
       rehydrated === null ? toolInput : rehydrated.updatedInput;
     const drop = await guard(finalInput, io);
-    return drop ?? rehydrated;
+    if (drop === null) return rehydrated;
+    if (drop.fault === undefined || rehydrated === null) return drop;
+    return { ...drop, release: rehydrated };
   };
 }
 
 /**
  * True when a trusted, fresh confirm sentinel exists for `fingerprint`,
- * consuming it so one confirmation approves exactly one Write. A sentinel
+ * consuming it so one confirmation approves exactly one call. A sentinel
  * older than {@link CONFIRM_TTL_MS} is stale — an abandoned deny from a
  * previous session, not a live confirmation — so it is removed and NOT
  * honored, preventing a leftover marker from acting as a standing
  * auto-approval. Removal is best-effort: a fresh marker we could not unlink
  * still counted as consumed for THIS call, and a leftover empty sentinel only
- * ever re-approves the identical (path, bytes, drop-set) Write the model
- * already confirmed — and only within the TTL.
+ * ever re-approves the identical fingerprinted call the model already
+ * confirmed — and only within the TTL.
  * @param {string} fingerprint
  * @returns {boolean}
  */
-function consumeConfirm(fingerprint) {
+export function consumeConfirm(fingerprint) {
   const marker = confirmMarkerPath(fingerprint);
   if (!markerIsTrusted(marker)) return false;
-  let fresh;
-  try {
-    fresh = Date.now() - lstatSync(marker).mtimeMs <= CONFIRM_TTL_MS;
-  } catch {
-    // Raced away between the trust check and the stat: no sentinel, no confirm.
-    return false;
-  }
+  const fresh = confirmFresh(fingerprint);
   try {
     unlinkSync(marker);
   } catch {
@@ -284,3 +372,22 @@ function consumeConfirm(fingerprint) {
   }
   return fresh;
 }
+
+/**
+ * True when a trusted confirm sentinel younger than {@link CONFIRM_TTL_MS}
+ * exists for `fingerprint`, WITHOUT consuming it — for a caller that learns
+ * only later whether the call it confirms actually proceeds, and consumes it
+ * then.
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+export function confirmFresh(fingerprint) {
+  const marker = confirmMarkerPath(fingerprint);
+  if (!markerIsTrusted(marker)) return false;
+  try {
+    return Date.now() - lstatSync(marker).mtimeMs <= CONFIRM_TTL_MS;
+  } catch {
+    // Raced away between the trust check and the stat: no sentinel, no confirm.
+    return false;
+  }
+}

package/claude-hooks/plugin-hooks.mjs

@@ -26,7 +26,6 @@ import {
 } from "./lib/hook-io.mjs";
 import {
   registerFaultPolicy,
-  KNOB_DECIDES,
   hookFaultOutcome,
   writeFaultOutcome,
 } from "./lib/hook-fault.mjs";
@@ -35,29 +34,31 @@ const HOOK_NAME = "plugin-hooks";
 
 // The dispatcher's entry in the one posture table (lib/hook-fault.mjs). It
 // answers no single event — it is the binder in front of all of them — so it
-// carries no stdout envelope and both arms are process-level.
+// carries no stdout envelope and both arms are process-level. Its one fault is
+// an unknown `--hook` mode: broken hooks.json wiring, so no hook runs for that
+// event until the install is fixed.
 //
-// BOTH ARMS BLOCK, and that is the declaration, not an oversight. The
-// AGENT_SANITIZER_FAIL_OPEN knob covers a hook that RAN and broke; an unknown
-// mode is static wiring corruption, which means no hook runs at all, silently,
-// for the life of the install — there is no run to degrade. Stating it here (and
-// pinning it in plugin/test/plugin-bundle.test.mjs) is the point of the table:
-// the arm that ignores the knob does so on the record, next to the ones that
-// honor it, instead of by hard-exiting past the question.
-//
-// Exit 2 is the one non-zero code Claude Code treats as BLOCKING: it blocks
-// PreToolUse and UserPromptSubmit, surfaces stderr for PostToolUse, and is
-// harmless for SessionStart.
-const unknownMode = (/** @type {{ message: string }} */ ctx) => ({
-  stderr: `${HOOK_NAME}: ${ctx.message}\n`,
-  exitCode: 2,
-});
+// OPEN exits 1, which Claude Code treats as a non-blocking hook error; through
+// plugin/scripts/safe-launch.sh it becomes that event's fail-open warning.
+// CLOSED exits 2, the one non-zero code Claude Code treats as BLOCKING: it
+// blocks PreToolUse and UserPromptSubmit, surfaces stderr for PostToolUse, and
+// is harmless for SessionStart.
+const unknownModeLine = (/** @type {{ message: string }} */ ctx) =>
+  `${HOOK_NAME}: ${ctx.message} — hooks.json names a hook this bundle does ` +
+  `not dispatch (known: ${HOOK_MODES.join(", ")}); reinstall or update the plugin.`;
 registerFaultPolicy(HOOK_NAME, {
   event: null,
   guarded: "hook payload",
-  alwaysClosed: KNOB_DECIDES,
-  open: unknownMode,
-  closed: unknownMode,
+  open: (ctx) => ({
+    stderr:
+      `${unknownModeLine(ctx)} This event is UNGUARDED; set ` +
+      "AGENT_SANITIZER_FAIL_OPEN=0 to block it instead.\n",
+    exitCode: 1,
+  }),
+  closed: (ctx) => ({
+    stderr: `${unknownModeLine(ctx)} Blocking (AGENT_SANITIZER_FAIL_OPEN=0).\n`,
+    exitCode: 2,
+  }),
 });
 
 // The packages the hooks lazy-load, each behind a thunk whose import specifier
@@ -90,7 +91,7 @@ const LAZY_LOADERS = {
  * as a non-blocking hook error and shows the raw tool output. That is a
  * fail-OPEN on the very hook that withholds secrets. Registering what resolves
  * and leaving the rest absent hands the gap to each hook's own lazyImport
- * guard, whose posture is to block.
+ * guard, which answers it loudly under the operator's fault posture.
  * @returns {Promise<void>}
  */
 async function registerAvailableModules() {
@@ -201,14 +202,16 @@ export async function main() {
     // some default hook and vet the wrong payload class. WHICH way it fails is
     // the operator's call, taken through the one posture table like every other
     // hook fault.
-    process.exit(
-      writeFaultOutcome(
-        hookFaultOutcome(
-          HOOK_NAME,
-          new Error(`unknown hook mode ${JSON.stringify(mode)}`),
-        ),
+    process.exitCode = writeFaultOutcome(
+      hookFaultOutcome(
+        HOOK_NAME,
+        new Error(`unknown hook mode ${JSON.stringify(mode)}`),
       ),
     );
+    // Drained like the disabled arm below: under the open posture the event
+    // proceeds, and a harness left writing into a closed pipe sees EPIPE.
+    process.stdin.resume();
+    return;
   }
 
   // An empty envelope is a verdict, not a crash: stdout stays non-empty, so the