@vvedantb/native-ui 0.9.0 → 0.10.0

package/README.md

@@ -80,7 +80,7 @@ The root entry exports everything. It still imports `BottomSheetContainer` and `
 | `@vvedantb/native-ui/date-time` | `DateTimeField`, `DateTimeFieldProps` (0.5.0) | `@react-native-community/datetimepicker`, `dayjs` (import) |
 | `@vvedantb/native-ui/ai` | The AI chat parts (from 0.4.0): `Conversation`, `Message`, `Reasoning`, `AgentTrace`, `ChainOfThought`, `ActivityStep`, `PromptInput`, `Suggestions`, `Sources`, `FileChip`, `Attachments`, `CodeBlock`, `ResponseText`, `Shimmer`, `Collapsible`, `useStreamingDisclosure` and their parts. See [AI chat](#ai-chat-040). Not on the root entry. | none |
 | `@vvedantb/native-ui/ai-gallery` | `AiChatGallery`, `AiChatSamples` (from 0.4.0) | none |
-| `@vvedantb/native-ui/auth` | From 0.7.0: `AuthProviders`, `SignInScreen`, `SignUpScreen`, `GoogleSignInButton`, `useGoogleSignIn`, `AuthScreen`, `OrDivider`, `FieldError`, `authErrorMessage` and their props types. See [Auth](#auth-070). Not on the root entry. | `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser`, `expo-router` (import) |
+| `@vvedantb/native-ui/auth` | From 0.7.0: `AuthProviders`, `SignInScreen`, `SignUpScreen`, `GoogleSignInButton`, `useGoogleSignIn`, `AuthScreen`, `OrDivider`, `FieldError`, `authErrorMessage`, `SecondFactorScreen`, `useSecondFactor`, `submitTotpSecondFactor`, `submitSecondFactor`, `prepareSecondFactorIfNeeded`, `TOTP_MESSAGES` and their props types. See [Auth](#auth-070). Not on the root entry. | `@clerk/clerk-expo`, `convex`, `expo-auth-session`, `expo-web-browser`, `expo-router` (import) |
 | `@vvedantb/native-ui/expo-web-root` | From 0.7.0: `ExpoWebRoot`, `ExpoWebRootProps`, `ExpoWebRootViewport`, `EXPO_WEB_VIEWPORT`, `expoWebBackgroundCss`. Not on the root entry. | `expo-router` (import of `expo-router/html`) |
 | `@vvedantb/native-ui/tailwind-preset` | From 0.7.0, CommonJS for `tailwind.config.js`: `nativeUiPreset`, `nativeUiContent`, `cssVar`, `hslVar`, `rgbAlpha`, `cssVariables`, `schemeColors` and a default preset. See [Expo / NativeWind](#expo--nativewind). | `nativewind` (`require`, when installed) |
 
@@ -211,10 +211,52 @@ export default function SignUp() {
 - `title`, `subtitle`, `showGoogle`, `googleLabel`, `errorDisplay` (`"toast"`, default, needs a `<Toaster />`; or `"inline"`), `testIDPrefix` (default the mode: `sign-in-email`, `sign-in-password`, `sign-in-submit`, `sign-in-google` and the rest).
 - `header` and `footer` slots for app chrome, such as a brand header or credit. The screen itself is neutral: background fill, title, subtitle, fields.
 - Messages are generic ("Sign in failed", "Invalid email or password", "Could not continue with Google") and never name the auth provider. `authErrorMessage(error, fallback)` shows an API error's own text only when it does not name it.
+- Two-step verification: when sign-in returns `needs_second_factor` or `needs_client_trust`, the screen shows `SecondFactorScreen` with the account's default method: authenticator app (`totp`), then `email_code`, `phone_code`, `backup_code`. Email and text codes are sent first. A "Use a backup code" link (and a link back) switches method. A valid code runs the same success path. Back returns to the email and password form.
+- `needs_new_password` shows a new-password step (`signIn.resetPassword`), then starts the session.
+- `onIncomplete(signIn)`: optional. Called only for statuses the built-in UI cannot finish: `needs_identifier`, `needs_first_factor`, unknown statuses, and `needs_second_factor` or `needs_client_trust` when no supported strategy (totp, backup code, phone code, email code) exists. The built-in screen always runs `needs_second_factor`, `needs_client_trust` and `needs_new_password`. When `onIncomplete` is called, the screen shows no message. Without it, those statuses show "This account needs another step to sign in. Finish it on the web." and log the status and strategy ids with `console.warn`. Ignored in `sign-up`.
+- Keyboard: `AuthScreen` (and so every screen here) pads for the soft keyboard on iOS and Android, including edge-to-edge Android, and scrolls the focused field and the button above it.
 - No forgot-password step. An app that needs one keeps its own screen.
 
 `GoogleSignInButton` (`scheme`, `redirectPath`, `afterAuthHref`, `replaceOptions`, `onSuccess`, `onError`, `label` and the `Button` props), `AuthScreen`, `OrDivider` and `FieldError` build custom screens. The module calls `WebBrowser.maybeCompleteAuthSession()` once when it loads, so the app no longer needs its own call.
 
+### Second factor (0.10.0)
+
+`SecondFactorScreen` is a one-time code step with no Clerk import. The caller owns the check.
+
+| Prop | Default | Use |
+| --- | --- | --- |
+| `title` | required | Screen title, through `AuthScreen` |
+| `description` | none | Text under the title |
+| `codeLength` | `6` | Digits in the code |
+| `onSubmit(code)` | required | Called with the full code |
+| `error` | none | Inline error under the field |
+| `loading` | `false` | Verify spinner; blocks a second submit |
+| `onBack` | none | Shows a ghost Back button |
+| `backLabel` | `"Back"` | Back button text |
+| `header` | none | Above the title |
+| `testIDPrefix` | `"second-factor"` | `-screen`, `-code`, `-error`, `-verify`, `-back` |
+| `footer` | none | Below the buttons, such as a "Use a backup code" switch |
+| `digitsOnly` | `true` | `false` takes any characters (backup codes) |
+| `placeholder` | `"Code"` | Field placeholder when `digitsOnly` is `false` |
+
+For Clerk, `useSecondFactor({ strategy? })` (default `"totp"`) returns `{ submit(code), prepare(strategy?, factor?), strategy, setStrategy, loading, error, clearError }`. `submit` calls `signIn.attemptSecondFactor({ strategy, code })`, then `setActive({ session: createdSessionId })`. `submit` never throws: it resolves `{ ok: true }` or `{ ok: false, error }`.
+
+```tsx
+const { submit, loading, error } = useSecondFactor();
+
+<SecondFactorScreen
+  title="Two-step verification"
+  description="Enter the code from your authenticator app."
+  onSubmit={async (code) => {
+    if ((await submit(code)).ok) router.replace("/");
+  }}
+  error={error}
+  loading={loading}
+/>
+```
+
+`submitTotpSecondFactor({ signIn, setActive, code })` is the TOTP call without the hook; `submitSecondFactor({ signIn, setActive, code, strategy })` takes any of `totp`, `backup_code`, `phone_code`, `email_code`. `prepareSecondFactorIfNeeded({ signIn, strategy, factor? })` sends the `email_code` or `phone_code` first (no call for the others). `pickSecondFactorStrategy(factors)` gives the default. `TOTP_MESSAGES` holds `invalidCode`, `invalidCodeGeneric`, `sendFailed`, `needsAnotherStep` and `notReady`. An API error shows its own text unless it names the provider.
+
 ## Theme
 
 Wrap the tree (inside your colour-scheme provider):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "license": "MIT",
   "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts, the family app marks, a NativeWind preset, the Expo web root and Clerk + Convex auth screens.",
   "type": "module",

package/src/auth/AuthScreen.tsx

@@ -1,5 +1,5 @@
-import type { ReactNode } from "react";
-import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, Text, View } from "react-native";
+import { useEffect, useState, type ReactNode } from "react";
+import { Keyboard, KeyboardAvoidingView, ScrollView, StyleSheet, Text, View } from "react-native";
 import { cn } from "../cn";
 import { textStyle, typeStyle } from "../controlStyles";
 import { palette } from "../palette";
@@ -18,23 +18,51 @@ export type AuthScreenProps = {
   className?: string;
 };
 
+/** Space under the form while the keyboard is open, on top of its height. */
+const KEYBOARD_EXTRA = 24;
+
+/** The height of the open soft keyboard, or 0. Edge-to-edge Android ignores `adjustResize`, so the screen pads itself. */
+function useKeyboardHeight(): number {
+  const [height, setHeight] = useState(0);
+  useEffect(() => {
+    const show = (event: { endCoordinates: { height: number } }) => setHeight(event.endCoordinates.height);
+    const hide = () => setHeight(0);
+    const subs = [
+      Keyboard.addListener("keyboardWillShow", show),
+      Keyboard.addListener("keyboardDidShow", show),
+      Keyboard.addListener("keyboardWillHide", hide),
+      Keyboard.addListener("keyboardDidHide", hide),
+    ];
+    return () => subs.forEach((sub) => sub.remove());
+  }, []);
+  return height;
+}
+
 /**
  * The sign-in and sign-up frame: a keyboard-avoiding scroll view on the
  * background colour, with a title, subtitle and the form in a column of 16.
+ * The form is centred until the keyboard opens. Then it aligns to the top and
+ * the scroll content gains the keyboard height as bottom space, so the focused
+ * field and the submit button scroll above the keyboard.
  */
 export function AuthScreen({ title, subtitle, children, header, footer, testID, className }: AuthScreenProps) {
   const scheme = useScheme();
+  const keyboardHeight = useKeyboardHeight();
+  const keyboardOpen = keyboardHeight > 0;
   return (
     <KeyboardAvoidingView
-      behavior={Platform.OS === "ios" ? "padding" : "height"}
+      // Padding on both platforms, as OverlayModal and PromptInput: Android `height` does nothing edge-to-edge.
+      behavior="padding"
       className="flex-1"
       style={{ backgroundColor: tokens.color.background[scheme] }}
     >
       <ScrollView
         testID={testID}
         className="flex-1"
-        contentContainerClassName={cn("grow justify-center px-6 py-12", className)}
+        contentContainerClassName={cn("grow px-6 py-12", keyboardOpen ? "justify-start" : "justify-center", className)}
+        contentContainerStyle={keyboardOpen ? { paddingBottom: keyboardHeight + KEYBOARD_EXTRA } : undefined}
         keyboardShouldPersistTaps="handled"
+        keyboardDismissMode="on-drag"
       >
         <View className="w-full max-w-sm self-center gap-6">
           {header}

package/src/auth/SecondFactorScreen.tsx

@@ -0,0 +1,87 @@
+// Clerk-free: a one-time code step. The caller owns the verification call and
+// its errors (`useSecondFactor` does both for Clerk).
+import { useState, type ReactNode } from "react";
+import { Button } from "../Button";
+import { Input } from "../Input";
+import { AuthScreen, FieldError } from "./AuthScreen";
+
+export type SecondFactorScreenProps = {
+  title: string;
+  description?: string;
+  /** Digits in the code. Default 6. */
+  codeLength?: number;
+  /** Called with the full code. A rejected promise is the caller's to handle. */
+  onSubmit: (code: string) => Promise<void> | void;
+  /** Inline error under the field, such as "Incorrect code". */
+  error?: string;
+  /** Shows the Verify spinner and blocks a second submit. */
+  loading?: boolean;
+  /** Shows a ghost back button when set. */
+  onBack?: () => void;
+  /** Default "Back". */
+  backLabel?: string;
+  /** Above the title. App brand chrome goes here. */
+  header?: ReactNode;
+  /** Prefix for every `testID`. Default "second-factor". */
+  testIDPrefix?: string;
+  /** Below the buttons, such as a "Use a backup code" switch. Passed to `AuthScreen`. */
+  footer?: ReactNode;
+  /** Default `true`: digits only, number pad. `false` takes any characters (backup codes). */
+  digitsOnly?: boolean;
+  /** Placeholder when `digitsOnly` is `false`. Default "Code". */
+  placeholder?: string;
+};
+
+/** A one-time code step: digits only, a Verify button, an inline error and a back link. */
+export function SecondFactorScreen({
+  title,
+  description,
+  codeLength = 6,
+  onSubmit,
+  error,
+  loading = false,
+  onBack,
+  backLabel = "Back",
+  header,
+  testIDPrefix = "second-factor",
+  footer,
+  digitsOnly = true,
+  placeholder,
+}: SecondFactorScreenProps) {
+  const [code, setCode] = useState("");
+  const ready = code.length === codeLength && !loading;
+
+  const submit = () => {
+    if (ready) void onSubmit(code);
+  };
+
+  return (
+    <AuthScreen testID={`${testIDPrefix}-screen`} title={title} subtitle={description} header={header} footer={footer}>
+      <Input
+        testID={`${testIDPrefix}-code`}
+        accessibilityLabel="Verification code"
+        value={code}
+        placeholder={digitsOnly ? "0".repeat(codeLength) : (placeholder ?? "Code")}
+        keyboardType={digitsOnly ? "number-pad" : "default"}
+        autoCapitalize="none"
+        autoCorrect={false}
+        autoComplete="one-time-code"
+        textContentType="oneTimeCode"
+        maxLength={codeLength}
+        autoFocus
+        returnKeyType="go"
+        onChangeText={(text) => setCode(digitsOnly ? text.replace(/\D/g, "") : text.trim())}
+        onSubmitEditing={submit}
+      />
+      <FieldError testID={`${testIDPrefix}-error`} message={error} />
+      <Button testID={`${testIDPrefix}-verify`} loading={loading} disabled={!ready} onPress={submit}>
+        Verify
+      </Button>
+      {onBack ? (
+        <Button testID={`${testIDPrefix}-back`} variant="ghost" onPress={onBack}>
+          {backLabel}
+        </Button>
+      ) : null}
+    </AuthScreen>
+  );
+}

package/src/auth/SignInScreen.tsx

@@ -9,6 +9,14 @@ import { toast } from "../toastStore";
 import { useScheme } from "../useScheme";
 import { AuthScreen, FieldError, OrDivider } from "./AuthScreen";
 import { authErrorMessage } from "./authErrors";
+import { SecondFactorScreen } from "./SecondFactorScreen";
+import {
+  pickSecondFactorStrategy,
+  supportedSecondFactorStrategies,
+  useSecondFactor,
+  type SecondFactor,
+  type SecondFactorStrategy,
+} from "./totp";
 import { GoogleSignInButton, type AuthNavigationOptions } from "./GoogleSignInButton";
 
 export type SignInMode = "sign-in" | "sign-up";
@@ -22,8 +30,66 @@ export const AUTH_MESSAGES = {
   verifyFailed: "Invalid code",
   missingCode: "Enter the code from the email",
   needsAnotherStep: "This account needs another step to sign in. Finish it on the web.",
+  secondFactorTitle: "Two-step verification",
+  secondFactorDescription: "Enter the code from your authenticator app.",
+  emailCodeTitle: "Check your email",
+  emailCodeDescription: "Enter the code we sent to your email.",
+  phoneCodeTitle: "Check your phone",
+  phoneCodeDescription: "Enter the code we sent by text message.",
+  backupCodeTitle: "Enter a backup code",
+  backupCodeDescription: "Use one of the backup codes you saved when you set up two-step verification.",
+  clientTrustTitle: "Verify it's you",
+  clientTrustEmailDescription: "This device is new. Enter the code we sent to your email.",
+  clientTrustPhoneDescription: "This device is new. Enter the code we sent by text message.",
+  useBackupCode: "Use a backup code",
+  useAuthenticator: "Use authenticator app",
+  useEmailCode: "Email me a code",
+  usePhoneCode: "Text me a code",
+  newPasswordTitle: "Set a new password",
+  newPasswordDescription: "Your password must change before you can sign in.",
+  newPasswordLabel: "New password",
+  confirmPasswordLabel: "Confirm new password",
+  passwordMismatch: "The passwords do not match",
+  passwordTooShort: "Use a longer password",
+  resetPasswordFailed: "Could not set the new password",
+  setPassword: "Set password",
 } as const;
 
+/**
+ * A sign-in that is not complete, as `signIn.create` returns it. Passed to
+ * `onIncomplete` so the app can run the step itself.
+ */
+export type IncompleteSignIn = {
+  status: string | null;
+  createdSessionId: string | null;
+  supportedFirstFactors?: Array<{ strategy: string; [key: string]: unknown }> | null;
+  supportedSecondFactors?: SecondFactor[] | null;
+};
+
+const METHOD_LABEL: Record<SecondFactorStrategy, string> = {
+  totp: AUTH_MESSAGES.useAuthenticator,
+  email_code: AUTH_MESSAGES.useEmailCode,
+  phone_code: AUTH_MESSAGES.usePhoneCode,
+  backup_code: AUTH_MESSAGES.useBackupCode,
+};
+
+function secondFactorCopy(strategy: SecondFactorStrategy, clientTrust: boolean) {
+  if (strategy === "email_code") {
+    return clientTrust
+      ? { title: AUTH_MESSAGES.clientTrustTitle, description: AUTH_MESSAGES.clientTrustEmailDescription }
+      : { title: AUTH_MESSAGES.emailCodeTitle, description: AUTH_MESSAGES.emailCodeDescription };
+  }
+  if (strategy === "phone_code") {
+    return clientTrust
+      ? { title: AUTH_MESSAGES.clientTrustTitle, description: AUTH_MESSAGES.clientTrustPhoneDescription }
+      : { title: AUTH_MESSAGES.phoneCodeTitle, description: AUTH_MESSAGES.phoneCodeDescription };
+  }
+  if (strategy === "backup_code") {
+    return { title: AUTH_MESSAGES.backupCodeTitle, description: AUTH_MESSAGES.backupCodeDescription };
+  }
+  return { title: AUTH_MESSAGES.secondFactorTitle, description: AUTH_MESSAGES.secondFactorDescription };
+}
+
 export type SignInScreenProps = AuthNavigationOptions & {
   /** Default `"sign-in"`. `"sign-up"` creates the account and checks an emailed code. */
   mode?: SignInMode;
@@ -53,6 +119,17 @@ export type SignInScreenProps = AuthNavigationOptions & {
   header?: ReactNode;
   /** Below the footer link row, such as an app credit. */
   footer?: ReactNode;
+  /**
+   * Called with the sign-in when the built-in UI cannot finish it:
+   * `needs_identifier`, `needs_first_factor`, any unknown status, and
+   * `needs_second_factor` or `needs_client_trust` when no supported strategy
+   * (totp, backup code, phone code, email code) exists. The built-in screen
+   * always runs `needs_second_factor`, `needs_client_trust` and
+   * `needs_new_password` itself. When called, the web-fallback message is not
+   * shown. Without it, the screen shows the web fallback and logs
+   * `console.warn`. Ignored in `sign-up`.
+   */
+  onIncomplete?: (signIn: IncompleteSignIn) => void;
 };
 
 /**
@@ -80,6 +157,7 @@ export function SignInScreen({
   testIDPrefix,
   header,
   footer,
+  onIncomplete,
 }: SignInScreenProps) {
   const signInState = useSignIn();
   const signUpState = useSignUp();
@@ -89,6 +167,13 @@ export function SignInScreen({
   const [password, setPassword] = useState("");
   const [code, setCode] = useState("");
   const [pendingVerification, setPendingVerification] = useState(false);
+  const [pendingSecondFactor, setPendingSecondFactor] = useState(false);
+  const [factors, setFactors] = useState<SecondFactor[]>([]);
+  const [clientTrust, setClientTrust] = useState(false);
+  const [pendingNewPassword, setPendingNewPassword] = useState(false);
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const secondFactor = useSecondFactor();
   const [error, setError] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const signUp = mode === "sign-up";
@@ -104,6 +189,71 @@ export function SignInScreen({
     else router.replace(afterAuthHref, replaceOptions);
   };
 
+  const warnIncomplete = (attempt: IncompleteSignIn) => {
+    console.warn(
+      `[native-ui] Sign-in not complete: status=${attempt.status}, ` +
+        `secondFactors=${JSON.stringify((attempt.supportedSecondFactors ?? []).map((f) => f.strategy))}, ` +
+        `firstFactors=${JSON.stringify((attempt.supportedFirstFactors ?? []).map((f) => f.strategy))}. ` +
+        "Pass onIncomplete to handle it in the app.",
+    );
+  };
+
+  // A status the built-in UI cannot finish: the app's `onIncomplete`, or the web fallback.
+  const unhandled = (attempt: IncompleteSignIn) => {
+    if (onIncomplete) return onIncomplete(attempt);
+    warnIncomplete(attempt);
+    fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.needsAnotherStep);
+  };
+
+  const chooseStrategy = async (strategy: SecondFactorStrategy, list: SecondFactor[]) => {
+    secondFactor.clearError();
+    secondFactor.setStrategy(strategy);
+    setPendingSecondFactor(true);
+    await secondFactor.prepare(
+      strategy,
+      list.find((factor) => factor.strategy === strategy),
+    );
+  };
+
+  const startSecondFactor = async (attempt: IncompleteSignIn, trust: boolean) => {
+    const list = attempt.supportedSecondFactors ?? [];
+    const strategy = pickSecondFactorStrategy(list);
+    if (!strategy) return unhandled(attempt);
+    setFactors(list);
+    setClientTrust(trust);
+    await chooseStrategy(strategy, list);
+  };
+
+  const onNewPassword = async () => {
+    const { isLoaded, signIn, setActive } = signInState;
+    if (!isLoaded || !signIn || !setActive || submitting) return;
+    if (!newPassword) return fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.missingFields);
+    if (minPasswordLength && newPassword.length < minPasswordLength) {
+      return fail(AUTH_MESSAGES.resetPasswordFailed, `Use at least ${minPasswordLength} characters for the password`);
+    }
+    if (newPassword !== confirmPassword) {
+      return fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.passwordMismatch);
+    }
+    setSubmitting(true);
+    setError("");
+    try {
+      const result = await signIn.resetPassword({ password: newPassword });
+      if (result.status === "complete" && result.createdSessionId) {
+        await setActive({ session: result.createdSessionId });
+        done();
+      } else if (onIncomplete) {
+        onIncomplete(result);
+      } else {
+        warnIncomplete(result);
+        fail(AUTH_MESSAGES.resetPasswordFailed, AUTH_MESSAGES.needsAnotherStep);
+      }
+    } catch (caught) {
+      fail(AUTH_MESSAGES.resetPasswordFailed, authErrorMessage(caught, AUTH_MESSAGES.resetPasswordFailed));
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
   const onSignIn = async () => {
     const { isLoaded, signIn, setActive } = signInState;
     if (!isLoaded || !signIn || !setActive || submitting) return;
@@ -115,8 +265,12 @@ export function SignInScreen({
       if (attempt.status === "complete" && attempt.createdSessionId) {
         await setActive({ session: attempt.createdSessionId });
         done();
+      } else if (attempt.status === "needs_new_password") {
+        setPendingNewPassword(true);
+      } else if (attempt.status === "needs_second_factor" || attempt.status === "needs_client_trust") {
+        await startSecondFactor(attempt, attempt.status === "needs_client_trust");
       } else {
-        fail(AUTH_MESSAGES.signInFailed, AUTH_MESSAGES.needsAnotherStep);
+        unhandled(attempt);
       }
     } catch (caught) {
       fail(AUTH_MESSAGES.signInFailed, authErrorMessage(caught, AUTH_MESSAGES.invalidCredentials));
@@ -125,6 +279,22 @@ export function SignInScreen({
     }
   };
 
+  const onSecondFactor = async (secondFactorCode: string) => {
+    const result = await secondFactor.submit(secondFactorCode);
+    if (result.ok) done();
+  };
+
+  const onSecondFactorBack = () => {
+    // The pending attempt stays; the next `signIn.create` replaces it.
+    setPendingSecondFactor(false);
+    setPendingNewPassword(false);
+    setNewPassword("");
+    setConfirmPassword("");
+    setPassword("");
+    setError("");
+    secondFactor.clearError();
+  };
+
   const onSignUp = async () => {
     const { isLoaded, signUp: attempt } = signUpState;
     if (!isLoaded || !attempt || submitting) return;
@@ -190,6 +360,97 @@ export function SignInScreen({
   );
   const hasFooter = Boolean((linkHref && !pendingVerification) || footer);
 
+  if (pendingNewPassword) {
+    return (
+      <AuthScreen
+        testID={id("new-password-screen")}
+        title={AUTH_MESSAGES.newPasswordTitle}
+        subtitle={AUTH_MESSAGES.newPasswordDescription}
+        header={header}
+      >
+        <Input
+          testID={id("new-password")}
+          accessibilityLabel={AUTH_MESSAGES.newPasswordLabel}
+          autoCapitalize="none"
+          autoComplete="new-password"
+          textContentType="newPassword"
+          secureTextEntry
+          autoFocus
+          returnKeyType="next"
+          value={newPassword}
+          placeholder={AUTH_MESSAGES.newPasswordLabel}
+          onChangeText={setNewPassword}
+        />
+        <Input
+          testID={id("confirm-password")}
+          accessibilityLabel={AUTH_MESSAGES.confirmPasswordLabel}
+          autoCapitalize="none"
+          autoComplete="new-password"
+          textContentType="newPassword"
+          secureTextEntry
+          returnKeyType="go"
+          value={confirmPassword}
+          placeholder={AUTH_MESSAGES.confirmPasswordLabel}
+          onChangeText={setConfirmPassword}
+          onSubmitEditing={() => void onNewPassword()}
+        />
+        <FieldError testID={id("error")} message={error} />
+        <Button testID={id("new-password-submit")} loading={submitting} onPress={() => void onNewPassword()}>
+          {AUTH_MESSAGES.setPassword}
+        </Button>
+        <Button testID={id("new-password-back")} variant="ghost" onPress={onSecondFactorBack}>
+          Use a different account
+        </Button>
+      </AuthScreen>
+    );
+  }
+
+  if (pendingSecondFactor) {
+    const active = secondFactor.strategy;
+    const available = supportedSecondFactorStrategies(factors);
+    const others = available.filter((strategy) => strategy !== active);
+    // From a backup code, go back to the default non-backup method. Otherwise offer a backup code.
+    const switchTo =
+      active === "backup_code"
+        ? pickSecondFactorStrategy(factors.filter((factor) => factor.strategy !== "backup_code"))
+        : others.includes("backup_code")
+          ? "backup_code"
+          : null;
+    const copy = secondFactorCopy(active, clientTrust);
+    const backup = active === "backup_code";
+    return (
+      <SecondFactorScreen
+        key={active}
+        title={copy.title}
+        description={copy.description}
+        codeLength={backup ? 8 : 6}
+        digitsOnly={!backup}
+        placeholder="Backup code"
+        footer={
+          switchTo ? (
+            <Button
+              testID={id("second-factor-switch")}
+              variant="link"
+              size="sm"
+              fullWidth={false}
+              disabled={secondFactor.loading}
+              onPress={() => void chooseStrategy(switchTo, factors)}
+            >
+              {METHOD_LABEL[switchTo]}
+            </Button>
+          ) : undefined
+        }
+        onSubmit={onSecondFactor}
+        error={secondFactor.error}
+        loading={secondFactor.loading}
+        onBack={onSecondFactorBack}
+        backLabel="Use a different account"
+        header={header}
+        testIDPrefix={id("second-factor")}
+      />
+    );
+  }
+
   if (pendingVerification) {
     return (
       <AuthScreen

package/src/auth/index.ts

@@ -19,4 +19,26 @@ export type {
   GoogleSignInButtonProps,
 } from "./GoogleSignInButton";
 export { SignInScreen, SignUpScreen, AUTH_MESSAGES } from "./SignInScreen";
-export type { SignInMode, SignInScreenProps, SignUpScreenProps } from "./SignInScreen";
+export type { IncompleteSignIn, SignInMode, SignInScreenProps, SignUpScreenProps } from "./SignInScreen";
+export { SecondFactorScreen } from "./SecondFactorScreen";
+export type { SecondFactorScreenProps } from "./SecondFactorScreen";
+export {
+  submitTotpSecondFactor,
+  submitSecondFactor,
+  prepareSecondFactorIfNeeded,
+  pickSecondFactorStrategy,
+  supportedSecondFactorStrategies,
+  SECOND_FACTOR_PREFERENCE,
+  useSecondFactor,
+  TOTP_MESSAGES,
+} from "./totp";
+export type {
+  SecondFactor,
+  SecondFactorSignIn,
+  SecondFactorStrategy,
+  TotpResult,
+  TotpSignIn,
+  TotpSetActive,
+  UseSecondFactorOptions,
+  UseSecondFactorResult,
+} from "./totp";

package/src/auth/totp.ts

@@ -0,0 +1,202 @@
+import { useState } from "react";
+import { useSignIn } from "@clerk/clerk-expo";
+import { authErrorMessage } from "./authErrors";
+
+/** The messages the second-factor step can show. Generic: none names a provider. */
+export const TOTP_MESSAGES = {
+  invalidCode: "Incorrect code. Check your authenticator app and try again.",
+  invalidCodeGeneric: "Incorrect code. Check it and try again.",
+  sendFailed: "Could not send the code. Try again.",
+  needsAnotherStep: "This account needs another step to sign in. Finish it on the web.",
+  notReady: "Sign in is not ready yet. Try again in a moment.",
+} as const;
+
+/** The second-factor strategies the built-in step handles. */
+export type SecondFactorStrategy = "totp" | "backup_code" | "phone_code" | "email_code";
+
+/** Default order: the first one the account supports wins. */
+export const SECOND_FACTOR_PREFERENCE: readonly SecondFactorStrategy[] = [
+  "totp",
+  "email_code",
+  "phone_code",
+  "backup_code",
+];
+
+/** One entry of `signIn.supportedSecondFactors`. */
+export type SecondFactor = {
+  strategy: string;
+  emailAddressId?: string;
+  phoneNumberId?: string;
+  safeIdentifier?: string;
+};
+
+type AttemptResult = { status: string | null; createdSessionId: string | null };
+
+/** The part of the sign-in resource that TOTP needs. Tests pass a mock. */
+export type TotpSignIn = {
+  attemptSecondFactor(params: { strategy: "totp"; code: string }): Promise<AttemptResult>;
+};
+
+/** The part of the sign-in resource that any second factor needs. Tests pass a mock. */
+export type SecondFactorSignIn = {
+  supportedSecondFactors?: SecondFactor[] | null;
+  prepareSecondFactor?(params: {
+    strategy: "phone_code" | "email_code";
+    phoneNumberId?: string;
+    emailAddressId?: string;
+  }): Promise<unknown>;
+  attemptSecondFactor(params: { strategy: SecondFactorStrategy; code: string }): Promise<AttemptResult>;
+};
+
+export type TotpSetActive = (params: { session: string }) => Promise<void>;
+
+export type TotpResult = { ok: true } | { ok: false; error: string };
+
+/** The strategies in `factors` that the built-in step handles, in the order given. */
+export function supportedSecondFactorStrategies(
+  factors: readonly SecondFactor[] | null | undefined,
+): SecondFactorStrategy[] {
+  const found = new Set((factors ?? []).map((factor) => factor.strategy));
+  return SECOND_FACTOR_PREFERENCE.filter((strategy) => found.has(strategy));
+}
+
+/** The default strategy: `totp`, then `email_code`, `phone_code`, `backup_code`. `null` when none is supported. */
+export function pickSecondFactorStrategy(
+  factors: readonly SecondFactor[] | null | undefined,
+): SecondFactorStrategy | null {
+  return supportedSecondFactorStrategies(factors)[0] ?? null;
+}
+
+/**
+ * Sends the code for `phone_code` and `email_code`, with the `phoneNumberId` or
+ * `emailAddressId` of the matching factor. `totp` and `backup_code` need no
+ * prepare: it returns `{ ok: true }` without a call. Never throws.
+ */
+export async function prepareSecondFactorIfNeeded(args: {
+  signIn: Pick<SecondFactorSignIn, "supportedSecondFactors" | "prepareSecondFactor">;
+  strategy: SecondFactorStrategy;
+  factor?: SecondFactor;
+}): Promise<TotpResult> {
+  const { signIn, strategy } = args;
+  if (strategy !== "phone_code" && strategy !== "email_code") return { ok: true };
+  if (!signIn.prepareSecondFactor) return { ok: false, error: TOTP_MESSAGES.sendFailed };
+  const factor = args.factor ?? signIn.supportedSecondFactors?.find((item) => item.strategy === strategy);
+  try {
+    if (strategy === "phone_code") {
+      await signIn.prepareSecondFactor({
+        strategy,
+        ...(factor?.phoneNumberId ? { phoneNumberId: factor.phoneNumberId } : {}),
+      });
+    } else {
+      await signIn.prepareSecondFactor({
+        strategy,
+        ...(factor?.emailAddressId ? { emailAddressId: factor.emailAddressId } : {}),
+      });
+    }
+    return { ok: true };
+  } catch (caught) {
+    return { ok: false, error: authErrorMessage(caught, TOTP_MESSAGES.sendFailed) };
+  }
+}
+
+/**
+ * Checks a second-factor code and starts the session. Call
+ * `prepareSecondFactorIfNeeded` first for `phone_code` and `email_code`.
+ * Never throws: a failure is `{ ok: false, error }`. An API error shows its
+ * own text (such as "Incorrect code") unless it names the provider; anything
+ * else gives `TOTP_MESSAGES.invalidCode` (`totp`) or `invalidCodeGeneric`.
+ */
+export async function submitSecondFactor(args: {
+  signIn: Pick<SecondFactorSignIn, "attemptSecondFactor">;
+  setActive: TotpSetActive;
+  code: string;
+  strategy: SecondFactorStrategy;
+}): Promise<TotpResult> {
+  try {
+    const attempt = await args.signIn.attemptSecondFactor({ strategy: args.strategy, code: args.code });
+    if (attempt.status === "complete" && attempt.createdSessionId) {
+      await args.setActive({ session: attempt.createdSessionId });
+      return { ok: true };
+    }
+    return { ok: false, error: TOTP_MESSAGES.needsAnotherStep };
+  } catch (caught) {
+    const fallback = args.strategy === "totp" ? TOTP_MESSAGES.invalidCode : TOTP_MESSAGES.invalidCodeGeneric;
+    return { ok: false, error: authErrorMessage(caught, fallback) };
+  }
+}
+
+/** Checks a TOTP code and starts the session. TOTP needs no `prepareSecondFactor`. Same as `submitSecondFactor` with `strategy: "totp"`. */
+export function submitTotpSecondFactor(args: {
+  signIn: TotpSignIn;
+  setActive: TotpSetActive;
+  code: string;
+}): Promise<TotpResult> {
+  return submitSecondFactor({ signIn: args.signIn, setActive: args.setActive, code: args.code, strategy: "totp" });
+}
+
+export type UseSecondFactorOptions = {
+  /** The strategy `submit` uses until `setStrategy` changes it. Default `"totp"`. */
+  strategy?: SecondFactorStrategy;
+};
+
+export type UseSecondFactorResult = {
+  /** Checks the code and starts the session. Never throws. Sets `error` on failure. */
+  submit: (code: string) => Promise<TotpResult>;
+  /** Sends the code for `phone_code` and `email_code` (no call for the others). Never throws. Sets `error` on failure. */
+  prepare: (strategy?: SecondFactorStrategy, factor?: SecondFactor) => Promise<TotpResult>;
+  /** The strategy `submit` uses. */
+  strategy: SecondFactorStrategy;
+  setStrategy: (strategy: SecondFactorStrategy) => void;
+  /** True while `submit` or `prepare` runs. */
+  loading: boolean;
+  /** The last failure message, or `""`. */
+  error: string;
+  clearError: () => void;
+};
+
+/**
+ * Completes a sign-in that returned `needs_second_factor`. Default strategy
+ * `"totp"` (an authenticator-app code); pass `{ strategy }` or call
+ * `setStrategy` for the others. Pair with `SecondFactorScreen`:
+ * `onSubmit={submit}`, `error={error}`, `loading={loading}`. After
+ * `{ ok: true }` the session is active: navigate in the caller.
+ */
+export function useSecondFactor(options: UseSecondFactorOptions = {}): UseSecondFactorResult {
+  const { isLoaded, signIn, setActive } = useSignIn();
+  const [chosen, setChosen] = useState<SecondFactorStrategy | null>(null);
+  const strategy = chosen ?? options.strategy ?? "totp";
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  const submit = async (code: string): Promise<TotpResult> => {
+    if (loading) return { ok: false, error };
+    if (!isLoaded || !signIn || !setActive) {
+      setError(TOTP_MESSAGES.notReady);
+      return { ok: false, error: TOTP_MESSAGES.notReady };
+    }
+    setLoading(true);
+    setError("");
+    const result = await submitSecondFactor({ signIn, setActive, code, strategy });
+    if (!result.ok) setError(result.error);
+    setLoading(false);
+    return result;
+  };
+
+  const prepare = async (
+    prepareStrategy: SecondFactorStrategy = strategy,
+    factor?: SecondFactor,
+  ): Promise<TotpResult> => {
+    if (!isLoaded || !signIn) {
+      setError(TOTP_MESSAGES.notReady);
+      return { ok: false, error: TOTP_MESSAGES.notReady };
+    }
+    setLoading(true);
+    setError("");
+    const result = await prepareSecondFactorIfNeeded({ signIn, strategy: prepareStrategy, factor });
+    if (!result.ok) setError(result.error);
+    setLoading(false);
+    return result;
+  };
+
+  return { submit, prepare, strategy, setStrategy: setChosen, loading, error, clearError: () => setError("") };
+}