agent-sanitizer 2.58.10 → 2.59.0

package/types/claude-hooks/lib/knobs.d.mts

@@ -0,0 +1,138 @@
+/**
+ * `raw` as a finite positive number of milliseconds, else `fallback`. A bare
+ * `Number(env) || fallback` silently accepts a NEGATIVE override (`-5 || 8000`
+ * is -5), and a non-positive deadline makes a fail-closed wait return at once.
+ * @param {string | undefined} raw
+ * @param {number} fallback
+ * @returns {number}
+ */
+export function positiveMsOr(raw: string | undefined, fallback: number): number;
+/**
+ * The parsed value of knob `name` in `env`. An unrecognized value is reported
+ * through `report` and reads as the knob's fallback; a name missing from
+ * {@link KNOBS} throws, since it is a wiring bug in this package rather than
+ * operator input.
+ * @template {keyof Knobs} K
+ * @param {K} name
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @param {(message: string) => void} [report]
+ * @returns {Knobs[K]["fallback"]}
+ */
+export function readKnob<K extends keyof Knobs>(name: K, env?: NodeJS.ProcessEnv | Record<string, string | undefined>, report?: (message: string) => void): Knobs[K]["fallback"];
+/**
+ * THE environment knobs the hooks and the CLI read, as one table.
+ *
+ * Every `AGENT_SANITIZER_*` / `_AGENT_SANITIZER_*` read goes through
+ * {@link readKnob}, which looks the name up here, parses the raw value with the
+ * entry's own grammar, and REPORTS a value the grammar does not recognize
+ * instead of silently treating it as unset. Seven hand-rolled parsers each
+ * decided that alone, and each failed the same way: `SECRETS_ENABLED=true`
+ * left the secret layer off, `FAIL_OPEN=FALSE` left the hooks open, and
+ * `MAX_INPUT_BYTES=0.5` became a zero-byte cap — all without a word.
+ *
+ * A bad value is reported, never thrown: these variables are set outside the
+ * session, so a throw (or a blocking verdict) would fail every tool call on a
+ * config value the session cannot edit. The entry's `fallback` is what the
+ * value then reads as, and `consequence` says so in the report.
+ *
+ * `test/claude-hooks-knobs.test.mjs` parses every hook module and the CLI and
+ * asserts the knobs they read are exactly this table, and that nothing reads
+ * one past {@link readKnob}.
+ */
+/**
+ * Values of AGENT_SANITIZER_FAIL_OPEN that select the fail-closed posture.
+ * Matched exactly: a case-insensitive match would need `tr`, which the launcher
+ * cannot reach (it runs its no-node arm on shell builtins alone).
+ *
+ * THE single source of truth for the closed set. The shell shims cannot import
+ * it, so `plugin/scripts/lib/fail-open.sh` is GENERATED from it by
+ * `scripts/gen-fail-open-lib.mjs` and committed; the round trip is asserted in
+ * plugin/test/fail-open-parity.test.mjs. Everything else that spells the set
+ * out by hand is an implementation that must appear in the parity table in
+ * tests/test_safe_launch.py.
+ */
+export const FAIL_CLOSED_VALUES: readonly string[];
+/** Every knob, by variable name. */
+export const KNOBS: Readonly<{
+    AGENT_SANITIZER_FAIL_OPEN: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_DISABLED_HOOKS: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_SECRETS_ENABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_FLAG_DIGEST_VALUES: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_INVISIBLE_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_TERMINAL_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_OUTPUT_DISABLED: Readonly<Knob<boolean> & {
+        surface: Surface;
+    }>;
+    AGENT_SANITIZER_MAX_INPUT_BYTES: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_EXTRA_SECRET_VARS: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_TRACE: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_TRACE_FILE: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_SOCKET: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_DAEMON: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_WAIT_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REDACTOR_REQUEST_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_SANITIZE_BUDGET_MS: Readonly<Knob<number> & {
+        surface: Surface;
+    }>;
+    _AGENT_SANITIZER_REVEAL_DIR: Readonly<Knob<string | undefined> & {
+        surface: Surface;
+    }>;
+}>;
+/**
+ * The operator knobs the plugin's shell launcher (plugin/scripts/) reads before
+ * any JS runs. They share plugin/README.md's knob tables with the `hooks`
+ * surface, so the tables document exactly these plus that surface; JS never
+ * reads them (the partition test holds JS reads to KNOBS).
+ */
+export const LAUNCHER_KNOBS: readonly string[];
+/**
+ * One knob: its grammar, the value an unrecognized input reads as, and the two
+ * halves of the report naming it.
+ */
+export type Knob<T> = {
+    parse: (raw: string | undefined) => T | typeof INVALID;
+    fallback: T;
+    expect: string;
+    consequence: string;
+};
+/**
+ * Who sets a knob, which is where it must be documented (asserted in
+ * test/claude-hooks-knobs.test.mjs):
+ *   - `hooks`: a Claude Code plugin operator — plugin/README.md's knob tables;
+ *   - `cli`: a caller of bin/sanitize-cli.mjs — README.md;
+ *   - `internal`: `_`-prefixed plumbing hooks.json and tests set — no stable
+ *     interface, so documented nowhere by name.
+ */
+export type Surface = "hooks" | "cli" | "internal";
+export type Knobs = typeof KNOBS;
+/** What a parser returns for a value its grammar does not recognize. */
+declare const INVALID: unique symbol;
+export {};

