# Капча Cloudflare Turnstile

v0.1 - 2026-11-16

Проверка «не робот» перед формами, которые шлют письма или заводят записи: регистрация, «Забыл пароль?», «Отправить
код ещё раз». Домену не обязательно быть в Cloudflare.

## Завести виджет

Cloudflare → **Turnstile** → Add widget:

- **Hostnames** — все домены, на страницах которых виджет будет рисоваться. Виджет на домене не из списка — «Invalid
  domain».
- **Widget mode** — Managed: Cloudflare сам решает, показывать ли задачу.
- **Site Key** — в браузер (публичный), **Secret Key** — только на сервер, не в git.

Для staging — отдельный виджет или адрес стенда в Hostnames того же.

## Проверка на сервере

Браузер получает от виджета токен и отправляет его с формой (в теле или заголовке). Сервер проверяет токен у
Cloudflare:

```
POST https://challenges.cloudflare.com/turnstile/v0/siteverify
secret=<Secret Key>&response=<токен>&remoteip=<адрес посетителя>
```

- Смотреть `success`, а ещё **`action`**: у каждой формы своё (`signup`, `reset`), и токен от одной формы не подойдёт
  к другой.
- Токен одноразовый и живёт несколько минут: на повтор формы — новый токен.
- `remoteip` — настоящий адрес посетителя; за прокси — из заголовка, только если прокси свой и заменяет его.

**Cloudflare не ответил** (сеть, сбой, таймаут) — решить заранее. Разумно пропустить запрос и записать в лог: чужой
сбой не должен закрыть регистрацию, а от ботов остаются лимиты.

## Разработка и проверки

- Ключи пустые — капчи нет: приложение работает без неё.
- Посмотреть виджет при разработке — тестовые ключи Cloudflare, всегда проходят: Site Key `1x00000000000000000000AA`,
  Secret Key `1x0000000000000000000000000000000AA`. Ключи «всегда не проходит» и другие — в документации Turnstile,
  раздел Testing.
- Автопроверки к Cloudflare не ходят: капчу включает тестовый переключатель, токен — заранее известная строка.

## История

- v0.1 — 2026-11-16: черновик.
