README für internen Bereich komplett überarbeitet (D1-Architektur, Deploy-Anleitung, Sicherheitsmodell)

cloudflare-worker/README.md

@@ -1,95 +1,126 @@
-# DOGFATHER UNIVERSE — Bewerbungs-Postfach (Cloudflare Worker)
+# DOGFATHER UNIVERSE — Interner Bereich (Cloudflare Worker + D1)
 
-Dieser Worker nimmt Bewerbungen von `bewerben.html` entgegen und speichert sie in Cloudflare KV.
-Nur wer den richtigen Code kennt, kann sie über `postfach.html` einsehen — der Code wird
-**serverseitig** geprüft (nicht im Browser-Code sichtbar), das ist der eigentliche Schutz.
+Setzt das Anforderungsdokument **„Geschützter Zugang, Rollen und Benutzerverwaltung"**
+(`Geschuetzter_Zugang_Rollen_Benutzerverwaltung.pdf`) vollständig um: Session-basierte Anmeldung,
+verschlüsselte (aber für Dogi jederzeit einsehbare) Zugangscodes, frei konfigurierbare Rollen mit
+granularen Rechten, individuelle Ausnahmen pro Person, Aktivitätsprotokoll, Login-Lockout.
 
-Kosten: läuft im kostenlosen Cloudflare-Tier (Workers Free + KV Free reichen für dieses Volumen locker).
+Kosten: läuft im kostenlosen Cloudflare-Tier (Workers Free, D1 Free, KV Free reichen locker).
 
 ## ✅ Bereits deployed
 
-Läuft schon unter: https://dogfather-universe-postfach.dogfather1608.workers.dev
-(Health-Check: `/health`). Die Website (`assets/js/forms.js`, `index.html`, `postfach.html`) zeigt
-bereits auf diese URL — die Schritte unten sind nur nötig, falls der Worker mal neu aufgesetzt
-werden muss (z.B. anderer Account, Code vergessen und Secret-Reset gewünscht).
+- **Interner Worker:** https://dogfather-universe-postfach.dogfather1608.workers.dev (Health-Check: `/health`)
+- **D1-Datenbank:** `dogfather-universe-db`
+- Website (`postfach.html`, `zugaenge.html`, `assets/js/*.js`) zeigt bereits auf diese URL.
+
+Die Schritte unten sind nur nötig, falls der Worker mal neu aufgesetzt werden muss.
+
+## Architektur
+
+```
+src/worker.js              Router — verteilt Requests an die Handler unten
+src/lib/crypto.js          SHA-256-Hashing, AES-256-GCM-Verschlüsselung, ID/Token-Erzeugung
+src/lib/auth.js            Login-Prüfung, Sessions, Rate-Limiting/Lockout
+src/lib/permissions.js     Vollständiger Permission-Katalog aus dem Anforderungsdokument
+src/lib/audit.js           Aktivitätsprotokoll schreiben (nie mit Codes!)
+src/lib/http.js            CORS/JSON-Helfer
+src/routes/auth.js         Login/Logout
+src/routes/users.js        Zugänge und Teammitglieder (inkl. Code-Funktionen, NUR Owner)
+src/routes/roles.js        Rollen erstellen/umbenennen/löschen
+src/routes/applications.js Bewerbungen: Status, Zuweisung, Notizen, Antwortentwürfe
+src/routes/audit.js        Aktivitätsprotokoll auslesen
+migrations/0001_init.sql   D1-Schema (users, roles, sessions, audit_log, applications, ...)
+```
+
+## Das Kernprinzip (aus dem Anforderungsdokument)
+
+> Nur der Hauptadministrator sieht jederzeit alle vollständigen Zugangscodes und nur der
+> Hauptadministrator darf sie erstellen, ändern, kopieren, zurücksetzen oder sperren.
+
+Technisch umgesetzt:
+
+- **Owner-Code** = das `POSTFACH_CODE`-Secret. Kein Datenbankeintrag, kann nicht gelöscht/verändert
+  werden außer von Dogi selbst per `wrangler secret put`.
+- **Team-Codes** werden **zweifach** gespeichert:
+  - `code_hash` (SHA-256, nicht umkehrbar) — für den schnellen Login-Vergleich.
+  - `code_enc` (AES-256-GCM, umkehrbar) — nur damit kann der Owner sich den Klartext-Code später
+    wieder anzeigen lassen. Der Schlüssel dafür liegt ausschließlich im `ENCRYPTION_KEY`-Secret.
+- **Code anzeigen** verlangt zusätzlich eine Re-Authentifizierung (Owner-Code erneut eingeben),
+  bevor der Klartext entschlüsselt und zurückgegeben wird.
+- Folgende Aktionen sind **fest an `isOwner === true` gebunden** und erscheinen nirgends als
+  wählbare Berechtigung: Code anzeigen/kopieren/erstellen/ändern/zurücksetzen, den eigenen
+  Owner-Zugang bearbeiten, die Owner-Rolle löschen/einschränken, jemanden zum Owner machen.
 
 ## Voraussetzungen
 
 - Ein (kostenloser) Cloudflare-Account
 - Node.js installiert (für `npx wrangler`)
 
