@joe-broadhead/messaging 0.7.0 → 0.8.0

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

@@ -0,0 +1,988 @@
+/**
+ * The conversation log as a pure reducer (spec §16.7). `ConvLog.apply` checks one relay-sequenced entry against the
+ * state of every earlier one, the chain, the signature and the authority rules, and appends it; a failed `apply`
+ * changes nothing. Membership, roles, epochs, settings, seats and the agent-context policy are a function of the
+ * log: `at(seq)` gives them at every position, and every member with the same prefix computes the same.
+ *
+ * Message rules (edit, delete, react, ...) need the sealed body: a member passes the opened body with the entry.
+ * Without it (the relay, or a device without the key) the header rules still run.
+ */
+import { z } from "../../vendor/zod/index.js";
+import { b64u } from "../b64u.js";
+import { asMessagingError, parseWith } from "../check.js";
+import { canonicalize } from "../jcs.js";
+import { Hash as HashSchema, LIMITS } from "../schema/common.js";
+import { ConvExpiredEntry as ExpiredSchema, ConvHead as ConvHeadSchema, ConvId as ConvIdSchema, MsgBody as MsgBodySchema, } from "../schema/conversation.js";
+import { MessagingError } from "../schema/errors.js";
+import { RealmId as RealmIdSchema } from "../schema/realm.js";
+import { admitConvEvent, convEntryHash, convEventSigned, convGenesisHash, convLinkHash, deepFreeze } from "./event.js";
+import { dmConvId, participantAgent, participantOf, participantPerson, selfConvId } from "./ids.js";
+import { verifyGuestInvitation } from "./guest-invitation.js";
+import { checkRequestEvent, requestLogState } from "./request-log.js";
+import { RequestImport } from "../schema/contact-request.js";
+const STRICTNESS = { none: 0, seats: 1, members: 2 };
+const BRIDGE_STRICTNESS = { none: 0, admins: 1, members: 2 };
+const isAdminRole = (role) => role === "owner" || role === "admin";
+const fail = (code, message) => {
+    throw new MessagingError(code, message);
+};
+function draftOf(s) {
+    return {
+        ...s,
+        participants: new Map(s.participants.map((p) => [p.p, { ...p }])),
+        votes: new Map(s.votes.map(({ person, ...vote }) => [person, vote])),
+        rekeyDue: new Set(s.rekeyDue),
+    };
+}
+function freezeDraft(d) {
+    const participants = [...d.participants.values()].sort((a, b) => (a.p < b.p ? -1 : a.p > b.p ? 1 : 0));
+    const persons = new Set(participants.map((p) => p.person));
+    for (const person of [...d.votes.keys()])
+        if (!persons.has(person))
+            d.votes.delete(person);
+    const votes = [...d.votes].sort(([a], [b]) => (a < b ? -1 : 1)).map(([person, vote]) => ({ person, ...vote }));
+    const voted = d.kind === "dm" || d.kind === "group";
+    const agentContext = voted
+        ? votes.reduce((min, v) => (v.agentContext !== undefined && STRICTNESS[v.agentContext] < STRICTNESS[min] ? v.agentContext : min), "members")
+        : d.agentContext;
+    const bridges = voted
+        ? [...persons].reduce((min, person) => {
+            const vote = d.votes.get(person)?.bridges ?? "none";
+            return BRIDGE_STRICTNESS[vote] < BRIDGE_STRICTNESS[min] ? vote : min;
+        }, "members")
+        : d.bridges;
+    const snapshot = { ...d, participants, votes, agentContext, bridges, rekeyDue: [...d.rekeyDue].sort() };
+    if (snapshot.visibility === undefined)
+        delete snapshot.visibility;
+    if (snapshot.org === undefined)
+        delete snapshot.org;
+    return deepFreeze(snapshot);
+}
+function participantFrom(seat, state, since) {
+    const person = participantPerson(seat.p);
+    const agent = participantAgent(seat.p);
+    const record = { p: seat.p, person, role: seat.role, state, since };
+    if (agent !== undefined)
+        record.agent = agent;
+    if (seat.device !== undefined)
+        record.device = seat.device;
+    if (seat.respondTo !== undefined)
+        record.respondTo = seat.respondTo;
+    return record;
+}
+/**
+ * A verified conversation log. Every method throws only MessagingError. Entries are kept as frozen copies of the
+ * received JSON, so hashes cover exactly what was received.
+ */
+export class ConvLog {
+    cid;
+    realm;
+    /** h(0), h(1), ...; an expired entry keeps its hash. */
+    #hashes;
+    #entries = [];
+    /** Opened bodies, when available, for a replay after a device cut. */
+    #bodies = new Map();
+    /** Authenticated chain links awaiting a current-device check in the member's verified realm. */
+    #held = new Set();
+    #ids = new Set();
+    /** A device's first authenticated revocation point in this conversation. */
+    #revoked = new Map();
+    /** seq of each op entry, ascending. */
+    #ops = [];
+    /** seqs of entries whose content expired: an op head must never name one. */
+    #expired = new Set();
+    #snapshots = [];
+    #messages = new Map();
+    #pinned = 0;
+    constructor(cid, realm) {
+        this.cid = cid;
+        this.realm = realm;
+        this.#hashes = [convGenesisHash(cid)];
+    }
+    /** An empty log of `cid` in `realm`: its head is {0, h(0)}. */
+    static open(cid, realm) {
+        try {
+            return new ConvLog(parseWith(ConvIdSchema, cid, "conversation id"), parseWith(RealmIdSchema, realm, "realm"));
+        }
+        catch (error) {
+            throw asMessagingError(error, "conversation log");
+        }
+    }
+    /** Replays a prefix; callers with a verified realm supply its removed-device check for every device rekey. */
+    static fromEntries(cid, realm, entries, checks = {}, onInvalidBody) {
+        return ConvLog.#replay(cid, realm, entries, undefined, checks, onInvalidBody);
+    }
+    /** Replays a complete prefix, retaining chain links for cut and expired entries. */
+    static #replay(cid, realm, entries, lastLive, checks = {}, onInvalidBody) {
+        const cuts = [];
+        // Later cuts can invalidate an earlier rekey too. Walk backwards so a cut rekey never cuts another device.
+        for (const { entry, held } of [...entries].reverse()) {
+            if (held)
+                continue; // An unresolved author cannot cut another device's state.
+            if (!entry || typeof entry !== "object" || !("event" in entry))
+                continue;
+            const outer = parseWith(EntryShape, entry, "conversation entry");
+            const event = admitConvEvent(outer.event);
+            if (event.class !== "op" || event.body.op !== "rekey" || event.body.cause !== "device" || event.body.until === undefined)
+                continue;
+            if (cuts.some((c) => event.by.device === c.device && outer.seq > c.until && outer.seq < c.rekey))
+                continue;
+            if (event.realm !== realm || event.cid !== cid || !convEventSigned(event))
+                fail("bad_signature", "invalid device rekey");
+            if (event.body.until >= outer.seq)
+                fail("invalid_request", "a device cut precedes its rekey");
+            cuts.push({ device: event.body.device, until: event.body.until, rekey: outer.seq });
+        }
+        const log = ConvLog.open(cid, realm);
+        for (let i = 0; i < entries.length; i++) {
+            const { entry, body, held } = entries[i];
+            if (entry && typeof entry === "object" && "digest" in entry && !("event" in entry)) {
+                log.applyExpired(entry);
+                continue;
+            }
+            const outer = parseWith(EntryShape, entry, "conversation entry");
+            const event = admitConvEvent(outer.event);
+            const cut = cuts.some((c) => event.by.device === c.device && outer.seq > c.until && outer.seq < c.rekey);
+            if (cut || held) {
+                log.#applyCut(outer);
+                if (held && !cut)
+                    log.#held.add(outer.seq);
+            }
+            else {
+                const live = i === entries.length - 1 && lastLive ? lastLive : checks;
+                try {
+                    log.#apply(entry, { ...(body === undefined ? {} : { body }), live });
+                }
+                catch (error) {
+                    if (!(error instanceof MessagingError) || !onInvalidBody || body === undefined || event.class !== "msg")
+                        throw error;
+                    // Retrying without the body distinguishes plaintext authority failures from structural failures.
+                    log.#apply(entry, { live });
+                    onInvalidBody(outer.seq);
+                }
+            }
+        }
+        return log;
+    }
+    /** Keeps a cut event's authenticated hash and op position, never its state or opened body. */
+    #applyCut(raw) {
+        const event = admitConvEvent(raw.event);
+        if (event.class === "keys" || event.realm !== this.realm || event.cid !== this.cid)
+            fail("invalid_request", "invalid cut entry");
+        const head = this.head();
+        if (raw.seq !== head.seq + 1 || raw.prev !== head.hash)
+            fail("conv_conflict", "cut entry does not extend the log");
+        if (!convEventSigned(event))
+            fail("bad_signature", "cut entry signature is invalid");
+        if (this.#ids.has(event.id))
+            fail("duplicate", "event id already used in this conversation");
+        if (this.#revoked.has(event.by.device))
+            fail("unknown_device", "the author's device was rekeyed out");
+        if (event.seen && event.seen.seq >= raw.seq)
+            fail("invalid_request", "seen names a position at or past the event");
+        if (event.class === "op")
+            this.#ops.push(raw.seq);
+        this.#ids.add(event.id);
+        this.#hashes.push(convEntryHash(raw.prev, event));
+        this.#entries.push(deepFreeze({ ...raw, event }));
+    }
+    #replace(other) {
+        this.#hashes.length = 0;
+        for (const v of other.#hashes)
+            this.#hashes.push(v);
+        this.#entries.length = 0;
+        for (const v of other.#entries)
+            this.#entries.push(v);
+        this.#ops.length = 0;
+        for (const v of other.#ops)
+            this.#ops.push(v);
+        this.#snapshots.length = 0;
+        for (const v of other.#snapshots)
+            this.#snapshots.push(v);
+        this.#expired.clear();
+        for (const v of other.#expired)
+            this.#expired.add(v);
+        this.#ids.clear();
+        for (const v of other.#ids)
+            this.#ids.add(v);
+        this.#revoked.clear();
+        for (const [k, v] of other.#revoked)
+            this.#revoked.set(k, v);
+        this.#messages.clear();
+        for (const [k, v] of other.#messages)
+            this.#messages.set(k, v);
+        this.#bodies.clear();
+        for (const [k, v] of other.#bodies)
+            this.#bodies.set(k, v);
+        this.#held.clear();
+        for (const seq of other.#held)
+            this.#held.add(seq);
+        this.#pinned = other.#pinned;
+    }
+    head() {
+        const seq = this.#hashes.length - 1;
+        return { seq, hash: this.#hashes[seq] };
+    }
+    /** The last op's seq and hash, or {0, h(0)}: what an author puts in `opHead`. */
+    opHead() {
+        const seq = this.#ops[this.#ops.length - 1] ?? 0;
+        return { seq, hash: this.#hashes[seq] };
+    }
+    /** h(seq), for 0 ≤ seq ≤ head. */
+    hashAt(seq) {
+        return Number.isSafeInteger(seq) && seq >= 0 ? this.#hashes[seq] : undefined;
+    }
+    entries() {
+        return [...this.#entries];
+    }
+    /** Held links are in the hash chain, but contribute neither state nor messages. */
+    held() { return [...this.#held]; }
+    /** The state at the head; undefined before `create`. */
+    state() {
+        return this.#snapshots[this.#snapshots.length - 1]?.snapshot;
+    }
+    /** The state after the entry at `seq`, as a log holding only entries 1..seq has it. */
+    at(seq) {
+        let found;
+        for (const s of this.#snapshots) {
+            if (s.seq > seq)
+                break;
+            found = s.snapshot;
+        }
+        return found;
+    }
+    /** What a member knows of the event `id`. */
+    message(id) {
+        const m = this.#messages.get(id);
+        return m && { ...m, reactions: m.reactions.map((r) => ({ key: r.key, by: [...r.by] })) };
+    }
+    /**
+     * Gossip (spec §16.4): `ahead` past the head (fetch up to it first); `consistent` when h(seq) is ours; `diverged`
+     * when this log has another hash at that seq, a fork whose evidence is the signed event that named it.
+     */
+    relate(head) {
+        try {
+            const seen = parseWith(ConvHeadSchema, head, "conversation head");
+            if (seen.seq > this.head().seq)
+                return { relation: "ahead" };
+            const ours = this.#hashes[seen.seq];
+            return ours === seen.hash ? { relation: "consistent" } : { relation: "diverged", ours };
+        }
+        catch (error) {
+            throw asMessagingError(error, "conversation head");
+        }
+    }
+    /**
+     * Checks one entry and appends it, in order: I-JSON and size (`invalid_request`, `too_large`); schema, realm and
+     * cid (`invalid_request`); the chain, seq = head + 1 and prev = h(head) (`conv_conflict`); the signature
+     * (`bad_signature`); the live checks given (`expired`, `unknown_device`); a reused id (`duplicate`); then the
+     * authority rules of spec §16.7. Returns the entry's h(seq).
+     */
+    apply(raw, options = {}) {
+        try {
+            const shape = EntryShape.safeParse(raw);
+            if (shape.success) {
+                const event = admitConvEvent(shape.data.event);
+                if (event.class === "op" && event.body.op === "rekey" && event.body.cause === "device" && event.body.until !== undefined) {
+                    const entries = this.#entries.map((entry) => ({ entry, held: this.#held.has(entry.seq), ...(this.#bodies.has(entry.seq) ? { body: this.#bodies.get(entry.seq) } : {}) }));
+                    entries.push({ entry: raw, ...(options.body === undefined ? {} : { body: options.body }) });
+                    const checks = { isRemovedDevice: options.live?.isRemovedDevice, requestBinding: options.live?.requestBinding };
+                    const rebuilt = ConvLog.#replay(this.cid, this.realm, entries, options.live, checks);
+                    this.#replace(rebuilt);
+                    return this.head().hash;
+                }
+            }
+            return this.#apply(raw, options);
+        }
+        catch (error) {
+            throw asMessagingError(error, "conversation entry");
+        }
+    }
+    /**
+     * Appends a `msg` entry whose content the relay expired (spec §16.4, "Retention"), by its digest: the chain stays
+     * verifiable and the state does not change. The create (seq 1) never expires (`invalid_request`), nor does any op:
+     * a later op head that names this seq fails.
+     */
+    applyExpired(raw) {
+        try {
+            const entry = parseWith(ExpiredSchema, raw, "expired entry");
+            const head = this.head();
+            if (entry.seq !== head.seq + 1 || entry.prev !== head.hash)
+                fail("conv_conflict", `entry does not extend head ${head.seq}`);
+            const hash = convLinkHash(entry.prev, b64u.decode(entry.digest));
+            this.#hashes.push(hash);
+            this.#entries.push(entry);
+            this.#expired.add(entry.seq);
+            return hash;
+        }
+        catch (error) {
+            throw asMessagingError(error, "expired entry");
+        }
+    }
+    /**
+     * Checks a key share against this log (spec §16.6); a share is not an entry, so nothing changes. In order: I-JSON,
+     * size and schema, realm and cid (`invalid_request`, `too_large`); the signature (`bad_signature`); the live checks
+     * given (`expired`, `unknown_device`); `by.agent` absent (`forbidden`); `opHead` names an op of this log
+     * (`conv_conflict`); then, in the state at `opHead`, the author's person is a member participant person
+     * (`not_member`) and the recipient's person a participant person (`forbidden`), and live, the recipient device is a
+     * current device of that person (`unknown_device`). Returns the frozen event.
+     */
+    checkShare(raw, live = {}) {
+        try {
+            const event = admitConvEvent(raw);
+            if (event.class !== "keys")
+                fail("invalid_request", "not a key share");
+            const share = event;
+            if (share.realm !== this.realm)
+                fail("invalid_request", "share is for another realm");
+            if (share.cid !== this.cid)
+                fail("invalid_request", "share is for another conversation");
+            if (!convEventSigned(share))
+                fail("bad_signature", "key share signature is invalid");
+            if (live.now !== undefined && Math.abs(share.ts - live.now) > (live.skewMs ?? LIMITS.clockSkewMs))
+                fail("expired", "share ts is outside the clock skew window");
+            if (live.isDevice && !live.isDevice(share.by.person, share.by.device))
+                fail("unknown_device", "the author device is not a current device of its person");
+            if (share.by.agent !== undefined)
+                fail("forbidden", "key shares are a device's: an agent never writes one");
+            this.#checkOpHead(share);
+            const revokedAt = this.#revoked.get(share.by.device);
+            if (revokedAt !== undefined && share.opHead.seq >= revokedAt)
+                fail("unknown_device", "the share author's device was rekeyed out");
+            const s = this.at(share.opHead.seq);
+            if (s === undefined)
+                fail("conv_conflict", "a share names an op of the conversation");
+            if (!s.participants.some((p) => p.person === share.by.person && p.state === "member"))
+                fail("not_member", "the author's person is not a participant");
+            const to = share.body.to;
+            if (!s.participants.some((p) => p.person === to.person && p.state === "member"))
+                fail("forbidden", "a share goes only to an accepted participant person");
+            if ((s.kind === "group" || s.history === "none") && s.rekeyDue.includes("added"))
+                fail("stale_epoch", "acceptance requires a rekey before sharing keys");
+            if (live.isDevice && !live.isDevice(to.person, to.device))
+                fail("unknown_device", "a share goes only to a current device");
+            return share;
+        }
+        catch (error) {
+            throw asMessagingError(error, "key share");
+        }
+    }
+    #apply(raw, options) {
+        const live = options.live ?? {};
+        canonicalize(raw);
+        const outer = parseWith(EntryShape, raw, "conversation entry");
+        const admitted = admitConvEvent(outer.event);
+        if (admitted.class === "keys")
+            fail("invalid_request", "a key share is not an entry of the log");
+        const event = admitted;
+        const entry = deepFreeze({ seq: outer.seq, prev: outer.prev, event });
+        if (event.realm !== this.realm)
+            fail("invalid_request", "event is for another realm");
+        if (event.cid !== this.cid)
+            fail("invalid_request", "event is for another conversation");
+        const head = this.head();
+        if (entry.seq !== head.seq + 1 || entry.prev !== head.hash)
+            fail("conv_conflict", `entry does not extend head ${head.seq}`);
+        if (!convEventSigned(event))
+            fail("bad_signature", "conversation event signature is invalid");
+        if (live.now !== undefined && Math.abs(event.ts - live.now) > (live.skewMs ?? LIMITS.clockSkewMs))
+            fail("expired", "event ts is outside the clock skew window");
+        if (live.isDevice && !live.isDevice(event.by.person, event.by.device))
+            fail("unknown_device", "the author device is not a current device of its person");
+        if (this.#ids.has(event.id))
+            fail("duplicate", "event id already used in this conversation");
+        if (this.#revoked.has(event.by.device))
+            fail("unknown_device", "the author's device was rekeyed out");
+        if (event.seen && event.seen.seq >= entry.seq)
+            fail("invalid_request", "seen names a position at or past the event");
+        if (live.requestBinding)
+            checkRequestEvent(this, outer.event, live.requestBinding, options.body);
+        // Keep our own parsed body: callers may mutate their input after apply, but a later cut must replay the
+        // originally accepted plaintext. Parse before committing so a failure cannot leave a partial append.
+        const imported = live.requestBinding && event.class === "msg" && event.request !== undefined;
+        const body = options.body === undefined || event.class !== "msg" ? undefined
+            : imported ? parseWith(RequestImport, options.body, "request import") : parseWith(MsgBodySchema, options.body, "message body");
+        const importedDelete = live.requestBinding && body?.t === "delete" && requestLogState(this, live.requestBinding).reservations.has(body.target) ? body.target : undefined;
+        // Portable imports retain their wrapper author. Their proof, rather than MsgBody, supplies source authority.
+        const commit = this.#authorize(entry, { ...options, body: imported || importedDelete ? undefined : body });
+        const hash = convEntryHash(entry.prev, event);
+        commit();
+        if (importedDelete) {
+            const target = this.#messages.get(importedDelete);
+            if (target)
+                target.deleted = true;
+        }
+        this.#hashes.push(hash);
+        this.#entries.push(entry);
+        this.#ids.add(event.id);
+        if (body !== undefined)
+            this.#bodies.set(entry.seq, body);
+        return hash;
+    }
+    #authorize(entry, options) {
+        const { event, seq } = entry;
+        const current = this.state();
+        const author = participantOf(event.by);
+        if (current === undefined) {
+            if (event.class !== "op" || event.body.op !== "create")
+                fail("conv_conflict", "the first entry must be create");
+            return this.#create(event, seq, options.live ?? {});
+        }
+        if (event.class === "op") {
+            const op = this.opHead();
+            if (event.opHead.seq !== op.seq || event.opHead.hash !== op.hash)
+                fail("conv_conflict", "op head is not the current one");
+            if (event.by.agent !== undefined)
+                fail("forbidden", "an op is a person's: an agent never writes one");
+            const d = draftOf(current);
+            const extra = this.#op(d, event, seq, options.live ?? {});
+            return () => {
+                d.changed = seq;
+                this.#push(seq, freezeDraft(d));
+                this.#ops.push(seq);
+                this.#record(event, seq, author);
+                extra?.();
+            };
+        }
+        this.#checkOpHead(event);
+        return this.#msg(current, event, seq, author, options);
+    }
+    #checkOpHead(event) {
+        const { seq, hash } = event.opHead;
+        const op = this.opHead();
+        if (seq > op.seq || this.#hashes[seq] !== hash || (seq !== 0 && !this.#ops.includes(seq)))
+            fail("conv_conflict", "op head names no op of this log");
+    }
+    #push(seq, snapshot) {
+        this.#snapshots.push({ seq, snapshot });
+    }
+    #record(event, seq, author, extra = {}) {
+        this.#messages.set(event.id, { id: event.id, seq, class: event.class, author, deleted: false, pinned: false, reactions: [], ...extra });
+    }
+    // ---- ops ----
+    #create(event, seq, live) {
+        const op = event.body;
+        if (event.opHead.seq !== 0 || event.opHead.hash !== this.#hashes[0])
+            fail("conv_conflict", "create's op head is h(0)");
+        if (event.by.agent !== undefined)
+            fail("forbidden", "an op is a person's: an agent never writes one");
+        const by = event.by.person;
+        const seats = op.participants;
+        const unique = new Set(seats.map((s) => s.p));
+        const d = {
+            cid: this.cid,
+            kind: op.kind,
+            history: op.history,
+            retainDays: op.retainDays,
+            post: op.post ?? "all",
+            invite: op.invite ?? "all",
+            pins: op.pins ?? "all",
+            archived: false,
+            epoch: 0,
+            epochSince: seq,
+            epochTs: event.ts,
+            rekeyDue: new Set(),
+            participants: new Map(),
+            agentContext: "members",
+            bridges: "none",
+            votes: new Map(),
+            changed: seq,
+        };
+        if (op.visibility !== undefined)
+            d.visibility = op.visibility;
+        if (op.org !== undefined)
+            d.org = op.org;
+        const state = (s) => {
+            const agentOf = participantAgent(s.p) === undefined ? undefined : participantPerson(s.p);
+            if (agentOf !== undefined)
+                return agentOf === by ? "member" : "invited";
+            return s.role === "guest" && s.p !== by ? "invited" : "member";
+        };
+        switch (op.kind) {
+            case "dm": {
+                if (seats.length !== 2)
+                    fail("invalid_request", "a dm lists exactly its two participants");
+                if (seats.some((s) => s.role !== "member"))
+                    fail("invalid_request", "both participants of a dm are members");
+                if (op.visibility !== undefined || op.org !== undefined || op.history !== "none" || op.sealedMeta !== undefined) {
+                    fail("invalid_request", "a dm has no visibility, org or meta, and history none");
+                }
+                if (op.post !== undefined || op.invite !== undefined || op.pins !== undefined)
+                    fail("invalid_request", "a dm has no permits");
+                if (this.cid !== dmConvId(seats[0].p, seats[1].p))
+                    fail("invalid_request", "a dm's cid is the one its participants derive");
+                if (!seats.some((s) => participantPerson(s.p) === by))
+                    fail("forbidden", "a dm is created by the person of one of its participants");
+                break;
+            }
+            case "self": {
+                if (seats.length !== 1 || seats[0].p !== by || seats[0].role !== "owner")
+                    fail("invalid_request", "a self conversation lists only its person, as owner");
+                if (this.cid !== selfConvId(by))
+                    fail("invalid_request", "a self conversation's cid is its person's");
+                if (op.visibility !== undefined || op.org !== undefined || op.history !== "shared" || op.sealedMeta !== undefined) {
+                    fail("invalid_request", "a self conversation has no visibility, org or meta, and history shared");
+                }
+                break;
+            }
+            case "group":
+            case "channel": {
+                if (this.cid.startsWith("d_") || this.cid.startsWith("s_"))
+                    fail("invalid_request", "a group or channel id is c_ and a ULID");
+                if (unique.size !== seats.length)
+                    fail("invalid_request", "a participant is listed twice");
+                if (!seats.some((s) => s.p === by && s.role === "owner"))
+                    fail("forbidden", "the creator is a participant, as owner");
+                if (op.kind === "group") {
+                    if (op.visibility !== undefined || op.org !== undefined)
+                        fail("invalid_request", "a group has no visibility or org");
+                    if (seats.length < 3)
+                        fail("invalid_request", "a group has at least 3 participants");
+                    if (seats.length > LIMITS.groupParticipants)
+                        fail("too_large", "a group has at most LIMITS.groupParticipants participants");
+                }
+                else {
+                    if (op.visibility === undefined)
+                        fail("invalid_request", "a channel states its visibility");
+                    if (op.visibility === "public" && op.org === undefined)
+                        fail("invalid_request", "a public channel names its org");
+                }
+                this.#checkSeats(seats, by, live, op.org ?? live.orgOf?.(by));
+                break;
+            }
+        }
+        for (const s of seats)
+            if (!d.participants.has(s.p))
+                d.participants.set(s.p, participantFrom(s, state(s), seq));
+        return () => {
+            this.#push(seq, freezeDraft(d));
+            this.#ops.push(seq);
+            this.#record(event, seq, participantOf(event.by));
+        };
+    }
+    /** Seats someone else adds: an agent of another person gets no device or respondTo; a person of another org is a guest. */
+    #checkSeats(seats, by, live, org) {
+        for (const s of seats) {
+            const person = participantPerson(s.p);
+            if (participantAgent(s.p) !== undefined && person !== by && (s.device !== undefined || s.respondTo !== undefined)) {
+                fail("forbidden", "only an agent's own person seats it");
+            }
+            if (live.orgOf && s.role !== "guest" && person !== by && (org === undefined || live.orgOf(person) !== org)) {
+                fail("forbidden", "a person of another org is added as a guest");
+            }
+            const owner = seats.find((p) => p.p === person) ?? this.state()?.participants.find((p) => p.p === person);
+            if (participantAgent(s.p) !== undefined && owner?.role === "guest" && s.role !== "guest")
+                fail("forbidden", "a guest's agent inherits the guest role");
+        }
+    }
+    #op(d, event, seq, live) {
+        const op = event.body;
+        const by = event.by.person;
+        const me = d.participants.get(by);
+        const fixed = d.kind === "dm" || d.kind === "self";
+        const requireMember = () => {
+            if (!me)
+                fail("not_member", "the author is not a participant");
+            if (me.state !== "member")
+                fail("forbidden", "the author has not accepted");
+            return me;
+        };
+        const requireAdmin = () => {
+            const rec = requireMember();
+            if (!isAdminRole(rec.role))
+                fail("forbidden", "only an owner or admin may do this");
+            return rec;
+        };
+        const owners = () => [...d.participants.values()].filter((p) => p.role === "owner" && p.agent === undefined);
+        // A sealed op is sealed as a message is: never under a key a removed device holds (spec §16.7).
+        const sealedUnder = (epoch) => {
+            if (epoch !== d.epoch)
+                fail("stale_epoch", `the current epoch is ${d.epoch}`);
+            if (d.rekeyDue.size > 0)
+                fail("stale_epoch", "a rekey is due before the next sealed op");
+        };
+        const removeWithAgents = (p) => {
+            const target = d.participants.get(p);
+            d.participants.delete(p);
+            if (target.agent === undefined)
+                for (const other of [...d.participants.keys()])
+                    if (participantPerson(other) === target.person)
+                        d.participants.delete(other);
+        };
+        switch (op.op) {
+            case "create":
+                return fail("conv_conflict", "the conversation already exists");
+            case "add": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind}'s participants are fixed`);
+                const rec = requireMember();
+                if (rec.role === "guest")
+                    fail("forbidden", "a guest cannot invite");
+                if (d.invite === "admins" && !isAdminRole(rec.role))
+                    fail("forbidden", "only an owner or admin may invite");
+                if (new Set(op.participants.map((s) => s.p)).size !== op.participants.length)
+                    fail("invalid_request", "a participant is listed twice");
+                for (const s of op.participants) {
+                    if (d.participants.has(s.p))
+                        fail("forbidden", "already a participant");
+                    if (s.role === "owner" && rec.role !== "owner")
+                        fail("forbidden", "only an owner adds an owner");
+                    if (s.role === "admin" && rec.role !== "owner")
+                        fail("forbidden", "only an owner adds an admin");
+                }
+                this.#checkSeats(op.participants, by, live, d.org ?? live.orgOf?.(by));
+                const max = d.kind === "group" ? LIMITS.groupParticipants : LIMITS.convParticipants;
+                if (d.participants.size + op.participants.length > max)
+                    fail("too_large", `a ${d.kind} is full`);
+                for (const s of op.participants) {
+                    const agentOf = participantAgent(s.p) === undefined ? undefined : participantPerson(s.p);
+                    const state = agentOf !== undefined ? (agentOf === by ? "member" : "invited") : s.role === "guest" ? "invited" : "member";
+                    d.participants.set(s.p, participantFrom(s, state, seq));
+                }
+                if ((d.kind === "group" || d.history === "none") && op.participants.some((s) => d.participants.get(s.p).state === "member"))
+                    d.rekeyDue.add("added");
+                return undefined;
+            }
+            case "accept": {
+                if (!me)
+                    fail("not_member", "the author is not a participant");
+                if (me.state !== "invited")
+                    fail("invalid_state", "the author is not invited");
+                if (me.role === "guest") {
+                    if (op.invitation === undefined)
+                        fail("forbidden", "a guest accepts a signed exposure preview");
+                    verifyGuestInvitation(this, op.invitation, by, event.ts);
+                }
+                me.state = "member";
+                me.since = seq;
+                if (d.kind === "group" || d.history === "none")
+                    d.rekeyDue.add("added");
+                return undefined;
+            }
+            case "join": {
+                if (d.kind !== "channel" || d.visibility !== "public")
+                    fail("forbidden", "only a public channel may be joined");
+                if (me)
+                    fail("invalid_state", "already a participant");
+                if (live.orgOf && live.orgOf(by) !== d.org)
+                    fail("forbidden", "the channel is open to another org");
+                if (d.participants.size + 1 > LIMITS.convParticipants)
+                    fail("too_large", "the channel is full");
+                d.participants.set(by, participantFrom({ p: by, role: "member" }, "member", seq));
+                if (d.history === "none")
+                    d.rekeyDue.add("added");
+                return undefined;
+            }
+            case "leave": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind}'s participants are fixed`);
+                if (!me)
+                    fail("not_member", "the author is not a participant");
+                const others = [...d.participants.values()].some((p) => p.agent === undefined && p.person !== by);
+                if (me.role === "owner" && owners().length === 1 && others)
+                    fail("forbidden", "the last owner names another before leaving");
+                removeWithAgents(by);
+                d.rekeyDue.add("removed");
+                return undefined;
+            }
+            case "remove": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind}'s participants are fixed`);
+                if (new Set(op.participants).size !== op.participants.length)
+                    fail("invalid_request", "a participant is listed twice");
+                for (const p of op.participants) {
+                    const target = d.participants.get(p);
+                    if (!target)
+                        fail("not_found", "not a participant");
+                    if (target.agent !== undefined && target.person === by)
+                        continue;
+                    const rec = requireAdmin();
+                    if (target.role === "owner" && rec.role !== "owner")
+                        fail("forbidden", "an admin cannot remove an owner");
+                }
+                for (const p of op.participants)
+                    if (d.participants.has(p))
+                        removeWithAgents(p);
+                if (owners().length === 0 && [...d.participants.values()].some((p) => p.agent === undefined))
+                    fail("forbidden", "the last owner cannot be removed");
+                d.rekeyDue.add("removed");
+                return undefined;
+            }
+            case "role": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind}'s roles are fixed`);
+                const rec = requireAdmin();
+                const target = d.participants.get(op.p);
+                if (!target)
+                    fail("not_found", "not a participant");
+                if (target.role === "guest" && op.role !== "guest")
+                    fail("forbidden", "a guest cannot be promoted");
+                if (target.agent !== undefined && d.participants.get(target.person)?.role === "guest" && op.role !== "guest")
+                    fail("forbidden", "a guest's agent inherits the guest role");
+                if (rec.role === "admin" && (target.role === "owner" || (op.role !== "member" && op.role !== "guest"))) {
+                    fail("forbidden", "an admin sets only member or guest, and never an owner's role");
+                }
+                if (target.role === "owner" && op.role !== "owner" && owners().length === 1)
+                    fail("forbidden", "the last owner cannot be demoted");
+                target.role = op.role;
+                return undefined;
+            }
+            case "seat": {
+                const target = d.participants.get(op.p);
+                if (!target)
+                    fail("not_found", "not a participant");
+                if (target.agent === undefined)
+                    fail("invalid_request", "only an agent is seated");
+                if (target.person !== by)
+                    fail("forbidden", "only the agent's own person seats it");
+                if (target.role === "guest" && (me?.state !== "member" || me.role !== "guest"))
+                    fail("forbidden", "a guest agent's owner must be an accepted, visible guest");
+                if (target.state === "invited") {
+                    target.since = seq;
+                    if (d.kind === "group" || d.history === "none")
+                        d.rekeyDue.add("added");
+                }
+                target.state = "member";
+                if (op.device !== undefined)
+                    target.device = op.device;
+                if (op.respondTo !== undefined)
+                    target.respondTo = op.respondTo;
+                return undefined;
+            }
+            case "settings": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind} has no settings`);
+                requireAdmin();
+                if (op.visibility !== undefined) {
+                    if (d.kind !== "channel")
+                        fail("invalid_request", "only a channel has a visibility");
+                    if (op.visibility === "public" && d.org === undefined)
+                        fail("invalid_state", "a channel with no org cannot be public");
+                    d.visibility = op.visibility;
+                }
+                if (op.history !== undefined && op.history !== d.history) {
+                    d.history = op.history;
+                    d.rekeyDue.add("settings");
+                }
+                if (op.retainDays !== undefined)
+                    d.retainDays = op.retainDays;
+                if (op.post !== undefined)
+                    d.post = op.post;
+                if (op.invite !== undefined)
+                    d.invite = op.invite;
+                if (op.pins !== undefined)
+                    d.pins = op.pins;
+                return undefined;
+            }
+            case "archive": {
+                if (fixed)
+                    fail("forbidden", `a ${d.kind} is never archived`);
+                requireAdmin();
+                d.archived = op.on;
+                return undefined;
+            }
+            case "rekey": {
+                if (![...d.participants.values()].some((p) => p.person === by && p.state === "member"))
+                    fail("not_member", "the author's person is not a participant");
+                if (op.epoch !== d.epoch + 1)
+                    fail("invalid_request", "a rekey starts the next epoch");
+                if (op.cause === "device") {
+                    if (op.until !== undefined && op.until >= seq)
+                        fail("invalid_request", "a device cut precedes its rekey");
+                    if (live.isRemovedDevice && !live.isRemovedDevice(op.device))
+                        fail("forbidden", "the device is not removed in the verified realm");
+                }
+                if (op.cause === "schedule") {
+                    if (event.ts - d.epochTs < LIMITS.rekeyScheduleMs)
+                        fail("invalid_state", "the epoch is not yet due for a scheduled rekey");
+                }
+                else if (op.cause !== "device" && !d.rekeyDue.has(op.cause)) {
+                    fail("invalid_state", "no rekey is due for this cause");
+                }
+                d.epoch = op.epoch;
+                d.epochSince = seq;
+                d.epochTs = event.ts;
+                d.rekeyDue.clear();
+                return op.cause === "device" ? () => { if (!this.#revoked.has(op.device))
+                    this.#revoked.set(op.device, seq); } : undefined;
+            }
+            case "policy": {
+                if (d.kind === "self")
+                    fail("forbidden", "a self conversation has no policy");
+                const rec = requireMember();
+                if (d.kind === "channel") {
+                    if (!isAdminRole(rec.role))
+                        fail("forbidden", "only an owner or admin sets a channel's policy");
+                    if (op.agentContext !== undefined)
+                        d.agentContext = op.agentContext;
+                    if (op.bridges !== undefined)
+                        d.bridges = op.bridges;
+                }
+                else {
+                    const vote = { ...d.votes.get(by) };
+                    if (op.agentContext !== undefined)
+                        vote.agentContext = op.agentContext;
+                    if (op.bridges !== undefined)
+                        vote.bridges = op.bridges;
+                    d.votes.set(by, vote);
+                }
+                return undefined;
+            }
+            case "meta": {
+                if (d.kind === "dm" || d.kind === "self")
+                    fail("forbidden", `a ${d.kind} has no meta`);
+                const rec = requireMember();
+                if (d.kind === "channel" && !isAdminRole(rec.role))
+                    fail("forbidden", "only an owner or admin sets a channel's meta");
+                sealedUnder(op.epoch);
+                return undefined;
+            }
+            case "setting": {
+                if (d.kind !== "self")
+                    fail("forbidden", "a setting goes in the self conversation only");
+                requireMember();
+                sealedUnder(op.epoch);
+                return undefined;
+            }
+        }
+    }
+    // ---- keys and messages ----
+    #msg(s, event, seq, author, options) {
+        const rec = s.participants.find((p) => p.p === author);
+        if (!rec)
+            fail("not_member", "the author is not a participant");
+        if (rec.state !== "member")
+            fail("forbidden", "the author has not accepted");
+        if (event.epoch !== s.epoch)
+            fail("stale_epoch", `the current epoch is ${s.epoch}`);
+        if (s.rekeyDue.length > 0)
+            fail("stale_epoch", "a rekey is due before the next message");
+        if (options.body === undefined)
+            return () => this.#record(event, seq, author);
+        const body = parseWith(MsgBodySchema, options.body, "message body");
+        return this.#body(s, rec, body, event, seq, author);
+    }
+    #target(id) {
+        const target = this.#messages.get(id);
+        if (!target || target.class !== "msg")
+            fail("not_found", "no such message in this conversation");
+        return target;
+    }
+    #body(s, rec, body, event, seq, author) {
+        const record = (extra = {}) => this.#record(event, seq, author, { t: body.t, ...extra });
+        const mayPost = () => {
+            if (s.archived)
+                fail("forbidden", "the conversation is archived");
+            if (s.post === "admins" && !isAdminRole(rec.role))
+                fail("forbidden", "only an owner or admin may post");
+        };
+        const live = (target) => {
+            if (target.deleted)
+                fail("invalid_state", "the message is deleted");
+        };
+        if ((s.kind === "self") !== (body.t === "sync"))
+            fail("invalid_request", "sync bodies go in the self conversation, and only they");
+        switch (body.t) {
+            case "line": {
+                mayPost();
+                if (body.via !== undefined && event.by.agent !== undefined)
+                    fail("forbidden", "only a person writes from a linked channel");
+                if (body.thread !== undefined)
+                    this.#target(body.thread);
+                if (body.answers !== undefined)
+                    this.#target(body.answers);
+                return () => record();
+            }
+            case "edit": {
+                if (s.archived)
+                    fail("forbidden", "the conversation is archived");
+                const target = this.#target(body.target);
+                if (target.t !== undefined && target.t !== "line")
+                    fail("invalid_state", "only a line is edited");
+                live(target);
+                if (target.author !== author)
+                    fail("forbidden", "only the line's author edits it");
+                return () => record();
+            }
+            case "delete": {
+                const target = this.#target(body.target);
+                if (target.t !== undefined && target.t !== "line" && target.t !== "task")
+                    fail("invalid_state", "only a line or a task event is deleted");
+                live(target);
+                if (target.author !== author && !isAdminRole(rec.role))
+                    fail("forbidden", "only the author, an owner or an admin deletes");
+                return () => {
+                    record();
+                    if (target.pinned)
+                        this.#pinned--;
+                    target.deleted = true;
+                    target.pinned = false;
+                    target.reactions = [];
+                };
+            }
+            case "react": {
+                mayPost();
+                const target = this.#target(body.target);
+                live(target);
+                const entry = target.reactions.find((r) => r.key === body.key);
+                if (body.on && !entry && target.reactions.length >= LIMITS.reactionsPerEvent)
+                    fail("too_large", "the message has LIMITS.reactionsPerEvent reaction keys");
+                return () => {
+                    record();
+                    if (body.on) {
+                        if (!entry)
+                            target.reactions.push({ key: body.key, by: [author] });
+                        else if (!entry.by.includes(author))
+                            entry.by.push(author);
+                    }
+                    else if (entry) {
+                        entry.by = entry.by.filter((p) => p !== author);
+                        if (entry.by.length === 0)
+                            target.reactions = target.reactions.filter((r) => r !== entry);
+                    }
+                };
+            }
+            case "pin": {
+                if (s.archived)
+                    fail("forbidden", "the conversation is archived");
+                if (s.pins === "admins" && !isAdminRole(rec.role))
+                    fail("forbidden", "only an owner or admin may pin");
+                const target = this.#target(body.target);
+                live(target);
+                if (body.on && !target.pinned && this.#pinned >= LIMITS.pins)
+                    fail("too_large", "the conversation has LIMITS.pins pins");
+                return () => {
+                    record();
+                    if (body.on !== target.pinned)
+                        this.#pinned += body.on ? 1 : -1;
+                    target.pinned = body.on;
+                };
+            }
+            case "task": {
+                const task = body.task;
+                if (task.k === "request") {
+                    mayPost();
+                    const to = s.participants.find((p) => p.p === task.to);
+                    if (!to || to.state !== "member")
+                        fail("not_found", "the task's agent is not a participant");
+                    return () => record({ taskRoot: true, taskTo: task.to });
+                }
+                const root = this.#target(task.root);
+                if (root.t !== undefined && !root.taskRoot)
+                    fail("invalid_state", "the root is not a task request");
+                if ((task.k === "status" || task.k === "artifact") && root.taskTo !== undefined && root.taskTo !== author)
+                    fail("forbidden", "only the task's agent reports on it");
+                if ((task.k === "cancel" || task.k === "followUp") && root.author !== author)
+                    fail("forbidden", "only the requester cancels or follows up");
+                return () => record();
+            }
+            case "receipt": {
+                this.#target(body.target);
+                return () => record();
+            }
+            case "sync":
+                return () => record();
+        }
+    }
+}
+const EntryShape = z.strictObject({ seq: z.number().int().min(1), prev: HashSchema, event: z.unknown() });