docs: trusted devices & MFA improvements (design + API/security/schema)

Add TRUSTED_DEVICES_MFA.md (the approved design/implementation plan) and fold
the feature into BACKEND_DESIGN §3 (trusted_devices + recovery_codes schema),
§4 (login/totp trust+recovery, /auth/me/trusted-devices*, recovery-codes*,
admin trusted-device + /mfa/reset routes), and §6 (trusted-device security
model + audit actions). Note the app-side trust/recovery flow in android PLAN §4.

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

website/BACKEND_DESIGN.md

@@ -223,6 +223,28 @@ list/revoke surface: `device_name VARCHAR(100) NULL` (a friendly label) and `las
 NULL` (bumped on each refresh). Existing rows get them via the schema's ALTER section; the token model
 is otherwise unchanged.
 
+### trusted_devices  — MFA "Trust this device"
+
+Lets a browser/app **skip the TOTP step** at login (never the password) for 30 days. Pattern-identical
+to `mobile_refresh_tokens`: the opaque trust token lives client-side (the `rg_trust` httpOnly cookie on
+web, `X-Trust-Token` / EncryptedSharedPreferences on native) and only its **sha256** hash is stored
+(`token_hash CHAR(64) UNIQUE`) — sha256, not bcrypt, because a 256-bit random token is looked up **by
+its hash** via the unique index (a per-row salt would break that). Columns mirror the mobile table
+(`platform`, `device_name`, `device_hash`, `user_agent`, `created_at`, `last_used_at`, `expires_at`,
+`revoked_at`). Capped at 10 rows/user **in application code — no silent pruning** (an over-cap trust is
+refused so the client can prompt the user to revoke one first). Consulted only at the login/password
+step, never at token refresh, and revoked wholesale on untrust / password change / password reset /
+TOTP disable. See `docs/website/TRUSTED_DEVICES_MFA.md`.
+
+### recovery_codes  — single-use MFA backup codes
+
+Generated at TOTP enrollment (10 at a time, shown to the user **once**) so a user who loses their
+authenticator can complete login without an admin reset. `code_hash VARCHAR(72)` is a **bcrypt** hash
+(not sha256): a recovery code is a human-typed, lower-entropy fallback credential — the closest
+analogue to a password — and there is no hash-lookup constraint (verification fetches the user's ≤10
+unused rows and `bcrypt.compare`s each, like password verification). `used_at` is the single-use
+marker. Cleared wholesale on TOTP disable / password change / password reset.
+
 ---
 
 ## 4. API contract
@@ -233,8 +255,9 @@ accepts `Authorization: Bearer` for API testing).
 ### /auth  (auth.routes.js → auth.controller.js)
 | Method | Path | Auth | Body | Purpose |
 |---|---|---|---|---|
-| POST | `/login` | — (rate-limited) | `{username,password}` | verify, set cookie, log `auth.login`, update `last_login_at` |
-| POST | `/logout` | cookie | — | clear cookie |
+| POST | `/login` | — (rate-limited) | `{username,password}` | verify, set cookie, log `auth.login`, update `last_login_at`. If the account has TOTP **and this browser is a trusted device** (a valid `rg_trust` cookie bound to the user), the TOTP step is **skipped** and a session is issued directly (logs `auth.login.trusted_device`). Otherwise a 2FA account returns `{totpRequired, challenge}`. |
+| POST | `/login/totp` | — (rate-limited) | `{challenge, code? \| recoveryCode?, trustDevice?, deviceName?}` | complete 2FA with a TOTP **or** single-use recovery code. `trustDevice` sets the `rg_trust` cookie so future logins skip TOTP; at the device cap the session is still issued and the body carries `{trustLimitReached, devices}`. |
+| POST | `/logout` | cookie | — | clear cookie (the `rg_trust` trust cookie deliberately **survives** logout) |
 | GET | `/me` | cookie / bearer | — | current user (no hash) or 401 — client bootstraps auth state |
 | POST | `/password/forgot` | — (rate-limited) | `{email}` | email a single-use, ~1h reset link to **every active account** on the address; **always** returns the same generic 200 (no account enumeration). Email is non-unique, so several accounts may each get a link naming their username. Logs `account.password.reset.request`. |
 | GET | `/password/reset/:token` | — | — | validate a link → `{username}` for the form, else 404 (never distinguishes expired/used/never-existed) |
@@ -242,8 +265,13 @@ accepts `Authorization: Bearer` for API testing).
 | GET | `/me/account` | cookie / bearer | — | full self account (`id, username, role, email, status, totp_enabled, has_password`) |
 | PATCH | `/me/account/username` | cookie / bearer (rate-limited) | `{username}` | change own username; re-issues the caller's session |
 | PATCH | `/me/account/password` | cookie / bearer (rate-limited) | `{newPassword, currentPassword?}` | change/set own password (current required unless the account has none); revokes other sessions, keeps the caller's |
