magenta-canon 0.2.0 → 0.4.0

package/README.md

@@ -19,7 +19,7 @@ MCP host (Claude Code, Claude Desktop, Cursor, …) and downstream MCP tools, an
 
 ```bash
 npx magenta-canon demo                  # full local proof loop: allow · block · witness · verify · tamper
-npx magenta-canon verify --self-test    # verifier self-check: one VERIFIED pass and one tamper FAIL
+npx magenta-canon verify --self-test    # verifier self-check: all verdict levels incl. a tamper FAIL
 npx magenta-canon gateway <config.json> # the stdio MCP capability gateway
 npx magenta-canon mirror --self-test    # external STH mirror: catch operator history rewrites
 ```
@@ -161,12 +161,35 @@ DOWNSTREAM_LOG=/tmp/downstream-calls.log \
 
 # 3. publish evidence and verify it independently
 curl -s :5000/api/trust/evidence > bundle.json
-npx magenta-canon verify bundle.json              # → RESULT: VERIFIED
+npx magenta-canon verify bundle.json --expected-witness-key witness.pub
+                                       # → RESULT: ORIGIN AND INTEGRITY VERIFIED
+# without --expected-witness-key the honest maximum is: RESULT: INTEGRITY VERIFIED
+# (the bundle can vouch for its math, not for who produced it)
 ```
 </details>
 
 Full walkthrough: [`docs/MCP_GATEWAY.md`](docs/MCP_GATEWAY.md).
 
+### Durable evidence (file ledger) — new in 0.4.0
+
+By default evidence lives in memory (the demo's fresh-universe behavior). For
+evidence that **survives a process restart**, point the gateway/control plane
+at an append-only file ledger and pin the witness identity:
+
+```bash
+MAGENTA_LEDGER_FILE=/var/lib/magenta/ledger.jsonl \
+MAGENTA_WITNESS_SECRET=<hex> MAGENTA_WITNESS_PUBLIC=<hex> \
+  <your magenta process>
+```
+
+Every receipt and signed tree head is fsync-committed before it is reported
+recorded; on restart the ledger is strictly replayed (chain, issuer
+signatures, Merkle roots, checkpoint history) or startup fails loudly. One
+exclusive writer per ledger; corruption is refused, never repaired silently.
+This is single-writer local/reference durability — see
+[`docs/FILE_LEDGER.md`](docs/FILE_LEDGER.md) for the format, lock recovery,
+crash-tail policy, backup guidance, and limitations.
+
 ### From the repo vs. as a CLI
 
 - **From a repo checkout** (above): `npm install` then `npm run demo`.
@@ -222,11 +245,14 @@ REFUSED_CALL isError=true  :: Blocked by Magenta capability gate: exceeds delega
 {"name":"refund","args":{"amount_cents":8900,"order_id":"4471"}}     ← only the allowed call
 # the blocked $250 refund is ABSENT — it never reached the tool.
 
-$ npx magenta-canon verify bundle.json
+$ npx magenta-canon verify bundle.json --expected-witness-key witness.pub
+  witness-key source: INDEPENDENT (supplied by caller)
   [PASS] STH signature verifies
+  [PASS] STH witness key matches INDEPENDENTLY supplied key
   [PASS] receipt chain intact
+  [PASS] receipt issuer signatures verify (2/2)
   [PASS] recomputed Merkle root == signed STH root
-  RESULT: VERIFIED            (exit code 0)
+  RESULT: ORIGIN AND INTEGRITY VERIFIED            (exit code 0)
 ```
 
 ## Security model

package/dist/MANIFEST.json

