@oxy.so/services 12.13.0 → 13.0.0

package/lib/typescript/module/ui/oauth/explicitOAuthConsent.d.ts

@@ -1,11 +1,9 @@
 /**
  * Explicit OAuth consent for an already-authenticated Oxy user.
  *
- * This is deliberately separate from sign-in routing. First-party applications
- * normally use the account dialog, but a consent-required scope (for example
- * `acting-as:offline`) still has to go through the OAuth authorize surface. The
- * caller must invoke this operation from a real user gesture; it never runs on
- * mount, retries silently, or grants anything locally.
+ * External applications may request additional scopes through OAuth. Own Oxy
+ * applications use the account dialog and never create OAuth consent grants.
+ * The caller invokes this operation from a user gesture.
  */
 import type { OxyServices } from "@oxy.so/core";
 import type { OAuthSessionCommitInput, WebAuthMode, WebOAuthFailureReason, WebOAuthRedirectReason } from "./types.js";
@@ -18,7 +16,7 @@ export interface RequestOAuthConsentOptions {
     timeoutMs?: number;
 }
 export type OAuthConsentFailureReason = WebOAuthFailureReason | "invalid-redirect-uri" | "invalid-scopes" | "scope-not-configured" | "client-resolution-failed" | "native-callback-invalid" | "state-mismatch" | "exchange-failed" | "subject-mismatch";
-export type OAuthConsentUnsupportedReason = "missing-client-id" | "identity-bound" | "not-authenticated" | "unsupported-platform";
+export type OAuthConsentUnsupportedReason = "missing-client-id" | "first-party-application" | "identity-bound" | "not-authenticated" | "unsupported-platform";
 export type OAuthConsentResult = {
     status: "consented";
 } | {

package/lib/typescript/module/ui/oauth/explicitOAuthConsent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explicitOAuthConsent.d.ts","sourceRoot":"","sources":["../../../../../src/ui/oauth/explicitOAuthConsent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAMnE,OAAO,KAAK,EAEX,uBAAuB,EACvB,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,YAAS,CAAC;AAEjB,MAAM,WAAW,0BAA0B;IAC1C,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,yBAAyB,GAClC,qBAAqB,GACrB,sBAAsB,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,0BAA0B,GAC1B,yBAAyB,GACzB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,CAAC;AAEtB,MAAM,MAAM,6BAA6B,GACtC,mBAAmB,GACnB,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,CAAC;AAE1B,MAAM,MAAM,kBAAkB,GAC3B;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,sBAAsB,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IACA,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,yBAAyB,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACpB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC3C,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAuDD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAqI7B"}
+{"version":3,"file":"explicitOAuthConsent.d.ts","sourceRoot":"","sources":["../../../../../src/ui/oauth/explicitOAuthConsent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAMnE,OAAO,KAAK,EAEX,uBAAuB,EACvB,WAAW,EACX,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,YAAS,CAAC;AAEjB,MAAM,WAAW,0BAA0B;IAC1C,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,yBAAyB,GAClC,qBAAqB,GACrB,sBAAsB,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,0BAA0B,GAC1B,yBAAyB,GACzB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,CAAC;AAEtB,MAAM,MAAM,6BAA6B,GACtC,mBAAmB,GACnB,yBAAyB,GACzB,gBAAgB,GAChB,mBAAmB,GACnB,sBAAsB,CAAC;AAE1B,MAAM,MAAM,kBAAkB,GAC3B;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,sBAAsB,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IACA,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,yBAAyB,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACpB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC3C,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,wFAAwF;IACxF,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAuDD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,0BAA0B,GACjC,OAAO,CAAC,kBAAkB,CAAC,CA2I7B"}

package/lib/typescript/module/ui/session/cachedBoot.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a returning session needs for its first paint, kept on this device.
+ *
+ * A cold boot used to wait on two round trips before it showed anything: the
+ * registry's classification of this app and the profile of the signed-in
+ * account. With a session saved on the device, the app now paints at once from
+ * what the last run left here, and the boot verifies both in the background
+ * (`runProviderColdBoot`). This module is that cache:
+ *
+ * - the registry's last verdict on this app (`device` or `oauth`), tied to the
+ *   `clientId` it was given for;
+ * - the last account profile the runtime held, tied to that account's id.
+ *
+ * Both live in the provider's ordinary storage (AsyncStorage on native,
+ * `localStorage` on web), next to the per-account query cache, which already
+ * holds the same profile under the SDK's `users` queries. Neither is a
+ * credential: the device secret and the access token stay in the auth store.
+ *
+ * A cached session is offered only when it matches the auth store: the profile
+ * must belong to the account the persisted session is for, so a switch or a
+ * sign-out on a previous run can never paint somebody else.
+ */
+import type { User } from '@oxy.so/core';
+import { type AuthStateStore } from '@oxy.so/core/session';
+import type { StorageInterface } from '../utils/storageHelpers.js';
+export type SessionLane = 'device' | 'oauth';
+/** A persisted session the app can show before the network answers. */
+export interface CachedSession {
+    sessionId: string;
+    userId: string;
+    deviceId: string;
+    /** The account profile the last run held for {@link userId}. */
+    user: User;
+    /** The persisted access token, when it is still valid past the refresh lead. */
+    warmToken: string | null;
+}
+export interface CachedBootStore {
+    saveLane(clientId: string, lane: SessionLane): Promise<void>;
+    saveAccount(user: User): Promise<void>;
+    clearAccount(): Promise<void>;
+    /**
+     * The cached session for this `clientId`, or `null` when anything a first
+     * paint needs is missing or does not match the auth store.
+     */
+    readSession(clientId: string, authStore: AuthStateStore): Promise<CachedSession | null>;
+}
+export declare function createCachedBootStore(storage: StorageInterface, prefix: string, now?: () => number): CachedBootStore;
+//# sourceMappingURL=cachedBoot.d.ts.map

package/lib/typescript/module/ui/session/cachedBoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cachedBoot.d.ts","sourceRoot":"","sources":["../../../../../src/ui/session/cachedBoot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAAyB,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,IAAI,EAAE,IAAI,CAAC;IACX,gFAAgF;IAChF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CACzF;AAuBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAM,MAAiB,GAC3B,eAAe,CA+DjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/services",
-  "version": "12.13.0",
+  "version": "13.0.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -150,7 +150,7 @@
     "delete-dts.js": "find ./lib/commonjs -name '*.d.js*' -delete && find ./lib/module -name '*.d.js*' -delete"
   },
   "dependencies": {
-    "@oxy.so/contracts": "^5.8.0",
+    "@oxy.so/contracts": "^6.0.0",
     "color": "^5.0.3",
     "@peable.to/sdk": "0.4.1"
   },
