# 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