Persist Refresh Token in Secure Storage vs. In‑Memory Only: Trade‑off for Least‑Privilege Auth in Ionic Capacitor Apps

Direct Answer

Store the refresh token in Secure Storage (hardware-backed keystore), not in memory only. Persist it with biometric/device-credential gating so the OS requires user presence to unlock. Trigger a silent refresh on foreground only when the access token is near expiry (e.g., <5 min); otherwise rely on 401 interception for the actual renewal. This hybrid gives you seamless session continuity after restarts/OS updates while keeping the proactive attack surface minimal.

Why This Combination Wins

Secure Storage vs In-Memory

• Secure Storage (Capacitor Secure Storage plugin → iOS Keychain / Android Keystore/EncryptedSharedPreferences) survives process death, OS updates, and memory pressure. In-memory tokens vanish on any cold start, forcing full re-auth — unacceptable for offline-first or push-notification flows.
• Mitigate theft risk by: (a) short refresh-token TTL (7–30 days), (b) rotation on every use (RFC 6819), (c) device binding (include a hardware fingerprint in the token request), and (d) biometric gating so a stolen device dump still can't extract the token without user auth.
• Web/PWA fallback: Secure Storage plugins are unavailable in browsers. Detect platform at runtime and fall back to in-memory + short-lived access tokens for web builds.

Foreground Silent Refresh vs Pure 401 Interception

• Pure 401 interception is reactive: adds ~1 RTT latency on the first request after expiry, but zero proactive network calls. Works naturally with offline queues (retry on reconnect). Must deduplicate concurrent 401s with a single refresh promise to avoid token-revocation storms.
• Foreground silent refresh (Capacitor App.addListener('resume', …)) renews before the user acts, eliminating that latency spike. Risk: a compromised foreground app can silently mint new access tokens. Mitigate by only refreshing when JWT exp claim shows expiry within a short threshold (5 min) and by adding jitter/backoff to avoid IDP rate limits on mass resume.
• Hybrid: check expiry locally on resume; if far from expiry, do nothing. If close, attempt silent refresh. If that fails (offline, rate-limited, revoked), the next API call hits 401 and the interceptor handles it. This keeps the common case fast and the edge cases safe.

Implementation Checklist

1. Use @capacitor-community/secure-storage (or native Keychain/Keystore wrappers), NOT @capacitor/preferences (plaintext).
2. Configure Keychain access control (kSecAccessControlBiometryCurrentSet) and Android BiometricPrompt so token read requires fresh biometric/device credential.
3. On app resume: decode stored refresh token's JWT (if JWT) or track issued-at/expires-in locally; if exp - now < 5 min, call refresh endpoint with jitter (0–2 s).
4. HTTP interceptor: on 401, inspect error code (not just status). token_expired → single refresh promise → retry original request. refresh_revoked / refresh_expired → clear storage → force logout.
5. Offline queue: persist mutations locally; on successful refresh after reconnect, replay queue.
6. Test: kill process (swipe recents), restart → session restored. Airplane mode + resume → no silent refresh attempt. 10 concurrent expired-token calls → exactly one refresh request. Rooted device / Keychain dumper → no plaintext tokens.

One Diagnostic Detail Needed

What is your minimum supported Android API level? Hardware-backed Keystore (required for non-extractable keys) needs API 23+. If you must support API 21–22, Secure Storage falls back to software-only encryption — adjust threat model accordingly.