From 046e905857145220041b7415024c08fa3d19f0de Mon Sep 17 00:00:00 2001 From: Xiaochen Cui Date: Wed, 10 Sep 2025 08:49:38 +0800 Subject: [PATCH] captcha: complete the docs (#1494) --- ... 20250826_captcha_cloudflare_turnstile.md} | 40 +++++++++---------- src/backend/src/routers/signup.js | 2 + 2 files changed, 22 insertions(+), 20 deletions(-) rename doc/RFCS/{20250826_captcha.md => 20250826_captcha_cloudflare_turnstile.md} (53%) diff --git a/doc/RFCS/20250826_captcha.md b/doc/RFCS/20250826_captcha_cloudflare_turnstile.md similarity index 53% rename from doc/RFCS/20250826_captcha.md rename to doc/RFCS/20250826_captcha_cloudflare_turnstile.md index 2011833a7..863e7181f 100644 --- a/doc/RFCS/20250826_captcha.md +++ b/doc/RFCS/20250826_captcha_cloudflare_turnstile.md @@ -1,5 +1,5 @@ - Feature Name: Cloudflare Turnstile CAPTCHA -- Status: In Progress +- Status: Completed - Created: 2025-08-26 ## Summary @@ -23,20 +23,14 @@ We choose Cloudflare Turnstile since: Here's a comparison of major CAPTCHA providers: -| Provider | Security (typical) | User experience (typical) | Price (publicly listed) | -| --------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Cloudflare Turnstile** | **High** 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][1], [cloudflare.com][2]) | -| **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][3]) | -| **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][4]) | -| **Friendly Captcha** | **Medium–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][5]) | -| **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][6]) | -[1]: https://blog.cloudflare.com/turnstile-ga/?utm_source=chatgpt.com "Cloudflare is free of CAPTCHAs; Turnstile is free for everyone" -[2]: https://www.cloudflare.com/application-services/products/turnstile/?utm_source=chatgpt.com "Cloudflare Turnstile | CAPTCHA Replacement Solution" -[3]: https://cloud.google.com/recaptcha/docs/compare-tiers?utm_source=chatgpt.com "Compare features between reCAPTCHA tiers" -[4]: https://www.hcaptcha.com/pricing?utm_source=chatgpt.com "Pricing" -[5]: https://friendlycaptcha.com/ "Friendly Captcha - Privacy-First Bot Protection" -[6]: https://www.arkoselabs.com/arkose-matchkey/?utm_source=chatgpt.com "Arkose MatchKey Advanced CAPTCHA Software" +| Provider | Security (typical) | User experience (typical) | Price (publicly listed) | +| ----------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Cloudflare Turnstile** | **High** 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](https://blog.cloudflare.com/turnstile-ga/?utm_source=chatgpt.com), [cloudflare.com](https://www.cloudflare.com/application-services/products/turnstile/?utm_source=chatgpt.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](https://cloud.google.com/recaptcha/docs/compare-tiers?utm_source=chatgpt.com)) | +| **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](https://www.hcaptcha.com/pricing?utm_source=chatgpt.com)) | +| **Friendly Captcha** | **Medium–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](https://friendlycaptcha.com/)) | +| **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](https://www.arkoselabs.com/arkose-matchkey/?utm_source=chatgpt.com)) | ## Implementation @@ -47,11 +41,17 @@ On the backend, Puter will call the **Cloudflare Turnstile verification API** to 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. -### Desktop Rendering +## Setup -TODO - -## Configuration - -TODO +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](https://developers.cloudflare.com/turnstile/concepts/widget/) 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": "", + "secret_key": "" + } + ``` diff --git a/src/backend/src/routers/signup.js b/src/backend/src/routers/signup.js index af7b43fca..f362bf067 100644 --- a/src/backend/src/routers/signup.js +++ b/src/backend/src/routers/signup.js @@ -84,6 +84,8 @@ module.exports = eggspress(['/signup'], { // cloudflare turnstile validation + // + // ref: https://developers.cloudflare.com/turnstile/get-started/server-side-validation/ if (config.services?.['cloudflare-turnstile']?.enabled) { const formData = new FormData(); formData.append('secret', config.services?.['cloudflare-turnstile']?.secret_key);