TURNSTILE.md

# 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

1. Create a Cloudflare account or log in to your existing account
2. Go to the [Turnstile dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
3. Click "Add Site" and follow the instructions
4. 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