agent-sanitizer 2.2.2 → 2.4.0

package/README.md

@@ -86,6 +86,113 @@ like `found`:
 | `filter-flagged`      | The filter flagged the output as a possible injection without deleting (content intact) |
 | `filter-error`        | The filter reported a non-fatal internal error while scanning (a fatal filter throws)   |
 
+## Using it with Claude Code
+
+The entry points above are a library — you supply the wiring. For Claude Code
+the wiring is already written, as four hooks that put Layers 1–4 on the tool
+stream: tool input, tool output, user prompts, and a session-start scan of the
+instruction files.
+
+### The plugin (recommended)
+
+```
+/plugin marketplace add AlexanderMattTurner/agent-sanitizer
+/plugin install agent-sanitizer@agent-sanitizer
+```
+
+The plugin ships a self-contained bundle and a committed Python zipapp of the
+secret-redaction engine, so it needs no `node_modules` and no install step
+beyond a `python3` on PATH.
+
+### Without the plugin
+
+Install the package and point your `settings.json` at the published hook entry.
+One entry point dispatches all four modes on `--hook=`:
+
+```jsonc
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-user-prompt",
+          },
+        ],
+      },
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=pretooluse-sanitize",
+          },
+        ],
+      },
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=sanitize-output",
+          },
+        ],
+      },
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ./node_modules/agent-sanitizer/claude-hooks/plugin-hooks.mjs --hook=scan-invisible-chars",
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+Resolve the path however your project prefers — `require.resolve("agent-sanitizer/claude-hooks")` gives it without hardcoding a layout. Importing the module instead of spawning it is a no-op, so a build step that pulls it in will not consume stdin.
+
+**Layer 4 needs the Python engine.** Secret redaction runs out-of-process
+against `agent-secret-redactor-daemon`, from the `secrets` extra on PyPI:
+
+```bash
+pip install 'agent-sanitizer[secrets]'   # version-match the npm package
+```
+
+Without it, `sanitize-output` **fails closed** on secret-shaped output — the
+tool result is suppressed and replaced with a placeholder rather than shown
+unvetted. That is the intended posture, not a degradation to ignore: Layers 1–3
+still run, but a missing daemon means every secret-shaped output is withheld.
+
+**Layer 5 (second-model injection filtering) is not included.** The `/output`
+seam accepts a `filterInjection` callback, but these hooks never supply one, so
+nothing here calls out to a model or leaves the machine.
+
+### Internal environment variables
+
+These tune the hooks' internals. They are **not a stable interface** — they
+carry a leading underscore and may change between minor versions. The stable
+surface is the `--hook=` CLI and the settings wiring above.
+
+| Variable                               | Effect                                                             |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| `_AGENT_SANITIZER_REDACTOR_DAEMON`     | Path to the redactor daemon binary                                 |
+| `_AGENT_SANITIZER_REDACTOR_SOCKET`     | Unix socket the daemon binds; per-session and private by default   |
+| `_AGENT_SANITIZER_REDACTOR_WAIT_MS`    | How long to wait for a freshly spawned daemon to accept            |
+| `_AGENT_SANITIZER_REDACTOR_REQUEST_MS` | Deadline for one request; bounds a daemon that accepts then stalls |
+| `_AGENT_SANITIZER_SANITIZE_BUDGET_MS`  | Total wall-clock budget for one hook run's daemon calls            |
+| `_AGENT_SANITIZER_TRACE`               | `info` or `debug` to emit one JSON line per layer engagement       |
+| `_AGENT_SANITIZER_TRACE_FILE`          | Trace sink; stderr when unset                                      |
+| `_AGENT_SANITIZER_REVEAL_DIR`          | Where Layer 2 stores pre-splice text for the model to read back    |
+
 ## How this compares
 
 The "sanitize untrusted LLM input" space mostly splits into two camps: ML

package/claude-hooks/config/credential-var-names.json

@@ -0,0 +1,23 @@
+{
+  "comment": "The credential-shaped ENV-VAR NAME vocabulary the hook-side pre-gate builds its regexes from (looksLikeCredentialVar in lib/env-config.mjs). `segments`: a var whose trailing underscore-delimited segment is one of these is treated as credential-bearing (matched as `(?:^|_)(?:<segment>)$`, case-insensitive). `excludeSuffixes` / `excludeNames`: names that end like a credential but hold a non-secret (an identifier, a public key, the ssh-agent socket path) and must NOT be redacted out of tool output. Every token is restricted to A-Z and _ so it carries no regex metacharacter; the consumer enforces that and fails closed on a violation, an empty list, or a missing field.",
+  "segments": [
+    "TOKEN",
+    "SECRET",
+    "SECRETS",
+    "PASSWORD",
+    "PASSWD",
+    "PASSPHRASE",
+    "APIKEY",
+    "API_KEY",
+    "ACCESS_KEY",
+    "SECRET_KEY",
+    "PRIVATE_KEY",
+    "AUTH_TOKEN",
+    "PAT",
+    "CREDENTIAL",
+    "CREDENTIALS",
+    "KEY"
+  ],
+  "excludeSuffixes": ["_KEY_ID", "_PUBLIC_KEY"],
+  "excludeNames": ["SSH_AUTH_SOCK"]
+}

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

@@ -0,0 +1,17 @@
+{
+  "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,
+  "vars": [
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "OPENAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "MISTRAL_API_KEY",
+    "GROQ_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "XAI_API_KEY",
+    "VENICE_INFERENCE_KEY"
+  ]
+}

package/claude-hooks/config/scrubbed-env-vars.json

@@ -0,0 +1,15 @@
+{
+  "description": "The GUARANTEED FLOOR of credential-bearing environment variables whose values must never reach the model through tool output. On top of this list the redactor self-populates with any credential-shaped var present in the environment (looksLikeCredentialVar in lib/env-config.mjs), so a newly-forwarded token is redacted without editing this file — this list only pins the names that must always be covered regardless of shape. The Layer-4 secret redactor treats each as an env-bound secret (env_secrets).",
+  "vars": [
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "NPM_TOKEN",
+    "PYPI_TOKEN",
+    "DOCKER_PASSWORD",
+    "DOCKER_AUTH_CONFIG"
+  ]
+}

package/claude-hooks/lib/authored-content.mjs

@@ -0,0 +1,166 @@
+/**
+ * Sanitize content the *model authors* into tool calls — file writes, edits,
+ * notebook cells, and command bodies (commit messages, PR/issue bodies passed on
+ * the command line). Two complementary protections:
+ *
+ *   1. Covert channel (steganography). Format chars (Cf — including the U+E00xx
+ *      TAG block used for ASCII smuggling and zero-width joiners) and variation
+ *      selectors can encode a hidden message that another AI reading the
+ *      committed file / PR / commit later decodes, while staying invisible to a
+ *      human reviewer. Stripped when payload-capable (see isPayloadCapable):
+ *      gated on volume because incidental joiners / emoji selectors are benign
+ *      and authored content is *persisted*, so over-stripping is costly.
+ *
+ *   2. Terminal-display rewriting. ANSI/terminal control sequences (CSI/OSC)
+ *      authored into a command — echoed and executed live — or into file
+ *      content (a latent bomb when the file is later `cat`'d) can clear the
+ *      screen, reposition the cursor, or overwrite what the user sees, hiding
+ *      the real command behind spoofed output. Stripped *unconditionally*: a
+ *      single sequence already does harm, so there is no volume threshold. The
+ *      false-positive rate is low because real source represents escapes as
+ *      *literals* (`\033`, `\x1b`, `\e`) — a *raw* ESC byte in authored content
+ *      is anomalous.
+ *
+ * Distinct from sanitize-output.mjs, which scrubs tool *responses* flowing
+ * toward the model (data the model reads). This scrubs what the model emits
+ * (data the model writes out). In pretooluse-sanitize.mjs it runs *after*
+ * confusable normalization, so on the shared `command` field it sees the
+ * already-normalized text and the two protections compose deterministically.
+ *
+ * Opt-outs are granular so dropping one protection doesn't drop the other:
+ * AGENT_SANITIZER_INVISIBLE_DISABLED=1 keeps invisible chars (legitimate i18n
+ * text relying on ZWNJ/ZWJ joiners) while terminal-control stripping stays on;
+ * AGENT_SANITIZER_TERMINAL_DISABLED=1 keeps raw escape sequences (fixtures that
+ * must contain them) while stego stripping stays on; and
+ * AGENT_SANITIZER_OUTPUT_DISABLED=1 disables both.
+ */
+import { lazyImport } from "./hook-io.mjs";
+
+// Bound via lazyImport (see its doc for the fail-OPEN hazard of a bare static
+// npm import — here the load crash would fire inside pretooluse-sanitize.mjs's
+// static import of this module, before its fail-closed catch runs). A failed
+// load leaves these bindings undefined, so sanitizeField's calls throw into
+// the fail-closed catch (ask) instead.
+const { stripAnsiFully } = /** @type {typeof import("agent-sanitizer")} */ (
+  await lazyImport("agent-sanitizer")
+);
+const { STRIP, LONG_RUN_RE, SCATTERED_THRESHOLD, stripInvisible } =
+  /** @type {typeof import("agent-sanitizer/invisible")} */ (
+    await lazyImport("agent-sanitizer/invisible")
+  );
+
+// Content fields the model authors, per tool. Paths and confusables are the
+// confusable layer's domain; here we target the free-text fields that carry
+// model-authored prose / code / data out into persisted or displayed artifacts.
+// A "key[].sub" entry addresses `sub` on every element of the array at `key`
+// (MultiEdit batches its writes as edits[].new_string), so the nested authored
+// content is sanitized too — not just the top-level fields.
+/** @type {Record<string, string[]>} */
+const FIELDS = {
+  Write: ["content"],
+  Edit: ["new_string"],
+  MultiEdit: ["edits[].new_string"],
+  NotebookEdit: ["new_source"],
+  Bash: ["command"],
+};
+
+// Payload-capable: a long contiguous run, or enough scattered invisibles to
+// carry a message. Mirrors sanitize-user-prompt so the model→world and
+// user→model surfaces share one definition of "stego payload".
+/** @param {string} text */
+function isPayloadCapable(text) {
+  LONG_RUN_RE.lastIndex = 0;
+  if (LONG_RUN_RE.test(text)) return true;
+  return (text.match(STRIP)?.length ?? 0) >= SCATTERED_THRESHOLD;
+}
+
+// Returns the cleaned value plus the human-readable actions applied, or null if
+// the field is already clean. Each protection has its own opt-out (see the
+// header) so a deployment can keep one while dropping the other.
+/** @param {string} value */
+function sanitizeField(value) {
+  const actions = [];
+  let cleaned = value;
+
+  // Strip terminal-control sequences first, so the invisible scan below runs on
+  // the same de-ANSI'd view sanitize-output uses (both go through the package's
+  // stripAnsiFully, which strips to a fixed point — so a sequence reconstituted
+  // when an inner one is removed is itself stripped on the next pass). Compare
+  // before/after rather than pre-testing for ESC: a lone control byte that forms
+  // no real sequence does not rewrite the display and is left alone, so we only
+  // report a genuine strip.
+  if (process.env.AGENT_SANITIZER_TERMINAL_DISABLED !== "1") {
+    const deAnsi = stripAnsiFully(cleaned);
+    if (deAnsi !== cleaned) {
+      cleaned = deAnsi;
+      actions.push("terminal-control sequences");
+    }
+  }
+
+  if (
+    process.env.AGENT_SANITIZER_INVISIBLE_DISABLED !== "1" &&
+    isPayloadCapable(cleaned)
+  ) {
+    cleaned = stripInvisible(cleaned);
+    actions.push("invisible characters");
+  }
+
+  return actions.length > 0 ? { cleaned, actions } : null;
+}
+
+/** @param {string[]} changed */
+export function authoredContext(changed) {
+  return `Sanitized model-authored content in: ${changed.join("; ")}. This removes a covert channel to other AIs and prevents authored content from rewriting the user's terminal. Opt out granularly with AGENT_SANITIZER_INVISIBLE_DISABLED=1 (i18n joiners) or AGENT_SANITIZER_TERMINAL_DISABLED=1 (raw-escape fixtures), or fully with AGENT_SANITIZER_OUTPUT_DISABLED=1.`;
+}
+
+/**
+ * Strip authored stego / terminal-control sequences from the model-authored
+ * fields of a tool call. Returns the updated input plus a per-field description
+ * of what was stripped, or null when nothing changed. Throws on internal error
+ * (caller fails closed).
+ * @param {string} tool
+ * @param {any} toolInput
+ * @returns {{ updatedInput: any, changed: string[] } | null}
+ */
+export function sanitizeAuthoredContent(tool, toolInput) {
+  const keys = FIELDS[tool];
+  if (!keys || toolInput === null || toolInput === undefined) return null;
+
+  const changed = [];
+  // Null-prototype copy: toolInput is untrusted parsed JSON where a `__proto__`
+  // key is own-enumerable, and the computed writes below would otherwise route
+  // it through the prototype chain. Object.assign onto Object.create(null) copies
+  // every own field (including a literal `__proto__`) as a plain own property.
+  const updatedInput = Object.assign(Object.create(null), toolInput);
+  for (const k of keys) {
+    // Named groups satisfy prefer-named-capture-group; reading the numeric
+    // indices keeps the values typed as string (match.groups is optional).
+    const nested = k.match(/^(?<arr>\w+)\[\]\.(?<sub>\w+)$/);
+    if (nested) {
+      const arrKey = nested[1];
+      const subKey = nested[2];
+      const arr = toolInput[arrKey];
+      if (!Array.isArray(arr)) continue;
+      let nestedChanged = false;
+      const newArr = arr.map((el) => {
+        const val = el?.[subKey];
+        if (typeof val !== "string") return el;
+        const result = sanitizeField(val);
+        if (!result) return el;
+        nestedChanged = true;
+        changed.push(`${arrKey}[].${subKey} (${result.actions.join(", ")})`);
+        return { ...el, [subKey]: result.cleaned };
+      });
+      if (nestedChanged) updatedInput[arrKey] = newArr;
+      continue;
+    }
+    if (typeof toolInput[k] !== "string") continue;
+    const result = sanitizeField(toolInput[k]);
+    if (!result) continue;
+    updatedInput[k] = result.cleaned;
+    changed.push(`${k} (${result.actions.join(", ")})`);
+  }
+
+  if (changed.length === 0) return null;
+  return { updatedInput, changed };
+}

