@oxyhq/core 5.5.0 → 7.0.0

package/dist/esm/HttpService.js

@@ -270,8 +270,11 @@ export class HttpService {
             try {
                 // Build URL with params
                 const fullUrl = this.buildURL(url, params);
-                // Get auth token (with auto-refresh)
-                const authHeader = await this.getAuthHeader();
+                // Get auth token (with auto-refresh). `skipAuth` requests (the
+                // body-authenticated refresh endpoint) send NO bearer and skip the
+                // near-expiry preflight — see RequestOptions.skipAuth for the deadlock
+                // this avoids.
+                const authHeader = config.skipAuth ? null : await this.getAuthHeader();
                 // CSRF protects cookie-authenticated browser writes. Bearer-authenticated
                 // SDK clients are not vulnerable to ambient-cookie CSRF, and linked app
                 // APIs should not need to implement a duplicate `/csrf-token` route.
@@ -358,7 +361,7 @@ export class HttpService {
                     // On 401, delegate refresh to AuthManager and retry once before
                     // giving up. HttpService deliberately does not know any session
                     // routes; the AuthManager is the single session authority.
-                    if (response.status === 401 && !config._isAuthRetry) {
+                    if (response.status === 401 && !config._isAuthRetry && !config.skipAuth) {
                         const refreshed = await this.refreshAccessToken('response-401');
                         if (refreshed) {
                             // `deduplicate: false` is REQUIRED on the retry (mirrors the 403
@@ -1017,7 +1020,7 @@ export class HttpService {
  * `clearCacheByPrefix` sweeps and `clearCacheEntry` base-key matching.
  * The `clearCacheEntry` callsites all pass fixed, dataless logical keys
  * (`GET:/users/<id>`, `GET:/session/user/<sessionId>`,
- * `GET:/fedcm/me/authorized-apps`), so this readable suffix can never be
+ * `GET:/auth/grants`), so this readable suffix can never be
  * ambiguous with a serialized request body.
  */
 HttpService.CACHE_IDENTITY_DELIM = ' id=';

package/dist/esm/OxyServices.base.js

@@ -7,10 +7,6 @@ import { jwtDecode } from 'jwt-decode';
 import { handleHttpError } from './utils/errorUtils.js';
 import { HttpService } from './HttpService.js';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors.js';
-import { resolveCentralAuthUrl } from './utils/authWebUrl.js';
-import { isWeb } from './utils/platform.js';
-import { registrableApex } from './utils/fapiAutoDetect.js';
-import { logger } from './utils/loggerUtils.js';
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -22,21 +18,14 @@ export class OxyServicesBase {
         if (!config || typeof config !== 'object') {
             throw new Error('OxyConfig is required');
         }
-        // Default `authWebUrl` to the CENTRAL IdP (`auth.oxy.so`) when the caller
-        // did not pin it explicitly. TRUE central cross-domain SSO (Google/Meta/
-        // Clerk style) routes every RP through the one central IdP — it owns the
-        // host-only `fedcm_session` cookie and the central session store — so the
-        // SDK no longer derives a per-apex `auth.<rp-apex>` IdP by default.
-        // `autoDetectAuthWebUrl` is still exported for any call site that opts into
-        // per-apex resolution, but it is NOT the constructor default anymore.
-        // An explicit `authWebUrl` always wins (we only fill it when absent).
-        const resolvedConfig = config.authWebUrl
-            ? config
-            : { ...config, authWebUrl: resolveCentralAuthUrl(config.authWebUrl) };
-        this.config = resolvedConfig;
-        this.cloudURL = resolvedConfig.cloudURL || 'https://cloud.oxy.so';
+        // `authWebUrl` is a plain optional config value now (used only for building
+        // third-party "Sign in with Oxy" OAuth links). The SDK no longer derives or
+        // defaults an IdP host — the device-first cold boot restores sessions from
+        // the persisted refresh store, not an `auth.<apex>` bounce.
+        this.config = config;
+        this.cloudURL = config.cloudURL || 'https://cloud.oxy.so';
         // Initialize unified HTTP service (handles auth, caching, deduplication, queuing, retry)
-        this.httpService = new HttpService(resolvedConfig);
+        this.httpService = new HttpService(config);
     }
     // Test-only utility to reset tokens on this instance between jest tests
     // Note: tokens are now per-instance, so create new instances in tests for isolation
@@ -65,22 +54,6 @@ export class OxyServicesBase {
     getBaseURL() {
         return this.httpService.getBaseURL();
     }
-    /**
-     * Get the base URL the SDK's first-party session/refresh calls should target.
-     *
-     * Returns the configured `sessionBaseUrl` when provided, otherwise falls back
-     * to the API `baseURL` (`getBaseURL()`). Per the 2026 session architecture
-     * (docs/SESSION-ARCHITECTURE.md), non-`oxy.so` apps point this at their own
-     * same-site backend (e.g. `https://api.mention.earth`) whose session bridge
-     * forwards the user's refresh credential to `api.oxy.so`; `*.oxy.so` apps
-     * leave it unset so it resolves to `https://api.oxy.so` and nothing changes.
-     *
-     * This is additive: it only exposes configuration for `@oxyhq/services` to
-     * consume in a later phase. No refresh/auth logic in core reads it yet.
-     */
-    getSessionBaseUrl() {
-        return this.config.sessionBaseUrl ?? this.getBaseURL();
-    }
     /**
      * Get the HTTP service instance
      * Useful for advanced use cases where direct access to the HTTP service is needed
@@ -253,74 +226,6 @@ export class OxyServicesBase {
     getAccessToken() {
         return this.httpService.getAccessToken();
     }
-    /**
-     * Register the CURRENTLY-ACTIVE session in the device's first-party
-     * multi-account refresh-cookie set by calling `POST /auth/session`.
-     *
-     * This is the single, shared primitive every web primary-session commit and the
-     * account switch use to plant their `oxy_rt_<authuser>` slot. It MUST be a
-     * dedicated call to `/auth/session` rather than relying on whichever endpoint
-     * established the session: that endpoint is frequently OUTSIDE the cookie's
-     * `Path=/auth` scope (`/accounts/:id/switch`) or is a cross-origin/credential-
-     * less restore (`/sso/exchange`, the IdP `/auth/silent` postMessage) that cannot
-     * set an `api.oxy.so` cookie at all. `/auth/session` runs where the device's
-     * existing slots ARE visible, so the server resolves this user's slot (reusing an
-     * existing one or allocating a new one) without clobbering a sibling account,
-     * mints a fresh access token bound to the same session, and returns the resolved
-     * `authuser`.
-     *
-     * Behaviour:
-     * - Requires a planted bearer (the caller must have already installed the
-     *   session's access token); `/auth/session` derives the session from it.
-     * - On success re-plants the rotated access token (so the active token matches
-     *   the freshly-rotated cookie) and returns the device `authuser` slot.
-     * - WEB-ONLY: on native there are no first-party refresh cookies → returns
-     *   `null`.
-     * - FIRST-PARTY-ONLY: the cookie is host-only on the API host with
-     *   `SameSite=Lax`, so it only sticks when the page is SAME-SITE (same
-     *   registrable apex) as the API. On a cross-apex RP (`mention.earth` calling
-     *   `api.oxy.so`) the browser rejects the `Set-Cookie` as a third-party cookie,
-     *   so a returned slot would be a phantom never enumerated by `refresh-all`.
-     *   Those RPs durably restore via the per-apex `/auth/silent` iframe + `/sso`
-     *   bounce, NOT this device set → returns `null` without calling the API.
-     * - BEST-EFFORT: a failure (e.g. transient network) never throws — the session
-     *   stays active in-memory; only its reload durability via the device set is at
-     *   risk. The caller treats `null` as "not registered in the device set".
-     *
-     * @returns The resolved device `authuser` slot, or `null` on native / cross-apex
-     *   / failure.
-     */
-    async establishDeviceRefreshSlot() {
-        if (!isWeb()) {
-            return null;
-        }
-        if (typeof window !== 'undefined' && window.location?.hostname) {
-            const pageApex = registrableApex(window.location.hostname);
-            let apiApex = null;
-            try {
-                apiApex = registrableApex(new URL(this.getBaseURL()).hostname);
-            }
-            catch {
-                apiApex = null;
-            }
-            if (!pageApex || !apiApex || pageApex !== apiApex) {
-                return null;
-            }
-        }
-        try {
-            const established = await this.makeRequest('POST', '/auth/session', undefined, { cache: false });
-            // `/auth/session` mints a fresh access token off the same session; re-plant
-            // it so the active token matches the rotated cookie.
-            if (established?.accessToken) {
-                this.setTokens(established.accessToken);
-            }
-            return typeof established?.authuser === 'number' ? established.authuser : null;
-        }
-        catch (error) {
-            logger.warn('[OxyServices] Failed to establish device refresh cookie via POST /auth/session; the session is active in-session but may not survive a reload as part of the device account set', { component: 'OxyServices', method: 'establishDeviceRefreshSlot' }, error);
-            return null;
-        }
-    }
     /**
      * Decode the current access token and return its `exp` claim in SECONDS since
      * the Unix epoch (the raw JWT `exp` unit), or `null` when there is no token,

package/dist/esm/boot/coldBootV2.js

@@ -0,0 +1,344 @@
+/**
+ * coldBootV2 — one device-first cold boot for every consumer.
+ *
+ * On a fresh page load / app launch this resolves the device's session in a
+ * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
+ * redirects to a login page: an unresolved boot ends in a signed-out state that
+ * the app renders with a "Sign in with Oxy" button.
+ *
+ * Ordered steps (first to yield a session wins):
+ *   1. `bootstrap-return` (web) — consume a `#oxy_boot` return fragment from a
+ *      just-completed cross-apex hop: strip it, verify state, persist the
+ *      deviceToken, exchange the code.
+ *   2. `stored-tokens` — the persisted per-origin refresh family: warm-plant a
+ *      still-valid access token, else rotate via `/auth/refresh-token`.
+ *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity,
+ *      issuing + mirroring a shared deviceToken the first time.
+ *   4. `bootstrap-hop` (web) — same-apex: an inline credentialed
+ *      `/auth/device/web-session` fetch (no redirect); cross-apex: ONE top-level
+ *      navigation to `/auth/device/bootstrap`, guarded once-ever per origin.
+ *   5. Signed out.
+ *
+ * All mutable guard state lives in STORAGE (localStorage `oxy.boot.attempted` +
+ * sessionStorage `oxy.boot.state`), never in module scope, so the guard holds
+ * under Metro/bundler re-evaluation.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { resolveUserId } from '@oxyhq/contracts';
+import { runColdBoot } from '../utils/coldBoot.js';
+import { isWeb as detectWeb, isNative as detectNative } from '../utils/platform.js';
+import { KeyManager } from '../crypto/keyManager.js';
+import { logger } from '../utils/loggerUtils.js';
+import { refreshPersistedSession } from '../session/refresh.js';
+import { consumeDeviceBootReturn, hashHasBootFragment, BOOT_STATE_SESSION_KEY, } from './deviceBootReturn.js';
+/**
+ * localStorage flag marking that the cross-apex bootstrap navigation has fired
+ * once for this origin. Persistent (not session) so the visible redirect
+ * happens AT MOST ONCE EVER per browser+origin — a signed-out user is never
+ * bounced again; they sign in explicitly.
+ */
+export const BOOT_ATTEMPTED_KEY = 'oxy.boot.attempted';
+/**
+ * Do not warm-plant a stored access token with less than this remaining — it
+ * would need an immediate refresh anyway, so fall through to the rotate path.
+ * Matches the refresh lead window.
+ */
+const WARM_MIN_REMAINING_MS = 60000;
+/**
+ * Generate a 128-bit hex CSRF state token. Prefers Web Crypto
+ * (`crypto.getRandomValues`, present in browsers and modern Node); falls back
+ * to a time+`Math.random` mix only when no CSPRNG is reachable (this token
+ * gates a single-use CSRF echo, not a long-lived secret).
+ */
+function generateStateToken() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        cryptoObj.getRandomValues(bytes);
+        return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    return `${Date.now().toString(16)}${Math.random().toString(16).slice(2, 18)}`;
+}
+/**
+ * The guarded real-globals {@link ColdBootDom}. Every accessor tolerates a
+ * missing/throwing global (SSR, sandboxed iframe) by returning a neutral value
+ * or no-op, so the boot degrades to signed-out rather than crashing.
+ */
+export function createBrowserColdBootDom() {
+    const safe = (fn, fallback) => {
+        try {
+            return fn();
+        }
+        catch {
+            return fallback;
+        }
+    };
+    return {
+        getHash: () => safe(() => (typeof window !== 'undefined' ? window.location.hash : ''), ''),
+        stripFragment: () => safe(() => {
+            if (typeof window !== 'undefined' && window.history?.replaceState) {
+                const { pathname, search } = window.location;
+                window.history.replaceState(null, '', `${pathname}${search}`);
+            }
+        }, undefined),
+        getSessionItem: (key) => safe(() => (typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(key) : null), null),
+        setSessionItem: (key, value) => safe(() => {
+            if (typeof sessionStorage !== 'undefined')
+                sessionStorage.setItem(key, value);
+        }, undefined),
+        removeSessionItem: (key) => safe(() => {
+            if (typeof sessionStorage !== 'undefined')
+                sessionStorage.removeItem(key);
+        }, undefined),
+        getLocalItem: (key) => safe(() => (typeof localStorage !== 'undefined' ? localStorage.getItem(key) : null), null),
+        setLocalItem: (key, value) => safe(() => {
+            if (typeof localStorage !== 'undefined')
+                localStorage.setItem(key, value);
+        }, undefined),
+        getLocationHostname: () => safe(() => (typeof window !== 'undefined' ? window.location.hostname : null), null),
+        getReturnToHref: () => safe(() => {
+            if (typeof window === 'undefined')
+                return null;
+            const { origin, pathname, search } = window.location;
+            return `${origin}${pathname}${search}`;
+        }, null),
+        navigate: (url) => safe(() => {
+            if (typeof window !== 'undefined')
+                window.location.assign(url);
+        }, undefined),
+        randomState: generateStateToken,
+    };
+}
+/**
+ * Registrable domain = the last two labels of a host. A deliberately SMALL
+ * local helper (the plan forbids coupling the boot to `fapiAutoDetect`/`tldts`).
+ * Correct for every Oxy apex (all two-label domains: `oxy.so`, `mention.earth`,
+ * `alia.onl`, `homiio.com`); the only imprecision — a multi-part public suffix
+ * such as `co.uk` — never arises here because the compared API host is always
+ * `api.oxy.so`, so a page under a different registrable domain still classifies
+ * as cross-apex.
+ */
+function registrableDomain(host) {
+    const labels = host.toLowerCase().split('.').filter(Boolean);
+    return labels.length <= 2 ? labels.join('.') : labels.slice(-2).join('.');
+}
+/**
+ * Is `host` an IP literal (v4/v6) or a single-label host (`localhost`)? Such
+ * hosts have NO registrable domain — the last-two-labels heuristic would
+ * mis-group them (`192.168.1.1` and `10.0.1.1` both collapse to `1.1`; IPv6
+ * `::1` and `localhost` are single "labels"), so a LAN/dev page could be wrongly
+ * classified same-apex as a different LAN API and skip the cross-apex hop.
+ */
+function isIpOrSingleLabel(host) {
+    if (host.includes(':')) {
+        return true; // IPv6 literal
+    }
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) {
+        return true; // IPv4 literal
+    }
+    return !host.includes('.'); // single-label (e.g. `localhost`)
+}
+/**
+ * True when both hosts are same-site / same-apex. For a normal multi-label host
+ * pair, that means sharing a registrable domain. For an IP literal or a
+ * single-label host (no registrable domain), same-apex requires the two hosts
+ * to be EXACTLY equal — never grouped by a spurious trailing-label match.
+ */
+export function isSameApex(pageHost, apiHost) {
+    const a = pageHost.toLowerCase();
+    const b = apiHost.toLowerCase();
+    if (isIpOrSingleLabel(a) || isIpOrSingleLabel(b)) {
+        return a === b;
+    }
+    const ra = registrableDomain(a);
+    const rb = registrableDomain(b);
+    return ra !== '' && ra === rb;
+}
+/** Build a `DeviceBootSession` from a persisted state (post-refresh/warm-plant). */
+function sessionFromPersisted(state, accessToken) {
+    return { sessionId: state.sessionId, userId: state.userId, accessToken };
+}
+/**
+ * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
+ * a side effect, invokes `onSession` (winning session, token already planted)
+ * or `onSignedOut` (no session — unless the boot is navigating away for the
+ * cross-apex hop, in which case neither fires).
+ */
+export async function runSessionColdBoot(opts) {
+    const { oxy, store } = opts;
+    const dom = opts.dom ?? createBrowserColdBootDom();
+    const isWeb = opts.platform?.isWeb ?? detectWeb();
+    const isNative = opts.platform?.isNative ?? detectNative();
+    // Signed-out reason + navigating flag are boot-local (not module-level), so
+    // they cannot leak across boots or break under bundler re-evaluation.
+    let signedOutReason = 'no_session';
+    let navigating = false;
+    const steps = [];
+    // 1. bootstrap-return (web) — consume a #oxy_boot fragment.
+    steps.push({
+        id: 'bootstrap-return',
+        enabled: () => isWeb && hashHasBootFragment(dom.getHash()),
+        run: async () => {
+            const outcome = await consumeDeviceBootReturn({
+                hash: dom.getHash(),
+                stripFragment: () => dom.stripFragment(),
+                readExpectedState: () => dom.getSessionItem(BOOT_STATE_SESSION_KEY),
+                clearExpectedState: () => dom.removeSessionItem(BOOT_STATE_SESSION_KEY),
+                store,
+                exchangeBootCode: (code) => oxy.exchangeBootCode(code),
+                plantAccessToken: (accessToken) => oxy.setTokens(accessToken),
+            });
+            if (outcome.kind === 'session') {
+                return { kind: 'session', session: outcome.session };
+            }
+            if (outcome.kind === 'state-mismatch') {
+                signedOutReason = 'state-mismatch';
+            }
+            else if (outcome.kind === 'no-session') {
+                // `DeviceBootReason` also carries 'session'; a no-session outcome with
+                // that reason (a `session` reason but no code) is still signed out.
+                signedOutReason = outcome.reason === 'new_device' ? 'new_device' : 'no_session';
+            }
+            // Fall through: a stored refresh family (a prior same-origin session) may
+            // still recover below. The once-ever flag blocks a second hop.
+            return { kind: 'skip' };
+        },
+    });
+    // 2. stored-tokens — warm-plant or rotate the persisted refresh family.
+    steps.push({
+        id: 'stored-tokens',
+        run: async () => {
+            const persisted = await store.load();
+            if (!persisted) {
+                return { kind: 'skip' };
+            }
+            // Warm path: a still-valid access token → plant immediately (no network).
+            if (persisted.accessToken &&
+                persisted.expiresAt &&
+                Date.parse(persisted.expiresAt) - Date.now() > WARM_MIN_REMAINING_MS) {
+                oxy.setTokens(persisted.accessToken);
+                return { kind: 'session', session: sessionFromPersisted(persisted, persisted.accessToken) };
+            }
+            // Rotate path: refreshPersistedSession plants + persists, and clears the
+            // store on a family-revoked error.
+            const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: isNative });
+            if (!token) {
+                return { kind: 'skip' };
+            }
+            const after = await store.load();
+            const base = after ?? persisted;
+            return { kind: 'session', session: sessionFromPersisted(base, token) };
+        },
+    });
+    // 3. shared-key-signin (native) — re-mint from the shared identity.
+    steps.push({
+        id: 'shared-key-signin',
+        enabled: () => isNative,
+        run: async () => {
+            const session = await oxy.signInWithSharedIdentity();
+            if (!session?.accessToken) {
+                return { kind: 'skip' };
+            }
+            // First shared-key sign-in on this device: issue + persist + mirror a
+            // shared deviceToken so every native Oxy app joins one DeviceSession.
+            // Best-effort — never fail the sign-in over device-token issuance.
+            try {
+                const existing = await KeyManager.getSharedDeviceToken();
+                if (!existing) {
+                    const deviceToken = await oxy.issueNativeDeviceToken();
+                    await store.saveDeviceToken(deviceToken);
+                    await KeyManager.setSharedDeviceToken(deviceToken);
+                }
+            }
+            catch (error) {
+                logger.debug('Native deviceToken issuance skipped', { component: 'coldBootV2', method: 'shared-key-signin' }, error);
+            }
+            return {
+                kind: 'session',
+                session: {
+                    sessionId: session.sessionId,
+                    userId: session.user.id,
+                    accessToken: session.accessToken,
+                },
+            };
+        },
+    });
+    // 4. bootstrap-hop (web, terminal) — same-apex inline fetch OR cross-apex nav.
+    steps.push({
+        id: 'bootstrap-hop',
+        enabled: () => isWeb,
+        run: async () => {
+            const pageHost = dom.getLocationHostname();
+            let apiHost = null;
+            try {
+                apiHost = new URL(oxy.getBaseURL()).hostname;
+            }
+            catch {
+                apiHost = null;
+            }
+            if (!pageHost || !apiHost) {
+                return { kind: 'skip' };
+            }
+            // Same-apex: inline credentialed fetch, no redirect, runs every boot.
+            if (isSameApex(pageHost, apiHost)) {
+                const result = await oxy.requestWebSession();
+                // The rotated deviceToken is on BOTH arms (it is device-level, not
+                // session-level) — persist it before branching on the session.
+                await store.saveDeviceToken(result.deviceToken);
+                if (result.reason === 'session') {
+                    const bundle = result.session;
+                    const userId = resolveUserId(bundle.user);
+                    if (!userId) {
+                        return { kind: 'skip' };
+                    }
+                    const next = {
+                        sessionId: bundle.sessionId,
+                        refreshToken: bundle.refreshToken,
+                        userId,
+                        deviceToken: result.deviceToken,
+                        accessToken: bundle.accessToken,
+                        expiresAt: bundle.expiresAt,
+                    };
+                    await store.save(next);
+                    oxy.setTokens(bundle.accessToken);
+                    return { kind: 'session', session: sessionFromPersisted(next, bundle.accessToken) };
+                }
+                // Known device, signed out.
+                signedOutReason = result.reason;
+                return { kind: 'skip' };
+            }
+            // Cross-apex: ONE visible top-level navigation, once-ever per origin.
+            if (dom.getLocalItem(BOOT_ATTEMPTED_KEY)) {
+                return { kind: 'skip' };
+            }
+            const returnTo = opts.returnTo ?? dom.getReturnToHref();
+            if (!returnTo) {
+                return { kind: 'skip' };
+            }
+            const state = dom.randomState();
+            dom.setSessionItem(BOOT_STATE_SESSION_KEY, state);
+            dom.setLocalItem(BOOT_ATTEMPTED_KEY, '1');
+            navigating = true;
+            dom.navigate(oxy.buildBootstrapUrl(returnTo, state));
+            return { kind: 'skip' };
+        },
+    });
+    const outcome = await runColdBoot({
+        steps,
+        onStepError: (id, error) => {
+            signedOutReason = 'error';
+            opts.onStepError?.(id, error);
+        },
+    });
+    if (outcome.kind === 'session') {
+        await opts.onSession?.({ ...outcome.session, via: outcome.via });
+        return outcome;
+    }
+    // Navigating away for the cross-apex hop: the page is unloading, so do not
+    // flash a signed-out state.
+    if (!navigating) {
+        await opts.onSignedOut?.(signedOutReason);
+    }
+    return outcome;
+}

package/dist/esm/boot/deviceBootReturn.js

@@ -0,0 +1,146 @@
+/**
+ * Device-boot return-fragment consumption (web cross-apex hop).
+ *
+ * After the top-level `GET /auth/device/bootstrap` hop, the API 303s back to the
+ * RP with a `#oxy_boot=<base64url(JSON)>` fragment. This module parses and
+ * consumes it: it strips the fragment from the URL FIRST (so the opaque
+ * deviceToken / code never linger in history or a `Referer`), verifies the
+ * echoed CSRF `state` against the value the initiator stashed in
+ * `sessionStorage`, persists the deviceToken, and — when a session resolved —
+ * exchanges the single-use `code` for a token bundle.
+ *
+ * Pure/injectable: all DOM access (hash, `history.replaceState`,
+ * `sessionStorage`) is passed in as callbacks so the logic is unit-testable
+ * under the jest `node` environment and reusable by `coldBootV2`.
+ *
+ * ESM-safe (no `require()`).
+ */
+import { deviceBootFragmentSchema, resolveUserId, safeParseContract, } from '@oxyhq/contracts';
+/** The `#oxy_boot=` fragment parameter name the API appends on the return hop. */
+export const BOOT_FRAGMENT_PARAM = 'oxy_boot';
+/**
+ * `sessionStorage` key under which the bootstrap-hop initiator stashes the
+ * 128-bit CSRF `state` before navigating, and which the return step reads back
+ * (single-use).
+ */
+export const BOOT_STATE_SESSION_KEY = 'oxy.boot.state';
+/**
+ * Decode a base64url string to UTF-8 text, or `null` on any malformed input.
+ * Handles both web (`atob` + `TextDecoder`) and Node (`Buffer`) without a
+ * `require()` — the ESM build stays clean.
+ */
+function base64UrlDecode(input) {
+    try {
+        let b64 = input.replace(/-/g, '+').replace(/_/g, '/');
+        while (b64.length % 4 !== 0) {
+            b64 += '=';
+        }
+        if (typeof atob === 'function') {
+            const binary = atob(b64);
+            const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+            if (typeof TextDecoder !== 'undefined') {
+                return new TextDecoder().decode(bytes);
+            }
+            return binary;
+        }
+        if (typeof Buffer !== 'undefined') {
+            return Buffer.from(b64, 'base64').toString('utf-8');
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a location hash carries the `oxy_boot` return fragment. */
+export function hashHasBootFragment(hash) {
+    return new RegExp(`(^|[#&])${BOOT_FRAGMENT_PARAM}=`).test(hash);
+}
+/**
+ * Extract + decode + validate the `oxy_boot` fragment from a location hash.
+ * Returns the parsed {@link DeviceBootFragment}, or `null` when the parameter
+ * is absent, not valid base64url, not JSON, or fails the contract schema.
+ */
+export function parseDeviceBootFragment(hash) {
+    const withoutHash = hash.startsWith('#') ? hash.slice(1) : hash;
+    const params = new URLSearchParams(withoutHash);
+    const raw = params.get(BOOT_FRAGMENT_PARAM);
+    if (!raw) {
+        return null;
+    }
+    const json = base64UrlDecode(raw);
+    if (!json) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    return safeParseContract(deviceBootFragmentSchema, parsed);
+}
+/**
+ * Consume the device-boot return fragment.
+ *
+ * Order is load-bearing:
+ *   1. If no fragment is present, return `none` (no URL mutation).
+ *   2. STRIP the fragment from the URL immediately — before validation or any
+ *      network — so the deviceToken/code never persist in history/referrer.
+ *   3. Verify the echoed `state` against the stashed (single-use) value; a
+ *      mismatch returns `state-mismatch` without persisting or exchanging.
+ *   4. Persist the deviceToken (survives sign-out).
+ *   5. If a session resolved (`reason:'session'` + `code`), exchange the code,
+ *      persist the rotated session, plant the token, and return `session`.
+ *      Otherwise return `no-session` with the reason.
+ */
+export async function consumeDeviceBootReturn(deps) {
+    if (!hashHasBootFragment(deps.hash)) {
+        return { kind: 'none' };
+    }
+    // Strip FIRST — even a forged/malformed fragment must not linger in the URL.
+    deps.stripFragment();
+    const fragment = parseDeviceBootFragment(deps.hash);
+    if (!fragment) {
+        return { kind: 'none' };
+    }
+    const expected = deps.readExpectedState();
+    deps.clearExpectedState();
+    if (!expected || expected !== fragment.state) {
+        return { kind: 'state-mismatch' };
+    }
+    await deps.store.saveDeviceToken(fragment.deviceToken);
+    // `code` is guaranteed present on the `session` arm (the contract's
+    // discriminated union requires it; a session fragment without a code fails to
+    // parse and never reaches here).
+    if (fragment.reason === 'session') {
+        try {
+            const bundle = await deps.exchangeBootCode(fragment.code);
+            const userId = resolveUserId(bundle.user);
+            if (!userId) {
+                return { kind: 'no-session', reason: 'no_session' };
+            }
+            const next = {
+                sessionId: bundle.sessionId,
+                refreshToken: bundle.refreshToken,
+                userId,
+                deviceToken: fragment.deviceToken,
+                accessToken: bundle.accessToken,
+                expiresAt: bundle.expiresAt,
+            };
+            await deps.store.save(next);
+            deps.plantAccessToken(bundle.accessToken);
+            return {
+                kind: 'session',
+                session: { sessionId: bundle.sessionId, userId, accessToken: bundle.accessToken },
+            };
+        }
+        catch {
+            // The code burned/expired between hop and exchange — resolve signed-out
+            // rather than throwing (the once-ever hop already fired; do not retry).
+            return { kind: 'no-session', reason: 'no_session' };
+        }
+    }
+    return { kind: 'no-session', reason: fragment.reason };
+}