@forgezero/agent 0.1.52 → 0.1.55

package/dist/software-helper.js

@@ -4,6 +4,7 @@ import {
   accessSync,
   chmodSync,
   copyFileSync,
+  existsSync,
   mkdtempSync,
   mkdirSync,
   readFileSync,
@@ -24,6 +25,7 @@ var OS_CATALOG = [
 ];
 var SOFTWARE_CATALOG = [
   { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "docker", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -33,6 +35,7 @@ var SOFTWARE_CATALOG = [
 ];
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "docker", version: "ubuntu-26.04" } },
   { requirement: { id: "nginx", version: "ubuntu-26.04" } },
   { requirement: { id: "arangodb", version: "3.11.14" } },
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
@@ -41,6 +44,15 @@ var UBUNTU_2604_X64 = [
   { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
 var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var DOCKER_DAEMON_PATH = "/etc/docker/daemon.json";
+var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
+  "data-root": "/var/lib/docker",
+  "storage-driver": "overlay2",
+  "live-restore": true,
+  "log-driver": "local",
+  "log-opts": { "max-size": "10m", "max-file": "3" }
+}, null, 2)}
+`;
 var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
 var runSoftwareCommand = async (argv, env = {}) => {
   let child;
@@ -83,12 +95,21 @@ async function executeSoftwareOperation(operation) {
   if (operation.kind === "check") {
     if (software === "bun")
       return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    if (software === "docker") {
+      const binary = await run(["/usr/bin/docker", "--version"]);
+      if (!successful(binary, /Docker version/))
+        return { ...binary, exitCode: 1 };
+      if (!existsSync(DOCKER_DAEMON_PATH) || readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
+        return { exitCode: 1, output: "Docker daemon policy is absent or differs from the reviewed ForgeZero policy" };
+      const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
+      return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
+    }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
       return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
     }
     if (software === "arangodb") {
-      const binary = await run(["/usr/bin/arangod", "--version"]);
+      const binary = await run(["/usr/sbin/arangod", "--version"]);
       if (!successful(binary, /3\.11\.14/))
         return { ...binary, exitCode: 1 };
       const [active, enabled] = await Promise.all([
@@ -115,11 +136,22 @@ async function executeSoftwareOperation(operation) {
       return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
     }
   }
-  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
-    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
-    if (installed.exitCode !== 0 || software !== "nginx")
+  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
+    const installed = await aptInstall(packageName);
+    if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
-    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+    if (software === "docker") {
+      mkdirSync("/etc/docker", { recursive: true, mode: 493 });
+      if (existsSync(DOCKER_DAEMON_PATH) && readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
+        return { exitCode: 2, output: "refusing to overwrite an existing Docker daemon configuration that differs from the reviewed ForgeZero policy" };
+      }
+      if (!existsSync(DOCKER_DAEMON_PATH))
+        writeFileSync(DOCKER_DAEMON_PATH, DOCKER_DAEMON_CONFIG, { mode: 420, flag: "wx" });
+      const enabled = await run(["/usr/bin/systemctl", "enable", "docker.service"]);
+      return enabled.exitCode === 0 ? run(["/usr/bin/systemctl", "restart", "docker.service"]) : enabled;
+    }
+    return run(["/usr/bin/systemctl", "enable", "--now", `${software}.service`]);
   }
   const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
   try {
@@ -204,7 +236,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };
@@ -677,13 +709,13 @@ function phasePipeline(definition, phase, profile, executeRelease = false) {
 }
 
 // src/software-helper.ts
-import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync3, unlinkSync as unlinkSync2 } from "node:fs";
+import { chmodSync as chmodSync2, existsSync as existsSync4, mkdirSync as mkdirSync4, unlinkSync as unlinkSync2 } from "node:fs";
 import { connect, createServer } from "node:net";
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 
 // src/service-supervisor.ts
 import { createHash as createHash2 } from "node:crypto";
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, realpathSync, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, realpathSync, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname, join as join2, resolve, sep } from "node:path";
 var SERVICE_STATE_DIRECTORY = "/var/lib/forgezero/services";
 var SERVICE_CONFIG_DIRECTORY = "/etc/forgezero/services";
@@ -700,8 +732,8 @@ var defaultHost = {
     renameSync2(next, path2);
   },
   read: (path2) => readFileSync2(path2, "utf8"),
-  exists: existsSync,
-  list: (path2) => existsSync(path2) ? readdirSync(path2) : [],
+  exists: existsSync2,
+  list: (path2) => existsSync2(path2) ? readdirSync(path2) : [],
   realpath: realpathSync,
   mkdir: (path2, mode) => mkdirSync2(path2, { recursive: true, mode }),
   remove: (path2) => rmSync2(path2, { force: true }),
@@ -898,6 +930,297 @@ async function activateSupervisedService(request, host = defaultHost) {
   return state;
 }
 
+// src/container-supervisor.ts
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync as realpathSync2, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname2, resolve as resolve2, sep as sep2 } from "node:path";
+var defaultHost2 = {
+  realpath: realpathSync2,
+  exists: existsSync3,
+  read: (path2) => readFileSync3(path2, "utf8"),
+  write(path2, content, mode) {
+    mkdirSync3(dirname2(path2), { recursive: true, mode: 493 });
+    const next = `${path2}.next`;
+    writeFileSync3(next, content, { mode });
+    renameSync3(next, path2);
+  },
+  remove: (path2) => rmSync3(path2, { force: true }),
+  list: (path2) => existsSync3(path2) ? readdirSync2(path2) : [],
+  mkdir: (path2, mode) => mkdirSync3(path2, { recursive: true, mode }),
+  async exec(argv2) {
+    const child = Bun.spawn([...argv2], { stdout: "pipe", stderr: "pipe", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", LANG: "C", LC_ALL: "C" } });
+    const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+    return { exitCode, output: `${stdout}${stderr}` };
+  },
+  async health(port, path2, timeoutMs, method, expectedStatus) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}${path2}`, { method, redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+      return expectedStatus.includes(response.status);
+    } catch {
+      return false;
+    }
+  },
+  sleep: (ms) => Bun.sleep(ms),
+  now: Date.now
+};
+var within2 = (root, path2) => path2 === root || path2.startsWith(`${root}${sep2}`);
+var idFor2 = (key) => createHash3("sha256").update(key).digest("hex").slice(0, 24);
+var statePath2 = (id) => `${SERVICE_STATE_DIRECTORY}/${id}.json`;
+var nameFor = (id, slot) => `forgezero-${id}-slot${slot}`;
+function validateRequest(request, host) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/.test(request.key) || !/^[a-f0-9]{40}$/.test(request.revision) || !/^[a-z][A-Za-z0-9-]{0,62}$/.test(request.component))
+    throw new Error("CONTAINER_IDENTITY_INVALID");
+  const root = host.realpath(resolve2(request.root));
+  const release = host.realpath(resolve2(request.release));
+  if (!within2(root, release))
+    throw new Error("CONTAINER_RELEASE_OUTSIDE_ROOT");
+  const application = request.application;
+  if (application.kind !== "application" || application.runtime.kind !== "container")
+    throw new Error("CONTAINER_RUNTIME_REQUIRED");
+  if (!application.resources.cpu || !application.resources.memory || !application.resources.pids)
+    throw new Error("CONTAINER_LIMITS_REQUIRED");
+  if (application.runtime.security.privileged !== false || application.runtime.security.noNewPrivileges !== true || !application.runtime.security.dropCapabilities.includes("ALL"))
+    throw new Error("CONTAINER_SECURITY_INVALID");
+  if (!application.network?.container || !["bridge", "host"].includes(application.network.container.mode))
+    throw new Error("CONTAINER_NETWORK_INVALID");
+  if (!application.network.ingress?.stablePort)
+    throw new Error("CONTAINER_STABLE_PORT_REQUIRED");
+  return { ...request, root, release };
+}
+async function checked2(host, argv2, code) {
+  const result = await host.exec(argv2);
+  if (result.exitCode !== 0)
+    throw new Error(`${code}: ${result.output.slice(0, 512)}`);
+  return result.output.trim();
+}
+async function buildContainerImage(requestValue, host = defaultHost2) {
+  const request = validateRequest(requestValue, host);
+  const runtime = request.application.runtime;
+  if (runtime.kind !== "container")
+    throw new Error("CONTAINER_RUNTIME_REQUIRED");
+  const source = runtime.image.source;
+  if (source.kind === "registry") {
+    if (!source.reference.includes("@sha256:"))
+      throw new Error("CONTAINER_IMAGE_DIGEST_REQUIRED");
+    await checked2(host, ["/usr/bin/docker", "pull", "--quiet", source.reference], "CONTAINER_PULL_FAILED");
+    const digest2 = await checked2(host, ["/usr/bin/docker", "image", "inspect", "--format={{.Id}}", source.reference], "CONTAINER_INSPECT_FAILED");
+    if (!/^sha256:[a-f0-9]{64}$/.test(digest2))
+      throw new Error("CONTAINER_DIGEST_INVALID");
+    return { image: source.reference, digest: digest2 };
+  }
+  const context = host.realpath(resolve2(request.release, source.context));
+  const dockerfile = host.realpath(resolve2(request.release, source.dockerfile));
+  if (!within2(request.release, context) || !within2(context, dockerfile))
+    throw new Error("CONTAINER_BUILD_PATH_INVALID");
+  const tag = `forgezero/${idFor2(request.key)}:${request.revision}`;
+  await checked2(host, [
+    "/usr/bin/docker",
+    "build",
+    "--pull",
+    ...request.noCache ? ["--no-cache"] : [],
+    "--file",
+    dockerfile,
+    "--tag",
+    tag,
+    "--label",
+    `net.forgezero.revision=${request.revision}`,
+    "--label",
+    `net.forgezero.component=${request.component}`,
+    context
+  ], "CONTAINER_BUILD_FAILED");
+  const digest = await checked2(host, ["/usr/bin/docker", "image", "inspect", "--format={{.Id}}", tag], "CONTAINER_INSPECT_FAILED");
+  if (!/^sha256:[a-f0-9]{64}$/.test(digest))
+    throw new Error("CONTAINER_DIGEST_INVALID");
+  return { image: tag, digest };
+}
+function readState2(host, id) {
+  if (!host.exists(statePath2(id)))
+    return null;
+  try {
+    const value = JSON.parse(host.read(statePath2(id)));
+    return value.format === 1 ? value : null;
+  } catch {
+    return null;
+  }
+}
+function usedPorts(host, exceptId) {
+  const ports = new Set;
+  for (const name of host.list(SERVICE_STATE_DIRECTORY).filter((entry) => /^[a-f0-9]{24}\.json$/.test(entry))) {
+    try {
+      const state = JSON.parse(host.read(`${SERVICE_STATE_DIRECTORY}/${name}`));
+      if (state.id !== exceptId) {
+        ports.add(state.publicPort);
+        state.applicationPorts.forEach((port) => ports.add(port));
+      }
+    } catch {}
+  }
+  return ports;
+}
+function allocatePorts(host, id, count, stablePort, previous) {
+  const used = usedPorts(host, id);
+  if (used.has(stablePort))
+    throw new Error("CONTAINER_PUBLIC_PORT_CONFLICT");
+  if (previous?.applicationPorts.length === count && previous.applicationPorts.every((port) => !used.has(port)))
+    return [...previous.applicationPorts];
+  const from = 20000;
+  const to = 49999;
+  const width = to - from + 1;
+  const start = Number.parseInt(id.slice(0, 8), 16) % width;
+  for (let offset = 0;offset < width; offset += 1) {
+    const first = from + (start + offset) % width;
+    const values = Array.from({ length: count }, (_, index) => first + index);
+    if (values.at(-1) <= to && values.every((port) => port !== stablePort && !used.has(port)))
+      return values;
+  }
+  throw new Error("CONTAINER_PORTS_EXHAUSTED");
+}
+function nginx2(request, id, port) {
+  const service = request.application.service;
+  const stablePort = request.application.network.ingress.stablePort;
+  return `# ForgeZero container ${id}
+${service.maximumConnections ? `limit_conn_zone $server_name zone=fz_${id}:64k;
+` : ""}server {
+  listen 127.0.0.1:${stablePort};
+  server_name _;
+${service.maximumConnections ? `  limit_conn fz_${id} ${service.maximumConnections};
+  limit_conn_status 503;
+` : ""}  location / {
+    proxy_pass http://127.0.0.1:${port};
+    proxy_http_version 1.1;
+${service.websocket ? `    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+` : ""}    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+}
+`;
+}
+function runArgv(request, id, slot, port, networkName) {
+  const { application } = request;
+  const resources = application.resources;
+  const runtime = application.runtime;
+  if (runtime.kind !== "container")
+    throw new Error("CONTAINER_RUNTIME_REQUIRED");
+  const memory = resources.memory;
+  const network = application.network.container;
+  const argv2 = [
+    "/usr/bin/docker",
+    "run",
+    "--detach",
+    "--name",
+    nameFor(id, slot),
+    "--restart",
+    "unless-stopped",
+    "--label",
+    `net.forgezero.key=${request.key}`,
+    "--label",
+    `net.forgezero.revision=${request.revision}`,
+    "--cpus",
+    String(resources.cpu.limit),
+    "--cpu-shares",
+    String(resources.cpu.weight ?? 100),
+    "--memory",
+    `${memory.limitMiB}m`,
+    ...memory.reservationMiB ? ["--memory-reservation", `${memory.reservationMiB}m`] : [],
+    ...memory.swap === "disabled" ? ["--memory-swap", `${memory.limitMiB}m`] : [],
+    "--pids-limit",
+    String(resources.pids.limit),
+    "--security-opt",
+    "no-new-privileges=true",
+    "--cap-drop",
+    "ALL",
+    ...runtime.security.root === "read-only" ? ["--read-only"] : [],
+    ...network.mode === "host" ? ["--network", "host", "--env", `FZ_APP_PORT=${port}`] : ["--network", networkName, "--publish", `127.0.0.1:${port}:${application.service.port}`]
+  ];
+  for (const mount of application.storage ?? []) {
+    if (mount.class === "ephemeral")
+      argv2.push("--tmpfs", `${mount.path}:rw,noexec,nosuid,size=${mount.sizeMiB}m`);
+    else
+      argv2.push("--volume", `forgezero-${id}-${mount.name}:${mount.path}`);
+  }
+  argv2.push(request.image, ...runtime.entrypoint ?? []);
+  return argv2;
+}
+async function activateContainer(requestValue, host = defaultHost2) {
+  const request = validateRequest(requestValue, host);
+  if (!/^sha256:[a-f0-9]{64}$/.test(request.image) && !/^forgezero\/[a-f0-9]{24}:[a-f0-9]{40}$/.test(request.image) && !request.image.includes("@sha256:"))
+    throw new Error("CONTAINER_IMAGE_INVALID");
+  const id = idFor2(request.key);
+  host.mkdir(SERVICE_STATE_DIRECTORY, 448);
+  host.mkdir(SERVICE_NGINX_DIRECTORY, 493);
+  const previous = readState2(host, id);
+  const slots = request.application.rollout.strategy === "blue-green" ? 2 : 1;
+  if (!["direct", "blue-green"].includes(request.application.rollout.strategy))
+    throw new Error("CONTAINER_ROLLOUT_REQUIRES_CONTROL_PLANE");
+  const containerNetwork = request.application.network.container;
+  let networkName = "host";
+  if (containerNetwork.mode === "bridge") {
+    networkName = containerNetwork.network ? `forgezero-${id}-${containerNetwork.network}` : "bridge";
+    if (networkName !== "bridge") {
+      const inspected = await host.exec(["/usr/bin/docker", "network", "inspect", '--format={{index .Labels "net.forgezero.owner"}}', networkName]);
+      if (inspected.exitCode !== 0) {
+        await checked2(host, ["/usr/bin/docker", "network", "create", "--driver", "bridge", "--label", `net.forgezero.owner=${id}`, networkName], "CONTAINER_NETWORK_CREATE_FAILED");
+      } else if (inspected.output.trim() !== id)
+        throw new Error("CONTAINER_NETWORK_OWNERSHIP_INVALID");
+    }
+  }
+  const ports = allocatePorts(host, id, slots, request.application.network.ingress.stablePort, previous);
+  const nextSlot = slots === 2 && previous?.activeSlot === 0 ? 1 : 0;
+  const port = ports[nextSlot];
+  const name = nameFor(id, nextSlot);
+  await host.exec(["/usr/bin/docker", "rm", "--force", name]);
+  await checked2(host, runArgv(request, id, nextSlot, port, networkName), "CONTAINER_START_FAILED");
+  let healthy = false;
+  const health = request.application.service.health;
+  for (let attempt = 0;attempt < (health.attempts ?? 30); attempt += 1) {
+    if (await host.health(port, health.path, health.timeoutMs, health.method, health.expectedStatus)) {
+      healthy = true;
+      break;
+    }
+    await host.sleep(health.intervalMs ?? 1000);
+  }
+  if (!healthy) {
+    await host.exec(["/usr/bin/docker", "rm", "--force", name]);
+    throw new Error("CONTAINER_HEALTH_FAILED");
+  }
+  const nginxPath = `${SERVICE_NGINX_DIRECTORY}/forgezero-${id}.conf`;
+  const previousNginx = host.exists(nginxPath) ? host.read(nginxPath) : null;
+  host.write(nginxPath, nginx2(request, id, port), 420);
+  try {
+    await checked2(host, ["/usr/sbin/nginx", "-t"], "CONTAINER_NGINX_INVALID");
+    await checked2(host, ["/usr/bin/systemctl", "reload", "nginx.service"], "CONTAINER_NGINX_RELOAD_FAILED");
+  } catch (cause) {
+    if (previousNginx === null)
+      host.remove(nginxPath);
+    else
+      host.write(nginxPath, previousNginx, 420);
+    await host.exec(["/usr/sbin/nginx", "-t"]);
+    await host.exec(["/usr/bin/systemctl", "reload", "nginx.service"]);
+    await host.exec(["/usr/bin/docker", "rm", "--force", name]);
+    throw cause;
+  }
+  const state = {
+    format: 1,
+    id,
+    key: request.key,
+    revision: request.revision,
+    strategy: request.application.rollout.strategy,
+    publicPort: request.application.network.ingress.stablePort,
+    applicationPorts: ports,
+    activeSlot: nextSlot,
+    healthPath: health.path,
+    updatedAtTs: host.now()
+  };
+  host.write(statePath2(id), `${JSON.stringify(state, null, 2)}
+`, 384);
+  if (previous && previous.activeSlot !== nextSlot) {
+    await host.sleep(request.application.rollout.drainMs ?? 30000);
+    await host.exec(["/usr/bin/docker", "rm", "--force", nameFor(id, previous.activeSlot)]);
+  }
+  return state;
+}
+
 // src/software-helper.ts
 var DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
 var SOFTWARE_HELPER_GROUP = "forgezero-software";
