humanish 0.114.0 → 0.116.0

package/dist/comms/connections.js

@@ -54,12 +54,13 @@ export async function readCommsConnections(cwd) {
         return empty();
     if ((await lstat(file)).size > 65_536)
         throw new Error("Connection configuration is too large.");
-    const bytes = await readContainedRegularFile(root, "comms.yaml");
-    if (!bytes || bytes.length > 65_536)
+    const read = await readContainedRegularFile(root, "comms.yaml", 65_536);
+    // Gone since the check above, or refused: either way it cannot be read safely.
+    if (read.status !== "read")
         throw new Error("Cannot safely read connection configuration.");
     // YAML diagnostics may echo the offending value; do not let them reach a status or frame.
     try {
-        return parseConnections(parse(bytes.toString("utf8"), { maxAliasCount: 0 }));
+        return parseConnections(parse(read.bytes.toString("utf8"), { maxAliasCount: 0 }));
     }
     catch {
         throw new Error("Invalid connection configuration.");

package/dist/comms/email-catch.js

@@ -9,6 +9,7 @@
 //
 // 127.0.0.1 only; request bodies are never logged; request size is capped.
 import { createServer } from "node:http";
+import { readBodyAtMost } from "../observer/http.js";
 import { capturedInlineImages } from "./images.js";
 // ---------------------------------------------------------------- shared parse helpers
 function str(value) {
@@ -116,26 +117,6 @@ export const DEFAULT_EMAIL_PROFILES = [
     sendgridEmailProfile,
 ];
 // ---------------------------------------------------------------- server
-class BodyTooLargeError extends Error {
-}
-function readBody(req, limit) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        req.on("data", (chunk) => {
-            size += chunk.length;
-            if (size > limit) {
-                // Reject without destroying the socket here: the handler responds 413 cleanly first (a
-                // write-after-destroy would otherwise reset the connection), then tears the request down.
-                reject(new BodyTooLargeError("request body too large"));
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
-        req.on("error", reject);
-    });
-}
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
 /**
  * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
@@ -170,21 +151,16 @@ export async function startEmailCatchServer(channel, options = {}) {
             respondJson(res, 404, { error: "not found" });
             return;
         }
-        let raw;
-        try {
-            raw = await readBody(req, MAX_BODY_BYTES);
-        }
-        catch (error) {
-            if (!res.headersSent)
-                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, {
-                    error: "request body could not be read",
-                });
-            req.destroy();
+        const body = await readBodyAtMost(req, MAX_BODY_BYTES).catch(() => undefined);
+        if (body === null || body === undefined) {
+            // The rest of the body is never read, so the connection closes after this answer.
+            res.setHeader("connection", "close");
+            respondJson(res, body === null ? 413 : 400, { error: "request body could not be read" });
             return;
         }
         let parsed;
         try {
-            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+            parsed = JSON.parse(body.length > 0 ? body.toString("utf8") : "{}");
         }
         catch {
             respondJson(res, 422, { error: "invalid JSON body" });

package/dist/comms/setup.js

@@ -13,6 +13,14 @@ import { resolveStudyManifest } from "../study/discover.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 import { otherStudyFiles } from "../study/files.js";
 import { isNodeError } from "../run/type-guards.js";
+/** The most of a study file the receiving copy reads, for its source and its destination. */
+const MAX_STUDY_COPY_BYTES = 1024 * 1024;
+/** The read found exactly `expected`, or found nothing where `expected` is null. */
+function readsAs(read, expected) {
+    return expected === null
+        ? read.status === "missing"
+        : read.status === "read" && read.bytes.equals(expected);
+}
 export async function checkCommsConnection(args) {
     const base = {
         schema: "humanish.comms-check.v1",
@@ -128,9 +136,10 @@ export async function configureCommsStudy(args) {
         const rel = path
             .relative(root.requestedPath, path.resolve(args.cwd, source.path))
             .replace(/\\/g, "/");
-        const bytes = await readContainedRegularFile(root, rel);
-        if (!bytes || bytes.length > 1024 * 1024)
+        const sourceRead = await readContainedRegularFile(root, rel, MAX_STUDY_COPY_BYTES);
+        if (sourceRead.status !== "read")
             return { ...base, message: "The study file is missing or too large." };
+        const bytes = sourceRead.bytes;
         const text = bytes.toString("utf8");
         const raw = parse(text);
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -182,13 +191,12 @@ export async function configureCommsStudy(args) {
                 ...base,
                 message: `${others.join(", ")} already uses the name ${stem}. Rename or remove it before configuring email, so \`run ${stem}\` reads one file.`,
             };
-        let prior;
-        try {
-            prior = await readContainedRegularFile(root, destination);
-        }
-        catch {
+        // An existing destination is replaced only when its bytes are in the plan token, so one that
+        // cannot be read whole is refused instead of being taken as absent.
+        const destinationRead = await readContainedRegularFile(root, destination, MAX_STUDY_COPY_BYTES);
+        if (destinationRead.status === "refused")
             return { ...base, message: "The local destination could not be read safely." };
-        }
+        const prior = destinationRead.status === "read" ? destinationRead.bytes : null;
         const content = String(study);
         const token = createHash("sha256")
             .update(bytes)
@@ -219,10 +227,8 @@ export async function configureCommsStudy(args) {
         const lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
         const identity = await lock.stat();
         try {
-            const currentSource = await readContainedRegularFile(root, rel);
-            const currentDestination = await readContainedRegularFile(root, destination);
-            if (!currentSource?.equals(bytes) ||
-                (prior === null ? currentDestination !== null : !currentDestination?.equals(prior)))
+            const reread = (file) => readContainedRegularFile(root, file, MAX_STUDY_COPY_BYTES);
+            if (!readsAs(await reread(rel), bytes) || !readsAs(await reread(destination), prior))
                 return { ...base, message: "Files changed while saving. Preview again." };
             await writeContainedOutputFile(directory, filename, content, "utf8");
         }

package/dist/evidence/encoded-text.d.ts

@@ -1,17 +1,19 @@
+/** Each run of characters U+0080 to U+00FF read as the UTF-8 bytes they may be: é as é. */
+export declare const latin1RunsAsUtf8: (text: string) => string;
 /**
  * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
- * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`;
- * decodeEscapesUtf8 reads it as `café`. A scan checks both: either reading can split a value that
- * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`; readingsOf
+ * also gives the reading as UTF-8, `café`.
  */
 export declare function decodeEscapes(text: string): string;
-/** decodeEscapes with each run of percent escapes read as UTF-8. */
-export declare function decodeEscapesUtf8(text: string): string;
 /**
- * The UTF-8 reading of text's escapes when it differs from decodeEscapes, which it can only where
- * a percent escape holds a byte of 0x80 or more.
+ * Every reading of the text a scan matches, each once: as written, decodeEscapes, with percent
+ * escapes read as UTF-8, decodeEscapes with transfer escapes expanded, and the text as written and
+ * decoded with each run of U+0080 to U+00FF characters read as UTF-8 bytes, which undoes text that
+ * a reader already decoded one byte per character. Either percent reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
  */
-export declare function utf8ReadingOf(text: string, decoded: string): string | undefined;
+export declare function readingsOf(text: string): string[];
 /** How scanEncodedText reads text. */
 export interface EncodedTextScanOptions {
     /** Do not count an encoded binary run as opaque. */
@@ -26,9 +28,8 @@ export interface EncodedTextScan {
     readonly opaque: boolean;
 }
 /**
- * Scans text for secrets as written, after decodeEscapes (also with percent escapes read as UTF-8)
- * and transfer escapes, and inside each
- * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
+ * Scans text for secrets in each of its readingsOf, and inside each base64 (standard, URL-safe or
+ * line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
  */

package/dist/evidence/encoded-text.js

@@ -2,43 +2,44 @@
 // undoes the encodings a reader undoes for free (JSON and JS escapes, percent-encoding, HTML
 // entities) and looks inside base64 runs. verify and bundle export share decodeEscapes, so they
 // judge the same decoded text.
+import { isUtf8 } from "node:buffer";
 import { createHash } from "node:crypto";
 import { readPlainText } from "./plain-text.js";
 import { containsSensitive } from "./redaction.js";
 // HTML5 named references that stand for printable ASCII. Letters and digits have only numeric
 // references, which decodeEscapes handles.
-const ASCII_ENTITIES = {
-    amp: "&",
-    apos: "'",
-    ast: "*",
-    bsol: "\\",
-    colon: ":",
-    comma: ",",
-    commat: "@",
-    dollar: "$",
-    equals: "=",
-    excl: "!",
-    grave: "`",
-    gt: ">",
-    hat: "^",
-    lcub: "{",
-    lowbar: "_",
-    lpar: "(",
-    lsqb: "[",
-    lt: "<",
-    num: "#",
-    percnt: "%",
-    period: ".",
-    plus: "+",
-    quest: "?",
-    quot: '"',
-    rcub: "}",
-    rpar: ")",
-    rsqb: "]",
-    semi: ";",
-    sol: "/",
-    verbar: "|",
-};
+const ASCII_ENTITIES = new Map([
+    ["amp", "&"],
+    ["apos", "'"],
+    ["ast", "*"],
+    ["bsol", "\\"],
+    ["colon", ":"],
+    ["comma", ","],
+    ["commat", "@"],
+    ["dollar", "$"],
+    ["equals", "="],
+    ["excl", "!"],
+    ["grave", "`"],
+    ["gt", ">"],
+    ["hat", "^"],
+    ["lcub", "{"],
+    ["lowbar", "_"],
+    ["lpar", "("],
+    ["lsqb", "["],
+    ["lt", "<"],
+    ["num", "#"],
+    ["percnt", "%"],
+    ["period", "."],
+    ["plus", "+"],
+    ["quest", "?"],
+    ["quot", '"'],
+    ["rcub", "}"],
+    ["rpar", ")"],
+    ["rsqb", "]"],
+    ["semi", ";"],
+    ["sol", "/"],
+    ["verbar", "|"],
+]);
 function codePoint(value, original) {
     return Number.isInteger(value) && value >= 0 && value <= 0x10ffff
         ? String.fromCodePoint(value)
@@ -57,20 +58,19 @@ function sequenceLength(lead) {
     return 0;
 }
 /**
- * A run of percent escapes read as UTF-8, as a browser reads a URL. A byte that starts no valid
- * sequence stands for itself, the character with that code, as decodeEscapes reads every byte.
+ * Bytes read as UTF-8, as a browser reads a URL. A byte that starts no valid sequence stands for
+ * itself, the character with that code, as decodeEscapes reads every byte.
  */
-function decodePercentRun(run) {
-    const bytes = Buffer.from(run.replace(/%/g, ""), "hex");
+function utf8Characters(bytes) {
+    if (isUtf8(bytes))
+        return bytes.toString("utf8");
     let text = "";
     for (let at = 0; at < bytes.length;) {
         const length = sequenceLength(bytes[at]);
-        const sequence = length > 0 ? bytes.subarray(at, at + length) : undefined;
-        const decoded = sequence?.length === length ? sequence.toString("utf8") : undefined;
-        // Node writes the replacement character for an overlong form, a surrogate half or a bad
-        // continuation byte, so a sequence counts only when its character encodes back to its bytes.
-        if (decoded !== undefined && Buffer.from(decoded, "utf8").equals(sequence)) {
-            text += decoded;
+        const sequence = bytes.subarray(at, at + length);
+        // isUtf8 refuses an overlong form, a surrogate half and a bad continuation byte.
+        if (length > 0 && sequence.length === length && isUtf8(sequence)) {
+            text += sequence.toString("utf8");
             at += length;
         }
         else {
@@ -80,31 +80,47 @@ function decodePercentRun(run) {
     }
     return text;
 }
+const decodePercentRun = (run) => utf8Characters(Buffer.from(run.replace(/%/g, ""), "hex"));
+// A character from U+0080 to U+00FF, which a byte of 0x80 or more becomes when read one per
+// character.
+const HIGH_BYTE = /[\x80-\xff]/;
+/** Each run of characters U+0080 to U+00FF read as the UTF-8 bytes they may be: é as é. */
+export const latin1RunsAsUtf8 = (text) => text.replace(/[\x80-\xff]+/g, (run) => utf8Characters(Buffer.from(run, "latin1")));
 function decodePercentBytes(run) {
     return Buffer.from(run.replace(/%/g, ""), "hex").toString("latin1");
 }
 /**
  * Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. Each
- * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`;
- * decodeEscapesUtf8 reads it as `café`. A scan checks both: either reading can split a value that
- * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
+ * percent escape is one character, the byte's code, so `caf%C3%A9` reads as `café`; readingsOf
+ * also gives the reading as UTF-8, `café`.
  */
 export function decodeEscapes(text) {
     return decodeWith(text, decodePercentBytes);
 }
-/** decodeEscapes with each run of percent escapes read as UTF-8. */
-export function decodeEscapesUtf8(text) {
-    return decodeWith(text, decodePercentRun);
+/** The readings a scan matches, with the two that scanEncodedText also searches for runs. */
+function readings(text) {
+    const decoded = decodeEscapes(text);
+    // The UTF-8 reading differs only where a percent escape holds a byte of 0x80 or more, which
+    // decodeEscapes writes as a character from U+0080 to U+00FF. Testing the decoded text also
+    // catches a `%` that a `\u0025` wrote.
+    const utf8 = HIGH_BYTE.test(decoded) ? decodeWith(text, decodePercentRun) : decoded;
+    const expanded = decodeTransferEscapes(decoded);
+    const recovered = [text, decoded].filter((reading) => HIGH_BYTE.test(reading));
+    return {
+        decoded,
+        expanded,
+        all: [...new Set([text, decoded, utf8, expanded, ...recovered.map(latin1RunsAsUtf8)])],
+    };
 }
 /**
- * The UTF-8 reading of text's escapes when it differs from decodeEscapes, which it can only where
- * a percent escape holds a byte of 0x80 or more.
+ * Every reading of the text a scan matches, each once: as written, decodeEscapes, with percent
+ * escapes read as UTF-8, decodeEscapes with transfer escapes expanded, and the text as written and
+ * decoded with each run of U+0080 to U+00FF characters read as UTF-8 bytes, which undoes text that
+ * a reader already decoded one byte per character. Either percent reading can split a value that
+ * the other keeps whole, as `%E2%80%80` (U+2000, a space, in UTF-8) does.
  */
-export function utf8ReadingOf(text, decoded) {
-    if (!/%[89a-f][0-9a-f]/i.test(text))
-        return undefined;
-    const utf8 = decodeEscapesUtf8(text);
-    return utf8 === decoded ? undefined : utf8;
+export function readingsOf(text) {
+    return readings(text).all;
 }
 function decodeWith(text, percent) {
     return text
@@ -114,7 +130,10 @@ function decodeWith(text, percent) {
         .replace(/(?:%[0-9a-f]{2})+/gi, percent)
         .replace(/&#x([0-9a-f]{1,6});?/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
         .replace(/&#(\d{1,7});?/g, (match, digits) => codePoint(Number.parseInt(digits, 10), match))
-        .replace(/&([a-z]+);/gi, (match, name) => ASCII_ENTITIES[name.toLowerCase()] ?? match);
+        .replace(/&([a-z]+);/gi, namedReference);
+}
+function namedReference(match, name) {
+    return ASCII_ENTITIES.get(name.toLowerCase()) ?? match;
 }
 // Sixteen characters hold twelve bytes, enough for the start of a key. Shorter runs are mostly
 // words and identifiers.
@@ -262,8 +281,7 @@ function inspectDecoded(bytes, run, options, depth) {
     if (inner !== undefined) {
         if (depth < MAX_DEPTH)
             return scanEncodedText(inner, options, depth + 1);
-        const innerDecoded = decodeEscapes(inner);
-        return matches(inner) || (innerDecoded !== inner && matches(innerDecoded)) ? SENSITIVE : CLEAN;
+        return readingsOf(inner).some(matches) ? SENSITIVE : CLEAN;
     }
     // A key next to a few binary bytes is still a printable stretch.
     if (matches(printableStretches(bytes)))
@@ -276,22 +294,15 @@ function inspectDecoded(bytes, run, options, depth) {
     };
 }
 /**
- * Scans text for secrets as written, after decodeEscapes (also with percent escapes read as UTF-8)
- * and transfer escapes, and inside each
- * base64 (standard, URL-safe or line-wrapped) and hex run. A run that decodes to text is scanned in
+ * Scans text for secrets in each of its readingsOf, and inside each base64 (standard, URL-safe or
+ * line-wrapped) and hex run. A run that decodes to text is scanned in
  * turn. A run that decodes to an archive, or to other binary past MIN_OPAQUE_BASE64_RUN characters,
  * is opaque unless the caller allows opaque runs.
  */
 export function scanEncodedText(text, options = {}, depth = 0) {
     const matches = matcherOf(options);
-    const decoded = decodeEscapes(text);
-    const utf8 = utf8ReadingOf(text, decoded);
-    const expanded = decodeTransferEscapes(decoded);
-    // A decoding that returns the same string would match the same way, so it is not matched again.
-    if (matches(text) ||
-        (decoded !== text && matches(decoded)) ||
-        (utf8 !== undefined && matches(utf8)) ||
-        (expanded !== decoded && matches(expanded)))
+    const { decoded, expanded, all } = readings(text);
+    if (all.some(matches))
         return SENSITIVE;
     const runs = [];
     // A piece or a run decoded from a slash only adds findings; its bytes are not judged opaque.
@@ -341,7 +352,7 @@ export function scanEncodedText(text, options = {}, depth = 0) {
 // Bump when scanEncodedText, decodeEscapes or the sensitive patterns change what they return. The
 // cache lives in one process, so the version guards results across a hot reload or a test that
 // swaps the scanner.
-const ENCODED_SCAN_VERSION = 4;
+const ENCODED_SCAN_VERSION = 5;
 // Distinct files one process verifies in a burst (a run's files, a serve library's runs).
 const SCAN_CACHE_LIMIT = 256;
 const scanCache = new Map();

package/dist/evidence/redaction.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Every marker humanish writes in place of what it withholds. The known-value scrub leaves text
+ * wholly inside one of these as it is, so a writer of a new marker adds it here.
+ */
+export declare const REDACTION_MARKERS: {
+    readonly secret: "[REDACTED_SECRET]";
+    readonly localPath: "[REDACTED_LOCAL_PATH]";
+    readonly runtimePath: "[REDACTED_RUNTIME_PATH]";
+    readonly promptText: "[REDACTED_PROMPT_TEXT]";
+    readonly lobbyCode: "[REDACTED_LOBBY_CODE]";
+};
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export declare function sensitivePatterns(): readonly RegExp[];
 /** True if the text contains a credential. Local paths and a URL on an E2B host alone do not count. */

package/dist/evidence/redaction.js

@@ -126,18 +126,29 @@ const SECRET_PATTERNS = [
     SANDBOX_URL,
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
+/**
+ * Every marker humanish writes in place of what it withholds. The known-value scrub leaves text
+ * wholly inside one of these as it is, so a writer of a new marker adds it here.
+ */
+export const REDACTION_MARKERS = {
+    secret: "[REDACTED_SECRET]",
+    localPath: "[REDACTED_LOCAL_PATH]",
+    runtimePath: "[REDACTED_RUNTIME_PATH]",
+    promptText: "[REDACTED_PROMPT_TEXT]",
+    lobbyCode: "[REDACTED_LOBBY_CODE]",
+};
 const LOCAL_PATH_PATTERNS = [
-    [/\/private\/var\/folders\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/var\/folders\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/private\/tmp\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/tmp\/[^\s"'`<>)]*/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/Users\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_LOCAL_PATH]"],
-    [/\/home\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, "[REDACTED_RUNTIME_PATH]"],
+    [/\/private\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/var\/folders\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/private\/tmp\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/tmp\/[^\s"'`<>)]*/g, REDACTION_MARKERS.localPath],
+    [/\/Users\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, REDACTION_MARKERS.localPath],
+    [/\/home\/[A-Za-z0-9._-]+(?:\/[^\s"'`<>)]*)?/g, REDACTION_MARKERS.runtimePath],
     // A Windows profile path, with `\`, `\\` (JSON-escaped) or `/` between segments. A match never
     // ends in a backslash, so it cannot swallow the escape of a closing quote.
     [
         /\b[A-Za-z]:(?:\\\\|\\|\/)Users(?:\\\\|\\|\/)[^\\/\s"'`<>)]+[^\s"'`<>)]*/g,
-        "[REDACTED_LOCAL_PATH]",
+        REDACTION_MARKERS.localPath,
     ],
 ];
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
@@ -171,7 +182,15 @@ export function containsSensitive(text) {
 // suffix so redaction cannot turn a string's contents into JSON delimiters.
 // This also works when the closing quote arrives in a later stream callback.
 function redactLocalPaths(text, label) {
-    return LOCAL_PATH_PATTERNS.reduce((current, [pattern, replacement]) => current.replace(pattern, (match) => (label ?? replacement) + (match.match(/\\+$/)?.[0] ?? "")), text);
+    return LOCAL_PATH_PATTERNS.reduce((current, [pattern, replacement]) => current.replace(pattern, (match) => (label ?? replacement) + trailingBackslashes(match)), text);
+}
+// Read from the end: `/\\+$/` retries a run of backslashes from each of its characters when
+// something follows the run, which took 1.4 s on a path holding 40,000 of them.
+function trailingBackslashes(text) {
+    let start = text.length;
+    while (start > 0 && text.charCodeAt(start - 1) === 0x5c)
+        start -= 1;
+    return text.slice(start);
 }
 /**
  * What a shared copy of a run says in place of a provider sandbox id. scripts/public-surface-scan.mjs
@@ -265,7 +284,7 @@ function redactSecrets(text) {
     return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, (...args) => {
         const groups = args.at(-1);
         const keep = isRecord(groups) && typeof groups.keep === "string" ? groups.keep : "";
-        return `${keep}[REDACTED_SECRET]`;
+        return `${keep}${REDACTION_MARKERS.secret}`;
     }), text);
 }
 /** Redact secrets to [REDACTED_SECRET] and local paths to their path labels. */
@@ -274,7 +293,7 @@ export function redactText(text) {
 }
 /** Redact every sensitive match (secrets and paths) to a single [REDACTED_SECRET] label. */
 export function redactToSecretLabel(text) {
-    return redactLocalPaths(redactSecrets(text), "[REDACTED_SECRET]");
+    return redactLocalPaths(redactSecrets(text), REDACTION_MARKERS.secret);
 }
 function canonicalizePath(value) {
     const resolved = path.resolve(value);
@@ -526,7 +545,7 @@ function blurPass(src, width, height, radius, horizontal) {
  * pattern-match, such as provisioned keys and subject env values. `values` is read on each call,
  * so a value registered later is scrubbed too.
  */
-export function scrubLiterals(values, marker = "[REDACTED_SECRET]") {
+export function scrubLiterals(values, marker = REDACTION_MARKERS.secret) {
     return (text) => values.reduce((current, value) => current.split(value).join(marker), text);
 }
 /**

package/dist/evidence/secret-scrub.d.ts

@@ -1,10 +1,27 @@
 /**
  * A value as written, and percent-encoded, JSON-escaped once (also with non-ASCII characters as
- * `\u` escapes) and twice, its UTF-8 bytes read one per character, base64 at each byte offset, base64url and hex. Twice, because a JSON event can carry a command's JSON output as a string. An
- * escaped form is searched for at any length, as the value is: it holds a backslash or a `%`, so it
- * is not ordinary text.
+ * `\u` escapes) and twice, its UTF-8 bytes read one per character and the reverse, base64 padded,
+ * unpadded and at each byte offset, base64url and hex. Twice, because a JSON event can carry a
+ * command's JSON output as a string. An escaped form is searched for at any length, as the value
+ * is: it holds a backslash or a `%`, so it is not ordinary text. A base64 or hex form is searched
+ * for from MIN_ENCODED_FORM characters, so a four-byte value is found in base64 written whole and
+ * not inside a longer run, where four or five of its characters do not depend on its neighbours.
  */
 export declare function encodedForms(value: string): string[];
+/**
+ * A scrub that replaces each non-empty value as written with `[REDACTED_SECRET]`, markers
+ * included. From the start of the text, the longest value that starts at a position is replaced
+ * and the search goes on after it, so the marker it writes is never searched. One global regex of
+ * the values, longest first, does that fastest. V8 compiles it at its first use and refuses it
+ * once a value has 32,768 characters; the scrub then finds each value itself, with the same
+ * output, in time linear in the text for each value.
+ */
+export declare function scrubValuesAsWritten(values: readonly string[]): (text: string) => string;
+/**
+ * A check that the text holds one of the values' forms outside the markers in any of its
+ * readingsOf. A scrub's output must pass it.
+ */
+export declare function holdsSecretValue(values: readonly string[]): (text: string) => boolean;
 /**
  * A scrub that replaces each non-empty value and its encoded forms with `[REDACTED_SECRET]`. Every
  * occurrence of every form is found on its own, and overlapping finds are merged into one span, so
@@ -12,5 +29,11 @@ export declare function encodedForms(value: string): string[];
  * through decodeEscapes, the decoder verify uses, and returns the decoded text: a warning with
  * percent-encoding, JSON escapes or HTML references shows them decoded, with the values removed.
  * That finds a value written partly encoded, which no single encoded form matches.
+ *
+ * The result's other readingsOf only detect. If one still holds a form, the scrub returns
+ * `[REDACTED_SECRET]` in place of the whole text. That happens for a value encoded twice, which
+ * the decoded text shows encoded once; for a value the UTF-8 or transfer reading holds, such as
+ * one with one of two non-ASCII characters percent-encoded; and for a value that holds part of a
+ * marker, such as `ET]x`, which the marker that replaced it can spell again.
  */
 export declare function scrubSecretValues(values: readonly string[]): (text: string) => string;