# API Authentication Guide

## Übersicht

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

### 1. Admin-Routes (Bearer Token)
- **Zweck**: Geschützte Admin-Funktionen (Deletion Log, Cleanup, Moderation, Statistics)
- **Methode**: Bearer Token im Authorization Header
- **Konfiguration**: `.env` → `ADMIN_API_KEY`

### 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. **Sicheren Admin-Key generieren**:
   ```bash
   # Linux/Mac:
   openssl rand -hex 32
   
   # Oder Node.js:
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   ```

2. **In `.env` eintragen**:
   ```env
   ADMIN_API_KEY=dein-generierter-key-hier
   ```

3. **Server neu starten**

### Verwendung

Alle Requests an `/api/admin/*` benötigen den Authorization Header:

```bash
curl -H "Authorization: Bearer dein-generierter-key-hier" \
     http://localhost:5000/api/admin/deletion-log
```

**Postman/Insomnia**:
- Type: `Bearer Token`
- Token: `dein-generierter-key-hier`

### Geschützte Endpoints

| 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/management-audit` | GET | Management Audit Log |
| `/api/admin/groups` | GET | Alle Gruppen (Moderation) |
| `/api/admin/groups/:id/approve` | PUT | Gruppe freigeben |
| `/api/admin/groups/:id` | DELETE | Gruppe löschen |

### Error Codes

| Status | Bedeutung |
|--------|-----------|
| `403` | Authorization header fehlt oder ungültig |
| `500` | ADMIN_API_KEY nicht konfiguriert |

---

## 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

**Admin-Route ohne Auth**:
```bash
curl http://localhost:5000/api/admin/deletion-log
# → 403 Forbidden
```

**Admin-Route mit Auth**:
```bash
curl -H "Authorization: Bearer your-key" \
     http://localhost:5000/api/admin/deletion-log
# → 200 OK
```

---

## Production Checklist

- [ ] `ADMIN_API_KEY` mit sicherem 64-Zeichen Key setzen
- [ ] `.env` nicht in Git committen (bereits in `.gitignore`)
- [ ] HTTPS verwenden (TLS/SSL)
- [ ] Rate Limiting aktiviert prüfen
- [ ] Audit Logs regelmäßig überprüfen
- [ ] Token-Rotation Policy für Admin-Key implementieren

---

## Sicherheits-Hinweise

### Admin-Key Rotation

Admin-Key regelmäßig erneuern (z.B. alle 90 Tage):

1. Neuen Key generieren
2. `.env` aktualisieren
3. Server neu starten
4. Alte Clients auf neuen Key umstellen

### 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

- Admin-Key **nie** im Code hart-kodieren
- Admin-Key **nie** in Logs/Errors ausgeben
- Requests über HTTPS (kein Plain-HTTP in Production)
- Rate-Limiting für beide Auth-Typen aktiv
- Audit-Logs regelmäßig auf Anomalien prüfen