feat(clerk-js): Trigger a new request to submit the captcha token

.changeset/dark-moons-sort.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Trigger a new request to submit the captcha token on sign up when executing the `signUp.create` method.

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

@@ -26,6 +26,7 @@ export class DisplayConfig extends BaseResource implements DisplayConfigResource
   branded: boolean = false;
   captchaHeartbeat: boolean = false;
   captchaHeartbeatIntervalMs?: number;
+  twoStepSignUpCreateEnabled: boolean = false;
   captchaOauthBypass: OAuthStrategy[] = ['oauth_google', 'oauth_microsoft', 'oauth_apple'];
   captchaProvider: CaptchaProvider = 'turnstile';
   captchaPublicKey: string | null = null;
@@ -80,6 +81,10 @@ export class DisplayConfig extends BaseResource implements DisplayConfigResource
     this.applicationName = this.withDefault(data.application_name, this.applicationName);
     this.branded = this.withDefault(data.branded, this.branded);
     this.captchaHeartbeat = this.withDefault(data.captcha_heartbeat, this.captchaHeartbeat);
+    this.twoStepSignUpCreateEnabled = this.withDefault(
+      data.two_step_sign_up_create_enabled,
+      this.twoStepSignUpCreateEnabled,
+    );
     this.captchaHeartbeatIntervalMs = this.withDefault(
       data.captcha_heartbeat_interval_ms,
       this.captchaHeartbeatIntervalMs,
@@ -130,6 +135,7 @@ export class DisplayConfig extends BaseResource implements DisplayConfigResource
       branded: this.branded,
       captcha_heartbeat_interval_ms: this.captchaHeartbeatIntervalMs,
       captcha_heartbeat: this.captchaHeartbeat,
+      two_step_sign_up_create_enabled: this.twoStepSignUpCreateEnabled,
       captcha_oauth_bypass: this.captchaOauthBypass,
       captcha_provider: this.captchaProvider,
       captcha_public_key_invisible: this.captchaPublicKeyInvisible,

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

@@ -14,13 +14,15 @@ import type {
   PrepareVerificationParams,
   PrepareWeb3WalletVerificationParams,
   SignUpAuthenticateWithWeb3Params,
+  SignUpCreateOptions,
   SignUpCreateParams,
   SignUpField,
   SignUpIdentificationField,
   SignUpJSON,
   SignUpJSONSnapshot,
   SignUpResource,
   SignUpStatus,
+  SignUpUpdateOptions,
   SignUpUpdateParams,
   StartEmailLinkFlowParams,
   Web3Provider,
@@ -45,7 +47,7 @@ import {
   clerkVerifyEmailAddressCalledBeforeCreate,
   clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
-import { BaseResource, ClerkRuntimeError, SignUpVerifications } from './internal';
+import { BaseResource, SignUpVerifications } from './internal';
 
 declare global {
   interface Window {
@@ -82,16 +84,23 @@ export class SignUp extends BaseResource implements SignUpResource {
     this.fromJSON(data);
   }
 
-  create = async (_params: SignUpCreateParams): Promise<SignUpResource> => {
+  create = async (_params: SignUpCreateParams, options?: SignUpCreateOptions): Promise<SignUpResource> => {
+    if (SignUp.clerk.__unstable__environment?.displayConfig?.twoStepSignUpCreateEnabled) {
+      return this.twoStepCreate(_params, options);
+    }
+
+    // This is the old flow and will be completely replaced by the two step flow when it's rolled out to everyone
+    return this.legacyCreate(_params);
+  };
+
+  private legacyCreate = async (_params: SignUpCreateParams): Promise<SignUpResource> => {
     let params: Record<string, unknown> = _params;
 
-    if (!__BUILD_DISABLE_RHC__ && !this.clientBypass() && !this.shouldBypassCaptchaForAttempt(params)) {
-      const captchaChallenge = new CaptchaChallenge(SignUp.clerk);
-      const captchaParams = await captchaChallenge.managedOrInvisible({ action: 'signup' });
-      if (!captchaParams) {
-        throw new ClerkRuntimeError('', { code: 'captcha_unavailable' });
+    if (!this.shouldBypassCaptchaForAttempt(params)) {
+      const captchaParams = await this.solveCaptchaChallenge();
+      if (captchaParams) {
+        params = { ...params, ...captchaParams };
       }
-      params = { ...params, ...captchaParams };
     }
 
     if (params.transfer && this.shouldBypassCaptchaForAttempt(params)) {
@@ -104,6 +113,33 @@ export class SignUp extends BaseResource implements SignUpResource {
     });
   };
 
+  private twoStepCreate = async (
+    _params: SignUpCreateParams,
+    options?: SignUpCreateOptions,
+  ): Promise<SignUpResource> => {
+    const params: Record<string, unknown> = _params;
+
+    // This is a legacy flow, where we allowed specific OAuth providers to bypass the captcha
+    // This is no longer supported, but we need to keep it for backwards compatibility
+    if (params.transfer && this.shouldBypassCaptchaForAttempt(params)) {
+      params.strategy = SignUp.clerk.client?.signIn.firstFactorVerification.strategy;
+    }
+
+    await this._basePost({
+      path: this.pathRoot,
+      body: normalizeUnsafeMetadata(params),
+    });
+
+    if (!this.shouldBypassCaptchaForAttempt(params) && !options?.skipCaptchaChallenge) {
+      return this.update(
+        { strategy: params.strategy as SignUpUpdateParams['strategy'] },
+        { triggerCaptchaChallenge: true },
+      );
+    }
+
+    return this;
+  };
+
   prepareVerification = (params: PrepareVerificationParams): Promise<this> => {
     return this._basePost({
       body: params,
@@ -346,7 +382,18 @@ export class SignUp extends BaseResource implements SignUpResource {
     });
   };
 
-  update = (params: SignUpUpdateParams): Promise<SignUpResource> => {
+  update = async (params: SignUpUpdateParams, options?: SignUpUpdateOptions): Promise<SignUpResource> => {
+    const isCaptchaChallengeMissingAndRequired =
+      this.missingFields.some(field => field === 'captcha_challenge') &&
+      this.requiredFields.some(field => field === 'captcha_challenge');
+
+    if (options?.triggerCaptchaChallenge && isCaptchaChallengeMissingAndRequired) {
+      const captchaParams = await this.solveCaptchaChallenge();
+      if (captchaParams) {
+        params = { ...params, ...captchaParams };
+      }
+    }
+
     return this._basePatch({
       body: normalizeUnsafeMetadata(params),
     });
@@ -417,12 +464,24 @@ export class SignUp extends BaseResource implements SignUpResource {
     };
   }
 
+  private solveCaptchaChallenge = async (): Promise<Record<string, unknown> | undefined> => {
+    let params: Record<string, unknown> | undefined;
+
+    if (!__BUILD_DISABLE_RHC__ && !this.clientBypass()) {
+      const captchaChallenge = new CaptchaChallenge(SignUp.clerk);
+      params = await captchaChallenge.managedOrInvisible({ action: 'signup' });
+    }
+
+    return params;
+  };
+
   private clientBypass() {
     return SignUp.clerk.client?.captchaBypass;
   }
 
   /**
    * We delegate bot detection to the following providers, instead of relying on turnstile exclusively
+   * This is a legacy flow, where we allowed specific OAuth providers to bypass the captcha
    */
   protected shouldBypassCaptchaForAttempt(params: SignUpCreateParams) {
     if (!params.strategy) {

packages/clerk-js/src/ui/components/SignUp/SignUpContinue.tsx

@@ -170,7 +170,7 @@ function SignUpContinueInternal() {
     card.setError(undefined);
 
     return signUp
-      .update(buildRequest(fieldsToSubmit))
+      .update(buildRequest(fieldsToSubmit), { triggerCaptchaChallenge: true })
       .then(res =>
         completeSignUpFlow({
           signUp: res,

packages/clerk-js/src/ui/components/SignUp/SignUpStart.tsx

@@ -220,8 +220,8 @@ function SignUpStartInternal(): JSX.Element {
 
         // TODO: This is a hack to reset the sign in attempt so that the oauth error
         // does not persist on full page reloads.
-        // We will revise this strategy as part of the Clerk DX epic.
-        void (await signUp.create({}));
+        // This will be handled by the backend (FAPI) in the future.
+        void (await signUp.create({}, { skipCaptchaChallenge: true }));
       }
     }
 

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

@@ -56,15 +56,14 @@ export class CaptchaChallenge {
         if (e.captchaError) {
           return { captchaError: e.captchaError };
         }
-        // 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 { captchaError: e?.message || e || 'unexpected_captcha_error' };
       });
-      return opts?.action === 'verify' ? { ...captchaResult, captchaAction: 'verify' } : captchaResult;
+      return { ...captchaResult, captchaAction: opts?.action };
     }
 
-    // if captcha action is signup, we return an empty object, because it means that the bot protection is disabled
+    // if captcha action is signup, we return undefined, 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 } : {};
+    return opts?.action === 'verify' ? { captchaError: 'captcha_unavailable', captchaAction: opts?.action } : undefined;
   }
 
   /**

packages/types/src/attributes.ts

@@ -2,3 +2,4 @@ export type FirstNameAttribute = 'first_name';
 export type LastNameAttribute = 'last_name';
 export type PasswordAttribute = 'password';
 export type LegalAcceptedAttribute = 'legal_accepted';
+export type CaptchaChallengeAttribute = 'captcha_challenge';

packages/types/src/displayConfig.ts

@@ -24,6 +24,7 @@ export interface DisplayConfigJSON {
   captcha_oauth_bypass: OAuthStrategy[] | null;
   captcha_heartbeat?: boolean;
   captcha_heartbeat_interval_ms?: number;
+  two_step_sign_up_create_enabled?: boolean;
   home_url: string;
   instance_environment_type: string;
   logo_image_url: string;
@@ -69,6 +70,7 @@ export interface DisplayConfigResource extends ClerkResource {
   captchaOauthBypass: OAuthStrategy[];
   captchaHeartbeat: boolean;
   captchaHeartbeatIntervalMs?: number;
+  twoStepSignUpCreateEnabled?: boolean;
   homeUrl: string;
   instanceEnvironmentType: string;
   logoImageUrl: string;

packages/types/src/signUp.ts

@@ -1,6 +1,12 @@
 import type { PhoneCodeChannel } from 'phoneCodeChannel';
 
-import type { FirstNameAttribute, LastNameAttribute, LegalAcceptedAttribute, PasswordAttribute } from './attributes';
+import type {
+  CaptchaChallengeAttribute,
+  FirstNameAttribute,
+  LastNameAttribute,
+  LegalAcceptedAttribute,
+  PasswordAttribute,
+} from './attributes';
 import type { AttemptEmailAddressVerificationParams, PrepareEmailAddressVerificationParams } from './emailAddress';
 import type {
   EmailAddressIdentifier,
@@ -71,9 +77,9 @@ export interface SignUpResource extends ClerkResource {
   abandonAt: number | null;
   legalAcceptedAt: number | null;
 
-  create: (params: SignUpCreateParams) => Promise<SignUpResource>;
+  create: (params: SignUpCreateParams, options?: SignUpCreateOptions) => Promise<SignUpResource>;
 
-  update: (params: SignUpUpdateParams) => Promise<SignUpResource>;
+  update: (params: SignUpUpdateParams, options?: SignUpUpdateOptions) => Promise<SignUpResource>;
 
   upsert: (params: SignUpCreateParams | SignUpUpdateParams) => Promise<SignUpResource>;
 
@@ -160,7 +166,12 @@ export type AttemptVerificationParams =
       signature: string;
     };
 
-export type SignUpAttributeField = FirstNameAttribute | LastNameAttribute | PasswordAttribute | LegalAcceptedAttribute;
+export type SignUpAttributeField =
+  | FirstNameAttribute
+  | LastNameAttribute
+  | PasswordAttribute
+  | LegalAcceptedAttribute
+  | CaptchaChallengeAttribute;
 
 // TODO: SignUpVerifiableField or SignUpIdentifier?
 export type SignUpVerifiableField =
@@ -199,6 +210,14 @@ export type SignUpCreateParams = Partial<
   } & Omit<SnakeToCamel<Record<SignUpAttributeField | SignUpVerifiableField, string>>, 'legalAccepted'>
 >;
 
+export type SignUpCreateOptions = Partial<{
+  skipCaptchaChallenge: boolean;
+}>;
+
+export type SignUpUpdateOptions = Partial<{
+  triggerCaptchaChallenge: boolean;
+}>;
+
 export type SignUpUpdateParams = SignUpCreateParams;
 
 /**