86 lines
3.3 KiB
Markdown
86 lines
3.3 KiB
Markdown
|
# transparency-log
|
||
|
|
|
||
|
|
Serverseitige Implementierung von **`POST /api/v1/log/entries`** laut
|
||
|
|
[`docs/adr/0005-signing-service-and-transparency-log-api.md`](../../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)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd services/transparency-log
|
||
|
|
go run ./cmd/transparency-log --addr :8080 --backend memory
|
||
|
|
```
|
||
|
|
|
||
|
|
Smoke-Test (gegen ADR-0005-Beispielpayload):
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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).
|