Files
webb/CLOUDFLARE_TURNSTILE_SETUP.md
T

3.9 KiB

Cloudflare Turnstile Integration & Activation Guide

This document explains how to activate and manage Cloudflare Turnstile bot protection on the CRE Innovations Web Studio platform.

Firebase Authentication has been completely replaced with Cloudflare Turnstile, providing frictionless, privacy-preserving bot and abuse protection across all AI inference tools and forms.


⚡ Quick Activation (2 Minutes)

To activate Cloudflare Turnstile, follow these simple steps:

Step 1: Open Cloudflare Dashboard

  1. Go to the Cloudflare Dashboard.
  2. Log in (or create a free Cloudflare account if you don't have one).

Step 2: Create a Turnstile Widget

  1. In the left navigation menu, click Turnstile (under Application Services).
  2. Click Add widget (or Add site).
  3. Fill in the widget details:
    • Widget name: CRE Innovations Studio (or any name you prefer).
    • Domains:
      • Add localhost (for local development and testing).
      • Add your production domain (e.g., creinnovations.in or yourdomain.com).
      • Add staging / preview domains if applicable (e.g. *.vercel.app).
    • Widget Mode:
      • Select Managed (Recommended): Cloudflare decides when to run an invisible background check vs. showing an interactive checkbox based on risk level.
      • Or select Non-interactive / Invisible based on your security preference.
  4. Click Create.

Step 3: Copy Your Keys

Cloudflare will display two keys:

  1. Site Key (Public, starts with 0x4AAAAAA...)
  2. Secret Key (Private, starts with 0x4AAAAAA...)

Step 4: Add Keys to .env.local

In the root directory of WEBB (and WEBB_EDITOR if running separately), open or create .env.local and add:

# Cloudflare Turnstile Keys
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_copied_site_key_here
CLOUDFLARE_TURNSTILE_SECRET_KEY=your_copied_secret_key_here

Step 5: Restart the Server

Restart the Next.js process:

npm run build && npm run start

Done! Cloudflare Turnstile is now active and protecting all AI inference calls against automated bots and scrapers.


🧪 Testing Locally (Zero Setup Test Keys)

Cloudflare provides official testing keys so you can test all scenarios immediately without needing a Cloudflare account:

Scenario Site Key (Public) Secret Key (Server) Expected Behavior
Always Passes 1x00000000000000000000AA 1x0000000000000000000000000000000AA Automatically passes verification without interaction.
Always Fails / Blocks 2x00000000000000000000AB 2x0000000000000000000000000000000AA Verification always fails; server rejects with HTTP 403.
Interactive Challenge 3x00000000000000000000FF 1x0000000000000000000000000000000AA Forces user to click the verification checkbox.

Note

If neither NEXT_PUBLIC_TURNSTILE_SITE_KEY nor CLOUDFLARE_TURNSTILE_SECRET_KEY is set in .env.local, the app defaults to the Always Passes test key in development so you are never locked out during development.


🛡️ Architecture & Verification Flow

  1. Client:
    • The user opens a tool workspace (e.g. /tools/blemish-remover).
    • The lightweight <TurnstileWidget /> loads dynamically from challenges.cloudflare.com.
    • Upon successful verification, a temporary token cf-turnstile-response is generated.
  2. Execution:
    • When the user clicks Process / Run, cf-turnstile-response is included in the multipart FormData sent to /api/try/[toolId].
  3. Server Verification:
    • /api/try/[toolId] validates the token against https://challenges.cloudflare.com/turnstile/v0/siteverify using CLOUDFLARE_TURNSTILE_SECRET_KEY.
    • If verification succeeds, GPU inference proceeds.
    • If verification fails or is omitted by a bot, the request is immediately rejected with HTTP 403 BOT_VERIFICATION_FAILED.