ProofedMesh/services/transparency-log/README.md

# 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`  | implementiert (DEV-604); 503 wenn unkonfiguriert | Prod. gRPC-Client auf Trillian LogServer. Siehe [`deploy/trillian/`](../../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)

```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. 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`](../../deploy/trillian/README.md) —
Trillian (MySQL + LogServer + LogSigner + Tree) läuft im Namespace
`agent-trust` auf dem BasicStack-Cluster (DEV-604).