@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/lib/modules/core/conversation/ratchet.js

@@ -0,0 +1,243 @@
+/**
+ * Sender keys (spec §16.5). Each sender device keeps one chain per (conversation, epoch):
+ *
+ *   mk_i     = HKDF-SHA256(ikm = ck_i, salt = empty, info = DOMAIN.convMsg,   32 bytes)
+ *   ck_{i+1} = HKDF-SHA256(ikm = ck_i, salt = empty, info = DOMAIN.convChain, 32 bytes)
+ *
+ * A rotation starts a fresh random chain key at the next index of the same epoch, so `(epoch, device, idx)` names a
+ * message's key whatever the rotations: the share with the greatest `idx` at or below a message's `idx` derives it.
+ * Pure: no clock, no I/O; times are passed in.
+ */
+import { hkdfSync, randomBytes } from "node:crypto";
+import { z } from "../../vendor/zod/index.js";
+import { b64u } from "../b64u.js";
+import { parseWith } from "../check.js";
+import { DOMAIN, Key32, LIMITS, MachineId as MachineIdSchema, Millis } from "../schema/common.js";
+import { KeyShare as KeyShareSchema } from "../schema/conversation.js";
+import { MessagingError } from "../schema/errors.js";
+const EMPTY = new Uint8Array(0);
+function hkdf(ck, info) {
+    return new Uint8Array(hkdfSync("sha256", ck, EMPTY, info, 32));
+}
+/** One ratchet step: the message key for this index and the chain key for the next. */
+export function chainStep(ck) {
+    if (ck.length !== 32)
+        throw new MessagingError("invalid_request", "a chain key is 32 bytes");
+    return { mk: hkdf(ck, DOMAIN.convMsg), next: hkdf(ck, DOMAIN.convChain) };
+}
+const Index = z.number().int().min(0);
+/** A sender chain as a device stores it. */
+export const SenderChainState = z.strictObject({
+    epoch: Index,
+    device: MachineIdSchema,
+    start: Index,
+    origin: Key32,
+    idx: Index,
+    ck: Key32,
+    startedAt: Millis,
+});
+/** The sending side of one chain. `next()` hands out each message key once. */
+export class SenderChain {
+    epoch;
+    device;
+    /** The index this chain starts at. */
+    start;
+    startedAt;
+    #origin;
+    #ck;
+    #idx;
+    constructor(state) {
+        this.epoch = state.epoch;
+        this.device = state.device;
+        this.start = state.start;
+        this.startedAt = state.startedAt;
+        this.#origin = state.origin;
+        this.#ck = state.ck;
+        this.#idx = state.idx;
+    }
+    /** A new chain at `idx` (default 0) of `epoch`, from a fresh random chain key. */
+    static start(args) {
+        return SenderChain.#from(args, randomBytes(32));
+    }
+    /** `start` with a caller-chosen chain key: for test vectors, and for a device restoring its own state. */
+    static startWith(args, ck) {
+        return SenderChain.#from(args, ck);
+    }
+    static #from(args, ck) {
+        const epoch = parseWith(Index, args.epoch, "epoch");
+        const device = parseWith(MachineIdSchema, args.device, "device");
+        const start = parseWith(Index, args.idx ?? 0, "chain index");
+        const startedAt = parseWith(Millis, args.now, "now");
+        if (ck.length !== 32)
+            throw new MessagingError("invalid_request", "a chain key is 32 bytes");
+        const key = new Uint8Array(ck);
+        return new SenderChain({ epoch, device, start, origin: key, idx: start, ck: key, startedAt });
+    }
+    static restore(raw) {
+        const s = parseWith(SenderChainState, raw, "sender chain");
+        if (s.idx < s.start)
+            throw new MessagingError("invalid_request", "a sender chain cannot be behind its start");
+        return new SenderChain({ ...s, origin: b64u.decode(s.origin), ck: b64u.decode(s.ck) });
+    }
+    export() {
+        return { epoch: this.epoch, device: this.device, start: this.start, origin: b64u.encode(this.#origin), idx: this.#idx, ck: b64u.encode(this.#ck), startedAt: this.startedAt };
+    }
+    /** The index the next message gets. */
+    get idx() {
+        return this.#idx;
+    }
+    /** The share that lets a receiver open every message of this chain: its chain key at its start. */
+    share() {
+        return { epoch: this.epoch, device: this.device, idx: this.start, ck: b64u.encode(this.#origin) };
+    }
+    /** The key for the next message, and its index. The chain moves past it. */
+    next() {
+        const { mk, next } = chainStep(this.#ck);
+        const idx = this.#idx;
+        this.#ck = next;
+        this.#idx = idx + 1;
+        return { idx, mk };
+    }
+    /** True once the chain has sent `LIMITS.chainMessages` messages or is `LIMITS.chainMaxMs` old: rotate before the next. */
+    due(now) {
+        return this.#idx - this.start >= LIMITS.chainMessages || now - this.startedAt >= LIMITS.chainMaxMs;
+    }
+    /** A fresh chain in the same epoch, starting at this chain's next index. Share it before sending on it. */
+    rotate(now) {
+        return SenderChain.start({ epoch: this.epoch, device: this.device, idx: this.#idx, now });
+    }
+    /** `rotate` with a caller-chosen chain key, for test vectors. */
+    rotateWith(now, ck) {
+        return SenderChain.startWith({ epoch: this.epoch, device: this.device, idx: this.#idx, now }, ck);
+    }
+}
+const Segment = z.strictObject({
+    epoch: Index,
+    device: MachineIdSchema,
+    start: Index,
+    origin: Key32,
+    pos: Index,
+    ck: Key32,
+    skipped: z.array(z.tuple([Index, Key32])).max(LIMITS.skippedKeys),
+});
+export const ReceiverChainsState = z.strictObject({ chains: z.array(Segment).max(100_000) });
+/**
+ * The receiving side: every chain this device holds for one conversation, by (epoch, sender device). It derives
+ * forward only and hands out each message key once; a message that arrives out of order uses a key kept from an
+ * earlier derivation, at most `LIMITS.skippedKeys` per sender and epoch. The chain keys at each share's index are
+ * kept, so the device can share them with a late joiner (history `shared`).
+ */
+export class ReceiverChains {
+    #chains = new Map();
+    static restore(raw) {
+        const state = parseWith(ReceiverChainsState, raw, "receiver chains");
+        const chains = new ReceiverChains();
+        for (const s of state.chains) {
+            if (s.pos < s.start)
+                throw new MessagingError("invalid_request", "a receiver chain cannot be behind its start");
+            const list = chains.#list(s.epoch, s.device);
+            if (list.some((seg) => seg.start === s.start))
+                throw new MessagingError("invalid_request", "duplicate receiver chain");
+            list.push({ start: s.start, origin: b64u.decode(s.origin), pos: s.pos, ck: b64u.decode(s.ck), skipped: new Map(s.skipped.map(([i, k]) => [i, b64u.decode(k)])) });
+            list.sort((a, b) => a.start - b.start);
+        }
+        return chains;
+    }
+    export() {
+        const chains = [];
+        for (const [key, list] of [...this.#chains].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+            const [epoch, device] = key.split(" ");
+            for (const s of list) {
+                chains.push({
+                    epoch: Number(epoch),
+                    device,
+                    start: s.start,
+                    origin: b64u.encode(s.origin),
+                    pos: s.pos,
+                    ck: b64u.encode(s.ck),
+                    skipped: [...s.skipped].sort(([a], [b]) => a - b).map(([i, k]) => [i, b64u.encode(k)]),
+                });
+            }
+        }
+        return { chains };
+    }
+    #list(epoch, device) {
+        const key = `${epoch} ${device}`;
+        let list = this.#chains.get(key);
+        if (!list) {
+            list = [];
+            this.#chains.set(key, list);
+        }
+        return list;
+    }
+    /**
+     * Adds a share. The first share at a given (epoch, device, idx) wins: a later one with another key changes
+     * nothing, and `add` returns false. Returns true when the share was new.
+     */
+    add(raw) {
+        const share = parseWith(KeyShareSchema, raw, "key share");
+        const list = this.#list(share.epoch, share.device);
+        if (list.some((s) => s.start === share.idx))
+            return false;
+        const ck = b64u.decode(share.ck);
+        list.push({ start: share.idx, origin: ck, pos: share.idx, ck, skipped: new Map() });
+        list.sort((a, b) => a.start - b.start);
+        return true;
+    }
+    /** Every share this device holds, from each chain's start: what it shares with a late joiner. */
+    shares() {
+        const out = [];
+        for (const s of this.export().chains)
+            out.push({ epoch: s.epoch, device: s.device, idx: s.start, ck: s.origin });
+        return out;
+    }
+    /**
+     * The message key for (`epoch`, `device`, `idx`), used once. `not_found` when no share covers it, or its key was
+     * already used or dropped; `too_large` when it is more than `LIMITS.skippedKeys` past the chain's position.
+     */
+    messageKey(epoch, device, idx) {
+        const list = this.#chains.get(`${epoch} ${device}`) ?? [];
+        let at = -1;
+        for (let i = 0; i < list.length; i++)
+            if (list[i].start <= idx)
+                at = i;
+        if (at < 0)
+            throw new MessagingError("not_found", "no key share covers this message");
+        // `at` is the last chain starting at or below `idx`, so the next one (a rotation) starts past it.
+        const seg = list[at];
+        if (idx < seg.pos) {
+            const mk = seg.skipped.get(idx);
+            if (!mk)
+                throw new MessagingError("not_found", "this message key was already used or dropped");
+            seg.skipped.delete(idx);
+            return mk;
+        }
+        if (idx - seg.pos > LIMITS.skippedKeys)
+            throw new MessagingError("too_large", "message index is too far past the chain");
+        let ck = seg.ck;
+        for (let i = seg.pos; i < idx; i++) {
+            const step = chainStep(ck);
+            seg.skipped.set(i, step.mk);
+            ck = step.next;
+        }
+        const { mk, next } = chainStep(ck);
+        seg.ck = next;
+        seg.pos = idx + 1;
+        this.#bound(list);
+        return mk;
+    }
+    /** Keeps at most `LIMITS.skippedKeys` skipped keys per (epoch, device), dropping the lowest indexes first. */
+    #bound(list) {
+        let total = list.reduce((n, s) => n + s.skipped.size, 0);
+        for (const seg of list) {
+            if (total <= LIMITS.skippedKeys)
+                return;
+            for (const i of [...seg.skipped.keys()].sort((a, b) => a - b)) {
+                if (total <= LIMITS.skippedKeys)
+                    return;
+                seg.skipped.delete(i);
+                total--;
+            }
+        }
+    }
+}

package/dist/lib/modules/core/conversation/seal.js

@@ -0,0 +1,198 @@
+/**
+ * Sealing in conversations (spec §16.5, §16.6):
+ *
+ * - a `msg` body: base64url(nonce ‖ AES-256-GCM(mk, nonce, JCS(MsgBody), aad = JCS(header)) ‖ tag), with a fresh
+ *   12-byte nonce, under the author's message key for (`epoch`, `idx`);
+ * - `create.sealedMeta`: the same, of JCS(ConvMeta) under the creator's epoch-0 message key 0, with the create
+ *   event's header as AAD;
+ * - a `keys` share: JCS({shares}) sealed to one recipient device under the envelope seal (spec §5, "Sealing": X25519
+ *   with a fresh ephemeral key, HKDF-SHA256 with salt epk ‖ recipient enc and info DOMAIN.seal, AES-256-GCM), with
+ *   aad = JCS({header, to}).
+ */
+import { createCipheriv, createDecipheriv, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from "node:crypto";
+import { b64u, utf8 } from "../b64u.js";
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { privateKeyFromRaw, publicKeyFromRaw, rawPublicKey } from "../keys.js";
+import { DOMAIN, LIMITS } from "../schema/common.js";
+import { ConvMeta, KeySharePayload, MsgBody, } from "../schema/conversation.js";
+import { MessagingError } from "../schema/errors.js";
+import { parseWire } from "../wire.js";
+import { convEventHeader, signConvEvent } from "./event.js";
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+function aad(header) {
+    return utf8(canonicalize(header));
+}
+function aesSeal(key, nonce, plaintext, additional) {
+    if (nonce.length !== NONCE_BYTES)
+        throw new MessagingError("invalid_request", "a nonce is 12 bytes");
+    const cipher = createCipheriv("aes-256-gcm", key, nonce, { authTagLength: TAG_BYTES });
+    cipher.setAAD(additional);
+    return Buffer.concat([nonce, cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+function aesOpen(key, sealed, additional, maxPlaintext) {
+    let data;
+    try {
+        data = b64u.decode(sealed);
+    }
+    catch {
+        throw new MessagingError("bad_signature", "sealed body is not base64url");
+    }
+    if (data.length - NONCE_BYTES - TAG_BYTES > maxPlaintext)
+        throw new MessagingError("too_large", "sealed body is too large");
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, data.subarray(0, NONCE_BYTES), { authTagLength: TAG_BYTES });
+        decipher.setAAD(additional);
+        decipher.setAuthTag(data.subarray(data.length - TAG_BYTES));
+        return Buffer.concat([decipher.update(data.subarray(NONCE_BYTES, data.length - TAG_BYTES)), decipher.final()]);
+    }
+    catch {
+        throw new MessagingError("bad_signature", "sealed body failed to open");
+    }
+}
+/** Decodes UTF-8 strictly and parses with `parseWire`. */
+function wireJson(bytes) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new MessagingError("invalid_request", "sealed body is not UTF-8");
+    }
+    return parseWire(text);
+}
+function plaintextOf(body) {
+    parseWith(MsgBody, body, "message body");
+    const bytes = utf8(canonicalize(body));
+    if (bytes.length > LIMITS.convPlaintextBytes)
+        throw new MessagingError("too_large", "message body is over LIMITS.convPlaintextBytes");
+    return bytes;
+}
+/** Seals `body` under `mk` as the body of `unsealed` and signs the event. Throws only MessagingError. */
+export function sealConvMsg(identity, unsealed, body, mk) {
+    return sealConvMsgWith(identity, unsealed, body, mk, randomBytes(NONCE_BYTES));
+}
+/** `sealConvMsg` with a caller-chosen nonce: for test vectors only (`@messaging/core/testing`). */
+export function sealConvMsgWith(identity, unsealed, body, mk, nonce) {
+    try {
+        const header = convEventHeader({ ...unsealed, class: "msg" });
+        const sealed = b64u.encode(aesSeal(mk, nonce, plaintextOf(body), aad(header)));
+        return signConvEvent(identity, { ...header, body: sealed });
+    }
+    catch (error) {
+        throw asMessagingError(error, "conversation message");
+    }
+}
+/**
+ * Opens a `msg` event's body with its message key: `bad_signature` when it fails to open, `too_large` over
+ * `LIMITS.convPlaintextBytes`, `invalid_request` when the plaintext is not a `MsgBody` (parsed with `parseWire`).
+ * The caller has verified the event's signature.
+ */
+export function openConvMsg(event, mk) {
+    try {
+        if (mk.length !== 32)
+            throw new MessagingError("invalid_request", "a message key is 32 bytes");
+        const bytes = aesOpen(mk, event.body, aad(convEventHeader(event)), LIMITS.convPlaintextBytes);
+        return parseWith(MsgBody, wireJson(bytes), "message body");
+    }
+    catch (error) {
+        throw asMessagingError(error, "conversation message");
+    }
+}
+/** `create.sealedMeta`: JCS(meta) sealed under the creator's epoch-0 key 0, with the create event's header as AAD. */
+export function sealConvMeta(header, meta, mk0) {
+    return sealConvMetaWith(header, meta, mk0, randomBytes(NONCE_BYTES));
+}
+/** `sealConvMeta` with a caller-chosen nonce: for test vectors only. */
+export function sealConvMetaWith(header, meta, mk0, nonce) {
+    try {
+        const value = parseWith(ConvMeta, meta, "conversation meta");
+        return b64u.encode(aesSeal(mk0, nonce, utf8(canonicalize(value)), aad(convEventHeader(header))));
+    }
+    catch (error) {
+        throw asMessagingError(error, "conversation meta");
+    }
+}
+/** Opens a `create` event's `sealedMeta`. Errors as for `openConvMsg`; `not_found` when it has none. */
+export function openConvMeta(event, mk0) {
+    try {
+        if (event.body.op !== "create" || event.body.sealedMeta === undefined)
+            throw new MessagingError("not_found", "the event carries no sealed meta");
+        const bytes = aesOpen(mk0, event.body.sealedMeta, aad(convEventHeader(event)), 2048);
+        return parseWith(ConvMeta, wireJson(bytes), "conversation meta");
+    }
+    catch (error) {
+        throw asMessagingError(error, "conversation meta");
+    }
+}
+function shareAad(header, to) {
+    return utf8(canonicalize({ header, to }));
+}
+function shareKey(shared, epk, recipientEnc) {
+    return new Uint8Array(hkdfSync("sha256", shared, Buffer.concat([epk, recipientEnc]), DOMAIN.seal, 32));
+}
+/**
+ * Seals `shares` to each recipient device as the body of `unsealed`, and signs the event. One sealed share per
+ * device; at most `LIMITS.keySharesPerEvent` devices and `LIMITS.keyShares` chain keys. Throws only MessagingError.
+ */
+export function sealKeyShares(identity, unsealed, recipients, shares) {
+    return sealShares(identity, unsealed, recipients, shares, () => {
+        const { privateKey } = generateKeyPairSync("x25519");
+        return { ephemeral: privateKey, nonce: randomBytes(NONCE_BYTES) };
+    });
+}
+/** `sealKeyShares` with fixed randomness per recipient, in order: for test vectors only. */
+export function sealKeySharesWith(identity, unsealed, recipients, shares, randomness) {
+    let i = 0;
+    return sealShares(identity, unsealed, recipients, shares, () => {
+        const r = randomness[i++];
+        if (!r)
+            throw new MessagingError("invalid_request", "one randomness per recipient");
+        return { ephemeral: privateKeyFromRaw("x25519", r.ephemeral), nonce: r.nonce };
+    });
+}
+function sealShares(identity, unsealed, recipients, shares, randomness) {
+    try {
+        const header = convEventHeader({ ...unsealed, class: "keys" });
+        const plaintext = utf8(canonicalize(parseWith(KeySharePayload, { shares }, "key shares")));
+        const sealed = recipients.map((recipient) => {
+            const to = { person: recipient.person, device: recipient.device };
+            const { ephemeral, nonce } = randomness();
+            const shared = diffieHellman({ privateKey: ephemeral, publicKey: publicKeyFromRaw("x25519", recipient.enc) });
+            const epk = rawPublicKey(ephemeral);
+            const key = shareKey(shared, b64u.decode(epk), b64u.decode(recipient.enc));
+            const data = aesSeal(key, nonce, plaintext, shareAad(header, to));
+            return { to, epk, nonce: b64u.encode(nonce), ct: b64u.encode(data.subarray(NONCE_BYTES)) };
+        });
+        return signConvEvent(identity, { ...header, body: { shares: sealed } });
+    }
+    catch (error) {
+        throw asMessagingError(error, "key shares");
+    }
+}
+/**
+ * Opens the share sealed to `identity`'s device in a `keys` event: `not_found` when there is none, `bad_signature`
+ * when it fails to open, `invalid_request` when the plaintext is not a share payload. The caller has verified the
+ * event's signature and applied it to the log.
+ */
+export function openKeyShares(event, identity) {
+    try {
+        const share = event.body.shares.find((s) => s.to.device === identity.machine);
+        if (!share)
+            throw new MessagingError("not_found", "no share for this device");
+        let key;
+        try {
+            const shared = diffieHellman({ privateKey: identity.encKey, publicKey: publicKeyFromRaw("x25519", share.epk) });
+            key = shareKey(shared, b64u.decode(share.epk), b64u.decode(identity.enc));
+        }
+        catch {
+            throw new MessagingError("bad_signature", "key share failed to open");
+        }
+        const bytes = aesOpen(key, share.nonce + share.ct, shareAad(convEventHeader(event), share.to), Number.MAX_SAFE_INTEGER);
+        return parseWith(KeySharePayload, wireJson(bytes), "key shares").shares;
+    }
+    catch (error) {
+        throw asMessagingError(error, "key shares");
+    }
+}

package/dist/lib/modules/core/delegation.js

@@ -0,0 +1,174 @@
+import { utf8 } from "./b64u.js";
+import { parseAddress } from "./address.js";
+import { asMessagingError, parseWith } from "./check.js";
+import { sha256 } from "./hash.js";
+import { canonicalize } from "./jcs.js";
+import { DOMAIN, LIMITS } from "./schema/common.js";
+import { DelegationChain, DelegationGrant } from "./schema/delegation.js";
+import { MessagingError } from "./schema/errors.js";
+import { sign, signingInput, verifyInput } from "./sign.js";
+/** SHA-256 of the JCS form of the full grant, including `sig`: the next grant's `parent`. */
+export function grantHash(grant) {
+    return sha256(canonicalize(grant));
+}
+/**
+ * Signs one grant with the machine key (spec §6.7): a root, or the next hop after `parent`. The new grant
+ * may narrow the parent's scope and maxDepth, never widen them, and expires no later than the parent.
+ * It does not check the chain as a whole; run `verifyChain` on the extended chain for that.
+ * Throws only MessagingError: `invalid_request` for bad arguments, `forbidden` for a widening, `expired`
+ * for a parent that has expired.
+ */
+export function createGrant(identity, args) {
+    try {
+        return grant(identity, args);
+    }
+    catch (error) {
+        throw asMessagingError(error, "delegation grant");
+    }
+}
+function grant(identity, args) {
+    const now = args.now ?? Date.now();
+    const ttl = args.ttlMs ?? LIMITS.ttlMs;
+    if (!Number.isSafeInteger(now))
+        throw new MessagingError("invalid_request", "now must be an integer");
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > LIMITS.ttlMs)
+        throw new MessagingError("invalid_request", "ttlMs out of range");
+    const raw = args.parent;
+    const parent = raw === undefined ? undefined : parseWith(DelegationGrant, raw, "parent grant");
+    if (parent !== undefined) {
+        if (parent.to !== args.from)
+            throw new MessagingError("invalid_request", "a grant extends the grant to its delegating session");
+    }
+    const maxDepth = args.maxDepth ?? parent?.maxDepth ?? LIMITS.delegationDepth;
+    const scope = args.scope ?? parent?.scope;
+    if (parent !== undefined) {
+        if (maxDepth > parent.maxDepth)
+            throw new MessagingError("forbidden", "maxDepth would widen the parent grant");
+        if (!narrows(scope, parent.scope))
+            throw new MessagingError("forbidden", "scope would widen the parent grant");
+    }
+    const exp = parent === undefined ? now + ttl : Math.min(now + ttl, parent.exp);
+    if (exp <= now)
+        throw new MessagingError("expired", "the parent grant has expired");
+    const unsigned = {
+        realm: args.realm,
+        task: args.task,
+        from: args.from,
+        to: args.to,
+        by: identity.machine,
+        ts: now,
+        exp,
+        maxDepth,
+        ...(scope !== undefined ? { scope: [...scope] } : {}),
+        ...(raw !== undefined ? { parent: grantHash(raw) } : {}),
+    };
+    parseWith(DelegationGrant.omit({ sig: true }), unsigned, "delegation grant");
+    return { ...unsigned, sig: sign(identity, DOMAIN.delegation, unsigned) };
+}
+/**
+ * Verifies a delegation chain for the hop it arrived on (spec §6.7), against the locally verified realm.
+ * Checks, in order, stopping at the first failure:
+ *
+ * 1. schema, I-JSON and 1…`LIMITS.delegationDepth` grants (`invalid_request`); JCS within
+ *    `LIMITS.delegationBytes` (`too_large`);
+ * 2. for each grant, root first: this realm (`invalid_request`); the time window, as for envelopes
+ *    (`expired`); `by` a current member whose person and label `from` names (`not_member`); the
+ *    signature over the raw grant (`bad_signature`); linkage, no `parent` on the root and `from = previous.to`,
+ *    `parent = grantHash(previous)` after it (`invalid_request`); narrowing of scope, maxDepth and exp
+ *    (`forbidden`);
+ * 3. at most the smallest maxDepth grants (`forbidden`);
+ * 4. no session twice (`forbidden`);
+ * 5. the last grant is for this hop (`forbidden`).
+ *
+ * Throws only MessagingError, and never quotes the chain.
+ */
+export function verifyChain(raw, ctx) {
+    try {
+        return check(raw, ctx);
+    }
+    catch (error) {
+        throw asMessagingError(error, "delegation chain");
+    }
+}
+function check(raw, ctx) {
+    const { realm, now, hop } = ctx;
+    if (!Number.isSafeInteger(now))
+        throw new MessagingError("invalid_request", "now must be an integer");
+    parseWith(DelegationChain, raw, "delegation chain");
+    // The raw value, so unknown fields stay covered; canonicalizing it also requires I-JSON.
+    const grants = raw;
+    if (utf8(canonicalize(grants)).length > LIMITS.delegationBytes)
+        throw new MessagingError("too_large", `a delegation chain is limited to ${LIMITS.delegationBytes} bytes`);
+    let maxDepth = LIMITS.delegationDepth;
+    let previous;
+    for (const grant of grants) {
+        const { sig, ...unsigned } = grant;
+        const input = signingInput(DOMAIN.delegation, unsigned);
+        if (grant.realm !== realm.realm)
+            throw new MessagingError("invalid_request", "a grant is for another realm");
+        if (grant.ts > grant.exp)
+            throw new MessagingError("expired", "a grant's ts is after its exp");
+        if (grant.ts > now + LIMITS.clockSkewMs)
+            throw new MessagingError("expired", "a grant's timestamp is in the future");
+        if (grant.exp <= now)
+            throw new MessagingError("expired", "a grant has expired");
+        if (grant.exp - grant.ts > LIMITS.ttlMs)
+            throw new MessagingError("expired", "a grant's lifetime exceeds the maximum");
+        const signer = realm.device(grant.by);
+        if (!signer)
+            throw new MessagingError("not_member", "a grant's signer is not a current member");
+        const from = parseAddress(grant.from);
+        if (signer.person !== from.person || signer.label !== from.label) {
+            throw new MessagingError("not_member", "a grant's from does not name its signer");
+        }
+        if (!verifyInput(grant.by, input, sig))
+            throw new MessagingError("bad_signature", "a grant signature is invalid");
+        if (previous === undefined) {
+            if (grant.parent !== undefined)
+                throw new MessagingError("invalid_request", "a root grant has no parent");
+        }
+        else {
+            if (grant.from !== previous.to)
+                throw new MessagingError("invalid_request", "a grant does not extend the previous grant's recipient");
+            if (grant.parent !== grantHash(previous))
+                throw new MessagingError("invalid_request", "a grant's parent is not the previous grant");
+            if (!narrows(grant.scope, previous.scope))
+                throw new MessagingError("forbidden", "a grant widens the previous grant's scope");
+            if (grant.maxDepth > previous.maxDepth)
+                throw new MessagingError("forbidden", "a grant raises the previous grant's maxDepth");
+            if (grant.exp > previous.exp)
+                throw new MessagingError("forbidden", "a grant outlives the previous grant");
+        }
+        maxDepth = Math.min(maxDepth, grant.maxDepth);
+        previous = grant;
+    }
+    if (grants.length > maxDepth)
+        throw new MessagingError("forbidden", "the chain is deeper than its maxDepth allows");
+    const root = grants[0];
+    const last = grants[grants.length - 1];
+    const addresses = [root.from, ...grants.map((grant) => grant.to)];
+    if (new Set(addresses).size !== addresses.length)
+        throw new MessagingError("forbidden", "a session appears twice in the chain");
+    if (last.by !== hop.by || last.from !== hop.from || last.to !== hop.to || last.task !== hop.task) {
+        throw new MessagingError("forbidden", "the chain does not authorize this request");
+    }
+    return {
+        grants: structuredClone(grants),
+        summary: {
+            addresses,
+            depth: grants.length,
+            maxDepth,
+            ...(last.scope !== undefined ? { scope: [...last.scope] } : {}),
+            exp: Math.min(...grants.map((grant) => grant.exp)),
+        },
+    };
+}
+/** Whether `child` names nothing `parent` does not. An absent scope is unrestricted. */
+function narrows(child, parent) {
+    if (parent === undefined)
+        return true;
+    if (child === undefined)
+        return false;
+    const allowed = new Set(parent);
+    return child.every((label) => allowed.has(label));
+}