boneio 1.6.0.dev4__tar.gz → 1.6.0.dev5__tar.gz

{boneio-1.6.0.dev4/boneio.egg-info → boneio-1.6.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boneio
-Version: 1.6.0.dev4
+Version: 1.6.0.dev5
 Summary: Python App for BoneIO
 Author-email: Paweł Szafer <pszafer@gmail.com>
 License: GNU General Public License v3.0

boneio-1.6.0.dev5/boneio/core/cloud/__init__.py

@@ -0,0 +1,5 @@
+"""Cloud registration module for boneIO Black PWA support."""
+
+from boneio.core.cloud.registration import CloudRegistration, set_enabled
+
+__all__ = ["CloudRegistration", "set_enabled"]

{boneio-1.6.0.dev4/boneio/migrations/assets/docker/nodered → boneio-1.6.0.dev5/boneio/core/cloud/data}/docker-compose-cloud.yaml

@@ -20,6 +20,10 @@ services:
       - "${HTTPS_PORT:-8443}:443"
     environment:
       - HOST_HOSTNAME=${HOSTNAME}
+      # The port the host publishes 443 on. Caddy only sees 443 from
+      # inside the container, so a redirect built from what it sees
+      # would send browsers to a port nothing listens on.
+      - PUBLIC_HTTPS_PORT=${HTTPS_PORT:-8443}
     volumes:
       - ./caddy/502.html:/srv/502.html:ro
       - ./caddy/init-certs-cloud.sh:/init-certs-cloud.sh:ro

{boneio-1.6.0.dev4/boneio/migrations/assets/docker/nodered → boneio-1.6.0.dev5/boneio/core/cloud/data}/docker-compose.yaml

@@ -25,6 +25,10 @@ services:
       - "${HTTPS_PORT:-8443}:443"
     environment:
       - HOST_HOSTNAME=${HOSTNAME:-boneio}
+      # The port the host publishes 443 on. Caddy only sees 443 from
+      # inside the container, so a redirect built from what it sees
+      # would send browsers to a port nothing listens on.
+      - PUBLIC_HTTPS_PORT=${HTTPS_PORT:-8443}
     volumes:
       - ./caddy/502.html:/srv/502.html:ro
       - ./caddy/init-certs.sh:/init-certs.sh:ro

{boneio-1.6.0.dev4 → boneio-1.6.0.dev5}/boneio/core/cloud/data/init-certs-cloud.sh

@@ -79,34 +79,12 @@ cat > /tmp/Caddyfile << EOF
 
 # HTTP - serve directly
 :80 {
-        handle_errors {
-                @502-504 expression {err.status_code} >= 502 && {err.status_code} <= 504
-                handle @502-504 {
-                        root * /srv
-                        rewrite * /502.html
-                        file_server
-                }
-        }
-
-        handle /nodered-status {
-                header Content-Type application/json
-                header X-NodeRed-Available "true"
-                header Access-Control-Expose-Headers "X-NodeRed-Available"
-                respond \`{"available": true}\` 200
-        }
-
-        handle /nodered/* {
-                reverse_proxy node-red:1880 {
-                        header_up X-Forwarded-Proto {scheme}
-                        header_down X-NodeRed-Available "true"
-                }
-        }
-
-        handle {
-                reverse_proxy host.docker.internal:8090 {
-                        header_up X-Forwarded-Proto {scheme}
-                }
-        }
+        # Redirect to HTTPS. This port used to serve the panel in the clear —
+        # the login form, the token it hands back, and a configuration carrying
+        # passwords. The port is substituted by this shell as the file is
+        # written: Caddy only sees 443 from inside the container, while the
+        # host publishes it as 8443.
+        redir https://{host}:${PUBLIC_HTTPS_PORT:-8443}{uri}
 }
 
 ${CLOUD_BLOCK}

{boneio-1.6.0.dev4 → boneio-1.6.0.dev5}/boneio/core/cloud/registration.py

@@ -41,9 +41,11 @@ KEY_FILE = CERT_DIR / "privkey.pem"
 
 # Caddy configuration paths
 CADDY_CONFIG_DIR = _DOCKER_DIR / "caddy"
-CADDY_DEFAULT_CONFIG = CADDY_CONFIG_DIR / "Caddyfile"
-CADDY_CLOUD_CONFIG = CADDY_CONFIG_DIR / "Caddyfile.cloud"
-CADDY_ACTIVE_CONFIG = CADDY_CONFIG_DIR / "Caddyfile"
+# No Caddyfile constants here on purpose. Caddy's configuration is not a file
+# in this directory — init-certs.sh (or init-certs-cloud.sh) writes it to
+# /tmp/Caddyfile inside the container on every start. Switching between local
+# and cloud mode swaps the compose file, and with it which of those two scripts
+# runs; there is no Caddyfile to copy over another.
 
 # Registration interval (1 hour)
 REGISTRATION_INTERVAL = 3600
@@ -637,3 +639,76 @@ class CloudRegistration:
             return "init-certs-cloud.sh" in content
         except Exception:
             return False
+
+
+async def set_enabled(config_helper, enabled: bool, local_ip: str | None = None) -> str:
+    """Turn cloud registration on or off on a running device.
+
+    Registration used to begin only in :mod:`boneio.runner`, so switching it on
+    from the panel wrote a line to config.yaml and asked for a restart —
+    on a controller whose whole point is that it is running. Everything the
+    change needs is already here: :meth:`CloudRegistration.start` does no more
+    than launch the loop that registers the name, fetches the certificate,
+    swaps the compose template and recreates Caddy.
+
+    Idempotent in both directions, because the panel can be open twice and a
+    save can be repeated.
+
+    Args:
+        config_helper: The live :class:`ConfigHelper`.
+        enabled: The state asked for.
+        local_ip: This device's address on the LAN. Read from the system when
+            not given.
+
+    Returns:
+        A short word for what happened: ``started``, ``stopped``, ``unchanged``
+        or ``unavailable``.
+    """
+    existing = getattr(config_helper, "_cloud_reg", None)
+
+    if not enabled:
+        config_helper._cloud_registration = False
+        if existing is None:
+            return "unchanged"
+        try:
+            await existing.stop()
+            # Put the plain template back, or Caddy keeps trying to serve a
+            # certificate for a name that is no longer being renewed.
+            await existing._restore_local_config()
+        except Exception as err:  # noqa: BLE001
+            _LOGGER.warning("Could not stop cloud registration cleanly: %s", err)
+        config_helper._cloud_reg = None
+        _LOGGER.info("Cloud registration stopped on request")
+        return "stopped"
+
+    if existing is not None:
+        config_helper._cloud_registration = True
+        return "unchanged"
+
+    serial = getattr(config_helper, "serial_number", None)
+    if not local_ip:
+        try:
+            from boneio.core.system.monitor import get_network_info
+
+            local_ip = (get_network_info() or {}).get("ip", "")
+        except Exception as err:  # noqa: BLE001
+            _LOGGER.warning("Could not read this device's address: %s", err)
+            local_ip = ""
+
+    if not serial or not local_ip:
+        # The setting is saved either way; the next start picks it up. Saying
+        # so is better than reporting success for a service that did not begin.
+        _LOGGER.warning(
+            "Cloud registration is enabled but %s is not known yet; it will "
+            "start on the next boot.",
+            "the serial number" if not serial else "this device's address",
+        )
+        config_helper._cloud_registration = True
+        return "unavailable"
+
+    registration = CloudRegistration(serial_number=serial, local_ip=local_ip)
+    await registration.start()
+    config_helper._cloud_reg = registration
+    config_helper._cloud_registration = True
+    _LOGGER.info("Cloud registration started for %s (IP: %s)", serial, local_ip)
+    return "started"

{boneio-1.6.0.dev4 → boneio-1.6.0.dev5}/boneio/core/config/yaml_patch.py

@@ -260,3 +260,124 @@ def ensure_section(config_file: str | Path, path: tuple[str, ...]) -> bool:
     file_path.write_text("".join(lines), encoding="utf-8")
     _LOGGER.info("Created section '%s' in %s", ".".join(path), file_path)
     return True
+
+
+def _find_section_line(lines: list[str], path: tuple[str, ...]) -> int | None:
+    """Index of the line declaring a nested key, or None if it is not there.
+
+    Args:
+        lines: File lines.
+        path: Section path, outermost first.
+
+    Returns:
+        The index of the key's own line, or None.
+    """
+    depth = 0
+    for index, line in enumerate(lines):
+        parsed = _line_key(line)
+        if parsed is None:
+            continue
+        key, indent, _ = parsed
+        if depth and indent <= (depth - 1) * len(INDENT):
+            return None
+        if key == path[depth] and indent == depth * len(INDENT):
+            depth += 1
+            if depth == len(path):
+                return index
+    return None
+
+
+def has_section(config_file: str | Path, path: tuple[str, ...]) -> bool:
+    """Whether a nested key is present in the file.
+
+    Separate from :func:`remove_section` so a caller can find out before doing
+    anything irreversible — such as writing a backup copy over the one it made
+    the last time it was asked.
+
+    Args:
+        config_file: Path to config.yaml.
+        path: Section path, outermost first.
+
+    Returns:
+        True when the key is there.
+
+    Raises:
+        YamlPatchError: If the path is empty.
+    """
+    if not path:
+        raise YamlPatchError("No section path given.")
+    lines = Path(config_file).read_text(encoding="utf-8").splitlines(keepends=True)
+    return _find_section_line(lines, path) is not None
+
+
+def remove_section(config_file: str | Path, path: tuple[str, ...]) -> bool:
+    """Delete a nested mapping key and everything under it.
+
+    Written for one job: taking the pre-1.6 ``web.auth`` block out of a
+    configuration after its account has been migrated into the hashed store.
+    Nothing reads it any more, and it still holds the owner's password in
+    plain text — in the file, and in every backup and diagnostic bundle made
+    since.
+
+    Line-based rather than a parse-and-dump, for the usual reason: the file
+    belongs to the owner, and round-tripping it through a YAML library would
+    return their comments, ordering and ``!include`` directives as something
+    they did not write.
+
+    Comment lines immediately above the key are removed with it. They describe
+    the block, and leaving them behind stranded over an unrelated setting is
+    worse than taking one comment too many.
+
+    Args:
+        config_file: Path to config.yaml.
+        path: Section path, outermost first, e.g. ``("web", "auth")``.
+
+    Returns:
+        True if something was removed, False if the key was not there.
+
+    Raises:
+        YamlPatchError: If the path is empty.
+    """
+    if not path:
+        raise YamlPatchError("No section path given.")
+
+    file_path = Path(config_file)
+    lines = file_path.read_text(encoding="utf-8").splitlines(keepends=True)
+
+    start = _find_section_line(lines, path)
+    if start is None:
+        return False
+    key_indent = len(lines[start]) - len(lines[start].lstrip())
+
+    # Everything indented under the key belongs to it, blank lines included
+    # while more indented content follows.
+    end = start + 1
+    while end < len(lines):
+        line = lines[end]
+        if not line.strip():
+            following = next(
+                (i for i in range(end + 1, len(lines)) if lines[i].strip()), None
+            )
+            if following is None:
+                break
+            next_indent = len(lines[following]) - len(lines[following].lstrip())
+            if next_indent <= key_indent:
+                break
+            end += 1
+            continue
+        indent = len(line) - len(line.lstrip())
+        if indent <= key_indent:
+            break
+        end += 1
+
+    # Take the comment block sitting directly on top of it.
+    while start > 0:
+        above = lines[start - 1].strip()
+        if above.startswith("#"):
+            start -= 1
+            continue
+        break
+
+    del lines[start:end]
+    file_path.write_text("".join(lines), encoding="utf-8")
+    return True

{boneio-1.6.0.dev4 → boneio-1.6.0.dev5}/boneio/core/containers.py

@@ -55,7 +55,12 @@ _FALLBACK: dict[str, list[str]] = {
     "restart-caddy": ["docker", "compose", "restart", CADDY_SERVICE],
     "reload-caddy": [
         "docker", "compose", "exec", CADDY_SERVICE,
-        "caddy", "reload", "--config", "/etc/caddy/Caddyfile",
+        # /tmp/Caddyfile, not /etc/caddy/Caddyfile: the container runs the
+        # file init-certs.sh writes on every start. /etc/caddy/Caddyfile is the
+        # stock config baked into the image, and reloading that swaps the
+        # working proxy for Caddy's welcome page — HTTPS goes down and stays
+        # down until the container is restarted.
+        "caddy", "reload", "--config", "/tmp/Caddyfile",
     ],
 }
 

boneio-1.6.0.dev5/boneio/core/security/certificate.py

@@ -0,0 +1,297 @@
+"""Checking a certificate and key before the device starts serving them.
+
+An operator who does not want cloud registration still deserves a panel that
+browsers accept, and the way there is their own certificate: from a company CA,
+or from Let's Encrypt obtained on a machine that can actually run the
+challenge. This is the part that decides whether what they uploaded is usable.
+
+The checking is the point. A certificate that does not match its key makes the
+proxy fail to start, and a certificate whose names do not cover the address
+people type produces the same browser warning as before — except now the
+operator believes they fixed it, which is worse than knowing they had not.
+"""
+
+from __future__ import annotations
+
+import datetime
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+
+_LOGGER = logging.getLogger(__name__)
+
+#: Refuse anything larger. A certificate chain is a few kilobytes; a megabyte
+#: of PEM is somebody uploading the wrong file.
+MAX_PEM_BYTES = 256 * 1024
+
+
+class CertificateError(Exception):
+    """The uploaded material cannot be served."""
+
+
+@dataclass
+class CertificateInfo:
+    """What a usable certificate turned out to be."""
+
+    subject: str
+    issuer: str
+    not_before: datetime.datetime
+    not_after: datetime.datetime
+    names: list[str] = field(default_factory=list)
+    fingerprint: str = ""
+    #: Names the device is reached by that this certificate does not cover.
+    #: Not an error — the operator may know something we do not — but the one
+    #: thing worth saying out loud.
+    uncovered: list[str] = field(default_factory=list)
+
+    @property
+    def days_left(self) -> int:
+        """Whole days until it expires."""
+        now = datetime.datetime.now(datetime.UTC)
+        return max(0, (self.not_after - now).days)
+
+    def to_dict(self) -> dict:
+        """Serialise for the API."""
+        return {
+            "subject": self.subject,
+            "issuer": self.issuer,
+            "not_before": self.not_before.isoformat(),
+            "not_after": self.not_after.isoformat(),
+            "days_left": self.days_left,
+            "names": self.names,
+            "fingerprint": self.fingerprint,
+            "uncovered": self.uncovered,
+        }
+
+
+def _names_of(cert: x509.Certificate) -> list[str]:
+    """Every name the certificate is valid for.
+
+    Args:
+        cert: The parsed certificate.
+
+    Returns:
+        DNS names and IP addresses from the SAN extension.
+    """
+    try:
+        san = cert.extensions.get_extension_for_class(
+            x509.SubjectAlternativeName
+        ).value
+    except x509.ExtensionNotFound:
+        return []
+    names = [str(n) for n in san.get_values_for_type(x509.DNSName)]
+    names += [str(n) for n in san.get_values_for_type(x509.IPAddress)]
+    return names
+
+
+def _covers(names: list[str], wanted: str) -> bool:
+    """Whether a certificate's names cover one address.
+
+    Args:
+        names: Names from the certificate.
+        wanted: A hostname or IP address the device is reached by.
+
+    Returns:
+        True when a browser would accept the certificate for *wanted*.
+    """
+    wanted = wanted.strip().lower()
+    if not wanted:
+        return True
+    for name in names:
+        name = name.lower()
+        if name == wanted:
+            return True
+        # A wildcard matches one label, and never the bare domain.
+        if name.startswith("*.") and "." in wanted:
+            if wanted.split(".", 1)[1] == name[2:]:
+                return True
+    return False
+
+
+def inspect(cert_pem: bytes, key_pem: bytes, reached_by: list[str] | None = None) -> CertificateInfo:
+    """Check a certificate and key, and describe what they are.
+
+    Args:
+        cert_pem: The certificate, or a full chain, in PEM.
+        key_pem: The private key in PEM. Must not be encrypted — the proxy
+            starts unattended and has nobody to ask for a passphrase.
+        reached_by: Hostnames and addresses this device is reached by, checked
+            against the certificate's names.
+
+    Returns:
+        What the certificate is.
+
+    Raises:
+        CertificateError: If it cannot be parsed, the key does not match, the
+            key is encrypted, or the certificate has expired.
+    """
+    if len(cert_pem) > MAX_PEM_BYTES or len(key_pem) > MAX_PEM_BYTES:
+        raise CertificateError("That file is far too large to be a certificate.")
+
+    try:
+        cert = x509.load_pem_x509_certificate(cert_pem)
+    except Exception as err:  # noqa: BLE001
+        raise CertificateError(f"The certificate is not readable PEM: {err}") from err
+
+    try:
+        key = serialization.load_pem_private_key(key_pem, password=None)
+    except TypeError as err:
+        raise CertificateError(
+            "The private key is protected by a passphrase. The proxy starts "
+            "unattended and has nobody to ask, so upload an unencrypted key."
+        ) from err
+    except Exception as err:  # noqa: BLE001
+        raise CertificateError(f"The private key is not readable PEM: {err}") from err
+
+    cert_public = cert.public_key().public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    key_public = key.public_key().public_bytes(
+        serialization.Encoding.DER,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    if cert_public != key_public:
+        raise CertificateError(
+            "That key does not belong to that certificate. Serving them "
+            "together would stop the proxy from starting at all."
+        )
+
+    not_after = cert.not_valid_after_utc
+    not_before = cert.not_valid_before_utc
+    now = datetime.datetime.now(datetime.UTC)
+    if not_after <= now:
+        raise CertificateError(
+            f"That certificate expired on {not_after.date()}. Browsers would "
+            "reject it more loudly than the self-signed one it replaces."
+        )
+
+    names = _names_of(cert)
+    uncovered = [
+        address
+        for address in (reached_by or [])
+        if address and not _covers(names, address)
+    ]
+
+    return CertificateInfo(
+        subject=cert.subject.rfc4514_string(),
+        issuer=cert.issuer.rfc4514_string(),
+        not_before=not_before,
+        not_after=not_after,
+        names=names,
+        fingerprint=cert.fingerprint(hashes.SHA256()).hex(),
+        uncovered=uncovered,
+    )
+
+
+def device_addresses(hostname: str | None, ip: str | None) -> list[str]:
+    """The names a browser is likely to be pointed at this device by.
+
+    Args:
+        hostname: The device's hostname.
+        ip: Its address on the local network.
+
+    Returns:
+        Addresses to check a certificate against.
+    """
+    addresses = []
+    for value in (hostname, f"{hostname}.local" if hostname else None, ip):
+        if value and value not in addresses:
+            addresses.append(value)
+    return addresses
+
+
+# --------------------------------------------------------------- on the device
+
+#: Where the proxy reads an uploaded certificate from.
+#:
+#: Inside Caddy's data directory on purpose. That directory is already mounted
+#: into the container and already belongs to the account the panel runs as, so
+#: nothing here needs a change to docker-compose.yaml — which is root-owned and
+#: would have to go out as a migration — and no new mount point can be created
+#: by Docker as root before the panel ever gets to write in it. The cloud
+#: path's own certificate lives elsewhere and is untouched by any of this.
+CERT_DIR = Path.home() / "docker" / "nodered" / "caddy" / "data" / "custom"
+CUSTOM_CERT = CERT_DIR / "fullchain.pem"
+CUSTOM_KEY = CERT_DIR / "privkey.pem"
+
+#: Caddy's own certificate authority, created on first start. Offering it for
+#: download is the cheapest way to a panel that browsers accept: no domain, no
+#: DNS credentials, nothing reachable from outside. What it costs is that a
+#: machine trusting it will believe that authority about any name, so it is
+#: offered with that said rather than as the obvious thing to do.
+ROOT_CA = (
+    Path.home()
+    / "docker" / "nodered" / "caddy" / "data" / "caddy" / "pki"
+    / "authorities" / "local" / "root.crt"
+)
+
+#: The key is a secret, and it is written by the account the panel runs as.
+KEY_MODE = 0o600
+CERT_MODE = 0o644
+
+
+def install(cert_pem: bytes, key_pem: bytes) -> None:
+    """Write a checked certificate and key where the proxy will find them.
+
+    Args:
+        cert_pem: The certificate or chain.
+        key_pem: Its private key.
+
+    Raises:
+        CertificateError: If the files cannot be written.
+    """
+    try:
+        CERT_DIR.mkdir(parents=True, exist_ok=True)
+        # The key is created with its mode already set, so it is never even
+        # briefly readable by anything else on the device.
+        def _private(path: str, flags: int) -> int:
+            return os.open(path, flags, KEY_MODE)
+
+        with open(CUSTOM_KEY, "wb", opener=_private) as handle:
+            handle.write(key_pem)
+        CUSTOM_KEY.chmod(KEY_MODE)
+        CUSTOM_CERT.write_bytes(cert_pem)
+        CUSTOM_CERT.chmod(CERT_MODE)
+    except OSError as err:
+        raise CertificateError(f"Could not store the certificate: {err}") from err
+    _LOGGER.warning("A custom TLS certificate was installed at %s", CUSTOM_CERT)
+
+
+def remove() -> bool:
+    """Delete the custom certificate, returning the proxy to its own.
+
+    Returns:
+        True if something was removed.
+    """
+    removed = False
+    for path in (CUSTOM_CERT, CUSTOM_KEY):
+        try:
+            path.unlink()
+            removed = True
+        except FileNotFoundError:
+            continue
+        except OSError as err:
+            raise CertificateError(f"Could not remove {path.name}: {err}") from err
+    if removed:
+        _LOGGER.warning("The custom TLS certificate was removed")
+    return removed
+
+
+def installed() -> CertificateInfo | None:
+    """Describe the custom certificate in place, if there is one.
+
+    Returns:
+        Its details, or None when the proxy is using its own.
+    """
+    if not (CUSTOM_CERT.exists() and CUSTOM_KEY.exists()):
+        return None
+    try:
+        return inspect(CUSTOM_CERT.read_bytes(), CUSTOM_KEY.read_bytes())
+    except (OSError, CertificateError) as err:
+        _LOGGER.warning("The installed certificate cannot be read: %s", err)
+        return None