# TURN REST Credentials (Ephemeral) – Nutzung & Betrieb

Dieses Dokument erklärt die **TURN REST Credential** Strategie für `niom-turn` (MVP → production-fähiger Pfad).

## Warum TURN REST?

- Du willst für WebRTC *kurzlebige* TURN-Logins ausstellen (z.B. 5–10 Minuten).
- Dein TURN-Server speichert keine User-Passwörter pro Nutzer.
- Dein Backend (später) kann Tokens ausstellen; bis dahin kannst du lokal/ops-seitig Tokens generieren.

## Verfahren (kompatibel zu gängigen WebRTC-Stacks)

**Username**: `<expiry_unix_seconds>` oder `<expiry_unix_seconds>:<opaque_user_id>`

- Beispiel: `1735412345:alice`
- `expiry_unix_seconds` ist ein Unix-Timestamp in Sekunden.

**Credential (Password)**:

$$\n\text{credential} = \text{base64}(\text{HMAC-SHA1}(\text{secret}, \text{username}))\n$$

Dieses `credential` wird dann ganz normal als TURN-Passwort im ICE-Server-Config verwendet.

## Server-Seite (`niom-turn`)

Konfiguration in [appsettings.example.json](../appsettings.example.json):

- `auth.rest_secret`: Shared Secret (muss geheim bleiben)
- `auth.rest_max_ttl_seconds`: Maximal akzeptiertes Zeitfenster in die Zukunft. Wenn ein Token zu weit in der Zukunft liegt, wird es abgewiesen (Sicherheitsmaßnahme).

Wichtig:
- Der Server akzeptiert TURN REST Credentials als Fallback **nur wenn** der Username nicht im CredentialStore gefunden wird.
- Ablauf/TTL:
  - `expiry` muss >= `now` sein
  - und `expiry - now <= rest_max_ttl_seconds`

## Lokal Tokens generieren (ohne Backend)

Das Repo enthält ein kleines CLI:

- Binary: [src/bin/turn_rest_cred.rs](../src/bin/turn_rest_cred.rs)

Beispiele:

1) Einfach (stdout als ENV-Zeilen)

`cargo run --bin turn_rest_cred -- --secret "SUPER_SECRET" --user alice --ttl 600`

2) JSON Ausgabe

`cargo run --bin turn_rest_cred -- --secret "SUPER_SECRET" --user alice --ttl 600 --json`

Du erhältst:
- `username` → in WebRTC als `iceServers[].username`
- `credential` → in WebRTC als `iceServers[].credential`

## WebRTC Beispiel (Frontend)

Du setzt in deiner App typischerweise:

- URLs (mindestens UDP + TLS):
  - `turn:your-domain:3478?transport=udp`
  - `turn:your-domain:3478?transport=tcp`
  - `turns:your-domain:5349?transport=tcp`

und dann:
- `username`: vom Generator/Backend
- `credential`: vom Generator/Backend

## Betriebshinweise

- **Secret Rotation**: Plane Rotation (z.B. zwei Secrets parallel) – sonst brechen Tokens im Umlauf.
- **TTL klein halten**: 5–10 Minuten ist typisch.
- **Logs**: Niemals `secret` oder vollständige Credentials loggen.
- **Rate Limits/Quotas**: Unbedingt ergänzen (Open-Relay/Abuse vermeiden).