fix(auth): F8 — stop intermittent mobile forced re-login (token loss)

[ahmetabdullahgultekin]

F8 — mobile app prompts for login randomly/inconsistently

By design: access token TTL = 15 min, refresh TTL = 24 h (sliding). An actively-used app should never re-prompt; the only normal forced re-login is after ~24 h of inactivity. The intermittent premature prompts ("sometimes asks, sometimes doesn't") were bugs. Full analysis: docs/LOGIN_TRIAGE_2026-06-12.md (F8 verdict).

All changes are in :shared (commonMain), so they apply to Android + Desktop. Pure auth-resilience hardening — no API/contract change.

Root cause 1 (primary) — session wiped on ANY transient refresh failure — commit b4cf47d3

NetworkModule.refreshAccessToken cleared the entire persisted session on any refresh failure: the blanket catch (_) { clearTokens() } plus the non-200 branches wiped tokens on every timeout / dropped keep-alive / brief offline / Traefik HTTP/2 stale-conn RST / 5xx / 429. A transient blip logged the user fully out → intermittent re-prompt.

Fix: distinguish a definitive auth failure (HTTP 400/401 invalid_grant from the refresh-token grant → token truly dead) from a transient failure (IOException/timeout/RST, or a non-auth non-200 such as 5xx/429). clearTokens() runs only on a definitive failure; transient failures return false without clearing, so only the in-flight request fails and the session survives the next attempt. Added isDefinitiveAuthFailure(status).

Root cause 2 — refresh-token reuse-detection family-revoke from uncoordinated refresh — commit 81b25ac3

The server revokes the whole rotation family if an already-rotated refresh token is re-presented. refreshMutex only serialized refreshes within the identity client; the biometric client had NO refresh interceptor and was outside the mutex, so a biometric 401 racing an identity refresh (or presenting a token rotated out from under it) could re-present the old token → family revoke → all sessions logged out non-deterministically.

Fix: extract the identity client's HttpSend refresh-on-401 + single-retry into a shared installRefreshOn401(client, tokenManager) and install it on both clients. Both now funnel every 401 through the same refreshAccessToken and the same module-level refreshMutex, so only one rotation is ever in flight. The refresh targets the identity token endpoint via absolute URLs, so driving it from the biometric client is correct. (Identity path = pure extraction, no behavior change.)

Root cause 3 (hardening) — empty-string refresh token — commit 9e31ce3a

AuthDto.toModel() maps a missing refresh_token to "". On a 200 refresh that omits a new refresh token (rotation disabled), the old code overwrote the stored token with "" → the next refresh had no token → forced re-login.

Fix:

• On a 200 refresh, keep the existing refresh token when the response omits one (oauth.refreshToken.ifBlank { refreshToken }), in both the OAuth and legacy /auth/refresh branches (mirrors the desktop RefreshInterceptor's "reuse if rotation disabled").
• TokenManager.getAccessToken/getRefreshToken treat a blank "" stored value as absent (return null), so a "" never looks like a usable token and isAuthenticated() falls back correctly.

Tests

./gradlew :shared:desktopTest — 12 new unit tests, all green:

• RefreshTokenResilienceTest (8): transient 503 / transport-error / legacy 5xx keep the session; definitive 400/401 clear it; 200 happy path; 200-without-refresh_token preserves the old token; isDefinitiveAuthFailure classification.
• TokenManagerBlankTokenTest (4): blank access/refresh read back as null; not-authenticated on blank-only refresh; authenticated on a real refresh token.

Compile result

• ./gradlew :shared:compileDebugKotlinAndroid — BUILD SUCCESSFUL (Android target).
• ./gradlew :shared:desktopTest — BUILD SUCCESSFUL, 12/12 green.
• No emulator/instrumented tests run (host has no KVM) — by project policy.

Release / rollback note (live mobile auth path)

This is the live mobile auth path. To verify on a real device, the owner must rebuild a signed APK and cut a new release tag (e.g. v5.3.2) — the change ships only in the APK:
gh workflow run android-build.yml -R Rollingcat-Software/client-apps --ref main -f build_type=release
Reversibility: if anything regresses, roll back by installing the prior release APK (same signing cert since v5.2.x → installs in place); no server change is involved.

Scope note

This PR is F8 only (client-apps / Kotlin). The other live-test findings (F1–F7, F9, F10) are web-app / backend and tracked separately; coordinator messages about web-app PR #204 / the approve-QR→MFA bridge / picker gating are a different repo and out of scope here.