@oxyhq/core 2.2.0 → 2.2.2

package/dist/cjs/index.js

@@ -20,7 +20,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = 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.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.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = 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 = void 0;
-exports.packageInfo = exports.runColdBoot = exports.generateSsoState = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_AUTH_URL = 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 = void 0;
+exports.packageInfo = exports.runColdBoot = exports.guardActive = exports.isCentralIdPOrigin = exports.buildSsoBounceUrl = exports.ssoNavigate = 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.MULTIPART_TLDS = 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 = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -230,14 +230,30 @@ Object.defineProperty(exports, "getAccountColor", { enumerable: true, get: funct
 // ---------------------------------------------------------------------------
 var fapiAutoDetect_1 = require("./utils/fapiAutoDetect");
 Object.defineProperty(exports, "autoDetectAuthWebUrl", { enumerable: true, get: function () { return fapiAutoDetect_1.autoDetectAuthWebUrl; } });
+Object.defineProperty(exports, "registrableApex", { enumerable: true, get: function () { return fapiAutoDetect_1.registrableApex; } });
+Object.defineProperty(exports, "MULTIPART_TLDS", { enumerable: true, get: function () { return fapiAutoDetect_1.MULTIPART_TLDS; } });
 // Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
 var authWebUrl_1 = require("./utils/authWebUrl");
 Object.defineProperty(exports, "CENTRAL_AUTH_URL", { enumerable: true, get: function () { return authWebUrl_1.CENTRAL_AUTH_URL; } });
+Object.defineProperty(exports, "CENTRAL_IDP_APEX", { enumerable: true, get: function () { return authWebUrl_1.CENTRAL_IDP_APEX; } });
 Object.defineProperty(exports, "resolveCentralAuthUrl", { enumerable: true, get: function () { return authWebUrl_1.resolveCentralAuthUrl; } });
 var ssoReturn_1 = require("./utils/ssoReturn");
 Object.defineProperty(exports, "parseSsoReturnFragment", { enumerable: true, get: function () { return ssoReturn_1.parseSsoReturnFragment; } });
+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; } });
+// 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; } });
+Object.defineProperty(exports, "SSO_GUARD_TTL_MS", { enumerable: true, get: function () { return ssoBounce_1.SSO_GUARD_TTL_MS; } });
+Object.defineProperty(exports, "ssoStateKey", { enumerable: true, get: function () { return ssoBounce_1.ssoStateKey; } });
+Object.defineProperty(exports, "ssoGuardKey", { enumerable: true, get: function () { return ssoBounce_1.ssoGuardKey; } });
+Object.defineProperty(exports, "ssoDestKey", { enumerable: true, get: function () { return ssoBounce_1.ssoDestKey; } });
+Object.defineProperty(exports, "ssoNoSessionKey", { enumerable: true, get: function () { return ssoBounce_1.ssoNoSessionKey; } });
+Object.defineProperty(exports, "ssoNavigate", { enumerable: true, get: function () { return ssoBounce_1.ssoNavigate; } });
+Object.defineProperty(exports, "buildSsoBounceUrl", { enumerable: true, get: function () { return ssoBounce_1.buildSsoBounceUrl; } });
+Object.defineProperty(exports, "isCentralIdPOrigin", { enumerable: true, get: function () { return ssoBounce_1.isCentralIdPOrigin; } });
+Object.defineProperty(exports, "guardActive", { enumerable: true, get: function () { return ssoBounce_1.guardActive; } });
 var coldBoot_1 = require("./utils/coldBoot");
 Object.defineProperty(exports, "runColdBoot", { enumerable: true, get: function () { return coldBoot_1.runColdBoot; } });
 // ---------------------------------------------------------------------------

package/dist/cjs/mixins/OxyServices.auth.js

@@ -138,6 +138,7 @@ function OxyServicesAuthMixin(Base) {
                     expiresAt: 0,
                     secretBuf: providedSecretBuf,
                     pending: null,
+                    apiKey: key,
                 };
                 this._serviceTokenCache.set(cacheKey, entry);
             }
@@ -177,10 +178,54 @@ function OxyServicesAuthMixin(Base) {
                     expiresAt,
                     secretBuf,
                     pending: null,
+                    apiKey: key,
                 });
             }
             return response.token;
         }
