feat(core,experience): additional 2fa suggestion (#7725)

* feat(phrases): add suggest_additional_mfa

* feat(core): mfa suggestion

* fix(core): respect mfa prompt

* feat(experience): mfa suggestion

* fix: fix api mfa suggestion test

Author: wangsijie

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

@@ -462,8 +462,10 @@ export default class ExperienceInteraction {
       return;
     }
 
-    // Verified
-    await this.guardMfaVerificationStatus();
+    // Verified, only SignIn requires MFA verification, for register, it does not make sense to verify MFA
+    if (this.#interactionEvent === InteractionEvent.SignIn) {
+      await this.guardMfaVerificationStatus();
+    }
 
     // Revalidate the new profile data if any
     await this.profile.validateAvailability();

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

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { type ToZodObject } from '@logto/connector-kit';
 import {
   type BindBackupCode,
@@ -26,13 +27,19 @@ import type Libraries from '#src/tenants/Libraries.js';
 import type Queries from '#src/tenants/Queries.js';
 import assertThat from '#src/utils/assert-that.js';
 
+import { EnvSet } from '../../../env-set/index.js';
 import { type InteractionContext } from '../types.js';
 
 import { getAllUserEnabledMfaVerifications } from './helpers.js';
 import { SignInExperienceValidator } from './libraries/sign-in-experience-validator.js';
 
 export type MfaData = {
   mfaSkipped?: boolean;
+  /**
+   * Whether user skipped the optional suggestion to add another MFA factor during registration.
+   * This flag lives only in the current interaction and should NOT be persisted to user profile.
+   */
+  additionalBindingSuggestionSkipped?: boolean;
   totp?: BindTotp;
   webAuthn?: BindWebAuthn[];
   backupCode?: BindBackupCode;
@@ -47,6 +54,7 @@ export type SanitizedMfaData = {
 
 export const mfaDataGuard = z.object({
   mfaSkipped: z.boolean().optional(),
+  additionalBindingSuggestionSkipped: z.boolean().optional(),
   totp: bindTotpGuard.optional(),
   webAuthn: z.array(bindWebAuthnGuard).optional(),
   backupCode: bindBackupCodeGuard.optional(),
@@ -80,6 +88,7 @@ const isMfaSkipped = (logtoConfig: JsonObject): boolean => {
 export class Mfa {
   private readonly signInExperienceValidator: SignInExperienceValidator;
   #mfaSkipped?: boolean;
+  #additionalBindingSuggestionSkipped?: boolean;
   #totp?: BindTotp;
   #webAuthn?: BindWebAuthn[];
   #backupCode?: BindBackupCode;
@@ -91,9 +100,10 @@ export class Mfa {
     private readonly interactionContext: InteractionContext
   ) {
     this.signInExperienceValidator = new SignInExperienceValidator(libraries, queries);
-    const { mfaSkipped, totp, webAuthn, backupCode } = data;
+    const { mfaSkipped, additionalBindingSuggestionSkipped, totp, webAuthn, backupCode } = data;
 
     this.#mfaSkipped = mfaSkipped;
+    this.#additionalBindingSuggestionSkipped = additionalBindingSuggestionSkipped;
     this.#totp = totp;
     this.#webAuthn = webAuthn;
     this.#backupCode = backupCode;
@@ -103,6 +113,10 @@ export class Mfa {
     return this.#mfaSkipped;
   }
 
+  get additionalBindingSuggestionSkipped() {
+    return this.#additionalBindingSuggestionSkipped;
+  }
+
   get bindMfaFactorsArray(): BindMfa[] {
     return [this.#totp, ...(this.#webAuthn ?? []), this.#backupCode].filter(Boolean);
   }
@@ -263,6 +277,14 @@ export class Mfa {
     this.#backupCode = verificationRecord.toBindMfa();
   }
 
+  /**
+   * Mark the optional suggestion as skipped for this interaction.
+   * No persistence to user account.
+   */
+  skipAdditionalBindingSuggestion() {
+    this.#additionalBindingSuggestionSkipped = true;
+  }
+
   /**
    * @throws {RequestError} with status 400 if the mfa factors are not enabled in the sign-in experience
    */
@@ -271,6 +293,52 @@ export class Mfa {
     await this.checkMfaFactorsEnabledInSignInExperience(newBindMfaFactors);
   }
 
+  /**
+   * Optionally suggest user to bind additional MFA factors during registration.
+   * Encapsulates suggestion logic and throws a 422 with `session.mfa.suggest_additional_mfa`
+   * when conditions are met.
+   * The purpose is to suggest another MFA factor if the user has only one Email or Phone factor.
+   */
+  async guardAdditionalBindingSuggestion(
+    factorsInUser: MfaFactor[],
+    availableFactors: MfaFactor[]
+  ) {
+    // Only suggest during registration flow
+    if (this.interactionContext.getInteractionEvent() !== InteractionEvent.Register) {
+      return;
+    }
+
+    // If no Email/Phone factor in use, then the user is not registered by Email/Phone
+    if (
+      !factorsInUser.includes(MfaFactor.EmailVerificationCode) &&
+      !factorsInUser.includes(MfaFactor.PhoneVerificationCode)
+    ) {
+      return;
+    }
+
+    const additionalFactors = availableFactors.filter((factor) => !factorsInUser.includes(factor));
+
+    // Respect user's choice to skip suggestion for this interaction
+    if (this.additionalBindingSuggestionSkipped) {
+      return;
+    }
+
+    // If user already bound an MFA in this interaction, don't suggest again
+    if (this.bindMfaFactorsArray.length > 0) {
+      return;
+    }
+
+    // No available factors to suggest
+    if (additionalFactors.length === 0) {
+      return;
+    }
+
+    throw new RequestError(
+      { code: 'session.mfa.suggest_additional_mfa', status: 422 },
+      { availableFactors: additionalFactors, skippable: true, suggestion: true }
+    );
+  }
+
   /**
    * @throws {RequestError} with status 422 if the user has not bound the required MFA factors
    * @throws {RequestError} with status 422 if the user has not bound the backup code but enabled in the sign-in experience
@@ -333,6 +401,11 @@ export class Mfa {
       )
     );
 
+    if (EnvSet.values.isDevFeaturesEnabled) {
+      // Optional suggestion: Let Mfa decide whether to suggest additional binding during registration
+      await this.guardAdditionalBindingSuggestion(factorsInUser, availableFactors);
+    }
+
     // Assert backup code
     assertThat(
       !factors.includes(MfaFactor.BackupCode) || linkedFactors.includes(MfaFactor.BackupCode),
@@ -346,6 +419,7 @@ export class Mfa {
   get data(): MfaData {
     return {
       mfaSkipped: this.mfaSkipped,
+      additionalBindingSuggestionSkipped: this.additionalBindingSuggestionSkipped,
       totp: this.#totp,
       webAuthn: this.#webAuthn,
       backupCode: this.#backupCode,
@@ -397,3 +471,4 @@ export class Mfa {
     ].filter(Boolean);
   }
 }
+/* eslint-enable max-lines */

packages/core/src/routes/experience/profile-routes.openapi.json

@@ -104,6 +104,31 @@
         }
       }
     },
+    "/api/experience/profile/mfa/mfa-suggestion-skipped": {
+      "post": {
+        "operationId": "SkipMfaSuggestion",
+        "summary": "Skip additional MFA suggestion",
+        "tags": ["Dev feature"],
+        "description": "Mark the optional additional MFA binding suggestion as skipped for the current interaction. When multiple MFA factors are enabled and only an email/phone factor is configured, a suggestion to add another factor may be shown; this endpoint records the choice to skip.",
+        "responses": {
+          "204": {
+            "description": "The suggestion was successfully skipped."
+          },
+          "400": {
+            "description": "Not supported for the current interaction event. The MFA profile API can only be used in the `SignIn` or `Register` interaction."
+          },
+          "403": {
+            "description": "Some MFA factors have already been enabled for the user. The user must verify MFA before updating related settings."
+          },
+          "404": {
+            "description": "The user has not been identified yet. The suggestion state must be associated with an identified user."
+          },
+          "422": {
+            "description": "The suggestion is not skippable under current policy."
+          }
+        }
+      }
+    },
     "/api/experience/profile/mfa": {
       "post": {
         "operationId": "BindMfaVerification",

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

@@ -44,7 +44,9 @@ function verifiedInteractionGuard<
       })
     );
 
-    await experienceInteraction.guardMfaVerificationStatus();
+    if (experienceInteraction.interactionEvent === InteractionEvent.SignIn) {
+      await experienceInteraction.guardMfaVerificationStatus();
+    }
 
     return next();
   };
@@ -184,6 +186,25 @@ export default function interactionProfileRoutes<T extends ExperienceInteraction
     }
   );
 
+  // Mark optional additional MFA binding suggestion as skipped in current interaction
+  if (EnvSet.values.isDevFeaturesEnabled) {
+    router.post(
+      `${experienceRoutes.mfa}/mfa-suggestion-skipped`,
+      koaGuard({ status: [204, 400, 403, 404, 422] }),
+      verifiedInteractionGuard(),
+      async (ctx, next) => {
+        const { experienceInteraction } = ctx;
+
+        experienceInteraction.mfa.skipAdditionalBindingSuggestion();
+        await experienceInteraction.save();
+
+        ctx.status = 204;
+
+        return next();
+      }
+    );
+  }
+
   router.post(
     `${experienceRoutes.mfa}`,
     koaGuard({

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

@@ -61,6 +61,11 @@ export const skipMfa = async () => {
   return submitInteraction();
 };
 
+export const skipMfaSuggestion = async () => {
+  await api.post(`${experienceApiRoutes.mfa}/mfa-suggestion-skipped`);
+  return submitInteraction();
+};
+
 export const bindMfa = async (
   type: MfaFactor,
   verificationId: string,

packages/experience/src/hooks/use-mfa-error-handler.ts

@@ -107,6 +107,7 @@ const useMfaErrorHandler = ({ replace }: Options = {}) => {
         const factors = data?.availableFactors ?? [];
         const skippable = data?.skippable;
         const maskedIdentifiers = data?.maskedIdentifiers;
+        const suggestion = data?.suggestion;
 
         if (factors.length === 0) {
           setToast(error.message);
@@ -119,7 +120,12 @@ const useMfaErrorHandler = ({ replace }: Options = {}) => {
             ? factors.filter((factor) => factor !== MfaFactor.WebAuthn)
             : factors;
 
-        await handleMfaRedirect(flow, { availableFactors, skippable, maskedIdentifiers });
+        await handleMfaRedirect(flow, {
+          availableFactors,
+          skippable,
+          maskedIdentifiers,
+          suggestion,
+        });
       };
     },
     [handleMfaRedirect, setToast]
@@ -129,6 +135,8 @@ const useMfaErrorHandler = ({ replace }: Options = {}) => {
     () => ({
       'user.missing_mfa': handleMfaError(UserMfaFlow.MfaBinding),
       'session.mfa.require_mfa_verification': handleMfaError(UserMfaFlow.MfaVerification),
+      // Optional suggestion to add another MFA during registration
+      'session.mfa.suggest_additional_mfa': handleMfaError(UserMfaFlow.MfaBinding),
       'session.mfa.backup_code_required': async () => startBackupCodeBinding(replace),
     }),
     [handleMfaError, replace, startBackupCodeBinding]

packages/experience/src/hooks/use-skip-optional-mfa.ts

@@ -0,0 +1,40 @@
+import { InteractionEvent } from '@logto/schemas';
+import { useCallback } from 'react';
+
+import { skipMfaSuggestion } from '@/apis/experience';
+
+import useApi from './use-api';
+import useErrorHandler from './use-error-handler';
+import useGlobalRedirectTo from './use-global-redirect-to';
+import useSubmitInteractionErrorHandler from './use-submit-interaction-error-handler';
+
+/**
+ * Skip handler for optional "add another MFA" suggestion during registration.
+ * Only stores skip in current interaction; does not persist to user account.
+ */
+const useSkipOptionalMfa = () => {
+  const asyncSkip = useApi(skipMfaSuggestion);
+  const redirectTo = useGlobalRedirectTo();
+
+  const handleError = useErrorHandler();
+  /**
+   * Reuse pre-sign-in error handler for post-skip submission flow.
+   */
+  const preSignInErrorHandler = useSubmitInteractionErrorHandler(InteractionEvent.SignIn, {
+    replace: true,
+  });
+
+  return useCallback(async () => {
+    const [error, result] = await asyncSkip();
+    if (error) {
+      await handleError(error, preSignInErrorHandler);
+      return;
+    }
+
+    if (result) {
+      await redirectTo(result.redirectTo);
+    }
+  }, [asyncSkip, handleError, preSignInErrorHandler, redirectTo]);
+};
+
+export default useSkipOptionalMfa;

packages/experience/src/pages/MfaBinding/TotpBinding/index.tsx

@@ -9,6 +9,7 @@ import UserInteractionContext from '@/Providers/UserInteractionContextProvider/U
 import Divider from '@/components/Divider';
 import SwitchMfaFactorsLink from '@/components/SwitchMfaFactorsLink';
 import useSkipMfa from '@/hooks/use-skip-mfa';
+import useSkipOptionalMfa from '@/hooks/use-skip-optional-mfa';
 import ErrorPage from '@/pages/ErrorPage';
 import { UserMfaFlow } from '@/types';
 import { totpBindingStateGuard } from '@/types/guard';
@@ -24,17 +25,18 @@ const TotpBinding = () => {
   const verificationId = verificationIdsMap[VerificationType.TOTP];
 
   const skipMfa = useSkipMfa();
+  const skipOptionalMfa = useSkipOptionalMfa();
 
   if (!totpBindingState || !verificationId) {
     return <ErrorPage title="error.invalid_session" />;
   }
 
-  const { availableFactors, skippable } = totpBindingState;
+  const { availableFactors, skippable, suggestion } = totpBindingState;
 
   return (
     <SecondaryPageLayout
       title="mfa.add_authenticator_app"
-      onSkip={conditional(skippable && skipMfa)}
+      onSkip={conditional(skippable && (suggestion ? skipOptionalMfa : skipMfa))}
     >
       <div className={styles.container}>
         <SecretSection {...totpBindingState} />

packages/experience/src/pages/MfaBinding/VerificationCodeMfaBinding/index.tsx

@@ -11,6 +11,7 @@ import { sendVerificationCode } from '@/apis/experience';
 import SwitchMfaFactorsLink from '@/components/SwitchMfaFactorsLink';
 import useErrorHandler from '@/hooks/use-error-handler';
 import useSkipMfa from '@/hooks/use-skip-mfa';
+import useSkipOptionalMfa from '@/hooks/use-skip-optional-mfa';
 import IdentifierProfileForm from '@/pages/Continue/IdentifierProfileForm';
 import ErrorPage from '@/pages/ErrorPage';
 import { UserMfaFlow } from '@/types';
@@ -39,6 +40,7 @@ const VerificationCodeMfaBinding = ({
   const [errorMessage, setErrorMessage] = useState<string>();
 
   const skipMfa = useSkipMfa();
+  const skipOptionalMfa = useSkipOptionalMfa();
   const handleError = useErrorHandler();
 
   const clearErrorMessage = useCallback(() => {
@@ -84,13 +86,13 @@ const VerificationCodeMfaBinding = ({
     return <ErrorPage title="error.invalid_session" />;
   }
 
-  const { skippable, availableFactors } = mfaFlowState;
+  const { skippable, availableFactors, suggestion } = mfaFlowState;
 
   return (
     <SecondaryPageLayout
       title={titleKey}
       description={descriptionKey}
-      onSkip={conditional(skippable && skipMfa)}
+      onSkip={conditional(skippable && (suggestion ? skipOptionalMfa : skipMfa))}
     >
       <IdentifierProfileForm
         autoFocus