up

docs/policy/api.md

@@ -0,0 +1,50 @@
+# Policy API Reference (runtime endpoints)
+
+> **Imposed rule:** Policy API calls must include tenant context and operate on frozen inputs; mutating endpoints require Authority scopes and audit events.
+
+## Base
+`/api/v1/policies`
+
+## Endpoints
+- `GET /policies` – list policies (with filters: tenant, status, name, tags); paginated.
+- `GET /policies/{id}` – fetch metadata and versions.
+- `GET /policies/{id}/versions/{v}` – fetch IR, hash, status, shadow flag, attestation refs.
+- `POST /policies/{id}/simulate` – run simulate; body: `{ inputs: { sbom_digest, advisory_snapshot, vex_set, reachability_hash, signals_digest }, settings: { shadow: bool } }`. Returns `runId`, findings, explain summary; full explain via run endpoint.
+- `POST /policies/{id}/run` – full run with frozen cursors; same body as simulate plus `mode` (`full|incremental`).
+- `GET /policy-runs/{runId}` – returns findings, explain trace refs, hashes, shadow flag, status.
+- `POST /policies/{id}/submit` – attach lint/simulate/coverage artefacts; transitions to `submitted`.
+- `POST /policies/{id}/approve` – requires `policy:approve`; records approval note.
+- `POST /policies/{id}/publish` – requires `policy:publish`; body includes `reason`, `ticket`, `sign=true|false`; returns attestation ref.
+- `POST /policies/{id}/activate` – requires `policy:activate`; activates version.
+- `POST /policies/{id}/archive` – archive version; reason required.
+
+## Headers
+- `X-Stella-Tenant` (required)
+- `X-Stella-Shadow` (optional; simulate)
+- `If-None-Match` (IR cache)
+
+## Auth & scopes
+- Read: `policy:read`
+- Simulate: `policy:simulate`
+- Submit: `policy:author`
+- Approve: `policy:approve`
+- Publish/Promote: `policy:publish`/`policy:promote`
+- Activate/Run: `policy:operate`
+
+## Errors (Problem+JSON)
+- `policy_inputs_unfrozen` (409) – missing cursors.
+- `policy_ir_hash_mismatch` (409) – IR hash differs from attested value.
+- `policy_shadow_required` (412) – shadow gate not satisfied.
+- `policy_attestation_required` (412) – publish without attestation metadata.
+- Standard auth/tenant errors.
+
+## Pagination & determinism
+- `limit`/`cursor`; stable ordering by `policyId` then `version`.
+- All list endpoints return `ETag` and `Content-SHA256` headers.
+
+## Offline
+- API supports `file://` bundle handler when running in sealed mode; simulate/run accept `bundle` path instead of remote cursors.
+
+## Observability
+- Metrics: `policy_api_requests_total{endpoint,status}`, `policy_simulate_latency_seconds`, `policy_run_latency_seconds`.
+- Logs: include `policyId`, `version`, `runId`, `tenant`, `shadow`, `cursors` hashes.