diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index ee40461..c9e60be 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -14,9 +14,35 @@
 | Vault item plaintext       | ❌ never           | Only the client (with master password) decrypts |
 | Item count                 | ✅                 | Acceptable leak                                |
 | Item type (login/note/...) | ✅                 | Acceptable leak                                |
+| TOTP shared secret (opt-in)| ✅ when 2FA enabled| RFC 6238 verifier requires the secret — see below |
+| TOTP recovery codes        | ❌ Argon2id-hashed | Plaintext shown to user once, never persisted  |
 
 ## Threats considered
 
+### Optional TOTP (2FA) — what it changes
+
+Enabling 2FA adds a per-user TOTP secret (RFC 4226 / 6238) to the
+`users` row. **This is the one server-stored secret that vault data is
+not derived from.** Crucially:
+
+- **Vault contents stay zero-knowledge.** A breach that leaks both the
+  auth_key hash and the TOTP secret still does **not** enable vault
+  decryption — the symmetric key is encrypted with the master key, and
+  the master key is never on the server.
+- **Login auth widens by one secret.** An attacker who exfiltrates the
+  TOTP secret can compute valid OTPs for that user and bypass the 2FA
+  challenge — but they still need the master password to get past the
+  first factor and to actually decrypt anything.
+- **Recovery codes are stored as Argon2id hashes**, identical posture to
+  the auth_key hash. A leak of the recovery-codes column does not
+  enable login.
+- **Disable always requires a fresh code** (current OTP or recovery
+  code). A stolen access token alone can't downgrade the auth posture.
+
+If you need a true zero-knowledge second factor, leave TOTP off and use
+the upcoming WebAuthn / passkey path (tracked) which uses public-key
+crypto — the server only stores the public key, never a verifier secret.
+
 ### Database breach
 Attacker pulls a full dump. They have: emails, Argon2 hashes of auth keys,
 KDF parameters, encrypted blobs.
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 140ab5f..39d6e43 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -355,6 +355,47 @@ The file shape is intentionally stable (`{ format, version, vault,
 items: [...] }`) so a future Restore flow can consume it without a
 schema bump.
 
+### 5g. Two-factor authentication (TOTP)
+
+Open the **Settings** link in the sidebar's user card → click **Set up 2FA**.
+
+The setup flow has three steps:
+
+1. **Scan the QR** with your authenticator (Google Authenticator,
+   1Password, Authy, Microsoft Authenticator, …). If your phone can't
+   reach the screen, expand "Can't scan? Type this manually" and copy
+   the base32 secret directly into the app.
+2. **Confirm the first code.** Type the 6-digit code your authenticator
+   shows. Passman verifies against the stored secret and only then
+   flips the `totp_enabled` flag — if you abandon the flow before this
+   step your account stays at single-factor.
+3. **Save your recovery codes.** Ten single-use codes are shown
+   *exactly once*. Each lets you log in if you lose your phone. Copy
+   them, download the `.txt`, or write them down — Passman keeps only
+   Argon2id hashes server-side, so this list cannot be retrieved later.
+
+Once enabled, login becomes two-step: email + master password, then a
+6-digit code. Recovery codes work in place of the 6-digit code (and
+are consumed on first use — `9 remaining` becomes `8`).
+
+> **Trade-off, plainly stated.** TOTP is **not** zero-knowledge —
+> RFC 6238 requires the verifier to know the shared secret, so the
+> server now holds your OTP secret alongside the existing auth_key
+> hash. Vault contents stay zero-knowledge: a server breach that leaks
+> both still can't decrypt your credentials. The benefit is that
+> credential-stuffing or phishing attacks against the password alone
+> can't get past login.
+>
+> If you need the strongest server-side guarantee, leave 2FA off —
+> the original posture (auth_key + master-password-derived key) is
+> already strong against offline attacks. WebAuthn / passkeys are the
+> tracked alternative for users who want a second factor without
+> server-side secrets.
+
+To turn 2FA off: Settings → **Disable 2FA** → enter a current code or
+a recovery code. A stolen access token alone can't downgrade — the
+disable endpoint always requires fresh proof.
+
 ---
 
 ## 6. Chrome extension
diff --git a/package-lock.json b/package-lock.json
index a33dada..7322b6a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1287,7 +1287,6 @@
       "version": "22.10.2",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.10.2.tgz",
       "integrity": "sha512-Xxr6BBRCAOQixvonOye19wnzyDiUtTeqldOOmj3CkeblonbccA12PFwlufvRdrpjXxqnmUaeiU5EOA+7s5diUQ==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "undici-types": "~6.20.0"
@@ -1300,6 +1299,15 @@
       "devOptional": true,
       "license": "MIT"
     },
+    "node_modules/@types/qrcode": {
+      "version": "1.5.6",
+      "resolved": "https://registry.npmjs.org/@types/qrcode/-/qrcode-1.5.6.tgz",
+      "integrity": "sha512-te7NQcV2BOvdj2b1hCAHzAoMNuj65kNBMz0KBaxM6c3VGBOhU0dURQKOtH8CFNI/dsKkwlv32p26qYQTWoB5bw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/react": {
       "version": "18.3.28",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.28.tgz",
@@ -1428,6 +1436,30 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/assertion-error": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -1485,6 +1517,15 @@
         "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
       }
     },
+    "node_modules/camelcase": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-5.3.1.tgz",
+      "integrity": "sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/caniuse-lite": {
       "version": "1.0.30001792",
       "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001792.tgz",
@@ -1516,6 +1557,35 @@
         "node": ">=18"
       }
     },
+    "node_modules/cliui": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-6.0.0.tgz",
+      "integrity": "sha512-t6wbgtoCXvAzst7QgXxJYqPt0usEfbgQdftEPbLL/cvv6HPE5VgvqCuAIDR0NgU52ds6rFwqrgakNLrHEjCbrQ==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.0",
+        "wrap-ansi": "^6.2.0"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
     "node_modules/convert-source-map": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
@@ -1548,6 +1618,21 @@
         }
       }
     },
+    "node_modules/decamelize": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/decamelize/-/decamelize-1.2.0.tgz",
+      "integrity": "sha512-z2S+W9X73hAUUki+N+9Za2lBlun89zigOyGrsax+KUQ6wKW4ZoWpEYBkGhQjwAjjDCkWxhY0VKEhk8wzY7F5cA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/dijkstrajs": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/dijkstrajs/-/dijkstrajs-1.0.3.tgz",
+      "integrity": "sha512-qiSlmBq9+BCdCA/L46dw8Uy93mloxsPSbwnm5yrKn2vMPiy8KyAskTF6zuV/j5BMsmOGZDPs7KjU+mjb670kfA==",
+      "license": "MIT"
+    },
     "node_modules/electron-to-chromium": {
       "version": "1.5.352",
       "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.352.tgz",
@@ -1555,6 +1640,12 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
     "node_modules/es-module-lexer": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.1.0.tgz",
@@ -1662,6 +1753,19 @@
         }
       }
     },
+    "node_modules/find-up": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz",
+      "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
+      "license": "MIT",
+      "dependencies": {
+        "locate-path": "^5.0.0",
+        "path-exists": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -1687,12 +1791,30 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
     "node_modules/hash-wasm": {
       "version": "4.12.0",
       "resolved": "https://registry.npmjs.org/hash-wasm/-/hash-wasm-4.12.0.tgz",
       "integrity": "sha512-+/2B2rYLb48I/evdOIhP+K/DD2ca2fgBjp6O+GBEnCDk2e4rpeXIK8GvIyRPjTezgmWn9gmKwkQjjx6BtqDHVQ==",
       "license": "MIT"
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -1725,6 +1847,18 @@
         "node": ">=6"
       }
     },
+    "node_modules/locate-path": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
+      "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
+      "license": "MIT",
+      "dependencies": {
+        "p-locate": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/loose-envify": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
@@ -1801,6 +1935,51 @@
       ],
       "license": "MIT"
     },
+    "node_modules/p-limit": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
+      "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
+      "license": "MIT",
+      "dependencies": {
+        "p-try": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-locate": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz",
+      "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
+      "license": "MIT",
+      "dependencies": {
+        "p-limit": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/p-try": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz",
+      "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/path-exists": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
+      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/pathe": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
@@ -1828,6 +2007,15 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/pngjs": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-5.0.0.tgz",
+      "integrity": "sha512-40QW5YalBNfQo5yRYmiw7Yz6TKKVr3h6970B2YE+3fQpsWcrbj1PzJgxeJ19DRQjhMbKPIuMY8rFaXc8moolVw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
     "node_modules/postcss": {
       "version": "8.5.14",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
@@ -1857,6 +2045,23 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/qrcode": {
+      "version": "1.5.4",
+      "resolved": "https://registry.npmjs.org/qrcode/-/qrcode-1.5.4.tgz",
+      "integrity": "sha512-1ca71Zgiu6ORjHqFBDpnSMTR2ReToX4l1Au1VFLyVeBTFavzQnv5JxMFr3ukHVKpSrSA2MCk0lNJSykjUfz7Zg==",
+      "license": "MIT",
+      "dependencies": {
+        "dijkstrajs": "^1.0.1",
+        "pngjs": "^5.0.0",
+        "yargs": "^15.3.1"
+      },
+      "bin": {
+        "qrcode": "bin/qrcode"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
     "node_modules/react": {
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
@@ -1924,6 +2129,21 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/require-main-filename": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/require-main-filename/-/require-main-filename-2.0.0.tgz",
+      "integrity": "sha512-NKN5kMDylKuldxYLSUfrbo5Tuzh4hd+2E8NPPX02mZtn1VuREQToYe/ZdlJy+J3uCpfaiGF05e7B8W0iXbQHmg==",
+      "license": "ISC"
+    },
     "node_modules/rollup": {
       "version": "4.60.3",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.3.tgz",
@@ -1988,6 +2208,12 @@
         "semver": "bin/semver.js"
       }
     },
+    "node_modules/set-blocking": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
+      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
+      "license": "ISC"
+    },
     "node_modules/siginfo": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -2019,6 +2245,32 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/tinybench": {
       "version": "2.9.0",
       "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
@@ -2081,7 +2333,6 @@
       "version": "6.20.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.20.0.tgz",
       "integrity": "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/update-browserslist-db": {
@@ -2307,6 +2558,12 @@
         }
       }
     },
+    "node_modules/which-module": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/which-module/-/which-module-2.0.1.tgz",
+      "integrity": "sha512-iBdZ57RDvnOR9AGBhML2vFZf7h8vmBjhoaZqODJBFWHVtKkDmKuHai3cx5PgVMrX5YDNp27AofYbAwctSS+vhQ==",
+      "license": "ISC"
+    },
     "node_modules/why-is-node-running": {
       "version": "2.3.0",
       "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
@@ -2324,6 +2581,26 @@
         "node": ">=8"
       }
     },
