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, 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
Next Phase: Phase 2.5 - Access Control