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

22. Token Refresh & Session Management

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

objective:

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

deliverables:

• Token refresh interceptor in APIClient
• Silent re-authentication flow
• Session expiry handling
• Concurrent request queue during refresh

steps:

1. Implement token refresh:
   • Add refresh token endpoint to backend if not exists
   • Modify APIClient to detect 401 responses
   • On 401, attempt token refresh with refresh token
   • Retry original request with new token
2. Handle concurrent requests:
   • Queue requests while refresh in progress
   • Don't duplicate refresh requests
   • Use Combine or async/await for coordination
3. Add silent re-authentication:
   • If refresh fails, try biometric re-auth
   • If biometric fails, prompt for password
   • If all fail, logout user
4. Implement session expiry:
   • Parse JWT expiry claim
   • Proactively refresh before expiry (5 min buffer)
   • Schedule background refresh
5. Add session monitoring:
   • Track session age
   • Alert user when session nearing expiry
   • Auto-refresh on app foreground
6. Handle edge cases:
   • Refresh token also expired → full re-auth
   • Network unavailable during refresh → queue and retry
   • Multiple tabs/apps refreshing simultaneously
7. Update AuthService:
   • Expose session state
   • Handle refresh failures gracefully
   • Notify UI of re-authentication needs

tests:

• Unit: Test token refresh logic
• Integration: Test concurrent request handling
• E2E: Test session expiry and refresh

acceptance_criteria:

• Token refresh automatic and transparent to user
• Concurrent requests queued during refresh, not failed
• 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

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:

• Current APIClient has retry logic but no token refresh
• Backend must support refresh token endpoint
• Consider using OAuth 2.0 refresh token flow
• Store refresh token with higher security than access token