Files
webb/CLOUDFLARE_TURNSTILE_SETUP.md

10 KiB

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
  2. Quick Activation (2 Minutes)
  3. Environment Configuration
  4. Testing Locally (Zero-Setup Test Keys)
  5. Technical Architecture & Verification Flow
  6. Production Deployment Guide
  7. 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 <AuthProvider>.

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.
  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:

# ---------------------------------------------------------------------------
# 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

# 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.


8. Direct Backend Server Protection Architecture

To ensure no one can send requests to the actual backend server on its own, the system employs a two-tier zero-trust defense:

[ External Client / Bot / Scraper ]
              │
              │  (A) Attempt direct curl/script to /api/try/* without Turnstile token
              ▼
   ┌────────────────────────────────────────────────────────┐
   │ Next.js Proxy Server (/api/try/[toolId])               │
   │ 1. Validate 'cf-turnstile-response' / 'x-turnstile'     │
   │ 2. Missing/Invalid Token -> HTTP 403 FORBIDDEN         │
   │    Zero network traffic dispatched to backend          │
   └────────────────────────────────────────────────────────┘
              │
              │  (B) Valid Turnstile Token Verified with Cloudflare API
              ▼
   ┌────────────────────────────────────────────────────────┐
   │ Next.js Server-Side Request Builder                    │
   │ - Injects internal API_SECRET_DEFAULT (e.g. 'abcdef')  │
   │ - Backend URLs & secrets NEVER reach the browser       │
   └────────────────────────────────────────────────────────┘
              │
              │  (C) Proxied Server-to-Server Request with Secret
              ▼
   ┌────────────────────────────────────────────────────────┐
   │ Actual FastAPI Backend (GPU Inference Servers)         │
   │ - Validates internal secretKey in middleware           │
   │ - Direct requests without secret -> HTTP 401           │
   └────────────────────────────────────────────────────────┘
  1. Gatekeeper Enforcement: All client requests target /api/try/[toolId]. If the incoming request lacks a valid Cloudflare Turnstile token, Next.js rejects it immediately with 403 Forbidden (BOT_VERIFICATION_FAILED). No network packets are sent to the actual backend.
  2. Zero Client Secret Leakage: The backend's real URLs (https://apigp0006.creinnovations.in or local FastAPI ports) and the backend authentication secret (API_SECRET_DEFAULT) exist exclusively in server-side environment variables. They are never exported into client JavaScript bundles.
  3. Backend-Side Defense: The actual backend server enforces FirebaseAppCheckMiddleware / secretKey verification on all incoming requests. Any direct request sent to the backend server bypassing the Next.js proxy will lack the secret key and receive 401 Unauthorized (The provided secret key is invalid.).