feat(auth): add phone OTP verification API with SMS delivery

[Folex1275]

Phone OTP Verification Service

Closes #67

Summary

Implemented a complete phone number verification system using one-time SMS passcodes via Africa's Talking gateway.

Changes

Database

• Migration: 20260827120000_add_phone_otp_verification

  • Added phoneNumber, phoneCountryCode, isPhoneVerified, phoneVerifiedAt to users table
  • Created phone_otp table with OTP tracking, expiry, and attempt count
  • Added indexes for performance optimization

• Schema Updates: prisma/schema.prisma

  • Updated User model with phone verification fields
  • Added PhoneOtp model with full relations and indexes

Backend Services

• OTP Service: src/modules/auth/otp.service.ts

  • Generate 6-digit OTP codes
  • Send SMS via Africa's Talking
  • Validate OTP with expiry checking (10 minutes)
  • Track verification attempts (max 5 per OTP)
  • Rate limiting (3 requests per minute per phone)
  • Update user verification status
  • Automatic invalidation of previous unused OTPs

• OTP Controller: src/modules/auth/otp.controller.ts

  • POST /api/v1/otp/send - Send OTP to phone number
  • POST /api/v1/otp/verify - Verify submitted OTP
  • GET /api/v1/otp/status - Get verification status
  • JWT authentication on all endpoints

DTOs

• SendOtpDto: src/modules/auth/dto/send-otp.dto.ts

  • E.164 phone number validation
  • Country code validation (2-3 chars)

• VerifyOtpDto: src/modules/auth/dto/verify-otp.dto.ts

  • E.164 phone number validation
  • 6-digit OTP format validation

Module Updates

• AuthModule: src/modules/auth/auth.module.ts
  • Registered OtpController and OtpService
  • Exported OtpService for use in other modules

Testing

• Unit Tests: src/modules/auth/otp.service.spec.ts
  • OTP generation and sending
  • Rate limiting enforcement
  • OTP verification (valid, expired, invalid, max attempts)
  • Verification status retrieval

Documentation

• API Documentation: docs/PHONE_OTP_VERIFICATION_API.md
  • Complete endpoint documentation with examples
  • Request/response schemas
  • Error handling details
  • Security features overview
  • Usage flow diagrams
  • Configuration guide

Configuration

• Environment: .env.example
  • Documented OTP configuration constants
  • Africa's Talking credentials setup

Features Implemented

✅ OTP Generation and Send Requests

• Random 6-digit OTP generation
• SMS delivery via Africa's Talking
• Automatic invalidation of previous OTPs

✅ Expiry and Attempt Count Tracking

• 10-minute expiry window
• Maximum 5 verification attempts per OTP
• Automatic cleanup of expired/used OTPs

✅ OTP Validation

• Expiry checking with clear error messages
• Attempt count enforcement
• Single-use OTP pattern (marked as used after success)

✅ Rate Limiting

• Per-phone number rate limiting
• 3 requests per 60-second window
• Automatic window reset
• Helpful error messages with retry timing

✅ Verified Phone Status on Profile

• isPhoneVerified boolean flag
• phoneNumber storage
• phoneVerifiedAt timestamp
• Status endpoint for frontend integration

Security Considerations

1. Single-use OTPs: Previous unused OTPs invalidated on new request
2. Time-limited: 10-minute expiry window
3. Attempt limiting: Max 5 attempts prevents brute force
4. Rate limiting: Prevents SMS bombing attacks
5. Authenticated endpoints: JWT required for all operations
6. E.164 validation: Ensures proper phone number format

API Endpoints

# Send OTP
POST /api/v1/otp/send
Authorization: Bearer <token>
{
  "phoneNumber": "+254712345678",
  "countryCode": "KE"
}

# Verify OTP
POST /api/v1/otp/verify
Authorization: Bearer <token>
{
  "phoneNumber": "+254712345678",
  "otp": "123456"
}

# Get verification status
GET /api/v1/otp/status
Authorization: Bearer <token>

[drips-wave]

@Folex1275 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits