@gryt/core 0.9.0 → 0.11.0

package/README.md

@@ -47,6 +47,14 @@ goes missing **and** when one appears that nobody listed.
 - **`permissions`** — the channel scope matrix: rules in, grid out, and back.
   The two apps keyed their cell map differently, a NUL on the desktop and a
   space on the phone, which is a key one of them could collide on.
+- **`mls`** — the DM half of MLS stage 1. It keeps a device's KeyPackages
+  topped up, opens a DM group, joins from a Welcome, sends, and reads the group
+  log in order. Each app hands it the socket, the storage and the pins through
+  the interfaces in `src/mls/interfaces.ts`. `mlsPinsFromPeerPins` builds the
+  pins from the peer pins `@gryt/crypto` already keeps.
+  `encodeMlsDmContent` and `decodeMlsDmContent` write and read what goes inside
+  each message, so both apps use the same JSON. It's the one module with a
+  dependency, `@gryt/crypto`, pinned exactly the way the apps pin it.
 
 ## What deliberately isn't
 

package/dist/index.d.ts

@@ -10,3 +10,7 @@ export { groupMembersByRole, OFFLINE_GROUP_KEY, UNGROUPED_GROUP_KEY, type Groupa
 export { senderStreamId } from "./webrtc/senderStreamId.js";
 export { describeFolderRules, folderFollowNote, folderPhrase, } from "./permissions/folderRules.js";
 export { agreementAt, createTermsGate, GUIDELINES_URL, TERMS_STORAGE_KEY, TERMS_URL, TERMS_VERSION, } from "./terms/termsAgreement.js";
+export { createMlsDmDriver, MlsDriverError, type MlsDriverErrorCode } from "./mls/dmDriver.js";
+export { mlsPinsFromPeerPins } from "./mls/pins.js";
+export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, type MlsDmContent, } from "./mls/content.js";
+export type { DmSealingMode, MlsClaimedKeyPackage, MlsDecryptedMessage, MlsDeviceRecord, MlsDeviceRef, MlsDmDriver, MlsDmDriverOptions, MlsDmEvents, MlsGroupRecord, MlsGroupView, MlsKeyPackageRecord, MlsLogEntry, MlsPins, MlsRefusal, MlsReply, MlsServerCapability, MlsStateStore, MlsTransport, MlsWelcomeDelivery, } from "./mls/interfaces.js";

package/dist/index.js

@@ -12,3 +12,6 @@ export { groupMembersByRole, OFFLINE_GROUP_KEY, UNGROUPED_GROUP_KEY, } from "./m
 export { senderStreamId } from "./webrtc/senderStreamId.js";
 export { describeFolderRules, folderFollowNote, folderPhrase, } from "./permissions/folderRules.js";
 export { agreementAt, createTermsGate, GUIDELINES_URL, TERMS_STORAGE_KEY, TERMS_URL, TERMS_VERSION, } from "./terms/termsAgreement.js";
+export { createMlsDmDriver, MlsDriverError } from "./mls/dmDriver.js";
+export { mlsPinsFromPeerPins } from "./mls/pins.js";
+export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, } from "./mls/content.js";

package/dist/mls/content.d.ts

@@ -0,0 +1,22 @@
+import { type SealedAttachmentKey } from "@gryt/crypto";
+export type MlsDmContent = {
+    type: "message";
+    /** Made by the sender, a UUID. Edits and deletes name it. */
+    id: string;
+    text: string;
+    replyTo?: string;
+    /** Upload id to what `sealAttachment` returned; `openAttachment` takes it as `meta`. */
+    attachments?: Record<string, SealedAttachmentKey>;
+} | {
+    type: "edit";
+    id: string;
+    text: string;
+} | {
+    type: "delete";
+    id: string;
+};
+export declare const MLS_DM_CONTENT_VERSION = 1;
+/** The same bytes the phone writes: `v` first, then the content's fields in this order. */
+export declare function encodeMlsDmContent(content: MlsDmContent): Uint8Array;
+/** Null for anything this version can't read: a newer version, a new type, or junk. */
+export declare function decodeMlsDmContent(bytes: Uint8Array): MlsDmContent | null;

package/dist/mls/content.js

