@oxyhq/core 5.2.0 → 5.3.0

package/dist/types/CrossDomainAuth.d.ts

@@ -1,11 +1,19 @@
 /**
  * Cross-Domain Authentication Helper
  *
- * Provides a simplified API for cross-domain SSO authentication that automatically
- * selects the best authentication method based on browser capabilities:
+ * Provides a simplified API for cross-domain SSO authentication. The
+ * automatic sign-in path uses a full-page redirect through the central IdP
+ * (`auth.oxy.so`) — a tokenless, universal mechanism that works in every
+ * browser.
  *
- * 1. FedCM (if supported) - Modern, Google-style browser-native auth
- * 2. Redirect (fallback) - Tokenless central SSO full-page redirect
+ * FedCM (`signInWithFedCM`) is intentionally NOT part of the automatic
+ * (`'auto'`) path: it is a Chrome-only browser API, and a misconfigured or
+ * unreachable FedCM endpoint fails fast and silently, which — combined with a
+ * caller's auth-guard effect re-invoking `signIn()` whenever the user is still
+ * unauthenticated — produced a real production incident (an accelerating
+ * `autoSignIn` → FedCM-fails → redirect retry loop). `signInWithFedCM` remains
+ * available for callers that want to opt into it EXPLICITLY
+ * (`signIn({ method: 'fedcm' })`).
  *
  * Usage:
  * ```typescript
@@ -13,7 +21,7 @@
  *
  * const auth = new CrossDomainAuth(oxyServices);
  *
- * // Automatic method selection
+ * // Automatic method selection (always redirect)
  * const session = await auth.signIn();
  *
  * // Or use a specific method
@@ -47,18 +55,25 @@ export declare class CrossDomainAuth {
     private oxyServices;
     constructor(oxyServices: OxyServices);
     /**
-     * Sign in with automatic method selection
+     * Sign in with automatic method selection.
      *
-     * Tries methods in this order:
-     * 1. FedCM (if supported and not in private browsing)
-     * 2. Redirect (always works)
+     * Auto mode always uses the full-page redirect (see the class doc comment
+     * for why FedCM was removed from this path). Pass `{ method: 'fedcm' }` to
+     * opt into FedCM explicitly.
      *
      * @param options - Authentication options
      * @returns Session with user data and access token
      */
     signIn(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse | null>;
     /**
-     * Automatic sign-in with progressive enhancement
+     * Automatic sign-in.
+     *
+     * Goes straight to the full-page redirect — the sole automatic method.
+     * FedCM is deliberately NOT attempted here (see the class doc comment):
+     * it is Chrome-only, and its fast/silent failure mode combined with a
+     * caller's auth-guard effect re-invoking `signIn()` produced a real
+     * production sign-in loop. Use `signIn({ method: 'fedcm' })` to opt in
+     * explicitly.
      *
      * @private
      */
@@ -84,8 +99,9 @@ export declare class CrossDomainAuth {
     /**
      * Silent sign-in (check for existing session)
      *
-     * Tries to automatically sign in without user interaction.
-     * Works with FedCM and iframe-based silent auth.
+     * Tries to automatically sign in without user interaction, via the
+     * iframe-based silent auth against the per-apex `/auth/silent` IdP host.
+     * FedCM is deliberately NOT attempted here (see the class doc comment).
      *
      * @returns Session if user is already signed in, null otherwise
      */
@@ -104,10 +120,14 @@ export declare class CrossDomainAuth {
     /**
      * Get recommended authentication method for current environment
      *
+     * Redirect is the sole recommended automatic method — it works in every
+     * browser, unlike FedCM (Chrome-only). Callers that want FedCM must opt in
+     * explicitly via `signIn({ method: 'fedcm' })`.
+     *
      * @returns Recommended method name and reason
      */
     getRecommendedMethod(): {
-        method: 'fedcm' | 'redirect';
+        method: 'redirect';
         reason: string;
     };
     /**

package/dist/types/index.d.ts

@@ -93,10 +93,17 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
+export { establishIdpSessionAfterClaim } from './utils/ssoEstablish';
+export type { SsoEstablishClient, EstablishAfterClaimDeps } from './utils/ssoEstablish';
 export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce';
 export type { SsoBounceGate } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
+export { SessionClient } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export { createSessionClientHost } from './session/sessionClientHost';
+export { createSessionClient } from './session/createSessionClient';
+export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
 export { packageInfo } from './constants/version';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

package/dist/types/mixins/OxyServices.sso.d.ts

@@ -59,6 +59,30 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
          * @returns The resolved {@link SessionLoginResponse}.
          */
         exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
+        /**
+         * Mint a server-formed `/sso/establish` URL for the caller's OWN session,
+         * bound to an approved RP `origin`.
+         *
+         * Bearer-authenticated (the session id is taken from the caller's own
+         * bearer, server-side — never from any argument). The server validates that
+         * `origin` is an approved client origin (and matches the request `Origin`),
+         * derives the per-apex IdP host (`auth.<apex>`), mints a short-lived HS256
+         * establish-token, and returns a fully-formed
+         * `https://<auth-host>/sso/establish?et=…&return_to=<origin>/__oxy/sso-callback&state=<state>`.
+         *
+         * Used AFTER a web device-flow claim to plant the durable first-party
+         * `fedcm_session` cookie so a reload can re-mint a token (see
+         * {@link establishIdpSessionAfterClaim}). Cache-free (a POST is never
+         * cached, but `cache: false` is explicit).
+         *
+         * @param origin - The RP origin (`window.location.origin`) to establish for.
+         * @param state - The CSRF state echoed back in the callback fragment; the
+         *   caller persists the SAME value under `ssoStateKey(origin)` so the
+         *   post-bounce `sso-return` step validates it.
+         */
+        requestSsoEstablishUrl(origin: string, state: string): Promise<{
+            establishUrl: string;
+        }>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -327,6 +327,20 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             total: number;
             hasMore: boolean;
         }>;
+        /**
+         * Get the authenticated VIEWER's OWN mutual-follow user ids — the accounts the
+         * viewer follows that ALSO follow the viewer back (a bidirectional follow
+         * edge). The viewer is derived server-side from the SDK's auth token (never a
+         * param), so there is no target id to pass.
+         *
+         * Returns a bounded, lean list of ids meant to SEED a "Mutuals" feed (the
+         * consumer hydrates/ranks the posts itself) — distinct from
+         * {@link getUserMutuals}, which returns hydrated "followers you know" DTOs
+         * about ANOTHER profile. An anonymous caller resolves to an empty array.
+         */
+        getMutualUserIds(params?: {
+            limit?: number;
+        }): Promise<string[]>;
         /**
          * Get notifications
          */

package/dist/types/server/index.d.ts

@@ -23,3 +23,5 @@ export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, Ssr
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
+export { registrableApex } from '../utils/fapiAutoDetect';
+export { SSO_CALLBACK_PATH } from '../utils/ssoBounce';

package/dist/types/session/SessionClient.d.ts

@@ -0,0 +1,55 @@
+import { type DeviceSessionState } from '@oxyhq/contracts';
+import type { MinimalSocket } from './socketLoader';
+export interface TokenTransport {
+    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
+    ensureActiveToken(state: DeviceSessionState): Promise<void>;
+}
+export interface SessionClientHost {
+    makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: {
+        cache?: boolean;
+    }): Promise<T>;
+    getBaseURL(): string;
+    getAccessToken(): string | null;
+    onTokensChanged(listener: (token: string | null) => void): () => void;
+    setTokens(accessToken: string): void;
+    getCurrentAccountId(): string | null;
+}
+export interface SessionClientOptions {
+    transport?: TokenTransport;
+}
+type StateListener = (state: DeviceSessionState | null) => void;
+export declare class SessionClient {
+    protected readonly host: SessionClientHost;
+    protected readonly options: SessionClientOptions;
+    private state;
+    private readonly listeners;
+    protected socket: MinimalSocket | null;
+    private tokenUnsub;
+    private started;
+    constructor(host: SessionClientHost, options?: SessionClientOptions);
+    getState(): DeviceSessionState | null;
+    subscribe(listener: StateListener): () => void;
+    protected notify(): void;
+    /** Validate + last-writer-wins by revision. Returns true if applied. */
+    protected applyState(raw: unknown): boolean;
+    /**
+     * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
+     * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push
+     * followed by this same `GET /state` fetch returns the SAME revision (applyState no-ops), but
+     * the token still needs to be planted. The account-match guard rejects a stale response for an
+     * account that is no longer active.
+     */
+    private applySync;
+    bootstrap(): Promise<void>;
+    switchAccount(accountId: string): Promise<void>;
+    signOut(target: {
+        accountId: string;
+    } | {
+        all: true;
+    }): Promise<void>;
+    addCurrentAccount(): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    private connectSocket;
+}
+export {};

package/dist/types/session/createSessionClient.d.ts

@@ -0,0 +1,23 @@
+import type { OxyServices } from '../OxyServices';
+import { SessionClient, type TokenTransport } from './SessionClient';
+import { createSessionClientHost } from './sessionClientHost';
+/**
+ * Wires a `SessionClient` over the given `OxyServices` instance: builds the
+ * `SessionClientHost` adapter and passes it through together with a
+ * caller-supplied `TokenTransport`.
+ *
+ * The transport is a required parameter (not constructed here) because it is
+ * the one piece of this integration that is NOT platform-agnostic: `services`
+ * branches native (shared-keychain sign-in) vs. web (silent sign-in), while
+ * `auth-sdk` is web-only. Each consumer builds its own transport and passes
+ * it in; this factory only wires the platform-agnostic parts (host + client)
+ * so neither consumer re-implements them.
+ *
+ * The host is returned alongside the client (not just the client) so the
+ * caller can call `host.setCurrentAccountId(...)` as the active account
+ * changes.
+ */
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport): {
+    client: SessionClient;
+    host: ReturnType<typeof createSessionClientHost>;
+};

