@auth0/auth0-react 2.12.0 → 2.14.0

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export { default as useAuth0 } from './use-auth0';
 export { default as withAuth0, WithAuth0Props } from './with-auth0';
 export { default as withAuthenticationRequired, WithAuthenticationRequiredOptions, } from './with-authentication-required';
 export { default as Auth0Context, Auth0ContextInterface, initialContext, LogoutOptions, RedirectLoginOptions, } from './auth0-context';
-export { AuthorizationParams, PopupLoginOptions, PopupConfigOptions, GetTokenWithPopupOptions, LogoutUrlOptions, CacheLocation, GetTokenSilentlyOptions, IdToken, User, ICache, InMemoryCache, LocalStorageCache, Cacheable, TimeoutError, MfaRequiredError, PopupCancelledError, PopupTimeoutError, AuthenticationError, MissingRefreshTokenError, GenericError, UseDpopNonceError, type FetcherConfig, RedirectConnectAccountOptions, ConnectAccountRedirectResult, ResponseType, ConnectError, CustomTokenExchangeOptions, TokenEndpointResponse, ClientConfiguration, } from '@auth0/auth0-spa-js';
+export { AuthorizationParams, PopupLoginOptions, PopupConfigOptions, GetTokenWithPopupOptions, LogoutUrlOptions, CacheLocation, GetTokenSilentlyOptions, IdToken, User, ICache, InMemoryCache, LocalStorageCache, Cacheable, TimeoutError, MfaRequiredError, PopupCancelledError, PopupTimeoutError, AuthenticationError, MissingRefreshTokenError, GenericError, UseDpopNonceError, type FetcherConfig, RedirectConnectAccountOptions, ConnectAccountRedirectResult, ResponseType, ConnectError, CustomTokenExchangeOptions, TokenEndpointResponse, ClientConfiguration, type MfaApiClient, type Authenticator, type MfaFactorType, type EnrollParams, type EnrollOtpParams, type EnrollSmsParams, type EnrollVoiceParams, type EnrollEmailParams, type EnrollPushParams, type EnrollmentResponse, type ChallengeAuthenticatorParams, type ChallengeResponse, type VerifyParams, type EnrollmentFactor, MfaError, MfaListAuthenticatorsError, MfaEnrollmentError, MfaChallengeError, MfaVerifyError, MfaEnrollmentFactorsError, } from '@auth0/auth0-spa-js';
 export { OAuthError } from './errors';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,IAAI,aAAa,EACxB,oBAAoB,EACpB,QAAQ,EACR,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EACL,OAAO,IAAI,0BAA0B,EACrC,iCAAiC,GAClC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,OAAO,IAAI,YAAY,EACvB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,OAAO,EACP,IAAI,EACJ,MAAM,EACN,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,KAAK,aAAa,EAClB,6BAA6B,EAC7B,4BAA4B,EAC5B,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,IAAI,aAAa,EACxB,oBAAoB,EACpB,QAAQ,EACR,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EACL,OAAO,IAAI,0BAA0B,EACrC,iCAAiC,GAClC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,OAAO,IAAI,YAAY,EACvB,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,OAAO,EACP,IAAI,EACJ,MAAM,EACN,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,iBAAiB,EACjB,KAAK,aAAa,EAClB,6BAA6B,EAC7B,4BAA4B,EAC5B,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EAEnB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAErB,QAAQ,EACR,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/use-auth0.d.ts

@@ -12,7 +12,8 @@ import { Auth0ContextInterface } from './auth0-context';
  *   getAccessTokenSilently,
  *   getAccessTokenWithPopup,
  *   getIdTokenClaims,
- *   exchangeToken,
+ *   loginWithCustomTokenExchange,
+ *   exchangeToken, // deprecated - use loginWithCustomTokenExchange
  *   loginWithRedirect,
  *   loginWithPopup,
  *   logout,

