push md

FORGOT_PASSWORD_FLOW.md

@@ -0,0 +1,336 @@
+# Forgot Password Flow
+
+This document explains the complete password reset flow implemented in the Zurri API.
+
+## Overview
+
+The forgot password flow consists of three main steps:
+1. **Request Password Reset** - User requests a password reset
+2. **Receive Reset Link** - User receives a reset token (via email in production)
+3. **Reset Password** - User uses the token to set a new password
+
+## Flow Diagram
+
+```
+User → Forgot Password Request → Server generates token → User receives email
+                                                              ↓
+User ← Reset Link (with token) ← Email sent ← Token stored in DB
+  ↓
+User submits token + new password → Server validates → Password reset
+```
+
+## Step-by-Step Process
+
+### 1. Request Password Reset
+
+**Endpoint:** `POST /api/auth/forgot-password`
+
+**Request:**
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Process:**
+1. User submits their email address
+2. Server validates email format
+3. Server checks if user exists (for security, always returns success message)
+4. If user exists:
+   - Generates a secure random token (32 bytes, hex-encoded)
+   - Hashes the token using bcrypt (10 rounds)
+   - Stores hashed token in database
+   - Sets expiration time (1 hour from now)
+   - **In Development:** Returns token and reset URL in response
+   - **In Production:** Sends email with reset link (email service not yet implemented)
+
+**Response (Success):**
+```json
+{
+  "message": "If an account with that email exists, a password reset link has been sent.",
+  "resetToken": "abc123...",  // Only in development mode
+  "resetUrl": "http://localhost:3000/reset-password?token=abc123...&email=user@example.com"  // Only in development mode
+}
+```
+
+**Security Features:**
+- ✅ Always returns same message (prevents email enumeration)
+- ✅ Token is hashed before storage
+- ✅ Token expires after 1 hour
+- ✅ Rate limited: 3 requests per hour per IP
+- ✅ Email sanitization and validation
+
+### 2. User Receives Reset Link
+
+**In Development Mode:**
+- Token and URL are returned in the API response
+- Frontend can use this directly for testing
+
+**In Production Mode:**
+- Email service should send an email with:
+  - Reset link: `{FRONTEND_URL}/reset-password?token={TOKEN}&email={EMAIL}`
+  - Token expires in 1 hour
+  - Clear instructions
+
+**Reset Link Format:**
+```
+https://yourdomain.com/reset-password?token=abc123def456...&email=user@example.com
+```
+
+### 3. Reset Password
+
+**Endpoint:** `POST /api/auth/reset-password`
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "token": "abc123def456...",
+  "password": "NewSecurePassword123!"
+}
+```
+
+**Process:**
+1. Server validates email format
+2. Server validates password strength (8+ chars, uppercase, lowercase, number, special char)
+3. Server finds user by email
+4. Server checks if reset token exists and hasn't expired
+5. Server verifies token by comparing with hashed token in database
+6. If valid:
+   - Hashes new password (bcrypt, 12 rounds)
+   - Updates user password
+   - Clears reset token and expiration
+   - Resets failed login attempts
+   - Unlocks account if locked
+7. Returns success message
+
+**Response (Success):**
+```json
+{
+  "message": "Password has been reset successfully"
+}
+```
+
+**Response (Error - Expired Token):**
+```json
+{
+  "error": "Reset token has expired"
+}
+```
+
+**Response (Error - Invalid Token):**
+```json
+{
+  "error": "Invalid reset token"
+}
+```
+
+**Response (Error - Weak Password):**
+```json
+{
+  "error": "Password does not meet requirements",
+  "details": [
+    "Password must be at least 8 characters long",
+    "Password must contain at least one uppercase letter",
+    ...
+  ]
+}
+```
+
+**Security Features:**
+- ✅ Token can only be used once (deleted after use)
+- ✅ Token expires after 1 hour
+- ✅ Strong password requirements enforced
+- ✅ Token verification using secure comparison
+- ✅ Rate limited: 3 requests per hour per IP
+- ✅ Account automatically unlocked on successful reset
+
+## Password Requirements
+
+The new password must meet all of these requirements:
+- ✅ Minimum 8 characters
+- ✅ At least one uppercase letter (A-Z)
+- ✅ At least one lowercase letter (a-z)
+- ✅ At least one number (0-9)
+- ✅ At least one special character (!@#$%^&*()_+-=[]{}|;':",./<>?)
+
+## Database Schema
+
+The `users` table includes these fields for password reset:
+
+```typescript
+passwordResetToken?: string;      // Hashed reset token
+passwordResetExpires?: Date;       // Token expiration time
+failedLoginAttempts: number;       // Reset to 0 on successful reset
+lockedUntil?: Date;                // Cleared on successful reset
+```
+
+## Security Considerations
+
+### Token Security
+- Tokens are cryptographically random (32 bytes)
+- Tokens are hashed before storage (bcrypt)
+- Tokens are single-use (deleted after successful reset)
+- Tokens expire after 1 hour
+
+### Rate Limiting
+- **Forgot Password:** 3 requests per hour per IP
+- **Reset Password:** 3 requests per hour per IP
+- Prevents abuse and brute force attacks
+
+### Email Enumeration Prevention
+- Always returns same success message
+- Doesn't reveal if email exists or not
+- Prevents attackers from discovering valid emails
+
+### Token Storage
+- Tokens are hashed (not stored in plaintext)
+- Even if database is compromised, tokens can't be extracted
+- Uses secure bcrypt comparison
+
+## Frontend Integration
+
+### Step 1: Request Reset
+```javascript
+const response = await fetch('/api/auth/forgot-password', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ email: 'user@example.com' })
+});
+
+const data = await response.json();
+// Show success message (always the same)
+alert(data.message);
+```
+
+### Step 2: Handle Reset Link
+```javascript
+// Extract token and email from URL query params
+const urlParams = new URLSearchParams(window.location.search);
+const token = urlParams.get('token');
+const email = urlParams.get('email');
+
+// Show password reset form
+```
+
+### Step 3: Submit New Password
+```javascript
+const response = await fetch('/api/auth/reset-password', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    email: email,
+    token: token,
+    password: 'NewSecurePassword123!'
+  })
+});
+
+const data = await response.json();
+if (response.ok) {
+  // Redirect to login
+  window.location.href = '/login';
+} else {
+  // Show error (expired token, weak password, etc.)
+  alert(data.error);
+}
+```
+
+## Error Handling
+
+### Common Errors
+
+1. **Invalid Email Format**
+   - Status: 400
+   - Message: "Invalid email format"
+
+2. **Expired Token**
+   - Status: 400
+   - Message: "Reset token has expired"
+   - Action: User must request a new reset
+
+3. **Invalid Token**
+   - Status: 400
+   - Message: "Invalid reset token"
+   - Action: Check token is correct or request new one
+
+4. **Weak Password**
+   - Status: 400
+   - Message: "Password does not meet requirements"
+   - Details: Array of specific requirements not met
+
+5. **Rate Limit Exceeded**
+   - Status: 429
+   - Message: "Too many password reset requests. Please try again later."
+   - Action: Wait 1 hour
+
+## Testing
+
+### Development Mode
+- Reset token and URL are returned in API response
+- Useful for testing without email service
+- Can test full flow locally
+
+### Production Mode
+- Requires email service integration
+- Token only sent via email
+- More secure (no token in API response)
+
+## Email Service Integration (TODO)
+
+To complete the flow in production, integrate an email service:
+
+1. **Recommended Services:**
+   - SendGrid
+   - AWS SES
+   - Mailgun
+   - Nodemailer with SMTP
+
+2. **Email Template Should Include:**
+   - Reset link with token
+   - Expiration time (1 hour)
+   - Security warning
+   - Instructions
+
+3. **Example Integration:**
+```typescript
+// In forgot-password handler
+if (user) {
+  // ... generate token ...
+  
+  // Send email (example with Nodemailer)
+  await sendPasswordResetEmail({
+    to: user.email,
+    resetUrl: resetUrl,
+    expiresIn: '1 hour'
+  });
+}
+```
+
+## Additional Endpoint: Change Password
+
+For authenticated users who want to change their password:
+
+**Endpoint:** `POST /api/auth/change-password`  
+**Authentication:** Required (Bearer token)
+
+**Request:**
+```json
+{
+  "currentPassword": "CurrentPassword123!",
+  "newPassword": "NewSecurePassword123!"
+}
+```
+
+This allows users to change their password while logged in, without needing a reset token.
+
+## Summary
+
+The forgot password flow is secure, user-friendly, and follows security best practices:
+- ✅ Secure token generation and storage
+- ✅ Time-limited tokens (1 hour)
+- ✅ Strong password requirements
+- ✅ Rate limiting
+- ✅ Email enumeration prevention
+- ✅ Single-use tokens
+- ✅ Automatic account unlock
+