adding docs for rate limit

README.md

@@ -30,7 +30,7 @@ Schlankes PHP-Flatfile-Projekt für einen digitalen Mitgliedsantrag (deutsches F
 3. Document Root auf das Projekt-Root setzen.
 4. Schreibrechte für `storage/` sicherstellen (mind. Webserver-User).
 5. Konfiguration anpassen:
-   - `config/app.php` (Admin-Passwort, Kontakt, Retention)
+   - `config/app.php` (Admin-Passwort, Kontakt, Retention, Rate Limit)
    - `config/mail.php` (Absender, Empfänger)
 6. Admin-Hash setzen:
    - Auf Server: `php -r "echo password_hash('DEIN-PASSWORT', PASSWORD_DEFAULT), PHP_EOL;"`
@@ -55,3 +55,10 @@ Schlankes PHP-Flatfile-Projekt für einen digitalen Mitgliedsantrag (deutsches F
 ## Entwicklung
 
 Lokale PHP-Laufzeit wird benötigt (CLI + Webserver), um Syntaxchecks/Tests auszuführen.
+
+## Weiterführende Doku
+
+- `docs/AI_OVERVIEW.md`
+- `docs/FORM_SCHEMA.md`
+- `docs/OPERATIONS.md`
+- `docs/RATE_LIMITING.md`

docs/AI_OVERVIEW.md

@@ -49,6 +49,7 @@ Digitaler Mitgliedsantrag für Feuerwehrverein mit Flatfile-Speicherung und Admi
 - Admin-Session/Login: `config/app.php` + `src/Admin/Auth.php`
 - Mailtexte/Empfänger: `config/mail.php` + `src/Mail/Mailer.php`
 - Retention-Tage: `config/app.php` + Cron `bin/cleanup.php`
+- Rate-Limit-Parameter: `config/app.php -> rate_limit` (Details: `docs/RATE_LIMITING.md`)
 
 ## Harte Regeln
 

docs/OPERATIONS.md

@@ -26,6 +26,13 @@ php /pfad/zum/projekt/bin/cleanup.php
 - `storage/logs/mail.log`
 - `storage/logs/app.log`
 
+## Rate Limiting
+
+- Konfiguration: `config/app.php -> rate_limit`
+- Persistenz: `storage/rate_limit/`
+- Detaillierte Doku: `docs/RATE_LIMITING.md`
+- Bei erhöhten `429`-Antworten zuerst `requests/window_seconds` prüfen und gegen reale Nutzerlast kalibrieren.
+
 ## Backup
 
 Regelmäßig sichern:
@@ -49,3 +56,4 @@ Regelmäßig sichern:
 - Upload Fehler: `upload_max_filesize` / `post_max_size` und Schema-Limits prüfen.
 - Login geht nicht: `admin.password_hash` prüfen, ggf. temporär `password_plain_fallback` nutzen.
 - ZIP Download fehlgeschlagen: `ZipArchive` Erweiterung auf Hosting prüfen.
+- Viele `429` Antworten: `docs/RATE_LIMITING.md` prüfen, Limits anpassen oder `storage/rate_limit/` kontrollieren.

docs/RATE_LIMITING.md

@@ -0,0 +1,61 @@
+# Rate Limiting
+
+## Zweck
+
+Schützt die API gegen Spam, Bot-Traffic und Missbrauch durch zu viele Anfragen in kurzer Zeit.
+
+## Implementierung
+
+- Klasse: `src/Security/RateLimiter.php`
+- Strategie: Sliding-Window auf Basis von Zeitstempeln
+- Persistenz: Flat Files in `storage/rate_limit/`
+- Schlüsselablage: pro Key wird `sha256(key).json` verwendet
+- Sperren: `flock(LOCK_EX)` je Key-Datei
+
+## Konfiguration
+
+In `config/app.php`:
+
+- `rate_limit.requests`
+Maximal erlaubte Requests pro Zeitfenster
+- `rate_limit.window_seconds`
+Länge des Zeitfensters in Sekunden
+
+Default:
+
+- `requests = 30`
+- `window_seconds = 300` (5 Minuten)
+
+## Aktuell geschützte Endpunkte
+
+- `POST /api/load-draft.php`
+  - Key: `load:{ip}:{email}`
+- `POST /api/save-draft.php`
+  - Key: `save:{ip}:{email}`
+- `POST /api/submit.php`
+  - Key: `submit:{ip}:{email}`
+
+Hinweis: Jeder Endpunkt hat einen eigenen Prefix (`load/save/submit`) und damit ein separates Limit-Fenster.
+
+## Verhalten bei Limitüberschreitung
+
+API antwortet mit HTTP `429` und einer Fehlermeldung (z. B. „Zu viele Anfragen“).
+
+## Betriebsaspekte
+
+- Viele Dateien in `storage/rate_limit/` sind normal.
+- Verzeichnis muss für den Webserver beschreibbar sein.
+- Löschen einzelner Dateien setzt das Limit für den betreffenden Key zurück.
+- Komplettes Leeren des Ordners setzt alle Limits zurück.
+
+## Tuning-Empfehlungen
+
+- Höherer Schutz: `requests` senken oder `window_seconds` erhöhen.
+- Weniger strenger Schutz: `requests` erhöhen oder `window_seconds` senken.
+- Bei aggressiven Bot-Wellen zuerst `submit` härter setzen (ggf. zukünftig endpoint-spezifische Limits einführen).
+
+## Bekannte Eigenschaften
+
+- Bei Dateisystemproblemen (Datei kann nicht geöffnet/gesperrt werden) erlaubt der Limiter aktuell die Anfrage (fail-open), um legitime Nutzer nicht zu blockieren.
+- NAT/Shared-IP kann mehrere legitime Nutzer unter derselben IP bündeln; durch Kombination mit E-Mail ist das Risiko reduziert.
+