Build a sign-in with 2-step verification

Overview

A three-stage flow: credentials → OTP → success. One component, one state machine, one place to handle errors.

2-step verification is the cheapest, biggest security win you can ship. A stolen password is no longer enough; the attacker would also need the operator's phone or authenticator app. For an SMB app — where the same login often unlocks cash drawers, payroll exports and supplier payments — that second factor is what separates "we got phished" from "we tried to get phished".

The recipe keeps the second factor short-code (TOTP-style), not push-based, because (a) it works offline and on a feature phone, and (b) you don't need to run a notification server to ship it. If the user opts in to "trust this device", you skip the OTP step on that device for 30 days.

Skip 2FA if your app holds no money, no PII and no actions that are hard to reverse — e.g. a public storefront, a marketing site, an internal-only kiosk. Adding a second factor to a low-stakes app just teaches users to dismiss prompts.

What you'll build

Three screens, one component. The state machine moves the user forward; the back button moves them back.

You can see this live in

Portal demos that wire this recipe in context. Open one to watch the state machine fire.

Required pieces

Everything this recipe pulls from @corelithzw/react. Open any reference page for props, variants and the do/don't.

@corelithzw/react exports used here: Stack, Form, Field, Input, InputOtp, Button, Alert, Checkbox, AuthShell. Phase 2 recipes copy these names verbatim — keep the convention.

Step-by-step build

The single hardest bug in auth flows is two screens being visible at the same time, or the back button skipping a step. Make the stage a string union — 'credentials' | 'otp' | 'success' — and render exactly one branch. Errors live on the same machine so you never have a "verified but still on the OTP screen" race.

Put both fields inside one Form so Enter submits, and link the alert above with aria-describedby so a screen reader reads the error together with the form. Don't navigate to a separate error page — that wipes what the user typed.

InputOtp handles the per-digit boxes, paste-into-all, and autocomplete="one-time-code" for iOS keyboard SMS suggestion. Run the resend countdown in a tiny useEffect; disable the resend button until the timer hits zero so the user can't spam your SMS budget.

People don't trust silent redirects. The success screen confirms the identity ("signed in as …") and tells the user what their trust-device choice means, then auto-forwards in 2 seconds. The auto-forward gives users who hit "trust" a moment to read the consequence; users who skipped it just see the dashboard a moment later.

Final composition

The whole SignInWith2FA component, assembled. State machine, error paths, resend timer, trust-device, and a wrapper AuthShell from the auth pattern so the centered card + logo come free.

Variations

Three common forks. Each is a small diff from the final composition — drop them in and the rest of the machine keeps working.

// Drop 'otp' from the union
type Stage = 'credentials' | 'success';

// CREDENTIALS_OK lands you on success
case 'CREDENTIALS_OK':
  return { ...s, stage: 'success', email: a.email };
// remove the <Otp/> render block

// Replace password Field with a hint
<p>We'll email you a one-time link.</p>

// OtpScreen becomes a poller
<Stack>
  <h1>Check your inbox</h1>
  <p>Link sent to <b>{email}</b>.</p>
</Stack>

// Credentials becomes a 2-line screen
<Button onClick={signInWithSso}>
  Continue with SSO
</Button>
<Button variant="link"
  onClick={() => setMode('password')}>
  Use email + password
</Button>

Accessibility

What this recipe takes care of for you. Every item below is something a screen-reader or keyboard-only user will notice if you skip it.

• Focus moves with the stage. When stage flips to 'otp', the first OTP box gets autoFocus. On 'success', the heading gets focus so the next Tab lands on "Go to dashboard".
• OTP input declares its purpose. autoComplete="one-time-code" + inputMode="numeric" together unlock the iOS keyboard SMS suggestion and pop the number pad on Android.
• Errors are linked, not just rendered. The Alert carries an id and the form/OTP carries a matching aria-describedby, so a screen reader reads the field name and the error in one breath.
• Success is announced. The success container uses role="status" + aria-live="polite" so screen readers say "You're in. Signed in as …" without the user needing to navigate to it.
• Resend disables itself. The button uses real disabled while the countdown runs — it's keyboard-skipped and screen-readers read it as "Resend in 0:42, dimmed", not as a clickable target.
• The whole flow is keyboard-only. Tab order matches reading order, Enter submits each form, Esc on the OTP screen returns to credentials.
• Trust-this-device is a real checkbox. Checkbox wraps the label so click-on-text works and screen readers announce its state.

Related recipes

More auth flows that share this state-machine pattern. Phase 2 fills these in.