magenta-canon 0.4.0 → 0.6.0

package/README.md

@@ -22,6 +22,7 @@ npx magenta-canon demo                  # full local proof loop: allow · block
 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
+npx magenta-canon sentinel pack         # Sentinel Mesh: invariant-check the packed artifact
 ```
 
 Magenta Canon is a proven **reference implementation**, not production-hosted infra
@@ -190,6 +191,71 @@ 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.
 
+### Witness identity & authorized key rotation — new in 0.5.0
+
+Instead of raw env keys, the witness can hold its identity in an **encrypted
+keystore** (scrypt → AES-256-GCM, header-bound AAD) and **rotate its signing
+key under cryptographic authorization** — the outgoing key signs the rotation,
+the incoming key countersigns, and the signed rotation record is committed
+**into the evidence ledger itself** before the new key signs anything:
+
+```bash
+MAGENTA_LEDGER_FILE=/var/lib/magenta/ledger.jsonl \
+MAGENTA_WITNESS_KEYFILE=/var/lib/magenta/witness.keystore \
+MAGENTA_WITNESS_PASSPHRASE=<operator passphrase> \
+  <your magenta process>
+```
+
+**Key material alone never grants authority — a validated, durably committed
+rotation record does.** Verifiers replay the rotation chain from a pinned
+anchor: historical checkpoints validate against the key that was authorized
+for their epoch, substitution/rollback/forks are refused, and
+`--expected-witness-key` still earns `ORIGIN AND INTEGRITY VERIFIED` across
+rotations from the *original* pinned key. A crash at any point in the rotation
+ceremony reconciles deterministically at next boot (recover the committed
+fact, abandon the orphaned key, or fail closed — never silent activation).
+
+**Scope honesty:** this is local/reference custody (file keystore, not
+KMS/HSM), and it covers the **witness** identity only — founder/receipt-issuer
+key custody is a separate forthcoming lane (in file-ledger mode the issuer key
+still regenerates on restart; old evidence keeps verifying). Keystore format,
+rotation protocol, boot-reconciliation table, and operator procedures:
+[`docs/WITNESS_IDENTITY.md`](docs/WITNESS_IDENTITY.md) (ships in the package).
+
+### Sentinel Mesh foundation — new in 0.6.0
+
+Magenta Canon 0.6.0 introduces an **executable Sentinel Mesh** that protects
+repository state, npm artifacts, dependency boundaries, release promotion,
+witness identity, and cryptographically authorized witness-key rotation:
+versioned invariants, deterministic repository / artifact / witness
+evaluation, evidence-preserving violations, and scoped release-promotion
+blocking.
+
+```bash
+magenta-canon sentinel repository        # invariant-check a git repository
+magenta-canon sentinel artifact <tgz|dir>  # invariant-check a packed artifact
+magenta-canon sentinel pack              # npm pack, then check the result
+magenta-canon sentinel witness --ledger ledger.jsonl  # witness rotation-authority check
+magenta-canon sentinel invariants        # list the invariant registry
+```
+
+The **Witness & Rotation Sentinel** (MC-WIT-001…011) watches the 0.5.0
+rotation-authority model itself: pinned-anchor continuity, dual-signed
+rotation validity, exact epoch boundaries, epoch-correct STH signing,
+retired-key resurrection / pre-activation refusal, and keystore↔ledger
+agreement — re-derived independently from the published wire formats, so it
+can disagree with a wrong (or compromised) server.
+
+Sentinels are read-only, redacting (paths + fingerprints, never secret
+bodies), deterministic, network-free, and emit `magenta-sentinel-violation/1`
+evidence records; exit codes map to a scoped promotion decision (`eligible` /
+`blocked` / `requires-independent-review`). Records at this layer are
+**unsigned local diagnostics**, and the freeze is a release/build promotion
+gate — **not** a production kill switch, a hosted Sentinel service, or
+complete Mesh coverage (ledger/execution/configuration sentinels are future
+lanes). Honest scope and the full model:
+[`docs/SENTINEL_MESH.md`](docs/SENTINEL_MESH.md).
+
 ### From the repo vs. as a CLI
 
 - **From a repo checkout** (above): `npm install` then `npm run demo`.

package/bin/magenta-canon.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * magenta-canon — CLI entry point for the open-source reference implementation.
  *
@@ -48,6 +48,8 @@ Usage:
                                      verify <mirror>, check <mirror> <bundle>, --self-test.
   magenta-canon mirror-feed ...      One feed cycle for a mirror operator:
                                      (--bundle <file> | --url <evidence-url>) --mirror <file>.
+  magenta-canon sentinel <cmd>       Sentinel Mesh: repository | artifact <tgz|dir> |
+                                     pack | invariants  (deterministic invariant checks).
   magenta-canon --help               Show this help.
   magenta-canon --version            Print the version.
 
@@ -110,6 +112,11 @@ switch (sub) {
     // Plain-Node operator helper; delegates all mirror semantics to `mirror`.
     run(process.execPath, [path.join(ROOT, "scripts", "mirror-feed.mjs"), ...rest], { cwd: process.cwd() });
     break;
+  case "sentinel":
+    // Sentinel Mesh foundation: deterministic invariant evaluation over a
+    // repository or a packed artifact (read-only; unsigned local diagnostics).
+    runTs("scripts/magenta-sentinel.ts", rest, { cwd: process.cwd() });
+    break;
   case "-v":
   case "--version":
   case "version":

package/dist/MANIFEST.json

@@ -1,15 +1,16 @@
 {
   "package.json": "8005a3491db7d92f36ac66369861589f9c47123d3a7c71e643fc2c06168cd45a",
-  "scripts/demo-control-plane.js": "6d58bd7e816029b3c23b8c3b5f8812a5bd8ae1f4b5d6a70851eeaf6cb577dbc1",
+  "scripts/demo-control-plane.js": "3a559f39d17c1a403988e731e053d0d071cbd41ab595fd6246910f852337ab2f",
   "scripts/intake-cli.js": "189014db22d6fccb034ed1a93ec11efe8905be820bc468366c68bb2cabaf8a97",
   "scripts/magenta-mirror.js": "cf701065f7a6e20f7f44a9b815396aeb5fe031c3f003bcd793b8014ea8801b85",
-  "scripts/magenta-verify.js": "f79c60944bef65926530c2d0fd5cc35df10319c5831764b035e547b6bfebe715",
+  "scripts/magenta-sentinel.js": "0280d7584524201551c61a93beb1f2ee4964e76b0e44eb7c9d15a0f5a95cafdc",
+  "scripts/magenta-verify.js": "0bb65ef6ff1350789eecc4f0434ca94dcf3a89930f8ef1d62cc38100e18094ba",
   "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/file-ledger-store.js": "216fe644e1753a5527bec6ccf58175d22ec695c006e1927dc3090be11df9c124",
   "server/intake/categories.js": "e9860eee0e2e0fe96c7ade165e5e068fae0874de2c7d39ff796efc91e713013b",
   "server/intake/engine.js": "abb8feacd925520cbf01acc2e932d9ebb037a3d016b053b7b10deaf8f545a605",
   "server/intake/gateway-intake.js": "40514fa489b031c29725e9b837e83998217bbc1ae84cf9259154a16b1faae2e8",
@@ -24,12 +25,21 @@
   "server/ledger-store.js": "fc8a46f925908764bac7a076cffa08053af4c1f93237bee408eb0ed1e61eeca2",
   "server/ledger.js": "9bf8f132e08d636070d2ede568b2eaf75810be245c90ecd5979d2d4de69af934",
   "server/persistence.js": "2e6b1d0b1c74babbd581780b028c2593256c5ec96c2d60f4c25159e3f54e4e3f",
+  "server/sentinel/artifact-sentinel.js": "93bae917af313c9247f8062af148e7c25ccfd16d0507fa85e755c64056715f8d",
+  "server/sentinel/promotion.js": "68ac5e54eb8c07d5c75ba0d2325d595b1583557840cc46322b2053dd9924a0be",
+  "server/sentinel/repository-sentinel.js": "722e973c8860cf281b29db8c4a22ec3cf473afcb088247916e8278d5e11638cf",
+  "server/sentinel/rules.js": "ab24435df4f6f5b10f8b721fde37fe7fa894453648f17f04923cab56020c459f",
+  "server/sentinel/tar-reader.js": "ded811eefebf3e4afa332d1bc0a48318cc22ad824222eb15b2dc08eb51048272",
+  "server/sentinel/violation.js": "70d44ae5eb43a560fada399b31eac1a2beccb66916340e1f3e9b549731776b38",
+  "server/sentinel/witness-sentinel.js": "f024dbe9fb505c7520ec466ed31bf9b3284c3c3066dbd287121d2e4397d3fb0a",
   "server/storage.js": "7a7556a6d15d736f028698b6094072daa71eed2230427594edac9d29b531081a",
-  "server/transparency-log.js": "826dbae845726853b0736d10546a2c65596357530b82af0d1a781ac368c69a79",
+  "server/transparency-log.js": "7f238edc5cad4edc2c70a7b3e1977197cf2087e77789d181ffae0035f948391b",
   "server/trust-bootstrap.js": "57a53a3ee9cd630ada2867e8b087a34b069ba26f86a696d3ead74888dd7e8d5f",
-  "server/witness.js": "1963401588a48817f7e478d3824a4752d8a3f438f277ba4443158abcedfd6a47",
+  "server/witness-identity.js": "9dd5b6e63aefa00171a838d1cd27e3c09ddcb7d39512427ebe537763fe5fc42e",
+  "server/witness.js": "b1a8209d4dae4ffafc3ca4a158474b369250472ba80cef03bd92048282be91a4",
   "shared/canonical.js": "476cee4b5c5702e8a2a198e79c2639cf8ff84000ffb92f68a04433ed2a2f5484",
   "shared/certificates.js": "7844e71a38e1b1324586c7d054b2f5c15222b86446318d1e6dea9bab504a4a73",
+  "shared/invariants.js": "414a2aac034c9b28d0e32fc4afefb9b9ab723ed465b4aba1f8da98dab08363d4",
   "shared/schema.js": "f89190990e3826e44c722d5e8f5b39fd59b4d3fb9ec047229930a17604e4646c",
   "shared/terminating-kernel.js": "8e2aa68d47d6780e4a70822482e3e410924e9d1af843f301a487da0af37ed047"
 }

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

@@ -34,6 +34,8 @@ 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 file_ledger_store_1 = require("../server/file-ledger-store");
+const ledger_1 = require("../server/ledger");
 const trust_bootstrap_1 = require("../server/trust-bootstrap");
 const PORT = Number(process.env.PORT ?? 0);
 const HOST = "127.0.0.1";
@@ -153,12 +155,35 @@ const server = (0, node_http_1.createServer)(async (req, res) => {
         // ── GET /api/trust/evidence ──────────────────────────────────────────────
         if (method === "GET" && url === "/api/trust/evidence") {
             const receipts = [...(await storage_1.storage.getExecutionReceipts())].reverse(); // creation order
+            const rotations = ledger_1.sharedLedgerStore instanceof file_ledger_store_1.FileLedgerStore ? ledger_1.sharedLedgerStore.allRotations() : [];
             return sendJson(res, 200, {
                 witness_pubkey: witness_1.witnessLog.witnessPublicKey,
                 sth: witness_1.witnessLog.latestSTH() ?? null,
                 receipts,
+                ...(rotations.length > 0 ? { rotations } : {}),
             });
         }
+        // ── POST /internal/witness/rotate ────────────────────────────────────────
+        // Full continuity protocol (keystore + durable ledger required): mint →
+        // durably commit the signed rotation record → activate → switch epoch.
+        if (method === "POST" && url === "/internal/witness/rotate") {
+            if (!internalAuthOk(req, res))
+                return;
+            let body;
+            try {
+                body = (await readBody(req));
+            }
+            catch (e) {
+                return sendJson(res, 400, { error: "bad_request", message: e.message });
+            }
+            try {
+                const record = (0, witness_2.rotateWitness)(body?.reason ?? "operator-initiated rotation");
+                return sendJson(res, 200, { rotated: true, rotation_id: record.rotation_id, new_version: record.new_version, new_pubkey: record.new_pubkey });
+            }
+            catch (e) {
+                return sendJson(res, 409, { error: "rotation_refused", message: e.message });
+            }
+        }
         sendJson(res, 404, { error: "not_found", message: `${method} ${url} is not served by the demo control plane` });
     }
     catch (e) {

package/dist/scripts/magenta-sentinel.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * magenta-sentinel — Sentinel Mesh CLI (foundation layer).
+ *
+ *   magenta-canon sentinel repository [--root <dir>] [--json]
+ *   magenta-canon sentinel artifact <tgz|package-dir> [--expected-version <v>] [--json]
+ *   magenta-canon sentinel pack [--json]      (npm pack, then evaluate the tarball)
+ *
+ * Exit codes: 0 eligible/diagnostic-only · 1 blocked · 2 requires-independent-review
+ *             3 usage / subject unreadable.
+ *
+ * Honesty: all records emitted here are UNSIGNED LOCAL DIAGNOSTICS. They are
+ * structured findings, not third-party-verifiable attestations.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const repository_sentinel_1 = require("../server/sentinel/repository-sentinel");
+const artifact_sentinel_1 = require("../server/sentinel/artifact-sentinel");
+const witness_sentinel_1 = require("../server/sentinel/witness-sentinel");
+const promotion_1 = require("../server/sentinel/promotion");
+const invariants_1 = require("../shared/invariants");
+const USAGE = `magenta-sentinel — deterministic invariant evaluation (Sentinel Mesh foundation)
+
+Usage:
+  sentinel repository [--root <dir>] [--json]
+  sentinel artifact <tarball.tgz | package-dir> [--expected-version <v>] [--json]
+  sentinel pack [--json]
+  sentinel witness --ledger <file> [--keystore <file>] [--passphrase-env <VAR>]
+                   [--anchor <pubkey-hex>] [--json]
+  sentinel invariants [--json]
+
+Exit: 0 eligible/diagnostic-only · 1 blocked · 2 requires review · 3 usage/unreadable
+`;
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i >= 0) {
+        args.splice(i, 1);
+        return true;
+    }
+    return false;
+}
+function option(args, name) {
+    const i = args.indexOf(name);
+    if (i >= 0 && i + 1 < args.length) {
+        const v = args[i + 1];
+        args.splice(i, 2);
+        return v;
+    }
+    return undefined;
+}
+function printHuman(kind, subject, result, promo) {
+    console.log(`magenta-sentinel ${kind}`);
+    console.log(`  subject: ${subject}`);
+    console.log(`  invariants evaluated: ${result.evaluated_invariants.length} — passed ${result.passed.length}, failed ${result.failed.length}`);
+    for (const f of result.findings) {
+        console.log(`  [FAIL] ${f.invariant_id} (${f.severity}, ${f.disposition})`);
+        console.log(`         observed: ${f.observed}`);
+        console.log(`         paths: ${f.paths.join(", ") || "-"}`);
+    }
+    for (const v of result.violations) {
+        console.log(`  evidence: ${v.invariant_id} record ${v.record_hash.slice(0, 16)}… (${v.assurance})`);
+    }
+    if (result.findings.length === 0)
+        console.log("  all evaluated invariants hold");
+    console.log(`  PROMOTION: ${promo.decision.toUpperCase()}${promo.evidence_complete ? "" : " (evidence INCOMPLETE)"}`);
+}
+function exitFor(promo) {
+    switch (promo.decision) {
+        case "eligible":
+        case "diagnostic-only": return 0;
+        case "blocked": return 1;
+        case "requires-independent-review": return 2;
+    }
+}
+const argv = process.argv.slice(2);
+const sub = argv.shift();
+const json = flag(argv, "--json");
+try {
+    if (sub === "repository") {
+        const root = option(argv, "--root") ?? process.cwd();
+        const res = (0, repository_sentinel_1.runRepositorySentinel)({ repoRoot: path.resolve(root) });
+        const promo = (0, promotion_1.decidePromotion)({ subject: `repository:${res.subject_identity}`, findings: res.findings, violations: res.violations });
+        if (json)
+            console.log(JSON.stringify({ result: res, promotion: promo }, null, 2));
+        else
+            printHuman("repository", res.subject_identity, res, promo);
+        process.exit(exitFor(promo));
+    }
+    else if (sub === "artifact") {
+        const target = argv.find((a) => !a.startsWith("-"));
+        if (!target) {
+            console.error("sentinel artifact: missing <tarball|dir>\n\n" + USAGE);
+            process.exit(3);
+        }
+        const expectedVersion = option(argv, "--expected-version");
+        const res = (0, artifact_sentinel_1.runArtifactSentinel)(path.resolve(target), { expectedVersion });
+        const promo = (0, promotion_1.decidePromotion)({ subject: `artifact:${res.subject_identity}`, findings: res.findings, violations: res.violations });
+        if (json)
+            console.log(JSON.stringify({ result: res, promotion: promo }, null, 2));
+        else
+            printHuman("artifact", `${res.artifact_name ?? "?"}@${res.artifact_version ?? "?"} (${res.subject_identity.slice(0, 19)}…, ${res.file_count} files)`, res, promo);
+        process.exit(exitFor(promo));
+    }
+    else if (sub === "pack") {
+        const out = (0, node_child_process_1.execFileSync)("npm", ["pack", "--silent"], { cwd: process.cwd(), encoding: "utf8", shell: process.platform === "win32" });
+        const tgz = out.trim().split(/\r?\n/).pop();
+        if (!(0, node_fs_1.existsSync)(tgz)) {
+            console.error(`sentinel pack: npm pack did not produce ${tgz}`);
+            process.exit(3);
+        }
+        const res = (0, artifact_sentinel_1.runArtifactSentinel)(path.resolve(tgz));
+        const promo = (0, promotion_1.decidePromotion)({ subject: `artifact:${res.subject_identity}`, findings: res.findings, violations: res.violations });
+        if (json)
+            console.log(JSON.stringify({ result: res, promotion: promo, tarball: tgz }, null, 2));
+        else {
+            console.log(`  packed: ${tgz}`);
+            printHuman("artifact", `${res.artifact_name}@${res.artifact_version}`, res, promo);
+        }
+        process.exit(exitFor(promo));
+    }
+    else if (sub === "witness") {
+        const ledger = option(argv, "--ledger");
+        if (!ledger) {
+            console.error("sentinel witness: missing --ledger <file>\n\n" + USAGE);
+            process.exit(3);
+        }
+        const keystore = option(argv, "--keystore");
+        const res = (0, witness_sentinel_1.runWitnessSentinel)({
+            ledgerPath: path.resolve(ledger),
+            keystorePath: keystore ? path.resolve(keystore) : undefined,
+            passphraseEnv: option(argv, "--passphrase-env"),
+            anchorPubkey: option(argv, "--anchor"),
+        });
+        const promo = (0, promotion_1.decidePromotion)({ subject: `witness:${res.subject_identity}`, findings: res.findings, violations: res.violations });
+        if (json)
+            console.log(JSON.stringify({ result: res, promotion: promo }, null, 2));
+        else {
+            printHuman("witness", `${res.subject_identity.slice(0, 27)}… (${res.ledger_sth_count} STH, ${res.ledger_rotation_count} rotation(s), tip ${res.tip_fingerprint ?? "-"})`, res, promo);
+            for (const n of res.not_evaluated)
+                console.log(`  [NOT EVALUATED] ${n.invariant_id}: ${n.reason}`);
+            if (res.incomplete_tail_ignored)
+                console.log("  note: incomplete trailing ledger line ignored (crash-tail semantics)");
+        }
+        process.exit(exitFor(promo));
+    }
+    else if (sub === "invariants") {
+        if (json)
+            console.log(JSON.stringify(invariants_1.INVARIANTS, null, 2));
+        else
+            for (const i of invariants_1.INVARIANTS)
+                console.log(`${i.id}  v${i.version}  ${i.status.padEnd(9)} ${i.severity.padEnd(8)} ${i.disposition.padEnd(26)} ${i.name}`);
+        process.exit(0);
+    }
+    else {
+        process.stdout.write(USAGE);
+        process.exit(sub === undefined || sub === "--help" || sub === "-h" ? 0 : 3);
+    }
+}
+catch (e) {
+    if (e instanceof artifact_sentinel_1.TarError) {
+        console.error(`sentinel: artifact unreadable (refusing to guess): ${e.message}`);
+        process.exit(3);
+    }
+    console.error(`sentinel: ${e.message}`);
+    process.exit(3);
+}

package/dist/scripts/magenta-verify.js

@@ -18,7 +18,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.verifyBundle = exports.verifyReceiptIssuerSignature = exports.verifyRotationChain = 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"));
@@ -109,6 +109,59 @@ function verifyConsistency(allLeaves, older, newer) {
         merkleRoot(allLeaves.slice(0, newer.tree_size)) === newer.root_hash);
 }
 exports.verifyConsistency = verifyConsistency;
+/** Validate a rotation chain from an anchor key. Pure re-implementation of
+ *  spec magenta-rotation/1 (sigs are Ed25519 over utf8(canonicalHash(body))). */
+function verifyRotationChain(anchorPubkey, rotations) {
+    const GENESIS = "0".repeat(64);
+    let active = anchorPubkey;
+    let activeVersion = rotations.length ? rotations[0].old_version : 1;
+    let prev = GENESIS;
+    let lastBoundary = -1;
+    const seen = new Set();
+    const epochs = [{ pubkey: anchorPubkey, fromExclusive: -1 }];
+    for (const r of rotations) {
+        if (r.spec !== "magenta-rotation/1")
+            return { valid: false, reason: `unsupported rotation spec '${r.spec}'` };
+        if (seen.has(r.rotation_id))
+            return { valid: false, reason: "duplicate rotation_id" };
+        seen.add(r.rotation_id);
+        if (r.old_pubkey !== active)
+            return { valid: false, reason: "rotation old_pubkey is not the active key" };
+        if (r.old_version !== activeVersion)
+            return { valid: false, reason: "rotation old_version mismatch" };
+        if (r.new_version !== activeVersion + 1)
+            return { valid: false, reason: "skipped key version" };
+        if (r.previous_rotation_hash !== prev)
+            return { valid: false, reason: "rotation chain hash broken" };
+        if (r.effective_tree_size <= lastBoundary)
+            return { valid: false, reason: "rotation boundaries must strictly increase" };
+        const body = {};
+        for (const k of Object.keys(r)) {
+            if (k !== "old_key_signature" && k !== "new_key_countersignature" && k !== "record_hash")
+                body[k] = r[k];
+        }
+        const h = (0, exports.canonicalHash)(body);
+        try {
+            if (!tweetnacl_1.default.sign.detached.verify(utf8(h), fromHex(r.old_key_signature), fromHex(r.old_pubkey)))
+                return { valid: false, reason: "old-key authorization signature invalid" };
+            if (!tweetnacl_1.default.sign.detached.verify(utf8(h), fromHex(r.new_key_countersignature), fromHex(r.new_pubkey)))
+                return { valid: false, reason: "new-key countersignature invalid" };
+        }
+        catch {
+            return { valid: false, reason: "malformed rotation signature material" };
+        }
+        if ((0, exports.canonicalHash)({ ...body, old_key_signature: r.old_key_signature, new_key_countersignature: r.new_key_countersignature }) !== r.record_hash) {
+            return { valid: false, reason: "rotation record_hash mismatch" };
+        }
+        active = r.new_pubkey;
+        activeVersion = r.new_version;
+        prev = r.record_hash;
+        lastBoundary = r.effective_tree_size;
+        epochs.push({ pubkey: r.new_pubkey, fromExclusive: r.effective_tree_size });
+    }
+    return { valid: true, epochs, tipPubkey: active };
+}
+exports.verifyRotationChain = verifyRotationChain;
 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. */
@@ -150,10 +203,31 @@ function verifyBundle(b, opts = {}) {
     if (b.sth) {
         add("STH signature verifies", verifySTH(b.sth), `root ${b.sth.root_hash.slice(0, 16)}… size ${b.sth.tree_size}`);
         // Internal coherence: the bundle's top-level key must agree with the STH's.
+        // (With rotations, the top-level key is the chain TIP by construction.)
         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)) {
+        if (b.rotations && b.rotations.length > 0) {
+            // Rotation continuity: the pinned key (or, integrity-only, the chain's
+            // own anchor) must chain by signed authorization+countersignature to
+            // the key that signed this STH at its tree size.
+            const anchor = (witnessKeySource === "cli" && HEX64.test(opts.expectedWitnessKey))
+                ? opts.expectedWitnessKey
+                : b.rotations[0].old_pubkey;
+            const chain = verifyRotationChain(anchor, b.rotations);
+            add(`rotation chain validates from ${witnessKeySource === "cli" ? "PINNED anchor" : "bundle anchor"} (${b.rotations.length} rotation(s))`, chain.valid, chain.valid ? `tip key …${chain.tipPubkey.slice(-12)}` : `ROTATION CHAIN INVALID: ${chain.reason}`);
+            if (chain.valid) {
+                let expected = chain.epochs[0].pubkey;
+                for (const e of chain.epochs)
+                    if (b.sth.tree_size > e.fromExclusive)
+                        expected = e.pubkey;
+                add("STH signed by the authorized key for its epoch", b.sth.witness_pubkey === expected, b.sth.witness_pubkey === expected ? "epoch boundary respected" : "STH KEY OUTSIDE THE AUTHORIZED ROTATION CHAIN");
+            }
+            if (witnessKeySource === "bundle") {
+                skip("witness key trust", "rotation chain anchored to the bundle's own first key — supply --expected-witness-key (the version-1 anchor) for origin assurance");
+            }
+        }
+        else 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");
         }

package/dist/server/file-ledger-store.js

@@ -86,6 +86,8 @@ const node_crypto_1 = require("node:crypto");
 const canonical_1 = require("../shared/canonical");
 const crypto_1 = require("./crypto");
 const transparency_log_1 = require("./transparency-log");
+const witness_identity_1 = require("./witness-identity");
+const canonical_2 = require("../shared/canonical");
 const FORMAT_VERSION = 1;
 const MAX_LINE = 1024 * 1024; // 1 MiB per record — bounded, fail-closed
 class LedgerCorruptionError extends Error {
@@ -121,6 +123,10 @@ class FileLedgerStore {
     lastHash;
     sths = [];
     sthBySize = new Map(); // tree_size -> root_hash (one root per size)
+    rotations = [];
+    activeWitnessKey; // anchored by first STH; advanced by rotations
+    activeWitnessVersion_ = 1;
+    lastRotationHash = canonical_2.GENESIS_HASH;
     leaves = []; // replay-validation view only
     fd;
     lockPath;
@@ -227,6 +233,9 @@ class FileLedgerStore {
         if (typeof sth.tree_size !== "number" || sth.tree_size < 0) {
             throw new Error("file-ledger: STH tree_size malformed — refused");
         }
+        if (this.activeWitnessKey !== undefined && sth.witness_pubkey !== this.activeWitnessKey) {
+            throw new Error("file-ledger: STH signed by a key that is not the active witness epoch — unauthorized substitution refused (commit a rotation record first)");
+        }
         const existing = this.sthBySize.get(sth.tree_size);
         if (existing !== undefined && existing !== sth.root_hash) {
             throw new Error(`file-ledger: conflicting STH at tree_size ${sth.tree_size} — equivocation refused`);
@@ -235,6 +244,57 @@ class FileLedgerStore {
         this.writeRecord({ v: FORMAT_VERSION, t: "sth", payload, payload_hash: (0, canonical_1.canonicalHash)(payload) });
         this.sths.push(sth);
         this.sthBySize.set(sth.tree_size, sth.root_hash);
+        if (this.activeWitnessKey === undefined)
+            this.activeWitnessKey = sth.witness_pubkey;
+    }
+    /**
+     * Durably commit a rotation continuity record. The record becomes part of
+     * the SAME append-only evidence ledger (single authority). Validation here
+     * is the write-side gate; replay re-validates the full chain.
+     */
+    appendRotation(record) {
+        if (this.activeWitnessKey === undefined) {
+            throw new Error("file-ledger: cannot rotate before any STH establishes the witness anchor");
+        }
+        const v = (0, witness_identity_1.validateRotationRecord)(record, {
+            activePubkey: this.activeWitnessKey,
+            activeVersion: this.activeWitnessVersion_,
+            previousRotationHash: this.lastRotationHash,
+            identityId: record.identity_id, // identity binding is enforced by the keystore + chain hashes
+        });
+        if (!v.valid)
+            throw new Error(`file-ledger: rotation refused — ${v.reason}`);
+        if (record.effective_tree_size !== this.leaves.length) {
+            throw new Error(`file-ledger: rotation boundary ${record.effective_tree_size} does not match the current ledger size ${this.leaves.length}`);
+        }
+        const latest = this.latestSth();
+        if (latest && record.last_old_sth_root !== latest.root_hash) {
+            throw new Error("file-ledger: rotation does not preserve the final old-key checkpoint root");
+        }
+        const payload = { ...record };
+        this.writeRecord({ v: FORMAT_VERSION, t: "rotation", payload, payload_hash: (0, canonical_1.canonicalHash)(payload) });
+        this.rotations.push(record);
+        this.activeWitnessKey = record.new_pubkey;
+        this.activeWitnessVersion_ = record.new_version;
+        this.lastRotationHash = record.record_hash;
+    }
+    allRotations() {
+        return this.rotations.slice();
+    }
+    activeWitnessPubkey() {
+        return this.activeWitnessKey;
+    }
+    activeWitnessVersion() {
+        return this.activeWitnessVersion_;
+    }
+    /** The validated epoch table (anchor + rotation boundaries). The single
+     *  source of "which key is authorized for which tree size" at this node. */
+    witnessEpochs() {
+        if (this.sths.length === 0)
+            return undefined;
+        const anchor = this.sths[0].witness_pubkey;
+        const w = (0, witness_identity_1.walkRotationChain)(anchor, this.rotations);
+        return w.valid ? w.epochs : undefined; // replay already validated → valid by construction
     }
     // ── reads (same copy semantics as the memory store) ───────────────────────
     async getReceiptsNewestFirst(limit) {
@@ -373,6 +433,30 @@ class FileLedgerStore {
                 this.leaves.push((0, transparency_log_1.hashLeaf)(rc.receipt_hash));
                 continue;
             }
+            if (rec.t === "rotation") {
+                const rot = rec.payload;
+                if (witnessKey === undefined)
+                    throw new LedgerCorruptionError(recNo, "rotation before any STH anchor");
+                const rv = (0, witness_identity_1.validateRotationRecord)(rot, {
+                    activePubkey: witnessKey,
+                    activeVersion: this.activeWitnessVersion_,
+                    previousRotationHash: this.lastRotationHash,
+                    identityId: rot.identity_id,
+                });
+                if (!rv.valid)
+                    throw new LedgerCorruptionError(recNo, `rotation record invalid: ${rv.reason}`);
+                if (rot.effective_tree_size !== this.leaves.length)
+                    throw new LedgerCorruptionError(recNo, "rotation boundary does not match ledger position");
+                const latestAtRotation = this.sths[this.sths.length - 1];
+                if (latestAtRotation && rot.last_old_sth_root !== latestAtRotation.root_hash) {
+                    throw new LedgerCorruptionError(recNo, "rotation does not preserve the final old-key checkpoint");
+                }
+                this.rotations.push(rot);
+                witnessKey = rot.new_pubkey;
+                this.activeWitnessVersion_ = rot.new_version;
+                this.lastRotationHash = rot.record_hash;
+                continue;
+            }
             if (rec.t === "sth") {
                 const sth = rec.payload;
                 if (!(0, transparency_log_1.verifySTH)(sth))
@@ -380,7 +464,7 @@ class FileLedgerStore {
                 if (witnessKey === undefined)
                     witnessKey = sth.witness_pubkey;
                 else if (sth.witness_pubkey !== witnessKey)
-                    throw new LedgerCorruptionError(recNo, "witness key changed mid-ledger (rotation records are a later lane)");
+                    throw new LedgerCorruptionError(recNo, "STH signed by a key outside the authorized rotation chain (silent substitution)");
                 if (sth.tree_size > this.leaves.length)
                     throw new LedgerCorruptionError(recNo, `STH tree_size ${sth.tree_size} exceeds receipts seen (${this.leaves.length})`);
                 const existing = this.sthBySize.get(sth.tree_size);
@@ -397,6 +481,7 @@ class FileLedgerStore {
         }
         if (lines.length > 0 && !headerSeen)
             throw new LedgerCorruptionError(1, "missing header record");
+        this.activeWitnessKey = witnessKey;
     }
     quarantineTail(tail, offset) {
         const qPath = `${this.filePath}.tail-quarantine-${Date.now()}`;