@azure/msal-browser 4.22.1 → 4.24.0

package/src/custom_auth/core/auth_flow/jit/result/AuthMethodRegistrationChallengeMethodResult.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { AuthMethodRegistrationChallengeMethodError } from "../error_type/AuthMethodRegistrationError.js";
+import type { AuthMethodVerificationRequiredState } from "../state/AuthMethodRegistrationState.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import { AuthMethodRegistrationCompletedState } from "../state/AuthMethodRegistrationCompletedState.js";
+import { AuthMethodRegistrationFailedState } from "../state/AuthMethodRegistrationFailedState.js";
+
+/**
+ * Result of challenging an authentication method for registration.
+ * Uses base state type to avoid circular dependencies.
+ */
+export class AuthMethodRegistrationChallengeMethodResult extends AuthFlowResultBase<
+    AuthMethodRegistrationChallengeMethodResultState,
+    AuthMethodRegistrationChallengeMethodError,
+    CustomAuthAccountData
+> {
+    /**
+     * Creates an AuthMethodRegistrationChallengeMethodResult with an error.
+     * @param error The error that occurred.
+     * @returns The AuthMethodRegistrationChallengeMethodResult with error.
+     */
+    static createWithError(
+        error: unknown
+    ): AuthMethodRegistrationChallengeMethodResult {
+        const result = new AuthMethodRegistrationChallengeMethodResult(
+            new AuthMethodRegistrationFailedState()
+        );
+        result.error = new AuthMethodRegistrationChallengeMethodError(
+            AuthMethodRegistrationChallengeMethodResult.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 ===
+            "AuthMethodVerificationRequiredState"
+        );
+    }
+
+    /**
+     * Checks if the result indicates that registration is completed (fast-pass scenario).
+     * @returns true if registration is 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.constructor?.name ===
+            "AuthMethodRegistrationCompletedState"
+        );
+    }
+
+    /**
+     * 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 AuthMethodRegistrationFailedState;
+    }
+}
+
+/**
+ * Type definition for possible states in AuthMethodRegistrationChallengeMethodResult.
+ */
+export type AuthMethodRegistrationChallengeMethodResultState =
+    | AuthMethodVerificationRequiredState
+    | AuthMethodRegistrationCompletedState
+    | AuthMethodRegistrationFailedState;

package/src/custom_auth/core/auth_flow/jit/result/AuthMethodRegistrationSubmitChallengeResult.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { AuthMethodRegistrationSubmitChallengeError } from "../error_type/AuthMethodRegistrationError.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import { AuthMethodRegistrationFailedState } from "../state/AuthMethodRegistrationFailedState.js";
+import { AuthMethodRegistrationCompletedState } from "../state/AuthMethodRegistrationCompletedState.js";
+
+/**
+ * Result of submitting a challenge for authentication method registration.
+ */
+export class AuthMethodRegistrationSubmitChallengeResult extends AuthFlowResultBase<
+    AuthMethodRegistrationSubmitChallengeResultState,
+    AuthMethodRegistrationSubmitChallengeError,
+    CustomAuthAccountData
+> {
+    /**
+     * Creates an AuthMethodRegistrationSubmitChallengeResult with an error.
+     * @param error The error that occurred.
+     * @returns The AuthMethodRegistrationSubmitChallengeResult with error.
+     */
+    static createWithError(
+        error: unknown
+    ): AuthMethodRegistrationSubmitChallengeResult {
+        const result = new AuthMethodRegistrationSubmitChallengeResult(
+            new AuthMethodRegistrationFailedState()
+        );
+        result.error = new AuthMethodRegistrationSubmitChallengeError(
+            AuthMethodRegistrationSubmitChallengeResult.createErrorData(error)
+        );
+        return result;
+    }
+
+    /**
+     * Checks if the result indicates that registration is completed.
+     * @returns true if registration is 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.constructor?.name ===
+            "AuthMethodRegistrationCompletedState"
+        );
+    }
+
+    /**
+     * 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 AuthMethodRegistrationFailedState;
+    }
+}
+
+/**
+ * Type definition for possible states in AuthMethodRegistrationSubmitChallengeResult.
+ */
+export type AuthMethodRegistrationSubmitChallengeResultState =
+    | AuthMethodRegistrationCompletedState
+    | AuthMethodRegistrationFailedState;

package/src/custom_auth/core/auth_flow/jit/state/AuthMethodRegistrationCompletedState.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+export class AuthMethodRegistrationCompletedState extends AuthFlowStateBase {}

package/src/custom_auth/core/auth_flow/jit/state/AuthMethodRegistrationFailedState.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+export class AuthMethodRegistrationFailedState extends AuthFlowStateBase {}

package/src/custom_auth/core/auth_flow/jit/state/AuthMethodRegistrationState.ts

@@ -0,0 +1,260 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    AuthMethodRegistrationStateParameters,
+    AuthMethodRegistrationRequiredStateParameters,
+    AuthMethodVerificationRequiredStateParameters,
+} from "./AuthMethodRegistrationStateParameters.js";
+import { AuthMethodDetails } from "../AuthMethodDetails.js";
+import {
+    JitChallengeAuthMethodParams,
+    JitSubmitChallengeParams,
+} from "../../../interaction_client/jit/parameter/JitParams.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import {
+    JIT_VERIFICATION_REQUIRED_RESULT_TYPE,
+    JIT_COMPLETED_RESULT_TYPE,
+} from "../../../interaction_client/jit/result/JitActionResult.js";
+import { UnexpectedError } from "../../../error/UnexpectedError.js";
+import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
+import { AuthFlowActionRequiredStateBase } from "../../AuthFlowState.js";
+import { GrantType } from "../../../../CustomAuthConstants.js";
+import { AuthMethodRegistrationChallengeMethodResult } from "../result/AuthMethodRegistrationChallengeMethodResult.js";
+import { AuthMethodRegistrationSubmitChallengeResult } from "../result/AuthMethodRegistrationSubmitChallengeResult.js";
+import { AuthMethodRegistrationCompletedState } from "./AuthMethodRegistrationCompletedState.js";
+
+/**
+ * Abstract base class for authentication method registration states.
+ */
+abstract class AuthMethodRegistrationState<
+    TParameters extends AuthMethodRegistrationStateParameters
+> extends AuthFlowActionRequiredStateBase<TParameters> {
+    /**
+     * Internal method to challenge an authentication method.
+     * @param authMethodDetails The authentication method details to challenge.
+     * @returns Promise that resolves to AuthMethodRegistrationChallengeMethodResult.
+     */
+    protected async challengeAuthMethodInternal(
+        authMethodDetails: AuthMethodDetails
+    ): Promise<AuthMethodRegistrationChallengeMethodResult> {
+        try {
+            this.stateParameters.logger.verbose(
+                `Challenging authentication method - '${authMethodDetails.authMethodType.id}' for auth method registration.`,
+                this.stateParameters.correlationId
+            );
+
+            const challengeParams: JitChallengeAuthMethodParams = {
+                correlationId: this.stateParameters.correlationId,
+                continuationToken: this.stateParameters.continuationToken ?? "",
+                authMethod: authMethodDetails.authMethodType,
+                verificationContact: authMethodDetails.verificationContact,
+                scopes: this.stateParameters.scopes ?? [],
+                username: this.stateParameters.username,
+                claims: this.stateParameters.claims,
+            };
+
+            const result =
+                await this.stateParameters.jitClient.challengeAuthMethod(
+                    challengeParams
+                );
+
+            this.stateParameters.logger.verbose(
+                "Authentication method challenged successfully for auth method registration.",
+                this.stateParameters.correlationId
+            );
+
+            if (result.type === JIT_VERIFICATION_REQUIRED_RESULT_TYPE) {
+                // Verification required
+                this.stateParameters.logger.verbose(
+                    "Auth method verification required.",
+                    this.stateParameters.correlationId
+                );
+
+                return new AuthMethodRegistrationChallengeMethodResult(
+                    new AuthMethodVerificationRequiredState({
+                        correlationId: result.correlationId,
+                        continuationToken: result.continuationToken,
+                        config: this.stateParameters.config,
+                        logger: this.stateParameters.logger,
+                        jitClient: this.stateParameters.jitClient,
+                        cacheClient: this.stateParameters.cacheClient,
+                        challengeChannel: result.challengeChannel,
+                        challengeTargetLabel: result.challengeTargetLabel,
+                        codeLength: result.codeLength,
+                        scopes: this.stateParameters.scopes ?? [],
+                        username: this.stateParameters.username,
+                        claims: this.stateParameters.claims,
+                    })
+                );
+            } else if (result.type === JIT_COMPLETED_RESULT_TYPE) {
+                // Registration completed (fast-pass scenario)
+                this.stateParameters.logger.verbose(
+                    "Auth method registration completed via fast-pass.",
+                    this.stateParameters.correlationId
+                );
+
+                const accountInfo = new CustomAuthAccountData(
+                    result.authenticationResult.account,
+                    this.stateParameters.config,
+                    this.stateParameters.cacheClient,
+                    this.stateParameters.logger,
+                    this.stateParameters.correlationId
+                );
+
+                return new AuthMethodRegistrationChallengeMethodResult(
+                    new AuthMethodRegistrationCompletedState(),
+                    accountInfo
+                );
+            } else {
+                // Handle unexpected result type with proper typing
+                this.stateParameters.logger.error(
+                    "Unexpected result type from auth challenge method",
+                    this.stateParameters.correlationId
+                );
+                throw new UnexpectedError(
+                    "Unexpected result type from auth challenge method"
+                );
+            }
+        } catch (error) {
+            this.stateParameters.logger.error(
+                "Failed to challenge authentication method for auth method registration.",
+                this.stateParameters.correlationId
+            );
+            return AuthMethodRegistrationChallengeMethodResult.createWithError(
+                error
+            );
+        }
+    }
+}
+
+/**
+ * State indicating that authentication method registration is required.
+ */
+export class AuthMethodRegistrationRequiredState extends AuthMethodRegistrationState<AuthMethodRegistrationRequiredStateParameters> {
+    /**
+     * Gets the available authentication methods for registration.
+     * @returns Array of available authentication methods.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getAuthMethods(): AuthenticationMethod[] {
+        return this.stateParameters.authMethods;
+    }
+
+    /**
+     * Challenges an authentication method for registration.
+     * @param authMethodDetails The authentication method details to challenge.
+     * @returns Promise that resolves to AuthMethodRegistrationChallengeMethodResult.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    async challengeAuthMethod(
+        authMethodDetails: AuthMethodDetails
+    ): Promise<AuthMethodRegistrationChallengeMethodResult> {
+        return this.challengeAuthMethodInternal(authMethodDetails);
+    }
+}
+
+/**
+ * State indicating that verification is required for the challenged authentication method.
+ */
+export class AuthMethodVerificationRequiredState extends AuthMethodRegistrationState<AuthMethodVerificationRequiredStateParameters> {
+    /**
+     * Gets the length of the expected verification code.
+     * @returns The code length.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getCodeLength(): number {
+        return this.stateParameters.codeLength;
+    }
+
+    /**
+     * Gets the channel through which the challenge was sent.
+     * @returns The challenge channel (e.g., "email").
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getChannel(): string {
+        return this.stateParameters.challengeChannel;
+    }
+
+    /**
+     * Gets the target label indicating where the challenge was sent.
+     * @returns The challenge target label (e.g., masked email address).
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getSentTo(): string {
+        return this.stateParameters.challengeTargetLabel;
+    }
+
+    /**
+     * Submits the verification challenge to complete the authentication method registration.
+     * @param code The verification code entered by the user.
+     * @returns Promise that resolves to AuthMethodRegistrationSubmitChallengeResult.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    async submitChallenge(
+        code: string
+    ): Promise<AuthMethodRegistrationSubmitChallengeResult> {
+        try {
+            this.ensureCodeIsValid(code, this.getCodeLength());
+
+            this.stateParameters.logger.verbose(
+                "Submitting auth method challenge.",
+                this.stateParameters.correlationId
+            );
+
+            const submitParams: JitSubmitChallengeParams = {
+                correlationId: this.stateParameters.correlationId,
+                continuationToken: this.stateParameters.continuationToken ?? "",
+                scopes: this.stateParameters.scopes ?? [],
+                grantType: GrantType.OOB,
+                challenge: code,
+                username: this.stateParameters.username,
+                claims: this.stateParameters.claims,
+            };
+
+            const result = await this.stateParameters.jitClient.submitChallenge(
+                submitParams
+            );
+
+            this.stateParameters.logger.verbose(
+                "Auth method challenge submitted successfully.",
+                this.stateParameters.correlationId
+            );
+
+            const accountInfo = new CustomAuthAccountData(
+                result.authenticationResult.account,
+                this.stateParameters.config,
+                this.stateParameters.cacheClient,
+                this.stateParameters.logger,
+                this.stateParameters.correlationId
+            );
+
+            return new AuthMethodRegistrationSubmitChallengeResult(
+                new AuthMethodRegistrationCompletedState(),
+                accountInfo
+            );
+        } catch (error) {
+            this.stateParameters.logger.error(
+                "Failed to submit auth method challenge.",
+                this.stateParameters.correlationId
+            );
+            return AuthMethodRegistrationSubmitChallengeResult.createWithError(
+                error
+            );
+        }
+    }
+
+    /**
+     * Challenges a different authentication method for registration.
+     * @param authMethodDetails The authentication method details to challenge.
+     * @returns Promise that resolves to AuthMethodRegistrationChallengeMethodResult.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    async challengeAuthMethod(
+        authMethodDetails: AuthMethodDetails
+    ): Promise<AuthMethodRegistrationChallengeMethodResult> {
+        return this.challengeAuthMethodInternal(authMethodDetails);
+    }
+}

package/src/custom_auth/core/auth_flow/jit/state/AuthMethodRegistrationStateParameters.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowActionRequiredStateParameters } from "../../AuthFlowState.js";
+import { JitClient } from "../../../interaction_client/jit/JitClient.js";
+import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
+import { CustomAuthSilentCacheClient } from "../../../../get_account/interaction_client/CustomAuthSilentCacheClient.js";
+
+export interface AuthMethodRegistrationStateParameters
+    extends AuthFlowActionRequiredStateParameters {
+    jitClient: JitClient;
+    cacheClient: CustomAuthSilentCacheClient;
+    scopes?: string[];
+    username?: string;
+    claims?: string;
+}
+
+export interface AuthMethodRegistrationRequiredStateParameters
+    extends AuthMethodRegistrationStateParameters {
+    authMethods: AuthenticationMethod[];
+}
+
+export interface AuthMethodVerificationRequiredStateParameters
+    extends AuthMethodRegistrationStateParameters {
+    challengeChannel: string;
+    challengeTargetLabel: string;
+    codeLength: number;
+}

package/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();
+    }
+}

package/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;

package/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;

package/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 {}

package/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 {}