Implement RFC 5322 Email Format Validator
epic-email-password-login-foundation-task-004 — Build the email validation function in CredentialValidator using a regex that conforms to RFC 5322 email format rules. Return structured validation result objects with localized error messages. Ensure the validator is a pure function with no side effects, suitable for use in both form fields and BLoC logic.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use a well-known, conservative RFC 5322 subset regex rather than attempting full RFC compliance (which is impractical in a single regex). A reliable pattern: r'^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$'. Document explicitly that this is a syntactic check only — Supabase will perform authoritative validation during sign-up. Return a typed ValidationResult sealed class or simple data class — do not return String?
(null = valid) as that pattern is less readable. Keep CredentialValidator as a final class with only static methods for easy testing and use in both BLoC event handlers and Flutter FormField validators. Localization keys should follow the app's existing l10n convention.
Testing Requirements
Unit tests using flutter_test covering: (1) 10+ valid email formats; (2) 10+ invalid formats including empty string, whitespace-only, missing @, double @, missing TLD, consecutive dots; (3) boundary: exactly 320 characters returns isValid true if otherwise valid; (4) 321 characters returns isValid false; (5) localization key is returned (not a resolved string) for error messages. No integration tests needed — pure function. Performance test: loop 10,000 calls and assert duration under 100ms.
Supabase client initialization may fail silently in certain Flutter environments if environment variables are missing or the anon key is rotated, leading to runtime null-pointer errors throughout the auth layer.
Mitigation & Contingency
Mitigation: Add explicit assertion checks during app startup that verify the Supabase client is initialized before the router resolves. Document required --dart-define keys in the project README and add a CI step that validates their presence.
Contingency: Implement a fallback initialization error screen with a clear message and a retry button. Log initialization failures to crash reporting immediately.
The flutter_secure_storage package behaviour differs between iOS Keychain and Android Keystore implementations. On Android, biometric-enrolled devices may require additional authentication to read stored tokens, causing unexpected session read failures.
Mitigation & Contingency
Mitigation: Test the repository on Android devices with and without biometric enrollment early in development. Use accessibility options in flutter_secure_storage to configure whether biometric authentication is required for storage access.
Contingency: If biometric-gated storage causes regressions, fall back to a non-biometric storage option for session tokens (reserving biometric-gated storage for higher-sensitivity credentials only).