feat(customer_auth): Implement OTP-based customer authentication system

- Add customer authentication schemas with OTP request/response models
- Implement customer auth service with OTP generation, verification, and JWT token creation
- Create customer auth dependency for JWT validation and customer extraction
- Add customer database initialization with scm_customers and customer_otps collections
- Integrate customer auth router into main application
- Add comprehensive documentation for customer auth implementation and API endpoints
- Include mobile app integration example with JavaScript client code
- Add setup and test scripts for customer authentication workflow
- Implement security features including 6-digit OTP, 5-minute expiration, and rate limiting
- Support new customer registration and existing customer login flows

CUSTOMER_AUTH_IMPLEMENTATION.md

@@ -0,0 +1,385 @@
+# Customer Authentication Implementation
+
+## Overview
+
+This document describes the implementation of OTP-based customer authentication in the Auth microservice. The system provides secure mobile-based authentication for customers using SMS OTP verification.
+
+## Architecture
+
+### Components
+
+1. **Customer Auth Schemas** (`app/auth/schemas/customer_auth.py`)
+   - Request/response models for OTP operations
+   - Input validation for mobile numbers and OTP codes
+
+2. **Customer Auth Service** (`app/auth/services/customer_auth_service.py`)
+   - Core business logic for OTP generation and verification
+   - Customer creation and management
+   - JWT token generation for customers
+
+3. **Customer Auth Dependencies** (`app/dependencies/customer_auth.py`)
+   - Authentication middleware for customer endpoints
+   - JWT token validation and customer extraction
+
+4. **Database Collections**
+   - `scm_customers`: Customer profile data
+   - `customer_otps`: OTP storage with TTL expiration
+
+## API Endpoints
+
+### 1. Send OTP
+```http
+POST /auth/customer/send-otp
+Content-Type: application/json
+
+{
+  "mobile": "+919999999999"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "OTP sent successfully",
+  "expires_in": 300
+}
+```
+
+### 2. Verify OTP
+```http
+POST /auth/customer/verify-otp
+Content-Type: application/json
+
+{
+  "mobile": "+919999999999",
+  "otp": "123456"
+}
+```
+
+**Response:**
+```json
+{
+  "access_token": "jwt_token_here",
+  "customer_id": "uuid",
+  "is_new_customer": false,
+  "token_type": "bearer",
+  "expires_in": 86400
+}
+```
+
+### 3. Get Customer Profile
+```http
+GET /auth/customer/me
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "customer_id": "uuid",
+  "mobile": "+919999999999",
+  "merchant_id": null,
+  "type": "customer"
+}
+```
+
+### 4. Customer Logout
+```http
+POST /auth/customer/logout
+Authorization: Bearer <access_token>
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Customer logged out successfully"
+}
+```
+
+## Database Schema
+
+### scm_customers Collection
+```javascript
+{
+  "_id": ObjectId,
+  "customer_id": "uuid",           // Unique customer identifier
+  "phone": "+919999999999",        // Mobile number (unique)
+  "name": "Customer Name",         // Full name (optional)
+  "email": "email@example.com",    // Email address (optional)
+  "status": "active",              // active | inactive
+  "merchant_id": "uuid",           // Associated merchant (optional)
+  "notes": "Registration notes",   // Free-form notes
+  "created_at": ISODate,
+  "updated_at": ISODate,
+  "last_login_at": ISODate
+}
+```
+
+**Indexes:**
+- `phone` (unique, sparse)
+- `customer_id` (unique)
+- `merchant_id` (sparse)
+- `status`
+- `{merchant_id: 1, status: 1}` (compound)
+
+### customer_otps Collection
+```javascript
+{
+  "_id": ObjectId,
+  "mobile": "+919999999999",       // Mobile number (unique)
+  "otp": "123456",                 // 6-digit OTP code
+  "created_at": ISODate,
+  "expires_at": ISODate,           // TTL expiration
+  "attempts": 0,                   // Verification attempts
+  "verified": false                // Whether OTP was used
+}
+```
+
+**Indexes:**
+- `mobile` (unique)
+- `expires_at` (TTL, expireAfterSeconds: 0)
+- `created_at`
+
+## Security Features
+
+### OTP Security
+- **6-digit random OTP** generated using `secrets.randbelow()`
+- **5-minute expiration** with automatic cleanup
+- **Maximum 3 verification attempts** per OTP
+- **One-time use** - OTP marked as verified after successful use
+- **Rate limiting** - New OTP request replaces previous one
+
+### JWT Token Security
+- **Customer-specific tokens** with `type: "customer"` claim
+- **Standard expiration** based on system configuration
+- **Stateless authentication** - no server-side session storage
+- **Secure payload** includes customer_id, mobile, and merchant_id
+
+### Input Validation
+- **Mobile number format** validation using regex
+- **International format** support (+country_code)
+- **OTP format** validation (digits only, 4-6 characters)
+- **Pydantic validation** for all request/response models
+
+## Customer Lifecycle
+
+### New Customer Registration
+1. Customer enters mobile number
+2. System sends OTP via SMS
+3. Customer verifies OTP
+4. New customer record created in `scm_customers`
+5. JWT token issued with `is_new_customer: true`
+6. Customer can complete profile later
+
+### Existing Customer Login
+1. Customer enters mobile number
+2. System sends OTP via SMS
+3. Customer verifies OTP
+4. Existing customer record updated with `last_login_at`
+5. JWT token issued with `is_new_customer: false`
+
+### Customer-Merchant Association
+- Initially, customers have `merchant_id: null`
+- Association happens when customer makes first purchase
+- Allows customers to shop across multiple merchants
+- Merchant-specific data isolation maintained
+
+## Error Handling
+
+### OTP Errors
+- **Invalid mobile format**: 422 Unprocessable Entity
+- **OTP not found**: 401 Unauthorized
+- **Expired OTP**: 401 Unauthorized
+- **Already used OTP**: 401 Unauthorized
+- **Too many attempts**: 429 Too Many Requests
+- **Invalid OTP**: 401 Unauthorized
+
+### Authentication Errors
+- **Missing token**: 401 Unauthorized
+- **Invalid token**: 401 Unauthorized
+- **Expired token**: 401 Unauthorized
+- **Non-customer token**: 403 Forbidden
+
+## Testing
+
+### Manual Testing
+Use the provided test script:
+```bash
+cd cuatrolabs-auth-ms
+python test_customer_auth.py
+```
+
+### Test Scenarios
+1. **Happy Path**: Send OTP → Verify OTP → Access protected endpoints
+2. **Error Cases**: Invalid mobile, wrong OTP, expired OTP, missing token
+3. **Security**: Multiple attempts, token validation, logout
+
+### Test Mobile Numbers
+- Use `+919999999999` for testing
+- OTP is logged in application logs for development
+- In production, integrate with SMS service provider
+
+## Integration Points
+
+### SMS Service Integration
+Currently, OTPs are logged for testing. To integrate with SMS service:
+
+1. Add SMS service configuration to `settings.py`
+2. Update `CustomerAuthService.send_otp()` method
+3. Replace logging with actual SMS API call
+4. Handle SMS service errors appropriately
+
+### Frontend Integration
+```javascript
+// Send OTP
+const sendOTP = async (mobile) => {
+  const response = await fetch('/auth/customer/send-otp', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ mobile })
+  });
+  return response.json();
+};
+
+// Verify OTP
+const verifyOTP = async (mobile, otp) => {
+  const response = await fetch('/auth/customer/verify-otp', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ mobile, otp })
+  });
+  return response.json();
+};
+
+// Store token and customer data
+const { access_token, customer_id, is_new_customer } = await verifyOTP(mobile, otp);
+localStorage.setItem('access_token', access_token);
+localStorage.setItem('customer_id', customer_id);
+
+// Use token for API calls
+const headers = {
+  'Authorization': `Bearer ${access_token}`,
+  'Content-Type': 'application/json'
+};
+```
+
+### Session Management
+```javascript
+// Check if user is logged in
+const isLoggedIn = () => {
+  const token = localStorage.getItem('access_token');
+  return token && !isTokenExpired(token);
+};
+
+// Auto-restore session
+const restoreSession = async () => {
+  if (isLoggedIn()) {
+    // Redirect to main app
+    window.location.href = '/(tabs)/index';
+  } else {
+    // Stay on auth screen
+    clearSession();
+  }
+};
+
+// Logout
+const logout = async () => {
+  const token = localStorage.getItem('access_token');
+  if (token) {
+    await fetch('/auth/customer/logout', {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${token}` }
+    });
+  }
+  clearSession();
+};
+
+const clearSession = () => {
+  localStorage.removeItem('access_token');
+  localStorage.removeItem('customer_id');
+  // Redirect to auth screen
+};
+```
+
+## Deployment Considerations
+
+### Environment Variables
+```bash
+# MongoDB connection
+MONGODB_URL=mongodb://localhost:27017
+MONGODB_DB_NAME=cuatrolabs_auth
+
+# JWT configuration
+JWT_SECRET_KEY=your-secret-key
+TOKEN_EXPIRATION_HOURS=24
+
+# SMS service (when integrated)
+SMS_API_KEY=your-sms-api-key
+SMS_API_URL=https://api.sms-provider.com
+```
+
+### Production Checklist
+- [ ] Configure SMS service integration
+- [ ] Set up proper JWT secret key
+- [ ] Configure CORS origins
+- [ ] Set up monitoring and logging
+- [ ] Configure rate limiting
+- [ ] Set up database backups
+- [ ] Test OTP delivery in production
+- [ ] Verify token expiration handling
+
+## Monitoring and Logging
+
+### Key Metrics
+- OTP send success/failure rates
+- OTP verification success/failure rates
+- Customer registration rates
+- Authentication token usage
+- Failed authentication attempts
+
+### Log Events
+- `customer_otp_sent`: OTP generation and sending
+- `customer_otp_verified`: Successful OTP verification
+- `customer_login_success`: Customer authentication success
+- `customer_logout`: Customer logout events
+- `customer_auth_failed`: Authentication failures
+
+### Alerts
+- High OTP failure rates
+- Unusual authentication patterns
+- SMS service failures
+- Database connection issues
+
+## Future Enhancements
+
+### Planned Features
+1. **Email OTP**: Alternative to SMS for customers with email
+2. **Social Login**: Google, Facebook, Apple authentication
+3. **Biometric Auth**: Fingerprint, Face ID support
+4. **Multi-factor Auth**: Additional security layer
+5. **Customer Profiles**: Extended profile management
+6. **Merchant Association**: Customer-merchant relationship management
+
+### Performance Optimizations
+1. **OTP Caching**: Redis for OTP storage
+2. **Token Blacklisting**: Revoked token management
+3. **Rate Limiting**: Advanced rate limiting per customer
+4. **SMS Queuing**: Async SMS delivery
+5. **Database Sharding**: Scale customer data storage
+
+## Support and Troubleshooting
+
+### Common Issues
+1. **OTP not received**: Check SMS service logs, verify mobile format
+2. **Token expired**: Implement token refresh mechanism
+3. **Customer not found**: Check database connectivity and indexes
+4. **Invalid mobile format**: Verify regex pattern and validation
+
+### Debug Endpoints
+- `GET /health`: Service health check
+- `GET /debug/db-status`: Database connection status
+
+### Contact
+For technical support or questions about this implementation, contact the development team.

app/auth/controllers/router.py

@@ -12,6 +12,14 @@ from app.dependencies.auth import get_system_user_service, get_current_user
 from app.system_users.models.model import SystemUserModel
 from app.core.config import settings
 from app.core.logging import get_logger
+from app.auth.schemas.customer_auth import (
+    SendOTPRequest, 
+    VerifyOTPRequest, 
+    CustomerAuthResponse, 
+    SendOTPResponse
+)
+from app.auth.services.customer_auth_service import CustomerAuthService
+from app.dependencies.customer_auth import get_current_customer, CustomerUser
 
 logger = get_logger(__name__)
 
@@ -613,6 +621,230 @@ async def get_password_rotation_status(
         )
 
 
+@router.post("/customer/send-otp", response_model=SendOTPResponse)
+async def send_customer_otp(request: SendOTPRequest):
+    """
+    Send OTP to customer mobile number for authentication.
+    
+    - **mobile**: Customer mobile number in international format (e.g., +919999999999)
+    
+    **Process:**
+    1. Validates mobile number format
+    2. Generates 6-digit OTP
+    3. Stores OTP with 5-minute expiration
+    4. Sends OTP via SMS (currently logged for testing)
+    
+    **Rate Limiting:**
+    - Maximum 3 verification attempts per OTP
+    - OTP expires after 5 minutes
+    - New OTP request replaces previous one
+    
+    Raises:
+        HTTPException: 400 - Invalid mobile number format
+        HTTPException: 500 - Failed to send OTP
+    """
+    try:
+        customer_auth_service = CustomerAuthService()
+        success, message, expires_in = await customer_auth_service.send_otp(request.mobile)
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=message
+            )
+        
+        logger.info(f"OTP sent to customer mobile: {request.mobile}")
+        
+        return SendOTPResponse(
+            success=True,
+            message=message,
+            expires_in=expires_in
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error sending OTP to {request.mobile}: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An unexpected error occurred while sending OTP"
+        )
+
+
+@router.post("/customer/verify-otp", response_model=CustomerAuthResponse)
+async def verify_customer_otp(request: VerifyOTPRequest):
+    """
+    Verify OTP and authenticate customer.
+    
+    - **mobile**: Customer mobile number used for OTP
+    - **otp**: 6-digit OTP code received via SMS
+    
+    **Process:**
+    1. Validates OTP against stored record
+    2. Checks expiration and attempt limits
+    3. Finds existing customer or creates new one
+    4. Generates JWT access token
+    5. Returns customer authentication data
+    
+    **Customer Creation:**
+    - New customers are automatically created on first successful OTP verification
+    - Customer profile can be completed later via separate endpoints
+    - Initial customer record contains only mobile number
+    
+    **Session Handling:**
+    - Returns JWT access token for API authentication
+    - Token includes customer_id and mobile number
+    - Token expires based on system configuration (default: 24 hours)
+    
+    Raises:
+        HTTPException: 400 - Invalid OTP format or mobile number
+        HTTPException: 401 - Invalid, expired, or already used OTP
+        HTTPException: 429 - Too many attempts
+        HTTPException: 500 - Server error
+    """
+    try:
+        customer_auth_service = CustomerAuthService()
+        customer_data, message = await customer_auth_service.verify_otp(
+            request.mobile, 
+            request.otp
+        )
+        
+        if not customer_data:
+            # Determine appropriate status code based on message
+            if "expired" in message.lower():
+                status_code = status.HTTP_401_UNAUTHORIZED
+            elif "too many attempts" in message.lower():
+                status_code = status.HTTP_429_TOO_MANY_REQUESTS
+            else:
+                status_code = status.HTTP_401_UNAUTHORIZED
+                
+            raise HTTPException(
+                status_code=status_code,
+                detail=message
+            )
+        
+        # Create JWT token for customer
+        access_token = customer_auth_service.create_customer_token(customer_data)
+        
+        logger.info(
+            f"Customer authenticated successfully: {customer_data['customer_id']}",
+            extra={
+                "event": "customer_login_success",
+                "customer_id": customer_data["customer_id"],
+                "mobile": request.mobile,
+                "is_new_customer": customer_data["is_new_customer"]
+            }
+        )
+        
+        return CustomerAuthResponse(
+            access_token=access_token,
+            customer_id=customer_data["customer_id"],
+            is_new_customer=customer_data["is_new_customer"],
+            expires_in=settings.TOKEN_EXPIRATION_HOURS * 3600
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error verifying OTP for {request.mobile}: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An unexpected error occurred during OTP verification"
+        )
+
+
+@router.get("/customer/me")
+async def get_customer_profile(
+    current_customer: CustomerUser = Depends(get_current_customer)
+):
+    """
+    Get current customer profile information.
+    
+    Requires customer JWT token in Authorization header (Bearer token).
+    
+    **Returns:**
+    - **customer_id**: Unique customer identifier
+    - **mobile**: Customer mobile number
+    - **merchant_id**: Associated merchant (if any)
+    - **type**: Always "customer"
+    
+    **Usage:**
+    - Use this endpoint to verify customer authentication
+    - Get basic customer information for app initialization
+    - Check if customer is associated with a merchant
+    
+    Raises:
+        HTTPException: 401 - Invalid or expired token
+        HTTPException: 403 - Not a customer token
+    """
+    try:
+        logger.info(f"Customer profile accessed: {current_customer.customer_id}")
+        
+        return {
+            "customer_id": current_customer.customer_id,
+            "mobile": current_customer.mobile,
+            "merchant_id": current_customer.merchant_id,
+            "type": current_customer.type
+        }
+        
+    except Exception as e:
+        logger.error(f"Error getting customer profile: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to get customer profile"
+        )
+
+
+@router.post("/customer/logout")
+async def logout_customer(
+    current_customer: CustomerUser = Depends(get_current_customer)
+):
+    """
+    Logout current customer.
+    
+    Requires customer JWT token in Authorization header (Bearer token).
+    
+    **Process:**
+    - Validates customer JWT token
+    - Records logout event for audit purposes
+    - Returns success confirmation
+    
+    **Note:** Since we're using stateless JWT tokens, the client is responsible for:
+    - Removing the token from local storage
+    - Clearing any cached customer data
+    - Redirecting to login screen
+    
+    **Security:**
+    - Logs logout event with customer information
+    - Provides audit trail for customer sessions
+    
+    Raises:
+        HTTPException: 401 - Invalid or expired token
+        HTTPException: 403 - Not a customer token
+    """
+    try:
+        logger.info(
+            f"Customer logged out: {current_customer.customer_id}",
+            extra={
+                "event": "customer_logout",
+                "customer_id": current_customer.customer_id,
+                "mobile": current_customer.mobile
+            }
+        )
+        
+        return {
+            "success": True,
+            "message": "Customer logged out successfully"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error during customer logout: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An unexpected error occurred during logout"
+        )
+
+
 @router.post("/password-rotation-policy")
 async def get_password_rotation_policy(
     user_service: SystemUserService = Depends(get_system_user_service)

app/auth/db_init_customer.py

@@ -0,0 +1,59 @@
+"""
+Database initialization for customer authentication collections.
+"""
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from app.nosql import get_database
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+async def init_customer_auth_collections():
+    """Initialize collections and indexes for customer authentication."""
+    try:
+        db: AsyncIOMotorDatabase = get_database()
+        
+        # Create indexes for scm_customers collection
+        customers_collection = db.scm_customers
+        
+        # Index on phone for fast lookup
+        await customers_collection.create_index("phone", unique=True, sparse=True)
+        
+        # Index on customer_id for fast lookup
+        await customers_collection.create_index("customer_id", unique=True)
+        
+        # Index on merchant_id for merchant-specific queries
+        await customers_collection.create_index("merchant_id", sparse=True)
+        
+        # Index on status for filtering
+        await customers_collection.create_index("status")
+        
+        # Compound index for merchant + status queries
+        await customers_collection.create_index([("merchant_id", 1), ("status", 1)])
+        
+        logger.info("✅ scm_customers collection indexes created")
+        
+        # Create indexes for customer_otps collection
+        otps_collection = db.customer_otps
+        
+        # Index on mobile for fast lookup
+        await otps_collection.create_index("mobile", unique=True)
+        
+        # TTL index on expires_at for automatic cleanup
+        await otps_collection.create_index("expires_at", expireAfterSeconds=0)
+        
+        # Index on created_at for cleanup queries
+        await otps_collection.create_index("created_at")
+        
+        logger.info("✅ customer_otps collection indexes created")
+        
+        logger.info("🎉 Customer authentication database initialization completed")
+        
+    except Exception as e:
+        logger.error(f"❌ Error initializing customer auth collections: {str(e)}", exc_info=True)
+        raise
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(init_customer_auth_collections())

app/auth/schemas/customer_auth.py

@@ -0,0 +1,56 @@
+"""
+Customer authentication schemas for OTP-based login.
+"""
+from typing import Optional
+from pydantic import BaseModel, Field, field_validator
+import re
+
+PHONE_REGEX = re.compile(r"^\+?[0-9\-\s]{8,20}$")
+
+
+class SendOTPRequest(BaseModel):
+    """Request schema for sending OTP to customer."""
+    mobile: str = Field(..., min_length=8, max_length=20, description="Mobile number with country code")
+
+    @field_validator("mobile")
+    @classmethod
+    def validate_mobile(cls, v: str) -> str:
+        if not PHONE_REGEX.match(v):
+            raise ValueError("Invalid mobile number format; use international format like +919999999999")
+        return v
+
+
+class VerifyOTPRequest(BaseModel):
+    """Request schema for verifying OTP."""
+    mobile: str = Field(..., min_length=8, max_length=20, description="Mobile number with country code")
+    otp: str = Field(..., min_length=4, max_length=6, description="OTP code")
+
+    @field_validator("mobile")
+    @classmethod
+    def validate_mobile(cls, v: str) -> str:
+        if not PHONE_REGEX.match(v):
+            raise ValueError("Invalid mobile number format; use international format like +919999999999")
+        return v
+
+    @field_validator("otp")
+    @classmethod
+    def validate_otp(cls, v: str) -> str:
+        if not v.isdigit():
+            raise ValueError("OTP must contain only digits")
+        return v
+
+
+class CustomerAuthResponse(BaseModel):
+    """Response schema for successful customer authentication."""
+    access_token: str = Field(..., description="JWT access token")
+    customer_id: str = Field(..., description="Customer UUID")
+    is_new_customer: bool = Field(..., description="Whether this is a new customer registration")
+    token_type: str = Field(default="bearer", description="Token type")
+    expires_in: int = Field(..., description="Token expiration time in seconds")
+
+
+class SendOTPResponse(BaseModel):
+    """Response schema for OTP send request."""
+    success: bool = Field(..., description="Whether OTP was sent successfully")
+    message: str = Field(..., description="Response message")
+    expires_in: int = Field(..., description="OTP expiration time in seconds")

app/auth/services/customer_auth_service.py

@@ -0,0 +1,249 @@
+"""
+Customer authentication service for OTP-based login.
+"""
+import secrets
+import uuid
+from datetime import datetime, timedelta
+from typing import Optional, Tuple, Dict, Any
+from motor.motor_asyncio import AsyncIOMotorDatabase
+
+from app.core.config import settings
+from app.core.logging import get_logger
+from app.nosql import get_database
+from app.system_users.services.service import SystemUserService
+
+logger = get_logger(__name__)
+
+
+class CustomerAuthService:
+    """Service for customer OTP authentication."""
+    
+    def __init__(self):
+        self.db: AsyncIOMotorDatabase = get_database()
+        self.customers_collection = self.db.scm_customers
+        self.otp_collection = self.db.customer_otps
+        self.system_user_service = SystemUserService()
+    
+    async def send_otp(self, mobile: str) -> Tuple[bool, str, int]:
+        """
+        Send OTP to customer mobile number.
+        
+        Args:
+            mobile: Customer mobile number
+            
+        Returns:
+            Tuple of (success, message, expires_in_seconds)
+        """
+        try:
+            # Generate 6-digit OTP
+            otp = str(secrets.randbelow(900000) + 100000)
+            
+            # Set expiration (5 minutes)
+            expires_at = datetime.utcnow() + timedelta(minutes=5)
+            expires_in = 300  # 5 minutes in seconds
+            
+            # Store OTP in database
+            otp_doc = {
+                "mobile": mobile,
+                "otp": otp,
+                "created_at": datetime.utcnow(),
+                "expires_at": expires_at,
+                "attempts": 0,
+                "verified": False
+            }
+            
+            # Upsert OTP (replace existing if any)
+            await self.otp_collection.replace_one(
+                {"mobile": mobile},
+                otp_doc,
+                upsert=True
+            )
+            
+            # TODO: Integrate with SMS service to send actual OTP
+            # For now, log the OTP for testing
+            logger.info(f"OTP generated for {mobile}: {otp} (expires in {expires_in}s)")
+            
+            return True, "OTP sent successfully", expires_in
+            
+        except Exception as e:
+            logger.error(f"Error sending OTP to {mobile}: {str(e)}", exc_info=True)
+            return False, "Failed to send OTP", 0
+    
+    async def verify_otp(self, mobile: str, otp: str) -> Tuple[Optional[Dict[str, Any]], str]:
+        """
+        Verify OTP and authenticate customer.
+        
+        Args:
+            mobile: Customer mobile number
+            otp: OTP code to verify
+            
+        Returns:
+            Tuple of (customer_data, message)
+        """
+        try:
+            # Find OTP record
+            otp_doc = await self.otp_collection.find_one({"mobile": mobile})
+            
+            if not otp_doc:
+                logger.warning(f"OTP verification failed - no OTP found for {mobile}")
+                return None, "Invalid OTP"
+            
+            # Check if OTP is expired
+            if datetime.utcnow() > otp_doc["expires_at"]:
+                logger.warning(f"OTP verification failed - expired OTP for {mobile}")
+                await self.otp_collection.delete_one({"mobile": mobile})
+                return None, "OTP has expired"
+            
+            # Check if already verified
+            if otp_doc.get("verified", False):
+                logger.warning(f"OTP verification failed - already used OTP for {mobile}")
+                return None, "OTP has already been used"
+            
+            # Increment attempts
+            attempts = otp_doc.get("attempts", 0) + 1
+            
+            # Check max attempts (3 attempts allowed)
+            if attempts > 3:
+                logger.warning(f"OTP verification failed - too many attempts for {mobile}")
+                await self.otp_collection.delete_one({"mobile": mobile})
+                return None, "Too many attempts. Please request a new OTP"
+            
+            # Update attempts
+            await self.otp_collection.update_one(
+                {"mobile": mobile},
+                {"$set": {"attempts": attempts}}
+            )
+            
+            # Verify OTP
+            if otp_doc["otp"] != otp:
+                logger.warning(f"OTP verification failed - incorrect OTP for {mobile}")
+                return None, "Invalid OTP"
+            
+            # Mark OTP as verified
+            await self.otp_collection.update_one(
+                {"mobile": mobile},
+                {"$set": {"verified": True}}
+            )
+            
+            # Find or create customer
+            customer = await self._find_or_create_customer(mobile)
+            
+            logger.info(f"OTP verified successfully for {mobile}")
+            return customer, "OTP verified successfully"
+            
+        except Exception as e:
+            logger.error(f"Error verifying OTP for {mobile}: {str(e)}", exc_info=True)
+            return None, "Failed to verify OTP"
+    
+    async def _find_or_create_customer(self, mobile: str) -> Dict[str, Any]:
+        """
+        Find existing customer or create new one.
+        
+        Args:
+            mobile: Customer mobile number
+            
+        Returns:
+            Customer data dictionary
+        """
+        try:
+            # Try to find existing customer
+            customer = await self.customers_collection.find_one({"phone": mobile})
+            
+            if customer:
+                # Update last login
+                await self.customers_collection.update_one(
+                    {"_id": customer["_id"]},
+                    {"$set": {"last_login_at": datetime.utcnow()}}
+                )
+                
+                return {
+                    "customer_id": str(customer.get("customer_id", customer["_id"])),
+                    "mobile": customer["phone"],
+                    "name": customer.get("name", ""),
+                    "email": customer.get("email"),
+                    "is_new_customer": False,
+                    "status": customer.get("status", "active"),
+                    "merchant_id": customer.get("merchant_id"),
+                    "created_at": customer.get("created_at"),
+                    "last_login_at": datetime.utcnow()
+                }
+            else:
+                # Create new customer
+                customer_id = str(uuid.uuid4())
+                now = datetime.utcnow()
+                
+                new_customer = {
+                    "customer_id": customer_id,
+                    "phone": mobile,
+                    "name": "",  # Will be updated later
+                    "email": None,
+                    "status": "active",
+                    "merchant_id": None,  # Will be set when customer makes first purchase
+                    "notes": "Customer registered via mobile app",
+                    "created_at": now,
+                    "updated_at": now,
+                    "last_login_at": now
+                }
+                
+                await self.customers_collection.insert_one(new_customer)
+                
+                logger.info(f"New customer created: {customer_id} for mobile {mobile}")
+                
+                return {
+                    "customer_id": customer_id,
+                    "mobile": mobile,
+                    "name": "",
+                    "email": None,
+                    "is_new_customer": True,
+                    "status": "active",
+                    "merchant_id": None,
+                    "created_at": now,
+                    "last_login_at": now
+                }
+                
+        except Exception as e:
+            logger.error(f"Error finding/creating customer for {mobile}: {str(e)}", exc_info=True)
+            raise
+    
+    def create_customer_token(self, customer_data: Dict[str, Any]) -> str:
+        """
+        Create JWT token for customer.
+        
+        Args:
+            customer_data: Customer information
+            
+        Returns:
+            JWT access token
+        """
+        try:
+            token_data = {
+                "sub": customer_data["customer_id"],
+                "mobile": customer_data["mobile"],
+                "customer_id": customer_data["customer_id"],
+                "type": "customer",
+                "merchant_id": customer_data.get("merchant_id")
+            }
+            
+            expires_delta = timedelta(hours=settings.TOKEN_EXPIRATION_HOURS)
+            
+            return self.system_user_service.create_access_token(
+                data=token_data,
+                expires_delta=expires_delta
+            )
+            
+        except Exception as e:
+            logger.error(f"Error creating customer token: {str(e)}", exc_info=True)
+            raise
+    
+    async def cleanup_expired_otps(self):
+        """Clean up expired OTP records."""
+        try:
+            result = await self.otp_collection.delete_many({
+                "expires_at": {"$lt": datetime.utcnow()}
+            })
+            
+            if result.deleted_count > 0:
+                logger.info(f"Cleaned up {result.deleted_count} expired OTP records")
+                
+        except Exception as e:
+            logger.error(f"Error cleaning up expired OTPs: {str(e)}", exc_info=True)

app/dependencies/customer_auth.py

@@ -0,0 +1,98 @@
+"""
+Customer authentication dependencies.
+"""
+from typing import Optional
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from pydantic import BaseModel
+
+from app.system_users.services.service import SystemUserService
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+security = HTTPBearer()
+
+
+class CustomerUser(BaseModel):
+    """Customer user model for dependency injection."""
+    customer_id: str
+    mobile: str
+    merchant_id: Optional[str] = None
+    type: str = "customer"
+
+
+async def get_current_customer(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> CustomerUser:
+    """
+    Get current authenticated customer from JWT token.
+    
+    Args:
+        credentials: HTTP Bearer token credentials
+        
+    Returns:
+        CustomerUser: Authenticated customer information
+        
+    Raises:
+        HTTPException: 401 - Invalid or expired token
+        HTTPException: 403 - Not a customer token
+    """
+    try:
+        if not credentials:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authentication credentials required",
+                headers={"WWW-Authenticate": "Bearer"}
+            )
+        
+        # Verify token
+        user_service = SystemUserService()
+        payload = user_service.verify_token(credentials.credentials, "access")
+        
+        if not payload:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid or expired token",
+                headers={"WWW-Authenticate": "Bearer"}
+            )
+        
+        # Check if it's a customer token
+        token_type = payload.get("type")
+        if token_type != "customer":
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Customer authentication required"
+            )
+        
+        customer_id = payload.get("sub")
+        mobile = payload.get("mobile")
+        merchant_id = payload.get("merchant_id")
+        
+        if not customer_id or not mobile:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token payload"
+            )
+        
+        return CustomerUser(
+            customer_id=customer_id,
+            mobile=mobile,
+            merchant_id=merchant_id,
+            type="customer"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error authenticating customer: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication failed"
+        )
+
+
+async def get_customer_service():
+    """Dependency to get customer auth service."""
+    from app.auth.services.customer_auth_service import CustomerAuthService
+    return CustomerAuthService()

app/main.py

@@ -52,6 +52,14 @@ async def lifespan(app: FastAPI):
     logger.info("Starting AUTH Microservice")
     await connect_to_mongo()
     
+    # Initialize customer authentication collections
+    try:
+        from app.auth.db_init_customer import init_customer_auth_collections
+        await init_customer_auth_collections()
+        logger.info("Customer authentication collections initialized")
+    except Exception as e:
+        logger.error(f"Failed to initialize customer auth collections: {e}")
+    
     logger.info("AUTH Microservice started successfully")
     
     yield

mobile_app_example.js

@@ -0,0 +1,456 @@
+/**
+ * Mobile App Customer Authentication Example
+ * 
+ * This example shows how to integrate the customer authentication APIs
+ * in a React Native or similar mobile application.
+ */
+
+// Configuration
+const AUTH_BASE_URL = 'http://localhost:8001'; // Auth service URL
+
+// Storage utilities (use AsyncStorage in React Native)
+const storage = {
+  async setItem(key, value) {
+    // In React Native: await AsyncStorage.setItem(key, value);
+    localStorage.setItem(key, value);
+  },
+  
+  async getItem(key) {
+    // In React Native: return await AsyncStorage.getItem(key);
+    return localStorage.getItem(key);
+  },
+  
+  async removeItem(key) {
+    // In React Native: await AsyncStorage.removeItem(key);
+    localStorage.removeItem(key);
+  }
+};
+
+// Customer Authentication Service
+class CustomerAuthService {
+  
+  /**
+   * Send OTP to customer mobile number
+   */
+  static async sendOTP(mobile) {
+    try {
+      const response = await fetch(`${AUTH_BASE_URL}/auth/customer/send-otp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ mobile }),
+      });
+      
+      const data = await response.json();
+      
+      if (!response.ok) {
+        throw new Error(data.detail || 'Failed to send OTP');
+      }
+      
+      return {
+        success: true,
+        message: data.message,
+        expiresIn: data.expires_in,
+      };
+    } catch (error) {
+      console.error('Send OTP error:', error);
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+  
+  /**
+   * Verify OTP and authenticate customer
+   */
+  static async verifyOTP(mobile, otp) {
+    try {
+      const response = await fetch(`${AUTH_BASE_URL}/auth/customer/verify-otp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ mobile, otp }),
+      });
+      
+      const data = await response.json();
+      
+      if (!response.ok) {
+        throw new Error(data.detail || 'Failed to verify OTP');
+      }
+      
+      // Store authentication data
+      await storage.setItem('access_token', data.access_token);
+      await storage.setItem('customer_id', data.customer_id);
+      await storage.setItem('mobile', mobile);
+      
+      return {
+        success: true,
+        accessToken: data.access_token,
+        customerId: data.customer_id,
+        isNewCustomer: data.is_new_customer,
+        expiresIn: data.expires_in,
+      };
+    } catch (error) {
+      console.error('Verify OTP error:', error);
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+  
+  /**
+   * Get customer profile
+   */
+  static async getProfile() {
+    try {
+      const token = await storage.getItem('access_token');
+      
+      if (!token) {
+        throw new Error('No access token found');
+      }
+      
+      const response = await fetch(`${AUTH_BASE_URL}/auth/customer/me`, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+      });
+      
+      const data = await response.json();
+      
+      if (!response.ok) {
+        throw new Error(data.detail || 'Failed to get profile');
+      }
+      
+      return {
+        success: true,
+        profile: data,
+      };
+    } catch (error) {
+      console.error('Get profile error:', error);
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+  }
+  
+  /**
+   * Logout customer
+   */
+  static async logout() {
+    try {
+      const token = await storage.getItem('access_token');
+      
+      if (token) {
+        // Call logout endpoint
+        await fetch(`${AUTH_BASE_URL}/auth/customer/logout`, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+          },
+        });
+      }
+      
+      // Clear stored data
+      await storage.removeItem('access_token');
+      await storage.removeItem('customer_id');
+      await storage.removeItem('mobile');
+      
+      return { success: true };
+    } catch (error) {
+      console.error('Logout error:', error);
+      // Still clear local data even if API call fails
+      await storage.removeItem('access_token');
+      await storage.removeItem('customer_id');
+      await storage.removeItem('mobile');
+      
+      return { success: true };
+    }
+  }
+  
+  /**
+   * Check if customer is authenticated
+   */
+  static async isAuthenticated() {
+    try {
+      const token = await storage.getItem('access_token');
+      
+      if (!token) {
+        return false;
+      }
+      
+      // Check if token is expired (basic check)
+      const payload = JSON.parse(atob(token.split('.')[1]));
+      const currentTime = Math.floor(Date.now() / 1000);
+      
+      if (payload.exp && payload.exp < currentTime) {
+        // Token expired, clear storage
+        await this.logout();
+        return false;
+      }
+      
+      return true;
+    } catch (error) {
+      console.error('Auth check error:', error);
+      return false;
+    }
+  }
+  
+  /**
+   * Get stored customer data
+   */
+  static async getStoredCustomerData() {
+    try {
+      const [token, customerId, mobile] = await Promise.all([
+        storage.getItem('access_token'),
+        storage.getItem('customer_id'),
+        storage.getItem('mobile'),
+      ]);
+      
+      return {
+        accessToken: token,
+        customerId,
+        mobile,
+      };
+    } catch (error) {
+      console.error('Get stored data error:', error);
+      return {};
+    }
+  }
+}
+
+// Navigation utilities
+class NavigationService {
+  
+  /**
+   * Handle navigation based on authentication state
+   */
+  static async handleAuthNavigation() {
+    const isAuth = await CustomerAuthService.isAuthenticated();
+    
+    if (isAuth) {
+      // Redirect to main app
+      this.navigateToMainApp();
+    } else {
+      // Stay on or redirect to auth screen
+      this.navigateToAuth();
+    }
+  }
+  
+  static navigateToMainApp() {
+    // In React Native: navigation.navigate('MainTabs');
+    // In web: window.location.href = '/(tabs)/index';
+    console.log('Navigate to main app');
+  }
+  
+  static navigateToAuth() {
+    // In React Native: navigation.navigate('Auth');
+    // In web: window.location.href = '/auth';
+    console.log('Navigate to auth screen');
+  }
+}
+
+// Example usage in a React component
+class AuthScreen {
+  
+  constructor() {
+    this.state = {
+      mobile: '',
+      otp: '',
+      step: 'mobile', // 'mobile' | 'otp'
+      loading: false,
+      error: null,
+      otpTimer: 0,
+    };
+  }
+  
+  /**
+   * Handle mobile number submission
+   */
+  async handleSendOTP() {
+    if (!this.state.mobile) {
+      this.setState({ error: 'Please enter mobile number' });
+      return;
+    }
+    
+    this.setState({ loading: true, error: null });
+    
+    const result = await CustomerAuthService.sendOTP(this.state.mobile);
+    
+    if (result.success) {
+      this.setState({
+        step: 'otp',
+        loading: false,
+        otpTimer: result.expiresIn,
+      });
+      this.startOTPTimer();
+    } else {
+      this.setState({
+        loading: false,
+        error: result.error,
+      });
+    }
+  }
+  
+  /**
+   * Handle OTP verification
+   */
+  async handleVerifyOTP() {
+    if (!this.state.otp) {
+      this.setState({ error: 'Please enter OTP' });
+      return;
+    }
+    
+    this.setState({ loading: true, error: null });
+    
+    const result = await CustomerAuthService.verifyOTP(
+      this.state.mobile,
+      this.state.otp
+    );
+    
+    if (result.success) {
+      // Authentication successful
+      console.log('Customer authenticated:', result.customerId);
+      console.log('Is new customer:', result.isNewCustomer);
+      
+      // Navigate to main app
+      NavigationService.navigateToMainApp();
+    } else {
+      this.setState({
+        loading: false,
+        error: result.error,
+      });
+    }
+  }
+  
+  /**
+   * Start OTP countdown timer
+   */
+  startOTPTimer() {
+    const timer = setInterval(() => {
+      this.setState(prevState => {
+        if (prevState.otpTimer <= 1) {
+          clearInterval(timer);
+          return { otpTimer: 0 };
+        }
+        return { otpTimer: prevState.otpTimer - 1 };
+      });
+    }, 1000);
+  }
+  
+  /**
+   * Resend OTP
+   */
+  async handleResendOTP() {
+    await this.handleSendOTP();
+  }
+  
+  setState(newState) {
+    this.state = { ...this.state, ...newState };
+    // In React: this.setState(newState);
+  }
+}
+
+// App initialization
+class App {
+  
+  async componentDidMount() {
+    // Auto-restore session on app launch
+    await NavigationService.handleAuthNavigation();
+  }
+  
+  /**
+   * Make authenticated API calls
+   */
+  static async makeAuthenticatedRequest(url, options = {}) {
+    const { accessToken } = await CustomerAuthService.getStoredCustomerData();
+    
+    if (!accessToken) {
+      throw new Error('No access token available');
+    }
+    
+    const headers = {
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+      ...options.headers,
+    };
+    
+    const response = await fetch(url, {
+      ...options,
+      headers,
+    });
+    
+    if (response.status === 401) {
+      // Token expired, logout and redirect to auth
+      await CustomerAuthService.logout();
+      NavigationService.navigateToAuth();
+      throw new Error('Authentication expired');
+    }
+    
+    return response;
+  }
+}
+
+// Error handling utilities
+class ErrorHandler {
+  
+  static handleAuthError(error) {
+    const errorMessages = {
+      'Invalid mobile number format': 'Please enter a valid mobile number with country code (e.g., +919999999999)',
+      'Invalid OTP': 'The OTP you entered is incorrect. Please try again.',
+      'OTP has expired': 'The OTP has expired. Please request a new one.',
+      'Too many attempts': 'Too many failed attempts. Please request a new OTP.',
+      'OTP has already been used': 'This OTP has already been used. Please request a new one.',
+    };
+    
+    return errorMessages[error] || error || 'An unexpected error occurred';
+  }
+}
+
+// Export for use in React Native or other frameworks
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    CustomerAuthService,
+    NavigationService,
+    ErrorHandler,
+  };
+}
+
+// Example usage:
+/*
+// In your React Native component:
+import { CustomerAuthService, NavigationService } from './mobile_app_example';
+
+const LoginScreen = () => {
+  const [mobile, setMobile] = useState('');
+  const [otp, setOtp] = useState('');
+  const [step, setStep] = useState('mobile');
+  
+  const handleSendOTP = async () => {
+    const result = await CustomerAuthService.sendOTP(mobile);
+    if (result.success) {
+      setStep('otp');
+    } else {
+      Alert.alert('Error', result.error);
+    }
+  };
+  
+  const handleVerifyOTP = async () => {
+    const result = await CustomerAuthService.verifyOTP(mobile, otp);
+    if (result.success) {
+      navigation.navigate('MainTabs');
+    } else {
+      Alert.alert('Error', result.error);
+    }
+  };
+  
+  // ... render UI
+};
+*/

setup_customer_auth.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Setup script for customer authentication system.
+"""
+import asyncio
+import sys
+import os
+
+# Add the app directory to Python path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'app'))
+
+from app.core.logging import setup_logging, get_logger
+from app.nosql import connect_to_mongo, close_mongo_connection
+from app.auth.db_init_customer import init_customer_auth_collections
+
+# Setup logging
+setup_logging(log_level="INFO", log_dir="logs")
+logger = get_logger(__name__)
+
+
+async def setup_customer_auth():
+    """Setup customer authentication system."""
+    try:
+        print("🚀 Setting up Customer Authentication System")
+        print("=" * 50)
+        
+        # Connect to MongoDB
+        print("\n1️⃣ Connecting to MongoDB...")
+        await connect_to_mongo()
+        logger.info("✅ Connected to MongoDB")
+        
+        # Initialize collections and indexes
+        print("\n2️⃣ Initializing database collections...")
+        await init_customer_auth_collections()
+        logger.info("✅ Database collections initialized")
+        
+        # Verify setup
+        print("\n3️⃣ Verifying setup...")
+        from app.nosql import get_database
+        
+        db = get_database()
+        
+        # Check collections exist
+        collections = await db.list_collection_names()
+        required_collections = ['scm_customers', 'customer_otps']
+        
+        for collection in required_collections:
+            if collection in collections:
+                print(f"   ✅ Collection '{collection}' exists")
+            else:
+                print(f"   ❌ Collection '{collection}' missing")
+        
+        # Check indexes
+        customers_indexes = await db.scm_customers.list_indexes().to_list(length=None)
+        otps_indexes = await db.customer_otps.list_indexes().to_list(length=None)
+        
+        print(f"   📊 scm_customers indexes: {len(customers_indexes)}")
+        print(f"   📊 customer_otps indexes: {len(otps_indexes)}")
+        
+        print("\n🎉 Customer Authentication System setup completed!")
+        print("\n📋 Next Steps:")
+        print("   1. Start the auth service: python -m app.main")
+        print("   2. Test the APIs: python test_customer_auth.py")
+        print("   3. Check the documentation: CUSTOMER_AUTH_IMPLEMENTATION.md")
+        
+    except Exception as e:
+        logger.error(f"❌ Setup failed: {str(e)}", exc_info=True)
+        print(f"\n❌ Setup failed: {str(e)}")
+        return False
+    
+    finally:
+        # Close MongoDB connection
+        await close_mongo_connection()
+        logger.info("🔌 MongoDB connection closed")
+    
+    return True
+
+
+async def cleanup_customer_auth():
+    """Cleanup customer authentication collections (for testing)."""
+    try:
+        print("🧹 Cleaning up Customer Authentication Collections")
+        print("=" * 50)
+        
+        # Connect to MongoDB
+        await connect_to_mongo()
+        
+        from app.nosql import get_database
+        db = get_database()
+        
+        # Drop collections
+        collections_to_drop = ['scm_customers', 'customer_otps']
+        
+        for collection in collections_to_drop:
+            try:
+                await db.drop_collection(collection)
+                print(f"   ✅ Dropped collection '{collection}'")
+            except Exception as e:
+                print(f"   ⚠️  Collection '{collection}' not found or error: {e}")
+        
+        print("\n🎉 Cleanup completed!")
+        
+    except Exception as e:
+        logger.error(f"❌ Cleanup failed: {str(e)}", exc_info=True)
+        print(f"\n❌ Cleanup failed: {str(e)}")
+        return False
+    
+    finally:
+        await close_mongo_connection()
+    
+    return True
+
+
+async def main():
+    """Main function."""
+    if len(sys.argv) > 1 and sys.argv[1] == "cleanup":
+        await cleanup_customer_auth()
+    else:
+        await setup_customer_auth()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

test_customer_auth.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Test script for customer authentication APIs.
+"""
+import asyncio
+import aiohttp
+import json
+from typing import Dict, Any
+
+# Configuration
+BASE_URL = "http://localhost:8001"  # Auth service URL
+TEST_MOBILE = "+919999999999"
+
+
+async def test_customer_auth_flow():
+    """Test the complete customer authentication flow."""
+    async with aiohttp.ClientSession() as session:
+        print("🧪 Testing Customer Authentication Flow")
+        print("=" * 50)
+        
+        # Test 1: Send OTP
+        print("\n1️⃣ Testing Send OTP")
+        send_otp_data = {
+            "mobile": TEST_MOBILE
+        }
+        
+        async with session.post(
+            f"{BASE_URL}/auth/customer/send-otp",
+            json=send_otp_data,
+            headers={"Content-Type": "application/json"}
+        ) as response:
+            if response.status == 200:
+                result = await response.json()
+                print(f"✅ OTP sent successfully")
+                print(f"   Message: {result['message']}")
+                print(f"   Expires in: {result['expires_in']} seconds")
+            else:
+                error = await response.text()
+                print(f"❌ Failed to send OTP: {response.status}")
+                print(f"   Error: {error}")
+                return
+        
+        # Get OTP from user input (in production, this would come from SMS)
+        print(f"\n📱 Check the logs for OTP sent to {TEST_MOBILE}")
+        otp = input("Enter the OTP: ").strip()
+        
+        if not otp:
+            print("❌ No OTP provided, skipping verification test")
+            return
+        
+        # Test 2: Verify OTP
+        print(f"\n2️⃣ Testing Verify OTP")
+        verify_otp_data = {
+            "mobile": TEST_MOBILE,
+            "otp": otp
+        }
+        
+        async with session.post(
+            f"{BASE_URL}/auth/customer/verify-otp",
+            json=verify_otp_data,
+            headers={"Content-Type": "application/json"}
+        ) as response:
+            if response.status == 200:
+                result = await response.json()
+                access_token = result["access_token"]
+                print(f"✅ OTP verified successfully")
+                print(f"   Customer ID: {result['customer_id']}")
+                print(f"   Is new customer: {result['is_new_customer']}")
+                print(f"   Token expires in: {result['expires_in']} seconds")
+                print(f"   Access token: {access_token[:50]}...")
+            else:
+                error = await response.text()
+                print(f"❌ Failed to verify OTP: {response.status}")
+                print(f"   Error: {error}")
+                return
+        
+        # Test 3: Get Customer Profile
+        print(f"\n3️⃣ Testing Get Customer Profile")
+        headers = {
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json"
+        }
+        
+        async with session.get(
+            f"{BASE_URL}/auth/customer/me",
+            headers=headers
+        ) as response:
+            if response.status == 200:
+                result = await response.json()
+                print(f"✅ Customer profile retrieved")
+                print(f"   Customer ID: {result['customer_id']}")
+                print(f"   Mobile: {result['mobile']}")
+                print(f"   Merchant ID: {result['merchant_id']}")
+                print(f"   Type: {result['type']}")
+            else:
+                error = await response.text()
+                print(f"❌ Failed to get customer profile: {response.status}")
+                print(f"   Error: {error}")
+        
+        # Test 4: Customer Logout
+        print(f"\n4️⃣ Testing Customer Logout")
+        async with session.post(
+            f"{BASE_URL}/auth/customer/logout",
+            headers=headers
+        ) as response:
+            if response.status == 200:
+                result = await response.json()
+                print(f"✅ Customer logged out successfully")
+                print(f"   Message: {result['message']}")
+            else:
+                error = await response.text()
+                print(f"❌ Failed to logout customer: {response.status}")
+                print(f"   Error: {error}")
+        
+        print(f"\n🎉 Customer authentication flow test completed!")
+
+
+async def test_error_scenarios():
+    """Test error scenarios for customer authentication."""
+    async with aiohttp.ClientSession() as session:
+        print("\n🧪 Testing Error Scenarios")
+        print("=" * 50)
+        
+        # Test 1: Invalid mobile number format
+        print("\n1️⃣ Testing Invalid Mobile Format")
+        invalid_mobile_data = {
+            "mobile": "123456"  # Invalid format
+        }
+        
+        async with session.post(
+            f"{BASE_URL}/auth/customer/send-otp",
+            json=invalid_mobile_data,
+            headers={"Content-Type": "application/json"}
+        ) as response:
+            if response.status == 422:
+                print("✅ Invalid mobile format correctly rejected")
+            else:
+                print(f"❌ Expected 422, got {response.status}")
+        
+        # Test 2: Invalid OTP
+        print("\n2️⃣ Testing Invalid OTP")
+        invalid_otp_data = {
+            "mobile": TEST_MOBILE,
+            "otp": "000000"  # Invalid OTP
+        }
+        
+        async with session.post(
+            f"{BASE_URL}/auth/customer/verify-otp",
+            json=invalid_otp_data,
+            headers={"Content-Type": "application/json"}
+        ) as response:
+            if response.status == 401:
+                print("✅ Invalid OTP correctly rejected")
+            else:
+                print(f"❌ Expected 401, got {response.status}")
+        
+        # Test 3: Access protected endpoint without token
+        print("\n3️⃣ Testing Protected Endpoint Without Token")
+        async with session.get(
+            f"{BASE_URL}/auth/customer/me"
+        ) as response:
+            if response.status == 401:
+                print("✅ Protected endpoint correctly requires authentication")
+            else:
+                print(f"❌ Expected 401, got {response.status}")
+        
+        print(f"\n🎉 Error scenarios test completed!")
+
+
+async def main():
+    """Main test function."""
+    print("🚀 Starting Customer Authentication API Tests")
+    print(f"📍 Base URL: {BASE_URL}")
+    print(f"📱 Test Mobile: {TEST_MOBILE}")
+    
+    try:
+        # Test normal flow
+        await test_customer_auth_flow()
+        
+        # Test error scenarios
+        await test_error_scenarios()
+        
+    except Exception as e:
+        print(f"❌ Test failed with error: {str(e)}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())