feat(clerk-js,shared,ui): Add Protect SDK challenge support during sign-up and sign-in (#8329)

Co-authored-by: Jacek Radko <jacek@clerk.dev>

Author: zourzouvillys

.changeset/protect-check-support.md

@@ -0,0 +1,30 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/react': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add support for Clerk Protect mid-flow SDK challenges (`protect_check`) on both sign-up and sign-in.
+
+When the Protect antifraud service issues a challenge, responses now carry a `protectCheck` field
+with `{ status, token, sdkUrl, expiresAt?, uiHints? }`. Clients resolve the gate by loading the
+SDK at `sdkUrl`, executing the challenge, and submitting the resulting proof token via
+`signUp.submitProtectCheck({ proofToken })` or `signIn.submitProtectCheck({ proofToken })`. The
+response may carry a chained challenge, which the SDK resolves iteratively.
+
+Sign-in adds a new `'needs_protect_check'` value to the `SignInStatus` union. **Upgrading this
+package is type-only and does not change runtime behavior**: the server returns the new status
+(and the `protectCheck` field) only for instances where Protect mid-flow challenges have been
+explicitly enabled — the feature is off by default and is not enabled for existing instances by
+upgrading. The server additionally only emits the new status value to SDK versions that
+understand it, so older clients never receive an unknown status.
+
+If an exhaustive `switch` on `signIn.status` flags the new value after upgrading, handle it by
+running the challenge described by `protectCheck` and submitting the proof via
+`submitProtectCheck()`. Clients should treat the `protectCheck` field as the authoritative gate
+signal and fall back to the status value for defense in depth.
+
+The pre-built `<SignIn />` and `<SignUp />` components handle the gate automatically by routing
+to a new `protect-check` route that runs the challenge SDK and resumes the flow on completion.

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

@@ -2418,6 +2418,97 @@ describe('Clerk singleton', () => {
         expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
       });
     });
