@vex-chat/libvex 6.5.2 → 6.5.4

package/src/Client.ts

@@ -109,6 +109,7 @@ import {
     takeReceiveMessageKey,
     takeSendMessageKey,
 } from "./utils/ratchet.js";
+import { verifyKeyBundleSignatures } from "./utils/verifyKeyBundle.js";
 
 /**
  * Thrown by {@link Client.register} when the server determined the supplied
@@ -350,18 +351,6 @@ import { uuidToUint8 } from "./utils/uint8uuid.js";
 
 const _protocolMsgRegex = /��\w+:\w+��/g;
 
-/**
- * Permission is a permission to a resource.
- *
- * Common fields:
- * - `permissionID`: unique permission row ID
- * - `userID`: user receiving this grant
- * - `resourceID`: target server/channel/etc.
- * - `resourceType`: type string for the resource
- * - `powerLevel`: authorization level
- */
-export type { Permission } from "@vex-chat/types";
-
 /**
  * @ignore
  */
@@ -378,27 +367,6 @@ export interface Channels {
     userList: (channelID: string) => Promise<User[]>;
 }
 
-/**
- * Device record associated with a user account.
- *
- * Common fields:
- * - `deviceID`: unique device identifier
- * - `owner`: owning user ID
- * - `signKey`: signing public key
- * - `name`: user-facing device name
- * - `lastLogin`: last login timestamp string
- * - `deleted`: soft-delete flag
- */
-export type { Device } from "@vex-chat/types";
-
-/**
- * Public passkey record returned by `client.passkeys.list()` and
- * `client.passkeys.finishRegistration()`. Server-private fields
- * (credential ID, public key, COSE algorithm, signature counter) are
- * never exposed.
- */
-export type { Passkey } from "@vex-chat/types";
-
 /**
  * ClientOptions are the options you can pass into the client.
  */
@@ -436,8 +404,41 @@ export interface ClientOptions {
     unsafeHttp?: boolean;
 }
 
+/**
+ * Permission is a permission to a resource.
+ *
+ * Common fields:
+ * - `permissionID`: unique permission row ID
+ * - `userID`: user receiving this grant
+ * - `resourceID`: target server/channel/etc.
+ * - `resourceType`: type string for the resource
+ * - `powerLevel`: authorization level
+ */
+export type { Permission } from "@vex-chat/types";
+
 export type DeviceRegistrationResult = Device | PendingDeviceRegistration;
 
+/**
+ * Device record associated with a user account.
+ *
+ * Common fields:
+ * - `deviceID`: unique device identifier
+ * - `owner`: owning user ID
+ * - `signKey`: signing public key
+ * - `name`: user-facing device name
+ * - `lastLogin`: last login timestamp string
+ * - `deleted`: soft-delete flag
+ */
+export type { Device } from "@vex-chat/types";
+
+/**
+ * Public passkey record returned by `client.passkeys.list()` and
+ * `client.passkeys.finishRegistration()`. Server-private fields
+ * (credential ID, public key, COSE algorithm, signature counter) are
+ * never exposed.
+ */
+export type { Passkey } from "@vex-chat/types";
+
 /**
  * @ignore
  */
@@ -556,6 +557,29 @@ export interface Files {
     retrieve: (fileID: string, key: string) => Promise<FileResponse | null>;
 }
 
+/**
+ * @ignore
+ */
+export interface Invites {
+    /** Creates an invite for a server and duration. */
+    create: (serverID: string, duration: string) => Promise<Invite>;
+    /** Redeems an invite and returns the created permission grant. */
+    redeem: (inviteID: string) => Promise<Permission>;
+    /** Lists active invites for a server. */
+    retrieve: (serverID: string) => Promise<Invite[]>;
+}
+
+/**
+ * Keys are a pair of ed25519 public and private keys,
+ * encoded as hex strings.
+ */
+export interface Keys {
+    /** Secret Ed25519 key as hex. Store securely. */
+    private: string;
+    /** Public Ed25519 key as hex. */
+    public: string;
+}
+
 /**
  * Channel is a chat channel on a server.
  *
@@ -581,29 +605,6 @@ export type { Server } from "@vex-chat/types";
  */
 export type { ServerChannelBootstrap } from "@vex-chat/types";
 
