@vex-chat/spire 1.0.3 → 1.1.0

package/src/Spire.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ActionToken, BaseMsg, NotifyMsg, User } from "@vex-chat/types";
-import type { Server } from "http";
+import type { IncomingMessage, Server } from "http";
 
 import { EventEmitter } from "events";
 import { execSync } from "node:child_process";
@@ -19,9 +19,10 @@ import express from "express";
 import { XUtils } from "@vex-chat/crypto";
 import {
     type KeyPair,
+    setCryptoProfile,
     xRandomBytes,
     xSignKeyPairFromSecret,
-    xSignOpen,
+    xSignKeyPairFromSecretAsync,
 } from "@vex-chat/crypto";
 import {
     MailWSSchema,
@@ -31,6 +32,7 @@ import {
 } from "@vex-chat/types";
 
 import jwt from "jsonwebtoken";
+import morgan from "morgan";
 import { stringify as uuidStringify } from "uuid";
 import { WebSocketServer } from "ws";
 import { z } from "zod/v4";
@@ -40,13 +42,15 @@ import { Database, hashPasswordArgon2, verifyPassword } from "./Database.ts";
 import { initApp, protect } from "./server/index.ts";
 import { authLimiter, devApiKeySkipsRateLimits } from "./server/rateLimit.ts";
 import { censorUser, getParam, getUser } from "./server/utils.ts";
+import { resolveSpireListenPort } from "./spireListenPort.ts";
 import { getJwtSecret } from "./utils/jwtSecret.ts";
 import { msgpack } from "./utils/msgpack.ts";
+import { spireXSignOpenAsync } from "./utils/spireXSignOpenAsync.ts";
 
 // expiry of regkeys = 24hr
 export const TOKEN_EXPIRY = 1000 * 60 * 10;
 export const JWT_EXPIRY = "7d";
-export const DEVICE_AUTH_JWT_EXPIRY = "1h";
+export const DEVICE_AUTH_JWT_EXPIRY = "7d";
 const DEVICE_CHALLENGE_EXPIRY = 1000 * 60; // 60 seconds
 
 // 3-19 chars long
@@ -132,15 +136,40 @@ const getCommitSha = (): string => {
 };
 
 export interface SpireOptions {
+    /**
+     * TCP port for the HTTP/WS server. If omitted, `run.ts` + `resolveSpireListenPort`
+     * use the default (16777 for all profiles; crypto mode is in `GET /status`). Env: `API_PORT`.
+     */
     apiPort?: number;
+    /** Default `tweetnacl`. For `fips`, use `Spire.createAsync` (FIPS key load is async). */
+    cryptoProfile?: "fips" | "tweetnacl";
     dbType?: "mysql" | "sqlite3" | "sqlite3mem" | "sqlite";
 }
 
+/**
+ * Masks identifying material in the access-log URL: hyphenated UUIDs, and
+ * `/device/...` path segments that hold public-key material (32B ed25519 hex, or
+ * a longer P-256 SPKI hex in FIPS) — not the same pattern as a UUID.
+ */
+function redactAccessLogUrl(url: string): string {
+    let s = url.replace(
+        /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi,
+        "[uuid]",
+    );
+    // Device id is a hex public key, not a UUID: strip the segment after /device/
+    s = s.replace(/(\/device\/)([0-9a-fA-F]{16,})(?=[/?#]|$)/g, "$1[device]");
+    return s;
+}
+
+/** FIPS: sign key loaded inside `Spire.createAsync` before the constructor runs. */
+let pendingFipsKeyPair: KeyPair | null = null;
+
 export class Spire extends EventEmitter {
     private actionTokens: ActionToken[] = [];
     private api = express();
     private clients: ClientManager[] = [];
     private readonly commitSha = getCommitSha();
+    private readonly cryptoProfile: "fips" | "tweetnacl";
     private db: Database;
     private dbReady = false;
     private deviceChallenges = new Map<
@@ -148,13 +177,13 @@ export class Spire extends EventEmitter {
         { deviceID: string; nonce: string; time: number }
     >();
     private queuedRequestIncrements = 0;
+
     private requestsTotal = 0;
 
     private requestsTotalLoaded = false;
-
     private server: null | Server = null;
-    private signKeys: KeyPair;
 
+    private signKeys: KeyPair;
     private readonly startedAt = new Date();
     private readonly version = getAppVersion();
     private wss: WebSocketServer = new WebSocketServer({
@@ -164,7 +193,19 @@ export class Spire extends EventEmitter {
 
     constructor(SK: string, options?: SpireOptions) {
         super();
-        this.signKeys = xSignKeyPairFromSecret(XUtils.decodeHex(SK));
+        this.cryptoProfile = options?.cryptoProfile ?? "tweetnacl";
+        if (pendingFipsKeyPair) {
+            this.signKeys = pendingFipsKeyPair;
+            pendingFipsKeyPair = null;
+        } else {
+            if (this.cryptoProfile === "fips") {
+                throw new Error(
+                    'FIPS: use `await Spire.createAsync(secretKeyHex, { ...options, cryptoProfile: "fips" })` instead of `new Spire()`.',
+                );
+            }
+            setCryptoProfile(this.cryptoProfile);
+            this.signKeys = xSignKeyPairFromSecret(XUtils.decodeHex(SK));
+        }
 
         // Trust a single proxy hop (nginx / cloudflare / load balancer).
         // Required so `req.ip` and `express-rate-limit`'s keyGenerator see
@@ -181,7 +222,34 @@ export class Spire extends EventEmitter {
             });
         });
 
-        this.init(options?.apiPort || 16777);
+        this.init(resolveSpireListenPort(options?.apiPort));
+    }
+
+    /**
+     * Construct Spire when the crypto profile is `fips` (async sign-key derivation).
+     * For `tweetnacl` (default) you can use `new Spire()` directly.
+     */
+    public static async createAsync(
+        secretKeyHex: string,
+        options?: SpireOptions,
+    ): Promise<Spire> {
+        if ((options?.cryptoProfile ?? "tweetnacl") !== "fips") {
+            return new Spire(secretKeyHex, options);
+        }
+        if (typeof globalThis.crypto.subtle !== "object") {
+            throw new Error(
+                "FIPS: Spire requires `globalThis.crypto.subtle` (e.g. Node 20+ with global Web Crypto).",
+            );
+        }
+        setCryptoProfile("fips");
+        try {
+            pendingFipsKeyPair = await xSignKeyPairFromSecretAsync(
+                XUtils.decodeHex(secretKeyHex),
+            );
+            return new Spire(secretKeyHex, options);
+        } finally {
+            pendingFipsKeyPair = null;
+        }
     }
 
     public async close(): Promise<void> {
@@ -232,6 +300,21 @@ export class Spire extends EventEmitter {
     }
 
     private init(apiPort: number): void {
+        // Request traces (UUIDs and device public-key path segments redacted
+        // in the `url` token). Enabled in all envs, including production.
+        const accessFlag = process.env["SPIRE_HTTP_ACCESS_LOG"];
+        const accessLogEnabled =
+            accessFlag !== "0" &&
+            accessFlag !== "false" &&
+            accessFlag !== "off";
+        if (accessLogEnabled) {
+            morgan.token("url", (req: IncomingMessage) => {
+                const r = req as IncomingMessage & { originalUrl?: string };
+                return redactAccessLogUrl(r.originalUrl ?? r.url ?? "");
+            });
+            this.api.use(morgan("dev"));
+        }
+
         this.api.use((_req, _res, next) => {
             this.requestsTotal += 1;
 
@@ -432,12 +515,16 @@ export class Spire extends EventEmitter {
             res.json({ dbReady: true, ok: true });
         });
 
-        this.api.get("/status", async (_req, res) => {
+        this.api.get("/status", async (req, res) => {
             const started = Date.now();
             const dbHealthy = this.dbReady ? await this.db.isHealthy() : false;
             const checkDurationMs = Date.now() - started;
 
             const ok = dbHealthy;
+            if (!devApiKeySkipsRateLimits(req)) {
+                res.json({ cryptoProfile: this.cryptoProfile, ok });
+                return;
+            }
             const canaryEnv = process.env["CANARY"]?.trim().toLowerCase();
             res.json({
                 canary:
@@ -445,6 +532,7 @@ export class Spire extends EventEmitter {
                     canaryEnv === "true" ||
                     canaryEnv === "yes",
                 checkDurationMs,
+                cryptoProfile: this.cryptoProfile,
                 now: new Date(),
                 ok,
                 version: this.version,
@@ -592,7 +680,7 @@ export class Spire extends EventEmitter {
                 }
 
                 // Verify the Ed25519 signature
-                const opened = xSignOpen(
+                const opened = await spireXSignOpenAsync(
                     XUtils.decodeHex(signed),
                     XUtils.decodeHex(device.signKey),
                 );
@@ -743,13 +831,14 @@ export class Spire extends EventEmitter {
                     return;
                 }
 
-                const regKey = xSignOpen(
+                const regKey = await spireXSignOpenAsync(
                     XUtils.decodeHex(regPayload.signed),
                     XUtils.decodeHex(regPayload.signKey),
                 );
 
                 if (
                     regKey &&
+                    regKey.length === 16 &&
                     this.validateToken(
                         uuidStringify(regKey),
                         TokenScopes.Register,
@@ -800,14 +889,28 @@ export class Spire extends EventEmitter {
                         }
                         res.send(msgpack.encode(censorUser(user)));
                     }
+                } else if (regKey && regKey.length !== 16) {
+                    res.status(400).send({
+                        error: "Invalid registration token payload.",
+                    });
                 } else {
                     res.status(400).send({
                         error: "Invalid or no token supplied.",
                     });
                 }
-            } catch (_err: unknown) {
-                // debugger: registration error
-                res.sendStatus(500);
+            } catch (err: unknown) {
+                const requestId = crypto.randomUUID();
+                const message =
+                    err instanceof Error ? err.message : String(err);
+                console.error(
+                    `[spire] /register failed requestId=${requestId} profile=${this.cryptoProfile} message=${message}`,
+                );
+                if (err instanceof Error && err.stack) {
+                    console.error(err.stack);
+                }
+                res.status(500).json({
+                    error: `Registration failed. requestId=${requestId}`,
+                });
             }
         });
 

package/src/__tests__/Database.spec.ts

@@ -71,7 +71,8 @@ describe("Database", () => {
         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);
+            // uuid@14 overloads: mock the string return path (v4 with no `buf` argument).
+            vi.mocked(uuid.v4 as () => string).mockReturnValueOnce(keyID);
 
             const provider = new Database(options);
             await new Promise<void>((resolve, reject) => {

package/src/__tests__/spireListenPort.spec.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+    DEFAULT_SPIRE_API_PORT,
+    resolveSpireListenPort,
+} from "../spireListenPort.ts";
+
+describe("resolveSpireListenPort", () => {
+    it("uses default for tweetnacl and fips when no explicit port", () => {
+        expect(resolveSpireListenPort(undefined)).toBe(DEFAULT_SPIRE_API_PORT);
+    });
+
+    it("honors explicit api port", () => {
+        expect(resolveSpireListenPort(9000)).toBe(9000);
+    });
+});

package/src/index.ts

@@ -7,3 +7,7 @@
 import { Spire } from "./Spire.ts";
 
 export { Spire };
+export {
+    DEFAULT_SPIRE_API_PORT,
+    resolveSpireListenPort,
+} from "./spireListenPort.ts";

package/src/run.ts

@@ -9,7 +9,7 @@ import type { SpireOptions } from "./Spire.ts";
 import { Spire } from "./Spire.ts";
 import { loadEnv } from "./utils/loadEnv.ts";
 
-function main() {
+async function main() {
     // load the environment variables — loadEnv() exits if required vars are missing
     loadEnv();
 
@@ -18,13 +18,32 @@ function main() {
         throw new Error("SPK must be set (loadEnv should have caught this).");
     }
 
-    const apiPort = process.env["API_PORT"];
+    const rawPort = process.env["API_PORT"]?.trim() ?? "";
+    const apiPort =
+        rawPort.length > 0 ? Number.parseInt(rawPort, 10) : undefined;
+    if (apiPort !== undefined) {
+        if (!Number.isFinite(apiPort) || apiPort < 1 || apiPort > 65_535) {
+            throw new Error(
+                `API_PORT must be 1-65535; got ${JSON.stringify(process.env["API_PORT"])}.`,
+            );
+        }
+    }
     const dbType = parseDbType(process.env["DB_TYPE"]);
+    const fips =
+        process.env["SPIRE_FIPS"] === "1" ||
+        process.env["SPIRE_FIPS"] === "true";
 
-    new Spire(spk, {
-        ...(apiPort !== undefined ? { apiPort: Number(apiPort) } : {}),
+    const options: SpireOptions = {
+        ...(apiPort !== undefined ? { apiPort } : {}),
         ...(dbType !== undefined ? { dbType } : {}),
-    });
+        ...(fips ? { cryptoProfile: "fips" } : {}),
+    };
+
+    if (fips) {
+        await Spire.createAsync(spk, options);
+    } else {
+        new Spire(spk, options);
+    }
 }
 
 function parseDbType(value: string | undefined): SpireOptions["dbType"] {
@@ -39,4 +58,7 @@ function parseDbType(value: string | undefined): SpireOptions["dbType"] {
     }
 }
 
-main();
+void main().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+});

package/src/server/index.ts

@@ -12,8 +12,7 @@ import * as fsp from "node:fs/promises";
 
 import express from "express";
 
-import { XUtils } from "@vex-chat/crypto";
-import { type KeyPair, xSignOpen } from "@vex-chat/crypto";
+import { type KeyPair, XUtils } from "@vex-chat/crypto";
 import { PreKeysWSSchema, TokenScopes, UserSchema } from "@vex-chat/types";
 
 import cors from "cors";
@@ -29,6 +28,7 @@ import { POWER_LEVELS } from "../ClientManager.ts";
 import { JWT_EXPIRY } from "../Spire.ts";
 import { getJwtSecret } from "../utils/jwtSecret.ts";
 import { msgpack } from "../utils/msgpack.ts";
+import { spireXSignOpenAsync } from "../utils/spireXSignOpenAsync.ts";
 
 import { getAvatarRouter } from "./avatar.ts";
 import { errorHandler } from "./errors.ts";
@@ -181,7 +181,7 @@ export const initApp = (
     ) => void,
 ) => {
     // INIT ROUTERS
-    const userRouter = getUserRouter(db, tokenValidator);
+    const userRouter = getUserRouter(db, tokenValidator, notify);
     const fileRouter = getFileRouter(db);
     const avatarRouter = getAvatarRouter();
     const inviteRouter = getInviteRouter(db, tokenValidator, notify);
@@ -198,16 +198,10 @@ export const initApp = (
             type: "application/msgpack",
         }),
     );
-    api.use(helmet());
-    api.use(msgpackParser);
-    api.use(checkAuth);
-    api.use(checkDevice);
 
-    // Browser clients (web, Tauri, Capacitor, etc.) hit Spire from arbitrary
-    // origins when self-hosted or embedded in third-party apps. libvex uses
-    // `Authorization: Bearer` only (no cookies), so reflecting `Origin` is the
-    // usual bearer-API pattern. Set `CORS_ORIGINS` to a comma-separated allowlist
-    // when an operator wants to restrict which frontends may call the API.
+    // CORS before helmet/auth so browser preflight (OPTIONS) and PATCH get
+    // Access-Control-* headers. Node clients ignore CORS; browsers do not.
+    // Set `CORS_ORIGINS` to a comma-separated allowlist to restrict frontends.
     const corsRaw = process.env["CORS_ORIGINS"];
     const corsOrigins = corsRaw
         ? corsRaw
@@ -218,6 +212,15 @@ export const initApp = (
     api.use(
         cors({
             credentials: true,
+            methods: [
+                "GET",
+                "HEAD",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "OPTIONS",
+            ],
             origin:
                 corsOrigins.length > 0
                     ? corsOrigins
@@ -225,6 +228,11 @@ export const initApp = (
         }),
     );
 
+    api.use(helmet());
+    api.use(msgpackParser);
+    api.use(checkAuth);
+    api.use(checkDevice);
+
     api.get("/server/:id", protect, async (req, res) => {
         const server = await db.retrieveServer(getParam(req, "id"));
 
@@ -576,7 +584,10 @@ export const initApp = (
             return;
         }
 
-        const regKey = xSignOpen(signed, XUtils.decodeHex(device.signKey));
+        const regKey = await spireXSignOpenAsync(
+            signed,
+            XUtils.decodeHex(device.signKey),
+        );
         if (
             regKey &&
             tokenValidator(uuidStringify(regKey), TokenScopes.Connect)
@@ -628,7 +639,7 @@ export const initApp = (
             return;
         }
 
-        const message = xSignOpen(
+        const message = await spireXSignOpenAsync(
             otk.signature,
             XUtils.decodeHex(device.signKey),
         );