docs(adr): add ADR template and ADR-0001..0003 (DB-App scope, session scope tokens, PII retention)

2026-10-25 15:11:23 +00:00 · 2026-10-25 15:11:23 +00:00 · a9c853f881
commit a9c853f881
parent 30939b777a
5 changed files with 328 additions and 0 deletions
--- a/docs/adr/0000-template.md
+++ b/docs/adr/0000-template.md
@ -0,0 +1,42 @@
+# ADR-XXXX: Kurztitel
+
+- **Status:** proposed | accepted | superseded by ADR-YYYY | deprecated
+- **Datum:** YYYY-MM-DD
+- **Entscheider:** <Namen oder Rollen>
+- **Betroffene Dokumente:** <z.B. docs/architecture/vX.Y.md Abschnitt N>
+
+## Kontext und Problemstellung
+
+<Welches Problem lösen wir? Welche Kräfte wirken?>
+
+## Entscheidungsoptionen
+
+- Option A: <kurz>
+- Option B: <kurz>
+- Option C: <kurz>
+
+## Entscheidung
+
+<Welche Option wird gewählt? Ein Satz plus Begründung.>
+
+### Begründung
+
+<Warum diese Option gegenüber den anderen? Welche Kriterien haben entschieden?>
+
+## Konsequenzen
+
+### Positive
+
+- <...>
+
+### Negative / Trade-offs
+
+- <...>
+
+### Folgearbeiten / Open Points
+
+- <...>
+
+## Links
+
+- <PRs, Issues, externe Referenzen>
--- a/docs/adr/0001-first-rollout-db-app-scope.md
+++ b/docs/adr/0001-first-rollout-db-app-scope.md
@ -0,0 +1,55 @@
+# ADR-0001: Erster produktiver Rollout — eigene DB-App als Senke UND Datenquelle
+
+- **Status:** accepted
+- **Datum:** 2026-10-25
+- **Entscheider:** CEO (A. Leinen), CTO
+- **Betroffene Dokumente:** `docs/architecture/v1.1.md` Abschnitte 7.2, 10 (Phase 4), 12
+
+## Kontext und Problemstellung
+
+ProofedMesh soll in einem ersten produktiven Durchlauf einen vollständig attestierten Reisekostenprozess abbilden: Benutzer wählt im Chat ein Projekt, Agenten holen Vorab-Infos und bauen eine Buchungsnutzlast, eine Senke übernimmt. Der Trust-Core (Approval, Signing, Verification, OPA, Trillian) muss sich dabei einmal end-to-end gegen echte Komponenten beweisen.
+
+Zwei Fragen sind zu entscheiden: (1) *Welche Senke* ist die erste produktive? (2) *Wo* holen Agenten ihre Vorab-Lesedaten?
+
+## Entscheidungsoptionen
+
+- **Option A — SAP S/4HANA zuerst** (Senke + evtl. OData als Datenquelle).
+- **Option B — eigene kleine Go-DB-App** als Senke `sink:expense-db-app` und Datenquelle `ds:expense-db-app` im selben Prozess.
+- **Option C — HTTP-Webhook an einen externen Dritt-Dienst** als Senke, kein eigener Datenquellen-Dienst.
+
+## Entscheidung
+
+**Option B.** Wir bauen eine kleine Go-DB-App (`expense-db-adapter` + `expense-db-postgres`), die zugleich Senke und Datenquelle ist, und nutzen sie für den ersten produktiven Rollout.
+
+### Begründung
+
+- **Kleinster Blast Radius.** Fehler im Trust-Core gefährden hier nur unsere eigene Instanz, keinen produktiven SAP-Mandanten.
+- **Schema-Hoheit bei uns.** Wir können `expense.canonical`, `ds.expense.project_assignment` und `sink.db.expense` so modellieren, wie es für den sauberen Durchlauf gebraucht wird; keine Rücksicht auf vorhandene ERP-Felder in Runde 1.
+- **Deckt beide Pfade in einem Adapter.** Lesepfad (project_assignments, account_assignments, cost_centers) und Schreibpfad (expenses) teilen Postgres-Instanz und Sitzungskontext — der Adapter kann in einer Transaktion gegenlesen, was er geschrieben hat, und die Testabdeckung wird trivial.
+- **Kein externer Vertrauensanker.** Keine externen Tokens, keine externe Replay-Tabelle, keine SM59-Rotation in Runde 1. Jede Komponente läuft in unserem Cluster.
+- **Lieferbar in Wochen, nicht Monaten.** SAP-Integration (Option A) hat eigene Produktentscheidungen offen (Travel Management vs. Concur vs. kundeneigener FI-Prozess, siehe `docs/architecture/v1.1.md` 7.1). Diese Entscheidung können wir treffen, nachdem der Trust-Kern bewiesen ist.
+
+Option C scheidet aus: ohne Datenquellen-Komponente in Runde 1 bleibt der parallele Lesepfad ungetestet, und Attestierungen mit `read_materials` sind der kryptografisch anspruchsvollere Teil.
+
+## Konsequenzen
+
+### Positive
+
+- Phase 4 im Phasenplan hat einen klaren Scope mit einem einzigen Deployment (`expense-db-adapter`).
+- Wir können den Adapter-Vertrag aus `docs/architecture/v1.1.md` 7.0 und 7a.0 an einer realen Komponente härten, bevor wir SAP (`sap_abap`) oder generische Webhooks angehen.
+- Das Datenmodell der DB-App ist klein und publishable — es dient später als Referenz für Partner, die eine ähnliche Senke anbinden wollen.
+
+### Negative / Trade-offs
+
+- SAP-Buchung schiebt sich auf Phase 6. Bis dahin müssen Reisekosten entweder im Zweistromverfahren (DB-App parallel zu SAP, keine Freigabe-Automatisierung in SAP) oder manuell nachgebucht werden.
+- Wir bauen ein Business-Datenmodell neben SAP auf, das wir später konsolidieren müssen. Risiko eines Doppelstammdatens; wird in späterer ADR adressiert.
+
+### Folgearbeiten / Open Points
+
+- ADR zur Rolle der DB-App gegenüber SAP (Spiegelung vs. zweite autoritative Quelle).
+- ADR zur SAP-Buchungsschnittstelle (Travel Management vs. Concur vs. kundeneigener FI-Prozess), spätestens vor Phase-6-Start.
+
+## Links
+
+- `docs/architecture/v1.1.md` Abschnitte 7.2, 10, 12
+- Thread auf [DEV-598](/BAS/issues/DEV-598)
--- a/docs/adr/0002-session-scope-token-format.md
+++ b/docs/adr/0002-session-scope-token-format.md
@ -0,0 +1,103 @@
+# ADR-0002: Session-Scope-Token-Format
+
+- **Status:** accepted
+- **Datum:** 2026-10-25
+- **Entscheider:** CTO
+- **Betroffene Dokumente:** `docs/architecture/v1.1.md` Abschnitte 3c, 4.5a, 5.1, 6, 7a.0, 9.1
+
+## Kontext und Problemstellung
+
+Ein Agent, der eine Datenquelle liest, muss ihr beweisen, dass er für Benutzer Y in einer aktiven Session S liest — nicht nur, dass er irgendein Agent ist. Ohne diesen Nachweis gibt es keine saubere Grundlage für OPA-Regeln wie „Agent-Travel darf nur `project_assignments` seines eigenen Benutzers lesen, nicht fremder". Pocket ID allein liefert nur Agent-Identität (via `client_credentials`), keine Benutzer-Delegation.
+
+## Entscheidungsoptionen
+
+- **Option A — Vollständiger OAuth 2.0 Token Exchange (RFC 8693) in Pocket ID.** Agent macht Token-Exchange gegen Pocket ID; dieser prüft Session und mintet ein Delegations-Token mit `act`-Claim.
+- **Option B — Eigener Session Scope Token Service (SSTS) in `trust-api`.** Agent präsentiert Pocket-ID-Access-Token + K8s-SA-Token; SSTS prüft doppelt, konsultiert OPA, stellt kurzlebigen JWT mit `act`-Claim aus, signiert mit eigenem Ed25519-Schlüssel. Datenquellen-Adapter validieren per JWKS offline.
+- **Option C — Opaque Bearer Tokens mit zentralem Introspection-Endpunkt.** Datenquellen rufen bei jedem Request `POST /introspect` am trust-api.
+
+## Entscheidung
+
+**Option B.** Der Session Scope Token Service läuft als Modul in `trust-api` und stellt JWTs im Format gemäß Anhang A dieser ADR aus, signiert mit einem eigenen Ed25519-Schlüssel.
+
+### Begründung
+
+- **Pocket ID macht keinen RFC-8693-Flow.** Der Check im Pocket-ID-OIDC-Discovery zeigt `client_credentials`, aber keinen `urn:ietf:params:oauth:grant-type:token-exchange`. Option A würde Pocket ID erweitern müssen oder einen zweiten IdP aufbauen — beides nicht gewünscht (siehe `docs/architecture/v1.1.md` 3a).
+- **Offline-Validierung ist wichtig.** Datenquellen-Adapter sollen Tokens ohne Round-Trip zum trust-api prüfen können — JWKS + signierter JWT reichen. Option C erzwingt eine Netzwerkrunde pro Lese-Request und bindet Datenquellen-Verfügbarkeit an trust-api-Verfügbarkeit.
+- **OPA-Entscheidung bleibt zentral.** Der SSTS konsultiert OPA genau einmal beim Ausstellen, nicht pro Query. Rego-Policies müssen nur im trust-api deployed sein.
+
+## Entscheidung — Anhang A: Token-Format
+
+Header:
+```json
+{ "alg": "EdDSA", "typ": "JWT", "kid": "sst-2026-q4" }
+```
+
+Payload (Claims):
+```json
+{
+  "iss": "https://trust.basicstack.de",
+  "sub": "agent-travel",
+  "act": {
+    "iss": "https://auth.basicstack.de",
+    "sub": "user-12345",
+    "session_id": "SES-2026-10-25-abc"
+  },
+  "aud": "ds:expense-db-app",
+  "scope": {
+    "data_source": "ds:expense-db-app",
+    "resource": "project_assignments",
+    "filters": { "employee_id": "EMP-12345" },
+    "operation": "read"
+  },
+  "jti": "01HE2D3V6X7Y8Z9ABCDEFG",
+  "iat": 1735120000,
+  "exp": 1735120300,
+  "nbf": 1735120000,
+  "policy_version": "sha256:<rego-bundle-digest>"
+}
+```
+
+Semantik:
+- `iss` = feste trust-api-Issuer-URL.
+- `sub` = `agent_id` (OIDC-Client-Name in Pocket ID + Eintrag in Agent Registry).
+- `act` = Delegations-Kontext nach RFC 8693 §4.1 (Semantik, nicht der volle Flow). `act.sub` ist der Benutzer, `act.session_id` die Approval-Service-Session.
+- `aud` = genau *eine* Zieldatenquelle. Mehrere Datenquellen → mehrere Tokens.
+- `scope` = engster erlaubter Scope. Datenquellen-Adapter MUSS `scope` strikt gegen Request matchen (keine erweiterten Filter, keine zusätzlichen Resources).
+- `jti` = ULID oder UUID. Datenquellen-Adapter führen `scope_token_log` mit `UNIQUE (data_source_id, jti)` als optionalen Replay-Schutz zusätzlich zur `exp`-Prüfung.
+- `exp` − `iat` = **≤ 300 Sekunden** (5 Minuten). Begründung: Agenten holen Tokens pro Query, nicht pro Session.
+- `nbf` = `iat`.
+- `policy_version` = SHA-256 des zur Entscheidungszeit aktiven OPA-Rego-Bundles. Wandert später in die Query Attestation für Nachvollziehbarkeit.
+
+Signatur: Ed25519. Schlüsselmaterial liegt in OpenBao Transit (`transit/keys/session-scope-token-signer`), rotiert alle 90 Tage. JWKS unter `https://trust.basicstack.de/.well-known/jwks.json`.
+
+### Begründung Detailentscheidungen
+
+- **EdDSA statt RS256.** Konsistent zum restlichen Signatur-Stack (DSSE / in-toto nutzen Ed25519).
+- **5-Minuten-TTL.** Lang genug für Chat-Interaktionen mit einer Datenquelle; kurz genug, dass ein geleakter Token begrenzten Schaden anrichtet. Agenten holen bei Bedarf einen neuen; `/session-scope-tokens` ist bewusst billig.
+- **`scope.filters` ist Teil des Tokens.** Alternative wäre „offene" Reads mit späterer Filterprüfung — würde aber erlauben, dass ein Agent erst eine breite Query stellt und dann nur bestimmte Zeilen weitergibt. Mit Filter im Token geht das nicht; die Query Attestation beweist zudem die gefilterten Parameter.
+- **`aud = ds:...`.** Explizite Audience bindet den Token an *eine* Datenquelle. Verhindert, dass ein Token bei anderen Datenquellen „probiert" wird.
+
+## Konsequenzen
+
+### Positive
+
+- OPA-Policies werden einmal pro Scope-Request ausgewertet, nicht pro Query-Zeile.
+- Datenquellen können offline (ohne trust-api) authorisieren — bessere Entkopplung, besseres Fehlerverhalten.
+- Delegationskette ist in Attestierungen vollständig nachvollziehbar: `session_scope_token_jti` zeigt zurück auf Token-Ausstellung, die wiederum OPA-Policy-Version trägt.
+
+### Negative / Trade-offs
+
+- Zusätzliche Signatur-Round-Trip (Agent → `/session-scope-tokens`) pro Lese-Operation. Bei chattigen Workflows mit vielen kleinen Queries ggf. relevant — eine spätere ADR könnte Scope-Token mit mehreren erlaubten Resources diskutieren.
+- Datenquellen-Adapter brauchen JWT-Validierungs-Bibliotheken (für Go: trivial, `github.com/go-jose/go-jose`).
+
+### Folgearbeiten / Open Points
+
+- Client-Library (Go) für Agenten mit Caching eines Scope-Tokens bis `exp - 30s`.
+- Rego-Testsuite für die drei Policy-Klassen (Transformation, Senke, Datenquelle).
+- Monitoring: Rate von Scope-Token-Ausstellungen pro Agent/Benutzer; Anomalie-Erkennung.
+
+## Links
+
+- `docs/architecture/v1.1.md` Abschnitte 3c, 4.5a, 5.1, 6, 7a.0, 9.1
+- RFC 8693 (OAuth 2.0 Token Exchange)
+- Pocket ID OIDC Discovery: `https://auth.basicstack.de/.well-known/openid-configuration`
--- a/docs/adr/0003-pii-retention-policy.md
+++ b/docs/adr/0003-pii-retention-policy.md
@ -0,0 +1,108 @@
+# ADR-0003: PII-Retention-Richtlinie
+
+- **Status:** accepted
+- **Datum:** 2026-10-25
+- **Entscheider:** CEO (A. Leinen), CTO
+- **Betroffene Dokumente:** `docs/architecture/v1.1.md` Abschnitte 8.1, 8.2, 8.4
+
+## Kontext und Problemstellung
+
+Der PII-Store (siehe `docs/architecture/v1.1.md` 8.4) hält personenbezogene Daten (Belege, kanonische Reisekostendaten, Query-Ergebnisse mit Namen und Zuordnungen) getrennt vom Evidence Store. Dieser muss zwei Anforderungen gleichzeitig erfüllen:
+
+1. **DSGVO Art. 17 „Recht auf Löschung"** — Betroffene müssen ihre personenbezogenen Daten löschen lassen können.
+2. **Kryptografischer Nachweis einer unverfälschten Kommunikation während eines sinnvollen Zeitraums** — Attestierungen müssen Nachkontrollen gegen den Originalinhalt erlauben, solange ein berechtigtes Interesse besteht.
+
+Festzulegen: wie lange halten wir PII-Daten auf, wann wird gelöscht, wie wird eine vorzeitige Löschung ausgeführt, und wie wird die Löschung ihrerseits nachweisbar?
+
+## Entscheidungsoptionen
+
+- **Option A — Default-Retention 1 Jahr, mit konfigurierbarer Verkürzung pro Prozess-Typ.** Nach Ablauf automatische Cryptographic Erasure. Betroffene können jederzeit vorzeitige Löschung beantragen.
+- **Option B — Default-Retention 90 Tage** — kürzer, aber möglicherweise zu kurz für realistische Nachprüfungen (Jahresabschluss, interne Audits).
+- **Option C — Default-Retention 3 Jahre** — richtet sich an GoBD-Fristen aus; widerspricht aber der grundsätzlichen Entscheidung „kein rechtssicheres Archiv" (ADR-0001 bzw. `docs/architecture/v1.1.md` 8.1).
+
+## Entscheidung
+
+**Option A.**
+
+Konkrete Regeln:
+
+### Default-Retention
+
+- **1 Jahr** ab letzter Workflow-Aktivität (letzte Attestierung, Decision oder Deletion-Anfrage, je nachdem was später ist).
+- Konfigurierbar **pro Prozess-Typ** (`workflow_type.retention_days`) und **pro Senke/Datenquelle** (`sinks.retention_days`, `data_sources.retention_days`), jeweils als Default-Override.
+- Minimum: 30 Tage (unter diesem Wert ist kein Review mehr sinnvoll). Maximum: 2 Jahre (darüber kippt die „kein rechtssicheres Archiv"-Positionierung).
+
+### Automatische Löschung
+
+- Cron-Job `pii-retention-sweeper` läuft **täglich 03:30 UTC**.
+- Für jeden Workflow mit `last_activity_at + retention_days < NOW()`:
+  1. Alle PII-Objekte des Workflows aus dem S3-Bucket entfernen.
+  2. Alle Envelope-Keys im OpenBao Transit vergessen (Cryptographic Erasure).
+  3. Eine signierte **PII-Deletion-Attestierung** in den Transparency Log schreiben (`predicateType=https://basicstack.de/attestations/pii_deletion/v1`).
+  4. Workflow-Status auf `pii_purged` setzen; der Evidence-Store-Eintrag bleibt bestehen.
+
+### Vorzeitige Löschung auf Antrag
+
+- Endpunkt `DELETE /pii/<workflow_id>` am PII-Mediator mit Admin-Auth.
+- Zusätzlich: Endpunkt `DELETE /pii/by-subject/<user_sub>` löscht alle Workflows, in denen der angegebene Benutzer `original_user.sub` ist. Für DSGVO-Antragsabwicklung.
+- Ablauf identisch zur automatischen Löschung (Schritte 1–4 oben).
+
+### Löschung-vs-Signaturkette
+
+- Signaturkette im Evidence Store wird **nicht** angerührt.
+- Hashes in Attestierungen bleiben prüfbar; Nachkontrolle gegen den Inhalt ist nach Löschung nicht mehr möglich — das ist der bewusste Trade-off.
+- Verification Service markiert Verifikationsantworten, deren materials-Hashes nicht mehr im PII-Store auflösbar sind, mit `content_check: "pii_purged"` (statt `pii_matched`).
+
+### PII-Deletion-Attestierung (neue predicate)
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    { "name": "pii/<workflow_id>", "digest": { "sha256": "<hash of deleted objects manifest>" } }
+  ],
+  "predicateType": "https://basicstack.de/attestations/pii_deletion/v1",
+  "predicate": {
+    "workflow_id": "WF-...",
+    "deletion_reason": "retention_policy_expired" | "subject_erasure_request" | "operator_action",
+    "deleted_objects": [ { "pii_store_ref": "pii://...", "content_hash_before_delete": "sha256:..." } ],
+    "requested_by": { "iss": "...", "sub": "..." },
+    "deleted_at": "YYYY-MM-DDTHH:MM:SSZ",
+    "retention_policy_version": "pii-retention-v1"
+  }
+}
+```
+
+Signiert vom PII-Mediator-Adapter (`agent_id = "pii-mediator"`), landet im Transparency Log.
+
+## Begründung
+
+- **1 Jahr trifft den Sweet Spot.** Länger als ein interner Audit-Zyklus (meist quartalsweise); kurz genug, dass wir nicht in GoBD-Territorium rutschen; akzeptabel für Betroffene (vgl. gängige SaaS-Retention bei Log-Daten).
+- **Pro-Typ-Konfigurierbarkeit** erlaubt es, z.B. Debugging-Workflows auf 30 Tage und besonders sensible Workflows auf das Minimum zu drücken.
+- **Deletion-Attestierung** schließt die Nachweislücke „zu diesem Workflow waren PII-Daten vorhanden und wurden am X auf Antrag Y gelöscht". Ohne diese Attestierung wäre Löschen und Nichthaben nachträglich nicht unterscheidbar.
+- **Automatische Löschung über Cron**, nicht erst auf Zugriff — damit garantieren wir, dass PII tatsächlich verschwindet und nicht erst durch Zufall irgendwann einmal.
+
+## Konsequenzen
+
+### Positive
+
+- DSGVO-Anfragen können technisch binnen Minuten abgearbeitet werden (vorzeitiger `DELETE`).
+- Datenwachstum im PII-Store ist bounded.
+- Deletion-Nachweis selbst ist kryptografisch (nicht nur Audit-Log).
+
+### Negative / Trade-offs
+
+- Fehlbedienung oder Scheduler-Bug kann Daten einen Tag zu früh löschen — Verification-Antworten dieser Workflows werden dann `content_check: "pii_purged"`. Mitigation: Dry-Run-Modus im Sweeper mit Warnung an Operator, bevor der echte Lauf greift.
+- OpenBao-Transit-Key-Vergessen ist unwiderruflich — Backup-Strategie muss sicherstellen, dass vergessene Keys nicht aus einem alten Backup zurückkehren. Siehe Folgearbeit.
+
+### Folgearbeiten / Open Points
+
+- Policy für Backup-Rotation: OpenBao-Snapshots dürfen nicht länger als `retention_days + 7` aufgehoben werden, damit vergessene Keys nicht wiederauftauchen.
+- Datenschutz-Dokument (für Benutzer-Information und AV-Vertrag) muss die 1-Jahres-Retention explizit benennen.
+- Monitoring: tägliche Metrik für Anzahl gelöschter Workflows + Alert, wenn Sweeper nicht läuft.
+
+## Links
+
+- `docs/architecture/v1.1.md` Abschnitte 8.1, 8.2, 8.4
+- DSGVO Art. 17
+- OpenBao Transit docs (Key Rotation + Delete)
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@ -0,0 +1,20 @@
+# Architecture Decision Records (ADRs)
+
+Dieses Verzeichnis dokumentiert durchlebte Architekturentscheidungen in [MADR-Form](https://adr.github.io/madr/). Jede ADR ist dauerhaft: einmal akzeptiert, wird sie nicht mehr editiert. Änderungen entstehen als neue ADR mit `supersedes`-Verweis.
+
+## Status-Werte
+
+- `proposed` — vorgeschlagen, Entscheidung steht noch aus
+- `accepted` — in Kraft
+- `superseded` — durch eine spätere ADR ersetzt (Verweis im Dokument)
+- `deprecated` — nicht mehr empfohlen, aber nicht offiziell ersetzt
+
+## Index
+
+| Nummer | Titel                                                                 | Status     |
+| ------ | --------------------------------------------------------------------- | ---------- |
+| 0001   | [Erster produktiver Rollout: eigene DB-App als Senke und Datenquelle](0001-first-rollout-db-app-scope.md) | accepted   |
+| 0002   | [Session-Scope-Token-Format](0002-session-scope-token-format.md)       | accepted   |
+| 0003   | [PII-Retention-Richtlinie](0003-pii-retention-policy.md)               | accepted   |
+
+Vorlage: [`0000-template.md`](0000-template.md).