@@ -0,0 +1,115 @@
+import { base64UrlDecode } from "@gryt/crypto";
+export const MLS_DM_CONTENT_VERSION = 1;
+const MAX_ID = 64;
+/** Well past the composer's limit, and under what one `mls:send` can carry. */
+const MAX_TEXT = 32_000;
+const MAX_ATTACHMENTS = 10;
+const MAX_LABEL = 255;
+const UPLOAD_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const isId = (v) => typeof v === "string" && v.length > 0 && v.length <= MAX_ID;
+const isText = (v) => typeof v === "string" && v.length <= MAX_TEXT;
+const isCount = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const isLabel = (v) => typeof v === "string" && v.length <= MAX_LABEL;
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function decodesTo(v, bytes) {
+    if (typeof v !== "string")
+        return false;
+    try {
+        return base64UrlDecode(v).length === bytes;
+    }
+    catch {
+        return false;
+    }
+}
+/** Only the fields a reader uses, each checked; null for anything off. */
+function readAttachmentKey(v) {
+    if (!isObject(v) || !isId(v.id) || !decodesTo(v.key, 32) || !decodesTo(v.iv, 12))
+        return null;
+    const out = { id: v.id, key: v.key, iv: v.iv };
+    for (const field of ["name", "mime"]) {
+        if (v[field] === undefined)
+            continue;
+        if (!isLabel(v[field]))
+            return null;
+        out[field] = v[field];
+    }
+    for (const field of ["size", "width", "height"]) {
+        if (v[field] === undefined)
+            continue;
+        if (!isCount(v[field]))
+            return null;
+        out[field] = v[field];
+    }
+    return out;
+}
+function readAttachments(v) {
+    if (!isObject(v))
+        return null;
+    const entries = Object.entries(v);
+    if (entries.length === 0 || entries.length > MAX_ATTACHMENTS)
+        return null;
+    const out = {};
+    for (const [uploadId, meta] of entries) {
+        const key = readAttachmentKey(meta);
+        if (!UPLOAD_ID.test(uploadId) || !key)
+            return null;
+        out[uploadId] = key;
+    }
+    return out;
+}
+/** The same bytes the phone writes: `v` first, then the content's fields in this order. */
+export function encodeMlsDmContent(content) {
+    let body;
+    if (content.type === "message") {
+        body = { type: content.type, id: content.id, text: content.text };
+        if (content.replyTo !== undefined)
+            body.replyTo = content.replyTo;
+        if (content.attachments && Object.keys(content.attachments).length > 0)
+            body.attachments = content.attachments;
+    }
+    else if (content.type === "edit") {
+        body = { type: content.type, id: content.id, text: content.text };
+    }
+    else {
+        body = { type: content.type, id: content.id };
+    }
+    const bytes = new TextEncoder().encode(JSON.stringify({ v: MLS_DM_CONTENT_VERSION, ...body }));
+    if (!decodeMlsDmContent(bytes))
+        throw new Error("That content wouldn't read back, so it isn't sent.");
+    return bytes;
+}
+/** Null for anything this version can't read: a newer version, a new type, or junk. */
+export function decodeMlsDmContent(bytes) {
+    let raw;
+    try {
+        raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(raw) || raw.v !== MLS_DM_CONTENT_VERSION || !isId(raw.id))
+        return null;
+    const { type, id, text } = raw;
+    if (type === "message" && isText(text)) {
+        const out = { type, id, text };
+        if (raw.replyTo !== undefined) {
+            if (!isId(raw.replyTo))
+                return null;
+            out.replyTo = raw.replyTo;
+        }
+        if (raw.attachments !== undefined) {
+            const attachments = readAttachments(raw.attachments);
+            if (!attachments)
+                return null;
+            out.attachments = attachments;
+        }
+        return out;
+    }
+    if (type === "edit" && isText(text))
+        return { type, id, text };
+    if (type === "delete")
+        return { type, id };
+    return null;
+}

package/dist/mls/dmDriver.d.ts

@@ -0,0 +1,9 @@
+import type { MlsDmDriver, MlsDmDriverOptions, MlsRefusal } from "./interfaces.js";
+export type MlsDriverErrorCode = "refused" | "no_device" | "waiting_for_welcome" | "not_in_group" | "unexpected_member" | "peer_unverified" | "too_many_attachments" | "commit_retries";
+export declare class MlsDriverError extends Error {
+    code: MlsDriverErrorCode;
+    /** The server's refusal, when there was one. */
+    refusal?: MlsRefusal;
+    constructor(code: MlsDriverErrorCode, message: string, refusal?: MlsRefusal);
+}
+export declare function createMlsDmDriver(options: MlsDmDriverOptions): MlsDmDriver;

package/dist/mls/dmDriver.js

