@vex-chat/spire 0.8.0 → 1.0.0

package/src/__tests__/Database.spec.ts

@@ -0,0 +1,167 @@
+import type { SpireOptions } from "../Spire.ts";
+import type { PreKeysWS } from "@vex-chat/types";
+
+import { XUtils } from "@vex-chat/crypto";
+
+import * as uuid from "uuid";
+import { describe, expect, it, vi } from "vitest";
+import winston from "winston";
+
+import { Database } from "../Database.ts";
+
+// vi.mock is hoisted above all imports automatically.
+// Minimal stubs for uuid functions used by spire src: v4, parse, stringify.
+vi.mock("uuid", () => ({
+    parse: (s: string) => {
+        const matches = s.replace(/-/g, "").match(/.{2}/g);
+        if (!matches) throw new Error("Invalid UUID");
+        return Uint8Array.from(matches.map((b) => parseInt(b, 16)));
+    },
+    stringify: (b: Uint8Array) => {
+        const hex = Array.from(b)
+            .map((x) => x.toString(16).padStart(2, "0"))
+            .join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+    },
+    v4: vi.fn(() => "93ce482b-a0f2-4f6e-b1df-3aed61073552"),
+    validate: () => true,
+}));
+
+/** Winston logger stub — Database.close() calls `.info`, and `{}` breaks that. */
+function silentLogger(): winston.Logger {
+    const noop = vi.fn();
+    return {
+        debug: noop,
+        error: noop,
+        info: noop,
+        log: noop,
+        verbose: noop,
+        warn: noop,
+    } as unknown as winston.Logger;
+}
+
+describe("Database", () => {
+    // Reusable test data
+    const keyID = "de459e05-aa63-4dfa-97b4-ed43d5c7a5f7";
+    const userID = "4e67b90f-cbf8-44bc-8ce3-d3b248f033f1";
+    const deviceID = "23cb0b27-7d0c-43b2-87e1-c2b93e0095e5";
+
+    const publicKey = XUtils.decodeHex(
+        "30c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+    );
+    const signature = XUtils.decodeHex(
+        "dd0665079426c3efcf4dce9b1487e4aca132f8147581b3294c3f23ddd2b4ba8240a10082bd06805d7eb320d91af971da3306e11b60073ccc3d829710f5036004000030c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+    );
+
+    const testSQLPreKey = {
+        deviceID,
+        index: 1,
+        keyID,
+        publicKey:
+            "30c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+        signature:
+            "dd0665079426c3efcf4dce9b1487e4aca132f8147581b3294c3f23ddd2b4ba8240a10082bd06805d7eb320d91af971da3306e11b60073ccc3d829710f5036004000030c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+        userID,
+    };
+
+    const testWSPreKey: PreKeysWS = {
+        deviceID,
+        index: 1,
+        publicKey,
+        signature,
+    };
+
+    const options: SpireOptions = {
+        dbType: "sqlite3mem",
+    };
+
+    describe("saveOTK", () => {
+        it("takes a userId and one time key, adds a keyId and saves it to oneTimeKey table", async () => {
+            expect.assertions(1);
+
+            vi.mocked(uuid.v4).mockReturnValueOnce(keyID);
+            vi.spyOn(winston, "createLogger").mockReturnValueOnce(
+                silentLogger(),
+            );
+
+            const provider = new Database(options);
+            await new Promise<void>((resolve, reject) => {
+                provider.once("ready", () => {
+                    void (async () => {
+                        try {
+                            await provider.saveOTK(
+                                testSQLPreKey.userID,
+                                testSQLPreKey.deviceID,
+                                [
+                                    {
+                                        deviceID,
+                                        index: 1,
+                                        publicKey,
+                                        signature,
+                                    },
+                                ],
+                            );
+                            const oneTimeKey = await provider.getOTK(deviceID);
+                            expect(oneTimeKey).toEqual(testWSPreKey);
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+    });
+
+    describe("getPreKeys", () => {
+        it("returns a preKey by deviceID if said preKey exists.", async () => {
+            expect.assertions(1);
+
+            const provider = new Database(options);
+            await new Promise<void>((resolve, reject) => {
+                provider.once("ready", () => {
+                    void (async () => {
+                        try {
+                            await provider["db"]
+                                .insertInto("preKeys")
+                                .values(testSQLPreKey)
+                                .execute();
+                            const result = await provider.getPreKeys(deviceID);
+                            expect(result).toEqual(testWSPreKey);
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+
+        it("return null if there are no preKeys with deviceID param", async () => {
+            expect.assertions(1);
+            const provider = new Database(options);
+            await new Promise<void>((resolve, reject) => {
+                provider.once("ready", () => {
+                    void (async () => {
+                        try {
+                            const result = await provider.getPreKeys(deviceID);
+                            expect(result).toBeNull();
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+    });
+});

package/src/ambient-modules.d.ts

@@ -0,0 +1 @@
+declare module "ed2curve";

package/src/db/schema.ts

@@ -0,0 +1,165 @@
+import type { Insertable, Selectable, Updateable } from "kysely";
+
+// ── Table interfaces ────────────────────────────────────────────────────
+
+export type ChannelRow = Selectable<ChannelsTable>;
+
+export interface ChannelsTable {
+    channelID: string;
+    name: string;
+    serverID: string;
+}
+
+export type ChannelUpdate = Updateable<ChannelsTable>;
+
+export type DeviceRow = Selectable<DevicesTable>;
+
+export interface DevicesTable {
+    deleted: number;
+    deviceID: string;
+    lastLogin: string;
+    name: string;
+    owner: string;
+    signKey: string;
+}
+
+export type DeviceUpdate = Updateable<DevicesTable>;
+
+export type EmojiRow = Selectable<EmojisTable>;
+
+export interface EmojisTable {
+    emojiID: string;
+    name: string;
+    owner: string;
+}
+
+export type EmojiUpdate = Updateable<EmojisTable>;
+
+export type FileRow = Selectable<FilesTable>;
+
+export interface FilesTable {
+    fileID: string;
+    nonce: string;
+    owner: string;
+}
+
+export type FileUpdate = Updateable<FilesTable>;
+
+// ── Database schema ─────────────────────────────────────────────────────
+
+export type InviteRow = Selectable<InvitesTable>;
+
+// ── Row utility types ───────────────────────────────────────────────────
+
+export interface InvitesTable {
+    expiration: string;
+    inviteID: string;
+    owner: string;
+    serverID: string;
+}
+export type InviteUpdate = Updateable<InvitesTable>;
+export type MailRow = Selectable<MailTable>;
+
+export interface MailTable {
+    authorID: string;
+    cipher: string;
+    extra: null | string;
+    forward: number;
+    group: null | string;
+    header: string;
+    mailID: string;
+    mailType: number;
+    nonce: string;
+    readerID: string;
+    recipient: string;
+    sender: string;
+    time: string;
+}
+export type MailUpdate = Updateable<MailTable>;
+export type NewChannel = Insertable<ChannelsTable>;
+
+export type NewDevice = Insertable<DevicesTable>;
+export type NewEmoji = Insertable<EmojisTable>;
+export type NewFile = Insertable<FilesTable>;
+
+export type NewInvite = Insertable<InvitesTable>;
+export type NewMail = Insertable<MailTable>;
+export type NewOneTimeKey = Insertable<OneTimeKeysTable>;
+
+export type NewPermission = Insertable<PermissionsTable>;
+export type NewPreKey = Insertable<PreKeysTable>;
+export type NewServer = Insertable<ServersTable>;
+
+export type NewServiceMetric = Insertable<ServiceMetricsTable>;
+export type NewUser = Insertable<UsersTable>;
+export type OneTimeKeyRow = Selectable<OneTimeKeysTable>;
+
+export interface OneTimeKeysTable {
+    deviceID: string;
+    index: number;
+    keyID: string;
+    publicKey: string;
+    signature: string;
+    userID: string;
+}
+export type OneTimeKeyUpdate = Updateable<OneTimeKeysTable>;
+export type PermissionRow = Selectable<PermissionsTable>;
+
+export interface PermissionsTable {
+    permissionID: string;
+    powerLevel: number;
+    resourceID: string;
+    resourceType: string;
+    userID: string;
+}
+export type PermissionUpdate = Updateable<PermissionsTable>;
+export type PreKeyRow = Selectable<PreKeysTable>;
+
+export interface PreKeysTable {
+    deviceID: string;
+    index: number;
+    keyID: string;
+    publicKey: string;
+    signature: string;
+    userID: string;
+}
+export type PreKeyUpdate = Updateable<PreKeysTable>;
+export interface ServerDatabase {
+    channels: ChannelsTable;
+    devices: DevicesTable;
+    emojis: EmojisTable;
+    files: FilesTable;
+    invites: InvitesTable;
+    mail: MailTable;
+    oneTimeKeys: OneTimeKeysTable;
+    permissions: PermissionsTable;
+    preKeys: PreKeysTable;
+    servers: ServersTable;
+    service_metrics: ServiceMetricsTable;
+    users: UsersTable;
+}
+
+export type ServerRow = Selectable<ServersTable>;
+export interface ServersTable {
+    icon: null | string;
+    name: string;
+    serverID: string;
+}
+export type ServerUpdate = Updateable<ServersTable>;
+
+export type ServiceMetricRow = Selectable<ServiceMetricsTable>;
+export interface ServiceMetricsTable {
+    metric_key: string;
+    metric_value: number;
+}
+export type ServiceMetricUpdate = Updateable<ServiceMetricsTable>;
+
+export type UserRow = Selectable<UsersTable>;
+export interface UsersTable {
+    lastSeen: string;
+    passwordHash: string;
+    passwordSalt: string;
+    userID: string;
+    username: string;
+}
+export type UserUpdate = Updateable<UsersTable>;

package/src/index.ts

@@ -0,0 +1,3 @@
+import { Spire } from "./Spire.ts";
+
+export { Spire };

package/src/middleware/validate.ts

@@ -0,0 +1,38 @@
+import type { NextFunction, Request, Response } from "express";
+import type { z } from "zod/v4";
+
+/**
+ * Express middleware that validates req.body against a Zod schema.
+ * On failure, returns 400 with validation errors.
+ */
+export function validateBody(schema: z.ZodType) {
+    return (req: Request, res: Response, next: NextFunction): void => {
+        const result = schema.safeParse(req.body);
+        if (!result.success) {
+            res.status(400).json({
+                error: "Validation failed",
+                issues: result.error.issues,
+            });
+            return;
+        }
+        req.body = result.data;
+        next();
+    };
+}
+
+/**
+ * Validates a single URL param as a non-empty string.
+ * For UUIDs, use validateUuidParam.
+ */
+export function validateParam(name: string) {
+    return (req: Request, res: Response, next: NextFunction): void => {
+        const value = req.params[name];
+        if (!value || typeof value !== "string" || value.trim() === "") {
+            res.status(400).json({
+                error: `Missing or empty parameter: ${name}`,
+            });
+            return;
+        }
+        next();
+    };
+}

package/src/migrations/2026-04-06_initial-schema.ts

@@ -0,0 +1,218 @@
+import { type Kysely, sql } from "kysely";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    const tables = [
+        "service_metrics",
+        "invites",
+        "emojis",
+        "files",
+        "permissions",
+        "channels",
+        "servers",
+        "oneTimeKeys",
+        "preKeys",
+        "mail",
+        "devices",
+        "users",
+    ] as const;
+
+    for (const table of tables) {
+        await db.schema.dropTable(table).ifExists().execute();
+    }
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("users")
+        .ifNotExists()
+        .addColumn("userID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("username", "varchar(255)", (cb) => cb.unique())
+        .addColumn("passwordHash", "text")
+        .addColumn("passwordSalt", "text")
+        .addColumn("lastSeen", "text")
+        .execute();
+
+    await db.schema
+        .createTable("devices")
+        .ifNotExists()
+        .addColumn("deviceID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("signKey", "varchar(255)", (cb) => cb.unique())
+        .addColumn("owner", "varchar(255)")
+        .addColumn("name", "varchar(255)")
+        .addColumn("lastLogin", "text")
+        .addColumn("deleted", "integer", (cb) => cb.defaultTo(0))
+        .execute();
+
+    await db.schema
+        .createTable("mail")
+        .ifNotExists()
+        .addColumn("nonce", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("recipient", "varchar(255)")
+        .addColumn("mailID", "varchar(255)")
+        .addColumn("sender", "varchar(255)")
+        .addColumn("header", "text")
+        .addColumn("cipher", "text")
+        .addColumn("group", "varchar(255)")
+        .addColumn("extra", "text")
+        .addColumn("mailType", "integer")
+        .addColumn("time", "text")
+        .addColumn("forward", "integer", (cb) => cb.defaultTo(0))
+        .addColumn("authorID", "varchar(255)")
+        .addColumn("readerID", "varchar(255)")
+        .execute();
+
+    await db.schema
+        .createIndex("mail_recipient_idx")
+        .ifNotExists()
+        .on("mail")
+        .column("recipient")
+        .execute();
+
+    await db.schema
+        .createTable("preKeys")
+        .ifNotExists()
+        .addColumn("keyID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)")
+        .addColumn("deviceID", "varchar(255)", (cb) => cb.unique())
+        .addColumn("publicKey", "text")
+        .addColumn("signature", "text")
+        .addColumn("index", "integer")
+        .execute();
+
+    await db.schema
+        .createIndex("preKeys_userID_idx")
+        .ifNotExists()
+        .on("preKeys")
+        .column("userID")
+        .execute();
+
+    await db.schema
+        .createIndex("preKeys_deviceID_idx")
+        .ifNotExists()
+        .on("preKeys")
+        .column("deviceID")
+        .execute();
+
+    await db.schema
+        .createTable("oneTimeKeys")
+        .ifNotExists()
+        .addColumn("keyID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)")
+        .addColumn("deviceID", "varchar(255)")
+        .addColumn("publicKey", "text")
+        .addColumn("signature", "text")
+        .addColumn("index", "integer")
+        .execute();
+
+    await db.schema
+        .createIndex("oneTimeKeys_userID_idx")
+        .ifNotExists()
+        .on("oneTimeKeys")
+        .column("userID")
+        .execute();
+
+    await db.schema
+        .createIndex("oneTimeKeys_deviceID_idx")
+        .ifNotExists()
+        .on("oneTimeKeys")
+        .column("deviceID")
+        .execute();
+
+    await db.schema
+        .createTable("servers")
+        .ifNotExists()
+        .addColumn("serverID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("name", "varchar(255)")
+        .addColumn("icon", "varchar(255)")
+        .execute();
+
+    await db.schema
+        .createTable("channels")
+        .ifNotExists()
+        .addColumn("channelID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("serverID", "varchar(255)")
+        .addColumn("name", "varchar(255)")
+        .execute();
+
+    await db.schema
+        .createTable("permissions")
+        .ifNotExists()
+        .addColumn("permissionID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)")
+        .addColumn("resourceType", "varchar(255)")
+        .addColumn("resourceID", "varchar(255)")
+        .addColumn("powerLevel", "integer")
+        .execute();
+
+    await db.schema
+        .createIndex("permissions_userID_idx")
+        .ifNotExists()
+        .on("permissions")
+        .column("userID")
+        .execute();
+
+    await db.schema
+        .createIndex("permissions_resourceID_idx")
+        .ifNotExists()
+        .on("permissions")
+        .column("resourceID")
+        .execute();
+
+    await db.schema
+        .createTable("files")
+        .ifNotExists()
+        .addColumn("fileID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("owner", "varchar(255)")
+        .addColumn("nonce", "varchar(255)")
+        .execute();
+
+    await db.schema
+        .createIndex("files_owner_idx")
+        .ifNotExists()
+        .on("files")
+        .column("owner")
+        .execute();
+
+    await db.schema
+        .createTable("emojis")
+        .ifNotExists()
+        .addColumn("emojiID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("owner", "varchar(255)")
+        .addColumn("name", "varchar(255)")
+        .execute();
+
+    await db.schema
+        .createIndex("emojis_owner_idx")
+        .ifNotExists()
+        .on("emojis")
+        .column("owner")
+        .execute();
+
+    await db.schema
+        .createTable("invites")
+        .ifNotExists()
+        .addColumn("inviteID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("serverID", "varchar(255)")
+        .addColumn("owner", "varchar(255)")
+        .addColumn("expiration", "text")
+        .execute();
+
+    await db.schema
+        .createIndex("invites_serverID_idx")
+        .ifNotExists()
+        .on("invites")
+        .column("serverID")
+        .execute();
+
+    await db.schema
+        .createTable("service_metrics")
+        .ifNotExists()
+        .addColumn("metric_key", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("metric_value", "bigint", (cb) => cb.notNull().defaultTo(0))
+        .execute();
+
+    // Seed the requests_total metric row
+    await sql`INSERT OR IGNORE INTO service_metrics (metric_key, metric_value) VALUES ('requests_total', 0)`.execute(
+        db,
+    );
+}

package/src/run.ts

@@ -0,0 +1,37 @@
+import type { SpireOptions } from "./Spire.ts";
+
+import { Spire } from "./Spire.ts";
+import { loadEnv } from "./utils/loadEnv.ts";
+
+function main() {
+    // load the environment variables — loadEnv() exits if required vars are missing
+    loadEnv();
+
+    const spk = process.env["SPK"];
+    if (!spk) {
+        throw new Error("SPK must be set (loadEnv should have caught this).");
+    }
+
+    const apiPort = process.env["API_PORT"];
+    const dbType = parseDbType(process.env["DB_TYPE"]);
+
+    new Spire(spk, {
+        ...(apiPort !== undefined ? { apiPort: Number(apiPort) } : {}),
+        ...(dbType !== undefined ? { dbType } : {}),
+        logLevel: "info",
+    });
+}
+
+function parseDbType(value: string | undefined): SpireOptions["dbType"] {
+    switch (value) {
+        case "mysql":
+        case "sqlite":
+        case "sqlite3":
+        case "sqlite3mem":
+            return value;
+        default:
+            return undefined;
+    }
+}
+
+main();