+    "node_modules/wrap-ansi": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
+      "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-4.0.3.tgz",
+      "integrity": "sha512-JKhqTOwSrqNA1NY5lSztJ1GrBiUodLMmIZuLiDaMRJ+itFd+ABVE8XBjOvIWL+rSqNDC74LCSFmlb/U4UZ4hJQ==",
+      "license": "ISC"
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
@@ -2331,6 +2608,41 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/yargs": {
+      "version": "15.4.1",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-15.4.1.tgz",
+      "integrity": "sha512-aePbxDmcYW++PaqBsJ+HYUFwCdv4LVvdnhBy78E57PIor8/OVvhMrADFFEDh8DHDFRv/O9i3lPhsENjO7QX0+A==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^6.0.0",
+        "decamelize": "^1.2.0",
+        "find-up": "^4.1.0",
+        "get-caller-file": "^2.0.1",
+        "require-directory": "^2.1.1",
+        "require-main-filename": "^2.0.0",
+        "set-blocking": "^2.0.0",
+        "string-width": "^4.2.0",
+        "which-module": "^2.0.0",
+        "y18n": "^4.0.0",
+        "yargs-parser": "^18.1.2"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "18.1.3",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-18.1.3.tgz",
+      "integrity": "sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==",
+      "license": "ISC",
+      "dependencies": {
+        "camelcase": "^5.0.0",
+        "decamelize": "^1.2.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/zustand": {
       "version": "5.0.13",
       "resolved": "https://registry.npmjs.org/zustand/-/zustand-5.0.13.tgz",
@@ -2403,6 +2715,8 @@
       "version": "0.1.0",
       "dependencies": {
         "@passman/core": "*",
+        "@types/qrcode": "^1.5.6",
+        "qrcode": "^1.5.4",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "react-router-dom": "^6.28.0",
diff --git a/packages/web/package.json b/packages/web/package.json
index 1f49cd6..87f922e 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -13,6 +13,8 @@
   },
   "dependencies": {
     "@passman/core": "*",
+    "@types/qrcode": "^1.5.6",
+    "qrcode": "^1.5.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-router-dom": "^6.28.0",
diff --git a/packages/web/src/App.tsx b/packages/web/src/App.tsx
index 1aa226f..39000ab 100644
--- a/packages/web/src/App.tsx
+++ b/packages/web/src/App.tsx
@@ -2,6 +2,7 @@ import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";
 
 import { LoginPage } from "./pages/LoginPage.js";
 import { RegisterPage } from "./pages/RegisterPage.js";
+import { SettingsPage } from "./pages/SettingsPage.js";
 import { VaultPage } from "./pages/VaultPage.js";
 
 export function App() {
@@ -12,6 +13,7 @@ export function App() {
         <Route path="/login" element={<LoginPage />} />
         <Route path="/register" element={<RegisterPage />} />
         <Route path="/vault" element={<VaultPage />} />
+        <Route path="/settings" element={<SettingsPage />} />
       </Routes>
     </BrowserRouter>
   );
diff --git a/packages/web/src/api/client.ts b/packages/web/src/api/client.ts
index 7b5a0da..d96c3a6 100644
--- a/packages/web/src/api/client.ts
+++ b/packages/web/src/api/client.ts
@@ -39,6 +39,31 @@ export interface TokenPair {
   encrypted_symmetric_key: string;
 }
 
+/** `POST /sessions` returns this when the user has 2FA enabled — phase-1
+ *  only. The client must follow up with `POST /sessions/otp` carrying the
+ *  same `otp_token` plus a 6-digit code (or a recovery code). */
+export interface OtpChallenge {
+  requires_otp: true;
+  otp_token: string;
+  otp_expires_in: number;
+}
+
+export type LoginResponse = TokenPair | OtpChallenge;
+
+export function isOtpChallenge(r: LoginResponse): r is OtpChallenge {
+  return (r as OtpChallenge).requires_otp === true;
+}
+
+export interface TotpStatus {
+  enabled: boolean;
+  recovery_codes_remaining: number;
+}
+
+export interface TotpSetup {
+  provisioning_uri: string;
+  secret_base32: string;
+}
+
 export interface VaultItem {
   id: string;
   item_type: string;
@@ -83,11 +108,37 @@ export const api = {
     request<KdfLookup>(`/accounts/kdf?email=${encodeURIComponent(email)}`),
 
   login: (email: string, authKey: string) =>
-    request<TokenPair>("/sessions", {
+    request<LoginResponse>("/sessions", {
       method: "POST",
       body: JSON.stringify({ email, auth_key: authKey }),
     }),
 
+  loginOtp: (otpToken: string, code: string) =>
+    request<TokenPair>("/sessions/otp", {
+      method: "POST",
+      body: JSON.stringify({ otp_token: otpToken, code }),
+    }),
+
+  totpStatus: (token: string) =>
+    request<TotpStatus>("/account/totp/status", {}, token),
+
+  totpSetup: (token: string) =>
+    request<TotpSetup>("/account/totp/setup", { method: "POST" }, token),
+
+  totpConfirm: (token: string, code: string) =>
+    request<{ recovery_codes: string[] }>(
+      "/account/totp/confirm",
+      { method: "POST", body: JSON.stringify({ code }) },
+      token,
+    ),
+
+  totpDisable: (token: string, code: string) =>
+    request<void>(
+      "/account/totp/disable",
+      { method: "POST", body: JSON.stringify({ code }) },
+      token,
+    ),
+
   logout: (token: string, refreshToken: string) =>
     request<void>("/sessions", {
       method: "DELETE",
diff --git a/packages/web/src/pages/LoginPage.tsx b/packages/web/src/pages/LoginPage.tsx
index fae8116..dce0b7e 100644
--- a/packages/web/src/pages/LoginPage.tsx
+++ b/packages/web/src/pages/LoginPage.tsx
@@ -1,13 +1,33 @@
 import { useState } from "react";
 import { useNavigate } from "react-router-dom";
 
-import { deriveLoginAuthKey, unlock } from "@passman/core";
+import {
+  deriveLoginAuthKey,
+  unlock,
+  type KdfParams,
+  type VaultSession,
+} from "@passman/core";
 
-import { ApiError, api } from "../api/client.js";
+import { ApiError, api, isOtpChallenge, type TokenPair } from "../api/client.js";
 import { useBranding } from "../branding/index.js";
 import { useSession } from "../stores/session.js";
 import { BrandHeader } from "./vault/BrandHeader.js";
 
+/**
+ * Login is now two-step when the user has 2FA enabled.
+ *
+ * Step 1 stays the same: derive auth_key from email + master password,
+ * POST /sessions. The server replies with either a TokenPair (no 2FA) or
+ * an OtpChallenge (`requires_otp: true`).
+ *
+ * Step 2 only runs if we got a challenge: prompt the user for an
+ * authenticator code, POST /sessions/otp. We hold the master password +
+ * KDF params in component state across the two steps so the post-OTP
+ * `unlock` call can derive the symmetric key without re-prompting.
+ *
+ * The held password is wiped from state as soon as the vault key is
+ * derived (we set the session and clear local state in the same render).
+ */
 export function LoginPage() {
   const nav = useNavigate();
   const setSession = useSession((s) => s.setSession);
@@ -17,41 +37,41 @@ export function LoginPage() {
   const [error, setError] = useState<string | null>(null);
   const [busy, setBusy] = useState(false);
 
+  // Phase-2 carry: present only when the server replied with an OTP challenge.
+  const [pending, setPending] = useState<{
+    otpToken: string;
+    kdfParams: KdfParams;
+    password: string;
+  } | null>(null);
+  const [otpCode, setOtpCode] = useState("");
+
   async function onSubmit(e: React.FormEvent) {
     e.preventDefault();
     setError(null);
     setBusy(true);
     try {
-      // 1. Get KDF params (server returns decoy params for unknown emails;
-      //    we don't try to detect that here — the login attempt below will fail.)
       const kdf = await api.kdfLookup(email);
-      const kdfParams = {
+      const kdfParams: KdfParams = {
         salt: kdf.kdf_salt,
         timeCost: kdf.kdf_time_cost,
         memoryCost: kdf.kdf_memory_cost,
         parallelism: kdf.kdf_parallelism,
       };
-
-      // 2. Derive auth key client-side and authenticate.
       const authKey = await deriveLoginAuthKey(password, kdfParams);
-      const tokens = await api.login(email, authKey);
+      const resp = await api.login(email, authKey);
 
-      // 3. Decrypt the symmetric key with our master key (re-derived inside `unlock`).
-      const vault = await unlock(password, kdfParams, tokens.encrypted_symmetric_key);
+      if (isOtpChallenge(resp)) {
+        // Carry the master password forward — we still need it after OTP
+        // verification to derive the vault symmetric key.
+        setPending({ otpToken: resp.otp_token, kdfParams, password });
+        return;
+      }
 
-      setSession({
-        email,
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token,
-        vault,
-      });
-      nav("/vault");
+      await completeLogin(resp, kdfParams, password);
     } catch (e) {
       if (e instanceof ApiError && e.status === 401) {
         setError("Invalid email or password.");
       } else if (e instanceof Error && /tag/i.test(e.message)) {
-        // GCM tag mismatch on unlock = wrong password (server accepted us, but
-        // our master key can't decrypt the sym key — implies a corrupted record).
         setError("Vault decryption failed. Wrong password?");
       } else {
         setError("Login failed. Try again.");
@@ -61,13 +81,98 @@ export function LoginPage() {
     }
   }
 
+  async function onSubmitOtp(e: React.FormEvent) {
+    e.preventDefault();
+    if (!pending) return;
+    setError(null);
+    setBusy(true);
+    try {
+      const tokens = await api.loginOtp(pending.otpToken, otpCode.trim());
+      await completeLogin(tokens, pending.kdfParams, pending.password);
+    } catch (e) {
+      setError(
+        e instanceof ApiError && e.status === 401
+          ? "That code didn't match. Try again or use a recovery code."
+          : "Login failed. Try again.",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function completeLogin(
+    tokens: TokenPair,
+    kdfParams: KdfParams,
+    pw: string,
+  ): Promise<void> {
+    const vault: VaultSession = await unlock(
+      pw,
+      kdfParams,
+      tokens.encrypted_symmetric_key,
+    );
+    setSession({
+      email,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token,
+      vault,
+    });
+    setPending(null);
+    setOtpCode("");
+    setPassword("");
+    nav("/vault");
+  }
+
+  if (pending) {
+    return (
+      <main className="auth-container">
+        <BrandHeader />
+        <h1>Two-factor verification</h1>
+        <p className="auth-tagline">
+          Enter the 6-digit code from your authenticator app, or one of your
+          recovery codes.
+        </p>
+        <form onSubmit={onSubmitOtp}>
+          <label>
+            Authenticator code
+            <input
+              autoFocus
+              inputMode="numeric"
+              pattern="[0-9]*"
+              maxLength={10}
+              value={otpCode}
+              onChange={(e) => setOtpCode(e.target.value)}
+              placeholder="123456 or xxxx-xxxx"
+              autoComplete="one-time-code"
+              required
+            />
+          </label>
+          {error && <p className="error">{error}</p>}
+          <button type="submit" disabled={busy || otpCode.trim().length < 4}>
+            {busy ? "Verifying…" : "Continue"}
+          </button>
+        </form>
+        <p>
+          <button
+            type="button"
+            className="user-card-action"
+            onClick={() => {
+              setPending(null);
+              setOtpCode("");
+              setError(null);
+            }}
+          >
+            ← Start over
+          </button>
+        </p>
+      </main>
+    );
+  }
+
   return (
     <main className="auth-container">
       <BrandHeader />
       <h1>Unlock your vault</h1>
-      {branding.tagline && (
-        <p className="auth-tagline">{branding.tagline}</p>
-      )}
+      {branding.tagline && <p className="auth-tagline">{branding.tagline}</p>}
       <form onSubmit={onSubmit}>
         <label>
           Email
diff --git a/packages/web/src/pages/SettingsPage.tsx b/packages/web/src/pages/SettingsPage.tsx
new file mode 100644
index 0000000..6111b02
--- /dev/null
+++ b/packages/web/src/pages/SettingsPage.tsx
@@ -0,0 +1,227 @@
+import { useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { ApiError, api, type TotpStatus } from "../api/client.js";
+import { useBranding } from "../branding/index.js";
+import { useSession } from "../stores/session.js";
+import { TotpSetupFlow } from "./settings/TotpSetupFlow.js";
+import { BrandHeader } from "./vault/BrandHeader.js";
+
+/**
+ * Settings page — v1 hosts only the 2FA management flow. The page is
+ * intentionally simple: a single Security section with status + actions.
+ * As more settings land they slot in as additional sections.
+ */
+export function SettingsPage() {
+  const nav = useNavigate();
+  const branding = useBranding();
+  const { accessToken } = useSession();
+
+  const [status, setStatus] = useState<TotpStatus | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [setupOpen, setSetupOpen] = useState(false);
+  const [disableOpen, setDisableOpen] = useState(false);
+
+  useEffect(() => {
+    if (!accessToken) {
+      nav("/login");
+      return;
+    }
+    void refresh();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  async function refresh() {
+    if (!accessToken) return;
+    try {
+      const s = await api.totpStatus(accessToken);
+      setStatus(s);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to load 2FA status");
+    }
+  }
+
+  return (
+    <main className="auth-container settings-container">
+      <BrandHeader />
+      <h1>Settings</h1>
+      {branding.tagline && <p className="auth-tagline">{branding.tagline}</p>}
+
+      {error && <p className="error">{error}</p>}
+
+      <section className="settings-section">
+        <header>
+          <h2>Two-factor authentication</h2>
+          <p className="settings-section-hint">
+            Adds a 6-digit code from your authenticator app (Google Authenticator,
+            1Password, Authy, …) to login. <strong>Note:</strong> enabling 2FA
+            stores the OTP secret server-side. Vault contents stay encrypted
+            with your master key — the server still can't read them.
+          </p>
+        </header>
+
+        {status === null ? (
+          <p className="settings-loading">Loading…</p>
+        ) : status.enabled ? (
+          <TotpEnabledPanel
+            status={status}
+            onDisable={() => setDisableOpen(true)}
+          />
+        ) : (
+          <TotpDisabledPanel onSetup={() => setSetupOpen(true)} />
+        )}
+      </section>
+
+      <p className="settings-back">
+        <a href="/vault">← Back to vault</a>
+      </p>
+
+      {setupOpen && accessToken && (
+        <TotpSetupFlow
+          accessToken={accessToken}
+          onClose={() => setSetupOpen(false)}
+          onDone={async () => {
+            setSetupOpen(false);
+            await refresh();
+          }}
+        />
+      )}
+
+      {disableOpen && accessToken && (
+        <DisableTotpDialog
+          accessToken={accessToken}
+          onClose={() => setDisableOpen(false)}
+          onDone={async () => {
+            setDisableOpen(false);
+            await refresh();
+          }}
+        />
+      )}
+    </main>
+  );
+}
+
+function TotpDisabledPanel({ onSetup }: { onSetup: () => void }) {
+  return (
+    <div className="settings-row">
+      <div>
+        <div className="settings-status">
+          <span className="status-dot status-dot-off" /> Not enabled
+        </div>
+      </div>
+      <button type="button" className="btn btn-primary" onClick={onSetup}>
+        Set up 2FA
+      </button>
+    </div>
+  );
+}
+
+function TotpEnabledPanel({
+  status,
+  onDisable,
+}: {
+  status: TotpStatus;
+  onDisable: () => void;
+}) {
+  return (
+    <div className="settings-row">
+      <div>
+        <div className="settings-status">
+          <span className="status-dot status-dot-on" /> Enabled
+        </div>
+        <div className="settings-status-meta">
+          {status.recovery_codes_remaining} recovery code
+          {status.recovery_codes_remaining === 1 ? "" : "s"} remaining
+        </div>
+      </div>
+      <button type="button" className="btn" onClick={onDisable}>
+        Disable 2FA
+      </button>
+    </div>
+  );
+}
+
+function DisableTotpDialog({
+  accessToken,
+  onClose,
+  onDone,
+}: {
+  accessToken: string;
+  onClose: () => void;
+  onDone: () => void;
+}) {
+  const [code, setCode] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setErr(null);
+    try {
+      await api.totpDisable(accessToken, code.trim());
+      onDone();
+    } catch (e) {
+      setErr(
+        e instanceof ApiError && e.status === 401
+          ? "That code didn't match. Try again or use a recovery code."
+          : "Failed to disable 2FA",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div
+      className="modal-backdrop"
+      role="dialog"
+      aria-modal="true"
+      onClick={(e) => {
+        if (e.target === e.currentTarget && !busy) onClose();
+      }}
+    >
+      <div className="modal" onClick={(e) => e.stopPropagation()}>
+        <div className="modal-head">
+          <div>
+            <h2>Disable 2FA</h2>
+            <div className="target">
+              Confirm with a code from your authenticator app, or a recovery code.
+            </div>
+          </div>
+          <button className="x" onClick={onClose} disabled={busy} aria-label="Close">
+            ✕
+          </button>
+        </div>
+        <form className="modal-body" onSubmit={onSubmit}>
+          <label>
+            6-digit code or recovery code
+            <input
+              autoFocus
+              value={code}
+              onChange={(e) => setCode(e.target.value)}
+              placeholder="123456 or xxxx-xxxx"
+              autoComplete="one-time-code"
+              required
+            />
+          </label>
+          {err && <p className="error">{err}</p>}
+        </form>
+        <div className="modal-foot">
+          <span className="spacer" />
+          <button
+            type="button"
+            className="btn btn-primary"
+            disabled={busy || code.trim().length < 4}
+            onClick={(e) => void onSubmit(e as unknown as React.FormEvent)}
+          >
+            {busy ? "Disabling…" : "Disable 2FA"}
+          </button>
+          <button onClick={onClose} disabled={busy}>
+            Cancel
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/web/src/pages/settings/TotpSetupFlow.tsx b/packages/web/src/pages/settings/TotpSetupFlow.tsx
new file mode 100644
index 0000000..edb0ac0
--- /dev/null
+++ b/packages/web/src/pages/settings/TotpSetupFlow.tsx
@@ -0,0 +1,253 @@
+import { useEffect, useState } from "react";
+
+import { ApiError, api, type TotpSetup } from "../../api/client.js";
+import { copyPlain } from "../../connect/clipboard.js";
+import { formatSecretForDisplay, renderOtpauthQr } from "../../twofactor/index.js";
+
+interface Props {
+  accessToken: string;
+  onClose: () => void;
+  onDone: () => void;
+}
+
+type Step = "loading" | "scan" | "confirm" | "recovery";
+
+/**
+ * Three-step modal:
+ *   1. POST /account/totp/setup → render the QR + base32 fallback
+ *   2. User scans, types the first code → POST /confirm
+ *   3. Show recovery codes, prompt user to write them down, then close
+ *
+ * The user can't navigate back from step 3 — once we've shown the codes
+ * they're not recoverable from the server (only Argon2id hashes survive).
+ */
+export function TotpSetupFlow({ accessToken, onClose, onDone }: Props) {
+  const [step, setStep] = useState<Step>("loading");
+  const [setup, setSetup] = useState<TotpSetup | null>(null);
+  const [qrSvg, setQrSvg] = useState<string>("");
+  const [code, setCode] = useState("");
+  const [recoveryCodes, setRecoveryCodes] = useState<string[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+
+  // Fire the setup call once on mount.
+  useEffect(() => {
+    let cancelled = false;
+    async function go() {
+      try {
+        const s = await api.totpSetup(accessToken);
+        if (cancelled) return;
+        setSetup(s);
+        setQrSvg(await renderOtpauthQr(s.provisioning_uri));
+        setStep("scan");
+      } catch (e) {
+        if (cancelled) return;
+        setErr(
+          e instanceof ApiError && e.status === 401
+            ? "Your session expired. Please log in again."
+            : e instanceof Error
+              ? e.message
+              : "Failed to start 2FA setup",
+        );
+      }
+    }
+    void go();
+    return () => {
+      cancelled = true;
+    };
+  }, [accessToken]);
+
+  // Esc closes during the early steps; once codes are shown we force a
+  // deliberate "I've saved them" click.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && step !== "recovery" && !busy) onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose, step, busy]);
+
+  async function onConfirm(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setErr(null);
+    try {
+      const r = await api.totpConfirm(accessToken, code.trim());
+      setRecoveryCodes(r.recovery_codes);
+      setStep("recovery");
+    } catch (e) {
+      setErr(
+        e instanceof ApiError && e.status === 401
+          ? "That code didn't match — make sure your phone's clock is on time and try the next one."
+          : e instanceof Error
+            ? e.message
+            : "Failed to confirm code",
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function copyAllCodes() {
+    await copyPlain(recoveryCodes.join("\n"));
+  }
+
+  function downloadCodes() {
+    const blob = new Blob([recoveryCodes.join("\n") + "\n"], { type: "text/plain" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = "passman-recovery-codes.txt";
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  }
+
+  return (
+    <div
+      className="modal-backdrop"
+      role="dialog"
+      aria-modal="true"
+      onClick={(e) => {
+        if (e.target === e.currentTarget && step !== "recovery" && !busy) onClose();
+      }}
+    >
+      <div className="modal modal-wide" onClick={(e) => e.stopPropagation()}>
+        <div className="modal-head">
+          <div>
+            <h2>
+              {step === "recovery"
+                ? "Save your recovery codes"
+                : "Set up two-factor authentication"}
+            </h2>
+            <div className="target">
+              {step === "scan" && "Step 1 of 2 · Scan the QR with your authenticator"}
+              {step === "confirm" && "Step 2 of 2 · Enter a code to confirm"}
+              {step === "recovery" && "One-time only — store these somewhere safe"}
+            </div>
+          </div>
+          {step !== "recovery" && (
+            <button className="x" onClick={onClose} disabled={busy} aria-label="Close">
+              ✕
+            </button>
+          )}
+        </div>
+
+        <div className="modal-body">
+          {step === "loading" && <p className="settings-loading">Generating secret…</p>}
+
+          {step === "scan" && setup && (
+            <div className="totp-scan">
+              <div
+                className="totp-qr"
+                aria-label="QR code for your authenticator app"
+                dangerouslySetInnerHTML={{ __html: qrSvg }}
+              />
+              <div className="totp-scan-info">
+                <p className="settings-section-hint">
+                  Open Google Authenticator / 1Password / Authy / etc. and scan
+                  this code. Then click <strong>Next</strong>.
+                </p>
+                <details className="totp-manual">
+                  <summary>Can't scan? Type this manually</summary>
+                  <code className="totp-secret-display">
+                    {formatSecretForDisplay(setup.secret_base32)}
+                  </code>
+                  <button
+                    type="button"
+                    className="icon-btn"
+                    onClick={() => void copyPlain(setup.secret_base32)}
+                  >
+                    Copy
+                  </button>
+                </details>
+              </div>
+            </div>
+          )}
+
+          {step === "confirm" && (
+            <form className="totp-confirm" onSubmit={onConfirm}>
+              <label>
+                6-digit code from your authenticator
+                <input
+                  autoFocus
+                  inputMode="numeric"
+                  pattern="[0-9]*"
+                  maxLength={8}
+                  value={code}
+                  onChange={(e) => setCode(e.target.value)}
+                  placeholder="123456"
+                  autoComplete="one-time-code"
+                  required
+                />
+              </label>
+              {err && <p className="error">{err}</p>}
+            </form>
+          )}
+
+          {step === "recovery" && (
+            <div className="totp-recovery">
+              <p className="warning">
+                ⚠️ <strong>Save these codes now.</strong> Each one logs you in
+                once if you lose access to your authenticator app. They are
+                shown <strong>only this time</strong> — Passman keeps only a
+                hash on the server, so this list cannot be recovered later.
+              </p>
+              <div className="totp-recovery-grid">
+                {recoveryCodes.map((c, i) => (
+                  <code key={i} className="totp-recovery-code">
+                    {c}
+                  </code>
+                ))}
+              </div>
+              <div className="totp-recovery-actions">
+                <button type="button" className="btn" onClick={() => void copyAllCodes()}>
+                  Copy all
+                </button>
+                <button type="button" className="btn" onClick={downloadCodes}>
+                  Download as .txt
+                </button>
+              </div>
+            </div>
+          )}
+
+          {err && step !== "confirm" && <p className="error">{err}</p>}
+        </div>
+
+        <div className="modal-foot">
+          <span className="spacer" />
+          {step === "scan" && (
+            <button
+              type="button"
+              className="btn btn-primary"
+              onClick={() => setStep("confirm")}
+            >
+              Next →
+            </button>
+          )}
+          {step === "confirm" && (
+            <>
+              <button type="button" onClick={() => setStep("scan")} disabled={busy}>
+                ← Back
+              </button>
+              <button
+                type="button"
+                className="btn btn-primary"
+                disabled={busy || code.trim().length < 6}
+                onClick={(e) => void onConfirm(e as unknown as React.FormEvent)}
+              >
+                {busy ? "Confirming…" : "Confirm & enable 2FA"}
+              </button>
+            </>
+          )}
+          {step === "recovery" && (
+            <button type="button" className="btn btn-primary" onClick={onDone}>
+              I've saved them — finish
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/web/src/pages/vault/Sidebar.tsx b/packages/web/src/pages/vault/Sidebar.tsx
index 59f8bb1..a019b96 100644
--- a/packages/web/src/pages/vault/Sidebar.tsx
+++ b/packages/web/src/pages/vault/Sidebar.tsx
@@ -138,13 +138,17 @@ export function Sidebar({ email, items, scope, onScopeChange, onExport }: Props)
             {email ?? "Unknown"}
           </div>
           <small>
+            <a href="/settings" className="user-card-action">
+              Settings
+            </a>
+            {" · "}
             <button
               type="button"
               className="user-card-action"
               onClick={onExport}
               title="Download an encrypted JSON backup of your whole vault"
             >
-              Export backup
+              Export
             </button>
             {branding.supportEmail && (
               <>
diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css
index 8f7dfc5..2ab28a0 100644
--- a/packages/web/src/styles.css
+++ b/packages/web/src/styles.css
@@ -1400,6 +1400,146 @@ main.vault-main {
   font-family: var(--mono);
 }
 
+/* Settings page — single auth-container layout, slightly wider */
+main.settings-container {
+  max-width: 640px;
+}
+.settings-section {
+  margin-top: 1.5rem;
+  padding: 1.1rem 1.25rem 1.1rem;
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+}
+.settings-section header h2 {
+  margin: 0 0 0.3rem;
+  font-size: 1rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+.settings-section-hint {
+  color: var(--muted);
+  font-size: 0.83rem;
+  line-height: 1.5;
+  margin: 0 0 0.85rem;
+}
+.settings-section-hint strong { color: var(--fg-2); font-weight: 500; }
+.settings-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.65rem 0;
+}
+.settings-status {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+  font-weight: 500;
+  font-size: 0.92rem;
+}
+.settings-status-meta {
+  color: var(--muted);
+  font-size: 0.78rem;
+  margin-top: 0.2rem;
+}
+.settings-loading {
+  color: var(--muted);
+  font-size: 0.85rem;
+  margin: 0.4rem 0;
+}
+.settings-back { font-size: 0.85rem; margin-top: 1.5rem; }
+.settings-back a { color: var(--brand); }
+
+.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  display: inline-block;
+}
+.status-dot-on  { background: var(--brand); box-shadow: 0 0 8px var(--brand); }
+.status-dot-off { background: var(--muted-2); }
+
+/* Wider modal variant for the 2FA setup flow (QR + side-by-side text) */
+.modal.modal-wide { max-width: 600px; }
+
+.totp-scan {
+  display: flex;
+  gap: 1.2rem;
+  align-items: flex-start;
+}
+.totp-qr {
+  flex-shrink: 0;
+  display: grid;
+  place-items: center;
+  background: var(--bg-deep);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 0.5rem;
+}
+.totp-qr svg {
+  display: block;
+  width: 200px;
+  height: 200px;
+}
+.totp-scan-info { flex: 1; min-width: 0; }
+.totp-manual {
+  margin-top: 0.85rem;
+  font-size: 0.78rem;
+  color: var(--muted);
+}
+.totp-manual summary { cursor: pointer; padding: 0.3rem 0; }
+.totp-secret-display {
+  display: block;
+  background: var(--bg-deep);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 0.55rem 0.7rem;
+  font-family: var(--mono);
+  font-size: 0.85rem;
+  letter-spacing: 0.04em;
+  color: var(--fg);
+  margin: 0.4rem 0 0.4rem;
+  word-break: break-all;
+}
+
+.totp-confirm label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  font-size: 0.83rem;
+  color: var(--muted);
+}
+.totp-confirm input {
+  font-family: var(--mono);
+  font-size: 1.2rem;
+  letter-spacing: 0.18em;
+  text-align: center;
+}
+
+.totp-recovery {
+  display: flex;
+  flex-direction: column;
+  gap: 0.85rem;
+}
+.totp-recovery-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 0.45rem;
+}
+.totp-recovery-code {
+  font-family: var(--mono);
+  font-size: 0.92rem;
+  background: var(--bg-deep);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  padding: 0.5rem 0.7rem;
+  letter-spacing: 0.05em;
+  text-align: center;
+  color: var(--fg);
+}
+.totp-recovery-actions { display: flex; gap: 0.5rem; }
+
 /* Toast (clipboard copied / cleared) — slides up from bottom-right */
 .toast {
   position: fixed;
diff --git a/packages/web/src/twofactor/index.ts b/packages/web/src/twofactor/index.ts
new file mode 100644
index 0000000..d204885
--- /dev/null
+++ b/packages/web/src/twofactor/index.ts
@@ -0,0 +1 @@
+export { formatSecretForDisplay, renderOtpauthQr } from "./qrcode.js";
diff --git a/packages/web/src/twofactor/qrcode.ts b/packages/web/src/twofactor/qrcode.ts
new file mode 100644
index 0000000..59d298e
--- /dev/null
+++ b/packages/web/src/twofactor/qrcode.ts
@@ -0,0 +1,49 @@
+/**
+ * Tiny wrapper over the `qrcode` npm library that produces an SVG string
+ * for a given otpauth:// URI. Keeping this isolated lets us swap the
+ * library later (or hand-roll if bundle weight ever becomes an issue)
+ * without touching the React components.
+ */
+import qrcode from "qrcode";
+
+export interface QrOptions {
+  /** Pixel size of the rendered SVG. Default 240 — fits in the setup modal
+   *  without stretching, large enough for phone cameras. */
+  size?: number;
+}
+
+export async function renderOtpauthQr(
+  otpauthUri: string,
+  options: QrOptions = {},
+): Promise<string> {
+  const size = options.size ?? 240;
+  // The library's `toString` with type "svg" returns inline SVG markup —
+  // safe to inject via `dangerouslySetInnerHTML` because the input is a
+  // server-controlled string (the otpauth:// URI built from the user's
+  // own secret + email).
+  return qrcode.toString(otpauthUri, {
+    type: "svg",
+    margin: 1,
+    width: size,
+    color: {
+      // Match the design tokens — `--bg-deep` and `--brand` couldn't be
+      // resolved at runtime here, so we hard-code values. If the brand
+      // colour ever needs to flow into QR codes too, swap to a CSS-var
+      // resolver.
+      dark: "#3ECF8E",
+      light: "#0d0f10",
+    },
+  });
+}
+
+/** Format a base32 secret with spaces every 4 chars — easier to read aloud
+ *  or paste into apps that don't auto-strip spaces. */
+export function formatSecretForDisplay(secretBase32: string): string {
+  return (
+    secretBase32
+      .toUpperCase()
+      .replace(/\s+/g, "")
+      .match(/.{1,4}/g)
+      ?.join(" ") ?? secretBase32
+  );
+}
diff --git a/packages/web/tests/twofactor.test.ts b/packages/web/tests/twofactor.test.ts
new file mode 100644
index 0000000..6f2b9bf
--- /dev/null
+++ b/packages/web/tests/twofactor.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { isOtpChallenge } from "../src/api/client.js";
+import { formatSecretForDisplay } from "../src/twofactor/qrcode.js";
+
+describe("isOtpChallenge", () => {
+  it("returns true for the OtpChallenge shape", () => {
+    expect(
+      isOtpChallenge({
+        requires_otp: true,
+        otp_token: "x",
+        otp_expires_in: 300,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false for a TokenPair", () => {
+    expect(
+      isOtpChallenge({
+        access_token: "a",
+        refresh_token: "r",
+        access_expires_in: 900,
+        refresh_expires_in: 86400,
+        encrypted_symmetric_key: "v1:iv:ct",
+      } as unknown as ReturnType<typeof Object>),
+    ).toBe(false);
+  });
+});
+
+describe("formatSecretForDisplay", () => {
+  it("groups the base32 secret into readable 4-char blocks", () => {
+    expect(formatSecretForDisplay("JBSWY3DPEHPK3PXP")).toBe("JBSW Y3DP EHPK 3PXP");
+  });
+
+  it("uppercases and strips embedded whitespace", () => {
+    expect(formatSecretForDisplay("  jbswy3dp ehpk3pxp ")).toBe(
+      "JBSW Y3DP EHPK 3PXP",
+    );
+  });
+
+  it("returns the input unchanged for very short strings (no fallback split)", () => {
+    expect(formatSecretForDisplay("ABC")).toBe("ABC");
+  });
+});
diff --git a/server/alembic/env.py b/server/alembic/env.py
index deec220..75cb44e 100644
--- a/server/alembic/env.py
+++ b/server/alembic/env.py
@@ -4,13 +4,13 @@
 import asyncio
 from logging.config import fileConfig
 
-from alembic import context
 from sqlalchemy.engine import Connection
 from sqlalchemy.ext.asyncio import async_engine_from_config
 
+from alembic import context
+from passman import models  # noqa: F401 — register models with Base.metadata
 from passman.config import get_settings
 from passman.db import Base
-from passman import models  # noqa: F401 — register models with Base.metadata
 
 config = context.config
 if config.config_file_name is not None:
diff --git a/server/alembic/versions/0001_initial.py b/server/alembic/versions/0001_initial.py
index 20da741..0d188d3 100644
--- a/server/alembic/versions/0001_initial.py
+++ b/server/alembic/versions/0001_initial.py
@@ -8,9 +8,10 @@
 from __future__ import annotations
 
 import sqlalchemy as sa
-from alembic import op
 from sqlalchemy.dialects import postgresql
 
+from alembic import op
+
 revision = "0001_initial"
 down_revision = None
 branch_labels = None
diff --git a/server/alembic/versions/0002_totp.py b/server/alembic/versions/0002_totp.py
new file mode 100644
index 0000000..0a28676
--- /dev/null
+++ b/server/alembic/versions/0002_totp.py
@@ -0,0 +1,50 @@
+"""add TOTP columns to users
+
+Revision ID: 0002_totp
+Revises: 0001_initial
+Create Date: 2026-05-10
+
+Adds three columns to support optional Google Authenticator-style 2FA:
+  - totp_secret           BYTEA NULL — RFC 4226/6238 shared secret
+  - totp_enabled          BOOL NOT NULL DEFAULT false — flipped on confirm
+  - totp_recovery_hashes  TEXT NULL — JSON list of Argon2id-hashed codes
+
+NULL on existing rows = "no 2FA configured", which keeps the existing
+login flow unchanged for users who haven't opted in.
+"""
+from __future__ import annotations
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "0002_totp"
+down_revision = "0001_initial"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("totp_secret", sa.LargeBinary(), nullable=True),
+    )
+    op.add_column(
+        "users",
+        sa.Column(
+            "totp_enabled",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.false(),
+        ),
+    )
+    op.add_column(
+        "users",
+        sa.Column("totp_recovery_hashes", sa.Text(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "totp_recovery_hashes")
+    op.drop_column("users", "totp_enabled")
+    op.drop_column("users", "totp_secret")
diff --git a/server/src/passman/auth.py b/server/src/passman/auth.py
index 9de5a20..f50813b 100644
--- a/server/src/passman/auth.py
+++ b/server/src/passman/auth.py
@@ -168,6 +168,45 @@ def decode_access_token(token: str) -> dict[str, Any]:
     return payload
 
 
+# ---------------------------------------------------------------------------
+# OTP challenge tokens — short-lived (5 min) bearer between phase-1 (password)
+# and phase-2 (OTP) of two-step login. Carries no permissions; they only let
+# the holder POST /sessions/otp with their authenticator code.
+# ---------------------------------------------------------------------------
+
+OTP_CHALLENGE_TTL_SECONDS = 300
+
+
+def create_otp_challenge_token(user_id: str) -> tuple[str, int]:
+    """Return ``(token, ttl_seconds)`` for a phase-1 OTP challenge."""
+    settings = get_settings()
+    now = _utcnow()
+    payload = {
+        "sub": user_id,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(seconds=OTP_CHALLENGE_TTL_SECONDS)).timestamp()),
+        "jti": secrets.token_urlsafe(16),
+        "type": "otp_challenge",
+    }
+    token = jwt.encode(
+        payload, settings.jwt_secret.get_secret_value(), algorithm=settings.jwt_algorithm
+    )
+    return token, OTP_CHALLENGE_TTL_SECONDS
+
+
+def decode_otp_challenge_token(token: str) -> dict[str, Any]:
+    """Raise :class:`JWTError` on invalid/expired tokens or wrong type."""
+    settings = get_settings()
+    payload = jwt.decode(
+        token,
+        settings.jwt_secret.get_secret_value(),
+        algorithms=[settings.jwt_algorithm],
+    )
+    if payload.get("type") != "otp_challenge":
+        raise JWTError("Invalid token type")
+    return payload
+
+
 # ---------------------------------------------------------------------------
 # Refresh tokens (opaque random string + SHA-256 stored)
 # ---------------------------------------------------------------------------
diff --git a/server/src/passman/errors.py b/server/src/passman/errors.py
index a6799d3..57cb9f5 100644
--- a/server/src/passman/errors.py
+++ b/server/src/passman/errors.py
@@ -6,10 +6,10 @@
 
 
 class InvalidCredentialsError(HTTPException):
-    def __init__(self) -> None:
+    def __init__(self, message: str = "Invalid credentials") -> None:
         super().__init__(
             status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid credentials",
+            detail=message,
             headers={"WWW-Authenticate": "Bearer"},
         )
 
diff --git a/server/src/passman/main.py b/server/src/passman/main.py
index 52f892e..c91bfd4 100644
--- a/server/src/passman/main.py
+++ b/server/src/passman/main.py
@@ -15,7 +15,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 
 from .config import get_settings
-from .routers import accounts, sessions, vault
+from .routers import account, accounts, sessions, vault
 
 logger = logging.getLogger("passman")
 
@@ -49,6 +49,7 @@ def create_app() -> FastAPI:
     app.include_router(accounts.router)
     app.include_router(sessions.router)
     app.include_router(vault.router)
+    app.include_router(account.router)
 
     @app.get("/healthz", tags=["meta"])
     async def healthz() -> dict[str, str]:
diff --git a/server/src/passman/models.py b/server/src/passman/models.py
index 8b8e16b..74616dd 100644
--- a/server/src/passman/models.py
+++ b/server/src/passman/models.py
@@ -10,7 +10,7 @@
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import ForeignKey, Index, String, Text, UniqueConstraint
+from sqlalchemy import Boolean, ForeignKey, Index, LargeBinary, String, Text, UniqueConstraint
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -41,6 +41,27 @@ class User(Base, TimestampMixin):
     # Format: "v1:<base64 IV>:<base64 ciphertext+tag>"
     encrypted_symmetric_key: Mapped[str] = mapped_column(Text, nullable=False)
 
+    # ---------------- TOTP / 2FA -------------------------------------------
+    # NOTE: Enabling TOTP necessarily widens the trust model: the server now
+    # holds the per-user OTP secret. Vault contents remain zero-knowledge —
+    # those are still encrypted with the master key the server never sees —
+    # but login auth gains a second secret the server must protect at rest.
+    # A leak of the OTP secret alone does NOT enable vault decryption.
+    #
+    # `totp_secret` is the raw RFC 4226 / 6238 shared secret (typically 20
+    # random bytes). NULL until the user begins setup; remains NULL after
+    # confirmation if `totp_enabled` stays false.
+    totp_secret: Mapped[bytes | None] = mapped_column(LargeBinary, nullable=True)
+    # `totp_enabled` flips to true after the user confirms with a valid first
+    # code. Until then, the secret is provisional and login still works
+    # without OTP — protects users who started setup but never completed.
+    totp_enabled: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default="false"
+    )
+    # Argon2id-hashed single-use recovery codes (10 by default), JSON-encoded
+    # list of PHC strings. NULL when 2FA is disabled.
+    totp_recovery_hashes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
     # Relationships
     vault_items: Mapped[list[VaultItem]] = relationship(
         back_populates="user", cascade="all, delete-orphan", lazy="selectin"
diff --git a/server/src/passman/routers/account.py b/server/src/passman/routers/account.py
new file mode 100644
index 0000000..cd923fe
--- /dev/null
+++ b/server/src/passman/routers/account.py
@@ -0,0 +1,159 @@
+"""Per-account settings endpoints.
+
+Distinct from `accounts.py` (registration + pre-login KDF lookup):
+this router holds endpoints that act on the *currently signed-in*
+user. v1 contents: TOTP / 2FA management.
+
+Threat-model note for the TOTP endpoints
+----------------------------------------
+RFC 6238 verification requires the verifier to know the shared secret,
+so enabling 2FA puts a per-user OTP secret on the server. Vault
+contents stay zero-knowledge — those are still encrypted with the
+master key the server never sees — but login auth widens by one
+secret. Disabling 2FA requires a current OTP code (or recovery code),
+so a stolen access token alone can't downgrade the auth posture.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import cast
+
+from fastapi import APIRouter, status
+
+from ..config import get_settings
+from ..deps import CurrentUserDep, SessionDep
+from ..errors import InvalidCredentialsError
+from ..schemas import (
+    TotpConfirmRequest,
+    TotpConfirmResponse,
+    TotpDisableRequest,
+    TotpSetupResponse,
+    TotpStatusResponse,
+)
+from ..totp import (
+    build_provisioning_uri,
+    consume_recovery_code,
+    generate_recovery_codes,
+    generate_secret,
+    hash_recovery_codes,
+    verify,
+)
+
+router = APIRouter(prefix="/api/account", tags=["account"])
+
+
+def _issuer_for_provisioning() -> str:
+    """The issuer string embedded in `otpauth://...` URIs.
+
+    Showing the deployment hostname (when set) helps users distinguish
+    "Passman (work)" from "Passman (personal)" in their authenticator
+    app's list. Falls back to the literal "Passman" when no host is
+    configured (e.g. in dev).
+    """
+    settings = get_settings()
+    # `cors_origins` is the closest stable signal we have for "what URL
+    # do my users actually see?". Take the first https origin.
+    for origin in settings.cors_origins:
+        if origin.startswith("https://"):
+            return f"Passman ({origin.removeprefix('https://')})"
+    return "Passman"
+
+
+@router.get("/totp/status", response_model=TotpStatusResponse)
+async def totp_status(user: CurrentUserDep) -> TotpStatusResponse:
+    """Whether 2FA is enabled + how many recovery codes are left."""
+    remaining = 0
+    if user.totp_enabled and user.totp_recovery_hashes:
+        try:
+            remaining = len(json.loads(user.totp_recovery_hashes))
+        except (ValueError, TypeError):
+            remaining = 0
+    return TotpStatusResponse(enabled=user.totp_enabled, recovery_codes_remaining=remaining)
+
+
+@router.post(
+    "/totp/setup",
+    response_model=TotpSetupResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def totp_setup(user: CurrentUserDep, session: SessionDep) -> TotpSetupResponse:
+    """Generate a fresh provisional TOTP secret + QR provisioning URI.
+
+    Idempotent: calling this on a user who already started but didn't
+    finish setup overwrites the provisional secret. Calling it on a
+    user who has fully enabled 2FA is rejected with 400 — they must
+    disable first.
+    """
+    if user.totp_enabled:
+        raise InvalidCredentialsError("2FA is already enabled — disable it first to re-enrol")
+
+    secret = generate_secret()
+    user.totp_secret = secret
+    # Keep `totp_enabled` false until the user confirms with a code.
+    await session.flush()
+
+    return TotpSetupResponse(
+        provisioning_uri=build_provisioning_uri(
+            secret, account=user.email, issuer=_issuer_for_provisioning()
+        ),
+        secret_base32=__import__("base64").b32encode(secret).decode("ascii").rstrip("="),
+    )
+
+
+@router.post(
+    "/totp/confirm",
+    response_model=TotpConfirmResponse,
+)
+async def totp_confirm(
+    payload: TotpConfirmRequest, user: CurrentUserDep, session: SessionDep
+) -> TotpConfirmResponse:
+    """Confirm setup by submitting a code from the user's authenticator.
+
+    On success, flips `totp_enabled` to true and returns the plaintext
+    recovery codes — they're shown to the user exactly once. The server
+    persists only the Argon2id-hashed list.
+    """
+    if user.totp_enabled:
+        raise InvalidCredentialsError("2FA already enabled")
+    if user.totp_secret is None:
+        raise InvalidCredentialsError("Call /totp/setup first")
+    if not verify(user.totp_secret, payload.code):
+        raise InvalidCredentialsError("Invalid OTP code")
+
+    codes = generate_recovery_codes()
+    user.totp_recovery_hashes = hash_recovery_codes(codes)
+    user.totp_enabled = True
+    await session.flush()
+
+    return TotpConfirmResponse(recovery_codes=codes)
+
+
+@router.post("/totp/disable", status_code=status.HTTP_204_NO_CONTENT, response_model=None)
+async def totp_disable(
+    payload: TotpDisableRequest, user: CurrentUserDep, session: SessionDep
+) -> None:
+    """Disable 2FA. Requires a current OTP code OR a recovery code so a
+    stolen access token alone can't downgrade the auth posture."""
+    if not user.totp_enabled:
+        return  # idempotent: already disabled
+
+    secret = user.totp_secret
+    valid = False
+    if secret is not None and verify(secret, payload.code):
+        valid = True
+    elif user.totp_recovery_hashes:
+        matched, _remaining = consume_recovery_code(user.totp_recovery_hashes, payload.code)
+        valid = matched
+
+    if not valid:
+        raise InvalidCredentialsError("Invalid OTP or recovery code")
+
+    user.totp_secret = None
+    user.totp_enabled = False
+    user.totp_recovery_hashes = None
+    await session.flush()
+
+
+# Re-export so tests can import without round-tripping through this module.
+__all__ = ["router", "_issuer_for_provisioning", cast(str, "totp_status")]
diff --git a/server/src/passman/routers/sessions.py b/server/src/passman/routers/sessions.py
index 272e2cb..098f807 100644
--- a/server/src/passman/routers/sessions.py
+++ b/server/src/passman/routers/sessions.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import uuid
 from contextlib import suppress
 from datetime import UTC, datetime, timedelta
 
@@ -13,6 +14,8 @@
 from ..auth import (
     auth_hash_needs_rehash,
     create_access_token,
+    create_otp_challenge_token,
+    decode_otp_challenge_token,
     generate_refresh_token,
     hash_auth_key,
     hash_refresh_token,
@@ -23,7 +26,16 @@
 from ..errors import InvalidCredentialsError, InvalidTokenError
 from ..models import Session as SessionModel
 from ..models import User
-from ..schemas import LoginRequest, RefreshRequest, RefreshResponse, TokenPair
+from ..schemas import (
+    LoginRequest,
+    OtpChallengeResponse,
+    OtpLoginRequest,
+    RefreshRequest,
+    RefreshResponse,
+    TokenPair,
+)
+from ..totp import consume_recovery_code
+from ..totp import verify as verify_totp
 
 logger = logging.getLogger(__name__)
 
@@ -39,13 +51,45 @@ def _ensure_aware(dt: datetime) -> datetime:
     return dt if dt.tzinfo is not None else dt.replace(tzinfo=UTC)
 
 
-@router.post("", response_model=TokenPair, status_code=status.HTTP_201_CREATED)
+async def _issue_token_pair(
+    user: User, session: SessionDep, user_agent: str | None
+) -> TokenPair:
+    """Mint access + refresh, persist the session row. Shared by phase-1
+    (no-2FA users) and phase-2 (after-OTP) login paths."""
+    raw_refresh, refresh_hash, refresh_ttl = generate_refresh_token()
+    access_token, access_ttl = create_access_token(str(user.id))
+
+    db_session = SessionModel(
+        user_id=user.id,
+        refresh_token_hash=refresh_hash,
+        expires_at=_utcnow() + timedelta(seconds=refresh_ttl),
+        user_agent=(user_agent or "")[:255],
+    )
+    session.add(db_session)
+    await session.flush()
+
+    return TokenPair(
+        access_token=access_token,
+        refresh_token=raw_refresh,
+        access_expires_in=access_ttl,
+        refresh_expires_in=refresh_ttl,
+        encrypted_symmetric_key=user.encrypted_symmetric_key,
+    )
+
+
+@router.post(
+    "",
+    response_model=TokenPair | OtpChallengeResponse,
+    status_code=status.HTTP_201_CREATED,
+)
 async def login(
     payload: LoginRequest,
     session: SessionDep,
     user_agent: str | None = Header(default=None, alias="User-Agent"),
-) -> TokenPair:
-    """Verify the auth_key and issue access + refresh tokens.
+) -> TokenPair | OtpChallengeResponse:
+    """Verify the auth_key. If 2FA is on, return an OTP challenge token
+    instead of the full token pair — the client then POSTs `/sessions/otp`
+    with the same token + a code to complete login.
 
     The unknown-user branch runs :func:`verify_dummy_auth_key` so the wall-time
     matches the wrong-password branch — closing the timing oracle that would
@@ -76,25 +120,68 @@ async def login(
             # convert a legitimate login into a 5xx.
             logger.warning("auth_hash rehash failed for user_id=%s", user.id, exc_info=True)
 
-    raw_refresh, refresh_hash, refresh_ttl = generate_refresh_token()
-    access_token, access_ttl = create_access_token(str(user.id))
+    # 2FA gate — if enabled, hand back an OTP challenge token and stop.
+    if user.totp_enabled:
+        otp_token, otp_ttl = create_otp_challenge_token(str(user.id))
+        return OtpChallengeResponse(otp_token=otp_token, otp_expires_in=otp_ttl)
 
-    db_session = SessionModel(
-        user_id=user.id,
-        refresh_token_hash=refresh_hash,
-        expires_at=_utcnow() + timedelta(seconds=refresh_ttl),
-        user_agent=(user_agent or "")[:255],
-    )
-    session.add(db_session)
-    await session.flush()
+    return await _issue_token_pair(user, session, user_agent)
 
-    return TokenPair(
-        access_token=access_token,
-        refresh_token=raw_refresh,
-        access_expires_in=access_ttl,
-        refresh_expires_in=refresh_ttl,
-        encrypted_symmetric_key=user.encrypted_symmetric_key,
-    )
+
+@router.post(
+    "/otp",
+    response_model=TokenPair,
+    status_code=status.HTTP_201_CREATED,
+)
+async def login_otp(
+    payload: OtpLoginRequest,
+    session: SessionDep,
+    user_agent: str | None = Header(default=None, alias="User-Agent"),
+) -> TokenPair:
+    """Phase-2 of two-step login. Accepts the `otp_token` minted by
+    :func:`login` plus a 6-digit authenticator code OR a single-use
+    recovery code, then issues the full token pair.
+
+    The OTP path verifies against the stored `totp_secret`; the
+    recovery-code path verifies against the JSON-list of Argon2id-hashed
+    codes and atomically strips the consumed entry.
+    """
+    from jose import JWTError
+
+    try:
+        claims = decode_otp_challenge_token(payload.otp_token)
+    except JWTError as e:
+        raise InvalidTokenError("OTP challenge token invalid or expired") from e
+
+    user_id_raw = claims.get("sub")
+    if not user_id_raw:
+        raise InvalidTokenError("OTP challenge token malformed")
+    try:
+        user_id = uuid.UUID(user_id_raw)
+    except (ValueError, TypeError) as e:
+        raise InvalidTokenError("OTP challenge token malformed") from e
+
+    user = await session.get(User, user_id)
+    if user is None or not user.totp_enabled:
+        # If 2FA was disabled between phase-1 and phase-2, the challenge
+        # is meaningless; force a fresh login.
+        raise InvalidTokenError("OTP challenge token invalid or expired")
+
+    # Try the rolling TOTP code first — overwhelmingly the common path.
+    accepted = False
+    if user.totp_secret is not None and verify_totp(user.totp_secret, payload.code):
+        accepted = True
+    elif user.totp_recovery_hashes:
+        matched, remaining = consume_recovery_code(user.totp_recovery_hashes, payload.code)
+        if matched:
+            accepted = True
+            user.totp_recovery_hashes = remaining
+            await session.flush()
+
+    if not accepted:
+        raise InvalidCredentialsError("Invalid OTP code")
+
+    return await _issue_token_pair(user, session, user_agent)
 
 
 @router.post("/refresh", response_model=RefreshResponse)
diff --git a/server/src/passman/schemas.py b/server/src/passman/schemas.py
index ef5f059..f240930 100644
--- a/server/src/passman/schemas.py
+++ b/server/src/passman/schemas.py
@@ -95,6 +95,62 @@ class TokenPair(BaseModel):
     encrypted_symmetric_key: str
 
 
+class OtpChallengeResponse(BaseModel):
+    """Returned by ``POST /sessions`` when the user has 2FA enabled.
+
+    The client treats this as the signal to prompt for an authenticator
+    code, then POSTs to ``/sessions/otp`` with the same `otp_token` plus
+    the 6-digit code (or a recovery code).
+    """
+
+    requires_otp: Literal[True] = True
+    otp_token: str
+    otp_expires_in: int
+
+
+class OtpLoginRequest(BaseModel):
+    otp_token: str
+    # Allow both 6-digit codes and recovery codes (length up to 9 with the
+    # `xxxx-xxxx` formatting). Pydantic v2 lets us narrow further at runtime.
+    code: str = Field(min_length=4, max_length=32)
+
+
+# -- TOTP / 2FA management (all require an authenticated session) ---------
+
+
+class TotpSetupResponse(BaseModel):
+    """Returned by ``POST /account/totp/setup`` — the data the client needs
+    to render a QR code (`provisioning_uri`) and offer a manual fallback
+    (`secret_base32`). The secret is provisional until the user confirms
+    by submitting a valid code."""
+
+    provisioning_uri: str
+    secret_base32: str
+
+
+class TotpConfirmRequest(BaseModel):
+    code: str = Field(min_length=4, max_length=10)
+
+
+class TotpConfirmResponse(BaseModel):
+    """The plaintext recovery codes are returned exactly once. The server
+    persists only their Argon2id hashes."""
+
+    recovery_codes: list[str]
+
+
+class TotpDisableRequest(BaseModel):
+    """Disabling 2FA requires either a current OTP code or a recovery code,
+    so a stolen access token alone can't downgrade the auth posture."""
+
+    code: str = Field(min_length=4, max_length=32)
+
+
+class TotpStatusResponse(BaseModel):
+    enabled: bool
+    recovery_codes_remaining: int
+
+
 class RefreshRequest(BaseModel):
     refresh_token: str
 
diff --git a/server/src/passman/totp.py b/server/src/passman/totp.py
new file mode 100644
index 0000000..85e059a
--- /dev/null
+++ b/server/src/passman/totp.py
@@ -0,0 +1,189 @@
+"""TOTP (RFC 6238) + recovery-code utilities.
+
+Hand-rolled rather than pulling `pyotp` to keep the dependency surface
+minimal — the logic is ~50 lines of well-trodden, easily-audited code.
+
+Defaults match what every authenticator app expects out of the box:
+  - HMAC-SHA1
+  - 30-second period
+  - 6-digit codes
+  - ±1 window tolerance for clock skew
+"""
+
+from __future__ import annotations
+
+import base64
+import hmac
+import json
+import secrets
+import struct
+import time
+from collections.abc import Iterable
+from hashlib import sha1
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+# RFC 6238 §5.1: 20 bytes is the recommended secret size for HMAC-SHA1.
+SECRET_BYTES = 20
+PERIOD_SECONDS = 30
+DIGITS = 6
+# Number of recovery codes generated when 2FA is enabled. Industry norm is 8 to 10.
+RECOVERY_CODE_COUNT = 10
+# Codes are formatted as `xxxx-xxxx` (8 chars + dash) — readable + unambiguous.
+RECOVERY_CODE_BYTES = 5  # 5 bytes -> 8 base32 chars (no padding)
+
+# Argon2id is overkill for short alphanumeric codes but matches our
+# password-hashing posture and avoids a bcrypt dep.
+_recovery_hasher = PasswordHasher()
+
+
+def generate_secret() -> bytes:
+    """Generate a fresh CSPRNG-backed TOTP secret."""
+    return secrets.token_bytes(SECRET_BYTES)
+
+
+def secret_to_base32(secret: bytes) -> str:
+    """Encode the binary secret as the base32 form authenticator apps expect.
+
+    The QR code's `otpauth://` URL embeds this; manual-entry users type it.
+    """
+    # Most authenticator apps tolerate trailing `=` padding but the cleanest
+    # presentation is no padding — strip it.
+    return base64.b32encode(secret).decode("ascii").rstrip("=")
+
+
+def base32_to_secret(b32: str) -> bytes:
+    """Inverse of `secret_to_base32` — accepts strings with or without padding."""
+    s = b32.strip().replace(" ", "").upper()
+    # Re-add the `=` padding base64 module expects (b32 alphabet uses 8-char blocks).
+    pad_len = (-len(s)) % 8
+    return base64.b32decode(s + "=" * pad_len)
+
+
+def build_provisioning_uri(secret: bytes, account: str, issuer: str) -> str:
+    """Construct the standard `otpauth://totp/...?secret=...&issuer=...` URI.
+
+    Format defined at https://github.com/google/google-authenticator/wiki/Key-Uri-Format.
+    The label is `<issuer>:<account>` so phones group entries by issuer.
+    """
+    from urllib.parse import quote
+
+    label = f"{quote(issuer, safe='')}:{quote(account, safe='')}"
+    params = (
+        f"secret={secret_to_base32(secret)}"
+        f"&issuer={quote(issuer, safe='')}"
+        f"&algorithm=SHA1"
+        f"&digits={DIGITS}"
+        f"&period={PERIOD_SECONDS}"
+    )
+    return f"otpauth://totp/{label}?{params}"
+
+
+def _hotp(secret: bytes, counter: int, digits: int = DIGITS) -> str:
+    """RFC 4226 HOTP — the building block TOTP windows over."""
+    msg = struct.pack(">Q", counter)
+    digest = hmac.new(secret, msg, sha1).digest()
+    # Dynamic truncation per RFC 4226 §5.3.
+    offset = digest[-1] & 0x0F
+    code_int = (
+        ((digest[offset] & 0x7F) << 24)
+        | ((digest[offset + 1] & 0xFF) << 16)
+        | ((digest[offset + 2] & 0xFF) << 8)
+        | (digest[offset + 3] & 0xFF)
+    )
+    return str(code_int % (10**digits)).zfill(digits)
+
+
+def current_code(secret: bytes, at_time: float | None = None) -> str:
+    """Compute the TOTP code for `at_time` (defaults to now). Used by tests
+    and the docs example; production verification calls `verify` instead."""
+    t = at_time if at_time is not None else time.time()
+    return _hotp(secret, int(t // PERIOD_SECONDS))
+
+
+def verify(secret: bytes, code: str, at_time: float | None = None, window: int = 1) -> bool:
+    """Constant-time-ish verify of a 6-digit TOTP code against `secret`.
+
+    Accepts codes from the previous, current, and next window (the ±1
+    default) to tolerate clock skew up to ~30 seconds. Wider windows
+    weaken security; narrower ones break in practice.
+
+    Code is normalised — strips whitespace, dashes — so users pasting
+    "123 456" or "123-456" work. Non-digit codes are rejected.
+    """
+    cleaned = "".join(ch for ch in code if ch.isdigit())
+    if len(cleaned) != DIGITS:
+        return False
+    t = at_time if at_time is not None else time.time()
+    counter = int(t // PERIOD_SECONDS)
+    # `hmac.compare_digest` is the constant-time string compare the stdlib
+    # provides; we use it on each candidate to keep timing leakage minimal.
+    for offset in range(-window, window + 1):
+        expected = _hotp(secret, counter + offset)
+        if hmac.compare_digest(expected, cleaned):
+            return True
+    return False
+
+
+# ----- Recovery codes ---------------------------------------------------------
+
+
+def generate_recovery_codes(count: int = RECOVERY_CODE_COUNT) -> list[str]:
+    """Generate `count` single-use recovery codes formatted as `xxxx-xxxx`.
+
+    The plaintext list is returned to the caller exactly once; only the
+    Argon2id-hashed forms are persisted server-side. If the user loses
+    the printed list, they have to disable + re-enable 2FA.
+    """
+    out: list[str] = []
+    for _ in range(count):
+        # 5 random bytes → base32 → 8 chars. Split for readability.
+        raw = base64.b32encode(secrets.token_bytes(RECOVERY_CODE_BYTES)).decode("ascii").rstrip("=")
+        # Defensive — unlikely-but-possible padding edge cases.
+        raw = raw[:8].lower()
+        out.append(f"{raw[:4]}-{raw[4:]}")
+    return out
+
+
+def hash_recovery_codes(codes: Iterable[str]) -> str:
+    """Argon2id-hash each code and JSON-encode the resulting list. The
+    server stores this string; never the plaintext codes."""
+    hashes = [_recovery_hasher.hash(c.lower().strip()) for c in codes]
+    return json.dumps(hashes)
+
+
+def consume_recovery_code(stored_hashes_json: str, code: str) -> tuple[bool, str | None]:
+    """Try to redeem `code` against the stored hashes.
+
+    Returns `(matched, remaining_json)`:
+      - if matched, `remaining_json` is the new JSON list with the used
+        hash stripped (caller persists it back)
+      - if no match, `remaining_json` is None (caller leaves the column
+        unchanged — no information leak from a partial write)
+
+    Recovery codes are single-use by design, hence the strip-on-match.
+    """
+    try:
+        hashes: list[str] = json.loads(stored_hashes_json)
+    except (ValueError, TypeError):
+        return False, None
+    cleaned = code.lower().strip().replace(" ", "")
+    import logging
+
+    log = logging.getLogger(__name__)
+    for i, h in enumerate(hashes):
+        try:
+            if _recovery_hasher.verify(h, cleaned):
+                remaining = hashes[:i] + hashes[i + 1 :]
+                return True, json.dumps(remaining)
+        except VerifyMismatchError:
+            # Wrong code — try the next stored hash.
+            continue
+        except Exception:
+            # Argon2 raises a few non-VerifyMismatch errors for malformed
+            # hashes; we log + skip so a single corrupt entry doesn't lock
+            # out the user.
+            log.warning("recovery-code hash %d unparseable, skipping", i, exc_info=True)
+            continue
+    return False, None
diff --git a/server/tests/test_totp.py b/server/tests/test_totp.py
new file mode 100644
index 0000000..b2a69a2
--- /dev/null
+++ b/server/tests/test_totp.py
@@ -0,0 +1,339 @@
+"""Tests for the TOTP / 2FA pipeline.
+
+Covers three layers:
+  - The pure utilities in `passman.totp` (verify, recovery codes,
+    provisioning URI shape)
+  - The /api/account/totp/* endpoints (setup → confirm → status → disable)
+  - The two-step login flow (/api/sessions returning OtpChallenge,
+    /api/sessions/otp completing with a code or recovery code)
+"""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+
+from passman import totp
+
+from .conftest import make_register_payload
+
+# ---------------------------------------------------------------------------
+# Pure-function tests (no DB / no HTTP)
+# ---------------------------------------------------------------------------
+
+
+def test_generate_secret_is_20_bytes() -> None:
+    s = totp.generate_secret()
+    assert len(s) == 20
+    # Two consecutive calls must differ — CSPRNG, not a fixed value.
+    assert s != totp.generate_secret()
+
+
+def test_secret_round_trips_through_base32() -> None:
+    s = totp.generate_secret()
+    encoded = totp.secret_to_base32(s)
+    assert "=" not in encoded  # we strip padding for clean display
+    assert totp.base32_to_secret(encoded) == s
+
+
+def test_verify_accepts_current_window_and_rejects_wrong_codes() -> None:
+    s = totp.generate_secret()
+    code = totp.current_code(s)
+    assert totp.verify(s, code) is True
+    # The next 6-digit string (off by one) must not validate.
+    bad = str((int(code) + 1) % 1_000_000).zfill(6)
+    assert totp.verify(s, bad) is False
+
+
+def test_verify_tolerates_one_window_of_clock_skew() -> None:
+    s = totp.generate_secret()
+    now = time.time()
+    # The previous window's code should still verify.
+    prev = totp.current_code(s, at_time=now - totp.PERIOD_SECONDS)
+    assert totp.verify(s, prev, at_time=now) is True
+
+
+def test_verify_rejects_two_windows_of_skew() -> None:
+    s = totp.generate_secret()
+    now = time.time()
+    way_old = totp.current_code(s, at_time=now - 3 * totp.PERIOD_SECONDS)
+    assert totp.verify(s, way_old, at_time=now) is False
+
+
+def test_verify_strips_whitespace_and_dashes() -> None:
+    s = totp.generate_secret()
+    code = totp.current_code(s)
+    formatted = f"{code[:3]} {code[3:]}"
+    assert totp.verify(s, formatted) is True
+
+
+def test_verify_rejects_non_digit_codes() -> None:
+    s = totp.generate_secret()
+    assert totp.verify(s, "abcdef") is False
+    assert totp.verify(s, "") is False
+
+
+def test_provisioning_uri_has_required_params() -> None:
+    s = totp.generate_secret()
+    uri = totp.build_provisioning_uri(s, account="alice@example.com", issuer="Passman")
+    assert uri.startswith("otpauth://totp/")
+    assert "secret=" in uri
+    assert "issuer=Passman" in uri
+    assert "algorithm=SHA1" in uri
+    assert "digits=6" in uri
+    assert "period=30" in uri
+    # Label is `<issuer>:<account>` URL-encoded.
+    assert "Passman:alice%40example.com" in uri
+
+
+def test_recovery_codes_are_unique_and_correctly_shaped() -> None:
+    codes = totp.generate_recovery_codes(count=10)
+    assert len(codes) == 10
+    assert len(set(codes)) == 10  # no duplicates
+    for c in codes:
+        assert len(c) == 9  # xxxx-xxxx
+        assert c[4] == "-"
+
+
+def test_recovery_codes_consume_once() -> None:
+    codes = totp.generate_recovery_codes(count=3)
+    stored = totp.hash_recovery_codes(codes)
+    matched, remaining = totp.consume_recovery_code(stored, codes[1])
+    assert matched is True
+    assert remaining is not None
+    # Same code can't be reused.
+    matched_again, _ = totp.consume_recovery_code(remaining, codes[1])
+    assert matched_again is False
+    # The other codes still work.
+    matched_other, _ = totp.consume_recovery_code(remaining, codes[0])
+    assert matched_other is True
+
+
+def test_recovery_codes_reject_garbage_input() -> None:
+    codes = totp.generate_recovery_codes(count=2)
+    stored = totp.hash_recovery_codes(codes)
+    matched, remaining = totp.consume_recovery_code(stored, "not-a-real-code")
+    assert matched is False
+    assert remaining is None
+
+
+# ---------------------------------------------------------------------------
+# /api/account/totp/* endpoint tests
+# ---------------------------------------------------------------------------
+
+
+async def _register_and_login(client, email: str):  # type: ignore[no-untyped-def]
+    reg = make_register_payload(email)
+    r = await client.post("/api/accounts/register", json=reg)
+    assert r.status_code == 201, r.text
+    login = await client.post(
+        "/api/sessions",
+        json={"email": email, "auth_key": reg["auth_key"]},
+    )
+    assert login.status_code == 201, login.text
+    return reg, login.json()["access_token"]
+
+
+async def _setup_and_confirm_totp(client, access_token: str):  # type: ignore[no-untyped-def]
+    """End-to-end helper: setup → confirm with the actual current code.
+    Returns the secret bytes + the recovery codes so tests can use them."""
+    setup = await client.post(
+        "/api/account/totp/setup",
+        headers={"Authorization": f"Bearer {access_token}"},
+    )
+    assert setup.status_code == 201, setup.text
+    body = setup.json()
+    secret = totp.base32_to_secret(body["secret_base32"])
+    code = totp.current_code(secret)
+    confirm = await client.post(
+        "/api/account/totp/confirm",
+        json={"code": code},
+        headers={"Authorization": f"Bearer {access_token}"},
+    )
+    assert confirm.status_code == 200, confirm.text
+    return secret, confirm.json()["recovery_codes"]
+
+
+@pytest.mark.asyncio
+async def test_totp_setup_returns_provisioning_uri_and_secret(client) -> None:  # type: ignore[no-untyped-def]
+    _reg, token = await _register_and_login(client, "totp1@example.com")
+    resp = await client.post(
+        "/api/account/totp/setup",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["provisioning_uri"].startswith("otpauth://totp/")
+    assert body["secret_base32"]
+
+
+@pytest.mark.asyncio
+async def test_totp_confirm_with_valid_code_enables_2fa_and_returns_recovery_codes(client) -> None:  # type: ignore[no-untyped-def]
+    _reg, token = await _register_and_login(client, "totp2@example.com")
+    _secret, codes = await _setup_and_confirm_totp(client, token)
+    assert len(codes) == 10
+    # Status now reports enabled.
+    status_resp = await client.get(
+        "/api/account/totp/status",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    body = status_resp.json()
+    assert body["enabled"] is True
+    assert body["recovery_codes_remaining"] == 10
+
+
+@pytest.mark.asyncio
+async def test_totp_confirm_with_wrong_code_rejects(client) -> None:  # type: ignore[no-untyped-def]
+    _reg, token = await _register_and_login(client, "totp3@example.com")
+    setup = await client.post(
+        "/api/account/totp/setup",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert setup.status_code == 201
+    bad = await client.post(
+        "/api/account/totp/confirm",
+        json={"code": "000000"},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert bad.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_totp_disable_requires_valid_code(client) -> None:  # type: ignore[no-untyped-def]
+    _reg, token = await _register_and_login(client, "totp4@example.com")
+    secret, _codes = await _setup_and_confirm_totp(client, token)
+
+    # Wrong code rejected.
+    bad = await client.post(
+        "/api/account/totp/disable",
+        json={"code": "000000"},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert bad.status_code == 401
+
+    # Correct current code accepted.
+    code = totp.current_code(secret)
+    ok = await client.post(
+        "/api/account/totp/disable",
+        json={"code": code},
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert ok.status_code == 204
+    status_resp = await client.get(
+        "/api/account/totp/status",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert status_resp.json()["enabled"] is False
+
+
+# ---------------------------------------------------------------------------
+# Two-step login flow
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_login_returns_otp_challenge_when_2fa_enabled(client) -> None:  # type: ignore[no-untyped-def]
+    reg, token = await _register_and_login(client, "twostep1@example.com")
+    await _setup_and_confirm_totp(client, token)
+
+    resp = await client.post(
+        "/api/sessions",
+        json={"email": reg["email"], "auth_key": reg["auth_key"]},
+    )
+    # Login responds 201 — it's still a "success" — but with the challenge shape.
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body.get("requires_otp") is True
+    assert body["otp_token"]
+    assert body["otp_expires_in"] > 0
+    # The full token-pair fields must NOT be present yet.
+    assert "access_token" not in body
+
+
+@pytest.mark.asyncio
+async def test_login_otp_with_valid_code_returns_token_pair(client) -> None:  # type: ignore[no-untyped-def]
+    reg, token = await _register_and_login(client, "twostep2@example.com")
+    secret, _codes = await _setup_and_confirm_totp(client, token)
+
+    challenge_resp = await client.post(
+        "/api/sessions",
+        json={"email": reg["email"], "auth_key": reg["auth_key"]},
+    )
+    otp_token = challenge_resp.json()["otp_token"]
+
+    code = totp.current_code(secret)
+    resp = await client.post(
+        "/api/sessions/otp",
+        json={"otp_token": otp_token, "code": code},
+    )
+    assert resp.status_code == 201, resp.text
+    body = resp.json()
+    assert body["access_token"]
+    assert body["refresh_token"]
+    assert body["encrypted_symmetric_key"]
+
+
+@pytest.mark.asyncio
+async def test_login_otp_with_wrong_code_rejects(client) -> None:  # type: ignore[no-untyped-def]
+    reg, token = await _register_and_login(client, "twostep3@example.com")
+    await _setup_and_confirm_totp(client, token)
+
+    challenge = await client.post(
+        "/api/sessions",
+        json={"email": reg["email"], "auth_key": reg["auth_key"]},
+    )
+    otp_token = challenge.json()["otp_token"]
+
+    resp = await client.post(
+        "/api/sessions/otp",
+        json={"otp_token": otp_token, "code": "000000"},
+    )
+    assert resp.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_login_otp_with_recovery_code_succeeds_and_consumes(client) -> None:  # type: ignore[no-untyped-def]
+    reg, token = await _register_and_login(client, "twostep4@example.com")
+    _secret, codes = await _setup_and_confirm_totp(client, token)
+    one_code = codes[0]
+
+    challenge = await client.post(
+        "/api/sessions",
+        json={"email": reg["email"], "auth_key": reg["auth_key"]},
+    )
+    otp_token = challenge.json()["otp_token"]
+
+    ok = await client.post(
+        "/api/sessions/otp",
+        json={"otp_token": otp_token, "code": one_code},
+    )
+    assert ok.status_code == 201, ok.text
+
+    # Recovery codes are single-use — second attempt with the same code fails.
+    challenge2 = await client.post(
+        "/api/sessions",
+        json={"email": reg["email"], "auth_key": reg["auth_key"]},
+    )
+    otp_token2 = challenge2.json()["otp_token"]
+    reused = await client.post(
+        "/api/sessions/otp",
+        json={"otp_token": otp_token2, "code": one_code},
+    )
+    assert reused.status_code == 401
+
+    # Status reflects that one was used.
+    status_resp = await client.get(
+        "/api/account/totp/status",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    assert status_resp.json()["recovery_codes_remaining"] == 9
+
+
+@pytest.mark.asyncio
+async def test_login_otp_with_bad_token_rejects(client) -> None:  # type: ignore[no-untyped-def]
+    resp = await client.post(
+        "/api/sessions/otp",
+        json={"otp_token": "not-a-jwt", "code": "123456"},
+    )
+    assert resp.status_code == 401