@oxyhq/core 1.11.24 → 2.0.0

package/dist/esm/i18n/locales/pt-PT.json

@@ -114,6 +114,89 @@
             "email": "Email",
             "password": "Palavra-passe",
             "confirmPassword": "Confirmar palavra-passe"
+        },
+        "revoke": "Revoke"
+    },
+    "notifications": {
+        "title": "Notifications",
+        "subtitle": "Manage push, email, and security alerts",
+        "updateError": "Failed to update notification preferences",
+        "sections": {
+            "channels": "Channels",
+            "alerts": "Alerts",
+            "marketing": "Marketing"
+        },
+        "items": {
+            "push": {
+                "title": "Push notifications",
+                "subtitle": "Real-time alerts on your devices"
+            },
+            "emailDigest": {
+                "title": "Email digest",
+                "subtitle": "Periodic summary of your account activity"
+            },
+            "securityAlerts": {
+                "title": "Security alerts",
+                "subtitle": "Sign-ins, recovery codes, and key changes"
+            },
+            "marketingEmails": {
+                "title": "Marketing emails",
+                "subtitle": "Product news and occasional offers"
+            }
+        }
+    },
+    "preferences": {
+        "title": "Preferences",
+        "subtitle": "Theme, motion, and regional settings",
+        "sections": {
+            "appearance": "Appearance",
+            "language": "Language",
+            "region": "Region"
+        },
+        "theme": {
+            "light": "Light",
+            "dark": "Dark",
+            "system": "System default"
+        },
+        "items": {
+            "theme": {
+                "title": "Theme"
+            },
+            "reduceMotion": {
+                "title": "Reduce motion",
+                "subtitle": "Minimise animations across Oxy apps",
+                "systemOn": "Following system: reduce motion is on"
+            },
+            "language": {
+                "title": "Language"
+            },
+            "timezone": {
+                "title": "Timezone",
+                "unknown": "Unable to detect timezone"
+            },
+            "about": {
+                "title": "About preferences",
+                "subtitle": "Preferences sync across every Oxy app you sign into"
+            }
+        }
+    },
+    "connectedApps": {
+        "title": "Connected apps",
+        "subtitle": "Manage third-party app access",
+        "empty": {
+            "title": "No connected apps",
+            "subtitle": "Apps you authorize to sign in with your Oxy account will appear here"
+        },
+        "item": {
+            "lastUsed": "Last used {{relative}}"
+        },
+        "confirm": {
+            "title": "Revoke access",
+            "message": "Revoke {{name}}'s access to your Oxy account?"
+        },
+        "toasts": {
+            "revoked": "Revoked access for {{name}}",
+            "revokeFailed": "Failed to revoke access"
         }
     }
 }

package/dist/esm/i18n/locales/zh-CN.json

@@ -114,6 +114,89 @@
             "email": "电子邮件",
             "password": "密码",
             "confirmPassword": "确认密码"
