Split host setup into explicit entity actions

actions/config/adam.py

@@ -0,0 +1,54 @@
+"""Provision the golden-image operator while preserving authorized keys."""
+import pwd
+import grp
+from pathlib import Path
+from engine.descriptor import Meta, Opt
+
+METADATA = Meta(summary="Configure the adam operator, sudo access and optional SSH public key.",
+                args=[Opt("--public-key-file", "Append one OpenSSH public key from this file.")])
+
+
+HOME = Path("/home/adam")
+
+
+def run(ctx, args):
+    system = ctx.sys
+    key = None
+    if args.public_key_file:
+        key = Path(args.public_key_file).read_text().strip()
+        if len(key.splitlines()) != 1 or not key.startswith(("ssh-", "ecdsa-", "sk-")):
+            raise ValueError("Supply one OpenSSH public key.")
+        system.run(["ssh-keygen", "-lf", "-"], input=key + "\n", capture=True)
+    groups = ["sudo"]
+    try:
+        grp.getgrnam("docker")
+    except KeyError:
+        pass
+    else:
+        groups.append("docker")
+    try:
+        account = pwd.getpwnam("adam")
+    except KeyError:
+        if HOME.exists() or HOME.is_symlink():
+            raise RuntimeError("Resolve existing /home/adam before creating the account.") from None
+        system.sudo(["useradd", "--create-home", "--shell", "/bin/bash", "--user-group", "adam"])
+        account = pwd.getpwnam("adam")
+    if account.pw_uid < 1000 or Path(account.pw_dir) != HOME or HOME.resolve() != HOME:
+        raise RuntimeError("Existing adam account has incompatible UID or home.")
+    if Path(account.pw_dir).stat().st_uid != account.pw_uid:
+        raise RuntimeError("The operator must own /home/adam.")
+    system.sudo(["usermod", "--shell", "/bin/bash", "--append", "--groups", ",".join(groups), "adam"])
+    if key:
+        system.sudo(["runuser", "-u", "adam", "--", "sh", "-ec",
+                     'umask 077; cd "$1"; mkdir -p .ssh; chmod 700 .ssh; '
+                     'touch .ssh/authorized_keys; chmod 600 .ssh/authorized_keys; '
+                     'IFS= read -r key; grep -Fxq -- "$key" .ssh/authorized_keys || '
+                     'printf "\\n%s\\n" "$key" >> .ssh/authorized_keys', "sh", str(HOME)], input=key + "\n")
+    content = "adam ALL=(ALL:ALL) NOPASSWD: ALL\n"
+    system.sudo(["visudo", "-cf", "-"], input=content)
+    path = Path("/etc/sudoers.d/99-apex-adam")
+    if path.is_symlink():
+        raise RuntimeError(f"Refusing redirected sudo policy: {path}")
+    ctx.host.write_file(str(path), content, mode="0440", backup=False, sudo=True)
+    system.sudo(["visudo", "-c"])
+    system.sudo(["runuser", "-u", "adam", "--", "sudo", "-n", "true"])

actions/config/alloy.py