-/**
- * @ignore
- */
-export interface Invites {
-    /** Creates an invite for a server and duration. */
-    create: (serverID: string, duration: string) => Promise<Invite>;
-    /** Redeems an invite and returns the created permission grant. */
-    redeem: (inviteID: string) => Promise<Permission>;
-    /** Lists active invites for a server. */
-    retrieve: (serverID: string) => Promise<Invite[]>;
-}
-
-/**
- * Keys are a pair of ed25519 public and private keys,
- * encoded as hex strings.
- */
-export interface Keys {
-    /** Secret Ed25519 key as hex. Store securely. */
-    private: string;
-    /** Public Ed25519 key as hex. */
-    public: string;
-}
-
 /**
  * @ignore
  */
@@ -753,6 +754,59 @@ export interface RetryRequest {
     source: "decrypt_failure" | "server_notify";
 }
 
+function compareInboxEntries(
+    a: [Uint8Array, MailWS, string],
+    b: [Uint8Array, MailWS, string],
+): number {
+    const timeCmp = a[2].localeCompare(b[2]);
+    if (timeCmp !== 0) {
+        return timeCmp;
+    }
+
+    const aMail = a[1];
+    const bMail = b[1];
+    if (aMail.sender !== bMail.sender) {
+        return aMail.sender.localeCompare(bMail.sender, "en");
+    }
+
+    const typeCmp = aMail.mailType - bMail.mailType;
+    if (typeCmp !== 0) {
+        return typeCmp;
+    }
+
+    if (
+        aMail.mailType === MailType.subsequent &&
+        bMail.mailType === MailType.subsequent
+    ) {
+        const aHeader = tryDecodeRatchetHeader(aMail.extra);
+        const bHeader = tryDecodeRatchetHeader(bMail.extra);
+        if (aHeader && bHeader) {
+            const dhCmp = XUtils.encodeHex(aHeader.dhPub).localeCompare(
+                XUtils.encodeHex(bHeader.dhPub),
+                "en",
+            );
+            if (dhCmp !== 0) {
+                return dhCmp;
+            }
+            const pnCmp = aHeader.pn - bHeader.pn;
+            if (pnCmp !== 0) {
+                return pnCmp;
+            }
+            return aHeader.n - bHeader.n;
+        }
+    }
+
+    return aMail.nonce.toString().localeCompare(bMail.nonce.toString(), "en");
+}
+
+function tryDecodeRatchetHeader(extra: Uint8Array) {
+    try {
+        return decodeRatchetHeader(extra);
+    } catch {
+        return null;
+    }
+}
+
 /** Zod schema matching the {@link Message} interface for forwarded-message decode. */
 const messageSchema: z.ZodType<Message> = z.object({
     authorID: z.string(),
@@ -2440,6 +2494,11 @@ export class Client {
 
             try {
                 keyBundle = await this.retrieveKeyBundle(device.deviceID);
+                await verifyKeyBundleSignatures(
+                    keyBundle,
+                    device,
+                    this.cryptoProfile,
+                );
             } catch (e) {
                 if (allowKeyBundleFailure) {
                     return;
@@ -3001,7 +3060,7 @@ export class Client {
             const rawInbox = z
                 .array(mailInboxEntry)
                 .parse(msgpack.decode(mailBuffer));
-            const inbox = rawInbox.sort((a, b) => b[2].localeCompare(a[2]));
+            const inbox = rawInbox.sort(compareInboxEntries);
 
             if (libvexDebugDmEnabled()) {
                 const did = (() => {
@@ -3046,8 +3105,9 @@ export class Client {
                     fetchErr,
                 );
             }
+        } finally {
+            this.fetchingMail = false;
         }
-        this.fetchingMail = false;
     }
 
     private async getMessageHistory(userID: string): Promise<Message[]> {
@@ -3204,7 +3264,6 @@ export class Client {
             }
             case "mail":
                 await this.getMail();
-                this.fetchingMail = false;
                 break;
             case "permission":
                 this.emitter.emit(
@@ -3232,6 +3291,27 @@ export class Client {
         }
     }
 
+    private handleTerminalSocketState(reason: string): boolean {
+        const { readyState } = this.socket;
+        if (readyState !== 2 && readyState !== 3) {
+            return false;
+        }
+        if (this.isManualCloseInFlight()) {
+            return true;
+        }
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+        debugLibvexDm("websocket-terminal-state", {
+            readyState,
+            reason,
+        });
+        this.emitter.emit("disconnect");
+        this.scheduleReconnect();
+        return true;
+    }
+
     // ── Passkeys ────────────────────────────────────────────────────────
 
     /**
@@ -3289,6 +3369,7 @@ export class Client {
                     this.socket.send(new TextEncoder().encode(authMsg));
                 } catch (err: unknown) {
                     if (err instanceof WebSocketNotOpenError) {
+                        this.handleTerminalSocketState("auth-open");
                         return;
                     }
                     throw err;
@@ -3522,6 +3603,9 @@ export class Client {
     }
 
     private ping() {
+        if (this.handleTerminalSocketState("ping")) {
+            return;
+        }
         if (!this.isAlive) {
             // Previous ping went unanswered — the WebSocket is half-open
             // (e.g., the network stack silently dropped the flow without a
@@ -3540,6 +3624,7 @@ export class Client {
             } catch {
                 // socket may already be CLOSING/CLOSED; ignore.
             }
+            this.scheduleReconnect();
             return;
         }
         this.setAlive(false);
@@ -3641,7 +3726,6 @@ export class Client {
             try {
                 await this.getMail();
                 count++;
-                this.fetchingMail = false;
 
                 if (count > 10) {
                     void this.negotiateOTK();
@@ -4221,7 +4305,9 @@ export class Client {
                                     },
                                 );
                             }
-                            healSession();
+                            if (failureCount >= 2) {
+                                healSession();
+                            }
                             if (failureCount === 1) {
                                 this.emitter.emit("retryRequest", {
                                     mailID: mail.mailID,

package/src/__tests__/verifyKeyBundle.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { CryptoProfile, KeyPair } from "@vex-chat/crypto";
+import type { Device, KeyBundle, KeyBundleEntry } from "@vex-chat/types";
+
+import {
+    setCryptoProfile,
+    xBoxKeyPairAsync,
+    xConstants,
+    xEcdhKeyPairFromEcdsaKeyPairAsync,
+    xEncode,
+    xSignAsync,
+    xSignKeyPairAsync,
+    XUtils,
+} from "@vex-chat/crypto";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { fipsP256PreKeySignPayload } from "../utils/fipsMailExtra.js";
+import { verifyKeyBundleSignatures } from "../utils/verifyKeyBundle.js";
+
+describe.sequential("verifyKeyBundleSignatures", () => {
+    afterEach(() => {
+        setCryptoProfile("tweetnacl");
+    });
+
+    it("accepts a valid tweetnacl key bundle", async () => {
+        const { device, keyBundle } = await makeBundle("tweetnacl");
+
+        await expect(
+            verifyKeyBundleSignatures(keyBundle, device, "tweetnacl"),
+        ).resolves.toBeUndefined();
+    });
+
+    it("rejects a tampered signed prekey public key", async () => {
+        const { device, keyBundle } = await makeBundle("tweetnacl");
+        const tampered = cloneBundle(keyBundle);
+        tampered.preKey.publicKey = flipFirstByte(tampered.preKey.publicKey);
+
+        await expect(
+            verifyKeyBundleSignatures(tampered, device, "tweetnacl"),
+        ).rejects.toThrow("signed prekey signature is invalid");
+    });
+
+    it("rejects a tampered one-time prekey public key", async () => {
+        const { device, keyBundle } = await makeBundle("tweetnacl", true);
+        const tampered = cloneBundle(keyBundle);
+        if (!tampered.otk) {
+            throw new Error("Expected OTK fixture.");
+        }
+        tampered.otk.publicKey = flipFirstByte(tampered.otk.publicKey);
+
+        await expect(
+            verifyKeyBundleSignatures(tampered, device, "tweetnacl"),
+        ).rejects.toThrow("one-time prekey signature is invalid");
+    });
+
+    it("rejects a bundle identity key that does not match the device", async () => {
+        const { device, keyBundle } = await makeBundle("tweetnacl");
+        const other = await xSignKeyPairAsync();
+        const tampered = cloneBundle(keyBundle);
+        tampered.signKey = other.publicKey;
+
+        await expect(
+            verifyKeyBundleSignatures(tampered, device, "tweetnacl"),
+        ).rejects.toThrow("identity key does not match");
+    });
+
+    it("accepts a valid FIPS key bundle", async () => {
+        const { device, keyBundle } = await makeBundle("fips", true);
+
+        await expect(
+            verifyKeyBundleSignatures(keyBundle, device, "fips"),
+        ).resolves.toBeUndefined();
+    });
+});
+
+function cloneBundle(bundle: KeyBundle): KeyBundle {
+    return {
+        ...(bundle.otk ? { otk: cloneEntry(bundle.otk) } : {}),
+        preKey: cloneEntry(bundle.preKey),
+        signKey: Uint8Array.from(bundle.signKey),
+    };
+}
+
+function cloneEntry(entry: KeyBundleEntry): KeyBundleEntry {
+    return {
+        deviceID: entry.deviceID,
+        index: entry.index,
+        publicKey: Uint8Array.from(entry.publicKey),
+        signature: Uint8Array.from(entry.signature),
+    };
+}
+
+function flipFirstByte(value: Uint8Array): Uint8Array {
+    const out = Uint8Array.from(value);
+    const first = out[0];
+    if (first === undefined) {
+        throw new Error("Cannot tamper empty byte array.");
+    }
+    out[0] = first ^ 0xff;
+    return out;
+}
+
+async function makeBundle(
+    profile: CryptoProfile,
+    includeOtk = false,
+): Promise<{ device: Device; keyBundle: KeyBundle }> {
+    setCryptoProfile(profile);
+    const signKeys = await xSignKeyPairAsync();
+    const identityPublic =
+        profile === "fips"
+            ? (await xEcdhKeyPairFromEcdsaKeyPairAsync(signKeys)).publicKey
+            : signKeys.publicKey;
+    const device: Device = {
+        deleted: false,
+        deviceID: "device-a",
+        lastLogin: new Date(0).toISOString(),
+        name: "test-device",
+        owner: "user-a",
+        signKey: XUtils.encodeHex(signKeys.publicKey),
+    };
+
+    const keyBundle: KeyBundle = {
+        preKey: await makeBundleEntry(signKeys, profile, device.deviceID, 1),
+        signKey: identityPublic,
+    };
+    if (includeOtk) {
+        keyBundle.otk = await makeBundleEntry(
+            signKeys,
+            profile,
+            device.deviceID,
+            2,
+        );
+    }
+
+    return { device, keyBundle };
+}
+
+async function makeBundleEntry(
+    signKeys: KeyPair,
+    profile: CryptoProfile,
+    deviceID: string,
+    index: number,
+): Promise<KeyBundleEntry> {
+    const preKey = await xBoxKeyPairAsync();
+    const payload =
+        profile === "fips"
+            ? fipsP256PreKeySignPayload(preKey.publicKey)
+            : xEncode(xConstants.CURVE, preKey.publicKey);
+    return {
+        deviceID,
+        index,
+        publicKey: preKey.publicKey,
+        signature: await xSignAsync(payload, signKeys.secretKey),
+    };
+}

package/src/utils/verifyKeyBundle.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { CryptoProfile } from "@vex-chat/crypto";
+import type { Device, KeyBundle, KeyBundleEntry } from "@vex-chat/types";
+
+import {
+    fipsEcdhRawPublicKeyFromEcdsaSpkiAsync,
+    xConstants,
+    xEncode,
+    xSignOpenAsync,
+    XUtils,
+} from "@vex-chat/crypto";
+
+import { fipsP256PreKeySignPayload } from "./fipsMailExtra.js";
+
+export async function verifyKeyBundleSignatures(
+    keyBundle: KeyBundle,
+    device: Device,
+    cryptoProfile: CryptoProfile,
+): Promise<void> {
+    const deviceSignKey = XUtils.decodeHex(device.signKey);
+    const expectedIdentity =
+        cryptoProfile === "fips"
+            ? await fipsEcdhRawPublicKeyFromEcdsaSpkiAsync(deviceSignKey)
+            : deviceSignKey;
+
+    if (!XUtils.bytesEqual(expectedIdentity, keyBundle.signKey)) {
+        throw new Error("Key bundle identity key does not match device.");
+    }
+
+    await verifyKeyBundleEntrySignature(
+        keyBundle.preKey,
+        device,
+        deviceSignKey,
+        cryptoProfile,
+        "signed prekey",
+    );
+
+    if (keyBundle.otk) {
+        await verifyKeyBundleEntrySignature(
+            keyBundle.otk,
+            device,
+            deviceSignKey,
+            cryptoProfile,
+            "one-time prekey",
+        );
+    }
+}
+
+async function verifyKeyBundleEntrySignature(
+    entry: KeyBundleEntry,
+    device: Device,
+    deviceSignKey: Uint8Array,
+    cryptoProfile: CryptoProfile,
+    label: string,
+): Promise<void> {
+    if (entry.deviceID !== device.deviceID) {
+        throw new Error(`Key bundle ${label} belongs to a different device.`);
+    }
+
+    const payload =
+        cryptoProfile === "fips"
+            ? fipsP256PreKeySignPayload(entry.publicKey)
+            : xEncode(xConstants.CURVE, entry.publicKey);
+    const opened = await xSignOpenAsync(entry.signature, deviceSignKey);
+
+    if (!opened || !XUtils.bytesEqual(opened, payload)) {
+        throw new Error(`Key bundle ${label} signature is invalid.`);
+    }
+}