@vex-chat/libvex 6.2.3 → 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.
@@ -2501,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 "";
@@ -3054,6 +3117,8 @@ export class Client {
         }
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     /**
      * Initializes the keyring. This must be called before anything else.
      */
@@ -3073,6 +3138,11 @@ 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");
     }
 
@@ -3284,6 +3354,7 @@ export class Client {
             return;
         }
         void this.database.saveMessage(message);
+        this.scheduleRetentionPurge();
     };
 
     private async passkeyApproveDeviceRequest(
@@ -3712,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,
@@ -3728,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,
                                   };
@@ -3900,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,
@@ -3914,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,
                                   };
@@ -4168,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
@@ -4189,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 */
@@ -4224,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) {
@@ -4231,7 +4385,11 @@ export class Client {
         }
 
         const mailID = uuid.v4();
-        const msgBytes = XUtils.decodeUTF8(message);
+        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
@@ -4403,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,
@@ -4412,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(),
                   };
@@ -4480,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) {
@@ -4553,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();

package/src/__tests__/retention.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+    clampLocalMessageRetentionDays,
+    formatVexRetentionEnvelope,
+    MAX_LOCAL_MESSAGE_RETENTION_DAYS,
+    stripVexRetentionEnvelope,
+} from "../retention.js";
+
+describe("retention", () => {
+    it("clamps local retention to 1–30", () => {
+        expect(clampLocalMessageRetentionDays(undefined)).toBe(30);
+        expect(clampLocalMessageRetentionDays(0)).toBe(1);
+        expect(clampLocalMessageRetentionDays(45)).toBe(30);
+        expect(clampLocalMessageRetentionDays(7)).toBe(7);
+    });
+
+    it("round-trips envelope prefix", () => {
+        const wrapped = formatVexRetentionEnvelope("hello", 7);
+        expect(wrapped).toBe("vex-retention:7\nhello");
+        expect(stripVexRetentionEnvelope(wrapped)).toEqual({
+            body: "hello",
+            retentionHintDays: 7,
+        });
+    });
+
+    it("format without hint leaves body unchanged", () => {
+        expect(formatVexRetentionEnvelope("plain", undefined)).toBe("plain");
+    });
+
+    it("MAX matches server contract constant name in docs", () => {
+        expect(MAX_LOCAL_MESSAGE_RETENTION_DAYS).toBe(30);
+    });
+});

package/src/index.ts

@@ -38,6 +38,10 @@ export type {
     VexFile,
 } from "./Client.js";
 export { createCodec, msgpack } from "./codec.js";
+export {
+    clampLocalMessageRetentionDays,
+    MAX_LOCAL_MESSAGE_RETENTION_DAYS,
+} from "./retention.js";
 export type { Storage } from "./Storage.js";
 export type {
     KeyPair,

package/src/retention.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+/** Matches the server-side minimum; clients cannot retain longer locally. */
+export const MAX_LOCAL_MESSAGE_RETENTION_DAYS = 30;
+
+/**
+ * Clamps a user preference to 1…{@link MAX_LOCAL_MESSAGE_RETENTION_DAYS}.
+ * Non-finite or missing values default to the maximum (keep up to the server cap).
+ */
+export function clampLocalMessageRetentionDays(
+    days: null | number | undefined,
+): number {
+    if (days === null || days === undefined) {
+        return MAX_LOCAL_MESSAGE_RETENTION_DAYS;
+    }
+    const n = Math.round(days);
+    if (!Number.isFinite(n)) {
+        return MAX_LOCAL_MESSAGE_RETENTION_DAYS;
+    }
+    return Math.min(MAX_LOCAL_MESSAGE_RETENTION_DAYS, Math.max(1, n));
+}
+
+const RETENTION_PREFIX = /^vex-retention:([1-9]|[12]\d|30)\n/;
+
+/**
+ * Prefixes plaintext with a machine-readable retention hint for other clients.
+ * When `retentionHintDays` is omitted, returns `body` unchanged.
+ */
+export function formatVexRetentionEnvelope(
+    body: string,
+    retentionHintDays?: null | number,
+): string {
+    if (
+        retentionHintDays === null ||
+        retentionHintDays === undefined ||
+        !Number.isFinite(retentionHintDays)
+    ) {
+        return body;
+    }
+    const d = clampLocalMessageRetentionDays(retentionHintDays);
+    return `vex-retention:${String(d)}\n${body}`;
+}
+
+/**
+ * Strips an optional first-line retention hint placed by cooperative clients.
+ * Malicious peers can omit or forge this; local expiry still cannot exceed 30 days.
+ */
+export function stripVexRetentionEnvelope(plaintext: string): {
+    body: string;
+    retentionHintDays?: number;
+} {
+    const m = RETENTION_PREFIX.exec(plaintext);
+    if (!m) {
+        return { body: plaintext };
+    }
+    const hint = Math.min(
+        MAX_LOCAL_MESSAGE_RETENTION_DAYS,
+        Math.max(1, Number(m[1])),
+    );
+    return {
+        body: plaintext.slice(m[0].length),
+        retentionHintDays: hint,
+    };
+}

package/src/storage/schema.ts

@@ -65,6 +65,8 @@ interface MessagesTable {
     nonce: string;
     readerID: string;
     recipient: string;
+    /** Optional peer hint (1–30 days); null when absent or legacy row. */
+    retentionHintDays: null | number;
     sender: string;
     timestamp: string;
 }