+        },
+        "revoke": "Revoke"
+    },
+    "notifications": {
+        "title": "Notifications",
+        "subtitle": "Manage push, email, and security alerts",
+        "updateError": "Failed to update notification preferences",
+        "sections": {
+            "channels": "Channels",
+            "alerts": "Alerts",
+            "marketing": "Marketing"
+        },
+        "items": {
+            "push": {
+                "title": "Push notifications",
+                "subtitle": "Real-time alerts on your devices"
+            },
+            "emailDigest": {
+                "title": "Email digest",
+                "subtitle": "Periodic summary of your account activity"
+            },
+            "securityAlerts": {
+                "title": "Security alerts",
+                "subtitle": "Sign-ins, recovery codes, and key changes"
+            },
+            "marketingEmails": {
+                "title": "Marketing emails",
+                "subtitle": "Product news and occasional offers"
+            }
+        }
+    },
+    "preferences": {
+        "title": "Preferences",
+        "subtitle": "Theme, motion, and regional settings",
+        "sections": {
+            "appearance": "Appearance",
+            "language": "Language",
+            "region": "Region"
+        },
+        "theme": {
+            "light": "Light",
+            "dark": "Dark",
+            "system": "System default"
+        },
+        "items": {
+            "theme": {
+                "title": "Theme"
+            },
+            "reduceMotion": {
+                "title": "Reduce motion",
+                "subtitle": "Minimise animations across Oxy apps",
+                "systemOn": "Following system: reduce motion is on"
+            },
+            "language": {
+                "title": "Language"
+            },
+            "timezone": {
+                "title": "Timezone",
+                "unknown": "Unable to detect timezone"
+            },
+            "about": {
+                "title": "About preferences",
+                "subtitle": "Preferences sync across every Oxy app you sign into"
+            }
+        }
+    },
+    "connectedApps": {
+        "title": "Connected apps",
+        "subtitle": "Manage third-party app access",
+        "empty": {
+            "title": "No connected apps",
+            "subtitle": "Apps you authorize to sign in with your Oxy account will appear here"
+        },
+        "item": {
+            "lastUsed": "Last used {{relative}}"
+        },
+        "confirm": {
+            "title": "Revoke access",
+            "message": "Revoke {{name}}'s access to your Oxy account?"
+        },
+        "toasts": {
+            "revoked": "Revoked access for {{name}}",
+            "revokeFailed": "Failed to revoke access"
         }
     }
 }

package/dist/esm/index.js

