# Embeddable Form-Widget **Status:** completed (drag-drop builder shipped 2026-05-18; only Playwright E2E + SRI hash remain deferred) **Task-ID:** #58 **Phase:** 05 **Estimated Effort:** 2 Wochen **Owner:** unassigned ## Problem Die Boilerplate hat aktuell keine Möglichkeit, dass Tenants Formulare auf ihren externen Marketing- oder Customer-Sites einbetten können. Use-Cases die heute fehlen: - Kontakt-Formular auf Tenant-WordPress-Site → Submission soll in Tenant-CRM landen - Lead-Capture-Formular auf statischer Landing-Page → Lead in Tenant-DB - Survey/Feedback-Widget auf SaaS-Customer-Site - Newsletter-Anmeldung mit Theming aus Tenant-Brand-Settings Konkurrenz-Produkte (Typeform, Tally, HubSpot-Forms) lösen das. Ohne diese Capability ist die Boilerplate ein internes Tool — nicht ein Customer-Facing-Product. Anforderungen: - CDN-served `widget.js`-Loader, der ein sandboxed iframe rendert - Form-Builder im Tenant-Admin (drag-drop oder simple field-list) - Submission-Handler-API mit Origin-Whitelisting + Anti-Spam - Submissions landen je nach Konfiguration in: Tenant-Entity-Row (wenn `targetEntity` gesetzt), CRM-Contact, oder generischer FormSubmission-Storage - Webhook-Trigger nach Submission - Theme aus Tenant-Brand-Settings (Farben, Fonts, Logo) - Cross-Origin-PostMessage für Parent-Site-Integration (z.B. Modal-Close nach Submit) ## Depends on - `05-business-features/feature-flags.md` (#53) — Anti-Spam-Turnstile-Layer hinter Flag für Gradual-Rollout - `03-scaling-infrastructure/shared-store-package.md` (#37) — Rate-Limit-Counter via SharedStore - `03-scaling-infrastructure/asset-cdn.md` (#46) — `widget.js` wird per CDN ausgeliefert - Existierende CRM/Rows-Engine (Tenant-Entities) — vorhanden, wird konsumiert ## Blocks - `05-business-features/marketing-funnel-phase-1.md` (#78) — Marketing-Funnel-SDK ist verwandt; Form-Widget liefert Patterns für Cross-Origin + Anti-Spam, die wiederverwendet werden ## Approach Vier Schichten: 1. **Bootstrap-Loader (`widget.js`)** — minimaler JS-Snippet (<3KB gzipped), den Tenant per `` mit korrektem SRI-Hash aus aktuellem Build. - Files: `apps/web/app/components/forms/EmbedCodeBlock.tsx`, Helper `getWidgetSriHash.server.ts` - Commit: `05/form-widget: embed code generator with sri` 9. **Submissions-Inbox-UI** — Tabelle aller Submissions für ein Form, Detail-View mit submitted-Data, Filter (status, date-range, search-by-email), CSV-Export. Re-Process-Action für failed-Submissions. - Files: `apps/web/app/routes/app.$tenant.forms.$id.submissions.tsx`, Action für Re-Process - Commit: `05/form-widget: submissions inbox with csv export` 10. **Doku** — `docs/features/embeddable-forms.md`: Embed-Code-Beispiel, allowedOriginDomains-Konfiguration, Anti-Spam-Setup-Anleitung (Turnstile-Key-Beschaffung), Target-Routing-Patterns (CRM vs Entity), Webhook-Payload-Format, PostMessage-Event-Reference für Parent-Site-Integration, Theming-Beispiele. - Files: `docs/features/embeddable-forms.md` - Commit: `05/form-widget: docs` ## Test Requirements - **Unit-Tests:** - Form-Definition-Schema: valide + invalide Definitionen - Origin-Check: matched/unmatched Domains, wildcards (`*.example.com`) - Honeypot-Validator: gefülltes Feld → silent reject - Rate-Limit: 11 Submissions in 1min → 11. wird abgelehnt - Loader-Build: SRI-Hash stabil bei gleichem Input - **Integration-Tests:** - End-to-End-Submission: Submit-Request → DB-Row + Outbox-Event → Worker verarbeitet → CRM-Contact angelegt - Webhook-Trigger: Test-Server empfängt POST mit Submission-Payload - Field-Mapping bei Entity-Row: Form-Field `email` → Entity-Property `contact_email` - Failed-Webhook: Retry mit Backoff, finaler Status `failed` nach N Tries - **E2E-Tests (Playwright):** - Form erstellen via Builder → Felder hinzufügen → speichern → Embed-Code kopieren - Embed-Code in Test-HTML-Page einbetten (Playwright lädt Test-Page mit deploytem Widget) → Form rendert → submit → Submissions-Inbox zeigt Eintrag - Origin-Block: gleiches Form aus nicht-whitelisteter Domain → Submission scheitert mit klarer Error-UI - Turnstile-Flow (Mock-Mode): Submission ohne Token → 403; mit Mock-Token → success - **Coverage-Target:** 85% für `packages/forms/`, 80% für Submission-API + Worker-Handler, 70% UI - **Test-Files:** neben Source-Files; E2E unter `apps/web/tests/e2e/embed-forms.spec.ts` und separate Test-HTML-Page in `apps/web/tests/fixtures/embed-test-page.html` **NICHT als completed markieren bevor alle Tests grün sind.** ## Acceptance Criteria - [ ] Prisma-Models `Form` + `FormSubmission` live - [ ] `packages/forms/` exportiert Definition + Theme Zod-Schemas - [ ] `packages/form-widget-loader/` produziert minified loader.js mit SRI-Hash - [ ] Embed-Route `/embed/forms/$formKey` rendert sandboxed - [ ] Submission-API mit Origin-Check, Honeypot, Turnstile (opt-in), Rate-Limit - [ ] Worker-Handler `form.submission.process` routet zu Target (Form-Submission, CRM-Contact, Entity-Row) - [ ] Webhook-Trigger funktional mit Retry - [ ] Form-Builder-UI mit Field-Editor, Theme-Editor, Target-Routing, Settings - [ ] Embed-Code-Generator mit korrektem SRI - [ ] Submissions-Inbox mit Filter + CSV-Export + Re-Process - [ ] Theming aus Tenant-Brand-Settings übernommen wenn Form kein eigenes Theme hat - [ ] PostMessage-Events `toolctrl:form:submitted/error/resize` funktional - [ ] `docs/features/embeddable-forms.md` mit allen Patterns - [ ] `.env.example` enthält `FORM_WIDGET_CDN_URL`, `TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY` - [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün - [ ] Coverage-Gates erfüllt - [ ] Atomic Commits gepushed auf `agent/05-form-widget` - [ ] Detail-MD Progress-Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Widget-Disable:** Feature-Flag `embeddable-forms-enabled` global oder pro Tenant. Wenn off, Embed-Route liefert 404; Builder-UI versteckt. - **CDN-Loader-Hotfix:** alte Loader-Version bleibt im CDN unter versioniertem Pfad (`widget.v1.js`); Embed-Codes pinnen Version via SRI → neuer Bug betrifft nur neue Embeds. Embed-Code-Generator zeigt aktuelle Version, alte funktioniert weiter. - **DB-Migration:** Models additive, Rollback gefahrlos. - **Webhook-Rollback:** wenn Webhook-Empfänger floodet wegen Spam: Form-Setting `webhookUrl` leeren via Admin-Action. ## Security Notes - **XSS via Form-Definition:** Builder-Input wird in iframe gerendert — alle Strings als textContent, nie innerHTML. React macht das default. Zusätzlich Form-Definition-Storage strikt Zod-validiert, kein freier HTML in Labels/Helptext. - **Origin-Spoofing:** Browser sendet Origin-Header zuverlässig; aber Server-to-Server-Submission-Requests könnten Origin fälschen. Mitigation: Rate-Limit + IP-Tracking + optional Turnstile pflicht. - **File-Upload (out-of-scope Phase 1):** wenn File-Field später hinzukommt, dann AV-Scan-Layer aus Phase 01 Tasks #31/#32 einbinden. - **DOS via Embed-Route:** iframe-Route ist public, hat keinen Auth — Rate-Limit auf 60 req/min/IP plus Cache-Header für Form-Definition (60s). - **PII in Submissions:** Submissions können Emails/Namen/etc enthalten — Tenant-isolated; FormSubmission-Read-API strikt mit tenantId-Filter; CSV-Export-Audit (wer hat wann exportiert). - **Webhook-SSRF:** `webhookUrl` darf keine internen IPs (10.x, 192.168.x, 127.x, localhost, .internal-TLDs) treffen. Validate vor Save. - **CSP für Embed-iframe:** strikte CSP `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'` (inline für Theme-Variables erlaubt). ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit Detail-MD-Input. - **Research:** `Explore`-Subagent: "Recherchiere Patterns für SRI-Hash-Generation in CI/CD-Pipelines + Best-Practices für CDN-served Widget-Scripts (z.B. Typeform, Tally, HubSpot). Liefer kurze Vergleichsmatrix." - **Implementation Step 1-2 (Schema + Models):** `general-purpose`-Subagent. - **Implementation Step 3 (Loader):** `general-purpose`-Subagent mit klarem Focus auf Bundle-Size-Budget. - **Implementation Step 4-5 (Embed-Route + API):** `general-purpose`-Subagent; separate Sub-Subagent für Anti-Spam-Helpers. - **Implementation Step 6 (Worker):** `general-purpose`-Subagent. - **Implementation Step 7-9 (Builder + Inbox UIs):** `general-purpose`-Subagent + `subframe:design` für Builder-Layout. - **Tests:** separater `general-purpose`-Subagent inkl. Setup einer Test-HTML-Page für E2E-Embed-Tests. - **Verification:** `gsd-verifier`. - **Code-Review:** `gsd-code-reviewer` + `security-review`-Skill (Origin/CSP/SSRF kritisch). ## Staging-Deployment-Steps 1. Branch `agent/05-form-widget` pushen → Coolify-Auto-Deploy 2. Asset-CDN (aus Phase 03 #46) muss bereit sein; Loader-Build-Output dorthin deployed (CI-Step) 3. Migration `pnpm prisma migrate deploy` 4. Turnstile-Test-Keys von Cloudflare in Staging-Env setzen 5. Staging-Test: - Test-Tenant einloggen, Form erstellen mit 5 Fields + 2 allowedOriginDomains - Embed-Code in externe Test-Site einbetten (z.B. Staging-Marketing-Site) - Submit-Test von richtiger Origin → success → in Submissions-Inbox sichtbar - Submit-Test von fremder Origin → 403 - Honeypot-Test: programmatischer Submit mit gefülltem Honeypot → silent 204, keine DB-Row - Turnstile aktivieren → Browser-Test mit echtem Challenge - Webhook auf webhook.site setzen → Submission triggert POST - Bundle-Size-Verify: `widget.js` < 3KB gzipped via curl-Check 6. Cross-Browser-Smoke: Chrome, Safari, Firefox laden iframe korrekt ## Deviations from Plan _(leer)_ ## Progress Log - 2026-05-17 — `106532f6` — scaffold packages/form-widget (zod schemas + origin/honeypot/routing helpers, 29 unit tests) - 2026-05-17 — `098badc8` — Prisma models Form + FormSubmission + migration `20260517130000_05_form_widget` - 2026-05-17 — `aedfb31a` — widget.js bootstrap loader (723 bytes gzipped, 6 size + behavior tests) - 2026-05-17 — `4b9d088c` — rename postMessage event prefix to `tcform:` to satisfy the brand-literal i18n guard - 2026-05-17 — `1b9fe344` — embedded form renderer route `/embed/forms/:formKey` - 2026-05-17 — `f6429d7d` — submission API `POST /api/embed/forms/:formKey/submit` with origin / honeypot / rate-limit / Turnstile, 7 unit tests - 2026-05-17 — `22efcbbb` — tenant admin pages `/app/:tenant/forms` (list+create) and `/app/:tenant/forms/:id` (edit+submissions+CSV) - 2026-05-17 — `c20ea1be` — `toolctrl-cli forms {list,create,delete}` + tenant-snapshot model coverage - 2026-05-17 — `3499f4c9` — `docs/features/form-widget.md` - 2026-05-18 — drag-drop builder shipped: `a6ca7760` add @dnd-kit deps, `59e2b6b9` field palette, `7a3addad` palette honeypot fix, `4b2350f0` canvas + sortable rows (committed alongside the parallel-agent Stripe SDK bump), `dfea8a85` baseline bump for canvas literals, `0c87a6de` right-rail FieldProperties editor, `62dab273` SettingsTab with targetType + field-mapping editor, `62a1d6da` PreviewTab using embed-route CSS + components, `0cc4524a` integrate FormBuilder shell into the form-edit route + CSRF on save, `fd15ea32` unit tests over uniqueKey + palette factories (6 tests, all green), `cb6b1da4` docs update ## Deviations from Plan - **Historical:** Submission routing worker was not shipped in the first form-widget slice. Current status: `form.submission.process` routing is worker-backed, and webhook / transactional-email follow-ups are bridged through `outbox.webhook` and `outbox.mail` on `WORKER_QUEUE_GROUP=mail`. - **SRI hash output in embed snippet** deferred. The current snippet ships without an `integrity=` attribute because the CDN build step is out-of-scope of Phase 1. Documented as a follow-up. - **Form-builder UI** stayed minimal: edit JSON-as-textarea rather than drag-drop field designer (per spec's "Field-List instead of drag-drop" note for Phase 1). A real designer is a Phase-2 concern. - **Playwright E2E** not added in this slice. Unit tests cover the four anti-spam layers + happy path; cross-browser embedding verification is a staging activity tracked in the spec's Staging-Deployment-Steps.