guard/docs/roadmap/v0.5-rst-challenge-ga.md
loki5512344 280284667f
docs: per-task roadmap, architecture and changelog
- Split TODO into a thin status index plus docs/roadmap/ with one file per
  task (v0.4 reliability, v0.5 product, v0.6 research, icebox).
- Add docs/architecture.md (current processes, packet/data path, layers,
  storage, metrics) and docs/development.md (rules, gates, DoD).
- Add CHANGELOG.md reconstructed from history; move round details out of
  TODO.
- Align docs with the code: config defaults and missing [detect]/
  [protocol.http] sections, XDP metric names, ClickHouse table and TTL,
  Redis RDB restore, multiarch clang include, CLI binary name.
- Add scripts/check_docs_links.sh and run it in CI.
- release profile: thin LTO + one codegen unit. Binary 12.3 MB -> 9.7 MB,
  http parser bench 314 ns -> 278 ns; panic=abort stays off for
  catch_unwind in the Redis subscriber.
- Drop the unused JWT role claim; fix 'rampart doctor' hints in the CLI.
2026-11-16 14:51:50 +01:00

3.1 KiB
Raw Blame History

v0.5 — RST-challenge: довести до GA

Milestone v0.5
Status planned
Priority P0
Depends on v0.4-xdp-ci-harness (регрессии на реальном ядре)

Цель

RST-challenge (Oubliette-style liveness proof) работает для IPv4 и IPv6, включён документированным способом и заменяет текстовый PoW там, где PoW несовместим с протоколом.

Зачем

В коде уже есть xdp/core/syn_challenge.h и [xdp] syn_challenge_enabled (IPv4, SYN-ACK с неверным ACK → RST от живого клиента → verified). Это универсальная проверка liveness, совместимая с любым TCP-клиентом, в отличие от userspace PoW, который ломает протоколы с собственным handshake (Minecraft). Осталось довести до продакшена и убрать расхождение «фича есть в C, но не в документации/дефолтах».

Scope

  • IPv6-паритет: 128-битные flow-ключи для pending-challenge и verified-состояния.
  • Метрики: выданные challenge, прошедшие/просроченные, доля verified-источников.
  • Заменить/дополнить PoW: описать матрицу «протокол → PoW / RST-challenge / оба», обновить [pow] и [xdp] в configuration.md.
  • Интеграционные тесты: живой клиент проходит, спуф не проходит; TTL challenge.
  • Docs: отдельный раздел про challenge в architecture.md и runbook.

Non-goals

  • RST-challenge для UDP.
  • Хранение verified-состояния в Redis между нодами (сейчас локально в XDP).

Approach

  1. Аудит текущего C-кода и ABI: ключи, таймауты, взаимодействие с conntrack.
  2. v6: расширить flow_key или добавить flow_key6; проверить размер карт.
  3. Userspace: метрики и переключатель; логировать причину отказа без секретов.
  4. Тесты: tests/xdp_ban_keys.rs рядом, scripts/xdp_ci.sh из v0.4.
  5. Документация и дефолты: решение «включать по умолчанию» принимается только после нагрузочного стенда.

Критерии приёмки

  • IPv4 и IPv6: живой клиент проходит после одного RST, спуф — нет.
  • Метрики challenge видны в /metrics и описаны в docs.
  • Нет дефолтного секрета: placeholder отклоняется при старте (уже есть).
  • PoW и RST-challenge не включаются одновременно для Minecraft.

Верификация

scripts/xdp_ci.sh + e2e-тест в tests/edge_e2e.rs; ручная проверка tcpdump на dev-ноде.