@@ -0,0 +1,629 @@
+import { addMlsMembers, asIdentityScope, base64UrlDecode, createMlsGroup, decodeMlsGroupState, encodeMlsGroupState, encryptMlsMessage, forgetMlsSecrets, generateMlsKeyPackage, joinMlsGroup, mlsGroupInfo, mlsGroupMembers, mlsWelcomeRefs, processMlsMessage, readMlsKeyPackage, removeMlsMembers, } from "@gryt/crypto";
+/** Five devices per person per server (design, section 1). The server holds the same line. */
+const MLS_MAX_DEVICES_PER_PERSON = 5;
+const COMMIT_ATTEMPTS = 5;
+/** socket.io closes the connection on a packet with more than 10 binary parts (GRYT-1522). */
+const MAX_BINARY_PARTS = 10;
+const LOG_PAGE = MAX_BINARY_PARTS;
+const PUBLISH_BATCH = MAX_BINARY_PARTS - 1;
+/** The server's cap on files in one message. */
+const MAX_ATTACHMENT_IDS = 10;
+const WELCOME_WAIT_MS = 10_000;
+/** The server keeps Welcomes 30 days; a last-resort package is replaced with a week to go. */
+const WELCOME_KEEP_S = 30 * 86_400;
+const RENEW_BEFORE_S = 7 * 86_400;
+export class MlsDriverError extends Error {
+    code;
+    /** The server's refusal, when there was one. */
+    refusal;
+    constructor(code, message, refusal) {
+        super(message);
+        this.name = "MlsDriverError";
+        this.code = code;
+        this.refusal = refusal;
+    }
+}
+function refused(what, r) {
+    return new MlsDriverError("refused", `${what}: ${r.error} (${r.message})`, r);
+}
+function toHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+const epochOf = (state) => Number(mlsGroupInfo(state).epoch);
+const groupIdOf = (state) => toHex(base64UrlDecode(mlsGroupInfo(state).groupId));
+/* One job at a time per key, in the order they were asked for. A job must never wait on
+   another job with its own key. */
+function keyedQueue() {
+    const tails = new Map();
+    return (key, job) => {
+        const result = (tails.get(key) ?? Promise.resolve()).then(job);
+        const tail = result.then(() => undefined, () => undefined);
+        tails.set(key, tail);
+        void tail.then(() => {
+            if (tails.get(key) === tail)
+                tails.delete(key);
+        });
+        return result;
+    };
+}
+export function createMlsDmDriver(options) {
+    const { transport, store, pins, events, serverUserId: self, capability } = options;
+    const scope = asIdentityScope(options.scope);
+    const trusts = new Map();
+    /** What the engine asks about every leaf: is it somebody in this conversation, by pin. */
+    function trustFor(conversationId) {
+        let t = trusts.get(conversationId);
+        if (!t) {
+            const trustPersonKey = pins.trustFor?.(conversationId) ?? (async (c) => (await pins.personOf(conversationId, c.personPublicKey)) !== null);
+            t = { scope, trustPersonKey };
+            trusts.set(conversationId, t);
+        }
+        return t;
+    }
+    const run = keyedQueue();
+    let device = null;
+    let registered = false;
+    /** Conversations whose device list was checked since the last `mls:devices:changed`. */
+    const reconciled = new Set();
+    const seen = new Set();
+    const welcomeWaiters = new Map();
+    async function ownDevice() {
+        if (device)
+            return device;
+        let d = await store.loadDevice();
+        if (!d) {
+            d = await options.newDevice();
+            await store.saveDevice(d);
+        }
+        device = d;
+        return d;
+    }
+    async function markSeen(serverUserId) {
+        if (serverUserId === self || seen.has(serverUserId))
+            return;
+        await pins.markSeenOnMls(serverUserId);
+        seen.add(serverUserId);
+    }
+    /** Every person with a leaf in the group, by pin. Null for a leaf nobody's pin covers. */
+    async function peopleIn(conversationId, state) {
+        const members = mlsGroupMembers(state, scope);
+        return Promise.all(members.map((m) => pins.personOf(conversationId, m.certificate.personPublicKey)));
+    }
+    async function notePeople(conversationId, state) {
+        for (const person of await peopleIn(conversationId, state))
+            if (person)
+                await markSeen(person);
+    }
+    async function save(open, cursor = open.rec.cursor) {
+        open.rec = { ...open.rec, state: encodeMlsGroupState(open.state), cursor };
+        await store.saveGroup(open.rec);
+    }
+    async function load(conversationId) {
+        const rec = await store.loadGroup(conversationId);
+        return rec ? { rec, state: decodeMlsGroupState(rec.state, trustFor(conversationId)) } : null;
+    }
+    // ── KeyPackages ─────────────────────────────────────────────────────
+    async function topUp(counts, forceLastResort = false) {
+        const d = await ownDevice();
+        const now = Math.floor(Date.now() / 1000);
+        const held = await store.listKeyPackages();
+        // A Welcome can still name a package for as long as the server keeps Welcomes.
+        for (const k of held)
+            if (k.expiresAt !== undefined && k.expiresAt < now - WELCOME_KEEP_S)
+                await store.deleteKeyPackage(k.ref);
+        const newestLast = held.filter((k) => k.lastResort).sort((a, b) => b.createdAt - a.createdAt)[0];
+        // One with no expiresAt predates lifetimes, and readers now refuse it.
+        const lastRunningOut = !!newestLast && (newestLast.expiresAt === undefined || newestLast.expiresAt - now < RENEW_BEFORE_S);
+        const wanted = !registered || counts.unclaimed < counts.target / 2 ? counts.target - counts.unclaimed : 0;
+        const needLastResort = !counts.lastResort || forceLastResort || lastRunningOut;
+        if (wanted <= 0 && !needLastResort && registered)
+            return;
+        const make = async (lastResort) => {
+            const kp = await generateMlsKeyPackage(d);
+            return { ...kp, lastResort, createdAt: Date.now() };
+        };
+        const fresh = [];
+        for (let i = 0; i < wanted; i++)
+            fresh.push(await make(false));
+        const last = needLastResort ? await make(true) : undefined;
+        // The private halves are stored first, so a Welcome can never name one this device lost.
+        await store.putKeyPackages(last ? [...fresh, last] : fresh);
+        // Nine at a time, and the last-resort one rides with the last batch.
+        const all = fresh.map((k) => k.keyPackage);
+        for (let i = 0; i === 0 || i < all.length; i += PUBLISH_BATCH) {
+            const keyPackages = all.slice(i, i + PUBLISH_BATCH);
+            const final = i + PUBLISH_BATCH >= all.length;
+            const r = await transport.publishKeyPackages({
+                deviceId: d.deviceId,
+                keyPackages,
+                lastResort: final ? last?.keyPackage : undefined,
+            });
+            if (!r.ok)
+                throw refused("Publishing KeyPackages", r);
+            registered = true;
+        }
+    }
+    async function syncAndTopUp(forceLastResort = false) {
+        const d = await ownDevice();
+        const r = await transport.sync({ deviceId: d.deviceId });
+        if (!r.ok)
+            throw refused("Sync", r);
+        registered = r.registered;
+        await topUp(r.keyPackages, forceLastResort);
+        return r.welcomes;
+    }
+    // ── The log ─────────────────────────────────────────────────────────
+    /** Returns false once the group can't go on from here; the state is kept, not dropped. */
+    async function applyEntry(open, e) {
+        if (e.seq <= open.rec.cursor)
+            return true;
+        const d = await ownDevice();
+        const current = epochOf(open.state);
+        if (e.kind === "commit") {
+            const pending = open.rec.pending;
+            if (pending && sameBytes(pending.commit, e.data)) {
+                open.state = decodeMlsGroupState(pending.state, trustFor(open.rec.conversationId));
+            }
+            else if (e.epoch < current) {
+                // Already in this state: our own commit, or one from before this device joined.
+            }
+            else if (e.epoch > current) {
+                events.onGroupLost?.({ conversationId: open.rec.conversationId, reason: "out_of_sync" });
+                return false;
+            }
+            else {
+                try {
+                    const r = await processMlsMessage(open.state, e.data);
+                    if (r.kind === "handshake" && r.removed) {
+                        await store.deleteGroup(open.rec.conversationId);
+                        events.onGroupLost?.({ conversationId: open.rec.conversationId, reason: "removed" });
+                        return false;
+                    }
+                    open.state = r.state;
+                }
+                catch {
+                    events.onGroupLost?.({ conversationId: open.rec.conversationId, reason: "out_of_sync" });
+                    return false;
+                }
+            }
+            open.rec = { ...open.rec, pending: undefined };
+            await notePeople(open.rec.conversationId, open.state);
+        }
+        else if (e.kind === "proposal") {
+            if (e.epoch === current) {
+                try {
+                    open.state = (await processMlsMessage(open.state, e.data)).state;
+                }
+                catch {
+                    events.onUndecryptable?.({ conversationId: open.rec.conversationId, seq: e.seq, reason: "bad_proposal" });
+                }
+            }
+        }
+        else if (!(e.senderServerUserId === self && e.senderDeviceId === d.deviceId) && e.epoch >= open.rec.joinedEpoch) {
+            let plaintext = null;
+            try {
+                const r = await processMlsMessage(open.state, e.data);
+                if (r.kind !== "application")
+                    throw new Error("Not an application message.");
+                open.state = r.state;
+                plaintext = r.plaintext;
+            }
+            catch {
+                events.onUndecryptable?.({ conversationId: open.rec.conversationId, seq: e.seq, reason: "undecryptable" });
+            }
+            if (plaintext) {
+                await events.onMessage({
+                    conversationId: open.rec.conversationId,
+                    seq: e.seq,
+                    senderServerUserId: e.senderServerUserId,
+                    senderDeviceId: e.senderDeviceId,
+                    plaintext,
+                    createdAt: e.createdAt,
+                });
+                await markSeen(e.senderServerUserId);
+            }
+        }
+        await save(open, e.seq);
+        return true;
+    }
+    /** Everything after the cursor, a page at a time. False when the group stopped. */
+    async function catchUp(open) {
+        for (;;) {
+            const r = await transport.fetchLog({ conversationId: open.rec.conversationId, after: open.rec.cursor, limit: LOG_PAGE });
+            if (!r.ok)
+                throw refused("Reading the group log", r);
+            if (r.group && r.group.groupId !== open.rec.groupId) {
+                events.onGroupLost?.({ conversationId: open.rec.conversationId, reason: "out_of_sync" });
+                return false;
+            }
+            if (r.gap && open.rec.cursor > 0) {
+                events.onUndecryptable?.({ conversationId: open.rec.conversationId, seq: open.rec.cursor + 1, reason: "gap" });
+            }
+            for (const e of r.entries)
+                if (!(await applyEntry(open, e)))
+                    return false;
+            if (r.nextCursor > open.rec.cursor)
+                await save(open, r.nextCursor);
+            if (!r.hasMore)
+                return true;
+        }
+    }
+    // ── Commits ─────────────────────────────────────────────────────────
+    /** Builds on the latest state, and on stale_epoch catches up and builds again. */
+    async function commitWithRetry(open, build) {
+        const d = await ownDevice();
+        for (let attempt = 0; attempt < COMMIT_ATTEMPTS; attempt++) {
+            const c = await build(open.state);
+            if (!c)
+                return;
+            open.rec = { ...open.rec, pending: { commit: c.commit, state: encodeMlsGroupState(c.state) } };
+            await save(open);
+            const r = await transport.commit({
+                conversationId: open.rec.conversationId,
+                deviceId: d.deviceId,
+                commit: c.commit,
+                welcome: c.welcome,
+            });
+            if (r.ok) {
+                open.state = c.state;
+                forgetMlsSecrets(c.consumed);
+                open.rec = { ...open.rec, pending: undefined };
+                await save(open);
+                return;
+            }
+            open.rec = { ...open.rec, pending: undefined };
+            await save(open);
+            if (r.error === "stale_epoch") {
+                if (!(await catchUp(open)))
+                    throw new MlsDriverError("not_in_group", "This device lost its place in the group.");
+                continue;
+            }
+            if (r.error === "no_group") {
+                // Saved locally but never registered, from a crash in between.
+                const created = await transport.createGroup({ conversationId: open.rec.conversationId, groupId: open.rec.groupId });
+                if (created.ok)
+                    continue;
+                await store.deleteGroup(open.rec.conversationId);
+                throw refused("Registering the group", created);
+            }
+            throw refused("Committing", r);
+        }
+        throw new MlsDriverError("commit_retries", "Other commits kept getting there first.");
+    }
+    /** Removes leaves for devices the server no longer lists, and with `adds` adds new ones. */
+    async function reconcile(open, peer, adds) {
+        const d = await ownDevice();
+        const conversationId = open.rec.conversationId;
+        const r = await transport.listDevices({ conversationId });
+        if (!r.ok)
+            throw refused("Listing devices", r);
+        const listed = r.devices.filter((x) => x.serverUserId === self || x.serverUserId === peer);
+        if (!listed.some((x) => x.serverUserId === self && x.deviceId === d.deviceId))
+            return;
+        const isListed = (id) => listed.some((x) => x.deviceId === id);
+        const treeIds = (s) => new Set(mlsGroupMembers(s, scope).map((m) => m.certificate.deviceId));
+        await commitWithRetry(open, async (s) => {
+            const gone = [...treeIds(s)].filter((id) => id !== d.deviceId && !isListed(id));
+            return gone.length ? removeMlsMembers(s, gone, scope) : null;
+        });
+        if (!adds)
+            return;
+        const inTree = treeIds(open.state);
+        const wanted = listed.filter((x) => !inTree.has(x.deviceId) && x.deviceId !== d.deviceId);
+        if (wanted.length === 0)
+            return;
+        let asking = wanted;
+        let addedPeer = false;
+        // A package out of date, by the reader or by addMlsMembers, gets one fresh claim for that device.
+        for (let round = 0; round < 2 && asking.length > 0; round++) {
+            const claim = await transport.claimKeyPackages({ conversationId, deviceId: d.deviceId, devices: asking });
+            if (!claim.ok)
+                throw refused("Claiming KeyPackages", claim);
+            asking = [];
+            const verified = [];
+            for (const kp of claim.keyPackages) {
+                const verdict = await vouchedFor(conversationId, kp, peer);
+                if (verdict === "ok")
+                    verified.push(kp);
+                else if (verdict === "unreadable")
+                    asking.push({ serverUserId: kp.serverUserId, deviceId: kp.deviceId });
+            }
+            await commitWithRetry(open, async (s) => {
+                const tree = treeIds(s);
+                const counts = new Map();
+                for (const person of await peopleIn(conversationId, s))
+                    if (person)
+                        counts.set(person, (counts.get(person) ?? 0) + 1);
+                const add = [];
+                for (const kp of verified) {
+                    const n = counts.get(kp.serverUserId) ?? 0;
+                    if (tree.has(kp.deviceId) || n >= MLS_MAX_DEVICES_PER_PERSON)
+                        continue;
+                    counts.set(kp.serverUserId, n + 1);
+                    add.push(kp);
+                }
+                if (add.length === 0)
+                    return null;
+                try {
+                    const c = await addMlsMembers(s, add.map((k) => k.keyPackage));
+                    addedPeer ||= add.some((k) => k.serverUserId === peer);
+                    return c;
+                }
+                catch {
+                    asking.push(...add.map((k) => ({ serverUserId: k.serverUserId, deviceId: k.deviceId })));
+                    return null;
+                }
+            });
+        }
+        if (addedPeer)
+            await markSeen(peer);
+    }
+    /** The certificate names the device the server said, under the person key pinned for that member. */
+    async function vouchedFor(conversationId, kp, peer) {
+        if (kp.serverUserId !== self && kp.serverUserId !== peer)
+            return "refused";
+        let certificate;
+        try {
+            ({ certificate } = await readMlsKeyPackage(kp.keyPackage, scope));
+        }
+        catch {
+            return "unreadable";
+        }
+        if (certificate.deviceId !== kp.deviceId)
+            return "refused";
+        return (await pins.personOf(conversationId, certificate.personPublicKey)) === kp.serverUserId ? "ok" : "refused";
+    }
+    // ── Opening and joining ─────────────────────────────────────────────
+    /** "open" when this device has the group, "exists" when somebody else made it first. */
+    async function openGroup(conversationId) {
+        if (await store.loadGroup(conversationId))
+            return "open";
+        const d = await ownDevice();
+        const state = await createMlsGroup(d, trustFor(conversationId));
+        const rec = {
+            conversationId,
+            groupId: groupIdOf(state),
+            state: encodeMlsGroupState(state),
+            cursor: 0,
+            joinedEpoch: 0,
+        };
+        // Saved before the server hears of it, so a crash can't leave a group nobody holds.
+        await store.saveGroup(rec);
+        const r = await transport.createGroup({ conversationId, groupId: rec.groupId });
+        if (r.ok)
+            return "open";
+        await store.deleteGroup(conversationId);
+        if (r.error === "group_exists")
+            return "exists";
+        throw refused("Creating the group", r);
+    }
+    function waitForWelcome(conversationId) {
+        return new Promise((resolve, reject) => {
+            const done = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                const list = welcomeWaiters.get(conversationId) ?? [];
+                welcomeWaiters.set(conversationId, list.filter((w) => w !== done));
+                reject(new MlsDriverError("waiting_for_welcome", "The group exists and this device hasn't been added yet."));
+            }, WELCOME_WAIT_MS);
+            welcomeWaiters.set(conversationId, [...(welcomeWaiters.get(conversationId) ?? []), done]);
+        });
+    }
+    async function ensureOpen(conversationId) {
+        if ((await run(conversationId, () => openGroup(conversationId))) === "open")
+            return;
+        await takeWaitingWelcomes();
+        if (!(await store.loadGroup(conversationId)))
+            await waitForWelcome(conversationId);
+    }
+    /** "joined", "not_ours" (ack it and forget it), or "retry" (keep it for next time). */
+    async function joinFrom(w) {
+        const conversationId = w.conversationId;
+        if (!conversationId)
+            return { result: "not_ours" };
+        let kp = null;
+        try {
+            for (const ref of mlsWelcomeRefs(w.data))
+                if ((kp = await store.getKeyPackage(ref)))
+                    break;
+        }
+        catch {
+            return { result: "not_ours" };
+        }
+        if (!kp)
+            return { result: "not_ours" };
+        const existing = await store.loadGroup(conversationId);
+        if (existing && existing.groupId === w.groupId)
+            return { result: "not_ours" };
+        let state;
+        try {
+            state = await joinMlsGroup(w.data, kp.keyPackage, kp.privatePackage, trustFor(conversationId));
+        }
+        catch {
+            return { result: "retry" };
+        }
+        const people = new Set(await peopleIn(conversationId, state));
+        if (groupIdOf(state) !== w.groupId || people.has(null) || people.size > 2 || !people.has(self)) {
+            return { result: "not_ours" };
+        }
+        const open = {
+            rec: { conversationId, groupId: w.groupId, state: new Uint8Array(), cursor: 0, joinedEpoch: epochOf(state) },
+            state,
+        };
+        await save(open);
+        if (!kp.lastResort)
+            await store.deleteKeyPackage(kp.ref);
+        await notePeople(conversationId, state);
+        await catchUp(open);
+        return { result: "joined", usedLastResort: kp.lastResort };
+    }
+    /** "retry" when it's kept for later, else whether it used a last-resort package. */
+    async function takeWelcome(w) {
+        const d = await ownDevice();
+        if (w.deviceId !== d.deviceId || !w.conversationId)
+            return "retry";
+        const conversationId = w.conversationId;
+        const { result, usedLastResort } = await run(conversationId, () => joinFrom(w));
+        if (result === "retry")
+            return "retry";
+        await transport.ackWelcomes({ deviceId: d.deviceId, welcomeIds: [w.welcomeId] });
+        if (result !== "joined")
+            return "done";
+        reconciled.delete(conversationId);
+        events.onJoined?.({ conversationId, groupId: w.groupId });
+        for (const done of welcomeWaiters.get(conversationId) ?? [])
+            done();
+        welcomeWaiters.delete(conversationId);
+        return usedLastResort ? "used_last_resort" : "done";
+    }
+    async function handleWelcome(w) {
+        // One package was used up, and a used last-resort one gets replaced.
+        const outcome = await takeWelcome(w);
+        if (outcome !== "retry")
+            await syncAndTopUp(outcome === "used_last_resort");
+    }
+    /* Sync until nothing waiting can be acted on: a server may hand out ten Welcomes a time,
+       and each one taken is acked, so the next sync brings the rest (GRYT-1528). */
+    async function takeWaitingWelcomes() {
+        let lastResortUsed = false;
+        for (let round = 0; round < 20; round++) {
+            const welcomes = await syncAndTopUp(lastResortUsed);
+            lastResortUsed = false;
+            let taken = 0;
+            for (const w of welcomes) {
+                const outcome = await takeWelcome(w);
+                if (outcome !== "retry")
+                    taken += 1;
+                if (outcome === "used_last_resort")
+                    lastResortUsed = true;
+            }
+            if (taken === 0)
+                return;
+        }
+    }
+    // ── What the app calls ──────────────────────────────────────────────
+    async function send(conversationId, peer, plaintext, options = {}) {
+        const attachmentIds = options.attachmentIds?.length ? [...options.attachmentIds] : undefined;
+        if (attachmentIds && attachmentIds.length > MAX_ATTACHMENT_IDS) {
+            throw new MlsDriverError("too_many_attachments", `At most ${MAX_ATTACHMENT_IDS} files go with one message.`);
+        }
+        if (!registered)
+            throw new MlsDriverError("no_device", "This device isn't registered for MLS here. Call start() first.");
+        await ensureOpen(conversationId);
+        return run(conversationId, async () => {
+            const d = await ownDevice();
+            const open = await load(conversationId);
+            if (!open || !(await catchUp(open)))
+                throw new MlsDriverError("not_in_group", "This device isn't in that group.");
+            if (!reconciled.has(conversationId))
+                await reconcile(open, peer, true);
+            const people = await peopleIn(conversationId, open.state);
+            if (people.some((p) => p !== self && p !== peer)) {
+                throw new MlsDriverError("unexpected_member", "Somebody other than the two of you is in this group.");
+            }
+            if (!people.includes(peer)) {
+                throw new MlsDriverError("peer_unverified", "None of their devices could be added. Is their person key pinned?");
+            }
+            reconciled.add(conversationId);
+            const out = await encryptMlsMessage(open.state, plaintext);
+            open.state = out.state;
+            // The generation is used up whether or not the send arrives, so the state is saved first.
+            await save(open);
+            const r = await transport.send({ conversationId, deviceId: d.deviceId, message: out.message, attachmentIds });
+            if (!r.ok)
+                throw refused("Sending", r);
+            return { seq: r.seq };
+        });
+    }
+    async function modeFor(conversationId, peer) {
+        const wasSeen = seen.has(peer) || (await pins.seenOnMls(peer));
+        if (wasSeen)
+            seen.add(peer);
+        if (!capability) {
+            return wasSeen ? { kind: "refused", reason: "server_dropped_mls" } : { kind: "sealed-v1", reason: "server_without_mls" };
+        }
+        let peerOnMls = !!(await store.loadGroup(conversationId));
+        if (!peerOnMls) {
+            const r = await transport.listDevices({ conversationId });
+            if (!r.ok)
+                throw refused("Listing devices", r);
+            peerOnMls = r.devices.some((x) => x.serverUserId === peer);
+        }
+        if (!peerOnMls) {
+            return wasSeen ? { kind: "refused", reason: "peer_left_mls" } : { kind: "sealed-v1", reason: "peer_without_mls" };
+        }
+        await markSeen(peer);
+        return registered ? { kind: "mls" } : { kind: "refused", reason: "no_own_device" };
+    }
+    async function handleMessage(entry) {
+        await run(entry.conversationId, async () => {
+            const open = await load(entry.conversationId);
+            if (!open || entry.seq <= open.rec.cursor)
+                return;
+            if (entry.seq === open.rec.cursor + 1 && entry.groupId === open.rec.groupId)
+                await applyEntry(open, entry);
+            else
+                await catchUp(open);
+        });
+    }
+    /** Adds wait for the next send; a device that's gone is removed straight away. */
+    async function handleDevicesChanged(push) {
+        reconciled.clear();
+        for (const rec of await store.listGroups()) {
+            await run(rec.conversationId, async () => {
+                const open = await load(rec.conversationId);
+                if (!open)
+                    return;
+                const people = await peopleIn(rec.conversationId, open.state);
+                const peer = people.find((p) => !!p && p !== self);
+                if (!peer || (push.serverUserId !== self && push.serverUserId !== peer))
+                    return;
+                if (await catchUp(open))
+                    await reconcile(open, peer, false);
+            });
+        }
+    }
+    return {
+        async start() {
+            await ownDevice();
+            if (!capability)
+                return;
+            await takeWaitingWelcomes();
+            reconciled.clear();
+            for (const rec of await store.listGroups()) {
+                await run(rec.conversationId, async () => {
+                    const open = await load(rec.conversationId);
+                    if (open)
+                        await catchUp(open);
+                });
+            }
+        },
+        modeFor,
+        send,
+        handleMessage,
+        handleWelcome,
+        handleDevicesChanged,
+        async ownDevices() {
+            const r = await transport.listDevices({});
+            if (!r.ok)
+                throw refused("Listing devices", r);
+            return r.devices;
+        },
+        async removeOwnDevice(deviceId) {
+            const r = await transport.removeDevice({ deviceId });
+            if (!r.ok)
+                throw refused("Removing the device", r);
+            await handleDevicesChanged({ serverUserId: self });
+        },
+    };
+}

