Captcha v2 для встраивания на сайт

Captcha v2 для встраивания на сайт
================================

Цель: невидимая каптча при первом прохождении, при необходимости — проверка
в модальном окне, без вставки лишних блоков в разметку формы.

Онлайн: этот текст доступен на публичной странице сервиса по пути
`/docs/v2-flow` (или откройте раздел «Обзор» по `/docs`).

Привязка к сайту
----------------
В личном кабинете задаётся домен. Запросы из браузера к API капчи должны
идти с Origin/Referer, чей хост совпадает с доменом или является поддоменом.

Быстрый старт (HTML)
--------------------
1. URL точки входа API — файл `api.php` капчи. Публичный лоадер доступен
по адресу `/assets/captcha-v2.js`.

2. Подключите скрипт **после** разметки формы (или с атрибутом `defer`),
чтобы в момент выполнения скрипта форма уже была в DOM:

3. На `<form>` обязательно:

- `data-site-key="ck_pub_…"` — публичный ключ из ЛК;
- `data-captcha-guard="v2"` — без этого скрипт форму не привязывает.

Опционально: `data-field-message="message"` — имя поля с текстом письма
(по умолчанию ищутся имена: message, body, text, comment).

Пример полей, которые читает загрузчик: `name` / `fio` / `fullname`,
`phone` / `tel` / `telephone`, текст — по `data-field-message` или
перечисленные выше имена.

4. При успешной проверке скрипт сам отправит форму с одним из скрытых
полей:
- `captcha_invisible_pass` — невидимая отправка;
- `captcha_attestation` — после решения модалки step-up (challenge).

Сервер сайта
------------
- Принять POST формы.
- **Проще всего (PHP):** один запрос `POST https://s.go-up.info/api.php/v2/verify-submission`
с заголовком `Authorization: Bearer cs_sec_…` и JSON-телом:
`invisible_pass`, `attestation`, `captcha_service_unavailable`, `user_ip` (IP посетителя),
`verify_fail_open` (bool), опционально дублируйте секрет полем `secret` (тот же `cs_sec_…`) —
на части PHP/хостингов исходящий `file_get_contents` не передаёт `Authorization`. Ответ: `valid: true/false`.
См. `examples/server_verify.php`.
- Если есть `captcha_invisible_pass` — вызвать
`POST …/api.php/v2/verify-invisible` с секретом сайта
(`Authorization: Bearer cs_sec_…`) и телом JSON:
`{ "invisible_pass": "<значение из формы>", "user_ip": "<IP клиента>" }`.
IP — тот же, что видит ваш веб-сервер для этого запроса (за прокси —
первый адрес из `X-Forwarded-For` или эквивалент).
- Если пришёл `captcha_attestation` (после step-up) — проверить подпись на сервере:
`POST …/api.php/v1/verify` с секретом и телом `{"attestation":"…"}`
(см. примеры в `examples/server_verify.*`).
- Если пришло только `captcha_service_unavailable=1` (без токенов) — сервис
капчи был недоступен в браузере; при необходимости примите заявку при
`CAPTCHA_VERIFY_FAIL_OPEN=1` или отложите в модерацию.

Примеры PHP и Python — в `examples/server_verify.php` и
`examples/server_verify.py`. MODX — `modx/INSTALL.txt` и сниппет
`snippet.CaptchaVerify.php` (один POST на `/v2/verify-submission`).

Клиент (кратко)
---------------
Скрипт `captcha-v2.js` создаёт сессию в cookie, перед отправкой запрашивает
политику и вызывает `/v2/decide`; при необходимости показывает модалку
с короткой задачей и подставляет скрытые поля. Повторные отправки с одной
сессии браузера могут потребовать прохождения модалки; при отказе сервис
возвращает понятное сообщение пользователю — обрабатывайте ответ формы
на своём бэкенде как обычно.

Если в тексте сообщения есть ссылка, step-up запрашивается сразу уже на
первой попытке. Это не означает авто-блок IP: ссылка только усиливает
проверку конкретной отправки.
Если в тексте сообщения есть ссылка, step-up может появиться уже на первой
попытке отправки — это штатная эвристика и она не заносит IP в blacklist сама по себе.

Политика fail-open на **вашем** сайте
--------------------------------------
- В примерах `examples/server_verify.php` и `server_verify.py` в начале файла
задаётся `$CAPTCHA_VERIFY_FAIL_OPEN` / `CAPTCHA_VERIFY_FAIL_OPEN` (`0` или `1`):
при сетевой ошибке verify или при `captcha_service_unavailable=1` без токенов
считать проверку пройденной. В своём коде можно вынести то же значение в
конфиг или переменные окружения. Согласуйте с разделом «Правила» в ЛК.