@@ -159,7 +159,7 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/app-integrity": "~58.0.2",
     "@expo/vector-icons": "^15.0.3",
-    "@oxy.so/core": "6.15.2",
+    "@oxy.so/core": "7.0.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^12.0.1",
     "@react-native/babel-preset": "^0.88.0",
@@ -209,12 +209,12 @@
     "expo-video": "~58.0.11"
   },
   "//@oxy.so/bloom": "Bloom 11.1.0 adds the shared grouped sections, usage card, subscription plans, frame appearance and overlay navigation APIs used by this SDK. First-party Bloom peers remain open above this tested minimum.",
-  "//@oxy.so/core": "Core 6.13.0 supplies the `accounts.settings.*` strings (picture, categories) the account settings speak in every language; 6.12.0 supplies `fileManagement.contentLost` and the `lost` file status a lost file is listed with; 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
+  "//@oxy.so/core": "Core 6.16.0 supplies `requireServerVerdict` and `onHolderRejected`, with which the cold boot checks a session it painted from the cache; 6.13.0 supplies the `accounts.settings.*` strings (picture, categories) the account settings speak in every language; 6.12.0 supplies `fileManagement.contentLost` and the `lost` file status a lost file is listed with; 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
   "peerDependencies": {
     "@expo/app-integrity": ">=56.0.0 <59.0.0",
     "@expo/vector-icons": "^15.0.3",
     "@oxy.so/bloom": ">=11.1.0",
-    "@oxy.so/core": "^6.14.0",
+    "@oxy.so/core": "^7.0.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": ">=11.4.1 <13.0.0",
     "@tanstack/query-async-storage-persister": "^5.101",

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(