feat(clerk-js,shared): Add support for email code MFA to SignInFuture

.changeset/gold-seals-sort.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+---
+
+Add support for email code MFA to SignInFuture

packages/clerk-js/src/core/resources/SignIn.ts

@@ -42,6 +42,7 @@ import type {
   SignInFutureEmailCodeVerifyParams,
   SignInFutureEmailLinkSendParams,
   SignInFutureFinalizeParams,
+  SignInFutureMFAEmailCodeVerifyParams,
   SignInFutureMFAPhoneCodeVerifyParams,
   SignInFuturePasskeyParams,
   SignInFuturePasswordParams,
@@ -643,6 +644,8 @@ class SignInFuture implements SignInFutureResource {
   mfa = {
     sendPhoneCode: this.sendMFAPhoneCode.bind(this),
     verifyPhoneCode: this.verifyMFAPhoneCode.bind(this),
+    sendEmailCode: this.sendMFAEmailCode.bind(this),
+    verifyEmailCode: this.verifyMFAEmailCode.bind(this),
     verifyTOTP: this.verifyTOTP.bind(this),
     verifyBackupCode: this.verifyBackupCode.bind(this),
   };
@@ -1174,6 +1177,32 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
+  async sendMFAEmailCode(): Promise<{ error: ClerkError | null }> {
+    return runAsyncResourceTask(this.#resource, async () => {
+      const emailCodeFactor = this.#resource.supportedSecondFactors?.find(f => f.strategy === 'email_code');
+
+      if (!emailCodeFactor) {
+        throw new ClerkRuntimeError('Email code factor not found', { code: 'factor_not_found' });
+      }
+
+      const { emailAddressId } = emailCodeFactor;
+      await this.#resource.__internal_basePost({
+        body: { emailAddressId, strategy: 'email_code' },
+        action: 'prepare_second_factor',
+      });
+    });
+  }
+
+  async verifyMFAEmailCode(params: SignInFutureMFAEmailCodeVerifyParams): Promise<{ error: ClerkError | null }> {
+    const { code } = params;
+    return runAsyncResourceTask(this.#resource, async () => {
+      await this.#resource.__internal_basePost({
+        body: { code, strategy: 'email_code' },
+        action: 'attempt_second_factor',
+      });
+    });
+  }
+
   async verifyTOTP(params: SignInFutureTOTPVerifyParams): Promise<{ error: ClerkError | null }> {
     const { code } = params;
     return runAsyncResourceTask(this.#resource, async () => {

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -979,6 +979,48 @@ describe('SignIn', () => {
       });
     });
 
+    describe('sendMFAEmailCode', () => {
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('prepares second factor with email code', async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+          client: null,
+          response: { id: 'signin_123' },
+        });
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn({
+          id: 'signin_123',
+          supported_second_factors: [
+            { strategy: 'email_code', email_address_id: 'email_123', safe_identifier: '[email protected]' },
+          ],
+        } as any);
+        await signIn.__internal_future.mfa.sendEmailCode();
+
+        expect(mockFetch).toHaveBeenCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/signin_123/prepare_second_factor',
+          body: {
+            emailAddressId: 'email_123',
+            strategy: 'email_code',
+          },
+        });
+      });
+
+      it('returns error when email code factor not found', async () => {
+        const signIn = new SignIn({
+          id: 'signin_123',
+          supported_second_factors: [{ strategy: 'totp' }],
+        } as any);
+        const result = await signIn.__internal_future.mfa.sendEmailCode();
+
+        expect(result.error).toBeTruthy();
+        expect(result.error?.code).toBe('factor_not_found');
+      });
+    });
+
     describe('passkey', () => {
       afterEach(() => {
         vi.clearAllMocks();

packages/react/src/stateProxy.ts

@@ -175,6 +175,8 @@ export class StateProxy implements State {
         mfa: this.wrapMethods(() => target().mfa, [
           'sendPhoneCode',
           'verifyPhoneCode',
+          'sendEmailCode',
+          'verifyEmailCode',
           'verifyTOTP',
           'verifyBackupCode',
         ] as const),

packages/shared/src/types/signInFuture.ts

@@ -218,6 +218,13 @@ export interface SignInFutureMFAPhoneCodeVerifyParams {
   code: string;
 }
 
+export interface SignInFutureMFAEmailCodeVerifyParams {
+  /**
+   * The one-time code that was sent to the user as part of the `signIn.mfa.sendEmailCode()` method.
+   */
+  code: string;
+}
+
 export interface SignInFutureTOTPVerifyParams {
   /**
    * The TOTP generated by the user's authenticator app.
@@ -468,6 +475,16 @@ export interface SignInFutureResource {
      */
     verifyPhoneCode: (params: SignInFutureMFAPhoneCodeVerifyParams) => Promise<{ error: ClerkError | null }>;
 
+    /**
+     * Used to send an email code as a second factor to sign-in
+     */
+    sendEmailCode: () => Promise<{ error: ClerkError | null }>;
+
+    /**
+     * Used to verify an email code sent as a second factor to sign-in
+     */
+    verifyEmailCode: (params: SignInFutureMFAEmailCodeVerifyParams) => Promise<{ error: ClerkError | null }>;
+
     /**
      * Used to verify a TOTP code as a second factor to sign-in
      */