basicstack/ProofedMesh
SHA256
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ProofedMesh/docs/architecture/v1.0.md

399 lines
18 KiB
Markdown
Raw Permalink Normal View History

docs(architecture): add trusted agent/SAP messaging architecture V1.0
2026-10-25 10:15:41 +00:00
# Technische Zielarchitektur: Vertrauenswürdige Kommunikation zwischen Menschen, KI-Agenten und SAP
**Status:** Architekturvorschlag V1.0 (Diskussionsgrundlage)
**Umfang:** Logische Zielarchitektur, keine konkrete Netzwerktopologie oder Produktauswahl.
Diese Lösung wird als **Identity-Aware Agent Messaging Platform** konzipiert: eine Plattform, die Benutzerfreigaben, delegierte Berechtigungen und sämtliche Verarbeitungsschritte kryptografisch nachvollziehbar macht.
Die zentrale Designentscheidung lautet:
> **Der Benutzer autorisiert den ursprünglichen Geschäftsinhalt. Jeder Agent attestiert anschließend seine eigene Verarbeitung. Der empfangende Agent überprüft die vollständige Kette, bevor er eine Aktion ausführt.**
Dabei werden Identität, Berechtigung, Verarbeitung und Nachrichtentransport strikt getrennt.
## 1. Zielarchitektur
Logische Komponentenübersicht, keine direkte Netzwerktopologie. Freigabe- und Attestierungsnachweise werden über eigene APIs erstellt und geprüft; Matrix transportiert Referenzen und Nachrichten.
## 2. Die fünf Architekturprinzipien
1. **Unveränderliche Benutzerfreigabe:** Ein vertrauenswürdiger Dienst bestätigt, welchen konkreten Geschäftsinhalt ein Benutzer autorisiert hat.
2. **Eigene Identität jedes Agenten:** Jeder Agent besitzt eine separate kryptografische Identität und signiert seine eigenen Verarbeitungsschritte.
3. **Verkettete Attestierungen:** Jeder Verarbeitungsschritt referenziert die exakten Eingabe- und Ausgabe-Hashes.
4. **Unabhängige Autorisierung:** Eine Signatur allein erteilt keine Berechtigung. Eine Policy Engine kontrolliert erlaubte Transformationen und ERP-Aktionen.
5. **Transportneutralität:** Die Nachweise funktionieren über Matrix, HTTP, NATS oder eine Queue, ohne dass die kryptografische Vertrauenskette verloren geht.
## 3. Konkrete technische Komponenten
| Dienst | Technologie | Verantwortung |
| --------------------- | ----------------------- | -------------------------------------------- |
| Identity Provider | Pocket ID oder Keycloak | Benutzeranmeldung, OIDC |
| Approval Service | Go, REST API | Inhaltsgebundene Benutzerfreigabe |
| Agent Registry | PostgreSQL | Agentenidentitäten und öffentliche Schlüssel |
| Signing Service | Go + OpenBao | DSSE-Signaturen, Schlüsselzugriff |
| Attestation Service | Go + in-toto | Verarbeitungsschritte dokumentieren |
| Policy Decision Point | Open Policy Agent (OPA) | Berechtigungen und Transformationsregeln |
| Verification Service | Go | Gesamte Vertrauenskette überprüfen |
| Message Transport | Matrix/Synapse | E2EE-Kommunikation |
| SAP Connector | ABAP REST API / OData | Validierte Buchungsaufträge |
| Evidence Store | PostgreSQL + S3 | Unveränderliche Nachweise |
Approval, Attestation, Registry und Verification werden zunächst in **einem modularen Go-Dienst** zusammengefasst. Separate APIs und Module bleiben erhalten, aber der Betrieb vieler kleiner Microservices wird vermieden.
Eine wichtige Abgrenzung: Keycloak bietet inzwischen Standard Token Exchange V2; die explizite Delegationsfunktion mit `act` und `may_act` ist weiterhin als Preview dokumentiert. Für den produktiven Kern wird die auftragsbezogene Delegation daher im eigenen Approval Service implementiert; Keycloak dient primär der Authentifizierung.
## 4. Datenmodell der Vertrauenskette
Jede Reisekostenabrechnung erhält eine unveränderliche `workflow_id`. Jede Fassung der Daten wird als eigenes Artefakt mit SHA-256-Hash gespeichert.
### Vertrauens- und Verarbeitungskette
1. **Benutzerfreigabe** — Approval Service signiert den Hash der bestätigten Abrechnung und bindet ihn an die OIDC-Identität des Mitarbeiters.
2. **Agent A: Vorbereitung** — Agent A signiert eine Attestierung über Eingabe-Hash, Ausgabe-Hash, Transformationsart und ursprüngliche Freigabe.
3. **Agent B: SAP-Mapping** — Agent B signiert seine eigene Attestierung und referenziert die Ausgabe von Agent A.
4. **Agent C: SAP-Buchung** — Agent C überprüft die komplette Kette und erzeugt nach erfolgreicher Buchung einen signierten Buchungsnachweis.
Die Attestierungen sind keine einfachen Chatnachrichten, sondern eigenständige, überprüfbare Datensätze.
### 4.1 Benutzerfreigabe
Ein Beispiel für eine in-toto-Attestierung des Approval Service:
```json
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{
"name": "expense/EXP-2026-0042/v1",
"digest": {
"sha256": "<64 hex characters>"
}
}
],
"predicateType": "https://example.org/attestation/approval/v1",
"predicate": {
"workflow_id": "WF-0042",
"approval_id": "APR-0042",
"issuer": "approval-service",
"user": {
"iss": "https://identity.example.org",
"sub": "user-12345"
},
"action": "expense.submit",
"audience": "sap-expense-workflow",
"allowed_transformations": [
"expense.normalize",
"expense.map_to_sap"
],
"expires_at": "2026-11-01T00:00:00Z"
}
}
```
Das `predicateType` ist hier ein eigenes, noch zu definierendes Schema. Die äußere Statement-Struktur mit `subject`, `predicateType` und `predicate` entspricht dem in-toto-Modell.
**Wesentlich:** Der Approval Service darf dieses Dokument nur erzeugen, nachdem er die authentifizierte Benutzersitzung, die Freigabeaktion und den Hash des tatsächlich angezeigten Inhalts geprüft hat. Ein Agent darf diesen Endpunkt nicht allein mit einer frei angegebenen Benutzer-ID aufrufen.
### 4.2 Signatur mit DSSE
Die vollständige Attestierung wird als DSSE-Payload signiert:
```json
{
"payloadType": "application/vnd.in-toto+json",
"payload": "<base64-encoded statement>",
"signatures": [
{
"keyid": "approval-service-key-2026",
"sig": "<base64-encoded signature>"
}
]
}
```
DSSE verwendet eine sogenannte Pre-Authentication Encoding (PAE), um Nutzlast und Inhaltstyp gemeinsam zu signieren. Das `keyid` ist lediglich ein Hinweis auf den zu verwendenden öffentlichen Schlüssel; die Identität ergibt sich erst aus der verifizierten Signatur und der vertrauenswürdigen Schlüsselregistrierung.
Damit wird der Approval Service zum kryptografischen Aussteller des Benutzerfreigabenachweises.
### 4.3 Attestierung einer Transformation
Agent B erzeugt beispielsweise:
```json
{
"_type": "https://in-toto.io/Statement/v1",
"subject": [
{
"name": "expense/EXP-2026-0042/sap-payload",
"digest": {
"sha256": "<output hash>"
}
}
],
"predicateType": "https://example.org/attestation/transform/v1",
"predicate": {
"workflow_id": "WF-0042",
"actor": "agent-sap-mapping",
"operation": "expense.map_to_sap",
"materials": [
{
"name": "expense/EXP-2026-0042/normalized",
"sha256": "<input hash>"
}
],
"parent_attestation": "sha256:<previous proof hash>",
"approval_ref": "APR-0042",
"transform_version": "1.3.0"
}
}
```
Agent B signiert diese Attestierung mit seinem eigenen Schlüssel.
Damit wird überprüfbar, **welcher Agent welche konkrete Eingabe in welche konkrete Ausgabe transformiert hat**. Dass die Transformation inhaltlich korrekt war, beweist die Signatur allerdings nicht. Dafür benötigt der Empfänger zusätzlich fachliche Prüfregeln.
## 5. Verifikation beim empfangenden Agenten
Der SAP-Agent darf sich nicht auf die mitgesendeten IDs verlassen. Er muss die gesamte Nachweiskette prüfen.
Hierfür wird ein zentraler Endpunkt bereitgestellt:
```
POST /api/v1/attestations/verify
Authorization: Bearer <service-token>
Content-Type: application/json
```
```json
{
"workflow_id": "WF-0042",
"artifact_digest": "sha256:<final hash>",
"requested_action": "expense.post_to_sap",
"target": "sap-s4hana-prod"
}
```
Der Verification Service führt folgende Prüfungen durch:
| Prüfung | Fehlerfall |
| ---------------------------------------------------------------- | --------------------- |
| Signatur der Benutzerfreigabe gültig? | Ablehnen |
| Benutzeridentität im vertrauenswürdigen IdP vorhanden? | Ablehnen |
| Freigabe gültig und nicht widerrufen? | Ablehnen |
| Alle Agentensignaturen gültig? | Ablehnen |
| Agenten zum Signaturzeitpunkt registriert und berechtigt? | Ablehnen |
| Stimmen Eingabe- und Ausgabe-Hashes überein? | Ablehnen |
| Transformationen laut Freigabe zulässig? | Ablehnen |
| Entspricht die SAP-Nutzlast der freigegebenen Geschäftssemantik? | Ablehnen |
| Auftrag bereits gebucht? | Keine erneute Buchung |
Eine erfolgreiche Prüfung könnte folgendes Ergebnis liefern:
```json
{
"valid": true,
"workflow_id": "WF-0042",
"original_user": {
"issuer": "https://identity.example.org",
"subject": "user-12345"
},
"actors": [
"agent-travel",
"agent-sap-mapping"
],
"authorized_action": "expense.post_to_sap",
"artifact_digest": "sha256:<final hash>",
"decision_id": "DEC-2026-0042"
}
```
Dieses Ergebnis darf selbst keine frei verwendbare Buchungsberechtigung darstellen. Für die produktive Umsetzung wird eine kurzlebige, signierte und an Agent C sowie den konkreten Payload-Hash gebundene Ausführungsberechtigung ausgestellt. SAP beziehungsweise der SAP-Connector muss diese erneut überprüfen.
## 6. Berechtigungssteuerung mit Open Policy Agent
Für die fachliche Autorisierung wird Open Policy Agent eingesetzt.
Beispielsweise:
- Agent A darf Belege extrahieren und Reisekosten strukturieren.
- Agent B darf Kontierungsinformationen ergänzen und SAP-Felder zuordnen.
- Agent B darf keine Beträge oder Währungen ohne zusätzliche Freigabe ändern.
- Agent C darf ausschließlich vollständig validierte Reisekostenabrechnungen buchen.
Die Regeln lassen sich über Rego-Policies zentral verwalten und versionieren.
Besonders wichtig ist eine **fachliche Integritätsprüfung**. Ein Hashvergleich allein reicht nicht, weil sich beim Mapping das technische Format zwangsläufig verändert.
Deshalb wird eine kanonische Geschäftsdatenstruktur definiert:
```json
{
"employee_id": "EMP-12345",
"currency": "EUR",
"total_amount": "428.50",
"expense_items": [
{ "type": "HOTEL", "amount": "328.50" },
{ "type": "MEALS", "amount": "100.00" }
]
}
```
Die Benutzerfreigabe bezieht sich auf diese Geschäftsdaten. Technische Transformationen dürfen deren geschäftliche Bedeutung nicht unerlaubt verändern.
## 7. SAP S/4HANA Integration
Für eine S/4HANA-2023-Umgebung wird eine kleine ABAP-Integrationsschicht vorgesehen, statt dem SAP-Agenten direkten Zugriff auf beliebige Buchungsfunktionen zu geben.
Agent C → ABAP REST Endpoint (Authentifizierung · Freigabenachweis · Idempotenz) → SAP-Anwendungslogik (Mitarbeiterzuordnung · fachliche Prüfungen · Buchung).
Der ABAP-Endpunkt könnte beispielsweise so aussehen:
```
POST /sap/bc/zexpense/v1/submit
Authorization: Bearer <sap-agent-token>
Idempotency-Key: WF-0042
Content-Type: application/json
```
```json
{
"workflow_id": "WF-0042",
"approval_id": "APR-0042",
"verification_ref": "DEC-2026-0042",
"expense_ref": "EXP-2026-0042",
"payload_hash": "sha256:<final hash>"
}
```
Die eigentlichen Geschäftsdaten empfängt SAP entweder zusammen mit dem Auftrag oder ruft sie über eine abgesicherte Schnittstelle anhand der Referenz ab.
Wichtig sind hierbei zwei unabhängige Prüfungen:
- **Technische Identität:** Der Aufruf kommt tatsächlich vom autorisierten SAP-Agenten.
- **Fachliche Identität:** Der freigebende Benutzer ist nachweisbar und wird über eine serverseitig gepflegte Zuordnung der korrekten SAP-Personalnummer zugeordnet.
Eine vom Agenten gelieferte Personalnummer darf diese Zuordnung nicht überschreiben.
Welche SAP-Buchungsschnittstelle verwendet werden sollte, hängt davon ab, ob die Reisekosten über SAP Travel Management, SAP Concur oder einen kundeneigenen FI-Prozess verarbeitet werden. Daher wird noch keine konkrete Standard-BAPI oder OData-API festgelegt.
### SAP-Auditdaten
Zusätzlich zum erzeugten ERP-Beleg wird eine eigene Tabelle `ZAGENT_AUDIT` vorgesehen.
| Feld | Inhalt |
| --------------------- | ---------------------------------- |
| WORKFLOW_ID | Eindeutige Prozess-ID |
| APPROVAL_ID | Benutzerfreigabe |
| USER_SUB | Externe Benutzeridentität |
| PERNR | Zugeordnete Personalnummer |
| AGENT_ID | Buchender Agent |
| PAYLOAD_HASH | SHA-256 der Buchungsdaten |
| VERIFICATION_ID | Verifikationsentscheidung |
| BUKRS / BELNR / GJAHR | FI-Belegreferenz, soweit vorhanden |
| CREATED_AT | Buchungszeitpunkt |
Der vollständige kryptografische Nachweis verbleibt im Evidence Store. SAP speichert nur die notwendigen Referenzen und Prüfinformationen.
Für die Idempotenz ist außerdem eine atomare Buchungs- beziehungsweise Wiederanlaufstrategie erforderlich, damit ein Netzwerkfehler nicht zu einer zweiten Reisekostenbuchung führt.
## 8. Archivierung und Langzeitnachweis
Der Evidence Store speichert die ursprüngliche Freigabe, alle DSSE-Envelopes, die referenzierten Artefakte, Policy-Entscheidungen und den abschließenden SAP-Buchungsnachweis.
Es wird zwischen zwei Datenklassen unterschieden:
| Daten | Speicherung |
| -------------------------------------- | ---------------------------- |
| Prozessstatus, Identitäten, Referenzen | PostgreSQL |
| Signierte Attestierungen | S3 Object Storage |
| Reisekostenbelege und Geschäftsdaten | Verschlüsselt in S3 |
| Signatur- und Schlüsselhistorie | Geschütztes Trust Repository |
| Archiv-Manifeste | S3, separat signiert |
Für eine langfristige Prüfung müssen auch frühere öffentliche Schlüssel, Schlüsselgültigkeiten, Widerrufsereignisse und die zum Entscheidungszeitpunkt verwendeten Policies nachvollziehbar bleiben.
Eine unveränderliche Ablage ist nicht automatisch rechtssicher oder revisionssicher. Aufbewahrungsfristen, Datenschutz, Löschkonzept und die tatsächlichen Unveränderbarkeitsgarantien des gewählten Objektspeichers müssen gesondert festgelegt werden.
## 9. Deployment in Kubernetes
Für den ersten produktionsnahen Aufbau sind folgende Namespaces und Dienste vorgesehen:
```
identity/
keycloak
identity-postgres
agent-trust/
trust-api
approval-service
verification-worker
policy-engine
trust-postgres
matrix/
synapse
element-web
agent-matrix-gateway
paperclip/
paperclip
agent-travel
agent-sap-mapping
agent-sap-posting
openbao/
openbao
```
Die Dienste unter `agent-trust` werden zunächst als Komponenten einer gemeinsamen Anwendung implementiert, nicht zwingend als eigenständige Deployments.
Für die Signaturschlüssel kommt OpenBao als zentrale Verwaltungs- und Zugriffsschicht in Frage. Die konkrete Unterstützung der benötigten Ed25519-Operationen, die Schlüsselisolation und das Backup-Konzept werden vor der Implementierung validiert.
Außerdem wird verhindert, dass Agenten private Schlüssel direkt lesen können. Stattdessen ruft ein Agent einen Signing-Endpunkt auf, der seine Workload-Identität überprüft und ausschließlich Attestierungen signiert, die zu seinen Berechtigungen passen.
## 10. Implementierungsreihenfolge
**Phase 1 – Identity & Approval**
OIDC-Anmeldung, Benutzerfreigabe, kanonische Reisekostendaten, DSSE-Signatur des Approval Service.
**Phase 2 – Agent Attestations**
Agent Registry, Ed25519-Schlüssel, in-toto-Transformationsnachweise, verkettete Artefakt-Hashes.
**Phase 3 – Verification & Policies**
Vollständige Signaturkettenprüfung, OPA-Regeln, Widerruf, Replay-Schutz, Prüfung unerlaubter Änderungen.
**Phase 4 – SAP und Archiv**
ABAP-Integrationsendpoint, serverseitige Mitarbeiterzuordnung, Buchungsnachweise, verschlüsseltes Archiv.
**Phase 5 – Matrix-Integration**
Chatbasierte Auftragserteilung, Benachrichtigungen, Agentenkommunikation und E2EE.
## 11. Was bewusst anders gemacht wird
Der Matrix-Chat wird **nicht** zur maßgeblichen Quelle für Berechtigungen und Benutzerfreigaben gemacht. Matrix bleibt Transport- und Interaktionsschicht.
Die maßgeblichen Informationen liegen im Trust Service:
- Wer hat welchen Geschäftsinhalt freigegeben?
- Welcher Agent durfte welche Transformation ausführen?
- Welche konkrete Ausgabe hat dieser Agent erzeugt?
- Darf das endgültige Ergebnis in SAP gebucht werden?
Damit lässt sich dieselbe Vertrauenskette später auch für Bestellungen, Rechnungsfreigaben, Stammdatenänderungen oder andere ERP-Prozesse nutzen.
## 12. Empfohlener Kernstack (Zielbild)
| Identität | OIDC / Keycloak |
| ------------- | ------------------------------- |
| Signaturen | Ed25519 / DSSE |
| Provenienz | in-toto v1 |
| Autorisierung | OPA + Approval Service |
| Kommunikation | Matrix E2EE |
| Agenten | Paperclip |
| ERP | SAP S/4HANA / ABAP REST |
| Archiv | PostgreSQL + verschlüsseltes S3 |
**Wichtigste Empfehlung:** Zuerst den Trust Service und einen vollständigen, signierten Testprozess von der Benutzerfreigabe bis zur simulierten SAP-Buchung implementieren. Matrix kann anschließend ergänzt werden, ohne das Sicherheitsmodell ändern zu müssen.
So entsteht keine reine Messaging-Lösung, sondern eine wiederverwendbare Infrastruktur für **nachweisbar autorisierte KI-Agentenprozesse**.
Reference in a new issue Copy permalink