magenta-canon 0.4.0 → 0.5.0

package/README.md

@@ -190,6 +190,37 @@ 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).
+
 ### From the repo vs. as a CLI
 
 - **From a repo checkout** (above): `npm install` then `npm run demo`.

package/dist/MANIFEST.json

@@ -1,15 +1,15 @@
 {
   "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-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",
@@ -25,9 +25,10 @@
   "server/ledger.js": "9bf8f132e08d636070d2ede568b2eaf75810be245c90ecd5979d2d4de69af934",
   "server/persistence.js": "2e6b1d0b1c74babbd581780b028c2593256c5ec96c2d60f4c25159e3f54e4e3f",
   "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/schema.js": "f89190990e3826e44c722d5e8f5b39fd59b4d3fb9ec047229930a17604e4646c",

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-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()}`;

package/dist/server/transparency-log.js

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyConsistency = exports.verifySTH = exports.TransparencyLog = exports.verifyInclusion = exports.inclusionProof = exports.merkleRoot = exports.hashLeaf = void 0;
 const crypto_1 = require("crypto");
 const ledger_store_1 = require("./ledger-store");
+const witness_identity_1 = require("./witness-identity");
 const crypto_2 = require("./crypto");
 // ----------------------------------------------------------------------------
 // Merkle primitives (RFC 6962 domain separation: 0x00 leaves, 0x01 nodes)
@@ -134,6 +135,15 @@ class TransparencyLog {
     get witnessPublicKey() {
         return this.witnessPub;
     }
+    /**
+     * Switch to the next witness key epoch. The caller MUST have durably
+     * committed the rotation continuity record first (the ledger is the single
+     * authority over rotations); this only swaps the signing key.
+     */
+    rotateWitnessKey(next) {
+        this.witnessPub = next.publicKey;
+        this.witnessSec = next.secretKey;
+    }
     /** Append a receipt hash as a leaf and publish a new signed tree head. */
     append(receiptHash) {
         const leaf = hashLeaf(receiptHash);
@@ -180,13 +190,38 @@ class TransparencyLog {
         }
         this.leaves = receiptHashes.map(hashLeaf);
         const latest = this.store.latestSth();
-        if (latest && latest.witness_pubkey !== this.witnessPub) {
-            throw new Error("transparency-log: the durable ledger's STH history was signed by a DIFFERENT witness key than this " +
-                "process holds — a restart regenerated the witness identity. Pin MAGENTA_WITNESS_SECRET/MAGENTA_WITNESS_PUBLIC " +
-                "to the original key (witness continuity is required for origin verification); refusing to continue incoherently.");
-        }
-        if (latest && merkleRoot(this.leaves.slice(0, latest.tree_size)) !== latest.root_hash) {
-            throw new Error("transparency-log: rebuilt leaf view does not match the committed STH root — ledger/receipt divergence");
+        if (latest) {
+            // Epoch-aware continuity. If the store exposes a validated rotation epoch
+            // table, the latest STH must be signed by the key authorized for ITS
+            // tree-size epoch — NOT necessarily the current live key (immediately
+            // after a committed rotation the newest checkpoint legitimately belongs
+            // to the retired epoch). Stores without rotations fall back to the
+            // single-key continuity guard.
+            const epochs = this.store.witnessEpochs?.();
+            if (epochs && epochs.length > 0) {
+                // (1) historical: the latest STH must be signed by the key authorized
+                //     for ITS tree-size epoch (may be a retired epoch immediately after
+                //     a committed rotation, before the first new-epoch STH).
+                const expected = (0, witness_identity_1.keyForTreeSize)(epochs, latest.tree_size);
+                if (latest.witness_pubkey !== expected) {
+                    throw new Error("transparency-log: latest STH is signed by a key outside the authorized rotation epoch for its tree size — refusing (fail closed)");
+                }
+                // (2) continuity: this process's LIVE signing key must be the active
+                //     epoch tip (else a regenerated/unreconciled witness identity would
+                //     sign the next STH with the wrong key). Pin the key / reconcile.
+                const tip = epochs[epochs.length - 1].pubkey;
+                if (this.witnessPub !== tip) {
+                    throw new Error("transparency-log: this process's live witness key is not the active rotation-epoch key (regenerated identity or unreconciled rotation) — refusing (fail closed)");
+                }
+            }
+            else if (latest.witness_pubkey !== this.witnessPub) {
+                throw new Error("transparency-log: the durable ledger's STH history was signed by a DIFFERENT witness key than this " +
+                    "process holds — a restart regenerated the witness identity. Pin MAGENTA_WITNESS_SECRET/MAGENTA_WITNESS_PUBLIC " +
+                    "(or use a keystore) to preserve witness continuity; refusing to continue incoherently.");
+            }
+            if (merkleRoot(this.leaves.slice(0, latest.tree_size)) !== latest.root_hash) {
+                throw new Error("transparency-log: rebuilt leaf view does not match the committed STH root — ledger/receipt divergence");
+            }
         }
     }
     /** Clear the log (fresh universe / test isolation). Keeps the witness key. */

package/dist/server/witness-identity.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * WITNESS IDENTITY & ROTATION CONTINUITY — Durable Witness PR 3 (Lane A).
+ *
+ * Moves Magenta from "unexpected witness-key change is refused" to
+ * "legitimate rotation is cryptographically authorized, durably recorded,
+ * independently verifiable, and distinguishable from silent substitution".
+ *
+ * THREE SEPARATED RESPONSIBILITIES (the ledger does NOT generate keys or
+ * decide rotation policy):
+ *   - WitnessKeyStore  — encrypted-at-rest custody of the identity's key
+ *                        versions (this module; local/reference mode).
+ *   - Rotation records — canonical signed continuity records, durably
+ *                        committed INTO THE EVIDENCE LEDGER (single
+ *                        authority: the same append-only file that holds
+ *                        receipts and STHs — no parallel custody journal).
+ *   - TransparencyLog  — signs STHs with whatever active key it is given;
+ *                        epoch switching happens via an explicit, validated
+ *                        rotation call.
+ *
+ * CUSTODY MODE (local/reference — NOT KMS/HSM):
+ *   - whole-file encryption: scrypt(passphrase) → AES-256-GCM;
+ *   - atomic create (O_EXCL, 0600) and atomic replace (tmp+rename);
+ *   - fail closed on wrong passphrase / malformed file / bad MAC;
+ *   - secret material is never logged, serialized into receipts/evidence,
+ *     or included in error messages.
+ *   Cloud KMS / customer-managed signing is a later lane
+ *   (docs/roadmaps/WITNESS_KEY_CUSTODY_ARCHITECTURE.md).
+ *
+ * ROTATION RECORD (spec "magenta-rotation/1") binds:
+ *   rotation_id · identity_id · old/new key version + pubkey · reason ·
+ *   initiated_at/effective_at · effective_tree_size (the exact ledger
+ *   boundary: STHs with tree_size <= boundary belong to the old epoch,
+ *   greater to the new) · last_old_sth_root (the preserved final old-key
+ *   checkpoint) · previous_rotation_hash (chain) · old-key AUTHORIZATION
+ *   signature · new-key COUNTERSIGNATURE · record_hash.
+ * Anything less is treated as unauthorized substitution. Signatures are
+ * Ed25519 over the UTF-8 bytes of the canonical hash of the record without
+ * its signature/record_hash fields — the same contract as receipt issuer
+ * signatures, so the standalone verifier re-derives it without server code.
+ */
+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 });
+exports.WitnessKeyStore = exports.keyForTreeSize = exports.walkRotationChain = exports.validateRotationRecord = exports.rotationRecordHash = exports.rotationSigningHash = exports.ROTATION_SPEC = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const canonical_1 = require("../shared/canonical");
+const crypto_1 = require("./crypto");
+exports.ROTATION_SPEC = "magenta-rotation/1";
+/** Canonical signing bytes: the record without signatures and record_hash. */
+function rotationSigningHash(r) {
+    return (0, canonical_1.canonicalHash)(r);
+}
+exports.rotationSigningHash = rotationSigningHash;
+function rotationRecordHash(r) {
+    return (0, canonical_1.canonicalHash)(r);
+}
+exports.rotationRecordHash = rotationRecordHash;
+/** Validate one rotation record against the expected chain state. */
+function validateRotationRecord(r, expected) {
+    const fail = (reason) => ({ valid: false, reason });
+    if (r.spec !== exports.ROTATION_SPEC)
+        return fail(`unsupported rotation spec '${r.spec}'`);
+    if (r.identity_id !== expected.identityId)
+        return fail("identity_id mismatch");
+    if (r.old_pubkey !== expected.activePubkey)
+        return fail("old_pubkey is not the currently active witness key");
+    if (r.old_version !== expected.activeVersion)
+        return fail("old_version is not the currently active key version");
+    if (r.new_version !== expected.activeVersion + 1)
+        return fail("new_version must increment by exactly 1 (no skipped versions)");
+    if (r.new_pubkey === r.old_pubkey)
+        return fail("rotation must change the key");
+    if (r.previous_rotation_hash !== expected.previousRotationHash)
+        return fail("previous_rotation_hash breaks the rotation chain");
+    if (!Number.isInteger(r.effective_tree_size) || r.effective_tree_size < 0)
+        return fail("effective_tree_size malformed");
+    const body = {
+        spec: r.spec, rotation_id: r.rotation_id, identity_id: r.identity_id,
+        old_version: r.old_version, old_pubkey: r.old_pubkey,
+        new_version: r.new_version, new_pubkey: r.new_pubkey,
+        reason: r.reason, initiated_at: r.initiated_at, effective_at: r.effective_at,
+        effective_tree_size: r.effective_tree_size, last_old_sth_root: r.last_old_sth_root,
+        previous_rotation_hash: r.previous_rotation_hash,
+    };
+    const signingHash = rotationSigningHash(body);
+    if (!(0, crypto_1.verify)(signingHash, r.old_key_signature, r.old_pubkey))
+        return fail("old-key authorization signature invalid");
+    if (!(0, crypto_1.verify)(signingHash, r.new_key_countersignature, r.new_pubkey))
+        return fail("new-key countersignature invalid");
+    if (rotationRecordHash({ ...body, old_key_signature: r.old_key_signature, new_key_countersignature: r.new_key_countersignature }) !== r.record_hash) {
+        return fail("record_hash mismatch");
+    }
+    return { valid: true };
+}
+exports.validateRotationRecord = validateRotationRecord;
+/**
+ * Walk a rotation chain from a pinned anchor key. Returns the epoch table
+ * (which key is authoritative for which tree sizes) or a failure reason.
+ * Pure — usable by the verifier, the ledger replay, and mirrors alike.
+ */
+function walkRotationChain(anchorPubkey, rotations) {
+    let activePubkey = anchorPubkey;
+    let activeVersion = rotations.length > 0 ? rotations[0].old_version : 1;
+    let prevHash = canonical_1.GENESIS_HASH;
+    let lastBoundary = -1;
+    const identityId = rotations.length > 0 ? rotations[0].identity_id : "";
+    const seenIds = new Set();
+    const epochs = [{ pubkey: anchorPubkey, fromExclusive: -1 }];
+    for (const r of rotations) {
+        if (seenIds.has(r.rotation_id))
+            return { valid: false, reason: `duplicate rotation_id ${r.rotation_id}` };
+        seenIds.add(r.rotation_id);
+        if (r.effective_tree_size <= lastBoundary)
+            return { valid: false, reason: "rotation boundaries must strictly increase (no replayed/reordered rotations)" };
+        const v = validateRotationRecord(r, { activePubkey, activeVersion, previousRotationHash: prevHash, identityId: r.identity_id === identityId ? identityId : "__mismatch__" });
+        if (!v.valid)
+            return { valid: false, reason: v.reason };
+        activePubkey = r.new_pubkey;
+        activeVersion = r.new_version;
+        prevHash = r.record_hash;
+        lastBoundary = r.effective_tree_size;
+        epochs.push({ pubkey: r.new_pubkey, fromExclusive: r.effective_tree_size });
+    }
+    return { valid: true, epochs, tipPubkey: activePubkey };
+}
+exports.walkRotationChain = walkRotationChain;
+/** Which key must have signed an STH at the given tree size, per the chain. */
+function keyForTreeSize(epochs, treeSize) {
+    let key = epochs[0].pubkey;
+    for (const e of epochs)
+        if (treeSize > e.fromExclusive)
+            key = e.pubkey;
+    return key;
+}
+exports.keyForTreeSize = keyForTreeSize;
+// scrypt cost: N=2^16 (was 2^14) — OWASP-2023-range for interactive reference
+// custody. Stored per-file (below), so it is tunable and forward-migratable.
+const SCRYPT = { N: 65536, r: 8, p: 1, keyLen: 32 };
+const SCRYPT_MAXMEM = 256 * 1024 * 1024; // headroom for N=2^16 (≈67MB working set)
+const KEYSTORE_FORMAT = "magenta-witness-keystore/1";
+/** Additional authenticated data binding the plaintext envelope header to the
+ *  ciphertext, so kdf params / iv / format / identity cannot be altered
+ *  without failing the GCM tag (fail closed). Deterministic from the header. */
+function keystoreAad(header) {
+    return Buffer.from((0, canonical_1.canonicalHash)(header), "utf8");
+}
+function encryptPayload(payload, passphrase) {
+    const salt = (0, node_crypto_1.randomBytes)(16);
+    const iv = (0, node_crypto_1.randomBytes)(12);
+    const key = (0, node_crypto_1.scryptSync)(passphrase, salt, SCRYPT.keyLen, { N: SCRYPT.N, r: SCRYPT.r, p: SCRYPT.p, maxmem: SCRYPT_MAXMEM });
+    const header = {
+        keystore: KEYSTORE_FORMAT,
+        cipher: "aes-256-gcm",
+        kdf: { algo: "scrypt", N: SCRYPT.N, r: SCRYPT.r, p: SCRYPT.p, keyLen: SCRYPT.keyLen, salt: salt.toString("hex") },
+        iv: iv.toString("hex"),
+        identity_id: payload.identity_id,
+    };
+    const cipher = (0, node_crypto_1.createCipheriv)("aes-256-gcm", key, iv);
+    cipher.setAAD(keystoreAad(header)); // bind format/kdf/iv/identity into the tag
+    const ct = Buffer.concat([cipher.update(JSON.stringify(payload), "utf8"), cipher.final()]);
+    return JSON.stringify({ ...header, tag: cipher.getAuthTag().toString("hex"), data: ct.toString("hex") });
+}
+function decryptPayload(fileText, passphrase) {
+    let env;
+    try {
+        env = JSON.parse(fileText);
+    }
+    catch {
+        throw new Error("witness-keystore: file is not valid JSON — refusing (fail closed)");
+    }
+    if (env.keystore !== KEYSTORE_FORMAT)
+        throw new Error("witness-keystore: unsupported keystore format — refusing");
+    const kdf = env.kdf;
+    if (!kdf || typeof kdf.N !== "number" || typeof kdf.salt !== "string")
+        throw new Error("witness-keystore: malformed kdf header — refusing");
+    // bound the attacker-influenced cost params before deriving (DoS guard)
+    if (kdf.N > 1 << 20 || kdf.r > 32 || kdf.p > 16)
+        throw new Error("witness-keystore: kdf cost parameters out of bounds — refusing");
+    const key = (0, node_crypto_1.scryptSync)(passphrase, Buffer.from(kdf.salt, "hex"), kdf.keyLen, { N: kdf.N, r: kdf.r, p: kdf.p, maxmem: SCRYPT_MAXMEM });
+    const header = { keystore: env.keystore, cipher: env.cipher, kdf: env.kdf, iv: env.iv, identity_id: env.identity_id };
+    const decipher = (0, node_crypto_1.createDecipheriv)("aes-256-gcm", key, Buffer.from(env.iv, "hex"));
+    decipher.setAAD(keystoreAad(header)); // any header tampering → tag mismatch below
+    decipher.setAuthTag(Buffer.from(env.tag, "hex"));
+    let pt;
+    try {
+        pt = Buffer.concat([decipher.update(Buffer.from(env.data, "hex")), decipher.final()]);
+    }
+    catch {
+        throw new Error("witness-keystore: decryption/authentication failed (wrong passphrase or tampered file) — refusing");
+    }
+    return JSON.parse(pt.toString("utf8"));
+}
+/**
+ * Encrypted, versioned custody for ONE witness identity. The store never
+ * exposes secrets except through sign(); rotation here only MINTS keys and
+ * records — making a rotation AUTHORITATIVE is the ledger's act (durable
+ * commit of the record), after which activate() is called.
+ */
+class WitnessKeyStore {
+    filePath;
+    passphrase;
+    payload;
+    constructor(filePath, passphrase, payload) {
+        this.filePath = filePath;
+        this.passphrase = passphrase;
+        this.payload = payload;
+    }
+    /** Create a brand-new identity (version 1 active). Fails if file exists. */
+    static create(filePath, passphrase) {
+        if (!path.isAbsolute(filePath))
+            throw new Error("witness-keystore: path must be absolute");
+        if (passphrase.length < 8)
+            throw new Error("witness-keystore: passphrase too short (min 8 chars)");
+        const kp = (0, crypto_1.generateKeyPair)();
+        const payload = {
+            store_version: 1,
+            identity_id: (0, canonical_1.canonicalHash)({ witness_identity_genesis: kp.publicKey }),
+            versions: [{ version: 1, pubkey: kp.publicKey, status: "active", created_at: new Date().toISOString(), activated_at_tree_size: 0 }],
+            secrets: { "1": kp.secretKey },
+        };
+        const fd = fs.openSync(filePath, "wx", 0o600); // atomic create, never overwrite
+        fs.writeSync(fd, encryptPayload(payload, passphrase));
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        return new WitnessKeyStore(filePath, passphrase, payload);
+    }
+    /** Open an existing identity. Fails closed on any custody problem. */
+    static open(filePath, passphrase) {
+        const text = fs.readFileSync(filePath, "utf8");
+        return new WitnessKeyStore(filePath, passphrase, decryptPayload(text, passphrase));
+    }
+    get identityId() { return this.payload.identity_id; }
+    activeVersion() {
+        const v = this.payload.versions.find((x) => x.status === "active");
+        if (!v)
+            throw new Error("witness-keystore: no active key version — refusing");
+        return { ...v };
+    }
+    versionByNumber(n) {
+        const v = this.payload.versions.find((x) => x.version === n);
+        return v ? { ...v } : undefined;
+    }
+    /** Active keypair for the TransparencyLog (secret stays inside the seam). */
+    activeKeypair() {
+        const v = this.activeVersion();
+        const secret = this.payload.secrets[String(v.version)];
+        if (!secret)
+            throw new Error("witness-keystore: active secret missing — refusing");
+        return { publicKey: v.pubkey, secretKey: secret };
+    }
+    /** Sign with a specific version (used to countersign during rotation). */
+    signWith(version, messageHash) {
+        const secret = this.payload.secrets[String(version)];
+        if (!secret)
+            throw new Error(`witness-keystore: no secret for version ${version}`);
+        return (0, crypto_1.sign)(messageHash, secret);
+    }
+    /**
+     * Mint a PENDING next key version and the fully signed rotation record for
+     * it. Does NOT activate: the caller must durably commit the record to the
+     * evidence ledger first, then call activate(record).
+     */
+    mintRotation(input) {
+        const oldV = this.activeVersion();
+        if (this.payload.versions.some((v) => v.status === "pending")) {
+            throw new Error("witness-keystore: a pending rotation already exists — resolve it first");
+        }
+        const next = (0, crypto_1.generateKeyPair)();
+        const newVersion = oldV.version + 1;
+        const now = new Date().toISOString();
+        const body = {
+            spec: exports.ROTATION_SPEC,
+            rotation_id: (0, node_crypto_1.randomBytes)(16).toString("hex"),
+            identity_id: this.payload.identity_id,
+            old_version: oldV.version,
+            old_pubkey: oldV.pubkey,
+            new_version: newVersion,
+            new_pubkey: next.publicKey,
+            reason: input.reason,
+            initiated_at: now,
+            effective_at: now,
+            effective_tree_size: input.effectiveTreeSize,
+            last_old_sth_root: input.lastOldSthRoot,
+            previous_rotation_hash: input.previousRotationHash,
+        };
+        const signingHash = rotationSigningHash(body);
+        const old_key_signature = this.signWith(oldV.version, signingHash);
+        const new_key_countersignature = (0, crypto_1.sign)(signingHash, next.secretKey);
+        const record = {
+            ...body,
+            old_key_signature,
+            new_key_countersignature,
+            record_hash: rotationRecordHash({ ...body, old_key_signature, new_key_countersignature }),
+        };
+        this.payload.versions.push({ version: newVersion, pubkey: next.publicKey, status: "pending", created_at: now });
+        this.payload.secrets[String(newVersion)] = next.secretKey;
+        this.persist();
+        return { record };
+    }
+    /** Activate a pending version AFTER its rotation record is durably committed. */
+    activate(record) {
+        const pending = this.payload.versions.find((v) => v.version === record.new_version && v.status === "pending");
+        if (!pending)
+            throw new Error("witness-keystore: no matching pending version to activate");
+        if (pending.pubkey !== record.new_pubkey)
+            throw new Error("witness-keystore: pending key does not match the committed rotation record");
+        const old = this.payload.versions.find((v) => v.version === record.old_version);
+        if (old) {
+            old.status = "retired";
+            old.retired_at_tree_size = record.effective_tree_size;
+        }
+        pending.status = "active";
+        pending.activated_at_tree_size = record.effective_tree_size;
+        this.persist();
+    }
+    /** Abandon a pending rotation that was never durably committed. */
+    abandonPending() {
+        const idx = this.payload.versions.findIndex((v) => v.status === "pending");
+        if (idx < 0)
+            return;
+        const v = this.payload.versions[idx];
+        delete this.payload.secrets[String(v.version)];
+        this.payload.versions.splice(idx, 1);
+        this.persist();
+    }
+    /**
+     * Deterministic boot reconciliation against the canonical ledger's committed
+     * rotation truth. Implements the sovereign rule: KEY MATERIAL ALONE NEVER
+     * GRANTS AUTHORITY — only a validated, durably committed rotation does;
+     * startup reconciles local bookkeeping to that committed fact and never
+     * guesses. Returns a NON-SECRET diagnostic.
+     *
+     *  - ledger active == keystore active  → in sync (abandon any orphan pending).
+     *  - ledger active == keystore active+1 with a matching committed record and
+     *    the exact pending key+secret  → complete activation (recovery of
+     *    already-committed authority, NOT a new authority decision).
+     *  - keystore pending with NO committed record  → abandon it.
+     *  - any other disagreement (>1 ahead, pubkey/secret mismatch, missing
+     *    material)  → throw, fail closed.
+     */
+    reconcileToCommitted(ledger) {
+        const ksActive = this.activeVersion();
+        const pending = this.payload.versions.find((v) => v.status === "pending");
+        if (ledger.activeVersion === ksActive.version && ledger.activePubkey === ksActive.pubkey) {
+            if (pending) {
+                const v = pending.version;
+                this.abandonPending();
+                return { action: "abandoned-orphan-pending", detail: `abandoned orphan pending v${v} (no committed rotation backs it)` };
+            }
+            return { action: "in-sync", detail: `witness identity active at v${ksActive.version}` };
+        }
+        if (ledger.activeVersion === ksActive.version + 1) {
+            const rec = ledger.latestRecord;
+            if (!rec || rec.new_version !== ledger.activeVersion || rec.new_pubkey !== ledger.activePubkey) {
+                throw new Error("witness-keystore: ledger epoch is ahead but its committed rotation record is missing/incoherent — refusing to reconcile (fail closed)");
+            }
+            if (!pending || pending.version !== ledger.activeVersion) {
+                throw new Error(`witness-keystore: ledger committed a rotation to v${ledger.activeVersion} but this keystore holds no matching pending version — new key material missing (fail closed)`);
+            }
+            if (pending.pubkey !== rec.new_pubkey) {
+                throw new Error("witness-keystore: pending key does not match the committed rotation's new key — refusing (fail closed)");
+            }
+            if (!this.payload.secrets[String(pending.version)]) {
+                throw new Error("witness-keystore: committed rotation's new secret is absent from the keystore — refusing (fail closed)");
+            }
+            this.activate(rec); // bookkeeping recovery of an authority event that already happened durably
+            return { action: "recovered-committed-rotation", detail: `recovered committed rotation: v${rec.old_version} → v${rec.new_version}` };
+        }
+        throw new Error(`witness-keystore: irreconcilable witness state — keystore active v${ksActive.version}, ledger active v${ledger.activeVersion} ` +
+            `(${ledger.activePubkey === ksActive.pubkey ? "pubkey match" : "pubkey MISMATCH"}). Refusing to guess; investigate (fail closed).`);
+    }
+    persist() {
+        // atomic replace: tmp (0600) + fsync + rename
+        const tmp = `${this.filePath}.tmp`;
+        const fd = fs.openSync(tmp, "w", 0o600);
+        fs.writeSync(fd, encryptPayload(this.payload, this.passphrase));
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fs.renameSync(tmp, this.filePath);
+    }
+}
+exports.WitnessKeyStore = WitnessKeyStore;

package/dist/server/witness.js

@@ -15,11 +15,62 @@
  *     from the trust root (good), but not externally managed (mirror the STHs to
  *     an outside party to get full insider-resistance).
  */
+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 });
-exports.rebuildWitnessFromReceipts = exports.witnessReceipt = exports.resetWitnessLog = exports.witnessLog = void 0;
+exports.rotateWitness = exports.rebuildWitnessFromReceipts = exports.witnessReceipt = exports.resetWitnessLog = exports.witnessLog = exports.witnessKeyStore = void 0;
 const transparency_log_1 = require("./transparency-log");
 const ledger_1 = require("./ledger");
+const witness_identity_1 = require("./witness-identity");
+const file_ledger_store_1 = require("./file-ledger-store");
+const fs = __importStar(require("node:fs"));
+/**
+ * KEYSTORE MODE (preferred for durable deployments): MAGENTA_WITNESS_KEYFILE +
+ * MAGENTA_WITNESS_PASSPHRASE select encrypted persistent custody — the witness
+ * identity survives restart WITHOUT raw key material in the environment, and
+ * key versions/rotations are managed by the store. ENV MODE (legacy/simple)
+ * and ephemeral mode are unchanged. Setting keystore + env keys together is a
+ * configuration error (no ambiguous identity authority).
+ */
+exports.witnessKeyStore = (() => {
+    const file = process.env.MAGENTA_WITNESS_KEYFILE;
+    if (!file)
+        return undefined;
+    const pass = process.env.MAGENTA_WITNESS_PASSPHRASE;
+    if (!pass)
+        throw new Error("witness: MAGENTA_WITNESS_KEYFILE is set but MAGENTA_WITNESS_PASSPHRASE is not — refusing");
+    if (process.env.MAGENTA_WITNESS_SECRET || process.env.MAGENTA_WITNESS_PUBLIC) {
+        throw new Error("witness: keystore mode and env-key mode are both configured — exactly one identity authority is allowed");
+    }
+    if (process.env.MAGENTA_STATE_FILE) {
+        throw new Error("witness: MAGENTA_WITNESS_KEYFILE and the legacy MAGENTA_STATE_FILE are both set — the keystore owns the witness identity; the legacy whole-state file must not also claim persistence authority. Use MAGENTA_LEDGER_FILE for durable evidence.");
+    }
+    return fs.existsSync(file) ? witness_identity_1.WitnessKeyStore.open(file, pass) : witness_identity_1.WitnessKeyStore.create(file, pass);
+})();
 function loadWitnessKey() {
+    if (exports.witnessKeyStore)
+        return exports.witnessKeyStore.activeKeypair();
     const secretKey = process.env.MAGENTA_WITNESS_SECRET;
     const publicKey = process.env.MAGENTA_WITNESS_PUBLIC;
     if (secretKey && publicKey)
@@ -27,6 +78,30 @@ function loadWitnessKey() {
     return undefined;
 }
 exports.witnessLog = new transparency_log_1.TransparencyLog(loadWitnessKey(), ledger_1.sharedLedgerStore);
+// BOOT RECONCILIATION (sovereign rule): reconcile local keystore bookkeeping
+// to the canonical ledger's COMMITTED rotation truth. Never activates a
+// pending key on mere file presence — only completes an already-durably-
+// committed rotation, abandons orphan pending keys, or fails closed. Runs once
+// at import, BEFORE any leaf rebuild, so the live signing key is the active
+// epoch. No-op outside keystore+file-ledger mode; idempotent across restarts.
+if (exports.witnessKeyStore && ledger_1.sharedLedgerStore instanceof file_ledger_store_1.FileLedgerStore) {
+    const led = ledger_1.sharedLedgerStore;
+    const activePub = led.activeWitnessPubkey();
+    if (activePub !== undefined) {
+        const evt = exports.witnessKeyStore.reconcileToCommitted({
+            activePubkey: activePub,
+            activeVersion: led.activeWitnessVersion(),
+            latestRecord: led.allRotations().at(-1),
+        });
+        if (evt.action === "recovered-committed-rotation") {
+            exports.witnessLog.rotateWitnessKey(exports.witnessKeyStore.activeKeypair());
+        }
+        if (evt.action !== "in-sync") {
+            // non-secret diagnostic — operator-visible recovery audit
+            console.error(`[witness] boot reconciliation: ${evt.action} — ${evt.detail}`);
+        }
+    }
+}
 /** Reset the witness log (fresh universe / test isolation). Keeps the witness key. */
 function resetWitnessLog() {
     exports.witnessLog.reset();
@@ -74,3 +149,40 @@ function rebuildWitnessFromReceipts(receiptHashes) {
     }
 }
 exports.rebuildWitnessFromReceipts = rebuildWitnessFromReceipts;
+/**
+ * Execute one witness-key rotation under the full continuity protocol:
+ *   mint (pending) → DURABLY COMMIT the signed record to the evidence ledger
+ *   → activate in the keystore → switch the live signing key.
+ * Requires keystore custody AND a durable file ledger (the single rotation
+ * authority). A failed durable commit abandons the pending key — the new key
+ * never becomes authoritative before the record is committed.
+ */
+function rotateWitness(reason) {
+    if (!exports.witnessKeyStore)
+        throw new Error("witness: rotation requires keystore custody (MAGENTA_WITNESS_KEYFILE)");
+    if (!(ledger_1.sharedLedgerStore instanceof file_ledger_store_1.FileLedgerStore)) {
+        throw new Error("witness: rotation requires the durable file ledger (MAGENTA_LEDGER_FILE) — rotations must be durably recorded before activation");
+    }
+    const ledger = ledger_1.sharedLedgerStore;
+    const latest = ledger.latestSth();
+    if (!latest)
+        throw new Error("witness: cannot rotate before any checkpoint exists");
+    const prevRotations = ledger.allRotations();
+    const { record } = exports.witnessKeyStore.mintRotation({
+        reason,
+        effectiveTreeSize: exports.witnessLog.size(),
+        lastOldSthRoot: latest.root_hash,
+        previousRotationHash: prevRotations.length ? prevRotations[prevRotations.length - 1].record_hash : "0".repeat(64),
+    });
+    try {
+        ledger.appendRotation(record); // durable commit — the authority event
+    }
+    catch (e) {
+        exports.witnessKeyStore.abandonPending(); // never activate an uncommitted rotation
+        throw e;
+    }
+    exports.witnessKeyStore.activate(record);
+    exports.witnessLog.rotateWitnessKey(exports.witnessKeyStore.activeKeypair());
+    return record;
+}
+exports.rotateWitness = rotateWitness;

package/docs/NPM_PACKAGING.md

@@ -3,16 +3,17 @@
 How Magenta Canon is packaged as an installable CLI, what ships in the tarball,
 what deliberately does not, and how to verify the package locally.
 
-> **Status: published on npm.** The current published release is **`0.1.13`**,
-> carried on **both** the `latest` and `next` dist-tags (CJ published `0.1.13`
-> and explicitly aligned both tags). This refresh prepares **`0.4.0`** — the
-> **truth-hardened verifier** (spec v1.1): layered verdicts (`ORIGIN AND
-> INTEGRITY VERIFIED` / `INTEGRITY VERIFIED` / `INCOMPLETE EVIDENCE` /
-> `VERIFICATION FAILED`), independently pinned witness keys
-> (`--expected-witness-key`), empty-evidence rejection, and enforced receipt
-> issuer signatures. `0.2.0` (the lean precompiled artifact) is **published**
-> and carried on both tags. `0.3.0` is **not yet published**; publishing
-> remains an explicitly-authorized step done on an authenticated machine.
+> **Status: published on npm.** The current published release is **`0.4.0`**
+> (the durable file ledger), carried on **both** the `latest` and `next`
+> dist-tags. This refresh prepares **`0.5.0`** — **durable witness identity
+> and cryptographically authorized rotation continuity**: an encrypted witness
+> keystore (`MAGENTA_WITNESS_KEYFILE`/`MAGENTA_WITNESS_PASSPHRASE`), dual-signed
+> rotation records committed into the evidence ledger, epoch-aware verification
+> from a pinned anchor, and deterministic crash reconciliation at boot.
+> Founder/receipt-issuer key custody is **not** part of 0.5.0 — it remains a
+> separate forthcoming durability lane. `0.5.0` is **not yet published**;
+> publishing remains an explicitly-authorized step done on an authenticated
+> machine.
 >
 > **Verdict-semantics migration (0.3.0):** scripts that grepped
 > `RESULT: VERIFIED` must match the new verdicts — `RESULT: INTEGRITY