@@ -0,0 +1,77 @@
+"""Deploy the opt-in native Alloy service using shared host/guest configs."""
+import json
+from pathlib import Path
+import re
+import tempfile
+
+from engine.descriptor import Flag, Meta
+
+METADATA = Meta(summary="Configure native Alloy from configs/alloy/config.json.",
+                args=[Flag("--dry-run", "Validate the deployment plan without changes.")])
+
+
+def deployment(ctx):
+    settings = Path(ctx.paths.configs) / "alloy/config.json"
+    if not settings.exists():
+        return None
+    values = json.loads(settings.read_text())
+    role = values.get("role")
+    if role not in ("host", "guest"):
+        raise ValueError("Alloy role must be host or guest")
+    env_file = values.get("environment_file", "")
+    if not re.fullmatch(r"/[A-Za-z0-9_./-]+", env_file):
+        raise ValueError("Alloy environment_file must be an absolute path without whitespace")
+    source = Path(ctx.paths.commons) / "etc/alloy" / (
+        "native-host.alloy" if role == "host" else "native.alloy")
+    config = source.read_text()
+    extra = Path(ctx.paths.configs) / "alloy/extra.alloy"
+    if extra.is_file():
+        config += "\n" + extra.read_text()
+    unit = ("[Service]\nEnvironmentFile=" + env_file + "\n"
+            'ExecStart=\nExecStart=/usr/bin/alloy run --storage.path=/var/lib/alloy --server.http.listen-addr=127.0.0.1:12346 /etc/alloy/config.alloy\n'
+            + ("User=root\nGroup=root\n" if role == "guest" else "") +
+            "SupplementaryGroups=systemd-journal" + (" docker" if role == "guest" else "") + "\n")
+    return config, unit, env_file
+
+
+def run(ctx, args):
+    plan = deployment(ctx)
+    if plan is None:
+        ctx.log.info("Native Alloy is not configured for this node; skipping.")
+        return
+    config, unit, env_file = plan
+    if args.dry_run:
+        ctx.log.info("Native Alloy deployment plan validated; no changes made.")
+        return
+    ctx.sys.sudo(["test", "-f", env_file])
+    # Validate with the actual service environment without printing credentials.
+    validator = '''import os, stat, subprocess, sys
+from pathlib import Path
+# Environment files deliberately use plain KEY=value, with no shell evaluation.
+secret = Path(sys.argv[1])
+info = secret.stat()
+if info.st_uid != 0 or stat.S_IMODE(info.st_mode) & 0o077:
+    raise RuntimeError('Alloy environment file must be root-owned with mode 0600 or stricter')
+for line in secret.read_text().splitlines():
+    if not line.strip() or line.lstrip().startswith('#'): continue
+    key, value = line.split('=', 1)
+    os.environ[key] = value
+subprocess.run(['alloy', 'validate', sys.argv[2]], check=True)
+'''
+    with tempfile.TemporaryDirectory(prefix="apex-alloy-") as directory:
+        config_path = Path(directory) / "config.alloy"
+        unit_path = Path(directory) / "apex.conf"
+        config_path.write_text(config)
+        unit_path.write_text(unit)
+        ctx.sys.sudo(["python3", "-c", validator, env_file, str(config_path)])
+        ctx.sys.sudo(["install", "-d", "-m", "0755", "/etc/alloy",
+                      "/etc/systemd/system/alloy.service.d"])
+        ctx.sys.sudo(["install", "-m", "0644", str(config_path), "/etc/alloy/config.alloy"])
+        ctx.sys.sudo(["install", "-m", "0644", str(unit_path),
+                      "/etc/systemd/system/alloy.service.d/apex.conf"])
+    ctx.sys.sudo(["systemctl", "unmask", "alloy.service"])
+    ctx.sys.daemon_reload()
+    ctx.sys.sudo(["systemctl", "enable", "alloy.service"])
+    ctx.sys.sudo(["systemctl", "restart", "alloy.service"])
+    ctx.sys.sudo(["systemctl", "is-active", "--quiet", "alloy.service"])
+    ctx.log.success("Configured native Alloy.")

actions/config/base.py

@@ -0,0 +1,40 @@
+"""Apply the common APT archive and journald retention policy."""
+from pathlib import Path
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Configure APT archive cleanup and journald retention.")
+
+
+def _configure(ctx, path, legacy, content, restart=False):
+    for target in (path, legacy):
+        if target.is_symlink():
+            raise RuntimeError(f"Refusing redirected configuration: {target}")
+    previous = path.read_text() if path.exists() else None
+    backup = ctx.host.backup(str(legacy), sudo=True) if legacy.exists() else None
+    if previous == content and not backup:
+        return
+    if previous != content:
+        ctx.host.write_file(str(path), content, sudo=True)
+    if backup:
+        ctx.sys.sudo(["rm", "--", str(legacy)])
+    if restart:
+        try:
+            ctx.sys.sudo(["systemctl", "restart", "systemd-journald"])
+        except Exception:
+            if backup:
+                ctx.sys.sudo(["cp", "--preserve=all", "--", backup, str(legacy)])
+            if previous is None:
+                ctx.sys.sudo(["rm", "--", str(path)])
+            elif previous != content:
+                ctx.host.write_file(str(path), previous, backup=False, sudo=True)
+            raise
+
+
+def run(ctx, args):
+    if not Path("/etc/debian_version").is_file():
+        raise RuntimeError("Debian required.")
+    apt = Path("/etc/apt/apt.conf.d")
+    journal = Path("/etc/systemd/journald.conf.d")
+    _configure(ctx, apt / "99-apex", apt / "01clean", 'APT::Keep-Downloaded-Packages "0";\n')
+    _configure(ctx, journal / "99-apex.conf", journal / "maxuse.conf",
+               "[Journal]\nSystemMaxUse=200M\n", restart=True)

