# Server Hysteria2 baseline

## Цель документа

Зафиксировать правила для серверного слоя Hysteria2 в модели, где UI поставляется вместе с проектом, а Hysteria берётся из official upstream во время установки.

## Роль Hysteria2

Hysteria2 — основной транспортный компонент сервера.  
Он не форкается и не поставляется как часть UI-форка.

## Source policy

Базовое правило:
- Hysteria2 скачивается **во время установки**
- источник — **официальный upstream**
- install layer не должен подменять собой upstream-дистрибуцию Hysteria2

## Версионная политика

С учётом выбранной модели «берём свежее из upstream» фиксируется такая практика:

- по умолчанию install layer тянет **свежий upstream release / install source**
- фактически установленная версия обязательно записывается в `post-install.env`
- бинарник Hysteria2 устанавливается только на этапе `install`
- версия, URL и SHA256 фиксируются в metadata install package
- `reconfigure` не обновляет и не откатывает бинарник Hysteria2

## Платформа

- ОС: только Debian 13
- init/system management: systemd
- сетевой фильтр: nftables
- архитектура baseline: x86_64/amd64

## Listen и сеть

### Listen
- только IPv4
- формат: `0.0.0.0:<PORT>`

### Порт
- один фиксированный UDP-порт
- этот порт должен совпадать в:
  - server config
  - firewall rules
  - `post-install.env`

## Обфускация

В baseline включается:
- `obfs.type: salamander`
- `obfs.password`

Правила:
- пароль должен быть сильным
- пароль должен фиксироваться в конфигурационном контуре
- значение должно быть доступно оператору через runtime config и `post-install.env`

## TLS

Требования:
- production default: `acme`
- поддерживаемые режимы: `acme | file | self_signed_dev`
- `self_signed_dev` только для dev/lab и только при явном `HY2XS_ALLOW_SELF_SIGNED_DEV=true`
- корректный `server_name` / SNI на клиентах
- одна понятная TLS policy
- без смешивания нескольких несовместимых схем по умолчанию

Инварианты:
- `acme` -> только `acme` block в конфиге;
- `acme` block обязан содержать `type: http|tls` из runtime env (`HY2XS_ACME_TYPE`);
- `HY2XS_ACME_TYPE=dns` в production-профиле запрещён до отдельной реализации;
- `HY2XS_HYSTERIA_AUTH_MODE` зафиксирован в `http` и валидируется fail-fast;
- `HY2XS_HYSTERIA_OBFS_TYPE` зафиксирован в `salamander` и валидируется fail-fast;
- блок `masquerade` в baseline не задаётся (допустимо, но приводит к `404 Not Found` на обычный HTTP трафик);
- `file` -> только `tls.cert`/`tls.key` block;
- `self_signed_dev` -> только dev сценарии.

## Auth policy

Для baseline выбирается одна предсказуемая auth-модель.

Правила:
- install flow должен оставить рабочий auth state
- bootstrap auth material должен быть либо передан оператором, либо безопасно сгенерирован
- дальнейшая модель выдачи доступа пользователям не фиксируется в этом пакете docs

## Bandwidth и congestion

Серверная baseline policy:
- `bandwidth.up = 50 mbps`
- `bandwidth.down = 50 mbps`
- `ignoreClientBandwidth = false`

Важно:
- эти параметры сами по себе не исчерпывают speed policy
- корректный лимит ожидается только в паре с совместимым клиентским конфигом

## Рекомендуемые пути

- `/etc/hysteria/config.yaml`
- `/var/lib/hysteria/`
- `/etc/hy2xs/hy2xs.env`
- `/etc/hysteria/post-install.env`

## Серверные инварианты

После установки должно быть верно:

1. Hysteria2 получена из official upstream
2. фактическая версия отражена в `post-install.env`
3. конфиг валиден
4. сервис стартует через systemd
5. нужный UDP-порт реально слушается
6. тестовый совместимый клиент может подключиться
7. bundled UI работает поверх актуального состояния сервера
8. `trafficStats.secret` отдельный от `JWT_SECRET`
9. IPv6 listen не используется
10. публичные клиентские endpoint/URL берутся из `HY2XS_PUBLIC_HOST` + `HY2XS_PUBLIC_PORT`, а не из `listen`/request-host