evershield 0.1.0 → 0.3.0

package/dist/rules/types.d.ts

@@ -5,6 +5,12 @@ export interface RuleContext {
     adapter: Adapter;
     /** Every shipped file's relative path, for cross-file checks such as source map references. */
     shippedPaths: ReadonlySet<string>;
+    /**
+     * Called with the unredacted value behind a finding, for in-process
+     * cross-checks such as `evershield recon --rea`. The value must never be
+     * stored on the finding or written anywhere.
+     */
+    onMatch?: (finding: Finding, raw: string) => void;
 }
 /**
  * A rule inspects one file and returns findings with evidence. The doc

package/dist/scan/archive.d.ts

@@ -0,0 +1,22 @@
+import type { ScannedFile } from "./files.ts";
+export type ArchiveKind = "android" | "ios" | "electron";
+export declare function archiveKind(file: string, head: Buffer): ArchiveKind | null;
+/** Printable runs of at least `min` characters, ASCII/UTF-8 and UTF-16LE (Android string pools). */
+export declare function extractStrings(buffer: Buffer, min?: number): string[];
+/**
+ * Hermes keeps every string literal and identifier in one storage blob with
+ * no separators, so a plain strings pass glues neighbours together and a key
+ * loses its word boundaries. Read the string table instead. The header is
+ * 128 bytes; the counts sit at fixed offsets; the sections that follow are
+ * 4-byte aligned. Function headers are 12 bytes in current versions (99,
+ * Expo SDK 58) and 16 in older ones, so both layouts are tried and the one
+ * whose every entry fits inside the storage wins. Returns null when neither
+ * does, and the caller falls back to a plain strings pass.
+ */
+export declare function hermesStrings(buffer: Buffer): string[] | null;
+/** Turn one archive entry, or a loose file from an extracted app, into what rules read. */
+export declare function toScanned(name: string, data: Buffer, location: string): ScannedFile | null;
+export declare function collectArchive(file: string): Promise<{
+    kind: ArchiveKind;
+    files: ScannedFile[];
+}>;

package/dist/scan/archive.js

