ADORSYS-GIS / ADORSYS-GIS/lightbridge-governance
[Story]: Release binaries carry verifiable build provenance
- Vorherrschende Sprache
- Rust
- Sterne
- 1
- Forks
- 2
- Ø Merge
- 13 Std. 13 Min.
- Gemergte PRs (30 T.)
- 110
Beschreibung
### Story Statement
As someone auditing what a developer laptop is running, I can verify that a published `governance-auth` binary was built by this repository's release workflow from a named commit — because every release asset carries a build-provenance attestation.
### Real Intent
Close an asymmetry the repo has already noticed: container images from this repo are cosign-signed, and the binary that holds a developer's refresh token is not signed at all. A checksum proves the bytes match what the release page says; it proves nothing about who produced them. If the release page is the thing in question, the checksum is circular.
ADR-0012 §6 picks `actions/attest-build-provenance` specifically because it is **keyless** — no key custody, no rotation dance — and closes the gap for every human and every republisher.
### Background and Context
The related trap this repo has already paid for is worth restating: images must be built with `cargo-auditable`, or Trivy scans only the base OS and reports a clean result meaning *"it never looked at your Rust dependencies"*. The pattern generalises — a verification step that silently inspects nothing is worse than no step, because it produces a green. That is the failure mode to design the acceptance criteria against here.
### Source of truth (links)
- [ADR-0012 §6](https://github.com/ADORSYS-GIS/lightbridge-governance/blob/main/docs/adr/0012-governance-auth-packaging-and-distribution.md)
- [`release-governance-auth.yml`](https://github.com/ADORSYS-GIS/lightbridge-governance/blob/main/.github/workflows/release-governance-auth.yml)
### Acceptance Criteria
1. `actions/attest-build-provenance` runs in the release workflow with the permissions ADR-0012 §6 names: `id-token: write`, `attestations: write`, `contents: read`.
2. **All six assets** are attested, not just the first matrix entry. Verified by attesting a real release and checking each of the six by name.
3. `gh attestation verify --repo ADORSYS-GIS/lightbridge-governance` succeeds against a genuinely published asset, and the transcript is in the PR.
4. ⚠️ **It must fail on a tampered asset.** Flip a byte and confirm verification is rejected. Without this the step could be attesting nothing and still report success — see the `cargo-auditable` precedent above.
5. Verification is **documented for a human**, in `docs/governance-auth/`, with the exact command. An attestation nobody knows how to check has no consumers.
6. ⚠️ **The `self-update` limitation is written down, not glossed.** ADR-0012 records that `gh attestation verify` requires authentication, so a colleague would need `gh auth login` before the binary could verify itself — meaning this story does **not** make `self-update` verify provenance. ADR-0012 flags this against an open `cli/cli` issue and says to recheck; **recheck it as part of this story** and record the answer either way. Silently letting a reader assume `self-update` is covered is the real risk here.
7. Adding attestation does not change asset names, the `.sha256` files, or anything `update.rs::asset_name()` depends on. `self-update` keeps working unchanged, asserted by a real self-update against the attested release.
### Out of Scope
- **In-process signature verification inside the binary** — ADR-0012 stage 6, blocked on open question 3 (sigstore keyless versus org-held Ed25519, which is a key-custody decision reserved for the maintainer).
- Apple Developer ID and notarization — ADR-0012 open question 2, ~$99/yr plus a CI signing identity, and §6 shows it is narrower than it first appears: `com.apple.quarantine` is set by browsers, not by `curl`, and a Homebrew Formula never touches it. The exposure is the initial browser download only.
- Attesting the container images. Already cosign-signed.
### Dependencies and Blockers
- None. ADR-0012's sequencing table shows stage 5 blocked on nothing — it can land in parallel with the installer work.
### Assumptions
- The repo's org settings permit `id-token: write` on this workflow. If org policy restricts OIDC token issuance, that surfaces as a blocked run rather than a silent skip — confirm it does.
### Implementation Notes
- Attest **after** the checksum step, so a mismatched pair is caught by the existing `sha256sum -c` guard before anything is attested.
- Keep it inside the existing matrix job rather than a separate collector job; each runner already holds the artefact it built.
### Test Expectations
- AC-3 and AC-4 as a pair. A passing verify alone is not evidence; the tampered-asset rejection is what makes it one.
### Verification evidence
To be filled by the implementing PR: `gh attestation verify` transcripts for a clean and a tampered asset, plus the recheck outcome for AC-6.
### Human accountable owner
@stephane-segning
### AI Usage Declaration
Drafting this story, Refining acceptance criteria, Suggesting implementation
### Human verification completed
Not yet.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.