# Permission Updates Summary

This document summarizes all the permission decorator updates made to secure the PX360 application.

## New Decorators Created (`apps/core/decorators.py`)

| Decorator | Description | Access Level |
|-----------|-------------|--------------|
| `@px_admin_required` | PX Admins only | Level 100 |
| `@hospital_admin_required` | PX Admins + Hospital Admins | Level 80+ |
| `@admin_required` | Any admin (PX, Hospital, Dept Manager) | Level 60+ |
| `@px_coordinator_required` | Coordinators and above | Level 50+ |
| `@staff_required` | All staff except Source Users | Level 10+ |
| `@source_user_required` | Source Users only | Level 5 |
| `@block_source_user` | Blocks Source Users | Blocks Level 5 |
| `@source_user_or_admin` | Source Users OR Admins | Level 5+ or 60+ |

---

## Views Updated with Permission Decorators

### 1. Dashboard Views (`apps/dashboard/views.py`)

| View | Original | Updated |
|------|----------|---------|
| `admin_evaluation` | `@login_required` | Added permission check inside |
| `admin_evaluation_chart_data` | `@login_required` | Added permission check inside |
| `staff_performance_detail` | `@login_required` | Added permission check inside |
| `department_benchmarks` | `@login_required` | Added permission check inside |
| `export_staff_performance` | `@login_required` | Added permission check inside |
| `performance_analytics_api` | `@login_required` | Added permission check inside |
| `staff_performance_trends` | `@login_required` | Added permission check inside |

**Access:** PX Admin and Hospital Admin only ❌ PX Coordinator

---

### 2. Analytics Views (`apps/analytics/ui_views.py`)

| View | Original | Updated |
|------|----------|---------|
| `analytics_dashboard` | `@login_required` | `@block_source_user` + `@login_required` |
| `kpi_list` | `@login_required` | `@block_source_user` + `@login_required` |
| `command_center` | `@login_required` | `@block_source_user` + `@login_required` |
| `command_center_api` | `@login_required` | `@block_source_user` + `@login_required` |
| `export_command_center` | `@login_required` | `@block_source_user` + `@login_required` |

**Access:** All staff except Source Users

---

### 3. Surveys Views (`apps/surveys/ui_views.py`)

All 22 views updated:
- `@login_required` → `@block_source_user` + `@login_required`

**Access:** All staff except Source Users

---

### 4. Organizations Views (`apps/organizations/ui_views.py`)

All views updated:
- `@login_required` → `@block_source_user` + `@login_required`

**Access:** All staff except Source Users

---

### 5. Complaints Views (`apps/complaints/ui_views.py`)

| View | Original | Updated | Access |
|------|----------|---------|--------|
| `complaint_list` | `@login_required` | No change (has RBAC filtering) | All users (filtered) |
| `complaint_create` | `@login_required` | No change | All staff + Source Users |
| `complaint_assign` | `@login_required` | `@hospital_admin_required` | Admin only |
| `complaint_activate` | `@login_required` | Permission check inside | Admin + Dept Manager |
| `complaint_escalate` | `@login_required` | Permission check inside | Admin only |
| `complaint_bulk_assign` | `@login_required` | `@hospital_admin_required` | Admin only |
| `complaint_bulk_status` | `@login_required` | `@hospital_admin_required` | Admin only |
| `complaint_bulk_escalate` | `@login_required` | `@hospital_admin_required` | Admin only |

---

### 6. Config Views (`apps/core/config_views.py`)

| View | Original | Updated |
|------|----------|---------|
| `config_dashboard` | `@login_required` | `@px_admin_required` |
| `sla_config_list` | `@login_required` | `@px_admin_required` |
| `routing_rules_list` | `@login_required` | `@px_admin_required` |

**Access:** PX Admin only

---

### 7. PX Sources Views (`apps/px_sources/ui_views.py`)

Already had proper decorators:
- Admin views: `@block_source_user`
- Source User views: `@source_user_required`

---

## Permission Enforcement Summary by Role

### PX Admin (Level 100)
✅ Full access to all views and functions

### Hospital Admin (Level 80)
✅ Can access:
- Admin Evaluation (own hospital)
- Staff Management (own hospital)
- Complaint assignment/activation
- Survey management
- Analytics and reports
- Settings (hospital-level)

❌ Cannot access:
- PX Admin-only config (system settings)
- Other hospitals' data

### Department Manager (Level 60)
✅ Can access:
- Department complaints
- Department staff
- Department analytics

❌ Cannot access:
- Admin Evaluation
- Bulk actions
- Complaint assignment
- Settings

