Filament Turnstile Laravel Package

Product Decisions This Supports

• Spam/bot protection as a shippable feature, not a project. Adding a captcha to Filament auth and public forms becomes a composer install plus a config/env change, then a single Turnstile::make('captcha') field. This is an hours-level task, not a sprint — realistic to slot into an existing iteration alongside other work.
• Build vs. buy on captcha integration. The "build" option is not the captcha itself (Cloudflare Turnstile is free and hosted); it is the Filament-specific glue: form field component, asset/script loading, theme/size/language options, reset-event handling on validation failure and post-submit. That glue is ~1–2 engineer-days plus ongoing maintenance across Filament majors. Buying (adopting) is the rational default; forking is the fallback.
• Roadmap input: which surfaces get protected first. The package is form-field based, so it maps cleanly onto a prioritized order — admin/staff login (highest credential-stuffing risk, smallest blast radius), customer registration and password reset, public contact/lead forms, then any unauthenticated Filament form. Use that order as the rollout plan.
• Vendor/tech choice: Turnstile vs. reCAPTCHA vs. hCaptcha. Turnstile is free at essentially any volume, largely invisible to users, and positioned as privacy-friendly (no cross-site tracking cookies). That is a product decision about conversion rate and privacy posture, not just security — it lets you defend "we added friction to login" internally and in a privacy policy/DNS review.
• Reduced credential-stuffing and abuse exposure is measurable. Bot protection on login directly supports KPIs you likely already report: failed-login rate, account lockout volume, junk-signup rate, and support load from spam. It also de-risks brute-force-driven incident response.
• Configurability as a product lever, not a chore. Theme, size, language and a customizable reset event are exposed; language alone supports localization rollouts, and the reset event lets you tune UX (fresh challenge after failure vs. reuse) without engineering rework.
• Test-environment support. Cloudflare's dummy keys mean QA can exercise the flow in staging without bypassing the control, which keeps release confidence honest.

When to Consider This Package

Adopt when all of these hold:

• You are on Filament (this plugin targets Filament v4/v5-era releases; the changelog shows an explicit Filament v5 upgrade and Laravel 13 support tracking). Non-Filament or heavily customized front-ends get much less value.
• You need protection on Filament-rendered forms — most commonly Login, registration, and password reset pages, or a public-facing panel form.
• You can live with basic form-field ergonomics: one captcha field per form, configured via Enums and env vars.
• You want zero or near-zero cost and no procurement cycle — MIT license, Cloudflare keys are free.
• Your team is small and you'd rather not own Filament asset-injection code across upgrades.

Look elsewhere or build in-house when:

• Non-Filament surfaces dominate. Public marketing forms, API endpoints, or a separate Next.js/Vue front-end need Turnstile integrated directly against Cloudflare's client/server SDKs; this package won't help there.
• You need enterprise-grade vendor assurance. This is a single-maintainer package with 11 stars and 0 dependents — no commercial support, no SLA, no security-response commitment beyond a policy file. If your org requires a supported vendor, use Cloudflare's own SDKs or a commercial alternative.
• You need guarantees about long-term maintenance. The project is active (recent releases, Dependabot, tests, changelog) but tiny. Treat it as "small dependency you may have to fork."
• You need advanced bot mitigation — rate limiting, behavioral scoring, WAF rules, server-side verification middleware applied across many routes. Turnstile + a Laravel rate limiter is the real answer; this plugin is only the form widget.
• Filament version drift is a risk you can't absorb. If you're on an older Filament major, verify compatibility before committing; the changelog shows a break-and-catch-up pattern around Filament v5.

Risk mitigations to price in:

• Pin the version in composer.json and review the changelog on upgrade.
• Budget a contingency: the package is MIT and small, so a fork-and-maintain path is genuinely cheap (one field class + a Blade view + a facade).
• Confirm the server-side verification behavior of the release you adopt — note v1.1.1 changed behavior to "only required if credentials are configured," meaning a misconfigured .env may silently skip enforcement. Add a deploy-time check that keys exist in production and a smoke test that a missing/invalid token is rejected.

How to Pitch It (Stakeholders)

To executives (one paragraph): Our admin panel and customer login are internet-facing and currently accept unlimited automated attempts. This is a small, MIT-licensed, free-to-use plugin that adds Cloudflare Turnstile — Cloudflare's human-verification widget — to our Filament forms, starting with login. Costs are effectively zero (Cloudflare's service is free), the work is measured in hours, and the user-facing impact is minimal because the check is largely invisible. It reduces credential-stuffing, junk signups, and spam-form support load, and it strengthens our privacy position versus reCAPTCHA because Turnstile doesn't track users across sites. The one caveat is that the plugin is maintained by a single developer with low adoption, so we treat it as a small, forkable dependency rather than a strategic vendor.

To engineering (the ask): Adopt as a thin dependency rather than building the glue ourselves. It ships a Filament form field (Turnstile::make('captcha')) with theme/size/language Enums, env-based keys (TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY), a publishable config, and a customizable reset event so we can refresh the challenge on validation failure (documented pattern via onValidationError / throwFailureValidationException, or explicit $this->dispatch(FilamentTurnstileFacade::getResetEventName())). Implementation is: composer install, publish config, extend the Login page to add the field, override login() in the PanelProvider, wire the reset dispatch. Tests exist (composer test / Pest) and Cloudflare dummy keys cover staging.

What we should explicitly own:

• Pin the version; add a scheduled dependency-review check.
• Assert keys are present in production and fail loudly if not — given v1.1.1's "only required if credentials are configured" behavior, silent non-enforcement is the main failure mode.
• Smoke test the rejection path (invalid/absent token must block submission) in staging as part of the release checklist.
• Accept the fork contingency: if upstream goes dormant, we can vendor and maintain the single field class ourselves at low cost.