@gryt/core 0.15.0 → 0.16.0

package/README.md

@@ -71,7 +71,16 @@ goes missing **and** when one appears that nobody listed.
   extension, and adds the new device to every DM. If the extension isn't there,
   it hands back Keycloak's own device page to open instead. The app passes in
   `fetch`, a clock, storage and the OIDC calls through
-  `src/pairing/interfaces.ts`. History isn't in it yet. It uses
+  `src/pairing/interfaces.ts`. When the app passes its archive, history goes
+  across too. On Approve, A notes where each group's log stands, reads the
+  archive newest day first through `HistoryArchive`, and seals and uploads it
+  in chunks. The envelope carries the history key and the first chunks, and
+  later sealed messages list the rest. After the adds, A sends the tail: what
+  it decrypted between the snapshot and each add, plus old-epoch messages that
+  land after it, which the app reports with `noteMessage`. N fetches the chunks
+  newest first, checks each against its manifest entry, and hands each message
+  to `HistorySink` once. Both sides report progress through
+  `subscribeHistory`. It uses
   `@noble/hashes` for the PKCE challenge, which `@gryt/crypto` already pulls in.
 
 ## What deliberately isn't

package/dist/index.d.ts

@@ -18,4 +18,4 @@ export type { DmSealingMode, MlsAddOwnDeviceOptions, MlsClaimedKeyPackage, MlsDe
 export { createApproverPairing, type ApproverOptions, type ApproverPairing, type ApproverState, } from "./pairing/approver.js";
 export { createNewDevicePairing, PAIRING_APPROVAL_MS, type NewDeviceOptions, type NewDevicePairing, type NewDeviceState, } from "./pairing/newDevice.js";
 export { createPairingRelay, PairingRelayError, type PairingRelay } from "./pairing/relayClient.js";
-export type { DeviceAuthorization, DeviceTokenPoll, OwnDeviceAdder, PairedServerDevice, PairingClock, PairingDeviceInfo, PairingEndReason, PairingFetch, PairingOidc, PairingStorage, PairingTokens, } from "./pairing/interfaces.js";
+export type { DeviceAuthorization, DeviceTokenPoll, HistoryArchive, HistoryConversation, HistoryCursor, HistoryNotedMessage, HistoryProgress, HistorySink, OwnDeviceAdder, PairedServerDevice, PairingClock, PairingDeviceInfo, PairingEndReason, PairingFetch, PairingOidc, PairingStorage, PairingTokens, } from "./pairing/interfaces.js";

package/dist/pairing/approver.d.ts

@@ -1,6 +1,6 @@
 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 { HistoryArchive, HistoryNotedMessage, HistoryProgress, OwnDeviceAdder, PairingClock, PairingDeviceInfo, PairingEndReason, PairingFetch } from "./interfaces.js";
 import type { PairingRelay } from "./relayClient.js";
 export type ApproverState = {
     phase: "idle";
@@ -34,6 +34,12 @@ export type ApproverState = {
     host: string;
     done: number;
     total: number;
+}
+/** N is in every conversation; the history's tail is still going. Progress is on `history`. */
+ | {
+    phase: "sending";
+    device: PairingDeviceInfo;
+    added: Record<string, MlsOwnDeviceAdd[]>;
 } | {
     phase: "done";
     device: PairingDeviceInfo;
@@ -51,10 +57,19 @@ export interface ApproverOptions {
     devices: OwnDeviceAdder;
     clock?: PairingClock;
     approvalMs?: number;
+    /** A's archive. Without it, no history goes across. */
+    history?: HistoryArchive;
+    /** How long after the adds A keeps collecting old-epoch messages for the last tail. */
+    lateWindowMs?: number;
 }
 export interface ApproverPairing {
     readonly state: ApproverState;
     subscribe(listener: (state: ApproverState) => void): () => void;
+    /** Null until Approve, or with no archive. */
+    readonly history: HistoryProgress | null;
+    subscribeHistory(listener: (progress: HistoryProgress) => void): () => void;
+    /** Every MLS message A archives while this runs, received or sent, for the tail. */
+    noteMessage(message: HistoryNotedMessage): void;
     /** A scanned QR, or a typed code. */
     claim(input: {
         qr: string;

package/dist/pairing/approver.js

@@ -1,7 +1,11 @@
 import { base64Url, base64UrlDecode, createPairingKey, decodePairingSessionId, encodePairingEnvelope, encodePairingSessionId, parsePairingCode, parsePairingQr, startApproverSession, } from "@gryt/crypto";
-import { mailbox, openJson, PairingEnded, reasonFor, systemClock } from "./channel.js";
+import { mailbox, openJson, PairingEnded, reasonFor, sealJson, systemClock } from "./channel.js";
+import { createHistorySender, createTailRecorder } from "./historySender.js";
 import { PAIRING_APPROVAL_MS } from "./newDevice.js";
 const NOT_LISTED_RETRIES = 5;
+/** How long Approve may spend sealing history before the envelope goes, so it lands in N's window. */
+const ENVELOPE_BUDGET_MS = 5_000;
+const HISTORY_LATE_WINDOW_MS = 60_000;
 /** auth#46's codes that get a named reason. Anything else it can answer still falls
     through to the generic `approve:<code>`. */
 const APPROVE_ERROR_REASONS = {
@@ -24,6 +28,15 @@ export function createApproverPairing(options) {
     let current = null;
     let device = null;
     let confirming = null;
+    let deadline = 0;
+    let history = null;
+    const historyListeners = new Set();
+    const tail = createTailRecorder();
+    const setHistory = (progress) => {
+        history = progress;
+        for (const l of historyListeners)
+            l(progress);
+    };
     const set = (next) => {
         if (state.phase === "ended" || state.phase === "done")
             return;
@@ -86,7 +99,7 @@ export function createApproverPairing(options) {
         const hello = openJson(current.session, await box.next(abort.signal, clock.now() + approvalMs), "hello");
         const text = (v) => (typeof v === "string" ? v.slice(0, 100) : "");
         device = { name: text(hello.name), app: text(hello.app), platform: text(hello.platform) };
-        const deadline = clock.now() + approvalMs;
+        deadline = clock.now() + approvalMs;
         set({ phase: "confirming", device, location: claimed.location, yourLocation: claimed.yourLocation, emoji: current.session.emoji, deadline });
         // N sends nothing more until A approves, so a message or a close here means something's off.
         confirming = new AbortController();
@@ -144,9 +157,37 @@ export function createApproverPairing(options) {
         }
         return added;
     }
+    /** Each group's cursor on every server in the envelope: the snapshot covers up to there. */
+    async function positions(envelope) {
+        const snap = new Map();
+        for (const { host } of envelope.servers) {
+            const driver = devices(host);
+            if (driver)
+                snap.set(host, new Map((await driver.groupPositions()).map((p) => [p.conversationId, p.seq])));
+        }
+        return snap;
+    }
+    function startHistory(archive) {
+        const { id, token, session } = current;
+        return createHistorySender({
+            relay, id, token, archive, clock, signal: abort.signal,
+            post: (message) => relay.post(id, token, { type: "sealed", body: sealJson(session, message) }),
+            onProgress: setHistory,
+        });
+    }
     async function approve(envelope, accessToken) {
         const { id, token, box, session } = current;
         set({ phase: envelope.account ? "signing_in" : "waiting_ready", device: device });
+        let sender = null;
+        let snap = new Map();
+        if (options.history) {
+            // Recording starts before the positions are read, so nothing lands between the two unseen.
+            tail.start();
+            snap = await positions(envelope);
+            sender = startHistory(options.history);
+            const chunks = await sender.forEnvelope(Math.min(clock.now() + ENVELOPE_BUDGET_MS, deadline - 10_000));
+            envelope = { ...envelope, history: { key: sender.key, manifest: { v: 1, chunks } } };
+        }
         await relay.post(id, token, { type: "sealed", body: base64Url(session.seal(encodePairingEnvelope(envelope))) });
         if (envelope.account && accessToken) {
             const message = await box.next(abort.signal, clock.now() + approvalMs);
@@ -163,10 +204,20 @@ export function createApproverPairing(options) {
         const ready = openJson(session, await box.next(abort.signal), "ready");
         const list = Array.isArray(ready.devices) ? ready.devices : [];
         const named = list.filter((d) => typeof d?.host === "string" && typeof d?.deviceId === "string");
+        sender?.startPaging();
         const added = await addEverywhere(named);
+        if (!sender) {
+            set({ phase: "done", device: device, added });
+            session.close();
+            return void (await closeQuietly());
+        }
+        set({ phase: "sending", device: device, added });
+        await sender.send(tail.take(snap, added), false);
+        await clock.sleep(options.lateWindowMs ?? HISTORY_LATE_WINDOW_MS, abort.signal);
+        await sender.send(tail.take(snap, added), true);
+        // N closes the session once it has every chunk; closing here would delete them.
         set({ phase: "done", device: device, added });
         session.close();
-        await closeQuietly();
     }
     return {
         get state() {
@@ -176,6 +227,14 @@ export function createApproverPairing(options) {
             listeners.add(listener);
             return () => void listeners.delete(listener);
         },
+        get history() {
+            return history;
+        },
+        subscribeHistory(listener) {
+            historyListeners.add(listener);
+            return () => void historyListeners.delete(listener);
+        },
+        noteMessage: (message) => tail.note(message),
         claim(input) {
             if (state.phase !== "idle")
                 throw new Error("This pairing has claimed a session already.");

package/dist/pairing/channel.d.ts

@@ -10,7 +10,7 @@ export declare const systemClock: PairingClock;
 export declare function reasonFor(error: unknown): PairingEndReason;
 export declare function sealJson(session: PairingSession, value: Record<string, unknown>): string;
 /** The next sealed message as JSON with a `t`, or a throw that ends the pairing as tampered. */
-export declare function openJson(session: PairingSession, message: RelayMessage | null, t: string): Record<string, unknown>;
+export declare function openJson(session: PairingSession, message: RelayMessage | null, t?: string): Record<string, unknown>;
 /** The other side's messages in order, long-polling the relay. `next` gives null once `deadline` passes. */
 export declare function mailbox(relay: PairingRelay, id: string, token: string, clock: PairingClock): {
     next(signal: AbortSignal, deadline?: number): Promise<RelayMessage | null>;

package/dist/pairing/channel.js

@@ -41,7 +41,8 @@ export function openJson(session, message, t) {
         if (message?.type !== "sealed" || !message.body)
             throw new Error();
         const value = JSON.parse(new TextDecoder().decode(session.open(base64UrlDecode(message.body))));
-        if (value && typeof value === "object" && value.t === t)
+        const got = value && typeof value === "object" ? value.t : undefined;
+        if (typeof got === "string" && (t === undefined || got === t))
             return value;
     }
     catch {

package/dist/pairing/historyReceiver.d.ts

@@ -0,0 +1,34 @@
+import { type HistoryChunkEntry } from "@gryt/crypto";
+import type { HistoryProgress, HistorySink, PairingClock } from "./interfaces.js";
+import { type PairingRelay } from "./relayClient.ts.js";
+export interface HistoryReceiverOptions {
+    relay: PairingRelay;
+    id: string;
+    token: string;
+    key: Uint8Array;
+    sink: HistorySink;
+    clock: PairingClock;
+    signal: AbortSignal;
+    onProgress(progress: HistoryProgress): void;
+}
+/** N: fetches each listed chunk newest first, checks it against its entry, and stores each message once. */
+export declare function createHistoryReceiver(options: HistoryReceiverOptions): {
+    done: Promise<void>;
+    progress: () => {
+        messages: number;
+        total: number | null;
+        chunks: number;
+        listed: number;
+        missing: number;
+        refused: number;
+        truncated: boolean;
+        oldest: number | null;
+        complete: boolean;
+    };
+    /** The envelope's manifest: slots 0 onwards, in order. */
+    listManifest(chunks: readonly HistoryChunkEntry[]): void;
+    /** One of A's history messages. Throws `tampered` for anything off. */
+    list(message: Record<string, unknown>): void;
+    /** The session is gone: whatever is still listed won't arrive. */
+    abandon: () => void;
+};

package/dist/pairing/historyReceiver.js

@@ -0,0 +1,139 @@
+import { openHistoryChunk, parseHistoryChunkEntry } from "@gryt/crypto";
+import { PairingEnded } from "./channel.js";
+import { emptyProgress } from "./historySender.js";
+import { PairingRelayError } from "./relayClient.js";
+const MAX_NETWORK_RETRIES = 5;
+const messageKey = (r) => JSON.stringify([r.scope, r.conversationId, r.messageId]);
+/** N: fetches each listed chunk newest first, checks it against its entry, and stores each message once. */
+export function createHistoryReceiver(options) {
+    const { relay, id, token, key, sink, clock, signal } = options;
+    const progress = emptyProgress();
+    const pending = new Map();
+    const slots = new Set();
+    const chunkIds = new Set();
+    const stored = new Set();
+    let final = false;
+    let stopped = false;
+    let wake = null;
+    const report = () => options.onProgress({ ...progress });
+    const nudge = () => (wake?.(), (wake = null));
+    function add(n, value) {
+        let entry;
+        try {
+            entry = parseHistoryChunkEntry(value);
+        }
+        catch {
+            throw new PairingEnded("tampered");
+        }
+        // A slot or chunk listed twice is either a replay or a bug; neither gets a second look.
+        if (!Number.isSafeInteger(n) || n < 0 || slots.has(n) || chunkIds.has(entry.id))
+            throw new PairingEnded("tampered");
+        slots.add(n);
+        chunkIds.add(entry.id);
+        pending.set(n, entry);
+        progress.listed++;
+    }
+    async function fetchChunk(n) {
+        for (let failures = 0;;) {
+            try {
+                return await relay.getChunk(id, token, n, signal);
+            }
+            catch (e) {
+                if (e instanceof PairingRelayError && e.status === 404)
+                    return "missing";
+                if (e instanceof PairingRelayError && e.status === 410)
+                    return "gone";
+                if (!(e instanceof PairingRelayError && e.code === "network") || ++failures > MAX_NETWORK_RETRIES)
+                    throw e;
+                await clock.sleep(2000, signal);
+            }
+        }
+    }
+    /** The newest listed chunk, so recent conversations fill in first. */
+    function next() {
+        let best = null;
+        for (const item of pending)
+            if (!best || item[1].last > best[1].last)
+                best = item;
+        return best;
+    }
+    function abandon() {
+        progress.missing += pending.size;
+        pending.clear();
+        stopped = true;
+        report();
+        nudge();
+    }
+    async function run() {
+        for (;;) {
+            if (signal.aborted || stopped)
+                return;
+            const item = next();
+            if (!item) {
+                if (final)
+                    return void ((progress.complete = true), report());
+                await new Promise((resolve) => (wake = resolve));
+                continue;
+            }
+            const [n, entry] = item;
+            const sealed = await fetchChunk(n);
+            if (sealed === "gone")
+                return abandon();
+            pending.delete(n);
+            if (sealed === "missing") {
+                progress.missing++;
+                report();
+                continue;
+            }
+            let records;
+            try {
+                records = openHistoryChunk(key, entry, sealed);
+            }
+            catch {
+                progress.refused++;
+                report();
+                continue;
+            }
+            const fresh = records.filter((r) => !stored.has(messageKey(r)));
+            if (fresh.length > 0)
+                await sink.put(fresh);
+            for (const r of fresh)
+                stored.add(messageKey(r));
+            progress.chunks++;
+            progress.messages += fresh.length;
+            progress.oldest = Math.min(progress.oldest ?? entry.first, entry.first);
+            report();
+            relay.deleteChunk(id, token, n).catch(() => undefined);
+        }
+    }
+    signal.addEventListener("abort", nudge, { once: true });
+    const done = run();
+    done.catch(() => undefined);
+    return {
+        done,
+        progress: () => ({ ...progress }),
+        /** The envelope's manifest: slots 0 onwards, in order. */
+        listManifest(chunks) {
+            chunks.forEach((entry, n) => add(n, entry));
+            report();
+            nudge();
+        },
+        /** One of A's history messages. Throws `tampered` for anything off. */
+        list(message) {
+            if (final || !Array.isArray(message.chunks))
+                throw new PairingEnded("tampered");
+            for (const chunk of message.chunks)
+                add(chunk?.n, chunk);
+            if (Number.isSafeInteger(message.total))
+                progress.total = message.total;
+            if (message.truncated === true)
+                progress.truncated = true;
+            if (message.final === true)
+                final = true;
+            report();
+            nudge();
+        },
+        /** The session is gone: whatever is still listed won't arrive. */
+        abandon,
+    };
+}

package/dist/pairing/historySender.d.ts

@@ -0,0 +1,65 @@
+import { type HistoryChunkEntry, type HistoryRecord } from "@gryt/crypto";
+import type { MlsOwnDeviceAdd } from "../mls/interfaces.js";
+import type { HistoryArchive, HistoryNotedMessage, HistoryProgress, PairingClock } from "./interfaces.js";
+import { type PairingRelay } from "./relayClient.ts.js";
+/** The relay's 256 MiB per session, less room for the tail. */
+export declare const HISTORY_SNAPSHOT_MAX_BYTES: number;
+/** Entries in the envelope's manifest and in each later message, which keep under 256 and 64 KiB. */
+export declare const HISTORY_ENVELOPE_ENTRIES = 400;
+export declare const HISTORY_PAGE_ENTRIES = 180;
+/** One chunk as a history message lists it: its relay slot and its manifest entry. */
+export interface ListedChunk extends HistoryChunkEntry {
+    n: number;
+}
+/** What A posts after the envelope, sealed. `final` says nothing more is coming. */
+export interface HistoryMessage {
+    t: "history";
+    chunks: ListedChunk[];
+    total?: number;
+    truncated?: boolean;
+    final?: boolean;
+}
+export declare const emptyProgress: () => HistoryProgress;
+export interface HistorySenderOptions {
+    relay: PairingRelay;
+    id: string;
+    token: string;
+    archive: HistoryArchive;
+    clock: PairingClock;
+    signal: AbortSignal;
+    /** Seals and posts one message. The sender calls it one at a time, in order. */
+    post(message: HistoryMessage): Promise<void>;
+    onProgress(progress: HistoryProgress): void;
+    maxBytes?: number;
+}
+/** A: seals the archive into chunks newest first, uploads each, then lists it to N. */
+export declare function createHistorySender(options: HistorySenderOptions): {
+    key: Uint8Array<ArrayBufferLike>;
+    progress: () => {
+        messages: number;
+        total: number | null;
+        chunks: number;
+        listed: number;
+        missing: number;
+        refused: number;
+        truncated: boolean;
+        oldest: number | null;
+        complete: boolean;
+    };
+    /** Waits until `until` or the end of the snapshot, whichever is first, and hands over what's up. */
+    forEnvelope(until: number): Promise<HistoryChunkEntry[]>;
+    /** After N's "ready": list what's waiting, and keep listing as pages fill. */
+    startPaging(): void;
+    /** The tail: records past the snapshot. `final` waits for the snapshot and says that's all. */
+    send(records: HistoryRecord[], final: boolean): Promise<void>;
+};
+/**
+ * A's record of MLS messages it archived during the transfer. The tail is every one past the
+ * snapshot that N can't read: before N's add, or sent in an older epoch that landed after it.
+ */
+export declare function createTailRecorder(): {
+    start: () => undefined;
+    note(message: HistoryNotedMessage): void;
+    /** Everything noted since the last call that N needs. `snap` and `added` are per host. */
+    take(snap: Map<string, Map<string, number>>, added: Record<string, MlsOwnDeviceAdd[]>): HistoryRecord[];
+};

package/dist/pairing/historySender.js

@@ -0,0 +1,182 @@
+import { generateHistoryKey, planHistoryChunks, sealHistoryChunk, } from "@gryt/crypto";
+import { archiveByDay } from "./historySnapshot.js";
+import { PairingRelayError } from "./relayClient.js";
+/** The relay's 256 MiB per session, less room for the tail. */
+export const HISTORY_SNAPSHOT_MAX_BYTES = 248 * 1024 * 1024;
+/** Entries in the envelope's manifest and in each later message, which keep under 256 and 64 KiB. */
+export const HISTORY_ENVELOPE_ENTRIES = 400;
+export const HISTORY_PAGE_ENTRIES = 180;
+/** The relay allows 64 messages a session, both sides together; N and the envelope use five. */
+const HISTORY_MAX_CHUNKS = HISTORY_ENVELOPE_ENTRIES + 40 * HISTORY_PAGE_ENTRIES;
+const MAX_NETWORK_RETRIES = 5;
+export const emptyProgress = () => ({
+    messages: 0, total: null, chunks: 0, listed: 0, missing: 0, refused: 0, truncated: false, oldest: null, complete: false,
+});
+/** A: seals the archive into chunks newest first, uploads each, then lists it to N. */
+export function createHistorySender(options) {
+    const { relay, id, token, clock, signal } = options;
+    const key = generateHistoryKey();
+    const maxBytes = options.maxBytes ?? HISTORY_SNAPSHOT_MAX_BYTES;
+    const progress = emptyProgress();
+    /** Uploaded, not yet listed. */
+    const unlisted = [];
+    let slot = 0;
+    let bytes = 0;
+    let paging = false;
+    let walked = false;
+    let posting = Promise.resolve();
+    let finished = false;
+    const report = () => options.onProgress({ ...progress });
+    async function put(n, sealed) {
+        for (let failures = 0;;) {
+            try {
+                return await relay.putChunk(id, token, n, sealed, signal);
+            }
+            catch (e) {
+                if (!(e instanceof PairingRelayError && e.code === "network") || ++failures > MAX_NETWORK_RETRIES)
+                    throw e;
+                await clock.sleep(2000, signal);
+            }
+        }
+    }
+    /** False once the cap or the relay says no more. */
+    async function upload(records, capped) {
+        for (const chunk of planHistoryChunks(records)) {
+            if (signal.aborted)
+                throw new Error("History transfer cancelled.");
+            const { entry, sealed } = sealHistoryChunk(key, chunk);
+            if (capped && (bytes + sealed.length > maxBytes || slot >= HISTORY_MAX_CHUNKS))
+                return false;
+            const n = slot++;
+            try {
+                await put(n, sealed);
+            }
+            catch (e) {
+                // The relay's own caps: whatever didn't fit stays behind, the same as our own cap.
+                if (capped && e instanceof PairingRelayError && (e.status === 507 || e.code === "busy"))
+                    return false;
+                throw e;
+            }
+            bytes += sealed.length;
+            unlisted.push({ n, ...entry });
+            progress.chunks++;
+            progress.messages += entry.count;
+            progress.oldest = Math.min(progress.oldest ?? entry.first, entry.first);
+            report();
+        }
+        return true;
+    }
+    async function walk() {
+        const conversations = await options.archive.conversations();
+        if (conversations.every((c) => typeof c.count === "number")) {
+            progress.total = conversations.reduce((sum, c) => sum + (c.count ?? 0), 0);
+            report();
+        }
+        for await (const day of archiveByDay(options.archive)) {
+            if (!(await upload(day, true))) {
+                progress.truncated = true;
+                break;
+            }
+            if (paging)
+                void flush(false, false);
+        }
+        walked = true;
+        if (paging)
+            void flush(false);
+    }
+    const snapshot = walk();
+    snapshot.catch(() => undefined);
+    /** Lists what's uploaded, a page per message. `partial` false keeps back a page that isn't full. */
+    function flush(final, partial = true) {
+        const pages = [];
+        while (unlisted.length >= (partial ? 1 : HISTORY_PAGE_ENTRIES))
+            pages.push(unlisted.splice(0, HISTORY_PAGE_ENTRIES));
+        if (final && pages.length === 0)
+            pages.push([]);
+        pages.forEach((chunks, i) => {
+            const message = { t: "history", chunks };
+            if (progress.total !== null)
+                message.total = progress.total;
+            if (progress.truncated)
+                message.truncated = true;
+            if (final && i === pages.length - 1)
+                message.final = true;
+            posting = posting.then(async () => {
+                await options.post(message);
+                progress.listed += chunks.length;
+                if (message.final)
+                    progress.complete = true;
+                report();
+            });
+        });
+        posting.catch(() => undefined);
+        return posting;
+    }
+    return {
+        key,
+        progress: () => ({ ...progress }),
+        /** Waits until `until` or the end of the snapshot, whichever is first, and hands over what's up. */
+        async forEnvelope(until) {
+            const wait = new AbortController();
+            const stop = () => wait.abort();
+            signal.addEventListener("abort", stop, { once: true });
+            try {
+                await Promise.race([snapshot, clock.sleep(Math.max(0, until - clock.now()), wait.signal).catch(() => undefined)]);
+            }
+            finally {
+                wait.abort();
+                signal.removeEventListener("abort", stop);
+            }
+            const listed = unlisted.splice(0, HISTORY_ENVELOPE_ENTRIES);
+            progress.listed += listed.length;
+            report();
+            return listed.map(({ n: _n, ...entry }) => entry);
+        },
+        /** After N's "ready": list what's waiting, and keep listing as pages fill. */
+        startPaging() {
+            paging = true;
+            void flush(false, walked);
+        },
+        /** The tail: records past the snapshot. `final` waits for the snapshot and says that's all. */
+        async send(records, final) {
+            if (finished)
+                throw new Error("This history transfer has finished.");
+            if (final) {
+                await snapshot;
+                finished = true;
+            }
+            if (records.length > 0)
+                await upload(records, false);
+            await flush(final);
+        },
+    };
+}
+/**
+ * A's record of MLS messages it archived during the transfer. The tail is every one past the
+ * snapshot that N can't read: before N's add, or sent in an older epoch that landed after it.
+ */
+export function createTailRecorder() {
+    let on = false;
+    let noted = [];
+    return {
+        start: () => void (on = true),
+        note(message) {
+            if (on)
+                noted.push(message);
+        },
+        /** Everything noted since the last call that N needs. `snap` and `added` are per host. */
+        take(snap, added) {
+            const out = [];
+            for (const m of noted) {
+                if (m.seq <= (snap.get(m.host)?.get(m.conversationId) ?? -1))
+                    continue;
+                const add = added[m.host]?.find((a) => a.conversationId === m.conversationId)?.add ?? null;
+                if (add && m.seq >= add.seq && m.epoch >= add.epoch)
+                    continue;
+                out.push(m.record);
+            }
+            noted = [];
+            return out;
+        },
+    };
+}

package/dist/pairing/historySnapshot.d.ts

@@ -0,0 +1,7 @@
+import type { HistoryRecord } from "@gryt/crypto";
+import type { HistoryArchive, HistoryCursor } from "./interfaces.js";
+export declare const dayOf: (sentAt: number) => number;
+/** Negative when `a` is newer: by time, then by message id, the same order the archive pages in. */
+export declare function newerFirst(a: HistoryCursor, b: HistoryCursor): number;
+/** A's archive one UTC day at a time, newest day first across every conversation and server. */
+export declare function archiveByDay(archive: HistoryArchive, pageSize?: number): AsyncGenerator<HistoryRecord[]>;

package/dist/pairing/historySnapshot.js

@@ -0,0 +1,45 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const dayOf = (sentAt) => Math.floor(sentAt / DAY_MS);
+/** Negative when `a` is newer: by time, then by message id, the same order the archive pages in. */
+export function newerFirst(a, b) {
+    return b.sentAt - a.sentAt || (a.messageId < b.messageId ? 1 : a.messageId > b.messageId ? -1 : 0);
+}
+/** A's archive one UTC day at a time, newest day first across every conversation and server. */
+export async function* archiveByDay(archive, pageSize = 500) {
+    const walks = (await archive.conversations()).map((c) => ({ ...c, buffer: [], exhausted: false }));
+    const fill = async (w) => {
+        if (w.buffer.length > 0 || w.exhausted)
+            return;
+        const page = await archive.page(w.scope, w.conversationId, { before: w.before, limit: pageSize });
+        // Only what's older than the cursor and in this conversation, so a sloppy page can't loop forever.
+        const fresh = page
+            .filter((r) => r.scope === w.scope && r.conversationId === w.conversationId)
+            .filter((r) => !w.before || newerFirst(r, w.before) > 0)
+            .sort(newerFirst);
+        w.buffer = fresh;
+        w.before = fresh.at(-1) ?? w.before;
+        w.exhausted = fresh.length === 0 || page.length < pageSize;
+    };
+    for (;;) {
+        await Promise.all(walks.map(fill));
+        const heads = walks.filter((w) => w.buffer.length > 0);
+        if (heads.length === 0)
+            return;
+        const day = Math.max(...heads.map((w) => dayOf(w.buffer[0].sentAt)));
+        const out = [];
+        for (const w of heads) {
+            for (;;) {
+                let i = 0;
+                while (i < w.buffer.length && dayOf(w.buffer[i].sentAt) === day)
+                    out.push(w.buffer[i++]);
+                w.buffer = w.buffer.slice(i);
+                if (w.buffer.length > 0)
+                    break;
+                await fill(w);
+                if (w.buffer.length === 0)
+                    break;
+            }
+        }
+        yield out;
+    }
+}

package/dist/pairing/interfaces.d.ts

@@ -1,5 +1,5 @@
-import type { PairingEnvelope } from "@gryt/crypto";
-import type { MlsAddOwnDeviceOptions, MlsOwnDeviceAdd } from "../mls/interfaces.js";
+import type { HistoryRecord, PairingEnvelope } from "@gryt/crypto";
+import type { MlsAddOwnDeviceOptions, MlsGroupPosition, MlsOwnDeviceAdd } from "../mls/interfaces.js";
 /** `fetch`, cut down to what pairing uses. The browser's, Node's and React Native's all fit. */
 export type PairingFetch = (url: string, init: {
     method: string;
@@ -69,10 +69,14 @@ export interface PairedServerDevice {
 /** A's DM driver on one server, or undefined when A isn't on it. */
 export type OwnDeviceAdder = (host: string) => {
     addOwnDevice(deviceId: string, options?: MlsAddOwnDeviceOptions): Promise<MlsOwnDeviceAdd[]>;
+    /** Where the history snapshot stops in each group; the tail starts after it. */
+    groupPositions(): Promise<MlsGroupPosition[]>;
 } | undefined;
 /** Why a pairing stopped. `approve:<error>` carries the extension's own error code for anything
     below that isn't broken out on its own (GRYT-1578; auth#46 has the full list). */
 export type PairingEndReason = "cancelled" | "cancelled_by_other" | "mismatch" | "timed_out" | "expired" | "already_claimed" | "unknown_code" | "wrong_relay" | "newer_version" | "not_pairing" | "rate_limited" | "tampered" | "wrong_account" | "sign_in_failed" | "relay_error"
+/** N's archive refused the history it was handed. Keys and sign-in are in place. */
+ | "history_failed"
 /** The approve endpoint says this user_code already got its one answer. */
  | "code_used"
 /** The approve endpoint says the user_code isn't valid any more: unknown, expired, or not pending. */
@@ -85,3 +89,53 @@ export type PairingEndReason = "cancelled" | "cancelled_by_other" | "mismatch" |
  | "access_denied"
 /** The device grant's user_code ran out before anyone answered it. */
  | "expired_token" | `approve:${string}`;
+/** A conversation in A's archive. `count` feeds the progress total, so leave it off rather than guess. */
+export interface HistoryConversation {
+    scope: string;
+    conversationId: string;
+    count?: number;
+}
+/** Where a page of the archive stops: the oldest record in it. */
+export interface HistoryCursor {
+    sentAt: number;
+    messageId: string;
+}
+/** A's archive, read for the history snapshot. Records are @gryt/crypto's HistoryRecord. */
+export interface HistoryArchive {
+    conversations(): Promise<HistoryConversation[]>;
+    /** Up to `limit` records sent before `before` (by sentAt, then messageId), in any order. */
+    page(scope: string, conversationId: string, options: {
+        before?: HistoryCursor;
+        limit: number;
+    }): Promise<HistoryRecord[]>;
+}
+/** N's archive. Core hands it each message id once; a record for an id N already holds replaces it. */
+export interface HistorySink {
+    put(records: HistoryRecord[]): Promise<void>;
+}
+/** How a history transfer is going, on either side. */
+export interface HistoryProgress {
+    /** A: messages uploaded and listed. N: messages stored. */
+    messages: number;
+    /** A: from the archive's counts. N: what A said it would send. Null when nobody knows yet. */
+    total: number | null;
+    /** Chunks uploaded (A) or fetched and stored (N), out of `listed`. */
+    chunks: number;
+    listed: number;
+    /** N only: chunks the relay no longer has, and chunks that failed their manifest check. */
+    missing: number;
+    refused: number;
+    /** The relay's cap stopped the snapshot early; the oldest messages stayed behind. */
+    truncated: boolean;
+    /** The oldest message time sent so far, so N can say how far back it has. */
+    oldest: number | null;
+    complete: boolean;
+}
+/** A message A archived from MLS, received or sent, with where it sits in its group's log. */
+export interface HistoryNotedMessage {
+    host: string;
+    conversationId: string;
+    seq: number;
+    epoch: number;
+    record: HistoryRecord;
+}

package/dist/pairing/newDevice.d.ts

@@ -1,5 +1,5 @@
 import { type PairingEmoji, type PairingServer } from "@gryt/crypto";
-import type { PairedServerDevice, PairingClock, PairingDeviceInfo, PairingEndReason, PairingOidc, PairingStorage } from "./interfaces.js";
+import type { HistoryProgress, HistorySink, PairedServerDevice, PairingClock, PairingDeviceInfo, PairingEndReason, PairingOidc, PairingStorage } from "./interfaces.js";
 import type { PairingRelay } from "./relayClient.js";
 export type NewDeviceState = {
     phase: "idle";
@@ -46,10 +46,15 @@ export interface NewDeviceOptions {
     /** Only for a server with its own auth server: goes in the QR for A to check against its own. */
     relayOrigin?: string;
     approvalMs?: number;
+    /** N's archive. Without it, history A sends is left on the relay. */
+    history?: HistorySink;
 }
 export interface NewDevicePairing {
     readonly state: NewDeviceState;
     subscribe(listener: (state: NewDeviceState) => void): () => void;
+    /** Null until the envelope brings a history key, or with no sink. */
+    readonly history: HistoryProgress | null;
+    subscribeHistory(listener: (progress: HistoryProgress) => void): () => void;
     start(): void;
     /** In `joining`: N's device on each server, once its KeyPackages are up. */
     ready(devices: PairedServerDevice[]): Promise<void>;

package/dist/pairing/newDevice.js

@@ -1,7 +1,8 @@
 import { base64Url, base64UrlDecode, createPairingKey, decodePairingEnvelope, decodePairingSessionId, formatPairingCode, formatPairingQr, pairingCommitment, startNewDeviceSession, } from "@gryt/crypto";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { randomBytes } from "@noble/hashes/utils.js";
-import { mailbox, PairingEnded, reasonFor, sealJson, systemClock } from "./channel.js";
+import { mailbox, openJson, PairingEnded, reasonFor, sealJson, systemClock } from "./channel.js";
+import { createHistoryReceiver } from "./historyReceiver.js";
 export const PAIRING_APPROVAL_MS = 60_000;
 const PAIRING_OIDC_SCOPE = "openid profile email offline_access";
 /** N: shows the QR and code, checks the emoji, opens the envelope, signs in, then says ready. */
@@ -13,6 +14,14 @@ export function createNewDevicePairing(options) {
     const abort = new AbortController();
     let state = { phase: "idle" };
     let current = null;
+    let receiver = null;
+    let history = null;
+    const historyListeners = new Set();
+    const setHistory = (progress) => {
+        history = progress;
+        for (const l of historyListeners)
+            l(progress);
+    };
     const set = (next) => {
         if (state.phase === "ended" || state.phase === "done")
             return;
@@ -141,6 +150,13 @@ export function createNewDevicePairing(options) {
             const envelope = outcome;
             const tokens = envelope.account ? await signIn(envelope.account, envelope.from) : null;
             await storage.commit(envelope, tokens);
+            if (envelope.history && options.history) {
+                const { id, token } = current;
+                receiver = createHistoryReceiver({
+                    relay, id, token, key: envelope.history.key, sink: options.history, clock, signal: abort.signal, onProgress: setHistory,
+                });
+                receiver.listManifest(envelope.history.manifest.chunks);
+            }
             set({ phase: "joining", servers: envelope.servers, from: envelope.from });
         }
         catch (e) {
@@ -148,20 +164,43 @@ export function createNewDevicePairing(options) {
                 await end(reasonFor(e));
         }
     }
+    /** Reads A's history messages until every chunk is in, or A closing is the finish. */
     async function linked(from) {
+        const { box, session } = current;
+        const stop = new AbortController();
+        const onAbort = () => stop.abort();
+        abort.signal.addEventListener("abort", onAbort, { once: true });
+        let failed = false;
+        receiver?.done.then(onAbort, () => ((failed = true), onAbort()));
         try {
-            // History from A lands here in a later version. Until then, A closing is the finish.
-            while (await current.box.next(abort.signal))
-                ;
+            for (;;) {
+                const body = openJson(session, await box.next(stop.signal), "history");
+                if (receiver)
+                    receiver.list(body);
+                // No sink here: nothing to fetch, so A's last message is the finish.
+                else if (body.final === true)
+                    throw (stop.abort(), new Error("finished"));
+            }
         }
         catch (e) {
             if (abort.signal.aborted)
                 return;
+            if (failed)
+                return end("history_failed");
+            if (stop.signal.aborted) {
+                set({ phase: "done", from });
+                session?.close();
+                return void (await closeQuietly());
+            }
             const reason = reasonFor(e);
             if (reason !== "cancelled_by_other" && reason !== "expired")
                 return end(reason);
+            receiver?.abandon();
             set({ phase: "done", from });
-            current?.session?.close();
+            session?.close();
+        }
+        finally {
+            abort.signal.removeEventListener("abort", onAbort);
         }
     }
     return {
@@ -172,6 +211,13 @@ export function createNewDevicePairing(options) {
             listeners.add(listener);
             return () => void listeners.delete(listener);
         },
+        get history() {
+            return history;
+        },
+        subscribeHistory(listener) {
+            historyListeners.add(listener);
+            return () => void historyListeners.delete(listener);
+        },
         start() {
             if (state.phase !== "idle")
                 throw new Error("This pairing has started already.");

package/dist/pairing/relayClient.d.ts

@@ -40,6 +40,13 @@ export interface PairingRelay {
     /** The other side's messages after `after`, waiting up to `waitSeconds`. Asking past one acks it. */
     poll(id: string, token: string, after: number, waitSeconds: number, signal?: AbortSignal): Promise<RelayMessage[]>;
     close(id: string, token: string): Promise<void>;
+    /** A: one sealed history chunk into slot `n`. */
+    putChunk(id: string, token: string, n: number, sealed: Uint8Array, signal?: AbortSignal): Promise<void>;
+    /** N: the chunk in slot `n`. A 404 means the relay doesn't have it. */
+    getChunk(id: string, token: string, n: number, signal?: AbortSignal): Promise<Uint8Array>;
+    /** N: done with slot `n`. */
+    deleteChunk(id: string, token: string, n: number): Promise<void>;
 }
-/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. */
+/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. The chunk
+    calls follow docs/pairing-design.md; the relay doesn't have them yet (GRYT-1591). */
 export declare function createPairingRelay(origin: string, fetch: PairingFetch): PairingRelay;

package/dist/pairing/relayClient.js

@@ -1,3 +1,4 @@
+import { base64Url, base64UrlDecode } from "@gryt/crypto";
 /** A refusal from the relay: its status and the `error` it sent, or "network" when nothing came back. */
 export class PairingRelayError extends Error {
     status;
@@ -9,7 +10,8 @@ export class PairingRelayError extends Error {
         this.code = code;
     }
 }
-/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. */
+/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. The chunk
+    calls follow docs/pairing-design.md; the relay doesn't have them yet (GRYT-1591). */
 export function createPairingRelay(origin, fetch) {
     const base = `${origin.replace(/\/+$/, "")}/api/v1/pairing/sessions`;
     async function call(method, path, body, token, signal) {
@@ -44,5 +46,18 @@ export function createPairingRelay(origin, fetch) {
             return (Array.isArray(res.messages) ? res.messages : []);
         },
         close: async (id, token) => void (await call("DELETE", path(id), undefined, token)),
+        putChunk: async (id, token, n, sealed, signal) => void (await call("PUT", `${path(id)}/chunks/${n}`, { body: base64Url(sealed) }, token, signal)),
+        getChunk: async (id, token, n, signal) => {
+            const res = await call("GET", `${path(id)}/chunks/${n}`, undefined, token, signal);
+            if (typeof res.body !== "string")
+                throw new PairingRelayError(200, "invalid_body");
+            try {
+                return base64UrlDecode(res.body);
+            }
+            catch {
+                throw new PairingRelayError(200, "invalid_body");
+            }
+        },
+        deleteChunk: async (id, token, n) => void (await call("DELETE", `${path(id)}/chunks/${n}`, undefined, token)),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/core",
-  "version": "0.15.0",
+  "version": "0.16.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": {