agent-sanitizer 2.10.1 → 2.12.0

package/README.md

@@ -202,6 +202,26 @@ hook module, and every consumer waits on that path instead. `lib/control-plane`
 resolves the marker at module scope, so a call that lands after that import
 warns on stderr — it cannot steer the wait that already started.
 
+**A host's own remedy can replace the packaged one in every fail-closed
+reason.** Deep call sites (`lib/control-plane`'s missing-package throw) take no
+remedy argument, so by default they can only say `pnpm install`. A host whose
+install has one entry point calls `configureMissingPackageRemedy(text)` (from
+`lib/hook-io`) — typically at its bundle entry — and every remedy-less
+`missingPackageMessage`/`missingPackageError` states that text instead. An
+explicit per-call remedy (including a per-gate `MESSAGES.remedy`) still wins,
+and `null` restores the packaged wording. Keep it to a sentence: past ~260
+characters it overruns the 300-char message budget.
+
+**A host's own secret registry can drive the env-bound redaction set.**
+`configureEnvConfigSource({ minSecretLen, extraVars })` (from `lib/env-config`)
+replaces the placeholder floor and unions extra `[A-Z0-9_]` variable names into
+`envBoundSecretVars()`, so a host that already declares its forwarded
+credentials (and their length floor) in a registry of its own feeds the packaged
+helpers from it instead of forking the module. Unset fields keep the package
+derivation; `null` restores it entirely. A malformed source — a non-object, a
+key the seam does not read, a bad field — throws on first use, inside the
+consuming hook's fail-closed catch, never at configure time.
+
 Hook internals are tuned by `_AGENT_SANITIZER_*` variables (redactor daemon
 path/socket/timeouts, sanitize budget, trace channel, Layer-2 reveal dir). The
 leading underscore marks them unstable — the supported surface is the `--hook=`

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

@@ -30,13 +30,101 @@ export function inferenceKeyVars() {
   return inferenceKeys.vars;
 }
 
+/**
+ * Host-supplied secret-vocabulary source, consulted before the package configs.
+ * Null (the default) keeps the package derivation.
+ * @type {{ minSecretLen?: number, extraVars?: string[] } | null}
+ */
+let hostEnvConfigSource = null;
+
+const HOST_SOURCE_LABEL = "configureEnvConfigSource";
+
+const HOST_SOURCE_KEYS = ["minSecretLen", "extraVars"];
+
+/**
+ * Adopt a host's own secret config in place of the package's: `minSecretLen`
+ * replaces the placeholder floor, and `extraVars` are unioned into the
+ * env-bound redaction set. This seam is what lets a host whose credential
+ * registry already names its forwarded secrets (and their length floor) drive
+ * the packaged helpers from that registry instead of forking this module —
+ * a fork is the drift channel that lets the two redaction sets silently
+ * disagree. Unset fields keep their package derivation; `undefined` and `null`
+ * both restore it entirely. Like the missing-package remedy seam there is no
+ * too-late window: the source is consulted at each helper call, never resolved
+ * at module scope, so a later call steers every later answer. A malformed
+ * source — a non-object, a key this seam does not read, a bad field — throws
+ * on first use, not here (see {@link hostSource}).
+ * @param {{ minSecretLen?: number, extraVars?: string[] } | null} source
+ *   host config, or null to restore the package derivation
+ * @returns {void}
+ */
+export function configureEnvConfigSource(source) {
+  hostEnvConfigSource = source ?? null;
+}
+
+/**
+ * The stored host source with its shape validated, or null when unconfigured.
+ * Shape errors — a non-object source, a key this seam does not read — throw
+ * HERE, on first use inside the consuming hook's fail-closed catch, never at
+ * configure time: a top-level throw in a bundle entry would kill the hook
+ * before that catch installs (fail OPEN), and silently ignoring the problem
+ * is worse — a typo'd `minSecretLength: 32` must not leave the helpers
+ * running at the package floor while the host believes it configured 32.
+ * @returns {{ minSecretLen?: number, extraVars?: string[] } | null}
+ */
+function hostSource() {
+  const source = hostEnvConfigSource;
+  if (source === null) return null;
+  if (typeof source !== "object")
+    throw new Error(
+      `${HOST_SOURCE_LABEL}: source must be an object, got ${typeof source}`,
+    );
+  for (const key of Object.keys(source))
+    if (!HOST_SOURCE_KEYS.includes(key))
+      throw new Error(
+        `${HOST_SOURCE_LABEL}: unknown key ${JSON.stringify(key)}; it reads ` +
+          `${HOST_SOURCE_KEYS.join(" and ")}`,
+      );
+  return source;
+}
+
 /**
  * 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.
+ * real secret and is skipped by the env-bound redaction pre-gate. A malformed
+ * host floor throws rather than degrading to the package's — a host that set 32
+ * must not silently run at a laxer floor, and a non-positive one would admit
+ * empty placeholders as secrets.
  * @returns {number}
  */
 export function minEnvSecretLen() {
-  return inferenceKeys.min_secret_len;
+  const hostLen = hostSource()?.minSecretLen;
+  if (hostLen === undefined) return inferenceKeys.min_secret_len;
+  if (!Number.isInteger(hostLen) || hostLen <= 0)
+    throw new Error(
+      `${HOST_SOURCE_LABEL}: minSecretLen must be a positive integer, got ${JSON.stringify(hostLen)}`,
+    );
+  return hostLen;
+}
+
+/**
+ * The host's declared extra secret variable names, or throw. A malformed entry
+ * fails CLOSED, same contract as {@link extraSecretVars}: dropping it silently
+ * would leave the host believing a forwarded credential is masked while its
+ * value flows to the model verbatim.
+ * @returns {string[]}
+ */
+function hostExtraSecretVars() {
+  const vars = hostSource()?.extraVars;
+  if (vars === undefined) return [];
+  if (!Array.isArray(vars))
+    throw new Error(`${HOST_SOURCE_LABEL}: extraVars must be an array`);
+  for (const name of vars)
+    if (typeof name !== "string" || !EXTRA_TOKEN_RE.test(name))
+      throw new Error(
+        `${HOST_SOURCE_LABEL}: ${JSON.stringify(name)} is not a variable name ` +
+          "(expected [A-Z0-9_] names)",
+      );
+  return vars;
 }
 
 // A rendered vocabulary token. Restricting it to A-Z/0-9/_ is what lets the
@@ -97,10 +185,13 @@ export function deriveCredentialVocabulary(spec) {
   for (const noun of nouns)
     if (Array.isArray(noun?.uses) && noun.uses.includes(ENV_NAME_USE))
       segments.push(...segmentForms(parts(noun.parts, "nouns[].parts")));
+  // Rendered WITHOUT a leading underscore; the boundary is applied in the regex
+  // below, symmetrically with the match pattern. Baking `_` into the token makes
+  // the exclusion reachable only when something precedes the run, so a variable
+  // named exactly `PUBLIC_KEY` matched on its trailing `KEY` and never reached
+  // its exclusion — its value was then cut out of every tool output carrying it.
   const excludeSuffixes = nonSecret.flatMap((suffix) =>
-    segmentForms(parts(suffix, "nonSecretSuffixes[]")).map(
-      (form) => `_${form}`,
-    ),
+    segmentForms(parts(suffix, "nonSecretSuffixes[]")),
   );
   return {
     segments: [...new Set(segments)],
@@ -156,7 +247,7 @@ export function buildCredentialNameRes(spec) {
   return {
     match: new RegExp(`(?:^|_)(?:${segments.join("|")})$`, "i"),
     exclude: new RegExp(
-      `(?:${excludeSuffixes.join("|")})$|^(?:${excludeNames.join("|")})$`,
+      `(?:^|_)(?:${excludeSuffixes.join("|")})$|^(?:${excludeNames.join("|")})$`,
       "i",
     ),
   };
@@ -239,10 +330,11 @@ export function extraSecretVars(env = process.env) {
 
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
- * credentials, any credential-shaped var present in the environment, and the
- * operator's declared extras. 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.
+ * credentials, any credential-shaped var present in the environment, the
+ * operator's declared extras, and the host's configured extras. 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[]}
  */
@@ -253,6 +345,7 @@ export function envBoundSecretVars(env = process.env) {
       ...scrubbed.vars,
       ...dynamicSecretVars(env),
       ...extraSecretVars(env),
+      ...hostExtraSecretVars(),
     ]),
   ];
 }

package/claude-hooks/lib/hook-io.mjs

@@ -241,6 +241,33 @@ export function failedLazyPackages() {
 export const DEFAULT_MISSING_PACKAGE_REMEDY =
   "reinstall the hook dependencies (pnpm install) and retry.";
 
+/**
+ * Host-supplied default remedy, replacing DEFAULT_MISSING_PACKAGE_REMEDY. Null
+ * (the default) keeps the package's wording.
+ * @type {string | null}
+ */
+let missingPackageRemedyOverride = null;
+
+/**
+ * Adopt a host's own remedy as the default {@link missingPackageMessage} and
+ * {@link missingPackageError} state when their caller passes none. This refusal
+ * to hard-code the wording is what prevents a fail-closed reason whose remedy
+ * names a command the host doesn't have: deep call sites (controlPlane's
+ * missing-package throw) never take a remedy argument, so without this seam
+ * they can only ever tell a reader to run `pnpm install` — wrong advice in a
+ * host whose one install entry point is its own setup script. An explicit
+ * per-call remedy still wins over the configured one. Unlike the hookgate
+ * marker there is no too-late window: the remedy is consulted at each throw,
+ * never resolved at module scope, so a later call steers every later message.
+ * Keep it to a sentence — a remedy beyond ~260 characters overruns the 300-char
+ * message budget (see missingPackageMessage).
+ * @param {string | null} remedy  host remedy text, or null to restore the package default
+ * @returns {void}
+ */
+export function configureMissingPackageRemedy(remedy) {
+  missingPackageRemedyOverride = remedy;
+}
+
 /**
  * The fail-closed reason for a package a hook could not load: the recorded
  * loader error plus the remedy. The cause is scrubbed (it is spliced into
@@ -257,7 +284,7 @@ export const DEFAULT_MISSING_PACKAGE_REMEDY =
 export function missingPackageMessage(
   pkg,
   err = lazyImportErrorFor(pkg),
-  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+  remedy = missingPackageRemedyOverride ?? DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
   const prefix = `${pkg} is unavailable: `;
   // 2 for the "; " joiner; 12 for safeErrMessage's own "…[truncated]" marker,
@@ -287,7 +314,7 @@ export function missingPackageMessage(
 export function missingPackageError(
   pkg,
   err = lazyImportErrorFor(pkg),
-  remedy = DEFAULT_MISSING_PACKAGE_REMEDY,
+  remedy = missingPackageRemedyOverride ?? DEFAULT_MISSING_PACKAGE_REMEDY,
 ) {
   return Object.assign(new Error(missingPackageMessage(pkg, err, remedy)), {
     code: "DEP_UNAVAILABLE",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "Defend an agent against hidden-content injection: strip payload-capable invisible Unicode and ANSI, splice out human-invisible HTML, and flag data-exfil URLs in untrusted text before any model sees it.",
   "type": "module",
   "repository": {

package/types/claude-hooks/lib/env-config.d.mts

@@ -4,9 +4,33 @@
  * @returns {string[]}
  */
 export function inferenceKeyVars(): string[];
+/**
+ * Adopt a host's own secret config in place of the package's: `minSecretLen`
+ * replaces the placeholder floor, and `extraVars` are unioned into the
+ * env-bound redaction set. This seam is what lets a host whose credential
+ * registry already names its forwarded secrets (and their length floor) drive
+ * the packaged helpers from that registry instead of forking this module —
+ * a fork is the drift channel that lets the two redaction sets silently
+ * disagree. Unset fields keep their package derivation; `undefined` and `null`
+ * both restore it entirely. Like the missing-package remedy seam there is no
+ * too-late window: the source is consulted at each helper call, never resolved
+ * at module scope, so a later call steers every later answer. A malformed
+ * source — a non-object, a key this seam does not read, a bad field — throws
+ * on first use, not here (see {@link hostSource}).
+ * @param {{ minSecretLen?: number, extraVars?: string[] } | null} source
+ *   host config, or null to restore the package derivation
+ * @returns {void}
+ */
+export function configureEnvConfigSource(source: {
+    minSecretLen?: number;
+    extraVars?: string[];
+} | null): void;
 /**
  * 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.
+ * real secret and is skipped by the env-bound redaction pre-gate. A malformed
+ * host floor throws rather than degrading to the package's — a host that set 32
+ * must not silently run at a laxer floor, and a non-positive one would admit
+ * empty placeholders as secrets.
  * @returns {number}
  */
 export function minEnvSecretLen(): number;
@@ -63,10 +87,11 @@ export function dynamicSecretVars(env?: Record<string, string | undefined>): str
 export function extraSecretVars(env?: Record<string, string | undefined>): string[];
 /**
  * The env-bound redaction set: the UNION of the inference keys, the curated host
- * credentials, any credential-shaped var present in the environment, and the
- * operator's declared extras. 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.
+ * credentials, any credential-shaped var present in the environment, the
+ * operator's declared extras, and the host's configured extras. 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[]}
  */

package/types/claude-hooks/lib/hook-io.d.mts

@@ -79,6 +79,23 @@ export function lazyImportErrorFor(pkg: string): unknown;
  * @returns {string[]}
  */
 export function failedLazyPackages(): string[];
+/**
+ * Adopt a host's own remedy as the default {@link missingPackageMessage} and
+ * {@link missingPackageError} state when their caller passes none. This refusal
+ * to hard-code the wording is what prevents a fail-closed reason whose remedy
+ * names a command the host doesn't have: deep call sites (controlPlane's
+ * missing-package throw) never take a remedy argument, so without this seam
+ * they can only ever tell a reader to run `pnpm install` — wrong advice in a
+ * host whose one install entry point is its own setup script. An explicit
+ * per-call remedy still wins over the configured one. Unlike the hookgate
+ * marker there is no too-late window: the remedy is consulted at each throw,
+ * never resolved at module scope, so a later call steers every later message.
+ * Keep it to a sentence — a remedy beyond ~260 characters overruns the 300-char
+ * message budget (see missingPackageMessage).
+ * @param {string | null} remedy  host remedy text, or null to restore the package default
+ * @returns {void}
+ */
+export function configureMissingPackageRemedy(remedy: string | null): void;
 /**
  * The fail-closed reason for a package a hook could not load: the recorded
  * loader error plus the remedy. The cause is scrubbed (it is spliced into