evershield 0.0.0-stage → 0.2.0

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,6 +1,75 @@
 {
   "name": "evershield",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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": {
+    "type": "git",
+    "url": "git+https://github.com/inviy/evershield.git"
+  },
+  "homepage": "https://github.com/inviy/evershield#readme",
+  "bugs": {
+    "url": "https://github.com/inviy/evershield/issues"
+  },
+  "keywords": [
+    "security",
+    "exposure",
+    "client-side",
+    "bundle",
+    "sourcemap",
+    "secrets",
+    "authorization",
+    "paywall",
+    "static-analysis",
+    "sarif",
+    "ci",
+    "devsecops",
+    "playwright",
+    "dom"
+  ],
+  "type": "module",
+  "bin": {
+    "evershield": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "packageManager": "pnpm@10.28.0",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test \"src/**/*.test.ts\"",
+    "check": "pnpm typecheck && pnpm test && pnpm build",
+    "prepublishOnly": "pnpm check"
+  },
+  "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
+    }
+  }
+}