brand-master/PASSWORD_RESET_GUIDE.md

# Password Reset with Email PIN - Implementation Summary

## What Was Implemented

### 1. Email Service Module ✅
**File**: `backend/app/services/email.py`

**Features**:
- `send_email()` - Generic SMTP email sender
- `send_password_reset_pin()` - Sends 6-digit PIN with HTML/plain text template
- `send_welcome_email()` - Welcome new users
- Graceful fallback: Prints to console if SMTP not configured
- Professional HTML email templates with branding

**Template Highlights**:
- Beautiful HTML design with Brand Master branding
- 6-digit PIN displayed prominently
- 15-minute expiration timer
- Instructions for password reset
- Responsive design
- Plain text fallback

### 2. Auth Router Integration ✅
**File**: `backend/app/routers/auth.py`

**Changes**:
- Imported email service functions
- Updated `request_reset_pin()` to send email instead of just printing
- Updated `register()` to send welcome email to new users
- Added error handling (non-blocking - won't fail if email fails)
- Removed PIN from API response (security fix)

**Flow**:
1. User requests password reset with email
2. System generates 6-digit PIN
3. Stores PIN in database with 15-minute expiration
4. **Sends PIN to user's email** (new!)
5. Falls back to console print if SMTP not configured
6. User enters PIN and new password
7. System validates PIN and updates password

### 3. Configuration Guide ✅
**File**: `EMAIL_SETUP.md`

**Includes**:
- 3 email provider options (Gmail, SendGrid, AWS SES)
- Step-by-step setup for each provider
- Kubernetes deployment configuration
- Secret management (production best practices)
- Testing instructions
- Troubleshooting guide
- Production checklist

### 4. Quick Fix Deployment Script ✅
**File**: `quick-fix.bat`

**Automates**:
- Applies both database migrations (007, 008)
- Builds backend and frontend Docker images
- Pushes to Harbor registry
- Deploys via Helm
- Shows next steps and instructions

## What You Need to Do

### REQUIRED Steps

#### 1. Apply Database Migrations (CRITICAL)
The system currently has errors because migrations aren't applied:

```bash
# Option A: Use quick-fix script (does everything)
quick-fix.bat

# Option B: Apply migrations manually
apply-migration.bat 007_enhance_contact_messages.sql
apply-migration.bat 008_add_username_to_users.sql
```

**These migrations fix**:
- ❌ "column full_name does not exist" → ✅ Renames name → full_name
- ❌ "column username does not exist" → ✅ Adds username column

#### 2. Configure Email (for password reset to work)

**Quick Setup (Gmail)**:

1. Get Gmail App Password:
   - Go to https://myaccount.google.com/apppasswords
   - Generate password for "Mail"
   - Copy 16-character password

2. Update `brand-master-chart/values.yaml`:
   ```yaml
   backend:
     env:
       # ... existing vars ...
       - name: SMTP_HOST
         value: "smtp.gmail.com"
       - name: SMTP_PORT
         value: "587"
       - name: SMTP_USERNAME
         value: "your-email@gmail.com"
       - name: SMTP_PASSWORD
         value: "abcd efgh ijkl mnop"  # Your 16-char app password
       - name: SMTP_FROM
         value: "Brand Master <noreply@brand-master.com>"
   ```

3. Redeploy:
   ```bash
   cd brand-master-chart
   helm upgrade brand-master . --namespace my-apps --wait
   ```

**Read [EMAIL_SETUP.md](EMAIL_SETUP.md) for**:
- Other email providers (SendGrid, AWS SES)
- Production setup with Kubernetes Secrets
- Troubleshooting guide

### OPTIONAL Steps

#### 3. Test Email Functionality

**Test Password Reset**:
```bash
# Request PIN
curl -X POST https://api-brand-master.dvirlabs.com/api/auth/request-reset-pin \
  -H "Content-Type: application/json" \
  -d '{"email": "your-test-email@gmail.com"}'

# Check your email for 6-digit PIN

# Reset password
curl -X POST https://api-brand-master.dvirlabs.com/api/auth/reset-password-with-pin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-test-email@gmail.com",
    "pin": "123456",
    "new_password": "NewPassword123!"
  }'
```

**Or test via UI**:
1. Go to https://brand-master.dvirlabs.com/login
2. Click "Forgot Password?"
3. Enter email
4. Check inbox for PIN
5. Enter PIN and new password

#### 4. Monitor Email Sending

```bash
# View backend logs
kubectl logs -n my-apps deployment/brand-master-backend -f

# Look for:
# ✅ Email sent successfully to user@example.com
# ⚠️ SMTP not configured. Email would have been sent to: ...
# ❌ Failed to send email: <error>
```

## Current Status

| Feature | Status | Notes |
|---------|--------|-------|
| Email service code | ✅ Complete | `backend/app/services/email.py` created |
| Password reset PIN email | ✅ Complete | Sends HTML email with 6-digit PIN |
| Welcome email | ✅ Complete | Sent on new user registration |
| Auth router integration | ✅ Complete | Email functions called in endpoints |
| Configuration guide | ✅ Complete | See `EMAIL_SETUP.md` |
| Deployment script | ✅ Complete | `quick-fix.bat` |
| Database migrations | ⚠️ **NOT APPLIED** | Must run migrations! |
| SMTP configuration | ⚠️ **NOT CONFIGURED** | Emails print to console until configured |
| Production deployment | ⚠️ Pending | Need to rebuild/redeploy |

## How It Works Now

### Without SMTP Configured (Current State)

**What happens**:
1. User requests password reset
2. System generates PIN
3. **Email service prints to console**:
   ```
   ⚠️ SMTP not configured. Email would have been sent to: user@example.com
   Subject: Brand Master - Password Reset PIN
   Body: Your PIN is: 123456
   ```
4. You check backend logs for the PIN
5. User can still reset password with the PIN

**This is fine for testing but not production!**

### With SMTP Configured (After Setup)

**What happens**:
1. User requests password reset
2. System generates PIN
3. **Email sent to user's inbox** ✅
4. User receives beautiful HTML email with PIN
5. User resets password (no need to check logs)

## Files Changed

### Created
- ✅ `backend/app/services/email.py` - Email service module
- ✅ `EMAIL_SETUP.md` - Email configuration guide
- ✅ `quick-fix.bat` - Automated deployment script
- ✅ `PASSWORD_RESET_GUIDE.md` - This file

### Modified
- ✅ `backend/app/routers/auth.py` - Integrated email service

### Ready to Apply
- ⚠️ `backend/migrations/007_enhance_contact_messages.sql`
- ⚠️ `backend/migrations/008_add_username_to_users.sql`

## Quick Start Commands

### Full Automated Deployment
```bash
# This does everything: migrations + build + deploy
quick-fix.bat
```

### Manual Step-by-Step
```bash
# 1. Apply migrations
apply-migration.bat 007_enhance_contact_messages.sql
apply-migration.bat 008_add_username_to_users.sql

# 2. Build images
cd backend && docker build -t harbor.dvirlabs.com/my-apps/brand-master-backend:latest . && cd ..
cd frontend && docker build -t harbor.dvirlabs.com/my-apps/brand-master-frontend:latest . && cd ..

# 3. Push images
docker push harbor.dvirlabs.com/my-apps/brand-master-backend:latest
docker push harbor.dvirlabs.com/my-apps/brand-master-frontend:latest

# 4. Deploy
cd brand-master-chart
helm upgrade brand-master . --namespace my-apps --wait
```

## Email Provider Recommendations

| Provider | Best For | Cost | Setup Difficulty |
|----------|----------|------|------------------|
| **Gmail** | Testing, Development | Free | Easy (App Password) |
| **SendGrid** | Production (Small) | Free tier: 100 emails/day | Medium |
| **AWS SES** | Production (Large) | $0.10 per 1000 emails | Medium-Hard |
| **Mailgun** | Production | Free tier: 5000 emails/month | Medium |

**My Recommendation**: 
- **For testing now**: Gmail (5 minutes to setup)
- **For production later**: SendGrid or AWS SES (better deliverability)

## Testing Checklist

After deployment:

- [ ] Can submit contact form without errors
- [ ] Can register with username and phone
- [ ] Can login with email, username, OR phone
- [ ] Can request password reset
- [ ] Receive PIN email (or see in logs if SMTP not configured)
- [ ] Can reset password with PIN
- [ ] PIN expires after 15 minutes
- [ ] Invalid PIN shows error
- [ ] Welcome email sent on registration

## Troubleshooting

### "Column full_name does not exist"
**Fix**: Run `apply-migration.bat 007_enhance_contact_messages.sql`

### "Column username does not exist"
**Fix**: Run `apply-migration.bat 008_add_username_to_users.sql`

### "SMTP not configured" in logs
**Fix**: Configure SMTP in `values.yaml` (see [EMAIL_SETUP.md](EMAIL_SETUP.md))

### PIN not received in email
**Fix**: Check backend logs for error message, verify SMTP credentials

### Emails go to spam
**Fix**: Use proper From address, setup SPF/DKIM, or use SendGrid/SES

## Next Features (Future)

Possible enhancements:
- ✉️ Order confirmation emails
- ✉️ Shipping notification emails
- ✉️ Contact form notification to admin
- ✉️ Email templates customization UI
- 📊 Email delivery tracking
- 🎨 Email template builder

---

**Implementation Date**: January 2025  
**Status**: Ready to deploy (migrations required)  
**Documentation**: EMAIL_SETUP.md, API_DOCUMENTATION.md