@zanii/blackbox 0.2.0 → 0.4.0

package/dist/transparency/index.js

@@ -0,0 +1,712 @@
+// Transparency (spec/transparency.md): deterministic CBOR, COSE_Sign1 Signed Statements (RFC 9052,
+// SCITT RFC 9943), RFC 9162 Merkle trees and proofs, COSE Receipts (RFC 9942), and C2SP signed notes,
+// checkpoints and witness cosignatures. Pure functions with node:crypto only, pinned with the Python
+// SDK by spec/vectors/transparency.json. Mirrors zanii_blackbox/transparency.py.
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { canonicalBytes } from "@zanii/core";
+import { verifyTimestamp } from "../timestamp/index.js";
+import { hashLine } from "../verify/envelope.js";
+export const tagged = (tag, value) => ({ tag, value });
+const head = (major, n) => {
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new RangeError("cbor: argument out of range");
+    const m = major << 5;
+    if (n < 24)
+        return Buffer.from([m | n]);
+    if (n < 0x100)
+        return Buffer.from([m | 24, n]);
+    if (n < 0x10000)
+        return Buffer.from([m | 25, n >> 8, n & 0xff]);
+    if (n < 0x100000000) {
+        const b = Buffer.alloc(5);
+        b[0] = m | 26;
+        b.writeUInt32BE(n, 1);
+        return b;
+    }
+    const b = Buffer.alloc(9);
+    b[0] = m | 27;
+    b.writeBigUInt64BE(BigInt(n), 1);
+    return b;
+};
+export function cborEncode(v) {
+    if (typeof v === "number")
+        return v >= 0 ? head(0, v) : head(1, -1 - v);
+    if (typeof v === "string") {
+        const b = Buffer.from(v, "utf8");
+        return Buffer.concat([head(3, b.length), b]);
+    }
+    if (v instanceof Uint8Array)
+        return Buffer.concat([head(2, v.length), Buffer.from(v)]);
+    if (v === false)
+        return Buffer.from([0xf4]);
+    if (v === true)
+        return Buffer.from([0xf5]);
+    if (v === null)
+        return Buffer.from([0xf6]);
+    if (Array.isArray(v))
+        return Buffer.concat([head(4, v.length), ...v.map(cborEncode)]);
+    if (v instanceof Map) {
+        const entries = [...v.entries()].map(([k, x]) => [cborEncode(k), cborEncode(x)]);
+        entries.sort((a, b) => Buffer.compare(a[0], b[0]));
+        for (let i = 1; i < entries.length; i++)
+            if (Buffer.compare(entries[i - 1][0], entries[i][0]) === 0)
+                throw new Error("cbor: duplicate map key");
+        return Buffer.concat([head(5, entries.length), ...entries.flat()]);
+    }
+    return Buffer.concat([head(6, v.tag), cborEncode(v.value)]);
+}
+/** Decodes one deterministic CBOR item; throws on anything else (indefinite lengths, floats, extra bytes). */
+export function cborDecode(bytes) {
+    const buf = Buffer.from(bytes);
+    let at = 0;
+    const arg = (ai) => {
+        if (ai < 24)
+            return ai;
+        const n = ai === 24 ? 1 : ai === 25 ? 2 : ai === 26 ? 4 : ai === 27 ? 8 : 0;
+        if (n === 0 || at + n > buf.length)
+            throw new Error("cbor: bad argument");
+        const v = n === 8 ? Number(buf.readBigUInt64BE(at)) : buf.readUIntBE(at, n);
+        at += n;
+        if (!Number.isSafeInteger(v))
+            throw new Error("cbor: integer too large");
+        const min = n === 1 ? 24 : n === 2 ? 0x100 : n === 4 ? 0x10000 : 0x100000000;
+        if (v < min)
+            throw new Error("cbor: not the shortest form");
+        return v;
+    };
+    const item = (depth) => {
+        if (depth > 32 || at >= buf.length)
+            throw new Error("cbor: truncated");
+        const ib = buf[at++];
+        const major = ib >> 5;
+        const ai = ib & 31;
+        if (major === 7) {
+            if (ib === 0xf4)
+                return false;
+            if (ib === 0xf5)
+                return true;
+            if (ib === 0xf6)
+                return null;
+            throw new Error("cbor: unsupported simple value or float");
+        }
+        const n = arg(ai);
+        if (major === 0)
+            return n;
+        if (major === 1)
+            return -1 - n;
+        if (major === 2 || major === 3) {
+            if (at + n > buf.length)
+                throw new Error("cbor: truncated");
+            const s = buf.subarray(at, at + n);
+            at += n;
+            return major === 2 ? new Uint8Array(s) : s.toString("utf8");
+        }
+        if (major === 4)
+            return Array.from({ length: n }, () => item(depth + 1));
+        if (major === 5) {
+            const m = new Map();
+            let last = null;
+            for (let i = 0; i < n; i++) {
+                const start = at;
+                const k = item(depth + 1);
+                const kb = buf.subarray(start, at);
+                if (last && Buffer.compare(last, kb) >= 0)
+                    throw new Error("cbor: map keys not in order");
+                last = kb;
+                m.set(k, item(depth + 1));
+            }
+            return m;
+        }
+        return { tag: n, value: item(depth + 1) };
+    };
+    const v = item(0);
+    if (at !== buf.length)
+        throw new Error("cbor: extra bytes");
+    return v;
+}
+// ---------------------------------------------------------------- Ed25519 (raw 32-byte keys)
+const PKCS8 = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI = Buffer.from("302a300506032b6570032100", "hex");
+const priv = (seed) => createPrivateKey({
+    key: Buffer.concat([PKCS8, Buffer.from(seed)]),
+    format: "der",
+    type: "pkcs8",
+});
+const pub = (key) => createPublicKey({ key: Buffer.concat([SPKI, Buffer.from(key)]), format: "der", type: "spki" });
+export const ed25519Sign = (seed, msg) => new Uint8Array(sign(null, msg, priv(seed)));
+export function ed25519Verify(publicKey, msg, sig) {
+    try {
+        return publicKey.length === 32 && sig.length === 64 && verify(null, msg, pub(publicKey), sig);
+    }
+    catch {
+        return false;
+    }
+}
+export const ed25519PublicKey = (seed) => new Uint8Array(createPublicKey(priv(seed)).export({ format: "der", type: "spki" }).subarray(-32));
+const sha256 = (...parts) => {
+    const h = createHash("sha256");
+    for (const p of parts)
+        h.update(p);
+    return new Uint8Array(h.digest());
+};
+// ---------------------------------------------------------------- COSE_Sign1 (RFC 9052, RFC 9864)
+export const ALG_ED25519 = -19;
+const ALG_EDDSA = -8; // deprecated; accepted when verifying, never made
+const SIG1 = (protectedBytes, payload) => cborEncode(["Signature1", protectedBytes, new Uint8Array(0), payload]);
+/** A SCITT Signed Statement: tagged COSE_Sign1, Ed25519 (alg -19), empty unprotected header, payload attached. */
+export function signStatement(input, seed) {
+    const protectedBytes = cborEncode(new Map([
+        [1, ALG_ED25519],
+        [3, input.contentType],
+        [4, input.kid],
+        [
+            15,
+            new Map([
+                [1, input.iss],
+                [2, input.sub],
+                [6, input.iat],
+            ]),
+        ],
+    ]));
+    const sig = ed25519Sign(seed, SIG1(protectedBytes, input.payload));
+    return new Uint8Array(cborEncode(tagged(18, [protectedBytes, new Map(), input.payload, sig])));
+}
+/** Parses a tagged COSE_Sign1; throws if it isn't one. */
+export function parseCoseSign1(bytes) {
+    const v = cborDecode(bytes);
+    const arr = v?.tag === 18 ? v.value : null;
+    if (!Array.isArray(arr) || arr.length !== 4)
+        throw new Error("not a tagged COSE_Sign1");
+    const [p, u, payload, signature] = arr;
+    if (!(p instanceof Uint8Array) || !(u instanceof Map) || !(signature instanceof Uint8Array))
+        throw new Error("not a COSE_Sign1");
+    if (payload !== null && !(payload instanceof Uint8Array))
+        throw new Error("bad COSE payload");
+    const prot = p.length === 0 ? new Map() : cborDecode(p);
+    if (!(prot instanceof Map))
+        throw new Error("bad protected header");
+    return { protectedBytes: p, protected: prot, unprotected: u, payload, signature };
+}
+/** Does a COSE_Sign1 verify with this Ed25519 key? `detached`: the payload, when it isn't attached. */
+export function verifyCoseSign1(bytes, publicKey, detached) {
+    try {
+        const c = parseCoseSign1(bytes);
+        const alg = c.protected.get(1);
+        if (alg !== ALG_ED25519 && alg !== ALG_EDDSA)
+            return false;
+        const payload = c.payload ?? detached;
+        if (!payload)
+            return false;
+        return ed25519Verify(publicKey, SIG1(c.protectedBytes, payload), c.signature);
+    }
+    catch {
+        return false;
+    }
+}
+/** The bytes a log entry is: the statement with its unprotected header emptied (RFC 9943 §6.3). */
+export function statementEntry(statement) {
+    const c = parseCoseSign1(statement);
+    return new Uint8Array(cborEncode(tagged(18, [c.protectedBytes, new Map(), c.payload, c.signature])));
+}
+// ---------------------------------------------------------------- RFC 9162 Merkle trees
+export const leafHash = (entry) => sha256(Uint8Array.of(0), entry);
+const nodeHash = (l, r) => sha256(Uint8Array.of(1), l, r);
+const split = (n) => {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+};
+/** MTH over leaf hashes (already `leafHash`ed). */
+export function merkleRoot(leaves) {
+    if (leaves.length === 0)
+        return sha256();
+    if (leaves.length === 1)
+        return leaves[0];
+    const k = split(leaves.length);
+    return nodeHash(merkleRoot(leaves.slice(0, k)), merkleRoot(leaves.slice(k)));
+}
+/** The audit path for leaf `m` in a tree of these leaf hashes, leaf to root. */
+export function inclusionProof(m, leaves) {
+    if (leaves.length <= 1)
+        return [];
+    const k = split(leaves.length);
+    return m < k
+        ? [...inclusionProof(m, leaves.slice(0, k)), merkleRoot(leaves.slice(k))]
+        : [...inclusionProof(m - k, leaves.slice(k)), merkleRoot(leaves.slice(0, k))];
+}
+const eq = (a, b) => a.length === b.length && Buffer.compare(a, b) === 0;
+/** RFC 9162 §2.1.3.2: does `path` prove leaf `index` (its hash) in a tree of `size` with `root`? */
+export function verifyInclusion(leaf, index, size, path, root) {
+    return eq(rootFromInclusion(leaf, index, size, path) ?? new Uint8Array(), root);
+}
+function rootFromInclusion(leaf, index, size, path) {
+    if (index >= size || index < 0)
+        return null;
+    let fn = index;
+    let sn = size - 1;
+    let r = leaf;
+    for (const p of path) {
+        if (sn === 0)
+            return null;
+        if (fn & 1 || fn === sn) {
+            r = nodeHash(p, r);
+            if (!(fn & 1))
+                while (!(fn & 1) && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+        }
+        else
+            r = nodeHash(r, p);
+        fn >>= 1;
+        sn >>= 1;
+    }
+    return sn === 0 ? r : null;
+}
+/** RFC 9162 §2.1.4.1: proof that the tree of the first `m` leaves is a prefix of all of them. */
+export function consistencyProof(m, leaves) {
+    const sub = (mm, d, b) => {
+        if (mm === d.length)
+            return b ? [] : [merkleRoot(d)];
+        const k = split(d.length);
+        return mm <= k
+            ? [...sub(mm, d.slice(0, k), b), merkleRoot(d.slice(k))]
+            : [...sub(mm - k, d.slice(k), false), merkleRoot(d.slice(0, k))];
+    };
+    return m === 0 || m === leaves.length ? [] : sub(m, leaves, true);
+}
+/** RFC 9162 §2.1.4.2, with the trivial cases: an empty first tree, and equal sizes. */
+export function verifyConsistency(first, second, firstRoot, secondRoot, proof) {
+    if (first === 0)
+        return proof.length === 0;
+    if (first === second)
+        return proof.length === 0 && eq(firstRoot, secondRoot);
+    if (first > second || proof.length === 0)
+        return false;
+    const path = (first & (first - 1)) === 0 ? [firstRoot, ...proof] : [...proof];
+    let fn = first - 1;
+    let sn = second - 1;
+    while (fn & 1) {
+        fn >>= 1;
+        sn >>= 1;
+    }
+    let fr = path[0];
+    let sr = path[0];
+    for (const c of path.slice(1)) {
+        if (sn === 0)
+            return false;
+        if (fn & 1 || fn === sn) {
+            fr = nodeHash(c, fr);
+            sr = nodeHash(c, sr);
+            if (!(fn & 1))
+                while (!(fn & 1) && fn !== 0) {
+                    fn >>= 1;
+                    sn >>= 1;
+                }
+        }
+        else
+            sr = nodeHash(sr, c);
+        fn >>= 1;
+        sn >>= 1;
+    }
+    return eq(fr, firstRoot) && eq(sr, secondRoot) && sn === 0;
+}
+/** A receipt of inclusion (vds RFC9162_SHA256): signed over the root, payload detached. */
+export function makeReceipt(proof, signer) {
+    const protectedBytes = cborEncode(new Map([
+        [1, ALG_ED25519],
+        [4, signer.kid],
+        [
+            15,
+            new Map([
+                [1, signer.iss],
+                [2, signer.sub],
+            ]),
+        ],
+        [395, 1],
+    ]));
+    const inclusion = cborEncode([proof.size, proof.index, [...proof.path]]);
+    const sig = ed25519Sign(signer.seed, SIG1(protectedBytes, proof.root));
+    const unprotected = new Map([[396, new Map([[-1, [inclusion]]])]]);
+    return new Uint8Array(cborEncode(tagged(18, [protectedBytes, unprotected, null, sig])));
+}
+/** RFC 9942 §5.2.1: does the receipt prove this entry (the statement, unprotected emptied) under this key?
+ * Returns the tree size and leaf index it proves, or null. Accepts a size-1 tree's empty path. */
+export function verifyReceipt(receipt, entry, publicKey) {
+    try {
+        const c = parseCoseSign1(receipt);
+        if (c.protected.get(395) !== 1)
+            return null;
+        const vdp = c.unprotected.get(396);
+        const proofs = vdp instanceof Map ? vdp.get(-1) : undefined;
+        if (!Array.isArray(proofs) || proofs.length < 1)
+            return null;
+        for (const bytes of proofs) {
+            if (!(bytes instanceof Uint8Array))
+                continue;
+            const p = cborDecode(bytes);
+            if (!Array.isArray(p) || p.length !== 3)
+                continue;
+            const [size, index, path] = p;
+            if (typeof size !== "number" || typeof index !== "number" || !Array.isArray(path))
+                continue;
+            if (!path.every((x) => x instanceof Uint8Array && x.length === 32))
+                continue;
+            const root = rootFromInclusion(leafHash(entry), index, size, path);
+            if (root && verifyCoseSign1(receipt, publicKey, root))
+                return { size, index };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A Transparent Statement: the statement with its receipts in unprotected header 394. */
+export function transparentStatement(statement, receipts) {
+    const c = parseCoseSign1(statement);
+    const unprotected = new Map([[394, [...receipts]]]);
+    return new Uint8Array(cborEncode(tagged(18, [c.protectedBytes, unprotected, c.payload, c.signature])));
+}
+// ---------------------------------------------------------------- C2SP signed notes, checkpoints, cosignatures
+const EM = "—";
+const b64 = (b) => Buffer.from(b).toString("base64");
+const unb64 = (s) => new Uint8Array(Buffer.from(s, "base64"));
+/** c2sp.org/signed-note: SHA-256(name || "\n" || type || public key)[:4]. Type 0x01 note, 0x04 cosignature. */
+export const noteKeyId = (name, type, publicKey) => sha256(Buffer.from(`${name}\n`, "utf8"), Uint8Array.of(type), publicKey).subarray(0, 4);
+/** A verifier key string: `name+hex(keyID)+base64(type || public key)`. */
+export const noteVkey = (name, type, publicKey) => `${name}+${Buffer.from(noteKeyId(name, type, publicKey)).toString("hex")}+${b64(Buffer.concat([Uint8Array.of(type), publicKey]))}`;
+export function parseVkey(vkey) {
+    // name+keyid+key: the base64 key may itself hold "+", so only the first two separate
+    const a = vkey.indexOf("+");
+    const b = vkey.indexOf("+", a + 1);
+    if (a < 1 || b < 0)
+        return null;
+    const name = vkey.slice(0, a);
+    const hexId = vkey.slice(a + 1, b);
+    const key = vkey.slice(b + 1);
+    const raw = unb64(key);
+    const type = raw[0];
+    const size = type === 6 ? 1 + MLDSA44_PUBLIC : 33;
+    if (!name || !/^[0-9a-f]{8}$/.test(hexId) || raw.length !== size)
+        return null;
+    const publicKey = raw.subarray(1);
+    if (Buffer.from(noteKeyId(name, type, publicKey)).toString("hex") !== hexId)
+        return null;
+    return { name, type, keyId: noteKeyId(name, type, publicKey), publicKey };
+}
+/** Signs a note's text (which ends in "\n") as `name`; returns the note with its signature line. */
+export function signNote(text, name, seed) {
+    if (!text.endsWith("\n"))
+        throw new Error("a note's text ends in a newline");
+    const id = noteKeyId(name, 1, ed25519PublicKey(seed));
+    const sig = ed25519Sign(seed, Buffer.from(text, "utf8"));
+    return `${text}\n${EM} ${name} ${b64(Buffer.concat([id, sig]))}\n`;
+}
+/** Splits a signed note into its text and signature lines. */
+export function splitNote(note) {
+    const i = note.lastIndexOf("\n\n");
+    if (i < 0)
+        return null;
+    const text = note.slice(0, i + 1);
+    const signatures = [];
+    for (const line of note.slice(i + 2).split("\n")) {
+        if (line === "")
+            continue;
+        const m = /^— (\S+) (\S+)$/.exec(line);
+        if (!m)
+            return null;
+        const raw = unb64(m[2]);
+        if (raw.length < 5)
+            return null;
+        signatures.push({ name: m[1], keyId: raw.subarray(0, 4), sig: raw.subarray(4) });
+    }
+    return { text, signatures };
+}
+/** Is the note signed (type 0x01) by this vkey? */
+export function verifyNote(note, vkey) {
+    const k = parseVkey(vkey);
+    const n = splitNote(note);
+    if (!k || !n || k.type !== 1)
+        return false;
+    return n.signatures.some((s) => s.name === k.name &&
+        eq(s.keyId, k.keyId) &&
+        ed25519Verify(k.publicKey, Buffer.from(n.text, "utf8"), s.sig));
+}
+/**
+ * §9: a log key rotation, as a note signed by the old key and the new one: the new key's vkey, the
+ * tree size it takes over at, and when. A verifier that pinned the old key follows it to the new.
+ */
+export function keyRotationNote(old, next, size, time) {
+    const oldVkey = noteVkey(old.origin, 1, ed25519PublicKey(old.seed));
+    const newVkey = noteVkey(next.origin, 1, ed25519PublicKey(next.seed));
+    const text = `zanii-blackbox/log-key-rotation/v1\nold ${oldVkey}\nnew ${newVkey}\nsize ${size}\ntime ${time}\n`;
+    const signed = signNote(text, old.origin, old.seed);
+    return signed + signNote(text, next.origin, next.seed).slice(text.length + 1);
+}
+/** §9: the new key, size and time a rotation note names, if the old key and the new one both signed it. */
+export function verifyKeyRotation(note, oldVkey) {
+    const n = splitNote(note);
+    const m = n
+        ? /^zanii-blackbox\/log-key-rotation\/v1\nold (\S+)\nnew (\S+)\nsize (0|[1-9][0-9]{0,15})\ntime (0|[1-9][0-9]{0,15})\n$/.exec(n.text)
+        : null;
+    if (!m || m[1] !== oldVkey)
+        return null;
+    const newVkey = m[2];
+    if (parseVkey(newVkey)?.type !== 1 || !verifyNote(note, oldVkey) || !verifyNote(note, newVkey))
+        return null;
+    return { new_vkey: newVkey, size: Number(m[3]), time: Number(m[4]) };
+}
+/** c2sp.org/tlog-checkpoint: origin, size, base64 root, each on its own line. */
+export const checkpointText = (origin, size, root) => `${origin}\n${size}\n${b64(root)}\n`;
+export function parseCheckpoint(text) {
+    const lines = text.split("\n");
+    if (lines.length < 4 || lines.at(-1) !== "")
+        return null;
+    const [origin, size, root] = lines;
+    if (!origin || !/^(0|[1-9][0-9]{0,15})$/.test(size))
+        return null;
+    const r = unb64(root);
+    if (r.length !== 32 || b64(r) !== root)
+        return null;
+    return { origin, size: Number(size), root: r };
+}
+/** c2sp.org/tlog-cosignature: the witness's timestamped Ed25519 cosignature (type 0x04) on a checkpoint. */
+export function cosign(checkpoint, name, seed, time) {
+    const id = noteKeyId(name, 4, ed25519PublicKey(seed));
+    const ts = Buffer.alloc(8);
+    ts.writeBigUInt64BE(BigInt(time));
+    const sig = ed25519Sign(seed, Buffer.from(`cosignature/v1\ntime ${time}\n${checkpoint}`, "utf8"));
+    return `${EM} ${name} ${b64(Buffer.concat([id, ts, sig]))}\n`;
+}
+// ---------------------------------------------------------------- ML-DSA-44 (FIPS 204, pure, empty context)
+const MLDSA44_PUBLIC = 1312;
+const MLDSA44_SIG = 2420;
+const MLDSA44_PKCS8 = Buffer.from("3034020100300b060960864801650304031104228020", "hex");
+const MLDSA44_SPKI = Buffer.from("30820532300b06096086480165030403110382052100", "hex");
+const mldsaKey = (seed) => {
+    if (seed.length !== 32)
+        throw new Error("an ML-DSA-44 seed is 32 bytes");
+    return createPrivateKey({
+        key: Buffer.concat([MLDSA44_PKCS8, seed]),
+        format: "der",
+        type: "pkcs8",
+    });
+};
+/** The raw ML-DSA-44 public key (1312 bytes) for a 32-byte seed. Needs Node ≥ 24.6. */
+export const mldsaPublicKey = (seed) => new Uint8Array(createPublicKey(mldsaKey(seed))
+    .export({ format: "der", type: "spki" })
+    .subarray(MLDSA44_SPKI.length));
+/** Whether this runtime has ML-DSA (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export function mldsaAvailable() {
+    try {
+        mldsaPublicKey(new Uint8Array(32));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const mldsaVerify = (publicKey, msg, sig) => {
+    try {
+        const key = createPublicKey({
+            key: Buffer.concat([MLDSA44_SPKI, publicKey]),
+            format: "der",
+            type: "spki",
+        });
+        return verify(null, msg, key, sig);
+    }
+    catch {
+        return false;
+    }
+};
+/** c2sp.org/tlog-cosignature v1.1 (type 0x06): what an ML-DSA-44 subtree cosignature signs. */
+export function subtreeMessage(name, time, origin, start, end, hash) {
+    const n = Buffer.from(name, "utf8");
+    const o = Buffer.from(origin, "utf8");
+    if (n.length > 255 || o.length > 255)
+        throw new Error("names and origins are at most 255 bytes");
+    const u64 = (v) => {
+        const b = Buffer.alloc(8);
+        b.writeBigUInt64BE(BigInt(v));
+        return b;
+    };
+    return new Uint8Array(Buffer.concat([
+        Buffer.from("subtree/v1\n\0", "latin1"),
+        Uint8Array.of(n.length),
+        n,
+        u64(time),
+        Uint8Array.of(o.length),
+        o,
+        u64(start),
+        u64(end),
+        hash,
+    ]));
+}
+/** An ML-DSA-44 cosignature line (type 0x06) on a checkpoint: what a log or witness adds for post-quantum. */
+export function cosignMldsa(checkpoint, name, seed, time) {
+    const cp = parseCheckpoint(checkpoint);
+    if (!cp)
+        throw new Error("not a checkpoint");
+    const id = noteKeyId(name, 6, mldsaPublicKey(seed));
+    const ts = Buffer.alloc(8);
+    ts.writeBigUInt64BE(BigInt(time));
+    const sig = sign(null, subtreeMessage(name, time, cp.origin, 0, cp.size, cp.root), mldsaKey(seed));
+    return `${EM} ${name} ${b64(Buffer.concat([id, ts, sig]))}\n`;
+}
+/**
+ * The time a cosignature (in a note's signature lines) says it saw the checkpoint, or null. Takes a
+ * witness's Ed25519 vkey (type 0x04) or an ML-DSA-44 one (type 0x06).
+ */
+export function verifyCosignature(note, vkey) {
+    const k = parseVkey(vkey);
+    const n = splitNote(note);
+    if (!k || !n || (k.type !== 4 && k.type !== 6))
+        return null;
+    if (k.type === 6) {
+        const cp = parseCheckpoint(n.text);
+        if (!cp)
+            return null;
+        for (const s of n.signatures) {
+            if (s.name !== k.name || !eq(s.keyId, k.keyId) || s.sig.length !== 8 + MLDSA44_SIG)
+                continue;
+            const time = Number(Buffer.from(s.sig.subarray(0, 8)).readBigUInt64BE());
+            const msg = subtreeMessage(k.name, time, cp.origin, 0, cp.size, cp.root);
+            if (mldsaVerify(k.publicKey, msg, s.sig.subarray(8)))
+                return time;
+        }
+        return null;
+    }
+    for (const s of n.signatures) {
+        if (s.name !== k.name || !eq(s.keyId, k.keyId) || s.sig.length !== 72)
+            continue;
+        const time = Number(Buffer.from(s.sig.subarray(0, 8)).readBigUInt64BE());
+        const msg = Buffer.from(`cosignature/v1\ntime ${time}\n${n.text}`, "utf8");
+        if (ed25519Verify(k.publicKey, msg, s.sig.subarray(8)))
+            return time;
+    }
+    return null;
+}
+/** c2sp.org/tlog-witness: the body of `POST add-checkpoint`. */
+export const addCheckpointBody = (old, proof, signedCheckpoint) => `old ${old}\n${proof.map((p) => `${b64(p)}\n`).join("")}\n${signedCheckpoint}`;
+export function parseAddCheckpoint(body) {
+    const i = body.indexOf("\n\n");
+    if (i < 0)
+        return null;
+    const lines = body.slice(0, i).split("\n");
+    const m = /^old (0|[1-9][0-9]{0,15})$/.exec(lines[0] ?? "");
+    if (!m || lines.length - 1 > 63)
+        return null;
+    const proof = lines.slice(1).map(unb64);
+    if (proof.some((p) => p.length !== 32))
+        return null;
+    return { old: Number(m[1]), proof, note: body.slice(i + 2) };
+}
+// ---------------------------------------------------------------- the gateway's log (spec/transparency.md)
+export const SESSION_CONTENT_TYPE = "application/vnd.zanii.blackbox.session+json";
+export const RECEIPT_SUB = "transparency-log";
+/** spec/transparency.md §1: the first 8 bytes of SHA-256(public key). */
+export const logKid = (publicKey) => sha256(publicKey).subarray(0, 8);
+/** spec/transparency.md §2: the Signed Statement a closed session gets. `iat` is `closed_at` in seconds. */
+export function sessionStatement(head, origin, seed) {
+    const payload = canonicalBytes({ v: 1, ...head });
+    return signStatement({
+        contentType: SESSION_CONTENT_TYPE,
+        payload: new Uint8Array(payload),
+        iss: origin,
+        sub: head.session_id,
+        iat: Math.floor(Date.parse(head.closed_at) / 1000),
+        kid: logKid(ed25519PublicKey(seed)),
+    }, seed);
+}
+/**
+ * spec/transparency.md §6: checks a bundle's `transparency` offline, against a log key the verifier
+ * pins (a C2SP vkey, type 0x01) and the witnesses it trusts (vkeys, type 0x04).
+ */
+export function verifyTransparency(bundle, options) {
+    const report = {
+        ok: false,
+        statement: false,
+        receipt: null,
+        checkpoint: null,
+        witnessed: [],
+        timestamp: null,
+        pq: null,
+        problems: [],
+    };
+    const t = bundle.transparency;
+    const key = parseVkey(options.logKey);
+    if (!key || key.type !== 1)
+        return { ...report, problems: ["the log key isn't a C2SP note key (type 0x01)"] };
+    if (!t || typeof t.statement !== "string")
+        return { ...report, problems: ["the bundle has no transparency statement"] };
+    const statement = unb64(t.statement);
+    if (!verifyCoseSign1(statement, key.publicKey))
+        report.problems.push("the statement doesn't verify under the log key");
+    else {
+        const payload = JSON.parse(Buffer.from(parseCoseSign1(statement).payload ?? new Uint8Array()).toString("utf8"));
+        const last = bundle.lines.at(-1);
+        if (payload.session_id !== bundle.session.session_id)
+            report.problems.push("the statement is about another session");
+        else if (payload.count !== bundle.lines.length ||
+            last === undefined ||
+            payload.head !== hashLine(last))
+            report.problems.push("the statement's count and head aren't this record's");
+        else
+            report.statement = true;
+    }
+    if (typeof t.checkpoint === "string") {
+        const text = splitNote(t.checkpoint)?.text;
+        const cp = text ? parseCheckpoint(text) : null;
+        if (!cp || !verifyNote(t.checkpoint, options.logKey))
+            report.problems.push("the checkpoint isn't signed by the log key");
+        else {
+            report.checkpoint = { origin: cp.origin, size: cp.size };
+            report.witnessed = (options.witnesses ?? []).filter((w) => verifyCosignature(t.checkpoint, w) !== null);
+            if (options.logPqKey !== undefined) {
+                report.pq = verifyCosignature(t.checkpoint, options.logPqKey) !== null;
+                if (!report.pq)
+                    report.problems.push("the checkpoint has no ML-DSA-44 signature from the log");
+            }
+            if (typeof t.timestamp === "string") {
+                const digest = new Uint8Array(createHash("sha256")
+                    .update(text)
+                    .digest());
+                const ts = verifyTimestamp(unb64(t.timestamp), {
+                    digest,
+                    ...(options.tsaRoots ? { roots: options.tsaRoots } : {}),
+                });
+                if (ts.ok)
+                    report.timestamp = ts.gen_time;
+                else
+                    report.problems.push(`the checkpoint's timestamp doesn't verify: ${ts.problems.join("; ")}`);
+            }
+            if (typeof t.receipt === "string") {
+                const proved = verifyReceipt(unb64(t.receipt), statementEntry(statement), key.publicKey);
+                const root = proved ? receiptRoot(unb64(t.receipt), statementEntry(statement)) : null;
+                if (!proved)
+                    report.problems.push("the receipt doesn't prove this statement");
+                else if (proved.size !== cp.size || !root || !eq(root, cp.root))
+                    report.problems.push("the receipt isn't for the checkpoint's tree");
+                else
+                    report.receipt = proved;
+            }
+            else
+                report.problems.push("the bundle has no receipt yet");
+        }
+    }
+    else
+        report.problems.push("the bundle has no checkpoint yet");
+    report.ok = report.problems.length === 0;
+    return report;
+}
+/** The root a receipt's first inclusion proof gives for this entry. */
+function receiptRoot(receipt, entry) {
+    const vdp = parseCoseSign1(receipt).unprotected.get(396);
+    const first = vdp instanceof Map ? vdp.get(-1)?.[0] : undefined;
+    if (!(first instanceof Uint8Array))
+        return null;
+    const [size, index, path] = cborDecode(first);
+    return rootFromInclusion(leafHash(entry), index, size, path);
+}