actions/config/cron.py

@@ -0,0 +1,14 @@
+# actions/config/cron.py
+"""Port of config/cron — install crontab from configs/cron/crontab."""
+import os
+from engine.descriptor import Meta, Flag
+
+METADATA = Meta(summary="Install the node crontab from configs/cron/crontab.",
+                args=[Flag("--dry-run", "Render + preview; do not install.")])
+
+def run(ctx, args):
+    crontab = os.path.join(ctx.paths.configs, "cron", "crontab")
+    if not os.path.isfile(crontab):
+        ctx.log.error(f"Crontab file not found: {crontab}"); raise SystemExit(1)
+    text = ctx.tpl.render(crontab, ctx.vars())
+    ctx.host.install_crontab(text, dry_run=args.dry_run)

actions/config/crowdsec.py

@@ -0,0 +1,24 @@
+# actions/config/crowdsec.py
+"""Port of config/crowdsec — install, deploy /etc/crowdsec, collections, bouncer."""
+import os
+from engine.descriptor import Meta, Flag
+
+METADATA = Meta(summary="Install + configure CrowdSec from configs/crowdsec.",
+                args=[Flag("--dry-run", "Render only; do not write/reload.")])
+
+def run(ctx, args):
+    cfg = os.path.join(ctx.paths.configs, "crowdsec")
+    if not os.path.isdir(cfg):
+        ctx.log.error(f"Config directory not found: {cfg}"); raise SystemExit(1)
+    ctx.log.info("Configuring CrowdSec...")
+    if not args.dry_run:
+        ctx.crowdsec.ensure_installed()
+    ctx.crowdsec.deploy("crowdsec", ctx.vars(), dry_run=args.dry_run)
+    if not args.dry_run:
+        ctx.crowdsec.install_collections(["crowdsecurity/linux", "crowdsecurity/traefik"])
+        bouncer = os.path.join(cfg, "bouncers", "crowdsec-firewall-bouncer.yaml.local")
+        if os.path.isfile(bouncer) and not ctx.sys.ok(
+                ["bash", "-c", "dpkg -l | grep -q crowdsec-firewall-bouncer-iptables"]):
+            ctx.log.info("Installing crowdsec-firewall-bouncer-iptables...")
+            ctx.sys.install_packages(["crowdsec-firewall-bouncer-iptables"])
+    ctx.log.success("Configured crowdsec.")

actions/config/docker.py

@@ -0,0 +1,12 @@
+"""Install a local Docker Engine, Compose and Buildx on Debian 13."""
+from pathlib import Path
+
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Verify a working Docker toolchain or install it on stock Debian 13.")
+
+
+def run(ctx, args):
+    provisioning = Path(ctx.paths.commons) / "ci/scripts/init-node"
+    ctx.sys.sudo(["python3", "-E", "-s", "-m", "provisioning.baseline", "--docker-policy"],
+                 cwd=str(provisioning))

actions/config/env.py

