chore(auth): add email otp mfa enums and types (#5237)

chore(auth): add email otp mfa enums and types (#5237)

Author: khatruong2009

.gitattributes

@@ -74,6 +74,7 @@
 
 ## Generated SDK files
 packages/**/lib/src/sdk/src/**              linguist-generated
+packages/auth/amplify_auth_cognito_dart/lib/src/sdk/sdk_exception.dart linguist-generated
 
 ## Generated Swift Plugins
 packages/amplify_datastore/ios/internal/**  linguist-generated

packages/amplify_core/doc/lib/auth.dart

@@ -104,22 +104,38 @@ Future<void> resendSignUpCode(String username) async {
 }
 // #enddocregion resend-signup-code
 
-// #docregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code
+// #docregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code, handle-confirm-signin-email-code, handle-confirm-signin-mfa-setup-selection, handle-confirm-signin-email-setup
 Future<void> _handleSignInResult(SignInResult result) async {
   switch (result.nextStep.signInStep) {
-    // #enddocregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code
+    // #enddocregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code, handle-confirm-signin-email-code, handle-confirm-signin-mfa-setup-selection, handle-confirm-signin-email-setup
     // #docregion handle-confirm-signin-mfa-selection
     case AuthSignInStep.continueSignInWithMfaSelection:
       final allowedMfaTypes = result.nextStep.allowedMfaTypes!;
       final selection = await _promptUserPreference(allowedMfaTypes);
       return _handleMfaSelection(selection);
     // #enddocregion handle-confirm-signin-mfa-selection
+    // #docregion handle-confirm-signin-mfa-setup-selection
+    case AuthSignInStep.continueSignInWithMfaSetupSelection:
+      final allowedMfaTypes = result.nextStep.allowedMfaTypes!;
+      if (allowedMfaTypes.length == 1) {
+        return _handleMfaSelection(allowedMfaTypes.first);
+      }
+      final selection = await _promptUserPreference(allowedMfaTypes);
+      safePrint('Selected MFA type: $selection');
+      return _handleMfaSelection(selection);
+    // #enddocregion handle-confirm-signin-mfa-setup-selection
     // #docregion handle-confirm-signin-totp-setup
     case AuthSignInStep.continueSignInWithTotpSetup:
       final totpSetupDetails = result.nextStep.totpSetupDetails!;
       final setupUri = totpSetupDetails.getSetupUri(appName: 'MyApp');
       safePrint('Open URI to complete setup: $setupUri');
     // #enddocregion handle-confirm-signin-totp-setup
+    // #docregion handle-confirm-signin-email-setup
+    case AuthSignInStep.continueSignInWithEmailMfaSetup:
+      safePrint(
+        'Enter the email address you want to use for two-factor authentication',
+      );
+    // #enddocregion handle-confirm-signin-email-setup
     // #docregion handle-confirm-signin-totp-code
     case AuthSignInStep.confirmSignInWithTotpMfaCode:
       safePrint('Enter a one-time code from your registered Authenticator app');
@@ -129,6 +145,11 @@ Future<void> _handleSignInResult(SignInResult result) async {
       final codeDeliveryDetails = result.nextStep.codeDeliveryDetails!;
       _handleCodeDelivery(codeDeliveryDetails);
     // #enddocregion handle-confirm-signin-sms
+    // #docregion handle-confirm-signin-email
+    case AuthSignInStep.confirmSignInWithEmailMfaCode:
+      final codeDeliveryDetails = result.nextStep.codeDeliveryDetails!;
+      _handleCodeDelivery(codeDeliveryDetails);
+    // #enddocregion handle-confirm-signin-email
     // #docregion handle-confirm-signin-new-password
     case AuthSignInStep.confirmSignInWithNewPassword:
       safePrint('Enter a new password to continue signing in');
@@ -158,10 +179,10 @@ Future<void> _handleSignInResult(SignInResult result) async {
     case AuthSignInStep.done:
       safePrint('Sign in is complete');
     // #enddocregion handle-confirm-signin-done
-    // #docregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code
+    // #docregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code, handle-confirm-signin-email-code, handle-confirm-signin-mfa-setup-selection, handle-confirm-signin-email-setup
   }
 }
-// #enddocregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code
+// #enddocregion handle-signin, handle-confirm-signin-sms, handle-confirm-signin-new-password, handle-confirm-signin-custom-challenge, handle-confirm-signin-reset-password, handle-confirm-signin-confirm-signup, handle-confirm-signin-done, handle-confirm-signin-mfa-selection, handle-confirm-signin-totp-setup, handle-confirm-signin-totp-code, handle-confirm-signin-email-code, handle-confirm-signin-mfa-setup-selection, handle-confirm-signin-email-setup
 
 // #docregion signin
 Future<void> signInUser(String username, String password) async {

packages/amplify_core/lib/src/config/amplify_outputs/auth/auth_outputs.g.dart

@@ -11,7 +11,10 @@ enum MfaMethod {
   sms,
 
   @JsonValue('TOTP')
-  totp;
+  totp,
+
+  @JsonValue('EMAIL')
+  email;
 
   /// The value to pass to `Amplify.Auth.confirmSignIn` when
   /// selecting an MFA type.

packages/amplify_core/lib/src/config/amplify_outputs/auth/mfa.dart

@@ -9,7 +9,10 @@ enum MfaType {
   sms,
 
   @JsonValue('TOTP')
-  totp;
+  totp,
+
+  @JsonValue('EMAIL')
+  email;
 
   /// The value to pass to `Amplify.Auth.confirmSignIn` when
   /// selecting an MFA type.
@@ -21,6 +24,7 @@ extension ToMfaMethod on MfaType {
     return switch (this) {
       MfaType.sms => MfaMethod.sms,
       MfaType.totp => MfaMethod.totp,
+      MfaType.email => MfaMethod.email,
     };
   }
 }

packages/amplify_core/lib/src/config/auth/cognito/auth.g.dart

@@ -10,17 +10,27 @@ enum AuthSignInStep {
   /// an MFA method.
   continueSignInWithMfaSelection,
 
+  /// The sign-in is not complete and the user must select an MFA method to setup.
+  continueSignInWithMfaSetupSelection,
+
   /// The sign-in is not complete and a TOTP authenticator app must be
   /// registered before continuing.
   continueSignInWithTotpSetup,
 
+  /// The sign-in is not complete and an Email MFA must be set up before
+  /// continuing.
+  continueSignInWithEmailMfaSetup,
+
   /// The sign-in is not complete and must be confirmed with an SMS code.
   confirmSignInWithSmsMfaCode,
 
   /// The sign-in is not complete and must be confirmed with a TOTP code
   /// from a registered authenticator app.
   confirmSignInWithTotpMfaCode,
 
+  /// The sign-in is not complete and must be confirmed with an email code.
+  confirmSignInWithEmailMfaCode,
+
   /// The sign-in is not complete and must be confirmed with the user's new
   /// password.
   confirmSignInWithNewPassword,

packages/amplify_core/lib/src/config/auth/cognito/mfa.dart

@@ -35,7 +35,7 @@ void main() {
           signInRes.nextStep.signInStep,
           because: 'MFA is required, and TOTP is chosen when '
               'no phone number is registered',
-        ).equals(AuthSignInStep.continueSignInWithTotpSetup);
+        ).equals(AuthSignInStep.continueSignInWithMfaSetupSelection);
 
         final sharedSecret = signInRes.nextStep.totpSetupDetails!.sharedSecret;
         final setupRes = await Amplify.Auth.confirmSignIn(

packages/amplify_core/lib/src/types/auth/sign_in/auth_next_sign_in_step.g.dart

@@ -34,7 +34,7 @@ void main() {
           signInRes.nextStep.signInStep,
           because:
               "TOTP MFA is automatically enabled when it's the only option",
-        ).equals(AuthSignInStep.continueSignInWithTotpSetup);
+        ).equals(AuthSignInStep.continueSignInWithMfaSetupSelection);
 
         final sharedSecret = signInRes.nextStep.totpSetupDetails!.sharedSecret;
         final setupRes = await Amplify.Auth.confirmSignIn(

packages/amplify_core/lib/src/types/auth/sign_in/auth_sign_in_step.dart

@@ -885,20 +885,22 @@ class AmplifyAuthCognitoDart extends AuthPluginInterface
   /// {@template amplify_core.amplify_auth_category.update_mfa_preference}
   /// Updates the MFA preference for the current user.
   ///
-  /// If [sms] or [totp] is `null`, the preference for that MFA type is left
-  /// unchanged. Setting either [sms] or [totp] to [MfaPreference.preferred]
+  /// If [sms], [totp], or [email] is `null`, the preference for that MFA type is left
+  /// unchanged. Setting either [sms], [totp], or [email] to [MfaPreference.preferred]
   /// will mark the other as not preferred.
   /// {@endtemplate}
   Future<void> updateMfaPreference({
     MfaPreference? sms,
     MfaPreference? totp,
+    MfaPreference? email,
   }) async {
     final tokens = await _stateMachine.getUserPoolTokens();
     final accessToken = tokens.accessToken.raw;
     return _cognitoIdp.setMfaSettings(
       accessToken: accessToken,
       sms: sms,
       totp: totp,
+      email: email,
     );
   }
 

packages/auth/amplify_auth_cognito/example/integration_test/mfa_sms_totp_required_test.dart

@@ -11,6 +11,9 @@ abstract class CognitoConstants {
   /// The `USERNAME` parameter.
   static const challengeParamUsername = 'USERNAME';
 
+  /// The `EMAIL` parameter.
+  static const challengeParamEmail = 'EMAIL';
+
   /// The `SRP_A` parameter.
   static const challengeParamSrpA = 'SRP_A';
 
@@ -57,6 +60,9 @@ abstract class CognitoConstants {
   /// The `SMS_MFA_CODE` parameter.
   static const challengeParamSmsMfaCode = 'SMS_MFA_CODE';
 
+  /// The `EMAIL_OTP_CODE` parameter.
+  static const challengeParamEmailMfaCode = 'EMAIL_OTP_CODE';
+
   /// The `SOFTWARE_TOKEN_MFA_CODE` parameter.
   static const challengeParamSoftwareTokenMfaCode = 'SOFTWARE_TOKEN_MFA_CODE';
 

packages/auth/amplify_auth_cognito/example/integration_test/mfa_totp_required_test.dart

@@ -1,4 +1,4 @@
-// Generated with smithy-dart 0.3.1. DO NOT MODIFY.
+// Generated with smithy-dart 0.3.2. DO NOT MODIFY.
 // ignore_for_file: avoid_unused_constructor_parameters,deprecated_member_use_from_same_package,non_constant_identifier_names,require_trailing_commas
 
 /// # Amazon Cognito Identity

packages/auth/amplify_auth_cognito_dart/lib/src/auth_plugin_impl.dart

@@ -1,4 +1,4 @@
-// Generated with smithy-dart 0.3.1. DO NOT MODIFY.
+// Generated with smithy-dart 0.3.2. DO NOT MODIFY.
 // ignore_for_file: avoid_unused_constructor_parameters,deprecated_member_use_from_same_package,non_constant_identifier_names,require_trailing_commas
 
 /// # Amazon Cognito Identity Provider
@@ -68,6 +68,7 @@ export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/device_remembered_status_type.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/device_secret_verifier_config_type.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/device_type.dart';
+export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/email_mfa_settings_type.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/enable_software_token_mfa_exception.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/expired_code_exception.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/forbidden_exception.dart';
@@ -99,6 +100,7 @@ export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/mfa_option_type.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/new_device_metadata_type.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/not_authorized_exception.dart';
+export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/password_history_policy_violation_exception.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/password_reset_required_exception.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/resend_confirmation_code_request.dart';
 export 'package:amplify_auth_cognito_dart/src/sdk/src/cognito_identity_provider/model/resend_confirmation_code_response.dart';