@vex-chat/libvex 7.1.5 → 7.2.0

package/src/Client.ts

@@ -15,6 +15,10 @@ import type {
 import type { KeyPair } from "@vex-chat/crypto";
 import type {
     ActionToken,
+    CallEvent,
+    CallResourceData,
+    CallSession,
+    CallSignalPayload,
     ChallMsg,
     Channel,
     Device,
@@ -22,6 +26,7 @@ import type {
     Emoji,
     FileResponse,
     FileSQL,
+    IceServerConfig,
     Invite,
     KeyBundle,
     MailWS,
@@ -70,6 +75,9 @@ import {
     XUtils,
 } from "@vex-chat/crypto";
 import {
+    CallEventSchema,
+    CallSessionSchema,
+    IceServerConfigSchema,
     MailType,
     MailWSSchema,
     PermissionSchema,
@@ -190,6 +198,16 @@ function debugLibvexDm(
     console.error(`[libvex:debug-dm] ${payload}`);
 }
 
+function errorFromUnknown(err: unknown): Error {
+    if (err instanceof Error) {
+        return err;
+    }
+    if (typeof err === "string") {
+        return new Error(err);
+    }
+    return new Error(JSON.stringify(err));
+}
+
 function ignoreSocketTeardown(err: unknown): void {
     if (err instanceof WebSocketNotOpenError) return;
     // Re-throw anything else as a real unhandled rejection so it
@@ -356,6 +374,28 @@ import { uuidToUint8 } from "./utils/uint8uuid.js";
 
 const _protocolMsgRegex = /��\w+:\w+��/g;
 
+/**
+ * Voice-call signaling operations.
+ *
+ * `libvex` moves authenticated call control over Spire. Platform apps own
+ * WebRTC/media capture and pass offers, answers, and ICE candidates through
+ * these methods.
+ */
+export interface Calls {
+    accept: (callID: string, signal?: CallSignalPayload) => Promise<CallEvent>;
+    active: () => Promise<CallSession[]>;
+    cancel: (callID: string) => Promise<CallEvent>;
+    hangup: (callID: string) => Promise<CallEvent>;
+    ice: (callID: string, signal: CallSignalPayload) => Promise<CallEvent>;
+    iceServers: () => Promise<IceServerConfig[]>;
+    reject: (callID: string) => Promise<CallEvent>;
+    signal: (callID: string, signal: CallSignalPayload) => Promise<CallEvent>;
+    startDM: (
+        recipientUserID: string,
+        signal?: CallSignalPayload,
+    ) => Promise<CallEvent>;
+}
+
 /**
  * @ignore
  */
@@ -1034,6 +1074,8 @@ const retryRequestNotifyData = z.union([
  * and {@link Client.once}.
  */
 export interface ClientEvents {
+    /** Voice-call signaling changed or an incoming call was received. */
+    call: (event: CallEvent) => void;
     /** The client has been shut down (via {@link Client.close}). */
     closed: () => void;
     /** WebSocket authorized by the server; pre-auth setup begins. */
@@ -1280,6 +1322,35 @@ export class Client {
 
     private static readonly NOT_FOUND_TTL = 30 * 60 * 1000;
 
+    /**
+     * Voice-call signaling operations.
+     *
+     * Platform apps own native media capture/WebRTC. These methods only move
+     * authenticated signaling and call state over Spire.
+     */
+    public calls: Calls = {
+        accept: (callID: string, signal?: CallSignalPayload) =>
+            this.sendCallResource("ACCEPT", {
+                callID,
+                ...(signal ? { signal } : {}),
+            }),
+        active: this.fetchActiveCalls.bind(this),
+        cancel: (callID: string) => this.sendCallResource("CANCEL", { callID }),
+        hangup: (callID: string) => this.sendCallResource("HANGUP", { callID }),
+        ice: (callID: string, signal: CallSignalPayload) =>
+            this.sendCallResource("ICE", { callID, signal }),
+        iceServers: this.fetchIceServers.bind(this),
+        reject: (callID: string) => this.sendCallResource("REJECT", { callID }),
+        signal: (callID: string, signal: CallSignalPayload) =>
+            this.sendCallResource("SIGNAL", { callID, signal }),
+        startDM: (recipientUserID: string, signal?: CallSignalPayload) =>
+            this.sendCallResource("INVITE", {
+                conversationType: "dm",
+                recipientUserID,
+                ...(signal ? { signal } : {}),
+            }),
+    };
+
     /**
      * Browser-safe NODE_ENV accessor.
      * Uses indirect lookup so the bare `process` global never appears in
@@ -2488,6 +2559,7 @@ export class Client {
     private acknowledgeRepeatedDecryptFailure(
         mail: MailWS,
         count: number,
+        timestamp: string,
     ): void {
         if (count < 2) return;
         if (libvexDebugDmEnabled()) {
@@ -2498,6 +2570,7 @@ export class Client {
                 thisDevice: this.getDevice().deviceID,
             });
         }
+        this.emitUndecryptedMessage(mail, timestamp);
         this.acknowledgeInboundMail(mail);
     }
 
@@ -2978,6 +3051,7 @@ export class Client {
             }
         });
     }
+
     private async deliverMailResourceOverSocket(
         msg: ResourceMsg,
         header: Uint8Array,
@@ -3007,6 +3081,7 @@ export class Client {
             });
         });
     }
+
     private deviceListFailureDetail(err: unknown): string {
         if (!isHttpError(err)) {
             return "";
@@ -3021,6 +3096,39 @@ export class Client {
         return "";
     }
 
+    private emitUndecryptedMessage(mail: MailWS, timestamp: string): void {
+        this.emitter.emit("message", {
+            authorID: mail.authorID,
+            decrypted: false,
+            direction: "incoming",
+            forward: mail.forward,
+            group: mail.group ? uuid.stringify(mail.group) : null,
+            mailID: mail.mailID,
+            message: "",
+            nonce: XUtils.encodeHex(new Uint8Array(mail.nonce)),
+            readerID: mail.readerID,
+            recipient: mail.recipient,
+            sender: mail.sender,
+            timestamp,
+        });
+    }
+
+    private async fetchActiveCalls(): Promise<CallSession[]> {
+        const res = await this.http.get(this.getHost() + "/calls/active", {
+            responseType: "json",
+        });
+        return z.object({ calls: z.array(CallSessionSchema) }).parse(res.data)
+            .calls;
+    }
+    private async fetchIceServers(): Promise<IceServerConfig[]> {
+        const res = await this.http.get(this.getHost() + "/calls/ice-servers", {
+            responseType: "json",
+        });
+        return z
+            .object({ iceServers: z.array(IceServerConfigSchema) })
+            .parse(res.data).iceServers;
+    }
+
     /**
      * Gets a list of permissions for a server.
      *
@@ -3661,6 +3769,14 @@ export class Client {
 
     private async handleNotify(msg: NotifyMsg) {
         switch (msg.event) {
+            case "call":
+            case "callInvite": {
+                const parsed = CallEventSchema.safeParse(msg.data);
+                if (parsed.success) {
+                    this.emitter.emit("call", parsed.data);
+                }
+                break;
+            }
             case "deviceRequest": {
                 const parsed = deviceRequestNotifyData.safeParse(msg.data);
                 if (parsed.success) {
@@ -4322,11 +4438,14 @@ export class Client {
                                   );
 
                         if (otk?.index !== preKeyIndex && preKeyIndex !== 0) {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             if (libvexDebugDmEnabled()) {
                                 try {
                                     debugLibvexDm(
                                         "readMail initial: abort (otk index mismatch)",
                                         {
+                                            attempts: failureCount,
                                             mailID: mail.mailID,
                                             otkIndex: String(
                                                 otk?.index ?? "null",
@@ -4345,6 +4464,17 @@ export class Client {
                                     );
                                 }
                             }
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                                timestamp,
+                            );
                             return;
                         }
 
@@ -4363,11 +4493,14 @@ export class Client {
                                   return c;
                               })();
                         if (!IK_A) {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             if (libvexDebugDmEnabled()) {
                                 try {
                                     debugLibvexDm(
                                         "readMail initial: abort (IK_A null, Ed→X25519?)",
                                         {
+                                            attempts: failureCount,
                                             fips: String(fipsRead),
                                             mailID: mail.mailID,
                                             thisDevice:
@@ -4383,6 +4516,17 @@ export class Client {
                                     );
                                 }
                             }
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                                timestamp,
+                            );
                             return;
                         }
                         const EK_A = ephKey;
@@ -4431,11 +4575,14 @@ export class Client {
                               );
 
                         if (!XUtils.bytesEqual(hmac, header)) {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             if (libvexDebugDmEnabled()) {
                                 try {
                                     debugLibvexDm(
                                         "readMail initial: abort (HMAC mismatch)",
                                         {
+                                            attempts: failureCount,
                                             mailID: mail.mailID,
                                             preKeyIndex: String(preKeyIndex),
                                             thisDevice:
@@ -4451,6 +4598,17 @@ export class Client {
                                     );
                                 }
                             }
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                                timestamp,
+                            );
                             return;
                         }
                         const unsealed = await xSecretboxOpenAsync(
@@ -4582,15 +4740,29 @@ export class Client {
                             }
                             this.acknowledgeInboundMail(mail);
                         } else {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             if (libvexDebugDmEnabled()) {
                                 debugLibvexDm(
                                     "readMail initial: abort (xSecretboxOpen null)",
                                     {
+                                        attempts: failureCount,
                                         mailID: mail.mailID,
                                         preKeyIndex: String(preKeyIndex),
                                     },
                                 );
                             }
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                                timestamp,
+                            );
                         }
                         break;
                     case MailType.subsequent: {
@@ -4613,7 +4785,20 @@ export class Client {
                         }
 
                         if (!session) {
+                            const failureCount =
+                                this.registerDecryptFailure(mail);
                             healSession();
+                            if (failureCount === 1) {
+                                this.emitter.emit("retryRequest", {
+                                    mailID: mail.mailID,
+                                    source: "decrypt_failure",
+                                });
+                            }
+                            this.acknowledgeRepeatedDecryptFailure(
+                                mail,
+                                failureCount,
+                                timestamp,
+                            );
                             return;
                         }
 
@@ -4717,6 +4902,7 @@ export class Client {
                             this.acknowledgeRepeatedDecryptFailure(
                                 mail,
                                 failureCount,
+                                timestamp,
                             );
                             return;
                         }
@@ -4808,6 +4994,7 @@ export class Client {
                             this.acknowledgeRepeatedDecryptFailure(
                                 mail,
                                 failureCount,
+                                timestamp,
                             );
                         }
                         break;
@@ -5179,6 +5366,89 @@ export class Client {
         }
     }
 
+    private async sendCallResource(
+        action: string,
+        data: CallResourceData,
+    ): Promise<CallEvent> {
+        const msg: ResourceMsg = {
+            action,
+            data,
+            resourceType: "call",
+            transmissionID: uuid.v4(),
+            type: "resource",
+        };
+
+        return await new Promise<CallEvent>((resolve, reject) => {
+            const settle = (err: null | unknown, event?: CallEvent) => {
+                this.socket.off("message", callback);
+                if (err !== null) {
+                    reject(errorFromUnknown(err));
+                    return;
+                }
+                if (!event) {
+                    reject(new Error("Call signaling response was empty."));
+                    return;
+                }
+                resolve(event);
+            };
+
+            const callback = (packedMsg: Uint8Array) => {
+                const [_header, receivedMsg] = XUtils.unpackMessage(packedMsg);
+                if (receivedMsg.transmissionID !== msg.transmissionID) {
+                    return;
+                }
+
+                const parsed = WSMessageSchema.safeParse(receivedMsg);
+                if (!parsed.success) {
+                    settle(
+                        "Call signaling failed: " + JSON.stringify(receivedMsg),
+                    );
+                    return;
+                }
+
+                if (parsed.data.type === "success") {
+                    const event = CallEventSchema.safeParse(parsed.data.data);
+                    if (!event.success) {
+                        settle(
+                            "Invalid call signaling response: " +
+                                JSON.stringify(event.error.issues),
+                        );
+                        return;
+                    }
+                    settle(null, event.data);
+                    return;
+                }
+
+                if (parsed.data.type === "error") {
+                    settle(new Error(parsed.data.error));
+                    return;
+                }
+
+                if (
+                    parsed.data.type === "notify" &&
+                    (parsed.data.event === "call" ||
+                        parsed.data.event === "callInvite")
+                ) {
+                    const event = CallEventSchema.safeParse(parsed.data.data);
+                    if (event.success) {
+                        settle(null, event.data);
+                    }
+                    return;
+                }
+
+                settle(
+                    "Unexpected call signaling response: " +
+                        JSON.stringify(parsed.data),
+                );
+            };
+
+            this.socket.on("message", callback);
+            this.send(msg).catch((err: unknown) => {
+                settle(err);
+            });
+        });
+    }
+
     private async sendGroupMessage(
         channelID: string,
         message: string,

package/src/__tests__/storage-sqlite.test.ts

@@ -0,0 +1,122 @@
+import type { Message } from "../index.js";
+import type { ClientDatabase } from "../storage/schema.js";
+
+import BetterSqlite3 from "better-sqlite3";
+import { Kysely, SqliteDialect } from "kysely";
+import { describe, expect, it } from "vitest";
+
+import { SqliteStorage } from "../storage/sqlite.js";
+
+describe("SqliteStorage message at-rest encryption", () => {
+    it("stores generated decrypt-failure placeholders as the only plaintext exception", async () => {
+        const { db, storage } = makeStorage();
+        try {
+            await storage.init();
+
+            const placeholder = makeMessage({
+                decrypted: false,
+                mailID: "placeholder-mail",
+                message: "",
+                nonce: nonceHex(1),
+            });
+            await storage.saveMessage(placeholder);
+
+            const row = await messageRow(db, placeholder.mailID);
+            expect(row?.decrypted).toBe(0);
+            expect(row?.extra).toBeNull();
+            expect(row?.message).toBe("");
+
+            const history = await storage.getMessageHistory(
+                placeholder.authorID,
+            );
+            expect(history).toMatchObject([
+                {
+                    decrypted: false,
+                    mailID: placeholder.mailID,
+                    message: "",
+                },
+            ]);
+        } finally {
+            await storage.close();
+        }
+    });
+
+    it("seals non-placeholder undecrypted messages and round-trips their content", async () => {
+        const { db, storage } = makeStorage();
+        try {
+            await storage.init();
+
+            const imported = makeMessage({
+                decrypted: false,
+                extra: JSON.stringify({ imported: true }),
+                mailID: "imported-mail",
+                message: "cleartext should not sit in sqlite",
+                nonce: nonceHex(2),
+            });
+            await storage.saveMessage(imported);
+
+            const row = await messageRow(db, imported.mailID);
+            expect(row?.decrypted).toBe(0);
+            expect(row?.extra).toBeNull();
+            expect(row?.message).not.toContain(imported.message);
+            expect(row?.message).not.toContain(imported.extra ?? "");
+
+            const history = await storage.getMessageHistory(imported.authorID);
+            expect(history).toMatchObject([
+                {
+                    decrypted: false,
+                    extra: imported.extra,
+                    mailID: imported.mailID,
+                    message: imported.message,
+                },
+            ]);
+        } finally {
+            await storage.close();
+        }
+    });
+});
+
+function makeMessage(overrides: Partial<Message>): Message {
+    return {
+        authorID: "peer-user",
+        decrypted: true,
+        direction: "incoming",
+        forward: false,
+        group: null,
+        mailID: "mail",
+        message: "hello",
+        nonce: nonceHex(0),
+        readerID: "local-user",
+        recipient: "local-device",
+        sender: "peer-device",
+        timestamp: "2026-06-01T00:00:00.000Z",
+        ...overrides,
+    };
+}
+
+function makeStorage(): {
+    db: Kysely<ClientDatabase>;
+    storage: SqliteStorage;
+} {
+    const db = new Kysely<ClientDatabase>({
+        dialect: new SqliteDialect({
+            database: new BetterSqlite3(":memory:"),
+        }),
+    });
+    return {
+        db,
+        storage: new SqliteStorage(db, new Uint8Array(32).fill(7)),
+    };
+}
+
+async function messageRow(db: Kysely<ClientDatabase>, mailID: string) {
+    return await db
+        .selectFrom("messages")
+        .select(["decrypted", "extra", "message"])
+        .where("mailID", "=", mailID)
+        .executeTakeFirst();
+}
+
+function nonceHex(value: number): string {
+    return value.toString(16).padStart(48, "0");
+}

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export { Client, DeviceApprovalRequiredError } from "./Client.js";
 export type {
+    Calls,
     Channel,
     Channels,
     ClientEvents,
@@ -96,4 +97,13 @@ export type {
     UnsavedPreKey,
 } from "./types/index.js";
 // Re-export app-facing types
-export type { Invite, Passkey } from "@vex-chat/types";
+export type {
+    CallAction,
+    CallEvent,
+    CallParticipant,
+    CallSession,
+    CallSignalPayload,
+    IceServerConfig,
+    Invite,
+    Passkey,
+} from "@vex-chat/types";

package/src/storage/sqlite.ts

@@ -538,24 +538,30 @@ export class SqliteStorage extends EventEmitter implements Storage {
             return;
         }
 
-        // Encrypt plaintext with at-rest key before saving to disk.
         const storedPlaintext = encodeStoredMessagePlaintext(message);
+        const isPlaintextFailurePlaceholder =
+            !message.decrypted &&
+            message.message === "" &&
+            message.extra === undefined;
         const fips = getCryptoProfile() === "fips";
-        const ct = fips
-            ? await xSecretboxAsync(
-                  XUtils.decodeUTF8(storedPlaintext),
-                  XUtils.decodeHex(message.nonce),
-                  this.atRestAesKey,
-              )
-            : xSecretbox(
-                  XUtils.decodeUTF8(storedPlaintext),
-                  XUtils.decodeHex(message.nonce),
-                  this.atRestAesKey,
+        const encryptedMessage = isPlaintextFailurePlaceholder
+            ? storedPlaintext
+            : XUtils.encodeHex(
+                  fips
+                      ? await xSecretboxAsync(
+                            XUtils.decodeUTF8(storedPlaintext),
+                            XUtils.decodeHex(message.nonce),
+                            this.atRestAesKey,
+                        )
+                      : xSecretbox(
+                            XUtils.decodeUTF8(storedPlaintext),
+                            XUtils.decodeHex(message.nonce),
+                            this.atRestAesKey,
+                        ),
               );
         if (this.isClosingNow()) {
             return;
         }
-        const encryptedMessage = XUtils.encodeHex(ct);
 
         try {
             await this.db
@@ -787,7 +793,9 @@ export class SqliteStorage extends EventEmitter implements Storage {
         for (const msg of messages) {
             const decryptedFlag = msg.decrypted !== 0;
             let plaintext = msg.message;
-            if (decryptedFlag) {
+            const isPlaintextFailurePlaceholder =
+                !decryptedFlag && msg.message === "" && msg.extra === null;
+            if (!isPlaintextFailurePlaceholder) {
                 const cipher = XUtils.decodeHex(msg.message);
                 const nonce = XUtils.decodeHex(msg.nonce);
                 const decrypted = fips