fix(ui): preserve password sign-in after identifier lockout

.changeset/tidy-emails-sign-in.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Allow password sign-in on instances with Enterprise SSO enabled when an unverified email or phone has been locked by code attempts. Reveal the password field after identifier lockout so users can enter their password manually.

packages/backend/src/api/endpoints/UserApi.ts

@@ -20,9 +20,9 @@ const basePath = '/users';
 
 /** @generateWithEmptyComment */
 export type UserCountParams = {
-  /** Counts users with emails that match the given query, via case-insensitive partial match. For example, `emailAddress=hello` will match a user with the email `HELLO@example.com`. Accepts up to 100 email addresses. */
+  /** Counts users with the specified email addresses. When an address has a verified owner, unverified copies on other accounts are excluded. Accepts up to 100 email addresses. */
   emailAddress?: string[];
-  /** Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, `phoneNumber=555` will match a user with the phone number `+1555xxxxxxx`. Accepts up to 100 phone numbers. */
+  /** Counts users with the specified phone numbers. When a number has a verified owner, unverified copies on other accounts are excluded. Accepts up to 100 phone numbers. */
   phoneNumber?: string[];
   /** Counts users with usernames that match the given query, via case-insensitive partial match. For example, `username=CoolUser` will match a user with the username `SomeCoolUser`. Accepts up to 100 usernames. */
   username?: string[];
@@ -38,9 +38,9 @@ export type UserCountParams = {
 
 /** @generateWithEmptyComment */
 export type UserListParams = ClerkPaginationRequest<{
-  /** Filters users with the specified email addresses. Accepts up to 100 email addresses. */
+  /** Filters users with the specified email addresses. When an address has a verified owner, unverified copies on other accounts are excluded. Accepts up to 100 email addresses. */
   emailAddress?: string[];
-  /** Filters users with the specified phone numbers. Accepts up to 100 phone numbers. */
+  /** Filters users with the specified phone numbers. When a number has a verified owner, unverified copies on other accounts are excluded. Accepts up to 100 phone numbers. */
   phoneNumber?: string[];
   /** Filters users with the specified usernames. Accepts up to 100 usernames. */
   username?: string[];
@@ -233,13 +233,13 @@ export type UserPasswordHashingParams = {
 export type CreateUserParams = {
   /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. */
   externalId?: string;
-  /** The email addresses to assign to the user. Each address must be unique across your instance. The first email address becomes the user's primary email address. Addresses are created as verified by default; use `emailAddressIdentificationStatus` to create reserved addresses. */
+  /** The email addresses to assign to the user. Each address must be unique across your instance when creating the user. A reserved address can later coexist with a verified copy on a separate account after its owner proves possession. The first email address becomes the user's primary email address. Addresses are created as verified by default; use `emailAddressIdentificationStatus` to create reserved addresses. */
   emailAddress?: string[];
-  /** Sets the creation status of each email address. Entries correspond by index to `emailAddress`, and the array must contain exactly one entry per email address. If omitted, every email address is created as `'verified'`. Use `'reserved'` to create an unverified address that can still be used for sign-in and cannot be claimed by another user. */
+  /** Sets the creation status of each email address. Entries correspond by index to `emailAddress`, and the array must contain exactly one entry per email address. If omitted, every email address is created as `'verified'`. Use `'reserved'` to create an unverified address that can identify this user for password sign-in when no verified owner exists. It cannot authenticate this user through email verification; a verified owner can claim it on a separate account, where the verified copy coexists with this user's reserved copy. */
   emailAddressIdentificationStatus?: ('verified' | 'reserved')[];
-  /** The phone numbers to assign to the user. Each number must be unique across your instance. The first phone number becomes the user's primary phone number. Numbers are created as verified by default; use `phoneNumberIdentificationStatus` to create reserved numbers. */
+  /** The phone numbers to assign to the user. Each number must be unique across your instance when creating the user. A reserved number can later coexist with a verified copy on a separate account after its owner proves possession. The first phone number becomes the user's primary phone number. Numbers are created as verified by default; use `phoneNumberIdentificationStatus` to create reserved numbers. */
   phoneNumber?: string[];
-  /** Sets the creation status of each phone number. Entries correspond by index to `phoneNumber`, and the array must contain exactly one entry per phone number. If omitted, every phone number is created as `'verified'`. Use `'reserved'` to create an unverified number that can still be used for sign-in and cannot be claimed by another user. */
+  /** Sets the creation status of each phone number. Entries correspond by index to `phoneNumber`, and the array must contain exactly one entry per phone number. If omitted, every phone number is created as `'verified'`. Use `'reserved'` to create an unverified number that can identify this user for password sign-in when no verified owner exists. It cannot authenticate this user through phone verification; a verified owner can claim it on a separate account, where the verified copy coexists with this user's reserved copy. */
   phoneNumberIdentificationStatus?: ('verified' | 'reserved')[];
   /** The username to assign to the user. Must be unique across your instance. */
   username?: string;
@@ -467,7 +467,7 @@ export class UserAPI extends AbstractAPI {
    *
    * Your settings in the [Clerk Dashboard](https://dashboard.clerk.com) determine how you should setup your user model. Anything **Required** will need to be provided when creating a user. Trying to add a field that isn't enabled will result in an error.
    *
-   * By default, email addresses and phone numbers created using this method are verified automatically. Use `emailAddressIdentificationStatus` and `phoneNumberIdentificationStatus` to create any of them as reserved. Reserved identifiers are unverified, but they can still be used for sign-in and cannot be claimed by another user.
+   * By default, email addresses and phone numbers created using this method are verified automatically. Use `emailAddressIdentificationStatus` and `phoneNumberIdentificationStatus` to create any of them as reserved. Reserved identifiers are unverified. They can identify this user for password sign-in only when no verified owner exists, but email or phone verification cannot authenticate this user. A verified owner can claim the contact on a separate account, where the verified copy coexists with this user's reserved copy.
    *
    * > [!CAUTION]
    * >

packages/ui/src/components/SignIn/SignInStart.tsx

@@ -1,4 +1,5 @@
 import { getAlternativePhoneCodeProviderData } from '@clerk/shared/alternativePhoneCode';
+import { isUserLockedError } from '@clerk/shared/error';
 import { inertProps } from '@clerk/shared/inert';
 import { ERROR_CODES, SIGN_UP_MODES } from '@clerk/shared/internal/clerk-js/constants';
 import { clerkInvalidFAPIResponse } from '@clerk/shared/internal/clerk-js/errors';
@@ -140,6 +141,7 @@ function SignInStartInternal(): JSX.Element {
     label: localizationKeys('formFieldLabel__password'),
     placeholder: localizationKeys('formFieldInputPlaceholder__password') as any,
   });
+  const [showInstantPasswordField, setShowInstantPasswordField] = useState(false);
 
   const [alternativePhoneCodeProvider, setAlternativePhoneCodeProvider] = useState<PhoneCodeChannelData | null>(null);
 
@@ -351,19 +353,42 @@ function SignInStartInternal(): JSX.Element {
     signInCreatePromise: Promise<SignInResource>,
     fields: Array<FormControlState<string>>,
   ) => {
-    return signInCreatePromise.then(signInResource => {
-      if (!userSettings.enterpriseSSO.enabled) {
-        return signInResource;
-      }
-      /**
-       * For instances with Enterprise SSO enabled, perform sign in with password only when it is allowed for the identified user.
-       */
-      const passwordField = fields.find(f => f.name === 'password')?.value;
-      if (!passwordField || signInResource.supportedFirstFactors?.some(ff => ff.strategy === 'enterprise_sso')) {
-        return signInResource;
-      }
-      return signInResource.attemptFirstFactor({ strategy: 'password', password: passwordField });
-    });
+    return signInCreatePromise.then(
+      signInResource => {
+        if (!userSettings.enterpriseSSO.enabled) {
+          return signInResource;
+        }
+        /**
+         * For instances with Enterprise SSO enabled, perform sign in with password only when it is allowed for the identified user.
+         */
+        const passwordField = fields.find(f => f.name === 'password')?.value;
+        if (!passwordField || signInResource.supportedFirstFactors?.some(ff => ff.strategy === 'enterprise_sso')) {
+          return signInResource;
+        }
+        return signInResource.attemptFirstFactor({ strategy: 'password', password: passwordField });
+      },
+      error => {
+        const passwordField = fields.find(f => f.name === 'password')?.value;
+        if (!userSettings.enterpriseSSO.enabled || !isUserLockedError(error)) {
+          throw error;
+        }
+        if (!passwordField) {
+          setShowInstantPasswordField(true);
+          throw error;
+        }
+        return signIn
+          .create({
+            identifier: buildRequest(fields).identifier,
+            password: passwordField,
+            strategy: 'password',
+          })
+          .catch(fallbackError => {
+            setShowInstantPasswordField(true);
+            handleError(fallbackError, [identifierField, instantPasswordField], card.setError);
+            throw new Error('password_fallback_failed');
+          });
+      },
+    );
   };
 
   const signInWithFields = async (
@@ -679,6 +704,7 @@ function SignInStartInternal(): JSX.Element {
                       </Form.ControlRow>
                       <InstantPasswordRow
                         field={passwordBasedInstance ? instantPasswordField : undefined}
+                        forceVisible={showInstantPasswordField}
                         onForgotPasswordClick={handleForgotPasswordClick}
                       />
                     </Col>
@@ -740,14 +766,16 @@ function SignInStartInternal(): JSX.Element {
 
 const InstantPasswordRow = ({
   field,
+  forceVisible = false,
   onForgotPasswordClick,
 }: {
   field?: FormControlState<'password'>;
+  forceVisible?: boolean;
   onForgotPasswordClick?: React.MouseEventHandler;
 }) => {
   const [autofilled, setAutofilled] = useState(false);
   const ref = useRef<HTMLInputElement>(null);
-  const show = !!(autofilled || field?.value);
+  const show = !!(forceVisible || autofilled || field?.value);
 
   // show password if it's autofilled by the browser
   useLayoutEffect(() => {