raz-encrypt 2.3.0 → 2.4.0

package/dist/trust.js

@@ -1,50 +1,363 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { gcm } from "@noble/ciphers/aes.js";
+import { equalBytes } from "@noble/ciphers/utils.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { sha384 } from "@noble/hashes/sha2.js";
+import { bytesToHex, concatBytes, hexToBytes, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { canonicalize } from "./canonicalJson.js";
+import { isValidIsoInstant, signCore, verifyCore } from "./crypto/hybrid.js";
+import { writeFileAtomic } from "./fileCrypto.js";
 import { fingerprint } from "./fingerprint.js";
+import { exportPublicIdentity } from "./identity.js";
+import { appendLogEntry } from "./store.js";
+/**
+ * Thrown when trust.json cannot be trusted: its MAC does not verify (edited,
+ * truncated, copied from another identity), it is not valid JSON, or it is an
+ * unauthenticated legacy file that was never explicitly adopted with
+ * `migrateLegacyTrustStore`. Everything that consults the trust list fails
+ * closed on this rather than reading a file anyone with filesystem access
+ * could have written.
+ */
+export class TrustStoreIntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TrustStoreIntegrityError";
+    }
+}
+const TRUST_STORE_HMAC_INFO = utf8ToBytes("raz-encrypt-trust-store-v1|hmac-key");
+// A separate key from the MAC key, same reason the audit log's head key is
+// separate from its entry key (ADR 0019) — independent HKDF outputs per use
+// (ADR 0027).
+const TRUST_STORE_ENC_INFO = utf8ToBytes("raz-encrypt-trust-store-v1|enc-key");
+// Third independent key, for the freshness sidecar (ADR 0030).
+const TRUST_STORE_SEQ_INFO = utf8ToBytes("raz-encrypt-trust-store-v1|seq-key");
 function trustFilePath(storageDir) {
     return join(storageDir, "trust.json");
 }