-## Deploy in 5 Schritten
+## Deploy von Grund auf (falls je nötig)
 
 Alles im Ordner `cloudflare-worker/` ausführen:
 
 ```bash
 cd cloudflare-worker
 
-# 1. Bei Cloudflare einloggen (öffnet Browser zur Anmeldung)
+# 1. Bei Cloudflare einloggen
 npx wrangler login
 
-# 2. KV-Namespace anlegen (Speicher für die Bewerbungen)
+# 2. D1-Datenbank anlegen
+npx wrangler d1 create dogfather-universe-db
+# -> "database_id" aus der Ausgabe in wrangler.toml eintragen
+
+# 3. Schema anlegen
+npx wrangler d1 execute dogfather-universe-db --remote --file=migrations/0001_init.sql
+
+# 4. KV-Namespace anlegen (nur noch für den Live-Status-Schalter genutzt)
 npx wrangler kv namespace create BEWERBUNGEN
-```
+# -> "id" aus der Ausgabe in wrangler.toml eintragen
 
-Die Ausgabe von Schritt 2 enthält eine `id = "..."`. Diese `id` in `wrangler.toml` bei
-`REPLACE_ME` eintragen.
-
-```bash
-# 3. Geheimen Zugangscode für das Postfach festlegen
-#    (wird abgefragt, nirgends im Code sichtbar — frei wählbar, z.B. ein langes Passwort)
+# 5. Owner-Code festlegen (dein persönlicher Hauptadministrator-Zugang)
 npx wrangler secret put POSTFACH_CODE
 
-# 4. Worker deployen
+# 6. Verschlüsselungs-Schlüssel für Team-Codes festlegen (32 zufällige Bytes, base64)
+#    z.B. erzeugen mit: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+npx wrangler secret put ENCRYPTION_KEY
+
+# 7. Deployen
 npx wrangler deploy
 ```
 
-Schritt 4 gibt eine URL aus, z.B. `https://dogfather-universe-postfach.<dein-account>.workers.dev`.
+## Wer den Owner-Code kennen darf
 
-```bash
-# 5. Kurz testen
-curl https://dogfather-universe-postfach.<dein-account>.workers.dev/health
-# sollte {"ok":true,"service":"dogfather-universe-postfach"} zurückgeben
-```
+Nur du. Er ist dein Hauptadministrator-Zugang — sieht ausnahmslos alles, kann Zugänge/Rollen/Codes
+verwalten. Ändern: `wrangler secret put POSTFACH_CODE` erneut ausführen.
 
-## Website mit dem Worker verbinden
+## Zugänge und Teammitglieder verwalten
 
-Nach dem Deploy die Worker-URL an zwei Stellen eintragen:
+Auf `zugaenge.html` (verlinkt von `postfach.html`, wenn du als Owner eingeloggt bist):
 
