MAIL HARDENING

NEXT_STEPS.md

@@ -1,8 +1,6 @@
 # Next Steps
 
-## Issue Drafts (Ready for Gitea/GitHub)
-
-- #TODO Define unified error strategy
+- #TODO Unified error strategy (Definition)
 - Aufwand: `M`
 - Labels: `quality`, `api`
 - Ziel: Einheitliches Verhalten bei Fehlern.
@@ -10,15 +8,12 @@
 - ADR/kurze Doku: wann `null/false`, wann Exception.
 - `sql.php`, `link-meta.php`, `troy-api.php` folgen derselben Strategie.
 - Mindestens 3 Beispiele in `README.md` dokumentiert.
-
-- #TODO Expand README with runnable examples
-- Aufwand: `S`
-- Labels: `docs`
-- Ziel: Schnellere Nutzung ohne Code-Lesen.
-- Akzeptanzkriterien:
-- Pro Modul mindestens 1 kurzes Copy/Paste-Beispiel.
-- Abschnitt "Konfiguration" mit `secret.php`-Feldern vorhanden.
-- Abschnitt "Known limitations" ergaenzt.
+- Festlegung:
+- Exceptions fuer interne/unerwartete Fehler (Konfiguration fehlt, DB/HTTP/JSON-Fehler, Parsing-Fehler, invalide Argumente).
+- `null` nur fuer "kein Ergebnis" als erwarteter Zustand (z. B. URL ohne OG-Metadaten).
+- `false` nur fuer boolesche Checks/Operationen mit reinem Erfolg-Flag; keine Detailfehler ueber `false`.
+- Keine Mischung pro Funktion: jede Funktion dokumentiert exakt einen Fehlerkanal in PHPDoc/README.
+- Alle gecatchten Exceptions werden mit Kontext weitergeworfen (ohne Secrets), nicht still geschluckt.
 
 - #TODO Complete `secret.php.example`
 - Aufwand: `S`
@@ -29,7 +24,7 @@
 - Jede Variable hat kurzen Kommentar.
 - Dateiformat entspricht direkt nutzbarer Vorlage.
 
-### 5) Remove `@` error suppression incrementally
+- #TODO Remove `@` error suppression incrementally
 - Aufwand: `M`
 - Labels: `quality`, `safety`
 - Ziel: Fehler sichtbar und kontrolliert behandeln.
@@ -38,9 +33,9 @@
 - Ersetzungen mit explizitem Error-Handling umgesetzt.
 - Keine neue `@`-Verwendung in geaenderten Dateien.
 
-## 2) Sicherheit und Robustheit
+- #TODO Sicherheit und Robustheit
 
-### 6) Harden URL fetching against SSRF
+- #TODO Harden URL fetching against SSRF
 - Aufwand: `M`
 - Labels: `security`, `network`
 - Akzeptanzkriterien:
@@ -48,15 +43,7 @@
 - Optionales Host-Allowlist-Feature vorhanden.
 - Tests fuer geblockte und erlaubte Ziele vorhanden.
 
-### 7) Prevent mail header injection
-- Aufwand: `S`
-- Labels: `security`, `mail`
-- Akzeptanzkriterien:
-- Empfaenger/Betreff/From werden validiert.
-- CRLF-Injection wird abgefangen.
-- Fehlerfall ist dokumentiert.
-
-### 8) Centralize HTTP limits (timeout/redirect/size)
+- #TODO Centralize HTTP limits (timeout/redirect/size)
 - Aufwand: `S`
 - Labels: `robustness`, `network`
 - Akzeptanzkriterien:
@@ -64,7 +51,7 @@
 - `og.php` und `link-meta.php` nutzen dieselben Limits.
 - Default-Werte sind in README dokumentiert.
 
-### 9) Improve SQL error handling + logging
+- #TODO Improve SQL error handling + logging
 - Aufwand: `M`
 - Labels: `sql`, `robustness`
 - Akzeptanzkriterien:
@@ -72,7 +59,7 @@
 - Fehler enthalten Query-Kontext ohne Secrets.
 - Verhalten entspricht der definierten Error-Strategie.
 
-### 10) Replace fragile HTML allowlist sanitizer
+- #TODO Replace fragile HTML allowlist sanitizer
 - Aufwand: `M`
 - Labels: `security`, `string`
 - Akzeptanzkriterien:
@@ -80,15 +67,15 @@
 - Erlaubte Tags sind konfigurierbar dokumentiert.
 - Regression-Tests fuer typische Eingaben vorhanden.
 
-## 3) Code-Qualitaet
+- #TODO Code-Qualitaet
 
 - Sammel-Issue: Naming-Konvention, SQL-Binding-Refactor, Legacy-Markierung, Markdown-Konsolidierung, klare Modulgrenzen.
 - Aufwand: `L`
 - Empfehlung: in 3-5 Unter-Issues aufteilen.
 
-## 4) Tests und Tooling
+- #TODO Tests und Tooling
 
-### 11) Bootstrap test/tooling baseline
+- #TODO Bootstrap test/tooling baseline
 - Aufwand: `M`
 - Labels: `testing`, `ci`
 - Akzeptanzkriterien:
@@ -96,9 +83,7 @@
 - PHPStan/Psalm auf niedriger Stufe integriert.
 - CI fuehrt mindestens Lint + Tests bei Push aus.
 
-## 5) Mittelfristige Architektur
-
-### 12) Prepare Composer + namespace migration path
+- #TODO Prepare Composer + namespace migration path
 - Aufwand: `L`
 - Labels: `architecture`
 - Akzeptanzkriterien: