Split host setup into explicit entity actions

actions/composition/run.py

@@ -1,8 +1,8 @@
-# actions/compose.py
+# actions/composition/run.py
 """Orchestrate docker compose across the node.
 
 Supports targeting all compositions in sequence (default: apex core first, services next;
-reverse on down) or targeting one with `apex compose -p apex restart traefik`.
+reverse on down) or targeting one with `apex composition/run -p apex restart traefik`.
 Wrapper options precede the action. Exports derived APEX_* vars and layers env files.
 """
 import os

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/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

@@ -1,5 +1,5 @@
-# actions/configure/cron.py
-"""Port of configure/cron — install crontab from configs/cron/crontab."""
+# actions/config/cron.py
+"""Port of config/cron — install crontab from configs/cron/crontab."""
 import os
 from engine.descriptor import Meta, Flag
 

actions/config/crowdsec.py

@@ -1,5 +1,5 @@
-# actions/configure/crowdsec.py
-"""Port of configure/crowdsec — install, deploy /etc/crowdsec, collections, bouncer."""
+# actions/config/crowdsec.py
+"""Port of config/crowdsec — install, deploy /etc/crowdsec, collections, bouncer."""
 import os
 from engine.descriptor import Meta, Flag
 

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/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

@@ -1,5 +1,5 @@
-# actions/configure/routing.py
-"""Port of configure/routing — idempotent node routing (ip_forward, fwmark rule, table 100)."""
+# 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.")

actions/config/systemd.py

@@ -1,5 +1,5 @@
-# actions/configure/systemd.py
-"""Port of configure/systemd — deploy + enable units from configs/systemd."""
+# actions/config/systemd.py
+"""Port of config/systemd — deploy + enable units from configs/systemd."""
 import os
 from engine.descriptor import Meta, Flag
 

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

@@ -1,5 +1,5 @@
-# actions/configure/ufw.py
-"""Port of configure/ufw — apply docker + host ufw rules from configs/ufw."""
+# actions/config/ufw.py
+"""Port of config/ufw — apply docker + host ufw rules from configs/ufw."""
 import os
 from engine.descriptor import Meta, Flag
 

actions/configure.py

@@ -1,34 +0,0 @@
-# actions/configure.py
-"""Run every configure/* action in a stable order."""
-import os
-from engine.descriptor import Meta, Flag, build_parser
-from engine import overlay
-
-METADATA = Meta(summary="Run every configure/* action in stable order.",
-                args=[Flag("--dry-run", "Pass --dry-run to sub-actions that support it.")])
-ORDER = ["configure/base", "configure/timezone", "configure/ufw", "configure/crowdsec",
-         "configure/cron", "configure/systemd", "configure/routing"]
-
-def run(ctx, args):
-    commons_actions = os.path.join(ctx.paths.commons, "actions")
-    prop = os.path.join(ctx.paths.proprietaries, "actions")
-    prop = prop if os.path.isdir(prop) else None
-    names = [i.name for i in overlay.discover(commons_actions, prop) if i.name.startswith("configure/")]
-    ordered = [n for n in ORDER if n in names] + sorted(n for n in names if n not in ORDER)
-    rc = 0
-    for name in ordered:
-        r = overlay.resolve(name, commons_actions, prop)
-        mod = overlay.load_module(r.path, "apex_umbrella_" + name.replace("/", "_"))
-        if getattr(mod, "DISABLED", None):
-            ctx.log.warn(f"Skipping disabled {name}"); continue
-        meta = mod.METADATA
-        has_dry = any(getattr(a, "name", None) == "--dry-run" for a in meta.args)
-        argv = ["--dry-run"] if (args.dry_run and has_dry) else []
-        sub_args = build_parser(meta, f"apex {name}").parse_args(argv)
-        ctx.log.info(f"=== {name} ===")
-        try:
-            mod.run(ctx, sub_args)
-        except SystemExit as e:
-            if e.code:
-                ctx.log.error(f"{name} exited {e.code}"); rc = rc or e.code
-    return rc

actions/configure/base.py

