From d37f3c0a5b90552e5700c1a9250c287548a55832 Mon Sep 17 00:00:00 2001 From: vshnosngh Date: Fri, 13 Nov 2026 18:17:10 +0530 Subject: [PATCH] docs: expand Cloudflare Turnstile setup guide with complete activation steps, testing keys, and architecture --- CLOUDFLARE_TURNSTILE_SETUP.md | 185 ++++++++++++++++++++++++---------- 1 file changed, 130 insertions(+), 55 deletions(-) diff --git a/CLOUDFLARE_TURNSTILE_SETUP.md b/CLOUDFLARE_TURNSTILE_SETUP.md index 2b6fd26..762cb91 100644 --- a/CLOUDFLARE_TURNSTILE_SETUP.md +++ b/CLOUDFLARE_TURNSTILE_SETUP.md @@ -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 ``. + +--- + +## 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 `` 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.