@vex-chat/spire 1.3.7 → 1.5.0

package/src/__tests__/passkeys.spec.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 { SpireOptions } from "../Spire.ts";
+
+import { describe, expect, it, vi } from "vitest";
+
+import { Database } from "../Database.ts";
+
+vi.mock("uuid", () => ({
+    parse: (s: string) => {
+        const matches = s.replace(/-/g, "").match(/.{2}/g);
+        if (!matches) throw new Error("Invalid UUID");
+        return Uint8Array.from(matches.map((b) => parseInt(b, 16)));
+    },
+    stringify: (b: Uint8Array) => {
+        const hex = Array.from(b)
+            .map((x) => x.toString(16).padStart(2, "0"))
+            .join("");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+    },
+    v4: vi.fn(() => "93ce482b-a0f2-4f6e-b1df-3aed61073552"),
+    validate: () => true,
+}));
+
+const options: SpireOptions = {
+    dbType: "sqlite3mem",
+};
+
+const userID = "4e67b90f-cbf8-44bc-8ce3-d3b248f033f1";
+
+const samplePasskey = {
+    algorithm: -7,
+    credentialID: "credential-id-base64url",
+    name: "Yubikey 5C",
+    publicKeyHex:
+        "30c2d0294c1cfdbb73c6b3bbe6010088c2dba8384b04ff2e2b92172431d66b5e",
+    transports: ["usb", "nfc"],
+};
+
+async function withDb<T>(fn: (db: Database) => Promise<T>): Promise<T> {
+    const provider = new Database(options);
+    return new Promise<T>((resolve, reject) => {
+        provider.once("ready", () => {
+            void (async () => {
+                try {
+                    const result = await fn(provider);
+                    await provider.close();
+                    resolve(result);
+                } catch (e: unknown) {
+                    await provider.close().catch(() => {
+                        // best-effort cleanup; ignore close failures here
+                        // so we surface the original error instead.
+                    });
+                    reject(e instanceof Error ? e : new Error(String(e)));
+                }
+            })();
+        });
+    });
+}
+
+describe("Database passkeys", () => {
+    describe("createPasskey", () => {
+        it("inserts a passkey and returns the public shape (no key material)", async () => {
+            expect.assertions(7);
+            await withDb(async (db) => {
+                const created = await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+
+                expect(created.userID).toBe(userID);
+                expect(created.name).toBe(samplePasskey.name);
+                expect(created.transports).toEqual(samplePasskey.transports);
+                expect(created.lastUsedAt).toBeNull();
+                expect(typeof created.passkeyID).toBe("string");
+                expect(created.passkeyID.length).toBeGreaterThan(0);
+                // Internal fields should NOT be on the public shape
+                expect(
+                    (created as unknown as Record<string, unknown>)[
+                        "publicKey"
+                    ],
+                ).toBeUndefined();
+            });
+        });
+    });
+
+    describe("retrievePasskeyByCredentialID", () => {
+        it("returns the row including key material when looked up by credentialID", async () => {
+            expect.assertions(4);
+            await withDb(async (db) => {
+                await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+
+                const row = await db.retrievePasskeyByCredentialID(
+                    samplePasskey.credentialID,
+                );
+
+                expect(row).not.toBeNull();
+                if (row === null) return;
+                expect(row.publicKey).toBe(samplePasskey.publicKeyHex);
+                expect(row.algorithm).toBe(samplePasskey.algorithm);
+                expect(row.signCount).toBe(0);
+            });
+        });
+
+        it("returns null for an unknown credentialID", async () => {
+            expect.assertions(1);
+            await withDb(async (db) => {
+                const row =
+                    await db.retrievePasskeyByCredentialID("does-not-exist");
+                expect(row).toBeNull();
+            });
+        });
+    });
+
+    describe("retrievePasskeysByUser", () => {
+        it("returns all passkeys for the user in public shape", async () => {
+            expect.assertions(3);
+            await withDb(async (db) => {
+                await db.createPasskey(
+                    userID,
+                    "yubikey",
+                    "cred-1",
+                    samplePasskey.publicKeyHex,
+                    -7,
+                    ["usb"],
+                );
+                await db.createPasskey(
+                    userID,
+                    "iCloud",
+                    "cred-2",
+                    samplePasskey.publicKeyHex,
+                    -7,
+                    [],
+                );
+
+                const list = await db.retrievePasskeysByUser(userID);
+                expect(list).toHaveLength(2);
+                const names = list.map((p) => p.name).sort();
+                expect(names).toEqual(["iCloud", "yubikey"]);
+                // empty transports column should decode to []
+                const icloud = list.find((p) => p.name === "iCloud");
+                expect(icloud?.transports).toEqual([]);
+            });
+        });
+
+        it("returns an empty array for users with no passkeys", async () => {
+            expect.assertions(1);
+            await withDb(async (db) => {
+                const list = await db.retrievePasskeysByUser(userID);
+                expect(list).toEqual([]);
+            });
+        });
+    });
+
+    describe("markPasskeyUsed", () => {
+        it("bumps the signature counter and lastUsedAt timestamp", 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 db.markPasskeyUsed(created.passkeyID, 42);
+                const row = await db.retrievePasskeyInternal(created.passkeyID);
+
+                expect(row).not.toBeNull();
+                if (row === null) return;
+                expect(row.signCount).toBe(42);
+                expect(row.lastUsedAt).not.toBeNull();
+            });
+        });
+    });
+
+    describe("deletePasskey", () => {
+        it("removes the passkey row", async () => {
+            expect.assertions(2);
+            await withDb(async (db) => {
+                const created = await db.createPasskey(
+                    userID,
+                    samplePasskey.name,
+                    samplePasskey.credentialID,
+                    samplePasskey.publicKeyHex,
+                    samplePasskey.algorithm,
+                    samplePasskey.transports,
+                );
+
+                await db.deletePasskey(created.passkeyID);
+
+                const row = await db.retrievePasskeyInternal(created.passkeyID);
+                expect(row).toBeNull();
+
+                const list = await db.retrievePasskeysByUser(userID);
+                expect(list).toEqual([]);
+            });
+        });
+    });
+});