@@ -1,131 +0,0 @@
-# actions/configure/base.py
-"""Port of configure/base — base packages + ufw + ufw-docker helper."""
-import hashlib
-import os
-from pathlib import Path
-import re
-import stat
-import urllib.request
-from engine.descriptor import Meta
-
-METADATA = Meta(summary="Configure base system packages (curl, wget, git, rsyslog, ufw, ufw-docker).")
-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")
-BASE_PACKAGES = ("curl", "wget", "git", "rsyslog", "ufw")
-
-
-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 _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):
-    log, s = ctx.log, ctx.sys
-    log.info("Starting base system initialization...")
-    if not os.path.isfile("/etc/debian_version"):
-        log.error("Requires a Debian-based system (Debian/Ubuntu).")
-        raise SystemExit(1)
-    _check_helper_path(UFW_DOCKER_PATH)
-    _install_missing(s, BASE_PACKAGES)
-    s.ensure_running("rsyslog")
-
-    # Configure APT to discard downloaded archives
-    apt_clean_path = "/etc/apt/apt.conf.d/99-apex"
-    apt_clean_content = 'APT::Keep-Downloaded-Packages "0";\n'
-    if os.path.exists("/etc/apt/apt.conf.d/01clean"):
-        s.sudo(["rm", "-f", "/etc/apt/apt.conf.d/01clean"])
-    current_apt = None
-    if os.path.exists(apt_clean_path):
-        try:
-            with open(apt_clean_path, encoding="utf-8") as f:
-                current_apt = f.read()
-        except OSError:
-            current_apt = None
-    if current_apt != apt_clean_content:
-        log.info("Configuring APT to discard downloaded archives...")
-        s.sudo(["tee", apt_clean_path], input=apt_clean_content)
-
-    # Limit systemd-journald max disk usage
-    journal_d = "/etc/systemd/journald.conf.d"
-    journal_conf = os.path.join(journal_d, "99-apex.conf")
-    journal_content = "[Journal]\nSystemMaxUse=200M\n"
-    if os.path.exists(os.path.join(journal_d, "maxuse.conf")):
-        s.sudo(["rm", "-f", os.path.join(journal_d, "maxuse.conf")])
-    current_journal = None
-    if os.path.exists(journal_conf):
-        try:
-            with open(journal_conf, encoding="utf-8") as f:
-                current_journal = f.read()
-        except OSError:
-            current_journal = None
-    if current_journal != journal_content:
-        log.info("Configuring systemd-journald SystemMaxUse=200M...")
-        s.sudo(["mkdir", "-p", journal_d])
-        s.sudo(["tee", journal_conf], input=journal_content)
-        s.sudo(["systemctl", "restart", "systemd-journald"])
-
-    _install_helper(ctx)
-    log.success("Base system initialization completed.")

actions/repository/chown.py

@@ -0,0 +1,62 @@
+"""Give adam ownership of the active node's tracked checkout and Git metadata."""
+import inspect
+import json
+from pathlib import Path
+import re
+from engine.descriptor import Meta
+
+METADATA = Meta(summary="Set ownership of tracked files and Git metadata under /srv to adam.")
+
+
+def _repair(root, tracked, mounts, uid, gid):
+    import os
+    import stat
+
+    directories = {""}
+    for item in tracked:
+        directory = os.path.dirname(item)
+        while directory and directory not in directories:
+            directories.add(directory)
+            directory = os.path.dirname(directory)
+    metadata = os.path.join(root, ".git")
+
+    def fail(error):
+        raise error
+
+    for parent, dirs, files, fd in os.fwalk(root, onerror=fail, follow_symlinks=False):
+        os.fchown(fd, uid, gid)
+        for name in dirs.copy() + files:
+            path = os.path.join(parent, name)
+            relative = os.path.relpath(path, root)
+            if path in mounts or not (relative in tracked or relative in directories or
+                                      path == metadata or path.startswith(metadata + "/")):
+                if name in dirs:
+                    dirs.remove(name)
+                continue
+            info = os.stat(name, dir_fd=fd, follow_symlinks=False)
+            if stat.S_ISDIR(info.st_mode):
+                continue
+            if (stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode)) and info.st_nlink == 1:
+                os.chown(name, uid, gid, dir_fd=fd, follow_symlinks=False)
+
+
+def run(ctx, args):
+    root = Path(ctx.paths.repo_root)
+    if (root.parent != Path("/srv") or root != root.resolve(strict=True) or
+            not (root / "node.env").is_file() or (root / ".git").is_symlink() or
+            not (root / ".git").is_dir()):
+        raise RuntimeError("Expected the current node checkout directly under /srv.")
+    git = ["git", "-c", f"safe.directory={root}", "-c", f"safe.directory={root}/commons",
+               "-C", str(root)]
+    entries = ctx.sys.run([*git, "ls-files", "--cached", "--recurse-submodules", "-z"],
+                          capture=True).stdout
+    gitfiles = ctx.sys.run([*git, "submodule", "foreach", "--quiet", "--recursive",
+                            'printf "%s\\0" "$displaypath/.git"'], capture=True).stdout
+    mounts = [re.sub(r"\\([0-7]{3})", lambda match: chr(int(match[1], 8)), line.split()[4])
+              for line in Path("/proc/self/mountinfo").read_text().splitlines()]
+    script = (inspect.getsource(_repair) + "\nimport json, pwd, sys\n"
+              "root, entries, mounts = json.load(sys.stdin)\n"
+              "adam = pwd.getpwnam('adam')\n"
+              "_repair(root, set(entries), set(mounts), adam.pw_uid, adam.pw_gid)")
+    ctx.sys.sudo(["python3", "-I", "-c", script],
+                 input=json.dumps([str(root), (entries + gitfiles).split("\0"), mounts]))

actions/tier/backup.py

