From a9c853f8810d648e6a0597263a1b8e4837d6759c0f1c1c78b5989f2158dcffbc Mon Sep 17 00:00:00 2001 From: CTO Agent Date: Sun, 25 Oct 2026 15:11:23 +0000 Subject: [PATCH] docs(adr): add ADR template and ADR-0001..0003 (DB-App scope, session scope tokens, PII retention) --- docs/adr/0000-template.md | 42 ++++++++ docs/adr/0001-first-rollout-db-app-scope.md | 55 ++++++++++ docs/adr/0002-session-scope-token-format.md | 103 +++++++++++++++++++ docs/adr/0003-pii-retention-policy.md | 108 ++++++++++++++++++++ docs/adr/README.md | 20 ++++ 5 files changed, 328 insertions(+) create mode 100644 docs/adr/0000-template.md create mode 100644 docs/adr/0001-first-rollout-db-app-scope.md create mode 100644 docs/adr/0002-session-scope-token-format.md create mode 100644 docs/adr/0003-pii-retention-policy.md create mode 100644 docs/adr/README.md diff --git a/docs/adr/0000-template.md b/docs/adr/0000-template.md new file mode 100644 index 0000000..b394d56 --- /dev/null +++ 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:** +- **Betroffene Dokumente:** + +## Kontext und Problemstellung + + + +## Entscheidungsoptionen + +- Option A: +- Option B: +- Option C: + +## Entscheidung + + + +### Begründung + + + +## Konsequenzen + +### Positive + +- <...> + +### Negative / Trade-offs + +- <...> + +### Folgearbeiten / Open Points + +- <...> + +## Links + +- diff --git a/docs/adr/0001-first-rollout-db-app-scope.md b/docs/adr/0001-first-rollout-db-app-scope.md new file mode 100644 index 0000000..884477a --- /dev/null +++ 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) diff --git a/docs/adr/0002-session-scope-token-format.md b/docs/adr/0002-session-scope-token-format.md new file mode 100644 index 0000000..d492295 --- /dev/null +++ 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:" +} +``` + +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` diff --git a/docs/adr/0003-pii-retention-policy.md b/docs/adr/0003-pii-retention-policy.md new file mode 100644 index 0000000..8ed42fc --- /dev/null +++ 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/` am PII-Mediator mit Admin-Auth. +- Zusätzlich: Endpunkt `DELETE /pii/by-subject/` 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/", "digest": { "sha256": "" } } + ], + "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) diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..887ab5b --- /dev/null +++ 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).