feat(js,ui,localizations): limit password confirmation attempts per session

.changeset/password-confirmation-attempts.md

@@ -0,0 +1,12 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/localizations': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Show how many password attempts remain when a user enters the wrong current password while changing their password or during reverification, and explain that the session has ended once the attempts run out.
+
+- `ClerkAPIError.meta.remainingAttempts` holds the attempts left in the current session. `0` means the session has ended, and Clerk signs the user out of the current tab and notifies other tabs.
+- Customize the messages with the `unstable__errors.password_confirmation_attempt_remaining`, `unstable__errors.password_confirmation_attempts_remaining` (receives `{{remainingAttempts}}`), and `unstable__errors.password_confirmation_session_ended` localization keys.
+- After the attempt limit signs a user out, the next prebuilt sign-in form explains why their session ended, including after a page reload.

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "556KB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "83KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "126KB" },
+    { "path": "./dist/clerk.js", "maxSize": "558KB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "85KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "128KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "324KB" },
-    { "path": "./dist/clerk.native.js", "maxSize": "82.5KB" },
+    { "path": "./dist/clerk.native.js", "maxSize": "83KB" },
     { "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

@@ -5,6 +5,14 @@ import {
   EmailLinkErrorCodeStatus,
 } from '@clerk/shared/error';
 import { ERROR_CODES } from '@clerk/shared/internal/clerk-js/constants';
+import {
+  PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY,
+  SafeLocalStorage,
+} from '@clerk/shared/internal/clerk-js/localStorage';
+import {
+  PASSWORD_CONFIRMATION_NOTICE_TTL,
+  PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM,
+} from '@clerk/shared/internal/clerk-js/passwordConfirmation';
 import type {
   ActiveSessionResource,
   PendingSessionResource,
@@ -4391,6 +4399,141 @@ describe('Clerk singleton', () => {
     });
   });
 
+  describe('password confirmation sign-in redirects', () => {
+    beforeEach(() => window.localStorage.clear());
+    afterEach(() => window.localStorage.clear());
+
+    it('carries the notice to hosted sign-in and removes the source marker when redirecting', async () => {
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load({
+        signInUrl: 'https://accounts.example.com/sign-in?existing=value#/start',
+        allowedRedirectOrigins: ['https://app.example.com'],
+      });
+      const key = `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${sut.publishableKey}`;
+      const notice = `${sut.publishableKey}:${Date.now()}`;
+      SafeLocalStorage.setItem(key, notice, PASSWORD_CONFIRMATION_NOTICE_TTL);
+      const url = new URL(sut.buildSignInUrl({ redirectUrl: 'https://app.example.com/account' }));
+      expect(url.origin).toBe('https://accounts.example.com');
+      expect(url.searchParams.get(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM)).toBe(notice);
+      expect(url.searchParams.get('existing')).toBe('value');
+      expect(url.hash).toContain('/start');
+      expect(url.href).toContain(encodeURIComponent('https://app.example.com/account'));
+      expect(SafeLocalStorage.getItem(key, null)).toBe(notice);
+      const navigate = vi.spyOn(sut, 'navigate').mockResolvedValue(undefined);
+      await sut.redirectToSignIn({ redirectUrl: 'https://app.example.com/account' });
+      expect(navigate).toHaveBeenCalledWith(url.href);
+      expect(SafeLocalStorage.getItem(key, null)).toBeNull();
+      navigate.mockRestore();
+    });
+
+    it.each(['initialization', 'activation'])(
+      'does not replay a direct-builder notice after session %s',
+      async mode => {
+        const sut = new Clerk(productionPublishableKey);
+        const options = { signInUrl: 'https://accounts.example.com/sign-in' };
+        await sut.load(options);
+        const key = `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${sut.publishableKey}`;
+        const otherKey = `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:another_instance`;
+        const notice = `${sut.publishableKey}:${Date.now()}`;
+        SafeLocalStorage.setItem(key, notice, PASSWORD_CONFIRMATION_NOTICE_TTL);
+        SafeLocalStorage.setItem(otherKey, 'other-notice', PASSWORD_CONFIRMATION_NOTICE_TTL);
+
+        expect(new URL(sut.buildSignInUrl()).searchParams.get(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM)).toBe(notice);
+        expect(SafeLocalStorage.getItem(key, null)).toBe(notice);
+
+        const session = {
+          id: 'session_new',
+          status: 'active',
+          user: { id: 'user_1' },
+          touch: vi.fn().mockResolvedValue(undefined),
+          getToken: vi.fn().mockResolvedValue('token_new'),
+          lastActiveToken: { getRawString: () => 'token_new' },
+        };
+        const client = { sessions: [session], signedInSessions: [session], lastActiveSessionId: session.id };
+        let returningClerk = sut;
+        if (mode === 'initialization') {
+          mockClientFetch.mockResolvedValue(client);
+          returningClerk = new Clerk(productionPublishableKey);
+          await returningClerk.load(options);
+        } else {
+          sut.updateClient(client as any);
+          expect(SafeLocalStorage.getItem(key, null)).toBe(notice);
+          await sut.setActive({ session: session.id });
+        }
+
+        expect(returningClerk.session?.id).toBe(session.id);
+        expect(SafeLocalStorage.getItem(key, null)).toBeNull();
+        expect(SafeLocalStorage.getItem(otherKey, null)).toBe('other-notice');
+        await returningClerk.setActive({ session: null });
+        expect(
+          new URL(returningClerk.buildSignInUrl()).searchParams.has(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM),
+        ).toBe(false);
+      },
+    );
+
+    it.each(['expired', 'other-instance', 'missing'])('does not forward a %s notice', async kind => {
+      const sut = new Clerk(productionPublishableKey);
+      await sut.load({ signInUrl: 'https://accounts.example.com/sign-in' });
+      const key = `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${sut.publishableKey}`;
+      if (kind !== 'missing') {
+        const notice =
+          kind === 'expired'
+            ? `${sut.publishableKey}:${Date.now() - PASSWORD_CONFIRMATION_NOTICE_TTL}`
+            : `another_instance:${Date.now()}`;
+        SafeLocalStorage.setItem(key, notice, PASSWORD_CONFIRMATION_NOTICE_TTL);
+      }
+      expect(new URL(sut.buildSignInUrl()).searchParams.has(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM)).toBe(false);
+    });
+  });
+
+  describe('__internal_handleSessionEnded', () => {
+    afterEach(() => {
+      (window as any).__internal_onAfterSetActive = null;
+    });
+
+    it.each([false, true])(
+      'preserves the notice and signs out when the response retains the active session: %s',
+      async retainsSession => {
+        const mockOnAfterSetActive = vi.fn().mockReturnValue(Promise.resolve());
+        (window as any).__internal_onAfterSetActive = mockOnAfterSetActive;
+        const eventBusSpy = vi.spyOn(eventBus, 'emit');
+        const mockSession = {
+          id: 'session_1',
+          status: 'active',
+          user: { id: 'user_1' },
+          lastActiveToken: { getRawString: () => 'token_1' },
+        };
+
+        const sut = new Clerk(productionPublishableKey);
+        sut.updateClient({ sessions: [mockSession], signedInSessions: [mockSession] } as any);
+        const key = `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${sut.publishableKey}`;
+        const updateClient = sut.updateClient;
+        const updateClientSpy = vi.spyOn(sut, 'updateClient').mockImplementation(client => {
+          expect(SafeLocalStorage.getItem(key, null)).toMatch(new RegExp(`^${sut.publishableKey}:\\d+$`));
+          updateClient(client);
+        });
+
+        await sut.__internal_handleSessionEnded({
+          sessions: retainsSession ? [mockSession] : [],
+          signedInSessions: retainsSession ? [mockSession] : [],
+        } as any);
+
+        expect(updateClientSpy).toHaveBeenCalledTimes(1);
+        expect(SafeLocalStorage.getItem(key, null)).toMatch(new RegExp(`^${sut.publishableKey}:\\d+$`));
+        const now = Date.now();
+        const nowSpy = vi.spyOn(Date, 'now').mockReturnValue(now + 5 * 60 * 1000 + 1);
+        expect(SafeLocalStorage.getItem(key, false)).toBe(false);
+        nowSpy.mockRestore();
+        updateClientSpy.mockRestore();
+
+        expect(sut.session).toBeNull();
+        expect(eventBusSpy).toHaveBeenCalledWith(events.UserSignOut, null);
+        expect(mockOnAfterSetActive).toHaveBeenCalled();
+        eventBusSpy.mockRestore();
+      },
+    );
+  });
+
   describe('__internal_attemptToEnableEnvironmentSetting', () => {
     afterEach(() => {
       mockEnvironmentFetch.mockReset();

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

@@ -31,6 +31,16 @@ import {
   ERROR_CODES,
 } from '@clerk/shared/internal/clerk-js/constants';
 import { hasMultipleEnterpriseConnections } from '@clerk/shared/internal/clerk-js/enterpriseSSOFactors';
+import {
+  CLERK_ENVIRONMENT_STORAGE_ENTRY,
+  PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY,
+  SafeLocalStorage,
+} from '@clerk/shared/internal/clerk-js/localStorage';
+import {
+  isPasswordConfirmationNotice,
+  PASSWORD_CONFIRMATION_NOTICE_TTL,
+  PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM,
+} from '@clerk/shared/internal/clerk-js/passwordConfirmation';
 import { RedirectUrls } from '@clerk/shared/internal/clerk-js/redirectUrls';
 import {
   getTaskEndpoint,
@@ -174,7 +184,6 @@ import {
   stripOrigin,
   web3,
 } from '../utils';
-import { CLERK_ENVIRONMENT_STORAGE_ENTRY, SafeLocalStorage } from '../utils/localStorage';
 import { memoizeListenerCallback } from '../utils/memoizeStateListenerCallback';
 import { AuthCookieService } from './auth/AuthCookieService';
 import { CaptchaHeartbeat } from './auth/CaptchaHeartbeat';
@@ -2271,7 +2280,17 @@ export class Clerk implements ClerkInterface {
 
     const modifiedOptions = this.isSatellite ? this.#addSyncTriggerToRedirectOptions(options) : options;
 
-    return this.#buildUrl('signInUrl', { ...modifiedOptions, redirectUrl }, options?.initialValues);
+    const signInUrl = this.#buildUrl('signInUrl', { ...modifiedOptions, redirectUrl }, options?.initialValues);
+    const notice = SafeLocalStorage.getItem(
+      `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${this.publishableKey}`,
+      null,
+    );
+    if (!signInUrl || !isPasswordConfirmationNotice(notice, this.publishableKey)) {
+      return signInUrl;
+    }
+    const url = new URL(signInUrl, window.location.href);
+    url.searchParams.set(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM, notice);
+    return url.href;
   }
 
   public buildSignUpUrl(options?: SignUpRedirectOptions): string {
@@ -2467,7 +2486,11 @@ export class Clerk implements ClerkInterface {
 
   public redirectToSignIn = async (options?: SignInRedirectOptions): Promise<unknown> => {
     if (inBrowser()) {
-      return this.navigate(this.buildSignInUrl(options));
+      const url = this.buildSignInUrl(options);
+      if (url && new URL(url, window.location.href).searchParams.has(PASSWORD_CONFIRMATION_SESSION_ENDED_PARAM)) {
+        SafeLocalStorage.removeItem(`${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${this.publishableKey}`);
+      }
+      return this.navigate(url);
     }
     return;
   };
@@ -3016,10 +3039,7 @@ export class Clerk implements ClerkInterface {
       if (this.session) {
         return;
       }
-      if (opts.broadcast) {
-        eventBus.emit(events.UserSignOut, null);
-      }
-      return this.setActive({ session: null });
+      return this.#completeSignOut(opts);
     } catch (err) {
       // `/client` can fail with either a 401, a 403, 500 or network errors.
       // 401 is already handled internally in our fetcher.
@@ -3033,6 +3053,31 @@ export class Clerk implements ClerkInterface {
     }
   };
 
+  /**
+   * Completes a sign-out that FAPI already performed, such as when a failed password
+   * confirmation ended the session and the piggybacked client no longer contains it.
+   *
+   * @internal
+   */
+  public __internal_handleSessionEnded = (client?: ClientResource): Promise<void> => {
+    SafeLocalStorage.setItem(
+      `${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${this.publishableKey}`,
+      `${this.publishableKey}:${Date.now()}`,
+      PASSWORD_CONFIRMATION_NOTICE_TTL,
+    );
+    if (client) {
+      this.updateClient(client);
+    }
+    return this.#completeSignOut({ broadcast: true });
+  };
+
+  #completeSignOut = (opts: { broadcast: boolean }): Promise<void> => {
+    if (opts.broadcast) {
+      eventBus.emit(events.UserSignOut, null);
+    }
+    return this.setActive({ session: null });
+  };
+
   public __internal_handleUnauthenticatedDevBrowser = async (): Promise<void> => {
     if (this.#authService) {
       await this.#authService.handleUnauthenticatedDevBrowser();
@@ -3840,6 +3885,10 @@ export class Clerk implements ClerkInterface {
   #updateAccessors = (session?: SignedInSessionResource | null, options?: { dangerouslySkipEmit?: boolean }) => {
     const { session: newSession, organization, user } = this.#getAccessorsFromSession(session);
 
+    if (newSession?.status === 'active' && (this.session?.id !== newSession.id || this.session?.status !== 'active')) {
+      SafeLocalStorage.removeItem(`${PASSWORD_CONFIRMATION_ERROR_STORAGE_ENTRY}:${this.publishableKey}`);
+    }
+
     this.session = newSession;
     this.organization = organization;
     this.user = user;

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

@@ -1,5 +1,6 @@
 import { isValidBrowserOnline } from '@clerk/shared/browser';
 import { ClerkAPIResponseError, ClerkRuntimeError } from '@clerk/shared/error';
+import { isPasswordConfirmationError } from '@clerk/shared/internal/clerk-js/passwordConfirmation';
 import { isProductionFromPublishableKey } from '@clerk/shared/keys';
 import type {
   ClerkAPIErrorJSON,
@@ -128,15 +129,20 @@ export abstract class BaseResource {
     }
 
     const { payload, status, statusText, headers } = fapiResponse;
-
+    const errors = payload?.errors ?? [];
     if (headers) {
       const country = headers.get('x-country');
 
       this.clerk.__internal_setCountry(country ? country.toLowerCase() : null);
     }
 
     // TODO: Link to Client payload piggybacking design document
-    if ((requestInit.method !== 'GET' || opts.forceUpdateClient) && !opts.skipUpdateClient) {
+    const shouldUpdateClient = (requestInit.method !== 'GET' || opts.forceUpdateClient) && !opts.skipUpdateClient;
+    if (status === 422 && isPasswordConfirmationError(errors[0]) && errors[0]?.meta?.remaining_attempts === 0) {
+      await BaseResource.clerk.__internal_handleSessionEnded(
+        shouldUpdateClient ? getClientResourceFromPayload(payload) : undefined,
+      );
+    } else if (shouldUpdateClient) {
       this._updateClient<J>(payload);
     }
 
@@ -145,9 +151,8 @@ export abstract class BaseResource {
     }
 
     if (status >= 400) {
-      const errors = payload?.errors as ClerkAPIErrorJSON[];
-      const message = errors?.[0]?.long_message;
-      const code = errors?.[0]?.code;
+      const message = errors[0]?.long_message;
+      const code = errors[0]?.code;
 
       // Handle 401 errors based on the specific error code:
       // - dev_browser_unauthenticated: reset the dev browser token