@oxyhq/services 22.12.5 → 22.12.7

package/src/ui/context/OxyContext.tsx

@@ -21,6 +21,7 @@ import type {
 } from '@oxyhq/core';
 import {
   KeyManager,
+  establishIdentitySession,
   installAuthRefreshHandler,
   startTokenRefreshScheduler,
   createAccountDialogController,
@@ -33,7 +34,13 @@ import {
 } from '../navigation/accountDialogManager';
 import { redirectToAuthorize } from '../components/oauthNavigation';
 import { openPasskeyHubPopup } from '../components/passkeyHubPopup';
+import {
+  startWebOAuthSignIn,
+  type StartWebOAuthSignInOptions,
+} from '../oauth/browserAuthTransport';
+import type { WebOAuthSignInResult } from '../oauth/types';
 import { isWebBrowser } from '../utils/isWebBrowser';
+import { resolveDeliveryPlatform } from '../utils/deliveryPlatform';
 import { runProviderColdBoot } from '../boot/runProviderColdBoot';
 import { loadPersistedDeviceCredential } from '../utils/deviceCredential';
 import { useAuthStore, type AuthState } from '../stores/authStore';
@@ -57,11 +64,14 @@ import { useAvatarPicker } from '../hooks/useAvatarPicker';
 import { useAccountStore } from '../stores/accountStore';
 import {
   createSessionClient,
+  createIdentitySessionBinding,
   createPlatformAuthStateStore,
   deviceStateToClientSessions,
   activeSessionIdOf,
   activeUserOf,
   accountIdsOf,
+  IdentityBoundSessionError,
+  type IdentitySessionBinding,
 } from '../session';
 import type {
   OxyContextState,
@@ -69,7 +79,7 @@ import type {
   CommitInput,
 } from './oxyContextTypes';
 import { DEFAULT_SESSION_VALIDITY_MS, loadUseFollowHook } from './oxyContextHelpers';
-import { commitDeviceSetAndResolve } from './commitSessionFlow';
+import { commitDeviceSetAndResolve, maybeSyncHubAfterCommit } from './commitSessionFlow';
 import { runPasskeyLogin, runPasskeyRegister, runPasskeyAdd } from './passkeyFlow';
 import {
   isPasskeySupported,
@@ -92,6 +102,8 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   authorizeBaseUrl,
   storageKeyPrefix = 'oxy_session',
   clientId: clientIdProp,
+  sessionMode = 'account',
+  webAuthMode = 'redirect',
   hubSync = true,
   onAuthStateChange,
   onError,
@@ -119,6 +131,23 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   }
   const authStore = authStoreRef.current;
 
+  // Identity-bound session binding (`sessionMode: 'identity'`) — the platform pin
+  // store plus the memoised pinned account id every lane below binds to. Built
+  // ONCE per provider mount and ONLY in identity mode: an account-mode provider
+  // never constructs one, so `identity` is `null` there and every branch keyed on
+  // it collapses to today's behaviour.
+  //
+  // Like `oxyServices` / `baseURL`, `sessionMode` is mount-time configuration: it
+  // is read once and a later change does not re-bind the provider. Latching it
+  // this way also fails SAFE — a provider that started identity-bound can never
+  // be downgraded mid-flight into following the device's active account.
+  const identityRef = useRef<IdentitySessionBinding | null>(null);
+  if (sessionMode === 'identity' && !identityRef.current) {
+    identityRef.current = createIdentitySessionBinding();
+  }
+  const identity = identityRef.current;
+  const isIdentityBound = identity !== null;
+
   const {
     user,
     isAuthenticated,
@@ -309,10 +338,65 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           logger('Failed to clear local state on remote sign-out', clearError);
         });
       },
+      // `null` for every account-mode provider — identical to omitting the
+      // option — and the pinned account id once an identity-bound provider has
+      // resolved its pin. Read through the ref so the resolver stays stable for
+      // the client's lifetime while still seeing later resolutions.
+      () => identityRef.current?.getPinnedAccountId() ?? null,
     );
   }
   const { client: sessionClient, host: sessionClientHost } = sessionClientPairRef.current;
 
