fix(clerk-js): Stop retrying on /verify if the client cannot solve the challenge (#5526)

Author: anagstef

.changeset/fresh-apples-add.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Stop retrying on `/verify` if the client cannot solve the challenge

packages/clerk-js/src/core/fraudProtection.ts

@@ -1,12 +1,15 @@
 import { CaptchaChallenge } from '../utils/captcha/CaptchaChallenge';
 import type { Clerk } from './resources/internal';
-import { Client, isClerkAPIResponseError } from './resources/internal';
+import { ClerkRuntimeError, Client, isClerkAPIResponseError } from './resources/internal';
 
 export class FraudProtection {
   private static instance: FraudProtection;
 
   private inflightException: Promise<unknown> | null = null;
 
+  private captchaRetryCount = 0;
+  private readonly MAX_RETRY_ATTEMPTS = 3;
+
   public static getInstance(): FraudProtection {
     if (!FraudProtection.instance) {
       FraudProtection.instance = new FraudProtection(Client, CaptchaChallenge);
@@ -20,6 +23,13 @@ export class FraudProtection {
   ) {}
 
   public async execute<T extends () => Promise<any>, R = Awaited<ReturnType<T>>>(clerk: Clerk, cb: T): Promise<R> {
+    if (this.captchaAttemptsExceeded()) {
+      throw new ClerkRuntimeError(
+        'Security verification failed. Please try again by refreshing the page, clearing your browser cookies, or using a different web browser.',
+        { code: 'captcha_client_attempts_exceeded' },
+      );
+    }
+
     try {
       if (this.inflightException) {
         await this.inflightException;
@@ -47,10 +57,15 @@ export class FraudProtection {
       let resolve: any;
       this.inflightException = new Promise<unknown>(r => (resolve = r));
 
-      const captchaParams = await this.managedChallenge(clerk);
-
       try {
-        await this.client.getOrCreateInstance().sendCaptchaToken(captchaParams);
+        const captchaParams: any = await this.managedChallenge(clerk);
+        if (captchaParams?.captchaError !== 'modal_component_not_ready') {
+          await this.client.getOrCreateInstance().sendCaptchaToken(captchaParams);
+          this.captchaRetryCount = 0; // Reset the retry count on success
+        }
+      } catch (err) {
+        this.captchaRetryCount++;
+        throw err;
       } finally {
         // Resolve the exception placeholder promise so that other exceptions can be handled
         resolve();
@@ -64,4 +79,8 @@ export class FraudProtection {
   public managedChallenge(clerk: Clerk) {
     return new this.CaptchaChallengeImpl(clerk).managedInModal({ action: 'verify' });
   }
+
+  private captchaAttemptsExceeded = () => {
+    return this.captchaRetryCount >= this.MAX_RETRY_ATTEMPTS;
+  };
 }

packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts

@@ -15,7 +15,7 @@ export class CaptchaChallenge {
     const { captchaSiteKey, canUseCaptcha, captchaPublicKeyInvisible } = retrieveCaptchaInfo(this.clerk);
 
     if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
-      return getCaptchaToken({
+      const captchaResult = await getCaptchaToken({
         siteKey: captchaPublicKeyInvisible,
         invisibleSiteKey: captchaPublicKeyInvisible,
         widgetType: 'invisible',
@@ -25,11 +25,12 @@ export class CaptchaChallenge {
         if (e.captchaError) {
           return { captchaError: e.captchaError };
         }
-        return { captchaError: e?.message || e };
+        return { captchaError: e?.message || e || 'unexpected_captcha_error' };
       });
+      return { ...captchaResult, captchaAction: opts?.action };
     }
 
-    return { captchaError: 'captcha_unavailable' };
+    return { captchaError: 'captcha_unavailable', captchaAction: opts?.action };
   }
 
   /**
@@ -45,7 +46,7 @@ export class CaptchaChallenge {
       retrieveCaptchaInfo(this.clerk);
 
     if (canUseCaptcha && captchaSiteKey && captchaPublicKeyInvisible) {
-      return getCaptchaToken({
+      const captchaResult = await getCaptchaToken({
         siteKey: captchaSiteKey,
         widgetType: captchaWidgetType,
         invisibleSiteKey: captchaPublicKeyInvisible,
@@ -55,11 +56,15 @@ export class CaptchaChallenge {
         if (e.captchaError) {
           return { captchaError: e.captchaError };
         }
-        return opts?.action === 'verify' ? { captchaError: e?.message || e } : undefined;
+        // if captcha action is signup, we return undefined, because we don't want to make the call to FAPI
+        return opts?.action === 'verify' ? { captchaError: e?.message || e || 'unexpected_captcha_error' } : undefined;
       });
+      return opts?.action === 'verify' ? { ...captchaResult, captchaAction: 'verify' } : captchaResult;
     }
 
-    return opts?.action === 'verify' ? { captchaError: 'captcha_unavailable' } : {};
+    // if captcha action is signup, we return an empty object, because it means that the bot protection is disabled
+    // and the user should be able to sign up without solving a captcha
+    return opts?.action === 'verify' ? { captchaError: 'captcha_unavailable', captchaAction: opts?.action } : {};
   }
 
   /**

packages/clerk-js/src/utils/captcha/turnstile.ts

@@ -176,7 +176,15 @@ export const getTurnstileToken = async (opts: CaptchaOptions) => {
     // but we won't show the modal as it will never escalate to interactive mode
     captchaWidgetType = widgetType;
     widgetContainerQuerySelector = modalContainerQuerySelector;
-    await openModal?.();
+    try {
+      await openModal?.();
+    } catch {
+      // When a client is captcha_block the first attempt to open the modal will fail with 'ClerkJS components are not ready yet.'
+      // This happens consistently in the first attempt, because in clerk.#loadInStandardBrowser we first await for the `/client` response
+      // and then we run initComponents to initialize the components.
+      // eslint-disable-next-line @typescript-eslint/only-throw-error
+      throw { captchaError: 'modal_component_not_ready' };
+    }
     const modalContainderEl = await waitForElement(modalContainerQuerySelector);
     if (modalContainderEl) {
       const { theme, language, size } = getCaptchaAttibutesFromElemenet(modalContainderEl);