@atomic-chat/core 0.5.1 → 0.13.2

package/dist/host/recipes/install-container-runtime.js

@@ -0,0 +1,796 @@
+/**
+ * The `linux.install-container-runtime` recipe (design D2/D3): Docker Engine and the NVIDIA
+ * Container Toolkit from the vendors' own apt or dnf repositories, the NVIDIA runtime registered
+ * with Docker, the NVIDIA CDI spec generated (task 2.23, F-5: Docker 28.2+ passes `--gpus` through
+ * it), `docker.service` enabled, and the user added to the `docker` group. This is the one
+ * piece of code in the product that runs as root on a user's machine, so its shape is deliberate:
+ *
+ * - **Data in, argv out.** `buildInstallContainerRuntimeSteps` is pure. Every command is an argv
+ *   array taken from `INSTALL_CONTAINER_RUNTIME_RECIPE` with validated values substituted into whole
+ *   arguments; nothing is ever handed to a shell.
+ * - **The recipe is its own digest.** Every command, path, URL, key fingerprint and file body lives
+ *   in the frozen `INSTALL_CONTAINER_RUNTIME_RECIPE`, and `INSTALL_CONTAINER_RUNTIME_RECIPE_DIGEST`
+ *   is its canonical hash. A change to any of them changes the digest, which a test pins.
+ * - **Only what is missing.** Parameters name components, never packages or commands. The executor
+ *   re-checks each one on the machine and skips what is already there, so a replay is a no-op.
+ * - **Nothing removed, nothing upgraded.** No step removes a package or a file, or upgrades the
+ *   system. `assertPermittedCommand` is an allowlist the executor applies to every argv before it
+ *   runs, and a test scans every step this module can build for the forbidden words. `apt-get
+ *   install` always carries `--no-remove`: without it apt's resolver may remove a conflicting
+ *   package to satisfy the install. `dnf install` has two ways to take a package away:
+ *   `--allowerasing` (forbidden) and RPM `Obsoletes`, which a plain install always honours — no
+ *   dnf option turns that off (libdnf and libdnf5 set `SOLVER_FLAG_YUM_OBSOLETES` unconditionally;
+ *   `obsoletes=False` only changes candidate selection). containerd.io obsoletes `containerd` and
+ *   `runc`, older docker-ce releases obsolete `docker-ce-selinux`, and nvidia-container-toolkit
+ *   obsoletes old `nvidia-container-runtime` and `nvidia-container-runtime-hook`. So two checks run
+ *   before any dnf install, and either refuses it: a static per-component conflict list, and a live
+ *   one — `dnf repoquery --obsoletes <package>` for each package still to install, then
+ *   `rpm --query <name>` for each name it obsoletes. Both ask rpm by package name only, because
+ *   libsolv matches Obsoletes against names, not against what a package provides. An installed
+ *   package of such a name is refused, never replaced. Only the packages the recipe names are
+ *   queried, not the dependencies the install pulls in (nvidia-container-toolkit-base, which the
+ *   toolkit requires, repeats the toolkit's Obsoletes).
+ * - **A package query fails closed.** A package counts as absent only when `rpm` or `dpkg-query`
+ *   says so in its own words; a database it cannot open, a lock or any other reply fails the step,
+ *   so a broken query can never make a conflict look absent.
+ *
+ * What `recipe_digest` covers: everything in `INSTALL_CONTAINER_RUNTIME_RECIPE` — argv templates,
+ * paths, URLs, key fingerprints, file bodies, modes, the environment, the conflict lists. What it
+ * does not cover: the code in this file and in `executor.ts` (how steps are ordered and named,
+ * `PERMITTED`, the check-then-act logic, the restart rule). A change there is a code change like
+ * any other; it does not by itself invalidate plans users have already approved.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import { canonicalDigest } from '../../runtime/environment/index.js';
+/** A value that is the object's own property — never one inherited from `Object.prototype`. */
+function own(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function invalid(message) {
+    throw new AtomicCoreError('MANAGED_HOST_STEP_INVALID', message);
+}
+export const INSTALL_CONTAINER_RUNTIME_RECIPE_ID = 'linux.install-container-runtime';
+/**
+ * What a plan can ask the recipe for, in the order the recipe applies them. `docker-restart` is not
+ * a step of its own: it is the user's consent (design D5) to restart a Docker that was already
+ * running when `nvidia-runtime` changes its configuration. `nvidia-cdi` (task 2.23, F-5) generates
+ * the CDI spec after the runtime is configured, and needs no restart.
+ */
+export const CONTAINER_RUNTIME_COMPONENTS = [
+    'docker-engine',
+    'nvidia-container-toolkit',
+    'nvidia-runtime',
+    'nvidia-cdi',
+    'docker-restart',
+    'docker-service',
+    'docker-group',
+];
+/** Deep-freezes the recipe so the object the digest describes is the object that runs. */
+function frozen(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/**
+ * Key fingerprints, pinned. Docker's rpm key is the one Docker's Fedora install guide tells the
+ * user to verify. Docker's deb key and NVIDIA's key are not printed in the vendors' current guides;
+ * these are the primary-key fingerprints of the keys the guides' URLs served on 2026-09-28, as
+ * `gpg --show-keys` reports them (`test/fixtures/host-keys/`). Docker's deb key is also the value
+ * Docker's Debian/Ubuntu guides printed for years ("9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88").
+ */
+const DOCKER_DEB_KEY = '9DC858229FC7DD38854AE2D88D81803C0EBFCD88';
+const DOCKER_RPM_KEY = '060A61C51B558A7F742B77AAC52FEB6B621E9F35';
+const NVIDIA_KEY = 'C95B321B61E88C1809C4F759DDCAE044F796ECB0';
+const DOCKER_ACTIVE = ['systemctl', 'is-active', '--quiet', 'docker'];
+/**
+ * Clears a failed or `start-limit-hit` docker.service and docker.socket before a start or restart
+ * (task 2.23, F-6): after a failed start systemd refuses further starts for a while, so a retry of
+ * the same step would fail on the leftover state rather than on the cause. Its exit status is ignored:
+ * on a unit that is not failed it does nothing.
+ */
+const DOCKER_RESET_FAILED = ['systemctl', 'reset-failed', 'docker.service', 'docker.socket'];
+/** Where the spec goes (ruling R-core-8): the path `nvidia-cdi-refresh` regenerates. */
+const CDI_SPEC = '/var/run/cdi/nvidia.yaml';
+/** The toolkit's unit (1.18+) that regenerates the spec after a driver update and on boot. */
+const CDI_REFRESH_UNIT = 'nvidia-cdi-refresh.path';
+/**
+ * Why docker.service did not start: `systemctl` itself only says "see journalctl". The last 40
+ * lines, message text only; run solely after a start or restart failed, never as a step of its own.
+ */
+const DOCKER_JOURNAL = ['journalctl', '-u', 'docker.service', '-n', '40', '--no-pager', '-o', 'cat'];
+/**
+ * The whole recipe as data. `{{name}}` marks a whole-argument or in-file substitution of a
+ * validated parameter; there is no other kind of template.
+ */
+export const INSTALL_CONTAINER_RUNTIME_RECIPE = frozen({
+    recipe_id: INSTALL_CONTAINER_RUNTIME_RECIPE_ID,
+    revision: 2,
+    /**
+     * The environment every command runs with, instead of the caller's. `sudo` and `pkexec` already
+     * scrub most of it, but a variable like `APT_CONFIG` or `LD_PRELOAD` must never reach a root
+     * package manager, whoever started us.
+     */
+    environment: {
+        PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
+        LANG: 'C',
+        LC_ALL: 'C',
+        DEBIAN_FRONTEND: 'noninteractive',
+    },
+    packages: {
+        'docker-engine': ['docker-ce', 'docker-ce-cli', 'containerd.io'],
+        'nvidia-container-toolkit': ['nvidia-container-toolkit'],
+    },
+    apt: {
+        /** Release → suite. Only these releases are buildable; `VERSION_CODENAME` is never trusted. */
+        suites: {
+            ubuntu: { '22.04': 'jammy', '24.04': 'noble', '26.04': 'resolute' },
+            debian: { '12': 'bookworm', '13': 'trixie' },
+        },
+        architectures: { x86_64: 'amd64', aarch64: 'arm64' },
+        repositories: {
+            'docker-engine': {
+                key: {
+                    url: 'https://download.docker.com/linux/{{distro}}/gpg',
+                    path: '/etc/apt/keyrings/docker.asc',
+                    encoding: 'armored',
+                    fingerprints: [DOCKER_DEB_KEY],
+                },
+                source: {
+                    path: '/etc/apt/sources.list.d/docker.list',
+                    content: 'deb [arch={{deb_arch}} signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/{{distro}} {{suite}} stable\n',
+                },
+            },
+            'nvidia-container-toolkit': {
+                key: {
+                    url: 'https://nvidia.github.io/libnvidia-container/gpgkey',
+                    path: '/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg',
+                    encoding: 'binary',
+                    fingerprints: [NVIDIA_KEY],
+                },
+                source: {
+                    path: '/etc/apt/sources.list.d/nvidia-container-toolkit.list',
+                    content: 'deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/$(ARCH) /\n',
+                },
+            },
+        },
+        /** Refresh one source list only: no other repository is fetched, no list is cleaned up. */
+        refresh: [
+            'apt-get',
+            'update',
+            '-o',
+            'Dir::Etc::sourcelist={{source}}',
+            '-o',
+            'Dir::Etc::sourceparts=-',
+            '-o',
+            'APT::Get::List-Cleanup=0',
+            '-o',
+            'DPkg::Lock::Timeout=300',
+        ],
+        installed: ['dpkg-query', '--show', '--showformat=${Status}', '{{package}}'],
+        /**
+         * Missing packages are appended. `--no-remove` makes apt fail rather than remove a package its
+         * resolver finds in the way; `confold` keeps the user's config on a dependency's upgrade; the
+         * lock timeout waits out unattended-upgrades instead of failing on dpkg's lock.
+         */
+        install: [
+            'apt-get',
+            'install',
+            '-y',
+            '--no-install-recommends',
+            '--no-remove',
+            '-o',
+            'Dpkg::Options::=--force-confdef',
+            '-o',
+            'Dpkg::Options::=--force-confold',
+            '-o',
+            'DPkg::Lock::Timeout=300',
+        ],
+        /**
+         * Installed packages that installing a component would have removed or replaced, per component.
+         * Docker's guide has these removed first; we never remove anything, so we refuse instead. With
+         * `--no-remove`, apt fails rather than removing; the check gives the clearer answer first.
+         */
+        conflicts: {
+            'docker-engine': ['docker.io', 'podman-docker', 'containerd', 'runc'],
+            'nvidia-container-toolkit': [],
+        },
+    },
+    dnf: {
+        /** Fedora's `VERSION_ID` is a plain release number; the descriptor decides which ones qualify. */
+        versions: { fedora: '^[1-9][0-9]$' },
+        repositories: {
+            'docker-engine': {
+                key: {
+                    url: 'https://download.docker.com/linux/fedora/gpg',
+                    path: '/etc/pki/rpm-gpg/RPM-GPG-KEY-docker-ce',
+                    encoding: 'armored',
+                    fingerprints: [DOCKER_RPM_KEY],
+                },
+                source: {
+                    path: '/etc/yum.repos.d/docker-ce.repo',
+                    // Docker's own `docker-ce.repo`, stable channel only, with the key we pinned instead of
+                    // a URL dnf would import from without asking anyone.
+                    content: [
+                        '[docker-ce-stable]',
+                        'name=Docker CE Stable - $basearch',
+                        'baseurl=https://download.docker.com/linux/fedora/$releasever/$basearch/stable',
+                        'enabled=1',
+                        'gpgcheck=1',
+                        'gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-docker-ce',
+                        '',
+                    ].join('\n'),
+                },
+            },
+            'nvidia-container-toolkit': {
+                key: {
+                    url: 'https://nvidia.github.io/libnvidia-container/gpgkey',
+                    path: '/etc/pki/rpm-gpg/RPM-GPG-KEY-nvidia-container-toolkit',
+                    encoding: 'armored',
+                    fingerprints: [NVIDIA_KEY],
+                },
+                source: {
+                    path: '/etc/yum.repos.d/nvidia-container-toolkit.repo',
+                    // NVIDIA's `nvidia-container-toolkit.repo`, stable channel only, same substitution.
+                    content: [
+                        '[nvidia-container-toolkit]',
+                        'name=nvidia-container-toolkit',
+                        'baseurl=https://nvidia.github.io/libnvidia-container/stable/rpm/$basearch',
+                        'repo_gpgcheck=1',
+                        'gpgcheck=0',
+                        'enabled=1',
+                        'gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-nvidia-container-toolkit',
+                        '',
+                    ].join('\n'),
+                },
+            },
+        },
+        /**
+         * Whether a package of exactly this name is installed: its name once per installed version, or
+         * exit 1 and "package <name> is not installed" (no `--quiet`, which would hide that answer). The
+         * `\\n` is the two characters rpm's query format expands itself, as a shell would pass `'%{NAME}\\n'`.
+         */
+        installed: ['rpm', '--query', '--queryformat=%{NAME}\\n', '{{package}}'],
+        /** No option here stops RPM `Obsoletes`; the two checks above the install do (see header). */
+        install: ['dnf', 'install', '-y', '--setopt=install_weak_deps=False'],
+        /**
+         * What a package from the configured repos `Obsoletes`, one per line. It installs and removes
+         * nothing, but it is not free of effects: it refreshes dnf's metadata cache, and `-y` accepts the
+         * import of the signing key of every enabled repository that has `repo_gpgcheck` on — the same
+         * keys, and the same prompt, the install itself would answer. `skip_if_unavailable=False`: a
+         * repository that cannot be read fails the query instead of being skipped into an empty answer.
+         */
+        obsoletes: [
+            'dnf',
+            'repoquery',
+            '--quiet',
+            '-y',
+            '--setopt=skip_if_unavailable=False',
+            '--obsoletes',
+            '{{package}}',
+        ],
+        /**
+         * Per component: Docker's Fedora guide has the first twelve removed first; the rest are what the
+         * component's packages `Obsolete` (containerd.io: containerd, runc; older docker-ce releases:
+         * docker-ce-selinux; nvidia-container-toolkit: nvidia-container-runtime ≤ 3.5.0-1,
+         * nvidia-container-runtime-hook ≤ 1.4.0-2). The live check covers anything else they obsolete.
+         */
+        conflicts: {
+            'docker-engine': [
+                'moby-engine',
+                'docker',
+                'docker-client',
+                'docker-client-latest',
+                'docker-common',
+                'docker-latest',
+                'docker-latest-logrotate',
+                'docker-logrotate',
+                'docker-selinux',
+                'docker-engine-selinux',
+                'docker-engine',
+                'podman-docker',
+                'containerd',
+                'runc',
+                'docker-ce-selinux',
+            ],
+            'nvidia-container-toolkit': ['nvidia-container-runtime', 'nvidia-container-runtime-hook'],
+        },
+    },
+    file_mode: 0o644,
+    runtime: {
+        daemon_json: '/etc/docker/daemon.json',
+        configure: ['nvidia-ctk', 'runtime', 'configure', '--runtime=docker'],
+        docker_active: DOCKER_ACTIVE,
+        /** Which runtimes the running daemon actually loaded, as opposed to what daemon.json says. */
+        loaded: ['docker', 'info', '--format', '{{json .Runtimes}}'],
+        restart: ['systemctl', 'restart', 'docker'],
+        reset_failed: DOCKER_RESET_FAILED,
+        journal: DOCKER_JOURNAL,
+    },
+    /**
+     * The NVIDIA CDI spec (task 2.23, F-5; ruling R-core-8): `nvidia-ctk cdi list` says whether a
+     * `nvidia.com/gpu` device is already defined — the same check the core's probe makes — and only
+     * when none is does `generate` write the spec, to the fixed path, never another. Where the toolkit
+     * ships `nvidia-cdi-refresh.path` (NVIDIA Container Toolkit 1.18+), it is enabled so the spec is
+     * rewritten after a driver update or a reboot (`/var/run` is a tmpfs); where it does not, nothing
+     * fails, and the next probe after a reboot plans the spec again.
+     */
+    cdi: {
+        spec: CDI_SPEC,
+        list: ['nvidia-ctk', 'cdi', 'list'],
+        generate: ['nvidia-ctk', 'cdi', 'generate', `--output=${CDI_SPEC}`],
+        /**
+         * The core's probe runs `nvidia-ctk cdi list` as the user, so the spec must be world-readable.
+         * Whether `generate` leaves it `0644` differs across toolkit releases (the CDI library writes a
+         * `0600` temporary file and renames it), so the step reads the mode and fixes it only when the
+         * file is not readable by others (task 2.23, review round 1).
+         */
+        mode: ['stat', '--format=%a', CDI_SPEC],
+        make_readable: ['chmod', '0644', CDI_SPEC],
+        refresh_unit: CDI_REFRESH_UNIT,
+        refresh_present: ['systemctl', 'list-unit-files', '--no-legend', CDI_REFRESH_UNIT],
+        refresh_enabled: ['systemctl', 'is-enabled', CDI_REFRESH_UNIT],
+        refresh_enable: ['systemctl', 'enable', '--now', CDI_REFRESH_UNIT],
+    },
+    service: {
+        enabled: ['systemctl', 'is-enabled', 'docker'],
+        active: DOCKER_ACTIVE,
+        reset_failed: DOCKER_RESET_FAILED,
+        enable: ['systemctl', 'enable', '--now', 'docker'],
+        journal: DOCKER_JOURNAL,
+    },
+    group: {
+        uid: ['id', '-u', '{{user}}'],
+        groups: ['id', '-nG', '{{user}}'],
+        add: ['usermod', '-aG', 'docker', '{{user}}'],
+    },
+});
+export const INSTALL_CONTAINER_RUNTIME_RECIPE_DIGEST = canonicalDigest(INSTALL_CONTAINER_RUNTIME_RECIPE);
+// ---------------------------------------------------------------------------------------------
+// Parameters
+// ---------------------------------------------------------------------------------------------
+/** POSIX portable user name; a leading `-` would be read as an option. */
+const USER_NAME = /^[A-Za-z_][A-Za-z0-9._-]{0,31}$/;
+const PARAMETER_KEYS = ['user', 'arch', 'family', 'distro_id', 'version_id', 'components'];
+function familyOf(distro) {
+    if (own(INSTALL_CONTAINER_RUNTIME_RECIPE.apt.suites, distro) !== undefined)
+        return 'apt';
+    if (own(INSTALL_CONTAINER_RUNTIME_RECIPE.dnf.versions, distro) !== undefined)
+        return 'dnf';
+    return null;
+}
+/** The apt suite for a release, from own properties only: `constructor`/`name` is not a release. */
+function aptSuite(distro, version) {
+    const releases = own(INSTALL_CONTAINER_RUNTIME_RECIPE.apt.suites, distro);
+    return releases === undefined ? undefined : own(releases, version);
+}
+/**
+ * Checks untrusted parameters against what this recipe can build, and returns them normalised
+ * (components in recipe order). The descriptor's distribution list is the core's business; this
+ * only refuses what the compiled recipe has no commands for.
+ */
+export function validateInstallContainerRuntimeParameters(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return { ok: false, problems: ['parameters must be an object'] };
+    const input = raw;
+    const problems = [];
+    for (const key of Object.keys(input))
+        if (!PARAMETER_KEYS.includes(key))
+            problems.push(`unknown parameter ${key}`);
+    const { user, arch, family, distro_id: distro, version_id: version, components } = input;
+    if (typeof user !== 'string' || !USER_NAME.test(user))
+        problems.push('user must be a POSIX user name');
+    if (arch !== 'x86_64' && arch !== 'aarch64')
+        problems.push('arch must be x86_64 or aarch64');
+    if (family !== 'apt' && family !== 'dnf')
+        problems.push('family must be apt or dnf');
+    if (typeof distro !== 'string' || typeof version !== 'string') {
+        problems.push('distro_id and version_id must be strings');
+    }
+    else {
+        const expected = familyOf(distro);
+        if (expected === null)
+            problems.push(`the recipe has no commands for distribution ${distro}`);
+        else if (expected !== family)
+            problems.push(`${distro} uses ${expected}, not ${String(family)}`);
+        else if (expected === 'apt' && aptSuite(distro, version) === undefined)
+            problems.push(`the recipe has no apt suite for ${distro} ${version}`);
+        else if (expected === 'dnf' &&
+            !new RegExp(own(INSTALL_CONTAINER_RUNTIME_RECIPE.dnf.versions, distro)).test(version))
+            problems.push(`${version} is not a ${distro} release number`);
+    }
+    let ordered = [];
+    if (!Array.isArray(components)) {
+        problems.push('components must be a list');
+    }
+    else {
+        for (const component of components)
+            if (!CONTAINER_RUNTIME_COMPONENTS.includes(component))
+                problems.push(`unknown component ${String(component)}`);
+        if (new Set(components).size !== components.length)
+            problems.push('a component is repeated');
+        if (components.length === 0)
+            problems.push('components is empty: nothing to do');
+        ordered = CONTAINER_RUNTIME_COMPONENTS.filter((component) => components.includes(component));
+    }
+    // Root needs no group (design D4); adding it would only ever be a mistake or an attack.
+    if (user === 'root' && ordered.includes('docker-group'))
+        problems.push('root is never added to the docker group');
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return {
+        ok: true,
+        parameters: {
+            user: user,
+            arch: arch,
+            family: family,
+            distro_id: distro,
+            version_id: version,
+            components: ordered,
+        },
+    };
+}
+function validated(parameters) {
+    const result = validateInstallContainerRuntimeParameters(parameters);
+    if (!result.ok)
+        invalid(`invalid recipe parameters: ${result.problems.join('; ')}`);
+    return result.parameters;
+}
+/** Canonical-JSON sha256 of the normalised parameters: what `parameters_digest` must equal. */
+export function installContainerRuntimeParametersDigest(parameters) {
+    return canonicalDigest(validated(parameters));
+}
+/**
+ * The parameters for an install plan from `assessLinux` (task 2.4), for the core to put behind a
+ * `pending_host_step` (task 2.6). Each system change maps to one component; anything the recipe
+ * cannot do, or a group line for an account other than the host's user, is refused.
+ */
+export function parametersFromPlan(plan, host) {
+    if (plan.recipe_id !== INSTALL_CONTAINER_RUNTIME_RECIPE_ID)
+        invalid(`the plan is for recipe ${plan.recipe_id}, not ${INSTALL_CONTAINER_RUNTIME_RECIPE_ID}`);
+    const wanted = new Set();
+    const { packages } = INSTALL_CONTAINER_RUNTIME_RECIPE;
+    for (const change of plan.system_changes) {
+        switch (change.code) {
+            case 'add-repository':
+                wanted.add(change.params?.['vendor'] === 'docker' ? 'docker-engine' : 'nvidia-container-toolkit');
+                break;
+            case 'install-packages':
+                for (const name of (change.params?.['packages'] ?? '').split(',').filter(Boolean)) {
+                    if (packages['docker-engine'].includes(name))
+                        wanted.add('docker-engine');
+                    else if (packages['nvidia-container-toolkit'].includes(name))
+                        wanted.add('nvidia-container-toolkit');
+                    else
+                        invalid(`the recipe does not install package ${name}`);
+                }
+                break;
+            case 'configure-nvidia-runtime':
+                wanted.add('nvidia-runtime');
+                break;
+            case 'generate-cdi-spec':
+                wanted.add('nvidia-cdi');
+                break;
+            case 'restart-docker':
+                wanted.add('docker-restart');
+                break;
+            case 'enable-docker-service':
+                wanted.add('docker-service');
+                break;
+            case 'add-user-to-docker-group':
+                if (change.params?.['user'] !== host.user)
+                    invalid(`the plan adds ${String(change.params?.['user'])} to the docker group, not ${host.user}`);
+                wanted.add('docker-group');
+                break;
+        }
+    }
+    return validated({ ...host, components: [...wanted] });
+}
+/**
+ * This recipe as the core's Linux provisioner consumes it (task 2.6): it builds the parameters of a
+ * pending host step from the plan and their digest, with the same functions the executor checks
+ * them against. The provisioner cannot import this module itself (it imports the environment
+ * module), so the core passes it in.
+ */
+export const INSTALL_CONTAINER_RUNTIME_BINDING = {
+    recipe_id: INSTALL_CONTAINER_RUNTIME_RECIPE_ID,
+    recipe_digest: INSTALL_CONTAINER_RUNTIME_RECIPE_DIGEST,
+    parameters: (plan, host) => parametersFromPlan(plan, host),
+    parametersDigest: (parameters) => installContainerRuntimeParametersDigest(parameters),
+};
+function fill(template, values) {
+    return template.replace(/\{\{([a-z_]+)\}\}/g, (_match, name) => {
+        const value = own(values, name);
+        if (value === undefined)
+            invalid(`no value for {{${name}}}`);
+        return value;
+    });
+}
+const argv = (template, values) => template.map((part) => fill(part, values));
+const VENDOR_IDS = {
+    'docker-engine': 'docker',
+    'nvidia-container-toolkit': 'nvidia',
+};
+/** The ordered steps for these parameters. Throws on parameters that do not validate. */
+export function buildInstallContainerRuntimeSteps(input) {
+    const parameters = validated(input);
+    const recipe = INSTALL_CONTAINER_RUNTIME_RECIPE;
+    const wants = (component) => parameters.components.includes(component);
+    const family = recipe[parameters.family];
+    const values = {
+        distro: parameters.distro_id,
+        user: parameters.user,
+        deb_arch: recipe.apt.architectures[parameters.arch],
+        suite: aptSuite(parameters.distro_id, parameters.version_id) ?? '',
+    };
+    const steps = [];
+    const vendors = ['docker-engine', 'nvidia-container-toolkit'].filter(wants);
+    for (const vendor of vendors) {
+        const { key, source } = family.repositories[vendor];
+        steps.push({
+            id: `${VENDOR_IDS[vendor]}-key`,
+            kind: 'install-key',
+            url: fill(key.url, values),
+            path: key.path,
+            encoding: key.encoding,
+            fingerprints: [...key.fingerprints],
+            mode: recipe.file_mode,
+        });
+        steps.push({
+            id: `${VENDOR_IDS[vendor]}-source`,
+            kind: 'write-source',
+            path: source.path,
+            content: fill(source.content, values),
+            mode: recipe.file_mode,
+        });
+    }
+    if (vendors.length > 0) {
+        const packages = vendors.flatMap((vendor) => recipe.packages[vendor]);
+        const query = (name) => ({ package: name, argv: argv(family.installed, { package: name }) });
+        steps.push({
+            id: 'packages',
+            kind: 'install-packages',
+            packages,
+            queries: packages.map(query),
+            conflicts: vendors.flatMap((vendor) => family.conflicts[vendor].map((name) => ({ ...query(name), component: vendor }))),
+            refresh: parameters.family === 'apt'
+                ? vendors.map((vendor) => argv(recipe.apt.refresh, { source: recipe.apt.repositories[vendor].source.path }))
+                : [],
+            obsoletes: parameters.family === 'dnf'
+                ? {
+                    queries: packages.map((name) => ({
+                        package: name,
+                        argv: argv(recipe.dnf.obsoletes, { package: name }),
+                    })),
+                    // The presence query without its trailing `{{package}}`: the executor appends each name.
+                    installed: recipe.dnf.installed.slice(0, -1),
+                }
+                : null,
+            install: [...family.install],
+        });
+    }
+    if (wants('nvidia-runtime')) {
+        steps.push({
+            id: 'nvidia-runtime',
+            kind: 'configure-runtime',
+            daemon_json: recipe.runtime.daemon_json,
+            configure: [...recipe.runtime.configure],
+            docker_active: [...recipe.runtime.docker_active],
+            loaded: [...recipe.runtime.loaded],
+            restart: [...recipe.runtime.restart],
+            reset_failed: [...recipe.runtime.reset_failed],
+            journal: [...recipe.runtime.journal],
+            restart_approved: wants('docker-restart'),
+        });
+    }
+    if (wants('nvidia-cdi')) {
+        steps.push({
+            id: 'nvidia-cdi',
+            kind: 'generate-cdi',
+            spec: recipe.cdi.spec,
+            list: [...recipe.cdi.list],
+            generate: [...recipe.cdi.generate],
+            mode: [...recipe.cdi.mode],
+            make_readable: [...recipe.cdi.make_readable],
+            refresh_unit: recipe.cdi.refresh_unit,
+            refresh_present: [...recipe.cdi.refresh_present],
+            refresh_enabled: [...recipe.cdi.refresh_enabled],
+            refresh_enable: [...recipe.cdi.refresh_enable],
+        });
+    }
+    if (wants('docker-service')) {
+        steps.push({
+            id: 'docker-service',
+            kind: 'enable-service',
+            enabled: [...recipe.service.enabled],
+            active: [...recipe.service.active],
+            reset_failed: [...recipe.service.reset_failed],
+            enable: [...recipe.service.enable],
+            journal: [...recipe.service.journal],
+        });
+    }
+    if (wants('docker-group')) {
+        steps.push({
+            id: 'docker-group',
+            kind: 'add-to-docker-group',
+            user: parameters.user,
+            uid: argv(recipe.group.uid, values),
+            groups: argv(recipe.group.groups, values),
+            add: argv(recipe.group.add, values),
+        });
+    }
+    return steps;
+}
+/** Every argv a step can run, checks included — what the forbidden-word scan reads. */
+export function commandsOf(step) {
+    switch (step.kind) {
+        case 'install-key':
+        case 'write-source':
+            return [];
+        case 'install-packages':
+            return [
+                ...step.queries.map((query) => query.argv),
+                ...step.conflicts.map((conflict) => conflict.argv),
+                ...(step.obsoletes === null
+                    ? []
+                    : [
+                        ...step.obsoletes.queries.map((query) => query.argv),
+                        [...step.obsoletes.installed, 'obsoleted-name'],
+                    ]),
+                ...step.refresh,
+                [...step.install, ...step.packages],
+            ];
+        case 'configure-runtime':
+            return [step.configure, step.docker_active, step.loaded, step.reset_failed, step.restart, step.journal];
+        case 'generate-cdi':
+            return [
+                step.list,
+                step.generate,
+                step.mode,
+                step.make_readable,
+                step.refresh_present,
+                step.refresh_enabled,
+                step.refresh_enable,
+            ];
+        case 'enable-service':
+            return [step.enabled, step.active, step.reset_failed, step.enable, step.journal];
+        case 'add-to-docker-group':
+            return [step.uid, step.groups, step.add];
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// The allowlist every command passes before it runs
+// ---------------------------------------------------------------------------------------------
+/** Every package the recipe itself installs: the only ones `dnf repoquery` is asked about. */
+export const RECIPE_PACKAGES = new Set([
+    ...INSTALL_CONTAINER_RUNTIME_RECIPE.packages['docker-engine'],
+    ...INSTALL_CONTAINER_RUNTIME_RECIPE.packages['nvidia-container-toolkit'],
+]);
+const PACKAGE_NAME = /^[A-Za-z0-9_][A-Za-z0-9._+-]{0,127}$/;
+/**
+ * A package name — what an RPM `Obsoletes` names, as `dnf repoquery` prints it without its version
+ * constraint. Never an option, a path or any other kind of capability.
+ */
+export function isPackageName(value) {
+    return PACKAGE_NAME.test(value);
+}
+/** Words that remove or upgrade. None may appear in any argument of any command. */
+export const FORBIDDEN_WORDS = [
+    'rm',
+    'purge',
+    'remove',
+    'autoremove',
+    'erase',
+    'upgrade',
+    'dist-upgrade',
+    'full-upgrade',
+    'distro-sync',
+    'reinstall',
+    'downgrade',
+    '-e',
+    '--erase',
+    '--allowerasing',
+    '--auto-remove',
+    '--autoremove',
+];
+const { runtime, cdi, service } = INSTALL_CONTAINER_RUNTIME_RECIPE;
+/**
+ * Programs the recipe only ever runs in fixed shapes, with every such shape, whole. Compared element
+ * by element (`sameArgv`), never as joined text: `['enable', '--now docker']` is not
+ * `['enable', '--now', 'docker']` (task 2.23, review round 1).
+ */
+const EXACT_COMMANDS = {
+    'docker': { shapes: [runtime.loaded], why: 'docker is only ever asked which runtimes it loaded' },
+    'journalctl': {
+        shapes: [DOCKER_JOURNAL],
+        why: 'journalctl only ever reads the last lines of docker.service',
+    },
+    'nvidia-ctk': {
+        shapes: [runtime.configure, cdi.list, cdi.generate],
+        why: 'nvidia-ctk only ever configures the docker runtime, lists CDI devices or writes the one CDI spec',
+    },
+    // systemctl only ever touches docker.service (and its socket) and the CDI refresh unit.
+    'systemctl': {
+        shapes: [
+            runtime.docker_active,
+            runtime.restart,
+            runtime.reset_failed,
+            service.enabled,
+            service.active,
+            service.enable,
+            service.reset_failed,
+            cdi.refresh_present,
+            cdi.refresh_enabled,
+            cdi.refresh_enable,
+        ],
+        why: 'systemctl is only ever run in the shapes this recipe builds',
+    },
+    'stat': { shapes: [cdi.mode], why: 'stat only ever reads the mode of the CDI spec' },
+    'chmod': { shapes: [cdi.make_readable], why: 'chmod only ever makes the CDI spec readable' },
+};
+/** The same argv: the same length, and every argument equal in its own position. */
+export function sameArgv(a, b) {
+    return a.length === b.length && a.every((argument, index) => argument === b[index]);
+}
+/** Program → the first argument it may be run with. Nothing else is ever run as root. */
+const PERMITTED = {
+    'apt-get': ['install', 'update'],
+    'dpkg-query': ['--show'],
+    'dnf': ['install', 'repoquery'],
+    'rpm': ['--query'],
+    'nvidia-ctk': ['runtime', 'cdi'],
+    'systemctl': ['is-active', 'is-enabled', 'enable', 'restart', 'reset-failed', 'list-unit-files'],
+    'id': ['-u', '-nG'],
+    'docker': ['info'],
+    'usermod': ['-aG'],
+    'journalctl': ['-u'],
+    'stat': ['--format=%a'],
+    'chmod': ['0644'],
+};
+/**
+ * Throws unless `argv` is one of the command shapes this recipe runs. The executor calls it on
+ * every command, so even a bug in step building cannot reach a shell, a removal or an upgrade.
+ */
+export function assertPermittedCommand(argv) {
+    const [program, first] = argv;
+    const refuse = (why) => {
+        throw new AtomicCoreError('MANAGED_HOST_STEP_INVALID', `refusing to run ${JSON.stringify(argv)}: ${why}`);
+    };
+    if (program === undefined)
+        refuse('empty command');
+    const allowed = own(PERMITTED, program);
+    if (allowed === undefined)
+        refuse(`${String(program)} is not a program this recipe runs`);
+    if (first === undefined || !allowed.includes(first))
+        refuse(`${String(first)} is not permitted here`);
+    for (const word of argv)
+        if (FORBIDDEN_WORDS.includes(word))
+            refuse(`${word} is forbidden`);
+    // An index refresh is only ever of one explicit source list, never of the whole system.
+    if (program === 'apt-get' && first === 'update' && !argv.includes('Dir::Etc::sourceparts=-'))
+        refuse('apt-get update must be restricted to one source list');
+    if (program === 'apt-get' && first === 'install' && !argv.includes('--no-remove'))
+        refuse('apt-get install must carry --no-remove, so the resolver can never remove a package');
+    // The queries (they install and remove nothing) are allowed in exactly the shapes the recipe
+    // builds, and nothing else.
+    if (program === 'dnf' && first === 'repoquery') {
+        const [, , ...rest] = argv;
+        const target = rest[4];
+        if (rest.length !== 5 ||
+            !sameArgv(rest.slice(0, 4), ['--quiet', '-y', '--setopt=skip_if_unavailable=False', '--obsoletes']) ||
+            target === undefined ||
+            !RECIPE_PACKAGES.has(target))
+            refuse('dnf repoquery is only ever asked what one of the recipe’s packages obsoletes');
+    }
+    if (program === 'rpm' &&
+        !(argv.length === 4 && argv[2] === '--queryformat=%{NAME}\\n' && isPackageName(argv[3])))
+        refuse('rpm is only ever asked whether a package of one exact name is installed');
+    if (program === 'usermod' && (argv[2] !== 'docker' || argv.length !== 4 || argv[3] === 'root'))
+        refuse('usermod only ever adds a non-root user to docker');
+    const exact = own(EXACT_COMMANDS, program);
+    if (exact !== undefined && !exact.shapes.some((shape) => sameArgv(argv, shape)))
+        refuse(exact.why);
+}
+//# sourceMappingURL=install-container-runtime.js.map