+  // Re-establishment lane for an identity-bound provider whose pin is missing or
+  // whose pinned account is no longer part of this device's session set (another
+  // app signed it out, or the device was re-provisioned). Adopting whichever
+  // account the device is currently switched to is exactly the drift
+  // `sessionMode: 'identity'` exists to prevent, so the only correct answer is to
+  // re-derive the session from the local identity key.
+  //
+  // Bounded on purpose: at most ONE attempt per applied device revision, and
+  // never two concurrently — a repeated failure (locked keychain, offline, no
+  // local identity) must never spin a sign-in loop against the server. Nothing
+  // awaits it, so it can never deadlock against the projection that triggers it;
+  // the `bootstrap()` below re-applies device state, whose notify re-runs the
+  // projection with the pin now resolved.
+  const identityEstablishRef = useRef<{ revision: number | null; inFlight: boolean }>({
+    revision: null,
+    inFlight: false,
+  });
+
+  const reestablishIdentitySession = useCallback(
+    (binding: IdentitySessionBinding, revision: number): void => {
+      const tracker = identityEstablishRef.current;
+      if (tracker.inFlight || tracker.revision === revision) {
+        return;
+      }
+      tracker.revision = revision;
+      tracker.inFlight = true;
+      void (async () => {
+        const established = await establishIdentitySession({
+          oxy: oxyServices,
+          store: authStore,
+          binding: binding.binding,
+        });
+        if (!established) {
+          return;
+        }
+        // The verify wrote a fresh pin; adopt it before re-reading device state
+        // so the notify that follows projects against the new binding.
+        await binding.refreshPinnedAccountId();
+        await sessionClient.bootstrap();
+      })()
+        .catch((establishError) => {
+          logger('Failed to re-establish the identity-bound session', establishError);
+        })
+        .finally(() => {
+          tracker.inFlight = false;
+        });
+    },
+    [oxyServices, authStore, sessionClient, logger],
+  );
+
   // Projects `client.getState()` onto the exposed `sessions`/`activeSessionId`/
   // `user`. Sole authority for both locally-initiated mutations (switch/logout)
   // AND remotely-pushed `session_state` over the `device:<deviceId>` socket.
@@ -334,6 +418,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     // Last-write-wins guard: capture the revision this projection is for, then
     // after the async profile fetch bail if a fresher state has landed.
     const capturedRevision = state.revision;
+    // Resolve the pin BEFORE the profile fetch (memoised: one storage + keychain
+    // read per boot) so every projection below is bound on the FIRST pass over a
+    // freshly applied state. Deferring it would let a sibling app's switch render
+    // once as this client's user before the pin corrected it. `null` for every
+    // account-mode provider, where each projection falls back to the device's
+    // active account exactly as before.
+    const pinnedAccountId = identity ? await identity.ensurePinnedAccountId() : null;
     const ids = accountIdsOf(state);
     let users: User[] = [];
     try {
@@ -346,16 +437,29 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     if (!latest || latest.revision !== capturedRevision) {
       return;
     }
+    if (identity && (pinnedAccountId === null || activeSessionIdOf(latest, pinnedAccountId) === null)) {
+      // Either no verified pin, or the pinned account left this device's session
+      // set. Projecting anything here would mean projecting SOMEBODY ELSE's
+      // account, so leave the current projection untouched and re-derive the
+      // session from the local identity key instead.
+      reestablishIdentitySession(identity, latest.revision);
+      return;
+    }
     const usersById = new Map(users.map((resolvedUser) => [resolvedUser.id, resolvedUser]));
-    updateSessions(deviceStateToClientSessions(latest, usersById));
-    setActiveSessionId(activeSessionIdOf(latest));
-    const activeUser = activeUserOf(latest, usersById);
+    updateSessions(deviceStateToClientSessions(latest, usersById, pinnedAccountId));
+    setActiveSessionId(activeSessionIdOf(latest, pinnedAccountId));
+    const activeUser = activeUserOf(latest, usersById, pinnedAccountId);
     if (activeUser) {
       loginSuccess(activeUser);
     }
-    sessionClientHost.setCurrentAccountId(latest.activeAccountId);
+    // The host's current account feeds the socket handshake and the bearer's
+    // token-account comparisons, so it tracks the PIN — never the account another
+    // app switched the device to.
+    sessionClientHost.setCurrentAccountId(pinnedAccountId ?? latest.activeAccountId);
   }, [
+    identity,
     oxyServices,
+    reestablishIdentitySession,
     sessionClient,
     sessionClientHost,
     updateSessions,
@@ -483,14 +587,21 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // credential via `POST /session/device/token`) plus the proactive scheduler
   // that refreshes ~60s before expiry and on tab-focus. Replaces the deleted
   // services-local `inSessionTokenRefresh` module.
+  // An identity binding turns every re-mint pinned: it targets the pinned
+  // account instead of the device's active one, and its recovery arm becomes the
+  // PRIMARY-key identity sign-in rather than the cross-app shared keychain.
   useEffect(() => {
-    const dispose = installAuthRefreshHandler({ oxy: oxyServices, store: authStore });
+    const dispose = installAuthRefreshHandler({
+      oxy: oxyServices,
+      store: authStore,
+      ...(identity ? { identity: identity.binding } : {}),
+    });
     const scheduler = startTokenRefreshScheduler(oxyServices);
     return () => {
       scheduler.dispose();
       dispose();
     };
-  }, [oxyServices, authStore]);
+  }, [oxyServices, authStore, identity]);
 
   // ── Session commit funnel ────────────────────────────────────────────────
   // The single place a session becomes committed: plant tokens, persist the
