dotfiles/docs/adr/0001-proxy-client-lichnyj-instrument.md

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 и в части защит больше не действует.