# Permissions & Access Control

The platform currently uses a **Role-Based Access Control (RBAC)** system. Each user is assigned a single role which determines their access level.

## Roles

| Role | Target Portal | Description |
|---|---|---|
| `admin` | Admin Panel | Full system control, approvals, and platform configuration. |
| `company_owner` | Company Portal | Primary contact for a service provider. Can manage everything for their company. |
| `company_staff` | Company Portal | Team members. Can view requests and create quotations. |
| `site_engineer` | Company Portal | Technical staff. Will be responsible for reporting execution progress. |
| `customer` | Mobile App / API | The end-user requesting services and signing contracts. |

## Authentication
`POST /api/v1/auth/login` grants a JWT only when `password_verify()` succeeds against `users.password_hash`. There is no alternate demo or master password path; enforce strong passwords and migrations that seed bcrypt hashes.

## Access Matrix

| Feature | Admin | Company Owner | Company Staff | Site Engineer | Customer |
|---|---|---|---|---|---|
| Approve Companies | ✅ | ❌ | ❌ | ❌ | ❌ |
| Manage Catalog | ❌ | ✅ | ✅ | ❌ | ❌ |
| View Requests | ❌ | ✅ | ✅ | ✅ | ✅ (Own) |
| Create Quotations | ❌ | ✅ | ✅ | ❌ | ❌ |
| **Manage Contracts** | ❌ | ✅ | ❌ | ❌ | ✅ (Sign) |
| **Sign Contract (UAE PASS)**| ❌ | ✅ | ❌ | ❌ | ✅ |
| Report Progress | ❌ | ✅ | ❌ | ✅ | ❌ |
| Global Settings | ✅ | ❌ | ❌ | ❌ | ❌ |

## Backend Enforcement
Enforced in `middlewares/AuthMiddleware.php` via `requireRole($user, 'role_name')`.
The `admin` role has "God Mode" and passes all role checks.

```php
// Example: Restricting to company users
$user = AuthMiddleware::protect();
AuthMiddleware::requireRole($user, 'company_owner'); // or 'company_staff'
```

## Future Granular Permissions
The database includes `permissions` and `role_permissions` tables to eventually support fine-grained access (e.g., `can_edit_catalog`, `can_sign_contracts`). For now, logic is simplified to the roles listed above.