fix(js): Coalesce concurrent first/second factor preparations

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
   action?: string;
   body?: any;
+  coalesce?: boolean;
   method?: HTTPMethod;
   path?: string;
+  signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+  promise: Promise<T>;
+  controller: AbortController;
+  expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
   id?: string;
   pathRoot = '';
 
+  #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
   static get fapiClient(): FapiClient {
     return BaseResource.clerk.getFapiClient();
   }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
   }
 
   protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
-    const { action, body, method, path } = params;
+    const { action, body, method, path, signal } = params;
     // TODO @userland-errors:
-    const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+    const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
     return this.fromJSON((json?.response || json) as J);
   }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
   }
 
   protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
-    return this._baseMutate<J>({ ...params, method: 'POST' });
+    if (!params.coalesce) {
+      return this._baseMutate<J>({ ...params, method: 'POST' });
+    }
+
+    const key = this.#coalescedPostKey(params);
+    const posts = (this.#pendingCoalescedPosts ??= new Map());
+    const pending = posts.get(key);
+    if (pending && Date.now() < pending.expiresAt) {
+      return pending.promise;
+    }
+
+    const controller = new AbortController();
+    const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+      if (posts.get(key)?.promise === promise) {
+        posts.delete(key);
+      }
+    });
+    posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+    return promise;
+  }
+
+  #coalescedPostKey(params: BaseMutateParams): string {
+    const body = Object.entries(params.body ?? {})
+      .filter(([, value]) => value !== undefined)
+      .sort(([left], [right]) => (left < right ? -1 : 1));
+    return JSON.stringify([this.id, params.path, params.action, body]);
   }
 
   protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
   prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
     return this._basePost<EmailAddressJSON>({
       action: 'prepare_verification',
+      coalesce: true,
       body: { ...params },
     });
   };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
   prepareVerification = (): Promise<PhoneNumberResource> => {
     return this._basePost<PhoneNumberJSON>({
       action: 'prepare_verification',
+      coalesce: true,
       body: { strategy: 'phone_code' },
     });
   };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
     return this._basePost({
       body: { ...config, strategy: params.strategy },
       action: 'prepare_first_factor',
+      coalesce: true,
     });
   };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
     return this._basePost({
       body: params,
       action: 'prepare_second_factor',
+      coalesce: true,
     });
   };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { emailAddressId, strategy: 'reset_password_email_code' },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
     });
   }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { phoneNumberId, strategy: 'reset_password_phone_code' },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
     });
   }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
     });
   }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
           strategy: 'email_link',
         },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
     });
   }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
     });
   }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
             strategy: 'enterprise_sso',
           },
           action: 'prepare_first_factor',
+          coalesce: true,
         });
       }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
         action: 'prepare_first_factor',
+        coalesce: true,
       });
 
       const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
         await this.#resource.__internal_basePost({
           body: { strategy: 'passkey' },
           action: 'prepare_first_factor',
+          coalesce: true,
         });
       }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { phoneNumberId, strategy: 'phone_code' },
         action: 'prepare_second_factor',
+        coalesce: true,
       });
     });
   }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
       await this.#resource.__internal_basePost({
         body: { emailAddressId, strategy: 'email_code' },
         action: 'prepare_second_factor',
+        coalesce: true,
       });
     });
   }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
     return this._basePost({
       body: params,
       action: 'prepare_verification',
+      coalesce: true,
     });
   };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
       await this.#resource.__internal_basePost({
         body: { strategy: 'email_code' },
         action: 'prepare_verification',
+        coalesce: true,
       });
     });
   }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
       await this.#resource.__internal_basePost({
         body: { strategy: 'phone_code', channel },
         action: 'prepare_verification',
+        coalesce: true,
       });
     });
   }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
       await this.#resource.__internal_basePost({
         body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
         action: 'prepare_verification',
+        coalesce: true,
       });
     });
   }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
       await this.#resource.__internal_basePost({
         body: { strategy },
         action: 'prepare_verification',
+        coalesce: true,
       });
 
       const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
   prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
     return this._basePost<Web3WalletJSON>({
       action: 'prepare_verification',
+      coalesce: true,
       body: { ...params },
     });
   };

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

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+  describe('prepareVerification', () => {
+    afterEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('coalesces concurrent identical preparations', async () => {
+      const deferred = createDeferredPromise<any>();
+      const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+      // @ts-ignore
+      BaseResource._fetch = mockFetch;
+
+      const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const params = { strategy: 'email_code' as const };
+
+      const first = emailAddress.prepareVerification(params);
+      const second = emailAddress.prepareVerification(params);
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+
+      deferred.resolve({
+        response: { id: 'email_123' },
+      });
+      await Promise.all([first, second]);
+    });
+
+    it('does not coalesce preparations with different strategies or params', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        response: { id: 'email_123' },
+      });
+      BaseResource._fetch = mockFetch;
+
+      const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+      await Promise.all([
+        emailAddress.prepareVerification({ strategy: 'email_code' }),
+        emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+        emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+      ]);
+
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
+
+    it('starts a new preparation after the previous request succeeds', async () => {
+      const mockFetch = vi.fn().mockResolvedValue({
+        response: { id: 'email_123' },
+      });
+      // @ts-ignore
+      BaseResource._fetch = mockFetch;
+
+      const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const params = { strategy: 'email_code' as const };
+
+      await emailAddress.prepareVerification(params);
+      await emailAddress.prepareVerification(params);
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('starts a new preparation after the previous request fails', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockRejectedValueOnce(new Error('prepare failed'))
+        .mockResolvedValueOnce({
+          response: { id: 'email_123' },
+        });
+      BaseResource._fetch = mockFetch;
+
+      const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const params = { strategy: 'email_code' as const };
+
+      await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+      await emailAddress.prepareVerification(params);
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('does not coalesce preparations across EmailAddress instances', async () => {
+      const deferred = createDeferredPromise<any>();
+      const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+      BaseResource._fetch = mockFetch;
+
+      const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const params = { strategy: 'email_code' as const };
+
+      const first = firstEmailAddress.prepareVerification(params);
+      const second = secondEmailAddress.prepareVerification(params);
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      deferred.resolve({
+        response: { id: 'email_123' },
+      });
+      await Promise.all([first, second]);
+    });
+
+    it('does not coalesce concurrent verification attempts', async () => {
+      const deferred = createDeferredPromise<any>();
+      const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+      BaseResource._fetch = mockFetch;
+
+      const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+      const params = { code: '123456' };
+
+      const first = emailAddress.attemptVerification(params);
+      const second = emailAddress.attemptVerification(params);
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      deferred.resolve({
+        response: { id: 'email_123' },
+      });
+      await Promise.all([first, second]);
+    });
+  });
+});