package/types/claude-hooks/lib/redactor-client.d.mts

@@ -1,16 +1,3 @@
-/**
- * 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: string | undefined, fallback: number): number;
 /**
  * The shape the redactor returns: plain mode `{text, found}`, map mode
  * `{text, pairs, found}` or `{unmappable}`. All fields optional so a consumer
@@ -40,49 +27,62 @@ export function positiveMsOr(raw: string | undefined, fallback: number): number;
  * `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: string, deps?: {
     lstat?: typeof lstatSync;
-    uid?: number;
+    uid?: number | null;
 }): "absent" | "untrusted" | "ok";
 /**
  * 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>}
  */
-export function connectAndRequest(socketPath: string, request: {
-    text: string;
-    map: boolean;
-    web_ingress: boolean;
-}, deadlineMs?: number): Promise<RedactResponse | null>;
+export function connectAndRequest(socketPath: string, request: Record<string, unknown>, deadlineMs?: number): Promise<RedactResponse | null>;
+/**
+ * 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: string, command?: string[]): void;
+export function spawnDaemon(socketPath: string, command?: string[]): DaemonHandle;
 /**
- * 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 function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
+export function waitForSocket(socketPath: string, { deadlineMs, stepMs, abandon }?: {
     deadlineMs?: number;
     stepMs?: number;
+    abandon?: () => boolean;
 }): Promise<boolean>;
 /**
  * Redact `text` via the daemon. Returns the response object (`{text, found}` for
@@ -96,26 +96,32 @@ export function waitForSocket(socketPath: string, { deadlineMs, stepMs }?: {
  * 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 function redactViaDaemon(text: string, opts?: {
+export function redactViaDaemon(text: string, opts: {
     map?: boolean;
-    webIngress?: boolean;
+    webIngress: boolean;
     socketPath?: string;
     deadline?: {
         remainingMs: () => number;
     };
     connect?: typeof connectAndRequest;
-    spawn?: typeof spawnDaemon;
+    spawn?: (socketPath: string) => DaemonHandle | void;
     waitForSocket?: typeof waitForSocket;
     now?: () => number;
 }): Promise<RedactResponse | null>;
-export const FRAME_CAP: number;
+export { FRAME_CAP };
+export { positiveMsOr } from "./knobs.mjs";
 export const DEFAULT_SOCKET_PATH: string;
 /**
  * The shape the redactor returns: plain mode `{text, found}`, map mode
@@ -132,4 +138,19 @@ export type RedactResponse = {
     }[] | undefined;
     unmappable?: string | undefined;
 };
+/**
+ * A spawned daemon, as far as the spawning hook can see it.
+ */
+export type DaemonHandle = {
+    /**
+     * why the daemon died before it was
+     * ready (its exit status and stderr tail), or undefined while it may still bind
+     */
+    failure: () => string | undefined;
+    /**
+     * stop reading its stderr
+     */
+    release: () => void;
+};
 import { lstatSync } from "node:fs";