@@ -0,0 +1,82 @@
+"""Export synthesized APEX values or bridge a composition's environment for Compose."""
+import os
+import shlex
+
+from engine.descriptor import Flag, Meta, Opt
+
+METADATA = Meta(
+    summary="Export or sync synthesized APEX_* variables for shell or docker compose.",
+    args=[
+        Flag("--export", "Format as shell export statements (default)."),
+        Flag("--dotenv", "Print quoted generated APEX_* dotenv values only."),
+        Opt("--write", "Write a standalone generated dotenv file (0600).", default=None),
+        Flag("--sync", "Preserve user .env text and refresh the core Compose managed block."),
+    ],
+)
+
+_START = "# BEGIN APEX MANAGED ENV"
+_END = "# END APEX MANAGED ENV"
+
+
+def _dotenv_value(value):
+    """Quote a literal using Compose dotenv escapes, including interpolation dollars."""
+    value = str(value)
+    for old, new in (("\\", "\\\\"), ('"', '\\"'), ("$", "$$"),
+                     ("\r", "\\r"), ("\n", "\\n"), ("\t", "\\t")):
+        value = value.replace(old, new)
+    return f'"{value}"'
+
+
+def _read_optional(path):
+    try:
+        with open(path, encoding="utf-8", newline="") as source:
+            return source.read()
+    except FileNotFoundError:
+        return ""
+
+
+def _sync_body(existing, public, generated):
+    if any(marker in public or marker in generated for marker in (_START, _END)):
+        raise ValueError("Managed environment marker collides with source content.")
+    lines = existing.splitlines(keepends=True)
+    markers = [(index, line.rstrip("\r\n")) for index, line in enumerate(lines)
+               if _START in line or _END in line]
+    if markers:
+        if (len(markers) != 2 or markers[0][1] != _START or markers[1][1] != _END):
+            raise ValueError("Malformed or duplicate managed environment markers; .env unchanged.")
+        start, end = markers[0][0], markers[1][0]
+        existing = "".join(lines[:start] + lines[end + 1:])
+    # Keep user bytes in order, but place managed values last to preserve precedence.
+    separator = "" if not existing or existing.endswith("\n") else "\n"
+    public_separator = "" if not public or public.endswith("\n") else "\n"
+    return (existing + separator + _START + "\n" + public + public_separator
+            + generated + _END + "\n")
+
+
+def run(ctx, args):
+    modes = (args.export, args.dotenv, args.write is not None, args.sync)
+    if sum(bool(mode) for mode in modes) > 1:
+        ctx.log.error("Choose only one of --export, --dotenv, --write, or --sync.")
+        raise SystemExit(64)
+    variables = {k: v for k, v in ctx.vars().items() if k.startswith("APEX_")}
+    generated = "".join(f"{key}={_dotenv_value(value)}\n"
+                        for key, value in sorted(variables.items()))
+    target = args.write
+    if args.sync:
+        core = os.path.join(ctx.paths.compositions, "apex")
+        target = os.path.join(core, ".env")
+        try:
+            generated = _sync_body(_read_optional(target),
+                                   _read_optional(os.path.join(core, "apex.env")), generated)
+        except ValueError as error:
+            ctx.log.error(str(error))
+            raise SystemExit(65) from error
+    if target is not None:
+        ctx.host.write_file(target, generated, mode="0600")
+        ctx.log.success(f"Wrote {len(variables)} synthesized variables to {target}.")
+    elif args.dotenv:
+        print(generated, end="")
+    else:
+        for key, value in sorted(variables.items()):
+            print(f"export {key}={shlex.quote(str(value))}")
+    return 0

actions/config/hardening.py

@@ -0,0 +1,143 @@
+"""Apply the image's public-key SSH policy to adam after a verified key login."""
+import ipaddress
+import json
+import os
+import pwd
+import re
+from pathlib import Path
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Require SSH public-key authentication for adam from an independent administrator or verified adam key session.")
+CONFIG = "/etc/ssh/sshd_config"
+POLICY = """
+# APEX operator SSH policy
+Match User adam
+    AuthenticationMethods publickey
+    PubkeyAuthentication yes
+    PasswordAuthentication no
+    KbdInteractiveAuthentication no
+    PermitEmptyPasswords no
+    X11Forwarding no
+"""
+
+
+def _ancestors():
+    ancestors = {}
+    pid = os.getppid()
+    ticks = os.sysconf("SC_CLK_TCK")
+    while pid > 1:
+        # comm can contain spaces and parentheses; the remaining fields start at state.
+        fields = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
+        ancestors[pid] = int(fields[19]) * 1_000_000 // ticks
+        pid = int(fields[1])
+    return ancestors
+
+
+def _connection(ctx):
+    if pwd.getpwuid(os.getuid()).pw_name != "adam":
+        raise RuntimeError("Run config/hardening inside an SSH public-key session as adam.")
+    ancestors = _ancestors()
+    sockets = ctx.sys.sudo(["ss", "-Hntp", "state", "established"], capture=True).stdout
+    connections = set()
+    for line in sockets.splitlines():
+        fields = line.split(None, 4)
+        if len(fields) == 5 and any(int(pid) in ancestors for pid in
+                                    re.findall(r'"sshd(?:-session)?",pid=(\d+),', fields[4])):
+            connections.add((fields[2], fields[3]))
+    if len(connections) != 1:
+        raise RuntimeError("Cannot identify a unique established SSH socket for this process.")
+    local, peer = connections.pop()
+    peer, peer_port = peer.rsplit(":", 1)
+    local, local_port = local.rsplit(":", 1)
+    def address(value):
+        ip = ipaddress.ip_address(value.strip("[]"))
+        return str(getattr(ip, "ipv4_mapped", None) or ip)
+    peer, local = address(peer), address(local)
+    record = rf"^Accepted publickey for adam from {re.escape(peer)} port {int(peer_port)} ssh2:"
+    result = ctx.sys.sudo(["journalctl", "-b", "_UID=0", "_EXE=/usr/sbin/sshd",
+                           "_EXE=/usr/lib/openssh/sshd-session", "_EXE=/usr/lib/openssh/sshd-auth",
+                           "--no-pager", "-o", "json", "--grep", record], capture=True, check=False)
+    if not result.returncode:
+        for line in result.stdout.splitlines():
+            entry = json.loads(line)
+            pid = int(entry["_PID"])
+            if (pid in ancestors and int(entry["__MONOTONIC_TIMESTAMP"]) >= ancestors[pid]
+                    and re.match(record, entry["MESSAGE"])):
+                ctx.sys.run(["sudo", "-n", "true"])
+                return f"user=adam,host={peer},addr={peer},laddr={local},lport={int(local_port)}"
+    raise RuntimeError("Cannot verify public-key login for this SSH process in the root sshd journal.")
+
+
+def _operator_access(ctx):
+    account = pwd.getpwnam("adam")
+    if account.pw_uid < 1000 or account.pw_dir != "/home/adam":
+        raise RuntimeError("Configure a regular adam operator account first.")
+    if pwd.getpwuid(os.getuid()).pw_name == "adam":
+        return _connection(ctx)
+    loginuid = int(Path("/proc/self/loginuid").read_text())
+    if loginuid in (account.pw_uid, 4294967295) or loginuid < 0:
+        raise RuntimeError("Use an independent administrator login or an SSH public-key session as adam.")
+    if os.getuid() not in (0, loginuid):
+        raise RuntimeError("Run from the independent administrator's own login.")
+    ctx.sys.sudo(["true"])
+    home = Path(account.pw_dir)
+    authorized = home / ".ssh" / "authorized_keys"
+    # Inspect as adam so private .ssh directories remain usable from another administrator.
+    command = ["runuser", "-u", "adam", "--"]
+    for path in (home, authorized.parent, authorized):
+        metadata = ctx.sys.sudo([*command, "env", "LC_ALL=C", "stat", "-c", "%u %a %F", "--", str(path)],
+                                capture=True).stdout.strip().split(" ", 2)
+        owner, mode, kind = metadata
+        expected = "regular file" if path == authorized else "directory"
+        if int(owner) not in (0, account.pw_uid) or int(mode, 8) & 0o022 or kind != expected:
+            raise RuntimeError(f"Unsafe operator SSH path: {path}")
+    keys = ctx.sys.sudo([*command, "cat", "--", str(authorized)], capture=True).stdout
+    for key in keys.splitlines():
+        if key.startswith(("ssh-", "ecdsa-", "sk-")) and ctx.sys.run(
+            ["ssh-keygen", "-lf", "-"], input=key + "\n", capture=True, check=False,
+        ).returncode == 0:
+            break
+    else:
+        raise RuntimeError("Install a valid unrestricted operator public key before applying SSH hardening.")
+    ctx.sys.sudo([*command, "sudo", "-n", "true"])
+    connection = "user=adam,host=localhost,addr=127.0.0.1"
+    paths = _effective(ctx.sys, connection).get("authorizedkeysfile", "").split()
+    if not {".ssh/authorized_keys", "%h/.ssh/authorized_keys", str(authorized)}.intersection(paths):
+        raise RuntimeError("sshd does not use the operator's verified authorized_keys file.")
+    return connection
+
+
+def _effective(system, connection):
+    result = system.sudo(["/usr/sbin/sshd", "-T", "-C", connection], capture=True)
+    return dict(line.split(" ", 1) for line in result.stdout.splitlines() if " " in line)
+
+
+def run(ctx, args):
+    connection = _operator_access(ctx)
+    system = ctx.sys
+    system.sudo(["/usr/sbin/sshd", "-t"])
+    effective = _effective(system, connection)
+    if effective.get("authenticationmethods") not in ("any", "publickey"):
+        raise RuntimeError("Preserve the existing SSH authentication chain; reconcile it explicitly.")
+    required = {"authenticationmethods": "publickey", "pubkeyauthentication": "yes",
+                "passwordauthentication": "no", "kbdinteractiveauthentication": "no",
+                "permitemptypasswords": "no", "x11forwarding": "no"}
+    if all(effective.get(key) == value for key, value in required.items()):
+        return
+    if Path(CONFIG).is_symlink():
+        raise RuntimeError(f"Refusing redirected SSH configuration: {CONFIG}")
+    original = system.sudo(["cat", CONFIG], capture=True).stdout
+    if "# APEX operator SSH policy" in original:
+        raise RuntimeError("The managed SSH policy is ineffective; reconcile earlier directives.")
+    ctx.host.write_file(CONFIG, original + "\n" + POLICY, sudo=True)
+    try:
+        system.sudo(["/usr/sbin/sshd", "-t"])
+        effective = _effective(system, connection)
+        if any(effective.get(key) != value for key, value in required.items()):
+            raise RuntimeError("The effective SSH policy differs; inspect existing Match blocks.")
+        system.reload("ssh")
+    except BaseException:
+        ctx.host.write_file(CONFIG, original, backup=False, sudo=True)
+        system.sudo(["/usr/sbin/sshd", "-t"])
+        system.reload("ssh")
+        raise

