Kordant/tasks/android-production/22-token-refresh.md

22. Token Refresh & Session Management

meta: id: android-production-22 feature: android-production priority: P1 depends_on: [android-production-21] tags: [backend, auth, production]

objective:

• Implement automatic token refresh and robust session management to prevent unexpected logouts

deliverables:

• OkHttp authenticator for token refresh
• Token refresh interceptor
• Silent re-authentication flow
• Session expiry handling

steps:

1. Implement OkHttp authenticator:
   • Add Authenticator to OkHttp client in NetworkModule.kt
   • Detect 401 responses
   • Attempt refresh with refresh token
   • Retry original request with new token
2. Handle concurrent requests:
   • Use Mutex or synchronized block to prevent duplicate refresh
   • Queue requests while refresh in progress
   • Use Kotlin coroutines for async coordination
3. Add token refresh endpoint:
   • Ensure backend supports refresh token endpoint
   • Implement refresh in AuthRepository
   • Store new access and refresh tokens
4. Implement proactive refresh:
   • Parse JWT expiry claim
   • Refresh 5 minutes before expiry
   • Schedule refresh on app foreground
5. Handle edge cases:
   • Refresh token expired → logout user
   • Network unavailable → queue and retry
   • Refresh fails → prompt re-authentication
6. Update AuthViewModel:
   • Expose session state
   • Handle refresh failures gracefully
   • Auto-logout on persistent auth failures
7. Add tests:
   • Test token refresh logic
   • Test concurrent request handling
   • Test session expiry scenarios

tests:

• Unit: Test authenticator with MockWebServer
• Integration: Test refresh flow end-to-end
• E2E: Test session expiry behavior

acceptance_criteria:

• Token refresh automatic and transparent to user
• Concurrent requests queued during refresh
• Proactive refresh 5 minutes before expiry
• Biometric re-auth offered if refresh fails
• Session restored on app relaunch (if tokens valid)
• Graceful logout if all auth methods fail
• No duplicate refresh requests
• Background refresh on app foreground
• Unit tests covering all refresh scenarios
• MockWebServer tests for authenticator

validation:

• Wait for token expiry → app refreshes automatically
• Trigger 401 → refresh attempted, request retried
• Revoke refresh token → app prompts re-auth
• Background app → foreground → token refreshed if needed
• Check logs → no duplicate refresh requests

notes:

• OkHttp Authenticator is the standard way to handle 401s
• Use EncryptedSharedPreferences for token storage
• Consider using Credential Manager for modern auth (API 34+)
• Backend must support refresh token endpoint