@@ -12,53 +12,96 @@
  *
  * const user = await oxyClient.signIn(publicKey);
  * ```
+ *
+ * Every export below is NOMINAL — no `export *`, no barrels, no compat shims.
+ * If a symbol does not appear here, it is NOT part of the public API.
  */
 // Ensure crypto polyfills are loaded before anything else
 import './crypto/polyfill.js';
-// --- Core API Client ---
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.js';
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices.js';
-// --- Authentication ---
+// ---------------------------------------------------------------------------
+// Authentication
+// ---------------------------------------------------------------------------
 export { AuthManager, createAuthManager } from './AuthManager.js';
 export { CrossDomainAuth, createCrossDomainAuth } from './CrossDomainAuth.js';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth.js';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
-// --- Crypto / Identity ---
-export { KeyManager, SignatureService, RecoveryPhraseService, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/index.js';
-// --- Models & Types ---
-export * from './models/interfaces.js';
-export * from './models/session.js';
-export { TopicType, TopicSource } from './models/Topic.js';
-// --- Device Management ---
+// ---------------------------------------------------------------------------
+// Auth helpers (token refresh, error normalisation, retry policies)
+// ---------------------------------------------------------------------------
+export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers.js';
+// ---------------------------------------------------------------------------
+// Sessions
+// ---------------------------------------------------------------------------
+export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils.js';
+// ---------------------------------------------------------------------------
+// Crypto / identity
+// ---------------------------------------------------------------------------
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/keyManager.js';
+export { SignatureService } from './crypto/signatureService.js';
+export { RecoveryPhraseService } from './crypto/recoveryPhrase.js';
+// ---------------------------------------------------------------------------
+// Devices
+// ---------------------------------------------------------------------------
 export { DeviceManager } from './utils/deviceManager.js';
-// --- Language Utilities ---
+export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces.js';
+// Topic enums + type
+export { TopicType, TopicSource } from './models/Topic.js';
+// ---------------------------------------------------------------------------
+// Languages
+// ---------------------------------------------------------------------------
 export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode, isRTLLocale, } from './utils/languageUtils.js';
-// --- Platform Detection ---
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
 export { getPlatformOS, setPlatformOS, isWeb, isNative, isIOS, isAndroid, } from './utils/platform.js';
-// --- Shared Utilities ---
+// ---------------------------------------------------------------------------
+// Colour / theme utilities
+// ---------------------------------------------------------------------------
 export { darkenColor, lightenColor, hexToRgb, rgbToHex, withOpacity, isLightColor, getContrastTextColor, } from './shared/utils/colorUtils.js';
 export { normalizeTheme, normalizeColorScheme, getOppositeTheme, systemPrefersDarkMode, getSystemColorScheme, } from './shared/utils/themeUtils.js';
+// ---------------------------------------------------------------------------
+// HTTP / error / network helpers
+// ---------------------------------------------------------------------------
 export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError, isUnauthorizedError, isForbiddenError, isNotFoundError, isRateLimitError, isServerError, isNetworkError, isRetryableError, } from './shared/utils/errorUtils.js';
 export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils.js';
 export { isDev, debugLog, debugWarn, debugError, createDebugLogger, } from './shared/utils/debugUtils.js';
-// --- i18n ---
+// ---------------------------------------------------------------------------
+// i18n
+// ---------------------------------------------------------------------------
 export { translate } from './i18n/index.js';
-// --- Auth Helpers ---
-export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken, isAuthenticationError, withAuthErrorHandling, authenticatedApiCall, } from './utils/authHelpers.js';
-// --- Session Utilities ---
-export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual } from './utils/sessionUtils.js';
-// --- Constants ---
-export { packageInfo } from './constants/version.js';
-// --- API & Error Utilities ---
-export * from './utils/apiUtils.js';
+// ---------------------------------------------------------------------------
+// API request / URL helpers
+// ---------------------------------------------------------------------------
+export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils.js';
 export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils.js';
 export { retryAsync } from './utils/asyncUtils.js';
-export * from './utils/validationUtils.js';
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils.js';
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
 export { logger, LogLevel, logAuth, logApi, logSession, logUser, logDevice, logPayment, logPerformance, } from './utils/loggerUtils.js';
-// --- Avatar Utilities ---
+// ---------------------------------------------------------------------------
+// Avatars
+// ---------------------------------------------------------------------------
 export { updateAvatarVisibility } from './utils/avatarUtils.js';
-// --- Account Utilities ---
-export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, } from './utils/accountUtils.js';
-// Default export
+// ---------------------------------------------------------------------------
+// Accounts
+// ---------------------------------------------------------------------------
+export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, mergeAccountsFromRefreshAll, getAccountColor, } from './utils/accountUtils.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export { packageInfo } from './constants/version.js';
+// ---------------------------------------------------------------------------
+// Default export (back-compat — OxyServices is the most common consumer entry)
+// ---------------------------------------------------------------------------
 import { OxyServices } from './OxyServices.js';
 export default OxyServices;

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

@@ -380,6 +380,241 @@ export function OxyServicesAuthMixin(Base) {
                 throw this.handleError(error);
             }
         }
+        /**
+         * Refresh every device-local refresh-cookie slot in a single round trip
+         * (Google-style multi-account rebuild).
+         *
+         * Calls `POST {sessionBaseUrl}/auth/refresh-all` with `credentials: 'include'`
+         * and NO bearer. The browser attaches every `oxy_rt*` cookie it has; the
+         * server rotates each in parallel and returns one entry per VALID account.
+         *
+         * Failure handling:
+         * - 401 → no signed-in accounts on this device → returns `{ accounts: [] }`
+         *   (NOT an error; this is the cold-boot "not signed in" path).
+         * - 404 → server is older than the multi-account endpoint. We fall back to
+         *   `POST /auth/refresh` (single-slot) and wrap its response in the
+         *   refresh-all shape so callers can treat the two paths uniformly. The
+         *   fallback entry has `authuser: 0` (the legacy slot maps to slot 0 by
+         *   convention) and a minimal `user` shape — consumers needing the full
+         *   user must fetch it separately. Always exactly one account in this
+         *   shape.
+         * - Any other non-2xx → throws via `handleError`.
+         *
+         * The refresh cookie itself never enters JS — only the rotated access
+         * tokens do. Each access token still needs to be planted via
+         * `setTokens(...)` (or per-account in-memory storage) at the consumer.
+         */
+        async refreshAllSessions() {
+            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/refresh-all`;
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { Accept: 'application/json' },
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+            if (response.status === 401) {
+                return { accounts: [] };
+            }
+            if (response.status === 404) {
+                // Legacy single-account refresh fallback. Wrap the response so the
+                // caller can treat both paths identically.
+                const legacy = await this._refreshCookieRaw();
+                if (!legacy) {
+                    return { accounts: [] };
+                }
+                const fallbackAccount = {
+                    authuser: 0,
+                    accessToken: legacy.accessToken,
+                    expiresAt: legacy.expiresAt,
+                    sessionId: this._decodeSessionIdFromAccessToken(legacy.accessToken) ?? '',
+                    // Legacy /auth/refresh does NOT project the user shape; the caller
+                    // (AuthManager) is expected to hydrate via /users/me after planting.
+                    user: null,
+                };
+                return { accounts: [fallbackAccount] };
+            }
+            if (!response.ok) {
+                throw this.handleError(new Error(`Refresh-all failed with HTTP ${response.status}`));
+            }
+            const payload = (await response.json());
+            const raw = Array.isArray(payload.accounts) ? payload.accounts : [];
+            const accounts = [];
+            for (const entry of raw) {
+                if (entry === null || typeof entry !== 'object') {
+                    continue;
+                }
+                const e = entry;
+                if (!e.accessToken || !e.expiresAt || !e.sessionId || !e.user) {
+                    continue;
+                }
+                const userId = e.user.id ?? e.user._id;
+                if (!userId || !e.user.username) {
+                    continue;
+                }
+                // Normalise the legacy un-suffixed cookie (`authuser: null` on the
+                // wire) to slot 0. The SDK surface always operates on numeric indices.
+                const authuser = typeof e.authuser === 'number' ? e.authuser : 0;
+                accounts.push({
+                    authuser,
+                    accessToken: e.accessToken,
+                    expiresAt: e.expiresAt,
+                    sessionId: e.sessionId,
+                    user: {
+                        id: userId,
+                        username: e.user.username,
+                        name: e.user.name,
+                        avatar: e.user.avatar ?? null,
+                        email: e.user.email,
+                        color: e.user.color ?? null,
+                    },
+                });
+            }
+            return { accounts };
+        }
+        /**
+         * Rotate a single refresh-cookie slot and return the fresh access token.
+         *
+         * When `authuser` is provided, the server rotates ONLY that slot
+         * (`oxy_rt_${authuser}`) — sibling accounts on the same device stay
+         * untouched. When omitted, the server picks the lowest indexed slot
+         * present (legacy fallback applies). The refresh cookie itself never
+         * enters JS.
+         *
+         * Returns `null` on 401 (no cookie / expired / reused) so the caller can
+         * fall through cleanly to the unauthenticated path.
+         */
+        async refreshTokenViaCookie(opts = {}) {
+            const result = await this._refreshCookieRaw(opts.authuser);
+            return result;
+        }
+        /**
+         * Sign out a single device-local account by its authuser slot index.
+         *
+         * Revokes that slot's refresh-token family and deactivates its session;
+         * sibling indexed slots stay signed in. The browser-side `oxy_rt_${n}`
+         * cookie is cleared by the server's `Set-Cookie` response header.
+         */
+        async logoutSessionByAuthuser(authuser) {
+            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout?authuser=${encodeURIComponent(String(authuser))}`;
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { Accept: 'application/json' },
+                });
+                if (!response.ok && response.status !== 401) {
+                    throw new Error(`Logout (authuser=${authuser}) failed with HTTP ${response.status}`);
+                }
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Sign out EVERY device-local account on this device by clearing every
+         * presented refresh-cookie slot at once. Revokes every family + clears
+         * every slot. Always succeeds (idempotent on unknown/garbage tokens).
+         */
+        async logoutAllSessionsViaCookie() {
+            const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/auth/logout`;
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { Accept: 'application/json' },
+                });
+                if (!response.ok && response.status !== 401) {
+                    throw new Error(`Logout-all failed with HTTP ${response.status}`);
+                }
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Internal: raw `POST /auth/refresh[?authuser=N]` call returning the
+         * minted access token. Returns `null` on 401 / non-2xx. Used as both the
+         * implementation of `refreshTokenViaCookie` and the legacy fallback for
+         * `refreshAllSessions` against older servers.
+         *
+         * @internal
+         */
+        async _refreshCookieRaw(authuser) {
+            const base = this.getSessionBaseUrl().replace(/\/$/, '');
+            const url = typeof authuser === 'number'
+                ? `${base}/auth/refresh?authuser=${encodeURIComponent(String(authuser))}`
+                : `${base}/auth/refresh`;
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { Accept: 'application/json' },
+                });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+            if (!response.ok) {
+                return null;
+            }
+            const payload = (await response.json());
+            if (typeof payload.accessToken !== 'string' || !payload.accessToken) {
+                return null;
+            }
+            const expiresAt = typeof payload.expiresAt === 'string' ? payload.expiresAt : '';
+            const respAuthuser = typeof payload.authuser === 'number' ? payload.authuser : null;
+            return {
+                accessToken: payload.accessToken,
+                expiresAt,
+                authuser: respAuthuser,
+            };
+        }
+        /**
+         * Internal: decode (without verifying) the `sessionId` claim from a
+         * server-signed access token. The server already verified the signature;
+         * the client only reads the claim to drive multi-session state.
+         *
+         * @internal
+         */
+        _decodeSessionIdFromAccessToken(token) {
+            if (!token || typeof token !== 'string') {
+                return null;
+            }
+            const segments = token.split('.');
+            if (segments.length !== 3) {
+                return null;
+            }
+            const payloadSegment = segments[1];
+            if (!payloadSegment) {
+                return null;
+            }
+            try {
+                const base64 = payloadSegment.replace(/-/g, '+').replace(/_/g, '/');
+                const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+                if (typeof atob !== 'function') {
+                    return null;
+                }
+                const json = decodeURIComponent(atob(padded)
+                    .split('')
+                    .map((char) => `%${`00${char.charCodeAt(0).toString(16)}`.slice(-2)}`)
+                    .join(''));
+                const parsed = JSON.parse(json);
+                if (parsed === null || typeof parsed !== 'object') {
+                    return null;
+                }
+                const claims = parsed;
+                return typeof claims.sessionId === 'string' ? claims.sessionId : null;
+            }
+            catch {
+                return null;
+            }
+        }
         /**
          * Get sessions by session ID
          */

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