@@ -571,21 +682,20 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         markAuthResolved: 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,
-            );
-          }
-        }
-      }
+      // Post-sign-in hub sync — a full-page redirect to auth.oxy.so. Gated HERE,
+      // inside the ONE commit funnel, so NO commit path (QR device flow,
+      // password/2FA through the account dialog, passkey, popup OAuth, cold
+      // boot) can bounce a `webAuthMode: 'popup'` tab to the IdP. See
+      // `maybeSyncHubAfterCommit` for the full gate list.
+      await maybeSyncHubAfterCommit({
+        activate: options.activate,
+        hubSyncRequested: options.hubSync === true,
+        hubSyncEnabled: hubSync,
+        webAuthMode,
+        syncHub: () => syncHubAfterSignIn(oxyServices, { enabled: hubSync }),
+      });
     },
-    [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, sessionClientHost, syncFromClient, loginSuccess, logger, hubSync],
+    [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, sessionClientHost, syncFromClient, loginSuccess, logger, hubSync, webAuthMode],
   );
   const commitSessionRef = useRef(commitSession);
   commitSessionRef.current = commitSession;
@@ -638,6 +748,33 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     [commitSession],
   );
 
+  // ── Web third-party OAuth sign-in ──────────────────────────────────────────
+  // The shared operation `OxySignInButton` (and any RP-owned button) delegates
+  // to, so no consumer ever writes popup listeners or a token exchange. The
+  // transport picks popup vs redirect from `webAuthMode`; both lanes land on the
+  // SAME completion path (`completeOAuthCode`) and the same commit funnel here.
+  //
+  // `hubSync: false` is deliberate: hub sync is a full-page redirect to
+  // auth.oxy.so, which would undo the one thing popup mode exists to guarantee —
+  // that the relying party never leaves its route. It matches how the redirect
+  // lane's return leg commits (see `runProviderColdBoot`).
+  const startWebOAuthSignInForContext = useCallback(
+    (options: StartWebOAuthSignInOptions): Promise<WebOAuthSignInResult> =>
+      startWebOAuthSignIn(
+        {
+          mode: webAuthMode,
+          oxyServices,
+          clientId,
+          authorizeBaseUrl,
+          identityBound: isIdentityBound,
+          commitSession: (input) =>
+            commitSessionRef.current(input, { activate: true, hubSync: false }),
+        },
+        options,
+      ),
+    [webAuthMode, oxyServices, clientId, authorizeBaseUrl, isIdentityBound],
+  );
+
   // ── Unified account dialog ─────────────────────────────────────────────────
   // The single account-chooser + sign-in surface. Built ONCE per provider mount
   // and bound to the live `oxyServices` + `sessionClient` + this provider's
@@ -679,8 +816,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     accountDialogSurfaceRef.current?.dismiss();
   }, []);
 
+  // Never built while identity-bound: the dialog exists to CHOOSE an account,
+  // and an identity-bound client has exactly one — the owner of the local
+  // identity key. Leaving it `null` (the same shape consumers see with no
+  // provider mounted) keeps its QR/polling machinery off entirely instead of
+  // relying on UI-level filtering to hide it.
   const accountDialogControllerRef = useRef<AccountDialogController | null>(null);
