@joe-broadhead/messaging 0.0.0-stage → 0.7.0

package/dist/lib/modules/core/directory/person-view.js

@@ -0,0 +1,197 @@
+/**
+ * Verifying a person (spec §15.7): a client checks what the directory serves of one person against the STH it
+ * adopted: the log extends what it holds, every entry passes the authority rules, every Jelly binding first
+ * appeared in an epoch before its token expired, the keys statements are the current devices', and the map at
+ * the STH's last epoch commits to exactly that log head and those keys.
+ */
+import { asMessagingError, parseWith } from "../check.js";
+import { PersonHead, PersonView } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+import { DeviceLog, logEntryHash } from "./device-log.js";
+import { verifyEpochProof } from "./epoch.js";
+import { keysStatementHash, verifyKeysStatement } from "./keys-statement.js";
+import { mapValue, TOMBSTONE, verifyMapProof } from "./smt.js";
+/** `directory_inconsistent`, with the evidence a client keeps and shows in its alarm. Its message never holds values. */
+export class DirectoryInconsistency extends MessagingError {
+    evidence;
+    constructor(message, evidence) {
+        super("directory_inconsistent", message);
+        this.name = "DirectoryInconsistency";
+        this.evidence = evidence;
+    }
+}
+const fail = (what) => new MessagingError("directory_inconsistent", what);
+/**
+ * Verifies one person's view and returns their new state (spec §15.7). Errors: `invalid_request` (shapes),
+ * `binding_invalid` (an entry, a keys statement, or a binding that first appeared in an epoch after its token's
+ * life), the log's own codes, and `directory_inconsistent` (a `DirectoryInconsistency` with evidence when the
+ * directory contradicts what the client holds; a plain one for a proof that fails).
+ */
+export function verifyPersonView(view, context) {
+    try {
+        const parsed = parseWith(PersonView, view, "person view");
+        const { sth, known } = context;
+        if (known && known.person !== parsed.person)
+            throw new MessagingError("invalid_request", "the known state is another person's");
+        const head = verifyEpochProof(sth, context.head);
+        if (head.index !== sth.size - 1)
+            throw fail("the head epoch is not the tree head's last");
+        const mapRoot = head.leaf.mapRoot;
+        const logContext = { ...context, person: parsed.person };
+        if (parsed.tombstone) {
+            if (parsed.log.length > 0 || parsed.keys.length > 0 || (parsed.epochs?.length ?? 0) > 0)
+                throw new MessagingError("invalid_request", "an erased person has no log or keys");
+            if (!verifyMapProof(mapRoot, parsed.person, TOMBSTONE, parsed.mapProof))
+                throw new DirectoryInconsistency("the map does not hold the tombstone", { kind: "map", sth, head });
+            return { person: parsed.person, log: known?.log ?? new DeviceLog(context.realm, parsed.person), keys: new Map(), erased: true };
+        }
+        // 1. The log extends what the client holds; an overlap must be the same entries.
+        const log = known ? known.log.clone() : new DeviceLog(context.realm, parsed.person);
+        const held = log.length;
+        let start = held;
+        if (parsed.log.length > 0) {
+            const first = parsed.log[0].seq;
+            if (first > held)
+                throw fail("the log skips entries after those held");
+            for (const entry of parsed.log.slice(0, Math.max(0, held - first))) {
+                const ours = log.entries()[entry.seq];
+                if (logEntryHash(ours) !== logEntryHash(entry))
+                    throw new DirectoryInconsistency("the log differs from the one held", { kind: "fork", seq: entry.seq, ours, theirs: entry });
+            }
+            start = Math.max(held, first);
+            for (const entry of parsed.log.slice(start - first)) {
+                try {
+                    log.append(entry, logContext);
+                }
+                catch (error) {
+                    if (error instanceof MessagingError && error.code === "log_conflict" && held > 0 && entry.seq === held) {
+                        throw new DirectoryInconsistency("the log forks from the one held", { kind: "fork", seq: held - 1, ours: log.entries()[held - 1], theirs: entry });
+                    }
+                    throw error;
+                }
+            }
+        }
+        // 2. Every new Jelly binding first appeared in an epoch before its token expired (freshness at the append).
+        const witnesses = new Map((parsed.epochs ?? []).map((witness) => [witness.seq, witness]));
+        for (let seq = start; seq < log.length; seq++) {
+            const deadline = log.bindingDeadline(seq);
+            if (deadline === undefined)
+                continue;
+            const witness = witnesses.get(seq);
+            if (!witness)
+                throw new MessagingError("binding_invalid", "a Jelly binding comes without the epoch it first appeared in");
+            checkWitness(witness, seq, deadline, log, parsed.person, sth);
+        }
+        // 3. The keys statements: one per current device, each signed by it, none older than one held.
+        const keys = new Map();
+        for (const raw of parsed.keys) {
+            const statement = verifyKeysStatement(raw, { realm: context.realm, person: parsed.person });
+            if (!log.device(statement.device)?.current)
+                throw new MessagingError("binding_invalid", "a keys statement is for a device that is not current");
+            if (keys.has(statement.device))
+                throw new MessagingError("invalid_request", "two keys statements for one device");
+            const ours = known?.keys.get(statement.device);
+            if (ours && statement.seq < ours.seq)
+                throw new DirectoryInconsistency("a keys statement is older than the one held", { kind: "rollback", what: "keys", ours: ours.seq, theirs: statement.seq });
+            if (ours && statement.seq === ours.seq && keysStatementHash(statement) !== keysStatementHash(ours))
+                throw fail("two keys statements share a device and seq");
+            keys.set(statement.device, statement);
+        }
+        for (const [device, ours] of known?.keys ?? []) {
+            if (log.device(device)?.current && !keys.has(device))
+                throw new DirectoryInconsistency("a held keys statement is withheld", { kind: "rollback", what: "keys", ours: ours.seq, theirs: -1 });
+        }
+        // 4. The map at the tree head commits to exactly this head and these keys.
+        const logHead = log.head();
+        if (!logHead) {
+            if (!verifyMapProof(mapRoot, parsed.person, undefined, parsed.mapProof))
+                throw new DirectoryInconsistency("the map holds a person served as absent", { kind: "map", sth, head });
+        }
+        else {
+            const value = mapValue({ log: logHead, keys: [...keys.values()].sort((a, b) => (a.device < b.device ? -1 : 1)).map(keysStatementHash) });
+            if (!verifyMapProof(mapRoot, parsed.person, value, parsed.mapProof))
+                throw new DirectoryInconsistency("the map does not commit to the log and keys served", { kind: "map", sth, head });
+        }
+        return { person: parsed.person, log, keys, erased: false };
+    }
+    catch (error) {
+        throw asMessagingError(error, "person view");
+    }
+}
+/**
+ * Two states of one person, each verified (`verifyPersonView`) at its own tree head of one adopted epoch log, `earlier`
+ * at a size at most `later`'s (spec §15.9, "One tree head per view"). The later must extend the earlier: the same
+ * entries at every seq the earlier holds, and, for each device still current, a keys statement at least as new.
+ * A client that verified two views of a person concurrently checks them against each other with this instead of
+ * one against the other's tree head. An erased state on either side is not compared (an erase drops the log).
+ * Throws a `DirectoryInconsistency` with the evidence.
+ */
+export function checkPersonSuccession(earlier, later) {
+    if (earlier.person !== later.person)
+        throw new MessagingError("invalid_request", "the two states are of two persons");
+    if (earlier.erased || later.erased)
+        return;
+    const ours = earlier.log.entries();
+    const theirs = later.log.entries();
+    if (theirs.length < ours.length)
+        throw new DirectoryInconsistency("a later tree head serves a shorter log", { kind: "rollback", what: "log", ours: ours.length, theirs: theirs.length });
+    for (let seq = 0; seq < ours.length; seq++) {
+        if (logEntryHash(ours[seq]) !== logEntryHash(theirs[seq]))
+            throw new DirectoryInconsistency("the log differs from the one held", { kind: "fork", seq, ours: ours[seq], theirs: theirs[seq] });
+    }
+    for (const [device, statement] of earlier.keys) {
+        if (!later.log.device(device)?.current)
+            continue;
+        const next = later.keys.get(device);
+        if (!next)
+            throw new DirectoryInconsistency("a held keys statement is withheld", { kind: "rollback", what: "keys", ours: statement.seq, theirs: -1 });
+        if (next.seq < statement.seq)
+            throw new DirectoryInconsistency("a keys statement is older than the one held", { kind: "rollback", what: "keys", ours: statement.seq, theirs: next.seq });
+        if (next.seq === statement.seq && keysStatementHash(next) !== keysStatementHash(statement))
+            throw fail("two keys statements share a device and seq");
+    }
+}
+/** Entry `seq` was in the map by an epoch whose `ts` is at most `deadline` (spec §15.7). Throws. */
+function checkWitness(witness, seq, deadline, log, person, sth) {
+    const epoch = verifyEpochProof(sth, witness.epoch);
+    const committed = witness.value.log;
+    if (committed.seq < seq || log.hashAt(committed.seq) !== committed.hash)
+        throw fail("an epoch witness commits to another log");
+    if (!verifyMapProof(epoch.leaf.mapRoot, person, mapValue(witness.value), witness.mapProof))
+        throw fail("an epoch witness's map proof does not verify");
+    if (epoch.leaf.ts > deadline)
+        throw new MessagingError("binding_invalid", "a Jelly binding first appeared after its token's life");
+}
+/**
+ * Verifies one person's head (spec §7, `dir.heads`) against the STH a client adopted: the map at its last epoch holds
+ * exactly that value (`mapValue` of the preimage), the tombstone, or nothing. It proves the log head a device binding
+ * to the person extends (`seq + 1`, `prev` = `hash`), and nothing about the entries before it.
+ */
+export function verifyPersonHead(view, context) {
+    try {
+        const parsed = parseWith(PersonHead, view, "person head");
+        const { sth } = context;
+        const head = verifyEpochProof(sth, context.head);
+        if (head.index !== sth.size - 1)
+            throw fail("the head epoch is not the tree head's last");
+        const mapRoot = head.leaf.mapRoot;
+        if (parsed.tombstone) {
+            if (parsed.value)
+                throw new MessagingError("invalid_request", "an erased person has no head");
+            if (!verifyMapProof(mapRoot, parsed.person, TOMBSTONE, parsed.mapProof))
+                throw new DirectoryInconsistency("the map does not hold the tombstone", { kind: "map", sth, head });
+            return { person: parsed.person, state: "erased" };
+        }
+        if (!parsed.value) {
+            if (!verifyMapProof(mapRoot, parsed.person, undefined, parsed.mapProof))
+                throw new DirectoryInconsistency("the map holds a person served as absent", { kind: "map", sth, head });
+            return { person: parsed.person, state: "absent" };
+        }
+        if (!verifyMapProof(mapRoot, parsed.person, mapValue(parsed.value), parsed.mapProof))
+            throw new DirectoryInconsistency("the map does not commit to the head served", { kind: "map", sth, head });
+        return { person: parsed.person, state: "live", log: parsed.value.log, keys: parsed.value.keys };
+    }
+    catch (error) {
+        throw asMessagingError(error, "person head");
+    }
+}

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

