2e44147a71
- services/attest-reconciler/ as its own go.mod (admin-api internal/ is not importable; shared code gets extracted when a 3rd consumer appears). - Scheduler accepts "@every <dur>" or a bare Go duration; context-cancellation stops the loop cleanly. - Store client defines PendingRateStore + Postgres skeleton for SELECT ... WHERE rate_change_attestation_ref IS NULL. - Orchestrator + HTTPSigner + tlog.HTTPSubmitter mirror admin-api byte-for-byte so the TLog idempotency key collides on resubmits (kein Doppelsignieren). - Prometheus text-format /metrics endpoint, dependency-free: attest_reconciler_dirty_rows_total, _reconciliation_attempts_total, _reconciliation_failures_total, _idempotent_noop_total. - Tests with fake store + fake signer + fake submitter cover: happy path, already-attested rows are NOT re-signed, TLog idempotency across ticks, TLog-down failure path, pre-cancelled ctx. - Top-level README reflects the new service; CI auto-discovers services/*/go.mod so no workflow change needed. Co-Authored-By: Paperclip <noreply@paperclip.ing>
108 lines
5.4 KiB
Markdown
108 lines
5.4 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
|
|
|
|
Dieses Repository bildet die **Basis für die Architekturentwicklung**. Die Komponentenentwicklung hat noch nicht begonnen.
|
|
|
|
- **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
|
|
db/
|
|
README.md
|
|
trust/migrations/0001_per_diem_rates.{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)
|
|
.forgejo/workflows/
|
|
validate.yml # JSON-Schema (ajv) + Rego (opa fmt + opa test) + Go (vet + test)
|
|
```
|
|
|
|
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 ./...)
|
|
```
|
|
|
|
CI (`.forgejo/workflows/validate.yml`) läuft dieselben Prüfungen auf jedem Push und PR gegen `main`.
|