service-finder/docs/p0_rbac_permission_matrix_gap_analysis.md

P0 DISCOVERY — RBAC Permission Matrix Alignment

Date: 2026-06-25
Scope: Full Gap Analysis between Code-required vs Database-stored permissions
Methodology: RequirePermission() decorator extraction from endpoints → PostgreSQL system.permissions table query → Diff Analysis

---

1. Codebase Scan — Permissions REQUIRED by the API

Extracted from all backend/app/api/v1/endpoints/ files using RequirePermission("...") decorators.

#	Permission Code	Endpoint File	Line(s)
1	org:view	admin_organizations.py	176, 324
2	org:view	admin.py	763
3	org:edit	admin_organizations.py	517
4	org:manage-members	admin_organizations.py	630, 743, 830
5	system:manage	system_parameters.py	118
6	dual-control:request	security.py	28
7	dual-control:approve	security.py	82, 111
8	dual-control:view	security.py	142
9	permissions:view	admin_permissions.py	137, 271, 317
10	permissions:edit	admin_permissions.py	177, 355
11	fleet:view	admin_permissions.py	456
12	finance:view	finance_admin.py	24
13	finance:edit	finance_admin.py	41
14	services:manage	admin_services.py	31, 58, 92
15	services:manage	admin.py	309, 370
16	subscription:manage	admin_packages.py	115, 188, 269, 393
17	settings:view	admin.py	37, 68, 92, 134, 163
18	settings:edit	admin.py	79, 101, 153
19	user:manage	admin.py	179, 664
20	moderation:manage	admin.py	240
21	gamification:manage	admin.py	418
22	user:view	admin.py	502

Unique permission codes required by code: 20

org:view, org:edit, org:manage-members,
system:manage,
dual-control:request, dual-control:approve, dual-control:view,
permissions:view, permissions:edit,
fleet:view,
finance:view, finance:edit,
services:manage,
subscription:manage,
settings:view, settings:edit,
user:manage, user:view,
moderation:manage,
gamification:manage

---

2. Database Scan — Permissions CURRENTLY in system.permissions

Queried from system.permissions table (PostgreSQL).

ID	Code	Domain	Action	Description
1	fleet:view	fleet	view	View fleet/vehicle data
2	fleet:create	fleet	create	Create new fleet/vehicle entries
3	fleet:edit	fleet	edit	Edit existing fleet/vehicle data
4	fleet:delete	fleet	delete	Delete fleet/vehicle entries
5	fleet:approve	fleet	approve	Approve fleet/vehicle submissions
6	user:view	user	view	View user profiles and data
7	user:create	user	create	Create new user accounts
8	user:edit	user	edit	Edit user profiles and data
9	user:delete	user	delete	Delete user accounts
10	user:manage-roles	user	manage-roles	Manage user role assignments
11	finance:view	finance	view	View financial data and transactions
12	finance:edit	finance	edit	Edit financial records
13	finance:approve	finance	approve	Approve financial transactions
14	finance:refund	finance	refund	Process refunds
15	system:view	system	view	View system configuration
16	system:edit	system	edit	Edit system configuration
17	system:manage	system	manage	Full system management access
18	org:view	org	view	View organization data
19	org:edit	org	edit	Edit organization data
20	org:delete	org	delete	Delete organizations
21	org:manage-members	org	manage-members	Manage organization members
22	reports:view	reports	view	View reports
23	reports:export	reports	export	Export reports
24	reports:manage	reports	manage	Manage report configurations
25	audit:view	audit	view	View audit logs
26	audit:export	audit	export	Export audit logs
27	settings:view	settings	view	View system settings
28	settings:edit	settings	edit	Edit system settings
29	permissions:view	permissions	view	View permission settings and matrix
30	permissions:edit	permissions	edit	Edit permission settings and role-permission mappings

Unique permission codes in database: 30

---

3. GAP ANALYSIS

3A. ORPHANED CODES — In Code, MISSING from Database

These 8 permissions are the ROOT CAUSE of the 403 Forbidden errors for non-Superadmin users.
The API checks for them via RequirePermission() in deps.py:283, but system.permissions has no such records → rbac_service.get_role_permissions() returns empty → 403 Forbidden.

