Authentication

The user app implements a secure authentication system with multiple entry points and verification methods.

Authentication Flows

Registration Flow

New users can register using their phone number:

┌─────────────────┐
│  Enter Phone    │
│    Number       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Receive OTP    │
│  (WhatsApp/SMS) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Verify OTP     │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Create PIN     │
│   (4-6 digits)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Profile Setup  │
│  (Name, Email)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Registration   │
│   Complete      │
└─────────────────┘

Login Flow

Returning users can authenticate via:

1. PIN Login: Phone number + PIN
2. Biometric Login: Fingerprint/Face ID (if enabled)
3. Password Login: Email + Password (optional)

┌─────────────────┐
│  Enter Phone    │
│    Number       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│   Enter PIN     │────▶│   Biometric     │
│                 │     │   (Optional)    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │   Home Screen   │
            └─────────────────┘

Forgot Password Flow

┌─────────────────┐
│  Enter Phone    │
│    Number       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Receive OTP    │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Verify OTP     │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Create New     │
│     PIN         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Confirm New    │
│     PIN         │
└─────────────────┘

Controller Methods

Method	Description
login(phone, pin)	Authenticate with phone and PIN
register(phone, otp)	Register new user after OTP verification
verifyOtp(otp)	Verify OTP code
resetPin(newPin)	Reset user PIN
logout()	End user session

Service Methods

Method	Description
login(phone, pin)	Returns AuthResponse
sendOtp(phone)	Send OTP to phone
verifyOtp(phone, otp)	Verify OTP, returns boolean
register(request)	Complete registration
refreshToken()	Refresh JWT token

API Endpoints

Endpoint	Method	Description
/auth/login	POST	User login
/auth/register	POST	New user registration
/auth/send-otp	POST	Request OTP
/auth/verify-otp	POST	Verify OTP code
/auth/reset-pin	POST	Reset user PIN
/auth/refresh	POST	Refresh JWT token

OTP Configuration

Setting	Value
Primary Channel	WhatsApp (requires button URL)
Fallback	SMS via Twilio
Expiry	5 minutes
Max Attempts	3

Security Measures

Token Storage

Tokens are stored securely using FlutterSecureStorage:

Key	Description
access_token	JWT access token
refresh_token	JWT refresh token

Biometric Authentication

Biometric login can be enabled after initial setup:

• Uses LocalAuthentication package
• Checks device capability first
• Saves preference after successful setup

Error Handling

Error Code	Message	Action
AUTH_001	Invalid credentials	Show error, clear PIN
AUTH_002	Account locked	Contact support
AUTH_003	OTP expired	Request new OTP
AUTH_004	Too many attempts	Wait 15 minutes
AUTH_005	Session expired	Re-authenticate

Related Files

File	Purpose
lib/screens/auth/login_screen.dart	Login screen
lib/screens/auth/register_screen.dart	Registration screen
lib/screens/auth/otp_verification_screen.dart	OTP verification
lib/screens/auth/forgot_password_screen.dart	Password reset
lib/controllers/auth_controller.dart	Auth controller
lib/services/auth_service.dart	Auth service