@vex-chat/spire 0.7.4 → 1.0.0

package/src/server/invite.ts

@@ -0,0 +1,65 @@
+import type { Database } from "../Database.ts";
+import type { TokenScopes } from "@vex-chat/types";
+import type winston from "winston";
+
+import express from "express";
+
+import { msgpack } from "../utils/msgpack.ts";
+
+import { getParam, getUser } from "./utils.ts";
+
+import { protect } from "./index.ts";
+
+export const getInviteRouter = (
+    db: Database,
+    log: winston.Logger,
+    tokenValidator: (key: string, scope: TokenScopes) => boolean,
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void,
+) => {
+    const router = express.Router();
+    router.patch("/:inviteID", protect, async (req, res) => {
+        const userDetails = getUser(req);
+
+        const invite = await db.retrieveInvite(getParam(req, "inviteID"));
+        if (!invite) {
+            res.sendStatus(404);
+            return;
+        }
+
+        if (new Date(invite.expiration).getTime() < Date.now()) {
+            res.sendStatus(401);
+            return;
+        }
+
+        const permission = await db.createPermission(
+            userDetails.userID,
+            "server",
+            invite.serverID,
+            0,
+        );
+        res.send(msgpack.encode(permission));
+        notify(
+            userDetails.userID,
+            "permission",
+            crypto.randomUUID(),
+            permission,
+        );
+    });
+
+    router.get("/:inviteID", protect, async (req, res) => {
+        const invite = await db.retrieveInvite(getParam(req, "inviteID"));
+        if (!invite) {
+            res.sendStatus(404);
+            return;
+        }
+        res.send(msgpack.encode(invite));
+    });
+
+    return router;
+};

package/src/server/openapi.ts

@@ -0,0 +1,51 @@
+/**
+ * API documentation endpoints (development only).
+ *
+ * - GET /docs        — Scalar OpenAPI viewer (REST API)
+ * - GET /async-docs  — AsyncAPI web component viewer (WebSocket protocol)
+ * - GET /openapi.json  — raw OpenAPI 3.1 spec
+ * - GET /asyncapi.json — raw AsyncAPI 3.0 spec
+ *
+ * Specs are generated at build time from Zod schemas in @vex-chat/types.
+ * The interactive viewers require unsafe-eval (AJV) and CDN scripts (Scalar),
+ * so they are disabled in production. Raw JSON specs are always available.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import express from "express";
+
+import asyncApiSpec from "@vex-chat/types/asyncapi.json" with { type: "json" };
+import openApiSpec from "@vex-chat/types/openapi.json" with { type: "json" };
+
+import { apiReference } from "@scalar/express-api-reference";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const isProduction = process.env["NODE_ENV"] === "production";
+
+const pkgDir = (pkg: string) =>
+    path.resolve(__dirname, "../../node_modules", pkg);
+
+export const setupDocs = (api: express.Application) => {
+    // Raw JSON specs — always available (no CSP issues, machine-readable)
+    api.get("/openapi.json", (_req, res) => {
+        res.json(openApiSpec);
+    });
+    api.get("/asyncapi.json", (_req, res) => {
+        res.json(asyncApiSpec);
+    });
+
+    if (isProduction) return;
+
+    // Interactive viewers — development only (require unsafe-eval + CDN)
+    api.use("/docs", apiReference({ theme: "purple", url: "/openapi.json" }));
+    api.use("/vendor", express.static(pkgDir("@asyncapi/web-component/lib")));
+    api.use(
+        "/assets",
+        express.static(pkgDir("@asyncapi/react-component/styles")),
+    );
+
+    api.get("/async-docs", (_req, res) => {
+        res.sendFile(path.resolve(__dirname, "../../public/async-docs.html"));
+    });
+};

package/src/server/permissions.ts

@@ -0,0 +1,40 @@
+import type { Permission } from "@vex-chat/types";
+
+/**
+ * Check whether any permission in the list covers the given resource
+ * (any power level).
+ */
+export function hasAnyPermission(
+    permissions: Permission[],
+    resourceID: string,
+): boolean {
+    return permissions.some((p) => p.resourceID === resourceID);
+}
+
+/**
+ * Check whether any permission in the list grants at least `minPowerLevel`
+ * on the given resource.
+ */
+export function hasPermission(
+    permissions: Permission[],
+    resourceID: string,
+    minPowerLevel: number,
+): boolean {
+    return permissions.some(
+        (p) => p.resourceID === resourceID && p.powerLevel > minPowerLevel,
+    );
+}
+
+/**
+ * Check whether any permission in the list grants at least `minPowerLevel`
+ * on the given resource AND belongs to the specified user.
+ */
+export function userHasPermission(
+    permissions: Permission[],
+    userID: string,
+    minPowerLevel: number,
+): boolean {
+    return permissions.some(
+        (p) => p.userID === userID && p.powerLevel > minPowerLevel,
+    );
+}

