23 lines
1.6 KiB
Markdown
23 lines
1.6 KiB
Markdown
# Ledger Observability Prep — PREP-LEDGER-OBS-54-001
|
|
|
|
Status: Prep complete (2025-11-20)
|
|
Owners: Findings Ledger Guild · Provenance Guild
|
|
Scope: Minimal HTTP surface plus determinism/telemetry hooks for `/v1/ledger/attestations`.
|
|
|
|
## Agreed contract (PREP-LEDGER-OBS-54-001)
|
|
- HTTP surface published in `docs/modules/findings-ledger/prep/ledger-attestations-http.md`.
|
|
- Endpoint: `GET /v1/ledger/attestations` with tenant header `X-Stella-Tenant` and bearer scope `ledger.attest.read` (or mTLS).
|
|
- Filters: `artifactId`, `findingId`, `attestationId`, `status`, `sinceRecordedAt`, `untilRecordedAt`, `limit`.
|
|
- Ordering/pagination: deterministic by `recordedAt ASC, attestationId ASC`; pagination token encodes `{recordedAt, attestationId, filtersHash}`.
|
|
- Response shape (JSON or NDJSON): ids, verification status/time, DSSE digest, optional Rekor entry id, evidence bundle ref, source ledger event id, Merkle leaf + root hashes.
|
|
- Offline posture: no live Rekor calls; all hashes lowercase SHA-256; times UTC; deterministic sort only.
|
|
|
|
## Telemetry hooks
|
|
- Log events: `ledger.attestations.query` (tenant, filtersHash, limit, duration_ms, result_count).
|
|
- Metrics: `ledger_attestations_queries_total{tenant,status}`; `ledger_attestations_failures_total{reason}`.
|
|
- Tracing: span `ledger.attestations.query` with attributes `filtersHash`, `next_page_token_present`.
|
|
|
|
## Handoff
|
|
- Use `docs/modules/findings-ledger/prep/ledger-attestations-http.md` as the binding prep artefact for LEDGER-OBS-54-001 / 55-001 implementation.
|
|
- Service scaffolding and OAS wiring land in LEDGER-OBS-54-001 once the web-service handler is added.
|