@auth0/auth0-spa-js 2.14.0 → 2.16.0

package/dist/typings/Auth0Client.d.ts

@@ -9,6 +9,7 @@ import { MfaApiClient } from './mfa';
 export declare class Auth0Client {
     private readonly transactionManager;
     private readonly cacheManager;
+    private readonly lockManager;
     private readonly domainUrl;
     private readonly tokenIssuer;
     private readonly scope;
@@ -33,7 +34,6 @@ export declare class Auth0Client {
      */
     readonly mfa: MfaApiClient;
     private worker?;
-    private readonly activeLockKeys;
     private readonly authJsClient;
     private readonly defaultOptions;
     constructor(options: Auth0ClientOptions);
@@ -185,6 +185,16 @@ export declare class Auth0Client {
      */
     getTokenSilently(options?: GetTokenSilentlyOptions): Promise<string>;
     private _getTokenSilently;
+    /**
+     * Checks if an error should be handled by the interactive error handler.
+     * Currently only handles mfa_required; extensible for future error types.
+     */
+    private _isInteractiveError;
+    /**
+     * Handles MFA errors by opening a popup to complete authentication,
+     * then reads the resulting token from cache.
+     */
+    private _handleInteractiveErrorWithPopup;
     /**
      * ```js
      * const token = await auth0.getTokenWithPopup(options);
@@ -236,13 +246,6 @@ export declare class Auth0Client {
     private _saveEntryInCache;
     private _getIdTokenFromCache;
     private _getEntryFromCache;
-    /**
-     * Releases any locks acquired by the current page that are not released yet
-     *
-     * Get's called on the `pagehide` event.
-     * https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
-     */
-    private _releaseLockOnPageHide;
     private _requestToken;
     /**
      * ```js

package/dist/typings/cache/cache-manager.d.ts

@@ -43,10 +43,14 @@ export declare class CacheManager {
      */
     private getEntryWithRefreshToken;
     /**
-     * Updates in the cache all entries that has a match with previous refresh_token with the
-     * new refresh_token obtained from the server
-     * @param oldRefreshToken Old refresh_token used on refresh
-     * @param newRefreshToken New refresh_token obtained from the server after refresh
-    */
+     * Updates the refresh token in all cache entries that contain the old refresh token.
+     *
+     * When a refresh token is rotated, multiple cache entries (for different audiences/scopes)
+     * may share the same refresh token. This method propagates the new refresh token to all
+     * matching entries.
+     *
+     * @param oldRefreshToken The refresh token that was used and is now invalid
+     * @param newRefreshToken The new refresh token received from the server
+     */
     updateEntry(oldRefreshToken: string, newRefreshToken: string): Promise<void>;
 }

package/dist/typings/global.d.ts

@@ -1,6 +1,12 @@
 import { ICache } from './cache';
 import type { Dpop } from './dpop/dpop';
 import { CompleteResponse } from './MyAccountApiClient';
+/**
+ * Configuration option for automatic interactive error handling.
+ *
+ * - `'popup'`: SDK automatically opens Universal Login popup on MFA error
+ */
+export type InteractiveErrorHandler = 'popup';
 export interface AuthorizationParams {
     /**
      * - `'page'`: displays the UI with a full page view
@@ -262,6 +268,21 @@ export interface Auth0ClientOptions {
      * The default setting is `false`.
      */
     useDpop?: boolean;
+    /**
+     * Configures automatic handling of interactive authentication errors.
+     *
+     * When set, the SDK intercepts `mfa_required` errors from `getTokenSilently()`
+     * and handles them automatically instead of throwing to the caller.
+     *
+     * - `'popup'`: Opens Universal Login in a popup to complete MFA.
+     *   The original `authorizationParams` (audience, scope) are preserved.
+     *   On success, the token is returned. On failure, popup errors are thrown.
+     *
+     * This option only affects `getTokenSilently()`. Other methods are not affected.
+     *
+     * @default undefined (MFA errors are thrown to the caller)
+     */
+    interactiveErrorHandler?: InteractiveErrorHandler;
     /**
      * URL parameters that will be sent back to the Authorization Server. This can be known parameters
      * defined by Auth0 or custom parameters that you define.

package/dist/typings/lock.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lock manager abstraction for cross-tab synchronization.
+ * Supports both modern Web Locks API and legacy localStorage-based locking.
+ */
+/** Lock manager interface - callback pattern ensures automatic lock release */
+export interface ILockManager {
+    /**
+     * Run callback while holding a lock.
+     * Lock is automatically released when callback completes or throws.
+     *
+     * @param key - Lock identifier
+     * @param timeout - Maximum time to wait for lock acquisition (ms)
+     * @param callback - Function to execute while holding the lock
+     * @returns Promise resolving to callback's return value
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    runWithLock<T>(key: string, timeout: number, callback: () => Promise<T>): Promise<T>;
+}
+/** Web Locks API implementation - true mutex with OS-level queuing */
+export declare class WebLocksApiManager implements ILockManager {
+    runWithLock<T>(key: string, timeout: number, callback: () => Promise<T>): Promise<T>;
+}
+/** Legacy localStorage-based locking with retry logic for older browsers */
+export declare class LegacyLockManager implements ILockManager {
+    private lock;
+    private activeLocks;
+    private pagehideHandler;
+    constructor();
+    runWithLock<T>(key: string, timeout: number, callback: () => Promise<T>): Promise<T>;
+}
+export declare function getLockManager(): ILockManager;
+export declare function resetLockManager(): void;

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.14.0";
+declare const _default: "2.16.0";
 export default _default;

package/package.json

@@ -3,7 +3,7 @@
   "name": "@auth0/auth0-spa-js",
   "description": "Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE",
   "license": "MIT",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",

package/src/Auth0Client.ts

@@ -1,5 +1,3 @@
-import Lock from 'browser-tabs-lock';
-
 import {
   createQueryParams,
   runPopup,
@@ -17,6 +15,8 @@ import {
   stripAuth0Client
 } from './utils';
 
+import { getLockManager, type ILockManager } from './lock';
+
 import { oauthToken } from './api';
 
 import { injectDefaultScopes, scopesToRequest } from './scope';
@@ -131,17 +131,13 @@ type GetTokenSilentlyResult = TokenEndpointResponse & {
   audience: string;
 };
 
-/**
- * @ignore
- */
-const lock = new Lock();
-
 /**
  * Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
  */
 export class Auth0Client {
   private readonly transactionManager: TransactionManager;
   private readonly cacheManager: CacheManager;
+  private readonly lockManager: ILockManager;
   private readonly domainUrl: string;
   private readonly tokenIssuer: string;
   private readonly scope: Record<string, string>;
@@ -170,7 +166,6 @@ export class Auth0Client {
   public readonly mfa: MfaApiClient;
 
   private worker?: Worker;
-  private readonly activeLockKeys: Set<string> = new Set();
   private readonly authJsClient: Auth0AuthJsClient;
 
   private readonly defaultOptions: Partial<Auth0ClientOptions> = {
@@ -193,6 +188,8 @@ export class Auth0Client {
 
     typeof window !== 'undefined' && validateCrypto();
 
+    this.lockManager = getLockManager();
+
     if (options.cache && options.cacheLocation) {
       console.warn(
         'Both `cache` and `cacheLocation` options have been specified in the Auth0Client configuration; ignoring `cacheLocation` and using `cache`.'
@@ -886,20 +883,15 @@ export class Auth0Client {
       getTokenOptions.authorizationParams.audience || 'default'
     );
 
-    if (await retryPromise(() => lock.acquireLock(lockKey, 5000), 10)) {
-      this.activeLockKeys.add(lockKey);
-
-      // Add event listener only if this is the first active lock
-      if (this.activeLockKeys.size === 1) {
-        window.addEventListener('pagehide', this._releaseLockOnPageHide);
-      }
-      try {
+    try {
+      return await this.lockManager.runWithLock(lockKey, 5000, async () => {
         // Check the cache a second time, because it may have been populated
         // by a previous call while this call was waiting to acquire the lock.
         if (cacheMode !== 'off') {
           const entry = await this._getEntryFromCache({
             scope: getTokenOptions.authorizationParams.scope,
-            audience: getTokenOptions.authorizationParams.audience || DEFAULT_AUDIENCE,
+            audience:
+              getTokenOptions.authorizationParams.audience || DEFAULT_AUDIENCE,
             clientId: this.options.clientId
           });
 
@@ -912,13 +904,8 @@ export class Auth0Client {
           ? await this._getTokenUsingRefreshToken(getTokenOptions)
           : await this._getTokenFromIFrame(getTokenOptions);
 
-        const {
-          id_token,
-          token_type,
-          access_token,
-          oauthTokenScope,
-          expires_in
-        } = authResult;
+        const { id_token, token_type, access_token, oauthTokenScope, expires_in } =
+          authResult;
 
         return {
           id_token,
@@ -927,16 +914,60 @@ export class Auth0Client {
           ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
           expires_in
         };
-      } finally {
-        await lock.releaseLock(lockKey);
-        this.activeLockKeys.delete(lockKey);
-        // If we have no more locks, we can remove the event listener to clean up
-        if (this.activeLockKeys.size === 0) {
-          window.removeEventListener('pagehide', this._releaseLockOnPageHide);
-        }
+      });
+    } catch (error) {
+      // Lock is already released - safe to open popup
+      if (this._isInteractiveError(error) && this.options.interactiveErrorHandler === 'popup') {
+        return await this._handleInteractiveErrorWithPopup(getTokenOptions);
       }
-    } else {
-      throw new TimeoutError();
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if an error should be handled by the interactive error handler.
+   * Currently only handles mfa_required; extensible for future error types.
+   */
+  private _isInteractiveError(error: unknown): error is MfaRequiredError {
+    return error instanceof MfaRequiredError;
+  }
+
+  /**
+   * Handles MFA errors by opening a popup to complete authentication,
+   * then reads the resulting token from cache.
+   */
+  private async _handleInteractiveErrorWithPopup(
+    options: GetTokenSilentlyOptions & {
+      authorizationParams: AuthorizationParams & { scope: string };
+    }
+  ): Promise<GetTokenSilentlyVerboseResponse> {
+    try {
+      await this.loginWithPopup({
+        authorizationParams: options.authorizationParams
+      });
+
+      const entry = await this._getEntryFromCache({
+        scope: options.authorizationParams.scope,
+        audience:
+          options.authorizationParams.audience || DEFAULT_AUDIENCE,
+        clientId: this.options.clientId
+      });
+
+      if (!entry) {
+        throw new GenericError(
+          'interactive_handler_cache_miss',
+          'Token not found in cache after interactive authentication'
+        );
+      }
+
+      return entry;
+    } catch (error) {
+      // Expected errors (all GenericError subclasses):
+      // - PopupCancelledError: user closed the popup before completing login
+      // - PopupTimeoutError: popup did not complete within the allowed time
+      // - PopupOpenError: popup could not be opened (e.g. blocked by browser)
+      // - GenericError: authentication or cache miss errors
+      throw error;
     }
   }
 
@@ -1088,93 +1119,99 @@ export class Auth0Client {
     // relies on the same transaction context as a top-level `loginWithRedirect`.
     // To resolve that, we add a second-level locking that locks only the iframe calls in
     // the same way as was done before https://github.com/auth0/auth0-spa-js/pull/1408.
-    if (await retryPromise(() => lock.acquireLock(iframeLockKey, 5000), 10)) {
-      try {
-        const params: AuthorizationParams & { scope: string } = {
-          ...options.authorizationParams,
-          prompt: 'none'
-        };
-
-        const orgHint = this.cookieStorage.get<string>(this.orgHintCookieName);
+    try {
+      return await this.lockManager.runWithLock(
+        iframeLockKey,
+        5000,
+        async () => {
+          const params: AuthorizationParams & { scope: string } = {
+            ...options.authorizationParams,
+            prompt: 'none'
+          };
 
-        if (orgHint && !params.organization) {
-          params.organization = orgHint;
-        }
+          const orgHint = this.cookieStorage.get<string>(
+            this.orgHintCookieName
+          );
 
-        const {
-          url,
-          state: stateIn,
-          nonce: nonceIn,
-          code_verifier,
-          redirect_uri,
-          scope,
-          audience
-        } = await this._prepareAuthorizeUrl(
-          params,
-          { response_mode: 'web_message' },
-          window.location.origin
-        );
+          if (orgHint && !params.organization) {
+            params.organization = orgHint;
+          }
 
-        // When a browser is running in a Cross-Origin Isolated context, using iframes is not possible.
-        // It doesn't throw an error but times out instead, so we should exit early and inform the user about the reason.
-        // https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
-        if ((window as any).crossOriginIsolated) {
-          throw new GenericError(
-            'login_required',
-            'The application is running in a Cross-Origin Isolated context, silently retrieving a token without refresh token is not possible.'
+          const {
+            url,
+            state: stateIn,
+            nonce: nonceIn,
+            code_verifier,
+            redirect_uri,
+            scope,
+            audience
+          } = await this._prepareAuthorizeUrl(
+            params,
+            { response_mode: 'web_message' },
+            window.location.origin
           );
-        }
 
-        const authorizeTimeout =
-          options.timeoutInSeconds || this.options.authorizeTimeoutInSeconds;
+          // When a browser is running in a Cross-Origin Isolated context, using iframes is not possible.
+          // It doesn't throw an error but times out instead, so we should exit early and inform the user about the reason.
+          // https://developer.mozilla.org/en-US/docs/Web/API/crossOriginIsolated
+          if ((window as any).crossOriginIsolated) {
+            throw new GenericError(
+              'login_required',
+              'The application is running in a Cross-Origin Isolated context, silently retrieving a token without refresh token is not possible.'
+            );
+          }
 
-        // Extract origin from domainUrl, fallback to domainUrl if URL parsing fails
-        let eventOrigin: string;
-        try {
-          eventOrigin = new URL(this.domainUrl).origin;
-        } catch {
-          eventOrigin = this.domainUrl;
-        }
+          const authorizeTimeout =
+            options.timeoutInSeconds || this.options.authorizeTimeoutInSeconds;
 
-        const codeResult = await runIframe(url, eventOrigin, authorizeTimeout);
+          // Extract origin from domainUrl, fallback to domainUrl if URL parsing fails
+          let eventOrigin: string;
+          try {
+            eventOrigin = new URL(this.domainUrl).origin;
+          } catch {
+            eventOrigin = this.domainUrl;
+          }
 
-        if (stateIn !== codeResult.state) {
-          throw new GenericError('state_mismatch', 'Invalid state');
-        }
+          const codeResult = await runIframe(
+            url,
+            eventOrigin,
+            authorizeTimeout
+          );
 
-        const tokenResult = await this._requestToken(
-          {
-            ...options.authorizationParams,
-            code_verifier,
-            code: codeResult.code as string,
-            grant_type: 'authorization_code',
-            redirect_uri,
-            timeout: options.authorizationParams.timeout || this.httpTimeoutMs
-          },
-          {
-            nonceIn,
-            organization: params.organization
+          if (stateIn !== codeResult.state) {
+            throw new GenericError('state_mismatch', 'Invalid state');
           }
-        );
 
-        return {
-          ...tokenResult,
-          scope: scope,
-          oauthTokenScope: tokenResult.scope,
-          audience: audience
-        };
-      } catch (e) {
-        if (e.error === 'login_required') {
-          this.logout({
-            openUrl: false
-          });
+          const tokenResult = await this._requestToken(
+            {
+              ...options.authorizationParams,
+              code_verifier,
+              code: codeResult.code as string,
+              grant_type: 'authorization_code',
+              redirect_uri,
+              timeout: options.authorizationParams.timeout || this.httpTimeoutMs
+            },
+            {
+              nonceIn,
+              organization: params.organization
+            }
+          );
+
+          return {
+            ...tokenResult,
+            scope: scope,
+            oauthTokenScope: tokenResult.scope,
+            audience: audience
+          };
         }
-        throw e;
-      } finally {
-        await lock.releaseLock(iframeLockKey);
+      );
+    } catch (e) {
+      if (e.error === 'login_required') {
+        this.logout({
+          openUrl: false
+        });
       }
-    } else {
-      throw new TimeoutError();
+      throw e;
     }
   }
 
@@ -1413,23 +1450,6 @@ export class Auth0Client {
     }
   }
 
-  /**
-   * Releases any locks acquired by the current page that are not released yet
-   *
-   * Get's called on the `pagehide` event.
-   * https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event
-   */
-  private _releaseLockOnPageHide = async () => {
-    // Release all active locks
-    const lockKeysToRelease = Array.from(this.activeLockKeys);
-    for (const lockKey of lockKeysToRelease) {
-      await lock.releaseLock(lockKey);
-    }
-    this.activeLockKeys.clear();
-
-    window.removeEventListener('pagehide', this._releaseLockOnPageHide);
-  };
-
   private async _requestToken(
     options:
       | PKCERequestTokenOptions

package/src/cache/cache-manager.ts

@@ -270,11 +270,15 @@ export class CacheManager {
   }
 
   /**
-   * Updates in the cache all entries that has a match with previous refresh_token with the
-   * new refresh_token obtained from the server
-   * @param oldRefreshToken Old refresh_token used on refresh
-   * @param newRefreshToken New refresh_token obtained from the server after refresh
-  */
+   * Updates the refresh token in all cache entries that contain the old refresh token.
+   *
+   * When a refresh token is rotated, multiple cache entries (for different audiences/scopes)
+   * may share the same refresh token. This method propagates the new refresh token to all
+   * matching entries.
+   *
+   * @param oldRefreshToken The refresh token that was used and is now invalid
+   * @param newRefreshToken The new refresh token received from the server
+   */
   async updateEntry(
     oldRefreshToken: string,
     newRefreshToken: string,
@@ -287,12 +291,8 @@ export class CacheManager {
       const entry = await this.cache.get<WrappedCacheEntry>(key);
 
       if (entry?.body?.refresh_token === oldRefreshToken) {
-        const cacheEntry = {
-          ...entry.body,
-          refresh_token: newRefreshToken,
-        } as CacheEntry;
-
-        await this.set(cacheEntry);
+        entry.body.refresh_token = newRefreshToken;
+        await this.cache.set(key, entry);
       }
     }
   }

package/src/global.ts

@@ -2,6 +2,13 @@ import { ICache } from './cache';
 import type { Dpop } from './dpop/dpop';
 import { CompleteResponse } from './MyAccountApiClient';
 
+/**
+ * Configuration option for automatic interactive error handling.
+ *
+ * - `'popup'`: SDK automatically opens Universal Login popup on MFA error
+ */
+export type InteractiveErrorHandler = 'popup';
+
 export interface AuthorizationParams {
   /**
    * - `'page'`: displays the UI with a full page view
@@ -296,6 +303,21 @@ export interface Auth0ClientOptions {
    */
   useDpop?: boolean;
 
+  /**
+   * Configures automatic handling of interactive authentication errors.
+   *
+   * When set, the SDK intercepts `mfa_required` errors from `getTokenSilently()`
+   * and handles them automatically instead of throwing to the caller.
+   *
+   * - `'popup'`: Opens Universal Login in a popup to complete MFA.
+   *   The original `authorizationParams` (audience, scope) are preserved.
+   *   On success, the token is returned. On failure, popup errors are thrown.
+   *
+   * This option only affects `getTokenSilently()`. Other methods are not affected.
+   *
+   * @default undefined (MFA errors are thrown to the caller)
+   */
+  interactiveErrorHandler?: InteractiveErrorHandler;
 
   /**
    * URL parameters that will be sent back to the Authorization Server. This can be known parameters