attenu-guard 0.1.0

package/dist/esm/cli.js

@@ -0,0 +1,97 @@
+/**
+ * attenu-guard — command-line tool.
+ *
+ *   attenu-guard verify <log.jsonl | bundle.json> [--hs256-key HEX | --pubkey HEX] [--kid KID]
+ *
+ * A `.jsonl` audit log is checked for hash-chain integrity. A bundle (the
+ * output of `exportBundle`, or of the Python library's `export_bundle`) is
+ * checked for integrity, monotonicity (child ⊆ parent) and containment from the
+ * bundle alone; the signed anchor is verified when a key is given and reported
+ * as "not checked" otherwise.
+ *
+ * Exit codes: 0 = ok, 2 = a check failed, 1 = usage. The output lines match the
+ * Python CLI's, so either implementation can stand in for the other in a script.
+ */
+import { readFileSync } from "node:fs";
+import { AuditLog } from "./audit.js";
+import { parseBundle, verifyBundle } from "./evidence.js";
+import { Ed25519Verifier, HS256TestSigner } from "./wire.js";
+const USAGE = `attenu-guard — command-line tool.
+
+  attenu-guard verify <log.jsonl | bundle.json> [--hs256-key HEX | --pubkey HEX] [--kid KID]
+                                     verify a hash-chained audit log, or an evidence bundle
+                                     (integrity · child ⊆ parent · containment;
+                                      --hs256-key/--pubkey checks the anchor)
+`;
+/** Render a boolean the way Python does, so the two CLIs print the same line. */
+function py(value) {
+    return value ? "True" : "False";
+}
+function verify(args) {
+    let path = null;
+    let keyHex = null;
+    let pubHex = null;
+    let kid = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--hs256-key")
+            keyHex = args[++i] ?? null;
+        else if (a === "--pubkey")
+            pubHex = args[++i] ?? null;
+        else if (a === "--kid")
+            kid = args[++i] ?? null;
+        else if (path === null)
+            path = a;
+    }
+    if (path === null) {
+        process.stdout.write(USAGE);
+        return 1;
+    }
+    const text = readFileSync(path, "utf8");
+    let bundle = null;
+    try {
+        // A bundle is ONE JSON object; a ledger is JSON Lines.
+        const parsed = parseBundle(text);
+        bundle =
+            parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && "entries" in parsed
+                ? parsed
+                : null;
+    }
+    catch {
+        bundle = null;
+    }
+    if (bundle !== null) {
+        const anchorKid = bundle.anchor?.["kid"] ?? undefined;
+        let signer = null;
+        if (keyHex)
+            signer = new HS256TestSigner(Buffer.from(keyHex, "hex"), kid ?? anchorKid ?? "k1");
+        else if (pubHex) {
+            signer = new Ed25519Verifier(Buffer.from(pubHex, "hex"), kid ?? anchorKid ?? "k1");
+        }
+        const rep = verifyBundle(bundle, signer);
+        const c = rep.checks;
+        process.stdout.write(`integrity=${py(c.integrity)} monotonicity=${py(c.monotonicity)} ` +
+            `containment=${py(c.containment)} anchor=${c.anchor} ` +
+            `nodes=${rep.nodes} actions_checked=${rep.actions_checked}\n`);
+        for (const f of rep.failures)
+            process.stdout.write(`  - ${f}\n`);
+        process.stdout.write(rep.ok ? "OK\n" : "FAILED\n");
+        return rep.ok ? 0 : 2;
+    }
+    const entries = AuditLog.parseLines(text);
+    const [ok, reason] = AuditLog.verify(entries);
+    process.stdout.write(ok ? "OK\n" : `TAMPERED — ${reason}\n`);
+    return ok ? 0 : 2;
+}
+export function main(argv = process.argv.slice(2)) {
+    if (argv.length === 0) {
+        process.stdout.write(USAGE);
+        return 1;
+    }
+    const [cmd, ...rest] = argv;
+    if (cmd === "verify" && rest.length > 0)
+        return verify(rest);
+    process.stdout.write(USAGE);
+    return 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/esm/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/esm/evidence.d.ts

@@ -0,0 +1,163 @@
+/**
+ * evidence.ts — the offline bundle exporter and verifier.
+ *
+ * A delegation ledger is only worth as much as an auditor's ability to check it
+ * WITHOUT the engine that produced it. A bundle is self-contained — the
+ * hash-chained ledger plus a signed anchor — and three invariants are checked
+ * from that bundle ALONE:
+ *
+ *   integrity     the hash chain reproduces AND matches the out-of-band signed
+ *                 anchor. A consistent full rewrite, which the chain check
+ *                 alone cannot catch, fails here: the anchor's head is the
+ *                 fixed point.
+ *   monotonicity  every delegation is child ⊆ parent — the granted authority on
+ *                 each `spawn` is narrower than the parent node's authority.
+ *   containment   every `allow` action's scope was within the acting node's
+ *                 authority: no action was authorized outside what the node held.
+ *
+ *     const bundle = exportBundle(guard.auditLog(), signer);
+ *     const report = verifyBundle(bundle, signer);
+ *
+ * No engine state is consulted — the bundle is the whole input, which is the
+ * point. This is byte-compatible with the Python library's
+ * `attenu_guard.evidence`.
+ */
+import { type Json } from "./canonical.js";
+import { AuditLog, type Anchor, type LedgerEntry } from "./audit.js";
+import type { Signer } from "./wire.js";
+/**
+ * The COMPLETE set of top-level ledger field names the library emits. Custody
+ * guarantee: an exported bundle may carry ONLY these — an unknown field is
+ * exactly where a raw tool argument would be smuggled, so it is a leak, not a
+ * curiosity. `exportBundle({strict: true})` throws on any field outside this set.
+ *
+ * `task` is free text (a delegated prompt) and `context` is an object; both are
+ * redactable for transport.
+ */
+export declare const LEDGER_FIELDS: ReadonlySet<string>;
+/**
+ * Thrown by `exportBundle({strict: true})` when a bundle would carry a field or
+ * context key outside the allow-list — potential customer data the custody
+ * contract says must not leave the premises.
+ */
+export declare class EvidenceLeakError extends Error {
+    constructor(message: string);
+}
+export interface RedactionViolation {
+    event_index: number;
+    event: Json;
+    field?: string;
+    context_key?: string;
+}
+export interface RedactionReport {
+    ok: boolean;
+    violations: RedactionViolation[];
+}
+export interface Bundle {
+    v: number;
+    chain_id: string;
+    entries: LedgerEntry[];
+    anchor: Anchor;
+    redaction: RedactionReport;
+    note: string;
+}
+/**
+ * Every top-level field must be in `LEDGER_FIELDS`; if `contextAllowlist` is
+ * given, every context key must be in it. `task` free text is allowed
+ * structurally but is redacted by `exportBundle({redactTask: true})` for
+ * transport — its raw value is the caller's to keep, not this library's.
+ */
+export declare function redactionReport(entries: readonly LedgerEntry[], contextAllowlist?: Iterable<string> | null): RedactionReport;
+/** A signed commitment to the head of `entries` — mirrors `AuditLog.anchor`. */
+export declare function anchorFor(entries: readonly LedgerEntry[], signer: Signer, ts?: number | string): Anchor;
+export interface ExportOptions {
+    ts?: number | string;
+    contextAllowlist?: Iterable<string> | null;
+    /** Replace free-text `task` fields with a length-and-hash marker. */
+    redactTask?: boolean;
+    /** Throw `EvidenceLeakError` on any field outside the allow-list. */
+    strict?: boolean;
+}
+/**
+ * A self-contained evidence bundle: the full ledger plus a signed anchor over
+ * its head.
+ *
+ * With `redactTask`, free-text `task` fields are replaced by a length-and-hash
+ * marker BEFORE the anchor is computed, so the transported bundle carries no
+ * raw prompt text yet still verifies — redaction is not tampering, because it
+ * only ever removes. With `strict`, the bundle is checked against
+ * `LEDGER_FIELDS` (and `contextAllowlist` if given) and an `EvidenceLeakError`
+ * is thrown on any field outside it.
+ */
+export declare function exportBundle(auditLog: AuditLog | readonly LedgerEntry[], signer: Signer, options?: ExportOptions): Bundle;
+export interface GraphNode {
+    agent: Json;
+    task: Json;
+    parent: Json;
+    scopes: string[];
+    allows: number;
+    denies: number;
+    revoked: boolean;
+    complete: boolean;
+    denials_by_disposition: Record<string, number>;
+}
+export interface DelegationGraph {
+    chain_id: Json;
+    nodes: Record<string, GraphNode>;
+    edges: {
+        parent: string;
+        child: string;
+    }[];
+}
+/**
+ * A view of the chain from the bundle: each node with its agent, task,
+ * authority, parent and per-node action counts — what a reviewer or a UI
+ * renders. Derived from the ledger alone.
+ */
+export declare function delegationGraph(bundle: Partial<Bundle>): DelegationGraph;
+export interface DenialRow {
+    node: Json;
+    agent: Json;
+    tool: Json;
+    scope: Json;
+    disposition: Json;
+    reason: Json;
+    count: number;
+    first_seq: number;
+    last_seq: number;
+}
+/**
+ * Deny events grouped by (node, tool, scope, disposition) — the rows a decisions
+ * queue renders: "should this agent be allowed to <tool>?", with how often it
+ * asked and why it was refused. A pure fold over the ledger, ordered by first
+ * occurrence.
+ */
+export declare function denials(bundle: Partial<Bundle>): DenialRow[];
+export interface VerifyChecks {
+    integrity: boolean;
+    monotonicity: boolean;
+    containment: boolean;
+    anchor: "not checked" | "verified" | "FAILED";
+}
+export interface VerifyReport {
+    ok: boolean;
+    checks: VerifyChecks;
+    failures: string[];
+    nodes: number;
+    actions_checked: number;
+    chain_id: Json;
+}
+/**
+ * Verify integrity, monotonicity and containment from the bundle alone.
+ *
+ * `signer` is the verifier for the bundle's signed anchor — a public key, or
+ * the test signer. Without one the hash chain, monotonicity and containment are
+ * still checked but the anchor signature is NOT; the report says so
+ * (`checks.anchor === "not checked"`), and `ok` then means "consistent,
+ * unverified by key": a consistent full rewrite by someone holding the key
+ * cannot be excluded without the key.
+ */
+export declare function verifyBundle(bundle: Partial<Bundle>, signer?: Signer | null): VerifyReport;
+/** Read a bundle from JSON text, keeping every number's original literal. */
+export declare function parseBundle(text: string): Bundle;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/esm/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/evidence.ts"],"names":[],"mappings":"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"}

package/dist/esm/evidence.js

@@ -0,0 +1,398 @@
+/**
+ * evidence.ts — the offline bundle exporter and verifier.
+ *
+ * A delegation ledger is only worth as much as an auditor's ability to check it
+ * WITHOUT the engine that produced it. A bundle is self-contained — the
+ * hash-chained ledger plus a signed anchor — and three invariants are checked
+ * from that bundle ALONE:
+ *
+ *   integrity     the hash chain reproduces AND matches the out-of-band signed
+ *                 anchor. A consistent full rewrite, which the chain check
+ *                 alone cannot catch, fails here: the anchor's head is the
+ *                 fixed point.
+ *   monotonicity  every delegation is child ⊆ parent — the granted authority on
+ *                 each `spawn` is narrower than the parent node's authority.
+ *   containment   every `allow` action's scope was within the acting node's
+ *                 authority: no action was authorized outside what the node held.
+ *
+ *     const bundle = exportBundle(guard.auditLog(), signer);
+ *     const report = verifyBundle(bundle, signer);
+ *
+ * No engine state is consulted — the bundle is the whole input, which is the
+ * point. This is byte-compatible with the Python library's
+ * `attenu_guard.evidence`.
+ */
+import { canonicalBytes, compareCodePoints, parseJson, toPlain, } from "./canonical.js";
+import { createHash } from "node:crypto";
+import { AuditLog, SCHEMA_VERSION, chainIdOf, hashEntry, GENESIS } from "./audit.js";
+import { Authority } from "./authority.js";
+/**
+ * The COMPLETE set of top-level ledger field names the library emits. Custody
+ * guarantee: an exported bundle may carry ONLY these — an unknown field is
+ * exactly where a raw tool argument would be smuggled, so it is a leak, not a
+ * curiosity. `exportBundle({strict: true})` throws on any field outside this set.
+ *
+ * `task` is free text (a delegated prompt) and `context` is an object; both are
+ * redactable for transport.
+ */
+export const LEDGER_FIELDS = new Set([
+    "v",
+    "seq",
+    "ts",
+    "event",
+    "prev_hash",
+    "hash",
+    "chain_id",
+    "node",
+    "parent",
+    "agent",
+    "task",
+    "scope",
+    "tool",
+    "context",
+    "reason",
+    "reasons",
+    "authority",
+    "requested",
+    "granted",
+    "target",
+    "revoked",
+    "strikes",
+    "mode",
+    "disposition",
+]);
+/**
+ * Thrown by `exportBundle({strict: true})` when a bundle would carry a field or
+ * context key outside the allow-list — potential customer data the custody
+ * contract says must not leave the premises.
+ */
+export class EvidenceLeakError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EvidenceLeakError";
+    }
+}
+function redactTask(t) {
+    if (t === undefined || t === null || t === "" || t === 0 || t === false)
+        return t;
+    const s = String(toPlain(t));
+    const h = createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex").slice(0, 12);
+    return `redacted:len=${s.length}:h=${h}`;
+}
+/**
+ * Every top-level field must be in `LEDGER_FIELDS`; if `contextAllowlist` is
+ * given, every context key must be in it. `task` free text is allowed
+ * structurally but is redacted by `exportBundle({redactTask: true})` for
+ * transport — its raw value is the caller's to keep, not this library's.
+ */
+export function redactionReport(entries, contextAllowlist) {
+    const allow = contextAllowlist === undefined || contextAllowlist === null ? null : new Set(contextAllowlist);
+    const violations = [];
+    entries.forEach((e, i) => {
+        for (const f of Object.keys(e)) {
+            if (!LEDGER_FIELDS.has(f)) {
+                violations.push({ event_index: i, event: toPlain(e["event"]), field: f });
+            }
+        }
+        if (allow !== null) {
+            const ctx = (e["context"] ?? {});
+            if (ctx !== null && typeof ctx === "object" && !Array.isArray(ctx)) {
+                for (const k of Object.keys(ctx)) {
+                    if (!allow.has(k)) {
+                        violations.push({ event_index: i, event: toPlain(e["event"]), context_key: k });
+                    }
+                }
+            }
+        }
+    });
+    return { ok: violations.length === 0, violations };
+}
+/** A signed commitment to the head of `entries` — mirrors `AuditLog.anchor`. */
+export function anchorFor(entries, signer, ts = 0) {
+    let seq;
+    let head;
+    if (entries.length === 0) {
+        seq = -1;
+        head = "GENESIS";
+    }
+    else {
+        const last = entries[entries.length - 1];
+        const rawSeq = toPlain(last["seq"]);
+        seq = typeof rawSeq === "number" ? rawSeq : entries.length - 1;
+        head = last["hash"];
+    }
+    const body = { v: SCHEMA_VERSION, chain_id: chainIdOf(entries), seq, head, ts };
+    return { ...body, kid: signer.kid ?? null, sig: signer.sign(canonicalBytes(body)).toString("hex") };
+}
+/**
+ * A self-contained evidence bundle: the full ledger plus a signed anchor over
+ * its head.
+ *
+ * With `redactTask`, free-text `task` fields are replaced by a length-and-hash
+ * marker BEFORE the anchor is computed, so the transported bundle carries no
+ * raw prompt text yet still verifies — redaction is not tampering, because it
+ * only ever removes. With `strict`, the bundle is checked against
+ * `LEDGER_FIELDS` (and `contextAllowlist` if given) and an `EvidenceLeakError`
+ * is thrown on any field outside it.
+ */
+export function exportBundle(auditLog, signer, options = {}) {
+    const source = auditLog instanceof AuditLog ? auditLog.entries : auditLog;
+    const entries = source.map((e) => ({ ...e }));
+    if (options.redactTask) {
+        for (const e of entries) {
+            if ("task" in e)
+                e["task"] = redactTask(e["task"]);
+        }
+        // Re-hash the chain so the redacted form is what the anchor covers.
+        let prev = GENESIS;
+        for (const e of entries) {
+            e["prev_hash"] = prev;
+            const payload = {};
+            for (const [k, v] of Object.entries(e))
+                if (k !== "hash")
+                    payload[k] = v;
+            e["hash"] = hashEntry(prev, payload);
+            prev = e["hash"];
+        }
+    }
+    const report = redactionReport(entries, options.contextAllowlist ?? null);
+    if (options.strict && !report.ok) {
+        throw new EvidenceLeakError(`${report.violations.length} field(s) outside the ledger allow-list: ` +
+            JSON.stringify(report.violations.slice(0, 5)));
+    }
+    const anchor = anchorFor(entries, signer, options.ts ?? 0);
+    anchor.verified = AuditLog.verifyAnchor(entries, anchor, signer)[0];
+    return {
+        v: SCHEMA_VERSION,
+        chain_id: chainIdOf(entries),
+        entries,
+        anchor,
+        redaction: report,
+        note: "offline-verifiable: attenu_guard.evidence.verify_bundle(bundle, signer)",
+    };
+}
+/**
+ * A ledger field, or `null` when it is absent. Python's `dict.get` yields `None`
+ * for a missing key and that `None` reaches the caller as a value; JavaScript
+ * would hand back `undefined`, which is not the same thing to a `deepEqual` or a
+ * JSON serialiser. Every field read for a report goes through here.
+ */
+function orNull(value) {
+    const plain = toPlain(value);
+    return plain === undefined ? null : plain;
+}
+/**
+ * `node -> Authority` and `node -> parent`, reconstructed from `root` and
+ * `spawn` events alone. No engine state.
+ */
+function nodeAuthorities(entries) {
+    const auth = new Map();
+    const parent = new Map();
+    const failures = [];
+    for (const e of entries) {
+        const ev = toPlain(e["event"]);
+        const node = toPlain(e["node"]);
+        if (ev === "root") {
+            try {
+                auth.set(node, Authority.fromWire(e["authority"] ?? null));
+            }
+            catch (exc) {
+                failures.push(`root ${node}: unreadable authority (${exc.message})`);
+            }
+        }
+        else if (ev === "spawn") {
+            parent.set(node, toPlain(e["parent"]) ?? null);
+            try {
+                auth.set(node, Authority.fromWire(e["granted"] ?? null));
+            }
+            catch (exc) {
+                failures.push(`spawn ${node}: unreadable granted (${exc.message})`);
+            }
+        }
+    }
+    return { auth, parent, failures };
+}
+/**
+ * A view of the chain from the bundle: each node with its agent, task,
+ * authority, parent and per-node action counts — what a reviewer or a UI
+ * renders. Derived from the ledger alone.
+ */
+export function delegationGraph(bundle) {
+    const entries = bundle.entries ?? [];
+    const { auth, parent } = nodeAuthorities(entries);
+    const meta = {};
+    for (const e of entries) {
+        const ev = toPlain(e["event"]);
+        const n = toPlain(e["node"]);
+        if (ev === "root" || ev === "spawn") {
+            const a = auth.get(n);
+            meta[n] = {
+                agent: orNull(e["agent"]),
+                task: orNull(e["task"]),
+                parent: orNull(e["parent"]),
+                scopes: a ? Array.from(a.scopes).sort(compareCodePoints) : [],
+                allows: 0,
+                denies: 0,
+                revoked: false,
+                complete: false,
+                denials_by_disposition: {},
+            };
+        }
+        else if (ev === "allow" && meta[n]) {
+            meta[n].allows += 1;
+        }
+        else if (ev === "deny" && meta[n]) {
+            meta[n].denies += 1;
+            // A deny without a disposition is named by its reason.
+            const d = (toPlain(e["disposition"]) ?? toPlain(e["reason"]) ?? "unstated");
+            meta[n].denials_by_disposition[d] = (meta[n].denials_by_disposition[d] ?? 0) + 1;
+        }
+        else if (ev === "done" && meta[n]) {
+            meta[n].complete = true;
+        }
+        else if (ev === "kill") {
+            for (const r of toPlain(e["revoked"]) ?? []) {
+                if (meta[r])
+                    meta[r].revoked = true;
+            }
+        }
+    }
+    const edges = [];
+    for (const [child, p] of parent) {
+        if (p)
+            edges.push({ parent: p, child });
+    }
+    return { chain_id: orNull(bundle.chain_id), nodes: meta, edges };
+}
+/**
+ * Deny events grouped by (node, tool, scope, disposition) — the rows a decisions
+ * queue renders: "should this agent be allowed to <tool>?", with how often it
+ * asked and why it was refused. A pure fold over the ledger, ordered by first
+ * occurrence.
+ */
+export function denials(bundle) {
+    const entries = bundle.entries ?? [];
+    const agentOf = new Map();
+    for (const e of entries) {
+        const ev = toPlain(e["event"]);
+        if (ev === "root" || ev === "spawn") {
+            agentOf.set(toPlain(e["node"]), orNull(e["agent"]));
+        }
+    }
+    const rows = new Map();
+    for (const e of entries) {
+        if (toPlain(e["event"]) !== "deny")
+            continue;
+        const node = orNull(e["node"]);
+        const key = JSON.stringify([node, orNull(e["tool"]), orNull(e["scope"]), orNull(e["disposition"])]);
+        const seq = toPlain(e["seq"]);
+        const existing = rows.get(key);
+        if (existing === undefined) {
+            rows.set(key, {
+                node,
+                agent: agentOf.get(node) ?? null,
+                tool: orNull(e["tool"]),
+                scope: orNull(e["scope"]),
+                disposition: orNull(e["disposition"]),
+                reason: orNull(e["reason"]),
+                count: 1,
+                first_seq: seq,
+                last_seq: seq,
+            });
+        }
+        else {
+            existing.count += 1;
+            existing.last_seq = seq;
+        }
+    }
+    return Array.from(rows.values()).sort((a, b) => a.first_seq - b.first_seq);
+}
+/**
+ * Verify integrity, monotonicity and containment from the bundle alone.
+ *
+ * `signer` is the verifier for the bundle's signed anchor — a public key, or
+ * the test signer. Without one the hash chain, monotonicity and containment are
+ * still checked but the anchor signature is NOT; the report says so
+ * (`checks.anchor === "not checked"`), and `ok` then means "consistent,
+ * unverified by key": a consistent full rewrite by someone holding the key
+ * cannot be excluded without the key.
+ */
+export function verifyBundle(bundle, signer = null) {
+    const entries = bundle.entries ?? [];
+    const anchor = (bundle.anchor ?? {});
+    const checks = {
+        integrity: false,
+        monotonicity: false,
+        containment: false,
+        anchor: "not checked",
+    };
+    const failures = [];
+    // (1) integrity: the hash chain, plus the signed anchor when a key is given.
+    const [okChain, err] = AuditLog.verify(entries);
+    if (!okChain)
+        failures.push(`integrity: ${err}`);
+    if (signer !== null) {
+        const [okAnchor, aerr] = AuditLog.verifyAnchor(entries, anchor, signer);
+        checks.anchor = okAnchor ? "verified" : "FAILED";
+        if (!okAnchor)
+            failures.push(`integrity(anchor): ${aerr}`);
+        checks.integrity = okChain && okAnchor;
+    }
+    else {
+        checks.integrity = okChain;
+    }
+    const { auth, parent, failures: afail } = nodeAuthorities(entries);
+    failures.push(...afail);
+    // (2) monotonicity: every child ⊆ its parent.
+    let mono = true;
+    for (const [node, pid] of parent) {
+        if (pid === null || !auth.has(pid) || !auth.has(node))
+            continue;
+        const child = auth.get(node);
+        const p = auth.get(pid);
+        const extra = Array.from(child.scopes).filter((s) => !p.scopes.has(s));
+        if (!child.isNarrowerThan(p) && extra.length > 0) {
+            mono = false;
+            failures.push(`monotonicity: ${node} not ⊆ parent ${pid} (child scopes ` +
+                `[${extra.sort(compareCodePoints).map((s) => `'${s}'`).join(", ")}] not held by parent)`);
+        }
+    }
+    checks.monotonicity = mono && afail.length === 0;
+    // (3) containment: every allowed action's scope within the acting node's authority.
+    let contained = true;
+    let actions = 0;
+    for (const e of entries) {
+        if (toPlain(e["event"]) !== "allow")
+            continue;
+        actions += 1;
+        const node = toPlain(e["node"]);
+        const scope = toPlain(e["scope"]);
+        const ctx = toPlain(e["context"]) ?? {};
+        const a = auth.get(node);
+        if (a === undefined) {
+            contained = false;
+            failures.push(`containment: allow on unknown node ${node}`);
+            continue;
+        }
+        if (!a.permits(scope, ctx).allowed) {
+            contained = false;
+            failures.push(`containment: allow of '${scope}' on ${node} outside its authority ` +
+                `[${Array.from(a.scopes).sort(compareCodePoints).map((s) => `'${s}'`).join(", ")}]`);
+        }
+    }
+    checks.containment = contained;
+    const ok = checks.integrity && checks.monotonicity && checks.containment && failures.length === 0;
+    return {
+        ok,
+        checks,
+        failures,
+        nodes: auth.size,
+        actions_checked: actions,
+        chain_id: orNull(bundle.chain_id),
+    };
+}
+/** Read a bundle from JSON text, keeping every number's original literal. */
+export function parseBundle(text) {
+    return parseJson(text);
+}
+//# sourceMappingURL=evidence.js.map