@oxyhq/core 5.2.0 → 5.3.0

package/dist/cjs/CrossDomainAuth.js

@@ -2,11 +2,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
@@ -14,7 +22,7 @@
  *
  * const auth = new CrossDomainAuth(oxyServices);
  *
- * // Automatic method selection
+ * // Automatic method selection (always redirect)
  * const session = await auth.signIn();
  *
  * // Or use a specific method
@@ -30,11 +38,11 @@ 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
@@ -52,22 +60,18 @@ 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) {
-                loggerUtils_1.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;
@@ -104,25 +108,13 @@ 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) {
-                loggerUtils_1.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();
         }
@@ -151,15 +143,13 @@ 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/cjs/i18n/locales/ar-SA.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "قائمة الحساب",
         "manage": "إدارة حساب Oxy الخاص بك",
+        "viewProfile": "عرض الملف الشخصي",
         "addAnother": "إضافة حساب آخر",
         "signOutAll": "تسجيل الخروج من جميع الحسابات",
         "open": "قائمة الحساب",

package/dist/cjs/i18n/locales/ca-ES.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menú del compte",
         "manage": "Gestiona el teu compte d'Oxy",
+        "viewProfile": "Mostra el perfil",
         "addAnother": "Afegeix un altre compte",
         "signOutAll": "Tanca la sessió de tots els comptes",
         "open": "Menú del compte",

package/dist/cjs/i18n/locales/de-DE.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Kontomenü",
         "manage": "Ihr Oxy-Konto verwalten",
+        "viewProfile": "Profil ansehen",
         "addAnother": "Weiteres Konto hinzufügen",
         "signOutAll": "Von allen Konten abmelden",
         "open": "Kontomenü",

package/dist/cjs/i18n/locales/en-US.json

