@vex-chat/libvex 6.2.3 → 6.3.1

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

@@ -24,13 +24,16 @@ import {
     XUtils,
 } from "@vex-chat/crypto";
 
+import { EventEmitter } from "eventemitter3";
+
+import { effectiveMessageRetentionHintDays } from "../../retention.js";
+
 /**
  * Minimal in-memory Storage for browser/RN platform tests.
  *
  * Uses eventemitter3 (browser-safe) instead of Node's events module.
  * No persistence — just enough for the register/login/connect/DM test flow.
  */
-import { EventEmitter } from "eventemitter3";
 
 export class MemoryStorage extends EventEmitter implements Storage {
     public ready = false;
@@ -170,6 +173,27 @@ 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 = effectiveMessageRetentionHintDays(
+                m.retentionHintDays,
+            );
+            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,50 @@
+/**
+ * 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,
+    effectiveMessageRetentionHintDays,
+    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);
+    });
+
+    it("effectiveMessageRetentionHintDays treats 0 and invalid as 30-day default", () => {
+        expect(effectiveMessageRetentionHintDays(undefined)).toBe(30);
+        expect(effectiveMessageRetentionHintDays(null)).toBe(30);
+        expect(effectiveMessageRetentionHintDays(0)).toBe(30);
+        expect(effectiveMessageRetentionHintDays(-3)).toBe(30);
+        expect(effectiveMessageRetentionHintDays(Number.NaN)).toBe(30);
+        expect(effectiveMessageRetentionHintDays(7)).toBe(7);
+        expect(effectiveMessageRetentionHintDays(45)).toBe(30);
+    });
+});

package/src/index.ts

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

package/src/retention.ts

@@ -0,0 +1,85 @@
+/**
+ * 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));
+}
+
+/**
+ * Normalizes a per-message `retentionHintDays` value read from storage.
+ * Non-finite, missing, or non-positive values behave like "no hint" (30 days)
+ * so a corrupt `0` row cannot wipe the entire local history on prune.
+ */
+export function effectiveMessageRetentionHintDays(
+    stored: null | number | undefined,
+): number {
+    if (stored == null || !Number.isFinite(stored) || stored < 1) {
+        return MAX_LOCAL_MESSAGE_RETENTION_DAYS;
+    }
+    return Math.min(
+        MAX_LOCAL_MESSAGE_RETENTION_DAYS,
+        Math.max(1, Math.round(stored)),
+    );
+}
+
+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

@@ -28,6 +28,13 @@ import type { Device, PreKeysSQL, SessionSQL } from "@vex-chat/types";
  *
  * This replaces three separate storage classes (Storage.ts, TauriStorage,
  * ExpoStorage) with a single implementation.
+ *
+ * **One database file today** holds both `sessions` (Double Ratchet /
+ * X3DH state — required to decrypt *new* traffic) and `messages` (history).
+ * If the file is lost or corrupted you lose both; restoring from backup
+ * re-seeds device keys but cannot reconstruct dropped ratchet chains from
+ * the server alone. A future split could park `sessions` + OTKs in a
+ * smaller “crypto state” store separate from bulk message history.
  */
 import {
     getCryptoProfile,
@@ -44,6 +51,7 @@ import {
 import { EventEmitter } from "eventemitter3";
 import { type Kysely, sql } from "kysely";
 
+import { effectiveMessageRetentionHintDays } from "../retention.js";
 import { parseSkippedKeysStrict } from "../utils/ratchet.js";
 
 export class SqliteStorage extends EventEmitter implements Storage {
@@ -349,6 +357,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     )
                     .execute();
                 await this.ensureSessionRatchetColumns();
+                await this.ensureRetentionHintColumn();
 
                 await this.db.schema
                     .createTable("preKeys")
@@ -416,6 +425,48 @@ 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 = effectiveMessageRetentionHintDays(
+                r.retentionHintDays,
+            );
+            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 +540,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,
                 })
@@ -617,6 +678,14 @@ export class SqliteStorage extends EventEmitter implements Storage {
     ): Promise<Message[]> {
         const fips = getCryptoProfile() === "fips";
         const out: Message[] = [];
+        let processed = 0;
+        /** Yield so RN / web UIs can paint between at-rest decrypt blocks. */
+        const yieldToHost = (): Promise<void> =>
+            new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+        const yieldEvery = 28;
+
         for (const msg of messages) {
             const decryptedFlag = msg.decrypted !== 0;
             let plaintext = msg.message;
@@ -638,7 +707,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 +720,16 @@ 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);
+
+            processed += 1;
+            if (processed % yieldEvery === 0) {
+                await yieldToHost();
+            }
         }
         return out;
     }
@@ -669,6 +747,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,