railiance-infra/docs/sops-rotation.md

# Bounded SOPS Recipient Rotation

The default operation is metadata-only and does not decrypt values:

```bash
python3 scripts/sops_rotation.py --check
```

It compares each protected file's public age-recipient metadata with the first
matching rule in `.sops.yaml`. CI runs this check to detect recipient drift.
The JSON output includes the exact file paths, ciphertext SHA-256 hashes, and
before/after recipient sets. Run without `--check` to inspect proposed drift.

An attended non-printing decryption check may emit a receipt:

```bash
python3 scripts/sops_rotation.py --check --verify-decryption \
  --receipt reports/sops-rotation-check.json
```

Decrypted bytes go directly to the null device. They are not retained in the
receipt or command output.

Actual key updates require `--apply` and an approval YAML containing
`approved: true`, `approved_by`, `approved_at`, and an exact `changes` list from
the current plan (including each changed file's `sha256`). The command fails if
that list differs from current metadata or the reviewed ciphertext has changed.
Applied receipts retain the reviewed before/after recipient sets and original
ciphertext hash, plus `after_sha256` for the resulting ciphertext.
Review and preserve recovery-key custody before approving recipient removal.
Start from `docs/sops-rotation-approval.example.yaml`; the committed example is
deliberately unapproved and contains no usable recipient.

Rollback is a reviewed restoration of the prior `.sops.yaml` recipient set
followed by the same exact-plan approval, `sops updatekeys`, and non-printing
decryption verification. Git history alone is not recovery-key custody.