From 502f828c6f5105ccc500576999ba70175981c089 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Mon, 28 Sep 2026 09:23:13 -0400 Subject: [PATCH] =?UTF-8?q?docs(proxy-client):=20=D0=BF=D1=80=D0=B8=D0=BD?= =?UTF-8?q?=D1=86=D0=B8=D0=BF=20=D0=BF=D1=80=D0=BE=D1=81=D1=82=D0=BE=D1=82?= =?UTF-8?q?=D1=8B=20=E2=80=94=20=D0=B2=20=D1=81=D0=BF=D0=B5=D1=86=D0=B8?= =?UTF-8?q?=D1=84=D0=B8=D0=BA=D0=B0=D1=86=D0=B8=D1=8E=20=D0=B2=D0=BC=D0=B5?= =?UTF-8?q?=D1=81=D1=82=D0=BE=20ADR?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Отдельный ADR дублировал спецификацию и оставлял в ней устаревшие места. 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 | 31 ++++++++++++--- 2 files changed, 26 insertions(+), 43 deletions(-) delete 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 deleted file mode 100644 index fd8f9d8..0000000 --- a/docs/adr/0001-proxy-client-lichnyj-instrument.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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 8aa8152..6a06f3c 100644 --- a/docs/specs/2026-07-15-proxy-client-design.md +++ b/docs/specs/2026-07-15-proxy-client-design.md @@ -2,12 +2,33 @@ Дата: 2026-07-15 -Статус: основная реализация принята вручную; самостоятельный установщик -спроектирован 2026-07-21, но ещё не реализован +Статус: реализовано; 2026-09-28 упрощено по принципу ниже -> 2026-09-28: часть защит отсюда снята как избыточная для личного инструмента, -> см. [ADR 0001](../adr/0001-proxy-client-lichnyj-instrument.md). При -> расхождении действует ADR. +## Принцип: личный инструмент + +`proxy-client` пользуются владелец и несколько друзей на своих машинах. Код +защищается от реальных ошибок и опасностей: + +- скачанный Xray проверяется по SHA-256 и заменяется атомарно; +- секреты профиля не попадают в вывод, служебные файлы закрыты правами 600/700; +- локальный порт Xray слушает только loopback; +- чужие файлы не перезаписываются; +- сигнал уходит только процессу, у которого `/proc/PID/exe` совпадает с + запущенным Xray. + +Пользователь и его собственные файлы — не противник. Сообщение об ошибке +называет файл полным путём и подсказывает готовую команду. + +Новая защита появляется вместе со сценарием, который реально случается у +пользователя, и этот сценарий записывается рядом с ней. Так же проверяется и +прежний код: в 2026-09-28 убраны защиты без такого сценария — повторное +использование PID, подложный `state.json`, zip-бомба в проверенном архиве, +гонка `status` с параллельным `start`. + +Тесты проверяют поведение через команду `proxy-client`, разбор ссылки +(`parse_vless` + `build_xray_config`), установку Xray с подставным +скачивателем, функции Bash с поддельным `PROXY_CLIENT_BIN` и установщик пакета +во временном HOME. ## Проблема