-1. `assets/js/forms.js` → Konstante `API_BASE_URL` ganz oben auf die Worker-URL setzen
-   (ohne abschließenden Slash).
-2. `postfach.html` → Konstante `API_BASE_URL` im `<script>`-Block genauso setzen.
+- **Neue Zugänge erstellen** — Name, Benutzername, E-Mail, Rolle, Gültigkeit, Notiz. Code manuell
+  festlegen oder automatisch sicher generieren lassen. Wird **einmalig** im Klartext angezeigt —
+  danach nur noch über „Code anzeigen" (mit Re-Auth) abrufbar.
+- **Rollen frei erstellen** — jedes einzelne Recht per Checkbox an-/abschaltbar (Bewerbungsbereiche,
+  Bearbeitung, Antworten, Notizen, Teamverwaltung, Einstellungen). Die Code-Funktionen tauchen dort
+  bewusst nirgends auf.
+- **Individuelle Ausnahmen pro Person** — zusätzlich zur Rolle einzelne Rechte gezielt erlauben
+  oder entziehen.
+- **Delegierbare Teilfunktion:** Personen mit dem Recht „Neue Benutzer vorbereiten" können einen
+  Entwurf anlegen (Name, Benutzername, Rolle) — der Zugang bleibt inaktiv, bis du ihn im Bereich
+  „Zugänge" mit „Freigeben & Code erstellen" final aktivierst.
+- **Pro Person:** Code anzeigen/kopieren/neu erstellen (nur Owner), Sperren/Entsperren, alle
+  Sitzungen beenden (nur Owner), Rolle ändern, Rechte verwalten, vollständig löschen (nur Owner).
 
-Danach gehen neue Bewerbungen automatisch an den Worker statt (nur) an den `mailto:`-Fallback,
-und `postfach.html` kann sie mit dem in Schritt 3 gesetzten Code anzeigen.
+## Sicherheitsmaßnahmen
 
-## Wer den Code kennen darf
-
-Der Code aus Schritt 3 ist dein **Owner-Code** — nur du (Dogi) solltest ihn kennen. Damit kannst
-du nicht nur Bewerbungen sehen, sondern auch Helfer-Codes für andere Personen vergeben (siehe
-unten). Code ändern: einfach `wrangler secret put POSTFACH_CODE` erneut ausführen und neuen Wert
-eingeben — alte Bewerbungen bleiben erhalten, nur der Zugangscode ändert sich.
-
-## Rollen für Rechte Hand, Linke Hand & Co.
-
-Auf `postfach.html` gibt es — nur sichtbar, wenn du dich mit deinem Owner-Code einloggst — einen
-Bereich „Rollen verwalten". Dort kannst du:
-
-- **Neue Codes erzeugen**, mit Rolle (Rechte Hand / Linke Hand / frei) + Name (z.B. "VanVan").
-  Der neue Code wird **einmalig** angezeigt — sofort weitergeben/notieren, danach ist er nicht
-  mehr abrufbar (nur als Hash gespeichert, aus Sicherheitsgründen).
-- **Codes entziehen**, falls sich jemandes Rolle ändert oder der Zugang nicht mehr gebraucht wird.
-
-**Was Helfer-Codes können:** ausschließlich die eingegangenen Bewerbungen ansehen — dieselbe
-Ansicht wie du. **Was sie NICHT können:** neue Codes erzeugen, andere Codes entziehen, oder
-irgendetwas an der Website selbst verändern/löschen. Für Website-Änderungen gibt es in diesem
-Worker schlicht keine einzige Funktion — das ist technisch gar nicht möglich, egal welchen Code
-jemand hat.
+- Nach 5 falschen Codes pro Client 15 Minuten Sperre (`login_attempts`-Tabelle).
+- Sessions: 30 Minuten Inaktivitäts-Timeout, 12 Stunden absolute Höchstdauer.
+- Zugangscodes erscheinen **niemals** im Aktivitätsprotokoll, im Quelltext oder in Fehlermeldungen.
+- CORS ist aktuell offen (`*`) — sobald die finale Domain feststeht, in `src/lib/http.js` →
+  `corsHeaders()` auf die echte Domain einschränken.
 
 ## Wartung
 
-- Bewerbungen ansehen: über `postfach.html` mit Code (empfohlen), oder direkt im Cloudflare
-  Dashboard unter Workers & Pages → KV → `BEWERBUNGEN`.
-- Bewerbungen löschen: im Cloudflare Dashboard unter KV die einzelnen `sub:...`-Einträge entfernen.
-- CORS ist aktuell offen (`*`) — sobald die finale Domain feststeht, in `src/worker.js` →
-  `corsHeaders()` auf die echte Domain einschränken (siehe TODO-Kommentar dort).
+- Bewerbungen/Zugänge/Rollen: alles über `zugaenge.html` bzw. `postfach.html` als Owner.
+- Direktzugriff auf die Datenbank bei Bedarf:
+  `npx wrangler d1 execute dogfather-universe-db --remote --command="SELECT ..."`