# RBAC and Permission Matrix

> This matrix is derived from `database/seeders/RolePermissionSeeder.php` and API route middleware. UI visibility is helpful but API middleware is the authorization boundary. Verify every change with an account holding the intended role.

## 1. Standard roles seeded by the application

| Role | Intended operating scope | Seeded access summary |
| --- | --- | --- |
| `admin` | System administrator | All seeded permissions. |
| `writer` | Prepare proposal content/templates | Proposal read/upload/accept/reject; template read/create/edit/delete; own profile. |
| `sales_person` | Manage bid, prospect and Fiverr lead/order flow | Proposals, prospects, core Fiverr order lifecycle, own profile. |
| `prospect_lead` | Own client/prospect conversion work | Prospect read/client/reject/interview/follow-up/reactivate; own profile. |

The application supports custom roles through role management. Do not assume a custom role inherits any permission unless it is explicitly assigned.

## 2. Permission families

| Family | Typical permissions | Main responsibility |
| --- | --- | --- |
| Profile | `profile.update`, `profile.change_password` | User manages own identity/password. |
| Users and roles | `users.*`, `roles.manage` | Administer access. |
| Upwork setup | `categories.*`, `sub_categories.*`, `templates.*`, `upwork_accounts.*` | Configure bid domain data. |
| Upwork jobs/proposals | `proposals.*` plus current route aliases for jobs | Collect, write, submit and track bids. |
| Prospects/projects | `prospects.*`, `projects.*` | Client conversion and project handoff. |
| Reports | `reports.*`, `fiverr_reports.*` | Read/export operational metrics. |
| Fiverr operations | `fiverr_orders.*`, `fiverr_accounts.*`, `fiverr_gigs.*` | Lead-to-order lifecycle. |
| Finance/forecast | `payment_accounts.*`, `payment_methods.*`, `fiverr_forecast.*` | Payment references and targets. |
| Configuration | `shifts.*`, `gemini_config.*`, `pusher_config.*`, `*_settings.*`, `upwork_alerts.*` | Operational and integration settings. |
| Audit | `activity_logs.view` | Inspect recorded activity. |

## 3. Recommended role boundaries

| Capability | Admin | Writer | Sales person | Prospect lead | Recommended control |
| --- | --- | --- | --- | --- | --- |
| Create/disable users and edit roles | Yes | No | No | No | Two-person review for Admin-role grants. |
| View/change Gemini or Pusher credentials | Yes, only trusted technical admins | No | No | No | Separate secrets access from daily operations. |
| Create/update categories, accounts, payment methods | Yes | Limited template work only | No by default | No | Require a setup/finance owner. |
| Create and edit proposals | Yes | Content/template contribution | Yes | No | Ensure assignment/ownership checks where required. |
| Submit proposal | Yes | No by default | Yes | No | Submission permission should be explicit. |
| View/update prospects | Yes | No | Yes | Yes | Restrict reassignment and final status if needed. |
| Perform Fiverr lead/order actions | Yes | No | Yes | No by default | Separate lead collection, offer acceptance and delivery completion when team size permits. |
| View payment accounts/methods | Yes | No | No by default | No | Finance-only or tightly scoped Admin access. |
| Manage forecast targets | Yes | No | Optional team lead scope | No | Separate data entry, verification and overall target management. |
| View/export reports | Yes | No by default | Scoped operational report | Scoped prospect report | Exports must follow data-sharing policy. |
| View activity logs | Yes | No | No | No | Audit access should be limited. |

## 4. High-risk permissions

| Permission/family | Risk | Required safeguard |
| --- | --- | --- |
| `roles.manage` | Can create/escalate access. | Limit to very few admins; review activity logs. |
| `users.create`, `users.edit`, `users.delete`, `users.restore` | Can create accounts or alter operating access. | Approval workflow and periodic review. |
| `gemini_config.edit`, `pusher_config.edit` | Can view/change integration credentials or destinations. | Technical-admin only; secret rotation procedure. |
| `payment_accounts.*`, `payment_methods.*` | Exposes or changes financial references. | Finance owner; least privilege; audit review. |
| `proposals.submit` | Commits agency bid activity/spend. | Assign to accountable bid role. |
| `projects.permanent`, `projects.discontinue` | Changes downstream business lifecycle. | Team-lead/admin approval. |
| `fiverr_orders.accept_offer`, `assign_team`, `mark_delivered`, `mark_completed` | Moves a client commitment through delivery lifecycle. | Separation of duties where possible; evidence required. |
| `fiverr_forecast.manage_overall`, `verify`, `seed-defaults` | Alters forecast planning/baseline. | Approval/review and activity log. |
| `reports.export`, `fiverr_reports.export` | Can distribute confidential operational data. | Export handling and retention controls. |

## 5. Access review procedure

1. Export or review all users, their assigned roles, platform, shift and categories.
2. Compare each user’s current work responsibility with this matrix.
3. Remove unneeded roles first; then remove unneeded individual permissions.
4. Verify that disabled/offboarded users have no active Sanctum tokens and no access to module routes.
5. Review every admin, finance, integration-config and export permission with the system owner.
6. Record reviewer, date, decisions and exceptions in the activity/audit process.

## 6. Implementation notes

- The seeded permission list uses `proposals.*` for much of the job workflow, while API routes also check aliases such as `jobs.view`, `jobs.create`, `jobs.edit`, `jobs.import`, `jobs.sync`, and `jobs.retry_scrape`. Standardize and seed these names or use one permission vocabulary; otherwise intended users can see UI capabilities yet receive 403 at the API.
- Upwork and Fiverr module route groups should apply `active.user` in addition to `auth:sanctum` so disabled accounts cannot use token-only endpoints.
- Every new endpoint must be added to this matrix, route middleware, API reference, and authorization test suite in the same pull request.