Skip to content

feat(clerk-js): Add support for captcha to Signal SignUp #6574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dstaley merged 6 commits into from
Aug 20, 2025
Merged

feat(clerk-js): Add support for captcha to Signal SignUp #6574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d98c7fc
feat(clerk-js): Add support for captcha to Signal SignUp
dstaley Aug 19, 2025
06b9adb
Merge branch 'main' into ds.feat/signals-signup-captcha
dstaley Aug 19, 2025
f469327
fix(clerk-js): Bump bundle limit
dstaley Aug 19, 2025
fb26e86
fix(clerk-js): Always submit captchaError to FAPI
dstaley Aug 20, 2025
9ffb2aa
Merge branch 'main' into ds.feat/signals-signup-captcha
dstaley Aug 20, 2025
724451a
Merge branch 'main' into ds.feat/signals-signup-captcha
dstaley Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/blue-cloths-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clerk/clerk-js': minor
---

[Experimental] Add support for captcha to Signal SignUp
27 changes: 26 additions & 1 deletion packages/clerk-js/src/core/resources/SignUp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import type {
AuthenticateWithPopupParams,
AuthenticateWithRedirectParams,
AuthenticateWithWeb3Params,
CaptchaWidgetType,
CreateEmailLinkFlowReturn,
PrepareEmailAddressVerificationParams,
PreparePhoneNumberVerificationParams,
Expand Down Expand Up @@ -487,11 +488,35 @@ class SignUpFuture implements SignUpFutureResource {
return this.resource.unverifiedFields;
}

private async getCaptchaToken(): Promise<{
captchaToken?: string;
captchaWidgetType?: CaptchaWidgetType;
captchaError?: unknown;
}> {
const captchaChallenge = new CaptchaChallenge(SignUp.clerk);
const response = await captchaChallenge.managedOrInvisible({ action: 'signup' });
if (!response) {
throw new Error('Captcha challenge failed');
Copy link
Member

@brkalow brkalow Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this use ClerkRuntimeError? Or not because it's only internal?

Copy link
Member Author

@dstaley dstaley Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is me kicking that can down the road until I can do an error pass across the entire implementation 😅

Copy link
Member

@brkalow brkalow Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't forget 😉

}

const { captchaError, captchaToken, captchaWidgetType } = response;
return { captchaToken, captchaWidgetType, captchaError };
}

async password({ emailAddress, password }: { emailAddress: string; password: string }): Promise<{ error: unknown }> {
return runAsyncResourceTask(this.resource, async () => {
const { captchaToken, captchaWidgetType, captchaError } = await this.getCaptchaToken();

await this.resource.__internal_basePost({
path: this.resource.pathRoot,
body: { emailAddress, password },
body: {
strategy: 'password',
emailAddress,
password,
captchaToken,
captchaWidgetType,
captchaError,
},
});
});
}
Comment on lines 506 to 522
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Password flow unconditionally requires CAPTCHA; bypass and retry semantics missing

As written, password() always requests a CAPTCHA token and will throw if CAPTCHA is disabled/unavailable (e.g., bypass or dev env). This diverges from create() and authenticateWithRedirectOrPopup(), which gate CAPTCHA and retry on environment/captcha errors. This will break password signup in environments where CAPTCHA is intentionally bypassed or temporarily unavailable.

Proposed fix:

  • Gate CAPTCHA retrieval on the same conditions used elsewhere (respect build flag and client bypass).
  • Retry once on CAPTCHA-related API errors after reloading the environment.
  • Spread optional captchaParams into the request body to omit absent fields.

Apply this diff:

   async password({ emailAddress, password }: { emailAddress: string; password: string }): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
-      const { captchaToken, captchaWidgetType, captchaError } = await this.getCaptchaToken();
-
-      await this.resource.__internal_basePost({
-        path: this.resource.pathRoot,
-        body: {
-          strategy: 'password',
-          emailAddress,
-          password,
-          captchaToken,
-          captchaWidgetType,
-          captchaError,
-        },
-      });
+      const shouldFetchCaptcha = !__BUILD_DISABLE_RHC__ && !SignUp.clerk.client?.captchaBypass;
+
+      let captchaParams: Partial<{
+        captchaToken: string;
+        captchaWidgetType: CaptchaWidgetType;
+        captchaError: unknown;
+      }> = {};
+
+      if (shouldFetchCaptcha) {
+        captchaParams = await this.getCaptchaToken();
+      }
+
+      const post = () =>
+        this.resource.__internal_basePost({
+          path: this.resource.pathRoot,
+          body: {
+            strategy: 'password',
+            emailAddress,
+            password,
+            ...captchaParams,
+          },
+        });
+
+      try {
+        await post();
+      } catch (e) {
+        if (isClerkAPIResponseError(e) && isCaptchaError(e)) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          await SignUp.clerk.__unstable__environment!.reload();
+          if (shouldFetchCaptcha) {
+            captchaParams = await this.getCaptchaToken();
+          }
+          await post();
+        } else {
+          throw e;
+        }
+      }
     });
   }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
