@oxyhq/core 5.4.3 → 6.0.0

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

@@ -1,92 +0,0 @@
-import { OxyAuthenticationError } from '../OxyServices.errors.js';
-import { buildSsoBounceUrl, ssoAttemptedKey, ssoDestKey, ssoGuardKey, ssoStateKey, } from '../utils/ssoBounce.js';
-/**
- * Redirect-based authentication without bearer tokens in URLs.
- *
- * The redirect fallback now uses the same central SSO code-return contract as
- * cold boot: the RP stores CSRF/destination state in sessionStorage, navigates
- * to the central IdP, receives only an opaque one-time code in the URL fragment,
- * and the provider's `sso-return` step exchanges that code for the real session.
- */
-export function OxyServicesRedirectAuthMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * Start a full-page redirect through the central SSO flow.
-         *
-         * No access token, refresh token, or session id is ever put in the URL or
-         * localStorage. The caller's provider must run `consumeSsoReturn` on startup
-         * to complete the code exchange and commit the session.
-         */
-        signInWithRedirect(options = {}) {
-            if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') {
-                throw new OxyAuthenticationError('Redirect authentication requires browser sessionStorage');
-            }
-            const origin = window.location.origin;
-            const state = this.generateState();
-            const destination = options.preserveUrl === false
-                ? (options.redirectUri || origin)
-                : (options.redirectUri || window.location.href);
-            window.sessionStorage.setItem(ssoStateKey(origin), state);
-            window.sessionStorage.setItem(ssoGuardKey(origin), String(Date.now()));
-            window.sessionStorage.setItem(ssoDestKey(origin), destination);
-            window.sessionStorage.setItem(ssoAttemptedKey(origin), '1');
-            window.location.assign(buildSsoBounceUrl(origin, state, this.config.authWebUrl));
-        }
-        signUpWithRedirect(options = {}) {
-            this.signInWithRedirect({ ...options, mode: 'signup' });
-        }
-        /**
-         * Legacy token-query callbacks are intentionally rejected. Modern providers
-         * complete redirect auth through `consumeSsoReturn`, which accepts only
-         * `#oxy_sso=ok&code=...`.
-         */
-        handleAuthCallback() {
-            if (typeof window === 'undefined') {
-                return null;
-            }
-            const url = new URL(window.location.href);
-            if (url.searchParams.has('access_token') || url.searchParams.has('session_id')) {
-                this.cleanAuthCallbackUrl(url);
-                throw new OxyAuthenticationError('Legacy access-token redirect callbacks are no longer accepted.');
-            }
-            return null;
-        }
-        restoreSession() {
-            return false;
-        }
-        clearStoredSession() {
-            this.httpService.clearTokens();
-        }
-        getStoredSessionId() {
-            return null;
-        }
-        generateState() {
-            if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-                return crypto.randomUUID();
-            }
-            if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-                const bytes = new Uint8Array(16);
-                crypto.getRandomValues(bytes);
-                return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-            }
-            throw new Error('No secure random source available for state generation');
-        }
-        generateNonce() {
-            return this.generateState();
-        }
-        cleanAuthCallbackUrl(url) {
-            url.searchParams.delete('access_token');
-            url.searchParams.delete('session_id');
-            url.searchParams.delete('expires_at');
-            url.searchParams.delete('state');
-            url.searchParams.delete('nonce');
-            url.searchParams.delete('error');
-            url.searchParams.delete('error_description');
-            window.history.replaceState({}, '', url.toString());
-        }
-    };
-}
-export { OxyServicesRedirectAuthMixin as RedirectAuthMixin };

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

