agent-sanitizer 2.58.8 → 2.58.10

package/THREAT-MODEL.md

@@ -54,9 +54,11 @@ table](./README.md#entry-points) maps each to its import.
 
 **Reassembly hardening.** The two passes feed each other in _both_ directions:
 stripping an invisible char can reconstitute an ANSI escape its split had
-hidden, removing one ANSI sequence can reconstitute another, and removing an
-ANSI sequence can make two invisibles adjacent that were not—a joiner run the
-invisible pass treats as a payload channel rather than as linguistic. So Layer 1
+hidden, and removing an ANSI sequence can make two invisibles adjacent that were
+not—a joiner run the invisible pass treats as a payload channel rather than as
+linguistic. One ANSI pass alone is already final: each token ends where a
+terminal's parser ends it, and an introducer that the next one cancels is
+removed with it, so no removal joins the remainder into a new sequence. Layer 1
 does not run a fixed sequence of passes; it iterates the whole
 {ANSI, invisible} composition to a fixed point (bounded, since each round
 deletes at least one character), and only once that is stable does it sweep any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sanitizer",
-  "version": "2.58.8",
+  "version": "2.58.10",
   "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/python/agent_sanitizer/data/invisible-charset.json

@@ -478,5 +478,5 @@
     158,
     159
   ],
-  "escape_sequence_pattern": "(?:(?:\\u001b[\\u005d\\u0050\\u0058\\u005e\\u005f]|[\\u0090\\u0098\\u009d\\u009e\\u009f])[^\\u0007\\u000a\\u000d\\u0018\\u001a\\u001b\\u0090\\u0098\\u009c\\u009d\\u009e\\u009f]*(?:[\\u0007\\u0018\\u001a\\u009c]|\\u001b\\u005c|(?=[\\u000a\\u000d\\u001b\\u0090\\u0098\\u009d\\u009e\\u009f])|(?![\\s\\S]))|[\\u001b\\u009b][\\[()#;?]*(?![\\[()#;?])[0-9;:]*[A-PR-TZcf-nqrty~])"
+  "escape_sequence_pattern": "(?:(?:\\u001b[\\u005d\\u0050\\u0058\\u005e\\u005f]|[\\u0090\\u0098\\u009d\\u009e\\u009f])[^\\u0007\\u000a\\u000d\\u0018\\u001a\\u001b\\u0090\\u0098\\u009c\\u009d\\u009e\\u009f]*(?:[\\u0007\\u0018\\u001a\\u009c]|\\u001b\\u005c|(?=[\\u000a\\u000d\\u001b\\u0090\\u0098\\u009d\\u009e\\u009f])|(?![\\s\\S]))|(?:\\u001b\\[|\\u009b)[ -?]*(?:[@-~]|[\\u0018\\u001a]|(?=[\\u001b\\u0080\\u0081\\u0082\\u0083\\u0084\\u0085\\u0086\\u0087\\u0088\\u0089\\u008a\\u008b\\u008c\\u008d\\u008e\\u008f\\u0090\\u0091\\u0092\\u0093\\u0094\\u0095\\u0096\\u0097\\u0098\\u0099\\u009a\\u009b\\u009c\\u009d\\u009e\\u009f]))|\\u001b(?:[ -/]+(?:[0-~]|[\\u0018\\u001a]|(?=[\\u001b\\u0080\\u0081\\u0082\\u0083\\u0084\\u0085\\u0086\\u0087\\u0088\\u0089\\u008a\\u008b\\u008c\\u008d\\u008e\\u008f\\u0090\\u0091\\u0092\\u0093\\u0094\\u0095\\u0096\\u0097\\u0098\\u0099\\u009a\\u009b\\u009c\\u009d\\u009e\\u009f]))|[\\u0030\\u0031\\u0032\\u0033\\u0034\\u0035\\u0036\\u0037\\u0038\\u0039\\u003a\\u003b\\u003c\\u003d\\u003e\\u003f\\u0040\\u0041\\u0042\\u0043\\u0044\\u0045\\u0046\\u0047\\u0048\\u0049\\u004a\\u004b\\u004c\\u004d\\u004e\\u004f\\u0051\\u0052\\u0053\\u0054\\u0055\\u0056\\u0057\\u0059\\u005a\\u005c\\u0060\\u0061\\u0062\\u0063\\u0064\\u0065\\u0066\\u0067\\u0068\\u0069\\u006a\\u006b\\u006c\\u006d\\u006e\\u006f\\u0070\\u0071\\u0072\\u0073\\u0074\\u0075\\u0076\\u0077\\u0078\\u0079\\u007a\\u007b\\u007c\\u007d\\u007e]|[\\u0018\\u001a])|[\\u001b\\u0080\\u0081\\u0082\\u0083\\u0084\\u0085\\u0086\\u0087\\u0088\\u0089\\u008a\\u008b\\u008c\\u008d\\u008e\\u008f\\u0090\\u0091\\u0092\\u0093\\u0094\\u0095\\u0096\\u0097\\u0098\\u0099\\u009a\\u009b\\u009c\\u009d\\u009e\\u009f](?=[\\u001b\\u0080\\u0081\\u0082\\u0083\\u0084\\u0085\\u0086\\u0087\\u0088\\u0089\\u008a\\u008b\\u008c\\u008d\\u008e\\u008f\\u0090\\u0091\\u0092\\u0093\\u0094\\u0095\\u0096\\u0097\\u0098\\u0099\\u009a\\u009b\\u009c\\u009d\\u009e\\u009f]))"
 }

