git.stella-ops.org/docs/release/promotion-attestations.md

Promotion-Time Attestations for Stella Ops

Status: Stable (2025-11)
Owners: Signing Guild · Provenance Guild · DevEx/CLI Guild · Export Center Guild

1. Purpose

Capture the full promotion-time evidence – image digest, SBOM/VEX artifacts, Rekor proof – in a single DSSE-wrapped statement so that air-gapped auditors can verify releases without talking to external services. This document explains the data shape, producer responsibilities, and downstream consumers that rely on the promotion attestation.

2. Predicate schema – stella.ops/promotion@v1

{
  "_type": "stella.ops/promotion@v1",
  "subject": [
    { "name": "registry.example.com/acme/api", "digest": { "sha256": "…" } }
  ],
  "materials": [
    { "role": "sbom", "algo": "sha256", "digest": "…", "format": "CycloneDX-1.6", "uri": "oci://…/sbom@sha256:…" },
    { "role": "vex",  "algo": "sha256", "digest": "…", "format": "OpenVEX-1.0",   "uri": "oci://…/vex@sha256:…" }
  ],
  "promotion": {
    "from": "staging",
    "to": "prod",
    "actor": "ci/gitlab-runner",
    "timestamp": "2025-11-10T12:34:56Z",
    "pipeline": "https://git.example.com/acme/api/-/pipelines/12345",
    "ticket": "JIRA-1234",
    "notes": "risk accepted by ops"
  },
  "rekor": {
    "uuid": "REKOR_ENTRY_UUID",
    "logIndex": 1234567,
    "inclusionProof": {
      "rootHash": "MERKLE_ROOT",
      "hashes": ["…path…"],
      "treeSize": 9876543,
      "checkpoint": {
        "origin": "rekor.sigstore.dev - transparency log",
        "size": 9876543,
        "hash": "CHECKPOINT_HASH",
        "signedNote": "BASE64_NOTE"
      }
    }
  },
  "attestation": {
    "bundle_sha256": "sha256:…",   
    "witness": "optional-transparency-witness-signature"
  }
}

The Provenance Guild implements the predicate builder (task PROV-OBS-53-003). The signer pipeline accepts the predicate as a raw JSON payload and wraps it inside a DSSE envelope (SIGN-CORE-186-005). Rekor metadata is pulled from Attestor after DSSE submission.

3. Producer workflow

3.1 CLI orchestration (CLI-PROMO-70-001/002)

1. Resolve and freeze the image digest (cosign triangulate/crane digest).
2. Hash SBOM and VEX artifacts, optionally publish them to an OCI registry.
3. Upload the SBOM (or dummy artifact) to Rekor to obtain {uuid, logIndex}.
4. Retrieve inclusion proof + checkpoint (rekor-cli get, rekor-cli loginfo).
5. Build attestation.json using the template above and current promotion metadata.
6. Call Signer to produce a DSSE bundle (cosign attest or stella promotion attest).
7. Store the bundle alongside attestation.json and add both to Offline/Replay kits.
8. Emit Timeline + Evidence Locker entries with bundle digest.

3.2 Signer responsibilities (SIGN-CORE-186-004/005/006)

• Accept the promotion predicate, verify Proof-of-Entitlement + release integrity.
• Sign via StellaOps.Cryptography providers (keyless or KMS) and return DSSE+cert bundle.
• Emit audit entries referencing the promotion metadata and Rekor proof.

3.3 Export Center integration (EXPORT-OBS-54-002)

• Bundle attestation.json, DSSE envelope, and Rekor checkpoint inside Offline kits.
• Surface promotion evidence via API/CLI for air-gapped consumers.

4. Verification flow

Auditors can validate the promotion attestation offline:

1. Verify the DSSE signature using the provided bundle and trusted key/cert chain.
2. Recompute Merkle inclusion using the embedded proof + checkpoint. The checkpoint’s signed note ties the inclusion to a known Rekor tree size.
3. Hash SBOM/VEX artifacts and compare to the materials digests.
4. Confirm the promotion metadata in release notes/CI evidence.

Authority exposes helper APIs (AUTH-VERIFY-186-007) to replay both DSSE and Merkle validations.

5. APIs & storage

Component	Endpoint / Artifact	Notes
Signer	POST /api/v1/signer/sign/dsse	Accepts promotion predicate, returns DSSE bundle + auditId.
Attestor	POST /api/v1/rekor/entries	Persists DSSE, returns {uuid, index, proof}.
Export Center	GET /api/v1/exports/{id}/promotion (planned)	Serve promotion attestation + bundle.
Evidence Locker	Store DSSE + Rekor proof for long-term retention.

Artifacts are content-addressed via CAS and mirrored into Offline kits (docs/replay/DETERMINISTIC_REPLAY.md).

6. Security considerations

• Promotion metadata is tenant-scoped; aim to avoid leaking pipeline URLs across tenants.
• Rekor inclusion proofs must be fetched at promotion time and embedded; do not rely on on-demand Rekor access in air-gapped installs.
• Rotate signing keys via Authority/KMS; promotion attestation inherits Signer’s DSSE trust model.

7. Implementation checklist

Area	Sprint task	Status
Predicate builder	PROV-OBS-53-003	TODO
Signer support	SIGN-CORE-186-004/005/006	TODO
CLI commands	CLI-PROMO-70-001/002	TODO
Authority verifier	AUTH-VERIFY-186-007	TODO
Export packaging	EXPORT-OBS-54-002	TODO
Documentation	DOCS-PROMO-70-001	DONE (2025-11-26)

When all tasks are completed this document should be updated with status links and sample payloads.