ContextQMD
Back to Puter

20250826 Captcha Cloudflare Turnstile

doc/RFCS/20250826_captcha_cloudflare_turnstile.md

2.5.15.5 KB
Original Source
  • Feature Name: Cloudflare Turnstile CAPTCHA
  • Status: Completed
  • Created: 2025-08-26

Summary

We propose integrating Cloudflare Turnstile to protect our signup flow against automated bot activity, while maintaining a seamless experience for legitimate users.

Motivation

Puter allocates resources to free user account — including storage, compute, and AI credits. To prevent these from being exploited by bots, we need a more robust verification mechanism. Although Puter currently includes a custom CAPTCHA service, it has several shortcomings:

  • The text-recognition CAPTCHA creates friction and disrupts the user experience.
  • Maintaining a token pool is resource-intensive and doesn’t scale well. The validation logic also requires ongoing maintenance within the codebase.

Choose of Service Provider

We choose Cloudflare Turnstile since:

  • It's free for unlimited use.
  • It's easy to integrate.
  • It's relative secure.

Here's a comparison of major CAPTCHA providers:

ProviderSecurity (typical)User experience (typical)Price (publicly listed)
Cloudflare TurnstileHigh for most sites; adaptive challenges; works without image puzzles.Excellent (can be fully invisible or auto-verify; checkbox only for risky traffic).Free for everyone (unlimited use). (The Cloudflare Blog, cloudflare.com)
Google reCAPTCHA (Essentials / Standard / Enterprise)Medium–High (v3 score + server rules; Enterprise adds features & support).Good–OK (v3 is invisible; v2 can show puzzles).Free up to 10k assessments/mo; $8 for up to 100k/mo; then $1 per 1k (Enterprise tiers). (Google Cloud)
hCaptcha (Basic / Pro / Enterprise)High (ML signals; enterprise options).Good on Basic; Very good on Pro with “low-friction 99.9% passive mode.”Basic: Free. Pro: $99/mo annual ($139 month-to-month) incl. 100k evals, then $0.99/1k; Enterprise custom. (hcaptcha.com)
Friendly CaptchaMedium–High (proof-of-work + risk signals).Excellent (invisible/automatic challenge; no image tasks).Starter €9/mo (1k req/mo); Growth €39/mo (5k/mo); Advanced €200/mo (50k/mo); Free non-commercial 1k/mo; Enterprise custom. (Friendly Captcha)
Arkose Labs (FunCaptcha / MatchKey)Very High (step-up, anti-farm, enterprise focus).Good–OK (challenge can be more involved when risk is high).Enterprise pricing (contact sales); publicly not listed. (Product overview only.) (Arkose Labs)

Implementation

Signup Flow

When a user submits the signup form, the client will include a Turnstile token alongside the other form data. On the backend, Puter will call the Cloudflare Turnstile verification API to validate this token before provisioning a new account.

Only if the token is verified as valid will the signup request be processed. Invalid or missing tokens will result in a rejected signup attempt.

Setup

  1. Create a new Widget on the Cloudflare Turnstile dashboard.

  2. Configure Widget name and Hostnames.

  3. Set Widget Mode to Managed and pre-clearance to Yes - Interactive. These settings minimize friction for legitimate users while also giving suspicious users one more chance to clear the CAPTCHA. (See Turnstile widgets · Cloudflare Turnstile docs for details)

  4. Add Site Key and Secret Key to the config file (default location: volatile/config/config.json):

    "cloudflare-turnstile": {
    "enabled": true,
    "site_key": "<your-site-key>",
    "secret_key": "<your-secret-key>"
}