package/dist/use-auth0.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-auth0.d.ts","sourceRoot":"","sources":["../src/use-auth0.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,QAAA,MAAM,QAAQ,GAAI,KAAK,SAAS,IAAI,GAAG,IAAI,EACzC,8DAAsB,KACrB,qBAAqB,CAAC,KAAK,CACuB,CAAC;AAEtD,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"use-auth0.d.ts","sourceRoot":"","sources":["../src/use-auth0.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAC3C,OAAqB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,QAAA,MAAM,QAAQ,GAAI,KAAK,SAAS,IAAI,GAAG,IAAI,EACzC,8DAAsB,KACrB,qBAAqB,CAAC,KAAK,CACuB,CAAC;AAEtD,eAAe,QAAQ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "Auth0",
   "name": "@auth0/auth0-react",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "Auth0 SDK for React Single Page Applications (SPA)",
   "keywords": [
     "auth0",
@@ -58,7 +58,7 @@
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.2",
     "@types/jest": "^29.5.14",
-    "@types/react": "19.2.10",
+    "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.36.0",
     "@typescript-eslint/parser": "^8.36.0",
@@ -95,6 +95,6 @@
     "react-dom": "^16.11.0 || ^17 || ^18 || ~19.0.1 || ~19.1.2 || ^19.2.1"
   },
   "dependencies": {
-    "@auth0/auth0-spa-js": "^2.12.0"
+    "@auth0/auth0-spa-js": "^2.15.0"
   }
 }

package/src/auth0-context.tsx

@@ -13,7 +13,8 @@ import {
   RedirectConnectAccountOptions,
   ConnectAccountRedirectResult,
   CustomTokenExchangeOptions,
-  TokenEndpointResponse
+  TokenEndpointResponse,
+  type MfaApiClient
 } from '@auth0/auth0-spa-js';
 import { createContext } from 'react';
 import { AuthState, initialAuthState } from './auth-state';
@@ -93,6 +94,60 @@ export interface Auth0ContextInterface<TUser extends User = User>
   getIdTokenClaims: () => Promise<IdToken | undefined>;
 
   /**
+   * ```js
+   * await loginWithCustomTokenExchange(options);
+   * ```
+   *
+   * Exchanges an external subject token for Auth0 tokens and logs the user in.
+   * This method implements the Custom Token Exchange grant as specified in RFC 8693.
+   *
+   * The exchanged tokens are automatically cached, establishing an authenticated session.
+   * After calling this method, you can use `getUser()`, `getIdTokenClaims()`, and
+   * `getTokenSilently()` to access the user's information and tokens.
+   *
+   * @param options - The options required to perform the token exchange.
+   *
+   * @returns A promise that resolves to the token endpoint response,
+   * which contains the issued Auth0 tokens (access_token, id_token, etc.).
+   *
+   * The request includes the following parameters:
+   * - `grant_type`: "urn:ietf:params:oauth:grant-type:token-exchange"
+   * - `subject_token`: The external token to exchange
+   * - `subject_token_type`: The type identifier of the external token
+   * - `scope`: Merged scopes from the request and SDK defaults
+   * - `audience`: Target audience (defaults to SDK configuration)
+   * - `organization`: Optional organization ID/name for org-scoped authentication
+   *
+   * **Example Usage:**
+   *
+   * ```js
+   * const options = {
+   *   subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
+   *   subject_token_type: 'urn:acme:legacy-system-token',
+   *   scope: 'openid profile email',
+   *   audience: 'https://api.example.com',
+   *   organization: 'org_12345'
+   * };
+   *
+   * try {
+   *   const tokenResponse = await loginWithCustomTokenExchange(options);
+   *   console.log('Access token:', tokenResponse.access_token);
+   *
+   *   // User is now logged in - access user info
+   *   const user = await getUser();
+   *   console.log('Logged in user:', user);
+   * } catch (error) {
+   *   console.error('Token exchange failed:', error);
+   * }
+   * ```
+   */
+  loginWithCustomTokenExchange: (
+    options: CustomTokenExchangeOptions
+  ) => Promise<TokenEndpointResponse>;
+
+  /**
+   * @deprecated Use `loginWithCustomTokenExchange()` instead. This method will be removed in the next major version.
+   *
    * ```js
    * const tokenResponse = await exchangeToken({
    *   subject_token: 'external_token_value',
@@ -101,18 +156,20 @@ export interface Auth0ContextInterface<TUser extends User = User>
    * });
    * ```
    *
-   * Exchanges an external subject token for Auth0 tokens via a token exchange request.
+   * Exchanges an external subject token for Auth0 tokens and logs the user in.
    *
    * This method implements the token exchange grant as specified in RFC 8693.
    * It performs a token exchange by sending a request to the `/oauth/token` endpoint
    * with the external token and returns Auth0 tokens (access token, ID token, etc.).
    *
-   * The request includes the following parameters:
-   * - `grant_type`: Hard-coded to "urn:ietf:params:oauth:grant-type:token-exchange"
-   * - `subject_token`: The external token to be exchanged
-   * - `subject_token_type`: A namespaced URI identifying the token type (must be under your organization's control)
-   * - `audience`: The target audience (falls back to the SDK's default audience if not provided)
-   * - `scope`: Space-separated list of scopes (merged with the SDK's default scopes)
+   * **Example:**
+   * ```js
+   * // Instead of:
+   * const tokens = await exchangeToken(options);
+   *
+   * // Use:
+   * const tokens = await loginWithCustomTokenExchange(options);
+   * ```
    *
    * @param options - The options required to perform the token exchange
    * @returns A promise that resolves to the token endpoint response containing Auth0 tokens
@@ -252,6 +309,60 @@ export interface Auth0ContextInterface<TUser extends User = User>
    * containing the domain and clientId.
    */
   getConfiguration: Auth0Client['getConfiguration'];
