raz-encrypt 0.3.0 → 2.1.0

package/dist/trust.d.ts

@@ -1,16 +1,62 @@
-import type { Identity, PublicCard } from "./identity.js";
+import { type Certificate, type VerifyResult } from "./crypto/hybrid.js";
+import { type Identity, type PublicCard } from "./identity.js";
 export interface TrustRecord {
     card: PublicCard;
     trustedAt: string;
     /** Set when this party was later revoked (see untrustParty). Absent = still trusted. */
     revokedAt?: string;
+    /**
+     * Set alongside revokedAt when this record was tombstoned by a verified
+     * rotation (applyRotation), not an ordinary revocation: the fingerprint of
+     * the card this party rotated TO. Informational only — verify() still
+     * reports "revoked-signer" for this record either way (ADR 0023/issue
+     * #37); nothing reads this field to change verification behavior.
+     */
+    rotatedTo?: string;
 }
+type Entries = Record<string, TrustRecord>;
+/**
+ * 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 declare class TrustStoreIntegrityError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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 declare function macMatches(identity: Identity, entries: Entries, mac: unknown): boolean;
+/**
+ * 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 declare function migrateTrustStoreToEncrypted(identity: Identity): Promise<void>;
+/**
+ * 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 declare function migrateLegacyTrustStore(identity: Identity): Promise<number>;
 /**
  * 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).
  */
@@ -23,6 +69,14 @@ export declare function trustParty(identity: Identity, card: PublicCard): Promis
  * "untrusted-signer" (never trusted at all).
  */
 export declare function untrustParty(identity: Identity, alias: string): Promise<void>;
+/**
+ * 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 declare function untrustFingerprint(identity: Identity, fingerprintValue: string): Promise<boolean>;
 /** Every currently-trusted (non-revoked) card. */
 export declare function listTrustedParties(identity: Identity): Promise<PublicCard[]>;
 /** Every trust record ever made, revoked or not — for audit/history purposes. */
@@ -39,3 +93,90 @@ export declare function getTrustedParty(identity: Identity, alias: string): Prom
 export declare function getTrustedPartiesByAlias(identity: Identity, alias: string): Promise<PublicCard[]>;
 /** All trust records (revoked or not) recorded under this alias. */
 export declare function getTrustRecordsByAlias(identity: Identity, alias: string): Promise<TrustRecord[]>;
