@gryt/core 0.13.0 → 0.14.0

package/README.md

@@ -49,15 +49,30 @@ goes missing **and** when one appears that nobody listed.
   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
+  log in order. For linking a device, `addOwnDevice` puts a new device of yours
+  in every DM straight away and says where in each group's log it went in.
+  `groupPositions` says where each log stood when the history snapshot was
+  taken. 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: a message, an edit, a delete or
   a reaction. `readMlsDmContent` also says when something came from a newer app,
   so it can be skipped quietly rather than counted as broken. `applyMlsReaction` puts a reaction on a message in the archive,
-  since the server never sees one. It's the one module with a
-  dependency, `@gryt/crypto`, pinned exactly the way the apps pin it.
+  since the server never sees one. It depends on `@gryt/crypto`, pinned
+  exactly the way the apps pin it.
+- **`pairing`** — linking a new device by QR code or short code, as
+  `docs/pairing-design.md` in `@gryt/crypto` lays it out. There's one state
+  machine per side. `createNewDevicePairing` shows the QR and code, checks the
+  emoji, opens the envelope and, for an account, signs in with the device grant
+  and checks the ID token is for the right person. It writes nothing until all
+  of that passes. `createApproverPairing` claims the session, shows who's
+  asking, seals the envelope, approves the sign-in through the Keycloak
+  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
+  `@noble/hashes` for the PKCE challenge, which `@gryt/crypto` already pulls in.
 
 ## What deliberately isn't
 

package/dist/index.d.ts

@@ -14,4 +14,8 @@ export { createMlsDmDriver, MlsDriverError, type MlsDriverErrorCode } from "./ml
 export { mlsPinsFromPeerPins } from "./mls/pins.js";
 export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, type MlsDmContent, readMlsDmContent, } from "./mls/content.js";
 export { applyMlsReaction, mlsReactionAction, type MlsReaction } from "./mls/reactions.js";
-export type { DmSealingMode, MlsClaimedKeyPackage, MlsDecryptedMessage, MlsDeviceRecord, MlsDeviceRef, MlsDmDriver, MlsDmDriverOptions, MlsDmEvents, MlsGroupRecord, MlsGroupView, MlsKeyPackageRecord, MlsListedDevice, MlsLogEntry, MlsOwnDevice, MlsPins, MlsRefusal, MlsReply, MlsServerCapability, MlsStateStore, MlsTransport, MlsWelcomeDelivery, } from "./mls/interfaces.js";
+export type { DmSealingMode, MlsAddOwnDeviceOptions, MlsClaimedKeyPackage, MlsDecryptedMessage, MlsDeviceRecord, MlsDeviceRef, MlsDmDriver, MlsDmDriverOptions, MlsDmEvents, MlsGroupPosition, MlsGroupRecord, MlsGroupView, MlsKeyPackageRecord, MlsListedDevice, MlsLogEntry, MlsOwnDevice, MlsOwnDeviceAdd, MlsPins, MlsRefusal, MlsReply, MlsServerCapability, MlsStateStore, MlsTransport, MlsWelcomeDelivery, } from "./mls/interfaces.js";
+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";

package/dist/index.js

@@ -16,3 +16,6 @@ export { createMlsDmDriver, MlsDriverError } from "./mls/dmDriver.js";
 export { mlsPinsFromPeerPins } from "./mls/pins.js";
 export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, readMlsDmContent, } from "./mls/content.js";
 export { applyMlsReaction, mlsReactionAction } from "./mls/reactions.js";
+export { createApproverPairing, } from "./pairing/approver.js";
+export { createNewDevicePairing, PAIRING_APPROVAL_MS, } from "./pairing/newDevice.js";
+export { createPairingRelay, PairingRelayError } from "./pairing/relayClient.js";

package/dist/mls/dmDriver.d.ts

@@ -1,5 +1,5 @@
 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" | "device_removed";
+export type MlsDriverErrorCode = "refused" | "not_own_device" | "no_device" | "waiting_for_welcome" | "not_in_group" | "unexpected_member" | "peer_unverified" | "too_many_attachments" | "commit_retries" | "device_removed";
 export declare class MlsDriverError extends Error {
     code: MlsDriverErrorCode;
     /** The server's refusal, when there was one. */

package/dist/mls/dmDriver.js

@@ -138,6 +138,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 +214,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 +242,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") {
@@ -255,6 +271,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 +322,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 };
@@ -667,6 +685,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();
@@ -694,5 +819,7 @@ export function createMlsDmDriver(options) {
                 throw refused("Removing the device", r);
             await handleDevicesChanged({ serverUserId: self });
         },
