From 620781b7bcb6e2e47bfd40c964b5b6922eee3bef Mon Sep 17 00:00:00 2001
From: wtclaude <claude@whitlocktech.net>
Date: Tue, 28 Jul 2026 01:01:12 -0500
Subject: [PATCH] feat(auth): honor and establish trusted devices on the SSO
 login paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Trust this device" did nothing for anyone who signs in with Google or Discord.
sso.controller went straight from needsTotp(user) to staging a pending-TOTP
challenge and never consulted resolveTrustedDevice, so an SSO user was asked for
a code on EVERY sign-in no matter how many times they had ticked the box — and
POST /auth/sso/totp accepted only `code`, so that step could not establish a
trust either. The password paths (web + native) were unaffected and already
worked; this closes the gap for SSO, on the website AND in the Android app.

Server:
- finishLogin and finishMobileLogin now run the same trusted-device check as
  auth.controller.login, via one shared helper: honor a trust that belongs to
  THIS user, stamp last_used_at, log auth.login.trusted_device. A store error
  falls through to the challenge — fail closed to asking for the code.
- POST /auth/sso/totp gains optional trustDevice + deviceName, sets the rg_trust
  cookie, and mirrors the password path's { trustLimitReached, devices } response
  at the cap (the sign-in still completes). Recovery codes stay password-only.

Android coverage, without leaking a secret into a URL:
- The app opens SSO in a Custom Tab, which shares the system browser's cookie
  jar, so the rg_trust cookie set on that TOTP form is presented back on the next
  app sign-in. That alone makes native SSO skip the code. Passing the app's token
  into the start URL was rejected — it would put a 256-bit secret in query
  strings, Referer headers and access logs.
- To also cover the app's NATIVE password login, ticking the box sets
  mobile_auth_sessions.trust_device (a boolean; never the token), and
  /auth/mobile/sso/exchange mints a platform:'mobile' trust and returns
  { trustToken }. Minting there keeps the raw token on an authenticated
  app→server call, out of the deep link and out of the bridge row. Best-effort:
  at the cap the response just omits it rather than failing a good sign-in.

Client: the trust checkbox is no longer hidden on the SSO second step, on both
the admin and player login screens. On the mobile bridge the deep-link redirect
takes priority over the cap prompt — the sign-in succeeded and the link is
single-use, so stalling there would strand the app.

Tests: 8 new cases in server/test/ssoTrustedDevice.test.js (verified to fail
against the pre-fix controller). Full suites green — server 445, client 43 —
and routes.manifest.json is a zero-line diff: no URL moved, only +2 handlers on
/auth/sso/totp in routes.guards.json for the two new validators. Swagger
regenerated. Verified live against the running server and real MariaDB: the TOTP
step issues rg_trust and persists the row, a subsequent SSO callback carrying it
skips the code, and an invalid trust is still challenged.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 client/src/api/client.js                      |   6 +-
 client/src/contexts/AuthContext.jsx           |   8 +-
 client/src/routes/admin/AdminLogin.jsx        |  26 ++-
 client/src/routes/player/PlayerLogin.jsx      |  38 ++-
 server/db/schema.sql                          |   9 +
 server/routes.guards.json                     |   2 +-
 .../mobileAuthBridge/mobileAuthBridge.db.js   |  15 ++
 .../mobileAuthBridge.model.js                 |   9 +
 .../router/v1/auth/mobileSso.controller.js    |  25 ++
 server/src/router/v1/auth/mobileSso.routes.js |   4 +-
 server/src/router/v1/auth/sso.controller.js   |  71 +++++-
 server/src/router/v1/auth/sso.routes.js       |   8 +-
 server/swagger/swagger-output.json            |  26 ++-
 server/test/ssoTrustedDevice.test.js          | 216 ++++++++++++++++++
 14 files changed, 419 insertions(+), 44 deletions(-)
 create mode 100644 server/test/ssoTrustedDevice.test.js

diff --git a/client/src/api/client.js b/client/src/api/client.js
index 2942301..6f522a6 100644
--- a/client/src/api/client.js
+++ b/client/src/api/client.js
@@ -71,8 +71,10 @@ export const api = {
   resetPassword: (token, password) =>
     req(`/auth/password/reset/${encodeURIComponent(token)}`, { method: 'POST', body: { password } }),
   // Second factor for an SSO login (challenge is held in an httpOnly cookie set by
-  // the callback, so only the code is sent). Returns { user, returnTo }.
-  ssoLoginTotp: (code) => req('/auth/sso/totp', { method: 'POST', body: { code } }),
+  // the callback, so only the code is sent). `extra` carries the trustDevice/
+  // deviceName opt-in, same as the password path. Returns { user, returnTo } — plus
+  // { trustLimitReached, devices } when trust was asked for but the cap is reached.
+  ssoLoginTotp: (code, extra = {}) => req('/auth/sso/totp', { method: 'POST', body: { code, ...extra } }),
   logout: () => req('/auth/logout', { method: 'POST' }),
   // Public SSO provider discovery — drives the login-page provider buttons.
   authProviders: () => req('/auth/providers'),
diff --git a/client/src/contexts/AuthContext.jsx b/client/src/contexts/AuthContext.jsx
index c92f164..5b6dce6 100644
--- a/client/src/contexts/AuthContext.jsx
+++ b/client/src/contexts/AuthContext.jsx
@@ -49,9 +49,11 @@ export function AuthProvider({ children }) {
   }, [])
 
   // Step 2 for SSO logins whose account has 2FA on. The pending challenge lives in