@@ -1,4 +1,4 @@
-# actions/backup/run.py
+# actions/tier/backup.py
 """Label-driven restic backup via resticontainer (git.ermnvldmr.com/deytenit/resticontainer).
 Runs the resticontainer core service one-shot: init-if-needed -> backup (discovers
 `restic.*`-labelled services, runs their pre-hooks/stops, snapshots the union of the

actions/tier/chown.py

@@ -1,5 +1,5 @@
-# actions/tiers/chown.py
-"""Port of tiers/chown — ownership: {tier}/{proj} -> uid:gid; {tier}/shared/{proj} ->
+# actions/tier/chown.py
+"""Port of tier/chown — ownership: {tier}/{proj} -> uid:gid; {tier}/shared/{proj} ->
 uid:shared_gid (+sticky); base/node-infra -> root:root. Reads APEX_UID/GID from each .env."""
 import os
 from engine.descriptor import Meta, Arg
@@ -31,7 +31,7 @@ def run(ctx, args):
 
     cp = s.run(["getent", "group", SHARED_GROUP], check=False, capture=True)
     if cp.returncode != 0:
-        log.error(f"Shared group '{SHARED_GROUP}' not found. Run tiers/useradd first."); raise SystemExit(1)
+        log.error(f"Shared group '{SHARED_GROUP}' not found. Run tier/useradd first."); raise SystemExit(1)
 
     log.info("Ensuring base structures owned by root...")
     for tp in tiers:
@@ -62,7 +62,7 @@ def run(ctx, args):
         gid = _env_val(env_path, "APEX_GID")
         sgid = _env_val(env_path, "APEX_SHARED_GID")
         if not (uid and gid and sgid):
-            log.warn(f"Incomplete APEX_UID/GID/SHARED_GID for {proj}. Run tiers/useradd first. Skipping.")
+            log.warn(f"Incomplete APEX_UID/GID/SHARED_GID for {proj}. Run tier/useradd first. Skipping.")
             continue
         log.info(f"Applying permissions for {proj} (UID={uid} GID={gid} SHARED_GID={sgid})")
         for tp in tiers:

actions/tier/link.py

@@ -1,5 +1,5 @@
-# actions/tiers/link.py
-"""Port of tiers/link — @tier symlink structure for the node + each composition project."""
+# actions/tier/link.py
+"""Port of tier/link — @tier symlink structure for the node + each composition project."""
 import os
 from engine.descriptor import Meta, Arg
 

actions/tier/useradd.py

@@ -1,5 +1,5 @@
-# actions/tiers/useradd.py
-"""Port of tiers/useradd — one noroot system user per composition project; inject the
+# actions/tier/useradd.py
+"""Port of tier/useradd — one noroot system user per composition project; inject the
 APEX_UID/APEX_GID/APEX_SHARED_GID block into each project .env."""
 import os, re
 from engine.descriptor import Meta
@@ -36,7 +36,7 @@ def run(ctx, args):
             continue
         # opt-out: a project marked .apex-root-owned runs as root and keeps its tier
         # data root-owned (e.g. seafile-mc, whose entrypoint refuses non-root-owned
-        # data). Skip the noroot user + .env UID injection; tiers/chown forces root.
+        # data). Skip the noroot user + .env UID injection; tier/chown forces root.
         if os.path.isfile(os.path.join(full, ".apex-root-owned")):
             log.info(f"{proj}: .apex-root-owned — runs as root; skipping noroot user")
             continue

actions/util/check-updates.py

@@ -1,4 +1,4 @@
-# actions/sync/packages.py
+# actions/util/check-updates.py
 """Check pending APT and running-image updates without pulling images."""
 import json
 import os

actions/util/extract-traefik-certs.py

@@ -1,5 +1,5 @@
-# actions/utils/extract-traefik-certs.py
-"""Port of utils/extract-traefik-certs — dump traefik v3 acme.json to pem via docker."""
+# actions/util/extract-traefik-certs.py
+"""Port of util/extract-traefik-certs — dump traefik v3 acme.json to pem via docker."""
 import os
 from engine.descriptor import Meta, Arg
 

actions/util/lint-docker-compose.py

@@ -1,4 +1,4 @@
-# actions/utils/lint-docker-compose.py
+# actions/util/lint-docker-compose.py
 """Run dclint through Docker and validate anchor IPs:
 every ipv4_address in compositions/*/docker-compose.yml must be unique and inside the
 node's /24."""
@@ -32,7 +32,7 @@ def run(ctx, args):
         if k in os.environ:
             env_args.extend(["-e", f"{k}={os.environ[k]}"])
     # "-e commons": never --fix inside the pinned submodule — a dirtied commons makes
-    # sync/repository abort the nightly capture-up.
+    # repository/sync abort the nightly capture-up.
     r = s.run(["docker", "run", "--rm", "--network", "host", *env_args, "-v", f"{repo}:/workdir", "-w", "/workdir", "node:lts-alpine",
                "npx", "--yes", "dclint", "-e", "@tier1", "-e", "@tier2", "-e", "@tier3", "-e", ".env",
                "-e", "commons", "--disable-rule", "no-build-and-image", "-r", "--fix", *targets], check=False)