+        groupPositions,
+        addOwnDevice,
     };
 }

package/dist/mls/interfaces.d.ts

@@ -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;
@@ -262,6 +264,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;
@@ -295,4 +330,11 @@ 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[]>;
 }

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;

package/dist/pairing/approver.js

@@ -0,0 +1,186 @@
+import { base64Url, base64UrlDecode, createPairingKey, decodePairingSessionId, encodePairingEnvelope, encodePairingSessionId, parsePairingCode, parsePairingQr, startApproverSession, } from "@gryt/crypto";
+import { mailbox, openJson, PairingEnded, reasonFor, systemClock } from "./channel.js";
+import { PAIRING_APPROVAL_MS } from "./newDevice.js";
+const NOT_LISTED_RETRIES = 5;
+/** A: claims the session, shows N and the emoji, and on Approve seals the envelope, signs N in and adds it. */
+export function createApproverPairing(options) {
+    const { relay, fetch, devices } = options;
+    const clock = options.clock ?? systemClock;
+    const approvalMs = options.approvalMs ?? PAIRING_APPROVAL_MS;
+    const listeners = new Set();
+    const abort = new AbortController();
+    let state = { phase: "idle" };
+    let current = null;
+    let device = null;
+    let confirming = null;
+    const set = (next) => {
+        if (state.phase === "ended" || state.phase === "done")
+            return;
+        state = next;
+        for (const l of listeners)
+            l(state);
+    };
+    const closeQuietly = () => (current ? relay.close(current.id, current.token).catch(() => undefined) : undefined);
+    const end = async (reason) => {
+        if (state.phase === "ended" || state.phase === "done")
+            return;
+        set({ phase: "ended", reason });
+        abort.abort();
+        current?.session?.close();
+        await closeQuietly();
+    };
+    const fail = (e) => (abort.signal.aborted ? undefined : end(reasonFor(e)));
+    async function claim(input) {
+        let by;
+        let scanned;
+        if ("qr" in input) {
+            const qr = parsePairingQr(input.qr);
+            if (!qr.ok)
+                throw new PairingEnded(qr.reason === "newer-version" ? "newer_version" : "not_pairing");
+            if (qr.relayOrigin !== undefined && qr.relayOrigin !== options.relayOrigin.toLowerCase().replace(/\/+$/, "")) {
+                throw new PairingEnded("wrong_relay");
+            }
+            by = { id: encodePairingSessionId(qr.sessionId) };
+            scanned = qr.publicKey;
+        }
+        else {
+            const code = parsePairingCode(input.code);
+            if (!code)
+                throw new PairingEnded("unknown_code");
+            by = { code };
+        }
+        set({ phase: "claiming" });
+        const key = createPairingKey();
+        const claimed = await relay.claim(by, base64Url(key.publicKey));
+        const box = mailbox(relay, claimed.id, claimed.token, clock);
+        current = { id: claimed.id, token: claimed.token, box };
+        const sessionId = decodePairingSessionId(claimed.id);
+        set({ phase: "waiting" });
+        const reveal = await box.next(abort.signal, clock.now() + approvalMs);
+        if (!reveal)
+            throw new PairingEnded("timed_out");
+        if (reveal.type !== "reveal" || !reveal.pkN || !sessionId)
+            throw new PairingEnded("tampered");
+        try {
+            current.session = startApproverSession(key, {
+                sessionId,
+                commitment: base64UrlDecode(claimed.commit),
+                newDevicePublicKey: base64UrlDecode(reveal.pkN),
+                scannedPublicKey: scanned,
+            });
+        }
+        catch {
+            throw new PairingEnded("tampered");
+        }
+        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;
+        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();
+        abort.signal.addEventListener("abort", () => confirming?.abort(), { once: true });
+        try {
+            if (await box.next(confirming.signal, deadline))
+                throw new PairingEnded("tampered");
+        }
+        catch (e) {
+            if (confirming.signal.aborted)
+                return;
+            // N's clock started a moment before ours, so its timeout close can land just before ours fires.
+            if (reasonFor(e) !== "cancelled_by_other" || clock.now() < deadline - 5000)
+                throw e;
+        }
+        throw new PairingEnded("timed_out");
+    }
+    async function approveExtension(issuer, userCode, accessToken) {
+        const token = await accessToken();
+        const res = await fetch(`${issuer.replace(/\/+$/, "")}/gryt-pairing/approve`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ user_code: userCode, binding: current.session.keycloakNonce }),
+        }).catch(() => {
+            throw new PairingEnded("approve:network");
+        });
+        if (res.status === 204)
+            return true;
+        if (res.status === 404)
+            return false;
+        const body = (await res.json().catch(() => null));
+        throw new PairingEnded(`approve:${typeof body?.error === "string" ? body.error : res.status}`);
+    }
+    async function addEverywhere(ready) {
+        const added = {};
+        for (const { host, deviceId } of ready) {
+            const driver = devices(host);
+            if (!driver)
+                continue;
+            for (let tries = 0;; tries++) {
+                try {
+                    added[host] = await driver.addOwnDevice(deviceId, {
+                        onProgress: ({ done, total }) => set({ phase: "adding", device: device, host, done, total }),
+                    });
+                    break;
+                }
+                catch (e) {
+                    // The server lists N's device once its KeyPackages are in, which can trail N's "ready".
+                    if (e.code !== "not_own_device" || tries >= NOT_LISTED_RETRIES)
+                        throw e;
+                    await clock.sleep(2000, abort.signal);
+                }
+            }
+        }
+        return added;
+    }
+    async function approve(envelope, accessToken) {
+        const { id, token, box, session } = current;
+        set({ phase: envelope.account ? "signing_in" : "waiting_ready", device: device });
+        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);
+            if (!message)
+                throw new PairingEnded("timed_out");
+            const userCode = String(openJson(session, message, "user_code").userCode ?? "");
+            if (!(await approveExtension(envelope.account.issuer, userCode, accessToken))) {
+                const url = `${envelope.account.issuer.replace(/\/+$/, "")}/device?user_code=${encodeURIComponent(userCode)}`;
+                set({ phase: "browser", device: device, url });
+            }
+        }
+        if (state.phase === "signing_in")
+            set({ phase: "waiting_ready", device: device });
+        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");
+        const added = await addEverywhere(named);
+        set({ phase: "done", device: device, added });
+        session.close();
+        await closeQuietly();
+    }
+    return {
+        get state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        claim(input) {
+            if (state.phase !== "idle")
+                throw new Error("This pairing has claimed a session already.");
+            claim(input).catch(fail);
+        },
+        approve(envelope, accessToken) {
+            if (state.phase !== "confirming")
+                throw new Error("Nothing to approve.");
+            if (envelope.account && !accessToken)
+                throw new Error("An account needs an access token to approve with.");
+            if (clock.now() > state.deadline)
+                return void end("timed_out");
+            confirming?.abort();
+            approve(envelope, accessToken).catch(fail);
+        },
+        deny: () => end("cancelled"),
+        mismatch: () => end("mismatch"),
+        cancel: () => end("cancelled"),
+    };
+}

