@vex-chat/libvex 6.4.0 → 6.5.0

package/src/Client.ts

@@ -149,6 +149,26 @@ export class DeviceApprovalRequiredError extends Error {
     }
 }
 
+function cloneNullableBytes(value: null | Uint8Array): null | Uint8Array {
+    return value ? new Uint8Array(value) : null;
+}
+
+function cloneSessionCrypto(session: SessionCrypto): SessionCrypto {
+    return {
+        ...session,
+        CKr: cloneNullableBytes(session.CKr),
+        CKs: cloneNullableBytes(session.CKs),
+        DHr: cloneNullableBytes(session.DHr),
+        DHsPrivate: new Uint8Array(session.DHsPrivate),
+        DHsPublic: new Uint8Array(session.DHsPublic),
+        fingerprint: new Uint8Array(session.fingerprint),
+        publicKey: new Uint8Array(session.publicKey),
+        RK: new Uint8Array(session.RK),
+        SK: new Uint8Array(session.SK),
+        skippedKeys: { ...session.skippedKeys },
+    };
+}
+
 function debugLibvexDm(
     msg: string,
     data?: Record<string, boolean | null | number | string | undefined>,
@@ -156,6 +176,9 @@ function debugLibvexDm(
     if (!libvexDebugDmEnabled()) {
         return;
     }
+    if (isHeartbeatDebugMessage(msg, data) && libvexDebugLevel() !== "trace") {
+        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}`);
@@ -168,6 +191,14 @@ function ignoreSocketTeardown(err: unknown): void {
     throw err;
 }
 
+function isHeartbeatDebugMessage(
+    msg: string,
+    data?: Record<string, boolean | null | number | string | undefined>,
+): boolean {
+    if (/\b(?:ping|pong)\b/i.test(msg)) return true;
+    return data?.["type"] === "ping" || data?.["type"] === "pong";
+}
+
 function isRecord(x: unknown): x is Record<string, unknown> {
     return typeof x === "object" && x !== null;
 }
@@ -202,6 +233,26 @@ function libvexDebugDmEnabled(): boolean {
     }
 }
 
+function libvexDebugLevel(): "debug" | "trace" {
+    try {
+        const g = Object.getOwnPropertyDescriptor(globalThis, "\u0070rocess");
+        if (!g) return "debug";
+        const proc: unknown = typeof g.get === "function" ? g.get() : g.value;
+        if (typeof proc !== "object" || proc === null) return "debug";
+        const envDesc = Object.getOwnPropertyDescriptor(proc, "env");
+        if (!envDesc) return "debug";
+        const env: unknown =
+            typeof envDesc.get === "function" ? envDesc.get() : envDesc.value;
+        if (typeof env !== "object" || env === null) return "debug";
+        const value = String(
+            Reflect.get(env, "LIBVEX_DEBUG_LEVEL") ?? "",
+        ).toLowerCase();
+        return value === "trace" || value === "2" ? "trace" : "debug";
+    } catch {
+        return "debug";
+    }
+}
+
 function sleep(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1299,16 +1350,17 @@ export class Client {
 
     private readonly dbPath: string;
 
+    private readonly decryptFailureCounts = new Map<string, number>();
+
     private device?: Device;
 
     private deviceRecords: Record<string, Device> = {};
-
     // ── 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;
     private readonly http: AxiosInstance;
@@ -1316,13 +1368,13 @@ export class Client {
     private readonly httpAbortController = new AbortController();
     private readonly idKeys: KeyPair | null;
     private isAlive: boolean = true;
-    private localMessageRetentionDays: number;
 
+    private localMessageRetentionDays: number;
     private localRetentionPurgeTimer: null | ReturnType<typeof setInterval> =
         null;
     private readonly mailInterval?: NodeJS.Timeout;
-    private manuallyClosing: boolean = false;
 
+    private manuallyClosing: boolean = false;
     /**
      * 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.
@@ -1336,19 +1388,19 @@ export class Client {
     and finally falls back to username. */
     /** Negative cache for user lookups that returned 404. TTL = 30 minutes. */
     private readonly notFoundUsers = new Map<string, number>();
+
     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 retentionPurgeDebounce: null | ReturnType<typeof setTimeout> = null;
     private readonly seenMailIDs: Set<string> = new Set();
@@ -1726,9 +1778,12 @@ export class Client {
 
         this.initSocket();
         // Yield the event loop so the WS open callback fires and sends the
-        // auth message before OTK generation blocks for ~5s on mobile.
+        // auth message before OTK generation starts. OTK top-up is best-effort
+        // and should not block app bootstrap/hydration.
         await new Promise((r) => setTimeout(r, 0));
-        await this.negotiateOTK();
+        this.negotiateOTK().catch(() => {
+            // Best-effort: lacking fresh OTKs should not fail login/boot.
+        });
     }
 
     /**
@@ -2176,10 +2231,27 @@ export class Client {
     }
 
     private acknowledgeInboundMail(mail: MailWS): void {
+        this.decryptFailureCounts.delete(mail.mailID);
         this.seenMailIDs.add(mail.mailID);
         this.sendReceipt(new Uint8Array(mail.nonce));
     }
 
+    private acknowledgeRepeatedDecryptFailure(
+        mail: MailWS,
+        count: number,
+    ): void {
+        if (count < 2) return;
+        if (libvexDebugDmEnabled()) {
+            debugLibvexDm("readMail: acknowledge repeated decrypt failure", {
+                attempts: count,
+                mailID: mail.mailID,
+                sender: mail.sender,
+                thisDevice: this.getDevice().deviceID,
+            });
+        }
+        this.acknowledgeInboundMail(mail);
+    }
+
     private async approveDeviceRequest(requestID: string): Promise<Device> {
         const req = await this.getDeviceRegistrationRequest(requestID);
         if (!req) {
@@ -2612,6 +2684,7 @@ export class Client {
     private async deletePermission(permissionID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/permission/" + permissionID);
     }
+
     private async deleteServer(serverID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/server/" + serverID);
     }
@@ -2628,7 +2701,6 @@ export class Client {
         }
         return "";
     }
-
     /**
      * Gets a list of permissions for a server.
      *
@@ -2899,16 +2971,14 @@ export class Client {
     /* Retrieves the current list of users you have sessions with. */
     private async getFamiliars(): Promise<User[]> {
         const sessions = await this.database.getAllSessions();
-        const familiars: User[] = [];
-
-        for (const session of sessions) {
-            const [user, _err] = await this.fetchUser(session.userID);
-            if (user) {
-                familiars.push(user);
-            }
-        }
-
-        return familiars;
+        const userIDs = [...new Set(sessions.map((session) => session.userID))];
+        const familiarEntries = await Promise.all(
+            userIDs.map(async (userID) => {
+                const [user] = await this.fetchUser(userID);
+                return user ?? null;
+            }),
+        );
+        return familiarEntries.filter((user): user is User => user !== null);
     }
 
     private async getGroupHistory(channelID: string): Promise<Message[]> {
@@ -3139,8 +3209,6 @@ export class Client {
         return decodeAxios(UserArrayCodec, res.data);
     }
 
-    // ── Passkeys ────────────────────────────────────────────────────────
-
     private async handleNotify(msg: NotifyMsg) {
         switch (msg.event) {
             case "deviceRequest": {
@@ -3209,6 +3277,8 @@ export class Client {
         this.emitter.emit("ready");
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     private initSocket() {
         try {
             if (!this.token) {
@@ -3649,6 +3719,23 @@ export class Client {
             return;
         }
 
+        if (await this.database.hasMessage(mail.mailID)) {
+            if (libvexDebugDmEnabled()) {
+                try {
+                    debugLibvexDm("readMail: skip (stored mailID)", {
+                        mailID: mail.mailID,
+                        thisDevice: this.getDevice().deviceID,
+                    });
+                } catch {
+                    debugLibvexDm("readMail: skip (stored mailID)", {
+                        mailID: mail.mailID,
+                    });
+                }
+            }
+            this.acknowledgeInboundMail(mail);
+            return;
+        }
+
         if (this.manuallyClosing) {
             if (libvexDebugDmEnabled()) {
                 debugLibvexDm("readMail: skip (manually closing)", {
@@ -4055,40 +4142,110 @@ export class Client {
                             return;
                         }
 
+                        const originalSession = cloneSessionCrypto(session);
                         const firstInboundFromSubsequent = !session.DHr;
+                        let candidateSession = cloneSessionCrypto(session);
                         if (firstInboundFromSubsequent) {
-                            session.DHr = ratchetHeader.dhPub;
-                            // First inbound after X3DH initial mail has no prior DH ratchet.
-                            // If this side has no receiving chain yet (initiator path),
-                            // derive the bootstrap receive chain to match peer's first
-                            // bootstrap send chain.
-                            if (!session.CKr) {
-                                session.CKr = deriveBootstrapSendChain(
-                                    session.RK,
+                            candidateSession.DHr = ratchetHeader.dhPub;
+                            // First inbound after X3DH initial mail can be either:
+                            // - peer's bootstrap send chain if they replied before seeing
+                            //   one of our subsequent messages; or
+                            // - a real DH ratchet if they already received one from us.
+                            // Try bootstrap first for backwards compatibility, then fall
+                            // back to the DH-ratchet interpretation if HMAC disagrees.
+                            if (!candidateSession.CKr) {
+                                candidateSession.CKr = deriveBootstrapSendChain(
+                                    candidateSession.RK,
                                 );
                             }
                         } else if (
-                            hasRemoteDhChanged(session.DHr, ratchetHeader.dhPub)
+                            hasRemoteDhChanged(
+                                candidateSession.DHr,
+                                ratchetHeader.dhPub,
+                            )
                         ) {
                             await ratchetStepReceive(
-                                session,
+                                candidateSession,
                                 ratchetHeader.dhPub,
                                 ratchetHeader.pn,
                             );
                         }
 
-                        const messageKey = takeReceiveMessageKey(
-                            session,
+                        let messageKey = takeReceiveMessageKey(
+                            candidateSession,
                             ratchetHeader.dhPub,
                             ratchetHeader.n,
                         );
-                        const HMAC = xHMAC(mail, messageKey);
+                        let HMAC = xHMAC(mail, messageKey);
+
+                        if (
+                            !XUtils.bytesEqual(HMAC, header) &&
+                            firstInboundFromSubsequent &&
+                            !originalSession.CKr
+                        ) {
+                            const ratchetedCandidate =
+                                cloneSessionCrypto(originalSession);
+                            await ratchetStepReceive(
+                                ratchetedCandidate,
+                                ratchetHeader.dhPub,
+                                ratchetHeader.pn,
+                            );
+                            const ratchetedMessageKey = takeReceiveMessageKey(
+                                ratchetedCandidate,
+                                ratchetHeader.dhPub,
+                                ratchetHeader.n,
+                            );
+                            const ratchetedHMAC = xHMAC(
+                                mail,
+                                ratchetedMessageKey,
+                            );
+                            if (XUtils.bytesEqual(ratchetedHMAC, header)) {
+                                if (libvexDebugDmEnabled()) {
+                                    debugLibvexDm(
+                                        "readMail subsequent: first inbound used DH-ratchet fallback",
+                                        {
+                                            mailID: mail.mailID,
+                                            thisDevice:
+                                                this.getDevice().deviceID,
+                                        },
+                                    );
+                                }
+                                candidateSession = ratchetedCandidate;
+                                messageKey = ratchetedMessageKey;
+                                HMAC = ratchetedHMAC;
+                            }
+                        }
 
                         if (!XUtils.bytesEqual(HMAC, header)) {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
+                            if (libvexDebugDmEnabled()) {
+                                debugLibvexDm(
+                                    "readMail subsequent: abort (HMAC mismatch)",
+                                    {
+                                        attempts: failureCount,
+                                        mailID: mail.mailID,
+                                        sender: mail.sender,
+                                        thisDevice: this.getDevice().deviceID,
+                                    },
+                                );
+                            }
                             healSession();
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                            );
                             return;
                         }
 
+                        session = candidateSession;
+
                         const decrypted = await xSecretboxOpenAsync(
                             new Uint8Array(mail.cipher),
                             new Uint8Array(mail.nonce),
@@ -4181,11 +4338,19 @@ export class Client {
                             ] = session;
                             this.acknowledgeInboundMail(mail);
                         } else {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             healSession();
-                            this.emitter.emit("retryRequest", {
-                                mailID: mail.mailID,
-                                source: "decrypt_failure",
-                            });
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                            );
                         }
                         break;
                     }
@@ -4205,6 +4370,12 @@ export class Client {
         return decodeAxios(PermissionCodec, res.data);
     }
 
+    private registerDecryptFailure(mail: MailWS): number {
+        const count = (this.decryptFailureCounts.get(mail.mailID) ?? 0) + 1;
+        this.decryptFailureCounts.set(mail.mailID, count);
+        return count;
+    }
+
     private async registerDevice(): Promise<DeviceRegistrationResult | null> {
         while (!this.xKeyRing) {
             await sleep(100);
@@ -4380,10 +4551,12 @@ export class Client {
                 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,
-                    );
+                    throw new DeviceApprovalRequiredError({
+                        challenge: newDevice.challenge,
+                        expiresAt: newDevice.expiresAt,
+                        requestID: newDevice.requestID,
+                        userID: newDevice.userID ?? null,
+                    });
                 } else {
                     throw new Error("Error registering device.");
                 }

package/src/Storage.ts

@@ -64,6 +64,8 @@ export interface Storage extends EventEmitter {
     getSessionByPublicKey: (
         publicKey: Uint8Array,
     ) => Promise<null | SessionCrypto>;
+    /** Returns whether a message with this `mailID` already exists locally. */
+    hasMessage: (mailID: string) => Promise<boolean>;
     /**
      * Performs storage initialization (schema creation, migrations, warmup, etc.).
      *

package/src/__tests__/harness/memory-storage.ts

@@ -155,6 +155,10 @@ export class MemoryStorage extends EventEmitter implements Storage {
         return Promise.resolve(this.sqlToCrypto(s));
     }
 
+    hasMessage(mailID: string): Promise<boolean> {
+        return Promise.resolve(this.messages.some((m) => m.mailID === mailID));
+    }
+
     init(): Promise<void> {
         this.ready = true;
         this.emit("ready");
@@ -215,6 +219,9 @@ export class MemoryStorage extends EventEmitter implements Storage {
     }
 
     async saveMessage(message: Message): Promise<void> {
+        if (this.messages.some((m) => m.mailID === message.mailID)) {
+            return;
+        }
         const copy = { ...message };
         const fips = getCryptoProfile() === "fips";
         const ct = fips

package/src/storage/sqlite.ts

@@ -225,8 +225,6 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
-    // ── Sessions ─────────────────────────────────────────────────────────────
-
     async getPreKeys(): Promise<null | PreKeysCrypto> {
         await this.untilReady();
         if (this.closing) {
@@ -250,6 +248,8 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
+    // ── Sessions ─────────────────────────────────────────────────────────────
+
     async getSessionByDeviceID(
         deviceID: string,
     ): Promise<null | SessionCrypto> {
@@ -297,6 +297,19 @@ export class SqliteStorage extends EventEmitter implements Storage {
         return this.sqlToCrypto(await this.sessionRowToSQLAsync(sessionRow));
     }
 
+    async hasMessage(mailID: string): Promise<boolean> {
+        await this.untilReady();
+        if (this.closing) {
+            return false;
+        }
+        const row = await this.db
+            .selectFrom("messages")
+            .select("mailID")
+            .where("mailID", "=", mailID)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+
     async init(): Promise<void> {
         if (this.ready || this.closing) {
             return;
@@ -358,6 +371,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     .execute();
                 await this.ensureSessionRatchetColumns();
                 await this.ensureRetentionHintColumn();
+                await this.ensureMessageMailIdIndex();
 
                 await this.db.schema
                     .createTable("preKeys")
@@ -507,6 +521,18 @@ export class SqliteStorage extends EventEmitter implements Storage {
         if (this.isClosingNow()) {
             return;
         }
+        await this.untilReady();
+
+        // Fan-out to multiple devices reuses one `mailID` but each encrypt path
+        // uses a fresh nonce (table PK). Keep a single local row per logical mail.
+        const dupe = await this.db
+            .selectFrom("messages")
+            .select("nonce")
+            .where("mailID", "=", message.mailID)
+            .executeTakeFirst();
+        if (dupe !== undefined) {
+            return;
+        }
 
         // Encrypt plaintext with at-rest key before saving to disk
         const fips = getCryptoProfile() === "fips";
@@ -747,6 +773,19 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
+    /** Speeds up mailID existence checks for saveMessage deduplication. */
+    private async ensureMessageMailIdIndex(): Promise<void> {
+        try {
+            await sql
+                .raw(
+                    "CREATE INDEX IF NOT EXISTS messages_mailID_idx ON messages(mailID)",
+                )
+                .execute(this.db);
+        } catch {
+            // Extremely defensive — `messages` always exists at this point.
+        }
+    }
+
     private async ensureRetentionHintColumn(): Promise<void> {
         try {
             await sql