actions/config/packages.py

@@ -0,0 +1,50 @@
+"""Install common Debian administrator tools without replacing host packages."""
+import re
+from pathlib import Path
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Install Debian administrator packages and enable rsyslog.")
+BASE_PACKAGES = ("curl", "wget", "git", "rsyslog", "ufw")
+
+
+ADMIN_PACKAGES = (
+    "tcpdump", "socat", "rsync", "bind9-dnsutils", "iproute2", "net-tools",
+    "traceroute", "ca-certificates", "jq", "sed", "gawk", "tar", "gzip",
+    "bzip2", "xz-utils", "unzip", "htop", "iotop", "strace", "lsof",
+    "sysstat", "parted", "fdisk", "pciutils", "usbutils", "smartmontools",
+    "tmux", "vim", "less", "tree", "bash-completion", "python3",
+    "python3-minimal", "python3-yaml", "sudo", "cron", "iptables", "ipset",
+    "debian-archive-keyring", "kmod",
+)
+
+def _install_missing(s, packages):
+    missing = []
+    for package in packages:
+        result = s.run(["dpkg-query", "-W", "-f=${Status}", package],
+                       check=False, capture=True)
+        if result.returncode or result.stdout.split()[1:] != ["ok", "installed"]:
+            missing.append(package)
+    if not missing:
+        return
+    apt = ["env", "LC_ALL=C", "DEBIAN_FRONTEND=noninteractive", "apt-get",
+           "-o", "DPkg::Lock::Timeout=60", "-o", "Acquire::Retries=2",
+           "-o", "Acquire::http::Timeout=30", "-o", "Acquire::https::Timeout=30"]
+    s.sudo([*apt, "update", "--error-on=any"])
+    command = [*apt, "install", "-y", "--no-install-recommends", "--no-upgrade",
+               "--no-remove", *missing]
+    plan = s.sudo([*command, "--simulate"], capture=True)
+    if any(line.startswith("Remv ") or re.match(r"^Inst \S+ \[", line)
+           for line in plan.stdout.splitlines()):
+        raise RuntimeError("Missing packages require upgrades/removals; reconcile packages first.")
+    s.sudo(command)
+
+
+def run(ctx, args):
+    if not Path("/etc/debian_version").is_file():
+        raise RuntimeError("Debian required.")
+    packages = (*BASE_PACKAGES, *ADMIN_PACKAGES)
+    if Path("/usr/bin/pveversion").exists():
+        packages = tuple(package for package in packages if package != "ufw")
+    _install_missing(ctx.sys, packages)
+    if not ctx.sys.start_and_enable("rsyslog"):
+        raise RuntimeError("rsyslog failed to start.")

