diff --git a/docs/adr/0001-proxy-client-lichnyj-instrument.md b/docs/adr/0001-proxy-client-lichnyj-instrument.md new file mode 100644 index 0000000..fd8f9d8 --- /dev/null +++ b/docs/adr/0001-proxy-client-lichnyj-instrument.md @@ -0,0 +1,38 @@ +# 0001. proxy-client — личный инструмент: простота важнее защиты + +Дата: 2026-09-28. Статус: принято. + +## Контекст + +`proxy-client` пользуются владелец и несколько друзей на своих машинах. Первая +версия защищалась от сценариев, которые на личной машине не случаются: +повторное использование PID между `start` и `stop`, подложный `state.json`, +zip-бомба в официальном архиве Xray, уже проверенном по SHA-256, гонка +`status` с параллельным `start`. Эта защита стоила сотен строк кода и тестов и +около минуты прогона. При этом она мешала в обычной жизни, например +отказывала, если `~/.local` сделан ссылкой. + +## Решение + +Защищаемся только от реальных ошибок и опасностей: + +- проверка SHA-256 скачанного Xray и атомарная замена бинарника; +- секреты профиля не попадают в вывод, служебные файлы закрыты правами 600/700; +- локальный порт Xray слушает только loopback; +- чужие файлы не перезаписываются; +- сигнал уходит только процессу, у которого `/proc/PID/exe` совпадает с + запущенным Xray. + +Не защищаемся от самого пользователя и его собственных файлов. Ошибка должна +быть понятной: называть файл полным путём и подсказывать готовую команду. + +Тесты проверяют поведение только через команду `proxy-client`, разбор ссылки, +установку Xray с подставным скачивателем, функции Bash и установщик пакета. Их +не пишут на внутренние функции и порядок вызовов. + +## Последствия + +Прежде чем добавлять новую защиту, нужно назвать сценарий, который реально +случается у пользователя. Иначе защита не добавляется. Первоначальный замысел +с полным набором защит описан в `docs/specs/2026-07-15-proxy-client-design.md` +и в части защит больше не действует. diff --git a/docs/specs/2026-07-15-proxy-client-design.md b/docs/specs/2026-07-15-proxy-client-design.md index e4b3a4a..8aa8152 100644 --- a/docs/specs/2026-07-15-proxy-client-design.md +++ b/docs/specs/2026-07-15-proxy-client-design.md @@ -5,6 +5,10 @@ Статус: основная реализация принята вручную; самостоятельный установщик спроектирован 2026-07-21, но ещё не реализован +> 2026-09-28: часть защит отсюда снята как избыточная для личного инструмента, +> см. [ADR 0001](../adr/0001-proxy-client-lichnyj-instrument.md). При +> расхождении действует ADR. + ## Проблема На удалённых Linux-серверах нет GUI-клиента Hiddify. Перед запуском Claude Code