@@ -697,6 +697,42 @@ export function OxyServicesFedCMMixin(Base) {
                     // Storage blocked
                 }
             }
+            /**
+             * List the authenticated user's authorized RP apps.
+             *
+             * Returns the intersection of the user's FedCM grants and the currently-
+             * approved RP catalog — what powers the "Connected apps" management UI in
+             * @oxyhq/services. Requires a real user session; service tokens are
+             * rejected by the underlying endpoint.
+             */
+            async listAuthorizedApps() {
+                try {
+                    const response = await this.makeRequest('GET', '/fedcm/me/authorized-apps', undefined, {
+                        cache: true,
+                        cacheTTL: 30 * 1000, // 30 second cache — short, this drives a manageable UI
+                    });
+                    return response.apps ?? [];
+                }
+                catch (error) {
+                    throw this.handleError(error);
+                }
+            }
+            /**
+             * Revoke the authenticated user's authorization for a specific RP origin.
+             *
+             * The next FedCM sign-in from that origin will require explicit re-consent.
+             * The corresponding cache entry is invalidated so a subsequent
+             * `listAuthorizedApps()` call sees fresh data.
+             */
+            async revokeAuthorizedApp(origin) {
+                try {
+                    await this.makeRequest('DELETE', `/fedcm/me/authorized-apps/${encodeURIComponent(origin)}`, undefined, { cache: false });
+                    this.clearCacheEntry('GET:/fedcm/me/authorized-apps');
+                }
+                catch (error) {
+                    throw this.handleError(error);
+                }
+            }
         },
         _a.DEFAULT_CONFIG_URL = 'https://auth.oxy.so/fedcm.json',
         _a.FEDCM_TIMEOUT = 15000 // 15 seconds for interactive

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