@@ -0,0 +1,40 @@
+/**
+ * The hosted `PersonId` (spec §15.1): a Jelly account `(iss, sub)` hashed into `p_` and 26 base32 characters
+ * (130 bits). A roster person name cannot collide with it: `_` is not allowed in a person name.
+ */
+import { createHash } from "node:crypto";
+import { utf8 } from "../b64u.js";
+import { parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { DOMAIN } from "../schema/common.js";
+import { JellySubject } from "../schema/jelly.js";
+import { z } from "../../vendor/zod/index.js";
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+/** RFC 4648 §6 base32 in lower case, without padding. */
+export function base32Lower(bytes) {
+    let out = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += BASE32[(buffer >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    if (bits > 0)
+        out += BASE32[(buffer << (5 - bits)) & 31];
+    return out;
+}
+const Account = z.object({ iss: z.string().min(1).max(2048), sub: JellySubject });
+/**
+ * `"p_" + base32lower(SHA-256(UTF-8("messaging/1/person\n") ‖ UTF-8(JCS({iss, sub}))))[0..26]`. `iss` is the
+ * issuer exactly as the token states it; `sub` must be a Jelly account id (`acc_…`). Throws `invalid_request`.
+ */
+export function personId(iss, sub) {
+    const account = parseWith(Account, { iss, sub }, "Jelly account");
+    const digest = createHash("sha256").update(utf8(DOMAIN.person)).update(utf8(canonicalize(account))).digest();
+    return `p_${base32Lower(digest).slice(0, 26)}`;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * A directory realm (spec §15.8): what a daemon home pins of its key directory, and the realm id that follows
+ * from it. The id commits to the directory's origin, the Jelly issuer that vouches for its persons and the epoch
+ * key that signs its tree heads, so two directories never share a realm and a client can tell which one an
+ * envelope belongs to.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { parseWith } from "../check.js";
+import { sha256 } from "../hash.js";
+import { canonicalize } from "../jcs.js";
+import { assertEd25519PublicKey } from "../keys.js";
+import { Key32, RelayUrl } from "../schema/common.js";
+import { MessagingError } from "../schema/errors.js";
+/** The Jelly ID issuer, as its tokens write `iss`: an `https://` URL, or `http://` to a loopback host (tests). */
+const IssuerUrl = z.string().max(2048).refine(isIssuerUrl, "an https:// issuer, or http:// on a loopback host");
+/** What a daemon's `config.json` pins of a directory realm (design §1.1): its relay, issuer, resource and epoch key. */
+export const DirectoryRealmConfig = z.object({
+    kind: z.literal("directory"),
+    url: RelayUrl,
+    issuer: IssuerUrl,
+    /** The `aud` of the realm's Jelly tokens. */
+    resource: z.string().min(1).max(2048),
+    /** The directory's epoch key, Ed25519 `x`: the only key that may sign the first STH this home adopts. */
+    key: Key32,
+    /**
+     * Until Jelly contract v1.2: the domains whose verified emails make a person a member of org `domain:<d>`
+     * (design §2.3). A person whose email domain is not listed is an individual.
+     */
+    orgDomains: z.array(z.string().regex(/^(?:[a-z0-9-]+\.)+[a-z0-9-]+$/).max(253)).max(1000).optional(),
+});
+/**
+ * `base64url(SHA-256(JCS({kind: "directory", origin, issuer, key})))`, where `origin` is the WHATWG origin of the
+ * relay URL. Throws `invalid_request` for a config that does not parse or a key that is not a usable Ed25519 key.
+ */
+export function directoryRealmId(config) {
+    const parsed = parseWith(DirectoryRealmConfig.pick({ url: true, issuer: true, key: true }), { url: config.url, issuer: config.issuer, key: config.key }, "directory realm");
+    assertEd25519PublicKey(parsed.key, "directory epoch key");
+    const origin = new URL(parsed.url).origin;
+    if (origin === "null")
+        throw new MessagingError("invalid_request", "directory realm url has no origin");
+    return sha256(canonicalize({ kind: "directory", origin, issuer: parsed.issuer, key: parsed.key }));
+}
+function loopback(host) {
+    return host === "localhost" || host === "[::1]" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+function parse(text) {
+    try {
+        return new URL(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isIssuerUrl(text) {
+    const url = parse(text);
+    if (!url || url.username !== "" || url.password !== "" || url.search !== "" || url.hash !== "")
+        return false;
+    return url.protocol === "https:" || (url.protocol === "http:" && loopback(url.hostname));
+}

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

@@ -0,0 +1,266 @@
+/**
+ * The directory's map (spec §15.5): a sparse Merkle tree of depth 256 from `SHA-256(UTF-8(PersonId))` to a
+ * 32-byte value, with fixed empty-subtree hashes and compact proofs (a 256-bit bitmap of the non-empty
+ * siblings and those siblings, bottom up). Every key's path has all 256 levels: there is no shortcut leaf in
+ * the hashes, so a proof is checked by 256 hashes. In memory the tree is a compressed trie that keeps hashes
+ * only where paths branch, so memory grows with the persons, not with 256 nodes each.
+ */
+import { createHash } from "node:crypto";
+import { b64u, utf8 } from "../b64u.js";
+import { parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { DOMAIN } from "../schema/common.js";
+import { MapValue } from "../schema/directory.js";
+import { MessagingError } from "../schema/errors.js";
+export const MAP_DEPTH = 256;
+function digest(...parts) {
+    const hash = createHash("sha256");
+    for (const part of parts)
+        hash.update(part);
+    return new Uint8Array(hash.digest());
+}
+/** E[0] = H(0x02); E[h+1] = H(0x01 ‖ E[h] ‖ E[h]). */
+const EMPTY = [digest(Uint8Array.of(0x02))];
+for (let h = 0; h < MAP_DEPTH; h++)
+    EMPTY.push(digest(Uint8Array.of(0x01), EMPTY[h], EMPTY[h]));
+/** The hash of an empty subtree of height `h` (0 ≤ h ≤ 256), base64url. */
+export function emptyMapHash(height) {
+    const hash = EMPTY[height];
+    if (!hash)
+        throw new MessagingError("invalid_request", "map height out of range");
+    return b64u.encode(hash);
+}
+/** The map key of a person: `SHA-256(UTF-8(person))`, base64url. */
+export function mapKey(person) {
+    return b64u.encode(digest(utf8(person)));
+}
+/**
+ * The value a live person's leaf holds: `SHA-256(JCS({log: {seq, hash}, keys}))`, where `log` is the head of
+ * their device log and `keys` the hashes of the current devices' keys statements, ordered by device.
+ */
+export function mapValue(value) {
+    const parsed = parseWith(MapValue, value, "map value");
+    return b64u.encode(digest(utf8(canonicalize(parsed))));
+}
+/** The value an erased person's leaf holds: `SHA-256(UTF-8("messaging/1/tombstone"))`. */
+export const TOMBSTONE = b64u.encode(digest(utf8(DOMAIN.tombstone)));
+/** Bit `index` of a key, from the most significant bit of its first byte. */
+function bit(key, index) {
+    return (key[index >> 3] >> (7 - (index & 7))) & 1;
+}
+function leafHash(key, value) {
+    return digest(Uint8Array.of(0x00), key, value);
+}
+function node(left, right) {
+    return digest(Uint8Array.of(0x01), left, right);
+}
+function decode32(hash, what) {
+    let bytes;
+    try {
+        bytes = b64u.decode(hash);
+    }
+    catch {
+        throw new MessagingError("invalid_request", `${what} must be 32 bytes of base64url`);
+    }
+    if (bytes.length !== 32)
+        throw new MessagingError("invalid_request", `${what} must be 32 bytes of base64url`);
+    return bytes;
+}
+function bottomOf(n) {
+    return n.kind === "leaf" ? MAP_DEPTH : n.bottom;
+}
+/** The subtree hash of `n` at depth `depth` (top ≤ depth ≤ bottom): its bottom hash, hashed up past empty siblings. */
+function hashAt(n, depth) {
+    let hash = n.kind === "leaf" ? leafHash(n.key, n.value) : node(n.children[0].hash, n.children[1].hash);
+    for (let d = bottomOf(n); d > depth; d--) {
+        const empty = EMPTY[MAP_DEPTH - d];
+        hash = bit(n.key, d - 1) === 0 ? node(hash, empty) : node(empty, hash);
+    }
+    return hash;
+}
+function leaf(top, key, value) {
+    const n = { kind: "leaf", top, key, value, hash: EMPTY[0] };
+    n.hash = hashAt(n, top);
+    return n;
+}
+function branch(top, bottom, children) {
+    const n = { kind: "branch", top, bottom, key: children[0].key, children, hash: EMPTY[0] };
+    n.hash = hashAt(n, top);
+    return n;
+}
+/** The first bit in [from, to) where `a` and `b` differ, or `to`. */
+function firstDifference(a, b, from, to) {
+    for (let i = from; i < to; i++)
+        if (bit(a, i) !== bit(b, i))
+            return i;
+    return to;
+}
+/** The trie over sorted leaves [from, to), hanging at depth `top`. */
+function build(leaves, top, from, to) {
+    if (to - from === 1)
+        return leaf(top, leaves[from].key, leaves[from].value);
+    // Sorted keys share every bit before the first difference of the first and the last.
+    const bottom = firstDifference(leaves[from].key, leaves[to - 1].key, top, MAP_DEPTH);
+    let mid = from;
+    while (bit(leaves[mid].key, bottom) === 0)
+        mid++;
+    return branch(top, bottom, [build(leaves, bottom + 1, from, mid), build(leaves, bottom + 1, mid, to)]);
+}
+/**
+ * The map, in memory. `set` costs about 256 hashes plus the branches above the person; `prove` reads siblings
+ * from the trie. A person never leaves the map: an erased person's value becomes `TOMBSTONE`.
+ */
+export class SparseMerkleTree {
+    #root;
+    #values = new Map();
+    #frozen = false;
+    /**
+     * A map of these persons and values, built at once: each leaf's path is hashed once. This is the way to load
+     * a large map (about 2.4 million hashes for 10,000 persons). A person given twice keeps the last value.
+     */
+    static from(entries) {
+        const tree = new SparseMerkleTree();
+        const leaves = new Map();
+        for (const [person, value] of entries) {
+            const key = digest(utf8(person));
+            const id = b64u.encode(key);
+            leaves.set(id, { key, value: decode32(value, "map value") });
+            tree.#values.set(id, value);
+        }
+        const sorted = [...leaves.values()].sort((a, b) => Buffer.compare(a.key, b.key));
+        tree.#root = sorted.length === 0 ? undefined : build(sorted, 0, 0, sorted.length);
+        return tree;
+    }
+    get size() {
+        return this.#values.size;
+    }
+    root() {
+        return b64u.encode(this.#root?.hash ?? EMPTY[MAP_DEPTH]);
+    }
+    get(person) {
+        if (this.#frozen)
+            throw new MessagingError("internal", "a map snapshot answers root and prove only");
+        return this.#values.get(mapKey(person));
+    }
+    /** Sets a person's value (from `mapValue`, or `TOMBSTONE`). */
+    set(person, value) {
+        if (this.#frozen)
+            throw new MessagingError("internal", "a map snapshot does not change");
+        const key = digest(utf8(person));
+        const bytes = decode32(value, "map value");
+        this.#values.set(b64u.encode(key), value);
+        this.#root = this.#root ? insert(this.#root, key, bytes) : leaf(0, key, bytes);
+    }
+    /**
+     * The map as it is now, for `root` and `prove` only: a later `set` on this tree does not change it. Cheap: the trie
+     * is persistent, so the snapshot shares every node.
+     */
+    snapshot() {
+        const frozen = new SparseMerkleTree();
+        frozen.#root = this.#root;
+        frozen.#frozen = true;
+        return frozen;
+    }
+    /**
+     * A tree that starts as this one and changes on its own: a `set` on either leaves the other as it was. The trie is
+     * shared (it is persistent); only the person index is copied. A directory prepares an epoch on a copy and adopts it
+     * once the epoch is stored.
+     */
+    copy() {
+        if (this.#frozen)
+            throw new MessagingError("internal", "a map snapshot answers root and prove only");
+        const copy = new SparseMerkleTree();
+        copy.#root = this.#root;
+        copy.#values = new Map(this.#values);
+        return copy;
+    }
+    /** The proof for `person`, present or absent, against `root()`. */
+    prove(person) {
+        const key = digest(utf8(person));
+        const found = [];
+        let current = this.#root;
+        while (current) {
+            const bottom = bottomOf(current);
+            const differs = firstDifference(key, current.key, current.top, bottom);
+            if (differs < bottom) {
+                // Absent: all of `current` below the divergence is the one non-empty sibling there.
+                found.push([MAP_DEPTH - differs - 1, hashAt(current, differs + 1)]);
+                break;
+            }
+            if (current.kind === "leaf")
+                break;
+            const side = bit(key, current.bottom);
+            found.push([MAP_DEPTH - current.bottom - 1, current.children[1 - side].hash]);
+            current = current.children[side];
+        }
+        found.sort((a, b) => a[0] - b[0]);
+        const bitmap = new Uint8Array(32);
+        for (const [height] of found)
+            bitmap[height >> 3] |= 0x80 >> (height & 7);
+        return { bitmap: b64u.encode(bitmap), siblings: found.map(([, hash]) => b64u.encode(hash)) };
+    }
+}
+/**
+ * `n` with `key` set to `value`. Persistent: it copies every node on the path and changes none, so a tree's earlier
+ * root still proves the map as it was (`SparseMerkleTree.snapshot`).
+ */
+function insert(n, key, value) {
+    const bottom = bottomOf(n);
+    const differs = firstDifference(key, n.key, n.top, bottom);
+    if (differs < bottom) {
+        // Split: a branch at the first differing depth, over the old subtree (now hanging lower) and a new leaf.
+        const lowered = { ...n, top: differs + 1 };
+        lowered.hash = hashAt(lowered, lowered.top);
+        const fresh = leaf(differs + 1, key, value);
+        return branch(n.top, differs, bit(key, differs) === 0 ? [fresh, lowered] : [lowered, fresh]);
+    }
+    let copy;
+    if (n.kind === "leaf") {
+        copy = { ...n, value };
+    }
+    else {
+        const side = bit(key, n.bottom);
+        const children = [n.children[0], n.children[1]];
+        children[side] = insert(n.children[side], key, value);
+        copy = { ...n, children };
+    }
+    copy.hash = hashAt(copy, copy.top);
+    return copy;
+}
+/**
+ * The root that `proof` gives for `person` holding `value` (undefined: no leaf, an absent person). Throws
+ * `invalid_request` for a malformed proof: a bitmap that is not 32 bytes, a sibling count that differs from
+ * the bitmap's, or a sibling equal to the empty hash of its height (a proof names only non-empty siblings).
+ */
+export function mapRootFromProof(person, value, proof) {
+    const key = digest(utf8(person));
+    const bitmap = decode32(proof.bitmap, "map proof bitmap");
+    if (!Array.isArray(proof.siblings))
+        throw new MessagingError("invalid_request", "map proof siblings must be an array");
+    let next = 0;
+    let hash = value === undefined ? EMPTY[0] : leafHash(key, decode32(value, "map value"));
+    for (let height = 0; height < MAP_DEPTH; height++) {
+        let sibling = EMPTY[height];
+        if ((bitmap[height >> 3] >> (7 - (height & 7))) & 1) {
+            const given = proof.siblings[next++];
+            if (given === undefined)
+                throw new MessagingError("invalid_request", "map proof has fewer siblings than its bitmap");
+            sibling = decode32(given, "map proof sibling");
+            if (Buffer.from(sibling).equals(EMPTY[height]))
+                throw new MessagingError("invalid_request", "map proof names an empty sibling");
+        }
+        hash = bit(key, MAP_DEPTH - 1 - height) === 0 ? node(hash, sibling) : node(sibling, hash);
+    }
+    if (next !== proof.siblings.length)
+        throw new MessagingError("invalid_request", "map proof has more siblings than its bitmap");
+    return b64u.encode(hash);
+}
+/** True when `proof` shows `person` holding `value` (undefined: absent) in the map with root `root`. Never throws. */
+export function verifyMapProof(root, person, value, proof) {
+    try {
+        return mapRootFromProof(person, value, proof) === root;
+    }
+    catch {
+        return false;
+    }
+}