@oxyhq/core 2.1.1 → 2.2.0

package/dist/cjs/OxyServices.base.js

@@ -10,6 +10,7 @@ const jwt_decode_1 = require("jwt-decode");
 const errorUtils_1 = require("./utils/errorUtils");
 const HttpService_1 = require("./HttpService");
 const OxyServices_errors_1 = require("./OxyServices.errors");
+const authWebUrl_1 = require("./utils/authWebUrl");
 /**
  * Base class for OxyServices with core infrastructure
  */
@@ -21,10 +22,21 @@ 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: (0, authWebUrl_1.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_1.HttpService(config);
+        this.httpService = new HttpService_1.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/cjs/index.js

@@ -20,7 +20,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.isRTLLocale = exports.normalizeLanguageCode = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.RecoveryPhraseService = exports.SignatureService = exports.IdentityPersistError = exports.IdentityAlreadyExistsError = exports.KeyManager = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.OxyAppDataIdentifierError = exports.ServiceCredentialMismatchError = exports.createCrossDomainAuth = exports.CrossDomainAuth = exports.createAuthManager = exports.AuthManager = exports.oxyClient = exports.OXY_CLOUD_URL = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyServices = void 0;
 exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.PASSWORD_REGEX = exports.USERNAME_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.translate = exports.createDebugLogger = exports.debugError = exports.debugWarn = exports.debugLog = exports.isDev = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = void 0;
-exports.packageInfo = exports.runColdBoot = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = void 0;
+exports.packageInfo = exports.runColdBoot = exports.generateSsoState = exports.parseSsoReturnFragment = exports.resolveCentralAuthUrl = exports.CENTRAL_AUTH_URL = exports.autoDetectAuthWebUrl = exports.getAccountColor = exports.mergeAccountsFromRefreshAll = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.logPerformance = exports.logPayment = exports.logDevice = exports.logUser = exports.logSession = exports.logApi = exports.logAuth = exports.LogLevel = exports.logger = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -230,6 +230,14 @@ Object.defineProperty(exports, "getAccountColor", { enumerable: true, get: funct
 // ---------------------------------------------------------------------------
 var fapiAutoDetect_1 = require("./utils/fapiAutoDetect");
 Object.defineProperty(exports, "autoDetectAuthWebUrl", { enumerable: true, get: function () { return fapiAutoDetect_1.autoDetectAuthWebUrl; } });
+// Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
+var authWebUrl_1 = require("./utils/authWebUrl");
+Object.defineProperty(exports, "CENTRAL_AUTH_URL", { enumerable: true, get: function () { return authWebUrl_1.CENTRAL_AUTH_URL; } });
+Object.defineProperty(exports, "resolveCentralAuthUrl", { enumerable: true, get: function () { return authWebUrl_1.resolveCentralAuthUrl; } });
+var ssoReturn_1 = require("./utils/ssoReturn");
+Object.defineProperty(exports, "parseSsoReturnFragment", { enumerable: true, get: function () { return ssoReturn_1.parseSsoReturnFragment; } });
+var OxyServices_sso_1 = require("./mixins/OxyServices.sso");
+Object.defineProperty(exports, "generateSsoState", { enumerable: true, get: function () { return OxyServices_sso_1.generateSsoState; } });
 var coldBoot_1 = require("./utils/coldBoot");
 Object.defineProperty(exports, "runColdBoot", { enumerable: true, get: function () { return coldBoot_1.runColdBoot; } });
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSsoState = generateSsoState;
+exports.OxyServicesSsoMixin = OxyServicesSsoMixin;
+const debugUtils_1 = require("../shared/utils/debugUtils");
+const debug = (0, debugUtils_1.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.
+ */
+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');
+}
+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/cjs/mixins/index.js

@@ -13,6 +13,7 @@ const OxyServices_auth_1 = require("./OxyServices.auth");
 const OxyServices_fedcm_1 = require("./OxyServices.fedcm");
 const OxyServices_popup_1 = require("./OxyServices.popup");
 const OxyServices_redirect_1 = require("./OxyServices.redirect");
+const OxyServices_sso_1 = require("./OxyServices.sso");
 const OxyServices_user_1 = require("./OxyServices.user");
 const OxyServices_privacy_1 = require("./OxyServices.privacy");
 const OxyServices_language_1 = require("./OxyServices.language");
@@ -52,6 +53,9 @@ const MIXIN_PIPELINE = [
     OxyServices_fedcm_1.OxyServicesFedCMMixin,
     OxyServices_popup_1.OxyServicesPopupAuthMixin,
     OxyServices_redirect_1.OxyServicesRedirectAuthMixin,
+    // Central cross-domain SSO (opaque-code exchange). After Popup so it can
+    // reuse the popup mixin's secure-random `generateState()`.
+    OxyServices_sso_1.OxyServicesSsoMixin,
     // User management (requires auth)
     OxyServices_user_1.OxyServicesUserMixin,
     OxyServices_privacy_1.OxyServicesPrivacyMixin,

package/dist/cjs/utils/authWebUrl.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CENTRAL_AUTH_URL = void 0;
+exports.resolveCentralAuthUrl = resolveCentralAuthUrl;
+/**
+ * The canonical central Identity Provider origin for the Oxy ecosystem.
+ * No trailing slash.
+ */
+exports.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}.
+ */
+function resolveCentralAuthUrl(explicit) {
+    return explicit ?? exports.CENTRAL_AUTH_URL;
+}

package/dist/cjs/utils/ssoReturn.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSsoReturnFragment = parseSsoReturnFragment;
+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.
+ */
+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;
+}