Secure Session Storage
Component Detail
Description
Encrypted key-value store backed by flutter_secure_storage that persists the Supabase session token, its expiry timestamp, and the user's biometric preference flag. Shared across all authentication features for a single source of truth on session state.
secure-session-storage
Summaries
Secure Session Storage is the security foundation for all user authentication in the mobile application. By storing session tokens, expiry timestamps, and biometric preferences in an encrypted key-value store backed by the device's secure enclave, it ensures that sensitive credentials are never exposed in plain text on the device. This directly reduces the risk of credential theft from device backups, rooted devices, or memory inspection. As a shared component used across all authentication features, it provides a single, consistent source of truth for session state — eliminating the risk of inconsistent behavior that could lead to security gaps or a degraded user experience.
Investing in this component reduces regulatory and compliance risk and demonstrates commitment to data protection best practices.
Secure Session Storage is a low-complexity, zero-external-dependency component, making it an ideal early deliverable that unblocks multiple downstream features. It must be implemented and validated before the Session Resume Manager, Biometric Auth Service, or any other authentication flow can be meaningfully tested end-to-end. Because it is a shared component, any API changes after initial delivery will have cascading impact across all consumers — interface stability is critical. Testing must cover encryption correctness, data persistence across app restarts, proper clearing on logout, and behavior on first install when no session exists.
Android Keystore and iOS Keychain behaviors differ subtly; cross-platform testing is mandatory. Treat this as a foundational dependency in the project schedule.
Secure Session Storage wraps flutter_secure_storage with a typed API, abstracting raw key-value operations behind domain-specific methods. saveSession(token, expiresAt) and getSession() handle Supabase JWT persistence. isSessionValid() computes validity by comparing the stored expiresAt timestamp against DateTime.now(), returning false if absent or expired. setBiometricEnabled(bool) and isBiometricEnabled() manage the per-user biometric enrollment flag independently from session state.
saveUserId(id) and getUserId() support user context without requiring a full session decode. All keys should be namespaced (e.g., 'auth.session.token') to avoid collisions. clearSession() must wipe all auth-related keys atomically. Since this is shared across features, avoid adding feature-specific logic here — keep it a pure persistence layer.
No async caching layer is needed given flutter_secure_storage's read performance.
Responsibilities
- Persist and retrieve encrypted Supabase session tokens
- Store and read session expiry timestamps for validity checks
- Manage biometric preference and enrollment flags per user
- Clear all stored credentials on logout or token invalidation
Interfaces
saveSession(token, expiresAt)
getSession()
clearSession()
isSessionValid()
setBiometricEnabled(bool)
isBiometricEnabled()
saveUserId(id)
getUserId()
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component