turnstile-spin

turnstile-spin — официальный навык Cloudflare для сквозной настройки Turnstile: проверки доступа, анализа проекта, создания или выбора виджета, встраивания его в выбранные пользовательские поверхности, серверной проверки через siteverify и последующей валидации. Он предназначен для защиты форм, endpoint-ов, кнопок, загрузок, комментариев и других действий от ботов. Навык работает вокруг уже существующего backend handler и добавляет проверку перед его текущей логикой; он не строит новый backend, прокси, базу данных или отдельную инфраструктуру. Сначала определяется режим: создание нового виджета или работа с уже существующим sitekey. Для нового виджета проверяются авторизация Cloudflare, аккаунт, домен, frontend framework, backend handler и наличие другого CAPTCHA. В список доменов для локальной разработки входят localhost и 127.0.0.1, а production-hostname проверяется отдельно; локальные домены нельзя включать в production allowlist backend. Перед необратимыми действиями workflow требует подтверждения пользователя, а для существующего виджета дополнительно требует явно подтвердить write manifest до получения секрета. Frontend-часть подключает официальный скрипт Turnstile, размещает cf-turnstile с sitekey и стабильным data-action на выбранной поверхности и сохраняет существующую форму или запрос. Backend читает cf-turnstile-response и вызывает https://challenges.cloudflare.com/turnstile/v0/siteverify. Принятие разрешается только при success === true, ожидаемом action и hostname из deployment-specific allowlist; пустой или слишком длинный токен, отсутствие hostname-конфигурации, сетевой сбой, не-2xx ответ или невалидный JSON обрабатываются fail-closed. Секрет хранится в существующем env или secret manager и не должен попадать в аргументы команд, логи, diff или чат. Токены Turnstile одноразовые. Для обычной формы с переходом страницы дополнительный reset не нужен; для SPA, которая остаётся на той же странице, после попытки нужно сбросить конкретный widget ID через window.turnstile.reset(widgetId) и разрешить новую попытку только после завершения запроса. При миграции с reCAPTCHA или hCaptcha меняются скрипт, класс виджета, поле токена и endpoint siteverify; v3 score threshold не переносится, потому что Turnstile использует success, а Enterprise migration не выполняется автоматически. Валидация не ограничивается тем, что виджет отрендерился: навык предлагает проверить секрет dummy-запросом, затем протестировать реальный защищённый backend свежим токеном и отдельно убедиться, что повторное использование токена отклоняется. Если backend нельзя запустить, destination validation остаётся pending и успех не объявляется. Такой подход отделяет наличие UI от фактической серверной защиты и сохраняет ответственность существующего handler за отправку формы, письмо, persistence и другие операции. Границы применения строгие: siteverify нельзя вызывать из браузера, секрет нельзя просить вставить в чат, проектный npx или случайный локальный Wrangler нельзя использовать для secret-bearing операций, а дополнительные Cloudflare Workers и sidecars не создаются. Навык полезен для signup, login, contact, download и API-защиты, но требует реального backend места для проверки. Он не является аудитом всей безопасности, не настраивает WAF и не заменяет проверку hostname, action, token lifecycle и логики самого handler после успешной валидации.