@auth0/auth0-spa-js 2.11.3 → 2.13.0

package/dist/typings/Auth0Client.d.ts

@@ -1,7 +1,8 @@
-import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions } from './global';
+import { Auth0ClientOptions, RedirectLoginOptions, PopupLoginOptions, PopupConfigOptions, RedirectLoginResult, GetTokenSilentlyOptions, GetTokenWithPopupOptions, LogoutOptions, User, IdToken, GetTokenSilentlyVerboseResponse, TokenEndpointResponse, ConnectAccountRedirectResult, RedirectConnectAccountOptions, ClientConfiguration } from './global';
 import { CustomTokenExchangeOptions } from './TokenExchange';
 import { Dpop } from './dpop/dpop';
 import { Fetcher, type FetcherConfig, type CustomFetchMinimalOutput } from './fetcher';
+import { MfaApiClient } from './mfa';
 /**
  * Auth0 SDK for Single Page Applications using [Authorization Code Grant Flow with PKCE](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce).
  */
@@ -21,10 +22,38 @@ export declare class Auth0Client {
     private readonly options;
     private readonly userCache;
     private readonly myAccountApi;
+    /**
+     * 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
+     */
+    readonly mfa: MfaApiClient;
     private worker?;
     private readonly activeLockKeys;
+    private readonly authJsClient;
     private readonly defaultOptions;
     constructor(options: Auth0ClientOptions);
+    /**
+     * 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' }
+     * ```
+     */
+    getConfiguration(): Readonly<ClientConfiguration>;
     private _url;
     private _authorizeUrl;
     private _verifyIdToken;
@@ -324,4 +353,25 @@ export declare class Auth0Client {
      * @throws {MyAccountApiError} If the connect request to the My Account API fails.
      */
     connectAccountWithRedirect<TAppState = any>(options: RedirectConnectAccountOptions<TAppState>): Promise<void>;
+    /**
+     * @internal
+     * Internal method used by MfaApiClient to exchange MFA tokens for access tokens.
+     * This method should not be called directly by applications.
+     */
+    _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>;
+}
+interface RequestTokenAdditionalParameters {
+    nonceIn?: string;
+    organization?: string;
+    scopesToRequest?: string;
 }
+export {};

package/dist/typings/errors.d.ts

@@ -1,3 +1,16 @@
+/**
+ * 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.
  */
@@ -55,7 +68,8 @@ export declare class PopupOpenError extends GenericError {
  */
 export declare class MfaRequiredError extends GenericError {
     mfa_token: string;
-    constructor(error: string, error_description: string, mfa_token: string);
+    mfa_requirements: MfaRequirements;
+    constructor(error: string, error_description: string, mfa_token: string, mfa_requirements: MfaRequirements);
 }
 /**
  * Error thrown when there is no refresh token to use

package/dist/typings/global.d.ts

@@ -265,9 +265,24 @@ export interface Auth0ClientOptions {
     /**
      * 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
  */
@@ -738,4 +753,4 @@ export type FetchResponse = {
     json: any;
 };
 export type GetTokenSilentlyVerboseResponse = Omit<TokenEndpointResponse, 'refresh_token'>;
-export {};
+export type { Authenticator, AuthenticatorType, OobChannel, MfaFactorType, EnrollParams, EnrollOtpParams, EnrollSmsParams, EnrollVoiceParams, EnrollEmailParams, EnrollPushParams, EnrollmentResponse, OtpEnrollmentResponse, OobEnrollmentResponse, ChallengeAuthenticatorParams, ChallengeResponse, VerifyParams, MfaGrantType, EnrollmentFactor } from './mfa/types';

package/dist/typings/index.d.ts

@@ -14,6 +14,9 @@ export * from './global';
 export declare function createAuth0Client(options: Auth0ClientOptions): Promise<Auth0Client>;
 export { Auth0Client };
 export { ConnectError, GenericError, AuthenticationError, TimeoutError, PopupTimeoutError, PopupCancelledError, PopupOpenError, MfaRequiredError, MissingRefreshTokenError, 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, InMemoryCache, Cacheable, DecodedToken, CacheEntry, WrappedCacheEntry, KeyManifestEntry, MaybePromise, CacheKey, CacheKeyData } from './cache';
 export type { FetcherConfig, Fetcher, CustomFetchMinimalOutput } from './fetcher';
 export { MyAccountApiError } from './MyAccountApiClient';

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

@@ -0,0 +1,225 @@
+import { Auth0Client } from '../Auth0Client';
+import type { TokenEndpointResponse } from '../global';
+import type { Authenticator, EnrollParams, EnrollmentResponse, ChallengeAuthenticatorParams, ChallengeResponse, VerifyParams, EnrollmentFactor } from './types';
+import { MfaClient as Auth0AuthJsMfaClient } from '@auth0/auth0-auth-js';
+import { MfaRequirements } from '../errors';
+/**
+ * Client for Auth0 MFA API operations
+ *
+ * Manages multi-factor authentication including:
+ * - Listing enrolled authenticators
+ * - Enrolling new authenticators (OTP, SMS, Voice, Push, Email)
+ * - Initiating MFA challenges
+ * - Verifying MFA challenges
+ *
+ * This is a wrapper around auth0-auth-js MfaClient that maintains
+ * backward compatibility with the existing spa-js API.
+ *
+ * MFA context (scope, audience) is stored internally keyed by mfaToken,
+ * enabling concurrent MFA flows without state conflicts.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await auth0.getTokenSilently({ authorizationParams: { audience: 'https://api.example.com' } });
+ * } catch (e) {
+ *   if (e instanceof MfaRequiredError) {
+ *     // SDK automatically stores context for this mfaToken
+ *     const authenticators = await auth0.mfa.getAuthenticators({ mfaToken: e.mfa_token });
+ *     // ... complete MFA flow
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaApiClient {
+    private authJsMfaClient;
+    private auth0Client;
+    private contextManager;
+    /**
+     * @internal
+     * Do not instantiate directly. Use Auth0Client.mfa instead.
+     */
+    constructor(authJsMfaClient: Auth0AuthJsMfaClient, auth0Client: Auth0Client);
+    /**
+     * @internal
+     * Stores authentication details (scope, audience, and MFA requirements) for MFA token verification.
+     * This is automatically called by Auth0Client when an mfa_required error occurs.
+     *
+     * The context is stored keyed by the MFA token, enabling concurrent MFA flows.
+     *
+     * @param mfaToken - The MFA token from the mfa_required error response
+     * @param scope - The OAuth scope from the original request (optional)
+     * @param audience - The API audience from the original request (optional)
+     * @param mfaRequirements - The MFA requirements from the mfa_required error (optional)
+     */
+    setMFAAuthDetails(mfaToken: string, scope?: string, audience?: string, mfaRequirements?: MfaRequirements): void;
+    /**
+     * Gets enrolled MFA authenticators filtered by challenge types from context.
+     *
+     * Challenge types are automatically resolved from the stored MFA context
+     * (set when mfa_required error occurred).
+     *
+     * @param mfaToken - MFA token from mfa_required error
+     * @returns Array of enrolled authenticators matching the challenge types
+     * @throws {MfaListAuthenticatorsError} If the request fails or context not found
+     *
+     * @example Basic usage
+     * ```typescript
+     * try {
+     *   await auth0.getTokenSilently();
+     * } catch (e) {
+     *   if (e instanceof MfaRequiredError) {
+     *     // SDK automatically uses challenge types from error context
+     *     const authenticators = await auth0.mfa.getAuthenticators(e.mfa_token);
+     *   }
+     * }
+     * ```
+     */
+    getAuthenticators(mfaToken: string): Promise<Authenticator[]>;
+    /**
+     * Enrolls a new MFA authenticator
+     *
+     * Requires MFA access token with 'enroll' scope
+     *
+     * @param params - Enrollment parameters including mfaToken and factorType
+     * @returns Enrollment response with authenticator details
+     * @throws {MfaEnrollmentError} If enrollment fails
+     *
+     * @example OTP enrollment
+     * ```typescript
+     * const enrollment = await mfa.enroll({
+     *   mfaToken: mfaToken,
+     *   factorType: 'otp'
+     * });
+     * console.log(enrollment.secret); // Base32 secret
+     * console.log(enrollment.barcodeUri); // QR code URI
+     * ```
+     *
+     * @example SMS enrollment
+     * ```typescript
+     * const enrollment = await mfa.enroll({
+     *   mfaToken: mfaToken,
+     *   factorType: 'sms',
+     *   phoneNumber: '+12025551234'
+     * });
+     * ```
+     */
+    enroll(params: EnrollParams): Promise<EnrollmentResponse>;
+    /**
+     * Initiates an MFA challenge
+     *
+     * Sends OTP via SMS, initiates push notification, or prepares for OTP entry
+     *
+     * @param params - Challenge parameters including mfaToken
+     * @returns Challenge response with oobCode if applicable
+     * @throws {MfaChallengeError} If challenge initiation fails
+     *
+     * @example OTP challenge
+     * ```typescript
+     * const challenge = await mfa.challenge({
+     *   mfaToken: mfaTokenFromLogin,
+     *   challengeType: 'otp',
+     *   authenticatorId: 'otp|dev_xxx'
+     * });
+     * // User enters OTP from their authenticator app
+     * ```
+     *
+     * @example SMS challenge
+     * ```typescript
+     * const challenge = await mfa.challenge({
+     *   mfaToken: mfaTokenFromLogin,
+     *   challengeType: 'oob',
+     *   authenticatorId: 'sms|dev_xxx'
+     * });
+     * console.log(challenge.oobCode); // Use for verification
+     * ```
+     */
+    challenge(params: ChallengeAuthenticatorParams): Promise<ChallengeResponse>;
+    /**
+     * Gets available MFA enrollment factors from the stored context.
+     *
+     * This method exposes the enrollment options from the mfa_required error's
+     * mfaRequirements.enroll array, eliminating the need for manual parsing.
+     *
+     * @param mfaToken - MFA token from mfa_required error
+     * @returns Array of enrollment factors available for the user (empty array if no enrollment required)
+     * @throws {MfaEnrollmentFactorsError} If MFA context not found
+     *
+     * @example Basic usage
+     * ```typescript
+     * try {
+     *   await auth0.getTokenSilently();
+     * } catch (error) {
+     *   if (error.error === 'mfa_required') {
+     *     // Get enrollment options from SDK
+     *     const enrollOptions = await auth0.mfa.getEnrollmentFactors(error.mfa_token);
+     *     // [{ type: 'otp' }, { type: 'phone' }, { type: 'push-notification' }]
+     *
+     *     showEnrollmentOptions(enrollOptions);
+     *   }
+     * }
+     * ```
+     *
+     * @example Check if enrollment is required
+     * ```typescript
+     * try {
+     *   const factors = await auth0.mfa.getEnrollmentFactors(mfaToken);
+     *   if (factors.length > 0) {
+     *     // User needs to enroll in MFA
+     *     renderEnrollmentUI(factors);
+     *   } else {
+     *     // No enrollment required, proceed with challenge
+     *   }
+     * } catch (error) {
+     *   if (error instanceof MfaEnrollmentFactorsError) {
+     *     console.error('Context not found:', error.error_description);
+     *   }
+     * }
+     * ```
+     */
+    getEnrollmentFactors(mfaToken: string): Promise<EnrollmentFactor[]>;
+    /**
+     * Verifies an MFA challenge and completes authentication
+     *
+     * The scope and audience are retrieved from the stored context (set when the
+     * mfa_required error occurred). The grant_type is automatically inferred from
+     * which verification field is provided (otp, oobCode, or recoveryCode).
+     *
+     * @param params - Verification parameters with OTP, OOB code, or recovery code
+     * @returns Token response with access_token, id_token, refresh_token
+     * @throws {MfaVerifyError} If verification fails (invalid code, expired, rate limited)
+     * @throws {MfaVerifyError} If MFA context not found
+     * @throws {MfaVerifyError} If grant_type cannot be inferred
+     *
+     * Rate limits:
+     * - 10 verification attempts allowed
+     * - Refreshes at 1 attempt per 6 minutes
+     *
+     * @example OTP verification (grant_type inferred from otp field)
+     * ```typescript
+     * const tokens = await mfa.verify({
+     *   mfaToken: mfaTokenFromLogin,
+     *   otp: '123456'
+     * });
+     * console.log(tokens.access_token);
+     * ```
+     *
+     * @example OOB verification (grant_type inferred from oobCode field)
+     * ```typescript
+     * const tokens = await mfa.verify({
+     *   mfaToken: mfaTokenFromLogin,
+     *   oobCode: challenge.oobCode,
+     *   bindingCode: '123456' // Code user received via SMS
+     * });
+     * ```
+     *
+     * @example Recovery code verification (grant_type inferred from recoveryCode field)
+     * ```typescript
+     * const tokens = await mfa.verify({
+     *   mfaToken: mfaTokenFromLogin,
+     *   recoveryCode: 'XXXX-XXXX-XXXX'
+     * });
+     * ```
+     */
+    verify(params: VerifyParams): Promise<TokenEndpointResponse>;
+}

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

@@ -0,0 +1,79 @@
+import { MfaRequirements } from '../errors';
+/**
+ * Represents the stored context for an MFA flow
+ */
+export interface MfaContext {
+    /** The OAuth scope for the original token request */
+    scope?: string;
+    /** The API audience for the original token request */
+    audience?: string;
+    /** MFA requirements from the mfa_required error (camelCase for TypeScript conventions) */
+    mfaRequirements?: MfaRequirements;
+    /** Timestamp when the context was created */
+    createdAt: number;
+}
+/**
+ * Manages MFA authentication contexts keyed by MFA token.
+ *
+ * When an mfa_required error occurs, the SDK stores the original request's
+ * scope and audience. When the user later provides an MFA token for verification,
+ * the SDK retrieves the matching context to complete the token exchange.
+ *
+ * This enables concurrent MFA flows without state conflicts.
+ *
+ * @example
+ * ```typescript
+ * const manager = new MfaContextManager();
+ *
+ * // Store context when mfa_required error occurs
+ * manager.set('mfaTokenAbc', { scope: 'openid profile', audience: 'https://api.example.com' });
+ *
+ * // Retrieve context when user completes MFA
+ * const context = manager.get('mfaTokenAbc');
+ * // { scope: 'openid profile', audience: 'https://api.example.com', createdAt: ... }
+ *
+ * // Remove after successful verification
+ * manager.remove('mfaTokenAbc');
+ * ```
+ */
+export declare class MfaContextManager {
+    private contexts;
+    private readonly ttlMs;
+    /**
+     * Creates a new MfaContextManager
+     * @param ttlMs - Time-to-live for contexts in milliseconds (default: 10 minutes)
+     */
+    constructor(ttlMs?: number);
+    /**
+     * Stores an MFA context keyed by the MFA token.
+     * Runs cleanup to remove expired entries before storing.
+     *
+     * @param mfaToken - The MFA token from the mfa_required error
+     * @param context - The scope and audience from the original request
+     */
+    set(mfaToken: string, context: Omit<MfaContext, 'createdAt'>): void;
+    /**
+     * Retrieves the MFA context for a given token.
+     * Returns undefined if the token is not found or has expired.
+     *
+     * @param mfaToken - The MFA token to look up
+     * @returns The stored context, or undefined if not found/expired
+     */
+    get(mfaToken: string): MfaContext | undefined;
+    /**
+     * Removes an MFA context.
+     * Should be called after successful MFA verification.
+     *
+     * @param mfaToken - The MFA token to remove
+     */
+    remove(mfaToken: string): void;
+    /**
+     * Removes all expired contexts from the Map.
+     * Called automatically on every `set` operation.
+     */
+    private cleanup;
+    /**
+     * Returns the number of stored contexts
+     */
+    get size(): number;
+}

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

@@ -0,0 +1,23 @@
+import type { MfaFactorType, OobChannel } from './types';
+/**
+ * Mapping configuration for a factor type
+ */
+export interface FactorMapping {
+    authenticatorTypes: ['otp'] | ['oob'];
+    oobChannels?: OobChannel[];
+}
+/**
+ * Maps MFA factor types to auth-js enrollment parameters
+ */
+export declare const FACTOR_MAPPING: Record<MfaFactorType, FactorMapping>;
+/**
+ * MFA grant type constants for verification
+ */
+export declare const MfaGrantTypes: {
+    /** Grant type for OTP (TOTP) verification */
+    readonly OTP: "http://auth0.com/oauth/grant-type/mfa-otp";
+    /** Grant type for OOB (SMS, Email, Push) verification */
+    readonly OOB: "http://auth0.com/oauth/grant-type/mfa-oob";
+    /** Grant type for recovery code verification */
+    readonly RECOVERY_CODE: "http://auth0.com/oauth/grant-type/mfa-recovery-code";
+};

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

@@ -0,0 +1,117 @@
+import { MfaApiErrorResponse } from '@auth0/auth0-auth-js';
+import { GenericError } from '../errors';
+/**
+ * Base class for MFA-related errors in auth0-spa-js.
+ * Extends GenericError for unified error hierarchy across the SDK.
+ */
+export declare class MfaError extends GenericError {
+    constructor(error: string, error_description: string);
+    static fromPayload({ error, error_description }: {
+        error: string;
+        error_description: string;
+    }): MfaError;
+}
+/**
+ * Error thrown when listing MFA authenticators fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const authenticators = await mfa.getAuthenticators();
+ * } catch (error) {
+ *   if (error instanceof MfaListAuthenticatorsError) {
+ *     console.log(error.error); // 'access_denied'
+ *     console.log(error.error_description); // 'Unauthorized'
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaListAuthenticatorsError extends MfaError {
+    constructor(error: string, error_description: string);
+}
+/**
+ * Error thrown when enrolling an MFA authenticator fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const enrollment = await mfa.enroll({
+ *     authenticator_types: ['otp']
+ *   });
+ * } catch (error) {
+ *   if (error instanceof MfaEnrollmentError) {
+ *     console.log(error.error); // 'invalid_phone_number'
+ *     console.log(error.error_description); // 'Invalid phone number format'
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaEnrollmentError extends MfaError {
+    constructor(error: string, error_description: string);
+}
+/**
+ * Error thrown when initiating an MFA challenge fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const challenge = await mfa.challenge({
+ *     mfaToken: mfaToken,
+ *     challengeType: 'otp',
+ *     authenticatorId: 'otp|dev_123'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof MfaChallengeError) {
+ *     console.log(error.error); // 'too_many_attempts'
+ *     console.log(error.error_description); // 'Rate limit exceeded'
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaChallengeError extends MfaError {
+    constructor(error: string, error_description: string);
+}
+/**
+ * Error thrown when verifying an MFA challenge fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tokens = await mfa.verify({
+ *     mfaToken: mfaToken,
+ *     grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp',
+ *     otp: '123456'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof MfaVerifyError) {
+ *     console.log(error.error); // 'invalid_otp' or 'context_not_found'
+ *     console.log(error.error_description); // Error details
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaVerifyError extends MfaError {
+    constructor(error: string, error_description: string);
+}
+/**
+ * Error thrown when getting enrollment factors fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const factors = await mfa.getEnrollmentFactors(mfaToken);
+ * } catch (error) {
+ *   if (error instanceof MfaEnrollmentFactorsError) {
+ *     console.log(error.error); // 'mfa_context_not_found'
+ *     console.log(error.error_description); // 'MFA context not found...'
+ *   }
+ * }
+ * ```
+ */
+export declare class MfaEnrollmentFactorsError extends MfaError {
+    constructor(error: string, error_description: string);
+}
+/**
+ * Re-export MfaApiErrorResponse type for convenience
+ */
+export type { MfaApiErrorResponse };

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

@@ -0,0 +1,4 @@
+export { MfaApiClient } from './MfaApiClient';
+export { MfaContextManager } from './MfaContextManager';
+export type { MfaContext } from './MfaContextManager';
+export type { Authenticator, AuthenticatorType, OobChannel, MfaFactorType, EnrollBaseParams, EnrollParams, EnrollOtpParams, EnrollSmsParams, EnrollVoiceParams, EnrollEmailParams, EnrollPushParams, EnrollmentResponse, OtpEnrollmentResponse, OobEnrollmentResponse, ChallengeAuthenticatorParams, ChallengeResponse, VerifyParams, MfaGrantType, EnrollmentFactor } from './types';