@@ -77,7 +77,37 @@ export function OxyServicesPopupAuthMixin(Base) {
                     clientId: window.location.origin,
                     redirectUri: `${this.resolveAuthUrl()}/auth/callback`,
                 });
-                const popup = this.openCenteredPopup(authUrl, 'Oxy Sign In', width, height);
+                // If the caller pre-opened a popup on the raw user gesture (recommended
+                // path — see `openBlankPopup` and `PopupAuthOptions.popup`), navigate it
+                // to the auth URL instead of issuing a fresh `window.open` (which would
+                // be blocked once any prior `await` has consumed the user activation).
+                let popup;
+                const preOpened = options.popup ?? null;
+                if (preOpened) {
+                    if (preOpened.closed) {
+                        // The pre-opened popup is gone — distinguish a user cancel (they
+                        // closed the blank window before sign-in could navigate it) from a
+                        // blocker rejection. Lumping these together as "Popup blocked" is
+                        // misleading: the popup was NOT blocked, it was opened successfully
+                        // and then dismissed.
+                        throw new OxyAuthenticationError('Sign-in window was closed before authentication could start.');
+                    }
+                    try {
+                        preOpened.location.replace(authUrl);
+                    }
+                    catch (replaceError) {
+                        // `location.replace` can throw in sandboxed / cross-origin-locked
+                        // environments. Fall back to `href` assignment, which is more
+                        // permissive. Logged at debug-level so consumers can correlate
+                        // unusual sign-in behaviour without producing noise in normal flows.
+                        debug.warn('location.replace failed, falling back to location.href', replaceError);
+                        preOpened.location.href = authUrl;
+                    }
+                    popup = preOpened;
+                }
+                else {
+                    popup = this.openCenteredPopup(authUrl, 'Oxy Sign In', width, height);
+                }
                 if (!popup) {
                     throw new OxyAuthenticationError('Popup blocked. Please allow popups for this site and try again.');
                 }
