evershield 0.0.0-stage → 0.1.0

package/dist/audit/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Layer 2: privilege-differential response audit.
+ *
+ * The operator declares identities (anonymous, free, pro, admin, …) whose
+ * credentials live in environment variables, an ordered list of tiers from
+ * least to most privileged, and endpoints to call as each identity. The
+ * audit compares what each identity receives and reports fields that a
+ * lower tier should not have.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface IdentityConfig {
+    /** Header values may reference env vars as `${NAME}`; credential headers must. */
+    headers?: Record<string, string>;
+}
+export interface EndpointExpectation {
+    /** JSON paths (dot notation, `[]` for arrays) that must be absent or null for this identity. */
+    absent?: string[];
+}
+export interface EndpointConfig {
+    method: HttpMethod;
+    /** Path relative to `baseUrl`, starting with `/`. */
+    path: string;
+    headers?: Record<string, string>;
+    /** JSON body for POST/PUT/PATCH. String values may reference env vars. */
+    body?: unknown;
+    /** The endpoint is supposed to answer differently per tier. */
+    tiered?: boolean;
+    /** Per-identity expectations, keyed by identity name. */
+    expect?: Record<string, EndpointExpectation>;
+}
+export interface AuditConfig {
+    /** Origin the audit is allowed to talk to. Endpoints are relative to it. */
+    baseUrl: string;
+    /** Identity names ordered from least to most privileged. */
+    tiers: string[];
+    identities: Record<string, IdentityConfig>;
+    endpoints: EndpointConfig[];
+    timeoutMs?: number;
+}
+export interface ResponseObservation {
+    identity: string;
+    status: number;
+    contentType: string | null;
+    /** Parsed JSON body, or undefined when the body was not JSON. */
+    json: unknown;
+    isJson: boolean;
+    /** Transport-level failure, when the request did not complete. */
+    error?: string;
+}
+export interface EndpointObservation {
+    endpoint: EndpointConfig;
+    /** "POST /api/analyze" */
+    label: string;
+    /** Identity names, least privileged first. */
+    tiers: string[];
+    responses: Map<string, ResponseObservation>;
+}

package/dist/audit/types.js

