matthias.lotz
6332b82c6a
- 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
110 lines
5.6 KiB
Markdown
110 lines
5.6 KiB
Markdown
# 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.
|