@@ -220,6 +250,36 @@ export function OxyServicesPopupAuthMixin(Base) {
                     document.body.removeChild(iframe);
                 }
             }
+            /**
+             * Open a blank, centered popup window SYNCHRONOUSLY.
+             *
+             * Use this in a click (or other user-gesture) handler BEFORE any `await`
+             * to capture the transient user-activation. Pass the returned handle into
+             * `signInWithPopup({ popup })` once the async portion of the flow runs.
+             *
+             * Returns `null` if the browser's popup blocker rejected the open.
+             *
+             * @example
+             * ```typescript
+             * const onSignInClick = () => {
+             *   const popup = oxyServices.openBlankPopup();
+             *   (async () => {
+             *     const silent = await oxyServices.silentSignInWithFedCM();
+             *     if (silent) { popup?.close(); return; }
+             *     await oxyServices.signInWithPopup({ popup });
+             *   })();
+             * };
+             * ```
+             */
+            openBlankPopup(width, height) {
+                if (typeof window === 'undefined') {
+                    return null;
+                }
+                const ctor = this.constructor;
+                const w = width ?? ctor.POPUP_WIDTH;
+                const h = height ?? ctor.POPUP_HEIGHT;
+                return this.openCenteredPopup('about:blank', 'Oxy Sign In', w, h);
+            }
             /**
              * Open a centered popup window
              *