agent-sanitizer 2.0.0

package/src/view-map.mjs

@@ -0,0 +1,354 @@
+/**
+ * Pure offset/text machinery for mapping between a file's on-disk bytes and
+ * the sanitized view the model reads (Layer 1 invisible/ANSI stripping, then
+ * Layer 4 secret redaction). No I/O — consumed by `./rehydrate.mjs`,
+ * which owns file access, the injected redactor, and policy.
+ *
+ * Coordinate spaces, disk → view:
+ *   disk    — the file's real bytes
+ *   cleaned — disk minus the runs Layer 1 deleted (`alignDeletions` recovers
+ *             them; a run at `start` sits immediately before cleaned[start])
+ *   view    — cleaned with each secret replaced by its [REDACTED…]
+ *             placeholder (`pairs` from the injected redactor’s map mode)
+ */
+
+/**
+ * Non-overlapping occurrence indices of `needle` in `haystack`.
+ * @param {string} haystack
+ * @param {string} needle
+ * @returns {number[]}
+ */
+export function occurrences(haystack, needle) {
+  // An empty needle has no meaningful occurrence here, and `indexOf("", k)`
+  // clamps to `haystack.length` rather than returning -1, so stepping by the
+  // needle length (0) would loop forever and grow `out` until a RangeError.
+  // Callers must never act on a zero-length match; return none.
+  if (needle === "") return [];
+  const out = [];
+  let i = haystack.indexOf(needle);
+  while (i !== -1) {
+    out.push(i);
+    i = haystack.indexOf(needle, i + needle.length);
+  }
+  return out;
+}
+
+/**
+ * Count of ALL matches of `needle` in `haystack`, including self-overlapping
+ * ones (stepping by 1, not by the needle length). `occurrences` deliberately
+ * steps by the needle length so it never reports overlapping spans — correct
+ * for splicing, but it undercounts a self-overlapping needle (e.g. "aa" in
+ * "aaa" is one non-overlapping match yet two overlapping ones). Ambiguity
+ * gating must use THIS count: an old_string that overlaps itself has more than
+ * one anchor a human (or the real Edit tool) could mean, so it is ambiguous even
+ * when `occurrences` reports a single non-overlapping match.
+ * @param {string} haystack
+ * @param {string} needle
+ * @returns {number}
+ */
+export function overlapAwareCount(haystack, needle) {
+  if (needle === "") return 0;
+  let count = 0;
+  let i = haystack.indexOf(needle);
+  while (i !== -1) {
+    count++;
+    i = haystack.indexOf(needle, i + 1);
+  }
+  return count;
+}
+
+/**
+ * The character runs Layer 1 deleted, located by greedy subsequence alignment
+ * (stripping only deletes, so `cleaned` is always a subsequence of `content`).
+ * Throws if the subsequence property does not hold — the caller fails closed.
+ * @param {string} content disk bytes
+ * @param {string} cleaned Layer-1 view of the same bytes
+ * @returns {{start: number, deleted: string}[]}
+ */
+export function alignDeletions(content, cleaned) {
+  const deletions = [];
+  let run = "";
+  let ci = 0;
+  for (let di = 0; di < content.length; di++) {
+    if (ci < cleaned.length && content[di] === cleaned[ci]) {
+      if (run) {
+        deletions.push({ start: ci, deleted: run });
+        run = "";
+      }
+      ci++;
+    } else {
+      run += content[di];
+    }
+  }
+  if (ci !== cleaned.length)
+    throw new Error("layer-1 view is not a subsequence of the file");
+  if (run) deletions.push({ start: ci, deleted: run });
+  return deletions;
+}
+
+/**
+ * Disk offset of cleaned-view offset `cleanedOffset`. A deleted run attaches
+ * immediately BEFORE the cleaned character at its `start`, so a span start
+ * lands after an adjacent run (preserving it) and a span end stops before one.
+ * @param {{start: number, deleted: string}[]} deletions sorted by start
+ * @param {number} cleanedOffset
+ * @param {boolean} isEnd span-end (exclusive) rather than span-start mapping
+ * @returns {number}
+ */
+function diskOffset(deletions, cleanedOffset, isEnd) {
+  let extra = 0;
+  for (const del of deletions) {
+    if (del.start < cleanedOffset || (!isEnd && del.start === cleanedOffset))
+      extra += del.deleted.length;
+    else break;
+  }
+  return cleanedOffset + extra;
+}
+
+/**
+ * Re-express each pair's `start` from a Unicode code-point offset — what the
+ * redactor's map mode emits (Python indexes strings by code point) — to a
+ * UTF-16 code-unit offset into `text`, the basis every other function here uses
+ * (JS `indexOf`/`slice`/`.length` count UTF-16 units). The two are identical for
+ * BMP-only text and diverge only when an astral character (e.g. an emoji)
+ * precedes a placeholder, where the code-point offset undercounts by one per
+ * astral char. `pair.start` is compared against UTF-16 view offsets throughout,
+ * so this conversion MUST run once at ingestion or an astral-preceded
+ * placeholder mis-anchors the edit onto the wrong bytes.
+ * @param {string} text the redacted view text the offsets index into
+ * @param {{placeholder: string, original: string, start: number}[]} pairs
+ * @returns {{placeholder: string, original: string, start: number}[]}
+ */
+export function pairsToUtf16(text, pairs) {
+  if (pairs.length === 0) return pairs;
+  const codePoints = Array.from(text);
+  // prefix[i] = UTF-16 length of the first i code points of `text`.
+  const prefix = new Array(codePoints.length + 1);
+  prefix[0] = 0;
+  for (let i = 0; i < codePoints.length; i++)
+    prefix[i + 1] = prefix[i] + codePoints[i].length;
+  // Code-point end of the previous pair's placeholder span. mapViewOffset's
+  // `else break` (and pairDiskSpans) assume pairs are sorted by start and never
+  // overlap; an out-of-order or overlapping pair would make the scan stop early
+  // and mis-map an offset onto the wrong bytes. Enforce the contract here.
+  let prevEnd = 0;
+  return pairs.map((pair) => {
+    // A redactor offset outside [0, codePoints.length] indexes `prefix` out of
+    // range and would silently yield `start: undefined`, which then poisons
+    // every downstream offset comparison (undefined < n is always false) and
+    // mis-anchors or corrupts the edit. Fail loudly instead — an out-of-range
+    // pair means the injected redactor's map contract was violated.
+    if (
+      !Number.isInteger(pair.start) ||
+      pair.start < 0 ||
+      pair.start > codePoints.length
+    )
+      throw new Error(
+        `redaction pair start ${pair.start} is out of range [0, ${codePoints.length}]`,
+      );
+    // Sorted + non-overlapping: `start` must be monotonically non-decreasing and
+    // each pair's placeholder span must end at or before the next pair's start.
+    // `prevEnd` already encodes the previous end, so `start < prevEnd` catches
+    // both an out-of-order start and an overlap in one comparison. Fail closed.
+    if (pair.start < prevEnd)
+      throw new Error(
+        `redaction pairs must be sorted and non-overlapping: pair start ${pair.start} precedes previous pair end ${prevEnd}`,
+      );
+    prevEnd = pair.start + Array.from(pair.placeholder).length;
+    return { ...pair, start: prefix[pair.start] };
+  });
+}
+
+/**
+ * Map a redacted-view offset to its Layer-1-cleaned offset, or null when the
+ * offset falls strictly inside a placeholder (no cleaned position corresponds).
+ * @param {{placeholder: string, original: string, start: number}[]} pairs
+ * @param {number} offset view offset
+ * @returns {number | null}
+ */
+function mapViewOffset(pairs, offset) {
+  let delta = 0;
+  for (const pair of pairs) {
+    const end = pair.start + pair.placeholder.length;
+    if (end <= offset) delta += pair.placeholder.length - pair.original.length;
+    else if (pair.start < offset) return null;
+    else break;
+  }
+  return offset - delta;
+}
+
+/**
+ * Resolve view span [viewStart, viewEnd) to its on-disk text and the redaction
+ * pairs it wholly contains, mapping across placeholder expansion (view →
+ * cleaned) and stripped invisible runs (cleaned → disk). Null when a boundary
+ * cuts through a placeholder. `invisibleBytes` counts stripped characters
+ * inside the span (replaced along with it); runs at the boundaries stay
+ * outside and are preserved. `cleanedText` is the span's Layer-1 view — the
+ * caller MUST verify that re-cleaning `diskText` reproduces it before acting:
+ * greedy alignment is ambiguous when a deleted run's edge character equals the
+ * adjacent kept character (an ANSI sequence ending in `m` before a kept `m`),
+ * and a mis-attributed run would mis-anchor the edit.
+ * @param {string} content disk file content
+ * @param {string} cleaned Layer-1 view of `content`
+ * @param {{text: string, pairs: {placeholder: string, original: string, start: number}[]}} view
+ * @param {{start: number, deleted: string}[]} deletions
+ * @param {number} viewStart
+ * @param {number} viewEnd
+ */
+export function resolveSpan(
+  content,
+  cleaned,
+  view,
+  deletions,
+  viewStart,
+  viewEnd,
+) {
+  const cleanedStart = mapViewOffset(view.pairs, viewStart);
+  const cleanedEnd = mapViewOffset(view.pairs, viewEnd);
+  if (cleanedStart === null || cleanedEnd === null) return null;
+  const diskText = content.slice(
+    diskOffset(deletions, cleanedStart, false),
+    diskOffset(deletions, cleanedEnd, true),
+  );
+  return {
+    diskText,
+    cleanedText: cleaned.slice(cleanedStart, cleanedEnd),
+    invisibleBytes: diskText.length - (cleanedEnd - cleanedStart),
+    pairs: view.pairs.filter(
+      (pair) =>
+        pair.start >= viewStart &&
+        pair.start + pair.placeholder.length <= viewEnd,
+    ),
+  };
+}
+
+/**
+ * All occurrences of any needle in `text`, ordered by position. Placeholder
+ * texts never substring-overlap one another (each ends in "]" right after its
+ * distinguishing label), so the sorted matches are non-overlapping.
+ * @param {string} text
+ * @param {string[]} needles
+ * @returns {{text: string, index: number}[]}
+ */
+export function orderedMatches(text, needles) {
+  const out = [];
+  for (const needle of needles)
+    for (const index of occurrences(text, needle))
+      out.push({ text: needle, index });
+  return out.sort((left, right) => left.index - right.index);
+}
+
+/**
+ * On-disk [start, end) span of every redaction pair, mapped from its view
+ * offset through placeholder expansion (view → cleaned) and stripped invisible
+ * runs (cleaned → disk). A run abutting the secret stays outside its span (it
+ * was never part of the secret); interior runs are included. Callers use these
+ * to detect an edit whose on-disk footprint intrudes into bytes the model was
+ * never shown.
+ * @param {{pairs: {placeholder: string, original: string, start: number}[]}} view
+ * @param {{start: number, deleted: string}[]} deletions
+ * @returns {{start: number, end: number}[]}
+ */
+export function pairDiskSpans(view, deletions) {
+  return view.pairs.map((pair) => {
+    // pair.start is a placeholder boundary; placeholders never overlap, so it is
+    // never strictly interior to another placeholder and mapViewOffset resolves.
+    const cleanedStart = mapViewOffset(view.pairs, pair.start);
+    if (cleanedStart === null)
+      throw new Error("redaction pair start maps inside another placeholder");
+    const cleanedEnd = cleanedStart + pair.original.length;
+    return {
+      start: diskOffset(deletions, cleanedStart, false),
+      end: diskOffset(deletions, cleanedEnd, true),
+    };
+  });
+}
+
+/**
+ * Substitute the placeholders in a model-authored new_string with the secrets
+ * they stand for. Resolution, strictest first: if the new placeholder
+ * sequence equals the matched span's, map 1:1 by position; otherwise each
+ * placeholder text must name a single distinct secret within the span. A
+ * placeholder naming a secret outside the span, or one whose text also
+ * appears literally in the matched file text, is unresolvable → deny.
+ * @param {string} oldS matched old_string (≡ the view span text)
+ * @param {string} newS model-authored replacement
+ * @param {{placeholder: string, original: string, start: number}[]} spanPairs
+ * @param {{placeholder: string, original: string, start: number}[]} filePairs
+ * @returns {{text: string, secrets: string[]} | {deny: string}}
+ */
+export function rehydrateNewString(oldS, newS, spanPairs, filePairs) {
+  const spanTexts = [...new Set(spanPairs.map((pair) => pair.placeholder))];
+  for (const phText of new Set(filePairs.map((pair) => pair.placeholder))) {
+    if (!newS.includes(phText)) continue;
+    if (!spanTexts.includes(phText)) {
+      if (!oldS.includes(phText))
+        return {
+          deny:
+            `new_string contains "${phText}", which stands for a redacted secret outside ` +
+            `the matched old_string; extend old_string to cover that secret, or drop it`,
+        };
+      continue; // literal file text the model matched verbatim
+    }
+    const produced = spanPairs.filter(
+      (pair) => pair.placeholder === phText,
+    ).length;
+    if (occurrences(oldS, phText).length > produced)
+      return {
+        deny:
+          `the matched text mixes literal "${phText}" text with a redacted secret sharing ` +
+          `that placeholder; cannot tell which occurrences in new_string are which — ` +
+          `edit the literal text and the secret's line separately`,
+      };
+  }
+  // With an empty span (the verbatim fast path) both sequences below are
+  // empty, so newS falls through unchanged.
+  const newSeq = orderedMatches(newS, spanTexts);
+  if (
+    newSeq.length === spanPairs.length &&
+    newSeq.every((match, i) => match.text === spanPairs[i].placeholder)
+  ) {
+    let out = "";
+    let last = 0;
+    newSeq.forEach((match, i) => {
+      out += newS.slice(last, match.index) + spanPairs[i].original;
+      last = match.index + match.text.length;
+    });
+    return {
+      text: out + newS.slice(last),
+      secrets: spanPairs.map((pair) => pair.original),
+    };
+  }
+
+  // Each placeholder text must name exactly one secret; resolve that mapping
+  // first, then splice in a SINGLE ordered pass. A chained
+  // `out.split(ph).join(secret)` per placeholder is unsound: an inserted secret
+  // whose bytes happen to contain a later placeholder text would be re-matched
+  // and corrupted (or partially exposed) by the next split. One pass over the
+  // ordered match positions only ever touches the original new_string bytes.
+  const valueByPh = new Map();
+  for (const phText of new Set(newSeq.map((match) => match.text))) {
+    const values = [
+      ...new Set(
+        spanPairs
+          .filter((pair) => pair.placeholder === phText)
+          .map((pair) => pair.original),
+      ),
+    ];
+    if (values.length > 1)
+      return {
+        deny:
+          `multiple distinct secrets in the matched text share the placeholder "${phText}" ` +
+          `and new_string changes their count or order; keep each one in place, or ` +
+          `edit them one at a time with unique surrounding context`,
+      };
+    valueByPh.set(phText, values[0]);
+  }
+  let out = "";
+  let last = 0;
+  for (const match of newSeq) {
+    out += newS.slice(last, match.index) + valueByPh.get(match.text);
+    last = match.index + match.text.length;
+  }
+  return { text: out + newS.slice(last), secrets: [...valueByPh.values()] };
+}

