Auth Feature
See lib/src/features/AGENTS.md for feature layout and /AGENTS.md for project-wide rules.
OVERVIEW
auth/ handles passwordless login (email start → OTP verify), session management, token refresh, and sign-out. Uses AuthRepository, AuthSessionStorage, AuthRemoteDataSource, and PauzaAuthGate for gate-based routing. Requires InternetRequiredGuard for start/verify flows.
WHERE TO LOOK
| Task | Location | Notes |
|---|---|---|
| Auth screen, OTP screen | widget/ | AuthScreen, OtpScreen; auth_form/, otp_code/ subfolders |
| Auth state machine | bloc/ | AuthBloc, events, states |
| Session, token storage | data/ | AuthRepository, AuthSessionStorage, AuthRemoteDataSource |
| Auth gate (routing) | domain/ | PauzaAuthGate, used by router guards |
| User DTO (from auth) | common/model/ | Auth returns user data; profile consumes |
CONVENTIONS
- Session stored securely via
AuthSessionStorage; refreshed viaAuthRepository.refreshSession(). - API client uses
ApiClientAuthMiddlewarewith token fromauthRepository.currentSession. - Auth gate notifies router when auth state changes; guards redirect unauthenticated users.
- On sign-out:
syncLocalDataSource.clearAllSyncableTables()called viaonSignOutCleanup.
ANTI-PATTERNS
- Do not leak account existence via error messages or timing in OTP flows.
- Do not put token or credential logic in widget layer; keep in repository/domain.
- Do not bypass
InternetRequiredGuardfor start/verify; these flows need connectivity.