Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0030
ADR-0030: Provenance uses in-toto / SLSA attestations rather than a bespoke format
| field | value |
|---|---|
| Status | Accepted |
| Date | 2026-07-24 |
| Register | factory (docs/adr, 4-digit ids) |
| Source | docs/adr/0030-provenance-uses-in-toto-slsa-attestations.md — permalink at bdafa201a (unchanged on master since that commit) |
| Wiki register entry | ADR-0030 (wiki status: Accepted) |
The record
- Status: Accepted
- Date: 2026-07-24
- Spec: SPEC-033 §1, §2, §7
- Amends: ADR-0001, ADR-0017
Context
Three separate decisions in this register each invent a piece of the same thing:
- ADR-0001 makes the enforcement boundary the committed worktree state, so the gate reasons about what changed between two states rather than what an agent claims it did.
- ADR-0017 makes governed writers attested pure functions — a writer declares its inputs and outputs and the gate verifies the declaration against reality.
- §7's threat model requires that a generated artefact be traceable to the requirement, the design and the executing identity that produced it, in a form an attacker cannot forge by self-report.
Together that is: signed statements binding a step's declared inputs and outputs to the identity that performed it, chained so the whole pipeline can be verified end to end. This is exactly the problem in-toto was built for, and SLSA is the maturity model layered on top of it.
The relevant mechanics map onto our design almost one-to-one:
- in-toto layouts declare the ordered steps of a supply chain, the materials (inputs) and products (outputs) each step may touch, and the authorized functionaries permitted to perform it — our pipeline stages, governed-writer allowlist, and three-UID execution model (ADR-0018).
- in-toto link metadata is the signed record of what a step actually consumed and produced. Verifying a layout means checking every link against the declared rules.
- in-toto artifact rules —
MATCH,ALLOW,DISALLOW,REQUIRE,CREATE,DELETE,MODIFY— are a state-diff enforcement language.MATCHin particular asserts that one step's products are exactly the next step's materials, which is the chaining property ADR-0001 needs and currently states informally. - SLSA provenance attests the builder identity, the build definition, and the resolved dependencies, and its levels give us a vocabulary for how hardened a claim is — notably that provenance must be generated by the build platform, not by the thing being built, which is the same no-self-report principle ADR-0008 and ADR-0024 assert independently.
We currently have none of this written down as a format. A bespoke one would have to re-derive the signing model, the chaining rules, the revocation story and the verification algorithm — and would be unverifiable by any external tool.
Decision
Adopt in-toto attestations as the provenance format, and SLSA as the level vocabulary.
- A governed writer's attestation (ADR-0017) is in-toto link metadata: signed, declaring materials and products, bound to the executing identity.
- Pipeline stage ordering and the governed-writer allowlist are expressed as an in-toto layout with authorized functionaries, rather than as prose in the spec.
- Cross-stage state-diff enforcement (ADR-0001) uses artifact rules, with
MATCHchaining each stage's products to the next stage's materials. - The factory declares a target SLSA level and states honestly which level it currently meets. The non-negotiable property is the one SLSA makes explicit: provenance is generated by the platform, never by the agent being governed.
This amends rather than supersedes ADR-0001 and ADR-0017: both decisions stand, and this record fixes the format in which they are expressed.
Alternatives rejected
- A bespoke attestation format — re-derives a solved problem, and produces artefacts no external verifier understands. The only argument for it was that we hadn't looked.
- Git signatures alone — attest who committed, not what a step consumed and produced, and cannot express the chaining rule.
- SLSA without in-toto — SLSA is a level model over an attestation format; adopting it alone leaves the format unspecified, which is the actual gap.
- Defer until Phase 1 — the format choice is cheapest before writers exist and expensive after; ADR-0017's writers are Phase-0 work.
Consequences
- Adds a signing and key-management story that the design has so far avoided naming. This is real work and a real operational burden, and it is the price of provenance that is not self-reported.
- Attestations must be stored and queryable, which touches ADR-0003's storage decision and ADR-0004's
(worktree, commit)fact keying — an attestation is naturally keyed the same way. - Gains external verifiability: an in-toto layout can be checked by tooling we did not write, which is a meaningfully stronger position than "our gate says it passed".
- The declared-vs-actual materials check makes ADR-0017's purity claim enforceable rather than asserted — a writer that touches an undeclared input fails verification.
Provenance
2026-07-24 prior-art research, which identified in-toto/SLSA as already modelling the provenance requirement that §7 and ADR-0017 state independently.
Related ADRs
Rulings cited
None.