Session Resume Manager
Component Detail
Description
Listens to Flutter app lifecycle events and decides whether to show the biometric prompt when the app returns to the foreground. Checks if the existing Supabase session is still valid before prompting. If the session has expired, redirects to full credential login instead.
session-resume-manager
Summaries
The Session Resume Manager directly protects user accounts and reduces friction in the mobile authentication experience. By intelligently deciding when to re-verify a user's identity after the app returns to the foreground, it balances security with convenience — users are only prompted when necessary, not on every app switch. This reduces abandonment caused by excessive authentication prompts while maintaining compliance with security policies. When a session has expired, the component automatically routes users to full credential login, preventing unauthorized access and reducing the risk of account compromise.
For a mobile product competing on user experience, seamless and secure session handling is a meaningful differentiator that directly impacts retention and trust.
The Session Resume Manager has medium complexity and depends on two foundational services: the Biometric Auth Service and Secure Session Storage, both of which must be completed and stable before this component can be fully tested. Its integration with Flutter's WidgetsBindingObserver lifecycle API requires careful testing across Android and iOS, particularly around edge cases like rapid app switching, background timers, and OS-level interruptions. QA must cover scenarios where the session is valid, expired, or borderline-expired during resume. Debounce logic for rapid foreground/background transitions adds test surface area.
Plan for dedicated device testing across platform versions. Failure to handle edge cases here can cause duplicate prompts or missed authentication challenges, which are high-visibility user-facing bugs.
Session Resume Manager implements WidgetsBindingObserver to hook into Flutter's AppLifecycleState.resumed lifecycle event. On each resume, it calls shouldPromptBiometric(), which reads session validity from SecureSessionStorage.isSessionValid() before deciding the routing path. If the session is valid, it triggers the BiometricAuthService prompt; if expired, it navigates to the credential login screen via handleSessionExpired(). Debouncing is required to prevent duplicate prompt invocations during rapid foreground/background transitions — a simple timestamp-based guard or a boolean lock is sufficient.
The component must be initialized in the root widget tree and disposed correctly to avoid memory leaks from the WidgetsBinding observer. initialize() and dispose() are the lifecycle anchors. No direct Supabase dependency — all session reads flow through SecureSessionStorage.
Responsibilities
- Observe AppLifecycleState.resumed events via WidgetsBindingObserver
- Validate current session expiry from secure storage before prompting
- Route to biometric prompt if session valid, or credential login if session expired
- Debounce rapid foreground/background transitions to prevent duplicate prompts
Interfaces
initialize()
dispose()
onAppResumed()
shouldPromptBiometric()
handleSessionExpired()
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (2)
Data entities managed by this component
Used Integrations (2)
External integrations and APIs this component relies on