Project-Image-Uploader/AUTHENTICATION.md

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:

   # Linux/Mac:
   openssl rand -hex 32
   
   # Oder Node.js:
   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

2. In .env eintragen:

   ADMIN_API_KEY=dein-generierter-key-hier
   

3. Server neu starten

Verwendung

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

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

# 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

Admin-Route ohne Auth:

curl http://localhost:5000/api/admin/deletion-log
# → 403 Forbidden

Admin-Route mit Auth:

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