@vex-chat/spire 1.11.5 → 2.0.0

package/src/__tests__/Database.spec.ts

@@ -5,7 +5,7 @@
  */
 
 import type { SpireOptions } from "../Spire.ts";
-import type { MailWS, PreKeysWS } from "@vex-chat/types";
+import type { DevicePayload, MailWS, PreKeysWS } from "@vex-chat/types";
 
 import { XUtils } from "@vex-chat/crypto";
 import { MailType } from "@vex-chat/types";
@@ -64,6 +64,19 @@ describe("Database", () => {
         signature,
     };
 
+    const devicePayload = (
+        deviceName: string,
+        signKey: string,
+    ): DevicePayload => ({
+        deviceName,
+        preKey: testSQLPreKey.publicKey,
+        preKeyIndex: 1,
+        preKeySignature: testSQLPreKey.signature,
+        signed: "00",
+        signKey,
+        username: "alice",
+    });
+
     const options: SpireOptions = {
         dbType: "sqlite3mem",
     };
@@ -156,6 +169,100 @@ describe("Database", () => {
         });
     });
 
+    describe("recoverDevice", () => {
+        it("creates a new device and revokes all previous devices for the user", async () => {
+            expect.assertions(8);
+
+            const provider = new Database(options);
+            await new Promise<void>((resolve, reject) => {
+                provider.once("ready", () => {
+                    void (async () => {
+                        try {
+                            const oldA = await provider.createDevice(
+                                userID,
+                                devicePayload("old-a", "a".repeat(64)),
+                            );
+                            const oldB = await provider.createDevice(
+                                userID,
+                                devicePayload("old-b", "b".repeat(64)),
+                            );
+                            await provider.saveOTK(userID, oldA.deviceID, [
+                                {
+                                    deviceID: oldA.deviceID,
+                                    index: 1,
+                                    publicKey,
+                                    signature,
+                                },
+                            ]);
+                            await provider.saveNotificationSubscription({
+                                channel: "expo",
+                                deviceID: oldA.deviceID,
+                                events: ["deviceRequest"],
+                                platform: "ios",
+                                token: "ExponentPushToken[old-a]",
+                                userID,
+                            });
+                            await provider.saveNotificationSubscription({
+                                channel: "expo",
+                                deviceID: oldB.deviceID,
+                                events: ["*"],
+                                platform: "android",
+                                token: "ExponentPushToken[old-b]",
+                                userID,
+                            });
+
+                            const recovered = await provider.recoverDevice(
+                                userID,
+                                devicePayload("recovered", "c".repeat(64)),
+                            );
+
+                            expect(recovered.revokedDeviceIDs.sort()).toEqual(
+                                [oldA.deviceID, oldB.deviceID].sort(),
+                            );
+                            expect(
+                                await provider.retrieveDevice(oldA.deviceID),
+                            ).toBeNull();
+                            expect(
+                                await provider.retrieveDevice(oldB.deviceID),
+                            ).toBeNull();
+                            expect(
+                                await provider.retrieveDevice(
+                                    recovered.device.deviceID,
+                                ),
+                            ).toEqual(recovered.device);
+                            expect(
+                                await provider.retrieveUserDeviceList([userID]),
+                            ).toEqual([recovered.device]);
+                            expect(
+                                await provider.getPreKeys(oldA.deviceID),
+                            ).toBeNull();
+                            expect(
+                                await provider.getOTK(oldA.deviceID),
+                            ).toBeNull();
+                            expect(
+                                await provider.retrieveNotificationSubscriptions(
+                                    {
+                                        event: "deviceRequest",
+                                        userID,
+                                    },
+                                ),
+                            ).toEqual([]);
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            await provider.close().catch(() => {
+                                /* ignore cleanup failure */
+                            });
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+    });
+
     describe("retrieveMail", () => {
         it("returns queued mail in send order for logged-out batch drains", async () => {
             expect.assertions(1);
@@ -231,9 +338,80 @@ describe("Database", () => {
         });
     });
 
+    describe("saveMailBatch", () => {
+        it("stores multiple queued mail rows in one insert", 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,
+                                nonce: number,
+                            ): MailWS => ({
+                                authorID: userID,
+                                cipher: new Uint8Array([1, nonce]),
+                                extra: new Uint8Array([2, nonce]),
+                                forward: false,
+                                group: null,
+                                mailID,
+                                mailType: MailType.initial,
+                                nonce: new Uint8Array([3, nonce]),
+                                readerID: userID,
+                                recipient: deviceID,
+                                sender: "sender-a",
+                            });
+
+                            await provider.saveMailBatch([
+                                {
+                                    header: new Uint8Array([4, 1]),
+                                    mail: mail(
+                                        "00000000-0000-0000-0000-000000000011",
+                                        1,
+                                    ),
+                                    senderDeviceID: "sender-a",
+                                    userID,
+                                },
+                                {
+                                    header: new Uint8Array([4, 2]),
+                                    mail: mail(
+                                        "00000000-0000-0000-0000-000000000012",
+                                        2,
+                                    ),
+                                    senderDeviceID: "sender-a",
+                                    userID,
+                                },
+                            ]);
+
+                            const result =
+                                await provider.retrieveMail(deviceID);
+                            expect(
+                                result.map(
+                                    ([, body]: [Uint8Array, MailWS, string]) =>
+                                        body.mailID,
+                                ),
+                            ).toEqual([
+                                "00000000-0000-0000-0000-000000000011",
+                                "00000000-0000-0000-0000-000000000012",
+                            ]);
+                            await provider.close();
+                            resolve();
+                        } catch (e: unknown) {
+                            reject(
+                                e instanceof Error ? e : new Error(String(e)),
+                            );
+                        }
+                    })();
+                });
+            });
+        });
+    });
+
     describe("notification subscriptions", () => {
         it("upserts and filters Expo push subscriptions by event", async () => {
-            expect.assertions(7);
+            expect.assertions(8);
 
             const provider = new Database(options);
             await new Promise<void>((resolve, reject) => {
@@ -297,6 +475,17 @@ describe("Database", () => {
                                 );
                             expect(deviceSubsAfterUpdate).toHaveLength(1);
 
+                            await provider.deleteDevice(deviceID);
+                            expect(
+                                await provider.retrieveNotificationSubscriptions(
+                                    {
+                                        deviceID,
+                                        event: "deviceRequest",
+                                        userID,
+                                    },
+                                ),
+                            ).toEqual([]);
+
                             await provider.close();
                             resolve();
                         } catch (e: unknown) {

package/src/__tests__/loadEnv.spec.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 {
+    isSpireFipsEnabled,
+    normalizeEnvValue,
+    validateSpireRuntimeEnv,
+} from "../utils/loadEnv.ts";
+
+const TWEETNACL_SPK = "ab".repeat(64);
+const FIPS_SPK = "cd".repeat(90);
+const JWT_SECRET = "ef".repeat(32);
+
+describe("normalizeEnvValue", () => {
+    it("strips matching quotes from compose/dotenv values", () => {
+        expect(normalizeEnvValue(`"${TWEETNACL_SPK}"`)).toBe(TWEETNACL_SPK);
+        expect(normalizeEnvValue(`'${JWT_SECRET}'`)).toBe(JWT_SECRET);
+    });
+
+    it("trims whitespace without stripping unmatched quotes", () => {
+        expect(normalizeEnvValue(`  ${TWEETNACL_SPK}  `)).toBe(TWEETNACL_SPK);
+        expect(normalizeEnvValue(`"${TWEETNACL_SPK}`)).toBe(
+            `"${TWEETNACL_SPK}`,
+        );
+    });
+});
+
+describe("isSpireFipsEnabled", () => {
+    it("accepts true and 1 only", () => {
+        expect(isSpireFipsEnabled("true")).toBe(true);
+        expect(isSpireFipsEnabled('"true"')).toBe(true);
+        expect(isSpireFipsEnabled("1")).toBe(true);
+        expect(isSpireFipsEnabled("false")).toBe(false);
+        expect(isSpireFipsEnabled(undefined)).toBe(false);
+    });
+});
+
+describe("validateSpireRuntimeEnv", () => {
+    it("accepts quoted compose-safe tweetnacl keys", () => {
+        expect(() => {
+            validateSpireRuntimeEnv({
+                JWT_SECRET: `"${JWT_SECRET}"`,
+                SPIRE_FIPS: "false",
+                SPK: `"${TWEETNACL_SPK}"`,
+            });
+        }).not.toThrow();
+    });
+
+    it("rejects non-hex SPK values before crypto init", () => {
+        expect(() => {
+            validateSpireRuntimeEnv({
+                JWT_SECRET,
+                SPK: `"${TWEETNACL_SPK}`,
+            });
+        }).toThrow(/SPK must be an even-length hex string/);
+    });
+
+    it("rejects a FIPS flag with a tweetnacl-sized SPK", () => {
+        expect(() => {
+            validateSpireRuntimeEnv({
+                JWT_SECRET,
+                SPIRE_FIPS: "true",
+                SPK: TWEETNACL_SPK,
+            });
+        }).toThrow(/requires an SPK from .*gen-spk-fips/);
+    });
+
+    it("rejects a FIPS-sized SPK without the FIPS flag", () => {
+        expect(() => {
+            validateSpireRuntimeEnv({
+                JWT_SECRET,
+                SPIRE_FIPS: "false",
+                SPK: FIPS_SPK,
+            });
+        }).toThrow(/SPK must be 128 hex characters/);
+    });
+
+    it("rejects reusing SPK as JWT_SECRET", () => {
+        expect(() => {
+            validateSpireRuntimeEnv({
+                JWT_SECRET: TWEETNACL_SPK,
+                SPK: TWEETNACL_SPK,
+            });
+        }).toThrow(/JWT_SECRET must be separate from SPK/);
+    });
+});

package/src/__tests__/passkeys.spec.ts

@@ -9,6 +9,7 @@ import type { SpireOptions } from "../Spire.ts";
 import { describe, expect, it, vi } from "vitest";
 
 import { Database } from "../Database.ts";
+import { passkeySecondFactorError } from "../Spire.ts";
 
 vi.mock("uuid", () => ({
     parse: (s: string) => {
@@ -191,6 +192,51 @@ describe("Database passkeys", () => {
         });
     });
 
+    describe("passkeySecondFactorError", () => {
+        it("allows bootstrap login when the account has no passkeys", async () => {
+            expect.assertions(1);
+            await withDb(async (db) => {
+                await expect(
+                    passkeySecondFactorError(db, userID, undefined, "mismatch"),
+                ).resolves.toBeNull();
+            });
+        });
+
+        it("requires a matching passkey once the account has one", async () => {
+            expect.assertions(3);
+            await withDb(async (db) => {
+                const created = await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+
+                await expect(
+                    passkeySecondFactorError(db, userID, undefined, "mismatch"),
+                ).resolves.toBe("Passkey verification required.");
+                await expect(
+                    passkeySecondFactorError(
+                        db,
+                        userID,
+                        "not-this-passkey",
+                        "mismatch",
+                    ),
+                ).resolves.toBe("mismatch");
+                await expect(
+                    passkeySecondFactorError(
+                        db,
+                        userID,
+                        created.passkeyID,
+                        "mismatch",
+                    ),
+                ).resolves.toBeNull();
+            });
+        });
+    });
+
     describe("deletePasskey", () => {
         it("removes the passkey row", async () => {
             expect.assertions(2);

package/src/__tests__/rateLimit.spec.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 {
+    DEV_API_KEY_HEADER,
+    devApiKeyMatches,
+    devApiKeySkipsRateLimits,
+} from "../server/rateLimit.ts";
+
+const ORIGINAL_DEV_API_KEY = process.env["DEV_API_KEY"];
+const ORIGINAL_DISABLE_RATE_LIMITS = process.env["SPIRE_DISABLE_RATE_LIMITS"];
+
+function requestWithDevKey(value: string | undefined) {
+    return {
+        get(name: string): string | undefined {
+            return name.toLowerCase() === DEV_API_KEY_HEADER
+                ? value
+                : undefined;
+        },
+    };
+}
+
+describe("dev API key matching", () => {
+    afterEach(() => {
+        if (ORIGINAL_DEV_API_KEY === undefined) {
+            delete process.env["DEV_API_KEY"];
+        } else {
+            process.env["DEV_API_KEY"] = ORIGINAL_DEV_API_KEY;
+        }
+
+        if (ORIGINAL_DISABLE_RATE_LIMITS === undefined) {
+            delete process.env["SPIRE_DISABLE_RATE_LIMITS"];
+        } else {
+            process.env["SPIRE_DISABLE_RATE_LIMITS"] =
+                ORIGINAL_DISABLE_RATE_LIMITS;
+        }
+    });
+
+    it("matches the configured dev API key exactly", () => {
+        process.env["DEV_API_KEY"] = "test-secret";
+
+        expect(devApiKeyMatches(requestWithDevKey("test-secret"))).toBe(true);
+        expect(devApiKeyMatches(requestWithDevKey("wrong-secret"))).toBe(false);
+        expect(devApiKeyMatches(requestWithDevKey(undefined))).toBe(false);
+    });
+
+    it("does not treat disabled rate limits as a dev API key match", () => {
+        delete process.env["DEV_API_KEY"];
+        process.env["SPIRE_DISABLE_RATE_LIMITS"] = "1";
+
+        const req = requestWithDevKey(undefined);
+        expect(devApiKeyMatches(req)).toBe(false);
+        expect(devApiKeySkipsRateLimits(req)).toBe(true);
+    });
+});

package/src/migrations/2026-05-03_passkeys.ts

@@ -13,8 +13,8 @@ export async function down(db: Kysely<unknown>): Promise<void> {
 // Passkeys are an administrative second-class credential alongside
 // `devices`. They cannot send/decrypt mail (no ratchet keys), but they
 // can authenticate the owning user, list devices, delete devices, and
-// approve/reject pending device-enrollment requests — i.e. account
-// recovery and provisioning.
+// recover/reject pending device-enrollment requests — i.e. account
+// recovery without additive passkey-only provisioning.
 //
 // `credentialID` is the WebAuthn credential id (base64url, opaque), and
 // is unique across all passkeys. `publicKey` is the COSE_Key bytes

package/src/server/index.ts

@@ -42,7 +42,11 @@ import {
     hasPermission,
     userHasPermission,
 } from "./permissions.ts";
-import { globalLimiter, keyBundleLimiter } from "./rateLimit.ts";
+import {
+    devApiKeyMatches,
+    globalLimiter,
+    keyBundleLimiter,
+} from "./rateLimit.ts";
 import { getUserRouter } from "./user.ts";
 import { censorUser, getParam, getUser } from "./utils.ts";
 import { getWellKnownRouter } from "./wellKnown.ts";
@@ -200,7 +204,7 @@ export const protect: express.RequestHandler = (req, res, next) => {
  * Restrict a route to passkey-scoped JWTs (used by the parallel
  * `/user/:id/passkey/devices/...` admin/recovery routes). A
  * passkey-authenticated caller can list devices, delete devices, and
- * approve/reject pending enrollments — and nothing else.
+ * recover or reject pending enrollments — and nothing else.
  */
 export const protectPasskey: express.RequestHandler = (req, res, next) => {
     if (!req.user || !req.passkey) {
@@ -243,6 +247,7 @@ export const initApp = (
         data?: unknown,
         deviceID?: string,
     ) => void,
+    disconnectDevices?: (deviceIDs: string[]) => void,
 ) => {
     // INIT ROUTERS
     const userRouter = getUserRouter(db, tokenValidator, notify);
@@ -250,7 +255,11 @@ export const initApp = (
     const avatarRouter = getAvatarRouter();
     const inviteRouter = getInviteRouter(db, tokenValidator, notify);
     const passkeyRouter = getPasskeyRouter(db);
-    const passkeyDeviceRouter = getPasskeyDeviceRouter(db, notify);
+    const passkeyDeviceRouter = getPasskeyDeviceRouter(
+        db,
+        notify,
+        disconnectDevices,
+    );
 
     // MIDDLEWARE
 
@@ -663,6 +672,20 @@ export const initApp = (
             res.sendStatus(404);
             return;
         }
+        if (req.user?.userID !== device.owner) {
+            res.sendStatus(401);
+            return;
+        }
+        const passkeys = await db.retrievePasskeysByUser(device.owner);
+        // The CLI stress harness cannot perform a WebAuthn ceremony.
+        // Keep normal clients gated, but let the existing dev/load-test key
+        // exercise device connect on disposable accounts.
+        if (passkeys.length === 0 && !devApiKeyMatches(req)) {
+            res.status(403).send({
+                error: "A passkey must be registered before this device can connect.",
+            });
+            return;
+        }
 
         const regKey = await spireXSignOpenAsync(
             signed,

package/src/server/passkey.ts

@@ -192,17 +192,6 @@ export const getPasskeyRouter = (db: Database) => {
                 res.sendStatus(401);
                 return;
             }
-            // Passwords/passkey JWTs both come through `protect`; only
-            // a real device session may add a passkey to keep the
-            // recovery story symmetric with device delete (a passkey
-            // can't bootstrap another passkey).
-            if (!req.device) {
-                res.status(401).send({
-                    error: "Adding a passkey requires an authenticated device.",
-                });
-                return;
-            }
-
             const parsed = PasskeyRegistrationStartPayloadSchema.safeParse(
                 req.body,
             );
@@ -215,6 +204,16 @@ export const getPasskeyRouter = (db: Database) => {
             }
 
             const existing = await db.retrievePasskeysByUser(userID);
+            // A freshly registered account has a bearer token but cannot
+            // get a device token until its first passkey exists. Allow
+            // exactly that bootstrap case; every later passkey addition
+            // must come from an authenticated device session.
+            if (!req.device && existing.length > 0) {
+                res.status(401).send({
+                    error: "Adding another passkey requires an authenticated device.",
+                });
+                return;
+            }
             if (existing.length >= MAX_PASSKEYS_PER_USER) {
                 res.status(409).send({
                     error: `Each account is limited to ${MAX_PASSKEYS_PER_USER} passkeys.`,
@@ -277,12 +276,6 @@ export const getPasskeyRouter = (db: Database) => {
                 res.sendStatus(401);
                 return;
             }
-            if (!req.device) {
-                res.status(401).send({
-                    error: "Adding a passkey requires an authenticated device.",
-                });
-                return;
-            }
 
             const parsed = PasskeyRegistrationFinishPayloadSchema.safeParse(
                 req.body,
@@ -295,6 +288,14 @@ export const getPasskeyRouter = (db: Database) => {
                 return;
             }
 
+            const existing = await db.retrievePasskeysByUser(userID);
+            if (!req.device && existing.length > 0) {
+                res.status(401).send({
+                    error: "Adding another passkey requires an authenticated device.",
+                });
+                return;
+            }
+
             pruneRegistrations();
             const pending = pendingRegistrations.get(parsed.data.requestID);
             if (!pending || pending.userID !== userID) {
@@ -409,6 +410,13 @@ export const getPasskeyRouter = (db: Database) => {
                 res.sendStatus(404);
                 return;
             }
+            const passkeys = await db.retrievePasskeysByUser(userID);
+            if (passkeys.length <= 1) {
+                res.status(400).send({
+                    error: "You can't delete your last passkey.",
+                });
+                return;
+            }
             await db.deletePasskey(passkeyID);
             res.sendStatus(200);
         },

package/src/server/passkeyDevices.ts

@@ -10,7 +10,10 @@ import express from "express";
 
 import { msgpack } from "../utils/msgpack.ts";
 
-import { resolveDeviceEnrollmentRequest } from "./user.ts";
+import {
+    recoverDeviceEnrollmentRequest,
+    resolveDeviceEnrollmentRequest,
+} from "./user.ts";
 import { getParam, getUser } from "./utils.ts";
 
 import { protectPasskey } from "./index.ts";
@@ -21,8 +24,8 @@ import { protectPasskey } from "./index.ts";
  *
  * - `GET    /user/:id/passkey/devices`                              — list
  * - `DELETE /user/:id/passkey/devices/:deviceID`                    — remove
- * - `POST   /user/:id/passkey/devices/requests/:requestID/approve`  — approve
  * - `POST   /user/:id/passkey/devices/requests/:requestID/reject`   — reject
+ * - `POST   /user/:id/passkey/recover/devices/requests/:requestID`  — recover
  *
  * The route family is parallel to `/user/:id/devices/...` so the
  * existing device-authenticated flow stays untouched (and there's no
@@ -42,6 +45,7 @@ export const getPasskeyDeviceRouter = (
         data?: unknown,
         deviceID?: string,
     ) => void,
+    disconnectDevices?: (deviceIDs: string[]) => void,
 ) => {
     const router = express.Router();
 
@@ -79,10 +83,9 @@ export const getPasskeyDeviceRouter = (
             // The device-auth `DELETE /user/:id/devices/:deviceID`
             // refuses to delete the user's last device (a device
             // can't lock itself out). Passkeys may delete the last
-            // device on purpose: that's the entire recovery story —
+            // device on purpose: that's part of the recovery story —
             // "I lost my phone, sign in with the passkey, wipe the
-            // old device, then enroll a new one with the passkey
-            // standing in as the approver."
+            // old device, then recover onto a new one."
             await db.deleteDevice(deviceID);
             // Tell whoever's online that the device-list shape
             // changed; clients use this to refresh the Settings →
@@ -93,7 +96,7 @@ export const getPasskeyDeviceRouter = (
     );
 
     router.post(
-        "/user/:id/passkey/devices/requests/:requestID/approve",
+        "/user/:id/passkey/recover/devices/requests/:requestID",
         protectPasskey,
         async (req, res) => {
             const userDetails = getUser(req);
@@ -103,20 +106,20 @@ export const getPasskeyDeviceRouter = (
                 res.sendStatus(401);
                 return;
             }
-            // No second-factor signature here: the passkey JWT itself
-            // is fresh proof of user presence (5 min TTL, freshly
-            // minted from a WebAuthn ceremony with userVerification).
-            // Reusing it within those 5 minutes to approve an
-            // enrollment is fine — the equivalent guarantee that the
-            // device flow gets from a per-request Ed25519 sig.
-            const result = await resolveDeviceEnrollmentRequest({
-                action: "approve",
+            // Recovery is intentionally the only passkey-backed
+            // provisioning path: it provisions the pending device and
+            // revokes every previously-active device for the account in
+            // one server-side operation. Clients cannot accidentally
+            // restore an account while leaving lost devices trusted.
+            const result = await recoverDeviceEnrollmentRequest({
                 db,
                 notify,
                 requestID,
                 userID,
             });
             if (result.kind === "ok") {
+                notify(userID, "deviceListChanged", crypto.randomUUID());
+                disconnectDevices?.(result.revokedDeviceIDs);
                 res.send(msgpack.encode(result.device));
                 return;
             }