@vex-chat/spire 1.3.7 → 1.5.0

package/src/server/passkeyDevices.ts

@@ -0,0 +1,154 @@
+/**
+ * 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";
+
+import express from "express";
+
+import { msgpack } from "../utils/msgpack.ts";
+
+import { resolveDeviceEnrollmentRequest } from "./user.ts";
+import { getParam, getUser } from "./utils.ts";
+
+import { protectPasskey } from "./index.ts";
+
+/**
+ * Routes that grant a passkey-authenticated session a strictly
+ * bounded admin/recovery surface:
+ *
+ * - `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
+ *
+ * The route family is parallel to `/user/:id/devices/...` so the
+ * existing device-authenticated flow stays untouched (and there's no
+ * confusion about which kind of credential is doing what when a
+ * single endpoint accepts both).
+ *
+ * Mail/server/permissions/etc. routes are intentionally NOT mirrored
+ * here — passkeys are an administrative credential, not a messaging
+ * device.
+ */
+export const getPasskeyDeviceRouter = (
+    db: Database,
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void,
+) => {
+    const router = express.Router();
+
+    router.get(
+        "/user/:id/passkey/devices",
+        protectPasskey,
+        async (req, res) => {
+            const userDetails = getUser(req);
+            const userID = getParam(req, "id");
+            if (userDetails.userID !== userID) {
+                res.sendStatus(401);
+                return;
+            }
+            const list = await db.retrieveUserDeviceList([userID]);
+            res.send(msgpack.encode(list));
+        },
+    );
+
+    router.delete(
+        "/user/:id/passkey/devices/:deviceID",
+        protectPasskey,
+        async (req, res) => {
+            const userDetails = getUser(req);
+            const userID = getParam(req, "id");
+            const deviceID = getParam(req, "deviceID");
+            if (userDetails.userID !== userID) {
+                res.sendStatus(401);
+                return;
+            }
+            const device = await db.retrieveDevice(deviceID);
+            if (!device || device.owner !== userID) {
+                res.sendStatus(404);
+                return;
+            }
+            // 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 —
+            // "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."
+            await db.deleteDevice(deviceID);
+            // Tell whoever's online that the device-list shape
+            // changed; clients use this to refresh the Settings →
+            // Devices view in real time.
+            notify(userID, "deviceListChanged", crypto.randomUUID());
+            res.sendStatus(200);
+        },
+    );
+
+    router.post(
+        "/user/:id/passkey/devices/requests/:requestID/approve",
+        protectPasskey,
+        async (req, res) => {
+            const userDetails = getUser(req);
+            const userID = getParam(req, "id");
+            const requestID = getParam(req, "requestID");
+            if (userDetails.userID !== userID) {
+                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",
+                db,
+                notify,
+                requestID,
+                userID,
+            });
+            if (result.kind === "ok") {
+                res.send(msgpack.encode(result.device));
+                return;
+            }
+            res.status(result.status).send({ error: result.error });
+        },
+    );
+
+    router.post(
+        "/user/:id/passkey/devices/requests/:requestID/reject",
+        protectPasskey,
+        async (req, res) => {
+            const userDetails = getUser(req);
+            const userID = getParam(req, "id");
+            const requestID = getParam(req, "requestID");
+            if (userDetails.userID !== userID) {
+                res.sendStatus(401);
+                return;
+            }
+            const result = await resolveDeviceEnrollmentRequest({
+                action: "reject",
+                db,
+                notify,
+                requestID,
+                userID,
+            });
+            if (result.kind === "ok") {
+                res.sendStatus(200);
+                return;
+            }
+            res.status(result.status).send({ error: result.error });
+        },
+    );
+
+    return router;
+};

package/src/server/user.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Database } from "../Database.ts";
-import type { DevicePayload } from "@vex-chat/types";
+import type { Device, DevicePayload } from "@vex-chat/types";
 
 import express from "express";
 
@@ -101,6 +101,110 @@ export function createPendingDeviceEnrollmentRequest(
     };
 }
 