+
+    it('does not route a sign-up callback into a stale sign-in protect_check gate', async () => {
+      mockEnvironmentFetch.mockReturnValue(
+        Promise.resolve({
+          authConfig: {},
+          userSettings: mockUserSettings,
+          displayConfig: mockDisplayConfig,
+          isSingleSession: () => false,
+          isProduction: () => false,
+          isDevelopmentOrStaging: () => true,
+          onWindowLocationHost: () => false,
+        }),
+      );
+
+      // An abandoned sign-in keeps serializing its pending protect_check on the client.
+      const staleSignIn = new SignIn({
+        status: 'needs_protect_check',
+        identifier: 'user@example.com',
+        first_factor_verification: null,
+        second_factor_verification: null,
+        user_data: null,
+        created_session_id: null,
+        created_user_id: null,
+        protect_check: { status: 'pending', token: 'stale-token', sdk_url: 'https://example.com/sdk.js' },
+      } as any as SignInJSON);
+      const completeSignUp = new SignUp({ status: 'complete', created_session_id: 'sess_signup' } as any as SignUpJSON);
+      // The intent-driven reload at the top of the handler is a no-op here; keep the state stable.
+      (staleSignIn as any).reload = vi.fn().mockResolvedValue(staleSignIn);
+      (completeSignUp as any).reload = vi.fn().mockResolvedValue(completeSignUp);
+
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          signedInSessions: [],
+          signIn: staleSignIn,
+          signUp: completeSignUp,
+        }),
+      );
+
+      const mockSetActive = vi.fn();
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+      sut.setActive = mockSetActive;
+
+      await sut.handleRedirectCallback({ reloadResource: 'signUp' });
+
+      await waitFor(() => {
+        // Completes the sign-up rather than routing into the stale sign-in's challenge.
+        expect(mockSetActive).toHaveBeenCalled();
+        expect(mockNavigate).not.toHaveBeenCalledWith('/sign-in#/protect-check');
+      });
+    });
+
+    it('routes a sign-in callback to the protect-check gate', async () => {
+      mockEnvironmentFetch.mockReturnValue(
+        Promise.resolve({
+          authConfig: {},
+          userSettings: mockUserSettings,
+          displayConfig: mockDisplayConfig,
+          isSingleSession: () => false,
+          isProduction: () => false,
+          isDevelopmentOrStaging: () => true,
+          onWindowLocationHost: () => false,
+        }),
+      );
+
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          signedInSessions: [],
+          signIn: new SignIn({
+            status: 'needs_protect_check',
+            identifier: 'user@example.com',
+            first_factor_verification: null,
+            second_factor_verification: null,
+            user_data: null,
+            created_session_id: null,
+            created_user_id: null,
+            protect_check: { status: 'pending', token: 'fresh-token', sdk_url: 'https://example.com/sdk.js' },
+          } as any as SignInJSON),
+          signUp: new SignUp(null),
+        }),
+      );
+
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+
+      await sut.handleRedirectCallback();
+
+      await waitFor(() => {
+        expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/protect-check');
+      });
+    });
   });
 
   describe('.handleEmailLinkVerification()', () => {

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

@@ -2379,6 +2379,7 @@ export class Clerk implements ClerkInterface {
       externalAccountErrorCode: externalAccount.error?.code,
       externalAccountSessionId: externalAccount.error?.meta?.sessionId,
       sessionId: signUp.createdSessionId,
+      protectCheck: signUp.protectCheck,
     };
 
     const si = {
@@ -2387,6 +2388,7 @@ export class Clerk implements ClerkInterface {
       firstFactorVerificationErrorCode: firstFactorVerification.error?.code,
       firstFactorVerificationSessionId: firstFactorVerification.error?.meta?.sessionId,
       sessionId: signIn.createdSessionId,
+      protectCheck: signIn.protectCheck,
     };
 
     const makeNavigate = (to: string) => () => navigate(to);
@@ -2410,6 +2412,11 @@ export class Clerk implements ClerkInterface {
         buildURL({ base: displayConfig.signInUrl, hashPath: '/reset-password' }, { stringify: true }),
     );
 
+    const navigateToSignInProtectCheck = makeNavigate(
+      params.signInProtectCheckUrl ||
+        buildURL({ base: displayConfig.signInUrl, hashPath: '/protect-check' }, { stringify: true }),
+    );
+
     const redirectUrls = new RedirectUrls(this.#options, params);
 
     const navigateToContinueSignUp = makeNavigate(
@@ -2423,7 +2430,19 @@ export class Clerk implements ClerkInterface {
         ),
     );
 
+    const navigateToSignUpProtectCheck = makeNavigate(
+      params.signUpProtectCheckUrl ||
+        buildURL({ base: displayConfig.signUpUrl, hashPath: '/protect-check' }, { stringify: true }),
+    );
+
     const navigateToNextStepSignUp = ({ missingFields }: { missingFields: SignUpField[] }) => {
+      // A protect-gated sign-up always carries 'protect_check' in missing_fields, so this gate
+      // check must run BEFORE the generic missing-fields short-circuit below — otherwise the
+      // OAuth/SAML callback would land on /continue instead of the challenge.
+      if (signUp.protectCheck || missingFields.includes('protect_check')) {
+        return navigateToSignUpProtectCheck();
+      }
+
       if (missingFields.length) {
         return navigateToContinueSignUp();
       }
@@ -2442,6 +2461,9 @@ export class Clerk implements ClerkInterface {
         verifyPhonePath:
           params.verifyPhoneNumberUrl ||
           buildURL({ base: displayConfig.signUpUrl, hashPath: '/verify-phone-number' }, { stringify: true }),
+        protectCheckPath:
+          params.signUpProtectCheckUrl ||
+          buildURL({ base: displayConfig.signUpUrl, hashPath: '/protect-check' }, { stringify: true }),
         navigate,
       });
     };
@@ -2492,12 +2514,36 @@ export class Clerk implements ClerkInterface {
       });
     }
 
+    // OAuth/SAML callbacks can resolve into a protect_check gate that surfaces on the next
+    // /v1/client read, so check for it here before continuing with the transfer logic below.
+    // Honor either the explicit `protectCheck` field or the `needs_protect_check` status override.
+    //
+    // Scope to the callback's intent: an abandoned sign-in keeps serializing its pending
+    // `protect_check` on the client for up to a day (and a later sign-up doesn't clear it in
+    // multi-session mode), so an unscoped check would route a *sign-up* callback into the stale
+    // sign-in's challenge. We only consult `si` here unless this is explicitly a sign-up callback.
+    // Transfers are unaffected: the `signIn.create({ transfer })` path below checks its own fresh
+    // response for the gate.
+    if (params.reloadResource !== 'signUp' && (si.protectCheck || si.status === 'needs_protect_check')) {
+      return navigateToSignInProtectCheck();
+    }
+
+    // The sign-up resource can be gated the same way (e.g. a callback that resolves straight into a
+    // gated sign-up). Scope to the sign-up intent for the symmetric reason — a stale sign-up's gate
+    // shouldn't hijack a sign-in callback.
+    if (params.reloadResource !== 'signIn' && su.protectCheck) {
+      return navigateToSignUpProtectCheck();
+    }
+
     const userExistsButNeedsToSignIn =
       su.externalAccountStatus === 'transferable' &&
       su.externalAccountErrorCode === ERROR_CODES.EXTERNAL_ACCOUNT_EXISTS;
 
     if (userExistsButNeedsToSignIn) {
       const res = await signIn.create({ transfer: true });
+      if (res.protectCheck || res.status === 'needs_protect_check') {
+        return navigateToSignInProtectCheck();
+      }
       switch (res.status) {
         case 'complete':
           return this.setActive({
@@ -2756,6 +2802,8 @@ export class Clerk implements ClerkInterface {
     strategy,
     legalAccepted,
     secondFactorUrl,
+    protectCheckUrl,
+    signUpProtectCheckUrl,
     walletName,
   }: ClerkAuthenticateWithWeb3Params): Promise<void> => {
     if (!this.client || !this.environment) {
@@ -2798,6 +2846,15 @@ export class Clerk implements ClerkInterface {
       secondFactorUrl || buildURL({ base: displayConfig.signInUrl, hashPath: '/factor-two' }, { stringify: true }),
     );
 
+    const navigateToSignInProtectCheck = makeNavigate(
+      protectCheckUrl || buildURL({ base: displayConfig.signInUrl, hashPath: '/protect-check' }, { stringify: true }),
+    );
+
+    const navigateToSignUpProtectCheck = makeNavigate(
+      signUpProtectCheckUrl ||
+        buildURL({ base: displayConfig.signUpUrl, hashPath: '/protect-check' }, { stringify: true }),
+    );
+
     const navigateToContinueSignUp = makeNavigate(
       signUpContinueUrl ||
         buildURL(
@@ -2810,6 +2867,7 @@ export class Clerk implements ClerkInterface {
     );
 
     let signInOrSignUp: SignInResource | SignUpResource;
+    let viaSignUp = false;
     try {
       signInOrSignUp = await this.client.signIn.authenticateWithWeb3({
         identifier,
@@ -2819,6 +2877,7 @@ export class Clerk implements ClerkInterface {
       });
     } catch (err) {
       if (isError(err, ERROR_CODES.FORM_IDENTIFIER_NOT_FOUND)) {
+        viaSignUp = true;
         signInOrSignUp = await this.client.signUp.authenticateWithWeb3({
           identifier,
           generateSignature,
@@ -2831,7 +2890,10 @@ export class Clerk implements ClerkInterface {
         if (
           signUpContinueUrl &&
           signInOrSignUp.status === 'missing_requirements' &&
-          signInOrSignUp.verifications.web3Wallet.status === 'verified'
+          signInOrSignUp.verifications.web3Wallet.status === 'verified' &&
+          // A protect_check gate also surfaces as missing_requirements; don't skip past it into
+          // the continue step. The gate is handled by the sign-up protect-check route instead.
+          !signInOrSignUp.protectCheck
         ) {
           await navigateToContinueSignUp();
         }
@@ -2852,6 +2914,15 @@ export class Clerk implements ClerkInterface {
       });
     };
 
+    // A Clerk Protect challenge can gate the inline web3 attempt (no redirect happens, so the
+    // centralized _handleRedirectCallback check never runs). Route to the challenge before the
+    // status switch below, otherwise the user is stranded on the wallet step. The sign-up fallback
+    // gates as `missing_requirements` + `protectCheck`, so it has no status branch below either.
+    if (signInOrSignUp.protectCheck || signInOrSignUp.status === 'needs_protect_check') {
+      await (viaSignUp ? navigateToSignUpProtectCheck : navigateToSignInProtectCheck)();
+      return;
+    }
+
     switch (signInOrSignUp.status) {
       case 'needs_second_factor':
         await navigateToFactorTwo();