@vex-chat/libvex 6.2.2 → 6.3.0

package/src/__tests__/harness/shared-suite.ts

@@ -87,11 +87,40 @@ export function platformSuite(
                 (m) => m.direction === "incoming" && m.decrypted,
                 `[${platformName}] self-DM`,
             );
-            void client.messages.send(me.userID, "platform-test");
+            await client.messages.send(me.userID, "platform-test");
             const msg = await msgPromise;
             expect(msg.message).toBe("platform-test");
         });
 
+        test("message history retrieve + delete", async () => {
+            const me = client.me.user();
+            const body = "history-test";
+
+            // Runs early (right after first self-DM) so ratchet/session state is
+            // fresh — the same assertion was flaky late in the suite when many
+            // prior tests had exercised the client against Spire.
+            const msgPromise = waitForMessage(
+                client,
+                (m) =>
+                    m.direction === "incoming" &&
+                    m.decrypted &&
+                    m.message === body,
+                "history DM",
+                25_000,
+            );
+            await client.messages.send(me.userID, body);
+            await client.syncInboxNow();
+            const inbound = await msgPromise;
+            expect(inbound.authorID).toBe(me.userID);
+
+            const history = await client.messages.retrieve(me.userID);
+            expect(history.length).toBeGreaterThan(0);
+
+            await client.messages.delete(me.userID);
+            const afterDelete = await client.messages.retrieve(me.userID);
+            expect(afterDelete.length).toBe(0);
+        }, 35_000);
+
         test("two-user DM", async () => {
             const SK2 = await e2eGenerateSecretKey();
             const opts2: ClientOptions = e2eClientOptionsBase();
@@ -356,26 +385,6 @@ export function platformSuite(
             }
         });
 
-        test("message history retrieve + delete", async () => {
-            const me = client.me.user();
-
-            // Send a message and wait for it
-            const msgPromise = waitForMessage(
-                client,
-                (m) => m.direction === "incoming" && m.decrypted,
-                "history DM",
-            );
-            void client.messages.send(me.userID, "history-test");
-            await msgPromise;
-
-            const history = await client.messages.retrieve(me.userID);
-            expect(history.length).toBeGreaterThan(0);
-
-            await client.messages.delete(me.userID);
-            const afterDelete = await client.messages.retrieve(me.userID);
-            expect(afterDelete.length).toBe(0);
-        });
-
         test("file upload + download", async () => {
             const [details, key] = await client.files.create(testFile);
             expect(details.fileID).toBeTruthy();

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;
 }

package/src/storage/sqlite.ts

@@ -349,6 +349,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     )
                     .execute();
                 await this.ensureSessionRatchetColumns();
+                await this.ensureRetentionHintColumn();
 
                 await this.db.schema
                     .createTable("preKeys")
@@ -416,6 +417,46 @@ export class SqliteStorage extends EventEmitter implements Storage {
 
     // ── PreKeys / OneTimeKeys ────────────────────────────────────────────────
 
+    async pruneExpiredLocalMessages(
+        clientMaxRetentionDays: number,
+    ): Promise<void> {
+        await this.untilReady();
+        if (this.closing) {
+            return;
+        }
+        const cap = Math.min(
+            30,
+            Math.max(1, Math.round(clientMaxRetentionDays)),
+        );
+        const rows = await this.db
+            .selectFrom("messages")
+            .select(["mailID", "timestamp", "retentionHintDays"])
+            .execute();
+        const now = Date.now();
+        const msPerDay = 86_400_000;
+        const toDelete: string[] = [];
+        for (const r of rows) {
+            const hintDays = r.retentionHintDays ?? 30;
+            const maxDays = Math.min(30, cap, hintDays);
+            const ts = new Date(r.timestamp).getTime();
+            if (!Number.isFinite(ts)) {
+                continue;
+            }
+            if (now - ts > maxDays * msPerDay) {
+                toDelete.push(r.mailID);
+            }
+        }
+        if (toDelete.length === 0) {
+            return;
+        }
+        for (const mailID of toDelete) {
+            await this.db
+                .deleteFrom("messages")
+                .where("mailID", "=", mailID)
+                .execute();
+        }
+    }
+
     async purgeHistory(): Promise<void> {
         await this.db.deleteFrom("messages").execute();
     }
@@ -489,6 +530,16 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     nonce: message.nonce,
                     readerID: message.readerID,
                     recipient: message.recipient,
+                    retentionHintDays:
+                        message.retentionHintDays === undefined
+                            ? null
+                            : Math.min(
+                                  30,
+                                  Math.max(
+                                      1,
+                                      Math.round(message.retentionHintDays),
+                                  ),
+                              ),
                     sender: message.sender,
                     timestamp: message.timestamp,
                 })
@@ -638,7 +689,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
             }
             const direction =
                 msg.direction === "incoming" ? "incoming" : "outgoing";
-            out.push({
+            const rowMessage: Message = {
                 authorID: msg.authorID,
                 decrypted: decryptedFlag,
                 direction,
@@ -651,7 +702,11 @@ export class SqliteStorage extends EventEmitter implements Storage {
                 recipient: msg.recipient,
                 sender: msg.sender,
                 timestamp: msg.timestamp,
-            });
+            };
+            if (msg.retentionHintDays != null) {
+                rowMessage.retentionHintDays = msg.retentionHintDays;
+            }
+            out.push(rowMessage);
         }
         return out;
     }
@@ -669,6 +724,18 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
+    private async ensureRetentionHintColumn(): Promise<void> {
+        try {
+            await sql
+                .raw(
+                    "ALTER TABLE messages ADD COLUMN retentionHintDays integer",
+                )
+                .execute(this.db);
+        } catch {
+            // Existing databases may already have this column.
+        }
+    }
+
     private async ensureSessionRatchetColumns(): Promise<void> {
         const add = async (
             column: string,