@oxyhq/services 19.0.1 → 19.1.0

package/src/ui/context/OxyContext.tsx

@@ -7,17 +7,12 @@ import {
   useMemo,
   useRef,
   useState,
-  type ReactNode,
 } from 'react';
 import { Linking } from 'react-native';
 import { OxyServices, oxyClient } from '@oxyhq/core';
 import type {
   User,
-  ApiError,
   SessionLoginResponse,
-  AccountNode,
-  CreateAccountInput,
-  ClientSession,
   AuthStateStore,
   PersistedAuthState,
   AccountDialogController,
@@ -25,20 +20,24 @@ import type {
 } from '@oxyhq/core';
 import {
   KeyManager,
-  runSessionColdBoot,
   installAuthRefreshHandler,
   startTokenRefreshScheduler,
   createAccountDialogController,
+  refreshPersistedSession,
   logger as loggerUtil,
+  syncHubAfterSignIn,
 } from '@oxyhq/core';
 import type { SecurityAlert } from '@oxyhq/contracts';
 import {
   registerAccountDialogControls,
   notifyAccountDialogVisibility,
 } from '../navigation/accountDialogManager';
+import { redirectToAuthorize } from '../components/oauthNavigation';
+import { isWebBrowser } from '../utils/isWebBrowser';
+import { runProviderColdBoot } from '../boot/runProviderColdBoot';
+import { loadPersistedDeviceCredential } from '../utils/deviceCredential';
 import { useAuthStore, type AuthState } from '../stores/authStore';
 import { useShallow } from 'zustand/react/shallow';
-import type { UseFollowHook } from '../hooks/useFollow.types';
 import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
 import { useAuthOperations, clearPersistedAuthSafe } from './hooks/useAuthOperations';
@@ -50,7 +49,6 @@ import { useQueryClient } from '@tanstack/react-query';
 import { clearQueryCache } from '../hooks/queryClient';
 import { useAvatarPicker } from '../hooks/useAvatarPicker';
 import { useAccountStore } from '../stores/accountStore';
-import { isWebBrowser } from '../utils/isWebBrowser';
 import {
   createSessionClient,
   createPlatformAuthStateStore,
@@ -59,297 +57,19 @@ import {
   activeUserOf,
   accountIdsOf,
 } from '../session';
+import {
+  type OxyContextState,
+  type PasswordSignInResult,
+  type OxyContextProviderProps,
+  type CommitInput,
+} from './oxyContextTypes';
+import { DEFAULT_SESSION_VALIDITY_MS, loadUseFollowHook } from './oxyContextHelpers';
+import { useOxyAccountGraph } from './useOxyAccountGraph';
 
-export interface OxyContextState {
-  user: User | null;
-  sessions: ClientSession[];
-  activeSessionId: string | null;
-  isAuthenticated: boolean;
-  isLoading: boolean;
-  isTokenReady: boolean;
-  hasAccessToken: boolean;
-  canUsePrivateApi: boolean;
-  isPrivateApiPending: boolean;
-  /**
-   * Whether the initial auth determination has concluded.
-   *
-   * `false` from mount until the FIRST device-first cold boot resolves —
-   * during that window `isAuthenticated: false` is UNDETERMINED, not a
-   * definitive "logged out". Flips to `true` exactly once the boot concludes
-   * (a session was committed OR none exists) and never reverts. Consumers should
-   * defer their first auth-dependent fetch until this is `true` so a cold-boot
-   * web reload with an existing session does not fetch anonymous data.
-   */
-  isAuthResolved: boolean;
-  isStorageReady: boolean;
-  error: string | null;
-  currentLanguage: string;
-  currentLanguageMetadata: ReturnType<typeof useLanguageManagement>['metadata'];
-  currentLanguageName: string;
-  currentNativeLanguageName: string;
-
-  // Identity (cryptographic key pair)
-  hasIdentity: () => Promise<boolean>;
-  getPublicKey: () => Promise<string | null>;
-
-  // Authentication
-  signIn: (publicKey: string, deviceName?: string) => Promise<User>;
-
-  /**
-   * Sign in with a username/email + password.
-   *
-   * Commits a successful session into context state through the SAME path the
-   * QR device-flow and cold boot use (so `isAuthenticated` / `user` update and
-   * the zero-cookie device credential is persisted). Returns a discriminated result
-   * so the caller can branch on the two-factor-required case — which creates NO
-   * session; the caller completes the 2FA challenge with the returned
-   * `loginToken` via {@link OxyContextState.completeTwoFactorSignIn}.
-   */
-  signInWithPassword: (
-    identifier: string,
-    password: string,
-    opts?: { deviceName?: string; deviceFingerprint?: string },
-  ) => Promise<PasswordSignInResult>;
-
-  /**
-   * Complete a 2FA-gated password sign-in started by {@link signInWithPassword}.
-   * Presents the short-lived `loginToken` with a TOTP `token` or a `backupCode`;
-   * on success the session is committed exactly like a one-step sign-in. Returns
-   * any `securityAlert` the server attached so the caller can show the same
-   * "New sign-in detected" acknowledgement as the one-step path.
-   */
-  completeTwoFactorSignIn: (params: {
-    loginToken: string;
-    token?: string;
-    backupCode?: string;
-    deviceName?: string;
-  }) => Promise<{ securityAlert?: SecurityAlert }>;
-
-  /**
-   * Commit a session obtained out-of-band (the "Sign in with Oxy" QR device
-   * flow). Plants tokens, persists the zero-cookie device credential, registers
-   * the account into the device set, and hydrates the full user profile.
-   */
-  handleWebSession: (session: SessionLoginResponse) => Promise<void>;
-
-  // Session management
-  logout: (targetSessionId?: string) => Promise<void>;
-  logoutAll: () => Promise<void>;
-  switchSession: (sessionId: string) => Promise<User>;
-  removeSession: (sessionId: string) => Promise<void>;
-  refreshSessions: () => Promise<void>;
-  setLanguage: (languageId: string) => Promise<void>;
-  getDeviceSessions: () => Promise<
-    Array<{
-      sessionId: string;
-      deviceId: string;
-      deviceName?: string;
-      lastActive?: string;
-      expiresAt?: string;
-    }>
-  >;
-  logoutAllDeviceSessions: () => Promise<void>;
-  updateDeviceName: (deviceName: string) => Promise<void>;
-  clearSessionState: () => Promise<void>;
-  clearAllAccountData: () => Promise<void>;
-  storageKeyPrefix: string;
-  /**
-   * The app's Oxy OAuth client id / ApplicationCredential publicKey, as
-   * supplied via the `clientId` prop. Required for the cross-app device
-   * sign-in flow: the sign-in components send it to
-   * `POST /auth/session/create` so the API can identify the requesting app by
-   * its real registered client id. `null` when the consuming app did not
-   * configure a client id — the device sign-in flow surfaces a configuration
-   * error in that case.
-   */
-  clientId: string | null;
-  oxyServices: OxyServices;
-  useFollow?: UseFollowHook;
-  showBottomSheet?: (screenOrConfig: RouteName | { screen: RouteName; props?: Record<string, unknown> }) => void;
-  openAvatarPicker: () => void;
-
-  // Unified account dialog (the single switcher + sign-in surface). The headless
-  // state machine lives in `@oxyhq/core`; `OxyAccountDialog` (mounted by
-  // `OxyProvider`) binds to it. `null` in the no-provider loading state.
-  /** The headless controller driving {@link openAccountDialog}. `null` before mount. */
-  accountDialogController: AccountDialogController | null;
-  /** Whether the unified account dialog is currently presented. */
-  isAccountDialogOpen: boolean;
-  /**
-   * Open the unified account dialog. `accounts` (default) shows the switcher;
-   * `signin` / `add` open the sign-in entry. Replaces every prior device/account
-   * surface and the standalone sign-in modal.
-   */
-  openAccountDialog: (view?: AccountDialogView) => void;
-  /** Dismiss the unified account dialog and cancel any in-flight sign-in flow. */
-  closeAccountDialog: () => void;
-
-  // Unified account graph (self, owned orgs/projects/bots, accounts shared with
-  // the caller). The cryptographic Commons/DID "identity" is a SEPARATE concept.
-  //
-  // UX concept: the user picks an account and the WHOLE app becomes that account
-  // — a genuine, REAL-SESSION switch (`switchToAccount`), identical to switching
-  // between device sign-ins. There is NO separate "active account" concept:
-  // `user` IS the active account after a switch.
-  /** Every account the caller can access — own personal root, owned, and shared — from `listAccounts()`. */
-  accounts: AccountNode[];
-  /**
-   * Switch the active session INTO an account from the {@link accounts} graph.
-   *
-   * Uniform with every other account switch: if the account is already on this
-   * device's multi-account set, switches straight through the same
-   * server-authoritative `SessionClient.switchAccount()` path {@link switchSession}
-   * uses. Only the FIRST switch into an account mints+plants a real session via
-   * `oxyServices.switchToAccount` and registers it into the device set, so it
-   * survives reload and appears in the device account list exactly like a device
-   * sign-in from then on. Either way, afterwards `user` IS the target account.
-   */
-  switchToAccount: (accountId: string) => Promise<void>;
-  refreshAccounts: () => Promise<void>;
-  createAccount: (data: CreateAccountInput) => Promise<AccountNode>;
-}
+export type { OxyContextState, PasswordSignInResult, OxyContextProviderProps } from './oxyContextTypes';
 
 const OxyContext = createContext<OxyContextState | null>(null);
 
-/**
- * Result of {@link OxyContextState.signInWithPassword}.
- *
- * `'ok'` — the password was accepted and the session committed (so
- * `isAuthenticated` / `user` are updated and the device credential persisted).
- * `securityAlert` is present when the server flagged this sign-in as anomalous
- * (new device / location) — the caller shows a "New sign-in detected"
- * acknowledgement before proceeding; the session is already committed.
- *
- * `'2fa_required'` — the account has two-factor auth enabled, so NO session was
- * created. Complete the challenge with the returned short-lived `loginToken`
- * via {@link OxyContextState.completeTwoFactorSignIn}.
- */
-export type PasswordSignInResult =
-  | { status: 'ok'; securityAlert?: SecurityAlert }
-  | { status: '2fa_required'; loginToken: string };
-
-export interface OxyContextProviderProps {
-  children: ReactNode;
-  oxyServices?: OxyServices;
-  baseURL?: string;
-  authWebUrl?: string;
-  authRedirectUri?: string;
-  storageKeyPrefix?: string;
-  /**
-   * The app's Oxy OAuth client id / ApplicationCredential publicKey; required
-   * for the cross-app device sign-in flow. See {@link OxyContextState.clientId}.
-   */
-  clientId?: string;
-  /**
-   * Whether this provider is the device-first **session authority**. `true`
-   * (default) runs `runSessionColdBoot` on mount and opens the signed-out
-   * device-state socket — the correct behavior for every Relying Party app.
-   *
-   * `false` is the IdP host (`auth.oxy.so`) opt-out: the IdP is NOT a session
-   * authority (handoff "IdP vs RP"), so it must NOT restore or reproject an
-   * ambient device session. With `coldBoot={false}` the cold boot never runs
-   * and the signed-out device socket never opens; auth resolves immediately as
-   * signed out. Interactive sign-in still commits a normal session on this
-   * origin — only the automatic restore/reproject is suppressed.
-   * @default true
-   */
-  coldBoot?: boolean;
-  onAuthStateChange?: (user: User | null) => void;
-  onError?: (error: ApiError) => void;
-}
-
-/**
- * Fallback client-session validity window (ms) — 7 days — applied when a
- * committed session does not carry an explicit `expiresAt`. This is only a
- * local display hint for the multi-session store; the server remains the source
- * of truth for actual session expiry.
- */
-const DEFAULT_SESSION_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
-
-/**
- * How long the cold boot WAITS for the post-boot SessionClient handoff
- * (`addCurrentAccount` + `start` + `syncFromClient`) before it resolves auth and
- * stops blocking. Once a boot step planted a token the user is already
- * authenticated — the handoff only populates the multi-account set and the
- * server-authoritative active account, and those also arrive via the socket
- * subscription. So on a slow backend we stop AWAITING the handoff here (it keeps
- * running in the background and projects when it lands) rather than delaying
- * auth resolution.
- */
-const SESSION_HANDOFF_DEADLINE = 6000;
-
-/** The internal commit input — a session plus the zero-cookie device credential
- * (`deviceId` + `deviceSecret`) that is not on the public `SessionLoginResponse`.
- * All extras optional so `SessionLoginResponse` is assignable. */
-interface CommitInput {
-  sessionId: string;
-  accessToken?: string;
-  deviceId?: string;
-  /** Rotating device secret (zero-cookie transport); persisted with `deviceId`
-   * so the cold boot can mint via `POST /session/device/token`. */
-  deviceSecret?: string;
-  expiresAt?: string;
-  userId?: string;
-  /** Minimal user carried by the sign-in response; a best-effort fallback used
-   * only when the full-profile fetch fails. Both `SessionLoginResponse.user`
-   * (structured `name`) and the login-result user (`{id, username?, avatar?}`)
-   * are assignable. */
-  user?: { id: string; username?: string; avatar?: string };
-}
-
-function getHttpStatus(error: unknown): number | undefined {
-  if (!error || typeof error !== 'object') {
-    return undefined;
-  }
-  if ('status' in error) {
-    const status = (error as { status?: unknown }).status;
-    if (typeof status === 'number') {
-      return status;
-    }
-  }
-  if ('response' in error) {
-    const response = (error as { response?: unknown }).response;
-    if (response && typeof response === 'object' && 'status' in response) {
-      const status = (response as { status?: unknown }).status;
-      if (typeof status === 'number') {
-        return status;
-      }
-    }
-  }
-  return undefined;
-}
-
-function isUnauthorizedStatus(error: unknown): boolean {
-  return getHttpStatus(error) === 401;
-}
-
-let cachedUseFollowHook: UseFollowHook | null = null;
-
-const loadUseFollowHook = (): UseFollowHook => {
-  if (cachedUseFollowHook) {
-    return cachedUseFollowHook;
-  }
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const { useFollow } = require('../hooks/useFollow');
-    cachedUseFollowHook = useFollow as UseFollowHook;
-    return cachedUseFollowHook;
-  } catch (error) {
-    if (__DEV__) {
-      loggerUtil.warn(
-        'useFollow hook is not available. Please import useFollow from @oxyhq/services directly.',
-        { component: 'OxyContext', method: 'loadUseFollowHook' },
-        error,
-      );
-    }
-    const fallback: UseFollowHook = () => {
-      throw new Error('useFollow hook is only available in the UI bundle. Import it from @oxyhq/services.');
-    };
-    cachedUseFollowHook = fallback;
-    return cachedUseFollowHook;
-  }
-};
-
 export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   children,
   oxyServices: providedOxyServices,
@@ -358,7 +78,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   authRedirectUri,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
-  coldBoot = true,
+  hubSync = true,
   onAuthStateChange,
   onError,
 }) => {
@@ -554,12 +274,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   markAuthResolvedRef.current = markAuthResolved;
 
   // Server-authoritative device session client. Built ONCE per `oxyServices`
-  // instance. `onUnauthenticated` (a device signout-all pushed over the
-  // bearer-authenticated socket, or bootstrapped as zero-account) clears the
-  // persisted store + local state so a reload does not try to restore a session
-  // the device no longer has. The realtime socket is bearer-only now: a
-  // signed-out tab cannot join any device room, so there is no signed-out sync
-  // wiring here.
+  // instance. Device-scoped sockets connect with deviceId+deviceSecret when no
+  // bearer is planted yet, so cross-origin apps sync via `session_state` after
+  // the one-shot join redirect.
   const sessionClientPairRef = useRef<ReturnType<typeof createSessionClient> | null>(null);
   if (!sessionClientPairRef.current) {
     sessionClientPairRef.current = createSessionClient(
@@ -626,6 +343,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   const syncFromClientRef = useRef(syncFromClient);
   syncFromClientRef.current = syncFromClient;
 
+  const syncDeviceCredentialToHost = useCallback(async (): Promise<void> => {
+    const cred = await loadPersistedDeviceCredential(authStore);
+    sessionClientHost.setDeviceCredential(cred);
+  }, [authStore, sessionClientHost]);
+
   useEffect(() => {
     return sessionClient.subscribe(() => {
       void syncFromClient();
@@ -654,6 +376,15 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     logger,
   });
 
+  // "That wasn't me": repudiating a flagged sign-in IS revoking the device
+  // session that just committed — the same server-authoritative
+  // `sessionClient.signOut(...)` path `logout` uses, which also clears the
+  // persisted device credential + local state when no sibling account remains.
+  // No dedicated "report suspicious" API endpoint exists (or is needed).
+  const revokeSuspiciousSignIn = useCallback(async (): Promise<void> => {
+    await logout();
+  }, [logout]);
+
   const clearAllAccountData = useCallback(async (): Promise<void> => {
     queryClient.clear();
     if (storage) {
@@ -693,6 +424,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       setHasAccessToken(Boolean(accessToken));
       if (accessToken) {
         setTokenReady(true);
+        if (sessionClient.getState()?.accounts.length) {
+          void syncFromClientRef.current();
+        }
         return;
       }
       if (userRef.current || isAuthenticatedRef.current) {
@@ -742,26 +476,31 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // Used by the QR device flow (`handleWebSession`), password sign-in, 2FA
   // completion, and the cold boot.
   const commitSession = useCallback(
-    async (input: CommitInput, options: { activate: boolean }): Promise<void> => {
+    async (
+      input: CommitInput,
+      options: { activate: boolean; hubSync?: boolean },
+    ): Promise<void> => {
       if (input.accessToken) {
         oxyServices.setTokens(input.accessToken);
       }
 
-      // Persist the durable blob when the zero-cookie device credential
-      // (`deviceId` + `deviceSecret`) is present. The cold boot has usually
-      // persisted already; this is idempotent. Without the credential there is
-      // nothing durable to persist and the session lives only for this runtime.
-      if (input.deviceId && input.deviceSecret && input.userId) {
+      // Persist the durable blob when the zero-cookie device credential is present.
+      if (input.deviceId && input.deviceSecret) {
         try {
+          const prior = await authStore.load();
           const next: PersistedAuthState = {
-            sessionId: input.sessionId,
-            userId: input.userId,
+            sessionId: input.sessionId || prior?.sessionId || '',
+            userId: input.userId || prior?.userId || '',
             deviceId: input.deviceId,
             deviceSecret: input.deviceSecret,
             ...(input.accessToken ? { accessToken: input.accessToken } : {}),
             ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
           };
           await authStore.save(next);
+          sessionClientHost.setDeviceCredential({
+            deviceId: input.deviceId,
+            deviceSecret: input.deviceSecret,
+          });
         } catch (persistError) {
           logger('Failed to persist auth state on commit', persistError);
         }
@@ -828,8 +567,22 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         onAuthStateChangeRef.current?.(fullUser);
       }
       markAuthResolvedRef.current();
+
+      if (options.activate && options.hubSync && hubSync && isWebBrowser()) {
+        try {
+          await syncHubAfterSignIn(oxyServices, { enabled: hubSync });
+        } catch (hubError) {
+          if (__DEV__) {
+            loggerUtil.debug(
+              'Hub sync after sign-in failed (non-fatal)',
+              { component: 'OxyContext', method: 'commitSession' },
+              hubError as unknown,
+            );
+          }
+        }
+      }
     },
-    [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, syncFromClient, loginSuccess, logger],
+    [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, sessionClientHost, syncFromClient, loginSuccess, logger, hubSync],
   );
   const commitSessionRef = useRef(commitSession);
   commitSessionRef.current = commitSession;
@@ -853,7 +606,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           userId: session.user.id,
           user: session.user,
         },
-        { activate: true },
+        { activate: true, hubSync: true },
       );
     },
     [commitSession],
@@ -874,10 +627,15 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       oxyServices,
       sessionClient,
       clientId,
+      authRedirectUri,
       locale: currentLanguage,
       commitSession: (session) => handleWebSessionRef.current(session),
       onSignedIn: () => setAccountDialogOpen(false),
       openUrl: (url) => {
+        if (isWebBrowser()) {
+          redirectToAuthorize(url);
+          return;
+        }
         void Linking.openURL(url);
       },
     });
@@ -902,7 +660,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   }, []);
 
   // Expose the live open/close controls to the imperative manager so
-  // `showSignInModal()` (and any app-level imperative "sign in" handler) works.
+  // Imperative `openAccountDialog('signin')` (and app-level sign-in handlers) works.
   useEffect(
     () => registerAccountDialogControls({ open: openAccountDialog, close: closeAccountDialog }),
     [openAccountDialog, closeAccountDialog],
@@ -921,9 +679,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       password: string,
       opts?: { deviceName?: string; deviceFingerprint?: string },
     ): Promise<PasswordSignInResult> => {
+      const persisted = await authStore.load();
       const result = await oxyServices.passwordSignIn(identifier, password, {
         deviceName: opts?.deviceName,
         deviceFingerprint: opts?.deviceFingerprint,
+        deviceId: persisted?.deviceId,
       });
       if ('twoFactorRequired' in result) {
         return { status: '2fa_required', loginToken: result.loginToken };
@@ -939,7 +699,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           userId: result.user.id,
           user: result.user,
         },
-        { activate: true },
+        { activate: true, hubSync: true },
       );
       return { status: 'ok', ...(result.securityAlert ? { securityAlert: result.securityAlert } : {}) };
     },
@@ -953,11 +713,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       backupCode?: string;
       deviceName?: string;
     }): Promise<{ securityAlert?: SecurityAlert }> => {
+      const persisted = await authStore.load();
       const result = await oxyServices.completeTwoFactorSignIn({
         loginToken: params.loginToken,
         token: params.token,
         backupCode: params.backupCode,
         deviceName: params.deviceName,
+        deviceId: persisted?.deviceId,
       });
       await commitSession(
         {
@@ -969,7 +731,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           userId: result.user.id,
           user: result.user,
         },
-        { activate: true },
+        { activate: true, hubSync: true },
       );
       return { securityAlert: result.securityAlert };
     },
@@ -977,84 +739,32 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   );
 
   // ── Cold boot ────────────────────────────────────────────────────────────
