feat: Implement forgot password feature with email reset functionality

- Added `FORGOT_PASSWORD_QUICKSTART.md` for quick reference on setup and usage.
- Created `IMPLEMENTATION_SUMMARY.md` detailing the implementation process and features.
- Introduced new API endpoints for password reset: `/auth/forgot-password`, `/auth/verify-reset-token`, and `/auth/reset-password`.
- Developed email service in `app/utils/email_service.py` for sending transactional emails.
- Updated configuration in `app/core/config.py` to include password reset settings.
- Enhanced user service in `app/system_users/services/service.py` to handle password reset token creation, verification, and email sending.
- Added schemas for password reset requests in `app/system_users/schemas/schema.py`.
- Implemented token storage and management in `app/system_users/models/model.py`.
- Created a test script `test_forgot_password.py` to validate the complete password reset flow.
- Included troubleshooting and security features in documentation.

.env.forgot-password.example

@@ -0,0 +1,103 @@
+# ============================================
+# FORGOT PASSWORD FEATURE - SMTP CONFIGURATION
+# ============================================
+# Add these settings to your .env file to enable email functionality
+
+# Password Reset Configuration
+PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES=60
+PASSWORD_RESET_BASE_URL=http://localhost:3000/reset-password
+
+# ============================================
+# SMTP Email Configuration (Choose one)
+# ============================================
+
+# Option 1: Gmail (Recommended for testing)
+# -----------------------------------------
+# 1. Enable 2-Factor Authentication on your Google account
+# 2. Generate an App Password: https://myaccount.google.com/apppasswords
+# 3. Use the generated password below (NOT your regular Gmail password)
+
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-16-char-app-password
+SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+SMTP_USE_TLS=true
+
+
+# Option 2: SendGrid
+# -----------------------------------------
+# 1. Sign up at https://sendgrid.com/
+# 2. Generate an API key
+# 3. Use the API key as password
+
+# SMTP_HOST=smtp.sendgrid.net
+# SMTP_PORT=587
+# SMTP_USERNAME=apikey
+# SMTP_PASSWORD=your-sendgrid-api-key
+# SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+# SMTP_USE_TLS=true
+
+
+# Option 3: AWS SES
+# -----------------------------------------
+# 1. Set up AWS SES: https://aws.amazon.com/ses/
+# 2. Verify your domain/email
+# 3. Generate SMTP credentials
+
+# SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+# SMTP_PORT=587
+# SMTP_USERNAME=your-ses-smtp-username
+# SMTP_PASSWORD=your-ses-smtp-password
+# SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+# SMTP_USE_TLS=true
+
+
+# Option 4: Mailgun
+# -----------------------------------------
+# 1. Sign up at https://www.mailgun.com/
+# 2. Get your SMTP credentials
+
+# SMTP_HOST=smtp.mailgun.org
+# SMTP_PORT=587
+# SMTP_USERNAME=postmaster@your-domain.mailgun.org
+# SMTP_PASSWORD=your-mailgun-smtp-password
+# SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+# SMTP_USE_TLS=true
+
+
+# Option 5: Office 365 / Outlook
+# -----------------------------------------
+# SMTP_HOST=smtp.office365.com
+# SMTP_PORT=587
+# SMTP_USERNAME=your-email@outlook.com
+# SMTP_PASSWORD=your-password
+# SMTP_FROM_EMAIL=your-email@outlook.com
+# SMTP_USE_TLS=true
+
+
+# ============================================
+# Testing Configuration
+# ============================================
+
+# For local testing, you can use a service like Mailtrap
+# which captures emails without sending them
+# Sign up at: https://mailtrap.io/
+
+# SMTP_HOST=smtp.mailtrap.io
+# SMTP_PORT=2525
+# SMTP_USERNAME=your-mailtrap-username
+# SMTP_PASSWORD=your-mailtrap-password
+# SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+# SMTP_USE_TLS=true
+
+
+# ============================================
+# Additional Notes
+# ============================================
+
+# 1. Never commit actual credentials to version control
+# 2. Use environment-specific .env files (.env.development, .env.production)
+# 3. For production, use proper email service (SendGrid, AWS SES, etc.)
+# 4. Test email configuration with: python test_forgot_password.py --check-config
+# 5. Monitor email delivery and bounces in production

FORGOT_PASSWORD_FEATURE.md

