FEATURE_REQUEST: Security — Server-seitige Sessions für Admin-API

Umsetzungsaufgaben (konkret & eindeutig für KI / Entwickler)

Die folgenden Aufgaben sind Schritt-für-Schritt auszuführen. Jede Aufgabe enthält das gewünschte Ergebnis und minimalen Beispielcode oder Befehle. Die KI/Entwickler sollen die Änderungen als Code-Patches anlegen, Tests hinzufügen und die Dokumentation aktualisieren.

Session-Store & Session-Konfiguration

Ziel: Server-seitige Sessions für Admin-Login verfügbar machen.

Schritte:

Installiere Packages: npm install express-session connect-sqlite3 --save (Backend).

In backend/src/server.js (oder Entrypoint) konfiguriere express-session mit connect-sqlite3:

const session = require('express-session');
const SQLiteStore = require('connect-sqlite3')(session);
app.use(session({
  store: new SQLiteStore({ db: 'sessions.sqlite' }),
  secret: process.env.ADMIN_SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { httpOnly: true, secure: process.env.NODE_ENV === 'production', sameSite: 'Strict', maxAge: 8*60*60*1000 }
}));

Abnahme: Session-Cookie (sid) wird gesetzt nach Login, cookie-Flags korrekt.

Login-Endpoint (Admin)
- Ziel: Admin kann sich mit Benutzername/Passwort anmelden; Backend erstellt Session.
- Schritte:
  - Füge POST /auth/login hinzu, prüft Credentials (z. B. gegen environment-stored admin user/pass oder htpasswd), legt req.session.user = { role: 'admin' } an und req.session.csrfToken = randomHex() an.
  - Rückgabe: 200 OK. Cookie wird automatisch gesetzt (credentials: 'include' vom Frontend).
- Abnahme: Nach POST /auth/login existiert req.session.user und req.session.csrfToken.
CSRF-Endpoint + Middleware
- Ziel: Session-gebundenen CSRF-Token ausgeben und Requests schützen.
- Schritte:
  - Endpoint GET /auth/csrf-token gibt { csrfToken: req.session.csrfToken } zurück (nur wenn eingeloggt).
  - Middleware requireCsrf prüft req.headers['x-csrf-token'] === req.session.csrfToken für state-changing Methoden.
