feat: add Multi-Factor Authentication (MFA) support (#1014)

## Summary

Adds comprehensive MFA support by exposing the MFA client from
`@auth0/auth0-spa-js` through the `useAuth0()` hook. Enables React
applications to implement MFA enrollment, challenge, and verification
flows for all authenticator types (OTP, SMS, Voice, Email, Push).

## Changes

### Core Implementation

**`src/auth0-context.tsx` & `src/auth0-provider.tsx`**
- Added `mfa` property to `Auth0ContextInterface` exposing
`MfaApiClient`
- Integrated MFA client into provider context
- Added JSDoc documentation with usage examples

**Available Methods:**
- `getAuthenticators(mfaToken)` - List enrolled authenticators
- `enroll(params)` - Enroll new authenticators (OTP, SMS, Voice, Email,
Push)
- `challenge(params)` - Initiate MFA challenges
- `verify(params)` - Verify with OTP, OOB code, or recovery code
- `getEnrollmentFactors(mfaToken)` - Get available enrollment factors


### Documentation (`EXAMPLES.md`)

Added comprehensive MFA guide covering:
- Setup and dashboard configuration
- MFA response flow patterns (challenge vs enroll)
- Error handling with `MfaRequiredError`
- Code examples for all authenticator types
- Challenge and verification patterns
- Recovery code handling

### Testing (`__tests__/mfa.test.tsx`)

- Availability tests: Verify MFA client and all 5 methods are accessible
- Success tests: Test each method returns expected responses
- Updated mocks in `__mocks__/@auth0/auth0-spa-js.tsx`

## Usage Example

```jsx
import { useAuth0, MfaRequiredError } from '@auth0/auth0-react';

const { getAccessTokenSilently, mfa } = useAuth0();

try {
  await getAccessTokenSilently();
} catch (error) {
  if (error instanceof MfaRequiredError) {
    // Enroll new authenticator
    const enrollment = await mfa.enroll({
      mfaToken: error.mfa_token,
      factorType: 'otp'
    });

    // Challenge and verify
    const authenticators = await mfa.getAuthenticators(error.mfa_token);
    await mfa.challenge({
      mfaToken: error.mfa_token,
      challengeType: 'otp',
      authenticatorId: authenticators[0].id
    });

    const tokens = await mfa.verify({
      mfaToken: error.mfa_token,
      otp: userCode
    });
  }
}
```

## Breaking Changes

None. Backward compatible, additive change only.

## Related Documentation

- [Auth0 MFA
Documentation](https://auth0.com/docs/secure/multi-factor-authentication)
- [`@auth0/auth0-spa-js` MFA
API](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md#multi-factor-authentication-mfa)

Author: gyaneshgouraw-okta

EXAMPLES.md

@@ -12,6 +12,7 @@
 - [Using Multi Resource Refresh Tokens](#using-multi-resource-refresh-tokens)
 - [Connect Accounts for using Token Vault](#connect-accounts-for-using-token-vault)
 - [Access SDK Configuration](#access-sdk-configuration)
+- [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa)
 
 ## Use with a Class Component
 
@@ -778,4 +779,214 @@ const ConfigInfo = () => {
 export default ConfigInfo;
 ```
 
-This is useful for debugging, logging, or building custom Auth0-related URLs without duplicating configuration values.
+This is useful for debugging, logging, or building custom Auth0-related URLs without duplicating configuration values.
+
+## Multi-Factor Authentication (MFA)
+
+Access MFA operations through the `mfa` property from `useAuth0()`. All operations require an `mfa_token` from the MFA required error.
+
+> [!NOTE]
+> Multi Factor Authentication support via SDKs is currently in Early Access. To request access to this feature, contact your Auth0 representative.
+
+- [Setup](#setup)
+- [Handling MFA Required Error](#handling-mfa-required-error)
+- [Enrolling Authenticators](#enrolling-authenticators)
+- [Challenging Authenticators](#challenging-authenticators)
+- [Verifying Challenges](#verifying-challenges)
+- [Error Handling](#error-handling)
+
+### Setup
+
+Before using the MFA API, configure MFA in your [Auth0 Dashboard](https://manage.auth0.com) under **Security** > **Multi-factor Auth**. For detailed configuration, see the [Auth0 MFA documentation](https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-enrollments-universal-login).
+
+#### Understanding the MFA Response
+
+When MFA is required, the error payload contains an `mfa_requirements` object that indicates either a **challenge** flow (user has enrolled authenticators) or an **enroll** flow (user needs to set up MFA).
+
+**Challenge Flow Response** (user has existing authenticators):
+
+```json
+{
+  "error": "mfa_required",
+  "error_description": "Multifactor authentication required",
+  "mfa_token": "Fe26.2*...",
+  "mfa_requirements": {
+    "challenge": [
+      { "type": "otp" },
+      { "type": "email" }
+      ...
+    ]
+  }
+}
+```
+
+**Enroll Flow Response** (user needs to enroll an authenticator):
+
+```json
+{
+  "error": "mfa_required",
+  "error_description": "Multifactor authentication required",
+  "mfa_token": "Fe26.2*...",
+  "mfa_requirements": {
+    "enroll": [
+      { "type": "otp" },
+      { "type": "phone" },
+      { "type": "push-notification" }
+      ...
+    ]
+  }
+}
+```
+
+Based on the response:
+- **`mfa_requirements.challenge`**: User has enrolled authenticators → proceed with **List Authenticators → Challenge → Verify** flow
+- **`mfa_requirements.enroll`**: User needs to set up MFA → proceed with **Enroll → Verify** flow
+
+> [!NOTE]
+> The SDK handles this logic automatically. When you call `getEnrollmentFactors()` or `getAuthenticators()`, the SDK uses the stored context to return the appropriate data.
+
+
+### Handling MFA Required Error
+When MFA is required, the SDK automatically stores the context. You can then call MFA methods with just the token:
+
+```jsx
+import { useAuth0, MfaRequiredError } from '@auth0/auth0-react';
+
+try {
+  await getAccessTokenSilently();
+} catch (error) {
+  if (error instanceof MfaRequiredError) {
+    const mfaToken = error.mfa_token;
+    
+    // Check if user needs to enroll
+    const factors = await mfa.getEnrollmentFactors(mfaToken);
+    if (factors.length > 0) {
+      // Show enrollment UI
+    } else {
+       // User has enrolled authenticators - get the list of enrolled authenticator
+      const authenticators = await mfa.getAuthenticators(error.mfa_token);
+
+      // proceed with challenge
+    }
+  }
+}
+```
+
+### Enrolling Authenticators
+
+```jsx
+const { mfa } = useAuth0();
+
+// Enroll any factor type
+const enrollment = await mfa.enroll({
+  mfaToken,
+  factorType: 'otp'  // 'otp' | 'sms' | 'email' | 'voice' | 'push'
+});
+
+// For OTP: Display QR code
+console.log('Scan:', enrollment.barcodeUri);
+console.log('Recovery codes:', enrollment.recoveryCodes);
+
+// For SMS: Include phone number
+await mfa.enroll({
+  mfaToken,
+  factorType: 'sms',
+  phoneNumber: '+12025551234'  // E.164 format
+});
+
+// For Voice: Include phone number
+await mfa.enroll({
+  mfaToken,
+  factorType: 'voice',
+  phoneNumber: '+12025551234'  // E.164 format
+});
+
+// For Email: Include email address
+await mfa.enroll({
+  mfaToken,
+  factorType: 'email',
+  email: 'user@example.com'
+});
+
+// For Push: Returns authenticator for mobile app
+const pushEnrollment = await mfa.enroll({
+  mfaToken,
+  factorType: 'push'
+});
+console.log('Authenticator ID:', pushEnrollment.id);  // Use with Guardian app
+```
+
+### Challenging Authenticators
+
+```jsx
+const { mfa } = useAuth0();
+
+// Get enrolled authenticators
+const authenticators = await mfa.getAuthenticators(mfaToken);
+
+// For OTP: Challenge is OPTIONAL - code already available in authenticator app
+// Skip directly to verify() with the 6-digit code, or optionally challenge with:
+const otpResponse = await mfa.challenge({
+  mfaToken,
+  challengeType: 'otp',
+  authenticatorId: authenticators[0].id
+});
+
+// For SMS/Voice/Email/Push: Challenge REQUIRED to send code (use 'oob' type)
+const oobResponse = await mfa.challenge({
+  mfaToken,
+  challengeType: 'oob',  // Use 'oob' for all out-of-band authenticators
+  authenticatorId: authenticators[0].id  // ID of SMS/Voice/Email/Push authenticator
+});
+console.log('OOB Code:', oobResponse.oobCode);  // Code sent via SMS/Voice/Email/Push
+```
+
+### Verifying Challenges
+
+```jsx
+const { mfa } = useAuth0();
+
+// Verify with OTP code (for OTP authenticators)
+const tokens = await mfa.verify({
+  mfaToken,
+  otp: '123456'  // 6-digit code from authenticator app
+});
+
+// Verify with OOB code (for SMS/Voice/Email authenticators)
+const tokens = await mfa.verify({
+  mfaToken,
+  oobCode: smsResponse.oobCode,
+  bindingCode: '123456'  // Optional: code shown in challenge
+});
+
+// Verify with recovery code (works for any authenticator)
+const tokens = await mfa.verify({
+  mfaToken,
+  recoveryCode: 'recovery-code-here'
+});
+
+// Tokens are now cached - user is authenticated
+console.log('Access token:', tokens.access_token);
+```
+
+### Error Handling
+
+```jsx
+import {
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError
+} from '@auth0/auth0-react';
+
+try {
+  await mfa.verify({ mfaToken, otp });
+} catch (error) {
+  if (error instanceof MfaVerifyError) {
+    console.error('Invalid code:', error.error_description);
+  } else if (error instanceof MfaChallengeError) {
+    console.error('Challenge failed:', error.error_description);
+  } else if (error instanceof MfaEnrollmentError) {
+    console.error('Enrollment failed:', error.error_description);
+  }
+}
+```

__mocks__/@auth0/auth0-spa-js.tsx

@@ -20,6 +20,11 @@ const setDpopNonce = jest.fn();
 const generateDpopProof = jest.fn();
 const createFetcher = jest.fn();
 const getConfiguration = jest.fn();
+const mfaGetAuthenticators = jest.fn(() => Promise.resolve([]));
+const mfaEnroll = jest.fn(() => Promise.resolve({ id: 'test-id', barcodeUri: 'test-uri', recoveryCodes: [] }));
+const mfaChallenge = jest.fn(() => Promise.resolve({ challengeType: 'otp', oobCode: null }));
+const mfaVerify = jest.fn(() => Promise.resolve({ access_token: 'test-token', id_token: 'test-id-token' }));
+const mfaGetEnrollmentFactors = jest.fn(() => Promise.resolve([]));
 
 export const Auth0Client = jest.fn(() => {
   return {
@@ -43,7 +48,21 @@ export const Auth0Client = jest.fn(() => {
     generateDpopProof,
     createFetcher,
     getConfiguration,
+    mfa: {
+      getAuthenticators: mfaGetAuthenticators,
+      enroll: mfaEnroll,
+      challenge: mfaChallenge,
+      verify: mfaVerify,
+      getEnrollmentFactors: mfaGetEnrollmentFactors,
+    },
   };
 });
 
-export const ResponseType = actual.ResponseType;
+export const ResponseType = actual.ResponseType;
+
+export const MfaError = actual.MfaError;
+export const MfaListAuthenticatorsError = actual.MfaListAuthenticatorsError;
+export const MfaEnrollmentError = actual.MfaEnrollmentError;
+export const MfaChallengeError = actual.MfaChallengeError;
+export const MfaVerifyError = actual.MfaVerifyError;
+export const MfaEnrollmentFactorsError = actual.MfaEnrollmentFactorsError;

__tests__/mfa.test.tsx

@@ -0,0 +1,96 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import useAuth0 from '../src/use-auth0';
+import { createWrapper } from './helpers';
+
+describe('MFA API', () => {
+  describe('Basic Availability', () => {
+    it('should provide mfa client through useAuth0', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.mfa).toBeDefined();
+      });
+    });
+
+    it('should provide all five MFA methods', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.mfa.getAuthenticators).toBeDefined();
+        expect(result.current.mfa.enroll).toBeDefined();
+        expect(result.current.mfa.challenge).toBeDefined();
+        expect(result.current.mfa.verify).toBeDefined();
+        expect(result.current.mfa.getEnrollmentFactors).toBeDefined();
+      });
+    });
+  });
+
+  describe('Method Success Tests', () => {
+    it('should call mfa.getAuthenticators', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(async () => {
+        const authenticators = await result.current.mfa.getAuthenticators('test-mfa-token');
+        expect(authenticators).toBeDefined();
+        expect(Array.isArray(authenticators)).toBe(true);
+      });
+    });
+
+    it('should call mfa.enroll', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(async () => {
+        const enrollment = await result.current.mfa.enroll({
+          mfaToken: 'test-mfa-token',
+          factorType: 'otp',
+        });
+        expect(enrollment).toBeDefined();
+        expect(enrollment.id).toBe('test-id');
+      });
+    });
+
+    it('should call mfa.challenge', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(async () => {
+        const response = await result.current.mfa.challenge({
+          mfaToken: 'test-mfa-token',
+          challengeType: 'otp',
+          authenticatorId: 'test-auth-id',
+        });
+        expect(response).toBeDefined();
+        expect(response.challengeType).toBe('otp');
+      });
+    });
+
+    it('should call mfa.verify', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(async () => {
+        const tokens = await result.current.mfa.verify({
+          mfaToken: 'test-mfa-token',
+          otp: '123456',
+        });
+        expect(tokens).toBeDefined();
+        expect(tokens.access_token).toBe('test-token');
+      });
+    });
+
+    it('should call mfa.getEnrollmentFactors', async () => {
+      const wrapper = createWrapper();
+      const { result } = renderHook(() => useAuth0(), { wrapper });
+
+      await waitFor(async () => {
+        const factors = await result.current.mfa.getEnrollmentFactors('test-mfa-token');
+        expect(factors).toBeDefined();
+        expect(Array.isArray(factors)).toBe(true);
+      });
+    });
+  });
+});