Supabase Session Manager
Component Detail
Description
Centralized service responsible for Supabase session lifecycle operations including token refresh, session validation, and sign-out. Shared across all login features to ensure consistent session handling. On successful biometric auth, it calls refreshSession() to extend the active token.
supabase-session-manager
Summaries
Supabase Session Manager is the backbone of user authentication continuity across the application. It ensures that once a user logs in — whether via password, biometrics, or SSO — their session remains active and secure without requiring repeated logins. This directly impacts user satisfaction and reduces abandonment caused by unexpected logouts or token expiry errors. By centralizing session management, the business avoids duplicated authentication logic across features, which lowers maintenance costs and reduces the attack surface for session-related security vulnerabilities.
As a shared service, it provides a single point of control for session policy enforcement, enabling rapid response to security incidents such as forced sign-outs across all active sessions.
Supabase Session Manager is a medium-complexity shared service with a single dependency on SecureSessionStorage, making its delivery sequence straightforward but critical — downstream features including biometric auth, password login, and any authenticated screen depend on it being stable. The onSessionChanged callback pattern requires careful coordination with Riverpod provider setup; plan for integration testing time beyond unit testing. Token refresh logic must be validated against Supabase Auth server behavior under network degradation scenarios, requiring test environment parity with production Supabase configuration. Because this service is shared across all login features, any breaking interface change has broad ripple effects — API changes must be communicated early and versioned carefully.
Allocate regression testing time whenever session handling logic is modified.
Supabase Session Manager centralizes all Supabase Auth lifecycle operations, exposing six methods: refreshSession(), getCurrentSession(), isSessionValid(), signOut(), onSessionChanged(callback), and restoreSession(token). It depends on SecureSessionStorage for persisting and retrieving tokens between app launches. The service integrates with Riverpod by emitting session state changes via the onSessionChanged stream, allowing auth-aware providers to reactively rebuild UI. Token refresh should be triggered proactively before expiry using a timer or background task scheduler rather than reactively on 401 responses.
isSessionValid() must validate against the Supabase Auth server rather than relying solely on local token expiry timestamps, since tokens can be revoked server-side. This component operates in the mobile execution context and manages the session and user data models. As a shared service, it must be thread-safe under concurrent calls from multiple features. Any changes to the signOut flow must ensure full local state cleanup including SecureSessionStorage wipe and Riverpod provider invalidation.
Responsibilities
- Refresh Supabase access tokens before expiry
- Validate current session against Supabase Auth server
- Sign out and clear session state on demand
- Propagate session state changes to Riverpod providers
Interfaces
refreshSession()
getCurrentSession()
isSessionValid()
signOut()
onSessionChanged(callback)
restoreSession(token)
Relationships
Related Data Entities (2)
Data entities managed by this component