@@ -0,0 +1,10 @@
+/**
+ * Layer 2: privilege-differential response audit.
+ *
+ * The operator declares identities (anonymous, free, pro, admin, …) whose
+ * credentials live in environment variables, an ordered list of tiers from
+ * least to most privileged, and endpoints to call as each identity. The
+ * audit compares what each identity receives and reports fields that a
+ * lower tier should not have.
+ */
+export {};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+const result = await run(process.argv.slice(2));
+if (result.stdout)
+    process.stdout.write(result.stdout);
+if (result.stderr)
+    process.stderr.write(result.stderr);
+process.exitCode = result.code;

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+export interface CliResult {
+    /** Process exit code. 0 clean, 1 blocking findings, 2 usage or runtime error. */
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Entry point without process side effects beyond the optional --output
+ * file: takes argv (minus node and the script path), returns what to print
+ * and the exit code.
+ */
+export declare function run(argv: readonly string[]): Promise<CliResult>;

package/dist/cli.js

@@ -0,0 +1,161 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { runAudit } from "./audit/run.js";
+import { applyIgnores, ConfigError, loadConfig } from "./config.js";
+import { VERSION } from "./index.js";
+import { CONFIDENCES, DEFAULT_GATE, isBlocking, renderJson, renderText, SEVERITIES } from "./report/index.js";
+import { renderSarif } from "./report/sarif.js";
+import { scanArtifact } from "./scan/artifact.js";
+import { ADAPTERS } from "./scan/adapters.js";
+const HELP = `evershield ${VERSION}
+Shield everything, everywhere.
+
+Usage:
+  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 --version              Print version
+  evershield --help                 Show this help
+
+Options (both commands):
+  --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)
+  --fail-on <severity|none>         Fail on findings at this severity or worse
+                                    (critical|high|medium|low|info|none; default: high)
+  --min-confidence <level>          Findings below this confidence never fail the build
+                                    (high|medium|low; default: medium)
+
+Scan options:
+  --adapter <nextjs|plain>          Force an adapter instead of detecting one
+
+Exit codes: 0 clean · 1 blocking findings · 2 usage or runtime error
+Documentation: https://github.com/inviy/evershield
+`;
+function usageError(message) {
+    return { code: 2, stdout: "", stderr: `evershield: ${message}\n\n${HELP}` };
+}
+function isOneOf(value, allowed) {
+    return allowed.includes(value);
+}
+function parseCommonOptions(rest) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...rest],
+            allowPositionals: true,
+            options: {
+                format: { type: "string", default: "text" },
+                output: { type: "string" },
+                config: { type: "string" },
+                "fail-on": { type: "string" },
+                "min-confidence": { type: "string" },
+                adapter: { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        return usageError(error instanceof Error ? error.message : String(error));
+    }
+    const format = String(parsed.values.format);
+    if (!isOneOf(format, ["text", "json", "sarif"]))
+        return usageError(`unknown --format "${format}"`);
+    const failOn = parsed.values["fail-on"] === undefined ? undefined : String(parsed.values["fail-on"]);
+    if (failOn !== undefined && !isOneOf(failOn, [...SEVERITIES, "none"]))
+        return usageError(`unknown --fail-on "${failOn}"`);
+    const minConfidence = parsed.values["min-confidence"] === undefined ? undefined : String(parsed.values["min-confidence"]);
+    if (minConfidence !== undefined && !isOneOf(minConfidence, CONFIDENCES))
+        return usageError(`unknown --min-confidence "${minConfidence}"`);
+    const adapter = parsed.values.adapter === undefined ? undefined : String(parsed.values.adapter);
+    if (adapter !== undefined && !isOneOf(adapter, Object.keys(ADAPTERS))) {
+        return usageError(`unknown --adapter "${adapter}"`);
+    }
+    return {
+        positionals: parsed.positionals,
+        format,
+        outputPath: parsed.values.output === undefined ? undefined : String(parsed.values.output),
+        configPath: parsed.values.config === undefined ? undefined : String(parsed.values.config),
+        failOn,
+        minConfidence,
+        adapter,
+    };
+}
+function gateFor(options, config) {
+    // Precedence: CLI flag, then config file, then defaults.
+    return {
+        failOn: options.failOn ?? config.gate?.failOn ?? DEFAULT_GATE.failOn,
+        minConfidence: options.minConfidence ?? config.gate?.minConfidence ?? DEFAULT_GATE.minConfidence,
+    };
+}
+async function finish(report, gate, options) {
+    const blocking = report.findings.filter((finding) => isBlocking(finding, gate)).length;
+    const rendered = options.format === "json" ? renderJson(report, gate) : options.format === "sarif" ? renderSarif(report, gate) : renderText(report, gate);
+    const code = blocking > 0 ? 1 : 0;
+    if (options.outputPath === undefined)
+        return { code, stdout: rendered, stderr: "" };
+    await writeFile(path.resolve(options.outputPath), rendered);
+    const summary = `evershield: ${report.findings.length} finding(s), ${blocking} blocking, ${report.ignored} ignored · ${options.format} report written to ${options.outputPath}\n`;
+    return { code, stdout: summary, stderr: "" };
+}
+function failure(command, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const prefix = error instanceof ConfigError ? "evershield config" : `evershield ${command}`;
+    return { code: 2, stdout: "", stderr: `${prefix}: ${message}\n` };
+}
+/**
+ * Entry point without process side effects beyond the optional --output
+ * file: takes argv (minus node and the script path), returns what to print
+ * and the exit code.
+ */
+export async function run(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "--help" || command === "-h" || command === "help") {
+        return { code: 0, stdout: HELP, stderr: "" };
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        return { code: 0, stdout: `${VERSION}\n`, stderr: "" };
+    }
+    if (command !== "scan" && command !== "audit") {
+        return usageError(`unknown command "${command}"`);
+    }
+    const options = parseCommonOptions(rest);
+    if ("code" in options)
+        return options;
+    if (command === "scan") {
+        const target = options.positionals[0];
+        if (target === undefined)
+            return usageError("scan: missing <dir>");
+        try {
+            const { config } = await loadConfig(options.configPath);
+            const gate = gateFor(options, config);
+            const scanned = await scanArtifact(target, options.adapter === undefined ? {} : { adapter: options.adapter });
+            const { kept, ignored } = applyIgnores(scanned.findings, config.ignore);
+            return await finish({ ...scanned, findings: kept, ignored: ignored.length }, gate, options);
+        }
+        catch (error) {
+            return failure("scan", error);
+        }
+    }
+    if (options.positionals.length > 0)
+        return usageError(`audit: unexpected argument "${options.positionals[0]}"`);
+    try {
+        const { config, source } = await loadConfig(options.configPath);
+        if (config.audit === undefined) {
+            throw new ConfigError(source === null
+                ? "audit needs a config file with an \"audit\" block (see docs/configuration.md)"
+                : `${source} has no "audit" block (see docs/configuration.md)`);
+        }
+        const gate = gateFor(options, config);
+        const audited = await runAudit(config.audit);
+        if (audited.responsesEvaluated === 0) {
+            // "No findings" would be a lie: nothing was looked at. Fail loudly.
+            throw new Error(`no response could be evaluated, so nothing was audited:\n  ${audited.warnings.join("\n  ")}`);
+        }
+        const { kept, ignored } = applyIgnores(audited.findings, config.ignore);
+        return await finish({ ...audited, findings: kept, ignored: ignored.length }, gate, options);
+    }
+    catch (error) {
+        return failure("audit", error);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,39 @@
+import type { AuditConfig } from "./audit/types.ts";
+import type { Finding } from "./index.ts";
+import { type Gate } from "./report/index.ts";
+export interface IgnoreRule {
+    /** Rule id to ignore, or "*" for any rule. */
+    ruleId: string;
+    /** Glob over the evidence path, relative to the scan target. */
+    path?: string;
+    /** Substring that must appear in the finding's message or excerpt. */
+    match?: string;
+    /** Why this is safe. Required. */
+    reason: string;
+}
+export interface Config {
+    gate?: Partial<Gate>;
+    ignore: IgnoreRule[];
+    /** Layer 2 settings; `evershield audit` requires this block. */
+    audit?: AuditConfig;
+}
+export declare const DEFAULT_CONFIG_FILE = "evershield.config.json";
+export declare class ConfigError extends Error {
+}
+/** Validate a parsed JSON value into a Config, with messages a human can act on. */
+export declare function parseConfig(raw: unknown, source: string): Config;
+/**
+ * Load the config file. An explicit path must exist; the default file is
+ * optional. Returns the source path alongside, for messages.
+ */
+export declare function loadConfig(explicitPath?: string): Promise<{
+    config: Config;
+    source: string | null;
+}>;
+/** Minimal glob: `**` spans directories, `*` and `?` stay within one segment. */
+export declare function globToRegExp(pattern: string): RegExp;
+/** Split findings into those kept and those an ignore rule accounts for. */
+export declare function applyIgnores(findings: Finding[], ignore: IgnoreRule[]): {
+    kept: Finding[];
+    ignored: Finding[];
+};

package/dist/config.js

@@ -0,0 +1,249 @@
+/**
+ * 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`);
+    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 parseAuditConfig(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object`);
+    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`);
+    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;
+    }
+    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`);
+    }
+    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 };
+    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;
+    }
+    return audit;
+}
+/**
+ * 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.
+        const subject = first?.kind === "file" ? first.path : first?.kind === "response" ? first.endpoint : 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,53 @@
+/**
+ * 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.1.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;
+    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.1.0";

package/dist/report/index.d.ts

@@ -0,0 +1,18 @@
+import type { AuditResult } from "../audit/run.ts";
+import type { Confidence, Finding, Severity } from "../index.ts";
+import type { ArtifactScanResult } from "../scan/artifact.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 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;