package/claude-hooks/lib/control-plane.mjs

@@ -0,0 +1,138 @@
+/**
+ * Bridge to the agent-agnostic control plane (agent-control-plane-core).
+ * Guardrail judges consume the normalized ToolCallEvent and return a Verdict;
+ * a per-agent adapter parses the native payload and renders the native
+ * response, so the same judge runs unchanged under any agent the package has
+ * an adapter for. This module owns the package load, the one Claude-specific
+ * transport rule (nativeStdout), and the shared judge-CLI transport
+ * (runJudgeCli).
+ */
+import { errMessage, lazyImport, readStdinJson } from "./hook-io.mjs";
+
+// Loaded via a *caught* dynamic import — never a bare static `import … from`.
+// A static npm import resolves before any try/catch, so a missing node_modules
+// would crash every importing hook at load; the harness treats that as a
+// non-blocking error and the tool call sails through UNGUARDED — fail OPEN. A
+// failed load leaves the bindings undefined, so controlPlane() throws into the
+// calling hook's catch and each hook takes its declared failure posture
+// (deny/ask for gates, suppression for the output sanitizer) instead.
+/** @type {typeof import("agent-control-plane-core/claude").claudeAdapter | undefined} */
+let claudeAdapter;
+/** @type {typeof import("agent-control-plane-core").Decision | undefined} */
+let Decision;
+/** @type {typeof import("agent-control-plane-core").EventKind | undefined} */
+let EventKind;
+
+/* c8 ignore start -- module-load boundary: the real import resolves in every
+   in-process test and spawned CLI run, and a missing node_modules can't be
+   simulated in-process, so this glue's failure arm is unobservable here. The
+   observable behaviour is controlPlane()'s throw, unit-tested directly. */
+// Stryker disable all
+{
+  const { claudeAdapter: adapter } =
+    /** @type {Partial<typeof import("agent-control-plane-core/claude")>} */ (
+      await lazyImport("agent-control-plane-core/claude")
+    );
+  const { Decision: decision, EventKind: eventKind } =
+    /** @type {Partial<typeof import("agent-control-plane-core")>} */ (
+      await lazyImport("agent-control-plane-core")
+    );
+  claudeAdapter = adapter;
+  Decision = decision;
+  EventKind = eventKind;
+}
+// Stryker restore all
+/* c8 ignore stop */
+
+/**
+ * The loaded control-plane bindings, narrowed to non-undefined — or a throw
+ * the calling hook's catch converts into its own failure posture. Overrides
+ * exist so tests can drive the unavailable arm in-process.
+ * @param {{ claudeAdapter?: unknown, Decision?: unknown, EventKind?: unknown }} [overrides]
+ * @returns {{
+ *   claudeAdapter: typeof import("agent-control-plane-core/claude").claudeAdapter,
+ *   Decision: typeof import("agent-control-plane-core").Decision,
+ *   EventKind: typeof import("agent-control-plane-core").EventKind,
+ * }}
+ */
+export function controlPlane(overrides = {}) {
+  const bindings = { claudeAdapter, Decision, EventKind, ...overrides };
+  if (!bindings.claudeAdapter || !bindings.Decision || !bindings.EventKind)
+    throw new Error("agent-control-plane-core is unavailable");
+  return /** @type {ReturnType<typeof controlPlane>} */ (bindings);
+}
+
+/**
+ * Serialize a rendered NativeResponse for Claude Code's stdout, or null when
+ * the body carries nothing a silent exit 0 doesn't already say. The adapter's
+ * exit_code is deliberately NOT honored by the hooks: Claude Code parses hook
+ * stdout as JSON only on exit 0 — under the adapter's exit-2 enforced-deny
+ * channel it discards stdout and reads the (empty) stderr instead, so the
+ * deny would land without its reason. For this host the stdout JSON's
+ * permissionDecision IS the enforcement channel, and hooks always exit 0.
+ * @param {{ stdout?: unknown }} response a NativeResponse from adapter.render
+ * @returns {string | null}
+ */
+export function nativeStdout(response) {
+  const stdout = /** @type {Record<string, unknown> | undefined} */ (
+    response.stdout
+  );
+  if (!stdout) return null;
+  // Directives live either inside hookSpecificOutput (permissionDecision,
+  // updatedInput, additionalContext) or at the top level (the non-gating
+  // decision:"block"/reason the adapter uses for post-tool and unclassified
+  // events). A body that is only the echoed hookEventName says nothing.
+  const body = /** @type {Record<string, unknown> | undefined} */ (
+    stdout.hookSpecificOutput
+  );
+  const meaningful =
+    Object.keys(stdout).some((key) => key !== "hookSpecificOutput") ||
+    (body !== undefined &&
+      Object.keys(body).some((key) => key !== "hookEventName"));
+  return meaningful ? JSON.stringify(stdout) : null;
+}
+
+/**
+ * Run a judge hook's CLI transport: read the native payload from stdin, parse
+ * it through the claude adapter, render the judge's verdict, and write the
+ * native response. This encodes the two transport invariants every gate hook
+ * shares: stdin is read BEFORE the control-plane bindings are touched, so a
+ * package-load failure still lands in `onError` with the parsed input in hand;
+ * and the process always exits 0 with the verdict in the stdout JSON (see
+ * nativeStdout — exit-code enforcement is deliberately not used). Any throw —
+ * unparsable stdin, missing package, a judge error — is reported on stderr and
+ * routed to `onError(err, input)` (`input` undefined when stdin never parsed),
+ * where the hook applies its declared fail posture.
+ * @param {string} hookName  prefix for the stderr diagnostic
+ * @param {(event: import("agent-control-plane-core").ToolCallEvent) =>
+ *   import("agent-control-plane-core").Verdict |
+ *   Promise<import("agent-control-plane-core").Verdict>} judge
+ * @param {object} opts
+ * @param {(err: unknown, input: unknown) => void} opts.onError  fail-posture emitter
+ * @param {(input: unknown) => unknown} [opts.transformInput]  raw-payload normalization before adapter.parse
+ * @param {() => Promise<unknown>} [opts.readInput]  injectable stdin reader
+ * @param {(chunk: string) => void} [opts.write]  injectable stdout writer
+ * @returns {Promise<void>}
+ */
+export async function runJudgeCli(
+  hookName,
+  judge,
+  {
+    onError,
+    transformInput = (raw) => raw,
+    readInput = readStdinJson,
+    write = (chunk) => process.stdout.write(chunk),
+  },
+) {
+  let input;
+  try {
+    input = await readInput();
+    const { claudeAdapter: adapter } = controlPlane();
+    const event = adapter.parse(transformInput(input));
+    const out = nativeStdout(adapter.render(await judge(event), event));
+    if (out !== null) write(out);
+  } catch (err) {
+    process.stderr.write(`${hookName} hook error: ${errMessage(err)}\n`);
+    onError(err, input);
+  }
+}

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