@@ -906,11 +1229,13 @@ var MAX_REQUEST_BYTES = 128 * 1024;
 var MAX_PENDING_REQUESTS = 128;
 function startSoftwareHelper(options = {}) {
   const socketPath = options.socketPath ?? DEFAULT_SOFTWARE_HELPER_SOCKET;
-  if (existsSync2(socketPath))
+  if (existsSync4(socketPath))
     unlinkSync2(socketPath);
-  mkdirSync3(dirname2(socketPath), { recursive: true, mode: 488 });
+  mkdirSync4(dirname3(socketPath), { recursive: true, mode: 488 });
   const ensure = options.ensure ?? ensureSoftwareRequirements;
   const activate = options.activate ?? activateSupervisedService;
+  const buildContainer = options.buildContainer ?? buildContainerImage;
+  const activateTypedContainer = options.activateContainer ?? activateContainer;
   let tail = Promise.resolve();
   let pending = 0;
   const server = createServer((socket) => {
@@ -943,10 +1268,29 @@ function startSoftwareHelper(options = {}) {
           return;
         }
         if (request.op === "activate-service" && request.request) {
-          if (!options.allowedRoot || request.request.root !== options.allowedRoot) {
+          const serviceRequest = request.request;
+          if (!options.allowedRoot || serviceRequest.root !== options.allowedRoot) {
             throw new Error("service deployment root is not owned by this helper");
           }
-          const state = await activate(request.request);
+          const state = await activate(serviceRequest);
+          socket.end(`${JSON.stringify({ ok: true, state })}
+`);
+          return;
+        }
+        if (request.op === "build-container" && request.request) {
+          const containerRequest = request.request;
+          if (!options.allowedRoot || containerRequest.root !== options.allowedRoot)
+            throw new Error("container deployment root is not owned by this helper");
+          const result = await buildContainer(containerRequest);
+          socket.end(`${JSON.stringify({ ok: true, result })}
+`);
+          return;
+        }
+        if (request.op === "activate-container" && request.request) {
+          const containerRequest = request.request;
+          if (!options.allowedRoot || containerRequest.root !== options.allowedRoot)
+            throw new Error("container deployment root is not owned by this helper");
+          const state = await activateTypedContainer(containerRequest);
           socket.end(`${JSON.stringify({ ok: true, state })}
 `);
           return;
@@ -970,8 +1314,43 @@ function startSoftwareHelper(options = {}) {
   server.listen(socketPath, () => chmodSync2(socketPath, 432));
   return server;
 }
+function requestContainer(op, request, socketPath, timeoutMs) {
+  return new Promise((resolve3, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op, request })}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("container helper timed out"));
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        const result = response.result ?? response.state;
+        if (!response.ok || !result)
+          throw new Error(response.error?.message ?? "container helper refused request");
+        resolve3(result);
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+function requestContainerBuild(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 30 * 60000) {
+  return requestContainer("build-container", request, socketPath, timeoutMs);
+}
+function requestContainerActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
+  return requestContainer("activate-container", request, socketPath, timeoutMs);
+}
 function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 10 * 60000) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "activate-service", request })}
 `));
     let buffer = "";
@@ -990,7 +1369,7 @@ function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_
         const response = JSON.parse(buffer.slice(0, newline));
         if (!response.ok || !response.state)
           throw new Error(response.error?.message ?? "service helper refused activation");
-        resolve2(response.state);
+        resolve3(response.state);
       } catch (cause) {
         reject(cause);
       }
@@ -1000,7 +1379,7 @@ function requestServiceActivation(request, socketPath = DEFAULT_SOFTWARE_HELPER_
 }
 function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
   validateSoftwareRequirements(requirements);
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
 `));
     let buffer = "";
