@forgezero/agent 0.1.25 → 0.1.27

package/dist/socket.d.ts

@@ -113,6 +113,8 @@ export interface AttestationSource {
 }
 export interface AgentOptions {
     socketPath: string;
+    /** PID 1-owned listener retained while the Agent drains and restarts. */
+    listenFd?: number;
     keys: NodeKeyPair;
     /** The node's identifier, as the platform knows it. */
     nodeKey: string;

package/dist/software-helper.d.ts

@@ -0,0 +1,14 @@
+import { type Server } from 'node:net';
+import { ensureSoftwareRequirements, type SoftwareRequirement } from './software';
+export declare const DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
+export declare const SOFTWARE_HELPER_GROUP = "forgezero-software";
+export declare const SOFTWARE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-software-helper.service";
+export declare function startSoftwareHelper(options?: {
+    socketPath?: string;
+    ensure?: typeof ensureSoftwareRequirements;
+}): Server;
+export declare function requestSoftware(requirements: readonly SoftwareRequirement[], socketPath?: string, timeoutMs?: number): Promise<Array<{
+    id: string;
+    version: string;
+    changed: boolean;
+}>>;

package/dist/software-helper.js

@@ -0,0 +1,203 @@
+// src/software.ts
+import { readFileSync } from "node:fs";
+var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
+var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var UBUNTU_2604_X64 = [
+  {
+    requirement: { id: "bun", version: "1.3.14" },
+    check: 'test "$(/usr/local/bin/bun --version 2>/dev/null)" = 1.3.14',
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL https://bun.sh/install -o "$tmp/install"; ` + `echo "${BUN_INSTALLER_SHA256}  $tmp/install" | sha256sum -c -; ` + `BUN_INSTALL="$tmp/bun" BUN_VERSION=1.3.14 bash "$tmp/install" >/dev/null; ` + `install -d -m 0755 /usr/local/lib/forgezero/runtime; ` + `install -m 0755 "$tmp/bun/bin/bun" /usr/local/lib/forgezero/runtime/bun.next; ` + `mv -Tf /usr/local/lib/forgezero/runtime/bun.next /usr/local/lib/forgezero/runtime/bun; ` + `ln -sfn /usr/local/lib/forgezero/runtime/bun /usr/local/bin/bun`
+  },
+  {
+    requirement: { id: "nginx", version: "ubuntu-26.04" },
+    check: "command -v nginx >/dev/null && systemctl is-active --quiet nginx",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y nginx && systemctl enable --now nginx"
+  },
+  {
+    requirement: { id: "arangodb", version: "3.11.14" },
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+  },
+  {
+    requirement: { id: "cloudflared", version: "2026.7.3" },
+    check: `cloudflared --version 2>/dev/null | grep -q '2026.7.3'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64' -o "$tmp/cloudflared"; ` + `echo "${CLOUDFLARED_SHA256}  $tmp/cloudflared" | sha256sum -c -; ` + `install -m 0755 "$tmp/cloudflared" /usr/local/bin/cloudflared`
+  },
+  {
+    requirement: { id: "ufw", version: "ubuntu-26.04" },
+    check: "command -v ufw >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  }
+];
+function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
+  const values = Object.fromEntries(osRelease.split(`
+`).flatMap((line) => {
+    const separator = line.indexOf("=");
+    return separator > 0 ? [[line.slice(0, separator), line.slice(separator + 1).replace(/^['"]|['"]$/g, "")]] : [];
+  }));
+  return {
+    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    architecture
+  };
+}
+function validateSoftwareRequirements(value) {
+  if (!Array.isArray(value) || value.length > 32)
+    throw new Error("software requirements must be an array of at most 32 entries");
+  const seen = new Set;
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("software requirement must be an object");
+    const row = item;
+    if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
+      throw new Error("software requirement contains an unknown field");
+    }
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].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 };
+    if (seen.has(requirement.id))
+      throw new Error(`duplicate software requirement: ${requirement.id}`);
+    seen.add(requirement.id);
+    return requirement;
+  });
+}
+async function ensureSoftwareRequirements(requirementsInput, options) {
+  const requirements = validateSoftwareRequirements(requirementsInput);
+  const observation = options.observation ?? observeSoftwareHost();
+  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+    throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
+  }
+  const results = [];
+  for (const requirement of requirements) {
+    const strategy = UBUNTU_2604_X64.find(({ requirement: candidate }) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!strategy)
+      throw new Error(`unsupported software requirement: ${requirement.id}@${requirement.version}`);
+    const before = await options.exec(strategy.check);
+    if (before.exitCode === 0) {
+      results.push({ ...requirement, changed: false });
+      continue;
+    }
+    const installed = await options.exec(strategy.install);
+    if (installed.exitCode !== 0)
+      throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
+    const after = await options.exec(strategy.check);
+    if (after.exitCode !== 0)
+      throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
+    results.push({ ...requirement, changed: true });
+  }
+  return results;
+}
+
+// src/software-helper.ts
+import { chmodSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { connect, createServer } from "node:net";
+import { dirname } from "node:path";
+var DEFAULT_SOFTWARE_HELPER_SOCKET = "/run/forgezero-software/helper.sock";
+var SOFTWARE_HELPER_GROUP = "forgezero-software";
+var SOFTWARE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-software-helper.service";
+var MAX_REQUEST_BYTES = 8 * 1024;
+var MAX_PENDING_REQUESTS = 128;
+var execute = async (command) => {
+  const child = Bun.spawn(["/bin/bash", "-Eeuo", "pipefail", "-c", command], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+function startSoftwareHelper(options = {}) {
+  const socketPath = options.socketPath ?? DEFAULT_SOFTWARE_HELPER_SOCKET;
+  if (existsSync(socketPath))
+    unlinkSync(socketPath);
+  mkdirSync(dirname(socketPath), { recursive: true, mode: 488 });
+  const ensure = options.ensure ?? ensureSoftwareRequirements;
+  let tail = Promise.resolve();
+  let pending = 0;
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES)
+        return socket.destroy();
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      if (pending >= MAX_PENDING_REQUESTS) {
+        socket.end(`${JSON.stringify({
+          ok: false,
+          error: { code: "SOFTWARE_BUSY", message: "software helper queue is full" }
+        })}
+`);
+        return;
+      }
+      pending += 1;
+      const work = tail.then(() => Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
+        if (request.op !== "ensure")
+          throw new Error("unknown software helper operation");
+        const requirements = validateSoftwareRequirements(request.requirements);
+        const results = await ensure(requirements, { exec: execute });
+        socket.end(`${JSON.stringify({ ok: true, results })}
+`);
+      }).catch((cause) => socket.end(`${JSON.stringify({
+        ok: false,
+        error: { code: "SOFTWARE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
+      })}
+`)).finally(() => {
+        pending -= 1;
+      }));
+      tail = work.then(() => {
+        return;
+      }, () => {
+        return;
+      });
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync(socketPath, 432));
+  return server;
+}
+function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCKET, timeoutMs = 15 * 60000) {
+  validateSoftwareRequirements(requirements);
+  return new Promise((resolve, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "ensure", requirements })}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("software helper did not answer before its deadline"));
+    });
+    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));
+        if (!response.ok || !response.results)
+          throw new Error(response.error?.message ?? "software helper refused the request");
+        resolve(response.results);
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+export {
+  startSoftwareHelper,
+  requestSoftware,
+  SOFTWARE_HELPER_UNIT_PATH,
+  SOFTWARE_HELPER_GROUP,
+  DEFAULT_SOFTWARE_HELPER_SOCKET
+};

