humanish 0.104.3 → 0.106.0

package/dist/evidence/encoded-text.js

@@ -0,0 +1,243 @@
+// A pattern scan reads characters, so a file can hide a secret by encoding it. scanEncodedText
+// 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 { 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: "|",
+};
+function codePoint(value, original) {
+    return Number.isInteger(value) && value >= 0 && value <= 0x10ffff
+        ? String.fromCodePoint(value)
+        : original;
+}
+/** Undoes JSON and JS escapes, percent-encoding and HTML character references, one pass each. */
+export function decodeEscapes(text) {
+    return text
+        .replace(/\\u([0-9a-f]{4})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
+        .replace(/\\x([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
+        .replace(/\\\//g, "/")
+        .replace(/%([0-9a-f]{2})/gi, (match, hex) => codePoint(Number.parseInt(hex, 16), match))
+        .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);
+}
+// Sixteen characters hold twelve bytes, enough for the start of a key. Shorter runs are mostly
+// words and identifiers.
+const BASE64_RUN = /[A-Za-z0-9+/]{16,}={0,2}/g;
+// The URL-safe alphabet swaps `+/` for `-_`. Only runs that use `-` or `_` need this pass.
+const BASE64URL_RUN = /[A-Za-z0-9_-]{16,}={0,2}/g;
+// MIME and PEM wrap base64 at 64 or 76 characters a line. The lookbehind starts a match only at the
+// start of a run, and each lookahead-backreference pair takes a line whole, so a long unwrapped run
+// cannot backtrack.
+const WRAPPED_BASE64 = /(?<![A-Za-z0-9+/])(?=([A-Za-z0-9+/]{16,}))\1(?:[ \t]*\r?\n[ \t]*(?=([A-Za-z0-9+/]{4,}))\2)+={0,2}/g;
+// Hex-encoded text, at least sixteen bytes of it.
+const HEX_RUN = /(?:[0-9a-f]{2}){16,}/gi;
+// A base64 run that decodes to bytes that are neither text nor an archive is unreadable only past
+// this length. Across 173 real run folders surveyed on 2026-10-01, the longest such run outside
+// observer/index.html was a 69-character URL path in a terminal log; base64 of a 94-byte payload,
+// such as a UTF-16 key line, is 128 characters.
+const MIN_OPAQUE_BASE64_RUN = 128;
+// Filler such as one letter repeated decodes to repeated bytes. Base64 of compressed, encrypted or
+// image bytes uses most of the 64 characters within 128 of them.
+const MIN_OPAQUE_DISTINCT_CHARACTERS = 16;
+// gzip, zip, 7z, bzip2, xz and zstd.
+const ARCHIVE_MAGIC = [
+    [0x1f, 0x8b],
+    [0x50, 0x4b, 0x03, 0x04],
+    [0x37, 0x7a, 0xbc, 0xaf, 0x27, 0x1c],
+    [0x42, 0x5a, 0x68],
+    [0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00],
+    [0x28, 0xb5, 0x2f, 0xfd],
+];
+const CONTROL_CHARACTERS = /[\x00-\x08\x0b\x0c\x0e-\x1f]/;
+// Base64 inside base64 is read this many levels deep.
+const MAX_DEPTH = 2;
+function startsWithArchive(bytes) {
+    return ARCHIVE_MAGIC.some((magic) => magic.every((byte, index) => bytes[index] === byte));
+}
+/** UTF-16 text, either byte order, that is mostly ASCII as a key would be; random bytes rarely qualify. */
+function utf16Text(bytes) {
+    if (bytes.length < 4 || bytes.length % 2 !== 0)
+        return undefined;
+    // Every ASCII character in UTF-16, in either byte order, has a 0x00 byte. Without one the decoded
+    // text has no ASCII, so the 90% rule below would reject it, and none of the sensitive patterns
+    // could match it: each needs ASCII characters (sensitivePatterns, pinned in
+    // tests/evidence/encoded-text.test.ts). Skipping the decode changes no result.
+    if (!bytes.includes(0))
+        return undefined;
+    for (const encoding of ["utf-16le", "utf-16be"]) {
+        let text;
+        try {
+            text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+        }
+        catch {
+            continue;
+        }
+        if (CONTROL_CHARACTERS.test(text))
+            continue;
+        let ascii = 0;
+        for (const character of text)
+            if (character.charCodeAt(0) < 0x80)
+                ascii += 1;
+        if (ascii >= text.length * 0.9)
+            return text;
+    }
+    return undefined;
+}
+/** The printable ASCII stretches of binary bytes, one per line, as `strings` would show them. */
+function printableStretches(bytes) {
+    return Buffer.from(bytes)
+        .toString("latin1")
+        .replace(/[^\x20-\x7e]+/g, "\n");
+}
+/**
+ * Escapes a transfer encoding adds: JSON whitespace escapes, and quoted-printable soft line breaks
+ * and `=XX` bytes. Bundle export does not apply these, so they stay out of decodeEscapes.
+ */
+function decodeTransferEscapes(text) {
+    return text
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/=\r?\n/g, "")
+        .replace(/=([0-9A-F]{2})/g, (match, hex) => codePoint(Number.parseInt(hex, 16), match));
+}
+const CLEAN = Object.freeze({ sensitive: false, opaque: false });
+const SENSITIVE = Object.freeze({ sensitive: true, opaque: false });
+function inspectDecoded(bytes, run, options, depth) {
+    if (startsWithArchive(bytes))
+        return { sensitive: false, opaque: options.allowOpaqueBase64 !== true };
+    const plain = readPlainText(bytes);
+    const inner = plain.ok ? plain.text : utf16Text(bytes);
+    if (inner !== undefined) {
+        if (depth < MAX_DEPTH)
+            return scanEncodedText(inner, options, depth + 1);
+        const innerDecoded = decodeEscapes(inner);
+        return containsSensitive(inner) || (innerDecoded !== inner && containsSensitive(innerDecoded))
+            ? SENSITIVE
+            : CLEAN;
+    }
+    // A key next to a few binary bytes is still a printable stretch.
+    if (containsSensitive(printableStretches(bytes)))
+        return SENSITIVE;
+    return {
+        sensitive: false,
+        opaque: run.length >= MIN_OPAQUE_BASE64_RUN &&
+            new Set(run).size >= MIN_OPAQUE_DISTINCT_CHARACTERS &&
+            options.allowOpaqueBase64 !== true,
+    };
+}
+/**
+ * Scans text for secrets as written, after decodeEscapes 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
+ * 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 decoded = decodeEscapes(text);
+    const expanded = decodeTransferEscapes(decoded);
+    // A decoding that returns the same string would match the same way, so it is not matched again.
+    if (containsSensitive(text) ||
+        (decoded !== text && containsSensitive(decoded)) ||
+        (expanded !== decoded && containsSensitive(expanded)))
+        return SENSITIVE;
+    const runs = [];
+    for (const [match] of expanded.matchAll(BASE64_RUN)) {
+        // Hex digests and ids decode to noise; the hex pass below reads hex as hex.
+        if (/^[0-9a-f]+$/i.test(match.replace(/=+$/, "")))
+            continue;
+        runs.push({ run: match, bytes: Buffer.from(match, "base64") });
+    }
+    for (const [match] of expanded.matchAll(BASE64URL_RUN)) {
+        if (/[-_]/.test(match))
+            runs.push({ run: match, bytes: Buffer.from(match, "base64url") });
+    }
+    for (const [match] of expanded.matchAll(WRAPPED_BASE64)) {
+        const run = match.replace(/\s+/g, "");
+        runs.push({ run, bytes: Buffer.from(run, "base64") });
+    }
+    let opaque = false;
+    for (const { run, bytes } of runs) {
+        const result = inspectDecoded(bytes, run, options, depth);
+        if (result.sensitive)
+            return result;
+        opaque ||= result.opaque;
+    }
+    for (const [match] of expanded.matchAll(HEX_RUN)) {
+        const plain = readPlainText(Buffer.from(match, "hex"));
+        if (plain.ok && depth < MAX_DEPTH && scanEncodedText(plain.text, options, depth + 1).sensitive)
+            return SENSITIVE;
+    }
+    return { sensitive: false, opaque };
+}
+// 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 = 1;
+// 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();
+/**
+ * scanEncodedText, cached in this process. The key is the sha256 of the scanned string's UTF-16
+ * code units, the options and ENCODED_SCAN_VERSION. Encoding as UTF-16LE keeps every code unit,
+ * lone surrogates included, so distinct strings get distinct keys and a hit is the result a fresh
+ * scan of the same string would give. Repeated verifies of an unchanged file, as serve admission
+ * and the Observer render do, skip the scan.
+ */
+export function scanEncodedTextCached(text, options = {}) {
+    const key = [
+        ENCODED_SCAN_VERSION,
+        options.allowOpaqueBase64 === true ? "opaque-allowed" : "opaque-unscanned",
+        createHash("sha256").update(Buffer.from(text, "utf16le")).digest("hex"),
+    ].join(":");
+    const cached = scanCache.get(key);
+    if (cached !== undefined) {
+        // Refresh its place so the least recently used entry is evicted first.
+        scanCache.delete(key);
+        scanCache.set(key, cached);
+        return cached;
+    }
+    // Every caller gets the cached object, so it is frozen.
+    const result = Object.freeze({ ...scanEncodedText(text, options) });
+    scanCache.set(key, result);
+    if (scanCache.size > SCAN_CACHE_LIMIT) {
+        const oldest = scanCache.keys().next().value;
+        if (oldest !== undefined)
+            scanCache.delete(oldest);
+    }
+    return result;
+}

package/dist/evidence/frame-signature.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
+ * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
+ * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.
+ *
+ * Normalization stretches each frame's own min..max across the full range before quantizing, so a
+ * mostly-white UI uses all the levels. Without it, a light-themed app pinned 93% of cells to one
+ * level and visibly different frames hashed the same. The 32x32 grid makes a cell about 45x30 px on
+ * a 1440x950 desktop, so widget-sized changes survive the averaging.
+ *
+ * It is still a coarse whole-frame hash and only one input to the no-progress backstop. The
+ * corroboration rule in src/actors/computer-use/loop/backstop.ts keeps a blind frame from ending a
+ * run on its own.
+ */
+export declare function perceptualSignature(pngBytes: Buffer | Uint8Array): string;

package/dist/evidence/frame-signature.js

@@ -0,0 +1,111 @@
+import { PNG } from "pngjs";
+const SIGNATURE_GRID = 32;
+const SIGNATURE_LEVELS = 16;
+const SIGNATURE_FALLBACK = "unreadable";
+// The brightness anchor is one hex digit over 8-bit channel means.
+const ANCHOR_LEVELS = 16;
+/**
+ * A perceptual hash of a PNG frame for no-progress detection. Decodes the PNG, area-averages it to
+ * a SIGNATURE_GRID x SIGNATURE_GRID grayscale grid, CONTRAST-NORMALIZES that grid, quantizes each
+ * cell to SIGNATURE_LEVELS, and packs the cells into a hex string. Deterministic (no Date, no
+ * random). Returns SIGNATURE_FALLBACK on any decode failure so two unreadable frames compare equal.
+ * The hash cannot be reversed to the image, so exposing it in a trace is public-safe.
+ *
+ * Normalization stretches each frame's own min..max across the full range before quantizing, so a
+ * mostly-white UI uses all the levels. Without it, a light-themed app pinned 93% of cells to one
+ * level and visibly different frames hashed the same. The 32x32 grid makes a cell about 45x30 px on
+ * a 1440x950 desktop, so widget-sized changes survive the averaging.
+ *
+ * It is still a coarse whole-frame hash and only one input to the no-progress backstop. The
+ * corroboration rule in src/actors/computer-use/loop/backstop.ts keeps a blind frame from ending a
+ * run on its own.
+ */
+export function perceptualSignature(pngBytes) {
+    let cells;
+    try {
+        const source = Buffer.isBuffer(pngBytes) ? pngBytes : Buffer.from(pngBytes);
+        if (source.length === 0)
+            return SIGNATURE_FALLBACK;
+        const decoded = PNG.sync.read(source);
+        const srcW = decoded.width;
+        const srcH = decoded.height;
+        if (!srcW || !srcH)
+            return SIGNATURE_FALLBACK;
+        cells = quantizedGrid(decoded.data, srcW, srcH);
+        return `${brightnessAnchor(decoded.data, srcW, srcH)}${packCells(cells)}`;
+    }
+    catch {
+        return SIGNATURE_FALLBACK;
+    }
+}
+/** Area-average an RGBA buffer to a grid of grayscale cells, contrast-normalized then quantized. */
+function quantizedGrid(data, srcW, srcH) {
+    const grays = [];
+    const xRatio = srcW / SIGNATURE_GRID;
+    const yRatio = srcH / SIGNATURE_GRID;
+    for (let gy = 0; gy < SIGNATURE_GRID; gy += 1) {
+        const sy0 = Math.floor(gy * yRatio);
+        const sy1 = Math.min(srcH, Math.max(sy0 + 1, Math.floor((gy + 1) * yRatio)));
+        for (let gx = 0; gx < SIGNATURE_GRID; gx += 1) {
+            const sx0 = Math.floor(gx * xRatio);
+            const sx1 = Math.min(srcW, Math.max(sx0 + 1, Math.floor((gx + 1) * xRatio)));
+            let sum = 0;
+            let n = 0;
+            for (let sy = sy0; sy < sy1; sy += 1) {
+                for (let sx = sx0; sx < sx1; sx += 1) {
+                    const si = (sy * srcW + sx) * 4;
+                    const r = data[si] ?? 0;
+                    const g = data[si + 1] ?? 0;
+                    const b = data[si + 2] ?? 0;
+                    sum += Math.round((r + g + b) / 3);
+                    n += 1;
+                }
+            }
+            grays.push(n ? Math.round(sum / n) : 0);
+        }
+    }
+    // Stretch this frame's own range across the full scale before quantizing. Without this a light UI
+    // occupies a sliver at the top of 0..255 and quantizes to a near-constant (#383).
+    //
+    // The endpoints are TRIMMED rather than the raw min/max: a handful of extreme cells must not be
+    // able to rescale the whole frame, or a blinking text cursor would rewrite every cell and read as
+    // progress forever. Trimming K cells from each end clamps that away while still preserving real
+    // structure, which occupies far more cells than K (a row of sidebar text covers dozens).
+    const sorted = [...grays].sort((a, b) => a - b);
+    const trim = Math.max(2, Math.floor(sorted.length / 256));
+    const lo = sorted[Math.min(trim, sorted.length - 1)] ?? 0;
+    const hi = sorted[Math.max(0, sorted.length - 1 - trim)] ?? 255;
+    const span = hi - lo;
+    const top = SIGNATURE_LEVELS - 1;
+    return grays.map((gray) => span <= 0 ? 0 : Math.min(top, Math.max(0, Math.round(((gray - lo) / span) * top))));
+}
+/**
+ * The frame's overall brightness, coarsely quantized. Normalization deliberately discards absolute
+ * level, so this is prefixed back on for the two cases where absolute level IS the change: a uniform
+ * frame (an all-white blank vs an all-black screen normalize identically), and a whole-page dim such
+ * as a modal overlay, which preserves relative structure while changing the whole frame. Quantized
+ * coarsely so ordinary antialiasing noise cannot move it.
+ */
+function brightnessAnchor(data, srcW, srcH) {
+    let sum = 0;
+    let n = 0;
+    const stride = Math.max(1, Math.floor((srcW * srcH) / 4096));
+    for (let p = 0; p < srcW * srcH; p += stride) {
+        const si = p * 4;
+        sum += ((data[si] ?? 0) + (data[si + 1] ?? 0) + (data[si + 2] ?? 0)) / 3;
+        n += 1;
+    }
+    const mean = n ? sum / n : 0;
+    return Math.min(ANCHOR_LEVELS - 1, Math.floor((mean * ANCHOR_LEVELS) / 256)).toString(16);
+}
+/** Pack 4-bit cells (two per byte) into a compact hex string. */
+function packCells(cells) {
+    const bytes = Buffer.alloc(Math.ceil(cells.length / 2));
+    for (let i = 0; i < cells.length; i += 1) {
+        const byteIndex = i >> 1;
+        const shift = (i & 1) * 4;
+        const value = (cells[i] ?? 0) & 0xf;
+        bytes[byteIndex] = (bytes[byteIndex] ?? 0) | (value << shift);
+    }
+    return bytes.toString("hex");
+}

package/dist/evidence/image.d.ts

@@ -0,0 +1,24 @@
+export declare const SCREENSHOT_MAX_WIDTH_CAP = 128;
+/**
+ * Drops every chunk outside SCREENSHOT_PNG_CHUNKS, so a frame from any source is written with
+ * image data only. Pixels and the kept chunks are copied unchanged. Bytes over the size cap, or
+ * that are not a well-formed chunk sequence, are returned as they are, for the evidence check to
+ * reject without walking them.
+ */
+export declare function stripPngMetadataChunks(bytes: Buffer): Buffer;
+/**
+ * Why a PNG must not reach the decoder, read from its header. pngjs allocates from the IHDR it
+ * finds and inflates interlaced data with no bound, so a PNG whose first chunk is not a 13-byte
+ * IHDR (its dimensions unchecked) or an interlaced one can cost gigabytes. Null when decoding is
+ * bounded by the byte and pixel caps. Every retained frame is non-interlaced with a 13-byte IHDR.
+ */
+export declare function pngDecodeRefusal(bytes: Buffer): string | null;
+/**
+ * True when the bytes have exactly the shape redactScreenshot writes: IHDR, IDAT and IEND only,
+ * an empty IEND ending the file, and a width within SCREENSHOT_MAX_WIDTH_CAP. A frame claiming
+ * `blurred` counts as redacted only in this shape: the claim alone cannot show that the pixels
+ * were downscaled, and any other chunk is a place to carry bytes no one reviews.
+ */
+export declare function isRedactedFrameShape(bytes: Buffer): boolean;
+export declare function screenshotEvidenceError(relativePath: string, bytes: Buffer): string | null;
+export declare function assertScreenshotEvidence(relativePath: string, bytes: Buffer): void;

package/dist/evidence/image.js

@@ -0,0 +1,170 @@
+import { PNG } from "pngjs";
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const PNG_IHDR_LENGTH = 13;
+// The pixel cap pngDecodeRefusal applies before any decode, for verify and the redactor alike.
+const SCREENSHOT_MAX_SOURCE_PIXELS = 50_000_000;
+// The widest thumbnail the redactor emits. A redacted frame is at most this wide, which is what
+// makes it too coarse to read text off; see redactScreenshot.
+export const SCREENSHOT_MAX_WIDTH_CAP = 128;
+function hasPngSignature(bytes) {
+    return (bytes.length >= PNG_SIGNATURE.length &&
+        bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE));
+}
+/**
+ * Read dimensions from a structurally positioned PNG IHDR without decoding.
+ * CRC and complete-file validity remain the decoder's responsibility.
+ */
+function readPngDeclaredDimensions(bytes) {
+    if (!hasPngSignature(bytes) ||
+        bytes.length < 24 ||
+        bytes.readUInt32BE(8) !== PNG_IHDR_LENGTH ||
+        bytes.subarray(12, 16).toString("ascii") !== "IHDR") {
+        return null;
+    }
+    return {
+        width: bytes.readUInt32BE(16),
+        height: bytes.readUInt32BE(20),
+    };
+}
+// A noisy 4K RGBA frame is roughly 32 MiB before PNG compression, so this
+// admits realistic screenshot payloads while bounding decoder input.
+const SCREENSHOT_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * The PNG chunks screenshot evidence may carry: image data and fixed-format display hints.
+ * Text (tEXt, zTXt, iTXt), ICC profiles, Exif, timestamps and private chunks can hold bytes that
+ * neither the text scan nor a look at the pixels would see, so a screenshot must not carry them.
+ * Frames from E2B desktops carry IHDR, IDAT, IEND and sBIT; blurred frames are re-encoded.
+ */
+const SCREENSHOT_PNG_CHUNKS = new Set([
+    "IHDR",
+    "PLTE",
+    "IDAT",
+    "IEND",
+    "tRNS",
+    "cHRM",
+    "gAMA",
+    "sBIT",
+    "sRGB",
+    "pHYs",
+    "bKGD",
+]);
+/** The chunks up to IEND, or null when a chunk runs past the end of the bytes. */
+function readPngChunks(bytes) {
+    const chunks = [];
+    let offset = PNG_SIGNATURE.length;
+    while (offset + 8 <= bytes.length) {
+        const end = offset + 12 + bytes.readUInt32BE(offset);
+        if (end > bytes.length)
+            return null;
+        const type = bytes.toString("latin1", offset + 4, offset + 8);
+        chunks.push({ type, start: offset, end });
+        offset = end;
+        if (type === "IEND")
+            break;
+    }
+    return chunks;
+}
+/**
+ * Drops every chunk outside SCREENSHOT_PNG_CHUNKS, so a frame from any source is written with
+ * image data only. Pixels and the kept chunks are copied unchanged. Bytes over the size cap, or
+ * that are not a well-formed chunk sequence, are returned as they are, for the evidence check to
+ * reject without walking them.
+ */
+export function stripPngMetadataChunks(bytes) {
+    if (!hasPngSignature(bytes) || bytes.length > SCREENSHOT_MAX_BYTES)
+        return bytes;
+    const chunks = readPngChunks(bytes);
+    if (chunks === null)
+        return bytes;
+    const kept = chunks.filter((chunk) => SCREENSHOT_PNG_CHUNKS.has(chunk.type));
+    if (kept.length === chunks.length)
+        return bytes;
+    return Buffer.concat([
+        bytes.subarray(0, PNG_SIGNATURE.length),
+        ...kept.map((chunk) => bytes.subarray(chunk.start, chunk.end)),
+    ]);
+}
+/**
+ * Why a PNG must not reach the decoder, read from its header. pngjs allocates from the IHDR it
+ * finds and inflates interlaced data with no bound, so a PNG whose first chunk is not a 13-byte
+ * IHDR (its dimensions unchecked) or an interlaced one can cost gigabytes. Null when decoding is
+ * bounded by the byte and pixel caps. Every retained frame is non-interlaced with a 13-byte IHDR.
+ */
+export function pngDecodeRefusal(bytes) {
+    if (!hasPngSignature(bytes))
+        return "expected PNG signature";
+    if (bytes.length > SCREENSHOT_MAX_BYTES) {
+        return `PNG byte size exceeds ${SCREENSHOT_MAX_BYTES} byte limit`;
+    }
+    const dimensions = readPngDeclaredDimensions(bytes);
+    if (dimensions === null)
+        return "PNG must start with a 13-byte IHDR chunk";
+    const dimensionsError = pngDimensionsError(dimensions.width, dimensions.height);
+    if (dimensionsError)
+        return dimensionsError;
+    // IHDR data: width, height, bit depth, color type, compression, filter, interlace (byte 28).
+    if (bytes.length > 28 && bytes[28] !== 0)
+        return "interlaced PNG evidence is not supported";
+    return null;
+}
+/**
+ * True when the bytes have exactly the shape redactScreenshot writes: IHDR, IDAT and IEND only,
+ * an empty IEND ending the file, and a width within SCREENSHOT_MAX_WIDTH_CAP. A frame claiming
+ * `blurred` counts as redacted only in this shape: the claim alone cannot show that the pixels
+ * were downscaled, and any other chunk is a place to carry bytes no one reviews.
+ */
+export function isRedactedFrameShape(bytes) {
+    if (pngDecodeRefusal(bytes) !== null)
+        return false;
+    const chunks = readPngChunks(bytes);
+    if (chunks === null || chunks.length < 3)
+        return false;
+    const last = chunks[chunks.length - 1];
+    return (chunks[0].type === "IHDR" &&
+        chunks.slice(1, -1).every((chunk) => chunk.type === "IDAT") &&
+        last.type === "IEND" &&
+        last.end - last.start === 12 &&
+        last.end === bytes.length &&
+        bytes.readUInt32BE(16) <= SCREENSHOT_MAX_WIDTH_CAP);
+}
+export function screenshotEvidenceError(relativePath, bytes) {
+    const extension = relativePath.toLowerCase().split(".").pop() ?? "";
+    if (extension !== "png") {
+        return `unsupported screenshot extension .${extension || "unknown"}; only decoded PNG evidence is supported`;
+    }
+    const refusal = pngDecodeRefusal(bytes);
+    if (refusal)
+        return refusal;
+    const chunks = readPngChunks(bytes);
+    const foreign = chunks?.find((chunk) => !SCREENSHOT_PNG_CHUNKS.has(chunk.type));
+    if (foreign !== undefined) {
+        const name = /^[A-Za-z]{4}$/.test(foreign.type) ? foreign.type : "malformed";
+        return `PNG carries a ${name} chunk; screenshot evidence may hold image data only`;
+    }
+    // pngjs reads IEND at any length, so its payload would go unchecked.
+    if (chunks?.some((chunk) => chunk.type === "IEND" && chunk.end - chunk.start !== 12)) {
+        return "PNG IEND chunk must be empty";
+    }
+    try {
+        const decoded = PNG.sync.read(bytes, { checkCRC: true });
+        return pngDimensionsError(decoded.width, decoded.height);
+    }
+    catch {
+        return "could not decode PNG evidence";
+    }
+}
+export function assertScreenshotEvidence(relativePath, bytes) {
+    const error = screenshotEvidenceError(relativePath, bytes);
+    if (error) {
+        throw new Error(`Invalid screenshot evidence ${relativePath}: ${error}`);
+    }
+}
+function pngDimensionsError(width, height) {
+    if (width === 0 || height === 0) {
+        return "PNG dimensions must be greater than zero";
+    }
+    if (width * height > SCREENSHOT_MAX_SOURCE_PIXELS) {
+        return `PNG pixel count exceeds ${SCREENSHOT_MAX_SOURCE_PIXELS} pixel limit`;
+    }
+    return null;
+}

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

@@ -0,0 +1,8 @@
+export type PlainText = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: "invalid-utf8" | "control-bytes";
+};
+export declare function readPlainText(bytes: Uint8Array): PlainText;

package/dist/evidence/plain-text.js

@@ -0,0 +1,16 @@
+// The rule for a run file humanish treats as text: strict UTF-8, with no control bytes other than
+// tab, line feed and carriage return. verify scans only such files for secrets, and bundle export
+// copies only such files as text, so neither calls a file clean that it could not read.
+const CONTROL_BYTES = /[\x00-\x08\x0b\x0c\x0e-\x1f]/;
+export function readPlainText(bytes) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return { ok: false, reason: "invalid-utf8" };
+    }
+    if (CONTROL_BYTES.test(text))
+        return { ok: false, reason: "control-bytes" };
+    return { ok: true, text };
+}