@vex-chat/libvex 6.2.2 → 6.3.0

package/src/Client.ts

@@ -78,6 +78,11 @@ import { EventEmitter } from "eventemitter3";
 import * as uuid from "uuid";
 import { z } from "zod/v4";
 
+import {
+    clampLocalMessageRetentionDays,
+    formatVexRetentionEnvelope,
+    stripVexRetentionEnvelope,
+} from "./retention.js";
 import {
     WebSocketAdapter,
     WebSocketNotOpenError,
@@ -363,6 +368,13 @@ export interface ClientOptions {
     host?: string;
     /** Use sqlite in-memory mode (`:memory:`) instead of a file. */
     inMemoryDb?: boolean;
+    /**
+     * Maximum age (in days) for messages kept in local storage. Values above
+     * 30 are clamped to 30 to match server retention. Peers may request a
+     * shorter window via an optional plaintext hint; this setting is still
+     * capped at 30 and is not enforceable against a modified client.
+     */
+    localMessageRetentionDays?: number;
     /** Whether local message history should be persisted by default storage. */
     saveHistory?: boolean;
     /** Use `http/ws` instead of `https/wss`. Intended for local/dev environments. */
@@ -552,6 +564,12 @@ export interface Message {
     readerID: string;
     /** Recipient device ID. */
     recipient: string;
+    /**
+     * Optional peer hint (1–30): cooperative senders prefix plaintext; used
+     * with {@link ClientOptions.localMessageRetentionDays} to pick the
+     * shorter local retention window. Ignored when absent.
+     */
+    retentionHintDays?: number;
     /** Sender device ID. */
     sender: string;
     /** Time the message was created/received. */
@@ -740,7 +758,11 @@ export interface Messages {
     /** Deletes local history for a user/channel. */
     delete: (userOrChannelID: string) => Promise<void>;
     /** Sends an encrypted message to all members of a channel. */
-    group: (channelID: string, message: string) => Promise<void>;
+    group: (
+        channelID: string,
+        message: string,
+        opts?: { retentionHintDays?: number },
+    ) => Promise<void>;
     /** Deletes all locally stored message history. */
     purge: () => Promise<void>;
     /** Returns local direct-message history with one user. */
@@ -748,7 +770,11 @@ export interface Messages {
     /** Returns local group-message history for one channel. */
     retrieveGroup: (channelID: string) => Promise<Message[]>;
     /** Sends an encrypted direct message to one user. */
-    send: (userID: string, message: string) => Promise<void>;
+    send: (
+        userID: string,
+        message: string,
+        opts?: { retentionHintDays?: number },
+    ) => Promise<void>;
 }
 
 /**
@@ -1072,7 +1098,11 @@ export class Client {
          * @param channelID - The channel to send a message to.
          * @param message - The message to send.
          */
-        group: this.sendGroupMessage.bind(this),
+        group: (
+            channelID: string,
+            message: string,
+            opts?: { retentionHintDays?: number },
+        ) => this.sendGroupMessage(channelID, message, opts),
         purge: this.purgeHistory.bind(this),
         /**
          * Gets the message history with a specific userID.
@@ -1093,7 +1123,11 @@ export class Client {
          * @param userID - The user to send a message to.
          * @param message - The message to send.
          */
-        send: this.sendMessage.bind(this),
+        send: (
+            userID: string,
+            message: string,
+            opts?: { retentionHintDays?: number },
+        ) => this.sendMessage(userID, message, opts),
     };
     /**
      * Server moderation helper methods.
@@ -1250,9 +1284,13 @@ export class Client {
     private readonly httpAbortController = new AbortController();
     private readonly idKeys: KeyPair | null;
     private isAlive: boolean = true;
-    private readonly mailInterval?: NodeJS.Timeout;
+    private localMessageRetentionDays: number;
 
+    private localRetentionPurgeTimer: null | ReturnType<typeof setInterval> =
+        null;
+    private readonly mailInterval?: NodeJS.Timeout;
     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.
@@ -1266,20 +1304,21 @@ 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();
     private sessionRecords: Record<string, SessionCrypto> = {};
 
@@ -1303,6 +1342,9 @@ export class Client {
         storage?: Storage,
     ) {
         this.options = options;
+        this.localMessageRetentionDays = clampLocalMessageRetentionDays(
+            options?.localMessageRetentionDays,
+        );
         this.cryptoProfile = material.cryptoProfile;
         this.signKeys = material.signKeys;
         this.idKeys = material.idKeys;
@@ -1600,6 +1642,14 @@ export class Client {
         if (this.mailInterval) {
             clearInterval(this.mailInterval);
         }
+        if (this.localRetentionPurgeTimer) {
+            clearInterval(this.localRetentionPurgeTimer);
+            this.localRetentionPurgeTimer = null;
+        }
+        if (this.retentionPurgeDebounce) {
+            clearTimeout(this.retentionPurgeDebounce);
+            this.retentionPurgeDebounce = null;
+        }
         delete this.xKeyRing;
 
         if (!muteEvent) {
@@ -1679,6 +1729,11 @@ export class Client {
         };
     }
 
+    /** Current local retention cap in days (always 1–30). */
+    public getLocalMessageRetentionDays(): number {
+        return this.localMessageRetentionDays;
+    }
+
     /**
      * Authenticates with username/password and stores the Bearer auth token.
      *
@@ -2019,6 +2074,15 @@ export class Client {
         return this;
     }
 
+    /**
+     * Updates the local retention cap (1–30 days) and prunes immediately.
+     * Does not affect server-side storage.
+     */
+    public setLocalMessageRetentionDays(days: number): void {
+        this.localMessageRetentionDays = clampLocalMessageRetentionDays(days);
+        void this.runLocalRetentionPurge();
+    }
+
     /**
      * Triggers an immediate inbox sync by fetching `/mail` once.
      * Useful on mobile foreground resume where background work may pause.
@@ -2060,6 +2124,11 @@ export class Client {
         return whoami;
     }
 
+    private acknowledgeInboundMail(mail: MailWS): void {
+        this.seenMailIDs.add(mail.mailID);
+        this.sendReceipt(new Uint8Array(mail.nonce));
+    }
+
     private async approveDeviceRequest(requestID: string): Promise<Device> {
         const req = await this.getDeviceRegistrationRequest(requestID);
         if (!req) {
@@ -2496,7 +2565,6 @@ export class Client {
     private async deleteServer(serverID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/server/" + serverID);
     }
-
     private deviceListFailureDetail(err: unknown): string {
         if (!isAxiosError(err)) {
             return "";
@@ -2510,7 +2578,6 @@ export class Client {
         }
         return "";
     }
-
     /**
      * Gets a list of permissions for a server.
      *
@@ -2526,6 +2593,7 @@ export class Client {
         );
         return decodeAxios(PermissionArrayCodec, res.data);
     }
+
     private async fetchUser(
         userIdentifier: string,
     ): Promise<[null | User, AxiosError | null]> {
@@ -3049,6 +3117,8 @@ export class Client {
         }
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     /**
      * Initializes the keyring. This must be called before anything else.
      */
@@ -3068,9 +3138,16 @@ export class Client {
 
         await this.populateKeyRing();
         this.emitter.on("message", this.onInternalMessage);
+        void this.runLocalRetentionPurge();
+        this.localRetentionPurgeTimer = setInterval(
+            () => void this.runLocalRetentionPurge(),
+            6 * 60 * 60 * 1000,
+        );
         this.emitter.emit("ready");
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     private initSocket() {
         try {
             if (!this.token) {
@@ -3169,8 +3246,6 @@ export class Client {
         }
     }
 
-    // ── Passkeys ────────────────────────────────────────────────────────
-
     /**
      * Fresh read of the `manuallyClosing` flag for async loops — direct property checks
      * after `await` are flagged as always-false by control-flow analysis even though
@@ -3279,6 +3354,7 @@ export class Client {
             return;
         }
         void this.database.saveMessage(message);
+        this.scheduleRetentionPurge();
     };
 
     private async passkeyApproveDeviceRequest(
@@ -3503,7 +3579,6 @@ export class Client {
             }
             return;
         }
-        this.seenMailIDs.add(mail.mailID);
 
         if (this.manuallyClosing) {
             if (libvexDebugDmEnabled()) {
@@ -3514,7 +3589,6 @@ export class Client {
             return;
         }
 
-        this.sendReceipt(new Uint8Array(mail.nonce));
         let timeout = 1;
         while (this.reading) {
             await sleep(timeout);
@@ -3709,13 +3783,39 @@ export class Client {
                             if (!mail.forward) {
                                 plaintext = XUtils.encodeUTF8(unsealed);
                             }
+                            let incomingPlain = plaintext;
+                            let hintFromEnvelope: number | undefined;
+                            if (!mail.forward && plaintext.length > 0) {
+                                const stripped =
+                                    stripVexRetentionEnvelope(plaintext);
+                                incomingPlain = stripped.body;
+                                hintFromEnvelope = stripped.retentionHintDays;
+                            }
 
                             // emit the message
                             const fwdMsg1 = mail.forward
                                 ? messageSchema.parse(msgpack.decode(unsealed))
                                 : null;
                             const message: Message = fwdMsg1
-                                ? { ...fwdMsg1, forward: true }
+                                ? (() => {
+                                      const stripped =
+                                          stripVexRetentionEnvelope(
+                                              fwdMsg1.message,
+                                          );
+                                      const base: Message = {
+                                          ...fwdMsg1,
+                                          forward: true,
+                                          message: stripped.body,
+                                      };
+                                      return stripped.retentionHintDays !==
+                                          undefined
+                                          ? {
+                                                ...base,
+                                                retentionHintDays:
+                                                    stripped.retentionHintDays,
+                                            }
+                                          : base;
+                                  })()
                                 : {
                                       authorID: mail.authorID,
                                       decrypted: true,
@@ -3725,12 +3825,18 @@ export class Client {
                                           ? uuid.stringify(mail.group)
                                           : null,
                                       mailID: mail.mailID,
-                                      message: plaintext,
+                                      message: incomingPlain,
                                       nonce: XUtils.encodeHex(
                                           new Uint8Array(mail.nonce),
                                       ),
                                       readerID: mail.readerID,
                                       recipient: mail.recipient,
+                                      ...(hintFromEnvelope !== undefined
+                                          ? {
+                                                retentionHintDays:
+                                                    hintFromEnvelope,
+                                            }
+                                          : {}),
                                       sender: mail.sender,
                                       timestamp: timestamp,
                                   };
@@ -3816,6 +3922,7 @@ export class Client {
                                 this.emitter.emit("session", newSession, user);
                             } else {
                             }
+                            this.acknowledgeInboundMail(mail);
                         } else {
                             if (libvexDebugDmEnabled()) {
                                 debugLibvexDm(
@@ -3896,11 +4003,35 @@ export class Client {
                             const fwdMsg2 = mail.forward
                                 ? messageSchema.parse(msgpack.decode(decrypted))
                                 : null;
+                            const rawIncoming = XUtils.encodeUTF8(decrypted);
+                            let bodyIncoming = rawIncoming;
+                            let hintIncoming: number | undefined;
+                            if (!mail.forward) {
+                                const stripped =
+                                    stripVexRetentionEnvelope(rawIncoming);
+                                bodyIncoming = stripped.body;
+                                hintIncoming = stripped.retentionHintDays;
+                            }
                             const message: Message = fwdMsg2
-                                ? {
-                                      ...fwdMsg2,
-                                      forward: true,
-                                  }
+                                ? (() => {
+                                      const stripped =
+                                          stripVexRetentionEnvelope(
+                                              fwdMsg2.message,
+                                          );
+                                      const base: Message = {
+                                          ...fwdMsg2,
+                                          forward: true,
+                                          message: stripped.body,
+                                      };
+                                      return stripped.retentionHintDays !==
+                                          undefined
+                                          ? {
+                                                ...base,
+                                                retentionHintDays:
+                                                    stripped.retentionHintDays,
+                                            }
+                                          : base;
+                                  })()
                                 : {
                                       authorID: mail.authorID,
                                       decrypted: true,
@@ -3910,12 +4041,15 @@ export class Client {
                                           ? uuid.stringify(mail.group)
                                           : null,
                                       mailID: mail.mailID,
-                                      message: XUtils.encodeUTF8(decrypted),
+                                      message: bodyIncoming,
                                       nonce: XUtils.encodeHex(
                                           new Uint8Array(mail.nonce),
                                       ),
                                       readerID: mail.readerID,
                                       recipient: mail.recipient,
+                                      ...(hintIncoming !== undefined
+                                          ? { retentionHintDays: hintIncoming }
+                                          : {}),
                                       sender: mail.sender,
                                       timestamp: timestamp,
                                   };
@@ -3949,6 +4083,7 @@ export class Client {
                             this.sessionRecords[
                                 XUtils.encodeHex(session.publicKey)
                             ] = session;
+                            this.acknowledgeInboundMail(mail);
                         } else {
                             void healSession();
                             this.emitter.emit("retryRequest", {
@@ -4163,6 +4298,19 @@ export class Client {
         return device;
     }
 
+    private async runLocalRetentionPurge(): Promise<void> {
+        if (this.isManualCloseInFlight()) {
+            return;
+        }
+        try {
+            await this.database.pruneExpiredLocalMessages(
+                this.localMessageRetentionDays,
+            );
+        } catch {
+            /* best-effort */
+        }
+    }
+
     /**
      * `xDHAsync` and other helpers in `@vex-chat/crypto` use the process-wide
      * active profile. When several {@link Client} instances use different
@@ -4184,6 +4332,16 @@ export class Client {
         }
     }
 
+    private scheduleRetentionPurge(): void {
+        if (this.retentionPurgeDebounce) {
+            clearTimeout(this.retentionPurgeDebounce);
+        }
+        this.retentionPurgeDebounce = setTimeout(() => {
+            this.retentionPurgeDebounce = null;
+            void this.runLocalRetentionPurge();
+        }, 3000);
+    }
+
     /* header is 32 bytes and is either empty
     or contains an HMAC of the message with
     a derived SK */
@@ -4219,6 +4377,7 @@ export class Client {
     private async sendGroupMessage(
         channelID: string,
         message: string,
+        opts?: { retentionHintDays?: number },
     ): Promise<void> {
         const userList = await this.getUserList(channelID);
         for (const user of userList) {
@@ -4226,28 +4385,89 @@ export class Client {
         }
 
         const mailID = uuid.v4();
+        const payload = formatVexRetentionEnvelope(
+            message,
+            opts?.retentionHintDays,
+        );
+        const msgBytes = XUtils.decodeUTF8(payload);
+        const myUserID = this.getUser().userID;
+        // Fan-out only to *other* server members. The current account's other
+        // devices receive the same group mail via `forward()` on the outgoing
+        // `message` event (see `onInternalMessage`). Including our own devices
+        // here races X3DH/ephemeral state and often fails silently — which
+        // matched reports of flaky early group messages and missing delivery
+        // while DMs (which never self-target) behaved better.
+        const peerUserIDs = [...new Set(userList.map((u) => u.userID))].filter(
+            (id) => id !== myUserID,
+        );
 
-        const userIDs = [...new Set(userList.map((user) => user.userID))];
-        const devices = await this.getMultiUserDeviceList(userIDs);
+        if (peerUserIDs.length === 0) {
+            const dev = this.getDevice();
+            const nonce = xMakeNonce();
+            this.emitter.emit("message", {
+                authorID: myUserID,
+                decrypted: true,
+                direction: "outgoing",
+                forward: false,
+                group: channelID,
+                mailID,
+                message,
+                nonce: XUtils.encodeHex(nonce),
+                readerID: myUserID,
+                recipient: dev.deviceID,
+                sender: dev.deviceID,
+                timestamp: new Date().toISOString(),
+            });
+            return;
+        }
 
-        for (const device of devices) {
+        const devices = await this.getMultiUserDeviceList(peerUserIDs);
+        if (devices.length === 0) {
+            throw new Error(
+                "No devices registered for other channel members — cannot send group message.",
+            );
+        }
+
+        const stableDevices = [...devices].sort((a, b) =>
+            a.deviceID.localeCompare(b.deviceID, "en"),
+        );
+
+        let failCount = 0;
+        let lastErr: unknown;
+        for (const device of stableDevices) {
             const ownerRecord = this.userRecords[device.owner];
             if (!ownerRecord) {
+                failCount += 1;
                 continue;
             }
             try {
                 await this.sendMail(
                     device,
                     ownerRecord,
-                    XUtils.decodeUTF8(message),
+                    msgBytes,
                     uuidToUint8(channelID),
                     mailID,
                     false,
                 );
-            } catch {
-                /* best-effort; each device needs its own X3DH handshake (sequential) */
+            } catch (e) {
+                lastErr = e;
+                failCount += 1;
             }
         }
+
+        if (failCount === stableDevices.length) {
+            throw lastErr instanceof Error
+                ? lastErr
+                : new Error(String(lastErr));
+        }
+        if (failCount > 0) {
+            const partial = new Error(
+                `Group message failed to reach ${String(failCount)} of ` +
+                    `${String(stableDevices.length)} peer device(s).`,
+            );
+            partial.cause = lastErr;
+            throw partial;
+        }
     }
 
     /* Sends encrypted mail to a user. */
@@ -4341,8 +4561,25 @@ export class Client {
             const fwdOut = forward
                 ? messageSchema.parse(msgpack.decode(msg))
                 : null;
+            const rawUtf8 = XUtils.encodeUTF8(msg);
+            const strippedOut = stripVexRetentionEnvelope(rawUtf8);
             const outMsg: Message = fwdOut
-                ? { ...fwdOut, forward: true }
+                ? (() => {
+                      const stripped = stripVexRetentionEnvelope(
+                          fwdOut.message,
+                      );
+                      const base: Message = {
+                          ...fwdOut,
+                          forward: true,
+                          message: stripped.body,
+                      };
+                      return stripped.retentionHintDays !== undefined
+                          ? {
+                                ...base,
+                                retentionHintDays: stripped.retentionHintDays,
+                            }
+                          : base;
+                  })()
                 : {
                       authorID: mail.authorID,
                       decrypted: true,
@@ -4350,10 +4587,16 @@ export class Client {
                       forward: mail.forward,
                       group: mail.group ? uuid.stringify(mail.group) : null,
                       mailID: mail.mailID,
-                      message: XUtils.encodeUTF8(msg),
+                      message: strippedOut.body,
                       nonce: XUtils.encodeHex(new Uint8Array(mail.nonce)),
                       readerID: mail.readerID,
                       recipient: mail.recipient,
+                      ...(strippedOut.retentionHintDays !== undefined
+                          ? {
+                                retentionHintDays:
+                                    strippedOut.retentionHintDays,
+                            }
+                          : {}),
                       sender: mail.sender,
                       timestamp: new Date().toISOString(),
                   };
@@ -4418,7 +4661,15 @@ export class Client {
         }
     }
 
-    private async sendMessage(userID: string, message: string): Promise<void> {
+    private async sendMessage(
+        userID: string,
+        message: string,
+        opts?: { retentionHintDays?: number },
+    ): Promise<void> {
+        const payload = formatVexRetentionEnvelope(
+            message,
+            opts?.retentionHintDays,
+        );
         try {
             const [userEntry, err] = await this.fetchUser(userID);
             if (err) {
@@ -4491,7 +4742,7 @@ export class Client {
                     await this.sendMail(
                         device,
                         userEntry,
-                        XUtils.decodeUTF8(message),
+                        XUtils.decodeUTF8(payload),
                         null,
                         messageMailID,
                         false,

package/src/Storage.ts

@@ -91,6 +91,13 @@ export interface Storage extends EventEmitter {
      * @event
      */
     on(event: "error", callback: (error: Error) => void): this;
+    /**
+     * Deletes local messages older than the effective per-row retention:
+     * `min(30 days, clientMaxRetentionDays, retentionHintDays ?? 30)`.
+     */
+    pruneExpiredLocalMessages: (
+        clientMaxRetentionDays: number,
+    ) => Promise<void>;
     /** Deletes all message history. */
     purgeHistory: () => Promise<void>;
     /** Deletes all local key/session state. */

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

@@ -170,6 +170,25 @@ export class MemoryStorage extends EventEmitter implements Storage {
         return Promise.resolve();
     }
 
+    pruneExpiredLocalMessages(clientMaxRetentionDays: number): Promise<void> {
+        const cap = Math.min(
+            30,
+            Math.max(1, Math.round(clientMaxRetentionDays)),
+        );
+        const now = Date.now();
+        const msPerDay = 86_400_000;
+        this.messages = this.messages.filter((m) => {
+            const hintDays = m.retentionHintDays ?? 30;
+            const maxDays = Math.min(30, cap, hintDays);
+            const ts = new Date(m.timestamp).getTime();
+            if (!Number.isFinite(ts)) {
+                return true;
+            }
+            return now - ts <= maxDays * msPerDay;
+        });
+        return Promise.resolve();
+    }
+
     purgeHistory(): Promise<void> {
         this.messages = [];
         return Promise.resolve();