@@ -0,0 +1,463 @@
+# Forgot Password Feature Documentation
+
+## Overview
+
+The forgot password feature allows users to securely reset their password by receiving a time-limited reset link via email. This implementation follows security best practices to prevent account enumeration and token reuse.
+
+## Architecture
+
+### Components
+
+1. **Email Service** (`app/utils/email_service.py`)
+   - Handles sending transactional emails via SMTP
+   - Uses `aiosmtplib` for async email delivery
+   - Provides HTML and plain text email templates
+
+2. **Service Layer** (`app/system_users/services/service.py`)
+   - `create_password_reset_token()` - Generates secure JWT token
+   - `send_password_reset_email()` - Sends reset email to user
+   - `verify_password_reset_token()` - Validates reset token
+   - `reset_password_with_token()` - Updates password with valid token
+
+3. **API Endpoints** (`app/system_users/controllers/router.py`)
+   - `POST /auth/forgot-password` - Request password reset
+   - `POST /auth/verify-reset-token` - Verify token validity
+   - `POST /auth/reset-password` - Reset password with token
+
+4. **Data Models** (`app/system_users/models/model.py`)
+   - Added `password_reset_token` field to SecuritySettingsModel
+   - Added `password_reset_token_created_at` timestamp
+
+## API Endpoints
+
+### 1. Request Password Reset
+
+**Endpoint:** `POST /auth/forgot-password`
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "If the email exists in our system, a password reset link has been sent"
+}
+```
+
+**Security Note:** This endpoint always returns success to prevent email enumeration attacks.
+
+---
+
+### 2. Verify Reset Token
+
+**Endpoint:** `POST /auth/verify-reset-token`
+
+**Request Body:**
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+**Success Response (200):**
+```json
+{
+  "success": true,
+  "message": "Reset token is valid",
+  "data": {
+    "email": "user@example.com"
+  }
+}
+```
+
+**Error Response (400):**
+```json
+{
+  "detail": "Invalid or expired reset token"
+}
+```
+
+---
+
+### 3. Reset Password
+
+**Endpoint:** `POST /auth/reset-password`
+
+**Request Body:**
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "new_password": "NewSecurePass123"
+}
+```
+
+**Success Response (200):**
+```json
+{
+  "success": true,
+  "message": "Password has been reset successfully. You can now login with your new password."
+}
+```
+
+**Error Response (400):**
+```json
+{
+  "detail": "Invalid or expired reset token"
+}
+```
+
+## Security Features
+
+### 1. Token Security
+- **JWT-based tokens** with expiration (default: 60 minutes)
+- **Secure random token** embedded in JWT for double verification
+- **One-time use** - Token is cleared after successful reset
+- **Server-side validation** - Token stored in database and verified on use
+
+### 2. Anti-Enumeration
+- Forgot password endpoint always returns success
+- No indication whether email exists in system
+- Prevents attackers from discovering valid email addresses
+
+### 3. Token Expiration
+- Configurable expiration time (default: 60 minutes)
+- Expired tokens are automatically rejected
+- Token creation timestamp stored in database
+
+### 4. Additional Protections
+- Tokens cleared after successful password reset
+- Failed login attempts reset after successful password reset
+- Account unlocked automatically after password reset
+- Password must meet complexity requirements
+
+## Configuration
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```bash
+# Password Reset Configuration
+PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES=60
+PASSWORD_RESET_BASE_URL=http://localhost:3000/reset-password
+
+# SMTP Configuration (required for email)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+SMTP_USE_TLS=true
+```
+
+### SMTP Configuration Examples
+
+#### Gmail
+```bash
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password  # Use App Password, not regular password
+SMTP_USE_TLS=true
+```
+
+#### SendGrid
+```bash
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=your-sendgrid-api-key
+SMTP_USE_TLS=true
+```
+
+#### AWS SES
+```bash
+SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+SMTP_PORT=587
+SMTP_USERNAME=your-ses-smtp-username
+SMTP_PASSWORD=your-ses-smtp-password
+SMTP_USE_TLS=true
+```
+
+## Email Template
+
+The password reset email includes:
+- Professional HTML design with inline CSS
+- Clear call-to-action button
+- Security warnings and expiration notice
+- Plain text fallback for email clients without HTML support
+- Company branding (Cuatro Labs)
+
+### Email Preview
+
+**Subject:** Password Reset Request - Cuatro Labs Auth
+
+The email contains:
+- Personalized greeting with user's first name
+- "Reset My Password" button linking to reset page
+- Security warnings about:
+  - 1-hour expiration
+  - One-time use only
+  - Ignore if not requested
+- Fallback plain text link
+- Professional footer
+
+## Frontend Integration
+
+### 1. Request Password Reset
+
+```javascript
+async function requestPasswordReset(email) {
+  const response = await fetch('/auth/forgot-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email })
+  });
+  
+  const data = await response.json();
+  
+  if (data.success) {
+    // Show success message
+    alert('Check your email for reset instructions');
+  }
+}
+```
+
+### 2. Verify Token on Page Load
+
+```javascript
+async function verifyResetToken(token) {
+  try {
+    const response = await fetch('/auth/verify-reset-token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token })
+    });
+    
+    if (response.ok) {
+      const data = await response.json();
+      return { valid: true, email: data.data.email };
+    } else {
+      return { valid: false, error: 'Token expired or invalid' };
+    }
+  } catch (error) {
+    return { valid: false, error: 'Network error' };
+  }
+}
+
+// Usage in reset page
+const urlParams = new URLSearchParams(window.location.search);
+const token = urlParams.get('token');
+
+if (token) {
+  const result = await verifyResetToken(token);
+  if (!result.valid) {
+    // Show error and redirect to forgot password page
+    alert(result.error);
+    window.location.href = '/forgot-password';
+  }
+}
+```
+
+### 3. Reset Password
+
+```javascript
+async function resetPassword(token, newPassword) {
+  const response = await fetch('/auth/reset-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ 
+      token, 
+      new_password: newPassword 
+    })
+  });
+  
+  const data = await response.json();
+  
+  if (response.ok && data.success) {
+    // Show success and redirect to login
+    alert('Password reset successful!');
+    window.location.href = '/login';
+  } else {
+    // Show error
+    alert(data.detail || 'Failed to reset password');
+  }
+}
+```
+
+## Testing
+
+### Manual Testing Steps
+
+1. **Request Password Reset**
+   ```bash
+   curl -X POST http://localhost:9182/auth/forgot-password \
+     -H "Content-Type: application/json" \
+     -d '{"email": "test@example.com"}'
+   ```
+
+2. **Check Email**
+   - Check the email inbox for test@example.com
+   - Copy the reset token from the URL in the email
+
+3. **Verify Token**
+   ```bash
+   curl -X POST http://localhost:9182/auth/verify-reset-token \
+     -H "Content-Type: application/json" \
+     -d '{"token": "YOUR_TOKEN_HERE"}'
+   ```
+
+4. **Reset Password**
+   ```bash
+   curl -X POST http://localhost:9182/auth/reset-password \
+     -H "Content-Type: application/json" \
+     -d '{
+       "token": "YOUR_TOKEN_HERE",
+       "new_password": "NewPassword123"
+     }'
+   ```
+
+5. **Login with New Password**
+   ```bash
+   curl -X POST http://localhost:9182/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{
+       "email_or_phone": "test@example.com",
+       "password": "NewPassword123"
+     }'
+   ```
+
+### Automated Tests
+
+Create a test file `test_password_reset.py`:
+
+```python
+import pytest
+from httpx import AsyncClient
+from app.main import app
+
+@pytest.mark.asyncio
+async def test_forgot_password():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.post(
+            "/auth/forgot-password",
+            json={"email": "test@example.com"}
+        )
+        assert response.status_code == 200
+        assert response.json()["success"] is True
+
+@pytest.mark.asyncio
+async def test_reset_password_invalid_token():
+    async with AsyncClient(app=app, base_url="http://test") as client:
+        response = await client.post(
+            "/auth/reset-password",
+            json={
+                "token": "invalid_token",
+                "new_password": "NewPassword123"
+            }
+        )
+        assert response.status_code == 400
+```
+
+## Troubleshooting
+
+### Email Not Sending
+
+1. **Check SMTP Configuration**
+   ```python
+   # In Python shell
+   from app.core.config import settings
+   print(f"SMTP Host: {settings.SMTP_HOST}")
+   print(f"SMTP Port: {settings.SMTP_PORT}")
+   print(f"SMTP Username: {settings.SMTP_USERNAME}")
+   ```
+
+2. **Test SMTP Connection**
+   ```python
+   import aiosmtplib
+   import asyncio
+   
+   async def test_smtp():
+       try:
+           await aiosmtplib.send(
+               message="Test",
+               hostname="smtp.gmail.com",
+               port=587,
+               username="your-email@gmail.com",
+               password="your-app-password",
+               use_tls=True
+           )
+           print("SMTP connection successful!")
+       except Exception as e:
+           print(f"Error: {e}")
+   
+   asyncio.run(test_smtp())
+   ```
+
+3. **Check Logs**
+   ```bash
+   tail -f logs/app.log | grep -i email
+   ```
+
+### Token Invalid or Expired
+
+1. **Check token expiration time in config**
+2. **Verify system clocks are synchronized**
+3. **Check if token was already used (one-time use)**
+4. **Verify JWT secret key matches**
+
+### Password Requirements Not Met
+
+The new password must:
+- Be at least 8 characters long
+- Contain at least one uppercase letter
+- Contain at least one lowercase letter
+- Contain at least one digit
+
+## Database Schema
+
+The password reset functionality adds these fields to the user document:
+
+```javascript
+{
+  "security_settings": {
+    "password_reset_token": "string (nullable)",
+    "password_reset_token_created_at": "datetime (nullable)",
+    // ... other security settings
+  }
+}
+```
+
+## Future Enhancements
+
+1. **Rate Limiting**
+   - Limit password reset requests per email per hour
+   - Prevent abuse and spam
+
+2. **Email Templates**
+   - Customizable email templates
+   - Multi-language support
+
+3. **SMS Reset Option**
+   - Alternative reset via SMS
+   - Two-factor authentication for reset
+
+4. **Admin Notifications**
+   - Alert admins of multiple failed reset attempts
+   - Security monitoring dashboard
+
+5. **Password History**
+   - Prevent reuse of recent passwords
+   - Store hashed password history
+
+## Support
+
+For issues or questions:
+- Check logs: `logs/app.log`
+- Review configuration: `.env` file
+- Contact: support@cuatrolabs.com