- Abnahme: state-changing Admin-Requests ohne oder mit falschem X-CSRF-Token bekommen 403.
Backend-Auth-Middleware für Admin-API
- Ziel: Alle /api/admin/* Endpoints prüfen Session statt Client-Token.
- Schritte:
  - Ersetze oder erweitere bestehende Admin-Auth-Middleware (middlewares/auth.js) so, dass sie req.session.user && req.session.user.role === 'admin' prüft; falls nicht gesetzt → 403.
- Abnahme: GET /api/admin/* ohne Session → 403; mit gültiger Session → durchgelassen.
Frontend-Änderungen (adminApi)
- Ziel: Frontend sendet keine Admin-Bearer-Tokens mehr; verwendet Cookie-Session + CSRF-Header.
- Schritte:
  - Entferne in frontend/src/services/adminApi.js die Abhängigkeit von process.env.REACT_APP_ADMIN_API_KEY.
  - Passe adminFetch/adminRequest an: bei Requests setze credentials: 'include' und füge X-CSRF-Token Header (Token bezieht Frontend über GET /auth/csrf-token nach Login).
  - Dokumentiere in frontend/README oder Code-Kommentar, dass Admin-UI nach Login fetch('/auth/csrf-token', { credentials: 'include' }) aufruft.
- Abnahme: adminApi.js sendet keine Bearer-Header; admin Requests beinhalten credentials: 'include' und X-CSRF-Token.
Entfernen von Admin-Key aus Frontend Build/Compose/Dockerfile
- Ziel: Keine Weitergabe von ADMIN_API_KEY an frontend und kein Kopieren sensibler .env in Frontend-Image.
- Schritte:
  - Entferne Zeile - REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY} aus docker/prod/docker-compose.yml.
  - Entferne COPY docker/prod/frontend/config/.env ./.env aus docker/prod/frontend/Dockerfile oder stelle sicher, dass diese Datei ausschließlich non-sensitive Keys enthält.
  - Dokumentiere in FeatureRequests/FEATURE_REQUEST-security.md welche Keys im runtime-env.sh erlaubt sind (z. B. API_URL, APP_VERSION).
- Abnahme: docker-compose enthält keine Übergabe an frontend; Build und Image enthalten keine Production-Secrets.
Secrets-Handling / Deployment
- Ziel: Secrets nur in Backend-Umgebung bereitstellen.
- Schritte:
  - Setze ADMIN_API_KEY und ADMIN_SESSION_SECRET in CI/CD Secrets oder Docker Secrets und referenziere sie nur im backend Service.
  - Beispiel-Dokumentation für CI: wie man Secret in GitLab/GitHub Actions setzt und an Container übergibt.
- Abnahme: Secrets sind nicht in Repo/Images; docker inspect der frontend-Container zeigt keinen Admin-Key.
Tests & CI-Checks
- Ziel: Automatisierte Verifikation der Sicherheitsregeln.
- Schritte:
  - Integrationstest 1: GET /api/admin/some ohne Session → expect 403.
  - Integrationstest 2: POST /auth/login with admin credentials → expect Set-Cookie; then GET /auth/csrf-token → receive token; then POST /api/admin/action with X-CSRF-Token → expect 200.
  - Build-scan-Check: CI Schritt rg REACT_APP_ADMIN_API_KEY build/ || true fails if found.
- Abnahme: Tests grün; CI verweigert Merge wenn Build enthält Admin-Key.
Key-Leak Reaktion (konkrete Anweisungen)
- Ziel: Falls ein Admin-Key geleakt wurde, sichere, koordinierte Rotation.
- Schritte:
  - Scannen: trufflehog --regex --entropy=True . oder git-secrets scan.
  - Entfernen: git-filter-repo --replace-text passwords.txt oder bfg --replace-text passwords.txt (siehe docs).
  - Rotation: Erzeuge neuen Key (openssl rand -hex 32), update CI secret, redeploy Backend.
- Hinweis: History-Rewrite ist invasiv; kommuniziere mit Team und informiere Contributors.
Dokumentation

Ziel: Abschlussdokumentation aktualisiert.
Schritte:
- Ergänze AUTHENTICATION.md um Login/Session/CSRF-Flow und Secret-Handling.
- Ergänze FeatureRequests/FEATURE_REQUEST-security.md mit Implementations-Links (Patches/PRs).

MIGRATION-GUIDE Anpassung (unbedingt)

Ziel: Die frontend/MIGRATION-GUIDE.md spiegelt nicht mehr den sicheren Produktions-Workflow. Sie muss aktualisiert werden, damit Entwickler/KI keine unsicheren Anweisungen (Admin-Key im Frontend) ausführen.
Aktueller Stand (zu prüfen): Die MIGRATION-GUIDE enthält Anweisungen, REACT_APP_ADMIN_API_KEY in frontend/.env zu setzen und dieselbe Variable an frontend im docker-compose.yml weiterzugeben. Dies steht im direkten Widerspruch zur hier geforderten serverseitigen Session-Lösung.
Erforderliche Änderungen in frontend/MIGRATION-GUIDE.md (konkret):
- Entferne oder ersetze alle Anweisungen, die REACT_APP_ADMIN_API_KEY in Frontend .env oder Build-Umgebungen für Production setzen.
- Ersetze Fetch-/Axios-Beispiele, die Authorization: Bearer ${process.env.REACT_APP_ADMIN_API_KEY} setzen, durch die neue Anleitung: Login → GET /auth/csrf-token → fetch(..., { credentials: 'include', headers: { 'X-CSRF-Token': csrfToken } }).
- Passe das Docker-Beispiel an: ADMIN_API_KEY darf nur dem backend-Service übergeben werden; entferne die Weitergabe an frontend (Zeile - REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY}).
- Ersetze lokale Testanweisungen, die Frontend mit REACT_APP_ADMIN_API_KEY starten, durch Login-/Session-Testschritte (siehe Tasks 2/3/8).
- Ergänze Hinweis zur CI/Build-Scan-Prüfung: CI muss prüfen, dass gebaute build/ keine Admin-Key-Strings enthält.
Abnahme: frontend/MIGRATION-GUIDE.md enthält keine Production-Anweisungen, die Admin-Secrets ins Frontend bringen; stattdessen ist der Session-Flow dokumentiert und verlinkt.

Hinweis für die Implementierung

Ergänze in FeatureRequests/FEATURE_REQUEST-security.md einen Link/Verweis zur überarbeiteten MIGRATION-GUIDE-Version in der PR/Release-Notes, damit Reviewer die Änderung nachvollziehen können.

Rolle der implementierenden KI/Dev

Erzeuge konkrete Code-Patches, führe lokale Tests aus, öffne PR mit Änderungen und Tests.
Stelle sicher, dass alle Abnahme-Kriterien (oben) automatisiert oder manuell prüfbar sind.

Mit diesen Aufgaben sind die vorher offenen Fragen in eindeutige, ausführbare Schritte übersetzt. Bitte bestätige, welche Aufgaben ich automatisch umsetzen soll (z. B. 1 = Compose/Docker-Änderungen; 2 = Frontend adminApi.js Patch; 3 = Backend Session+CSRF minimal-Implementierung; oder all).

Hintergrund (Ist-Stand)

Aktuell existieren folgende sicherheitskritische Zustände im Repository:
- frontend/.env enthält REACT_APP_ADMIN_API_KEY in der Arbeitskopie (lokal). Die Datei ist in .gitignore und wird nicht ins Git-Repository getrackt, ist aber sensibel und darf nicht in Builds/Images gelangen.
- docker/prod/docker-compose.yml injiziert REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY} in den frontend-Service — der Key kann so in den gebauten Frontend-Bundles landen.
- frontend/src/services/adminApi.js liest process.env.REACT_APP_ADMIN_API_KEY und sendet den Bearer-Token clientseitig mit Admin-Requests.
- Das Production-Frontend-Dockerfile kopiert docker/prod/frontend/config/.env in das Laufzeit-Image und führt zur Startzeit ein env.sh aus, das env-config.js erzeugt (window._env_), was sensible Werte im Browser verfügbar machen kann, falls sie in .env landen.
- Die Moderation-Weboberfläche ist zusätzlich durch htpasswd/nginx HTTP Basic Auth geschützt — das schützt das UI, aber nicht die API-Endpoints ausreichend.

Problemstellung (warum es ein Problem ist)

Ein im Frontend sichtbarer Admin-Key ist öffentlich und ermöglicht Missbrauch (API-Calls mit Admin-Rechten von jedem Browser).
Das serverseitige Secret ADMIN_API_KEY wird derzeit in Artefakte/Images injiziert und kann geleakt werden.
HTTP Basic Auth vor der UI ist nützlich, aber kein Ersatz für serverseitige API-Authentifizierung; API-Endpunkte müssen eigenständig prüfen.

Ziel (Soll-Stand, aus Kundensicht)

Admin-Funktionen sind nur nach sicherer Anmeldung erreichbar.
Der geheime Admin-Key verbleibt ausschließlich auf dem Server/Backend und wird nicht in Frontend-Code, Images oder öffentlich zugängliche Dateien geschrieben.
Frontend kommuniziert nach Anmeldung mit dem Backend, ohne je den Admin-Key im Browser zu speichern.

Anforderungen (aus Sicht des Auftraggebers, umsetzbar durch eine KI)

Authentifizierung:
- Einführung eines serverseitigen Login-Flows für Admins (Session-Cookies, HttpOnly, Secure, SameSite).
- Nach erfolgreicher Anmeldung erhält der Admin-Browser ein HttpOnly-Cookie; dieses Cookie erlaubt Zugriff auf geschützte /api/admin/*-Endpoints.
- Backend validiert alle /api/admin/*-Requests anhand der Session; nur dann wird mit dem internen ADMIN_API_KEY gearbeitet.
Secrets & Build:
- Keine Secrets (z. B. ADMIN_API_KEY) im Frontend-Quellcode, in frontend/.env, in env-config.js oder in gebauten Bundles.
- docker/prod/docker-compose.yml darf ADMIN_API_KEY nur dem backend-Service bereitstellen; keine Weitergabe an frontend.
- Dockerfile des Frontends darf keine Produktion-.env kopieren, die Secrets enthält.
Betrieb & Infrastruktur:
- Bestehende htpasswd-Absicherung der Admin-UI kann beibehalten werden als zusätzliche Hürde, ist aber nicht die einzige Schutzmaßnahme.
- Empfehlung: ADMIN_API_KEY über sichere Secret-Mechanismen bereitstellen (CI/CD secret store, Docker Secrets, Swarm/K8s Secrets) — dies ist ein Hinweis, keine Pflichtanweisung.

Akzeptanzkriterien (klar messbar, für Tests durch eine KI/Dev)

Funktional:
- Unauthentifizierte Requests an /api/admin/* erhalten 403 Forbidden.
- Admin-Login-Endpoint existiert und setzt ein HttpOnly-Cookie; angemeldete Admins erreichen /api/admin/* erfolgreich.
Artefakte / Repo:
- frontend-Bundle (der gebaute build/-Ordner) enthält nicht den Wert von ADMIN_API_KEY (automatischer Scan: kein Vorkommen des Key-Strings).
- frontend/.env enthält keine REACT_APP_ADMIN_API_KEY-Zeile in Produktion; docker/prod/docker-compose.yml enthält keine Weitergabe des Keys an frontend.
Sicherheit & Ops:
- Dokumentation: In AUTHENTICATION.md und in dieser Feature-Request-Datei wird der neue Login-Flow und Hinweis zum Secret-Handling vermerkt.
- Dokumentation: In AUTHENTICATION.md und in dieser Feature-Request-Datei wird der neue Login-Flow und Hinweis zum Secret-Handling vermerkt.
- Falls ein Key im Git-Verlauf existierte, ist die Rotation des Admin-Keys als Handlungsempfehlung dokumentiert.
- Falls frontend/.env oder ein Admin-Key jemals in das Repository gelangt ist: Scannt die Git-History und entfernt das Secret aus der History, danach rotiert den Key. Empfohlene Tools/Schritte (kurz):
  - Finden: git log --all -S 'part-of-key' oder git grep -n "REACT_APP_ADMIN_API_KEY" $(git rev-list --all) oder nutzen truffleHog/git-secrets.
  - Entfernen aus History: git-filter-repo oder bfg-repo-cleaner (z.B. bfg --replace-text passwords.txt --no-blob-protection) — danach Force-Push in ein neues Remote (Achtung: Auswirkungen auf Contributors).
  - Key-Rotation: Erzeuge neuen ADMIN_API_KEY, setze ihn in der sicheren Backend-Umgebung (CI/CD secrets / Docker secret), redeploye Backend.
  - Hinweis: Diese Schritte sind invasiv für die Git-History; koordinieren mit Team bevor Ausführung.

Nicht-funktionale Anforderungen

Use Session-Cookies: Cookies müssen HttpOnly, Secure und SameSite=Strict (oder Lax falls nötig) gesetzt werden.
CSRF-Schutz: Bei Cookie-basierten Sessions muss ein CSRF-Schutzmechanismus vorhanden sein (z. B. double-submit-token oder CSRF-Header). Hinweis: CSRF-Mechanik ist zu implementieren, aber detaillierte Schritte sind nicht Teil dieses Requests.
Kompatibilität: Änderungen dürfen Entwickler-Workflows nicht unnötig blockieren; Dev-Mode-Patterns (runtime env-config.js in docker/dev) können bestehen bleiben, jedoch klar getrennt von Prod.

Hinweise für die implementierende KI / das Dev-Team (kontextbezogen)

Aktueller Code-Pfade von Relevanz:
- frontend/src/services/adminApi.js — liest aktuell process.env.REACT_APP_ADMIN_API_KEY und setzt den Bearer-Token clientseitig.
- frontend/.env — enthält aktuell REACT_APP_ADMIN_API_KEY.
- docker/prod/docker-compose.yml — injiziert REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY} in frontend.
- docker/prod/frontend/Dockerfile — kopiert docker/prod/frontend/config/.env in das Image und führt env.sh aus, das env-config.js erzeugt (window._env_).
- docker/prod/frontend/config/env.sh — generiert zur Laufzeit env-config.js aus .env.
- docker/prod/frontend/config/htpasswd — existierender Schutz der Admin-UI via nginx.
Erwartung an eine KI-Implementierung:
- Verstehe die Codebasis (insbesondere frontend/src/* und backend/src/*) und identifiziere alle Stellen, die REACT_APP_ADMIN_API_KEY oder ADMIN_API_KEY verwenden oder weiterreichen.
- Entferne clientseitige Verwendung des Admin-Keys; ersetze Aufrufe an Admin-API so, dass sie serverseitig autorisiert werden (Session-Check).
- Verifiziere durch automatische Tests (Integrationstest oder API-Call) dass /api/admin/* ohne Session abgewiesen wird und mit Session funktioniert.

Was der Auftraggeber (Ich) erwartet — kurz und klar

Die Admin-Funktionen sind nur nach Anmeldung verfügbar.
Keine Admin-Secrets gelangen in Frontend-Bundles, Images oder öffentlich zugängliche Dateien.
Der existierende htpasswd-Schutz darf bestehen bleiben, ist aber nicht alleinige Sicherheitsmaßnahme.

Abnahmekriterien (für das Review durch den Auftraggeber)

Manuelle Überprüfung: Versuch, Admin-Endpoints ohne Login aufzurufen → 403.
Build-Review: gebaute Frontend-Dateien enthalten keinen Admin-Key.
Dokumentation aktualisiert (AUTHENTICATION.md weist auf neue Session-Flow hin).

Offene Fragen / Optionen (für Entwickler/KI) — Empfehlung und Umsetzungsdetails

Session-Store (empfohlen: SQLite für Single-Host, Redis für Skalierung)
- Empfehlung für diese App: SQLite / file-basierter Session-Store (einfach zu betreiben, keine zusätzliche Infrastruktur).
- Umsetzung (Express): benutze express-session + connect-sqlite3 (oder better-sqlite3 backend). Konfiguration:
  - Session-Cookie: HttpOnly, Secure (Prod), SameSite=Strict (oder Lax wenn externe callbacks nötig), maxAge angemessen (z. B. 8h).
  - Session-Secret aus sicherer Quelle (Backend ADMIN_SESSION_SECRET), nicht im Repo.
- Skalierung: falls Cluster/Multiple hosts geplant, wechsle zu Redis (z.B. connect-redis) und setze Redis via Docker/K8s Secret.
CSRF-Mechanik (empfohlen: session-bound CSRF token + Header)
- Empfehlung: Implementiere einen session-gebundenen CSRF-Token. Ablauf:
  1. Bei Login: generiere req.session.csrfToken = randomHex() auf dem Server.
  2. Exponiere Endpoint GET /auth/csrf-token (nur für eingeloggte Sessions), der das Token im JSON zurückgibt.
  3. Frontend ruft /auth/csrf-token nach Login (credentials: 'include') und speichert Token im JS-Scope.
  4. Bei state-changing Requests sendet Frontend X-CSRF-Token: <token> Header.
  5. Server-Middleware vergleicht Header mit req.session.csrfToken und verwirft bei Mismatch (403).
- Vorteil: HttpOnly-Session-Cookie bleibt geschützt; Token ist an Session gebunden.
- Alternative (schnell): Double-submit cookie (weniger robust, Token in non-HttpOnly cookie + Header); nur als kurzfristige Übergangslösung.
Entfernen von Admin-Key aus Frontend/Build (konkrete Änderungen)
- frontend/src/services/adminApi.js: entferne Nutzung von process.env.REACT_APP_ADMIN_API_KEY. Passe adminRequest so an, dass credentials: 'include' verwendet wird und kein Bearer-Token gesetzt wird.
- docker/prod/docker-compose.yml: lösche die Zeile - REACT_APP_ADMIN_API_KEY=${ADMIN_API_KEY} unter frontend.
- docker/prod/frontend/Dockerfile: entferne COPY docker/prod/frontend/config/.env ./.env (oder stelle sicher, dass die Datei keine Secrets enthält). Vermeide Prod .env Kopie in Image.
- docker/prod/frontend/config/env.sh: darf nur non-sensitive Werte (z. B. API_URL, APP_VERSION) schreiben; dokumentiere welche Keys erlaubt sind.
Secrets-Delivery / Deployment
- Backend-Secret ADMIN_API_KEY und ADMIN_SESSION_SECRET via CI/CD Secret Store oder Docker Secrets bereitstellen.
- Beispiel (Docker secret): erstelle Secret im Swarm/K8s und referenziere es nur im backend-Service.
Tests / Abnahme (automatisierbar)
- Integrationstest 1: GET /api/admin/* ohne Session → 403.
- Integrationstest 2: Login-Flow → setze Session-Cookie → POST /api/admin/* mit gültigem X-CSRF-Token → 200.
- Build-Scan: nach Build grep -R "<part-of-admin-key>" build/ oder rg REACT_APP_ADMIN_API_KEY build/ → kein Treffer.
Key-Leak Reaktion
- Falls Key geleakt: sofort Key-Rotation, dokumentiere wie (generate new key, update backend secret, redeploy), und führe Git-History-Check wie in Abschnitt oben durch.
Operationale Hinweise
- Behalte htpasswd-Schutz für Admin-UI als zusätzliche Zugangskontrolle, nicht als einzige Schutzmaßnahme.
- Dokumentiere alle Änderungen in AUTHENTICATION.md und in Release-Notes.

Diese Empfehlungen sind aus Sicht einer sicheren, pragmatischen Umsetzung gewählt: sie minimieren Infrastruktur-Overhead (SQLite) und bieten klare, testbare CSRF/Session‑Mechaniken. Eine implementierende KI soll die obenstehenden Punkte in konkreten Code‑Patches umsetzen und automatisierte Tests hinzufügen.

Kontakt / Kontext

Repo: Project-Image-Uploader — bestehende Struktur docker/prod, frontend/, backend/ beachten.
Hinweis: Diese Feature-Request-Datei benennt Missstände und Anforderungen; sie erwartet, dass ein Entwickler oder eine KI die Implementierung auf Code-Ebene vornimmt.

20 KiB Raw Blame History Unescape Escape

FEATURE_REQUEST: Security — Server-seitige Sessions für Admin-API

20 KiB

Raw Blame History