package/src/server/rateLimit.ts

@@ -0,0 +1,86 @@
+/**
+ * Rate limiting middleware.
+ *
+ * Three tiers matching CWE-307 (brute-force auth), CWE-400 / CWE-770
+ * (unrestricted resource consumption), and OWASP API4:2023:
+ *
+ * - `globalLimiter` — baseline per-IP limit across every route. Wide
+ *   enough to not bother normal clients, tight enough to shield the
+ *   server from a single-host flood.
+ * - `authLimiter` — strict per-IP limit on auth endpoints (register,
+ *   login, device challenge). `skipSuccessfulRequests` means only the
+ *   failed attempts count, so a correct login doesn't eat the budget.
+ * - `uploadLimiter` — upload-specific limit applied before multer,
+ *   so multer never even parses a request that's over quota.
+ *
+ * All three use `ipKeyGenerator` from `express-rate-limit@7.4+` to
+ * bucket IPv4 and IPv4-mapped IPv6 correctly (CVE-2026-30827 — older
+ * versions silently collapsed all IPv4-mapped IPv6 addresses into
+ * one bucket, which let attackers bypass the limiter).
+ *
+ * `trust proxy` must be set on the Express app (see Spire.ts) so
+ * `req.ip` returns the real client address, not the immediate proxy.
+ */
+import type { Request } from "express";
+
+import rateLimit, { ipKeyGenerator } from "express-rate-limit";
+
+/**
+ * Bucket requests by the real client IP, IPv6-safe.
+ *
+ * `req.ip` is already populated correctly because `trust proxy` is
+ * set to `1` in Spire's constructor. We still run it through
+ * `ipKeyGenerator` so IPv4-mapped IPv6 (`::ffff:1.2.3.4`) doesn't
+ * collide with unrelated IPv6 addresses in the same /56.
+ */
+const keyByIp = (req: Request): string => ipKeyGenerator(req.ip ?? "");
+
+/**
+ * Global per-IP limiter. Applied app-wide via `api.use(globalLimiter)`.
+ *
+ * 300 requests per 15 minutes per client IP. A human chatting via a
+ * browser or the libvex client won't come close; a single-host DoS
+ * gets throttled quickly.
+ */
+export const globalLimiter = rateLimit({
+    keyGenerator: keyByIp,
+    legacyHeaders: false,
+    limit: 300,
+    standardHeaders: "draft-7",
+    windowMs: 15 * 60 * 1000,
+});
+
+/**
+ * Strict auth endpoint limiter. Applied per-route to /auth, /register,
+ * and /auth/device.
+ *
+ * 5 failed attempts per 15 minutes per IP. Successful logins don't
+ * count (`skipSuccessfulRequests`), so a normal user doesn't lock
+ * themselves out by fat-fingering a password once. Blocks brute force
+ * (CWE-307) without harming UX.
+ */
+export const authLimiter = rateLimit({
+    keyGenerator: keyByIp,
+    legacyHeaders: false,
+    limit: 5,
+    skipSuccessfulRequests: true,
+    standardHeaders: "draft-7",
+    windowMs: 15 * 60 * 1000,
+});
+
+/**
+ * Upload endpoint limiter. Applied per-route to /file and /avatar
+ * POSTs, BEFORE multer parses the multipart body. Caps the number of
+ * upload attempts per minute so an attacker can't force spire to
+ * spend CPU/IO on repeated large-body parses.
+ *
+ * 20 uploads per minute per IP — generous for a chat client (rapid-
+ * fire image attachments) but tight enough to shield the disk.
+ */
+export const uploadLimiter = rateLimit({
+    keyGenerator: keyByIp,
+    legacyHeaders: false,
+    limit: 20,
+    standardHeaders: "draft-7",
+    windowMs: 60 * 1000,
+});

package/src/server/user.ts

