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