agent-sanitizer 2.51.0 → 2.53.0

package/README.md

@@ -40,6 +40,15 @@ const result = await sanitize(pageSource, { html: true });
 // Layer 3 alone: flag exfil-shaped URLs without splicing anything (for text
 // that must stay byte-faithful, e.g. a PR diff). Implied by `html: true`.
 const scanned = await sanitize(diffText, { exfilScan: true });
+
+// Layer 3 reads an exact-digest-length hex value under a generic parameter
+// name (`?v=<md5>`, an ETag, a commit id) as a fingerprint. `flagDigestValues`
+// reports it as payload instead — more false positives, no 16-to-64-byte
+// channel under a name the caller picks. For monitors, not for splicing.
+const strict = await sanitize(logText, {
+  exfilScan: true,
+  flagDigestValues: true,
+});
 ```
 
 `sanitize` never throws and never silently drops content—any change comes with

package/THREAT-MODEL.md

@@ -140,6 +140,18 @@ attributes (`src`/`href`/`background`/`srcset`/`ping`, form `action`/`formaction
 - off-origin form actions and `meta refresh` redirects
 - `javascript:` / `vbscript:` targets
 
+**The digest exemption, and the switch that lifts it.** A value that is
+exactly one digest width of hex (32/40/56/64/96/128) under a generic parameter
+name reads as a fingerprint, not a payload: a cache-buster `?v=<md5>`, an ETag,
+a request id, a git commit, imgix's `?s=`. Under a name that already says
+credential the same characters read as payload and still flag. That leaves a
+residual, because the caller writing the URL picks the name: a payload padded to
+exactly one digest length rides under a generic one, buying 16 to 64 bytes per
+parameter. `flagDigestValues` moves the trade-off — it drops the exemption
+entirely, at the cost of flagging every real fingerprint — for a caller whose
+job is monitoring rather than presenting text to a model. Like every Layer 3
+option it can only ADD detection; there is no switch that turns a report off.
+
 Each threat carries a `reason` and the destination `target` (never the
 payload-bearing query/fragment) — the finding is shown to the operator with the
 target named and the payload withheld, since re-presenting the exfil payload in

package/bin/sanitize-cli.mjs

@@ -15,7 +15,7 @@
  * bare `{ text, html }` keeps working). Per op:
  *
  *   sanitize           { text, html? }            -> { cleaned, found, warnings, notes, splices? }
- *   sanitizeText       { text, html?, exfilScan? } -> { cleaned, warnings, notes, modified, sgrNote }
+ *   sanitizeText       { text, html?, exfilScan?, flagDigestValues? } -> { cleaned, warnings, notes, modified, sgrNote }
  *   classifyPrompt     { text }                    -> { action, reason? }
  *   scanInstructionFiles { globs, cwd? }           -> { findings: [{ file, findings }] }
  *   cleanFile          { path }                    -> { changed }
@@ -135,6 +135,7 @@ export const OPS = {
       {
         html: Boolean(req.html),
         exfilScan: Boolean(req.exfilScan),
+        flagDigestValues: Boolean(req.flagDigestValues),
       },
     );
     return { cleaned, warnings, notes, modified, sgrNote };

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

@@ -30,8 +30,13 @@
  * every session cry wolf, which is the alert fatigue this notice fights.
  *
  * Dependency-free on purpose: everything imports this, including hook-io, so a
- * back-import would close a cycle. The one emitter it needs is passed in.
+ * back-import would close a cycle. The one emitter it needs is passed in. The
+ * node builtins below are not such a dependency — they read one small manifest,
+ * once, to name this build's version in a report line.
  */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * Wall-clock a single hook invocation may spend before it is reported as slow.
@@ -62,6 +67,103 @@ export const SLOW_PROVISION_THRESHOLD_MS = 60000;
 const ISSUE_URL =
   "https://github.com/AlexanderMattTurner/agent-sanitizer/issues/new";
 
