# API Authentication Guide

## Übersicht

Die API verwendet **zwei verschiedene Authentifizierungs-Mechanismen** für unterschiedliche Zugriffslevel:

### 1. Admin-Routes (Session + CSRF)
- **Zweck**: Geschützte Admin-Funktionen (Deletion Log, Cleanup, Moderation, Statistics)
- **Methode**: HTTP Session (Cookie) + CSRF-Token
- **Konfiguration**: `.env` → `ADMIN_SESSION_SECRET` (+ Admin-Benutzer in DB)

### 2. Management-Routes (UUID Token)
- **Zweck**: Self-Service Portal für Gruppen-Verwaltung
- **Methode**: UUID v4 Token in URL-Path
- **Quelle**: Automatisch generiert beim Upload, gespeichert in DB

---

## 1. Admin Authentication

### Setup

1. **Session Secret setzen**:
   ```env
   ADMIN_SESSION_SECRET=$(openssl rand -hex 32)
   ```
   > ℹ️  Standardmäßig setzt der Server in Production HTTPS-Only Cookies (`Secure`). Falls deine Installation **ohne HTTPS** hinter einem internen Netzwerk läuft, kannst du das Verhalten über `ADMIN_SESSION_COOKIE_SECURE=false` explizit deaktivieren. Verwende dies nur in vertrauenswürdigen Umgebungen und setze den Wert vorzugsweise per lokaler Compose-Override-Datei oder geheimen ENV-Variablen, damit das Repo weiterhin den sicheren Default `true` behält.
2. **Backend starten** – Migration legt Tabelle `admin_users` an.
3. **Setup-Status prüfen**:
   ```bash
   curl -c cookies.txt http://localhost:5000/auth/setup/status
   ```
4. **Initialen Admin anlegen** (nur wenn `needsSetup=true`):
   ```bash
   curl -X POST -H "Content-Type: application/json" \
        -c cookies.txt -b cookies.txt \
        -d '{"username":"admin","password":"SuperSicher123!"}' \
        http://localhost:5000/auth/setup/initial-admin
   ```
5. **Login für weitere Sessions**:
   ```bash
   curl -X POST -H "Content-Type: application/json" \
        -c cookies.txt -b cookies.txt \
        -d '{"username":"admin","password":"SuperSicher123!"}' \
        http://localhost:5000/auth/login
   ```
6. **CSRF Token abrufen** (für mutierende Requests):
   ```bash
   curl -b cookies.txt http://localhost:5000/auth/csrf-token
   ```

### Verwendung

Alle `/api/admin/*`- und `/api/system/*`-Routen setzen voraus:

1. Browser sendet automatisch das Session-Cookie (`sid`).
2. Für POST/PUT/PATCH/DELETE muss der Header `X-CSRF-Token` gesetzt werden.

Beispiel:

```bash
CSRF=$(curl -sb cookies.txt http://localhost:5000/auth/csrf-token | jq -r '.csrfToken')
curl -X PATCH \
     -H "Content-Type: application/json" \
     -H "X-CSRF-Token: $CSRF" \
     -b cookies.txt \
     -d '{"approved":true}' \
     http://localhost:5000/api/admin/groups/abc123/approve
```

### Geschützte Endpoints (Auszug)

| Endpoint | Method | Beschreibung |
|----------|--------|--------------|
| `/api/admin/deletion-log` | GET | Deletion Log Einträge |
| `/api/admin/deletion-log/csv` | GET | Deletion Log als CSV |
| `/api/admin/cleanup/run` | POST | Cleanup manuell starten |
| `/api/admin/cleanup/status` | GET | Cleanup Status |
| `/api/admin/rate-limiter/stats` | GET | Rate-Limiter Statistiken |
| `/api/admin/groups` | GET | Alle Gruppen (Moderation) |
| `/api/admin/groups/:id/approve` | PATCH | Gruppe freigeben |
| `/api/admin/groups/:id` | DELETE | Gruppe löschen |
| `/api/system/migration/*` | POST | Migrationswerkzeuge |

### Error Codes

| Status | Bedeutung |
|--------|-----------|
| `401` | Session fehlt oder ist abgelaufen |
| `403` | CSRF ungültig oder Benutzer hat keine Admin-Rolle |
| `419` | (optional) Session wurde invalidiert |

---

## 2. Management Authentication

