Feat rbac

[RUKAYAT-CODER]

🔐 Develop Authentication and Authorization System with RBAC

Module: Auth / Security
Type: Feature

---

📖 Overview

This PR implements a comprehensive authentication and authorization system with Role-Based Access Control (RBAC), JWT-based sessions, refresh token rotation, and fine-grained permission management.

The system is designed to be secure, scalable, and enterprise-ready, supporting advanced features such as account lockout, email verification, password recovery, two-factor authentication (2FA), hierarchical permissions, and performance-optimized permission checks.

---

🎯 Goals

• Provide secure user authentication with JWT access and refresh tokens
• Enforce authorization using RBAC and granular permissions
• Support enterprise-grade security features (2FA, lockout, verification)
• Enable flexible, condition-based permissions
• Ensure performance through caching and efficient token handling

---

👤 Core Entities

User

• UUID primary key
• Email/password-based authentication
• Role and department associations
• Account security controls (lockout, failed attempts, 2FA)
• Refresh token tracking
• Audit fields and soft deletes

Role

• UUID primary key
• Unique role names
• Many-to-many relationship with permissions
• Support for system roles (e.g., Super Admin)

Permission

• UUID primary key
• Resource-based permissions (assets, users, departments, etc.)
• Action enum: CREATE, READ, UPDATE, DELETE, MANAGE
• Optional JSON-based conditions for attribute-level access control

RefreshToken

• UUID primary key
• Hashed token storage
• Expiration and revocation tracking
• Rotation support
• IP-based audit metadata

---

🔗 RBAC & Permission Model

• Users inherit permissions through assigned roles
• Roles can have multiple permissions
• Permissions support:
  • Resource + action matching
  • Conditional logic (e.g. department-based access)
  • Hierarchical permissions (parent includes children)
• Permission checks enforced on every protected endpoint

---

🔑 Authentication Flow

• Email/password authentication using bcrypt (cost factor: 12)
• JWT access tokens (15-minute expiry)
• Refresh tokens (7-day expiry)
• Secure HTTP-only cookies for refresh tokens
• Token rotation on refresh
• Token revocation via Redis-backed blacklist
• CSRF protection enabled

---

🔐 Advanced Security Features

• Account lockout after 5 failed login attempts (30 minutes)
• Email verification on registration
• Password reset with expiring tokens (1 hour)
• Two-Factor Authentication (TOTP via speakeasy)
• Request signing support for API keys
• Rate limiting on auth endpoints (5 req/min for login)

---

🌐 API Endpoints

Authentication

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/logout
• POST /api/v1/auth/refresh
• POST /api/v1/auth/forgot-password
• POST /api/v1/auth/reset-password
• POST /api/v1/auth/verify-email
• POST /api/v1/auth/resend-verification
• POST /api/v1/auth/change-password
• POST /api/v1/auth/2fa/enable
• POST /api/v1/auth/2fa/verify
• POST /api/v1/auth/2fa/disable

Users

• GET /api/v1/users
• GET /api/v1/users/:id
• POST /api/v1/users
• PUT /api/v1/users/:id
• DELETE /api/v1/users/:id
• PATCH /api/v1/users/:id/activate
• GET /api/v1/users/me

Roles & Permissions

• GET /api/v1/roles
• POST /api/v1/roles
• PUT /api/v1/roles/:id
• DELETE /api/v1/roles/:id
• GET /api/v1/permissions
• POST /api/v1/roles/:id/permissions

---

🛠️ Technical Implementation

• Auth: Passport.js (JWT strategy)
• 2FA: speakeasy (TOTP)
• Caching: Redis (permissions, token blacklist)
• Security:
  • HTTP-only cookies
  • CSRF protection
  • Hashed refresh tokens
• Authorization:
  • Custom guards for auth & RBAC
  • @RequirePermission decorator
• Rate Limiting: Redis-backed middleware

---

🧪 Validation & Rules

• Email: valid format, unique, max 255 chars
• Password: min 8 chars, uppercase, lowercase, number, special char
• Names: 2–50 chars
• Phone: E.164 format
• 2FA codes: 6 digits
• All passwords hashed and never logged

---

👥 Predefined Roles

• Super Admin: Full access, cannot be deleted
• Admin: Manage users, roles, settings, assets
• Manager: Manage assets, approve transfers, view reports
• User: Create/edit own assets, request transfers
• Viewer: Read-only access

---

✅ Acceptance Criteria

• User registration with email verification
• Secure login with JWT issuance
• Refresh token rotation implemented
• Password reset flow works end-to-end
• Account lockout after failed attempts
• 2FA enable/verify/disable supported
• RBAC enforced on all protected routes
• Insufficient permissions return 403
• Tokens expire and refresh correctly
• All sensitive credentials securely hashed

---

🚀 Impact

This PR establishes a robust, enterprise-grade authentication and authorization foundation that supports current application needs while remaining flexible enough for future growth, compliance requirements, and security enhancements.

close #384

[vercel]

@RUKAYAT-CODER is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[RUKAYAT-CODER]

i just created a PR kindly review