@forgezero/agent 0.1.34 → 0.1.35

package/dist/metal-bootstrap.js

@@ -0,0 +1,942 @@
+// @bun
+// src/metal-bootstrap.ts
+import { createHash, randomBytes } from "crypto";
+import {
+  chmodSync,
+  chownSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync as mkdirSync2,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve } from "path";
+import { isIP as isIP2 } from "net";
+
+// src/metal-isolation.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+
+// src/metal-provision.ts
+import { dirname, isAbsolute, join } from "path";
+import { isIP } from "net";
+
+// src/ubuntu.ts
+var SUPPORTED_GUEST_IMAGE = Object.freeze({
+  key: "ubuntu-resolute-20260731",
+  family: "ubuntu-26.04",
+  version: "2026-07-31",
+  label: "Ubuntu 26.04 LTS Resolute",
+  url: "https://cloud-images.ubuntu.com/releases/resolute/release-20260731/ubuntu-26.04-server-cloudimg-amd64.img",
+  sha256: "9dc7c5363c0146a08ba0c9aa834d82c2c6dfbb1c471ad9a2f0aba1189e21be05"
+});
+
+// src/metal-provision.ts
+var SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/;
+var DEVICE = /^[a-zA-Z][a-zA-Z0-9_.-]{0,14}$/;
+var IPV4_PREFIX = /^(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)\.(?:25[0-5]|2[0-4]\d|1?\d?\d)$/;
+var LINUX_LIST = /^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/;
+
+class MetalProvisionError extends Error {
+}
+function membersOfLinuxList(value, label) {
+  if (!LINUX_LIST.test(value))
+    throw new MetalProvisionError(`invalid ${label} list`);
+  const members = [];
+  for (const part of value.split(",")) {
+    const [startText, endText = startText] = part.split("-");
+    const start = Number(startText);
+    const end = Number(endText);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > 65535) {
+      throw new MetalProvisionError(`invalid ${label} list`);
+    }
+    for (let value2 = start;value2 <= end; value2 += 1)
+      members.push(value2);
+  }
+  if (new Set(members).size !== members.length)
+    throw new MetalProvisionError(`${label} list overlaps itself`);
+  return members;
+}
+function validateMetalProfile(profile) {
+  if (!SAFE_NAME.test(profile.volumeGroup))
+    throw new MetalProvisionError("invalid volume group");
+  if (!DEVICE.test(profile.bridge))
+    throw new MetalProvisionError("invalid bridge");
+  if (!IPV4_PREFIX.test(profile.subnetPrefix))
+    throw new MetalProvisionError("invalid subnet prefix");
+  if (!Number.isInteger(profile.addressStart) || !Number.isInteger(profile.addressEnd) || profile.addressStart < 2 || profile.addressEnd > 254 || profile.addressStart > profile.addressEnd)
+    throw new MetalProvisionError("invalid guest address range");
+  for (const path of [profile.stateDir, profile.seedDir, profile.unitDir]) {
+    if (!isAbsolute(path))
+      throw new MetalProvisionError("metal paths must be absolute");
+  }
+  new URL(profile.apiUrl);
+  let telemetryEndpoint;
+  try {
+    telemetryEndpoint = new URL(profile.agentTelemetryEndpoint);
+  } catch {
+    throw new MetalProvisionError("Agent telemetry endpoint must be an absolute public HTTPS URL");
+  }
+  if (telemetryEndpoint.protocol !== "https:" || telemetryEndpoint.username || telemetryEndpoint.password || telemetryEndpoint.search || telemetryEndpoint.hash || isIP(telemetryEndpoint.hostname) !== 0 || !telemetryEndpoint.hostname.includes(".") || telemetryEndpoint.hostname === "localhost" || telemetryEndpoint.hostname.endsWith(".local"))
+    throw new MetalProvisionError("Agent telemetry endpoint must be a public HTTPS DNS coordinate without credentials, query or fragment");
+  const imageKeys = Object.keys(profile.images);
+  if (imageKeys.length !== 1 || imageKeys[0] !== SUPPORTED_GUEST_IMAGE.key || profile.images[SUPPORTED_GUEST_IMAGE.key]?.sha256 !== SUPPORTED_GUEST_IMAGE.sha256) {
+    throw new MetalProvisionError(`metal profile must contain only the pinned ${SUPPORTED_GUEST_IMAGE.key} image contract`);
+  }
+  if (!Array.isArray(profile.cpuPools) || profile.cpuPools.length === 0) {
+    throw new MetalProvisionError("at least one exclusive CPU pool is required");
+  }
+  const keys = new Set;
+  const assigned = new Set;
+  const assignedMemory = new Set;
+  let poolsWithMemory = 0;
+  for (const pool of profile.cpuPools) {
+    if (!SAFE_NAME.test(pool.key) || keys.has(pool.key))
+      throw new MetalProvisionError("invalid or duplicate CPU pool key");
+    keys.add(pool.key);
+    const cpus = membersOfLinuxList(pool.cpus, "CPU");
+    if (!Number.isInteger(pool.physicalCores) || pool.physicalCores < 1 || pool.physicalCores > cpus.length) {
+      throw new MetalProvisionError("invalid CPU pool physical-core count");
+    }
+    for (const cpu of cpus) {
+      if (assigned.has(cpu))
+        throw new MetalProvisionError("CPU pools overlap");
+      assigned.add(cpu);
+    }
+    if (pool.memoryNodes) {
+      poolsWithMemory += 1;
+      for (const node of membersOfLinuxList(pool.memoryNodes, "memory-node")) {
+        if (assignedMemory.has(node))
+          throw new MetalProvisionError("guest memory-node pools overlap");
+        assignedMemory.add(node);
+      }
+    }
+  }
+  if (poolsWithMemory !== 0 && poolsWithMemory !== profile.cpuPools.length) {
+    throw new MetalProvisionError("every CPU pool must name memory nodes when NUMA isolation is enabled");
+  }
+  const housekeeping = membersOfLinuxList(profile.housekeepingCpus, "housekeeping CPU");
+  if (housekeeping.some((cpu) => assigned.has(cpu))) {
+    throw new MetalProvisionError("housekeeping CPUs overlap guest CPU pools");
+  }
+  if (profile.housekeepingMemoryNodes) {
+    const housekeepingMemory = membersOfLinuxList(profile.housekeepingMemoryNodes, "housekeeping memory-node");
+    if (housekeepingMemory.some((node) => assignedMemory.has(node))) {
+      throw new MetalProvisionError("housekeeping memory nodes overlap guest memory-node pools");
+    }
+  } else if (assignedMemory.size > 0) {
+    throw new MetalProvisionError("NUMA-isolated guest pools require housekeeping memory nodes");
+  }
+}
+
+// src/metal-isolation.ts
+var members = (list) => list.split(",").flatMap((part) => {
+  const [first, last = first] = part.split("-").map(Number);
+  return Array.from({ length: last - first + 1 }, (_, index) => first + index);
+});
+var compact = (values) => {
+  const sorted = [...new Set(values)].sort((left, right) => left - right);
+  const ranges = [];
+  for (let index = 0;index < sorted.length; ) {
+    const first = sorted[index];
+    let last = first;
+    while (sorted[index + 1] === last + 1)
+      last = sorted[++index];
+    ranges.push(first === last ? String(first) : `${first}-${last}`);
+    index += 1;
+  }
+  return ranges.join(",");
+};
+var memoryDirective = (nodes) => nodes ? `AllowedMemoryNodes=${nodes}
+` : "";
+function metalGuestSliceUnit(profile) {
+  validateMetalProfile(profile);
+  const cpus = compact(profile.cpuPools.flatMap((pool) => members(pool.cpus)));
+  const nodes = compact(profile.cpuPools.flatMap((pool) => pool.memoryNodes ? members(pool.memoryNodes) : [])) || undefined;
+  return `[Unit]
+Description=ForgeZero exclusive guest CPU and memory boundary
+
+[Slice]
+AllowedCPUs=${cpus}
+${memoryDirective(nodes)}`;
+}
+function metalHousekeepingDropIn(profile, kind) {
+  validateMetalProfile(profile);
+  return `[${kind === "slice" ? "Slice" : "Scope"}]
+AllowedCPUs=${profile.housekeepingCpus}
+${memoryDirective(profile.housekeepingMemoryNodes)}`;
+}
+var defaultExec = async (argv) => {
+  const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text()
+  ]);
+  return { exitCode, stdout, stderr };
+};
+var checked = async (exec, argv) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${argv[0]} failed: ${(result.stderr || result.stdout).trim()}`);
+  return result;
+};
+var requireGuestsInSlice = async (exec) => {
+  const active = await checked(exec, [
+    "systemctl",
+    "list-units",
+    "--type=service",
+    "--state=running",
+    "--plain",
+    "--no-legend",
+    "forgezero-guest@*.service"
+  ]);
+  for (const line of active.stdout.split(`
+`)) {
+    const service = line.trim().split(/\s+/)[0];
+    if (!service)
+      continue;
+    const cgroup = await checked(exec, ["systemctl", "show", "-p", "ControlGroup", "--value", service]);
+    if (!cgroup.stdout.trim().includes("/forgezero-guests.slice/")) {
+      throw new Error(`${service} must be drained and restarted into forgezero-guests.slice`);
+    }
+  }
+};
+async function applyMetalIsolation(profile, exec = defaultExec) {
+  validateMetalProfile(profile);
+  await requireGuestsInSlice(exec);
+  const unitDir = profile.unitDir;
+  mkdirSync(unitDir, { recursive: true });
+  writeFileSync(join2(unitDir, "forgezero-guests.slice"), metalGuestSliceUnit(profile), { mode: 420 });
+  for (const unit of ["system.slice", "user.slice"]) {
+    const directory = join2(unitDir, `${unit}.d`);
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(join2(directory, "50-forgezero-housekeeping.conf"), metalHousekeepingDropIn(profile, "slice"), { mode: 420 });
+  }
+  const initDirectory = join2(unitDir, "init.scope.d");
+  mkdirSync(initDirectory, { recursive: true });
+  writeFileSync(join2(initDirectory, "50-forgezero-housekeeping.conf"), metalHousekeepingDropIn(profile, "scope"), { mode: 420 });
+  await checked(exec, ["systemctl", "daemon-reload"]);
+  await requireGuestsInSlice(exec);
+  const properties = [`AllowedCPUs=${profile.housekeepingCpus}`];
+  if (profile.housekeepingMemoryNodes)
+    properties.push(`AllowedMemoryNodes=${profile.housekeepingMemoryNodes}`);
+  for (const unit of ["system.slice", "user.slice", "init.scope"]) {
+    await checked(exec, ["systemctl", "set-property", "--runtime", unit, ...properties]);
+  }
+}
+
+// src/egress-policy.ts
+var AGENT_EGRESS_TABLE = "forgezero_agent_egress";
+var SYSTEMD_RESOLVED_ADDRESS = "127.0.0.53";
+var BLOCKED_IPV4 = [
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "168.63.129.16/32",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.0.0/24",
+  "192.0.2.0/24",
+  "192.88.99.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "198.51.100.0/24",
+  "203.0.113.0/24",
+  "224.0.0.0/4",
+  "240.0.0.0/4"
+];
+var BLOCKED_IPV6 = [
+  "::/128",
+  "::1/128",
+  "::ffff:0:0/96",
+  "64:ff9b::/96",
+  "64:ff9b:1::/48",
+  "100::/64",
+  "fc00::/7",
+  "fec0::/10",
+  "fe80::/10",
+  "ff00::/8",
+  "2001::/32",
+  "2001:2::/48",
+  "2001:10::/28",
+  "2001:20::/28",
+  "2001:db8::/32",
+  "2002::/16",
+  "3fff::/20"
+];
+var normalizeEgressTcpPorts = (ports) => {
+  for (const port of ports) {
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Agent egress policy refuses an invalid loopback TCP port.");
+    }
+  }
+  return [...new Set(ports)].sort((left, right) => left - right);
+};
+function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
+  const ports = normalizeEgressTcpPorts(loopbackTcpPorts);
+  return [
+    "RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6",
+    `IPAddressAllow=${SYSTEMD_RESOLVED_ADDRESS}/32`,
+    ...ports.length > 0 ? ["IPAddressAllow=127.0.0.1/32", "IPAddressAllow=::1/128"] : [],
+    ...BLOCKED_IPV4.map((network) => `IPAddressDeny=${network}`),
+    ...BLOCKED_IPV6.map((network) => `IPAddressDeny=${network}`)
+  ].join(`
+`);
+}
+
+// src/version.ts
+var VERSION = "0.1.35";
+
+// src/metal-bootstrap.ts
+var PROFILE_PATH = "/etc/forgezero/metal.json";
+var STATE_PATH = "/etc/forgezero/metal.initialized.json";
+var SEED_CREDENTIAL_PATH = "/etc/forgezero/creds/metal-agent-seed.cred";
+var UNIT_DIRECTORY = "/etc/systemd/system";
+var AGENT_PATH = "/usr/local/bin/fz-agent";
+var HELPER_SOCKET = "/run/forgezero-metal/helper.sock";
+var UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
+var MAX_CONFIG_BYTES = 256 * 1024;
+var SUPPORTED_BUN_VERSION = "1.3.14";
+var SUPPORTED_BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
+
+class MetalBootstrapError extends Error {
+}
+var defaultExec2 = async (argv, stdin) => {
+  const child = Bun.spawn([...argv], {
+    stdin: stdin === undefined ? undefined : new Blob([stdin]),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text()
+  ]);
+  return { exitCode, stdout, stderr };
+};
+var runChecked = async (exec, argv, stdin) => {
+  const result = await exec(argv, stdin);
+  if (result.exitCode !== 0) {
+    throw new MetalBootstrapError(`${argv.join(" ")} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.exitCode}`}`);
+  }
+  return result;
+};
+var exactKeys = (value, allowed, label) => {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length)
+    throw new MetalBootstrapError(`${label} contains unknown fields: ${unknown.join(", ")}`);
+};
+var validUnit = (unit) => {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.@-]{0,127}\.service$/.test(unit)) {
+    throw new MetalBootstrapError("hostTelemetryUnit must be a systemd .service unit");
+  }
+  if (/^(forgezero@.*|forgezero-agent|forgezero-metal-agent|forgezero-metal-helper|forgezero-db)\.service$/.test(unit)) {
+    throw new MetalBootstrapError("the OTLP collector must be independently supervised");
+  }
+};
+function validateMetalBootstrapConfig(config) {
+  if (!config || typeof config !== "object")
+    throw new MetalBootstrapError("metal bootstrap config must be an object");
+  exactKeys(config, ["kind", "metalHostname", "profile", "hostTelemetryEndpoint", "hostTelemetryUnit", "agentSeedFile"], "metal bootstrap config");
+  if (config.kind !== "metal")
+    throw new MetalBootstrapError("metal bootstrap config kind must be metal");
+  if (!/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(config.metalHostname)) {
+    throw new MetalBootstrapError("invalid metal inventory hostname");
+  }
+  if (!config.profile || typeof config.profile !== "object")
+    throw new MetalBootstrapError("metal profile must be an object");
+  exactKeys(config.profile, [
+    "volumeGroup",
+    "bridge",
+    "subnetPrefix",
+    "addressStart",
+    "addressEnd",
+    "gateway",
+    "nameservers",
+    "stateDir",
+    "seedDir",
+    "unitDir",
+    "apiUrl",
+    "agentTelemetryEndpoint",
+    "images",
+    "cpuPools",
+    "housekeepingCpus",
+    "housekeepingMemoryNodes",
+    "bunVersion",
+    "bunInstallerSha256",
+    "agentVersion",
+    "confidential"
+  ], "metal profile");
+  if (Array.isArray(config.profile.cpuPools)) {
+    for (const pool of config.profile.cpuPools)
+      exactKeys(pool, ["key", "cpus", "physicalCores", "memoryNodes"], "metal CPU pool");
+  }
+  validateMetalProfile(config.profile);
+  if (config.profile.stateDir !== "/etc/forgezero/metal-guests" || config.profile.seedDir !== "/var/lib/forgezero/seed" || config.profile.unitDir !== UNIT_DIRECTORY || config.profile.legacyStateDir !== undefined) {
+    throw new MetalBootstrapError("metal bootstrap uses fixed state, seed, and systemd unit directories");
+  }
+  const image = config.profile.images[Object.keys(config.profile.images)[0]];
+  if (!image.path.startsWith("/var/lib/forgezero/images/") || resolve(image.path) !== image.path || /[\0\r\n]/.test(image.path)) {
+    throw new MetalBootstrapError("the pinned guest image must use the fixed image directory");
+  }
+  if (config.profile.bunVersion !== SUPPORTED_BUN_VERSION || config.profile.bunInstallerSha256 !== SUPPORTED_BUN_INSTALLER_SHA256 || config.profile.agentVersion !== VERSION) {
+    throw new MetalBootstrapError("metal guest runtime must use the package-owned Bun and Agent release coordinates");
+  }
+  let api;
+  try {
+    api = new URL(config.profile.apiUrl);
+  } catch {
+    throw new MetalBootstrapError("metal API must be a public HTTPS origin");
+  }
+  if (api.protocol !== "https:" || api.username || api.password || api.pathname !== "/" || api.search || api.hash || isIP2(api.hostname) !== 0 || !api.hostname.includes(".") || api.hostname.endsWith(".local")) {
+    throw new MetalBootstrapError("metal API must be a credential-free public HTTPS origin");
+  }
+  if (config.profile.nameservers?.some((address) => isIP2(address) === 0)) {
+    throw new MetalBootstrapError("metal nameservers must be literal IP addresses");
+  }
+  if (isIP2(`${config.profile.subnetPrefix}.1`) !== 4 || isIP2(config.profile.gateway) !== 4 || !config.profile.gateway.startsWith(`${config.profile.subnetPrefix}.`)) {
+    throw new MetalBootstrapError("metal gateway must be an IPv4 address in the reviewed subnet");
+  }
+  if (config.profile.confidential && (!Number.isSafeInteger(config.profile.confidential.cbitpos) || config.profile.confidential.cbitpos < 1 || config.profile.confidential.cbitpos > 63 || !Number.isSafeInteger(config.profile.confidential.reducedPhysBits) || config.profile.confidential.reducedPhysBits < 0 || config.profile.confidential.reducedPhysBits > 63 || !/^0x[0-9a-fA-F]{1,16}$/.test(config.profile.confidential.policy)))
+    throw new MetalBootstrapError("invalid confidential-compute coordinate");
+  if (config.hostTelemetryEndpoint !== "http://127.0.0.1:4318") {
+    throw new MetalBootstrapError("metal host OTLP must use exact loopback http://127.0.0.1:4318");
+  }
+  validUnit(config.hostTelemetryUnit);
+  if (config.agentSeedFile)
+    validateOwnerOnlyPath(config.agentSeedFile, false);
+  return config;
+}
+function validateOwnerOnlyPath(path, requireRootOwner) {
+  if (!isAbsolute2(path) || resolve(path) !== path || path.includes("/../")) {
+    throw new MetalBootstrapError("private bootstrap paths must be canonical absolute paths");
+  }
+  const metadata = lstatSync(path);
+  if (!metadata.isFile() || metadata.isSymbolicLink() || realpathSync(path) !== path) {
+    throw new MetalBootstrapError("private bootstrap path must be a regular non-symlink file");
+  }
+  if ((metadata.mode & 63) !== 0)
+    throw new MetalBootstrapError("private bootstrap file must be owner-only");
+  const caller = typeof process.getuid === "function" ? process.getuid() : -1;
+  if (requireRootOwner && metadata.uid !== 0 || !requireRootOwner && metadata.uid !== 0 && metadata.uid !== caller) {
+    throw new MetalBootstrapError(requireRootOwner ? "private bootstrap file must be root-owned" : "private bootstrap file has an unexpected owner");
+  }
+}
+function readMetalBootstrapConfig(path) {
+  validateOwnerOnlyPath(path, false);
+  const metadata = statSync(path);
+  if (metadata.size < 2 || metadata.size > MAX_CONFIG_BYTES)
+    throw new MetalBootstrapError("metal bootstrap config size is invalid");
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new MetalBootstrapError("metal bootstrap config is not valid JSON");
+  }
+  return validateMetalBootstrapConfig(parsed);
+}
+function planMetalBootstrap(config) {
+  validateMetalBootstrapConfig(config);
+  return {
+    kind: "metal",
+    metalHostname: config.metalHostname,
+    profilePath: PROFILE_PATH,
+    units: [
+      "forgezero-metal-helper.service",
+      "forgezero-agent-update-helper.service",
+      "forgezero-metal-agent-egress.service",
+      "forgezero-metal-agent.service"
+    ],
+    steps: [
+      "install fixed KVM/LVM/cloud-init/nftables prerequisites",
+      "verify bridge, volume group, pinned guest image, KVM and optional SEV device",
+      "install the published Agent binary and root-owned immutable metal profile",
+      "seal or generate the metal identity seed as a systemd credential",
+      "apply reviewed CPU/NUMA host and guest isolation",
+      "install helper, update, egress and identity-only Agent units",
+      "enable units and prove services, local sockets, egress policy and OTLP collector"
+    ],
+    requiresRoot: true,
+    consumes: config.agentSeedFile ? [config.agentSeedFile] : []
+  };
+}
+var atomicWrite = (path, body, mode) => {
+  mkdirSync2(dirname2(path), { recursive: true, mode: 493 });
+  const temporary = `${path}.next-${process.pid}`;
+  writeFileSync2(temporary, body, { mode, flag: "wx" });
+  chmodSync(temporary, mode);
+  chownSync(temporary, 0, 0);
+  renameSync(temporary, path);
+};
+var validateAgentSourcePath = (source) => {
+  if (!isAbsolute2(source) || !lstatSync(source).isFile() || lstatSync(source).isSymbolicLink()) {
+    throw new MetalBootstrapError("published Agent source path must be an absolute regular non-symlink file");
+  }
+};
+var ensureAccount = async (exec) => {
+  if ((await exec(["/usr/bin/getent", "group", "forgezero-metal"])).exitCode !== 0) {
+    await runChecked(exec, ["/usr/sbin/groupadd", "--system", "forgezero-metal"]);
+  }
+  if ((await exec(["/usr/bin/getent", "group", "forgezero-update"])).exitCode !== 0) {
+    await runChecked(exec, ["/usr/sbin/groupadd", "--system", "forgezero-update"]);
+  }
+  if ((await exec(["/usr/bin/id", "forgezero-metal"])).exitCode !== 0) {
+    await runChecked(exec, [
+      "/usr/sbin/useradd",
+      "--system",
+      "--no-create-home",
+      "--shell",
+      "/usr/sbin/nologin",
+      "--gid",
+      "forgezero-metal",
+      "forgezero-metal"
+    ]);
+  }
+  await runChecked(exec, ["/usr/sbin/usermod", "-a", "-G", "forgezero-update", "forgezero-metal"]);
+};
+function renderMetalUnits(config) {
+  validateMetalBootstrapConfig(config);
+  const egress = systemdAgentEgressDirectives([4318]);
+  const updateEgress = systemdAgentEgressDirectives();
+  return {
+    "forgezero-metal-helper.service": `[Unit]
+Description=ForgeZero constrained physical-host helper
+After=local-fs.target
+
+[Service]
+Type=simple
+User=root
+Group=forgezero-metal
+UMask=0007
+RuntimeDirectory=forgezero-metal
+RuntimeDirectoryMode=0770
+ExecStart=${AGENT_PATH} metal-helper --profile=${PROFILE_PATH}
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=10min
+LimitCORE=0
+PrivateTmp=true
+ProtectHome=true
+RestrictAddressFamilies=AF_UNIX
+
+[Install]
+WantedBy=multi-user.target
+`,
+    "forgezero-agent-update-helper.service": `[Unit]
+Description=ForgeZero verified Agent update helper
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+Group=forgezero-update
+Environment=FZ_AGENT_UPDATE_SOCKET=${UPDATE_SOCKET}
+ExecStart=${AGENT_PATH} update-helper
+Restart=always
+RestartSec=2
+RuntimeDirectory=forgezero-update
+RuntimeDirectoryMode=0750
+UMask=0007
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+ReadWritePaths=/opt/forgezero/agent /var/lib/forgezero
+${updateEgress}
+
+[Install]
+WantedBy=multi-user.target
+`,
+    "forgezero-metal-agent-egress.service": `[Unit]
+Description=ForgeZero physical Agent host egress policy
+After=systemd-resolved.service nftables.service
+Requires=systemd-resolved.service
+Before=forgezero-metal-agent.service
+
+[Service]
+Type=notify
+NotifyAccess=all
+User=root
+Group=root
+ExecStart=${AGENT_PATH} egress-policy --user=forgezero-metal --loopback-user=forgezero-metal --loopback-tcp-port=4318 --public-tcp-port=443
+Restart=on-failure
+RestartSec=2
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+CapabilityBoundingSet=CAP_NET_ADMIN
+RestrictAddressFamilies=AF_UNIX AF_NETLINK
+
+[Install]
+WantedBy=multi-user.target
+`,
+    "forgezero-metal-agent.service": `[Unit]
+Description=ForgeZero identity-only physical-host Agent
+After=network-online.target ${config.hostTelemetryUnit} forgezero-metal-helper.service forgezero-agent-update-helper.service forgezero-metal-agent-egress.service
+Wants=network-online.target ${config.hostTelemetryUnit}
+Requires=forgezero-metal-helper.service forgezero-agent-update-helper.service forgezero-metal-agent-egress.service
+BindsTo=forgezero-metal-agent-egress.service
+
+[Service]
+Type=simple
+User=forgezero-metal
+Group=forgezero-metal
+SupplementaryGroups=forgezero-update
+LoadCredentialEncrypted=metal-agent-seed:${SEED_CREDENTIAL_PATH}
+Environment=FZ_SEED_CREDENTIAL=metal-agent-seed
+Environment=FZ_AGENT_ROLE=metal
+Environment=FZ_METAL_HOSTNAME=${config.metalHostname}
+Environment=FZ_API=${config.profile.apiUrl}
+Environment=FZ_METAL_HELPER_SOCKET=${HELPER_SOCKET}
+Environment=FZ_DRAIN_DEADLINE_MS=120000
+Environment=NODE_ENV=production
+Environment=OTEL_EXPORTER_OTLP_ENDPOINT=${config.hostTelemetryEndpoint}
+Environment=OTEL_SERVICE_NAME=forgezero-metal-agent
+ExecStart=${AGENT_PATH}
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=130s
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+${egress}
+
+[Install]
+WantedBy=multi-user.target
+`
+  };
+}
+var installAgentBinary = (source, version) => {
+  validateAgentSourcePath(source);
+  const release = `/opt/forgezero/agent/versions/${version}/dist`;
+  mkdirSync2(release, { recursive: true, mode: 493 });
+  copyFileSync(source, join3(release, "fz-agent.js"));
+  chmodSync(join3(release, "fz-agent.js"), 493);
+  chownSync(join3(release, "fz-agent.js"), 0, 0);
+  mkdirSync2("/opt/forgezero/agent", { recursive: true, mode: 493 });
+  for (const [link, target] of [
+    ["/opt/forgezero/agent/current.next", `versions/${version}`],
+    [AGENT_PATH, "/opt/forgezero/agent/current/dist/fz-agent.js"]
+  ]) {
+    try {
+      unlinkSync(link);
+    } catch {}
+    symlinkSync(target, link);
+    if (link.endsWith("current.next"))
+      renameSync(link, "/opt/forgezero/agent/current");
+  }
+};
+var preflight = async (config, exec) => {
+  await runChecked(exec, ["/usr/bin/systemctl", "is-active", "--quiet", config.hostTelemetryUnit]);
+  await runChecked(exec, [
+    "/usr/bin/curl",
+    "--silent",
+    "--show-error",
+    "--fail",
+    "--max-time",
+    "5",
+    "--request",
+    "POST",
+    "--header",
+    "Content-Type: application/json",
+    "--data-binary",
+    "{}",
+    `${config.hostTelemetryEndpoint}/v1/metrics`
+  ]);
+  await runChecked(exec, ["/usr/sbin/vgs", config.profile.volumeGroup]);
+  await runChecked(exec, ["/usr/sbin/ip", "link", "show", config.profile.bridge]);
+  if (!existsSync("/dev/kvm"))
+    throw new MetalBootstrapError("/dev/kvm is required");
+  if (config.profile.confidential) {
+    if (!existsSync("/dev/sev"))
+      throw new MetalBootstrapError("/dev/sev is required by the confidential profile");
+    await runChecked(exec, ["/usr/bin/qemu-system-x86_64", "-object", "sev-snp-guest,help"]);
+  }
+  const digest = (await runChecked(exec, ["/usr/bin/sha256sum", config.profile.images[Object.keys(config.profile.images)[0]].path])).stdout.split(/\s+/)[0];
+  if (digest !== config.profile.images[Object.keys(config.profile.images)[0]].sha256)
+    throw new MetalBootstrapError("pinned guest image digest mismatch");
+};
+var assertSupportedMetalHost = () => {
+  if (process.platform !== "linux" || process.arch !== "x64") {
+    throw new MetalBootstrapError("metal bootstrap supports only Ubuntu 26.04 x86_64 hosts");
+  }
+  const release = readFileSync("/etc/os-release", "utf8");
+  if (!/^ID=ubuntu$/m.test(release) || !/^VERSION_ID="?26\.04"?$/m.test(release)) {
+    throw new MetalBootstrapError("metal bootstrap supports only Ubuntu 26.04 x86_64 hosts");
+  }
+};
+var ensurePinnedGuestImage = async (config, exec) => {
+  const image = config.profile.images[SUPPORTED_GUEST_IMAGE.key];
+  if (existsSync(image.path))
+    return;
+  mkdirSync2(dirname2(image.path), { recursive: true, mode: 493 });
+  const temporary = `${image.path}.next-${process.pid}`;
+  try {
+    await runChecked(exec, [
+      "/usr/bin/curl",
+      "--fail",
+      "--location",
+      "--proto",
+      "=https",
+      "--tlsv1.2",
+      "--output",
+      temporary,
+      SUPPORTED_GUEST_IMAGE.url
+    ]);
+    const digest = (await runChecked(exec, ["/usr/bin/sha256sum", temporary])).stdout.split(/\s+/)[0];
+    if (digest !== image.sha256)
+      throw new MetalBootstrapError("downloaded guest image digest mismatch");
+    chmodSync(temporary, 292);
+    chownSync(temporary, 0, 0);
+    renameSync(temporary, image.path);
+  } catch (cause) {
+    try {
+      unlinkSync(temporary);
+    } catch {}
+    throw cause;
+  }
+};
+async function applyMetalBootstrap(config, options) {
+  validateMetalBootstrapConfig(config);
+  if ((options.getuid ?? process.getuid)?.() !== 0)
+    throw new MetalBootstrapError("fz bootstrap metal --apply must run as root");
+  assertSupportedMetalHost();
+  if (existsSync(STATE_PATH) && !options.repair)
+    throw new MetalBootstrapError("metal host is already initialized; use explicit repair");
+  if (config.agentSeedFile)
+    validateOwnerOnlyPath(config.agentSeedFile, true);
+  if (config.agentSeedFile && existsSync(SEED_CREDENTIAL_PATH)) {
+    throw new MetalBootstrapError("repair refuses replacement seed material while the sealed metal identity exists");
+  }
+  validateAgentSourcePath(options.agentSourcePath);
+  const exec = options.exec ?? defaultExec2;
+  await runChecked(exec, ["/usr/bin/apt-get", "update"]);
+  await runChecked(exec, [
+    "/usr/bin/apt-get",
+    "install",
+    "-y",
+    "--no-install-recommends",
+    "qemu-system-x86",
+    "qemu-utils",
+    "cloud-image-utils",
+    "lvm2",
+    "nftables",
+    "curl"
+  ]);
+  await ensurePinnedGuestImage(config, exec);
+  await preflight(config, exec);
+  await ensureAccount(exec);
+  installAgentBinary(options.agentSourcePath, config.profile.agentVersion);
+  mkdirSync2("/etc/forgezero/creds", { recursive: true, mode: 448 });
+  mkdirSync2(config.profile.stateDir, { recursive: true, mode: 448 });
+  mkdirSync2(config.profile.seedDir, { recursive: true, mode: 448 });
+  const persistedProfile = {
+    ...config.profile,
+    metalHostname: config.metalHostname,
+    hostTelemetryEndpoint: config.hostTelemetryEndpoint,
+    hostTelemetryUnit: config.hostTelemetryUnit
+  };
+  atomicWrite(PROFILE_PATH, `${JSON.stringify(persistedProfile, null, 2)}
+`, 384);
+  if (!existsSync(SEED_CREDENTIAL_PATH)) {
+    const seed = config.agentSeedFile ? readFileSync(config.agentSeedFile, "utf8").trim() : randomBytes(32).toString("base64url");
+    if (seed.length < 32 || /[\0\r\n]/.test(seed))
+      throw new MetalBootstrapError("metal Agent seed is invalid");
+    await runChecked(exec, ["/usr/bin/systemd-creds", "encrypt", "--name=metal-agent-seed", "-", SEED_CREDENTIAL_PATH], `${seed}
+`);
+    chmodSync(SEED_CREDENTIAL_PATH, 256);
+    chownSync(SEED_CREDENTIAL_PATH, 0, 0);
+    if (config.agentSeedFile)
+      unlinkSync(config.agentSeedFile);
+  }
+  await applyMetalIsolation(config.profile, (argv) => exec(argv));
+  for (const [unit, body] of Object.entries(renderMetalUnits(config)))
+    atomicWrite(join3(UNIT_DIRECTORY, unit), body, 420);
+  await runChecked(exec, ["/usr/bin/systemctl", "daemon-reload"]);
+  await runChecked(exec, [
+    "/usr/bin/systemctl",
+    "enable",
+    "--now",
+    "forgezero-agent-update-helper.service",
+    "forgezero-metal-helper.service",
+    "forgezero-metal-agent-egress.service",
+    "forgezero-metal-agent.service"
+  ]);
+  for (let attempt = 0;attempt < 100 && (!socketReady(HELPER_SOCKET) || !socketReady(UPDATE_SOCKET)); attempt += 1) {
+    await Bun.sleep(100);
+  }
+  const status = await metalBootstrapStatus(exec);
+  const operationalProblems = options.repair ? status.problems.filter((problem) => problem !== "metal initialized state does not bind the current profile") : status.problems;
+  if (operationalProblems.length)
+    throw new MetalBootstrapError(`metal bootstrap verification failed: ${operationalProblems.join("; ")}`);
+  const identity = await runChecked(exec, [
+    "/usr/bin/systemd-run",
+    "--pipe",
+    "--wait",
+    "--quiet",
+    "--collect",
+    `--property=LoadCredentialEncrypted=metal-agent-seed:${SEED_CREDENTIAL_PATH}`,
+    "--setenv=FZ_SEED_CREDENTIAL=metal-agent-seed",
+    AGENT_PATH,
+    "identity"
+  ]);
+  const publicIdentity = identity.stdout.trim();
+  if (!publicIdentity || /[\r\n]/.test(publicIdentity))
+    throw new MetalBootstrapError("metal public identity proof was invalid");
+  const state = {
+    initializedAt: new Date().toISOString(),
+    role: "metal",
+    metalHostname: config.metalHostname,
+    profileSha256: createHash("sha256").update(JSON.stringify(config.profile)).digest("hex")
+  };
+  atomicWrite(STATE_PATH, `${JSON.stringify(state, null, 2)}
+`, 384);
+  return { ...status, initialized: true, problems: [], metalHostname: config.metalHostname, publicIdentity };
+}
+var socketReady = (path) => {
+  try {
+    return lstatSync(path).isSocket();
+  } catch {
+    return false;
+  }
+};
+async function metalBootstrapStatus(exec = defaultExec2) {
+  const problems = [];
+  let profileValid = false, imageVerified = false, metalHostname, profileSha256;
+  let profileMode = null;
+  if (existsSync(PROFILE_PATH)) {
+    try {
+      const metadata = statSync(PROFILE_PATH);
+      profileMode = metadata.mode & 511;
+      if (profileMode !== 384 || metadata.uid !== 0)
+        problems.push("metal profile is not root-owned mode 0600");
+      const persisted = JSON.parse(readFileSync(PROFILE_PATH, "utf8"));
+      const { metalHostname: profileHostname, hostTelemetryEndpoint, hostTelemetryUnit, ...profile } = persisted;
+      validateMetalProfile(profile);
+      profileValid = true;
+      profileSha256 = createHash("sha256").update(JSON.stringify(profile)).digest("hex");
+      if (!/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(profileHostname) || hostTelemetryEndpoint !== "http://127.0.0.1:4318") {
+        problems.push("persisted metal host coordinates are invalid");
+      }
+      try {
+        validUnit(hostTelemetryUnit);
+      } catch {
+        problems.push("persisted metal OTLP collector unit is invalid");
+      }
+      if ((await exec(["/usr/bin/systemctl", "is-active", "--quiet", hostTelemetryUnit])).exitCode !== 0) {
+        problems.push(`${hostTelemetryUnit} is inactive`);
+      } else if ((await exec([
+        "/usr/bin/curl",
+        "--silent",
+        "--show-error",
+        "--fail",
+        "--max-time",
+        "5",
+        "--request",
+        "POST",
+        "--header",
+        "Content-Type: application/json",
+        "--data-binary",
+        "{}",
+        `${hostTelemetryEndpoint}/v1/metrics`
+      ])).exitCode !== 0) {
+        problems.push("local OTLP metrics receiver did not accept a proof request");
+      }
+      const image = profile.images[Object.keys(profile.images)[0]];
+      if (existsSync(image.path)) {
+        const digest = (await exec(["/usr/bin/sha256sum", image.path])).stdout.split(/\s+/)[0];
+        imageVerified = digest === image.sha256;
+      }
+      if (!imageVerified)
+        problems.push("pinned guest image is absent or has the wrong digest");
+    } catch (cause) {
+      problems.push(`metal profile invalid: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+  } else
+    problems.push("metal profile is missing");
+  if (existsSync(STATE_PATH)) {
+    try {
+      const state = JSON.parse(readFileSync(STATE_PATH, "utf8"));
+      metalHostname = state.metalHostname;
+      if (state.role !== "metal" || !metalHostname || state.profileSha256 !== profileSha256) {
+        problems.push("metal initialized state does not bind the current profile");
+      }
+    } catch {
+      problems.push("metal initialized state is invalid");
+    }
+  }
+  const units = {};
+  for (const unit of [
+    "forgezero-metal-helper.service",
+    "forgezero-agent-update-helper.service",
+    "forgezero-metal-agent-egress.service",
+    "forgezero-metal-agent.service"
+  ]) {
+    if (!existsSync(join3(UNIT_DIRECTORY, unit)))
+      units[unit] = "missing";
+    else
+      units[unit] = (await exec(["/usr/bin/systemctl", "is-active", "--quiet", unit])).exitCode === 0 ? "active" : "inactive";
+    if (units[unit] !== "active")
+      problems.push(`${unit} is ${units[unit]}`);
+  }
+  const helperSocketReady = socketReady(HELPER_SOCKET);
+  const updateSocketReady = socketReady(UPDATE_SOCKET);
+  if (!helperSocketReady)
+    problems.push("metal helper socket is not ready");
+  if (!updateSocketReady)
+    problems.push("Agent update helper socket is not ready");
+  return {
+    initialized: existsSync(STATE_PATH),
+    profileValid,
+    profileMode,
+    imageVerified,
+    units,
+    helperSocketReady,
+    updateSocketReady,
+    metalHostname,
+    problems
+  };
+}
+export {
+  validateOwnerOnlyPath,
+  validateMetalBootstrapConfig,
+  renderMetalUnits,
+  readMetalBootstrapConfig,
+  planMetalBootstrap,
+  metalBootstrapStatus,
+  applyMetalBootstrap,
+  MetalBootstrapError
+};