package/dist/types/session/projectSessionState.d.ts

@@ -0,0 +1,43 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { ClientSession } from '../models/session';
+import type { User } from '../models/interfaces';
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes consumers (`@oxyhq/services`, `@oxyhq/auth`) render today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ */
+/**
+ * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
+ *
+ * `DeviceSessionState` carries no per-account `expiresAt` / `lastActive` —
+ * both are set to `state.updatedAt` (converted to an ISO-8601 string; the
+ * wire value is an epoch-ms number) as a provisional value.
+ *
+ * `usersById` is accepted for signature symmetry with `activeUserOf` even
+ * though `ClientSession` only stores `userId` — a session is still
+ * projected for an account whose id is absent from `usersById` (no
+ * placeholder user is fabricated).
+ */
+export declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>): ClientSession[];
+/**
+ * The active account's `sessionId`, or `null` when there is no state or no
+ * active account is set.
+ */
+export declare function activeSessionIdOf(state: DeviceSessionState | null): string | null;
+/**
+ * The active account's `User`, resolved from `usersById`. `null` when there
+ * is no state, no active account is set, or the active account id is absent
+ * from `usersById`.
+ */
+export declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>): User | null;
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export declare function accountIdsOf(state: DeviceSessionState | null): string[];

package/dist/types/session/sessionClientHost.d.ts

