@oxyhq/core 2.1.1 → 2.2.0

package/dist/esm/OxyServices.base.js

@@ -7,6 +7,7 @@ import { jwtDecode } from 'jwt-decode';
 import { handleHttpError } from './utils/errorUtils.js';
 import { HttpService } from './HttpService.js';
 import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors.js';
+import { resolveCentralAuthUrl } from './utils/authWebUrl.js';
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -18,10 +19,21 @@ 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 = 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
     // Note: tokens are now per-instance, so create new instances in tests for isolation

package/dist/esm/index.js

@@ -100,6 +100,10 @@ export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccou
 // Cross-domain SSO infrastructure
 // ---------------------------------------------------------------------------
 export { autoDetectAuthWebUrl } from './utils/fapiAutoDetect.js';
+// Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
+export { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './utils/authWebUrl.js';
+export { parseSsoReturnFragment } from './utils/ssoReturn.js';
+export { generateSsoState } from './mixins/OxyServices.sso.js';
 export { runColdBoot } from './utils/coldBoot.js';
 // ---------------------------------------------------------------------------
 // Constants

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

@@ -0,0 +1,138 @@
+/**
+ * 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 { createDebugLogger } from '../shared/utils/debugUtils.js';
+const debug = createDebugLogger('SSO');
+/**
+ * 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() {
+    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(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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() {
+            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}.
+         */
+        async exchangeSsoCode(code) {
+            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;
+            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;
+            try {
+                payload = (await response.json());
+            }
+            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 = {
+                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 = {
+                sessionId: payload.sessionId,
+                deviceId: '',
+                expiresAt: payload.expiresAt ?? '',
+                user,
+                accessToken: payload.accessToken,
+            };
+            return session;
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -9,6 +9,7 @@ import { OxyServicesAuthMixin } from './OxyServices.auth.js';
 import { OxyServicesFedCMMixin } from './OxyServices.fedcm.js';
 import { OxyServicesPopupAuthMixin } from './OxyServices.popup.js';
 import { OxyServicesRedirectAuthMixin } from './OxyServices.redirect.js';
+import { OxyServicesSsoMixin } from './OxyServices.sso.js';
 import { OxyServicesUserMixin } from './OxyServices.user.js';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy.js';
 import { OxyServicesLanguageMixin } from './OxyServices.language.js';
@@ -48,6 +49,9 @@ const MIXIN_PIPELINE = [
     OxyServicesFedCMMixin,
     OxyServicesPopupAuthMixin,
     OxyServicesRedirectAuthMixin,
+    // Central cross-domain SSO (opaque-code exchange). After Popup so it can
+    // reuse the popup mixin's secure-random `generateState()`.
+    OxyServicesSsoMixin,
     // User management (requires auth)
     OxyServicesUserMixin,
     OxyServicesPrivacyMixin,

package/dist/esm/utils/authWebUrl.js

@@ -0,0 +1,33 @@
+/**
+ * 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 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 function resolveCentralAuthUrl(explicit) {
+    return explicit ?? CENTRAL_AUTH_URL;
+}

package/dist/esm/utils/ssoReturn.js

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+const VALID_KINDS = new Set(['ok', 'none', 'error']);
+/**
+ * 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 function parseSsoReturnFragment(hash) {
+    if (typeof hash !== 'string' || hash.length === 0) {
+        return null;
+    }
+    // Strip a single leading '#'. A bare '#' (empty fragment) yields no params.
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (raw.length === 0) {
+        return null;
+    }
+    let params;
+    try {
+        params = new URLSearchParams(raw);
+    }
+    catch {
+        // URLSearchParams does not throw for malformed input in practice, but guard
+        // against any environment/polyfill that might so this stays total.
+        return null;
+    }
+    const kind = params.get('oxy_sso');
+    if (kind === null || !VALID_KINDS.has(kind)) {
+        // Not an oxy_sso fragment (absent or unrecognised value) — ignore it.
+        return null;
+    }
+    const result = { kind: kind };
+    const state = params.get('state');
+    if (state !== null && state.length > 0) {
+        result.state = state;
+    }
+    // The opaque code is only meaningful on success; ignore any stray `code` on
+    // none/error so callers never attempt an exchange for a non-ok outcome.
+    if (result.kind === 'ok') {
+        const code = params.get('code');
+        if (code !== null && code.length > 0) {
+            result.code = code;
+        }
+    }
+    return result;
+}