+/**
+ * Reusable approve/reject side of a pending device-enrollment
+ * request. Lives here so both the device-authenticated router
+ * (signs an approval challenge with the approving device's
+ * Ed25519 key) and the passkey-authenticated router (relies on
+ * the freshness of the passkey JWT instead) can share the same
+ * state-machine + enrollment lifecycle.
+ *
+ * The device-auth caller is expected to have already verified the
+ * approving device's signature before invoking this helper.
+ */
+export async function resolveDeviceEnrollmentRequest(args: {
+    action: "approve" | "reject";
+    db: Database;
+    notify: (
+        userID: string,
+        event: string,
+        transmissionID: string,
+        data?: unknown,
+        deviceID?: string,
+    ) => void;
+    requestID: string;
+    userID: string;
+}): Promise<
+    | { device: Device; kind: "ok" }
+    | { 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 };
+    }
+
+    if (args.action === "reject") {
+        pending.status = "rejected";
+        pending.resolvedAt = Date.now();
+        pending.error = "Rejected.";
+        deviceEnrollments.set(args.requestID, pending);
+        args.notify(args.userID, "deviceRequest", crypto.randomUUID(), {
+            requestID: args.requestID,
+            status: "rejected",
+        });
+        // Caller maps `kind: "ok"` without device to a 200; reuse the
+        // ok shape with a placeholder device since the type insists
+        // on one. The reject flow doesn't return a body, the caller
+        // discards `device`.
+        return {
+            device: {
+                deleted: false,
+                deviceID: "",
+                lastLogin: "",
+                name: "",
+                owner: args.userID,
+                signKey: "",
+            },
+            kind: "ok",
+        };
+    }
+
+    try {
+        const device = await args.db.createDevice(
+            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" };
+    } catch {
+        pending.status = "rejected";
+        pending.error = "Could not create approved 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 create approved device.",
+            kind: "err",
+            status: 470,
+        };
+    }
+}
+
 function buildApprovalChallenge(
     requestID: string,
     signKey: string,

package/src/server/wellKnown.ts

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2020-2026 Vex Heavy Industries LLC
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ * Commercial licenses available at vex.wtf
+ */
+
+import express from "express";
+
+const HEX_FINGERPRINT = /^[0-9a-fA-F]{2}(?::?[0-9a-fA-F]{2}){31}$/;
+
+/**
+ * Build the Apple App Site Association body, or `null` when the
+ * server isn't configured to advertise any iOS apps.
+ */
+export function buildAppleAppSiteAssociation(): null | {
+    webcredentials: { apps: string[] };
+} {
+    const apps = parseList(process.env["SPIRE_PASSKEY_IOS_APP_IDS"]);
+    if (apps.length === 0) {
+        return null;
+    }
+    return { webcredentials: { apps } };
+}
+
+/**
+ * Build the Android Digital Asset Links body, or `null` when the
+ * server isn't configured to advertise an Android app.
+ */
+export function buildAssetLinks():
+    | null
+    | {
+          relation: string[];
+          target: {
+              namespace: "android_app";
+              package_name: string;
+              sha256_cert_fingerprints: string[];
+          };
+      }[] {
+    const packageName = process.env["SPIRE_PASSKEY_ANDROID_PACKAGE"]?.trim();
+    const fingerprintsRaw = parseList(
+        process.env["SPIRE_PASSKEY_ANDROID_FINGERPRINTS"],
+    );
+    if (!packageName || fingerprintsRaw.length === 0) {
+        return null;
+    }
+    const fingerprints: string[] = [];
+    for (const raw of fingerprintsRaw) {
+        const norm = normalizeFingerprint(raw);
+        if (norm != null) {
+            fingerprints.push(norm);
+        }
+    }
+    if (fingerprints.length === 0) {
+        return null;
+    }
+    return [
+        {
+            relation: [
+                "delegate_permission/common.get_login_creds",
+                "delegate_permission/common.handle_all_urls",
+            ],
+            target: {
+                namespace: "android_app",
+                package_name: packageName,
+                sha256_cert_fingerprints: fingerprints,
+            },
+        },
+    ];
+}
+
+/**
+ * Normalize a SHA-256 fingerprint to upper-case `AA:BB:...` form.
+ *
+ * Accepts hex with or without colon separators. Returns `null` for
+ * anything that isn't a valid 32-byte SHA-256 hex value.
+ */
+export function normalizeFingerprint(raw: string): null | string {
+    if (!HEX_FINGERPRINT.test(raw)) {
+        return null;
+    }
+    const hex = raw.replace(/:/g, "").toUpperCase();
+    const pairs = hex.match(/.{2}/g);
+    return pairs ? pairs.join(":") : null;
+}
+
+function parseList(envValue: string | undefined): string[] {
+    if (envValue == null) {
+        return [];
+    }
+    return envValue
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+
+/**
+ * Serves the WebAuthn well-known association files Apple and Google
+ * fetch to verify the app ↔ domain link before letting their
+ * Credential Manager run a passkey ceremony.
+ *
+ * Both files are served at their canonical paths and 404 when the
+ * corresponding env vars are not set, so a non-passkey deployment is
+ * indistinguishable from one that simply hasn't published an app yet.
+ *
+ * Env:
+ * - `SPIRE_PASSKEY_IOS_APP_IDS` — comma-separated `TEAMID.bundle.id`
+ *   for the AASA `webcredentials.apps` array (e.g.
+ *   `ABCDE12345.chat.vex.mobile`). Required for iOS.
+ * - `SPIRE_PASSKEY_ANDROID_PACKAGE` — Android package name. Required
+ *   for Android together with `SPIRE_PASSKEY_ANDROID_FINGERPRINTS`.
+ * - `SPIRE_PASSKEY_ANDROID_FINGERPRINTS` — comma-separated SHA-256
+ *   fingerprints (with or without colons) of the certs that sign the
+ *   Android app.
+ *
+ * Mount this router BEFORE the global rate limiter so periodic
+ * platform fetches are never 429'd.
+ */
+export const getWellKnownRouter = (): express.Router => {
+    const router = express.Router();
+
+    router.get("/.well-known/apple-app-site-association", (_req, res) => {
+        const body = buildAppleAppSiteAssociation();
+        if (!body) {
+            res.sendStatus(404);
+            return;
+        }
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", "public, max-age=300");
+        res.status(200).end(JSON.stringify(body));
+    });
+
+    router.get("/.well-known/assetlinks.json", (_req, res) => {
+        const body = buildAssetLinks();
+        if (!body) {
+            res.sendStatus(404);
+            return;
+        }
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", "public, max-age=300");
+        res.status(200).end(JSON.stringify(body));
+    });
+
+    return router;
+};

package/src/types/express.ts

@@ -21,6 +21,14 @@ declare global {
             bearerToken?: string;
             device?: Device;
             exp?: number;
+            /**
+             * 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
+             * cannot send mail or do anything device-specific.
+             */
+            passkey?: { passkeyID: string };
             user?: User;
         }
     }