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>

client/src/routes/admin/AdminLogin.jsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react'
 import { Link, useNavigate, useLocation } from 'react-router-dom'
 import MoonDot from '../../components/MoonDot.jsx'
 import ProviderIcon from '../../components/ProviderIcon.jsx'
+import TrustLimitModal from '../../components/security/TrustLimitModal.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
 import { useSite } from '../../contexts/SiteContext.jsx'
 import { api } from '../../api/client.js'
@@ -52,6 +53,9 @@ export default function AdminLogin() {
   const [challenge, setChallenge] = useState('')
   const [code, setCode] = useState('')
   const [ssoTotp, setSsoTotp] = useState(false)
+  const [trustDevice, setTrustDevice] = useState(false)
+  const [useRecovery, setUseRecovery] = useState(false)
+  const [trustLimit, setTrustLimit] = useState(null) // { devices, dest } when the cap is hit
 
   // SSO providers to offer (empty if none configured) + any error the callback
   // bounced us back with (?sso_error=...).
@@ -122,16 +126,23 @@ export default function AdminLogin() {
         const { returnTo } = await ssoLoginTotp(code)
         navigate(returnTo || '/admin', { replace: true })
       } else {
-        const u = await loginTotp(challenge, code)
-        navigate(destFor(u), { replace: true })
+        const entered = code.trim()
+        const data = await loginTotp(challenge, useRecovery ? '' : entered, {
+          recoveryCode: useRecovery ? entered : undefined,
+          trustDevice,
+        })
+        const to = destFor(data.user)
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       }
     } catch (err) {
       const expired = err.status === 401 && /expired/i.test(err.message)
-      setError(
-        expired
-          ? 'Your verification session expired. Please sign in again.'
-          : 'Invalid verification code.',
-      )
+      const badRecovery = useRecovery ? 'That recovery code is not valid.' : 'Invalid verification code.'
+      setError(expired ? 'Your verification session expired. Please sign in again.' : badRecovery)
       setBusy(false)
       if (expired) {
         setStage('creds')
@@ -223,22 +234,40 @@ export default function AdminLogin() {
               </div>
             </>
           ) : (
-            <label style={{ display: 'block', marginBottom: 22 }}>
-              <span className="field-label">Authentication code</span>
-              <input
-                type="text"
-                inputMode="numeric"
-                autoComplete="one-time-code"
-                autoFocus
-                placeholder="6-digit code"
-                value={code}
-                onChange={(e) => setCode(e.target.value)}
-                className="input"
-              />
-              <span className="sans" style={{ display: 'block', marginTop: 8, color: 'var(--dim)', fontSize: '0.76rem' }}>
-                Enter the code from your authenticator app.
-              </span>
-            </label>
+            <>
+              <label style={{ display: 'block', marginBottom: 14 }}>
+                <span className="field-label">{useRecovery ? 'Recovery code' : 'Authentication code'}</span>
+                <input
+                  type="text"
+                  inputMode={useRecovery ? 'text' : 'numeric'}
+                  autoComplete="one-time-code"
+                  autoFocus
+                  placeholder={useRecovery ? 'xxxxx-xxxxx' : '6-digit code'}
+                  value={code}
+                  onChange={(e) => setCode(e.target.value)}
+                  className="input"
+                />
+                <span className="sans" style={{ display: 'block', marginTop: 8, color: 'var(--dim)', fontSize: '0.76rem' }}>
+                  {useRecovery ? 'Enter one of your saved single-use recovery codes.' : 'Enter the code from your authenticator app.'}
+                </span>
+              </label>
+              {!ssoTotp && (
+                <label className="sans" style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12, color: 'var(--muted)', fontSize: '0.84rem' }}>
+                  <input type="checkbox" checked={trustDevice} onChange={(e) => setTrustDevice(e.target.checked)} />
+                  Trust this device for 30 days (skip the code next time)
+                </label>
+              )}
+              {!ssoTotp && (
+                <button
+                  type="button"
+                  onClick={() => { setUseRecovery((v) => !v); setCode('') }}
+                  className="sans"
+                  style={{ display: 'block', marginBottom: 22, background: 'none', border: 'none', padding: 0, color: 'var(--accent)', cursor: 'pointer', fontSize: '0.8rem' }}
+                >
+                  {useRecovery ? 'Use an authenticator code instead' : 'Use a recovery code instead'}
+                </button>
+              )}
+            </>
           )}
 
           {(error || (stage === 'creds' && ssoError)) && (
@@ -304,6 +333,14 @@ export default function AdminLogin() {
           </Link>
         </p>
       </div>
+
+      {trustLimit && (
+        <TrustLimitModal
+          devices={trustLimit.devices}
+          onTrusted={() => navigate(trustLimit.dest, { replace: true })}
+          onCancel={() => navigate(trustLimit.dest, { replace: true })}
+        />
+      )}
     </main>
   )
 }

client/src/routes/admin/views/AccountAdmin.jsx

@@ -1,6 +1,9 @@
 import { useCallback, useEffect, useState } from 'react'
 import { Loading, ErrorState } from '../../../components/PageState.jsx'
 import ProviderIcon from '../../../components/ProviderIcon.jsx'
+import RecoveryCodesDisplay from '../../../components/security/RecoveryCodesDisplay.jsx'
+import TrustedDevicesPanel from '../../../components/security/TrustedDevicesPanel.jsx'
+import RecoveryCodesPanel from '../../../components/security/RecoveryCodesPanel.jsx'
 import { api } from '../../../api/client.js'
 
 // Link/unlink external SSO identities to this account. Linking redirects through
@@ -127,6 +130,7 @@ export default function AccountAdmin() {
   const [code, setCode] = useState('')
   const [busy, setBusy] = useState(false)
   const [msg, setMsg] = useState('')
+  const [newCodes, setNewCodes] = useState(null) // one-time recovery codes shown after enabling
 
   async function load() {
     try {
@@ -164,9 +168,10 @@ export default function AccountAdmin() {
     setMsg('')
     setError('')
     try {
-      await api.admin.totpEnable(code.trim())
+      const res = await api.admin.totpEnable(code.trim())
       setSetup(null)
       setCode('')
+      setNewCodes(res?.recoveryCodes || null)
       setMsg('Two-factor authentication is now enabled.')
       await load()
     } catch (err) {
@@ -302,6 +307,21 @@ export default function AccountAdmin() {
       {msg && <p className="sans" style={{ marginTop: 16, color: '#7fd0a4', fontSize: '0.86rem' }}>{msg}</p>}
       {error && <p className="sans" style={{ marginTop: 16, color: '#d98b84', fontSize: '0.86rem' }}>{error}</p>}
 
+      {/* One-time recovery codes shown right after enabling 2FA. */}
+      {newCodes && (
+        <div style={{ marginTop: 20 }}>
+          <RecoveryCodesDisplay codes={newCodes} onDone={() => setNewCodes(null)} />
+        </div>
+      )}
+
+      {/* Trusted devices + recovery-code management, only relevant with 2FA on. */}
+      {enabled && (
+        <>
+          <TrustedDevicesPanel />
+          <RecoveryCodesPanel hasPassword={account?.has_password !== false} />
+        </>
+      )}
+
       <LinkedAccounts />
     </section>
   )

client/src/routes/admin/views/UserDetail.jsx

@@ -1,4 +1,4 @@
-import { useMemo } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
 import { useParams, Link } from 'react-router-dom'
 import { Loading, ErrorState } from '../../../components/PageState.jsx'
 import { useAsync } from '../../../lib/useAsync.js'
@@ -136,6 +136,114 @@ function Houses({ scope }) {
   )
 }
 
+// Admin security controls for one user: their trusted devices (view + revoke) and
+// an MFA reset for a locked-out user. Every action is audit-logged server-side.
+function SecurityAdmin({ userId }) {
+  const [devices, setDevices] = useState(null)
+  const [error, setError] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [msg, setMsg] = useState('')
+
+  const load = useCallback(async () => {
+    try {
+      setDevices(await api.admin.userTrustedDevices(userId))
+    } catch {
+      setError('Could not load trusted devices.')
+    }
+  }, [userId])
+  useEffect(() => {
+    load()
+  }, [load])
+
+  async function revoke(deviceId) {
+    setBusy(true); setMsg(''); setError('')
+    try {
+      await api.admin.revokeUserTrustedDevice(userId, deviceId)
+      await load()
+    } catch {
+      setError('Could not revoke that device.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function revokeAll() {
+    if (!window.confirm('Revoke ALL of this user’s trusted devices?')) return
+    setBusy(true); setMsg(''); setError('')
+    try {
+      await api.admin.revokeAllUserTrustedDevices(userId)
+      setMsg('All trusted devices revoked.')
+      await load()
+    } catch {
+      setError('Could not revoke devices.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  async function resetMfa() {
+    if (!window.confirm('Reset this user’s two-factor? This turns TOTP off, revokes their trusted devices, and clears their recovery codes so they can sign in with their password.')) return
+    setBusy(true); setMsg(''); setError('')
+    try {
+      await api.admin.resetUserMfa(userId)
+      setMsg('Two-factor has been reset for this user.')
+      await load()
+    } catch {
+      setError('Could not reset two-factor.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const fmt = (d) => {
+    const t = d ? new Date(d) : null
+    return t && !Number.isNaN(t.getTime()) ? t.toLocaleDateString() : '—'
+  }
+
+  return (
+    <section style={{ borderTop: '1px solid var(--line-soft)', marginTop: 30, paddingTop: 22 }}>
+      <SectionTitle>Security &amp; two-factor</SectionTitle>
+      {devices == null ? (
+        <p className="sans dim" style={{ margin: 0, fontSize: '0.86rem' }}>Loading…</p>
+      ) : devices.length === 0 ? (
+        <p className="sans dim" style={{ margin: 0, fontSize: '0.86rem' }}>No trusted devices.</p>
+      ) : (
+        <ul style={{ listStyle: 'none', margin: '0 0 14px', padding: 0, display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {devices.map((d) => (
+            <li key={d.id} style={{ display: 'flex', alignItems: 'center', gap: 12, padding: '10px 14px', border: '1px solid var(--line)', borderRadius: 8 }}>
+              <div style={{ flex: 1, minWidth: 0 }}>
+                <div className="sans" style={{ color: 'var(--head)', fontSize: '0.9rem' }}>
+                  {d.deviceName || (d.platform === 'mobile' ? 'Mobile app' : 'Browser')}
+                </div>
+                <div className="sans dim" style={{ fontSize: '0.76rem', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                  {d.userAgent || '—'} · last used {fmt(d.lastUsedAt)} · expires {fmt(d.expiresAt)}
+                </div>
+              </div>
+              <button onClick={() => revoke(d.id)} disabled={busy} className="pill" style={{ color: '#d98b84', borderColor: '#d98b84' }}>
+                Revoke
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div style={{ display: 'flex', gap: 10, alignItems: 'center', flexWrap: 'wrap' }}>
+        {devices && devices.length > 0 && (
+          <button onClick={revokeAll} disabled={busy} className="pill" style={{ color: '#d98b84', borderColor: '#d98b84' }}>
+            Revoke all trusted devices
+          </button>
+        )}
+        <button onClick={resetMfa} disabled={busy} className="btn btn-sq" style={{ borderColor: '#d98b84', color: '#d98b84' }}>
+          Reset two-factor
+        </button>
+      </div>
+
+      {msg && <p className="sans" style={{ marginTop: 12, color: '#7fd0a4', fontSize: '0.86rem' }}>{msg}</p>}
+      {error && <p className="sans" style={{ marginTop: 12, color: '#d98b84', fontSize: '0.86rem' }}>{error}</p>}
+    </section>
+  )
+}
+
 function ShardSections({ scope }) {
   return (
     <>
@@ -187,6 +295,7 @@ export default function UserDetail() {
         </div>
       </div>
 
+      <SecurityAdmin userId={id} />
       <ShardSections scope={scope} />
     </section>
   )

client/src/routes/player/PlayerAccount.jsx

@@ -1,6 +1,9 @@
 import { useCallback, useEffect, useState } from 'react'
 import ProviderIcon from '../../components/ProviderIcon.jsx'
 import { Loading, ErrorState } from '../../components/PageState.jsx'
+import RecoveryCodesDisplay from '../../components/security/RecoveryCodesDisplay.jsx'
+import TrustedDevicesPanel from '../../components/security/TrustedDevicesPanel.jsx'
+import RecoveryCodesPanel from '../../components/security/RecoveryCodesPanel.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
 import { api } from '../../api/client.js'
 
@@ -116,6 +119,7 @@ function TwoFactor({ account, reload }) {
   const [busy, setBusy] = useState(false)
   const [msg, setMsg] = useState('')
   const [error, setError] = useState('')
+  const [newCodes, setNewCodes] = useState(null) // one-time recovery codes shown after enabling
 
   async function begin() {
     setBusy(true); setMsg(''); setError('')
@@ -131,8 +135,8 @@ function TwoFactor({ account, reload }) {
   async function confirm() {
     setBusy(true); setMsg(''); setError('')
     try {
-      await api.player.totpEnable(code.trim())
-      setSetup(null); setCode(''); setMsg('Two-factor is now enabled.')
+      const res = await api.player.totpEnable(code.trim())
+      setSetup(null); setCode(''); setNewCodes(res?.recoveryCodes || null); setMsg('Two-factor is now enabled.')
       await reload()
     } catch (err) {
       setError(err.message || 'Could not enable two-factor.')
@@ -204,6 +208,11 @@ function TwoFactor({ account, reload }) {
         </div>
       )}
       <Note msg={msg} error={error} />
+      {newCodes && (
+        <div style={{ marginTop: 16 }}>
+          <RecoveryCodesDisplay codes={newCodes} onDone={() => setNewCodes(null)} />
+        </div>
+      )}
     </Section>
   )
 }
@@ -416,6 +425,12 @@ export default function PlayerAccount() {
           <ChangeUsername account={account} onChanged={onUsernameChanged} />
           <ChangePassword account={account} />
           <TwoFactor account={account} reload={load} />
+          {account.totp_enabled && (
+            <>
+              <TrustedDevicesPanel />
+              <RecoveryCodesPanel hasPassword={account.has_password !== false} />
+            </>
+          )}
           <LinkedAccounts />
           <ActiveDevices />
         </>

client/src/routes/player/PlayerLogin.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import { Link, useNavigate, useLocation } from 'react-router-dom'
 import ProviderIcon from '../../components/ProviderIcon.jsx'
+import TrustLimitModal from '../../components/security/TrustLimitModal.jsx'
 import { useAuth } from '../../contexts/AuthContext.jsx'
 import { api } from '../../api/client.js'
 import PlayerShell, { honeypotStyle } from './PlayerShell.jsx'
@@ -34,6 +35,12 @@ export default function PlayerLogin() {
   const [challenge, setChallenge] = useState('')
   const [code, setCode] = useState('')
   const [ssoTotp, setSsoTotp] = useState(false)
+  const [trustDevice, setTrustDevice] = useState(false)
+  const [useRecovery, setUseRecovery] = useState(false)
+  // When trust was requested at login but the device cap is reached: show the
+  // revoke-to-continue modal, then navigate on resolve. `pendingDest` holds where
+  // to go once the prompt is dealt with.
+  const [trustLimit, setTrustLimit] = useState(null) // { devices, dest }
 
   const [providers, setProviders] = useState([])
   const [canRegister, setCanRegister] = useState(false)
@@ -111,12 +118,25 @@ export default function PlayerLogin() {
         }
         navigate(returnTo || '/account', { replace: true })
       } else {
-        const u = await loginTotp(challenge, code)
-        navigate(destFor(u), { replace: true })
+        const entered = code.trim()
+        const data = await loginTotp(challenge, useRecovery ? '' : entered, {
+          recoveryCode: useRecovery ? entered : undefined,
+          trustDevice,
+        })
+        const to = destFor(data.user)
+        // Trust was requested but the device cap is reached: the session is already
+        // issued, so prompt to revoke one before trusting, then navigate.
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       }
     } catch (err) {
       const expired = err.status === 401 && /expired/i.test(err.message)
-      setError(expired ? 'Your verification session expired. Please sign in again.' : 'Invalid verification code.')
+      const badRecovery = useRecovery ? 'That recovery code is not valid.' : 'Invalid verification code.'
+      setError(expired ? 'Your verification session expired. Please sign in again.' : badRecovery)
       setBusy(false)
       if (expired) {
         setStage('creds')
@@ -169,13 +189,42 @@ export default function PlayerLogin() {
             </div>
           </>
         ) : (
-          <label style={{ display: 'block', marginBottom: 22 }}>
-            <span className="field-label">Authentication code</span>
-            <input type="text" inputMode="numeric" autoComplete="one-time-code" autoFocus placeholder="6-digit code" value={code} onChange={(e) => setCode(e.target.value)} className="input" />
-            <span className="sans" style={{ display: 'block', marginTop: 8, color: 'var(--dim)', fontSize: '0.76rem' }}>
-              Enter the code from your authenticator app.
-            </span>
-          </label>
+          <>
+            <label style={{ display: 'block', marginBottom: 14 }}>
+              <span className="field-label">{useRecovery ? 'Recovery code' : 'Authentication code'}</span>
+              <input
+                type="text"
+                inputMode={useRecovery ? 'text' : 'numeric'}
+                autoComplete="one-time-code"
+                autoFocus
+                placeholder={useRecovery ? 'xxxxx-xxxxx' : '6-digit code'}
+                value={code}
+                onChange={(e) => setCode(e.target.value)}
+                className="input"
+              />
+              <span className="sans" style={{ display: 'block', marginTop: 8, color: 'var(--dim)', fontSize: '0.76rem' }}>
+                {useRecovery ? 'Enter one of your saved single-use recovery codes.' : 'Enter the code from your authenticator app.'}
+              </span>
+            </label>
+            {/* Trust-this-device only applies to real authenticator/recovery login,
+                not the SSO 2FA bounce (which has no trust cookie flow here). */}
+            {!ssoTotp && (
+              <label className="sans" style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 12, color: 'var(--muted)', fontSize: '0.84rem' }}>
+                <input type="checkbox" checked={trustDevice} onChange={(e) => setTrustDevice(e.target.checked)} />
+                Trust this device for 30 days (skip the code next time)
+              </label>
+            )}
+            {!ssoTotp && (
+              <button
+                type="button"
+                onClick={() => { setUseRecovery((v) => !v); setCode('') }}
+                className="sans"
+                style={{ display: 'block', marginBottom: 22, background: 'none', border: 'none', padding: 0, color: 'var(--accent)', cursor: 'pointer', fontSize: '0.8rem' }}
+              >
+                {useRecovery ? 'Use an authenticator code instead' : 'Use a recovery code instead'}
+              </button>
+            )}
+          </>
         )}
 
         {(error || (stage === 'creds' && ssoError)) && (
@@ -208,6 +257,14 @@ export default function PlayerLogin() {
           </div>
         )}
       </form>
+
+      {trustLimit && (
+        <TrustLimitModal
+          devices={trustLimit.devices}
+          onTrusted={() => navigate(trustLimit.dest, { replace: true })}
+          onCancel={() => navigate(trustLimit.dest, { replace: true })}
+        />
+      )}
     </PlayerShell>
   )
 }