@@ -1,202 +0,0 @@
-import { createDebugLogger } from "../shared/utils/debugUtils.js";
-const debug = createDebugLogger("SilentAuth");
-/**
- * Cross-domain silent browser auth helpers.
- *
- * The clean session model supports FedCM, tokenless redirect SSO, and silent
- * iframe SSO. Bearer-token callback URLs are not part of this surface.
- */
-export function OxyServicesSilentAuthMixin(Base) {
-    var _a;
-    return _a = class extends Base {
-            constructor(...args) {
-                super(...args);
-            }
-            /** Resolve auth URL from config or static default (method, not getter — getters break in TS mixins) */
-            resolveAuthUrl() {
-                return (this.config.authWebUrl || this.constructor.DEFAULT_AUTH_URL);
-            }
-            /**
-             * Silent sign-in using hidden iframe
-             *
-             * Attempts to automatically re-authenticate the user without any UI.
-             * This is what enables seamless SSO across all Oxy domains.
-             *
-             * How it works:
-             * 1. Creates hidden iframe pointing to auth.oxy.so/silent-auth
-             * 2. If user has valid session at auth.oxy.so, it exchanges an opaque SSO code
-             * 3. If not, iframe responds with null (no error thrown)
-             *
-             * This should be called on app startup to check for existing sessions.
-             *
-             * @param options - Silent auth options
-             * @returns Session if user is signed in, null otherwise
-             *
-             * @example
-             * ```typescript
-             * useEffect(() => {
-             *   const checkAuth = async () => {
-             *     const session = await oxyServices.silentSignIn();
-             *     if (session) {
-             *       setUser(session.user);
-             *     }
-             *   };
-             *   checkAuth();
-             * }, []);
-             * ```
-             */
-            async silentSignIn(options = {}) {
-                if (typeof window === "undefined") {
-                    return null;
-                }
-                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 = `${authOrigin}/auth/silent?` +
-                    `client_id=${encodeURIComponent(clientId)}&` +
-                    `nonce=${nonce}`;
-                iframe.src = silentUrl;
-                document.body.appendChild(iframe);
-                try {
-                    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
-                    // stale credential from being committed to HttpService when the
-                    // user is actually signed out — that pattern caused a `getCurrentUser`
-                    // -> 401 -> token-clear loop in consumer apps because callers gated
-                    // on `session?.user` and never installed the user via
-                    // `handleAuthSuccess`, while HttpService quietly held the token.
-                    const accessToken = session
-                        ? session.accessToken
-                        : undefined;
-                    if (!session || !accessToken || !session.sessionId) {
-                        return null;
-                    }
-                    // Snapshot the previous token so we can roll back if the user
-                    // lookup below fails — this avoids leaving a half-committed session
-                    // (token installed, user missing) which would let the next
-                    // authenticated request 401 with no way to recover.
-                    const previousAccessToken = this.httpService.getAccessToken();
-                    this.httpService.setTokens(accessToken);
-                    // The iframe typically returns `{ sessionId, accessToken }` without
-                    // user data. Fetch the user explicitly so callers receive a
-                    // fully-formed session and never need a second `/users/me` round
-                    // trip. If this fails the session is unusable — revert the token
-                    // and return null so the caller treats this exactly like a
-                    // missing-session response.
-                    if (!session.user) {
-                        try {
-                            const userData = await this.makeRequest("GET", `/session/user/${session.sessionId}`, undefined, { cache: false, retry: false });
-                            if (!userData) {
-                                throw new Error("Empty user response");
-                            }
-                            session.user = userData;
-                        }
-                        catch (userError) {
-                            debug.warn("silentSignIn: failed to fetch user data, rolling back token", userError);
-                            if (previousAccessToken) {
-                                this.httpService.setTokens(previousAccessToken);
-                            }
-                            else {
-                                this.httpService.clearTokens();
-                            }
-                            return null;
-                        }
-                    }
-                    return session;
-                }
-                catch (error) {
-                    return null;
-                }
-                finally {
-                    document.body.removeChild(iframe);
-                }
-            }
-            /**
-             * Wait for authentication response from iframe
-             *
-             * @private
-             */
-            async waitForIframeAuth(iframe, timeout, expectedOrigin) {
-                return new Promise((resolve) => {
-                    const timeoutId = setTimeout(() => {
-                        cleanup();
-                        resolve(null); // Silent failure - don't throw
-                    }, timeout);
-                    const messageHandler = (event) => {
-                        // 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;
-                        if (type !== "oxy_silent_auth") {
-                            return;
-                        }
-                        cleanup();
-                        resolve(session || null);
-                    };
-                    // Fail-fast on a load failure. When the per-apex `/auth/silent` host is
-                    // unreachable, blocked by CSP `frame-ancestors`/`X-Frame-Options`, or the
-                    // network drops, the iframe never posts a message — without this handler
-                    // the silent restore would block for the FULL `timeout` (dead latency in
-                    // the cold-boot critical path). `onerror`/`onabort` fire on a failed load,
-                    // so resolve `null` immediately and let the next cold-boot step run. The
-                    // success path posts a message and is handled above; these only catch the
-                    // no-message failure modes.
-                    const failFast = () => {
-                        cleanup();
-                        resolve(null);
-                    };
-                    iframe.onerror = failFast;
-                    iframe.onabort = failFast;
-                    const cleanup = () => {
-                        clearTimeout(timeoutId);
-                        iframe.onerror = null;
-                        iframe.onabort = null;
-                        window.removeEventListener("message", messageHandler);
-                    };
-                    window.addEventListener("message", messageHandler);
-                });
-            }
-            /**
-             * Generate nonce for replay attack prevention
-             *
-             * @private
-             */
-            generateNonce() {
-                if (typeof crypto !== "undefined" && crypto.randomUUID) {
-                    return crypto.randomUUID();
-                }
-                if (typeof crypto !== "undefined" && crypto.getRandomValues) {
-                    const bytes = new Uint8Array(16);
-                    crypto.getRandomValues(bytes);
-                    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-                }
-                throw new Error("No secure random source available for nonce generation");
-            }
-        },
-        _a.DEFAULT_AUTH_URL = "https://auth.oxy.so",
-        _a.SILENT_TIMEOUT = 5000 // 5 seconds
-    ,
-        _a;
-}
-// Export the mixin function as both named and default
-export { OxyServicesSilentAuthMixin as SilentAuthMixin };

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

