@oxyhq/core 3.4.4 → 3.4.6

package/dist/types/HttpService.d.ts

@@ -172,7 +172,7 @@ export declare class HttpService {
      * Get auth header with automatic token refresh
      */
     private getAuthHeader;
-    private refreshAccessToken;
+    refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
     /**
      * Unwrap standardized API response format
      */

package/dist/types/OxyServices.base.d.ts

@@ -3,6 +3,10 @@ import { HttpService, type RequestOptions } from './HttpService';
 export interface OxyConfig extends OxyConfigBase {
     cloudURL?: string;
 }
+export interface LinkedHttpClient {
+    client: HttpService;
+    dispose(): void;
+}
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -40,6 +44,16 @@ export declare class OxyServicesBase {
      * Useful for advanced use cases where direct access to the HTTP service is needed
      */
     getClient(): HttpService;
+    /**
+     * Create an app/backend HTTP client linked to this Oxy session.
+     *
+     * Use this when an app has its own API origin (for example
+     * `https://api.syra.fm`) but authentication is owned by the canonical
+     * OxyServices instance mounted in OxyProvider. The returned client has its own
+     * base URL, cache and request queue, but its bearer token is kept in lockstep
+     * with this session and its 401 refresh path delegates back to this session.
+     */
+    createLinkedClient(config: OxyConfig): LinkedHttpClient;
     /**
      * Get performance metrics
      */

package/dist/types/OxyServices.d.ts

@@ -56,7 +56,7 @@
  *
  * See method JSDoc for more details and options.
  */
-import { type OxyConfig } from './OxyServices.base';
+import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import type { SessionLoginResponse } from './models/session';
 import type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
@@ -111,6 +111,7 @@ export declare class OxyServices extends OxyServicesComposed {
     constructor(config: OxyConfig);
 }
 export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
+    createLinkedClient(config: OxyConfig): LinkedHttpClient;
     isFedCMSupported(): boolean;
     signInWithFedCM(options?: FedCMAuthOptions): Promise<SessionLoginResponse>;
     silentSignInWithFedCM(): Promise<SessionLoginResponse | null>;

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@
 import './crypto/polyfill';
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
+export type { LinkedHttpClient } from './OxyServices.base';
 export { AuthManager, createAuthManager } from './AuthManager';
 export type { StorageAdapter, AuthStateChangeCallback, AuthMethod, AuthManagerConfig, } from './AuthManager';
 export type { AuthManagerAccount, RestoreFromCookiesResult, RestoreFromCookiesOptions, SwitchAuthuserResult, } from './AuthManagerTypes';
@@ -80,7 +81,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
 export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoNavigate, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { packageInfo } from './constants/version';

package/dist/types/mixins/OxyServices.analytics.d.ts

@@ -27,6 +27,7 @@ export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBa
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.appData.d.ts

@@ -63,6 +63,7 @@ export declare function OxyServicesAppDataMixin<T extends typeof OxyServicesBase
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.applications.d.ts

@@ -371,6 +371,7 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -100,6 +100,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -398,6 +398,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.contacts.d.ts

@@ -55,6 +55,7 @@ export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBas
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -57,6 +57,7 @@ export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.features.d.ts

@@ -184,6 +184,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -259,6 +259,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.language.d.ts

@@ -42,6 +42,7 @@ export declare function OxyServicesLanguageMixin<T extends typeof OxyServicesBas
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.location.d.ts

@@ -25,6 +25,7 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.managedAccounts.d.ts

@@ -82,6 +82,7 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.payment.d.ts

@@ -72,6 +72,7 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.privacy.d.ts

@@ -83,6 +83,7 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.redirect.d.ts

@@ -44,6 +44,7 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.reputation.d.ts

@@ -390,6 +390,7 @@ export declare function OxyServicesReputationMixin<T extends typeof OxyServicesB
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.security.d.ts

@@ -39,6 +39,7 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.silent.d.ts

@@ -82,6 +82,7 @@ export declare function OxyServicesSilentAuthMixin<T extends typeof OxyServicesB
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.sso.d.ts

@@ -64,6 +64,7 @@ export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Ba
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.topics.d.ts

@@ -65,6 +65,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -231,6 +231,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -250,6 +250,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/mixins/OxyServices.workspaces.d.ts

@@ -159,6 +159,7 @@ export declare function OxyServicesWorkspacesMixin<T extends typeof OxyServicesB
         getBaseURL(): string;
         getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
         getMetrics(): {
             totalRequests: number;
             successfulRequests: number;

package/dist/types/utils/ssoBounce.d.ts

@@ -79,6 +79,29 @@ export declare function ssoNoSessionKey(origin: string): string;
  * centrally) can probe again.
  */
 export declare function ssoAttemptedKey(origin: string): string;
+/**
+ * Per-origin marker written by the pre-hydration callback bootstrap.
+ *
+ * Static Expo exports render unknown paths as `+not-found`; on
+ * `/__oxy/sso-callback` that can fail hydration before the React provider has a
+ * chance to run `consumeSsoReturn`. The bootstrap runs in the HTML head, moves
+ * the URL to a hydratable route while preserving the SSO fragment, and writes
+ * this marker so `consumeSsoReturn` still restores the original destination as
+ * if the page were physically on the callback path.
+ */
+export declare function ssoCallbackBootstrapKey(origin: string): string;
+/**
+ * Inline script for Expo/static web apps.
+ *
+ * Must run before the app bundle hydrates. It is intentionally tiny and
+ * dependency-free: if the browser lands on the internal callback route with an
+ * Oxy SSO fragment, it marks the handoff and rewrites the path to `/` while
+ * preserving `#oxy_sso=...`. The normal SDK cold-boot `sso-return` step then
+ * consumes the fragment from a route that can hydrate. If the internal route is
+ * reached without a valid SSO fragment, it leaves the route via a hard root
+ * navigation because there is no session material to preserve.
+ */
+export declare function getSsoCallbackBootstrapScript(): string;
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.4",
+  "version": "3.4.6",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -878,7 +878,7 @@ export class HttpService {
     }
   }
 
-  private async refreshAccessToken(reason: AuthRefreshReason): Promise<string | null> {
+  async refreshAccessToken(reason: AuthRefreshReason): Promise<string | null> {
     if (!this.authRefreshHandler) {
       return null;
     }

package/src/OxyServices.base.ts

@@ -6,7 +6,7 @@
 import { jwtDecode } from 'jwt-decode';
 import type { OxyConfig as OxyConfigBase, ApiError, User } from './models/interfaces';
 import { handleHttpError } from './utils/errorUtils';
-import { HttpService, type RequestOptions } from './HttpService';
+import { HttpService, type AuthRefreshReason, type RequestOptions } from './HttpService';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import { resolveCentralAuthUrl } from './utils/authWebUrl';
 
@@ -14,6 +14,11 @@ export interface OxyConfig extends OxyConfigBase {
   cloudURL?: string;
 }
 
+export interface LinkedHttpClient {
+  client: HttpService;
+  dispose(): void;
+}
+
 interface JwtPayload {
   exp?: number;
   userId?: string;
@@ -116,6 +121,50 @@ export class OxyServicesBase {
     return this.httpService;
   }
 
+  /**
+   * Create an app/backend HTTP client linked to this Oxy session.
+   *
+   * Use this when an app has its own API origin (for example
+   * `https://api.syra.fm`) but authentication is owned by the canonical
+   * OxyServices instance mounted in OxyProvider. The returned client has its own
+   * base URL, cache and request queue, but its bearer token is kept in lockstep
+   * with this session and its 401 refresh path delegates back to this session.
+   */
+  public createLinkedClient(config: OxyConfig): LinkedHttpClient {
+    const client = new HttpService(config);
+
+    const syncToken = (accessToken: string | null): void => {
+      const currentAccessToken = client.getAccessToken();
+      if (accessToken) {
+        if (currentAccessToken !== accessToken) {
+          client.setTokens(accessToken);
+        }
+        return;
+      }
+
+      if (currentAccessToken) {
+        client.clearTokens();
+      }
+    };
+
+    syncToken(this.getAccessToken());
+    const unsubscribe = this.onTokensChanged(syncToken);
+    client.setAuthRefreshHandler(async (reason: AuthRefreshReason) => {
+      const refreshed = await this.httpService.refreshAccessToken(reason);
+      syncToken(refreshed);
+      return refreshed;
+    });
+
+    return {
+      client,
+      dispose: () => {
+        unsubscribe();
+        client.setAuthRefreshHandler(null);
+        client.clearTokens();
+      },
+    };
+  }
+
   /**
    * Get performance metrics
    */

package/src/OxyServices.ts

@@ -56,7 +56,7 @@
  *
  * See method JSDoc for more details and options.
  */
-import { OxyServicesBase, type OxyConfig } from './OxyServices.base';
+import { OxyServicesBase, type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 import type { SessionLoginResponse } from './models/session';
 import type { FedCMAuthOptions, FedCMConfig } from './mixins/OxyServices.fedcm';
@@ -130,6 +130,8 @@ export class OxyServices extends OxyServicesComposed {
 // Explicit declarations are added for cross-domain auth methods that downstream
 // packages (auth-sdk, services) need without casting to `any`.
 export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
+  createLinkedClient(config: OxyConfig): LinkedHttpClient;
+
   // FedCM authentication
   isFedCMSupported(): boolean;
   signInWithFedCM(options?: FedCMAuthOptions): Promise<SessionLoginResponse>;

package/src/__tests__/linkedClient.test.ts

@@ -0,0 +1,64 @@
+import { OxyServices } from '../OxyServices';
+
+function createServices(): OxyServices {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+describe('OxyServices.createLinkedClient', () => {
+  it('mirrors token changes from the session owner', () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    expect(linked.client.getAccessToken()).toBeNull();
+
+    oxy.setTokens('access_1');
+    expect(linked.client.getAccessToken()).toBe('access_1');
+
+    oxy.setTokens('access_2');
+    expect(linked.client.getAccessToken()).toBe('access_2');
+
+    oxy.clearTokens();
+    expect(linked.client.getAccessToken()).toBeNull();
+
+    linked.dispose();
+  });
+
+  it('copies the current token when created after sign-in', () => {
+    const oxy = createServices();
+    oxy.setTokens('existing_access');
+
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    expect(linked.client.getAccessToken()).toBe('existing_access');
+
+    linked.dispose();
+  });
+
+  it('delegates token refresh to the session owner', async () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    oxy.getClient().setAuthRefreshHandler(async () => 'refreshed_access');
+
+    const refreshed = await linked.client.refreshAccessToken('preflight');
+
+    expect(refreshed).toBe('refreshed_access');
+    expect(oxy.getAccessToken()).toBe('refreshed_access');
+    expect(linked.client.getAccessToken()).toBe('refreshed_access');
+
+    linked.dispose();
+  });
+
+  it('stops mirroring after dispose', () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    oxy.setTokens('before_dispose');
+    expect(linked.client.getAccessToken()).toBe('before_dispose');
+
+    linked.dispose();
+    oxy.setTokens('after_dispose');
+
+    expect(linked.client.getAccessToken()).toBeNull();
+  });
+});

package/src/index.ts

@@ -25,6 +25,7 @@ import './crypto/polyfill';
 // ---------------------------------------------------------------------------
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
+export type { LinkedHttpClient } from './OxyServices.base';
 
 // ---------------------------------------------------------------------------
 // Authentication
@@ -458,7 +459,9 @@ export {
     ssoDestKey,
     ssoNoSessionKey,
     ssoAttemptedKey,
+    ssoCallbackBootstrapKey,
     ssoNavigate,
+    getSsoCallbackBootstrapScript,
     buildSsoBounceUrl,
     isCentralIdPOrigin,
     guardActive,

package/src/utils/__tests__/ssoReturn.test.ts

@@ -7,7 +7,42 @@
  * `null` for anything that is not an oxy_sso fragment.
  */
 
-import { parseSsoReturnFragment } from '../ssoReturn';
+import type { SessionLoginResponse } from '../../models/session';
+import { consumeSsoReturn, parseSsoReturnFragment } from '../ssoReturn';
+import {
+  getSsoCallbackBootstrapScript,
+  ssoAttemptedKey,
+  ssoCallbackBootstrapKey,
+  ssoDestKey,
+  ssoNoSessionKey,
+  ssoStateKey,
+} from '../ssoBounce';
+
+class MemorySsoStorage implements Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> {
+  private readonly values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
+}
+
+const ORIGIN = 'https://app.mention.earth';
+
+const exchangedSession: SessionLoginResponse = {
+  sessionId: 'sess_sso',
+  deviceId: 'device_sso',
+  accessToken: 'access_sso',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  user: { id: 'user_sso', username: 'sso-user' },
+};
 
 describe('parseSsoReturnFragment', () => {
   describe('ok', () => {
@@ -118,3 +153,99 @@ describe('parseSsoReturnFragment', () => {
     });
   });
 });
+
+describe('consumeSsoReturn pre-hydration callback bootstrap', () => {
+  it('continues an ok callback after the HTML bootstrap moved the URL to a hydratable route', async () => {
+    const storage = new MemorySsoStorage();
+    const replaceStateCalls: string[] = [];
+    const dispatchPopState = jest.fn();
+    const hardRedirect = jest.fn();
+    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
+
+    storage.setItem(ssoStateKey(ORIGIN), 'state-ok');
+    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/explore?tab=home#top`);
+    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
+
+    const session = await consumeSsoReturn(
+      { exchangeSsoCode },
+      {
+        isWeb: () => true,
+        storage,
+        location: {
+          hash: '#oxy_sso=ok&code=opaque-code&state=state-ok',
+          origin: ORIGIN,
+          pathname: '/',
+          search: '',
+        },
+        history: {
+          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
+            replaceStateCalls.push(String(url ?? ''));
+          },
+        },
+        dispatchPopState,
+        hardRedirect,
+      },
+    );
+
+    expect(session).toBe(exchangedSession);
+    expect(exchangeSsoCode).toHaveBeenCalledWith('opaque-code');
+    expect(replaceStateCalls).toEqual(['/', '/explore?tab=home#top']);
+    expect(dispatchPopState).toHaveBeenCalledTimes(1);
+    expect(hardRedirect).not.toHaveBeenCalled();
+    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBeNull();
+  });
+
+  it('leaves a bootstrapped none callback with loop breakers set and no exchange', async () => {
+    const storage = new MemorySsoStorage();
+    const replaceStateCalls: string[] = [];
+    const dispatchPopState = jest.fn();
+    const hardRedirect = jest.fn();
+    const exchangeSsoCode = jest.fn(async (): Promise<SessionLoginResponse> => exchangedSession);
+
+    storage.setItem(ssoStateKey(ORIGIN), 'state-none');
+    storage.setItem(ssoDestKey(ORIGIN), `${ORIGIN}/library`);
+    storage.setItem(ssoCallbackBootstrapKey(ORIGIN), '1');
+
+    const session = await consumeSsoReturn(
+      { exchangeSsoCode },
+      {
+        isWeb: () => true,
+        storage,
+        location: {
+          hash: '#oxy_sso=none&state=state-none',
+          origin: ORIGIN,
+          pathname: '/',
+          search: '',
+        },
+        history: {
+          replaceState: (_data: unknown, _unused: string, url?: string | URL | null): void => {
+            replaceStateCalls.push(String(url ?? ''));
+          },
+        },
+        dispatchPopState,
+        hardRedirect,
+      },
+    );
+
+    expect(session).toBeNull();
+    expect(exchangeSsoCode).not.toHaveBeenCalled();
+    expect(replaceStateCalls).toEqual(['/']);
+    expect(dispatchPopState).not.toHaveBeenCalled();
+    expect(hardRedirect).toHaveBeenCalledWith(`${ORIGIN}/library`);
+    expect(storage.getItem(ssoCallbackBootstrapKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoDestKey(ORIGIN))).toBeNull();
+    expect(storage.getItem(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.getItem(ssoAttemptedKey(ORIGIN))).toBe('1');
+  });
+
+  it('exposes a pre-hydration script that preserves the SSO fragment', () => {
+    const script = getSsoCallbackBootstrapScript();
+
+    expect(script).toContain('/__oxy/sso-callback');
+    expect(script).toContain('oxy_sso=');
+    expect(script).toContain('window.history.replaceState');
+    expect(script).toContain('window.location.hash');
+  });
+});