package/dist/software.d.ts

@@ -0,0 +1,27 @@
+/** Repository input is a catalogue coordinate, never a root command. */
+export interface SoftwareRequirement {
+    id: 'bun' | 'nginx' | 'arangodb' | 'cloudflared' | 'ufw';
+    version: string;
+}
+export interface SoftwareObservation {
+    os: {
+        id: string;
+        versionId: string;
+    };
+    architecture: string;
+}
+export interface SoftwareCommandResult {
+    exitCode: number;
+    output: string;
+}
+export type SoftwareExec = (command: string) => Promise<SoftwareCommandResult>;
+export declare function observeSoftwareHost(osRelease?: string, architecture?: NodeJS.Architecture): SoftwareObservation;
+export declare function validateSoftwareRequirements(value: unknown): SoftwareRequirement[];
+export declare function ensureSoftwareRequirements(requirementsInput: unknown, options: {
+    observation?: SoftwareObservation;
+    exec: SoftwareExec;
+}): Promise<Array<{
+    id: string;
+    version: string;
+    changed: boolean;
+}>>;

package/dist/software.js

@@ -0,0 +1,95 @@
+// src/software.ts
+import { readFileSync } from "node:fs";
+var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
+var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
+var UBUNTU_2604_X64 = [
+  {
+    requirement: { id: "bun", version: "1.3.14" },
+    check: 'test "$(/usr/local/bin/bun --version 2>/dev/null)" = 1.3.14',
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL https://bun.sh/install -o "$tmp/install"; ` + `echo "${BUN_INSTALLER_SHA256}  $tmp/install" | sha256sum -c -; ` + `BUN_INSTALL="$tmp/bun" BUN_VERSION=1.3.14 bash "$tmp/install" >/dev/null; ` + `install -d -m 0755 /usr/local/lib/forgezero/runtime; ` + `install -m 0755 "$tmp/bun/bin/bun" /usr/local/lib/forgezero/runtime/bun.next; ` + `mv -Tf /usr/local/lib/forgezero/runtime/bun.next /usr/local/lib/forgezero/runtime/bun; ` + `ln -sfn /usr/local/lib/forgezero/runtime/bun /usr/local/bin/bun`
+  },
+  {
+    requirement: { id: "nginx", version: "ubuntu-26.04" },
+    check: "command -v nginx >/dev/null && systemctl is-active --quiet nginx",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y nginx && systemctl enable --now nginx"
+  },
+  {
+    requirement: { id: "arangodb", version: "3.11.14" },
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+  },
+  {
+    requirement: { id: "cloudflared", version: "2026.7.3" },
+    check: `cloudflared --version 2>/dev/null | grep -q '2026.7.3'`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://github.com/cloudflare/cloudflared/releases/download/2026.7.3/cloudflared-linux-amd64' -o "$tmp/cloudflared"; ` + `echo "${CLOUDFLARED_SHA256}  $tmp/cloudflared" | sha256sum -c -; ` + `install -m 0755 "$tmp/cloudflared" /usr/local/bin/cloudflared`
+  },
+  {
+    requirement: { id: "ufw", version: "ubuntu-26.04" },
+    check: "command -v ufw >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y ufw"
+  }
+];
+function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
+  const values = Object.fromEntries(osRelease.split(`
+`).flatMap((line) => {
+    const separator = line.indexOf("=");
+    return separator > 0 ? [[line.slice(0, separator), line.slice(separator + 1).replace(/^['"]|['"]$/g, "")]] : [];
+  }));
+  return {
+    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    architecture
+  };
+}
+function validateSoftwareRequirements(value) {
+  if (!Array.isArray(value) || value.length > 32)
+    throw new Error("software requirements must be an array of at most 32 entries");
+  const seen = new Set;
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item))
+      throw new Error("software requirement must be an object");
+    const row = item;
+    if (Object.keys(row).some((key) => key !== "id" && key !== "version")) {
+      throw new Error("software requirement contains an unknown field");
+    }
+    if (!["bun", "nginx", "arangodb", "cloudflared", "ufw"].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 };
+    if (seen.has(requirement.id))
+      throw new Error(`duplicate software requirement: ${requirement.id}`);
+    seen.add(requirement.id);
+    return requirement;
+  });
+}
+async function ensureSoftwareRequirements(requirementsInput, options) {
+  const requirements = validateSoftwareRequirements(requirementsInput);
+  const observation = options.observation ?? observeSoftwareHost();
+  if (observation.os.id !== "ubuntu" || observation.os.versionId !== "26.04" || observation.architecture !== "x64") {
+    throw new Error(`unsupported software strategy: ${observation.os.id} ${observation.os.versionId} ${observation.architecture}`);
+  }
+  const results = [];
+  for (const requirement of requirements) {
+    const strategy = UBUNTU_2604_X64.find(({ requirement: candidate }) => candidate.id === requirement.id && candidate.version === requirement.version);
+    if (!strategy)
+      throw new Error(`unsupported software requirement: ${requirement.id}@${requirement.version}`);
+    const before = await options.exec(strategy.check);
+    if (before.exitCode === 0) {
+      results.push({ ...requirement, changed: false });
+      continue;
+    }
+    const installed = await options.exec(strategy.install);
+    if (installed.exitCode !== 0)
+      throw new Error(`could not install ${requirement.id}@${requirement.version}: ${installed.output.trim()}`);
+    const after = await options.exec(strategy.check);
+    if (after.exitCode !== 0)
+      throw new Error(`${requirement.id}@${requirement.version} did not pass its post-install check`);
+    results.push({ ...requirement, changed: true });
+  }
+  return results;
+}
+export {
+  validateSoftwareRequirements,
+  observeSoftwareHost,
+  ensureSoftwareRequirements
+};

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.25";
+export declare const VERSION = "0.1.27";

