# Identity, tenancy, and scopes

Authority issues short-lived tokens bound to tenants and scopes. Tenancy is
enforced at every service boundary.

Token model
- tenant: required for all tenant-scoped APIs.
- scopes: list of granted permissions.
- service_identity: required for privileged write scopes.
- auth_time: used for fresh auth enforcement.
- reason and ticket fields: required for sensitive operations.
- act claim: present for delegated service accounts.

Tenancy propagation
- Gateways attach the tenant claim to a header (X-StellaOps-Tenant or configured).
- Services reject missing or mismatched tenant headers.
- All audit events record tenant and scope for traceability.

Scope categories (examples)
- Ingestion: advisory:ingest, vex:ingest.
- Verification: aoc:verify (required with advisory:read or vex:read).
- Signals: signals:read, signals:write.
- Policy: policy:author, policy:approve, policy:publish, policy:promote.
- Findings: effective:write (Policy Engine only), findings:read.
- Observability: obs:read, timeline:read, timeline:write, evidence:read.
- Ops: airgap:status:read, airgap:import, airgap:seal.
- Automation: packs.read, packs.run, packs.approve.
- Notifications: notify.viewer, notify.operator, notify.admin.

Scope enforcement rules
- advisory:read and vex:read require aoc:verify.
- effective:write requires service_identity = policy-engine.
- graph:write requires service_identity = cartographer.
- Ingest scopes must not be combined with effective:write.

Scope matrix (examples)
| Module | Typical roles | Scopes |
| --- | --- | --- |
| Concelier | concelier-ingest | advisory:ingest, advisory:read, aoc:verify |
| Excititor | excititor-ingest | vex:ingest, vex:read, aoc:verify |
| Policy Engine | policy-engine | effective:write, findings:read |
| Scanner | scanner-operator | scanner:read, scanner:scan, scanner:export |
| Graph | cartographer-service | graph:write, graph:read |
| Notify | notify-operator | notify.viewer, notify.operator |
| Export Center | export-operator | export.viewer, export.operator |
| Airgap | airgap-operator | airgap:status:read, airgap:import |
| Observability | obs-investigator | obs:read, timeline:read, timeline:write, evidence:read |
| Task Runner | packs-runner | packs.read, packs.run |

Role bundles
- Roles group scopes for common workflows (scanner, policy, notify, export).
- Policy author role: policy:author, policy:read, policy:simulate.
- Policy approver role: policy:approve, policy:review, policy:read.
- Pack runner role: packs.read, packs.run.
- Observability incident commander role: obs:read, obs:incident, timeline:write.

Fresh auth and MFA
- Policy publish and promote require fresh auth (auth_time window).
- Exception approvals can require MFA when routing templates demand it.
- Sensitive scopes require reason and ticket metadata for audit.

Delegation and service accounts
- Delegated accounts mint limited tokens for automation.
- Authority enforces per-tenant quotas and allowedScopes lists.
- Delegated tokens include act and service account identifiers.

Offline notes
- Offline kits can include scoped tokens with short expirations.
- Rotate tokens and trust roots on a fixed schedule.
- Avoid long-lived admin scopes in sealed environments.

Related references
- docs/security/authority-scopes.md
- docs/architecture/console-admin-rbac.md
- docs/modules/authority/architecture.md