feat(auth): trusted devices, recovery codes, and admin MFA management

Add opt-in "Trust this device" so a browser/app skips the TOTP step (never
the password) for 30 days, single-use bcrypt recovery codes as a 2FA-lockout
fallback, and admin trusted-device/MFA-reset management — backend, web UI,
OpenAPI spec, and tests.

- Schema: trusted_devices (sha256 token hash, looked up by unique index) and
  recovery_codes (bcrypt, single-use). Both additive/idempotent.
- Session service: trust-token mint/hash/resolve + cap helpers; new rg_trust
  httpOnly cookie (survives logout, revoked on untrust/password change/reset/
  TOTP disable). JWTs stay stateless — trust is a server-side row, not a claim.
- Web + mobile login accept a trusted-device token / recovery code; login/totp
  gains trustDevice + recoveryCode. Cap of 10/user with NO silent pruning — an
  over-cap trust returns 409/trustLimitReached and the client prompts to revoke.
- Self-service /auth/me/trusted-devices* + recovery-codes*; admin
  /admin/users/:id/trusted-devices* + /mfa/reset. All actions audit-logged.
- Client: "Trust this device" + recovery-code login options, one-time recovery
  code display, Trusted Devices + Recovery Codes account panels, a TOTP-styled
  revoke-to-continue cap modal, and admin per-user security controls.
- OpenAPI regenerated; 33 new server tests (all suites green).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/src/model/recoveryCodes/recoveryCodes.db.js

@@ -0,0 +1,63 @@
+const { query } = require('../../utils/db')
+
+// SQL for the recovery_codes table. Each row is one bcrypt-hashed, single-use
+// backup code. The raw codes are shown to the user exactly once at generation and
+// never stored in the clear.
+
+// Bulk-insert freshly generated code hashes for a user. `hashes` is an array of
+// bcrypt strings. One multi-row INSERT keeps generation atomic-ish and cheap.
+async function insertMany(userId, hashes) {
+  if (!hashes || hashes.length === 0) return 0
+  const values = hashes.map(() => '(?, ?)').join(', ')
+  const params = []
+  for (const h of hashes) params.push(userId, h)
+  const res = await query(
+    `INSERT INTO recovery_codes (user_id, code_hash) VALUES ${values}`,
+    params,
+  )
+  return Number(res.affectedRows || 0)
+}
+
+// All not-yet-used codes for a user (hashes included — this is the verify path,
+// server-side only). Ordered by id so verification is deterministic.
+async function listUnusedForUser(userId) {
+  return query(
+    'SELECT id, code_hash FROM recovery_codes WHERE user_id = ? AND used_at IS NULL ORDER BY id',
+    [userId],
+  )
+}
+
+// Count a user's remaining (unused) codes — for the status endpoint (never the
+// codes themselves).
+async function countUnusedForUser(userId) {
+  const rows = await query(
+    'SELECT COUNT(*) AS n FROM recovery_codes WHERE user_id = ? AND used_at IS NULL',
+    [userId],
+  )
+  return Number(rows[0]?.n || 0)
+}
+
+// Mark one code row used (single-use). Guarded on used_at IS NULL so a race can
+// only consume it once. Returns rows changed.
+async function markUsed(id) {
+  const res = await query(
+    'UPDATE recovery_codes SET used_at = NOW() WHERE id = ? AND used_at IS NULL',
+    [id],
+  )
+  return Number(res.affectedRows || 0)
+}
+
+// Delete every code for a user. Used both when regenerating (replace the set) and
+// on TOTP disable / password change/reset. Returns rows removed.
+async function deleteAllForUser(userId) {
+  const res = await query('DELETE FROM recovery_codes WHERE user_id = ?', [userId])
+  return Number(res.affectedRows || 0)
+}
+
+module.exports = {
+  insertMany,
+  listUnusedForUser,
+  countUnusedForUser,
+  markUsed,
+  deleteAllForUser,
+}

server/src/model/recoveryCodes/recoveryCodes.model.js

@@ -0,0 +1,86 @@
+// Recovery (backup) code store. Logic layer over recoveryCodes.db, doing the
+// bcrypt hashing itself — the same pattern as users.model hashing passwords (a
+// recovery code is a human-typed, lower-entropy fallback credential, so bcrypt,
+// not sha256; see docs/website/TRUSTED_DEVICES_MFA.md §3). Codes are generated in
+// batches, shown to the user once, and consumed single-use at login.
+
+const crypto = require('crypto')
+const bcrypt = require('bcryptjs')
+
+const db = require('./recoveryCodes.db')
+
+const SALT_ROUNDS = 10
+const CODE_COUNT = Number(process.env.RECOVERY_CODE_COUNT) || 10
+// 10 chars from a 32-symbol alphabet ≈ 50 bits of entropy per code. Crockford-ish
+// base32 minus visually ambiguous glyphs (no I, L, O, U) to keep hand-entry clean.
+const ALPHABET = '23456789ABCDEFGHJKMNPQRSTVWXYZ'
+const CODE_LEN = 10
+
+// Canonical form used for hashing + comparison: uppercase, alphanumerics only.
+// Display adds a dash for readability; input is normalized back to this before
+// bcrypt.compare so 'abcde-fghij', 'ABCDEFGHIJ', etc. all verify.
+function normalize(code) {
+  return String(code || '').toUpperCase().replace(/[^0-9A-Z]/g, '')
+}
+
+// One random code in canonical form (no separator).
+function generateCode() {
+  const bytes = crypto.randomBytes(CODE_LEN)
+  let out = ''
+  for (let i = 0; i < CODE_LEN; i++) out += ALPHABET[bytes[i] % ALPHABET.length]
+  return out
+}
+
+// Present a canonical code to the user with a mid-string dash (display only).
+function formatForDisplay(code) {
+  const mid = Math.floor(code.length / 2)
+  return `${code.slice(0, mid)}-${code.slice(mid)}`
+}
+
+// Generate a fresh batch, REPLACING any existing codes for the user (regeneration
+// invalidates the old set). Returns the plaintext codes for one-time display — the
+// only time they exist outside the user's hands.
+async function generateForUser(userId, count = CODE_COUNT) {
+  const plain = Array.from({ length: count }, generateCode)
+  const hashes = await Promise.all(plain.map((c) => bcrypt.hash(c, SALT_ROUNDS)))
+  await db.deleteAllForUser(userId)
+  await db.insertMany(userId, hashes)
+  return plain.map(formatForDisplay)
+}
+
+// Verify + consume a recovery code (single-use). Normalizes input, bcrypt-compares
+// against the user's unused codes, and marks the first match used. Returns true iff
+// a code was consumed. Timing is dominated by bcrypt regardless of match position.
+async function consumeForUser(userId, rawCode) {
+  const candidate = normalize(rawCode)
+  if (!candidate) return false
+  const rows = await db.listUnusedForUser(userId)
+  for (const row of rows) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await bcrypt.compare(candidate, row.code_hash)) {
+      // eslint-disable-next-line no-await-in-loop
+      const changed = await db.markUsed(row.id)
+      return changed > 0 // lost the race to consume this exact code → treat as fail
+    }
+  }
+  return false
+}
+
+// Remaining (unused) code count — for the status endpoint. Never returns codes.
+async function remainingForUser(userId) {
+  return db.countUnusedForUser(userId)
+}
+
+// Clear every code for a user (TOTP disable / password change/reset).
+async function clearForUser(userId) {
+  return db.deleteAllForUser(userId)
+}
+
+module.exports = {
+  CODE_COUNT,
+  normalize,
+  generateForUser,
+  consumeForUser,
+  remainingForUser,
+  clearForUser,
+}