-  // an httpOnly cookie, so only the code is sent. Returns { user, returnTo }.
-  const ssoLoginTotp = useCallback(async (code) => {
-    const data = await api.ssoLoginTotp(code)
+  // an httpOnly cookie, so only the code is sent. `extra` carries the trustDevice/
+  // deviceName opt-in. Returns the full payload ({ user, returnTo,
+  // trustLimitReached?, devices? }) so the caller can handle the device-cap prompt.
+  const ssoLoginTotp = useCallback(async (code, extra) => {
+    const data = await api.ssoLoginTotp(code, extra)
     setUser(data.user)
     return data
   }, [])
diff --git a/client/src/routes/admin/AdminLogin.jsx b/client/src/routes/admin/AdminLogin.jsx
index bea6c35..bd71039 100644
--- a/client/src/routes/admin/AdminLogin.jsx
+++ b/client/src/routes/admin/AdminLogin.jsx
@@ -123,8 +123,16 @@ export default function AdminLogin() {
     setBusy(true)
     try {
       if (ssoTotp) {
-        const { returnTo } = await ssoLoginTotp(code)
-        navigate(returnTo || '/admin', { replace: true })
+        // Trust works on the SSO second factor exactly as it does on the password
+        // one — the IdP already proved the first factor.
+        const data = await ssoLoginTotp(code.trim(), { trustDevice })
+        const to = data.returnTo || '/admin'
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       } else {
         const entered = code.trim()
         const data = await loginTotp(challenge, useRecovery ? '' : entered, {
@@ -251,12 +259,14 @@ export default function AdminLogin() {
                   {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>
-              )}
+              {/* Offered on the SSO second factor too — the trust is on the device,
+                  not on how the first factor was proved. */}
+              <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>
+              {/* Recovery codes remain password-login only: the SSO second step
+                  verifies an authenticator code against the staged challenge. */}
               {!ssoTotp && (
                 <button
                   type="button"
diff --git a/client/src/routes/player/PlayerLogin.jsx b/client/src/routes/player/PlayerLogin.jsx
index f12ad5b..cda99ab 100644
--- a/client/src/routes/player/PlayerLogin.jsx
+++ b/client/src/routes/player/PlayerLogin.jsx
@@ -108,15 +108,28 @@ export default function PlayerLogin() {
     setBusy(true)
     try {
       if (ssoTotp) {
-        const { returnTo, redirect } = await ssoLoginTotp(code)
+        // Trust works on the SSO second factor too. On the mobile bridge this page
+        // is running inside the app's Custom Tab, so the cookie set here is what
+        // lets the next app sign-in skip the code.
+        const data = await ssoLoginTotp(code.trim(), { trustDevice })
         // Native SSO bridge (M9): a mobile 2FA completion returns an absolute
         // deep link (e.g. runicgateway://…) to hand the app its one-time code.
         // React Router can't navigate a custom scheme, so leave the SPA for it.
-        if (redirect) {
-          window.location.href = redirect
+        // This wins over the trust-cap prompt: the sign-in itself succeeded and the
+        // deep link is single-use, so stalling here to manage devices would strand
+        // the app. An over-cap user simply isn't trusted and can prune the list
+        // from Account → Trusted Devices.
+        if (data.redirect) {
+          window.location.href = data.redirect
           return
         }
-        navigate(returnTo || '/account', { replace: true })
+        const to = data.returnTo || '/account'
+        if (data.trustLimitReached) {
+          setTrustLimit({ devices: data.devices || [], dest: to })
+          setBusy(false)
+          return
+        }
+        navigate(to, { replace: true })
       } else {
         const entered = code.trim()
         const data = await loginTotp(challenge, useRecovery ? '' : entered, {
@@ -206,14 +219,15 @@ export default function PlayerLogin() {
                 {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>
-            )}
+            {/* Offered on the SSO second factor too — the trust is on the device,
+                not on how the first factor was proved. Inside the app's Custom Tab
+                this is also what trusts the device for future native sign-ins. */}
+            <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>
+            {/* Recovery codes remain password-login only: the SSO second step
+                verifies an authenticator code against the staged challenge. */}
             {!ssoTotp && (
               <button
                 type="button"
diff --git a/server/db/schema.sql b/server/db/schema.sql
index a86eff6..b8de326 100644
--- a/server/db/schema.sql
+++ b/server/db/schema.sql
@@ -215,6 +215,9 @@ CREATE TABLE IF NOT EXISTS mobile_auth_sessions (
   state          VARCHAR(255) NOT NULL,               -- app-generated opaque CSRF value, echoed to the app
   status         ENUM('pending','completed','consumed') NOT NULL DEFAULT 'pending',
   user_id        INT          NULL,                   -- set once SSO resolves the account
+  trust_device   TINYINT(1)   NOT NULL DEFAULT 0,     -- user ticked "trust this device" on the Custom Tab TOTP form;
+                                                      -- a BOOLEAN only — the trust token itself is minted at /exchange
+                                                      -- and returned over that app→server call, never stored here
   created_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
   expires_at     DATETIME NOT NULL,                   -- ~10 min (one redirect round-trip incl. TOTP)
   used_at        DATETIME NULL,                       -- stamped at exchange
@@ -1069,3 +1072,9 @@ ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS in_registry TINYINT(1) NOT NUL
 -- self-service list. Both nullable and additive; existing rows get them here.
 ALTER TABLE mobile_refresh_tokens ADD COLUMN IF NOT EXISTS device_name VARCHAR(100) NULL;
 ALTER TABLE mobile_refresh_tokens ADD COLUMN IF NOT EXISTS last_used_at DATETIME NULL;
+
+-- SSO trusted devices: records that the user ticked "trust this device" on the
+-- Custom Tab TOTP form, so /auth/mobile/sso/exchange knows to mint the app's own
+-- trust token. A boolean only — the token is returned over that app→server call
+-- and never persisted here (only its sha256 lands in trusted_devices).
+ALTER TABLE mobile_auth_sessions ADD COLUMN IF NOT EXISTS trust_device TINYINT(1) NOT NULL DEFAULT 0;
diff --git a/server/routes.guards.json b/server/routes.guards.json
index 35318cf..c1f4b2f 100644
--- a/server/routes.guards.json
+++ b/server/routes.guards.json
@@ -1550,7 +1550,7 @@
     {
       "method": "POST",
       "path": "/api/v1/auth/sso/totp",
-      "handlers": 6,
+      "handlers": 8,
       "gates": [
         "backoffGuard",
         "middleware",
diff --git a/server/src/model/mobileAuthBridge/mobileAuthBridge.db.js b/server/src/model/mobileAuthBridge/mobileAuthBridge.db.js
index 2ca462e..209761a 100644
--- a/server/src/model/mobileAuthBridge/mobileAuthBridge.db.js
+++ b/server/src/model/mobileAuthBridge/mobileAuthBridge.db.js
@@ -37,6 +37,20 @@ async function completeSession(sessionId, userId) {
   return Number(res.affectedRows || 0)
 }
 
+// Record that the user asked to trust this device on the Custom Tab TOTP form.
+// Guarded on status + expiry for the same reason completeSession is: a replayed
+// TOTP post must not re-arm a session that has already been consumed. Stores a
+// boolean only — the trust token is minted at /exchange and never lands here.
+async function setTrustDevice(sessionId) {
+  const res = await query(
+    `UPDATE mobile_auth_sessions
+        SET trust_device = 1
+      WHERE session_id = ? AND status = 'pending' AND expires_at > NOW()`,
+    [sessionId],
+  )
+  return Number(res.affectedRows || 0)
+}
+
 // Mark a session `consumed` after a successful token exchange (stamps used_at).
 async function consumeSession(sessionId) {
   const res = await query(
@@ -93,6 +107,7 @@ module.exports = {
   insertSession,
   getSession,
   completeSession,
+  setTrustDevice,
   consumeSession,
   insertCode,
   findValidCode,
diff --git a/server/src/model/mobileAuthBridge/mobileAuthBridge.model.js b/server/src/model/mobileAuthBridge/mobileAuthBridge.model.js
index 136f914..d04dc8f 100644
--- a/server/src/model/mobileAuthBridge/mobileAuthBridge.model.js
+++ b/server/src/model/mobileAuthBridge/mobileAuthBridge.model.js
@@ -79,6 +79,14 @@ async function consumeCode(rawCode) {
   return changed > 0
 }
 
+// Flag that the user ticked "trust this device" on the Custom Tab TOTP form. The
+// exchange step reads this to decide whether to mint the app's own trust token.
+// Returns true iff the session was still eligible to be flagged.
+async function markTrustRequested(sessionId) {
+  if (!sessionId) return false
+  return (await db.setTrustDevice(sessionId)) > 0
+}
+
 // Mark a session fully consumed after a successful exchange.
 async function finishSession(sessionId) {
   return db.consumeSession(sessionId)
@@ -97,6 +105,7 @@ module.exports = {
   issueAuthCode,
   findRedeemableCode,
   consumeCode,
+  markTrustRequested,
   finishSession,
   pruneExpired,
 }
diff --git a/server/src/router/v1/auth/mobileSso.controller.js b/server/src/router/v1/auth/mobileSso.controller.js
index e8dbe5c..064b99e 100644
--- a/server/src/router/v1/auth/mobileSso.controller.js
+++ b/server/src/router/v1/auth/mobileSso.controller.js
@@ -22,6 +22,7 @@ const settings = require('../../../model/settings/settings.model')
 const sessionService = require('../../../auth/session.service')
 const ssoState = require('../../../auth/ssoState')
 const ssoController = require('./sso.controller')
+const { establishTrust } = require('./trustDevice.helper')
 
 const log = require('../../../utils/logger')('auth-mobile-sso')
 
@@ -163,12 +164,36 @@ async function exchange(req, res) {
       expiresAt: out.refreshExpiresAt,
     })
     await activity.log({ req, userId: user.id, action: 'auth.mobile.login', detail: { sso: sess.provider } })
+
+    // The user ticked "trust this device" on the Custom Tab TOTP form. That already
+    // set the browser's rg_trust cookie (which is what lets the NEXT Custom Tab SSO
+    // sign-in skip the code); mint the app its OWN trust token here so a native
+    // password login on the same device skips the code too. Minting at this point
+    // — an authenticated app→server call — is deliberate: the token reaches the app
+    // in a JSON body and never travels in the deep-link URL or sits in the bridge
+    // row. Best-effort: a device at the trust cap just gets no token, never a failed
+    // sign-in, so this can't turn a good login into an error.
+    let trustToken = null
+    if (sess.trust_device) {
+      try {
+        const trust = await establishTrust(req, user, {
+          platform: 'mobile',
+          deviceName: req.body.device_name || null,
+        })
+        if (trust.ok) trustToken = trust.trustToken
+        else if (trust.capReached) log.info('mobile sso: trust refused, device cap reached', { id: user.id })
+      } catch (err) {
+        log.error('mobile sso: could not establish trust (continuing, sign-in already succeeded)', err)
+      }
+    }
+
     log.info('mobile sso exchange success', { id: user.id, provider: sess.provider, ip: req.ip })
     return res.json({
       accessToken: out.accessToken,
       refreshToken: out.refreshToken,
       expiresIn: out.expiresIn,
       user: { id: user.id, username: user.username, role: user.role },
+      ...(trustToken ? { trustToken } : {}),
     })
   } catch (err) {
     log.error('mobile sso exchange', err)
diff --git a/server/src/router/v1/auth/mobileSso.routes.js b/server/src/router/v1/auth/mobileSso.routes.js
index e33b8e6..b24843c 100644
--- a/server/src/router/v1/auth/mobileSso.routes.js
+++ b/server/src/router/v1/auth/mobileSso.routes.js
@@ -39,9 +39,9 @@ mobileSsoRouter.post(
   '/exchange',
   // #swagger.tags = ['Auth · Mobile']
   // #swagger.summary = 'Exchange an SSO authorization code for mobile tokens'
-  // #swagger.description = 'Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401.'
+  // #swagger.description = 'Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401. If the user ticked "trust this device" on the TOTP form during this flow, the response also carries { trustToken } for the app to store and replay via X-Trust-Token — minted here rather than passed through the deep link so it never appears in a URL.'
   /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/MobileSsoExchangeRequest" } } } } */
-  /* #swagger.responses[200] = { description: 'Access + refresh tokens', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
+  /* #swagger.responses[200] = { description: 'Access + refresh tokens (optionally with a trustToken to persist)', content: { "application/json": { schema: { $ref: "#/components/schemas/MobileTokenResponse" } } } } */
   /* #swagger.responses[400] = { description: 'Validation error', content: { "application/json": { schema: { $ref: "#/components/schemas/ValidationError" } } } } */
   /* #swagger.responses[401] = { description: 'Invalid/expired/used code or failed PKCE verification', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   /* #swagger.responses[429] = { description: 'Too many attempts (rate limited)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
diff --git a/server/src/router/v1/auth/sso.controller.js b/server/src/router/v1/auth/sso.controller.js
index 1697d56..cb51f18 100644
--- a/server/src/router/v1/auth/sso.controller.js
+++ b/server/src/router/v1/auth/sso.controller.js
@@ -26,6 +26,7 @@ const usernamePolicy = require('../../../auth/usernamePolicy')
 const botScore = require('../../../middleware/botScore')
 const loginProtection = require('../../../middleware/loginProtection')
 const { needsTotp } = require('./auth.controller')
+const { establishTrust } = require('./trustDevice.helper')
 
 const log = require('../../../utils/logger')('sso')
 
@@ -226,6 +227,29 @@ async function provisionSsoPlayer(req, providerId, profile) {
   return null
 }
 
+// Trusted-device skip for the SSO paths — the exact analogue of the check in
+// auth.controller.login, and the reason SSO used to demand a code on every single
+// sign-in even from a browser the user had explicitly trusted.
+//
+// The first factor here is the IdP authentication that just succeeded, so skipping
+// the SECOND factor on a device the user deliberately trusted is the same posture
+// as the password path. The trust must belong to THIS user (a trust token is
+// scoped to the account that minted it), and any store hiccup falls through to the
+// normal TOTP challenge — fail closed to asking for the code.
+async function trustedDeviceSkips(req, user, providerId) {
+  try {
+    const device = await sessionService.resolveTrustedDevice(req)
+    if (!device || device.user_id !== user.id) return false
+    await sessionService.honorTrustedDevice(device.id)
+    await activity.log({ req, userId: user.id, action: 'auth.login.trusted_device', detail: { provider: providerId, sso: true } })
+    log.info('sso login via trusted device (TOTP skipped)', { provider: providerId, id: user.id, ip: req.ip })
+    return true
+  } catch (err) {
+    log.error('sso trusted-device check failed; falling back to TOTP', err)
+    return false
+  }
+}
+
 // SSO login. Normally link-only: a login succeeds only if the external identity
 // is already linked. The one setting-gated relaxation is auto-provisioning a
 // player when player_registration ∈ {sso, both} (see provisionSsoPlayer).
@@ -257,10 +281,11 @@ async function finishLogin(req, res, providerId, kind, tx, profile) {
   const authMethod = sessionService.AUTH_METHODS.includes(kind) ? kind : 'sso'
 
   // 2FA parity with the local login (auth.controller): if the account has TOTP
-  // enabled, an SSO sign-in must NOT bypass the second factor. Stage a signed,
-  // httpOnly challenge and route the browser through the TOTP form instead of
-  // minting a session here. See issue #31.
-  if (needsTotp(user)) {
+  // enabled, an SSO sign-in must NOT bypass the second factor — unless this browser
+  // is a trusted device, which skips the second factor exactly as it does for a
+  // password login. Otherwise stage a signed, httpOnly challenge and route the
+  // browser through the TOTP form instead of minting a session here. See issue #31.
+  if (needsTotp(user) && !(await trustedDeviceSkips(req, user, providerId))) {
     const pending = ssoState.createTotpPending({
       userId: user.id,
       provider: providerId,
@@ -381,10 +406,17 @@ async function finishMobileLogin(req, res, providerId, kind, tx, profile) {
 
   const authMethod = sessionService.AUTH_METHODS.includes(kind) ? kind : 'sso'
 
-  if (needsTotp(user)) {
-    // Same second-factor gate as web: stage a signed pending-TOTP cookie (now
-    // carrying the bridge session) and route the Custom Tab through the player
-    // TOTP form. finishSsoTotp completes the mobile flow on a correct code.
+  // Same second-factor gate as web, including the trusted-device skip. This request
+  // is the IdP redirect landing in the app's Custom Tab, which shares the system
+  // browser's cookie jar — so an rg_trust cookie set by a previous SSO sign-in from
+  // this app IS presented here, and the app gets the same "don't ask me again"
+  // behaviour as the website without having to inject a header into a tab it does
+  // not control. (Putting the token in the start URL instead would leak a secret
+  // into query strings and logs.)
+  if (needsTotp(user) && !(await trustedDeviceSkips(req, user, providerId))) {
+    // Stage a signed pending-TOTP cookie (now carrying the bridge session) and route
+    // the Custom Tab through the player TOTP form. finishSsoTotp completes the
+    // mobile flow on a correct code.
     const pending = ssoState.createTotpPending({
       userId: user.id,
       provider: providerId,
@@ -432,6 +464,19 @@ async function finishSsoTotp(req, res) {
     res.clearCookie(ssoState.TOTP_COOKIE, token.cookieOptions(req))
     loginProtection.recordSuccess(req.ip)
 
+    // Optionally remember this browser, exactly as the password path does. On the
+    // mobile flow this browser IS the Custom Tab, so the cookie set here is what
+    // lets the NEXT app sign-in skip the code.
+    let trustLimit = null
+    if (req.body.trustDevice) {
+      const result = await establishTrust(req, user, {
+        platform: 'web',
+        deviceName: req.body.deviceName || null,
+      })
+      if (result.ok) token.setTrustCookie(req, res, result.trustToken)
+      else if (result.capReached) trustLimit = result.devices
+    }
+
     // Mobile SSO bridge: instead of a web session, mint the one-time auth code and
     // return a deep link for the app to redeem. The second factor is now complete,
     // so the code is issued no earlier than an ordinary web session would be.
@@ -440,11 +485,18 @@ async function finishSsoTotp(req, res) {
       if (!sess || sess.status !== 'pending' || new Date(sess.expires_at).getTime() <= Date.now()) {
         return res.status(401).json({ message: 'Your sign-in session expired. Please sign in again from the app.' })
       }
+      // Record the user's choice on the bridge session (a boolean — never the token)
+      // so /auth/mobile/sso/exchange can mint the APP's own trust token and hand it
+      // back over that authenticated app→server call. The token therefore never
+      // travels in the deep-link URL.
+      if (req.body.trustDevice && !trustLimit) {
+        await mobileBridge.markTrustRequested(sess.session_id)
+      }
       const link = await mintMobileAuthLink(req, sess, user, pending.provider, true)
       if (!link) {
         return res.status(409).json({ message: 'This sign-in session was already used. Please sign in again from the app.' })
       }
-      return res.json({ redirect: link })
+      return res.json({ redirect: link, ...(trustLimit ? { trustLimitReached: true, devices: trustLimit } : {}) })
     }
 
     const authMethod = sessionService.AUTH_METHODS.includes(pending.authMethod) ? pending.authMethod : 'sso'
@@ -456,6 +508,7 @@ async function finishSsoTotp(req, res) {
     return res.json({
       user: { id: user.id, username: user.username, role: user.role },
       returnTo: sanitizeReturn(pending.returnTo) || homePath(portalFor(pending.returnTo)),
+      ...(trustLimit ? { trustLimitReached: true, devices: trustLimit } : {}),
     })
   } catch (err) {
     log.error('sso totp error', err)
diff --git a/server/src/router/v1/auth/sso.routes.js b/server/src/router/v1/auth/sso.routes.js
index 6665b79..07ebf08 100644
--- a/server/src/router/v1/auth/sso.routes.js
+++ b/server/src/router/v1/auth/sso.routes.js
@@ -67,13 +67,15 @@ ssoRouter.post(
   '/sso/totp',
   // #swagger.tags = ['Auth · SSO']
   // #swagger.summary = 'Complete an SSO login with a TOTP code'
-  // #swagger.description = 'Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Rate limited and behind bot/backoff guards.'
-  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["code"], properties: { code: { type: "string" } } } } } } */
-  /* #swagger.responses[200] = { description: 'Session issued', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/SafeUser" }, returnTo: { type: "string" } } } } } } */
+  // #swagger.description = 'Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Set trustDevice to remember this browser and skip TOTP on future SSO sign-ins (30 days) — on the mobile flow this browser is the app Custom Tab, and the app additionally receives its own trustToken at /auth/mobile/sso/exchange. If the trusted-device limit is reached the sign-in still completes and the response carries { trustLimitReached, devices }. Rate limited and behind bot/backoff guards.'
+  /* #swagger.requestBody = { required: true, content: { "application/json": { schema: { type: "object", required: ["code"], properties: { code: { type: "string" }, trustDevice: { type: "boolean" }, deviceName: { type: "string" } } } } } } */
+  /* #swagger.responses[200] = { description: 'Session issued (web), or a deep link to redeem (mobile bridge); optionally with a trusted-device-limit prompt', content: { "application/json": { schema: { type: "object", properties: { user: { $ref: "#/components/schemas/SafeUser" }, returnTo: { type: "string" }, redirect: { type: "string" }, trustLimitReached: { type: "boolean" }, devices: { type: "array", items: { $ref: "#/components/schemas/TrustedDevice" } } } } } } } */
   /* #swagger.responses[401] = { description: 'Invalid code or expired challenge', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   /* #swagger.responses[429] = { description: 'Too many attempts (rate limited / backoff)', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
   ...loginGuards,
   body('code').isString().trim().isLength({ min: 6, max: 8 }),
+  body('trustDevice').optional().isBoolean(),
+  body('deviceName').optional({ values: 'falsy' }).isString().trim().isLength({ max: 100 }),
   validate,
   ctrl.finishSsoTotp,
 )
diff --git a/server/swagger/swagger-output.json b/server/swagger/swagger-output.json
index 9e08dd0..72b23d2 100644
--- a/server/swagger/swagger-output.json
+++ b/server/swagger/swagger-output.json
@@ -8626,10 +8626,10 @@
           "Auth · Mobile"
         ],
         "summary": "Exchange an SSO authorization code for mobile tokens",
-        "description": "Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401.",
+        "description": "Redeems the single-use authorization code returned to the app callback, together with the PKCE code_verifier, for the SAME access + refresh pair as /auth/mobile/login. The code is single-use and PKCE-bound: a wrong verifier, an expired/used code, or a reused code all fail 401. If the user ticked \"trust this device\" on the TOTP form during this flow, the response also carries { trustToken } for the app to store and replay via X-Trust-Token — minted here rather than passed through the deep link so it never appears in a URL.",
         "responses": {
           "200": {
-            "description": "Access + refresh tokens",
+            "description": "Access + refresh tokens (optionally with a trustToken to persist)",
             "content": {
               "application/json": {
                 "schema": {
@@ -9057,10 +9057,10 @@
           "Auth · SSO"
         ],
         "summary": "Complete an SSO login with a TOTP code",
-        "description": "Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Rate limited and behind bot/backoff guards.",
+        "description": "Second step when a linked account has 2FA enabled. Reads the staged pending-TOTP cookie set by the callback plus the current authenticator code, and on success sets the session cookie. Set trustDevice to remember this browser and skip TOTP on future SSO sign-ins (30 days) — on the mobile flow this browser is the app Custom Tab, and the app additionally receives its own trustToken at /auth/mobile/sso/exchange. If the trusted-device limit is reached the sign-in still completes and the response carries { trustLimitReached, devices }. Rate limited and behind bot/backoff guards.",
         "responses": {
           "200": {
-            "description": "Session issued",
+            "description": "Session issued (web), or a deep link to redeem (mobile bridge); optionally with a trusted-device-limit prompt",
             "content": {
               "application/json": {
                 "schema": {
@@ -9071,6 +9071,18 @@
                     },
                     "returnTo": {
                       "type": "string"
+                    },
+                    "redirect": {
+                      "type": "string"
+                    },
+                    "trustLimitReached": {
+                      "type": "boolean"
+                    },
+                    "devices": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/TrustedDevice"
+                      }
                     }
                   }
                 }
@@ -9122,6 +9134,12 @@
                 "properties": {
                   "code": {
                     "type": "string"
+                  },
+                  "trustDevice": {
+                    "type": "boolean"
+                  },
+                  "deviceName": {
+                    "type": "string"
                   }
                 }
               }
diff --git a/server/test/ssoTrustedDevice.test.js b/server/test/ssoTrustedDevice.test.js
new file mode 100644
index 0000000..644e587
--- /dev/null
+++ b/server/test/ssoTrustedDevice.test.js
@@ -0,0 +1,216 @@
+// Point the DB at a closed port BEFORE requiring the controller (its models build
+// the pool). Every collaborator is monkeypatched, so no query runs.
+process.env.DB_HOST = '127.0.0.1'
+process.env.DB_PORT = '59999'
+
+const { test, after, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+// Trusted devices on the SSO paths. The gap these lock down: SSO used to jump
+// straight from needsTotp() to staging a challenge, so a browser the user had
+// explicitly trusted was still asked for a code on EVERY Google/Discord sign-in,
+// and the SSO second step had no way to establish trust at all.
+//
+// Covered here:
+//   - a trusted device (bound to THEM) skips the SSO second factor;
+//   - a trust bound to a DIFFERENT user is ignored — challenge as usual;
+//   - a store error falls back to the challenge (fail closed to asking);
+//   - the mobile bridge (Custom Tab) gets the same skip;
+//   - POST /auth/sso/totp with trustDevice sets the trust cookie, and flags the
+//     bridge session so /exchange can mint the app's own token;
+//   - at the device cap the sign-in still completes, with a trustLimitReached prompt.
+const ssoCtrl = require('../src/router/v1/auth/sso.controller')
+const users = require('../src/model/users/users.model')
+const activity = require('../src/model/activity/activity.model')
+const userIdentities = require('../src/model/userIdentities/userIdentities.model')
+const sessionService = require('../src/auth/session.service')
+const trustedDevices = require('../src/model/trustedDevices/trustedDevices.model')
+const mobileBridge = require('../src/model/mobileAuthBridge/mobileAuthBridge.model')
+const ssoState = require('../src/auth/ssoState')
+const totp = require('../src/utils/totp')
+const botScore = require('../src/middleware/botScore')
+const loginProtection = require('../src/middleware/loginProtection')
+const db = require('../src/utils/db')
+
+after(() => db.close())
+
+function mockRes() {
+  return {
+    statusCode: 200,
+    body: null,
+    cookies: {},
+    redirectedTo: null,
+    status(c) { this.statusCode = c; return this },
+    json(b) { this.body = b; return this },
+    cookie(name, val) { this.cookies[name] = val; return this },
+    clearCookie(name) { this.cookies[name] = undefined; return this },
+    redirect(to) { this.redirectedTo = to; return this },
+  }
+}
+
+const TOTP_USER = { id: 5, username: 'gwen', role: 'player', status: 'active', totp_enabled: 1, totp_secret: 'S' }
+
+let sessionsCreated
+const orig = {}
+beforeEach(() => {
+  sessionsCreated = []
+  for (const [mod, name] of [
+    [users, 'getRawById'], [users, 'getById'], [users, 'recordLogin'],
+    [activity, 'log'],
+    [userIdentities, 'findByProviderSubject'],
+    [sessionService, 'createSession'],
+    [sessionService, 'resolveTrustedDevice'], [sessionService, 'honorTrustedDevice'],
+    [sessionService, 'trustDeviceCapReached'], [sessionService, 'mintTrustToken'], [sessionService, 'sessionMeta'],
+    [trustedDevices, 'store'], [trustedDevices, 'listActiveForUser'],
+    [mobileBridge, 'getSession'], [mobileBridge, 'markTrustRequested'], [mobileBridge, 'issueAuthCode'],
+    [ssoState, 'createTotpPending'], [ssoState, 'verifyTotpPending'],
+    [totp, 'verifyCode'],
+    [botScore, 'recordLoginFailure'], [loginProtection, 'recordFailure'], [loginProtection, 'recordSuccess'],
+  ]) {
+    orig[name] = orig[name] || { mod, val: mod[name] }
+  }
+  users.recordLogin = async () => {}
+  activity.log = async () => {}
+  botScore.recordLoginFailure = () => {}
+  loginProtection.recordFailure = () => {}
+  loginProtection.recordSuccess = () => {}
+  sessionService.createSession = (user, authMethod) => {
+    sessionsCreated.push({ user, authMethod })
+    return { token: 'session-token' }
+  }
+  sessionService.honorTrustedDevice = async () => true
+  sessionService.sessionMeta = () => ({ deviceHash: 'dh', userAgent: 'UA' })
+  sessionService.trustDeviceCapReached = async () => false
+  sessionService.mintTrustToken = () => ({
+    trustToken: 'raw-trust', trustHash: 'hash', deviceHash: 'dh', userAgent: 'UA', expiresAt: new Date(Date.now() + 1e6),
+  })
+  trustedDevices.store = async () => 1
+  ssoState.createTotpPending = () => 'pending-jwt'
+  userIdentities.findByProviderSubject = async () => ({ user_id: 5 })
+  users.getById = async () => TOTP_USER
+})
+afterEach(() => {
+  for (const key of Object.keys(orig)) { orig[key].mod[key] = orig[key].val; delete orig[key] }
+})
+
+const baseReq = (body = {}) => ({ body, ip: '10.0.0.1', headers: {}, cookies: {} })
+const tx = { returnTo: '/account' }
+const profile = { subject: 'sub-1', email: 'g@example.test' }
+
+// ── finishLogin(): trusted device skips the SSO second factor ──────────────
+test('sso login: a TOTP user on a device trusted by THEM skips the code', async () => {
+  users.getRawById = async () => TOTP_USER
+  sessionService.resolveTrustedDevice = async () => ({ id: 11, user_id: 5 })
+  let honored = null
+  sessionService.honorTrustedDevice = async (id) => { honored = id }
+
+  const res = mockRes()
+  await ssoCtrl.finishLogin(baseReq(), res, 'google', 'sso', tx, profile)
+
+  assert.equal(sessionsCreated.length, 1, 'session issued without a TOTP bounce')
+  assert.equal(honored, 11, 'the trusted device was stamped as used')
+  assert.ok(!String(res.redirectedTo).includes('sso_totp'), `did not bounce to the code form (got ${res.redirectedTo})`)
+})
+
+test('sso login: a trust bound to a DIFFERENT user is ignored (code still required)', async () => {
+  sessionService.resolveTrustedDevice = async () => ({ id: 11, user_id: 999 })
+
+  const res = mockRes()
+  await ssoCtrl.finishLogin(baseReq(), res, 'google', 'sso', tx, profile)
+
+  assert.match(String(res.redirectedTo), /sso_totp=1/)
+  assert.equal(sessionsCreated.length, 0)
+})
+
+test('sso login: a trusted-device lookup error falls back to the code (fail closed)', async () => {
+  sessionService.resolveTrustedDevice = async () => { throw new Error('store down') }
+
+  const res = mockRes()
+  await ssoCtrl.finishLogin(baseReq(), res, 'google', 'sso', tx, profile)
+
+  assert.match(String(res.redirectedTo), /sso_totp=1/)
+  assert.equal(sessionsCreated.length, 0)
+})
+
+// ── finishSsoTotp(): the second step can now establish trust ───────────────
+test('sso totp: trustDevice sets the trust cookie and completes the sign-in', async () => {
+  ssoState.verifyTotpPending = () => ({ id: 5, provider: 'google', authMethod: 'sso', returnTo: '/account' })
+  users.getRawById = async () => TOTP_USER
+  totp.verifyCode = () => true
+
+  const res = mockRes()
+  await ssoCtrl.finishSsoTotp(baseReq({ code: '123456', trustDevice: true, deviceName: 'Kitchen laptop' }), res)
+
+  assert.equal(res.statusCode, 200)
+  assert.equal(res.cookies.rg_trust, 'raw-trust', 'trust cookie issued')
+  assert.equal(res.body.user.id, 5)
+  assert.equal(res.body.trustLimitReached, undefined)
+})
+
+test('sso totp: without trustDevice no trust cookie is set', async () => {
+  ssoState.verifyTotpPending = () => ({ id: 5, provider: 'google', authMethod: 'sso', returnTo: '/account' })
+  users.getRawById = async () => TOTP_USER
+  totp.verifyCode = () => true
+
+  const res = mockRes()
+  await ssoCtrl.finishSsoTotp(baseReq({ code: '123456' }), res)
+
+  assert.equal(res.statusCode, 200)
+  assert.equal(res.cookies.rg_trust, undefined)
+})
+
+test('sso totp: at the device cap the sign-in still succeeds, with a trustLimitReached prompt', async () => {
+  ssoState.verifyTotpPending = () => ({ id: 5, provider: 'google', authMethod: 'sso', returnTo: '/account' })
+  users.getRawById = async () => TOTP_USER
+  totp.verifyCode = () => true
+  sessionService.trustDeviceCapReached = async () => true
+  trustedDevices.listActiveForUser = async () => [{ id: 1, platform: 'web' }]
+
+  const res = mockRes()
+  await ssoCtrl.finishSsoTotp(baseReq({ code: '123456', trustDevice: true }), res)
+
+  assert.equal(res.statusCode, 200)
+  assert.equal(res.body.trustLimitReached, true)
+  assert.equal(res.cookies.rg_trust, undefined, 'no cookie when the cap refused the trust')
+  assert.equal(sessionsCreated.length, 1, 'the session is still issued')
+})
+
+// ── mobile bridge: the Custom Tab gets the same treatment ──────────────────
+test('sso totp (mobile bridge): trustDevice flags the session so /exchange can mint the app token', async () => {
+  ssoState.verifyTotpPending = () => ({ id: 5, provider: 'google', authMethod: 'sso', mobileSessionId: 'sess-1' })
+  users.getRawById = async () => TOTP_USER
+  totp.verifyCode = () => true
+  mobileBridge.getSession = async () => ({
+    session_id: 'sess-1', status: 'pending', expires_at: new Date(Date.now() + 60000),
+    redirect_uri: 'runicgateway://auth/callback', state: 'st',
+  })
+  mobileBridge.issueAuthCode = async () => ({ code: 'authcode' })
+  let flagged = null
+  mobileBridge.markTrustRequested = async (id) => { flagged = id; return true }
+
+  const res = mockRes()
+  await ssoCtrl.finishSsoTotp(baseReq({ code: '123456', trustDevice: true }), res)
+
+  assert.equal(flagged, 'sess-1', 'bridge session flagged for the app-side trust token')
+  assert.equal(res.cookies.rg_trust, 'raw-trust', 'the Custom Tab browser is trusted too')
+  assert.match(String(res.body.redirect), /^runicgateway:\/\/auth\/callback/)
+})
+
+test('sso totp (mobile bridge): without trustDevice the session is not flagged', async () => {
+  ssoState.verifyTotpPending = () => ({ id: 5, provider: 'google', authMethod: 'sso', mobileSessionId: 'sess-1' })
+  users.getRawById = async () => TOTP_USER
+  totp.verifyCode = () => true
+  mobileBridge.getSession = async () => ({
+    session_id: 'sess-1', status: 'pending', expires_at: new Date(Date.now() + 60000),
+    redirect_uri: 'runicgateway://auth/callback', state: 'st',
+  })
+  mobileBridge.issueAuthCode = async () => ({ code: 'authcode' })
+  let flagged = null
+  mobileBridge.markTrustRequested = async (id) => { flagged = id; return true }
+
+  const res = mockRes()
+  await ssoCtrl.finishSsoTotp(baseReq({ code: '123456' }), res)
+
+  assert.equal(flagged, null)
+  assert.equal(res.cookies.rg_trust, undefined)
+})