docs: expand Cloudflare Turnstile setup guide with complete activation steps, testing keys, and architecture
This commit is contained in:
+130
-55
@@ -1,80 +1,155 @@
|
||||
# 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.
|
||||
This runbook documents the complete replacement of **Firebase Authentication** with **Cloudflare Turnstile** bot and abuse protection across the CRE Innovations Web Studio platform, and provides step-by-step instructions for activating and testing it.
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Activation (2 Minutes)
|
||||
## 📋 Table of Contents
|
||||
1. [Overview & What Changed](#overview--what-changed)
|
||||
2. [Quick Activation (2 Minutes)](#quick-activation-2-minutes)
|
||||
3. [Environment Configuration](#environment-configuration)
|
||||
4. [Testing Locally (Zero-Setup Test Keys)](#testing-locally-zero-setup-test-keys)
|
||||
5. [Technical Architecture & Verification Flow](#technical-architecture--verification-flow)
|
||||
6. [Production Deployment Guide](#production-deployment-guide)
|
||||
7. [Troubleshooting & FAQs](#troubleshooting--faqs)
|
||||
|
||||
To activate Cloudflare Turnstile, follow these simple steps:
|
||||
---
|
||||
|
||||
## 1. Overview & What Changed
|
||||
|
||||
Firebase Authentication has been **completely removed** from the repository to eliminate authentication friction, OAuth consent requirements, and complex Google Cloud service account setups.
|
||||
|
||||
In its place, **Cloudflare Turnstile** provides lightweight, privacy-preserving bot protection that verifies human visitors without frustrating puzzles (no crosswalks, traffic lights, or CAPTCHA solving):
|
||||
|
||||
### Files Removed (Firebase):
|
||||
- `src/lib/firebase/` (`admin.ts`, `AuthContext.tsx`, `config.ts`, `serverAuth.ts`)
|
||||
- `src/components/auth/` (`AuthModal.tsx`, `UserMenu.tsx`)
|
||||
- `src/app/api/auth/session/route.ts`
|
||||
- `tests/auth.test.ts`
|
||||
- `FIREBASE_SETUP.md`
|
||||
- `firebase` and `firebase-admin` dependencies removed from `package.json`
|
||||
|
||||
### Files Added / Updated (Cloudflare Turnstile):
|
||||
- `src/lib/turnstile.ts`: Server-side token validation against `https://challenges.cloudflare.com/turnstile/v0/siteverify`.
|
||||
- `src/components/turnstile/TurnstileWidget.tsx`: SSR-safe, dynamic client component with real-time status micro-badges.
|
||||
- `src/app/api/try/[toolId]/route.ts`: Validates `cf-turnstile-response` token before executing GPU neural pipelines.
|
||||
- `src/components/tools/DynamicToolWorkspace.tsx`: Turnstile widget embedded right above the Process button with automatic token attachment to `FormData`.
|
||||
- `src/components/sections/TryItWidget.tsx`: Turnstile verification integrated into quick-try card.
|
||||
- `src/components/ui/Navbar.tsx`: Restored clean header without Firebase login modals.
|
||||
- `src/app/layout.tsx`: Restored clean root layout without `<AuthProvider>`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Quick Activation (2 Minutes)
|
||||
|
||||
Activating Cloudflare Turnstile is **100% free** and takes under two minutes.
|
||||
|
||||
### 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).
|
||||
1. Navigate to the [Cloudflare Dashboard](https://dash.cloudflare.com/).
|
||||
2. Log in with your Cloudflare account (or create a free account).
|
||||
|
||||
### Step 2: Create a Turnstile Widget
|
||||
1. In the left navigation menu, click **Turnstile** (under Application Services).
|
||||
1. In the left navigation menu, expand **Application Services** and click **Turnstile**.
|
||||
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`).
|
||||
3. Fill in the widget form:
|
||||
- **Widget name**: `CRE Innovations Studio` (or your preferred name).
|
||||
- **Domains**:
|
||||
- `localhost` *(required for local development and testing)*
|
||||
- `127.0.0.1` *(optional, for IP-based local tests)*
|
||||
- Your production domain (e.g. `creinnovations.in` or `yourdomain.com`).
|
||||
- Any preview / staging domains (e.g. `*.vercel.app` or `*.railway.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.
|
||||
- **Managed** *(Recommended)*: Cloudflare automatically decides when to run an invisible background check vs. showing a single unobtrusive checkbox if risk is elevated.
|
||||
- **Non-interactive**: Runs a purely automated browser challenge without user interaction.
|
||||
- **Invisible**: Completely invisible background token verification.
|
||||
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...`)
|
||||
Cloudflare displays two API keys on the completion screen:
|
||||
- **Site Key** (Public): Starts with `0x4AAAAAA...`
|
||||
- **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:
|
||||
---
|
||||
|
||||
## 3. Environment Configuration
|
||||
|
||||
### Local Environment (`.env.local`)
|
||||
Create or edit `.env.local` in the project root:
|
||||
|
||||
```env
|
||||
# Cloudflare Turnstile Keys
|
||||
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_copied_site_key_here
|
||||
CLOUDFLARE_TURNSTILE_SECRET_KEY=your_copied_secret_key_here
|
||||
# ---------------------------------------------------------------------------
|
||||
# Cloudflare Turnstile Bot & Anti-Abuse Protection
|
||||
# ---------------------------------------------------------------------------
|
||||
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_actual_site_key_from_cloudflare
|
||||
CLOUDFLARE_TURNSTILE_SECRET_KEY=your_actual_secret_key_from_cloudflare
|
||||
```
|
||||
|
||||
### 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.
|
||||
> If `CLOUDFLARE_TURNSTILE_SECRET_KEY` is omitted or empty during local development, the server gracefully logs a notice and bypasses the check so developers are never blocked while provisioning keys.
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Architecture & Verification Flow
|
||||
## 4. Testing Locally (Zero-Setup Test Keys)
|
||||
|
||||
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`.
|
||||
Cloudflare maintains official dummy keys that allow testing all pass, fail, and interactive scenarios immediately without creating a Cloudflare account:
|
||||
|
||||
| Testing Scenario | Public Site Key (`NEXT_PUBLIC_TURNSTILE_SITE_KEY`) | Server Secret Key (`CLOUDFLARE_TURNSTILE_SECRET_KEY`) | What Happens |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Always Passes** | `1x00000000000000000000AA` | `1x0000000000000000000000000000000AA` | Instantly validates without user clicking. Inference succeeds. |
|
||||
| **Always Blocks / Fails** | `2x00000000000000000000AB` | `2x0000000000000000000000000000000AA` | Challenge fails. Server responds with HTTP `403 BOT_VERIFICATION_FAILED`. |
|
||||
| **Interactive Checkbox** | `3x00000000000000000000FF` | `1x0000000000000000000000000000000AA` | Shows interactive "Verify you are human" checkbox. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Technical Architecture & Verification Flow
|
||||
|
||||
```
|
||||
[ User Browser ]
|
||||
│
|
||||
▼ (1) Loads /tools/[slug]
|
||||
[ TurnstileWidget ] ───> Cloudflare CDN (challenges.cloudflare.com)
|
||||
│
|
||||
▼ (2) Human verification complete -> returns 'cf-turnstile-response' token
|
||||
[ DynamicToolWorkspace ]
|
||||
│
|
||||
▼ (3) POST /api/try/[toolId] (FormData with file + 'cf-turnstile-response')
|
||||
[ Next.js Server Route ]
|
||||
│
|
||||
▼ (4) POST https://challenges.cloudflare.com/turnstile/v0/siteverify
|
||||
│ Body: { secret: CLOUDFLARE_TURNSTILE_SECRET_KEY, response: token, remoteip: ip }
|
||||
│
|
||||
├─► [FAIL] ──► Return HTTP 403 { code: 'BOT_VERIFICATION_FAILED' }
|
||||
│
|
||||
└─► [PASS] ──► Execute backend GPU model pipeline & stream lossless 4K result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Production Deployment Guide
|
||||
|
||||
### Vercel / Railway / Render / AWS
|
||||
Add these two Environment Variables in your hosting dashboard:
|
||||
- `NEXT_PUBLIC_TURNSTILE_SITE_KEY`: Your production Turnstile Site Key.
|
||||
- `CLOUDFLARE_TURNSTILE_SECRET_KEY`: Your production Turnstile Secret Key.
|
||||
|
||||
### Restarting the Server
|
||||
```bash
|
||||
# 1. Clean build
|
||||
npm run build
|
||||
|
||||
# 2. Start production server
|
||||
npm run start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Troubleshooting & FAQs
|
||||
|
||||
### Q: Why do I see "Human verification confirmed" even without setting keys?
|
||||
**A:** In development mode (`NODE_ENV !== 'production'`), if no keys are provided, the widget defaults to Cloudflare's official `Always Passes` test key so developers and testers can use the app offline or before creating a Cloudflare account.
|
||||
|
||||
### Q: What if a user has JavaScript disabled or an aggressive ad-blocker?
|
||||
**A:** Cloudflare Turnstile is served from `challenges.cloudflare.com`, which is whitelisted on standard ad-blockers as a privacy-respecting CAPTCHA alternative. If a network error prevents loading, `/api/try/[toolId]` returns a friendly `retryable: true` message instructing the user to refresh.
|
||||
|
||||
### Q: Can Turnstile tokens be reused?
|
||||
**A:** No. Cloudflare Turnstile tokens are single-use and expire within 300 seconds. After each tool execution, the React widget automatically resets to obtain a fresh token for subsequent runs.
|
||||
|
||||
Reference in New Issue
Block a user