@vex-chat/libvex 5.4.0 → 5.5.1

package/src/Client.ts

@@ -89,14 +89,56 @@ import {
     isFipsSubsequentExtraV1,
 } from "./utils/fipsMailExtra.js";
 
-function sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function debugLibvexDm(
+    msg: string,
+    data?: Record<string, boolean | null | number | string | undefined>,
+): void {
+    if (!libvexDebugDmEnabled()) {
+        return;
+    }
+    const payload = data ? `${msg} ${JSON.stringify(data)}` : msg;
+    // eslint-disable-next-line no-console -- gated by LIBVEX_DEBUG_DM; remove when debugging is done
+    console.error(`[libvex:debug-dm] ${payload}`);
 }
 
 function isRecord(x: unknown): x is Record<string, unknown> {
     return typeof x === "object" && x !== null;
 }
 
+/**
+ * Set `LIBVEX_DEBUG_DM=1` (e.g. in vitest / shell) to log DM multi-device / X3DH paths.
+ * Uses indirect `globalThis` lookup so the bare `process` global never appears in
+ * source that the platform-guard plugin scans (browser/RN/Tauri).
+ */
+function libvexDebugDmEnabled(): boolean {
+    try {
+        const g = Object.getOwnPropertyDescriptor(globalThis, "\u0070rocess");
+        if (!g) {
+            return false;
+        }
+        const proc: unknown = typeof g.get === "function" ? g.get() : g.value;
+        if (typeof proc !== "object" || proc === null) {
+            return false;
+        }
+        const envDesc = Object.getOwnPropertyDescriptor(proc, "env");
+        if (!envDesc) {
+            return false;
+        }
+        const env: unknown =
+            typeof envDesc.get === "function" ? envDesc.get() : envDesc.value;
+        if (typeof env !== "object" || env === null) {
+            return false;
+        }
+        return Reflect.get(env, "LIBVEX_DEBUG_DM") === "1";
+    } catch {
+        return false;
+    }
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 /**
  * Spire 5+ JSON error bodies use `{ "error": { "message", "requestId"?, "details"? } }`.
  * Responses are `arraybuffer` — decode UTF-8 and parse for a one-line `Error` message
@@ -149,48 +191,6 @@ function spireErrorBodyMessage(data: unknown, max = 8_000): string {
     return t.length > max ? t.slice(0, max) + "…" : t;
 }
 
-/**
- * Set `LIBVEX_DEBUG_DM=1` (e.g. in vitest / shell) to log DM multi-device / X3DH paths.
- * Uses indirect `globalThis` lookup so the bare `process` global never appears in
- * source that the platform-guard plugin scans (browser/RN/Tauri).
- */
-function libvexDebugDmEnabled(): boolean {
-    try {
-        const g = Object.getOwnPropertyDescriptor(globalThis, "\u0070rocess");
-        if (!g) {
-            return false;
-        }
-        const proc: unknown = typeof g.get === "function" ? g.get() : g.value;
-        if (typeof proc !== "object" || proc === null) {
-            return false;
-        }
-        const envDesc = Object.getOwnPropertyDescriptor(proc, "env");
-        if (!envDesc) {
-            return false;
-        }
-        const env: unknown =
-            typeof envDesc.get === "function" ? envDesc.get() : envDesc.value;
-        if (typeof env !== "object" || env === null) {
-            return false;
-        }
-        return Reflect.get(env, "LIBVEX_DEBUG_DM") === "1";
-    } catch {
-        return false;
-    }
-}
-
-function debugLibvexDm(
-    msg: string,
-    data?: Record<string, string | number | boolean | null | undefined>,
-): void {
-    if (!libvexDebugDmEnabled()) {
-        return;
-    }
-    const payload = data ? `${msg} ${JSON.stringify(data)}` : msg;
-    // eslint-disable-next-line no-console -- gated by LIBVEX_DEBUG_DM; remove when debugging is done
-    console.error(`[libvex:debug-dm] ${payload}`);
-}
-
 import { msgpack } from "./codec.js";
 import {
     ActionTokenCodec,
@@ -202,6 +202,7 @@ import {
     DeviceArrayCodec,
     DeviceChallengeCodec,
     DeviceCodec,
+    DeviceRegistrationResultCodec,
     EmojiArrayCodec,
     EmojiCodec,
     FileSQLCodec,
@@ -209,6 +210,8 @@ import {
     InviteCodec,
     KeyBundleCodec,
     OtkCountCodec,
+    PendingDeviceRequestArrayCodec,
+    PendingDeviceRequestCodec,
     PermissionArrayCodec,
     PermissionCodec,
     ServerArrayCodec,
@@ -276,6 +279,12 @@ export interface ClientOptions {
     cryptoProfile?: "fips" | "tweetnacl";
     /** Folder path where the sqlite file is created. */
     dbFolder?: string;
+    /**
+     * When set (non-empty), sent as `x-dev-api-key` on every HTTP request.
+     * Spire omits in-process rate limits when this matches the server's `DEV_API_KEY`
+     * (local / load-testing only — never use in production).
+     */
+    devApiKey?: string;
     /** Platform label for device registration (e.g. "ios", "macos", "linux"). */
     deviceName?: string;
     /** API host without protocol. Defaults to `api.vex.wtf`. */
@@ -286,46 +295,30 @@ export interface ClientOptions {
     saveHistory?: boolean;
     /** Use `http/ws` instead of `https/wss`. Intended for local/dev environments. */
     unsafeHttp?: boolean;
-    /**
-     * When set (non-empty), sent as `x-dev-api-key` on every HTTP request.
-     * Spire omits in-process rate limits when this matches the server's `DEV_API_KEY`
-     * (local / load-testing only — never use in production).
-     */
-    devApiKey?: string;
 }
 
+export type DeviceRegistrationResult = Device | PendingDeviceRegistration;
+
 /**
  * @ignore
  */
 export interface Devices {
+    /** Approves a pending device registration request as the current device. */
+    approveRequest: (requestID: string) => Promise<Device>;
     /** Deletes one of the account's devices (except the currently active one). */
     delete: (deviceID: string) => Promise<void>;
+    /** Fetches one pending registration request by ID for the current user. */
+    getRequest: (requestID: string) => Promise<null | PendingDeviceRequest>;
+    /** Lists pending/processed registration requests for the current user. */
+    listRequests: () => Promise<PendingDeviceRequest[]>;
     /** Registers the current key material as a new device. */
-    register: () => Promise<Device | null>;
+    register: () => Promise<DeviceRegistrationResult | null>;
+    /** Rejects a pending device registration request as the current device. */
+    rejectRequest: (requestID: string) => Promise<void>;
     /** Fetches one device by ID. */
     retrieve: (deviceIdentifier: string) => Promise<Device | null>;
 }
 
-/**
- * Channel is a chat channel on a server.
- *
- * Common fields:
- * - `channelID`
- * - `serverID`
- * - `name`
- */
-export type { Channel } from "@vex-chat/types";
-
-/**
- * Server is a single chat server.
- *
- * Common fields:
- * - `serverID`
- * - `name`
- * - `icon` (optional URL/data)
- */
-export type { Server } from "@vex-chat/types";
-
 /**
  * @ignore
  */
@@ -379,6 +372,26 @@ export interface FileProgress {
  */
 export type FileRes = FileResponse;
 
+/**
+ * Channel is a chat channel on a server.
+ *
+ * Common fields:
+ * - `channelID`
+ * - `serverID`
+ * - `name`
+ */
+export type { Channel } from "@vex-chat/types";
+
+/**
+ * Server is a single chat server.
+ *
+ * Common fields:
+ * - `serverID`
+ * - `name`
+ * - `icon` (optional URL/data)
+ */
+export type { Server } from "@vex-chat/types";
+
 /**
  * @ignore
  */
@@ -454,6 +467,31 @@ export interface Message {
     timestamp: string;
 }
 
+export type PendingDeviceApprovalStatus =
+    | "approved"
+    | "expired"
+    | "pending"
+    | "rejected";
+
+export interface PendingDeviceRegistration {
+    challenge: string;
+    expiresAt: string;
+    requestID: string;
+    status: "pending_approval";
+}
+
+export interface PendingDeviceRequest {
+    approvedDeviceID?: string | undefined;
+    createdAt: string;
+    deviceName: string;
+    error?: string | undefined;
+    expiresAt: string;
+    requestID: string;
+    signKey: string;
+    status: PendingDeviceApprovalStatus;
+    username: string;
+}
+
 /** Zod schema matching the {@link Message} interface for forwarded-message decode. */
 const messageSchema: z.ZodType<Message> = z.object({
     authorID: z.string(),
@@ -476,6 +514,14 @@ const mailInboxEntry = z.tuple([
     MailWSSchema,
     z.string(),
 ]);
+const deviceRequestNotifyData = z.object({
+    requestID: z.string(),
+    status: z.union([
+        z.literal("approved"),
+        z.literal("pending"),
+        z.literal("rejected"),
+    ]),
+});
 
 /**
  * Event signatures emitted by {@link Client}.
@@ -490,6 +536,14 @@ export interface ClientEvents {
     connected: () => void;
     /** Mail decryption pass is in progress. */
     decryptingMail: () => void;
+    /** Device approval queue changed (pending/approved/rejected). */
+    deviceRequest: (update: {
+        requestID: string;
+        status: Extract<
+            PendingDeviceApprovalStatus,
+            "approved" | "pending" | "rejected"
+        >;
+    }) => void;
     /** WebSocket connection lost. */
     disconnect: () => void;
     /** Progress update for a file upload or download. */
@@ -748,8 +802,12 @@ export class Client {
      * Device management methods.
      */
     public devices: Devices = {
+        approveRequest: this.approveDeviceRequest.bind(this),
         delete: this.deleteDevice.bind(this),
+        getRequest: this.getDeviceRegistrationRequest.bind(this),
+        listRequests: this.listDeviceRegistrationRequests.bind(this),
         register: this.registerDevice.bind(this),
+        rejectRequest: this.rejectDeviceRequest.bind(this),
         retrieve: this.getDeviceByID.bind(this),
     };
 
@@ -967,6 +1025,8 @@ export class Client {
         retrieve: this.fetchUser.bind(this),
     };
 
+    private readonly cryptoProfile: CryptoProfile;
+
     private readonly database: Storage;
 
     private readonly dbPath: string;
@@ -977,34 +1037,28 @@ export class Client {
 
     // ── Event subscription (composition over inheritance) ───────────────
     private readonly emitter = new EventEmitter<ClientEvents>();
-
     private fetchingMail: boolean = false;
+
     private firstMailFetch = true;
 
     private readonly forwarded = new Set<string>();
-
     private readonly host: string;
-    /**
-     * Node-only: per-client HTTP(S) agents (see `init()` + `storage/node/http-agents`).
-     * Dropped on `close()` so idle keep-alive sockets do not keep the process alive.
-     */
-    private nodeHttpAgents?: {
-        http: { destroy(): void };
-        https: { destroy(): void };
-    };
+    private readonly http: AxiosInstance;
     /** Cancels in-flight axios work on `close()` so `postAuth`/`getMail` cannot hang forever. */
     private readonly httpAbortController = new AbortController();
-    private readonly http: AxiosInstance;
     private readonly idKeys: KeyPair | null;
     private isAlive: boolean = true;
     private readonly mailInterval?: NodeJS.Timeout;
 
     private manuallyClosing: boolean = false;
     /**
-     * Bumped when the WebSocket is torn down and re-opened so the previous
-     * `postAuth` loop exits instead of overlapping a new one.
+     * Node-only: per-client HTTP(S) agents (see `init()` + `storage/node/http-agents`).
+     * Dropped on `close()` so idle keep-alive sockets do not keep the process alive.
      */
-    private postAuthVersion = 0;
+    private nodeHttpAgents?: {
+        http: { destroy(): void };
+        https: { destroy(): void };
+    };
     /* Retrieves the userID with the user identifier.
     user identifier is checked for userID, then signkey,
     and finally falls back to username. */
@@ -1014,24 +1068,28 @@ export class Client {
     private readonly options?: ClientOptions | undefined;
 
     private pingInterval: null | ReturnType<typeof setTimeout> = null;
+    /**
+     * Bumped when the WebSocket is torn down and re-opened so the previous
+     * `postAuth` loop exits instead of overlapping a new one.
+     */
+    private postAuthVersion = 0;
+
     private readonly prefixes:
         | { HTTP: "http://"; WS: "ws://" }
         | { HTTP: "https://"; WS: "wss://" };
-
     private reading: boolean = false;
     private readonly seenMailIDs: Set<string> = new Set();
     private sessionRecords: Record<string, SessionCrypto> = {};
+
     // these are created from one set of sign keys
     private readonly signKeys: KeyPair;
-
     private socket: WebSocketLike;
     private token: null | string = null;
+
     private user?: User;
 
     private userRecords: Record<string, User> = {};
-
     private xKeyRing?: XKeyRing;
-    private readonly cryptoProfile: CryptoProfile;
 
     private constructor(
         material: {
@@ -1246,32 +1304,6 @@ export class Client {
         return xMnemonic(xKDF(XUtils.decodeHex(session.fingerprint)));
     }
 
-    /**
-     * True when running under Node (has `process.versions`).
-     * Uses indirect lookup so the bare `process` global never appears in
-     * source that the platform-guard plugin scans.
-     */
-    private static isNodeRuntime(): boolean {
-        try {
-            const g = Object.getOwnPropertyDescriptor(
-                globalThis,
-                "\u0070rocess",
-            );
-            if (!g) return false;
-            const proc: unknown =
-                typeof g.get === "function" ? g.get() : g.value;
-            if (typeof proc !== "object" || proc === null) {
-                return false;
-            }
-            return (
-                "versions" in proc &&
-                typeof (proc as { versions?: unknown }).versions === "object"
-            );
-        } catch {
-            return false;
-        }
-    }
-
     /**
      * Browser-safe NODE_ENV accessor.
      * Uses indirect lookup so the bare `process` global never appears in
@@ -1312,12 +1344,29 @@ export class Client {
     }
 
     /**
-     * Fresh read of the `manuallyClosing` flag for async loops — direct property checks
-     * after `await` are flagged as always-false by control-flow analysis even though
-     * `close()` can run concurrently.
+     * True when running under Node (has `process.versions`).
+     * Uses indirect lookup so the bare `process` global never appears in
+     * source that the platform-guard plugin scans.
      */
-    private isManualCloseInFlight(): boolean {
-        return this.manuallyClosing;
+    private static isNodeRuntime(): boolean {
+        try {
+            const g = Object.getOwnPropertyDescriptor(
+                globalThis,
+                "\u0070rocess",
+            );
+            if (!g) return false;
+            const proc: unknown =
+                typeof g.get === "function" ? g.get() : g.value;
+            if (typeof proc !== "object" || proc === null) {
+                return false;
+            }
+            return (
+                "versions" in proc &&
+                typeof (proc as { versions?: unknown }).versions === "object"
+            );
+        } catch {
+            return false;
+        }
     }
 
     /**
@@ -1392,62 +1441,6 @@ export class Client {
         await this.negotiateOTK();
     }
 
-    /**
-     * Tears down the current WebSocket and opens a new one, keeping the same
-     * session (user + device in storage). Restarts the post-auth mail loop.
-     * Use for long-running processes or e2e where a fresh socket matches a
-     * newly-registered second device.
-     */
-    public async reconnectWebsocket(): Promise<void> {
-        this.postAuthVersion++;
-        if (this.pingInterval) {
-            clearInterval(this.pingInterval);
-            this.pingInterval = null;
-        }
-        this.socket.close();
-        try {
-            await new Promise<void>((resolve, reject) => {
-                const t = setTimeout(() => {
-                    this.off("connected", onC);
-                    reject(
-                        new Error(
-                            "reconnectWebsocket: timed out waiting for authorized",
-                        ),
-                    );
-                }, 15_000);
-                const onC = () => {
-                    clearTimeout(t);
-                    this.off("connected", onC);
-                    resolve();
-                };
-                this.on("connected", onC);
-                try {
-                    this.initSocket();
-                } catch (err: unknown) {
-                    clearTimeout(t);
-                    this.off("connected", onC);
-                    const e =
-                        err instanceof Error
-                            ? err
-                            : new Error(String(err), { cause: err });
-                    reject(e);
-                }
-            });
-        } catch (e: unknown) {
-            throw e instanceof Error ? e : new Error(String(e), { cause: e });
-        }
-        await new Promise((r) => setTimeout(r, 0));
-        await this.negotiateOTK();
-    }
-
-    /**
-     * Triggers an immediate inbox sync by fetching `/mail` once.
-     * Useful on mobile foreground resume where background work may pause.
-     */
-    public async syncInboxNow(): Promise<void> {
-        await this.getMail();
-    }
-
     /**
      * Delete all local data — message history, encryption sessions, and prekeys.
      * Closes the client afterward. Credentials (keychain) must be cleared by the consumer.
@@ -1626,6 +1619,54 @@ export class Client {
         return this;
     }
 
+    /**
+     * Tears down the current WebSocket and opens a new one, keeping the same
+     * session (user + device in storage). Restarts the post-auth mail loop.
+     * Use for long-running processes or e2e where a fresh socket matches a
+     * newly-registered second device.
+     */
+    public async reconnectWebsocket(): Promise<void> {
+        this.postAuthVersion++;
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+        this.socket.close();
+        try {
+            await new Promise<void>((resolve, reject) => {
+                const t = setTimeout(() => {
+                    this.off("connected", onC);
+                    reject(
+                        new Error(
+                            "reconnectWebsocket: timed out waiting for authorized",
+                        ),
+                    );
+                }, 15_000);
+                const onC = () => {
+                    clearTimeout(t);
+                    this.off("connected", onC);
+                    resolve();
+                };
+                this.on("connected", onC);
+                try {
+                    this.initSocket();
+                } catch (err: unknown) {
+                    clearTimeout(t);
+                    this.off("connected", onC);
+                    const e =
+                        err instanceof Error
+                            ? err
+                            : new Error(String(err), { cause: err });
+                    reject(e);
+                }
+            });
+        } catch (e: unknown) {
+            throw e instanceof Error ? e : new Error(String(e), { cause: e });
+        }
+        await new Promise((r) => setTimeout(r, 0));
+        await this.negotiateOTK();
+    }
+
     /**
      * Registers a new account on the server.
      *
@@ -1699,6 +1740,14 @@ export class Client {
         return this;
     }
 
+    /**
+     * Triggers an immediate inbox sync by fetching `/mail` once.
+     * Useful on mobile foreground resume where background work may pause.
+     */
+    public async syncInboxNow(): Promise<void> {
+        await this.getMail();
+    }
+
     /**
      * Returns a compact `<username><deviceID>` debug label.
      */
@@ -1732,6 +1781,36 @@ export class Client {
         return whoami;
     }
 
+    private async approveDeviceRequest(requestID: string): Promise<Device> {
+        const req = await this.getDeviceRegistrationRequest(requestID);
+        if (!req) {
+            throw new Error("Device approval request not found.");
+        }
+        if (req.status !== "pending") {
+            throw new Error(
+                "Device approval request is not pending: " + req.status,
+            );
+        }
+        const signed = XUtils.encodeHex(
+            await xSignAsync(
+                XUtils.decodeUTF8(requestID),
+                this.signKeys.secretKey,
+            ),
+        );
+        const response = await this.http.post(
+            this.prefixes.HTTP +
+                this.host +
+                "/user/" +
+                this.getUser().userID +
+                "/devices/requests/" +
+                requestID +
+                "/approve",
+            msgpack.encode({ signed }),
+            { headers: { "Content-Type": "application/msgpack" } },
+        );
+        return decodeAxios(DeviceCodec, response.data);
+    }
+
     private censorPreKey(preKey: PreKeysSQL): PreKeysWS {
         if (!preKey.index) {
             throw new Error("Key index is required.");
@@ -1852,31 +1931,10 @@ export class Client {
     }
 
     private async createServer(name: string): Promise<Server> {
-        const res = await this.http.post(
-            this.getHost() + "/server/" + globalThis.btoa(name),
-        );
-        return decodeAxios(ServerCodec, res.data);
-    }
-
-    /**
-     * `xDHAsync` and other helpers in `@vex-chat/crypto` use the process-wide
-     * active profile. When several {@link Client} instances use different
-     * `cryptoProfile` values, scope the global to this instance for the duration
-     * of that crypto work.
-     */
-    private async runWithThisCryptoProfile<T>(
-        fn: () => Promise<T>,
-    ): Promise<T> {
-        const prev = getCryptoProfile();
-        if (prev === this.cryptoProfile) {
-            return await fn();
-        }
-        setCryptoProfile(this.cryptoProfile);
-        try {
-            return await fn();
-        } finally {
-            setCryptoProfile(prev);
-        }
+        const res = await this.http.post(
+            this.getHost() + "/server/" + globalThis.btoa(name),
+        );
+        return decodeAxios(ServerCodec, res.data);
     }
 
     private async createSession(
@@ -2111,6 +2169,21 @@ export class Client {
     private async deleteServer(serverID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/server/" + serverID);
     }
+
+    private deviceListFailureDetail(err: unknown): string {
+        if (!isAxiosError(err)) {
+            return "";
+        }
+        const st = err.response?.status;
+        if (typeof st === "number") {
+            return ` (HTTP ${String(st)})`;
+        }
+        if (err.code !== undefined) {
+            return ` (${err.code})`;
+        }
+        return "";
+    }
+
     /**
      * Gets a list of permissions for a server.
      *
@@ -2160,6 +2233,56 @@ export class Client {
         }
     }
 
+    private async fetchUserDeviceListOnce(userID: string): Promise<Device[]> {
+        if (this.isManualCloseInFlight()) {
+            return [];
+        }
+        const res = await this.http.get(
+            this.getHost() + "/user/" + userID + "/devices",
+        );
+        const devices = decodeAxios(DeviceArrayCodec, res.data);
+        for (const device of devices) {
+            this.deviceRecords[device.deviceID] = device;
+        }
+        return devices;
+    }
+
+    /**
+     * DM / forward paths need the peer’s (or self) device rows under load: bounded
+     * retries with exponential backoff (same shape as session pubkey hydration).
+     */
+    private async fetchUserDeviceListWithBackoff(
+        userID: string,
+        label: "own" | "peer",
+    ): Promise<Device[]> {
+        const base =
+            label === "own"
+                ? "Couldn't get own devices"
+                : "Couldn't get device list";
+        let lastErr: unknown;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            if (this.isManualCloseInFlight()) {
+                return [];
+            }
+            if (attempt > 0) {
+                const delayMs = 100 * 2 ** (attempt - 1);
+                // Chunk the delay so close() can finish before we retry HTTP.
+                const chunkMs = 10;
+                for (let elapsed = 0; elapsed < delayMs; elapsed += chunkMs) {
+                    if (this.isManualCloseInFlight()) {
+                        return [];
+                    }
+                    await sleep(Math.min(chunkMs, delayMs - elapsed));
+                }
+            }
+            try {
+                return await this.fetchUserDeviceListOnce(userID);
+            } catch (err: unknown) {
+                lastErr = err;
+            }
+        }
+        throw new Error(`${base}${this.deviceListFailureDetail(lastErr)}`);
+    }
     private async forward(message: Message) {
         if (this.isManualCloseInFlight()) {
             return;
@@ -2252,6 +2375,27 @@ export class Client {
         }
     }
 
+    private async getDeviceRegistrationRequest(
+        requestID: string,
+    ): Promise<null | PendingDeviceRequest> {
+        try {
+            const response = await this.http.get(
+                this.prefixes.HTTP +
+                    this.host +
+                    "/user/" +
+                    this.getUser().userID +
+                    "/devices/requests/" +
+                    requestID,
+            );
+            return decodeAxios(PendingDeviceRequestCodec, response.data);
+        } catch (err: unknown) {
+            if (isAxiosError(err) && err.response?.status === 404) {
+                return null;
+            }
+            throw err;
+        }
+    }
+
     /* Retrieves the current list of users you have sessions with. */
     private async getFamiliars(): Promise<User[]> {
         const sessions = await this.database.getAllSessions();
@@ -2314,8 +2458,8 @@ export class Client {
                     }
                 })();
                 debugLibvexDm("getMail: inbox", {
-                    deviceID: did,
                     count: String(inbox.length),
+                    deviceID: did,
                 });
             }
 
@@ -2325,8 +2469,8 @@ export class Client {
                     if (libvexDebugDmEnabled()) {
                         debugLibvexDm("getMail: readMail one", {
                             mailID: mailBody.mailID,
-                            type: String(mailBody.mailType),
                             recipient: mailBody.recipient,
+                            type: String(mailBody.mailType),
                         });
                     }
                     await this.readMail(mailHeader, mailBody, timestamp);
@@ -2464,20 +2608,6 @@ export class Client {
         return this.user;
     }
 
-    private deviceListFailureDetail(err: unknown): string {
-        if (!isAxiosError(err)) {
-            return "";
-        }
-        const st = err.response?.status;
-        if (typeof st === "number") {
-            return ` (HTTP ${String(st)})`;
-        }
-        if (err.code !== undefined) {
-            return ` (${err.code})`;
-        }
-        return "";
-    }
-
     /**
      * Single GET for `/user/:id/devices`. On failure returns `null` (swallows errors)
      * — callers that need reliability should use `fetchUserDeviceListWithBackoff`.
@@ -2492,57 +2622,6 @@ export class Client {
         }
     }
 
-    private async fetchUserDeviceListOnce(userID: string): Promise<Device[]> {
-        if (this.isManualCloseInFlight()) {
-            return [];
-        }
-        const res = await this.http.get(
-            this.getHost() + "/user/" + userID + "/devices",
-        );
-        const devices = decodeAxios(DeviceArrayCodec, res.data);
-        for (const device of devices) {
-            this.deviceRecords[device.deviceID] = device;
-        }
-        return devices;
-    }
-
-    /**
-     * DM / forward paths need the peer’s (or self) device rows under load: bounded
-     * retries with exponential backoff (same shape as session pubkey hydration).
-     */
-    private async fetchUserDeviceListWithBackoff(
-        userID: string,
-        label: "peer" | "own",
-    ): Promise<Device[]> {
-        const base =
-            label === "own"
-                ? "Couldn't get own devices"
-                : "Couldn't get device list";
-        let lastErr: unknown;
-        for (let attempt = 0; attempt < 5; attempt++) {
-            if (this.isManualCloseInFlight()) {
-                return [];
-            }
-            if (attempt > 0) {
-                const delayMs = 100 * 2 ** (attempt - 1);
-                // Chunk the delay so close() can finish before we retry HTTP.
-                const chunkMs = 10;
-                for (let elapsed = 0; elapsed < delayMs; elapsed += chunkMs) {
-                    if (this.isManualCloseInFlight()) {
-                        return [];
-                    }
-                    await sleep(Math.min(chunkMs, delayMs - elapsed));
-                }
-            }
-            try {
-                return await this.fetchUserDeviceListOnce(userID);
-            } catch (err: unknown) {
-                lastErr = err;
-            }
-        }
-        throw new Error(`${base}${this.deviceListFailureDetail(lastErr)}`);
-    }
-
     private async getUserList(channelID: string): Promise<User[]> {
         const res = await this.http.post(
             this.getHost() + "/userList/" + channelID,
@@ -2552,6 +2631,13 @@ export class Client {
 
     private async handleNotify(msg: NotifyMsg) {
         switch (msg.event) {
+            case "deviceRequest": {
+                const parsed = deviceRequestNotifyData.safeParse(msg.data);
+                if (parsed.success) {
+                    this.emitter.emit("deviceRequest", parsed.data);
+                }
+                break;
+            }
             case "mail":
                 await this.getMail();
                 this.fetchingMail = false;
@@ -2570,28 +2656,6 @@ export class Client {
         }
     }
 
-    /**
-     * Pipeline for decrypted messages — registered in `init`. After `close()` sets
-     * `manuallyClosing`, this becomes a no-op so fire-and-forget `forward` does not
-     * race HTTP teardown (we avoid `off()` here — it can interact badly with emit).
-     */
-    private readonly onInternalMessage = (message: Message): void => {
-        if (this.isManualCloseInFlight()) {
-            return;
-        }
-        if (message.direction === "outgoing" && !message.forward) {
-            void this.forward(message);
-        }
-
-        if (
-            message.direction === "incoming" &&
-            message.recipient === message.sender
-        ) {
-            return;
-        }
-        void this.database.saveMessage(message);
-    };
-
     /**
      * Initializes the keyring. This must be called before anything else.
      */
@@ -2693,6 +2757,15 @@ export class Client {
         }
     }
 
+    /**
+     * Fresh read of the `manuallyClosing` flag for async loops — direct property checks
+     * after `await` are flagged as always-false by control-flow analysis even though
+     * `close()` can run concurrently.
+     */
+    private isManualCloseInFlight(): boolean {
+        return this.manuallyClosing;
+    }
+
     private async kickUser(userID: string, serverID: string): Promise<void> {
         const permissionList = await this.fetchPermissionList(serverID);
         for (const permission of permissionList) {
@@ -2713,6 +2786,19 @@ export class Client {
         }
     }
 
+    private async listDeviceRegistrationRequests(): Promise<
+        PendingDeviceRequest[]
+    > {
+        const response = await this.http.get(
+            this.prefixes.HTTP +
+                this.host +
+                "/user/" +
+                this.getUser().userID +
+                "/devices/requests",
+        );
+        return decodeAxios(PendingDeviceRequestArrayCodec, response.data);
+    }
+
     private async markSessionVerified(sessionID: string) {
         return this.database.markSessionVerified(sessionID);
     }
@@ -2737,6 +2823,28 @@ export class Client {
         this.xKeyRing.ephemeralKeys = await xBoxKeyPairAsync();
     }
 
+    /**
+     * Pipeline for decrypted messages — registered in `init`. After `close()` sets
+     * `manuallyClosing`, this becomes a no-op so fire-and-forget `forward` does not
+     * race HTTP teardown (we avoid `off()` here — it can interact badly with emit).
+     */
+    private readonly onInternalMessage = (message: Message): void => {
+        if (this.isManualCloseInFlight()) {
+            return;
+        }
+        if (message.direction === "outgoing" && !message.forward) {
+            void this.forward(message);
+        }
+
+        if (
+            message.direction === "incoming" &&
+            message.recipient === message.sender
+        ) {
+            return;
+        }
+        void this.database.saveMessage(message);
+    };
+
     private ping() {
         if (!this.isAlive) {
         }
@@ -2881,9 +2989,7 @@ export class Client {
                         void this.createSession(
                             deviceEntry,
                             user,
-                            XUtils.decodeUTF8(
-                                `��RETRY_REQUEST:${mail.mailID}��`,
-                            ),
+                            new Uint8Array(),
                             mail.group,
                             uuid.v4(),
                             false,
@@ -2923,10 +3029,10 @@ export class Client {
                                         "readMail initial: abort (otk index mismatch)",
                                         {
                                             mailID: mail.mailID,
-                                            preKeyIndex: String(preKeyIndex),
                                             otkIndex: String(
                                                 otk?.index ?? "null",
                                             ),
+                                            preKeyIndex: String(preKeyIndex),
                                             thisDevice:
                                                 this.getDevice().deviceID,
                                         },
@@ -2963,8 +3069,8 @@ export class Client {
                                     debugLibvexDm(
                                         "readMail initial: abort (IK_A null, Ed→X25519?)",
                                         {
-                                            mailID: mail.mailID,
                                             fips: String(fipsRead),
+                                            mailID: mail.mailID,
                                             thisDevice:
                                                 this.getDevice().deviceID,
                                         },
@@ -3091,12 +3197,12 @@ export class Client {
                                         "readMail initial: ok (emit message)",
                                         {
                                             mailID: mail.mailID,
-                                            preKeyIndex: String(preKeyIndex),
-                                            thisDevice:
-                                                this.getDevice().deviceID,
                                             plaintextLen: String(
                                                 plaintext.length,
                                             ),
+                                            preKeyIndex: String(preKeyIndex),
+                                            thisDevice:
+                                                this.getDevice().deviceID,
                                         },
                                     );
                                 } catch {
@@ -3283,7 +3389,7 @@ export class Client {
         return decodeAxios(PermissionCodec, res.data);
     }
 
-    private async registerDevice(): Promise<Device | null> {
+    private async registerDevice(): Promise<DeviceRegistrationResult | null> {
         while (!this.xKeyRing) {
             await sleep(100);
         }
@@ -3336,7 +3442,19 @@ export class Client {
             msgpack.encode(devMsg),
             { headers: { "Content-Type": "application/msgpack" } },
         );
-        return decodeAxios(DeviceCodec, res.data);
+        return decodeAxios(DeviceRegistrationResultCodec, res.data);
+    }
+
+    private async rejectDeviceRequest(requestID: string): Promise<void> {
+        await this.http.post(
+            this.prefixes.HTTP +
+                this.host +
+                "/user/" +
+                this.getUser().userID +
+                "/devices/requests/" +
+                requestID +
+                "/reject",
+        );
     }
 
     private async respond(msg: ChallMsg) {
@@ -3444,8 +3562,13 @@ export class Client {
                 await this.populateKeyRing();
 
                 const newDevice = await this.registerDevice();
-                if (newDevice) {
+                if (newDevice && "deviceID" in newDevice) {
                     device = newDevice;
+                } else if (newDevice && "status" in newDevice) {
+                    throw new Error(
+                        "Device registration requires approval from an existing device. requestID=" +
+                            newDevice.requestID,
+                    );
                 } else {
                     throw new Error("Error registering device.");
                 }
@@ -3456,6 +3579,27 @@ export class Client {
         return device;
     }
 
+    /**
+     * `xDHAsync` and other helpers in `@vex-chat/crypto` use the process-wide
+     * active profile. When several {@link Client} instances use different
+     * `cryptoProfile` values, scope the global to this instance for the duration
+     * of that crypto work.
+     */
+    private async runWithThisCryptoProfile<T>(
+        fn: () => Promise<T>,
+    ): Promise<T> {
+        const prev = getCryptoProfile();
+        if (prev === this.cryptoProfile) {
+            return await fn();
+        }
+        setCryptoProfile(this.cryptoProfile);
+        try {
+            return await fn();
+        } finally {
+            setCryptoProfile(prev);
+        }
+    }
+
     /* header is 32 bytes and is either empty
     or contains an HMAC of the message with
     a derived SK */
@@ -3533,9 +3677,9 @@ export class Client {
             if (!session || retry) {
                 if (libvexDebugDmEnabled()) {
                     debugLibvexDm("sendMail: createSession path", {
+                        hasSession: String(!!session),
                         peerDevice: device.deviceID,
                         retry: String(retry),
-                        hasSession: String(!!session),
                     });
                 }
                 await this.createSession(
@@ -3684,11 +3828,11 @@ export class Client {
                 debugLibvexDm(
                     "sendMessage: peer device list (merged, sorted)",
                     {
-                        userID,
                         nAfterBackoff: String(afterBackoff.length),
                         nMerged: String(deviceListRaw.length),
                         nSorted: String(deviceList.length),
                         ourDevice: this.getDevice().deviceID,
+                        userID,
                     },
                 );
                 for (const [i, d] of deviceList.entries()) {
@@ -3699,13 +3843,15 @@ export class Client {
             }
             let lastErr: unknown;
             let failCount = 0;
+            // One logical DM fan-outs to multiple recipient devices. Reuse a
+            // single mailID so local/UI dedupe treats it as one message.
+            const messageMailID = uuid.v4();
             for (const device of deviceList) {
-                const mailID = uuid.v4();
                 try {
                     if (libvexDebugDmEnabled()) {
                         debugLibvexDm("sendMessage: sendMail start", {
+                            mailID: messageMailID,
                             recipientDevice: device.deviceID,
-                            mailID,
                         });
                     }
                     await this.sendMail(
@@ -3713,7 +3859,7 @@ export class Client {
                         userEntry,
                         XUtils.decodeUTF8(message),
                         null,
-                        mailID,
+                        messageMailID,
                         false,
                     );
                     if (libvexDebugDmEnabled()) {