@oxyhq/core 2.1.2 → 2.2.1

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.popup.d.ts

@@ -25,6 +25,25 @@ export interface PopupAuthOptions {
 }
 export interface SilentAuthOptions {
     timeout?: number;
+    /**
+     * Override the auth-web (IdP) origin used for the silent iframe, instead of
+     * the instance's configured `resolveAuthUrl()`.
+     *
+     * Why this exists: an instance configured with the CENTRAL IdP
+     * (`authWebUrl=https://auth.oxy.so`, for the opaque-code `/sso` bounce and
+     * FedCM) cannot read the DURABLE per-apex `fedcm_session` cookie via the
+     * central host — that cookie is first-party only on `auth.<rp-apex>` (e.g.
+     * `auth.mention.earth`). The cross-domain reload-restore path must point the
+     * `/auth/silent` iframe at the PER-APEX host so the cookie is same-site to
+     * the RP page (first-party under Safari ITP / Firefox TCP) and the restore
+     * is NOT a top-level navigation (no flash, works in a backgrounded tab).
+     *
+     * When provided this value is used BOTH for the iframe `src` AND for the
+     * `postMessage` origin validation in {@link waitForIframeAuth}, so the
+     * security check still matches the exact origin the iframe was loaded from.
+     * Must be an absolute origin (`https://auth.<apex>`); ignored if empty.
+     */
+    authWebUrlOverride?: string;
 }
 /**
  * Popup-based Cross-Domain Authentication Mixin

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.2",
+  "version": "2.2.1",
   "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,7 +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 { autoDetectAuthWebUrl } from './utils/fapiAutoDetect';
+import { resolveCentralAuthUrl } from './utils/authWebUrl';
 
 export interface OxyConfig extends OxyConfigBase {
   cloudURL?: string;
@@ -36,18 +36,17 @@ export class OxyServicesBase {
       throw new Error('OxyConfig is required');
     }
 
-    // Auto-detect the first-party IdP (`auth.<rp-apex>`) when the caller did not
-    // pin `authWebUrl` explicitly. This mirrors the provider-`baseURL` path in
-    // `@oxyhq/services` (OxyContext), so apps that construct their OWN
-    // `OxyServices` instance and pass it to `<OxyProvider oxyServices={...} />`
-    // get the same same-site IdP resolution. On web at `https://mention.earth`
-    // this yields `https://auth.mention.earth`; on native/SSR (no `window`)
-    // `autoDetectAuthWebUrl()` returns `undefined`, leaving the auth mixins'
-    // `DEFAULT_AUTH_URL` fallback in effect — native behavior is unchanged.
+    // 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: autoDetectAuthWebUrl() };
+      : { ...config, authWebUrl: resolveCentralAuthUrl(config.authWebUrl) };
 
     this.config = resolvedConfig;
     this.cloudURL = resolvedConfig.cloudURL || 'https://cloud.oxy.so';

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.popup.ts

@@ -31,6 +31,25 @@ export interface PopupAuthOptions {
 
 export interface SilentAuthOptions {
   timeout?: number;
+  /**
+   * Override the auth-web (IdP) origin used for the silent iframe, instead of
+   * the instance's configured `resolveAuthUrl()`.
+   *
+   * Why this exists: an instance configured with the CENTRAL IdP
+   * (`authWebUrl=https://auth.oxy.so`, for the opaque-code `/sso` bounce and
+   * FedCM) cannot read the DURABLE per-apex `fedcm_session` cookie via the
+   * central host — that cookie is first-party only on `auth.<rp-apex>` (e.g.
+   * `auth.mention.earth`). The cross-domain reload-restore path must point the
+   * `/auth/silent` iframe at the PER-APEX host so the cookie is same-site to
+   * the RP page (first-party under Safari ITP / Firefox TCP) and the restore
+   * is NOT a top-level navigation (no flash, works in a backgrounded tab).
+   *
+   * When provided this value is used BOTH for the iframe `src` AND for the
+   * `postMessage` origin validation in {@link waitForIframeAuth}, so the
+   * security check still matches the exact origin the iframe was loaded from.
+   * Must be an absolute origin (`https://auth.<apex>`); ignored if empty.
+   */
+  authWebUrlOverride?: string;
 }
 
 /**
@@ -244,6 +263,16 @@ export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base
     const nonce = this.generateNonce();
     const clientId = window.location.origin;
 
+    // Resolve the IdP origin for the iframe. An explicit per-apex override (the
+    // durable cross-domain reload path — see `SilentAuthOptions.authWebUrlOverride`)
+    // wins over the instance's configured central auth URL. The SAME origin is
+    // handed to `waitForIframeAuth` so the postMessage origin check matches the
+    // exact host the iframe was loaded from.
+    const authOrigin =
+      options.authWebUrlOverride && options.authWebUrlOverride.length > 0
+        ? options.authWebUrlOverride
+        : this.resolveAuthUrl();
+
     const iframe = document.createElement('iframe');
     iframe.style.display = 'none';
     iframe.style.position = 'absolute';
@@ -251,13 +280,13 @@ export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base
     iframe.style.height = '0';
     iframe.style.border = 'none';
 
-    const silentUrl = `${this.resolveAuthUrl()}/auth/silent?` + `client_id=${encodeURIComponent(clientId)}&` + `nonce=${nonce}`;
+    const silentUrl = `${authOrigin}/auth/silent?` + `client_id=${encodeURIComponent(clientId)}&` + `nonce=${nonce}`;
 
     iframe.src = silentUrl;
     document.body.appendChild(iframe);
 
     try {
-      const session = await this.waitForIframeAuth(iframe, timeout, clientId);
+      const session = await this.waitForIframeAuth(iframe, timeout, authOrigin);
 
       // Bail early on incomplete responses. The iframe contract requires
       // both an access token and a session id; anything less is unusable.
@@ -475,8 +504,11 @@ export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base
       }, timeout);
 
       const messageHandler = (event: MessageEvent) => {
-        // Verify origin
-        if (event.origin !== this.resolveAuthUrl()) {
+        // Verify origin against the EXACT host the iframe was loaded from
+        // (`expectedOrigin`). For the per-apex durable-restore path this is
+        // `auth.<rp-apex>`, not the instance's central `resolveAuthUrl()` — so
+        // we must honour the caller-supplied origin, never re-derive it here.
+        if (event.origin !== expectedOrigin) {
           return;
         }
 

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;
+    }
+  };
+}