+import { FRAME_CAP } from "./redactor-wire.mjs";

package/types/claude-hooks/lib/redactor-wire.d.mts

@@ -0,0 +1,46 @@
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 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: unknown, shape: Shape): boolean;
+/**
+ * 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: unknown): Buffer;
+export { PROTOCOL };
+export const FRAME_CAP: number;
+/**
+ * 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 {
+    /**
+     * 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: Buffer): {
+        value: unknown;
+    } | undefined;
+    #private;
+}
+/**
+ * protocol field name -> field type
+ */
+export type Shape = Record<string, string>;
+import PROTOCOL from "../../python/agent_sanitizer/secrets/data/redactor-protocol.json" with { type: "json" };

package/types/claude-hooks/lib/trace.d.mts

@@ -1,10 +1,23 @@
 /**
- * Numeric verbosity from _AGENT_SANITIZER_TRACE: 0 off, 1 info, 2 debug.
- * Unknown, empty, or "off" → 0.
- * @param {NodeJS.ProcessEnv} [env]
+ * Numeric verbosity from _AGENT_SANITIZER_TRACE: 0 off, 1 info, 2 debug. Empty
+ * or "off" → 0; an unrecognized value is reported and reads as 0.
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
  * @returns {number}
  */
-export function traceThreshold(env?: NodeJS.ProcessEnv): number;
+export function traceThreshold(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): number;
+/**
+ * THE trace line's record: the envelope ({@link TRACE_RESERVED_KEYS}) first,
+ * then `fields`. A field named like an envelope key cannot overwrite it — a
+ * reader buckets on `level` and `event`, so a producer field `level: "debug"`
+ * would misfile the line — and is not dropped silently either: its name lands in
+ * `shadowed`, so the producer bug is visible on the channel it broke.
+ * @param {string} event
+ * @param {Record<string, unknown>} fields
+ * @param {"info"|"debug"} level
+ * @param {number} ts
+ * @returns {Record<string, unknown>}
+ */
+export function traceRecord(event: string, fields: Record<string, unknown>, level: "info" | "debug", ts: number): Record<string, unknown>;
 /**
  * Emit one JSON trace line for `event` at `level` (default "info") carrying the
  * metadata `fields`. No-op when the channel is below `level`; best-effort on write.
@@ -70,6 +83,8 @@ export const TraceEvent: Readonly<{
     SCAN_INVISIBLE_CHARS_RAN: "scan_invisible_chars_ran";
     SCAN_LOADED_INSTRUCTIONS_RAN: "scan_loaded_instructions_ran";
 }>;
+/** The keys every trace line's envelope owns; a field cannot set them. */
+export const TRACE_RESERVED_KEYS: readonly string[];
 /**
  * The sink shape a hook emits through: the event name, its metadata fields, and
  * the level. A host implementation receives the same {@link TraceEvent} names the

package/types/claude-hooks/sanitize-output.d.mts

@@ -191,15 +191,14 @@ export function emitFailClosed(input: any, message: string, emit?: (fields: Reco
  * fail-OPEN by default — a warning context and NO `updatedToolOutput`, leaving
  * the original tool output in the model's view — or the fail-closed
  * suppression of {@link emitFailClosed} when the caller set
- * AGENT_SANITIZER_FAIL_OPEN=0.
+ * AGENT_SANITIZER_FAIL_OPEN=0, or opted into Layer 4 (see the policy below).
  *
  * This is the hook where the two postures diverge the most, so state the open
  * one plainly: several of these layers throw on inputs an attacker composes (a
- * nesting depth that overflows the walk, a redaction budget spent on a thousand
- * secret-shaped leaves), and each of those throws is
- * guarding content the open posture hands to the model verbatim, secrets
- * included. An operator who cares more about withholding a secret than about
- * keeping the session moving sets the knob to `0`.
+ * nesting depth that overflows the walk), and each of those throws is guarding
+ * content the open posture hands to the model verbatim. An operator who cares
+ * more about withholding that than about keeping the session moving sets the
+ * knob to `0`.
  * @param {any} input  parsed hook input, or undefined if parsing threw
  * @param {unknown} err
  * @param {(fields: Record<string, unknown>) => void} [emit]