18 KiB
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.mdundPROGRESS.mdüberein. - Dependency-Graph (ASCII) ist konsistent mit den Detail-MDs.
- "9 Tasks" stimmt mit PROGRESS.md.
- Task-Reihenfolge stimmt mit
- 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 wirdsupabase-removal.mdan Position 5 gelistet, dann #16/#17 an 6/7. Das ist konsistent. OK.
- 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.
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.tsmit 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:
apiVersionfü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(...)jetztverifyPassword(...). BeirehashedHash→db.user.update(...)". Das implementiert jeder Caller selbst — DRY-Verstoß. Besser: helperverifyAndPersist(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.
- Klein:
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), nurgeneral-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/webals 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 })mitsilent: 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.tsliegen — Konvention für Migrations-Scripts (vsprisma/migrations/.../data.tsaus 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.
- Mittel: Im "Approach" Schritt 4 wird gesagt
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=falseals 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+xmlmit 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.
- Klein: Rollback-Section erwähnt
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/scanStatuswird 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:
clamscannpm-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.
- Mittel: DB-Migration für
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_SECREToder ä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.passwordHashzu 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 wopasswordHashnon-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.
- Mittel: Step 6 ändert
Cross-File Issues
-
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. -
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. -
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. -
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. -
Coolify-Deployment-Konsistenz: Tasks erwähnen alle "Coolify-Auto-Deploy" + branch-pattern
agent/01-<task>. Die README sollte einmalig den Coolify-Branch-Trigger-Mechanismus dokumentieren, statt es 7-mal in jedem Detail-MD zu wiederholen. -
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
- Magic-Link-Service-Contract als einheitliches TS-Interface in #19 definieren (wird in #20 referenziert).
- Discrepancy "5 vs 6 Validierungen" in password-policy.md angleichen.
User.passwordHash-Nullable-Migration in #20 mit Caller-Audit-Sub-Step erweitern.- DB-Migration für Quarantine-Spalten in av-scanner-layer-2 als eigenen atomic-commit-Step expliziert.
- 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
- Audit-Event-Naming-Konvention als 1-Seiten-Doc anlegen (
docs/audit-events.mdoder ähnlich). - Env-Variables-Inventory für Phase 01 zentralisieren (alle neuen Keys + Defaults + Begründung an einem Ort).
- Coolify-Deployment-How-To einmalig in README oder AGENT-INSTRUCTIONS auslagern.
- Stripe-apiVersion vor Implementation auf den dann aktuellen Wert prüfen (in #28 ist
"2024-10-28.acacia"schon veraltet aus 2026-Sicht). verifyAndPersist-Helper in #28 statt jeder Caller mache eigenes DB-Update.
Nice-to-Have
- Im README-Phase-Graph die transitive Dep #28 → #27 → #20 (Password-Setup im Invitation-Flow) visuell ergänzen.
- Rate-Limiter-Existenz in #19 als Recherche-Step formalisieren (gibt es einen? Wenn nein → eigener Step für neuen Rate-Limiter).
- SVG-Sanitization-Entscheidung in #16 entweder als Step oder explizit als out-of-scope deklarieren.
- 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.