@@ -1,204 +0,0 @@
-/**
- * Central Cross-Domain SSO (opaque-code) Mixin
- *
- * Implements the Relying-Party half of TRUE central cross-domain SSO
- * (Google/Meta/Clerk style). The central IdP at `auth.oxy.so` owns the session;
- * an RP bounces a top-level redirect (prompt=none) to `auth.oxy.so/sso`, which
- * returns an OPAQUE single-use code in the redirect fragment. The RP then
- * exchanges that code here for the real session.
- *
- * Security properties:
- *   - NO token/JWT ever travels in a URL — only the opaque code does. The real
- *     `accessToken` is delivered exclusively in this exchange response body.
- *   - The exchange is a CORS POST with NO credentials/cookies — the opaque code
- *     is the only bearer of authority, and the central store burns it atomically
- *     (single-use). Sending no cookies keeps the request a clean, ambient-
- *     authority-free bearer exchange that the central `POST /sso/exchange`
- *     endpoint validates by `Origin` against the code's bound `clientOrigin`.
- *   - The code is minted server-side bound to the RP origin and expires in
- *     seconds, so a leaked code is useless cross-origin and short-lived.
- *
- * On success the mixin plants the returned access token via
- * `httpService.setTokens(...)` — mirroring `exchangeIdTokenForSession` /
- * `verifyChallenge` — so callers do NOT need to plant tokens manually.
- */
-import { createDebugLogger } from '../shared/utils/debugUtils.js';
-import { ssoStateKey } from '../utils/ssoBounce.js';
-const debug = createDebugLogger('SSO');
-/**
- * Generate a cryptographically secure state value for the SSO bounce.
- *
- * Exposed as a module-level helper (in addition to the instance method below)
- * so consumers that do not yet hold an `OxyServices` instance can still mint a
- * bounce state. Uses `crypto.randomUUID` with a `getRandomValues` fallback.
- */
-export function generateSsoState() {
-    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-        return crypto.randomUUID();
-    }
-    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-        const bytes = new Uint8Array(16);
-        crypto.getRandomValues(bytes);
-        return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-    }
-    throw new Error('No secure random source available for SSO state generation');
-}
-/**
- * Read the SSO bounce state stored for the current browser origin, if any.
- *
- * Returns `null` outside a browser (no `window`/`sessionStorage`) or when no
- * state is stored — in which case the caller cannot (and must not) enforce a
- * state match, e.g. native flows or pre-hydration callbacks that already
- * validated the state before this exchange.
- */
-function getStoredSsoStateForCurrentOrigin() {
-    if (typeof window === 'undefined' || !window.location || !window.sessionStorage) {
-        return null;
-    }
-    try {
-        return window.sessionStorage.getItem(ssoStateKey(window.location.origin));
-    }
-    catch {
-        return null;
-    }
-}
-export function OxyServicesSsoMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * Generate cryptographically secure state for the SSO bounce (CSRF
-         * protection). Delegates to the module-level {@link generateSsoState}
-         * helper, which uses `crypto.randomUUID` when available and falls back to
-         * `crypto.getRandomValues`.
-         */
-        generateSsoState() {
-            return generateSsoState();
-        }
-        /**
-         * Exchange an opaque single-use SSO code for the real Oxy session.
-         *
-         * POSTs `{ code }` to `${getSessionBaseUrl()}/sso/exchange` as a CORS
-         * request with NO credentials/cookies. On success the returned access token
-         * is planted via `httpService.setTokens(...)` (matching
-         * `exchangeIdTokenForSession` / `verifyChallenge`), so callers do not need
-         * to plant tokens manually.
-         *
-         * @param code - The opaque single-use code delivered in the SSO return
-         *   fragment (see {@link parseSsoReturnFragment}). The central store burns
-         *   it atomically on exchange.
-         * @param state - The state value returned alongside the code. In browsers,
-         *   when an SSO bounce state is still stored for the current origin, this
-         *   must match before any token-committing exchange is attempted.
-         * @returns The resolved {@link SessionLoginResponse}.
-         */
-        async exchangeSsoCode(code, state) {
-            if (typeof code !== 'string' || code.length === 0) {
-                throw this.handleError(new Error('exchangeSsoCode requires a non-empty code'));
-            }
-            const expectedState = getStoredSsoStateForCurrentOrigin();
-            if (expectedState !== null && (typeof state !== 'string' || state.length === 0 || state !== expectedState)) {
-                throw this.handleError(new Error('SSO exchange state mismatch'));
-            }
-            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/sso/exchange`;
-            debug.log('Exchanging SSO code for session...');
-            let response;
-            try {
-                response = await fetch(url, {
-                    method: 'POST',
-                    // No cookies: the opaque code is the sole bearer of authority and the
-                    // server validates by Origin against the code's bound clientOrigin.
-                    credentials: 'omit',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        Accept: 'application/json',
-                    },
-                    body: JSON.stringify({ code }),
-                });
-            }
-            catch (error) {
-                debug.error('SSO exchange request failed:', error instanceof Error ? error.message : String(error));
-                throw this.handleError(error);
-            }
-            if (!response.ok) {
-                throw this.handleError(new Error(`SSO exchange failed with HTTP ${response.status}`));
-            }
-            let payload;
-            try {
-                payload = (await response.json());
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-            if (!payload || typeof payload.accessToken !== 'string' || payload.accessToken.length === 0) {
-                throw this.handleError(new Error('SSO exchange returned no access token'));
-            }
-            if (typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
-                throw this.handleError(new Error('SSO exchange returned no sessionId'));
-            }
-            const userId = payload.user?.id ?? payload.user?._id;
-            if (!userId || typeof payload.user?.username !== 'string') {
-                throw this.handleError(new Error('SSO exchange returned an invalid user'));
-            }
-            const user = {
-                id: userId,
-                username: payload.user.username,
-                // `name.displayName` is optional on the contract. A no-name user is
-                // valid; carry whatever structured name the server sent (possibly an
-                // empty object) and let consumers fall back to a handle.
-                name: payload.user.name ?? {},
-                avatar: payload.user.avatar,
-            };
-            // Plant the access token exactly like exchangeIdTokenForSession does.
-            // The SSO exchange does not return a refresh token (the central store
-            // holds the refresh credential), so default it to an empty string.
-            this.httpService.setTokens(payload.accessToken);
-            debug.log('SSO exchange complete:', { hasSession: !!payload.sessionId });
-            const session = {
-                sessionId: payload.sessionId,
-                deviceId: '',
-                expiresAt: payload.expiresAt ?? '',
-                user,
-                accessToken: payload.accessToken,
-            };
-            return session;
-        }
-        /**
-         * Mint a server-formed `/sso/establish` URL for the caller's OWN session,
-         * bound to an approved RP `origin`.
-         *
-         * Bearer-authenticated (the session id is taken from the caller's own
-         * bearer, server-side — never from any argument). The server validates that
-         * `origin` is an approved client origin (and matches the request `Origin`),
-         * derives the per-apex IdP host (`auth.<apex>`), mints a short-lived HS256
-         * establish-token, and returns a fully-formed
-         * `https://<auth-host>/sso/establish?et=…&return_to=<origin>/__oxy/sso-callback&state=<state>`.
-         *
-         * Used AFTER a web device-flow claim to plant the durable first-party
-         * `fedcm_session` cookie so a reload can re-mint a token (see
-         * {@link establishIdpSessionAfterClaim}). Cache-free (a POST is never
-         * cached, but `cache: false` is explicit).
-         *
-         * @param origin - The RP origin (`window.location.origin`) to establish for.
-         * @param state - The CSRF state echoed back in the callback fragment; the
-         *   caller persists the SAME value under `ssoStateKey(origin)` so the
-         *   post-bounce `sso-return` step validates it.
-         */
-        async requestSsoEstablishUrl(origin, state) {
-            if (typeof origin !== 'string' || origin.length === 0) {
-                throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty origin'));
-            }
-            if (typeof state !== 'string' || state.length === 0) {
-                throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty state'));
-            }
-            const response = await this.makeRequest('POST', '/sso/establish-token', { origin, state }, { cache: false });
-            if (!response ||
-                typeof response.establishUrl !== 'string' ||
-                response.establishUrl.length === 0) {
-                throw this.handleError(new Error('SSO establish-token returned no establishUrl'));
-            }
-            return { establishUrl: response.establishUrl };
-        }
-    };
-}