+        /**
+         * Invalidate cached service token(s), forcing the next `getServiceToken()`
+         * call to mint a fresh token from `/auth/service-token`.
+         *
+         * `getServiceToken()` only refreshes on expiry (with a 60s clock-drift
+         * buffer), so a credential that is revoked or rotated mid-run — surfaced as
+         * a 401 on a downstream service request — cannot otherwise be recovered
+         * within the same process: the still-unexpired cached token keeps being
+         * returned. Call this after such a 401 to clear the stale entry; the very
+         * next `getServiceToken()` for that credential re-mints.
+         *
+         * Fully synchronous and deterministic: the call completes before it
+         * returns, so a `getServiceToken()` issued immediately afterwards is
+         * guaranteed to see the cleared cache and mint anew.
+         *
+         * @param apiKey - When provided, clears only the cache entry for that
+         *   specific apiKey. When omitted, clears the entry for the credential set
+         *   via `configureServiceAuth()`; if neither is available (no key to
+         *   target), clears the entire cache. Passing no argument is the common
+         *   case for hosts that configured a single service credential at startup.
+         *
+         * The cache Map is keyed by an asynchronously-computed `SHA-256(apiKey)`
+         * that cannot be reproduced synchronously, so a targeted clear scans the
+         * entries and removes the one whose stored raw `apiKey` matches — keeping
+         * this method synchronous. The fully-untargeted call (no argument and no
+         * configured key) clears every entry, which is safe because each credential
+         * pair is independently re-minted on its next request.
+         */
+        invalidateServiceToken(apiKey) {
+            const targetKey = apiKey ?? this._serviceApiKey;
+            // No specific credential to target — clear everything. The next
+            // getServiceToken() for any credential re-mints from scratch.
+            if (!targetKey) {
+                this._serviceTokenCache.clear();
+                return;
+            }
+            for (const [cacheKey, entry] of this._serviceTokenCache) {
+                if (entry.apiKey === targetKey) {
+                    this._serviceTokenCache.delete(cacheKey);
+                    return;
+                }
+            }
+        }
         /**
          * Make an authenticated request on behalf of a user using a service token.
          * Automatically obtains/refreshes the service token.

package/dist/cjs/mixins/OxyServices.popup.js

@@ -191,17 +191,25 @@ function OxyServicesPopupAuthMixin(Base) {
                 const timeout = options.timeout || this.constructor.SILENT_TIMEOUT;
                 const nonce = this.generateNonce();
                 const clientId = window.location.origin;
+                // Resolve the IdP origin for the iframe. An explicit per-apex override (the
+                // durable cross-domain reload path — see `SilentAuthOptions.authWebUrlOverride`)
+                // wins over the instance's configured central auth URL. The SAME origin is
+                // handed to `waitForIframeAuth` so the postMessage origin check matches the
+                // exact host the iframe was loaded from.
+                const authOrigin = options.authWebUrlOverride && options.authWebUrlOverride.length > 0
+                    ? options.authWebUrlOverride
+                    : this.resolveAuthUrl();
                 const iframe = document.createElement('iframe');
                 iframe.style.display = 'none';
                 iframe.style.position = 'absolute';
                 iframe.style.width = '0';
                 iframe.style.height = '0';
                 iframe.style.border = 'none';
-                const silentUrl = `${this.resolveAuthUrl()}/auth/silent?` + `client_id=${encodeURIComponent(clientId)}&` + `nonce=${nonce}`;
+                const silentUrl = `${authOrigin}/auth/silent?` + `client_id=${encodeURIComponent(clientId)}&` + `nonce=${nonce}`;
                 iframe.src = silentUrl;
                 document.body.appendChild(iframe);
                 try {
-                    const session = await this.waitForIframeAuth(iframe, timeout, clientId);
+                    const session = await this.waitForIframeAuth(iframe, timeout, authOrigin);
                     // Bail early on incomplete responses. The iframe contract requires
                     // both an access token and a session id; anything less is unusable.
                     // Returning `null` here (without installing the token) prevents a
@@ -389,8 +397,11 @@ function OxyServicesPopupAuthMixin(Base) {
                         resolve(null); // Silent failure - don't throw
                     }, timeout);
                     const messageHandler = (event) => {
-                        // Verify origin
-                        if (event.origin !== this.resolveAuthUrl()) {
+                        // Verify origin against the EXACT host the iframe was loaded from
+                        // (`expectedOrigin`). For the per-apex durable-restore path this is
+                        // `auth.<rp-apex>`, not the instance's central `resolveAuthUrl()` — so
+                        // we must honour the caller-supplied origin, never re-derive it here.
+                        if (event.origin !== expectedOrigin) {
                             return;
                         }
                         const { type, session } = event.data;

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

@@ -96,14 +96,24 @@ function OxyServicesUserMixin(Base) {
         }
         /**
          * Get profile recommendations, optionally filtering out specific user types.
+         *
+         * Public discovery read — works WITHOUT authentication. The SDK attaches the
+         * access token automatically when one is available (personalized via
+         * mutual-connection overlap), and falls back to popular public profiles when
+         * the caller is logged out. This deliberately does NOT use `withAuthRetry`,
+         * which would throw an authentication timeout for logged-out callers before
+         * the request is ever sent.
          */
         async getProfileRecommendations(options) {
-            const params = options?.excludeTypes?.length
-                ? { excludeTypes: options.excludeTypes.join(',') }
-                : undefined;
-            return this.withAuthRetry(async () => {
+            try {
+                const params = options?.excludeTypes?.length
+                    ? { excludeTypes: options.excludeTypes.join(',') }
+                    : undefined;
                 return await this.makeRequest('GET', '/profiles/recommendations', params, { cache: true });
-            }, 'getProfileRecommendations');
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
         }
         /**
          * Get profiles similar to a given user, based on co-follower overlap.

package/dist/cjs/utils/authWebUrl.js

@@ -18,13 +18,24 @@
  * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CENTRAL_AUTH_URL = void 0;
+exports.CENTRAL_AUTH_URL = exports.CENTRAL_IDP_APEX = void 0;
 exports.resolveCentralAuthUrl = resolveCentralAuthUrl;
+/**
+ * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
+ * Provider. The central IdP is reachable at `auth.${CENTRAL_IDP_APEX}` and the
+ * ID-token assertion issuer is always `https://auth.${CENTRAL_IDP_APEX}`
+ * regardless of which per-apex `auth.<rp>` host served a given request.
+ *
+ * Kept as a standalone constant so the IdP worker and the SDK derive the same
+ * literal from one source of truth (the worker imports it to brand assertions).
+ */
+exports.CENTRAL_IDP_APEX = 'oxy.so';
 /**
  * The canonical central Identity Provider origin for the Oxy ecosystem.
- * No trailing slash.
+ * No trailing slash. Derived from {@link CENTRAL_IDP_APEX} so the apex and the
+ * full origin never drift apart.
  */
-exports.CENTRAL_AUTH_URL = 'https://auth.oxy.so';
+exports.CENTRAL_AUTH_URL = `https://auth.${exports.CENTRAL_IDP_APEX}`;
 /**
  * Resolve the central IdP origin, honouring an explicit override.
  *

package/dist/cjs/utils/fapiAutoDetect.js

@@ -36,6 +36,8 @@
  * is required for end-to-end FedCM correctness — no per-RP config.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MULTIPART_TLDS = void 0;
+exports.registrableApex = registrableApex;
 exports.autoDetectAuthWebUrl = autoDetectAuthWebUrl;
 /**
  * Known multi-part public suffixes where the registrable domain is the LAST
@@ -49,7 +51,7 @@ exports.autoDetectAuthWebUrl = autoDetectAuthWebUrl;
  * before relying on this helper, otherwise auto-detection silently bails to
  * `undefined` and the consumer must pass `authWebUrl` explicitly.
  */
-const MULTIPART_TLDS = new Set([
+exports.MULTIPART_TLDS = new Set([
     'co.uk',
     'com.au',
     'co.jp',
@@ -61,6 +63,46 @@ const MULTIPART_TLDS = new Set([
     'co.kr',
     'com.sg',
 ]);
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname, guarding against
+ * multi-part public suffixes.
+ *
+ * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
+ * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
+ * and builds NO URL. It only answers "what is the registrable domain of this
+ * host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - hosts whose trailing two labels form a known multi-part public suffix
+ *     (e.g. `foo.co.uk`), where `labels.slice(-2)` would yield an
+ *     attacker-registrable suffix (`co.uk`) rather than a real registrable
+ *     domain. Such hosts MUST configure `authWebUrl` explicitly.
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+function registrableApex(hostname) {
+    if (!hostname)
+        return null;
+    const host = hostname.toLowerCase();
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(host))
+        return null;
+    // IPv6 literals are bracketed; any remaining ':' implies a port — neither
+    // yields a registrable apex.
+    if (host.startsWith('[') || host.includes(':'))
+        return null;
+    const labels = host.split('.');
+    if (labels.length < 2)
+        return null;
+    const lastTwo = labels.slice(-2).join('.');
+    if (exports.MULTIPART_TLDS.has(lastTwo))
+        return null;
+    return lastTwo;
+}
 function autoDetectAuthWebUrl(location = typeof window !== 'undefined' ? window.location : undefined) {
     if (!location)
         return undefined;
@@ -75,14 +117,13 @@ function autoDetectAuthWebUrl(location = typeof window !== 'undefined' ? window.
         return undefined;
     if (hostname.startsWith('['))
         return undefined;
+    // Already ON the IdP — keep everything same-origin instead of hopping to a
+    // sibling host.
     if (hostname.startsWith('auth.')) {
         return `${protocol}//${hostname}`;
     }
-    const labels = hostname.split('.');
-    if (labels.length < 2)
-        return undefined;
-    if (MULTIPART_TLDS.has(labels.slice(-2).join('.')))
+    const apex = registrableApex(hostname);
+    if (apex === null)
         return undefined;
-    const apex = labels.slice(-2).join('.');
     return `${protocol}//auth.${apex}`;
 }

package/dist/cjs/utils/ssoBounce.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Central cross-domain SSO bounce — per-origin sessionStorage keys, the bounce
+ * URL builder, and the small pure predicates shared by every consumer's
+ * cold-boot `sso-return` / `sso-bounce` steps and bfcache `pageshow`
+ * re-evaluation.
+ *
+ * This is the single source of truth for the SSO bounce wire/storage contract.
+ * `@oxyhq/auth` (`WebOxyProvider`) and `@oxyhq/services` (`OxyContext`) both
+ * consume these helpers so the two providers behave identically.
+ *
+ * TRUE central SSO (Google/Meta/Clerk style) works like this for a Relying
+ * Party (mention.earth, homiio.com, alia.onl, …) with no local session:
+ *
+ *   1. `sso-bounce` (terminal, once): a TOP-LEVEL navigation to
+ *      `auth.oxy.so/sso?prompt=none&client_id=<origin>&return_to=<origin>{@link SSO_CALLBACK_PATH}&state=<s>`.
+ *      Before navigating it records, in this origin's `sessionStorage`, the
+ *      CSRF `state` ({@link ssoStateKey}), a guard timestamp ({@link ssoGuardKey},
+ *      the loop breaker), and the real destination URL ({@link ssoDestKey}) to
+ *      restore after the callback.
+ *   2. The central IdP worker reads its first-party `fedcm_session`, mints a
+ *      session, stores it under an opaque single-use `code`, and 303-redirects
+ *      back to `<origin>{@link SSO_CALLBACK_PATH}#oxy_sso=ok&code=<code>&state=<s>`
+ *      (or `#oxy_sso=none` / `#oxy_sso=error`).
+ *   3. `sso-return` parses the fragment (`parseSsoReturnFragment`), validates
+ *      `state`, exchanges the `code` via `oxyServices.exchangeSsoCode`, commits
+ *      the session, then restores the original destination.
+ *
+ * Loop proof (logged-out): first load all steps skip → `sso-bounce` sets
+ * guard/state/dest and navigates; the IdP (no central session) returns
+ * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
+ * NO_SESSION flag ({@link ssoNoSessionKey}), and `sso-bounce` is then disabled.
+ * Exactly ONE bounce, no loop. An interrupted bounce (user hit back
+ * mid-redirect) self-heals once the {@link SSO_GUARD_TTL_MS} guard TTL lapses.
+ *
+ * All state lives in `sessionStorage` (per tab, cleared on tab close) and is
+ * keyed per-origin so two RPs hosted in the same browser never collide. The
+ * key strings and the 30s TTL are a wire/storage contract — they MUST match
+ * the values the IdP and every consumer expect and must not change lightly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSO_GUARD_TTL_MS = exports.SSO_CALLBACK_PATH = void 0;
+exports.ssoStateKey = ssoStateKey;
+exports.ssoGuardKey = ssoGuardKey;
+exports.ssoDestKey = ssoDestKey;
+exports.ssoNoSessionKey = ssoNoSessionKey;
+exports.ssoNavigate = ssoNavigate;
+exports.buildSsoBounceUrl = buildSsoBounceUrl;
+exports.isCentralIdPOrigin = isCentralIdPOrigin;
+exports.guardActive = guardActive;
+const authWebUrl_1 = require("./authWebUrl");
+/**
+ * The RP callback path the central IdP redirects back to after a bounce. The
+ * SSO result is delivered in the fragment of this URL; the `sso-return` step
+ * consumes it and then restores the user's real destination (stored under
+ * {@link ssoDestKey}), so the user never lingers on this internal path.
+ */
+exports.SSO_CALLBACK_PATH = '/__oxy/sso-callback';
+/**
+ * Self-healing TTL (ms) for the bounce guard. An in-flight bounce sets a
+ * timestamp guard; if the bounce is interrupted before the callback lands
+ * (e.g. the user navigates back mid-redirect), the guard would otherwise pin
+ * the RP signed-out forever. After this window the guard is treated as stale
+ * and a fresh single bounce is permitted. 30s comfortably exceeds a real
+ * redirect round-trip while keeping a crash short-lived.
+ */
+exports.SSO_GUARD_TTL_MS = 30000;
+const STATE_KEY_PREFIX = 'oxy_sso_state:';
+const GUARD_KEY_PREFIX = 'oxy_sso_guard:';
+const DEST_KEY_PREFIX = 'oxy_sso_dest:';
+const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
+/** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
+function ssoStateKey(origin) {
+    return `${STATE_KEY_PREFIX}${origin}`;
+}
+/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
+function ssoGuardKey(origin) {
+    return `${GUARD_KEY_PREFIX}${origin}`;
+}
+/** Per-origin destination key (the real URL to restore after the callback). */
+function ssoDestKey(origin) {
+    return `${DEST_KEY_PREFIX}${origin}`;
+}
+/**
+ * Per-origin "the central IdP has no session for me" key. Set after a
+ * `none`/`error` return (or a failed/forged exchange) so `sso-bounce` does not
+ * fire again this tab — the definitive loop breaker.
+ */
+function ssoNoSessionKey(origin) {
+    return `${NO_SESSION_KEY_PREFIX}${origin}`;
+}
+/**
+ * Perform the terminal top-level SSO bounce navigation.
+ *
+ * A thin wrapper over `window.location.assign(url)` so the single navigation
+ * seam lives in one place (and stays mockable in tests, where jsdom's
+ * `Location.assign` is a non-configurable native method). In production this is
+ * exactly `window.location.assign` — the document is torn down and replaced by
+ * the central IdP page. Off-browser (SSR / native) it is a no-op: native never
+ * bounces.
+ */
+function ssoNavigate(url) {
+    if (typeof window === 'undefined' || typeof window.location === 'undefined') {
+        return;
+    }
+    window.location.assign(url);
+}
+/**
+ * Build the central IdP `/sso` bounce URL for an RP.
+ *
+ * Pure (no DOM access) so it is unit-testable and shared by every consumer's
+ * terminal `sso-bounce` step. The IdP reads `client_id` (the RP origin) and
+ * `return_to` to mint an origin-bound opaque code and 303-redirect back.
+ *
+ * The IdP base is resolved via {@link resolveCentralAuthUrl} so an explicit
+ * `authWebUrl` override (e.g. a staging IdP) drives the SSO bounce exactly the
+ * way it drives FedCM. When omitted, the central default {@link CENTRAL_AUTH_URL}
+ * is used.
+ *
+ * @param origin - The RP origin (`window.location.origin`).
+ * @param state - The CSRF state minted for this bounce.
+ * @param authWebUrl - Optional explicit IdP base URL override. Falls back to
+ *   the central default when `undefined`/empty.
+ * @returns The absolute `<idp-origin>/sso?...` URL string.
+ */
+function buildSsoBounceUrl(origin, state, authWebUrl) {
+    const url = new URL('/sso', (0, authWebUrl_1.resolveCentralAuthUrl)(authWebUrl));
+    url.searchParams.set('prompt', 'none');
+    url.searchParams.set('client_id', origin);
+    url.searchParams.set('return_to', origin + exports.SSO_CALLBACK_PATH);
+    url.searchParams.set('state', state);
+    return url.toString();
+}
+/**
+ * Whether `origin` IS the central IdP origin. The RP must NEVER bounce while
+ * sitting on `auth.oxy.so` itself — doing so would loop the IdP against itself.
+ *
+ * Both sides are normalised via `new URL(...).origin` so a trailing-slash or
+ * path difference never defeats the guard. Returns `false` on any parse
+ * failure (an unparseable candidate is, by definition, not the central IdP).
+ */
+function isCentralIdPOrigin(origin) {
+    let centralOrigin;
+    try {
+        centralOrigin = new URL(authWebUrl_1.CENTRAL_AUTH_URL).origin;
+    }
+    catch {
+        return false;
+    }
+    let candidateOrigin;
+    try {
+        candidateOrigin = new URL(origin).origin;
+    }
+    catch {
+        return false;
+    }
+    return candidateOrigin === centralOrigin;
+}
+/**
+ * Read the bounce guard and decide whether it is still ACTIVE.
+ *
+ * Active means: a guard value is present AND it parses to a finite timestamp
+ * AND less than {@link SSO_GUARD_TTL_MS} has elapsed since it was set. An active
+ * guard disables `sso-bounce` (a bounce is already in flight this tab). A
+ * missing, malformed, or expired guard is NOT active, so a fresh bounce may
+ * proceed (this is the 30s self-heal for an interrupted bounce).
+ *
+ * Defensive: a `getItem` that throws (e.g. a locked/disabled storage) is
+ * treated as "not active" so the guard never wedges the flow.
+ *
+ * @param storage - The session storage to read (injected for testability).
+ * @param origin - The page origin whose guard to evaluate.
+ * @param now - Current epoch ms (injected for deterministic tests). Defaults to
+ *   `Date.now()`.
+ */
+function guardActive(storage, origin, now = Date.now()) {
+    let raw;
+    try {
+        raw = storage.getItem(ssoGuardKey(origin));
+    }
+    catch {
+        return false;
+    }
+    if (raw === null || raw.length === 0) {
+        return false;
+    }
+    const ts = Number(raw);
+    if (!Number.isFinite(ts)) {
+        return false;
+    }
+    return now - ts < exports.SSO_GUARD_TTL_MS;
+}

package/dist/cjs/utils/ssoReturn.js

@@ -23,6 +23,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseSsoReturnFragment = parseSsoReturnFragment;
+exports.consumeSsoReturn = consumeSsoReturn;
+const ssoBounce_1 = require("./ssoBounce");
 const VALID_KINDS = new Set(['ok', 'none', 'error']);
 /**
  * Parse an SSO return fragment.
@@ -70,3 +72,112 @@ function parseSsoReturnFragment(hash) {
     }
     return result;
 }
+/**
+ * Consume an SSO return: the commit-free, security-critical kernel of the
+ * cross-domain SSO `sso-return` cold-boot step.
+ *
+ * This performs the CSRF/fragment/exchange/dest-restore/loop-breaker sequence
+ * and RETURNS the exchanged session (or `null`). It deliberately does NOT
+ * commit any UI/auth state — each provider commits its own way AROUND this
+ * (e.g. `@oxyhq/services` `OxyContext` calls its `handleWebSSOSession`,
+ * `@oxyhq/auth` `WebOxyProvider` updates its React state). Hoisting the kernel
+ * here keeps the two providers byte-for-byte identical on the parts that matter
+ * for security (state validation, fragment stripping order, loop prevention).
+ *
+ * Security/loop invariants (preserved exactly from both former copies):
+ *   - The fragment is stripped via `history.replaceState` FIRST — before the
+ *     exchange — so the opaque code never lingers in the URL, browser history,
+ *     or a `Referer` header even if a later step throws.
+ *   - `state` must match (CSRF). A mismatch or a missing code sets the
+ *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
+ *   - `none`/`error` outcomes set the NO_SESSION flag (the load2 half of the
+ *     loop proof).
+ *   - A throwing exchange is caught, reported via `onExchangeError`, and
+ *     treated exactly like "no session" (never loops, never rethrows).
+ *   - After a successful exchange landing on {@link SSO_CALLBACK_PATH}, the real
+ *     destination is restored from the DEST key — same-origin only (an
+ *     attacker-planted cross-origin or relative-evil dest is rejected). The
+ *     DEST key is removed unconditionally.
+ *
+ * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
+ *
+ * @param oxy - The exchange surface (`oxyServices.exchangeSsoCode`).
+ * @param deps - Injectable web seams; see {@link ConsumeSsoReturnDeps}.
+ * @returns The exchanged session on success, otherwise `null`.
+ */
+async function consumeSsoReturn(oxy, deps = {}) {
+    const isWeb = deps.isWeb ??
+        (() => typeof window !== 'undefined' &&
+            typeof window.sessionStorage !== 'undefined');
+    if (!isWeb()) {
+        return null;
+    }
+    const storage = deps.storage ?? window.sessionStorage;
+    const location = deps.location ?? window.location;
+    const history = deps.history ?? window.history;
+    const onExchangeError = deps.onExchangeError;
+    const ret = parseSsoReturnFragment(location.hash);
+    if (!ret) {
+        // Not an oxy_sso fragment — nothing to do (do NOT touch any flags).
+        return null;
+    }
+    const origin = location.origin;
+    const expectedState = storage.getItem((0, ssoBounce_1.ssoStateKey)(origin));
+    const stateOk = !!ret.state && !!expectedState && ret.state === expectedState;
+    // Strip the fragment FIRST so the opaque code never lingers in the address
+    // bar, history, or a `Referer` — even if a later step throws.
+    history.replaceState(null, '', location.pathname + location.search);
+    storage.removeItem((0, ssoBounce_1.ssoStateKey)(origin));
+    // The in-flight bounce is now resolved — drop its guard so a later cold boot
+    // (e.g. after sign-out) can bounce again.
+    storage.removeItem((0, ssoBounce_1.ssoGuardKey)(origin));
+    const markNoSession = () => {
+        storage.setItem((0, ssoBounce_1.ssoNoSessionKey)(origin), '1');
+    };
+    if (ret.kind === 'none' || ret.kind === 'error') {
+        // The central IdP had no session (or the bounce failed). Record it so we do
+        // not bounce again this tab — the definitive loop breaker.
+        markNoSession();
+        return null;
+    }
+    if (!stateOk || !ret.code) {
+        // Forged / replayed / stale fragment, or a malformed ok with no code. Treat
+        // exactly like "no session": never exchange, never loop.
+        markNoSession();
+        return null;
+    }
+    let session;
+    try {
+        session = await oxy.exchangeSsoCode(ret.code);
+    }
+    catch (error) {
+        onExchangeError?.(error);
+        markNoSession();
+        return null;
+    }
+    if (!session?.sessionId) {
+        markNoSession();
+        return null;
+    }
+    // If we landed on the internal callback path, restore the user's real
+    // destination (captured at bounce time). Same-origin only — never honour a
+    // cross-origin destination that could have been planted to redirect the
+    // freshly signed-in user. `new URL(dest, origin)` tolerates relative dests
+    // and is still re-checked against the page origin.
+    if (location.pathname === ssoBounce_1.SSO_CALLBACK_PATH) {
+        const dest = storage.getItem((0, ssoBounce_1.ssoDestKey)(origin));
+        if (dest) {
+            try {
+                const destUrl = new URL(dest, origin);
+                if (destUrl.origin === origin) {
+                    history.replaceState(null, '', destUrl.pathname + destUrl.search + destUrl.hash);
+                }
+            }
+            catch {
+                // Malformed stored destination — leave the URL on the callback path.
+            }
+        }
+    }
+    storage.removeItem((0, ssoBounce_1.ssoDestKey)(origin));
+    return session;
+}