@@ -1019,7 +1398,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
         const response = JSON.parse(buffer.slice(0, newline));
         if (!response.ok || !response.results)
           throw new Error(response.error?.message ?? "software helper refused the request");
-        resolve2(response.results);
+        resolve3(response.results);
       } catch (cause) {
         reject(cause);
       }
@@ -1031,6 +1410,8 @@ export {
   startSoftwareHelper,
   requestSoftware,
   requestServiceActivation,
+  requestContainerBuild,
+  requestContainerActivation,
   SOFTWARE_HELPER_UNIT_PATH,
   SOFTWARE_HELPER_GROUP,
   DEFAULT_SOFTWARE_HELPER_SOCKET

package/dist/software.d.ts

@@ -1,6 +1,6 @@
 export type CatalogStatus = 'testing' | 'active' | 'retired';
 export type DeploymentChannel = 'development' | 'production';
-export type SoftwareId = 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'cloudflare-warp' | 'ufw' | 'openssh-client';
+export type SoftwareId = 'bun' | 'docker' | 'nginx' | 'arangodb' | 'cloudflared' | 'cloudflare-warp' | 'ufw' | 'openssh-client';
 /** Repository input is a catalogue coordinate, never a root command. */
 export interface SoftwareRequirement {
     id: SoftwareId;

package/dist/software.js

@@ -4,6 +4,7 @@ import {
   accessSync,
   chmodSync,
   copyFileSync,
+  existsSync,
   mkdtempSync,
   mkdirSync,
   readFileSync,
@@ -24,6 +25,7 @@ var OS_CATALOG = [
 ];
 var SOFTWARE_CATALOG = [
   { id: "bun", version: "1.3.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "docker", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "nginx", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "arangodb", version: "3.11.14", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
   { id: "cloudflared", version: "2026.7.3", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
@@ -33,6 +35,7 @@ var SOFTWARE_CATALOG = [
 ];
 var UBUNTU_2604_X64 = [
   { requirement: { id: "bun", version: "1.3.14" } },
+  { requirement: { id: "docker", version: "ubuntu-26.04" } },
   { requirement: { id: "nginx", version: "ubuntu-26.04" } },
   { requirement: { id: "arangodb", version: "3.11.14" } },
   { requirement: { id: "cloudflared", version: "2026.7.3" } },
@@ -41,6 +44,15 @@ var UBUNTU_2604_X64 = [
   { requirement: { id: "openssh-client", version: "ubuntu-26.04" } }
 ];
 var path = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+var DOCKER_DAEMON_PATH = "/etc/docker/daemon.json";
+var DOCKER_DAEMON_CONFIG = `${JSON.stringify({
+  "data-root": "/var/lib/docker",
+  "storage-driver": "overlay2",
+  "live-restore": true,
+  "log-driver": "local",
+  "log-opts": { "max-size": "10m", "max-file": "3" }
+}, null, 2)}
+`;
 var softwareSpawnFailure = (cause, argv) => cause.code === "ENOENT" ? { exitCode: 127, output: `executable is absent: ${argv[0]}` } : undefined;
 var runSoftwareCommand = async (argv, env = {}) => {
   let child;
@@ -83,12 +95,21 @@ async function executeSoftwareOperation(operation) {
   if (operation.kind === "check") {
     if (software === "bun")
       return run(["/usr/local/bin/bun", "--version"]).then((r) => ({ ...r, exitCode: successful(r, /^1\.3\.14\s*$/m) ? 0 : 1 }));
+    if (software === "docker") {
+      const binary = await run(["/usr/bin/docker", "--version"]);
+      if (!successful(binary, /Docker version/))
+        return { ...binary, exitCode: 1 };
+      if (!existsSync(DOCKER_DAEMON_PATH) || readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG)
+        return { exitCode: 1, output: "Docker daemon policy is absent or differs from the reviewed ForgeZero policy" };
+      const active = await run(["/usr/bin/systemctl", "is-active", "--quiet", "docker.service"]);
+      return active.exitCode === 0 ? { exitCode: 0, output: binary.output } : active;
+    }
     if (software === "nginx") {
       const binary = await run(["/usr/sbin/nginx", "-v"]);
       return binary.exitCode === 0 ? run(["/usr/bin/systemctl", "is-active", "--quiet", "nginx.service"]) : binary;
     }
     if (software === "arangodb") {
-      const binary = await run(["/usr/bin/arangod", "--version"]);
+      const binary = await run(["/usr/sbin/arangod", "--version"]);
       if (!successful(binary, /3\.11\.14/))
         return { ...binary, exitCode: 1 };
       const [active, enabled] = await Promise.all([
@@ -115,11 +136,22 @@ async function executeSoftwareOperation(operation) {
       return { exitCode: 1, output: cause instanceof Error ? cause.message : String(cause) };
     }
   }
-  if (software === "nginx" || software === "ufw" || software === "openssh-client") {
-    const installed = await aptInstall(software === "openssh-client" ? "openssh-client" : software);
-    if (installed.exitCode !== 0 || software !== "nginx")
+  if (software === "docker" || software === "nginx" || software === "ufw" || software === "openssh-client") {
+    const packageName = software === "openssh-client" ? "openssh-client" : software === "docker" ? "docker.io" : software;
+    const installed = await aptInstall(packageName);
+    if (installed.exitCode !== 0 || software !== "nginx" && software !== "docker")
       return installed;
-    return run(["/usr/bin/systemctl", "enable", "--now", "nginx.service"]);
+    if (software === "docker") {
+      mkdirSync("/etc/docker", { recursive: true, mode: 493 });
+      if (existsSync(DOCKER_DAEMON_PATH) && readFileSync(DOCKER_DAEMON_PATH, "utf8") !== DOCKER_DAEMON_CONFIG) {
+        return { exitCode: 2, output: "refusing to overwrite an existing Docker daemon configuration that differs from the reviewed ForgeZero policy" };
+      }
+      if (!existsSync(DOCKER_DAEMON_PATH))
+        writeFileSync(DOCKER_DAEMON_PATH, DOCKER_DAEMON_CONFIG, { mode: 420, flag: "wx" });
+      const enabled = await run(["/usr/bin/systemctl", "enable", "docker.service"]);
+      return enabled.exitCode === 0 ? run(["/usr/bin/systemctl", "restart", "docker.service"]) : enabled;
+    }
+    return run(["/usr/bin/systemctl", "enable", "--now", `${software}.service`]);
   }
   const directory = mkdtempSync(join(tmpdir(), "forgezero-software-"));
   try {
@@ -204,7 +236,7 @@ function validateSoftwareRequirements(value, _options = {}) {
     if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
       throw new Error("software requirement contains an unknown field");
     }
-    if (!["bun", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "docker", "nginx", "arangodb", "cloudflared", "cloudflare-warp", "ufw", "openssh-client"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
       throw new Error("software requirement coordinate is invalid");
     }
     const requirement = { id: row.id, version: row.version };

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.52";
+export declare const VERSION = "0.1.55";