Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -6,7 +6,7 @@
|
||||
| **Owner** | Raffael |
|
||||
| **Phase** | Phase 22 (v2-P1) — Public-API & Webhooks |
|
||||
| **Cycle/Fenster** | v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-17 |
|
||||
| **Status** | geplant |
|
||||
| **Status** | On Hold — serverseitig umgesetzt, Admin-Screens/UX aus `D-P22` fehlen |
|
||||
|
||||
## Abhängigkeiten & Parallelität
|
||||
- **Blocked by:** `VR-P22a` (Read-Endpoints + OpenAPI), `R-P12a` (v1-Automation: `external_event`-Trigger + ausgehende Webhook-Action)
|
||||
@@ -15,25 +15,32 @@
|
||||
- **Konflikt-Risiko:** gering — nur die geteilte Webhook-Ingest-Infra braucht Koordination (Owner = Raffael, Akeshan dockt an).
|
||||
|
||||
## Was wir bauen
|
||||
Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys authentifizieren Requests mit **Scopes** und **Rate-Limit** (1k/h pro Key, 10k/h pro Tenant, `X-RateLimit-*`-Header + Klartext-429). **Eingehende Lead-Webhooks** (`POST /webhooks/incoming/{tenant}/{slug}`) legen Leads an (API-Key/HMAC/URL-Token + Payload-Mapping + Auto-Match). **Ausgehende `WebhookSubscriptions`** senden Events HMAC-SHA256-signiert mit Idempotenz-ID, Retry mit exp. Backoff (max 5) und Auto-Disable nach 10 Fehlern; die ausgehende Webhook-**Action** dockt an die v1-Automation (`external_event`-Trigger) an. Tarif-Gates (M027) machen API-Keys/Webhooks abo-abhängig.
|
||||
Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API auf **`api.hivegrid.de`** (staging:
|
||||
`staging-api.hivegrid.de`). Es gibt keine Public-API- oder Public-Webhook-Routen unter `app.hivegrid.de/api`.
|
||||
API-Keys authentifizieren Requests mit **Scopes** und **Rate-Limit** (1k/h pro Key, 10k/h pro Tenant,
|
||||
`X-RateLimit-*`-Header + Klartext-429). **Eingehende Lead-Webhooks**
|
||||
(`POST https://api.hivegrid.de/v1/webhooks/incoming/{tenant}/{slug}`) legen Leads an (API-Key/HMAC/URL-Token +
|
||||
Payload-Mapping + Auto-Match). **Ausgehende `WebhookSubscriptions`** senden Events HMAC-SHA256-signiert mit
|
||||
Idempotenz-ID, Retry mit exp. Backoff (max 5) und Auto-Disable nach 10 Fehlern; die ausgehende Webhook-**Action**
|
||||
dockt an die v1-Automation (`external_event`-Trigger) an. Tarif-Gates (M027) machen API-Keys/Webhooks abo-abhängig.
|
||||
|
||||
## Benötigte Screens (Backend bedient — Design liefert `D-P22`)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| API-Key-Verwaltung [`/admin/api-keys`] | Key-Liste (Name/Scopes/letzte Nutzung/Status/Tarif-Gate) · Key erstellen (Scope-Auswahl, **Secret einmal sichtbar**) · Rotieren/Widerrufen — Erweiterung der v1-Fläche |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log |
|
||||
| Incoming-Webhook-Verwaltung [`/admin/api-keys/incoming-webhooks`] | Slug-Endpoints auf `api.hivegrid.de/v1/webhooks/...`, Auth-Modus (API-Key/HMAC/URL-Token), Payload-Mapping, Auto-Match-Regeln · Ingestion-Log |
|
||||
| Outgoing-Subscription-Liste [`/admin/webhooks`] | Ziel-URL, Event-Typen, Status (aktiv/auto-disabled), letzte Zustellung, Fehlerzähler |
|
||||
| Outgoing-Subscription-Detail [`/admin/webhooks/:id`] | **Secret einmal sichtbar**, Delivery-Stats, Delivery-Log mit Retry-Status, Replay/Test-senden, Aktivieren/Pausieren |
|
||||
| API-Request-Logs + Usage [`/admin/api-keys/usage`] | Request-Log (Endpoint/Key/Status/Latenz/Rate-Limit-Treffer) · Usage-Aggregat (Calls/h pro Key + Tenant, Quota) |
|
||||
|
||||
## Definition of Done
|
||||
- [ ] **API-Key-Auth** + **Scopes** + **Rate-Limit** (1k/h Key, 10k/h Tenant) + `X-RateLimit-*`-Header + Klartext-429
|
||||
- [ ] **Eingehende Lead-Webhooks** (API-Key/HMAC/URL-Token) + Payload-Mapping + **Auto-Match** (From/Pattern → Contact/Lead)
|
||||
- [ ] **Ausgehende `WebhookSubscriptions`** HMAC-SHA256-signiert, Idempotenz-ID, Retry exp. Backoff (max 5), **Auto-Disable nach 10 Fehlern**
|
||||
- [ ] **Tarif-Gates (M027):** API-Keys/Webhooks nur im passenden Abo verfügbar (`tenantHasModule('public_api')`)
|
||||
- [ ] **Writes** durch v1-Frozen/past_due-Middleware geblockt (**402**)
|
||||
- [ ] Secret/Webhook-Signing-Secret **einmalig sichtbar** (Copy-once-Muster), nur Hash persistiert
|
||||
- [ ] Ausgehende Webhook-Action an v1-Automation (`external_event`-Trigger) angedockt
|
||||
- [x] **API-Key-Auth** + **Scopes** + **Rate-Limit** (1k/h Key, 10k/h Tenant) + `X-RateLimit-*`-Header + Klartext-429
|
||||
- [x] **Eingehende Lead-Webhooks** auf `api.hivegrid.de/v1/webhooks/...` (API-Key/HMAC/URL-Token) + Payload-Mapping + **Auto-Match** (From/Pattern → Contact/Lead)
|
||||
- [x] **Ausgehende `WebhookSubscriptions`** HMAC-SHA256-signiert, Idempotenz-ID, Retry exp. Backoff (max 5), **Auto-Disable nach 10 Fehlern**
|
||||
- [x] **Tarif-Gates (M027):** API-Keys/Webhooks nur im passenden Abo verfügbar (`tenantHasModule('public_api')`)
|
||||
- [x] **Writes** durch v1-Frozen/past_due-Middleware geblockt (**402**)
|
||||
- [x] Secret/Webhook-Signing-Secret **einmalig sichtbar** (Copy-once-Muster), nur Hash persistiert
|
||||
- [x] Ausgehende Webhook-Action an v1-Automation (`external_event`-Trigger) angedockt
|
||||
|
||||
## Technische Bausteine
|
||||
- **Entities** (eigene `prisma/schema/publicApi.prisma`, AD-21): `ApiKey` (`key_hash`, `scope`, `expires_at`, [RLS][Soft-Delete] — Auth-Pfad hier vollständig), `WebhookSubscription` (Ziel-URL, abonnierte Event-Typen, Signing-Secret-Hash, Status, Fehlerzähler), Incoming-Webhook-Endpoint (Slug, Auth-Modus, Payload-Mapping), Delivery-/Ingestion-Log (append-only). Lead-Anlage über die CRM-Domäne (Lead-Entity), nur referenziert.
|
||||
@@ -41,6 +48,8 @@ Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys aut
|
||||
- **Rate-Limit:** Redis-Token-Bucket (geteilt mit v1-Redis), Key- und Tenant-Bucket getrennt.
|
||||
- **HMAC:** SHA256 für ein- und ausgehend; Signatur-Header + dokumentiertes Format (Code-Snippet für Verifizierung im UI).
|
||||
- **Webhook-Ingest-Infra:** geteilter Layer mit VA-P23 (Postfach-Sync) — einmal robust, idempotent.
|
||||
- **Host-Surface:** Public API und Public-Webhooks laufen nur im `hivegrid-api`-Service (`api.hivegrid.de` /
|
||||
`staging-api.hivegrid.de`), nie im Web-Service (`app.hivegrid.de/api` ist verboten).
|
||||
- **Konnektor:** `tenantHasModule('public_api')` + Tarif-Gate (M027, `SubscriptionFeature.code`).
|
||||
- **`is_demo_data`:** ggf. Demo-Webhook-Subscriptions geseedet (Bulk-Löschung beim Echt-Start).
|
||||
|
||||
@@ -55,4 +64,18 @@ Den **Auth-, Scope-, Rate-Limit- und Webhook-Teil** der Public-API. API-Keys aut
|
||||
## Dev-Nachzug (nach Davids `D-P22`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `VR-P22b` aktualisiert
|
||||
- [x] Plane-Ticket `VR-P22b` aktualisiert
|
||||
|
||||
## Umsetzungsnotiz
|
||||
|
||||
**2026-07-03 — Server-DoD umgesetzt, Ticket auf On Hold bis `D-P22`:**
|
||||
- API-Key-Scopes, Legacy-Read-Kompatibilität, Key-/Tenant-Rate-Limits und `X-RateLimit-*`-Header für `GET /v1/...` ergänzt.
|
||||
- `POST /v1/webhooks/incoming/{tenant}/{slug}` auf dem API-Service (`api.hivegrid.de`) ergänzt: URL-Token, HMAC und API-Key-Auth, Payload-Mapping, Lead-Anlage, Kontakt-Auto-Match, Ingestion-Log, Tarif-Gate und 402 bei `frozen`/`past_due`.
|
||||
- `prisma/schema/publicApi.prisma`, Migration `20260703090000_vr_p22b_public_api_webhooks` und RLS-Rollout-Datei für Incoming-Endpoints, Ingestion-Logs, Outgoing-Subscriptions und Delivery-Logs ergänzt.
|
||||
- Outgoing-Subscription-Service ergänzt: Copy-once Signing-Secret, Hash-only-Persistenz, HMAC-Signatur, Idempotenz-Key, Delivery-Log, exponential Backoff bis 5 Versuche und Auto-Pause nach 10 Fehlern.
|
||||
- v1-Automation ist angebunden: eingehende Webhooks erzeugen `AutomationExecution` für `webhook.received` mit `triggerPayload.source = "external_event"`; die bestehende `http.request`-Action bleibt der ausgehende Webhook-Action-Pfad.
|
||||
- OpenAPI, Route-Access-Inventar, Security-Doku, Tenant-Registry und Tests nachgezogen.
|
||||
|
||||
**Proof:** `pnpm exec prisma validate`; `pnpm --filter @hivegrid/api typecheck`; `pnpm --filter @hivegrid/db typecheck`; `pnpm --filter @hivegrid/cli typecheck`; fokussierte Vitest-Suite für Public-API/OpenAPI/Route-Inventar/DB; `pnpm run verify:api-inventory`; `pnpm run verify:openapi-security`; `node scripts/verify-cross-cutting-models-complete.mjs`; `pnpm typecheck`; `pnpm lint`; `pnpm test`.
|
||||
|
||||
**Stand:** 7/7 Server-DoD = 100 % serverseitig. Gesamtticket bleibt **On Hold**, weil die Verwaltungs-Screens aus `D-P22` noch fehlen: API-Key-Verwaltung, Incoming-Webhooks, Outgoing-Subscriptions, Detail/Replay und Usage-Logs.
|
||||
Reference in new issue
Block a user