actions/config/routing.py

@@ -0,0 +1,21 @@
+# actions/config/routing.py
+"""Port of config/routing — idempotent node routing (ip_forward, fwmark rule, table 100)."""
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Idempotent node-level routing rules and routes.")
+
+def run(ctx, args):
+    log, s = ctx.log, ctx.sys
+    log.info("Applying persistent node-level routing configuration...")
+    s.sudo(["sysctl", "-w", "net.ipv4.ip_forward=1"])
+    if s.ok(["bash", "-c", "sudo ip rule show | grep -q 'fwmark 0x1 lookup 100'"]):
+        log.info("IP rule for mark 0x1 already exists.")
+    else:
+        s.run(["bash", "-c", "sudo ip rule add fwmark 0x1 lookup 100 priority 100 || true"])
+        log.info("IP rule added for mark 0x1.")
+    if s.ok(["bash", "-c", "sudo ip route show table 100 2>/dev/null | grep -q 'local default dev lo'"]):
+        log.info("Local route in table 100 already exists.")
+    else:
+        s.run(["bash", "-c", "sudo ip route add local 0.0.0.0/0 dev lo table 100 || true"])
+        log.info("Local route added to table 100.")
+    log.success("Routing configuration applied.")

actions/config/systemd.py

@@ -0,0 +1,15 @@
+# actions/config/systemd.py
+"""Port of config/systemd — deploy + enable units from configs/systemd."""
+import os
+from engine.descriptor import Meta, Flag
+
+METADATA = Meta(summary="Deploy + enable systemd units from configs/systemd.",
+                args=[Flag("--dry-run", "Render only; do not write/enable.")])
+
+def run(ctx, args):
+    cfg = os.path.join(ctx.paths.configs, "systemd")
+    if not os.path.isdir(cfg):
+        ctx.log.error(f"Config directory not found: {cfg}"); raise SystemExit(1)
+    ctx.log.info("Deploying systemd units...")
+    ctx.systemd.deploy_units("systemd", ctx.vars(), dry_run=args.dry_run)
+    ctx.log.success("Configured systemd.")

actions/config/timezone.py

@@ -0,0 +1,33 @@
+"""Apply the optional node timezone before installing scheduled jobs."""
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from engine.descriptor import Meta, Flag
+
+METADATA = Meta(summary="Apply configs/timezone and refresh cron when the timezone changes.",
+                args=[Flag("--dry-run", "Validate and preview without changing the host.")])
+
+
+def run(ctx, args):
+    source = Path(ctx.paths.configs) / "timezone"
+    if not source.is_file():
+        ctx.log.info("No configs/timezone declaration; preserving host timezone.")
+        return
+    zone = source.read_text().strip()
+    try:
+        ZoneInfo(zone)
+    except (ValueError, ZoneInfoNotFoundError):
+        ctx.log.error("configs/timezone must name an installed IANA timezone.")
+        raise SystemExit(1) from None
+    current = ctx.sys.run(["timedatectl", "show", "--property=Timezone", "--value"], capture=True).stdout.strip()
+    if current == zone:
+        ctx.log.info(f"Timezone already set to {zone}.")
+        return
+    if args.dry_run:
+        ctx.log.info(f"[DRY-RUN] would change timezone from {current} to {zone} and refresh active cron.")
+        return
+    ctx.sys.sudo(["timedatectl", "set-timezone", zone])
+    if ctx.sys.service_is_active("cron") and not ctx.sys.restart("cron"):
+        ctx.log.error("Timezone changed, but cron did not become active after restart.")
+        raise SystemExit(1)
+    ctx.log.success(f"Timezone set to {zone}.")

actions/config/ufw-docker.py

