@vex-chat/spire 1.11.5 → 2.0.1

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;

package/src/utils/loadEnv.ts

@@ -6,16 +6,92 @@
 
 import { config } from "dotenv";
 
+const REQUIRED_ENV_VARS = ["DB_TYPE", "JWT_SECRET", "SPK"] as const;
+const NORMALIZED_ENV_VARS = [
+    ...REQUIRED_ENV_VARS,
+    "API_PORT",
+    "SPIRE_FIPS",
+    "SPIRE_PASSKEY_RP_ID",
+    "SPIRE_PASSKEY_RP_NAME",
+    "SPIRE_PASSKEY_ORIGINS",
+    "SPIRE_PASSKEY_IOS_APP_IDS",
+    "SPIRE_PASSKEY_ANDROID_PACKAGE",
+    "SPIRE_PASSKEY_ANDROID_FINGERPRINTS",
+] as const;
+const HEX_BYTES_RE = /^(?:[0-9a-fA-F]{2})+$/;
+const TWEETNACL_SPK_HEX_LENGTH = 128;
+
+export function isSpireFipsEnabled(value: string | undefined): boolean {
+    const normalized = value == null ? "" : normalizeEnvValue(value);
+    return normalized === "1" || normalized === "true";
+}
+
 /* Populate process.env with vars from .env and verify required vars are present. */
 export function loadEnv(): void {
     config();
-    const requiredEnvVars: string[] = ["DB_TYPE", "JWT_SECRET", "SPK"];
-    for (const required of requiredEnvVars) {
-        if (process.env[required] === undefined) {
+    normalizeConfiguredEnv();
+    for (const required of REQUIRED_ENV_VARS) {
+        if (!process.env[required]) {
             process.stderr.write(
                 `Required environment variable '${required}' is not set. Please consult the README.\n`,
             );
             process.exit(1);
         }
     }
+    validateSpireRuntimeEnv(process.env);
+}
+
+export function normalizeEnvValue(value: string): string {
+    const trimmed = value.trim();
+    if (trimmed.length < 2) {
+        return trimmed;
+    }
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === `"` && last === `"`) || (first === `'` && last === `'`)) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+
+export function validateSpireRuntimeEnv(
+    env: Record<string, string | undefined>,
+): void {
+    const spk = normalizeEnvValue(env["SPK"] ?? "");
+    const jwtSecret = normalizeEnvValue(env["JWT_SECRET"] ?? "");
+    if (!HEX_BYTES_RE.test(spk)) {
+        throw new Error(
+            "SPK must be an even-length hex string. Generate one with `pnpm --filter @vex-chat/spire gen-spk` or `gen-spk-fips`.",
+        );
+    }
+
+    if (isSpireFipsEnabled(env["SPIRE_FIPS"])) {
+        if (spk.length === TWEETNACL_SPK_HEX_LENGTH) {
+            throw new Error(
+                "SPIRE_FIPS=true requires an SPK from `pnpm --filter @vex-chat/spire gen-spk-fips`; the configured SPK looks like a tweetnacl key.",
+            );
+        }
+    } else if (spk.length !== TWEETNACL_SPK_HEX_LENGTH) {
+        throw new Error(
+            "SPIRE_FIPS is not enabled, so SPK must be 128 hex characters from `pnpm --filter @vex-chat/spire gen-spk`.",
+        );
+    }
+
+    if (jwtSecret.length === 0) {
+        throw new Error(
+            "JWT_SECRET must be set. Generate one with `pnpm --filter @vex-chat/spire gen-spk` or `gen-spk-fips`.",
+        );
+    }
+    if (jwtSecret === spk) {
+        throw new Error("JWT_SECRET must be separate from SPK.");
+    }
+}
+
+function normalizeConfiguredEnv(): void {
+    for (const name of NORMALIZED_ENV_VARS) {
+        const value = process.env[name];
+        if (value != null) {
+            process.env[name] = normalizeEnvValue(value);
+        }
+    }
 }