# Изменения HY2XS

Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/).
Проект использует [семантическое версионирование](https://semver.org/lang/ru/).

Версия относится к самому HY2XS, а не к Hysteria: версия Hysteria выбирается
на этапе сборки пакета и фиксируется в его metadata.

## [Unreleased]

Hardening-проход перед релизом `1.0.0`. Основная тема — сделать политику
«только чистая установка» настоящим системным инвариантом, а не строчкой в
документации.

Второй проход закрывает то, что осталось: два контракта приёмки, гарантированно
ронявшие сборку на корректном коде; жизненный цикл планировщика; мёртвое
состояние в таблице `config`; каналы утечки bootstrap-учётных данных; возраст
графа зависимостей.

Третий проход — операции, которые делают не то, что обещает их имя: отзыв
доступа, не переживающий перезапуск; резервная копия, молча получающаяся
неполной; диагностика, обрывающая соединения; аварийный выход сборки, которым
невозможно воспользоваться.

Четвёртый проход — failure path и релизные гейты: восстановление после
неудачной установки, которое умело отменить само себя, два гейта сборки,
проверявшие не то, что обещали, и два свойства, которые были описаны, но не
обеспечены — read-only у `doctor` и различение отказа базы у `reset-admin`.

Пятый проход — нижний слой того же механизма. Верхнеуровневый откат стал
надёжным раньше, чем его storage/firewall substrate: откат гарантированно
запускался, но отдельные его шаги могли молча не выполнить восстановление,
отчитаться успехом и уничтожить резервную копию.

### Исправлено — целостность отката

- **Данные для отката уничтожались до фиксации успеха.** Успешный install
  заканчивался вызовом, который снимал таймер автоотката **и удалял резервные
  копии firewall**, — и стоял этот вызов ДО долговечной записи
  `phase: installed`. Если запись падала (`ENOSPC`, `EIO`, read-only ФС),
  управление уходило в обработчик ошибки, обязательный откат честно запускался
  и сообщал `no HY2XS rollback markers found`. Откат нельзя было отменить, но
  откатывать ему было нечем — причём отказ записи маркера это ровно тот
  сценарий, который был специально сделан безопасным прошлым проходом.

  Операция разделена на `disarmFirewallRollback` (снять таймер, копии
  оставить) и `cleanupFirewallRollback` (удалить копии). Порядок теперь:
  `smoke_ok` → disarm → durable `installed` → cleanup best-effort. То же в
  `reconfigure`.

- **Резервные копии снимались без доказательства.** И firewall, и
  `reconfigure` копировали файлы как `cp ... || true`, поэтому отказ
  копирования игнорировался, а операция начинала менять систему, не имея
  копии, на которую рассчитывает откат. У firewall маркер `prepared`
  («данные для отката существуют») выставлялся вообще до копирования.
  Копирование стало строгим, факт создания проверяется, маркер ставится после.

- **Копии `reconfigure` смешивались между операциями.** Они лежали одним общим
  набором `*.bak` в `/etc/hy2xs/backups`, не привязанным к проходу. Если у
  операции B копирование падало, B всё равно менял систему, а его откат
  восстанавливал файлы, сохранённые операцией A: сервер возвращался не в
  состояние «до B», а в более старое — и это выглядело успешным откатом.
  Копия стала операционной: `/etc/hy2xs/backups/<op-id>/` с манифестом, где
  отсутствие файла — записанный факт (`"present": false`), а не вывод из
  неудачи `cp`. Разбор манифеста строгий, включая проверку `opId`.

- **Ошибка восстановления скрывалась, а копии после неё удалялись.**
  `rollbackFirewallNow` выполняла `cp` и `nft -f` с `|| true`, а затем
  безусловно удаляла `/run/hy2xs/rollback/<op>`. Худшая возможная комбинация:
  неудача восстановления не видна, стадия отчитывается успешной, а данные, по
  которым оператор мог бы поднять firewall вручную, уничтожены. Теперь копии
  удаляются только после подтверждённого успеха, иначе сохраняются с
  сообщением `manual recovery data preserved at …`.

- **Команды отката глушили собственный код возврата.** `systemctl stop`,
  `disable`, `reset-failed`, `cp`, `nft -f`, `daemon-reload`, `restart` — все
  несли `|| true`. До появления стадийного раннера это была единственная защита
  от обрыва цепочки; после его появления — маскировка: стадия физически не
  могла сообщить, что ничего не сделала, и обещание «отказавшие стадии
  перечисляются» для них не выполнялось никогда. `|| true` убран,
  непрерывность обеспечивает раннер, `rollbackCurrentState` разбита на семь
  независимых стадий.

- **Долговечность записи каталога маркера.** `writeTextAtomic` синхронизирует
  файл и каталог, в котором файл лежит, но при первой установке
  `/var/lib/hy2xs` создаётся тут же, и запись «hy2xs» в `/var/lib` оставалась
  несинхронизированной: после потери питания мог исчезнуть весь каталог вместе
  с маркером. `ensureDir` сообщает о фактическом создании и синхронизирует
  родителя только тогда.

### Изменено — свойства, ставшие инвариантами

- **`doctor` read-only по инварианту рантайма, а не по соглашению.**
  Принудительный `skipServiceStart` закрывал ровно одну ИЗВЕСТНУЮ мутацию —
  рестарт сервисов. Всё остальное в `smoke` держалось на том, что автор правки
  выбрал правильный раннер, а читающие команды (`test -s`, `grep -q`, `stat`,
  `sudo -u ... test`, `nft -c`) шли через мутирующий namespace. То есть
  настоящая мутация, случайно добавленная в `smoke`, ничем бы от них не
  отличалась и была бы разрешена в `doctor` молча.

  Эти команды классифицированы честно, ожидание между попытками перестало быть
  подпроцессом `sleep` через мутирующий раннер, а сам `doctor` целиком
  выполняется под тем же read-only guard, что и PHASE 0 установки. Диагностика
  при этом не сузилась.

### Исправлено — `reset-admin`

- **Отказ базы трактовался как «администратора нет».** Слой данных специально
  различает `ErrAdminUserNotFound` и `ErrStorage`, но команда восстановления
  доступа склеивала их обычным `if err != nil { создать } else { обновить }`.
  Опасен здесь не только нарушенный смысл sentinel'ов: при транзиентном отказе
  чтения («database is locked») ветка создания отрабатывала успешно, и в
  таблице оказывались ДВЕ учётные записи администратора. `GetAdminUser` берёт
  `First()` и о второй строке не сообщает — то есть на сервере оставалась
  вторая рабочая учётка с паролем, уже напечатанным на экран, и ни один запрос
  об этом не говорил.

- **Ошибка хеширования пароля проглатывалась.** В ветке обновления стояло
  `hash, _ := util.HashPassword(password)` внутри литерала map. При отказе
  bcrypt в `password_hash` уезжала пустая строка, а на экран печатался пароль,
  которым войти уже невозможно: `VerifyPassword` отклоняет всё, что не является
  bcrypt-хешем. Команда восстановления доступа умела молча его отобрать.

### Исправлено — восстановление после неудачной операции

- **Запись состояния отказа отменяла откат.** Обработчик ошибки в `install` и
  `reconfigure` первым делом писал в `install-state.json` фазу отказа обычным
  `await` и только потом откатывался. Эта запись — `mkdir`, `write` и `chown` в
  `/var/lib/hy2xs`, то есть она падает ровно там, где откат нужнее всего:
  заполненный диск, read-only ФС, ошибка ввода-вывода. Бросок уносил управление
  наружу, и обязательное восстановление не выполнялось вовсе — применённый
  firewall и развёрнутые сервисы оставались на сервере.

  Необязательная телеметрия состояния стояла перед обязательным
  восстановлением. Для сбора диагностики это уже было закрыто прошлым проходом,
  для записи состояния — нет. Теперь запись обёрнута так же: неудача попадает в
  журнал строкой `failed to persist failure state, continuing with the mandatory
  rollback`, а откат продолжается.

- **Откат отменял сам себя.** Он был написан цепочкой `await`, а каждая его
  стадия — `systemctl`, `cp`, `rm -rf` или `nft`, то есть умеет упасть сама.
  Отказ первой стадии отменял все последующие. В `reconfigure` это означало
  сервер одновременно с применённым сломанным firewall **и** без
  восстановленных из `/etc/hy2xs/backups` конфигов — худший сценарий отказа
  лишался обеих половин восстановления сразу.

  Внутри `rollbackCurrentState` болезнь была та же: единственная команда без
  `|| true` (`systemctl daemon-reload`) отменяла перезапуск сервисов строкой
  ниже, и восстановленные unit-файлы так и не применялись.

  Стадии стали независимыми: выполняются все и в объявленном порядке,
  отказавшие перечисляются в журнале, наружу уходит исходная ошибка операции.

- **У маркера установки было два писателя с разными гарантиями.** `install`
  перезаписывал файл на месте, `reconfigure` подставлял атомарно; слабейшая
  гарантия досталась команде, которая этот файл создаёт. Перезапись на месте
  укорачивает файл до нуля и только потом наполняет — отказ между этими
  моментами оставляет половину JSON, которая не разбирается: `reconfigure`
  видит такой маркер как отсутствующий, clean-host — как присутствующий, а хост
  к этому моменту уже изменён.

  Атомарности при этом было бы мало: `rename()` без `fsync` даёт атомарность
  видимости без долговечности, и после потери питания ext4 штатно отдаёт по
  этому пути нулевой файл. Порядок теперь: права и владелец → `fsync` файла →
  `rename` → `fsync` каталога.

- **Ownership-флаг маркера отвечал не на тот вопрос.** Он назывался
  `stateWritten` и взводился ПОСЛЕ успешной записи, хотя запись — это три
  операции. Отказ на `chown` оставлял файл на диске при невзведённом флаге, то
  есть давал классификацию `fatal_pre_apply` — «на сервере ничего не изменено» —
  при уже существующем `/var/lib/hy2xs/install-state.json`, который ломал
  следующую чистую установку. Флаг переименован в `stateTouched` и взводится до
  первой операции записи, как все остальные.

### Изменено — релизные гейты сборки

- **`pnpm audit` проверяет весь lock-граф, а не production-подграф.** Гейт
  запускался с `--prod` под обоснованием «devDependencies в артефакт не
  попадают». Для frontend build tooling это неверно по существу: `vite` и
  `rollup` не копируются на сервер, но исполняются на build-машине и порождают
  тот самый production-бандл. Ровно такой случай и был найден в этом же
  релизном цикле — DOM clobbering в Rollup затрагивал генерируемый бандл, а
  `--prod` его не показывал; по всему графу тот же прогон дал 33 предупреждения
  против нуля. Критерий приёмки №47 в `docs/11` формулировал это правильно ещё
  до того, как стало правдой в коде.

- **Удалён `SKIP_TESTS`.** Переменная была описана как «аварийное отключение
  тестов; для release-сборок недопустимо». Недопустимость держалась
  исключительно на этой фразе: ни metadata, ни финальная приёмка архива не
  проверяли, что тесты запускались, поэтому `SKIP_TESTS=true ./tools/build/build.sh`
  доходила до конца и выдавала обычный tarball с `build_profile=production` и
  `dependency_security_gate=true` — артефакт, по которому невозможно отличить
  проверенную сборку от непроверенной. Глушила она при этом не только тесты, но
  и `tsc --noEmit` с `go vet`.

  Выбран тот же строгий вариант, что и для проверки зависимостей: обхода нет,
  а готовый пакет объявляет `tests_gate=true` в `metadata/package.env`. Поле
  опирается на фактический прогон — `write_metadata` отказывается писать
  метаданные, если хотя бы один из двух прогонов не подтверждён. Для локальной
  работы обходить нечего: `bun test`, `tsc --noEmit`, `go vet` и `go test`
  запускаются напрямую и tarball не создают.

### Исправлено — операции, не выполняющие обещанного

- **Удаление `bootstrap-admin-peer` не было отзывом доступа.** Признаком
  «создавать пир или нет» служило наличие строки в таблице пиров, а
  `HY2XS_ADMIN_CON_PASS` продолжает жить в `/etc/hy2xs/hy2xs.env` — его читает
  systemd-юнит. Поэтому оператор удалял пира, доступ действительно исчезал, а
  ближайший `systemctl restart hy2xs-admin` или перезагрузка сервера возвращали
  того же пира с тем же секретом. Молча: ни строки в журнале, в списке пиров
  запись просто снова есть.

  Признаком стала отметка `BOOTSTRAP_PEER_SEEDED` в таблице `config`: она
  отвечает на вопрос «пир КОГДА-ЛИБО создавался», а не «существует сейчас».
  Отметка и сам пир пишутся одной транзакцией — раздельная запись вернула бы
  прежнее поведение при падении процесса между двумя операциями. Удаление
  осталось разрешённым и стало необратимым; отключение (`Disabled = 1`)
  остаётся вторым, обратимым способом.

- **Резервная копия с секретами могла молча оказаться неполной.**
  `ListExportPeer(true)` проглатывала и ошибку расшифровки, и отсутствие
  шифртекста, отдавая пира с пустым полем `secret` и успешный ответ. Оператор,
  СПЕЦИАЛЬНО выбравший режим «копия с действующими credentials», получал файл,
  выглядящий полным, и узнавал о потере после импорта на новом сервере — по
  отвалившимся клиентам. Теперь недоступный секрет хотя бы одного пира
  отклоняет весь запрос с указанием имени; файл не создаётся. Безопасная
  выгрузка (`includeSecrets=false`) не изменилась.

- **`DecryptPeerSecret` возвращала содержимое колонки как расшифрованный
  секрет,** если оно не начиналось с `v1:`. Ветка досталась от поколения, где
  секреты пиров лежали открытым текстом; при clean-install-only политике такой
  строки существовать не может, а вред оставался: повреждённая колонка уходила
  в клиентскую ссылку и в резервную копию как учётные данные. Формат хранения
  теперь ровно один, всё остальное — ошибка. Тот же класс, что и удалённый
  SHA-224 fallback при входе.

- **`hy2xs-orchestrator doctor` перезапускал оба сервиса.** Команда собирала
  контекст с параметрами по умолчанию и звала общий smoke, который начинается с
  `systemctl restart hysteria-server hy2xs-admin`. То есть диагностика, которую
  runbook предлагает запускать при подозрении на проблему, гарантированно
  обрывала все живые VPN-соединения — включая случай, когда с сервисом всё в
  порядке. Диагностика, меняющая то, что диагностирует, отвечает не на заданный
  вопрос. `doctor` принудительно выставляет `skipServiceStart`; остальные
  проверки smoke выполняются полностью.

- **Админка сама придумывала `HYSTERIA2_TRAFFIC_STATS_SECRET`.** При пустом env
  и пустой базе она генерировала случайный токен, записать который в
  `/etc/hysteria/config.yaml` не может — файл принадлежит оркестратору и
  доступен ей только на чтение. Сервис объявлял себя здоровым, а machine auth
  переставал совпадать, потому что Hysteria продолжала слать прежнее значение.
  Тот же принцип, что уже действует для `HY2XS_ADMIN_INITIAL_PASSWORD`: пустой
  env при пустой базе — отказ старта; уже согласованный токен в базе
  принимается.

- **Обходы проверки зависимостей существовали только на бумаге.**
  Документированные `dependency_security_gate=accepted-risk` и `skipped` не
  могли произвести артефакт: финальная приёмка архива требует буквально `true`,
  поэтому сборка с ними проходила весь цикл и падала на последнем шаге. Продукт
  документировал операцию, которую сам же запрещал. Обе переменные удалены из
  сборки и документации; их отсутствие проверяется приёмкой. Контракт стал
  однозначным: релизный артефакт невозможно собрать с непройденной проверкой.

- **`UPDATE` по отсутствующей строке `config` считался успехом.**
  `updateConfigOn` смотрел только на `tx.Error`, а UPDATE без совпавших строк
  ошибкой SQL не является. Следом `applyRuntimeConfigUpdates` применял значение
  к планировщику, поэтому оператор дважды получал подтверждение изменения,
  которого не произошло, а перезапуск сервиса возвращал прежний cron. Решение
  принимается по `RowsAffected` — как в соседней `UpsertConfigValue`, где эта же
  ошибка уже была разобрана.

- **Слой данных не отличал «записи нет» от «база не ответила».** Каждый `Get*`
  возвращал свежий `errors.New` со строкой, поэтому отказ SQLite был
  неотличим от отсутствия записи, а решения на этом принимались серьёзные:
  «пира нет» означало «создать заново», «по auth_id не нашли» — «искать по
  имени и, не найдя, создать», «ошибка» в `ExistPeerName` — «имя свободно». При
  недоступной базе продукт не отказывал, а трактовал отказ как разрешение
  действовать. Введены sentinel-значения `ErrPeerNotFound`,
  `ErrAdminUserNotFound`, `ErrConfigNotFound` и `ErrStorage`.

- **Алиасы `/:id/client-url` и `/:id/qr` удалены.** Они были оставлены «на один
  миграционный релиз», которого у clean-install-only продукта не существует;
  дожив до `1.0.0`, они стали бы частью публичного API v1.

### Добавлено — контракт разработки

- **`apps/go.mod` объявляет `toolchain go1.26.7`.** Директива `go` — языковой
  baseline модуля, а не выбор компилятора: с ней одной локальный `go build` на
  другой минорной линии проходил успешно, хотя релизный бинарь собирается на
  1.26.7 и наследует **её** stdlib. Разработчик и сборка проверяли разный код.
  Совпадение с `versions.env` проверяет `verify_go_toolchain_contract`.

- **`tools/dev/doctor.sh` и `tools/dev/doctor.ps1`** сверяют Go, Node, pnpm, Bun
  и директиву `toolchain` с `versions.env`. Собственных значений версий у них
  нет — второй список неизбежно разъехался бы с контрактом. Сборка соблюдала
  `versions.env` и раньше; машина разработчика не проверялась никак, и
  расхождение обнаруживалось на Debian, внутри release-сборки.

### Изменено — модернизация frontend

Известное ограничение «проверка типов frontend почти ничего не проверяет»
закрыто и удалено из документации.

- **`vue-tsc` стал настоящим release gate.** Он был версии `0.35.0` (2022 год) и
  шаблоны Vue не типизировал: проверка проходила зелёной, не давая обещанной
  гарантии. На Vue 3.5 она к тому же ломается сама, не зная `vue/jsx-runtime`, —
  то есть пережить обновление Vue не могла в любом случае.

  Современный `vue-tsc 3.3` на том же коде дал **142 ошибки**, а не ~155 из
  прогноза, и картина оказалась однороднее: 141 × `TS18048` и одна `TS2322`,
  всё в двух файлах представления Hysteria. Ожидавшегося класса «`DefaultRow`
  несовместим с `PeerVo`» на Element Plus 2.3 не существовало — он появился
  вместе с обновлением Element Plus до 2.14.

  Скрипты разделены: `typecheck`, `build:prod`, `verify`. Сборка запускает
  проверку типов **до** bundle; раньше `vite build && vue-tsc` сначала тратил
  время на production bundle и только потом сообщал о типовой ошибке.

- **Нормализация конфига Hysteria на границе API.** Все 142 ошибки — обращения
  к необязательным секциям конфига в шаблоне. Необязательны они правильно: так
  устроен upstream YAML. Инвариант «секция есть всегда» существовал, но держался
  на порядке присваиваний внутри компонента и типом не выражался. Введён
  `Hysteria2ServerConfigView`, выводимый из модели ответа типом, а не вторым
  списком полей, — вместо 141 оператора `?.` или `as any`.

- **Убраны три редактора, которые ничего не сохраняли.** Outbounds, список
  значений и словарь «ключ — значение» на странице конфига Hysteria: страница
  отрисована с `:disabled="true"`, значения передаются без `v-model`, маршрутов
  записи серверного конфига в API нет. Оператор мог добавить outbound, увидеть
  его в списке и уйти в уверенности, что изменил конфигурацию сервера.

  У одного цена была ещё и измеримой: `vuedraggable` поставляется UMD-сборкой,
  поэтому её `require("vue")` разрешался в полную сборку Vue с
  рантайм-компилятором — около полумегабайта в bundle ради перетаскивания тегов
  в недоступной для редактирования форме.

- **`pnpm audit` по всему графу: 33 предупреждения → 0.** Из них четыре
  затрагивали production-зависимости (`vue-i18n`, `echarts`), остальные —
  build-цепочку. Среди последних был rollup GHSA DOM clobbering, а он
  затрагивает **генерируемый bundle**, то есть уезжает в production: `pnpm audit
  --prod`, на который смотрит gate сборки, его не показывал.

  Обновлены: Vue 3.2 → 3.5, TypeScript 4.9 → 5.9, Element Plus 2.3 → 2.14,
  Vue Router 4.1 → 4.6, Pinia 2.0 → 2.3, VueUse 9 → 14, echarts 5 → 6,
  Vite 4.3 → 7.3, eslint 8 → 10 (с переходом на flat config), stylelint 15 → 17.
  Pinia 3, Vue Router 5 и Vite 8 сознательно не берутся: Vite 8 — это переезд на
  Rolldown, остальные не дают проекту ничего, кроме номера версии.

- **`vite-plugin-svg-icons` заменён собственным спрайтом.** Плагин не
  обновлялся с 2022 года и тянул `svgo 2.8`, `postcss 5.2.18` и
  `image-size 0.5.5`, у которой advisory сообщает `Patched versions: <0.0.0` —
  исправленной версии не существует. Проверка на реальных ассетах поймала то,
  что иначе уехало бы в релиз: три иконки из семнадцати не объявляют `viewBox`,
  и без его синтеза из `width`/`height` отрисовывались бы обрезанными.

- **Разбор bundle через sourcemap** нашёл вторую потерю: `@vueuse/core`
  собирался дважды — наш и тот, что тянет Element Plus. Версии сведены.

  Итог по размеру: 2 819 722 байта против 2 404 202 на исходной базовой линии.
  Рост в 17% — цена Vue 3.5, Element Plus 2.14, echarts 6 и rollup 4;
  промежуточное состояние до двух исправлений выше было 3 046 172.

### Исправлено — сборка не собиралась

- **`build.sh` детектировал сам себя и падал шестым шагом из четырнадцати.**
  `verify_api_namespace_contract` искал возвращение legacy-пространства имён
  через `grep -rlF '/hui'` по списку каталогов, в который входили `tools/build`
  и тесты. Поиск находил два файла: `apps/router/router_test.go`, который
  ПЕРЕЧИСЛЯЕТ legacy-префикс, чтобы доказать отсутствие маршрута, и сам
  `versions.sh`, где эта строка стоит в тексте проверки. То есть добавление
  теста, закрепляющего очистку, ломало сборку, а до резолва Hysteria дело не
  доходило вовсе.

  Скан теперь идёт только по runtime production sources и по тому, что уезжает
  в пакет, с исключением `*_test.go`. Гарантия не ослабла, а переехала на слой,
  где она сильнее: отсутствие маршрута доказывает
  `TestRouterHasNoLegacyNamespace` на таблице маршрутов собранного роутера, и
  существование этого теста само стало частью контракта.

- **Второй такой же контракт прятался за первым.** Проверка «импорт пиров не
  выходит за транзакцию» брала `source.slice(start)` — файл от начала
  `applyPeerImportEntry` и до конца, — захватывая объявленные ниже
  `ExistPeerName` и `UpdatePeerLastConnectionAt`. Это обычные операции вне
  импорта, которым глобальное соединение положено, поэтому проверка падала на
  корректном коде. Замечена не была только потому, что сборка до неё не
  доходила. Границей тела функции теперь служит следующее объявление верхнего
  уровня.

  Отсюда общее правило и помощники `code_without_comments` / `code_mentions_in`
  в `acceptance.sh`: приёмка проверяет **код**, а не упоминания.

### Исправлено — runtime

- **Смена расписания сброса трафика размножала планировщики.**
  `middleware.InitCron()` вызывался из `runServer` и на каждом вызове создавал
  новый `cron.New()`, нигде не сохраняя ссылку; `cron.Stop()` не вызывался
  нигде. При этом смена `RESET_TRAFFIC_CRON` выполняла `StopServer()`, а точка
  входа крутила `for { runServer() }` и поднимала сервис заново.

  Каждая правка добавляла **целый дублирующий набор джоб** — учёт трафика, сбор
  метрик, уборка статистики, — а старое расписание сброса продолжало работать.
  После двух правок на процессе висели три планировщика и три разных расписания
  одновременно. Плюс окно, в котором джобы старого планировщика били в уже
  закрытое SQLite-соединение: `releaseResource()` отрабатывал раньше, чем
  следующий `runServer` успевал открыть базу.

  Планировщик теперь принадлежит процессу: фиксированные джобы регистрируются
  один раз, расписание сброса переносится на месте по своему `EntryID`,
  HTTP-сервер к смене настройки отношения не имеет. Цикл перезапуска в точке
  входа удалён — перезапуском упавшего юнита занимается systemd.

- **Невалидное cron-выражение принималось API и молча отключало сброс трафика.**
  Поле в панели — `el-select` с `allow-create`, то есть строка произвольная;
  backend принимал её как строку до 128 символов, а ошибка `AddFunc` при
  следующем старте только логировалась. Оператор получал успех, панель работала,
  автоматический сброс исчезал.

  Выражение проверяется до записи в базу тем же парсером (`cron.ParseStandard`),
  которым его потом разбирает планировщик. Невалидное значение — отказ, база не
  меняется. Пустое значение легально и означает «сброс выключен».

- **`updateConfigs` применял партию частично.** Валидация и запись шли в одном
  цикле, поэтому партия «разрешённый ключ + запрещённый» применяла первый и
  возвращала ошибку на втором. Существовавший тест ставил запрещённый ключ
  первым и не смотрел в базу — поймать это он был неспособен по построению.

  Теперь: полная проверка партии → одна транзакция (`dao.WithConfigTx`) →
  применение к рантайму. Тест переписан на обратный порядок ключей и проверяет
  состояние базы на настоящей SQLite.

- **Сервис не завершался штатно.** `SIGTERM` от systemd убивал процесс на
  середине: соединения обрывались, SQLite закрывался вместе с процессом, джобы
  могли быть остановлены посреди записи. Добавлено штатное завершение —
  планировщик глушится и дожидается запущенных джоб, затем закрывается база.

- **Ложные ERROR в журнале на каждой первой загрузке.** Создание секретов шло по
  схеме «сначала INSERT, при ошибке UPDATE», а строки ключей уже существовали из
  `seedBaseConfig`: три записи `duplicated key not allowed` уровня error на
  совершенно здоровом старте. Зеркальная схема «сначала UPDATE, при ошибке
  INSERT» в других местах была хуже — она **тихо не делала ничего**, если строки
  не было: UPDATE без совпавших строк не ошибка, поэтому ветка INSERT не
  выполнялась, а вызывающий получал сгенерированный секрет как сохранённый. Для
  `JWT_SECRET` это означало бы подпись токенов ключом, которого нет в базе.
  Обе схемы заменены на `dao.UpsertConfigValue`, решающий по `RowsAffected`.

- **Дублирующая реализация генерации ключей шифрования.** В
  `service/peer_secret.go` лежали построчные копии `getOrCreateConfigKey` и
  `getPeerSecretEncryptionKey` из `dao/sqlite.go`: две функции в двух пакетах,
  порождающие один и тот же материал шифрования. Расхождение между ними
  означало бы, что секреты пиров шифруются одним ключом, а расшифровываются
  другим. Осталась одна реализация в `dao`.

### Безопасность

- **Bootstrap-пароль администратора писался в журнал открытым текстом.** При
  отсутствии `HY2XS_ADMIN_INITIAL_PASSWORD` админка генерировала пароль сама и
  печатала его двумя `logrus.Warnf` в `/var/log/hy2xs/hy2xs-admin.log` — файл,
  который отдаётся кнопкой выгрузки и попадает в diagnostics-бандл. Такой пароль
  к тому же не знал никто, кроме журнала.

  Отсутствие переменной теперь **отказ старта** с объяснением причины. То же для
  `HY2XS_ADMIN_CON_PASS` при создании пира установщика: его секрет продублирован
  в `/etc/hy2xs/bootstrap-admin.secret`, откуда его читает проверка machine-auth,
  и придуманный админкой секрет разошёлся бы с файлом.

- **Собственный журнал админки выгружался без санитайза**, хотя чужой (журнал
  Hysteria) — с санитайзом. Теперь оба проходят `SanitizeLogText`, и во вкладке
  просмотра тоже.

- **`golang-jwt/jwt` v3 в пути аутентификации.** У v3.2.2 есть GO-2025-3553,
  у которой **нет исправленной версии в ветке v3** (`Fixed in: N/A`), а уязвимый
  код достигается из `ParseToken`, то есть с неаутентифицированного запроса.
  Выполнен переход на `jwt/v5`.

  Заодно закрыт тихий недостаток: `keyfunc` возвращал ключ, не проверяя алгоритм
  подписи, — набор допустимых алгоритмов фактически задавал сам токен. Разбор
  ограничен `jwt.WithValidMethods`, проверяются `issuer` и обязательное наличие
  срока жизни; пустой `JWT_SECRET` считается повреждённым состоянием, а не
  ключом нулевой длины.

- **Вход по несолёному SHA-224 больше невозможен.** `VerifyPassword` принимала
  такой хеш как «legacy»-формат предыдущего поколения. В v1 он недостижим:
  миграции таблицы `account` удалены, установка возможна только на чистый хост,
  конфигурация 0.x отклоняется по схеме. Compatibility-ветка пережила слой
  совместимости, ради которого существовала, и осталась запасным путём проверки
  пароля слабым алгоритмом в обработчике логина.

- **Modulo bias в генераторе секретов.** `util.RandomString` брала остаток байта
  от деления на длину алфавита (62): первые восемь символов выпадали примерно на
  четверть чаще остальных. Через эту функцию проходят `JWT_SECRET`,
  `PEER_SECRET_KEY`, `PEER_SECRET_ENCRYPTION_KEY`, секрет trafficStats API,
  секреты и `auth_id` пиров. Добавлена отбраковка (rejection sampling).

- **Пир установщика был защищён только в импорте.** Обычный CRUD панели
  позволял переподписать или переименовать `bootstrap-admin-peer`, молча
  рассинхронизировав базу с `/etc/hy2xs/bootstrap-admin.secret`. Защита
  распространена на все пути записи; удаление и отключение остаются
  разрешёнными — это осознанные действия оператора, не создающие расхождения.

- **Латентная паника в разборе токена.** `service.GetToken` доставала токен
  через `strings.SplitN(header, " ", 2)[1]` и падала на заголовке без пробела.
  Единственный потребитель — резервная ветка `GetAdminInfo`, недостижимая и
  проверявшая меньше, чем middleware (ни статус учётной записи, ни версию
  токена). Оба удалены: разбор токена у продукта ровно один.

- **`reset-admin` генерировал 6-символьные логин и пароль** — нижняя граница,
  которую пропускает `HashPassword`. Увеличено до 12 и 24.

### Изменено

- **Toolchain переведён на поддерживаемые линии.** `GO_VERSION` 1.21.13 → 1.26.7,
  `NODE_VERSION` 20.19.0 (EOL) → 24.20.0. Go компилирует `hy2xs-admin`, поэтому
  его stdlib целиком попадает в production-бинарь: на прежнем графе
  `govulncheck ./...` находил **21 вызываемую уязвимость**, из них 17 в stdlib.
  После перехода и обновления зависимостей — **ноль**.

  Bun намеренно оставлен на 1.3.13: оркестратор собирается через
  `bun build --compile`, то есть Bun runtime входит в исполняемый файл, и смена
  его версии требует отдельного прохода по всей матрице проверок.

- **Добавлен обязательный шаг проверки зависимостей** (`tools/build/lib/security.sh`):
  `govulncheck ./...` для Go-графа и stdlib с анализом достижимости и
  `pnpm audit --prod` для frontend. Версия `govulncheck` пиньтся в `versions.env`,
  база уязвимостей подтягивается на каждом запуске. Аварийный выход —
  `ALLOW_VULNERABLE_DEPENDENCIES=true`; результат уезжает в metadata пакета полем
  `dependency_security_gate`.

- **Обновлены зависимости frontend, попадающие в браузерный бандл**: `axios`
  1.3.4 → 1.20.0, плюс `lodash`/`lodash-es` через `pnpm.overrides` до 4.18.1.
  Прямые зависимости и их диапазоны не менялись — двинулся только lockfile.
  В production-графе не осталось уязвимостей уровня high и critical.

### Удалено

- **Четыре ключа таблицы `config` без единого потребителя** —
  `HYSTERIA2_ENABLE` (жизненным циклом Hysteria владеет systemd),
  `HYSTERIA2_CONFIG` (второй источник истины рядом с
  `/etc/hysteria/config.yaml`, причём читался **первым**),
  `HYSTERIA2_TRAFFIC_TIME` (настройка «период учёта трафика», которую не читал
  никто: интервал сбора метрик задан в коде) и `HYSTERIA2_CONFIG_REMARK` (пустая
  read-only строка). Строки удаляются миграцией `006_drop_dead_config_keys`.

  Настоящую замену получил только последний: имя профиля в клиентской ссылке
  теперь выводится из имени пира, а при его отсутствии — из публичного хоста.

  После очистки панель владеет ровно одной настройкой — `RESET_TRAFFIC_CRON`.

### Исправлено — предыдущий проход

- **Каждая чистая установка падала сразу после `apt-get`.** Внутри `install`
  `preflight()` вызывался дважды, и оба раза проверял контракт чистого хоста.
  Ко второму вызову на диске уже лежал собственный
  `/var/lib/hy2xs/install-state.json`, записанный после первого preflight, — и
  он опознавался как маркер посторонней установки. Отказ приходил уже как
  `fatal_post_apply`: сервер оставался наполовину настроенным, а повторный
  запуск упирался в тот же маркер.

  Причина в том, что clean-host и проверка возможностей платформы ехали одним
  параметром, хотя отвечают на разные вопросы: чистота хоста — условие **входа**
  в операцию, а `systemd-run`/`nftables`/OpenSSL 3 проверяются уже после
  `installDeps`, то есть внутри PHASE 1. `preflight()` теперь принимает
  `checkCleanHost` явно и **без значения по умолчанию** в режиме install: любое
  умолчание здесь неверно, решение обязано приниматься на месте вызова.

- **PHASE 1 начиналась вне зоны ответственности оркестратора.** `install.sh`
  сам создавал `/usr/local/lib/hy2xs`, ставил туда бинарник, вешал symlink в
  `/usr/local/bin` и копировал runtime-пакет — и только потом запускал
  оркестратор, у которого дальше шёл собственный preflight. Если тот отказывал
  (сменился DNS, занялся порт, не ответил резолвер), ни один ownership-флаг не
  был взведён: отказ классифицировался как `fatal_pre_apply`, и оператор читал
  «на сервере ничего не изменено» при уже созданном каталоге оркестратора.
  Следующий запуск упирался в эти пути как в маркеры чужой установки.

  Отследить владение мутацией невозможно, пока мутируют двое. Теперь
  `install.sh` не изменяет на сервере **ничего**: он проверяет и передаёт
  управление через `exec`. Раскладку выполняет сам оркестратор — шаг
  `steps/bootstrap.ts` под флагом `ownership.bootstrapTouched`, а сами пути
  попадают в `owned_paths` install-state наравне с остальными. Сборка проверяет
  структурно, что в установщике не осталось ни одной мутирующей команды.

  Побочный эффект: у списка clean-host маркеров больше нет «мягкой» версии для
  PHASE 1. Она существовала только затем, чтобы установка не отказала на путях,
  которые shell создал между фазами.

- **Machine token утекал в обычные логи при каждом подключении пира.** Hysteria
  обращается к машинному endpoint'у как
  `/internal/hysteria/auth?access_token=<секрет>`, а журнал админки писал
  `c.Request.RequestURI` — то есть путь вместе с query string. Действующий
  токен оседал открытым текстом в `/var/log/hy2xs/hy2xs-admin.log`, который
  отдаётся оператору через `ExportLog` и попадает в diagnostics-бандл. Вся
  структурная редакция, сделанная для конфигов и env, этот канал не закрывала.

  Логируется путь; значения query-параметров не пишутся вовсе, имена —
  пишутся (`reqQueryKeys`). Поле `reqUri` удалено из модели журнала.

  Каналов было два: `gin.Default()` подключает `gin.Logger()`, который печатает
  путь вместе с query в stdout, откуда он уходит в journald, а оттуда — в
  diagnostics-бандл. Панель запускается через `gin.New()` + `gin.Recovery()`,
  и HTTP-логгер у продукта остался ровно один.

  Дополнительно: журналы внутри diagnostics-бандла (`journal-admin.log`,
  `journal-hysteria.log`, вывод `systemctl status`) больше не копируются как
  есть, а проходят санитайз; тот же проход применяется к журналу Hysteria,
  который админка отдаёт через `ExportLog`. Сравнение machine token переведено
  на `subtle.ConstantTimeCompare`.

- **Config API позволял прочитать и подменить криптографические ключи
  приложения.** Generic export/import таблицы `config` удалили, но точечный API
  остался прежним: `getConfig`/`listConfig` принимали произвольный ключ, а
  проверка записи работала denylist'ом из трёх ключей оркестратора. Запрос
  `?key=PEER_SECRET_ENCRYPTION_KEY` отдавал master-key шифрования секретов
  пиров, а `updateConfigs` позволял подменить `JWT_SECRET` и оба peer-ключа.

  Доступ переведён на **allowlist**: наружу открыты только
  `HYSTERIA2_TRAFFIC_TIME`, `RESET_TRAFFIC_CRON` (чтение и запись) и
  `HYSTERIA2_CONFIG_REMARK` (только чтение). Denylist требует, чтобы автор
  каждого нового ключа вспомнил про этот файл; при allowlist забытый ключ
  закрыт. Маршрут `GET /api/config/getConfig` удалён целиком — потребителей у
  него не было ни одного, а фильтр на неиспользуемой двери остаётся дверью.

- **Импорт пиров не был атомарным, вопреки собственному контракту.** Партия
  проверялась целиком до первой записи, но применялась по одной записи, каждая
  своим оператором. Валидация ничего не знает о том, что уже лежит в базе:
  пусть есть `A(auth_id=aaa, name=alice1)` и `B(auth_id=bbb, name=bob123)`, а
  файл несёт `(auth_id=aaa, name=bob123)` — поиск найдёт A по `auth_id` и
  попытается переименовать её в `bob123`, прямо в `UNIQUE(name)`. Всё, что шло
  в файле до конфликтной строки, оставалось применённым, и откатить это
  оператор уже не мог.

  Применение выполняется одной транзакцией (`dao.WithPeerTx`). Криптоматериал
  считается до её открытия: digest и шифрование читают ключи из той же таблицы
  `config`, и держать на ней открытую запись во время AES по каждой из тысяч
  записей незачем.

- **Файл импорта мог содержать хвост, который молча не применялся.**
  `json.Decoder` читает первый документ и останавливается, поэтому файл вида
  `[{...}]\n{"что-то":"ещё"}` принимался целиком: оператор видел «импорт
  выполнен» и не узнавал, что применилась половина. После разбора проверяется
  `io.EOF`.

- **Отказ сбора диагностики отменял откат.** В `install` и `reconfigure`
  `diagnosticsCollect()` стояла перед rollback обычным `await`. Она создаёт
  каталог, копирует файлы и упаковывает tar — на заполненном диске падает сама,
  и тогда худший сценарий отказа установки гарантированно лишался единственного
  механизма восстановления. Диагностика — best effort, откат — обязателен.

- **`fatal_pre_apply` мог означать «хост уже изменён».** `install-state.json`
  пишется сразу после успешного preflight, до установки пакетов, но
  классификация отказа его не учитывала. Падение `apt-get update` или
  `apt-get install` объявлялось как «на сервере ничего не изменено»: откат и
  обработка состояния пропускались, а маркер оставался на диске и ломал
  следующую установку по clean-host контракту.

  Ownership-флаги переформулированы с «шаг успешно завершился» на «операция
  могла начать менять систему» и взводятся **перед** мутирующим вызовом:
  `apt-get` умеет изменить систему и упасть. `fatal_pre_apply` теперь
  недостижим ни при одном взведённом флаге, включая запись состояния.

- **Экспорт в админке оставлял секреты на диске навсегда.** `ExportPeer` и
  выгрузка системного конфига шли через `os.Create` в
  `/var/lib/hy2xs-admin/export/`, и файл там не удалялся. При
  `?includeSecrets=true` это означало расшифрованные секреты пиров — фактические
  учётные данные доступа — в открытом виде, накапливающиеся с каждым нажатием
  кнопки. Экспорт формируется в памяти; каталога `export/` больше нет.

- **Generic export/import таблицы `config` выгружал и позволял подменить
  криптографические ключи приложения.** Выгрузка исключала только сырой Hysteria
  YAML, а в той же таблице лежат `JWT_SECRET`, `PEER_SECRET_KEY`,
  `PEER_SECRET_ENCRYPTION_KEY` и `HYSTERIA2_TRAFFIC_STATS_SECRET`. Импорт их не
  блокировал: подмена `PEER_SECRET_ENCRYPTION_KEY` ломает расшифровку секретов
  уже существующих пиров. Оба маршрута и их UI удалены — production-сценария у
  них не было, перенос пиров делают `peer-import`/`peer-export`.

- **Импорт пиров шёл мимо всей валидации.** Обычное создание пира проходит через
  `dto.PeerSaveDto`, импорт JSON — нет: в базу попадало имя любой длины и с
  любыми символами, `disabled` с произвольным числом, отрицательные счётчики.
  Файл применялся построчно, поэтому ошибка в середине оставляла список пиров
  наполовину изменённым, а импорт мог перезаписать `bootstrap-admin-peer`, чей
  секрет продублирован в `/etc/hy2xs/bootstrap-admin.secret`. Партия теперь
  проверяется целиком до первой записи, неизвестные поля отклоняются,
  bootstrap-пир защищён.

- **DNS проверялся на существование A-записи, но не на то, куда она ведёт.**
  После принудительной смены IPv4 провайдером `doctor` отвечал успехом, хотя
  клиентская ссылка отправляла людей на чужую машину. Проверялся при этом
  `HY2XS_DOMAIN`, тогда как в `hysteria2://` уезжает `HY2XS_PUBLIC_HOST`.

  Добавлен инвариант публичного endpoint: A-записи обязаны принадлежать
  множеству публичных IPv4, назначенных интерфейсам этого сервера. Проверка
  живёт в общем `preflight`, поэтому действует в `install`, `reconfigure` и
  `doctor`. Адрес определяется локально, без внешних сервисов определения IP.
  Строгость управляется `HY2XS_PUBLIC_ENDPOINT_POLICY` (`strict` по умолчанию).

- **Read-only guard PHASE 0 можно было обойти.** Guard стоял на `writeText`,
  `writeTextAtomic`, `runVisible`, `runHidden` и `runRawVisible`, но не на
  универсальном `run`, через который в коде проходили и наблюдение (`ss`,
  `systemctl is-active`), и настоящие мутации (`useradd`, `install -d`,
  `mkdir`, `cp -a`, `tar`). Универсального раннера больше нет: есть
  `runReadOnly*` без guard'а и `runMutating*` под guard'ом, а выбор — явное
  решение на месте вызова.

- **Go-санитайзер конфига вырезал секреты из URL только у ключей `url`/`addr`.**
  Будущее upstream-поле с другим именем (`endpoint:`) уносило встроенные
  учётные данные и `access_token` наружу целиком; URL внутри списков не
  обрабатывались вовсе. Граница определяется значением, а не именем ключа —
  как в TS-санитайзере оркестратора; обе реализации покрыты зеркальными тестами.

- **`purge-v0.sh --keep-hysteria-binary` противоречил установщику.** Скрипт
  сохранял `/usr/local/bin/hysteria` и сообщал «хост чист для установки
  HY2XS v1», хотя clean-host контракт считает этот бинарник legacy-маркером и
  следующая установка отказалась бы. Флаг удалён.

- **clean-host не замечал часть того, что удаляет purge.** `/var/lib/hysteria`
  (ACME-состояние и сертификаты Hysteria), `/var/log/hy2xs`,
  `/usr/local/lib/hy2xs` и `/usr/local/bin/hy2xs-orchestrator` не были
  маркерами: сервер, где остался только старый runtime-state Hysteria, проходил
  проверку и получал свежую установку поверх чужого состояния. Оба списка
  теперь описывают одну границу, и приёмка это проверяет.

- **Установщик мог повредить работающий сервер до того, как откажется его
  трогать.** `install.sh` переписывал `/usr/local/lib/hy2xs`, раскладывал
  runtime-пакет и перезаписывал `/var/lib/hy2xs/install-state.json`, и лишь
  потом запускал clean-host preflight. При ошибочном запуске поверх старого
  сервера rollback дополнительно выполнял `stop` и `disable` для работающих
  `hysteria-server` и `hy2xs-admin`.

  Установка разделена на две фазы с жёсткой границей: **PHASE 0 — read only**,
  **PHASE 1 — mutation**. Read-only проверка выполняется новой командой
  `hy2xs-orchestrator preflight-install` из распакованного архива, а граница
  держится runtime-guard'ом, а не соглашением.

- **Отсутствие `HY2XS_CONFIG_SCHEMA_VERSION` считалось текущей схемой.** До v1
  этого поля не существовало, поэтому именно пустое значение — самый вероятный
  признак конфигурации `0.x`. Теперь оно отклоняется как legacy с указанием на
  чистую установку. Тест, закреплявший прежнее поведение, инвертирован.

- **`reconfigure` и `repair` работали поверх любого маркера установки.**
  Проверялся только флаг `installed`, который мог остаться и от `0.x`.
  Маркер получил идентификацию поколения (`product`, `release_line`,
  `config_schema_version`), и обе команды проверяют её до всего остального.

- **Классификация отказа шла по тексту сообщения об ошибке.** Ошибка
  preflight со словом `nftables` классифицировалась как отказ firewall и
  приводила к откату чужого ruleset. Теперь классификация опирается на то, что
  операция реально успела применить. `systemctl stop/disable` выполняется
  только для юнитов, развёрнутых текущей операцией, а `fatal_pre_apply` по
  определению не выполняет системный откат и не собирает diagnostics-бандл.

- **Diagnostics-бандл уносил machine token наружу.** Построчное правило
  редакции `auth:` подставляло маркер в заголовок mapping'а и оставляло
  нетронутым вложенный `auth.http.url` с `access_token=<секрет>` — тем самым,
  что открывает и trafficStats API, и auth-endpoint. Редакция YAML переписана
  структурно; в env-файлах секреты теперь вырезаются и из URL-значений
  (`HY2_AUTH_URL` не подходил ни под один маркер имени).

- **`quic.maxIdleTimeout` не проверялся** семантической проверкой конфига, хотя
  присутствовал в production-профиле. Заодно `auth.http.url` теперь сверяется
  целиком (host/port/path/token), а не по наличию подстроки `access_token=`;
  добавлены проверки `auth.http.insecure`, полей ACME и отсутствия посторонних
  секций верхнего уровня.

- **Версия админки разъехалась с версией пакета**: пакет `1.0.0` сообщал
  `HY2XS admin version v0.0.22`. Константа заменена переменной, которую
  проставляет сборка через ldflags из `versions.env`.

- **Кнопки в панели, которые всегда возвращали ошибку.** «Перезапустить панель»
  и загрузка сертификатов обращались к заглушкам. Маршруты и UI удалены.

### Добавлено

- **`versions.env`** — единственный источник истины для контракта
  «продукт / платформа / toolchain»: версия продукта, линия релиза, схема
  конфигурации, целевая платформа, версии и контрольные суммы Go/Bun/Node/pnpm,
  политика выбора Hysteria. Прикладные зависимости и конкретная версия
  Hysteria сюда намеренно не переносятся: у них есть собственные lock-механизмы.

- **Шаг сборки `verify_versions_contract`.** Роняет сборку до создания tarball,
  если разошлись `PACKAGE_VERSION`, `packageManager` в двух `package.json`,
  схема в `package/config/hy2xs.env`, константы, скомпилированные в
  оркестратор, директива `go` в `apps/go.mod`, metadata пакета или версия,
  которую сообщает собранный `hy2xs-admin`.

- **Контрольные суммы toolchain в контракте**, включая **обе** сборки Bun
  (`bun-linux-x64` и `bun-linux-x64-baseline`): артефакт выбирается по наличию
  AVX2, поэтому одной суммы архитектурно недостаточно. Передавать суммы через
  окружение больше не нужно — production-сборка запускается одной командой.

- **Проверка происхождения артефакта Hysteria.** Ожидаемый SHA-256 берётся из
  upstream-ассета `hashes.txt` и сверяется со скачанным бинарником до записи в
  HY2XS lock. Раньше сумма считалась локально от уже скачанного файла, то есть
  была trust-on-first-use.

- **Полный clean-host контракт.** Список маркеров чужой установки расширен с
  двух до четырнадцати: состояние, runtime-пакет, конфиги, бинарник Hysteria,
  фрагмент nftables, systemd-юниты, база админки и наследие `0.x`. Пути
  установки и данных берутся из конфигурации, а не захардкожены.

- **`tools/legacy/purge-v0.sh`** и [docs/14-legacy-cleanup.md](docs/14-legacy-cleanup.md) —
  явная очистка сервера от предыдущего поколения. По умолчанию скрипт
  показывает план и ничего не делает; выполнение требует
  `--apply --yes-i-know`. Из установщика он не вызывается никогда: это вернуло
  бы destructive migration logic в путь свежей установки.

- **Явный флаг `--allow-partial-state` для `repair`.** Прежде согласие на
  работу поверх незавершённой установки подразумевалось молча.

- **`HY2XS_PUBLIC_ENDPOINT_POLICY`** (`strict` | `warn` | `off`, по умолчанию
  `strict`) — строгость проверки того, что публичный endpoint ведёт на этот
  сервер. Ослабление предназначено для топологий вне baseline: NAT, floating IP,
  anycast. Отсутствие A-записи фатально при любом значении.

- **Раздельные API подпроцессов в оркестраторе**: `runReadOnly` /
  `runReadOnlySecret` для наблюдения и `runMutating*` под read-only guard'ом.

- **Сверка API namespace на сборке.** Путь machine-auth и базовый префикс
  админского API объявлены по одной константе на компонент, а
  `verify_versions_contract` сверяет Go, фронтенд и шаблоны против значений,
  скомпилированных в оркестратор.

### Изменено

- **Пространства имён HTTP API.** Операторский и auth API переехали с `/hui` на
  `/api`, machine-auth endpoint Hysteria — на `/internal/hysteria/auth`. Прежний
  общий префикс был наследием H UI: под ним лежали и machine-to-machine auth, и
  JWT-защищённый админский API, хотя middleware у них не пересекаются. Момент
  выбран до первого clean-install релиза: после `1.0.0` эти строки стали бы
  частью фактического v1 compatibility contract.

- **Сетевая идентичность админки принадлежит оркестратору.** Ключи
  `H_UI_WEB_PORT`, `H_UI_WEB_CONTEXT`, `H_UI_CRT_PATH`, `H_UI_KEY_PATH` удалены
  из схемы, seed и интерфейса вместе с собственным TLS-слоем панели. Раньше
  оркестратор передавал порт аргументом, админка записывала его в SQLite и тут
  же читала обратно, а UI показывал поля в disabled-виде: второй источник истины,
  из которого ничего нельзя было изменить. Панель всегда монтируется в `/`.

- **`HUI_DATA`/`HUI_LOG` → `HY2XS_DATA_DIR`/`HY2XS_LOG_DIR`.** Мост в
  systemd-юните, перекладывавший canonical env HY2XS в имена старого H UI,
  удалён.

- **Экспорт пиров разделён на два явных режима.** «Экспорт настроек» — без
  секретов, «Резервная копия» — с ними, через подтверждение с описанием риска.

  Кнопка была одна и всегда звала маршрут без `includeSecrets`, хотя
  документация называла эту пару механизмом переноса пиров. Записи с пустым
  секретом при импорте получают **новые** секреты, поэтому перенос обычным
  экспортом восстанавливал пиров, но все существующие клиентские ссылки после
  него переставали работать. Разница продуктовая, и оставлять её неявной нельзя.

- **`reconfigure`/`repair` больше не классифицируют отказ по тексту ошибки.**
  Записываемая фаза выбиралась регулярным выражением
  `/firewall|nft|ssh port check failed/i` по сообщению — тот же приём, который
  уже убрали из `install`. Классификация переведена на ownership-флаги, а откат
  firewall выполняется только если эта операция его трогала.

- **Список непубличных IPv4 приведён к IANA Special-Purpose Address Registry.**
  Функция называлась «маршрутизируемый публичный IPv4», а исключения покрывали
  только приватные диапазоны: `203.0.113.5` (TEST-NET-3 из RFC-примеров)
  считался нормальным публичным адресом сервера. Добавлены документационные
  (`192.0.2/24`, `198.51.100/24`, `203.0.113/24`), benchmarking (`198.18/15`),
  6to4-anycast и IETF protocol assignments.

- **Отказ DNS-резолвера отличается от отсутствия A-записи.** Любая ошибка
  `resolve4` печаталась как «has no A-record», поэтому при сломанном
  `/etc/resolv.conf` оператор шёл править запись, которая была на месте.
  `ENODATA`/`ENOTFOUND`/`NXDOMAIN` — это «нет записи», всё остальное —
  «резолвер не ответил», с отдельным текстом. Фатальны оба: без ответа
  резолвера проверка не выполнена, а не «выполнена с замечанием».

- **База админки — `hy2xs-admin.db`** вместо `h_ui.db`; reference-схема —
  `apps/docs/sql/schema.sql` вместо `h_ui_db.sql`. Совместимость сохранять не
  требуется: v1 ставится только с нуля. Историческое имя `h_ui.db` остаётся в
  [docs/14-legacy-cleanup.md](docs/14-legacy-cleanup.md) — там это имя чужого
  артефакта, который очистка должна найти.

- **Индикатор загрузки и legacy-цвета переведены на брендовый токен.**
  NProgress приходил со своим `#29d` и был единственным элементом интерфейса вне
  палитры HY2XS; страницы `401`/`404` и подсветка выбранной строки таблицы несли
  цвета исходного admin-шаблона. Все они привязаны к `--el-color-primary`, а не
  переписаны вторым литералом.

- **Приёмка сверяет схему конфигурации с `versions.env`**, а не с числом `2`
  в тексте проверки.

- **E2E подключается по ссылке из production-кода.** Внутри
  `tools/test/e2e-hysteria.sh` жила вторая реализация `hysteria2://` URI на
  bash: дрейф любой из двух реализаций оставлял обе группы тестов зелёными.
  Теперь ссылку выдаёт `service.BuildHysteria2ShareURI` через
  `apps/tools/share-uri`. Единственное расхождение — `insecure=1` для
  самоподписанного сертификата, и оно ограничено тестами с двух сторон.

- **Формулировка гарантии санитайза экспорта.** Вместо «любой будущий секрет
  будет удалён» — «известные секреты и неизвестные поля с секретоподобным
  именем». Список маркеров расширен (`apiKey`, `privateKey`, `authorization`,
  `cookie`, `bearer`, `passphrase`, `signature`, …) и синхронизирован между
  Go-админкой и оркестратором.

### Удалено

- Маршруты, операциями которых продукт не владеет:
  `POST /hysteria2ChangeVersion`, `GET /listRelease`,
  `POST /config/updateHysteria2Config`, `POST /config/importHysteria2Config`,
  `POST /config/restartServer`, `POST /config/uploadCertFile`,
  `GET /config/hysteria2AcmePath`. Вместе с ними — соответствующие сервисы,
  клиентские функции фронтенда, кнопки и строки i18n.

  Маршруты удалены, а не оставлены отвечающими «feature disabled»: API-контракт
  не должен обещать updater, которого у продукта нет, а неиспользуемый маршрут
  остаётся attack surface.

- `POST /config/exportConfig` и `POST /config/importConfig` — generic-выгрузка и
  загрузка таблицы `config` вместе с криптографическими ключами приложения.
  Вместе с ними — кнопки Import/Export в настройках, клиентские функции и
  строки i18n.

- Персистентный каталог выгрузок `/var/lib/hy2xs-admin/export/` и
  файловый helper `util.ExportFile`. Артефакт, который покидает сервер, не
  должен существовать на сервере дольше самого запроса.

- Флаг `purge-v0.sh --keep-hysteria-binary`.

- Мёртвые строки i18n, оставшиеся от H UI: `noHttpsTip`, `defaultPassTip`,
  `hui*`, `useHysteria2Cert`, `invalidWebContext`, `mustBeInteger`.

- `GET /api/config/getConfig` — точечное чтение произвольного ключа таблицы
  `config`. Потребителей у маршрута не было ни одного, а список ключей в этой
  таблице включает `JWT_SECRET`, `PEER_SECRET_KEY` и
  `PEER_SECRET_ENCRYPTION_KEY`. Вместе с ним удалены `dto.ConfigDto`,
  клиентская функция `getConfigApi` и её тип.

- Compatibility-слой аккаунтов предыдущего поколения: сущность
  `entity.LegacyAccount`, миграции `002_migrate_legacy_accounts` и
  `003_archive_legacy_account`, а также мёртвые helpers `listSQLMigrationFiles`
  и `envInt`. HY2XS v1 не мигрирует базу `0.x` ни при каком сценарии, и
  clean-host контракт отказывает ещё до создания базы — живого пути, по
  которому таблица `account` могла бы оказаться в `hy2xs-admin.db`, не
  существует. Номера оставшихся миграций сохранены: перенумерация заставила бы
  их примениться повторно.

  В `docs/14-legacy-cleanup.md` имена предыдущего поколения остаются — там они
  обозначают реальные объекты, которые нужно удалить с сервера. Из остальных
  v1-доков этот словарь убран.

## [1.0.0] — 2026-08-27

Первый релиз линейки `v1`.

> **Обновление с `0.x` не поддерживается.**
> Между `0.x` и `1.0.0` изменились схема конфигурации, тип обфускации
> по умолчанию и контракт выбора версии Hysteria. Сервер, установленный
> из пакета `0.x`, нужно поднимать заново: очистка и установка с нуля.
> Подробности — в разделе «Миграция с 0.x» ниже.

### Добавлено

- **Разрешение версии Hysteria на этапе сборки.** Builder по умолчанию сам
  определяет последний стабильный upstream-релиз, скачивает артефакт,
  вычисляет SHA-256 и замораживает `version` + `url` + `sha256` в metadata
  пакета. Target-сервер по-прежнему скачивает конкретный неизменяемый
  артефакт и никогда не обращается к moving `latest`.
- **Compatibility gate в сборке.** До создания release-пакета builder
  рендерит канонический конфиг HY2XS тем же кодом, что и оркестратор, и
  запускает с ним реальный бинарник Hysteria — для обоих профилей
  обфускации. Несовместимый upstream ломает сборку, а не сервер оператора.
- **Поддержка Gecko-обфускации** (Hysteria 2.9.2+) со сквозной интеграцией:
  оркестратор, шаблон конфига, модель админки, генерация `hysteria2://` URI,
  типы и формы фронтенда.
- **Версия схемы конфигурации** `HY2XS_CONFIG_SCHEMA_VERSION=2`. Пакет
  отказывается работать с конфигурацией неизвестной схемы вместо того,
  чтобы молча применить чужие значения.
- **Современный серверный baseline** в генерируемом конфиге:
  `congestion.type: bbr` + `bbrProfile: standard`,
  `bandwidth.disableLossCompensation: false`,
  `quic.disableStatelessReset: false`, а также
  `maxIdleTimeout`, `maxIncomingStreams`, `disablePathMTUDiscovery`.
- **Модель современной схемы Hysteria в админке**: `obfs.gecko`, `ech`,
  `congestion`, `mimic`, `realm`, `tls.clientCA`,
  `quic.disableStatelessReset`, `bandwidth.disableLossCompensation`,
  `masquerade.proxy.xForwarded`. Поля читаются и отображаются, даже если
  HY2XS не включает их в default-профиль.
- **Тесты оркестратора** (`bun test`): разбор env, рендер конфига,
  семантические инварианты профиля, резолвер upstream-релизов,
  release rollover.
- **E2E-проверка с реальным клиентом Hysteria** — `tools/test/e2e-hysteria.sh`:
  TLS и obfs handshake, HTTP auth (допуск и отказ), TCP и UDP forwarding,
  trafficStats, per-peer accounting, переподключение после перезапуска
  сервера и подключение клиента именно по сгенерированной ссылке.
- **`CHANGELOG.md`** в корне репозитория.

### Изменено

- **Обфускация по умолчанию для новых установок — Gecko.** Salamander
  остаётся полностью поддержанным режимом совместимости и выбирается через
  `HY2XS_HYSTERIA_OBFS_TYPE=salamander`.
- **Gecko использует upstream-defaults `512/1200`** и не выносит размеры
  пакетов в env: официальная URI-схема не умеет их передавать, поэтому
  нестандартные значения сделали бы клиентскую ссылку неполной.
- **Тип обфускации больше не собирается внутри статического YAML.**
  Оркестратор формирует проверенный `obfs`-блок целиком, поэтому
  комбинация вида `type: gecko` рядом с блоком `salamander` структурно
  невозможна.
- **Экспорт конфига Hysteria работает от исходного YAML**, а не от
  типизированной модели: поля, о которых HY2XS ещё не знает, переживают
  выгрузку.
- **Smoke-проверки разбирают YAML** и сверяют его с production-профилем,
  вместо поиска подстрок.
- **Канонический upstream-репозиторий** — `HyNetworks/hysteria`
  (вместо устаревших ссылок на `apernet`).
- **Реестр ACME DNS-провайдеров во фронтенде** приведён к актуальному
  upstream: добавлены `namecheap`, `njalla`, `porkbun`.
- **Дефолты формы Hysteria во фронтенде** отражают baseline HY2XS
  (50/50 Mbps, Let's Encrypt, каталог ACME), а не пример из upstream-доки.
- Сборка запускает тесты оркестратора и админки до упаковки.

### Исправлено

- **`hysteria2://` для Gecko.** Генератор ссылок был завязан на
  `Obfs.Salamander.Password`, поэтому при любой другой обфускации выдавал
  формально корректную, но неработающую ссылку без параметров `obfs`.
- **SNI в клиентской ссылке при файловых сертификатах.** SNI брался только
  из ACME-блока, поэтому при `HY2XS_TLS_MODE=file` уходил пустым. Теперь
  источник — ACME-домен, затем `HY2XS_DOMAIN`, затем `HY2XS_PUBLIC_HOST`;
  IP-адрес в качестве SNI не используется.
- **Утечка секретов в экспорте конфига.** Выгружаемый оператору YAML
  содержал `trafficStats.secret`, `access_token` в auth-URL и пароль
  обфускации. Секреты вырезаются, включая поля, о которых HY2XS ещё
  не знает.
- **Расхождение runtime-конфига с разобранным.** `renderRuntimeEnv`
  печатал тип обфускации и режим auth литералами, игнорируя фактическую
  конфигурацию, — из-за чего запись `/etc/hy2xs/hy2xs.env` могла разойтись
  с тем, что реально применено.
- **Смешение веток `obfs` в UI.** Форма склеивала дефолт с ответом API и
  показывала блок обфускации, которого нет в конфиге сервера.
- **`namedotcom` в списке ACME DNS-провайдеров.** Провайдер удалён из
  Hysteria в 2.11.0; конфигурация с ним больше не запускается.
- **Отсутствие подсказок в форме создания пира.** У полей «Пир»,
  «Комментарий» и «Секрет» не было ни примеров, ни пояснений: оператор не
  мог понять без документации, что секрет необязателен и генерируется
  автоматически.

### Безопасность

- Переход на Hysteria 2.12.2 закрывает исправления, вышедшие после 2.8.2,
  включая обход UDP ACL, возможный OOM через sniff и обход ACL через
  домены с завершающей точкой (2.9.2).
- Экспорт конфига больше не выносит секреты за пределы сервера.

### Миграция с 0.x

Автоматическая миграция не предусмотрена и не планируется.

Порядок перехода:

1. Выпишите с работающего сервера список пиров и их секреты.
2. Очистите сервер: `tools/legacy/purge-v0.sh` или ручная процедура из
   [docs/14-legacy-cleanup.md](docs/14-legacy-cleanup.md).
3. Разверните `1.0.0` на чистом Debian 13 из release-пакета.
4. Заведите пиров заново и раздайте новые клиентские ссылки.

Установщик `1.0.0` обнаружит остатки предыдущей установки на шаге PHASE 0,
откажется работать и **не изменит на сервере ничего**.

Клиентские ссылки `0.x` в любом случае перестанут работать: смена
обфускации — это изменение wire-совместимости.

[Unreleased]: https://git.flamy.studio/prod/HY2XS_flamy/compare/v1.0.0...HEAD
[1.0.0]: https://git.flamy.studio/prod/HY2XS_flamy/releases/tag/v1.0.0