evershield 0.1.0 → 0.2.0

package/README.md

@@ -7,10 +7,9 @@
 **Shield everything, everywhere.** Find what your web app exposes to the
 browser before attackers do.
 
-> Status: pre-release. Layer 1 (built-artifact scan) and layer 2
-> (privilege-differential response audit) work today. Layer 3 is next;
-> follow the [roadmap](docs/design.md#roadmap) or open an issue to help
-> shape it.
+> Status: pre-release. All three layers work: built-artifact scan,
+> privilege-differential response audit, and rendered-surface audit. Follow
+> the [roadmap](docs/design.md#roadmap) or open an issue to help shape it.
 
 ## Why
 
@@ -96,9 +95,50 @@ names mark them as a higher tier's (`premium_*`, `pro_only`, `internal_*`),
 credential-like fields in any response, and endpoints that answer every
 identity identically. The audit only ever talks to `baseUrl`.
 
+## Find paywalls that only hide
+
+Layer 3 opens your pages in a headless browser as each identity and reports
+content that is in the page but hidden: blurred, `display: none`, clipped,
+or tucked into a `data-*` attribute, an inline script or `localStorage`.
+
+```json
+{
+  "surface": {
+    "baseUrl": "https://staging.example.com",
+    "tiers": ["free", "pro"],
+    "identities": {
+      "free": { "storageState": "${EVERSHIELD_FREE_STATE}" },
+      "pro":  { "storageState": "${EVERSHIELD_PRO_STATE}" }
+    },
+    "pages": [{ "path": "/report/demo" }]
+  }
+}
+```
+
+```bash
+npm install --save-dev playwright && npx playwright install chromium
+EVERSHIELD_FREE_STATE=free.json EVERSHIELD_PRO_STATE=pro.json npx evershield surface
+```
+
+The key rule compares tiers: text the Pro page shows that the Free page
+also contains, hidden, is a cosmetic paywall. Tabs and menus hidden for
+everyone never trigger it. See [the surface rules](docs/rules.md#layer-3-surface)
+and [configuration](docs/configuration.md#surface-layer-3).
+
 ## In CI
 
-The GitHub Action scans your build and uploads the result to the Security
+Fastest path: run this in your project root.
+
+```bash
+npx evershield init
+```
+
+It detects the framework (Next.js, Vite, Astro, SvelteKit, Nuxt, CRA), the
+build directory and package manager, and writes `evershield.config.json`
+and `.github/workflows/evershield.yml`. Existing files are left alone
+unless you pass `--force`.
+
+Or write the workflow yourself. The GitHub Action scans your build and uploads the result to the Security
 tab as code-scanning alerts:
 
 ```yaml
@@ -123,6 +163,18 @@ Inputs: `path` (required), `fail-on`, `min-confidence`, `config`, `adapter`,
 `sarif-file`, `upload-sarif`, `version`. The step fails when evershield
 exits 1 (blocking findings) or 2 (error), after the SARIF upload.
 
+## In Claude Code
+
+```
+/plugin marketplace add inviy/evershield
+/plugin install evershield@evershield
+```
+
+The plugin adds an `evershield` skill (Claude checks the server-side
+boundary whenever it touches response fields, plan branches, public env
+vars or `public/`) and an `/evershield` command that builds and scans the
+project.
+
 ## Allowlisting with a reason
 
 Known-safe matches go in `evershield.config.json`, each with a reason:

package/dist/cli.js

@@ -3,6 +3,8 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { runAudit } from "./audit/run.js";
 import { applyIgnores, ConfigError, loadConfig } from "./config.js";
+import { runInit } from "./init.js";
+import { runSurface } from "./surface/run.js";
 import { VERSION } from "./index.js";
 import { CONFIDENCES, DEFAULT_GATE, isBlocking, renderJson, renderText, SEVERITIES } from "./report/index.js";
 import { renderSarif } from "./report/sarif.js";
@@ -12,13 +14,18 @@ const HELP = `evershield ${VERSION}
 Shield everything, everywhere.
 
 Usage:
+  evershield init [--force]         Detect your framework and write evershield.config.json
+                                    and a GitHub workflow that scans every pull request
   evershield scan <dir> [options]   Layer 1: scan a built web artifact directory
   evershield audit [options]        Layer 2: call configured endpoints as each identity
                                     and compare what they receive (needs config "audit")
+  evershield surface [options]      Layer 3: open configured pages as each identity in a
+                                    headless browser and find content that is present but
+                                    hidden (needs config "surface" and Playwright)
   evershield --version              Print version
   evershield --help                 Show this help
 
-Options (both commands):
+Options (scan, audit, surface):
   --format <text|json|sarif>        Output format (default: text)
   --output <file>                   Write the report to a file; stdout gets a one-line summary
   --config <file>                   Config file (default: ./evershield.config.json if present)
@@ -116,7 +123,32 @@ export async function run(argv) {
     if (command === "--version" || command === "-v" || command === "version") {
         return { code: 0, stdout: `${VERSION}\n`, stderr: "" };
     }
-    if (command !== "scan" && command !== "audit") {
+    if (command === "init") {
+        const unknown = rest.filter((arg) => arg !== "--force");
+        if (unknown.length > 0)
+            return usageError(`init: unexpected argument "${unknown[0]}"`);
+        try {
+            const { detection, written, skipped } = await runInit(process.cwd(), { force: rest.includes("--force") });
+            const lines = [
+                `evershield init · detected ${detection.framework} · build output ${detection.buildDir} · ${detection.packageManager}`,
+                ...written.map((file) => `  created  ${file}`),
+                ...skipped.map((file) => `  skipped  ${file} (exists; use --force to overwrite)`),
+                "",
+                "Next:",
+                `  1. Build, then try it locally:  npx evershield scan ${detection.buildDir}`,
+                "  2. Commit the workflow; every pull request is scanned and findings appear in the Security tab.",
+                "  3. Known-safe matches go in evershield.config.json under \"ignore\", each with a reason.",
+            ];
+            if (detection.framework === "unknown") {
+                lines.push("", `Could not detect a framework; edit the build step and path in .github/workflows/evershield.yml.`);
+            }
+            return { code: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+        }
+        catch (error) {
+            return failure("init", error);
+        }
+    }
+    if (command !== "scan" && command !== "audit" && command !== "surface") {
         return usageError(`unknown command "${command}"`);
     }
     const options = parseCommonOptions(rest);
@@ -138,7 +170,27 @@ export async function run(argv) {
         }
     }
     if (options.positionals.length > 0)
-        return usageError(`audit: unexpected argument "${options.positionals[0]}"`);
+        return usageError(`${command}: unexpected argument "${options.positionals[0]}"`);
+    if (command === "surface") {
+        try {
+            const { config, source } = await loadConfig(options.configPath);
+            if (config.surface === undefined) {
+                throw new ConfigError(source === null
+                    ? "surface needs a config file with a \"surface\" block (see docs/configuration.md)"
+                    : `${source} has no "surface" block (see docs/configuration.md)`);
+            }
+            const gate = gateFor(options, config);
+            const surfaced = await runSurface(config.surface);
+            if (surfaced.snapshotsEvaluated === 0) {
+                throw new Error(`no page could be evaluated, so nothing was audited:\n  ${surfaced.warnings.join("\n  ")}`);
+            }
+            const { kept, ignored } = applyIgnores(surfaced.findings, config.ignore);
+            return await finish({ ...surfaced, findings: kept, ignored: ignored.length }, gate, options);
+        }
+        catch (error) {
+            return failure("surface", error);
+        }
+    }
     try {
         const { config, source } = await loadConfig(options.configPath);
         if (config.audit === undefined) {

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { AuditConfig } from "./audit/types.ts";
 import type { Finding } from "./index.ts";
+import type { SurfaceConfig } from "./surface/types.ts";
 import { type Gate } from "./report/index.ts";
 export interface IgnoreRule {
     /** Rule id to ignore, or "*" for any rule. */
@@ -16,6 +17,8 @@ export interface Config {
     ignore: IgnoreRule[];
     /** Layer 2 settings; `evershield audit` requires this block. */
     audit?: AuditConfig;
+    /** Layer 3 settings; `evershield surface` requires this block. */
+    surface?: SurfaceConfig;
 }
 export declare const DEFAULT_CONFIG_FILE = "evershield.config.json";
 export declare class ConfigError extends Error {

package/dist/config.js

@@ -72,6 +72,8 @@ export function parseConfig(raw, source) {
     }
     if (raw.audit !== undefined)
         config.audit = parseAuditConfig(raw.audit, `${source}: audit`);
+    if (raw.surface !== undefined)
+        config.surface = parseSurfaceConfig(raw.surface, `${source}: surface`);
     return config;
 }
 const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -90,9 +92,7 @@ function parseHeaders(raw, where) {
     }
     return headers;
 }
-function parseAuditConfig(raw, where) {
-    if (!isRecord(raw))
-        throw new ConfigError(`${where} must be an object`);
+function parseBaseUrl(raw, where) {
     if (typeof raw.baseUrl !== "string")
         throw new ConfigError(`${where}.baseUrl is required`);
     let base;
@@ -104,6 +104,30 @@ function parseAuditConfig(raw, where) {
     }
     if (base.protocol !== "http:" && base.protocol !== "https:")
         throw new ConfigError(`${where}.baseUrl must be http or https`);
+    return base;
+}
+function parseTiers(raw, where, identities) {
+    if (!Array.isArray(raw.tiers) || raw.tiers.length === 0 || !raw.tiers.every((tier) => typeof tier === "string")) {
+        throw new ConfigError(`${where}.tiers must list identity names from least to most privileged`);
+    }
+    const tiers = raw.tiers;
+    for (const tier of tiers) {
+        if (identities[tier] === undefined)
+            throw new ConfigError(`${where}.tiers names "${tier}" which is not in identities`);
+    }
+    return tiers;
+}
+function parseTimeout(raw, where) {
+    if (raw.timeoutMs === undefined)
+        return undefined;
+    if (typeof raw.timeoutMs !== "number" || raw.timeoutMs <= 0)
+        throw new ConfigError(`${where}.timeoutMs must be a positive number`);
+    return raw.timeoutMs;
+}
+function parseAuditConfig(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object`);
+    const base = parseBaseUrl(raw, where);
     if (!isRecord(raw.identities) || Object.keys(raw.identities).length === 0) {
         throw new ConfigError(`${where}.identities must define at least one identity`);
     }
@@ -116,14 +140,7 @@ function parseAuditConfig(raw, where) {
             identity.headers = parseHeaders(value.headers, `${where}.identities.${name}.headers`);
         identities[name] = identity;
     }
-    if (!Array.isArray(raw.tiers) || raw.tiers.length === 0 || !raw.tiers.every((tier) => typeof tier === "string")) {
-        throw new ConfigError(`${where}.tiers must list identity names from least to most privileged`);
-    }
-    const tiers = raw.tiers;
-    for (const tier of tiers) {
-        if (identities[tier] === undefined)
-            throw new ConfigError(`${where}.tiers names "${tier}" which is not in identities`);
-    }
+    const tiers = parseTiers(raw, where, identities);
     if (!Array.isArray(raw.endpoints) || raw.endpoints.length === 0)
         throw new ConfigError(`${where}.endpoints must list at least one endpoint`);
     const endpoints = raw.endpoints.map((entry, index) => {
@@ -164,13 +181,98 @@ function parseAuditConfig(raw, where) {
         return endpoint;
     });
     const audit = { baseUrl: base.origin, tiers, identities, endpoints };
-    if (raw.timeoutMs !== undefined) {
-        if (typeof raw.timeoutMs !== "number" || raw.timeoutMs <= 0)
-            throw new ConfigError(`${where}.timeoutMs must be a positive number`);
-        audit.timeoutMs = raw.timeoutMs;
-    }
+    const timeoutMs = parseTimeout(raw, where);
+    if (timeoutMs !== undefined)
+        audit.timeoutMs = timeoutMs;
     return audit;
 }
+const ENV_REF_PRESENT = /\$\{[A-Z_][A-Z0-9_]*\}/;
+function parseStringList(value, where) {
+    if (!(Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0))) {
+        throw new ConfigError(`${where} must be an array of non-empty strings`);
+    }
+    return value;
+}
+function parseSurfaceConfig(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object`);
+    const base = parseBaseUrl(raw, where);
+    if (!isRecord(raw.identities) || Object.keys(raw.identities).length === 0) {
+        throw new ConfigError(`${where}.identities must define at least one identity`);
+    }
+    const identities = {};
+    for (const [name, value] of Object.entries(raw.identities)) {
+        const at = `${where}.identities.${name}`;
+        if (!isRecord(value))
+            throw new ConfigError(`${at} must be an object`);
+        const identity = {};
+        if (value.headers !== undefined)
+            identity.headers = parseHeaders(value.headers, `${at}.headers`);
+        if (value.cookies !== undefined) {
+            if (!isRecord(value.cookies))
+                throw new ConfigError(`${at}.cookies must be an object of cookie name → value`);
+            identity.cookies = {};
+            for (const [cookie, cookieValue] of Object.entries(value.cookies)) {
+                if (typeof cookieValue !== "string" || !ENV_REF_PRESENT.test(cookieValue)) {
+                    throw new ConfigError(`${at}.cookies.${cookie} must reference an environment variable such as "\${EVERSHIELD_PRO_SESSION}"; literal credentials are not allowed in config`);
+                }
+                identity.cookies[cookie] = cookieValue;
+            }
+        }
+        if (value.storageState !== undefined) {
+            if (typeof value.storageState !== "string" || value.storageState.length === 0)
+                throw new ConfigError(`${at}.storageState must be a file path`);
+            identity.storageState = value.storageState;
+        }
+        identities[name] = identity;
+    }
+    const tiers = parseTiers(raw, where, identities);
+    if (!Array.isArray(raw.pages) || raw.pages.length === 0)
+        throw new ConfigError(`${where}.pages must list at least one page`);
+    const pages = raw.pages.map((entry, index) => {
+        const at = `${where}.pages[${index}]`;
+        if (!isRecord(entry))
+            throw new ConfigError(`${at} must be an object`);
+        if (typeof entry.path !== "string" || !entry.path.startsWith("/"))
+            throw new ConfigError(`${at}.path must start with "/" (relative to baseUrl)`);
+        const page = { path: entry.path };
+        if (entry.waitFor !== undefined) {
+            if (typeof entry.waitFor !== "string" || entry.waitFor.length === 0)
+                throw new ConfigError(`${at}.waitFor must be a CSS selector`);
+            page.waitFor = entry.waitFor;
+        }
+        if (entry.expect !== undefined) {
+            if (!isRecord(entry.expect))
+                throw new ConfigError(`${at}.expect must be an object keyed by identity`);
+            page.expect = {};
+            for (const [identity, expectation] of Object.entries(entry.expect)) {
+                if (identities[identity] === undefined)
+                    throw new ConfigError(`${at}.expect.${identity} is not a defined identity`);
+                if (!isRecord(expectation))
+                    throw new ConfigError(`${at}.expect.${identity} must be an object`);
+                const parsed = {};
+                if (expectation.absentText !== undefined)
+                    parsed.absentText = parseStringList(expectation.absentText, `${at}.expect.${identity}.absentText`);
+                if (expectation.absentSelectors !== undefined) {
+                    parsed.absentSelectors = parseStringList(expectation.absentSelectors, `${at}.expect.${identity}.absentSelectors`);
+                }
+                page.expect[identity] = parsed;
+            }
+        }
+        return page;
+    });
+    const surface = { baseUrl: base.origin, tiers, identities, pages };
+    const timeoutMs = parseTimeout(raw, where);
+    if (timeoutMs !== undefined)
+        surface.timeoutMs = timeoutMs;
+    if (raw.minTextLength !== undefined) {
+        if (typeof raw.minTextLength !== "number" || !Number.isInteger(raw.minTextLength) || raw.minTextLength < 4) {
+            throw new ConfigError(`${where}.minTextLength must be an integer of at least 4`);
+        }
+        surface.minTextLength = raw.minTextLength;
+    }
+    return surface;
+}
 /**
  * Load the config file. An explicit path must exist; the default file is
  * optional. Returns the source path alongside, for messages.
@@ -226,8 +328,9 @@ function matches(rule, finding) {
     const first = finding.evidence[0];
     if (rule.path !== undefined) {
         // For file evidence the glob matches the file path; for response
-        // evidence it matches "METHOD /path" so one entry can cover an endpoint.
-        const subject = first?.kind === "file" ? first.path : first?.kind === "response" ? first.endpoint : undefined;
+        // evidence it matches "METHOD /path" so one entry can cover an endpoint;
+        // DOM evidence matches the page path.
+        const subject = first?.kind === "file" ? first.path : first?.kind === "response" ? first.endpoint : first?.kind === "dom" ? new URL(first.url).pathname : undefined;
         if (subject === undefined || !globToRegExp(rule.path).test(subject))
             return false;
     }

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * every layer reports in, so CLI, GitHub Action and MCP surfaces can share
  * one finding model from day one. See docs/design.md for the rationale.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 /** How sure evershield is that a finding is real. Drives exit codes and CI gating. */
 export type Confidence = "high" | "medium" | "low";
 /** How bad it is if the finding is real. */
@@ -29,6 +29,7 @@ export type Evidence = {
     kind: "dom";
     url: string;
     selector: string;
+    identity?: string;
     excerpt?: string;
 };
 export interface Finding {

package/dist/index.js

@@ -5,4 +5,4 @@
  * every layer reports in, so CLI, GitHub Action and MCP surfaces can share
  * one finding model from day one. See docs/design.md for the rationale.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";

package/dist/init.d.ts

@@ -0,0 +1,21 @@
+export interface Detection {
+    framework: "nextjs" | "vite" | "astro" | "create-react-app" | "nuxt" | "sveltekit" | "unknown";
+    /** Build output directory relative to the project root. */
+    buildDir: string;
+    packageManager: "pnpm" | "yarn" | "bun" | "npm";
+    /** Shell command that produces the build directory. */
+    buildCommand: string;
+    /** package.json pins a version in "packageManager"; pnpm/action-setup fails without it unless told one. */
+    packageManagerPinned?: boolean;
+}
+export declare function detectProject(root: string): Promise<Detection>;
+export declare function renderWorkflow(detection: Detection): string;
+export declare function renderConfig(): string;
+export interface InitResult {
+    detection: Detection;
+    written: string[];
+    skipped: string[];
+}
+export declare function runInit(root: string, options?: {
+    force?: boolean;
+}): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,136 @@
+/**
+ * `evershield init`: turn a one-off scan into a check that runs on every
+ * pull request. Detects the framework and build directory, then writes
+ * `evershield.config.json` and `.github/workflows/evershield.yml`.
+ *
+ * Existing files are never overwritten unless `--force` is given; init
+ * reports what it skipped instead.
+ */
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+async function exists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function anyExists(root, names) {
+    for (const name of names)
+        if (await exists(path.join(root, name)))
+            return true;
+    return false;
+}
+export async function detectProject(root) {
+    let pkg = {};
+    try {
+        pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    }
+    catch {
+        // Not a Node project, or no package.json: fall through to defaults.
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const has = (name) => deps[name] !== undefined;
+    let framework = "unknown";
+    let buildDir = "dist";
+    if (has("next") || (await anyExists(root, ["next.config.js", "next.config.mjs", "next.config.ts"]))) {
+        framework = "nextjs";
+        buildDir = ".next";
+    }
+    else if (has("nuxt")) {
+        framework = "nuxt";
+        buildDir = ".output/public";
+    }
+    else if (has("@sveltejs/kit")) {
+        framework = "sveltekit";
+        buildDir = "build";
+    }
+    else if (has("astro")) {
+        framework = "astro";
+        buildDir = "dist";
+    }
+    else if (has("react-scripts")) {
+        framework = "create-react-app";
+        buildDir = "build";
+    }
+    else if (has("vite")) {
+        framework = "vite";
+        buildDir = "dist";
+    }
+    let packageManager = "npm";
+    if (await exists(path.join(root, "pnpm-lock.yaml")))
+        packageManager = "pnpm";
+    else if (await exists(path.join(root, "yarn.lock")))
+        packageManager = "yarn";
+    else if (await anyExists(root, ["bun.lockb", "bun.lock"]))
+        packageManager = "bun";
+    const run = packageManager === "npm" ? "npm run" : packageManager;
+    const buildCommand = pkg.scripts?.build !== undefined ? `${run} build` : "echo 'set your build command here' && exit 1";
+    return { framework, buildDir, packageManager, buildCommand, packageManagerPinned: typeof pkg.packageManager === "string" };
+}
+const INSTALL = {
+    npm: "npm ci",
+    pnpm: "pnpm install --frozen-lockfile",
+    yarn: "yarn install --frozen-lockfile",
+    bun: "bun install --frozen-lockfile",
+};
+export function renderWorkflow(detection) {
+    const setup = detection.packageManager === "pnpm"
+        ? `      - uses: pnpm/action-setup@v4\n${detection.packageManagerPinned === true ? "" : "        with:\n          version: 10\n"}      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n          cache: pnpm\n`
+        : detection.packageManager === "bun"
+            ? "      - uses: oven-sh/setup-bun@v2\n"
+            : `      - uses: actions/setup-node@v4\n        with:\n          node-version: 22\n          cache: ${detection.packageManager}\n`;
+    return `name: evershield
+
+# Scans what your app ships to the browser on every pull request and
+# reports findings in the Security tab. Generated by \`evershield init\`.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+${setup}      - run: ${INSTALL[detection.packageManager]}
+      - run: ${detection.buildCommand}
+      - uses: inviy/evershield@v0
+        with:
+          path: ${detection.buildDir}
+`;
+}
+export function renderConfig() {
+    return `${JSON.stringify({
+        gate: { failOn: "high", minConfidence: "medium" },
+        ignore: [],
+    }, null, 2)}\n`;
+}
+export async function runInit(root, options = {}) {
+    const detection = await detectProject(root);
+    const files = [
+        ["evershield.config.json", renderConfig()],
+        [".github/workflows/evershield.yml", renderWorkflow(detection)],
+    ];
+    const written = [];
+    const skipped = [];
+    for (const [relative, content] of files) {
+        const target = path.join(root, relative);
+        if (!options.force && (await exists(target))) {
+            skipped.push(relative);
+            continue;
+        }
+        await mkdir(path.dirname(target), { recursive: true });
+        await writeFile(target, content);
+        written.push(relative);
+    }
+    return { detection, written, skipped };
+}

package/dist/report/index.d.ts

@@ -1,9 +1,10 @@
 import type { AuditResult } from "../audit/run.ts";
 import type { Confidence, Finding, Severity } from "../index.ts";
 import type { ArtifactScanResult } from "../scan/artifact.ts";
+import type { SurfaceResult } from "../surface/run.ts";
 export type Format = "text" | "json" | "sarif";
 /** Any layer's result. Renderers switch on `layer` for the header only. */
-export type Report = ArtifactScanResult | AuditResult;
+export type Report = ArtifactScanResult | AuditResult | SurfaceResult;
 export declare const SEVERITIES: readonly Severity[];
 export declare const CONFIDENCES: readonly Confidence[];
 export interface Gate {

package/dist/report/index.js

@@ -17,7 +17,7 @@ function location(finding) {
     }
     if (first.kind === "response")
         return `${first.endpoint} as ${first.identity} → ${first.jsonPath}`;
-    return `${first.url} ${first.selector}`;
+    return `${first.url}${first.identity === undefined ? "" : ` as ${first.identity}`} → ${first.selector}`;
 }
 function header(result) {
     if (result.layer === "artifact") {
@@ -26,6 +26,12 @@ function header(result) {
             `target: ${result.target}`,
         ];
     }
+    if (result.layer === "surface") {
+        return [
+            `evershield ${result.version} · surface audit · ${result.pagesAudited} page(s) × ${result.identities.length} identities (${result.identities.join(" < ")}) · ${result.snapshotsEvaluated} page loads evaluated`,
+            `target: ${result.target}`,
+        ];
+    }
     return [
         `evershield ${result.version} · response audit · ${result.endpointsAudited} endpoint(s) × ${result.identities.length} identities (${result.identities.join(" < ")}) · ${result.responsesEvaluated} responses evaluated`,
         `target: ${result.target}`,
@@ -33,14 +39,18 @@ function header(result) {
 }
 export function renderText(result, gate) {
     const lines = [...header(result), ""];
-    if (result.layer === "response" && result.warnings.length > 0) {
+    if (result.layer !== "artifact" && result.warnings.length > 0) {
         for (const warning of result.warnings)
             lines.push(`! ${warning}`);
         lines.push("");
     }
     const ignoredNote = result.ignored > 0 ? ` ${result.ignored} finding(s) ignored by config.` : "";
     if (result.findings.length === 0) {
-        const what = result.layer === "artifact" ? "Nothing in the shipped files matched a rule." : "Every identity received only what it should.";
+        const what = result.layer === "artifact"
+            ? "Nothing in the shipped files matched a rule."
+            : result.layer === "surface"
+                ? "No identity's page held content it could not see."
+                : "Every identity received only what it should.";
         lines.push(`No findings. ${what}${ignoredNote}`);
         return `${lines.join("\n")}\n`;
     }

package/dist/report/sarif.js

@@ -6,11 +6,12 @@
  * File paths are relative to the scanned directory, not the repository
  * root, because build output is usually not committed. Response evidence
  * has no file, so it is reported as a logical location (endpoint, identity
- * and JSON path).
+ * and JSON path); DOM evidence likewise (page, identity and selector).
  */
 import { RESPONSE_RULES } from "../audit/rules.js";
 import { VERSION } from "../index.js";
 import { ARTIFACT_RULES } from "../rules/index.js";
+import { SURFACE_RULES } from "../surface/rules.js";
 import { helpUri } from "../rules/types.js";
 import { isBlocking } from "./index.js";
 function levelFor(severity) {
@@ -41,16 +42,29 @@ function locations(finding) {
             },
         ];
     }
-    return [{ logicalLocations: [{ name: first.selector, fullyQualifiedName: `${first.url} ${first.selector}`, kind: "element" }] }];
+    const as = first.identity === undefined ? "" : ` as ${first.identity}`;
+    return [{ logicalLocations: [{ name: first.selector, fullyQualifiedName: `${first.url}${as} → ${first.selector}`, kind: "element" }] }];
 }
 const KNOWN_RULES = new Map([
     ...ARTIFACT_RULES.map((rule) => [rule.id, rule]),
     ...RESPONSE_RULES.map((rule) => [rule.id, rule]),
+    ...SURFACE_RULES.map((rule) => [rule.id, rule]),
 ]);
 function invocationProperties(result, gate) {
     if (result.layer === "artifact") {
         return { layer: result.layer, adapter: result.adapter, filesScanned: result.filesScanned, ignored: result.ignored, gate };
     }
+    if (result.layer === "surface") {
+        return {
+            layer: result.layer,
+            identities: result.identities,
+            pagesAudited: result.pagesAudited,
+            snapshotsEvaluated: result.snapshotsEvaluated,
+            warnings: result.warnings,
+            ignored: result.ignored,
+            gate,
+        };
+    }
     return {
         layer: result.layer,
         identities: result.identities,