Skip to content

feat: add release conformance attestation format (relay-conform-attestation/1), spec §20.6 - #183

Merged
SoundMatt merged 1 commit into
mainfrom
feat/relay-142-attestation-format
Aug 21, 2026
Merged

feat: add release conformance attestation format (relay-conform-attestation/1), spec §20.6#183
SoundMatt merged 1 commit into
mainfrom
feat/relay-142-attestation-format

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Summary

Implements a scoped-down version of issue #142 (NEW-SPEC-4), per explicit direction to scope this spec-only rather than stand up real signing/publishing infrastructure.

Scope decision

The originating issue proposed a signed SLSA/in-toto attestation published alongside a release's container image, with its digest surfaced in version --format json and relay probe/relay report treating unverifiable releases as non-conformant. This PR ships spec-only: it defines the predicate format an implementation MAY publish, without actual signing or publishing.

Two concrete blockers made "full implementation" the wrong call here:

  • RELAY's own CI only does docker build as a smoke test — it doesn't push images to any registry. "Published alongside the release's container image" presupposes infrastructure that doesn't exist.
  • Real cryptographic signing needs real key management (e.g. Sigstore/cosign keyless signing). Fabricating an unreal "signature" would be worse than not signing at all.

predicate.signed MUST be false on an unsigned attestation. This section defines shape only — it does not mandate a signing mechanism or publication channel.

What's added

  • New §20.6 defines the relay-conform-attestation/1 predicate: an in-toto Statement whose subject digest is the SHA-256 of the attested binary file, and whose predicate bundles the full §17.2 conformance manifest, the attestation-generating tool's own embedded vectors_version (§15.8 — explicitly not observed from the attested binary, since a black-box invocation cannot introspect it), and an optional implementation-defined safety_evidence_summary.
  • New embedded schema spec/schemas/relay-conform-attestation.json.
  • Reference implementation: relay conform --attestation <binary> in cmd/relay/conform.go.
  • New REQ-RELAY-098.

Bug found and fixed along the way

While wiring the attestation's conformance_manifest field, I found buildManifest's Requirements slice was missing entry 16 (Vector manifest) — PR #181 added the §17 Requirement 16 spec text and verifier-table row but never added the corresponding code entry. Every relay-conform/1 manifest generated since v2.4 has silently omitted it, despite the spec's own text mandating "exactly one entry per §17 requirement (1–16, ...)". Fixed; the two manifest-shape tests that should have caught this (TestBuildManifestSelf, TestRunConformManifestFlag) were also stale at a hardcoded 15 and are corrected alongside it.

Version

SpecVersion bumped 2.52.6 (MINOR, new optional format + CLI flag).

Verification

  • 6 new tests for the attestation feature, including independent cross-checks: the subject digest matches a separately-computed SHA-256 of the binary file, vectors_version matches the tool's own parsed vectors_manifest.json, and schema validation against the new embedded schema.
  • Real mutation test on the Requirement-16 bug fix: reverted the fix, confirmed both TestBuildManifestSelf and TestRunConformManifestFlag correctly failed, restored and confirmed green.
  • Manually verified relay conform --attestation end-to-end: digest independently matched via hashlib.sha256, overall: PASS, signed: false, 16 requirement entries.
  • go build ./... && go vet ./... && go test ./... — all packages green.
  • gofmt -l . and golangci-lint run (latest) — clean.
  • gofusa check (pinned v0.48.0): 0 errors. gofusa trace -req-coverage 100: 100% (98/98).

Closes #142.

…tation/1), spec §20.6

- New §20.6 defines the shape an implementation MAY publish to make §20.1's
  CI gates externally verifiable rather than self-asserted: an in-toto
  Statement whose subject digest is the SHA-256 of the attested binary
  file, and whose predicate bundles the full §17.2 conformance manifest,
  the attestation-generating tool's own embedded vectors_version (§15.8 -
  explicitly NOT observed from the attested binary, which a black-box
  invocation cannot introspect), and an optional implementation-defined
  safety_evidence_summary.
- Scope decision, documented in the CHANGELOG rather than silently
  narrowed: this PR ships spec-only. The originating issue also proposed
  cryptographic signing, publishing alongside a release's container
  image, surfacing the digest in version --format json, and having
  relay probe/relay report treat an unverifiable release as
  non-conformant. None of that ships here - RELAY's own CI does not
  currently push container images to any registry, and fabricating an
  unreal 'signature' without real key management would be worse than not
  signing at all. predicate.signed MUST be false on an unsigned
  attestation; this section defines shape only.
- New embedded schema spec/schemas/relay-conform-attestation.json.
- Reference implementation: relay conform --attestation <binary> in
  cmd/relay/conform.go.  New REQ-RELAY-098.
- Real bug found and fixed while implementing this: buildManifest's
  Requirements slice was missing entry 16 (Vector manifest) - PR #181
  added the §17 Requirement 16 spec text and verifier-table row but never
  added the corresponding code entry, so every relay-conform/1 manifest
  generated since v2.4 silently omitted it despite the spec's own text
  mandating 'exactly one entry per §17 requirement (1-16, ...)'. Fixed;
  the two manifest-shape tests that should have caught this
  (TestBuildManifestSelf, TestRunConformManifestFlag) were also stale at
  a hardcoded 15 and are corrected alongside it. Mutation-tested: reverted
  the fix, confirmed both tests failed, restored.
- 6 new tests for the attestation feature, including independent
  cross-checks: subject digest matches a separately-computed sha256 of
  the binary file, vectors_version matches the tool's own parsed
  vectors_manifest.json, and schema validation against the new embedded
  schema.
- SpecVersion bumped 2.5 -> 2.6 (MINOR, new optional format + CLI flag).

Closes #142.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Matt <47545907+SoundMatt@users.noreply.github.com>
@SoundMatt
SoundMatt merged commit 0fd692a into main Aug 21, 2026
8 checks passed
@SoundMatt
SoundMatt deleted the feat/relay-142-attestation-format branch August 21, 2026 12:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[NEW-SPEC-4] Signed release conformance attestation, bundling the conformance manifest and vector hash

1 participant