package/dist/pairing/channel.d.ts

@@ -0,0 +1,17 @@
+import { type PairingSession } from "@gryt/crypto";
+import type { PairingClock, PairingEndReason } from "./interfaces.js";
+import type { PairingRelay, RelayMessage } from "./relayClient.js";
+/** Thrown inside a pairing to stop it with a reason the screen can show. */
+export declare class PairingEnded extends Error {
+    readonly reason: PairingEndReason;
+    constructor(reason: PairingEndReason);
+}
+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>;
+/** 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

@@ -0,0 +1,81 @@
+import { base64Url, base64UrlDecode } from "@gryt/crypto";
+import { PairingRelayError } from "./relayClient.js";
+/** Thrown inside a pairing to stop it with a reason the screen can show. */
+export class PairingEnded extends Error {
+    reason;
+    constructor(reason) {
+        super(`Pairing ended: ${reason}`);
+        this.reason = reason;
+    }
+}
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => (clearTimeout(timer), reject(signal.reason)), { once: true });
+    }),
+};
+export function reasonFor(error) {
+    if (error instanceof PairingEnded)
+        return error.reason;
+    if (!(error instanceof PairingRelayError))
+        return "relay_error";
+    if (error.status === 410)
+        return error.code === "closed" ? "cancelled_by_other" : "expired";
+    if (error.code === "already_claimed")
+        return "already_claimed";
+    if (error.status === 404)
+        return "unknown_code";
+    if (error.status === 429)
+        return "rate_limited";
+    return "relay_error";
+}
+export function sealJson(session, value) {
+    return base64Url(session.seal(new TextEncoder().encode(JSON.stringify(value))));
+}
+/** The next sealed message as JSON with a `t`, or a throw that ends the pairing as tampered. */
+export function openJson(session, message, t) {
+    try {
+        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)
+            return value;
+    }
+    catch {
+        // Falls through: whatever went wrong, the other side can't be trusted with the rest.
+    }
+    throw new PairingEnded("tampered");
+}
+const MAX_NETWORK_RETRIES = 5;
+/** The other side's messages in order, long-polling the relay. `next` gives null once `deadline` passes. */
+export function mailbox(relay, id, token, clock) {
+    let after = 0;
+    const queue = [];
+    return {
+        async next(signal, deadline) {
+            for (let failures = 0;;) {
+                const queued = queue.shift();
+                if (queued)
+                    return queued;
+                const left = deadline === undefined ? 25_000 : deadline - clock.now();
+                if (left <= 0)
+                    return null;
+                try {
+                    for (const m of await relay.poll(id, token, after, Math.min(25, Math.ceil(left / 1000)), signal)) {
+                        if (m.seq > after)
+                            (queue.push(m), (after = m.seq));
+                    }
+                    failures = 0;
+                }
+                catch (e) {
+                    if (!(e instanceof PairingRelayError && e.code === "network") || ++failures > MAX_NETWORK_RETRIES)
+                        throw e;
+                    await clock.sleep(2000, signal);
+                }
+            }
+        },
+    };
+}

