Filament Turnstile Laravel Package

Technical Evaluation

Architecture fit. l3aro/filament-turnstile is a thin Filament form-field wrapper around Cloudflare Turnstile. It ships a Turnstile::make('captcha') field, backed-enums for theme/size/language, a Blade view, and a config file holding site key, secret key, and a configurable reset event name. The integration surface is a single schema component plus a Livewire browser event, so it slots into any Filament panel without touching application architecture. Fits well if we already run Filament and want CAPTCHA on auth or public forms — the alternative is hand-rolling the same thing (a Blade partial, a siteverify rule, and a reset listener), which is maybe a day of work but fully owned.

Integration feasibility. Composer install, two artisan publish commands, two env vars, one schema line. The README's Login-page recipe (subclass Filament\Pages\Auth\Login, override getForms() and throwFailureValidationException(), re-point ->login() in the PanelProvider) is copy-pasteable and low-risk. Real feasibility risk is version drift: the README example uses the Filament v3 API (Filament\Forms\Form, ->schema()), while the changelog shows a v5 upgrade in 1.0.6 and Laravel 13 support in 1.1.0. That mismatch means the docs are not a reliable spec for our target Filament major — treat the changelog and source, not the README, as authoritative.

Technical risk.

• Adoption/validation risk (high for a TPM): 11 stars, 0 dependents, single maintainer. There is no third-party evidence of production use. That is not disqualifying for a component this small, but it means we are the QA.
• Trust boundary: the README never explicitly documents the server-side siteverify call, token single-use semantics, or the 300-second token lifetime. Any CAPTCHA that only renders client-side is decorative. Verifying the server-side path is a gating question, not a nice-to-have.
• Stale docs vs. released code is the most likely source of a failed sprint.
• Bus factor 1: MIT license, ~a few hundred lines — we can vendor or fork cheaply. This materially de-risks the dependency.
• Third-party runtime dependency: challenges.cloudflare.com becomes a hard dependency on our auth path.

Key questions.

1. Does the field perform server-side verification, and what happens on a network timeout vs. an explicit success: false?
2. Is the token single-use enforced on our side (replay protection on retried Livewire requests)?
3. Which Filament majors are actually supported in 1.1.1 — v3, v4, v5, or a subset?
4. What does v1.1.1's "only required if credentials are configured" mean exactly — can we ship the field in dev/CI with no keys and no validation?
5. Is the reset event purely client-side, and can it be dispatched from a non-Livewire context?
6. CSP story: what domains must be allowlisted, and is the reset event name conflict-prone with our own JS?

Integration Approach

Stack fit. Laravel + Filament, Pest test suite, Composer/Packagist distribution, env-var configuration. It matches the default shape of our stack with no bespoke bootstrapping. If we are on a Filament version outside the verified matrix, the field is small enough to copy into app/Filament/Forms/ and own outright — a credible Plan B we should price up front.

Migration path. Greenfield: nothing to migrate. Existing reCAPTCHA/hCaptcha: no automated path — it is a per-form swap of the widget plus removal of the old verification rule, so treat it as a small, enumerable refactor rather than a migration. Existing forms that already have a custom CAPTCHA: run both in parallel only in staging, never in production, to avoid double-challenge friction.

Compatibility. Confirm the installed Filament major before estimating. Laravel 13 support in 1.1.0 is good forward signal; Filament 5 support landed in 1.0.6. Pin to an exact minor (^1.1.1) and record the Filament version in the ticket, because this package's compatibility is expressed through prose, not a hard constraint we can read from a matrix.

Sequencing.

1. Spike (0.5 day): install on a scratch panel, prove the siteverify round-trip with Cloudflare's documented dummy keys, confirm failure behaviour with the network blocked.
2. Pilot (1–2 days): instrument one low-consequence form — password reset or a public contact form. Not login.
3. Roll out to customer-facing login and registration once the pilot shows clean telemetry over a full week.
4. Admin panel login last, and only with a break-glass path (see below).
5. Cleanup: remove any prior CAPTCHA code, add CSP entries, document the reset-event convention in the runbook.

Operational Impact

Maintenance. Low volume, low surface: dependabot already runs upstream, and the code is small. Our exposure is not churn, it is abandonment. Mitigation: pin the version, keep a one-page "fork and inline this field" runbook with the exact two files to copy, and review at each Filament major upgrade — that upgrade, not this package's releases, is the real maintenance trigger.

Support. No commercial support, no SLA, no documented issue-triage cadence. Escalation path is a GitHub issue to a single maintainer, or our own fork. For an auth-path dependency, decide now who owns the fork if upstream goes quiet — realistically the same engineer who owns the Filament panel.

Scaling. Negligible: Turnstile is a client-side widget plus one outbound HTTPS call per submission. It does not touch our database or session layer. The scaling concern is Cloudflare's, and their free tier is generous; per-submission verification adds tens of milliseconds to form posts, invisible outside a synthetic benchmark.

Failure modes. These are the ones that will page someone:

• Cloudflare outage or regional block → every protected form, including admin login, hard-fails. This is the top risk and the reason admin login goes last with a bypass.
• Ad-blocker / privacy extension blocks the widget script → legitimate users cannot submit. Needs a fallback (server-side rate limiting, or a support channel).
• Secret key misconfiguration or rotation → universal failure with a generic error. Requires alerting on verification failure rate, not just on exceptions.
• Token expiry on slow forms → user completes the challenge, token lapses before submit, confusing rejection. The reset-on-validation-error pattern in the README mitigates but does not eliminate this.
• Break-glass: maintain a documented, audited way to disable Turnstile on the admin panel via env var without a deploy. Non-negotiable for an auth dependency.

Ramp-up. Small. One Laravel/Filament-fluent engineer, under a day to be productive, including the spike. No new concepts beyond Cloudflare key management and Livewire event dispatching. The README's login example is the best onboarding artefact — with the caveat that its Filament API version must be checked against ours before anyone follows it literally.

Recommendation. Adopt conditionally for customer-facing forms; the cost of entry is near zero and the code is trivially forkable. Gate admin-panel login on the spike confirming genuine server-side verification plus a working break-glass bypass. The dominant risk is not the package's quality but the combination of a single maintainer and an auth-path dependency — a risk we can retire cheaply because of the MIT license and small footprint.