@@ -23,7 +24,7 @@ what deliberately does not, and how to verify the package locally.
 
 ## Release posture
 
-The **`latest`** dist-tag tracks the current release (`0.1.13`), so a plain
+The **`latest`** dist-tag tracks the current release (`0.4.0`), so a plain
 `npm i magenta-canon` resolves the current reference implementation; the **`next`**
 tag points at the same version. It remains a **proven reference implementation**,
 not production-hosted infrastructure yet — production durability and an
@@ -57,7 +58,8 @@ npm dist-tag add magenta-canon@<version> next
 | `0.1.13` | **security hardening** (no API change): constant-time `INTERNAL_API_KEY` comparison; trust-key custody regression tests (root/intermediate never transit, actor key never persisted, key-returning routes fail closed) pinning the design Socket's AI heuristic flagged on `server/routes.ts`; threat-model docs (`SECURITY_MODEL.md` "Trust-key custody") + Socket dependency-alert mapping (`SUPPLY_CHAIN_REVIEW.md` §8) |
 | `0.2.0` | the **lean precompiled artifact** (supply-chain cleanroom, PRs #23–#25): minimal in-process demo control plane (the hosted Express/Passport/Postgres plane no longer ships); explicit `files` whitelist; org-storage and org-schema splits keep `pg`/drizzle out of the lean closure; **precompiled CommonJS `dist/`** built by `npm run build:lean` at `prepack` (deterministic, sha256 `MANIFEST.json`); runtime deps 17 → **2** (`tweetnacl`, `zod`); consumer install 111 → **3** packages; **zero install scripts**; no runtime `tsx`/`esbuild`/TypeScript; closure + precompile regression guards in `scripts/lean-closure.test.ts` — **published**; `latest`/`next` aligned |
 | `0.3.0` | **verifier truth hardening** (spec v1.1, PR #27): layered verdicts; `--expected-witness-key` (independently pinned witness identity — a bundle's own key can no longer masquerade as trusted); `INCOMPLETE EVIDENCE` for zero-receipt bundles; `--require-receipt`/`--require-action-hash`/`--min-receipts` claim pinning; **receipt issuer signatures enforced**; `--json` machine output; 21-test adversarial battery; demo now pins the witness key and earns `ORIGIN AND INTEGRITY VERIFIED`. Plus: Durable Witness architecture report, MVAR v1 receipt-standard DRAFT + schema/vectors, public verifier-page design — **published**; `latest`/`next` aligned |
-| `0.4.0` | **durable file ledger** (Durable Witness PRs 1–2, #32/#33): `LedgerStore` seam; `FileLedgerStore` — append-only canonical-JSONL evidence ledger (`MAGENTA_LEDGER_FILE`), fsync-before-committed, exclusive writer lock with documented stale-lock recovery, strict boot replay (payload hashes, chain, issuer signatures, STH signatures, one-root-per-tree-size, recomputed Merkle roots), crash-tail quarantine vs corruption refusal, **witness-continuity enforcement** (regenerated witness identity refuses to continue an existing ledger), dual-authority prevention vs legacy `MAGENTA_STATE_FILE`; two-real-process restart proof (`ORIGIN AND INTEGRITY VERIFIED` after `SIGKILL`); ships `docs/FILE_LEDGER.md` — **not yet published** |
+| `0.4.0` | **durable file ledger** (Durable Witness PRs 1–2, #32/#33): `LedgerStore` seam; `FileLedgerStore` — append-only canonical-JSONL evidence ledger (`MAGENTA_LEDGER_FILE`), fsync-before-committed, exclusive writer lock with documented stale-lock recovery, strict boot replay (payload hashes, chain, issuer signatures, STH signatures, one-root-per-tree-size, recomputed Merkle roots), crash-tail quarantine vs corruption refusal, **witness-continuity enforcement** (regenerated witness identity refuses to continue an existing ledger), dual-authority prevention vs legacy `MAGENTA_STATE_FILE`; two-real-process restart proof (`ORIGIN AND INTEGRITY VERIFIED` after `SIGKILL`); ships `docs/FILE_LEDGER.md` — **published**; `latest`/`next` aligned |
+| `0.5.0` | **durable witness identity + authorized rotation continuity** (Durable Witness PR 3, #35): encrypted witness keystore (`MAGENTA_WITNESS_KEYFILE`/`MAGENTA_WITNESS_PASSPHRASE`; scrypt N=2^16 with bounded params → AES-256-GCM with header-bound AAD, `O_EXCL` create, atomic replace); **rotation records committed into the evidence ledger** (`magenta-rotation/1`: old-key authorization + new-key countersignature + `effective_tree_size` epoch boundary + chain hash) — *key material alone never grants authority; a validated, durably committed rotation record does*; epoch-aware replay in server **and** standalone verifier (historical STHs validate against their epoch's key; rollback/substitution/forked chains refused); deterministic crash reconciliation at boot (recover committed fact / abandon orphan / fail closed — never silent activation); single-authority config matrix (keystore × env-keys × `MAGENTA_STATE_FILE` exclusions); ships `docs/WITNESS_IDENTITY.md`. **Limitation (documented):** witness identity only — founder/receipt-issuer custody is a separate forthcoming lane (issuer key still regenerates on restart in file-ledger mode; pre-restart evidence keeps verifying). **Migration:** none required — 0.4.0 env-key and memory modes are unchanged; the keystore is opt-in and mutually exclusive with `MAGENTA_WITNESS_SECRET`/`PUBLIC` and `MAGENTA_STATE_FILE`. **Also in this release (repo hygiene, #37/#38):** the legacy RealityOS heartbeat adapter is **deprecated and removed** — excluded from the supported product architecture, never required for Magenta verification or distribution (`docs/LEGACY_REALITYOS_HEARTBEAT.md`); a tracked legacy dev identity was removed with a secret-hygiene CI gate added (`reports/INCIDENT_TRACKED_DEV_IDENTITY.md`) — **not yet published** |
 
 
 **Verified on macOS / Linux / Windows (current release `0.1.11`; `0.1.12` re-proven via installed-tarball smoke):**
@@ -256,28 +258,28 @@ MCP gateway, and a **local-file external STH mirror foundation** with an
 operator runbook. **Not** included: hosted mirror service, automated network
 publishing, production multi-tenant SaaS, production durability guarantees.
 
-## Verifying the release artifact (checklist — current target `0.4.0`)
+## Verifying the release artifact (checklist — current target `0.5.0`)
 
 From a clean checkout of the release commit:
 
 ```bash
 npm ci && npm run check && npm test          # 0 tsc errors; full suite green
 npm run build:lean && npm run build:lean     # deterministic: dist/MANIFEST.json identical
-npm pack                                     # prepack rebuilds dist/; expect magenta-canon-0.4.0.tgz
-tar -tzf magenta-canon-0.4.0.tgz             # 53 files; no .ts, no .map, no tests, no server/routes.ts, no ledger/lock files
+npm pack                                     # prepack rebuilds dist/; expect magenta-canon-0.5.0.tgz
+tar -tzf magenta-canon-0.5.0.tgz             # 55 files; no .ts, no .map, no tests, no server/routes.ts, no ledger/lock/keystore files
 ```
 
 Then in an empty directory:
 
 ```bash
-npm init -y && npm i ../path/to/magenta-canon-0.4.0.tgz
+npm init -y && npm i ../path/to/magenta-canon-0.5.0.tgz
 ls node_modules                              # exactly: magenta-canon tweetnacl zod
 npx magenta-canon verify --self-test         # all verdict levels incl. tamper VERIFICATION FAILED
 npx magenta-canon mirror --self-test         # [PASS] x3
 npx magenta-canon demo                       # allow / block / VERIFIED / tamper FAILED
 ```
 
-Expected artifact metrics: **49 files · ~124.7 kB packed · ~468 kB unpacked ·
+Expected artifact metrics: **55 files · ~157.5 kB packed · ~577.9 kB unpacked ·
 deps `tweetnacl`+`zod` · 3-package consumer install · 0 install scripts**. The
 single expected scanner heuristic is TweetNaCl's minified upstream distribution
 (retained deliberately — see `docs/SUPPLY_CHAIN_REVIEW.md`).

package/docs/SECURITY_MODEL.md

@@ -76,6 +76,15 @@ Concretely, proven in `docs/MCP_GATEWAY_RUN.md` and `docs/VERIFICATION_RUN.md`:
    (`INCOMPLETE EVIDENCE`), and receipt issuer signatures are cryptographically
    enforced when present. Auditors verifying a disputed action should also pin
    the claim itself: `--require-receipt <hash>` / `--require-action-hash <hash>`.
+6. **Witness continuity is durable; trust-root continuity is not (yet).** With
+   the file ledger + witness keystore, the witness identity and its
+   cryptographically authorized rotation chain survive restart, so old
+   evidence keeps verifying and origin verification holds from a pinned
+   anchor. The **founder/root receipt issuer remains memory-resident** and is
+   regenerated on restart — receipts issued after a restart carry a new issuer
+   key. Trust-root/issuer custody is a separate forthcoming durability lane.
+   Do not read "witness identity survives restart" as "all signing authority
+   survives restart."
 
 ## Trust-key custody (root/intermediate never leave; actor key is caller-owned)
 

package/docs/WITNESS_IDENTITY.md

@@ -0,0 +1,134 @@
+# Witness Identity, Custody, and Rotation Continuity
+
+How Magenta's witness key persists across restarts, how it is protected at
+rest, and how a **legitimate** key rotation is distinguished — cryptographically
+and durably — from a silent key substitution.
+
+## Identity model
+
+| Concept | Meaning |
+|---|---|
+| **Witness identity** | A stable identity (`identity_id` = hash of the genesis public key) that outlives any single keypair. |
+| **Key version** | Numbered Ed25519 keypairs (`1, 2, …`) with status `pending → active → retired` (and `revoked` reserved). Exactly one active version at a time; versions never skip. |
+| **Epoch** | The range of tree sizes a key version is authoritative for. STHs with `tree_size <= effective_tree_size` of a rotation belong to the OLD epoch; greater to the NEW. |
+| **Anchor** | The version-1 public key an auditor/mirror pins. All later epochs must chain to it by signed rotation records. |
+
+## Trust-root limitation (read this — important for honest claims)
+
+0.5.0 makes the **witness identity** durable and rotatable. It does **not**
+yet make the **trust-root / receipt-issuer** identity durable. In file-ledger
+mode the founder/root key lives in memory and is **regenerated on restart**
+(and cannot be persisted alongside the ledger — `MAGENTA_LEDGER_FILE` +
+`MAGENTA_STATE_FILE` is refused). Consequences:
+
+- Old evidence still verifies after restart (witness identity + rotation
+  chain persist; STHs remain valid; receipts keep their original issuer
+  signatures).
+- **Receipts recorded *after* a restart are signed by a NEW issuer key** until
+  a future trust-root custody lane lands.
+
+> Witness continuity survives restart and cryptographically authorized
+> rotation. Trust-root and receipt-issuer custody are separate forthcoming
+> durability lanes; in the current file-ledger mode the issuer identity is
+> regenerated after restart.
+
+Do not describe this as full identity continuity or complete production key
+custody.
+
+## Custody modes (exactly one identity authority)
+
+| Mode | Selection | Notes |
+|---|---|---|
+| **Keystore** (preferred for durable deployments) | `MAGENTA_WITNESS_KEYFILE` + `MAGENTA_WITNESS_PASSPHRASE` | Encrypted at rest: scrypt (N=2^16, bounded/validated) → AES-256-GCM with **AAD binding the plaintext envelope** (format/version, KDF params, IV, identity_id) so header tampering fails the tag; `0600`, atomic create (`O_EXCL`, never overwrites an identity) and atomic replace. Wrong passphrase / tampered file / malformed file / out-of-bounds KDF cost all **fail closed**. Secrets never appear in logs, receipts, evidence, rotation records, or error messages (test-enforced). Combining the keystore with `MAGENTA_WITNESS_SECRET/PUBLIC` **or** `MAGENTA_STATE_FILE` is a startup error. **Windows:** `0600` is advisory (mode is ignored by the OS); `O_EXCL` and atomic rename still hold. |
+| Env keys (legacy/simple) | `MAGENTA_WITNESS_SECRET/PUBLIC` | Unchanged. Cannot be combined with keystore mode (startup error). |
+| Ephemeral (default) | none | Fresh key per process — demo/tests. |
+
+**This is local/reference custody — NOT KMS/HSM.** Cloud KMS, OS credential
+stores, and customer-managed signing follow the custody architecture lane
+(`docs/roadmaps/WITNESS_KEY_CUSTODY_ARCHITECTURE.md`).
+
+## Rotation continuity record (`magenta-rotation/1`)
+
+A canonical signed record binding: `rotation_id` · `identity_id` ·
+old/new version + pubkey · `reason` · `initiated_at`/`effective_at` ·
+**`effective_tree_size`** (the exact ledger boundary) ·
+**`last_old_sth_root`** (the preserved final old-key checkpoint) ·
+`previous_rotation_hash` (rotation chain) · **old-key authorization
+signature** · **new-key countersignature** · `record_hash`. Signatures are
+Ed25519 over the UTF-8 bytes of the canonical hash of the record without its
+signature/hash fields — the same contract as receipt issuer signatures, so
+any spec-conforming verifier re-derives it.
+
+**Anything less is unauthorized substitution** — verifiers and mirrors must
+treat a key change without a complete valid record as an attack, not a rotation.
+
+## Rotation protocol (order is the security property)
+
+```
+1. keystore mints the PENDING next version + the dual-signed record
+2. the record is DURABLY COMMITTED to the evidence ledger   ← authority event
+3. the keystore activates the new version (old → retired)
+4. the transparency log switches its signing key (new epoch begins)
+```
+
+- A failed durable commit **abandons the pending key** — a new key can never
+  become authoritative before its continuity record is committed.
+- The evidence ledger is the **single rotation authority** (`rotation` records
+  live in the same append-only file as receipts and STHs — no parallel
+  custody journal, no dual authority).
+- Rollback: an STH under a retired key is refused at append; re-activating an
+  old key requires a NEW dual-signed rotation back to it.
+
+## Boot reconciliation (crash recovery — the sovereign rule)
+
+**Key material alone never grants authority. Only a validated, durably
+committed rotation record does.** At startup, in keystore + file-ledger mode,
+the keystore reconciles its local bookkeeping to the ledger's committed truth:
+
+| State at boot | Action |
+|---|---|
+| keystore active == ledger active epoch | **in sync** (and any stray pending key is abandoned) |
+| ledger committed a rotation to vN, keystore holds the exact matching pending vN (pubkey + secret) | **recover**: complete activation (the authority event already happened durably — this is bookkeeping, not a new decision); switch the live signing key to vN |
+| keystore has a pending key with **no** committed rotation record | **abandon** it (durably; it can never activate without a fresh authorized rotation) |
+| ledger >1 epoch ahead, pubkey/secret mismatch, or new key material missing | **fail closed** — refuse to guess |
+
+This resolves the crash-after-commit-before-activation window: a legitimately
+committed rotation that crashed before the keystore caught up is recovered
+deterministically rather than wedging writes. Recovery emits a non-secret
+audit line. Crash boundaries are exhaustively tested in
+`server/rotation-crash-boundary.test.ts` (B2 abandon, B3 recover + idempotent
+re-restart, B4 epoch-aware rebuild, plus missing/wrong-key fail-closed).
+
+Note: a pending key is only ever persisted *after* it is fully signed
+(`mintRotation` is atomic mint+sign+persist), so "a pending key with no
+signatures" is not a reachable durable state.
+
+## Replay & verification
+
+- **Ledger replay** re-validates every rotation record in sequence (chain
+  hash, version increment, dual signatures, boundary == ledger position,
+  preserved final old-key root) and enforces that every STH is signed by the
+  key that is active at its position. Deleting or reordering a rotation
+  record turns the ledger into refused corruption.
+- **Standalone verifier**: evidence bundles may carry `rotations`. With
+  `--expected-witness-key <v1-anchor>`, the verifier walks the chain from the
+  pinned anchor (pure re-implementation — no server code) and checks the STH
+  against the authorized key **for its epoch**. Verdicts are unchanged:
+  `ORIGIN AND INTEGRITY VERIFIED` requires the pinned anchor + a valid chain;
+  bundle-anchored chains remain `INTEGRITY VERIFIED` with the skip surfaced.
+
+## Operator procedure
+
+- **Rotate:** `POST /internal/witness/rotate` (INTERNAL_API_KEY-gated;
+  requires keystore + file-ledger modes) or the `rotateWitness(reason)` API.
+- **Backup:** the keystore file and the ledger file together; the passphrase
+  separately. Restoring an old keystore alongside a newer ledger fails boot
+  (the active version cannot sign the current epoch) — restore matched pairs.
+- **Compromise response:** rotate immediately (the old key signs its own
+  retirement — if the OLD key is already attacker-held, the attacker can also
+  rotate: this is the classic CA problem; mirrors + the anchor pin bound the
+  damage to a detectable fork). Revocation records and out-of-band
+  re-anchoring are the documented follow-up lane.
+- **Limitations:** single identity per keystore; rotation requires the
+  durable file ledger; trust-root (issuer) custody is a separate lane;
+  passphrase loss is unrecoverable by design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magenta-canon",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "A verifiable MCP accountability gateway for AI-agent tool calls: allows authorized calls, blocks unauthorized calls, records both, and produces cryptographic evidence anyone can verify.",
@@ -44,6 +44,7 @@
     "docs/SECURITY_MODEL.md",
     "docs/NPM_PACKAGING.md",
     "docs/FILE_LEDGER.md",
+    "docs/WITNESS_IDENTITY.md",
     "public/canon/schemas/constitutional-spine.schema.json",
     "public/canon/spine/constitutional-spine.v1.json",
     "README.md",