-| POST | `/me/account/totp/setup` · `…/enable` · `…/disable` | cookie / bearer | `{code}` on enable/disable | self 2FA enrollment (disable needs a valid current code, not a password) |
+| POST | `/me/account/totp/setup` · `…/enable` · `…/disable` | cookie / bearer | `{code}` on enable/disable | self 2FA enrollment (disable needs a valid current code, not a password). **enable** returns the one-time `recoveryCodes`; **disable** clears the user's trusted devices + recovery codes |
 | GET | `/me/account/identities` · DELETE `…/:provider` | cookie / bearer | — | list / unlink own SSO identities |
+| GET | `/me/trusted-devices` | cookie / bearer | — | list own active trusted devices (never tokens) |
+| POST | `/me/trusted-devices` | cookie / bearer (rate-limited) | `{deviceName?}` | trust the current device; web gets an httpOnly `rg_trust` cookie, native gets `{trustToken}`. **409 `{error:'trusted_device_limit', devices}`** at the cap |
+| DELETE | `/me/trusted-devices` · `…/:id` | cookie / bearer | — | untrust all / one (ownership-scoped) |
+| GET | `/me/account/recovery-codes/status` | cookie / bearer | — | remaining unused code count (never the codes) |
+| POST | `/me/account/recovery-codes/generate` | cookie / bearer (rate-limited, **password step-up**) | `{currentPassword?}` | regenerate the one-time recovery codes (returned once); refused when 2FA is off |
 | POST | `/me/devices` | cookie / bearer | `{endpoint, transport?, platform?}` | register a push endpoint; **rejects a disallowed endpoint 400** (SSRF guard). Idempotent per (user, endpoint) |
 | GET | `/me/devices` · DELETE `…/:id` | cookie / bearer | — | list / unregister own push devices |
 | GET | `/me/notifications/streams` | cookie / bearer | — | the subscribable catalog (`personal`/`requiresLinkedAccount` flags) |
@@ -375,6 +403,9 @@ Public content GETs pass through the **siteMode** gate (§5).
 | GET | `/settings` · PUT `/settings` | read all / update `{key:value,...}` |
 | GET | `/activity?limit=&offset=` | paginated activity log |
 | GET | `/users` · POST `/users` · PUT `/users/:id` · DELETE `/users/:id` | user mgmt (can't delete self / last admin; password hashed on write) |
+| GET | `/users/:id/trusted-devices` | list a user's active trusted devices (never tokens) |
+| DELETE | `/users/:id/trusted-devices` · `…/:deviceId` | revoke all / one of a user's trusted devices (logs `admin.trusted_device.revoke[_all]`) |
+| POST | `/users/:id/mfa/reset` | recover a locked-out user: disable TOTP + revoke all trusted devices + clear recovery codes (logs `admin.user.totp.reset`) |
 
 Every admin write logs to `activity_log`.
 
@@ -405,7 +436,8 @@ who"; `activity_log` provides the history feed.
 ## 6. Auth & security
 
 - **JWT** signed with `JWT_SECRET`, `expiresIn=JWT_EXPIRES_IN` (default `1d`); payload `{id,username,role}`.
-- **Cookie**: `httpOnly`, `sameSite=Lax`, `path=/`, and **`secure` decided per-request** (`COOKIE_SECURE=auto` → `secure: req.secure`). This is the key to dual access: the cookie is `Secure` when reached through Pangolin (HTTPS, `X-Forwarded-Proto: https`) but **not** `Secure` when reached directly over the LAN IP on plain HTTP — so login works in both. `COOKIE_SECURE=true|false` can force it. Requires `trust proxy` (below). `localhost:5173` (Vite) and `localhost:3000` are same-site, so the cookie flows in dev too.
+- **Cookie**: `httpOnly`, `sameSite=Lax`, `path=/`, and **`secure` decided per-request** (`COOKIE_SECURE=auto` → `secure: req.secure`).
+- **Trusted-device MFA.** A second, separate httpOnly cookie (`rg_trust`, default 30d) — opaque, sha256-hashed server-side in `trusted_devices` — lets a browser/app **skip the TOTP step** (never the password) on future logins. It is a server-side, per-row-revocable record (never a JWT claim), so the stateless session JWT is unchanged and trust stays revocable. It only ever gates the **second factor**; it deliberately outlives logout, and is cleared on untrust / password change / password reset / TOTP disable. **Recovery codes** (bcrypt, single-use) are the 2FA-lockout fallback. All admin trusted-device/MFA actions and the self actions (`auth.login.trusted_device`, `account.trusted_device.*`, `account.recovery_code*`, `admin.trusted_device.*`, `admin.user.totp.reset`) are audit-logged. See `docs/website/TRUSTED_DEVICES_MFA.md`. This is the key to dual access: the cookie is `Secure` when reached through Pangolin (HTTPS, `X-Forwarded-Proto: https`) but **not** `Secure` when reached directly over the LAN IP on plain HTTP — so login works in both. `COOKIE_SECURE=true|false` can force it. Requires `trust proxy` (below). `localhost:5173` (Vite) and `localhost:3000` are same-site, so the cookie flows in dev too.
 - **bcrypt** hashing (cost 10+); plaintext passwords never stored, logged, or returned.
 - **Rate limiting** (`express-rate-limit`) on `/auth/login` and `/public/contact`.
 - **Validation** (`express-validator`) on all writes; centralized error handler.