feat(sync): approve new devices without recovery keys

Add an expiring, account-scoped enrollment mailbox with atomic device-cap replacement and authenticated API routes. Wire automatic desktop registration, trusted-device approval, recovery-key fallback, device management, generated clients, and coverage.

Author: ComputelessComputer

apps/api/openapi.gen.json

@@ -49,6 +49,7 @@ export const DEVICE_LIMIT_ERROR_CODE = "sync_device_limit_reached";
 export const DEVICE_LIMIT_TOAST_ID = "cloudsync-device-limit";
 
 export type CloudsyncCredentialBlock =
+  | "approval_pending"
   | "device_limit"
   | "identity_mismatch"
   | "keychain_access"

apps/desktop/src/auth/cloudsync-credentials.ts

@@ -9,6 +9,8 @@ import {
   execute,
   getCloudsyncStatus,
   getE2eeIdentityStatus,
+  getOrCreateE2eeDeviceIdentity,
+  importE2eeDeviceEnrollment,
   suspendCloudsync,
   suspendCloudsyncAfterAuthLoss,
   suspendCloudsyncForSignOut,
@@ -138,6 +140,28 @@ function replicaCredentialsResponse() {
   );
 }
 
+function deviceEnrollmentResponse(status: "pending" | "sealed") {
+  return new Response(
+    JSON.stringify({
+      requestId: "11111111-1111-4111-8111-111111111111",
+      expiresAt: new Date(NOW.getTime() + 24 * 60 * 60 * 1000).toISOString(),
+      status,
+      package:
+        status === "sealed"
+          ? {
+              ephemeralPublicKey: "E".repeat(43),
+              nonce: "N".repeat(32),
+              ciphertext: "C".repeat(100),
+            }
+          : null,
+    }),
+    {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+}
+
 function cloudsyncStatus(activityPaused = false) {
   return {
     cloudsync_enabled: true,
@@ -235,6 +259,17 @@ describe("CloudSync auth lifecycle", () => {
       keyId: E2EE_KEY_ID,
       memberPublicKey: E2EE_MEMBER_PUBLIC_KEY,
     });
+    vi.mocked(getOrCreateE2eeDeviceIdentity).mockResolvedValue({
+      publicKey: "A".repeat(43),
+    });
+    vi.mocked(importE2eeDeviceEnrollment).mockResolvedValue({
+      keyId: E2EE_KEY_ID,
+    });
+    vi.mocked(miscCommands.getFingerprint).mockResolvedValue({
+      status: "error",
+      error: "unavailable",
+    });
+    vi.mocked(hostname).mockResolvedValue(null);
     vi.mocked(fsSyncCommands.deleteSessionFolder).mockResolvedValue({
       status: "ok",
       data: null,
@@ -280,25 +315,150 @@ describe("CloudSync auth lifecycle", () => {
     expect(getCloudsyncCredentialBlock()).toBeNull();
   });
 
-  test("does not request cloud credentials before E2EE recovery setup", async () => {
-    const fetchMock = vi.fn();
+  test("keeps first-device recovery setup separate from enrollment", async () => {
+    const fetchMock = vi.fn<(input: RequestInfo | URL) => Promise<Response>>(
+      () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              error: {
+                code: "e2ee_enrollment_requires_existing_key",
+                message: "Set up encrypted sync on an existing device first",
+              },
+            }),
+            {
+              status: 409,
+              headers: { "Content-Type": "application/json" },
+            },
+          ),
+        ),
+    );
     vi.stubGlobal("fetch", fetchMock);
     vi.mocked(getE2eeIdentityStatus).mockResolvedValue({
       configured: false,
       keyId: null,
       memberPublicKey: null,
     });
+    vi.mocked(miscCommands.getFingerprint).mockResolvedValue({
+      status: "ok",
+      data: "fingerprint-1234",
+    });
     vi.spyOn(console, "warn").mockImplementation(() => {});
 
     await handleCloudsyncAuthChange("SIGNED_IN", session());
     await vi.advanceTimersByTimeAsync(60 * 60 * 1000);
 
-    expect(fetchMock).not.toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0].toString()).toBe(
+      "https://api.test/sync/e2ee/device-enrollments",
+    );
     expect(configureCloudsyncToken).not.toHaveBeenCalled();
     expect(suspendCloudsync).toHaveBeenCalledTimes(1);
     expect(getCloudsyncCredentialBlock()).toBe("setup_required");
   });
 
+  test("registers a keyless device and polls for approval", async () => {
+    const fetchMock = vi.fn(() =>
+      Promise.resolve(deviceEnrollmentResponse("pending")),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.mocked(getE2eeIdentityStatus).mockResolvedValue({
+      configured: false,
+      keyId: null,
+      memberPublicKey: null,
+    });
+    vi.mocked(miscCommands.getFingerprint).mockResolvedValue({
+      status: "ok",
+      data: "fingerprint-1234",
+    });
+
+    await handleCloudsyncAuthChange("SIGNED_IN", session());
+
+    expect(getCloudsyncCredentialBlock()).toBe("approval_pending");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(getOrCreateE2eeDeviceIdentity).toHaveBeenCalledWith("user-id");
+    expect(configureCloudsyncToken).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(5 * 1000);
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(getCloudsyncCredentialBlock()).toBe("approval_pending");
+  });
+
+  test("imports an approved package and continues credential exchange", async () => {
+    const fetchMock = vi
+      .fn<(input: RequestInfo | URL) => Promise<Response>>()
+      .mockResolvedValueOnce(deviceEnrollmentResponse("sealed"))
+      .mockResolvedValueOnce(new Response(null, { status: 204 }))
+      .mockResolvedValueOnce(credentialsResponse());
+    vi.stubGlobal("fetch", fetchMock);
+    vi.mocked(getE2eeIdentityStatus)
+      .mockResolvedValueOnce({
+        configured: false,
+        keyId: null,
+        memberPublicKey: null,
+      })
+      .mockResolvedValueOnce({
+        configured: true,
+        keyId: E2EE_KEY_ID,
+        memberPublicKey: E2EE_MEMBER_PUBLIC_KEY,
+      });
+    vi.mocked(miscCommands.getFingerprint).mockResolvedValue({
+      status: "ok",
+      data: "fingerprint-1234",
+    });
+
+    await handleCloudsyncAuthChange("SIGNED_IN", session());
+
+    expect(importE2eeDeviceEnrollment).toHaveBeenCalledWith(
+      "user-id",
+      "11111111-1111-4111-8111-111111111111",
+      {
+        ephemeralPublicKey: "E".repeat(43),
+        nonce: "N".repeat(32),
+        ciphertext: "C".repeat(100),
+      },
+    );
+    expect(fetchMock.mock.calls[1]?.[0].toString()).toContain("/consume");
+    expect(configureCloudsyncToken).toHaveBeenCalledTimes(1);
+    expect(getCloudsyncCredentialBlock()).toBeNull();
+  });
+
+  test("blocks enrollment until a capped device is replaced", async () => {
+    const fetchMock = vi.fn(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            error: {
+              code: "sync_device_limit_reached",
+              message: "CloudSync device limit reached",
+            },
+          }),
+          {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+          },
+        ),
+      ),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    vi.mocked(getE2eeIdentityStatus).mockResolvedValue({
+      configured: false,
+      keyId: null,
+      memberPublicKey: null,
+    });
+    vi.mocked(miscCommands.getFingerprint).mockResolvedValue({
+      status: "ok",
+      data: "fingerprint-1234",
+    });
+
+    await handleCloudsyncAuthChange("SIGNED_IN", session());
+
+    expect(getCloudsyncCredentialBlock()).toBe("device_limit");
+    expect(sonnerToast.error).toHaveBeenCalledOnce();
+    expect(configureCloudsyncToken).not.toHaveBeenCalled();
+  });
+
   test("surfaces macOS Keychain access failures separately", async () => {
     const fetchMock = vi.fn();
     vi.stubGlobal("fetch", fetchMock);

apps/desktop/src/auth/cloudsync.test.ts

@@ -4,6 +4,8 @@ import type { AuthChangeEvent, Session } from "@supabase/supabase-js";
 import {
   bindCloudsyncAccount,
   getCloudsyncStatus,
+  getOrCreateE2eeDeviceIdentity,
+  importE2eeDeviceEnrollment,
   isCloudsyncActivityDeferredError,
   suspendCloudsync,
   suspendCloudsyncAfterAuthLoss,
@@ -16,6 +18,7 @@ import {
   DEVICE_LIMIT_ERROR_CODE,
   DEVICE_LIMIT_TOAST_ID,
   getCloudsyncCredentialBlock,
+  getDeviceIdentity,
   hasWorkspaceProjection,
   isCredentials,
   readE2eeIdentity,
@@ -31,6 +34,12 @@ import {
 import { flushCloudsyncSessionEvictions } from "./cloudsync-session-evictions";
 import { requestCloudsyncCredentials } from "./cloudsync-token-exchange";
 import { provisionMissingWorkspaceKeys } from "./cloudsync-workspace-keys";
+import {
+  ENROLLMENT_REQUIRES_EXISTING_KEY_ERROR_CODE,
+  SyncDeviceRequestError,
+  consumeDeviceEnrollment,
+  registerDeviceEnrollment,
+} from "./sync-devices";
 
 import { resolveConfigValue } from "~/shared/config";
 import { isKeychainAccessError } from "~/shared/keychain";
@@ -44,6 +53,7 @@ export {
 const REFRESH_LEAD_MS = 2 * 60 * 1000;
 const RETRY_DELAY_MS = 60 * 1000;
 const ACTIVITY_RETRY_DELAY_MS = 5 * 1000;
+const ENROLLMENT_RETRY_DELAY_MS = 5 * 1000;
 const MIN_REFRESH_DELAY_MS = 1000;
 const EXCHANGE_TIMEOUT_MS = 25 * 1000;
 const EVICTION_RETRY_DELAY_MS = 30 * 1000;
@@ -600,6 +610,65 @@ function scheduleActivityStatusRetry(
   }, ACTIVITY_RETRY_DELAY_MS);
 }
 
+async function enrollCurrentDevice(
+  session: Session,
+  activeGeneration: number,
+): Promise<"imported" | "pending"> {
+  const controller = new AbortController();
+  exchangeController = controller;
+  const timeout = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
+
+  try {
+    const [device, enrollmentIdentity] = await Promise.all([
+      getDeviceIdentity(),
+      getOrCreateE2eeDeviceIdentity(session.user.id),
+    ]);
+    if (
+      controller.signal.aborted ||
+      activeGeneration !== generation ||
+      !device.fingerprint
+    ) {
+      throw new Error("E2EE device enrollment was interrupted");
+    }
+
+    const enrollment = await registerDeviceEnrollment({
+      accessToken: session.access_token,
+      publicKey: enrollmentIdentity.publicKey,
+      fingerprint: device.fingerprint,
+      deviceName: device.name,
+      signal: controller.signal,
+    });
+    if (enrollment.status !== "sealed" || !enrollment.package) {
+      return "pending";
+    }
+
+    await importE2eeDeviceEnrollment(
+      session.user.id,
+      enrollment.requestId,
+      enrollment.package,
+    );
+    try {
+      await consumeDeviceEnrollment({
+        accessToken: session.access_token,
+        requestId: enrollment.requestId,
+        publicKey: enrollmentIdentity.publicKey,
+        fingerprint: device.fingerprint,
+        signal: controller.signal,
+      });
+    } catch {
+      console.warn(
+        "[cloudsync] imported device enrollment acknowledgement failed; credential exchange will finalize it",
+      );
+    }
+    return "imported";
+  } finally {
+    clearTimeout(timeout);
+    if (exchangeController === controller) {
+      exchangeController = null;
+    }
+  }
+}
+
 async function activateCloudsync(
   session: Session,
   suspendBeforeExchange: boolean,
@@ -796,7 +865,7 @@ async function activateCloudsync(
     if (identityRead.status === "timed_out") {
       throw new Error("E2EE identity read timed out");
     }
-    const identity = identityRead.value;
+    let identity = identityRead.value;
     if (activeGeneration !== generation) {
       return "ok";
     }
@@ -820,6 +889,65 @@ async function activateCloudsync(
       }
       suspendedBeforeCredentialExchange = true;
     }
+    if (!identity.configured) {
+      let enrollment: Awaited<ReturnType<typeof enrollCurrentDevice>>;
+      try {
+        enrollment = await enrollCurrentDevice(session, activeGeneration);
+      } catch (error) {
+        if (activeGeneration !== generation) {
+          return "ok";
+        }
+        if (
+          error instanceof SyncDeviceRequestError &&
+          error.code === ENROLLMENT_REQUIRES_EXISTING_KEY_ERROR_CODE
+        ) {
+          setCredentialBlock("setup_required");
+          await suspendCloudsyncAfterCredentialRejection(activeGeneration);
+          console.warn(
+            "[cloudsync] first-device E2EE recovery key setup is required; sync remains disabled",
+          );
+          return "ok";
+        }
+        if (error instanceof SyncDeviceRequestError && error.status === 403) {
+          const deviceLimit = error.code === DEVICE_LIMIT_ERROR_CODE;
+          setCredentialBlock(deviceLimit ? "device_limit" : "not_entitled");
+          await suspendCloudsyncAfterCredentialRejection(activeGeneration);
+          if (deviceLimit) {
+            sonnerToast.error(
+              t`Cloud sync is limited to 5 devices. Replace or remove another device to sync here.`,
+              { id: DEVICE_LIMIT_TOAST_ID },
+            );
+          }
+          return "ok";
+        }
+        throw error;
+      }
+      if (activeGeneration !== generation) {
+        return "ok";
+      }
+      if (enrollment === "pending") {
+        setCredentialBlock("approval_pending");
+        await suspendCloudsyncAfterCredentialRejection(activeGeneration);
+        if (activeGeneration === generation) {
+          scheduleExchange(
+            session,
+            activeGeneration,
+            ENROLLMENT_RETRY_DELAY_MS,
+            onAccountMismatch,
+          );
+        }
+        return "ok";
+      }
+
+      const importedIdentity = await settleCloudsyncOperationWithin(
+        readE2eeIdentity(session.user.id),
+        EXCHANGE_TIMEOUT_MS,
+      );
+      if (importedIdentity.status === "timed_out") {
+        throw new Error("Imported E2EE identity read timed out");
+      }
+      identity = importedIdentity.value;
+    }
     if (
       !identity.configured ||
       !identity.keyId ||