81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# 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 `<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`.
|