Project-Image-Uploader/FeatureRequests/FEATURE_PLAN-security.md

# 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
- [x] **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.

- [x] **Admin User Datenbank**
  - Migration / Schema für `admin_users` inkl. Passwort-Hash (bcrypt) und Meta-Feldern.
  - Seed-/Wizard-Mechanismus für ersten Admin.

- [x] **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.

- [x] **CSRF Token & Middleware**
  - `GET /auth/csrf-token` (nur authentifizierte Sessions).
  - Middleware `requireCsrf` für mutierende Admin-/System-Routen.
- [x] **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.

- [x] **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.

- [x] **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`.

- [x] **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.

- [x] **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.

- [x] **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.

- [x] **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.

- [x] **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.