@vex-chat/spire 1.11.4 → 2.0.0

package/src/__tests__/notifyFanout.spec.ts

@@ -36,11 +36,13 @@ function createSpireHarness(
     clients: FakeClient[],
     subscriptions: NotificationSubscription[] = [],
     removeNotificationSubscription = vi.fn(() => Promise.resolve(true)),
+    hasMail = vi.fn(() => Promise.resolve(true)),
 ) {
     const retrieveNotificationSubscriptions = vi.fn(() =>
         Promise.resolve(subscriptions),
     );
     const db = {
+        hasMail,
         removeNotificationSubscription,
         retrieveNotificationSubscriptions,
     } as unknown as Database;
@@ -53,6 +55,7 @@ function createSpireHarness(
     return {
         clients: managers,
         db,
+        hasMail,
         notifications,
         removeNotificationSubscription,
         retrieveNotificationSubscriptions,
@@ -199,6 +202,112 @@ describe("Spire notify fanout", () => {
         });
     });
 
+    it("skips Expo mail push when websocket delivery is acknowledged during the grace window", async () => {
+        vi.useFakeTimers();
+        const recipient = fakeClient({
+            getDeviceID: vi.fn(() => "device-b"),
+        });
+        const fetchMock = vi.fn();
+        const hasMail = vi.fn(() => Promise.resolve(false));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { notifications } = createSpireHarness(
+            [recipient],
+            [subscription],
+            undefined,
+            hasMail,
+        );
+        const mailNonce = new Uint8Array([1, 2, 3]);
+
+        notifications.notify({
+            deviceID: "device-b",
+            event: "mail",
+            mailNonce,
+            transmissionID: "00000000-0000-0000-0000-000000000010",
+            userID: "user-b",
+        });
+
+        expect(recipient.send).toHaveBeenCalledTimes(1);
+        expect(fetchMock).not.toHaveBeenCalled();
+
+        await vi.advanceTimersByTimeAsync(1500);
+
+        await vi.waitFor(() => {
+            expect(hasMail).toHaveBeenCalledWith(mailNonce, "device-b");
+        });
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it("sends Expo mail push after the grace window when websocket mail remains pending", async () => {
+        vi.useFakeTimers();
+        const recipient = fakeClient({
+            getDeviceID: vi.fn(() => "device-b"),
+        });
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        const hasMail = vi.fn(() => Promise.resolve(true));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { notifications } = createSpireHarness(
+            [recipient],
+            [subscription],
+            undefined,
+            hasMail,
+        );
+
+        notifications.notify({
+            deviceID: "device-b",
+            event: "mail",
+            mailNonce: new Uint8Array([4, 5, 6]),
+            transmissionID: "00000000-0000-0000-0000-000000000011",
+            userID: "user-b",
+        });
+
+        expect(fetchMock).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1500);
+
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    it("sends Expo mail push immediately when no websocket client was notified", async () => {
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        const hasMail = vi.fn(() => Promise.resolve(true));
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { notifications } = createSpireHarness(
+            [],
+            [subscription],
+            undefined,
+            hasMail,
+        );
+
+        notifications.notify({
+            deviceID: "device-b",
+            event: "mail",
+            mailNonce: new Uint8Array([7, 8, 9]),
+            transmissionID: "00000000-0000-0000-0000-000000000012",
+            userID: "user-b",
+        });
+
+        await vi.waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledTimes(1);
+        });
+        expect(hasMail).not.toHaveBeenCalled();
+    });
+
     it("checks Expo receipts and removes unregistered devices", async () => {
         vi.useFakeTimers();
         const fetchMock = vi

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;
             }

package/src/server/rateLimit.ts

@@ -13,16 +13,11 @@ import rateLimit, { ipKeyGenerator } from "express-rate-limit";
 /** HTTP header carrying the dev API key (must match {@link process.env.DEV_API_KEY}). */
 export const DEV_API_KEY_HEADER = "x-dev-api-key";
 
-/**
- * When `DEV_API_KEY` is set in the environment, any request whose
- * `x-dev-api-key` header matches (constant-time) skips all in-process rate
- * limiters. Dev / load-testing escape hatch only — never set in production.
- * (Future: first-class API keys with scopes may reuse this header name.)
- */
-export function devApiKeySkipsRateLimits(req: Request): boolean {
-    if (disableRateLimitsByEnv()) {
-        return true;
-    }
+interface HeaderReader {
+    get(name: string): string | undefined;
+}
+
+export function devApiKeyMatches(req: HeaderReader): boolean {
     const configured = process.env["DEV_API_KEY"]?.trim() ?? "";
     if (configured.length === 0) {
         return false;
@@ -41,6 +36,19 @@ export function devApiKeySkipsRateLimits(req: Request): boolean {
     }
 }
 
+/**
+ * When `DEV_API_KEY` is set in the environment, any request whose
+ * `x-dev-api-key` header matches (constant-time) skips all in-process rate
+ * limiters. Dev / load-testing escape hatch only — never set in production.
+ * (Future: first-class API keys with scopes may reuse this header name.)
+ */
+export function devApiKeySkipsRateLimits(req: HeaderReader): boolean {
+    if (disableRateLimitsByEnv()) {
+        return true;
+    }
+    return devApiKeyMatches(req);
+}
+
 function disableRateLimitsByEnv(): boolean {
     const raw = process.env["SPIRE_DISABLE_RATE_LIMITS"]?.trim().toLowerCase();
     return raw === "1" || raw === "true";

package/src/server/user.ts

@@ -126,6 +126,72 @@ export function createPendingDeviceEnrollmentRequest(
  * The device-auth caller is expected to have already verified the
  * approving device's signature before invoking this helper.
  */
+export async function recoverDeviceEnrollmentRequest(args: {
+    db: Database;
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void;
+    requestID: string;
+    userID: string;
+}): Promise<
+    | { device: Device; kind: "ok"; revokedDeviceIDs: string[] }
+    | { error: string; kind: "err"; status: number }
+> {
+    pruneDeviceEnrollmentRequests();
+    const pending = deviceEnrollments.get(args.requestID);
+    if (!pending || pending.userID !== args.userID) {
+        return { error: "Request not found.", kind: "err", status: 404 };
+    }
+    if (pending.status !== "pending") {
+        return {
+            error: "Request is not pending.",
+            kind: "err",
+            status: 409,
+        };
+    }
+    if (Date.now() - pending.createdAt > DEVICE_REQUEST_TTL_MS) {
+        pending.status = "expired";
+        pending.resolvedAt = Date.now();
+        pending.error = "Request expired.";
+        deviceEnrollments.set(args.requestID, pending);
+        return { error: "Request expired.", kind: "err", status: 410 };
+    }
+
+    try {
+        const { device, revokedDeviceIDs } = await args.db.recoverDevice(
+            args.userID,
+            pending.devicePayload,
+        );
+        pending.status = "approved";
+        pending.approvedDeviceID = device.deviceID;
+        pending.resolvedAt = Date.now();
+        deviceEnrollments.set(args.requestID, pending);
+        args.notify(args.userID, "deviceRequest", crypto.randomUUID(), {
+            requestID: args.requestID,
+            status: "approved",
+        });
+        return { device, kind: "ok", revokedDeviceIDs };
+    } catch {
+        pending.status = "rejected";
+        pending.error = "Could not recover device.";
+        pending.resolvedAt = Date.now();
+        deviceEnrollments.set(args.requestID, pending);
+        args.notify(args.userID, "deviceRequest", crypto.randomUUID(), {
+            requestID: args.requestID,
+            status: "rejected",
+        });
+        return {
+            error: "Could not recover device.",
+            kind: "err",
+            status: 470,
+        };
+    }
+}
+
 export async function resolveDeviceEnrollmentRequest(args: {
     action: "approve" | "reject";
     db: Database;