@vex-chat/libvex 1.1.0 → 4.0.0

package/{dist/IStorage.d.ts → src/Storage.ts}

@@ -1,6 +1,11 @@
-import type { IDevice, IPreKeysCrypto, IPreKeysSQL, ISessionCrypto } from "@vex-chat/types";
-import { EventEmitter } from "eventemitter3";
-import type { IMessage, ISession } from "./index.js";
+import type { Message, Session } from "./index.js";
+import type {
+    PreKeysCrypto,
+    SessionCrypto,
+    UnsavedPreKey,
+} from "./types/index.js";
+import type { Device, PreKeysSQL } from "@vex-chat/types";
+import type { EventEmitter } from "eventemitter3";
 /**
  * Storage contract used by `Client` for local persistence.
  *
@@ -13,33 +18,25 @@ import type { IMessage, ISession } from "./index.js";
  * - Managing prekeys / one-time keys used for session setup
  * - Emitting lifecycle events (`ready`, `error`)
  */
-export interface IStorage extends EventEmitter {
-    /**
-     * Set this to "true" when init has complete.
-     */
-    ready: boolean;
+export interface Storage extends EventEmitter {
     /** Closes storage resources (connections, handles, transactions, etc.). */
     close: () => Promise<void>;
     /**
-     * Persists one chat message.
+     * Deletes history for a direct conversation or group channel.
      *
-     * @example
-     * ```ts
-     * await storage.saveMessage(message);
-     * ```
+     * @param channelOrUserID - Channel ID or user ID whose history should be deleted.
      */
-    saveMessage: (message: IMessage) => Promise<void>;
+    deleteHistory: (channelOrUserID: string) => Promise<void>;
     /** Deletes one message by `mailID`. */
     deleteMessage: (mailID: string) => Promise<void>;
-    /**
-     * Marks an encryption session as verified.
-     *
-     * This usually means the user has compared safety words / fingerprint out
-     * of band and confirmed the session.
-     */
-    markSessionVerified: (sessionID: string) => Promise<void>;
-    /** Updates a session's `lastUsed` timestamp to "now". */
-    markSessionUsed: (sessionID: string) => Promise<void>;
+    /** Deletes one one-time key by index. */
+    deleteOneTimeKey: (index: number) => Promise<void>;
+    /** Returns all known encryption sessions. */
+    getAllSessions: () => Promise<Session[]>;
+    /** Gets one device record by ID. */
+    getDevice: (deviceID: string) => Promise<Device | null>;
+    /** Returns group-message history for a channel. */
+    getGroupHistory: (channelID: string) => Promise<Message[]>;
     /**
      * Returns direct-message history for a user.
      *
@@ -48,55 +45,34 @@ export interface IStorage extends EventEmitter {
      * const history = await storage.getMessageHistory(userID);
      * ```
      */
-    getMessageHistory: (userID: string) => Promise<IMessage[]>;
-    /** Returns group-message history for a channel. */
-    getGroupHistory: (channelID: string) => Promise<IMessage[]>;
-    /**
-     * Deletes history for a direct conversation or group channel.
-     *
-     * If `olderThan` is omitted, the full history for that thread is removed.
-     *
-     * @param channelOrUserID Channel ID or user ID whose history should be deleted.
-     * @param olderThan Relative duration such as `1h`, `7d`, or `30m`.
-     */
-    deleteHistory: (channelOrUserID: string, olderThan?: string) => Promise<void>;
-    /** Deletes all message history. */
-    purgeHistory: () => Promise<void>;
-    /** Deletes all local key/session state. */
-    purgeKeyData: () => Promise<void>;
-    /**
-     * Saves signed prekeys.
-     *
-     * @param preKeys Prekeys to persist.
-     * @param oneTime `true` for one-time keys, `false` for the long-lived signed prekey.
-     */
-    savePreKeys: (preKeys: IPreKeysCrypto[], oneTime: boolean) => Promise<IPreKeysSQL[]>;
+    getMessageHistory: (userID: string) => Promise<Message[]>;
+    /** Fetches one one-time key by index. */
+    getOneTimeKey: (index: number) => Promise<null | PreKeysCrypto>;
     /**
      * Returns the local signed prekey pair, or `null` when it has not been created yet.
      */
-    getPreKeys: () => Promise<IPreKeysCrypto | null>;
-    /** Fetches one one-time key by index. */
-    getOneTimeKey: (index: number) => Promise<IPreKeysCrypto | null>;
-    /** Deletes one one-time key by index. */
-    deleteOneTimeKey: (index: number) => Promise<void>;
-    /** Fetches an encryption session using the session public key bytes. */
-    getSessionByPublicKey: (publicKey: Uint8Array) => Promise<ISessionCrypto | null>;
-    /** Returns all known encryption sessions. */
-    getAllSessions: () => Promise<ISession[]>;
+    getPreKeys: () => Promise<null | PreKeysCrypto>;
     /** Returns the active session for a device ID (typically the most recently used). */
-    getSessionByDeviceID: (deviceID: string) => Promise<ISessionCrypto | null>;
-    /** Persists an encryption session. */
-    saveSession: (session: ISession) => Promise<void>;
+    getSessionByDeviceID: (deviceID: string) => Promise<null | SessionCrypto>;
+    /** Fetches an encryption session using the session public key bytes. */
+    getSessionByPublicKey: (
+        publicKey: Uint8Array,
+    ) => Promise<null | SessionCrypto>;
     /**
      * Performs storage initialization (schema creation, migrations, warmup, etc.).
      *
      * Implementations should set `ready = true` and emit `ready` after completion.
      */
     init: () => Promise<void>;
-    /** Gets one device record by ID. */
-    getDevice: (deviceID: string) => Promise<IDevice | null>;
-    /** Saves a device record. */
-    saveDevice: (device: IDevice) => Promise<void>;
+    /** Updates a session's `lastUsed` timestamp to "now". */
+    markSessionUsed: (sessionID: string) => Promise<void>;
+    /**
+     * Marks an encryption session as verified.
+     *
+     * This usually means the user has compared safety words / fingerprint out
+     * of band and confirmed the session.
+     */
+    markSessionVerified: (sessionID: string) => Promise<void>;
     /**
      * Emit this event when init has complete.
      *
@@ -109,4 +85,36 @@ export interface IStorage extends EventEmitter {
      * @event
      */
     on(event: "error", callback: (error: Error) => void): this;
+    /** Deletes all message history. */
+    purgeHistory: () => Promise<void>;
+    /** Deletes all local key/session state. */
+    purgeKeyData: () => Promise<void>;
+    /**
+     * Set this to "true" when init has complete.
+     */
+    ready: boolean;
+    /** Saves a device record. */
+    saveDevice: (device: Device) => Promise<void>;
+    /**
+     * Persists one chat message.
+     *
+     * @example
+     * ```ts
+     * await storage.saveMessage(message);
+     * ```
+     */
+    saveMessage: (message: Message) => Promise<void>;
+
+    /**
+     * Saves signed prekeys.
+     *
+     * @param preKeys - Prekeys to persist.
+     * @param oneTime - `true` for one-time keys, `false` for the long-lived signed prekey.
+     */
+    savePreKeys: (
+        preKeys: UnsavedPreKey[],
+        oneTime: boolean,
+    ) => Promise<PreKeysSQL[]>;
+    /** Persists an encryption session. */
+    saveSession: (session: Session) => Promise<void>;
 }

package/src/__tests__/codec.test.ts

@@ -0,0 +1,256 @@
+import fc from "fast-check";
+/**
+ * Property-based round-trip tests for msgpack codec.
+ *
+ * Generates random valid messages matching our wire types and verifies
+ * they survive encode → decode through msgpack without data loss.
+ *
+ * Only uses msgpack-safe types: strings, numbers, booleans, null,
+ * Uint8Array, arrays, plain objects. No Date, undefined, Map, Set.
+ */
+import { describe, expect, it } from "vitest";
+
+import { msgpack } from "../codec.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const hex = (len: number) =>
+    fc.stringMatching(new RegExp(`^[0-9a-f]{${String(len)}}$`));
+const hexVar = (min: number, max: number) =>
+    fc.stringMatching(new RegExp(`^[0-9a-f]{${String(min)},${String(max)}}$`));
+const rec = (arbs: Record<string, fc.Arbitrary<unknown>>) =>
+    fc.record(arbs, { noNullPrototype: true });
+
+/**
+ * Strip keys that are magic in JS (`__proto__`, `constructor`, `prototype`)
+ * from generated JSON values. These can't round-trip through msgpack because
+ * the JS runtime intercepts them on plain objects.
+ */
+function stripProtoKeys(val: unknown): unknown {
+    if (val === null || typeof val !== "object") return val;
+    if (Array.isArray(val)) return val.map(stripProtoKeys);
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(val)) {
+        if (k === "__proto__" || k === "constructor" || k === "prototype")
+            continue;
+        out[k] = stripProtoKeys(v);
+    }
+    return out;
+}
+
+const safeJsonValue = (opts?: { maxDepth?: number }) =>
+    fc
+        .jsonValue(opts)
+        .map((v) => stripProtoKeys(JSON.parse(JSON.stringify(v))));
+
+// ── Arbitraries ──────────────────────────────────────────────────────────────
+
+const arbBaseMsg = rec({
+    transmissionID: fc.uuid({ version: 4 }),
+    type: fc.string({ maxLength: 32, minLength: 1 }),
+});
+
+const arbSuccessMsg = rec({
+    data: safeJsonValue({ maxDepth: 1 }),
+    timestamp: fc.option(fc.string(), { nil: null }),
+    transmissionID: fc.uuid({ version: 4 }),
+    type: fc.constant("success"),
+});
+
+const arbErrMsg = rec({
+    data: fc.option(safeJsonValue({ maxDepth: 1 }), { nil: null }),
+    error: fc.string({ minLength: 1 }),
+    transmissionID: fc.uuid({ version: 4 }),
+    type: fc.constant("error"),
+});
+
+const arbResourceMsg = rec({
+    action: fc.constantFrom("CREATE", "RETRIEVE", "UPDATE", "DELETE"),
+    data: fc.option(safeJsonValue({ maxDepth: 1 }), { nil: null }),
+    resourceType: fc.constantFrom("mail", "preKeys", "otk"),
+    transmissionID: fc.uuid({ version: 4 }),
+    type: fc.constant("resource"),
+});
+
+const arbNotifyMsg = rec({
+    data: fc.option(safeJsonValue({ maxDepth: 1 }), { nil: null }),
+    event: fc.constantFrom("mail", "serverChange", "permission"),
+    transmissionID: fc.uuid({ version: 4 }),
+    type: fc.constant("notify"),
+});
+
+const arbMailSQL = rec({
+    authorID: fc.uuid({ version: 4 }),
+    cipher: hexVar(2, 64),
+    extra: hexVar(2, 64),
+    forward: fc.boolean(),
+    group: fc.option(fc.uuid({ version: 4 }), { nil: null }),
+    header: hex(64),
+    mailID: fc.uuid({ version: 4 }),
+    mailType: fc.constantFrom(0, 1),
+    nonce: hex(48),
+    readerID: fc.uuid({ version: 4 }),
+    recipient: fc.uuid({ version: 4 }),
+    sender: fc.uuid({ version: 4 }),
+    time: fc.string({ maxLength: 30, minLength: 10 }),
+});
+
+const arbServer = rec({
+    icon: fc.option(fc.uuid({ version: 4 }), { nil: null }),
+    name: fc.string({ maxLength: 64, minLength: 1 }),
+    serverID: fc.uuid({ version: 4 }),
+});
+
+const arbChannel = rec({
+    channelID: fc.uuid({ version: 4 }),
+    name: fc.string({ maxLength: 64, minLength: 1 }),
+    serverID: fc.uuid({ version: 4 }),
+});
+
+const arbPermission = rec({
+    permissionID: fc.uuid({ version: 4 }),
+    powerLevel: fc.integer({ max: 100, min: 0 }),
+    resourceID: fc.uuid({ version: 4 }),
+    resourceType: fc.constant("server"),
+    userID: fc.uuid({ version: 4 }),
+});
+
+const arbDevice = rec({
+    deleted: fc.boolean(),
+    deviceID: fc.uuid({ version: 4 }),
+    lastLogin: fc.string({ maxLength: 30, minLength: 10 }),
+    name: fc.string({ maxLength: 32, minLength: 1 }),
+    owner: fc.uuid({ version: 4 }),
+    signKey: hex(64),
+});
+
+const arbMailWS = rec({
+    authorID: fc.uuid({ version: 4 }),
+    cipher: fc.uint8Array({ maxLength: 128, minLength: 1 }),
+    extra: fc.uint8Array({ maxLength: 64 }),
+    forward: fc.boolean(),
+    group: fc.option(fc.uint8Array({ maxLength: 16, minLength: 16 }), {
+        nil: null,
+    }),
+    mailID: fc.uuid({ version: 4 }),
+    mailType: fc.constantFrom(0, 1),
+    nonce: fc.uint8Array({ maxLength: 24, minLength: 24 }),
+    readerID: fc.uuid({ version: 4 }),
+    recipient: fc.uuid({ version: 4 }),
+    sender: fc.uuid({ version: 4 }),
+});
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("msgpack round-trip", () => {
+    const opts = { numRuns: 200 };
+
+    it("baseMsg", () => {
+        fc.assert(
+            fc.property(arbBaseMsg, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("successMsg", () => {
+        fc.assert(
+            fc.property(arbSuccessMsg, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("errMsg", () => {
+        fc.assert(
+            fc.property(arbErrMsg, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("resourceMsg", () => {
+        fc.assert(
+            fc.property(arbResourceMsg, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("notifyMsg", () => {
+        fc.assert(
+            fc.property(arbNotifyMsg, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("mailSQL (string fields)", () => {
+        fc.assert(
+            fc.property(arbMailSQL, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("mailWS (binary fields)", () => {
+        fc.assert(
+            fc.property(arbMailWS, (msg) => {
+                const decoded = msgpack.decode(msgpack.encode(msg));
+                // Uint8Array round-trips through msgpack as Buffer — compare contents
+                for (const key of Object.keys(msg) as (keyof typeof msg)[]) {
+                    const orig = msg[key];
+                    const dec = (decoded as Record<string, unknown>)[key];
+                    const actual =
+                        orig instanceof Uint8Array
+                            ? new Uint8Array(dec as ArrayBuffer)
+                            : dec;
+                    expect(actual).toEqual(orig);
+                }
+            }),
+            opts,
+        );
+    });
+
+    it("server", () => {
+        fc.assert(
+            fc.property(arbServer, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("channel", () => {
+        fc.assert(
+            fc.property(arbChannel, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("permission", () => {
+        fc.assert(
+            fc.property(arbPermission, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+
+    it("device", () => {
+        fc.assert(
+            fc.property(arbDevice, (msg) => {
+                expect(msgpack.decode(msgpack.encode(msg))).toEqual(msg);
+            }),
+            opts,
+        );
+    });
+});

package/src/__tests__/harness/fixtures.ts

@@ -0,0 +1,22 @@
+/**
+ * Inline test fixtures — no fs needed, works on all platforms.
+ */
+
+// Minimal valid 1x1 transparent PNG (67 bytes)
+const TINY_PNG_B64 =
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVQI12NgAAIABQABNjN9GQAAAABJRU5ErkJggg==";
+
+function base64ToUint8Array(b64: string): Uint8Array {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+
+/** Valid 1x1 PNG — passes MIME type checks for avatar/emoji endpoints. */
+export const testImage = base64ToUint8Array(TINY_PNG_B64);
+
+/** Arbitrary binary data for file upload tests. */
+export const testFile = new Uint8Array(1000).fill(42);