feat(admin-rbac): implement user management, audit remediation, distributed... (!33) · Merge Requests · ThinhNC / finwise-miniapp-be

feat(admin-rbac): implement user management, audit remediation, distributed...

Overview

This PR implements comprehensive administrative user management APIs, remediates security and reliability findings from the code audit, hardens the distributed lock mechanism, and expands the RBAC test coverage.

Key Changes

Admin User Management Module:
- Added GET /api/v1/users with pagination, search, role filtering, and status filtering.
- Added GET /api/v1/users/:id for detailed profile inspection.
- Added PATCH /api/v1/users/:id/status (activate/deactivate user accounts).
- Added PATCH /api/v1/users/:id/role for assigning system and custom roles with permission boundary enforcement.
Dynamic RBAC & Permission Matrix:
- Centralized all permission constants (permission.constant.ts) and system role definitions (system-role.constant.ts).
- Added granular permission guards (users:read, users:update, users:assign_role, roles:read, roles:write).
- Seed script updated to initialize baseline permissions, default system roles, and administrator accounts.
Security & Reliability Hardening (Audit Remediation):
- Distributed Lock Service: Implemented UUID fencing tokens, safe release script, TTL validation, and exponential backoff retry.
- Query Safety: Parameterized date bounds in anomaly detection and cash flow forecasting repositories to eliminate injection/overflow risks.
- Input Validation: Enforced strict Zod schemas for all user management, authentication, and RBAC endpoints.
- Worker Lifecycle: Graceful shutdown and signal handling for notification and scheduled workers.
Testing & Quality Assurance:
- Added 300+ lines of comprehensive RBAC unit and integration tests covering role assignment, permission caching/invalidation, and edge cases.

### Overview
This PR implements comprehensive administrative user management APIs, remediates security and reliability findings from the code audit, hardens the distributed lock mechanism, and expands the RBAC test coverage.

---

### Key Changes
- **Admin User Management Module:**
  - Added `GET /api/v1/users` with pagination, search, role filtering, and status filtering.
  - Added `GET /api/v1/users/:id` for detailed profile inspection.
  - Added `PATCH /api/v1/users/:id/status` (activate/deactivate user accounts).
  - Added `PATCH /api/v1/users/:id/role` for assigning system and custom roles with permission boundary enforcement.
- **Dynamic RBAC & Permission Matrix:**
  - Centralized all permission constants (`permission.constant.ts`) and system role definitions (`system-role.constant.ts`).
  - Added granular permission guards (`users:read`, `users:update`, `users:assign_role`, `roles:read`, `roles:write`).
  - Seed script updated to initialize baseline permissions, default system roles, and administrator accounts.
- **Security & Reliability Hardening (Audit Remediation):**
  - **Distributed Lock Service:** Implemented UUID fencing tokens, safe release script, TTL validation, and exponential backoff retry.
  - **Query Safety:** Parameterized date bounds in anomaly detection and cash flow forecasting repositories to eliminate injection/overflow risks.
  - **Input Validation:** Enforced strict Zod schemas for all user management, authentication, and RBAC endpoints.
  - **Worker Lifecycle:** Graceful shutdown and signal handling for notification and scheduled workers.
- **Testing & Quality Assurance:**
  - Added 300+ lines of comprehensive RBAC unit and integration tests covering role assignment, permission caching/invalidation, and edge cases.