package/package.json

@@ -1,15 +1,16 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.25",
+	"version": "0.1.27",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm --packages external && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm --packages external && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"devDependencies": {
+		"@forgezero/access": "^0.1.0",
 		"typescript": "^5.6.0",
 		"@types/bun": "latest",
 		"@types/node": "^22.0.0",
@@ -17,9 +18,8 @@
 		"@noble/post-quantum": "^0.6.1"
 	},
 	"dependencies": {
-		"@forgezero/access": "^0.1.0",
 		"@forgezero/runtime": "^0.1.4",
-		"@forgezero/vault": "^0.1.5",
+		"@forgezero/vault": "^0.1.7",
 		"@noble/curves": "^2.2.0",
 		"@noble/hashes": "^2.2.0",
 		"@noble/post-quantum": "^0.6.1",
@@ -96,6 +96,26 @@
 			"types": "./dist/lifecycle-helper.d.ts",
 			"default": "./dist/lifecycle-helper.js"
 		},
+		"./agent-update": {
+			"types": "./dist/agent-update.d.ts",
+			"default": "./dist/agent-update.js"
+		},
+		"./agent-update-helper": {
+			"types": "./dist/agent-update-helper.d.ts",
+			"default": "./dist/agent-update-helper.js"
+		},
+		"./agent-heartbeat": {
+			"types": "./dist/agent-heartbeat.d.ts",
+			"default": "./dist/agent-heartbeat.js"
+		},
+		"./software": {
+			"types": "./dist/software.d.ts",
+			"default": "./dist/software.js"
+		},
+		"./software-helper": {
+			"types": "./dist/software-helper.d.ts",
+			"default": "./dist/software-helper.js"
+		},
 		"./metal-provision": {
 			"types": "./dist/metal-provision.d.ts",
 			"default": "./dist/metal-provision.js"