FORGOT_PASSWORD_QUICKSTART.md

@@ -0,0 +1,202 @@
+# Forgot Password - Quick Reference
+
+## 🚀 Quick Start
+
+### 1. Configure SMTP (Required)
+
+Add to your `.env` file:
+
+```bash
+# For Gmail
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password  # Generate at https://myaccount.google.com/apppasswords
+SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+SMTP_USE_TLS=true
+
+# Password Reset Settings
+PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES=60
+PASSWORD_RESET_BASE_URL=http://localhost:3000/reset-password
+```
+
+### 2. Test Email Configuration
+
+```bash
+python test_forgot_password.py --check-config
+```
+
+### 3. Test Complete Flow
+
+```bash
+python test_forgot_password.py user@example.com
+```
+
+---
+
+## 📡 API Endpoints
+
+### Request Password Reset
+```bash
+curl -X POST http://localhost:9182/auth/forgot-password \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+### Verify Reset Token
+```bash
+curl -X POST http://localhost:9182/auth/verify-reset-token \
+  -H "Content-Type: application/json" \
+  -d '{"token": "YOUR_TOKEN"}'
+```
+
+### Reset Password
+```bash
+curl -X POST http://localhost:9182/auth/reset-password \
+  -H "Content-Type: application/json" \
+  -d '{
+    "token": "YOUR_TOKEN",
+    "new_password": "NewPassword123"
+  }'
+```
+
+---
+
+## 🌐 Frontend Integration
+
+### Step 1: Forgot Password Page
+
+```javascript
+// Request password reset
+async function handleForgotPassword(email) {
+  const res = await fetch('/auth/forgot-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email })
+  });
+  
+  const data = await res.json();
+  alert('Check your email for reset instructions!');
+}
+```
+
+### Step 2: Reset Password Page
+
+```javascript
+// Get token from URL
+const params = new URLSearchParams(window.location.search);
+const token = params.get('token');
+
+// Verify token on page load
+async function verifyToken(token) {
+  const res = await fetch('/auth/verify-reset-token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token })
+  });
+  
+  if (!res.ok) {
+    alert('Invalid or expired link');
+    window.location.href = '/forgot-password';
+  }
+}
+
+// Reset password
+async function handleResetPassword(token, newPassword) {
+  const res = await fetch('/auth/reset-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token, new_password: newPassword })
+  });
+  
+  if (res.ok) {
+    alert('Password reset successful!');
+    window.location.href = '/login';
+  }
+}
+
+// Initialize
+verifyToken(token);
+```
+
+---
+
+## 🔒 Security Features
+
+✅ **Secure Tokens** - JWT with 60-minute expiration  
+✅ **One-Time Use** - Token invalidated after use  
+✅ **Anti-Enumeration** - No user existence disclosure  
+✅ **Password Requirements** - 8+ chars, uppercase, lowercase, digit  
+✅ **Account Unlock** - Failed attempts reset on password change  
+
+---
+
+## 📧 Email Template Features
+
+- Professional HTML design
+- Mobile responsive
+- Clear call-to-action button
+- Security warnings
+- Plain text fallback
+- Company branding
+
+---
+
+## 🐛 Troubleshooting
+
+### Email Not Sending?
+
+1. **Check SMTP config:**
+   ```bash
+   python test_forgot_password.py --check-config
+   ```
+
+2. **For Gmail:** Enable 2FA and create [App Password](https://myaccount.google.com/apppasswords)
+
+3. **Check logs:**
+   ```bash
+   tail -f logs/app.log | grep -i email
+   ```
+
+### Token Invalid?
+
+- Tokens expire after 60 minutes
+- Tokens can only be used once
+- Check system time is synchronized
+
+---
+
+## 📚 Full Documentation
+
+See [FORGOT_PASSWORD_FEATURE.md](FORGOT_PASSWORD_FEATURE.md) for complete documentation.
+
+---
+
+## ✅ Testing Checklist
+
+- [ ] Configure SMTP in `.env`
+- [ ] Run `python test_forgot_password.py --check-config`
+- [ ] Test with real user: `python test_forgot_password.py user@email.com`
+- [ ] Check email received
+- [ ] Click reset link
+- [ ] Set new password
+- [ ] Login with new password
+
+---
+
+## 🎯 API Response Examples
+
+### Success Response
+```json
+{
+  "success": true,
+  "message": "Password has been reset successfully"
+}
+```
+
+### Error Response
+```json
+{
+  "detail": "Invalid or expired reset token"
+}
+```

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,407 @@
+# 🔐 Forgot Password Feature - Implementation Summary
+
+## ✅ Implementation Complete
+
+The forgot password feature with email reset link has been successfully implemented in your authentication microservice.
+
+---
+
+## 📦 What Was Added
+
+### 1. New Files Created
+
+- **`app/utils/email_service.py`** - Email service for sending transactional emails
+- **`test_forgot_password.py`** - Test script for the feature
+- **`FORGOT_PASSWORD_FEATURE.md`** - Complete documentation
+- **`FORGOT_PASSWORD_QUICKSTART.md`** - Quick reference guide
+- **`.env.forgot-password.example`** - SMTP configuration examples
+
+### 2. Modified Files
+
+- **`app/system_users/schemas/schema.py`**
+  - Added `ForgotPasswordRequest` schema
+  - Added `ResetPasswordRequest` schema  
+  - Added `VerifyResetTokenRequest` schema
+
+- **`app/system_users/services/service.py`**
+  - Added `create_password_reset_token()` method
+  - Added `send_password_reset_email()` method
+  - Added `verify_password_reset_token()` method
+  - Added `reset_password_with_token()` method
+
+- **`app/system_users/controllers/router.py`**
+  - Added `POST /auth/forgot-password` endpoint
+  - Added `POST /auth/verify-reset-token` endpoint
+  - Added `POST /auth/reset-password` endpoint
+
+- **`app/system_users/models/model.py`**
+  - Added `password_reset_token` field to `SecuritySettingsModel`
+  - Added `password_reset_token_created_at` field
+
+- **`app/core/config.py`**
+  - Added `PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES` setting
+  - Added `PASSWORD_RESET_BASE_URL` setting
+
+---
+
+## 🚀 How to Use
+
+### Step 1: Configure SMTP
+
+Copy settings from `.env.forgot-password.example` to your `.env` file:
+
+```bash
+# For Gmail (easiest for testing)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password  # Get from https://myaccount.google.com/apppasswords
+SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+SMTP_USE_TLS=true
+
+# Password Reset Settings
+PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES=60
+PASSWORD_RESET_BASE_URL=http://localhost:3000/reset-password
+```
+
+### Step 2: Test Configuration
+
+```bash
+python test_forgot_password.py --check-config
+```
+
+### Step 3: Test Full Flow
+
+```bash
+python test_forgot_password.py user@example.com
+```
+
+---
+
+## 🌐 API Endpoints
+
+### 1. Request Password Reset
+
+**POST** `/auth/forgot-password`
+
+```bash
+curl -X POST http://localhost:9182/auth/forgot-password \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com"}'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "If the email exists in our system, a password reset link has been sent"
+}
+```
+
+### 2. Verify Reset Token
+
+**POST** `/auth/verify-reset-token`
+
+```bash
+curl -X POST http://localhost:9182/auth/verify-reset-token \
+  -H "Content-Type: application/json" \
+  -d '{"token": "YOUR_TOKEN"}'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Reset token is valid",
+  "data": {
+    "email": "user@example.com"
+  }
+}
+```
+
+### 3. Reset Password
+
+**POST** `/auth/reset-password`
+
+```bash
+curl -X POST http://localhost:9182/auth/reset-password \
+  -H "Content-Type: application/json" \
+  -d '{
+    "token": "YOUR_TOKEN",
+    "new_password": "NewPassword123"
+  }'
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Password has been reset successfully. You can now login with your new password."
+}
+```
+
+---
+
+## 🎨 Frontend Integration
+
+### Forgot Password Page
+
+```javascript
+async function requestPasswordReset(email) {
+  const response = await fetch('/auth/forgot-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email })
+  });
+  
+  const data = await response.json();
+  alert('Check your email for reset instructions!');
+}
+```
+
+### Reset Password Page
+
+```javascript
+// Get token from URL query parameter
+const urlParams = new URLSearchParams(window.location.search);
+const token = urlParams.get('token');
+
+// Verify token on page load
+async function verifyToken(token) {
+  const response = await fetch('/auth/verify-reset-token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token })
+  });
+  
+  if (!response.ok) {
+    alert('Invalid or expired reset link');
+    window.location.href = '/forgot-password';
+    return;
+  }
+  
+  const data = await response.json();
+  // Show reset form with email pre-filled
+  document.getElementById('email').value = data.data.email;
+}
+
+// Reset password
+async function resetPassword(token, newPassword) {
+  const response = await fetch('/auth/reset-password', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ 
+      token, 
+      new_password: newPassword 
+    })
+  });
+  
+  if (response.ok) {
+    alert('Password reset successful!');
+    window.location.href = '/login';
+  } else {
+    const data = await response.json();
+    alert(data.detail || 'Failed to reset password');
+  }
+}
+
+// Initialize
+verifyToken(token);
+```
+
+---
+
+## 🔒 Security Features
+
+✅ **JWT Tokens** - Secure, time-limited tokens (60 minutes)  
+✅ **One-Time Use** - Tokens invalidated after successful reset  
+✅ **Double Verification** - Token stored in both JWT and database  
+✅ **Anti-Enumeration** - Doesn't reveal if email exists  
+✅ **Password Requirements** - Enforced complexity rules  
+✅ **Account Unlock** - Failed login attempts reset on password change  
+✅ **Expiration** - Tokens automatically expire after 1 hour  
+
+---
+
+## 📧 Email Template
+
+Professional HTML email with:
+- Clean, modern design
+- Mobile responsive layout
+- Clear "Reset Password" button
+- Security warnings and instructions
+- Plain text fallback
+- Company branding
+
+---
+
+## 🧪 Testing
+
+### Manual Testing
+
+1. **Request reset:**
+   ```bash
+   curl -X POST http://localhost:9182/auth/forgot-password \
+     -H "Content-Type: application/json" \
+     -d '{"email": "test@example.com"}'
+   ```
+
+2. **Check email** for reset link
+
+3. **Copy token** from email URL
+
+4. **Verify token:**
+   ```bash
+   curl -X POST http://localhost:9182/auth/verify-reset-token \
+     -H "Content-Type: application/json" \
+     -d '{"token": "YOUR_TOKEN"}'
+   ```
+
+5. **Reset password:**
+   ```bash
+   curl -X POST http://localhost:9182/auth/reset-password \
+     -H "Content-Type: application/json" \
+     -d '{"token": "YOUR_TOKEN", "new_password": "NewPass123"}'
+   ```
+
+6. **Login** with new password
+
+### Automated Testing
+
+```bash
+# Check SMTP configuration
+python test_forgot_password.py --check-config
+
+# Test full flow
+python test_forgot_password.py user@example.com
+```
+
+---
+
+## 📝 Configuration Options
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES` | 60 | Token validity period |
+| `PASSWORD_RESET_BASE_URL` | `http://localhost:3000/reset-password` | Frontend reset page URL |
+| `SMTP_HOST` | - | SMTP server hostname |
+| `SMTP_PORT` | 587 | SMTP server port |
+| `SMTP_USERNAME` | - | SMTP authentication username |
+| `SMTP_PASSWORD` | - | SMTP authentication password |
+| `SMTP_FROM_EMAIL` | - | Sender email address |
+| `SMTP_USE_TLS` | true | Use TLS encryption |
+
+---
+
+## 🐛 Troubleshooting
+
+### Email Not Sending
+
+1. **Verify SMTP config:**
+   ```bash
+   python test_forgot_password.py --check-config
+   ```
+
+2. **For Gmail:**
+   - Enable 2-Factor Authentication
+   - Generate App Password at https://myaccount.google.com/apppasswords
+   - Use App Password, not regular password
+
+3. **Check logs:**
+   ```bash
+   tail -f logs/app.log | grep -i email
+   ```
+
+### Token Issues
+
+- **Expired:** Tokens expire after 60 minutes
+- **Already Used:** Tokens can only be used once
+- **Invalid:** Check JWT secret key matches
+
+### Password Requirements
+
+New password must:
+- Be at least 8 characters long
+- Contain at least one uppercase letter (A-Z)
+- Contain at least one lowercase letter (a-z)
+- Contain at least one digit (0-9)
+
+---
+
+## 📚 Documentation
+
+- **[FORGOT_PASSWORD_FEATURE.md](FORGOT_PASSWORD_FEATURE.md)** - Complete documentation
+- **[FORGOT_PASSWORD_QUICKSTART.md](FORGOT_PASSWORD_QUICKSTART.md)** - Quick reference
+- **[.env.forgot-password.example](.env.forgot-password.example)** - SMTP configuration examples
+
+---
+
+## ✅ Testing Checklist
+
+Before deploying to production:
+
+- [ ] Configure SMTP in `.env` file
+- [ ] Test SMTP configuration with `--check-config`
+- [ ] Test forgot password request
+- [ ] Verify email is received with correct formatting
+- [ ] Test reset link works
+- [ ] Test token expiration (wait 60+ minutes)
+- [ ] Test token can't be reused
+- [ ] Test invalid token handling
+- [ ] Test password requirements validation
+- [ ] Test successful password reset
+- [ ] Test login with new password
+- [ ] Test with non-existent email (should not reveal)
+- [ ] Test with inactive account
+- [ ] Check logs for any errors
+- [ ] Monitor email delivery in production
+
+---
+
+## 🎯 Next Steps
+
+1. **Configure SMTP** in your `.env` file
+2. **Test locally** using the test script
+3. **Update frontend** to integrate the new endpoints
+4. **Test thoroughly** before deploying to production
+5. **Monitor** email delivery and errors
+
+---
+
+## 🔮 Future Enhancements
+
+Potential improvements:
+- Rate limiting on password reset requests
+- SMS-based password reset option
+- Multi-language email templates
+- Password history to prevent reuse
+- Admin notifications for suspicious activity
+- Custom email templates per merchant type
+- Two-factor authentication for reset
+
+---
+
+## 💡 Tips
+
+1. **Use App Passwords** for Gmail (not regular password)
+2. **Test with Mailtrap.io** to avoid sending real emails during development
+3. **Monitor email deliverability** in production
+4. **Set up proper SPF/DKIM** records for your domain
+5. **Use professional email service** (SendGrid, AWS SES) for production
+6. **Log all password reset attempts** for security monitoring
+
+---
+
+## 🤝 Support
+
+For questions or issues:
+- Review logs: `logs/app.log`
+- Check configuration: `.env` file
+- Review documentation: `FORGOT_PASSWORD_FEATURE.md`
+- Run test script: `python test_forgot_password.py --check-config`
+
+---
+
+**Implementation completed successfully! 🎉**
+
+The forgot password feature is now fully integrated and ready to use.

