239 lines
15 KiB
Markdown
239 lines
15 KiB
Markdown
# 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.
|