@@ -0,0 +1,18 @@
+import type { OxyServices } from '../OxyServices';
+import type { SessionClientHost } from './SessionClient';
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` is host-agnostic: it only needs a REST + token surface.
+ * `OxyServices` already exposes all of that except `getCurrentAccountId`,
+ * which has no direct equivalent — the adapter holds a mutable ref set by
+ * the caller (`OxyContext` in `@oxyhq/services`, `WebOxyProvider` in
+ * `@oxyhq/auth`) via `setCurrentAccountId`.
+ *
+ * Shared here (rather than duplicated per consumer) because it is entirely
+ * platform-agnostic: every method it calls exists identically on
+ * `OxyServices` regardless of host (web, Expo/RN, Node).
+ */
+export declare function createSessionClientHost(oxyServices: OxyServices): SessionClientHost & {
+    setCurrentAccountId(id: string | null): void;
+};

package/dist/types/session/socketLoader.d.ts

@@ -0,0 +1,9 @@
+export interface MinimalSocket {
+    connected: boolean;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    connect(): void;
+    disconnect(): void;
+}
+export type SocketIOFactory = (uri: string, opts?: Record<string, unknown>) => MinimalSocket;
+export declare function getSocketIO(): Promise<SocketIOFactory | null>;

package/dist/types/utils/ssoBounce.d.ts

@@ -103,18 +103,18 @@ export declare function ssoPriorSessionKey(origin: string): string;
  * per-tab `sessionStorage` the loop-breaker keys use — it must survive a reload.
  *
  * It exists purely to suppress AUTOMATIC silent restore after a deliberate
- * sign-out: a still-live IdP session (the central `fedcm_session` / the FedCM
- * credential association) would otherwise let `fedcm-silent` / the per-apex
- * `/auth/silent` iframe re-mint a session on the very next cold boot, so a user
- * who pressed "Sign out" gets silently signed back in on reload. With this flag
- * set, those silent cold-boot steps are skipped while the Gmail-style
- * returning-account fast-path is otherwise preserved.
+ * sign-out: a still-live IdP session (the central `fedcm_session`) would
+ * otherwise let the per-apex `/auth/silent` iframe re-mint a session on the
+ * very next cold boot, so a user who pressed "Sign out" gets silently signed
+ * back in on reload. With this flag set, that silent cold-boot step is
+ * skipped while the Gmail-style returning-account fast-path is otherwise
+ * preserved.
  *
  * Lifecycle (mirrors the existing gate machinery — set on a definitive event,
  * cleared on its inverse):
  *   - SET on EXPLICIT full sign-out (alongside clearing the prior-session hint
  *     and the SSO bounce state).
- *   - CLEARED on ANY deliberate sign-in (password, FedCM, account switch, device
+ *   - CLEARED on ANY deliberate sign-in (password, account switch, device
  *     claim) so a real sign-in fully re-enables silent restore — there is no
  *     "stuck signed out" state.
  *
@@ -206,8 +206,8 @@ export declare function guardActive(storage: Pick<Storage, 'getItem'>, origin: s
  * Whether AUTOMATIC silent restore is SUPPRESSED for this origin because the
  * user deliberately signed out (the durable {@link ssoSignedOutKey} flag).
  *
- * When `true`, the silent cold-boot steps that can re-mint a session from a
- * still-live IdP session WITHOUT user intent — `fedcm-silent` and the per-apex
+ * When `true`, the silent cold-boot step that can re-mint a session from a
+ * still-live IdP session WITHOUT user intent — the per-apex
  * `/auth/silent` iframe — MUST be skipped, so a user who pressed "Sign out" is
  * not silently signed back in on the next reload. Interactive sign-in clears the
  * flag, so this never blocks a deliberate re-sign-in.

package/dist/types/utils/ssoEstablish.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Post-claim durable-session establish hop (web device-flow / "Sign in with
+ * Oxy" QR).
+ *
+ * A WEB device-flow claim (`claimSessionByToken`) plants only IN-MEMORY tokens:
+ * unlike a redirect/FedCM/silent sign-in, it never causes the IdP to plant a
+ * `fedcm_session` cookie. So a reload has nothing to restore from — the
+ * silent-iframe and `/sso` paths find no IdP session and the session is lost.
+ *
+ * This primitive closes that gap. AFTER the claim has committed and the session
+ * has been durably persisted, it performs ONE top-level establish hop through
+ * the RP's own per-apex IdP host (`auth.<rp-apex>`), reusing the EXISTING
+ * `/sso/establish` endpoint: the server mints a short-lived, host+audience-bound
+ * establish-token and returns a fully-formed establish URL; navigating to it
+ * plants the durable first-party `fedcm_session` cookie and bounces back to the
+ * RP callback with an opaque code the standard `sso-return` cold-boot step
+ * exchanges.
+ *
+ * It reuses the SAME per-origin `sessionStorage` bounce contract
+ * (`ssoStateKey` / `ssoGuardKey` / `ssoDestKey`) that {@link buildSsoBounceUrl}
+ * primes for the terminal `/sso` bounce, so the post-bounce `sso-return` step
+ * (`consumeSsoReturn`) validates the CSRF `state`, exchanges the code, and
+ * restores the user's real destination with no extra wiring.
+ *
+ * Contract:
+ *  - WEB only — off-web / native it is a no-op returning `false`.
+ *  - NEVER fires while sitting on the central IdP origin (that would loop the
+ *    IdP against itself).
+ *  - Bounce state is persisted ONLY after the establish-URL request succeeds, so
+ *    a failed request leaves no stale state behind.
+ *  - SINGLE attempt: the caller invokes this exactly once per successful claim.
+ *    On ANY failure it does NOT navigate and returns `false`, leaving the
+ *    committed in-memory session exactly as-is (the user is no worse off than
+ *    before this hop existed).
+ *  - Total: never throws. Failures are reported via {@link deps.onError} only.
+ */
+/**
+ * The minimal SDK surface this hop needs: mint a server-formed establish URL
+ * bound to the caller's own session for an approved RP origin. Structural so the
+ * primitive is unit-testable with a stub and never imports the full client.
+ */
+export interface SsoEstablishClient {
+    requestSsoEstablishUrl(origin: string, state: string): Promise<{
+        establishUrl: string;
+    }>;
+}
+/**
+ * Injectable web seams for {@link establishIdpSessionAfterClaim}. Every seam is
+ * overridable so the primitive is fully unit-testable with fakes and so native
+ * callers rely on the defaults (which resolve to `window.*` only when a browser
+ * is present). Defaults are evaluated lazily inside the function so importing
+ * this module never touches `window`.
+ */
+export interface EstablishAfterClaimDeps {
+    /** Per-tab SSO bounce store. Default: `window.sessionStorage`. */
+    storage?: Pick<Storage, 'getItem' | 'setItem'>;
+    /** The current location. Default: `window.location`. */
+    location?: Pick<Location, 'origin' | 'href'>;
+    /** Top-level navigation seam. Default: {@link ssoNavigate} (`location.assign`). */
+    navigate?: (url: string) => void;
+    /**
+     * Whether the current environment is a web browser with usable
+     * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
+     * window.sessionStorage !== 'undefined'`.
+     */
+    isWeb?: () => boolean;
+    /** CSRF state generator. Default: {@link generateSsoState}. */
+    generateState?: () => string;
+    /** Epoch-ms clock for the bounce guard. Default: `Date.now`. */
+    now?: () => number;
+    /**
+     * Optional debug hook invoked with the thrown error when the establish
+     * request (or state persistence) fails. NEVER rethrown. Default: no-op.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Perform the post-claim establish hop. Returns `true` when a navigation to the
+ * establish URL was initiated (the document is being torn down and replaced by
+ * the IdP), `false` on every no-op / failure path.
+ *
+ * @param client - The exchange surface (`oxyServices.requestSsoEstablishUrl`).
+ * @param deps - Injectable web seams; see {@link EstablishAfterClaimDeps}.
+ */
+export declare function establishIdpSessionAfterClaim(client: SsoEstablishClient, deps?: EstablishAfterClaimDeps): Promise<boolean>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/CrossDomainAuth.ts

