# Release attestations

A release attestation is a signed statement of what Bucker knew about one build artifact, for one
commit and one environment, at one moment. Your deploy step checks it **offline**, with no call to
Bucker, and your own policy decides what to do. A Bucker outage can neither block a deploy nor wave
one through: the check Bucker posts on your pull request stays neutral, and the deploy decision is
yours.

## What you get

An in-toto Statement v1 in a DSSE envelope, valid for **24 hours**.

- **Subject**: the digest of the build artifact your CI step reported (`sha256:<hex>`), so an
  admission controller that matches on the image digest works.
- **Predicate type**: `https://spec.bucker.io/release-attestation/v0.1`. That address names the
  format. It is never fetched, by Bucker or by the verifier.
- **Predicate**: the signed evidence (organization, project, release, commit, environment, verdict,
  open-issue counts, validity window), the gates that were evaluated with their stage, revision,
  rule-set digest, per-rule outcomes and the digest of each signed gate result, the overrides in
  force named by the digest of their own receipts, and what the CI step reported about itself.
- **Signature**: Ed25519 over the DSSE pre-authentication encoding, by the Bucker signing key. The
  same evidence is filed as a `release_attestation` receipt in your organization's receipt log
  (`ledgerRef`, `org-log:<seq>`), where `bucker-verify verify-log` can check it.

It carries counts, digests, identifiers and gate rule names. It carries no issue title, file name,
author or override reason.

## Asking for one

```bash
curl -sS -X POST "https://api.bucker.io/orgs/$ORG/projects/$PROJECT/release-attestations" \
  -H "Authorization: Bearer $BUCKER_TOKEN" -H 'content-type: application/json' \
  -d '{"sha":"'$GITHUB_SHA'","environment":"production",
       "artifactDigest":"'$IMAGE_DIGEST'","artifactName":"ghcr.io/acme/shop",
       "repository":"'$GITHUB_REPOSITORY'","ref":"'$GITHUB_REF'","workflow":"release.yml"}' \
  | jq .attestation.envelope > attestation.json
```

`BUCKER_TOKEN` is the organization CI token you already use for releases. It needs `release:write`,
which every org CI token has; nothing about issuing widens a token. A person with write access to
the project can ask too. An agent cannot, and neither can an OAuth client: an attestation is a system
act after a deterministic evaluation.

Asking again for the same artifact within a minute returns the attestation already issued
(`reused: true`). `GET .../release-attestations?environment=&artifactDigest=&sha=` lists a project's
attestations with their `status` (`valid`, `expired`), and `GET .../release-attestations/:id` reads
one.

`repository`, `ref` and `workflow` are what your CI step **reported**. They are recorded as such
(`reportedByCi`) and proven by nothing. The keyless exchange that would prove them, trading a GitHub
or GitLab workflow's OIDC token at Bucker's RFC 8693 endpoint for a short-lived token bound to
repository, ref, commit, workflow and environment, **is not built**. It waits on the security review
of the authorization server. Until then, issuing uses your CI token.

## Checking one in the deploy step

Fetch the public key once, from a place you trust, and keep it with your deploy configuration:

```bash
curl -sS https://api.bucker.io/.well-known/proof-ledger-keys | jq -r .publicKeyPem > org.pem
```

Then, in the deploy job:

```bash
npx bucker-verify attestation attestation.json \
  --env production \
  --artifact-digest "sha256:$IMAGE_DIGEST" \
  --org "$BUCKER_ORG_ID" \
  --project "$BUCKER_PROJECT_ID" \
  --commit "$GITHUB_SHA" \
  --key org.pem
```

**What you are deploying is not optional.** `--env`, `--artifact-digest` and `--org` are required,
and the command refuses to run without them (exit 64). A signature proves only that Bucker signed
*something*. The signing key is Bucker's, not yours, so another organization's attestation for the
same image digest carries a valid signature too. Only the digest, environment and organization you
state make "is this the attestation for this deploy" answerable. Pass `--project` and `--commit`
too, as above: anyone with write access to ANOTHER project of your organization can ask for an
attestation of the same image digest, and only `--project` tells that one apart from this project's.
`--commit` takes at least seven hex characters.

| Exit | Meaning |
| --- | --- |
| 0 | Signature valid under your key, and every claim holds. |
| 2 | No key you supplied verifies the signature: the attestation was altered or signed by another issuer. |
| 4 | The signature holds but the attestation does not say what this deploy needs. The finding code says which. |
| 6 | Not a release attestation, or malformed. |
| 7 | No key was supplied. Nothing was checked, so nothing is accepted. |
| 64 | Usage error. |

Finding codes under exit 4: `EXPIRED`, `NOT_YET_VALID`, `VALIDITY_TOO_LONG`, `WRONG_ARTIFACT`,
`SUBJECT_MISMATCH`, `WRONG_ENVIRONMENT`, `WRONG_ORG`, `WRONG_PROJECT`, `WRONG_COMMIT`,
`VERDICT_NOT_ACCEPTED`. Run with `--json` to read them. `--now <ISO time>` fixes the clock for a
reproducible check. The command imports no network module and reads the clock in one place, the
default of `--now`.

## The verdict, and whose policy it is

Over the project's gates that cover a deploy, evaluated when you ask:

| Verdict | When |
| --- | --- |
| `blocked` | An **enforced** gate failed and no override covers it. |
| `not_evaluated` | No **enforced** gate of this project covers a deploy (shadow and warn gates alone decide nothing, pass or fail), an enforced gate could not decide (missing data), or an enforced gate could not be read. |
| `attention` | Every enforced gate passed or is covered by an override in force, and a warn or shadow gate failed or an override was needed. |
| `clear` | At least one enforced gate passed and nothing failed. |

Bucker never refuses to issue because of the verdict: it states the fact. By default the verifier
accepts `clear` and `attention` and refuses `blocked` and `not_evaluated` (`VERDICT_NOT_ACCEPTED`).
`--accept-verdict clear` is stricter; `--accept-verdict clear,attention,not_evaluated` is looser. An
override is never reported as `clear`: Bucker does not claim a pass it did not compute. An override
counts only when it has a signed receipt, so it can be named by digest, and only while the gate is
at the revision the person overrode: editing the gate ends the override's effect on attestations.

`openIssues` counts the project's issues that are new, ongoing or regressed. `newIssuesSinceBaseline`
counts those first seen after the **baseline**, the most recent earlier deploy of this project to the
same environment. With no earlier deploy it is 0 and the predicate's `baseline` is `null`.

## Offline revocation

Validity is short on purpose: an attestation is stale after 24 hours whatever happens. Revoking one
before then (a person's act) and listing revoked attestations in the checkpoint are not built yet; a
verifier that must honour a revocation sooner than the window ends needs to fetch the status, which
this offline command deliberately does not do.

## Kyverno and Sigstore policy-controller

The subject digest is the artifact's, so an `ImageVerification` / `ClusterImagePolicy` attestation
rule can select the statement by `predicateType` and read `predicate.evidence.verdict`,
`predicate.evidence.validUntil` and `predicate.evidence.environment` in a CEL or JMESPath condition.
Distribute the Bucker public key as the policy's key.

## What is held

- The keyless workflow-identity exchange (OIDC at the RFC 8693 endpoint). No route exists for it.
- Which key signs releases: today the proof-ledger signing key does. A dedicated release key, or a
  key per organization, is the owner's decision (H-409). Until then the organization check above is
  what separates one tenant's attestations from another's.