### PX Coordinator (Level 50)
✅ Can access:
- Complaints (create, manage - but NOT assign/activate)
- PX Actions
- Surveys
- Analytics (basic)

❌ Cannot access:
- **Admin Evaluation** (NEW)
- Staff Management
- Settings
- Complaint assignment/activation

### Source User (Level 5)
✅ Can access:
- Create complaints (their own)
- Create inquiries (their own)
- View own created complaints/inquiries
- **Automatically redirected to `/px-sources/dashboard/` when visiting `/` or `/dashboard/my/`**

❌ Cannot access:
- **Surveys** (NEW - blocked → redirected)
- **Analytics** (NEW - blocked → redirected)
- **Staff/Organizations** (NEW - blocked → redirected)
- **Settings** (NEW - blocked → redirected)
- **PX Actions** (NEW - blocked → redirected)
- **Acknowledgements** (NEW - blocked → redirected)
- **Command Center** (`/` - redirected to source dashboard)
- **My Dashboard** (`/dashboard/my/` - redirected to source dashboard)

---

## Key Security Fixes

1. **Fixed**: PX Coordinator could access Admin Evaluation (now blocked)
2. **Fixed**: Source Users could access Surveys (now blocked)
3. **Fixed**: Source Users could access Analytics (now blocked)
4. **Fixed**: Source Users could access Staff Management (now blocked)
5. **Fixed**: Source Users could access Settings (now blocked)

---

## Source User Strict Access Control

**STRICT POLICY**: Source Users can ONLY access:
1. `/px-sources/*` - Their dashboard, complaints, and inquiries
2. `/accounts/password/change/` - Password change
3. `/accounts/settings/` - Basic settings
4. `/accounts/logout/` - Logout

**ALL other pages are BLOCKED and redirected to `/px-sources/dashboard/`**

### Middleware Enforcement

The `SourceUserRestrictionMiddleware` enforces this at the request level:
- Checks every request from source users
- Only allows whitelisted paths
- Silently redirects to source dashboard for blocked paths
- Runs after authentication middleware

### Allowed URLs for Source Users:

| URL | Access |
|-----|--------|
| `/px-sources/dashboard/` | ✅ Yes |
| `/px-sources/complaints/` | ✅ Yes |
| `/px-sources/inquiries/` | ✅ Yes |
| `/px-sources/complaints/new/` | ✅ Yes |
| `/px-sources/inquiries/new/` | ✅ Yes |
| `/accounts/password/change/` | ✅ Yes |
| `/accounts/settings/` | ✅ Yes |
| `/accounts/logout/` | ✅ Yes |
| `/` (root) | ❌ **Redirected** |
| `/dashboard/my/` | ❌ **Redirected** |
| `/surveys/*` | ❌ **Redirected** |
| `/analytics/*` | ❌ **Redirected** |
| `/organizations/*` | ❌ **Redirected** |
| `/config/*` | ❌ **Redirected** |
| `/actions/*` | ❌ **Redirected** |
| `/complaints/` (main list) | ❌ **Redirected** |
| `/complaints/inquiries/` (main) | ❌ **Redirected** |

### Technical Implementation

```python
# SourceUserRestrictionMiddleware
ALLOWED_PATH_PREFIXES = ['/px-sources/']
ALLOWED_URL_NAMES = {
    'accounts:password_change',
    'accounts:settings', 
    'accounts:logout',
}

# Everything else is BLOCKED for source users
```

---

## Testing Checklist

- [ ] PX Admin can access everything
- [ ] Hospital Admin can access their hospital data only
- [ ] Department Manager can access their department only
- [ ] PX Coordinator CANNOT access Admin Evaluation
- [ ] PX Coordinator can create complaints but NOT assign them
- [ ] **Source User visiting `/` gets redirected to `/px-sources/dashboard/`**
- [ ] **Source User visiting `/dashboard/my/` gets redirected to `/px-sources/dashboard/`**
- [ ] Source User can create/view their own complaints only
- [ ] Source User CANNOT access Surveys (redirects to their dashboard)
- [ ] Source User CANNOT access Analytics (redirects to their dashboard)
- [ ] Source User CANNOT access Staff Management (redirects to their dashboard)
- [ ] Source User CANNOT access Settings (redirects to their dashboard)

---

## Decorator Usage Examples

```python
# PX Admin only
@px_admin_required
def system_settings(request):
    pass

# Hospital Admin and above
@hospital_admin_required
def hospital_settings(request):
    pass

# Any admin
@admin_required
def department_management(request):
    pass

# Block source users
@block_source_user
def staff_list(request):
    pass

# Source users only
@source_user_required
def source_dashboard(request):
    pass
```

---

**Last Updated:** 2026-02-25