evershield 0.1.0 → 0.2.0

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>;

package/dist/surface/driver.js

@@ -0,0 +1,114 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Headless browser driver. Playwright is an optional peer dependency: the
+ * layer 1 and 2 commands never load it, and `evershield surface` explains
+ * how to install it when it is missing.
+ *
+ * Only the small slice of Playwright's API evershield uses is typed here,
+ * so the published types do not depend on Playwright being installed.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { interpolateEnv } from "../audit/http.js";
+import { ConfigError } from "../config.js";
+import { collectSurface } from "./collect.js";
+export const PLAYWRIGHT_MISSING = "evershield surface drives a headless browser and needs Playwright: npm install --save-dev playwright && npx playwright install chromium";
+async function loadPlaywright() {
+    for (const name of ["playwright", "playwright-core"]) {
+        try {
+            return (await import(__rewriteRelativeImportExtension(name)));
+        }
+        catch {
+            // Try the next package name.
+        }
+    }
+    throw new Error(PLAYWRIGHT_MISSING);
+}
+const COLLECT_LIMITS = { maxBlocks: 5000, maxText: 500 };
+function emptySnapshot(request, error) {
+    return {
+        identity: request.identityName,
+        url: request.url,
+        finalUrl: request.url,
+        status: 0,
+        blocks: [],
+        attributes: [],
+        scripts: [],
+        storage: [],
+        selectorMatches: [],
+        error,
+    };
+}
+async function readStorageState(file, env) {
+    const resolved = path.resolve(interpolateEnv(file, env));
+    try {
+        return JSON.parse(await readFile(resolved, "utf8"));
+    }
+    catch (error) {
+        throw new ConfigError(`cannot read storageState ${resolved}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function launchPlaywrightDriver(env = process.env) {
+    const playwright = await loadPlaywright();
+    const executablePath = env.EVERSHIELD_CHROMIUM_PATH;
+    const browser = await playwright.chromium.launch({ headless: true, ...(executablePath ? { executablePath } : {}) });
+    return {
+        async capture(request) {
+            const env = request.env ?? process.env;
+            const origin = new URL(request.baseUrl).origin;
+            const headers = Object.fromEntries(Object.entries(request.identity.headers ?? {}).map(([name, value]) => [name.toLowerCase(), interpolateEnv(value, env)]));
+            const cookies = Object.entries(request.identity.cookies ?? {}).map(([name, value]) => ({ name, value: interpolateEnv(value, env), url: origin }));
+            const storageState = request.identity.storageState === undefined ? undefined : await readStorageState(request.identity.storageState, env);
+            // Service workers are blocked so every request goes through the route
+            // below, which adds credentials only for the audited origin.
+            const context = await browser.newContext({ serviceWorkers: "block", ...(storageState === undefined ? {} : { storageState }) });
+            try {
+                if (Object.keys(headers).length > 0) {
+                    await context.route("**/*", async (route) => {
+                        const target = route.request();
+                        if (new URL(target.url()).origin === origin)
+                            await route.continue({ headers: { ...target.headers(), ...headers } });
+                        else
+                            await route.continue();
+                    });
+                }
+                if (cookies.length > 0)
+                    await context.addCookies(cookies);
+                const page = await context.newPage();
+                let response;
+                try {
+                    response = await page.goto(request.url, { waitUntil: "networkidle", timeout: request.timeoutMs });
+                }
+                catch (error) {
+                    return emptySnapshot(request, error instanceof Error ? error.message.split("\n")[0] : String(error));
+                }
+                if (request.waitFor !== undefined) {
+                    try {
+                        await page.waitForSelector(request.waitFor, { timeout: request.timeoutMs, state: "attached" });
+                    }
+                    catch {
+                        return { ...emptySnapshot(request, `waitFor selector "${request.waitFor}" never appeared`), finalUrl: page.url(), status: response?.status() ?? 0 };
+                    }
+                }
+                // Let late effects (entitlement checks, transitions) settle.
+                await page.waitForTimeout(300);
+                const args = { absentSelectors: request.absentSelectors, ...COLLECT_LIMITS };
+                const collected = await page.evaluate(collectSurface, args);
+                return { identity: request.identityName, url: request.url, finalUrl: page.url(), status: response?.status() ?? 0, ...collected };
+            }
+            finally {
+                await context.close();
+            }
+        },
+        async close() {
+            await browser.close();
+        },
+    };
+}

package/dist/surface/rules.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Surface rules. Each inspects one page observed as every identity.
+ *
+ * - surface/expected-absent-present: the operator said identity X must not
+ *   receive text T (or selector S) on this page, and it is somewhere in X's
+ *   DOM, attributes, inline scripts or storage. High/high: the operator's
+ *   own contract.
+ * - surface/hidden-higher-tier-content: text the top tier can see is present
+ *   for a lower tier but hidden from it (display:none, blur, clipped, in a
+ *   data attribute, inline script or storage). The paywall is cosmetic.
+ *   High/high: the same text, visible to one tier and hidden in another's
+ *   page, is not a coincidence.
+ * - surface/obscured-content: a lower tier's page blurs or makes transparent
+ *   real-looking text. Blur is how UIs fake a paywall; legitimate hidden UI
+ *   (menus, tabs) uses display or visibility instead. High/medium: the text
+ *   may be a decoy, which the rule cannot always tell.
+ *
+ * Tabs, menus and dialogs hidden for every tier never fire the differential
+ * rule, because it requires the top tier to see the text.
+ */
+import type { Confidence, Finding, Severity } from "../index.ts";
+import type { PageObservation } from "./types.ts";
+export interface SurfaceRule {
+    id: string;
+    defaultSeverity: Severity;
+    defaultConfidence: Confidence;
+    check(observation: PageObservation): Finding[];
+}
+export declare const expectedAbsentPresent: SurfaceRule;
+export declare const hiddenHigherTierContent: SurfaceRule;
+export declare const obscuredContent: SurfaceRule;
+export declare const SURFACE_RULES: readonly SurfaceRule[];

package/dist/surface/rules.js

@@ -0,0 +1,150 @@
+const RULES_DOC = "https://github.com/inviy/evershield/blob/main/docs/rules.md";
+const help = (id) => `${RULES_DOC}#${id.replace("/", "")}`;
+function excerpt(text, max = 80) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+function usable(snapshot) {
+    return snapshot !== undefined && snapshot.error === undefined && snapshot.status < 400;
+}
+/** Find `needle` in everything the identity received, hidden or not. */
+function locate(snapshot, needle, options) {
+    for (const block of snapshot.blocks) {
+        if (options.hiddenOnly && block.hiddenBy === null)
+            continue;
+        if (block.text.includes(needle)) {
+            return { selector: block.selector, where: block.hiddenBy === null ? "visible text" : `text hidden by ${block.hiddenBy}`, text: block.text };
+        }
+    }
+    for (const attribute of snapshot.attributes) {
+        if (attribute.value.includes(needle))
+            return { selector: `${attribute.selector}[${attribute.name}]`, where: `attribute ${attribute.name}`, text: attribute.value };
+    }
+    for (const script of snapshot.scripts) {
+        if (script.text.includes(needle))
+            return { selector: script.selector, where: "inline script", text: needle };
+    }
+    for (const entry of snapshot.storage) {
+        if (entry.value.includes(needle) || entry.key.includes(needle)) {
+            return { selector: `${entry.area}[${JSON.stringify(entry.key)}]`, where: entry.area, text: needle };
+        }
+    }
+    return undefined;
+}
+export const expectedAbsentPresent = {
+    id: "surface/expected-absent-present",
+    defaultSeverity: "high",
+    defaultConfidence: "high",
+    check(observation) {
+        const findings = [];
+        for (const [identity, expectation] of Object.entries(observation.page.expect ?? {})) {
+            const snapshot = observation.snapshots.get(identity);
+            if (!usable(snapshot))
+                continue;
+            for (const text of expectation.absentText ?? []) {
+                const hit = locate(snapshot, text, { hiddenOnly: false });
+                if (hit === undefined)
+                    continue;
+                findings.push({
+                    ruleId: expectedAbsentPresent.id,
+                    layer: "surface",
+                    severity: "high",
+                    confidence: "high",
+                    message: `${observation.page.path} gives ${identity} "${excerpt(text, 40)}" (${hit.where}), which the config says it must not receive`,
+                    evidence: [{ kind: "dom", url: observation.url, selector: hit.selector, identity, excerpt: excerpt(hit.text) }],
+                    remediation: "Do not send this content to this tier at all: render it on the server only for entitled users. Hiding it in the page is not a boundary.",
+                    helpUri: help(expectedAbsentPresent.id),
+                });
+            }
+            for (const match of snapshot.selectorMatches) {
+                if (match.text === "(invalid selector)")
+                    continue;
+                findings.push({
+                    ruleId: expectedAbsentPresent.id,
+                    layer: "surface",
+                    severity: "high",
+                    confidence: "high",
+                    message: `${observation.page.path} renders "${match.selector}" for ${identity}, which the config says must match nothing`,
+                    evidence: [{ kind: "dom", url: observation.url, selector: match.selector, identity, excerpt: excerpt(match.text) }],
+                    remediation: "Do not render this element for this tier; if it needs a placeholder, render placeholder content, not the real value.",
+                    helpUri: help(expectedAbsentPresent.id),
+                });
+            }
+        }
+        return findings;
+    },
+};
+export const hiddenHigherTierContent = {
+    id: "surface/hidden-higher-tier-content",
+    defaultSeverity: "high",
+    defaultConfidence: "high",
+    check(observation) {
+        const findings = [];
+        const topName = observation.tiers[observation.tiers.length - 1];
+        const top = topName === undefined ? undefined : observation.snapshots.get(topName);
+        if (!usable(top) || observation.tiers.length < 2)
+            return findings;
+        const topVisible = [...new Set(top.blocks.filter((block) => block.hiddenBy === null && block.text.length >= observation.minTextLength).map((block) => block.text))];
+        for (const identity of observation.tiers.slice(0, -1)) {
+            const snapshot = observation.snapshots.get(identity);
+            if (!usable(snapshot))
+                continue;
+            const visibleHere = snapshot.blocks.filter((block) => block.hiddenBy === null).map((block) => block.text);
+            let reported = 0;
+            for (const text of topVisible) {
+                // Visible to this tier too: shared content, not a leak.
+                if (visibleHere.some((visible) => visible.includes(text)))
+                    continue;
+                const hit = locate(snapshot, text, { hiddenOnly: true });
+                if (hit === undefined)
+                    continue;
+                reported += 1;
+                if (reported > 20)
+                    break;
+                findings.push({
+                    ruleId: hiddenHigherTierContent.id,
+                    layer: "surface",
+                    severity: "high",
+                    confidence: "high",
+                    message: `${observation.page.path}: "${excerpt(text, 40)}" is visible to ${topName} and present but hidden for ${identity} (${hit.where})`,
+                    evidence: [{ kind: "dom", url: observation.url, selector: hit.selector, identity, excerpt: excerpt(text) }],
+                    remediation: `Anyone on the ${identity} tier can read this in DevTools. Leave it out of the ${identity} page (server-render a placeholder) instead of hiding it.`,
+                    helpUri: help(hiddenHigherTierContent.id),
+                });
+            }
+        }
+        return findings;
+    },
+};
+/** Text that is obviously a decoy: masks, lorem ipsum, a single repeated character. */
+const PLACEHOLDER = /^(?:[\sxX*•●▒█#?·._,\-–—0]+|lorem ipsum.*|(.)\1+)$/i;
+export const obscuredContent = {
+    id: "surface/obscured-content",
+    defaultSeverity: "high",
+    defaultConfidence: "medium",
+    check(observation) {
+        const findings = [];
+        // With one identity there is nothing more privileged to protect; still
+        // check it, since blur on any audited page is the classic fake paywall.
+        const lower = observation.tiers.length > 1 ? observation.tiers.slice(0, -1) : observation.tiers;
+        for (const identity of lower) {
+            const snapshot = observation.snapshots.get(identity);
+            if (!usable(snapshot))
+                continue;
+            const obscured = snapshot.blocks.filter((block) => (block.hiddenBy === "blur" || block.hiddenBy === "transparent-text") && block.text.length >= 3 && !PLACEHOLDER.test(block.text));
+            if (obscured.length === 0)
+                continue;
+            findings.push({
+                ruleId: obscuredContent.id,
+                layer: "surface",
+                severity: "high",
+                confidence: "medium",
+                message: `${observation.page.path} shows ${identity} ${obscured.length} blurred or transparent text element(s); the text is readable in the DOM`,
+                evidence: obscured.slice(0, 10).map((block) => ({ kind: "dom", url: observation.url, selector: block.selector, identity, excerpt: excerpt(block.text) })),
+                remediation: `Render placeholder text (e.g. "●●●") behind the blur for ${identity}, or nothing; send the real values only to tiers that may see them.`,
+                helpUri: help(obscuredContent.id),
+            });
+        }
+        return findings;
+    },
+};
+export const SURFACE_RULES = [expectedAbsentPresent, hiddenHigherTierContent, obscuredContent];

package/dist/surface/run.d.ts

@@ -0,0 +1,23 @@
+import { type ScanSummary } from "../index.ts";
+import { type SurfaceDriver } from "./driver.ts";
+import type { SurfaceConfig } from "./types.ts";
+export interface SurfaceResult extends ScanSummary {
+    layer: "surface";
+    target: string;
+    identities: string[];
+    pagesAudited: number;
+    /** Page loads that rendered and were evaluated by the rules. */
+    snapshotsEvaluated: number;
+    ignored: number;
+    warnings: string[];
+}
+export interface SurfaceOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Injected in tests; defaults to a Playwright Chromium. */
+    driver?: SurfaceDriver;
+}
+/**
+ * Layer 3: open each page as each identity, least privileged first, one at a
+ * time, and run the surface rules over what each identity's browser held.
+ */
+export declare function runSurface(config: SurfaceConfig, options?: SurfaceOptions): Promise<SurfaceResult>;

package/dist/surface/run.js

@@ -0,0 +1,80 @@
+import { VERSION } from "../index.js";
+import { sortFindings } from "../scan/artifact.js";
+import { launchPlaywrightDriver } from "./driver.js";
+import { SURFACE_RULES } from "./rules.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MIN_TEXT = 12;
+/**
+ * Layer 3: open each page as each identity, least privileged first, one at a
+ * time, and run the surface rules over what each identity's browser held.
+ */
+export async function runSurface(config, options = {}) {
+    const startedAt = new Date().toISOString();
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const minTextLength = config.minTextLength ?? DEFAULT_MIN_TEXT;
+    const findings = [];
+    const warnings = [];
+    let snapshotsEvaluated = 0;
+    const driver = options.driver ?? (await launchPlaywrightDriver(options.env));
+    try {
+        for (const page of config.pages) {
+            const url = new URL(page.path, config.baseUrl).toString();
+            const observation = { page, url, tiers: config.tiers, snapshots: new Map(), minTextLength };
+            for (const identityName of config.tiers) {
+                const identity = config.identities[identityName];
+                if (identity === undefined) {
+                    warnings.push(`${page.path}: identity "${identityName}" is not defined`);
+                    continue;
+                }
+                const snapshot = await driver.capture({
+                    baseUrl: config.baseUrl,
+                    url,
+                    identityName,
+                    identity,
+                    absentSelectors: page.expect?.[identityName]?.absentSelectors ?? [],
+                    timeoutMs,
+                    ...(page.waitFor === undefined ? {} : { waitFor: page.waitFor }),
+                    ...(options.env === undefined ? {} : { env: options.env }),
+                });
+                if (snapshot.error === undefined && new URL(snapshot.finalUrl).origin !== new URL(config.baseUrl).origin) {
+                    snapshot.error = `redirected off the audited origin to ${new URL(snapshot.finalUrl).origin}`;
+                }
+                observation.snapshots.set(identityName, snapshot);
+                for (const match of snapshot.selectorMatches) {
+                    if (match.text === "(invalid selector)")
+                        warnings.push(`${page.path}: absentSelectors entry "${match.selector}" is not a valid CSS selector`);
+                }
+                if (snapshot.error !== undefined) {
+                    warnings.push(`${page.path} as ${identityName}: ${snapshot.error}, not evaluated`);
+                }
+                else if (snapshot.status >= 400) {
+                    warnings.push(`${page.path} as ${identityName}: HTTP ${snapshot.status}, not evaluated`);
+                }
+                else {
+                    snapshotsEvaluated += 1;
+                    if (snapshot.finalUrl !== url)
+                        warnings.push(`${page.path} as ${identityName}: landed on ${snapshot.finalUrl}`);
+                }
+            }
+            for (const rule of SURFACE_RULES)
+                findings.push(...rule.check(observation));
+        }
+    }
+    finally {
+        if (options.driver === undefined)
+            await driver.close();
+    }
+    return {
+        version: VERSION,
+        layer: "surface",
+        target: config.baseUrl,
+        identities: [...config.tiers],
+        pagesAudited: config.pages.length,
+        snapshotsEvaluated,
+        ignored: 0,
+        warnings,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        findings: sortFindings(findings),
+    };
+}

package/dist/surface/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Layer 3: rendered-surface audit.
+ *
+ * The operator lists pages and identities. evershield opens each page in a
+ * headless browser as each identity, waits for it to settle, and records
+ * every text-bearing element with whether a person can actually see it,
+ * plus `data-*` attributes, inline scripts and web storage. The rules then
+ * look for data that is present but only visually hidden.
+ */
+export interface SurfaceIdentityConfig {
+    /** Sent only to requests for `baseUrl`'s origin. Credential headers must reference env vars. */
+    headers?: Record<string, string>;
+    /** Cookie name → value, set for `baseUrl`. Values must reference env vars. */
+    cookies?: Record<string, string>;
+    /** Path to a Playwright storage-state file (cookies + localStorage), e.g. from `playwright codegen --save-storage`. May reference env vars. */
+    storageState?: string;
+}
+export interface PageExpectation {
+    /** Strings that must not appear anywhere for this identity: DOM text (hidden or not), attributes, inline scripts, storage. */
+    absentText?: string[];
+    /** CSS selectors that must match nothing for this identity. */
+    absentSelectors?: string[];
+}
+export interface PageConfig {
+    /** Path relative to `baseUrl`, starting with `/`. */
+    path: string;
+    /** CSS selector to wait for before capturing, for pages that render after data loads. */
+    waitFor?: string;
+    expect?: Record<string, PageExpectation>;
+}
+export interface SurfaceConfig {
+    /** Origin the browser is allowed to be credentialed for. Pages are relative to it. */
+    baseUrl: string;
+    /** Identity names ordered from least to most privileged. */
+    tiers: string[];
+    identities: Record<string, SurfaceIdentityConfig>;
+    pages: PageConfig[];
+    timeoutMs?: number;
+    /** Shortest text, in characters, the differential rule compares. Default 12. */
+    minTextLength?: number;
+}
+/** Why an element cannot be seen. `null` means visible. */
+export type HiddenBy = "display" | "visibility" | "opacity" | "blur" | "transparent-text" | "clipped" | "zero-size";
+export interface TextBlock {
+    selector: string;
+    /** Element's own text (direct text nodes), whitespace collapsed. */
+    text: string;
+    hiddenBy: HiddenBy | null;
+}
+export interface AttributeValue {
+    selector: string;
+    name: string;
+    value: string;
+}
+export interface ScriptText {
+    selector: string;
+    text: string;
+}
+export interface StorageEntry {
+    area: "localStorage" | "sessionStorage";
+    key: string;
+    value: string;
+}
+export interface SurfaceSnapshot {
+    identity: string;
+    /** URL requested. */
+    url: string;
+    /** URL after redirects. */
+    finalUrl: string;
+    status: number;
+    blocks: TextBlock[];
+    attributes: AttributeValue[];
+    scripts: ScriptText[];
+    storage: StorageEntry[];
+    /** Selectors from the page's `absentSelectors` expectations that matched, with a text sample. */
+    selectorMatches: Array<{
+        selector: string;
+        text: string;
+    }>;
+    /** Navigation or capture failure. */
+    error?: string;
+}
+export interface PageObservation {
+    page: PageConfig;
+    /** Absolute URL of the page. */
+    url: string;
+    tiers: string[];
+    snapshots: Map<string, SurfaceSnapshot>;
+    minTextLength: number;
+}

package/dist/surface/types.js

@@ -0,0 +1,10 @@
+/**
+ * Layer 3: rendered-surface audit.
+ *
+ * The operator lists pages and identities. evershield opens each page in a
+ * headless browser as each identity, waits for it to settle, and records
+ * every text-bearing element with whether a person can actually see it,
+ * plus `data-*` attributes, inline scripts and web storage. The rules then
+ * look for data that is present but only visually hidden.
+ */
+export {};