# 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](https://dash.cloudflare.com/). 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: ```env # 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: ```bash 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 `` 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`.