Protect Custom Flows WIP

.changeset/protect-check-modal.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/ui': minor
+'@clerk/shared': patch
+'@clerk/react': patch
+---
+
+Resolve Clerk Protect challenges in custom sign-in and sign-up flows. When a request returns a `protect_check`, clerk-js opens Clerk's Protect UI in a modal over the page, runs the challenge, submits the proof, and then lets the original call return. Nothing needs to be rendered by the application. The prebuilt `<SignIn />` and `<SignUp />` components keep handling challenges inside their own cards.

integration/tests/protect-check.test.ts

@@ -12,6 +12,13 @@ const waitForProtectCheckSubmit = (page: Page) =>
     { timeout: 30_000 },
   );
 
+const protectCheckModalSelector = '.cl-modalContent:has(.cl-protectCheck-root)';
+
+const waitForProtectCheckModal = (page: Page) =>
+  page.waitForFunction(selector => !!document.querySelector(selector), protectCheckModalSelector, {
+    timeout: 30_000,
+  });
+
 test.describe('protect check @generic', () => {
   test.describe.configure({ mode: 'serial' });
 
@@ -41,8 +48,10 @@ test.describe('protect check @generic', () => {
     const protectCheckSubmit = waitForProtectCheckSubmit(page);
 
     await u.po.signUp.goTo();
+    const protectCheckRoute = page.waitForURL(/protect-check/, { timeout: 30_000 });
     await u.po.signUp.signUpWithEmailAndPassword({ email: fakeUser.email!, password: fakeUser.password });
 
+    await protectCheckRoute;
     expect((await protectCheckSubmit).ok()).toBe(true);
     await u.po.signUp.enterTestOtpCode();
     await u.po.expect.toBeSignedIn();
@@ -55,14 +64,86 @@ test.describe('protect check @generic', () => {
     const protectCheckSubmit = waitForProtectCheckSubmit(page);
 
     await u.po.signIn.goTo();
+    const protectCheckRoute = page.waitForURL(/protect-check/, { timeout: 30_000 });
     await u.po.signIn.signInWithEmailAndInstantPassword({
       email: fakeUser.email!,
       password: fakeUser.password,
       waitForSession: false,
     });
 
+    await protectCheckRoute;
     expect((await protectCheckSubmit).ok()).toBe(true);
     await u.po.signIn.enterTestOtpCode();
     await u.po.expect.toBeSignedIn();
   });
 });
+
+test.describe('protect check in custom flows @custom', () => {
+  test.describe.configure({ mode: 'serial' });
+
+  let app: Application;
+  let fakeUser: FakeUser | undefined;
+
+  test.beforeAll(async () => {
+    test.setTimeout(150_000);
+    app = await appConfigs.customFlows.reactVite.clone().commit();
+    await app.setup();
+    await app.withEnv(appConfigs.envs.withProtectService);
+    await app.dev();
+  });
+
+  test.afterEach(async () => {
+    await fakeUser?.deleteIfExists();
+    fakeUser = undefined;
+  });
+
+  test.afterAll(async () => {
+    await app.teardown();
+  });
+
+  test('shows the Protect modal on sign-up', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    fakeUser = u.services.users.createFakeUser(test);
+    const protectCheckSubmit = waitForProtectCheckSubmit(page);
+    const prepareVerification = page.waitForResponse(
+      response => response.request().method() === 'POST' && response.url().includes('prepare_verification'),
+      { timeout: 30_000 },
+    );
+
+    await u.page.goToRelative('/sign-up');
+    await expect(u.page.getByText('Sign up', { exact: true })).toBeVisible();
+    const protectCheckModal = waitForProtectCheckModal(page);
+    await u.po.signUp.signUp({ email: fakeUser.email!, password: fakeUser.password });
+
+    expect((await protectCheckSubmit).ok()).toBe(true);
+    await protectCheckModal;
+    await page.locator(protectCheckModalSelector).waitFor({ state: 'detached' });
+    await prepareVerification;
+    await u.page.getByRole('textbox', { name: 'code' }).fill('424242');
+    await u.po.signUp.continue();
+    await u.page.waitForURL(/protected/);
+    await u.po.expect.toBeSignedIn();
+  });
+
+  test('shows the Protect modal on sign-in', async ({ page, context }) => {
+    const u = createTestUtils({ app, page, context });
+    fakeUser = u.services.users.createFakeUser(test);
+    await u.services.users.createBapiUser(fakeUser);
+    const protectCheckSubmit = waitForProtectCheckSubmit(page);
+
+    await u.page.goToRelative('/sign-in');
+    await expect(u.page.getByText('Sign in', { exact: true })).toBeVisible();
+    const protectCheckModal = waitForProtectCheckModal(page);
+    await u.po.signIn.setIdentifier(fakeUser.email!);
+    await u.po.signIn.continue();
+
+    expect((await protectCheckSubmit).ok()).toBe(true);
+    await protectCheckModal;
+    await page.locator(protectCheckModalSelector).waitFor({ state: 'detached' });
+    await u.page.getByRole('button', { name: 'email_code', exact: true }).click();
+    await u.page.getByRole('textbox', { name: 'code' }).fill('424242');
+    await u.po.signIn.continue();
+    await u.page.waitForURL(/protected/);
+    await u.po.expect.toBeSignedIn();
+  });
+});

packages/clerk-js/bundlewatch.config.json

@@ -4,7 +4,7 @@
     { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "124.5KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "322.25KB" },
-    { "path": "./dist/clerk.native.js", "maxSize": "80KB" },
+    { "path": "./dist/clerk.native.js", "maxSize": "82KB" },
     { "path": "./dist/vendors*.js", "maxSize": "7KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "36KB" },
     { "path": "./dist/base-account-sdk*.js", "maxSize": "207KB" },

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

@@ -18,6 +18,7 @@ import { restoreDocument, setDocumentVisibilityState } from '@/test/document-hel
 import { mockNativeRuntime } from '../../test/utils';
 import { Clerk } from '../clerk';
 import { eventBus, events } from '../events';
+import { ProtectCheckGate } from '../protectCheckGate';
 import type { DisplayConfig, Organization } from '../resources/internal';
 import { BaseResource, Client, Environment, SignIn, SignUp } from '../resources/internal';
 
@@ -3186,6 +3187,49 @@ describe('Clerk singleton', () => {
         expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/protect-check');
       });
     });
+
+    it('owns both Protect flows while it routes a callback', async () => {
+      const release = vi.fn();
+      const register = vi.spyOn(ProtectCheckGate.prototype, 'register').mockReturnValue(release);
+      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(null), signUp: new SignUp(null) }),
+      );
+
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+      await sut.handleRedirectCallback();
+
+      expect(register).toHaveBeenCalledWith(['signIn', 'signUp']);
+      expect(release).toHaveBeenCalledTimes(1);
+      register.mockRestore();
+    });
+
+    it('releases its Protect claim when routing a callback throws', async () => {
+      const release = vi.fn();
+      const register = vi.spyOn(ProtectCheckGate.prototype, 'register').mockReturnValue(release);
+      mockEnvironmentFetch.mockReturnValue(Promise.resolve({ authConfig: {}, userSettings: mockUserSettings }));
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({ signedInSessions: [], signIn: new SignIn(null), signUp: new SignUp(null) }),
+      );
+
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+      await expect(sut.handleRedirectCallback()).rejects.toThrow();
+
+      expect(release).toHaveBeenCalledTimes(1);
+      register.mockRestore();
+    });
   });
 
   describe('.handleEmailLinkVerification()', () => {
@@ -4005,6 +4049,118 @@ describe('Clerk singleton', () => {
     });
   });
 
