@oxyhq/services 12.1.0 → 12.2.0

package/lib/typescript/module/utils/crossApex.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cross-apex web detection for sign-in durability gating.
+ *
+ * On a web Relying Party whose registrable apex differs from the central Oxy
+ * Identity Provider apex (`oxy.so`), the ONLY sign-in completion that survives a
+ * page reload is the interactive "Continue with Oxy" IdP flow, because it is the
+ * only one that establishes a first-party `fedcm_session` cookie at
+ * `auth.<apex>` — the anchor the cross-domain cold-boot restore reads on reload.
+ *
+ * The other sign-in completions the SDK can drive do NOT plant a `fedcm_session`:
+ *   - password / public-key sign-in mints a bearer directly against the Oxy API
+ *     (its refresh cookie is host-scoped to `api.oxy.so` and `SameSite=Lax`, so
+ *     it is unreachable cross-site from the RP), and
+ *   - the Commons-app device-flow handoff (cross-device QR / same-device
+ *     deep-link) is approved OUTSIDE the browser, so no IdP browser session is
+ *     established.
+ * On a cross-apex RP each of these leaves the user signed in for the current
+ * page only — a reload logs them out. See OxyHQServices AGENTS.md
+ * "Auth / Session Contract".
+ *
+ * Same-apex `*.oxy.so` apps (e.g. `accounts.oxy.so`) are first-party with
+ * `api.oxy.so`: their refresh cookie rides same-site requests so reload restore
+ * works without `fedcm_session`, and they are therefore NOT gated.
+ *
+ * Returns `false` off-browser (React Native has no `window.location`) and for
+ * hosts without a registrable apex (localhost / raw IP / single-label dev
+ * hosts), so native and local development keep every sign-in method.
+ */
+/**
+ * Whether the given host is a web RP on a registrable apex other than the
+ * central Oxy IdP apex (`oxy.so`). See the module doc for why this gates the
+ * non-durable sign-in paths.
+ *
+ * @param hostname - The host to classify. Defaults to the current
+ *   `window.location.hostname`; resolves to `undefined` off-browser (React
+ *   Native / SSR), which yields `false`. The explicit parameter mirrors
+ *   `autoDetectAuthWebUrl(location?)` and keeps the predicate unit-testable
+ *   without manipulating the global `window.location`.
+ */
+export declare function isCrossApexWeb(hostname?: string | undefined): boolean;
+/**
+ * Thrown when an app attempts a direct (non-IdP) sign-in — password or
+ * public-key — on a cross-apex web RP, where such a sign-in would not survive a
+ * page reload because no `fedcm_session` is established (see {@link isCrossApexWeb}).
+ *
+ * Apps on a cross-apex apex must sign in through the interactive
+ * "Continue with Oxy" IdP flow (`OxySignInButton` / `showSignInModal()`), which
+ * plants the durable session.
+ */
+export declare class CrossApexDirectSignInError extends Error {
+    readonly name = "CrossApexDirectSignInError";
+    readonly code = "CROSS_APEX_DIRECT_SIGN_IN_UNSUPPORTED";
+    constructor();
+}
+//# sourceMappingURL=crossApex.d.ts.map

package/lib/typescript/module/utils/crossApex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crossApex.d.ts","sourceRoot":"","sources":["../../../../src/utils/crossApex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,GAAE,MAAM,GAAG,SAEN,GACZ,OAAO,CAMT;AAED;;;;;;;;GAQG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAkB,IAAI,gCAAgC;IACtD,QAAQ,CAAC,IAAI,2CAA2C;;CASzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/index.ts

@@ -180,6 +180,10 @@ export {
     extractErrorMessage,
 } from './ui/utils/errorHandlers';
 export type { HandleAuthErrorOptions } from './ui/utils/errorHandlers';
+// Thrown by `signInWithPassword` / `signIn` on a cross-apex web RP, where a
+// direct (non-IdP) sign-in would not survive a page reload — apps catch it to
+// route the user to the durable "Continue with Oxy" IdP flow.
+export { CrossApexDirectSignInError, isCrossApexWeb } from './utils/crossApex';
 
 // ---------------------------------------------------------------------------
 // File filtering

