Project-Image-Uploader/AUTHENTICATION.md

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:

   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:

   curl -c cookies.txt http://localhost:5000/auth/setup/status
   

4. Initialen Admin anlegen (nur wenn needsSetup=true):

   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:

   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):

   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:

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):

# 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

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

Integration Tests

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

# Alle API Tests
npm test

Manuelles Testen

1. Login:

   curl -c cookies.txt -X POST -H "Content-Type: application/json" \
        -d '{"username":"admin","password":"Secret123"}' \
        http://localhost:5000/auth/login
   

2. CSRF holen:

   CSRF=$(curl -sb cookies.txt http://localhost:5000/auth/csrf-token | jq -r '.csrfToken')
   

3. Admin-Route aufrufen:

   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)