@auth0/auth0-spa-js 2.14.0 → 2.15.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);
@@ -236,13 +236,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/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.15.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.15.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,58 +883,37 @@ export class Auth0Client {
       getTokenOptions.authorizationParams.audience || 'default'
     );
 
-    if (await retryPromise(() => lock.acquireLock(lockKey, 5000), 10)) {
-      this.activeLockKeys.add(lockKey);
+    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,
+          clientId: this.options.clientId
+        });
 
-      // Add event listener only if this is the first active lock
-      if (this.activeLockKeys.size === 1) {
-        window.addEventListener('pagehide', this._releaseLockOnPageHide);
-      }
-      try {
-        // 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,
-            clientId: this.options.clientId
-          });
-
-          if (entry) {
-            return entry;
-          }
+        if (entry) {
+          return entry;
         }
+      }
 
-        const authResult = this.options.useRefreshTokens
-          ? await this._getTokenUsingRefreshToken(getTokenOptions)
-          : await this._getTokenFromIFrame(getTokenOptions);
+      const authResult = this.options.useRefreshTokens
+        ? 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,
-          token_type,
-          access_token,
-          ...(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);
-        }
-      }
-    } else {
-      throw new TimeoutError();
-    }
+      return {
+        id_token,
+        token_type,
+        access_token,
+        ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
+        expires_in
+      };
+    });
   }
 
   /**
@@ -1088,93 +1064,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 +1395,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/lock.ts

@@ -0,0 +1,141 @@
+import BrowserTabsLock from 'browser-tabs-lock';
+import { TimeoutError } from './errors';
+
+/**
+ * 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 class WebLocksApiManager implements ILockManager {
+  async runWithLock<T>(
+    key: string,
+    timeout: number,
+    callback: () => Promise<T>
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    try {
+      return await navigator.locks.request(
+        key,
+        { mode: 'exclusive', signal: controller.signal },
+        async lock => {
+          clearTimeout(timeoutId);
+          if (!lock) throw new Error('Lock not available');
+          return await callback();
+        }
+      );
+    } catch (error: any) {
+      clearTimeout(timeoutId);
+      if (error?.name === 'AbortError') throw new TimeoutError();
+      throw error;
+    }
+  }
+}
+
+/** Legacy localStorage-based locking with retry logic for older browsers */
+export class LegacyLockManager implements ILockManager {
+  private lock: BrowserTabsLock;
+  private activeLocks: Set<string> = new Set();
+  private pagehideHandler: () => void;
+
+  constructor() {
+    this.lock = new BrowserTabsLock();
+
+    this.pagehideHandler = () => {
+      this.activeLocks.forEach(key => this.lock.releaseLock(key));
+      this.activeLocks.clear();
+    };
+  }
+
+  async runWithLock<T>(
+    key: string,
+    timeout: number,
+    callback: () => Promise<T>
+  ): Promise<T> {
+    // Retry logic to handle race conditions in localStorage-based locking
+    const retryAttempts = 10;
+    let acquired = false;
+
+    for (let i = 0; i < retryAttempts && !acquired; i++) {
+      acquired = await this.lock.acquireLock(key, timeout);
+    }
+
+    if (!acquired) {
+      throw new TimeoutError();
+    }
+
+    this.activeLocks.add(key);
+
+    // Add pagehide listener when acquiring first lock
+    if (this.activeLocks.size === 1 && typeof window !== 'undefined') {
+      window.addEventListener('pagehide', this.pagehideHandler);
+    }
+
+    try {
+      return await callback();
+    } finally {
+      this.activeLocks.delete(key);
+      await this.lock.releaseLock(key);
+
+      // Remove pagehide listener when all locks are released
+      if (this.activeLocks.size === 0 && typeof window !== 'undefined') {
+        window.removeEventListener('pagehide', this.pagehideHandler);
+      }
+    }
+  }
+}
+
+/**
+ * Feature detection for Web Locks API support
+ */
+function isWebLocksSupported(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    typeof navigator.locks?.request === 'function'
+  );
+}
+
+function createLockManager(): ILockManager {
+  return isWebLocksSupported()
+    ? new WebLocksApiManager()
+    : new LegacyLockManager();
+}
+
+/**
+ * Get the singleton lock manager instance.
+ * Uses Web Locks API in modern browsers, falls back to localStorage in older browsers.
+ */
+let lockManager: ILockManager | null = null;
+
+export function getLockManager(): ILockManager {
+  if (!lockManager) {
+    lockManager = createLockManager();
+  }
+  return lockManager;
+}
+
+// For testing: allow resetting the singleton
+export function resetLockManager(): void {
+  lockManager = null;
+}

package/src/version.ts

@@ -1 +1 @@
-export default '2.14.0';
+export default '2.15.0';