Remain Logged In Across App Restarts
Session persistence is essential for a field-use app. Peer mentors register activities in brief moments between interactions — they cannot be expected to log in every session. After a successful email/password login, the auth token must be stored securely in encrypted device storage. On subsequent launches, the session manager checks for a valid token and restores the authenticated state transparently. If the token has expired or been revoked, the user is redirected to the login screen with a clear explanation.
User Story
Audience Summaries
Session persistence is the highest-impact usability improvement available for field-deployed applications like this one. Peer mentors operate in fast-paced, interpersonal environments where stopping to re-authenticate between sessions is a genuine barrier to data capture. HLF documented a single peer mentor completing 380 individual activity registrations in one year — requiring login for each session would create unacceptable friction and directly reduce reporting completeness. By storing credentials securely and restoring authenticated state transparently on relaunch, the app removes the single largest usability obstacle for returning users.
This directly increases registration completion rates, improves the volume and quality of data submitted to Bufdir, and strengthens the organisation's ability to demonstrate impact to funders. Persistent sessions are table-stakes for any field-use mobile application and are critical to user retention and long-term engagement.
This is a critical-priority story with a dependency on the email/password login story (story-email-password-login-peer-mentor-001) and must be sequenced accordingly. Delivery involves implementing secure token storage using platform-native encrypted APIs (iOS Keychain, Android Keystore), a session manager that validates tokens with Supabase on launch within a 1-second performance budget, and a graceful token expiry flow with clear user messaging. Five acceptance criteria span the happy path, expiry handling, sign-out, and server-side revocation (401 response handling), all of which require dedicated test coverage. QA must include cold-start timing benchmarks across target devices, token expiry simulation, and sign-out verification.
Stakeholder review should confirm the approved session expiry duration with the security team. The 1-second validation SLA on normal connections introduces a risk if Supabase cold-start latency is not accounted for — the team should validate this early.
Implementation requires integrating a secure encrypted storage library (e.g., expo-secure-store or react-native-keychain) to persist the Supabase auth token after successful login. A SessionManager service must be introduced to run at app launch, read the stored token, validate it against the Supabase auth API, and route the user to the appropriate screen — home on success, login on expiry or absence. The validation call must complete within 1 second on a normal connection, so a loading/splash state is required to avoid layout flicker. The sign-out handler must explicitly delete the token from secure storage, not merely clear in-memory state.
A global 401 interceptor should detect server-side revocation mid-session and trigger the same secure-storage-clear and redirect flow. Edge cases include devices with no secure storage API, token decode errors, and Supabase API timeouts — each must be handled gracefully. Unit tests should cover all five acceptance criteria branches.
Acceptance Criteria
- Given the user has successfully logged in, When the user closes the app completely and reopens it, Then the app navigates directly to the peer mentor home screen without showing the login form
- Given a stored session token exists, When the app launches, Then the session manager validates the token with Supabase before routing the user, completing within 1 second on a normal connection
- Given the stored token has expired, When the app launches, Then the user is redirected to the login screen with the message 'Your session has expired. Please sign in again.'
- Given the user explicitly signs out, When the sign-out action is confirmed, Then the stored token is deleted from secure storage and the user is returned to the login screen
- Given the device is compromised or the token revoked server-side, When the next authenticated API call fails with 401, Then the app clears local session data and redirects to login
Business Value
Session persistence is the single most important usability factor for field workers. HLF noted one peer mentor with 380 individual registrations in a year — requiring login for each would be untenable. Persistent sessions reduce friction to near zero for returning users, directly increasing registration completion rates and the quality of data available for Bufdir reporting.
Components
- Authentication Session Manager service
- Auth Token Store data
- Secure Storage Adapter infrastructure
- Session Resume Manager service
- Secure Session Storage data
- Supabase Session Manager infrastructure
Dependencies
- Sign In with Email and Password critical