@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/lib/modules/core/directory/jelly-token.js

@@ -0,0 +1,305 @@
+/**
+ * Jelly ID resource tokens as a hosted realm verifies them (Jelly's contract v1.1 §4, §5, §11; spec §15.2):
+ * decoding, the verification steps against a key the caller has found, the key's validity window from the key
+ * history, the `cnf` binding, and the key archive → JWKS → key history lookup with the fetches injected (core
+ * does no I/O). Also the reading of Jelly's refusals when a host mints a bound token (§3, §6).
+ */
+import { verify as ed25519Verify } from "node:crypto";
+import { b64u, utf8 } from "../b64u.js";
+import { assertEd25519PublicKey, publicKeyFromRaw } from "../keys.js";
+import { parseWire } from "../wire.js";
+import { MessagingError } from "../schema/errors.js";
+import { ArchivedJellyKey, JELLY_DEVICE_SOURCE, JellyClaims, JellyHistoryKey, JellyJwk, JellyJwks, JellyKeyHistory, JellyTokenHeader, Jws, } from "../schema/jelly.js";
+/** Contract v1.1 §5 step 5: a token lives at most 900 s, and its `iat` may be at most 60 s ahead of now. */
+export const JELLY_MAX_LIFETIME_S = 900;
+export const JELLY_IAT_LEEWAY_S = 60;
+/** Contract v1.1 §5 step 2: Jelly's key set is believed for 24 h; the key history for 5 min. */
+export const JELLY_JWKS_TTL_MS = 24 * 60 * 60 * 1000;
+export const JELLY_HISTORY_TTL_MS = 5 * 60 * 1000;
+/** An archived key's revocation is rechecked against the key history when older than this (spec §15.2). */
+export const JELLY_REVOCATION_CHECK_MS = 24 * 60 * 60 * 1000;
+/** An unknown `kid` refetches a key set at most this often, so a stream of unknown `kid`s cannot loop. */
+export const JELLY_REFETCH_MIN_MS = 60 * 1000;
+/** The largest key set or key history read; a larger answer counts as unavailable. */
+const KEY_SET_BYTES = 1_048_576;
+const invalid = (what) => new MessagingError("binding_invalid", what);
+function segment(text, what) {
+    let bytes;
+    try {
+        bytes = b64u.decode(text);
+    }
+    catch {
+        throw invalid(`Jelly token ${what} is not base64url`);
+    }
+    try {
+        return parseWire(new TextDecoder("utf-8", { fatal: true }).decode(bytes), { maxBytes: 8192 });
+    }
+    catch {
+        throw invalid(`Jelly token ${what} is not JSON`);
+    }
+}
+/**
+ * Decodes a compact resource token: three base64url segments, a header with `alg: EdDSA`, `typ:
+ * jelly-resource+jwt` and a printable `kid`, and claims of the contract's shape (contract v1.1 §4, §5 step 1;
+ * `cnf`, when present, exactly `{jwk: {kty, crv, x}}`). Verifies nothing. Throws `binding_invalid`.
+ */
+export function decodeJellyToken(token) {
+    if (!Jws.safeParse(token).success)
+        throw invalid("Jelly token is not a compact JWS");
+    const [header, payload, signature] = token.split(".");
+    const parsedHeader = JellyTokenHeader.safeParse(segment(header, "header"));
+    if (!parsedHeader.success)
+        throw invalid("Jelly token header is not EdDSA jelly-resource+jwt with a key id");
+    const claims = JellyClaims.safeParse(segment(payload, "claims"));
+    if (!claims.success) {
+        const at = claims.error.issues[0]?.path.map(String).join(".");
+        throw invalid(`Jelly token claims are malformed${at ? ` at ${at}` : ""}`);
+    }
+    let sig;
+    try {
+        sig = b64u.decode(signature);
+    }
+    catch {
+        throw invalid("Jelly token signature is not base64url");
+    }
+    if (sig.length !== 64)
+        throw invalid("Jelly token signature is not 64 bytes");
+    return { header: parsedHeader.data, claims: claims.data, signingInput: utf8(`${header}.${payload}`), signature: sig };
+}
+/**
+ * True when a key may have signed a token issued at `iat` (seconds): always for a key seen only in the key set;
+ * for a key the history describes, `iat ∈ [nbf, retired_at)` (an open end while `retired_at` is null) and
+ * before any `revoked_at` (contract v1.1 §5 step 2, §11).
+ */
+export function jellyKeyCovers(key, iat) {
+    if (key.nbf !== undefined && iat < key.nbf)
+        return false;
+    if (key.retiredAt !== undefined && key.retiredAt !== null && iat >= key.retiredAt)
+        return false;
+    if (key.revokedAt !== undefined && key.revokedAt !== null && iat >= key.revokedAt)
+        return false;
+    return true;
+}
+/** True when `x` is a key Jelly ID would bind (contract v1.1 §3): a canonical Ed25519 point not of small order. */
+export function isBindableKey(x) {
+    try {
+        assertEd25519PublicKey(x, "cnf key");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The `cnf_jwk` a host asks Jelly ID to bind for `device` (contract v1.1 §3, §6). Throws `invalid_request` for an unusable key. */
+export function cnfJwk(device) {
+    assertEd25519PublicKey(device, "device key");
+    return { kty: "OKP", crv: "Ed25519", x: device };
+}
+/**
+ * Verifies a resource token (contract v1.1 §5; spec §15.2 steps 1–6): the header, the key and its window, the
+ * signature, `iss` and `aud`, the lifetime, `sub`, how it was minted (`hst`, or `src: "device"` with no `hst`), and
+ * `cnf`. Returns the decoded token. Throws
+ * `binding_invalid`; never reports a missing key as anything else (finding it is `JellyKeyring`'s).
+ */
+export function verifyJellyToken(token, options) {
+    const decoded = decodeJellyToken(token);
+    const { header, claims } = decoded;
+    const key = options.key(header.kid);
+    if (!key)
+        throw invalid("Jelly token names a key no source knows");
+    if (!jellyKeyCovers(key, claims.iat))
+        throw invalid("Jelly token was issued outside its key's validity");
+    let ok = false;
+    try {
+        ok = ed25519Verify(null, decoded.signingInput, publicKeyFromRaw("ed25519", key.x), decoded.signature);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw invalid("Jelly token signature does not verify");
+    if (claims.iss !== options.issuer)
+        throw invalid("Jelly token issuer is not the realm's");
+    if (claims.aud !== options.audience)
+        throw invalid("Jelly token audience is not the realm's resource");
+    if (claims.exp <= claims.iat || claims.exp - claims.iat > JELLY_MAX_LIFETIME_S)
+        throw invalid("Jelly token lifetime is not in (0, 900] seconds");
+    if (options.now !== undefined) {
+        const now = Math.floor(options.now / 1000);
+        if (claims.exp <= now)
+            throw invalid("Jelly token has expired");
+        if (claims.iat > now + JELLY_IAT_LEEWAY_S)
+            throw invalid("Jelly token is issued in the future");
+    }
+    // How it was minted (contract v1.1 §3, v1.2 §12.4): by a host (`hst`), or by a device that signed in
+    // through the browser (`src: "device"`, bound, no `hst`). Both, neither, or another `src` is not a token we know.
+    if (claims.src !== undefined) {
+        if (claims.src !== JELLY_DEVICE_SOURCE)
+            throw invalid("Jelly token was minted by a source Messaging does not know");
+        if (claims.hst !== undefined)
+            throw invalid("Jelly token names both a host and a device sign-in");
+        if (claims.cnf === undefined)
+            throw invalid("a Jelly token from a device sign-in is not bound to a key");
+    }
+    else if (claims.hst === undefined) {
+        throw invalid("Jelly token names neither a host nor a device sign-in");
+    }
+    if (claims.cnf !== undefined && !isBindableKey(claims.cnf.jwk.x))
+        throw invalid("Jelly token is bound to an unusable key");
+    if (options.cnf !== undefined) {
+        if (claims.cnf === undefined)
+            throw invalid("Jelly token is not bound to a key");
+        if (claims.cnf.jwk.x !== options.cnf)
+            throw invalid("Jelly token is bound to another key");
+    }
+    return decoded;
+}
+/**
+ * Finds the keys of resource tokens, in the order of spec §15.2: the client's own archive of every key it has
+ * verified, then Jelly ID's key set (cached 24 h; an unknown `kid` refetches it at most once a minute), then the
+ * key history (cached 5 min). A key found in the key set or the history joins the archive, with the history's
+ * window. An archived key whose revocation was last checked over 24 h ago is checked again, and keeps its archived
+ * window if the history cannot be fetched. Persist `archive()`; pass it back to the constructor.
+ */
+export class JellyKeyring {
+    #sources;
+    #archive = new Map();
+    #jwks;
+    #jwksTried = Number.NEGATIVE_INFINITY;
+    #history;
+    #historyTried = Number.NEGATIVE_INFINITY;
+    constructor(sources, archive = []) {
+        this.#sources = sources;
+        for (const key of archive) {
+            const parsed = ArchivedJellyKey.safeParse(key);
+            if (!parsed.success)
+                throw new MessagingError("invalid_request", "invalid archived Jelly key");
+            this.#archive.set(parsed.data.kid, parsed.data);
+        }
+    }
+    /** Every key this client has verified, to persist. */
+    archive() {
+        return [...this.#archive.values()].map((key) => ({ ...key }));
+    }
+    /** The archived key with this `kid`, without fetching. */
+    archived(kid) {
+        return this.#archive.get(kid);
+    }
+    /**
+     * Finds the keys of these tokens (a token that does not decode is skipped: verifying it fails anyway) and
+     * returns the synchronous lookup `verifyJellyToken` takes. Throws `jelly_unavailable` when a `kid` is in no
+     * source and a source it needed could not be fetched: never `binding_invalid` for an unreachable Jelly ID.
+     */
+    async prepare(tokens, now) {
+        const kids = new Set();
+        for (const token of tokens) {
+            try {
+                kids.add(decodeJellyToken(token).header.kid);
+            }
+            catch {
+                // Undecodable: verifyJellyToken refuses it.
+            }
+        }
+        for (const kid of kids)
+            await this.resolve(kid, now);
+        return (kid) => this.#archive.get(kid);
+    }
+    /** Finds one key (see the class). Returns undefined when every source answered and none knows it. */
+    async resolve(kid, now) {
+        const archived = this.#archive.get(kid);
+        if (archived) {
+            if (archived.historyAt === undefined || now - archived.historyAt > JELLY_REVOCATION_CHECK_MS) {
+                try {
+                    await this.#loadHistory(now);
+                }
+                catch {
+                    // Keep the archived window; the next use checks again.
+                }
+            }
+            return this.#archive.get(kid);
+        }
+        let unavailable = false;
+        try {
+            const fresh = this.#jwks !== undefined && now - this.#jwks.at <= JELLY_JWKS_TTL_MS;
+            if (!fresh || (!this.#jwks.keys.has(kid) && now - this.#jwksTried >= JELLY_REFETCH_MIN_MS))
+                await this.#loadJwks(now);
+        }
+        catch {
+            unavailable = true;
+        }
+        const fromSet = this.#jwks?.keys.get(kid);
+        try {
+            const fresh = this.#history !== undefined && now - this.#history.at <= JELLY_HISTORY_TTL_MS;
+            if (!fresh || (!this.#history.keys.has(kid) && now - this.#historyTried >= JELLY_REFETCH_MIN_MS))
+                await this.#loadHistory(now);
+        }
+        catch {
+            if (!fromSet)
+                unavailable = true;
+        }
+        const fromHistory = this.#history?.keys.get(kid);
+        if (fromSet) {
+            // The key set chooses the key (contract v1.1 §5 step 2); the history's window applies only to the same key.
+            this.#archive.set(kid, { kid, x: fromSet.x, ...(fromHistory?.x === fromSet.x ? this.#window(fromHistory, now) : {}) });
+        }
+        else if (fromHistory) {
+            this.#archive.set(kid, { kid, x: fromHistory.x, ...this.#window(fromHistory, now) });
+        }
+        const found = this.#archive.get(kid);
+        if (!found && unavailable)
+            throw new MessagingError("jelly_unavailable", "Jelly ID's keys could not be fetched");
+        return found;
+    }
+    #window(key, now) {
+        return { nbf: key.nbf, retiredAt: key.retired_at, revokedAt: key.revoked_at ?? null, historyAt: now };
+    }
+    async #loadJwks(now) {
+        this.#jwksTried = now;
+        const set = JellyJwks.parse(parseWire(await this.#sources.fetchJwks(), { maxBytes: KEY_SET_BYTES }));
+        const keys = new Map();
+        for (const entry of set.keys) {
+            const key = JellyJwk.safeParse(entry);
+            if (key.success && isBindableKey(key.data.x))
+                keys.set(key.data.kid, key.data);
+        }
+        this.#jwks = { at: now, keys };
+    }
+    async #loadHistory(now) {
+        this.#historyTried = now;
+        const history = JellyKeyHistory.parse(parseWire(await this.#sources.fetchHistory(), { maxBytes: KEY_SET_BYTES }));
+        const keys = new Map();
+        for (const entry of history.keys) {
+            const key = JellyHistoryKey.safeParse(entry);
+            if (key.success && isBindableKey(key.data.x))
+                keys.set(key.data.kid, key.data);
+        }
+        this.#history = { at: now, keys };
+        // Every archived key the history names takes its current window; a key under another `x` is not the same key.
+        for (const [kid, archived] of this.#archive) {
+            const seen = keys.get(kid);
+            if (seen && seen.x === archived.x)
+                this.#archive.set(kid, { kid, x: archived.x, ...this.#window(seen, now) });
+            else if (!seen)
+                this.#archive.set(kid, { ...archived, historyAt: now });
+        }
+    }
+}
+/**
+ * Reads a refusal from Jelly ID's mint route (`{error, detail?}`) or the engine accessor (an `Error` with
+ * `code` and `detail`). Branches on `detail`: a plain `invalid_target` still means no such resource.
+ */
+export function jellyMintRefusal(code, detail) {
+    switch (code) {
+        case "invalid_target":
+            return detail === "invalid_cnf_jwk" ? "unbindable_key" : "no_resource";
+        case "access_denied":
+            return "denied";
+        case "not_enrolled":
+        case "invalid_client":
+            return "not_enrolled";
+        case "invalid_request":
+            return "bad_request";
+        default:
+            return "retry";
+    }
+}

package/dist/lib/modules/core/directory/keys-statement.js

@@ -0,0 +1,43 @@
+/**
+ * Keys statements (spec §15.4): a hosted device's self-signed encryption key. They are not log entries, so a
+ * rotation does not grow the log; the map commits to each current device's latest statement.
+ */
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { sha256 } from "../hash.js";
+import { sign, verify } from "../sign.js";
+import { DOMAIN, LIMITS, PROTOCOL } from "../schema/common.js";
+import { KeysStatement } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+/** `SHA-256(JCS(statement))`, the signature included: what the map commits to. */
+export function keysStatementHash(statement) {
+    return sha256(canonicalize(statement));
+}
+/** This device's statement of its current encryption key. Throws `invalid_request`. */
+export function createKeysStatement(identity, args) {
+    const unsigned = { v: PROTOCOL, realm: args.realm, person: args.person, device: identity.machine, enc: identity.enc, seq: args.seq, ts: args.ts };
+    return parseWith(KeysStatement, { ...unsigned, sig: sign(identity, DOMAIN.deviceKeys, unsigned) }, "keys statement");
+}
+/**
+ * Checks a keys statement: the schema and `LIMITS.keysStatementBytes` (`invalid_request`, `too_large`), then
+ * the realm, the person, and the device's signature (`binding_invalid`). Whether the device is current, and
+ * whether `seq` is above the last one seen, are the caller's (`verifyPersonView` checks both).
+ */
+export function verifyKeysStatement(statement, context) {
+    try {
+        const parsed = parseWith(KeysStatement, statement, "keys statement");
+        if (Buffer.byteLength(canonicalize(parsed), "utf8") > LIMITS.keysStatementBytes)
+            throw new MessagingError("too_large", "keys statement is over its size limit");
+        if (parsed.realm !== context.realm)
+            throw new MessagingError("binding_invalid", "keys statement is for another realm");
+        if (parsed.person !== context.person)
+            throw new MessagingError("binding_invalid", "keys statement is for another person");
+        const { sig, ...unsigned } = parsed;
+        if (!verify(parsed.device, DOMAIN.deviceKeys, unsigned, sig))
+            throw new MessagingError("binding_invalid", "keys statement signature does not verify");
+        return parsed;
+    }
+    catch (error) {
+        throw asMessagingError(error, "keys statement");
+    }
+}

package/dist/lib/modules/core/directory/link.js

@@ -0,0 +1,81 @@
+/**
+ * Approving a new device by link (spec §15.3): the new device shows a signed link request as text (and a QR
+ * code) with a six-digit short authentication string; one of its person's Jelly-vouched devices checks both and
+ * appends the `bind`.
+ */
+import { createHash } from "node:crypto";
+import { b64u, utf8 } from "../b64u.js";
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { sign, verify } from "../sign.js";
+import { parseWire } from "../wire.js";
+import { DOMAIN, LIMITS, PROTOCOL } from "../schema/common.js";
+import { LinkRequest } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+/** The prefix of a link request's text form. A link is not a secret, but it should not travel through chat. */
+export const LINK_PREFIX = "messaging-link.";
+/** The largest link text read: far above a request's size. */
+const LINK_TEXT_BYTES = 2048;
+/** The new device's signed link request. Throws `invalid_request`. */
+export function createLinkRequest(identity, args) {
+    if (args.nonce.length !== 16)
+        throw new MessagingError("invalid_request", "link nonce must be 16 bytes");
+    const unsigned = { v: PROTOCOL, realm: args.realm, device: identity.machine, enc: identity.enc, label: args.label, kind: args.kind, nonce: b64u.encode(args.nonce), ts: args.ts };
+    return parseWith(LinkRequest, { ...unsigned, sig: sign(identity, DOMAIN.deviceLink, unsigned) }, "link request");
+}
+/** `messaging-link.` and the base64url of the request's JCS. */
+export function encodeLink(link) {
+    return LINK_PREFIX + b64u.encode(utf8(canonicalize(parseWith(LinkRequest, link, "link request"))));
+}
+/** Reads a link's text (surrounding whitespace ignored), with `parseWire`. Verifies nothing. Throws `invalid_request`. */
+export function decodeLink(text) {
+    const trimmed = typeof text === "string" ? text.trim() : "";
+    if (!trimmed.startsWith(LINK_PREFIX) || trimmed.length > LINK_TEXT_BYTES)
+        throw new MessagingError("invalid_request", "not a messaging-link text");
+    let json;
+    try {
+        json = new TextDecoder("utf-8", { fatal: true }).decode(b64u.decode(trimmed.slice(LINK_PREFIX.length)));
+    }
+    catch {
+        throw new MessagingError("invalid_request", "link text is not base64url of UTF-8");
+    }
+    return parseWith(LinkRequest, parseWire(json, { maxBytes: LINK_TEXT_BYTES }), "link request");
+}
+/** True when the request's signature is its device's. Never throws. */
+export function verifyLinkSignature(link) {
+    try {
+        const { sig, ...unsigned } = link;
+        return verify(link.device, DOMAIN.deviceLink, unsigned, sig);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What an approving device checks before it shows the request (§15.3): the schema (`invalid_request`), the
+ * signature and the realm (`binding_invalid`), and `ts` no older than `LIMITS.linkTtlMs` and no later than the
+ * clock skew ahead of `now` (`expired`).
+ */
+export function verifyLinkRequest(link, context) {
+    try {
+        const parsed = parseWith(LinkRequest, link, "link request");
+        if (!verifyLinkSignature(parsed))
+            throw new MessagingError("binding_invalid", "link request signature does not verify");
+        if (parsed.realm !== context.realm)
+            throw new MessagingError("binding_invalid", "link request is for another realm");
+        if (parsed.ts > context.now + LIMITS.clockSkewMs || context.now - parsed.ts > LIMITS.linkTtlMs)
+            throw new MessagingError("expired", "link request is outside its ten minutes");
+        return parsed;
+    }
+    catch (error) {
+        throw asMessagingError(error, "link request");
+    }
+}
+/**
+ * The six-digit short authentication string both devices show: the first four bytes of SHA-256(JCS(request)),
+ * big-endian, modulo 1,000,000, zero-padded. The person compares the two before approving.
+ */
+export function linkSas(link) {
+    const digest = createHash("sha256").update(utf8(canonicalize(parseWith(LinkRequest, link, "link request")))).digest();
+    return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}

package/dist/lib/modules/core/directory/merkle-log.js

@@ -0,0 +1,250 @@
+/**
+ * An RFC 9162 (Certificate Transparency 2.0) Merkle tree over SHA-256: the hashes, the tree head, and audit
+ * paths and consistency proofs, made and verified (spec §15.6). The epoch log of a hosted realm is one.
+ * Hashes cross the API as base64url (`Hash`); a malformed one makes a verification false, never a throw.
+ */
+import { createHash } from "node:crypto";
+import { b64u } from "../b64u.js";
+import { MessagingError } from "../schema/errors.js";
+const LEAF = Uint8Array.of(0x00);
+const NODE = Uint8Array.of(0x01);
+function digest(...parts) {
+    const hash = createHash("sha256");
+    for (const part of parts)
+        hash.update(part);
+    return new Uint8Array(hash.digest());
+}
+/** `SHA-256(0x00 ‖ data)`, the hash of a leaf. */
+export function merkleLeafHash(data) {
+    return b64u.encode(digest(LEAF, data));
+}
+function node(left, right) {
+    return digest(NODE, left, right);
+}
+/** The largest power of two below `n` (n ≥ 2). */
+function split(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function decode(hash) {
+    try {
+        const bytes = b64u.decode(hash);
+        return bytes.length === 32 ? bytes : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/** True for 1, 2, 4, …: exact for every safe integer (no 32-bit bitwise operators). */
+function isPowerOfTwo(n) {
+    while (n > 1 && n % 2 === 0)
+        n /= 2;
+    return n === 1;
+}
+function isSize(n) {
+    return Number.isSafeInteger(n) && n >= 0;
+}
+/**
+ * The leaf hashes of a log, appended in order. It answers the tree head at any size it holds, and the audit
+ * path and consistency proof between sizes (RFC 9162 §2.1.1-§2.1.4). Subtree roots are cached, so a proof
+ * costs O(log² n) hashes after the first.
+ */
+export class MerkleLog {
+    #leaves = [];
+    #cache = new Map();
+    /** A log of these leaf hashes (from `merkleLeafHash`), in order. */
+    static fromLeafHashes(hashes) {
+        const log = new MerkleLog();
+        for (const hash of hashes)
+            log.appendLeafHash(hash);
+        return log;
+    }
+    get size() {
+        return this.#leaves.length;
+    }
+    /** Appends the leaf whose data is `data`; returns its index. */
+    append(data) {
+        return this.appendLeafHash(merkleLeafHash(data));
+    }
+    /** Appends a leaf by its hash; returns its index. */
+    appendLeafHash(hash) {
+        const bytes = decode(hash);
+        if (!bytes)
+            throw new MessagingError("invalid_request", "leaf hash must be 32 bytes of base64url");
+        this.#leaves.push(bytes);
+        return this.#leaves.length - 1;
+    }
+    /** The root the log would have with the leaf `hash` appended; the log itself does not change. */
+    rootWith(hash) {
+        const bytes = decode(hash);
+        if (!bytes)
+            throw new MessagingError("invalid_request", "leaf hash must be 32 bytes of base64url");
+        const size = this.#leaves.length;
+        this.#leaves.push(bytes);
+        try {
+            return b64u.encode(this.#mth(0, size + 1));
+        }
+        finally {
+            this.#leaves.pop();
+            // The complete subtrees that end at the new leaf are not this log's.
+            for (let n = 1; n <= size + 1; n *= 2)
+                this.#cache.delete(`${size + 1 - n}:${n}`);
+        }
+    }
+    leafHash(index) {
+        this.#size(index + 1);
+        return b64u.encode(this.#leaves[index]);
+    }
+    /** MTH of the first `size` leaves (default: all). The empty tree's root is SHA-256 of nothing. */
+    root(size = this.size) {
+        this.#size(size);
+        return b64u.encode(size === 0 ? digest() : this.#mth(0, size));
+    }
+    /** The audit path of leaf `index` in the tree of the first `size` leaves, bottom up (RFC 9162 §2.1.3.1). */
+    inclusionProof(index, size = this.size) {
+        this.#size(size);
+        if (!isSize(index) || index >= size)
+            throw new MessagingError("invalid_request", "leaf index is beyond the tree size");
+        return this.#path(index, 0, size).map((hash) => b64u.encode(hash));
+    }
+    /** The consistency proof from the tree of `from` leaves to the tree of `size` leaves (RFC 9162 §2.1.4.1). */
+    consistencyProof(from, size = this.size) {
+        this.#size(size);
+        if (!isSize(from) || from > size)
+            throw new MessagingError("invalid_request", "consistency proof from a size beyond the tree");
+        if (from === 0 || from === size)
+            return [];
+        return this.#subproof(from, 0, size, true).map((hash) => b64u.encode(hash));
+    }
+    #size(size) {
+        if (!isSize(size) || size > this.#leaves.length)
+            throw new MessagingError("invalid_request", "tree size is beyond the log");
+    }
+    /** MTH(D[start:start+n]), n ≥ 1. Complete subtrees (n a power of two) are cached: they never change. */
+    #mth(start, n) {
+        if (n === 1)
+            return this.#leaves[start];
+        const complete = isPowerOfTwo(n);
+        const key = `${start}:${n}`;
+        if (complete) {
+            const cached = this.#cache.get(key);
+            if (cached)
+                return cached;
+        }
+        const k = split(n);
+        const hash = node(this.#mth(start, k), this.#mth(start + k, n - k));
+        if (complete)
+            this.#cache.set(key, hash);
+        return hash;
+    }
+    /** PATH(m, D[start:start+n]). */
+    #path(m, start, n) {
+        if (n === 1)
+            return [];
+        const k = split(n);
+        return m < k ? [...this.#path(m, start, k), this.#mth(start + k, n - k)] : [...this.#path(m - k, start + k, n - k), this.#mth(start, k)];
+    }
+    /** SUBPROOF(m, D[start:start+n], b). */
+    #subproof(m, start, n, whole) {
+        if (m === n)
+            return whole ? [] : [this.#mth(start, n)];
+        const k = split(n);
+        return m <= k
+            ? [...this.#subproof(m, start, k, whole), this.#mth(start + k, n - k)]
+            : [...this.#subproof(m - k, start + k, n - k, false), this.#mth(start, k)];
+    }
+}
+/**
+ * True when `proof` is the audit path of the leaf with hash `leafHash` at `index` in a tree of `size` leaves
+ * whose root is `root` (RFC 9162 §2.1.3.2). Never throws.
+ */
+export function verifyInclusion(index, size, leafHash, proof, root) {
+    if (!isSize(index) || !isSize(size) || index >= size || !Array.isArray(proof))
+        return false;
+    const leaf = decode(leafHash);
+    const expected = decode(root);
+    const path = proof.map(decode);
+    if (!leaf || !expected || path.some((hash) => !hash))
+        return false;
+    let fn = index;
+    let sn = size - 1;
+    let r = leaf;
+    for (const p of path) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            r = node(p, r);
+            if (fn % 2 === 0) {
+                while (fn % 2 === 0 && fn !== 0) {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                }
+            }
+        }
+        else {
+            r = node(r, p);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && equal(r, expected);
+}
+/**
+ * True when `proof` shows that the tree of `size1` leaves with root `root1` is a prefix of the tree of `size2`
+ * leaves with root `root2` (RFC 9162 §2.1.4.2). Equal sizes need an empty proof and equal roots; a proof from
+ * the empty tree proves nothing and is false. Never throws.
+ */
+export function verifyConsistency(size1, size2, proof, root1, root2) {
+    if (!isSize(size1) || !isSize(size2) || size1 === 0 || size2 < size1 || !Array.isArray(proof))
+        return false;
+    const first = decode(root1);
+    const second = decode(root2);
+    const path = proof.map(decode);
+    if (!first || !second || path.some((hash) => !hash))
+        return false;
+    if (size1 === size2)
+        return path.length === 0 && equal(first, second);
+    const c = [...path];
+    if (c.length === 0)
+        return false;
+    if (isPowerOfTwo(size1))
+        c.unshift(first);
+    let fn = size1 - 1;
+    let sn = size2 - 1;
+    while (fn % 2 === 1) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    let fr = c[0];
+    let sr = c[0];
+    for (const p of c.slice(1)) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            fr = node(p, fr);
+            sr = node(p, sr);
+            if (fn % 2 === 0) {
+                while (fn % 2 === 0 && fn !== 0) {
+                    fn = Math.floor(fn / 2);
+                    sn = Math.floor(sn / 2);
+                }
+            }
+        }
+        else {
+            sr = node(sr, p);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && equal(fr, first) && equal(sr, second);
+}