Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,216 @@
# 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.