# Onboarding-Backend & Desktop-Identität

Dieses Dokument beschreibt die Backend-Infrastruktur für die Identifizierung und Authentifizierung von
Desktop-Clients ("Meldestelle-Biest").

## 🚀 Übersicht

Im Gegensatz zur Web-App (die via Keycloak/JWT authentifiziert) nutzen die Desktop-Instanzen für die
Offline-Synchronisation eine Identität, die während des **Onboarding-Prozesses** lokal vergeben und am Server
registriert wird.

## 🛡️ Authentifizierungs-Mechanismus

Die Authentifizierung erfolgt über zwei HTTP-Header, die bei jedem Request vom Desktop-Client mitgesendet werden müssen:

| Header           | Beschreibung                                       | Beispiel           |
|:-----------------|:---------------------------------------------------|:-------------------|
| `X-Device-Name`  | Der beim Onboarding vergebene Gerätename           | `Meldestelle-PC-1` |
| `X-Security-Key` | Der beim Onboarding vergebene Sicherheitsschlüssel | `secret-key-123`   |

### DeviceSecurityFilter

Ein Custom-Security-Filter (`DeviceSecurityFilter`) im Backend extrahiert diese Header und setzt einen Spring Security
Kontext mit der Authority `ROLE_DEVICE`.

## 🛰️ API-Endpunkte (Identity Service)

### 1. Gerät registrieren

Wird beim Abschluss des Onboarding-Screens aufgerufen.

- **URL:** `POST /api/v1/devices/register`
- **Body:**

```json
{
  "name": "Meldestelle-PC-1",
  "securityKeyHash": "...",
  "role": "MASTER"
}
```

- **Hinweis:** Dieser Endpunkt ist `permitAll()`, um die Erstregistrierung zu ermöglichen.

### 2. Gerät abrufen

- **URL:** `GET /api/v1/devices/{name}`
- **Auth:** Erfordert `ROLE_DEVICE` oder `JWT`.

## 💾 Datenmodell (Exposed)

Die Tabelle `identity_devices` speichert die registrierten Instanzen:

- `id`: Eindeutige UUID.
- `name`: Gerätename (eindeutig).
- `security_key_hash`: Der Sicherheitsschlüssel (gehasht).
- `role`: `MASTER` oder `CLIENT`.
- `last_sync_at`: Zeitstempel der letzten erfolgreichen Synchronisation.

## 🛠️ Local Test-Setup

Für lokale Tests mit `curl`:

```bash
curl -X GET http://localhost:8081/api/v1/devices/Meldestelle-PC-1 \
     -H "X-Device-Name: Meldestelle-PC-1" \
     -H "X-Security-Key: secret-key-123"
```