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
- Overview & What Changed
- Quick Activation (2 Minutes)
- Environment Configuration
- Testing Locally (Zero-Setup Test Keys)
- Technical Architecture & Verification Flow
- Production Deployment Guide
- 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.tstests/auth.test.tsFIREBASE_SETUP.mdfirebaseandfirebase-admindependencies removed frompackage.json
Files Added / Updated (Cloudflare Turnstile):
src/lib/turnstile.ts: Server-side token validation againsthttps://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: Validatescf-turnstile-responsetoken before executing GPU neural pipelines.src/components/tools/DynamicToolWorkspace.tsx: Turnstile widget embedded right above the Process button with automatic token attachment toFormData.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
- Navigate to the Cloudflare Dashboard.
- Log in with your Cloudflare account (or create a free account).
Step 2: Create a Turnstile Widget
- In the left navigation menu, expand Application Services and click Turnstile.
- Click Add widget (or Add site).
- 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.inoryourdomain.com). - Any preview / staging domains (e.g.
*.vercel.appor*.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.
- Widget name:
- 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_KEYis 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 │
└────────────────────────────────────────────────────────┘
- Gatekeeper Enforcement: All client requests target
/api/try/[toolId]. If the incoming request lacks a valid Cloudflare Turnstile token, Next.js rejects it immediately with403 Forbidden(BOT_VERIFICATION_FAILED). No network packets are sent to the actual backend. - Zero Client Secret Leakage: The backend's real URLs (
https://apigp0006.creinnovations.inor 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. - Backend-Side Defense: The actual backend server enforces
FirebaseAppCheckMiddleware/secretKeyverification on all incoming requests. Any direct request sent to the backend server bypassing the Next.js proxy will lack the secret key and receive401 Unauthorized(The provided secret key is invalid.).