package/dist/pairing/interfaces.d.ts

@@ -0,0 +1,74 @@
+import type { PairingEnvelope } from "@gryt/crypto";
+import type { MlsAddOwnDeviceOptions, 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;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface PairingClock {
+    now(): number;
+    /** Resolves after `ms`, or rejects once `signal` aborts. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+}
+/** What N tells A about itself, shown on the approval screen. N chooses it, so A treats it as a claim. */
+export interface PairingDeviceInfo {
+    name: string;
+    app: string;
+    platform: string;
+}
+/** Tokens from the device grant. The ID token has already been checked against the envelope. */
+export interface PairingTokens {
+    idToken: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+}
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    expiresIn: number;
+    interval?: number;
+}
+export type DeviceTokenPoll = {
+    status: "pending" | "slow_down" | "denied" | "expired";
+} | {
+    status: "ok";
+    tokens: PairingTokens;
+};
+/** The two RFC 8628 calls, against `{issuer}/protocol/openid-connect/...`. Core makes the PKCE and nonce. */
+export interface PairingOidc {
+    deviceAuthorization(req: {
+        issuer: string;
+        clientId: string;
+        scope: string;
+        codeChallenge: string;
+        codeChallengeMethod: "S256";
+        nonce: string;
+    }): Promise<DeviceAuthorization>;
+    deviceToken(req: {
+        issuer: string;
+        clientId: string;
+        deviceCode: string;
+        codeVerifier: string;
+    }): Promise<DeviceTokenPoll>;
+}
+/** N's secure storage. Called once, only after every check has passed, with everything to keep. */
+export interface PairingStorage {
+    commit(envelope: PairingEnvelope, tokens: PairingTokens | null): Promise<void>;
+}
+/** N's MLS device on one server, sent to A in "ready" once its KeyPackages are published. */
+export interface PairedServerDevice {
+    host: string;
+    deviceId: string;
+}
+/** 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[]>;
+} | undefined;
+/** Why a pairing stopped. `approve:<error>` carries the extension's own error code. */
+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" | `approve:${string}`;

package/dist/pairing/interfaces.js

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

package/dist/pairing/newDevice.d.ts

@@ -0,0 +1,62 @@
+import { type PairingEmoji, type PairingServer } from "@gryt/crypto";
+import type { PairedServerDevice, PairingClock, PairingDeviceInfo, PairingEndReason, PairingOidc, PairingStorage } from "./interfaces.js";
+import type { PairingRelay } from "./relayClient.js";
+export type NewDeviceState = {
+    phase: "idle";
+} | {
+    phase: "opening";
+}
+/** `renewed` says why this is a fresh QR: the last one ran out, or A never approved. */
+ | {
+    phase: "showing";
+    qr: string;
+    code: string;
+    expiresAt: number;
+    renewed?: "expired" | "timed_out";
+} | {
+    phase: "comparing";
+    emoji: readonly PairingEmoji[];
+    deadline: number;
+} | {
+    phase: "signing_in";
+    username: string;
+    from: string;
+}
+/** Everything is written. The app joins `servers`, publishes KeyPackages, then calls `ready`. */
+ | {
+    phase: "joining";
+    servers: PairingServer[];
+    from: string;
+} | {
+    phase: "linked";
+    from: string;
+} | {
+    phase: "done";
+    from: string;
+} | {
+    phase: "ended";
+    reason: PairingEndReason;
+};
+export interface NewDeviceOptions {
+    relay: PairingRelay;
+    device: PairingDeviceInfo;
+    storage: PairingStorage;
+    oidc: PairingOidc;
+    clock?: PairingClock;
+    /** Only for a server with its own auth server: goes in the QR for A to check against its own. */
+    relayOrigin?: string;
+    approvalMs?: number;
+}
+export interface NewDevicePairing {
+    readonly state: NewDeviceState;
+    subscribe(listener: (state: NewDeviceState) => void): () => void;
+    start(): void;
+    /** In `joining`: N's device on each server, once its KeyPackages are up. */
+    ready(devices: PairedServerDevice[]): Promise<void>;
+    cancel(): Promise<void>;
+    /** "They don't match": the same as cancel, with a reason that says the link may be tampered with. */
+    mismatch(): Promise<void>;
+}
+export declare const PAIRING_APPROVAL_MS = 60000;
+/** N: shows the QR and code, checks the emoji, opens the envelope, signs in, then says ready. */
+export declare function createNewDevicePairing(options: NewDeviceOptions): NewDevicePairing;

package/dist/pairing/newDevice.js

@@ -0,0 +1,204 @@
+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";
+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. */
+export function createNewDevicePairing(options) {
+    const { relay, device, storage, oidc } = options;
+    const clock = options.clock ?? systemClock;
+    const approvalMs = options.approvalMs ?? PAIRING_APPROVAL_MS;
+    const listeners = new Set();
+    const abort = new AbortController();
+    let state = { phase: "idle" };
+    let current = null;
+    const set = (next) => {
+        if (state.phase === "ended" || state.phase === "done")
+            return;
+        state = next;
+        for (const l of listeners)
+            l(state);
+    };
+    const closeQuietly = () => (current ? relay.close(current.id, current.token).catch(() => undefined) : undefined);
+    const end = async (reason) => {
+        if (state.phase === "ended" || state.phase === "done")
+            return;
+        set({ phase: "ended", reason });
+        abort.abort();
+        current?.session?.close();
+        await closeQuietly();
+    };
+    async function attempt(renewed) {
+        set({ phase: "opening" });
+        const key = createPairingKey();
+        const created = await relay.create(base64Url(pairingCommitment(key.publicKey)));
+        const sessionId = decodePairingSessionId(created.id);
+        if (!sessionId)
+            throw new PairingEnded("relay_error");
+        const box = mailbox(relay, created.id, created.token, clock);
+        current = { id: created.id, token: created.token, box };
+        if (abort.signal.aborted) {
+            await closeQuietly();
+            throw new PairingEnded("cancelled");
+        }
+        const expiresAt = Date.parse(created.expiresAt);
+        const qr = formatPairingQr({ sessionId, publicKey: key.publicKey, relayOrigin: options.relayOrigin });
+        set({ phase: "showing", qr, code: formatPairingCode(created.code), expiresAt, ...(renewed ? { renewed } : {}) });
+        // No local deadline: the relay's clock decides, and its 410 is what renews the QR.
+        const claim = await box.next(abort.signal).catch((e) => {
+            if (reasonFor(e) === "expired")
+                return null;
+            throw e;
+        });
+        if (!claim)
+            return "expired";
+        if (claim.type !== "claim" || !claim.pkA)
+            throw new PairingEnded("tampered");
+        let session;
+        try {
+            session = current.session = startNewDeviceSession(key, { sessionId, approverPublicKey: base64UrlDecode(claim.pkA) });
+        }
+        catch {
+            throw new PairingEnded("tampered");
+        }
+        await relay.post(created.id, created.token, { type: "reveal", pkN: base64Url(key.publicKey) });
+        const deadline = clock.now() + approvalMs;
+        await relay.post(created.id, created.token, { type: "sealed", body: sealJson(session, { t: "hello", ...device, deadline }) });
+        set({ phase: "comparing", emoji: session.emoji, deadline });
+        const sealed = await box.next(abort.signal, deadline);
+        if (!sealed || clock.now() > deadline) {
+            session.close();
+            await closeQuietly();
+            return "timed_out";
+        }
+        try {
+            if (sealed.type !== "sealed" || !sealed.body)
+                throw new Error();
+            return decodePairingEnvelope(session.open(base64UrlDecode(sealed.body)));
+        }
+        catch (e) {
+            throw new PairingEnded(e instanceof Error && /newer version/.test(e.message) ? "newer_version" : "tampered");
+        }
+    }
+    async function signIn(account, from) {
+        const { id, token, box, session } = current;
+        set({ phase: "signing_in", username: account.username, from });
+        const verifier = base64Url(randomBytes(32));
+        const auth = await oidc.deviceAuthorization({
+            issuer: account.issuer,
+            clientId: account.clientId,
+            scope: PAIRING_OIDC_SCOPE,
+            codeChallenge: base64Url(sha256(new TextEncoder().encode(verifier))),
+            codeChallengeMethod: "S256",
+            nonce: session.keycloakNonce,
+        });
+        await relay.post(id, token, { type: "sealed", body: sealJson(session, { t: "user_code", userCode: auth.userCode }) });
+        // A sends nothing more here, so anything from the relay (a close, most likely) stops the polling.
+        const stop = new AbortController();
+        const onAbort = () => stop.abort();
+        abort.signal.addEventListener("abort", onAbort, { once: true });
+        let failure = null;
+        box.next(stop.signal).then(() => ((failure = new PairingEnded("tampered")), stop.abort()), (e) => (stop.signal.aborted ? undefined : ((failure = e), stop.abort())));
+        try {
+            let interval = (auth.interval ?? 5) * 1000;
+            for (const until = clock.now() + auth.expiresIn * 1000; clock.now() < until;) {
+                await clock.sleep(interval, stop.signal).catch(() => {
+                    throw failure ?? new PairingEnded("cancelled");
+                });
+                const polled = await oidc.deviceToken({
+                    issuer: account.issuer,
+                    clientId: account.clientId,
+                    deviceCode: auth.deviceCode,
+                    codeVerifier: verifier,
+                });
+                if (failure)
+                    throw failure;
+                if (polled.status === "ok")
+                    return checkIdToken(polled.tokens, account, session.keycloakNonce);
+                if (polled.status === "slow_down")
+                    interval += 5000;
+                else if (polled.status !== "pending")
+                    break;
+            }
+            throw new PairingEnded("sign_in_failed");
+        }
+        finally {
+            stop.abort();
+            abort.signal.removeEventListener("abort", onAbort);
+        }
+    }
+    async function run() {
+        try {
+            let outcome = await attempt();
+            while (typeof outcome === "string")
+                outcome = await attempt(outcome);
+            const envelope = outcome;
+            const tokens = envelope.account ? await signIn(envelope.account, envelope.from) : null;
+            await storage.commit(envelope, tokens);
+            set({ phase: "joining", servers: envelope.servers, from: envelope.from });
+        }
+        catch (e) {
+            if (!abort.signal.aborted)
+                await end(reasonFor(e));
+        }
+    }
+    async function linked(from) {
+        try {
+            // History from A lands here in a later version. Until then, A closing is the finish.
+            while (await current.box.next(abort.signal))
+                ;
+        }
+        catch (e) {
+            if (abort.signal.aborted)
+                return;
+            const reason = reasonFor(e);
+            if (reason !== "cancelled_by_other" && reason !== "expired")
+                return end(reason);
+            set({ phase: "done", from });
+            current?.session?.close();
+        }
+    }
+    return {
+        get state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        start() {
+            if (state.phase !== "idle")
+                throw new Error("This pairing has started already.");
+            void run();
+        },
+        async ready(devices) {
+            if (state.phase !== "joining" || !current?.session)
+                throw new Error("Not waiting to join.");
+            const { from } = state;
+            const body = sealJson(current.session, { t: "ready", devices: devices.map(({ host, deviceId }) => ({ host, deviceId })) });
+            await relay.post(current.id, current.token, { type: "sealed", body });
+            set({ phase: "linked", from });
+            void linked(from);
+        },
+        cancel: () => end("cancelled"),
+        mismatch: () => end("mismatch"),
+    };
+}
+/** Straight from the token endpoint over TLS, so the claims are read, not the signature (OIDC Core 3.1.3.7). */
+function checkIdToken(tokens, account, nonce) {
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(base64UrlDecode(tokens.idToken.split(".")[1] ?? "")));
+    }
+    catch {
+        throw new PairingEnded("sign_in_failed");
+    }
+    const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+    if (claims.nonce !== nonce || claims.iss !== account.issuer || !aud.includes(account.clientId)) {
+        throw new PairingEnded("tampered");
+    }
+    if (claims.sub !== account.sub)
+        throw new PairingEnded("wrong_account");
+    return tokens;
+}

