fix(v1): разблокировать сборку, починить жизненный цикл cron и закрыть каналы утечки

Сборка не собиралась: два контракта приёмки роняли её на корректном коде.

verify_api_namespace_contract искал возвращение legacy-пространства имён
через grep по '/hui' и находил router_test.go, который ПЕРЕЧИСЛЯЕТ этот
префикс, чтобы доказать отсутствие маршрута, и сам versions.sh, где строка
стоит в тексте проверки. Падение приходило шестым шагом из четырнадцати, до
резолва Hysteria. За ним прятался второй такой же: проверка транзакционности
импорта пиров брала файл от начала applyPeerImportEntry и до конца, захватывая
объявленные ниже ExistPeerName и UpdatePeerLastConnectionAt.

Обе проверки теперь смотрят на код, а не на упоминания: добавлены помощники
code_without_comments и code_mentions_in, а отсутствие legacy-маршрута
доказывает тест на таблице маршрутов собранного роутера.

Планировщик стал собственностью процесса. InitCron вызывался из runServer и
на каждом вызове создавал новый cron.New(), не сохраняя ссылку; cron.Stop()
не вызывался нигде. Смена RESET_TRAFFIC_CRON выполняла StopServer(), точка
входа крутила for { runServer() } — и каждая правка добавляла целый
дублирующий набор джоб, а старое расписание сброса продолжало работать.
Фиксированные джобы регистрируются один раз, расписание переносится на месте
по EntryID, HTTP-сервер не трогается. Добавлено штатное завершение по SIGTERM.

Выражение проверяется до записи в базу тем же парсером (cron.ParseStandard),
которым его разбирает планировщик: раньше невалидная строка сохранялась, API
отвечал успехом, а сброс трафика молча исчезал.

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

Удалены четыре ключа таблицы config без единого потребителя: HYSTERIA2_ENABLE,
HYSTERIA2_CONFIG (второй источник истины, читался первым), HYSTERIA2_TRAFFIC_TIME
и HYSTERIA2_CONFIG_REMARK. Имя профиля в share URI выводится из имени пира.

Безопасность:
- bootstrap-пароль администратора больше не генерируется и не пишется в журнал,
  который отдаётся кнопкой выгрузки; отсутствие env — отказ старта;
- собственный журнал админки санитизируется наравне с чужим;
- golang-jwt/jwt v3 -> v5: GO-2025-3553 не имеет исправленной версии в v3 и
  достижима с неаутентифицированного запроса; набор алгоритмов подписи
  зафиксирован через WithValidMethods;
- удалён вход по несолёному SHA-224 из предыдущего поколения;
- убран modulo bias в util.RandomString — единственном генераторе секретов;
- пир установщика защищён во всех путях записи, а не только в импорте;
- удалена латентная паника в service.GetToken и недостижимая ветка GetAdminInfo,
  проверявшая меньше, чем middleware.

