get to prod tasks

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

@@ -0,0 +1,77 @@
+# 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