@oxyhq/core 9.1.0 → 9.2.0

package/dist/esm/boot/{coldBootV2.js → sessionColdBoot.js}

@@ -1,5 +1,5 @@
 /**
- * coldBootV2 — one device-first cold boot for every consumer.
+ * Device-first session 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
@@ -92,7 +92,7 @@ export async function runSessionColdBoot(opts) {
                     return { kind: 'skip' };
                 }
                 // Transient (network / 5xx): keep the secret; a later attempt can succeed.
-                logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'coldBootV2', method: 'device-secret-mint' }, error);
+                logger.debug('device-secret mint failed (transient) — keeping secret', { component: 'sessionColdBoot', method: 'device-secret-mint' }, error);
                 return { kind: 'skip' };
             }
         },

package/dist/esm/index.js

@@ -131,7 +131,9 @@ export { runColdBoot } from './utils/coldBoot.js';
 // OAuth 2.0 Authorization Code + PKCE helpers ("Sign in with Oxy" third party).
 // Standard OAuth against auth.oxy.so/authorize — no FedCM/cookies/SSO bounce.
 // ---------------------------------------------------------------------------
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, } from './utils/oauthPkce.js';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, } from './utils/oauthPkce.js';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins.js';
+export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync.js';
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------
@@ -164,7 +166,7 @@ export { AccountDialogController, createAccountDialogController, } from './sessi
 // ---------------------------------------------------------------------------
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore.js';
 export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
-export { runSessionColdBoot } from './boot/coldBootV2.js';
+export { runSessionColdBoot } from './boot/sessionColdBoot.js';
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every
 // client SDK. Import them directly from `@oxyhq/contracts`; `@oxyhq/core` does NOT

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

@@ -803,6 +803,7 @@ export function OxyServicesAuthMixin(Base) {
                     password,
                     deviceName: options.deviceName,
                     deviceFingerprint: options.deviceFingerprint,
+                    ...(options.deviceId ? { deviceId: options.deviceId } : {}),
                 }, { cache: false });
                 const parsed = safeParseContract(loginResultSchema, res);
                 if (!parsed) {
@@ -831,6 +832,7 @@ export function OxyServicesAuthMixin(Base) {
                     token: params.token,
                     backupCode: params.backupCode,
                     deviceName: params.deviceName,
+                    ...(params.deviceId ? { deviceId: params.deviceId } : {}),
                 }, { cache: false });
                 const parsed = safeParseContract(loginResultSchema, res);
                 if (!parsed || 'twoFactorRequired' in parsed) {
@@ -845,5 +847,64 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Exchange an OAuth authorization code (returned to the RP redirect URI
+         * after password sign-in at auth.oxy.so) for a device-first session.
+         * Public first-party clients use PKCE (`codeVerifier`); the access token is
+         * planted immediately on success.
+         */
+        async exchangeOAuthCode(params) {
+            try {
+                const res = await this.makeRequest('POST', '/auth/oauth/token', {
+                    code: params.code,
+                    clientId: params.clientId,
+                    redirectUri: params.redirectUri,
+                    codeVerifier: params.codeVerifier,
+                }, { cache: false });
+                const payload = res.data ??
+                    res;
+                if (!payload || typeof payload !== 'object') {
+                    throw new Error('auth/oauth/token returned an unexpected response shape');
+                }
+                const record = payload;
+                const accessToken = (record.access_token ?? record.accessToken);
+                const sessionId = (record.session_id ?? record.sessionId);
+                const deviceId = (record.deviceId ?? record.device_id);
+                const deviceSecret = (record.deviceSecret ?? record.device_secret);
+                const userRaw = record.user;
+                if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+                    throw new Error('auth/oauth/token returned an incomplete session payload');
+                }
+                const userObj = userRaw;
+                const userId = userObj.id;
+                if (!userId) {
+                    throw new Error('auth/oauth/token returned a session without user.id');
+                }
+                const expiresInSec = typeof record.expires_in === 'number'
+                    ? record.expires_in
+                    : typeof record.expiresIn === 'number'
+                        ? record.expiresIn
+                        : 15 * 60;
+                const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
+                if (accessToken) {
+                    this.setTokens(accessToken);
+                }
+                return {
+                    sessionId,
+                    deviceId,
+                    expiresAt,
+                    accessToken,
+                    deviceSecret,
+                    user: {
+                        id: userId,
+                        username: typeof userObj.username === 'string' ? userObj.username : undefined,
+                        avatar: typeof userObj.avatar === 'string' ? userObj.avatar : undefined,
+                    },
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
     };
 }

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

