@oxy.so/services 12.13.0 → 12.14.0

package/src/ui/boot/__tests__/cachedColdBoot.test.ts

@@ -0,0 +1,187 @@
+/**
+ * `runProviderColdBoot` with a session saved on the device: it paints from the
+ * cache before any network answers, then checks the classification and the
+ * session in the background. A first boot (nothing cached) is unchanged.
+ */
+import type { AuthStateStore, PersistedAuthState, SessionClient } from '@oxy.so/core/session';
+
+jest.mock('@oxy.so/core/session', () => {
+  const actual = jest.requireActual('@oxy.so/core/session');
+  return { __esModule: true, ...actual, runSessionColdBoot: jest.fn() };
+});
+
+import { runSessionColdBoot } from '@oxy.so/core/session';
+import { runProviderColdBoot, type RunProviderColdBootOptions } from '../runProviderColdBoot';
+
+const mockRunSessionColdBoot = runSessionColdBoot as jest.Mock;
+type BootOptions = Parameters<typeof runSessionColdBoot>[0];
+
+const OFFICIAL = {
+  id: 'app',
+  name: 'App',
+  type: 'first_party',
+  isOfficial: true,
+  isInternal: false,
+  scopes: [],
+};
+
+function credentialStore(): AuthStateStore {
+  const state: PersistedAuthState = {
+    sessionId: 's1',
+    userId: 'u1',
+    deviceId: 'd1',
+    deviceSecret: 'secret',
+  };
+  return {
+    load: jest.fn(async () => state),
+    save: jest.fn(async () => true),
+    clear: jest.fn(async () => undefined),
+  } as unknown as AuthStateStore;
+}
+
+function makeOptions(paints: boolean): RunProviderColdBootOptions & {
+  getPublic: jest.Mock;
+  release: (app: unknown) => void;
+  fail: (error: Error) => void;
+} {
+  let release: (app: unknown) => void = () => undefined;
+  let fail: (error: Error) => void = () => undefined;
+  const getPublic = jest.fn(
+    () =>
+      new Promise((resolve, reject) => {
+        release = resolve;
+        fail = reject;
+      }),
+  );
+  const markAuthResolved = jest.fn();
+  return {
+    oxyServices: { apps: { getPublic } } as unknown as RunProviderColdBootOptions['oxyServices'],
+    authStore: credentialStore(),
+    clientId: 'oxy_dk_test',
+    sessionClient: { start: jest.fn(async () => undefined) } as unknown as SessionClient,
+    syncDeviceCredentialToHost: jest.fn(async () => undefined),
+    commitSession: jest.fn(async () => undefined),
+    markAuthResolved,
+    setTokenReady: jest.fn(),
+    paintCachedSession: jest.fn(async () => {
+      if (paints) markAuthResolved();
+      return paints;
+    }),
+    onCachedSessionRejected: jest.fn(async () => undefined),
+    onCachedSessionUnconfirmed: jest.fn(),
+    getPublic,
+    release: (app) => release(app),
+    fail: (error) => fail(error),
+  };
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+beforeEach(() => {
+  mockRunSessionColdBoot.mockReset();
+  window.history.replaceState(null, '', '/');
+});
+
+it('paints a saved session before the registry or the mint answers, then mints for a verdict', async () => {
+  mockRunSessionColdBoot.mockImplementation(async (opts: BootOptions) => {
+    const session = { sessionId: 's1', userId: 'u1', accessToken: 'minted', via: 'mint' };
+    await opts.onSession?.(session);
+    return { kind: 'session', via: session.via, session };
+  });
+  const options = makeOptions(true);
+
+  const boot = runProviderColdBoot(options);
+  await tick();
+
+  expect(options.markAuthResolved).toHaveBeenCalled();
+  expect(mockRunSessionColdBoot).not.toHaveBeenCalled();
+
+  options.release(OFFICIAL);
+  await boot;
+
+  expect(mockRunSessionColdBoot).toHaveBeenCalledWith(
+    expect.objectContaining({ requireServerVerdict: true }),
+  );
+  expect(options.commitSession).toHaveBeenCalledWith(
+    { sessionId: 's1', userId: 'u1', accessToken: 'minted', deviceState: undefined },
+    { activate: false },
+  );
+  expect(options.onCachedSessionRejected).not.toHaveBeenCalled();
+  expect(options.onCachedSessionUnconfirmed).not.toHaveBeenCalled();
+});
+
+it.each([
+  ['the server ends the holder', OFFICIAL, true],
+  [
+    'the registry now classifies the app OAuth-only',
+    { ...OFFICIAL, type: 'third_party', isOfficial: false },
+    false,
+  ],
+])('signs a painted session out when %s', async (_case, app, mints) => {
+  mockRunSessionColdBoot.mockImplementation(async (opts: BootOptions) => {
+    opts.onHolderRejected?.();
+    await opts.onSignedOut?.('no_session');
+    return { kind: 'unauthenticated' };
+  });
+  const options = makeOptions(true);
+
+  const boot = runProviderColdBoot(options);
+  await tick();
+  options.release(app);
+  await boot;
+
+  expect(mockRunSessionColdBoot).toHaveBeenCalledTimes(mints ? 1 : 0);
+  expect(options.onCachedSessionRejected).toHaveBeenCalledTimes(1);
+  expect(options.onCachedSessionUnconfirmed).not.toHaveBeenCalled();
+});
+
+it('keeps a painted session the server could not be asked about, and asks again', async () => {
+  mockRunSessionColdBoot.mockImplementationOnce(async (opts: BootOptions) => {
+    await opts.onSignedOut?.('no_session');
+    return { kind: 'unauthenticated' };
+  });
+  const options = makeOptions(true);
+
+  const boot = runProviderColdBoot(options);
+  await tick();
+  options.fail(new Error('offline'));
+  await boot;
+
+  expect(options.onCachedSessionRejected).not.toHaveBeenCalled();
+  const retry = (options.onCachedSessionUnconfirmed as jest.Mock).mock.calls[0][0];
+  mockRunSessionColdBoot.mockImplementationOnce(async (opts: BootOptions) => {
+    const session = { sessionId: 's1', userId: 'u1', accessToken: 'minted', via: 'mint' };
+    await opts.onSession?.(session);
+    return { kind: 'session', via: session.via, session };
+  });
+  const retried = retry();
+  await tick();
+  options.release(OFFICIAL);
+  await retried;
+
+  expect(options.commitSession).toHaveBeenCalledTimes(1);
+  expect(options.onCachedSessionUnconfirmed).toHaveBeenCalledTimes(1);
+});
+
+it('a first boot with nothing cached still waits for the verdict and the handoff', async () => {
+  mockRunSessionColdBoot.mockImplementation(async (opts: BootOptions) => {
+    await opts.onSignedOut?.('no_session');
+    return { kind: 'unauthenticated' };
+  });
+  const options = makeOptions(false);
+
+  const boot = runProviderColdBoot(options);
+  await tick();
+
+  expect(options.markAuthResolved).not.toHaveBeenCalled();
+  expect(mockRunSessionColdBoot).not.toHaveBeenCalled();
+
+  options.release(OFFICIAL);
+  await boot;
+
+  expect(mockRunSessionColdBoot).toHaveBeenCalledWith(
+    expect.objectContaining({ requireServerVerdict: false }),
+  );
+  expect(options.markAuthResolved).toHaveBeenCalled();
+  expect(options.onCachedSessionRejected).not.toHaveBeenCalled();
+});

package/src/ui/boot/runProviderColdBoot.ts

@@ -121,11 +121,223 @@ export interface RunProviderColdBootOptions {
   ) => Promise<void>;
   markAuthResolved: () => void;
   setTokenReady: (ready: boolean) => void;
+  /**
+   * Show the session saved on this device before any network: the account from
+   * its cached profile, auth resolved. Resolves `true` when it did, `false` when
+   * the device holds nothing a first paint can use (then the boot runs as a
+   * first boot). Never consulted in `sessionMode: 'identity'` or with an OAuth
+   * return on the URL.
+   */
+  paintCachedSession?: () => Promise<boolean>;
+  /**
+   * The server ended the painted session: the registry now classifies the app
+   * as OAuth-only, or the mint answered this holder `invalid_device_secret` /
+   * `no_active_session` and no recovery lane restored one. Sign out now.
+   */
+  onCachedSessionRejected?: () => Promise<void>;
+  /**
+   * The painted session could not be checked yet (offline, the registry or the
+   * mint unreachable). It stays on screen; call `retry` later to ask again.
+   */
+  onCachedSessionUnconfirmed?: (retry: () => Promise<void>) => void;
+}
+
+type ClassificationLane = 'device' | 'oauth';
+
+/** Starts the provider's fresh classification; a rejection is observed, not swallowed. */
+function startClassification(opts: RunProviderColdBootOptions): Promise<ClassificationLane> {
+  const classification = (async () =>
+    opts.resolveSessionLane?.() ??
+    resolveApplicationSessionLane(opts.oxyServices, opts.clientId))();
+  // Observed so a rejection that lands before it is awaited is not reported as
+  // unhandled; every caller still awaits it and sees the rejection.
+  classification.catch(() => undefined);
+  return classification;
+}
+
+/** What the device lanes made of this holder: a session, a verdict against it, or no answer. */
+type DeviceRestoreOutcome = 'session' | 'rejected' | 'unreachable';
+
+/**
+ * The device lanes of the boot (`runSessionColdBoot`), for a first boot or for
+ * the background check of a painted one.
+ *
+ * A first boot (`painted: false`) is on the critical path: its committed
+ * session resolves auth, bounded by {@link SESSION_HANDOFF_DEADLINE_MS}. A
+ * painted boot already resolved auth from the cache, so nothing waits on the
+ * handoff and the pure-local warm token is skipped: the check needs the mint's
+ * verdict, which a still-valid token cannot give.
+ */
+async function restoreDeviceSession(
+  opts: RunProviderColdBootOptions,
+  painted: boolean,
+): Promise<DeviceRestoreOutcome> {
+  const {
+    oxyServices,
+    authStore,
+    sessionMode = 'account',
+    identity,
+    sessionClient,
+    syncDeviceCredentialToHost,
+    commitSession,
+    markAuthResolved,
+  } = opts;
+
+  await opts.beforeDeviceBoot?.();
+
+  // Best-effort connectivity probe up front: an EXPLICIT offline verdict skips
+  // the two doomed network steps so routing settles immediately instead of
+  // burning the overall deadline on a mint that cannot succeed. Any ambiguity
+  // resolves to "online" — the network steps still run.
+  const offline = await detectOfflineHint();
+
+  let outcome: DeviceRestoreOutcome = 'unreachable';
+  let holderRejected = false;
+  await runSessionColdBoot({
+    oxy: oxyServices,
+    store: authStore,
+    platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
+    sessionMode,
+    identity,
+    // The device-wide shared credential slot, enabling the `shared-device-adopt`
+    // lane: a newly installed official app joins this device's existing session
+    // instead of falling back to signing a challenge with the Commons identity
+    // key. `null` on web, where each origin is its own device by design; the
+    // core lane is also skipped outright in `sessionMode: 'identity'`.
+    sharedDeviceCredential: createPlatformSharedDeviceCredentialStore() ?? undefined,
+    overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE_MS,
+    isOffline: () => offline,
+    requireServerVerdict: painted,
+    onHolderRejected: () => {
+      holderRejected = true;
+    },
+    onStepDeadline: (stepId) => {
+      loggerUtil.warn(
+        `Cold-boot step "${stepId}" exceeded the ${COLD_BOOT_OVERALL_DEADLINE_MS}ms overall deadline — abandoned; routing proceeds signed-out`,
+        { component: 'runProviderColdBoot', method: 'onStepDeadline' },
+      );
+    },
+    onSession: async (session) => {
+      outcome = 'session';
+      // Mint already persisted `{deviceId, deviceSecret}` to the store; sync the
+      // in-memory SessionClient host so sockets + tab-focus re-mint can use it.
+      await syncDeviceCredentialToHost();
+      const handoff = commitSession(
+        {
+          sessionId: session.sessionId,
+          accessToken: session.accessToken,
+          userId: session.userId,
+          deviceState: session.state,
+        },
+        { activate: false },
+      );
+      if (painted) {
+        // The account is already on screen; the commit refreshes its profile.
+        await handoff;
+        return;
+      }
+      let handoffDeadlineId: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([
+        handoff,
+        new Promise<void>((resolve) => {
+          handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE_MS);
+        }),
+      ]).finally(() => {
+        if (handoffDeadlineId !== undefined) {
+          clearTimeout(handoffDeadlineId);
+        }
+      });
+      markAuthResolved();
+    },
+    onSignedOut: async () => {
+      outcome = holderRejected ? 'rejected' : 'unreachable';
+      await syncDeviceCredentialToHost();
+      // A painted session is the caller's to end or keep (see verifyCachedSession).
+      if (painted) return;
+      const cred = await loadPersistedDeviceCredential(authStore);
+      if (cred) {
+        try {
+          await sessionClient.start();
+        } catch (socketError) {
+          if (__DEV__) {
+            loggerUtil.debug(
+              'Device socket start failed (non-fatal)',
+              { component: 'runProviderColdBoot' },
+              socketError,
+            );
+          }
+        }
+      }
+      markAuthResolved();
+    },
+    onStepError: (id, error) => {
+      if (__DEV__) {
+        loggerUtil.debug(
+          `Cold-boot step "${id}" errored (non-fatal, falling through)`,
+          { component: 'runProviderColdBoot' },
+          error,
+        );
+      }
+    },
+  });
+  await opts.afterDeviceBoot?.();
+  return outcome;
+}
+
+/**
+ * The background check of a painted session: the registry's classification and
+ * a mint with this holder's own credential (whose commit refreshes the profile).
+ * Each is asked until the server answers it. A verdict against the session
+ * signs out at that moment; no answer keeps the cached session on screen and
+ * hands the caller a retry.
+ */
+async function verifyCachedSession(
+  opts: RunProviderColdBootOptions,
+  verified: { lane: boolean; session: boolean },
+  classification: Promise<ClassificationLane>,
+): Promise<void> {
+  if (!verified.lane) {
+    let lane: ClassificationLane | null = null;
+    try {
+      lane = await classification;
+    } catch {
+      // The registry could not be asked (offline, timeout, 5xx). That is no
+      // verdict on this app: the cached `device` classification stands until it
+      // answers.
+    }
+    if (lane === 'oauth') {
+      await opts.onCachedSessionRejected?.();
+      return;
+    }
+    verified.lane = lane === 'device';
+  }
+  if (!verified.session) {
+    const outcome = await restoreDeviceSession(opts, true);
+    if (outcome === 'rejected') {
+      await opts.onCachedSessionRejected?.();
+      return;
+    }
+    verified.session = outcome === 'session';
+  }
+  if (!verified.lane || !verified.session) {
+    opts.onCachedSessionUnconfirmed?.(() =>
+      verifyCachedSession(
+        opts,
+        verified,
+        verified.lane ? Promise.resolve('device') : startClassification(opts),
+      ),
+    );
+  }
 }
 
 /**
  * Device-first cold boot for `@oxy.so/services` providers.
  *
+ * A returning session saved on this device (account mode, the app last
+ * classified `device`, its profile cached) paints first, with no network, and
+ * is then checked in the background — see `paintCachedSession`. Otherwise, a
+ * first boot:
+ *
  * Ordered pipeline:
  * 1. Complete an OAuth authorization-code return already on the URL (web)
  * 2. `runSessionColdBoot` — device-secret mint (+ the native Commons-proof lane,
@@ -148,9 +360,6 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
     clientId,
     authRedirectUri,
     sessionMode = 'account',
-    identity,
-    sessionClient,
-    syncDeviceCredentialToHost,
     commitSession,
     markAuthResolved,
     setTokenReady,
@@ -162,14 +371,21 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
 
   try {
     // Classification precedes every USE of a local secret, the shared credential
-    // and the identity key. Unavailable registry metadata fails closed, including
-    // offline boot. It starts now, before anything else, so its round trip
-    // overlaps the local work below.
-    const classification = (async () =>
-      opts.resolveSessionLane?.() ?? resolveApplicationSessionLane(oxyServices, clientId))();
-    // Observed so a rejection that lands before it is awaited is not reported as
-    // unhandled; every path below still awaits it and sees the rejection.
-    classification.catch(() => undefined);
+    // and the identity key. Unavailable registry metadata fails closed on a first
+    // boot, including offline. It starts now, before anything else, so its round
+    // trip overlaps the local work below.
+    const classification = startClassification(opts);
+
+    // A returning session saved on this device paints at once from the cache:
+    // the account, its cached content, auth resolved, no network on the way.
+    // The classification and the session are then checked in the background,
+    // and a verdict against either signs out at that moment. Identity-bound
+    // clients and OAuth returns keep the path below.
+    const freshLaunch = !identityBound && !hasOAuthReturnOnUrl();
+    if (freshLaunch && (await opts.paintCachedSession?.())) {
+      await verifyCachedSession(opts, { lane: false, session: false }, classification);
+      return;
+    }
 
     // The verdict decides HOW a session is restored, never WHETHER there is one.
     // A web origin with nothing to restore and no OAuth return on the URL ends
@@ -177,7 +393,7 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
     // for an answer that cannot change the outcome. The classification still
     // completes below and still gates every later sign-in
     // (`ensureDeviceSessionLane` shares this same in-flight lookup).
-    if (!identityBound && isWebBrowser() && !hasOAuthReturnOnUrl()) {
+    if (freshLaunch && isWebBrowser()) {
       if (!(await hasRestorableState(authStore))) {
         markAuthResolved();
         const lane = await classification;
@@ -215,89 +431,7 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
       return;
     }
 
-    await opts.beforeDeviceBoot?.();
-
-    // Best-effort connectivity probe up front: an EXPLICIT offline verdict skips
-    // the two doomed network steps so routing settles immediately instead of
-    // burning the overall deadline on a mint that cannot succeed. Any ambiguity
-    // resolves to "online" — the network steps still run.
-    const offline = await detectOfflineHint();
-
-    await runSessionColdBoot({
-      oxy: oxyServices,
-      store: authStore,
-      platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
-      sessionMode,
-      identity,
-      // The device-wide shared credential slot, enabling the `shared-device-adopt`
-      // lane: a newly installed official app joins this device's existing session
-      // instead of falling back to signing a challenge with the Commons identity
-      // key. `null` on web, where each origin is its own device by design; the
-      // core lane is also skipped outright in `sessionMode: 'identity'`.
-      sharedDeviceCredential: createPlatformSharedDeviceCredentialStore() ?? undefined,
-      overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE_MS,
-      isOffline: () => offline,
-      onStepDeadline: (stepId) => {
-        loggerUtil.warn(
-          `Cold-boot step "${stepId}" exceeded the ${COLD_BOOT_OVERALL_DEADLINE_MS}ms overall deadline — abandoned; routing proceeds signed-out`,
-          { component: 'runProviderColdBoot', method: 'onStepDeadline' },
-        );
-      },
-      onSession: async (session) => {
-        // Mint already persisted `{deviceId, deviceSecret}` to the store; sync the
-        // in-memory SessionClient host so sockets + tab-focus re-mint can use it.
-        await syncDeviceCredentialToHost();
-        const handoff = commitSession(
-          {
-            sessionId: session.sessionId,
-            accessToken: session.accessToken,
-            userId: session.userId,
-            deviceState: session.state,
-          },
-          { activate: false },
-        );
-        let handoffDeadlineId: ReturnType<typeof setTimeout> | undefined;
-        await Promise.race([
-          handoff,
-          new Promise<void>((resolve) => {
-            handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE_MS);
-          }),
-        ]).finally(() => {
-          if (handoffDeadlineId !== undefined) {
-            clearTimeout(handoffDeadlineId);
-          }
-        });
-        markAuthResolved();
-      },
-      onSignedOut: async () => {
-        await syncDeviceCredentialToHost();
-        const cred = await loadPersistedDeviceCredential(authStore);
-        if (cred) {
-          try {
-            await sessionClient.start();
-          } catch (socketError) {
-            if (__DEV__) {
-              loggerUtil.debug(
-                'Device socket start failed (non-fatal)',
-                { component: 'runProviderColdBoot' },
-                socketError,
-              );
-            }
-          }
-        }
-        markAuthResolved();
-      },
-      onStepError: (id, error) => {
-        if (__DEV__) {
-          loggerUtil.debug(
-            `Cold-boot step "${id}" errored (non-fatal, falling through)`,
-            { component: 'runProviderColdBoot' },
-            error,
-          );
-        }
-      },
-    });
-    await opts.afterDeviceBoot?.();
+    await restoreDeviceSession(opts, false);
   } catch (error) {
     if (__DEV__) {
       loggerUtil.error(