KI-AGENT: Zentralen Push-Server Stack ergänzen

2026-05-22 16:53:27 +02:00
parent 19bab852de
commit 5a4de421ce
43 changed files with 17731 additions and 0 deletions
--- a/push-server/README.md
+++ b/push-server/README.md
@@ -0,0 +1,115 @@
+# FEDEO Push Server
+
+Eigenständiger Stack für den zentralen FEDEO Push-Transportdienst. Selfhosted FEDEO-Instanzen registrieren Geräte lokal und leiten nur technische Push-Aufträge an diesen Dienst weiter. Die Instanzen authentifizieren sich mit einem rotierbaren Schlüssel, der im Admin-Dashboard gepflegt wird.
+
+## Bestandteile
+
+- `apps/api`: Fastify API für Admin-Dashboard und Selfhost-Instanzen
+- `apps/admin`: Nuxt Admin Dashboard mit Nuxt UI
+- `packages/db`: Drizzle Schema und Migrationen für PostgreSQL
+- `docker-compose.yml`: lokaler Stack aus Postgres, API und Admin
+
+## Entwicklung
+
+```bash
+cd push-server
+cp .env.example .env
+npm install
+npm run db:migrate
+npm run dev:api
+npm run dev:admin
+```
+
+Standardports:
+
+- API: `http://localhost:4020`
+- Admin: `http://localhost:3000` lokal oder `http://localhost:3020` über Docker Compose
+- Postgres: `localhost:5442`
+
+## Admin-Zugang
+
+Das Dashboard nutzt den Wert aus `ADMIN_TOKEN`. Der Token wird im Browser nur lokal gespeichert und als `Authorization: Bearer ...` an die API gesendet.
+
+## Instanz-Authentifizierung
+
+Instanzaufrufe verwenden HMAC-SHA256:
+
+```text
+X-Fedeo-Instance-Id: inst_...
+X-Fedeo-Timestamp: 2026-05-22T10:00:00.000Z
+X-Fedeo-Signature: <hex-hmac>
+```
+
+Signiert wird:
+
+```text
+METHOD
+PATH
+TIMESTAMP
+SHA256(BODY)
+INSTANCE_ID
+```
+
+Beispiel:
+
+```ts
+import { createHash, createHmac } from "node:crypto";
+
+const body = JSON.stringify(payload);
+const timestamp = new Date().toISOString();
+const bodyHash = createHash("sha256").update(body).digest("hex");
+const canonical = ["POST", "/v1/push", timestamp, bodyHash, instanceId].join("\n");
+const signature = createHmac("sha256", clientSecret).update(canonical).digest("hex");
+```
+
+## Wichtige API-Endpunkte
+
+- `GET /v1/public-config`
+- `POST /v1/instances/heartbeat`
+- `POST /v1/devices`
+- `DELETE /v1/devices/:centralDeviceId`
+- `POST /v1/push`
+- `GET /v1/push/:deliveryJobId`
+
+Admin:
+
+- `GET /admin/summary`
+- `GET /admin/instances`
+- `POST /admin/instances`
+- `PATCH /admin/instances/:id`
+- `POST /admin/instances/:id/rotate-secret`
+- `GET /admin/instances/:id/devices`
+- `GET /admin/instances/:id/jobs`
+
+## Apple Push Notification service
+
+Für iOS müssen diese Werte gesetzt sein:
+
+```env
+IOS_BUNDLE_ID=software.federspiel.fedeo
+APNS_TEAM_ID=...
+APNS_KEY_ID=...
+APNS_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+APNS_PRODUCTION=false
+```
+
+Solange APNs nicht vollständig konfiguriert ist, nimmt die API Push-Aufträge an, markiert iOS-Zustellversuche aber mit `apns_not_configured`.
+
+## Aktueller Umfang
+
+Implementiert:
+
+- Instanzverwaltung im Admin-Dashboard
+- rotierbare Instanzschlüssel mit verschlüsselter Speicherung
+- HMAC-authentifizierte Instanzbefehle
+- Geräte-Registry für `web`, `ios` und `android`
+- Zustelljobs mit Idempotenzschlüssel
+- APNs-Zustellung für iOS
+- technische Status- und Fehlererfassung
+
+Vorbereitet, aber noch nicht vollständig implementiert:
+
+- Web Push Zustellung
+- FCM Zustellung
+- asynchrone Queue/Worker-Verarbeitung
+- produktive Rate-Limits pro Instanz