Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/VERIFICATION.md
T

18 KiB
Raw Blame History

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.
  • 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.
  • 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-<task>. 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

  1. Audit-Event-Naming-Konvention als 1-Seiten-Doc anlegen (docs/audit-events.md oder ähnlich).
  2. Env-Variables-Inventory für Phase 01 zentralisieren (alle neuen Keys + Defaults + Begründung an einem Ort).
  3. Coolify-Deployment-How-To einmalig in README oder AGENT-INSTRUCTIONS auslagern.
  4. Stripe-apiVersion vor Implementation auf den dann aktuellen Wert prüfen (in #28 ist "2024-10-28.acacia" schon veraltet aus 2026-Sicht).
  5. verifyAndPersist-Helper in #28 statt jeder Caller mache eigenes DB-Update.

Nice-to-Have

  1. Im README-Phase-Graph die transitive Dep #28 → #27 → #20 (Password-Setup im Invitation-Flow) visuell ergänzen.
  2. Rate-Limiter-Existenz in #19 als Recherche-Step formalisieren (gibt es einen? Wenn nein → eigener Step für neuen Rate-Limiter).
  3. SVG-Sanitization-Entscheidung in #16 entweder als Step oder explizit als out-of-scope deklarieren.
  4. 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.