+/**
+ * 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 declare function trustSignedCard(identity: Identity, card: PublicCard, certificate: Certificate): Promise<VerifyResult>;
+export interface RotationDocument {
+    oldCard: PublicCard;
+    newCard: PublicCard;
+    rotatedAt: string;
+}
+export interface RotationStatement {
+    document: RotationDocument;
+    oldCertificate: Certificate;
+    newCertificate: Certificate;
+}
+/**
+ * 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.
+ */
+export declare function beginRotation(oldIdentity: Identity, newCard: PublicCard, options?: {
+    rotatedAt?: string;
+}): Promise<{
+    document: RotationDocument;
+    oldCertificate: Certificate;
+}>;
+/**
+ * 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 — not just asserted unilaterally by whoever holds the
+ * old key (which could be an attacker who compromised it alone).
+ */
+export declare function completeRotation(newIdentity: Identity, draft: {
+    document: RotationDocument;
+    oldCertificate: Certificate;
+}): Promise<RotationStatement>;
+/**
+ * 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.
+ */
+export declare function applyRotation(identity: Identity, statement: RotationStatement): Promise<VerifyResult>;
+export interface RevocationDocument {
+    revokedCard: PublicCard;
+    revokedAt: string;
+    reason?: string;
+}
+/** A Certificate only stores its document's HASH, not the document itself (same as everywhere else in this codebase) — so a revocation notice bundles the document alongside its certificate, the same shape RotationStatement already uses for the same reason. */
+export interface RevocationNotice {
+    document: RevocationDocument;
+    certificate: Certificate;
+}
+/**
+ * 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 declare function createRevocationNotice(identity: Identity, options?: {
+    reason?: string;
+}): Promise<RevocationNotice>;
+/**
+ * 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 declare function applyRevocationNotice(identity: Identity, notice: RevocationNotice): Promise<VerifyResult>;
+export {};

package/dist/trust.js

@@ -1,50 +1,250 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+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 { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { canonicalize } from "./canonicalJson.js";
+import { isValidIsoInstant, signCore, verifyCore } from "./crypto/hybrid.js";
 import { fingerprint } from "./fingerprint.js";
+import { exportPublicIdentity } from "./identity.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");
 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);
+}
+function computeMac(identity, entries) {
+    return bytesToHex(hmac(sha384, deriveTrustStoreKey(identity), utf8ToBytes(canonicalize({ version: 3, entries }))));
+}
+/**
+ * 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) {
+    if (typeof mac !== "string" || !/^[0-9a-f]{96}$/.test(mac))
+        return false;
+    return equalBytes(hexToBytes(mac), hexToBytes(computeMac(identity, entries)));
+}
+/** 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) {
+    return bytesToHex(hmac(sha384, deriveTrustStoreKey(identity), utf8ToBytes(canonicalize({ version: 4, nonce, ciphertext }))));
+}
+function macMatchesV4(identity, nonce, ciphertext, mac) {
+    if (typeof mac !== "string" || !/^[0-9a-f]{96}$/.test(mac))
+        return false;
+    return equalBytes(hexToBytes(mac), hexToBytes(computeMacV4(identity, nonce, ciphertext)));
+}
+/** 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);
+}
+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);
+}
 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) {
-    let raw;
+async function readRaw(storageDir) {
     try {
-        raw = await readFile(trustFilePath(storageDir), "utf8");
+        return await readFile(trustFilePath(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);
 }
-async function writeTrustStore(storageDir, store) {
-    await mkdir(storageDir, { recursive: true });
-    await writeFile(trustFilePath(storageDir), JSON.stringify(store, null, 2), { mode: 0o600 });
+function parse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new TrustStoreIntegrityError("trust.json is not valid JSON; refusing to use it.");
+    }
+}
+/** Reads and AUTHENTICATES the trust store, transparently decrypting a v4 (issue #43) file. Missing file = empty store. Anything unauthenticated throws TrustStoreIntegrityError. */
+async function readTrustStore(identity) {
+    const raw = await readRaw(identity.storageDir);
+    if (raw === undefined)
+        return {};
+    const data = parse(raw);
+    if (isV4(data)) {
+        if (!macMatchesV4(identity, data.nonce, data.ciphertext, data.mac)) {
+            throw new TrustStoreIntegrityError("trust.json failed its integrity check: it was modified, truncated, or belongs to a different identity.");
+        }
+        return decryptEntries(identity, data.nonce, data.ciphertext);
+    }
+    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.");
+    }
+    if (!macMatches(identity, data.entries, data.mac)) {
+        throw new TrustStoreIntegrityError("trust.json failed its integrity check: it was modified, truncated, or belongs to a different identity.");
+    }
+    return data.entries;
+}
+async function writeStoreFile(identity, store) {
+    await mkdir(identity.storageDir, { recursive: true, mode: 0o700 });
+    const finalPath = trustFilePath(identity.storageDir);
+    const tmpPath = `${finalPath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await writeFile(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+        await rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        await rm(tmpPath, { force: true });
+        throw err;
+    }
+}
+/**
+ * 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);
+    if (isV4(current)) {
+        await writeTrustStore4(identity, entries);
+        return;
+    }
+    await writeStoreFile(identity, { version: 3, entries, mac: computeMac(identity, entries) });
+}
+async function writeTrustStore4(identity, entries) {
+    const { nonce, ciphertext } = encryptEntries(identity, entries);
+    await writeStoreFile(identity, { version: 4, nonce, ciphertext, mac: computeMacV4(identity, nonce, ciphertext) });
+}
+/**
+ * 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 async function migrateTrustStoreToEncrypted(identity) {
+    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 async function migrateLegacyTrustStore(identity) {
+    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);
+    const entries = await readTrustStore(identity);
+    entries[fingerprint(card)] = { card, trustedAt: new Date().toISOString() };
+    await writeTrustStore(identity, entries);
 }
 /**
  * Revokes every currently-trusted card recorded under `alias` — e.g. after a
@@ -54,25 +254,42 @@ export async function trustParty(identity, card) {
  * "untrusted-signer" (never trusted at all).
  */
 export async function untrustParty(identity, alias) {
-    const store = await readTrustStore(identity.storageDir);
+    const entries = await readTrustStore(identity);
     const revokedAt = new Date().toISOString();
-    for (const record of Object.values(store.entries)) {
+    for (const record of Object.values(entries)) {
         if (record.card.alias === alias && !record.revokedAt)
             record.revokedAt = revokedAt;
     }
-    await writeTrustStore(identity.storageDir, store);
+    await writeTrustStore(identity, entries);
+}
+/**
+ * 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 async function untrustFingerprint(identity, fingerprintValue) {
+    const normalize = (value) => value.replace(/\s+/g, "").toUpperCase();
+    const wanted = normalize(fingerprintValue);
+    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);
+    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 +309,139 @@ 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.
+ */
+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 — not just asserted unilaterally by whoever holds the
+ * old key (which could be an attacker who compromised it alone).
+ */
+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.
+ */
+export async function applyRotation(identity, statement) {
+    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 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);
+    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;
+    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);
+    return { valid: true };
 }
 //# sourceMappingURL=trust.js.map