# Phase 01 — Verification Report **Reviewer-Rolle:** Read-only Verifier **Datum:** 2026-05-16 **Scope:** Phase 01 (Tech-Debt-Foundation), 10 Files (README + 9 Task-Detail-MDs) ## Overall Verdict **PASS-WITH-MINOR-ISSUES** Die Phase ist inhaltlich solide, technisch korrekt und für agentic execution grundsätzlich ready. Es gibt einige strukturelle und einige inhaltliche Issues, die vor Start adressiert werden sollten, aber kein Blocker. --- ## Per-File Findings ### README.md (Phase-README) - **Template-Konformität:** N/A (kein Detail-MD, Phase-Übersicht). Struktur passt zur restlichen Doku, Done-Definition + Phase-Summary-Section vorhanden — gut. - **Inhaltliche Korrektheit:** - Task-Reihenfolge stimmt mit `00-execution-order.md` und `PROGRESS.md` überein. - Dependency-Graph (ASCII) ist konsistent mit den Detail-MDs. - "9 Tasks" stimmt mit PROGRESS.md. - **Issues:** - **Kleinigkeit:** Im Done-Definition-Block werden Performance-Regression-Check und ein "pre-Phase-01-Baseline" erwartet — wo wird diese Baseline ermittelt? Kein Hinweis auf Tool/Verfahren. Empfehlung: kurz benennen (z.B. `pnpm build` + Bundle-Analyzer-Snapshot in CI). - **Kleinigkeit:** Reihenfolge-Begründung zwischen #16 und #17 ist konsistent (#16 → #17), aber im internen Graph wird #18 vor #16 platziert — das stimmt aber NICHT mit `00-execution-order.md`'s Tabelle: dort wird `supabase-removal.md` an Position 5 gelistet, dann #16/#17 an 6/7. Das ist konsistent. OK. ### dead-code.md (#25) - **Template-Konformität:** ✅ Alle 15 Sections in korrekter Reihenfolge (Lessons-Learned fehlt — explizit optional). - **Dependencies:** Konsistent mit README und 00-execution-order.md (#25 unabhängig, blockt #28/#27). - **Implementation-Steps-Qualität:** - 6 Steps, atomar genug. Single-Commit-Strategie explizit begründet. - Commit-Message-Vorlage vorhanden (`01/dead-code: ...`). - Technisch korrekt (rg, gezielte File-Edits). - **Test-Requirements:** Konkret — keine neuen Tests, aber bestehende müssen grün bleiben + Grep-Verify. Angemessen für reinen Delete-Task. - **Acceptance-Criteria:** Verifizierbar (Symbole weg, Grep-Output leer). - **Subagent-Recommendations:** Passend (research + impl + verify als general-purpose, code-review als gsd-code-reviewer). - **Staging:** Korrekt als "nicht nötig" markiert. - **Issues:** Keine. ### dep-updates.md (#28) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Konsistent. Sagt korrekt "blockt #26/#27" — passt zu README+execution-order. - **Implementation-Steps-Qualität:** - 6 Steps, ein Commit pro Dependency — sehr sauber. - Reihenfolge der Bumps (jsdom → highlight.js → marked → moment → stripe → bcrypt→argon2) ist sinnvoll (Risk-ascending). - Marked-Migration mit async/await-Umgang in React-Render korrekt adressiert. - **Test-Requirements:** Sehr gut — `passwordHasher.test.ts` mit allen 4 Cases (bcrypt-success+rehash, bcrypt-fail, argon2-success-no-rehash, argon2-fail) ist konkret. - **Acceptance-Criteria:** Verifizierbar. - **Subagent-Recommendations:** Realistisch — 6 separate Subagents pro Dep, explizit begründet (Kontext-Overflow). - **Staging:** Vollständig inkl. 48h Burn-In + Coolify-Build-Logs (argon2 native-build). - **User-Wünsche-Konsistenz (bcrypt → argon2 mit Dual-Mode-Verify):** - **✅ KORREKT:** Es wird klar gemacht, dass kein Bulk-Rehash möglich ist (bcrypt one-way). Dual-Mode-Verify (Hash-Prefix-Detection, Rehash-on-Login) wird genau wie vom User gewünscht beschrieben. - **✅ KORREKT:** bcryptjs bleibt als Dep, weil die Verify-Fallback-Phase ihn braucht — wird sogar erwähnt dass die Entfernung erst nach 6-12 Monaten Telemetrie passieren soll (separater Backlog-Task). - **✅ Argon2-Parameter** (`memoryCost=19456, timeCost=2, parallelism=1`) sind OWASP-konform — präzise. - **Issues:** - **Klein:** `apiVersion` für Stripe wird mit `"2024-10-28.acacia"` vorgeschlagen — Stand 2026 ist das veraltet, sollte aktualisiert werden vor Start (oder via "checken vor Implementation"-Note, was schon drinsteht). Akzeptabel. - **Mittel:** Im Step 6 wird gesagt "Caller umstellen: statt `bcryptjs.compare(...)` jetzt `verifyPassword(...)`. Bei `rehashedHash` → `db.user.update(...)`". Das implementiert *jeder* Caller selbst — DRY-Verstoß. Besser: helper `verifyAndPersist(userId, plain)` der den Update inline macht. Sollte vor Implementation klargestellt werden. - **Klein:** "Big-Bang in einem Sprint" + "Estimated 1 Woche" — bei 6 Major-Bumps inkl. Stripe-API-Migration ist 1 Woche knapp; sollte ggf. realistischer als 1.5-2 Wochen angegeben werden. ### totp-consolidation.md (#26) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Sagt "empfohlen vorher #28, nicht hart blockierend". Konsistent mit README/execution-order. - **Implementation-Steps-Qualität:** 5 Steps, atomar mit Commit-Messages. - **Test-Requirements:** Sehr konkret (Window-Drift-Tests mit ±30s/±60s). - **Acceptance-Criteria:** Verifizierbar. - **User-Wünsche-Konsistenz (otpauth als einzige TOTP-Impl):** - **✅ KORREKT:** Selbst-gebaute HMAC-SHA1-Variante wird komplett entfernt, otpauth ist Single-Source-of-Truth. Genau wie User gewünscht. - **✅ Window=1 explizit** dokumentiert (User-Wunsch impliziert "production-grade"-Default). - **Issues:** - **Mittel:** Schritt 3 (Caller-Migration) sagt "atomic commit" — aber wenn N Caller in N verschiedenen Files sind, ist es ein Multi-File-Commit. Bei N>15 sollte erwähnt werden, dass das je nach Caller-Count gesplittet werden kann. - **Klein:** Recovery-Codes werden in Security Notes erwähnt — sollte aber im Test-Requirements expliziter beschrieben sein (Recovery-Code-Generation/Storage gehört technisch zu TOTP-Flow). Aktuell nur "falls dort gleicher Pfad". - **Klein:** Section "Subagent-Recommendations" listet keine `gsd-verifier` (was im AGENT-INSTRUCTIONS Regel 1 als bevorzugt erwähnt wird), nur `general-purpose`. Akzeptabel, aber inkonsistent zum Workflow-Vorbild. ### password-policy.md (#27) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Konsistent. - **Implementation-Steps-Qualität:** 9 Steps, sehr gut atomisiert mit klaren Commit-Messages. - **Test-Requirements:** Sehr stark — explizit HIBP-fail-open, Email-Substring-Check, Unicode. - **Acceptance-Criteria:** Verifizierbar (`rg "length\\s*>=\\s*(4|6|8)" apps/web` als konkrete Check-Methode — schön). - **Subagent-Recommendations:** Drei sequentielle Subagents (Modul → Migration → Doku) — sinnvoll. - **Staging:** Vollständig + HIBP-Outage-Simulation als expliziter Smoke-Test — gut. - **Issues:** - **Mittel:** "5 verschiedene Validierungen" im Problem, aber dann "6 Inline-Password-Checks" in Acceptance-Criteria. Discrepancy. Sollte angeglichen werden. - **Klein:** Login-Soft-Check (Step 8) ruft `validatePassword(plain, { email })` mit `silent: true`-Mode auf — aber dieser Mode-Param ist nicht im API-Contract aus Step 1 spezifiziert. API-Definition unvollständig. - **Klein:** "i18n-keys statt hardcoded Strings" wird erwähnt, aber kein Beispiel-Naming-Schema. Sollte ein konkretes Format genannt werden (z.B. `auth.password.errors.tooShort`). ### supabase-removal.md (#18) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Konsistent mit README/execution-order. - **Implementation-Steps-Qualität:** 9 Steps, gut atomisiert, klare conditional-flow (wenn 0 Rows → skip Migration). - **Test-Requirements:** LocalStack im CI für S3-Tests erwähnt — gut. - **Acceptance-Criteria:** Verifizierbar mit Grep-Strategie. - **User-Wünsche-Konsistenz ("kein Supabase, sondern S3"):** - **✅ KORREKT:** Adapter wird komplett gelöscht, S3 als alleiniges Backend. Migrations-Script + Cleanup-Workflow vollständig. - **Staging:** Sehr detailliert (Dry-Run, Spot-Check 10 Files, 7 Tage Burn-In, Production-Cutover-Plan). - **Issues:** - **Mittel:** Im "Approach" Schritt 4 wird gesagt `storage_provider`-Spalte bleibt drin, aber der Code akzeptiert nur noch `'s3'`. Wenn die Spalte bleibt → kein DB-Migration. Wenn der Code Default `'s3'` setzt → was passiert mit historischen Rows mit anderen Werten (z.B. `'memory'` aus Tests)? Sollte konkreter spezifiziert sein. - **Mittel:** Recherche zur DB-Schema-Spalte (`media.storageProvider`) wird ohne konkrete Schema-Verifikation referenziert. Vor Implementation muss der Subagent prüfen ob die Spalte überhaupt so heißt — empfehlenswert ist ein Phase-0-Step "Schema-Audit" der das verifiziert. - **Klein:** Migrations-Script soll in `scripts/migrate-supabase-to-s3.ts` liegen — Konvention für Migrations-Scripts (vs `prisma/migrations/.../data.ts` aus AGENT-INSTRUCTIONS Regel 8) ist hier abweichend. Klar dass das ein One-Off-Script ist, kein Prisma-Migration; aber Konvention sollte explizit erwähnt werden. ### av-scanner-layer-1.md (#16) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Konsistent. - **Implementation-Steps-Qualität:** 6 Steps, klare Trennung Interface → Adapter → Allow-List → Integration → Audit → Doku. - **Test-Requirements:** Sehr konkret mit real-File-Fixtures. - **Acceptance-Criteria:** Verifizierbar. - **Subagent-Recommendations:** Passend. - **Staging:** Vollständig. - **Issues:** - **Klein:** Rollback-Section erwähnt `STORAGE_SCAN_LAYER1_ENABLED=false` als Notfall-Bypass — wird im Implementation-Step nicht explizit als zu implementieren markiert. Sollte in Step 2 ergänzt werden ("Adapter checkt das Env-Flag"). - **Klein:** Allow-List umfasst `image/svg+xml` mit SVG-XSS-Hinweis in Security-Notes — Risiko-Mitigation (CSP, DOMPurify) wird beschrieben, aber NICHT als Implementation-Step. Sollte entweder hier behandelt oder explizit als out-of-scope deklariert werden. - **Klein:** "Filename-Sanitization" wird als "prüfen ob bereits implementiert, sonst BLOCKERS.md" erwähnt — schwach. Besser: konkret als verifizierbarer Acceptance-Criteria-Punkt aufnehmen. ### av-scanner-layer-2.md (#17) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Korrekt (#16 ist hart blockierend, BullMQ vorhanden — stimmt mit Tech-Stack überein). - **Implementation-Steps-Qualität:** 9 Steps, gut. Container-Setup + Adapter + Job + Quarantäne als separate Commits. - **Test-Requirements:** EICAR-Test ist Industry-Standard und korrekt referenziert. Echter ClamAV-Container im CI ist ambitioniert aber sinnvoll. - **Acceptance-Criteria:** Verifizierbar. - **Staging:** Sehr detailliert inkl. Docker-Compose-Snippet, freshclam-Download-Hinweis (~10 Min initial), Operator-Notes für `docs/deployment.md` — sehr gut für Coolify-Deployment. - **Issues:** - **Mittel:** DB-Migration für `quarantined`/`scanResult`/`scanStatus` wird erwähnt (Step 5), aber nicht in einem separaten Step als Prisma-Migration-Commit ausgewiesen. Per AGENT-INSTRUCTIONS Regel 8 sollte das ein eigener atomic commit sein. Sollte explizit Step werden: "Step 5a: Prisma-Migration für quarantined+scanResult+scanStatus". - **Klein:** `clamscan` npm-Library wird empfohlen — alternative Libraries (z.B. `node-clam`) nicht diskutiert. OK, aber Alternative-Check hätte den Punkt "verworfen" verdient. - **Klein:** Step 8 (Admin-Dashboard) ist als "optional" markiert mit Fallback-Option "in Backlog". Sollte klarere Entscheidung sein — entweder drin oder draußen. Aktuell ambivalent. ### magic-link-reset.md (#19) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Korrekt. - **Implementation-Steps-Qualität:** 8 Steps, gut atomisiert. - **Test-Requirements:** Vollständig (unit + integration + e2e + rate-limit-Test). - **Acceptance-Criteria:** Verifizierbar. - **Security-Notes:** Sehr stark — Anti-Enumeration, Single-Use atomic-transaction, Token-Logging-Hygiene, Referer-Leakage-Protection. - **Issues:** - **Klein:** Step 2 erwähnt "Single-Use durch In-DB-Used-Flag ODER In-Memory-Nonce-Store mit Redis als Backing" — die Wahl muss vor Implementation getroffen werden, nicht zur Subagent-Decision-Time. Sollte als Architecture-Decision explizit getroffen werden (Empfehlung im Text: DB-Flag, aber nicht festgenagelt). - **Klein:** Rate-Limiter wird "existierender Rate-Limiter-Pfad" referenziert — wenn der nicht existiert (zu prüfen!), fehlt der Implementation-Step für einen neuen. Schwacher Punkt. - **Klein:** Token-Signature wird "HMAC-SHA256 mit Server-Secret" empfohlen — sollte konkret auf den existing Server-Secret-Env-Key referenzieren (z.B. `SESSION_SECRET` oder ähnlich), nicht abstrakt bleiben. ### magic-link-invitation.md (#20) - **Template-Konformität:** ✅ Alle 15 Sections. - **Dependencies:** Korrekt (#19 hart benötigt für polyvalenten Service). - **Implementation-Steps-Qualität:** 8 Steps, gut. - **Test-Requirements:** Vollständig. - **Acceptance-Criteria:** Verifizierbar. - **Security-Notes:** Forge-Schutz (`metadata.invitationId === params.id`) ist exzellent. DB-Race und Email-Forwarding adressiert. - **Issues:** - **Mittel:** Step 6 ändert `User.passwordHash` zu nullable. Das ist ein Schema-Change mit potenziell weitreichenden Auswirkungen auf Login-Logik (`if (user.passwordHash)`-Checks). Mehr Caller-Audit nötig vor Migration. Sollte als separater Sub-Step expliziert sein: "Caller-Audit: alle Stellen wo `passwordHash` non-null erwartet wird". - **Klein:** "7 Tage TTL" für Invitation-Token ist sehr lang vs 15 Min für Reset — Security-Trade-off OK, aber bei Single-Use sollten auch revocation-Mechanismen erwähnt sein (Admin kann Invitation widerrufen → Token muss invalidieren). Aktuell nicht abgedeckt. --- ## Cross-File Issues 1. **Magic-Link-Service-API-Definition fragmentiert:** Sowohl #19 als auch #20 sprechen über `generateMagicLinkToken({purpose, ttl, metadata})` — aber die volle Signatur wird in keinem Detail-MD als verbindlicher Contract festgelegt. Vorschlag: in #19 (das #20 blockt) eine klare API-Definition mit TypeScript-Interface in einem dedizierten Code-Block. 2. **Hash-Wechsel-Konsistenz:** #28 (dep-updates) implementiert `passwordHasher.server.ts`; #27 (password-policy) erwartet diesen Hasher; #20 (magic-link-invitation) verweist auf #27 + #28 für Password-Setup. Diese 3-fach-Verkettung ist beschrieben, aber nicht visuell im README-Graph dargestellt — sollte ergänzt werden. 3. **Audit-Event-Naming-Konvention:** Tasks definieren verschiedene Event-Namen (`upload.rejected.scan`, `auth.magic-link.requested`, `invitation.accepted.magic`). Inkonsistente Patterns (mix of dot+dash). Sollte ein zentrales Konventions-Doc gefasst werden bevor erste Implementation einen Stil etabliert. 4. **Env-Variable-Naming:** Tasks fügen viele neue Env-Vars hinzu (`AUTH_PASSWORD_*`, `CLAMAV_*`, `STORAGE_SCAN_*`, `AUTH_MAGIC_LINK_ENABLED`, `AUTH_INVITATION_MAGIC_ENABLED`). README's Done-Definition fordert Dokumentation in `.env.example`. Ein zentrales "Env-Vars-Added-in-Phase-01"-Inventory wäre wertvoll — fehlt aktuell. 5. **Coolify-Deployment-Konsistenz:** Tasks erwähnen alle "Coolify-Auto-Deploy" + branch-pattern `agent/01-`. Die README sollte einmalig den Coolify-Branch-Trigger-Mechanismus dokumentieren, statt es 7-mal in jedem Detail-MD zu wiederholen. 6. **PROGRESS.md-Update-Mechanik:** Alle Detail-MDs sagen "PROGRESS.md Status auf `completed`" — aber das ist Multi-File-Edit was zu Merge-Konflikten führen kann bei parallel arbeitenden Agents. Sollte Workflow-mässig in AGENT-INSTRUCTIONS adressiert sein (z.B. "PROGRESS.md immer als letzter Step rebase-fähig commiten"). --- ## Recommendations for Author ### Must-Fix vor Phase-Start 1. **Magic-Link-Service-Contract** als einheitliches TS-Interface in #19 definieren (wird in #20 referenziert). 2. **Discrepancy "5 vs 6 Validierungen"** in password-policy.md angleichen. 3. **`User.passwordHash`-Nullable-Migration** in #20 mit Caller-Audit-Sub-Step erweitern. 4. **DB-Migration für Quarantine-Spalten** in av-scanner-layer-2 als eigenen atomic-commit-Step expliziert. 5. **Tenant-Audit für Supabase-Storage-Provider** in #18 sollte als Phase-0-Schema-Recherche-Step formalisiert werden (nicht erst beim Implementation-Step). ### Should-Fix für Qualität 6. **Audit-Event-Naming-Konvention** als 1-Seiten-Doc anlegen (`docs/audit-events.md` oder ähnlich). 7. **Env-Variables-Inventory** für Phase 01 zentralisieren (alle neuen Keys + Defaults + Begründung an einem Ort). 8. **Coolify-Deployment-How-To** einmalig in README oder AGENT-INSTRUCTIONS auslagern. 9. **Stripe-apiVersion** vor Implementation auf den dann aktuellen Wert prüfen (in #28 ist `"2024-10-28.acacia"` schon veraltet aus 2026-Sicht). 10. **`verifyAndPersist`-Helper** in #28 statt jeder Caller mache eigenes DB-Update. ### Nice-to-Have 11. Im README-Phase-Graph die transitive Dep #28 → #27 → #20 (Password-Setup im Invitation-Flow) visuell ergänzen. 12. **Rate-Limiter-Existenz** in #19 als Recherche-Step formalisieren (gibt es einen? Wenn nein → eigener Step für neuen Rate-Limiter). 13. **SVG-Sanitization-Entscheidung** in #16 entweder als Step oder explizit als out-of-scope deklarieren. 14. **Admin-Quarantine-View-Entscheidung** in #17 finalisieren statt "optional". --- ## Acceptance Verdict **Diese Phase ist bereit für agentic execution**, mit folgenden Voraussetzungen: - Must-Fix-Items 1–5 vor Start adressieren (vor allem #1 Magic-Link-Service-Contract und #4 DB-Migration-Step, da diese sonst zu inkonsistenten Implementations führen können). - Cross-File-Issues #1 und #2 sollten als Hinweis an den implementierenden Agent dokumentiert werden. Die inhaltliche Qualität ist hoch: - User-Wünsche (Supabase weg, argon2-Dual-Mode, otpauth-only) sind alle korrekt umgesetzt. - Technische Details (OWASP-Argon2-Params, HIBP-k-Anonymity, EICAR-Test, Magic-Link-Forge-Schutz) zeigen Domain-Expertise. - Atomic-Commit-Strategie ist konsequent durchgezogen. - Staging-Pfade sind realistisch und Coolify-tauglich. Schwächen sind primär **strukturell/Workflow-orientiert**, nicht inhaltlich. Mit den genannten Korrekturen ist Phase 01 ein gutes Vorbild für die nachfolgenden Phasen.