From 05a7f1e4fbe133a0b99f1be231a41bee0b20bcf6 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 28 Sep 2026 09:22:28 -0400 Subject: [PATCH] =?UTF-8?q?docs(adr):=20proxy-client=20=E2=80=94=20=D0=BB?= =?UTF-8?q?=D0=B8=D1=87=D0=BD=D1=8B=D0=B9=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BC=D0=B5=D0=BD=D1=82,=20=D0=BF=D1=80=D0=BE=D1=81?= =?UTF-8?q?=D1=82=D0=BE=D1=82=D0=B0=20=D0=B2=D0=B0=D0=B6=D0=BD=D0=B5=D0=B5?= =?UTF-8?q?=20=D0=B7=D0=B0=D1=89=D0=B8=D1=82=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 (1M context) --- .../0001-proxy-client-lichnyj-instrument.md | 38 +++++++++++++++++++ docs/specs/2026-07-15-proxy-client-design.md | 4 ++ 2 files changed, 42 insertions(+) create mode 100644 docs/adr/0001-proxy-client-lichnyj-instrument.md 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