feat(core, react): add step up mfa error handler

docs-site/src/pages/SsoProviderEditDocs.tsx

@@ -893,7 +893,7 @@ interface ComponentAction<T, U = undefined> {
                     <li>
                       <code>tabs.provisioning.content.notifications.*</code> – Notification messages
                       (delete_success, remove_success, update_success, general_error,
-                      provisioning_disabled_success, scim_token_delete_sucess)
+                      provisioning_disabled_success, scim_token_delete_success)
                     </li>
                   </ul>
                 </div>

examples/next-rwa/package.json

@@ -10,7 +10,7 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@auth0/nextjs-auth0": "^4.13.2",
+    "@auth0/nextjs-auth0": "^v4.15.0",
     "@auth0/universal-components-react": "workspace:*",
     "@tailwindcss/postcss": "^4.1.17",
     "execa": "^9.1.0",

examples/next-rwa/src/lib/auth0.ts

@@ -25,7 +25,6 @@ export const auth0 = new Auth0Client({
   httpTimeout: 20000, // 20 seconds
   authorizationParameters: {
     scope: process.env.AUTH0_SCOPE || 'openid profile email offline_access',
-
     ...(process.env.AUTH0_DOMAIN && {
       audience: `${process.env.AUTH0_DOMAIN.replace(/\/$/, '')}/my-org/`,
     }),

examples/react-spa-npm/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@auth0/auth0-react": "^2.12.0",
+    "@auth0/auth0-react": "^2.15.0",
     "@auth0/universal-components-react": "workspace:*",
     "i18next": "^25.2.1",
     "lucide-react": "^0.511.0",

packages/core/src/api/index.ts

@@ -6,3 +6,4 @@
 
 export * from './api-error';
 export * from './business-error';
+export * from './proxy-http-client';

packages/core/src/api/proxy-http-client.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared HTTP client for proxy-mode API calls.
+ * @module proxy-http-client
+ * @internal
+ */
+
+/**
+ * A lightweight HTTP client scoped to a base URL.
+ * Provides `get` and `post` helpers with standardized error handling.
+ */
+export interface ProxyHttpClient {
+  /** Sends a GET request with optional query parameters. */
+  get: <T>(path: string, query?: Record<string, string>) => Promise<T>;
+  /** Sends a POST request with a JSON body. */
+  post: <T>(path: string, body: unknown) => Promise<T>;
+}
+
+/**
+ * Creates a proxy HTTP client scoped to the given base URL.
+ *
+ * @param baseUrl - The base URL for all requests (trailing slash is stripped).
+ * @returns A {@link ProxyHttpClient} with `get` and `post` methods.
+ */
+export function createProxyHttpClient(baseUrl: string): ProxyHttpClient {
+  const normalizedBase = baseUrl.replace(/\/$/, '');
+
+  const handleResponse = async <T>(response: Response): Promise<T> => {
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      throw Object.assign(new Error(errorBody.error_description || `HTTP ${response.status}`), {
+        status: response.status,
+        body: errorBody,
+        ...errorBody,
+      });
+    }
+    return response.json();
+  };
+
+  const get = async <T>(path: string, query?: Record<string, string>): Promise<T> => {
+    const url = new URL(`${normalizedBase}${path}`);
+    if (query) {
+      Object.entries(query).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+    const response = await fetch(url.toString());
+    return handleResponse<T>(response);
+  };
+
+  const post = async <T>(path: string, body: unknown): Promise<T> => {
+    const response = await fetch(`${normalizedBase}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return handleResponse<T>(response);
+  };
+
+  return { get, post };
+}

packages/core/src/auth/__mocks__/core-client.mocks.ts

@@ -7,7 +7,6 @@ import type {
   BasicAuth0ContextInterface,
   CoreClientInterface,
   User,
-  Auth0ContextInterface,
   GetTokenSilentlyVerboseResponse,
   GetTokenSilentlyOptions,
 } from '../auth-types';
@@ -39,6 +38,29 @@ export const createMockVerboseTokenResponse = (
   ...overrides,
 });
 
+/**
+ * Creates a mock MFA API client
+ */
+const createMockMfaClient = () => ({
+  getAuthenticators: vi.fn().mockResolvedValue([]),
+  enroll: vi.fn().mockResolvedValue({
+    authenticatorType: 'otp',
+    secret: 'mock-secret',
+    barcodeUri: 'otpauth://totp/mock',
+    id: 'authenticator_123',
+  }),
+  challenge: vi.fn().mockResolvedValue({
+    challengeType: 'oob',
+    oobCode: 'mock-oob-code',
+  }),
+  getEnrollmentFactors: vi.fn().mockResolvedValue([]),
+  verify: vi.fn().mockResolvedValue({
+    id_token: 'mock-id-token',
+    access_token: 'mock-access-token',
+    expires_in: 3600,
+  }),
+});
+
 /**
  * Creates a mock BasicAuth0ContextInterface
  */
@@ -59,36 +81,7 @@ export const createMockBasicAuth0Context = (
     domain: TEST_DOMAIN,
     clientId: TEST_CLIENT_ID,
   }),
-  ...overrides,
-});
-
-/**
- * Creates a mock Auth0ContextInterface with full properties
- */
-export const createMockAuth0Context = (
-  overrides?: Partial<Auth0ContextInterface>,
-): Auth0ContextInterface => ({
-  isAuthenticated: true,
-  isLoading: false,
-  user: createMockUser(),
-  getAccessTokenSilently: vi.fn().mockImplementation(async (options?: GetTokenSilentlyOptions) => {
-    if (options?.detailedResponse) {
-      return createMockVerboseTokenResponse();
-    }
-    return 'mock-access-token';
-  }),
-  getAccessTokenWithPopup: vi.fn().mockResolvedValue('mock-access-token'),
-  loginWithRedirect: vi.fn().mockResolvedValue(undefined),
-  loginWithPopup: vi.fn().mockResolvedValue(undefined),
-  logout: vi.fn().mockResolvedValue(undefined),
-  getIdTokenClaims: vi.fn().mockResolvedValue({
-    sub: 'auth0|test-user-123',
-    aud: 'test-client-id',
-    iss: 'https://test-domain.auth0.com/',
-  }),
-  handleRedirectCallback: vi.fn().mockResolvedValue({
-    appState: {},
-  }),
+  mfa: createMockMfaClient(),
   ...overrides,
 });
 
@@ -115,9 +108,35 @@ export const createMockMyAccountApiClient = (): CoreClientInterface['myAccountAp
       delete: vi.fn().mockResolvedValue(undefined),
       verify: vi.fn().mockResolvedValue({ confirmed: true }),
     },
+    withScopes: vi.fn().mockReturnThis(),
   } as unknown as CoreClientInterface['myAccountApiClient'];
 };
 
+/**
+ * Creates a mock StepUpApiService
+ */
+export const createMockStepUpApiService = (): CoreClientInterface['stepUpApiService'] => {
+  return {
+    getAuthenticators: vi.fn().mockResolvedValue([]),
+    enroll: vi.fn().mockResolvedValue({
+      authenticatorType: 'otp',
+      secret: 'mock-secret',
+      barcodeUri: 'otpauth://totp/mock',
+      id: 'authenticator_123',
+    }),
+    challenge: vi.fn().mockResolvedValue({
+      challengeType: 'oob',
+      oobCode: 'mock-oob-code',
+    }),
+    getEnrollmentFactors: vi.fn().mockResolvedValue([]),
+    verify: vi.fn().mockResolvedValue({
+      id_token: 'mock-id-token',
+      access_token: 'mock-access-token',
+      expires_in: 3600,
+    }),
+  } as unknown as CoreClientInterface['stepUpApiService'];
+};
+
 /**
  * Creates a mock MyOrganizationClient service
  */
@@ -203,6 +222,7 @@ export const createMockMyOrganizationApiClient =
           },
         },
       },
+      withScopes: vi.fn().mockReturnThis(),
     } as unknown as CoreClientInterface['myOrganizationApiClient'];
   };
 
@@ -214,21 +234,25 @@ export const createMockCoreClient = (authDetails?: Partial<AuthDetails>): CoreCl
   const mockI18nService = createMockI18nService();
   const mockMyAccountApiClient = createMockMyAccountApiClient();
   const mockMyOrganizationApiClient = createMockMyOrganizationApiClient();
+  const mockStepUpApiService = createMockStepUpApiService();
 
   return {
     auth: mockAuth,
     i18nService: mockI18nService,
     myAccountApiClient: mockMyAccountApiClient,
     myOrganizationApiClient: mockMyOrganizationApiClient,
+    stepUpApiService: mockStepUpApiService,
     getMyAccountApiClient: vi.fn(
       () => mockMyAccountApiClient,
     ) as CoreClientInterface['getMyAccountApiClient'],
     getMyOrganizationApiClient: vi.fn(
       () => mockMyOrganizationApiClient,
     ) as CoreClientInterface['getMyOrganizationApiClient'],
+    getStepUpApiService: vi.fn(
+      () => mockStepUpApiService,
+    ) as CoreClientInterface['getStepUpApiService'],
     getToken: vi.fn().mockResolvedValue('mock-access-token'),
     isProxyMode: vi.fn().mockReturnValue(false),
-    ensureScopes: vi.fn().mockResolvedValue(undefined),
     getDomain: vi.fn(
       () => mockAuth.domain ?? mockAuth.contextInterface?.getConfiguration()?.domain,
     ),

packages/core/src/auth/__mocks__/index.ts

@@ -1,2 +1,2 @@
 export * from './core-client.mocks';
-export * from './token-manager.mocks';
+export * from './spa-token-retriever.mocks';

packages/core/src/auth/__mocks__/token-manager.mocks.ts → packages/core/src/auth/__mocks__/spa-token-retriever.mocks.ts

@@ -1,19 +1,19 @@
 import { vi } from 'vitest';
 
-import type { createTokenManager } from '../token-manager';
+import type { createSpaTokenRetriever } from '../spa-token-retriever';
 
 /**
- * Creates a mock token manager service
+ * Creates a mock SPA token retriever service
  */
-export const createMockTokenManager = (
+export const createMockSpaTokenRetriever = (
   tokenValue: string | undefined = 'mock-access-token',
-): ReturnType<typeof createTokenManager> => ({
+): ReturnType<typeof createSpaTokenRetriever> => ({
   getToken: vi.fn(async () => tokenValue),
 });
 
-export const createMockTokenManagerWithScopes = (
+export const createMockSpaTokenRetrieverWithScopes = (
   tokenValue: string | undefined = 'mock-access-token',
-): ReturnType<typeof createTokenManager> & {
+): ReturnType<typeof createSpaTokenRetriever> & {
   lastScope?: string;
   lastAudiencePath?: string;
 } => {
@@ -29,9 +29,9 @@ export const createMockTokenManagerWithScopes = (
   return mockManager;
 };
 
-export const createMockTokenManagerWithError = (
+export const createMockSpaTokenRetrieverWithError = (
   error: Error = new Error('Token retrieval failed'),
-): ReturnType<typeof createTokenManager> => ({
+): ReturnType<typeof createSpaTokenRetriever> => ({
   getToken: async () => {
     throw error;
   },