Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/archive/handoffs/HANDOFF-2026-05-20.md
T

239 lines
15 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.
# Handoff — Stand 2026-05-20
> **Historical snapshot only (2026-05-25 cleanup).** This file is preserved
> for audit/history. Do not treat its "start", "push", "deploy" or operator
> instructions as current work. Use `PROGRESS.md`, `OPERATOR-CHECKLIST.md`
> and the latest session notes for live status.
**Vorgänger-Agent:** Claude Opus 4.7 (1M context)
**Letzte aktive Session:** Phase 06 Plugin-System — von "audit-package zusammenstellen" bis "fast alle internen Findings remediated"
**Ziel des Handoffs:** Nachfolge-Agent soll in **3 Minuten** wissen wo wir stehen, was gerade kein Code-Problem sondern Operator-Arbeit ist, und welche Tracks Code-Arbeit brauchen.
---
## 1. Was die letzte Session bewegt hat (29 commits auf `main`)
Phase 06 (Plugin-System) #23 von `pending` → `in_progress (operator-audit-pending)`. Audit-Package-Layer + 12 interne Findings remediated mit Tests.
Schlüssel-Artefakte:
- `docs/security/plugin-threat-model.md` — 14 Assets × STRIDE, jede Mitigation per `file:line` an Code gehängt
- `docs/security/plugin-attack-surface.md` — 9 Capabilities, Manifest-Felder, DB-Tabellen, Routes, Env
- `docs/security/plugin-internal-findings.md` — 24 F-NNN Findings, 23 davon disposed (closed / accepted-residual / blocked-on-precondition / blocked-architecturally)
- `docs/security/plugin-audit-rfp.md` — RFP mit Vendor-Empfehlung Cure53 (Alternates: Trail of Bits / NCC Group / SySS / secfault), 25k EUR Cap
- `docs/security/plugin-runtime-signoff.md` — Joint Sign-Off-Template
- `scripts/build-plugin-audit-package.sh` — bündelt In-Scope-Code + Docs + SHA-256-Manifest in ein tar.gz (smoke-getestet ~209 KB)
- `docs/improvement-plan/06-plugin-system/security-findings/README.md` — Folder-Convention für künftige Findings-Files
Code-Remediations diese Session (alle mit Tests + grünem Lefthook-Pre-Commit):
- F-015 Critical (worker bootstrap unwired) — `handlePluginInvokeJob` jetzt wirklich an BullMQ angeschlossen
- F-005 Phase A + B — Install-Path Trust-Store-Gate + binary-on-disk verify
- F-017 — Manifest-Schema um `minHostVersion`/`maxHostVersion` erweitert
- F-010 — CSRF-body-consumption immunity verifiziert
- F-014 — sanitize total-size budget
- F-011 — install-route per-tenant rate limit
- F-008/F-009/F-021/F-023 — Medium-Sweep (statement cap, install cap, tenantId regex, circular-ref WeakSet)
- F-007/F-020 — per-stmt migration audit + audit-table-size warning
- F-006 — Token-aware migration scan (ersetzt substring-only Forbidden-Token-Check)
- F-003 — `PluginCapabilityUse` per-tenant hash chain (Prisma migration + verifier)
- F-001 backend — `TenantPluginCapabilityGrant` Modell + enable-time consent-gate (UI deferred)
- F-013/F-016/F-018/F-019/F-012 — als accepted-residual / documented / blocked-on-precondition geschlossen
Nur **F-002** bleibt offen — per-instruction fuel braucht Wasmtime-Swap (multi-week, architektur). Konkrete Two-Track-Remediation steht in der Findings-Datei.
---
## 2. Gesamt-Projekt-Status
```
Total Tasks: 63 aktiv + 7 Backlog
Completed: 35 / 63 (56%)
In Progress: 28 / 63
Pending: 0
Backlog: 7
Blocked-hart: 0 (siehe BLOCKERS.md für Operator-Anfragen)
```
Die "In Progress: 28" zerfallen in drei sehr unterschiedliche Buckets — das ist das wichtigste was der nächste Agent verstehen muss.
### Bucket A — Operator-Pending (~14 Tasks, KEINE Code-Arbeit)
Code ist fertig + getestet, was fehlt ist eine Operator-Aktion (env flip, deploy, account setup, store submission, live E2E test). **Nicht anpacken ohne klaren Operator-Auftrag.**
| Task | Operator-Aktion |
| --------------------------------- | ------------------------------------------------------------------------ |
| #16 / #17 AV-Layer 1+2 | Erste echte EICAR-Upload-Smoke auf staging |
| #19 / #20 Magic-Link / Invitation | Live E2E-Flow auf staging |
| #23 Phase 06 #23 | **External pen-test dispatch** (B-006) — siehe Section 4 |
| #26 TOTP | Live MFA enroll/challenge E2E |
| #29 / #30 / #32 Sentry | Workflow-Smoke + Project-Setup |
| #40 PgBouncer | App `DATABASE_URL` flip |
| #41 R/W-Split | Replica deploy + connection-string flip |
| #51 Asset-CDN | CDN-Zone provisionieren |
| #56 AI-Cost Phase 3 | Stripe-Account Meter-Setup (siehe `docs/ops/stripe-meters-migration.md`) |
| #65 Mobile | Native-builds + App Store / Play Store submission |
| #27 Password-Policy | Login-Soft-Banner (Code-Stub existiert, UI-Polish deferred) |
### Bucket B — Code-Sprint-Deferred (~13 Tasks, ECHTE Code-Arbeit)
Foundation ist da, Feature-Vervollständigung steht aus. Diese sind die echten "weitermachen"-Kandidaten.
| Task | Was zu tun ist | Aufwand |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------- |
| **#21 / #22 Plugin Phase 1+2** | Hot-reload, marketplace, sandboxed iframe, output-hooks, 13 zusätzliche hook-points, global crash counter | 2-3 Wochen |
| **#38 Shared-Store** | 3 von 6 Stores migriert; idempotency + subscription-cache + session offen | 1 Woche |
| **#42 Outbox** | Foundation shipped; call-site migrations, admin UI, CLI re-queue, e2e tests offen | 1 Woche |
| **#39 Pub/Sub** | feature-flag invalidation in Phase 05 wired-up | 2-3 Tage |
| **#53 Feature-Flags** | Visual rule builder UI | 3-5 Tage |
| **#55 AI-Cost Quota** | Admin + tenant UI + CLI | 3-5 Tage |
| **#59 Realtime-Collab** | Andere Editoren als Novel anbinden (Hocuspocus) | 1 Woche |
| **#62 Storybook** | a11y / visual-regression / test-runner | 3-5 Tage |
| **#72 i18n** | 200+ jsx-text + prop-literal extractions (`/72 i18n migration sprint` in D1) | 3-5 Tage |
| **#73 WCAG** | Axe-violation Backlog abarbeiten | 5-7 Tage |
| **#76 Test-Coverage** | Per-Module-Gates ratchet | 5-10 Tage |
| **#78 Marketing-Funnel** | Admin-Sidebar wiring + Turnstile staging-verify | 1-2 Tage |
| **F-002 (Phase 06)** | Per-instruction fuel via Wasmtime-Swap ODER worker-thread + wall-clock kill | multi-week |
### Bucket C — Backlog (7 Tasks, on-demand)
#24 (Marketplace), #52, #57, #64, #66, #74, #77 — explizit "nur wenn jemand fragt", nicht auf der aktiven Roadmap.
---
## 3. Offene Operator-Blocker (BLOCKERS.md)
> **Superseded blocker status (2026-05-28):** this section is preserved as
> the 2026-05-20 snapshot. Current truth: B-006 remains the external plugin
> production gate; B-008 is closed by operator disk-pressure alerting; B-012
> is a mitigated runner-host recurrence risk, not an active deploy/code
> blocker. Use `../../OPERATOR-CHECKLIST.md` and `../../BLOCKERS.md`.
### Aktuell **open**:
- **B-006 — External Security Review of WASM Sandbox** (Phase 06 production rollout gate)
- Audit-Package + RFP + Vendor-Memo + Sign-Off-Template alle ready (siehe Section 4)
- Operator: Cure53 (oder einer der 4 Alternates) engagieren, 3-5 Tage Pen-Test, ~15-25k EUR
- **B-008 — Disk-pressure monitoring** (Aftermath: containers wieder up, prevention pending)
- Operator: Grafana-Alert + automated `docker system prune` cron
- **B-012 — Gitea-runner Docker default-address-pool** (mitigated 2026-05-18, permanent fix operator-owed)
- Operator: `/etc/docker/daemon.json` auf `homeserver` editieren + dockerd restart
### Resolved (siehe BLOCKERS.md für Archiv):
B-001 (Stripe 13→19), B-002 (Staging-Access), B-003 (Push-Strategie), B-005 (Sentry OTLP), B-007 (Authentik blueprints), B-009 (Lighthouse session-cookie), B-010 (pgvector + migrations), B-011 (Worker Dockerfile), B-013 (Vite node:crypto)
---
## 4. Phase 06 — Production-Rollout-Path (konkrete Schritte)
> **Archived superseded notes:** this rollout path predates later plugin
> readiness and worker-topology docs. Use `docs/operations/plugin-lifecycle.md`,
> `docs/worker.md`, `docs/ops/worker-queues.md`, and
> `docs/security/plugin-runtime-signoff.md` for current runtime gates. In
> particular, the production gate is now `PLUGIN_RUNTIME_PRODUCTION_ENABLED`,
> not the older `PLUGIN_RUNTIME_ENABLED` wording below.
Phase 06 ist der einzige Track der gerade "audit-ready" ist und auf eine externe Operator-Aktion wartet. Der Pfad zur completed-Markierung:
1. **`git push`** — die 29 lokalen commits auf `main` müssen nach `origin` (Pre-Push-Hook ist grün seit `3afbb257`)
2. **`bash scripts/build-plugin-audit-package.sh`** — erzeugt `artifacts/plugin-audit/2026-05-20/plugin-audit-<sha>.tar.gz`
3. **RFP + Archive an Cure53 verschicken** per `docs/security/plugin-audit-rfp.md` § 9 (E-Mail-Template am Ende der RFP-Datei)
4. **Während des Audits (~3 Wochen):** Findings werden unter `docs/improvement-plan/06-plugin-system/security-findings/F-NNN-….md` abgelegt. Pro Critical/High einen eigenen File mit Reproduction + Remediation-Plan.
5. **Fixes pushen → Re-Test anfragen** (Cure53 macht typischerweise 1× Re-Test im Engagement)
6. **`docs/security/plugin-runtime-signoff.md`** ausgefüllt + von Operator + Lead Auditor signiert
7. **Production-Env-Vars setzen** _bevor_ `PLUGIN_RUNTIME_ENABLED=true`:
- `PLUGIN_TRUSTED_PUBLIC_KEYS=<CSV von hex Ed25519 keys>` (Operator-Aktion)
- `PLUGIN_INSTALL_SKIP_BINARY_VERIFY=false` (Default — NICHT auf true setzen in Prod)
- `PLUGIN_REQUIRE_CAPABILITY_CONSENT=true` (Default — NICHT auf false setzen in Prod)
- `PLUGIN_BINARY_BASE_PATH=/app/var/plugins` (oder operator-gewählt)
- `WORKER_QUEUE_GROUP=plugin` Container provisionieren (separates `worker-plugin` deploy)
8. **PROGRESS.md** Status für #23 von `in_progress (operator-audit-pending)` → `completed`
9. **F-002** bleibt nach Audit als deferred — entweder direkt im selben Rollout angegangen ODER als Phase-06-follow-up
---
## 5. Was der nächste Agent zuerst tun sollte
**Lies in dieser Reihenfolge (max 15 Minuten):**
1. Dieses Handoff-Dokument (bis hierhin)
2. `docs/improvement-plan/PROGRESS.md` Aggregat-Sektion (Zeilen 1-50)
3. `docs/improvement-plan/BLOCKERS.md` (alle `Open` Einträge)
4. `docs/improvement-plan/OPERATOR-CHECKLIST.md` § A (operator-env-flip-pending Items)
5. `docs/security/plugin-internal-findings.md` Summary-Tabelle (Section "Summary")
6. `.claude/CLAUDE.md` (React Router v7 conventions — die werden im Repo strikt enforced)
7. `AGENTS.md` im Repo-Root (Workflow + Branch-Strategie)
**Dann sprich mit dem User über die Richtung:**
> "Vorgänger hat Phase 06 audit-ready übergeben. Open Bucket-B Tracks sind A, B, C, D — welcher davon ist priorität, oder gibt es einen anderen Track der dich gerade interessiert?"
**NICHT** einfach in Phase-06-Follow-Up-Code reingehen ohne expliziten Auftrag — F-002 ist Multi-Wochen-Architektur (Wasmtime), nichts zum "kurz mal machen". Auch nicht in Bucket-A-Operator-Tracks reinarbeiten ohne klaren Anlass — der Code ist fertig, das Warten ist beabsichtigt.
---
## 6. Workflow-Konventionen (NICHT vergessen)
> **Archived superseded notes:** these workflow conventions were session-local
> for 2026-05-20. They do not override current repository instructions,
> conversation constraints, branch policy, verification scope, or commit/push
> decisions.
Aus `AGENTS.md` + Session-Erfahrung:
1. **Alle Commits direkt auf `main`** — keine Branches, Coolify deployed auto auf staging
2. **`git pull --rebase` vor Workflow-Start** — andere Agenten arbeiten parallel
3. **Lefthook Pre-Commit ist hart** — `test-density`, `eslint-baseline`, `secrets`, `lint-staged` müssen grün
4. **Lefthook Pre-Push ist hart** — full `pnpm typecheck`. Bricht den Push wenn TS-Fehler. Diese Session hatte einen Push-Fail wegen F-001 Set-Type — fix in `3afbb257`.
5. **React Router v7** — Route-Type-Imports IMMER als `./+types/<routeName>`, nie relativ. Nach Route-Add `npm run typecheck` ausführen.
6. **Niemals `git add -A`** — nur explizite Paths. Parallel-Agenten-Disziplin.
7. **Co-Author-Trailer:** `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`
8. **`pnpm`, nicht npm** — pnpm-workspace-Setup, `pnpm -F <pkg>` für package-scoped scripts
9. **Tests via `npx vitest run <path>`**, NICHT `pnpm test` (zu breit für TDD)
---
## 7. Push-Status (jetzt-aktuell)
> **Archived superseded notes:** the push status below is a point-in-time
> snapshot from 2026-05-20, not current repository state.
```
HEAD: 3afbb257 fix(plugins): widen capability-name Set type in F-001 grant check
local-main vs origin/main: 29 commits ahead
worktree: nur auto-generated Prisma client modifications (packages/db/generated/prisma/*)
```
**Operator sollte als allererstes `git push` durchziehen.** Die 29 Commits sind lokal, getestet, hooks-grün, aber noch nicht auf `origin`. Bis die nicht oben sind ist nichts deployed.
Wenn der Push erneut scheitert: Pre-Push-Hook Output lesen, das ist ein neuer Bug, kein bekannter Fehler.
---
## 8. Was diese Session NICHT geleistet hat (ehrlich)
- **F-002 nicht angegangen** — Wasmtime-Swap ist multi-week, nicht session-scoped. Konkrete Two-Path-Remediation in `plugin-internal-findings.md` F-002 dokumentiert.
- **Phase 06 UI** — Capability-Consent-Dialog, Sandboxed-iframe-Settings, Audit-Trail-Filter-UI sind alle deferred (#22 Deviations + F-001 backend-only)
- **13 weitere Hook-Points** — Phase 06 #22 hat 5/18 wired; 13 deferred
- **Marketplace** — Phase 11 Backlog #24, nicht aktiv
- **Andere Tracks außerhalb Phase 06** — diese Session war Phase-06-fokussiert. Bucket B (Sprint-Deferred) Items sind unverändert seit vor 2026-05-19.
---
## 9. Sofort-Sanity-Check für nächsten Agent
```bash
# Im Repo-Root
git log --oneline -5 # sollte mit 3afbb257 starten
git status -s # sollte nur Prisma-generated zeigen
pnpm -F @toolctrl/plugin-runtime test 2>&1 | tail -5 # sollte 168 tests passing
bash scripts/build-plugin-audit-package.sh # sollte tar.gz erzeugen
```
Wenn alle 4 grün: Repo ist in dem Zustand der diesem Handoff entspricht.
---
**Ende des Handoffs.** Bei Unklarheit den User fragen, nicht raten.