Support "oras pull" for attestations

[ralphbean]

Description

In slack, I saw some musing about letting users use a tool like oras to pull down attestations from the OCI registry and letting cosign do the verification locally.

One small improvement that could help make that more viable is if we added a org.opencontainers.image.title annotation to each layer in the image manifests that cosign attest pushes (the ones with artifactType application/vnd.dev.sigstore.bundle.v0.3+json).

oras pull uses that annotation to determine what the local file name it should use when writing out the blob to disk. Without that annotation (today), oras pull <oci image ref to the attestation itself> just skips downloading the bundle.

If we were to add it, what name should we set in the value?

• We could use a fixed name like attestation.sigstore.json. Since the image manifests always include only one blob, there are no other names to collide with.
• However, if you have multiple attestations and you "oras pull" all of them with multiple invocations in the same directory, then the names would collide. Frustrating!
• We could use the digest of the referred-to artifact in the name. That might be nice since the name of the file would reflect the subject of the attestation (which is what you normally see in file-based attestation in, for example, a github release of some project), but it would collide unless we differentiated them somehow.
• What if we used the digest of the attestation bundle in the name, like sha256:e9f5f5b00ca581a437925b0717e8f0845cd8f853864021f5aa365f4d1ce370ab.sigstore.json. There would be no collisions. Each attestation for the same original OCI subject would get a different filename.
• What if we let the user specify it with an optional flag to cosign attest. More flags is a UX burden, but the user may know best how they want people to see the attestation when it later lands on a consumer's filesystem.

I think I like the combination of (1) use the digest of the attestation bundle in the name as a default and (2) let the user override it with a custom name if they care to. The default is safe and collision free and a user-friendly name is just around the corner.

---

To be clear, here I'm talking about adding an annotation to the layer in the image manifest, not an annotation on the image manifest itself. We already set some annotations on the image manifest, but currently set no annotations on the layer.

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "size": 2,
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
  },
  "layers": [
    {
      "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
      "size": 6771,
      "digest": "sha256:e9f5f5b00ca581a437925b0717e8f0845cd8f853864021f5aa365f4d1ce370ab"
      // Right here
      "annotations": {
        "org.opencontainers.image.title": "my-cool-new-attestation-filename.json"
      }
    }
  ],
  "annotations": {
    "dev.sigstore.bundle.content": "dsse-envelope",
    "dev.sigstore.bundle.predicateType": "https://sigstore.dev/cosign/sign/v1",
    "org.opencontainers.image.created": "2025-10-24T14:03:07Z"
  },
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 772,
    "digest": "sha256:4ba82e25ea7779793aa5764f944f072a4567963ec68ab6718cea6e485d0d9d38"
  },
  "artifactType": "application/vnd.dev.sigstore.bundle.v0.3+json"
}

---

Note, #4205 and #4491 added support to cosign tree to expose the digest of attestations, giving the user a way to discover them, although oras discover also works.