@auth0/auth0-spa-js 2.15.0 → 2.16.0

package/dist/typings/Auth0Client.d.ts

@@ -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);

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/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.15.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.15.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

@@ -883,37 +883,92 @@ export class Auth0Client {
       getTokenOptions.authorizationParams.audience || 'default'
     );
 
-    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
-        });
-
-        if (entry) {
-          return entry;
+    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,
+            clientId: this.options.clientId
+          });
+
+          if (entry) {
+            return entry;
+          }
         }
+
+        const authResult = this.options.useRefreshTokens
+          ? await this._getTokenUsingRefreshToken(getTokenOptions)
+          : await this._getTokenFromIFrame(getTokenOptions);
+
+        const { id_token, token_type, access_token, oauthTokenScope, expires_in } =
+          authResult;
+
+        return {
+          id_token,
+          token_type,
+          access_token,
+          ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
+          expires_in
+        };
+      });
+    } catch (error) {
+      // Lock is already released - safe to open popup
+      if (this._isInteractiveError(error) && this.options.interactiveErrorHandler === 'popup') {
+        return await this._handleInteractiveErrorWithPopup(getTokenOptions);
       }
+      throw error;
+    }
+  }
 
-      const authResult = this.options.useRefreshTokens
-        ? await this._getTokenUsingRefreshToken(getTokenOptions)
-        : await this._getTokenFromIFrame(getTokenOptions);
+  /**
+   * 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;
+  }
 
-      const { id_token, token_type, access_token, oauthTokenScope, expires_in } =
-        authResult;
+  /**
+   * 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
+      });
 
-      return {
-        id_token,
-        token_type,
-        access_token,
-        ...(oauthTokenScope ? { scope: oauthTokenScope } : null),
-        expires_in
-      };
-    });
+      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;
+    }
   }
 
   /**

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

package/src/version.ts

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