@vex-chat/libvex 5.5.2 → 6.0.0

package/dist/utils/sqlSessionToCrypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlSessionToCrypto.js","sourceRoot":"","sources":["../../src/utils/sqlSessionToCrypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,UAAU,kBAAkB,CAAC,OAAmB;IAClD,OAAO;QACH,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;QAClD,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9C,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;KACzB,CAAC;AACN,CAAC"}
+{"version":3,"file":"sqlSessionToCrypto.js","sourceRoot":"","sources":["../../src/utils/sqlSessionToCrypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,MAAM,UAAU,kBAAkB,CAAC,OAAmB;IAClD,MAAM,WAAW,GAAG,gBAAgB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D,OAAO;QACH,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;QACvD,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;QACvD,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI;QACvD,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC;QAChD,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9C,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC;QAClD,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC;QAC9C,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,WAAW;QACX,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC7B,CAAC;AACN,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAW;IACjC,IAAI,CAAC;QACD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAChD,OAAO,EAAE,CAAC;QACd,CAAC;QACD,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1C,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACxB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACf,CAAC;QACL,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vex-chat/libvex",
-  "version": "5.5.2",
+  "version": "6.0.0",
   "description": "Library for communicating with xchat server.",
   "type": "module",
   "sideEffects": false,
@@ -93,8 +93,8 @@
     "msgpackr": "^1.11.9",
     "uuid": "^14.0.0",
     "zod": "^4.3.6",
-    "@vex-chat/crypto": "^2.1.2",
-    "@vex-chat/types": "^2.0.0"
+    "@vex-chat/crypto": "^3.0.0",
+    "@vex-chat/types": "^3.0.0"
   },
   "peerDependencies": {
     "better-sqlite3": ">=11.0.0"

package/src/Client.ts

@@ -80,14 +80,22 @@ import { z } from "zod/v4";
 import { WebSocketAdapter } from "./transport/websocket.js";
 import {
     decodeFipsInitialExtraV1,
-    decodeFipsSubsequentExtraV1,
     encodeFipsInitialExtraV1,
-    encodeFipsSubsequentExtraV1,
     fipsP256AdFromIdentityPubs,
     fipsP256PreKeySignPayload,
     isFipsInitialExtraV1,
-    isFipsSubsequentExtraV1,
 } from "./utils/fipsMailExtra.js";
+import {
+    decodeRatchetHeader,
+    encodeRatchetHeader,
+    hasRemoteDhChanged,
+    initRatchetSession,
+    ratchetStepReceive,
+    ratchetStepSend,
+    sessionToSqlPatch,
+    takeReceiveMessageKey,
+    takeSendMessageKey,
+} from "./utils/ratchet.js";
 
 function debugLibvexDm(
     msg: string,
@@ -1309,9 +1317,6 @@ export class Client {
                 return [signKey, ephKey, ad, index];
             }
             case MailType.subsequent:
-                if (isFipsSubsequentExtraV1(extra)) {
-                    return [decodeFipsSubsequentExtraV1(extra)];
-                }
                 return [extra];
             default:
                 return [];
@@ -2094,7 +2099,9 @@ export class Client {
             // discard the ephemeral keys
             await this.newEphemeralKeys();
 
+            const ratchet = await initRatchetSession(SK, "initiator");
             const sessionEntry: SessionSQL = {
+                ...ratchet,
                 deviceID: device.deviceID,
                 fingerprint: XUtils.encodeHex(AD),
                 lastUsed: new Date().toISOString(),
@@ -3271,7 +3278,12 @@ export class Client {
                                 deviceEntry;
 
                             // save session
+                            const ratchet = await initRatchetSession(
+                                SK,
+                                "receiver",
+                            );
                             const newSession: SessionSQL = {
+                                ...ratchet,
                                 deviceID: mail.sender,
                                 fingerprint: XUtils.encodeHex(AD),
                                 lastUsed: new Date().toISOString(),
@@ -3305,19 +3317,12 @@ export class Client {
                         }
                         break;
                     case MailType.subsequent: {
-                        const extraBuf = new Uint8Array(mail.extra);
-                        const publicKey = isFipsSubsequentExtraV1(extraBuf)
-                            ? decodeFipsSubsequentExtraV1(extraBuf)
-                            : Client.deserializeExtra(
-                                  mail.mailType,
-                                  extraBuf,
-                              )[0];
-                        if (!publicKey) {
-                            throw new Error(
-                                "Malformed subsequent mail extra: missing publicKey",
-                            );
-                        }
-                        let session = await this.getSessionByPubkey(publicKey);
+                        const ratchetHeader = decodeRatchetHeader(
+                            new Uint8Array(mail.extra),
+                        );
+                        let session = await this.database.getSessionByDeviceID(
+                            mail.sender,
+                        );
                         let retries = 0;
                         while (!session) {
                             if (retries >= 3) {
@@ -3325,14 +3330,32 @@ export class Client {
                             }
                             await sleep(100 * 2 ** retries);
                             retries++;
-                            session = await this.getSessionByPubkey(publicKey);
+                            session = await this.database.getSessionByDeviceID(
+                                mail.sender,
+                            );
                         }
 
                         if (!session) {
                             void healSession();
                             return;
                         }
-                        const HMAC = xHMAC(mail, session.SK);
+
+                        if (
+                            hasRemoteDhChanged(session.DHr, ratchetHeader.dhPub)
+                        ) {
+                            await ratchetStepReceive(
+                                session,
+                                ratchetHeader.dhPub,
+                                ratchetHeader.pn,
+                            );
+                        }
+
+                        const messageKey = takeReceiveMessageKey(
+                            session,
+                            ratchetHeader.dhPub,
+                            ratchetHeader.n,
+                        );
+                        const HMAC = xHMAC(mail, messageKey);
 
                         if (!XUtils.bytesEqual(HMAC, header)) {
                             void healSession();
@@ -3342,7 +3365,7 @@ export class Client {
                         const decrypted = await xSecretboxOpenAsync(
                             new Uint8Array(mail.cipher),
                             new Uint8Array(mail.nonce),
-                            session.SK,
+                            messageKey,
                         );
 
                         if (decrypted) {
@@ -3374,9 +3397,34 @@ export class Client {
                                   };
                             this.emitter.emit("message", message);
 
-                            void this.database.markSessionUsed(
-                                session.sessionID,
-                            );
+                            const sqlPatch = sessionToSqlPatch(session);
+                            const persisted: SessionSQL = {
+                                CKr: sqlPatch.CKr,
+                                CKs: sqlPatch.CKs,
+                                deviceID: mail.sender,
+                                DHr: sqlPatch.DHr,
+                                DHsPrivate: sqlPatch.DHsPrivate,
+                                DHsPublic: sqlPatch.DHsPublic,
+                                fingerprint: XUtils.encodeHex(
+                                    session.fingerprint,
+                                ),
+                                lastUsed: new Date().toISOString(),
+                                mode: session.mode,
+                                Nr: sqlPatch.Nr,
+                                Ns: sqlPatch.Ns,
+                                PN: sqlPatch.PN,
+                                publicKey: XUtils.encodeHex(session.publicKey),
+                                RK: sqlPatch.RK,
+                                sessionID: session.sessionID,
+                                SK: XUtils.encodeHex(session.SK),
+                                skippedKeys: sqlPatch.skippedKeys,
+                                userID: session.userID,
+                                verified: session.verified,
+                            };
+                            await this.database.saveSession(persisted);
+                            this.sessionRecords[
+                                XUtils.encodeHex(session.publicKey)
+                            ] = session;
                         } else {
                             void healSession();
                             this.emitter.emit("retryRequest", {
@@ -3718,12 +3766,19 @@ export class Client {
                 });
             }
 
+            if (!session.CKs) {
+                await ratchetStepSend(session);
+            }
+            const { messageKey, n } = takeSendMessageKey(session);
+            const ratchetHeader = {
+                dhPub: session.DHsPublic,
+                n,
+                pn: session.PN,
+                version: 1 as const,
+            };
             const nonce = xMakeNonce();
-            const cipher = await xSecretboxAsync(msg, nonce, session.SK);
-            const extra =
-                this.cryptoProfile === "fips"
-                    ? encodeFipsSubsequentExtraV1(session.publicKey)
-                    : session.publicKey;
+            const cipher = await xSecretboxAsync(msg, nonce, messageKey);
+            const extra = encodeRatchetHeader(ratchetHeader);
 
             const mail: MailWS = {
                 authorID: this.getUser().userID,
@@ -3747,7 +3802,7 @@ export class Client {
                 type: "resource",
             };
 
-            const hmac = xHMAC(mail, session.SK);
+            const hmac = xHMAC(mail, messageKey);
 
             const fwdOut = forward
                 ? messageSchema.parse(msgpack.decode(msg))
@@ -3770,6 +3825,31 @@ export class Client {
                   };
             this.emitter.emit("message", outMsg);
 
+            const sqlPatch = sessionToSqlPatch(session);
+            const persisted: SessionSQL = {
+                CKr: sqlPatch.CKr,
+                CKs: sqlPatch.CKs,
+                deviceID: device.deviceID,
+                DHr: sqlPatch.DHr,
+                DHsPrivate: sqlPatch.DHsPrivate,
+                DHsPublic: sqlPatch.DHsPublic,
+                fingerprint: XUtils.encodeHex(session.fingerprint),
+                lastUsed: new Date().toISOString(),
+                mode: session.mode,
+                Nr: sqlPatch.Nr,
+                Ns: sqlPatch.Ns,
+                PN: sqlPatch.PN,
+                publicKey: XUtils.encodeHex(session.publicKey),
+                RK: sqlPatch.RK,
+                sessionID: session.sessionID,
+                SK: XUtils.encodeHex(session.SK),
+                skippedKeys: sqlPatch.skippedKeys,
+                userID: session.userID,
+                verified: session.verified,
+            };
+            await this.database.saveSession(persisted);
+            this.sessionRecords[XUtils.encodeHex(session.publicKey)] = session;
+
             await new Promise((res, rej) => {
                 const callback = (packedMsg: Uint8Array) => {
                     const [_header, receivedMsg] =

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

@@ -234,7 +234,12 @@ export class MemoryStorage extends EventEmitter implements Storage {
     }
 
     saveSession(session: SessionSQL): Promise<void> {
-        if (!this.sessions.find((s) => s.SK === session.SK)) {
+        const idx = this.sessions.findIndex(
+            (s) => s.sessionID === session.sessionID,
+        );
+        if (idx >= 0) {
+            this.sessions[idx] = session;
+        } else {
             this.sessions.push(session);
         }
         return Promise.resolve();
@@ -261,14 +266,31 @@ export class MemoryStorage extends EventEmitter implements Storage {
     }
 
     private sqlToCrypto(s: SessionSQL): SessionCrypto {
+        let skippedKeys: Record<string, string> = {};
+        try {
+            skippedKeys = JSON.parse(s.skippedKeys) as Record<string, string>;
+        } catch {
+            skippedKeys = {};
+        }
         return {
+            CKr: s.CKr ? XUtils.decodeHex(s.CKr) : null,
+            CKs: s.CKs ? XUtils.decodeHex(s.CKs) : null,
+            DHr: s.DHr ? XUtils.decodeHex(s.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(s.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(s.DHsPublic),
             fingerprint: XUtils.decodeHex(s.fingerprint),
             lastUsed: s.lastUsed,
             mode: s.mode,
+            Nr: s.Nr,
+            Ns: s.Ns,
+            PN: s.PN,
             publicKey: XUtils.decodeHex(s.publicKey),
+            RK: XUtils.decodeHex(s.RK),
             sessionID: s.sessionID,
             SK: XUtils.decodeHex(s.SK),
+            skippedKeys,
             userID: s.userID,
+            verified: s.verified,
         };
     }
 }

package/src/__tests__/ratchet.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import { XUtils } from "@vex-chat/crypto";
+
+import { describe, expect, it } from "vitest";
+
+import {
+    decodeRatchetHeader,
+    encodeRatchetHeader,
+    hasRemoteDhChanged,
+    initRatchetSession,
+    ratchetStepReceive,
+    ratchetStepSend,
+    takeReceiveMessageKey,
+    takeSendMessageKey,
+} from "../utils/ratchet.js";
+
+describe("double ratchet helpers", () => {
+    it("derives matching message keys for first exchange and reply", async () => {
+        const sk = XUtils.decodeHex(
+            "1111111111111111111111111111111111111111111111111111111111111111",
+        );
+        const alice = await initRatchetSession(sk, "initiator");
+        const bob = await initRatchetSession(sk, "receiver");
+
+        const aliceState = {
+            CKr: alice.CKr ? XUtils.decodeHex(alice.CKr) : null,
+            CKs: alice.CKs ? XUtils.decodeHex(alice.CKs) : null,
+            DHr: alice.DHr ? XUtils.decodeHex(alice.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(alice.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(alice.DHsPublic),
+            Nr: alice.Nr,
+            Ns: alice.Ns,
+            PN: alice.PN,
+            RK: XUtils.decodeHex(alice.RK),
+            skippedKeys: {} as Record<string, string>,
+        };
+        const bobState = {
+            CKr: bob.CKr ? XUtils.decodeHex(bob.CKr) : null,
+            CKs: bob.CKs ? XUtils.decodeHex(bob.CKs) : null,
+            DHr: bob.DHr ? XUtils.decodeHex(bob.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(bob.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(bob.DHsPublic),
+            Nr: bob.Nr,
+            Ns: bob.Ns,
+            PN: bob.PN,
+            RK: XUtils.decodeHex(bob.RK),
+            skippedKeys: {} as Record<string, string>,
+        };
+
+        await ratchetStepSend(aliceState);
+        const a1 = takeSendMessageKey(aliceState);
+        const h1 = decodeRatchetHeader(
+            encodeRatchetHeader({
+                dhPub: aliceState.DHsPublic,
+                n: a1.n,
+                pn: aliceState.PN,
+                version: 1,
+            }),
+        );
+
+        expect(hasRemoteDhChanged(bobState.DHr, h1.dhPub)).toBe(true);
+        await ratchetStepReceive(bobState, h1.dhPub, h1.pn);
+        const b1 = takeReceiveMessageKey(bobState, h1.dhPub, h1.n);
+        expect(XUtils.bytesEqual(a1.messageKey, b1)).toBe(true);
+
+        await ratchetStepSend(bobState);
+        const bReply = takeSendMessageKey(bobState);
+        const h2 = decodeRatchetHeader(
+            encodeRatchetHeader({
+                dhPub: bobState.DHsPublic,
+                n: bReply.n,
+                pn: bobState.PN,
+                version: 1,
+            }),
+        );
+        await ratchetStepReceive(aliceState, h2.dhPub, h2.pn);
+        const aReply = takeReceiveMessageKey(aliceState, h2.dhPub, h2.n);
+        expect(XUtils.bytesEqual(aReply, bReply.messageKey)).toBe(true);
+    });
+
+    it("supports skipped keys for out-of-order messages", async () => {
+        const sk = XUtils.decodeHex(
+            "2222222222222222222222222222222222222222222222222222222222222222",
+        );
+        const initiator = await initRatchetSession(sk, "initiator");
+        const receiver = await initRatchetSession(sk, "receiver");
+
+        const s = {
+            CKr: initiator.CKr ? XUtils.decodeHex(initiator.CKr) : null,
+            CKs: initiator.CKs ? XUtils.decodeHex(initiator.CKs) : null,
+            DHr: initiator.DHr ? XUtils.decodeHex(initiator.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(initiator.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(initiator.DHsPublic),
+            Nr: initiator.Nr,
+            Ns: initiator.Ns,
+            PN: initiator.PN,
+            RK: XUtils.decodeHex(initiator.RK),
+            skippedKeys: {} as Record<string, string>,
+        };
+        const r = {
+            CKr: receiver.CKr ? XUtils.decodeHex(receiver.CKr) : null,
+            CKs: receiver.CKs ? XUtils.decodeHex(receiver.CKs) : null,
+            DHr: receiver.DHr ? XUtils.decodeHex(receiver.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(receiver.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(receiver.DHsPublic),
+            Nr: receiver.Nr,
+            Ns: receiver.Ns,
+            PN: receiver.PN,
+            RK: XUtils.decodeHex(receiver.RK),
+            skippedKeys: {} as Record<string, string>,
+        };
+
+        await ratchetStepSend(s);
+        const m0 = takeSendMessageKey(s);
+        const m1 = takeSendMessageKey(s);
+        const h0 = {
+            dhPub: s.DHsPublic,
+            n: m0.n,
+            pn: s.PN,
+            version: 1 as const,
+        };
+        const h1 = {
+            dhPub: s.DHsPublic,
+            n: m1.n,
+            pn: s.PN,
+            version: 1 as const,
+        };
+
+        await ratchetStepReceive(r, h1.dhPub, h1.pn);
+        const r1 = takeReceiveMessageKey(r, h1.dhPub, h1.n);
+        expect(XUtils.bytesEqual(r1, m1.messageKey)).toBe(true);
+
+        const r0 = takeReceiveMessageKey(r, h0.dhPub, h0.n);
+        expect(XUtils.bytesEqual(r0, m0.messageKey)).toBe(true);
+    });
+});

package/src/storage/schema.ts

@@ -88,13 +88,23 @@ interface PreKeysTable {
     userID: ColumnType<string, string | undefined, string>;
 }
 interface SessionsTable {
+    CKr: null | string;
+    CKs: null | string;
     deviceID: string;
+    DHr: null | string;
+    DHsPrivate: string;
+    DHsPublic: string;
     fingerprint: string;
     lastUsed: string;
     mode: string;
+    Nr: number;
+    Ns: number;
+    PN: number;
     publicKey: string;
+    RK: string;
     sessionID: string;
     SK: string;
+    skippedKeys: string;
     userID: string;
     verified: number;
 }