feat: add forgot password methods (#7611)

* feat: add forgot password methods

* fix: filter forgotPasswordMethods based on available connectors

* refactor: make forgotPasswordMethods nullable with fallback

* fix: fix test

* fix: fix integration test

* refactor: maintain forgotPassword API

* refactor(console,core): align forgotPassword logic and add comments

* fix: fix experience test

* refactor: revert changes in experience

* fix: fix unit test

Author: wangsijie

packages/console/src/components/SignInExperiencePreview/index.tsx

@@ -1,5 +1,5 @@
 import type { LanguageTag } from '@logto/language-kit';
-import { Theme, ConnectorType } from '@logto/schemas';
+import { Theme, ConnectorType, ForgotPasswordMethod } from '@logto/schemas';
 import type { ConnectorMetadata, ConnectorResponse } from '@logto/schemas';
 import { conditional } from '@silverhand/essentials';
 import classNames from 'classnames';
@@ -9,6 +9,7 @@ import { useTranslation } from 'react-i18next';
 import useSWR from 'swr';
 
 import PhoneInfo from '@/assets/images/phone-info.svg?react';
+import { isDevFeaturesEnabled } from '@/consts/env';
 import { AppDataContext } from '@/contexts/AppDataProvider';
 import type { RequestError } from '@/hooks/use-api';
 import useUiLanguages from '@/hooks/use-ui-languages';
@@ -70,17 +71,41 @@ function SignInExperiencePreview({
     );
 
     const hasEmailConnector = allConnectors.some(({ type }) => type === ConnectorType.Email);
-
     const hasSmsConnector = allConnectors.some(({ type }) => type === ConnectorType.Sms);
 
+    /**
+     * Generate forgot password object based on available connectors and configured methods.
+     * This logic aligns with the core library implementation in sign-in-experience/index.ts
+     */
+    const forgotPassword = (() => {
+      // If forgotPasswordMethods is null (production compatibility) or dev features are not enabled,
+      // fall back to connector-based availability only
+      if (!signInExperience.forgotPasswordMethods || !isDevFeaturesEnabled) {
+        return {
+          email: hasEmailConnector,
+          phone: hasSmsConnector,
+        };
+      }
+
+      // When methods are explicitly configured and dev features are enabled,
+      // require both method inclusion and connector availability
+      return {
+        email:
+          signInExperience.forgotPasswordMethods.includes(
+            ForgotPasswordMethod.EmailVerificationCode
+          ) && hasEmailConnector,
+        phone:
+          signInExperience.forgotPasswordMethods.includes(
+            ForgotPasswordMethod.PhoneVerificationCode
+          ) && hasSmsConnector,
+      };
+    })();
+
     return {
       signInExperience: {
         ...signInExperience,
         socialConnectors,
-        forgotPassword: {
-          email: hasEmailConnector,
-          sms: hasSmsConnector,
-        },
+        forgotPassword,
       },
       language,
       mode,

packages/core/src/__mocks__/sign-in-experience.ts

@@ -106,4 +106,5 @@ export const mockSignInExperience: SignInExperience = {
   captchaPolicy: {},
   sentinelPolicy: {},
   emailBlocklistPolicy: {},
+  forgotPasswordMethods: null,
 };

packages/core/src/libraries/sign-in-experience/index.test.ts

@@ -4,6 +4,8 @@ import { CaptchaType, type CreateSignInExperience, type SignInExperience } from
 import { TtlCache } from '@logto/shared';
 
 import {
+  mockAliyunDmConnector,
+  mockAliyunSmsConnector,
   mockCaptchaProvider,
   mockCustomProfileFields,
   mockGithubConnector,
@@ -180,10 +182,6 @@ describe('getFullSignInExperience()', () => {
       ...mockSignInExperience,
       socialConnectors: [],
       socialSignInConnectorTargets: ['github', 'facebook', 'wechat'],
-      forgotPassword: {
-        email: false,
-        phone: false,
-      },
       ssoConnectors: [
         {
           id: wellConfiguredSsoConnector.id,
@@ -196,6 +194,10 @@ describe('getFullSignInExperience()', () => {
       googleOneTap: undefined,
       captchaConfig: undefined,
       customProfileFields: mockCustomProfileFields,
+      forgotPassword: {
+        email: false,
+        phone: false,
+      },
     });
   });
 
@@ -219,10 +221,6 @@ describe('getFullSignInExperience()', () => {
         { ...mockGoogleConnector.metadata, id: mockGoogleConnector.dbEntry.id },
       ],
       socialSignInConnectorTargets: ['github', 'facebook', 'google'],
-      forgotPassword: {
-        email: false,
-        phone: false,
-      },
       ssoConnectors: [
         {
           id: wellConfiguredSsoConnector.id,
@@ -239,6 +237,10 @@ describe('getFullSignInExperience()', () => {
         connectorId: 'google',
       },
       captchaConfig: undefined,
+      forgotPassword: {
+        email: false,
+        phone: false,
+      },
     });
   });
 });
@@ -331,3 +333,37 @@ describe('findCaptchaPublicConfig', () => {
     expect(captchaPublicConfig).toBeUndefined();
   });
 });
+
+describe('forgot password methods', () => {
+  it('should return connector-based methods when forgotPasswordMethods is null', async () => {
+    findDefaultSignInExperience.mockResolvedValueOnce({
+      ...mockSignInExperience,
+      forgotPasswordMethods: null, // Test null case
+    });
+    getLogtoConnectors.mockResolvedValueOnce([mockAliyunDmConnector, mockAliyunSmsConnector]);
+    mockSsoConnectorLibrary.getAvailableSsoConnectors.mockResolvedValueOnce([]);
+
+    const fullSignInExperience = await getFullSignInExperience({ locale: 'en' });
+
+    expect(fullSignInExperience.forgotPassword).toEqual({
+      email: true,
+      phone: true,
+    });
+  });
+
+  it('should return false values when forgotPasswordMethods is null and no connectors available', async () => {
+    findDefaultSignInExperience.mockResolvedValueOnce({
+      ...mockSignInExperience,
+      forgotPasswordMethods: null,
+    });
+    getLogtoConnectors.mockResolvedValueOnce([]); // No connectors
+    mockSsoConnectorLibrary.getAvailableSsoConnectors.mockResolvedValueOnce([]);
+
+    const fullSignInExperience = await getFullSignInExperience({ locale: 'en' });
+
+    expect(fullSignInExperience.forgotPassword).toEqual({
+      email: false,
+      phone: false,
+    });
+  });
+});

packages/core/src/libraries/sign-in-experience/index.ts

@@ -7,7 +7,7 @@ import type {
   SignInExperience,
   SsoConnectorMetadata,
 } from '@logto/schemas';
-import { ConnectorType, ReservedPlanId } from '@logto/schemas';
+import { ConnectorType, ForgotPasswordMethod, ReservedPlanId } from '@logto/schemas';
 import { cond, conditional, deduplicate, pick, trySafe } from '@silverhand/essentials';
 import deepmerge from 'deepmerge';
 
@@ -203,11 +203,6 @@ export const createSignInExperienceLibrary = (
       ? await getActiveSsoConnectors(locale)
       : [];
 
-    const forgotPassword = {
-      phone: logtoConnectors.some(({ type }) => type === ConnectorType.Sms),
-      email: logtoConnectors.some(({ type }) => type === ConnectorType.Email),
-    };
-
     const socialConnectors = signInExperience.socialSignInConnectorTargets.reduce<
       ConnectorMetadata[]
     >((previous, connectorTarget) => {
@@ -264,14 +259,54 @@ export const createSignInExperienceLibrary = (
       return findCaptchaPublicConfig();
     };
 
+    /**
+     * Generate forgot password object based on available connectors and configured methods.
+     *
+     * This function determines which forgot password methods are available by checking:
+     * 1. Whether the required connectors (email/SMS) are configured and available
+     * 2. Whether specific methods are explicitly enabled in the sign-in experience configuration
+     *
+     * The logic handles two scenarios:
+     * - Legacy/fallback mode: When forgotPasswordMethods is null or dev features are disabled,
+     *   availability is determined solely by connector presence
+     * - Explicit configuration mode: When dev features are enabled and methods are configured,
+     *   both method inclusion and connector availability must be satisfied
+     */
+    const getForgotPassword = () => {
+      // Check availability of required connectors
+      const hasEmailConnector = logtoConnectors.some(({ type }) => type === ConnectorType.Email);
+      const hasSmsConnector = logtoConnectors.some(({ type }) => type === ConnectorType.Sms);
+
+      // If forgotPasswordMethods is null (production compatibility) or dev features are not enabled,
+      // fall back to connector-based availability only
+      if (!signInExperience.forgotPasswordMethods || !EnvSet.values.isDevFeaturesEnabled) {
+        return {
+          email: hasEmailConnector,
+          phone: hasSmsConnector,
+        };
+      }
+
+      // When methods are explicitly configured, require both method inclusion and connector availability
+      return {
+        email:
+          signInExperience.forgotPasswordMethods.includes(
+            ForgotPasswordMethod.EmailVerificationCode
+          ) && hasEmailConnector,
+        phone:
+          signInExperience.forgotPasswordMethods.includes(
+            ForgotPasswordMethod.PhoneVerificationCode
+          ) && hasSmsConnector,
+      };
+    };
+
     return {
       ...deepmerge(
         deepmerge(signInExperience, getAppSignInExperience()),
         organizationOverride ?? {}
       ),
       socialConnectors,
       ssoConnectors,
-      forgotPassword,
+      forgotPassword: getForgotPassword(),
       isDevelopmentTenant,
       googleOneTap: getGoogleOneTap(),
       captchaConfig: await getCaptchaConfig(),

packages/core/src/queries/sign-in-experience.test.ts

@@ -39,12 +39,13 @@ describe('sign-in-experience query', () => {
     captchaPolicy: JSON.stringify(mockSignInExperience.captchaPolicy),
     sentinelPolicy: JSON.stringify(mockSignInExperience.sentinelPolicy),
     emailBlocklistPolicy: JSON.stringify(mockSignInExperience.emailBlocklistPolicy),
+    forgotPasswordMethods: JSON.stringify(mockSignInExperience.forgotPasswordMethods),
   };
 
   it('findDefaultSignInExperience', async () => {
     /* eslint-disable sql/no-unsafe-query */
     const expectSql = `
-      select "tenant_id", "id", "color", "branding", "language_info", "terms_of_use_url", "privacy_policy_url", "agree_to_terms_policy", "sign_in", "sign_up", "social_sign_in", "social_sign_in_connector_targets", "sign_in_mode", "custom_css", "custom_content", "custom_ui_assets", "password_policy", "mfa", "single_sign_on_enabled", "support_email", "support_website_url", "unknown_session_redirect_url", "captcha_policy", "sentinel_policy", "email_blocklist_policy"
+      select "tenant_id", "id", "color", "branding", "language_info", "terms_of_use_url", "privacy_policy_url", "agree_to_terms_policy", "sign_in", "sign_up", "social_sign_in", "social_sign_in_connector_targets", "sign_in_mode", "custom_css", "custom_content", "custom_ui_assets", "password_policy", "mfa", "single_sign_on_enabled", "support_email", "support_website_url", "unknown_session_redirect_url", "captcha_policy", "sentinel_policy", "email_blocklist_policy", "forgot_password_methods"
       from "sign_in_experiences"
       where "id"=$1
     `;

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

@@ -1,5 +1,6 @@
 import {
   AlternativeSignUpIdentifier,
+  ForgotPasswordMethod,
   InteractionEvent,
   MissingProfile,
   type SignInExperience,
@@ -8,6 +9,7 @@ import {
   VerificationType,
 } from '@logto/schemas';
 
+import { EnvSet } from '#src/env-set/index.js';
 import RequestError from '#src/errors/RequestError/index.js';
 import { validateEmailAgainstBlocklistPolicy } from '#src/libraries/sign-in-experience/index.js';
 import type Libraries from '#src/tenants/Libraries.js';
@@ -139,7 +141,7 @@ export class SignInExperienceValidator {
         break;
       }
       case InteractionEvent.ForgotPassword: {
-        this.guardForgotPasswordVerificationMethod(verificationRecord);
+        await this.guardForgotPasswordVerificationMethod(verificationRecord);
         break;
       }
     }
@@ -342,11 +344,32 @@ export class SignInExperienceValidator {
   }
 
   /** Forgot password only supports verification code type verification record */
-  private guardForgotPasswordVerificationMethod(verificationRecord: VerificationRecord) {
+  private async guardForgotPasswordVerificationMethod(verificationRecord: VerificationRecord) {
     assertThat(
       verificationRecord.type === VerificationType.EmailVerificationCode ||
         verificationRecord.type === VerificationType.PhoneVerificationCode,
       new RequestError({ code: 'session.not_supported_for_forgot_password', status: 422 })
     );
+
+    if (EnvSet.values.isDevFeaturesEnabled) {
+      const { forgotPasswordMethods } = await this.getSignInExperienceData();
+
+      // If forgotPasswordMethods is null, fallback to connector-based validation (allow all)
+      if (forgotPasswordMethods) {
+        if (verificationRecord.type === VerificationType.EmailVerificationCode) {
+          assertThat(
+            forgotPasswordMethods.includes(ForgotPasswordMethod.EmailVerificationCode),
+            new RequestError({ code: 'session.not_supported_for_forgot_password', status: 422 })
+          );
+        }
+
+        if (verificationRecord.type === VerificationType.PhoneVerificationCode) {
+          assertThat(
+            forgotPasswordMethods.includes(ForgotPasswordMethod.PhoneVerificationCode),
+            new RequestError({ code: 'session.not_supported_for_forgot_password', status: 422 })
+          );
+        }
+      }
+    }
   }
 }

packages/core/src/routes/sign-in-experience/index.test.ts

@@ -261,4 +261,18 @@ describe('PATCH /sign-in-exp', () => {
       },
     });
   });
+
+  it('should accept empty forgotPasswordMethods array', async () => {
+    const response = await signInExperienceRequester.patch('/sign-in-exp').send({
+      forgotPasswordMethods: [],
+    });
+
+    expect(response).toMatchObject({
+      status: 200,
+      body: {
+        ...mockSignInExperience,
+        forgotPasswordMethods: [],
+      },
+    });
+  });
 });

packages/core/src/routes/sign-in-experience/index.ts

@@ -1,9 +1,10 @@
 import { DemoConnector } from '@logto/connector-kit';
 import { PasswordPolicyChecker } from '@logto/core-kit';
-import { ConnectorType, SignInExperiences } from '@logto/schemas';
+import { ConnectorType, SignInExperiences, ForgotPasswordMethod } from '@logto/schemas';
 import { conditional, tryThat } from '@silverhand/essentials';
 import { literal, object, string, z } from 'zod';
 
+import { EnvSet } from '#src/env-set/index.js';
 import {
   validateSignUp,
   validateSignIn,
@@ -82,7 +83,15 @@ export default function signInExperiencesRoutes<T extends ManagementApiRouter>(
         query: { removeUnusedDemoSocialConnector },
         body: { socialSignInConnectorTargets, emailBlocklistPolicy, ...rest },
       } = ctx.guard;
-      const { languageInfo, signUp, signIn, mfa, sentinelPolicy, captchaPolicy } = rest;
+      const {
+        languageInfo,
+        signUp,
+        signIn,
+        mfa,
+        sentinelPolicy,
+        captchaPolicy,
+        forgotPasswordMethods,
+      } = rest;
 
       if (languageInfo) {
         await validateLanguageInfo(languageInfo);
@@ -118,6 +127,26 @@ export default function signInExperiencesRoutes<T extends ManagementApiRouter>(
         validateMfa(mfa, currentSignIn);
       }
 
+      if (forgotPasswordMethods && EnvSet.values.isDevFeaturesEnabled) {
+        const hasEmailConnector = connectors.some(({ type }) => type === ConnectorType.Email);
+        const hasSmsConnector = connectors.some(({ type }) => type === ConnectorType.Sms);
+
+        for (const method of forgotPasswordMethods) {
+          if (method === ForgotPasswordMethod.EmailVerificationCode && !hasEmailConnector) {
+            throw new RequestError({
+              code: 'sign_in_experiences.forgot_password_method_requires_connector',
+              method: 'email',
+            });
+          }
+          if (method === ForgotPasswordMethod.PhoneVerificationCode && !hasSmsConnector) {
+            throw new RequestError({
+              code: 'sign_in_experiences.forgot_password_method_requires_connector',
+              method: 'sms',
+            });
+          }
+        }
+      }
+
       /* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
       // Guard the quota for the security features enabled. Guarded properties are:
       // - sentinelPolicy: if sentinelPolicy is not empty object, security features are guarded

packages/core/src/routes/well-known/well-known.test.ts

@@ -72,8 +72,13 @@ describe('GET /.well-known/sign-in-exp', () => {
     expect(findDefaultSignInExperience).toHaveBeenCalledTimes(1);
     expect(getLogtoConnectors).toHaveBeenCalledTimes(1);
     expect(response.status).toEqual(200);
+    const { forgotPasswordMethods, ...expectedSignInExperience } = mockSignInExperience;
     expect(response.body).toMatchObject({
-      ...mockSignInExperience,
+      ...expectedSignInExperience,
+      forgotPassword: {
+        email: true,
+        phone: true,
+      },
       socialConnectors: [
         {
           ...mockGithubConnector.metadata,