git.stella-ops.org/docs/modules/findings-ledger/prep/ledger-attestations-http.md

Ledger attestation HTTP surface (prep for LEDGER-OBS-54-001 / 55-001)

Goal. Provide the minimal HTTP contract to expose ledger attestation verifications so PREP-LEDGER-OBS-55-001 can proceed. This complements the OAS baseline (docs/modules/findings-ledger/openapi/findings-ledger.v1.yaml) and schema (docs/modules/findings-ledger/schema.md).

Endpoint

• GET /v1/ledger/attestations
• Tenant header: X-Stella-Tenant (required).
• Auth: bearer scope=ledger.attest.read or mTLS.
• Query params:
  • artifactId (string, optional; OCI digest or SBOM id)
  • findingId (string, optional)
  • attestationId (uuid, optional)
  • status (verified|failed|unknown, optional)
  • sinceRecordedAt / untilRecordedAt (ISO-8601 UTC)
  • limit (int, default 200, max 1000)
• Ordering: deterministic by recordedAt ASC, attestationId ASC.
• Response: JSON array (or NDJSON when Accept: application/x-ndjson). Each item:
  • attestationId (uuid)
  • artifactId (string)
  • findingId (string)
  • verificationStatus (verified|failed|unknown)
  • verificationTime (ISO-8601 UTC)
  • dsseDigest (sha256)
  • rekorEntryId (string, optional)
  • evidenceBundleRef (string, optional)
  • ledgerEventId (uuid) — source ledger event that linked the attestation
  • recordedAt (ISO-8601 UTC)
  • merkleLeafHash (sha256)
  • rootHash (sha256)

Determinism/offline posture

• Sorting keys are fixed; pagination token encodes {recordedAt, attestationId, filtersHash}.
• No live Rekor calls; rekorEntryId is stored reference only.
• Hashes remain lowercase SHA-256; times are UTC.

Artefact location

• This prep doc: docs/modules/findings-ledger/prep/ledger-attestations-http.md.
• Storage/view contract: docs/modules/findings-ledger/prep/ledger-attestations-storage.md.
• Add path to OAS in a follow-on increment (LEDGER-OAS-61-002/63-001) once approved.