package/src/ansi.mjs

@@ -86,28 +86,15 @@ export const SGR_RE = new RegExp(SGR_SOURCE, "g");
 // scanner has already delimited.
 const SGR_ANCHORED_RE = new RegExp(`^${SGR_SOURCE}$`);
 
-// Private parameter-prefix and intermediate bytes that may follow an
-// introducer before the parameters (`ESC[?25h`, `ESC(B`, `ESC#8`). Also covers
-// the 7-bit `ESC [` CSI introducer's bracket itself.
-// The `[` is escaped though neither engine requires it: Python's `re` warns
-// `FutureWarning: Possible nested set` on a bare one, and this class ships as
-// the generated pattern a Python consumer compiles.
-const CSI_INTRO_CLASS = "[\\[()#;?]";
-const CSI_INTRO_RE = new RegExp(CSI_INTRO_CLASS);
-
-// ECMA-48 parameter bytes.
-const CSI_PARAM_CLASS = "[0-9;:]";
-const CSI_PARAM_RE = new RegExp(CSI_PARAM_CLASS);
-
-// ECMA-48 final bytes, minus the ones a terminal never accepts here. Digits are
-// PARAMETER bytes and can never terminate a sequence — an unterminated `ESC[`
-// must not eat trailing visible digits (`ESC[2024 report` is NOT `ESC[` +
-// final-byte `2`; it is an incomplete intro whose ESC the residual sweep
-// removes, leaving "2024 report" intact). `<=>?` (0x3C-0x3F) are private
-// PARAMETER-prefix bytes per ECMA-48 § 5.4, not finals — including them let a
-// private-marker sequence terminate one byte too early. `~` (0x7E) IS a real
-// final byte (vt220 function keys, `ESC[3~` for Delete) and is kept.
-const CSI_FINAL_CLASS = "[A-PR-TZcf-nqrty~]";
+// CSI as a terminal parses it (DEC's parser, vt100.net/emu/dec_ansi_parser):
+// after `ESC [` or U+009B every byte in 0x20-0x3F is swallowed — ECMA-48's
+// parameters (0x30-0x3F, private markers `<=>?` included) and intermediates
+// (0x20-0x2F, e.g. the space in DECSCUSR `ESC[1 q`), well-formed or not — until
+// one final byte (0x40-0x7E) ends the sequence. The two classes are disjoint, so
+// the arm cannot backtrack.
+const CSI_BODY_CLASS = "[ -?]";
+const CSI_BODY_RE = new RegExp(CSI_BODY_CLASS);
+const CSI_FINAL_CLASS = "[@-~]";
 const CSI_FINAL_RE = new RegExp(CSI_FINAL_CLASS);
 
 const ESC = 0x1b;
@@ -132,6 +119,11 @@ const SUB = 0x1a;
 const LF = 0x0a;
 const CR = 0x0d;
 
+// CAN and SUB cancel a sequence in progress (ECMA-48; DEC's parser executes
+// them and returns to ground), so they are consumed with the bytes they cancel.
+const SEQUENCE_CANCEL = [CAN, SUB];
+const INTRODUCER_RE = new RegExp(CONTROL_INTRODUCER_SOURCE);
+
 // PROBLEM CLASS — a control string whose body the grammar leaves as visible
 // text. ECMA-48 opens FIVE strings, not one: OSC (`ESC ]` / U+009D), DCS
 // (`ESC P` / U+0090), SOS (`ESC X` / U+0098), PM (`ESC ^` / U+009E) and APC
