evershield 0.1.0 → 0.3.0

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,154 @@
+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, or a label next to a mask ("Burstiness score ●●●●"), which is
+ * the fix this rule recommends.
+ */
+const PLACEHOLDER = /^(?:[\sxX*•●▒█#?·._,\-–—0]+|lorem ipsum.*|(.)\1+)$|[•●▒█*#]{3,}|\b[xX]{4,}\b/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 {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "evershield",
-  "version": "0.1.0",
-  "description": "Shield everything, everywhere: find what your web app exposes to the browser before attackers do",
+  "version": "0.3.0",
+  "description": "Shield everything, everywhere: find what your web app exposes to the browser, in bundles, API responses and the rendered page",
   "license": "MIT",
   "author": "Lee Dongwook (@inviy)",
   "repository": {
@@ -24,7 +24,9 @@
     "static-analysis",
     "sarif",
     "ci",
-    "devsecops"
+    "devsecops",
+    "playwright",
+    "dom"
   ],
   "type": "module",
   "bin": {
@@ -47,13 +49,28 @@
   "packageManager": "pnpm@10.28.0",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
     "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
     "check": "pnpm typecheck && pnpm test && pnpm build",
-    "prepublishOnly": "pnpm check"
+    "prepublishOnly": "pnpm check",
+    "corpus": "node --experimental-strip-types scripts/corpus.ts"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
+    "playwright": "1.56.1",
+    "playwright-core": "1.56.1",
     "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0",
+    "playwright-core": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
   }
 }