# Policy Governance & Least Privilege

> **Audience:** Security Guild, Policy Guild, Authority Core, auditors.  
> **Scope:** Scopes, RBAC, approval controls, tenancy, auditing, and compliance requirements for Policy Engine v2.

---

## 1 · Governance Principles

1. **Least privilege by scope** – API clients receive only the `policy:*` scopes required for their role; `effective:write` reserved for service identity.
2. **Immutable history** – All policy changes, approvals, runs, and suppressions produce audit artefacts retrievable offline.
3. **Separation of duties** – Authors cannot approve their own submissions; approvers require distinct scope and should not have deployment rights.
4. **Deterministic verification** – Simulations, determinism checks, and incident replay bundles provide reproducible evidence for auditors.
5. **Tenant isolation** – Policies, runs, and findings scoped to tenants; cross-tenant access requires explicit admin scopes and is logged.
6. **Offline parity** – Air-gapped sites follow the same governance workflow with sealed-mode safeguards and signed bundles.

---

## 2 · Authority Scopes & Role Mapping

| Scope | Description | Recommended role |
|-------|-------------|------------------|
| `policy:read` | View policies, revisions, runs, findings. | Readers, auditors. |
| `policy:author` | Create/edit drafts, lint/compile, quick simulate. | `role/policy-author`. |
| `policy:review` | Comment, request changes, approve in-progress drafts. | `role/policy-reviewer`. |
| `policy:approve` | Final approval; archive decisions. | `role/policy-approver`. |
| `policy:operate` | Promote revisions, trigger runs, manage rollouts. | `role/policy-operator`, automation bots. |
| `policy:audit` | Access immutable history and evidence bundles. | `role/policy-auditor`, compliance teams. |
| `policy:simulate` | Execute simulations via API/CLI. | Authors, reviewers, CI. |
| `policy:run` | Trigger runs, inspect live status. | Operators, automation bots. |
| `policy:activate` | Promote approved version, schedule activation. | Runtime operators / release managers. |
| `findings:read` | View effective findings/explain. | Analysts, auditors, CLI. |
| `effective:write` | **Service only** – materialise findings. | Policy Engine service principal. |

> Map organisation roles to scopes via Authority issuer config (`authority.tenants[].roles`). Document assignments in tenant onboarding checklist.

> **Authority configuration tip:** the Policy Engine service client must include `properties.serviceIdentity: policy-engine` and a tenant hint in `authority.yaml`. Authority rejects `effective:write` tokens that lack this marker. See [Authority scopes](authority-scopes.md) for the full scope catalogue.

---

## 3 · Workflow Controls

- **Submit gate:** CLI/UI require fresh lint + simulation artefacts (<24 h). Submissions store reviewer list and diff attachments.
- **Review quorum:** Authority policy enforces minimum reviewers (e.g., 2) and optional separation between functional/security domains.
- **Approval guard:** Approvers must acknowledge simulation + determinism check completion. CLI enforces `--note` and `--attach` fields.
- **Activation guard:** Policy Engine refuses activation when latest full run status ≠ success or incremental backlog aged > SLA.
- **Rollback policy:** Rollbacks require incident reference and produce `policy.rollback` audit events.

---

## 4 · Tenancy & Data Access

- Policies stored per tenant; `tenant-global` used for shared baselines.
- API filters all requests by `X-Stella-Tenant` (default from token). Cross-tenant requests require `policy:tenant-admin`.
- Effective findings collections include `tenant` field and unique indexes preventing cross-tenant writes.
- CLI/Console display tenant context prominently; switching tenant triggers warnings when active policy differs.
- Offline bundles encode tenant metadata; import commands validate compatibility before applying.

---

## 5 · Audit & Evidence

- **Collections:** `policies`, `policy_reviews`, `policy_history`, `policy_runs`, `policy_run_events`, `effective_finding_*_history`.
- **Events:** `policy.submitted`, `policy.review.requested`, `policy.approved`, `policy.activated`, `policy.archived`, `policy.run.*`, `policy.incident.*`.
- **Explain traces:** Stored for critical findings (sampled); available via CLI/UI for auditors (requires `findings:read`).
- **Offline evidence:** `stella policy bundle export` produces DSSE-signed packages containing DSL, IR digest, simulations, approval notes, run summaries, trace metadata.
- **Retention:** Default 365 days for run history, extendable per compliance requirements; incident mode extends to 30 days minimum.

---

## 6 · Secrets & Configuration Hygiene

- Policy Engine configuration loaded from environment/secret stores; no secrets in repo.
- CLI profiles should store tokens encrypted (`stella profile set --secret`).
- UI/CLI logs redact tokens, reviewer emails, and attachments.
- Rotating tokens/keys: Authority exposes `policy scopes` in discovery docs; follow `/docs/security/authority-scopes.md` for rotation.
- Use `policy:operate` to disable self-service simulation temporarily during incident response if needed.

---

## 7 · Incident Response

- Trigger incident mode for determinism violations, backlog surges, or suspected policy abuse.
- Capture replay bundles and run `stella policy run replay` for affected runs.
- Coordinate with Observability dashboards (see `/docs/observability/policy.md`) to monitor queue depth, failures.
- After resolution, document remediation in Lifecycle guide (§8) and attach to approval history.

---

## 8 · Offline / Air-Gapped Governance

- Same scopes apply; tokens issued by local Authority.
- Approvers must use offline UI/CLI to sign submissions; attachments stored locally.
- Bundle import/export must be signed (DSSE + cosign). CLI warns if signatures missing.
- Sealed-mode banner reminds operators to refresh bundles when staleness thresholds exceeded.
- Offline audits rely on evidence bundles and local `policy_runs` snapshot.

---

## 9 · Compliance Checklist

- [ ] **Scope mapping reviewed:** Authority issuer config updated; RBAC matrix stored with change request.
- [ ] **Separation enforced:** Automated checks block self-approval; review quorum satisfied.
- [ ] **Activation guard documented:** Operators trained on run health checks before promoting.
- [ ] **Audit exports tested:** Evidence bundles verified (hash/signature) and stored per compliance policy.
- [ ] **Incident drills rehearsed:** Replay/rollback procedures executed and logged.
- [ ] **Offline parity confirmed:** Air-gapped site executes submit/approve flow with sealed-mode guidance.
- [ ] **Documentation cross-links:** References to lifecycle, runs, observability, CLI, and API docs validated.

---

*Last updated: 2025-10-26 (Sprint 20).*