@vex-chat/spire 1.3.6 → 1.4.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";
 
@@ -65,6 +65,7 @@ export function createPendingDeviceEnrollmentRequest(
     expiresAt: string;
     requestID: string;
     status: "pending_approval";
+    userID: string;
 } {
     pruneDeviceEnrollmentRequests();
     const requestID = crypto.randomUUID();
@@ -82,6 +83,13 @@ export function createPendingDeviceEnrollmentRequest(
         requestID,
         status: "pending",
     });
+    // We include the existing user's `userID` so the new (still-
+    // unauthenticated) device can fetch its public avatar from the
+    // unauthenticated `/avatar/:userID` endpoint and surface an "is
+    // this you?" confirmation before continuing with the approval
+    // request. The userID is already implicit (the requester typed the
+    // username and learned the account exists from this very response),
+    // so returning it here doesn't expand the attack surface.
     return {
         challenge: challengeHex,
         expiresAt: new Date(
@@ -89,9 +97,114 @@ export function createPendingDeviceEnrollmentRequest(
         ).toISOString(),
         requestID,
         status: "pending_approval",
+        userID,
     };
 }
 
+/**
+ * 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/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;
         }
     }