@@ -1,11 +1,19 @@
 /**
  * Cross-Domain Authentication Helper
  *
- * Provides a simplified API for cross-domain SSO authentication that automatically
- * selects the best authentication method based on browser capabilities:
+ * Provides a simplified API for cross-domain SSO authentication. The
+ * automatic sign-in path uses a full-page redirect through the central IdP
+ * (`auth.oxy.so`) — a tokenless, universal mechanism that works in every
+ * browser.
  *
- * 1. FedCM (if supported) - Modern, Google-style browser-native auth
- * 2. Redirect (fallback) - Tokenless central SSO full-page redirect
+ * FedCM (`signInWithFedCM`) is intentionally NOT part of the automatic
+ * (`'auto'`) path: it is a Chrome-only browser API, and a misconfigured or
+ * unreachable FedCM endpoint fails fast and silently, which — combined with a
+ * caller's auth-guard effect re-invoking `signIn()` whenever the user is still
+ * unauthenticated — produced a real production incident (an accelerating
+ * `autoSignIn` → FedCM-fails → redirect retry loop). `signInWithFedCM` remains
+ * available for callers that want to opt into it EXPLICITLY
+ * (`signIn({ method: 'fedcm' })`).
  *
  * Usage:
  * ```typescript
@@ -13,7 +21,7 @@
  *
  * const auth = new CrossDomainAuth(oxyServices);
  *
- * // Automatic method selection
+ * // Automatic method selection (always redirect)
  * const session = await auth.signIn();
  *
  * // Or use a specific method
@@ -54,11 +62,11 @@ export class CrossDomainAuth {
   constructor(private oxyServices: OxyServices) {}
 
   /**
-   * Sign in with automatic method selection
+   * Sign in with automatic method selection.
    *
-   * Tries methods in this order:
-   * 1. FedCM (if supported and not in private browsing)
-   * 2. Redirect (always works)
+   * Auto mode always uses the full-page redirect (see the class doc comment
+   * for why FedCM was removed from this path). Pass `{ method: 'fedcm' }` to
+   * opt into FedCM explicitly.
    *
    * @param options - Authentication options
    * @returns Session with user data and access token
@@ -80,22 +88,18 @@ export class CrossDomainAuth {
   }
 
   /**
-   * Automatic sign-in with progressive enhancement
+   * Automatic sign-in.
+   *
+   * Goes straight to the full-page redirect — the sole automatic method.
+   * FedCM is deliberately NOT attempted here (see the class doc comment):
+   * it is Chrome-only, and its fast/silent failure mode combined with a
+   * caller's auth-guard effect re-invoking `signIn()` produced a real
+   * production sign-in loop. Use `signIn({ method: 'fedcm' })` to opt in
+   * explicitly.
    *
    * @private
    */
   private async autoSignIn(options: CrossDomainAuthOptions): Promise<SessionLoginResponse | null> {
-    // 1. Try FedCM first (best UX, most modern)
-    if (this.isFedCMSupported()) {
-      try {
-        options.onMethodSelected?.('fedcm');
-        return await this.signInWithFedCM(options);
-      } catch (error) {
-        logger.warn('FedCM failed, falling back to redirect', { component: 'CrossDomainAuth', method: 'autoSignIn' }, error);
-      }
-    }
-
-    // 2. Fallback to redirect (always works)
     options.onMethodSelected?.('redirect');
     this.signInWithRedirect(options);
     return null;
@@ -136,25 +140,13 @@ export class CrossDomainAuth {
   /**
    * Silent sign-in (check for existing session)
    *
-   * Tries to automatically sign in without user interaction.
-   * Works with FedCM and iframe-based silent auth.
+   * Tries to automatically sign in without user interaction, via the
+   * iframe-based silent auth against the per-apex `/auth/silent` IdP host.
+   * FedCM is deliberately NOT attempted here (see the class doc comment).
    *
    * @returns Session if user is already signed in, null otherwise
    */
   async silentSignIn(): Promise<SessionLoginResponse | null> {
-    // Try FedCM silent sign-in first (if supported)
-    if (this.isFedCMSupported()) {
-      try {
-        const session = await this.oxyServices.silentSignInWithFedCM();
-        if (session) {
-          return session;
-        }
-      } catch (error) {
-        logger.debug('FedCM silent sign-in did not resolve', { component: 'CrossDomainAuth', method: 'silentSignIn' }, error);
-      }
-    }
-
-    // Fallback to iframe-based silent auth
     try {
       return await this.oxyServices.silentSignIn();
     } catch (error) {
@@ -185,16 +177,13 @@ export class CrossDomainAuth {
   /**
    * Get recommended authentication method for current environment
    *
+   * Redirect is the sole recommended automatic method — it works in every
+   * browser, unlike FedCM (Chrome-only). Callers that want FedCM must opt in
+   * explicitly via `signIn({ method: 'fedcm' })`.
+   *
    * @returns Recommended method name and reason
    */
-  getRecommendedMethod(): { method: 'fedcm' | 'redirect'; reason: string } {
-    if (this.isFedCMSupported()) {
-      return {
-        method: 'fedcm',
-        reason: 'FedCM is supported - provides best UX with browser-native auth',
-      };
-    }
-
+  getRecommendedMethod(): { method: 'redirect'; reason: string } {
     if (typeof window !== 'undefined') {
       return {
         method: 'redirect',