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

217 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-<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
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.