Files
homegate/homegate.py
DizelBadCoder eeffcfb616
All checks were successful
Test and publish Homegate / checks (push) Successful in 28s
Test and publish Homegate / publish (push) Successful in 12m47s
Add NPM certificate selection and read-only VDS certificate renewal sync
2026-10-15 05:12:03 +03:00

977 lines
50 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""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 io
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 zipfile
import requests
import yaml
from cryptography import x509
from cryptography.exceptions import InvalidSignature, UnsupportedAlgorithm
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",
"certificate_mode", "npm_certificate_id", "remote_certificate_id"},
"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)
mode = r.setdefault("certificate_mode", "homegate")
require(mode in ("homegate", "npm", "remote_npm"), "Invalid certificate_mode")
if mode == "npm" or "npm_certificate_id" in r:
number(r.get("npm_certificate_id"), 1, 2147483647, "npm_certificate_id")
if mode == "remote_npm":
number(r.get("remote_certificate_id"), 1, 2147483647, "remote_certificate_id")
else:
require("remote_certificate_id" not in r, "remote_certificate_id requires remote_npm mode")
require(mode != "homegate" or "npm_certificate_id" not in r,
"npm_certificate_id requires an NPM certificate mode")
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")
targets = {}
for r in c["services"]:
if r.get("npm_certificate_id"):
target = r["npm_certificate_id"]
source = (r["certificate_mode"], r.get("remote_certificate_id"))
require(target not in targets or targets[target] == source,
"A local certificate cannot have different renewal sources")
targets[target] = source
# 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)
# The standalone deployment enforces LAN access through the configured subnets.
bind_ip = "LAN (configured in the web panel)"
if os.environ.get("HOMEGATE_MANAGED_UI") != "1":
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 RemoteNPM(API):
"""Read-only production source. No renewal, upload, host or settings endpoints."""
login = NPM.login
def call(self, method, path, **kwargs):
require((method == "POST" and path == "/tokens") or
(method == "GET" and path == "/nginx/certificates"),
"Remote NPM is read-only: request refused")
return super().call(method, path, **kwargs)
def download(self, cert_id):
number(cert_id, 1, 2147483647, "remote_certificate_id")
path = f"/nginx/certificates/{cert_id}/download"
try:
with self.session.get(self.base + path, timeout=(5, 30), allow_redirects=False, stream=True) as response:
require(response.status_code == 200, f"Remote NPM: HTTP {response.status_code} downloading certificate")
content = bytearray()
for chunk in response.iter_content(65536):
content.extend(chunk)
require(len(content) <= 2 * 1024 * 1024, "Remote certificate archive is too large")
return bytes(content)
except requests.RequestException:
raise Error("Remote NPM: certificate download connection or TLS error") from None
def certificate_info(cert):
"""Whitelist public fields: NPM responses can contain private keys and DNS tokens."""
domains = cert.get("domain_names", [])
expires = cert.get("expires_on")
fingerprint = None
pem = cert.get("meta", {}).get("certificate")
if isinstance(pem, str) and "BEGIN CERTIFICATE" in pem:
try:
leaf = x509.load_pem_x509_certificate(pem.encode())
domains = leaf.extensions.get_extension_for_class(x509.SubjectAlternativeName).value.get_values_for_type(x509.DNSName)
expires = leaf.not_valid_after_utc.isoformat()
fingerprint = leaf.fingerprint(hashes.SHA256()).hex()
except (ValueError, x509.ExtensionNotFound, x509.DuplicateExtension):
raise Error("NPM certificate has invalid PEM or missing DNS subject alternative names") from None
return {"id": cert["id"], "name": cert.get("nice_name", ""), "provider": cert.get("provider"),
"domains": domains, "expires": expires, "fingerprint": fingerprint,
"modified": cert.get("modified_on")}
def covers_domain(pattern, hostname):
pattern = pattern.lower().rstrip(".")
return pattern == hostname or (pattern.startswith("*.") and
hostname.count(".") == pattern.count(".") and hostname.endswith(pattern[1:]))
def check_certificate(info, hostnames):
try:
expires = datetime.fromisoformat(info["expires"].replace("Z", "+00:00"))
if expires.tzinfo is None:
expires = expires.replace(tzinfo=timezone.utc)
except (ValueError, TypeError, AttributeError):
raise Error("NPM certificate has no valid expiration date") from None
require(expires > now(), "NPM certificate has expired")
for hostname in hostnames:
require(any(covers_domain(d, hostname) for d in info["domains"]),
f"NPM certificate does not cover {hostname}")
return expires
def remote_bundle(content, hostnames):
"""Read bounded PEMs in memory, never extract untrusted ZIP paths to disk."""
try:
with zipfile.ZipFile(io.BytesIO(content)) as archive:
entries = archive.infolist()
require(len(entries) <= 16 and sum(e.file_size for e in entries) <= 2 * 1024 * 1024,
"Invalid remote certificate archive size")
require(all(re.fullmatch(r"[a-zA-Z0-9_.-]+", e.filename) and not e.flag_bits & 1 for e in entries),
"Invalid remote certificate archive entries")
def read_one(pattern):
matches = [e for e in entries if re.fullmatch(pattern, e.filename)]
require(len(matches) == 1, "Remote archive must contain one fullchain and one private key")
return archive.read(matches[0]).decode("ascii")
fullchain = read_one(r"fullchain\d*\.pem")
key_pem = read_one(r"privkey\d*\.pem")
chain = x509.load_pem_x509_certificates(fullchain.encode())
require(len(chain) >= 2, "Remote certificate must include the intermediate chain")
leaf = chain[0]
require(not leaf.extensions.get_extension_for_class(x509.BasicConstraints).value.ca,
"Remote certificate must be a server certificate")
key = serialization.load_pem_private_key(key_pem.encode(), password=None)
public = lambda k: k.public_bytes(serialization.Encoding.DER, serialization.PublicFormat.SubjectPublicKeyInfo)
require(public(key.public_key()) == public(leaf.public_key()), "Remote certificate and key do not match")
require(leaf.not_valid_before_utc <= now(), "Remote certificate is not valid yet")
for child, issuer in zip(chain, chain[1:]):
child.verify_directly_issued_by(issuer)
require(issuer.extensions.get_extension_for_class(x509.BasicConstraints).value.ca,
"Invalid intermediate CA")
require(issuer.not_valid_before_utc <= now() < issuer.not_valid_after_utc,
"Remote intermediate certificate is not valid")
info = certificate_info({"id": 0, "meta": {"certificate": fullchain}})
check_certificate(info, hostnames)
return {"cert": leaf.public_bytes(serialization.Encoding.PEM).decode(), "key": key_pem,
"chain": "".join(c.public_bytes(serialization.Encoding.PEM).decode() for c in chain[1:]),
"info": info}
except (zipfile.BadZipFile, UnicodeError, ValueError, TypeError, InvalidSignature, NotImplementedError,
UnsupportedAlgorithm, x509.ExtensionNotFound, x509.DuplicateExtension):
raise Error("Invalid remote certificate archive, key or certificate chain") from None
class CertificateSync:
"""Copy renewed source certificates into the home NPM; retain last copy offline."""
def __init__(self, npm, remote, settings, state, registry, routes):
self.npm, self.remote, self.settings = npm, remote, settings or {}
self.state, self.registry, self.routes = state, registry, routes
self.sources = None
self.source_error = None
self.results = {}
self.conflicts = set()
targets = {}
for route in routes:
target_id = route.get("npm_certificate_id")
if not target_id and route.get("certificate_mode") == "remote_npm":
name = f'homegate:{registry["instance"]}:remote:{route["remote_certificate_id"]}'
target_id = next((c["id"] for c in npm.certs if c.get("nice_name") == name), None)
if target_id:
source = (route["certificate_mode"], route.get("remote_certificate_id"))
if target_id in targets and targets[target_id] != source:
self.conflicts.add(target_id)
targets[target_id] = source
def get_sources(self):
if self.source_error:
raise Error(self.source_error)
if self.sources is None:
try:
require(self.remote is not None, "Configure the VDS NPM connection in Settings")
self.remote.login(self.settings["remote_npm_identity"], self.settings["remote_npm_password"])
self.sources = self.remote.call("GET", "/nginx/certificates")
except (Error, KeyError):
self.source_error = "Remote NPM unavailable; check its connection and certificate read permissions"
raise Error(self.source_error) from None
return self.sources
def select(self, route):
target_id = route.get("npm_certificate_id")
source_id = route.get("remote_certificate_id")
name = f'homegate:{self.registry["instance"]}:remote:{source_id}'
matches = [c for c in self.npm.certs if c["id"] == target_id] if target_id else [
c for c in self.npm.certs if c.get("nice_name") == name]
require(len(matches) <= 1, "Duplicate local NPM certificate")
target = matches[0] if matches else None
require(target is not None or not target_id, "Selected local NPM certificate no longer exists")
require(not target or target["id"] not in self.conflicts,
"Local certificate has conflicting renewal sources; use a separate copy")
if route["certificate_mode"] == "npm":
info = certificate_info(target)
check_certificate(info, [route["hostname"]])
signature = {"id": target["id"], "sha256": info["fingerprint"],
"expires": info["expires"], "modified": info["modified"]}
return target["id"], info, signature, None
require(target is None or target["provider"] == "other",
"VDS synchronization requires a custom certificate in the home NPM")
cache_key = str(target["id"]) if target else name
if cache_key in self.results:
check_certificate(self.results[cache_key][1], [route["hostname"]])
return self.results[cache_key]
error = None
# Validate every local proxy sharing this certificate before replacing it.
hostnames = {r["hostname"] for r in self.routes if r.get("npm_certificate_id") == target_id and
(target_id or r.get("remote_certificate_id") == source_id)}
hostnames.update(d for host in self.npm.hosts if target and host.get("certificate_id") == target["id"]
for d in host["domain_names"])
records = self.registry.setdefault("certificate_copies", {})
record = records.get(str(target["id"]), {}) if target else {}
try:
sources = [c for c in self.get_sources() if c["id"] == source_id]
require(len(sources) == 1 and sources[0]["provider"] == "letsencrypt",
"Select an existing Let's Encrypt certificate from VDS NPM")
source = certificate_info(sources[0])
check_certificate(source, hostnames)
revision = {"url": self.remote.base, "id": source_id,
"expires": source["expires"], "modified": source["modified"]}
local = certificate_info(target) if target else None
if (record.get("source") != revision or not local or
local["fingerprint"] != record.get("fingerprint") or
time.time() - record.get("checked_at", 0) >= 86400):
bundle = remote_bundle(self.remote.download(source_id), hostnames)
info = bundle["info"]
if local and local["expires"]:
# A source rolled back to an older certificate must not shorten local validity.
try:
old_expiry = check_certificate(local, hostnames)
except Error:
old_expiry = now()
require(check_certificate(info, hostnames) >= old_expiry,
"VDS certificate is older than the local copy")
if not target:
target = self.npm.call("POST", "/nginx/certificates", json={"provider": "other", "nice_name": name})
self.npm.certs.append(target)
digest = hashlib.sha256((bundle["cert"] + bundle["chain"]).encode()).hexdigest()
if not local or local["fingerprint"] != info["fingerprint"] or record.get("sha256") != digest:
self.npm.call("POST", f'/nginx/certificates/{target["id"]}/upload', files={
"certificate": ("certificate.pem", bundle["cert"], "application/x-pem-file"),
"certificate_key": ("key.pem", bundle["key"], "application/x-pem-file"),
"intermediate_certificate": ("chain.pem", bundle["chain"], "application/x-pem-file"),
})
target.update(expires_on=info["expires"], domain_names=info["domains"],
meta={"certificate": bundle["cert"]})
record = {"source": revision, "fingerprint": info["fingerprint"], "sha256": digest,
"checked_at": time.time(), "synced_at": time.time()}
records[str(target["id"])] = record
save_json(self.state / "registry.json", self.registry)
except (Error, ValueError, KeyError, OSError) as exc:
error = str(exc)
LOG.warning("VDS certificate copy: %s", error)
require(target is not None, error or "Local certificate copy is not available yet")
info = certificate_info(target)
check_certificate(info, [route["hostname"]])
info["synced_at"] = record.get("synced_at")
info["sync_error"] = error
# The route records this fingerprint only after nginx accepted a reload.
signature = {"id": target["id"], "sha256": record.get("sha256") or info["fingerprint"]}
result = (target["id"], info, signature, error)
self.results[str(target["id"])] = self.results[cache_key] = result
return result
class PiHole(API):
def login(self, password):
self.session.headers.pop("X-FTL-SID", None)
self.session.headers.pop("X-FTL-CSRF", None)
self.session.cookies.clear()
session = self.call("POST", "/auth", json={"password": password})["session"]
# Pi-hole with authentication disabled returns valid=true, sid=null,
# validity=-1 and no CSRF token. It needs neither auth headers nor logout.
no_password = "sid" in session and session["sid"] is None and session.get("validity") == -1
require(session.get("valid") is True and (session.get("sid") or no_password),
"Pi-hole authentication failed")
if session.get("sid"):
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, remote=None, settings=None):
npm.inventory()
certificates = CertificateSync(npm, remote, settings, state, registry, config["services"])
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"])
previous = registry["routes"].get(host, {})
cert_error = None
if route.get("certificate_mode", "homegate") == "homegate":
bundle = ca.leaf(host)
cert_id, changed, signature = npm.certificate(name, bundle, previous.get("uploaded"))
cert_info = None
else:
cert_id, cert_info, signature, cert_error = certificates.select(route)
changed = signature != 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,
"certificate": cert_info, "certificate_mode": route.get("certificate_mode", "homegate")}
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"])
if cert_error:
failures.append(host)
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
settings_file = os.environ.get("HOMEGATE_CONNECTIONS")
settings = read_json(Path(settings_file)) if settings_file else None
if settings is not None and settings.get("api_ca_pem"):
ca_path = Path(settings_file).with_name("management-ca.pem")
atomic(ca_path, settings["api_ca_pem"].encode(), 0o600)
verify = str(ca_path)
npm = NPM(settings["npm_url"] if settings is not None else os.environ.get("NPM_URL", ""), "NPM", verify)
dns = None
remote = None
dns_error = False
try:
npm.login(settings["npm_identity"] if settings is not None else os.environ.get("NPM_IDENTITY", ""),
settings["npm_password"] if settings is not None else secret("NPM"))
if config["dns_mode"] == "pihole6":
dns = PiHole(settings["pihole_url"] if settings is not None else os.environ.get("PIHOLE_URL", ""), "PIHOLE", verify)
try:
dns.login(settings["pihole_password"] if settings is not None else 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
if settings and settings.get("remote_npm_url") and any(
r.get("certificate_mode") == "remote_npm" for r in config["services"]):
remote = RemoteNPM(settings["remote_npm_url"], "Remote NPM")
reconcile(config, state, ca, registry, npm, dns, remote, settings)
require(not dns_error, "Pi-hole login failed; proxy/certificate maintenance completed")
finally:
npm.close()
if dns:
dns.close()
if remote:
remote.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 = []
registry = read_json(state / "registry.json", {"routes": {}})
for route in config["services"]:
mode = route.get("certificate_mode", "homegate")
if mode != "homegate":
saved = registry["routes"].get(route["hostname"], {})
info = saved.get("certificate") if saved.get("certificate_mode") == mode else None
if info and (not route.get("npm_certificate_id") or info["id"] == route["npm_certificate_id"]):
certs.append({"hostname": route["hostname"], "mode": mode, **info})
continue
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"], "mode": mode, "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)