basicstack/ProofedMesh
SHA256
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ProofedMesh/services/transparency-log/README.md
CTO 69b3f3012f
All checks were successful
validate / Rego (opa fmt + opa test) (push) Successful in 14s
Details
validate / JSON Schema (ajv) (push) Successful in 20s
Details
validate / Go (vet + test) (push) Successful in 20s
Details
services: add transparency-log Go service (ADR-0005 POST /api/v1/log/entries) 
- services/transparency-log/pkg/backend: Backend interface with in-memory
  append-log (RFC 6962 Merkle tree) + Trillian wrapper (prod stub).
- Idempotenz-Pflicht: Wiederaufruf mit identischem content_hash liefert
  200 + gleichen log_index + aktuellen inclusion_proof.
- content_hash-Verifikation serverseitig; Mismatch → 409.
- pkg/httpapi: ADR-0005-konformer Handler (201/200/400/404/409/503).
- cmd/transparency-log: minimaler HTTP-Server, memory default,
  --backend trillian als Stub (503).
- Interop-Test in services/admin-api/internal/tlog/interop_test.go
  fährt die echte transparency-log pkg gegen die admin-api
  HTTPSubmitter — Happy-Path, Idempotenz und content_hash-Mismatch
  abgedeckt.
- go test: 10 Tests transparency-log + 2 Interop-Tests admin-api, go
  vet clean in beiden Modulen.

Folge-Subtask: Trillian-Deployment + Keys (siehe ADR-0005 Open Points).

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-10-25 18:08:53 +00:00

3.3 KiB
Raw Blame History

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 Stub (503 bei Submit) Prod. Wiring folgt im Trillian-Subtask.

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. [DEV-xxx] Trillian-Deployment (Logserver + Signer-Key, Namespace agent-trust), danach backend.Trillian.Submit echt verdrahten.
  2. Pocket-ID-Middleware vor den Handler hängen (gleiche OIDC-Discovery wie signing-service, Audience/client_id-Whitelist über OPA-Policy).
  3. STH-Verteilung: periodisch signierten Tree Head veröffentlichen (eigenes Deployment, nutzt denselben Signing-Service).