basicstack/ProofedMesh
SHA256
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ProofedMesh/services/transparency-log
History
CTO (Paperclip) 47a7373ef2 transparency-log: add GET /api/v1/log/entries/{hash} + /healthz (DEV-613) 
The verification-service and testagent-transform clients both call
`GET /api/v1/log/entries/{content_hash}` to read a stored envelope and
inclusion proof back out of the log, but the server previously only
implemented the POST (write) half of ADR-0005. Add:

- `Backend.Get` plus `backend.Entry` and `ErrEntryNotFound` so the
  memory backend can serve the read; Trillian stays stubbed and
  continues returning 503 (`ErrTrillianUnavailable`) until a later
  subtask wires the real read path.
- `GET /api/v1/log/entries/{hash}` on the HTTP server, routing 404 /
  503 / 500 with the same error envelope as the POST half.
- `GET /healthz` so the Phase-1 smoke-test harness can wait for the
  service to come up instead of racing against its bind.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-10-25 20:57:52 +00:00
..
cmd/transparency-log transparency-log: real Trillian backend wiring + agent-trust deploy (DEV-604) 2026-10-25 18:39:44 +00:00
pkg transparency-log: add GET /api/v1/log/entries/{hash} + /healthz (DEV-613) 2026-10-25 20:57:52 +00:00
Dockerfile transparency-log: real Trillian backend wiring + agent-trust deploy (DEV-604) 2026-10-25 18:39:44 +00:00
go.mod transparency-log: real Trillian backend wiring + agent-trust deploy (DEV-604) 2026-10-25 18:39:44 +00:00
go.sum transparency-log: real Trillian backend wiring + agent-trust deploy (DEV-604) 2026-10-25 18:39:44 +00:00
README.md transparency-log: real Trillian backend wiring + agent-trust deploy (DEV-604) 2026-10-25 18:39:44 +00:00

README.md

transparency-log

Serverseitige Implementierung von POST /api/v1/log/entries laut docs/adr/0005-signing-service-and-transparency-log-api.md.

Die admin-api und spätere Agent-Dienste rufen diesen Service auf, um DSSE- Envelopes in einen Append-Only-Log zu schreiben und einen Inclusion-Proof zurückzubekommen. Der zurückgelieferte content_hash ist die stabile Attestation-ID überall sonst im System.

Vertrag

Siehe ADR-0005. Zusammengefasst:

  • POST /api/v1/log/entries mit { envelope, content_hash }.
  • Server rechnet content_hash serverseitig nach — Mismatch → 409.
  • Idempotent: Wiederaufruf mit identischem content_hash liefert 200 + dasselbe log_index + gültigen (aktuellen) inclusion_proof.
  • Erstanlage antwortet mit 201.
  • Trillian-Backend nicht erreichbar / nicht deployed → 503.

Authentisierung (Pocket-ID Bearer) wird außerhalb des Handlers über eine Middleware eingehängt; der Core-Handler ist absichtlich auth-agnostisch, damit Dev- und CI-Runs ohne IdP laufen.

Backends

Backend Status Wofür
memory implementiert Dev + CI. Append-Log + RFC 6962 Merkle Tree.
trillian implementiert (DEV-604); 503 wenn unkonfiguriert Prod. gRPC-Client auf Trillian LogServer. Siehe deploy/trillian/.

Der In-Memory-Backend ist bewusst klein gehalten: er speichert jeden Envelope als Leaf-Hash (SHA-256(0x00 || canonical envelope bytes)), rechnet Baumwurzel und Audit-Path pro Submit frisch aus und liefert deterministische signed_tree_head_ref-Werte aus (tree_size, root). Das reicht für die admin-api-Interop-Tests und den lokalen Durchstich der Vertrauenskette.

Starten (lokal)

cd services/transparency-log
go run ./cmd/transparency-log --addr :8080 --backend memory

Smoke-Test (gegen ADR-0005-Beispielpayload):

curl -sS -X POST http://127.0.0.1:8080/api/v1/log/entries \
  -H 'Content-Type: application/json' \
  -d '{"envelope":{"payloadType":"application/vnd.in-toto+json","payload":"aGVsbG8","signatures":[{"keyid":"k","sig":"c2ln"}]},"content_hash":"<siehe EnvelopeContentHash>"}'

Der korrekte content_hash ergibt sich aus backend.EnvelopeContentHash (bit-identisch zu admin-api/internal/attest.EnvelopeContentHash).

Tests

cd services/transparency-log
go vet ./...
go test ./...

Die wichtigen Testpakete:

  • internal/backend — Append-Log, Idempotenz, content_hash-Mismatch, RFC-6962-Audit-Path-Verifikation.
  • internal/httpapi — HTTP-Statuscodes (201/200/400/404/409/503).
  • internal/interop — admin-api tlog.HTTPSubmitter gegen diesen Server, Happy-Path + Idempotenz + Content-Hash-Mismatch.

Die go.mod enthält eine replace-Direktive auf die lokale admin-api, damit der Interop-Test den tatsächlichen Produktions-Client importieren kann.

Nächste Schritte

  1. Pocket-ID-Middleware vor den Handler hängen (gleiche OIDC-Discovery wie signing-service, Audience/client_id-Whitelist über OPA-Policy).
  2. STH-Verteilung: periodisch signierten Tree Head veröffentlichen (eigenes Deployment, nutzt denselben Signing-Service).
  3. Image-Build-Pipeline (CI/CD): Push von services/transparency-log/Dockerfile nach harbor.basicstack.de/proofedmesh/transparency-log:<tag> automatisieren und deploy/trillian/40-transparency-log.yaml auf diese Tags anpassen.

Prod-Deployment

Siehe deploy/trillian/README.md — Trillian (MySQL + LogServer + LogSigner + Tree) läuft im Namespace agent-trust auf dem BasicStack-Cluster (DEV-604).