package/src/__tests__/wellKnown.spec.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 {
+    buildAppleAppSiteAssociation,
+    buildAssetLinks,
+    normalizeFingerprint,
+} from "../server/wellKnown.ts";
+
+const PASSKEY_ENV_VARS = [
+    "SPIRE_PASSKEY_IOS_APP_IDS",
+    "SPIRE_PASSKEY_ANDROID_PACKAGE",
+    "SPIRE_PASSKEY_ANDROID_FINGERPRINTS",
+] as const;
+
+afterEach(() => {
+    for (const v of PASSKEY_ENV_VARS) {
+        process.env[v] = "";
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete process.env[v];
+    }
+});
+
+describe("normalizeFingerprint", () => {
+    it("normalizes lower-case hex without colons", () => {
+        const out = normalizeFingerprint(
+            "7d94dbdfc92da8bba1a79b64e117ad700a69daa5a0eb00a912a44efc5f6b7c42",
+        );
+        expect(out).toBe(
+            "7D:94:DB:DF:C9:2D:A8:BB:A1:A7:9B:64:E1:17:AD:70:0A:69:DA:A5:A0:EB:00:A9:12:A4:4E:FC:5F:6B:7C:42",
+        );
+    });
+
+    it("preserves a correctly-formatted colon-separated value", () => {
+        const input =
+            "7D:94:DB:DF:C9:2D:A8:BB:A1:A7:9B:64:E1:17:AD:70:0A:69:DA:A5:A0:EB:00:A9:12:A4:4E:FC:5F:6B:7C:42";
+        expect(normalizeFingerprint(input)).toBe(input);
+    });
+
+    it("rejects values that are too short", () => {
+        expect(normalizeFingerprint("AB:CD:EF")).toBeNull();
+    });
+
+    it("rejects non-hex characters", () => {
+        expect(
+            normalizeFingerprint(
+                "ZZ:94:DB:DF:C9:2D:A8:BB:A1:A7:9B:64:E1:17:AD:70:0A:69:DA:A5:A0:EB:00:A9:12:A4:4E:FC:5F:6B:7C:42",
+            ),
+        ).toBeNull();
+    });
+});
+
+describe("buildAppleAppSiteAssociation", () => {
+    it("returns null when SPIRE_PASSKEY_IOS_APP_IDS is unset", () => {
+        expect(buildAppleAppSiteAssociation()).toBeNull();
+    });
+
+    it("returns the AASA body with parsed app IDs", () => {
+        process.env["SPIRE_PASSKEY_IOS_APP_IDS"] =
+            "ABCDE12345.chat.vex.mobile, ABCDE12345.chat.vex.mobile.dev";
+        expect(buildAppleAppSiteAssociation()).toEqual({
+            webcredentials: {
+                apps: [
+                    "ABCDE12345.chat.vex.mobile",
+                    "ABCDE12345.chat.vex.mobile.dev",
+                ],
+            },
+        });
+    });
+});
+
+describe("buildAssetLinks", () => {
+    it("returns null when package or fingerprints are unset", () => {
+        expect(buildAssetLinks()).toBeNull();
+
+        process.env["SPIRE_PASSKEY_ANDROID_PACKAGE"] = "chat.vex.mobile";
+        expect(buildAssetLinks()).toBeNull();
+    });
+
+    it("returns the asset-links body with normalized fingerprints", () => {
+        process.env["SPIRE_PASSKEY_ANDROID_PACKAGE"] = "chat.vex.mobile";
+        process.env["SPIRE_PASSKEY_ANDROID_FINGERPRINTS"] =
+            "7d94dbdfc92da8bba1a79b64e117ad700a69daa5a0eb00a912a44efc5f6b7c42, 5C:13:F0:E4:EE:11:67:A4:9C:04:EB:C8:03:3E:05:8F:44:50:BD:AE:36:AA:15:B6:4F:83:7C:AC:24:0F:D2:82";
+        const body = buildAssetLinks();
+        expect(body).toEqual([
+            {
+                relation: [
+                    "delegate_permission/common.get_login_creds",
+                    "delegate_permission/common.handle_all_urls",
+                ],
+                target: {
+                    namespace: "android_app",
+                    package_name: "chat.vex.mobile",
+                    sha256_cert_fingerprints: [
+                        "7D:94:DB:DF:C9:2D:A8:BB:A1:A7:9B:64:E1:17:AD:70:0A:69:DA:A5:A0:EB:00:A9:12:A4:4E:FC:5F:6B:7C:42",
+                        "5C:13:F0:E4:EE:11:67:A4:9C:04:EB:C8:03:3E:05:8F:44:50:BD:AE:36:AA:15:B6:4F:83:7C:AC:24:0F:D2:82",
+                    ],
+                },
+            },
+        ]);
+    });
+
+    it("drops malformed fingerprints and returns null when none survive", () => {
+        process.env["SPIRE_PASSKEY_ANDROID_PACKAGE"] = "chat.vex.mobile";
+        process.env["SPIRE_PASSKEY_ANDROID_FINGERPRINTS"] = "not-a-hash, ZZ:CD";
+        expect(buildAssetLinks()).toBeNull();
+    });
+});

package/src/db/schema.ts

@@ -92,10 +92,11 @@ export type NewInvite = Insertable<InvitesTable>;
 export type NewMail = Insertable<MailTable>;
 export type NewOneTimeKey = Insertable<OneTimeKeysTable>;
 
+export type NewPasskey = Insertable<PasskeysTable>;
 export type NewPermission = Insertable<PermissionsTable>;
 export type NewPreKey = Insertable<PreKeysTable>;
-export type NewServer = Insertable<ServersTable>;
 
+export type NewServer = Insertable<ServersTable>;
 export type NewServiceMetric = Insertable<ServiceMetricsTable>;
 export type NewUser = Insertable<UsersTable>;
 export type OneTimeKeyRow = Selectable<OneTimeKeysTable>;
@@ -109,6 +110,21 @@ export interface OneTimeKeysTable {
     userID: string;
 }
 export type OneTimeKeyUpdate = Updateable<OneTimeKeysTable>;
+export type PasskeyRow = Selectable<PasskeysTable>;
+
+export interface PasskeysTable {
+    algorithm: number;
+    createdAt: string;
+    credentialID: string;
+    lastUsedAt: null | string;
+    name: string;
+    passkeyID: string;
+    publicKey: string;
+    signCount: number;
+    transports: string;
+    userID: string;
+}
+export type PasskeyUpdate = Updateable<PasskeysTable>;
 export type PermissionRow = Selectable<PermissionsTable>;
 
 export interface PermissionsTable {
@@ -138,6 +154,7 @@ export interface ServerDatabase {
     invites: InvitesTable;
     mail: MailTable;
     oneTimeKeys: OneTimeKeysTable;
+    passkeys: PasskeysTable;
     permissions: PermissionsTable;
     preKeys: PreKeysTable;
     servers: ServersTable;

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

@@ -0,0 +1,52 @@
+/**
+ * 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("passkeys").ifExists().execute();
+}
+
+// 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.
+//
+// `credentialID` is the WebAuthn credential id (base64url, opaque), and
+// is unique across all passkeys. `publicKey` is the COSE_Key bytes
+// returned by the authenticator, hex-encoded for storage. `signCount`
+// is the WebAuthn signature counter (monotonic) used to detect cloned
+// authenticators. `transports` is a comma-separated list of hints
+// ("usb,nfc,ble,internal,hybrid") so subsequent assertions can request
+// the right transport.
+export async function up(db: Kysely<unknown>): Promise<void> {
+    await db.schema
+        .createTable("passkeys")
+        .ifNotExists()
+        .addColumn("passkeyID", "varchar(255)", (cb) => cb.primaryKey())
+        .addColumn("userID", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("name", "varchar(255)", (cb) => cb.notNull())
+        .addColumn("credentialID", "varchar(512)", (cb) =>
+            cb.unique().notNull(),
+        )
+        .addColumn("publicKey", "text", (cb) => cb.notNull())
+        .addColumn("algorithm", "integer", (cb) => cb.notNull())
+        .addColumn("signCount", "integer", (cb) => cb.notNull().defaultTo(0))
+        .addColumn("transports", "varchar(255)", (cb) =>
+            cb.notNull().defaultTo(""),
+        )
+        .addColumn("createdAt", "text", (cb) => cb.notNull())
+        .addColumn("lastUsedAt", "text")
+        .execute();
+
+    await db.schema
+        .createIndex("passkeys_userID_idx")
+        .ifNotExists()
+        .on("passkeys")
+        .column("userID")
+        .execute();
+}

package/src/server/index.ts

@@ -35,6 +35,8 @@ import { errorHandler } from "./errors.ts";
 import { getFileRouter } from "./file.ts";
 import { getInviteRouter } from "./invite.ts";
 import { setupDocs } from "./openapi.ts";
+import { getPasskeyRouter } from "./passkey.ts";
+import { getPasskeyDeviceRouter } from "./passkeyDevices.ts";
 import {
     hasAnyPermission,
     hasPermission,
@@ -43,6 +45,7 @@ import {
 import { globalLimiter } from "./rateLimit.ts";
 import { getUserRouter } from "./user.ts";
 import { censorUser, getParam, getUser } from "./utils.ts";
+import { getWellKnownRouter } from "./wellKnown.ts";
 
 // expiry of regkeys
 export const EXPIRY_TIME = 1000 * 60 * 5;
@@ -95,6 +98,14 @@ const jwtDevicePayload = z.object({
     }),
 });
 
+const jwtPasskeyPayload = z.object({
+    passkey: z.object({
+        passkeyID: z.string(),
+    }),
+    scope: z.literal("passkey"),
+    user: UserSchema,
+});
+
 /** Extract Bearer token from Authorization header. */
 function extractBearer(req: express.Request): null | string {
     const header = req.headers.authorization;
@@ -107,13 +118,27 @@ const checkAuth: express.RequestHandler = (req, _res, next) => {
     if (token) {
         try {
             const result = jwt.verify(token, getJwtSecret());
-            const parsed = jwtUserPayload.safeParse(result);
-            if (parsed.success) {
-                req.user = parsed.data.user;
-                if (parsed.data.exp !== undefined) {
-                    req.exp = parsed.data.exp;
-                }
+            // Passkey-scoped JWTs share the bearer slot with regular
+            // user JWTs but carry a `scope: "passkey"` discriminator
+            // and a `passkey` claim. Populate `req.passkey` and the
+            // user (so route guards using `req.user` still pass) but
+            // never `req.device`. The actual privilege gate lives at
+            // the route level: passkey-only routes require
+            // `req.passkey`, device-only routes require `req.device`.
+            const passkeyParsed = jwtPasskeyPayload.safeParse(result);
+            if (passkeyParsed.success) {
+                req.user = passkeyParsed.data.user;
+                req.passkey = passkeyParsed.data.passkey;
                 req.bearerToken = token;
+            } else {
+                const parsed = jwtUserPayload.safeParse(result);
+                if (parsed.success) {
+                    req.user = parsed.data.user;
+                    if (parsed.data.exp !== undefined) {
+                        req.exp = parsed.data.exp;
+                    }
+                    req.bearerToken = token;
+                }
             }
         } catch {
             // Token verification failed — continue without auth
@@ -147,6 +172,21 @@ export const protect: express.RequestHandler = (req, res, next) => {
     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.
+ */
+export const protectPasskey: express.RequestHandler = (req, res, next) => {
+    if (!req.user || !req.passkey) {
+        res.sendStatus(401);
+        return;
+    }
+
+    next();
+};
+
 export const msgpackParser: express.RequestHandler = (req, res, next) => {
     if (req.is("application/msgpack")) {
         try {
@@ -185,11 +225,22 @@ export const initApp = (
     const fileRouter = getFileRouter(db);
     const avatarRouter = getAvatarRouter();
     const inviteRouter = getInviteRouter(db, tokenValidator, notify);
+    const passkeyRouter = getPasskeyRouter(db);
+    const passkeyDeviceRouter = getPasskeyDeviceRouter(db, notify);
 
     // MIDDLEWARE
-    // Global per-IP rate limit is the FIRST middleware so a flooded
-    // source hits the limiter before Express spends any cycles on
-    // body parsing, helmet, or auth. See src/server/rateLimit.ts.
+
+    // WebAuthn well-known association files (AASA, assetlinks.json)
+    // are served BEFORE the global rate limiter so periodic platform
+    // fetches by Apple / Google CDNs are never 429'd. They 404 when
+    // the relevant env vars aren't set, so this is a no-op for
+    // deployments that haven't enrolled an app.
+    api.use(getWellKnownRouter());
+
+    // Global per-IP rate limit is the FIRST authenticated-path
+    // middleware so a flooded source hits the limiter before Express
+    // spends any cycles on body parsing, helmet, or auth. See
+    // src/server/rateLimit.ts.
     api.use(globalLimiter);
     api.use(express.json({ limit: "20mb" }));
     api.use(
@@ -854,6 +905,14 @@ export const initApp = (
     );
 
     // COMPLEX RESOURCES
+    // Passkey routes are mounted at the root since they live under
+    // both `/user/:id/passkeys/...` (registration / list / delete by
+    // an authenticated device) and `/auth/passkey/...` (public
+    // sign-in). The router itself defines the full path on each
+    // route handler.
+    api.use(passkeyRouter);
+    api.use(passkeyDeviceRouter);
+
     api.use("/user", userRouter);
 
     api.use("/file", fileRouter);