Toolchain: Go 1.21.13 -> 1.26.7, Node 20.19.0 (EOL) -> 24.20.0. На прежнем
графе govulncheck находил 21 вызываемую уязвимость, 17 из них в stdlib,
попадающей в production-бинарь. Сейчас — ноль. Добавлен обязательный шаг
проверки зависимостей (govulncheck + pnpm audit) с записью результата в
metadata пакета.
This commit is contained in:
2026-08-29 21:37:38 +05:00
parent 672d455467
commit b99be7d514
50 changed files with 3907 additions and 1622 deletions
+148 -5
View File
@@ -133,6 +133,16 @@ Hysteria обращается к машинному endpoint'у как
сохраняет host, port и path — диагностика от него не страдает. Тот же проход
применяется к `journal-*.log` внутри diagnostics-бандла оркестратора.
**Собственный журнал админки проходит тот же санитайз.** Раньше не проходил: он
отдавался сырым файлом через `c.File(constant.SystemLogPath)` и показывался во
вкладке без обработки. Асимметрия «чужому журналу не доверяем, своему доверяем»
ничем не обоснована — файл в обоих случаях покидает сервер и пересылается в
переписке, — и цена у неё была известна поимённо: пока bootstrap-пароль
администратора печатался в лог warning'ом, обычная кнопка выгрузки отдавала его
открытым текстом. Сам warning убран (см. ниже), но защита стоит и на выходе:
следующий неосторожный `logrus.Warnf("token=%s", …)` не превратит выгрузку
журнала в канал утечки.
## Импорт и экспорт
| Операция | Статус |
@@ -165,10 +175,8 @@ API: `getConfig` и `listConfig` принимали произвольный к
| Ключ | Чтение | Запись |
| --- | --- | --- |
| `HYSTERIA2_TRAFFIC_TIME` | да | да |
| `RESET_TRAFFIC_CRON` | да | да |
| `HYSTERIA2_CONFIG_REMARK` | да | нет |
| `HYSTERIA2_ENABLE`, `HYSTERIA2_CONFIG`, `HYSTERIA2_TRAFFIC_STATS_SECRET` | нет | нет, владелец — оркестратор |
| `HYSTERIA2_TRAFFIC_STATS_SECRET` | нет | нет, владелец — оркестратор |
| `JWT_SECRET`, `PEER_SECRET_KEY`, `PEER_SECRET_ENCRYPTION_KEY` | нет | нет |
| любой другой | нет | нет |
@@ -178,8 +186,53 @@ Denylist требует, чтобы автор каждого нового кл
по умолчанию не зависит от внимательности.
Маршрут `GET /api/config/getConfig` **удалён целиком**: потребителей у него не
было ни одного, а фильтр на неиспользуемой двери — это по-прежнему дверь. Право
записи `HYSTERIA2_CONFIG_REMARK` тоже убрано: панель его только отображает.
было ни одного, а фильтр на неиспользуемой двери — это по-прежнему дверь.
### Мёртвое состояние в таблице `config` удалено
Четыре ключа предыдущего поколения к v1 перестали чем-либо управлять и удалены
вместе со строками в базе (миграция `006_drop_dead_config_keys`):
| Ключ | Что с ним было не так |
| --- | --- |
| `HYSTERIA2_ENABLE` | жизненным циклом Hysteria владеет systemd; единственным потребителем ключа была строка в журнале |
| `HYSTERIA2_CONFIG` | второй источник истины рядом с `/etc/hysteria/config.yaml`, причём читался **первым**: значение, попавшее в базу в обход продукта, молча становилось тем, что панель показывает и из чего генерирует ссылки |
| `HYSTERIA2_TRAFFIC_TIME` | настройка «период учёта трафика» без единого потребителя в рантайме: интервал сбора метрик задан в коде |
| `HYSTERIA2_CONFIG_REMARK` | пустая read-only строка, которую никто никогда не записывал |
Настоящую замену получил только последний: имя профиля в клиентской ссылке
теперь выводится из **имени пира**, а при его отсутствии — из публичного хоста.
Это то различие, которое пользователю и нужно видеть в списке серверов, и оно не
требует ни одной дополнительной настройки.
После очистки панель владеет ровно одной настройкой — `RESET_TRAFFIC_CRON`, — а
всё остальное в таблице является внутренними секретами.
### Расписание сброса трафика: планировщик принадлежит процессу
Смена `RESET_TRAFFIC_CRON` **не перезапускает** HTTP-сервер.
Раньше перезапускала: обработчик вызывал `StopServer()`, точка входа крутила
`for { runServer() }` и поднимала сервис заново, чтобы новый планировщик прочитал
настройку из базы. При этом `InitCron()` на каждом вызове создавал новый
`cron.New()` и нигде не сохранял ссылку, а `cron.Stop()` не вызывался нигде.
Итог: каждая правка расписания добавляла **целый дублирующий набор джоб**, а
старое расписание сброса продолжало работать. После двух правок на процессе
висели три планировщика и три разных расписания одновременно.
Теперь фиксированные джобы регистрируются один раз за жизнь процесса, а
расписание сброса переносится на месте по своему `EntryID`.
Выражение проверяется **до записи в базу** тем же парсером
(`cron.ParseStandard`), которым его потом разбирает планировщик. Невалидное
значение — отказ `4xx`, база не меняется. Раньше строка сохранялась, API отвечал
успехом, а сброс трафика молча исчезал до следующего чтения журнала.
Пустое значение легально и означает «автоматический сброс выключен».
Сервис завершается штатно по `SIGTERM`: сначала останавливается планировщик и
дожидаются запущенные джобы, затем закрывается SQLite. Обратный порядок означал
бы работу джоб с уже закрытым соединением при каждом `systemctl restart`.
Ключи оркестратора отклоняются отдельным сообщением, называющим владельца, —
«этим значением владеет оркестратор» это другой ответ, чем «такого ключа нет»,
@@ -191,6 +244,23 @@ Denylist требует, чтобы автор каждого нового кл
секреты пиров на диске, накапливающиеся с каждым нажатием кнопки. Каталога
`export/` больше не существует.
### Партия настроек применяется целиком или не применяется вовсе
`POST /api/config/updateConfigs` выполняется в три прохода:
1. проверка партии целиком — права на ключ, дубликаты ключей, значения;
2. одна транзакция базы;
3. применение к рантайму.
Раньше проходов не было: цикл проверял очередной элемент и тут же его записывал.
Партия «разрешённый ключ + запрещённый» применяла первый и возвращала ошибку на
втором — оператор получал отказ на запрос, который систему уже изменил.
Тест на этот случай существовал, но ставил запрещённый ключ **первым** и не
смотрел в базу — поймать частичное применение он был неспособен по построению.
Сейчас разрешённый ключ идёт первым, запрещённый вторым, а состояние базы
проверяется явно: `TestUpdateConfigsRefusesWholeBatchWhenLaterKeyIsForbidden`.
### Экспорт пиров: два режима, а не флаг
| Кнопка | Запрос | Что внутри |
@@ -380,6 +450,72 @@ upstream выберет для нового секрета. Список мар
- `HY2XS_ADMIN_DATA_DIR`
- `HY2XS_ADMIN_LOG_DIR`
## Учётные данные и аутентификация
### Bootstrap-учётные данные приходят от оркестратора
Первая учётная запись администратора создаётся из `HY2XS_ADMIN_INITIAL_PASSWORD`,
пир установщика — из `HY2XS_ADMIN_CON_PASS`. Оба значения задаёт оркестратор
через `/etc/hy2xs/hy2xs.env`, а копию кладёт в
`/etc/hy2xs/bootstrap-admin.secret`.
Если переменной нет, а создавать учётную запись нужно, админка **отказывает в
старте** с сообщением, называющим причину и способ починки.
Раньше она в этом случае придумывала пароль сама и печатала его двумя
`logrus.Warnf` — открытым текстом в `/var/log/hy2xs/hy2xs-admin.log`, то есть в
файл, который отдаётся кнопкой выгрузки и попадает в diagnostics-бандл. Помимо
утечки, у такого пароля была вторая проблема: его не знал никто, кроме журнала.
Попадание в эту ветку означает не «нужно что-то придумать», а повреждённый
контракт запуска, и реакция на него должна быть громкой.
Для пира установщика цена ошибки ещё конкретнее: его секрет продублирован в
`bootstrap-admin.secret`, откуда его читает проверка machine-auth в smoke
оркестратора. Придуманный админкой секрет разошёлся бы с файлом, и проверка
подключения провалилась бы на корректном во всём остальном сервере.
Порядок проверок при этом такой: сначала выясняется, нужно ли вообще создавать
запись, и только потом требуется переменная. Перезапуск уже установленного
сервиса без неё работает штатно.
### Пир установщика защищён во всех путях записи
`bootstrap-admin-peer` нельзя переименовать, переподписать или занять его имя
чужим пиром — ни импортом, ни через обычные формы панели. Раньше проверка стояла
только в импорте, то есть ровно то, ради чего она существует, делалось через
интерфейс.
Удаление и отключение при этом **разрешены**: после установки это обычный
действующий доступ, секрет которого лежит ещё и в файле на диске, и оператор
обязан иметь возможность его отозвать. В отличие от смены секрета, удаление не
создаёт расхождения между базой и файлом — пира просто нет, и это видно в списке.
### Токены и пароли
Токены выписываются и проверяются `golang-jwt/jwt/v5`. Переход с v3 —
не косметика: у `github.com/golang-jwt/jwt` v3.2.2 есть GO-2025-3553, у которой
**нет исправленной версии в ветке v3** (`Fixed in: N/A`), а уязвимый код
достигается из разбора токена, то есть с неаутентифицированного запроса.
Обновлять было нечего — лечится только сменой мажорной ветки.
Заодно закрыт тихий недостаток прежней реализации: `keyfunc` возвращал ключ,
**не проверяя алгоритм подписи**, то есть набор допустимых алгоритмов
фактически задавал сам токен. Сейчас разбор ограничен `jwt.WithValidMethods`,
проверяются `issuer` и обязательное наличие срока жизни, а пустой `JWT_SECRET`
считается повреждённым состоянием, а не ключом нулевой длины.
Пароли администратора хранятся ровно в одном формате — bcrypt. Ветка сравнения
с несолёным SHA-224 (формат предыдущего поколения) удалена: в v1 такой хеш не
может появиться — миграции таблицы `account` удалены, установка возможна только
на чистый хост, а конфигурация 0.x отклоняется по `HY2XS_CONFIG_SCHEMA_VERSION`.
Compatibility-ветка пережила слой совместимости, ради которого существовала, и
осталась запасным путём проверки пароля слабым алгоритмом в обработчике логина.
Все секреты продукта генерируются одним примитивом `util.RandomString` с
отбраковкой (rejection sampling): прежняя реализация брала остаток байта от
деления на длину алфавита, из-за чего первые восемь символов алфавита выпадали
примерно на четверть чаще остальных.
## Инварианты
Схема считается корректной, если:
@@ -394,3 +530,10 @@ upstream выберет для нового секрета. Список мар
8. экспорт конфига сохраняет неизвестные upstream-поля
9. экспорт конфига не содержит секретов
10. сгенерированная `hysteria2://` ссылка содержит фактический тип обфускации, и совместимый клиент подключается по ней напрямую
11. планировщик существует в единственном экземпляре на процесс, а смена расписания не перезапускает HTTP-сервер
12. значение настройки проверяется до записи в базу тем же кодом, который его потом исполняет
13. партия настроек применяется целиком или не применяется вовсе
14. в таблице `config` нет ключей без потребителя
15. bootstrap-учётные данные приходят от оркестратора и никогда не генерируются и не логируются админкой
16. любой журнал, покидающий сервер, проходит санитайз
17. пароль администратора хранится ровно в одном формате — bcrypt