@auth0/auth0-spa-js 2.11.3 → 2.13.0

package/src/mfa/errors.ts

@@ -0,0 +1,154 @@
+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 class MfaError extends GenericError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaError.prototype);
+  }
+
+  static fromPayload({
+    error,
+    error_description
+  }: {
+    error: string;
+    error_description: string;
+  }) {
+    return new MfaError(error, error_description);
+  }
+}
+
+/**
+ * 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 class MfaListAuthenticatorsError extends MfaError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaListAuthenticatorsError.prototype);
+  }
+}
+
+/**
+ * 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 class MfaEnrollmentError extends MfaError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaEnrollmentError.prototype);
+  }
+}
+
+/**
+ * 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 class MfaChallengeError extends MfaError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaChallengeError.prototype);
+  }
+}
+
+/**
+ * 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 class MfaVerifyError extends MfaError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaVerifyError.prototype);
+  }
+}
+
+/**
+ * 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 class MfaEnrollmentFactorsError extends MfaError {
+  constructor(error: string, error_description: string) {
+    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
+    Object.setPrototypeOf(this, MfaEnrollmentFactorsError.prototype);
+  }
+}
+
+/**
+ * Re-export MfaApiErrorResponse type for convenience
+ */
+export type { MfaApiErrorResponse };

package/src/mfa/index.ts

@@ -0,0 +1,24 @@
+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';

package/src/mfa/types.ts

@@ -0,0 +1,209 @@
+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/src/mfa/utils.ts

@@ -0,0 +1,41 @@
+import { FACTOR_MAPPING, MfaGrantTypes } from './constants';
+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 function getAuthJsEnrollParams(params: EnrollParams) {
+  const mapping = FACTOR_MAPPING[params.factorType];
+
+  return {
+    mfaToken: params.mfaToken,
+    authenticatorTypes: mapping.authenticatorTypes,
+    ...(mapping.oobChannels && { oobChannels: mapping.oobChannels }),
+    ...('phoneNumber' in params && { phoneNumber: params.phoneNumber }),
+    ...('email' in params && { email: params.email })
+  };
+}
+
+/**
+ * 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 function getGrantType(params: VerifyParams): MfaGrantType | undefined {
+  if ('otp' in params && params.otp) {
+    return MfaGrantTypes.OTP;
+  }
+  if ('oobCode' in params && params.oobCode) {
+    return MfaGrantTypes.OOB;
+  }
+  if ('recoveryCode' in params && params.recoveryCode) {
+    return MfaGrantTypes.RECOVERY_CODE;
+  }
+  return undefined;
+}

package/src/utils.ts

@@ -184,10 +184,16 @@ const ALLOWED_AUTH0CLIENT_PROPERTIES = [
 /**
  * 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 const stripAuth0Client = (auth0Client: any) => {
+export const stripAuth0Client = (auth0Client: any, excludeEnv = false) => {
   return Object.keys(auth0Client).reduce((acc: any, key: string) => {
+    // Exclude 'env' if requested (for /authorize query params to prevent truncation)
+    if (excludeEnv && key === 'env') {
+      return acc;
+    }
+
     const allowedProperty = ALLOWED_AUTH0CLIENT_PROPERTIES.find(
       p => p.key === key
     );

package/src/version.ts

@@ -1 +1 @@
-export default '2.11.3';
+export default '2.13.0';