normogen/backend/PHASE-2.4-SPEC.md

# Phase 2.4: User Management Enhancement

**Status**: 🚧 In Development  
**Started**: 2026-02-15  
**Last Updated**: 2026-02-15 16:33:00 UTC

---

## Overview

This phase enhances user management capabilities with password recovery, email verification, and improved profile management.

---

## Features to Implement

### 1. Password Recovery with Zero-Knowledge Phrases

**Description**: Allow users to recover accounts using pre-configured recovery phrases without storing them in plaintext.

**Requirements**:
- Users can set up recovery phrases during registration or in profile settings
- Recovery phrases are hashed using the same PBKDF2 as passwords
- Zero-knowledge proof: Server never sees plaintext phrases
- Password reset with phrase verification
- Rate limiting on recovery attempts

**API Endpoints**:
```
POST /api/auth/recovery/setup
Body: { "recovery_phrase": "string" }
Response: 200 OK

POST /api/auth/recovery/verify
Body: { "email": "string", "recovery_phrase": "string" }
Response: 200 OK { "verified": true }

POST /api/auth/recovery/reset-password
Body: { "email": "string", "recovery_phrase": "string", "new_password": "string" }
Response: 200 OK
```

**Implementation Notes**:
- Store `recovery_phrase_hash` in User model
- Use existing `PasswordService` for hashing
- Add rate limiting (5 attempts per hour)
- Log all recovery attempts

---

### 2. Email Verification Flow

**Description**: Verify user email addresses to improve security and enable email notifications.

**Requirements**:
- Send verification email on registration
- Generate secure verification tokens
- Token expiration: 24 hours
- Resend verification email functionality
- Block unverified users from certain actions

**API Endpoints**:
```
POST /api/auth/verify/send
Body: { "email": "string" }
Response: 200 OK { "message": "Verification email sent" }

GET /api/auth/verify/confirm?token=string
Response: 200 OK { "verified": true }

POST /api/auth/verify/resend
Body: { "email": "string" }
Response: 200 OK { "message": "Verification email resent" }
```

**Database Schema**:
``
ust
// Add to User model
pub struct EmailVerification {
    pub email_verified: bool,
    pub verification_token: String,
    pub verification_expires: DateTime<Utc>,
    pub verification_attempts: i32,
}
```

**Implementation Notes**:
- Use JWT for verification tokens (short-lived)
- Integrate with email service (placeholder for now)
- Store token in User document
- Add background job to clean expired tokens

---

### 3. Enhanced Profile Management

**Description**: Allow users to update their profiles with more information.

**API Endpoints**:
```
GET /api/users/me
Response: 200 OK { "user": {...} }

PUT /api/users/me
Body: { "username": "string", "full_name": "string", ... }
Response: 200 OK { "user": {...} }

DELETE /api/users/me
Response: 200 OK { "deleted": true }
```

**Implementation Notes**:
- Update existing `get_profile` handler
- Add `update_profile` handler
- Add `delete_account` handler
- Validate input data
- Add password confirmation for sensitive changes

---

### 4. Account Settings Management

**Description**: Manage user account preferences and security settings.

**API Endpoints**:
```
GET /api/users/me/settings
Response: 200 OK { "settings": {...} }

PUT /api/users/me/settings
Body: { "notifications": bool, "theme": "string", ... }
Response: 200 OK { "settings": {...} }

POST /api/users/me/change-password
Body: { "current_password": "string", "new_password": "string" }
Response: 200 OK { "updated": true }
```

**Database Schema**:
``
ust
pub struct UserSettings {
    pub email_notifications: bool,
    pub two_factor_enabled: bool,
    pub theme: String,
    pub language: String,
    pub timezone: String,
}
```

---

## Implementation Order

1. ✅ **Step 1**: Update User model with new fields
2. ✅ **Step 2**: Implement password recovery endpoints
3. ✅ **Step 3**: Implement email verification endpoints
4. ✅ **Step 4**: Implement enhanced profile management
5. ✅ **Step 5**: Implement account settings endpoints
6. ✅ **Step 6**: Add rate limiting for sensitive operations
7. ✅ **Step 7**: Write integration tests
8. ✅ **Step 8**: Update API documentation

---

## Progress Tracking

| Feature | Status | Notes |
|---------|--------|-------|
| Password Recovery | 🚧 Not Started | |
| Email Verification | 🚧 Not Started | |
| Enhanced Profile | 🚧 Not Started | |
| Account Settings | 🚧 Not Started | |
| Rate Limiting | 🚧 Not Started | |
| Integration Tests | 🚧 Not Started | |

---

## Dependencies

- ✅ MongoDB connection
- ✅ JWT authentication
- ✅ Password hashing (PBKDF2)
- ⏳ Email service (placeholder)
- ⏳ Rate limiting middleware

---

## Testing Strategy

1. Unit tests for each handler
2. Integration tests with test database
3. Rate limiting tests
4. Email verification flow tests
5. Password recovery flow tests

---

## Next Steps

1. Create new models for EmailVerification, UserSettings
2. Implement password recovery handlers
3. Implement email verification handlers
4. Update profile management handlers
5. Add rate limiting middleware
6. Write comprehensive tests

---

**Previous Phase**: [Phase 2.3 - JWT Authentication](./STATUS.md)  
**Next Phase**: [Phase 2.5 - Access Control](./STATUS.md)