@oxyhq/services 22.12.4 → 22.12.7

package/src/ui/components/OxyConsentScreen.tsx

@@ -76,13 +76,20 @@ export interface OxyConsentScreenProps {
 /**
  * Friendly-label i18n keys for the scopes the platform issues. Standard OIDC
  * scopes (`openid` / `profile` / `email` / `offline_access`) and the Oxy scope
- * set both map to a curated `consent.scopes.*` sentence. Unknown scopes fall
- * back to the raw scope string so the user always sees something concrete.
+ * set — including the `<resource>:read` ids the API actually issues
+ * (`profile:read`, `email:read`) — map to a curated `consent.scopes.*` sentence
+ * that already ships in `@oxyhq/core` for all 11 locales. This is the SAME
+ * vocabulary the Commons approval screen uses
+ * (`packages/commons/lib/commons-signin/scope-summary.ts`), so one permission
+ * reads identically wherever it is granted. Unknown scopes fall back to the raw
+ * scope string so the user always sees something concrete.
  */
-const SCOPE_LABEL_KEYS: Record<string, string> = {
+const SCOPE_LABEL_KEYS: Readonly<Record<string, string>> = {
   openid: 'consent.scopes.openid',
   profile: 'consent.scopes.profile',
+  'profile:read': 'consent.scopes.profile',
   email: 'consent.scopes.email',
+  'email:read': 'consent.scopes.email',
   offline_access: 'consent.scopes.offlineAccess',
   'user:read': 'consent.scopes.userRead',
   'files:read': 'consent.scopes.filesRead',
@@ -96,9 +103,47 @@ const SCOPE_LABEL_KEYS: Record<string, string> = {
 
 type Translate = ReturnType<typeof useI18n>['t'];
 
-function scopeLabel(scope: string, t: Translate): string {
-  const key = SCOPE_LABEL_KEYS[scope];
-  return key ? t(key) : scope;
+/** One permission row of the "Permissions requested" list. */
+interface PermissionRow {
+  /** Stable list key / testID suffix — the first scope that produced this row. */
+  scope: string;
+  /** Shared `consent.scopes.*` key, absent when this build has no sentence for the scope. */
+  labelKey?: string;
+}
+
+/**
+ * Resolve the requested scopes into the rows the user actually reads.
+ *
+ * De-duplicates by RESOLVED MEANING rather than by raw string — `profile` and
+ * `profile:read` are one permission and must not render as two identical rows —
+ * while preserving the server's ordering. An unknown scope is never dropped: it
+ * keeps its own row and renders verbatim, so a permission this build has no
+ * sentence for is still shown to the person granting it.
+ */
+function resolvePermissionRows(scopes: readonly string[]): PermissionRow[] {
+  const rows: PermissionRow[] = [];
+  const seen = new Set<string>();
+
+  for (const raw of scopes) {
+    // The caller resolves scopes from the network; a non-string entry must not
+    // take the whole consent surface down with a `.trim()` on it.
+    if (typeof raw !== 'string') continue;
+    const scope = raw.trim();
+    if (!scope) continue;
+
+    const labelKey = SCOPE_LABEL_KEYS[scope];
+    const identity = labelKey ?? `raw:${scope}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+
+    rows.push(labelKey ? { scope, labelKey } : { scope });
+  }
+
+  return rows;
+}
+
+function permissionRowLabel(row: PermissionRow, t: Translate): string {
+  return row.labelKey ? t(row.labelKey) : row.scope;
 }
 
 /** A tappable legal/website link that opens the URL in the platform browser. */
@@ -150,9 +195,7 @@ export function OxyConsentScreen({
   const theme = useTheme();
   const { t } = useI18n();
   const appName = application.name;
-  // Scopes key the permission rows — a duplicate in the request would mean
-  // duplicate React keys and redundant rows.
-  const uniqueScopes = [...new Set(scopes)];
+  const permissionRows = resolvePermissionRows(scopes);
 
   const provenanceLabel = application.isOfficial
     ? t('consent.provenance.official')
@@ -217,12 +260,12 @@ export function OxyConsentScreen({
           {t('consent.permissions.title')}
         </Text>
         <View style={[styles.card, { borderColor: theme.colors.border, backgroundColor: theme.colors.card }]}>
-          {uniqueScopes.length > 0 ? (
-            uniqueScopes.map((scope) => (
-              <View key={scope} testID={`consent-scope-${scope}`} style={styles.row}>
+          {permissionRows.length > 0 ? (
+            permissionRows.map((row) => (
+              <View key={row.scope} testID={`consent-scope-${row.scope}`} style={styles.row}>
                 <View style={[styles.bullet, { backgroundColor: theme.colors.primary }]} />
                 <Text style={[styles.rowText, { color: theme.colors.text }]}>
-                  {scopeLabel(scope, t)}
+                  {permissionRowLabel(row, t)}
                 </Text>
               </View>
             ))

package/src/ui/components/OxyProvider.tsx

@@ -12,7 +12,6 @@ import { logger as loggerUtil } from '@oxyhq/core';
 import { RequireOxyAuth } from './RequireOxyAuth';
 import { attachQueryPersistence, createQueryClient } from '../hooks/queryClient';
 import { createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
-import { setupFonts } from './FontLoader';
 
 /**
  * Background color shown for the brief window between mount and the
@@ -40,9 +39,6 @@ const bootStyles = StyleSheet.create({
     },
 });
 
-// Initialize fonts automatically
-setupFonts();
-
 // Detect if running on web
 const isWeb = Platform.OS === 'web';
 
@@ -95,6 +91,8 @@ const OxyProvider: FC<OxyProviderProps> = ({
     authWebUrl,
     authRedirectUri,
     authorizeBaseUrl,
+    sessionMode = 'account',
+    webAuthMode = 'redirect',
     queryClient: providedQueryClient,
     requireAuth = 'off',
     hubSync = true,
@@ -293,6 +291,8 @@ const OxyProvider: FC<OxyProviderProps> = ({
                     authorizeBaseUrl={authorizeBaseUrl}
                     storageKeyPrefix={storageKeyPrefix}
                     clientId={clientId}
+                    sessionMode={sessionMode}
+                    webAuthMode={webAuthMode}
                     hubSync={hubSync}
                     onAuthStateChange={onAuthStateChange as OxyContextProviderProps['onAuthStateChange']}
                 >

package/src/ui/components/OxySignInButton.tsx

@@ -6,9 +6,6 @@ import {
     generatePkcePair,
     generateOAuthState,
     buildOAuthAuthorizeUrl,
-    OXY_OAUTH_STATE_STORAGE_KEY,
-    OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
-    persistOAuthHandshake,
     type PublicApplication,
 } from '@oxyhq/core';
 import { useAuthStore } from '../stores/authStore';
@@ -16,15 +13,18 @@ import { useShallow } from 'zustand/react/shallow';
 import { useTheme } from '@oxyhq/bloom/theme';
 import { Button, type ButtonVariant } from '@oxyhq/bloom/button';
 import { useOxy } from '../context/OxyContext';
+import { useI18n } from '../hooks/useI18n';
 import { LogoIcon } from './logo/LogoIcon';
 import { subscribeToAccountDialog } from '../navigation/accountDialogManager';
-import { redirectToAuthorize, openAuthorizeUrlNative } from './oauthNavigation';
+import { openAuthorizeUrlNative } from './oauthNavigation';
+import { closeOAuthPopup, openOAuthPopup } from '../oauth/oauthPopup';
+import type { OAuthPopupHandle } from '../oauth/types';
 
 /**
  * The OAuth handshake surfaced to a NATIVE third-party RP via
  * {@link OxySignInButtonProps.onOAuthResult} so it can finish the code exchange
- * (`POST /auth/oauth/token`). Web RPs read the same `state` / `code_verifier`
- * back from `sessionStorage` across the redirect and do not need this callback.
+ * (`POST /auth/oauth/token`). Web sign-in is handled entirely by the SDK's web
+ * transport (`useOxy().startWebOAuthSignIn`) and never uses this callback.
  */
 export interface OxyOAuthResult {
     /** Deep-link URL the native auth session returned to (`?code=…&state=…`), or `null` if unobserved. */
@@ -35,17 +35,6 @@ export interface OxyOAuthResult {
     codeVerifier: string;
 }
 
-/**
- * Persist the OAuth CSRF `state` + PKCE `code_verifier` for the RP callback.
- * Returns `false` when the handshake could not be stored — no `sessionStorage`
- * (SSR / non-browser host) or a write that threw (`SecurityError` /
- * `QuotaExceededError`, e.g. Safari private mode) — so the caller aborts the
- * flow cleanly rather than redirect to a callback that cannot validate `state`.
- */
-function persistOAuthHandshakeForButton(state: string, codeVerifier: string): boolean {
-    return persistOAuthHandshake(state, codeVerifier);
-}
-
 export interface OxySignInButtonProps {
     /**
      * Controls the appearance of the button
@@ -70,8 +59,12 @@ export interface OxySignInButtonProps {
     textStyle?: StyleProp<TextStyle>;
 
     /**
-     * Custom button text
-     * @default 'Sign in with Oxy'
+     * Overrides the button label. When omitted the button renders the ONE
+     * primary relying-party action, localized: `accountSwitcher.continueWithOxy`
+     * ("Continue with Oxy" in English). "Sign in with Oxy" remains the name of
+     * the MECHANISM — only this surface's label is "Continue with Oxy".
+     *
+     * @default localized `accountSwitcher.continueWithOxy`
      */
     text?: string;
 
@@ -90,19 +83,20 @@ export interface OxySignInButtonProps {
     /**
      * Exact registered redirect URI the OAuth authorization code is returned to.
      * REQUIRED only for third-party (`type: 'third_party'`) applications, which
-     * sign in via an OAuth + PKCE redirect to `auth.oxy.so`. First-party /
-     * official apps open the in-app dialog and ignore this prop. If a third-party
-     * app resolves without it, the button logs an error and does nothing (it will
-     * not invent a redirect URI).
+     * sign in via OAuth + PKCE against `auth.oxy.so`. First-party / official apps
+     * open the in-app dialog and ignore this prop. If a third-party app resolves
+     * without it, the button logs an error and does nothing (it will not invent a
+     * redirect URI).
      */
     oauthRedirectUri?: string;
 
     /**
      * Native only: receives the OAuth handshake after a third-party auth session
-     * so the RP can finish the token exchange. On web the handshake is read back
-     * from `sessionStorage` across the full-page redirect, so this is not used
-     * there. A native third-party sign-in with NO `onOAuthResult` handler cannot
-     * complete (the `state` + `code_verifier` are lost) and logs a warning.
+     * so the RP can finish the token exchange. On web the SDK completes the flow
+     * itself — the popup transport keeps the handshake in memory, and the
+     * redirect transport reads it back from `sessionStorage` — so this is never
+     * called there. A native third-party sign-in with NO `onOAuthResult` handler
+     * cannot complete (the `state` + `code_verifier` are lost) and logs a warning.
      *
      * @example
      * ```tsx
@@ -148,14 +142,15 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
     onPress,
     style,
     textStyle,
-    text = 'Sign in with Oxy',
+    text,
     disabled = false,
     showWhenAuthenticated = false,
     oauthRedirectUri,
     onOAuthResult,
 }) => {
     const theme = useTheme();
-    const { openAccountDialog, oxyServices, clientId } = useOxy();
+    const { t } = useI18n();
+    const { openAccountDialog, oxyServices, clientId, webAuthMode, startWebOAuthSignIn } = useOxy();
     const { isAuthenticated, isLoading } = useAuthStore(
         useShallow((state) => ({ isAuthenticated: state.isAuthenticated, isLoading: state.isLoading }))
     );
@@ -180,6 +175,12 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
     // redirects, so block a second concurrent press from racing the sessionStorage
     // handshake against a different PKCE pair.
     const routingRef = useRef(false);
+    // Popup mode only opens a window for applications that could actually need
+    // one: `oauthRedirectUri` is required for (and only for) third-party OAuth,
+    // so an official app never flashes a popup open and closed while its
+    // in-app dialog loads.
+    const shouldPreOpenPopup =
+        Platform.OS === 'web' && webAuthMode === 'popup' && Boolean(oauthRedirectUri);
 
     const resolvePublicApplication = useCallback((): Promise<PublicApplication> | null => {
         if (!clientId) return null;
@@ -204,44 +205,58 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
         openAccountDialog('signin');
     }, [openAccountDialog]);
 
-    // Third-party surface: an OAuth 2.0 authorization-code + PKCE redirect to
+    // Third-party surface: an OAuth 2.0 authorization-code + PKCE flow against
     // auth.oxy.so. No FedCM, no SSO bounce, no Oxy session cookies.
+    //
+    // Web delegates to the ONE shared transport (`startWebOAuthSignIn`), which
+    // owns popup-vs-redirect selection, the popup lifecycle, the code exchange,
+    // and the session commit. Native keeps its in-app auth session and hands the
+    // handshake to the RP, which owns that exchange.
     const startThirdPartyOAuth = useCallback(
-        async (app: PublicApplication): Promise<void> => {
+        async (app: PublicApplication, popup: OAuthPopupHandle | null): Promise<void> => {
             if (!clientId) {
+                closeOAuthPopup(popup);
                 startOfficialSignIn();
                 return;
             }
             if (!oauthRedirectUri) {
+                closeOAuthPopup(popup);
                 logger.error(
-                    'OxySignInButton: a third_party application requires the `oauthRedirectUri` prop to start the OAuth redirect; sign-in aborted',
+                    'OxySignInButton: a third_party application requires the `oauthRedirectUri` prop to start the OAuth flow; sign-in aborted',
                     undefined,
                     { component: 'OxySignInButton', clientId, application: app.name },
                 );
                 return;
             }
 
-            const [pkce, state] = await Promise.all([generatePkcePair(), generateOAuthState()]);
-            const authorizeUrl = buildOAuthAuthorizeUrl({
-                clientId,
-                redirectUri: oauthRedirectUri,
-                state,
-                codeChallenge: pkce.codeChallenge,
-            });
-
             if (Platform.OS === 'web') {
-                // Persist the handshake for the RP callback, then hand the
-                // top-level document to the IdP. Without storage the callback
-                // cannot validate `state`, so abort cleanly rather than redirect.
-                if (!persistOAuthHandshakeForButton(state, pkce.codeVerifier)) {
-                    return;
+                const result = await startWebOAuthSignIn({
+                    redirectUri: oauthRedirectUri,
+                    // In popup mode the window was claimed during the press (see
+                    // `handlePress`); `null` means the browser blocked it and the
+                    // transport falls back to a redirect. `undefined` (redirect
+                    // mode) lets the transport decide for itself.
+                    ...(shouldPreOpenPopup ? { popup } : {}),
+                });
+                if (result.status === 'failed') {
+                    logger.warn(
+                        `OxySignInButton: web sign-in failed (${result.reason})`,
+                        { component: 'OxySignInButton', application: app.name },
+                        result.description,
+                    );
                 }
-                redirectToAuthorize(authorizeUrl);
                 return;
             }
 
             // Native: open the in-app auth session, then hand the handshake to the
             // RP so it can complete the token exchange from its deep-link callback.
+            const [pkce, state] = await Promise.all([generatePkcePair(), generateOAuthState()]);
+            const authorizeUrl = buildOAuthAuthorizeUrl({
+                clientId,
+                redirectUri: oauthRedirectUri,
+                state,
+                codeChallenge: pkce.codeChallenge,
+            });
             const { redirectUrl } = await openAuthorizeUrlNative(authorizeUrl, oauthRedirectUri);
             if (onOAuthResult) {
                 onOAuthResult({ redirectUrl, state, codeVerifier: pkce.codeVerifier });
@@ -252,51 +267,73 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
                 { component: 'OxySignInButton', application: app.name },
             );
         },
-        [clientId, oauthRedirectUri, onOAuthResult, startOfficialSignIn],
+        [
+            clientId,
+            oauthRedirectUri,
+            onOAuthResult,
+            startOfficialSignIn,
+            startWebOAuthSignIn,
+            shouldPreOpenPopup,
+        ],
     );
 
-    // Resolve the Application once, then route: third-party → OAuth redirect;
-    // first-party / official / unresolved → the in-app dialog. Resolution failure
-    // NEVER breaks an official app's sign-in — it falls back to the dialog.
-    const routeSignIn = useCallback(async (): Promise<void> => {
-        if (routingRef.current) return;
-        routingRef.current = true;
-        try {
-            const resolving = resolvePublicApplication();
-            if (!resolving) {
-                startOfficialSignIn();
+    // Resolve the Application once, then route: third-party → OAuth; first-party
+    // / official / unresolved → the in-app dialog. Resolution failure NEVER
+    // breaks an official app's sign-in — it falls back to the dialog. Every path
+    // that does NOT reach the OAuth lane closes the pre-opened popup, so a
+    // mis-routed press can never leave an empty window on screen.
+    const routeSignIn = useCallback(
+        async (popup: OAuthPopupHandle | null): Promise<void> => {
+            if (routingRef.current) {
+                closeOAuthPopup(popup);
                 return;
             }
-            let app: PublicApplication;
+            routingRef.current = true;
             try {
-                app = await resolving;
-            } catch (error) {
-                logger.warn(
-                    'OxySignInButton: could not resolve the application; opening the sign-in dialog',
-                    { component: 'OxySignInButton', clientId },
-                    error,
-                );
+                const resolving = resolvePublicApplication();
+                if (!resolving) {
+                    closeOAuthPopup(popup);
+                    startOfficialSignIn();
+                    return;
+                }
+                let app: PublicApplication;
+                try {
+                    app = await resolving;
+                } catch (error) {
+                    closeOAuthPopup(popup);
+                    logger.warn(
+                        'OxySignInButton: could not resolve the application; opening the sign-in dialog',
+                        { component: 'OxySignInButton', clientId },
+                        error,
+                    );
+                    startOfficialSignIn();
+                    return;
+                }
+                if (app.type === 'third_party' && !app.isOfficial) {
+                    await startThirdPartyOAuth(app, popup);
+                    return;
+                }
+                closeOAuthPopup(popup);
                 startOfficialSignIn();
-                return;
-            }
-            if (app.type === 'third_party' && !app.isOfficial) {
-                await startThirdPartyOAuth(app);
-                return;
+            } finally {
+                routingRef.current = false;
             }
-            startOfficialSignIn();
-        } finally {
-            routingRef.current = false;
-        }
-    }, [resolvePublicApplication, startOfficialSignIn, startThirdPartyOAuth, clientId]);
+        },
+        [resolvePublicApplication, startOfficialSignIn, startThirdPartyOAuth, clientId],
+    );
 
     // Defer to a caller-supplied handler, otherwise route by application type.
+    //
+    // The popup is opened HERE, synchronously, before the async application
+    // resolve: `window.open` only survives while the click is still being
+    // handled, so a window opened after that first `await` is silently blocked.
     const handlePress = useCallback(() => {
         if (onPress) {
             onPress();
             return;
         }
-        void routeSignIn();
-    }, [onPress, routeSignIn]);
+        void routeSignIn(shouldPreOpenPopup ? openOAuthPopup() : null);
+    }, [onPress, routeSignIn, shouldPreOpenPopup]);
 
     // Don't show the button if already authenticated (unless explicitly overridden)
     if (isAuthenticated && !showWhenAuthenticated) return null;
@@ -314,6 +351,10 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
     const logoColor = isContained ? '#ffffff' : theme.colors.primary;
     const logoLetterColor = isContained ? theme.colors.primary : '#ffffff';
 
+    // The relying party surfaces exactly ONE primary action, and it reads
+    // "Continue with Oxy" (issue #691). A caller-supplied `text` still wins.
+    const label = text ?? t('accountSwitcher.continueWithOxy');
+
     return (
         <Button
             variant={buttonVariant}
@@ -330,7 +371,7 @@ export const OxySignInButton: React.FC<OxySignInButtonProps> = ({
                 />
             }
         >
-            {isLoading || isModalOpen ? 'Signing in...' : text}
+            {isLoading || isModalOpen ? t('signin.status.signingIn') : label}
         </Button>
     );
 };

package/src/ui/components/OxySignInRequestSurface.tsx

@@ -0,0 +1,202 @@
+/**
+ * `OxySignInRequestSurface` — the in-flight "Sign in with Oxy" request, rendered
+ * from plain facts (issue #691, Phase 5).
+ *
+ * The user already performed their one action. From here the surface only
+ * REPORTS: the route-appropriate primary visual, the status line for the
+ * progress it was told about, and nothing else at the same weight. Alternatives
+ * stay behind "Having trouble?" until the chosen route could not be carried out,
+ * at which point they ARE the content and render plainly.
+ *
+ * PRESENTATIONAL AND HEADLESS-FRIENDLY. It owns no request, no controller, no
+ * polling, and no state of its own: everything it draws is a prop. That is what
+ * lets the two hosts of this surface share ONE implementation —
+ *
+ *  - `OxyAuthChooser`'s `SignInRequestView`, driven by `AccountDialogController`'s
+ *    device flow;
+ *  - the auth.oxy.so IdP's OAuth-bound lane, whose request carries an OAuth
+ *    binding the account dialog's session has no concept of.
+ *
+ * It resolves only what every `@oxyhq/services` consumer already has in context:
+ * the Bloom theme (`useTheme`) and the SDK's own locale dictionary (`useI18n`,
+ * the `accountSwitcher.*` copy in all 11 locales). Host-specific copy — the
+ * labels on {@link OxySignInRequestSurfaceProps.subordinate} and
+ * {@link OxySignInRequestSurfaceProps.alternatives} — arrives already localized.
+ *
+ * TWO THINGS IT DELIBERATELY DOES NOT DO:
+ *  - it renders no failure REASON. A host surfaces that the way its own shell
+ *    demands (the account dialog toasts it — errors never render inline there;
+ *    a full page may show a banner around this surface). The surface only takes
+ *    the fact that the request failed, and offers the way forward.
+ *  - it derives nothing from {@link OxySignInRequestSurfaceProps.qrPayload}.
+ *    Application identity, origin, and scopes are resolved server-side by the
+ *    approver (Commons), never read out of a payload here — the plate encodes it
+ *    and shows nothing about it.
+ *
+ * SECRETS: every prop is safe to render. There is no `sessionToken` (the secret
+ * claim/finalize credential), no bearer, and no authorization code — a host
+ * keeps those in its own controller, and no prop on this component invites one.
+ */
+
+import type React from 'react';
+import { View } from 'react-native';
+import { Button } from '@oxyhq/bloom/button';
+import { useTheme } from '@oxyhq/bloom/theme';
+import { Text } from '@oxyhq/bloom/typography';
+import type { CommonsDeliveryRoute, SignInProgress } from '@oxyhq/core';
+import { useI18n } from '../hooks/useI18n';
+import TroubleDisclosure from './authChooser/TroubleDisclosure';
+import { SubtleLink } from './authChooser/primitives';
+import { GetCommonsPrompt, RequestPrimarySurface } from './authChooser/requestSurfaces';
+import { signInProgressLabel } from './authChooser/signInProgress';
+import { authChooserStyles as styles } from './authChooser/styles';
+import type { OxySignInSurfaceAction } from './authChooser/types';
+
+/** Shared empty list, so an omitted action bundle allocates nothing per render. */
+const NO_ACTIONS: readonly OxySignInSurfaceAction[] = [];
+
+export interface OxySignInRequestSurfaceProps {
+  /**
+   * The ONE primary delivery route chosen for this request, or `null` while it
+   * is still being resolved. There is no chain: the surface renders exactly one
+   * route's visual, and never guesses one that has not been chosen yet.
+   */
+  route: CommonsDeliveryRoute | null;
+  /**
+   * The request's DERIVED progress — the only thing the status line is built
+   * from. It must come from a real observed signal (a server-reported delivery,
+   * an approver opening the request, an approval); the surface owns no clock and
+   * will never advance it on its own. `'idle'` means there is nothing honest to
+   * report, and renders no status line.
+   */
+  progress: SignInProgress;
+  /**
+   * The PUBLIC `oxycommons://approve?…` payload to encode as the QR, or `null`.
+   * It carries the single-use approval handle — never a secret credential — and
+   * the surface renders NOTHING derived from it.
+   */
+  qrPayload?: string | null;
+  /**
+   * `true` when the chosen primary route could not be carried out on this device.
+   * The one signal that reveals {@link alternatives} without the user asking;
+   * a host never silently cascades to another route on its own.
+   */
+  routeFailed?: boolean;
+  /**
+   * `true` when the request itself is terminally failed — there is no working
+   * primary route left to report on, so {@link onRetry} becomes the surface's one
+   * primary action and the alternatives render plainly.
+   */
+  failed?: boolean;
+  /**
+   * Start a BRAND-NEW request. Rendered as the primary action while
+   * {@link failed}; omit it when a fresh attempt cannot help (a request that
+   * would fail identically every time), leaving the alternatives as the only
+   * way forward.
+   */
+  onRetry?: () => void;
+  /**
+   * The acquisition action for a device where Commons is known to be ABSENT.
+   *
+   * Pass it ONLY on a positive "not installed" verdict. There, acquiring Commons
+   * is the GENUINE primary route — a same-device QR the user would have to scan
+   * with the very screen showing it is a dead end — so the surface leads with it
+   * and reports no route progress. Omit it wherever absence cannot be known (a
+   * browser cannot ask whether a URL scheme is registered).
+   */
+  onAcquireCommons?: () => void;
+  /**
+   * Subordinate links rendered directly beneath the primary, always visible:
+   * the ways OUT of the surface that are not troubleshooting (creating an
+   * account, cancelling the request).
+   */
+  subordinate?: readonly OxySignInSurfaceAction[];
+  /**
+   * The alternative ways to authenticate, kept behind "Having trouble?" until
+   * the user asks — or shown plainly once {@link failed} / {@link routeFailed}
+   * says the chosen route cannot deliver.
+   */
+  alternatives?: readonly OxySignInSurfaceAction[];
+}
+
+export const OxySignInRequestSurface: React.FC<OxySignInRequestSurfaceProps> = ({
+  route,
+  progress,
+  qrPayload = null,
+  routeFailed = false,
+  failed = false,
+  onRetry,
+  onAcquireCommons,
+  subordinate = NO_ACTIONS,
+  alternatives = NO_ACTIONS,
+}) => {
+  const theme = useTheme();
+  const { t } = useI18n();
+
+  const subordinateLinks = subordinate.map((action) => (
+    <SubtleLink
+      key={action.key}
+      label={action.label}
+      theme={theme}
+      onPress={action.onPress}
+      disabled={action.disabled}
+      testID={action.key}
+    />
+  ));
+
+  // A failed request has no working primary route left. Its REASON is the host's
+  // to surface (toast / banner); all this owes the user is the way forward.
+  if (failed) {
+    return (
+      <View style={styles.centeredBlock}>
+        {onRetry ? (
+          <Button variant="primary" onPress={onRetry} style={styles.primaryButton}>
+            {t('common.actions.tryAgain')}
+          </Button>
+        ) : null}
+        {subordinateLinks}
+        <TroubleDisclosure actions={alternatives} revealed theme={theme} t={t} />
+      </View>
+    );
+  }
+
+  // Commons is absent: acquiring it IS the primary route, not a fallback, so it
+  // renders as the one primary action and no route progress is reported (there is
+  // no route to report on until the host says otherwise).
+  if (onAcquireCommons) {
+    return (
+      <View style={styles.centeredBlock}>
+        <GetCommonsPrompt theme={theme} t={t} onGetCommons={onAcquireCommons} />
+        {subordinateLinks}
+        <TroubleDisclosure actions={alternatives} revealed={false} theme={theme} t={t} />
+      </View>
+    );
+  }
+
+  const status = signInProgressLabel(progress, route, t);
+
+  return (
+    <View style={styles.centeredBlock}>
+      <RequestPrimarySurface
+        route={route}
+        progress={progress}
+        qrPayload={qrPayload}
+        theme={theme}
+        t={t}
+      />
+      {status ? (
+        <Text
+          style={[styles.mutedText, { color: theme.colors.textSecondary }]}
+          accessibilityLiveRegion="polite"
+          testID="signin-progress"
+        >
+          {status}
+        </Text>
+      ) : null}
+      {subordinateLinks}
+      <TroubleDisclosure actions={alternatives} revealed={routeFailed} theme={theme} t={t} />
+    </View>
+  );
+};
+
+export default OxySignInRequestSurface;