### Setup

**Kein Setup nötig!** Token werden automatisch generiert.

### Funktionsweise

1. **Bei Upload** wird automatisch ein UUID v4 Token generiert
2. **Token wird gespeichert** in DB (Spalte: `management_token`)
3. **Token wird zurückgegeben** in der Upload-Response
4. **Nutzer erhält Link** wie: `https://example.com/manage/{token}`

### Verwendung

Token wird **im URL-Path** übergeben (nicht im Header):

```bash
# Token validieren und Daten laden
GET /api/manage/550e8400-e29b-41d4-a716-446655440000

# Bilder hochladen
POST /api/manage/550e8400-e29b-41d4-a716-446655440000/images

# Gruppe löschen
DELETE /api/manage/550e8400-e29b-41d4-a716-446655440000
```

### Geschützte Endpoints

| Endpoint | Method | Beschreibung |
|----------|--------|--------------|
| `/api/manage/:token` | GET | Gruppen-Daten laden |
| `/api/manage/:token/consents` | PUT | Social Media Consents |
| `/api/manage/:token/metadata` | PUT | Metadaten bearbeiten |
| `/api/manage/:token/images` | POST | Bilder hinzufügen |
| `/api/manage/:token/images/:imageId` | DELETE | Bild löschen |
| `/api/manage/:token` | DELETE | Gruppe löschen |

### Sicherheits-Features

- **Token-Format Validierung**: Nur gültige UUID v4 Tokens
- **Rate Limiting**: Schutz vor Brute-Force
- **Audit Logging**: Alle Aktionen werden geloggt
- **DB-Check**: Token muss in DB existieren

### Error Codes

| Status | Bedeutung |
|--------|-----------|
| `404` | Token nicht gefunden oder Gruppe gelöscht |
| `429` | Rate Limit überschritten |

---

## Testing

### Unit Tests

```bash
npm test -- tests/unit/auth.test.js
```

### Integration Tests

```bash
# Admin Auth testen
npm test -- tests/api/admin-auth.test.js

# Alle API Tests
npm test
```

### Manuelles Testen

1. **Login**:
   ```bash
   curl -c cookies.txt -X POST -H "Content-Type: application/json" \
        -d '{"username":"admin","password":"Secret123"}' \
        http://localhost:5000/auth/login
   ```
2. **CSRF holen**:
   ```bash
   CSRF=$(curl -sb cookies.txt http://localhost:5000/auth/csrf-token | jq -r '.csrfToken')
   ```
3. **Admin-Route aufrufen**:
   ```bash
   curl -b cookies.txt -H "X-CSRF-Token: $CSRF" http://localhost:5000/api/admin/deletion-log
   # → 200 OK
   ```
4. **Ohne Session** (z. B. Cookies löschen) → Request liefert `403 SESSION_REQUIRED`.

---

## Production Checklist

- [ ] `ADMIN_SESSION_SECRET` sicher generieren (>= 32 Bytes random)
- [ ] `.env` nicht in Git committen (bereits in `.gitignore`)
- [ ] HTTPS verwenden (TLS/SSL) damit Cookies `Secure` gesetzt werden können (falls nicht möglich: `ADMIN_SESSION_COOKIE_SECURE=false` setzen – nur in vertrauenswürdigen Netzen)
- [ ] Session-Store auf persistentem Volume ablegen
- [ ] Rate Limiting & Audit Logs überwachen
- [ ] Admin-Benutzerverwaltung (On-/Offboarding) dokumentieren

---

## Sicherheits-Hinweise

### Session-Secret Rotation

1. Wartungsfenster planen (alle Sessions werden invalidiert)
2. Neuen `ADMIN_SESSION_SECRET` generieren
3. `.env` aktualisieren und Backend neu starten

### Management-Token

- Token sind **permanent gültig** bis Gruppe gelöscht wird
- Bei Verdacht auf Leak: Gruppe löschen (löscht auch Token)
- Token-Format (UUID v4) macht Brute-Force unpraktisch

### Best Practices

- Keine Admin-Secrets im Frontend oder in Repos committen
- Admin-Session-Cookies nur über HTTPS ausliefern
- Rate-Limiting für beide Auth-Typen aktiv halten
- Audit-Logs regelmäßig auf Anomalien prüfen
- Session-Store-Backups schützen (enthalten Benutzer-IDs)