@vex-chat/libvex 5.5.2 → 6.0.0

package/src/storage/sqlite.ts

@@ -18,7 +18,6 @@ import type {
     SessionRow,
 } from "./schema.js";
 import type { Device, PreKeysSQL, SessionSQL } from "@vex-chat/types";
-import type { Kysely } from "kysely";
 
 /**
  * Unified Kysely-based SQLite storage implementation.
@@ -43,6 +42,7 @@ import {
 } from "@vex-chat/crypto";
 
 import { EventEmitter } from "eventemitter3";
+import { type Kysely, sql } from "kysely";
 
 export class SqliteStorage extends EventEmitter implements Storage {
     public ready = false;
@@ -273,7 +273,9 @@ export class SqliteStorage extends EventEmitter implements Storage {
         const rows = await this.db
             .selectFrom("sessions")
             .selectAll()
-            .where("publicKey", "=", hex)
+            .where((eb) =>
+                eb.or([eb("publicKey", "=", hex), eb("DHr", "=", hex)]),
+            )
             .limit(1)
             .execute();
 
@@ -331,7 +333,20 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     .addColumn("mode", "text")
                     .addColumn("lastUsed", "text")
                     .addColumn("verified", "integer")
+                    .addColumn("RK", "text")
+                    .addColumn("DHsPublic", "text")
+                    .addColumn("DHsPrivate", "text")
+                    .addColumn("DHr", "text")
+                    .addColumn("CKs", "text")
+                    .addColumn("CKr", "text")
+                    .addColumn("Ns", "integer", (col) => col.defaultTo(0))
+                    .addColumn("Nr", "integer", (col) => col.defaultTo(0))
+                    .addColumn("PN", "integer", (col) => col.defaultTo(0))
+                    .addColumn("skippedKeys", "text", (col) =>
+                        col.defaultTo("{}"),
+                    )
                     .execute();
+                await this.ensureSessionRatchetColumns();
 
                 await this.db.schema
                     .createTable("preKeys")
@@ -531,24 +546,62 @@ export class SqliteStorage extends EventEmitter implements Storage {
         if (this.closing) {
             return;
         }
+        const sealedCKr = session.CKr ? await this.sealHex(session.CKr) : null;
+        const sealedCKs = session.CKs ? await this.sealHex(session.CKs) : null;
+        const sealedDHsPrivate = await this.sealHex(session.DHsPrivate);
+        const sealedRK = await this.sealHex(session.RK);
+        const sealedSK = await this.sealHex(session.SK);
         try {
             await this.db
                 .insertInto("sessions")
                 .values({
+                    CKr: sealedCKr,
+                    CKs: sealedCKs,
                     deviceID: session.deviceID,
+                    DHr: session.DHr,
+                    DHsPrivate: sealedDHsPrivate,
+                    DHsPublic: session.DHsPublic,
                     fingerprint: session.fingerprint,
                     lastUsed: session.lastUsed,
                     mode: session.mode,
+                    Nr: session.Nr,
+                    Ns: session.Ns,
+                    PN: session.PN,
                     publicKey: session.publicKey,
+                    RK: sealedRK,
                     sessionID: session.sessionID,
-                    SK: await this.sealHex(session.SK),
+                    SK: sealedSK,
+                    skippedKeys: session.skippedKeys,
                     userID: session.userID,
                     verified: session.verified ? 1 : 0,
                 })
                 .execute();
         } catch (err: unknown) {
             if (this.isDuplicateError(err)) {
-                // duplicate SK — ignore
+                await this.db
+                    .updateTable("sessions")
+                    .set({
+                        CKr: sealedCKr,
+                        CKs: sealedCKs,
+                        deviceID: session.deviceID,
+                        DHr: session.DHr,
+                        DHsPrivate: sealedDHsPrivate,
+                        DHsPublic: session.DHsPublic,
+                        fingerprint: session.fingerprint,
+                        lastUsed: session.lastUsed,
+                        mode: session.mode,
+                        Nr: session.Nr,
+                        Ns: session.Ns,
+                        PN: session.PN,
+                        publicKey: session.publicKey,
+                        RK: sealedRK,
+                        SK: sealedSK,
+                        skippedKeys: session.skippedKeys,
+                        userID: session.userID,
+                        verified: session.verified ? 1 : 0,
+                    })
+                    .where("sessionID", "=", session.sessionID)
+                    .execute();
             } else {
                 throw err;
             }
@@ -614,6 +667,35 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
+    private async ensureSessionRatchetColumns(): Promise<void> {
+        const add = async (
+            column: string,
+            type: "integer" | "text",
+            defaultSql: null | string = null,
+        ) => {
+            const defaultClause = defaultSql ? ` DEFAULT ${defaultSql}` : "";
+            try {
+                await sql
+                    .raw(
+                        `ALTER TABLE sessions ADD COLUMN ${column} ${type}${defaultClause}`,
+                    )
+                    .execute(this.db);
+            } catch {
+                // Existing databases may already have this column.
+            }
+        };
+        await add("RK", "text");
+        await add("DHsPublic", "text");
+        await add("DHsPrivate", "text");
+        await add("DHr", "text");
+        await add("CKs", "text");
+        await add("CKr", "text");
+        await add("Ns", "integer", "0");
+        await add("Nr", "integer", "0");
+        await add("PN", "integer", "0");
+        await add("skippedKeys", "text", "'{}'");
+    }
+
     /**
      * Read `closing` where TypeScript would incorrectly assume it cannot
      * become true after an earlier guard (e.g. across `await`).
@@ -648,6 +730,24 @@ export class SqliteStorage extends EventEmitter implements Storage {
         return false;
     }
 
+    private parseSkippedKeys(raw: string): Record<string, string> {
+        try {
+            const parsed: unknown = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null) {
+                return {};
+            }
+            const out: Record<string, string> = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === "string") {
+                    out[k] = v;
+                }
+            }
+            return out;
+        } catch {
+            return {};
+        }
+    }
+
     /**
      * Encrypt a hex-encoded secret for at-rest storage.
      * Returns hex(nonce || ciphertext) where nonce is 24 random bytes.
@@ -669,28 +769,54 @@ export class SqliteStorage extends EventEmitter implements Storage {
     }
 
     private async sessionRowToSQLAsync(row: SessionRow): Promise<SessionSQL> {
+        const rawSK = await this.unsealHex(row.SK);
+        const rawRK = row.RK ? await this.unsealHex(row.RK) : rawSK;
         return {
+            CKr: row.CKr ? await this.unsealHex(row.CKr) : null,
+            CKs: row.CKs ? await this.unsealHex(row.CKs) : null,
             deviceID: row.deviceID,
+            DHr: row.DHr,
+            DHsPrivate: row.DHsPrivate
+                ? await this.unsealHex(row.DHsPrivate)
+                : rawSK,
+            DHsPublic: row.DHsPublic,
             fingerprint: row.fingerprint,
             lastUsed: row.lastUsed,
             mode: row.mode === "initiator" ? "initiator" : "receiver",
+            Nr: row.Nr,
+            Ns: row.Ns,
+            PN: row.PN,
             publicKey: row.publicKey,
+            RK: rawRK,
             sessionID: row.sessionID,
-            SK: await this.unsealHex(row.SK),
+            SK: rawSK,
+            skippedKeys: row.skippedKeys,
             userID: row.userID,
             verified: row.verified !== 0,
         };
     }
 
     private sqlToCrypto(session: SessionSQL): SessionCrypto {
+        const skippedKeys = this.parseSkippedKeys(session.skippedKeys);
         return {
+            CKr: session.CKr ? XUtils.decodeHex(session.CKr) : null,
+            CKs: session.CKs ? XUtils.decodeHex(session.CKs) : null,
+            DHr: session.DHr ? XUtils.decodeHex(session.DHr) : null,
+            DHsPrivate: XUtils.decodeHex(session.DHsPrivate),
+            DHsPublic: XUtils.decodeHex(session.DHsPublic),
             fingerprint: XUtils.decodeHex(session.fingerprint),
             lastUsed: session.lastUsed,
             mode: session.mode,
+            Nr: session.Nr,
+            Ns: session.Ns,
+            PN: session.PN,
             publicKey: XUtils.decodeHex(session.publicKey),
+            RK: XUtils.decodeHex(session.RK),
             sessionID: session.sessionID,
             SK: XUtils.decodeHex(session.SK),
+            skippedKeys,
             userID: session.userID,
+            verified: session.verified,
         };
     }
 

package/src/types/crypto.ts

@@ -25,14 +25,25 @@ export interface PreKeysCrypto extends UnsavedPreKey {
 
 /** In-memory representation of an encryption session (not yet persisted to SQL). */
 export interface SessionCrypto {
+    CKr: null | Uint8Array;
+    CKs: null | Uint8Array;
+    DHr: null | Uint8Array;
+    DHsPrivate: Uint8Array;
+    DHsPublic: Uint8Array;
     fingerprint: Uint8Array;
     lastUsed: string;
     mode: "initiator" | "receiver";
+    Nr: number;
+    Ns: number;
+    PN: number;
     publicKey: Uint8Array;
+    RK: Uint8Array;
     sessionID: string;
     /** Shared secret key derived during X3DH. */
     SK: Uint8Array;
+    skippedKeys: Record<string, string>;
     userID: string;
+    verified: boolean;
 }
 
 /** Prekey before DB storage — no index yet. */