app/core/config.py

@@ -33,6 +33,10 @@ class Settings(BaseSettings):
     MAX_FAILED_LOGIN_ATTEMPTS: int = int(os.getenv("MAX_FAILED_LOGIN_ATTEMPTS", "5"))
     ACCOUNT_LOCK_DURATION_MINUTES: int = int(os.getenv("ACCOUNT_LOCK_DURATION_MINUTES", "15"))
     REMEMBER_ME_TOKEN_HOURS: int = int(os.getenv("REMEMBER_ME_TOKEN_HOURS", "24"))
+    
+    # Password Reset Configuration
+    PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES: int = int(os.getenv("PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES", "60"))
+    PASSWORD_RESET_BASE_URL: str = os.getenv("PASSWORD_RESET_BASE_URL", "http://localhost:3000/reset-password")
 
     # API Configuration
     MAX_PAGE_SIZE: int = int(os.getenv("MAX_PAGE_SIZE", "100"))

app/system_users/controllers/router.py

@@ -14,6 +14,9 @@ from app.system_users.schemas.schema import (
     CreateUserRequest,
     UpdateUserRequest,
     ChangePasswordRequest,
+    ForgotPasswordRequest,
+    ResetPasswordRequest,
+    VerifyResetTokenRequest,
     UserInfoResponse,
     UserListResponse,
     UserListRequest,
@@ -560,6 +563,162 @@ async def change_password(
         )
 
 
+@router.post("/forgot-password", response_model=StandardResponse)
+async def forgot_password(
+    request_data: ForgotPasswordRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Request password reset link. Sends an email with reset link to the user.
+    
+    This endpoint always returns success to prevent email enumeration attacks.
+    
+    Raises:
+        HTTPException: 400 - Invalid email format
+        HTTPException: 500 - Server error
+    """
+    try:
+        # Validate email
+        if not request_data.email or not request_data.email.strip():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Email is required"
+            )
+        
+        # Send password reset email
+        # Note: We always return success to prevent email enumeration
+        await user_service.send_password_reset_email(request_data.email)
+        
+        logger.info(f"Password reset requested for email: {request_data.email}")
+        
+        return StandardResponse(
+            success=True,
+            message="If the email exists in our system, a password reset link has been sent"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error in forgot password: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to process password reset request"
+        )
+
+
+@router.post("/verify-reset-token", response_model=StandardResponse)
+async def verify_reset_token(
+    request_data: VerifyResetTokenRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Verify if a password reset token is valid.
+    
+    Use this endpoint to check if a token is valid before showing the reset password form.
+    
+    Raises:
+        HTTPException: 400 - Invalid or expired token
+        HTTPException: 500 - Server error
+    """
+    try:
+        # Validate token
+        if not request_data.token or not request_data.token.strip():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Reset token is required"
+            )
+        
+        # Verify token
+        token_data = await user_service.verify_password_reset_token(request_data.token)
+        
+        if not token_data:
+            logger.warning("Invalid or expired reset token verification attempt")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid or expired reset token"
+            )
+        
+        return StandardResponse(
+            success=True,
+            message="Reset token is valid",
+            data={"email": token_data.get("email")}
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error verifying reset token: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to verify reset token"
+        )
+
+
+@router.post("/reset-password", response_model=StandardResponse)
+async def reset_password(
+    request_data: ResetPasswordRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Reset password using a valid reset token.
+    
+    The token is validated and can only be used once. After successful reset,
+    the user can login with their new password.
+    
+    Raises:
+        HTTPException: 400 - Invalid token or password requirements not met
+        HTTPException: 500 - Server error
+    """
+    try:
+        # Validate inputs
+        if not request_data.token or not request_data.token.strip():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Reset token is required"
+            )
+        
+        if not request_data.new_password or not request_data.new_password.strip():
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="New password is required"
+            )
+        
+        if len(request_data.new_password) < 8:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Password must be at least 8 characters long"
+            )
+        
+        # Reset password
+        success, message = await user_service.reset_password_with_token(
+            token=request_data.token,
+            new_password=request_data.new_password
+        )
+        
+        if not success:
+            logger.warning(f"Password reset failed: {message}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=message
+            )
+        
+        logger.info("Password reset completed successfully")
+        
+        return StandardResponse(
+            success=True,
+            message="Password has been reset successfully. You can now login with your new password."
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error resetting password: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to reset password"
+        )
+
+
 @router.delete("/users/{user_id}", response_model=StandardResponse)
 async def deactivate_user(
     user_id: str,

app/system_users/models/model.py

@@ -44,6 +44,8 @@ class SecuritySettingsModel(BaseModel):
     account_locked_until: Optional[datetime] = Field(None, description="Account lock expiry time")
     last_password_change: Optional[datetime] = Field(None, description="Last password change timestamp")
     login_attempts: List[LoginAttemptModel] = Field(default_factory=list, description="Recent login attempts (last 10)")
+    password_reset_token: Optional[str] = Field(None, description="Password reset token (stored securely)")
+    password_reset_token_created_at: Optional[datetime] = Field(None, description="When reset token was created")
 
 
 class SystemUserModel(BaseModel):

app/system_users/schemas/schema.py

@@ -101,9 +101,32 @@ class ChangePasswordRequest(BaseModel):
         return v
 
 
+class ForgotPasswordRequest(BaseModel):
+    """Forgot password request schema."""
+    email: EmailStr = Field(..., description="Email address to receive reset link")
+
+
 class ResetPasswordRequest(BaseModel):
-    """Reset password request schema."""
-    email: EmailStr = Field(..., description="Email address")
+    """Reset password with token request schema."""
+    token: str = Field(..., description="Password reset token", min_length=20)
+    new_password: str = Field(..., description="New password", min_length=8, max_length=100)
+    
+    @validator('new_password')
+    def validate_new_password(cls, v):
+        if len(v) < 8:
+            raise ValueError('Password must be at least 8 characters long')
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain at least one uppercase letter')
+        if not any(c.islower() for c in v):
+            raise ValueError('Password must contain at least one lowercase letter')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain at least one digit')
+        return v
+
+
+class VerifyResetTokenRequest(BaseModel):
+    """Verify reset token request schema."""
+    token: str = Field(..., description="Password reset token to verify")
 
 
 class UserListResponse(BaseModel):

app/system_users/services/service.py

@@ -26,6 +26,7 @@ from app.system_users.schemas.schema import (
 from app.constants.collections import AUTH_SYSTEM_USERS_COLLECTION, AUTH_ACCESS_ROLES_COLLECTION, SCM_ACCESS_ROLES_COLLECTION
 from app.core.config import settings
 from app.core.logging import get_logger
+from app.utils.email_service import email_service
 
 logger = get_logger(__name__)
 
@@ -502,6 +503,215 @@ class SystemUserService:
             logger.error(f"Error deactivating user {user_id}: {e}")
             return False
 
+    async def create_password_reset_token(self, email: str) -> Optional[str]:
+        """
+        Create a password reset token for a user.
+        
+        Args:
+            email: User's email address
+            
+        Returns:
+            Reset token string or None if user not found
+        """
+        try:
+            # Get user by email
+            user = await self.get_user_by_email(email)
+            if not user:
+                logger.warning(f"Password reset requested for non-existent email: {email}")
+                # Don't reveal that user doesn't exist for security
+                return None
+            
+            # Check if account is active
+            if user.status not in [UserStatus.ACTIVE, UserStatus.PENDING_ACTIVATION]:
+                logger.warning(f"Password reset requested for {user.status.value} account: {email}")
+                return None
+            
+            # Generate secure token
+            reset_token = secrets.token_urlsafe(32)
+            
+            # Create JWT token with expiration
+            token_data = {
+                "sub": user.user_id,
+                "email": user.email,
+                "type": "password_reset",
+                "token": reset_token,
+                "exp": datetime.utcnow() + timedelta(minutes=settings.PASSWORD_RESET_TOKEN_EXPIRATION_MINUTES)
+            }
+            
+            jwt_token = jwt.encode(token_data, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+            
+            # Store reset token info in database
+            await self.collection.update_one(
+                {"user_id": user.user_id},
+                {"$set": {
+                    "security_settings.password_reset_token": reset_token,
+                    "security_settings.password_reset_token_created_at": datetime.utcnow(),
+                    "updated_at": datetime.utcnow()
+                }}
+            )
+            
+            logger.info(f"Password reset token created for user: {user.user_id}")
+            return jwt_token
+            
+        except Exception as e:
+            logger.error(f"Error creating password reset token: {e}")
+            return None
+
+    async def send_password_reset_email(self, email: str) -> bool:
+        """
+        Generate password reset token and send reset email.
+        
+        Args:
+            email: User's email address
+            
+        Returns:
+            True if email was sent successfully, False otherwise
+        """
+        try:
+            # Get user
+            user = await self.get_user_by_email(email)
+            if not user:
+                # Don't reveal that user doesn't exist
+                logger.warning(f"Password reset email requested for non-existent email: {email}")
+                return True  # Return true to not leak information
+            
+            # Create reset token
+            reset_token = await self.create_password_reset_token(email)
+            if not reset_token:
+                logger.error(f"Failed to create reset token for: {email}")
+                return False
+            
+            # Build reset link
+            reset_link = f"{settings.PASSWORD_RESET_BASE_URL}?token={reset_token}"
+            
+            # Send email
+            email_sent = await email_service.send_password_reset_email(
+                to_email=user.email,
+                reset_link=reset_link,
+                user_name=user.first_name
+            )
+            
+            if email_sent:
+                logger.info(f"Password reset email sent to: {email}")
+            else:
+                logger.error(f"Failed to send password reset email to: {email}")
+            
+            return email_sent
+            
+        except Exception as e:
+            logger.error(f"Error sending password reset email: {e}")
+            return False
+
+    async def verify_password_reset_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """
+        Verify password reset token and return user info.
+        
+        Args:
+            token: JWT reset token
+            
+        Returns:
+            Dict with user_id and email if valid, None otherwise
+        """
+        try:
+            # Decode JWT token
+            payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+            
+            # Check token type
+            if payload.get("type") != "password_reset":
+                logger.warning("Invalid token type for password reset")
+                return None
+            
+            user_id = payload.get("sub")
+            email = payload.get("email")
+            reset_token = payload.get("token")
+            
+            if not all([user_id, email, reset_token]):
+                logger.warning("Missing required fields in reset token")
+                return None
+            
+            # Get user from database
+            user = await self.get_user_by_id(user_id)
+            if not user:
+                logger.warning(f"User not found for reset token: {user_id}")
+                return None
+            
+            # Verify email matches
+            if user.email != email:
+                logger.warning(f"Email mismatch in reset token for user: {user_id}")
+                return None
+            
+            # Verify token matches stored token
+            stored_token = user.security_settings.password_reset_token
+            if not stored_token or stored_token != reset_token:
+                logger.warning(f"Reset token mismatch for user: {user_id}")
+                return None
+            
+            # Check if token was used (token should be cleared after use)
+            if not user.security_settings.password_reset_token:
+                logger.warning(f"Reset token already used for user: {user_id}")
+                return None
+            
+            return {
+                "user_id": user_id,
+                "email": email,
+                "token": reset_token
+            }
+            
+        except JWTError as e:
+            logger.warning(f"Invalid or expired reset token: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Error verifying reset token: {e}")
+            return None
+
+    async def reset_password_with_token(self, token: str, new_password: str) -> Tuple[bool, str]:
+        """
+        Reset user password using reset token.
+        
+        Args:
+            token: JWT reset token
+            new_password: New password to set
+            
+        Returns:
+            Tuple of (success: bool, message: str)
+        """
+        try:
+            # Verify token
+            token_data = await self.verify_password_reset_token(token)
+            if not token_data:
+                return False, "Invalid or expired reset token"
+            
+            user_id = token_data["user_id"]
+            
+            # Hash new password
+            new_password_hash = self.get_password_hash(new_password)
+            
+            # Update password and clear reset token
+            result = await self.collection.update_one(
+                {"user_id": user_id},
+                {"$set": {
+                    "password_hash": new_password_hash,
+                    "security_settings.password_reset_token": None,
+                    "security_settings.password_reset_token_created_at": None,
+                    "security_settings.last_password_change": datetime.utcnow(),
+                    "security_settings.require_password_change": False,
+                    "security_settings.failed_login_attempts": 0,
+                    "security_settings.account_locked_until": None,
+                    "updated_at": datetime.utcnow()
+                }}
+            )
+            
+            if result.modified_count > 0:
+                logger.info(f"Password reset successfully for user: {user_id}")
+                return True, "Password reset successfully"
+            else:
+                logger.error(f"Failed to update password for user: {user_id}")
+                return False, "Failed to reset password"
+            
+        except Exception as e:
+            logger.error(f"Error resetting password: {e}")
+            return False, "An error occurred while resetting password"
+
     def convert_to_user_info_response(self, user: SystemUserModel) -> UserInfoResponse:
         """Convert SystemUserModel to UserInfoResponse."""
         return UserInfoResponse(

app/utils/email_service.py

@@ -0,0 +1,245 @@
+"""
+Email service for sending transactional emails.
+Uses aiosmtplib for async email sending.
+"""
+import aiosmtplib
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from typing import Optional, List
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class EmailService:
+    """Service for sending emails via SMTP."""
+    
+    def __init__(self):
+        self.smtp_host = settings.SMTP_HOST
+        self.smtp_port = settings.SMTP_PORT
+        self.smtp_username = settings.SMTP_USERNAME
+        self.smtp_password = settings.SMTP_PASSWORD
+        self.from_email = settings.SMTP_FROM_EMAIL or settings.SMTP_USERNAME
+        self.use_tls = settings.SMTP_USE_TLS
+    
+    async def send_email(
+        self,
+        to_email: str,
+        subject: str,
+        html_content: str,
+        plain_content: Optional[str] = None
+    ) -> bool:
+        """
+        Send an email using SMTP.
+        
+        Args:
+            to_email: Recipient email address
+            subject: Email subject
+            html_content: HTML email content
+            plain_content: Plain text fallback content
+            
+        Returns:
+            True if email was sent successfully, False otherwise
+        """
+        try:
+            # Validate SMTP configuration
+            if not all([self.smtp_host, self.smtp_port, self.from_email]):
+                logger.error("SMTP configuration is incomplete")
+                return False
+            
+            # Create message
+            message = MIMEMultipart("alternative")
+            message["From"] = self.from_email
+            message["To"] = to_email
+            message["Subject"] = subject
+            
+            # Add plain text part if provided
+            if plain_content:
+                part1 = MIMEText(plain_content, "plain")
+                message.attach(part1)
+            
+            # Add HTML part
+            part2 = MIMEText(html_content, "html")
+            message.attach(part2)
+            
+            # Send email
+            await aiosmtplib.send(
+                message,
+                hostname=self.smtp_host,
+                port=self.smtp_port,
+                username=self.smtp_username,
+                password=self.smtp_password,
+                use_tls=self.use_tls,
+            )
+            
+            logger.info(f"Email sent successfully to {to_email}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Failed to send email to {to_email}: {e}", exc_info=True)
+            return False
+    
+    async def send_password_reset_email(
+        self,
+        to_email: str,
+        reset_link: str,
+        user_name: Optional[str] = None
+    ) -> bool:
+        """
+        Send password reset email with reset link.
+        
+        Args:
+            to_email: Recipient email address
+            reset_link: Password reset link
+            user_name: User's first name (optional)
+            
+        Returns:
+            True if email was sent successfully, False otherwise
+        """
+        name = user_name or "User"
+        
+        subject = "Password Reset Request - Cuatro Labs Auth"
+        
+        # HTML content
+        html_content = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <style>
+                body {{
+                    font-family: Arial, sans-serif;
+                    line-height: 1.6;
+                    color: #333333;
+                    max-width: 600px;
+                    margin: 0 auto;
+                    padding: 20px;
+                }}
+                .container {{
+                    background-color: #f9f9f9;
+                    border-radius: 10px;
+                    padding: 30px;
+                    border: 1px solid #e0e0e0;
+                }}
+                .header {{
+                    text-align: center;
+                    margin-bottom: 30px;
+                }}
+                .header h1 {{
+                    color: #2c3e50;
+                    margin: 0;
+                    font-size: 24px;
+                }}
+                .content {{
+                    background-color: white;
+                    padding: 25px;
+                    border-radius: 8px;
+                    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+                }}
+                .button {{
+                    display: inline-block;
+                    padding: 12px 30px;
+                    background-color: #3498db;
+                    color: white !important;
+                    text-decoration: none;
+                    border-radius: 5px;
+                    margin: 20px 0;
+                    font-weight: bold;
+                }}
+                .button:hover {{
+                    background-color: #2980b9;
+                }}
+                .footer {{
+                    margin-top: 30px;
+                    text-align: center;
+                    font-size: 12px;
+                    color: #777777;
+                }}
+                .warning {{
+                    background-color: #fff3cd;
+                    border-left: 4px solid #ffc107;
+                    padding: 12px;
+                    margin: 20px 0;
+                    border-radius: 4px;
+                }}
+                .link-text {{
+                    word-break: break-all;
+                    color: #3498db;
+                    font-size: 12px;
+                    margin-top: 15px;
+                }}
+            </style>
+        </head>
+        <body>
+            <div class="container">
+                <div class="header">
+                    <h1>🔐 Password Reset Request</h1>
+                </div>
+                
+                <div class="content">
+                    <p>Hello <strong>{name}</strong>,</p>
+                    
+                    <p>We received a request to reset the password for your account. If you made this request, click the button below to reset your password:</p>
+                    
+                    <div style="text-align: center;">
+                        <a href="{reset_link}" class="button">Reset My Password</a>
+                    </div>
+                    
+                    <div class="warning">
+                        <strong>⚠️ Important:</strong>
+                        <ul style="margin: 10px 0;">
+                            <li>This link will expire in <strong>1 hour</strong></li>
+                            <li>This link can only be used once</li>
+                            <li>If you didn't request this, please ignore this email</li>
+                        </ul>
+                    </div>
+                    
+                    <p>If the button doesn't work, you can copy and paste this link into your browser:</p>
+                    <p class="link-text">{reset_link}</p>
+                    
+                    <p style="margin-top: 25px;">If you didn't request a password reset, please ignore this email or contact support if you have concerns about your account security.</p>
+                </div>
+                
+                <div class="footer">
+                    <p>This is an automated message from Cuatro Labs Authentication Service.</p>
+                    <p>Please do not reply to this email.</p>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+        
+        # Plain text fallback
+        plain_content = f"""
+        Password Reset Request
+        
+        Hello {name},
+        
+        We received a request to reset the password for your account.
+        
+        To reset your password, please click the following link:
+        {reset_link}
+        
+        IMPORTANT:
+        - This link will expire in 1 hour
+        - This link can only be used once
+        - If you didn't request this, please ignore this email
+        
+        If you didn't request a password reset, please ignore this email or contact support if you have concerns.
+        
+        ---
+        Cuatro Labs Authentication Service
+        """
+        
+        return await self.send_email(
+            to_email=to_email,
+            subject=subject,
+            html_content=html_content,
+            plain_content=plain_content
+        )
+
+
+# Global email service instance
+email_service = EmailService()

test_forgot_password.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Test script for forgot password functionality.
+"""
+import asyncio
+import sys
+from motor.motor_asyncio import AsyncIOMotorClient
+from app.core.config import settings
+from app.system_users.services.service import SystemUserService
+from app.system_users.schemas.schema import ForgotPasswordRequest, ResetPasswordRequest
+
+async def test_forgot_password_flow():
+    """Test the complete forgot password flow."""
+    print("=" * 60)
+    print("Testing Forgot Password Feature")
+    print("=" * 60)
+    
+    # Get email from command line or use default
+    email = sys.argv[1] if len(sys.argv) > 1 else "test@example.com"
+    
+    try:
+        # Connect to database
+        print(f"\n1. Connecting to database...")
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        service = SystemUserService(db)
+        
+        # Check if user exists
+        print(f"\n2. Checking if user exists: {email}")
+        user = await service.get_user_by_email(email)
+        
+        if not user:
+            print(f"❌ User with email {email} not found!")
+            print(f"   Please create a user first or provide a valid email address.")
+            return
+        
+        print(f"✅ User found: {user.username} ({user.first_name} {user.last_name})")
+        print(f"   User ID: {user.user_id}")
+        print(f"   Status: {user.status.value}")
+        
+        # Test password reset token creation
+        print(f"\n3. Creating password reset token...")
+        token = await service.create_password_reset_token(email)
+        
+        if not token:
+            print("❌ Failed to create password reset token!")
+            return
+        
+        print(f"✅ Password reset token created successfully")
+        print(f"   Token (first 50 chars): {token[:50]}...")
+        
+        # Verify the token
+        print(f"\n4. Verifying password reset token...")
+        token_data = await service.verify_password_reset_token(token)
+        
+        if not token_data:
+            print("❌ Token verification failed!")
+            return
+        
+        print(f"✅ Token verified successfully")
+        print(f"   User ID: {token_data['user_id']}")
+        print(f"   Email: {token_data['email']}")
+        
+        # Test sending email (if SMTP is configured)
+        print(f"\n5. Testing email sending...")
+        
+        if not all([settings.SMTP_HOST, settings.SMTP_USERNAME, settings.SMTP_PASSWORD]):
+            print("⚠️  SMTP not configured. Skipping email test.")
+            print("   To enable email, configure these environment variables:")
+            print("   - SMTP_HOST")
+            print("   - SMTP_PORT")
+            print("   - SMTP_USERNAME")
+            print("   - SMTP_PASSWORD")
+            print("   - SMTP_FROM_EMAIL")
+        else:
+            print(f"   SMTP Host: {settings.SMTP_HOST}")
+            print(f"   SMTP Port: {settings.SMTP_PORT}")
+            print(f"   From Email: {settings.SMTP_FROM_EMAIL}")
+            print(f"   Attempting to send email...")
+            
+            email_sent = await service.send_password_reset_email(email)
+            
+            if email_sent:
+                print(f"✅ Password reset email sent successfully!")
+                print(f"   Check inbox for: {email}")
+            else:
+                print(f"❌ Failed to send password reset email")
+                print(f"   Check logs for details")
+        
+        # Generate reset link
+        print(f"\n6. Generated reset link:")
+        reset_link = f"{settings.PASSWORD_RESET_BASE_URL}?token={token}"
+        print(f"   {reset_link}")
+        
+        # Summary
+        print("\n" + "=" * 60)
+        print("Test Summary")
+        print("=" * 60)
+        print("✅ All core functionality tests passed!")
+        print("\nNext steps:")
+        print("1. Copy the reset link above")
+        print("2. Open it in your browser")
+        print("3. Enter a new password")
+        print("4. Test login with the new password")
+        
+        print("\nOr test password reset via API:")
+        print(f"""
+curl -X POST http://localhost:9182/auth/reset-password \\
+  -H "Content-Type: application/json" \\
+  -d '{{
+    "token": "{token[:50]}...",
+    "new_password": "NewTestPassword123"
+  }}'
+        """)
+        
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        client.close()
+
+
+async def test_email_configuration():
+    """Test email configuration."""
+    print("=" * 60)
+    print("Email Configuration Test")
+    print("=" * 60)
+    
+    print(f"\nSMTP Settings:")
+    print(f"  Host: {settings.SMTP_HOST or '❌ Not configured'}")
+    print(f"  Port: {settings.SMTP_PORT}")
+    print(f"  Username: {settings.SMTP_USERNAME or '❌ Not configured'}")
+    print(f"  Password: {'***' if settings.SMTP_PASSWORD else '❌ Not configured'}")
+    print(f"  From Email: {settings.SMTP_FROM_EMAIL or settings.SMTP_USERNAME or '❌ Not configured'}")
+    print(f"  Use TLS: {settings.SMTP_USE_TLS}")
+    
+    if not all([settings.SMTP_HOST, settings.SMTP_USERNAME, settings.SMTP_PASSWORD]):
+        print("\n⚠️  SMTP is not fully configured!")
+        print("Please set these environment variables in your .env file:")
+        print("""
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your-email@gmail.com
+SMTP_PASSWORD=your-app-password
+SMTP_FROM_EMAIL=noreply@cuatrolabs.com
+SMTP_USE_TLS=true
+        """)
+    else:
+        print("\n✅ SMTP configuration looks good!")
+
+
+if __name__ == "__main__":
+    print("\nForgot Password Feature Test\n")
+    
+    if len(sys.argv) > 1 and sys.argv[1] == "--check-config":
+        asyncio.run(test_email_configuration())
+    else:
+        asyncio.run(test_forgot_password_flow())