@@ -1,14 +1,15 @@
 {
   "package.json": "8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
-  "scripts/demo-control-plane.js": "3357c8de8e3fe32e73e0be99a3bb02179dff3ee041854d4ee6f8d135e4d8dcbf",
+  "scripts/demo-control-plane.js": "6d58bd7e816029b3c23b8c3b5f8812a5bd8ae1f4b5d6a70851eeaf6cb577dbc1",
   "scripts/intake-cli.js": "189014db22d6fccb034ed1a93ec11efe8905be820bc468366c68bb2cabaf8a97",
   "scripts/magenta-mirror.js": "cf701065f7a6e20f7f44a9b815396aeb5fe031c3f003bcd793b8014ea8801b85",
-  "scripts/magenta-verify.js": "3c41d176a435ae8f53dd49c2418f63be5ad82de7e26fbe9f436a6545f521d331",
+  "scripts/magenta-verify.js": "f79c60944bef65926530c2d0fd5cc35df10319c5831764b035e547b6bfebe715",
   "scripts/mcp-gateway.js": "335923004b73511fe42ea0fc6f2e567afe8018dc95464a79027e4c2537e30de1",
   "server/agent-policy.js": "20dd9150f8244c33aaf14ecdf3a09f471210960d246cda9ab8d5abe0e8433518",
   "server/agent-record.js": "790bbfa2a10601c2bdcd98873e6e41babdf96d1df7c7ca34f19791de4c8b860f",
   "server/crypto.js": "ebbcb2929e7b3651e4ec04c9fbf3dcb656e3ae0d30bf8864f3642f72f3be2f39",
   "server/execution-receipts.js": "171a506df7d1e99f3370de9a41c1a4f0b21b38d1f02edc78d9c44e68c93dbee4",
+  "server/file-ledger-store.js": "92dc58d313be183e53817455ee9fd4ab7cb2f3a171343de66f5db26e0f139d79",
   "server/intake/categories.js": "e9860eee0e2e0fe96c7ade165e5e068fae0874de2c7d39ff796efc91e713013b",
   "server/intake/engine.js": "abb8feacd925520cbf01acc2e932d9ebb037a3d016b053b7b10deaf8f545a605",
   "server/intake/gateway-intake.js": "40514fa489b031c29725e9b837e83998217bbc1ae84cf9259154a16b1faae2e8",
@@ -20,11 +21,13 @@
   "server/intake/rationale.js": "3ea64a1430828ae5a06b41f4e93d06cdd667850d6a2ff9a1e266f98bdfc6c404",
   "server/intake/types.js": "014891c6c8360648d6954b3185ae92d56be625484bf2f0d0f71dac271a59e23b",
   "server/intake/witness.js": "588ad166f4870d65a6ed334c70aaa2deb1d6d96ec97d889902a9eda7528bd34f",
+  "server/ledger-store.js": "fc8a46f925908764bac7a076cffa08053af4c1f93237bee408eb0ed1e61eeca2",
+  "server/ledger.js": "9bf8f132e08d636070d2ede568b2eaf75810be245c90ecd5979d2d4de69af934",
   "server/persistence.js": "2e6b1d0b1c74babbd581780b028c2593256c5ec96c2d60f4c25159e3f54e4e3f",
-  "server/storage.js": "4f1660e9542dcb157148f561efd757d8aa452730c3a09064d3b1314feb16e8c9",
-  "server/transparency-log.js": "42d0d9fd3de9c60389ca882b546d9784e6ef0003895898dd5958d763d54f2f6b",
+  "server/storage.js": "7a7556a6d15d736f028698b6094072daa71eed2230427594edac9d29b531081a",
+  "server/transparency-log.js": "826dbae845726853b0736d10546a2c65596357530b82af0d1a781ac368c69a79",
   "server/trust-bootstrap.js": "57a53a3ee9cd630ada2867e8b087a34b069ba26f86a696d3ead74888dd7e8d5f",
-  "server/witness.js": "e94384a35a4cfce39990e580eb5b572ef9a2d4c4d9bad1a2ed9b5382aba64b1b",
+  "server/witness.js": "1963401588a48817f7e478d3824a4752d8a3f438f277ba4443158abcedfd6a47",
   "shared/canonical.js": "476cee4b5c5702e8a2a198e79c2639cf8ff84000ffb92f68a04433ed2a2f5484",
   "shared/certificates.js": "7844e71a38e1b1324586c7d054b2f5c15222b86446318d1e6dea9bab504a4a73",
   "shared/schema.js": "f89190990e3826e44c722d5e8f5b39fd59b4d3fb9ec047229930a17604e4646c",

package/dist/scripts/demo-control-plane.js

@@ -33,6 +33,7 @@ const node_crypto_1 = require("node:crypto");
 const storage_1 = require("../server/storage");
 const witness_1 = require("../server/witness");
 const agent_record_1 = require("../server/agent-record");
+const witness_2 = require("../server/witness");
 const trust_bootstrap_1 = require("../server/trust-bootstrap");
 const PORT = Number(process.env.PORT ?? 0);
 const HOST = "127.0.0.1";
@@ -164,6 +165,13 @@ const server = (0, node_http_1.createServer)(async (req, res) => {
         sendJson(res, 500, { error: "internal_error", message: e instanceof Error ? e.message : String(e) });
     }
 });
+// File-ledger restart support: rebuild the witness's derived leaf view from
+// any receipts the durable store replayed (no-op in the default memory mode).
+void (async () => {
+    const restored = await storage_1.storage.getExecutionReceipts();
+    if (restored.length > 0)
+        (0, witness_2.rebuildWitnessFromReceipts)([...restored].reverse().map((r) => r.receipt_hash));
+})();
 server.listen(PORT, HOST, () => {
     const addr = server.address();
     const port = typeof addr === "object" && addr ? addr.port : PORT;

package/dist/scripts/magenta-verify.js

@@ -18,12 +18,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyBundle = exports.verifyConsistency = exports.verifyReceiptChain = exports.verifySTH = exports.verifyInclusion = exports.merkleRoot = exports.hashLeaf = exports.chainHash = exports.canonicalHash = exports.canonicalize = exports.VERSION = void 0;
+exports.verifyBundle = exports.verifyReceiptIssuerSignature = exports.verifyConsistency = exports.verifyReceiptChain = exports.verifySTH = exports.verifyInclusion = exports.merkleRoot = exports.hashLeaf = exports.chainHash = exports.canonicalHash = exports.canonicalize = exports.VERSION = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
 /** Verifier version — emitted in output so a verification run is self-describing. */
-exports.VERSION = "magenta-verify/1.0.0 (spec v1)";
+exports.VERSION = "magenta-verify/1.1.0 (spec v1.1)";
 // ── §1 primitives ──────────────────────────────────────────────────────────
 const utf8 = (s) => Buffer.from(s, "utf8");
 const fromHex = (h) => Buffer.from(h, "hex");
@@ -109,17 +109,79 @@ function verifyConsistency(allLeaves, older, newer) {
         merkleRoot(allLeaves.slice(0, newer.tree_size)) === newer.root_hash);
 }
 exports.verifyConsistency = verifyConsistency;
-function verifyBundle(b) {
+const HEX64 = /^[0-9a-f]{64}$/;
+/** Receipt issuer signature (spec §2): Ed25519 over the canonical receipt body
+ *  (all fields except receipt_signature), message = UTF-8 of the hex hash. */
+function verifyReceiptIssuerSignature(receipt) {
+    const { receipt_signature, issuer_pubkey } = receipt;
+    if (typeof receipt_signature !== "string" || typeof issuer_pubkey !== "string")
+        return false;
+    const body = {};
+    for (const k of Object.keys(receipt))
+        if (k !== "receipt_signature")
+            body[k] = receipt[k];
+    try {
+        return tweetnacl_1.default.sign.detached.verify(utf8((0, exports.canonicalHash)(body)), fromHex(receipt_signature), fromHex(issuer_pubkey));
+    }
+    catch {
+        return false;
+    }
+}
+exports.verifyReceiptIssuerSignature = verifyReceiptIssuerSignature;
+function verifyBundle(b, opts = {}) {
     const checks = [];
+    const skipped = [];
+    const reasons = [];
     const add = (name, pass, detail = "") => checks.push({ name, pass, detail });
+    const skip = (name, reason) => skipped.push({ name, reason });
+    // ── witness-key trust input (§5.6): the expected key must be independent ──
+    let witnessKeySource = "none";
+    if (opts.expectedWitnessKey !== undefined) {
+        witnessKeySource = "cli";
+        // Malformed trusted-key input fails closed: a bad key must never silently
+        // downgrade to bundle-trust.
+        if (!HEX64.test(opts.expectedWitnessKey)) {
+            add("expected witness key well-formed", false, "expected key is not 64 lowercase hex chars — failing closed");
+        }
+    }
+    else if (b.sth || b.witness_pubkey) {
+        witnessKeySource = "bundle";
+    }
     if (b.sth) {
-        const expectedKey = b.witness_pubkey ?? b.sth.witness_pubkey;
         add("STH signature verifies", verifySTH(b.sth), `root ${b.sth.root_hash.slice(0, 16)}… size ${b.sth.tree_size}`);
-        add("STH bound to expected witness key", b.sth.witness_pubkey === expectedKey, b.sth.witness_pubkey === expectedKey ? "matches mirrored key" : "WITNESS KEY MISMATCH");
+        // Internal coherence: the bundle's top-level key must agree with the STH's.
+        if (b.witness_pubkey !== undefined) {
+            add("bundle witness_pubkey == STH witness key", b.witness_pubkey === b.sth.witness_pubkey, b.witness_pubkey === b.sth.witness_pubkey ? "bundle is internally coherent" : "BUNDLE KEY FIELDS DISAGREE");
+        }
+        if (witnessKeySource === "cli" && HEX64.test(opts.expectedWitnessKey)) {
+            const match = b.sth.witness_pubkey === opts.expectedWitnessKey;
+            add("STH witness key matches INDEPENDENTLY supplied key", match, match ? "key supplied via --expected-witness-key matches" : "WITNESS KEY MISMATCH — bundle was NOT signed by the trusted witness");
+        }
+        else if (witnessKeySource === "bundle") {
+            skip("witness key trust", "key taken from the bundle itself — supply --expected-witness-key for origin assurance");
+        }
+    }
+    else if (witnessKeySource === "cli") {
+        add("STH present for expected-key comparison", false, "an expected witness key was supplied but the bundle has no STH");
     }
+    const receiptCount = b.receipts?.length ?? 0;
     if (b.receipts && b.receipts.length) {
         const chain = verifyReceiptChain(b.receipts);
         add("receipt chain intact", chain.valid, chain.error ?? `${b.receipts.length} receipts`);
+        // §2 issuer signatures: enforced when present; absence is surfaced, never hidden.
+        const withSig = b.receipts.filter((r) => r.receipt_signature !== undefined
+            || r.issuer_pubkey !== undefined);
+        if (withSig.length > 0) {
+            const bad = withSig.filter((r) => !verifyReceiptIssuerSignature(r));
+            add(`receipt issuer signatures verify (${withSig.length - bad.length}/${withSig.length})`, bad.length === 0, bad.length === 0 ? "each receipt is Ed25519-signed by its issuer over the canonical body"
+                : `INVALID issuer signature on ${bad.length} receipt(s)`);
+            if (withSig.length < b.receipts.length) {
+                add("all receipts carry issuer signatures", false, `${b.receipts.length - withSig.length} receipt(s) missing issuer signature while others are signed`);
+            }
+        }
+        else {
+            skip("receipt issuer signatures", "no receipt carries issuer_pubkey/receipt_signature — issuer authentication not established");
+        }
         if (b.sth) {
             const leaves = b.receipts.map((r) => (0, exports.hashLeaf)(r.receipt_hash));
             const root = merkleRoot(leaves);
@@ -130,6 +192,18 @@ function verifyBundle(b) {
             }
         }
     }
+    // ── caller-required evidence (§5.7): absence of required proof is a FAILURE ──
+    if (opts.minReceipts !== undefined) {
+        add(`bundle contains >= ${opts.minReceipts} receipt(s)`, receiptCount >= opts.minReceipts, `${receiptCount} present`);
+    }
+    if (opts.requireReceiptHash !== undefined) {
+        const found = (b.receipts ?? []).some((r) => r.receipt_hash === opts.requireReceiptHash);
+        add("required receipt_hash present in bundle", found, found ? `receipt ${opts.requireReceiptHash.slice(0, 16)}… is in the verified chain` : "REQUIRED RECEIPT ABSENT");
+    }
+    if (opts.requireActionHash !== undefined) {
+        const found = (b.receipts ?? []).some((r) => r.action_hash === opts.requireActionHash);
+        add("required action_hash present in bundle", found, found ? "a receipt commits to the required action" : "REQUIRED ACTION ABSENT");
+    }
     if (b.inclusion) {
         const inc = verifyInclusion(b.inclusion.leaf_hash, b.inclusion.proof, b.inclusion.root_hash);
         add(`inclusion proof for leaf #${b.inclusion.index}`, inc, "leaf is provably in the log under the root");
@@ -148,15 +222,127 @@ function verifyBundle(b) {
             add("reveal target exists", false, `no receipt at index ${b.reveal.index}`);
         }
     }
-    return { checks, allPassed: checks.length > 0 && checks.every((c) => c.pass) };
+    const allPassed = checks.length > 0 && checks.every((c) => c.pass);
+    // ── verdict assignment (never silently upgraded) ────────────────────────────
+    let verdict;
+    if (!allPassed) {
+        verdict = "VERIFICATION FAILED";
+        reasons.push(checks.some((c) => !c.pass) ? "one or more performed checks failed" : "no checks could be performed");
+    }
+    else if (receiptCount === 0 && !b.inclusion && !opts.allowEmptyLog) {
+        verdict = "INCOMPLETE EVIDENCE";
+        reasons.push("bundle proves no action: zero receipts and no inclusion proof (use --allow-empty-log for checkpoint-only diagnostics)");
+    }
+    else if (witnessKeySource === "cli") {
+        verdict = "ORIGIN AND INTEGRITY VERIFIED";
+        reasons.push("all checks passed and the witness key matched an independently supplied trusted key");
+    }
+    else {
+        verdict = "INTEGRITY VERIFIED";
+        reasons.push("all checks passed, but the witness key came from the bundle itself — a forger with a fresh key can fabricate a self-consistent history; supply --expected-witness-key (or corroborate via an external mirror) for origin assurance");
+        if (receiptCount === 0 && opts.allowEmptyLog) {
+            reasons.push("EMPTY LOG accepted in explicit diagnostic mode (--allow-empty-log): this verifies a checkpoint, not any action");
+        }
+    }
+    if (witnessKeySource === "cli" && verdict === "ORIGIN AND INTEGRITY VERIFIED" && receiptCount === 0 && opts.allowEmptyLog) {
+        reasons.push("EMPTY LOG accepted in explicit diagnostic mode (--allow-empty-log): this verifies a checkpoint, not any action");
+    }
+    return { checks, skipped, allPassed, verdict, witnessKeySource, reasons };
 }
 exports.verifyBundle = verifyBundle;
 // ── CLI ───────────────────────────────────────────────────────────────────────
+const USAGE = `usage: magenta-canon verify <bundle.json> [options]
+       magenta-canon verify --self-test
+
+options:
+  --expected-witness-key <file-or-hex>  independently trusted witness public key.
+                                        REQUIRED for "ORIGIN AND INTEGRITY VERIFIED";
+                                        without it the best result is
+                                        "INTEGRITY VERIFIED" (bundle-trusted key).
+  --require-receipt <hash>              fail unless this exact receipt_hash is present
+  --require-action-hash <hash>          fail unless a receipt commits to this action_hash
+  --min-receipts <n>                    fail unless the bundle has at least n receipts
+  --allow-empty-log                     diagnostic mode: permit zero-receipt checkpoints
+  --json                                machine-readable outcome on stdout
+  --version                             print verifier version
+
+exit codes: 0 verified (either level) · 1 verification failed · 2 incomplete evidence / usage
+`;
 function printResult(r) {
     console.log(`  verifier: ${exports.VERSION}`);
+    console.log(`  witness-key source: ${r.witnessKeySource === "cli" ? "INDEPENDENT (supplied by caller)"
+        : r.witnessKeySource === "bundle" ? "bundle-provided (NOT independently trusted)" : "none"}`);
     for (const c of r.checks)
         console.log(`  [${c.pass ? "PASS" : "FAIL"}] ${c.name}${c.detail ? `  — ${c.detail}` : ""}`);
-    console.log(`\n  RESULT: ${r.allPassed ? "VERIFIED" : "VERIFICATION FAILED"}`);
+    for (const s of r.skipped)
+        console.log(`  [SKIP] ${s.name}  — ${s.reason}`);
+    for (const reason of r.reasons)
+        console.log(`  note: ${reason}`);
+    console.log(`\n  RESULT: ${r.verdict}`);
+}
+const exitCodeFor = (v) => v === "VERIFICATION FAILED" ? 1 : v === "INCOMPLETE EVIDENCE" ? 2 : 0;
+/** Accept a 64-hex key directly or a path to a file containing one. Fails closed. */
+function loadExpectedKey(arg) {
+    const raw = (() => {
+        try {
+            return (0, node_fs_1.readFileSync)(arg, "utf8");
+        }
+        catch {
+            return arg;
+        }
+    })();
+    return raw.trim().toLowerCase();
+}
+function parseCliArgs(argv) {
+    const opts = {};
+    let bundlePath;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--expected-witness-key": {
+                const v = argv[++i];
+                if (!v)
+                    return { error: "--expected-witness-key requires a value" };
+                opts.expectedWitnessKey = loadExpectedKey(v);
+                break;
+            }
+            case "--require-receipt": {
+                const v = argv[++i];
+                if (!v)
+                    return { error: "--require-receipt requires a value" };
+                opts.requireReceiptHash = v.toLowerCase();
+                break;
+            }
+            case "--require-action-hash": {
+                const v = argv[++i];
+                if (!v)
+                    return { error: "--require-action-hash requires a value" };
+                opts.requireActionHash = v.toLowerCase();
+                break;
+            }
+            case "--min-receipts": {
+                const v = Number(argv[++i]);
+                if (!Number.isInteger(v) || v < 0)
+                    return { error: "--min-receipts requires a non-negative integer" };
+                opts.minReceipts = v;
+                break;
+            }
+            case "--allow-empty-log":
+                opts.allowEmptyLog = true;
+                break;
+            case "--json":
+                json = true;
+                break;
+            default:
+                if (a.startsWith("-"))
+                    return { error: `unknown option '${a}'` };
+                if (bundlePath)
+                    return { error: "multiple bundle paths given" };
+                bundlePath = a;
+        }
+    }
+    return { bundlePath, opts, json };
 }
 function selfTest() {
     // Build a tiny log + STH with an ephemeral witness key, entirely self-contained.
@@ -167,27 +353,59 @@ function selfTest() {
     const root_hash = merkleRoot(leaves);
     const sth = { tree_size: 3, root_hash, timestamp: "2026-05-31T00:00:00Z", witness_pubkey, signature: "" };
     sth.signature = Buffer.from(tweetnacl_1.default.sign.detached(utf8(sthMessage(sth)), kp.secretKey)).toString("hex");
-    console.log("── self-test: valid evidence ──");
-    printResult(verifyBundle({ witness_pubkey, sth, inclusion: { index: 1, leaf_hash: leaves[1], proof: [
+    const valid = { witness_pubkey, sth, inclusion: { index: 1, leaf_hash: leaves[1], proof: [
                 { sibling: leaves[0], right: false }, { sibling: leaves[2], right: true },
-            ], root_hash } }));
+            ], root_hash } };
+    console.log("── self-test: valid evidence, bundle-trusted key (integrity only) ──");
+    printResult(verifyBundle(valid));
+    console.log("\n── self-test: valid evidence + independently pinned key (full origin) ──");
+    printResult(verifyBundle(valid, { expectedWitnessKey: witness_pubkey }));
+    console.log("\n── self-test: ATTACK — fabricated history under a fresh key (must NOT gain origin) ──");
+    const attacker = tweetnacl_1.default.sign.keyPair();
+    const forgedKey = Buffer.from(attacker.publicKey).toString("hex");
+    const forgedSth = { ...sth, witness_pubkey: forgedKey, signature: "" };
+    forgedSth.signature = Buffer.from(tweetnacl_1.default.sign.detached(utf8(sthMessage(forgedSth)), attacker.secretKey)).toString("hex");
+    printResult(verifyBundle({ witness_pubkey: forgedKey, sth: forgedSth, inclusion: valid.inclusion }, { expectedWitnessKey: witness_pubkey }));
+    console.log("\n── self-test: empty checkpoint without --allow-empty-log (must be INCOMPLETE) ──");
+    const emptyRoot = merkleRoot([]);
+    const emptySth = { tree_size: 0, root_hash: emptyRoot, timestamp: "2026-05-31T00:00:00Z", witness_pubkey, signature: "" };
+    emptySth.signature = Buffer.from(tweetnacl_1.default.sign.detached(utf8(sthMessage(emptySth)), kp.secretKey)).toString("hex");
+    printResult(verifyBundle({ witness_pubkey, sth: emptySth, receipts: [] }));
     console.log("\n── self-test: tampered STH root (must FAIL) ──");
     printResult(verifyBundle({ witness_pubkey, sth: { ...sth, root_hash: "00".repeat(32) } }));
 }
 function main() {
-    const arg = process.argv[2];
-    if (arg === "--version") {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "--version") {
         console.log(exports.VERSION);
         return;
     }
-    if (!arg || arg === "--self-test") {
+    if (argv.length === 0 || argv[0] === "--self-test") {
         selfTest();
         return;
     }
-    const bundle = JSON.parse((0, node_fs_1.readFileSync)(arg, "utf8"));
-    const result = verifyBundle(bundle);
-    printResult(result);
-    process.exit(result.allPassed ? 0 : 1);
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const parsed = parseCliArgs(argv);
+    if ("error" in parsed) {
+        console.error(`magenta-verify: ${parsed.error}\n\n${USAGE}`);
+        process.exit(2);
+    }
+    if (!parsed.bundlePath) {
+        console.error(`magenta-verify: missing <bundle.json>\n\n${USAGE}`);
+        process.exit(2);
+    }
+    const bundle = JSON.parse((0, node_fs_1.readFileSync)(parsed.bundlePath, "utf8"));
+    const result = verifyBundle(bundle, parsed.opts);
+    if (parsed.json) {
+        console.log(JSON.stringify({ version: exports.VERSION, ...result }, null, 2));
+    }
+    else {
+        printResult(result);
+    }
+    process.exit(exitCodeFor(result.verdict));
 }
 // Run as CLI only when executed directly (not when imported by tests).
 if (process.argv[1] && /magenta-verify\.[cm]?[jt]s$/.test(process.argv[1]))