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

58 lines
3.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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-ноде.