image: expose in-toto attestation statements via the API - #52636

- What I did
Added a new Engine API endpoint, GET /images/{name}/attestations, which returns the in-toto attestation statements attached to an image for a given platform.

Query parameters:

• platform: JSON-encoded OCI platform; defaults to the daemon’s host platform if omitted.
• type: comma-separated list of in-toto predicate type URIs; if omitted, all statements are returned.
• statement: boolean, defaults to false. When true, the daemon reads each matching statement blob and includes the verbatim in-toto JSON in the response. When omitted or false, only the descriptor and predicate type are returned and statement blobs are not read.

The response is a JSON array of statement objects. Each object contains the layer's OCI descriptor (including media type, digest, size, annotations), the in-toto predicate type, and when statement=true is set, the verbatim statement JSON. With statement=true the caller gets the full content inline and avoids additional registry round-trips; without it, the response is metadata only.

- How I did it
The manifest-chain walk (locating the image manifest for the platform and the associated attestation manifest) is delegated to policyimage.ResolveSignatureChain from policy-helpers, ensuring that both Moby and BuildKit agree on how to interpret the attestation storage format.

The statement-layer iteration and blob reading are implemented in daemon/containerd/image_attestations.go. WhenIncludeStatement is set, the daemon fails fast on the first unreadable blob and reads matching blobs eagerly into memory; otherwise the content store is not touched for statement bodies.

The endpoint is implemented for the containerd image store. The legacy graphdriver store returns errdefs.NotImplemented (HTTP 501), allowing clients to distinguish backend non-support from images that have no attestations.

HTTP status codes:

• 200 - success (empty array when the image has no attestations)
• 400 - malformed platform value, or API version below 1.55
• 404 - unknown image, or no manifest for the requested platform
• 500 - server error (e.g., blob read failure)
• 501 - legacy graphdriver backend; attestations not supported

The Go client SDK exposes (*Client).ImageAttestations(...), returning an ImageAttestationsResult wrapper that contains an Items slice.

- How to verify it

• Build an image with attestations.

• Query the endpoint:

  curl --unix-socket /var/run/docker.sock \
    'http://localhost/v1.55/images/attest-test:latest/attestations' | jq '.'
  

• Include statement bodies:

  curl --unix-socket /var/run/docker.sock \
    'http://localhost/v1.55/images/moby/buildkit:latest/attestations?statement=true' | jq '.'
  

• Or filter by predicate type:

  curl --unix-socket /var/run/docker.sock \
    'http://localhost/v1.55/images/attest-test:latest/attestations?type=https://slsa.dev/provenance/v1' | jq '.'
  

Automated coverage:

• Unit tests in daemon/containerd/image_provenance_test.go cover layer iteration, filtering behavior, and error propagation.
• Integration tests in integration/image/attestation_test.go exercise the HTTP endpoint end-to-end via the client SDK.

- Human readable description for the release notes

Add `GET /images/{name}/attestations` endpoint returns in-toto attestation statements (such as SLSA provenance and SPDX SBOM) attached to an image, with optional platform selection, predicate type filtering, and an opt-in `statement` query parameter for retrieving the verbatim statement bodies. Clients can now retrieve attestation metadata and content directly from the daemon instead of performing additional registry round-trips.