package/dist/mls/interfaces.d.ts

@@ -0,0 +1,278 @@
+import type { TrustPersonKey } from "@gryt/crypto";
+/** A refusal, exactly as the server's ack sends it. Extra fields ride along. */
+export interface MlsRefusal {
+    ok: false;
+    error: string;
+    message: string;
+    [extra: string]: unknown;
+}
+export type MlsReply<T> = ({
+    ok: true;
+} & T) | MlsRefusal;
+export interface MlsDeviceRef {
+    serverUserId: string;
+    deviceId: string;
+}
+/** The server's view of a group. `groupId` is lower-case hex. */
+export interface MlsGroupView {
+    conversationId: string;
+    groupId: string;
+    epoch: number;
+    headSeq: number;
+}
+/** One entry of a group's log, from `mls:log:fetch` or the `mls:message` push. */
+export interface MlsLogEntry {
+    conversationId: string;
+    groupId: string;
+    seq: number;
+    kind: "commit" | "proposal" | "application";
+    epoch: number;
+    senderServerUserId: string;
+    senderDeviceId: string;
+    data: Uint8Array;
+    createdAt: string;
+}
+/** A Welcome, from `mls:sync` or the `mls:welcome` push. Pushes go to every device of a person. */
+export interface MlsWelcomeDelivery {
+    welcomeId: string;
+    conversationId: string | null;
+    groupId: string;
+    deviceId: string;
+    data: Uint8Array;
+    createdAt: string;
+}
+export interface MlsClaimedKeyPackage extends MlsDeviceRef {
+    keyPackage: Uint8Array;
+    lastResort: boolean;
+}
+/**
+ * One method per mls:* request. The app adds `accessToken`, emits, and resolves with the ack,
+ * turning ArrayBuffers into Uint8Arrays. Pushes go to the driver's `handle*` methods instead.
+ */
+export interface MlsTransport {
+    publishKeyPackages(req: {
+        deviceId: string;
+        keyPackages: Uint8Array[];
+        lastResort?: Uint8Array;
+    }): Promise<MlsReply<{
+        stored: number;
+        unclaimed: number;
+        lastResort: boolean;
+    }>>;
+    claimKeyPackages(req: {
+        conversationId: string;
+        deviceId: string;
+        devices?: MlsDeviceRef[];
+    }): Promise<MlsReply<{
+        keyPackages: MlsClaimedKeyPackage[];
+        missing: MlsDeviceRef[];
+    }>>;
+    /** Your own devices with no conversation, or every member's with one. */
+    listDevices(req: {
+        conversationId?: string;
+    }): Promise<MlsReply<{
+        devices: MlsDeviceRef[];
+    }>>;
+    removeDevice(req: {
+        deviceId: string;
+    }): Promise<MlsReply<object>>;
+    /** The loser gets `error: "group_exists"` with the winner's `group`. */
+    createGroup(req: {
+        conversationId: string;
+        groupId: string;
+    }): Promise<MlsReply<{
+        group: MlsGroupView;
+    }>>;
+    /** `error: "stale_epoch"` carries `epoch` and `headSeq`. */
+    commit(req: {
+        conversationId: string;
+        deviceId: string;
+        commit: Uint8Array;
+        welcome?: Uint8Array;
+    }): Promise<MlsReply<{
+        seq: number;
+        epoch: number;
+    }>>;
+    /** `attachmentIds` are the uploads the message carries, so the server can tie them to it. */
+    send(req: {
+        conversationId: string;
+        deviceId: string;
+        message: Uint8Array;
+        attachmentIds?: string[];
+    }): Promise<MlsReply<{
+        seq: number;
+    }>>;
+    fetchLog(req: {
+        conversationId: string;
+        after: number;
+        limit?: number;
+    }): Promise<MlsReply<{
+        group: MlsGroupView | null;
+        entries: MlsLogEntry[];
+        nextCursor: number;
+        hasMore: boolean;
+        gap: boolean;
+    }>>;
+    sync(req: {
+        deviceId: string;
+    }): Promise<MlsReply<{
+        registered: boolean;
+        groups: (MlsGroupView & {
+            oldestSeq: number | null;
+        })[];
+        welcomes: MlsWelcomeDelivery[];
+        keyPackages: {
+            unclaimed: number;
+            lastResort: boolean;
+            target: number;
+        };
+    }>>;
+    ackWelcomes(req: {
+        deviceId: string;
+        welcomeIds: string[];
+    }): Promise<MlsReply<{
+        deleted: number;
+    }>>;
+}
+/** `server:info.mls`. Absent means the server can't do MLS. */
+export interface MlsServerCapability {
+    version: number;
+    ciphersuites: number[];
+    retentionDays: number;
+}
+/** This device's leaf key and certificate, from `createMlsDevice` in @gryt/crypto. */
+export interface MlsDeviceRecord {
+    deviceId: string;
+    signKey: Uint8Array;
+    publicKey: Uint8Array;
+    certificate: Uint8Array;
+}
+/** The private half of a published KeyPackage, found again by the ref a Welcome names. */
+export interface MlsKeyPackageRecord {
+    ref: string;
+    keyPackage: Uint8Array;
+    privatePackage: Uint8Array;
+    lastResort: boolean;
+    /** Milliseconds. */
+    createdAt: number;
+    /** Seconds, from `generateMlsKeyPackage`. Absent on records written before 0.7.0. */
+    expiresAt?: number;
+}
+/**
+ * One group. `state` and `cursor` are always written together (design, section 2).
+ * `pending` is a commit sent but not yet seen accepted, so a crash can't strand it.
+ */
+export interface MlsGroupRecord {
+    conversationId: string;
+    groupId: string;
+    state: Uint8Array;
+    cursor: number;
+    /** Entries from before this epoch were never meant for this device. */
+    joinedEpoch: number;
+    pending?: {
+        commit: Uint8Array;
+        state: Uint8Array;
+    };
+}
+/**
+ * One store per server. Keep it out of OS backups: restored MLS state is out of sync. On the
+ * web, only the tab holding the Web Lock may write.
+ */
+export interface MlsStateStore {
+    loadDevice(): Promise<MlsDeviceRecord | null>;
+    saveDevice(device: MlsDeviceRecord): Promise<void>;
+    putKeyPackages(records: MlsKeyPackageRecord[]): Promise<void>;
+    getKeyPackage(ref: string): Promise<MlsKeyPackageRecord | null>;
+    listKeyPackages(): Promise<MlsKeyPackageRecord[]>;
+    deleteKeyPackage(ref: string): Promise<void>;
+    loadGroup(conversationId: string): Promise<MlsGroupRecord | null>;
+    listGroups(): Promise<MlsGroupRecord[]>;
+    saveGroup(record: MlsGroupRecord): Promise<void>;
+    deleteGroup(conversationId: string): Promise<void>;
+}
+/**
+ * The person-key pin (design, section 1). The app verifies each member's person key binding
+ * and pins it on first sight, before the driver meets their leaves; the driver only asks.
+ */
+export interface MlsPins {
+    /** Which member of this conversation holds this person key by pin, you included, or null. */
+    personOf(conversationId: string, personPublicKey: Uint8Array): string | null | Promise<string | null>;
+    /** The engine's check for every leaf. Without it, any leaf `personOf` names passes. */
+    trustFor?(conversationId: string): TrustPersonKey;
+    /** Decision 4: once a peer is seen on MLS, never seal to them with version 1 again. */
+    seenOnMls(serverUserId: string): boolean | Promise<boolean>;
+    markSeenOnMls(serverUserId: string): void | Promise<void>;
+}
+export interface MlsDecryptedMessage {
+    conversationId: string;
+    seq: number;
+    senderServerUserId: string;
+    senderDeviceId: string;
+    plaintext: Uint8Array;
+    createdAt: string;
+}
+/**
+ * `onMessage` must have stored the message before it resolves: the key is gone once the
+ * cursor moves. It may see the same seq twice after a crash.
+ */
+export interface MlsDmEvents {
+    onMessage(message: MlsDecryptedMessage): void | Promise<void>;
+    /** "Some messages couldn't be decrypted on this device" (design, section 2). */
+    onUndecryptable?(info: {
+        conversationId: string;
+        seq: number;
+        reason: string;
+    }): void;
+    /** This device is out of the group: removed, or its state couldn't keep up. */
+    onGroupLost?(info: {
+        conversationId: string;
+        reason: "removed" | "out_of_sync" | "gap";
+    }): void;
+    onJoined?(info: {
+        conversationId: string;
+        groupId: string;
+    }): void;
+}
+/** Decision 4, per DM. `refused` never falls back to version 1. */
+export type DmSealingMode = {
+    kind: "mls";
+} | {
+    kind: "sealed-v1";
+    reason: "server_without_mls" | "peer_without_mls";
+} | {
+    kind: "refused";
+    reason: "peer_left_mls" | "server_dropped_mls" | "no_own_device";
+};
+export interface MlsDmDriverOptions {
+    transport: MlsTransport;
+    store: MlsStateStore;
+    pins: MlsPins;
+    events: MlsDmEvents;
+    /** The identity scope this server's keys are derived under. */
+    scope: string;
+    serverUserId: string;
+    /** `server:info.mls`, or null when the server doesn't advertise it. */
+    capability: MlsServerCapability | null;
+    /** The first time only: `createMlsDevice` from @gryt/crypto, so the seed stays in the app. */
+    newDevice(): MlsDeviceRecord | Promise<MlsDeviceRecord>;
+}
+/** One per server. Calls for one conversation run one at a time, in order. */
+export interface MlsDmDriver {
+    /** On connect: register, top up KeyPackages, take waiting Welcomes, catch up every group. */
+    start(): Promise<void>;
+    modeFor(conversationId: string, peerServerUserId: string): Promise<DmSealingMode>;
+    /** Opens the group if need be, adds or removes devices that changed, then sends. */
+    send(conversationId: string, peerServerUserId: string, plaintext: Uint8Array, options?: {
+        attachmentIds?: readonly string[];
+    }): Promise<{
+        seq: number;
+    }>;
+    handleMessage(entry: MlsLogEntry): Promise<void>;
+    handleWelcome(welcome: MlsWelcomeDelivery): Promise<void>;
+    handleDevicesChanged(push: {
+        serverUserId: string;
+    }): Promise<void>;
+    ownDevices(): Promise<MlsDeviceRef[]>;
+    /** Your own devices only. Every group you share drops it on the next pass. */
+    removeOwnDevice(deviceId: string): Promise<void>;
+}

