FM / docs

/home/techb158/cosmic-risk.abdallabala.com/docs/

/home/techb158/cosmic-risk.abdallabala.com/docs

Name	Size	Mode	Actions
00-design-study.md	3678	0644	edit dl rm
01-uml-class-diagram.puml	11869	0644	edit dl rm
02-use-case-diagram.puml	3763	0644	edit dl rm
03-sequence-diagrams.puml	9732	0644	edit dl rm
04-database-entity-model.mmd	7051	0644	edit dl rm
05-database-schema.sql	13372	0644	edit dl rm
06-diagram-preview.html	5021	0644	edit dl rm
07-design-checklist.md	3256	0644	edit dl rm
08-step-2-storage-layer.md	5325	0644	edit dl rm
09-step-3-risk-crud-ui.md	3380	0644	edit dl rm
10-step-4-mitigation-workflow.md	3996	0644	edit dl rm
11-step-5-deployment-gate-workflow.md	2292	0644	edit dl rm
12-step-6-multi-pm-integration.md	3770	0644	edit dl rm
13-step-6-1-microsoft-planner-integration.md	2335	0644	edit dl rm
14-step-7-reporting-export.md	4158	0644	edit dl rm
15-step-7-1-oauth-live-connectors.md	4545	0644	edit dl rm
16-step-8-user-roles-access-control.md	3297	0644	edit dl rm
17-step-9-production-deployment-security.md	4228	0644	edit dl rm
18-step-10-final-academic-submission.md	3199	0644	edit dl rm
19-final-report-draft.md	6814	0644	edit dl rm
20-instructor-submission-checklist.md	3639	0644	edit dl rm
21-demo-script.md	3948	0644	edit dl rm
22-traceability-matrix.md	4847	0644	edit dl rm
23-testing-evidence.md	2961	0644	edit dl rm
24-evaluation-rubric-mapping.md	2910	0644	edit dl rm
25-final-deployment-runbook.md	3214	0644	edit dl rm
26-known-limitations-and-future-work.md	2632	0644	edit dl rm
27-final-qa-checklist.md	2893	0644	edit dl rm
28-demo-rehearsal-script.md	3618	0644	edit dl rm
29-submission-freeze-report.md	2769	0644	edit dl rm
30-final-known-issues.md	1876	0644	edit dl rm
31-saas-rebuild-implementation.md	2573	0644	edit dl rm
application-documentation.md	27515	0644	edit dl rm
conversation-log.md	18503	0644	edit dl rm
dashboard-spec.md	3691	0644	edit dl rm
database-guide.md	37826	0644	edit dl rm
development-summary.md	7070	0644	edit dl rm
github-architecture.svg	6288	0644	edit dl rm
integration-pull-push-plan.md	7384	0644	edit dl rm

Edit: /home/techb158/cosmic-risk.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.

cmd: