@auth0/auth0-spa-js 2.11.3 → 2.13.0

package/dist/typings/mfa/types.d.ts

@@ -0,0 +1,181 @@
+import { MfaGrantTypes } from './constants';
+/**
+ * Represents an MFA authenticator enrolled by a user
+ */
+export interface Authenticator {
+    /** Unique identifier for the authenticator */
+    id: string;
+    /** Type of authenticator */
+    authenticatorType: AuthenticatorType;
+    /** Whether the authenticator is active */
+    active: boolean;
+    /** Optional friendly name */
+    name?: string;
+    /** ISO 8601 timestamp when created */
+    createdAt?: string;
+    /** ISO 8601 timestamp of last authentication */
+    lastAuth?: string;
+    /** Types of MFA challenges*/
+    type?: string;
+}
+/**
+ * Supported authenticator types.
+ * Note: Email authenticators use 'oob' type with oobChannel: 'email'
+ */
+export type AuthenticatorType = 'otp' | 'oob' | 'recovery-code';
+/**
+ * Types of MFA challenges
+ */
+export type ChallengeType = 'otp' | 'phone' | 'recovery-code' | 'email' | 'push-notification' | 'totp';
+/**
+ * Out-of-band delivery channels.
+ * Includes 'email' which is also delivered out-of-band.
+ */
+export type OobChannel = 'sms' | 'voice' | 'auth0' | 'email';
+/**
+ * Supported MFA factors for enrollment
+ */
+export type MfaFactorType = 'otp' | 'sms' | 'email' | 'push' | 'voice';
+/**
+ * Base parameters for all enrollment types
+ */
+export interface EnrollBaseParams {
+    /** MFA token from mfa_required error */
+    mfaToken: string;
+}
+/**
+ * OTP (Time-based One-Time Password) enrollment parameters
+ */
+export interface EnrollOtpParams extends EnrollBaseParams {
+    /** The factor type for enrollment */
+    factorType: 'otp';
+}
+/**
+ * SMS enrollment parameters
+ */
+export interface EnrollSmsParams extends EnrollBaseParams {
+    /** The factor type for enrollment */
+    factorType: 'sms';
+    /** Phone number in E.164 format (required for SMS) */
+    phoneNumber: string;
+}
+/**
+ * Voice enrollment parameters
+ */
+export interface EnrollVoiceParams extends EnrollBaseParams {
+    /** The factor type for enrollment */
+    factorType: 'voice';
+    /** Phone number in E.164 format (required for voice) */
+    phoneNumber: string;
+}
+/**
+ * Email enrollment parameters
+ */
+export interface EnrollEmailParams extends EnrollBaseParams {
+    /** The factor type for enrollment */
+    factorType: 'email';
+    /** Email address (optional, uses user's email if not provided) */
+    email?: string;
+}
+/**
+ * Push notification enrollment parameters
+ */
+export interface EnrollPushParams extends EnrollBaseParams {
+    /** The factor type for enrollment */
+    factorType: 'push';
+}
+/**
+ * Union type for all enrollment parameter types
+ */
+export type EnrollParams = EnrollOtpParams | EnrollSmsParams | EnrollVoiceParams | EnrollEmailParams | EnrollPushParams;
+/**
+ * Response when enrolling an OTP authenticator
+ */
+export interface OtpEnrollmentResponse {
+    /** Authenticator type */
+    authenticatorType: 'otp';
+    /** Base32-encoded secret for TOTP generation */
+    secret: string;
+    /** URI for generating QR code (otpauth://...) */
+    barcodeUri: string;
+    /** Recovery codes for account recovery */
+    recoveryCodes?: string[];
+    /** Authenticator ID */
+    id?: string;
+}
+/**
+ * Response when enrolling an OOB authenticator
+ */
+export interface OobEnrollmentResponse {
+    /** Authenticator type */
+    authenticatorType: 'oob';
+    /** Delivery channel used */
+    oobChannel: OobChannel;
+    /** Out-of-band code for verification */
+    oobCode?: string;
+    /** Binding method (e.g., 'prompt' for user code entry) */
+    bindingMethod?: string;
+    /** Recovery codes (generated when enrolling first MFA factor) */
+    recoveryCodes?: string[];
+    /** Authenticator ID */
+    id?: string;
+    /** URI for QR code (for Push/Guardian enrollment) */
+    barcodeUri?: string;
+}
+/**
+ * Union type for all enrollment response types
+ */
+export type EnrollmentResponse = OtpEnrollmentResponse | OobEnrollmentResponse;
+/**
+ * Parameters for initiating an MFA challenge
+ */
+export interface ChallengeAuthenticatorParams {
+    /** MFA token from mfa_required error or MFA-scoped access token */
+    mfaToken: string;
+    /** Type of challenge to initiate */
+    challengeType: 'otp' | 'oob';
+    /** Specific authenticator to challenge (optional) */
+    authenticatorId?: string;
+}
+/**
+ * Response from initiating an MFA challenge
+ */
+export interface ChallengeResponse {
+    /** Type of challenge created */
+    challengeType: 'otp' | 'oob';
+    /** Out-of-band code (for OOB challenges) */
+    oobCode?: string;
+    /** Binding method for OOB (e.g., 'prompt') */
+    bindingMethod?: string;
+}
+/**
+ * Grant types for MFA verification (derived from MfaGrantTypes constants)
+ */
+export type MfaGrantType = (typeof MfaGrantTypes)[keyof typeof MfaGrantTypes];
+/**
+ * Parameters for verifying an MFA challenge.
+ *
+ * The grant_type is automatically inferred from which verification field is provided:
+ * - `otp` field → MFA-OTP grant type
+ * - `oobCode` field → MFA-OOB grant type
+ * - `recoveryCode` field → MFA-RECOVERY-CODE grant type
+ */
+export interface VerifyParams {
+    /** MFA token from challenge flow */
+    mfaToken: string;
+    /** One-time password (for OTP challenges) */
+    otp?: string;
+    /** Out-of-band code (for OOB challenges) */
+    oobCode?: string;
+    /** Binding code (for OOB challenges with binding) */
+    bindingCode?: string;
+    /** Recovery code (for recovery code verification) */
+    recoveryCode?: string;
+}
+/**
+ * Enrollment factor returned by getEnrollmentFactors
+ */
+export interface EnrollmentFactor {
+    /** Type of enrollment factor available */
+    type: string;
+}