-  // The single device-first session restore. Runs ONCE after storage init.
-  // `runSessionColdBoot` resolves the device's session (bootstrap-return →
-  // stored-tokens → shared-key (native) → bootstrap-hop (web)) WITHOUT ever
-  // redirecting to a login page; an unresolved boot ends signed-out and the app
-  // renders its "Sign in with Oxy" affordance. On a winning boot the token is
-  // already planted + persisted, so `onSession` only hands off to the
-  // SessionClient (membership + active account + realtime socket) and marks
-  // auth resolved. `onSignedOut` marks auth resolved with no session.
+  // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
-    setTokenReady(false);
-    try {
-      await runSessionColdBoot({
-        oxy: oxyServices,
-        store: authStore,
-        platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
-        onSession: async (session) => {
-          // Bound how long auth resolution waits for the handoff — the token is
-          // already planted, so on a slow backend we proceed and let the handoff
-          // land asynchronously (the socket subscription re-projects when it does).
-          const handoff = commitSessionRef.current(
-            { sessionId: session.sessionId, accessToken: session.accessToken, userId: session.userId },
-            { activate: false },
-          );
-          let handoffDeadlineId: ReturnType<typeof setTimeout> | undefined;
-          await Promise.race([
-            handoff,
-            new Promise<void>((resolve) => {
-              handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE);
-            }),
-          ]).finally(() => {
-            if (handoffDeadlineId !== undefined) {
-              clearTimeout(handoffDeadlineId);
-            }
-          });
-          markAuthResolvedRef.current();
-        },
-        onSignedOut: () => {
-          // The realtime socket is bearer-only: a signed-out tab cannot join any
-          // device room, so there is no signed-out socket to start here.
-          markAuthResolvedRef.current();
-        },
-        onStepError: (id, error) => {
-          if (__DEV__) {
-            loggerUtil.debug(
-              `Cold-boot step "${id}" errored (non-fatal, falling through)`,
-              { component: 'OxyContext', method: 'runColdBoot' },
-              error,
-            );
-          }
-        },
-      });
-    } catch (error) {
-      if (__DEV__) {
-        loggerUtil.error(
-          'Cold boot error',
-          error instanceof Error ? error : new Error(String(error)),
-          { component: 'OxyContext', method: 'runColdBoot' },
-        );
-      }
-    } finally {
-      // Backstop: resolve on every exit path so the gate can never hang.
-      markAuthResolvedRef.current();
-    }
-  }, [oxyServices, authStore]);
+    await runProviderColdBoot({
+      oxyServices,
+      authStore,
+      clientId: clientIdProp,
+      authRedirectUri,
+      sessionClient,
+      syncDeviceCredentialToHost,
+      commitSession: (input, options) => commitSessionRef.current(input, options),
+      markAuthResolved: () => markAuthResolvedRef.current(),
+      setTokenReady,
+    });
+  }, [
+    oxyServices,
+    authStore,
+    clientIdProp,
+    authRedirectUri,
+    syncDeviceCredentialToHost,
+    sessionClient,
+  ]);
 
   useEffect(() => {
     if (initialized) {
       return;
     }
-    // IdP mode (`coldBoot={false}`): this provider is NOT the ecosystem session
-    // authority, so it never runs the device-first restore. Resolve auth
-    // immediately as signed out so there is no boot spinner; a deliberate sign-in
-    // still commits a normal session.
-    if (!coldBoot) {
-      setInitialized(true);
-      markAuthResolved();
-      return;
-    }
     if (!storage) {
       return;
     }
@@ -1064,7 +774,29 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         logger('Cold boot failed', error);
       }
     });
