Защита backend
В документации v2 обозначает версию API Kontur 4.0. Внешний сайт можно подключить по заявке.
Браузерный скрипт готовит пропуск. Серверный модуль @kontur/server проверяет его перед вашим обработчиком и ограничивает расход ресурсов на защищённом маршруте. Прямой HTTP-запрос проходит через ту же границу.
| Граница | Поведение |
|---|---|
| Нагрузка | Общая квота маршрута и квота клиента в PostgreSQL; 429 с Retry-After |
| IPv6 | Одна квота на /64; смена адреса внутри подсети её не обнуляет |
| Размер и время | До 32 КБ тела и 5 секунд чтения; JSON глубиной до 20 |
| Одновременные запросы | До 32 на экземпляр guard; при перегрузке 503 до verify |
| Серверная проверка | HTTPS, запрет редиректов, до 3 секунд на весь ответ; точные action, hostname и context |
| Повтор пропуска | 409 до обработчика; кэшированный success не запускает действие повторно |
| Отказ зависимости | Ошибка БД, сети или формата ответа закрывает доступ к обработчику |
Подключение к серверу
Пакет находится в репозитории и пока не опубликован в npm. Соберите его, создайте архив командой npm pack --workspace @kontur/server и установите архив в серверный проект. Подробный пример и SQL миграции находятся в packages/kontur-server/README.md.
// app/api/signup/route.ts, Node.js 22+
// kontur — общий серверный экземпляр с секретом, hostname,
// PostgreSQL store и resolver адреса доверенного прокси.
import { kontur } from '@/lib/kontur';
export const runtime = 'nodejs';
export const POST = kontur.protect({
routeId: 'signup', action: 'signup',
limit: { perClient: 10, total: 300, windowMs: 60_000 },
parse(body) {
if (typeof body.email !== 'string' || body.email.length > 254)
throw new Error('invalid-email');
return { email: body.email.trim() };
},
}, async (_request, { operationId }) => {
// Здесь — проверка прав и ваша бизнес-транзакция.
return Response.json({ accepted: true, operationId });
});Одно действие задаётся сервером и совпадает с data-action виджета. Все реплики используют один store и одинаковые настройки. Адрес посетителя берётся из сокета или от явно доверенного прокси, который перезаписывает заголовки; модуль не доверяет X-Forwarded-For самостоятельно. Таблица хранит HMAC-ключи квот без адресов и полей формы.
При ответе с challenge передайте его в kontur.challenge(data.challenge) клиента. При 409 получите новую проверку. JSON и обычные URL encoded формы поддерживаются; загрузки файлов требуют отдельного маршрута.
Что подтверждено
На изолированном PostgreSQL-стенде два экземпляра guard и два HTTP API получают 16 конкурентных копий одного пропуска: бизнес-обработчик запускается один раз. Проверены общие квоты между процессами, отказ БД, повторы, подмена привязок, ограничения тела и времени.
Границы защиты сервера
Оборачивайте каждый нужный маршрут. Аутентификация, права на данные, параметризованный SQL и транзакционная уникальность бизнес-операции остаются обязательными. Новый пропуск означает новую операцию; для письма или платежа нужна собственная дедупликация. Ограничения reverse proxy, время запросов БД и внешних сервисов настраиваются отдельно. Для долгого стрима нужен отдельный лимит: слот guard освобождается при возврате Response.
Модуль не защищает операционную систему от захвата и не останавливает объёмный DDoS до сервера. Для этого нужны изоляция процесса, обновления, закрытые порты, резервные копии и защита на стороне инфраструктуры.