# Cloudflare Turnstile Integration & Activation Guide 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. --- ## 📋 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) --- ## 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. 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, expand **Application Services** and click **Turnstile**. 2. Click **Add widget** (or **Add site**). 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**: - **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 displays two API keys on the completion screen: - **Site Key** (Public): Starts with `0x4AAAAAA...` - **Secret Key** (Private): Starts with `0x4AAAAAA...` --- ## 3. Environment Configuration ### Local Environment (`.env.local`) Create or edit `.env.local` in the project root: ```env # --------------------------------------------------------------------------- # 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 ``` > [!NOTE] > 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. --- ## 4. Testing Locally (Zero-Setup Test Keys) 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.