docs(architecture): clarify PII-Store is a role, not a product; add dedicated section 8.4 with technology choice

This commit is contained in:
CTO Agent 2026-10-25 14:57:00 +00:00
parent fddce4d0fb
commit 989140ee88

View file

@ -31,6 +31,7 @@ Diese Revision setzt die Richtungsentscheidungen der bisherigen Review-Runden um
- **🆕 Datenquellen und paralleler Lesepfad:** Agenten holen während der Vorbereitung Informationen aus registrierten **Datenquellen** (Section 3b, 4.5a) über das gleiche Vertrauens- und Autorisierungsmodell wie bei Senken. Jede Abfrage erzeugt eine **Query Attestation**; die Benutzerfreigabe bindet an diese Query-Materialien. - **🆕 Datenquellen und paralleler Lesepfad:** Agenten holen während der Vorbereitung Informationen aus registrierten **Datenquellen** (Section 3b, 4.5a) über das gleiche Vertrauens- und Autorisierungsmodell wie bei Senken. Jede Abfrage erzeugt eine **Query Attestation**; die Benutzerfreigabe bindet an diese Query-Materialien.
- **🆕 Session Scope Tokens:** Session-gebundene, kurzlebige Delegations-Tokens, mit denen Agenten „im Auftrag von Benutzer X in Session S" lesen dürfen. Siehe Abschnitt 3c. - **🆕 Session Scope Tokens:** Session-gebundene, kurzlebige Delegations-Tokens, mit denen Agenten „im Auftrag von Benutzer X in Session S" lesen dürfen. Siehe Abschnitt 3c.
- **🆕 Erster produktiver Rollout:** **eigene kleine Go-DB-App** (`sink:expense-db-app` + `ds:expense-db-app`) als kombinierte Quelle und Senke. SAP folgt später. - **🆕 Erster produktiver Rollout:** **eigene kleine Go-DB-App** (`sink:expense-db-app` + `ds:expense-db-app`) als kombinierte Quelle und Senke. SAP folgt später.
- **🆕 Begriffsklärung PII-Store:** Der Begriff bezeichnet eine **Rolle im Datenmodell**, kein Produkt. Konkrete Technologie-Wahl und Löschsemantik stehen in Abschnitt 8.4.
## 1. Zielarchitektur ## 1. Zielarchitektur
@ -72,7 +73,7 @@ Senken sind nach außen offene Zielsysteme — ERP, eigene Datenbankanwendungen,
| Senken-Adapter | pro Senke; siehe Abschnitt 7 | Übersetzt verifizierte Decision in Senken-Aktion | | Senken-Adapter | pro Senke; siehe Abschnitt 7 | Übersetzt verifizierte Decision in Senken-Aktion |
| **Datenquellen-Adapter** | **pro Quelle; siehe Abschnitt 7a** | **Prüft Scope-Token + Policy, führt Query aus, erzeugt Query Attestation** | | **Datenquellen-Adapter** | **pro Quelle; siehe Abschnitt 7a** | **Prüft Scope-Token + Policy, führt Query aus, erzeugt Query Attestation** |
| Evidence Store | PostgreSQL (Metadaten) + S3 | DSSE-Envelopes und Attestate (Retention: 1 Jahr) | | Evidence Store | PostgreSQL (Metadaten) + S3 | DSSE-Envelopes und Attestate (Retention: 1 Jahr) |
| PII-Store | Verschlüsselt in S3 | Belege, Geschäftsdaten UND Query-Ergebnisse mit PII — redaktionierbar | | PII-Store (Rolle) | Verschlüsselter S3-Bucket + Mediator-Service | Belege, Geschäftsdaten UND Query-Ergebnisse mit PII — redaktionierbar. **Rolle, kein Produkt** — Details Abschnitt 8.4 |
Approval, Session Scope Token Service, Attestation, Registry (Agent + Sink + Data Source) und Verification laufen in **einem modularen Go-Dienst** (`trust-api`). Signing Service läuft als eigenes Deployment. Senken- und Datenquellen-Adapter laufen pro Typ (oft als derselbe Prozess, wenn eine Komponente beides anbietet — siehe 7.2). Approval, Session Scope Token Service, Attestation, Registry (Agent + Sink + Data Source) und Verification laufen in **einem modularen Go-Dienst** (`trust-api`). Signing Service läuft als eigenes Deployment. Senken- und Datenquellen-Adapter laufen pro Typ (oft als derselbe Prozess, wenn eine Komponente beides anbietet — siehe 7.2).
@ -623,6 +624,63 @@ Query-Ergebnisse mit PII landen immer im PII-Store. Löschung dort invalidiert *
Append-only Merkle-Log mit Inclusion Proofs. Cassandra ist dafür ungeeignet (siehe V1.1 Erstfassung). Append-only Merkle-Log mit Inclusion Proofs. Cassandra ist dafür ungeeignet (siehe V1.1 Erstfassung).
### 8.4 Was ist der PII-Store konkret?
**Begriffsklärung.** „PII" steht für *Personally Identifiable Information* (deutsch: personenbezogene Daten im Sinne der DSGVO Art. 4 Nr. 1). „PII-Store" ist **kein Produktname und keine Technologie**, sondern eine **architektonische Rolle** in unserem Datenmodell. Das Muster — personenbezogene Daten in einem *dedizierten, löschbaren* Speicher getrennt vom unveränderlichen Nachweismaterial zu halten — ist in Privacy-Engineering-Literatur unter Namen wie „PII vault", „tokenization vault" oder „data minimization layer" bekannt (siehe NIST SP 800-188 „De-Identifying Government Datasets" oder ENISA „Pseudonymisation techniques and best practices").
**Warum wir die Rolle brauchen.** Wir müssen zwei scheinbar widersprüchliche Anforderungen gleichzeitig erfüllen:
- **Nachweiskette darf nicht geändert werden** — eine Signaturkette, deren Inhalte nachträglich veränderbar sind, ist nutzlos.
- **DSGVO Art. 17 „Recht auf Löschung"** — personenbezogene Daten müssen auf Antrag entfernt werden können.
Lösung: wir trennen *Nachweis* und *Nutzinhalt* physisch:
- Der **Evidence Store** hält DSSE-Envelopes, Attestierungen, Transparency-Log-Einträge und Hashes. Dieser Speicher ist für die Dauer der Retention unveränderlich.
- Der **PII-Store** hält die eigentlichen Nutzinhalte (Reisekostenbelege, Dateien, Query-Ergebnisse mit Personen- oder Projektdaten). Dieser Speicher ist pro Vorgang und pro Betroffenem löschbar.
Löscht man im PII-Store, bleibt die Signaturkette intakt — nur die Nachkontrolle gegen den Inhalt ist dann nicht mehr möglich. Das ist der bewusste Trade-off: Löschbarkeit gewinnt gegenüber Nachkontrolle, der *Beweis der Kommunikation an sich* bleibt bestehen.
**Konkrete Technologie-Wahl für ProofedMesh (Default).** Der PII-Store wird aus zwei Bausteinen gebaut, die wir bereits im Cluster haben:
1. **Verschlüsselter Hetzner Object Storage (S3-kompatibel), eigener Bucket.** Jeder Workflow bekommt ein eigenes Prefix (`pii/<workflow_id>/…`). Der Bucket hat keine öffentlichen ACLs; Zugriff nur per Service-Account aus unserem Cluster.
2. **PII-Mediator-Service** (kleine Go-Komponente). Alle anderen Dienste (Approval, Datenquellen-Adapter, Senken-Adapter, Verifikations-UI) sprechen **nur** mit dem Mediator, nie direkt mit S3. Der Mediator:
- vergibt pro Objekt einen Datenschlüssel (envelope-encrypted über OpenBao Transit — der eigentliche Objektschlüssel liegt nicht im Mediator),
- prüft bei jedem Zugriff: Token, Scope, OPA-Policy,
- führt ein Zugriffs-Audit (`workflow_id`, `agent_id`/`user_sub`, `operation`, `created_at`),
- exekutiert Löschungen (Objekt löschen + Transit-Schlüssel vergessen → Cryptographic Erasure).
Dadurch ergibt sich automatisch ein **doppeltes Löschen**: Objekt entfernt UND Entschlüsselungsschlüssel vergessen. Beides muss gelingen, aber jedes einzelne davon reicht bereits, um die Daten unlesbar zu machen.
**Was im PII-Store liegt (vs. was NICHT dort liegt):**
| Datenart | PII-Store? | Alternativer Ort |
| -------------------------------------------------------- | ---------- | ----------------------------- |
| Reisekostenbelege (PDF, Scan) | ja | — |
| Kanonische Reisekostendaten (`expense.canonical`) | ja | — |
| Query-Ergebnisse mit Namen/Kostenstellen/Projektzuordnungen | ja | — |
| DSSE-Envelopes (nur Hashes) | **nein** | Evidence Store (S3, Retention 1 Jahr) |
| Transparency-Log-Einträge | **nein** | Trillian + Postgres |
| Agent-/Session-Schlüsselmaterial | **nein** | OpenBao Transit, Agent Registry |
| Workflow-Status, Decision-IDs, Referenzen | **nein** | `trust-postgres` |
**Retention und Löschsemantik.**
- Default-Retention: **1 Jahr nach letzter Workflow-Aktivität** (identisch zu Evidence Store), danach automatisches Löschen durch Cron-Job.
- Vorzeitige Löschung auf Antrag eines Betroffenen (DSGVO Art. 17): PII-Mediator ruft `DELETE /pii/<workflow_id>` → S3-Objekte entfernen + Transit-Keys vergessen + Audit-Zeile schreiben. Die Signaturkette im Evidence Store wird NICHT angerührt.
- Löschprotokoll: der Mediator schreibt eine signierte **Deletion-Attestierung** in den Transparency Log (`predicateType=https://basicstack.de/attestations/pii_deletion/v1`), damit später nachweisbar ist „zu diesem Workflow waren PII-Daten vorhanden und wurden am Datum X auf Antrag Y gelöscht".
**Alternativen, die wir bewusst nicht wählen (Begründung).**
| Alternative | Warum nicht (für den Start) |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Keine Trennung**, PII in den DSSE-Payloads | Macht DSGVO Art. 17 unlösbar — die Signaturkette müsste bei jeder Löschung invalidiert werden. |
| Kommerzielle PII-Vaults (Skyflow, Piiano, VGS) | Externer Dienst, Vendor-Lock-in, Kosten; keine Zusatzgarantien, die wir für den geplanten Scope brauchen. |
| Dedizierte Postgres-Instanz mit TDE | Löschbarkeit braucht Zusatzlogik; kein nennenswerter Vorteil gegenüber verschlüsseltem Object Storage für Blob-PII. |
| OpenBao Transform Engine (Format-Preserving Encryption) | Lohnt sich bei strukturierten Feldern (z.B. Kreditkarten) in einer bestehenden App — Overhead für unsere Use Cases. |
| Confidential Computing (TEE/SGX) | Overkill und derzeit auf Hetzner nicht in der Variante verfügbar, die wir brauchen würden. |
**Begrifflichkeit im weiteren Doc.** Wo bisher „PII-Store" steht, ist jeweils diese Rolle gemeint — konkret implementiert als „verschlüsselter S3-Bucket + PII-Mediator-Service". Wenn wir später z.B. Confluence-Export oder Teams-Daten anbinden, bleibt der Begriff gleich; nur der Mediator bekommt zusätzliche Backend-Adapter.
## 9. Deployment in Kubernetes ## 9. Deployment in Kubernetes
``` ```