/home/techb158/cosmic.abdallabala.com/docs
Edit: /home/techb158/cosmic.abdallabala.com/docs/16-step-8-user-roles-access-control.md (3297B)
# Step 8, User Roles and Access Control
## Purpose
Step 8 adds role-based access control to the COSMIC AI-Risk Dashboard before production hardening. This is required because the application now supports live third-party API clients, OAuth tokens, reviewer gate decisions, report exports, and governance audit events.
## Source alignment
The source framework separates organizational project management, AI solution management, risk and uncertainty management, and governance review. Access control is an implementation extension that protects these workflows in software.
## Roles added
| Role | Main permissions |
|---|---|
| System Admin | All permissions |
| Project Manager | Project read, risk write, mitigation write, gate evaluate, reports, integration sync, audit read |
| Risk Owner | Risk read/write and mitigation write |
| AI Engineer / Data Scientist | Project read, risk read, mitigation write, metrics write, reports |
| Governance Reviewer | Gate read, gate evaluate, gate review, reports, audit read |
| Legal / Ethics Reviewer | Gate review, risk read, mitigation write, reports, audit read |
| Integration Admin | Integration read/write/sync and OAuth management |
| Read-only Viewer | Project, risk, gate, integration, and report read access |
## Permission set
```text
project:read
risk:read
risk:write
risk:delete
mitigation:write
gate:read
gate:evaluate
gate:review
gate:approve
report:export
integration:read
integration:write
integration:sync
oauth:manage
user:read
user:write
audit:read
metrics:write
```
## API enforcement
The API reads the actor from this request header:
```http
X-Cosmic-User-Id: USER-GOV
```
If no actor is provided, the prototype defaults to `USER-SYSTEM` so existing tests and local demo scripts continue to run.
Examples:
| Action | Required permission |
|---|---|
| View dashboard | `project:read` |
| Create or edit risk | `risk:write` |
| Delete risk | `risk:delete` |
| Create or edit mitigation | `mitigation:write` |
| Evaluate deployment gate | `gate:evaluate` |
| Record reviewer decision | `gate:review` |
| Export reports | `report:export` |
| Configure OAuth | `oauth:manage` |
| Sync PM integration | `integration:sync` |
| Manage users and roles | `user:write` |
## New API endpoints
```text
GET /api/access/me
GET /api/access/permissions
POST /api/access/seed-defaults
GET /api/users
POST /api/users
GET /api/users/{userId}
PATCH /api/users/{userId}
GET /api/roles
POST /api/roles
GET /api/roles/{roleId}
PATCH /api/roles/{roleId}
```
## UI additions
A new **Access control** tab was added. It allows the instructor or evaluator to switch the active actor and verify that permissions affect available actions.
The UI now displays:
1. Current actor and role.
2. Current actor permissions.
3. User table.
4. Role and permission matrix.
5. Disabled action buttons when the actor lacks permission.
## Test coverage
The new test file is:
```text
tests/access-control.test.js
```
It verifies:
1. Default roles and users are seeded.
2. Viewer can read the dashboard.
3. Viewer cannot create risks.
4. Risk owner can create risks.
5. Risk owner cannot delete risks.
6. Admin can delete risks.
7. Integration admin can access OAuth provider configuration.
8. Viewer cannot access OAuth provider configuration.