+  describe('protect check modal', () => {
+    beforeEach(() => {
+      mockEnvironmentFetch.mockReturnValue(
+        Promise.resolve({
+          userSettings: mockUserSettings,
+          displayConfig: mockDisplayConfig,
+          isSingleSession: () => false,
+          isProduction: () => true,
+          isDevelopmentOrStaging: () => false,
+        }),
+      );
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          signedInSessions: [],
+        }),
+      );
+    });
+
+    const gatedSignIn = () => ({
+      protectCheck: { status: 'pending', token: 'tok', sdkUrl: 'https://p.example.com/sdk.js' },
+    });
+
+    it('resolves at once when Clerk was loaded without UI components', async () => {
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+
+      await expect(sut.__internal_openProtectCheckModal({ resource: gatedSignIn() as any })).resolves.toBeUndefined();
+    });
+
+    it('resolves at once and leaves the gate when the UI predates the Protect modal', async () => {
+      const openModal = vi.fn();
+      const mockClerkUICtor = vi.fn(function () {
+        return { ensureMounted: () => Promise.resolve({ openModal, closeModal: vi.fn() }) };
+      });
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load({ ...mockedLoadOptions, ui: { ClerkUI: mockClerkUICtor } });
+      const resource = gatedSignIn() as any;
+
+      await expect(sut.__internal_openProtectCheckModal({ resource })).resolves.toBeUndefined();
+      expect(openModal).not.toHaveBeenCalled();
+      expect(resource.protectCheck).not.toBeNull();
+    });
+
+    it('opens the modal and resolves once the modal reports the gate cleared', async () => {
+      const openProtectCheckModal = vi.fn();
+      const closeModal = vi.fn();
+      const mockClerkUICtor = vi.fn(function () {
+        return { ensureMounted: () => Promise.resolve({ openProtectCheckModal, closeModal }) };
+      });
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load({ ...mockedLoadOptions, ui: { ClerkUI: mockClerkUICtor } });
+      const resource = gatedSignIn() as any;
+
+      let settled = false;
+      const pending = sut.__internal_openProtectCheckModal({ resource }).then(() => {
+        settled = true;
+      });
+      await vi.waitFor(() => expect(openProtectCheckModal).toHaveBeenCalled());
+      expect(openProtectCheckModal).toHaveBeenCalledWith({
+        resource,
+        onResolved: expect.any(Function),
+        onFailed: expect.any(Function),
+      });
+      expect(settled).toBe(false);
+
+      openProtectCheckModal.mock.calls[0][0].onResolved();
+      await pending;
+      expect(closeModal).toHaveBeenCalledWith('protectCheck');
+      expect(settled).toBe(true);
+    });
+
+    it('closes the modal and rejects with the error the modal reports', async () => {
+      const openProtectCheckModal = vi.fn();
+      const closeModal = vi.fn();
+      const mockClerkUICtor = vi.fn(function () {
+        return { ensureMounted: () => Promise.resolve({ openProtectCheckModal, closeModal }) };
+      });
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load({ ...mockedLoadOptions, ui: { ClerkUI: mockClerkUICtor } });
+      const blocked = new Error('blocked');
+
+      const pending = sut.__internal_openProtectCheckModal({ resource: gatedSignIn() as any });
+      await vi.waitFor(() => expect(openProtectCheckModal).toHaveBeenCalled());
+      openProtectCheckModal.mock.calls[0][0].onFailed(blocked);
+
+      await expect(pending).rejects.toBe(blocked);
+      expect(closeModal).toHaveBeenCalledWith('protectCheck');
+    });
+
+    it('resolves gates the client carries on its sign-in and sign-up', async () => {
+      const resolve = vi.spyOn(ProtectCheckGate.prototype, 'resolve').mockResolvedValue(undefined);
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load(mockedLoadOptions);
+
+      await sut.__internal_resolvePendingProtectCheck();
+
+      expect(resolve).toHaveBeenCalledWith(sut, 'signIn', sut.client?.signIn);
+      expect(resolve).toHaveBeenCalledWith(sut, 'signUp', sut.client?.signUp);
+      resolve.mockRestore();
+    });
+
+    it('registers prebuilt handlers with the gate', () => {
+      const release = vi.fn();
+      const register = vi.spyOn(ProtectCheckGate.prototype, 'register').mockReturnValue(release);
+      const sut = new Clerk(productionPublishableKey);
+
+      expect(sut.__internal_registerProtectCheckHandler(['signUp'])).toBe(release);
+      expect(register).toHaveBeenCalledWith(['signUp']);
+      register.mockRestore();
+    });
+  });
+
   describe('ui.ClerkUI option', () => {
     beforeEach(() => {
       mockEnvironmentFetch.mockReturnValue(

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

@@ -62,6 +62,7 @@ import type {
   __internal_EnableOrganizationsPromptProps,
   __internal_OAuthConsentProps,
   __internal_PlanDetailsProps,
+  __internal_ProtectCheckModalProps,
   __internal_SubscriptionDetailsProps,
   __internal_UserVerificationModalProps,
   APIKeysNamespace,
@@ -108,6 +109,7 @@ import type {
   OrganizationSwitcherProps,
   PricingTableProps,
   ProtectAssertion,
+  ProtectCheckFlow,
   PublicKeyCredentialCreationOptionsWithoutExtensions,
   PublicKeyCredentialRequestOptionsWithoutExtensions,
   PublicKeyCredentialWithAuthenticatorAssertionResponse,
@@ -195,6 +197,7 @@ import { createCheckoutInstance } from './modules/checkout/instance';
 import { OAuthApplication } from './modules/oauthApplication';
 import { Protect } from './protect';
 import { protectAssertionParams } from './protectAssertion';
+import { ProtectCheckGate } from './protectCheckGate';
 import { BaseResource, Client, Environment, Organization, Waitlist } from './resources/internal';
 import { State } from './state';
 
@@ -991,6 +994,47 @@ export class Clerk implements ClerkInterface {
       .then(controls => controls.closeModal('enableOrganizationsPrompt'));
   };
 
+  public __internal_registerProtectCheckHandler = (flows: ProtectCheckFlow[]): (() => void) => {
+    return ProtectCheckGate.getInstance().register(flows);
+  };
+
+  public __internal_resolvePendingProtectCheck = async (): Promise<void> => {
+    if (!this.client) {
+      return;
+    }
+    const gate = ProtectCheckGate.getInstance();
+    await gate.resolve(this, 'signIn', this.client.signIn);
+    await gate.resolve(this, 'signUp', this.client.signUp);
+  };
+
+  public __internal_openProtectCheckModal = (
+    props: Pick<__internal_ProtectCheckModalProps, 'resource'>,
+  ): Promise<void> => {
+    if (!this.#clerkUI) {
+      return Promise.resolve();
+    }
+    return this.#clerkUI
+      .then(ui => ui.ensureMounted())
+      .then(controls => {
+        if (!controls.openProtectCheckModal) {
+          return;
+        }
+        return new Promise<void>((resolve, reject) => {
+          controls.openProtectCheckModal?.({
+            ...props,
+            onResolved: () => {
+              controls.closeModal('protectCheck');
+              resolve();
+            },
+            onFailed: error => {
+              controls.closeModal('protectCheck');
+              reject(error);
+            },
+          });
+        });
+      });
+  };
+
   public __internal_openBlankCaptchaModal = (): Promise<unknown> => {
     this.assertComponentsReady(this.#clerkUI);
     return this.#clerkUI.then(ui => ui.ensureMounted()).then(controls => controls.openModal('blankCaptcha', {}));
@@ -2569,7 +2613,16 @@ export class Clerk implements ClerkInterface {
     return this.__internal_handleResourceCallback(signInOrUp, params, customNavigate);
   };
 
-  private _handleRedirectCallback = async (
+  private _handleRedirectCallback = async (...args: Parameters<Clerk['_routeRedirectCallback']>): Promise<unknown> => {
+    const release = ProtectCheckGate.getInstance().register(['signIn', 'signUp']);
+    try {
+      return await this._routeRedirectCallback(...args);
+    } finally {
+      release();
+    }
+  };
+
+  private _routeRedirectCallback = async (
     params: ResumeAfterProtectCheckParams,
     {
       signIn,