package/src/ui/components/SignInModal.tsx

@@ -30,6 +30,7 @@ import { useOxy } from '../context/OxyContext';
 import OxyLogo from './OxyLogo';
 import AnotherDeviceQR from './AnotherDeviceQR';
 import { useOxyAuthSession, OXY_ACCOUNTS_WEB_URL } from '../hooks/useOxyAuthSession';
+import { isCrossApexWeb } from '../../utils/crossApex';
 
 // Store for modal visibility with subscription support
 let modalVisible = false;
@@ -110,6 +111,12 @@ const SignInModalContent: React.FC<SignInModalContentProps> = ({
         { onSignedIn: hideSignInModal },
     );
 
+    // On a cross-apex web RP, only the "Continue with Oxy" IdP popup establishes
+    // a durable `fedcm_session`. The Commons-app handoffs (same-device deep-link
+    // + cross-device QR) approve OUTSIDE the browser, so they leave no IdP
+    // session and the user would be logged out on reload — hide them there.
+    const crossApexWeb = isCrossApexWeb();
+
     // Entrance animation.
     const opacity = useSharedValue(0);
     const scale = useSharedValue(0.96);
@@ -194,8 +201,9 @@ const SignInModalContent: React.FC<SignInModalContentProps> = ({
 
                             {/* Same-device "Sign in with Oxy" handoff — deep-links into the
                                 native Oxy app to approve. Shown only when the handoff backend
-                                returned a payload. */}
-                            {qrPayload && (
+                                returned a payload, and never on a cross-apex web RP (the
+                                approval happens outside the browser → no durable session). */}
+                            {!crossApexWeb && qrPayload && (
                                 <Button
                                     variant="secondary"
                                     onPress={openSameDeviceApproval}
@@ -216,10 +224,14 @@ const SignInModalContent: React.FC<SignInModalContentProps> = ({
                                 </View>
                             )}
 
-                            {/* Collapsed "sign in on another device" QR disclosure */}
-                            <View style={styles.qrSection}>
-                                <AnotherDeviceQR qrData={qrData} qrPayload={qrPayload} />
-                            </View>
+                            {/* Collapsed "sign in on another device" QR disclosure. Hidden on
+                                a cross-apex web RP: a remote Commons-app approval completes via
+                                the device-flow claim, which plants no `fedcm_session`. */}
+                            {!crossApexWeb && (
+                                <View style={styles.qrSection}>
+                                    <AnotherDeviceQR qrData={qrData} qrPayload={qrPayload} />
+                                </View>
+                            )}
                         </>
                     )}
 

package/src/ui/context/OxyContext.tsx

@@ -53,6 +53,7 @@ import { useAccountStore } from '../stores/accountStore';
 import { logger as loggerUtil } from '@oxyhq/core';
 import { useWebSSO, isWebBrowser } from '../hooks/useWebSSO';
 import { buildSilentGuardKey } from '../../utils/silentGuardKey';
+import { isCrossApexWeb, CrossApexDirectSignInError } from '../../utils/crossApex';
 import { createInSessionRefreshHandler, startTokenRefreshScheduler } from './inSessionTokenRefresh';
 import { mintSessionViaPerApexIframe, selectActiveRefreshAccount } from './silentSessionRestore';
 
@@ -1418,14 +1419,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             // step that prevents the re-bounce loop: when it finds a session,
             // the terminal `sso-bounce` never fires.
             //
-            // The instance is configured with `authWebUrl=auth.oxy.so` (central,
-            // for the bounce + FedCM), so we explicitly point the iframe at the
-            // per-apex host via `autoDetectAuthWebUrl()` and `silentSignIn`'s
-            // `authWebUrlOverride`. On a `*.oxy.so` RP the per-apex host IS the
-            // central host (`auth.oxy.so`), so this is a same-host no-op-
-            // equivalent. When auto-detection bails (localhost/IP/single-label)
-            // there is no per-apex IdP and the step skips. Web only; on native
-            // `isWebBrowser()` gates it off, so native never runs an iframe.
+            // The per-apex iframe mint itself lives in
+            // `mintSessionViaPerApexIframe` (shared verbatim with the in-session
+            // refresh handler so the two paths can never drift): it points the
+            // iframe at `autoDetectAuthWebUrl()` and skips when there is no
+            // per-apex IdP (localhost/IP/single-label/off-browser). Web only; on
+            // native `isWebBrowser()` gates it off, so native never runs an
+            // iframe.
             //
             // FIX-B: additionally skipped when `stored-session` already won.
             // FIX-D: bounded by `SILENT_IFRAME_TIMEOUT` (plus `iframe.onerror`
@@ -1777,6 +1777,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       password: string,
       opts?: { deviceName?: string; deviceFingerprint?: string },
     ): Promise<PasswordSignInResult> => {
+      // On a cross-apex web RP a direct password sign-in mints a bearer against
+      // the Oxy API but establishes no `fedcm_session`, so the session would be
+      // lost on reload. Refuse it and direct the app to the durable IdP popup
+      // ("Continue with Oxy"). Native and same-apex `*.oxy.so` are unaffected.
+      if (isCrossApexWeb()) {
+        throw new CrossApexDirectSignInError();
+      }
       const response = await oxyServices.signIn(
         identifier,
         password,

package/src/ui/context/hooks/useAuthOperations.ts

@@ -10,6 +10,7 @@ import type { OxyServices } from '@oxyhq/core';
 import { SignatureService } from '@oxyhq/core';
 import { isWebBrowser } from '../../hooks/useWebSSO';
 import { clearActiveAuthuser, clearSsoBounceState } from '../../utils/activeAuthuser';
+import { isCrossApexWeb, CrossApexDirectSignInError } from '../../../utils/crossApex';
 
 export interface UseAuthOperationsOptions {
   oxyServices: OxyServices;
@@ -203,6 +204,13 @@ export const useAuthOperations = ({
    */
   const signIn = useCallback(
     async (publicKey: string, deviceName?: string): Promise<User> => {
+      // On a cross-apex web RP a direct public-key sign-in mints a bearer against
+      // the Oxy API but establishes no `fedcm_session`, so the session would be
+      // lost on reload. Refuse it and direct the app to the durable IdP popup
+      // ("Continue with Oxy"). Native and same-apex `*.oxy.so` are unaffected.
+      if (isCrossApexWeb()) {
+        throw new CrossApexDirectSignInError();
+      }
       setAuthState({ isLoading: true, error: null });
 
       try {

package/src/ui/context/inSessionTokenRefresh.ts

@@ -15,10 +15,10 @@
  *
  *  1. {@link createInSessionRefreshHandler} — an `AuthRefreshHandler` installed
  *     on the owner client. It re-mints a fresh access token WITHOUT a page
- *     reload by reusing the SAME durable per-apex silent-restore arms cold boot
- *     uses (in order; first that yields a token wins). The linked client
- *     (`createLinkedClient`) inherits the fix for free — its refresh delegates
- *     back to the owner's `refreshAccessToken`.
+ *     reload by composing the SAME silent-restore primitives cold boot uses
+ *     ({@link mintSessionViaPerApexIframe}, {@link selectActiveRefreshAccount}) —
+ *     not a copy. The linked client (`createLinkedClient`) inherits the fix for
+ *     free: its refresh delegates back to the owner's `refreshAccessToken`.
  *
  *  2. {@link startTokenRefreshScheduler} — a proactive scheduler that refreshes
  *     ~{@link TOKEN_REFRESH_LEAD_MS} before expiry (and on web tab-focus / native
@@ -35,10 +35,11 @@ import type {
   AuthRefreshHandler,
   AuthRefreshReason,
 } from '@oxyhq/core';
-import { autoDetectAuthWebUrl, logger as loggerUtil } from '@oxyhq/core';
+import { logger as loggerUtil } from '@oxyhq/core';
 import { AppState, type AppStateStatus } from 'react-native';
 import { isWebBrowser } from '../hooks/useWebSSO';
 import { readActiveAuthuser } from '../utils/activeAuthuser';
+import { mintSessionViaPerApexIframe, selectActiveRefreshAccount } from './silentSessionRestore';
 
 /**
  * Per-arm fail-fast budget (ms) for the web first-party `/auth/silent` iframe
@@ -67,114 +68,97 @@ const COOKIE_REFRESH_TIMEOUT = 4000;
  */
 export const TOKEN_REFRESH_LEAD_MS = 60_000;
 
-function debugRefresh(message: string, reason: AuthRefreshReason, error?: unknown): void {
-  if (__DEV__) {
-    loggerUtil.debug(
-      message,
-      { component: 'inSessionTokenRefresh', method: 'authRefreshHandler', reason },
-      error,
-    );
-  }
-}
+/**
+ * A single refresh arm: attempts one silent-restore mechanism and resolves to
+ * the freshly planted access token, or `null` to fall through to the next arm.
+ */
+type RefreshArm = () => Promise<string | null>;
 
 /**
  * Build the in-session `AuthRefreshHandler` for the owner client.
  *
- * Arms (first to yield a fresh token wins; each is bounded and falls through on
- * failure). Every arm plants the fresh token internally, so on success we read
- * it back via `getAccessToken()`:
+ * Arms run in an explicit order; the first to plant a token wins. Each arm
+ * resolves to the planted token (read back via `getAccessToken()` — the
+ * underlying SDK call plants it internally) or `null`. A throw in one arm is
+ * logged and treated as `null` so the chain continues.
  *
  *   NATIVE (Expo): shared cross-app identity key re-mint
  *     (`signInWithSharedIdentity` → challenge→sign→verify plants the tokens).
  *     The ONLY silent native arm (mirrors cold boot's `shared-key-signin`); the
- *     `/auth/silent` web iframe is NEVER attempted on native. Returns `null`
+ *     `/auth/silent` web iframe is NEVER attempted on native. Resolves to `null`
  *     when the device holds no shared identity (e.g. a password-only native
  *     sign-in) so a genuinely dead session reconciles to logged-out rather than
  *     staying a zombie.
  *
  *   WEB, in order:
- *     1. First-party `/auth/silent` iframe at the per-apex IdP
- *        (`silentSignIn` with `authWebUrlOverride = autoDetectAuthWebUrl()`).
- *        The durable cross-apex path: the iframe reads the first-party
- *        `fedcm_session` cookie on `auth.<apex>` and mints a fresh Oxy token. No
- *        top-level navigation → works in a backgrounded tab. On a `*.oxy.so`
- *        app the per-apex host IS the central host, so this also covers
- *        same-apex.
+ *     1. Per-apex `/auth/silent` iframe — {@link mintSessionViaPerApexIframe}
+ *        (shared verbatim with cold boot). The durable cross-apex path; also
+ *        covers `*.oxy.so` (the per-apex host IS the central host there).
  *     2. FedCM silent re-auth (Chrome) — `silentSignInWithFedCM`.
- *     3. Same-apex refresh cookie — `refreshAllSessions`. On `*.oxy.so` the
- *        httpOnly `oxy_rt_${n}` cookies ride along; we plant the active
- *        account's rotated token. On a cross-apex RP it returns `{accounts:[]}`
- *        and is a clean no-op. Unlike the cold-boot cookie restore this does NOT
- *        rebuild multi-session state — an in-session refresh only needs a fresh
- *        bearer.
+ *     3. Same-apex refresh cookie — `refreshAllSessions` + the shared
+ *        {@link selectActiveRefreshAccount}; plant the active account's rotated
+ *        token. On a cross-apex RP it returns `{accounts:[]}` (clean no-op).
+ *        Unlike the cold-boot cookie restore this does NOT rebuild multi-session
+ *        state — an in-session refresh only needs a fresh bearer.
  *
- * NO RECURSION: none of these arms issue requests through the authed client's
+ * NO RECURSION: no arm issues a request through the authed client's
  * `refreshAccessToken` path. The iframe/FedCM transports are postMessage /
  * credential APIs; the follow-up `/session/user` fetch inside `silentSignIn`
  * runs against the just-planted FULL-TTL token (≫ the preflight lead), so it
- * never re-enters the refresh path; `refreshAllSessions` uses a raw `fetch` with
- * `credentials:'include'`.
+ * never re-enters the refresh path; `refreshAllSessions` uses a raw `fetch`.
  */
 export function createInSessionRefreshHandler(oxyServices: OxyServices): AuthRefreshHandler {
-  return async (reason: AuthRefreshReason): Promise<string | null> => {
-    if (!isWebBrowser()) {
-      try {
-        const session = await oxyServices.signInWithSharedIdentity?.();
-        if (session) {
-          // `verifyChallenge` inside `signInWithSharedIdentity` already planted
-          // the fresh tokens; read the planted access token back out.
-          return oxyServices.getAccessToken();
-        }
-      } catch (error) {
-        debugRefresh('Native shared-key in-session refresh failed', reason, error);
+  const runArm = async (label: string, reason: AuthRefreshReason, arm: RefreshArm): Promise<string | null> => {
+    try {
+      return await arm();
+    } catch (error) {
+      if (__DEV__) {
+        loggerUtil.debug(
+          `In-session refresh arm "${label}" failed (falling through)`,
+          { component: 'inSessionTokenRefresh', method: 'authRefreshHandler', reason },
+          error,
+        );
       }
       return null;
     }
+  };
 
-    // WEB arm 1 — first-party silent iframe at the per-apex IdP.
-    try {
-      const perApexAuthUrl = autoDetectAuthWebUrl();
-      if (perApexAuthUrl) {
-        const session = await oxyServices.silentSignIn?.({
-          authWebUrlOverride: perApexAuthUrl,
-          timeout: SILENT_IFRAME_REFRESH_TIMEOUT,
-        });
-        if (session) {
-          return oxyServices.getAccessToken();
-        }
+  const webArms: Array<[string, RefreshArm]> = [
+    ['silent-iframe', async () =>
+      (await mintSessionViaPerApexIframe(oxyServices, SILENT_IFRAME_REFRESH_TIMEOUT))
+        ? oxyServices.getAccessToken()
+        : null,
+    ],
+    ['fedcm-silent', async () => {
+      if (oxyServices.isFedCMSupported?.() !== true) {
+        return null;
       }
-    } catch (error) {
-      debugRefresh('Silent-iframe in-session refresh failed', reason, error);
-    }
-
-    // WEB arm 2 — FedCM silent re-auth (Chrome).
-    try {
-      if (oxyServices.isFedCMSupported?.() === true) {
-        const session = await oxyServices.silentSignInWithFedCM?.();
-        if (session) {
-          return oxyServices.getAccessToken();
-        }
+      return (await oxyServices.silentSignInWithFedCM?.()) ? oxyServices.getAccessToken() : null;
+    }],
+    ['refresh-cookie', async () => {
+      const snapshot = await oxyServices.refreshAllSessions({ timeout: COOKIE_REFRESH_TIMEOUT });
+      if (snapshot.accounts.length === 0) {
+        return null;
       }
-    } catch (error) {
-      debugRefresh('FedCM-silent in-session refresh failed', reason, error);
+      const active = selectActiveRefreshAccount(snapshot.accounts, readActiveAuthuser());
+      oxyServices.httpService.setTokens(active.accessToken);
+      return oxyServices.getAccessToken();
+    }],
+  ];
+
+  return async (reason: AuthRefreshReason): Promise<string | null> => {
+    if (!isWebBrowser()) {
+      return runArm('native-shared-key', reason, async () =>
+        (await oxyServices.signInWithSharedIdentity?.()) ? oxyServices.getAccessToken() : null,
+      );
     }
 
-    // WEB arm 3 — same-apex refresh cookie.
-    try {
-      const snapshot = await oxyServices.refreshAllSessions({ timeout: COOKIE_REFRESH_TIMEOUT });
-      if (snapshot.accounts.length > 0) {
-        const persistedAuthuser = readActiveAuthuser();
-        const active =
-          (persistedAuthuser !== null
-            ? snapshot.accounts.find((account) => account.authuser === persistedAuthuser)
-            : undefined) ?? snapshot.accounts[0];
-        oxyServices.httpService.setTokens(active.accessToken);
-        return oxyServices.getAccessToken();
+    for (const [label, arm] of webArms) {
+      const token = await runArm(label, reason, arm);
+      if (token) {
+        return token;
       }
-    } catch (error) {
-      debugRefresh('Refresh-cookie in-session refresh failed', reason, error);
     }
-
     return null;
   };
 }
@@ -194,14 +178,15 @@ export interface TokenRefreshSchedulerHandle {
  * current access token's `exp`, calling `httpService.refreshAccessToken`
  * ('preflight') — which runs the installed handler and is deduped + cooldown-
  * guarded. After every attempt it reschedules from the (possibly rotated) token.
- * It also reschedules whenever the token changes (`onTokensChanged`) and, on
- * web tab-focus / native app-foreground, refreshes immediately if already inside
- * the lead window (a long-hidden tab throttles timers, so the token can be
- * expired on return).
+ * It also reschedules whenever the token changes (`onTokensChanged` — so a
+ * sign-out that clears the token cancels the timer) and, on web tab-focus /
+ * native app-foreground, refreshes immediately if already inside the lead window
+ * (a long-hidden tab throttles timers, so the token can be expired on return).
  *
- * No-ops cleanly when there is no token, an opaque/no-`exp` token, or the host
- * lacks `getAccessTokenExpiry` (older stubs) — in those cases the reactive 401
- * path remains the only refresh trigger.
+ * The `exp` is derived directly from the JWT via `getAccessTokenExpiry()`. No-ops
+ * cleanly when there is no token, an opaque/no-`exp` token, or the host lacks
+ * `getAccessTokenExpiry` (older stubs) — the reactive 401 path stays the only
+ * refresh trigger in those cases.
  */
 export function startTokenRefreshScheduler(oxyServices: OxyServices): TokenRefreshSchedulerHandle {
   let disposed = false;

package/src/ui/screens/OxyAuthScreen.tsx

@@ -29,6 +29,7 @@ import OxyLogo from '../components/OxyLogo';
 import AnotherDeviceQR from '../components/AnotherDeviceQR';
 import LoadingState from '../components/LoadingState';
 import { useOxyAuthSession, OXY_ACCOUNTS_WEB_URL } from '../hooks/useOxyAuthSession';
+import { isCrossApexWeb } from '../../utils/crossApex';
 
 const OxyAuthScreen: React.FC<BaseScreenProps> = ({ goBack, onAuthenticated }) => {
   const bloomTheme = useTheme();
@@ -41,6 +42,13 @@ const OxyAuthScreen: React.FC<BaseScreenProps> = ({ goBack, onAuthenticated }) =
     { onSignedIn: onAuthenticated },
   );
 
+  // On a cross-apex web RP, only the "Continue with Oxy" IdP popup establishes a
+  // durable `fedcm_session`. The Commons-app handoffs (same-device deep-link +
+  // cross-device QR) approve OUTSIDE the browser, so they leave no IdP session
+  // and the user would be logged out on reload — hide them there. Off-browser
+  // (native) this is always `false`, so the bottom sheet is unchanged.
+  const crossApexWeb = isCrossApexWeb();
+
   if (isLoading) {
     return (
       <View className="flex-1 items-center justify-center bg-bg">
@@ -104,8 +112,10 @@ const OxyAuthScreen: React.FC<BaseScreenProps> = ({ goBack, onAuthenticated }) =
       </Button>
 
       {/* Same-device "Sign in with Oxy" handoff — deep-links into the native Oxy
-          app to approve. Shown only when the handoff backend returned a payload. */}
-      {qrPayload && (
+          app to approve. Shown only when the handoff backend returned a payload,
+          and never on a cross-apex web RP (approval happens outside the browser
+          → no durable session). */}
+      {!crossApexWeb && qrPayload && (
         <Button
           variant="secondary"
           size="large"
@@ -130,10 +140,14 @@ const OxyAuthScreen: React.FC<BaseScreenProps> = ({ goBack, onAuthenticated }) =
         </View>
       )}
 
-      {/* Collapsed "sign in on another device" QR disclosure */}
-      <View className="w-full mt-space-24">
-        <AnotherDeviceQR qrData={qrData} qrPayload={qrPayload} />
-      </View>
+      {/* Collapsed "sign in on another device" QR disclosure. Hidden on a
+          cross-apex web RP: a remote Commons-app approval completes via the
+          device-flow claim, which plants no `fedcm_session`. */}
+      {!crossApexWeb && (
+        <View className="w-full mt-space-24">
+          <AnotherDeviceQR qrData={qrData} qrPayload={qrPayload} />
+        </View>
+      )}
 
       {/* Footer — create an account */}
       <View className="flex-row flex-wrap justify-center items-center mt-space-24">

package/src/utils/crossApex.ts

@@ -0,0 +1,75 @@
+/**
+ * Cross-apex web detection for sign-in durability gating.
+ *
+ * On a web Relying Party whose registrable apex differs from the central Oxy
+ * Identity Provider apex (`oxy.so`), the ONLY sign-in completion that survives a
+ * page reload is the interactive "Continue with Oxy" IdP flow, because it is the
+ * only one that establishes a first-party `fedcm_session` cookie at
+ * `auth.<apex>` — the anchor the cross-domain cold-boot restore reads on reload.
+ *
+ * The other sign-in completions the SDK can drive do NOT plant a `fedcm_session`:
+ *   - password / public-key sign-in mints a bearer directly against the Oxy API
+ *     (its refresh cookie is host-scoped to `api.oxy.so` and `SameSite=Lax`, so
+ *     it is unreachable cross-site from the RP), and
+ *   - the Commons-app device-flow handoff (cross-device QR / same-device
+ *     deep-link) is approved OUTSIDE the browser, so no IdP browser session is
+ *     established.
+ * On a cross-apex RP each of these leaves the user signed in for the current
+ * page only — a reload logs them out. See OxyHQServices AGENTS.md
+ * "Auth / Session Contract".
+ *
+ * Same-apex `*.oxy.so` apps (e.g. `accounts.oxy.so`) are first-party with
+ * `api.oxy.so`: their refresh cookie rides same-site requests so reload restore
+ * works without `fedcm_session`, and they are therefore NOT gated.
+ *
+ * Returns `false` off-browser (React Native has no `window.location`) and for
+ * hosts without a registrable apex (localhost / raw IP / single-label dev
+ * hosts), so native and local development keep every sign-in method.
+ */
+
+import { registrableApex, CENTRAL_IDP_APEX } from '@oxyhq/core';
+
+/**
+ * Whether the given host is a web RP on a registrable apex other than the
+ * central Oxy IdP apex (`oxy.so`). See the module doc for why this gates the
+ * non-durable sign-in paths.
+ *
+ * @param hostname - The host to classify. Defaults to the current
+ *   `window.location.hostname`; resolves to `undefined` off-browser (React
+ *   Native / SSR), which yields `false`. The explicit parameter mirrors
+ *   `autoDetectAuthWebUrl(location?)` and keeps the predicate unit-testable
+ *   without manipulating the global `window.location`.
+ */
+export function isCrossApexWeb(
+  hostname: string | undefined = typeof window !== 'undefined'
+    ? window.location?.hostname
+    : undefined,
+): boolean {
+  if (!hostname) {
+    return false;
+  }
+  const apex = registrableApex(hostname);
+  return apex !== null && apex !== CENTRAL_IDP_APEX;
+}
+
+/**
+ * Thrown when an app attempts a direct (non-IdP) sign-in — password or
+ * public-key — on a cross-apex web RP, where such a sign-in would not survive a
+ * page reload because no `fedcm_session` is established (see {@link isCrossApexWeb}).
+ *
+ * Apps on a cross-apex apex must sign in through the interactive
+ * "Continue with Oxy" IdP flow (`OxySignInButton` / `showSignInModal()`), which
+ * plants the durable session.
+ */
+export class CrossApexDirectSignInError extends Error {
+  override readonly name = 'CrossApexDirectSignInError';
+  readonly code = 'CROSS_APEX_DIRECT_SIGN_IN_UNSUPPORTED';
+
+  constructor() {
+    super(
+      'Direct sign-in is unavailable on this domain because the session would ' +
+        'not survive a page reload. Use "Continue with Oxy" to sign in through ' +
+        'the Oxy identity provider.',
+    );
+  }
+}