@@ -0,0 +1,125 @@
+import type { Database } from "../Database.ts";
+import type winston from "winston";
+
+import express from "express";
+
+import { XUtils } from "@vex-chat/crypto";
+import { xSignOpen } from "@vex-chat/crypto";
+import { DevicePayloadSchema, TokenScopes } from "@vex-chat/types";
+
+import { stringify } from "uuid";
+
+import { msgpack } from "../utils/msgpack.ts";
+
+import { censorUser, getParam, getUser } from "./utils.ts";
+
+import { protect } from "./index.ts";
+
+export const getUserRouter = (
+    db: Database,
+    log: winston.Logger,
+    tokenValidator: (key: string, scope: TokenScopes) => boolean,
+) => {
+    const router = express.Router();
+
+    router.get("/:id", protect, async (req, res) => {
+        const user = await db.retrieveUser(getParam(req, "id"));
+
+        if (user) {
+            return res.send(msgpack.encode(censorUser(user)));
+        } else {
+            return res.sendStatus(404);
+        }
+    });
+
+    router.get("/:id/devices", protect, async (req, res) => {
+        const deviceList = await db.retrieveUserDeviceList([
+            getParam(req, "id"),
+        ]);
+        return res.send(msgpack.encode(deviceList));
+    });
+
+    router.get("/:id/permissions", protect, async (req, res) => {
+        const userDetails = getUser(req);
+        const permissions = await db.retrievePermissions(
+            userDetails.userID,
+            "all",
+        );
+        res.send(msgpack.encode(permissions));
+    });
+
+    router.get("/:id/servers", protect, async (req, res) => {
+        const userDetails = getUser(req);
+        const servers = await db.retrieveServers(userDetails.userID);
+        res.send(msgpack.encode(servers));
+    });
+
+    router.delete("/:userID/devices/:deviceID", protect, async (req, res) => {
+        const device = await db.retrieveDevice(getParam(req, "deviceID"));
+
+        if (!device) {
+            res.sendStatus(404);
+            return;
+        }
+        const userDetails = getUser(req);
+        if (userDetails.userID !== device.owner) {
+            res.sendStatus(401);
+            return;
+        }
+        const deviceList = await db.retrieveUserDeviceList([
+            userDetails.userID,
+        ]);
+        if (deviceList.length === 1) {
+            res.status(400).send({
+                error: "You can't delete your last device.",
+            });
+            return;
+        }
+
+        await db.deleteDevice(device.deviceID);
+        res.sendStatus(200);
+    });
+
+    router.post("/:id/devices", protect, async (req, res) => {
+        const userDetails = getUser(req);
+        const parsed = DevicePayloadSchema.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({
+                error: "Invalid device payload",
+                issues: parsed.error.issues,
+            });
+            return;
+        }
+        const deviceData = parsed.data;
+
+        const token = xSignOpen(
+            XUtils.decodeHex(deviceData.signed),
+            XUtils.decodeHex(deviceData.signKey),
+        );
+
+        if (!token) {
+            log.warn("Invalid signature on token.");
+            res.sendStatus(400);
+            return;
+        }
+
+        if (tokenValidator(stringify(token), TokenScopes.Device)) {
+            try {
+                const device = await db.createDevice(
+                    userDetails.userID,
+                    deviceData,
+                );
+                res.send(msgpack.encode(device));
+            } catch (err: unknown) {
+                log.warn(String(err));
+                // failed registration due to signkey being taken
+                res.sendStatus(470);
+                return;
+            }
+        } else {
+            res.sendStatus(401);
+        }
+    });
+
+    return router;
+};

package/src/server/utils.ts

@@ -0,0 +1,59 @@
+import type { Device, User, UserRecord } from "@vex-chat/types";
+import type { Request } from "express";
+
+import { AppError } from "./errors.ts";
+
+/**
+ * Strips password fields from a DB user record, returning the
+ * public-safe User shape.
+ */
+export const censorUser = (user: UserRecord): User => {
+    return {
+        lastSeen: user.lastSeen,
+        userID: user.userID,
+        username: user.username,
+    };
+};
+
+/**
+ * Safely extract the authenticated device from a request.
+ * Throws if the device is not set (i.e. checkDevice middleware did
+ * not run or the token was not a device token).
+ *
+ * Throws `AppError(401)` — the central error handler turns this into
+ * a JSON 401 response. No stack trace or raw Error leaks.
+ */
+export function getDevice(req: Request): Device {
+    if (!req.device) throw new AppError(401, "Not authenticated");
+    return req.device;
+}
+
+/**
+ * Safely extract a required route parameter.
+ *
+ * Throws `AppError(400)` if the parameter is missing or is an array
+ * (which shouldn't happen for well-wired routes, but defensively
+ * checked). The error message deliberately does NOT include the
+ * user-supplied value — CWE-79 / CWE-116 fix for the earlier
+ * `"Missing route parameter: " + name` concatenation pattern.
+ */
+export function getParam(req: Request, name: string): string {
+    const value = req.params[name];
+    if (!value || Array.isArray(value)) {
+        throw new AppError(400, "Missing or invalid route parameter");
+    }
+    return value;
+}
+
+/**
+ * Safely extract the authenticated user from a request.
+ * Throws if the user is not set (i.e. protect middleware was not
+ * applied to this route).
+ *
+ * Throws `AppError(401)` — the central error handler turns this into
+ * a JSON 401 response.
+ */
+export function getUser(req: Request): User {
+    if (!req.user) throw new AppError(401, "Not authenticated");
+    return req.user;
+}

