agent-sanitizer 2.58.10 → 2.59.0

package/claude-hooks/lib/redactor-client.mjs

@@ -11,11 +11,10 @@
  * retries from scratch. If the socket is absent or dead we (re)spawn the daemon
  * once and retry — a crashed daemon self-heals on the next redaction.
  *
- * Wire protocol (both directions): a 4-byte big-endian unsigned length prefix
- * then that many bytes of UTF-8 JSON. Request {text, map, web_ingress,
- * env_secrets}; response is the same object the redactor's one-shot CLI would
- * print, or JSON null for the "nothing to redact" case, or {error} when the
- * daemon could not vet input.
+ * Wire protocol: python/agent_sanitizer/secrets/data/redactor-protocol.json,
+ * which the daemon reads too — the framing, the frame cap, and the exact shape
+ * of every request and response. A response that matches no shape the request
+ * allows fails closed.
  */
 import { spawn } from "node:child_process";
 import {
@@ -24,35 +23,31 @@ import {
 } from "./hook-timing.mjs";
 import { existsSync, lstatSync } from "node:fs";
 import { createConnection } from "node:net";
-import { tmpdir, userInfo } from "node:os";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { envBoundSecretVars } from "./env-config.mjs";
+import {
+  FRAME_CAP,
+  FrameReader,
+  PROTOCOL,
+  conforms,
+  encodeFrame,
+  isPlainObject,
+} from "./redactor-wire.mjs";
+import { currentUid, isPrivateDir, ownedByCurrentUser } from "./hook-io.mjs";
+import { readKnob } from "./knobs.mjs";
 
-// Refuse absurd frames rather than buffer unbounded (mirrors the daemon's cap).
-export const FRAME_CAP = 16 * 1024 * 1024;
+export { FRAME_CAP };
 
-/**
- * Parse a millisecond deadline from an env override, falling back to `fallback`
- * unless the value is a finite positive number. A bare `Number(env) || fallback`
- * silently accepts a NEGATIVE override (`-5 || 8000` is -5) — a non-positive
- * deadline makes the fail-closed wait/request return immediately, defeating the
- * deadline. Unset/blank/NaN/<=0 all take the sane positive fallback; a load-time
- * throw is deliberately avoided so a misconfigured env can never crash these
- * fail-closed hooks into a fail-OPEN non-load.
- * @param {string|undefined} raw the env override value
- * @param {number} fallback the sane positive default
- * @returns {number}
- */
-export function positiveMsOr(raw, fallback) {
-  const ms = Number(raw);
-  return Number.isFinite(ms) && ms > 0 ? ms : fallback;
-}
+// Published here, where hosts already import it; the parser behind every
+// millisecond knob lives with the knob table.
+export { positiveMsOr } from "./knobs.mjs";
 
 // Per-session private socket. The daemon binds it 0600 under a 0700 dir AFTER
 // priming, so its mere existence means "ready". Overridable for tests.
 export const DEFAULT_SOCKET_PATH =
-  process.env._AGENT_SANITIZER_REDACTOR_SOCKET ||
+  readKnob("_AGENT_SANITIZER_REDACTOR_SOCKET") ??
   join(tmpdir(), "agent-sanitizer-redactor", "redactor.sock");
 
 /**
@@ -71,7 +66,7 @@ export const DEFAULT_SOCKET_PATH =
  * @returns {string[]}
  */
 function daemonCommand() {
-  const configured = process.env._AGENT_SANITIZER_REDACTOR_DAEMON;
+  const configured = readKnob("_AGENT_SANITIZER_REDACTOR_DAEMON");
   if (configured) return [configured];
   // Inside the built bundle import.meta.url is .../plugin/dist/hooks/<bundle>,
   // so the committed zipapp sits one level up; from the raw sources no such
@@ -83,10 +78,7 @@ function daemonCommand() {
 // How long to wait for a freshly-spawned daemon to start accepting. A cold start
 // pays the detect-secrets import + plugin prime (~1-3s), so the default leaves
 // margin; tests shorten it to exercise the give-up-and-fail-closed path quickly.
-const WAIT_DEADLINE_MS = positiveMsOr(
-  process.env._AGENT_SANITIZER_REDACTOR_WAIT_MS,
-  8000,
-);
+const WAIT_DEADLINE_MS = readKnob("_AGENT_SANITIZER_REDACTOR_WAIT_MS");
 
 // A daemon that ACCEPTS the connection but then stalls — a deadlock, a
 // pathological detect-secrets input, or a half-written length prefix that never
@@ -100,7 +92,7 @@ const WAIT_DEADLINE_MS = positiveMsOr(
 // timeout (two connects + the spawn wait must fit); tests shorten it via the env
 // override (read per call) or the deadlineMs parameter to exercise the path fast.
 function requestDeadlineMs() {
-  return positiveMsOr(process.env._AGENT_SANITIZER_REDACTOR_REQUEST_MS, 20000);
+  return readKnob("_AGENT_SANITIZER_REDACTOR_REQUEST_MS");
 }
 
 /**
@@ -196,18 +188,18 @@ function failClosed(cause) {
  * `lstat`/`uid` are injectable seams so a test can drive a stat shape the test
  * process cannot create (a dir owned by another uid); production binds the real ones.
  * @param {string} socketPath
- * @param {{lstat?: typeof lstatSync, uid?: number}} [deps]
+ * @param {{lstat?: typeof lstatSync, uid?: number | null}} [deps]
  * @returns {"absent" | "untrusted" | "ok"}
  */
 export function classifySocket(socketPath, deps = {}) {
-  const { lstat = lstatSync, uid = userInfo().uid } = deps;
+  const { lstat = lstatSync, uid = currentUid() } = deps;
   let st;
   try {
     st = lstat(socketPath);
   } catch {
     return "absent";
   }
-  if (!st.isSocket() || st.uid !== uid) return "untrusted";
+  if (!st.isSocket() || !ownedByCurrentUser(st, uid)) return "untrusted";
   let dir;
   try {
     dir = lstat(dirname(socketPath));
@@ -241,25 +233,23 @@ export function classifySocket(socketPath, deps = {}) {
  * root to hand it to: there the hook spawns the daemon as the ordinary user, which
  * binds under a 0700 dir it owns, and our own uid is not the adversary.
  * @param {import("node:fs").Stats} dir
- * @param {number} uid
+ * @param {number | null} uid
  * @returns {boolean}
  */
 function isTrustedSocketDir(dir, uid) {
-  return (
-    dir.isDirectory() &&
-    (dir.uid === uid || dir.uid === 0) &&
-    (dir.mode & 0o022) === 0
-  );
+  return isPrivateDir(dir, { uid, rootMayOwn: true });
 }
 
 /**
  * Open one connection, send `request`, resolve with the parsed response object
  * (or null). Rejects on connect failure, a malformed/oversize/short frame, or an
  * {error} response — every one of which the caller turns into a fail-closed. A
- * socket present but not owned by us fails closed WITHOUT respawning (the error
- * carries no errno, so isRespawnable is false), so we never dial into a squat.
+ * socket present but not owned by us, and a request the protocol does not
+ * accept, fail closed WITHOUT dialing (the error carries no errno, so
+ * isRespawnable is false): we never dial into a squat, and an oversize request
+ * is not mistaken for a dead daemon worth respawning.
  * @param {string} socketPath
- * @param {{text: string, map: boolean, web_ingress: boolean}} request
+ * @param {Record<string, unknown>} request
  * @param {number} [deadlineMs] total exchange deadline; defaults to the env-tunable value
  * @returns {Promise<RedactResponse|null>}
  */
@@ -277,16 +267,15 @@ export function connectAndRequest(
       );
       return;
     }
+    if (!conforms(request, PROTOCOL.request)) {
+      reject(new Error("redactor request does not match the wire protocol"));
+      return;
+    }
+    // Encoded before dialing: an over-cap request throws here, rejecting with
+    // no errno, so it is not mistaken for a dead daemon worth respawning.
+    const frame = encodeFrame(request);
     const sock = createConnection(socketPath);
-    /** @type {Buffer[]} */
-    const chunks = [];
-    // Running total of buffered bytes, so we never re-concat the whole backlog on
-    // every 'data' event (that would be O(n^2) in the response size). We concat at
-    // most twice: once to read the 4-byte header if it straddles chunks, once to
-    // slice the full frame — both O(n) overall.
-    let received = 0;
-    /** @type {number|null} */
-    let expected = null;
+    const reader = new FrameReader();
     // Total deadline for the whole connect→request→response exchange, cleared by
     // finish() on the first terminal event. A stalled daemon (post-connect
     // silence) trips it and fails the call closed instead of hanging the hook.
@@ -304,41 +293,31 @@ export function connectAndRequest(
       () => finish(reject, new Error("redactor response timeout")),
       deadlineMs,
     );
-    // The bytes buffered so far as one Buffer, copying only when more than one
-    // chunk is held (a single chunk — the common case — is returned as-is).
-    const joined = () =>
-      chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, received);
     sock.on("error", (err) => finish(reject, err));
-    sock.on("connect", () => {
-      const body = Buffer.from(JSON.stringify(request), "utf8");
-      const header = Buffer.allocUnsafe(4);
-      header.writeUInt32BE(body.length, 0);
-      sock.write(Buffer.concat([header, body]));
-    });
+    sock.on("connect", () => sock.write(frame));
     sock.on("data", (chunk) => {
-      // No setEncoding, so 'data' is always a Buffer at runtime; the cast tells the
-      // type checker that without a (never-taken, uncoverable) string branch.
-      chunks.push(/** @type {Buffer} */ (chunk));
-      received += chunk.length;
-      if (expected === null) {
-        if (received < 4) return;
-        expected = joined().readUInt32BE(0);
-        if (expected > FRAME_CAP) {
-          finish(reject, new Error("oversize response frame"));
-          return;
-        }
-      }
-      if (received < 4 + expected) return;
-      const buf = joined();
-      let parsed;
+      let frameRead;
       try {
-        parsed = JSON.parse(buf.subarray(4, 4 + expected).toString("utf8"));
+        // No setEncoding, so 'data' is always a Buffer at runtime.
+        frameRead = reader.push(/** @type {Buffer} */ (chunk));
       } catch (err) {
+        // Recovery: an over-cap or non-JSON frame fails THIS call closed.
         finish(reject, err);
         return;
       }
-      if (parsed && typeof parsed === "object" && "error" in parsed) {
-        finish(reject, new Error("daemon reported redaction failure"));
+      if (frameRead === undefined) return;
+      const parsed = frameRead.value;
+      if (isPlainObject(parsed) && "error" in parsed) {
+        // The daemon's error strings are fixed literals, never request data.
+        const reason = conforms(parsed, PROTOCOL.responses.error)
+          ? `: ${parsed.error}`
+          : "";
+        finish(
+          reject,
+          new Error(
+            `daemon reported redaction failure${reason}; its log is ${join(dirname(socketPath), "daemon.log")}`,
+          ),
+        );
         return;
       }
       finish(resolve, parsed);
@@ -349,43 +328,81 @@ export function connectAndRequest(
   });
 }
 
+// How much of a failed daemon's stderr is kept for the error message: the tail,
+// which is where a Python traceback names its exception.
+const STDERR_TAIL_CHARS = 2000;
+
+/**
+ * A spawned daemon, as far as the spawning hook can see it.
+ * @typedef {object} DaemonHandle
+ * @property {() => string | undefined} failure why the daemon died before it was
+ *   ready (its exit status and stderr tail), or undefined while it may still bind
+ * @property {() => void} release stop reading its stderr
+ */
+
 /**
  * Spawn the daemon detached so it outlives this hook process. The daemon's bind()
- * is the cross-process mutex, so a racing second spawn just exits — the spawn is
- * idempotent and needs no lock here.
+ * is the cross-process mutex, so a racing second spawn just exits 0 — the spawn
+ * is idempotent and needs no lock here.
+ *
+ * Its stderr is piped back so a daemon that dies on startup (an import error, a
+ * refused cache directory) fails the call at once with its own reason rather than
+ * after the whole spawn wait with none. The daemon points its stderr at a log
+ * file before it publishes the socket, so the pipe is only read until then.
  * @param {string} socketPath
  * @param {string[]} [command] daemon command as [argv0, ...leadingArgs]
  * (injectable so tests can drive the missing-binary arm in-process;
  * production always uses daemonCommand())
+ * @returns {DaemonHandle}
  */
 export function spawnDaemon(socketPath, command = daemonCommand()) {
   const [bin, ...leading] = command;
   const child = spawn(bin, [...leading, socketPath], {
     detached: true,
-    stdio: "ignore",
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  const stderr = /** @type {import("node:net").Socket} */ (child.stderr);
+  let output = "";
+  /** @type {string | undefined} */
+  let failure;
+  stderr.setEncoding("utf8");
+  stderr.on("data", (/** @type {string} */ chunk) => {
+    output = (output + chunk).slice(-STDERR_TAIL_CHARS);
   });
   // A missing daemon binary surfaces as an async 'error' event; UNHANDLED it
   // kills this hook process, which the harness reads as "no objection" — the
-  // tool output would pass through UNSANITIZED (fail open). Swallowed, the
-  // daemon simply never binds and waitForSocket's deadline fails the call
-  // CLOSED, the declared posture for an unreachable redactor.
-  child.on("error", () => {});
+  // tool output would pass through UNSANITIZED (fail open). Recorded instead,
+  // it ends the spawn wait and fails the call CLOSED.
+  child.on("error", (err) => {
+    failure = err.message;
+  });
+  // 'close', not 'exit': it fires after stderr has drained, so the tail is whole.
+  // Exit 0 is the daemon that lost the bind race to a live one.
+  child.on("close", (code, signal) => {
+    if (code === 0) return;
+    const status = signal ? `killed by ${signal}` : `exit ${code}`;
+    const tail = output.trim();
+    failure ??= tail ? `${status}: ${tail}` : status;
+  });
   child.unref();
+  stderr.unref();
+  return { failure: () => failure, release: () => stderr.destroy() };
 }
 
 /**
- * Poll until the daemon is accepting connections or the deadline passes. Probes by
- * connecting (not just existsSync) so it waits for listen(), not merely bind().
+ * Poll until the daemon is accepting connections, the deadline passes, or
+ * `abandon` reports the spawned daemon dead. Probes by connecting (not just
+ * existsSync) so it waits for listen(), not merely bind().
  * @param {string} socketPath
- * @param {{deadlineMs?: number, stepMs?: number}} [opts]
+ * @param {{deadlineMs?: number, stepMs?: number, abandon?: () => boolean}} [opts]
  * @returns {Promise<boolean>}
  */
 export async function waitForSocket(
   socketPath,
-  { deadlineMs = WAIT_DEADLINE_MS, stepMs = 100 } = {},
+  { deadlineMs = WAIT_DEADLINE_MS, stepMs = 100, abandon = () => false } = {},
 ) {
   const deadline = Date.now() + deadlineMs;
-  while (Date.now() < deadline) {
+  while (Date.now() < deadline && !abandon()) {
     if (existsSync(socketPath) && (await canConnect(socketPath))) return true;
     await sleep(stepMs);
   }
@@ -422,17 +439,26 @@ function canConnect(socketPath) {
  * budget fails CLOSED without dialing — never dial with a non-positive deadline,
  * which would race and could return the raw, unvetted secret (fail open). Omitted,
  * the redactor keeps its own per-call request deadline (the standalone default).
+ *
+ * `webIngress` is required: it chooses between the name-trusting heuristics for
+ * local output and the stricter ones for attacker-controlled text, and a
+ * default would make that choice silently for any caller that forgot it.
  * @param {string} text
- * @param {{map?: boolean, webIngress?: boolean, socketPath?: string,
+ * @param {{map?: boolean, webIngress: boolean, socketPath?: string,
  *   deadline?: {remainingMs: () => number},
- *   connect?: typeof connectAndRequest, spawn?: typeof spawnDaemon,
- *   waitForSocket?: typeof waitForSocket, now?: () => number}} [opts]
+ *   connect?: typeof connectAndRequest,
+ *   spawn?: (socketPath: string) => DaemonHandle | void,
+ *   waitForSocket?: typeof waitForSocket, now?: () => number}} opts
  * @returns {Promise<RedactResponse|null>}
  */
-export async function redactViaDaemon(text, opts = {}) {
+export async function redactViaDaemon(text, opts) {
+  if (typeof opts?.webIngress !== "boolean")
+    throw new TypeError(
+      "redactViaDaemon: opts.webIngress must be true (attacker-controlled text) or false (local output)",
+    );
   const {
     map = false,
-    webIngress = false,
+    webIngress,
     socketPath = DEFAULT_SOCKET_PATH,
     deadline,
     connect = connectAndRequest,
@@ -459,36 +485,33 @@ export async function redactViaDaemon(text, opts = {}) {
     web_ingress: webIngress,
     env_secrets: collectEnvSecrets(),
   };
-  // Response-contract guard — every out-of-contract shape fails CLOSED, because a
-  // caller reading a field the daemon didn't set gets `undefined` and would proceed
-  // on unvetted content (fail OPEN). null (nothing to redact) is in-contract in both
-  // modes. Plain mode: `{text, found}` — text must be a string. Map mode: the
-  // `{unmappable}` marker (the daemon could not build a reversible map, so the
-  // caller suppresses) OR a `{text, pairs}` map — string text AND an array of pairs;
-  // a bare `{}` or a missing/non-array `pairs` is refused, since rehydrateRedacted
-  // reading `result.pairs` on it would silently emit the original secret-shaped
-  // content. Validated AFTER the respawn/retry logic so a malformed response is not
-  // mistaken for a dead socket worth respawning.
-  // Each throw carries the BARE cause: every call sits inside a catch that
-  // wraps what it caught, so wrapping here too would nest the sentence in itself.
-  /** @param {RedactResponse|null} result @returns {RedactResponse|null} */
+  // Response-contract guard — every shape the protocol does not allow for this
+  // mode fails CLOSED, because a caller reading a field the daemon didn't set
+  // gets `undefined` and would proceed on unvetted content (fail OPEN). Plain
+  // mode: `{text, found}`, or null for nothing to redact. Map mode: a
+  // `{text, pairs, found}` map or the `{unmappable}` marker — never null, since
+  // the daemon always answers a map request with one of the two. Validated AFTER
+  // the respawn/retry logic so a malformed response is not mistaken for a dead
+  // socket worth respawning. Each throw carries the BARE cause: every call sits
+  // inside a catch that wraps what it caught.
+  const { responses } = PROTOCOL;
+  /** @param {unknown} result @returns {RedactResponse|null} */
   const validate = (result) => {
-    if (result === null) return null;
     if (map) {
       if (
-        result?.unmappable === undefined &&
-        !(typeof result?.text === "string" && Array.isArray(result?.pairs))
+        !conforms(result, responses.map) &&
+        !conforms(result, responses.unmappable)
       )
         throw new Error(
-          "redactor returned a malformed map response (no `unmappable` marker and no `{text, pairs}` map)",
+          "redactor returned a malformed map response (neither `{text, pairs, found}` nor `{unmappable}`)",
         );
-      return result;
+      return /** @type {RedactResponse} */ (result);
     }
-    if (typeof result?.text !== "string")
+    if (result !== null && !conforms(result, responses.plain))
       throw new Error(
-        "redactor returned a malformed plain response (no string `text`)",
+        "redactor returned a malformed plain response (neither null nor `{text, found}`)",
       );
-    return result;
+    return /** @type {RedactResponse|null} */ (result);
   };
   // Every dial is charged to the redactor share, so the slow-hook notice can
   // place the wait in this call rather than guess at it: the daemon is a
@@ -509,7 +532,7 @@ export async function redactViaDaemon(text, opts = {}) {
     // Socket absent or dead: (re)spawn the daemon, wait for it, retry exactly once
     // — but only if the shared budget still has room for a cold start + a scan.
     if (budgetSpent()) throw outOfBudget("before redactor respawn");
-    spawnFn(socketPath);
+    const daemon = spawnFn(socketPath) ?? undefined;
     // Clamp the cold-start wait to what the budget still allows, so a respawn can
     // never blow it. waitForSocket returns false when the daemon never bound
     // within the deadline; surface that as the actual cause rather than the opaque
@@ -519,18 +542,30 @@ export async function redactViaDaemon(text, opts = {}) {
       budgetMs === undefined
         ? WAIT_DEADLINE_MS
         : Math.min(WAIT_DEADLINE_MS, budgetMs);
-    const waitOpts =
-      budgetMs === undefined ? undefined : { deadlineMs: waitMs };
+    const waitOpts = {
+      deadlineMs: waitMs,
+      abandon: () => daemon?.failure() !== undefined,
+    };
     // The cold-start wait is PROVISIONING — a one-time detect-secrets import and
     // plugin prime (~1-3s, see WAIT_DEADLINE_MS), paid by whichever tool call
     // happens to be first and by no other. Charging it to this hook would make
     // the slow-hook notice fire once per session on a healthy install.
-    if (!(await excludeProvisioning(() => waitFn(socketPath, waitOpts), now)))
+    const ready = await excludeProvisioning(
+      () => waitFn(socketPath, waitOpts),
+      now,
+    );
+    daemon?.release();
+    const died = daemon?.failure();
+    if (!ready)
       throw failClosed(
-        // The CLAMPED wait, since that is what actually elapsed: naming
-        // WAIT_DEADLINE_MS tells an operator debugging a 200ms budget that the
-        // redactor got seconds it was never given.
-        new Error(`redactor daemon did not start within ${waitMs}ms`),
+        new Error(
+          died === undefined
+            ? // The CLAMPED wait, since that is what actually elapsed: naming
+              // WAIT_DEADLINE_MS tells an operator debugging a 200ms budget
+              // that the redactor got seconds it was never given.
+              `redactor daemon did not start within ${waitMs}ms`
+            : `redactor daemon failed to start (${died})`,
+        ),
       );
     if (budgetSpent()) throw outOfBudget("after redactor respawn");
     try {

package/claude-hooks/lib/redactor-wire.mjs

@@ -0,0 +1,145 @@
+/**
+ * The redactor daemon's wire protocol, on the Node side: the one codec every
+ * party that speaks it here (the client, and the stand-in daemons the tests
+ * serve) derives from.
+ *
+ * The protocol itself is python/agent_sanitizer/secrets/data/redactor-protocol.json,
+ * which the Python daemon reads too: the frame cap and the exact shape of every
+ * request and response. A frame is a 4-byte big-endian body length, then that
+ * many bytes of UTF-8 JSON, in both directions.
+ */
+import PROTOCOL from "../../python/agent_sanitizer/secrets/data/redactor-protocol.json" with { type: "json" };
+
+export { PROTOCOL };
+
+// Refuse absurd frames rather than buffer unbounded, in either direction.
+export const FRAME_CAP = PROTOCOL.frame_cap;
+
+const HEADER_BYTES = 4;
+
+/** @typedef {Record<string, string>} Shape protocol field name -> field type */
+
+/**
+ * Whether `value` is of protocol field type `kind` (see the protocol file's
+ * description). An unknown type throws: it is a defect in the protocol file,
+ * never a verdict on the value.
+ * @param {unknown} value
+ * @param {string} kind
+ * @returns {boolean}
+ */
+function hasType(value, kind) {
+  switch (kind) {
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "index":
+      return Number.isSafeInteger(value) && /** @type {number} */ (value) >= 0;
+    case "string-list":
+      return Array.isArray(value) && value.every((v) => typeof v === "string");
+    case "string-map":
+      return (
+        isPlainObject(value) &&
+        Object.values(value).every((v) => typeof v === "string")
+      );
+    case "pair-list":
+      return (
+        Array.isArray(value) && value.every((v) => conforms(v, PROTOCOL.pair))
+      );
+    default:
+      throw new Error(`unknown protocol field type ${JSON.stringify(kind)}`);
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether `value` is an object with exactly `shape`'s fields, each of its
+ * declared protocol type.
+ * @param {unknown} value
+ * @param {Shape} shape
+ * @returns {boolean}
+ */
+export function conforms(value, shape) {
+  if (!isPlainObject(value)) return false;
+  const names = Object.keys(shape);
+  return (
+    Object.keys(value).length === names.length &&
+    names.every(
+      (name) => Object.hasOwn(value, name) && hasType(value[name], shape[name]),
+    )
+  );
+}
+
+/**
+ * One frame carrying `value`. Throws (with no errno, so the client does not
+ * mistake it for a dead daemon) when the body exceeds the frame cap, which the
+ * peer would refuse unread.
+ * @param {unknown} value
+ * @returns {Buffer}
+ */
+export function encodeFrame(value) {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  if (body.length > FRAME_CAP) {
+    throw new Error(
+      `redactor frame of ${body.length} bytes exceeds the ${FRAME_CAP}-byte frame cap`,
+    );
+  }
+  const header = Buffer.allocUnsafe(HEADER_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * Reassembles one frame from the chunks a stream delivers. Holds a running
+ * byte total so the backlog is concatenated at most twice (header, then the
+ * whole frame) rather than on every chunk, which would be quadratic.
+ */
+export class FrameReader {
+  /** @type {Buffer[]} */
+  #chunks = [];
+  #received = 0;
+  /** @type {number | null} */
+  #expected = null;
+
+  /**
+   * Feed one chunk. Returns `{ value }` once the whole frame has arrived and
+   * undefined before then; throws on a header over the frame cap or a body
+   * that is not JSON.
+   * @param {Buffer} chunk
+   * @returns {{ value: unknown } | undefined}
+   */
+  push(chunk) {
+    this.#chunks.push(chunk);
+    this.#received += chunk.length;
+    if (this.#expected === null) {
+      if (this.#received < HEADER_BYTES) return undefined;
+      this.#expected = this.#joined().readUInt32BE(0);
+      if (this.#expected > FRAME_CAP) {
+        throw new Error(
+          `redactor frame header claims ${this.#expected} bytes, over the ${FRAME_CAP}-byte frame cap`,
+        );
+      }
+    }
+    const end = HEADER_BYTES + this.#expected;
+    if (this.#received < end) return undefined;
+    return {
+      value: JSON.parse(
+        this.#joined().subarray(HEADER_BYTES, end).toString("utf8"),
+      ),
+    };
+  }
+
+  /** The bytes buffered so far, copying only when more than one chunk is held. */
+  #joined() {
+    return this.#chunks.length === 1
+      ? this.#chunks[0]
+      : Buffer.concat(this.#chunks, this.#received);
+  }
+}

package/claude-hooks/lib/reveal.mjs

@@ -31,9 +31,10 @@ import {
   closeSync,
   constants,
 } from "node:fs";
-import { tmpdir, userInfo } from "node:os";
+import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { PROJECT_HASH, writeFileNoFollow } from "./hook-io.mjs";
+import { PROJECT_HASH, isPrivateDir, writeFileNoFollow } from "./hook-io.mjs";
+import { readKnob } from "./knobs.mjs";
 
 /**
  * Where reveal sidecars are stored. Exported so the PreToolUse placeholder
@@ -48,7 +49,7 @@ export function revealDir() {
   // instead. The 12-hex span KEY inside the directory is untouched — it is the
   // published placeholder grammar, not a path detail.
   return (
-    process.env._AGENT_SANITIZER_REVEAL_DIR ||
+    readKnob("_AGENT_SANITIZER_REVEAL_DIR") ??
     join(tmpdir(), `agent-sanitizer-layer2-reveal-${PROJECT_HASH}`)
   );
 }
@@ -131,13 +132,7 @@ function revealDirIsSafe(dir) {
     return false;
   }
   /* c8 ignore stop */
-  const groupOrOtherWritable = (st.mode & 0o022) !== 0;
-  return (
-    st.isDirectory() &&
-    !st.isSymbolicLink() &&
-    st.uid === userInfo().uid &&
-    !groupOrOtherWritable
-  );
+  return isPrivateDir(st);
 }
 
 /**