116 lines
3.0 KiB
Markdown
116 lines
3.0 KiB
Markdown
# 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
|