@vex-chat/spire 2.0.0 → 2.1.0

package/src/Database.ts

@@ -152,6 +152,11 @@ export interface SaveNotificationSubscriptionInput {
     userID: string;
 }
 
+interface DevicePasskeyApprovalInput {
+    approvedByDeviceID?: null | string;
+    approvedByPasskeyID: string;
+}
+
 export class Database extends EventEmitter {
     private static readonly EMOJI_LIST_CACHE_TTL_MS = 10_000;
 
@@ -226,18 +231,18 @@ export class Database extends EventEmitter {
     public async createDevice(
         owner: string,
         payload: DevicePayload,
+        passkeyApproval?: DevicePasskeyApprovalInput,
     ): Promise<Device> {
+        const now = new Date().toISOString();
         const device = {
             deleted: 0,
             deviceID: crypto.randomUUID(),
-            lastLogin: new Date().toISOString(),
+            lastLogin: now,
             name: payload.deviceName,
             owner,
             signKey: payload.signKey,
         };
 
-        await this.db.insertInto("devices").values(device).execute();
-
         const medPreKeys = {
             deviceID: device.deviceID,
             index: payload.preKeyIndex,
@@ -247,7 +252,34 @@ export class Database extends EventEmitter {
             userID: owner,
         };
 
-        await this.db.insertInto("preKeys").values(medPreKeys).execute();
+        await this.db.transaction().execute(async (trx) => {
+            await trx.insertInto("devices").values(device).execute();
+            await trx.insertInto("preKeys").values(medPreKeys).execute();
+            if (passkeyApproval) {
+                await trx
+                    .insertInto("device_passkey_approvals")
+                    .values({
+                        approvedAt: now,
+                        approvedByDeviceID:
+                            passkeyApproval.approvedByDeviceID ?? null,
+                        approvedByPasskeyID:
+                            passkeyApproval.approvedByPasskeyID,
+                        deviceID: device.deviceID,
+                        userID: owner,
+                    })
+                    .onConflict((oc) =>
+                        oc.column("deviceID").doUpdateSet({
+                            approvedAt: now,
+                            approvedByDeviceID:
+                                passkeyApproval.approvedByDeviceID ?? null,
+                            approvedByPasskeyID:
+                                passkeyApproval.approvedByPasskeyID,
+                            userID: owner,
+                        }),
+                    )
+                    .execute();
+            }
+        });
 
         return toDevice(device);
     }
@@ -446,6 +478,11 @@ export class Database extends EventEmitter {
             .where("deviceID", "=", deviceID)
             .execute();
 
+        await this.db
+            .deleteFrom("device_passkey_approvals")
+            .where("deviceID", "=", deviceID)
+            .execute();
+
         await this.db
             .updateTable("devices")
             .set({ deleted: 1 })
@@ -697,6 +734,20 @@ export class Database extends EventEmitter {
             .execute();
     }
 
+    public async isDevicePasskeyApproved(
+        userID: string,
+        deviceID: string,
+    ): Promise<boolean> {
+        const row = await this.db
+            .selectFrom("device_passkey_approvals")
+            .select("deviceID")
+            .where("userID", "=", userID)
+            .where("deviceID", "=", deviceID)
+            .limit(1)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+
     public async isHealthy(): Promise<boolean> {
         try {
             await sql`select 1 as ok`.execute(this.db);
@@ -755,11 +806,13 @@ export class Database extends EventEmitter {
     public async recoverDevice(
         owner: string,
         payload: DevicePayload,
+        passkeyApproval?: DevicePasskeyApprovalInput,
     ): Promise<{ device: Device; revokedDeviceIDs: string[] }> {
+        const now = new Date().toISOString();
         const device = {
             deleted: 0,
             deviceID: crypto.randomUUID(),
-            lastLogin: new Date().toISOString(),
+            lastLogin: now,
             name: payload.deviceName,
             owner,
             signKey: payload.signKey,
@@ -784,6 +837,30 @@ export class Database extends EventEmitter {
 
             await trx.insertInto("devices").values(device).execute();
             await trx.insertInto("preKeys").values(medPreKeys).execute();
+            if (passkeyApproval) {
+                await trx
+                    .insertInto("device_passkey_approvals")
+                    .values({
+                        approvedAt: now,
+                        approvedByDeviceID:
+                            passkeyApproval.approvedByDeviceID ?? null,
+                        approvedByPasskeyID:
+                            passkeyApproval.approvedByPasskeyID,
+                        deviceID: device.deviceID,
+                        userID: owner,
+                    })
+                    .onConflict((oc) =>
+                        oc.column("deviceID").doUpdateSet({
+                            approvedAt: now,
+                            approvedByDeviceID:
+                                passkeyApproval.approvedByDeviceID ?? null,
+                            approvedByPasskeyID:
+                                passkeyApproval.approvedByPasskeyID,
+                            userID: owner,
+                        }),
+                    )
+                    .execute();
+            }
 
             if (revokedDeviceIDs.length > 0) {
                 await trx
@@ -798,6 +875,10 @@ export class Database extends EventEmitter {
                     .deleteFrom("notification_subscriptions")
                     .where("deviceID", "in", revokedDeviceIDs)
                     .execute();
+                await trx
+                    .deleteFrom("device_passkey_approvals")
+                    .where("deviceID", "in", revokedDeviceIDs)
+                    .execute();
                 await trx
                     .updateTable("devices")
                     .set({ deleted: 1 })

package/src/NotificationService.ts

@@ -474,13 +474,12 @@ function expoMessageForSubscription(
                 : undefined,
         data,
         priority: subscription.platform === "android" ? "high" : undefined,
-        // Do not set `sound: "default"` here. Current mobile native
-        // notification modules can treat it as a custom sound resource named
-        // "default" instead of the platform default, which causes warnings when
-        // no such bundled resource exists.
         title,
         to: subscription.token,
     };
+    if (subscription.platform === "ios") {
+        message["sound"] = "default";
+    }
     if (body) {
         message["body"] = body;
     }

package/src/Spire.ts

@@ -51,6 +51,7 @@ import {
     MailIngressValidationError,
     validateMailIngress,
 } from "./server/mailIngress.ts";
+import { passkeySecondFactorError } from "./server/passkeySecondFactor.ts";
 import { authLimiter, devApiKeySkipsRateLimits } from "./server/rateLimit.ts";
 import { createPendingDeviceEnrollmentRequest } from "./server/user.ts";
 import { censorUser, getParam, getUser } from "./server/utils.ts";
@@ -59,6 +60,8 @@ import { getJwtSecret } from "./utils/jwtSecret.ts";
 import { msgpack } from "./utils/msgpack.ts";
 import { spireXSignOpenAsync } from "./utils/spireXSignOpenAsync.ts";
 
+export { passkeySecondFactorError } from "./server/passkeySecondFactor.ts";
+
 // expiry of regkeys = 24hr
 export const TOKEN_EXPIRY = 1000 * 60 * 10;
 export const JWT_EXPIRY = "7d";
@@ -127,26 +130,6 @@ interface ValidatedMailBatchEntry {
     recipientDevice: Device;
 }
 
-export async function passkeySecondFactorError(
-    db: Database,
-    userID: string,
-    passkeyID: string | undefined,
-    mismatchError: string,
-): Promise<null | string> {
-    const passkeys = await db.retrievePasskeysByUser(userID);
-    if (passkeys.length === 0) {
-        return null;
-    }
-    if (!passkeyID) {
-        return "Passkey verification required.";
-    }
-    const passkey = await db.retrievePasskeyInternal(passkeyID);
-    if (!passkey || passkey.userID !== userID) {
-        return mismatchError;
-    }
-    return null;
-}
-
 const notificationSubscribePayload = z.object({
     channel: z.literal("expo"),
     events: z.array(z.string().min(1)).default(["mail"]),
@@ -813,6 +796,7 @@ export class Spire extends EventEmitter {
                     user.userID,
                     req.passkey?.passkeyID,
                     "Passkey verification does not match this device.",
+                    { trustedDeviceID: device.deviceID },
                 );
                 if (passkeyError) {
                     const body: { error: string; username?: string } = {

package/src/__tests__/Database.spec.ts

@@ -171,7 +171,7 @@ describe("Database", () => {
 
     describe("recoverDevice", () => {
         it("creates a new device and revokes all previous devices for the user", async () => {
-            expect.assertions(8);
+            expect.assertions(9);
 
             const provider = new Database(options);
             await new Promise<void>((resolve, reject) => {
@@ -181,6 +181,7 @@ describe("Database", () => {
                             const oldA = await provider.createDevice(
                                 userID,
                                 devicePayload("old-a", "a".repeat(64)),
+                                { approvedByPasskeyID: "old-passkey" },
                             );
                             const oldB = await provider.createDevice(
                                 userID,
@@ -247,6 +248,12 @@ describe("Database", () => {
                                     },
                                 ),
                             ).toEqual([]);
+                            expect(
+                                await provider.isDevicePasskeyApproved(
+                                    userID,
+                                    oldA.deviceID,
+                                ),
+                            ).toBe(false);
                             await provider.close();
                             resolve();
                         } catch (e: unknown) {

package/src/__tests__/notifyFanout.spec.ts

@@ -517,12 +517,14 @@ describe("Spire notify fanout", () => {
             collapseId?: string;
             data?: Record<string, unknown>;
             priority?: string;
+            sound?: string;
             tag?: string;
             title?: string;
         }>;
         expect(messages[0]?.collapseId).toBe("vex-message-summary");
         expect(messages[0]?.channelId).toBe("vex-push-messages-v2");
         expect(messages[0]?.priority).toBe("high");
+        expect(messages[0]).not.toHaveProperty("sound");
         expect(messages[0]?.tag).toBe("vex-message-summary");
         expect(messages[0]?.title).toBe("New Message");
         expect(messages[0]).not.toHaveProperty("body");
@@ -533,6 +535,48 @@ describe("Spire notify fanout", () => {
         });
     });
 
+    it("requests the default sound for iOS visible Expo pushes only", async () => {
+        const iosSubscription: NotificationSubscription = {
+            ...subscription,
+            platform: "ios",
+            subscriptionID: "sub-ios",
+        };
+        const fetchMock = vi.fn().mockResolvedValueOnce({
+            json: () =>
+                Promise.resolve({
+                    data: [{ id: "receipt-a", status: "ok" }],
+                }),
+            ok: true,
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const { db } = createSpireHarness([], [iosSubscription]);
+        const service = new NotificationService(db, [], () => {});
+
+        await service["notifyPush"]({
+            deviceID: iosSubscription.deviceID,
+            event: "mail",
+            transmissionID: "00000000-0000-0000-0000-000000000016",
+            userID: iosSubscription.userID,
+        });
+
+        const init = fetchMock.mock.calls[0]?.[1] as
+            | undefined
+            | { body?: unknown };
+        const messages = JSON.parse(String(init?.body)) as Array<{
+            channelId?: string;
+            priority?: string;
+            sound?: string;
+            tag?: string;
+            title?: string;
+        }>;
+        expect(messages[0]?.sound).toBe("default");
+        expect(messages[0]).not.toHaveProperty("channelId");
+        expect(messages[0]).not.toHaveProperty("priority");
+        expect(messages[0]).not.toHaveProperty("tag");
+        expect(messages[0]?.title).toBe("New Message");
+    });
+
     it("awaits ticket error cleanup so rejection stays on notifyPush", async () => {
         const cleanupError = new Error("database unavailable");
         const removeNotificationSubscription = vi.fn(() =>

package/src/__tests__/passkeys.spec.ts

@@ -42,6 +42,17 @@ const samplePasskey = {
     transports: ["usb", "nfc"],
 };
 
+const sampleDevicePayload = {
+    deviceName: "iPhone",
+    preKey: "30c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+    preKeyIndex: 1,
+    preKeySignature:
+        "dd0665079426c3efcf4dce9b1487e4aca132f8147581b3294c3f23ddd2b4ba8240a10082bd06805d7eb320d91af971da3306e11b60073ccc3d829710f5036004000030c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+    signed: "00",
+    signKey: "a".repeat(64),
+    username: "alice",
+};
+
 async function withDb<T>(fn: (db: Database) => Promise<T>): Promise<T> {
     const provider = new Database(options);
     return new Promise<T>((resolve, reject) => {
@@ -235,6 +246,68 @@ describe("Database passkeys", () => {
                 ).resolves.toBeNull();
             });
         });
+
+        it("allows device-key auth for devices provisioned under passkey approval", async () => {
+            expect.assertions(3);
+            await withDb(async (db) => {
+                const created = await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+                const device = await db.createDevice(
+                    userID,
+                    sampleDevicePayload,
+                    { approvedByPasskeyID: created.passkeyID },
+                );
+
+                await expect(
+                    passkeySecondFactorError(db, userID, undefined, "mismatch"),
+                ).resolves.toBe("Passkey verification required.");
+                await expect(
+                    db.isDevicePasskeyApproved(userID, device.deviceID),
+                ).resolves.toBe(true);
+                await expect(
+                    passkeySecondFactorError(
+                        db,
+                        userID,
+                        undefined,
+                        "mismatch",
+                        { trustedDeviceID: device.deviceID },
+                    ),
+                ).resolves.toBeNull();
+            });
+        });
+
+        it("clears passkey approval trust when a device is deleted", async () => {
+            expect.assertions(2);
+            await withDb(async (db) => {
+                const created = await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+                const device = await db.createDevice(
+                    userID,
+                    sampleDevicePayload,
+                    { approvedByPasskeyID: created.passkeyID },
+                );
+
+                await expect(
+                    db.isDevicePasskeyApproved(userID, device.deviceID),
+                ).resolves.toBe(true);
+                await db.deleteDevice(device.deviceID);
+                await expect(
+                    db.isDevicePasskeyApproved(userID, device.deviceID),
+                ).resolves.toBe(false);
+            });
+        });
     });
 
     describe("deletePasskey", () => {

package/src/db/schema.ts

@@ -18,6 +18,16 @@ export interface ChannelsTable {
 
 export type ChannelUpdate = Updateable<ChannelsTable>;
 
+export type DevicePasskeyApprovalRow = Selectable<DevicePasskeyApprovalsTable>;
+
+export interface DevicePasskeyApprovalsTable {
+    approvedAt: string;
+    approvedByDeviceID: null | string;
+    approvedByPasskeyID: string;
+    deviceID: string;
+    userID: string;
+}
+
 export type DeviceRow = Selectable<DevicesTable>;
 
 export interface DevicesTable {
@@ -85,6 +95,7 @@ export type MailUpdate = Updateable<MailTable>;
 export type NewChannel = Insertable<ChannelsTable>;
 
 export type NewDevice = Insertable<DevicesTable>;
+export type NewDevicePasskeyApproval = Insertable<DevicePasskeyApprovalsTable>;
 export type NewEmoji = Insertable<EmojisTable>;
 export type NewFile = Insertable<FilesTable>;
 
@@ -167,6 +178,7 @@ export interface PreKeysTable {
 export type PreKeyUpdate = Updateable<PreKeysTable>;
 export interface ServerDatabase {
     channels: ChannelsTable;
+    device_passkey_approvals: DevicePasskeyApprovalsTable;
     devices: DevicesTable;
     emojis: EmojisTable;
     files: FilesTable;

package/src/migrations/2026-05-25_device-passkey-approvals.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 { Kysely } from "kysely";
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+    await db.schema.dropTable("device_passkey_approvals").ifExists().execute();
+}
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("device_passkey_approvals")
+        .ifNotExists()
+        .addColumn("deviceID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("approvedByPasskeyID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("approvedByDeviceID", "varchar(255)")
+        .addColumn("approvedAt", "text", (cb) => cb.notNull())
+        .execute();
+
+    await db.schema
+        .createIndex("device_passkey_approvals_user_idx")
+        .ifNotExists()
+        .on("device_passkey_approvals")
+        .columns(["userID", "deviceID"])
+        .execute();
+}

package/src/server/passkeyDevices.ts

@@ -106,12 +106,18 @@ export const getPasskeyDeviceRouter = (
                 res.sendStatus(401);
                 return;
             }
+            const passkeyID = req.passkey?.passkeyID;
+            if (!passkeyID) {
+                res.sendStatus(401);
+                return;
+            }
             // 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({
+                approvedByPasskeyID: passkeyID,
                 db,
                 notify,
                 requestID,

package/src/server/passkeySecondFactor.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { Database } from "../Database.ts";
+
+export async function passkeySecondFactorError(
+    db: Database,
+    userID: string,
+    passkeyID: string | undefined,
+    mismatchError: string,
+    options?: { trustedDeviceID?: string },
+): Promise<null | string> {
+    if (
+        options?.trustedDeviceID &&
+        (await db.isDevicePasskeyApproved(userID, options.trustedDeviceID))
+    ) {
+        return null;
+    }
+
+    const passkeys = await db.retrievePasskeysByUser(userID);
+    if (passkeys.length === 0) {
+        return null;
+    }
+    if (!passkeyID) {
+        return "Passkey verification required.";
+    }
+    const passkey = await db.retrievePasskeyInternal(passkeyID);
+    if (!passkey || passkey.userID !== userID) {
+        return mismatchError;
+    }
+    return null;
+}

package/src/server/user.ts

@@ -19,6 +19,7 @@ import { z } from "zod/v4";
 import { msgpack } from "../utils/msgpack.ts";
 import { spireXSignOpenAsync } from "../utils/spireXSignOpenAsync.ts";
 
+import { passkeySecondFactorError } from "./passkeySecondFactor.ts";
 import { censorUser, getParam, getUser } from "./utils.ts";
 
 import { protect } from "./index.ts";
@@ -127,6 +128,7 @@ export function createPendingDeviceEnrollmentRequest(
  * approving device's signature before invoking this helper.
  */
 export async function recoverDeviceEnrollmentRequest(args: {
+    approvedByPasskeyID?: string;
     db: Database;
     notify: (
         userID: string,
@@ -165,6 +167,9 @@ export async function recoverDeviceEnrollmentRequest(args: {
         const { device, revokedDeviceIDs } = await args.db.recoverDevice(
             args.userID,
             pending.devicePayload,
+            args.approvedByPasskeyID
+                ? { approvedByPasskeyID: args.approvedByPasskeyID }
+                : undefined,
         );
         pending.status = "approved";
         pending.approvedDeviceID = device.deviceID;
@@ -710,6 +715,17 @@ export const getUserRouter = (
                 return;
             }
 
+            const passkeyError = await passkeySecondFactorError(
+                db,
+                userID,
+                req.passkey?.passkeyID,
+                "Passkey verification does not match this account.",
+            );
+            if (passkeyError) {
+                res.status(403).send({ error: passkeyError });
+                return;
+            }
+
             const opened = await spireXSignOpenAsync(
                 XUtils.decodeHex(parsedApprove.data.signed),
                 XUtils.decodeHex(approverDevice.signKey),
@@ -732,6 +748,12 @@ export const getUserRouter = (
                 const device = await db.createDevice(
                     userID,
                     pending.devicePayload,
+                    req.passkey
+                        ? {
+                              approvedByDeviceID: approverDevice.deviceID,
+                              approvedByPasskeyID: req.passkey.passkeyID,
+                          }
+                        : undefined,
                 );
                 pending.status = "approved";
                 pending.approvedDeviceID = device.deviceID;

package/src/types/express.ts

@@ -25,7 +25,7 @@ declare global {
              * Set by `checkPasskey` middleware when the bearer token is
              * a passkey-scoped JWT. The presence of `req.passkey`
              * (without `req.device`) marks an admin-only request that
-             * may list/delete devices and approve enrollments, but
+             * may list/delete devices and recover/reject enrollments, but
              * cannot send mail or do anything device-specific.
              */
             passkey?: { passkeyID: string };