[Native Auth] Add MFA related states and results (#8060)

Author: shenj

change/@azure-msal-browser-bdfa211a-74c7-4a1c-b8fa-1417e02d99b4.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "[Native Auth] Add MFA related state and results",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/src/custom_auth/core/auth_flow/AuthFlowErrorBase.ts

@@ -66,7 +66,9 @@ export abstract class AuthFlowErrorBase {
                 this.errorData.subError ===
                     CustomAuthApiSuberror.INVALID_OOB_VALUE) ||
             (this.errorData instanceof InvalidArgumentError &&
-                this.errorData.errorDescription?.includes("code") === true)
+                (this.errorData.errorDescription?.includes("code") ||
+                    this.errorData.errorDescription?.includes("challenge")) ===
+                    true)
         );
     }
 
@@ -140,13 +142,24 @@ export abstract class AuthFlowErrorBase {
         );
     }
 
-    protected isInvalidAuthMethodRegistrationInputError(): boolean {
+    protected isInvalidInputError(): boolean {
         return (
             this.errorData instanceof CustomAuthApiError &&
             this.errorData.error === CustomAuthApiErrorCode.INVALID_REQUEST &&
             this.errorData.errorCodes?.includes(901001) === true
         );
     }
+
+    protected isVerificationContactBlockedError(): boolean {
+        return (
+            this.errorData instanceof CustomAuthApiError &&
+            this.errorData.error === CustomAuthApiErrorCode.INVALID_REQUEST &&
+            this.errorData.errorCodes?.includes(550024) === true &&
+            this.errorData.errorDescription?.includes(
+                "multi-factor authentication method is blocked"
+            ) === true
+        );
+    }
 }
 
 export abstract class AuthActionErrorBase extends AuthFlowErrorBase {

lib/msal-browser/src/custom_auth/core/auth_flow/jit/error_type/AuthMethodRegistrationError.ts

@@ -14,7 +14,15 @@ export class AuthMethodRegistrationChallengeMethodError extends AuthActionErrorB
      * @returns true if the input is incorrect, false otherwise.
      */
     isInvalidInput(): boolean {
-        return this.isInvalidAuthMethodRegistrationInputError();
+        return this.isInvalidInputError();
+    }
+
+    /**
+     * Checks if the error is due to the verification contact (e.g., phone number or email) being blocked. Consider using a different email/phone number or a different authentication method.
+     * @returns true if the error is due to the verification contact being blocked, false otherwise.
+     */
+    isVerificationContactBlocked(): boolean {
+        return this.isVerificationContactBlockedError();
     }
 }
 

lib/msal-browser/src/custom_auth/core/auth_flow/mfa/error_type/MfaError.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthActionErrorBase } from "../../AuthFlowErrorBase.js";
+
+/**
+ * Error that occurred during MFA challenge request.
+ */
+export class MfaRequestChallengeError extends AuthActionErrorBase {
+    /**
+     * Checks if the input for MFA challenge is incorrect.
+     * @returns true if the input is incorrect, false otherwise.
+     */
+    isInvalidInput(): boolean {
+        return this.isInvalidInputError();
+    }
+}
+
+/**
+ * Error that occurred during MFA challenge submission.
+ */
+export class MfaSubmitChallengeError extends AuthActionErrorBase {
+    /**
+     * Checks if the submitted challenge code (e.g., OTP code) is incorrect.
+     * @returns true if the challenge code is invalid, false otherwise.
+     */
+    isIncorrectChallenge(): boolean {
+        return this.isInvalidCodeError();
+    }
+}

lib/msal-browser/src/custom_auth/core/auth_flow/mfa/result/MfaRequestChallengeResult.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { MfaRequestChallengeError } from "../error_type/MfaError.js";
+import { MfaFailedState } from "../state/MfaFailedState.js";
+import type { MfaVerificationRequiredState } from "../state/MfaState.js";
+
+/**
+ * Result of requesting an MFA challenge.
+ * Uses base state type to avoid circular dependencies.
+ */
+export class MfaRequestChallengeResult extends AuthFlowResultBase<
+    MfaRequestChallengeResultState,
+    MfaRequestChallengeError
+> {
+    /**
+     * Creates an MfaRequestChallengeResult with an error.
+     * @param error The error that occurred.
+     * @returns The MfaRequestChallengeResult with error.
+     */
+    static createWithError(error: unknown): MfaRequestChallengeResult {
+        const result = new MfaRequestChallengeResult(new MfaFailedState());
+        result.error = new MfaRequestChallengeError(
+            MfaRequestChallengeResult.createErrorData(error)
+        );
+        return result;
+    }
+
+    /**
+     * Checks if the result indicates that verification is required.
+     * @returns true if verification is required, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isVerificationRequired(): boolean {
+        return this.state.constructor?.name === "MfaVerificationRequiredState";
+    }
+
+    /**
+     * Checks if the result is in a failed state.
+     * @returns true if the result is failed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isFailed(): boolean {
+        return this.state instanceof MfaFailedState;
+    }
+}
+
+/**
+ * The possible states for the MfaRequestChallengeResult.
+ * This includes:
+ * - MfaVerificationRequiredState: The user needs to verify their challenge.
+ * - MfaFailedState: The MFA request failed.
+ */
+export type MfaRequestChallengeResultState =
+    | MfaVerificationRequiredState
+    | MfaFailedState;

lib/msal-browser/src/custom_auth/core/auth_flow/mfa/result/MfaSubmitChallengeResult.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { MfaSubmitChallengeError } from "../error_type/MfaError.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import { MfaCompletedState } from "../state/MfaCompletedState.js";
+import { MfaFailedState } from "../state/MfaFailedState.js";
+
+/**
+ * Result of submitting an MFA challenge.
+ */
+export class MfaSubmitChallengeResult extends AuthFlowResultBase<
+    MfaSubmitChallengeResultState,
+    MfaSubmitChallengeError,
+    CustomAuthAccountData
+> {
+    /**
+     * Creates an MfaSubmitChallengeResult with an error.
+     * @param error The error that occurred.
+     * @returns The MfaSubmitChallengeResult with error.
+     */
+    static createWithError(error: unknown): MfaSubmitChallengeResult {
+        const result = new MfaSubmitChallengeResult(new MfaFailedState());
+        result.error = new MfaSubmitChallengeError(
+            MfaSubmitChallengeResult.createErrorData(error)
+        );
+        return result;
+    }
+
+    /**
+     * Checks if the MFA flow is completed successfully.
+     * @returns true if completed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isCompleted(): boolean {
+        return this.state instanceof MfaCompletedState;
+    }
+
+    /**
+     * Checks if the result is in a failed state.
+     * @returns true if the result is failed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isFailed(): boolean {
+        return this.state instanceof MfaFailedState;
+    }
+}
+
+export type MfaSubmitChallengeResultState = MfaCompletedState | MfaFailedState;

lib/msal-browser/src/custom_auth/core/auth_flow/mfa/state/MfaCompletedState.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+/**
+ * State indicating that the MFA flow has completed successfully.
+ */
+export class MfaCompletedState extends AuthFlowStateBase {}

lib/msal-browser/src/custom_auth/core/auth_flow/mfa/state/MfaFailedState.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+/**
+ * State indicating that the MFA flow has failed.
+ */
+export class MfaFailedState extends AuthFlowStateBase {}