package/dist/typings/mfa/utils.d.ts

@@ -0,0 +1,23 @@
+import type { EnrollParams, VerifyParams, MfaGrantType } from './types';
+/**
+ * Converts factor-based enrollment params to auth-js format
+ *
+ * @param params - The enrollment parameters with factorType
+ * @returns Parameters in auth-js format with authenticatorTypes/oobChannels
+ */
+export declare function getAuthJsEnrollParams(params: EnrollParams): {
+    email?: string | undefined;
+    phoneNumber?: string | undefined;
+    oobChannels?: import("./types").OobChannel[] | undefined;
+    mfaToken: string;
+    authenticatorTypes: ["otp"] | ["oob"];
+};
+/**
+ * Gets the grant type from verification parameters based on which field is provided.
+ *
+ * Priority order: otp > oobCode > recoveryCode
+ *
+ * @param params - The verification parameters
+ * @returns The grant type or undefined if no verification field is present
+ */
+export declare function getGrantType(params: VerifyParams): MfaGrantType | undefined;

package/dist/typings/utils.d.ts

@@ -10,9 +10,10 @@ export declare const decode: (value: string) => string;
 /**
  * Strips any property that is not present in ALLOWED_AUTH0CLIENT_PROPERTIES
  * @param auth0Client - The full auth0Client object
+ * @param excludeEnv - If true, excludes the 'env' property from the result
  * @returns The stripped auth0Client object
  */