package/src/utils/ratchet.ts

@@ -0,0 +1,289 @@
+/**
+ * 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 { RatchetHeader, SessionSQL } from "@vex-chat/types";
+
+import {
+    xBoxKeyPairAsync,
+    xConcat,
+    xDHAsync,
+    xHMAC,
+    xKDF,
+    XUtils,
+} from "@vex-chat/crypto";
+
+const VERSION = 1;
+
+const encoder = new TextEncoder();
+
+export function decodeRatchetHeader(extra: Uint8Array): RatchetHeader {
+    if (extra.length < 11) {
+        throw new Error("Malformed ratchet header: too short.");
+    }
+    const view = new DataView(extra.buffer, extra.byteOffset, extra.byteLength);
+    const version = view.getUint8(0);
+    if (version !== VERSION) {
+        throw new Error("Unsupported ratchet header version.");
+    }
+    const dhLen = view.getUint16(1, false);
+    const expected = 3 + dhLen + 8;
+    if (extra.length !== expected) {
+        throw new Error("Malformed ratchet header length.");
+    }
+    const dhPub = extra.slice(3, 3 + dhLen);
+    const pn = view.getUint32(3 + dhLen, false);
+    const n = view.getUint32(7 + dhLen, false);
+    return { dhPub, n, pn, version: 1 };
+}
+
+export function deriveInitialRootKey(sk: Uint8Array): Uint8Array {
+    return xKDF(xConcat(sk, encoder.encode("dr-root-v1")));
+}
+
+export function encodeRatchetHeader(header: RatchetHeader): Uint8Array {
+    if (header.dhPub.length > 65535) {
+        throw new Error("Ratchet header dhPub too large.");
+    }
+    const out = new Uint8Array(3 + header.dhPub.length + 8);
+    const view = new DataView(out.buffer);
+    view.setUint8(0, VERSION);
+    view.setUint16(1, header.dhPub.length, false);
+    out.set(header.dhPub, 3);
+    view.setUint32(3 + header.dhPub.length, header.pn, false);
+    view.setUint32(7 + header.dhPub.length, header.n, false);
+    return out;
+}
+
+export function hasRemoteDhChanged(
+    current: null | Uint8Array,
+    incoming: Uint8Array,
+): boolean {
+    if (!current) {
+        return true;
+    }
+    return !XUtils.bytesEqual(current, incoming);
+}
+
+export async function initRatchetSession(
+    sk: Uint8Array,
+    mode: "initiator" | "receiver",
+): Promise<{
+    CKr: null | string;
+    CKs: null | string;
+    DHr: null | string;
+    DHsPrivate: string;
+    DHsPublic: string;
+    Nr: number;
+    Ns: number;
+    PN: number;
+    RK: string;
+    skippedKeys: string;
+}> {
+    const RK = deriveInitialRootKey(sk);
+    const DHs = await xBoxKeyPairAsync();
+    const CKs =
+        mode === "initiator"
+            ? xHMAC({ label: "init-send-chain", version: VERSION }, RK)
+            : null;
+    return {
+        CKr: null,
+        CKs: CKs ? XUtils.encodeHex(CKs) : null,
+        DHr: null,
+        DHsPrivate: XUtils.encodeHex(DHs.secretKey),
+        DHsPublic: XUtils.encodeHex(DHs.publicKey),
+        Nr: 0,
+        Ns: 0,
+        PN: 0,
+        RK: XUtils.encodeHex(RK),
+        skippedKeys: "{}",
+    };
+}
+
+export async function ratchetStepReceive(
+    state: {
+        CKr: null | Uint8Array;
+        CKs: null | Uint8Array;
+        DHr: null | Uint8Array;
+        DHsPrivate: Uint8Array;
+        DHsPublic: Uint8Array;
+        Nr: number;
+        Ns: number;
+        PN: number;
+        RK: Uint8Array;
+        skippedKeys: Record<string, string>;
+    },
+    remoteDhPub: Uint8Array,
+    pn: number,
+): Promise<void> {
+    if (state.CKr && state.DHr) {
+        while (state.Nr < pn) {
+            const { chainKey, messageKey } = kdfChain(state.CKr);
+            state.CKr = chainKey;
+            state.skippedKeys[skippedKeyId(state.DHr, state.Nr)] =
+                XUtils.encodeHex(messageKey);
+            state.Nr += 1;
+        }
+    }
+
+    state.PN = state.Ns;
+    state.Ns = 0;
+    state.Nr = 0;
+    state.CKs = null;
+    state.DHr = remoteDhPub;
+
+    const dhOut = await xDHAsync(state.DHsPrivate, remoteDhPub);
+    const recv = kdfRoot(state.RK, dhOut);
+    state.RK = recv.rootKey;
+    state.CKr = recv.chainKey;
+}
+
+export async function ratchetStepSend(state: {
+    CKr: null | Uint8Array;
+    CKs: null | Uint8Array;
+    DHr: null | Uint8Array;
+    DHsPrivate: Uint8Array;
+    DHsPublic: Uint8Array;
+    Nr: number;
+    Ns: number;
+    PN: number;
+    RK: Uint8Array;
+    skippedKeys: Record<string, string>;
+}): Promise<void> {
+    if (!state.DHr) {
+        if (!state.CKs) {
+            state.CKs = xHMAC(
+                { label: "bootstrap-send-chain", version: VERSION },
+                state.RK,
+            );
+        }
+        return;
+    }
+    const nextDh = await xBoxKeyPairAsync();
+    state.PN = state.Ns;
+    state.Ns = 0;
+    state.DHsPrivate = nextDh.secretKey;
+    state.DHsPublic = nextDh.publicKey;
+    const dhOut = await xDHAsync(state.DHsPrivate, state.DHr);
+    const send = kdfRoot(state.RK, dhOut);
+    state.RK = send.rootKey;
+    state.CKs = send.chainKey;
+}
+
+export function sessionToSqlPatch(session: {
+    CKr: null | Uint8Array;
+    CKs: null | Uint8Array;
+    DHr: null | Uint8Array;
+    DHsPrivate: Uint8Array;
+    DHsPublic: Uint8Array;
+    Nr: number;
+    Ns: number;
+    PN: number;
+    RK: Uint8Array;
+    skippedKeys: Record<string, string>;
+}): Pick<
+    SessionSQL,
+    | "CKr"
+    | "CKs"
+    | "DHr"
+    | "DHsPrivate"
+    | "DHsPublic"
+    | "Nr"
+    | "Ns"
+    | "PN"
+    | "RK"
+    | "skippedKeys"
+> {
+    return {
+        CKr: session.CKr ? XUtils.encodeHex(session.CKr) : null,
+        CKs: session.CKs ? XUtils.encodeHex(session.CKs) : null,
+        DHr: session.DHr ? XUtils.encodeHex(session.DHr) : null,
+        DHsPrivate: XUtils.encodeHex(session.DHsPrivate),
+        DHsPublic: XUtils.encodeHex(session.DHsPublic),
+        Nr: session.Nr,
+        Ns: session.Ns,
+        PN: session.PN,
+        RK: XUtils.encodeHex(session.RK),
+        skippedKeys: JSON.stringify(session.skippedKeys),
+    };
+}
+
+export function takeReceiveMessageKey(
+    state: {
+        CKr: null | Uint8Array;
+        DHr: null | Uint8Array;
+        Nr: number;
+        skippedKeys: Record<string, string>;
+    },
+    remoteDhPub: Uint8Array,
+    n: number,
+): Uint8Array {
+    const skippedId = skippedKeyId(remoteDhPub, n);
+    const skipped = state.skippedKeys[skippedId];
+    if (skipped) {
+        const { [skippedId]: _discarded, ...rest } = state.skippedKeys;
+        state.skippedKeys = rest;
+        return XUtils.decodeHex(skipped);
+    }
+
+    if (!state.CKr) {
+        throw new Error("Missing receiving chain key.");
+    }
+
+    while (state.Nr < n) {
+        const { chainKey, messageKey } = kdfChain(state.CKr);
+        state.CKr = chainKey;
+        if (!state.DHr) {
+            throw new Error("Missing DHr when storing skipped key.");
+        }
+        state.skippedKeys[skippedKeyId(state.DHr, state.Nr)] =
+            XUtils.encodeHex(messageKey);
+        state.Nr += 1;
+    }
+
+    const { chainKey, messageKey } = kdfChain(state.CKr);
+    state.CKr = chainKey;
+    state.Nr += 1;
+    return messageKey;
+}
+
+export function takeSendMessageKey(state: {
+    CKs: null | Uint8Array;
+    Ns: number;
+}): { messageKey: Uint8Array; n: number } {
+    if (!state.CKs) {
+        throw new Error("Missing sending chain key.");
+    }
+    const n = state.Ns;
+    const { chainKey, messageKey } = kdfChain(state.CKs);
+    state.CKs = chainKey;
+    state.Ns += 1;
+    return { messageKey, n };
+}
+
+function kdfChain(ck: Uint8Array): {
+    chainKey: Uint8Array;
+    messageKey: Uint8Array;
+} {
+    return {
+        chainKey: xHMAC({ label: "ck-next", version: VERSION }, ck),
+        messageKey: xHMAC({ label: "msg-key", version: VERSION }, ck),
+    };
+}
+
+function kdfRoot(
+    rootKey: Uint8Array,
+    dhOut: Uint8Array,
+): { chainKey: Uint8Array; rootKey: Uint8Array } {
+    const material = xKDF(xConcat(rootKey, dhOut, encoder.encode("dr-v1")));
+    return {
+        chainKey: xHMAC({ label: "chain", version: VERSION }, material),
+        rootKey: xHMAC({ label: "root", version: VERSION }, material),
+    };
+}
+
+function skippedKeyId(dhPub: Uint8Array, n: number): string {
+    return `${XUtils.encodeHex(dhPub)}:${String(n)}`;
+}

package/src/utils/sqlSessionToCrypto.ts

@@ -10,13 +10,43 @@ import type { SessionSQL } from "@vex-chat/types";
 import { XUtils } from "@vex-chat/crypto";
 
 export function sqlSessionToCrypto(session: SessionSQL): SessionCrypto {
+    const skippedKeys = parseSkippedKeys(session.skippedKeys);
     return {
+        CKr: session.CKr ? XUtils.decodeHex(session.CKr) : null,
+        CKs: session.CKs ? XUtils.decodeHex(session.CKs) : null,
+        DHr: session.DHr ? XUtils.decodeHex(session.DHr) : null,
+        DHsPrivate: XUtils.decodeHex(session.DHsPrivate),
+        DHsPublic: XUtils.decodeHex(session.DHsPublic),
         fingerprint: XUtils.decodeHex(session.fingerprint),
         lastUsed: session.lastUsed,
         mode: session.mode,
+        Nr: session.Nr,
+        Ns: session.Ns,
+        PN: session.PN,
         publicKey: XUtils.decodeHex(session.publicKey),
+        RK: XUtils.decodeHex(session.RK),
         sessionID: session.sessionID,
         SK: XUtils.decodeHex(session.SK),
+        skippedKeys,
         userID: session.userID,
+        verified: session.verified,
     };
 }
+
+function parseSkippedKeys(raw: string): Record<string, string> {
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            return {};
+        }
+        const out: Record<string, string> = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === "string") {
+                out[k] = v;
+            }
+        }
+        return out;
+    } catch {
+        return {};
+    }
+}