@oxyhq/core 5.2.1 → 5.4.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/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,56 @@ 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 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 = (0, apiUtils_1.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/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,152 @@
+"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) {
+            const parsed = contracts_1.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) : [];
+            loggerUtils_1.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 (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;

package/dist/cjs/session/createSessionClient.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionClient = createSessionClient;
+const SessionClient_1 = require("./SessionClient");
+const sessionClientHost_1 = require("./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.
+ */
+function createSessionClient(oxyServices, transport) {
+    const host = (0, sessionClientHost_1.createSessionClientHost)(oxyServices);
+    const client = new SessionClient_1.SessionClient(host, { transport });
+    return { client, host };
+}

package/dist/cjs/session/projectSessionState.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceStateToClientSessions = deviceStateToClientSessions;
+exports.activeSessionIdOf = activeSessionIdOf;
+exports.activeUserOf = activeUserOf;
+exports.accountIdsOf = accountIdsOf;
+/**
+ * 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).
+ */
+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.
+ */
+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`.
+ */
+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.
+ */
+function accountIdsOf(state) {
+    if (state === null) {
+        return [];
+    }
+    return state.accounts.map((account) => account.accountId);
+}

package/dist/cjs/session/sessionClientHost.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionClientHost = createSessionClientHost;
+/**
+ * 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).
+ */
+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/cjs/session/socketLoader.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSocketIO = getSocketIO;
+const loggerUtils_1 = require("../utils/loggerUtils");
+let cachedFactory = null;
+let loadAttempted = false;
+async function getSocketIO() {
+    if (cachedFactory)
+        return cachedFactory;
+    if (loadAttempted)
+        return null;
+    loadAttempted = true;
+    try {
+        const mod = (await Promise.resolve().then(() => __importStar(require('socket.io-client'))));
+        cachedFactory = mod.io ?? mod.default ?? null;
+        return cachedFactory;
+    }
+    catch (error) {
+        loggerUtils_1.logger.warn('[SessionClient] socket.io-client import failed; realtime session sync disabled', { component: 'SessionClient' }, error);
+        return null;
+    }
+}