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/swagger/swagger.js

@@ -145,10 +145,14 @@ const doc = {
       },
       TotpLoginRequest: {
         type: 'object',
-        required: ['challenge', 'code'],
+        required: ['challenge'],
+        description: 'Second step for 2FA login. Supply either code OR recoveryCode.',
         properties: {
           challenge: { type: 'string', description: 'Token returned by /login when totpRequired.' },
-          code: { type: 'string', example: '123456' },
+          code: { type: 'string', description: 'Current authenticator code.', example: '123456' },
+          recoveryCode: { type: 'string', description: 'A single-use recovery code (alternative to code).', example: 'abcde-12345' },
+          trustDevice: { type: 'boolean', description: 'Remember this browser so future logins skip the TOTP step (30 days).', example: false },
+          deviceName: { type: 'string', description: 'Optional friendly label for the Trusted Devices list.', example: 'My Laptop' },
         },
       },
       MobileLoginRequest: {
@@ -158,7 +162,9 @@ const doc = {
           username: { type: 'string', example: 'admin' },
           password: { type: 'string', format: 'password', example: 'super-secret' },
           code: { type: 'string', description: 'TOTP code (only when 2FA is enabled).', example: '123456' },
-          device_name: { type: 'string', description: 'Optional friendly device label for Active Devices.', example: 'Pixel 8' },
+          recoveryCode: { type: 'string', description: 'Single-use recovery code (alternative to code).', example: 'abcde-12345' },
+          trustDevice: { type: 'boolean', description: 'Remember this device so future logins skip the TOTP step; the response then carries trustToken.', example: false },
+          device_name: { type: 'string', description: 'Optional friendly device label for Active/Trusted Devices.', example: 'Pixel 8' },
         },
       },
       MobileTokenResponse: {
@@ -172,6 +178,9 @@ const doc = {
             example: '15m',
           },
           user: { $ref: '#/components/schemas/SafeUser' },
+          trustToken: { type: 'string', nullable: true, description: 'Present only when trustDevice was requested and accepted — store securely and send as X-Trust-Token on future logins to skip TOTP.' },
+          trustLimitReached: { type: 'boolean', nullable: true, description: 'Present (true) when trustDevice was requested but the device cap is reached; see devices.' },
+          devices: { type: 'array', nullable: true, items: { $ref: '#/components/schemas/TrustedDevice' }, description: 'The existing trusted devices, when trustLimitReached is set.' },
         },
       },
       MobileRefreshRequest: {
@@ -212,6 +221,46 @@ const doc = {
           expiresAt: { type: 'string', format: 'date-time' },
         },
       },
+      // A device allowed to skip the TOTP step at login (MFA "Trust this device").
+      // Distinct from DeviceSession (a live mobile login session). Never exposes the
+      // trust token/hash.
+      TrustedDevice: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer', description: 'Trusted-device id (pass to DELETE …/trusted-devices/:id).' },
+          platform: { type: 'string', enum: ['web', 'mobile'], example: 'web' },
+          deviceName: { type: 'string', nullable: true, example: 'My Laptop' },
+          userAgent: { type: 'string', nullable: true },
+          createdAt: { type: 'string', format: 'date-time' },
+          lastUsedAt: { type: 'string', format: 'date-time' },
+          expiresAt: { type: 'string', format: 'date-time' },
+        },
+      },
+      // Result of POST /auth/me/trusted-devices. Web receives an httpOnly cookie and
+      // { trusted:true }; native (bearer) sessions additionally get { trustToken }.
+      TrustDeviceResult: {
+        type: 'object',
+        properties: {
+          trusted: { type: 'boolean', example: true },
+          trustToken: { type: 'string', nullable: true, description: 'Native clients only — store securely and send as X-Trust-Token.' },
+        },
+      },
+      // 409 body when the trusted-device cap is reached: the caller must revoke one
+      // of the listed devices before retrying.
+      TrustedDeviceLimit: {
+        type: 'object',
+        properties: {
+          error: { type: 'string', example: 'trusted_device_limit' },
+          devices: { type: 'array', items: { $ref: '#/components/schemas/TrustedDevice' } },
+        },
+      },
+      // One-time recovery (backup) codes. Returned ONLY at generation; never re-shown.
+      RecoveryCodes: {
+        type: 'object',
+        properties: {
+          recoveryCodes: { type: 'array', items: { type: 'string', example: 'abcde-12345' } },
+        },
+      },
       Message: {
         type: 'object',
         properties: { message: { type: 'string', example: 'Logged out.' } },
@@ -638,8 +687,16 @@ const doc = {
       },
       TotpState: {
         type: 'object',
-        description: 'Result of enabling/disabling 2FA.',
-        properties: { totp_enabled: { type: 'boolean', example: true } },
+        description: 'Result of enabling/disabling 2FA. Enabling also returns the one-time recovery codes.',
+        properties: {
+          totp_enabled: { type: 'boolean', example: true },
+          recoveryCodes: {
+            type: 'array',
+            nullable: true,
+            description: 'Single-use recovery codes, shown ONCE on enable.',
+            items: { type: 'string', example: 'abcde-12345' },
+          },
+        },
       },
       LinkedIdentity: {
         type: 'object',