Cloudflare Turnstile Integration

TTS Arena supports Cloudflare Turnstile for bot protection. This guide explains how to set up and configure Turnstile for your deployment.

What is Cloudflare Turnstile?

Cloudflare Turnstile is a CAPTCHA alternative that provides protection against bots and malicious traffic while maintaining a user-friendly experience. Unlike traditional CAPTCHAs, Turnstile uses a variety of signals to detect bots without forcing legitimate users to solve frustrating puzzles.

Setup Instructions

1. Register for Cloudflare Turnstile

Create a Cloudflare account or log in to your existing account
Go to the Turnstile dashboard
Click "Add Site" and follow the instructions
Create a new site key
- Choose "Managed" or "Invisible" mode (Managed is recommended for better balance of security and user experience)
- Set an appropriate domain policy
- Create the site key

Once created, you'll receive a Site Key (public) and Secret Key (private).

2. Configure Environment Variables

Add the following environment variables to your deployment:

TURNSTILE_ENABLED=true
TURNSTILE_SITE_KEY=your_site_key_here
TURNSTILE_SECRET_KEY=your_secret_key_here
TURNSTILE_TIMEOUT_HOURS=24

Variable	Description
`TURNSTILE_ENABLED`	Set to `true` to enable Turnstile protection
`TURNSTILE_SITE_KEY`	Your Cloudflare Turnstile site key
`TURNSTILE_SECRET_KEY`	Your Cloudflare Turnstile secret key
`TURNSTILE_TIMEOUT_HOURS`	How often users need to verify (default: 24 hours)

3. Implementation Details

When Turnstile is enabled:

All routes and API endpoints require Turnstile verification
Users are redirected to a verification page when they first visit
Verification status is stored in the session
Re-verification is required after the timeout period
API requests receive a 403 error if not verified

Customization

The Turnstile verification page uses the same styling as the main application, providing a seamless user experience. You can customize the appearance by modifying templates/turnstile.html.

Troubleshooting

Verification Loops: If users get stuck in verification loops, check that cookies are being properly stored (ensure proper cookie settings and no browser extensions blocking cookies)
API Errors: If API clients receive 403 errors, they need to implement Turnstile verification
Missing Environment Variables: Ensure all required environment variables are set correctly