@@ -0,0 +1,65 @@
+"""Install the pinned ufw-docker integration on Docker hosts."""
+import hashlib
+import os
+from pathlib import Path
+import stat
+import urllib.request
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Install the pinned Docker integration for UFW.")
+UFW_DOCKER_REVISION = "020a8699f95592561f254d8d4ad1bb40d401dfc7"
+UFW_DOCKER_SHA256 = "643e56b080567c567b4aa28650196849b2a2da5dd0473fd3e5216b0886035ab0"
+UFW_DOCKER_URL = (
+    "https://raw.githubusercontent.com/chaifeng/ufw-docker/"
+    + UFW_DOCKER_REVISION + "/ufw-docker"
+)
+UFW_DOCKER_PATH = Path("/usr/local/bin/ufw-docker")
+def _check_helper_path(path):
+    for parent in reversed(path.parents):
+        info = parent.lstat()
+        if (not stat.S_ISDIR(info.st_mode) or info.st_uid != 0 or
+                info.st_mode & 0o022):
+            raise RuntimeError(f"Unsafe ufw-docker ancestor: {parent}")
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return False
+    if (not stat.S_ISREG(info.st_mode) or info.st_uid != 0 or info.st_gid != 0 or
+            info.st_mode & 0o022 or info.st_nlink != 1):
+        raise RuntimeError(f"Unsafe ufw-docker target: {path}")
+    return True
+
+
+def _install_helper(ctx):
+    path = UFW_DOCKER_PATH
+    exists = _check_helper_path(path)
+    payload = path.read_bytes() if exists else None
+    if payload is None or hashlib.sha256(payload).hexdigest() != UFW_DOCKER_SHA256:
+        ctx.log.info(f"Downloading pinned ufw-docker helper to {path}...")
+        # The immutable HTTPS URL is authenticated by the digest below.
+        with urllib.request.urlopen(UFW_DOCKER_URL, timeout=30) as response:  # noqa: S310
+            payload = response.read(1024 * 1024 + 1)
+        if len(payload) > 1024 * 1024 or hashlib.sha256(payload).hexdigest() != UFW_DOCKER_SHA256:
+            raise RuntimeError("ufw-docker checksum mismatch; refusing installation.")
+        _check_helper_path(path)
+        ctx.host.write_file(str(path), payload.decode("utf-8"), mode="0755",
+                            backup=False, sudo=True)
+    elif stat.S_IMODE(path.stat().st_mode) != 0o755:
+        ctx.host.write_file(str(path), payload.decode("utf-8"), mode="0755",
+                            backup=False, sudo=True)
+    if (not _check_helper_path(path) or
+            hashlib.sha256(path.read_bytes()).hexdigest() != UFW_DOCKER_SHA256 or
+            stat.S_IMODE(path.stat().st_mode) != 0o755):
+        raise RuntimeError("ufw-docker verification failed; refusing execution.")
+    ctx.log.info("Ensuring ufw-docker routing rules are installed in UFW...")
+    ctx.sys.sudo([str(path), "install"])
+
+
+def run(ctx, args):
+    _check_helper_path(UFW_DOCKER_PATH)
+    if os.path.exists("/usr/bin/pveversion"):
+        raise RuntimeError("Use the Proxmox firewall on a PVE host.")
+    for binary in ("ufw", "docker"):
+        if not ctx.sys.ok(["which", binary]):
+            raise RuntimeError(f"Install {binary} before configuring ufw-docker.")
+    _install_helper(ctx)

actions/config/ufw.py

@@ -0,0 +1,24 @@
+# actions/config/ufw.py
+"""Port of config/ufw — apply docker + host ufw rules from configs/ufw."""
+import os
+from engine.descriptor import Meta, Flag
+
+METADATA = Meta(summary="Render + apply this node's UFW rules (configs/ufw).",
+                args=[Flag("--dry-run", "Preview; do not apply.")])
+
+def run(ctx, args):
+    cfg = os.path.join(ctx.paths.configs, "ufw")
+    if not os.path.isdir(cfg):
+        ctx.log.error(f"Config directory not found: {cfg}"); raise SystemExit(1)
+    docker_dir = os.path.join(cfg, "docker")
+    host_dir = os.path.join(cfg, "host")
+    ctx.log.info("Configuring UFW rules...")
+    has_docker = os.path.isdir(docker_dir)
+    has_host = os.path.isdir(host_dir)
+    if not has_docker:
+        ctx.log.warn(f"Docker rules dir not found at {docker_dir}. Skipping ufw-docker rules.")
+    if not has_host:
+        ctx.log.warn(f"Host rules dir not found at {host_dir}. Skipping host rules.")
+    if has_docker or has_host:
+        ctx.ufw.apply(docker_dir if has_docker else None, host_dir if has_host else None, dry_run=args.dry_run)
+    ctx.log.success("Configured ufw.")