feat(auth): implement user self-deactivation with email verification (!6) · Merge Requests · ThinhNC / upgrade-data-crawler-be

feat(auth): implement user self-deactivation with email verification

Summary of Changes

Implemented a secure, two-step User Account Self-Deactivation flow with email verification in compliance with the strict 5-layer architecture and audit safety standards.

Business & Security Invariants

Two-Step Verification Flow:
- POST /api/v1/auth/deactivate/request: Requires authenticated user session, validates current password via bcrypt, derives a time-limited (15-minute) signed JWT token bound to passwordHash (purpose: "deactivate-account"), and dispatches a verification email.
- POST /api/v1/auth/deactivate/confirm: Cryptographically verifies the token, marks user as inactive (isActive = false, deletedAt = NOW(), deletedBy = userId), revokes sessions, and clears client authentication cookies.
Zero Token Leakage:
- The deactivation token is handled strictly inside the service layer and sent via the email service. It is never returned in API responses or leaked across architectural layers.
Sole Admin Lockout Protection:
- Deactivation requests and confirmations are rejected with a validation error if the requesting user is the last remaining active Admin in the system, preventing accidental orphan administrative lockout.
Comprehensive Revocation via Atomic Transaction:
- Executes inside a database transaction:
  - Soft-deletes user record (isActive = false, deletedAt = NOW(), deletedBy = userId).
  - Deletes all active refresh tokens for the user.
  - Deactivates all associated API keys (isActive = false).
  - Deactivates all associated crawl schedules (isActive = false).
Strict Layering & Zero Hardcode Compliance:
- Only repository interacts with the database.
- Utilizes shared domain constants for roles and audit actions without hardcoded string literals.

## Summary of Changes

Implemented a secure, two-step **User Account Self-Deactivation** flow with email verification in compliance with the strict 5-layer architecture and audit safety standards.

### Business & Security Invariants

1. **Two-Step Verification Flow**:
   - `POST /api/v1/auth/deactivate/request`: Requires authenticated user session, validates current password via bcrypt, derives a time-limited (15-minute) signed JWT token bound to `passwordHash` (`purpose: "deactivate-account"`), and dispatches a verification email.
   - `POST /api/v1/auth/deactivate/confirm`: Cryptographically verifies the token, marks user as inactive (`isActive = false`, `deletedAt = NOW()`, `deletedBy = userId`), revokes sessions, and clears client authentication cookies.
2. **Zero Token Leakage**:
   - The deactivation token is handled strictly inside the service layer and sent via the email service. It is never returned in API responses or leaked across architectural layers.
3. **Sole Admin Lockout Protection**:
   - Deactivation requests and confirmations are rejected with a validation error if the requesting user is the last remaining active Admin in the system, preventing accidental orphan administrative lockout.
4. **Comprehensive Revocation via Atomic Transaction**:
   - Executes inside a database transaction:
     - Soft-deletes user record (`isActive = false`, `deletedAt = NOW()`, `deletedBy = userId`).
     - Deletes all active refresh tokens for the user.
     - Deactivates all associated API keys (`isActive = false`).
     - Deactivates all associated crawl schedules (`isActive = false`).
5. **Strict Layering & Zero Hardcode Compliance**:
   - Only repository interacts with the database.
   - Utilizes shared domain constants for roles and audit actions without hardcoded string literals.