@gryt/core 0.13.0 → 0.15.0

package/dist/mls/dmDriver.js

@@ -9,6 +9,10 @@ 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 same cap as a message that isn't MLS: after this a send fails and the text goes back. */
+const SEND_GIVE_UP_MS = 5 * 60_000;
+/** A send with no answer goes again after this, or sooner if the connection comes back. */
+const RESEND_AFTER_MS = 2_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;
@@ -26,6 +30,11 @@ export class MlsDriverError extends Error {
 function refused(what, r) {
     return new MlsDriverError("refused", `${what}: ${r.error} (${r.message})`, r);
 }
+/** A refusal that says nothing about the request, only that the server couldn't be reached. */
+function unreachable(r) {
+    const error = r instanceof MlsDriverError ? r.refusal?.error : r?.error;
+    return error === "offline" || error === "timeout" ? error : null;
+}
 function toHex(bytes) {
     return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -107,6 +116,35 @@ export function createMlsDmDriver(options) {
     const reconciled = new Set();
     const seen = new Set();
     const welcomeWaiters = new Map();
+    const flights = new Set();
+    let waitingForServer = false;
+    let stopped = false;
+    const paused = new Set();
+    const giveUpMs = options.sendGiveUpMs ?? SEND_GIVE_UP_MS;
+    function setWaiting(next) {
+        if (waitingForServer === next)
+            return;
+        waitingForServer = next;
+        events.onWaiting?.(next);
+    }
+    /** Until `start()` has caught up again, or `ms`. Fails at the deadline or on `stop()`. */
+    function pause(deadline, ms) {
+        return new Promise((resolve, reject) => {
+            const left = deadline - Date.now();
+            if (stopped || left <= 0)
+                return reject(stopped ? stoppedError() : gaveUpError());
+            const done = (then) => {
+                clearTimeout(timer);
+                paused.delete(entry);
+                then();
+            };
+            const entry = { resume: () => done(resolve), fail: (e) => done(() => reject(e)) };
+            const timer = setTimeout(() => (Date.now() >= deadline ? entry.fail(gaveUpError()) : entry.resume()), Math.min(left, ms));
+            paused.add(entry);
+        });
+    }
+    const gaveUpError = () => new MlsDriverError("offline", "The server didn't answer in time, so the message wasn't sent.");
+    const stoppedError = () => new MlsDriverError("stopped", "This connection has closed.");
     async function ownDevice() {
         if (device)
             return device;
@@ -138,6 +176,20 @@ export function createMlsDmDriver(options) {
         open.rec = { ...open.rec, state: encodeMlsGroupState(open.state), cursor };
         await store.saveGroup(open.rec);
     }
+    /** Where each device went into each group, as this driver saw it happen. Memory only. */
+    const joins = new Map();
+    function noteJoins(conversationId, before, after, seq, byThisDevice) {
+        if (before === after)
+            return;
+        const had = new Set(mlsGroupMembers(before, scope).map((m) => m.certificate.deviceId));
+        const here = joins.get(conversationId) ?? new Map();
+        for (const { certificate } of mlsGroupMembers(after, scope)) {
+            if (!had.has(certificate.deviceId))
+                here.set(certificate.deviceId, { seq, epoch: epochOf(after), byThisDevice });
+        }
+        if (here.size)
+            joins.set(conversationId, here);
+    }
     async function load(conversationId) {
         const rec = await store.loadGroup(conversationId);
         return rec ? { rec, state: decodeMlsGroupState(rec.state, trustFor(conversationId)) } : null;
@@ -200,6 +252,7 @@ export function createMlsDmDriver(options) {
         const d = await ownDevice();
         const current = epochOf(open.state);
         if (e.kind === "commit") {
+            const before = open.state;
             const pending = open.rec.pending;
             if (pending && sameBytes(pending.commit, e.data)) {
                 open.state = decodeMlsGroupState(pending.state, trustFor(open.rec.conversationId));
@@ -227,6 +280,7 @@ export function createMlsDmDriver(options) {
                 }
             }
             open.rec = { ...open.rec, pending: undefined };
+            noteJoins(open.rec.conversationId, before, open.state, e.seq, !!pending && sameBytes(pending.commit, e.data));
             await notePeople(open.rec.conversationId, open.state);
         }
         else if (e.kind === "proposal") {
@@ -239,7 +293,14 @@ export function createMlsDmDriver(options) {
                 }
             }
         }
-        else if (!(e.senderServerUserId === self && e.senderDeviceId === d.deviceId) && e.epoch >= open.rec.joinedEpoch) {
+        else if (e.senderServerUserId === self && e.senderDeviceId === d.deviceId) {
+            // A send whose answer never came: the log says it landed, so it isn't sent again.
+            for (const f of flights) {
+                if (f.conversationId === open.rec.conversationId && f.seq === null && f.message && sameBytes(f.message, e.data))
+                    f.seq = e.seq;
+            }
+        }
+        else if (e.epoch >= open.rec.joinedEpoch) {
             let plaintext = null;
             try {
                 const r = await processMlsMessage(open.state, e.data);
@@ -255,6 +316,7 @@ export function createMlsDmDriver(options) {
                 await events.onMessage({
                     conversationId: open.rec.conversationId,
                     seq: e.seq,
+                    epoch: e.epoch,
                     senderServerUserId: e.senderServerUserId,
                     senderDeviceId: e.senderDeviceId,
                     plaintext,
@@ -305,6 +367,7 @@ export function createMlsDmDriver(options) {
                 welcome: c.welcome,
             });
             if (r.ok) {
+                noteJoins(open.rec.conversationId, open.state, c.state, r.seq, true);
                 open.state = c.state;
                 forgetMlsSecrets(c.consumed);
                 open.rec = { ...open.rec, pending: undefined };
@@ -551,12 +614,50 @@ export function createMlsDmDriver(options) {
         }
         if (!registered)
             throw new MlsDriverError("no_device", "This device isn't registered for MLS here. Call start() first.");
-        await ensureOpen(conversationId);
+        if (stopped)
+            throw stoppedError();
+        const deadline = Date.now() + giveUpMs;
+        const flight = { conversationId, message: null, seq: null };
+        flights.add(flight);
+        try {
+            for (;;) {
+                try {
+                    return await sendOnce(flight, peer, plaintext, attachmentIds);
+                }
+                catch (e) {
+                    const why = unreachable(e);
+                    if (!why || stopped)
+                        throw e;
+                    // Offline waits for the next start(). A timeout goes again soon, as the same bytes.
+                    if (why === "offline")
+                        setWaiting(true);
+                    await pause(deadline, why === "offline" ? Infinity : RESEND_AFTER_MS);
+                }
+            }
+        }
+        finally {
+            flights.delete(flight);
+        }
+    }
+    /* Encrypted at most once, and only once the group is caught up. Every later attempt sends
+       the same bytes, which the server takes as a repeat rather than a second message. */
+    async function sendOnce(flight, peer, plaintext, attachmentIds) {
+        const { conversationId } = flight;
+        if (!flight.message)
+            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 (flight.seq !== null)
+                return { seq: flight.seq };
+            if (flight.message) {
+                const r = await transport.send({ conversationId, deviceId: d.deviceId, message: flight.message, attachmentIds });
+                if (!r.ok)
+                    throw refused("Sending", r);
+                return { seq: r.seq };
+            }
             if (!reconciled.has(conversationId))
                 await reconcile(open, peer, true);
             const people = await peopleIn(conversationId, open.state);
@@ -571,6 +672,7 @@ export function createMlsDmDriver(options) {
             open.state = out.state;
             // The generation is used up whether or not the send arrives, so the state is saved first.
             await save(open);
+            flight.message = out.message;
             const r = await transport.send({ conversationId, deviceId: d.deviceId, message: out.message, attachmentIds });
             if (!r.ok)
                 throw refused("Sending", r);
@@ -667,6 +769,113 @@ export function createMlsDmDriver(options) {
             thisDevice: x.deviceId === d.deviceId,
         }));
     }
+    // ── Pairing ─────────────────────────────────────────────────────────
+    async function groupPositions() {
+        const out = [];
+        for (const rec of await store.listGroups()) {
+            const pos = await run(rec.conversationId, async () => {
+                const open = await load(rec.conversationId);
+                return open && { conversationId: open.rec.conversationId, groupId: open.rec.groupId, seq: open.rec.cursor, epoch: epochOf(open.state) };
+            });
+            if (pos)
+                out.push(pos);
+        }
+        return out;
+    }
+    /** A claimed package for `deviceId`, checked to be yours under your own person key. Null when the server has none. */
+    async function claimOwn(conversationId, deviceId, ownPersonKey) {
+        const d = await ownDevice();
+        // One more claim when the first package won't read, as with a peer's.
+        for (let round = 0; round < 2; round++) {
+            const claim = await transport.claimKeyPackages({ conversationId, deviceId: d.deviceId, devices: [{ serverUserId: self, deviceId }] });
+            if (!claim.ok)
+                throw refused("Claiming KeyPackages", claim);
+            const kp = claim.keyPackages.find((k) => k.serverUserId === self && k.deviceId === deviceId);
+            if (!kp)
+                return null;
+            let certificate;
+            try {
+                ({ certificate } = await readMlsKeyPackage(kp.keyPackage, scope));
+            }
+            catch {
+                continue;
+            }
+            if (certificate.deviceId !== deviceId || !sameBytes(certificate.personPublicKey, ownPersonKey)) {
+                throw new MlsDriverError("not_own_device", "That device's certificate isn't signed by your person key.");
+            }
+            return kp.keyPackage;
+        }
+        return null;
+    }
+    async function addOwnDeviceTo(conversationId, deviceId, ownPersonKey) {
+        const open = await load(conversationId);
+        const result = (outcome, error) => {
+            const j = joins.get(conversationId)?.get(deviceId);
+            const add = outcome === "failed" || !j ? null : { seq: j.seq, epoch: j.epoch };
+            return { conversationId, groupId: open?.rec.groupId ?? "", outcome, add, ...(error ? { error } : {}) };
+        };
+        if (!open || !(await catchUp(open)))
+            return result("failed", "not_in_group");
+        const inTree = (s) => mlsGroupMembers(s, scope).some((m) => m.certificate.deviceId === deviceId);
+        const settled = () => result(joins.get(conversationId)?.get(deviceId)?.byThisDevice ? "added" : "added_by_other");
+        if (inTree(open.state))
+            return settled();
+        let full = false;
+        for (let round = 0; round < 2 && !inTree(open.state); round++) {
+            const keyPackage = await claimOwn(conversationId, deviceId, ownPersonKey);
+            if (!keyPackage)
+                return result("failed", "no_key_package");
+            let stale = false;
+            await commitWithRetry(open, async (s) => {
+                if (inTree(s))
+                    return null;
+                const mine = mlsGroupMembers(s, scope).filter((m) => sameBytes(m.certificate.personPublicKey, ownPersonKey));
+                if ((full = mine.length >= MLS_MAX_DEVICES_PER_PERSON))
+                    return null;
+                try {
+                    return await addMlsMembers(s, [keyPackage]);
+                }
+                catch {
+                    stale = true;
+                    return null;
+                }
+            });
+            if (!stale)
+                break;
+        }
+        if (inTree(open.state))
+            return settled();
+        return result("failed", full ? "too_many_devices" : "no_key_package");
+    }
+    async function addOwnDevice(deviceId, options = {}) {
+        const d = await ownDevice();
+        const listed = await transport.listDevices({});
+        if (!listed.ok)
+            throw refused("Listing devices", listed);
+        if (deviceId === d.deviceId || !listed.devices.some((x) => x.serverUserId === self && x.deviceId === deviceId)) {
+            throw new MlsDriverError("not_own_device", "The server doesn't list that device as one of yours.");
+        }
+        const ownPersonKey = readDeviceCertificate(d.certificate, scope).personPublicKey;
+        const ids = (await store.listGroups()).map((r) => r.conversationId);
+        const first = (options.order ?? []).filter((id) => ids.includes(id));
+        const ordered = [...new Set([...first, ...ids])];
+        const results = [];
+        for (const conversationId of ordered) {
+            let result;
+            try {
+                result = await run(conversationId, () => addOwnDeviceTo(conversationId, deviceId, ownPersonKey));
+            }
+            catch (e) {
+                if (e instanceof MlsDriverError && e.code === "not_own_device")
+                    throw e;
+                const groupId = (await store.loadGroup(conversationId))?.groupId ?? "";
+                result = { conversationId, groupId, outcome: "failed", add: null, error: e instanceof MlsDriverError ? e.code : "error" };
+            }
+            results.push(result);
+            options.onProgress?.({ done: results.length, total: ordered.length, result });
+        }
+        return results;
+    }
     return {
         async start() {
             await ownDevice();
@@ -681,6 +890,15 @@ export function createMlsDmDriver(options) {
                         await catchUp(open);
                 });
             }
+            // Caught up, so the sends that waited go now, on top of that.
+            setWaiting(false);
+            for (const p of [...paused])
+                p.resume();
+        },
+        stop() {
+            stopped = true;
+            for (const p of [...paused])
+                p.fail(stoppedError());
         },
         modeFor,
         send,
@@ -694,5 +912,7 @@ export function createMlsDmDriver(options) {
                 throw refused("Removing the device", r);
             await handleDevicesChanged({ serverUserId: self });
         },
+        groupPositions,
+        addOwnDevice,
     };
 }

package/dist/mls/interfaces.d.ts

@@ -51,8 +51,8 @@ export interface MlsClaimedKeyPackage extends MlsDeviceRef {
     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.
+ * One method per mls:* request: add `accessToken`, emit, resolve with the ack. Pushes go to `handle*`.
+ * Disconnected, answer `offline` without emitting; with no ack in time, answer `timeout`.
  */
 export interface MlsTransport {
     publishKeyPackages(req: {
@@ -211,6 +211,8 @@ export interface MlsPins {
 export interface MlsDecryptedMessage {
     conversationId: string;
     seq: number;
+    /** The epoch it was sent in. A pairing tail wants the old-epoch ones that land after an add. */
+    epoch: number;
     senderServerUserId: string;
     senderDeviceId: string;
     plaintext: Uint8Array;
@@ -228,6 +230,8 @@ export interface MlsDmEvents {
         seq: number;
         reason: string;
     }): void;
+    /** Sends are held until the connection is back and `start()` has caught up, or not any more. */
+    onWaiting?(waiting: boolean): void;
     /** This device is out of the group: removed, or its state couldn't keep up. */
     onGroupLost?(info: {
         conversationId: string;
@@ -262,6 +266,39 @@ export interface MlsOwnDevice extends MlsDeviceRef {
     lastSeenAt: string | null;
     thisDevice: boolean;
 }
+/** A place in one group's log: a seq, and the epoch this device is in there. */
+export interface MlsGroupPosition {
+    conversationId: string;
+    groupId: string;
+    seq: number;
+    epoch: number;
+}
+/**
+ * Where one of your devices joined one group. `add` is the commit's seq and the epoch the device
+ * starts in, or null when it didn't go in, or went in before this driver was running.
+ */
+export interface MlsOwnDeviceAdd {
+    conversationId: string;
+    groupId: string;
+    /** "added_by_other" when another member's commit put it in first. */
+    outcome: "added" | "added_by_other" | "failed";
+    add: {
+        seq: number;
+        epoch: number;
+    } | null;
+    /** Why it failed: an MlsDriverError code, or "too_many_devices", "no_key_package" or "error". */
+    error?: string;
+}
+export interface MlsAddOwnDeviceOptions {
+    /** Conversation ids to do first, most recently active first. The rest follow. */
+    order?: readonly string[];
+    /** After each group, with how many are done. */
+    onProgress?(progress: {
+        done: number;
+        total: number;
+        result: MlsOwnDeviceAdd;
+    }): void;
+}
 export interface MlsDmDriverOptions {
     transport: MlsTransport;
     store: MlsStateStore;
@@ -274,13 +311,18 @@ export interface MlsDmDriverOptions {
     capability: MlsServerCapability | null;
     /** The first time only: `createMlsDevice` from @gryt/crypto, so the seed stays in the app. */
     newDevice(): MlsDeviceRecord | Promise<MlsDeviceRecord>;
+    /** How long a send waits for the server before it fails with `offline`. Five minutes. */
+    sendGiveUpMs?: number;
 }
 /** 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. */
+    /**
+     * Opens the group if need be, adds or removes devices that changed, then sends. Offline, it
+     * waits for the next `start()` and encrypts after that. It goes out once, or fails `offline`.
+     */
     send(conversationId: string, peerServerUserId: string, plaintext: Uint8Array, options?: {
         attachmentIds?: readonly string[];
     }): Promise<{
@@ -295,4 +337,13 @@ export interface MlsDmDriver {
     ownDevices(): Promise<MlsOwnDevice[]>;
     /** Your own devices only. Every group you share drops it on the next pass. */
     removeOwnDevice(deviceId: string): Promise<void>;
+    /** Pairing: each group's cursor now, which is what the history snapshot covers. */
+    groupPositions(): Promise<MlsGroupPosition[]>;
+    /**
+     * Pairing: adds one of your own new devices to every group now, and says where it went in.
+     * Throws `not_own_device` for a device the server doesn't list as yours, or not under your person key.
+     */
+    addOwnDevice(deviceId: string, options?: MlsAddOwnDeviceOptions): Promise<MlsOwnDeviceAdd[]>;
+    /** Sends still waiting fail with `stopped`, and no more are taken. For a session going away. */
+    stop(): void;
 }

package/dist/pairing/approver.d.ts

@@ -0,0 +1,71 @@
+import { type PairingEmoji, type PairingEnvelope } from "@gryt/crypto";
+import type { MlsOwnDeviceAdd } from "../mls/interfaces.js";
+import type { OwnDeviceAdder, PairingClock, PairingDeviceInfo, PairingEndReason, PairingFetch } from "./interfaces.js";
+import type { PairingRelay } from "./relayClient.js";
+export type ApproverState = {
+    phase: "idle";
+} | {
+    phase: "claiming";
+} | {
+    phase: "waiting";
+} | {
+    phase: "confirming";
+    device: PairingDeviceInfo;
+    /** Where the relay puts N, and A, from their IPs. Null when it can't say. */
+    location: string | null;
+    yourLocation: string | null;
+    emoji: readonly PairingEmoji[];
+    deadline: number;
+} | {
+    phase: "signing_in";
+    device: PairingDeviceInfo;
+}
+/** No extension on this Keycloak: the app opens `url`, Keycloak's own device page, for the same code. */
+ | {
+    phase: "browser";
+    device: PairingDeviceInfo;
+    url: string;
+} | {
+    phase: "waiting_ready";
+    device: PairingDeviceInfo;
+} | {
+    phase: "adding";
+    device: PairingDeviceInfo;
+    host: string;
+    done: number;
+    total: number;
+} | {
+    phase: "done";
+    device: PairingDeviceInfo;
+    added: Record<string, MlsOwnDeviceAdd[]>;
+} | {
+    phase: "ended";
+    reason: PairingEndReason;
+};
+export interface ApproverOptions {
+    relay: PairingRelay;
+    /** A's own relay origin. A QR naming any other is refused. */
+    relayOrigin: string;
+    /** For the extension call. */
+    fetch: PairingFetch;
+    devices: OwnDeviceAdder;
+    clock?: PairingClock;
+    approvalMs?: number;
+}
+export interface ApproverPairing {
+    readonly state: ApproverState;
+    subscribe(listener: (state: ApproverState) => void): () => void;
+    /** A scanned QR, or a typed code. */
+    claim(input: {
+        qr: string;
+    } | {
+        code: string;
+    }): void;
+    /** For an account, `accessToken` refreshes first: the extension refuses a token over 60 seconds old. */
+    approve(envelope: PairingEnvelope, accessToken?: () => Promise<string>): void;
+    deny(): Promise<void>;
+    mismatch(): Promise<void>;
+    cancel(): Promise<void>;
+}
+/** A: claims the session, shows N and the emoji, and on Approve seals the envelope, signs N in and adds it. */
+export declare function createApproverPairing(options: ApproverOptions): ApproverPairing;