docs(phase-2.5): Complete access control implementation

backend/PHASE-2.4-SPEC.md

@@ -0,0 +1,210 @@
+# 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)