Have My Session Securely Persisted So I Do Not Need to Log In Every Time I Open the App
After successful authentication, the Supabase session token and related credentials must be stored in the device's secure storage (iOS Keychain / Android Keystore) rather than in-memory or in plain local storage. The session resume manager should check for a valid persisted session on app launch and, if found, resume the session silently or via biometric confirmation. The session must have a configurable expiry and must be invalidated on logout, organization switch, or explicit biometric disable. This is the infrastructure layer that makes biometric re-authentication meaningful.
User Story
Audience Summaries
Secure session persistence is the foundational infrastructure that makes the entire biometric authentication experience viable and is a prerequisite for the product being practical as a daily-use tool. Without encrypted token storage, every app launch forces peer mentors through a full BankID or Vipps re-authentication flow taking 30 to 60 seconds — making the app impractical for the high-frequency daily usage required to capture 380+ activities per year. Beyond usability, storing session credentials in encrypted device storage (iOS Keychain, Android Keystore) is a data security obligation: peer mentors access sensitive contact and health-adjacent information, and plaintext credential storage would represent a serious compliance and reputational risk for all four partner organizations. This story directly addresses both the underreporting problem and the organization's duty of care around user data protection.
This story is a critical infrastructure dependency that must be completed before biometric authentication (Story 133) can be implemented or tested. It involves platform-specific secure storage integration on both iOS and Android, session lifecycle management (creation, expiry, invalidation, multi-tenant context switching), and coordination with the authentication service team. Acceptance criteria cover six scenarios including encrypted write verification, silent resume, expiry handling, logout invalidation, organization switch clearing, and background timeout re-authentication. Testing requires validation on both platforms with real devices and must include negative tests for expired tokens and organization switching edge cases.
The configurable session timeout value should be agreed with partner organizations and security stakeholders before implementation begins, as it affects both security posture and user experience.
Implementation requires platform-specific secure storage adapters: flutter_secure_storage (backed by iOS Keychain and Android Keystore) must be used for all token writes — SharedPreferences and localStorage are explicitly excluded per acceptance criteria. The session resume manager must run on app cold start, check for a valid non-expired token, and branch into either silent resume or biometric confirmation trigger. Session expiry must be enforced both on cold start and on foreground resume after background timeout, with redirect to the login screen on expiry. Logout must atomically clear both the session token and any stored biometric credential from secure storage.
Organization switching must clear the previous tenant's session and write a new session scoped to the correct tenant context before resuming. Edge cases include token corruption, keychain access errors (e.g., device not unlocked), and concurrent session invalidation from server-side logout events.
Acceptance Criteria
- Given I successfully authenticate, When the session token is stored, Then it is written to encrypted secure storage (iOS Keychain or Android Keystore), never to plain SharedPreferences or localStorage
- Given a valid session is persisted, When I open the app after closing it, Then the session resume manager detects the token and either resumes silently or triggers biometric confirmation
- Given a persisted session has expired, When I open the app, Then I am redirected to the login screen with a clear message that my session has ended
- Given I log out explicitly, When logout completes, Then the session token and biometric credential are both removed from secure storage
- Given I switch organizations, When the switch completes, Then the old organization's session is cleared and the new session is stored with the correct tenant context
- Given the app is in the background for more than the configured session timeout, When I return to the app, Then I am prompted to re-authenticate via biometrics before accessing data
Business Value
Secure session persistence is the technical foundation for the biometric authentication feature. Without it, every app launch requires full BankID/Vipps re-authentication, which would take 30–60 seconds per login and make the app impractical for high-frequency daily use. This directly addresses the underreporting problem by removing the largest single friction point in the activity registration workflow. Encrypted storage is also a data security obligation given that peer mentors access sensitive contact information.
Components
- Session Resume Manager service
- Secure Session Storage data
- Supabase Session Manager infrastructure
- Auth Token Store data
- Secure Storage Adapter infrastructure
- Authentication Session Manager service
- Secure Storage Adapter infrastructure
- Tenant Session Store data
- Authentication Repository data
- Supabase Auth Client infrastructure