diff --git a/docs/architecture/v1.1.md b/docs/architecture/v1.1.md index 4118d51..16f3bd7 100644 --- a/docs/architecture/v1.1.md +++ b/docs/architecture/v1.1.md @@ -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. - **🆕 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. +- **🆕 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 @@ -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 | | **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) | -| 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). @@ -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). +### 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//…`). 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/` → 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 ```