@oxyhq/core 2.1.1 → 2.2.0

package/dist/types/OxyServices.d.ts

@@ -126,6 +126,8 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
     openBlankPopup(width?: number, height?: number): Window | null;
     signInWithRedirect(options?: RedirectAuthOptions): void;
     signUpWithRedirect(options?: RedirectAuthOptions): void;
+    exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+    generateSsoState(): string;
     auth(options?: {
         debug?: boolean;
         onError?: (error: unknown) => unknown;

package/dist/types/index.d.ts

@@ -73,6 +73,10 @@ export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, mergeAccountsFromRefreshAll, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 export { autoDetectAuthWebUrl } from './utils/fapiAutoDetect';
+export { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './utils/authWebUrl';
+export { parseSsoReturnFragment } from './utils/ssoReturn';
+export type { SsoReturnKind, SsoReturnResult } from './utils/ssoReturn';
+export { generateSsoState } from './mixins/OxyServices.sso';
 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.assets.d.ts

@@ -132,9 +132,7 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
             maxRetries?: number;
             retryDelay?: number;
-            authTimeoutMs? /**
-             * Get asset metadata
-             */: number;
+            authTimeoutMs?: number;
         }): Promise<T_1>;
         validate(): Promise<boolean>;
         handleError(error: unknown): Error;

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

@@ -0,0 +1,111 @@
+/**
+ * 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 type { OxyServicesBase } from '../OxyServices.base';
+import type { SessionLoginResponse } from '../models/session';
+/**
+ * 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. Reuses the same `crypto.randomUUID`-based generator the popup
+ * mixin uses for its CSRF state, with a `getRandomValues` fallback.
+ */
+export declare function generateSsoState(): string;
+export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Generate cryptographically secure state for the SSO bounce (CSRF
+         * protection). Delegates to the module-level {@link generateSsoState}
+         * helper, which uses the same `crypto.randomUUID`-based generator the popup
+         * mixin's `generateState()` uses — one shared secure-random implementation.
+         */
+        generateSsoState(): string;
+        /**
+         * 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.
+         * @returns The resolved {@link SessionLoginResponse}.
+         */
+        exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getSessionBaseUrl(): string;
+        getClient(): import("../HttpService").HttpService;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string, refreshToken?: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

package/dist/types/mixins/index.d.ts

@@ -9,6 +9,7 @@ import { OxyServicesAuthMixin } from './OxyServices.auth';
 import { OxyServicesFedCMMixin } from './OxyServices.fedcm';
 import { OxyServicesPopupAuthMixin } from './OxyServices.popup';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect';
+import { OxyServicesSsoMixin } from './OxyServices.sso';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
 import { OxyServicesLanguageMixin } from './OxyServices.language';
@@ -35,7 +36,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPopupAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesKarmaMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeveloperMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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

@@ -0,0 +1,31 @@
+/**
+ * Central IdP (auth web) URL resolution for cross-domain SSO.
+ *
+ * The Oxy ecosystem runs a single, central Identity Provider at
+ * `auth.oxy.so`. For TRUE central cross-domain SSO (Google/Meta/Clerk style),
+ * FedCM and the opaque-code SSO bounce always target this one origin — it owns
+ * the host-only `fedcm_session` cookie and the central session store reachable
+ * via `api.oxy.so`. Relying Parties (mention.earth, homiio.com, alia.onl, …)
+ * delegate to it rather than standing up a per-apex IdP.
+ *
+ * This module is intentionally pure: it performs no DOM access, reads no
+ * `window`/`location`, and has no side effects. It is the single source of
+ * truth for the central IdP origin so call sites never hardcode the literal.
+ *
+ * Note: this is distinct from `autoDetectAuthWebUrl` (per-apex `auth.<rp-apex>`
+ * derivation). The central-SSO path deliberately does NOT auto-detect per-apex
+ * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
+ */
+/**
+ * The canonical central Identity Provider origin for the Oxy ecosystem.
+ * No trailing slash.
+ */
+export declare const CENTRAL_AUTH_URL = "https://auth.oxy.so";
+/**
+ * Resolve the central IdP origin, honouring an explicit override.
+ *
+ * @param explicit - A caller-supplied auth web URL, or `undefined`/empty to use
+ *   the central default. An explicit non-empty value always wins.
+ * @returns The explicit value when provided, otherwise {@link CENTRAL_AUTH_URL}.
+ */
+export declare function resolveCentralAuthUrl(explicit?: string): string;

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

@@ -0,0 +1,46 @@
+/**
+ * Parse the SSO return fragment delivered by the central IdP.
+ *
+ * After a top-level redirect bounce to `auth.oxy.so/sso` (prompt=none), the
+ * central IdP returns the Relying Party to its `redirect_uri` with the result
+ * encoded in the URL fragment (the `#…` part). The fragment is used — not a
+ * query string — so the opaque single-use code never reaches a server access
+ * log, a `Referer` header, or browser history in a recoverable form.
+ *
+ * Three outcomes are possible:
+ *   - `#oxy_sso=ok&code=<opaque>&state=<state>` — the IdP had a session; the RP
+ *     exchanges `code` (via `oxy.exchangeSsoCode`) for the real session. NO
+ *     token/JWT ever appears in the URL — only the opaque code.
+ *   - `#oxy_sso=none&state=<state>` — the IdP had no session (prompt=none, user
+ *     not signed in centrally). The RP shows its own signed-out UI.
+ *   - `#oxy_sso=error&state=<state>` — the bounce failed. The RP recovers.
+ *
+ * This parser is pure and defensive: it never throws, and `kind` is strictly
+ * one of `'ok' | 'none' | 'error'`. It returns `null` when the fragment is not
+ * an oxy_sso fragment at all (i.e. `oxy_sso` is absent or an unrecognised
+ * value), so the caller can ignore unrelated fragments without special-casing.
+ */
+/**
+ * The recognised outcomes of an SSO bounce.
+ */
+export type SsoReturnKind = 'ok' | 'none' | 'error';
+/**
+ * The parsed result of an SSO return fragment.
+ *
+ * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
+ * generated for the bounce (when the IdP round-tripped it).
+ */
+export interface SsoReturnResult {
+    kind: SsoReturnKind;
+    code?: string;
+    state?: string;
+}
+/**
+ * Parse an SSO return fragment.
+ *
+ * @param hash - The URL fragment, with or without the leading `#`
+ *   (e.g. `location.hash`). May be `undefined`/empty.
+ * @returns The parsed result when `hash` is a recognised oxy_sso fragment,
+ *   otherwise `null`. Never throws.
+ */
+export declare function parseSsoReturnFragment(hash: string | undefined | null): SsoReturnResult | null;

package/package.json

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

package/src/OxyServices.base.ts

@@ -8,6 +8,7 @@ import type { OxyConfig as OxyConfigBase, ApiError, User } from './models/interf
 import { handleHttpError } from './utils/errorUtils';
 import { HttpService, type RequestOptions } from './HttpService';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+import { resolveCentralAuthUrl } from './utils/authWebUrl';
 
 export interface OxyConfig extends OxyConfigBase {
   cloudURL?: string;
@@ -34,11 +35,24 @@ export class OxyServicesBase {
     if (!config || typeof config !== 'object') {
       throw new Error('OxyConfig is required');
     }
-    this.config = config;
-    this.cloudURL = config.cloudURL || 'https://cloud.oxy.so';
+
+    // 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: OxyConfig = config.authWebUrl
+      ? config
+      : { ...config, authWebUrl: resolveCentralAuthUrl(config.authWebUrl) };
+
+    this.config = resolvedConfig;
+    this.cloudURL = resolvedConfig.cloudURL || 'https://cloud.oxy.so';
 
     // Initialize unified HTTP service (handles auth, caching, deduplication, queuing, retry)
-    this.httpService = new HttpService(config);
+    this.httpService = new HttpService(resolvedConfig);
   }
 
   // Test-only utility to reset tokens on this instance between jest tests

package/src/OxyServices.ts

@@ -151,6 +151,10 @@ export interface OxyServices extends InstanceType<ReturnType<typeof composeOxySe
   signInWithRedirect(options?: RedirectAuthOptions): void;
   signUpWithRedirect(options?: RedirectAuthOptions): void;
 
+  // Central cross-domain SSO (opaque single-use code exchange)
+  exchangeSsoCode(code: string): Promise<SessionLoginResponse>;
+  generateSsoState(): string;
+
   // Express.js middleware
   auth(options?: {
     debug?: boolean;

package/src/index.ts

@@ -369,6 +369,13 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // Cross-domain SSO infrastructure
 // ---------------------------------------------------------------------------
 export { autoDetectAuthWebUrl } from './utils/fapiAutoDetect';
+
+// Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
+export { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './utils/authWebUrl';
+export { parseSsoReturnFragment } from './utils/ssoReturn';
+export type { SsoReturnKind, SsoReturnResult } from './utils/ssoReturn';
+export { generateSsoState } from './mixins/OxyServices.sso';
+
 export { runColdBoot } from './utils/coldBoot';
 export type {
     ColdBootStep,

package/src/mixins/OxyServices.sso.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 type { OxyServicesBase } from '../OxyServices.base';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
+import { createDebugLogger } from '../shared/utils/debugUtils';
+
+const debug = createDebugLogger('SSO');
+
+/**
+ * Wire shape of `POST /sso/exchange`. `expiresAt` and `authuser` are optional
+ * (the central store may omit them for legacy single-slot sessions).
+ */
+interface SsoExchangeWireResponse {
+  accessToken: string;
+  sessionId: string;
+  user: {
+    id?: string;
+    _id?: string;
+    username?: string;
+    avatar?: string;
+  };
+  expiresAt?: string;
+  authuser?: number;
+}
+
+/**
+ * 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. Reuses the same `crypto.randomUUID`-based generator the popup
+ * mixin uses for its CSRF state, with a `getRandomValues` fallback.
+ */
+export function generateSsoState(): string {
+  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');
+}
+
+export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Generate cryptographically secure state for the SSO bounce (CSRF
+     * protection). Delegates to the module-level {@link generateSsoState}
+     * helper, which uses the same `crypto.randomUUID`-based generator the popup
+     * mixin's `generateState()` uses — one shared secure-random implementation.
+     */
+    public generateSsoState(): string {
+      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.
+     * @returns The resolved {@link SessionLoginResponse}.
+     */
+    public async exchangeSsoCode(code: string): Promise<SessionLoginResponse> {
+      if (typeof code !== 'string' || code.length === 0) {
+        throw this.handleError(new Error('exchangeSsoCode requires a non-empty code'));
+      }
+
+      const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/sso/exchange`;
+      debug.log('Exchanging SSO code for session...');
+
+      let response: 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: SsoExchangeWireResponse;
+      try {
+        payload = (await response.json()) as SsoExchangeWireResponse;
+      } 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: MinimalUserData = {
+        id: userId,
+        username: payload.user.username,
+        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: SessionLoginResponse = {
+        sessionId: payload.sessionId,
+        deviceId: '',
+        expiresAt: payload.expiresAt ?? '',
+        user,
+        accessToken: payload.accessToken,
+      };
+
+      return session;
+    }
+  };
+}

package/src/mixins/__tests__/constructorAuthWebUrl.test.ts

@@ -0,0 +1,85 @@
+/**
+ * `OxyServices` constructor central-IdP defaulting.
+ *
+ * TRUE central cross-domain SSO (Google/Meta/Clerk style, 2026-06-13) routes
+ * every Relying Party through ONE central IdP at `auth.oxy.so` — it owns the
+ * host-only `fedcm_session` cookie and the central session store. The SDK
+ * therefore defaults `authWebUrl` to the central IdP when the caller omits it,
+ * via `resolveCentralAuthUrl(config.authWebUrl)`.
+ *
+ * This replaces the previous behaviour, where the constructor auto-detected a
+ * per-apex IdP (`auth.<rp-apex>`) from `window.location`. `autoDetectAuthWebUrl`
+ * is still exported for call sites that opt into per-apex resolution, but it is
+ * NO LONGER the constructor default.
+ *
+ * Contract:
+ *   - authWebUrl omitted, no window (native/SSR) -> 'https://auth.oxy.so'
+ *   - authWebUrl omitted, window present         -> 'https://auth.oxy.so'
+ *     (the page host is irrelevant — central only)
+ *   - authWebUrl explicit                        -> respected verbatim (wins)
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { CENTRAL_AUTH_URL } from '../../utils/authWebUrl';
+
+function installWindowLocation(hostname: string, protocol = 'https:'): void {
+  (globalThis as unknown as { window: unknown }).window = {
+    location: { hostname, protocol },
+  };
+}
+
+function clearWindow(): void {
+  delete (globalThis as Record<string, unknown>).window;
+}
+
+describe('OxyServices constructor — central IdP defaulting', () => {
+  afterEach(() => {
+    clearWindow();
+  });
+
+  it('defaults authWebUrl to the central IdP on native/SSR (no window)', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    expect(oxy.config.authWebUrl).toBe(CENTRAL_AUTH_URL);
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
+  });
+
+  it('defaults to the central IdP on web regardless of page host', () => {
+    // The page is mention.earth, but central SSO never derives a per-apex IdP.
+    installWindowLocation('mention.earth');
+
+    const oxy = new OxyServices({ baseURL: 'https://api.mention.earth' });
+
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
+  });
+
+  it('defaults to the central IdP even on a subdomain page host', () => {
+    installWindowLocation('www.homiio.com');
+
+    const oxy = new OxyServices({ baseURL: 'https://api.homiio.com' });
+
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
+  });
+
+  it('respects an explicit authWebUrl (explicit wins)', () => {
+    installWindowLocation('mention.earth');
+
+    const oxy = new OxyServices({
+      baseURL: 'https://api.mention.earth',
+      authWebUrl: 'https://auth.mention.earth',
+    });
+
+    // The caller pinned a per-apex IdP explicitly — honour it verbatim.
+    expect(oxy.config.authWebUrl).toBe('https://auth.mention.earth');
+  });
+
+  it('does not mutate the caller-supplied config object', () => {
+    const input = { baseURL: 'https://api.mention.earth' };
+    const oxy = new OxyServices(input);
+
+    // The stored config carries the central IdP default...
+    expect(oxy.config.authWebUrl).toBe('https://auth.oxy.so');
+    // ...but the caller's own object reference is untouched.
+    expect((input as { authWebUrl?: string }).authWebUrl).toBeUndefined();
+  });
+});