@@ -0,0 +1,247 @@
+/**
+ * Packaged apps as artifacts: Android (.apk, .aab), iOS (.ipa) and Electron
+ * (.asar). Everything inside ships to the user's device, so everything a
+ * rule can read is scanned. No dependencies: zip is parsed here and inflated
+ * with node:zlib; ASAR is a JSON header followed by file bytes.
+ *
+ * Text entries are decoded as UTF-8. Binary entries that carry the strings an
+ * attacker would read (Hermes bytecode, DEX, compiled Android XML and
+ * resources, binary plists, Mach-O executables) are reduced to their
+ * printable strings, one per line, so the same rules apply; a finding's
+ * line is then the string's index, and its path ends in " (strings)".
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+const MAX_ARCHIVE_BYTES = 1024 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 100 * 1024 * 1024;
+const TEXT_ENTRY = /\.(?:m?js|cjs|jsx|ts|tsx|json|html?|css|xml|plist|txt|svg|map|bundle|jsbundle|webmanifest|properties|strings)$/i;
+/** Binary formats whose string tables hold what developers embed: keys, URLs, config. */
+const STRINGS_ENTRY = /(?:\.(?:dex|hbc|arsc|bundle|jsbundle|plist)$|(?:^|\/)AndroidManifest\.xml$)/i;
+const SKIP_ENTRY = /\.(?:png|jpe?g|gif|webp|ico|ttf|otf|woff2?|mp3|mp4|ogg|wav|so|dylib|car|nib|storyboardc|RSA|DSA|EC|SF|MF)$|(?:^|\/)(?:META-INF\/|_CodeSignature\/)/i;
+/** Hermes bytecode magic, little-endian 0x1F1903C103BC1FC6. */
+const HERMES_MAGIC = Buffer.from([0xc6, 0x1f, 0xbc, 0x03, 0xc1, 0x03, 0x19, 0x1f]);
+export function archiveKind(file, head) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === ".asar")
+        return "electron";
+    if (head.length < 4 || head.readUInt32LE(0) !== 0x04034b50)
+        return null;
+    if (ext === ".ipa")
+        return "ios";
+    if (ext === ".apk" || ext === ".aab" || ext === ".xapk")
+        return "android";
+    return null;
+}
+function zipEntries(buffer) {
+    // End of central directory: last 22..65557 bytes.
+    let eocd = -1;
+    for (let i = buffer.length - 22; i >= Math.max(0, buffer.length - 65557); i -= 1) {
+        if (buffer.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new Error("not a zip archive (no end of central directory)");
+    const count = buffer.readUInt16LE(eocd + 10);
+    let offset = buffer.readUInt32LE(eocd + 16);
+    const entries = [];
+    for (let i = 0; i < count; i += 1) {
+        if (buffer.readUInt32LE(offset) !== 0x02014b50)
+            throw new Error("corrupt zip central directory");
+        const method = buffer.readUInt16LE(offset + 10);
+        const compressed = buffer.readUInt32LE(offset + 20);
+        const size = buffer.readUInt32LE(offset + 24);
+        const nameLength = buffer.readUInt16LE(offset + 28);
+        const extraLength = buffer.readUInt16LE(offset + 30);
+        const commentLength = buffer.readUInt16LE(offset + 32);
+        const local = buffer.readUInt32LE(offset + 42);
+        const name = buffer.toString("utf8", offset + 46, offset + 46 + nameLength);
+        offset += 46 + nameLength + extraLength + commentLength;
+        if (name.endsWith("/") || size > MAX_ENTRY_BYTES || compressed === 0xffffffff)
+            continue;
+        entries.push({
+            name,
+            read() {
+                const start = local + 30 + buffer.readUInt16LE(local + 26) + buffer.readUInt16LE(local + 28);
+                const data = buffer.subarray(start, start + compressed);
+                if (method === 0)
+                    return data;
+                if (method === 8)
+                    return inflateRawSync(data, { maxOutputLength: MAX_ENTRY_BYTES });
+                throw new Error(`unsupported zip compression method ${method} for ${name}`);
+            },
+        });
+    }
+    return entries;
+}
+function asarEntries(buffer) {
+    // Pickle: [u32 4][u32 headerPickleSize] then [u32 payload][u32 jsonLength][json…].
+    const headerSize = buffer.readUInt32LE(4);
+    const jsonLength = buffer.readUInt32LE(12);
+    const header = JSON.parse(buffer.toString("utf8", 16, 16 + jsonLength));
+    const base = 8 + headerSize;
+    const entries = [];
+    const walk = (node, prefix) => {
+        for (const [name, child] of Object.entries(node.files ?? {})) {
+            const full = prefix === "" ? name : `${prefix}/${name}`;
+            if (child.files !== undefined)
+                walk(child, full);
+            else if (child.offset !== undefined && child.size !== undefined && child.unpacked !== true && child.size <= MAX_ENTRY_BYTES) {
+                const start = base + Number(child.offset);
+                const size = child.size;
+                entries.push({ name: full, read: () => buffer.subarray(start, start + size) });
+            }
+        }
+    };
+    walk(header, "");
+    return entries;
+}
+/** Printable runs of at least `min` characters, ASCII/UTF-8 and UTF-16LE (Android string pools). */
+export function extractStrings(buffer, min = 6) {
+    const out = [];
+    const seen = new Set();
+    const add = (value) => {
+        if (value.length >= min && !seen.has(value)) {
+            seen.add(value);
+            out.push(value);
+        }
+    };
+    let start = -1;
+    for (let i = 0; i <= buffer.length; i += 1) {
+        const byte = i < buffer.length ? buffer[i] : 0;
+        const printable = (byte >= 0x20 && byte < 0x7f) || byte === 0x09;
+        if (printable && start < 0)
+            start = i;
+        if (!printable && start >= 0) {
+            add(buffer.toString("latin1", start, i));
+            start = -1;
+        }
+    }
+    // UTF-16LE: printable ASCII byte followed by 0x00, at either byte alignment.
+    for (const alignment of [0, 1]) {
+        let run = "";
+        for (let i = alignment; i + 1 < buffer.length; i += 2) {
+            const lo = buffer[i];
+            if (buffer[i + 1] === 0 && lo >= 0x20 && lo < 0x7f)
+                run += String.fromCharCode(lo);
+            else {
+                add(run);
+                run = "";
+            }
+        }
+        add(run);
+    }
+    return out;
+}
+/**
+ * Hermes keeps every string literal and identifier in one storage blob with
+ * no separators, so a plain strings pass glues neighbours together and a key
+ * loses its word boundaries. Read the string table instead. The header is
+ * 128 bytes; the counts sit at fixed offsets; the sections that follow are
+ * 4-byte aligned. Function headers are 12 bytes in current versions (99,
+ * Expo SDK 58) and 16 in older ones, so both layouts are tried and the one
+ * whose every entry fits inside the storage wins. Returns null when neither
+ * does, and the caller falls back to a plain strings pass.
+ */
+export function hermesStrings(buffer) {
+    if (buffer.length < 128)
+        return null;
+    const u32 = (offset) => buffer.readUInt32LE(offset);
+    const align = (value) => Math.ceil(value / 4) * 4;
+    const functionCount = u32(40);
+    const stringKindCount = u32(44);
+    const identifierCount = u32(48);
+    const stringCount = u32(52);
+    const overflowCount = u32(56);
+    const storageSize = u32(60);
+    for (const functionHeaderSize of [12, 16]) {
+        let offset = 128;
+        offset = align(offset + functionCount * functionHeaderSize);
+        offset = align(offset + stringKindCount * 4);
+        offset = align(offset + identifierCount * 4);
+        const small = offset;
+        offset = align(offset + stringCount * 4);
+        const overflow = offset;
+        offset = align(offset + overflowCount * 8);
+        const storage = offset;
+        if (storage + storageSize > buffer.length)
+            continue;
+        const strings = [];
+        let valid = true;
+        for (let i = 0; i < stringCount && valid; i += 1) {
+            const entry = u32(small + i * 4);
+            const utf16 = (entry & 1) === 1;
+            let start = (entry >>> 1) & 0x7fffff;
+            let length = entry >>> 24;
+            if (length === 255) {
+                if (start >= overflowCount) {
+                    valid = false;
+                    break;
+                }
+                const at = overflow + start * 8;
+                start = u32(at);
+                length = u32(at + 4);
+            }
+            const bytes = utf16 ? length * 2 : length;
+            if (start + bytes > storageSize)
+                valid = false;
+            else if (length > 0)
+                strings.push(buffer.toString(utf16 ? "utf16le" : "latin1", storage + start, storage + start + bytes));
+        }
+        if (valid)
+            return strings;
+    }
+    return null;
+}
+function looksBinary(buffer) {
+    const end = Math.min(buffer.length, 8192);
+    for (let i = 0; i < end; i += 1)
+        if (buffer[i] === 0)
+            return true;
+    return false;
+}
+/** Turn one archive entry, or a loose file from an extracted app, into what rules read. */
+export function toScanned(name, data, location) {
+    if (data.length === 0 || SKIP_ENTRY.test(name))
+        return null;
+    const isHermes = data.length >= 8 && data.subarray(0, 8).equals(HERMES_MAGIC);
+    if (!isHermes && TEXT_ENTRY.test(name) && !looksBinary(data)) {
+        return { absolutePath: location, relativePath: name, text: data.toString("utf8") };
+    }
+    if (isHermes || STRINGS_ENTRY.test(name) || isMainExecutable(name, data)) {
+        const strings = (isHermes ? hermesStrings(data) : null) ?? extractStrings(data);
+        // One string per line; a multi-line literal stays readable but cannot merge with its neighbour.
+        return { absolutePath: location, relativePath: `${name} (strings)`, text: strings.map((s) => s.replace(/\n/g, " ")).join("\n") };
+    }
+    return null;
+}
+/** The iOS app executable: Payload/Name.app/Name, a Mach-O file. */
+function isMainExecutable(name, data) {
+    const match = /^Payload\/([^/]+)\.app\/([^/]+)$/.exec(name);
+    if (match === null || match[1] !== match[2] || data.length < 4)
+        return false;
+    const magic = data.readUInt32LE(0);
+    return magic === 0xfeedfacf || magic === 0xfeedface || magic === 0xcafebabe || magic === 0xbebafeca;
+}
+export async function collectArchive(file) {
+    const info = await stat(file);
+    if (info.size > MAX_ARCHIVE_BYTES)
+        throw new Error(`${file} is larger than ${MAX_ARCHIVE_BYTES / 1024 / 1024} MiB`);
+    const buffer = await readFile(file);
+    const kind = archiveKind(file, buffer);
+    if (kind === null)
+        throw new Error(`not a supported app package (.apk, .aab, .ipa, .asar): ${file}`);
+    const entries = kind === "electron" ? asarEntries(buffer) : zipEntries(buffer);
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name.split("/").includes("node_modules") && kind !== "electron")
+            continue;
+        const scanned = toScanned(entry.name, entry.read(), `${file}!/${entry.name}`);
+        if (scanned !== null)
+            files.push(scanned);
+    }
+    files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+    return { kind, files };
+}

