agent-sanitizer 2.20.2 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.20.2",
+  "version": "2.21.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/index.mjs

@@ -6,19 +6,19 @@
  * lazy-loads the heavier HTML layer (Layers 2 & 3) so the remark/rehype graph
  * is only paid for by callers that ask for it.
  *
+ * Layers 1-3 are NOT implemented here: this module is a facade over the single
+ * implementation in `./output.mjs` (`sanitizeText`). The two used to be
+ * hand-synced copies and had already drifted apart in their warning prose, so
+ * the layer bodies live in exactly one place and this file only translates the
+ * facade's option/result shape. Importing `./output.mjs` costs nothing at module
+ * scope — its graph is dependency-free and it lazy-loads `./html.mjs` on the
+ * same terms this facade used to.
+ *
  * The low-level building blocks stay public via the `./invisible` and `./html`
  * subpath entries; import those directly when you want a single layer without
  * the convenience wrapper.
  */
-import { CATEGORY, describeStripped } from "./invisible.mjs";
-import { needsMarkdownPipeline } from "./gates.mjs";
-import { applyLayer1, LONE_SURROGATE_RE } from "./layer1.mjs";
-import {
-  describeExfil,
-  describeHtmlSanitized,
-  describeWarned,
-  LONE_SURROGATE_WARNING,
-} from "./warnings.mjs";
+import { sanitizeText } from "./output.mjs";
 
 // Layer 1 lives in the zero-dependency `./layer1.mjs`, shared verbatim with the
 // tool-output pipeline (`./output`) and the Edit-repair rehydrator
