agent-sanitizer 2.0.0

package/src/confusables.mjs

@@ -0,0 +1,199 @@
+/**
+ * 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 = {
+  Bash: ["command"],
+  Edit: ["file_path"],
+  Write: ["file_path"],
+  Read: ["file_path"],
+  MultiEdit: ["file_path"],
+  NotebookEdit: ["notebook_path"],
+  Grep: ["pattern", "path"],
+  Glob: ["pattern", "path"],
+  LS: ["path"],
+};
+
+/**
+ * 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) {
+  for (let i = 0; i < value.length; i++) {
+    if (value.charCodeAt(i) > 0x7f) return true;
+  }
+  return false;
+}
+
+/**
+ * Model-facing note naming the fields whose confusables were folded.
+ * @param {string[]} normalized
+ * @returns {string}
+ */
+export function normalizeContext(normalized) {
+  return `Confusable characters normalized in: ${normalized.join(", ")}. If a path now fails to resolve, the on-disk name itself contains the look-alike glyph shown.`;
+}
+
+// Cap the per-field fold list so a glyph-stuffed input can't bloat the context.
+const MAX_REPORTED_FOLDS = 8;
+
+/** @param {Array<{ char: string, latinEquivalent: string }>} findings */
+function describeFolds(findings) {
+  const folds = [
+    ...new Set(
+      findings.map(
+        (finding) =>
+          // char is always a non-empty confusable glyph, so codePointAt(0) is
+          // defined; the cast avoids an unreachable `?? 0` fallback branch.
+          `U+${
+            /** @type {number} */ (finding.char.codePointAt(0))
+              .toString(16)
+              .toUpperCase()
+              .padStart(4, "0")
+          } → "${finding.latinEquivalent}"`,
+      ),
+    ),
+  ];
+  const shown = folds.slice(0, MAX_REPORTED_FOLDS).join(", ");
+  return folds.length > MAX_REPORTED_FOLDS ? `${shown}, …` : shown;
+}
+
+/**
+ * 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, findings) {
+  let folded = text;
+  for (const finding of [...findings].sort(
+    (lhs, rhs) => rhs.index - lhs.index,
+  )) {
+    // Fail loud on a finding that does not match the actual bytes at its offset:
+    // a buggy/adversarial scanner reporting a wrong char/index would otherwise
+    // silently corrupt the path/command, defeating the deny-rule protection.
+    // A negative index is the gap the startsWith guard alone misses: when `char`
+    // is a prefix of the text, `startsWith(char, -1)` is true (the offset is
+    // clamped to 0), and the slice math below then mangles the string instead of
+    // throwing — so range-check the index explicitly first.
+    if (!Number.isInteger(finding.index) || finding.index < 0)
+      throw new Error(
+        `Confusable finding has an out-of-range index ${finding.index}`,
+      );
+    // An empty `char` makes startsWith("", i) vacuously true for ANY index, so
+    // the slice below inserts latinEquivalent without consuming a code point —
+    // silent insertion-corruption — and describeFolds then crashes on
+    // "".codePointAt(0). A finding must name a real matched glyph, so reject it
+    // loudly rather than let a buggy/adversarial scanner corrupt the input.
+    if (finding.char === "")
+      throw new Error(
+        `Confusable finding at index ${finding.index} has an empty char`,
+      );
+    if (!folded.startsWith(finding.char, finding.index))
+      throw new Error(
+        `Confusable finding does not match input at index ${finding.index}: expected ${JSON.stringify(finding.char)}`,
+      );
+    // An empty `latinEquivalent` slips past the ASCII loop below (it never
+    // iterates) and would splice the glyph to nothing — silently DELETING a
+    // character from a path/command. That is the same class of silent corruption
+    // the non-ASCII guard rejects, so fail loud here too rather than let a
+    // buggy/adversarial scanner erase input.
+    if (finding.latinEquivalent === "")
+      throw new Error(
+        `Confusable finding for ${JSON.stringify(
+          finding.char,
+        )} at index ${finding.index} has an empty latinEquivalent`,
+      );
+    // The replacement must be the ASCII canon the contract promises. A non-ASCII
+    // `latinEquivalent` would fold one confusable into ANOTHER look-alike (e.g.
+    // Cyrillic а → Cyrillic е), defeating the whole point — the cross-script
+    // deny-rule bypass would survive — and silently break the fold-to-ASCII
+    // invariant callers rely on, so reject it loudly.
+    for (const ch of finding.latinEquivalent)
+      if (/** @type {number} */ (ch.codePointAt(0)) > 0x7f)
+        throw new Error(
+          `Confusable latinEquivalent ${JSON.stringify(
+            finding.latinEquivalent,
+          )} is not ASCII`,
+        );
+    folded =
+      folded.slice(0, finding.index) +
+      finding.latinEquivalent +
+      folded.slice(finding.index + finding.char.length);
+  }
+  return folded;
+}
+
+/**
+ * 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,
+  toolInput,
+  { scan, fields = DEFAULT_FIELDS },
+) {
+  const keys = Object.hasOwn(fields, tool) ? fields[tool] : undefined;
+  if (!keys || toolInput === null || toolInput === undefined) return null;
+
+  // ASCII fast-path: only a field carrying a non-ASCII code unit can hold a
+  // confusable, so all-ASCII input never invokes the (heavy) scanner.
+  const candidates = keys.filter(
+    (k) => typeof toolInput[k] === "string" && hasNonAscii(toolInput[k]),
+  );
+  if (candidates.length === 0) return null;
+
+  const normalized = [];
+  const updatedInput = { ...toolInput };
+  for (const k of candidates) {
+    const { findings } = scan(toolInput[k]);
+    if (findings.length === 0) continue;
+    updatedInput[k] = foldConfusables(toolInput[k], findings);
+    normalized.push(`${k} (${describeFolds(findings)})`);
+  }
+
+  if (normalized.length === 0) return null;
+  return { updatedInput, normalized };
+}

package/src/gates.mjs

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+
+// ─── Cheap pre-gates ─────────────────────────────────────────────────────────
+
+/**
+ * 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 = /<[a-zA-Z/!?][^<>]*>/;
+
+/**
+ * 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 = /\]\(|!\[|^[ \t]*\[[^[\]\n]+\]:\s/m;
+
+// ─── Secret-shape pre-gate (Layer 3 URL-param reuse) ─────────────────────────
+// Cheap shape match that decides whether a URL parameter value carries a
+// credential (Layer 3). This hand-duplicates credential-shape knowledge that
+// also lives in the Python detect-secrets detectors (python/.../secret-detectors.json)
+// — a deliberately BROADER, shorter-run superset that adds keyword and
+// non-detector shapes (AWS `AKIA…`, JWT `eyJ…`, Slack `xox…`, …) and trims each
+// opaque run for ReDoS-safety. It is NOT derivable from that JSON: inlining the
+// detector regexes would reintroduce the cross-arm polynomial backtracking the
+// two-alternation split below exists to prevent, so this is a distinct
+// representation for a distinct constraint, not a copy. That duplication can't
+// be collapsed to one source, so it is instead DRIFT-GUARDED: the test in
+// test/secret-detectors-portability.test.mjs drives from the JSON and fails the
+// moment a detector is added/changed without a matching arm here — extend
+// SECRET_HINT when that fires.
+// Split across TWO regexes, combined by matchesSecretHint:
+// one alternation of every arm makes a redos analyzer see cross-arm polynomial
+// backtracking (each arm is linear alone, but the union was a 3rd-degree
+// polynomial on a long alnum run). Testing two independently-safe literals with
+// || is linear and keeps each under the analyzer's bar. The `(?<!...)`
+// lookbehinds on the EXT run-matching arms pin them to a token boundary so they
+// can't be retried at every offset; the atlasv1 arm in SECRET_HINT does the same.
+/** @type {RegExp} */
+export const SECRET_HINT =
+  /secret|token|password|passwd|pwd|bearer|credential|authorization|contrase[nñ]a|-----BEGIN|(?:api|auth|service|account|db|database|priv|private|client|access)[_-]?key|(?:db|database|key)[_-]?pass|(?:A3T|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}|gh[pousr]_[A-Za-z0-9]|github_pat_|gl[a-z]{2,12}-[0-9A-Za-z_-]{20}|sk-ant-|AIza[0-9A-Za-z_-]{35}|sk_live_|sk_test_|rk_live_|rk_test_|xox[bpasr]-|eyJ[A-Za-z0-9]|do[opr]_v1_[a-f0-9]{16}|v1\.0-[a-f0-9]{24}-|hv[sb]\.[A-Za-z0-9_-]{20}|(?<![a-z0-9])[a-z0-9]{14}\.atlasv1\.|sk-or-v1-[0-9a-f]{16}|gsk_[A-Za-z0-9]{16}|xai-[A-Za-z0-9]{16}|r8_[A-Za-z0-9]{16}/i;
+
+// Second alternation (see SECRET_HINT): kept a separate literal so a redos
+// analyzer vets each alternation in isolation.
+/** @type {RegExp} */
+export const SECRET_HINT_EXT =
+  /(?:AC|SK)[a-z0-9]{32}|SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}|sq0csp-[0-9A-Za-z_-]{43}|(?<![0-9])[0-9]{8,10}:[0-9A-Za-z_-]{35}|(?<![0-9a-z])[0-9a-z]{32}-us[0-9]{1,2}|(?<![A-Za-z0-9_-])[MNO][A-Za-z0-9_-]{23,25}\.[A-Za-z0-9_-]{6}\.[A-Za-z0-9_-]{27}|T3BlbkFJ|pypi-AgE|(?<![A-Za-z0-9])AKC[A-Za-z0-9]{10}|(?<![A-Za-z0-9])AP[0-9A-Fa-f][A-Za-z0-9]{8}|:\/\/[^\s:/@]{1,64}:[^\s:/@]{1,64}@|(?:key|pw|pass)["']?[\s:=>]+["']?[A-Za-z0-9_/+-]{20}/i;
+
+/**
+ * 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) {
+  return SECRET_HINT.test(text) || SECRET_HINT_EXT.test(text);
+}