Deep-Dive: User Management & RBAC System¶

Area: #4 — User Management & RBAC (Full-Stack) Generated: 2026-02-25 | Last Updated: 2026-02-25 | Scan Level: Exhaustive | Workflow: document-project v1.2.0 Files Analyzed: 85+ (38 backend + 47+ frontend) Lines of Code Scanned: ~16,100+ (backend ~4,500 + frontend ~11,600+) Known Issues Found: 76 (11 Critical, 16 High, 26 Medium, 23 Low) Cross-references: Auth Deep-Dive (23 overlapping issues), API Reference (23 undocumented endpoints found) Security Assessment: RBAC Attack Scenarios — Full privilege escalation chain documented (zero-permission user → super_admin in 1 API call) Post-Scan Update: Backend refactored Feb 18-22 — middleware.ts now active (was dead code), new permissionMiddleware.ts added (third permission system), contextMiddleware now attaches permissions to req.user, auth.ts now loads userRoles

Table of Contents¶

1. Executive Summary
2. File Inventory
3. Database Schema
4. Backend Modules
5. Permission System Architecture
6. Frontend Architecture
7. API Endpoint Reference
8. Data Flow & User Journeys
9. Dependency Graph
10. Known Issues
11. Seed Data
12. Risks & Contributor Guidance

1. Executive Summary¶

The User Management & RBAC system provides administrative CRUD operations for users, roles, permissions, user settings (2FA), and an invite-only registration flow. It implements a hybrid role model: each user has one primary role (User.roleId → Role) plus zero or more extra roles via a many-to-many join table (user_roles). Permissions are route-string based (dot notation, e.g., user.create) and assigned to roles, not directly to users. A super_admin role bypasses all permission checks.

