backend extended
This commit is contained in:
@@ -0,0 +1,226 @@
|
||||
# Password Reset Implementation Guide
|
||||
|
||||
## Overview
|
||||
The SerpentRace application includes a complete password reset system with email verification and secure token handling.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### 1. Forgot Password (Request Reset)
|
||||
**Endpoint:** `POST /api/users/forgot-password`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"email": "user@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"message": "If the email exists, a reset link has been sent to your email address."
|
||||
}
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Validates email format
|
||||
- Security: Always returns success message (doesn't reveal if email exists)
|
||||
- Generates secure reset token with 1-hour expiration
|
||||
- Sends multilingual email with reset link and token
|
||||
- Logs all password reset attempts
|
||||
|
||||
### 2. Reset Password (Complete Reset)
|
||||
**Endpoint:** `POST /api/users/reset-password`
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"token": "abc123def456ghi789",
|
||||
"newPassword": "newSecurePassword123!"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"message": "Password has been reset successfully. You can now login with your new password."
|
||||
}
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Validates token existence and expiration
|
||||
- Enforces password strength requirements
|
||||
- Hashes new password securely
|
||||
- Clears reset token after successful reset
|
||||
- Comprehensive error handling
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Security Features
|
||||
1. **Token Security:**
|
||||
- Tokens are hashed before storage
|
||||
- 1-hour expiration time
|
||||
- Single-use tokens (cleared after use)
|
||||
|
||||
2. **Password Validation:**
|
||||
- Minimum 6 characters
|
||||
- Maximum 100 characters
|
||||
- Password strength validation via PasswordService
|
||||
|
||||
3. **Email Privacy:**
|
||||
- Non-existent emails don't reveal account existence
|
||||
- Consistent response messages
|
||||
|
||||
### Error Handling
|
||||
- Invalid/expired tokens: `400 Bad Request`
|
||||
- Password validation failures: `400 Bad Request` with specific message
|
||||
- Token expiration: Clear error message
|
||||
- Server errors: `500 Internal Server Error`
|
||||
|
||||
### Email Templates
|
||||
The system supports multilingual email templates:
|
||||
- `password-reset.txt` (English)
|
||||
- `password-reset-hu.txt` (Hungarian)
|
||||
- `password-reset-de.txt` (German)
|
||||
|
||||
Templates include:
|
||||
- Reset URL link
|
||||
- Reset token (fallback)
|
||||
- Security warnings
|
||||
- Expiration information
|
||||
|
||||
## Testing the Implementation
|
||||
|
||||
### Test Forgot Password:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/users/forgot-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "test@example.com"}'
|
||||
```
|
||||
|
||||
### Test Reset Password:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/users/reset-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "your-reset-token", "newPassword": "newPassword123!"}'
|
||||
```
|
||||
|
||||
### Error Test Cases:
|
||||
1. **Invalid email format:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/users/forgot-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "invalid-email"}'
|
||||
```
|
||||
|
||||
2. **Missing token:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/users/reset-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"newPassword": "newPassword123!"}'
|
||||
```
|
||||
|
||||
3. **Weak password:**
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/users/reset-password \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "valid-token", "newPassword": "123"}'
|
||||
```
|
||||
|
||||
## Integration with Existing Services
|
||||
|
||||
### Used Services:
|
||||
- **EmailService:** Sends multilingual reset emails
|
||||
- **TokenService:** Generates and validates reset tokens
|
||||
- **PasswordService:** Validates and hashes passwords
|
||||
- **ValidationMiddleware:** Validates request data
|
||||
- **Logger:** Logs all operations for audit
|
||||
|
||||
### Database Integration:
|
||||
- **UserRepository:** Finds users by email/token, updates passwords
|
||||
- Token storage in user table with expiration
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
### Reset Flow:
|
||||
1. User clicks "Forgot Password" on login page
|
||||
2. User enters email address
|
||||
3. Frontend calls `/api/users/forgot-password`
|
||||
4. User receives email with reset link
|
||||
5. User clicks link or uses token
|
||||
6. Frontend presents password reset form
|
||||
7. Frontend calls `/api/users/reset-password`
|
||||
8. User can login with new password
|
||||
|
||||
### Sample Frontend Code:
|
||||
```javascript
|
||||
// Request password reset
|
||||
async function requestPasswordReset(email) {
|
||||
const response = await fetch('/api/users/forgot-password', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ email })
|
||||
});
|
||||
|
||||
if (response.ok) {
|
||||
alert('Reset link sent to your email!');
|
||||
}
|
||||
}
|
||||
|
||||
// Reset password
|
||||
async function resetPassword(token, newPassword) {
|
||||
const response = await fetch('/api/users/reset-password', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({ token, newPassword })
|
||||
});
|
||||
|
||||
if (response.ok) {
|
||||
alert('Password reset successful!');
|
||||
// Redirect to login
|
||||
} else {
|
||||
const error = await response.json();
|
||||
alert('Error: ' + error.error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
Required environment variables:
|
||||
```env
|
||||
# Email Configuration
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_SECURE=false
|
||||
EMAIL_USER=your-email@gmail.com
|
||||
EMAIL_PASS=your-app-password
|
||||
EMAIL_FROM=noreply@serpentrace.com
|
||||
|
||||
# Application URL for reset links
|
||||
APP_BASE_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
## Monitoring and Logging
|
||||
|
||||
All password reset operations are logged with:
|
||||
- Request details (sanitized)
|
||||
- Success/failure status
|
||||
- Error messages
|
||||
- User identification (when available)
|
||||
- Timestamps
|
||||
|
||||
Log entries help with:
|
||||
- Security monitoring
|
||||
- Troubleshooting issues
|
||||
- Audit trail compliance
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Rate Limiting:** Consider implementing rate limiting on password reset requests
|
||||
2. **IP Tracking:** Log IP addresses for security monitoring
|
||||
3. **Account Lockout:** Consider temporary lockout after multiple failed attempts
|
||||
4. **Token Entropy:** Tokens use cryptographically secure random generation
|
||||
5. **Email Security:** Ensure SMTP connection is encrypted
|
||||
|
||||
This implementation provides a secure, user-friendly password reset system that integrates seamlessly with the existing SerpentRace authentication infrastructure.
|
||||
Reference in New Issue
Block a user