@@ -1555,6 +1555,7 @@
     "accountMenu": {
         "label": "Account menu",
         "manage": "Manage your Oxy Account",
+        "viewProfile": "View profile",
         "addAnother": "Add another account",
         "signOutAll": "Sign out of all accounts",
         "open": "Account menu",

package/dist/cjs/i18n/locales/es-ES.json

@@ -1555,6 +1555,7 @@
     "accountMenu": {
         "label": "Menú de cuenta",
         "manage": "Gestiona tu cuenta de Oxy",
+        "viewProfile": "Ver perfil",
         "addAnother": "Añadir otra cuenta",
         "signOutAll": "Cerrar sesión en todas las cuentas",
         "open": "Menú de cuenta",

package/dist/cjs/i18n/locales/fr-FR.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu du compte",
         "manage": "Gérer votre compte Oxy",
+        "viewProfile": "Voir le profil",
         "addAnother": "Ajouter un autre compte",
         "signOutAll": "Se déconnecter de tous les comptes",
         "open": "Menu du compte",

package/dist/cjs/i18n/locales/it-IT.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu account",
         "manage": "Gestisci il tuo account Oxy",
+        "viewProfile": "Visualizza profilo",
         "addAnother": "Aggiungi un altro account",
         "signOutAll": "Esci da tutti gli account",
         "open": "Menu account",

package/dist/cjs/i18n/locales/ja-JP.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "アカウントメニュー",
         "manage": "Oxy アカウントを管理",
+        "viewProfile": "プロフィールを表示",
         "addAnother": "別のアカウントを追加",
         "signOutAll": "すべてのアカウントからログアウト",
         "open": "アカウントメニュー",

package/dist/cjs/i18n/locales/ko-KR.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "계정 메뉴",
         "manage": "Oxy 계정 관리",
+        "viewProfile": "프로필 보기",
         "addAnother": "다른 계정 추가",
         "signOutAll": "모든 계정에서 로그아웃",
         "open": "계정 메뉴",

package/dist/cjs/i18n/locales/locales/ar-SA.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "قائمة الحساب",
     "manage": "إدارة حساب Oxy الخاص بك",
+    "viewProfile": "عرض الملف الشخصي",
     "addAnother": "إضافة حساب آخر",
     "signOutAll": "تسجيل الخروج من جميع الحسابات",
     "open": "قائمة الحساب",

package/dist/cjs/i18n/locales/locales/ca-ES.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menú del compte",
     "manage": "Gestiona el teu compte d'Oxy",
+    "viewProfile": "Mostra el perfil",
     "addAnother": "Afegeix un altre compte",
     "signOutAll": "Tanca la sessió de tots els comptes",
     "open": "Menú del compte",

package/dist/cjs/i18n/locales/locales/de-DE.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Kontomenü",
     "manage": "Ihr Oxy-Konto verwalten",
+    "viewProfile": "Profil ansehen",
     "addAnother": "Weiteres Konto hinzufügen",
     "signOutAll": "Von allen Konten abmelden",
     "open": "Kontomenü",

package/dist/cjs/i18n/locales/locales/en-US.json

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Account menu",
     "manage": "Manage your Oxy Account",
+    "viewProfile": "View profile",
     "addAnother": "Add another account",
     "signOutAll": "Sign out of all accounts",
     "open": "Account menu",

package/dist/cjs/i18n/locales/locales/es-ES.json

@@ -1555,6 +1555,7 @@
   "accountMenu": {
     "label": "Menú de cuenta",
     "manage": "Gestiona tu cuenta de Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Añadir otra cuenta",
     "signOutAll": "Cerrar sesión en todas las cuentas",
     "open": "Menú de cuenta",

package/dist/cjs/i18n/locales/locales/fr-FR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu du compte",
     "manage": "Gérer votre compte Oxy",
+    "viewProfile": "Voir le profil",
     "addAnother": "Ajouter un autre compte",
     "signOutAll": "Se déconnecter de tous les comptes",
     "open": "Menu du compte",

package/dist/cjs/i18n/locales/locales/it-IT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu account",
     "manage": "Gestisci il tuo account Oxy",
+    "viewProfile": "Visualizza profilo",
     "addAnother": "Aggiungi un altro account",
     "signOutAll": "Esci da tutti gli account",
     "open": "Menu account",

package/dist/cjs/i18n/locales/locales/ja-JP.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "アカウントメニュー",
     "manage": "Oxy アカウントを管理",
+    "viewProfile": "プロフィールを表示",
     "addAnother": "別のアカウントを追加",
     "signOutAll": "すべてのアカウントからログアウト",
     "open": "アカウントメニュー",

package/dist/cjs/i18n/locales/locales/ko-KR.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "계정 메뉴",
     "manage": "Oxy 계정 관리",
+    "viewProfile": "프로필 보기",
     "addAnother": "다른 계정 추가",
     "signOutAll": "모든 계정에서 로그아웃",
     "open": "계정 메뉴",

package/dist/cjs/i18n/locales/locales/pt-PT.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "Menu da conta",
     "manage": "Gerir a sua conta Oxy",
+    "viewProfile": "Ver perfil",
     "addAnother": "Adicionar outra conta",
     "signOutAll": "Terminar sessão em todas as contas",
     "open": "Menu da conta",

package/dist/cjs/i18n/locales/locales/zh-CN.json

@@ -207,6 +207,7 @@
   "accountMenu": {
     "label": "账户菜单",
     "manage": "管理您的 Oxy 账户",
+    "viewProfile": "查看个人资料",
     "addAnother": "添加其他账户",
     "signOutAll": "退出所有账户",
     "open": "账户菜单",

package/dist/cjs/i18n/locales/pt-PT.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "Menu da conta",
         "manage": "Gerir a sua conta Oxy",
+        "viewProfile": "Ver perfil",
         "addAnother": "Adicionar outra conta",
         "signOutAll": "Terminar sessão em todas as contas",
         "open": "Menu da conta",

package/dist/cjs/i18n/locales/zh-CN.json

@@ -207,6 +207,7 @@
     "accountMenu": {
         "label": "账户菜单",
         "manage": "管理您的 Oxy 账户",
+        "viewProfile": "查看个人资料",
         "addAnother": "添加其他账户",
         "signOutAll": "退出所有账户",
         "open": "账户菜单",

package/dist/cjs/index.js

@@ -20,8 +20,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.isRTLLocale = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.verifyPublicCardAttestation = exports.parseAttestPayload = exports.parseIdPayload = exports.buildUserDid = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.createCrossDomainAuth = exports.CrossDomainAuth = exports.createAuthManager = exports.AuthManager = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
 exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = void 0;
-exports.ssoPriorSessionKey = exports.ssoAttemptedKey = exports.ssoNoSessionKey = exports.ssoDestKey = exports.ssoGuardKey = exports.ssoStateKey = exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = exports.generateSsoState = exports.consumeSsoReturn = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_IDP_APEX = exports.CENTRAL_AUTH_URL = exports.registrableApex = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = void 0;
-exports.packageInfo = exports.runColdBoot = exports.allowSsoBounce = exports.silentRestoreSuppressed = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = exports.ssoSignedOutKey = void 0;
+exports.ssoAttemptedKey = exports.ssoNoSessionKey = exports.ssoDestKey = exports.ssoGuardKey = exports.ssoStateKey = exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = exports.establishIdpSessionAfterClaim = exports.generateSsoState = exports.consumeSsoReturn = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_IDP_APEX = exports.CENTRAL_AUTH_URL = exports.registrableApex = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = void 0;
+exports.packageInfo = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.runColdBoot = exports.allowSsoBounce = exports.silentRestoreSuppressed = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.getSsoCallbackBootstrapScript = exports.ssoNavigate = exports.ssoCallbackBootstrapKey = exports.ssoSignedOutKey = exports.ssoPriorSessionKey = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -274,6 +274,9 @@ Object.defineProperty(exports, "parseSsoReturnFragment", { enumerable: true, get
 Object.defineProperty(exports, "consumeSsoReturn", { enumerable: true, get: function () { return ssoReturn_1.consumeSsoReturn; } });
 var OxyServices_sso_1 = require("./mixins/OxyServices.sso");
 Object.defineProperty(exports, "generateSsoState", { enumerable: true, get: function () { return OxyServices_sso_1.generateSsoState; } });
+// Post-claim durable-session establish hop (web device-flow / QR sign-in).
+var ssoEstablish_1 = require("./utils/ssoEstablish");
+Object.defineProperty(exports, "establishIdpSessionAfterClaim", { enumerable: true, get: function () { return ssoEstablish_1.establishIdpSessionAfterClaim; } });
 // SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
 var ssoBounce_1 = require("./utils/ssoBounce");
 Object.defineProperty(exports, "SSO_CALLBACK_PATH", { enumerable: true, get: function () { return ssoBounce_1.SSO_CALLBACK_PATH; } });
@@ -295,6 +298,25 @@ Object.defineProperty(exports, "silentRestoreSuppressed", { enumerable: true, ge
 Object.defineProperty(exports, "allowSsoBounce", { enumerable: true, get: function () { return ssoBounce_1.allowSsoBounce; } });
 var coldBoot_1 = require("./utils/coldBoot");
 Object.defineProperty(exports, "runColdBoot", { enumerable: true, get: function () { return coldBoot_1.runColdBoot; } });
+// ---------------------------------------------------------------------------
+// Session sync (device-scoped multi-account session client)
+// ---------------------------------------------------------------------------
+var SessionClient_1 = require("./session/SessionClient");
+Object.defineProperty(exports, "SessionClient", { enumerable: true, get: function () { return SessionClient_1.SessionClient; } });
+// 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`.
+var sessionClientHost_1 = require("./session/sessionClientHost");
+Object.defineProperty(exports, "createSessionClientHost", { enumerable: true, get: function () { return sessionClientHost_1.createSessionClientHost; } });
+var createSessionClient_1 = require("./session/createSessionClient");
+Object.defineProperty(exports, "createSessionClient", { enumerable: true, get: function () { return createSessionClient_1.createSessionClient; } });
+var projectSessionState_1 = require("./session/projectSessionState");
+Object.defineProperty(exports, "deviceStateToClientSessions", { enumerable: true, get: function () { return projectSessionState_1.deviceStateToClientSessions; } });
+Object.defineProperty(exports, "activeSessionIdOf", { enumerable: true, get: function () { return projectSessionState_1.activeSessionIdOf; } });
+Object.defineProperty(exports, "activeUserOf", { enumerable: true, get: function () { return projectSessionState_1.activeUserOf; } });
+Object.defineProperty(exports, "accountIdsOf", { enumerable: true, get: function () { return projectSessionState_1.accountIdsOf; } });
 // 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/cjs/mixins/OxyServices.sso.js

@@ -168,5 +168,41 @@ 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/cjs/mixins/OxyServices.user.js

@@ -633,6 +633,30 @@ 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 = (0, apiUtils_1.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 notifications
          */

package/dist/cjs/server/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifySecret = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
+exports.SSO_CALLBACK_PATH = exports.registrableApex = exports.verifySecret = exports.createOxyCors = exports.UPSTREAM_HEADERS_TIMEOUT_MS = exports.MAX_URL_LENGTH = exports.MAX_REDIRECTS = exports.DEFAULT_USER_AGENT = exports.BLOCKED_HOSTNAMES = exports.ALLOWED_PROTOCOLS = exports.ALLOWED_PORTS = exports.UpstreamError = exports.SsrfRejection = exports.safeFetch = exports.isBlockedIp = exports.assertSafePublicUrl = exports.createOxyRateLimit = exports.requireOxyAuth = exports.isOxyAuthenticated = exports.getRequiredOxyUserId = exports.getOxyUserId = exports.createOxyAuthMiddleware = exports.createOptionalOxyAuth = void 0;
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "createOptionalOxyAuth", { enumerable: true, get: function () { return auth_1.createOptionalOxyAuth; } });
 Object.defineProperty(exports, "createOxyAuthMiddleware", { enumerable: true, get: function () { return auth_1.createOxyAuthMiddleware; } });
@@ -46,3 +46,15 @@ Object.defineProperty(exports, "createOxyCors", { enumerable: true, get: functio
 // Constant-time secret comparison.
 var verifySecret_1 = require("./verifySecret");
 Object.defineProperty(exports, "verifySecret", { enumerable: true, get: function () { return verifySecret_1.verifySecret; } });
+// 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.
+var fapiAutoDetect_1 = require("../utils/fapiAutoDetect");
+Object.defineProperty(exports, "registrableApex", { enumerable: true, get: function () { return fapiAutoDetect_1.registrableApex; } });
+// 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.
+var ssoBounce_1 = require("../utils/ssoBounce");
+Object.defineProperty(exports, "SSO_CALLBACK_PATH", { enumerable: true, get: function () { return ssoBounce_1.SSO_CALLBACK_PATH; } });

package/dist/cjs/session/SessionClient.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionClient = void 0;
+const contracts_1 = require("@oxyhq/contracts");
+const loggerUtils_1 = require("../utils/loggerUtils");
+const socketLoader_1 = require("./socketLoader");
+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) {
+                loggerUtils_1.logger.error('[SessionClient] subscriber threw', error);
+            }
+        }
+    }
+    /** Validate + last-writer-wins by revision. Returns true if applied. */
+    applyState(raw) {
+        const next = (0, contracts_1.safeParseContract)(contracts_1.deviceSessionStateSchema, raw);
+        if (!next) {
+            loggerUtils_1.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) => {
+                loggerUtils_1.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 = (0, contracts_1.safeParseContract)(contracts_1.deviceSessionSyncSchema, raw);
+        if (!sync) {
+            loggerUtils_1.logger.warn('[SessionClient] discarded invalid session sync');
+            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?.data);
+    }
+    async switchAccount(accountId) {
+        const res = await this.host.makeRequest('POST', '/session/device/switch', { accountId }, { cache: false });
+        this.applySync(res?.data);
+    }
+    async signOut(target) {
+        const res = await this.host.makeRequest('POST', '/session/device/signout', target, { cache: false });
+        this.applySync(res?.data);
+    }
+    async addCurrentAccount() {
+        const res = await this.host.makeRequest('POST', '/session/device/add', undefined, { cache: false });
+        this.applySync(res?.data);
+    }
+    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 (0, socketLoader_1.getSocketIO)();
+        if (!io) {
+            loggerUtils_1.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) => {
+                        loggerUtils_1.logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
+                    });
+                }
+            }
+        });
+        this.socket = socket;
+    }
+}
+exports.SessionClient = SessionClient;