-export declare const stripAuth0Client: (auth0Client: any) => any;
+export declare const stripAuth0Client: (auth0Client: any, excludeEnv?: boolean) => any;
 export declare const createQueryParams: ({ clientId: client_id, ...params }: any) => string;
 export declare const sha256: (s: string) => Promise<any>;
 export declare const urlDecodeB64: (input: string) => string;

package/dist/typings/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "2.11.3";
+declare const _default: "2.13.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.11.3",
+  "version": "2.13.0",
   "main": "dist/lib/auth0-spa-js.cjs.js",
   "types": "dist/typings/index.d.ts",
   "module": "dist/auth0-spa-js.production.esm.js",
@@ -23,6 +23,7 @@
     }
   },
   "dependencies": {
+    "@auth0/auth0-auth-js": "^1.4.0",
     "browser-tabs-lock": "^1.2.15",
     "dpop": "^2.1.1",
     "es-cookie": "~1.3.2"
@@ -54,12 +55,17 @@
   },
   "devDependencies": {
     "@auth0/component-cdn-uploader": "^2.4.2",
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^21.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^4.0.0",
     "@types/cypress": "^1.1.3",
     "@types/jest": "^28.1.7",
     "@typescript-eslint/eslint-plugin-tslint": "^5.33.1",
     "@typescript-eslint/parser": "^5.33.1",
-    "browserstack-cypress-cli": "1.36.1",
+    "browserstack-cypress-cli": "1.36.2",
     "cli-table": "^0.3.6",
     "concurrently": "^7.3.0",
     "cypress": "13.17.0",
@@ -82,10 +88,8 @@
     "rimraf": "^3.0.2",
     "rollup": "^2.78.0",
     "rollup-plugin-analyzer": "^4.0.0",
-    "rollup-plugin-commonjs": "^10.1.0",
     "rollup-plugin-dev": "^1.1.3",
     "rollup-plugin-livereload": "^2.0.5",
-    "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-terser": "^7.0.2",
     "rollup-plugin-typescript2": "^0.36.0",

package/src/Auth0Client.ts

@@ -13,7 +13,8 @@ import {
   openPopup,
   getDomain,
   getTokenIssuer,
-  parseNumber
+  parseNumber,
+  stripAuth0Client
 } from './utils';
 
 import { oauthToken } from './api';
@@ -37,6 +38,7 @@ import {
   AuthenticationError,
   ConnectError,
   GenericError,
+  MfaRequiredError,
   MissingRefreshTokenError,
   MissingScopesError,
   PopupOpenError,
@@ -86,6 +88,7 @@ import {
   RedirectConnectAccountOptions,
   ResponseType,
   ClientAuthorizationParams,
+  ClientConfiguration
 } from './global';
 
 // @ts-ignore
@@ -114,6 +117,8 @@ import {
   type CustomFetchMinimalOutput
 } from './fetcher';
 import { MyAccountApiClient } from './MyAccountApiClient';
+import { MfaApiClient } from './mfa';
+import { AuthClient as Auth0AuthJsClient } from '@auth0/auth0-auth-js';
 
 /**
  * @ignore
@@ -152,8 +157,20 @@ export class Auth0Client {
   private readonly userCache: ICache = new InMemoryCache().enclosedCache;
   private readonly myAccountApi: MyAccountApiClient;
 
+  /**
+   * MFA API client for multi-factor authentication operations.
+   *
+   * Provides methods for:
+   * - Listing enrolled authenticators
+   * - Enrolling new authenticators (OTP, SMS, Voice, Push, Email)
+   * - Initiating MFA challenges
+   * - Verifying MFA challenges
+   */
+  public readonly mfa: MfaApiClient;
+
   private worker?: Worker;
   private readonly activeLockKeys: Set<string> = new Set();
+  private readonly authJsClient: Auth0AuthJsClient;
 
   private readonly defaultOptions: Partial<Auth0ClientOptions> = {
     authorizationParams: {
@@ -270,6 +287,14 @@ export class Auth0Client {
       myAccountApiIdentifier
     );
 
+    // Initialize auth-js client foundational Oauth feature support
+    this.authJsClient = new Auth0AuthJsClient({
+      domain: this.options.domain,
+      clientId: this.options.clientId,
+    });
+    this.mfa = new MfaApiClient(this.authJsClient.mfa, this);
+
+
     // Don't use web workers unless using refresh tokens in memory
     if (
       typeof window !== 'undefined' &&
@@ -285,9 +310,35 @@ export class Auth0Client {
     }
   }
 
+  /**
+   * Returns a readonly copy of the initialization configuration.
+   *
+   * @returns An object containing domain and clientId
+   *
+   * @example
+   * ```typescript
+   * const auth0 = new Auth0Client({
+   *   domain: 'tenant.auth0.com',
+   *   clientId: 'abc123'
+   * });
+   *
+   * const config = auth0.getConfiguration();
+   * // { domain: 'tenant.auth0.com', clientId: 'abc123' }
+   * ```
+   */
+  public getConfiguration(): Readonly<ClientConfiguration> {
+    return Object.freeze({
+      domain: this.options.domain,
+      clientId: this.options.clientId
+    });
+  }
+
   private _url(path: string) {
+    const auth0ClientObj = this.options.auth0Client || DEFAULT_AUTH0_CLIENT;
+    // Strip env from auth0Client for /authorize to prevent query param truncation
+    const strippedAuth0Client = stripAuth0Client(auth0ClientObj, true);
     const auth0Client = encodeURIComponent(
-      btoa(JSON.stringify(this.options.auth0Client || DEFAULT_AUTH0_CLIENT))
+      btoa(JSON.stringify(strippedAuth0Client))
     );
     return `${this.domainUrl}${path}&auth0Client=${auth0Client}`;
   }
@@ -1258,6 +1309,14 @@ export class Auth0Client {
       ) {
         return await this._getTokenFromIFrame(options);
       }
+      if (e instanceof MfaRequiredError) {
+        this.mfa.setMFAAuthDetails(
+          e.mfa_token,
+          options.authorizationParams?.scope,
+          options.authorizationParams?.audience,
+          e.mfa_requirements
+        );
+      }
 
       throw e;
     }
@@ -1396,9 +1455,9 @@ export class Auth0Client {
     // If so, clear the cache to prevent tokens from multiple users coexisting
     if (options.grant_type === 'authorization_code') {
       const existingIdToken = await this._getIdTokenFromCache();
-      
-      if (existingIdToken?.decodedToken?.claims?.sub && 
-          existingIdToken.decodedToken.claims.sub !== decodedToken.claims.sub) {
+
+      if (existingIdToken?.decodedToken?.claims?.sub &&
+        existingIdToken.decodedToken.claims.sub !== decodedToken.claims.sub) {
         // Different user detected - clear cached tokens
         await this.cacheManager.clear(this.options.clientId);
         this.userCache.remove(CACHE_KEY_ID_TOKEN_SUFFIX);
@@ -1580,6 +1639,7 @@ export class Auth0Client {
     });
   }
 
+
   /**
    * Initiates a redirect to connect the user's account with a specified connection.
    * This method generates PKCE parameters, creates a transaction, and redirects to the /connect endpoint.
@@ -1649,6 +1709,29 @@ export class Auth0Client {
       window.location.assign(url);
     }
   }
+
+  /**
+   * @internal
+   * Internal method used by MfaApiClient to exchange MFA tokens for access tokens.
+   * This method should not be called directly by applications.
+   */
+  async _requestTokenForMfa(
+    options: {
+      grant_type: string;
+      mfaToken: string;
+      scope?: string;
+      audience?: string;
+      otp?: string;
+      binding_code?: string;
+      oob_code?: string;
+      recovery_code?: string;
+    },
+    additionalParameters?: RequestTokenAdditionalParameters
+  ): Promise<TokenEndpointResponse> {
+    // Need to add better typing here
+    const { mfaToken, ...restOptions } = options;
+    return this._requestToken({ ...restOptions, mfa_token: mfaToken } as any, additionalParameters);
+  }
 }
 
 interface BaseRequestTokenOptions {

package/src/dpop/utils.ts

@@ -7,7 +7,10 @@ const KEY_PAIR_ALGORITHM: dpopLib.JWSAlgorithm = 'ES256';
 const SUPPORTED_GRANT_TYPES = [
   'authorization_code',
   'refresh_token',
-  'urn:ietf:params:oauth:grant-type:token-exchange'
+  'urn:ietf:params:oauth:grant-type:token-exchange',
+  'http://auth0.com/oauth/grant-type/mfa-oob',
+  'http://auth0.com/oauth/grant-type/mfa-otp',
+  'http://auth0.com/oauth/grant-type/mfa-recovery-code'
 ];
 
 export type KeyPair = Readonly<dpopLib.KeyPair>;

package/src/errors.ts

@@ -1,3 +1,13 @@
+/**
+ * MFA requirements from an mfa_required error response
+ */
+export interface MfaRequirements {
+  /** Required enrollment types */
+  enroll?: Array<{ type: string }>;
+  /** Required challenge types */
+  challenge?: Array<{ type: string }>;
+}
+
 /**
  * Thrown when network requests to the Auth server fail.
  */
@@ -99,7 +109,8 @@ export class MfaRequiredError extends GenericError {
   constructor(
     error: string,
     error_description: string,
-    public mfa_token: string
+    public mfa_token: string,
+    public mfa_requirements: MfaRequirements
   ) {
     super(error, error_description);
     //https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work

package/src/global.ts

@@ -296,13 +296,31 @@ export interface Auth0ClientOptions {
    */
   useDpop?: boolean;
 
+
   /**
    * 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.
-   */
+  */
   authorizationParams?: ClientAuthorizationParams;
 }
 
+/**
+ * Configuration details exposed by the Auth0Client after initialization.
+ *
+ * @category Main
+ */
+export interface ClientConfiguration {
+  /**
+   * The Auth0 domain that was configured
+   */
+  domain: string;
+
+  /**
+   * The Auth0 client ID that was configured
+   */
+  clientId: string;
+}
+
 /**
  * The possible locations where tokens can be stored
  */
@@ -818,3 +836,25 @@ export type GetTokenSilentlyVerboseResponse = Omit<
   TokenEndpointResponse,
   'refresh_token'
 >;
+
+// MFA API types
+export type {
+  Authenticator,
+  AuthenticatorType,
+  OobChannel,
+  MfaFactorType,
+  EnrollParams,
+  EnrollOtpParams,
+  EnrollSmsParams,
+  EnrollVoiceParams,
+  EnrollEmailParams,
+  EnrollPushParams,
+  EnrollmentResponse,
+  OtpEnrollmentResponse,
+  OobEnrollmentResponse,
+  ChallengeAuthenticatorParams,
+  ChallengeResponse,
+  VerifyParams,
+  MfaGrantType,
+  EnrollmentFactor
+} from './mfa/types';

package/src/http.ts

@@ -188,7 +188,7 @@ export async function getJSON<T>(
       error_description || `HTTP error. Unable to fetch ${url}`;
 
     if (error === 'mfa_required') {
-      throw new MfaRequiredError(error, errorMessage, data.mfa_token);
+      throw new MfaRequiredError(error, errorMessage, data.mfa_token, data.mfa_requirements);
     }
 
     if (error === 'missing_refresh_token') {

package/src/index.ts

@@ -35,6 +35,28 @@ export {
   UseDpopNonceError
 } from './errors';
 
+export {
+  MfaError,
+  MfaListAuthenticatorsError,
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError,
+  MfaEnrollmentFactorsError
+} from './mfa/errors';
+
+export { MfaApiClient } from './mfa';
+
+export type {
+  MfaFactorType,
+  EnrollParams,
+  EnrollOtpParams,
+  EnrollSmsParams,
+  EnrollVoiceParams,
+  EnrollEmailParams,
+  EnrollPushParams,
+  VerifyParams
+} from './mfa';
+
 export {
   ICache,
   LocalStorageCache,