@@ -2,7 +2,7 @@
  * Device-first token mint mixin.
  *
  * The client half of the zero-cookie device transport: the single network call
- * the cold boot (`coldBootV2`) and the unified re-mint handler (`refresh.ts`)
+ * the cold boot (`sessionColdBoot`) and the unified re-mint handler (`refresh.ts`)
  * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
  * token. The response is validated against the `@oxyhq/contracts`
  * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { deviceTokenMintResponseSchema, safeParseContract, } from '@oxyhq/contracts';
+import { deviceTokenMintResponseSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemResponseSchema, safeParseContract, } from '@oxyhq/contracts';
 export function OxyServicesDeviceBootMixin(Base) {
     return class extends Base {
         /**
@@ -44,5 +44,33 @@ export function OxyServicesDeviceBootMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /** Mint a one-time hub sync ticket (bearer required). */
+        async issueHubTicket(returnOrigin) {
+            try {
+                const res = await this.makeRequest('POST', '/session/device/hub-ticket', { returnOrigin }, { cache: false });
+                const parsed = safeParseContract(deviceHubTicketIssueResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('session/device/hub-ticket returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /** Redeem a hub sync ticket for a fresh device secret (public). */
+        async redeemHubTicket(ticket, returnOrigin) {
+            try {
+                const res = await this.makeRequest('POST', '/session/device/redeem-ticket', { ticket, returnOrigin }, { cache: false, skipAuth: true });
+                const parsed = safeParseContract(deviceHubTicketRedeemResponseSchema, res);
+                if (!parsed) {
+                    throw new Error('session/device/redeem-ticket returned an unexpected response shape');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
     };
 }

package/dist/esm/server/index.js

@@ -27,3 +27,4 @@ export { verifySecret } from './verifySecret.js';
 // Pure host handling (no browser deps), so it is safe on the server subpath and
 // lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex.js';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins.js';

package/dist/esm/session/SessionClient.js

@@ -60,21 +60,32 @@ export class SessionClient {
             return false;
         }
         this.state = next;
-        this.notify();
-        if (this.options.transport) {
-            void this.options.transport.ensureActiveToken(next).catch((error) => {
+        const transport = this.options.transport;
+        const needsMintBeforeNotify = transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+        const finishApply = () => {
+            this.notify();
+            if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+                try {
+                    this.options.onUnauthenticated();
+                }
+                catch (error) {
+                    logger.error('[SessionClient] onUnauthenticated threw', error);
+                }
+            }
+        };
+        if (needsMintBeforeNotify) {
+            void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
                 logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+                finishApply();
             });
         }
-        // A device signout-all leaves zero accounts — tell the provider to clear
-        // the persisted store so a reload does not try to restore a dead session.
-        if (next.accounts.length === 0 && this.options.onUnauthenticated) {
-            try {
-                this.options.onUnauthenticated();
-            }
-            catch (error) {
-                logger.error('[SessionClient] onUnauthenticated threw', error);
+        else {
+            if (transport) {
+                void transport.ensureActiveToken(next).catch((error) => {
+                    logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+                });
             }
+            finishApply();
         }
         return true;
     }
@@ -152,19 +163,24 @@ export class SessionClient {
         this.started = true;
         this.tokenUnsub = this.host.onTokensChanged((token) => {
             // A rotated/fresh bearer landed — reconnect a dropped socket so its
-            // handshake re-runs with the current token. Sign-out (null token) is
-            // handled by the consumer calling `stop()`.
-            if (!token || !this.socket)
+            // handshake re-runs with the current token. Sign-out (null token) keeps
+            // the device-scoped socket when a device credential is available.
+            if (!this.socket)
                 return;
-            if (!this.socket.connected) {
+            if (token) {
+                if (!this.socket.connected) {
+                    this.socket.connect();
+                }
+                return;
+            }
+            const cred = this.host.getDeviceCredential();
+            if (cred && !this.socket.connected) {
                 this.socket.connect();
             }
         });
         this.openBroadcastChannel();
-        // `bootstrap` (`GET /session/device/state`) is bearer-authenticated. A
-        // signed-out client opens no socket and runs no bootstrap; a bootstrap
-        // failure is non-fatal — the socket still connects so realtime sync
-        // survives a transient state-fetch error.
+        // Device-scoped socket: bearer when authenticated, else deviceId+deviceSecret so
+        // signed-out tabs still receive `session_state` and can mint on change.
         if (this.host.getAccessToken()) {
             try {
                 await this.bootstrap();
@@ -207,15 +223,29 @@ export class SessionClient {
         }
         if (!this.started)
             return; // stopped while the dynamic import was in flight
-        // Sockets are BEARER-ONLY: the server rejects any handshake without a valid
-        // bearer, so a signed-out client never opens a socket.
-        if (!this.host.getAccessToken())
+        const token = this.host.getAccessToken();
+        const deviceCredential = this.host.getDeviceCredential();
+        if (!token && !deviceCredential)
             return;
         const socket = io(this.host.getBaseURL(), {
             transports: ['websocket'],
             autoConnect: true,
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 10000,
             auth: (cb) => {
-                cb({ token: this.host.getAccessToken() ?? '' });
+                const bearer = this.host.getAccessToken();
+                if (bearer) {
+                    cb({ token: bearer });
+                    return;
+                }
+                const cred = this.host.getDeviceCredential();
+                if (cred) {
+                    cb({ deviceId: cred.deviceId, deviceSecret: cred.deviceSecret });
+                    return;
+                }
+                cb({ token: '' });
             },
         });
         socket.on('session_state', (payload) => {
@@ -223,9 +253,11 @@ export class SessionClient {
             if (!applied)
                 return;
             // A push changed the active account on another device/tab — re-fetch state
-            // to plant the access token for the newly-active account.
+            // to plant the access token for the newly-active account. When this tab is
+            // still signed out, applyState mints via ensureActiveToken first; bootstrap
+            // requires a bearer and must not run until then.
             const active = this.state?.activeAccountId ?? null;
-            if (active && active !== this.host.getCurrentAccountId()) {
+            if (active && active !== this.host.getCurrentAccountId() && this.host.getAccessToken()) {
                 void this.bootstrap().catch((error) => {
                     logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
                 });

package/dist/esm/session/accountDialogController.js

@@ -27,6 +27,7 @@
  */
 import { logger } from '../utils/loggerUtils.js';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
+import { generateOAuthState, generatePkcePair, normalizeOAuthRedirectUri, persistOAuthHandshake, } from '../utils/oauthPkce.js';
 import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
 const DEFAULT_POLL_INTERVAL_MS = 3000;
 const IDLE_SIGN_IN = {
@@ -68,6 +69,7 @@ export class AccountDialogController {
         this.commitSession = options.commitSession;
         this.onSignedIn = options.onSignedIn;
         this.idpApex = options.idpApex ?? CENTRAL_IDP_APEX;
+        this.authRedirectUri = options.authRedirectUri ?? null;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.openUrl = options.openUrl;
         this.snapshot = this.computeSnapshot();
@@ -421,18 +423,27 @@ export class AccountDialogController {
      * @param params.state - Optional opaque state echoed back on return.
      * @returns The absolute auth.oxy.so sign-in URL.
      */
-    openPasswordAtOxyAuth(params = {}) {
+    async openPasswordAtOxyAuth(params = {}) {
         const base = `https://auth.${this.idpApex}`;
         const url = new URL('/login', base);
-        const returnUrl = params.returnUrl ?? currentLocationHref();
-        if (returnUrl) {
-            url.searchParams.set('redirect_uri', returnUrl);
+        const rawRedirect = params.redirectUri ??
+            this.authRedirectUri ??
+            params.returnUrl ??
+            currentLocationOrigin();
+        const redirectUri = rawRedirect ? normalizeOAuthRedirectUri(rawRedirect) : '';
+        if (redirectUri) {
+            url.searchParams.set('redirect_uri', redirectUri);
         }
         if (this.clientId) {
             url.searchParams.set('client_id', this.clientId);
         }
-        if (params.state) {
-            url.searchParams.set('state', params.state);
+        const state = params.state ?? (await generateOAuthState());
+        url.searchParams.set('state', state);
+        const { codeChallenge, codeVerifier } = await generatePkcePair();
+        url.searchParams.set('code_challenge', codeChallenge);
+        url.searchParams.set('code_challenge_method', 'S256');
+        if (!persistOAuthHandshake(state, codeVerifier)) {
+            throw new Error('Could not persist OAuth handshake for password sign-in');
         }
         const href = url.toString();
         this.openUrl?.(href);
@@ -601,8 +612,8 @@ export function createAccountDialogController(options) {
 // ---------------------------------------------------------------------------
 // Local helpers
 // ---------------------------------------------------------------------------
-/** Current document URL on web; empty string where `location` is absent (native/SSR). */
-function currentLocationHref() {
+/** Current document origin on web; empty string where `location` is absent (native/SSR). */
+function currentLocationOrigin() {
     const location = globalThis.location;
-    return typeof location?.href === 'string' ? location.href : '';
+    return typeof location?.origin === 'string' ? location.origin : '';
 }

package/dist/esm/session/authStateStore.js

@@ -5,7 +5,7 @@
  * a reload restores the session locally without a redirect: `deviceId` +
  * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
  * This module is the storage seam: a tiny `load / save / clear` interface plus
- * platform factories, so the cold boot (`coldBootV2`) and the unified re-mint
+ * platform factories, so the cold boot (`sessionColdBoot`) and the unified re-mint
  * handler (`refresh.ts`) never touch a platform storage API directly.
  *
  * Platform-agnostic — the native factory takes an INJECTED key/value store
@@ -42,15 +42,21 @@ function deserialize(raw) {
         return null;
     }
     const candidate = parsed;
-    if (typeof candidate.sessionId !== 'string' ||
-        typeof candidate.userId !== 'string' ||
-        candidate.sessionId.length === 0 ||
-        candidate.userId.length === 0) {
+    const hasDeviceCredential = typeof candidate.deviceId === 'string' &&
+        candidate.deviceId.length > 0 &&
+        typeof candidate.deviceSecret === 'string' &&
+        candidate.deviceSecret.length > 0;
+    const hasSessionIdentity = typeof candidate.sessionId === 'string' &&
+        typeof candidate.userId === 'string' &&
+        candidate.sessionId.length > 0 &&
+        candidate.userId.length > 0;
+    // Device-only bootstrap (post join, pre-sign-in): durable credential without session.
+    if (!hasSessionIdentity && !hasDeviceCredential) {
         return null;
     }
     const state = {
-        sessionId: candidate.sessionId,
-        userId: candidate.userId,
+        sessionId: hasSessionIdentity ? candidate.sessionId : '',
+        userId: hasSessionIdentity ? candidate.userId : '',
     };
     if (typeof candidate.deviceId === 'string' && candidate.deviceId.length > 0) {
         state.deviceId = candidate.deviceId;

package/dist/esm/session/hubSync.js

@@ -0,0 +1,51 @@
+/**
+ * Post-sign-in hub sync — plant device credentials on auth.oxy.so via a
+ * one-time server ticket (no secrets in URL fragments).
+ */
+import { buildHubSyncUrl, buildIdpHubOrigin, isIdpHubOrigin, isOfficialWebOrigin, } from '../utils/officialOrigins.js';
+/**
+ * After a successful sign-in on an official web app, mint a hub ticket and
+ * redirect to auth.oxy.so/sync so the IdP hub can redeem it and persist the
+ * shared device credential for silent OAuth restore on other origins.
+ *
+ * No-op on native, non-official origins, and when already on the IdP hub.
+ */
+export async function syncHubAfterSignIn(oxy, opts) {
+    if (opts?.enabled === false) {
+        return false;
+    }
+    if (typeof globalThis === 'undefined') {
+        return false;
+    }
+    const location = globalThis.location;
+    if (!location) {
+        return false;
+    }
+    if (isIdpHubOrigin()) {
+        return false;
+    }
+    if (!isOfficialWebOrigin(location.origin)) {
+        return false;
+    }
+    const hubOrigin = buildIdpHubOrigin();
+    const issued = await oxy.issueHubTicket(hubOrigin);
+    const returnUrl = `${location.origin}${location.pathname}${location.search}`;
+    const syncUrl = buildHubSyncUrl(issued.ticket, returnUrl);
+    window.location.assign(syncUrl);
+    return true;
+}
+/** Redeem a hub ticket on auth.oxy.so and persist credentials locally. */
+export async function redeemHubTicketOnHub(oxy, store, ticket) {
+    const hubOrigin = buildIdpHubOrigin();
+    const creds = await oxy.redeemHubTicket(ticket, hubOrigin);
+    const prior = await store.load();
+    await store.save({
+        sessionId: prior?.sessionId ?? '',
+        userId: prior?.userId ?? '',
+        deviceId: creds.deviceId,
+        deviceSecret: creds.deviceSecret,
+        ...(prior?.accessToken ? { accessToken: prior.accessToken } : {}),
+        ...(prior?.expiresAt ? { expiresAt: prior.expiresAt } : {}),
+    });
+    return true;
+}

package/dist/esm/session/sessionClientHost.js

@@ -12,15 +12,20 @@
  */
 export function createSessionClientHost(oxyServices) {
     let currentAccountId = null;
+    let deviceCredential = null;
     return {
         makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
         getBaseURL: () => oxyServices.getBaseURL(),
         getAccessToken: () => oxyServices.getAccessToken(),
+        getDeviceCredential: () => deviceCredential,
         onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
         setTokens: (accessToken) => oxyServices.setTokens(accessToken),
         getCurrentAccountId: () => currentAccountId,
         setCurrentAccountId: (id) => {
             currentAccountId = id;
         },
+        setDeviceCredential: (credential) => {
+            deviceCredential = credential;
+        },
     };
 }

package/dist/esm/utils/coldBoot.js

@@ -16,7 +16,7 @@
  *     web bundle — the reason any run-once guard for a step must live in the
  *     calling consumer, never in a core module-level singleton).
  *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
- *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
  *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns

package/dist/esm/utils/oauthPkce.js

@@ -131,5 +131,65 @@ export function buildOAuthAuthorizeUrl(params) {
     url.searchParams.set('scope', scope);
     url.searchParams.set('code_challenge', codeChallenge);
     url.searchParams.set('code_challenge_method', 'S256');
+    if (params.prompt) {
+        url.searchParams.set('prompt', params.prompt);
+    }
     return url.toString();
 }
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
+/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
+export const OXY_SILENT_OAUTH_ATTEMPTED_KEY = 'oxy.silent_oauth_attempted';
+/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
+export const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = 'oxy.cross_origin_restore_attempted';
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ */
+export function normalizeOAuthRedirectUri(input) {
+    try {
+        return new URL(input).origin;
+    }
+    catch {
+        return input;
+    }
+}
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export function persistOAuthHandshake(state, codeVerifier) {
+    const store = globalThis.sessionStorage;
+    try {
+        if (!store)
+            throw new Error('sessionStorage is unavailable');
+        store.setItem(OXY_OAUTH_STATE_STORAGE_KEY, state);
+        store.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+        return true;
+    }
+    catch (error) {
+        logger.warn('Could not persist OAuth handshake to sessionStorage', { component: 'oauthPkce' }, error);
+        return false;
+    }
+}
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export function readOAuthHandshake() {
+    const store = globalThis.sessionStorage;
+    if (!store)
+        return null;
+    const state = store.getItem(OXY_OAUTH_STATE_STORAGE_KEY);
+    const codeVerifier = store.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    if (!state || !codeVerifier)
+        return null;
+    return { state, codeVerifier };
+}
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export function clearOAuthHandshake() {
+    const store = globalThis.sessionStorage;
+    try {
+        store?.removeItem(OXY_OAUTH_STATE_STORAGE_KEY);
+        store?.removeItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}