+/**
+ * Where this build's own version sits, relative to the directory this module
+ * runs from — each shipped artifact puts its manifest at a fixed offset, so the
+ * candidates are enumerated rather than searched for:
+ *
+ *   `../../.claude-plugin/plugin.json`        the installed Claude Code plugin,
+ *                                             whose bundle ships at
+ *                                             `plugin/dist/hooks/`
+ *   `../../plugin/.claude-plugin/plugin.json` a source checkout, where that same
+ *                                             manifest is the accurate version
+ *                                             and package.json's is the frozen
+ *                                             placeholder npm overwrites at
+ *                                             publish
+ *   `../../package.json`                      the npm package, which ships this
+ *                                             module at `claude-hooks/lib/` and
+ *                                             carries the published version
+ *
+ * First hit wins, and each candidate exists only inside the artifact it belongs
+ * to, so no foreign manifest is ever a candidate.
+ */
+const VERSION_MANIFESTS = [
+  "../../.claude-plugin/plugin.json",
+  "../../plugin/.claude-plugin/plugin.json",
+  "../../package.json",
+];
+
+/** Strict X.Y.Z, the only shape this project's release tooling ever writes. */
+const SEMVER = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+/**
+ * This build's version for the report line below, or null when nothing here can
+ * name it — a compiled hook binary whose `import.meta.url` points inside the
+ * executable reads no manifest, and the notice then asks the operator to look
+ * the version up rather than printing one nothing confirmed.
+ * @returns {string | null}
+ */
+function readVersion() {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  for (const manifest of VERSION_MANIFESTS) {
+    const version = readManifest(join(dir, manifest));
+    if (version !== null) return version;
+  }
+  return null;
+}
+
+/**
+ * The strict semver `path` carries, or null when it carries none.
+ *
+ * The read and the parse are caught because neither failure is this function's
+ * business: every candidate but one is absent in any given artifact, and a
+ * manifest a packager corrupted is not a reason for a PERFORMANCE notice to
+ * throw inside the hook it is reporting on.
+ * @param {string} path
+ * @returns {string | null}
+ */
+function readManifest(path) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+  return SEMVER.test(manifest?.version) ? manifest.version : null;
+}
+
+/** @type {string | null | undefined} */
+let cachedVersion;
+
+/**
+ * {@link readVersion}, computed once per process — the notice fires on a
+ * vanishing fraction of runs, and every hook imports this module on the hot
+ * path, so the manifest is read only once something is being reported.
+ * @returns {string | null}
+ */
+export function sanitizerVersion() {
+  if (cachedVersion === undefined) cachedVersion = readVersion();
+  return cachedVersion;
+}
+
+/**
+ * The clause naming the version an issue report should carry: this build's when
+ * it knows it, and otherwise an instruction to look it up — never a guess.
+ *
+ * Resolves the version HERE rather than in a caller's default argument, which
+ * would read the manifest on every healthy run too — the notices call this only
+ * once they have decided to report.
+ * @param {string | null | undefined} version  a caller's override; `undefined`
+ *   asks this build for its own, `null` says nothing could name it
+ * @returns {string}
+ */
+function versionClause(version) {
+  const resolved = version === undefined ? sanitizerVersion() : version;
+  return resolved
+    ? `agent-sanitizer ${resolved}`
+    : "your agent-sanitizer version";
+}
+
 /**
  * Milliseconds as the seconds string every notice below prints.
  *
@@ -439,6 +541,9 @@ function attributeWait(elapsedMs, cpuMs, redactorMs, hostMs) {
  * @param {SlowHookContext} [context]  known CPU time / payload size /
  *   triggering tool, so the notice is self-diagnosing rather than requiring the
  *   next reader to reconstruct what was slow by hand
+ * @param {string | null} [version]  the build to name in the report line;
+ *   omitted asks {@link sanitizerVersion}, and the shell port passes its own,
+ *   read from the plugin manifest it ships beside
  * @returns {string | null}
  */
 export function slowHookNotice(
@@ -446,6 +551,7 @@ export function slowHookNotice(
   elapsedMs,
   thresholdMs = SLOW_HOOK_THRESHOLD_MS,
   context,
+  version,
 ) {
   if (elapsedMs <= thresholdMs) return null;
   const cpuMs = context?.cpuMs;
@@ -473,7 +579,7 @@ export function slowHookNotice(
   return (
     `agent-sanitizer PERFORMANCE: the ${hookName} hook took ` +
     `${formatSeconds(elapsedMs)}s${formatContextSuffix(context)}, over its ${formatSeconds(thresholdMs)}s budget${attribution} ` +
-    `Tell the user, and suggest they report it at ${ISSUE_URL} with the hook name and ${timings}.`
+    `Tell the user, and suggest they report it at ${ISSUE_URL} with ${versionClause(version)}, the hook name and ${timings}.`
   );
 }
 
@@ -498,6 +604,7 @@ export function slowHookNotice(
  * @param {string} [advice] step-specific speedup advice — the default fits the
  *   engine install; the hook-binary download passes its own, because telling a
  *   user mid-download that uv would help is advice about the wrong step
+ * @param {string | null} [version]  see {@link slowHookNotice}
  * @returns {string | null}
  */
 export function slowProvisionNotice(
@@ -505,13 +612,14 @@ export function slowProvisionNotice(
   elapsedMs,
   thresholdMs = SLOW_PROVISION_THRESHOLD_MS,
   advice = "Installing uv makes it faster",
+  version,
 ) {
   if (elapsedMs <= thresholdMs) return null;
   return (
     `agent-sanitizer PERFORMANCE: one-time setup (${stepName}) took ` +
     `${formatSeconds(elapsedMs)}s, over its ${formatSeconds(thresholdMs)}s budget — ` +
     "this is paid once per install, not per tool call, so the session is not slow from here on. " +
-    `${advice}; if it happens on EVERY new session, report it at ${ISSUE_URL}.`
+    `${advice}; if it happens on EVERY new session, report it at ${ISSUE_URL} with ${versionClause(version)}.`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.51.0",
+  "version": "2.53.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/src/html.mjs

@@ -2720,9 +2720,13 @@ function rawParams(qs) {
  * @param {string} name    lowercased parameter name, for the allowlist gate
  * @param {string} value   RAW (un-decoded) value
  * @param {string} rawName RAW (case-preserved, un-decoded) name
+ * @param {boolean} flagDigestValues  drop the digest exemption entirely. The
+ *   name is the weak half of the test above, because the caller writing the
+ *   URL picks it: a payload padded to exactly one digest length otherwise
+ *   rides under any generic name.
  * @returns {string | null}
  */
-function paramExfilReason(name, value, rawName) {
+function paramExfilReason(name, value, rawName, flagDigestValues) {
   if (BENIGN_BLOB_PARAM_RE.test(name)) return null;
   const publicKeyId =
     PUBLIC_KEY_ID_PARAM_RE.test(name) && value.length < BLOB_VALUE_MIN_LEN;
@@ -2730,9 +2734,9 @@ function paramExfilReason(name, value, rawName) {
   // — a cache-buster `?v=`, an ETag, imgix's `?s=`, a commit id. Under a name
   // that already says credential the same 64 hex characters read as 32 bytes of
   // payload, so the exemption stops there.
-  const digestIsBenign = !(
-    KEYWORD_PARAM_NAME_RE.test(name) || matchesSecretHint(name)
-  );
+  const digestIsBenign =
+    !flagDigestValues &&
+    !(KEYWORD_PARAM_NAME_RE.test(name) || matchesSecretHint(name));
   for (const candidate of [rawName, value]) {
     if (!candidate) continue;
     // A leaked credential is an OPAQUE, separator-free token. Gate the
@@ -2784,7 +2788,10 @@ function rawUrlKeywordExfil(url) {
   for (const segment of url.slice(qIdx + 1).split("#")) {
     for (const [name, value, rawName] of rawParams(segment)) {
       if (!KEYWORD_PARAM_NAME_RE.test(name)) continue;
-      const reason = paramExfilReason(name, value, rawName);
+      // Only credential-named params reach here, and the digest exemption never
+      // applies to those, so there is no exemption for `flagDigestValues` to
+      // lift on this path.
+      const reason = paramExfilReason(name, value, rawName, false);
       if (reason) return reason;
     }
   }
@@ -2826,19 +2833,18 @@ function allParamsBenign(parsed) {
 /**
  * Walk the query and fragment parameters of a parsed URL for an exfil reason.
  * @param {URL} parsed
+ * @param {boolean} flagDigestValues
  * @returns {string | null}
  */
-function checkUrlParams(parsed) {
-  for (const [name, value, rawName] of rawParams(parsed.search.slice(1))) {
-    const reason = paramExfilReason(name, value, rawName);
-    if (reason) return reason;
-  }
-  // The fragment carries the same `key=value` channel (`#token=…`); a bare
-  // anchor (`#section-2`) yields one empty-value param that trips nothing.
-  for (const [name, value, rawName] of rawParams(parsed.hash.slice(1))) {
-    const reason = paramExfilReason(name, value, rawName);
-    if (reason) return reason;
-  }
+function checkUrlParams(parsed, flagDigestValues) {
+  // Query and fragment are one channel: `#token=…` carries what `?token=…` does,
+  // and a bare anchor (`#section-2`) yields one empty-value param that trips
+  // nothing.
+  for (const segment of [parsed.search.slice(1), parsed.hash.slice(1)])
+    for (const [name, value, rawName] of rawParams(segment)) {
+      const reason = paramExfilReason(name, value, rawName, flagDigestValues);
+      if (reason) return reason;
+    }
   return null;
 }
 
@@ -2861,10 +2867,18 @@ function checkUrlPath(parsed) {
 }
 
 /**
+ * `flagDigestValues` drops the digest exemption: an exact-digest-length hex
+ * value under a generic parameter name is reported as payload rather than read
+ * as a fingerprint. Off by default because the exemption is what keeps a
+ * cache-buster, an ETag and a commit id quiet; on for a caller whose cost of a
+ * missed 16-to-64-byte channel beats its cost of those false positives. Like
+ * every option this module takes, it can only ADD detection.
  * @param {string} url
+ * @param {{ flagDigestValues?: boolean }} [options]
  * @returns {string | null}
  */
-export function checkExfilUrl(url) {
+export function checkExfilUrl(url, options = {}) {
+  const { flagDigestValues = false } = options;
   // A browser strips tab/newline/CR ANYWHERE in a URL before resolving its
   // scheme, so `java\tscript:alert(1)` navigates as `javascript:`. Strip them
   // for the scheme tests (the payload/length checks below keep the raw string).
@@ -2913,7 +2927,7 @@ export function checkExfilUrl(url) {
     return "unusually long query string";
   if (parsed.hash.length > LONG_QUERY_THRESHOLD)
     return "unusually long fragment";
-  return checkUrlParams(parsed) || checkUrlPath(parsed);
+  return checkUrlParams(parsed, flagDigestValues) || checkUrlPath(parsed);
 }
 
 /**
@@ -3177,9 +3191,10 @@ function collectUrls(text) {
  * link somebody has to follow. Both are reported; the caller uses it to decide
  * how loudly (see the exfil tier in ./output.mjs).
  * @param {string} text
+ * @param {{ flagDigestValues?: boolean }} [options] see {@link checkExfilUrl}
  * @returns {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }> | null}
  */
-export function detectExfil(text) {
+export function detectExfil(text, options = {}) {
   if (!needsUrlScan(text)) return null;
 
   /** @type {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }>} */
@@ -3188,7 +3203,7 @@ export function detectExfil(text) {
   try {
     for (const { url, isImage, autoFetched, context } of collectUrls(text)) {
       const reason =
-        checkExfilUrl(url) ||
+        checkExfilUrl(url, options) ||
         (context !== "resource" && isOffOrigin(url)
           ? OFF_ORIGIN_REASON[context]
           : null);

package/src/index.mjs

@@ -102,14 +102,23 @@ export {
  * legitimate markup — matching the separate flags `sanitizeText` takes for the
  * tool-output pipeline, which needs Layer 3's detection without Layer 2's
  * splice.
+ *
+ * `flagDigestValues` widens Layer 3 only: it drops the digest exemption, so an
+ * exact-digest-length hex value under a generic parameter name is reported as
+ * payload rather than read as a cache-buster or an ETag. Off by default, and
+ * like `exfilScan` it can only ADD detection.
  * @param {string} text
- * @param {{ html?: boolean, exfilScan?: boolean } | null} [options]
+ * @param {{ html?: boolean, exfilScan?: boolean, flagDigestValues?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], splices?: Array<{ placeholder: string, original: string }> }>}
  */
 export async function sanitize(text, options) {
   if (typeof text !== "string")
     throw new TypeError("sanitize(text, options): text must be a string");
-  const { html = false, exfilScan = false } = options ?? {};
+  const {
+    html = false,
+    exfilScan = false,
+    flagDigestValues = false,
+  } = options ?? {};
   const { cleaned, found, warnings, notes, splices } = await sanitizeText(
     text,
     {
@@ -118,6 +127,7 @@ export async function sanitize(text, options) {
       // an opt-OUT would make `{ html: true, exfilScan: false }` splice Layer 2
       // while silently dropping Layer 3's report — a fail-open the docs deny.
       exfilScan: exfilScan || html,
+      flagDigestValues,
     },
   );
   return {

package/src/output.mjs

@@ -393,10 +393,13 @@ function processLayer1(text, sgrCarveOut) {
  * vet them before they leave. The transform itself stays pure — the caller owns
  * any persistence.
  * @param {PipelineState} state
- * @param {{ html?: boolean, exfilScan?: boolean, deadline?: Deadline }} options
+ * @param {{ html?: boolean, exfilScan?: boolean, flagDigestValues?: boolean, deadline?: Deadline }} options
  * @returns {Promise<{ reveal: string | undefined, splices: Array<{ placeholder: string, original: string }> }>}
  */
-async function applyMarkdownPipeline(state, { html, exfilScan, deadline }) {
+async function applyMarkdownPipeline(
+  state,
+  { html, exfilScan, flagDigestValues, deadline },
+) {
   const inputText = state.text;
   /** @type {string | undefined} */
   let reveal;
@@ -485,7 +488,7 @@ async function applyMarkdownPipeline(state, { html, exfilScan, deadline }) {
   // suspicious, not less, yet Layer 2 has already removed it from `cleaned`.
   if (runLayer3) {
     refuseIfSpent();
-    const threats = detectExfil(inputText);
+    const threats = detectExfil(inputText, { flagDigestValues });
     // Severity tracks who does the fetching. An auto-fetched target — an image,
     // a stylesheet, a form action, a meta refresh — exfiltrates the moment the
     // content renders, with nobody deciding anything: a WARNING. A plain LINK
@@ -571,6 +574,7 @@ async function vetStageValue(text, redact, findings, label) {
  * @typedef {{
  *   html?: boolean,
  *   exfilScan?: boolean,
+ *   flagDigestValues?: boolean,
  *   redact?: (text: string) => Promise<RedactResult|null> | (RedactResult|null),
  *   filterInjection?: (text: string) => Promise<Layer5Result|null> | (Layer5Result|null),
  *   sgrCarveOut?: boolean,

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

@@ -1,3 +1,10 @@
+/**
+ * {@link readVersion}, computed once per process — the notice fires on a
+ * vanishing fraction of runs, and every hook imports this module on the hot
+ * path, so the manifest is read only once something is being reported.
+ * @returns {string | null}
+ */
+export function sanitizerVersion(): string | null;
 /**
  * Milliseconds as the seconds string every notice below prints.
  *
@@ -149,9 +156,12 @@ export function startHookTimer(now?: () => number, cpuNow?: () => number): {
  * @param {SlowHookContext} [context]  known CPU time / payload size /
  *   triggering tool, so the notice is self-diagnosing rather than requiring the
  *   next reader to reconstruct what was slow by hand
+ * @param {string | null} [version]  the build to name in the report line;
+ *   omitted asks {@link sanitizerVersion}, and the shell port passes its own,
+ *   read from the plugin manifest it ships beside
  * @returns {string | null}
  */
-export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number, context?: SlowHookContext): string | null;
+export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?: number, context?: SlowHookContext, version?: string | null): string | null;
 /**
  * The line for a ONE-TIME provisioning step that overran
  * {@link SLOW_PROVISION_THRESHOLD_MS}, or null when it did not.
@@ -173,9 +183,10 @@ export function slowHookNotice(hookName: string, elapsedMs: number, thresholdMs?
  * @param {string} [advice] step-specific speedup advice — the default fits the
  *   engine install; the hook-binary download passes its own, because telling a
  *   user mid-download that uv would help is advice about the wrong step
+ * @param {string | null} [version]  see {@link slowHookNotice}
  * @returns {string | null}
  */
-export function slowProvisionNotice(stepName: string, elapsedMs: number, thresholdMs?: number, advice?: string): string | null;
+export function slowProvisionNotice(stepName: string, elapsedMs: number, thresholdMs?: number, advice?: string, version?: string | null): string | null;
 /**
  * Write the slow-hook notice to stderr and return it, or return null when the
  * run was within budget (writing nothing, so the quiet path stays quiet).
@@ -228,40 +239,6 @@ export function withSlowHookNotice<V extends {
  * @returns {boolean}  whether a notice was emitted
  */
 export function reportSlowHook(hookName: string, elapsedMs: number, hookEventName: string, emit: (event: string, fields: Record<string, unknown>) => void, writeErr?: (chunk: string) => void, context?: SlowHookContext): boolean;
-/**
- * The one place a hook's own cost is measured and reported — one threshold, one
- * message, one merge rule, shared by every hook.
- *
- * These hooks sit on the critical path of every tool call, prompt and session
- * start: whatever they spend, the user waits. A slow hook is also the hardest
- * bug to notice from inside — it looks exactly like a slow agent, so it goes
- * unreported for weeks (one SessionStart scan blocked startup for 30 SECONDS
- * before anyone traced it back here). A hook past the budget therefore says so
- * IN BAND, in the model's context, where it can be relayed to the operator.
- *
- * FOUR numbers, because wall-clock alone cannot say whose cost it is: a hook on
- * a contended host waits far longer than it computes (a 1.1 KB payload and a
- * 235 KB one both reported 7.2s on a loaded 2-vCPU box, against 0.3s of work).
- * So the notice prints, beside the clock, the CPU this process burned, the time
- * it spent inside redactor round trips, and the time it spent inside a HOST
- * EXTENSION it called ({@link chargeHostExtension}) — the redactor daemon and a
- * host callback's subprocess or socket peer are separate processes whose CPU this
- * one cannot see (see {@link processCpuMs}), so the call that waits for each is
- * the only measurable stand-in. The notice GATES on none of them: a hook wedged
- * on a dead redactor socket burns no CPU and is exactly the sanitizer's fault.
- *
- * The host-extension window is what turned "blocked on something outside the
- * sanitizer" — a verdict nobody can act on — into a named callee: a composer's
- * best-effort audit POST to an unreachable sink charged every tool call its full
- * 1.0s connect bound, and the notice could name none of it.
- *
- * ONE-TIME PROVISIONING is excluded (see {@link excludeProvisioning}): charging
- * an install to the hook that merely waited it out would make the FIRST call of
- * every session cry wolf, which is the alert fatigue this notice fights.
- *
- * Dependency-free on purpose: everything imports this, including hook-io, so a
- * back-import would close a cycle. The one emitter it needs is passed in.
- */
 /**
  * Wall-clock a single hook invocation may spend before it is reported as slow.
  *

package/types/html.d.mts

@@ -111,10 +111,19 @@ export function sanitizeHtml(text: string): {
     unparseable?: true;
 } | null;
 /**
+ * `flagDigestValues` drops the digest exemption: an exact-digest-length hex
+ * value under a generic parameter name is reported as payload rather than read
+ * as a fingerprint. Off by default because the exemption is what keeps a
+ * cache-buster, an ETag and a commit id quiet; on for a caller whose cost of a
+ * missed 16-to-64-byte channel beats its cost of those false positives. Like
+ * every option this module takes, it can only ADD detection.
  * @param {string} url
+ * @param {{ flagDigestValues?: boolean }} [options]
  * @returns {string | null}
  */
-export function checkExfilUrl(url: string): string | null;
+export function checkExfilUrl(url: string, options?: {
+    flagDigestValues?: boolean;
+}): string | null;
 /**
  * Host of a flagged URL — enough for the warning to name the destination
  * without echoing the payload-bearing query/fragment.
@@ -133,9 +142,12 @@ export function urlHost(url: string): string;
  * link somebody has to follow. Both are reported; the caller uses it to decide
  * how loudly (see the exfil tier in ./output.mjs).
  * @param {string} text
+ * @param {{ flagDigestValues?: boolean }} [options] see {@link checkExfilUrl}
  * @returns {Array<{ isImage: boolean, autoFetched: boolean, reason: string, target: string }> | null}
  */
-export function detectExfil(text: string): Array<{
+export function detectExfil(text: string, options?: {
+    flagDigestValues?: boolean;
+}): Array<{
     isImage: boolean;
     autoFetched: boolean;
     reason: string;

package/types/index.d.mts

@@ -35,13 +35,19 @@
  * legitimate markup — matching the separate flags `sanitizeText` takes for the
  * tool-output pipeline, which needs Layer 3's detection without Layer 2's
  * splice.
+ *
+ * `flagDigestValues` widens Layer 3 only: it drops the digest exemption, so an
+ * exact-digest-length hex value under a generic parameter name is reported as
+ * payload rather than read as a cache-buster or an ETag. Off by default, and
+ * like `exfilScan` it can only ADD detection.
  * @param {string} text
- * @param {{ html?: boolean, exfilScan?: boolean } | null} [options]
+ * @param {{ html?: boolean, exfilScan?: boolean, flagDigestValues?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], splices?: Array<{ placeholder: string, original: string }> }>}
  */
 export function sanitize(text: string, options?: {
     html?: boolean;
     exfilScan?: boolean;
+    flagDigestValues?: boolean;
 } | null): Promise<{
     cleaned: string;
     found: string[];

package/types/output.d.mts

@@ -38,6 +38,7 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * @typedef {{
  *   html?: boolean,
  *   exfilScan?: boolean,
+ *   flagDigestValues?: boolean,
  *   redact?: (text: string) => Promise<RedactResult|null> | (RedactResult|null),
  *   filterInjection?: (text: string) => Promise<Layer5Result|null> | (Layer5Result|null),
  *   sgrCarveOut?: boolean,
@@ -268,6 +269,7 @@ export type PipelineState = {
 export type SanitizeTextOptions = {
     html?: boolean;
     exfilScan?: boolean;
+    flagDigestValues?: boolean;
     redact?: (text: string) => Promise<RedactResult | null> | (RedactResult | null);
     filterInjection?: (text: string) => Promise<Layer5Result | null> | (Layer5Result | null);
     sgrCarveOut?: boolean;