-  }, [coldBoot, runColdBoot, storage, initialized, logger, markAuthResolved]);
+  }, [runColdBoot, storage, initialized, logger]);
+
+  // Reconcile device state when the tab returns to foreground (background tabs may
+  // miss socket pushes or have stale bearer tokens).
+  useEffect(() => {
+    if (!isWebBrowser()) return;
+    const onVisibility = (): void => {
+      if (document.visibilityState !== 'visible') return;
+      const reconcile = async (): Promise<void> => {
+        if (!oxyServices.getAccessToken() && sessionClientHost.getDeviceCredential()) {
+          await refreshPersistedSession({ oxy: oxyServices, store: authStore });
+        }
+        if (!oxyServices.getAccessToken() && !sessionClientHost.getDeviceCredential()) {
+          return;
+        }
+        await sessionClient.bootstrap();
+        await syncFromClient();
+      };
+      void reconcile().catch(() => undefined);
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    return () => document.removeEventListener('visibilitychange', onVisibility);
+  }, [oxyServices, sessionClient, sessionClientHost, authStore, syncFromClient]);
 
   // Exposed `refreshSessions`: re-bootstrap the server-authoritative device
   // state and reproject — the manual counterpart to the realtime socket.
@@ -1113,87 +845,18 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     showBottomSheet: showBottomSheetForContext,
   });
 
