feat(core): add api for sending mfa verification code (#7684)

* feat(core): add api for sending mfa verification code

* refactor(core): add mfa code verification class

Author: wangsijie

packages/core/src/routes/experience/classes/helpers.ts

@@ -99,7 +99,9 @@ export const identifyUserByVerificationRecord = async (
   switch (verificationRecord.type) {
     case VerificationType.Password:
     case VerificationType.EmailVerificationCode:
-    case VerificationType.PhoneVerificationCode: {
+    case VerificationType.PhoneVerificationCode:
+    case VerificationType.MfaEmailVerificationCode:
+    case VerificationType.MfaPhoneVerificationCode: {
       return {
         user: await verificationRecord.identifyUser(),
       };

packages/core/src/routes/experience/classes/libraries/mfa-validator.ts

@@ -11,8 +11,8 @@ import {
 import { getAllUserEnabledMfaVerifications } from '../helpers.js';
 import { type BackupCodeVerification } from '../verifications/backup-code-verification.js';
 import {
-  type EmailCodeVerification,
-  type PhoneCodeVerification,
+  type MfaEmailCodeVerification,
+  type MfaPhoneCodeVerification,
 } from '../verifications/code-verification.js';
 import { type VerificationRecord } from '../verifications/index.js';
 import { type TotpVerification } from '../verifications/totp-verification.js';
@@ -22,31 +22,31 @@ const mfaVerificationTypes = Object.freeze([
   VerificationType.TOTP,
   VerificationType.BackupCode,
   VerificationType.WebAuthn,
-  VerificationType.EmailVerificationCode,
-  VerificationType.PhoneVerificationCode,
+  VerificationType.MfaEmailVerificationCode,
+  VerificationType.MfaPhoneVerificationCode,
 ]);
 
 type MfaVerificationType =
   | VerificationType.TOTP
   | VerificationType.BackupCode
   | VerificationType.WebAuthn
-  | VerificationType.EmailVerificationCode
-  | VerificationType.PhoneVerificationCode;
+  | VerificationType.MfaEmailVerificationCode
+  | VerificationType.MfaPhoneVerificationCode;
 
 const mfaVerificationTypeToMfaFactorMap = Object.freeze({
   [VerificationType.TOTP]: MfaFactor.TOTP,
   [VerificationType.BackupCode]: MfaFactor.BackupCode,
   [VerificationType.WebAuthn]: MfaFactor.WebAuthn,
-  [VerificationType.EmailVerificationCode]: MfaFactor.EmailVerificationCode,
-  [VerificationType.PhoneVerificationCode]: MfaFactor.PhoneVerificationCode,
+  [VerificationType.MfaEmailVerificationCode]: MfaFactor.EmailVerificationCode,
+  [VerificationType.MfaPhoneVerificationCode]: MfaFactor.PhoneVerificationCode,
 }) satisfies Record<MfaVerificationType, MfaFactor>;
 
 type MfaVerificationRecord =
   | TotpVerification
   | WebAuthnVerification
   | BackupCodeVerification
-  | EmailCodeVerification
-  | PhoneCodeVerification;
+  | MfaEmailCodeVerification
+  | MfaPhoneCodeVerification;
 
 const isMfaVerificationRecord = (
   verification: VerificationRecord

packages/core/src/routes/experience/classes/verifications/code-verification.ts

@@ -52,6 +52,8 @@ const getPasscodeIdentifierPayload = (
 type CodeVerificationIdentifierMap = {
   [VerificationType.EmailVerificationCode]: { primaryEmail: string };
   [VerificationType.PhoneVerificationCode]: { primaryPhone: string };
+  [VerificationType.MfaEmailVerificationCode]: Record<string, unknown>;
+  [VerificationType.MfaPhoneVerificationCode]: Record<string, unknown>;
 };
 
 /**
@@ -88,17 +90,6 @@ abstract class CodeVerification<T extends CodeVerificationType>
     return this.verified;
   }
 
-  get isNewBindMfaVerification() {
-    // For EmailCodeVerification and PhoneCodeVerification, the binding is always completed before submitting the interaction.
-    // So this method always returns false.
-    // So that it can be used right after the new Email/Phone is bound to the user.
-    // The flow: user binds a new email/phone -> user info updated to the DB -> user submits the interaction
-    // -> check user enabled MFA verifications -> the new email/phone is included in the enabled MFA verifications
-    // -> but the user does not need to verify the new email/phone again -> reuse the verification record
-    // So this verification record are used for the new bind MFA verification, and also can be used for the verification.
-    return false;
-  }
-
   /**
    * Send the verification code to the current `identifier`
    *
@@ -242,6 +233,32 @@ export class PhoneCodeVerification extends CodeVerification<VerificationType.Pho
   }
 }
 
+export class MfaEmailCodeVerification extends CodeVerification<VerificationType.MfaEmailVerificationCode> {
+  public readonly type = VerificationType.MfaEmailVerificationCode;
+
+  toUserProfile(): Record<string, unknown> {
+    return {};
+  }
+
+  get isNewBindMfaVerification(): boolean {
+    // This class is only used for MFA verification
+    return false;
+  }
+}
+
+export class MfaPhoneCodeVerification extends CodeVerification<VerificationType.MfaPhoneVerificationCode> {
+  public readonly type = VerificationType.MfaPhoneVerificationCode;
+
+  toUserProfile(): Record<string, unknown> {
+    return {};
+  }
+
+  get isNewBindMfaVerification(): boolean {
+    // This class is only used for MFA verification
+    return false;
+  }
+}
+
 /**
  * Factory method to create a new `EmailCodeVerification` / `PhoneCodeVerification` record using the given identifier.
  */
@@ -276,3 +293,40 @@ export const createNewCodeVerificationRecord = (
     }
   }
 };
+
+/**
+ * Factory method to create a new `MfaEmailCodeVerification` / `MfaPhoneCodeVerification` record using the given identifier.
+ */
+export const createNewMfaCodeVerificationRecord = (
+  libraries: Libraries,
+  queries: Queries,
+  identifier:
+    | VerificationCodeIdentifier<SignInIdentifier.Email>
+    | VerificationCodeIdentifier<SignInIdentifier.Phone>,
+  verified = false
+): MfaEmailCodeVerification | MfaPhoneCodeVerification => {
+  const { type } = identifier;
+
+  switch (type) {
+    case SignInIdentifier.Email: {
+      return new MfaEmailCodeVerification(libraries, queries, {
+        id: generateStandardId(),
+        type: VerificationType.MfaEmailVerificationCode,
+        identifier,
+        // TODO @wangsijie: replace to new template type
+        templateType: TemplateType.SignIn,
+        verified,
+      });
+    }
+    case SignInIdentifier.Phone: {
+      return new MfaPhoneCodeVerification(libraries, queries, {
+        id: generateStandardId(),
+        type: VerificationType.MfaPhoneVerificationCode,
+        identifier,
+        // TODO @wangsijie: replace to new template type
+        templateType: TemplateType.SignIn,
+        verified,
+      });
+    }
+  }
+};

packages/core/src/routes/experience/classes/verifications/index.ts

@@ -1,4 +1,8 @@
-import { VerificationType } from '@logto/schemas';
+import {
+  mfaEmailCodeVerificationRecordDataGuard,
+  mfaPhoneCodeVerificationRecordDataGuard,
+  VerificationType,
+} from '@logto/schemas';
 import { z } from 'zod';
 
 import type Libraries from '#src/tenants/Libraries.js';
@@ -16,6 +20,8 @@ import {
   emailCodeVerificationRecordDataGuard,
   PhoneCodeVerification,
   phoneCodeVerificationRecordDataGuard,
+  MfaEmailCodeVerification,
+  MfaPhoneCodeVerification,
   type CodeVerificationRecordData,
 } from './code-verification.js';
 import {
@@ -69,6 +75,8 @@ export type VerificationRecordData =
   | PasswordVerificationRecordData
   | CodeVerificationRecordData<VerificationType.EmailVerificationCode>
   | CodeVerificationRecordData<VerificationType.PhoneVerificationCode>
+  | CodeVerificationRecordData<VerificationType.MfaEmailVerificationCode>
+  | CodeVerificationRecordData<VerificationType.MfaPhoneVerificationCode>
   | SocialVerificationRecordData
   | EnterpriseSsoVerificationRecordData
   | TotpVerificationRecordData
@@ -81,6 +89,8 @@ export type SanitizedVerificationRecordData =
   | PasswordVerificationRecordData
   | CodeVerificationRecordData<VerificationType.EmailVerificationCode>
   | CodeVerificationRecordData<VerificationType.PhoneVerificationCode>
+  | CodeVerificationRecordData<VerificationType.MfaEmailVerificationCode>
+  | CodeVerificationRecordData<VerificationType.MfaPhoneVerificationCode>
   | SanitizedSocialVerificationRecordData
   | SanitizedEnterpriseSsoVerificationRecordData
   | SanitizedTotpVerificationRecordData
@@ -99,6 +109,8 @@ export type VerificationRecordMap = AssertVerificationMap<{
   [VerificationType.Password]: PasswordVerification;
   [VerificationType.EmailVerificationCode]: EmailCodeVerification;
   [VerificationType.PhoneVerificationCode]: PhoneCodeVerification;
+  [VerificationType.MfaEmailVerificationCode]: MfaEmailCodeVerification;
+  [VerificationType.MfaPhoneVerificationCode]: MfaPhoneCodeVerification;
   [VerificationType.Social]: SocialVerification;
   [VerificationType.EnterpriseSso]: EnterpriseSsoVerification;
   [VerificationType.TOTP]: TotpVerification;
@@ -123,6 +135,8 @@ export const verificationRecordDataGuard = z.discriminatedUnion('type', [
   passwordVerificationRecordDataGuard,
   emailCodeVerificationRecordDataGuard,
   phoneCodeVerificationRecordDataGuard,
+  mfaEmailCodeVerificationRecordDataGuard,
+  mfaPhoneCodeVerificationRecordDataGuard,
   socialVerificationRecordDataGuard,
   enterpriseSsoVerificationRecordDataGuard,
   totpVerificationRecordDataGuard,
@@ -136,6 +150,8 @@ export const publicVerificationRecordDataGuard = z.discriminatedUnion('type', [
   passwordVerificationRecordDataGuard,
   emailCodeVerificationRecordDataGuard,
   phoneCodeVerificationRecordDataGuard,
+  mfaEmailCodeVerificationRecordDataGuard,
+  mfaPhoneCodeVerificationRecordDataGuard,
   sanitizedSocialVerificationRecordDataGuard,
   sanitizedEnterpriseSsoVerificationRecordDataGuard,
   sanitizedTotpVerificationRecordDataGuard,
@@ -148,6 +164,7 @@ export const publicVerificationRecordDataGuard = z.discriminatedUnion('type', [
 /**
  * The factory method to build a new `VerificationRecord` instance based on the provided `VerificationRecordData`.
  */
+// eslint-disable-next-line complexity
 export const buildVerificationRecord = (
   libraries: Libraries,
   queries: Queries,
@@ -163,6 +180,12 @@ export const buildVerificationRecord = (
     case VerificationType.PhoneVerificationCode: {
       return new PhoneCodeVerification(libraries, queries, data);
     }
+    case VerificationType.MfaEmailVerificationCode: {
+      return new MfaEmailCodeVerification(libraries, queries, data);
+    }
+    case VerificationType.MfaPhoneVerificationCode: {
+      return new MfaPhoneCodeVerification(libraries, queries, data);
+    }
     case VerificationType.Social: {
       return new SocialVerification(libraries, queries, data);
     }

packages/core/src/routes/experience/profile-routes.ts

@@ -16,6 +16,7 @@ import assertThat from '#src/utils/assert-that.js';
 
 import { EnvSet } from '../../env-set/index.js';
 
+import { createNewMfaCodeVerificationRecord } from './classes/verifications/code-verification.js';
 import { experienceRoutes } from './const.js';
 import { type ExperienceInteractionRouterContext } from './types.js';
 
@@ -51,7 +52,7 @@ function verifiedInteractionGuard<
 
 export default function interactionProfileRoutes<T extends ExperienceInteractionRouterContext>(
   router: Router<unknown, T>,
-  tenant: TenantContext
+  { libraries, queries }: TenantContext
 ) {
   router.post(
     `${experienceRoutes.profile}`,
@@ -228,6 +229,21 @@ export default function interactionProfileRoutes<T extends ExperienceInteraction
             verificationId,
             log
           );
+          const { primaryEmail } = experienceInteraction.profile.data;
+          // If the primary email is set, create a new MFA code verification record
+          // to bypass the MFA verification step.
+          if (primaryEmail) {
+            const codeVerification = createNewMfaCodeVerificationRecord(
+              libraries,
+              queries,
+              {
+                type: SignInIdentifier.Email,
+                value: primaryEmail,
+              },
+              true
+            );
+            experienceInteraction.setVerificationRecord(codeVerification);
+          }
           break;
         }
         case MfaFactor.PhoneVerificationCode: {
@@ -240,6 +256,21 @@ export default function interactionProfileRoutes<T extends ExperienceInteraction
             verificationId,
             log
           );
+          const { primaryPhone } = experienceInteraction.profile.data;
+          // If the primary phone is set, create a new MFA code verification record
+          // to bypass the MFA verification step.
+          if (primaryPhone) {
+            const codeVerification = createNewMfaCodeVerificationRecord(
+              libraries,
+              queries,
+              {
+                type: SignInIdentifier.Phone,
+                value: primaryPhone,
+              },
+              true
+            );
+            experienceInteraction.setVerificationRecord(codeVerification);
+          }
           break;
         }
       }