package/types/cf-charset.d.mts

@@ -0,0 +1,14 @@
+/**
+ * GENERATED by scripts/gen-invisible-charset.mjs from Node's Unicode data
+ * (\p{Cf}, Unicode 17.0) — DO NOT EDIT.
+ *
+ * The general-category Cf code points, PINNED at generation time. invisible.mjs
+ * strips exactly this set instead of testing \p{Cf} live, and the Python port
+ * reads the SAME set from data/invisible-charset.json's `cf_codepoints`, so both
+ * layers strip an identical Cf set regardless of each runtime's own Unicode
+ * version. Regenerate with `node scripts/gen-invisible-charset.mjs`;
+ * test/invisible-charset.test.mjs fails if this drifts from Node's \p{Cf}.
+ */
+export const UNICODE_VERSION: "17.0";
+/** @type {readonly number[]} Sorted ascending. */
+export const CF_CODEPOINTS: readonly number[];

package/types/confusables.d.mts

@@ -0,0 +1,85 @@
+/**
+ * True iff any UTF-16 code unit is outside ASCII (> 0x7F). Surrogates (astral
+ * chars) are >= 0xD800 so they count; ASCII control chars (tab, newline) stay
+ * ASCII. A plain loop, not a regex, to avoid a control char in the pattern.
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function hasNonAscii(value: string): boolean;
+/**
+ * Model-facing note naming the fields whose confusables were folded.
+ * @param {string[]} normalized
+ * @returns {string}
+ */
+export function normalizeContext(normalized: string[]): string;
+/**
+ * Replace every scan-flagged confusable with its ASCII (latin) equivalent.
+ * `index` is a UTF-16 offset into `text` and `char` is the matched glyph (which
+ * may be an astral, 2-unit char); splice highest-index first so a
+ * length-changing fold never shifts the offsets of earlier findings.
+ * @param {string} text
+ * @param {Array<{ index: number, char: string, latinEquivalent: string }>} findings
+ * @returns {string}
+ */
+export function foldConfusables(text: string, findings: Array<{
+    index: number;
+    char: string;
+    latinEquivalent: string;
+}>): string;
+/**
+ * Normalize confusable/homoglyph chars in the path/command fields of a tool
+ * call. Returns the updated input plus the fields touched, or null when nothing
+ * changed. Throws if the injected scanner fails (the caller fails closed: an
+ * un-normalized confusable could slip past a deny rule).
+ *
+ * `scan` is the injected confusable engine: `scan(text)` → `{ findings }` (an
+ * empty `findings` means no confusables). `fields` maps a tool name to the
+ * input keys to fold; defaults to {@link DEFAULT_FIELDS}.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @param {{ scan: (text: string) => { findings: Array<{ index: number, char: string, latinEquivalent: string }> }, fields?: Record<string, string[]> }} options
+ * @returns {{ updatedInput: any, normalized: string[] } | null}
+ */
+export function normalizeConfusables(tool: string, toolInput: any, { scan, fields }: {
+    scan: (text: string) => {
+        findings: Array<{
+            index: number;
+            char: string;
+            latinEquivalent: string;
+        }>;
+    };
+    fields?: Record<string, string[]>;
+}): {
+    updatedInput: any;
+    normalized: string[];
+} | null;
+/**
+ * Confusable / homoglyph folding for tool-call INPUT fields.
+ *
+ * Folding look-alike glyphs to their ASCII canon narrows the steganographic
+ * channel a model-to-model paste can open and closes the cross-script deny-rule
+ * bypass of CVE-2025-54794: a Cyrillic "а" dressed as ASCII "a" would not match
+ * an ASCII deny rule, so an attacker could slip a denied path/command past a
+ * filter by spelling it in look-alike code points.
+ *
+ * Folding is per-character and context-free: every glyph the injected scanner
+ * flags is replaced with its ASCII (latin) equivalent regardless of its
+ * neighbours. This deliberately catches an ISOLATED confusable with no ASCII
+ * anchor (a lone Cyrillic "а" in "/а") that a context-SENSITIVE canonicaliser
+ * would leave untouched — exactly the bypass to close — while leaving genuine
+ * non-confusable non-ASCII (accented Latin, CJK, emoji) alone, since a faithful
+ * scanner does not flag those.
+ *
+ * The confusable scanner is INJECTED, never imported: the canonical engine
+ * (namespace-guard's vision-weighted map) is a heavy, separately-owned peer.
+ * Pass `{ scan }` where `scan(text)` returns `{ findings: [{ index, char,
+ * latinEquivalent }] }` — `index` a UTF-16 offset, `char` the matched glyph
+ * (possibly a 2-unit astral char), `latinEquivalent` its ASCII canon.
+ */
+/**
+ * Default path/command fields to fold per tool. Agent-agnostic: the keys are
+ * the conventional Claude/Anthropic tool names, but a caller with a different
+ * tool surface passes its own `fields` map.
+ * @type {Record<string, string[]>}
+ */
+export const DEFAULT_FIELDS: Record<string, string[]>;

