feat: add declarative sing-box egress control plane

README.md

@@ -0,0 +1,81 @@
+# singbox_glue / vpn-egressctl
+
+`vpn-egressctl` — локальный декларативный control plane для шлюза `vpn-egress-gw`.
+Он получает реквизиты подключения из защищённого Hysteria2 URI, объединяет их с
+локальной инфраструктурной политикой и полностью генерирует конфигурацию
+sing-box.
+
+Проект намеренно поддерживает только **sing-box 1.13.19**. Версии 1.13.12,
+другие patch-релизы и вся ветка 1.14 отклоняются до изменения файлов.
+
+## Что решает проект
+
+- IP Hysteria2-сервера отсутствует в `route_exclude_address` и nftables policy.
+- Смена DNS A-записи не требует перегенерации конфигурации.
+- Смена credential выполняется одной безопасной командой через stdin.
+- Перед установкой candidate проверяется реальным `sing-box check`.
+- Запись атомарна; после неуспешного restart/healthcheck выполняется rollback.
+- URI, production config, state и backups имеют режим `0600`.
+- Неизвестные URI/policy-параметры отклоняются, а не игнорируются.
+- systemd следит за desired state без постоянно работающего Python-процесса.
+- Отдельный nftables guard блокирует прямой forwarding `eth1 -> eth0`.
+
+## Источники состояния
+
+```text
+/etc/vpn-egress/policy.json
+/etc/vpn-egress/hysteria2.uri
+             │
+             ▼
+      renderer 1.13.19
+             │
+             ▼
+/etc/sing-box/config.json
+```
+
+`/etc/sing-box/config.json` является генерируемым артефактом. Редактировать его
+вручную после миграции нельзя.
+
+## Основные команды
+
+```bash
+# URI не попадает в argv и shell history.
+sudo vpn-egressctl import --stdin
+
+sudo vpn-egressctl check
+sudo vpn-egressctl diff
+sudo vpn-egressctl sync
+sudo vpn-egressctl status
+sudo vpn-egressctl doctor
+sudo vpn-egressctl rollback
+```
+
+Позиционный `vpn-egressctl import 'hysteria2://...'` запрещён специально.
+
+## Документация
+
+- [Архитектура](docs/architecture.md)
+- [Конфигурация](docs/configuration.md)
+- [Установка и миграция](docs/migration.md)
+- [Эксплуатация](docs/operations.md)
+- [Безопасность](docs/security.md)
+- [Диагностика](docs/troubleshooting.md)
+- [Тестирование](docs/testing.md)
+- [Почему не поддерживается 1.14](docs/sing-box-1.14.md)
+
+## Локальная проверка
+
+Проект не имеет runtime-зависимостей вне Python stdlib.
+
+```powershell
+E:\python-31312\python.exe -m compileall -q src tests
+```
+
+Изолированная Windows-сборка Python в указанном каталоге не добавляет cwd в
+`sys.path`, поэтому полный тестовый запуск выполняется так:
+
+```powershell
+E:\python-31312\python.exe -c "import sys,unittest; sys.path[:0]=[r'F:\projects\singbox_glue\src',r'F:\projects\singbox_glue']; s=unittest.defaultTestLoader.discover(r'F:\projects\singbox_glue\tests'); r=unittest.TextTestRunner(verbosity=2).run(s); raise SystemExit(not r.wasSuccessful())"
+```
+
+На Linux достаточно `make check`.