Permission Code	Endpoint File(s)	Routes Affected
dual-control:request	security.py:28	POST /security/dual-control/request
dual-control:approve	security.py:82,111	POST /security/dual-control/approve, POST /security/dual-control/reject
dual-control:view	security.py:142	GET /security/dual-control/pending
services:manage	admin_services.py:31,58,92; admin.py:309,370	CRUD /admin/services/*
subscription:manage	admin_packages.py:115,188,269,393	CRUD /admin/packages/*
user:manage	admin.py:179,664	POST /admin/users, PUT /admin/users/{id}
moderation:manage	admin.py:240	GET /admin/moderation
gamification:manage	admin.py:418	GET /admin/gamification

---

3B. UNUSED CODES — In Database, NEVER referenced in any Endpoint

These 18 permissions exist in the database but no RequirePermission("...") references them anywhere.

Permission Code	Domain	Notes
fleet:create	fleet	No endpoint checks this
fleet:edit	fleet	No endpoint checks this
fleet:delete	fleet	No endpoint checks this
fleet:approve	fleet	No endpoint checks this
user:create	user	No endpoint checks this
user:edit	user	No endpoint checks this
user:delete	user	No endpoint checks this
user:manage-roles	user	No endpoint checks this
finance:approve	finance	No endpoint checks this
finance:refund	finance	No endpoint checks this
system:view	system	No endpoint checks this
system:edit	system	No endpoint checks this
org:delete	org	No endpoint checks this
reports:view	reports	No endpoint checks this
reports:export	reports	No endpoint checks this
reports:manage	reports	No endpoint checks this
audit:view	audit	No endpoint checks this
audit:export	audit	No endpoint checks this

---

3C. Intersection — Permissions that EXIST in BOTH (Correct)

These 12 permissions are properly aligned — they exist in the code and the database.

Permission Code	In Code	In DB
org:view	3 endpoints	ID 18
org:edit	1 endpoint	ID 19
org:manage-members	3 endpoints	ID 21
system:manage	1 endpoint	ID 17
permissions:view	3 endpoints	ID 29
permissions:edit	2 endpoints	ID 30
fleet:view	1 endpoint	ID 1
finance:view	1 endpoint	ID 11
finance:edit	1 endpoint	ID 12
settings:view	4 endpoints	ID 27
settings:edit	3 endpoints	ID 28
user:view	1 endpoint	ID 6

---

4. ROOT CAUSE SUMMARY

The 403 Forbidden Problem

The ADMIN role receives 403 errors because 8 critical permission codes are missing from the database:

Domain	Missing Codes
Dual Control	dual-control:request, dual-control:approve, dual-control:view
Services	services:manage
Subscriptions	subscription:manage
User Management	user:manage
Moderation	moderation:manage
Gamification	gamification:manage

When a non-Superadmin user calls any endpoint protected by these permissions, RequirePermission() in deps.py:333 calls rbac_service.get_role_permissions() in rbac_service.py:263 which queries system.role_permissions joined with system.permissions. Since the code doesn't exist in system.permissions, no system.role_permissions record can reference it → the permission check fails → 403 Forbidden.

How the code resolves this (from deps.py:311-336):

# SUPERADMIN bypass — rank 100 bypasses all checks
if current_user.role == UserRole.SUPERADMIN:
    return current_user

# Non-Superadmin: query DB
user_permissions = await rbac_service.get_role_permissions(db, role_id)
if permission_code not in user_permissions:
    raise HTTPException(403, f"Missing permission: {permission_code}")

This is why SUPERADMIN works but ADMIN (or any other role) gets 403 on all 8 phantom permissions.

---

5. CRITICAL FINDINGS

Metric	Value
Total permissions required by code	20
Total permissions in database	30
Properly aligned (in both)	12 (60% of code requirements are satisfied)
ORPHANED (code-only, breaking 403s)	8 (40% of code requirements)
UNUSED (DB-only, no endpoint uses)	18 (60% of database entries)

The database is 60% polluted with unused permissions, while simultaneously missing 40% of the permissions the code actually needs.

---

6. RECOMMENDED NEXT STEPS (Not Implemented — report only)

1. INSERT the 8 orphaned permission codes into system.permissions:

   • dual-control:request, dual-control:approve, dual-control:view
   • services:manage, subscription:manage
   • user:manage, moderation:manage, gamification:manage

2. GRANT these permissions to the admin role in system.role_permissions.

3. (Optional) Cleanup: Review the 18 unused codes — keep those planned for future use, archive the rest.

---

Report generated by Service Finder Rendszer-Architect. No code or database changes were made — pure discovery audit.