CalDAV: Support Basic auth; trim+validate UUID; deprecate query token via headers; ICS end time helper; docs+instructions updated

docs/caldav-setup.md

@@ -0,0 +1,121 @@
+# CalDAV-Kalender Einrichtung
+
+## Übersicht
+
+Die App bietet einen CalDAV-Endpunkt, um Buchungen in externe Kalender-Apps zu synchronisieren. Aus Sicherheitsgründen erfolgt die Authentifizierung per Header. Unterstützt werden:
+
+- Authorization: Bearer <TOKEN>
+- Basic Auth, wobei der Token als Benutzername übergeben wird (Passwort leer/optional)
+
+## Token generieren
+
+1. Als Admin einloggen
+2. Im Admin-Bereich den CalDAV-Token generieren
+3. Token und URL werden angezeigt
+
+**Wichtig:** Der Token ist 24 Stunden gültig. Danach muss ein neuer Token generiert werden.
+
+## Endpunkt
+
+```
+GET /caldav/calendar/events.ics
+Authorization: Bearer <TOKEN>
+
+oder
+
+Authorization: Basic <base64(token:)>   # Token als Benutzername, Passwort leer
+```
+
+## Unterstützte Kalender-Apps
+
+### ✅ Thunderbird (empfohlen)
+
+1. Kalender → Neuer Kalender → Im Netzwerk
+2. Format: CalDAV
+3. Standort: CalDAV-URL eingeben
+4. Benutzername: Den generierten Token eingeben (Basic Auth)
+5. Passwort: Leer lassen
+
+### ✅ Outlook (mit Einschränkungen)
+
+1. Datei → Kontoeinstellungen → Internetkalender
+2. URL eingeben
+3. Erweiterte Einstellungen → Benutzerdefinierte Header:
+   ```
+   Authorization: Bearer <TOKEN>
+   ```
+
+**Hinweis:** Nicht alle Outlook-Versionen unterstützen benutzerdefinierte Header.
+
+### ⚠️ Apple Calendar (eingeschränkt)
+
+Apple Calendar unterstützt keine Authorization-Header für Kalenderabonnements.
+
+**Alternativen:**
+- Manuelle ICS-Datei importieren (nicht automatisch aktualisiert)
+- CalDAV-Bridge verwenden (z.B. über Proxy)
+
+### ⚠️ Google Calendar (eingeschränkt)
+
+Google Calendar unterstützt keine Authorization-Header für URL-Abonnements.
+
+**Alternativen:**
+- Google Apps Script als Bridge verwenden
+- Manuelle ICS-Datei importieren
+
+## Testen mit cURL
+
+```bash
+# Bearer
+curl -H "Authorization: Bearer <DEIN_TOKEN>" \
+  https://deine-domain.de/caldav/calendar/events.ics
+
+# Basic (Token als Benutzername, Passwort leer)
+curl -H "Authorization: Basic $(printf "%s" "<DEIN_TOKEN>:" | base64)" \
+  https://deine-domain.de/caldav/calendar/events.ics
+```
+
+Erwartete Antwort: ICS-Datei mit allen bestätigten und ausstehenden Buchungen.
+
+## Sicherheit
+
+### Warum Authorization-Header?
+
+- **Query-Parameter** (`?token=...`) werden in Browser-History, Server-Logs und Referrer-Headers gespeichert
+- **Authorization-Header** werden nicht geloggt und nicht in der URL sichtbar
+- Folgt REST-API Best Practices
+
+### Token-Verwaltung
+
+- Token sind 24 Stunden gültig
+- Abgelaufene Token werden automatisch beim nächsten Zugriff gelöscht
+- Bei Bedarf neuen Token generieren (alte Token werden nicht automatisch invalidiert)
+
+### Backward Compatibility
+
+Die alte Methode mit Query-Parameter (`?token=...`) wird noch unterstützt, aber als **deprecated** markiert. Der Server sendet zusätzlich Response-Header (`Deprecation: true` und `Warning: 299 ...`). Eine Warnung wird im Server-Log ausgegeben.
+
+## Troubleshooting
+
+### "Unauthorized - Token required"
+
+- Prüfe, ob der Authorization-Header korrekt gesetzt ist
+- Format: `Authorization: Bearer <TOKEN>` (mit Leerzeichen nach "Bearer")
+
+### "Unauthorized - Invalid or expired token"
+
+- Token ist abgelaufen (24h Gültigkeit)
+- Generiere einen neuen Token im Admin-Bereich
+
+### Kalender zeigt keine Termine
+
+- Prüfe, ob Buchungen mit Status "confirmed" oder "pending" existieren
+- Teste den Endpunkt mit cURL
+- Prüfe Server-Logs auf Fehler
+
+## Zukünftige Verbesserungen
+
+- [ ] Langlebige Token mit Refresh-Mechanismus
+- [ ] Token-Revocation-Endpoint
+- [ ] CalDAV-Bridge für Apple Calendar und Google Calendar
+- [ ] Webhook-basierte Push-Notifications statt Polling