@vex-chat/spire 1.10.1 → 1.10.3

package/src/__tests__/Database.spec.ts

@@ -5,9 +5,10 @@
  */
 
 import type { SpireOptions } from "../Spire.ts";
-import type { PreKeysWS } from "@vex-chat/types";
+import type { MailWS, PreKeysWS } from "@vex-chat/types";
 
 import { XUtils } from "@vex-chat/crypto";
+import { MailType } from "@vex-chat/types";
 
 import * as uuid from "uuid";
 import { describe, expect, it, vi } from "vitest";
@@ -154,4 +155,79 @@ describe("Database", () => {
             });
         });
     });
+
+    describe("retrieveMail", () => {
+        it("returns queued mail in send order for logged-out batch drains", async () => {
+            expect.assertions(1);
+
+            const provider = new Database(options);
+            await new Promise<void>((resolve, reject) => {
+                provider.once("ready", () => {
+                    void (async () => {
+                        try {
+                            const mail = (
+                                mailID: string,
+                                time: string,
+                                nonce: string,
+                            ) => ({
+                                authorID: userID,
+                                cipher: "01",
+                                extra: "02",
+                                forward: 0,
+                                group: null,
+                                header: "03",
+                                mailID,
+                                mailType: MailType.initial,
+                                nonce,
+                                readerID: userID,
+                                recipient: deviceID,
+                                sender: "sender-a",
+                                time,
+                            });
+
+                            await provider["db"]
+                                .insertInto("mail")
+                                .values([
+                                    mail(
+                                        "00000000-0000-0000-0000-000000000003",
+                                        "2026-05-07T12:00:02.000Z",
+                                        "06",
+                                    ),
+                                    mail(
+                                        "00000000-0000-0000-0000-000000000001",
+                                        "2026-05-07T12:00:00.000Z",
+                                        "04",
+                                    ),
+                                    mail(
+                                        "00000000-0000-0000-0000-000000000002",
+                                        "2026-05-07T12:00:01.000Z",
+                                        "05",
+                                    ),
+                                ])
+                                .execute();
+
+                            const result =
+                                await provider.retrieveMail(deviceID);
+                            expect(
+                                result.map(
+                                    ([, body]: [Uint8Array, MailWS, string]) =>
+                                        body.mailID,
+                                ),
+                            ).toEqual([
+                                "00000000-0000-0000-0000-000000000001",
+                                "00000000-0000-0000-0000-000000000002",
+                                "00000000-0000-0000-0000-000000000003",
+                            ]);
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+    });
 });

package/src/__tests__/deviceTokenRevalidation.spec.ts

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Device, User } from "@vex-chat/types";
+import type express from "express";
+
+import jwt from "jsonwebtoken";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createCheckDevice } from "../server/index.ts";
+
+const jwtSecret = "test-jwt-secret";
+
+const user: User = {
+    lastSeen: new Date(0).toISOString(),
+    userID: "user-a",
+    username: "alice",
+};
+
+const device: Device = {
+    deleted: false,
+    deviceID: "device-a",
+    lastLogin: new Date(0).toISOString(),
+    name: "desktop",
+    owner: user.userID,
+    signKey: "sign-key-a",
+};
+
+function makeReq(token: string, reqUser: undefined | User = user) {
+    return {
+        headers: { "x-device-token": token },
+        user: reqUser,
+    } as unknown as express.Request;
+}
+
+function makeToken(tokenDevice: Device = device): string {
+    return jwt.sign({ device: tokenDevice }, jwtSecret);
+}
+
+describe("createCheckDevice", () => {
+    afterEach(() => {
+        delete process.env["JWT_SECRET"];
+    });
+
+    it("sets req.device from the current non-deleted database row", async () => {
+        process.env["JWT_SECRET"] = jwtSecret;
+        const db = {
+            retrieveDevice: vi.fn(() => Promise.resolve(device)),
+        };
+        const req = makeReq(makeToken());
+        const next = vi.fn();
+
+        await createCheckDevice(db)(req, {} as express.Response, next);
+
+        expect(req.device).toEqual(device);
+        expect(db.retrieveDevice).toHaveBeenCalledWith(device.deviceID);
+        expect(next).toHaveBeenCalledOnce();
+    });
+
+    it("does not trust a token for a deleted or missing device", async () => {
+        process.env["JWT_SECRET"] = jwtSecret;
+        const db = {
+            retrieveDevice: vi.fn(() => Promise.resolve(null)),
+        };
+        const req = makeReq(makeToken());
+
+        await createCheckDevice(db)(req, {} as express.Response, vi.fn());
+
+        expect(req.device).toBeUndefined();
+    });
+
+    it("does not trust a token whose signing key no longer matches", async () => {
+        process.env["JWT_SECRET"] = jwtSecret;
+        const db = {
+            retrieveDevice: vi.fn(() =>
+                Promise.resolve({ ...device, signKey: "rotated-sign-key" }),
+            ),
+        };
+        const req = makeReq(makeToken());
+
+        await createCheckDevice(db)(req, {} as express.Response, vi.fn());
+
+        expect(req.device).toBeUndefined();
+    });
+
+    it("does not bind a device token to a different bearer user", async () => {
+        process.env["JWT_SECRET"] = jwtSecret;
+        const db = {
+            retrieveDevice: vi.fn(() => Promise.resolve(device)),
+        };
+        const req = makeReq(makeToken(), {
+            lastSeen: new Date(0).toISOString(),
+            userID: "user-b",
+            username: "bob",
+        });
+
+        await createCheckDevice(db)(req, {} as express.Response, vi.fn());
+
+        expect(req.device).toBeUndefined();
+    });
+});

package/src/__tests__/mailIngress.spec.ts

@@ -0,0 +1,122 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { Device, MailWS } from "@vex-chat/types";
+
+import { MailType } from "@vex-chat/types";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { validateMailIngress } from "../server/mailIngress.ts";
+
+const senderDeviceID = "sender-device";
+const senderUserID = "sender-user";
+const recipientDeviceID = "recipient-device";
+const recipientUserID = "recipient-user";
+
+const recipientDevice: Device = {
+    deleted: false,
+    deviceID: recipientDeviceID,
+    lastLogin: new Date(0).toISOString(),
+    name: "recipient",
+    owner: recipientUserID,
+    signKey: "recipient-sign-key",
+};
+
+function makeDb(device: Device | null = recipientDevice) {
+    return {
+        retrieveDevice: vi.fn(() => Promise.resolve(device)),
+    };
+}
+
+function makeMail(overrides: Partial<MailWS> = {}): MailWS {
+    return {
+        authorID: senderUserID,
+        cipher: new Uint8Array([1, 2, 3]),
+        extra: new Uint8Array([4, 5, 6]),
+        forward: false,
+        group: null,
+        mailID: "mail-id",
+        mailType: MailType.initial,
+        nonce: new Uint8Array([7, 8, 9]),
+        readerID: recipientUserID,
+        recipient: recipientDeviceID,
+        sender: senderDeviceID,
+        ...overrides,
+    };
+}
+
+describe("validateMailIngress", () => {
+    it("accepts mail bound to the authenticated sender and recipient owner", async () => {
+        const db = makeDb();
+
+        await expect(
+            validateMailIngress(db, makeMail(), senderDeviceID, senderUserID),
+        ).resolves.toEqual({ recipientDevice });
+        expect(db.retrieveDevice).toHaveBeenCalledWith(recipientDeviceID);
+    });
+
+    it("rejects sender spoofing before looking up the recipient", async () => {
+        const db = makeDb();
+
+        await expect(
+            validateMailIngress(
+                db,
+                makeMail({ sender: "other-device" }),
+                senderDeviceID,
+                senderUserID,
+            ),
+        ).rejects.toMatchObject({
+            message: "Mail sender does not match the authenticated device.",
+            status: 403,
+        });
+        expect(db.retrieveDevice).not.toHaveBeenCalled();
+    });
+
+    it("rejects author spoofing before looking up the recipient", async () => {
+        const db = makeDb();
+
+        await expect(
+            validateMailIngress(
+                db,
+                makeMail({ authorID: "other-user" }),
+                senderDeviceID,
+                senderUserID,
+            ),
+        ).rejects.toMatchObject({
+            message: "Mail author does not match the authenticated user.",
+            status: 403,
+        });
+        expect(db.retrieveDevice).not.toHaveBeenCalled();
+    });
+
+    it("rejects mail to a missing or deleted recipient device", async () => {
+        const db = makeDb(null);
+
+        await expect(
+            validateMailIngress(db, makeMail(), senderDeviceID, senderUserID),
+        ).rejects.toMatchObject({
+            message: "No associated user record found for recipient device.",
+            status: 400,
+        });
+    });
+
+    it("rejects reader spoofing against the recipient device owner", async () => {
+        const db = makeDb();
+
+        await expect(
+            validateMailIngress(
+                db,
+                makeMail({ readerID: "other-reader" }),
+                senderDeviceID,
+                senderUserID,
+            ),
+        ).rejects.toMatchObject({
+            message: "Mail reader does not match the recipient device owner.",
+            status: 400,
+        });
+    });
+});

package/src/__tests__/mailRetention.spec.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+    DEFAULT_SERVER_MAIL_RETENTION_DAYS,
+    serverMailRetentionCutoffIso,
+    serverMailRetentionMs,
+} from "../mailRetention.ts";
+
+const MS_PER_DAY = 86_400_000;
+const MS_PER_HOUR = 3_600_000;
+
+describe("server mail retention config", () => {
+    afterEach(() => {
+        delete process.env["SPIRE_MAIL_RETENTION_DAYS"];
+        delete process.env["SPIRE_MAIL_RETENTION_TTL"];
+    });
+
+    it("defaults to thirty days", () => {
+        expect(serverMailRetentionMs()).toBe(
+            DEFAULT_SERVER_MAIL_RETENTION_DAYS * MS_PER_DAY,
+        );
+    });
+
+    it("accepts duration strings from SPIRE_MAIL_RETENTION_TTL", () => {
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "6h";
+
+        expect(serverMailRetentionMs()).toBe(6 * MS_PER_HOUR);
+    });
+
+    it("accepts day-count compatibility config", () => {
+        process.env["SPIRE_MAIL_RETENTION_DAYS"] = "7";
+
+        expect(serverMailRetentionMs()).toBe(7 * MS_PER_DAY);
+    });
+
+    it("prefers TTL config over day-count compatibility config", () => {
+        process.env["SPIRE_MAIL_RETENTION_DAYS"] = "7";
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "24h";
+
+        expect(serverMailRetentionMs()).toBe(MS_PER_DAY);
+    });
+
+    it("clamps invalid and unsafe values to safe bounds", () => {
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "not-a-duration";
+        expect(serverMailRetentionMs()).toBe(
+            DEFAULT_SERVER_MAIL_RETENTION_DAYS * MS_PER_DAY,
+        );
+
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "1m";
+        expect(serverMailRetentionMs()).toBe(MS_PER_HOUR);
+
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "999d";
+        expect(serverMailRetentionMs()).toBe(365 * MS_PER_DAY);
+    });
+
+    it("uses the configured retention when building the cutoff", () => {
+        process.env["SPIRE_MAIL_RETENTION_TTL"] = "24h";
+        const now = Date.parse("2026-05-07T12:00:00.000Z");
+
+        expect(serverMailRetentionCutoffIso(now)).toBe(
+            "2026-05-06T12:00:00.000Z",
+        );
+    });
+});

package/src/__tests__/notifyFanout.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import type { ClientManager } from "../ClientManager.ts";
+import type { BaseMsg } from "@vex-chat/types";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { Spire } from "../Spire.ts";
+
+interface FakeClient {
+    getDeviceID: () => null | string;
+    getUserID: () => null | string;
+    hasFailed: () => boolean;
+    send: (msg: BaseMsg) => void;
+}
+
+type NotifyFn = (
+    userID: string,
+    event: string,
+    transmissionID: string,
+    data?: unknown,
+    deviceID?: string,
+) => void;
+
+function createSpireHarness(clients: FakeClient[]) {
+    const spire = Object.create(Spire.prototype) as {
+        clients: ClientManager[];
+        notify: NotifyFn;
+    };
+    spire.clients = clients as unknown as ClientManager[];
+    return spire;
+}
+
+function fakeClient(overrides: Partial<FakeClient> = {}): FakeClient {
+    return {
+        getDeviceID: vi.fn(() => "device-a"),
+        getUserID: vi.fn(() => "user-a"),
+        hasFailed: vi.fn(() => false),
+        send: vi.fn(),
+        ...overrides,
+    };
+}
+
+describe("Spire notify fanout", () => {
+    it("continues device fanout after pruning a stale client", () => {
+        const stale = fakeClient({
+            getDeviceID: vi.fn(() => null),
+        });
+        const recipient = fakeClient({
+            getDeviceID: vi.fn(() => "device-b"),
+        });
+        const other = fakeClient({
+            getDeviceID: vi.fn(() => "device-c"),
+        });
+        const spire = createSpireHarness([stale, recipient, other]);
+
+        spire.notify(
+            "user-b",
+            "mail",
+            "00000000-0000-0000-0000-000000000001",
+            null,
+            "device-b",
+        );
+
+        expect(recipient.send).toHaveBeenCalledTimes(1);
+        expect(other.send).not.toHaveBeenCalled();
+        expect(spire.clients).toEqual([recipient, other]);
+    });
+
+    it("continues user fanout after a client inspection throws", () => {
+        const broken = fakeClient({
+            getUserID: vi.fn(() => {
+                throw new Error("stale client");
+            }),
+        });
+        const recipient = fakeClient({
+            getUserID: vi.fn(() => "user-b"),
+        });
+        const other = fakeClient({
+            getUserID: vi.fn(() => "user-c"),
+        });
+        const spire = createSpireHarness([broken, recipient, other]);
+
+        spire.notify(
+            "user-b",
+            "device_pending_enrollment",
+            "00000000-0000-0000-0000-000000000002",
+        );
+
+        expect(recipient.send).toHaveBeenCalledTimes(1);
+        expect(other.send).not.toHaveBeenCalled();
+        expect(spire.clients).toEqual([recipient, other]);
+    });
+});

package/src/mailRetention.ts

@@ -4,10 +4,15 @@
  * Commercial licenses available at vex.wtf
  */
 
-/** Minimum time the server keeps undelivered mail rows (hard cap). */
-export const SERVER_MAIL_RETENTION_DAYS = 30;
+import parseDuration from "parse-duration";
+
+export const DEFAULT_SERVER_MAIL_RETENTION_DAYS = 30;
 
 const MS_PER_DAY = 86_400_000;
+const DEFAULT_SERVER_MAIL_RETENTION_MS =
+    DEFAULT_SERVER_MAIL_RETENTION_DAYS * MS_PER_DAY;
+const MIN_SERVER_MAIL_RETENTION_MS = 60 * 60 * 1000;
+const MAX_SERVER_MAIL_RETENTION_MS = 365 * MS_PER_DAY;
 
 /**
  * ISO-8601 cutoff: mail with `time` strictly before this must not be retained
@@ -16,7 +21,33 @@ const MS_PER_DAY = 86_400_000;
 export function serverMailRetentionCutoffIso(
     nowMs: number = Date.now(),
 ): string {
-    return new Date(
-        nowMs - SERVER_MAIL_RETENTION_DAYS * MS_PER_DAY,
-    ).toISOString();
+    return new Date(nowMs - serverMailRetentionMs()).toISOString();
+}
+
+export function serverMailRetentionMs(): number {
+    const ttl = process.env["SPIRE_MAIL_RETENTION_TTL"]?.trim();
+    if (ttl) {
+        const parsed = parseDuration(ttl, "ms");
+        return clampRetentionMs(parsed);
+    }
+
+    const days = process.env["SPIRE_MAIL_RETENTION_DAYS"]?.trim();
+    if (days) {
+        const parsed = Number(days);
+        return clampRetentionMs(
+            Number.isFinite(parsed) ? parsed * MS_PER_DAY : undefined,
+        );
+    }
+
+    return DEFAULT_SERVER_MAIL_RETENTION_MS;
+}
+
+function clampRetentionMs(value: null | number | undefined): number {
+    if (!Number.isFinite(value) || value === undefined || value === null) {
+        return DEFAULT_SERVER_MAIL_RETENTION_MS;
+    }
+    return Math.min(
+        MAX_SERVER_MAIL_RETENTION_MS,
+        Math.max(MIN_SERVER_MAIL_RETENTION_MS, Math.floor(value)),
+    );
 }

package/src/server/index.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Database } from "../Database.ts";
-import type { Emoji } from "@vex-chat/types";
+import type { Device, Emoji } from "@vex-chat/types";
 
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
@@ -42,7 +42,7 @@ import {
     hasPermission,
     userHasPermission,
 } from "./permissions.ts";
-import { globalLimiter } from "./rateLimit.ts";
+import { globalLimiter, keyBundleLimiter } from "./rateLimit.ts";
 import { getUserRouter } from "./user.ts";
 import { censorUser, getParam, getUser } from "./utils.ts";
 import { getWellKnownRouter } from "./wellKnown.ts";
@@ -147,21 +147,45 @@ const checkAuth: express.RequestHandler = (req, _res, next) => {
     next();
 };
 
-const checkDevice: express.RequestHandler = (req, _res, next) => {
-    const token = req.headers["x-device-token"];
-    if (typeof token === "string" && token) {
-        try {
-            const result = jwt.verify(token, getJwtSecret());
-            const parsed = jwtDevicePayload.safeParse(result);
-            if (parsed.success) {
-                req.device = parsed.data.device;
+export function createCheckDevice(
+    db: Pick<Database, "retrieveDevice">,
+): express.RequestHandler {
+    return async (req, _res, next) => {
+        const token = req.headers["x-device-token"];
+        if (typeof token === "string" && token) {
+            try {
+                const result = jwt.verify(token, getJwtSecret());
+                const parsed = jwtDevicePayload.safeParse(result);
+                if (parsed.success) {
+                    const device = await currentTokenDevice(
+                        db,
+                        parsed.data.device,
+                    );
+                    if (
+                        device &&
+                        (!req.user || device.owner === req.user.userID)
+                    ) {
+                        req.device = device;
+                    }
+                }
+            } catch {
+                // Device token verification/revalidation failed — continue without device.
             }
-        } catch {
-            // Device token verification failed — continue without device
         }
+        next();
+    };
+}
+
+async function currentTokenDevice(
+    db: Pick<Database, "retrieveDevice">,
+    tokenDevice: Device,
+): Promise<Device | null> {
+    const device = await db.retrieveDevice(tokenDevice.deviceID);
+    if (!device || device.signKey !== tokenDevice.signKey) {
+        return null;
     }
-    next();
-};
+    return device;
+}
 
 export const protect: express.RequestHandler = (req, res, next) => {
     if (!req.user) {
@@ -282,7 +306,7 @@ export const initApp = (
     api.use(helmet());
     api.use(msgpackParser);
     api.use(checkAuth);
-    api.use(checkDevice);
+    api.use(createCheckDevice(db));
 
     api.get("/server/:id", protect, async (req, res) => {
         const server = await db.retrieveServer(getParam(req, "id"));
@@ -596,18 +620,23 @@ export const initApp = (
         }
     });
 
-    api.post("/device/:id/keyBundle", protect, async (req, res) => {
-        try {
-            const keyBundle = await db.getKeyBundle(getParam(req, "id"));
-            if (keyBundle) {
-                res.send(msgpack.encode(keyBundle));
-            } else {
-                res.sendStatus(404);
+    api.post(
+        "/device/:id/keyBundle",
+        protect,
+        keyBundleLimiter,
+        async (req, res) => {
+            try {
+                const keyBundle = await db.getKeyBundle(getParam(req, "id"));
+                if (keyBundle) {
+                    res.send(msgpack.encode(keyBundle));
+                } else {
+                    res.sendStatus(404);
+                }
+            } catch {
+                res.sendStatus(500);
             }
-        } catch {
-            res.sendStatus(500);
-        }
-    });
+        },
+    );
 
     api.post("/device/:id/mail", protect, async (req, res) => {
         const deviceDetails = req.device;