package/dist/esm/utils/ssoEstablish.js

@@ -1,107 +0,0 @@
-/**
- * Post-claim durable-session establish hop (web device-flow / "Sign in with
- * Oxy" QR).
- *
- * A WEB device-flow claim (`claimSessionByToken`) plants only IN-MEMORY tokens:
- * unlike a redirect/FedCM/silent sign-in, it never causes the IdP to plant a
- * `fedcm_session` cookie. So a reload has nothing to restore from — the
- * silent-iframe and `/sso` paths find no IdP session and the session is lost.
- *
- * This primitive closes that gap. AFTER the claim has committed and the session
- * has been durably persisted, it performs ONE top-level establish hop through
- * the RP's own per-apex IdP host (`auth.<rp-apex>`), reusing the EXISTING
- * `/sso/establish` endpoint: the server mints a short-lived, host+audience-bound
- * establish-token and returns a fully-formed establish URL; navigating to it
- * plants the durable first-party `fedcm_session` cookie and bounces back to the
- * RP callback with an opaque code the standard `sso-return` cold-boot step
- * exchanges.
- *
- * It reuses the SAME per-origin `sessionStorage` bounce contract
- * (`ssoStateKey` / `ssoGuardKey` / `ssoDestKey`) that {@link buildSsoBounceUrl}
- * primes for the terminal `/sso` bounce, so the post-bounce `sso-return` step
- * (`consumeSsoReturn`) validates the CSRF `state`, exchanges the code, and
- * restores the user's real destination with no extra wiring.
- *
- * Contract:
- *  - WEB only — off-web / native it is a no-op returning `false`.
- *  - NEVER fires while sitting on the central IdP origin (that would loop the
- *    IdP against itself).
- *  - Bounce state is persisted ONLY after the establish-URL request succeeds, so
- *    a failed request leaves no stale state behind.
- *  - SINGLE attempt: the caller invokes this exactly once per successful claim.
- *    On ANY failure it does NOT navigate and returns `false`, leaving the
- *    committed in-memory session exactly as-is (the user is no worse off than
- *    before this hop existed).
- *  - Total: never throws. Failures are reported via {@link deps.onError} only.
- */
-import { ssoStateKey, ssoGuardKey, ssoDestKey, ssoNavigate, isCentralIdPOrigin, } from './ssoBounce.js';
-import { generateSsoState } from '../mixins/OxyServices.sso.js';
-/**
- * Perform the post-claim establish hop. Returns `true` when a navigation to the
- * establish URL was initiated (the document is being torn down and replaced by
- * the IdP), `false` on every no-op / failure path.
- *
- * @param client - The exchange surface (`oxyServices.requestSsoEstablishUrl`).
- * @param deps - Injectable web seams; see {@link EstablishAfterClaimDeps}.
- */
-export async function establishIdpSessionAfterClaim(client, deps = {}) {
-    const isWeb = deps.isWeb ??
-        (() => typeof window !== 'undefined' &&
-            typeof window.sessionStorage !== 'undefined');
-    if (!isWeb()) {
-        return false;
-    }
-    const storage = deps.storage ?? window.sessionStorage;
-    const location = deps.location ?? window.location;
-    const navigate = deps.navigate ?? ssoNavigate;
-    const generateState = deps.generateState ?? generateSsoState;
-    const now = deps.now ?? (() => Date.now());
-    const origin = location.origin;
-    // Never establish while sitting on the central IdP itself — that would bounce
-    // the IdP against itself. (The device-flow claim can only happen on an RP.)
-    if (isCentralIdPOrigin(origin)) {
-        return false;
-    }
-    const state = generateState();
-    let establishUrl;
-    try {
-        const result = await client.requestSsoEstablishUrl(origin, state);
-        if (!result ||
-            typeof result.establishUrl !== 'string' ||
-            result.establishUrl.length === 0) {
-            return false;
-        }
-        establishUrl = result.establishUrl;
-        // Defense-in-depth before a TOP-LEVEL navigation: the establish URL is
-        // server-formed, but never follow anything that is not a well-formed https
-        // `/sso/establish` on an `auth.` host. A malformed or unexpected URL aborts
-        // silently (no navigation, no state persisted) — same total/no-throw
-        // contract — rather than navigating the document somewhere unintended.
-        let parsedEstablishUrl;
-        try {
-            parsedEstablishUrl = new URL(establishUrl);
-        }
-        catch {
-            return false;
-        }
-        if (parsedEstablishUrl.protocol !== 'https:' ||
-            parsedEstablishUrl.pathname !== '/sso/establish' ||
-            !parsedEstablishUrl.hostname.toLowerCase().startsWith('auth.')) {
-            return false;
-        }
-        // Persist the bounce state ONLY now that the request has succeeded and the
-        // URL is validated — so a failed/rejected request never leaves stale state
-        // behind. This is the exact contract the terminal `/sso` bounce primes via
-        // `buildSsoBounceUrl`, so the post-bounce `sso-return` step (`consumeSsoReturn`)
-        // validates `state`, exchanges the returned code, and restores the dest.
-        storage.setItem(ssoStateKey(origin), state);
-        storage.setItem(ssoGuardKey(origin), String(now()));
-        storage.setItem(ssoDestKey(origin), location.href);
-    }
-    catch (error) {
-        deps.onError?.(error);
-        return false;
-    }
-    navigate(establishUrl);
-    return true;
-}