package/dist/pairing/relayClient.d.ts

@@ -0,0 +1,45 @@
+import type { PairingFetch } from "./interfaces.js";
+/** A refusal from the relay: its status and the `error` it sent, or "network" when nothing came back. */
+export declare class PairingRelayError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+export interface RelayMessage {
+    seq: number;
+    type: "claim" | "reveal" | "sealed";
+    pkA?: string;
+    pkN?: string;
+    body?: string;
+}
+export interface PairingRelay {
+    create(commit: string): Promise<{
+        id: string;
+        code: string;
+        token: string;
+        expiresAt: string;
+    }>;
+    claim(by: {
+        id: string;
+    } | {
+        code: string;
+    }, pkA: string): Promise<{
+        id: string;
+        token: string;
+        commit: string;
+        location: string | null;
+        yourLocation: string | null;
+    }>;
+    post(id: string, token: string, message: {
+        type: "reveal";
+        pkN: string;
+    } | {
+        type: "sealed";
+        body: string;
+    }): Promise<void>;
+    /** 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>;
+}
+/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. */
+export declare function createPairingRelay(origin: string, fetch: PairingFetch): PairingRelay;

package/dist/pairing/relayClient.js

@@ -0,0 +1,48 @@
+/** A refusal from the relay: its status and the `error` it sent, or "network" when nothing came back. */
+export class PairingRelayError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`Pairing relay: ${status} ${code}`);
+        this.name = "PairingRelayError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/** The relay's HTTP API as auth#45 built it, under `{origin}/api/v1/pairing`. */
+export function createPairingRelay(origin, fetch) {
+    const base = `${origin.replace(/\/+$/, "")}/api/v1/pairing/sessions`;
+    async function call(method, path, body, token, signal) {
+        const headers = {};
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        let res;
+        try {
+            res = await fetch(`${base}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal });
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            throw new PairingRelayError(0, "network");
+        }
+        if (res.status === 204)
+            return {};
+        const json = (await res.json().catch(() => null));
+        if (res.status >= 400 || !json)
+            throw new PairingRelayError(res.status, String(json?.error ?? "unknown"));
+        return json;
+    }
+    const path = (id) => `/${encodeURIComponent(id)}`;
+    return {
+        create: async (commit) => (await call("POST", "", { commit })),
+        claim: async (by, pkA) => (await call("POST", "/claim", { ...by, pkA })),
+        post: async (id, token, message) => void (await call("POST", `${path(id)}/messages`, message, token)),
+        poll: async (id, token, after, waitSeconds, signal) => {
+            const res = await call("GET", `${path(id)}/messages?after=${after}&wait=${waitSeconds}`, undefined, token, signal);
+            return (Array.isArray(res.messages) ? res.messages : []);
+        },
+        close: async (id, token) => void (await call("DELETE", path(id), undefined, token)),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/core",
-  "version": "0.13.0",
+  "version": "0.14.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": {
@@ -35,6 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@gryt/crypto": "0.7.0"
+    "@gryt/crypto": "0.8.0",
+    "@noble/hashes": "^2.3.0"
   }
 }