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/auth/session.service.js

@@ -27,6 +27,7 @@ const crypto = require('crypto')
 
 const token = require('./token')
 const revokedSessions = require('../model/revokedSessions/revokedSessions.model')
+const trustedDevices = require('../model/trustedDevices/trustedDevices.model')
 const users = require('../model/users/users.model')
 const log = require('../utils/logger')('session')
 
@@ -198,6 +199,63 @@ function sessionMeta(req) {
   return { ip, userAgent, deviceHash }
 }
 
+// ── Trusted devices (MFA "Trust this device") ──────────────────────────────
+// A trusted device lets a login SKIP the TOTP step (never the password). The
+// opaque trust token lives client-side (rg_trust cookie on web, X-Trust-Token /
+// EncryptedSharedPreferences on native); only its sha256 hash is stored, so — like
+// the mobile refresh token — the server side is revocable and never holds the raw
+// secret. These functions mint/hash/resolve; the controller sets the cookie and
+// the trustedDevices model persists the row. sha256 (not bcrypt): the token is a
+// 256-bit random value looked up BY its hash via a UNIQUE index.
+
+const TRUSTED_DEVICE_TTL_DAYS = Number(process.env.TRUSTED_DEVICE_TTL_DAYS) || 30
+
+// Hash a raw trust token to the value stored in the DB. Separate name from
+// hashRefreshToken so intent is explicit at call sites, though the algorithm is
+// the same deterministic sha256.
+function hashTrustToken(raw) {
+  return crypto.createHash('sha256').update(String(raw)).digest('hex')
+}
+
+// Mint a fresh opaque trust token + its hash + expiry. `meta` (from sessionMeta)
+// supplies the best-effort device fingerprint stored for display. `now` injectable
+// for tests. Does NOT touch cookies or the DB.
+function mintTrustToken(meta = {}, now = Date.now()) {
+  const trustToken = crypto.randomBytes(32).toString('base64url') // 256 bits, opaque
+  const expiresAt = new Date(now + TRUSTED_DEVICE_TTL_DAYS * 24 * 60 * 60 * 1000)
+  return {
+    trustToken,
+    trustHash: hashTrustToken(trustToken),
+    deviceHash: meta.deviceHash || null,
+    userAgent: meta.userAgent || null,
+    expiresAt,
+  }
+}
+
+// Resolve the trust token on an incoming request to its still-valid DB row (or
+// null). The caller MUST confirm row.user_id matches the user who just passed the
+// password step before honoring it — a trust token is scoped to the account that
+// created it. Never throws on a DB hiccup here; the caller falls back to TOTP.
+async function resolveTrustedDevice(req) {
+  const raw = token.extractTrustToken(req)
+  if (!raw) return null
+  return trustedDevices.findValidByHash(hashTrustToken(raw))
+}
+
+// Stamp a trusted device as used (called when its trust was honored to skip TOTP).
+async function honorTrustedDevice(id) {
+  if (!id) return false
+  await trustedDevices.touchLastUsed(id)
+  return true
+}
+
+// True if the user already holds the maximum number of trusted devices. Callers
+// refuse a new trust (signaling the client to revoke one first) rather than
+// pruning silently. See docs/website/TRUSTED_DEVICES_MFA.md §5.
+async function trustDeviceCapReached(userId) {
+  return trustedDevices.isAtCap(userId)
+}
+
 // ── Revocation / invalidation ──────────────────────────────────────────────
 // Web/cookie sessions are JWTs, so revocation is enforced by requireAuth reading
 // two server-side stores these functions write:
@@ -264,4 +322,10 @@ module.exports = {
   refreshMobileSession,
   validateBearerToken,
   hashRefreshToken,
+  // Trusted devices (MFA "Trust this device").
+  hashTrustToken,
+  mintTrustToken,
+  resolveTrustedDevice,
+  honorTrustedDevice,
+  trustDeviceCapReached,
 }