Staple attestation to OCI image

[Bo98]

Basic framework for stapling attestations to OCI image, which allows us to fetch attestations from the same source we download bottles and means we don't have the restrictions of needing an API token (or a heavily rate-limited endpoint without a token). This is the first of two steps required for attestations to leave beta (the second step being the fetching side paired with sigstore-ruby but that should be easy).

Basically how it works is we upload the attestation as a blob and reference it in the manifest annotation as sh.brew.attestation_bundle, which will allow brew to download it in just one extra roundtrip.

For uploading however we need extra manifests etc. Brew won't use these but the OCI registry does.

The best way to do this is using OCI 1.1, using an approach like https://github.com/sigstore/cosign/blob/main/specs/BUNDLE_SPEC.md. Unfortunately, GitHub Packages is AFAICT the only major OCI registry that still does not support OCI 1.1 (despite Azure being one of the first to support it).

Alternative approaches unfortunately all suck but they include:

• Use the tag "fallback" method:

  • This creates a separate "referrer list" image index for each bottle and uploads each as a separate tag.
  • Pros:
    • It's the recommended way to support OCI registries that still lack OCI 1.1 support
  • Cons:
    • This is a breaking change for people using the tags API, though number of users are perhaps small.
    • It will spam a lot of fake tags into the tag list, making it somewhat useless as a tag list.
    • It requires the most code.
    • It makes the upload process less atomic as each tag needs to be uploaded separately and natural internet failures/outages could occur between stages. It'll also upload slower but benchmarks are TBC.

• Use the untagged "fallback" method:

  • Do the above but push an untagged image index.
  • Pros:
    • Doesn't affect the tag list
  • Cons:
    • Not really possible to fetch the image index again (we won't, but mirror tools will)
    • Dubious relying on it not to be GCed (GitHub probably won't but still)
    • Probably will break most mirror tools.

• Add the referrer manifests directly to the bottle manifest list

  • Pros:
    • Should be OCI "compliant" and likely not break anything.
  • Cons:
    • Very dubious abuse of OCI manifest list (mixing attestations as a variant of a bottle doesn't make sense)
    • Increases manifest download size by ~350 bytes per bottle. Small but inefficient.
    • Does not scale well if we add other referrer-type manifests (like the all_files thing that's planned).

• Inline the whole thing in an annotation (potentially as base64):

  • Pros:
    • Again, should be OCI "compliant" and likely not break anything.
  • Cons:
    • Can massively increase the manifest size by as much as 15x.
    • Lots of duplicate data as a single bundle can cover most/all bottles (but not always!)
    • Even if every bundle was different, that's a lot of bundles you didn't need to know about.

[Bo98]

(Created this PR mostly in advance of the AGM for discussion.

Talked a bit to @woodruffw in person today about OCI 1.1 and potential paths forward - nothing confirmed yet but will discuss further in Slack.)

[MikeMcQuaid]

Seems ideal if/when GitHub supports this, thanks!