From 357daa8915b8479c92ec2eadfc370c80aa273a97 Mon Sep 17 00:00:00 2001 From: DizelBadCoder Date: Wed, 14 Oct 2026 01:40:14 +0300 Subject: [PATCH] Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions --- .dockerignore | 11 + .env.example | 19 + .gitea/workflows/release.yaml | 105 ++++++ .gitignore | 10 + DOMAINS.md | 81 ++++ Dockerfile | 13 + README.md | 341 +++++++++++++++++ REGISTRY.md | 246 ++++++++++++ SSH.md | 175 +++++++++ VERSION | 1 + WEB.md | 157 ++++++++ bootstrap.py | 58 +++ ci/check_compose.py | 53 +++ ci/image_metadata.py | 49 +++ ci/smoke_image.sh | 56 +++ ci/smoke_ui.py | 61 +++ compose.registry.yaml | 150 ++++++++ compose.yaml | 139 +++++++ config/services.yaml | 50 +++ homegate.py | 692 ++++++++++++++++++++++++++++++++++ homegate_ui.py | 275 ++++++++++++++ requirements.txt | 9 + run-local.sh | 25 ++ setup.sh | 47 +++ sync_ssh.py | 222 +++++++++++ tests/test_distribution.py | 112 ++++++ tests/test_homegate.py | 295 +++++++++++++++ tests/test_ssh_and_zones.py | 258 +++++++++++++ tests/test_ui.py | 182 +++++++++ ui/dist/app.js | 104 +++++ ui/dist/favicon.svg | 1 + ui/dist/index.html | 34 ++ ui/dist/style.css | 1 + 33 files changed, 4032 insertions(+) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .gitea/workflows/release.yaml create mode 100644 .gitignore create mode 100644 DOMAINS.md create mode 100644 Dockerfile create mode 100644 README.md create mode 100644 REGISTRY.md create mode 100644 SSH.md create mode 100644 VERSION create mode 100644 WEB.md create mode 100644 bootstrap.py create mode 100644 ci/check_compose.py create mode 100644 ci/image_metadata.py create mode 100755 ci/smoke_image.sh create mode 100644 ci/smoke_ui.py create mode 100644 compose.registry.yaml create mode 100644 compose.yaml create mode 100644 config/services.yaml create mode 100644 homegate.py create mode 100644 homegate_ui.py create mode 100644 requirements.txt create mode 100755 run-local.sh create mode 100755 setup.sh create mode 100644 sync_ssh.py create mode 100644 tests/test_distribution.py create mode 100644 tests/test_homegate.py create mode 100644 tests/test_ssh_and_zones.py create mode 100644 tests/test_ui.py create mode 100644 ui/dist/app.js create mode 100644 ui/dist/favicon.svg create mode 100644 ui/dist/index.html create mode 100644 ui/dist/style.css diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..44065ed --- /dev/null +++ b/.dockerignore @@ -0,0 +1,11 @@ +* +!Dockerfile +!requirements.txt +!homegate.py +!sync_ssh.py +!homegate_ui.py +!ui/ +!ui/dist/ +!ui/dist/** +!bootstrap.py +!VERSION diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..1da5a45 --- /dev/null +++ b/.env.example @@ -0,0 +1,19 @@ +# IP/port of EXISTING Nginx Proxy Manager management UI, without /api. +NPM_URL=http://192.168.0.10:81 +NPM_IDENTITY=admin@example.com +# Pi-hole 6 web interface, without /admin or /api; not DNS port 53. +PIHOLE_URL=http://192.168.0.2 +# LAN IP of the Docker HOST running Homegate (may differ from proxy_ip/NPM). +# SSH export is anonymous within allowed_networks; never use 0.0.0.0 here. +SSH_BIND_IP=192.168.0.10 +SSH_PORT=8099 +# Management panel: password protected and LAN-only. Must match the browser URL. +UI_BIND_IP=192.168.0.10 +UI_PORT=8098 +UI_ORIGIN=http://192.168.0.10:8098 +# For HTTPS management APIs with a private CA, copy its PEM bundle into config/ +# and set API_CA_BUNDLE=/config/management-ca.pem +API_CA_BUNDLE= +# Written by setup.sh to match ownership of secrets/ and state/ on Linux. +LOCAL_UID=1000 +LOCAL_GID=1000 diff --git a/.gitea/workflows/release.yaml b/.gitea/workflows/release.yaml new file mode 100644 index 0000000..58f3370 --- /dev/null +++ b/.gitea/workflows/release.yaml @@ -0,0 +1,105 @@ +name: Test and publish Homegate +"on": + push: + branches: ['**'] + tags: ['v*'] + pull_request: + +# Use a dedicated Linux runner labelled homegate:host; see REGISTRY.md. +permissions: + contents: read + +jobs: + checks: + runs-on: homegate + steps: + - name: Checkout + uses: https://github.com/actions/checkout@v4 + with: + github-server-url: ${{ gitea.server_url }} + token: ${{ secrets.GITEA_TOKEN }} + persist-credentials: false + - name: Python environment + shell: bash + run: | + set -euo pipefail + test_env="$(mktemp -d "$RUNNER_TEMP/homegate-python.XXXXXX")" + printf 'TEST_PYTHON=%s/bin/python\n' "$test_env" >> "$GITHUB_ENV" + printf 'TEST_ENV=%s\n' "$test_env" >> "$GITHUB_ENV" + python3 -m venv "$test_env" + "$test_env/bin/python" -m pip install -r requirements.txt + - name: Unit and HTTP tests + run: '"$TEST_PYTHON" -m unittest discover -s tests -v' + - name: JavaScript and shell syntax + run: | + node --check ui/dist/app.js + for script in setup.sh run-local.sh ci/smoke_image.sh; do sh -n "$script"; done + - name: Compose contracts + env: + PYTHONPATH: . + run: '"$TEST_PYTHON" ci/check_compose.py' + - name: Build and smoke-test runtime image + env: + CI_REVISION: ${{ gitea.sha }} + run: | + set -eu + test_image="homegate-ci:$CI_REVISION-$$" + trap 'docker image rm "$test_image" >/dev/null 2>&1 || true' EXIT + docker build --build-arg VERSION="$(cat VERSION)" --tag "$test_image" . + sh ci/smoke_image.sh "$test_image" + - name: Clean Python environment + if: always() + shell: bash + run: | + if [ -n "${TEST_ENV:-}" ]; then rm -rf -- "$TEST_ENV"; fi + + publish: + needs: checks + if: gitea.event_name == 'push' && startsWith(gitea.ref, 'refs/tags/v') + runs-on: homegate + env: + DOCKER_BUILD_SUMMARY: "false" + DOCKER_BUILD_RECORD_UPLOAD: "false" + steps: + - name: Checkout release + uses: https://github.com/actions/checkout@v4 + with: + github-server-url: ${{ gitea.server_url }} + token: ${{ secrets.GITEA_TOKEN }} + persist-credentials: false + - name: Validate release identity + id: image + env: + CI_SERVER_URL: ${{ gitea.server_url }} + CI_REPOSITORY: ${{ gitea.repository }} + CI_REF: ${{ gitea.ref }} + CI_REVISION: ${{ gitea.sha }} + REGISTRY: ${{ vars.REGISTRY }} + run: python3 ci/image_metadata.py + - name: Configure cross-platform emulation + uses: https://github.com/docker/setup-qemu-action@v3 + with: + platforms: amd64,arm64 + - name: Configure Buildx + uses: https://github.com/docker/setup-buildx-action@v3 + - name: Log in to Gitea Container Registry + uses: https://github.com/docker/login-action@v3 + with: + registry: ${{ steps.image.outputs.registry }} + username: ${{ secrets.REGISTRY_USERNAME }} + password: ${{ secrets.REGISTRY_TOKEN }} + - name: Publish AMD64 and ARM64 image + uses: https://github.com/docker/build-push-action@v6 + with: + context: . + platforms: linux/amd64,linux/arm64 + push: true + build-args: | + VERSION=${{ steps.image.outputs.version }} + tags: | + ${{ steps.image.outputs.image }}:${{ steps.image.outputs.version }} + ${{ steps.image.outputs.image }}:sha-${{ steps.image.outputs.revision }} + labels: | + org.opencontainers.image.source=${{ steps.image.outputs.source }} + org.opencontainers.image.revision=${{ steps.image.outputs.revision }} + provenance: false diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b9be4db --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +.env +state/ +secrets/ +control/ +config/backups/ +config/.ui-config.lock +__pycache__/ +*.pyc +.venv/ +.local/ diff --git a/DOMAINS.md b/DOMAINS.md new file mode 100644 index 0000000..8575df9 --- /dev/null +++ b/DOMAINS.md @@ -0,0 +1,81 @@ +# Кастомные доменные зоны + +До первого запуска задайте все нужные зоны в `config/services.yaml`: + +```yaml +domain_zones: + - home + - home.arpa + - lab.internal + - dev.example.net +``` + +После этого допустимы, например, `pve.home`, `nas.home.arpa`, `grafana.lab.internal` +и `git.dev.example.net`. Поддерживаются поддомены любой глубины и apex зоны с точкой, +например `dev.example.net`. Wildcard-сертификаты и wildcard DNS не создаются; +каждый веб-сервис имеет отдельное имя, DNS-запись и сертификат. + +Если `domain_zones` отсутствует в старом конфиге, сохраняются прежние `home` и `home.arpa`. +Начальная/конечная точка зоны и регистр нормализуются; имена самих сервисов должны быть +в нижнем регистре. IDN задавайте в ASCII/punycode. Проверяются границы DNS-меток: +зона `home` не разрешает `pve.evilhome`. + +При использовании реального домена выбирайте принадлежащую вам зону. Записи остаются +локальными в Pi-hole; регистрации домена или публикации публичного DNS Homegate не делает. +Публичный сертификат автоматически не появляется: все зоны обслуживает локальный CA. +Для домашнего использования предпочтительна `home.arpa` по +[RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html). +Избегайте `.local`, зарезервированной для [mDNS](https://www.rfc-editor.org/rfc/rfc6762.html#section-3) +и обрабатываемой клиентами иначе, чем обычный DNS. + +Новый корневой CA содержит ограничения `NameConstraints` для зон первого запуска. +Добавление нового хоста или дочерней зоны внутри уже разрешённого суффикса не меняет CA. +Удаление зоны сужает политику выпуска Homegate, но не отзывает старые сертификаты и +не меняет доверие уже установленного корня. Удаляемые из зоны маршруты нужно также +убрать из YAML; правила сохранения/ручного удаления NPM-объектов описаны в README. + +## Добавление зоны за пределами существующего CA + +Если CA уже создан и новая зона **вне его ограничений**, Homegate не выпускает для неё +заведомо недоверенный сертификат. Смена корневого сертификата никогда не запускается +автоматически. Для расширения выполните явную миграцию: + +```sh +# Сначала измените domain_zones и маршруты в config/services.yaml. +docker compose stop homegate +docker compose run --rm homegate rotate-ca +# Скопируйте новый state/root-ca.crt на клиенты и установите доверие. +docker compose up -d homegate +``` + +`rotate-ca` сохраняет прежние `ca.json` и `root-ca.crt` в `state/ca-history/`, создаёт +новый ключ/корень и сохраняет `registry.json`, поэтому объекты NPM остаются теми же. +При следующем запуске сертификаты активных маршрутов перевыпускаются под новым корнем +и nginx перечитывает их. Установите новый корень на клиенты перед возобновлением контроллера; +до этого NPM продолжает отдавать прежние сертификаты. После перехода удалите доверие к +старому CA. Для удалённых из YAML маршрутов сертификаты не перевыпускаются автоматически. +Резервная копия CA содержит приватный ключ и должна оставаться защищённой. + +Для установки, которая ещё не запускалась, достаточно изменить `domain_zones` до +первого `docker compose up`: менять CA и устанавливать его второй раз не потребуется. + +## Обновление с 0.1 + +Замените исходники, Dockerfile и Compose. Сохраните свои `.env`, `config/`, `state/` +и `secrets/`; не заменяйте настроенный YAML примером из архива. Добавьте в `.env`: + +```dotenv +SSH_BIND_IP=192.168.0.10 +SSH_PORT=8099 +``` + +Замените IP на LAN-IP Docker-хоста Homegate и выполните: + +```sh +docker compose up -d --build +``` + +Новые зоны добавляйте намеренно. Старый конфиг без `domain_zones` продолжает работать. +Существующий CA 0.1 разрешает `home` и `home.arpa`; для `lab.internal` или иной новой +зоны примените миграцию выше. Настройки SSH в существующих сервисах добавляются отдельно +по [инструкции](SSH.md). diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..01b339d --- /dev/null +++ b/Dockerfile @@ -0,0 +1,13 @@ +FROM python:3.13-slim-bookworm +WORKDIR /app +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt +COPY homegate.py sync_ssh.py homegate_ui.py bootstrap.py VERSION . +COPY ui/dist ./ui/dist +ARG VERSION=0.4.0 +LABEL org.opencontainers.image.title="Homegate" \ + org.opencontainers.image.description="LAN DNS, HTTPS and SSH management for Pi-hole and NPM" \ + org.opencontainers.image.version=$VERSION +USER 1000:1000 +ENTRYPOINT ["python", "/app/homegate.py"] +CMD ["run"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..4b75667 --- /dev/null +++ b/README.md @@ -0,0 +1,341 @@ +# Homegate 0.4 + +Дополнение к **существующим Pi-hole и Nginx Proxy Manager** для домашней сети: + +```text +https://pve.home → NPM:443 → https://192.168.0.137:8006 +``` + +Вы описываете сервисы в `config/services.yaml`. Homegate создаёт локальные DNS-записи, +сертификаты и Proxy Hosts, затем поддерживает их актуальными. Развёртывание — Docker Compose. +Веб-панель Homegate управляет сервисами, доменными зонами, SSH и настройками сети. +Отдельный контейнер публикует SSH-конфиг без авторизации для устройств домашней подсети. + +Новое в 0.4: [один Compose-файл, готовый образ и Gitea Actions](REGISTRY.md). +Также доступны: [веб-панель и локальный запуск](WEB.md), [SSH-конфиг и скрипт для ПК](SSH.md), [кастомные доменные зоны и миграция CA](DOMAINS.md). + +**Для HTTPS без предупреждений нужно один раз установить `root-ca.crt` на каждое +клиентское устройство.** Для внутренних имён `.home` публичный сертификат Let's Encrypt +не подходит. Установка корневого сертификата на сервер не устанавливает доверие на +телефонах и компьютерах. Доверие к локальному CA описано в +[документации Let's Encrypt](https://letsencrypt.org/docs/certificates-for-localhost/). + +Зоны настраиваются списком `domain_zones`: например `home`, `home.arpa`, `lab.internal`, +`lab.example.net`. Поддерживаются несколько зон одновременно и несколько уровней +поддоменов; каждому имени выпускается отдельный сертификат. В примере сохранено `pve.home`. +Для новой домашней зоны стандарт рекомендует `home.arpa`: +[RFC 8375](https://www.rfc-editor.org/rfc/rfc8375.html). + +## Как это работает + +```mermaid +flowchart LR + Browser[Браузер с доверенным Root CA] -->|DNS: pve.home| PiHole[Pi-hole] + PiHole -->|192.168.0.10 — адрес NPM| Browser + Browser -->|HTTPS :443| NPM[Nginx Proxy Manager] + NPM -->|HTTPS :8006| PVE[Proxmox 192.168.0.137] + Controller[Homegate] -->|DNS API| PiHole + Controller -->|Сертификаты и Proxy Hosts| NPM +``` + +DNS указывает на **NPM**, а не на Proxmox. Порт и протокол целевой VM выбирает NPM +по имени из запроса. Это обратный прокси, адрес в браузере остаётся `https://pve.home`. + +Контроллер Homegate не публикует портов, не требует Docker socket и не запускает второй DNS или nginx. +Сервис `ssh-export` публикует HTTP-порт `8099` на явно заданном LAN-IP и проверяет +клиента по `allowed_networks`. Он не имеет доступа к `state/` и паролям API. +Он может работать на отдельной Linux VM с доступом к API вашего Pi-hole и NPM. +Образ пока не опубликован. `compose.yaml` собирает его из исходников; +`compose.registry.yaml` скачивает готовый образ после публикации через Gitea Actions. +Для запуска только по одному файлу, без исходников и setup.sh, см. [REGISTRY.md](REGISTRY.md). + +## Требования и границы проверки + +- Linux-хост с Docker Engine и Docker Compose v2+; архитектура amd64 или arm64. +- Существующий NPM 2.x; интеграция сверена с исходниками **2.16.0**. Для других версий + сначала проверьте запуск на одном имени. API NPM может меняться. +- **Pi-hole 6** для автоматического DNS. Для Pi-hole 5 или неподдерживаемого API + используйте `dns_mode: manual` и добавьте записи через интерфейс Pi-hole. +- Стабильные адреса Pi-hole, NPM и VM; NPM должен принимать HTTPS на LAN-порту 443. +- Все клиенты используют Pi-hole как DNS. Публичный «резервный DNS», browser DoH, + Android Private DNS и VPN могут обходить локальный DNS. В IPv6 настройте DNS через + RA/DHCPv6 тоже. Используйте второй локальный Pi-hole для резервирования. +- Если Pi-hole и NPM на одном IP, их web-порты должны различаться: например NPM + `80/81/443`, Pi-hole web `8080`, DNS `53`. Homegate этот конфликт автоматически не исправляет. + +Проверены Compose-конфигурация, shell-синтаксис и 55 тестов: сертификаты, настоящее TLS-рукопожатие +в стандартных и кастомных зонах, продление, повторный запуск, конфликты, ошибки API, +смена CA, HTTP-обработчик выгрузки, LAN ACL и отказ опасных SSH-директив. +Подключение дополнительного файла также проверено настоящим `ssh -G` с сохранением личных настроек. +HTTP API в тестах имитируются по официальным контрактам. **Запуск образа, реальные API NPM/Pi-hole, +HTTPS-сервисы и noVNC на вашем сервере ещё не проверены:** локальная служба Docker при подготовке не работала. + +## Быстрый запуск из исходников + +Запуск готового образа описан отдельно в [REGISTRY.md](REGISTRY.md). + +Распакуйте каталог `homegate` на сервере и перейдите в него. Команды ниже выполняются из этого каталога. + +### 1. Подготовьте конфигурацию и пароли + +```sh +sh setup.sh +``` + +Скрипт создаёт `.env`, `secrets/`, `state/` и `control/`, запрашивает пароли скрытым вводом, +записывает UID/GID текущего пользователя. Он не подключается к вашему homelab. +Для NPM используйте учётную запись с правами управления Proxy Hosts и сертификатами; +администратор имеет нужные права. В `NPM_IDENTITY` укажите её email. + +Измените `.env`; адреса `.10` и `.2` ниже — **примеры**, замените их своими: + +```dotenv +NPM_URL=http://192.168.0.10:81 +NPM_IDENTITY=admin@example.com +PIHOLE_URL=http://192.168.0.2 +SSH_BIND_IP=192.168.0.10 +SSH_PORT=8099 +UI_BIND_IP=192.168.0.10 +UI_PORT=8098 +UI_ORIGIN=http://192.168.0.10:8098 +``` + +`SSH_BIND_IP` — LAN-IP Docker-хоста Homegate, который может отличаться от IP NPM. +`NPM_URL` и `PIHOLE_URL` — адреса административных интерфейсов, **без `/api` и `/admin`**. Если Pi-hole web +на порту 8080, укажите `http://192.168.0.2:8080`. `localhost` внутри контейнера означает +сам Homegate. Для управления через HTTPS скопируйте доверенный PEM CA bundle в `config/` +и задайте `API_CA_BUNDLE=/config/management-ca.pem`. Проверка TLS у API всегда включена. +HTTP передаёт пароли и сертификаты без шифрования; используйте его только внутри доверенной +сети управления или общей закрытой Docker-сети. Для изолированной Docker-сети добавьте её +как external network в Compose и используйте имена контейнеров. + +Для **Pi-hole application password** нужно разрешение на изменение конфигурации. +В существующий Compose Pi-hole добавьте: + +```yaml +environment: + FTLCONF_webserver_api_app_sudo: "true" +``` + +Затем пересоздайте только сервис Pi-hole из его собственного Compose-проекта. +Альтернатива — обычный пароль администратора без 2FA. При 2FA нужен application password. +`app_sudo` даёт приложению широкие права изменения настроек, а не только DNS; +это свойство [API Pi-hole](https://docs.pi-hole.net/ftldns/configfile/#app_sudo). +Не задавайте `FTLCONF_dns_hosts` через environment Pi-hole при автоматическом управлении: +такая настройка становится read-only для API. + +### 2. Опишите маршруты + +В `config/services.yaml` замените `proxy_ip` на LAN-IP NPM и `allowed_networks` на вашу подсеть: + +```yaml +proxy_ip: 192.168.0.10 +domain_zones: [home, home.arpa, lab.internal] +allowed_networks: + - 192.168.0.0/24 +dns_mode: pihole6 +interval_seconds: 60 + +services: + - hostname: pve.home + upstream: https://192.168.0.137:8006 + upstream_tls_verify: false + websocket: true + timeout_seconds: 3600 + max_body_mb: 10240 + ssh: + alias: pve + user: root + port: 22 + + - hostname: grafana.home + upstream: http://192.168.0.120:3000 +``` + +VM-адреса в этой версии — **IPv4**, RFC1918. Upstream должен быть веб-сервисом HTTP(S), +без пути, query и встроенного пароля. Для SSH, базы данных и произвольного TCP такая +конфигурация не подходит. Локальные IPv6 ULA можно использовать в `proxy_ip` и списке +допустимых сетей; для dual-stack DNS дополнительные записи задаются вручную в manual-режиме. + +### 3. Соберите и запустите + +```sh +docker compose build +docker compose run --rm homegate validate +docker compose up -d +docker compose logs -f --tail=100 homegate +``` + +`validate` проверяет только файл и ничего не меняет в Pi-hole/NPM. +Панель открывается по `UI_ORIGIN`, вход — паролем панели, заданным в `setup.sh`. +Подробнее: [веб-панель, резервные копии и HTTPS](WEB.md). + +После старта ожидаются сообщения `Created local root CA`, `Configured https://pve.home ...` +и `DNS: pve.home -> ...`. Сертификат для клиентов появится в `state/root-ca.crt`. +`healthy` означает успешную синхронизацию API, а не доступность целевой VM. + +Первичная сборка скачивает базовый образ и Python-зависимости из интернета. После сборки +работа и продление сертификатов не требуют интернета, публичного DNS или публичного ACME. +Для полностью офлайн-сервера предварительно соберите образ на машине той же архитектуры +и перенесите через `docker save homegate:0.4.0` / `docker load`, затем используйте +`docker compose up -d --no-build`. + +### 4. Установите корневой сертификат на клиенты + +Копируйте на устройства **только `state/root-ca.crt`** через доверенный канал, например SCP. +Сверьте SHA-256 с сервером: + +```sh +docker compose exec homegate python /app/homegate.py fingerprint +``` + +Публичный корень также можно скачать в панели на странице «Сертификаты». +Сверяйте его отпечаток с сервером. Никогда не передавайте клиентам `ca.json`, +`issued/`, `registry.json` или весь `state/`: там находятся закрытые ключи. + +| Клиент | Установка доверия | +|---|---| +| Windows | Импорт `root-ca.crt` в «Доверенные корневые центры сертификации» для нужного пользователя или компьютера. Перезапустите браузер. | +| macOS | «Связка ключей» → System → импорт сертификата → Trust → SSL: Always Trust. Потребуются права администратора. | +| Debian / Ubuntu | `sudo cp root-ca.crt /usr/local/share/ca-certificates/homegate.crt` и `sudo update-ca-certificates`. | +| iPhone / iPad | Установите профиль сертификата; затем Settings → General → About → Certificate Trust Settings → Enable Full Trust для Homegate. | +| Android | Настройки безопасности → установка сертификата CA; путь зависит от производителя. Некоторые приложения не доверяют пользовательским CA. | +| Firefox / отдельные приложения | Если системное доверие не подхватилось, импортируйте CA в собственное хранилище Authorities приложения с доверием для сайтов. | + +На iOS одного импорта недостаточно: [Apple описывает отдельное включение SSL-доверия](https://support.apple.com/en-gb/102390). +Результат зависит от хранилища доверия конкретного браузера/приложения; некоторые устройства +не позволяют добавлять CA. В этом случае вариант — принадлежащий вам публичный домен +и DNS-01 сертификат с локальными DNS-записями; такое имя будет, например, +`pve.lab.your-domain.example`, а не `pve.home`. DNS-01 не требует публикации самого сервиса +в интернет: [Let's Encrypt](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). + +### 5. Проверьте маршрут + +На клиенте, заменив адреса Pi-hole и NPM на реальные: + +```sh +nslookup pve.home 192.168.0.2 +curl --cacert root-ca.crt --resolve pve.home:443:192.168.0.10 https://pve.home/ -I +curl --cacert root-ca.crt https://pve.home/ -I +``` + +DNS должен вернуть IP NPM. Первая команда `curl` проверяет HTTPS независимо от DNS; +вторая — вместе с DNS. Не используйте `-k`: он скрывает ошибки доверия. +Откройте **`https://pve.home`**, выполните вход в Proxmox и проверьте noVNC/Shell. + +## Особенности Proxmox и TLS + +WebSocket, часовые proxy-timeouts, отключение буферизации и лимит тела 10 GiB уже +заданы в примере. Лимит можно увеличить через `max_body_mb`. NPM передаёт имя запроса +и заголовки прокси штатным шаблоном. При необходимости доверенных прокси или корректного +внешнего URL в других приложениях настройте эти приложения отдельно. + +У HTTPS есть два участка: + +1. **Браузер → NPM:** сертификат `pve.home`, подписанный Homegate CA; клиент проверяет + имя и цепочку после установки CA. +2. **NPM → Proxmox:** TLS со штатным сертификатом Proxmox. В примере проверка этого + сертификата явно выключена через `upstream_tls_verify: false`. Шифрование есть, + но подлинность upstream не проверяется. Это не меняет доверие браузера к NPM. + +Для проверки обоих участков скопируйте **публичный CA Proxmox** из +`/etc/pve/pve-root-ca.pem` в постоянный каталог NPM, например +`/data/custom-trust/pve-root-ca.pem` внутри контейнера. Проверьте SAN серверного сертификата +Proxmox и укажите соответствующее имя: + +```yaml +- hostname: pve.home + upstream: https://192.168.0.137:8006 + upstream_tls_verify: true + upstream_tls_name: pve.your-existing-lan-domain + upstream_ca_file: /data/custom-trust/pve-root-ca.pem +``` + +Здесь `upstream_tls_name` — существующее имя из сертификата Proxmox, оно не обязано быть +`pve.home`. Путь читается **NPM**, не Homegate. При собственном сертификате Proxmox +используйте его издателя. Для остальных HTTPS upstream проверка по умолчанию включена. + +## Доступ только из домашней сети + +Homegate добавляет в каждый свой Proxy Host `allow <ваши подсети>; deny all;`. +ACL применяется к IP, который видит NPM. Никаких правил проброса портов на роутере не нужно. +Оставьте WAN-вход закрытым для `80`, `443`, `81`, `53`, порта web Pi-hole и `SSH_PORT` (8099), +включая IPv6 и автоматические пробросы UPnP. При Docker применяйте firewall-правила +с учётом Docker forwarding; одного обычного UFW INPUT-правила может быть недостаточно. + +Если перед NPM стоит другой прокси/NAT, который заменяет адрес источника на разрешённый +LAN-IP, ACL уже не различает внешних и домашних клиентов. Ограничение на роутере/межсетевом +экране остаётся необходимым. Не включайте доверие произвольным `X-Forwarded-For`. +DNS-имя `.home` само по себе не является ограничением доступа. + +## Изменения, продление и восстановление + +- Новый сервис: добавьте блок в `config/services.yaml`; изменения подхватятся за 60 секунд. + Контейнер перечитывает каталог конфигурации, в том числе после атомарного сохранения редактором. +- Сертификат выдаётся на 90 дней и заменяется, когда осталось менее 30. Homegate загружает + его в NPM и обновляет Proxy Host, чтобы nginx перечитал сертификат. Перезапуск контейнера + сохраняет CA и идентификатор владельца. +- Если Pi-hole недоступен, Homegate продолжает обслуживание сертификатов/прокси и показывает + нездоровый статус синхронизации. Каждый цикл повторяет неуспешные операции. При отказе NPM + DNS-запись нового сервиса не публикуется. +- Отключение: задайте `enabled: false`; NPM выключит соответствующий Proxy Host, DNS останется. +- Удаление записи из файла **не удаляет** ресурсы. Для окончательного удаления сначала уберите + блок из файла, затем удалите Proxy Host, его сертификат и DNS в интерфейсах NPM/Pi-hole. + До ручного удаления прежний маршрут продолжает работать; продление удалённого из файла + сервиса прекращается. Это также относится к переименованию сервиса. +- Уже существующий чужой Proxy Host с тем же именем или конфликтующий DNS-адрес не + перезаписывается. Используйте новое имя или заранее перенесите старую запись вручную. + NPM-хосты этого проекта редактируйте через YAML: ручные изменения управляемых полей + будут восстановлены. Не удаляйте строку `# homegate:...` из Advanced. +- При смене LAN-IP NPM поправьте `proxy_ip`, затем вручную удалите/исправьте прежние + конфликтующие DNS-записи. Homegate добавляет записи по одной, не заменяет весь DNS-список. +- Для Pi-hole 5 выберите `dns_mode: manual`, в его Local DNS добавьте + `pve.home → IP_NPM`. Сертификаты и NPM остаются автоматическими. +- Держите только один экземпляр контроллера на `state/`. Файловая блокировка не даёт + одновременно запускать `run` и `once`. Для ручного прохода остановите сервис и выполните + `docker compose run --rm homegate once`, затем `docker compose up -d`. + +Для резервной копии остановите Homegate, сохраните **`.env`, `config/`, `secrets/`, `state/`** +в защищённом хранилище и запустите снова. Отдельно резервируйте NPM (его `/data` и +`/etc/letsencrypt`) и Pi-hole. Закрытый ключ CA хранится в `state/ca.json` без шифрования +с правами `0600`, каталог `state/` — `0700`; используйте шифрование диска/backup. +Это простой онлайн-CA для homelab, без офлайн-корня, CRL и OCSP. При компрометации CA +нужно удалить доверие к старому корню на всех клиентах и развернуть новый CA. +Корень действует 10 лет; за 91 день до истечения выпуск блокируется и требуется миграция доверия. + +Потеря всего `state/` означает потерю CA и владельца объектов. Восстанавливайте backup: +новый CA потребует повторной установки доверия, а старые NPM-объекты не будут присвоены +новому контроллеру автоматически. Ключ CA никогда не импортируется в NPM: туда попадают +только сертификаты отдельных сервисов и их ключи. + +## Диагностика + +| Симптом | Что проверить | +|---|---| +| `NXDOMAIN` | Клиент использует Pi-hole; запись указывает на NPM; отключён обход DNS через DoH/VPN; очистите DNS-кэш. | +| Сертификат не доверен | CA установлен именно на клиенте и в хранилище этого браузера; на iOS включён Full Trust; дата/время верны. | +| Ошибка имени сертификата | Открывайте `https://pve.home`, не IP NPM; проверьте SNI и привязанный в NPM сертификат. | +| HTTP 403 от NPM | IP клиента, видимый NPM, должен входить в `allowed_networks`; проверьте VLAN, IPv6 и наличие внешнего NAT. | +| HTTP 502 | NPM достигает IP:port VM; выбран HTTPS для Proxmox; при `upstream_tls_verify: true` корректны CA и SAN. | +| Pi-hole API HTTP 401/403 | Версия 6, правильный пароль; application password с `app_sudo`; для 2FA — application password. | +| Pi-hole API HTTP 400 | Проверьте `/api/docs` вашей версии и что `dns.hosts` не задан read-only через `FTLCONF_dns_hosts`. | +| NPM API HTTP 401/403 | Email, пароль и разрешения учётной записи; URL содержит административный порт 81. | +| `nginx configuration` | Посмотрите статус хоста и ошибку в NPM; проверьте наличие `upstream_ca_file` внутри NPM. | +| `conflicting Pi-hole record` | DNS для этого имени уже ведёт на другой IP; исправьте его вручную. | +| `not managed by this instance` | Имя занято в NPM или потерян `registry.json`; восстановите state либо выберите другое имя. | +| Сервис `unhealthy` | `docker compose logs --tail=100 homegate`; Docker healthcheck показывает отказ, но сам по себе не перезапускает контейнер. | + +## Проверки разработчика + +```sh +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt +.venv/bin/python -m unittest discover -s tests -v +docker compose --env-file .env.example config --quiet +``` + +Протоколы интеграции: [Pi-hole API](https://docs.pi-hole.net/api/), +[Pi-hole authentication](https://docs.pi-hole.net/api/auth/), +[NPM certificates API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/certificates.js), +[NPM certificate upload implementation](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/internal/certificate.js), +[NPM Proxy Hosts API 2.16.0](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/v2.16.0/backend/routes/nginx/proxy_hosts.js). diff --git a/REGISTRY.md b/REGISTRY.md new file mode 100644 index 0000000..71522b8 --- /dev/null +++ b/REGISTRY.md @@ -0,0 +1,246 @@ +# Один Compose-файл и Gitea Container Registry + +Homegate 0.4 поддерживает два способа установки: + +| Файл | Назначение | +| --- | --- | +| `compose.registry.yaml` | Готовый образ из Gitea; именованные volumes, автоматическая первичная настройка | +| `compose.yaml` | Прежний запуск из исходников с `build`, `setup.sh` и каталогами на хосте | + +Gitea здесь ещё не подключена, образ не опубликован. Workflow готов к запуску в вашем +репозитории. Имена `git.example.home` и `your-user` ниже — примеры. + +## 1. Настройте репозиторий и runner один раз + +Загрузите содержимое каталога проекта в корень репозитория Gitea, включая скрытую папку +`.gitea/workflows/`. Включите **Enable Repository Actions** в настройках репозитория. +В Gitea должен быть включён Package Registry. + +Workflow использует выделенный **Linux runner** с меткой `homegate:host`: + +- Python 3.11+ с `venv` и pip, Git, OpenSSH client, Bash, Node.js 20+; +- Docker Engine, Buildx и Docker Compose **2.30.0+**; +- права на использование Docker и установку QEMU/binfmt через `setup-qemu-action`; +- доступ к Gitea/registry, GitHub для загрузки actions, Docker Hub и PyPI при сборке. + +Метка в workflow — `runs-on: homegate`; если у вашего runner другое имя метки, замените +его в обоих jobs. Для runner с контейнерными jobs нужна специально подготовленная среда, +включающая эти инструменты и доступ к Docker daemon. Шаблон рассчитан на `homegate:host`. +Используйте отдельную VM для сборок: job исполняет код репозитория и имеет доступ к Docker. +Внешние PR запускайте только после проверки авторства и содержимого либо на изолированном +одноразовом runner. Registry secrets используются только в job публикации Git-тега. + +В **Repository Settings → Actions → Secrets** добавьте: + +| Secret | Значение | +| --- | --- | +| `REGISTRY_USERNAME` | Пользователь Gitea, которому разрешено публиковать пакеты владельца репозитория | +| `REGISTRY_TOKEN` | Personal access token этого пользователя с правом `write:package` | + +Для репозитория организации учётная запись должна иметь право записи её пакетов. +Встроенный `GITEA_TOKEN` используется только для checkout; отдельный registry token +обеспечивает совместимость с инсталляциями, где job token не может публиковать пакеты. +Не добавляйте сюда пароли NPM, Pi-hole или панели — они нужны только при развёртывании. + +По умолчанию registry берётся из адреса Gitea, image — из `owner/repository` в нижнем регистре: + +```text +git.example.home/your-user/homegate:0.4.0 +``` + +Если registry доступен по другому имени/порту, задайте Actions **variable** `REGISTRY`, +например `registry.example.home:5000`, без `https://` и без пути. Этот адрес должен действительно +обслуживать Gitea Container Registry. Для имён владельца/репозитория используйте латинские +буквы, цифры и разделители, допустимые в Docker image names. + +Для Gitea с локальным CA настройте доверие к CA у runner, Docker daemon и BuildKit builder. +В workflow не отключается TLS-проверка. Если используете отдельный builder, его настройка +доверия независима от системного хранилища сертификатов. + +## 2. Выпустите образ + +Файл `VERSION` сейчас содержит `0.4.0`. После загрузки проверенного кода в Gitea: + +```sh +git tag v0.4.0 +git push origin v0.4.0 +``` + +При следующем выпуске измените `VERSION`, закоммитьте его вместе с изменениями и создайте +соответствующий тег. Тег должен совпасть с файлом `VERSION`: например `v0.4.1` и `0.4.1`. +Предварительные версии вида `v0.4.1-rc.1` также поддерживаются. Полный номер задаётся +в `VERSION`; примеры в Compose, Dockerfile и документации при выпуске также обновите. + +Workflow `.gitea/workflows/release.yaml` выполняет: + +1. На push в ветку, тег или PR — Python/HTTP-тесты, проверку JavaScript и shell, + проверку обоих Compose-файлов. +2. Сборку образа для архитектуры runner и пробный запуск изолированного стека без + портов хоста и доступа к NPM/Pi-hole. Проверяются вход по паролю, сохранение + настроек, права volumes, отсутствие чужих secrets в UI и сохранность CA после повторной инициализации. +3. Только для push тега `v*`, после успешных проверок — проверку `VERSION`, сборку + `linux/amd64` + `linux/arm64` и публикацию в Gitea Container Registry. + +Образ получает два тега: `0.4.0` и `sha-<полный SHA коммита>`. Тег `latest` не создаётся. +`org.opencontainers.image.source` связывает метаданные образа с URL исходников. +Права на просмотр/скачивание пакета проверьте в Gitea Packages отдельно от доступа к коду. +Workflow не меняет видимость пакетов и не развёртывает Homegate на домашнем сервере. + +Для runtime-тестов локально, если Docker запущен: + +```sh +docker build --build-arg VERSION="$(cat VERSION)" -t homegate:test . +sh ci/smoke_image.sh homegate:test +``` + +Тест создаёт временный Compose-проект со случайным именем `homegate-smoke-*` и удаляет +только его контейнеры и volumes при завершении. Образ не публикуется. + +## 3. Разверните, скачав только Compose + +Скопируйте **только `compose.registry.yaml`** на Linux Docker-хост и переименуйте +в `compose.yaml`. Клонировать проект, устанавливать Python и запускать `setup.sh` не нужно. + +В Bash укажите свои адреса. Здесь `.10`, `.11` и `.2` — примеры: + +```bash +export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.0 +export HOMEGATE_LAN_IP=192.168.0.10 +export HOMEGATE_PROXY_IP=192.168.0.11 +export HOMEGATE_ALLOWED_NETWORKS='[192.168.0.0/24]' +export HOMEGATE_ZONES='[home, home.arpa, lab.internal]' +export UI_ORIGIN=http://192.168.0.10:8098 +export NPM_URL=http://192.168.0.11:81 +export NPM_IDENTITY=admin@example.com +export PIHOLE_URL=http://192.168.0.2 + +read -rsp 'Пароль панели (от 12 символов): ' UI_PASSWORD; printf '\n' +read -rsp 'Пароль NPM: ' NPM_PASSWORD; printf '\n' +read -rsp 'Пароль Pi-hole: ' PIHOLE_PASSWORD; printf '\n' +export UI_PASSWORD NPM_PASSWORD PIHOLE_PASSWORD +``` + +Пароли вводятся скрыто, не записываются в Compose и не передаются как environment контейнера: +Compose монтирует их отдельными secret-файлами только в нужные сервисы. Имена параметров, +которые заканчиваются на `_IP`, принимают приватные IP. `HOMEGATE_LAN_IP` — IPv4 Docker-хоста, +`HOMEGATE_PROXY_IP` — адрес NPM. Это могут быть разные машины. + +Для Pi-hole 5 или ручного DNS вместо автоматического режима: + +```bash +export HOMEGATE_DNS_MODE=manual +export PIHOLE_PASSWORD=not-used +``` + +Для приватного образа войдите в registry, указав свой Gitea username и token вместо пароля: + +```sh +docker login git.example.home +docker compose pull +docker compose up -d +``` + +Для общедоступного образа `docker login` не нужен. Остальные команды одинаковы. +Не публикуйте порты через NAT роутера или внешние туннели. + +Откройте `UI_ORIGIN`. Вход — паролем панели. Начальный список сервисов пуст: +добавьте нужные VM в интерфейсе. Контроллер получает конфигурацию из того же volume. +Защищённый HTTPS сервисов потребует установки корневого CA на клиентские устройства. +О настройке HTTPS самой панели см. [WEB.md](WEB.md#https-самой-панели). + +`HOMEGATE_ZONES`, `HOMEGATE_PROXY_IP`, `HOMEGATE_ALLOWED_NETWORKS`, `HOMEGATE_DNS_MODE` +используются для начального YAML **только один раз**. После первого запуска изменяйте +эти настройки в панели. Изменение seed в Compose при обновлении не затирает ваши настройки. +Зоны лучше определить до первого запуска CA; расширение списка позже может потребовать +явной смены CA по [DOMAINS.md](DOMAINS.md). + +Переменные нужны Compose и при последующих `up`, `pull`, `run` и `exec`; после закрытия +терминала задайте их снова. По желанию можно сохранить их в локальном `.env` с правами `600` +и исключить его из Git. Дополнительный файл не является обязательным. + +Если административные API используют локальный HTTPS CA, его PEM bundle можно скопировать +в volume конфигурации по примеру импорта ниже и указать `API_CA_BUNDLE=/config/management-ca.pem`. +CA самой VM для `upstream_ca_file` по-прежнему устанавливается отдельно внутри NPM. + +## Хранение, обновление и восстановление + +Создаются volumes `homegate_config`, `homegate_state`, `homegate_control` (префикс зависит +от имени Compose-проекта). Не меняйте имя проекта при обычном обновлении, иначе Docker +создаст другой набор volumes и новый CA. + +| Volume | Содержимое | У кого есть доступ | +| --- | --- | --- | +| config | YAML, его резервные копии, необязательный management CA | UI — запись; контроллер и SSH-export — чтение | +| state | Закрытый ключ CA, выданные сертификаты, реестр NPM | Только контроллер | +| control | Публичное состояние и запросы синхронизации | UI и контроллер | + +Инициализатор однократно запускается от root без сети, портов и паролей: готовит права +каталогов для UID/GID `1000:1000`, создаёт YAML только при отсутствии, затем завершается. +При новом запуске он проверяет существующий файл и сохраняет его. Остальные сервисы +всегда работают от UID/GID `1000:1000`. Инициализатор не выпускает и не заменяет CA. + +Обновление до уже опубликованной версии: + +```sh +export HOMEGATE_IMAGE=git.example.home/your-user/homegate:0.4.1 +docker compose pull +docker compose up -d +``` + +Обычные `up`, `restart` и `down` сохраняют volumes. **`docker compose down -v` удалит данные, +включая доверенный CA.** Сделайте резервную копию перед обновлением. Удаление state при +сохранённых настройках в NPM означает потерю ключа и связей с ранее созданными объектами. + +Экспорт YAML и публичного CA: + +```sh +docker compose cp ui:/config/services.yaml ./services.backup.yaml +docker compose cp homegate:/data/root-ca.crt ./root-ca.crt +``` + +Для полной резервной копии остановите три долгоживущих сервиса, чтобы YAML и реестр +не менялись во время копирования. Архив state содержит приватные ключи: + +```sh +umask 077 +mkdir -p backup/config backup/state backup/control +docker compose stop homegate ui ssh-export +docker compose cp ui:/config/. ./backup/config/ +docker compose cp homegate:/data/. ./backup/state/ +docker compose cp ui:/control/. ./backup/control/ +docker compose start homegate ui ssh-export +``` + +При восстановлении используйте тот же Compose project name, сначала запустите только +`initialize`, затем импортируйте файлы через одноразовый контейнер `initialize` +(`docker compose run --rm --no-deps -T --entrypoint python initialize -c ...`). +Он видит все три volumes и имеет права выставить владельца восстановленных файлов `1000:1000`. +Не запускайте контроллер с пустым state до импорта резервной копии CA и реестра. +Для разового импорта YAML без копирования закрытых ключей: + +```sh +docker compose stop homegate ui ssh-export +docker compose run --rm --no-deps -T --entrypoint python ui -c \ + 'import sys; from pathlib import Path; Path("/config/services.yaml").write_bytes(sys.stdin.buffer.read())' \ + < services.backup.yaml +docker compose run --rm --no-deps homegate validate +docker compose start homegate ui ssh-export +``` + +Команды предполагают, что volumes уже инициализированы. Миграцию существующей установки +на bind mounts выполняйте через резервное копирование: автоматический перенос старого `state/` +в новые volumes не выполняется. Используйте новое имя Compose-проекта во время подготовки +миграции; старый стек остановите перед запуском нового на тех же портах/API. + +## Что проверено + +Локально проходят 55 тестов, включая первый запуск, сохранение пользовательских изменений +и CA, отказ от повреждённого конфига и проверку адреса/версии публикуемого образа. +Оба Compose-файла проверяются установленным Docker Compose. Синтаксис shell, JavaScript +и YAML workflow проверен. Docker daemon при подготовке выключен, поэтому сборка образа, +контейнерный smoke-test и исполнение самого workflow должны впервые пройти на вашем runner. + +Официальные контракты: [Gitea Container Registry](https://docs.gitea.com/usage/packages/container/), +[Gitea Actions](https://docs.gitea.com/usage/actions/quickstart/), +[Compose secrets из environment](https://docs.docker.com/reference/compose-file/secrets/), +[Compose configs с content](https://docs.docker.com/reference/compose-file/configs/). diff --git a/SSH.md b/SSH.md new file mode 100644 index 0000000..e79c80c --- /dev/null +++ b/SSH.md @@ -0,0 +1,175 @@ +# Общий SSH-конфиг в локальной сети + +Добавьте секцию `ssh` к нужному веб-сервису. SSH-адрес по умолчанию берётся из IP +его `upstream`; при необходимости задайте другой `ssh.host`: + +```yaml +services: + - hostname: pve.home + upstream: https://192.168.0.137:8006 + upstream_tls_verify: false + ssh: + alias: pve + user: root + port: 22 +``` + +Выгрузка содержит: + +```sshconfig +Host pve pve.home + HostName 192.168.0.137 + Port 22 + User root + StrictHostKeyChecking ask +``` + +`ssh pve` и `ssh pve.home` подключаются **напрямую к VM**, а не к NPM. +Без этого Include обычное DNS-разрешение `pve.home` возвращает NPM, предназначенный для HTTPS. +Это не SSH-прокси и не SSH-сервер: на целевой машине должен уже работать `sshd`, а ключи +авторизации и доступ из LAN на нужный порт настраиваются отдельно. + +Для машин без веб-сервиса есть независимый список. DNS/Proxy Host для них не создаётся: + +```yaml +ssh_hosts: + - aliases: [backup, backup.lab.internal] + host: 192.168.0.150 + port: 2222 + user: admin +``` + +Секция `ssh` необязательна. Если её нет, сервис не включается в выгрузку. `user` тоже +необязателен: тогда применяется личный SSH-конфиг/имя пользователя ПК. Для отключения +экспорта одного сервиса используйте `ssh.enabled: false`; `enabled: false` у веб-сервиса +также исключает его из SSH-конфига. Записи `ssh_hosts` поддерживают собственный `enabled`. +Алиасы должны быть уникальными, без wildcard, пробелов и управляющих конструкций. +SSH HostName может быть RFC1918 IPv4 или ULA IPv6. + +## Адрес выгрузки + +В `.env` укажите IP **Docker-хоста Homegate**, который может отличаться от IP NPM: + +```dotenv +SSH_BIND_IP=192.168.0.10 +SSH_PORT=8099 +``` + +В `config/services.yaml` задайте свою подсеть: + +```yaml +allowed_networks: + - 192.168.0.0/24 +``` + +После `docker compose up -d --build` файл доступен по адресу: + +```text +http://192.168.0.10:8099/ssh-config +``` + +Замените `.10` своим адресом. Список генерируется при каждом запросе из текущего YAML, +поэтому изменение адреса/порта или удаление SSH-записи отражается сразу и не требует +доступных Pi-hole/NPM. При невалидной конфигурации сервер возвращает HTTP 503. +Для просмотра без HTTP можно выполнить `docker compose run --rm homegate ssh-config`; +эта команда не использует API и не блокирует работающий контроллер. + +Выгрузка открыта без логина **только разрешённым IP**. Она содержит топологию сети и +имена пользователей, но не приватные ключи, пароли, CA или SSH host keys. +Сервер не раздаёт каталоги и игнорирует `X-Forwarded-For` при проверке клиента. +В контейнер `ssh-export` вообще не монтируются ключ CA и пароли управления. + +Docker публикует порт на конкретном адресе хоста; это описано в +[документации Docker](https://docs.docker.com/engine/network/port-publishing/). +Не пробрасывайте этот порт из WAN и не включайте для него UPnP. Привязка IP и ACL +не заменяют firewall, если перед сервером стоит NAT, подменяющий внешний IP разрешённым +LAN-адресом. На Docker Desktop источник может выглядеть иначе, чем на Linux; +эта конфигурация рассчитана на Linux-хост с сохранением исходного IP клиента. + +## Подключение на ПК + +Скопируйте `sync_ssh.py` из проекта на ПК. Нужны Python 3.9+ и OpenSSH; +дополнительные Python-пакеты не требуются. Первый запуск на Linux/macOS: + +```sh +python3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install +ssh pve +``` + +На Windows с Python и OpenSSH Client: + +```powershell +py -3 sync_ssh.py http://192.168.0.10:8099/ssh-config --install +ssh pve +``` + +Скрипт сохраняет отдельный файл `~/.ssh/config.d/homegate.conf`. Флаг `--install` один раз +добавляет в конец основного `~/.ssh/config` блок `Host *` с `Include` на абсолютный путь +этого файла. Перед изменением основной файл копируется в `config.before-homegate-*`. +Повторный запуск не дублирует Include. На Windows используется `.ssh` в профиле пользователя. +Другой каталог можно задать через `--ssh-dir`; OpenSSH сам должен быть настроен читать +находящийся там основной конфиг, например через `ssh -F /path/config pve`. + +Существующие настройки имеют приоритет по правилу первого значения OpenSSH. +Приватные ключи и `IdentityFile` задавайте в личном конфиге: + +```sshconfig +Host pve + IdentityFile ~/.ssh/id_ed25519_homelab + IdentitiesOnly yes +``` + +Этот блок разместите **до** Homegate Include. Если прежде был `Host *` с `User` или +`Port`, он также имеет приоритет перед загруженными значениями. При необходимости +переместите весь блок Homegate Include выше общих настроек, сохранив его маркеры. +Проверить результат без подключения: `ssh -G pve`. +OpenSSH описывает [порядок применения и Include](https://man.openbsd.org/ssh_config#Include). + +Скрипт не меняет NTFS ACL на Windows: используйте обычный приватный каталог профиля, +не общую сетевую папку. Windows-вариант написан на стандартной библиотеке Python, +но отдельно на Windows не запускался. Symlink основного конфига автоматически не +перезаписывается: в таком случае добавьте Include вручную и запускайте скрипт без `--install`. + +## Обновление + +Для последующих обновлений достаточно той же команды без `--install`: + +```sh +python3 sync_ssh.py http://192.168.0.10:8099/ssh-config +``` + +Обновление атомарное: при ошибке сети или проверок старый файл сохраняется. Удалённые +SSH-записи исчезают из дополнительного файла при следующем успешном обновлении. +Основной конфиг и `known_hosts` при обновлении не меняются. Файл на ПК обновляется +только при запуске скрипта; автоматическое расписание не создаётся. +На Linux/macOS файл получает права `0600`, каталог — `0700`. + +Скрипт принимает только `Host`, `HostName`, `Port`, `User` и `StrictHostKeyChecking ask`, +проверяет значения и заново собирает текст перед записью. Скачанные `ProxyCommand`, +`Match exec`, вложенные `Include`, глобальные wildcard-настройки и выключение проверки +SSH host key отклоняются. Первый SSH-вход требует проверки отпечатка ключа +сервера обычным способом. Скрипт не выполняет скачанный код, не следует HTTP-редиректам +и не использует прокси из переменных окружения. + +## HTTPS для загрузки + +HTTP не защищает список адресов от подмены внутри LAN. Для аутентифицированной загрузки +добавьте HTTPS Proxy Host через существующий NPM на exporter, включив в `services`: + +```yaml +- hostname: config.home + upstream: http://192.168.0.10:8099 +``` + +Тогда на ПК: + +```sh +python3 sync_ssh.py https://config.home/ssh-config --ca-file root-ca.crt --install +``` + +Это опциональный маршрут; домен должен входить в `domain_zones`. +NPM применяет LAN ACL к клиенту; exporter должен видеть разрешённый LAN-IP NPM. +Если Docker NAT показывает другой адрес, настройте сетевой путь или узкое правило +для этого конкретного адреса, не разрешайте весь Docker subnet без необходимости. +Проверка HTTPS у скрипта всегда включена. Корневой сертификат берите по доверенному +каналу из `state/root-ca.crt`. Ни HTTP-, ни HTTPS-вариант не требует логина для скачивания из LAN. diff --git a/VERSION b/VERSION new file mode 100644 index 0000000..1d0ba9e --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.4.0 diff --git a/WEB.md b/WEB.md new file mode 100644 index 0000000..00fd189 --- /dev/null +++ b/WEB.md @@ -0,0 +1,157 @@ +# Веб-панель Homegate 0.4 + +Панель включена в проект и Docker Compose. Она редактирует настоящий YAML, проверяет +настройки на сервере и показывает результат синхронизации контроллера с Pi-hole/NPM. +Интерфейс на русском, адаптируется к узким экранам и работает без внешних шрифтов, +аналитики, CDN или интернет-сервисов. + +## Что доступно + +- **Сервисы:** поиск, добавление, редактирование, включение/выключение; адрес VM, домен, + WebSocket, проверка TLS upstream, тайм-аут и размер загрузки, SSH-доступ. + Поле «Название» сохраняется как `display_name` и используется в каталоге, поиске + и схеме соединения. Оно необязательное, до 100 символов; без него подпись определяется по домену. +- **Доменные зоны:** несколько зон одновременно; добавление и удаление с проверкой + привязанных сервисов. Расширение ограничений уже созданного CA требует его явной смены. +- **SSH:** предпросмотр и скачивание конфига, скрипт для ПК, команда подключения, + отдельные SSH-хосты без веб-сервиса. Открытая LAN-выгрузка работает через `ssh-export`. +- **Сертификаты:** публичный корневой сертификат, SHA-256, сроки и список выданных + сертификатов. Смена CA выполняется на сервере по инструкции из панели. +- **Настройки:** IP NPM, разрешённые подсети, режим DNS, интервал синхронизации, + журнал сохранений и скачивание текущего YAML. + +## Локальный запуск через Sites + +Использован локальный режим Sites: исходники и работающий сервер остаются на компьютере. +Регистрация в облаке и публикация в интернете для этого проекта не выполняются. + +На macOS/Linux с Python 3.11+ из каталога проекта: + +```sh +sh run-local.sh +``` + +Откройте **http://127.0.0.1:8787**. При первом запуске скрипт создаёт отдельную среду Python +и устанавливает зависимости. Рабочая копия YAML, резервные копии и данные интерфейса +хранятся в `.local/`; образец `config/services.yaml` остаётся исходным шаблоном. +Чтобы изменить порт, используйте `HOMEGATE_LOCAL_PORT=8788 sh run-local.sh`. +Остановка — Ctrl+C в терминале; повторный запуск сохраняет внесённые настройки. + +Локальный режим доступен только через `127.0.0.1`, вход в нём не требуется. +Он не запускает контроллер и не изменяет Pi-hole/NPM. Кнопка «Применить» сохраняет запрос; +без контроллера панель прямо сообщает, что применения пока нет. Скачайте подготовленный +YAML через кнопку в панели и перенесите в `config/services.yaml` на Docker-хосте. + +В экземпляре, запущенном при подготовке проекта, рабочая копия находится отдельно +в `work/local-ui/config/services.yaml` относительно папки задачи. Для её повторного запуска +из исходной папки задачи без повторной установки зависимостей: + +```sh +HOMEGATE_LOCAL_DIR="$PWD/work/local-ui" \ +HOMEGATE_PYTHON="$PWD/work/venv/bin/python" \ +sh outputs/homegate/run-local.sh +``` + +## Панель для домашней сети через Docker + +Для готового образа и автоматического создания volumes используйте [один Compose-файл](REGISTRY.md). +Ниже — вариант сборки из исходников. + +```sh +sh setup.sh +# Замените примеры адресов в .env и config/services.yaml своими. +docker compose build +docker compose run --rm homegate validate +docker compose up -d +``` + +`setup.sh` отдельно запрашивает пароль панели длиной от 12 символов. +В `.env` задайте: + +```dotenv +UI_BIND_IP=192.168.0.10 +UI_PORT=8098 +UI_ORIGIN=http://192.168.0.10:8098 +SSH_BIND_IP=192.168.0.10 +SSH_PORT=8099 +``` + +Адрес `.10` — пример LAN-IP **хоста Homegate**; он может отличаться от IP NPM. +Откройте точный `UI_ORIGIN`, войдите с паролем из `secrets/ui_password`. +Настройки сохраняются непосредственно в `config/services.yaml`, контроллер применяет их +каждые `interval_seconds`. «Применить» будит контроллер обычно в пределах двух секунд, +после чего ему требуется время на обращения к API. Статус не равнозначен доступности VM: +он сообщает об успешной настройке NPM/Pi-hole, а не о проверке приложения за прокси. + +Сохранение создаёт резервную копию в `config/backups/` (последние 20 файлов). +При одновременном редактировании в двух вкладках устаревшая версия не перезаписывает новую. +Форматирование и комментарии YAML при сохранении через панель заменяются сериализованным YAML. +Для восстановления скопируйте нужный файл из `config/backups/` в `config/services.yaml`. +В панели отображаются последние восемь из двадцати сохранений, с временем без персонального аудита. + +Выключение сервиса передаёт `enabled: false` в NPM. Удаление из списка прекращает управление, +но уже созданные Proxy Host и DNS-запись сохраняются: удалите их отдельно в NPM/Pi-hole. +Это поведение явно описано в диалоге удаления. Переименование домена эквивалентно созданию +нового имени и прекращению управления старым; старые объекты также остаются. + +## HTTPS самой панели + +Исходный порт `8098` работает по HTTP. Для HTTPS добавьте в Homegate сервис, например: + +```yaml +- hostname: homegate.home + upstream: http://192.168.0.10:8098 +``` + +После применения и установки `root-ca.crt` на клиенте измените `.env`: + +```dotenv +UI_ORIGIN=https://homegate.home +``` + +Пересоздайте панель: + +```sh +docker compose up -d --force-recreate ui +``` + +Теперь вход выполняется по **https://homegate.home**. Старый URL по IP намеренно перестанет +проходить проверку Host. В NPM нужно сохранять исходный Host (обычное поведение Proxy Host). +Для прямого отката измените `UI_ORIGIN` обратно и пересоздайте `ui`. +Сервис панели должен разрешать подсеть NPM в `allowed_networks`; NPM проверяет исходный +клиентский IP по тому же списку. Панель сама не доверяет `X-Forwarded-For`. +Не перенаправляйте порты через роутер и не публикуйте их через внешние туннели. +HTTP-вход используйте только в доверенной сети при первоначальной настройке; +постоянный доступ к панели лучше проводить через описанный HTTPS-маршрут. + +## Изоляция компонентов + +| Компонент | Доступ | +| --- | --- | +| `homegate` | YAML только для чтения, CA и реестр в `state/`, API-пароли, `control/` | +| `ui` | YAML и резервные копии, `control/`, только пароль панели | +| `ssh-export` | Только YAML для чтения; без паролей и `state/` | + +`control/status.json` содержит публичные сертификаты и состояние последней синхронизации. +`control/sync-request.json` — запрос на очередной цикл. CA-ключи не попадают в эти файлы. +Контейнер панели не имеет доступа к `state/`, паролям интеграций или Docker socket. +Сессии хранятся в памяти 12 часов, после рестарта нужно войти снова. Включены проверка +Origin, CSRF-токен, HttpOnly/SameSite cookie, защита от перебора и список допустимых Host. +При HTTPS cookie также получает Secure. После смены пароля перезапустите `ui`, чтобы сбросить сессии. + +Ограничение подсетей основано на видимом контейнеру адресе клиента. Рекомендуется Linux Docker +Engine; Docker Desktop или дополнительный reverse proxy могут менять этот адрес. +Проверяйте доступ с разрешённого и постороннего сегмента после установки, включая правила +хостового firewall и Docker. Публикация на конкретном LAN-IP сама по себе не отменяет NAT роутера. + +## Проверки + +55 тестов проходят локально: прежняя логика DNS/TLS/SSH, HTTP-вход и сессии, Origin/CSRF, +LAN ACL, скачивание, проверка YAML, резервные копии, конфликт изменений, свежесть статуса +и передача в панель только публичных данных. JavaScript и Compose проходят проверку синтаксиса. +В браузере проверены добавление сервиса, поиск, навигация, SSH-предпросмотр и адаптивная компоновка. +Реальные API вашего homelab и запуск Docker-образа на сервере пока не проверены. + +```sh +python -m unittest discover -s tests -v +``` diff --git a/bootstrap.py b/bootstrap.py new file mode 100644 index 0000000..d89dcfe --- /dev/null +++ b/bootstrap.py @@ -0,0 +1,58 @@ +"""Initialize named volumes once; never replace an existing Homegate configuration.""" +import fcntl +import os +from pathlib import Path +import stat +import sys + +import yaml + +import homegate as h + + +def initialize(seed, config, state, control, uid=1000, gid=1000): + config, state, control = map(Path, (config, state, control)) + seed = Path(seed) + for directory in (config.parent, state, control): + h.require(not directory.is_symlink(), f"Volume must not be a symlink: {directory}") + directory.mkdir(parents=True, exist_ok=True, mode=0o700) + h.require(directory.is_dir(), f"Expected a directory: {directory}") + # The short-lived initializer is the only root container. No recursive chown: + # existing CA material and backups must not be traversed or replaced. + if os.geteuid() == 0: + os.chown(directory, uid, gid) + os.chmod(directory, 0o700) + lock_path = config.parent / '.bootstrap.lock' + h.require(not lock_path.is_symlink(), 'Bootstrap lock must not be a symlink') + with lock_path.open('a') as lock: + fcntl.flock(lock, fcntl.LOCK_EX) + h.require(not config.is_symlink(), 'services.yaml must not be a symlink') + if config.exists(): + h.require(stat.S_ISREG(config.stat().st_mode), 'services.yaml must be a regular file') + h.load_config(config) + created = False + else: + h.load_config(seed) # Reject invalid seed before touching the live config. + h.atomic(config, seed.read_bytes(), 0o600) + created = True + if os.geteuid() == 0: + os.chown(config, uid, gid) + return created + + +def main(): + os.umask(0o077) + created = initialize(os.environ.get('HOMEGATE_SEED', '/run/configs/homegate-seed.yaml'), + os.environ.get('HOMEGATE_CONFIG', '/config/services.yaml'), + os.environ.get('HOMEGATE_STATE', '/data'), + os.environ.get('HOMEGATE_CONTROL', '/control')) + print('Created initial configuration' if created else 'Existing configuration retained') + return 0 + + +if __name__ == '__main__': + try: + sys.exit(main()) + except (h.Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc: + print(f'Initialization failed: {exc}', file=sys.stderr) + sys.exit(1) diff --git a/ci/check_compose.py b/ci/check_compose.py new file mode 100644 index 0000000..65368e9 --- /dev/null +++ b/ci/check_compose.py @@ -0,0 +1,53 @@ +"""Validate both deployment models without a running Docker daemon or real credentials.""" +import json +import os +from pathlib import Path +import subprocess +import yaml +import homegate as h + + +def main(): + env = dict(os.environ, HOMEGATE_IMAGE='registry.example/homegate/homegate:0.4.0', + HOMEGATE_LAN_IP='192.168.0.10', HOMEGATE_PROXY_IP='192.168.0.10', + HOMEGATE_ALLOWED_NETWORKS='[192.168.0.0/24]', HOMEGATE_ZONES='[home, home.arpa]', + HOMEGATE_DNS_MODE='manual', UI_ORIGIN='http://192.168.0.10:8098', + NPM_URL='http://192.168.0.10:81', NPM_IDENTITY='test@example.invalid', + UI_PASSWORD='test-only-panel-password', NPM_PASSWORD='test-only-npm', + PIHOLE_PASSWORD='not-used', PIHOLE_URL='', UI_PORT='8098', SSH_PORT='8099') + model = json.loads(subprocess.check_output( + ['docker', 'compose', '--env-file', os.devnull, '-f', 'compose.registry.yaml', + 'config', '--format', 'json'], env=env)) + assert set(model['services']) == {'initialize', 'homegate', 'ssh-export', 'ui'} + for name, service in model['services'].items(): + assert 'build' not in service, name + assert service['image'] == env['HOMEGATE_IMAGE'] + assert all(v['type'] == 'volume' for v in service.get('volumes', [])), name + if name != 'initialize': + assert service['user'] == '1000:1000' + assert service['depends_on']['initialize']['condition'] == 'service_completed_successfully' + for port in service.get('ports', []): + assert port['host_ip'] == env['HOMEGATE_LAN_IP'] + assert model['services']['initialize']['network_mode'] == 'none' + assert not model['services']['initialize'].get('secrets') + assert not model['services']['ssh-export'].get('secrets') + assert [v['source'] for v in model['services']['ui']['secrets']] == ['ui_password'] + for name in ('ui', 'ssh-export'): + assert all(v['target'] != '/data' for v in model['services'][name]['volumes']) + assert set(model['secrets']) == {'ui_password', 'npm_password', 'pihole_password'} + assert all('environment' in s and 'file' not in s for s in model['secrets'].values()) + seed = h.validate_config(yaml.safe_load(model['configs']['initial-config']['content'])) + assert seed['services'] == [] and seed['ssh_hosts'] == [] + subprocess.run(['docker', 'compose', '--env-file', '.env.example', '-f', 'compose.yaml', + 'config', '--quiet'], check=True, env=env) + # The one-file deployment cannot accidentally fall back to all host interfaces. + del env['HOMEGATE_LAN_IP'] + missing = subprocess.run(['docker', 'compose', '--env-file', os.devnull, + '-f', 'compose.registry.yaml', 'config', '--quiet'], + env=env, capture_output=True) + assert missing.returncode != 0 + print('Build and registry Compose models validated; isolation and first-run defaults verified.') + + +if __name__ == '__main__': + main() diff --git a/ci/image_metadata.py b/ci/image_metadata.py new file mode 100644 index 0000000..ae03d85 --- /dev/null +++ b/ci/image_metadata.py @@ -0,0 +1,49 @@ +"""Validate release identity before registry credentials are used.""" +import os +from pathlib import Path +import re +from urllib.parse import urlsplit + + +VERSION_PATTERN = r'(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z][0-9A-Za-z.-]*)?' +COMPONENT = r'[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*' + + +def metadata(server_url, repository, ref, revision, version_file, registry_override=''): + server = urlsplit(server_url) + if server.scheme not in ('http', 'https') or not server.hostname or server.username or server.query or server.fragment: + raise ValueError('Invalid Gitea server URL') + registry = (registry_override or server.netloc).lower() + parsed = urlsplit('https://' + registry) + if (not re.fullmatch(r'[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]{1,5})?', registry) + or parsed.port is not None and not 1 <= parsed.port <= 65535): + raise ValueError('REGISTRY must be a hostname[:port], without scheme or path') + if '.' not in registry and ':' not in registry and registry != 'localhost': + raise ValueError('Use a registry FQDN or explicit port; a bare name is a Docker Hub namespace') + repository = repository.lower() + if not re.fullmatch(COMPONENT + '/' + COMPONENT, repository): + raise ValueError('Repository must be owner/name with a Docker-compatible lowercase name') + if not ref.startswith('refs/tags/v'): + raise ValueError('Images are published only for vVERSION tags') + version = ref.removeprefix('refs/tags/v') + if not re.fullmatch(VERSION_PATTERN, version) or len(version) > 100: + raise ValueError('Use a tag such as v0.4.0 or v0.4.0-rc.1') + if version != version_file.strip(): + raise ValueError('Release tag must match VERSION in the checked-out commit') + if not re.fullmatch(r'[a-fA-F0-9]{40}|[a-fA-F0-9]{64}', revision): + raise ValueError('Invalid commit SHA') + return {'registry': registry, 'image': registry + '/' + repository, + 'version': version, 'revision': revision.lower(), + 'source': server_url.rstrip('/') + '/' + repository} + + +if __name__ == '__main__': + values = metadata(os.environ['CI_SERVER_URL'], os.environ['CI_REPOSITORY'], + os.environ['CI_REF'], os.environ['CI_REVISION'], + Path('VERSION').read_text(), os.environ.get('REGISTRY', '')) + with open(os.environ['GITHUB_OUTPUT'], 'a') as output: + for key, value in values.items(): + if '\n' in value or '\r' in value: + raise ValueError('Invalid multiline output') + output.write(f'{key}={value}\n') + print('Validated release:', values['image'] + ':' + values['version']) diff --git a/ci/smoke_image.sh b/ci/smoke_image.sh new file mode 100755 index 0000000..1e48caa --- /dev/null +++ b/ci/smoke_image.sh @@ -0,0 +1,56 @@ +#!/bin/sh +# Disposable CI deployment. No host ports and no access to NPM/Pi-hole. +set -eu +cd "$(dirname "$0")/.." +: "${1:?Pass a locally built image}" +export HOMEGATE_IMAGE=$1 +export HOMEGATE_LAN_IP=192.168.42.10 +export HOMEGATE_PROXY_IP=192.168.42.11 +export HOMEGATE_ALLOWED_NETWORKS='[192.168.42.0/24]' +export HOMEGATE_ZONES='[home]' +export HOMEGATE_DNS_MODE=manual +export UI_ORIGIN=http://192.168.42.10:8098 +export NPM_URL=http://192.168.42.11:81 +export NPM_IDENTITY=smoke@example.invalid +export PIHOLE_URL= +export API_CA_BUNDLE= +export UI_PASSWORD=disposable-smoke-password +export NPM_PASSWORD=disposable-smoke-npm +export PIHOLE_PASSWORD=not-used +smoke_dir=$(mktemp -d) +project="homegate-smoke-$(python3 -c 'import secrets; print(secrets.token_hex(6))')" +cat > "$smoke_dir/override.yaml" <<'YAML' +services: + ui: + ports: !reset [] + network_mode: none + ssh-export: + ports: !reset [] + network_mode: none + homegate: + network_mode: none +YAML +compose() { + docker compose --env-file /dev/null -p "$project" -f compose.registry.yaml -f "$smoke_dir/override.yaml" "$@" +} +cleanup() { + compose down --volumes --remove-orphans >/dev/null 2>&1 || true + rm -rf -- "$smoke_dir" +} +trap cleanup EXIT +trap 'exit 1' HUP INT TERM +compose up -d --wait --wait-timeout 60 --pull never ui ssh-export +compose run --rm --no-deps homegate validate +compose exec -T ui python - write < ci/smoke_ui.py +compose exec -T ssh-export python -c "from pathlib import Path; import os,urllib.request; assert os.getuid()==1000; assert not Path('/run/secrets/ui_password').exists(); assert not Path('/data').exists(); urllib.request.urlopen('http://127.0.0.1:8080/healthz',timeout=3).read()" +ca_check="from pathlib import Path; import hashlib,os,homegate as h; assert os.getuid()==1000; c=h.load_config('/config/services.yaml'); h.Authority(Path('/data'),c['domain_zones']); print(hashlib.sha256(Path('/data/root-ca.crt').read_bytes()).hexdigest())" +ca_before=$(compose run --rm --no-deps --entrypoint python homegate -c "$ca_check") +# Changing a first-run seed must not replace live settings or the established CA. +export HOMEGATE_PROXY_IP=192.168.42.99 +export HOMEGATE_ZONES='[changed.internal]' +compose run --rm --no-deps initialize +compose restart ui ssh-export +compose exec -T ui python - verify < ci/smoke_ui.py +ca_after=$(compose run --rm --no-deps --entrypoint python homegate -c "$ca_check") +[ "$ca_before" = "$ca_after" ] +printf 'Runtime smoke test passed: bootstrap, permissions, secrets, config and CA persistence.\n' diff --git a/ci/smoke_ui.py b/ci/smoke_ui.py new file mode 100644 index 0000000..a430212 --- /dev/null +++ b/ci/smoke_ui.py @@ -0,0 +1,61 @@ +"""Executed inside the UI container of ci/smoke_image.sh; no external networking.""" +import http.cookiejar +import json +import os +from pathlib import Path +import sys +import time +import urllib.error +import urllib.request +from urllib.parse import urlsplit + +origin = os.environ['UI_ORIGIN'] +authority = urlsplit(origin).netloc +opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar())) +csrf = '' + + +def request(path, data=None): + headers = {'Host': authority} + if data is not None: + headers.update({'Origin': origin, 'Content-Type': 'application/json', 'X-Homegate-CSRF': csrf}) + payload = None if data is None else json.dumps(data).encode() + with opener.open(urllib.request.Request('http://127.0.0.1:8081' + path, payload, headers), timeout=2) as r: + body = r.read() + return json.loads(body) if 'application/json' in r.headers.get('Content-Type', '') else body + + +assert os.getuid() == 1000 +assert not Path('/run/secrets/npm_password').exists() +assert not Path('/run/secrets/pihole_password').exists() +assert not Path('/data').exists() +assert Path('/app/VERSION').read_text().strip() +for attempt in range(30): + try: + session = request('/api/session') + break + except urllib.error.URLError: + if attempt == 29: + raise + time.sleep(1) +assert session['authenticated'] is False +try: + request('/api/state') +except urllib.error.HTTPError as error: + assert error.code == 401 +else: + raise AssertionError('Unauthenticated state is exposed') +csrf = request('/api/login', {'password': Path('/run/secrets/ui_password').read_text()})['csrf'] +state = request('/api/state') +if sys.argv[-1] == 'write': + assert state['config']['services'] == [] + state['config']['services'] = [{'hostname': 'smoke.home', 'display_name': 'Сохранённый сервис', + 'upstream': 'http://192.168.42.137:8000', + 'ssh': {'alias': 'smoke', 'user': 'admin'}}] + state = request('/api/config', {'config': state['config'], 'revision': state['revision']}) +assert state['config']['proxy_ip'] == '192.168.42.11' +assert state['config']['domain_zones'] == ['home'] +assert state['config']['services'][0]['display_name'] == 'Сохранённый сервис' +assert b'Host smoke smoke.home' in request('/api/ssh-config') +assert len(list(Path('/config/backups').glob('*.yaml'))) >= 1 +print('UI: non-root login, secret isolation, saved configuration and SSH export verified') diff --git a/compose.registry.yaml b/compose.registry.yaml new file mode 100644 index 0000000..84f4afb --- /dev/null +++ b/compose.registry.yaml @@ -0,0 +1,150 @@ +# Download this file only. Supply settings/passwords via the shell or an optional .env. +# Docker Compose >= 2.30.0 (not docker stack deploy). See REGISTRY.md. +# Example image: git.example.home/your-user/homegate:0.4.0 +name: homegate + +x-runtime: &runtime + image: "${HOMEGATE_IMAGE:?Set the full registry/owner/homegate:version image name}" + restart: unless-stopped + init: true + user: "1000:1000" + read_only: true + tmpfs: + - /tmp:rw,noexec,nosuid,size=16m + cap_drop: [ALL] + security_opt: + - no-new-privileges:true + pids_limit: 64 + mem_limit: 256m + cpus: 0.5 + logging: + driver: json-file + options: + max-size: 5m + max-file: "3" + +x-environment: &environment + PYTHONDONTWRITEBYTECODE: "1" + PYTHONUNBUFFERED: "1" + HOMEGATE_CONFIG: /config/services.yaml + +services: + initialize: + <<: *runtime + entrypoint: [python, /app/bootstrap.py] + command: [] + user: "0:0" + restart: "no" + network_mode: none + # Only prepares permissions/configuration, then exits. No secrets or API calls. + cap_add: [CHOWN, DAC_OVERRIDE, FOWNER] + environment: + <<: *environment + HOMEGATE_STATE: /data + HOMEGATE_CONTROL: /control + volumes: + - config:/config + - state:/data + - control:/control + configs: + - source: initial-config + target: /run/configs/homegate-seed.yaml + + homegate: + <<: *runtime + depends_on: + initialize: + condition: service_completed_successfully + environment: + <<: *environment + HOMEGATE_STATE: /data + HOMEGATE_CONTROL: /control + NPM_URL: "${NPM_URL:?Set the NPM management URL without /api}" + NPM_IDENTITY: "${NPM_IDENTITY:?Set the NPM login email}" + NPM_PASSWORD_FILE: /run/secrets/npm_password + PIHOLE_URL: "${PIHOLE_URL:-}" + PIHOLE_PASSWORD_FILE: /run/secrets/pihole_password + API_CA_BUNDLE: "${API_CA_BUNDLE:-}" + volumes: + - config:/config:ro + - state:/data + - control:/control + secrets: [npm_password, pihole_password] + healthcheck: + test: [CMD, python, /app/homegate.py, health] + interval: 30s + timeout: 5s + start_period: 120s + retries: 3 + + ssh-export: + <<: *runtime + command: [serve] + depends_on: + initialize: + condition: service_completed_successfully + environment: + <<: *environment + SSH_BIND_IP: "${HOMEGATE_LAN_IP:?Set the Docker host private IPv4 address}" + ports: + - "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}:${SSH_PORT:-8099}:8080" + volumes: + - config:/config:ro + healthcheck: + test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=3).read()"] + interval: 30s + timeout: 5s + retries: 3 + + ui: + <<: *runtime + entrypoint: [python, /app/homegate_ui.py] + command: [] + depends_on: + initialize: + condition: service_completed_successfully + environment: + <<: *environment + HOMEGATE_CONTROL: /control + UI_BIND_IP: "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}" + UI_ORIGIN: "${UI_ORIGIN:?Set the exact panel URL, for example http://192.168.0.10:8098}" + UI_PASSWORD_FILE: /run/secrets/ui_password + SSH_PUBLIC_URL: "http://${HOMEGATE_LAN_IP}:${SSH_PORT:-8099}/ssh-config" + ports: + - "${HOMEGATE_LAN_IP:?Set HOMEGATE_LAN_IP}:${UI_PORT:-8098}:8081" + volumes: + - config:/config + - control:/control + secrets: [ui_password] + healthcheck: + test: [CMD, python, -c, "import os,urllib.request,urllib.parse; r=urllib.request.Request('http://127.0.0.1:8081/',headers={'Host':urllib.parse.urlsplit(os.environ['UI_ORIGIN']).netloc}); urllib.request.urlopen(r,timeout=3).read()"] + interval: 30s + timeout: 5s + retries: 3 + +# Seed is copied only when config/services.yaml does not exist in the volume. +# After the first start edit settings in the UI; this seed never overwrites them. +configs: + initial-config: + content: | + proxy_ip: ${HOMEGATE_PROXY_IP:?Set the private IP of NPM} + allowed_networks: ${HOMEGATE_ALLOWED_NETWORKS:?Set a YAML list of allowed LAN subnets} + domain_zones: ${HOMEGATE_ZONES:-[home, home.arpa, lab.internal]} + dns_mode: ${HOMEGATE_DNS_MODE:-pihole6} + interval_seconds: 60 + services: [] + ssh_hosts: [] + +# Compose creates secret files. Passwords are not container environment variables. +secrets: + npm_password: + environment: NPM_PASSWORD + pihole_password: + environment: PIHOLE_PASSWORD + ui_password: + environment: UI_PASSWORD + +volumes: + config: + state: + control: diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..4eaa053 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,139 @@ +name: homegate +services: + homegate: + build: . + image: homegate:0.4.0 + restart: unless-stopped + init: true + user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}" + environment: + PYTHONDONTWRITEBYTECODE: "1" + PYTHONUNBUFFERED: "1" + HOMEGATE_CONFIG: /config/services.yaml + HOMEGATE_STATE: /data + HOMEGATE_CONTROL: /control + NPM_URL: "${NPM_URL:?Set NPM_URL in .env}" + NPM_IDENTITY: "${NPM_IDENTITY:?Set NPM_IDENTITY in .env}" + NPM_PASSWORD_FILE: /run/secrets/npm_password + PIHOLE_URL: "${PIHOLE_URL:-}" + PIHOLE_PASSWORD_FILE: /run/secrets/pihole_password + # Optional PEM bundle for HTTPS management APIs; never disable verification. + API_CA_BUNDLE: "${API_CA_BUNDLE:-}" + volumes: + - ./config:/config:ro + - ./state:/data + - ./control:/control + secrets: + - npm_password + - pihole_password + read_only: true + tmpfs: + - /tmp:rw,noexec,nosuid,size=16m + cap_drop: [ALL] + security_opt: + - no-new-privileges:true + pids_limit: 64 + mem_limit: 256m + cpus: 0.5 + healthcheck: + test: [CMD, python, /app/homegate.py, health] + interval: 30s + timeout: 5s + start_period: 120s + retries: 3 + logging: + driver: json-file + options: + max-size: 5m + max-file: "3" + # No ports, Docker socket or host networking required. + + ssh-export: + build: . + image: homegate:0.4.0 + command: [serve] + restart: unless-stopped + init: true + user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}" + environment: + PYTHONDONTWRITEBYTECODE: "1" + PYTHONUNBUFFERED: "1" + HOMEGATE_CONFIG: /config/services.yaml + SSH_BIND_IP: "${SSH_BIND_IP:?Set the Homegate host LAN IP in .env}" + ports: + - "${SSH_BIND_IP:?Set SSH_BIND_IP}:${SSH_PORT:-8099}:8080" + volumes: + - ./config:/config:ro + # This service has NO CA state, API passwords or Docker socket. + read_only: true + tmpfs: + - /tmp:rw,noexec,nosuid,size=16m + cap_drop: [ALL] + security_opt: + - no-new-privileges:true + pids_limit: 64 + mem_limit: 128m + cpus: 0.5 + healthcheck: + test: [CMD, python, -c, "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=3).read()"] + interval: 30s + timeout: 5s + retries: 3 + logging: + driver: json-file + options: + max-size: 5m + max-file: "3" + + ui: + build: . + image: homegate:0.4.0 + entrypoint: [python, /app/homegate_ui.py] + command: [] + restart: unless-stopped + init: true + user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}" + environment: + PYTHONDONTWRITEBYTECODE: "1" + PYTHONUNBUFFERED: "1" + HOMEGATE_CONFIG: /config/services.yaml + HOMEGATE_CONTROL: /control + UI_BIND_IP: "${UI_BIND_IP:?Set the Homegate host LAN IP}" + UI_ORIGIN: "${UI_ORIGIN:?Set the exact panel URL in .env}" + UI_PASSWORD_FILE: /run/secrets/ui_password + SSH_PUBLIC_URL: "http://${SSH_BIND_IP}:${SSH_PORT:-8099}/ssh-config" + ports: + - "${UI_BIND_IP:?Set UI_BIND_IP}:${UI_PORT:-8098}:8081" + volumes: + - ./config:/config + - ./control:/control + secrets: + - ui_password + # No CA private keys, NPM/Pi-hole passwords or Docker socket in the UI. + read_only: true + tmpfs: + - /tmp:rw,noexec,nosuid,size=16m + cap_drop: [ALL] + security_opt: + - no-new-privileges:true + pids_limit: 64 + mem_limit: 128m + cpus: 0.5 + healthcheck: + test: [CMD, python, -c, "import os,urllib.request,urllib.parse; r=urllib.request.Request('http://127.0.0.1:8081/',headers={'Host':urllib.parse.urlsplit(os.environ['UI_ORIGIN']).netloc}); urllib.request.urlopen(r,timeout=3).read()"] + interval: 30s + timeout: 5s + retries: 3 + logging: + driver: json-file + options: + max-size: 5m + max-file: "3" + +secrets: + ui_password: + file: ./secrets/ui_password + npm_password: + file: ./secrets/npm_password + pihole_password: + file: ./secrets/pihole_password diff --git a/config/services.yaml b/config/services.yaml new file mode 100644 index 0000000..3816157 --- /dev/null +++ b/config/services.yaml @@ -0,0 +1,50 @@ +# LAN address where NPM accepts connections on 443 (NOT the upstream VM). +proxy_ip: 192.168.0.10 +# DNS suffixes allowed for web services and certificates. ASCII/punycode. +# Add custom zones before first startup; expanding an existing CA needs rotate-ca. +domain_zones: + - home + - home.arpa + - lab.internal +# Requests from other source addresses receive 403. Use your actual subnet. +allowed_networks: + - 192.168.0.0/24 + +# pihole6 = automatic local DNS through Pi-hole API. +# manual = configure DNS in Pi-hole yourself; also works with Pi-hole 5. +dns_mode: pihole6 +interval_seconds: 60 + +services: + - hostname: pve.home + # Optional label shown in the UI; domain and SSH aliases stay independent. + # display_name: Proxmox + upstream: https://192.168.0.137:8006 + # Explicit exception for the default self-signed Proxmox certificate. + # Browser -> NPM is still verified HTTPS after installing Homegate's root CA. + upstream_tls_verify: false + websocket: true + timeout_seconds: 3600 + max_body_mb: 10240 + ssh: + alias: pve + user: root + port: 22 + # host defaults to 192.168.0.137 from upstream (NOT the NPM address). + + # - hostname: grafana.home + # upstream: http://192.168.0.120:3000 + # - hostname: nas.home.arpa + # upstream: https://192.168.0.130:443 + # upstream_tls_name: nas.home.arpa + # upstream_ca_file: /data/custom-trust/nas-ca.pem # path INSIDE NPM + # upstream_tls_verify: true + # enabled: true + +# Optional SSH-only machines. No DNS or NPM objects are created for these. +ssh_hosts: [] +# ssh_hosts: +# - aliases: [backup, backup.lab.internal] +# host: 192.168.0.150 +# port: 2222 +# user: admin diff --git a/homegate.py b/homegate.py new file mode 100644 index 0000000..7f3fe84 --- /dev/null +++ b/homegate.py @@ -0,0 +1,692 @@ +"""Local DNS/NPM controller and a separate read-only LAN SSH config exporter.""" +from __future__ import annotations + +import argparse +import copy +import fcntl +import hashlib +import ipaddress +import json +import logging +import os +from pathlib import Path +import re +import signal +import shutil +import sys +import tempfile +import threading +import time +from datetime import datetime, timedelta, timezone +from urllib.parse import quote, urlsplit +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import uuid + +import requests +import yaml +from cryptography import x509 +from cryptography.exceptions import InvalidSignature +from cryptography.hazmat.primitives import hashes, serialization +from cryptography.hazmat.primitives.asymmetric import ec +from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID +from sync_ssh import render_ssh, validate_entry + +LOG = logging.getLogger("homegate") +STOP = threading.Event() +PRIVATE = tuple(ipaddress.ip_network(n) for n in + ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7")) +LABEL = r"[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?" +DOMAIN = re.compile(r"(?=.{1,253}$)" + LABEL + r"(?:\." + LABEL + r")+$") +ZONE = re.compile(r"(?=.{1,253}$)" + LABEL + r"(?:\." + LABEL + r")*$") +DEFAULT_ZONES = ["home", "home.arpa"] + + +class Error(RuntimeError): + pass + + +def require(ok, message): + if not ok: + raise Error(message) + + +def private_address(value): + address = ipaddress.ip_address(value) + require(any(address.version == n.version and address in n for n in PRIVATE), + f"Expected RFC1918 or ULA address: {value}") + return str(address) + + +def number(value, minimum, maximum, name): + require(type(value) is int and minimum <= value <= maximum, + f"{name} must be an integer between {minimum} and {maximum}") + return value + + +def boolean(value, name): + require(type(value) is bool, f"{name} must be true or false") + return value + + +def in_zones(hostname, zones): + return any(hostname == zone or hostname.endswith("." + zone) for zone in zones) + + +def normalize_zones(value): + require(isinstance(value, list) and 0 < len(value) <= 64, "domain_zones must contain 1–64 zones") + zones = [] + for zone in value: + require(isinstance(zone, str), "Domain zones must be strings") + zone = zone.strip(".").lower() + require(ZONE.fullmatch(zone) is not None, "Invalid domain zone; use ASCII/punycode without wildcards") + require(zone not in zones, "Duplicate domain zone: " + zone) + zones.append(zone) + return zones + + +def load_config(path): + return validate_config(yaml.safe_load(Path(path).read_text())) + + +def validate_config(value): + c = copy.deepcopy(value) + require(isinstance(c, dict), "Config must be a YAML mapping") + require(not set(c) - {"proxy_ip", "allowed_networks", "dns_mode", "interval_seconds", "services", + "domain_zones", "ssh_hosts"}, + "Unknown top-level config key") + c["domain_zones"] = normalize_zones(c.get("domain_zones", DEFAULT_ZONES)) + c["proxy_ip"] = private_address(c["proxy_ip"]) + require(isinstance(c.get("allowed_networks"), list) and c["allowed_networks"], + "allowed_networks must be a non-empty list") + nets = [] + for raw in c["allowed_networks"]: + net = ipaddress.ip_network(raw, strict=True) + require(any(net.version == n.version and net.subnet_of(n) for n in PRIVATE), + "allowed_networks must be RFC1918 or ULA subnets") + nets.append(str(net)) + c["allowed_networks"] = nets + c.setdefault("dns_mode", "pihole6") + require(c["dns_mode"] in ("pihole6", "manual"), "dns_mode must be pihole6 or manual") + c["interval_seconds"] = number(c.get("interval_seconds", 60), 30, 3600, "interval_seconds") + require(isinstance(c.get("services"), list), "services must be a list") + seen = set() + for r in c["services"]: + require(isinstance(r, dict), "Each service must be a mapping") + require(not set(r) - {"hostname", "display_name", "upstream", "upstream_tls_verify", "upstream_tls_name", + "upstream_ca_file", "websocket", "timeout_seconds", "max_body_mb", "enabled", "ssh"}, + "Unknown service config key") + if "display_name" in r: + name = r["display_name"] + require(isinstance(name, str) and bool(name.strip()) and len(name) <= 100 + and not any(ord(ch) < 32 or ord(ch) == 127 for ch in name), + "display_name must be a non-empty single-line string of at most 100 characters") + host = r["hostname"] + require(isinstance(host, str) and DOMAIN.fullmatch(host) and + in_zones(host, c["domain_zones"]), + "hostname must be a lowercase DNS name in domain_zones") + require(host not in seen, f"Duplicate hostname: {host}") + seen.add(host) + u = urlsplit(r["upstream"]) + require(u.scheme in ("http", "https") and not u.username and not u.password + and u.path in ("", "/") and not u.query and not u.fragment, + f"{host}: upstream must be http(s)://private-IP:port without path or credentials") + r["forward_host"] = private_address(u.hostname) + require(":" not in r["forward_host"], "This release supports IPv4 upstream VMs only") + r["forward_scheme"] = u.scheme + r["forward_port"] = number(u.port or (443 if u.scheme == "https" else 80), 1, 65535, "port") + for k, default in (("enabled", True), ("websocket", True), ("upstream_tls_verify", True)): + r[k] = boolean(r.get(k, default), k) + r["timeout_seconds"] = number(r.get("timeout_seconds", 3600), 1, 86400, "timeout_seconds") + r["max_body_mb"] = number(r.get("max_body_mb", 1024), 1, 102400, "max_body_mb") + if "upstream_tls_name" in r: + require(isinstance(r["upstream_tls_name"], str) and DOMAIN.fullmatch(r["upstream_tls_name"]), + "Invalid upstream_tls_name") + if "upstream_ca_file" in r: + p = r["upstream_ca_file"] + require(isinstance(p, str) and re.fullmatch(r"/[a-zA-Z0-9_./-]+", p) + and ".." not in Path(p).parts, "Unsafe upstream_ca_file path") + if "ssh" in r: + s = r["ssh"] + require(isinstance(s, dict) and not set(s) - {"alias", "host", "port", "user", "enabled"}, + "service.ssh accepts alias, host, port, user and enabled") + boolean(s.get("enabled", True), "ssh.enabled") + require(isinstance(c.get("ssh_hosts", []), list), "ssh_hosts must be a list") + # Validate the complete inventory (including duplicate aliases) before any side effects. + ssh_entries(c) + return c + + +def ssh_entries(config): + entries = [] + for route in config["services"]: + s = route.get("ssh") + if s is None: + continue + aliases = [route["hostname"]] + if s.get("alias") and s["alias"] not in aliases: + aliases.insert(0, s["alias"]) + entry = {"aliases": aliases, "host": s.get("host", route["forward_host"]), + "port": s.get("port", 22)} + if "user" in s: + entry["user"] = s["user"] + validate_entry(entry) + if route["enabled"] and s.get("enabled", True): + entries.append(entry) + for item in config.get("ssh_hosts", []): + require(isinstance(item, dict) and not set(item) - {"aliases", "host", "port", "user", "enabled"}, + "ssh_hosts entries accept aliases, host, port, user and enabled") + enabled = boolean(item.get("enabled", True), "ssh_hosts.enabled") + entry = {k: v for k, v in item.items() if k != "enabled"} + entry.setdefault("port", 22) + validate_entry(entry) + if enabled: + entries.append(entry) + render_ssh(entries) # Also rejects aliases shared by two different entries. + return entries + + +def atomic(path, data, mode=0o600): + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) + temporary = path.with_name(path.name + ".tmp") + fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode) + with os.fdopen(fd, "wb") as f: + f.write(data if isinstance(data, bytes) else data.encode()) + f.flush() + os.fsync(f.fileno()) + os.chmod(temporary, mode) + os.replace(temporary, path) + + +def save_json(path, value): + atomic(path, json.dumps(value, indent=2)) + + +def read_json(path, default=None): + return json.loads(path.read_text()) if path.exists() else default + + +def now(): + return datetime.now(timezone.utc) + + +def pem_key(key): + return key.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, + serialization.NoEncryption()).decode() + + +class Authority: + def __init__(self, state, zones=None): + self.state = state + self.zones = normalize_zones(zones if zones is not None else DEFAULT_ZONES) + bundle_path = state / "ca.json" + bundle = read_json(bundle_path) + if bundle is None: + require(not (state / "registry.json").exists(), "CA missing from existing state; restore backup") + key = ec.generate_private_key(ec.SECP384R1()) + subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "Homegate Local Root CA")]) + cert = (x509.CertificateBuilder().subject_name(subject).issuer_name(subject) + .public_key(key.public_key()).serial_number(x509.random_serial_number()) + .not_valid_before(now() - timedelta(minutes=5)) + .not_valid_after(now() + timedelta(days=3650)) + .add_extension(x509.BasicConstraints(ca=True, path_length=0), critical=True) + .add_extension(x509.KeyUsage(False, False, False, False, False, True, True, False, False), True) + .add_extension(x509.SubjectKeyIdentifier.from_public_key(key.public_key()), False) + .add_extension(x509.NameConstraints([x509.DNSName(z) for z in self.zones], None), True) + .sign(key, hashes.SHA384())) + bundle = {"key": pem_key(key), "cert": cert.public_bytes(serialization.Encoding.PEM).decode()} + save_json(bundle_path, bundle) + LOG.info("Created local root CA; install root-ca.crt on client devices") + self.key = serialization.load_pem_private_key(bundle["key"].encode(), password=None) + self.cert = x509.load_pem_x509_certificate(bundle["cert"].encode()) + constraints = self.cert.extensions.get_extension_for_class(x509.NameConstraints).value + self.permitted_zones = [n.value for n in constraints.permitted_subtrees if isinstance(n, x509.DNSName)] + require(self.key.public_key().public_numbers() == self.cert.public_key().public_numbers(), + "CA key does not match certificate") + require(self.cert.not_valid_after_utc > now() + timedelta(days=91), + "Root CA expires in under 91 days; migrate client trust to a new CA") + atomic(state / "root-ca.crt", bundle["cert"], 0o644) + + def leaf(self, hostname): + require(self.cert.not_valid_after_utc > now() + timedelta(days=91), + "Root CA expires in under 91 days; migrate client trust to a new CA") + require(DOMAIN.fullmatch(hostname) and in_zones(hostname, self.zones), + "Refusing to issue outside configured domain_zones") + require(in_zones(hostname, self.permitted_zones), + "Existing root CA does not permit this zone; stop controller and run rotate-ca, then install new root on clients") + path = self.state / "issued" / f"{hostname}.json" + bundle = read_json(path) + if bundle: + cert = x509.load_pem_x509_certificate(bundle["cert"].encode()) + same_issuer = True + try: + cert.verify_directly_issued_by(self.cert) + except (InvalidSignature, ValueError): + same_issuer = False # A deliberate CA rotation requires new leaves. + if same_issuer and cert.not_valid_after_utc > now() + timedelta(days=30): + key = serialization.load_pem_private_key(bundle["key"].encode(), password=None) + require(key.public_key().public_numbers() == cert.public_key().public_numbers(), + "Leaf private key does not match certificate") + require(cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value + .get_values_for_type(x509.DNSName) == [hostname], "Leaf SAN mismatch") + return bundle + key = ec.generate_private_key(ec.SECP256R1()) + subject = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, hostname[:64])]) + cert = (x509.CertificateBuilder().subject_name(subject).issuer_name(self.cert.subject) + .public_key(key.public_key()).serial_number(x509.random_serial_number()) + .not_valid_before(now() - timedelta(minutes=5)).not_valid_after(now() + timedelta(days=90)) + .add_extension(x509.BasicConstraints(ca=False, path_length=None), True) + .add_extension(x509.KeyUsage(True, False, False, False, False, False, False, False, False), True) + .add_extension(x509.ExtendedKeyUsage([ExtendedKeyUsageOID.SERVER_AUTH]), False) + .add_extension(x509.SubjectAlternativeName([x509.DNSName(hostname)]), False) + .add_extension(x509.SubjectKeyIdentifier.from_public_key(key.public_key()), False) + .add_extension(x509.AuthorityKeyIdentifier.from_issuer_public_key(self.key.public_key()), False) + .sign(self.key, hashes.SHA384())) + bundle = {"key": pem_key(key), "cert": cert.public_bytes(serialization.Encoding.PEM).decode()} + save_json(path, bundle) + LOG.info("Issued 90-day certificate for %s", hostname) + return bundle + + +def rotate_ca(state, zones): + """Explicit trust migration; preserve instance/route IDs and old CA for recovery.""" + require((state / "ca.json").exists(), "No existing CA; run once/run to initialize it") + history = state / "ca-history" / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ-") + uuid.uuid4().hex[:8]) + history.mkdir(parents=True, mode=0o700) + # Stage the new CA before changing the active one. ca.json is the source of truth. + with tempfile.TemporaryDirectory(dir=state, prefix="ca-next-") as temp: + prepared = Path(temp) + Authority(prepared, zones) + for name in ("ca.json", "root-ca.crt"): + if (state / name).exists(): + shutil.copy2(state / name, history / name) + atomic(state / "ca.json", (prepared / "ca.json").read_bytes()) + atomic(state / "root-ca.crt", (prepared / "root-ca.crt").read_bytes(), 0o644) + LOG.warning("CA rotated. Install state/root-ca.crt on clients before restarting. Previous CA: %s", history) + return history + + +def export_response(path, peer, config_path): + """No directory serving. Only a validated SSH inventory can leave this process.""" + config = load_config(config_path) + address = ipaddress.ip_address(peer) + if address.version == 6 and address.ipv4_mapped: + address = address.ipv4_mapped + local_health = path == "/healthz" and address.is_loopback + allowed = any(address.version == n.version and address in n for n in + (ipaddress.ip_network(raw) for raw in config["allowed_networks"])) + if not allowed and not local_health: + return 403, b"Forbidden\n", "text/plain; charset=utf-8" + if path == "/healthz": + return 200, b"ok\n", "text/plain; charset=utf-8" + if path == "/ssh-config": + return 200, render_ssh(ssh_entries(config)).encode(), "text/plain; charset=utf-8" + return 404, b"Not found\n", "text/plain; charset=utf-8" + + +def export_handler(config_path): + class Handler(BaseHTTPRequestHandler): + server_version = "Homegate" + sys_version = "" + + def setup(self): + super().setup() + self.connection.settimeout(10) + + def do_GET(self): + try: + status, body, content_type = export_response(self.path, self.client_address[0], config_path) + except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError): + status, body, content_type = 503, b"Invalid or unavailable configuration\n", "text/plain" + self.send_response(status) + self.send_header("Content-Type", content_type) + self.send_header("Content-Length", str(len(body))) + self.send_header("Cache-Control", "no-store") + self.send_header("X-Content-Type-Options", "nosniff") + if status == 200 and self.path == "/ssh-config": + self.send_header("Content-Disposition", 'attachment; filename="homegate.conf"') + self.end_headers() + if self.command != "HEAD": + self.wfile.write(body) + + do_HEAD = do_GET + + def log_message(self, fmt, *args): + LOG.info("SSH export: peer=%s status=%s", self.client_address[0], args[1] if len(args) > 1 else "-") + + return Handler + + +def serve_export(config_path): + load_config(config_path) + # Compose requires an explicit private host IP; never publish on every host interface. + bind_ip = private_address(os.environ.get("SSH_BIND_IP", "")) + require(ipaddress.ip_address(bind_ip).version == 4, "SSH_BIND_IP must be a private IPv4 address") + with ThreadingHTTPServer(("0.0.0.0", 8080), export_handler(config_path)) as server: + LOG.info("SSH export available through Docker binding %s; path /ssh-config", bind_ip) + server.serve_forever() + + +class API: + def __init__(self, url, label, verify=True): + u = urlsplit(url) + require(u.scheme in ("http", "https") and u.hostname and not u.username and not u.password + and u.path in ("", "/") and not u.query and not u.fragment, + f"{label}_URL must be http(s)://host:port without /api, /admin or credentials") + self.base = url.rstrip("/") + "/api" + self.label = label + self.session = requests.Session() + self.session.trust_env = False # Keep LAN credentials out of environment HTTP proxies. + self.session.verify = verify + + def call(self, method, path, **kwargs): + try: + response = self.session.request(method, self.base + path, timeout=(5, 30), + allow_redirects=False, **kwargs) + except requests.RequestException: + raise Error(f"{self.label}: connection or TLS error at {path}") from None + require(200 <= response.status_code < 300, + f"{self.label}: HTTP {response.status_code} at {path}; check credentials, version and permissions") + # Do not log response bodies: NPM upload responses contain the private key. + if not response.content: + return None + try: + return response.json() + except ValueError: + raise Error(f"{self.label}: non-JSON response at {path}; check management URL") from None + + def close(self): + self.session.close() + + +class NPM(API): + def login(self, identity, password): + token = self.call("POST", "/tokens", json={"identity": identity, "secret": password}) + self.session.headers["Authorization"] = "Bearer " + token["token"] + + def inventory(self): + self.hosts = self.call("GET", "/nginx/proxy-hosts") + self.certs = self.call("GET", "/nginx/certificates") + + def find_host(self, hostname, marker): + matches = [h for h in self.hosts if hostname in h["domain_names"]] + require(len(matches) <= 1, f"Multiple NPM hosts for {hostname}") + if not matches: + return None + host = matches[0] + require(host["domain_names"] == [hostname] and + host.get("advanced_config", "").splitlines()[:1] == [marker], + f"{hostname}: NPM host already exists and is not managed by this instance") + return host + + def certificate(self, name, bundle, uploaded): + matches = [c for c in self.certs if c.get("nice_name") == name] + require(len(matches) <= 1, f"Duplicate managed certificate: {name}") + cert = matches[0] if matches else self.call("POST", "/nginx/certificates", + json={"provider": "other", "nice_name": name}) + require(cert["provider"] == "other", "Expected a custom NPM certificate") + if not matches: + self.certs.append(cert) + digest = hashlib.sha256(bundle["cert"].encode()).hexdigest() + signature = {"id": cert["id"], "sha256": digest} + changed = signature != uploaded or not cert.get("meta", {}).get("certificate") + if changed: + self.call("POST", f'/nginx/certificates/{cert["id"]}/upload', files={ + "certificate": ("certificate.pem", bundle["cert"], "application/x-pem-file"), + "certificate_key": ("key.pem", bundle["key"], "application/x-pem-file"), + }) + return cert["id"], changed, signature + + def host(self, existing, payload, force_reload=False): + if existing: + unhealthy = payload["enabled"] and existing.get("meta", {}).get("nginx_online") is not True + if force_reload or unhealthy or any(existing.get(k) != v for k, v in payload.items()): + result = self.call("PUT", f'/nginx/proxy-hosts/{existing["id"]}', json=payload) + else: + result = existing + else: + result = self.call("POST", "/nginx/proxy-hosts", json=payload) + self.hosts.append(result) + if payload["enabled"]: + require(result.get("meta", {}).get("nginx_online") is True, + "NPM could not activate nginx configuration; inspect the host in NPM") + return result + + +class PiHole(API): + def login(self, password): + session = self.call("POST", "/auth", json={"password": password})["session"] + require(session.get("valid") and session.get("sid"), "Pi-hole authentication failed") + self.session.headers["X-FTL-SID"] = session["sid"] + self.session.headers["X-FTL-CSRF"] = session["csrf"] + + def records(self): + dns = self.call("GET", "/config/dns")["config"]["dns"] + self.hosts = dns["hosts"] + self.cnames = dns.get("cnameRecords", []) + + def check(self, hostname, address): + for entry in self.hosts: + fields = entry.split("#", 1)[0].split() + if len(fields) > 1 and hostname in [s.lower().rstrip(".") for s in fields[1:]]: + require(fields[0] == address, f"{hostname}: conflicting Pi-hole record: {entry}") + for entry in self.cnames: + require(entry.split(",")[0].strip().lower().rstrip(".") != hostname, + f"{hostname}: existing Pi-hole CNAME; remove it or use manual DNS") + + def ensure(self, hostname, address): + self.check(hostname, address) + if any(hostname in [s.lower().rstrip(".") for s in e.split("#", 1)[0].split()[1:]] for e in self.hosts): + return + entry = f"{address} {hostname}" + self.call("PUT", "/config/dns/hosts/" + quote(entry, safe="")) + self.hosts.append(entry) + LOG.info("DNS: %s -> %s", hostname, address) + + def close(self): + try: + if "X-FTL-SID" in self.session.headers: + self.call("DELETE", "/auth") + except Error: + LOG.warning("Pi-hole logout failed; session will expire") + finally: + super().close() + + +def payload(config, route, cert_id, marker): + advanced = [marker] + advanced += [f"allow {net};" for net in config["allowed_networks"]] + ["deny all;"] + advanced += [f'client_max_body_size {route["max_body_mb"]}m;', "proxy_buffering off;", + "proxy_request_buffering off;", f'proxy_read_timeout {route["timeout_seconds"]}s;', + f'proxy_send_timeout {route["timeout_seconds"]}s;', "proxy_connect_timeout 10s;"] + if route["forward_scheme"] == "https": + advanced += ["proxy_ssl_server_name on;", + f'proxy_ssl_name {route.get("upstream_tls_name", route["forward_host"])};', + "proxy_ssl_verify " + ("on;" if route["upstream_tls_verify"] else "off;")] + if route["upstream_tls_verify"]: + advanced += ["proxy_ssl_verify_depth 3;", "proxy_ssl_trusted_certificate " + + route.get("upstream_ca_file", "/etc/ssl/certs/ca-certificates.crt") + ";"] + return {"domain_names": [route["hostname"]], "forward_scheme": route["forward_scheme"], + "forward_host": route["forward_host"], "forward_port": route["forward_port"], + "certificate_id": cert_id, "ssl_forced": True, "http2_support": True, + "hsts_enabled": False, "hsts_subdomains": False, "block_exploits": False, + "caching_enabled": False, "allow_websocket_upgrade": route["websocket"], + "access_list_id": 0, "advanced_config": "\n".join(advanced), + "locations": [], "enabled": route["enabled"]} + + +def reconcile(config, state, ca, registry, npm, dns): + npm.inventory() + dns_error = False + if dns: + try: + dns.records() + except Error as exc: + LOG.error("DNS unavailable; continuing certificate/proxy maintenance: %s", exc) + dns = None + dns_error = True + failures = [] + current = {r["hostname"] for r in config["services"]} + for stale in set(registry["routes"]) - current: + LOG.warning("%s removed from file; NPM host and DNS retained. Disable/delete explicitly in their UIs.", stale) + for route in config["services"]: + host = route["hostname"] + name = f'homegate:{registry["instance"]}:{host}' + marker = "# " + name + try: + existing = npm.find_host(host, marker) + if dns and route["enabled"]: + dns.check(host, config["proxy_ip"]) + bundle = ca.leaf(host) + previous = registry["routes"].get(host, {}) + cert_id, changed, signature = npm.certificate(name, bundle, previous.get("uploaded")) + result = npm.host(existing, payload(config, route, cert_id, marker), force_reload=changed) + # Save only AFTER nginx accepts the host/reload. Failed upload/reload is retried. + registry["routes"][host] = {"host_id": result["id"], "uploaded": signature} + save_json(state / "registry.json", registry) + # Publish DNS only once proxy and TLS are configured. + if dns and route["enabled"]: + dns.ensure(host, config["proxy_ip"]) + if changed or not existing: + LOG.info("Configured https://%s -> %s", host, route["upstream"]) + except (Error, ValueError, KeyError, OSError) as exc: + failures.append(host) + LOG.error("%s: %s", host, exc) + require(not failures, "Routes failed: " + ", ".join(failures)) + require(not dns_error, "DNS sync failed; proxy/certificate maintenance completed") + + +def secret(name): + p = os.environ.get(name + "_PASSWORD_FILE", f"/run/secrets/{name.lower()}_password") + value = Path(p).read_text().rstrip("\r\n") + require(bool(value), f"Empty {name} password file") + return value + + +def cycle(config, state, ca, registry): + verify = os.environ.get("API_CA_BUNDLE") or True + npm = NPM(os.environ.get("NPM_URL", ""), "NPM", verify) + dns = None + dns_error = False + try: + npm.login(os.environ.get("NPM_IDENTITY", ""), secret("NPM")) + if config["dns_mode"] == "pihole6": + dns = PiHole(os.environ.get("PIHOLE_URL", ""), "PIHOLE", verify) + try: + dns.login(secret("PIHOLE")) + except (Error, OSError) as exc: + LOG.error("Pi-hole login unavailable; continuing proxy maintenance: %s", exc) + dns.close() + dns = None + dns_error = True + reconcile(config, state, ca, registry, npm, dns) + require(not dns_error, "Pi-hole login failed; proxy/certificate maintenance completed") + finally: + npm.close() + if dns: + dns.close() + + +def publish_panel_status(control, revision, config, state, ca, ok, error): + """Export only public certificate/status information to the UI's separate volume.""" + control.mkdir(parents=True, exist_ok=True, mode=0o700) + previous = read_json(control / "status.json", {}) + certs = [] + for route in config["services"]: + path = state / "issued" / (route["hostname"] + ".json") + if path.exists(): + cert = x509.load_pem_x509_certificate(read_json(path)["cert"].encode()) + certs.append({"hostname": route["hostname"], "expires": cert.not_valid_after_utc.isoformat()}) + save_json(control / "status.json", { + "ok": ok, "time": time.time(), "max_age": max(180, config["interval_seconds"] * 3), + "error": error, "applied_revision": revision if ok else previous.get("applied_revision"), + "root": {"pem": ca.cert.public_bytes(serialization.Encoding.PEM).decode(), + "fingerprint": ca.cert.fingerprint(hashes.SHA256()).hex(":"), + "expires": ca.cert.not_valid_after_utc.isoformat(), "zones": ca.permitted_zones}, + "certificates": certs, + }) + + +def main(): + os.umask(0o077) + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("command", choices=("run", "once", "validate", "health", "fingerprint", "rotate-ca", "serve", "ssh-config"), default="run", nargs="?") + args = parser.parse_args() + state = Path(os.environ.get("HOMEGATE_STATE", "/data")) + path = Path(os.environ.get("HOMEGATE_CONFIG", "/config/services.yaml")) + control = Path(os.environ.get("HOMEGATE_CONTROL", "/control")) + if args.command == "serve": + serve_export(path) + return 0 + if args.command == "health": + status = read_json(state / "status.json", {}) + return 0 if status.get("ok") and time.time() - status.get("time", 0) < status.get("max_age", 180) else 1 + if args.command == "fingerprint": + cert = x509.load_pem_x509_certificate((state / "root-ca.crt").read_bytes()) + print("SHA256:", cert.fingerprint(hashes.SHA256()).hex(":")) + return 0 + config = load_config(path) + if args.command == "ssh-config": + print(render_ssh(ssh_entries(config)), end="") + return 0 + if args.command == "validate": + for route in config["services"]: + print(f'{route["hostname"]} -> {config["proxy_ip"]}:443 -> {route["upstream"]}') + print(f'Config valid; DNS mode: {config["dns_mode"]}. No API calls were made.') + print(f'Domain zones: {", ".join(config["domain_zones"])}; SSH hosts: {len(ssh_entries(config))}') + return 0 + state.mkdir(parents=True, exist_ok=True, mode=0o700) + with (state / "controller.lock").open("a") as lock: + try: + fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError: + raise Error("Another Homegate controller is already using this state") from None + if args.command == "rotate-ca": + rotate_ca(state, config["domain_zones"]) + return 0 + ca = Authority(state, config["domain_zones"]) + registry = read_json(state / "registry.json", {"instance": str(uuid.uuid4()), "routes": {}}) + save_json(state / "registry.json", registry) + for sig in (signal.SIGTERM, signal.SIGINT): + signal.signal(sig, lambda *_: STOP.set()) + while not STOP.is_set(): + ok = False + sync_error = None + revision = None + request_path = control / "sync-request.json" + request_before = request_path.read_bytes() if request_path.exists() else None + try: + # Hash the same bytes we apply, even when the UI saves during a slow API call. + raw = path.read_bytes() + revision = hashlib.sha256(raw).hexdigest() + config = validate_config(yaml.safe_load(raw)) + ca.zones = config["domain_zones"] + cycle(config, state, ca, registry) + ok = True + except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc: + sync_error = str(exc) + LOG.error("Sync failed: %s", exc) + save_json(state / "status.json", {"ok": ok, "time": time.time(), + "max_age": max(180, config["interval_seconds"] * 3)}) + try: + publish_panel_status(control, revision, config, state, ca, ok, sync_error) + except (ValueError, KeyError, OSError) as exc: + LOG.warning("Could not export panel status: %s", exc) + if args.command == "once": + return 0 if ok else 1 + deadline = time.monotonic() + config["interval_seconds"] + while not STOP.is_set() and time.monotonic() < deadline: + current_request = request_path.read_bytes() if request_path.exists() else None + if current_request != request_before: + break + STOP.wait(min(2, max(0, deadline - time.monotonic()))) + return 0 + + +if __name__ == "__main__": + try: + sys.exit(main()) + except (Error, ValueError, KeyError, TypeError, OSError, yaml.YAMLError) as exc: + LOG.error("%s", exc) + sys.exit(1) diff --git a/homegate_ui.py b/homegate_ui.py new file mode 100644 index 0000000..679e723 --- /dev/null +++ b/homegate_ui.py @@ -0,0 +1,275 @@ +"""Homegate local management UI. Config writes + public controller status only.""" +import argparse +from collections import defaultdict +import fcntl +import hashlib +import hmac +from http.cookies import SimpleCookie +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import ipaddress +import json +import logging +import os +from pathlib import Path +import secrets +import threading +import time +from urllib.parse import urlsplit + +import yaml +import homegate as h + +LOG = logging.getLogger("homegate.ui") +BASE = Path(__file__).resolve().parent +MAX_BODY = 1024 * 1024 + + +class UIError(Exception): + def __init__(self, message, status=400): + self.status = status + super().__init__(message) + + +class Panel: + def __init__(self, config, control, origin, local=False, password_file=None, ssh_url=""): + self.config = Path(config) + self.control = Path(control) + self.origin = origin.rstrip("/") + self.authority = urlsplit(self.origin).netloc + parsed_origin = urlsplit(self.origin) + if (parsed_origin.scheme not in ("http", "https") or not self.authority + or parsed_origin.path or parsed_origin.query or parsed_origin.fragment or parsed_origin.username): + raise UIError("UI_ORIGIN must be the exact http(s)://host:port of the panel") + self.local = local + self.password_file = password_file + self.ssh_url = ssh_url + self.sessions = {} + self.attempts = defaultdict(list) + self.mutex = threading.RLock() + if not local and (not password_file or len(Path(password_file).read_text().strip()) < 12): + raise UIError("UI password must contain at least 12 characters; run setup.sh") + h.load_config(self.config) + + def config_data(self): + raw = self.config.read_bytes() + value = yaml.safe_load(raw) + h.validate_config(value) + return value, hashlib.sha256(raw).hexdigest() + + def allowed(self, peer): + address = ipaddress.ip_address(peer) + if address.version == 6 and address.ipv4_mapped: + address = address.ipv4_mapped + if address.is_loopback: + return True + if self.local: + return False + c = h.load_config(self.config) + return any(address.version == net.version and address in net for net in + (ipaddress.ip_network(n) for n in c["allowed_networks"])) + + def session(self, cookie): + jar = SimpleCookie() + try: + jar.load(cookie or "") + token = jar["homegate_session"].value if "homegate_session" in jar else "" + except Exception: + token = "" + with self.mutex: + self.sessions = {k: v for k, v in self.sessions.items() if v["expires"] > time.time()} + return token, self.sessions.get(token) + + def new_session(self): + with self.mutex: + if len(self.sessions) >= 128: + self.sessions.pop(next(iter(self.sessions))) + token = secrets.token_urlsafe(32) + entry = {"csrf": secrets.token_urlsafe(32), "expires": time.time() + 12 * 3600} + self.sessions[token] = entry + return token, entry + + def login(self, password, peer): + with self.mutex: + self.attempts = defaultdict(list, {k: [t for t in v if time.time() - t < 60] + for k, v in self.attempts.items() if any(time.time() - t < 60 for t in v)}) + attempts = self.attempts[peer] + if len(attempts) >= 5: + raise UIError("Слишком много попыток. Подождите минуту.", 429) + attempts.append(time.time()) + expected = Path(self.password_file).read_text().rstrip("\r\n") + if not isinstance(password, str) or not hmac.compare_digest(password.encode(), expected.encode()): + raise UIError("Неверный пароль", 401) + self.attempts.pop(peer, None) + return self.new_session() + + def status(self): + value, revision = self.config_data() + snapshot = h.read_json(self.control / "status.json", {}) + fresh = bool(snapshot) and time.time() - snapshot.get("time", 0) < snapshot.get("max_age", 180) + history = h.read_json(self.control / "ui-history.json", []) + return {"config": value, "revision": revision, "mode": "local" if self.local else "lan", + "ssh_url": self.ssh_url, "controller": {**snapshot, "fresh": fresh}, "history": history[:8]} + + def save(self, value, revision): + h.validate_config(value) + data = yaml.safe_dump(value, sort_keys=False, allow_unicode=True).encode() + with self.mutex: + lock_path = self.config.parent / ".ui-config.lock" + with lock_path.open("a") as lock: + fcntl.flock(lock, fcntl.LOCK_EX) + original = self.config.read_bytes() + if hashlib.sha256(original).hexdigest() != revision: + raise UIError("Настройки уже изменились. Обновите страницу и повторите сохранение.", 409) + backup = self.config.parent / "backups" / f"services-{time.time_ns()}.yaml" + h.atomic(backup, original) + # Preserve readability for the export container running under the same UID. + h.atomic(self.config, data, 0o644) + backups = sorted(backup.parent.glob("services-*.yaml")) + for stale in backups[:-20]: + stale.unlink() + self.control.mkdir(parents=True, exist_ok=True, mode=0o700) + history = h.read_json(self.control / "ui-history.json", []) + h.save_json(self.control / "ui-history.json", [{"time": time.time(), "text": "Настройки сохранены"}] + history[:19]) + return self.status() + + def request_sync(self): + self.control.mkdir(parents=True, exist_ok=True, mode=0o700) + h.save_json(self.control / "sync-request.json", {"id": secrets.token_hex(16), "time": time.time()}) + return {"queued": True, "fresh": self.status()["controller"]["fresh"]} + + +def handler_for(panel): + class Handler(BaseHTTPRequestHandler): + server_version = "Homegate" + sys_version = "" + + def setup(self): + super().setup() + self.connection.settimeout(15) + + def respond(self, status, body, content_type="application/json; charset=utf-8", cookie=None, filename=None): + if not isinstance(body, bytes): + body = json.dumps(body, ensure_ascii=False).encode() + self.send_response(status) + self.send_header("Content-Type", content_type) + self.send_header("Content-Length", str(len(body))) + self.send_header("Cache-Control", "no-store") + self.send_header("X-Content-Type-Options", "nosniff") + self.send_header("Referrer-Policy", "no-referrer") + self.send_header("X-Frame-Options", "DENY") + self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'") + if cookie is not None: + secure = "; Secure" if panel.origin.startswith("https:") else "" + self.send_header("Set-Cookie", f"homegate_session={cookie}; Path=/; HttpOnly; SameSite=Strict; Max-Age=43200{secure}") + if filename: + self.send_header("Content-Disposition", f'attachment; filename="{filename}"') + self.end_headers() + self.wfile.write(body) + + def dispatch(self): + if self.headers.get("Host", "") != panel.authority: + raise UIError("Unexpected Host", 403) + if not panel.allowed(self.client_address[0]): + raise UIError("Доступ разрешён только из домашней сети", 403) + path = urlsplit(self.path).path + if self.command == "GET" and path in ("/", "/app.js", "/style.css", "/favicon.svg"): + name = {"/": "index.html", "/app.js": "app.js", "/style.css": "style.css", "/favicon.svg": "favicon.svg"}[path] + content_type = {"index.html": "text/html; charset=utf-8", "app.js": "text/javascript; charset=utf-8", + "style.css": "text/css; charset=utf-8", "favicon.svg": "image/svg+xml"}[name] + return self.respond(200, (BASE / "ui" / "dist" / name).read_bytes(), content_type) + token, session = panel.session(self.headers.get("Cookie")) + if self.command == "GET" and path == "/api/session": + if panel.local and session is None: + token, session = panel.new_session() + return self.respond(200, {"authenticated": bool(session), "local": panel.local, + "csrf": session["csrf"] if session else None}, cookie=token if session else None) + if self.command == "POST": + if self.headers.get("Origin") != panel.origin: + raise UIError("Invalid request origin", 403) + if self.headers.get("Content-Type", "").split(";")[0] != "application/json": + raise UIError("JSON required", 415) + size = int(self.headers.get("Content-Length", "0")) + if size < 1 or size > MAX_BODY: + raise UIError("Неверный размер запроса", 413) + body = json.loads(self.rfile.read(size)) + if not isinstance(body, dict): + raise UIError("JSON object required") + if path == "/api/login" and not panel.local: + token, session = panel.login(body.get("password"), self.client_address[0]) + return self.respond(200, {"csrf": session["csrf"]}, cookie=token) + if session is None: + raise UIError("Войдите в панель", 401) + if self.command == "GET": + if path == "/api/state": + return self.respond(200, panel.status()) + if path == "/api/ssh-config": + text = h.render_ssh(h.ssh_entries(h.load_config(panel.config))) + return self.respond(200, text.encode(), "text/plain; charset=utf-8") + if path == "/downloads/ssh-config": + text = h.render_ssh(h.ssh_entries(h.load_config(panel.config))) + return self.respond(200, text.encode(), "text/plain; charset=utf-8", filename="homegate.conf") + if path == "/downloads/sync_ssh.py": + return self.respond(200, (BASE / "sync_ssh.py").read_bytes(), "text/plain", filename="sync_ssh.py") + if path == "/downloads/services.yaml": + return self.respond(200, panel.config.read_bytes(), "text/yaml", filename="services.yaml") + if path == "/downloads/root-ca.crt": + pem = panel.status()["controller"].get("root", {}).get("pem") + if not pem: + raise UIError("Корневой сертификат ещё не создан контроллером", 404) + return self.respond(200, pem.encode(), "application/x-pem-file", filename="root-ca.crt") + if self.command == "POST": + if not hmac.compare_digest(self.headers.get("X-Homegate-CSRF", ""), session["csrf"]): + raise UIError("Invalid session token", 403) + if path == "/api/config": + return self.respond(200, panel.save(body["config"], body["revision"])) + if path == "/api/sync": + return self.respond(202, panel.request_sync()) + if path == "/api/logout": + panel.sessions.pop(token, None) + return self.respond(200, {"ok": True}, cookie="") + raise UIError("Not found", 404) + + def do_GET(self): + try: + self.dispatch() + except UIError as exc: + self.respond(exc.status, {"error": str(exc)}) + except (h.Error, ValueError, KeyError, TypeError, yaml.YAMLError) as exc: + self.respond(400, {"error": str(exc)}) + except OSError: + self.respond(503, {"error": "Не удалось прочитать или сохранить настройки"}) + + do_POST = do_GET + + def log_message(self, fmt, *args): + LOG.info("UI peer=%s status=%s", self.client_address[0], args[1] if len(args) > 1 else "-") + + return Handler + + +def main(): + os.umask(0o077) + logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s") + p = argparse.ArgumentParser(description=__doc__) + p.add_argument("--host", default=os.environ.get("UI_LISTEN_HOST", "0.0.0.0")) + p.add_argument("--port", type=int, default=int(os.environ.get("UI_LISTEN_PORT", "8081"))) + p.add_argument("--local", action="store_true", help="Loopback-only local Sites mode, no login") + args = p.parse_args() + if args.local and args.host != "127.0.0.1": + raise UIError("Local no-login mode must bind to loopback") + if not args.local: + bind_ip = os.environ.get("UI_BIND_IP", "") + h.private_address(bind_ip) + h.require(ipaddress.ip_address(bind_ip).version == 4, "UI_BIND_IP must be a private IPv4 address") + origin = os.environ.get("UI_ORIGIN", f"http://{args.host}:{args.port}") + panel = Panel(os.environ.get("HOMEGATE_CONFIG", "/config/services.yaml"), + os.environ.get("HOMEGATE_CONTROL", "/control"), origin, args.local, + os.environ.get("UI_PASSWORD_FILE", "/run/secrets/ui_password"), + os.environ.get("SSH_PUBLIC_URL", "")) + with ThreadingHTTPServer((args.host, args.port), handler_for(panel)) as server: + print(f"Homegate Local: {origin}", flush=True) + server.serve_forever() + + +if __name__ == "__main__": + main() diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..2bef36c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,9 @@ +cryptography==46.0.7 +PyYAML==6.0.3 +requests==2.34.2 +cffi==2.1.1 +pycparser==3.11 +certifi==2026.7.22 +charset-normalizer==3.5.2 +idna==3.20 +urllib3==2.8.0 diff --git a/run-local.sh b/run-local.sh new file mode 100755 index 0000000..0d9e905 --- /dev/null +++ b/run-local.sh @@ -0,0 +1,25 @@ +#!/bin/sh +# Local-only Sites preview; never starts the controller or connects to homelab APIs. +set -eu +cd "$(dirname "$0")" +umask 077 +local_dir=${HOMEGATE_LOCAL_DIR:-"$PWD/.local"} +mkdir -p "$local_dir/config" "$local_dir/control" +if [ ! -f "$local_dir/config/services.yaml" ]; then + cp config/services.yaml "$local_dir/config/services.yaml" +fi +if [ -n "${HOMEGATE_PYTHON:-}" ]; then + panel_python=$HOMEGATE_PYTHON +else + if [ ! -x "$local_dir/venv/bin/python" ]; then + python3 -m venv "$local_dir/venv" + "$local_dir/venv/bin/python" -m pip install -r requirements.txt + fi + panel_python=$local_dir/venv/bin/python +fi +panel_port=${HOMEGATE_LOCAL_PORT:-8787} +export HOMEGATE_CONFIG="$local_dir/config/services.yaml" +export HOMEGATE_CONTROL="$local_dir/control" +export UI_ORIGIN="http://127.0.0.1:$panel_port" +export PYTHONDONTWRITEBYTECODE=1 +exec "$panel_python" homegate_ui.py --local --host 127.0.0.1 --port "$panel_port" diff --git a/setup.sh b/setup.sh new file mode 100755 index 0000000..9f51e5f --- /dev/null +++ b/setup.sh @@ -0,0 +1,47 @@ +#!/bin/sh +set -eu +cd "$(dirname "$0")" +umask 077 +mkdir -p state secrets control +chmod 700 state secrets control +if [ ! -f .env ]; then + sed -e "s/^LOCAL_UID=.*/LOCAL_UID=$(id -u)/" \ + -e "s/^LOCAL_GID=.*/LOCAL_GID=$(id -g)/" .env.example > .env +fi +read_secret() { + target=$1 + label=$2 + minimum=${3:-1} + if [ -s "$target" ]; then return; fi + printf '%s: ' "$label" + previous_tty=$(stty -g) + trap 'stty "$previous_tty"' EXIT HUP INT TERM + stty -echo + IFS= read -r value + stty "$previous_tty" + trap - EXIT HUP INT TERM + printf '\n' + if [ "${#value}" -lt "$minimum" ]; then + printf 'Password must contain at least %s characters. Run setup.sh again.\n' "$minimum" >&2 + exit 1 + fi + printf '%s' "$value" > "$target" + unset value +} +read_secret secrets/ui_password 'Homegate panel password (at least 12 characters)' 12 +read_secret secrets/npm_password 'NPM password' +printf 'Automatic DNS requires Pi-hole 6. Manual DNS works with any version.\n' +printf 'Configure automatic Pi-hole DNS? [Y/n]: ' +IFS= read -r automatic +case "$automatic" in + n|N|no|NO) + if [ ! -f secrets/pihole_password ]; then : > secrets/pihole_password; fi + printf 'Set dns_mode: manual in config/services.yaml.\n' + ;; + *) read_secret secrets/pihole_password 'Pi-hole password (app password requires app_sudo)' ;; +esac +chmod 600 .env secrets/* +printf '\nEdit .env and config/services.yaml, then run:\n' +printf ' docker compose build\n' +printf ' docker compose run --rm homegate validate\n' +printf ' docker compose up -d\n' diff --git a/sync_ssh.py b/sync_ssh.py new file mode 100644 index 0000000..89413fb --- /dev/null +++ b/sync_ssh.py @@ -0,0 +1,222 @@ +#!/usr/bin/env python3 +"""Download a restricted Homegate SSH config. Requires Python 3.9+, no packages.""" +import argparse +import ipaddress +import os +from pathlib import Path +import re +import ssl +import sys +import tempfile +import time +from urllib.parse import urlsplit +from urllib.request import build_opener, ProxyHandler, HTTPSHandler, HTTPRedirectHandler + +MAX_BYTES = 512 * 1024 +HEADER = "# Homegate SSH config v1" +BEGIN = "# BEGIN HOMEGATE INCLUDE" +END = "# END HOMEGATE INCLUDE" +ALIAS = re.compile(r"[a-z0-9][a-z0-9_.-]{0,252}$") +USER = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.@-]{0,63}$") +PRIVATE = [ipaddress.ip_network(n) for n in + ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7")] + + +def check(ok, message): + if not ok: + raise ValueError(message) + + +def validate_entry(entry): + check(isinstance(entry, dict) and not set(entry) - {"aliases", "host", "port", "user"}, + "Unknown SSH field") + aliases = entry.get("aliases") + check(isinstance(aliases, list) and 0 < len(aliases) <= 16, "SSH aliases must contain 1–16 names") + for alias in aliases: + check(isinstance(alias, str) and ALIAS.fullmatch(alias), "SSH aliases must be literal names; no patterns or tokens") + try: + ipaddress.ip_address(alias) + except ValueError: + pass + else: + raise ValueError("Use an SSH alias, not an IP address, in Host") + check(len(set(aliases)) == len(aliases), "Duplicate SSH alias") + check(isinstance(entry.get("host"), str), "SSH HostName must be an IP string") + address = ipaddress.ip_address(entry["host"]) + check(address.version != 6 or address.scope_id is None, "Scoped IPv6 and SSH percent tokens are not allowed") + check(any(address.version == net.version and address in net for net in PRIVATE), + "SSH HostName must be an RFC1918 or ULA address") + check(type(entry.get("port")) is int and 1 <= entry["port"] <= 65535, "Invalid SSH port") + if "user" in entry: + check(isinstance(entry["user"], str) and USER.fullmatch(entry["user"]), "Invalid SSH user") + return entry + + +def render_ssh(entries): + check(isinstance(entries, list) and len(entries) <= 1024, "Too many SSH hosts") + lines = [HEADER, "# Public connection metadata only. Private keys stay on this computer.", ""] + seen = set() + for entry in entries: + validate_entry(entry) + check(not seen.intersection(entry["aliases"]), "SSH aliases must be unique across all hosts") + seen.update(entry["aliases"]) + lines += ["Host " + " ".join(entry["aliases"]), " HostName " + entry["host"], + " Port " + str(entry["port"])] + if "user" in entry: + lines.append(" User " + entry["user"]) + lines += [" StrictHostKeyChecking ask", ""] + # Do not leave an included file in its final host's conditional scope. + lines += ["Host *", ""] + result = "\n".join(lines) + check(len(result.encode()) <= MAX_BYTES, "SSH config exceeds size limit") + return result + + +def validate_download(raw): + """Never pass arbitrary downloaded SSH directives to ssh (Match exec can execute).""" + check(len(raw) <= MAX_BYTES, "SSH config exceeds size limit") + text = raw.decode("ascii").replace("\r\n", "\n") + check(all(c == "\n" or c == "\t" or 32 <= ord(c) < 127 for c in text), "Control characters in SSH config") + check(text.splitlines()[:1] == [HEADER], "Not a Homegate SSH config") + entries, current, fields = [], None, set() + finished = False + + def flush(): + if current is not None: + check({"hostname", "port", "stricthostkeychecking"}.issubset(fields), "Incomplete SSH host") + validate_entry(current) + entries.append(current) + + for line in text.splitlines()[1:]: + line = line.strip() + if not line or line.startswith("#"): + continue + check(not finished, "Directives after final Host * are forbidden") + parts = line.split() + directive, values = parts[0].lower(), parts[1:] + if directive == "host": + flush() + current, fields = None, set() + if values == ["*"]: + finished = True + else: + current = {"aliases": values} + continue + check(current is not None, "Global directives are forbidden") + check(directive in {"hostname", "port", "user", "stricthostkeychecking"}, + "Forbidden SSH directive: " + directive) + check(directive not in fields and len(values) == 1, "Duplicate directive or unexpected arguments") + fields.add(directive) + value = values[0] + if directive == "hostname": + current["host"] = value + elif directive == "port": + check(value.isascii() and value.isdecimal(), "Invalid SSH port") + current["port"] = int(value) + elif directive == "user": + current["user"] = value + else: + check(value == "ask", "Host key verification must remain enabled") + check(finished, "Missing final Host *") + # Rebuild from validated values; don't install source text from the network. + return render_ssh(entries) + + +class NoRedirect(HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + raise ValueError("Redirects are refused; provide the final /ssh-config URL") + + +def download(url, ca_file=None): + parsed = urlsplit(url) + check(parsed.scheme in ("http", "https") and parsed.hostname and not parsed.username + and not parsed.password and not parsed.fragment, "Use an HTTP(S) URL without credentials") + context = ssl.create_default_context(cafile=ca_file) + # Ignore HTTP(S)_PROXY for LAN fetches. HTTPS verification cannot be disabled. + opener = build_opener(ProxyHandler({}), HTTPSHandler(context=context), NoRedirect()) + with opener.open(url, timeout=15) as response: + check(response.status == 200, "Server did not return HTTP 200") + raw = response.read(MAX_BYTES + 1) + return validate_download(raw) + + +def atomic_write(path, data): + check(not path.is_symlink(), "Refusing to overwrite a symlink: " + str(path)) + fd, temporary = tempfile.mkstemp(dir=path.parent, prefix=".homegate-") + try: + with os.fdopen(fd, "wb") as stream: + stream.write(data) + stream.flush() + os.fsync(stream.fileno()) + os.chmod(temporary, 0o600) + os.replace(temporary, path) + finally: + if os.path.exists(temporary): + os.unlink(temporary) + + +def include_update(original, include_path="config.d/homegate.conf"): + text = original.decode("utf-8") + expected = BEGIN + '\nHost *\n Include "' + include_path + '"\n' + END + check((BEGIN in text) == (END in text), "Incomplete Homegate Include block; repair it manually") + if BEGIN in text: + check(text.count(BEGIN) == 1 and text.count(END) == 1, "Duplicate Homegate Include block") + check(expected in text.replace("\r\n", "\n"), "Homegate Include block was edited; inspect it manually") + return original + suffix = ("\n" if original and not original.endswith(b"\n") else "") + suffix += "\n" + expected + "\n" + return original + suffix.encode() + + +def install_config(text, ssh_dir, add_include=False): + # Validate before creating directories or changing any existing files. + text = validate_download(text.encode()) + check(not ssh_dir.is_symlink(), "SSH directory is a symlink; use its real path with --ssh-dir") + target_dir = ssh_dir / "config.d" + target = target_dir / "homegate.conf" + main = ssh_dir / "config" + check(not target_dir.is_symlink() and not target.is_symlink(), "Generated config path must not be a symlink") + original, updated = b"", b"" + if add_include: + check(not main.is_symlink(), "Main config is a symlink; add Include manually") + original = main.read_bytes() if main.exists() else b"" + include_path = target.resolve().as_posix() + check(not any(c in include_path for c in '\r\n\x00"$%*?[]'), "SSH directory contains unsupported Include path characters") + updated = include_update(original, include_path) + ssh_dir.mkdir(parents=True, exist_ok=True, mode=0o700) + target_dir.mkdir(exist_ok=True, mode=0o700) + os.chmod(ssh_dir, 0o700) + os.chmod(target_dir, 0o700) + if not target.exists() or target.read_bytes() != text.encode(): + atomic_write(target, text.encode()) + else: + os.chmod(target, 0o600) + if add_include and updated != original: + if main.exists(): + atomic_write(ssh_dir / ("config.before-homegate-" + str(time.time_ns())), original) + atomic_write(main, updated) + return target + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("url", help="e.g. http://192.168.0.10:8099/ssh-config") + parser.add_argument("--install", action="store_true", help="Also append one Include block; back up existing config") + parser.add_argument("--ssh-dir", type=Path, default=Path.home() / ".ssh") + parser.add_argument("--ca-file", help="Trusted PEM CA file for HTTPS") + args = parser.parse_args() + text = download(args.url, args.ca_file) + target = install_config(text, args.ssh_dir.expanduser(), args.install) + print("Updated:", target) + if args.install: + print("Include installed. Existing settings take precedence; check an alias with: ssh -G ALIAS") + else: + print("To add the Include on first use, run again with --install.") + + +if __name__ == "__main__": + try: + main() + except Exception as exc: + print("Homegate SSH sync failed:", exc, file=sys.stderr) + sys.exit(1) diff --git a/tests/test_distribution.py b/tests/test_distribution.py new file mode 100644 index 0000000..c03ed06 --- /dev/null +++ b/tests/test_distribution.py @@ -0,0 +1,112 @@ +"""First-install/update safety and release destination validation.""" +import os +from pathlib import Path +import tempfile +import unittest + +import yaml +import homegate as h +from bootstrap import initialize +from ci.image_metadata import metadata + +BASE = Path(__file__).resolve().parents[1] + + +class BootstrapTests(unittest.TestCase): + def setUp(self): + temp = tempfile.TemporaryDirectory() + self.addCleanup(temp.cleanup) + self.root = Path(temp.name) + self.seed = self.root / 'seed.yaml' + value = yaml.safe_load((BASE / 'config/services.yaml').read_bytes()) + value['services'] = [] + self.seed.write_text(yaml.safe_dump(value)) + self.config = self.root / 'config/services.yaml' + self.state = self.root / 'state' + self.control = self.root / 'control' + + def run_init(self): + return initialize(self.seed, self.config, self.state, self.control, os.getuid(), os.getgid()) + + def test_empty_volume_creates_valid_config_with_private_permissions(self): + self.assertTrue(self.run_init()) + self.assertEqual(h.load_config(self.config)['services'], []) + self.assertEqual(self.config.stat().st_mode & 0o777, 0o600) + for directory in (self.config.parent, self.state, self.control): + self.assertEqual(directory.stat().st_mode & 0o777, 0o700) + self.assertFalse((self.state / 'ca.json').exists()) + + def test_upgrade_preserves_edits_and_ca_even_with_changed_seed(self): + self.run_init() + config = yaml.safe_load(self.config.read_bytes()) + config['services'] = [{'hostname': 'notes.home', 'display_name': 'Мои заметки', + 'upstream': 'http://192.168.0.150:3000'}] + self.config.write_text(yaml.safe_dump(config, allow_unicode=True)) + ca = h.Authority(self.state, config['domain_zones']) + before = self.config.read_bytes() + ca_before = (self.state / 'ca.json').read_bytes() + self.seed.write_text('invalid: new seed must not overwrite config') + self.assertFalse(self.run_init()) + self.assertEqual(self.config.read_bytes(), before) + self.assertEqual((self.state / 'ca.json').read_bytes(), ca_before) + self.assertEqual(ca.cert.subject, h.Authority(self.state, config['domain_zones']).cert.subject) + + def test_invalid_first_seed_does_not_install_configuration(self): + self.seed.write_text('proxy_ip: 8.8.8.8') + with self.assertRaises((h.Error, KeyError)): + self.run_init() + self.assertFalse(self.config.exists()) + + def test_invalid_existing_file_is_not_replaced(self): + self.run_init() + self.config.write_text('do not erase this file') + with self.assertRaises(h.Error): + self.run_init() + self.assertEqual(self.config.read_text(), 'do not erase this file') + + def test_symlink_config_and_volume_are_refused(self): + self.config.parent.mkdir() + self.config.symlink_to(self.seed) + with self.assertRaises(h.Error): + self.run_init() + self.assertEqual(self.config.resolve(), self.seed.resolve()) + self.config.unlink() + self.state.rmdir() + self.state.symlink_to(self.config.parent, target_is_directory=True) + with self.assertRaises(h.Error): + self.run_init() + + +class ReleaseMetadataTests(unittest.TestCase): + def values(self, **overrides): + fields = {'server_url': 'https://git.example.home:3000', 'repository': 'HomeLab/Homegate', + 'ref': 'refs/tags/v0.4.0', 'revision': 'a' * 40, 'version_file': '0.4.0\n'} + fields.update(overrides) + return metadata(**fields) + + def test_registry_and_owner_come_from_gitea_repository(self): + value = self.values() + self.assertEqual(value['registry'], 'git.example.home:3000') + self.assertEqual(value['image'], 'git.example.home:3000/homelab/homegate') + self.assertEqual(value['version'], '0.4.0') + + def test_registry_override_and_prerelease(self): + value = self.values(registry_override='registry.example.home', ref='refs/tags/v0.4.0-rc.1', + version_file='0.4.0-rc.1') + self.assertEqual(value['image'], 'registry.example.home/homelab/homegate') + self.assertEqual(value['source'], 'https://git.example.home:3000/homelab/homegate') + + def test_wrong_tag_commit_or_destination_is_rejected(self): + for change in ({'ref': 'refs/heads/main'}, {'ref': 'refs/tags/v0.5.0'}, + {'ref': 'refs/tags/v0.4.0;bad'}, {'revision': 'bad\nvalue'}, + {'repository': 'owner/repo\nnew-output=x'}, {'repository': '../repo'}, + {'registry_override': 'https://registry.example.home'}, + {'registry_override': 'gitea'}, + {'registry_override': 'registry.example.home:99999'}, + {'registry_override': 'registry.example.home/path'}): + with self.subTest(change=change), self.assertRaises(ValueError): + self.values(**change) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/test_homegate.py b/tests/test_homegate.py new file mode 100644 index 0000000..00da600 --- /dev/null +++ b/tests/test_homegate.py @@ -0,0 +1,295 @@ +"""Behavior tests using real X.509/TLS and a simulated NPM/Pi-hole HTTP transport.""" +import copy +from datetime import timedelta +from email.parser import BytesParser +from email.policy import default +import json +from pathlib import Path +import ssl +import tempfile +import unittest +from unittest.mock import patch +from urllib.parse import unquote, urlsplit + +import requests +import yaml +from cryptography import x509 + +import homegate as h + +BASE = Path(__file__).resolve().parents[1] + + +class Transport: + def __init__(self): + self.hosts = [] + self.certs = [] + self.records = ["192.168.0.9 unrelated.home"] + self.cnames = [] + self.writes = [] + self.fail_upload = False + self.fail_nginx = False + self.fail_dns = False + self.uploads = {} + + def send(self, session, request, **kwargs): + path = unquote(urlsplit(request.url).path.removeprefix("/api")) + method = request.method + data = json.loads(request.body) if request.body and "application/json" in request.headers.get("Content-Type", "") else None + body, status = None, 200 + if method != "GET": + self.writes.append((method, path)) + if path == "/tokens": + body = {"token": "TEST_TOKEN"} + elif path == "/auth": + if method == "POST": + body = {"session": {"valid": True, "sid": "TEST_SID", "csrf": "TEST_CSRF"}} + else: + status = 204 + elif path.startswith("/nginx/"): + assert request.headers["Authorization"] == "Bearer TEST_TOKEN" + if path == "/nginx/proxy-hosts": + if method == "GET": + body = self.hosts + else: + assert self.uploads[data["certificate_id"]] + body = dict(data, id=len(self.hosts) + 1, meta={"nginx_online": not self.fail_nginx}) + self.hosts.append(body) + elif path.startswith("/nginx/proxy-hosts/"): + index = int(path.split("/")[-1]) - 1 + body = dict(data, id=index + 1, meta={"nginx_online": not self.fail_nginx}) + self.hosts[index] = body + elif path == "/nginx/certificates": + if method == "GET": + body = self.certs + else: + body = dict(data, id=len(self.certs) + 1, meta={}) + self.certs.append(body) + elif path.endswith("/upload"): + cert_id = int(path.split("/")[-2]) + if self.fail_upload: + status = 500 + else: + raw = ("Content-Type: " + request.headers["Content-Type"] + "\r\n\r\n").encode() + request.body + message = BytesParser(policy=default).parsebytes(raw) + fields = {p.get_param("name", header="content-disposition"): p.get_payload(decode=True) + for p in message.iter_parts()} + assert set(fields) == {"certificate", "certificate_key"} + x509.load_pem_x509_certificate(fields["certificate"]) + self.uploads[cert_id] = fields + self.certs[cert_id - 1]["meta"] = {"certificate": True, "certificate_key": True} + body = {"certificate_key": "SECRET_NOT_TO_LOG"} + else: + raise AssertionError(path) + elif path == "/config/dns": + assert request.headers["X-FTL-SID"] == "TEST_SID" + if self.fail_dns: + status = 503 + else: + body = {"config": {"dns": {"hosts": self.records, "cnameRecords": self.cnames}}} + elif path.startswith("/config/dns/hosts/"): + assert method == "PUT" + assert request.headers["X-FTL-SID"] == "TEST_SID" + entry = path.removeprefix("/config/dns/hosts/") + assert entry not in self.records + assert self.hosts[0]["meta"]["nginx_online"] + self.records.append(entry) + status = 201 + else: + raise AssertionError((method, path)) + response = requests.Response() + response.status_code = status + response._content = json.dumps(body).encode() if body is not None else b"" + return response + + +class HomegateTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.addCleanup(self.tmp.cleanup) + self.state = Path(self.tmp.name) + self.ca = h.Authority(self.state) + self.config = h.load_config(BASE / "config/services.yaml") + self.registry = {"instance": "test-instance", "routes": {}} + self.transport = Transport() + transport = self.transport + self.patch = patch.object(requests.Session, "send", lambda session, request, **kw: transport.send(session, request, **kw)) + self.patch.start() + self.addCleanup(self.patch.stop) + self.npm = h.NPM("http://npm:81", "NPM") + self.npm.login("test@example.com", "password") + self.dns = h.PiHole("http://pihole", "PIHOLE") + self.dns.login("password") + self.addCleanup(self.npm.close) + self.addCleanup(self.dns.close) + self.transport.writes.clear() + + def sync(self): + h.reconcile(self.config, self.state, self.ca, self.registry, self.npm, self.dns) + + def test_first_sync_and_idempotent_second_sync(self): + self.sync() + self.assertIn("192.168.0.10 pve.home", self.transport.records) + self.assertIn("192.168.0.9 unrelated.home", self.transport.records) + host = self.transport.hosts[0] + self.assertTrue(host["ssl_forced"]) + self.assertTrue(host["allow_websocket_upgrade"]) + self.assertIn("allow 192.168.0.0/24;\ndeny all;", host["advanced_config"]) + self.assertIn("proxy_ssl_verify off;", host["advanced_config"]) + self.transport.writes.clear() + self.sync() + self.assertEqual([], self.transport.writes) + + def test_renewal_uploads_and_reloads_existing_host(self): + self.sync() + old = self.transport.uploads[1]["certificate"] + future = h.now() + timedelta(days=61) + self.transport.writes.clear() + with patch.object(h, "now", return_value=future): + self.sync() + self.assertNotEqual(old, self.transport.uploads[1]["certificate"]) + self.assertEqual([("POST", "/nginx/certificates/1/upload"), ("PUT", "/nginx/proxy-hosts/1")], self.transport.writes) + self.assertEqual(1, len(self.transport.certs)) + + def test_failed_upload_retries_without_duplicate_certificate(self): + self.transport.fail_upload = True + with self.assertRaises(h.Error): + self.sync() + self.assertEqual({}, self.registry["routes"]) + self.assertEqual([], self.transport.hosts) + self.transport.fail_upload = False + self.sync() + self.assertEqual(1, len(self.transport.certs)) + + def test_failed_reload_is_retried_and_does_not_publish_dns(self): + self.transport.fail_nginx = True + with self.assertRaises(h.Error): + self.sync() + self.assertNotIn("192.168.0.10 pve.home", self.transport.records) + self.assertEqual({}, self.registry["routes"]) + self.transport.fail_nginx = False + self.sync() + self.assertIn("192.168.0.10 pve.home", self.transport.records) + + def test_unmanaged_proxy_is_not_overwritten(self): + self.transport.hosts.append({"id": 1, "domain_names": ["pve.home"], "advanced_config": "# existing"}) + with self.assertRaises(h.Error): + self.sync() + self.assertEqual([], self.transport.writes) + + def test_conflicting_dns_is_not_overwritten(self): + self.transport.records.append("192.168.0.137 pve.home alias.home") + with self.assertRaises(h.Error): + self.sync() + self.assertEqual([], self.transport.writes) + + def test_cname_conflict_is_not_overwritten(self): + self.transport.cnames.append("pve.home,other.home") + with self.assertRaises(h.Error): + self.sync() + self.assertEqual([], self.transport.writes) + + def test_dns_outage_does_not_stop_certificate_renewal(self): + self.sync() + self.transport.fail_dns = True + future = h.now() + timedelta(days=61) + with patch.object(h, "now", return_value=future), self.assertRaises(h.Error): + self.sync() + self.assertEqual(1, len(self.transport.certs)) + self.assertIn(("PUT", "/nginx/proxy-hosts/1"), self.transport.writes) + + def test_removed_service_is_not_deleted(self): + self.sync() + self.config["services"] = [] + self.transport.writes.clear() + self.sync() + self.assertEqual([], self.transport.writes) + self.assertEqual(1, len(self.transport.hosts)) + + def test_disabled_service_disables_proxy(self): + self.sync() + self.config["services"][0]["enabled"] = False + self.sync() + self.assertFalse(self.transport.hosts[0]["enabled"]) + + def test_invalid_input_cannot_inject_nginx_or_expand_access(self): + base = yaml.safe_load((BASE / "config/services.yaml").read_text()) + for field, value in [("hostname", "pve.home;return 200;"), ("upstream", "http://8.8.8.8:80"), + ("upstream", "https://192.168.0.137:8006/path"), ("websocket", "false"), + ("upstream_ca_file", "/tmp/ca;return 200;"), ("upstream_tls_name", "pve;#")]: + c = copy.deepcopy(base) + c["services"][0][field] = value + p = self.state / "invalid.yaml" + p.write_text(yaml.safe_dump(c)) + with self.subTest(field=field, value=value), self.assertRaises((h.Error, ValueError)): + h.load_config(p) + base["allowed_networks"] = ["0.0.0.0/0"] + p.write_text(yaml.safe_dump(base)) + with self.assertRaises(h.Error): + h.load_config(p) + + def test_ca_survives_restart_and_private_files_are_restricted(self): + original = (self.state / "root-ca.crt").read_bytes() + h.Authority(self.state) + self.assertEqual(original, (self.state / "root-ca.crt").read_bytes()) + self.assertEqual(0o600, (self.state / "ca.json").stat().st_mode & 0o777) + with self.assertRaises(h.Error): + self.ca.leaf("example.com") + + def test_missing_ca_does_not_silently_replace_trust(self): + (self.state / "registry.json").write_text("{}") + (self.state / "ca.json").unlink() + with self.assertRaises(h.Error): + h.Authority(self.state) + + def tls_handshake(self, hostname, trust=True): + bundle = self.ca.leaf("pve.home") + certpath, keypath = self.state / "tls.pem", self.state / "tls.key" + certpath.write_text(bundle["cert"]) + keypath.write_text(bundle["key"]) + server_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) + server_ctx.load_cert_chain(certpath, keypath) + client_ctx = ssl.create_default_context(cafile=str(self.state / "root-ca.crt") if trust else None) + ci, co, si, so = ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO() + client = client_ctx.wrap_bio(ci, co, server_hostname=hostname) + server = server_ctx.wrap_bio(si, so, server_side=True) + finished = set() + for _ in range(20): + for name, obj in (("client", client), ("server", server)): + try: + obj.do_handshake() + finished.add(name) + except ssl.SSLWantReadError: + pass + if co.pending: + si.write(co.read()) + if so.pending: + ci.write(so.read()) + if len(finished) == 2: + return client.getpeercert() + self.fail("TLS handshake did not complete") + + def test_real_tls_accepts_correct_hostname_and_trusted_ca(self): + cert = self.tls_handshake("pve.home") + self.assertIn(("DNS", "pve.home"), cert["subjectAltName"]) + + def test_real_tls_rejects_wrong_hostname(self): + with self.assertRaises(ssl.SSLCertVerificationError): + self.tls_handshake("wrong.home") + + def test_real_tls_rejects_untrusted_ca(self): + with self.assertRaises(ssl.SSLCertVerificationError): + self.tls_handshake("pve.home", trust=False) + + def test_upstream_verification_is_default_for_other_https_services(self): + c = yaml.safe_load((BASE / "config/services.yaml").read_text()) + c["services"] = [{"hostname": "nas.home.arpa", "upstream": "https://192.168.0.130"}] + p = self.state / "config.yaml" + p.write_text(yaml.safe_dump(c)) + config = h.load_config(p) + result = h.payload(config, config["services"][0], 1, "# test") + self.assertIn("proxy_ssl_verify on;", result["advanced_config"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_ssh_and_zones.py b/tests/test_ssh_and_zones.py new file mode 100644 index 0000000..ab76df6 --- /dev/null +++ b/tests/test_ssh_and_zones.py @@ -0,0 +1,258 @@ +import io +from pathlib import Path +import shutil +import ssl +import subprocess +import tempfile +import unittest +from unittest.mock import patch + +from cryptography import x509 +import yaml + +import homegate as h +import sync_ssh as s + +BASE = Path(__file__).resolve().parents[1] + + +class MemorySocket: + """Feed an actual BaseHTTPRequestHandler without binding a network port.""" + def __init__(self, data): + self.input = io.BytesIO(data) + self.output = b"" + + def makefile(self, *args): + return self.input + + def sendall(self, data): + self.output += data + + def settimeout(self, value): + pass + + +class SSHAndZonesTests(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory(prefix="homegate test ") + self.addCleanup(self.temp.cleanup) + self.root = Path(self.temp.name) + self.path = self.root / "services.yaml" + self.raw = yaml.safe_load((BASE / "config/services.yaml").read_text()) + self.write() + + def write(self): + self.path.write_text(yaml.safe_dump(self.raw)) + + def config(self): + return h.load_config(self.path) + + def rendered(self): + return s.render_ssh(h.ssh_entries(self.config())) + + def test_service_ssh_uses_vm_address_and_fqdn_alias(self): + rendered = self.rendered() + self.assertIn("Host pve pve.home\n HostName 192.168.0.137\n Port 22\n User root", rendered) + self.assertNotIn("192.168.0.10", rendered) + self.assertEqual(rendered, s.validate_download(rendered.encode())) + + def test_separate_ssh_hosts_and_custom_ports(self): + self.raw["ssh_hosts"] = [{"aliases": ["backup", "backup.lab.internal"], "host": "192.168.0.150", + "port": 2222, "user": "admin"}] + self.write() + self.assertIn("Host backup backup.lab.internal\n HostName 192.168.0.150\n Port 2222", self.rendered()) + + def test_disabled_entries_disappear_and_empty_inventory_is_valid(self): + self.raw["services"][0]["ssh"]["enabled"] = False + self.write() + self.assertNotIn("Host pve", self.rendered()) + self.assertEqual(self.rendered(), s.validate_download(self.rendered().encode())) + + def test_duplicate_alias_and_malicious_user_are_rejected(self): + self.raw["ssh_hosts"] = [{"aliases": ["pve"], "host": "192.168.0.150", "port": 22}] + self.write() + with self.assertRaises(ValueError): + self.config() + self.raw.pop("ssh_hosts") + self.raw["services"][0]["ssh"]["user"] = "root\nProxyCommand touch /tmp/not-allowed" + self.write() + with self.assertRaises(ValueError): + self.config() + + def test_ssh_ipv6_accepts_ula_without_scope_or_tokens(self): + entry = {"aliases": ["ipv6-vm"], "host": "fd12:3456::1", "port": 22} + self.assertIn("HostName fd12:3456::1", s.render_ssh([entry])) + for host in ("fd12:3456::1%h", "fd12:3456::1%eth0\nProxyCommand bad", "fe80::1"): + with self.subTest(host=host), self.assertRaises(ValueError): + s.render_ssh([dict(entry, host=host)]) + def test_export_acl_and_no_arbitrary_files(self): + for peer, code in [("192.168.0.20", 200), ("192.168.1.20", 403), ("8.8.8.8", 403), + ("::ffff:192.168.0.20", 200), ("127.0.0.1", 403)]: + with self.subTest(peer=peer): + self.assertEqual(code, h.export_response("/ssh-config", peer, self.path)[0]) + for path in ("/ca.json", "/root-ca.crt", "/../state/ca.json", "/ssh-config?file=ca.json", "/"): + self.assertEqual(404, h.export_response(path, "192.168.0.20", self.path)[0]) + self.assertEqual(200, h.export_response("/healthz", "127.0.0.1", self.path)[0]) + + def request(self, target="/ssh-config", peer="192.168.0.20", headers=""): + sock = MemorySocket((f"GET {target} HTTP/1.1\r\nHost: test\r\n{headers}\r\n").encode()) + h.export_handler(self.path)(sock, (peer, 5000), None) + return sock.output + + def test_http_handler_download_and_forwarded_header_cannot_bypass_acl(self): + response = self.request() + self.assertIn(b"200 OK", response) + self.assertEqual(self.rendered(), s.validate_download(response.split(b"\r\n\r\n", 1)[1])) + denied = self.request(peer="8.8.8.8", headers="X-Forwarded-For: 192.168.0.20\r\n") + self.assertIn(b"403 Forbidden", denied) + self.assertNotIn(b"192.168.0.137", denied) + + def test_http_export_fails_closed_on_invalid_config(self): + self.path.write_text("invalid: [\n") + self.assertIn(b"503 Service Unavailable", self.request()) + + def test_dangerous_downloaded_directives_are_rejected(self): + original = self.rendered() + candidates = [original.replace(" Port 22", " ProxyCommand touch /tmp/forbidden\n Port 22"), + original.replace(" Port 22", " Include /tmp/other\n Port 22"), + original.replace(" Port 22", "Match exec echo bad\n Port 22"), + original.replace("Host pve pve.home", "Host *"), + original.replace(" StrictHostKeyChecking ask", " StrictHostKeyChecking no"), + original.replace("192.168.0.137", "8.8.8.8"), + original + " ProxyCommand bad\n", + original.replace(" Port 22", " Port 22\x00"), + "not a config", original * 10000] + for text in candidates: + with self.subTest(text=text[:40]), self.assertRaises(ValueError): + s.validate_download(text.encode()) + + def test_install_preserves_existing_config_and_is_idempotent(self): + sshdir = self.root / ".ssh" + sshdir.mkdir() + original = b"Host work\n HostName 10.1.2.3\nHost pve\n User operator\n" + (sshdir / "config").write_bytes(original) + target = s.install_config(self.rendered(), sshdir, add_include=True) + installed = (sshdir / "config").read_bytes() + self.assertTrue(installed.startswith(original)) + self.assertEqual(1, installed.count(s.BEGIN.encode())) + backups = list(sshdir.glob("config.before-homegate-*")) + self.assertEqual(1, len(backups)) + self.assertEqual(original, backups[0].read_bytes()) + s.install_config(self.rendered(), sshdir, add_include=True) + self.assertEqual(installed, (sshdir / "config").read_bytes()) + self.assertEqual(1, len(list(sshdir.glob("config.before-homegate-*")))) + self.assertEqual(0o600, target.stat().st_mode & 0o777) + if shutil.which("ssh"): + result = subprocess.run(["ssh", "-G", "-F", str(sshdir / "config"), "pve"], + capture_output=True, text=True, check=True) + self.assertIn("hostname 192.168.0.137\n", result.stdout) + self.assertIn("user operator\n", result.stdout) + self.assertIn("port 22\n", result.stdout) + + def test_invalid_download_never_replaces_local_files(self): + sshdir = self.root / ".ssh" + target = s.install_config(self.rendered(), sshdir, add_include=True) + previous = target.read_bytes() + with self.assertRaises(ValueError): + s.install_config("Match exec evil\n", sshdir, add_include=True) + self.assertEqual(previous, target.read_bytes()) + + def test_download_failure_leaves_file_unchanged_and_no_redirects(self): + sshdir = self.root / ".ssh" + target = s.install_config(self.rendered(), sshdir) + previous = target.read_bytes() + with patch.object(s, "build_opener") as build: + build.return_value.open.side_effect = OSError("offline") + with self.assertRaises(OSError): + s.download("http://192.168.0.10:8099/ssh-config") + self.assertEqual(previous, target.read_bytes()) + with self.assertRaises(ValueError): + s.NoRedirect().redirect_request(None, None, 302, "", {}, "http://other") + + def test_symlink_target_is_not_overwritten(self): + sshdir = self.root / ".ssh" + target = s.install_config(self.rendered(), sshdir) + elsewhere = self.root / "elsewhere" + elsewhere.write_text("preserved") + target.unlink() + target.symlink_to(elsewhere) + with self.assertRaises(ValueError): + s.install_config(self.rendered(), sshdir) + self.assertEqual("preserved", elsewhere.read_text()) + + def test_multiple_custom_zones_and_label_boundaries(self): + self.raw["domain_zones"] = [".LAB.Internal.", "example.test", "home"] + self.raw["services"][0]["hostname"] = "pve.lab.internal" + self.write() + self.assertEqual(["lab.internal", "example.test", "home"], self.config()["domain_zones"]) + self.raw["services"][0]["hostname"] = "evilhome" + self.write() + with self.assertRaises(h.Error): + self.config() + self.raw["services"][0]["hostname"] = "pve.evilhome" + self.write() + with self.assertRaises(h.Error): + self.config() + + def test_old_config_without_domain_zones_still_loads(self): + self.raw.pop("domain_zones") + self.write() + self.assertEqual(h.DEFAULT_ZONES, self.config()["domain_zones"]) + + def test_ca_zone_expansion_requires_explicit_rotation(self): + state = self.root / "state" + state.mkdir() + ca = h.Authority(state) + original = (state / "ca.json").read_bytes() + original_leaf = ca.leaf("pve.home")["cert"] + registry = {"instance": "keep-me", "routes": {"pve.home": {"host_id": 1}}} + h.save_json(state / "registry.json", registry) + ca = h.Authority(state, ["home", "lab.internal"]) + with self.assertRaises(h.Error): + ca.leaf("pve.lab.internal") + self.assertEqual(original, (state / "ca.json").read_bytes()) + history = h.rotate_ca(state, ["home", "lab.internal"]) + self.assertEqual(original, (history / "ca.json").read_bytes()) + self.assertEqual(registry, h.read_json(state / "registry.json")) + ca = h.Authority(state, ["home", "lab.internal"]) + self.assertNotEqual(original_leaf, ca.leaf("pve.home")["cert"]) + ca.leaf("pve.lab.internal") + with self.assertRaises(h.Error): + ca.leaf("pve.home.arpa") + + def test_real_tls_with_custom_zone_certificate(self): + state = self.root / "state" + state.mkdir() + ca = h.Authority(state, ["lab.internal", "example.test"]) + bundle = ca.leaf("pve.lab.internal") + certpath, keypath = state / "leaf.crt", state / "leaf.key" + certpath.write_text(bundle["cert"]) + keypath.write_text(bundle["key"]) + cert = x509.load_pem_x509_certificate(bundle["cert"].encode()) + self.assertIn("pve.lab.internal", cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value + .get_values_for_type(x509.DNSName)) + serverctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) + serverctx.load_cert_chain(certpath, keypath) + clientctx = ssl.create_default_context(cafile=str(state / "root-ca.crt")) + ci, co, si, so = ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO(), ssl.MemoryBIO() + client = clientctx.wrap_bio(ci, co, server_hostname="pve.lab.internal") + server = serverctx.wrap_bio(si, so, server_side=True) + done = set() + for _ in range(20): + for name, obj in (("client", client), ("server", server)): + try: + obj.do_handshake() + done.add(name) + except ssl.SSLWantReadError: + pass + if co.pending: + si.write(co.read()) + if so.pending: + ci.write(so.read()) + if len(done) == 2: + break + self.assertEqual({"client", "server"}, done) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_ui.py b/tests/test_ui.py new file mode 100644 index 0000000..c4bee42 --- /dev/null +++ b/tests/test_ui.py @@ -0,0 +1,182 @@ +"""HTTP/session/config integration tests without external APIs or listening ports.""" +import copy +import hashlib +import json +from pathlib import Path +import tempfile +import time +import unittest +from unittest.mock import patch + +import yaml +import homegate as h +import homegate_ui as ui +from test_ssh_and_zones import MemorySocket + +BASE = Path(__file__).resolve().parents[1] + + +class PanelTests(unittest.TestCase): + def setUp(self): + temp = tempfile.TemporaryDirectory() + self.addCleanup(temp.cleanup) + self.root = Path(temp.name) + self.config = self.root / 'config/services.yaml' + self.config.parent.mkdir() + self.config.write_bytes((BASE / 'config/services.yaml').read_bytes()) + self.control = self.root / 'control' + self.password = self.root / 'password' + self.password.write_text('local-test-password') + self.panel = ui.Panel(self.config, self.control, 'http://192.168.0.10:8098', + password_file=self.password) + self.cookie = '' + self.csrf = '' + + def request(self, path='/api/state', body=None, peer='192.168.0.20', headers=None): + method = 'GET' if body is None else 'POST' + payload = b'' if body is None else json.dumps(body).encode() + heads = {'Host': self.panel.authority, 'Cookie': self.cookie} + if body is not None: + heads.update({'Origin': self.panel.origin, 'Content-Type': 'application/json', + 'Content-Length': str(len(payload)), 'X-Homegate-CSRF': self.csrf}) + heads.update(headers or {}) + raw = f'{method} {path} HTTP/1.1\r\n' + ''.join(f'{k}: {v}\r\n' for k, v in heads.items()) + '\r\n' + sock = MemorySocket(raw.encode() + payload) + ui.handler_for(self.panel)(sock, (peer, 5000), None) + header, data = sock.output.split(b'\r\n\r\n', 1) + status = int(header.split()[1]) + response_headers = dict(line.decode().split(': ', 1) for line in header.split(b'\r\n')[1:]) + if 'application/json' in response_headers.get('Content-Type', ''): + data = json.loads(data) + return status, data, response_headers + + def login(self): + code, body, headers = self.request('/api/login', {'password': 'local-test-password'}) + self.assertEqual(code, 200) + self.cookie = headers['Set-Cookie'].split(';')[0] + self.csrf = body['csrf'] + return headers + + def test_login_cookie_and_logout(self): + self.assertEqual(self.request()[0], 401) + headers = self.login() + self.assertIn('HttpOnly; SameSite=Strict', headers['Set-Cookie']) + self.assertEqual(self.request()[0], 200) + self.assertEqual(self.request('/api/logout', {})[0], 200) + self.assertEqual(self.request()[0], 401) + + def test_wrong_password_rate_limited(self): + for _ in range(5): + self.assertEqual(self.request('/api/login', {'password': 'incorrect'})[0], 401) + self.assertEqual(self.request('/api/login', {'password': 'incorrect'})[0], 429) + + def test_origin_csrf_and_host_required(self): + self.login() + for headers in ({'Origin': 'https://attacker.example'}, {'X-Homegate-CSRF': ''}, {'Host': 'attacker.example'}): + with self.subTest(headers=headers): + self.assertEqual(self.request('/api/sync', {}, headers=headers)[0], 403) + self.assertFalse((self.control / 'sync-request.json').exists()) + self.assertEqual(self.request('/api/sync', {})[0], 202) + self.assertTrue((self.control / 'sync-request.json').exists()) + + def test_lan_acl_and_local_mode(self): + for peer in ('8.8.8.8', '192.168.1.5'): + self.assertEqual(self.request('/', peer=peer)[0], 403) + self.assertEqual(self.request('/', peer='::ffff:192.168.0.20')[0], 200) + self.panel = ui.Panel(self.config, self.control, 'http://127.0.0.1:8787', local=True) + self.assertEqual(self.request('/api/session', peer='192.168.0.20')[0], 403) + code, body, _ = self.request('/api/session', peer='127.0.0.1') + self.assertEqual(code, 200) + self.assertTrue(body['authenticated']) + + def test_config_write_backups_and_conflicts(self): + self.login() + original = self.config.read_bytes() + _, data, _ = self.request() + new = copy.deepcopy(data['config']) + new['domain_zones'].append('test.internal') + code, saved, _ = self.request('/api/config', {'config': new, 'revision': data['revision']}) + self.assertEqual(code, 200) + self.assertNotEqual(saved['revision'], data['revision']) + self.assertIn('test.internal', h.load_config(self.config)['domain_zones']) + backup = list((self.config.parent / 'backups').glob('*.yaml')) + self.assertEqual(len(backup), 1) + self.assertEqual(backup[0].read_bytes(), original) + self.assertEqual(self.request('/api/config', {'config': new, 'revision': data['revision']})[0], 409) + + def test_invalid_config_is_not_written(self): + self.login() + before = self.config.read_bytes() + data = self.panel.status() + data['config']['services'][0]['hostname'] = 'outside.example' + code, _, _ = self.request('/api/config', {'config': data['config'], 'revision': data['revision']}) + self.assertEqual(code, 400) + self.assertEqual(self.config.read_bytes(), before) + + def test_malformed_json_and_missing_fields_return_400(self): + self.login() + for body in ([], None, 'string', {'revision': 'x'}): + if body is not None: + self.assertEqual(self.request('/api/config', body)[0], 400) + + def test_downloads_require_login_and_no_private_files(self): + for name in ('services.yaml', 'root-ca.crt', 'ssh-config'): + self.assertEqual(self.request('/downloads/' + name)[0], 401) + self.login() + self.assertEqual(self.request('/downloads/root-ca.crt')[0], 404) + self.assertIn(b'Host pve pve.home', self.request('/downloads/ssh-config')[1]) + for path in ('/downloads/../state/ca.json', '/state/ca.json', '/downloads/ui_password'): + self.assertEqual(self.request(path)[0], 404) + + def test_secure_cookie_expiry_and_static_csp(self): + self.panel.origin = 'https://panel.home' + self.panel.authority = 'panel.home' + headers = self.login() + self.assertIn('; Secure', headers['Set-Cookie']) + self.assertIn("frame-ancestors 'none'", self.request('/')[2]['Content-Security-Policy']) + with patch.object(ui.time, 'time', return_value=time.time() + 13 * 3600): + self.assertEqual(self.request()[0], 401) + + def test_freshness_reflects_controller_heartbeat(self): + h.save_json(self.control / 'status.json', {'time': time.time()-200, 'max_age': 180, 'ok': True}) + self.assertFalse(self.panel.status()['controller']['fresh']) + h.save_json(self.control / 'status.json', {'time': time.time(), 'max_age': 180, 'ok': False}) + self.assertTrue(self.panel.status()['controller']['fresh']) + self.assertFalse(self.panel.status()['controller']['ok']) + + def test_config_validation_does_not_mutate_ui_input(self): + original, _ = self.panel.config_data() + other = copy.deepcopy(original) + h.validate_config(other) + self.assertEqual(other, original) + self.panel.save(other, self.panel.status()['revision']) + self.assertNotIn('forward_host', yaml.safe_load(self.config.read_bytes())['services'][0]) + + def test_public_status_uses_applied_revision_without_keys(self): + state = self.root / 'state' + state.mkdir() + config = h.load_config(self.config) + ca = h.Authority(state, config['domain_zones']) + ca.leaf('pve.home') + applied = hashlib.sha256(self.config.read_bytes()).hexdigest() + self.config.write_bytes(self.config.read_bytes() + b'\n# Edited while syncing\n') + h.publish_panel_status(self.control, applied, config, state, ca, True, None) + status = h.read_json(self.control / 'status.json') + self.assertEqual(status['applied_revision'], applied) + self.assertNotEqual(status['applied_revision'], self.panel.status()['revision']) + self.assertIn('BEGIN CERTIFICATE', status['root']['pem']) + self.assertEqual(status['certificates'][0]['hostname'], 'pve.home') + self.assertNotIn('PRIVATE KEY', json.dumps(status)) + h.publish_panel_status(self.control, 'failed-revision', config, state, ca, False, 'API unavailable') + self.assertEqual(h.read_json(self.control / 'status.json')['applied_revision'], applied) + + def test_weak_password_or_invalid_origin_refused(self): + self.password.write_text('short') + with self.assertRaises(ui.UIError): + ui.Panel(self.config, self.control, 'http://panel.home', password_file=self.password) + with self.assertRaises(ui.UIError): + ui.Panel(self.config, self.control, 'http://panel.home/path', local=True) + + +if __name__ == '__main__': + unittest.main() diff --git a/ui/dist/app.js b/ui/dist/app.js new file mode 100644 index 0000000..1e6c4af --- /dev/null +++ b/ui/dist/app.js @@ -0,0 +1,104 @@ +'use strict'; +const $ = (s, root=document) => root.querySelector(s); +const esc = v => String(v ?? '').replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c])); +const paths = { + grid:'', + globe:'', + terminal:'', + shield:'', + sliders:'', + plus:'', search:'', + refresh:'', + download:'', + arrow:'', external:'', + edit:'', trash:'', + monitor:'', + server:'', + route:'', + copy:'', + check:'', info:'', + clock:'', close:'', + key:'', lock:'', +}; +const icon = (name,size=17) => ``; +let data, csrf='', tab='services', search='', filter='all', busy=false, settingsDirty=false; +const pages = [['services','Сервисы','grid'],['domains','Доменные зоны','globe'],['ssh','SSH-доступ','terminal'],['certificates','Сертификаты','shield'],['settings','Настройки','sliders']]; +const clone = v => JSON.parse(JSON.stringify(v)); +const date = v => v ? new Date(typeof v==='number'?v*1000:v).toLocaleDateString('ru-RU',{day:'numeric',month:'short',year:'numeric'}) : '—'; +const time = v => new Date(v*1000).toLocaleTimeString('ru-RU',{hour:'2-digit',minute:'2-digit'}); +const zones = () => data.config.domain_zones || ['home','home.arpa']; +const services = () => data.config.services || []; +const sshEntries = () => [...services().filter(r=>r.enabled!==false&&r.ssh&&r.ssh.enabled!==false).map(r=>({aliases:[...(r.ssh.alias?[r.ssh.alias]:[]),r.hostname].filter((x,i,a)=>a.indexOf(x)===i),host:r.ssh.host||new URL(r.upstream).hostname,port:r.ssh.port||22,user:r.ssh.user})),...(data.config.ssh_hosts||[]).filter(r=>r.enabled!==false)]; +const controller = () => data.controller || {}; +const isApplied = () => controller().fresh && controller().ok && controller().applied_revision===data.revision; +const sshUrl = () => data.ssh_url || `http://${data.config.proxy_ip}:8099/ssh-config`; + +async function api(path, body) { + const options = {credentials:'same-origin',headers:{}}; + if(body!==undefined){options.method='POST';options.headers={'Content-Type':'application/json','X-Homegate-CSRF':csrf};options.body=JSON.stringify(body);} + const r=await fetch(path,options); + const value=(r.headers.get('content-type')||'').includes('application/json')?await r.json():await r.text(); + if(!r.ok) {if(r.status===401&&path!=='/api/login')showLogin();throw new Error(value.error||`Ошибка ${r.status}`);} + return value; +} +function toast(text,error=false){const region=$('#toast-region');region.innerHTML=`
${icon(error?'info':'check',19)}${esc(text)}
`;setTimeout(()=>{region.innerHTML='';},6500);} +async function copy(text){try{await navigator.clipboard.writeText(text);toast('Скопировано');}catch{toast('Буфер обмена недоступен. Выделите текст и скопируйте вручную.',true);}} +function friendlyError(e){const s=e.message;return s.includes('display_name')?'Название должно быть в одну строку, не длиннее 100 символов.':s.includes('domain_zones')?'Имя сервиса должно принадлежать одной из ваших доменных зон.':s.includes('Duplicate hostname')?'Сервис с таким доменом уже есть.':s.includes('SSH aliases must be unique')?'SSH-псевдоним уже используется другим сервером.':s.includes('RFC1918')?'Укажите адрес или подсеть вашей локальной сети.':s;} +function heading(title,subtitle,actions=''){return `
ВАШЕ ЛОКАЛЬНОЕ ПРОСТРАНСТВО

${title}

${subtitle}

${actions}
`;} +function badge(text,kind=''){return `${text}`;} +function nav(){ + $('#navigation').innerHTML=pages.map(([id,label,i])=>`${icon(i,18)}${label}${id==='services'?`${services().length}`:''}`).join(''); + $('#crumb').textContent=pages.find(p=>p[0]===tab)[1]; +} +function statusStrip(){const c=controller();if(!c.fresh)return `
${icon('info',15)}Контроллер пока не подключён. Настройки сохраняются здесь. Для применения запустите Homegate в Docker.
`; + if(!c.ok)return `
${icon('info',15)}Не удалось применить настройки. ${esc(c.error||'Проверьте подключение к Pi-hole и NPM.')}
`; + if(!isApplied())return `
${icon('clock',15)}Есть новые настройки. Контроллер применит их в следующем цикле.
`; + return `
${icon('check',15)}Конфигурация применена в ${time(c.time)}. Доступность самих VM проверяется отдельно.
`; +} +function serviceName(r){if(r.display_name?.trim())return r.display_name.trim();const n=r.hostname.split('.')[0];return ({pve:'Proxmox',nas:'Хранилище',grafana:'Grafana',git:'Git',config:'Конфигурация',portainer:'Portainer',ha:'Home Assistant'})[n]||n;} +function serviceRows(){ + const rows=services().map((r,i)=>({r,i})).filter(({r})=>(`${r.hostname} ${r.upstream} ${serviceName(r)}`.toLowerCase().includes(search.toLowerCase()))&&(filter==='all'||(filter==='enabled'?r.enabled!==false:r.enabled===false))); + if(!rows.length)return `
${icon('search',26)}

Сервисы не найдены

${services().length?'Измените запрос или фильтр.':'Добавьте первый сервис, чтобы дать ему понятный адрес.'}

`; + return rows.map(({r,i})=>`
${esc(Array.from(serviceName(r))[0].toUpperCase())}
${esc(serviceName(r))}${r.ssh&&r.ssh.enabled!==false?'SSH-доступ настроен':'Веб-сервис'}
${icon('lock',12)} ${esc(r.hostname)} ${icon('external',11)}${esc(r.upstream)}${r.enabled===false?badge('Выключен','muted'):isApplied()?badge('Настроен','success'):badge('Ожидает применения')}
`).join(''); +} +function renderServices(){const c=controller();const first=services().find(r=>r.enabled!==false);const ssh=sshEntries();return heading('Ваши сервисы','Понятные адреса для всего, что работает дома.',``)+statusStrip()+` +
Сервисы ${icon('grid')}
${services().length}${services().filter(r=>r.enabled!==false).length} включено
в вашей конфигурации
Доменные зоны ${icon('globe')}
${zones().length}
${esc(zones().slice(0,3).map(x=>'.'+x).join(' · '))}
SSH-подключения ${icon('terminal')}
${ssh.length}
один конфиг для всех машин
Локальный HTTPS ${icon('shield')}
${c.root?'CA настроен':'Ожидает CA'}
${c.root?'доверие на ваших устройствах':'создаётся при запуске контроллера'}
+

Каталог сервисов ${services().length}

Прокси ${esc(data.config.proxy_ip)}
+
${[['all','Все сервисы'],['enabled','Включены'],['disabled','Выключены']].map(([v,l])=>``).join('')}
${serviceRows()}
СервисЛокальный адресКуда направлятьСостояние
Изменения сохраняются в services.yamlОбновление каждые ${data.config.interval_seconds||60} сек.
+
Как проходит соединение Локальная сеть

${first?`Маршрут для ${esc(first.hostname)}`:'Добавьте сервис, чтобы настроить первый маршрут'}

${icon('monitor',19)}Браузерваше устройство
${icon('globe',19)}Pi-holeимя → IP
${icon('route',19)}NPMHTTPS · 443
${icon('server',19)}${first?esc(serviceName(first)):'Ваша VM'}${first?esc(new URL(first.upstream).hostname):'IP:порт'}
${icon('shield',12)} Корневой сертификат устанавливается на каждое устройство
Серверы на расстоянии команды ${icon('terminal',20)}

Подключите общий SSH-конфиг на компьютере.
IP и порты больше не нужно держать в памяти.

$ssh ${esc(ssh[0]?.aliases[0]||'имя-сервера')}
`;} +function renderDomains(){const root=controller().root;return heading('Доменные зоны','Свои имена для разных частей вашей домашней сети.',``)+`
${zones().map((z,i)=>{const count=services().filter(r=>r.hostname===z||r.hostname.endsWith('.'+z)).length;const covered=root&&root.zones.some(p=>z===p||z.endsWith('.'+p));return `
${icon('globe',21)}
.${esc(z)}

${count} ${count===1?'сервис':'сервисов'} в этой зоне

${root?(covered?badge('Разрешена CA','success'):badge('Нужна смена CA')):badge('CA ещё не создан','muted')}DNS / TLS
`;}).join('')}
${icon('info',19)}

Домены работают внутри вашей сети.
Pi-hole направляет имена на NPM. Для домашних сетей подходит home.arpa; можно использовать и собственные зоны.

${root?`
${icon('shield',19)}

Новая зона может потребовать нового корневого сертификата.
Если зона вне ограничений текущего CA, выполните миграцию и установите новый корень на устройства.

`:''}`;} +function renderSSH(){const entries=sshEntries();return heading('SSH-доступ','Один дополнительный конфиг для всех ваших компьютеров.',`${icon('download',14)} Скрипт для ПК${icon('download',14)} Скачать конфиг`)+`
~/.ssh/config.d/homegate.conf
Загружаем конфиг…
Подключите за пару минут
1
Скачайте скрипт на компьютер

Python 3.9+ и OpenSSH. Приватные ключи остаются у вас.

${icon('download',12)} sync_ssh.py
2
Подключите дополнительный файл

Основной SSH-конфиг сохраняется. Для Windows используйте py -3.

python3 sync_ssh.py ${esc(sshUrl())} --install
3
Подключайтесь по имени

При следующих обновлениях запустите скрипт без --install.

ssh ${esc(entries[0]?.aliases[0]||'имя-сервера')}
${icon('lock',18)}

Открытая выгрузка только для вашей LAN.
${esc(sshUrl())}
${data.mode==='local'?'Этот адрес заработает после запуска ssh-export в Docker. Сейчас конфиг можно скачать кнопкой выше.':'Доступ ограничен разрешёнными подсетями. Пароль панели для этой выгрузки не нужен.'}

Серверы без веб-интерфейса ${(data.config.ssh_hosts||[]).length}

${(data.config.ssh_hosts||[]).map((r,i)=>``).join('')||``}
ПсевдонимыАдресПользователь
${esc(r.aliases.join(', '))} ${r.enabled===false?badge('Выключен','muted'):''}${esc(r.host)}:${r.port||22}${esc(r.user||'Из личного конфига')}
${icon('server',25)}

Здесь можно добавить NAS, backup-сервер или любую машину с SSH.
SSH веб-сервисов настраивается в карточке сервиса.

`;} +function renderCertificates(){const root=controller().root;const certs=controller().certificates||[];return heading('Сертификаты','Доверенный HTTPS для локальных адресов.',`${root?`${icon('download',14)} Скачать корневой CA`:''}`)+`
${icon('shield',29)}

Homegate Local Root CA

Ваш центр сертификации внутри домашней сети.

Состояние${root?badge('Создан','success'):badge('Ожидает запуска','muted')}
Действует до${date(root?.expires)}
Зоны в сертификате${esc(root?.zones.join(', ')||'Определятся при первом запуске')}
Срок сертификата сервиса90 дней
ПродлениеКогда осталось менее 30 дней
${root?`Отпечаток SHA-256
${esc(root.fingerprint)}
`:`
${icon('info',17)}

Корень создаётся контроллером. Сейчас панель не видит его данные.

`}
Установите доверие на устройства

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

1
Скачайте только root-ca.crt

Сверьте отпечаток с сервером. Приватный ключ CA никогда не публикуется в панели.

2
Импортируйте как доверенный корневой CA

Windows — доверенные корневые центры.
macOS — Связка ключей → System → Always Trust.
iOS — включите Full Trust после установки.

3
Откройте сервис по доменному имени

Например, https://${esc(services()[0]?.hostname||'service.home')}. Проверка сертификата по IP — другой запрос.

${icon('shield',17)}

Проверка TLS между NPM и самой VM настраивается отдельно для каждого сервиса.

Сертификаты сервисов

Данные контроллера
${certs.map(c=>``).join('')||''}
ДоменДействует до
${date(c.expires)}

После первого применения здесь появятся выданные сертификаты.

`;} +function renderSettings(){const c=data.config;return heading('Настройки сети','Адрес прокси, разрешённые подсети и частота обновления.')+`

Ваша локальная сеть

Доменные имена сервисов будут указывать на адрес NPM.

Локальный DNS

Выберите, кто создаёт записи для сервисов.

Подключения

Пароли остаются в Docker secrets на сервере.

${icon('globe',19)}
Pi-hole${c.dns_mode==='manual'?'Ручное управление DNS':'DNS-записи через API'}
${badge(controller().fresh&&controller().ok?'Синхронизирован':'Нет данных',controller().fresh&&controller().ok?'success':'muted')}
${icon('route',19)}
Nginx Proxy ManagerПрокси и HTTPS
${badge(controller().fresh&&controller().ok?'Синхронизирован':'Нет данных',controller().fresh&&controller().ok?'success':'muted')}

Адреса API и учётные данные задаются в .env и secrets/ при установке.

Последние изменения
${data.history.length?data.history.map(item=>`
${icon('check',13)}

${esc(item.text)}

`).join(''):'

Здесь появятся сохранения из панели.

'}
${icon('download',14)} Скачать текущий YAML
`;} + +function render(){if(!data)return;tab=pages.some(p=>p[0]===location.hash.slice(1))?location.hash.slice(1):'services';nav();$('#content').innerHTML=({services:renderServices,domains:renderDomains,ssh:renderSSH,certificates:renderCertificates,settings:renderSettings})[tab]();$('#yaml-download').innerHTML=icon('download',16);$('#logout').hidden=data.mode==='local';$('#service-search')?.addEventListener('input',e=>{search=e.target.value;$('#service-rows').innerHTML=serviceRows();});if(tab==='ssh')api('/api/ssh-config').then(text=>{if($('#ssh-preview'))$('#ssh-preview').textContent=text;}).catch(e=>toast(e.message,true));if(tab==='settings'){const form=$('#settings-form');form.addEventListener('input',()=>settingsDirty=true);form.addEventListener('submit',saveSettings);}} +async function refresh(){data=await api('/api/state');render();} +async function saveConfig(config){if(busy)throw new Error('Подождите завершения сохранения');busy=true;try{data=await api('/api/config',{config,revision:data.revision});settingsDirty=false;render();toast(controller().fresh?'Настройки сохранены. Контроллер применит их в следующем цикле.':'Настройки сохранены локально. Для применения подключите контроллер.');}finally{busy=false;}} + +function showModal(title,subtitle,body,footer){$('#modal-content').innerHTML=`${body}${footer||''}`;$('#modal').showModal();} +const modalFooter=(label='Сохранить')=>``; +function serviceModal(index=-1){const r=index<0?{}:services()[index];showModal(index<0?'Новый сервис':'Настройки сервиса','Домен, адрес VM и параметры подключения.',``,modalFooter(index<0?'Добавить сервис':'Сохранить')); + const form=$('#modal-form');const check=$('[name=ssh_enabled]',form);const fields=$('.ssh-fields',form);fields.hidden=!check.checked;check.addEventListener('change',()=>fields.hidden=!check.checked); + form.addEventListener('submit',async e=>{e.preventDefault();const f=new FormData(form);const item={...clone(r),hostname:f.get('hostname').trim().toLowerCase(),upstream:f.get('upstream').trim(),websocket:f.has('websocket'),upstream_tls_verify:f.has('upstream_tls_verify'),timeout_seconds:Number(f.get('timeout_seconds')),max_body_mb:Number(f.get('max_body_mb'))};if(f.get('display_name').trim())item.display_name=f.get('display_name').trim();else delete item.display_name;for(const k of ['upstream_tls_name','upstream_ca_file']){if(f.get(k).trim())item[k]=f.get(k).trim();else delete item[k];}if(f.has('ssh_enabled')){item.ssh={port:Number(f.get('ssh_port'))};for(const [a,b] of [['alias','ssh_alias'],['user','ssh_user'],['host','ssh_host']])if(f.get(b).trim())item.ssh[a]=f.get(b).trim();}else delete item.ssh;const c=clone(data.config);if(index<0)c.services.push(item);else c.services[index]=item;await modalSave(c);}); +} +async function modalSave(config){try{await saveConfig(config);$('#modal').close();}catch(e){const error=$('#modal-error');if(error){error.hidden=false;error.textContent=friendlyError(e);}else toast(friendlyError(e),true);}} +function zoneModal(){showModal('Новая доменная зона','Все сервисы этой зоны будут доступны через локальный DNS.',``,modalFooter('Добавить зону'));$('#modal-form').addEventListener('submit',async e=>{e.preventDefault();const z=new FormData(e.target).get('zone').trim().toLowerCase().replace(/^\.+|\.+$/g,'');const c=clone(data.config);c.domain_zones=[...zones(),z];await modalSave(c);});} +function sshModal(index=-1){const r=index<0?{}:data.config.ssh_hosts[index];showModal(index<0?'Новый SSH-хост':'Настройки SSH-хоста','Прямое подключение к машине без создания веб-прокси.',``,modalFooter());$('#modal-form').addEventListener('submit',async e=>{e.preventDefault();const f=new FormData(e.target);const item={aliases:f.get('aliases').split(',').map(x=>x.trim().toLowerCase()).filter(Boolean),host:f.get('host').trim(),port:Number(f.get('port')),enabled:f.has('enabled')};if(f.get('user').trim())item.user=f.get('user').trim();const c=clone(data.config);c.ssh_hosts||=[];if(index<0)c.ssh_hosts.push(item);else c.ssh_hosts[index]=item;await modalSave(c);});} +function confirmModal(title,text,action){showModal(title,'',``,``);$('#confirm-action').addEventListener('click',action);} +function guide(ca=false){const command=ca?'docker compose stop homegate\ndocker compose run --rm homegate rotate-ca\n# Установите новый state/root-ca.crt на устройства\ndocker compose up -d homegate':'sh setup.sh\n# Укажите адреса и пароли в .env / secrets\ndocker compose up -d --build';showModal(ca?'Смена корневого сертификата':'Подключите Homegate к вашей сети',ca?'Выполните на Docker-хосте после добавления новых зон.':'Панель готовит конфигурацию. Контроллер применяет её к Pi-hole и NPM.',``,``);$('#copy-guide').addEventListener('click',()=>copy(command));} +async function saveSettings(e){e.preventDefault();const f=new FormData(e.target);const c=clone(data.config);c.proxy_ip=f.get('proxy_ip').trim();c.allowed_networks=f.get('allowed_networks').split(/\n|,/).map(x=>x.trim()).filter(Boolean);c.dns_mode=f.get('dns_mode');c.interval_seconds=Number(f.get('interval_seconds'));try{await saveConfig(c);}catch(err){$('#settings-error').hidden=false;$('#settings-error').textContent=friendlyError(err);}} + +document.addEventListener('click',async e=>{const button=e.target.closest('[data-action]');if(!button)return;const i=Number(button.dataset.index);const a=button.dataset.action;try{ + if(a==='add-service')serviceModal();else if(a==='edit-service')serviceModal(i);else if(a==='add-zone')zoneModal();else if(a==='add-ssh')sshModal();else if(a==='edit-ssh')sshModal(i);else if(a==='close-modal')$('#modal').close();else if(a==='guide')guide();else if(a==='ca-guide')guide(true);else if(a==='go-ssh')location.hash='ssh'; + else if(a==='filter'){filter=button.dataset.filter;render();} + else if(a==='sync'){button.disabled=true;const r=await api('/api/sync',{});toast(r.fresh?'Применение запрошено. Дождитесь обновления состояния.':'Запрос сохранён. Контроллер пока не отвечает.');button.disabled=false;} + else if(a==='toggle-service'){const c=clone(data.config);c.services[i].enabled=c.services[i].enabled===false;await saveConfig(c);} + else if(a==='remove-service')confirmModal('Убрать сервис из Homegate?',`${esc(services()[i].hostname)} исчезнет из конфигурации и SSH-выгрузки. Уже созданные объекты NPM и DNS останутся — удалите их отдельно в интерфейсах этих сервисов.`,async()=>{const c=clone(data.config);c.services.splice(i,1);await modalSave(c);}); + else if(a==='remove-zone')confirmModal('Удалить доменную зону?',`Зона .${esc(zones()[i])} будет убрана из списка. Сначала перенесите или удалите использующие её сервисы.`,async()=>{const c=clone(data.config);c.domain_zones=zones().filter((_,j)=>j!==i);await modalSave(c);}); + else if(a==='remove-ssh')confirmModal('Удалить SSH-хост?',`Он исчезнет из общего SSH-конфига при следующем обновлении на ПК.`,async()=>{const c=clone(data.config);c.ssh_hosts.splice(i,1);await modalSave(c);}); + else if(a==='copy-install')await copy(`python3 sync_ssh.py ${sshUrl()} --install`);else if(a==='copy-ssh-command')await copy(`ssh ${sshEntries()[0]?.aliases[0]||'имя-сервера'}`);else if(a==='copy-ssh-config')await copy(await api('/api/ssh-config')); +}catch(err){button.disabled=false;toast(friendlyError(err),true);}}); +function showLogin(){const box=$('#login-screen');box.hidden=false;box.innerHTML=``;$('#login-form').addEventListener('submit',async e=>{e.preventDefault();try{const r=await api('/api/login',{password:new FormData(e.target).get('password')});csrf=r.csrf;box.hidden=true;await refresh();}catch(err){$('#login-error').hidden=false;$('#login-error').textContent=err.message;}});} +$('#guide-button').addEventListener('click',()=>guide());$('#menu-button').addEventListener('click',()=>document.body.classList.toggle('menu-open'));$('#sidebar-shade').addEventListener('click',()=>document.body.classList.remove('menu-open'));$('#logout').addEventListener('click',async()=>{await api('/api/logout',{});showLogin();});window.addEventListener('hashchange',()=>{settingsDirty=false;document.body.classList.remove('menu-open');render();}); +async function boot(){try{const session=await api('/api/session');if(!session.authenticated)return showLogin();csrf=session.csrf;await refresh();}catch(e){$('#content').innerHTML=`

Не удалось загрузить панель

${esc(e.message)}

`;$('#retry-load').onclick=boot;}} +boot();setInterval(()=>{if(data&&!busy&&!settingsDirty&&!document.body.classList.contains('menu-open')&&!document.activeElement?.matches('input,textarea,select')&&!$('#modal').open&&$('#login-screen').hidden)refresh().catch(()=>{});},15000); diff --git a/ui/dist/favicon.svg b/ui/dist/favicon.svg new file mode 100644 index 0000000..48ef349 --- /dev/null +++ b/ui/dist/favicon.svg @@ -0,0 +1 @@ + diff --git a/ui/dist/index.html b/ui/dist/index.html new file mode 100644 index 0000000..4f53086 --- /dev/null +++ b/ui/dist/index.html @@ -0,0 +1,34 @@ + + + + + + + Homegate — домашняя сеть + + + + + + +
+ + +
+
Только локальноH
+

Загружаем вашу сеть…

+
Создано для вашей домашней сетиPi-hole · Nginx Proxy Manager · Homegate
+
+
+ + +
+ + diff --git a/ui/dist/style.css b/ui/dist/style.css new file mode 100644 index 0000000..e515be7 --- /dev/null +++ b/ui/dist/style.css @@ -0,0 +1 @@ +:root{font-family:Inter,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#24333d;background:#f5f7f8;font-synthesis:none;--ink:#22323a;--muted:#7a8791;--line:#e4e9ec;--green:#257a56;--mint:#91deb3;--sidebar:#14272e;--radius:13px}*{box-sizing:border-box}body{margin:0;font-size:14px}button,input,select,textarea{font:inherit}button,a,input,select,textarea{-webkit-tap-highlight-color:transparent}button{cursor:pointer}button:disabled{cursor:not-allowed;opacity:.55}a{color:inherit;text-decoration:none}button{border:0}button:focus-visible,a:focus-visible{outline:3px solid #75c99f;outline-offset:3px}input:focus,select:focus,textarea:focus{outline:2px solid #a5d4be;outline-offset:1px}svg{vertical-align:middle;flex-shrink:0}button svg{pointer-events:none}[hidden]{display:none!important}.sidebar{position:fixed;inset:0 auto 0 0;width:244px;background:var(--sidebar);color:#ced9dc;display:flex;flex-direction:column;padding:34px 20px 22px;z-index:20}.brand{display:flex;gap:10px;align-items:center;color:#fff;font-size:26px;font-weight:730;letter-spacing:-1.2px;padding:0 12px}.brand-dot{color:var(--mint)}.workspace{margin:36px 2px 30px;padding:13px 11px;display:flex;align-items:center;gap:11px;border:1px solid #ffffff15;border-radius:10px;background:#ffffff04}.workspace-icon{width:32px;height:32px;border-radius:8px;display:grid;place-items:center;background:#31504f;color:#b8ead4;font-weight:650}.workspace strong{display:block;color:#eef3f4;font-size:12px;font-weight:600}.workspace div>span{font-size:10px;display:block;color:#8ea2a9;margin-top:4px}.workspace-dots{margin-left:auto;letter-spacing:2px}.nav-label{font-size:9px;letter-spacing:1.65px;color:#7e939a;padding:0 14px;margin-bottom:13px;font-weight:600}.nav-item{display:flex;align-items:center;gap:12px;margin-bottom:5px;border-radius:8px;padding:13px 14px;font-size:12px;font-weight:500;color:#aebdc3;transition:background .15s,color .15s}.nav-item:hover{background:#ffffff08;color:#fff}.nav-item.active{background:#29423f;color:#b2ebc9}.nav-item svg{opacity:.85}.nav-count{margin-left:auto;background:#ffffff13;min-width:20px;padding:2px 6px;font-size:10px;border-radius:5px;text-align:center}.sidebar-guide{margin:auto 4px 26px;padding:22px 14px 18px;border-top:1px solid #ffffff0e}.guide-orbit{display:grid;place-items:center;width:31px;height:31px;border:1px solid #75988a66;color:#93c8ae;font-size:18px;border-radius:50%;margin-bottom:13px}.sidebar-guide strong{font-size:12px;font-weight:600;color:#dce8e7}.sidebar-guide p{color:#8aa0a8;font-size:11px;line-height:1.8;margin:7px 0 13px}.text-link{background:none;color:#a3d9b9;padding:0;font-size:11px;display:flex;gap:20px;align-items:center}.sidebar-bottom{border-top:1px solid #ffffff10;padding:20px 11px 0;display:flex;align-items:center;gap:10px}.online-dot{height:6px;width:6px;display:inline-block;border-radius:50%;background:#81cda1;flex-shrink:0}.sidebar-bottom strong{display:block;font-size:10px;color:#c6d7d9;font-weight:500}.sidebar-bottom div>span{display:block;font-size:10px;margin-top:5px;color:#729098}.version{margin-left:4px;color:#a4bdc2}.sidebar-bottom button{margin-left:auto;color:#a5b7ba}.workspace-main{margin-left:244px;min-height:100vh;display:flex;flex-direction:column}.topbar{height:78px;background:#fff;border-bottom:1px solid var(--line);display:flex;align-items:center;justify-content:space-between;padding:0 42px;flex-shrink:0}.breadcrumb{display:flex;align-items:center;gap:14px;font-size:11px;color:#929da4}.breadcrumb strong{font-weight:500;color:#465760}.crumb-slash{color:#c7d0d5}.topbar-right{display:flex;align-items:center;gap:23px}.local-chip{font-size:10px;color:#6f7f86;display:flex;gap:7px;align-items:center}.avatar{border-radius:50%;background:#edf0e8;color:#6d775f;width:30px;height:30px;display:grid;place-items:center;font-size:11px;font-weight:600}.icon-button{padding:6px;display:inline-grid;place-items:center;border-radius:6px;background:transparent;color:#809098;min-width:30px;min-height:30px}.icon-button:hover{background:#eff3f4;color:#294a3d}.icon-button.danger:hover{background:#fff1ef;color:#b75d4e}main{padding:38px 42px 34px;max-width:1570px;width:100%;margin:0 auto;flex:1}.heading{display:flex;justify-content:space-between;align-items:center;gap:16px;margin-bottom:26px}.eyebrow{font-size:9px;letter-spacing:1.7px;font-weight:650;color:#94a29f;text-transform:uppercase;margin-bottom:10px}h1{font-size:28px;letter-spacing:-1px;line-height:1.25;font-weight:680;margin:0;color:#24363e}.subtitle{margin:10px 0 0;font-size:12px;line-height:1.65;color:#7d8a92}.button-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.btn{display:inline-flex;align-items:center;justify-content:center;gap:8px;border:1px solid var(--line);background:#fff;color:#46565e;border-radius:8px;padding:10px 14px;font-size:11px;font-weight:550;min-height:36px;white-space:nowrap;transition:background .15s,transform .15s}.btn:hover{background:#f8faf9;border-color:#cbd8d1}.btn:active{transform:translateY(1px)}.btn.primary{background:#2b7655;border-color:#2b7655;color:white;box-shadow:0 2px 3px #163e2310}.btn.primary:hover{background:#246747}.btn.dark{background:#213d36;color:#e5f2e9;border-color:#213d36}.btn.subtle{background:#f7f9f8}.btn.danger{background:#fff3f1;color:#b5594e;border-color:#f1d5d0}.btn.small{padding:6px 10px;font-size:10px;min-height:30px}.btn.link{padding:0;border:0;background:none;color:var(--green)}.status-strip{display:flex;align-items:center;gap:10px;padding:12px 15px;border:1px solid #e6e8db;background:#fbfcf6;border-radius:9px;margin-bottom:22px;color:#7c805d;font-size:11px;line-height:1.6}.status-strip strong{font-weight:600}.status-strip button{margin-left:auto}.status-strip.good{background:#f0f8f3;border-color:#d6e7dc;color:#3f7859}.status-strip.bad{background:#fff6f3;color:#a76852;border-color:#f1ded5}.stats{display:grid;grid-template-columns:repeat(4,1fr);gap:16px;margin-bottom:26px}.stat{background:#fff;border:1px solid var(--line);border-radius:var(--radius);padding:19px 20px 17px;min-height:120px}.stat-top{display:flex;align-items:center;justify-content:space-between;color:#8a989f;font-size:11px}.stat-top svg{color:#889c95}.stat-value{font-size:28px;font-weight:650;letter-spacing:-1px;margin-top:15px;line-height:1.15;color:#293e44;display:flex;align-items:center;gap:9px}.stat-value.text-value{font-size:17px;letter-spacing:-.3px;line-height:1.9}.stat-note{font-size:10px;color:#9aa5ab;margin-top:6px}.mini-pill{font-size:9px;letter-spacing:0;font-weight:500;padding:4px 6px;border-radius:5px;background:#f0f6f2;color:#638571}.section-heading{display:flex;align-items:center;justify-content:space-between;margin:27px 0 13px}.section-heading h2,h2.section-title{font-size:14px;font-weight:620;letter-spacing:-.2px;margin:0}.count-label{font-size:10px;background:#e9edf0;padding:2px 6px;color:#8a969d;border-radius:5px;margin-left:7px;font-weight:500}.section-kicker{font-size:10px;color:#929fa5}.panel{background:#fff;border:1px solid var(--line);border-radius:var(--radius);overflow:hidden}.panel-pad{padding:23px}.toolbar{display:flex;align-items:center;justify-content:space-between;gap:14px;padding:17px 20px;border-bottom:1px solid #edf0f2}.search-box{display:flex;align-items:center;gap:9px;max-width:310px;flex:1;color:#9eaaaf}.search-box input{width:100%;border:0;outline:0;background:transparent;color:#3a4c54;font-size:11px;min-height:27px}.search-box input::placeholder{color:#9aa5ab}.filters{display:flex;gap:5px;padding:3px;background:#f5f7f8;border-radius:7px}.filter{font-size:10px;color:#8c999f;background:transparent;padding:6px 9px;border-radius:5px}.filter.active{background:white;color:#3d6451;box-shadow:0 1px 4px #1f352311}.table-scroll{overflow-x:auto}table{border-collapse:collapse;width:100%;text-align:left}th{font-size:9px;font-weight:500;letter-spacing:.55px;color:#9ca8ae;padding:13px 20px;background:#fcfdfd;text-transform:uppercase}td{padding:18px 20px;border-top:1px solid #edf0f2;font-size:11px;vertical-align:middle;white-space:nowrap}tbody tr:hover{background:#fdfefd}.service-name{display:flex;align-items:center;gap:12px}.service-icon{height:38px;width:38px;background:#f7eee5;border-radius:10px;color:#b47e3e;display:grid;place-items:center;font-size:15px;font-weight:650;flex-shrink:0}.service-icon.teal{background:#e8f4f0;color:#4a9977}.service-icon.blue{background:#eaf0fb;color:#6d86ad}.service-name strong{display:block;max-width:240px;white-space:normal;overflow-wrap:anywhere;font-size:12px;font-weight:600;color:#344751}.service-name small{display:block;font-size:10px;color:#9aa6ac;margin-top:5px}.mono{font-family:"SFMono-Regular",Consolas,"Liberation Mono",monospace;font-size:10px;letter-spacing:-.2px}.domain-link{display:inline-flex;align-items:center;gap:5px;color:#417b61;font-weight:500;font-size:11px}.domain-link svg{opacity:.65}.badge{padding:5px 8px;display:inline-flex;align-items:center;gap:5px;font-size:9px;border-radius:6px;background:#f4f5ed;color:#969265;font-weight:500}.badge.success{background:#edf7f0;color:#56866b}.badge.muted{background:#f0f3f5;color:#86939a}.badge.blue{background:#eef3fa;color:#7188ae}.badge.error{background:#fff0ea;color:#bb755e}.badge .online-dot{width:4px;height:4px;background:currentColor}.row-actions{display:flex;align-items:center;gap:4px;justify-content:flex-end}.switch{width:29px;height:17px;background:#d7dfe1;border-radius:20px;padding:2px;display:inline-flex;align-items:center;transition:background .2s}.switch:after{content:"";width:13px;height:13px;border-radius:50%;background:#fff;box-shadow:0 1px 2px #0002;transition:transform .2s}.switch.on{background:#6ea78a}.switch.on:after{transform:translateX(12px)}.table-end{padding:13px 20px;display:flex;justify-content:space-between;color:#a5afb4;font-size:9px;border-top:1px solid #edf0f2}.add-row{display:flex;width:100%;justify-content:center;align-items:center;gap:8px;background:#fff;color:#93a49a;font-size:11px;padding:17px;border-top:1px dashed #e2e9e5}.add-row:hover{background:#f9fcfa;color:#397a56}.below-grid{display:grid;grid-template-columns:1.55fr 1fr;gap:20px;margin-top:22px}.panel-heading{display:flex;justify-content:space-between;align-items:center;font-size:12px;font-weight:600;margin-bottom:9px}.panel-description{font-size:10px;color:#95a1a7;line-height:1.8;margin:0}.flow{display:flex;align-items:center;justify-content:space-between;gap:9px;margin-top:23px;margin-bottom:13px}.flow-node{text-align:center;min-width:60px}.node-symbol{width:38px;height:38px;background:#f2f6f3;border:1px solid #e3ece6;border-radius:11px;display:grid;place-items:center;margin:0 auto 9px;color:#81998a}.flow-node strong{max-width:100px;overflow-wrap:anywhere;font-size:10px;font-weight:550;display:block}.flow-node small{font-size:8px;color:#a1adaf;display:block;margin-top:5px}.flow-line{flex:1;border-top:1px dashed #bdcfc4;position:relative;margin-top:-27px}.flow-line:after{content:"›";color:#a1b9ac;position:absolute;right:-1px;top:-9px;font-size:14px}.flow-foot{margin-top:19px;padding-top:13px;border-top:1px solid #f0f2f3;font-size:9px;color:#92a09b;display:flex;gap:7px;align-items:center}.ssh-card{background:#eff5f1;border-color:#dce7df;position:relative}.ssh-card .panel-heading{color:#35624b}.ssh-card .panel-description{color:#879b8e}.command-small{background:#fff9;border:1px solid #dae7df;color:#578267;border-radius:7px;display:flex;align-items:center;justify-content:space-between;padding:10px 12px;margin:17px 0;font-size:11px}.command-small .dollar{color:#afc5b7;padding-right:9px}.ssh-card .btn{background:transparent;border-color:#c9dccf;color:#557e65;width:100%;margin-top:1px}.page-footer{display:flex;justify-content:space-between;color:#a9b3b9;padding:20px 42px 25px;font-size:9px;gap:10px}.footer-dot{margin:0 7px;color:#cad2d6}.empty{padding:45px 20px;text-align:center;color:#98a5ac}.empty svg{margin-bottom:10px;color:#adbbb3}.empty h3{font-size:14px;color:#61716d;font-weight:550}.empty p{font-size:11px;line-height:1.7}.empty .btn{margin-top:10px}.zones-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:18px}.zone-card{padding:23px;position:relative}.zone-top{display:flex;justify-content:space-between;align-items:center;margin-bottom:22px}.zone-symbol{height:37px;width:37px;background:#edf4f0;color:#72a184;border-radius:10px;display:grid;place-items:center}.zone-name{font-size:21px;font-weight:620;letter-spacing:-.6px;word-break:break-word}.zone-caption{color:#97a49f;font-size:10px;margin:8px 0 20px}.zone-foot{display:flex;align-items:center;justify-content:space-between;border-top:1px solid #edf1ef;padding-top:14px}.info-box{margin-top:22px;display:flex;gap:12px;padding:18px 20px;border:1px solid #e0e7e2;background:#f2f7f3;border-radius:10px;font-size:11px;line-height:1.8;color:#698473}.info-box strong{color:#476d54}.info-box p{margin:0}.info-box.warning{background:#fbf8ef;border-color:#eae3cc;color:#9a8960}.info-box.warning strong{color:#867143}.two-col{display:grid;grid-template-columns:1.1fr 1fr;gap:23px}.code-panel{background:#1b3036;color:#bfd3c9;border:1px solid #294149;border-radius:10px;overflow:hidden}.code-top{display:flex;align-items:center;justify-content:space-between;padding:15px 19px;background:#ffffff04;border-bottom:1px solid #ffffff09;font-size:10px;color:#96aaa8}.code-top .icon-button{color:#a5bfb4}.code-top .icon-button:hover{background:#ffffff09}.code-panel pre{margin:0;padding:23px 21px;overflow:auto;font:11px/1.9 "SFMono-Regular",Consolas,monospace;white-space:pre;min-height:200px;max-height:480px}.step{display:flex;gap:13px;margin:23px 0}.step-number{border-radius:50%;background:#eaf2ed;color:#769b83;width:25px;height:25px;display:grid;place-items:center;font-size:10px;flex-shrink:0}.step strong{font-size:11px;font-weight:600;color:#43584d}.step p{font-size:10px;color:#8d9c94;line-height:1.8;margin:5px 0}.command-line{display:flex;gap:8px;align-items:center;background:#f5f8f6;border:1px solid #e4ebe7;border-radius:7px;padding:8px 10px;margin-top:10px;max-width:100%}.command-line code{font-size:9px;line-height:1.8;word-break:break-all;color:#5f7a68;flex:1}.command-line .icon-button{flex-shrink:0}.settings-grid{display:grid;grid-template-columns:minmax(0,1.4fr) minmax(260px,1fr);gap:23px}.form-section{padding:24px}.form-section+.form-section{border-top:1px solid var(--line)}.form-section h2{font-size:13px;font-weight:600;margin:0 0 7px}.form-section>p{font-size:11px;color:#909da4;line-height:1.7;margin:0 0 23px}.form-grid{display:grid;grid-template-columns:1fr 1fr;gap:17px}.field{display:flex;flex-direction:column;gap:7px;font-size:11px;color:#566a73;min-width:0}.field.full{grid-column:1/-1}.field input,.field select,.field textarea{border:1px solid #dce4e7;border-radius:7px;background:#fff;padding:10px 11px;color:#32464e;font-size:12px;width:100%;min-height:38px}.field textarea{resize:vertical;line-height:1.6}.field small{font-size:9px;line-height:1.6;color:#95a2a8}.field input::placeholder{color:#b1bbc0}.check-line{display:flex;align-items:center;gap:9px;color:#61746a;font-size:11px;line-height:1.6}.check-line input{accent-color:#347a58;width:15px;height:15px}.form-footer{display:flex;align-items:center;justify-content:flex-end;gap:9px;padding:17px 24px;background:#fafcfb;border-top:1px solid var(--line)}.stack{display:flex;flex-direction:column;gap:18px}.integration{display:flex;gap:11px;padding:18px 0;border-bottom:1px solid #edf1ef;align-items:center}.integration:last-child{border-bottom:0;padding-bottom:0}.integration-icon{height:35px;width:35px;display:grid;place-items:center;background:#f3f6f4;border-radius:9px;color:#8fa699}.integration strong{display:block;font-size:12px;font-weight:550}.integration small{display:block;margin-top:5px;color:#98a6a1;font-size:10px}.integration .badge{margin-left:auto}.certificate-card{padding:26px}.certificate-art{width:55px;height:65px;border:1px solid #c5ddcc;border-radius:9px;background:#f1f8f3;color:#91b79c;display:grid;place-items:center;margin-bottom:22px}.certificate-card h2{font-size:20px;letter-spacing:-.5px;margin:0 0 8px}.key-details{margin:23px 0}.detail-line{display:flex;justify-content:space-between;gap:20px;padding:11px 0;border-bottom:1px solid #eef2ef;font-size:11px;color:#8a9b91}.detail-line strong{font-weight:500;color:#506e5a}.fingerprint{font:10px/1.8 "SFMono-Regular",monospace;word-break:break-all;background:#f6f8f7;border-radius:7px;padding:11px;margin-top:12px;color:#82988a}.history-item{display:flex;align-items:flex-start;gap:10px;padding:13px 0;border-bottom:1px solid #f0f3f1;font-size:11px;color:#6b7f74}.history-item:last-child{border:0}.history-item svg{color:#84a691}.history-item time{font-size:9px;color:#a2aea7;margin-left:auto}.history-item p{margin:0;line-height:1.6}.note{font-size:10px;line-height:1.8;color:#8d9c94}.loading-state{display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:400px;color:#8da094;font-size:12px}.spinner{height:24px;width:24px;border:2px solid #dde9e0;border-top-color:#679c79;border-radius:50%;animation:spin 1s linear infinite}@keyframes spin{to{transform:rotate(360deg)}}dialog{width:570px;max-width:calc(100% - 28px);padding:0;border:1px solid #dce6df;border-radius:15px;box-shadow:0 24px 100px #11271d3b;color:var(--ink);max-height:90vh}dialog::backdrop{background:#15282160;backdrop-filter:blur(3px)}.modal-header{padding:23px 26px 18px;display:flex;align-items:flex-start;justify-content:space-between;border-bottom:1px solid #edf1ef}.modal-header h2{font-size:19px;letter-spacing:-.5px;margin:0 0 7px}.modal-header p{font-size:11px;color:#91a099;margin:0;line-height:1.7}.modal-body{padding:24px 26px;max-height:65vh;overflow:auto}.modal-body .form-grid{gap:16px}.modal-subtitle{font-size:11px;font-weight:600;border-top:1px solid var(--line);padding-top:20px;margin:22px 0 13px;color:#4b6d58}.form-error{padding:11px 13px;margin-top:14px;font-size:11px;color:#aa6150;background:#fff1ec;border:1px solid #f1ddd5;border-radius:7px;line-height:1.7;word-break:break-word}.toast-region{position:fixed;right:28px;bottom:25px;z-index:100;max-width:420px}.toast{display:flex;gap:10px;align-items:flex-start;max-width:calc(100vw - 35px);padding:15px 19px;border:1px solid #d0e3d5;background:#f3faf5;box-shadow:0 8px 36px #24492f20;border-radius:10px;color:#527c60;font-size:12px;line-height:1.6;animation:rise .2s ease}.toast.error{background:#fff4ef;border-color:#eed1c5;color:#a96b56}.toast svg{margin-top:1px;flex-shrink:0}@keyframes rise{from{transform:translateY(10px);opacity:0}to{transform:translateY(0);opacity:1}}.login-screen{position:fixed;inset:0;z-index:50;background:#eff3ef;display:grid;place-items:center;padding:20px}.login-card{background:#fff;border:1px solid #dce7df;border-radius:18px;padding:38px;width:380px;max-width:100%;box-shadow:0 12px 50px #28472e09}.login-card img{margin-bottom:25px}.login-card h1{font-size:25px}.login-card p{font-size:12px;line-height:1.8;color:#87998d;margin:12px 0 26px}.login-card .btn{width:100%;margin-top:20px}.mobile-only{display:none}.sidebar-shade{display:none}details.advanced{margin-top:18px;border-top:1px solid #e8eeea;padding-top:16px}details.advanced summary{cursor:pointer;color:#799584;font-size:11px}details.advanced .form-grid{margin-top:18px}.mobile-label{display:none}@media(min-width:1500px){main{padding-top:45px}.stats{gap:22px}.heading{margin-bottom:30px}.stat{padding:24px}.sidebar{width:260px}.workspace-main{margin-left:260px}.topbar{padding:0 48px}main{padding-left:48px;padding-right:48px}}@media(max-width:1150px){.sidebar{width:212px;padding:28px 13px 20px}.workspace-main{margin-left:212px}.brand{font-size:23px}.topbar{padding:0 26px}main{padding:29px 26px}.stat{padding:17px 15px}.stats{gap:11px}td,th{padding-left:14px;padding-right:14px}.below-grid{grid-template-columns:1.2fr 1fr}.zones-grid{grid-template-columns:repeat(2,1fr)}.settings-grid,.two-col{grid-template-columns:1fr}.page-footer{padding:20px 26px}.flow{gap:5px}.flow-node{min-width:49px}.ssh-card .command-small{font-size:10px}}@media(max-width:850px){.sidebar{transform:translateX(-100%);transition:transform .2s;width:244px}.workspace-main{margin-left:0}.mobile-only{display:inline-grid}.menu-open .sidebar{transform:translateX(0)}.menu-open .sidebar-shade{display:block;position:fixed;inset:0;background:#0d251e55;z-index:19}.topbar{height:65px;padding:0 23px}.heading{align-items:flex-start}h1{font-size:26px}.stats{grid-template-columns:repeat(2,1fr)}.below-grid{grid-template-columns:1fr 1fr}.sidebar-guide{margin-top:auto}.table-end{gap:10px}.topbar-right{gap:15px}.breadcrumb{gap:9px}.page-footer{font-size:8px}}@media(max-width:560px){main{padding:25px 17px}.topbar{padding:0 17px}.breadcrumb>span:first-of-type{display:none}.crumb-slash{display:none}.local-chip{font-size:9px}.topbar-right{gap:8px}.heading{flex-direction:column;gap:20px;margin-bottom:22px}.heading .button-row{width:100%;justify-content:flex-end}.heading .button-row .btn{flex:1}.subtitle{font-size:11px}.stat{padding:17px}.stat-value{font-size:26px}.stats{gap:10px}.below-grid{grid-template-columns:1fr}.toolbar{flex-direction:column;align-items:stretch;padding:14px}.search-box{max-width:none}.filters{align-self:flex-start}.zones-grid{grid-template-columns:1fr}.status-strip{font-size:10px;align-items:flex-start}.status-strip svg{margin-top:3px}.status-strip button{font-size:10px}.form-grid{grid-template-columns:1fr}.field.full{grid-column:auto}.form-section{padding:20px}.modal-body{padding:20px}.modal-header{padding:20px}.form-footer{padding:16px 20px}.page-footer{flex-direction:column;padding:18px;text-align:center;gap:8px}.flow-node{min-width:60px}.section-heading{align-items:flex-start;gap:9px}.panel-pad{padding:20px}.toast-region{right:15px;bottom:15px}.badge{white-space:nowrap}.two-col,.settings-grid{gap:17px}.table-scroll{max-width:calc(100vw - 36px)}}@media(prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}