Filament Turnstile Laravel Package

Technical Evaluation

Scope of evidence This assessment is written against the v1.0.0 → v1.2.0 delta for happenv-com/filament-turnstile. The only release artifact provided is a bare GitHub compare link with no per-release notes, no migration guide, and no enumerated breaking changes. The evaluation below is therefore based on the package's stated purpose (a Filament form component for Cloudflare Turnstile) and on Laravel/Filament ecosystem conventions; all version-specific claims must be validated against the tagged source and composer.json constraints before adoption.

Architecture fit

• Narrow, well-bounded responsibility: renders the Turnstile widget inside Filament forms and (presumably) validates the returned token server-side against Cloudflare's siteverify endpoint. This is a leaf dependency — it does not touch persistence, auth, or queue topology, so it will not distort our domain architecture.
• Fit is strongest where Filament is already the admin/back-office surface: login, registration, password reset, contact and lead-capture forms. It is not a general-purpose CAPTCHA layer for public APIs or Inertia/Livewire front-ends outside Filament panels.
• Introduces a hard runtime dependency on a third-party SaaS (Cloudflare) in the request path of form submission. That is an architectural decision, not a package decision — treat it as such at review.

Integration feasibility

• Expected path is low-friction: Composer install, publish config, set site/secret keys via env, add the field to form schemas, optionally register a validation rule. Typical effort for a Laravel-fluent engineer is on the order of half a day for a first form, one to two days to harden and test.
• Two integration seams carry most of the risk: (1) whether server-side verification is performed by the package or must be wired up by us, and (2) how the package behaves when keys are absent (dev/CI environments) — a silent pass-through is convenient but must be provably disabled in production.
• Filament's major-version cadence is the dominant feasibility variable. Confirm the package supports our pinned Filament major (v3 vs v4) and Laravel version before any spike.

Technical risk

• Version-jump opacity (elevated). Going 1.0.0 → 1.2.0 with no notes means we cannot distinguish additive features from behavioral changes. Semver implies no breaking API change, but Laravel ecosystem packages frequently ship dependency-constraint changes in minors that are breaking in practice.
• Bus factor / vendor maturity. A single-purpose package from a small publisher warrants a repository health check: commit recency, issue/PR responsiveness, CI status, test coverage, license, and whether abandoned forks exist.
• Fail-open vs fail-closed. The most consequential unknown. If Cloudflare is unreachable or keys are misconfigured, does submission get blocked (availability incident) or silently allowed (security control void)? We need the answer in writing.
• Compliance exposure. Turnstile transmits client signals to Cloudflare. That requires a DPA, a privacy-notice update, and a documented lawful basis for EU/UK traffic. This is often missed in package reviews and is a product-visible obligation.
• Accessibility and UX. CAPTCHA-adjacent controls have a history of WCAG friction and can suppress conversion on public-facing forms.

Key questions

1. Does the package perform server-side siteverify, or only render the widget client-side?
2. What are the exact composer.json constraints for php, laravel/framework, and filament/filament?
3. What changed between v1.0.0 and v1.2.0 — features, config keys, dependency bumps, or behavior defaults?
4. Is there a documented bypass/fake mode for local and CI, and is it env-gated safely by default?
5. How are missing, expired, replayed, or invalid tokens handled — validation message, exception, or silent pass?
6. Does it support multiple panels and multiple forms on one page, and is it localization-ready?
7. Is a CSP nonce/allowlist for challenges.cloudflare.com documented?
8. Is there a test suite and CI pipeline we can inspect, and what is the license?

Integration Approach

Stack fit

• Assumes the standard Laravel + Filament (TALL: Tailwind, Alpine, Laravel, Livewire) stack. No new infrastructure, no additional datastore, no queue or worker changes.
• Configuration expected via env (TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY style) plus a publishable config file — consistent with our existing twelve-factor config conventions. Ensure secrets land in the secret manager, not in committed .env examples.
• If we run multiple Filament panels (admin, partner, public), confirm key resolution is per-panel or global by explicit choice rather than accident.

Migration path

