"""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 class APIError(Error): def __init__(self, message, status=None): super().__init__(message) self.status = status 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=kwargs.pop("timeout", (5, 30)), allow_redirects=False, **kwargs) except requests.RequestException: raise APIError(f"{self.label}: connection or TLS error at {path}") from None if not 200 <= response.status_code < 300: raise APIError(f"{self.label}: HTTP {response.status_code} at {path}; check credentials, version and permissions", response.status_code) # 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 APIError(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"), "dns_challenge": cert.get("meta", {}).get("dns_challenge") is True, "dns_provider": cert.get("meta", {}).get("dns_provider")} 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)