+
+  /**
+   * ```js
+   * const { mfa } = useAuth0();
+   * const authenticators = await mfa.getAuthenticators(mfaToken);
+   * ```
+   *
+   * MFA API client for Multi-Factor Authentication operations.
+   *
+   * Provides access to all MFA-related methods:
+   * - `getAuthenticators(mfaToken)` - List enrolled authenticators
+   * - `enroll(params)` - Enroll new authenticators (OTP, SMS, Voice, Email, Push)
+   * - `challenge(params)` - Initiate MFA challenges
+   * - `verify(params)` - Verify MFA challenges and complete authentication
+   * - `getEnrollmentFactors(mfaToken)` - Get available enrollment factors
+   *
+   * @example
+   * ```js
+   * const { mfa, getAccessTokenSilently } = useAuth0();
+   *
+   * try {
+   *   await getAccessTokenSilently();
+   * } catch (error) {
+   *   if (error.error === 'mfa_required') {
+   *     // Check if enrollment is needed
+   *     const factors = await mfa.getEnrollmentFactors(error.mfa_token);
+   *
+   *     if (factors.length > 0) {
+   *       // Enroll in OTP
+   *       const enrollment = await mfa.enroll({
+   *         mfaToken: error.mfa_token,
+   *         factorType: 'otp'
+   *       });
+   *       console.log('QR Code:', enrollment.barcodeUri);
+   *     }
+   *
+   *     // Get authenticators and challenge
+   *     const authenticators = await mfa.getAuthenticators(error.mfa_token);
+   *     await mfa.challenge({
+   *       mfaToken: error.mfa_token,
+   *       challengeType: 'otp',
+   *       authenticatorId: authenticators[0].id
+   *     });
+   *
+   *     // Verify with user's code
+   *     const tokens = await mfa.verify({
+   *       mfaToken: error.mfa_token,
+   *       otp: userCode
+   *     });
+   *   }
+   * }
+   * ```
+   */
+  mfa: MfaApiClient;
 }
 
 /**
@@ -271,6 +382,7 @@ export const initialContext = {
   getAccessTokenSilently: stub,
   getAccessTokenWithPopup: stub,
   getIdTokenClaims: stub,
+  loginWithCustomTokenExchange: stub,
   exchangeToken: stub,
   loginWithRedirect: stub,
   loginWithPopup: stub,
@@ -282,6 +394,13 @@ export const initialContext = {
   generateDpopProof: stub,
   createFetcher: stub,
   getConfiguration: stub,
+  mfa: {
+    getAuthenticators: stub,
+    enroll: stub,
+    challenge: stub,
+    verify: stub,
+    getEnrollmentFactors: stub,
+  } as unknown as MfaApiClient,
 };
 
 /**

package/src/auth0-provider.tsx

@@ -279,19 +279,19 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
-  const exchangeToken = useCallback(
+  const loginWithCustomTokenExchange = useCallback(
     async (
       options: CustomTokenExchangeOptions
     ): Promise<TokenEndpointResponse> => {
       let tokenResponse;
       try {
-        tokenResponse = await client.exchangeToken(options);
+        tokenResponse = await client.loginWithCustomTokenExchange(options);
       } catch (error) {
         throw tokenError(error);
       } finally {
-        // We dispatch the standard GET_ACCESS_TOKEN_COMPLETE action here to maintain 
-        // backward compatibility and consistency with the getAccessTokenSilently flow. 
-        // This ensures the SDK's internal state lifecycle (loading/user updates) remains 
+        // We dispatch the standard GET_ACCESS_TOKEN_COMPLETE action here to maintain
+        // backward compatibility and consistency with the getAccessTokenSilently flow.
+        // This ensures the SDK's internal state lifecycle (loading/user updates) remains
         // identical regardless of whether the token was retrieved via silent auth or CTE.
         dispatch({
           type: 'GET_ACCESS_TOKEN_COMPLETE',
@@ -303,6 +303,15 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
+  const exchangeToken = useCallback(
+    async (
+      options: CustomTokenExchangeOptions
+    ): Promise<TokenEndpointResponse> => {
+      return loginWithCustomTokenExchange(options);
+    },
+    [loginWithCustomTokenExchange]
+  );
+
   const handleRedirectCallback = useCallback(
     async (
       url?: string
@@ -346,12 +355,15 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     [client]
   );
 
+  const mfa = useMemo(() => client.mfa, [client]);
+
   const contextValue = useMemo<Auth0ContextInterface<TUser>>(() => {
     return {
       ...state,
       getAccessTokenSilently,
       getAccessTokenWithPopup,
       getIdTokenClaims,
+      loginWithCustomTokenExchange,
       exchangeToken,
       loginWithRedirect,
       loginWithPopup,
@@ -363,12 +375,14 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
       generateDpopProof,
       createFetcher,
       getConfiguration,
+      mfa,
     };
   }, [
     state,
     getAccessTokenSilently,
     getAccessTokenWithPopup,
     getIdTokenClaims,
+    loginWithCustomTokenExchange,
     exchangeToken,
     loginWithRedirect,
     loginWithPopup,
@@ -380,6 +394,7 @@ const Auth0Provider = <TUser extends User = User>(opts: Auth0ProviderOptions<TUs
     generateDpopProof,
     createFetcher,
     getConfiguration,
+    mfa,
   ]);
 
   return <context.Provider value={contextValue}>{children}</context.Provider>;

package/src/index.tsx

@@ -47,5 +47,27 @@ export {
   CustomTokenExchangeOptions,
   TokenEndpointResponse,
   ClientConfiguration,
+  // MFA Types
+  type MfaApiClient,
+  type Authenticator,
+  type MfaFactorType,
+  type EnrollParams,
+  type EnrollOtpParams,
+  type EnrollSmsParams,
+  type EnrollVoiceParams,
+  type EnrollEmailParams,
+  type EnrollPushParams,
+  type EnrollmentResponse,
+  type ChallengeAuthenticatorParams,
+  type ChallengeResponse,
+  type VerifyParams,
+  type EnrollmentFactor,
+  // MFA Errors
+  MfaError,
+  MfaListAuthenticatorsError,
+  MfaEnrollmentError,
+  MfaChallengeError,
+  MfaVerifyError,
+  MfaEnrollmentFactorsError,
 } from '@auth0/auth0-spa-js';
 export { OAuthError } from './errors';

package/src/use-auth0.tsx

@@ -14,7 +14,8 @@ import Auth0Context, { Auth0ContextInterface } from './auth0-context';
  *   getAccessTokenSilently,
  *   getAccessTokenWithPopup,
  *   getIdTokenClaims,
- *   exchangeToken,
+ *   loginWithCustomTokenExchange,
+ *   exchangeToken, // deprecated - use loginWithCustomTokenExchange
  *   loginWithRedirect,
  *   loginWithPopup,
  *   logout,