# User Roles, Permissions, and Access Control Architecture
## Kampong Speu Provincial Demographic Management System (KSP-DMS)

**Document Code:** KSP-DMS-DOC-ROLES-01  
**Security Model:** Dual-Axis Access Control (Role-Based RBAC + Geographic Boundary Scoping)  
**Version:** 1.0 (Draft Proposal)  

---

## 1. The Dual-Axis Security Concept

Access control in KSP-DMS is governed by two orthogonal security vectors:
1. **Functional Authority (What can you do?):** Determined by assigned user roles and permission sets.
2. **Geographic Jurisdiction (Where can you do it?):** Determined by assigned administrative scope (Province, District, Commune, or Village).

```
+-----------------------------------------------------------------------------------+
|                           GEOGRAPHIC SCOPE VECTOR                                 |
|                                                                                   |
|  [Province Scope]       --> Provincial Administrator, Data Protection Officer     |
|         |                                                                         |
|  [District Scope]       --> District Reviewer (e.g. Chbar Mon Municipality Only)  |
|         |                                                                         |
|  [Commune Scope]        --> Commune Reviewer (e.g. Sangkat Roka Thum Only)        |
|         |                                                                         |
|  [Village Scope]        --> Village Data Collector (e.g. Phum Prey Veng Only)     |
+-----------------------------------------------------------------------------------+
                                          X
+-----------------------------------------------------------------------------------+
|                        FUNCTIONAL PERMISSION VECTOR                               |
|                                                                                   |
|  CREATE_DRAFT | EDIT_DRAFT | SUBMIT_BATCH | VERIFY_COMMUNE | APPROVE_DISTRICT     |
|  VIEW_REPORT  | EXPORT_CSV | AUDIT_INSPECT | USER_MANAGE    | SYSTEM_CONFIG       |
+-----------------------------------------------------------------------------------+
```

---

## 2. Defined System Roles

### 2.1 Super Administrator (`super_admin`)
- **Scope:** System-wide (All provinces / technical infrastructure).
- **Abilities:** User provisioning, role assignment, configuration management, automated database backups, system logging inspection.
- **Restriction:** Does not alter live demographic records directly.

### 2.2 Provincial Administrator (`provincial_admin`)
- **Scope:** Province of Kampong Speu.
- **Abilities:** Final approval of annual demographic baselines, view all district/commune records, export high-level provincial reports, inspect GIS thematic layers.

### 2.3 District Reviewer (`district_reviewer`)
- **Scope:** Assigned District/Municipality only (e.g., Basedth District).
- **Abilities:** Audit and validate commune submissions, approve/reject demographic batches, view district statistics and demographic pyramids.
- **Restriction:** Zero access to data in other districts.

### 2.4 Commune Reviewer (`commune_reviewer`)
- **Scope:** Assigned Commune/Sangkat only (e.g., Commune Svay Chacheb).
- **Abilities:** Review village data collector drafts, verify supporting civil registration documents, approve batch submission upwards to District.
- **Restriction:** Confined strictly to subordinate villages within the assigned commune.

### 2.5 Village Data Collector (`village_collector`)
- **Scope:** Assigned Village only (e.g., Phum Trapeang Lean).
- **Abilities:** Create new household drafts, add person profiles, register birth/death/migration event notices, submit batches for commune review.
- **Restriction:** Cannot directly commit changes to the active demographic baseline.

### 2.6 Data Protection & Legal Officer (`legal_auditor`)
- **Scope:** Province of Kampong Speu.
- **Abilities:** Read-only access to audit logs, data quality issue logs, and compliance telemetry.
- **Restriction:** No write or approval permissions.

---

## 3. Detailed Permissions Matrix

| Permission Key | Super Admin | Prov Admin | Dist Reviewer | Comm Reviewer | Vill Collector | Legal Auditor |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| `household.create_draft` | - | - | - | - | **YES** | - |
| `household.edit_draft` | - | - | - | **YES** | **YES** | - |
| `household.view` | **YES** | **YES** | **YES** (Scope) | **YES** (Scope) | **YES** (Scope)| **YES** |
| `event.register` | - | - | - | - | **YES** | - |
| `submission.submit_commune`| - | - | - | - | **YES** | - |
| `submission.verify_commune`| - | - | - | **YES** | - | - |
| `submission.approve_district`| - | - | **YES** | - | - | - |
| `report.view_aggregate` | **YES** | **YES** | **YES** | **YES** | **YES** | **YES** |
| `gis.view_choropleth` | **YES** | **YES** | **YES** | **YES** | - | **YES** |
| `audit.view_logs` | **YES** | **YES** | - | - | - | **YES** |
| `system.manage_users` | **YES** | - | - | - | - | - |
| `system.run_backup` | **YES** | - | - | - | - | - |

---

## 4. Enforcement Implementation
1. **Laravel Middleware (`CheckGeographicScope`):** Intercepts requests and verifies that route parameters (`{village}`, `{commune}`, `{household}`) match the authenticated user's geographic hierarchy.
2. **Model Global Scopes (`GeographicScope`):** Automatically injects SQL constraints into every Eloquent query.
3. **URL Tampering Prevention:** If a Commune Reviewer from Chbar Mon attempts to access `/households/999` (belonging to Kong Pisei), the system returns an immediate `403 Forbidden` and records an intrusion alert in `audit_logs`.