@@ -74,6 +74,15 @@ export {
  * caller passing the wrong TYPE for `text` gets a clear, named error instead
  * of an internal TypeError leaking implementation details (or a silent, wrong
  * coercion of e.g. a number to a string).
+ *
+ * The layer bodies live in `./output.mjs`; this is a facade over them, not a
+ * second implementation (see the module doc). It narrows `sanitizeText`'s result
+ * to the three fields this entry has always promised — `modified`/`sgrNote`
+ * describe the tool-output pipeline's banner, and `reveal` is produced only by
+ * options this facade does not expose. `html` selects Layers 2 AND 3 together
+ * here, which is the surface this entry has always had; `sanitizeText` takes
+ * them as separate flags for the tool-output pipeline, which needs Layer 3's
+ * detection without Layer 2's splice.
  * @param {string} text
  * @param {{ html?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[] }>}
@@ -82,69 +91,9 @@ export async function sanitize(text, options) {
   if (typeof text !== "string")
     throw new TypeError("sanitize(text, options): text must be a string");
   const { html = false } = options ?? {};
-  /** @type {string[]} */ const found = [];
-  /** @type {string[]} */ const warnings = [];
-
-  const { cleaned: layer1, deAnsi, found: invisFound } = applyLayer1(text);
-  let cleaned = layer1;
-  if (invisFound.length > 0) {
-    found.push(...invisFound);
-    warnings.push(describeStripped(invisFound, deAnsi));
-  }
-
-  const wellFormed = cleaned.replace(LONE_SURROGATE_RE, "\uFFFD");
-  if (wellFormed !== cleaned) {
-    cleaned = wellFormed;
-    found.push(CATEGORY.LONE_SURROGATES);
-    warnings.push(LONE_SURROGATE_WARNING);
-  }
-
-  // Layers 2 and 3 can only find something in text carrying an HTML tag or a
-  // markdown link, so the shared pre-gate decides whether the heavy
-  // remark/rehype graph is imported at all — the same gate `sanitizeText()`
-  // applies, so both entry points pay for (and skip) the import on exactly the
-  // same inputs.
-  if (!html || !needsMarkdownPipeline(cleaned))
-    return { cleaned, found, warnings };
-
-  let sanitizeHtml, detectExfil;
-  /* c8 ignore start -- a rejected dynamic import of a module that ships in
-     this very package (not an optional peer dep) requires corrupting
-     node_modules or the filesystem to trigger; there's no clean way to force
-     this from a test without fragile module-loader mocking (Node's
-     mock.module needs --experimental-test-module-mocks, which isn't wired
-     into this repo's test script). Fail loudly with context if it ever fires. */
-  try {
-    ({ sanitizeHtml, detectExfil } = await import("./html.mjs"));
-  } catch (importErr) {
-    throw new Error(
-      "sanitize: failed to load HTML module (is the optional HTML dependency installed?)",
-      { cause: importErr },
-    );
-  }
-  /* c8 ignore stop */
-  // Scan for exfil URLs on the text BEFORE Layer 2 splices anything out — a
-  // beacon URL hidden in a comment or hidden element is more suspicious, not
-  // less, yet Layer 2 would otherwise remove it from view before the scan.
-  const preSplice = cleaned;
-
-  const layer2 = sanitizeHtml(cleaned);
-  if (layer2) {
-    if (layer2.text !== cleaned) {
-      cleaned = layer2.text;
-      if (layer2.removed.comments > 0) found.push(CATEGORY.HTML_COMMENTS);
-      if (layer2.removed.hidden > 0) found.push(CATEGORY.HIDDEN_HTML);
-      warnings.push(describeHtmlSanitized(layer2.removed));
-    }
-    const preserved = describeWarned(layer2.warned);
-    if (preserved) warnings.push(preserved);
-  }
-
-  const threats = detectExfil(preSplice);
-  if (threats) {
-    found.push(CATEGORY.EXFIL_URLS);
-    warnings.push(describeExfil(threats));
-  }
-
+  const { cleaned, found, warnings } = await sanitizeText(text, {
+    html,
+    exfilScan: html,
+  });
   return { cleaned, found, warnings };
 }

package/src/output.mjs

@@ -141,9 +141,11 @@ function normalizeLoneSurrogates(text) {
 }
 
 /**
- * @typedef {{ text: string, warnings: string[], modified: boolean, sgrNote: boolean }} PipelineState
+ * @typedef {{ text: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean }} PipelineState
  *   The running state of one {@link sanitizeText} call. Layers read `text` and
- *   mutate it ONLY through {@link applyMutation}.
+ *   mutate it ONLY through {@link applyMutation}. `found` is the machine-readable
+ *   twin of `warnings`: the {@link CATEGORY} codes for whatever Layers 1-3
+ *   neutralized or flagged.
  */
 
 /**
@@ -273,16 +275,19 @@ export function deleteVerbatimSpans(text, spans) {
  * with a terse note, not the WARNING prefix.
  * @param {string} text
  * @param {boolean} sgrCarveOut
- * @returns {{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean }}
+ * @returns {{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean }}
  */
 function processLayer1(text, sgrCarveOut) {
   /** @type {string[]} */
   const warnings = [];
+  /** @type {string[]} */
+  const found = [];
   let modified = false;
   let sgrNote = false;
   const { cleaned: layer1, deAnsi, found: invisFound } = applyLayer1(text);
   let cleaned = layer1;
   if (invisFound.length > 0) {
+    found.push(...invisFound);
     modified = true;
     // Display-only color with the carve-out enabled: the strip removed cosmetic
     // styling and nothing else (found is exactly [ANSI], so zero invisible
@@ -304,9 +309,10 @@ function processLayer1(text, sgrCarveOut) {
     cleaned = wellFormed;
     modified = true;
     sgrNote = false;
+    found.push(CATEGORY.LONE_SURROGATES);
     warnings.push(LONE_SURROGATE_WARNING);
   }
-  return { cleaned, warnings, modified, sgrNote };
+  return { cleaned, found, warnings, modified, sgrNote };
 }
 
 /**
@@ -327,7 +333,23 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
   let reveal;
   if ((!html && !exfilScan) || !needsMarkdownPipeline(inputText))
     return undefined;
-  const { sanitizeHtml, detectExfil } = await import("./html.mjs");
+  let sanitizeHtml, detectExfil;
+  /* c8 ignore start -- a rejected dynamic import of a module that ships in
+     this very package (not an optional peer dep) requires corrupting
+     node_modules or the filesystem to trigger; there's no clean way to force
+     this from a test without fragile module-loader mocking (Node's
+     mock.module needs --experimental-test-module-mocks, which isn't wired
+     into this repo's test script). Fail loudly with context if it ever fires. */
+  try {
+    ({ sanitizeHtml, detectExfil } = await import("./html.mjs"));
+  } catch (importErr) {
+    throw new Error(
+      "agent-sanitizer: failed to load ./html.mjs, so Layers 2/3 could not run " +
+        "(are the package's remark/rehype dependencies installed?)",
+      { cause: importErr },
+    );
+  }
+  /* c8 ignore stop */
   // Layer 2 — strips what a rendered page would not show (comments, hidden
   // elements); scripting/resource tags preserved+reported.
   if (html) {
@@ -336,6 +358,9 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
       if (layer2.text !== state.text) {
         reveal = state.text;
         applyMutation(state, layer2.text);
+        if (layer2.removed.comments > 0)
+          state.found.push(CATEGORY.HTML_COMMENTS);
+        if (layer2.removed.hidden > 0) state.found.push(CATEGORY.HIDDEN_HTML);
         state.warnings.push(describeHtmlSanitized(layer2.removed));
       }
       const preserved = describeWarned(layer2.warned);
@@ -348,7 +373,10 @@ async function applyMarkdownPipeline(state, { html, exfilScan }) {
   // suspicious, not less, yet Layer 2 has already removed it from `cleaned`.
   if (exfilScan) {
     const threats = detectExfil(inputText);
-    if (threats) state.warnings.push(describeExfil(threats));
+    if (threats) {
+      state.found.push(CATEGORY.EXFIL_URLS);
+      state.warnings.push(describeExfil(threats));
+    }
   }
   return reveal;
 }
@@ -421,18 +449,23 @@ async function vetStageValue(text, redact, warnings, label) {
  * through {@link runRedact}, so a layer cannot re-establish some of the
  * post-mutation invariants and forget the rest, and every string in the returned
  * object has traversed Layer 4.
+ *
+ * `found` is the machine-readable twin of `warnings` — the {@link CATEGORY}
+ * codes for what Layers 1-3 neutralized or flagged, in the order the layers ran.
+ * Layers 4 and 5 have no category codes (their findings are the injected seam's
+ * own vocabulary), so they contribute warnings only.
  * @param {string} text
  * @param {SanitizeTextOptions} [options]
- * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export async function sanitizeText(text, options = {}) {
   const { redact, filterInjection, sgrCarveOut = false } = options;
-  const { warnings, cleaned, modified, sgrNote } = processLayer1(
+  const { warnings, found, cleaned, modified, sgrNote } = processLayer1(
     text,
     sgrCarveOut,
   );
   /** @type {PipelineState} */
-  const state = { text: cleaned, warnings, modified, sgrNote };
+  const state = { text: cleaned, found, warnings, modified, sgrNote };
 
   const revealText = await applyMarkdownPipeline(state, options);
 
@@ -483,6 +516,7 @@ export async function sanitizeText(text, options = {}) {
         );
   return {
     cleaned: state.text,
+    found: state.found,
     warnings: state.warnings,
     modified: state.modified,
     sgrNote: state.sgrNote,

package/types/index.d.mts

@@ -17,6 +17,15 @@
  * caller passing the wrong TYPE for `text` gets a clear, named error instead
  * of an internal TypeError leaking implementation details (or a silent, wrong
  * coercion of e.g. a number to a string).
+ *
+ * The layer bodies live in `./output.mjs`; this is a facade over them, not a
+ * second implementation (see the module doc). It narrows `sanitizeText`'s result
+ * to the three fields this entry has always promised — `modified`/`sgrNote`
+ * describe the tool-output pipeline's banner, and `reveal` is produced only by
+ * options this facade does not expose. `html` selects Layers 2 AND 3 together
+ * here, which is the surface this entry has always had; `sanitizeText` takes
+ * them as separate flags for the tool-output pipeline, which needs Layer 3's
+ * detection without Layer 2's splice.
  * @param {string} text
  * @param {{ html?: boolean } | null} [options]
  * @returns {Promise<{ cleaned: string, found: string[], warnings: string[] }>}

package/types/output.d.mts

@@ -49,12 +49,18 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * through {@link runRedact}, so a layer cannot re-establish some of the
  * post-mutation invariants and forget the rest, and every string in the returned
  * object has traversed Layer 4.
+ *
+ * `found` is the machine-readable twin of `warnings` — the {@link CATEGORY}
+ * codes for what Layers 1-3 neutralized or flagged, in the order the layers ran.
+ * Layers 4 and 5 have no category codes (their findings are the injected seam's
+ * own vocabulary), so they contribute warnings only.
  * @param {string} text
  * @param {SanitizeTextOptions} [options]
- * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, options?: SanitizeTextOptions): Promise<{
     cleaned: string;
+    found: string[];
     warnings: string[];
     modified: boolean;
     sgrNote: boolean;
@@ -183,10 +189,13 @@ export type Layer5Result = {
 };
 /**
  * The running state of one {@link sanitizeText} call. Layers read `text` and
- * mutate it ONLY through {@link applyMutation}.
+ * mutate it ONLY through {@link applyMutation}. `found` is the machine-readable
+ * twin of `warnings`: the {@link CATEGORY} codes for whatever Layers 1-3
+ * neutralized or flagged.
  */
 export type PipelineState = {
     text: string;
+    found: string[];
     warnings: string[];
     modified: boolean;
     sgrNote: boolean;