ddbd304659
Some checks failed
build-images / approval-service image (push) Waiting to run
build-images / dummy-sink image (push) Waiting to run
phase1-smoke / Phase 1 end-to-end smoke (push) Waiting to run
validate / JSON Schema (ajv) (push) Waiting to run
validate / Rego (opa fmt + opa test) (push) Waiting to run
validate / Go (vet + test) (push) Waiting to run
validate / DB (migrate up/down dry-run) (push) Waiting to run
build-images / verification-service image (push) Has been cancelled
build-images / signing-service image (push) Has been cancelled
- README: Phase 1 abgeschlossen, Service-Liste + Deploy-Pfade + phase1-smoke-Anleitung. - ADR-0006: Approval-Service — WebAuthn als Content-Binding mit `nonce || H_content`, Alternative U2F-Challenge dokumentiert und als "challenge-only"-Fallback markiert. - ADR-0007: Signing-Service — zweistufige Identität (Pocket-ID JWKS + K8s TokenReview), Fehlermodus `registry_identity_mismatch` explizit. - ADR-0008: Dummy-Sink + zweistufige Verification-Chain, zentraler Replay-Guard in `verification_decisions`. Co-Authored-By: Paperclip <noreply@paperclip.ing>
154 lines
8.1 KiB
Markdown
154 lines
8.1 KiB
Markdown
# ProofedMesh
|
|
|
|
**Identity-Aware Agent Messaging Platform** — eine Plattform für kryptografisch nachvollziehbare Kommunikation zwischen Menschen, KI-Agenten und beliebigen Prozess-Senken (ERP, eigene Datenbankapplikationen, HTTP-Webhooks, Message-Queues, Dateiablage).
|
|
|
|
## Vision
|
|
|
|
Benutzerfreigaben, delegierte Berechtigungen und sämtliche Verarbeitungsschritte zwischen Menschen, Agenten und Zielsystemen werden kryptografisch nachvollziehbar.
|
|
|
|
> Der Benutzer autorisiert den ursprünglichen Geschäftsinhalt. Jeder Agent attestiert anschließend seine eigene Verarbeitung. Die empfangende Senke überprüft die vollständige Kette, bevor sie eine Aktion ausführt.
|
|
|
|
Identität, Berechtigung, Verarbeitung und Nachrichtentransport werden strikt getrennt. Der Trust-Core ist senken-agnostisch.
|
|
|
|
## Status
|
|
|
|
**Phase 1 abgeschlossen — End-to-End-Skelett läuft, Phase-1-Smoke grün.**
|
|
Die vollständige Vertrauenskette (User → Approval → Transform → Dummy-Sink → Verification)
|
|
lässt sich reproduzierbar durchlaufen; `make phase1-smoke` deckt sie in CI ab
|
|
([`.forgejo/workflows/phase1-smoke.yml`](.forgejo/workflows/phase1-smoke.yml)).
|
|
Die Prod-Härtung (OpenBao Transit, OPA, echte Senken) ist Phase-2-Scope.
|
|
|
|
- **Aktive Architektur:** [`docs/architecture/v1.1.md`](docs/architecture/v1.1.md) — V1.1 inkl. Senken-Generalisierung (SAP ist eine von vielen Senken), Pocket ID als alleiniger IdP, PII-Trennung, Trillian für Transparency Log, Content Binding mit WebAuthn, Replay-Schutz, Retention 1 Jahr
|
|
- **Historisch:** [`docs/architecture/v1.0.md`](docs/architecture/v1.0.md) — ursprünglicher Entwurf, archiviert
|
|
|
|
## Architekturprinzipien
|
|
|
|
1. **Unveränderliche Benutzerfreigabe** — ein vertrauenswürdiger Dienst bestätigt den konkret autorisierten Geschäftsinhalt (per WebAuthn Content Binding).
|
|
2. **Eigene Identität jedes Agenten** — jeder Agent besitzt eine separate kryptografische Identität.
|
|
3. **Verkettete Attestierungen** — jeder Verarbeitungsschritt referenziert exakte Eingabe- und Ausgabe-Hashes.
|
|
4. **Unabhängige Autorisierung** — eine Signatur allein erteilt keine Berechtigung; OPA kontrolliert erlaubte Transformationen und Senken-Aktionen.
|
|
5. **Transportneutralität** — Nachweise funktionieren über HTTP, NATS oder Matrix, ohne dass die Vertrauenskette verloren geht.
|
|
6. **Senken-Neutralität** — der Trust-Core kennt keine konkrete Senken-Semantik; Senken-Adapter sind Plug-ins mit festem Vertrag.
|
|
|
|
## Zielkernstack (V1.1)
|
|
|
|
| Bereich | Technologie |
|
|
| ------------- | ------------------------------------------------------------------ |
|
|
| Identität | Pocket ID (Menschen und Agent-Clients) |
|
|
| Workload-ID | Kubernetes projected ServiceAccount Token + TokenReview |
|
|
| Signaturen | Ed25519 / DSSE, OpenBao Transit |
|
|
| Provenienz | in-toto v1 (`basicstack.de/attestations/*/*`) |
|
|
| Autorisierung | OPA + Approval Service |
|
|
| Transparency | Trillian + PostgreSQL |
|
|
| Transport | HTTPS/mTLS + NATS JetStream; Matrix optional für Mensch-Chat |
|
|
| Agenten | Paperclip |
|
|
| Senken | Plug-in-Architektur: SAP S/4HANA (ABAP), eigene DB-Apps (Go-Adapter), HTTP-Webhooks, Message-Queues, Dateiablage |
|
|
| Evidence | PostgreSQL + S3 (Retention 1 Jahr) |
|
|
| PII | Separater verschlüsselter S3-Bucket, redaktionierbar |
|
|
|
|
## Repository-Layout
|
|
|
|
```
|
|
docs/
|
|
architecture/
|
|
v1.0.md # Ursprünglicher Entwurf (archiviert)
|
|
v1.1.md # Aktive Architektur
|
|
adr/
|
|
README.md # ADR-Index
|
|
0000-template.md
|
|
0001-first-rollout-db-app-scope.md
|
|
0002-session-scope-token-format.md
|
|
0003-pii-retention-policy.md
|
|
0004-db-migrations.md
|
|
0005-signing-service-and-transparency-log-api.md
|
|
0006-approval-service-webauthn-content-binding.md
|
|
0007-signing-service-dual-identity-check.md
|
|
0008-dummy-sink-and-verification-chain.md
|
|
db/
|
|
README.md
|
|
trust/migrations/0001_per_diem_rates.{up,down}.sql
|
|
trust/migrations/0004_approval_sessions.{up,down}.sql
|
|
trust/migrations/0005_verification_decisions.{up,down}.sql
|
|
schemas/
|
|
README.md
|
|
expense/canonical/{v1.0.0,v1.1.0,v1.2.0}.json
|
|
ds/expense/project_assignment/v1.0.0.json
|
|
ds/receipts/v1.0.0.json
|
|
ds/per_diem/v1.0.0.json
|
|
sink/db/expense/{v1.0.0,v1.1.0,v1.2.0}.json
|
|
policies/
|
|
README.md
|
|
transformations/{expense,per_diem}.rego (+ _test.rego)
|
|
sinks/expense_db_app.rego (+ _test.rego)
|
|
data_sources/{expense_db_app,receipts,per_diem_rates}.rego (+ _test.rego)
|
|
services/
|
|
per-diem-calculator/ # deterministic calculator (Go)
|
|
admin-api/ # admin surface for per-diem rate management (Go)
|
|
attest-reconciler/ # periodic worker: re-signs per_diem_rates rows without rate_change_attestation_ref (Go)
|
|
signing-service/ # DSSE signing service (Go, ADR-0005 + ADR-0007) + Dockerfile
|
|
transparency-log/ # Trillian-backed transparency log (Go, ADR-0005)
|
|
approval-service/ # WebAuthn-gated content-binding approvals (Go, ADR-0006)
|
|
testagent-transform/ # Phase-1 Transform-Agent-CLI (Go)
|
|
dummy-sink/ # Phase-1 Mock-Senke (Go, ADR-0008)
|
|
verification-service/ # Phase-1 Chain-Verifier + Replay-Guard (Go, ADR-0008)
|
|
deploy/
|
|
trillian/ # Trillian MySQL + log server/signer (namespace agent-trust)
|
|
signing-service/ # signing-service Deployment/Service/NetworkPolicy + Secret convention
|
|
approval-service/ # approval-service Deployment/Service/NetworkPolicy + Pocket-ID OIDC-Secret
|
|
verification-service/ # verification-service Deployment/Service/NetworkPolicy
|
|
dummy-sink/ # dummy-sink Deployment/Service/NetworkPolicy + PVC (Longhorn RWO)
|
|
.forgejo/workflows/
|
|
validate.yml # JSON-Schema (ajv) + Rego (opa fmt + opa test) + Go (vet + test)
|
|
build-images.yml # Container-Images für ProofedMesh-Services → harbor.basicstack.de
|
|
phase1-smoke.yml # End-to-End Phase-1-Smoke (make phase1-smoke)
|
|
```
|
|
|
|
Weitere Verzeichnisse (weitere Services, Deployment-Manifeste, Senken-/Datenquellen-Adapter) folgen im Zuge der Architekturentwicklung.
|
|
|
|
## Einstiegspunkte
|
|
|
|
- [Architektur V1.1](docs/architecture/v1.1.md) — Zielbild
|
|
- [ADRs](docs/adr/README.md) — getroffene Entscheidungen
|
|
- [Schemas](schemas/README.md) — kanonische Business-, Datenquellen- und Senken-Formate
|
|
- [Policies](policies/README.md) — OPA/Rego-Policies für Transformationen, Senken und Datenquellen
|
|
|
|
## Lokal validieren
|
|
|
|
```bash
|
|
# JSON-Schemas
|
|
npx -y ajv-cli@5 compile --spec=draft2020 -c ajv-formats \
|
|
-s schemas/expense/canonical/v1.0.0.json
|
|
|
|
# Rego
|
|
opa fmt --list --diff policies/
|
|
opa test policies/ -v
|
|
|
|
# Go services
|
|
(cd services/admin-api && go vet ./... && go test ./...)
|
|
(cd services/per-diem-calculator && go vet ./... && go test ./...)
|
|
(cd services/attest-reconciler && go vet ./... && go test ./...)
|
|
(cd services/signing-service && go vet ./... && go test ./...)
|
|
(cd services/transparency-log && go vet ./... && go test ./...)
|
|
(cd services/approval-service && go vet ./... && go test ./...)
|
|
(cd services/testagent-transform && go vet ./... && go test ./...)
|
|
(cd services/dummy-sink && go vet ./... && go test ./...)
|
|
(cd services/verification-service && go vet ./... && go test ./...)
|
|
```
|
|
|
|
CI (`.forgejo/workflows/validate.yml`) läuft dieselben Prüfungen auf jedem Push und PR gegen `main`.
|
|
|
|
## Phase-1-Smoke
|
|
|
|
Der End-to-End-Smoketest baut jeden Phase-1-Service als statisches Binary,
|
|
startet sie auf Loopback-Ports und treibt die vollständige Kette
|
|
User → Approval → Transform → Dummy-Sink → Verification mit `curl` + `jq`
|
|
durch. Keine Container-Runtime nötig, keine Kubernetes-Instanz.
|
|
|
|
```bash
|
|
make phase1-smoke
|
|
```
|
|
|
|
Der Test prüft `valid=true` auf `/verify/chain`, dass der Dummy-Sink die
|
|
Payload unter `<WORK>/data/<decision_id>.json` abgelegt hat, und dass der
|
|
Transparency-Log drei DSSE-Attestationen enthält (Approval + Transform +
|
|
Handover). CI-Workflow: [`.forgejo/workflows/phase1-smoke.yml`](.forgejo/workflows/phase1-smoke.yml).
|