KryaCaptcha (КряКапча) — это продвинутый антибот-модуль и саркастичное испытание в стиле World's Hardest CAPTCHA на русском языке. Поддерживает встраивание в HTML-формы через JS SDK (kryacaptcha.js) и серверную валидацию через REST API.

1. Встраиваемый JavaScript SDK (kryacaptcha.js)

Добавьте скрипт в разметку вашей страницы и укажите контейнер:

<!-- 1. Подключение скрипта -->
<script src="http://localhost:3000/sdk/kryacaptcha.js"></script>

<!-- 2. Контейнер капчи внутри вашей формы -->
<form action="/login" method="POST">
  <input type="text" name="username" placeholder="Логин" />
  <input type="password" name="password" placeholder="Пароль" />
  
  <div id="captcha-box"></div>

  <button type="submit">Войти</button>
</form>

<!-- 3. Инициализация виджета -->
<script>
  const widget = KryaCaptcha.render('#captcha-box', {
    mode: 'rounds', // 'rounds' или 'endless'
    targetRounds: 3, // количество раундов до победы
    onSuccess: function(token) {
      console.log('Пользователь доказал человечность! Токен:', token);
    },
    onFail: function(stats) {
      console.log('Капча провалена:', stats);
    }
  });
</script>

При успешном прохождении скрипт автоматически заполняет скрытое поле <input type="hidden" name="hardcaptcha-token" /> внутри формы.

2. Серверная проверка токена (Server-Side Validation)

После отправки формы ваш бэкенд проверяет полученный токен через эндпоинт /api/v1/siteverify (совместимо со стандартом Cloudflare Turnstile и Google reCAPTCHA).

POST /api/v1/siteverify

Параметр	Тип	Описание
token	string (обязательный)	Подписанный HMAC токен из поля формы hardcaptcha-token.
secret	string (опционально)	Секретный ключ (по умолчанию берётся из окружения сервера).

Пример ответа сервера:

{
  "success": true,
  "score": 1.0,
  "rounds_completed": 3,
  "mode": "rounds",
  "challenge_ts": "2026-09-03T20:15:30.123Z",
  "action": "hardcaptcha_verify"
}

Пример проверки на Node.js / Express:

app.post('/login', async (req, res) => {
  const token = req.body['hardcaptcha-token'];

  const verifyRes = await fetch('http://localhost:3000/api/v1/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token })
  });
  const data = await verifyRes.json();

  if (data.success) {
    res.send('Успешный вход! Человечность подтверждена.');
  } else {
    res.status(403).send('Ошибка капчи: роботам вход воспрещен.');
  }
});

Пример проверки на Python (FastAPI / Requests):

import requests

def verify_kryacaptcha(token: str) -> bool:
    resp = requests.post(
        "http://localhost:3000/api/v1/siteverify",
        json={"token": token}
    )
    result = resp.json()
    return result.get("success", False)

3. REST API для управления сессиями

POST /api/v1/session/new

Создаёт новую сессию капчи.

curl -X POST http://localhost:3000/api/v1/session/new \
  -H "Content-Type: application/json" \
  -d '{"mode": "endless"}'

GET /api/v1/session/:sessionId/challenge

Возвращает текущую активную задачу (поддерживает ?forceType=chess для тестирования конкретной головоломки).

POST /api/v1/session/:sessionId/verify

Отправляет ответ пользователя на проверку движку сессии.