-  // ── Account graph ──────────────────────────────────────────────────────────
-  const [accounts, setAccounts] = useState<AccountNode[]>([]);
-
-  const refreshAccounts = useCallback(async (): Promise<void> => {
-    if (!isAuthenticated || !tokenReady || !oxyServices.getAccessToken()) {
-      setAccounts([]);
-      return;
-    }
-    try {
-      const list = await oxyServices.listAccounts();
-      setAccounts(list);
-    } catch (err) {
-      if (isUnauthorizedStatus(err)) {
-        setAccounts([]);
-        await clearSessionStateRef.current();
-        return;
-      }
-      if (__DEV__) {
-        loggerUtil.debug('Failed to load accounts', { component: 'OxyContext' }, err as unknown);
-      }
-    }
-  }, [isAuthenticated, oxyServices, tokenReady]);
-
-  useEffect(() => {
-    if (isAuthenticated && initialized && tokenReady) {
-      refreshAccounts();
-      // Reload the dialog's own account graph too, so a session restored OUTSIDE
-      // the dialog (cold boot / password sign-in) surfaces its graph accounts.
-      void accountDialogControllerRef.current?.refresh();
-    }
-  }, [isAuthenticated, initialized, tokenReady, refreshAccounts]);
-
-  const runPostAccountSwitchSideEffects = useCallback(async (): Promise<void> => {
-    await refreshAccounts();
-    queryClient.invalidateQueries();
-  }, [refreshAccounts, queryClient]);
-
-  // Switch the active session INTO an account from the unified graph. In the
-  // real-session model this is identical to switching device sign-ins.
-  const switchToAccount = useCallback(
-    async (accountId: string): Promise<void> => {
-      const deviceState = sessionClient.getState();
-      if (deviceState?.accounts.some((account) => account.accountId === accountId)) {
-        await sessionClient.switchAccount(accountId);
-        await syncFromClient();
-        await runPostAccountSwitchSideEffects();
-        return;
-      }
-
-      const result = await oxyServices.switchToAccount(accountId);
-      if (!result?.user || !result?.sessionId) {
-        throw new Error('Account switch did not return a valid session');
-      }
-      // `oxyServices.switchToAccount` already planted the access token; commit
-      // the minted session through the shared funnel (persist + register +
-      // hydrate) as a deliberate activation.
-      await commitSession(
-        {
-          sessionId: result.sessionId,
-          accessToken: result.accessToken,
-          deviceSecret: (result as { deviceSecret?: string }).deviceSecret,
-          deviceId: result.deviceId,
-          expiresAt: result.expiresAt,
-          userId: result.user.id,
-          user: result.user,
-        },
-        { activate: true },
-      );
-      await runPostAccountSwitchSideEffects();
-    },
-    [oxyServices, sessionClient, syncFromClient, commitSession, runPostAccountSwitchSideEffects],
-  );
-
-  const createAccountFn = useCallback(
-    async (data: CreateAccountInput): Promise<AccountNode> => {
-      const account = await oxyServices.createAccount(data);
-      await refreshAccounts();
-      return account;
-    },
-    [oxyServices, refreshAccounts],
-  );
+  const { accounts, refreshAccounts, switchToAccount, createAccount: createAccountFn } = useOxyAccountGraph({
+    isAuthenticated,
+    tokenReady,
+    initialized,
+    oxyServices,
+    sessionClient,
+    syncFromClient,
+    commitSession,
+    queryClient,
+    accountDialogControllerRef,
+    clearSessionStateRef,
+  });
 
   const canUsePrivateApi = authResolved && isAuthenticated && tokenReady && hasAccessToken;
   const isPrivateApiPending = !authResolved || (isAuthenticated && (!tokenReady || !hasAccessToken));