async password({ emailAddress, password }: { emailAddress: string; password: string }): Promise<{ error: unknown }> {
return runAsyncResourceTask(this.resource, async () => {
const { captchaToken, captchaWidgetType, captchaError } = await this.getCaptchaToken();
await this.resource.__internal_basePost({
path: this.resource.pathRoot,
body: { emailAddress, password },
body: {
strategy: 'password',
emailAddress,
password,
captchaToken,
captchaWidgetType,
captchaError,
},
});
});
}
async password({ emailAddress, password }: { emailAddress: string; password: string }): Promise<{ error: unknown }> {
return runAsyncResourceTask(this.resource, async () => {
const shouldFetchCaptcha = !__BUILD_DISABLE_RHC__ && !SignUp.clerk.client?.captchaBypass;
let captchaParams: Partial<{
captchaToken: string;
captchaWidgetType: CaptchaWidgetType;
captchaError: unknown;
}> = {};
if (shouldFetchCaptcha) {
captchaParams = await this.getCaptchaToken();
}
const post = () =>
this.resource.__internal_basePost({
path: this.resource.pathRoot,
body: {
strategy: 'password',
emailAddress,
password,
...captchaParams,
},
});
try {
await post();
} catch (e) {
if (isClerkAPIResponseError(e) && isCaptchaError(e)) {
// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
await SignUp.clerk.__unstable__environment!.reload();
if (shouldFetchCaptcha) {
captchaParams = await this.getCaptchaToken();
}
await post();
} else {
throw e;
}
}
});
}
🤖 Prompt for AI Agents 
In packages/clerk-js/src/core/resources/SignUp.ts around lines 506-522, the
password() flow always requests a CAPTCHA token which fails in bypass/dev
environments; update it to only call getCaptchaToken when the same
CAPTCHA-enabled conditions used by create() and
authenticateWithRedirectOrPopup() are met (respecting build flags and client
bypass), spread the optional captchaParams into the POST body so absent fields
aren’t sent, and wrap the API call in a retry that, on CAPTCHA-related API
errors, reloads the environment and retries the POST once before failing.

Expand Down
9 changes: 8 additions & 1 deletion packages/clerk-js/src/utils/captcha/CaptchaChallenge.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import type { CaptchaWidgetType } from '@clerk/types';

import type { Clerk } from '../../core/resources/internal';
import { getCaptchaToken } from './getCaptchaToken';
import { retrieveCaptchaInfo } from './retrieveCaptchaInfo';
Expand Down Expand Up @@ -42,7 +44,12 @@ export class CaptchaChallenge {
*
* Managed challenged start as non-interactive and escalate to interactive if necessary.
*/
public async managedOrInvisible(opts?: Partial<CaptchaOptions>) {
public async managedOrInvisible(
opts?: Partial<CaptchaOptions>,
): Promise<
| { captchaError?: string; captchaAction?: string; captchaToken?: string; captchaWidgetType?: CaptchaWidgetType }
| undefined
> {
const { captchaSiteKey, canUseCaptcha, captchaWidgetType, captchaProvider, captchaPublicKeyInvisible, nonce } =
retrieveCaptchaInfo(this.clerk);

Expand Down
Loading