@vex-chat/libvex 6.2.3 → 6.3.1

package/src/Client.ts

@@ -42,7 +42,9 @@ import type { AxiosInstance } from "axios";
 
 import {
     type CryptoProfile,
+    enterCryptoProfileScope,
     getCryptoProfile,
+    leaveCryptoProfileScope,
     setCryptoProfile,
     xBoxKeyPairAsync,
     xBoxKeyPairFromSecretAsync,
@@ -78,6 +80,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 +370,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. */
@@ -375,6 +389,14 @@ export type DeviceRegistrationResult = Device | PendingDeviceRegistration;
  * @ignore
  */
 export interface Devices {
+    /**
+     * Deletes an unpublished enrollment before any owner notification
+     * (e.g. user picked "not my account").
+     */
+    abortPendingRegistration: (args: {
+        challenge: string;
+        requestID: string;
+    }) => Promise<void>;
     /** Approves a pending device registration request as the current device. */
     approveRequest: (requestID: string) => Promise<Device>;
     /** Deletes one of the account's devices (except the currently active one). */
@@ -402,6 +424,14 @@ export interface Devices {
         challenge: string;
         requestID: string;
     }) => Promise<null | PendingDeviceRequest>;
+    /**
+     * After the user confirms the pending enrollment is theirs, notifies
+     * their existing devices (same proof as poll).
+     */
+    publishPendingRegistration: (args: {
+        challenge: string;
+        requestID: string;
+    }) => Promise<void>;
     /** Registers the current key material as a new device. */
     register: () => Promise<DeviceRegistrationResult | null>;
     /** Rejects a pending device registration request as the current device. */
@@ -552,6 +582,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 +776,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 +788,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>;
 }
 
 /**
@@ -977,12 +1021,16 @@ export class Client {
      * Device management methods.
      */
     public devices: Devices = {
+        abortPendingRegistration:
+            this.abortPendingDeviceRegistration.bind(this),
         approveRequest: this.approveDeviceRequest.bind(this),
         delete: this.deleteDevice.bind(this),
         getRequest: this.getDeviceRegistrationRequest.bind(this),
         list: this.listDevices.bind(this),
         listRequests: this.listDeviceRegistrationRequests.bind(this),
         pollPendingRegistration: this.pollPendingDeviceRegistration.bind(this),
+        publishPendingRegistration:
+            this.publishPendingDeviceRegistration.bind(this),
         register: this.registerDevice.bind(this),
         rejectRequest: this.rejectDeviceRequest.bind(this),
         retrieve: this.getDeviceByID.bind(this),
@@ -1072,7 +1120,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 +1145,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 +1306,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 +1326,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 +1364,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 +1664,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 +1751,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 +2096,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 +2146,23 @@ export class Client {
         return whoami;
     }
 
+    private async abortPendingDeviceRegistration(args: {
+        challenge: string;
+        requestID: string;
+    }): Promise<void> {
+        const signed = await this.signPendingRegistrationChallenge(
+            args.challenge,
+        );
+        await this.http.post(
+            this.getHost() +
+                "/user/devices/requests/" +
+                args.requestID +
+                "/abort",
+            msgpack.encode({ signed }),
+            { headers: { "Content-Type": "application/msgpack" } },
+        );
+    }
+
     private acknowledgeInboundMail(mail: MailWS): void {
         this.seenMailIDs.add(mail.mailID);
         this.sendReceipt(new Uint8Array(mail.nonce));
@@ -2497,11 +2600,9 @@ export class Client {
     private async deletePermission(permissionID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/permission/" + permissionID);
     }
-
     private async deleteServer(serverID: string): Promise<void> {
         await this.http.delete(this.getHost() + "/server/" + serverID);
     }
-
     private deviceListFailureDetail(err: unknown): string {
         if (!isAxiosError(err)) {
             return "";
@@ -2515,6 +2616,7 @@ export class Client {
         }
         return "";
     }
+
     /**
      * Gets a list of permissions for a server.
      *
@@ -3015,6 +3117,8 @@ export class Client {
         return decodeAxios(UserArrayCodec, res.data);
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     private async handleNotify(msg: NotifyMsg) {
         switch (msg.event) {
             case "deviceRequest": {
@@ -3054,6 +3158,8 @@ export class Client {
         }
     }
 
+    // ── Passkeys ────────────────────────────────────────────────────────
+
     /**
      * Initializes the keyring. This must be called before anything else.
      */
@@ -3073,11 +3179,14 @@ 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) {
@@ -3284,6 +3393,7 @@ export class Client {
             return;
         }
         void this.database.saveMessage(message);
+        this.scheduleRetentionPurge();
     };
 
     private async passkeyApproveDeviceRequest(
@@ -3360,21 +3470,12 @@ export class Client {
         );
     }
 
-    /**
-     * Polls the public unauthenticated request status endpoint as the
-     * requesting device. Signs the server-issued challenge with the local
-     * private signing key so the server can verify ownership of the pending
-     * request without us needing a user token.
-     */
     private async pollPendingDeviceRegistration(args: {
         challenge: string;
         requestID: string;
     }): Promise<null | PendingDeviceRequest> {
-        const signed = XUtils.encodeHex(
-            await xSignAsync(
-                XUtils.decodeHex(args.challenge),
-                this.signKeys.secretKey,
-            ),
+        const signed = await this.signPendingRegistrationChallenge(
+            args.challenge,
         );
         try {
             const response = await this.http.post(
@@ -3484,6 +3585,23 @@ export class Client {
         }
     }
 
+    private async publishPendingDeviceRegistration(args: {
+        challenge: string;
+        requestID: string;
+    }): Promise<void> {
+        const signed = await this.signPendingRegistrationChallenge(
+            args.challenge,
+        );
+        await this.http.post(
+            this.getHost() +
+                "/user/devices/requests/" +
+                args.requestID +
+                "/publish",
+            msgpack.encode({ signed }),
+            { headers: { "Content-Type": "application/msgpack" } },
+        );
+    }
+
     private async purgeHistory(): Promise<void> {
         await this.database.purgeHistory();
     }
@@ -3712,13 +3830,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 +3872,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 +4050,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 +4088,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 +4345,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
@@ -4177,18 +4367,24 @@ export class Client {
     private async runWithThisCryptoProfile<T>(
         fn: () => Promise<T>,
     ): Promise<T> {
-        const prev = getCryptoProfile();
-        if (prev === this.cryptoProfile) {
-            return await fn();
-        }
-        setCryptoProfile(this.cryptoProfile);
+        enterCryptoProfileScope(this.cryptoProfile);
         try {
             return await fn();
         } finally {
-            setCryptoProfile(prev);
+            leaveCryptoProfileScope();
         }
     }
 
+    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 +4420,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 +4428,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 +4604,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 +4630,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 +4704,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 +4785,7 @@ export class Client {
                     await this.sendMail(
                         device,
                         userEntry,
-                        XUtils.decodeUTF8(message),
+                        XUtils.decodeUTF8(payload),
                         null,
                         messageMailID,
                         false,
@@ -4616,6 +4848,26 @@ export class Client {
 
     private setUser(user: User): void {
         this.user = user;
+        // Fresh identity / token: drop stale 404 negative-cache entries so a
+        // prior transient miss (or wrong host) cannot block DM sends for 30m.
+        this.notFoundUsers.clear();
+    }
+
+    /**
+     * Polls the public unauthenticated request status endpoint as the
+     * requesting device. Signs the server-issued challenge with the local
+     * private signing key so the server can verify ownership of the pending
+     * request without us needing a user token.
+     */
+    private async signPendingRegistrationChallenge(
+        challengeHex: string,
+    ): Promise<string> {
+        return XUtils.encodeHex(
+            await xSignAsync(
+                XUtils.decodeHex(challengeHex),
+                this.signKeys.secretKey,
+            ),
+        );
     }
 
     private async submitOTK(amount: number) {

package/src/Storage.ts

@@ -91,6 +91,14 @@ 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, effectiveMessageRetentionHintDays(row))`
+     * (invalid or non-positive stored hints are treated like 30).
+     */
+    pruneExpiredLocalMessages: (
+        clientMaxRetentionDays: number,
+    ) => Promise<void>;
     /** Deletes all message history. */
     purgeHistory: () => Promise<void>;
     /** Deletes all local key/session state. */