commit 357daa8915b8479c92ec2eadfc370c80aa273a97 Author: DizelBadCoder Date: Wed Oct 14 01:40:14 2026 +0300 Initial Homegate 0.4.0 with web UI, Compose and Gitea Actions 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}}