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:

# 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:

   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:

   cd brand-master-chart
   helm upgrade brand-master . --namespace my-apps --wait
   

Read 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:

# 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

# 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

# This does everything: migrations + build + deploy
quick-fix.bat

Manual Step-by-Step

# 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)

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