+/**
+ * HKDF-derived from BOTH the classical and PQC signing secrets, same
+ * composition as the audit log's key (ADR 0009) but under its own info label
+ * so the two MAC keys are independent. Recomputed on every use, never persisted.
+ */
+function deriveTrustStoreKey(identity) {
+    return hkdf(sha384, concatBytes(identity.classical.secretKey, identity.pqcSign.secretKey), undefined, TRUST_STORE_HMAC_INFO, 32);
+}
+/** Same derivation shape as deriveTrustStoreKey, under its own info label (ADR 0027) — never derived from a passphrase, since trustParty/etc. only ever receive an Identity. */
+function deriveTrustStoreEncKey(identity) {
+    return hkdf(sha384, concatBytes(identity.classical.secretKey, identity.pqcSign.secretKey), undefined, TRUST_STORE_ENC_INFO, 32);
+}
+// `seq` joins the MAC input only when present, so files written before ADR 0030 keep verifying unchanged.
+function computeMac(identity, entries, seq) {
+    const body = seq === undefined ? { version: 3, entries } : { version: 3, entries, seq };
+    return bytesToHex(hmac(sha384, deriveTrustStoreKey(identity), utf8ToBytes(canonicalize(body))));
+}
+/**
+ * Exported (ADR 0026) so the timing-safety test can exercise this exact
+ * compare in isolation, without the file I/O its only internal callers do.
+ */
+export function macMatches(identity, entries, mac, seq) {
+    if (typeof mac !== "string" || !/^[0-9a-f]{96}$/.test(mac))
+        return false;
+    return equalBytes(hexToBytes(mac), hexToBytes(computeMac(identity, entries, seq)));
+}
+/** v4's MAC covers the ciphertext blob instead of the plaintext entries (ADR 0027) — same chain-authentication mechanism, different bytes underneath it. */
+function computeMacV4(identity, nonce, ciphertext, seq) {
+    const body = seq === undefined ? { version: 4, nonce, ciphertext } : { version: 4, nonce, ciphertext, seq };
+    return bytesToHex(hmac(sha384, deriveTrustStoreKey(identity), utf8ToBytes(canonicalize(body))));
+}
+function macMatchesV4(identity, nonce, ciphertext, mac, seq) {
+    if (typeof mac !== "string" || !/^[0-9a-f]{96}$/.test(mac))
+        return false;
+    return equalBytes(hexToBytes(mac), hexToBytes(computeMacV4(identity, nonce, ciphertext, seq)));
+}
+/** Associated data for the entries AEAD: binds the ciphertext to the format version and its own nonce, same pattern as fileCrypto.ts's headerAad. */
+function entriesAad(version, nonce) {
+    return utf8ToBytes(canonicalize({ version, nonce }));
+}
+function encryptEntries(identity, entries) {
+    const nonce = randomBytes(12);
+    const nonceHex = bytesToHex(nonce);
+    const ciphertext = gcm(deriveTrustStoreEncKey(identity), nonce, entriesAad(4, nonceHex)).encrypt(utf8ToBytes(canonicalize(entries)));
+    return { nonce: nonceHex, ciphertext: bytesToHex(ciphertext) };
+}
+/** Throws TrustStoreIntegrityError (never a raw AEAD error) if the ciphertext doesn't authenticate or doesn't decode as entries. */
+function decryptEntries(identity, nonce, ciphertext) {
+    try {
+        const plaintext = gcm(deriveTrustStoreEncKey(identity), hexToBytes(nonce), entriesAad(4, nonce)).decrypt(hexToBytes(ciphertext));
+        const entries = JSON.parse(new TextDecoder().decode(plaintext));
+        if (typeof entries !== "object" || entries === null || Array.isArray(entries))
+            throw new Error("decrypted trust store is not an entries object");
+        return entries;
+    }
+    catch {
+        throw new TrustStoreIntegrityError("trust.json failed its integrity check: it was modified, truncated, or belongs to a different identity.");
+    }
+}
+function isV3(data) {
+    if (typeof data !== "object" || data === null || data.version !== 3)
+        return false;
+    const entries = data.entries;
+    return typeof entries === "object" && entries !== null && !Array.isArray(entries) && validSeq(data.seq);
+}
+function validSeq(seq) {
+    return seq === undefined || (typeof seq === "number" && Number.isSafeInteger(seq) && seq >= 1);
+}
+function isHex96(value) {
+    return typeof value === "string" && /^[0-9a-f]{96}$/.test(value);
+}
+function isV4(data) {
+    if (typeof data !== "object" || data === null || data.version !== 4)
+        return false;
+    const d = data;
+    return typeof d.nonce === "string" && /^[0-9a-f]{24}$/.test(d.nonce) && typeof d.ciphertext === "string" && /^[0-9a-f]*$/.test(d.ciphertext) && isHex96(d.mac) && validSeq(data.seq);
+}
 function isV2(data) {
     return typeof data === "object" && data !== null && data.version === 2;
 }
