evershield 0.0.0-stage → 0.2.0

package/dist/config.js

@@ -0,0 +1,352 @@
+/**
+ * evershield.config.json
+ *
+ * {
+ *   "gate": { "failOn": "high", "minConfidence": "medium" },
+ *   "ignore": [
+ *     { "ruleId": "artifact/internal-endpoint", "match": "localhost:9999",
+ *       "reason": "supabase-js bundles this default; unreachable in production" }
+ *   ]
+ * }
+ *
+ * Every ignore needs a reason. An allowlist without reasons rots into a
+ * list nobody dares to delete; with reasons it is documentation.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { CONFIDENCES, SEVERITIES } from "./report/index.js";
+export const DEFAULT_CONFIG_FILE = "evershield.config.json";
+export class ConfigError extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Validate a parsed JSON value into a Config, with messages a human can act on. */
+export function parseConfig(raw, source) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${source}: expected a JSON object`);
+    const config = { ignore: [] };
+    if (raw.gate !== undefined) {
+        if (!isRecord(raw.gate))
+            throw new ConfigError(`${source}: "gate" must be an object`);
+        const gate = {};
+        if (raw.gate.failOn !== undefined) {
+            const failOn = raw.gate.failOn;
+            if (typeof failOn !== "string" || !(failOn === "none" || SEVERITIES.includes(failOn))) {
+                throw new ConfigError(`${source}: "gate.failOn" must be one of ${[...SEVERITIES, "none"].join(", ")}`);
+            }
+            gate.failOn = failOn;
+        }
+        if (raw.gate.minConfidence !== undefined) {
+            const minConfidence = raw.gate.minConfidence;
+            if (typeof minConfidence !== "string" || !CONFIDENCES.includes(minConfidence)) {
+                throw new ConfigError(`${source}: "gate.minConfidence" must be one of ${CONFIDENCES.join(", ")}`);
+            }
+            gate.minConfidence = minConfidence;
+        }
+        config.gate = gate;
+    }
+    if (raw.ignore !== undefined) {
+        if (!Array.isArray(raw.ignore))
+            throw new ConfigError(`${source}: "ignore" must be an array`);
+        raw.ignore.forEach((entry, index) => {
+            const where = `${source}: ignore[${index}]`;
+            if (!isRecord(entry))
+                throw new ConfigError(`${where} must be an object`);
+            if (typeof entry.ruleId !== "string" || entry.ruleId.length === 0)
+                throw new ConfigError(`${where}.ruleId is required`);
+            if (typeof entry.reason !== "string" || entry.reason.trim().length === 0) {
+                throw new ConfigError(`${where}.reason is required: say why this finding is safe to ignore`);
+            }
+            if (entry.path !== undefined && typeof entry.path !== "string")
+                throw new ConfigError(`${where}.path must be a string`);
+            if (entry.match !== undefined && typeof entry.match !== "string")
+                throw new ConfigError(`${where}.match must be a string`);
+            const rule = { ruleId: entry.ruleId, reason: entry.reason };
+            if (typeof entry.path === "string")
+                rule.path = entry.path;
+            if (typeof entry.match === "string")
+                rule.match = entry.match;
+            config.ignore.push(rule);
+        });
+    }
+    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"];
+const CREDENTIAL_HEADERS = new Set(["authorization", "cookie", "x-api-key", "api-key", "x-auth-token"]);
+function parseHeaders(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object of header name → value`);
+    const headers = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (typeof value !== "string")
+            throw new ConfigError(`${where}.${name} must be a string`);
+        if (CREDENTIAL_HEADERS.has(name.toLowerCase()) && !/\$\{[A-Z_][A-Z0-9_]*\}/.test(value)) {
+            throw new ConfigError(`${where}.${name} must reference an environment variable such as "Bearer \${EVERSHIELD_PRO_TOKEN}"; literal credentials are not allowed in config`);
+        }
+        headers[name] = value;
+    }
+    return headers;
+}
+function parseBaseUrl(raw, where) {
+    if (typeof raw.baseUrl !== "string")
+        throw new ConfigError(`${where}.baseUrl is required`);
+    let base;
+    try {
+        base = new URL(raw.baseUrl);
+    }
+    catch {
+        throw new ConfigError(`${where}.baseUrl is not a valid URL`);
+    }
+    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`);
+    }
+    const identities = {};
+    for (const [name, value] of Object.entries(raw.identities)) {
+        if (!isRecord(value))
+            throw new ConfigError(`${where}.identities.${name} must be an object`);
+        const identity = {};
+        if (value.headers !== undefined)
+            identity.headers = parseHeaders(value.headers, `${where}.identities.${name}.headers`);
+        identities[name] = identity;
+    }
+    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) => {
+        const at = `${where}.endpoints[${index}]`;
+        if (!isRecord(entry))
+            throw new ConfigError(`${at} must be an object`);
+        const method = (typeof entry.method === "string" ? entry.method : "GET").toUpperCase();
+        if (!METHODS.includes(method))
+            throw new ConfigError(`${at}.method must be one of ${METHODS.join(", ")}`);
+        if (typeof entry.path !== "string" || !entry.path.startsWith("/"))
+            throw new ConfigError(`${at}.path must start with "/" (relative to baseUrl)`);
+        const endpoint = { method: method, path: entry.path };
+        if (entry.headers !== undefined)
+            endpoint.headers = parseHeaders(entry.headers, `${at}.headers`);
+        if (entry.body !== undefined)
+            endpoint.body = entry.body;
+        if (entry.tiered !== undefined) {
+            if (typeof entry.tiered !== "boolean")
+                throw new ConfigError(`${at}.tiered must be a boolean`);
+            endpoint.tiered = entry.tiered;
+        }
+        if (entry.expect !== undefined) {
+            if (!isRecord(entry.expect))
+                throw new ConfigError(`${at}.expect must be an object keyed by identity`);
+            endpoint.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 absent = expectation.absent;
+                if (absent !== undefined && !(Array.isArray(absent) && absent.every((path) => typeof path === "string" && path.length > 0))) {
+                    throw new ConfigError(`${at}.expect.${identity}.absent must be an array of JSON paths`);
+                }
+                endpoint.expect[identity] = absent === undefined ? {} : { absent: absent };
+            }
+        }
+        return endpoint;
+    });
+    const audit = { baseUrl: base.origin, tiers, identities, endpoints };
+    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.
+ */
+export async function loadConfig(explicitPath) {
+    const filePath = path.resolve(explicitPath ?? DEFAULT_CONFIG_FILE);
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" && explicitPath === undefined)
+            return { config: { ignore: [] }, source: null };
+        throw new ConfigError(`cannot read config ${filePath}: ${code ?? String(error)}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError(`${filePath}: invalid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return { config: parseConfig(raw, filePath), source: filePath };
+}
+/** Minimal glob: `**` spans directories, `*` and `?` stay within one segment. */
+export function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                const slashFollows = pattern[i + 2] === "/";
+                out += slashFollows ? "(?:.*/)?" : ".*";
+                i += slashFollows ? 2 : 1;
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            out += "[^/]";
+        }
+        else {
+            out += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+function matches(rule, finding) {
+    if (rule.ruleId !== "*" && rule.ruleId !== finding.ruleId)
+        return false;
+    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;
+        // 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;
+    }
+    if (rule.match !== undefined) {
+        const haystack = `${finding.message}\n${first?.excerpt ?? ""}`;
+        if (!haystack.includes(rule.match))
+            return false;
+    }
+    return true;
+}
+/** Split findings into those kept and those an ignore rule accounts for. */
+export function applyIgnores(findings, ignore) {
+    const kept = [];
+    const ignored = [];
+    for (const finding of findings) {
+        (ignore.some((rule) => matches(rule, finding)) ? ignored : kept).push(finding);
+    }
+    return { kept, ignored };
+}

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * evershield public API.
+ *
+ * The scanner itself lands in later releases; this module fixes the shapes
+ * 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.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. */
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+/** Which analysis layer produced the finding. */
+export type Layer = "artifact" | "response" | "surface";
+/** Where in the shipped output the evidence was observed. */
+export type Evidence = {
+    kind: "file";
+    path: string;
+    line?: number;
+    column?: number;
+    excerpt?: string;
+} | {
+    kind: "response";
+    endpoint: string;
+    identity: string;
+    jsonPath: string;
+    excerpt?: string;
+} | {
+    kind: "dom";
+    url: string;
+    selector: string;
+    identity?: string;
+    excerpt?: string;
+};
+export interface Finding {
+    /** Stable rule identifier, e.g. "artifact/secret-like-string". */
+    ruleId: string;
+    layer: Layer;
+    severity: Severity;
+    confidence: Confidence;
+    /** One sentence a developer can act on without opening docs. */
+    message: string;
+    evidence: Evidence[];
+    /** Concrete fix, phrased for the person who will apply it. */
+    remediation?: string;
+    /** Rule documentation URL. */
+    helpUri?: string;
+}
+export interface ScanSummary {
+    version: string;
+    startedAt: string;
+    finishedAt: string;
+    findings: Finding[];
+}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * evershield public API.
+ *
+ * The scanner itself lands in later releases; this module fixes the shapes
+ * 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.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

@@ -0,0 +1,19 @@
+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 | SurfaceResult;
+export declare const SEVERITIES: readonly Severity[];
+export declare const CONFIDENCES: readonly Confidence[];
+export interface Gate {
+    /** Findings at this severity or worse can fail the build. "none" never fails. */
+    failOn: Severity | "none";
+    /** Findings below this confidence never fail the build, whatever their severity. */
+    minConfidence: Confidence;
+}
+export declare const DEFAULT_GATE: Gate;
+export declare function isBlocking(finding: Finding, gate: Gate): boolean;
+export declare function renderText(result: Report, gate: Gate): string;
+export declare function renderJson(result: Report, gate: Gate): string;

package/dist/report/index.js

@@ -0,0 +1,82 @@
+export const SEVERITIES = ["critical", "high", "medium", "low", "info"];
+export const CONFIDENCES = ["high", "medium", "low"];
+export const DEFAULT_GATE = { failOn: "high", minConfidence: "medium" };
+export function isBlocking(finding, gate) {
+    if (gate.failOn === "none")
+        return false;
+    const severeEnough = SEVERITIES.indexOf(finding.severity) <= SEVERITIES.indexOf(gate.failOn);
+    const sureEnough = CONFIDENCES.indexOf(finding.confidence) <= CONFIDENCES.indexOf(gate.minConfidence);
+    return severeEnough && sureEnough;
+}
+function location(finding) {
+    const first = finding.evidence[0];
+    if (first === undefined)
+        return "";
+    if (first.kind === "file") {
+        return first.line === undefined ? first.path : `${first.path}:${first.line}:${first.column ?? 1}`;
+    }
+    if (first.kind === "response")
+        return `${first.endpoint} as ${first.identity} → ${first.jsonPath}`;
+    return `${first.url}${first.identity === undefined ? "" : ` as ${first.identity}`} → ${first.selector}`;
+}
+function header(result) {
+    if (result.layer === "artifact") {
+        return [
+            `evershield ${result.version} · artifact scan · ${result.adapter} adapter · ${result.filesScanned} files`,
+            `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}`,
+    ];
+}
+export function renderText(result, gate) {
+    const lines = [...header(result), ""];
+    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."
+            : 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`;
+    }
+    let blocking = 0;
+    for (const finding of result.findings) {
+        const blocks = isBlocking(finding, gate);
+        if (blocks)
+            blocking += 1;
+        const marker = blocks ? "✖" : "•";
+        lines.push(`${marker} [${finding.severity}/${finding.confidence}] ${finding.message}`);
+        lines.push(`    at ${location(finding)}`);
+        const first = finding.evidence[0];
+        const excerpt = first?.excerpt;
+        if (excerpt !== undefined && first !== undefined && (first.kind !== "file" || first.line !== undefined)) {
+            lines.push(`    evidence: ${excerpt}`);
+        }
+        if (finding.remediation !== undefined)
+            lines.push(`    fix: ${finding.remediation}`);
+        lines.push(`    rule: ${finding.ruleId}`);
+        lines.push("");
+    }
+    const gateText = gate.failOn === "none" ? "gate disabled" : `gate: severity ≥ ${gate.failOn}, confidence ≥ ${gate.minConfidence}`;
+    lines.push(`${result.findings.length} finding(s), ${blocking} blocking (${gateText}).${ignoredNote}`);
+    return `${lines.join("\n")}\n`;
+}
+export function renderJson(result, gate) {
+    const blocking = result.findings.filter((finding) => isBlocking(finding, gate)).length;
+    return `${JSON.stringify({ ...result, gate, blocking }, null, 2)}\n`;
+}

package/dist/report/sarif.d.ts

@@ -0,0 +1,2 @@
+import { type Gate, type Report } from "./index.ts";
+export declare function renderSarif(result: Report, gate: Gate): string;