package/src/types/express.ts

@@ -0,0 +1,23 @@
+import type { Device, User } from "@vex-chat/types";
+
+/**
+ * Augment Express's global Request interface with the properties
+ * set by checkAuth and checkDevice middleware.
+ *
+ * The global Express.Request is merged into express-serve-static-core's
+ * Request via `extends Express.Request`, so properties added here are
+ * available on `req` in all route handlers.
+ */
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-namespace -- required for Express declaration merging
+    namespace Express {
+        interface Request {
+            bearerToken?: string;
+            device?: Device;
+            exp?: number;
+            user?: User;
+        }
+    }
+}
+
+export {};

package/src/utils/createLogger.ts

@@ -0,0 +1,47 @@
+import winston from "winston";
+
+/**
+ * @ignore
+ */
+export function createLogger(logName: string, logLevel?: string) {
+    const logger = winston.createLogger({
+        defaultMeta: { service: "vex-" + logName },
+        format: winston.format.combine(
+            winston.format.timestamp({
+                format: "YYYY-MM-DD HH:mm:ss",
+            }),
+            winston.format.errors({ stack: true }),
+            winston.format.splat(),
+            winston.format.json(),
+        ),
+        level: logLevel || "error",
+        transports: [
+            //
+            // - Write all logs with level `error` and below to `error.log`
+            // - Write all logs with level `info` and below to `combined.log`
+            //
+            new winston.transports.File({
+                filename: "vex:" + logName + ".log",
+                level: "error",
+            }),
+        ],
+    });
+    //
+    // If we're not in production then log to the `console` with the format:
+    // `${info.level}: ${info.message} JSON.stringify({ ...rest }) `
+    //
+    if (
+        process.env["NODE_ENV"] !== "production" &&
+        process.env["NODE_ENV"] !== "test"
+    ) {
+        logger.add(
+            new winston.transports.Console({
+                format: winston.format.combine(
+                    winston.format.colorize(),
+                    winston.format.simple(),
+                ),
+            }),
+        );
+    }
+    return logger;
+}

package/src/utils/createUint8UUID.ts

@@ -0,0 +1,9 @@
+import { parse as uuidParse } from "uuid";
+
+export function createUint8UUID(): Uint8Array {
+    return uuidToUint8(crypto.randomUUID());
+}
+
+export function uuidToUint8(uuid: string): Uint8Array {
+    return new Uint8Array(uuidParse(uuid));
+}

package/src/utils/jwtSecret.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns the JWT signing secret.
+ *
+ * Prefers JWT_SECRET (dedicated HMAC key) over SPK (NaCl server signing key).
+ * Falls back to SPK for backward compat with existing deployments.
+ */
+export function getJwtSecret(): string {
+    const secret = process.env["JWT_SECRET"] ?? process.env["SPK"];
+    if (!secret) {
+        throw new Error(
+            "Neither JWT_SECRET nor SPK is set. " +
+                "Set JWT_SECRET (preferred) or SPK in your environment.",
+        );
+    }
+    return secret;
+}

package/src/utils/loadEnv.ts

@@ -0,0 +1,15 @@
+import { config } from "dotenv";
+
+/* Populate process.env with vars from .env and verify required vars are present. */
+export function loadEnv(): void {
+    config();
+    const requiredEnvVars: string[] = ["CANARY", "DB_TYPE", "SPK"];
+    for (const required of requiredEnvVars) {
+        if (process.env[required] === undefined) {
+            process.stderr.write(
+                `Required environment variable '${required}' is not set. Please consult the README.\n`,
+            );
+            process.exit(1);
+        }
+    }
+}

package/src/utils/msgpack.ts

@@ -0,0 +1,4 @@
+import { Packr } from "msgpackr";
+
+// Standard msgpack encoder/decoder configured for broad compatibility.
+export const msgpack = new Packr({ moreTypes: false, useRecords: false });

package/dist/migrations/20210103192527_users.d.ts

@@ -1,3 +0,0 @@
-import * as Knex from "knex";
-export declare function up(knex: Knex): Promise<void>;
-export declare function down(knex: Knex): Promise<void>;