Authentication Session Manager

As a shared component consumed by every authentication feature in the application, this component sits on the critical path for all auth-related delivery. Its single dependency — the Secure Storage Adapter — must be available early in the sprint cycle. Any breaking interface changes to this component (session model, stream contract, or storage format) will require coordinated updates across all consumers, making its API contract a key design decision to lock down early. Medium complexity overall, but the JWT auto-refresh logic and stream broadcast behavior require careful integration testing under network degradation and token expiry edge cases.

Risk: if session persistence or refresh logic has a regression, all users are effectively locked out — prioritize this component for thorough QA and consider feature-flagged rollout.

Manages the full Supabase JWT session lifecycle: initial persistence via persistSession(), automatic token refresh before expiry, and propagation of auth state changes through a reactive Stream consumed by the BLoC/Riverpod state layer. The stream is the integration seam — consumers subscribe via authStateChanges() and react to signed-in, signed-out, and token-refreshed events without polling. Session data is stored in SecureStorageAdapter, keeping JWTs out of SharedPreferences or the file system. getUserId() and isAuthenticated() provide synchronous convenience accessors for cases where reactive subscription is unnecessary.

The refreshSession() method should implement retry-with-backoff for network failures. As a shared component, it must be initialized as a singleton early in the app lifecycle (before any route guard or auth gate evaluates isAuthenticated) to avoid race conditions on cold start.