• Net-new adoption, so there is no legacy migration. The only "migration" is scope: start with a single low-risk form (e.g. internal admin login or a staging contact form) before touching public registration or lead capture.
• Pin the exact version in composer.json (e.g. 1.2.* or a lockfile-pinned 1.2.0) rather than a floating ^1.0, precisely because the release notes do not describe the delta.
• Rollback is a config revert plus removing the field from the form schema — cheap, provided server-side verification is not entangled with our own form-handling code. Keep that verification boundary explicit so it can be disabled independently.

Compatibility

• Verify against our actual matrix: PHP version, Laravel LTS/current, Filament major, Livewire major, and our test runner. Filament v4's schema/component API differs materially from v3; a package supporting one will not work on the other.
• Check for conflicts with any existing CAPTCHA, rate-limiting, or bot-mitigation stack (e.g. laravel/throttle, WAF rules, honeypot fields) to avoid double-penalizing legitimate users.
• Confirm behavior under php artisan config:cache and in queue/CLI contexts where no HTTP request exists.

Sequencing

1. Discovery (0.5 day): read the actual v1.0.0…v1.2.0 diff, composer.json, README, and license; answer the key questions above.
2. Spike (1 day, non-production): integrate into one Filament form in staging; exercise happy path, expired token, invalid key, and Cloudflare-unreachable scenarios.
3. Security & compliance gate (parallel): confirm fail-closed behavior, confirm dev bypass cannot reach production, confirm DPA and privacy-notice updates are owned by someone.
4. Pilot (1 week): single production form, instrumented for submit-failure rate and latency delta.
5. Broaden: roll to remaining forms, then add to the dependency-update ritual with a named owner.

Operational Impact

Maintenance

• Low ongoing surface: one Composer dependency, one config file, environment keys. Real cost sits in tracking upstream — Filament major releases will force package upgrades, and a slow-moving upstream can block our own Filament upgrades.
• Assign ownership and add the package to the dependency-review cadence. Given the thin release documentation, treat every minor bump as reviewable rather than auto-merged, at least for the first several releases.
• Rotating Turnstile keys should be a documented runbook step; if it is not trivial, that is itself a finding.

Support

• Tier-1 support will see "the form won't submit" tickets that are actually Cloudflare-side or key-config issues. Publish an internal runbook covering the three common causes: domain not registered on the Turnstile widget, expired token, CSP blocking.
• Upstream support is community-only (GitHub issues) unless a commercial arrangement exists. Do not assume response SLAs. Budget for the possibility that we maintain a fork or vendor a patch.

Scaling

• Negligible infrastructure cost: the widget is a static client-side script and verification is one outbound HTTPS call per submission, roughly 100–300 ms added to submit latency.
• Horizontally safe — no shared state, no sticky sessions, no local cache. Cloudflare's siteverify is the only external ceiling and our submission volume is far below any plausible limit.
• Watch the client-side script weight on high-traffic public pages and the per-request outbound call under submission spikes; neither is a scaling blocker at our volumes but both are measurable.

Failure modes

• Cloudflare outage or network egress block → all protected forms fail (fail-closed) or silently lose protection (fail-open). Decide the intended posture before launch and test it deliberately; do not discover it in an incident.
• Token expiry / replay → tokens are short-lived; slow users or double-submits can produce confusing errors. Verify the validation message is user-comprehensible.
• Misconfigured or missing keys → worst case is a silent no-op in production. Add a startup/health assertion that keys are present in production config.
• CSP or ad-blocker interference → script blocked → widget never renders → permanent submit failure for affected users. Allowlist the Turnstile domains and monitor the failure rate as a product metric, not just an error log.
• Regional availability → Turnstile is not universally reachable; users on restricted networks may be locked out. Consider a fallback path if public-facing forms are in scope.
• Upstream abandonment → no fix for a future Filament incompatibility. Mitigation is the fork option and the low switching cost to an alternative Turnstile integration.

Ramp-up

• A Laravel/Filament-fluent engineer is productive on the first form within a day; no specialized knowledge required beyond reading Cloudflare's Turnstile docs.
• Non-obvious knowledge to transfer: fail-open/fail-closed posture, key rotation, CSP allowlist entries, and the dev/CI bypass mechanism. Capture these in the runbook at pilot time rather than after the first incident.
• Total cost to a hardened pilot: approximately 2–3 engineer-days including compliance review. Recommend adoption conditional on answering the key questions and confirming fail-closed behavior — with the explicit caveat that the v1.0.0→v1.2.0 release notes are insufficient to certify the change as non-breaking.