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/trustedDevices/trustedDevices.db.js

@@ -0,0 +1,103 @@
+const { query } = require('../../utils/db')
+
+// SQL for the trusted_devices table. The opaque trust token lives client-side; the
+// DB stores only its sha256 hash (token_hash). Mirrors mobileSessions.db — a
+// trusted device is the MFA analogue of a live session: it lets a login skip the
+// TOTP step, and is revocable per-row.
+
+// Insert a new trusted-device row. expiresAt is a JS Date (or ms epoch). last_used_at
+// is seeded to now (the device was just trusted at a successful login).
+async function insert({ userId, tokenHash, platform = 'web', deviceName = null, deviceHash = null, userAgent = null, expiresAt }) {
+  const res = await query(
+    `INSERT INTO trusted_devices (user_id, token_hash, platform, device_name, device_hash, user_agent, expires_at, last_used_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, NOW())`,
+    [userId, tokenHash, platform, deviceName, deviceHash, userAgent, new Date(expiresAt)],
+  )
+  return res.insertId
+}
+
+// Look up a trusted device by token hash only if it is still usable: not revoked
+// and not past expiry. Returns the row (incl. user_id) or null. Used by the login
+// path to decide whether TOTP can be skipped.
+async function findValidByHash(tokenHash) {
+  const rows = await query(
+    `SELECT * FROM trusted_devices
+     WHERE token_hash = ? AND revoked_at IS NULL AND expires_at > NOW()
+     LIMIT 1`,
+    [tokenHash],
+  )
+  return rows[0] || null
+}
+
+// Stamp last_used_at when a device's trust is honored at login. Idempotent.
+async function touchLastUsed(id) {
+  const res = await query(
+    'UPDATE trusted_devices SET last_used_at = NOW() WHERE id = ?',
+    [id],
+  )
+  return Number(res.affectedRows || 0)
+}
+
+// List a user's currently-active (unrevoked, unexpired) trusted devices — newest
+// first. Never returns the token hash. Powers the self-service "Trusted Devices"
+// list and the admin per-user view. Works for any user id (self or admin target).
+async function listActiveForUser(userId) {
+  return query(
+    `SELECT id, platform, device_name, device_hash, user_agent, created_at, last_used_at, expires_at
+       FROM trusted_devices
+      WHERE user_id = ? AND revoked_at IS NULL AND expires_at > NOW()
+      ORDER BY last_used_at DESC, created_at DESC`,
+    [userId],
+  )
+}
+
+// Count a user's currently-active trusted devices. Used to enforce the per-user cap
+// (no silent pruning — the caller refuses an over-cap insert instead).
+async function countActiveForUser(userId) {
+  const rows = await query(
+    'SELECT COUNT(*) AS n FROM trusted_devices WHERE user_id = ? AND revoked_at IS NULL AND expires_at > NOW()',
+    [userId],
+  )
+  return Number(rows[0]?.n || 0)
+}
+
+// Revoke one of a user's trusted devices by row id (ownership-scoped, so both self
+// and admin-for-target go through the same guarded query). Idempotent; returns
+// rows changed.
+async function revokeByIdForUser(id, userId) {
+  const res = await query(
+    'UPDATE trusted_devices SET revoked_at = NOW() WHERE id = ? AND user_id = ? AND revoked_at IS NULL',
+    [id, userId],
+  )
+  return Number(res.affectedRows || 0)
+}
+
+// Revoke every active trusted device for a user ("untrust everywhere", and the
+// invalidation hook on password change/reset / TOTP disable). Returns rows changed.
+async function revokeAllForUser(userId) {
+  const res = await query(
+    'UPDATE trusted_devices SET revoked_at = NOW() WHERE user_id = ? AND revoked_at IS NULL',
+    [userId],
+  )
+  return Number(res.affectedRows || 0)
+}
+
+// Housekeeping: delete rows that are long dead (expired or revoked). Returns rows
+// removed. Same opportunistic-prune approach as mobile_refresh_tokens.
+async function pruneExpired() {
+  const res = await query(
+    'DELETE FROM trusted_devices WHERE expires_at < NOW() OR revoked_at IS NOT NULL',
+  )
+  return Number(res.affectedRows || 0)
+}
+
+module.exports = {
+  insert,
+  findValidByHash,
+  touchLastUsed,
+  listActiveForUser,
+  countActiveForUser,
+  revokeByIdForUser,
+  revokeAllForUser,
+  pruneExpired,
+}

server/src/model/trustedDevices/trustedDevices.model.js

@@ -0,0 +1,69 @@
+// Trusted-device store. Thin logic layer over trustedDevices.db — mirrors the
+// mobileSessions model split (.db = SQL, .model = the API the rest of the app
+// calls). The opaque trust token lives client-side; only its sha256 hash is
+// persisted (hashing is done by the session service so caller + store agree, the
+// same seam as mobile refresh tokens).
+
+const db = require('./trustedDevices.db')
+
+// Max active trusted devices per user. Enforced by assertUnderCap (no silent
+// pruning — an over-cap trust attempt is refused so the client can prompt the user
+// to revoke one first). See docs/website/TRUSTED_DEVICES_MFA.md §5.
+const MAX_TRUSTED_DEVICES = Number(process.env.MAX_TRUSTED_DEVICES) || 10
+
+// Persist a newly trusted device (by token hash). Returns the row id.
+async function store({ userId, tokenHash, platform, deviceName, deviceHash, userAgent, expiresAt }) {
+  return db.insert({ userId, tokenHash, platform, deviceName, deviceHash, userAgent, expiresAt })
+}
+
+// Return the stored row for a still-valid (unrevoked, unexpired) trust token, else
+// null. Used by the login path to decide whether the TOTP step can be skipped.
+async function findValidByHash(tokenHash) {
+  return db.findValidByHash(tokenHash)
+}
+
+// Stamp last_used_at when a device's trust is honored at login.
+async function touchLastUsed(id) {
+  return db.touchLastUsed(id)
+}
+
+// List a user's active trusted devices (self-service list + admin per-user view).
+async function listActiveForUser(userId) {
+  return db.listActiveForUser(userId)
+}
+
+// True if the user is at/over the trusted-device cap. Callers refuse the insert and
+// signal the client to revoke one first, rather than pruning silently.
+async function isAtCap(userId) {
+  const n = await db.countActiveForUser(userId)
+  return n >= MAX_TRUSTED_DEVICES
+}
+
+// Revoke one of a user's trusted devices by row id (ownership-scoped). Returns rows
+// changed (0 if it wasn't theirs / already gone — treat idempotently).
+async function revokeByIdForUser(id, userId) {
+  return db.revokeByIdForUser(id, userId)
+}
+
+// Revoke all of a user's trusted devices ("untrust everywhere" + the invalidation
+// hook on password change/reset / TOTP disable). Returns rows changed.
+async function revokeAllForUser(userId) {
+  return db.revokeAllForUser(userId)
+}
+
+// Drop expired/revoked rows.
+async function pruneExpired() {
+  return db.pruneExpired()
+}
+
+module.exports = {
+  MAX_TRUSTED_DEVICES,
+  store,
+  findValidByHash,
+  touchLastUsed,
+  listActiveForUser,
+  isAtCap,
+  revokeByIdForUser,
+  revokeAllForUser,
+  pruneExpired,
+}