feuerwehr-freising-antragsformular/docs/rate_limiting.md

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.local.php:

• rate_limit.enabled Globaler Schalter (true/false). Bei false lässt der Limiter alle Requests durch.
• rate_limit.requests Maximal erlaubte Requests pro Zeitfenster
• rate_limit.window_seconds Länge des Zeitfensters in Sekunden

Default:

• enabled = true
• requests = 30
• window_seconds = 300 (5 Minuten)

Aktuell geschützte Endpunkte

• POST /api/request-otp.php
  • Key: otp-request:{ip}:{email}
• POST /api/verify-otp.php
  • Key: otp-verify:{ip}:{email}
• 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}
• POST /api/reset.php
  • Key: reset:{ip}:{email}
• POST /api/upload-preview.php
  • Key: preview-upload:{ip}:{email}
• POST /api/delete-upload.php
  • Key: delete-upload:{ip}:{email}

Hinweis: Jeder Endpunkt hat einen eigenen Prefix und damit ein separates Limit-Fenster.

Kapazität bei aktivem Limiting

Aktive Konfiguration (config/app.local.php):

• enabled = true
• requests = 30
• window_seconds = 300 (5 Minuten)

Daraus ergibt sich pro Rate-Limit-Bucket (Key = prefix + ip + email):

• 5 Minuten: 30 Requests
• 1 Stunde: 360 Requests
• 24 Stunden: 8.640 Requests

Da aktuell 8 Endpunkte getrennte Buckets nutzen, ist der theoretische Gesamtwert über alle Endpunkte (gleiche IP + E-Mail) entsprechend:

• 5 Minuten: 240 Requests
• 1 Stunde: 2.880 Requests
• 24 Stunden: 69.120 Requests

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.