Key characteristics: - 5 backend modules (User, Role, Permission, InviteUser, UserSetting) + 8 middleware/shared dependency files — 85+ files total - 6 TypeORM entities (User, Role, Permission, UserRole, UserSetting, InviteUser) - Full soft-delete lifecycle: trash → restore → permanent delete (all entities) - Bulk operations: bulk delete, bulk restore, bulk permanent delete - Three parallel permission systems: middleware v1 (broken, 1 route), helper (primary, 30+ services), middleware v2 (new, 1 route) - Frontend: 57 files — 4 API hook files, 9 page components, 3 permission wrappers, sidebars, auth pages, settings, providers - 87 seeded permissions across 11 display groups - 76 issues found (11 Critical, 16 High, 26 Medium, 23 Low) — all attack vectors re-verified STILL VULNERABLE — all claims verified against actual code — expert panel found v2 middleware blocks super_admin (#76)

2. File Inventory¶

2.1 Backend — Entities (6 files, ~310 LOC)¶

2.2 Backend — Modules (21 files, ~2,200 LOC)¶

2.3 Backend — Supporting & Infrastructure Files (14 files, ~1,780 LOC)¶

2.4 Frontend — API Hooks (4 files, ~1,024 LOC)¶

2.5 Frontend — Components (12 files, ~5,905 LOC)¶

2.6 Frontend — Pages (5 files, ~132 LOC)¶

3. Database Schema¶

3.1 Entity Relationship Diagram¶

┌─────────────┐      1:N       ┌──────────┐      M:M      ┌──────────────┐
│    User      │───────────────▶│   Role   │◀─────────────▶│  Permission  │
│              │  (roleId FK)   │          │ (role_permission│              │
│ id           │                │ id       │  join table)   │ id           │
│ name         │                │ name     │                │ route        │
│ email        │   M:M          │ displayName               │ displayName  │
│ password     │◀──────────────▶│ isDeleted│                │ readonly     │
│ roleId (FK)  │ (user_roles    │ deletedAt│                │ isDeleted    │
│ avatar       │  join table)   └──────────┘                │ deletedAt    │
│ phone        │                                            └──────────────┘
│ address      │
│ status       │   1:1          ┌──────────────┐
│ provider     │───────────────▶│ UserSetting  │
│ inviteOnly   │                │ id           │
│ isDeleted    │                │ userId (FK)  │
│ deletedAt    │                │ isTwoFactorEnabled
│ stripeCustomerId              │ twoFactorProvider
│ lemonSqueezyCustomerId        │ twoFactorSecret
└─────────────┘                 │ tempTwoFactorSecret
                                │ backupCodes  │
                                │ language     │
                                │ deletedAt    │
                                └──────────────┘

┌───────────────────┐           ┌──────────────┐
│  UserRole         │           │  InviteUser  │
│  (entity: mostly  │           │ (user_invites│
│   orphaned)       │           │  table)      │
│ id                │           │ id           │
│ userId (FK→User)  │           │ email        │
│ roleId (FK→Role)  │           │ status       │
│ createdAt         │           │ deletedAt    │
│ deletedAt         │           └──────────────┘
└───────────────────┘

3.2 Join Tables¶

3.3 Indexes¶

User: 6 compound indexes for query optimization: - (status, deletedAt), (email, deletedAt), (roleId, deletedAt), (status, roleId, deletedAt), (provider, email), (inviteOnly, status) - Individual: status, provider

Role: Partial unique index IDX_ROLE_NAME_ACTIVE on name where deletedAt IS NULL

Permission: Index on route (also has unique: true constraint)

UserSetting: Index on userId, index on twoFactorSecret (unnecessary — secret shouldn't be indexed)

3.4 Enums¶

4. Backend Modules¶

4.1 User Module¶

Path: src/app/modules/v1/User/

Routes (registered at /api/v1/users):

Service exports: createUser, updateUser, deleteUser, getUserList, getProfile, updateProfile, getUserById, deleteUsersByIds, restoreUserFromTrash, deletePermanentUser, userAnalytics, saveLemonSqueezyCustomerId, bulkUserRestore

Key behaviors: - getUserList filters out super_admin users from results (line 187) - getUserList returns analytics (total, paid, active, pending) alongside paginated data - createUser checks for soft-deleted users with same email (but rejects them instead of restoring) - updateUser has duplicated userRoles validation logic (see Issue #14) - updateProfile handles avatar upload with local/cloud branching - deleteUser uses TypeORM softDelete (sets deletedAt) - deletePermanentUser uses repo.remove() (hard delete)

4.2 Role Module¶

Path: src/app/modules/v1/Role/

Routes (registered at /api/v1/roles):

Key behaviors: - getRoleList uses in-memory cache (node-cache) with 24-hour TTL, keyed by stringified query - createRole auto-restores soft-deleted roles with matching name (un-deletes) - createRole calls PermissionService.updateRolePermissions() to assign initial permissions - createRole has no permission check (commented out at line 150) - updateRole validates name uniqueness (excluding self) and displayName uniqueness - restoreFromTrash checks for name conflicts before restoring - upsertRole is used by seed only - Validation forbids reserved names: user, admin, super-admin, super_admin - All mutations call deleteCacheByPrefix("roles:") to invalidate cache

4.3 Permission Module¶

Path: src/app/modules/v1/Permission/

Routes (registered at /api/v1/permissions):

Key behaviors: - getPermissions groups by displayName and adds action suffix analysis - getAllPermissions returns flat paginated list (separate from grouped view) - createPermission auto-assigns new permission to super_admin role - createPermission auto-restores soft-deleted permissions with same route - updatePermissionRoute blocks modification of readonly permissions - deletePermissionById blocks deletion of readonly permissions - grantPermissionToRole has no permission check — any authenticated user can call it - Route ordering issue: GET /all must come before GET /:permissionId — currently correct - Route conflict: GET /user-permissions after GET /:permissionId — will never match (:permissionId captures "user-permissions")

4.4 InviteUser Module¶

Path: src/app/modules/v1/InviteUser/

Routes (registered at both /api/v1/invite-users AND /api/v1/user-invites):

Key behaviors: - createInviteUser emits EVENT_TYPES.INVITE_USER_CREATED event → sends invitation email - checkIviteUserExists is public (no auth) — validates invite link for registration page - Invite link format: {config.invite_user_link}?email={encodeURIComponent(email)} - createInviteUser does NOT check for soft-deleted invites (commented-out restore logic) - updateInviteStatus (called by auth during registration) marks invite as ACCEPTED - Duplicate route registration: both /invite-users and /user-invites → same handler

4.5 UserSetting Module¶

Path: src/app/modules/v1/UserSetting/

Routes (registered at /api/v1/user-settings):

Key behaviors: - Two 2FA providers: Email OTP and Google Authenticator (TOTP via speakeasy) - Google 2FA flow: start2FASetup → stores temp secret → returns QR code → verify2FAGoogleSetup promotes to permanent - Backup codes: 10 codes, 10-char alphanumeric with hyphen, SHA-512 hashed, concatenated as single string - verifyBackupCode does string .includes(hash) to check — vulnerable to substring collisions (see Issue #27) - Email 2FA setup: creates OTP in database, sends via email - getUserSetting and getSettingById have no permission checks — any authenticated user can list all settings

5. Permission System Architecture¶

5.1 Permission Format¶

Permissions use dot notation: {domain}.{action}

5.2 Permission Resolution Flow (Updated Feb 25)¶

Request
  │
  ├── middleware.ts pipeline (global):
  │     security → cookies → CORS → session → passport → body parsers → contextMiddleware
  │     (contextMiddleware: loads user + roles, inits permission cache, attaches Set to req.user)
  │
  ├── Route-level middleware:
  │     auth() → [contextMiddleware AGAIN on some routes — double execution]
  │            → permission("user.view") [NEW v2 middleware — on GET /users only so far]
  │            → Handler
  │
  └── Service method:
        checkPermissionAndThrow(path) → hasPermission(path) [helper version]
              │
              ├── Is super_admin? → return true
              ├── Check permissionCache (Set<string>) → return cached
              └── Cache miss → loadUserRoles() from DB → checkPermissionInRoles()

THREE SYSTEMS (should be consolidated to two — see ADR-2):
  [DELETE] middlewares/hasPermission.ts — route format, primary role only (1 route: GET /payments)
  [KEEP]   middlewares/permissionMiddleware.ts — dot format, req.user.permissions Set (route-level)
  [KEEP]   helper/hasPermission.ts — dot format, cache + DB (service-level conditional checks)

5.3 Super Admin Bypass¶

The super_admin role has three bypass mechanisms: 1. Helper level: hasPermission() checks isCurrentUserSuperAdmin() → returns true immediately 2. Service level: currentUserPermission() returns ALL permission routes for super_admin 3. Frontend: Super admin gets ['*'] which useCheckPermission would need to handle (but it doesn't — it uses every() with .includes(), which would fail on wildcard)

5.4 Permission Caching¶

• Role list cache: node-cache with key prefix roles:, 24-hour TTL
• Permission cache: permissionCache.ts (in-memory, per-request via AsyncLocalStorage)
• Cache invalidation: All Role mutations call deleteCacheByPrefix("roles:")
• Gap: Permission mutations do NOT invalidate the role cache, so role permission changes may be stale

6. Frontend Architecture¶

6.1 Permission Checking¶

useCheckPermission(requiredPermissions: string[]): boolean - Reads from Redux state.auth.user.permissions (flat string array) - Uses every() — ALL required permissions must be present - Returns true if requiredPermissions is empty/null - Does NOT handle wildcard * (super admin gets all routes as individual strings from backend)

PermissionWrapper component: - Props: permission (string or string[]), children, showLoader, showError, showMessage, redirectTo - For arrays: uses every() (all required) - Renders UnauthorizedError component on failure (if showError)

NavPermissionWrapper component: - Supports recursive sub-item checking for navigation menus - Modes: requireAll (every) vs default (some)

6.2 State Management¶

User permissions are stored in Redux state.auth.user.permissions — populated on login/profile fetch. The getProfile backend endpoint aggregates permissions from primary role + all extra roles into a flat deduplicated array.

6.3 Frontend Permission Strings Used¶

7. API Endpoint Reference¶

7.1 Frontend → Backend Endpoint Mapping Gaps¶

All 5 hooks will produce 404 errors when called.

7.2 Payload Key Inconsistencies¶

Users bulk delete uses userIds while all others use ids.

8. Data Flow & User Journeys¶

8.1 Admin Creates a User¶

Admin clicks "Add User" → user-form.jsx opens
  → Fills name, email, role, password (or inviteOnly checkbox)
  → Submits → users-page.jsx handleFormSubmit()
  → ⚠️ BUG: calls updateUser.mutate() even for create mode
  → Backend POST /users → user.service.createUser()
    → checkPermissionAndThrow("user.create")
    → Validate role exists
    → Check email uniqueness (including soft-deleted)
    → Hash password
    → Validate extra userRoles if user has "users.assign.roles" permission
    → Save user

8.2 Admin Creates a Role with Permissions¶

Admin clicks "Add Role" → role-form.jsx opens
  → Fills display name, role name
  → Selects permissions via grouped checkboxes
  → Submits { role, displayName, permissionIds }
  → Backend POST /roles → role.service.createRole()
    → ⚠️ No permission check (commented out)
    → Check name uniqueness, displayName uniqueness
    → Create role entity
    → Call PermissionService.updateRolePermissions() to assign permissions
    → Invalidate role cache

8.3 Invite-Only Registration Flow¶

Admin creates invite → POST /user-invites { email }
  → inviteUser.service.createInviteUser()
    → Check email not already registered as User
    → Check email not already invited (active)
    → Create InviteUser with PENDING status
    → Emit INVITE_USER_CREATED event → sends email with invite link

User clicks invite link → Frontend /register?email=xxx
  → Frontend calls POST /user-invites/check-invite { email }
    → Validates invite exists and is PENDING
  → User fills registration form
  → Auth registration flow completes
  → inviteUser.service.updateInviteStatus(email) → marks ACCEPTED

8.4 Soft-Delete Lifecycle¶

All entities follow the same pattern:

Active → softDelete() → sets deletedAt timestamp
  → "Trash" tab shows soft-deleted items
  → restore() → clears deletedAt (with conflict checks)
  → OR repo.remove() → permanent hard delete

9. Dependency Graph¶

9.1 Backend Module Dependencies¶

User Module
├── imports: Role entity, Permission entity, PermissionService
├── uses: hasPermission helper, checkPermissionAndThrow helper
├── uses: eventEmitter (for inviteOnly user creation)
├── depends on: QueryBuilder, getSortQuery, parseBoolean, normalizeImageSrc
└── used by: Auth module, Seed, Analytics

Role Module
├── imports: Permission entity, PermissionService
├── uses: checkPermissionAndThrow helper
├── uses: node-cache (addCache, deleteCache, deleteCacheByPrefix, getCache)
├── depends on: QueryBuilder, getSortQuery, parseBoolean
└── used by: User module (role validation), Seed (upsertRole)

Permission Module
├── imports: Role entity, User entity
├── uses: hasPermission helper, checkPermissionAndThrow helper
├── depends on: QueryBuilder, getSortQuery, parseBoolean
└── used by: Role module (updateRolePermissions), User module (currentUserPermission)

InviteUser Module
├── imports: User entity, InviteUser entity
├── uses: checkPermissionAndThrow helper
├── uses: eventEmitter (INVITE_USER_CREATED event)
├── depends on: inviteUserEmailTemplate
└── used by: Auth module (updateInviteStatus during registration)

UserSetting Module
├── imports: UserSetting entity, Otp entity, User entity
├── uses: speakeasy, qrcode, crypto
├── uses: AuthService.logininfoWithToken (for backup code login)
├── depends on: sendEmail helper, QueryBuilder
└── used by: Auth module (2FA verification during login)

9.2 Frontend Component Tree¶

/dashboard/users/page.js
└── UsersPage
    ├── useGetUsers (API)
    ├── useUpdateUser, useDeleteUser, usePermanentDeleteUser, etc.
    ├── useGetRoles (for role filter dropdown)
    ├── usePermissions (for permission filter dropdown)
    ├── PermissionWrapper (gates entire page + individual actions)
    └── UserForm (modal)
        ├── useGetRoles (for role selector)
        └── PermissionWrapper

/dashboard/roles-permissions/roles/page.js
└── RolesPage
    ├── useGetRoles (API)
    ├── useCreateRole, useUpdateRole, useDeleteRole, etc.
    ├── PermissionWrapper
    └── RoleForm (modal)
        ├── useGetPermissions (grouped, for checkbox grid)
        └── PermissionWrapper

/dashboard/roles-permissions/permissions/page.js
└── PermissionsPage
    ├── usePermissions (flat list API)
    ├── useCreatePermission, useUpdatePermission, etc.
    ├── PermissionWrapper (gates on "role.view" — wrong? should be "permission.view")
    └── PermissionForm (modal)

/dashboard/invited-users/page.js
└── InvitedUsersPage
    ├── useGetInvitedUsers (API)
    ├── useCreateInvitedUser, useDeleteInvitedUser, etc.
    ├── PermissionWrapper
    └── InviteForm (modal)

10. Known Issues¶

Note: The canonical issue registry is in Section 17 with all 74 issues. This section provides a quick severity summary.

Re-verification (Feb 25): All 6 critical attack vectors confirmed STILL VULNERABLE against the current codebase. The Feb 18-22 backend refactoring did not address any security issues. See Attack Scenarios for details.

11. Seed Data¶

11.1 Seeded Roles (3)¶

11.2 Seeded Permissions (87)¶

Notable gap: No invite.* permissions are seeded. The InviteUser module requires invite.view, invite.create, invite.update, invite.delete, invite.restore but these must be created manually.

11.3 Seed Execution Order¶

1. roleSeed()       → Insert admin, user, super_admin roles
2. permissionSeed() → Insert 87 permissions (skips if any exist)
3. seedSettings()   → Insert app settings
4. seedSuperAdmin() → Create super_admin user from env vars

Note: Seed does NOT auto-assign permissions to super_admin. The allPermissionAssignToAdmin() function exists in PermissionService but is never called during seeding. Super_admin bypasses checks anyway, but the /my-permissions endpoint would return empty for super_admin until permissions are explicitly assigned.

12. Risks & Contributor Guidance¶

12.1 Before Modifying These Files¶

• Permission string changes propagate to both backend services AND frontend PermissionWrapper/useCheckPermission calls. Search both codebases.
• Role cache (node-cache) is NOT invalidated by permission changes — only by role mutations. After modifying permissions, the cache may serve stale data for up to 24 hours.
• isDeleted vs deletedAt confusion exists across all entities. When adding soft-delete queries, use deletedAt (TypeORM's official mechanism), not isDeleted (legacy boolean that is never automatically set).
• UserRole entity should not be used — use the User.userRoles M2M relation instead.

12.2 Verification Steps¶

1. After any permission route change: verify the permission string matches in both backend checkPermissionAndThrow() calls and frontend PermissionWrapper/useCheckPermission arrays
2. After role CRUD changes: check that deleteCacheByPrefix("roles:") is called
3. After adding new backend routes: ensure they are registered in routes/v1/index.ts and check for parameter route conflicts (:id before named paths)
4. After modifying user creation: test both direct-create and invite-only flows
5. After 2FA changes: test the complete flow — enable → verify → login with 2FA → disable → backup code login

12.3 Suggested Tests¶

• Unit: hasPermission() with cache hit, cache miss, super_admin, no roles, multiple roles with overlapping permissions
• Unit: Backup code generation, encoding, verification (especially hash boundary testing)
• Integration: User CRUD lifecycle: create → update → soft-delete → restore → permanent-delete
• Integration: Role-permission grant flow: create role → assign permissions → verify user gains access
• Integration: Invite flow: create invite → check-invite → register → verify status changes to ACCEPTED
• E2E: Permission propagation: assign permission to role → user with that role can access the gated route

13. Backend Dependency Deep Analysis¶

13.1 Request Context (src/shared/requestContext.ts — 122 LOC)¶

Per-request state via Node.js AsyncLocalStorage. Stores the authenticated user, their role name (as string from JWT), roleId, userRoles (as Role[]), and the permission cache.

• getCurrentUser() — throws ContextNotFoundError / UserNotFoundError if missing
• isCurrentUserSuperAdmin() — compares user.role === 'super_admin' (hard-coded string literal)
• setPermissionCache() / getPermissionCache() — validates userId ownership before read/write

Issue: Role name is taken from the JWT, not from DB. If a user's role is changed in the database after their JWT was issued, the context has a stale role name until the token expires.

13.2 Permission Cache (src/shared/permissionCache.ts — 183 LOC)¶

Per-request cache (NOT global). Initialized by contextMiddleware with all permission route strings extracted from the user's roles.

• initializePermissionCache(user, roles) — extracts permission.route into a Set<string>
• hasPermissionInCache(permission) — raw string match against the Set (returns boolean | null)
• Cache stores raw dot-notation strings from the database (e.g., user.create)

Issue: The hasPermission helper has normalization commented out, so cache lookups work only when the caller uses the exact same format as stored in DB. Route-format queries like /users/create will always miss.

13.3 Permission Normalizer (src/shared/permissionNormalizer.ts — 215 LOC)¶

Designed to convert between route format (/users/create) and dot notation (users.create). Has 13 exports including normalizePermissionString, getPermissionVariants, convertDotToRoute, etc.

Status: Effectively dead infrastructure. The only consumer (src/helper/hasPermission.ts) has the normalization call commented out at lines 57-63. The ACTION_MAPPING constant (update→edit, view→read, etc.) is defined but never used by active code. The middleware has its own inline normalizePath function.

13.4 Context Middleware (src/app/middlewares/contextMiddleware.ts — 93 LOC)¶

Runs after auth(), loads full user with relations (role, userRoles, userRoles.permissions, role.permissions), wraps remaining request in AsyncLocalStorage.run(), and initializes permission cache.

UPDATE (Feb 22): Now also attaches permissions to req.user.permissions as a Set<string>. Previously permissions were only available via AsyncLocalStorage. This enables the new permissionMiddleware.ts (see 13.5b).

Architecture (corrected after expert review): The global registration in middleware.ts runs AFTER passport.session() but BEFORE per-route auth(). This is intentional dual-path design: - OAuth (Google) flow: passport.session() → deserializeUser sets req.user → global contextMiddleware runs with user → context available - JWT flow: passport.session() does nothing → global contextMiddleware short-circuits (req.user undefined) → per-route auth() decodes JWT → per-route contextMiddleware runs → context available

Remaining issues: - Role name set from JWT (req.user.role) not from DB-loaded fullUser.role.name — stale after role changes - Silently continues on DB errors — request proceeds without context, req.user.permissions never set → v2 middleware throws TypeError - For OAuth sessions only: runs twice (global + per-route if route also applies it). Not an issue for JWT flows.

13.5 middleware.ts — Now Active (Previously Dead Code)¶

UPDATE (Feb 18-19): middleware.ts was documented as dead code in both the Middleware DD and this deep-dive. It is now the primary middleware pipeline — app.ts calls registerMiddlewares(app) which registers all middleware in order: securityMiddleware (Helmet — re-enabled), cookieParser, request logger, compression, CORS, session, passport, body parsers, timing, contextMiddleware.

Key implications: - securityMiddleware (Helmet) is active again — invalidates Middleware DD finding - contextMiddleware runs globally as the last middleware in registerMiddlewares() — this is the first invocation. Many routes add it again per-route, causing double execution. - registerErrorHandlers() is exported but still NOT called — app.ts still registers error handlers inline - Webhook routes are now AFTER registerMiddlewares() which includes express.json() — potentially breaks Stripe webhook signature verification (Stripe needs raw body) - Dead imports in app.ts: cors, passport, cookieParser, session, config, httpLogger, contextMiddleware are all imported but unused (now handled by middleware.ts)

13.5b NEW: Permission Middleware v2 (src/app/middlewares/permissionMiddleware.ts — 39 LOC)¶

Created Feb 19. A third permission-checking system alongside the existing two.

Exports: - permission(permission: string) — checks req.user.permissions.has(permission) (Set) - hasAnyPermission(permissions: string[]) — checks if any permission matches

Currently used by: GET /users in user.routes.ts — permission("user.view")

How it differs from existing systems: - Uses req.user.permissions (Set attached by contextMiddleware) — no DB query, no AsyncLocalStorage - Uses dot notation (matches DB format) — correct, unlike middleware v1 - Route-level middleware (like v1) but name-based (like the helper)

Bugs: - hasAnyPermission error message references ${permission} (function object) instead of ${permissions} (array) — leaks function source code to users (#69) - CRITICAL (#76): No super_admin bypass. After yarn seed, the role_permission table has ZERO entries for super_admin (seed never calls allPermissionAssignToAdmin()). req.user.permissions is an empty Set → has() always returns false → 403 for super_admin on all v2-protected routes. Currently blocks GET /users for super_admin. - No null-safety: if contextMiddleware fails silently, req.user.permissions is undefined → has() throws TypeError

13.5c Triple hasPermission Implementations (CRITICAL — Updated)¶

Three separate permission-checking systems now exist:

Architectural direction: Middleware v2 is the intended replacement. It uses the correct format (dot notation), reads from the permission Set (already computed by contextMiddleware), and works at route level. The helper remains necessary for in-service conditional checks. Middleware v1 should be deleted (ADR-2 still applies).

13.5d Auth Middleware Changes (src/app/middlewares/auth.ts — 353 LOC)¶

UPDATE (Feb 22): The default auth() now uses createQueryBuilder instead of findOne to load the authenticated user. It joins userRoles as extraRole:

leftJoinAndSelect("user.userRoles", "extraRole")

Computes allRoleIds = [role.id, ...userRoles.map(r => r.id)] but never uses it (the permission cache code that would consume it is commented out at lines 333-340). The authGuard export (named export) now validates the DB user's role name matches the JWT role name.

Still present: - user.refreshToken !== refreshToken (line 277) — User entity has no refreshToken column - Debug message "You are not authorized!33" (line 63) - 153 lines of commented-out dead code (old auth implementations) - escapeRegexPath function defined but never called - secure: true hardcoded for cookies (should be process.env.NODE_ENV === 'production')

13.6 Query Builder (src/app/builder/QueryBuilder.ts — 222 LOC)¶

Generic paginated query builder used by all list endpoints. Supports search, filters, relations, sorting, soft-delete modes (trashOnly, includeDeleted). Redundantly adds deletedAt IS NULL when TypeORM already excludes soft-deleted entities by default.

13.7 Resolved: Routes Controller Removed¶

UPDATE (Feb 18): Commit d021804 removed routerList.routes.ts and routes.controller.ts. The /api/v1/routes endpoint that crashed due to missing routes.json no longer exists. This resolves the Middleware DD Critical issue about the routes endpoint crash.

14. Cross-Reference: Auth Deep-Dive Overlap¶

23 issues from the Auth Deep-Dive overlap with this area. Issues #51-64 were tagged "out-of-scope" in the auth doc and are owned by this deep-dive as their canonical home.

14.1 Issues Owned by This Deep-Dive (from Auth DD #51-64)¶

14.2 Issues Cross-Referenced from Auth DD (in-scope there)¶

15. API Documentation Gaps¶

Cross-referencing docs/architecture/api.md against actual routes revealed 23 undocumented endpoints:

15.1 /roles — 4 Undocumented Endpoints¶

15.2 /permissions — 12 Undocumented Endpoints (only 2 of 14 documented)¶

15.3 /invite-users — 7 Undocumented Endpoints (only 3 of 10 documented)¶

15.4 Database Documentation Discrepancies¶

16. Expanded Frontend Coverage¶

The deep scan found 57 frontend files (~13,100 LOC) related to RBAC, organized in 9 categories:

16.1 Additional Files Not in Original Scan¶

• components/custom/unauthorized-error.jsx (73 LOC) — Access denied page rendered by PermissionWrapper
• components/custom/roles-badge-group.jsx (67 LOC) — Role badge display with color coding
• components/custom/user-avatar-group.jsx (75 LOC) — Overlapping avatar display for role user lists
• store/slices/authSlice.js (47 LOC) — Redux state for user.permissions
• services/authService.js (54 LOC) — Raw API calls including getProfile
• api/auth/index.js (153 LOC) — React Query hooks for auth, loads user.permissions
• middleware.js (23 LOC) — Token-only route protection (no permission/role checks)
• components/providers/protected-route.jsx (28 LOC) — Client-side auth check
• components/providers/auth-initializer.jsx (20 LOC) — Redux auth initialization
• interceptors/axiosInstance.js (48 LOC) — Bearer token injection, 401/403 logout
• components/pages/auth/register.jsx (424 LOC) — Invite-only registration flow
• 3 sidebar variants + top-nav (permission-gated navigation)
• settings/profile/page.jsx (375 LOC) — Profile editing page
• api/settings/account-setting.js (123 LOC) — 2FA API hooks
• 4 2FA components (742 LOC total)
• 16+ additional consumer files using PermissionWrapper across blogs, packages, products, contacts, etc.

16.2 Additional Frontend Findings¶

• useGetUsers does NOT check permissions (unlike useGetRoles/usePermissions/useGetInvitedUsers which gate via enabled: hasPermission)
• permission-form.jsx update is broken — handleUpdatePermission is commented out (lines 110-119)
• roles-badge-group.jsx has duplicate demo ID — demoAssignedRoles array has id: 2 for both "Moderator" and "User"
• Register page (register.jsx) handles invite-only flow via websiteType == 2, checking invite via POST /user-invites/check-invite
• Dashboard layout (layout.js) has no permission checking — only uses useUser() for loading state

17. Complete Issue Registry (75 Total)¶

Critical (10) — includes privilege escalation chain (Attack Scenarios)¶

High (16) — Severity-adjusted after code verification + devil's advocate challenge¶

Medium (26) — Severity-adjusted after code verification + devil's advocate challenge¶

Low (23) — Severity-adjusted after code verification + devil's advocate challenge¶

Resolved Issues (confirmed fixed by recent commits)¶

18. Production Risk Assessment¶

Pre-mortem analysis identified 7 production failure scenarios. Full details in RBAC Attack Scenarios — Part 2.

Minimum Viable Production Readiness (6 fixes, ~30 min)¶

1. Strip role from updateProfile service + validation (Issues #5b — blocks escalation)
2. Uncomment checkPermissionAndThrow("role.create") (Issue #4 — blocks role creation)
3. Add checkPermissionAndThrow("permission.grant") to grantPermissionToRole (Issue #5 — blocks permission assignment)
4. Add user status check in contextMiddleware (blocks fired employee access)
5. Fix create-user mutation in users-page.jsx (Issue #1 — updateUser → createUser)
6. Seed invite.* permissions in seed/data/permission.ts (Issue #28 — unblocks invite system)

19. Architecture Decision Records¶

Five ADRs were produced to resolve the systemic architectural issues. Full migration plan in RBAC Attack Scenarios — Part 3.

ADR Summary¶

Migration Phases¶

Target Architecture¶

AFTER (updated for Feb 22 changes):
  Route-level: permissionMiddleware.ts (dot notation, req.user.permissions Set)
       ├── permission("user.view") — single permission check
       └── hasAnyPermission(["a","b"]) — any-of check (fix bug in error msg first)

  Service-level: helper/hasPermission.ts (dot notation, multi-role, cached)
       ├── checkPermissionAndThrow() — all services
       └── hasPermission() — conditional checks

  Both backed by: contextMiddleware → initializePermissionCache → req.user.permissions Set

  DELETE: middlewares/hasPermission.ts (v1, route format, broken)
  ONE format: dot notation
  ONE soft-delete: @DeleteDateColumn
  ONE user↔role table: user_roles (@ManyToMany JoinTable)

20. Root Cause Analysis¶

5 Whys analysis traced all 74 issues back to 5 systemic root causes. Full reasoning chains in RBAC Attack Scenarios — Part 4.

The 5 Root Causes¶

Prevention Table¶

21. Sprint Plan¶

Cross-functional war room triaged all 70 issues into 4 phases. Full sprint plan with verification checklists, acceptance tests, and sprint board at RBAC Sprint Plan.

4 issues auto-resolved by Sprint 1 deletions (UserRole entity, normalizer).

Generated by BMAD Document Project workflow v1.2.0 — Exhaustive deep-dive, 2026-02-25