🏠 Overview › ✅ Implementation Tasks ›✅ epic-email-password-login-auth-logic-task-001

Define AuthService interface and domain exceptions

epic-email-password-login-auth-logic-task-001 — Define the AuthService abstract interface with signIn, signOut, and getSession methods. Define typed domain exceptions: InvalidCredentialsException, NetworkFailureException, RateLimitException, ServerErrorException. These form the contract between the BLoC layer and the service implementation.

critical priority low complexity backend pending backend specialist Tier 0

Acceptance Criteria

AuthService abstract class/interface is defined in a dedicated file under lib/features/auth/domain/
signIn(String email, String password) returns Future<AuthResult> (sealed class with success/failure variants)
signOut() returns Future<void> and is declared on the interface
getSession() returns Future<SessionResult?> (nullable for unauthenticated state)
InvalidCredentialsException is defined with optional String message field
NetworkFailureException is defined with optional String message and bool isTimeout fields
RateLimitException is defined with optional int retryAfterSeconds field
ServerErrorException is defined with int statusCode and optional String message fields
All exceptions extend a common AuthException base class
No Supabase or GoTrue imports exist in the domain layer — pure Dart only
Each exception has a meaningful toString() implementation for logging
File compiles with zero analyzer warnings (flutter analyze passes)

Technical Requirements

frameworks
Flutter
Dart
data models
AuthResult
SessionResult
AuthException
performance requirements
Interface methods must be declared as async (Future-returning) to allow non-blocking implementations
security requirements
No credentials (email/password) stored on the exception objects
Exception messages must not leak raw Supabase error payloads at the domain layer

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Place all domain types in lib/features/auth/domain/auth_service.dart (interface) and lib/features/auth/domain/auth_exceptions.dart (exceptions). Use Dart sealed classes for AuthResult so callers are forced to handle both success and failure at compile time (`sealed class AuthResult` with `AuthSuccess` and `AuthFailure` subtypes). Avoid enums for exception types — typed classes give BLoC granular pattern-matching. Keep this layer free of any package imports other than dart:core.

This file will be imported by both the BLoC (010-login-form-bloc) and the concrete service implementation, so the abstraction must remain stable.

Testing Requirements

Unit tests in test/features/auth/domain/: (1) Verify each exception type can be instantiated with all combinations of optional fields. (2) Verify AuthException is the supertype of all typed exceptions using `is` checks. (3) Verify toString() returns a non-empty string for each exception type. No mocking required — pure Dart classes.

100% line coverage expected for this file.

Component
Authentication Service
service medium
Epic Risks (2)
high impact medium prob integration

Supabase GoTrue returns HTTP error codes and string messages that may change between SDK versions. Incorrect or incomplete mapping could cause the wrong user-facing message to be shown (e.g., showing a generic error instead of a specific credential error), violating the plain-language feedback acceptance criteria and potentially exposing security-sensitive information.

Mitigation & Contingency

Mitigation: Pin the supabase_flutter SDK to a specific minor version in pubspec.yaml. Write integration tests that mock the Supabase HTTP layer and assert each error code maps to the correct domain exception. Document the mapping table as a constant in AuthService.

Contingency: If an unrecognized error code is received at runtime, catch it as an UnknownAuthException and display a generic safe message. Alert via crash reporting for triage and SDK update.

medium impact medium prob technical

If the user taps the sign-in button multiple times rapidly, concurrent authentication requests could result in race conditions: duplicate network calls, out-of-order state emissions, or multiple session tokens being written to secure storage.

Mitigation & Contingency

Mitigation: Use bloc concurrency transformer (droppable or restartable) to ensure only one authentication event is processed at a time. The BLoC should guard against submission while in LoginLoading state.

Contingency: Add a UI-level disable on the submit button when loading state is active as a secondary guard independent of BLoC concurrency control.

Quick Links
All Tasks Execution Plan