-  if (!accountDialogControllerRef.current) {
+  if (!isIdentityBound && !accountDialogControllerRef.current) {
     accountDialogControllerRef.current = createAccountDialogController({
       oxyServices,
       sessionClient,
@@ -714,11 +856,27 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       // popup concept there, and off-origin passkey sign-in isn't reachable
       // (Commons owns the native flow).
       openPopup: isWebBrowser() ? openPasskeyHubPopup : undefined,
+      // Which surface a sign-in starts from — a FACT only this consumer can
+      // supply (headless core never touches a platform global). It decides
+      // whether automatic delivery may take the same-device Commons deep link;
+      // without it the controller stays `'unknown'` and that route never fires.
+      platform: resolveDeliveryPlatform(),
     });
   }
   const accountDialogController = accountDialogControllerRef.current;
 
   const openAccountDialog = useCallback((view?: AccountDialogView): void => {
+    if (isIdentityBound) {
+      // No controller was built, and there is nothing to choose: this app's user
+      // is fixed to the owner of the local identity key.
+      if (__DEV__) {
+        loggerUtil.warn(
+          'openAccountDialog ignored: the session is identity-bound (sessionMode: "identity")',
+          { component: 'OxyContext', method: 'openAccountDialog' },
+        );
+      }
+      return;
+    }
     const nextView = view ?? 'accounts';
     accountDialogControllerRef.current?.setView(nextView);
 
@@ -762,7 +920,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       }
     });
     setAccountDialogOpen(true);
-  }, []);
+  }, [isIdentityBound]);
 
   const closeAccountDialog = useCallback((): void => {
     accountDialogControllerRef.current?.cancelSignIn();
@@ -867,24 +1025,46 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // ── Cold boot ────────────────────────────────────────────────────────────
   // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
+    // Resolve the pin BEFORE any boot lane runs: `getPinnedAccountId()` is a
+    // SYNCHRONOUS read on `SessionClient`'s apply path, and a stale `null` there
+    // would let a pinned client behave like an account-mode one for the first
+    // state it applies (including re-electing the device's active account).
+    if (identity) {
+      await identity.ensurePinnedAccountId();
+    }
     await runProviderColdBoot({
       oxyServices,
       authStore,
       clientId: clientIdProp,
       authRedirectUri,
       authorizeBaseUrl,
+      sessionMode,
+      identity: identity?.binding,
+      // Popup mode forbids the boot's automatic full-page `prompt=none` restore:
+      // a domain with no local credential resolves signed out instead of
+      // navigating the tab to the IdP (see `allowsAutomaticIdpRedirect`).
+      webAuthMode,
       sessionClient,
       syncDeviceCredentialToHost,
       commitSession: (input, options) => commitSessionRef.current(input, options),
       markAuthResolved: () => markAuthResolvedRef.current(),
       setTokenReady,
     });
+    // The boot may have (re-)established the identity session or cleared a pin
+    // whose key no longer exists, so re-resolve rather than trusting the memo
+    // taken before it ran.
+    if (identity) {
+      await identity.refreshPinnedAccountId();
+    }
   }, [
     oxyServices,
     authStore,
     clientIdProp,
     authRedirectUri,
     authorizeBaseUrl,
+    sessionMode,
+    identity,
+    webAuthMode,
     syncDeviceCredentialToHost,
     sessionClient,
   ]);
@@ -974,8 +1154,14 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // Exposed `switchSession`: route through the server-authoritative
   // `SessionClient`. Resolve the target account from the current device state,
   // ask the server to switch, reproject, and return the now-active user.
+  //
+  // Identity-bound providers reject: this is the session-keyed twin of
+  // `switchToAccount`, so leaving it live would be a bypass around the same rule.
   const switchSessionForContext = useCallback(
     async (sessionId: string): Promise<User> => {
+      if (isIdentityBound) {
+        throw new IdentityBoundSessionError('switchSession');
+      }
       const targetAccountId = sessionClient
         .getState()
         ?.accounts.find((account) => account.sessionId === sessionId)?.accountId;
@@ -990,7 +1176,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       }
       return activeUser;
     },
-    [sessionClient, syncFromClient],
+    [isIdentityBound, sessionClient, syncFromClient],
   );
 
   // Thin passthroughs to the platform-agnostic KeyManager. NOTE: both now THROW
@@ -1021,6 +1207,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     isAuthenticated,
     tokenReady,
     initialized,
+    identityBound: isIdentityBound,
     oxyServices,
     sessionClient,
     syncFromClient,
@@ -1046,6 +1233,8 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       isPrivateApiPending,
       isAuthResolved: authResolved,
       isStorageReady: storage !== null,
+      sessionMode: isIdentityBound ? 'identity' : 'account',
+      webAuthMode,
       error,
       currentLanguage,
       currentLanguages,
@@ -1061,6 +1250,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       removePasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
+      startWebOAuthSignIn: startWebOAuthSignInForContext,
       logout,
       logoutAll,
       switchSession: switchSessionForContext,
