@oxyhq/core 5.2.1 → 5.4.0

package/dist/esm/CrossDomainAuth.js

@@ -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
@@ -26,11 +34,11 @@ export class CrossDomainAuth {
         this.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
@@ -48,22 +56,18 @@ export class CrossDomainAuth {
         return this.autoSignIn(options);
     }
     /**
-     * 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
      */
     async autoSignIn(options) {
-        // 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;
@@ -100,25 +104,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() {
-        // 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();
         }
@@ -147,15 +139,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() {
-        if (this.isFedCMSupported()) {
-            return {
-                method: 'fedcm',
-                reason: 'FedCM is supported - provides best UX with browser-native auth',
-            };
-        }
         if (typeof window !== 'undefined') {
             return {
                 method: 'redirect',

package/dist/esm/index.js

@@ -126,9 +126,23 @@ export { autoDetectAuthWebUrl, registrableApex } from './utils/fapiAutoDetect.js
 export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl.js';
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn.js';
 export { generateSsoState } from './mixins/OxyServices.sso.js';
+// Post-claim durable-session establish hop (web device-flow / QR sign-in).
+export { establishIdpSessionAfterClaim } from './utils/ssoEstablish.js';
 // SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
 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.js';
 export { runColdBoot } from './utils/coldBoot.js';
+// ---------------------------------------------------------------------------
+// Session sync (device-scoped multi-account session client)
+// ---------------------------------------------------------------------------
+export { SessionClient } from './session/SessionClient.js';
+// Shared SessionClient integration layer: the host adapter, the pure
+// DeviceSessionState projection helpers, and the client factory are defined
+// ONCE here so `@oxyhq/services` and `@oxyhq/auth` both reuse them instead of
+// duplicating a local copy. Each consumer supplies its own `TokenTransport`
+// (native vs. web mint strategies differ) to `createSessionClient`.
+export { createSessionClientHost } from './session/sessionClientHost.js';
+export { createSessionClient } from './session/createSessionClient.js';
+export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState.js';
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every
 // client SDK. Import them directly from `@oxyhq/contracts`; `@oxyhq/core` does NOT

package/dist/esm/mixins/OxyServices.sso.js

@@ -164,5 +164,41 @@ export function OxyServicesSsoMixin(Base) {
             };
             return session;
         }
+        /**
+         * 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.
+         */
+        async requestSsoEstablishUrl(origin, state) {
+            if (typeof origin !== 'string' || origin.length === 0) {
+                throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty origin'));
+            }
+            if (typeof state !== 'string' || state.length === 0) {
+                throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty state'));
+            }
+            const response = await this.makeRequest('POST', '/sso/establish-token', { origin, state }, { cache: false });
+            if (!response ||
+                typeof response.establishUrl !== 'string' ||
+                response.establishUrl.length === 0) {
+                throw this.handleError(new Error('SSO establish-token returned no establishUrl'));
+            }
+            return { establishUrl: response.establishUrl };
+        }
     };
 }

package/dist/esm/mixins/OxyServices.user.js

@@ -630,6 +630,56 @@ export function OxyServicesUserMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * 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.
+         */
+        async getMutualUserIds(params) {
+            try {
+                const query = buildPaginationParams(params || {});
+                const response = await this.makeRequest('GET', '/users/mutual-ids', query, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                return response.data || [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Get the authenticated VIEWER's bounded "follows-of-follows" user ids — the
+         * union of the accounts followed by the accounts the viewer follows (a
+         * two-hop walk of the follow graph), MINUS the viewer's own follows and the
+         * viewer themselves. 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 friends-of-friends
+         * feed (the consumer hydrates/ranks the posts itself), ordered by frequency
+         * (accounts followed by more of the viewer's follows first), then recency.
+         * An anonymous caller resolves to an empty array. Mirrors
+         * {@link getMutualUserIds}'s caching posture.
+         */
+        async getFollowsOfFollowsIds(params) {
+            try {
+                const query = buildPaginationParams(params || {});
+                const response = await this.makeRequest('GET', '/users/follows-of-follows-ids', query, {
+                    cache: true,
+                    cacheTTL: 2 * 60 * 1000, // 2 minutes cache
+                });
+                return response.data || [];
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
         /**
          * Get notifications
          */

package/dist/esm/server/index.js

@@ -22,3 +22,13 @@ export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamErr
 export { createOxyCors } from './cors.js';
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret.js';
+// Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
+// SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
+// Pure host handling (no browser deps), so it is safe on the server subpath and
+// lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
+export { registrableApex } from '../utils/fapiAutoDetect.js';
+// The single RP callback path the IdP redirects back to. A pure wire-contract
+// constant (no browser deps at module top level), re-used server-side so the
+// `/sso/establish-token` `return_to` cannot drift from what `/sso/establish`
+// validates.
+export { SSO_CALLBACK_PATH } from '../utils/ssoBounce.js';

package/dist/esm/session/SessionClient.js

@@ -0,0 +1,148 @@
+import { deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, } from '@oxyhq/contracts';
+import { logger } from '../utils/loggerUtils.js';
+import { getSocketIO } from './socketLoader.js';
+export class SessionClient {
+    constructor(host, options = {}) {
+        this.host = host;
+        this.options = options;
+        this.state = null;
+        this.listeners = new Set();
+        this.socket = null;
+        this.tokenUnsub = null;
+        this.started = false;
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener(this.state);
+            }
+            catch (error) {
+                logger.error('[SessionClient] subscriber threw', error);
+            }
+        }
+    }
+    /** Validate + last-writer-wins by revision. Returns true if applied. */
+    applyState(raw) {
+        const next = safeParseContract(deviceSessionStateSchema, raw);
+        if (!next) {
+            logger.warn('[SessionClient] discarded invalid session state');
+            return false;
+        }
+        if (this.state && next.revision <= this.state.revision) {
+            return false;
+        }
+        this.state = next;
+        this.notify();
+        if (this.options.transport) {
+            void this.options.transport.ensureActiveToken(next).catch((error) => {
+                logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+            });
+        }
+        return true;
+    }
+    /**
+     * 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.
+     */
+    applySync(raw) {
+        const sync = safeParseContract(deviceSessionSyncSchema, raw);
+        if (!sync) {
+            const parsed = deviceSessionSyncSchema.safeParse(raw);
+            // Log field-level type diagnostics ONLY — never values. The payload carries tokens and
+            // session ids; issue.path/code and the invalid_type expected/received TYPE names are safe,
+            // but zod messages can embed offending values for other codes, so they are omitted.
+            const issues = parsed.success
+                ? []
+                : parsed.error.issues.map((issue) => issue.code === 'invalid_type'
+                    ? { path: issue.path.join('.'), code: issue.code, expected: issue.expected, received: issue.received }
+                    : { path: issue.path.join('.'), code: issue.code });
+            const keys = raw && typeof raw === 'object' ? Object.keys(raw) : [];
+            logger.warn('[SessionClient] discarded invalid session sync', { component: 'SessionClient', issues, keys });
+            return;
+        }
+        this.applyState(sync.state);
+        if (sync.activeToken && this.state && sync.state.activeAccountId === this.state.activeAccountId) {
+            this.host.setTokens(sync.activeToken.accessToken);
+        }
+    }
+    async bootstrap() {
+        const res = await this.host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
+        this.applySync(res);
+    }
+    async switchAccount(accountId) {
+        const res = await this.host.makeRequest('POST', '/session/device/switch', { accountId }, { cache: false });
+        this.applySync(res);
+    }
+    async signOut(target) {
+        const res = await this.host.makeRequest('POST', '/session/device/signout', target, { cache: false });
+        this.applySync(res);
+    }
+    async addCurrentAccount() {
+        const res = await this.host.makeRequest('POST', '/session/device/add', undefined, { cache: false });
+        this.applySync(res);
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.tokenUnsub = this.host.onTokensChanged((token) => {
+            if (token && this.socket && !this.socket.connected) {
+                this.socket.connect();
+            }
+        });
+        await this.bootstrap();
+        await this.connectSocket();
+    }
+    stop() {
+        this.started = false;
+        if (this.tokenUnsub) {
+            this.tokenUnsub();
+            this.tokenUnsub = null;
+        }
+        if (this.socket) {
+            this.socket.disconnect();
+            this.socket = null;
+        }
+    }
+    async connectSocket() {
+        const io = await getSocketIO();
+        if (!io) {
+            logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
+            return;
+        }
+        if (!this.started)
+            return; // stopped while the dynamic import was in flight
+        const hasToken = Boolean(this.host.getAccessToken());
+        const socket = io(this.host.getBaseURL(), {
+            transports: ['websocket'],
+            autoConnect: hasToken,
+            auth: (cb) => {
+                cb({ token: this.host.getAccessToken() ?? '' });
+            },
+        });
+        socket.on('session_state', (payload) => {
+            const applied = this.applyState(payload);
+            if (applied) {
+                const active = this.state?.activeAccountId ?? null;
+                if (active && active !== this.host.getCurrentAccountId()) {
+                    void this.bootstrap().catch((error) => {
+                        logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
+                    });
+                }
+            }
+        });
+        this.socket = socket;
+    }
+}

package/dist/esm/session/createSessionClient.js

@@ -0,0 +1,23 @@
+import { SessionClient } from './SessionClient.js';
+import { createSessionClientHost } from './sessionClientHost.js';
+/**
+ * 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 function createSessionClient(oxyServices, transport) {
+    const host = createSessionClientHost(oxyServices);
+    const client = new SessionClient(host, { transport });
+    return { client, host };
+}

package/dist/esm/session/projectSessionState.js

@@ -0,0 +1,69 @@
+/**
+ * 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 function deviceStateToClientSessions(state, usersById) {
+    const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+    return state.accounts.map((account) => ({
+        sessionId: account.sessionId,
+        deviceId: state.deviceId,
+        // provisional: expiresAt/lastActive are not carried on DeviceSessionState
+        expiresAt: provisionalTimestamp,
+        lastActive: provisionalTimestamp,
+        userId: account.accountId,
+        isCurrent: account.accountId === state.activeAccountId,
+        authuser: account.authuser,
+    }));
+}
+/**
+ * The active account's `sessionId`, or `null` when there is no state or no
+ * active account is set.
+ */
+export function activeSessionIdOf(state) {
+    if (state === null || state.activeAccountId === null) {
+        return null;
+    }
+    const activeAccountId = state.activeAccountId;
+    const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
+    return activeAccount?.sessionId ?? 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 function activeUserOf(state, usersById) {
+    if (state === null || state.activeAccountId === null) {
+        return null;
+    }
+    return usersById.get(state.activeAccountId) ?? null;
+}
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export function accountIdsOf(state) {
+    if (state === null) {
+        return [];
+    }
+    return state.accounts.map((account) => account.accountId);
+}

package/dist/esm/session/sessionClientHost.js

@@ -0,0 +1,27 @@
+/**
+ * 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 function createSessionClientHost(oxyServices) {
+    let currentAccountId = null;
+    return {
+        makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
+        getBaseURL: () => oxyServices.getBaseURL(),
+        getAccessToken: () => oxyServices.getAccessToken(),
+        onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
+        setTokens: (accessToken) => oxyServices.setTokens(accessToken),
+        getCurrentAccountId: () => currentAccountId,
+        setCurrentAccountId: (id) => {
+            currentAccountId = id;
+        },
+    };
+}

package/dist/esm/session/socketLoader.js

@@ -0,0 +1,19 @@
+import { logger } from '../utils/loggerUtils.js';
+let cachedFactory = null;
+let loadAttempted = false;
+export async function getSocketIO() {
+    if (cachedFactory)
+        return cachedFactory;
+    if (loadAttempted)
+        return null;
+    loadAttempted = true;
+    try {
+        const mod = (await import('socket.io-client'));
+        cachedFactory = mod.io ?? mod.default ?? null;
+        return cachedFactory;
+    }
+    catch (error) {
+        logger.warn('[SessionClient] socket.io-client import failed; realtime session sync disabled', { component: 'SessionClient' }, error);
+        return null;
+    }
+}

package/dist/esm/utils/ssoBounce.js

@@ -124,18 +124,18 @@ export function ssoPriorSessionKey(origin) {
  * 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.
  *
@@ -279,8 +279,8 @@ export function guardActive(storage, origin, now = Date.now()) {
  * 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.