# Scopes and Roles

This document defines the **scope taxonomy** and how scopes map to roles across StellaOps. It is intentionally cross-cutting and does not attempt to list every module-specific scope; module dossiers and gateway contracts are the source of truth for per-surface requirements.

## Terms

- **Scope:** an OAuth2/OIDC scope string granted to a client/user token and enforced by the gateway and services.
- **Role:** a human-friendly grouping of scopes, assigned per tenant (often via RBAC in Authority/Console).
- **ABAC claims:** optional attribute filters that constrain a token further (e.g., environment, namespace, project).

## Scope Naming Conventions

Scopes follow a predictable pattern:

- `<area>:<verb>`
- Verbs are small and consistent: `read`, `write`, `approve`, `simulate`, `audit`, `admin`.

Examples that appear across current contracts and module dossiers:

- Vulnerability Explorer: `vuln:view`, `vuln:investigate`, `vuln:operate`, `vuln:audit`
- Exception governance: `exception:read`, `exception:write`, `exception:approve`
- Policy: `policy:read`, `policy:simulate`
- VEX ingestion: `vex.read`, `vex.admin`

## Typical Role Shapes (Tenant-Local)

Exact role names vary per deployment, but the intent is stable:

- **Viewer:** read-only access to findings/evidence for a tenant.
- **Operator:** can triage findings and create workflow objects (comments, assignments, exports).
- **Approver:** can approve/reject workflow objects that change gating (exceptions, waivers) for a tenant.
- **Auditor:** can access audit exports, histories, and verification surfaces.
- **Admin:** tenant administration (RBAC, client credentials, quotas, configuration).

## Enforcement Model (Where Scopes Are Checked)

- **Authority** issues tokens and embeds scopes (and optional ABAC claims).
- **Gateway** (when present) performs consistent scope enforcement and tenant routing.
- **Services** validate tenant context and enforce scope checks at endpoint boundaries.
- **Service-to-service** calls may use short-lived, sender-constrained tokens (OpTok/DPoP/mTLS) in addition to scopes.

## References

- Tenancy model and isolation: `docs/security/tenancy-overview.md`
- Exceptions API entry point: `docs/api/exceptions.md`
- Policy + Exceptions gateway contract: `docs/api/gateway/policy-exceptions.md`