@@ -142,8 +134,8 @@ const CR = 0x0d;
 // prompt gate the two bare `ESC`s tokenized as inert orphans, which is the
 // benign kind, so the gate answered `note` instead of `block`.
 // The second byte of the 7-bit form, keyed by introducer. `P` also happens to
-// be a CSI final byte, so without this table `ESC P` completed a two-byte CSI
-// and the DCS body survived that way instead.
+// be an escape final byte, so without this table `ESC P` completed a two-byte
+// escape and the DCS body survived that way instead.
 const STRING_INTRO_7BIT = "]PX^_";
 const OSC_7BIT = "]";
 const OSC_C1 = 0x9d;
@@ -152,14 +144,30 @@ const OSC_C1 = 0x9d;
 // set: opening a string is exactly what ends the one already open.
 const STRING_INTRO_C1 = new Set([0x90, 0x98, OSC_C1, 0x9e, 0x9f]);
 
+// Every other escape, per ECMA-35 § 13.1: `ESC`, intermediate bytes (0x20-0x2F),
+// one final byte (0x30-0x7E) — charset designation `ESC(B`, DECALN `ESC#8`,
+// DECSC `ESC 7`, keypad mode `ESC=`, RIS `ESC c`. A final DIRECTLY after the ESC
+// excludes `[` and the string introducers: those open a CSI or control string
+// instead, so an incomplete `ESC[` stays an orphan rather than a complete escape.
+const ESC_INTERMEDIATE_CLASS = "[ -/]";
+const ESC_INTERMEDIATE_RE = new RegExp(ESC_INTERMEDIATE_CLASS);
+const ESC_FINAL_CLASS = "[0-~]";
+const ESC_FINAL_RE = new RegExp(ESC_FINAL_CLASS);
+const ESC_DIRECT_FINAL_CLASS = charClass(
+  Array.from({ length: 0x7e - 0x30 + 1 }, (_, i) => 0x30 + i).filter(
+    (cp) => !`[${STRING_INTRO_7BIT}`.includes(String.fromCharCode(cp)),
+  ),
+);
+const ESC_DIRECT_FINAL_RE = new RegExp(ESC_DIRECT_FINAL_CLASS);
+
 /**
  * The same grammar {@link scanAnsi} implements, as a REGEX SOURCE — the shipped
  * artifact for a consumer that cannot run this module.
  *
  * The scanner below is AUTHORITATIVE and this is derived from its own constants,
  * never the other way round: the scanner emits token KINDS a regex cannot, and
- * it is linear by construction where the regex form has to carry an explicit
- * guard to stay linear (see the CSI arm's lookahead). What a regex CAN be is data —
+ * it is linear by construction. The regex stays linear too: in every arm each
+ * quantified class is disjoint from what follows it. What a regex CAN be is data —
  * a stdlib-only Python filter on an uncontrolled host, with no install path for
  * this package, can read a pattern string but cannot import a tokenizer. So the
  * generator pins this into `data/invisible-charset.json` beside the introducer
@@ -192,17 +200,23 @@ export const ESCAPE_SEQUENCE_SOURCE = (() => {
     `(?:${charClass(consumed)}|${escapeSt}` +
     `|(?=${charClass(abortBefore)})|(?![\\s\\S]))`;
   const stringArm = `(?:${introducer7Bit}|${charClass(c1Introducers)})${body}${terminator}`;
-  // The negative lookahead pins the intro run MAXIMAL — which is what the
-  // scanner's `while` loop does — and in doing so removes the only place the
-  // two quantifiers could repartition (`;` is in both classes), so this cannot
-  // backtrack super-linearly the way an unbounded `[…;…]*[…;…]*` would.
+  // A sequence ends at its final byte, or is ABORTED (see scanCsi): CAN/SUB is
+  // consumed with it, another introducer ends it before that byte.
+  /** @param {string} finalClass */
+  const ending = (finalClass) =>
+    `(?:${finalClass}|${charClass(SEQUENCE_CANCEL)}|(?=${CONTROL_INTRODUCER_SOURCE}))`;
   const csiArm =
-    `${charClass([ESC, CSI_C1])}${CSI_INTRO_CLASS}*(?!${CSI_INTRO_CLASS})` +
-    `${CSI_PARAM_CLASS}*${CSI_FINAL_CLASS}`;
+    `(?:${unicodeEscape(ESC)}\\[|${unicodeEscape(CSI_C1)})` +
+    `${CSI_BODY_CLASS}*${ending(CSI_FINAL_CLASS)}`;
+  const escapeArm =
+    `${unicodeEscape(ESC)}(?:${ESC_INTERMEDIATE_CLASS}+${ending(ESC_FINAL_CLASS)}` +
+    `|${ESC_DIRECT_FINAL_CLASS}|${charClass(SEQUENCE_CANCEL)})`;
+  // isCancelledOrphan's introducer: one directly before another introducer.
+  const cancelledArm = `${CONTROL_INTRODUCER_SOURCE}(?=${CONTROL_INTRODUCER_SOURCE})`;
   // The string arm runs FIRST for the same reason it does in scanAnsi: `P` is
-  // also a CSI final byte, so a CSI-first alternation takes `ESC P` alone and
-  // leaves the DCS body as visible text.
-  return `(?:${stringArm}|${csiArm})`;
+  // also an escape final byte, so an escape-first alternation takes `ESC P`
+  // alone and leaves the DCS body as visible text.
+  return `(?:${stringArm}|${csiArm}|${escapeArm}|${cancelledArm})`;
 })();
 
 // The three SGR parameters that move the CONCEAL state (ECMA-48 § 8.3.117).
@@ -254,9 +268,9 @@ export const TOKEN_KIND = Object.freeze({
   /**
    * A 7-bit `ESC` that OPENS a CSI (`ESC [`) it never completes. Split from
    * {@link TOKEN_KIND.ORPHAN} because a terminal's CSI parser is STATEFUL: it
-   * keeps consuming what follows as parameters and intermediates until a final
-   * byte (0x40-0x7E) arrives, so `hello ESC[12 world` renders as `hello orld`
-   * — the ` w` is eaten as the sequence's intermediate and final. That is the
+   * executes a line break and keeps waiting for a final byte (0x40-0x7E), so
+   * `hello ESC[12` + LF + `world` renders `orld` on the second line — the `w`
+   * is eaten as the sequence's final. That is the
    * model-sees/human-sees divergence the gate exists for, so consumers that
    * downgrade an inert strip to a note must keep warning on this one; only a
    * lone `ESC` that opens nothing is inert.
@@ -279,7 +293,7 @@ export const TOKEN_KIND = Object.freeze({
 /**
  * True for either orphan kind — the tokens {@link scanAnsi} emits for an
  * introducer that completes no sequence, which the stripper must leave in place
- * for the residual sweep rather than splice (see stripAnsiOnce).
+ * for the residual sweep rather than splice (see stripAnsiFully).
  * @param {string} kind one of {@link TOKEN_KIND}
  * @returns {boolean}
  */
@@ -300,8 +314,8 @@ export function isOrphanKind(kind) {
  * `[` is the only lookahead that matters. The five string introducers — `ESC ]`,
  * `ESC P`, `ESC X`, `ESC ^`, `ESC _` — are consumed whole by
  * {@link scanControlString}, to the end of input if unterminated, so they never
- * reach here; every other second byte (`ESC (`, `ESC #`) bounds what a terminal
- * swallows to a byte or two rather than running until a final byte arrives.
+ * reach here; any other incomplete escape (`ESC (` before a line break) costs a
+ * terminal at most intermediate bytes and one final byte, not a CSI's long run.
  * @param {string} ch
  * @param {string} [next]  the following character, or undefined at end of input
  * @returns {string}
@@ -378,27 +392,75 @@ function scanControlString(text, start) {
 }
 
 /**
- * End index of the CSI / two-byte escape sequence starting at `start`, or -1
- * when the introducer completes no sequence.
- *
- * Single-pass and greedy: intro bytes, then parameter bytes, then exactly one
- * final byte. The previous regex form had to BOUND the intro run ({0,12})
- * because `;` lives in both the intro and parameter classes, so an unbounded
- * run let a `;#;#…` string be split between the two quantifiers — quadratic
- * backtracking (CodeQL js/polynomial-redos). A hand-written scanner never
- * backtracks, so the bound is gone and the scan is linear by construction.
+ * Where a sequence whose body run stopped at `i` ends, or -1 when it is still
+ * incomplete there. A final byte (`finalRe`) or CAN/SUB ends it after that
+ * byte. Another control introducer ABORTS it before that byte: a terminal
+ * drops what it has swallowed so far and starts afresh, so the aborted bytes are
+ * one token and the introducer is re-read as its own.
+ * @param {string} text
+ * @param {number} i
+ * @param {RegExp} finalRe
+ * @returns {number}
+ */
+function sequenceEnd(text, i, finalRe) {
+  if (i >= text.length) return -1;
+  if (finalRe.test(text[i]) || SEQUENCE_CANCEL.includes(text.charCodeAt(i)))
+    return i + 1;
+  return INTRODUCER_RE.test(text[i]) ? i : -1;
+}
+
+/**
+ * End index of the CSI sequence starting at `start`, or -1 when no complete or
+ * aborted CSI starts there. Greedy and single-pass over two disjoint classes.
  * @param {string} text
  * @param {number} start
  * @returns {number}
  */
 function scanCsi(text, start) {
   const code = text.charCodeAt(start);
-  if (code !== ESC && code !== CSI_C1) return -1;
+  let i;
+  if (code === CSI_C1) i = start + 1;
+  else if (code === ESC && text[start + 1] === "[") i = start + 2;
+  else return -1;
+  while (i < text.length && CSI_BODY_RE.test(text[i])) i++;
+  return sequenceEnd(text, i, CSI_FINAL_RE);
+}
+
+/**
+ * End index of the non-CSI escape (`ESC(B`, `ESC#8`, `ESC 7`) starting at
+ * `start`, or -1 when no complete or aborted escape starts there. A bare `ESC`
+ * directly before another introducer is not one: see {@link isCancelledOrphan}.
+ * @param {string} text
+ * @param {number} start
+ * @returns {number}
+ */
+function scanEscape(text, start) {
+  if (text.charCodeAt(start) !== ESC) return -1;
   let i = start + 1;
-  while (i < text.length && CSI_INTRO_RE.test(text[i])) i++;
-  while (i < text.length && CSI_PARAM_RE.test(text[i])) i++;
-  if (i < text.length && CSI_FINAL_RE.test(text[i])) return i + 1;
-  return -1;
+  while (i < text.length && ESC_INTERMEDIATE_RE.test(text[i])) i++;
+  if (i > start + 1) return sequenceEnd(text, i, ESC_FINAL_RE);
+  if (i >= text.length) return -1;
+  const directEnd =
+    ESC_DIRECT_FINAL_RE.test(text[i]) ||
+    SEQUENCE_CANCEL.includes(text.charCodeAt(i));
+  return directEnd ? i + 1 : -1;
+}
+
+/**
+ * True for an orphan a terminal CANCELS: the next character is another control
+ * introducer, which starts afresh, so this one can never complete. A strip
+ * splices it at once — left in place, removing the sequence after it would join
+ * it to the text beyond, a sequence no terminal ever parses.
+ * @param {string} text
+ * @param {AnsiToken} token  a token {@link scanAnsi} returned for `text`
+ * @returns {boolean}
+ */
+export function isCancelledOrphan(text, token) {
+  return (
+    isOrphanKind(token.kind) &&
+    token.end < text.length &&
+    INTRODUCER_RE.test(text[token.end])
+  );
 }
 
 // Drives the scan: jumping introducer-to-introducer keeps the common case (text
@@ -428,11 +490,12 @@ export function scanAnsi(text) {
   let match;
   while ((match = INTRODUCER_SCAN_RE.exec(text)) !== null) {
     const start = match.index;
-    // The string arms run FIRST: `ESC P` also completes a two-byte CSI (`P` is a
-    // final byte), so letting scanCsi answer first would take the DCS
+    // The string arms run FIRST: `ESC P` also completes a two-byte escape (`P`
+    // is a final byte), so letting scanEscape answer first would take the DCS
     // introducer alone and leave its body as visible text.
     const string = scanControlString(text, start);
-    const csiEnd = string ? -1 : scanCsi(text, start);
+    let csiEnd = string ? -1 : scanCsi(text, start);
+    if (!string && csiEnd < 0) csiEnd = scanEscape(text, start);
     let end = start + 1;
     /** @type {string} */
     let kind = orphanKindFor(text[start], text[start + 1]);

package/src/layer1.mjs

@@ -24,6 +24,7 @@
 import { stripInvisibleWithReport, CATEGORY, STRIP } from "./invisible.mjs";
 import {
   CONTROL_INTRODUCER_SOURCE,
+  isCancelledOrphan,
   isOrphanKind,
   orphanKindFor,
   scanAnsi,
@@ -63,60 +64,34 @@ function sweepIntroducers(text, kinds) {
 export const LONE_SURROGATE_RE =
   /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 
-const MAX_ANSI_PASSES = 3;
-
 /**
  * Splice out every complete ANSI sequence {@link scanAnsi} finds — SGR, other
- * CSI/two-byte escapes, and whole OSC strings. An ORPHAN introducer (one that
- * starts no sequence) is deliberately LEFT: deleting it here would drop the
- * `ESC` out of `ESC`<ZWSP>`[32m` before the invisible pass could reconstitute
- * the sequence, turning a hidden control into visible `[32m` in the model's
- * view. Orphans are removed by applyLayer1's residual sweep, once no
- * reconstitution is possible.
- * @param {string} text
+ * CSI/escapes, aborted sequences and whole control strings — in ONE pass, which
+ * is already a fixed point: a token ends only where a terminal's parser would,
+ * and a cancelled orphan (see {@link isCancelledOrphan}) goes with it, so no
+ * removal can join what is left into a new sequence. Any other ORPHAN
+ * introducer is deliberately LEFT: deleting it here would drop the `ESC` out of
+ * `ESC`<ZWSP>`[32m` before the invisible pass could reconstitute the sequence,
+ * turning a hidden control into visible `[32m` in the model's view. Orphans are
+ * removed by applyLayer1's residual sweep, once no reconstitution is possible.
+ * @param {string} input
  * @param {Set<string>} [kinds]  collects the {@link TOKEN_KIND} of every
- *   sequence this pass actually removed, so a caller can tell a display-only
- *   colour strip from a cursor/erase/OSC one without re-scanning (see
+ *   sequence actually removed, so a caller can tell a display-only colour strip
+ *   from a cursor/erase/OSC one without re-scanning (see
  *   {@link isBenignAnsiKinds}).
  * @returns {string}
  */
-function stripAnsiOnce(text, kinds) {
+export function stripAnsiFully(input, kinds) {
   let out = "";
   let last = 0;
-  for (const token of scanAnsi(text)) {
-    if (isOrphanKind(token.kind)) continue;
+  for (const token of scanAnsi(input)) {
+    if (isOrphanKind(token.kind) && !isCancelledOrphan(input, token)) continue;
     kinds?.add(token.kind);
-    out += text.slice(last, token.start);
+    out += input.slice(last, token.start);
     last = token.end;
   }
-  if (last === 0) return text;
-  return out + text.slice(last);
-}
-
-/**
- * Strip ANSI escape sequences to a fixed point. Removing one sequence can
- * reconstitute another around it (a lone ESC left of `ESC[32m[0m` gains the
- * trailing `[0m` once the inner sequence is removed, forming a brand-new valid
- * sequence the single pass would miss), so iterate — but only a fixed few
- * times. Bounding by the input's ESC count is quadratic on attacker-controlled
- * text: `("\x1b[").repeat(n) + "m".repeat(n)` reconstitutes exactly ONE
- * sequence per pass, so n full O(n) scans run, and 48 KB already costs seconds.
- * The passes are not what makes Layer 1 safe — applyLayer1's residual
- * CONTROL_INTRODUCER_RE sweep is, and it removes every ESC/C1 byte whatever
- * survives here. Past the bound a reconstituted sequence therefore degrades to
- * VISIBLE text rather than a hidden control, which is the fail-open direction.
- * @param {string} input
- * @param {Set<string>} [kinds]  see {@link stripAnsiOnce}; accumulates across passes
- * @returns {string}
- */
-export function stripAnsiFully(input, kinds) {
-  let prev = input;
-  let out = stripAnsiOnce(prev, kinds);
-  for (let pass = 1; pass < MAX_ANSI_PASSES && out !== prev; pass++) {
-    prev = out;
-    out = stripAnsiOnce(prev, kinds);
-  }
-  return out;
+  if (last === 0) return input;
+  return out + input.slice(last);
 }
 
 /**
@@ -260,8 +235,8 @@ export function isBenignAnsi(text) {
 
 // How many times the {ANSI strip, invisible strip} composition may re-run before
 // the sweep is forced. Each iteration deletes at least one character, so the
-// loop terminates on its own; the bound is a DoS guard on the same quadratic
-// argument as MAX_ANSI_PASSES (n rounds of O(n) scans on adversarial input).
+// loop terminates on its own; the bound is a DoS guard: n rounds of O(n) scans
+// on adversarial input is quadratic.
 // Three rounds is what the deepest REAL reconstitution needs — strip
 // invisibles, remove the ANSI they hid, strip the joiners that ANSI removal
 // made adjacent, confirm — so four leaves a round of margin. Deeper nesting is
@@ -270,7 +245,7 @@ export function isBenignAnsi(text) {
 // escape sequence, and every joiner that hides one is therefore stripped by the
 // FIRST invisible pass. Past the bound the composition simply stops early — the
 // final sweep still holds the no-introducer guarantee, and what is left degrades
-// to visible text (the fail-open direction), exactly as with MAX_ANSI_PASSES.
+// to visible text (the fail-open direction).
 const MAX_LAYER1_PASSES = 4;
 
 /**

package/types/ansi.d.mts

@@ -1,7 +1,7 @@
 /**
  * True for either orphan kind — the tokens {@link scanAnsi} emits for an
  * introducer that completes no sequence, which the stripper must leave in place
- * for the residual sweep rather than splice (see stripAnsiOnce).
+ * for the residual sweep rather than splice (see stripAnsiFully).
  * @param {string} kind one of {@link TOKEN_KIND}
  * @returns {boolean}
  */
@@ -15,13 +15,23 @@ export function isOrphanKind(kind: string): boolean;
  * `[` is the only lookahead that matters. The five string introducers — `ESC ]`,
  * `ESC P`, `ESC X`, `ESC ^`, `ESC _` — are consumed whole by
  * {@link scanControlString}, to the end of input if unterminated, so they never
- * reach here; every other second byte (`ESC (`, `ESC #`) bounds what a terminal
- * swallows to a byte or two rather than running until a final byte arrives.
+ * reach here; any other incomplete escape (`ESC (` before a line break) costs a
+ * terminal at most intermediate bytes and one final byte, not a CSI's long run.
  * @param {string} ch
  * @param {string} [next]  the following character, or undefined at end of input
  * @returns {string}
  */
 export function orphanKindFor(ch: string, next?: string): string;
+/**
+ * True for an orphan a terminal CANCELS: the next character is another control
+ * introducer, which starts afresh, so this one can never complete. A strip
+ * splices it at once — left in place, removing the sequence after it would join
+ * it to the text beyond, a sequence no terminal ever parses.
+ * @param {string} text
+ * @param {AnsiToken} token  a token {@link scanAnsi} returned for `text`
+ * @returns {boolean}
+ */
+export function isCancelledOrphan(text: string, token: AnsiToken): boolean;
 /**
  * Tokenize every raw control introducer in `text`.
  *
@@ -100,8 +110,8 @@ export const SGR_RE: RegExp;
  *
  * The scanner below is AUTHORITATIVE and this is derived from its own constants,
  * never the other way round: the scanner emits token KINDS a regex cannot, and
- * it is linear by construction where the regex form has to carry an explicit
- * guard to stay linear (see the CSI arm's lookahead). What a regex CAN be is data —
+ * it is linear by construction. The regex stays linear too: in every arm each
+ * quantified class is disjoint from what follows it. What a regex CAN be is data —
  * a stdlib-only Python filter on an uncontrolled host, with no install path for
  * this package, can read a pattern string but cannot import a tokenizer. So the
  * generator pins this into `data/invisible-charset.json` beside the introducer
@@ -139,9 +149,9 @@ export const TOKEN_KIND: Readonly<{
     /**
      * A 7-bit `ESC` that OPENS a CSI (`ESC [`) it never completes. Split from
      * {@link TOKEN_KIND.ORPHAN} because a terminal's CSI parser is STATEFUL: it
-     * keeps consuming what follows as parameters and intermediates until a final
-     * byte (0x40-0x7E) arrives, so `hello ESC[12 world` renders as `hello orld`
-     * — the ` w` is eaten as the sequence's intermediate and final. That is the
+     * executes a line break and keeps waiting for a final byte (0x40-0x7E), so
+     * `hello ESC[12` + LF + `world` renders `orld` on the second line — the `w`
+     * is eaten as the sequence's final. That is the
      * model-sees/human-sees divergence the gate exists for, so consumers that
      * downgrade an inert strip to a note must keep warning on this one; only a
      * lone `ESC` that opens nothing is inert.

package/types/layer1.d.mts

@@ -1,17 +1,18 @@
 /**
- * Strip ANSI escape sequences to a fixed point. Removing one sequence can
- * reconstitute another around it (a lone ESC left of `ESC[32m[0m` gains the
- * trailing `[0m` once the inner sequence is removed, forming a brand-new valid
- * sequence the single pass would miss), so iterate — but only a fixed few
- * times. Bounding by the input's ESC count is quadratic on attacker-controlled
- * text: `("\x1b[").repeat(n) + "m".repeat(n)` reconstitutes exactly ONE
- * sequence per pass, so n full O(n) scans run, and 48 KB already costs seconds.
- * The passes are not what makes Layer 1 safe — applyLayer1's residual
- * CONTROL_INTRODUCER_RE sweep is, and it removes every ESC/C1 byte whatever
- * survives here. Past the bound a reconstituted sequence therefore degrades to
- * VISIBLE text rather than a hidden control, which is the fail-open direction.
+ * Splice out every complete ANSI sequence {@link scanAnsi} finds — SGR, other
+ * CSI/escapes, aborted sequences and whole control strings — in ONE pass, which
+ * is already a fixed point: a token ends only where a terminal's parser would,
+ * and a cancelled orphan (see {@link isCancelledOrphan}) goes with it, so no
+ * removal can join what is left into a new sequence. Any other ORPHAN
+ * introducer is deliberately LEFT: deleting it here would drop the `ESC` out of
+ * `ESC`<ZWSP>`[32m` before the invisible pass could reconstitute the sequence,
+ * turning a hidden control into visible `[32m` in the model's view. Orphans are
+ * removed by applyLayer1's residual sweep, once no reconstitution is possible.
  * @param {string} input
- * @param {Set<string>} [kinds]  see {@link stripAnsiOnce}; accumulates across passes
+ * @param {Set<string>} [kinds]  collects the {@link TOKEN_KIND} of every
+ *   sequence actually removed, so a caller can tell a display-only colour strip
+ *   from a cursor/erase/OSC one without re-scanning (see
+ *   {@link isBenignAnsiKinds}).
  * @returns {string}
  */
 export function stripAnsiFully(input: string, kinds?: Set<string>): string;

package/types/src/ansi.d.mts

@@ -1,7 +1,7 @@
 /**
  * True for either orphan kind — the tokens {@link scanAnsi} emits for an
  * introducer that completes no sequence, which the stripper must leave in place
- * for the residual sweep rather than splice (see stripAnsiOnce).
+ * for the residual sweep rather than splice (see stripAnsiFully).
  * @param {string} kind one of {@link TOKEN_KIND}
  * @returns {boolean}
  */
@@ -15,13 +15,23 @@ export function isOrphanKind(kind: string): boolean;
  * `[` is the only lookahead that matters. The five string introducers — `ESC ]`,
  * `ESC P`, `ESC X`, `ESC ^`, `ESC _` — are consumed whole by
  * {@link scanControlString}, to the end of input if unterminated, so they never
- * reach here; every other second byte (`ESC (`, `ESC #`) bounds what a terminal
- * swallows to a byte or two rather than running until a final byte arrives.
+ * reach here; any other incomplete escape (`ESC (` before a line break) costs a
+ * terminal at most intermediate bytes and one final byte, not a CSI's long run.
  * @param {string} ch
  * @param {string} [next]  the following character, or undefined at end of input
  * @returns {string}
  */
 export function orphanKindFor(ch: string, next?: string): string;
+/**
+ * True for an orphan a terminal CANCELS: the next character is another control
+ * introducer, which starts afresh, so this one can never complete. A strip
+ * splices it at once — left in place, removing the sequence after it would join
+ * it to the text beyond, a sequence no terminal ever parses.
+ * @param {string} text
+ * @param {AnsiToken} token  a token {@link scanAnsi} returned for `text`
+ * @returns {boolean}
+ */
+export function isCancelledOrphan(text: string, token: AnsiToken): boolean;
 /**
  * Tokenize every raw control introducer in `text`.
  *
@@ -100,8 +110,8 @@ export const SGR_RE: RegExp;
  *
  * The scanner below is AUTHORITATIVE and this is derived from its own constants,
  * never the other way round: the scanner emits token KINDS a regex cannot, and
- * it is linear by construction where the regex form has to carry an explicit
- * guard to stay linear (see the CSI arm's lookahead). What a regex CAN be is data —
+ * it is linear by construction. The regex stays linear too: in every arm each
+ * quantified class is disjoint from what follows it. What a regex CAN be is data —
  * a stdlib-only Python filter on an uncontrolled host, with no install path for
  * this package, can read a pattern string but cannot import a tokenizer. So the
  * generator pins this into `data/invisible-charset.json` beside the introducer
@@ -139,9 +149,9 @@ export const TOKEN_KIND: Readonly<{
     /**
      * A 7-bit `ESC` that OPENS a CSI (`ESC [`) it never completes. Split from
      * {@link TOKEN_KIND.ORPHAN} because a terminal's CSI parser is STATEFUL: it
-     * keeps consuming what follows as parameters and intermediates until a final
-     * byte (0x40-0x7E) arrives, so `hello ESC[12 world` renders as `hello orld`
-     * — the ` w` is eaten as the sequence's intermediate and final. That is the
+     * executes a line break and keeps waiting for a final byte (0x40-0x7E), so
+     * `hello ESC[12` + LF + `world` renders `orld` on the second line — the `w`
+     * is eaten as the sequence's final. That is the
      * model-sees/human-sees divergence the gate exists for, so consumers that
      * downgrade an inert strip to a note must keep warning on this one; only a
      * lone `ESC` that opens nothing is inert.