nexarch/mail/docs/ARC-08-PRUEFPROTOKOLL.md

# ARC-08 – Prüfprotokoll: Verschlüsselungsschlüssel-Rotation

Voraussetzung ARC-02 (Fertig).

## Architektur-Ausgangslage (real geprüft)

Core (API-10, `internal/kek.Store.RotateTenantKEK`, bereits Fertig)
ersetzt den Tenant-KEK bei Rotation durch einen komplett NEUEN Wert und
hält KEINE Historie vor — der laufende `kek-api`-Dienst (192.168.1.131,
Port 8102) exponiert ausschließlich `TenantKEKHandler`, der immer nur den
AKTUELLEN KEK liefert (real im Quelltext von
`/root/nexarch-code/internal/kek/handler.go` und `cmd/kek-api/main.go`
auf 131 verifiziert). Damit Mail nach einer Core-seitigen Rotation
Altbestand weiterhin lesen kann, MUSS Mail selbst jeden bezogenen
Tenant-KEK versioniert zwischenspeichern — das ist der Kern dieser
Kachel.

## Umsetzung

- `mail/internal/crypto/kekversions.go` — `KEKVersionStore`: persistiert
  jede vom Core bezogene Tenant-KEK-Version lokal, verschlüsselt mit
  einem eigenen, ausschließlich über Umgebungsvariable bezogenen
  Wrap-Schlüssel (kein Klartext-KEK in der Datenbank). `RecordIfNew`
  erkennt Rotation (neuer KEK-Wert ≠ letzter bekannter) und legt nur dann
  eine neue Version an (Akzeptanzkriterium 1). `Revoke` sperrt gezielt
  eine einzelne Version (Pflichtprüfung 2).
- `mail/internal/crypto/service.go` — `Service.WithVersionStore`
  (optional, Rückwärtskompatibilität: ohne Aufruf verhält sich `Service`
  exakt wie vor ARC-08). `Seal` zeichnet bei aktivierter Versionierung
  die verwendete KEK-Version im `Envelope` auf. Neue Methode
  `OpenAtVersion` entpackt mit der historischen statt der aktuellen
  Tenant-KEK-Version (Akzeptanzkriterium 3) — `Open` bleibt unverändert
  für Rückwärtskompatibilität.
- `mail/internal/encstorage/encstorage.go` — neuer Sidecar
  `<key>.dek.version` (gleiches Muster wie der bestehende `.dek`-Sidecar
  aus ARC-02) speichert die KEK-Version je Objekt. `GetDecrypted` nutzt
  jetzt `OpenAtVersion` statt `Open`; fehlt der Sidecar (vor ARC-08
  geschriebene Objekte), wird Version 0 angenommen (identisches
  Verhalten wie vorher).
- Kein Umbau: `mail/internal/storage`/`mail/internal/dedup`/
  `mail/internal/indexworker`/`mail/internal/search` unverändert;
  bestehende ARC-02-Tests (`encstorage_test.go`) unverändert lauffähig
  ohne Codeänderung an ihnen.

## Prüfungen

| # | Prüfung | Ergebnis |
|---|---|---|
| 1 | Test: Rotation des Hauptschlüssels lässt Altbestand weiterhin lesbar | **bestanden** – `TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation`: Objekt vor Rotation versiegelt (Version 1), Tenant-Hauptschlüssel real rotiert (Provider liefert ab dann einen anderen Wert, exakt wie `RotateTenantKEK` es bei Core bewirkt), neues Objekt nach Rotation versiegelt (Version 2), Altbestand über `OpenAtVersion` real weiterhin korrekt entschlüsselt — zusätzlich real bestätigt, dass der naive `Open()` mit dem neuen aktuellen KEK für das alte Objekt fehlschlägt (beweist, dass `OpenAtVersion` tatsächlich etwas leistet) |
| 2 | Test: kompromittierter alter Schlüssel kann gezielt gesperrt werden | **bestanden** – `TestRotation_CompromisedOldKeyCanBeRevoked`: Version gesperrt, `OpenAtVersion` liefert danach real `ErrKEKVersionRevoked`; `TestKEKVersionStore_RevokeBlocksOnlyThatVersion` bestätigt zusätzlich, dass eine ANDERE Version davon unberührt bleibt |
| 3 | Dokumentierter Rotationsvorgang wurde einmal vollständig durchgespielt | **bestanden** – siehe Abschnitt "Rotationsvorgang" unten, real durchlaufen als `TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation` |

### Rotationsvorgang (Pflichtprüfung 3, vollständig durchgespielt)

1. Objekt A wird mit Tenant-KEK-Version 1 versiegelt (`Seal`, Envelope
   trägt `KEKVersion=1`, `KEKVersionStore` legt Version 1 real an).
2. Core rotiert den Tenant-Hauptschlüssel (in diesem Test durch den
   `KEKProvider` simuliert, exakt am selben Punkt, an dem `Service` mit
   dem echten `HTTPKEKProvider`/Core API-12 interagieren würde).
3. Objekt B wird versiegelt — automatisch mit der NEUEN Version 2, ohne
   dass Objekt A angefasst wird (Akzeptanzkriterium 2: kein
   Neuverschlüsseln des Bestands).
4. Objekt A wird über `OpenAtVersion(..., kekVersion=1, ...)` gelesen —
   real erfolgreich, Klartext identisch zum Original.
5. Ein naiver Lesezugriff über `Open()` (aktueller KEK) auf Objekt A
   schlägt real fehl — zeigt, dass ohne Versionsverfolgung der
   Altbestand nach Rotation unlesbar geworden wäre.

## Build/Test-Ergebnis (192.168.1.131)

```
go build ./...  -> clean
go vet ./...    -> clean
golangci-lint run ./...  -> 0 issues
TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
TEST_MANTICORE_URL=http://127.0.0.1:9308 \
  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/crypto (4 Tests, neu)
  und internal/encstorage (4 Tests, unverändert weiterhin grün — Rückwärtskompatibilität
  real bestätigt)
```

## Gesamtergebnis

**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
real erfüllt. Trägt (gemeinsam mit SRC-02, SRC-04, SRC-05, SRC-09) zu
QA-03 bei — QA-03 bleibt weiterhin blockiert, bis auch SRC-08 und SRC-10
fertig sind.