@@ -0,0 +1,140 @@
+/**
+ * The env-bound secret vocabulary the Layer-4 pre-gate and the redactor client
+ * share, so the set of variable names whose VALUES get masked has one definition
+ * instead of a copy per hook that can silently drift.
+ *
+ * The three JSON configs are imported as modules, not read from disk at call
+ * time: esbuild inlines them into the plugin bundle (which ships with no
+ * config directory beside it) and Node resolves them natively from the package
+ * when the hooks run from source. Their VALIDATION stays lazy — a malformed
+ * credential vocabulary throws on first use, inside the consuming hook's
+ * fail-closed catch, rather than at module load where a throw would abort before
+ * that catch installs and let the harness pass the tool output through
+ * UNSANITIZED (fail OPEN).
+ */
+import credentialVarNames from "../config/credential-var-names.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" };
+
+/**
+ * The inference-provider key env vars. Their values authenticate the agent to a
+ * model backend, so they are masked like any other credential.
+ * @returns {string[]}
+ */
+export function inferenceKeyVars() {
+  return inferenceKeys.vars;
+}
+
+/**
+ * The placeholder floor: a candidate value shorter than this is too short to be a
+ * real secret and is skipped by the env-bound redaction pre-gate.
+ * @returns {number}
+ */
+export function minEnvSecretLen() {
+  return inferenceKeys.min_secret_len;
+}
+
+// A token from credential-var-names.json. Restricting it to A-Z/_ is what lets
+// the regexes below interpolate it unescaped: a stray metacharacter (or an empty
+// list, which would make the match regex accept nothing and leak every forwarded
+// credential) fails closed here instead of silently under-matching.
+const CRED_TOKEN_RE = /^[A-Z_]+$/;
+
+/**
+ * The validated token list under `field`, or throw. An absent, empty, or
+ * metacharacter-bearing list must not degrade into a pattern that matches nothing,
+ * which would leak every forwarded credential.
+ * @param {Record<string, unknown>} spec
+ * @param {string} field
+ * @returns {string[]}
+ */
+function credentialTokens(spec, field) {
+  const group = spec[field];
+  if (!Array.isArray(group) || group.length === 0)
+    throw new Error(`credential-var-names.json: ${field} is empty or missing`);
+  for (const token of group)
+    if (typeof token !== "string" || !CRED_TOKEN_RE.test(token))
+      throw new Error(
+        `credential-var-names.json: bad token ${token} in ${field}`,
+      );
+  return group;
+}
+
+/**
+ * Validate a credential-var-names spec and build its match/exclude regexes. Pure
+ * and exported so the fail-closed paths can be driven directly with a bad spec.
+ * @param {Record<string, unknown>} spec
+ * @returns {{ match: RegExp, exclude: RegExp }}
+ */
+export function buildCredentialNameRes(spec) {
+  const segments = credentialTokens(spec, "segments");
+  const excludeSuffixes = credentialTokens(spec, "excludeSuffixes");
+  const excludeNames = credentialTokens(spec, "excludeNames");
+  return {
+    match: new RegExp(`(?:^|_)(?:${segments.join("|")})$`, "i"),
+    exclude: new RegExp(
+      `(?:${excludeSuffixes.join("|")})$|^(?:${excludeNames.join("|")})$`,
+      "i",
+    ),
+  };
+}
+
+/** @type {{ match: RegExp, exclude: RegExp } | undefined} */
+let _credentialNameRes;
+/**
+ * The credential-var-NAME regexes, memoized after the first build. Matching by
+ * trailing segment lets the redaction set self-populate with any token the
+ * process actually holds; a curated list drifts. The curated sets
+ * (inferenceKeyVars + scrubbed vars) stay the guaranteed floor; this only ADDS
+ * lookalikes.
+ * @returns {{ match: RegExp, exclude: RegExp }}
+ */
+function credentialNameRes() {
+  if (_credentialNameRes !== undefined) return _credentialNameRes;
+  return (_credentialNameRes = buildCredentialNameRes(credentialVarNames));
+}
+
+/**
+ * True when `name` looks like a credential-bearing variable (and isn't a known
+ * non-secret lookalike).
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function looksLikeCredentialVar(name) {
+  const res = credentialNameRes();
+  return res.match.test(name) && !res.exclude.test(name);
+}
+
+/**
+ * Credential-shaped env-var names present in `env` with a value long enough to be
+ * a real secret (the min_secret_len floor the daemon also applies), beyond the
+ * curated set. Reads the live environment so a newly-forwarded token is redacted
+ * without a code change.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function dynamicSecretVars(env = process.env) {
+  const floor = minEnvSecretLen();
+  return Object.keys(env).filter(
+    (name) => looksLikeCredentialVar(name) && (env[name]?.length ?? 0) >= floor,
+  );
+}
+
+/**
+ * The env-bound redaction set: the UNION of the inference keys, the curated host
+ * credentials, and any credential-shaped var present in the environment. The
+ * redactor binds the same union; every consumer (the sanitize-output pre-gate,
+ * the redactor client's per-request env snapshot) must mirror it exactly, else a
+ * credential value would never trip the daemon.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string[]}
+ */
+export function envBoundSecretVars(env = process.env) {
+  return [
+    ...new Set([
+      ...inferenceKeyVars(),
+      ...scrubbed.vars,
+      ...dynamicSecretVars(env),
+    ]),
+  ];
+}