package/dist/mls/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/mls/pins.d.ts

@@ -0,0 +1,21 @@
+import { type PeerPinStore } from "@gryt/crypto";
+import type { MlsPins } from "./interfaces.js";
+/**
+ * `MlsPins` over the peer pins @gryt/crypto keeps, person keys included. The app still pins
+ * with `evaluateMemberKeys`, passing each member's `personKeyBinding`, before the driver asks.
+ */
+export declare function mlsPinsFromPeerPins({ store, scope, serverUserId, ownPersonKey, membersOf, seen, }: {
+    store: PeerPinStore;
+    scope: string;
+    /** Yours on this server. Your own person key answers as you. */
+    serverUserId: string;
+    /** The public half of `derivePersonKeyPair(seed, scope)`. */
+    ownPersonKey: Uint8Array;
+    /** Everybody in the conversation. Anybody else's person key is refused there. */
+    membersOf(conversationId: string): readonly string[] | Promise<readonly string[]>;
+    /** Decision 4's record, kept by the app: a peer pin has no field for it yet. */
+    seen: {
+        has(serverUserId: string): boolean | Promise<boolean>;
+        add(serverUserId: string): void | Promise<void>;
+    };
+}): MlsPins;

package/dist/mls/pins.js

@@ -0,0 +1,26 @@
+import { asIdentityScope, base64Url, getPeerPin, trustPinnedPersonKeys } from "@gryt/crypto";
+/**
+ * `MlsPins` over the peer pins @gryt/crypto keeps, person keys included. The app still pins
+ * with `evaluateMemberKeys`, passing each member's `personKeyBinding`, before the driver asks.
+ */
+export function mlsPinsFromPeerPins({ store, scope, serverUserId, ownPersonKey, membersOf, seen, }) {
+    const identityScope = asIdentityScope(scope);
+    const own = base64Url(ownPersonKey);
+    return {
+        async personOf(conversationId, personPublicKey) {
+            const presented = base64Url(personPublicKey);
+            if (presented === own)
+                return serverUserId;
+            const members = await membersOf(conversationId);
+            return members.find((id) => id !== serverUserId && getPeerPin(store, identityScope, id)?.personPublicKey === presented) ?? null;
+        },
+        trustFor(conversationId) {
+            return async (certificate) => {
+                const memberIds = await membersOf(conversationId);
+                return trustPinnedPersonKeys({ store, scope: identityScope, memberIds, ownPersonKey })(certificate);
+            };
+        },
+        seenOnMls: (id) => seen.has(id),
+        markSeenOnMls: (id) => seen.add(id),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Gryt's shared application logic: one implementation of the things the desktop and mobile apps both do.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -33,5 +33,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@gryt/crypto": "0.7.0"
   }
 }