18 KiB
18 KiB
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
targetEntitygesetzt), 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-Rollout03-scaling-infrastructure/shared-store-package.md(#37) — Rate-Limit-Counter via SharedStore03-scaling-infrastructure/asset-cdn.md(#46) —widget.jswird 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:
- Bootstrap-Loader (
widget.js) — minimaler JS-Snippet (<3KB gzipped), den Tenant per<script>-Tag einbettet. Lädt sandboxed iframe mitsrcdocoder iframe-URL/embed/forms/$formKey. Mit SRI-Hash, CSP-safe. - Embedded Form-App — React-Mini-App, gebundled separat von Main-App, wird im iframe gerendert. Konsumiert Form-Definition + Theme, rendert Felder, validiert client-side, postet an Submission-API.
- Form-Builder im Tenant-Admin — UI zum Erstellen/Editieren von Formular-Definitionen, Embed-Code-Generator, Submissions-Inbox.
- Submission-API —
POST /api/embed/forms/$formKey/submitmit Origin-Check, Honeypot, Turnstile, Rate-Limit, Routing zu Target-Storage.
Begründung der Architektur-Wahl:
- Iframe statt Direct-DOM-Inject: verhindert CSS-Konflikte mit Parent-Site, isoliert JS-Errors, ermöglicht strikte CSP, schützt User-Input vor Parent-Site-Listeners. Verzicht auf nahtloses Theming akzeptabel — kontrollierbar via PostMessage-Resize.
- CDN-served Loader: zentral updatebar ohne dass Tenant Embed-Code ändern muss. SRI für Tamper-Detection (Embed-Code enthält Hash).
- Form-Definition als JSON in DB: Builder produziert JSON; Embedded-App rendert daraus. Versionierung mit
formVersion-Field, alte Embeds rendern alte Version weiter (Form-History). - Target-Routing-Konfiguration: statt einer harten "wo landen Submissions"-Regel: pro Form konfigurierbar. Default:
FormSubmission-Generic-Storage. Optional: Tenant-Entity (mit Field-Mapping), CRM-Contact. - Anti-Spam-Layer: Honeypot reicht für 80% der Bots; Turnstile als opt-in für High-Traffic-Forms. Rate-Limit (10/min/IP/origin) als Always-On.
Implementation Steps
- Prisma-Models —
Form { id, tenantId, key (cuid, unique, public), name, version, definitionJson, themeJson, targetType (form-submission|crm-contact|entity-row), targetEntityId?, fieldMappingJson?, allowedOriginDomains String[], antiSpamConfig Json (honeypotEnabled, turnstileEnabled), successMessage, redirectUrl?, webhookUrl?, createdAt, updatedAt }+FormSubmission { id, formId, formVersion, submittedDataJson, submitterIp, submitterUserAgent, originDomain, processedAt?, processingResultJson, createdAt }mit Index(formId, createdAt).- Files:
prisma/schema.prisma,prisma/migrations/<ts>_embeddable_forms/migration.sql - Commit:
05/form-widget: prisma models for forms and submissions
- Files:
- Form-Definition-Schema (Zod) —
packages/forms/src/schema.ts: Field-Types (text, email, number, select, multi-select, textarea, checkbox, radio, file optional), Validation-Rules per Field, optional ConditionalLogic (showIfpro Field). Theme-Schema: colors, fontFamily, borderRadius, logoUrl. Versionierung via SchemaVersion-Field.- Files:
packages/forms/src/schema.ts, Tests - Commit:
05/form-widget: zod schemas for form definition and theme
- Files:
- Bootstrap-Loader-Build —
packages/form-widget-loader/mitsrc/loader.ts(~2-3KB). Pattern: liestdata-keyaus eigenem Script-Tag, erstellt iframe mitsrc={FORM_WIDGET_CDN_URL}/embed/$formKey?origin=$encodedOrigin, hört auf PostMessagetoolctrl:form:resizefür dynamic-height, emittiert PostMessage-Eventstoolctrl:form:submitted,toolctrl:form:error. Build-Output via esbuild/vite minified mit SRI-Hash-Output für Embed-Code-Generator.- Files:
packages/form-widget-loader/src/loader.ts,packages/form-widget-loader/build.config.ts, Tests - Commit:
05/form-widget: cdn loader script with sri
- Files:
- Embedded-Form-App (iframe-Content) — neue React-Router-Route
apps/web/app/routes/embed.forms.$formKey.tsx(kein Layout, minimal-CSS, kein Auth). Loader: Lookup Form, prüftorigin-Query-Param gegenallowedOriginDomains, returnt Form-Definition + Theme. Component rendert Felder, validiert mit Zod, postet Submission, sendet PostMessage an Parent. Theming via CSS-Variables aus Theme-JSON. Bundle-Size-Budget: <80KB gzipped.- Files:
apps/web/app/routes/embed.forms.$formKey.tsx,apps/web/app/components/embed/FormRenderer.tsx, Field-Components - Commit:
05/form-widget: embedded form renderer route
- Files:
- Submission-API —
apps/web/app/routes/api.embed.forms.$formKey.submit.tsxmitaction. Checks: Origin-Header gegenallowedOriginDomains, Honeypot-Field (Submission mit gefülltem Honeypot → silent 204), optional Turnstile-Token-Verifizieren via Server-API-Call, Rate-Limit via SharedStore (10/min/IP, 100/min/origin). Bei Valid: insert FormSubmission, enqueue Outbox-Eventform.submission.processmit FormSubmission-ID.- Files:
apps/web/app/routes/api.embed.forms.$formKey.submit.tsx,apps/web/app/utils/embed/originCheck.ts,apps/web/app/utils/embed/turnstile.ts, Tests - Commit:
05/form-widget: submission api with anti-spam
- Files:
- Worker-Handler
form.submission.process— verarbeitet je nachtargetType:form-submission→ bleibt als Generic-Row;crm-contact→ upsert Contact via existing CRM-Service mit Field-Mapping;entity-row→ insert Row in Target-Entity. BeiwebhookUrlgesetzt: POST mit Submission-Payload (Retry mit Backoff via Worker-Queue). Markiert FormSubmissionprocessedAt + processingResultJson.- Files:
apps/worker/src/handlers/form.submission.process.ts, Tests - Commit:
05/form-widget: worker handler for submission processing
- Files:
- Form-Builder-UI im Tenant-Admin —
apps/web/app/routes/app.$tenant.forms._index.tsx(Liste),app.$tenant.forms.new.tsx,app.$tenant.forms.$id.tsx(Detail/Edit),app.$tenant.forms.$id.submissions.tsx(Inbox). Builder: drag-drop ist phase-1-Scope groß; stattdessen Field-List mit "Add Field"-Modal + Reorder-Buttons. Field-Editor pro Field-Type. Theme-Editor. Target-Routing-Config mit Field-Mapping-Builder beicrm-contact/entity-row. Settings: success-message, redirect-url, allowedOriginDomains, anti-spam-Toggles, webhook-url.- Files: mehrere Route-Files unter
apps/web/app/routes/app.$tenant.forms.*, Components - Commit:
05/form-widget: tenant admin form builder ui
- Files: mehrere Route-Files unter
- Embed-Code-Generator — auf Form-Detail-Page Button "Embed-Code kopieren": liefert
<script src="$cdnUrl/widget.js" data-widget="form" data-key="$formKey" integrity="sha384-..."></script>mit korrektem SRI-Hash aus aktuellem Build.- Files:
apps/web/app/components/forms/EmbedCodeBlock.tsx, HelpergetWidgetSriHash.server.ts - Commit:
05/form-widget: embed code generator with sri
- Files:
- 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
- Files:
- 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
- Files:
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-Propertycontact_email - Failed-Webhook: Retry mit Backoff, finaler Status
failednach 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.tsund separate Test-HTML-Page inapps/web/tests/fixtures/embed-test-page.html
NICHT als completed markieren bevor alle Tests grün sind.
Acceptance Criteria
- Prisma-Models
Form+FormSubmissionlive packages/forms/exportiert Definition + Theme Zod-Schemaspackages/form-widget-loader/produziert minified loader.js mit SRI-Hash- Embed-Route
/embed/forms/$formKeyrendert sandboxed - Submission-API mit Origin-Check, Honeypot, Turnstile (opt-in), Rate-Limit
- Worker-Handler
form.submission.processroutet 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/resizefunktional docs/features/embeddable-forms.mdmit allen Patterns.env.exampleenthältFORM_WIDGET_CDN_URL,TURNSTILE_SITE_KEY,TURNSTILE_SECRET_KEYpnpm lint,pnpm typecheck,pnpm testgrü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-enabledglobal 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
webhookUrlleeren 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:
webhookUrldarf 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:designfü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
- Branch
agent/05-form-widgetpushen → Coolify-Auto-Deploy - Asset-CDN (aus Phase 03 #46) muss bereit sein; Loader-Build-Output dorthin deployed (CI-Step)
- Migration
pnpm prisma migrate deploy - Turnstile-Test-Keys von Cloudflare in Staging-Env setzen
- 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
- 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 + migration20260517130000_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 totcform:to satisfy the brand-literal i18n guard - 2026-05-17 —
1b9fe344— embedded form renderer route/embed/forms/:formKey - 2026-05-17 —
f6429d7d— submission APIPOST /api/embed/forms/:formKey/submitwith 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:
a6ca7760add @dnd-kit deps,59e2b6b9field palette,7a3addadpalette honeypot fix,4b2350f0canvas + sortable rows (committed alongside the parallel-agent Stripe SDK bump),dfea8a85baseline bump for canvas literals,0c87a6deright-rail FieldProperties editor,62dab273SettingsTab with targetType + field-mapping editor,62a1d6daPreviewTab using embed-route CSS + components,0cc4524aintegrate FormBuilder shell into the form-edit route + CSRF on save,fd15ea32unit tests over uniqueKey + palette factories (6 tests, all green),cb6b1da4docs update
Deviations from Plan
- Historical: Submission routing worker was not shipped in the
first form-widget slice. Current status:
form.submission.processrouting is worker-backed, and webhook / transactional-email follow-ups are bridged throughoutbox.webhookandoutbox.mailonWORKER_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.