@vex-chat/libvex 1.1.0 → 4.0.0

package/src/keystore/node.ts

@@ -0,0 +1,102 @@
+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;
+    private readonly passphrase: string;
+
+    constructor(passphrase: string, dir: string = ".") {
+        if (!passphrase) {
+            throw new Error(
+                "NodeKeyStore requires a non-empty passphrase. " +
+                    "The caller must supply a passphrase sourced from user input, OS keychain, or similar.",
+            );
+        }
+        this.passphrase = passphrase;
+        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(this.passphrase, 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),
+                this.passphrase,
+            );
+            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,7 @@
+import type { Storage } from "../Storage.js";
+
+/** Internal preset interface used by nodePreset and testPreset. */
+export interface PlatformPreset {
+    createStorage(dbName: string, privateKey: string): Promise<Storage>;
+    deviceName: string;
+}

package/src/preset/node.ts

@@ -0,0 +1,18 @@
+import type { Storage } from "../Storage.js";
+/**
+ * Platform preset for Node.js (CLI tools, bots, tests).
+ *
+ * - WebSocket: native global (Node 22+)
+ * - Storage:   Kysely + better-sqlite3
+ */
+import type { PlatformPreset } from "./common.js";
+
+export function nodePreset(): PlatformPreset {
+    return {
+        async createStorage(dbName, privateKey): Promise<Storage> {
+            const { createNodeStorage } = await import("../storage/node.js");
+            return createNodeStorage(dbName, privateKey);
+        },
+        deviceName: process.platform,
+    };
+}

package/src/preset/test.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform preset for tests — no I/O, no platform dependencies.
+ *
+ * - WebSocket: native global (Node 22+)
+ * - Storage:   in-memory (no persistence)
+ */
+import type { PlatformPreset } from "./common.js";
+
+export function testPreset(): PlatformPreset {
+    return {
+        async createStorage(_dbName, privateKey) {
+            const { MemoryStorage } =
+                await import("../__tests__/harness/memory-storage.js");
+            const storage = new MemoryStorage(privateKey);
+            await storage.init();
+            return storage;
+        },
+        deviceName: "test",
+    };
+}

package/src/storage/node.ts

@@ -0,0 +1,22 @@
+import type { Storage } from "../Storage.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): Storage {
+    const db = new Kysely<ClientDatabase>({
+        dialect: new SqliteDialect({
+            database: new BetterSqlite3(dbPath),
+        }),
+    });
+    const storage = new SqliteStorage(db, SK);
+    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;
+}