package/dist/scan/artifact.d.ts

@@ -1,18 +1,34 @@
 import { type Finding, type ScanSummary } from "../index.ts";
+import type { RuleContext } from "../rules/types.ts";
 import { type Adapter } from "./adapters.ts";
+import { type ArchiveKind } from "./archive.ts";
+import { type ScannedFile } from "./files.ts";
 export interface ArtifactScanOptions {
     /** Force an adapter instead of detecting one from the directory. */
     adapter?: Adapter["name"];
+    /** See RuleContext.onMatch. */
+    onMatch?: RuleContext["onMatch"];
 }
 export interface ArtifactScanResult extends ScanSummary {
     layer: "artifact";
     target: string;
-    adapter: Adapter["name"];
+    /** Directory adapter, or the kind of app package scanned. */
+    adapter: Adapter["name"] | ArchiveKind;
     filesScanned: number;
     /** Findings removed by config ignore rules; they are not in `findings`. */
     ignored: number;
 }
 /** Worst first, then surest first, then by location so output is stable. */
 export declare function sortFindings(findings: Finding[]): Finding[];
-/** Layer 1: scan a directory of built files for what should not ship. */
+export interface CollectedTarget {
+    root: string;
+    adapter: Adapter;
+    /** Directory adapter, or the kind of app package. */
+    adapterName: ArtifactScanResult["adapter"];
+    files: ScannedFile[];
+}
+/** Read what a target ships: a build directory through its adapter, or an app package in memory. */
+export declare function collectTarget(target: string, options?: Pick<ArtifactScanOptions, "adapter">): Promise<CollectedTarget>;
+export declare function runArtifactRules(files: ScannedFile[], adapter: Adapter, onMatch?: RuleContext["onMatch"]): Finding[];
+/** Layer 1: scan a directory of built files, or an app package, for what should not ship. */
 export declare function scanArtifact(target: string, options?: ArtifactScanOptions): Promise<ArtifactScanResult>;

