# Two Factor

> Use when implementing two-factor authentication setup and verification.

- Skill: `thedaviddias/two-factor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add thedaviddias/two-factor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedaviddias/two-factor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thedaviddias (https://skillmd.com/u/thedaviddias)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thedaviddias/two-factor

---


# Two-Factor Authentication

Two-factor authentication setup and verification

## What it solves

**Two-Factor Authentication (2FA)** adds a second verification step after the user enters their password, requiring proof of something they have (a phone, security key, or authenticator app) in addition to something they know (their password). This dramatically reduces the risk of unauthorized access from stolen credentials.
The 2FA pattern covers both the **setup flow** (enrolling a second factor) and the **verification flow** (entering a code or using a device during login).

## When to use

Use **Two-Factor Authentication** to **protect accounts with an additional verification layer beyond username and password**.
**Common scenarios include:**
- Financial applications, banking, and payment platforms
- Email services and communication platforms
- Admin dashboards and privileged user accounts
- Healthcare and legal applications with sensitive data
- Developer platforms with access to infrastructure and code repositories

## When to avoid

- Low-risk applications where the cost of 2FA outweighs the security benefit
- Applications targeting users with limited technical proficiency (consider risk-based auth instead)
- When the friction of 2FA would significantly reduce adoption of a consumer product (make it optional)
- Kiosk or shared-device environments where device-based factors are impractical

## Implementation workflow

1. Confirm the pattern matches the problem and constraints before copying the example.
2. Start from the anatomy and examples in `references/pattern.md`, then choose the smallest viable variation.
3. Apply accessibility, performance, and interaction guardrails before layering visual polish.
4. Use the testing guidance to verify behavior across keyboard, screen reader, responsive, and failure scenarios.

## Accessibility guardrails

**Do's ✅**
- Use `inputmode="numeric"` on the code input for the numeric keyboard on mobile
- Use `autocomplete="one-time-code"` so browsers and password managers can autofill SMS codes
- Provide `alt` text for the QR code image describing its purpose
- Announce errors with `role="alert"` when an invalid code is entered
- Provide a text-based alternative to the QR code (manual entry of the secret key)
**Don'ts ❌**
- Don't make the QR code the only way to set up TOTP — always offer manual entry
- Don't use time pressure that penalizes users who need more time to enter codes
- Don't rely on color alone for success/error feedback on code entry

## Performance guardrails

### Target Metrics
- **QR code generation:** < 200ms server-side
- **Code verification:** < 300ms server-side
- **SMS delivery:** < 10 seconds
- **Code input response:** < 50ms keystroke-to-display
- **Auto-submit:** < 100ms from 6th digit to submission
### Optimization Strategies
**Client-Side QR Code Generation**
```javascript
const qrDataUrl = await QRCode.toDataURL(totpUri);
```

## Common mistakes

### No Backup Code Recovery
**The Problem:**
Users who lose their authenticator device have no way to access their account.

**How to Fix It:**
Generate 8-10 one-time backup codes during 2FA setup. Clearly prompt users to save them. Provide a backup code entry option on the verification screen.

### SMS as the Only 2FA Method
**The Problem:**
SMS codes are vulnerable to SIM swapping, SS7 interception, and delivery delays.

**How to Fix It:**
Offer TOTP (authenticator app) as the primary method. Use SMS only as a fallback. Consider supporting security keys for high-security accounts.

### Time-Skew Rejection
**The Problem:**
TOTP codes are rejected because the user's device clock is slightly out of sync with the server.

**How to Fix It:**
Accept codes from the current time window plus one window before and after (±30 seconds). This is standard TOTP tolerance.

## Related patterns

- https://uxpatterns.dev/patterns/authentication/account-settings
- https://uxpatterns.dev/patterns/authentication/login
- https://uxpatterns.dev/patterns/authentication/password-reset
- https://uxpatterns.dev/patterns/authentication/social-login

---

For full implementation detail, examples, and testing notes, see `references/pattern.md`.

Pattern page: https://uxpatterns.dev/patterns/authentication/two-factor