package/types/gates.d.mts

@@ -0,0 +1,37 @@
+/**
+ * True when either pre-gate alternation shape-matches `text`. Split into two
+ * literals (see SECRET_HINT) and OR'd so neither grows into a
+ * polynomial-backtracking shape.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function matchesSecretHint(text: string): boolean;
+/**
+ * Cheap, dependency-free pre-gates shared by the HTML layer (Layers 2 & 3) and
+ * re-exported from both the package root and the `./html` subpath.
+ *
+ * These are pulled out of `html.mjs` so the package root can re-export them
+ * without dragging in the heavy remark/rehype/unified graph: a static
+ * `export … from "./html.mjs"` would eagerly evaluate that ~200ms module on
+ * every root import, defeating the lazy-load design. This module imports
+ * nothing, so re-exporting it is free.
+ */
+/**
+ * Matches any HTML tag-like construct: opening tags, closing tags (`</`),
+ * comments and bogus declarations (`<!`), and processing instructions / bogus
+ * comments (`<?…?>`, which the HTML tokenizer hides exactly like a comment).
+ * The `<?` arm is what lets a PI-only document reach Layer 2's bogus-comment
+ * splice; without it such a document would skip the pipeline entirely. Gate for
+ * Layer 2 (HTML sanitization) and the HTML img/a exfil path in Layer 3.
+ */
+export const HTML_TAG_PRESENT: RegExp;
+/**
+ * Matches markdown link/image syntax (`](`, `![`) and reference link
+ * definitions (`[label]: url` at line start). Gate for Layer 3 (markdown
+ * exfiltration detection).
+ */
+export const MD_LINK_HINT: RegExp;
+/** @type {RegExp} */
+export const SECRET_HINT: RegExp;
+/** @type {RegExp} */
+export const SECRET_HINT_EXT: RegExp;