@@ -1221,6 +884,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       signIn,
       signInWithPassword,
       completeTwoFactorSignIn,
+      revokeSuspiciousSignIn,
       handleWebSession,
       logout,
       logoutAll,
@@ -1270,6 +934,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       signIn,
       signInWithPassword,
       completeTwoFactorSignIn,
+      revokeSuspiciousSignIn,
       handleWebSession,
       logout,
       logoutAll,
@@ -1337,6 +1002,7 @@ const LOADING_STATE: OxyContextState = {
   signIn: () => rejectMissingProvider<User>(),
   signInWithPassword: () => rejectMissingProvider<PasswordSignInResult>(),
   completeTwoFactorSignIn: () => rejectMissingProvider<{ securityAlert?: SecurityAlert }>(),
+  revokeSuspiciousSignIn: () => rejectMissingProvider<void>(),
   handleWebSession: () => rejectMissingProvider<void>(),
   logout: () => rejectMissingProvider<void>(),
   logoutAll: () => rejectMissingProvider<void>(),
@@ -1360,7 +1026,7 @@ const LOADING_STATE: OxyContextState = {
   accounts: [],
   switchToAccount: () => rejectMissingProvider<void>(),
   refreshAccounts: () => rejectMissingProvider<void>(),
-  createAccount: () => rejectMissingProvider<AccountNode>(),
+  createAccount: () => rejectMissingProvider<import('@oxyhq/core').AccountNode>(),
 };
 
 export const useOxy = (): OxyContextState => {