evershield 0.0.0-stage → 0.2.0

package/dist/scan/artifact.js

@@ -0,0 +1,68 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { VERSION } from "../index.js";
+import { ARTIFACT_RULES } from "../rules/index.js";
+import { ADAPTERS, detectAdapter } from "./adapters.js";
+import { collectFiles } from "./files.js";
+const SEVERITY_RANK = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};
+const CONFIDENCE_RANK = {
+    high: 0,
+    medium: 1,
+    low: 2,
+};
+/** Worst first, then surest first, then by location so output is stable. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+        if (bySeverity !== 0)
+            return bySeverity;
+        const byConfidence = CONFIDENCE_RANK[a.confidence] - CONFIDENCE_RANK[b.confidence];
+        if (byConfidence !== 0)
+            return byConfidence;
+        const aPath = a.evidence[0]?.kind === "file" ? a.evidence[0].path : "";
+        const bPath = b.evidence[0]?.kind === "file" ? b.evidence[0].path : "";
+        if (aPath !== bPath)
+            return aPath < bPath ? -1 : 1;
+        const aLine = a.evidence[0]?.kind === "file" ? (a.evidence[0].line ?? 0) : 0;
+        const bLine = b.evidence[0]?.kind === "file" ? (b.evidence[0].line ?? 0) : 0;
+        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();
+    const root = path.resolve(target);
+    const info = await stat(root).catch(() => null);
+    if (info === null || !info.isDirectory()) {
+        throw new Error(`not a directory: ${target}`);
+    }
+    const adapter = options.adapter ? ADAPTERS[options.adapter] : await detectAdapter(root);
+    const files = await collectFiles(root, adapter);
+    const context = {
+        adapter,
+        shippedPaths: new Set(files.map((file) => file.relativePath)),
+    };
+    const findings = [];
+    for (const file of files) {
+        for (const rule of ARTIFACT_RULES) {
+            findings.push(...rule.check(file, context));
+        }
+    }
+    return {
+        version: VERSION,
+        layer: "artifact",
+        target: root,
+        adapter: adapter.name,
+        filesScanned: files.length,
+        ignored: 0,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        findings: sortFindings(findings),
+    };
+}

package/dist/scan/files.d.ts

@@ -0,0 +1,16 @@
+import type { Adapter } from "./adapters.ts";
+/** One text file inside the artifact, as rules see it. */
+export interface ScannedFile {
+    /** Absolute path on disk. */
+    absolutePath: string;
+    /** Path relative to the scan root, with forward slashes. Used in reports. */
+    relativePath: string;
+    text: string;
+}
+export interface CollectOptions {
+    /** Files larger than this are skipped; bundles rarely exceed it and maps can be huge. */
+    maxBytes?: number;
+}
+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

@@ -0,0 +1,41 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const ALWAYS_SKIP_DIRS = new Set(["node_modules", ".git"]);
+/** Cheap binary check: a NUL byte in the first 8 KiB means not text. */
+function isProbablyBinary(buffer) {
+    const end = Math.min(buffer.length, 8192);
+    for (let i = 0; i < end; i += 1) {
+        if (buffer[i] === 0)
+            return true;
+    }
+    return false;
+}
+export function toPosix(relative) {
+    return relative.split(path.sep).join("/");
+}
+/** Walk the root, keep what the adapter says the browser receives, read as UTF-8. */
+export async function collectFiles(root, adapter, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const absolutePath = path.join(entry.parentPath, entry.name);
+        const relativePath = toPosix(path.relative(root, absolutePath));
+        if (relativePath.split("/").some((segment) => ALWAYS_SKIP_DIRS.has(segment)))
+            continue;
+        if (!adapter.includes(relativePath))
+            continue;
+        const info = await stat(absolutePath);
+        if (info.size === 0 || info.size > maxBytes)
+            continue;
+        const buffer = await readFile(absolutePath);
+        if (isProbablyBinary(buffer))
+            continue;
+        files.push({ absolutePath, relativePath, text: buffer.toString("utf8") });
+    }
+    files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+    return files;
+}

package/dist/scan/text.d.ts

@@ -0,0 +1,18 @@
+/** Text helpers shared by rules: positions, redaction and entropy. */
+export interface LineColumn {
+    line: number;
+    column: number;
+}
+/** 1-based line and column for a character offset. */
+export declare function lineColumn(text: string, offset: number): LineColumn;
+/**
+ * Redact a matched value so reports never reproduce the secret they found.
+ * Keeps enough of each end to recognise the value in the source.
+ */
+export declare function redact(value: string, keep?: number): string;
+/** Shannon entropy in bits per character. ~4.5 is random base64, ~3 is prose. */
+export declare function shannonEntropy(value: string): number;
+/** Values humans type as stand-ins; never worth a finding on their own. */
+export declare function looksLikePlaceholder(value: string): boolean;
+/** Decode a JWT payload without verifying it. Returns null when it is not a JWT. */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;

package/dist/scan/text.js

@@ -0,0 +1,58 @@
+/** Text helpers shared by rules: positions, redaction and entropy. */
+/** 1-based line and column for a character offset. */
+export function lineColumn(text, offset) {
+    let line = 1;
+    let lastBreak = -1;
+    for (let i = 0; i < offset && i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            line += 1;
+            lastBreak = i;
+        }
+    }
+    return { line, column: offset - lastBreak };
+}
+/**
+ * Redact a matched value so reports never reproduce the secret they found.
+ * Keeps enough of each end to recognise the value in the source.
+ */
+export function redact(value, keep = 4) {
+    if (value.length <= keep * 2 + 1)
+        return "*".repeat(value.length);
+    return `${value.slice(0, keep)}…${value.slice(-keep)} (${value.length} chars)`;
+}
+/** Shannon entropy in bits per character. ~4.5 is random base64, ~3 is prose. */
+export function shannonEntropy(value) {
+    if (value.length === 0)
+        return 0;
+    const counts = new Map();
+    for (const ch of value)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / value.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+const PLACEHOLDER = /^(x+|0+|\*+|your[_-]|changeme|placeholder|example|dummy|test|sample|<)/i;
+/** Values humans type as stand-ins; never worth a finding on their own. */
+export function looksLikePlaceholder(value) {
+    return PLACEHOLDER.test(value) || /^(.)\1+$/.test(value);
+}
+/** Decode a JWT payload without verifying it. Returns null when it is not a JWT. */
+export function decodeJwtPayload(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    const payload = parts[1];
+    if (payload === undefined)
+        return null;
+    try {
+        const json = Buffer.from(payload, "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        return typeof parsed === "object" && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

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