package/types/html.d.mts

@@ -0,0 +1,117 @@
+/**
+ * @param {string} styleStr
+ * @returns {boolean}
+ */
+export function isHiddenStyle(styleStr: string): boolean;
+/**
+ * True for an element a rendered page would not show: `hidden` attribute or a
+ * hiding inline style. Works on both hast nodes and parseHtmlTag results.
+ * @param {any} node
+ * @returns {boolean}
+ */
+export function isHiddenElement(node: any): boolean;
+/**
+ * @param {string} htmlValue
+ * @returns {string | null}
+ */
+export function isHiddenOpen(htmlValue: string): string | null;
+/**
+ * @param {string} htmlValue
+ * @returns {string | null}
+ */
+export function closingTagName(htmlValue: string): string | null;
+/**
+ * Replace each range of `text` with its kind's placeholder, preserving every
+ * byte outside the ranges verbatim. Overlapping/nested ranges are merged
+ * (defense-in-depth — the scanners emit disjoint ranges).
+ * @param {string} text
+ * @param {Array<{start: number, end: number, kind: "comment" | "hidden"}>} ranges
+ * @returns {string}
+ */
+export function spliceRanges(text: string, ranges: Array<{
+    start: number;
+    end: number;
+    kind: "comment" | "hidden";
+}>): string;
+/**
+ * Scan raw HTML for hidden content to strip and preserved tags to report.
+ * Returned ranges are offsets into `html`; comments and hidden elements span
+ * the whole element including its content (rehype positions cover open tag
+ * through matching close, and parse5 extends an unclosed element to the end
+ * of the fragment — fail-closed for truncated markup).
+ * @param {string} html
+ * @returns {{ ranges: Array<{start: number, end: number, kind: "comment" | "hidden"}>, warned: ReturnType<typeof newWarned> }}
+ */
+export function scanHtmlFragment(html: string): {
+    ranges: Array<{
+        start: number;
+        end: number;
+        kind: "comment" | "hidden";
+    }>;
+    warned: ReturnType<typeof newWarned>;
+};
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function looksLikeHtmlSource(text: string): boolean;
+/**
+ * Layer 2 over web-ingress text: splice out HTML comments and hidden elements
+ * (placeholders mark the cuts; all other bytes are preserved verbatim) and
+ * count preserved scripting/resource tags for the caller's warning. Returns
+ * null when there is nothing to strip and nothing to report.
+ * @param {string} text
+ * @returns {{ text: string, removed: { comments: number, hidden: number }, warned: { tags: Record<string, number>, dataSrc: number } } | null}
+ */
+export function sanitizeHtml(text: string): {
+    text: string;
+    removed: {
+        comments: number;
+        hidden: number;
+    };
+    warned: {
+        tags: Record<string, number>;
+        dataSrc: number;
+    };
+} | null;
+/**
+ * @param {string} url
+ * @returns {string | null}
+ */
+export function checkExfilUrl(url: string): string | null;
+/**
+ * Host of a flagged URL — enough for the warning to name the destination
+ * without echoing the payload-bearing query/fragment.
+ * @param {string} url
+ * @returns {string}
+ */
+export function urlHost(url: string): string;
+/**
+ * Layer 3: report data-exfil-shaped URLs in markdown links/images/definitions
+ * and HTML attributes (src/href/background/srcset/ping, form action/formaction,
+ * meta-refresh). Detection only — the text is never modified; the caller
+ * surfaces the threats as a warning.
+ * @param {string} text
+ * @returns {Array<{ isImage: boolean, reason: string, target: string }> | null}
+ */
+export function detectExfil(text: string): Array<{
+    isImage: boolean;
+    reason: string;
+    target: string;
+}> | null;
+export const REPORTED_TAGS: Set<string>;
+export const COMMENT_PLACEHOLDER: "[HTML comment removed]";
+export const HIDDEN_PLACEHOLDER: "[hidden HTML removed]";
+export const UNPARSEABLE_PLACEHOLDER: "[HTML unparseable \u2014 withheld]";
+export const DATA_URI_LENGTH_THRESHOLD: 4096;
+/** @returns {{ tags: Record<string, number>, dataSrc: number }} */
+declare function newWarned(): {
+    tags: Record<string, number>;
+    dataSrc: number;
+};
+import { HTML_TAG_PRESENT } from "./gates.mjs";
+import { MD_LINK_HINT } from "./gates.mjs";
+import { SECRET_HINT } from "./gates.mjs";
+import { SECRET_HINT_EXT } from "./gates.mjs";
+import { matchesSecretHint } from "./gates.mjs";
+export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint };

package/types/index.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Sanitize untrusted text before any LLM sees it.
+ *
+ * Always runs Layer 1 (invisible-char + ANSI stripping, lone-surrogate
+ * normalization). When `html` is true, also lazy-loads the HTML layer to splice
+ * out human-invisible HTML (comments, hidden elements — Layer 2) and detect
+ * data-exfil-shaped URLs (Layer 3); the heavy remark/rehype dependency is only
+ * imported on that path. The exfil scan runs on the pre-splice text so a beacon
+ * URL hidden inside a `display:none` element is still reported, not buried by
+ * its own removal.
+ *
+ * `found` names the categories neutralized; `warnings` carries the
+ * operator-facing notices. `cleaned` is always a string, and a change only
+ * ever carries a warning (no silent suppression). `options` is optional and
+ * tolerates an explicit `null`/`undefined` (treated the same as omitted) —
+ * only a genuinely malformed `text` (not a string) throws, deliberately: a
+ * 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).
+ * @param {string} text
+ * @param {{ html?: boolean } | null} [options]
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[] }>}
+ */
+export function sanitize(text: string, options?: {
+    html?: boolean;
+} | null): Promise<{
+    cleaned: string;
+    found: string[];
+    warnings: string[];
+}>;
+export { applyLayer1, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
+export { stripInvisible, stripInvisibleWithReport, isSgrOnly, STRIP, SGR_RE, CHECKS, CATEGORY, CATEGORY_LABELS, LINGUISTIC_SCRIPTS, VS, BLANK_NON_CF, LONG_RUN_RE, LONG_RUN_THRESHOLD, SCATTERED_THRESHOLD } from "./invisible.mjs";
+export { HTML_TAG_PRESENT, MD_LINK_HINT, SECRET_HINT, SECRET_HINT_EXT, matchesSecretHint } from "./gates.mjs";