feat(core): bind Email MFA (#7653)

Author: wangsijie

packages/core/src/routes/experience/classes/experience-interaction.ts

@@ -93,6 +93,7 @@ export default class ExperienceInteraction {
       getVerificationRecordByTypeAndId: (type, verificationId) =>
         this.getVerificationRecordByTypeAndId(type, verificationId),
       getVerificationRecordById: (verificationId) => this.getVerificationRecordById(verificationId),
+      getCurrentProfile: () => this.profile.data,
     };
 
     if (typeof interactionData === 'string') {

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

@@ -6,7 +6,14 @@
  */
 
 import { defaults, parseAffiliateData } from '@logto/affiliate';
-import { adminTenantId, MfaFactor, VerificationType, type User } from '@logto/schemas';
+import {
+  adminTenantId,
+  MfaFactor,
+  VerificationType,
+  type User,
+  type Mfa,
+  type MfaVerification,
+} from '@logto/schemas';
 import { conditional, trySafe } from '@silverhand/essentials';
 import { type IRouterContext } from 'koa-router';
 
@@ -171,6 +178,57 @@ export const mergeUserMfaVerifications = (
   return [...userMfaVerifications, ...newMfaVerifications];
 };
 
+/**
+ * Filter out backup codes mfa verifications that have been used
+ */
+const filterOutEmptyBackupCodes = (
+  mfaVerifications: User['mfaVerifications']
+): User['mfaVerifications'] =>
+  mfaVerifications.filter((mfa) => {
+    if (mfa.type === MfaFactor.BackupCode) {
+      return mfa.codes.some((code) => !code.usedAt);
+    }
+    return true;
+  });
+
+/**
+ * Get all enabled MFA verifications for a user (stored + implicit)
+ * @param mfaSettings - MFA settings from sign-in experience
+ * @param user - User object with mfaVerifications and profile data
+ * @param currentProfile - Optional profile override (for current interaction contexts), in cases of MFA verification, this is not needed
+ * @returns Array of all enabled MFA verifications
+ */
+export const getAllUserEnabledMfaVerifications = (
+  mfaSettings: Mfa,
+  user: User,
+  currentProfile?: InteractionProfile
+): MfaVerification[] => {
+  const storedVerifications = filterOutEmptyBackupCodes(user.mfaVerifications).filter(
+    (verification) => mfaSettings.factors.includes(verification.type)
+  );
+
+  if (!EnvSet.values.isDevFeaturesEnabled) {
+    return storedVerifications;
+  }
+
+  const email = currentProfile?.primaryEmail ?? user.primaryEmail;
+
+  const implicitVerifications = [
+    // Email MFA Factor: user has primaryEmail + Email factor enabled in SIE
+    ...(mfaSettings.factors.includes(MfaFactor.EmailVerificationCode) && email
+      ? ([
+          {
+            id: 'implicit-email-mfa', // Fake ID for capability
+            type: MfaFactor.EmailVerificationCode,
+            createdAt: new Date(user.createdAt).toISOString(),
+          },
+        ] satisfies MfaVerification[])
+      : []),
+  ];
+
+  return [...storedVerifications, ...implicitVerifications];
+};
+
 /**
  * Post affiliate data to the cloud service.
  */

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

@@ -9,7 +9,9 @@ import {
   type User,
 } from '@logto/schemas';
 
+import { getAllUserEnabledMfaVerifications } from '../helpers.js';
 import { type BackupCodeVerification } from '../verifications/backup-code-verification.js';
+import { type EmailCodeVerification } from '../verifications/code-verification.js';
 import { type VerificationRecord } from '../verifications/index.js';
 import { type TotpVerification } from '../verifications/totp-verification.js';
 import { type WebAuthnVerification } from '../verifications/web-authn-verification.js';
@@ -18,20 +20,27 @@ const mfaVerificationTypes = Object.freeze([
   VerificationType.TOTP,
   VerificationType.BackupCode,
   VerificationType.WebAuthn,
+  VerificationType.EmailVerificationCode,
 ]);
 
 type MfaVerificationType =
   | VerificationType.TOTP
   | VerificationType.BackupCode
-  | VerificationType.WebAuthn;
+  | VerificationType.WebAuthn
+  | VerificationType.EmailVerificationCode;
 
 const mfaVerificationTypeToMfaFactorMap = Object.freeze({
   [VerificationType.TOTP]: MfaFactor.TOTP,
   [VerificationType.BackupCode]: MfaFactor.BackupCode,
   [VerificationType.WebAuthn]: MfaFactor.WebAuthn,
+  [VerificationType.EmailVerificationCode]: MfaFactor.EmailVerificationCode,
 }) satisfies Record<MfaVerificationType, MfaFactor>;
 
-type MfaVerificationRecord = TotpVerification | WebAuthnVerification | BackupCodeVerification;
+type MfaVerificationRecord =
+  | TotpVerification
+  | WebAuthnVerification
+  | BackupCodeVerification
+  | EmailCodeVerification;
 
 const isMfaVerificationRecord = (
   verification: VerificationRecord
@@ -49,13 +58,10 @@ export class MfaValidator {
    * Get the enabled MFA factors for the user
    *
    * - Filter out MFA factors that are not configured in the sign-in experience
+   * - Include implicit Email and Phone MFA factors if user has them and they're enabled in SIE
    */
   get userEnabledMfaVerifications() {
-    const { mfaVerifications } = this.user;
-
-    return mfaVerifications.filter((verification) =>
-      this.mfaSettings.factors.includes(verification.type)
-    );
+    return getAllUserEnabledMfaVerifications(this.mfaSettings, this.user);
   }
 
   /**

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

@@ -28,6 +28,7 @@ import assertThat from '#src/utils/assert-that.js';
 
 import { type InteractionContext } from '../types.js';
 
+import { getAllUserEnabledMfaVerifications } from './helpers.js';
 import { SignInExperienceValidator } from './libraries/sign-in-experience-validator.js';
 
 export type MfaData = {
@@ -73,19 +74,6 @@ const isMfaSkipped = (logtoConfig: JsonObject): boolean => {
   return parsed.success ? parsed.data[userMfaDataKey].skipped === true : false;
 };
 
-/**
- * Filter out backup codes mfa verifications that have been used
- */
-const filterOutEmptyBackupCodes = (
-  mfaVerifications: User['mfaVerifications']
-): User['mfaVerifications'] =>
-  mfaVerifications.filter((mfa) => {
-    if (mfa.type === MfaFactor.BackupCode) {
-      return mfa.codes.some((code) => !code.usedAt);
-    }
-    return true;
-  });
-
 /**
  * This class stores all the pending new MFA settings for a user.
  */
@@ -261,11 +249,11 @@ export class Mfa {
 
     await this.checkMfaFactorsEnabledInSignInExperience([MfaFactor.BackupCode]);
 
-    const { mfaVerifications } = await this.interactionContext.getIdentifiedUser();
-    const userHasOtherMfa = mfaVerifications.some((mfa) => mfa.type !== MfaFactor.BackupCode);
-    const hasOtherNewMfa = Boolean(this.#totp ?? this.#webAuthn?.length);
+    const userFactors = await this.getUserMfaFactors();
+    const hasOtherMfaFactors = userFactors.some((factor) => factor !== MfaFactor.BackupCode);
+
     assertThat(
-      userHasOtherMfa || hasOtherNewMfa,
+      hasOtherMfaFactors,
       new RequestError({
         code: 'session.mfa.backup_code_can_not_be_alone',
         status: 422,
@@ -298,11 +286,7 @@ export class Mfa {
       return;
     }
 
-    const {
-      mfaVerifications,
-      logtoConfig,
-      id: userId,
-    } = await this.interactionContext.getIdentifiedUser();
+    const { logtoConfig, id: userId } = await this.interactionContext.getIdentifiedUser();
 
     const isMfaRequiredByUserOrganizations = await this.isMfaRequiredByUserOrganizations(
       mfaSettings,
@@ -334,7 +318,7 @@ export class Mfa {
 
     const availableFactors = factors.filter((factor) => factor !== MfaFactor.BackupCode);
 
-    const factorsInUser = filterOutEmptyBackupCodes(mfaVerifications).map(({ type }) => type);
+    const factorsInUser = await this.getUserMfaFactors();
     const factorsInBind = this.bindMfaFactorsArray.map(({ type }) => type);
     const linkedFactors = deduplicate([...factorsInUser, ...factorsInBind]);
 
@@ -395,4 +379,21 @@ export class Mfa {
 
     return organizations.some(({ isMfaRequired }) => isMfaRequired);
   }
+
+  private async getUserMfaFactors(): Promise<MfaFactor[]> {
+    const mfaSettings = await this.signInExperienceValidator.getMfaSettings();
+    const user = await this.interactionContext.getIdentifiedUser();
+    const currentProfile = this.interactionContext.getCurrentProfile();
+
+    const existingVerifications = getAllUserEnabledMfaVerifications(
+      mfaSettings,
+      user,
+      currentProfile
+    );
+    return [
+      ...existingVerifications.map(({ type }) => type),
+      ...(this.#totp ? [MfaFactor.TOTP] : []),
+      ...(this.#webAuthn?.length ? [MfaFactor.WebAuthn] : []),
+    ].filter(Boolean);
+  }
 }

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

@@ -88,6 +88,17 @@ 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`
    *

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

@@ -14,6 +14,8 @@ import koaGuard from '#src/middleware/koa-guard.js';
 import type TenantContext from '#src/tenants/TenantContext.js';
 import assertThat from '#src/utils/assert-that.js';
 
+import { EnvSet } from '../../env-set/index.js';
+
 import { experienceRoutes } from './const.js';
 import { type ExperienceInteractionRouterContext } from './types.js';
 
@@ -216,9 +218,20 @@ export default function interactionProfileRoutes<T extends ExperienceInteraction
           await experienceInteraction.mfa.addBackupCodeByVerificationId(verificationId, log);
           break;
         }
-        case MfaFactor.EmailVerificationCode:
+        case MfaFactor.EmailVerificationCode: {
+          if (!EnvSet.values.isDevFeaturesEnabled) {
+            throw new Error('Not implemented yet');
+          }
+
+          await experienceInteraction.profile.setProfileByVerificationId(
+            SignInIdentifier.Email,
+            verificationId,
+            log
+          );
+          break;
+        }
         case MfaFactor.PhoneVerificationCode: {
-          // TODO: Implement email and SMS verification code MFA binding
+          // TODO: Implement SMS verification code MFA binding
           throw new Error('Not implemented yet');
         }
       }

packages/core/src/routes/experience/types.ts

@@ -150,6 +150,7 @@ export type InteractionContext = {
     type: K,
     verificationId: string
   ) => VerificationRecordMap[K];
+  getCurrentProfile: () => InteractionProfile;
 };
 
 export type ExperienceInteractionRouterContext<ContextT extends WithLogContext = WithLogContext> =

packages/experience/src/apis/experience/mfa.ts

@@ -87,7 +87,8 @@ export const bindMfa = async (payload: BindMfaPayload, verificationId: string) =
     }
     case MfaFactor.EmailVerificationCode:
     case MfaFactor.PhoneVerificationCode: {
-      // TODO: Implement email and phone verification code binding
+      // Email/Phone MFA factors use special binding logic, but don't submit immediately
+      // to allow additional MFA factors to be bound in the same session
       break;
     }
   }

packages/integration-tests/src/helpers/sign-in-experience.ts

@@ -169,6 +169,22 @@ export const enableMandatoryMfaWithTotpAndBackupCode = async () =>
     },
   });
 
+export const enableMandatoryMfaWithEmail = async () =>
+  updateSignInExperience({
+    mfa: {
+      factors: [MfaFactor.EmailVerificationCode],
+      policy: MfaPolicy.Mandatory,
+    },
+  });
+
+export const enableMandatoryMfaWithEmailAndBackupCode = async () =>
+  updateSignInExperience({
+    mfa: {
+      factors: [MfaFactor.EmailVerificationCode, MfaFactor.BackupCode],
+      policy: MfaPolicy.Mandatory,
+    },
+  });
+
 export const enableMandatoryMfaWithWebAuthnAndBackupCode = async () =>
   updateSignInExperience({
     mfa: {