@@ -1100,6 +1290,8 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       isPrivateApiPending,
       authResolved,
       storage,
+      isIdentityBound,
+      webAuthMode,
       error,
       currentLanguage,
       currentLanguages,
@@ -1115,6 +1307,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       removePasskey,
       revokeSuspiciousSignIn,
       handleWebSession,
+      startWebOAuthSignInForContext,
       logout,
       logoutAll,
       switchSessionForContext,
@@ -1172,6 +1365,8 @@ const LOADING_STATE: OxyContextState = {
   isPrivateApiPending: true,
   isAuthResolved: false,
   isStorageReady: false,
+  sessionMode: 'account',
+  webAuthMode: 'redirect',
   error: null,
   currentLanguage: 'en-US',
   currentLanguages: [],
@@ -1187,6 +1382,7 @@ const LOADING_STATE: OxyContextState = {
   removePasskey: () => rejectMissingProvider<void>(),
   revokeSuspiciousSignIn: () => rejectMissingProvider<void>(),
   handleWebSession: () => rejectMissingProvider<void>(),
+  startWebOAuthSignIn: () => rejectMissingProvider<WebOAuthSignInResult>(),
   logout: () => rejectMissingProvider<void>(),
   logoutAll: () => rejectMissingProvider<void>(),
   switchSession: () => rejectMissingProvider<User>(),

package/src/ui/context/__tests__/commitSessionFlow.test.ts

@@ -1,8 +1,11 @@
 import type { User } from '@oxyhq/core';
 import { logger } from '@oxyhq/core';
+import type { WebAuthMode } from '../../oauth/types';
 import {
   commitDeviceSetAndResolve,
+  maybeSyncHubAfterCommit,
   type CommitDeviceSetAndResolveDeps,
+  type MaybeSyncHubAfterCommitDeps,
 } from '../commitSessionFlow';
 
 // A resolved promise chain (addCurrentAccount -> start -> syncFromClient) settles
@@ -178,6 +181,92 @@ describe('commitDeviceSetAndResolve — cold boot (activate: false)', () => {
   });
 });
 
