@vex-chat/libvex 1.1.0 → 2.0.0

package/src/codecs.ts

@@ -0,0 +1,101 @@
+/**
+ * Pre-built codec instances for every HTTP response type.
+ *
+ * Usage: import { UserCodec } from "./codecs.js";
+ *        const data = decodeAxios(UserCodec, res.data);
+ *
+ * decode() returns typed data without runtime validation (SDK trusts server).
+ * For trust boundary validation, use codec.decodeSafe() directly.
+ */
+import {
+    ActionTokenSchema,
+    ChannelSchema,
+    DeviceSchema,
+    EmojiSchema,
+    FileSQLSchema,
+    InviteSchema,
+    KeyBundleSchema,
+    PermissionSchema,
+    ServerSchema,
+    UserSchema,
+} from "@vex-chat/types";
+
+import { z } from "zod/v4";
+
+import { createCodec } from "./codec.js";
+
+// ── Named schema codecs ─────────────────────────────────────────────────────
+
+export const UserCodec = createCodec(UserSchema);
+export const DeviceCodec = createCodec(DeviceSchema);
+export const ServerCodec = createCodec(ServerSchema);
+export const ChannelCodec = createCodec(ChannelSchema);
+export const PermissionCodec = createCodec(PermissionSchema);
+export const InviteCodec = createCodec(InviteSchema);
+export const EmojiCodec = createCodec(EmojiSchema);
+export const FileSQLCodec = createCodec(FileSQLSchema);
+export const ActionTokenCodec = createCodec(ActionTokenSchema);
+export const KeyBundleCodec = createCodec(KeyBundleSchema);
+
+// ── Array codecs ────────────────────────────────────────────────────────────
+
+export const UserArrayCodec = createCodec(z.array(UserSchema));
+export const DeviceArrayCodec = createCodec(z.array(DeviceSchema));
+export const ServerArrayCodec = createCodec(z.array(ServerSchema));
+export const ChannelArrayCodec = createCodec(z.array(ChannelSchema));
+export const PermissionArrayCodec = createCodec(z.array(PermissionSchema));
+export const InviteArrayCodec = createCodec(z.array(InviteSchema));
+export const EmojiArrayCodec = createCodec(z.array(EmojiSchema));
+
+// ── Inline ad-hoc response codecs ───────────────────────────────────────────
+
+export const ConnectResponseCodec = createCodec(
+    z.object({ deviceToken: z.string() }),
+);
+
+export const AuthResponseCodec = createCodec(
+    z.object({
+        token: z.string(),
+        user: UserSchema,
+    }),
+);
+
+export const DeviceChallengeCodec = createCodec(
+    z.object({
+        challenge: z.string(),
+        challengeID: z.string(),
+    }),
+);
+
+export const WhoamiCodec = createCodec(
+    z.object({
+        exp: z.number(),
+        token: z.string(),
+        user: UserSchema,
+    }),
+);
+
+export const OtkCountCodec = createCodec(z.object({ count: z.number() }));
+
+// ── Helper: decode axios response buffer ────────────────────────────────────
+
+/**
+ * Decode an axios arraybuffer response with a typed codec.
+ * Uses decodeSafe (Zod-validated) so schema mismatches surface immediately.
+ */
+export function decodeAxios<T>(
+    codec: { decodeSafe: (data: Uint8Array) => T },
+    /**
+     * Accepts `unknown` because axios types its `responseType: 'arraybuffer'`
+     * responses as `any`. At runtime this is always an `ArrayBuffer`.
+     */
+    data: unknown,
+): T {
+    if (data instanceof Uint8Array) {
+        return codec.decodeSafe(data);
+    }
+    if (data instanceof ArrayBuffer) {
+        return codec.decodeSafe(new Uint8Array(data));
+    }
+    throw new Error("Expected Uint8Array or ArrayBuffer from axios response");
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { Client } from "./Client.js";
+export type {
+    Channel,
+    Channels,
+    ClientOptions,
+    Device,
+    Devices,
+    Emojis,
+    FileProgress,
+    FileRes,
+    Files,
+    Invites,
+    Keys,
+    Me,
+    Message,
+    Messages,
+    Moderation,
+    Permission,
+    Permissions,
+    Server,
+    Servers,
+    Session,
+    Sessions,
+    User,
+    Users,
+    VexFile,
+} from "./Client.js";
+export { createCodec, msgpack } from "./codec.js";
+export type { Storage } from "./Storage.js";
+export type { Logger } from "./transport/types.js";
+export type { KeyStore, StoredCredentials } from "./types/index.js";
+// Re-export app-facing types
+export type { Invite } from "@vex-chat/types";

package/src/keystore/memory.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory KeyStore for testing and ephemeral sessions.
+ * No persistence — credentials are lost when the process exits.
+ */
+import type { KeyStore, StoredCredentials } from "../types/index.js";
+
+export class MemoryKeyStore implements KeyStore {
+    private readonly store = new Map<string, StoredCredentials>();
+
+    clear(username: string): Promise<void> {
+        this.store.delete(username);
+        return Promise.resolve();
+    }
+
+    load(username?: string): Promise<null | StoredCredentials> {
+        if (username) {
+            return Promise.resolve(this.store.get(username) ?? null);
+        }
+        // Return the most recently saved credentials
+        const entries = [...this.store.values()];
+        return Promise.resolve(
+            entries.length > 0 ? (entries[entries.length - 1] ?? null) : null,
+        );
+    }
+
+    save(creds: StoredCredentials): Promise<void> {
+        this.store.set(creds.username, creds);
+        return Promise.resolve();
+    }
+}

package/src/keystore/node.ts

@@ -0,0 +1,91 @@
+import type { KeyStore, StoredCredentials } from "../types/index.js";
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * File-backed KeyStore for Node.js (CLI tools, bots, integration tests).
+ *
+ * Stores credentials as encrypted files on disk using XUtils.encryptKeyData.
+ * Node-only — imports node:fs.
+ */
+import { XUtils } from "@vex-chat/crypto";
+
+export class NodeKeyStore implements KeyStore {
+    private readonly dir: string;
+
+    constructor(dir: string = ".") {
+        this.dir = dir;
+    }
+
+    clear(username: string): Promise<void> {
+        try {
+            fs.unlinkSync(this.filePath(username));
+        } catch {
+            // File may not exist
+        }
+        return Promise.resolve();
+    }
+
+    load(username?: string): Promise<null | StoredCredentials> {
+        if (username) {
+            return Promise.resolve(this.readFile(this.filePath(username)));
+        }
+        // Find most recent .vex file in the directory
+        try {
+            const files = fs
+                .readdirSync(this.dir)
+                .filter((f) => f.endsWith(".vex"))
+                .map((f) => ({
+                    mtime: fs.statSync(path.join(this.dir, f)).mtimeMs,
+                    name: f,
+                }))
+                .sort((a, b) => b.mtime - a.mtime);
+            if (files.length === 0) return Promise.resolve(null);
+            const newest = files[0];
+            if (!newest) return Promise.resolve(null);
+            return Promise.resolve(
+                this.readFile(path.join(this.dir, newest.name)),
+            );
+        } catch {
+            return Promise.resolve(null);
+        }
+    }
+
+    save(creds: StoredCredentials): Promise<void> {
+        const data = JSON.stringify(creds);
+        const encrypted = XUtils.encryptKeyData("", data);
+        fs.writeFileSync(this.filePath(creds.username), encrypted);
+        return Promise.resolve();
+    }
+
+    private filePath(username: string): string {
+        return path.join(this.dir, `${username}.vex`);
+    }
+
+    private readFile(filePath: string): null | StoredCredentials {
+        try {
+            const data = fs.readFileSync(filePath);
+            const decrypted = XUtils.decryptKeyData(new Uint8Array(data), "");
+            const parsed: unknown = JSON.parse(decrypted);
+            if (isStoredCredentials(parsed)) {
+                return parsed;
+            }
+            return null;
+        } catch {
+            return null;
+        }
+    }
+}
+
+function isStoredCredentials(value: unknown): value is StoredCredentials {
+    if (typeof value !== "object" || value === null) return false;
+    return (
+        "username" in value &&
+        typeof value.username === "string" &&
+        "deviceID" in value &&
+        typeof value.deviceID === "string" &&
+        "deviceKey" in value &&
+        typeof value.deviceKey === "string"
+    );
+}

package/src/preset/common.ts

@@ -0,0 +1,13 @@
+import type { Storage } from "../Storage.js";
+import type { Logger } from "../transport/types.js";
+
+/** Internal preset interface used by nodePreset and testPreset. */
+export interface PlatformPreset {
+    createStorage(
+        dbName: string,
+        privateKey: string,
+        logger: Logger,
+    ): Promise<Storage>;
+    deviceName: string;
+    logger: Logger;
+}

package/src/preset/node.ts

@@ -0,0 +1,34 @@
+import type { Storage } from "../Storage.js";
+import type { Logger } from "../transport/types.js";
+/**
+ * Platform preset for Node.js (CLI tools, bots, tests).
+ *
+ * - WebSocket: native global (Node 22+)
+ * - Storage:   Kysely + better-sqlite3
+ * - Logger:    winston (loaded dynamically)
+ */
+import type { PlatformPreset } from "./common.js";
+
+export async function nodePreset(logLevel?: string): Promise<PlatformPreset> {
+    const { createLogger } = await import("../utils/createLogger.js");
+    const logger: Logger = createLogger("libvex", logLevel);
+
+    return {
+        async createStorage(
+            dbName,
+            privateKey,
+            storageLogger,
+        ): Promise<Storage> {
+            const { createNodeStorage } = await import("../storage/node.js");
+
+            const storage: Storage = createNodeStorage(
+                dbName,
+                privateKey,
+                storageLogger,
+            );
+            return storage;
+        },
+        deviceName: process.platform,
+        logger,
+    };
+}

package/src/preset/test.ts

@@ -0,0 +1,37 @@
+import type { Logger } from "../transport/types.js";
+/**
+ * Platform preset for tests — no I/O, no platform dependencies.
+ *
+ * - WebSocket: native global (Node 22+)
+ * - Storage:   in-memory (no persistence)
+ * - Logger:    console
+ */
+import type { PlatformPreset } from "./common.js";
+
+const logger: Logger = {
+    debug() {},
+    error(m: string) {
+        console.error(`[test] ${m}`);
+    },
+    info(m: string) {
+        console.log(`[test] ${m}`);
+    },
+    warn(m: string) {
+        console.warn(`[test] ${m}`);
+    },
+};
+
+export function testPreset(): PlatformPreset {
+    return {
+        async createStorage(_dbName, privateKey, _logger) {
+            // Lazy import to avoid pulling eventemitter3 into the type graph
+            const { MemoryStorage } =
+                await import("../__tests__/harness/memory-storage.js");
+            const storage = new MemoryStorage(privateKey);
+            await storage.init();
+            return storage;
+        },
+        deviceName: "test",
+        logger,
+    };
+}

package/src/storage/node.ts

@@ -0,0 +1,33 @@
+import type { Storage } from "../Storage.js";
+import type { Logger } from "../transport/types.js";
+import type { ClientDatabase } from "./schema.js";
+
+import BetterSqlite3 from "better-sqlite3";
+/**
+ * Node.js storage factory — creates SqliteStorage with better-sqlite3 dialect.
+ * Node-only — imports better-sqlite3 which is a native addon.
+ */
+import { Kysely, SqliteDialect } from "kysely";
+
+import { SqliteStorage } from "./sqlite.js";
+
+export function createNodeStorage(
+    dbPath: string,
+    SK: string,
+    logger?: Logger,
+): Storage {
+    const db = new Kysely<ClientDatabase>({
+        dialect: new SqliteDialect({
+            database: new BetterSqlite3(dbPath),
+        }),
+    });
+    const log: Logger = logger ?? {
+        debug() {},
+        error() {},
+        info() {},
+        warn() {},
+    };
+    const storage = new SqliteStorage(db, SK, log);
+    void storage.init();
+    return storage;
+}

package/src/storage/schema.ts

@@ -0,0 +1,94 @@
+/**
+ * Kysely typed table interfaces for the client-side SQLite database.
+ */
+import type {
+    ColumnType,
+    Generated,
+    Insertable,
+    Selectable,
+    Updateable,
+} from "kysely";
+
+export interface ClientDatabase {
+    devices: DevicesTable;
+    messages: MessagesTable;
+    oneTimeKeys: OneTimeKeysTable;
+    preKeys: PreKeysTable;
+    sessions: SessionsTable;
+}
+
+export type DeviceRow = Selectable<DevicesTable>;
+
+export type DeviceUpdate = Updateable<DevicesTable>;
+
+export type MessageRow = Selectable<MessagesTable>;
+
+export type MessageUpdate = Updateable<MessagesTable>;
+
+export type NewDevice = Insertable<DevicesTable>;
+
+// ── Row utility types ────────────────────────────────────────────────────────
+
+export type NewMessage = Insertable<MessagesTable>;
+export type NewOneTimeKey = Insertable<OneTimeKeysTable>;
+export type NewPreKey = Insertable<PreKeysTable>;
+
+export type NewSession = Insertable<SessionsTable>;
+export type OneTimeKeyRow = Selectable<OneTimeKeysTable>;
+export type PreKeyRow = Selectable<PreKeysTable>;
+
+export type SessionRow = Selectable<SessionsTable>;
+export type SessionUpdate = Updateable<SessionsTable>;
+interface DevicesTable {
+    deleted: number;
+    deviceID: string;
+    lastLogin: string;
+    name: string;
+    owner: string;
+    signKey: string;
+}
+
+interface MessagesTable {
+    authorID: string;
+    decrypted: number;
+    direction: string;
+    forward: number;
+    group: null | string;
+    mailID: string;
+    message: string;
+    nonce: string;
+    readerID: string;
+    recipient: string;
+    sender: string;
+    timestamp: string;
+}
+interface OneTimeKeysTable {
+    deviceID: ColumnType<string, string | undefined, string>;
+    index: Generated<number>;
+    keyID: ColumnType<string, string | undefined, string>;
+    privateKey: string;
+    publicKey: string;
+    signature: string;
+    userID: ColumnType<string, string | undefined, string>;
+}
+
+interface PreKeysTable {
+    deviceID: ColumnType<string, string | undefined, string>;
+    index: Generated<number>;
+    keyID: ColumnType<string, string | undefined, string>;
+    privateKey: string;
+    publicKey: string;
+    signature: string;
+    userID: ColumnType<string, string | undefined, string>;
+}
+interface SessionsTable {
+    deviceID: string;
+    fingerprint: string;
+    lastUsed: string;
+    mode: string;
+    publicKey: string;
+    sessionID: string;
+    SK: string;
+    userID: string;
+    verified: number;
+}