-/** Migrates a legacy alias-keyed store to the fingerprint-keyed v2 shape. */
-function migrateLegacy(legacy) {
+/** Converts an unauthenticated legacy file (v1 alias map, or v2 without a MAC) to fingerprint-keyed entries. */
+function legacyEntries(data) {
+    if (isV2(data))
+        return data.entries;
+    if (typeof data !== "object" || data === null) {
+        // Object.values(null) throws TypeError; fail closed with the same error
+        // every other unauthenticated-shape rejection in this module uses,
+        // rather than crashing the caller (found by fuzzing, issue #42).
+        throw new TrustStoreIntegrityError("trust.json is not a valid legacy trust-store shape (expected an object).");
+    }
     const entries = {};
-    for (const card of Object.values(legacy)) {
+    for (const card of Object.values(data)) {
         entries[fingerprint(card)] = { card, trustedAt: new Date().toISOString() };
     }
-    return { version: 2, entries };
+    return entries;
 }
-async function readTrustStore(storageDir) {
+async function readRaw(storageDir) {
+    try {
+        return await readFile(trustFilePath(storageDir), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+}
+function parse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new TrustStoreIntegrityError("trust.json is not valid JSON; refusing to use it.");
+    }
+}
+const ROLLBACK_MESSAGE = "trust.json is older than the last recorded trust change: it was rolled back (or its sequence file was removed). Refusing to use it. Restore the newest copy, or investigate before re-trusting anyone.";
+function seqFilePath(storageDir) {
+    return join(storageDir, "trust.seq.json");
+}
+function computeSeqMac(identity, seq, storeMac) {
+    const key = hkdf(sha384, concatBytes(identity.classical.secretKey, identity.pqcSign.secretKey), undefined, TRUST_STORE_SEQ_INFO, 32);
+    return bytesToHex(hmac(sha384, key, utf8ToBytes(canonicalize({ version: 1, seq, storeMac }))));
+}
+/** The sidecar's contents, or undefined if absent. Throws TrustStoreIntegrityError if it exists but is malformed or fails its MAC. */
+async function readSeqRecord(identity) {
     let raw;
     try {
-        raw = await readFile(trustFilePath(storageDir), "utf8");
+        raw = await readFile(seqFilePath(identity.storageDir), "utf8");
     }
     catch (err) {
         if (err.code === "ENOENT")
-            return { version: 2, entries: {} };
+            return undefined;
         throw err;
     }
-    const data = JSON.parse(raw);
-    return isV2(data) ? data : migrateLegacy(data);
+    const bad = () => new TrustStoreIntegrityError("trust.seq.json failed its integrity check: it was modified or belongs to a different identity.");
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        throw bad();
+    }
+    const d = data;
+    if (typeof d !== "object" || d === null || d.version !== 1 || !validSeq(d.seq) || d.seq === undefined || !isHex96(d.storeMac) || !isHex96(d.mac))
+        throw bad();
+    if (!equalBytes(hexToBytes(d.mac), hexToBytes(computeSeqMac(identity, d.seq, d.storeMac))))
+        throw bad();
+    return d;
+}
+/**
+ * Reads and AUTHENTICATES the trust store, transparently decrypting a v4 (issue #43) file, and
+ * checks its freshness against the sequence sidecar (ADR 0030): a store whose `seq` is below the
+ * sidecar's, or equal with a different MAC, is a rollback. A store AHEAD of the sidecar is a crash
+ * between the two writes and is accepted (the next write repairs it). Missing file = empty store.
+ */
+async function readStoreState(identity) {
+    const raw = await readRaw(identity.storageDir);
+    if (raw === undefined)
+        return { entries: {}, seq: 0, mac: "" };
+    const data = parse(raw);
+    let state;
+    if (isV4(data)) {
+        if (!macMatchesV4(identity, data.nonce, data.ciphertext, data.mac, data.seq)) {
+            throw new TrustStoreIntegrityError("trust.json failed its integrity check: it was modified, truncated, or belongs to a different identity.");
+        }
+        state = { entries: decryptEntries(identity, data.nonce, data.ciphertext), seq: data.seq ?? 0, mac: data.mac };
+    }
+    else if (!isV3(data)) {
+        throw new TrustStoreIntegrityError("trust.json is an unauthenticated legacy file (written before trust-store MACs). Review it, then call migrateLegacyTrustStore(identity) to adopt it.");
+    }
+    else {
+        if (!macMatches(identity, data.entries, data.mac, data.seq)) {
+            throw new TrustStoreIntegrityError("trust.json failed its integrity check: it was modified, truncated, or belongs to a different identity.");
+        }
+        state = { entries: data.entries, seq: data.seq ?? 0, mac: data.mac };
+    }
+    const record = await readSeqRecord(identity);
+    if (record === undefined) {
+        // Only a first-ever write can legitimately leave a store with no sidecar (crash between the two writes).
+        if (state.seq > 1)
+            throw new TrustStoreIntegrityError(ROLLBACK_MESSAGE);
+    }
+    else if (state.seq < record.seq || (state.seq === record.seq && state.mac !== record.storeMac)) {
+        throw new TrustStoreIntegrityError(ROLLBACK_MESSAGE);
+    }
+    return state;
+}
+async function readTrustStore(identity) {
+    return (await readStoreState(identity)).entries;
+}
+/** The current `{ seq, mac }` of the trust store. Store it off-box after changes you care about. */
+export async function getTrustStoreAnchor(identity) {
+    const { seq, mac } = await readStoreState(identity);
+    return { seq, mac };
+}
+/**
+ * Throws TrustStoreIntegrityError if the local trust store is older than `anchor`, or has the
+ * same sequence number with different contents. Newer is fine. This is the only check that
+ * catches a rollback where trust.json and trust.seq.json were restored together (ADR 0030).
+ */
+export async function verifyTrustStoreAnchor(identity, anchor) {
+    const { seq, mac } = await readStoreState(identity);
+    if (seq < anchor.seq || (seq === anchor.seq && mac !== anchor.mac)) {
+        throw new TrustStoreIntegrityError("the trust store does not match the anchor you supplied: it was rolled back or replaced.");
+    }
 }
-async function writeTrustStore(storageDir, store) {
-    await mkdir(storageDir, { recursive: true });
-    await writeFile(trustFilePath(storageDir), JSON.stringify(store, null, 2), { mode: 0o600 });
+async function writeStoreFile(identity, store, seq) {
+    // Temp file with a unique name, fsync of file and directory, then rename (ADR 0028):
+    // a crash leaves the complete old file or the complete new one, never a torn one.
+    await writeFileAtomic(trustFilePath(identity.storageDir), JSON.stringify(store, null, 2));
+    // Then the freshness sidecar (ADR 0030). A crash between the two leaves the store one ahead, which reads accept.
+    const record = { version: 1, seq, storeMac: store.mac, mac: computeSeqMac(identity, seq, store.mac) };
+    await writeFileAtomic(seqFilePath(identity.storageDir), JSON.stringify(record));
+}
+/**
+ * Serializes every read-modify-write of one identity's trust store (ADR
+ * 0028, issue #56). Without this, two overlapping mutations each read the
+ * same snapshot and the later write erased the earlier one, so a revocation
+ * could be lost while the revoked party stayed trusted. In-process only, like
+ * the audit log's queue (ADR 0011): separate OS processes sharing one
+ * storageDir are not coordinated.
+ *
+ * A failure in one task never blocks the next. The map entry is removed once
+ * its chain drains, so it does not grow with every storageDir ever touched.
+ */
+const mutationQueues = new Map();
+function serialized(identity, task) {
+    const key = resolve(identity.storageDir);
+    const run = (mutationQueues.get(key) ?? Promise.resolve()).then(task);
+    const tail = run.then(() => undefined, () => undefined);
+    mutationQueues.set(key, tail);
+    void tail.then(() => {
+        if (mutationQueues.get(key) === tail)
+            mutationQueues.delete(key);
+    });
+    return run;
+}
+/**
+ * Writes the store with a fresh MAC, atomically (temp file in the same
+ * directory, then rename), mode 0o600. Preserves whatever format is
+ * currently on disk (issue #43): once `migrateTrustStoreToEncrypted` has
+ * been called, every subsequent write here stays v4; a brand-new or
+ * never-migrated store stays v3, exactly as before this issue.
+ */
+async function writeTrustStore(identity, entries) {
+    const raw = await readRaw(identity.storageDir);
+    const current = raw === undefined ? undefined : parse(raw);
+    const seq = (current?.seq ?? 0) + 1;
+    if (isV4(current)) {
+        await writeTrustStore4(identity, entries, seq);
+        return;
+    }
+    await writeStoreFile(identity, { version: 3, entries, seq, mac: computeMac(identity, entries, seq) }, seq);
+}
+async function writeTrustStore4(identity, entries, seq) {
+    const next = seq ?? (await currentSeq(identity)) + 1;
+    const { nonce, ciphertext } = encryptEntries(identity, entries);
+    await writeStoreFile(identity, { version: 4, nonce, ciphertext, seq: next, mac: computeMacV4(identity, nonce, ciphertext, next) }, next);
+}
+async function currentSeq(identity) {
+    const raw = await readRaw(identity.storageDir);
+    const seq = raw === undefined ? undefined : parse(raw).seq;
+    return typeof seq === "number" ? seq : 0;
+}
+/**
+ * One-time, explicit opt-in (issue #43/ADR 0027) to encrypt `trust.json`'s
+ * entries, so filesystem access alone no longer reveals who this identity
+ * trusts. A no-op if the store is already v4. A legacy (unauthenticated) file
+ * is not implicitly adopted here — call `migrateLegacyTrustStore` first, same
+ * as reading it would require.
+ */
+export function migrateTrustStoreToEncrypted(identity) {
+    return serialized(identity, async () => {
+        const raw = await readRaw(identity.storageDir);
+        const current = raw === undefined ? undefined : parse(raw);
+        const entries = await readTrustStore(identity); // verifies/decrypts whichever format; throws on a legacy or tampered file
+        if (isV4(current))
+            return; // already encrypted — true no-op, same spirit as migrateLegacyTrustStore's
+        await writeTrustStore4(identity, entries);
+    });
+}
+/**
+ * One-time, explicit adoption of a trust.json written before trust-store
+ * MACs existed (a v1 alias map or a v2 fingerprint-keyed file). Those files
+ * carry no proof of who wrote them, so they are never read implicitly (an
+ * attacker could otherwise plant one and bypass the MAC). Calling this says
+ * "I have reviewed the current file and it is mine": its records are kept
+ * and the file is rewritten authenticated. Returns the number of records
+ * adopted; returns 0 and changes nothing if the file is missing or already
+ * authenticated (a modified authenticated file still throws).
+ */
+export function migrateLegacyTrustStore(identity) {
+    return serialized(identity, async () => {
+        const raw = await readRaw(identity.storageDir);
+        if (raw === undefined)
+            return 0;
+        const data = parse(raw);
+        if (isV3(data) || isV4(data)) {
+            await readTrustStore(identity); // verifies (and decrypts, for v4); throws if tampered
+            return 0;
+        }
+        const entries = legacyEntries(data);
+        await writeTrustStore(identity, entries);
+        return Object.keys(entries).length;
+    });
 }
 /**
  * Records another party's public card as trusted, keyed by the card's
  * fingerprint (not alias — two different real parties could otherwise pick
  * the same alias and silently overwrite each other). Public keys are not
  * secret, so this file is plain JSON (unlike identity.enc.json), though it's
- * still permission-restricted to the owning user.
+ * permission-restricted to the owning user and, since ADR 0015, carries an
+ * HMAC (keyed from the Identity's secret keys) so edits are detected.
  *
  * Trusting a card again after it was revoked reinstates it (clears revokedAt).
  */
-export async function trustParty(identity, card) {
-    const store = await readTrustStore(identity.storageDir);
-    store.entries[fingerprint(card)] = { card, trustedAt: new Date().toISOString() };
-    await writeTrustStore(identity.storageDir, store);
+export function trustParty(identity, card) {
+    return serialized(identity, async () => {
+        const entries = await readTrustStore(identity);
+        entries[fingerprint(card)] = { card, trustedAt: new Date().toISOString() };
+        await writeTrustStore(identity, entries);
+        await appendLogEntry(identity, { action: "trust", counterpartAlias: card.alias });
+    });
 }
 /**
  * Revokes every currently-trusted card recorded under `alias` — e.g. after a
@@ -53,26 +366,49 @@ export async function trustParty(identity, card) {
  * lost, and so verify() can report "revoked-signer" distinctly from
  * "untrusted-signer" (never trusted at all).
  */
-export async function untrustParty(identity, alias) {
-    const store = await readTrustStore(identity.storageDir);
-    const revokedAt = new Date().toISOString();
-    for (const record of Object.values(store.entries)) {
-        if (record.card.alias === alias && !record.revokedAt)
-            record.revokedAt = revokedAt;
-    }
-    await writeTrustStore(identity.storageDir, store);
+export function untrustParty(identity, alias) {
+    return serialized(identity, async () => {
+        const entries = await readTrustStore(identity);
+        const revokedAt = new Date().toISOString();
+        for (const record of Object.values(entries)) {
+            if (record.card.alias === alias && !record.revokedAt)
+                record.revokedAt = revokedAt;
+        }
+        await writeTrustStore(identity, entries);
+        await appendLogEntry(identity, { action: "untrust", counterpartAlias: alias });
+    });
+}
+/**
+ * Revokes exactly one card, identified by its `fingerprint(card)` string
+ * (spaces and case are ignored). Unlike `untrustParty`, parties that merely
+ * share an alias are untouched — alias is a non-unique display label.
+ * Returns true if a currently-trusted record was revoked, false if no such
+ * trusted record exists (a typo'd fingerprint is reported, not ignored).
+ */
+export function untrustFingerprint(identity, fingerprintValue) {
+    const normalize = (value) => value.replace(/\s+/g, "").toUpperCase();
+    const wanted = normalize(fingerprintValue);
+    return serialized(identity, async () => {
+        const entries = await readTrustStore(identity);
+        const key = Object.keys(entries).find((candidate) => normalize(candidate) === wanted);
+        if (key === undefined || entries[key].revokedAt)
+            return false;
+        entries[key].revokedAt = new Date().toISOString();
+        await writeTrustStore(identity, entries);
+        await appendLogEntry(identity, { action: "untrust", counterpartAlias: entries[key].card.alias });
+        return true;
+    });
 }
 /** Every currently-trusted (non-revoked) card. */
 export async function listTrustedParties(identity) {
-    const store = await readTrustStore(identity.storageDir);
-    return Object.values(store.entries)
+    const entries = await readTrustStore(identity);
+    return Object.values(entries)
         .filter((record) => !record.revokedAt)
         .map((record) => record.card);
 }
 /** Every trust record ever made, revoked or not — for audit/history purposes. */
 export async function listTrustRecords(identity) {
-    const store = await readTrustStore(identity.storageDir);
-    return Object.values(store.entries);
+    return Object.values(await readTrustStore(identity));
 }
 /** The first currently-trusted (non-revoked) card recorded under this alias, if any. */
 export async function getTrustedParty(identity, alias) {
@@ -92,7 +428,165 @@ export async function getTrustedPartiesByAlias(identity, alias) {
 }
 /** All trust records (revoked or not) recorded under this alias. */
 export async function getTrustRecordsByAlias(identity, alias) {
-    const store = await readTrustStore(identity.storageDir);
-    return Object.values(store.entries).filter((record) => record.card.alias === alias);
+    return Object.values(await readTrustStore(identity)).filter((record) => record.card.alias === alias);
+}
+// --- Authenticated key lifecycle (issue #37 / ADR 0023) -----------------
+//
+// Everything below is an ordinary Certificate over a new document shape,
+// verified by reusing verifyCore — never a new signing or verification
+// primitive. The common trick: a SELF-signed document's trust basis isn't a
+// trust-store lookup, it's self-consistency (does the certificate's signer
+// match the card it's attached to?), so `cardMatchesSigner` stands in for
+// checkTrust wherever one of these functions verifies a self-signed card.
+/** True iff `signer` (a Certificate's signer fields) is the SAME party `card` claims to be — not a trust-store lookup, a self-consistency check. */
+function cardMatchesSigner(card, signer) {
+    return card.alias === signer.alias && card.classicalPublicKey === signer.classicalPublicKey && card.pqcSignPublicKey === signer.pqcSignPublicKey;
+}
+/**
+ * Verifies a self-signed card (from `exportSignedCard`) — checks the
+ * signature is self-consistent (the certificate's signer IS the card it's
+ * attached to) and, if the card carries an `expiresAt`, that it hasn't
+ * passed. Only on success does this call the ordinary `trustParty` to
+ * actually record it — self-signing proves the card is authentic and
+ * current, not that you've decided to trust it (Fingerprint confirmation
+ * is still the human-level trust decision, same as a bare card).
+ */
+export async function trustSignedCard(identity, card, certificate) {
+    const result = await verifyCore(identity, card, certificate, {
+        checkTrust: async (signer) => (cardMatchesSigner(card, signer) ? "trusted" : "untrusted"),
+    });
+    if (result.valid)
+        await trustParty(identity, card);
+    return result;
+}
+/**
+ * Starts a key rotation: the OLD identity signs a statement naming `newCard`
+ * as its successor. Hand the result to `completeRotation`, called with the
+ * NEW identity, to get a complete, dual-signed RotationStatement — a single
+ * signature from the old key alone is never enough to redirect a peer's
+ * trust (see `applyRotation`), so this function's output is not yet usable
+ * on its own. Even a dual-signed statement is only as trustworthy as the new
+ * fingerprint the receiver confirms out of band (`applyRotation`).
+ */
+export async function beginRotation(oldIdentity, newCard, options = {}) {
+    const rotatedAt = options.rotatedAt ?? new Date().toISOString();
+    if (!isValidIsoInstant(rotatedAt))
+        throw new Error(`rotatedAt must be a valid ISO-8601 instant in the exact format new Date().toISOString() produces; got ${JSON.stringify(rotatedAt)}.`);
+    const document = { oldCard: exportPublicIdentity(oldIdentity), newCard, rotatedAt };
+    const oldCertificate = await signCore(oldIdentity, document);
+    return { document, oldCertificate };
+}
+/**
+ * Finishes a key rotation: the NEW identity signs the SAME document
+ * `beginRotation` produced, proving the new key exists and agrees to be
+ * named as successor. This proves the statement's author controls the new
+ * key; it does NOT prove the new key belongs to the real owner — an attacker
+ * who stole the old key can mint their own "new" identity and complete the
+ * statement themselves. Receivers close that gap with `applyRotation`'s
+ * out-of-band `confirmNewFingerprint`.
+ */
+export async function completeRotation(newIdentity, draft) {
+    const newCertificate = await signCore(newIdentity, draft.document);
+    return { document: draft.document, oldCertificate: draft.oldCertificate, newCertificate };
+}
+/**
+ * Verifies a RotationStatement (both signatures self-consistent, both
+ * certificates over the identical document) and, only if `oldCard` already
+ * has an existing Trust Record, moves trust to `newCard` and tombstones
+ * `oldCard`'s record (revokedAt set, plus rotatedTo pointing at newCard's
+ * fingerprint). A statement for a card you never trusted is a no-op — this
+ * is not a way to seed your trust store with a card you never decided to
+ * trust in the first place.
+ *
+ * `options.confirmNewFingerprint` is REQUIRED: the new card's fingerprint as
+ * the real owner gave it to you over a channel the statement did not travel
+ * on (phone call, in person). Dual signatures alone only prove the author
+ * holds both keys; an attacker with a stolen old key supplies their own
+ * "new" key and signs both. Spacing and case are ignored when comparing.
+ * A mismatch returns `{ valid: false, reason: "fingerprint-mismatch" }` and
+ * changes nothing; a missing value throws (ADR 0029).
+ */
+export async function applyRotation(identity, statement, options) {
+    if (typeof options?.confirmNewFingerprint !== "string" || options.confirmNewFingerprint.trim() === "") {
+        throw new Error("applyRotation requires options.confirmNewFingerprint: the new card's fingerprint, confirmed with its owner out of band (ADR 0029).");
+    }
+    const { document, oldCertificate, newCertificate } = statement;
+    const oldResult = await verifyCore(identity, document, oldCertificate, {
+        checkTrust: async (signer) => (cardMatchesSigner(document.oldCard, signer) ? "trusted" : "untrusted"),
+    });
+    if (!oldResult.valid)
+        return oldResult;
+    const newResult = await verifyCore(identity, document, newCertificate, {
+        checkTrust: async (signer) => (cardMatchesSigner(document.newCard, signer) ? "trusted" : "untrusted"),
+    });
+    if (!newResult.valid)
+        return newResult;
+    const normalize = (value) => value.replace(/\s+/g, "").toUpperCase();
+    if (normalize(fingerprint(document.newCard)) !== normalize(options.confirmNewFingerprint)) {
+        return { valid: false, reason: "fingerprint-mismatch" };
+    }
+    // Signature checks above need no store access; only the read-modify-write is serialized.
+    return serialized(identity, async () => {
+        const entries = await readTrustStore(identity);
+        const oldKey = fingerprint(document.oldCard);
+        const existing = entries[oldKey];
+        if (!existing || existing.revokedAt)
+            return { valid: true }; // nothing trusted to migrate from — no-op
+        const revokedAt = new Date().toISOString();
+        entries[oldKey] = { ...existing, revokedAt, rotatedTo: fingerprint(document.newCard) };
+        entries[fingerprint(document.newCard)] = { card: document.newCard, trustedAt: revokedAt };
+        await writeTrustStore(identity, entries);
+        await appendLogEntry(identity, { action: "rotate", counterpartAlias: document.oldCard.alias });
+        return { valid: true };
+    });
+}
+/**
+ * Produces a self-signed, portable revocation notice for `identity`'s own
+ * card — verifiable by any peer independently of their (or your) local
+ * trust-store state. The same function works whether called reactively
+ * (retiring a key now) or right after createIdentity, to be stored
+ * separately and used later if this identity becomes inaccessible — that's
+ * what actually makes "recovery" possible for a lost passphrase or a lost
+ * identity file (ADR 0023): there is no special "pre-generated" mode, it's
+ * the same notice either way.
+ */
+export async function createRevocationNotice(identity, options = {}) {
+    const revokedAt = new Date().toISOString();
+    const document = {
+        revokedCard: exportPublicIdentity(identity),
+        revokedAt,
+        ...(options.reason !== undefined ? { reason: options.reason } : {}),
+    };
+    const certificate = await signCore(identity, document);
+    return { document, certificate };
+}
+/**
+ * Verifies a revocation notice (self-consistent, well-formed, `revokedAt`
+ * a valid ISO instant) and, only if the named card already has an existing
+ * Trust Record, tombstones it (revokedAt set) — exactly like
+ * `untrustFingerprint`. A notice for a card you never trusted is a no-op,
+ * for the same reason `applyRotation` is: this is not a pre-emptive
+ * denylist feature.
+ */
+export async function applyRevocationNotice(identity, notice) {
+    const { document, certificate } = notice;
+    if (!isValidIsoInstant(document.revokedAt))
+        return { valid: false, reason: "malformed-certificate" };
+    const result = await verifyCore(identity, document, certificate, {
+        checkTrust: async (signer) => (cardMatchesSigner(document.revokedCard, signer) ? "trusted" : "untrusted"),
+    });
+    if (!result.valid)
+        return result;
+    return serialized(identity, async () => {
+        const entries = await readTrustStore(identity);
+        const key = fingerprint(document.revokedCard);
+        const existing = entries[key];
+        if (!existing || existing.revokedAt)
+            return { valid: true }; // nothing trusted to revoke — no-op
+        entries[key] = { ...existing, revokedAt: document.revokedAt };
+        await writeTrustStore(identity, entries);
+        await appendLogEntry(identity, { action: "revoke", counterpartAlias: document.revokedCard.alias });
+        return { valid: true };
+    });
 }
 //# sourceMappingURL=trust.js.map