+/**
+ * Post-sign-in hub sync is a FULL-PAGE redirect to auth.oxy.so. It runs from the
+ * ONE commit funnel, so gating it here gates every commit path at once —
+ * `webAuthMode: 'popup'` must never bounce the tab, whichever path signed the
+ * user in (#691 phase 7).
+ */
+describe('maybeSyncHubAfterCommit — webAuthMode transport gate (#691 phase 7)', () => {
+  const buildHubDeps = (
+    overrides: Partial<MaybeSyncHubAfterCommitDeps> = {},
+  ): MaybeSyncHubAfterCommitDeps => ({
+    activate: true,
+    hubSyncRequested: true,
+    hubSyncEnabled: true,
+    webAuthMode: 'redirect',
+    syncHub: jest.fn(async () => true),
+    ...overrides,
+  });
+
+  it("redirect mode: syncs the hub after a deliberate sign-in (unchanged)", async () => {
+    const deps = buildHubDeps();
+
+    await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(true);
+
+    expect(deps.syncHub).toHaveBeenCalledTimes(1);
+  });
+
+  it('popup mode: NEVER syncs the hub, even on an otherwise-eligible sign-in', async () => {
+    const deps = buildHubDeps({ webAuthMode: 'popup' });
+
+    await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+
+    expect(deps.syncHub).not.toHaveBeenCalled();
+  });
+
+  it('popup mode: no commit path can opt back in', async () => {
+    // Every commit path differs only in `activate` / `hubSyncRequested`; the
+    // transport gate outranks all of them.
+    for (const activate of [true, false]) {
+      for (const hubSyncRequested of [true, false]) {
+        const deps = buildHubDeps({ webAuthMode: 'popup', activate, hubSyncRequested });
+        await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+        expect(deps.syncHub).not.toHaveBeenCalled();
+      }
+    }
+  });
+
+  it.each(['popup', 'redirect'] as const)(
+    'never syncs on a cold-boot restore, in either mode (%s)',
+    async (webAuthMode: WebAuthMode) => {
+      const deps = buildHubDeps({ webAuthMode, activate: false });
+
+      await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+
+      expect(deps.syncHub).not.toHaveBeenCalled();
+    },
+  );
+
+  it('redirect mode: honours the per-commit opt-out (account switch / popup OAuth lanes)', async () => {
+    const deps = buildHubDeps({ hubSyncRequested: false });
+
+    await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+
+    expect(deps.syncHub).not.toHaveBeenCalled();
+  });
+
+  it('redirect mode: honours the provider-level hubSync opt-out', async () => {
+    const deps = buildHubDeps({ hubSyncEnabled: false });
+
+    await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+
+    expect(deps.syncHub).not.toHaveBeenCalled();
+  });
+
+  it('redirect mode: a failing hub sync is non-fatal and never rejects', async () => {
+    const deps = buildHubDeps({
+      syncHub: jest.fn(async () => {
+        throw new Error('hub ticket failed');
+      }),
+    });
+
+    await expect(maybeSyncHubAfterCommit(deps)).resolves.toBe(false);
+
+    expect(deps.syncHub).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('commitDeviceSetAndResolve — deliberate sign-in (activate: true)', () => {
   it('BLOCKS on the device-set reconcile before resolving auth (unchanged ordering)', async () => {
     const order: string[] = [];

package/src/ui/context/commitSessionFlow.ts

@@ -1,5 +1,8 @@
 import type { User } from '@oxyhq/core';
 import { logger as loggerUtil } from '@oxyhq/core';
+import { allowsAutomaticIdpRedirect } from '../oauth/legacyRedirectLanes';
+import type { WebAuthMode } from '../oauth/types';
+import { isWebBrowser } from '../utils/isWebBrowser';
 import { isUnauthorizedStatus } from './oxyContextHelpers';
 
 const LOG_CONTEXT = { component: 'OxyContext', method: 'commitSession' } as const;
@@ -123,3 +126,61 @@ export async function commitDeviceSetAndResolve(
   await hydrateAndResolve();
   void reconcileDeviceSet().catch(logReconcileError);
 }
+
+export interface MaybeSyncHubAfterCommitDeps {
+  /** Deliberate sign-in (`true`) vs. a cold-boot / background commit (`false`). */
+  activate: boolean;
+  /** Per-commit opt-in — `commitSession`'s `options.hubSync`. */
+  hubSyncRequested: boolean;
+  /** Provider-level opt-out — `OxyProviderProps.hubSync`. */
+  hubSyncEnabled: boolean;
+  /**
+   * The provider's web sign-in transport — `OxyProviderProps.webAuthMode`.
+   * A first-class input: `'popup'` forbids the redirect outright.
+   */
+  webAuthMode: WebAuthMode;
+  /**
+   * Starts the full-page hop to `auth.oxy.so/sync`; resolves `true` when the
+   * navigation was actually started.
+   */
+  syncHub: () => Promise<boolean>;
+}
+
+/**
+ * Post-sign-in hub sync: plant this device's credential on the IdP hub so OTHER
+ * official origins can silently restore a session on their next cold boot.
+ *
+ * The tail of the ONE commit funnel (`commitSession`), extracted so every gate
+ * on this legacy lane lives — and is tested — in one place. Returns whether the
+ * full-page redirect was started; a failure is non-fatal and never propagates
+ * (the sign-in itself already succeeded).
+ *
+ * Four gates, all of which must pass:
+ * 1. `activate` — only a deliberate sign-in syncs; a cold-boot restore never does.
+ * 2. `hubSyncRequested` — the in-place lanes (account switch, popup OAuth) opt out.
+ * 3. `hubSyncEnabled` — the provider-level `hubSync` prop.
+ * 4. `allowsAutomaticIdpRedirect(webAuthMode)` — hub sync REPLACES the document
+ *    with `auth.oxy.so`, so `webAuthMode: 'popup'` forbids it: a redirect that
+ *    bounces the tab defeats the entire point of the mode, no matter which
+ *    commit path produced the session (issue #691, "Cold boot and cross-domain
+ *    behavior"). Redirect mode — the default and the compatibility path — is
+ *    unchanged, and this whole function disappears with it in phase 7b.
+ */
+export async function maybeSyncHubAfterCommit(
+  deps: MaybeSyncHubAfterCommitDeps,
+): Promise<boolean> {
+  const { activate, hubSyncRequested, hubSyncEnabled, webAuthMode, syncHub } = deps;
+
+  if (!activate || !hubSyncRequested || !hubSyncEnabled) return false;
+  if (!allowsAutomaticIdpRedirect(webAuthMode)) return false;
+  if (!isWebBrowser()) return false;
+
+  try {
+    return await syncHub();
+  } catch (hubError) {
+    if (__DEV__) {
+      loggerUtil.debug('Hub sync after sign-in failed (non-fatal)', LOG_CONTEXT, hubError);
+    }
+    return false;
+  }
+}