# Policy Signing & Attestation (DevOps)

## Purpose
- Keep policy artefacts (DSL files, bundles) signed with a short‑lived cosign key (or OIDC workload identity) so promotion is verifiable offline.
- Provide deterministic, reproducible signing/attestation flows that runners can execute without external registries.
- Make key rotation and verification one-liners for on-call and CI.

## Scripts
- `scripts/policy/rotate-key.sh` – generate cosign keypair, emit base64 values for CI secrets in `out/policy-sign/keys/`.
- `scripts/policy/sign-policy.sh` – sign a policy blob with `COSIGN_KEY_B64` and verify the signature; emits signature + public key to `out/policy-sign/`.
- `scripts/policy/attest-verify.sh` – create a DSSE attestation for a policy blob and verify it against the generated bundle/public key.

## Local / CI workflow
1. **Generate key (ephemeral or rotated):**
   ```bash
   OUT_DIR=out/policy-sign/keys PREFIX=ci-policy COSIGN_PASSWORD= scripts/policy/rotate-key.sh
   ```
   Copy the base64 strings from `out/policy-sign/keys/README.txt` into `POLICY_COSIGN_KEY_B64` / `POLICY_COSIGN_PUB_B64` secrets.
2. **Sign a policy:**
   ```bash
   export COSIGN_KEY_B64=$(base64 -w0 out/policy-sign/keys/ci-policy-cosign.key)
   COSIGN_PASSWORD= scripts/policy/sign-policy.sh --file docs/examples/policies/baseline.stella --out-dir out/policy-sign
   ```
   Outputs: `baseline.stella.sig`, `cosign.pub`.
3. **Attest + verify:**
   ```bash
   export COSIGN_KEY_B64=$(base64 -w0 out/policy-sign/keys/ci-policy-cosign.key)
   COSIGN_PASSWORD= scripts/policy/attest-verify.sh --file docs/examples/policies/baseline.stella --out-dir out/policy-sign
   ```
   Outputs: DSSE bundle `.attestation.sigstore` and re-verifies it with the public key.
4. **CI stage:** `.gitea/workflows/policy-simulate.yml` now installs cosign, runs the three steps above, and publishes `out/policy-sign/` as an artifact alongside simulation outputs.

## OIDC / workload identity
- Runners with keyless cosign enabled can skip `COSIGN_KEY_B64` and rely on `COSIGN_EXPERIMENTAL=1` + `COSIGN_FULCIO_URL`/`COSIGN_REKOR_URL`; keep offline jobs on key mode.
- Rotate keys per environment; keep prod keys in Gitea secrets and staging keys in repo‑local `out/` for reproducibility.

## Verification quick check
- To verify a policy blob from artifacts:
  ```bash
  cosign verify-blob --key out/policy-sign/cosign.pub --signature out/policy-sign/baseline.stella.sig docs/examples/policies/baseline.stella
  cosign verify-blob-attestation --key out/policy-sign/cosign.pub --type stella.policy --bundle out/policy-sign/baseline.stella.attestation.sigstore docs/examples/policies/baseline.stella
  ```

## Notes
- All outputs are deterministic (UTC timestamps, fixed file names) to stay audit-friendly and offline-ready.
- Attestation predicate captures filename + SHA256 + timestamp for traceability. Update predicate schema if promotion metadata expands.