hobbyhimmel/Project-Image-Uploader
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
80aca79b32
Project-Image-Uploader/FeatureRequests/FEATURE_PLAN-security.md
matthias.lotz 6332b82c6a Feature Request: admin session security 
- replace bearer auth with session+CSRF flow and add admin user directory

- update frontend moderation flow, force password change gate, and new CLI

- refresh changelog/docs/feature plan + ensure swagger dev experience
2025-11-23 21:18:42 +01:00

5.6 KiB
Raw Blame History

Feature Plan: Server-seitige Sessions für Admin-API

Kontext

  • Ziel: Admin-API auf serverseitige Sessions mit CSRF-Schutz umstellen, Secrets ausschließlich backendseitig halten.
  • Initialer Admin wird über einen Setup-Wizard in der Admin-UI angelegt; weitere Admins werden in einer neuen admin_users-Tabelle verwaltet.
  • Session-Cookies (HttpOnly, Secure, SameSite=Strict) und SQLite-basierter Session-Store.

Annahmen & Randbedingungen

  1. Backend nutzt weiterhin SQLite; Session-Daten liegen in separater Datei (sessions.sqlite).
  2. Session-Secret (ADMIN_SESSION_SECRET) bleibt als ENV-Variable im Backend.
  3. Frontend authentifiziert sich ausschließlich via Session-Cookie + X-CSRF-Token; keine Bearer-Tokens im Browser.
  4. Initialer Admin wird per UI-Wizard erstellt; falls Wizard nicht verfügbar ist, gibt es ein Fallback-CLI/Script.
  5. AUTHENTICATION.md und frontend/MIGRATION-GUIDE.md sind maßgebliche Dokumente für Auth-Flow.

Aufgaben-Backlog

  • Session Store & Konfiguration

    • express-session + connect-sqlite3 installieren und konfigurieren.
    • Session-Datei z. B. unter backend/src/data/sessions.sqlite speichern.
    • Cookie-Flags gemäß Prod/Dev setzen.

  • Admin User Datenbank

    • Migration / Schema für admin_users inkl. Passwort-Hash (bcrypt) und Meta-Feldern.
    • Seed-/Wizard-Mechanismus für ersten Admin.

  • Login / Logout Endpoints

    • POST /auth/login prüft Credentials gegen DB.
    • POST /auth/logout zerstört Session + Cookie.
    • Bei Login req.session.user + req.session.csrfToken setzen.

  • CSRF Token & Middleware

    • GET /auth/csrf-token (nur authentifizierte Sessions).
    • Middleware requireCsrf für mutierende Admin-/System-Routen.

  • Initial Admin Setup Flow (Backend)

    • GET /auth/setup/status liefert { needsSetup: boolean } basierend auf Admin-Anzahl.
    • POST /auth/setup/initial-admin erlaubt das Anlegen des ersten Admins (nur wenn needsSetup true).
    • UI-Wizard ruft Status ab, zeigt Formular und loggt Admin optional direkt ein.

Endpoint-Konzept

  • POST /auth/setup/initial-admin

    • Body: { username, password } (optional passwordConfirm auf UI-Seite validieren).
    • Backend: prüft, dass keine aktiven Admins existieren, erstellt Nutzer (bcrypt Hash) und markiert Session als eingeloggt.
    • Response: { success: true, csrfToken } und setzt Session-Cookie.

  • GET /auth/setup/status

    • Response: { needsSetup: true|false } plus optional hasSession: boolean.

  • POST /auth/login

    • Body: { username, password }.
    • Checks: User aktiv, Passwort korrekt (bcrypt.compare), optional Rate-Limit.
    • Side-effects: req.session.user = { id, username, role }, req.session.csrfToken = randomHex(32).
    • Response: { success: true, csrfToken } (Cookie kommt automatisch).

  • POST /auth/logout

    • Destroys session, clears cookie, returns 204/200.

  • GET /auth/csrf-token

    • Requires valid session, returns { csrfToken } (regenerates when missing or ?refresh=true).

  • Middleware requireAdminSession

    • Prüft req.session.user?.role === 'admin' und optional is_active Flag.
    • Antwortet mit 403 + { reason: 'SESSION_REQUIRED' } wenn nicht vorhanden.

  • Middleware requireCsrf

    • Gilt für POST/PUT/PATCH/DELETE auf /api/admin/* & /api/system/*.
    • Erwartet Header x-csrf-token; vergleicht mit req.session.csrfToken.
    • Bei Fehler: 403 + { reason: 'CSRF_INVALID' }.

  • Frontend-Fluss

    • Nach Login/Setup: speichert gelieferten Token im State.
    • Für alle Admin-Requests: fetch(url, { method, credentials: 'include', headers: { 'X-CSRF-Token': token } }).
    • Wenn 401/403 wegen Session: UI zeigt Login.

  • Admin-Auth Middleware

    • /api/admin/* + /api/system/* prüfen Session (req.session.user.role === 'admin').
    • Alte Token-basierte Checks entfernen.
    • Ergänzt durch neue öffentliche Route GET /api/social-media/platforms (Upload/Management), während Admin-spezifische Plattform-Funktionen weiterhin über /api/admin/social-media/* laufen.

  • Frontend Admin Flow

    • adminApi.js auf credentials: 'include' + X-CSRF-Token umbauen.
    • Login-UI + Setup-Wizard für initialen Admin.
    • State-Handling für CSRF-Token (Hook/Context) via AdminSessionProvider + AdminSessionGate.

  • Secret-Handling & Docker

    • docker/prod/docker-compose.yml und Backend-Configs geben nur noch ADMIN_SESSION_SECRET an.
    • Frontend-Build enthält keine sensiblen .env-Dateien; Public env-config liefert ausschließlich non-sensitive Werte.
    • Deployment-Dokumentation (env.sh, README) beschreibt erlaubte Variablen.

  • Tests & CI

    • Jest-Suites decken Login/CSRF/Admin-Endpunkte ab (tests/api/*, tests/unit/auth.test.js).
    • Secret-Grep + Docker-Build-Schritt stellen sicher, dass das Frontend-Bundle keine Admin-Secrets enthält.

  • Mehrere Admins & CLI-Tooling

    • POST /api/admin/users + AdminAuthService.createAdminUser für zusätzliche Admins.
    • scripts/create_admin_user.sh automatisiert Initial-Setup & weitere Accounts via API.

  • Passwortrotation erzwingen

    • Flag requires_password_change, POST /auth/change-password, Frontend-Formular blockiert Dashboard bis zur Änderung.

  • Key-Leak Reaktionsplan

    • Anleitung (Scans, History-Cleanup, Rotation) dokumentieren bzw. verlinken.

  • Dokumentation

    • AUTHENTICATION.md, README(.dev) und frontend/MIGRATION-GUIDE.md beschreiben Session/CSRF-Flow.
    • Feature-Request-Referenzen zeigen auf neue Session-Implementierung.

  • Kommunikation & Review

    • Verweise auf relevante Patches/PRs ergänzen.
    • Reviewer-Hinweise (Testplan, Rollout) dokumentieren.