android/PLAN.md

@@ -544,25 +544,37 @@ Uses the existing **mobile bearer** surface, no backend changes:
 - `POST /auth/mobile/logout` `{ refreshToken?, all? }` (requires bearer) — revoke this session or all
   sessions. Called on user logout and on "sign out everywhere."
 
-#### 4.1.1 Trusted devices & recovery codes — backend ready, app work sequenced after backend
+#### 4.1.1 Trusted devices & recovery codes — **implemented** (app PR `feature/trusted-devices-mfa`)
 The backend trusted-device + recovery-code feature (canonical ref: `../website/TRUSTED_DEVICES_MFA.md`)
-is additive on the mobile surface; the app consumes it as follows (implemented **after** the backend
-lands, alongside the account screens):
+is additive on the mobile surface. As built:
 - **Login extras:** `POST /auth/mobile/login` accepts `recoveryCode` (a single-use alternative to
-  `code`), `trustDevice: true`, and an `X-Trust-Token` header. On the `401 { totpRequired }` screen,
-  offer "use a recovery code instead" and a **"Trust this device"** checkbox. When `trustDevice` is set
-  and accepted, the response carries `trustToken` → **store it in EncryptedSharedPreferences** (same
-  store as the bearer tokens, never plain prefs/logs) and send it as `X-Trust-Token` on future logins
-  to skip the TOTP prompt. A `{ trustLimitReached, devices }` response means show the device list and
-  prompt the user to revoke one (`DELETE /auth/me/trusted-devices/:id`) then retry.
-- **Self-service (account screens):** `GET /auth/me/trusted-devices`, `DELETE …/:id`, `DELETE
-  …/trusted-devices` (untrust all); `POST /auth/me/trusted-devices` to trust the current device from an
-  authenticated session (returns `{ trustToken }` for native). Recovery codes: enabling TOTP returns
-  the one-time `recoveryCodes` (show once, offer copy/share); `GET …/recovery-codes/status` for the
-  remaining count; `POST …/recovery-codes/generate` (password step-up) to regenerate.
-- **Invalidation:** on logout / dead-refresh sign-out / Settings→Server switch, **clear the stored
-  `trustToken`** along with the bearer tokens (a password change/reset or TOTP disable already revokes
-  it server-side).
+  `code`), `trustDevice: true`, `device_name`, and an `X-Trust-Token` header. On the `401 { totpRequired }`
+  screen the app offers a "use a recovery code instead" toggle and a **"Trust this device"** checkbox.
+  When `trustDevice` is accepted, the response carries `trustToken` → stored in a **dedicated
+  EncryptedSharedPreferences file** (`runic_trust`, AES-256-GCM; never plain prefs/logs) **scoped to the
+  username** it was minted for, and replayed as `X-Trust-Token` on that account's future logins to skip
+  the TOTP prompt.
+- **Login-time cap:** a `{ trustLimitReached, devices }` response means login **succeeded** but the
+  device was not remembered (session is already issued on native, unlike the web cookie step). Rather
+  than a blocking login-time modal, this is surfaced + resolved on the **Trusted Devices** account
+  screen, whose `POST /auth/me/trusted-devices` gives the exact revoke-one-then-retry flow. (Deliberate
+  deviation from the earlier "prompt at login" sketch — the mobile login is past the point a modal would
+  gate.)
+- **Self-service (account screens):** a **Security** section on the account screen links to two
+  dedicated screens. **Trusted Devices** — `GET /auth/me/trusted-devices` (list), `DELETE …/:id`
+  (revoke one), `DELETE …/trusted-devices` (untrust all), and `POST /auth/me/trusted-devices` to trust
+  the current device (stores the returned `{ trustToken }`). **Recovery Codes** — enabling TOTP returns
+  the one-time `recoveryCodes` (shown once on the account screen with copy/share); `GET
+  …/recovery-codes/status` for the remaining count; `POST …/recovery-codes/generate` (password step-up)
+  to regenerate, shown once.
+- **Invalidation — trust token deliberately survives logout.** The trust token is the native analogue
+  of the web `rg_trust` cookie, which per the canonical design *survives logout so the next login skips
+  2FA*. On mobile the token is only ever consulted at a **fresh** login — i.e. exactly after a logout or
+  a dead-refresh sign-out — so clearing it there would make the feature a no-op. It is therefore kept in
+  its own store, **untouched by session teardown** (`SessionManager.onSignedOut`), and cleared only on a
+  **Settings → Server switch** (bound to the old host), an **untrust-all**, or server-side revocation
+  (password change/reset, TOTP disable — which makes any surviving token inert; the next login just
+  prompts for the code). This supersedes the earlier handoff note that said to clear it on logout.
 
 ### 4.2 Website-handled flows: registration, invite, forgot-password, SSO
 These are **not** rebuilt in the app. The app links out to the website's own pages/API and the user