package/dist/scan/artifact.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { VERSION } from "../index.js";
 import { ARTIFACT_RULES } from "../rules/index.js";
 import { ADAPTERS, detectAdapter } from "./adapters.js";
+import { collectArchive } from "./archive.js";
 import { collectFiles } from "./files.js";
 const SEVERITY_RANK = {
     critical: 0,
@@ -34,35 +35,47 @@ export function sortFindings(findings) {
         return aLine - bLine;
     });
 }
-/** Layer 1: scan a directory of built files for what should not ship. */
-export async function scanArtifact(target, options = {}) {
-    const startedAt = new Date().toISOString();
+/** Read what a target ships: a build directory through its adapter, or an app package in memory. */
+export async function collectTarget(target, options = {}) {
     const root = path.resolve(target);
     const info = await stat(root).catch(() => null);
-    if (info === null || !info.isDirectory()) {
-        throw new Error(`not a directory: ${target}`);
+    if (info === null || (!info.isDirectory() && !info.isFile())) {
+        throw new Error(`not a directory or app package: ${target}`);
+    }
+    if (info.isFile()) {
+        // An app package ships everything inside it; there is nothing for a web adapter to filter.
+        const archive = await collectArchive(root);
+        return { root, adapter: ADAPTERS.plain, adapterName: archive.kind, files: archive.files };
     }
     const adapter = options.adapter ? ADAPTERS[options.adapter] : await detectAdapter(root);
-    const files = await collectFiles(root, adapter);
+    return { root, adapter, adapterName: adapter.name, files: await collectFiles(root, adapter) };
+}
+export function runArtifactRules(files, adapter, onMatch) {
     const context = {
         adapter,
         shippedPaths: new Set(files.map((file) => file.relativePath)),
+        ...(onMatch === undefined ? {} : { onMatch }),
     };
     const findings = [];
     for (const file of files) {
-        for (const rule of ARTIFACT_RULES) {
+        for (const rule of ARTIFACT_RULES)
             findings.push(...rule.check(file, context));
-        }
     }
+    return sortFindings(findings);
+}
+/** Layer 1: scan a directory of built files, or an app package, for what should not ship. */
+export async function scanArtifact(target, options = {}) {
+    const startedAt = new Date().toISOString();
+    const collected = await collectTarget(target, options);
     return {
         version: VERSION,
         layer: "artifact",
-        target: root,
-        adapter: adapter.name,
-        filesScanned: files.length,
+        target: collected.root,
+        adapter: collected.adapterName,
+        filesScanned: collected.files.length,
         ignored: 0,
         startedAt,
         finishedAt: new Date().toISOString(),
-        findings: sortFindings(findings),
+        findings: runArtifactRules(collected.files, collected.adapter, options.onMatch),
     };
 }

package/dist/scan/files.d.ts

@@ -11,6 +11,7 @@ export interface CollectOptions {
     /** Files larger than this are skipped; bundles rarely exceed it and maps can be huge. */
     maxBytes?: number;
 }
+export declare const PACKAGED: RegExp;
 export declare function toPosix(relative: string): string;
 /** Walk the root, keep what the adapter says the browser receives, read as UTF-8. */
 export declare function collectFiles(root: string, adapter: Adapter, options?: CollectOptions): Promise<ScannedFile[]>;

package/dist/scan/files.js

@@ -1,7 +1,9 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { toScanned } from "./archive.js";
 const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
 const ALWAYS_SKIP_DIRS = new Set(["node_modules", ".git"]);
+export const PACKAGED = /\.(?:bundle|jsbundle|hbc|dex)$/i;
 /** Cheap binary check: a NUL byte in the first 8 KiB means not text. */
 function isProbablyBinary(buffer) {
     const end = Math.min(buffer.length, 8192);
@@ -26,6 +28,16 @@ export async function collectFiles(root, adapter, options = {}) {
         const relativePath = toPosix(path.relative(root, absolutePath));
         if (relativePath.split("/").some((segment) => ALWAYS_SKIP_DIRS.has(segment)))
             continue;
+        // React Native bundles and Android bytecode in an extracted app or a native build directory.
+        if (PACKAGED.test(relativePath)) {
+            const info = await stat(absolutePath);
+            if (info.size === 0 || info.size > maxBytes)
+                continue;
+            const scanned = toScanned(relativePath, await readFile(absolutePath), absolutePath);
+            if (scanned !== null)
+                files.push(scanned);
+            continue;
+        }
         if (!adapter.includes(relativePath))
             continue;
         const info = await stat(absolutePath);

package/dist/surface/collect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The function that runs inside the page. It is serialized by the browser
+ * driver, so it must be self-contained: no imports, no closures, no helpers
+ * defined outside its body.
+ */
+import type { SurfaceSnapshot } from "./types.ts";
+export type CollectedSurface = Pick<SurfaceSnapshot, "blocks" | "attributes" | "scripts" | "storage" | "selectorMatches">;
+export interface CollectArgs {
+    absentSelectors: string[];
+    maxBlocks: number;
+    maxText: number;
+}
+export declare function collectSurface(args: CollectArgs): CollectedSurface;

package/dist/surface/collect.js

@@ -0,0 +1,130 @@
+export function collectSurface(args) {
+    const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "TITLE", "META", "LINK"]);
+    const clip = (text) => (text.length > args.maxText ? `${text.slice(0, args.maxText)}…` : text);
+    const norm = (text) => text.replace(/\s+/g, " ").trim();
+    const selectorOf = (element) => {
+        const parts = [];
+        let node = element;
+        while (node !== null && parts.length < 5) {
+            if (node.id !== "" && /^[A-Za-z][\w-]*$/.test(node.id)) {
+                parts.unshift(`#${node.id}`);
+                break;
+            }
+            let part = node.tagName.toLowerCase();
+            const parent = node.parentElement;
+            if (parent !== null) {
+                const same = Array.from(parent.children).filter((child) => child.tagName === node.tagName);
+                if (same.length > 1)
+                    part += `:nth-of-type(${same.indexOf(node) + 1})`;
+            }
+            parts.unshift(part);
+            node = parent;
+        }
+        return parts.join(" > ");
+    };
+    const blurPx = (filter) => {
+        const match = /blur\(([\d.]+)px\)/.exec(filter);
+        return match === null ? 0 : Number(match[1]);
+    };
+    const alphaOf = (color) => {
+        if (color === "transparent")
+            return 0;
+        const match = /rgba?\(([^)]+)\)/.exec(color);
+        if (match === null)
+            return 1;
+        const parts = match[1].split(/[ ,/]+/).filter((part) => part.length > 0);
+        return parts.length >= 4 ? Number(parts[3]) : 1;
+    };
+    const hiddenBy = (element) => {
+        const checkable = element;
+        const rect = element.getBoundingClientRect();
+        for (let node = element; node !== null; node = node.parentElement) {
+            const style = getComputedStyle(node);
+            if (style.display === "none")
+                return "display";
+            if (blurPx(style.filter) >= 2)
+                return "blur";
+            if (Number(style.opacity) < 0.1)
+                return "opacity";
+            if (node !== element && style.overflow !== "visible" && style.overflow !== "") {
+                const box = node.getBoundingClientRect();
+                const outside = rect.bottom <= box.top || rect.top >= box.bottom || rect.right <= box.left || rect.left >= box.right;
+                if (outside || box.width < 2 || box.height < 2)
+                    return "clipped";
+            }
+        }
+        if (checkable.checkVisibility !== undefined && !checkable.checkVisibility({ checkVisibilityCSS: true, visibilityProperty: true, contentVisibilityAuto: true })) {
+            return "visibility";
+        }
+        const style = getComputedStyle(element);
+        if (style.visibility !== "visible")
+            return "visibility";
+        if (alphaOf(style.color) < 0.1)
+            return style.textShadow !== "none" ? "blur" : "transparent-text";
+        if (rect.width === 0 || rect.height === 0)
+            return "zero-size";
+        if (style.clip !== "auto" && style.clip !== "" && (rect.width <= 1 || rect.height <= 1))
+            return "clipped";
+        return null;
+    };
+    const blocks = [];
+    const attributes = [];
+    const scripts = [];
+    for (const element of Array.from(document.querySelectorAll("body *"))) {
+        if (SKIP.has(element.tagName)) {
+            if (element.tagName === "SCRIPT" && !element.src) {
+                const text = norm(element.textContent ?? "");
+                if (text.length > 0)
+                    scripts.push({ selector: selectorOf(element), text });
+            }
+            continue;
+        }
+        for (const attribute of Array.from(element.attributes)) {
+            const isValue = attribute.name === "value" && element.tagName === "INPUT";
+            if ((attribute.name.startsWith("data-") || isValue) && attribute.value.trim().length > 0) {
+                attributes.push({ selector: selectorOf(element), name: attribute.name, value: clip(norm(attribute.value)) });
+            }
+        }
+        if (blocks.length >= args.maxBlocks)
+            continue;
+        let own = "";
+        for (const child of Array.from(element.childNodes))
+            if (child.nodeType === 3)
+                own += ` ${child.textContent ?? ""}`;
+        own = norm(own);
+        if (own.length === 0)
+            continue;
+        blocks.push({ selector: selectorOf(element), text: clip(own), hiddenBy: hiddenBy(element) });
+    }
+    for (const script of Array.from(document.querySelectorAll("head script:not([src])"))) {
+        const text = norm(script.textContent ?? "");
+        if (text.length > 0)
+            scripts.push({ selector: selectorOf(script), text });
+    }
+    const storage = [];
+    for (const area of ["localStorage", "sessionStorage"]) {
+        try {
+            const store = window[area];
+            for (let i = 0; i < store.length; i += 1) {
+                const key = store.key(i);
+                if (key !== null)
+                    storage.push({ area, key, value: clip(store.getItem(key) ?? "") });
+            }
+        }
+        catch {
+            // Storage can be blocked for the origin; nothing to record.
+        }
+    }
+    const selectorMatches = [];
+    for (const selector of args.absentSelectors) {
+        try {
+            const found = document.querySelector(selector);
+            if (found !== null)
+                selectorMatches.push({ selector, text: clip(norm(found.textContent ?? "")) });
+        }
+        catch {
+            selectorMatches.push({ selector, text: "(invalid selector)" });
+        }
+    }
+    return { blocks, attributes, scripts, storage, selectorMatches };
+}

package/dist/surface/driver.d.ts

@@ -0,0 +1,17 @@
+import type { SurfaceIdentityConfig, SurfaceSnapshot } from "./types.ts";
+export interface CaptureRequest {
+    baseUrl: string;
+    url: string;
+    identityName: string;
+    identity: SurfaceIdentityConfig;
+    waitFor?: string;
+    absentSelectors: string[];
+    timeoutMs: number;
+    env?: NodeJS.ProcessEnv;
+}
+export interface SurfaceDriver {
+    capture(request: CaptureRequest): Promise<SurfaceSnapshot>;
+    close(): Promise<void>;
+}
+export declare const PLAYWRIGHT_MISSING = "evershield surface drives a headless browser and needs Playwright: npm install --save-dev playwright && npx playwright install chromium";
+export declare function launchPlaywrightDriver(env?: NodeJS.ProcessEnv): Promise<SurfaceDriver>;