vigiles 9.1.0 → 11.0.0

package/dist/audit-score.d.ts

@@ -3,23 +3,30 @@
  *
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
- * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
- * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
- * the leaderboard's single health number, via the shared `computeIntegrityScore`
- * — so the two surfaces never disagree). Same detectors, no re-detection
- * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
- * hooks actually block?" — is NOT an `audit` ring:
- * it requires executing your hooks, which needs cross-platform confinement
- * that isn't shipped yet, so it lives in the `vigiles/testing` API via
- * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
+ * deterministic findings into five categories — Truthfulness, Triggering,
+ * Structure, Safety, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown
+ * beneath one headline `overall` = `100 − Σ(all graded penalties)` (the SAME
+ * summed model as the leaderboard's single health number, via the shared
+ * `computeIntegrityScore` — so the two surfaces never disagree). Same detectors,
+ * no re-detection (one-detector-no-drift); all deterministic, no execution.
+ *
+ * SAFETY is fed by the STATIC lethal-trifecta capability check
+ * (`lethalTrifectaIssues` → `report.trifectaFindings`): a unit holding all three
+ * capability legs is a prompt-injection exfil path detectable from the tool-SET
+ * alone — nothing executes, so it sidesteps the confinement blocker. A `"hard"`
+ * (explicit all-three) finding is GRADED into the overall; a `"advisory"`
+ * (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
+ * "do your hooks actually block?" disaster-battery is STILL not an `audit` ring:
+ * running arbitrary hooks safely needs cross-platform confinement that isn't
+ * shipped yet, so the battery lives in the `vigiles/testing` API via
+ * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.
  *
  * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
  */
 import { type PluginScore } from "./leaderboard.js";
 import type { ScanReport } from "./scan.js";
-export type CategoryKey = "Truthfulness" | "Triggering" | "Structure" | "Tested";
+export type CategoryKey = "Truthfulness" | "Triggering" | "Structure" | "Safety" | "Tested";
 export interface CategoryScore {
     readonly key: CategoryKey;
     /** 0–100, or `null` when the category isn't assessable (n/a — excluded from overall). */
@@ -52,7 +59,7 @@ export interface AuditScore {
     readonly empty: boolean;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * Bucket a scan report into the five deterministic Lighthouse categories as a
  * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
  * penalties)` (the shared summed model — NOT the average of the rings — so it
  * equals the leaderboard's single health number). The advisory Tested ring and

package/dist/audit-score.js

@@ -7,16 +7,23 @@ exports.formatAuditScore = formatAuditScore;
  *
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
- * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
- * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
- * the leaderboard's single health number, via the shared `computeIntegrityScore`
- * — so the two surfaces never disagree). Same detectors, no re-detection
- * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
- * hooks actually block?" — is NOT an `audit` ring:
- * it requires executing your hooks, which needs cross-platform confinement
- * that isn't shipped yet, so it lives in the `vigiles/testing` API via
- * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
+ * deterministic findings into five categories — Truthfulness, Triggering,
+ * Structure, Safety, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown
+ * beneath one headline `overall` = `100 − Σ(all graded penalties)` (the SAME
+ * summed model as the leaderboard's single health number, via the shared
+ * `computeIntegrityScore` — so the two surfaces never disagree). Same detectors,
+ * no re-detection (one-detector-no-drift); all deterministic, no execution.
+ *
+ * SAFETY is fed by the STATIC lethal-trifecta capability check
+ * (`lethalTrifectaIssues` → `report.trifectaFindings`): a unit holding all three
+ * capability legs is a prompt-injection exfil path detectable from the tool-SET
+ * alone — nothing executes, so it sidesteps the confinement blocker. A `"hard"`
+ * (explicit all-three) finding is GRADED into the overall; a `"advisory"`
+ * (inherits-all) finding is SHOWN in the ring but not graded. NB the EXECUTING
+ * "do your hooks actually block?" disaster-battery is STILL not an `audit` ring:
+ * running arbitrary hooks safely needs cross-platform confinement that isn't
+ * shipped yet, so the battery lives in the `vigiles/testing` API via
+ * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.
  *
  * A category that can't be assessed scores `null` (n/a) and is EXCLUDED from the
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
@@ -120,13 +127,68 @@ function structure(r) {
             weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "disallowedTools typo(s) that block nothing",
         },
+    ]);
+    // inherit-all (no `tools:` line) is ADVISORY, not graded: it's surfaced as a
+    // least-privilege NUDGE but never lowers the Structure ring. WHY: omitting the
+    // tool contract is a near-universal, legitimate authoring style (a measured OSS
+    // sweep of 122 real plugins found 109 whose only finding was this), so grading
+    // it would make `audit` cry wolf on idiomatic subagents. See reportDeductions.
+    const advisory = noContract > 0
+        ? [
+            `${String(noContract)} agent(s) inherit all tools (no contract) (advisory)`,
+        ]
+        : [];
+    return {
+        key: "Structure",
+        score,
+        weight: 1,
+        findings: [...findings, ...advisory],
+    };
+}
+/**
+ * SAFETY — fed by the STATIC lethal-trifecta check (`report.trifectaFindings`).
+ * A `"hard"` finding (an explicit contract naming all three capability legs) is a
+ * declared prompt-injection exfil path and is GRADED (`W_TRIFECTA` each, the same
+ * weight `reportDeductions` sums into the overall, so the ring and the headline
+ * agree). A `"advisory"` finding (inherits-all) is SHOWN in the ring's findings
+ * but NOT graded — aligned with the inherits-all-is-advisory stance.
+ *
+ * Scores `null` (n/a, excluded from the overall) when there's NO tool-bearing
+ * surface to assess at all — no subagents AND no model-invocable skills. A
+ * user-invoked skill carries no model-driven trifecta risk, so it doesn't count
+ * as an assessable surface. When there ARE assessable surfaces but no trifecta,
+ * the ring is a clean 100.
+ */
+function safety(r) {
+    const modelInvocableSkills = r.skills.filter((s) => !s.userInvoked).length;
+    const assessable = r.agents.length + modelInvocableSkills;
+    if (assessable === 0) {
+        return {
+            key: "Safety",
+            score: null,
+            weight: 1,
+            findings: ["no tool-bearing surface to assess"],
+        };
+    }
+    const hard = r.trifectaFindings.filter((f) => f.finding.severity === "hard");
+    const { score, findings } = scoreFrom([
         {
-            n: noContract,
-            weight: leaderboard_js_1.W_NO_CONTRACT,
-            label: "agent(s) inherit all tools (no contract)",
+            n: hard.length,
+            weight: leaderboard_js_1.W_TRIFECTA,
+            label: "unit(s) holding all three lethal-trifecta legs (prompt-injection exfil path)",
         },
     ]);
-    return { key: "Structure", score, weight: 1, findings };
+    // inherits-all trifecta findings are ADVISORY: surfaced as a maximal-blast-radius
+    // note but never graded (mirrors the Structure inherits-all advisory).
+    const advisory = r.trifectaFindings
+        .filter((f) => f.finding.severity === "advisory")
+        .map((f) => `${f.name} inherits all tools — maximal trifecta blast radius (advisory)`);
+    return {
+        key: "Safety",
+        score,
+        weight: 1,
+        findings: [...findings, ...advisory],
+    };
 }
 function tested(r) {
     const { score, findings } = scoreFrom([
@@ -147,7 +209,7 @@ function isEmptyAudit(r) {
     return (0, leaderboard_js_1.isEmptyMachine)(r) && !r.instructions;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * Bucket a scan report into the five deterministic Lighthouse categories as a
  * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
  * penalties)` (the shared summed model — NOT the average of the rings — so it
  * equals the leaderboard's single health number). The advisory Tested ring and
@@ -159,6 +221,7 @@ function auditScore(report) {
             "Truthfulness",
             "Triggering",
             "Structure",
+            "Safety",
             "Tested",
         ];
         return {
@@ -177,6 +240,7 @@ function auditScore(report) {
         truthfulness(report),
         triggering(report),
         structure(report),
+        safety(report),
         tested(report),
     ];
     // The headline is the SUMMED model (the shared integrity score), NOT the average

package/dist/audit-serve.d.ts

@@ -0,0 +1,109 @@
+/** A per-run server session: the secret token + the adopt allowlist. */
+export interface ServeSession {
+    /** Crypto-random hex; embedded in the HTML, required on every mutating POST. */
+    readonly token: string;
+    /** The loopback port the server is bound to (for the Origin check). */
+    readonly port: number;
+    /**
+     * The adoptable surfaces, keyed by their repo-relative path. A POST names a
+     * path; we resolve it HERE against this set, so an off-list path is refused.
+     */
+    readonly surfaces: ReadonlySet<string>;
+}
+/** The salient, transport-agnostic fields of an incoming request. */
+export interface RequestView {
+    readonly method: string;
+    /** The URL path (no query string). */
+    readonly path: string;
+    /** The `X-Vigiles-Token` header, if any. */
+    readonly token: string | null;
+    /** The `Origin` header, if any. */
+    readonly origin: string | null;
+    /** `body.target` for an adopt POST, if any. */
+    readonly target: string | null;
+}
+/** What the server should do with a request — a pure, testable verdict. */
+export type ServeDecision = {
+    readonly kind: "report";
+} | {
+    readonly kind: "adopt";
+    readonly target: string;
+} | {
+    readonly kind: "adopt-all";
+} | {
+    readonly kind: "shutdown";
+} | {
+    readonly kind: "reject";
+    readonly status: number;
+    readonly reason: string;
+};
+/**
+ * Constant-time token comparison (avoids a timing side-channel). Returns false
+ * for a missing/short token rather than throwing.
+ */
+export declare function tokenOk(provided: string | null, expected: string): boolean;
+/**
+ * A mutating POST's Origin must be the loopback server itself (or absent — some
+ * same-origin fetches omit it, and the token already guards those). A foreign
+ * site's Origin never matches, so a cross-site POST is refused even before the
+ * token check.
+ */
+export declare function originOk(origin: string | null, port: number): boolean;
+/**
+ * Resolve a client-supplied surface path against the allowlist. Returns the path
+ * only if it's a known adoptable surface — never trusts a raw path (no traversal).
+ */
+export declare function resolveSurface(target: string | null, surfaces: ReadonlySet<string>): string | null;
+/**
+ * The pure router: given a request and the session, decide what to do. Every
+ * MUTATING route (adopt / adopt-all / shutdown) requires POST + a valid Origin +
+ * a valid token; GET / serves the report page (its body is CORS-protected, so a
+ * foreign site can't read it even if it requests it).
+ */
+export declare function decideServe(req: RequestView, session: ServeSession): ServeDecision;
+/** A fresh crypto-random session token (32 hex chars = 16 bytes). */
+export declare function newToken(): string;
+/** Whether `audit` should start the live adoption server. */
+export type ServeGate = "serve" | "skip" | "ask";
+/**
+ * The pure serve-gate decision (option B). A plain `audit` stays a terminating,
+ * headless-safe read; the live server is only ever offered/started INTERACTIVELY
+ * and OWN-REPO (it writes specs — never into a stranger's dir):
+ *   - `--no-serve`, a foreign repo, or `--json`/headless → skip (never serve).
+ *   - `--serve` → serve (force, skip the prompt).
+ *   - a TTY with adoptable surfaces → ask once ("open the live report?").
+ *   - a TTY with nothing to adopt → skip (no point).
+ */
+export declare function decideServeGate(o: {
+    serveFlag: boolean;
+    noServeFlag: boolean;
+    json: boolean;
+    isTTY: boolean;
+    ownRepo: boolean;
+    adoptableCount: number;
+}): ServeGate;
+/** The outcome of running an adopt action, reported back to the report UI. */
+export interface AdoptOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+}
+export interface ServeOptions {
+    /** The per-run secret token (already injected into `html`). */
+    readonly token: string;
+    /** The adopt allowlist (repo-relative surface paths). */
+    readonly surfaces: ReadonlySet<string>;
+    /** The rendered report HTML (with the token already injected). */
+    readonly html: string;
+    /** Adopt ONE surface (the CLI passes a closure over `init --target=`). */
+    readonly runAdopt: (target: string) => Promise<AdoptOutcome>;
+    /** Adopt every surface (bare `init`). */
+    readonly runAdoptAll: () => Promise<AdoptOutcome>;
+    /** Called once the server is listening, with the URL to open. */
+    readonly onListening?: (url: string) => void;
+}
+/**
+ * Start the loopback adoption server. Resolves when the server shuts down (via
+ * the /shutdown route or SIGINT). Bound to 127.0.0.1 only.
+ */
+export declare function serveAudit(opts: ServeOptions): Promise<void>;
+//# sourceMappingURL=audit-serve.d.ts.map

package/dist/audit-serve.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenOk = tokenOk;
+exports.originOk = originOk;
+exports.resolveSurface = resolveSurface;
+exports.decideServe = decideServe;
+exports.newToken = newToken;
+exports.decideServeGate = decideServeGate;
+exports.serveAudit = serveAudit;
+/**
+ * `audit --serve` — the optional one-click-local adoption server.
+ *
+ * The HTML audit report is a STATIC file: a browser can't write your repo, so by
+ * default its "Create spec" buttons just COPY the `npx vigiles init …` command.
+ * `--serve` (or the TTY prompt) instead starts a tiny LOCAL server the report
+ * POSTs to, so a button click actually runs `init` for you — without ever leaving
+ * your machine.
+ *
+ * This is the only path where `audit` WRITES via a button, so it carries the
+ * standard localhost-server hardening (the Jupyter recipe — see
+ * research/audit-serve-design.md):
+ *
+ *   1. BIND 127.0.0.1 only (never 0.0.0.0) — unreachable off the machine.
+ *   2. A per-run SECRET TOKEN (crypto-random), embedded in the served HTML and
+ *      REQUIRED on every mutating POST. A foreign website can't read the token
+ *      (CORS blocks reading a cross-origin GET body), so it can't forge a POST —
+ *      this is the primary CSRF defense.
+ *   3. ORIGIN/Host check as belt-and-suspenders: a POST's Origin must be the
+ *      loopback server itself.
+ *   4. The adopt endpoint takes a surface ID from the pre-computed ALLOWLIST (the
+ *      surfaces audit already discovered), never a client-supplied path — so a
+ *      forged request can't traverse outside the repo.
+ *   5. The action calls `init` IN-PROCESS (an injected runner), never a shell, so
+ *      there's no command injection.
+ *   6. Worst-case blast radius is tiny: `init` writes a reversible local
+ *      `.spec.ts` (no exec, no network, no model); `eject` undoes it.
+ *
+ * The pure decision logic (`decideServe`, `tokenOk`, `originOk`,
+ * `resolveSurface`) is unit-tested; the http/IO shell (`serveAudit`) is the thin
+ * v8-ignored wrapper.
+ */
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Constant-time token comparison (avoids a timing side-channel). Returns false
+ * for a missing/short token rather than throwing.
+ */
+function tokenOk(provided, expected) {
+    if (!provided || provided.length !== expected.length)
+        return false;
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    // Lengths are equal here, so timingSafeEqual is safe to call.
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * A mutating POST's Origin must be the loopback server itself (or absent — some
+ * same-origin fetches omit it, and the token already guards those). A foreign
+ * site's Origin never matches, so a cross-site POST is refused even before the
+ * token check.
+ */
+function originOk(origin, port) {
+    if (origin === null)
+        return true; // rely on the token (a foreign site can't have it)
+    return (origin === `http://127.0.0.1:${String(port)}` ||
+        origin === `http://localhost:${String(port)}`);
+}
+/**
+ * Resolve a client-supplied surface path against the allowlist. Returns the path
+ * only if it's a known adoptable surface — never trusts a raw path (no traversal).
+ */
+function resolveSurface(target, surfaces) {
+    if (!target)
+        return null;
+    return surfaces.has(target) ? target : null;
+}
+/**
+ * The pure router: given a request and the session, decide what to do. Every
+ * MUTATING route (adopt / adopt-all / shutdown) requires POST + a valid Origin +
+ * a valid token; GET / serves the report page (its body is CORS-protected, so a
+ * foreign site can't read it even if it requests it).
+ */
+function decideServe(req, session) {
+    if (req.method === "GET" &&
+        (req.path === "/" || req.path === "/index.html")) {
+        return { kind: "report" };
+    }
+    const mutating = req.path === "/adopt" ||
+        req.path === "/adopt-all" ||
+        req.path === "/shutdown";
+    if (!mutating) {
+        return { kind: "reject", status: 404, reason: "not found" };
+    }
+    if (req.method !== "POST") {
+        return { kind: "reject", status: 405, reason: "method not allowed" };
+    }
+    if (!originOk(req.origin, session.port)) {
+        return { kind: "reject", status: 403, reason: "bad origin" };
+    }
+    if (!tokenOk(req.token, session.token)) {
+        return { kind: "reject", status: 403, reason: "bad or missing token" };
+    }
+    if (req.path === "/shutdown")
+        return { kind: "shutdown" };
+    if (req.path === "/adopt-all")
+        return { kind: "adopt-all" };
+    const target = resolveSurface(req.target, session.surfaces);
+    if (!target) {
+        return { kind: "reject", status: 400, reason: "unknown surface" };
+    }
+    return { kind: "adopt", target };
+}
+/** A fresh crypto-random session token (32 hex chars = 16 bytes). */
+function newToken() {
+    return (0, node_crypto_1.randomBytes)(16).toString("hex");
+}
+/**
+ * The pure serve-gate decision (option B). A plain `audit` stays a terminating,
+ * headless-safe read; the live server is only ever offered/started INTERACTIVELY
+ * and OWN-REPO (it writes specs — never into a stranger's dir):
+ *   - `--no-serve`, a foreign repo, or `--json`/headless → skip (never serve).
+ *   - `--serve` → serve (force, skip the prompt).
+ *   - a TTY with adoptable surfaces → ask once ("open the live report?").
+ *   - a TTY with nothing to adopt → skip (no point).
+ */
+function decideServeGate(o) {
+    if (o.noServeFlag)
+        return "skip";
+    if (!o.ownRepo)
+        return "skip"; // serve writes specs → own repo only
+    if (o.serveFlag)
+        return "serve";
+    if (o.json || !o.isTTY)
+        return "skip"; // headless never serves
+    if (o.adoptableCount === 0)
+        return "skip"; // nothing to adopt
+    return "ask";
+}
+/* v8 ignore start — the http/IO shell; the decision logic above is unit-tested. */
+/** Read a request body to a string, capped to avoid an unbounded read. */
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > 64 * 1024)
+            break; // an adopt POST is tiny; cap defensively
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+function viewOf(req, body) {
+    const path = (req.url ?? "/").split("?")[0];
+    let target = null;
+    try {
+        if (body)
+            target = JSON.parse(body).target ?? null;
+    }
+    catch {
+        target = null;
+    }
+    const header = (n) => {
+        const v = req.headers[n];
+        return typeof v === "string" ? v : null;
+    };
+    return {
+        method: req.method ?? "GET",
+        path,
+        token: header("x-vigiles-token"),
+        origin: header("origin"),
+        target,
+    };
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "content-type": "application/json",
+        // No CORS headers: same-origin only. A cross-origin site can fire a request
+        // but cannot read this response — and can't forge the token anyway.
+        "x-content-type-options": "nosniff",
+    });
+    res.end(payload);
+}
+/**
+ * Start the loopback adoption server. Resolves when the server shuts down (via
+ * the /shutdown route or SIGINT). Bound to 127.0.0.1 only.
+ */
+async function serveAudit(opts) {
+    const { token, surfaces, html, runAdopt, runAdoptAll, onListening } = opts;
+    // The bound port is known only after listen(); the request handler reads it via
+    // this closure. No request can arrive before the server is listening, so the
+    // late assignment is race-free.
+    let session = { token, port: 0, surfaces };
+    await new Promise((resolveServer) => {
+        const server = (0, node_http_1.createServer)((req, res) => {
+            void (async () => {
+                const body = req.method === "POST" ? await readBody(req) : "";
+                const decision = decideServe(viewOf(req, body), session);
+                switch (decision.kind) {
+                    case "report":
+                        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+                        res.end(html);
+                        return;
+                    case "adopt": {
+                        const out = await runAdopt(decision.target);
+                        sendJson(res, out.ok ? 200 : 500, out);
+                        return;
+                    }
+                    case "adopt-all": {
+                        const out = await runAdoptAll();
+                        sendJson(res, out.ok ? 200 : 500, out);
+                        return;
+                    }
+                    case "shutdown":
+                        sendJson(res, 200, { ok: true, message: "shutting down" });
+                        server.close(() => {
+                            resolveServer();
+                        });
+                        return;
+                    case "reject":
+                        sendJson(res, decision.status, {
+                            ok: false,
+                            message: decision.reason,
+                        });
+                        return;
+                }
+            })().catch(() => {
+                try {
+                    sendJson(res, 500, { ok: false, message: "internal error" });
+                }
+                catch {
+                    /* response already sent */
+                }
+            });
+        });
+        server.on("error", () => {
+            resolveServer();
+        });
+        // 127.0.0.1 ONLY — never 0.0.0.0; the server is unreachable off the machine.
+        // Port 0 → the OS assigns an ephemeral port; we learn it after binding.
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = addr && typeof addr === "object" ? addr.port : 0;
+            session = { token, port, surfaces };
+            onListening?.(`http://127.0.0.1:${String(port)}/?token=${token}`);
+        });
+        const stop = () => {
+            server.close(() => {
+                resolveServer();
+            });
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+/* v8 ignore stop */
+//# sourceMappingURL=audit-serve.js.map