@forgezero/agent 0.1.35 → 0.1.36

package/README.md

@@ -36,6 +36,35 @@ Install the service explicitly:
 fz agent install --apply         # writes a hardened systemd unit
 ```
 
+## Host bootstrap
+
+The package is also the host installer. There is no separate shell setup
+script and no second implementation for tenant or platform machines:
+
+```bash
+fz bootstrap platform                         # interactive plan, no mutation
+sudo fz bootstrap platform --apply            # initial DB+API or API-only host
+sudo fz bootstrap tenant --bootstrap-config ./tenant.json --apply
+sudo fz bootstrap metal --bootstrap-config ./metal.json --apply
+sudo fz bootstrap status
+sudo fz bootstrap repair --bootstrap-config ./original.json --apply
+```
+
+Platform bootstrap supports an elastic Community ArangoDB 3.11.14 fleet. The
+first three database-capable computes establish the writable cluster; later
+database joiners and API-only computes use the same command with their typed
+profile and an API-issued one-time enrolment file. Nothing treats three as a
+maximum.
+
+After genesis, a tenant can designate an enrolled compute as a bootstrap
+runner. The API creates a project-bound, expiring job containing only public
+SSH coordinates and a pinned Ed25519 host-key fingerprint. The runner claims it
+with its hybrid node identity, reads its SSH key only from a local systemd
+credential, pins one vetted DNS answer, transfers this packaged CLI, and runs
+the same `fz bootstrap tenant` flow on the target. Claim renewal, completion,
+retry and cancellation are fenced in the compute aggregate; the API never
+stores the SSH private key or a plaintext enrolment token.
+
 The attended Cloudflare resource phase is part of the same published command,
 but remains separate from the root host install so its management token never
 enters the API or Agent service environment:

package/dist/agent-heartbeat.js

@@ -744,7 +744,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.35";
+var VERSION3 = "0.1.36";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap.d.ts

@@ -68,6 +68,11 @@ export interface TenantBootstrapConfig {
     deployRoot?: string;
     software?: SoftwareRequirement[];
     installCloudflared?: boolean;
+    /** Local-only runner authority. The API receives only the resulting node scope. */
+    bootstrapRunner?: {
+        sshPrivateKeyFile: string;
+        targetTelemetryEndpoint: string;
+    };
 }
 export type BootstrapConfig = PlatformBootstrapConfig | TenantBootstrapConfig;
 export interface BootstrapStep {

package/dist/bootstrap.js

@@ -1214,7 +1214,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.35";
+var VERSION = "0.1.36";
 
 // src/software.ts
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
@@ -1245,6 +1245,11 @@ var UBUNTU_2604_X64 = [
     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"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 
@@ -1786,7 +1791,12 @@ function agentUnit(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -1852,6 +1862,9 @@ function agentUnit(options) {
     options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
     options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null,
     options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_PULL=true" : null,
+    options.pullBootstrap ? "FZ_BOOTSTRAP_SSH_KEY_CREDENTIAL=bootstrap-ssh-key" : null,
+    options.pullBootstrap ? `FZ_BOOTSTRAP_TARGET_OTLP_ENDPOINT=${options.bootstrapTargetTelemetryEndpoint}` : null,
     `FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}`,
     options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
   ].filter((line) => line !== null);
@@ -1859,6 +1872,8 @@ function agentUnit(options) {
     environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
   }
   const gitCredential = options.gitCredentialPath ? `LoadCredentialEncrypted=git-deploy-key:${options.gitCredentialPath}
+` : "";
+  const bootstrapCredential = bootstrapEnabled ? `LoadCredentialEncrypted=bootstrap-ssh-key:${bootstrapSshCredentialPath}
 ` : "";
   const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
 `);
@@ -1913,7 +1928,7 @@ User=${user}
 Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
-${gitCredential}${projectCredentials}${projectCredentials ? `
+${gitCredential}${bootstrapCredential}${projectCredentials}${projectCredentials ? `
 ` : ""}${snpPrepare}ExecStart=${bin}
 Restart=always
 RestartSec=2
@@ -1968,6 +1983,10 @@ function planProvision(options) {
   if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
     throw new Error("migration pull and lifecycle profile must be supplied together");
   }
+  const bootstrapEnabled = Boolean(options.pullBootstrap && options.bootstrapSshCredentialPath && options.bootstrapTargetTelemetryEndpoint);
+  if ([options.pullBootstrap, options.bootstrapSshCredentialPath, options.bootstrapTargetTelemetryEndpoint].some(Boolean) && !bootstrapEnabled) {
+    throw new Error("bootstrap pull, SSH credential and target telemetry endpoint must be supplied together");
+  }
   const warpValues = [
     options.warpOrganization,
     options.warpClientIdCredentialPath,
@@ -1993,13 +2012,20 @@ function planProvision(options) {
   const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
   const lifecycleProfilePath = lifecycleEnabled ? systemdPath(options.lifecycleProfilePath, "lifecycle profile") : undefined;
   const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const bootstrapSshCredentialPath = bootstrapEnabled ? systemdPath(options.bootstrapSshCredentialPath, "bootstrap SSH credential") : undefined;
   const warpClientIdCredentialPath = warpEnabled ? systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential") : undefined;
   const warpClientSecretCredentialPath = warpEnabled ? systemdPath(options.warpClientSecretCredentialPath, "WARP client-secret credential") : undefined;
   return {
     mode,
     reason: reasonFor(mode),
     unitPath: UNIT_PATH,
-    unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
+    unit: agentUnit({
+      ...options,
+      mode,
+      lifecycleProfilePath,
+      lifecycleHelperSocketPath,
+      bootstrapSshCredentialPath
+    }),
     auxiliaryUnits: [
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
@@ -2600,6 +2626,7 @@ var SEED_CREDENTIAL = `${CREDS}/seed-sync-root.cred`;
 var BACKUP_RECOVERY_CREDENTIAL = `${CREDS}/backup-recovery-root.cred`;
 var WARP_CLIENT_ID_CREDENTIAL = `${CREDS}/warp-auth-client-id.cred`;
 var WARP_CLIENT_SECRET_CREDENTIAL = `${CREDS}/warp-auth-client-secret.cred`;
+var BOOTSTRAP_SSH_CREDENTIAL = `${CREDS}/bootstrap-ssh-key.cred`;
 var PLATFORM_ENROL_SOURCE = "/run/forgezero-platform-enrol-token";
 var DB_MODE_EVIDENCE = "/var/lib/forgezero-cluster/server-mode.json";
 var LIFECYCLE_PROFILE = "/etc/forgezero/lifecycle.json";
@@ -2662,6 +2689,20 @@ function validateBootstrapConfig(value) {
     }
     if (!value.enrolTokenFile)
       throw new Error("tenant bootstrap requires --enrol-token-file");
+    if (value.bootstrapRunner) {
+      if (!value.bootstrapRunner.sshPrivateKeyFile.startsWith("/") || /[\r\n]/.test(value.bootstrapRunner.sshPrivateKeyFile)) {
+        throw new Error("bootstrap runner SSH private-key file must be absolute");
+      }
+      let targetTelemetry;
+      try {
+        targetTelemetry = new URL(value.bootstrapRunner.targetTelemetryEndpoint);
+      } catch {
+        throw new Error("bootstrap target telemetry endpoint is malformed");
+      }
+      if (targetTelemetry.protocol !== "https:" || targetTelemetry.username || targetTelemetry.password || targetTelemetry.search || targetTelemetry.hash || targetTelemetry.port && targetTelemetry.port !== "443") {
+        throw new Error("bootstrap target telemetry must be public HTTPS on port 443");
+      }
+    }
     return value;
   }
   if (!PLATFORM_BOOTSTRAP_PROFILES.includes(value.profile))
@@ -2723,7 +2764,11 @@ function validateBootstrapConfig(value) {
 }
 function planBootstrap(input, initialized = false) {
   const config = validateBootstrapConfig(structuredClone(input));
-  const software = config.kind === "tenant" ? [...config.software ?? [], ...config.installCloudflared ? [{ id: "cloudflared", version: "2026.7.3" }] : []] : [
+  const software = config.kind === "tenant" ? [
+    ...config.software ?? [],
+    ...config.bootstrapRunner && !config.software?.some(({ id }) => id === "openssh-client") ? [{ id: "openssh-client", version: "ubuntu-26.04" }] : [],
+    ...config.installCloudflared ? [{ id: "cloudflared", version: "2026.7.3" }] : []
+  ] : [
     ...config.firewall.enabled ? [{ id: "ufw", version: "ubuntu-26.04" }] : [],
     { id: "bun", version: "1.3.14" },
     { id: "nginx", version: "ubuntu-26.04" },
@@ -2958,6 +3003,10 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
   const alreadyEnrolled = host.exists("/var/lib/forgezero/enrolment.json");
   host.mkdir(CREDS, 448);
   host.mkdir("/var/lib/forgezero", 448);
+  if (config.kind === "tenant" && config.bootstrapRunner && !host.exists(BOOTSTRAP_SSH_CREDENTIAL)) {
+    await seal(host, "bootstrap-ssh-key", BOOTSTRAP_SSH_CREDENTIAL, privateFile(host, config.bootstrapRunner.sshPrivateKeyFile, "bootstrap runner SSH private key"));
+    host.remove(config.bootstrapRunner.sshPrivateKeyFile);
+  }
   if (cloudflare?.warp) {
     await seal(host, "warp-auth-client-id", WARP_CLIENT_ID_CREDENTIAL, cloudflare.warp.clientId);
     await seal(host, "warp-auth-client-secret", WARP_CLIENT_SECRET_CREDENTIAL, cloudflare.warp.clientSecret);
@@ -3157,7 +3206,8 @@ function strictBootstrapDocument(value) {
     "cloudflareHandoff",
     "realm",
     "enrolTokenFile",
-    "software"
+    "software",
+    "bootstrapRunner"
   ], "bootstrap config");
   if (root.kind === "platform") {
     exactKeys(root.firewall, ["enabled", "sshPort", "privateCidrs"], "firewall config");
@@ -3222,6 +3272,8 @@ function strictBootstrapDocument(value) {
       exactKeys(environment.cloudflare.warp, ["organization", "virtualNetworkId", "deviceProfileId"], "Cloudflare WARP runtime config");
     }
   } else if (root.kind === "tenant") {
+    if (root.bootstrapRunner !== undefined)
+      exactKeys(root.bootstrapRunner, ["sshPrivateKeyFile", "targetTelemetryEndpoint"], "bootstrap runner config");
     for (const key of ["environment", "profile", "computeReference", "database", "platformEnrolTokenFile", "runtime", "cloudflareHandoff"]) {
       if (root[key] !== undefined && key !== "profile")
         throw new Error(`tenant bootstrap cannot contain ${key}`);
@@ -3316,6 +3368,9 @@ function localBootstrapHost() {
         generateGitIdentity: true,
         pullDeployments: true,
         pullMigrations: config.kind === "platform",
+        pullBootstrap: config.kind === "tenant" && Boolean(config.bootstrapRunner),
+        bootstrapSshCredentialPath: config.kind === "tenant" && config.bootstrapRunner ? BOOTSTRAP_SSH_CREDENTIAL : undefined,
+        bootstrapTargetTelemetryEndpoint: config.kind === "tenant" ? config.bootstrapRunner?.targetTelemetryEndpoint : undefined,
         lifecycleProfilePath: config.kind === "platform" ? LIFECYCLE_PROFILE : undefined,
         ...config.kind === "platform" && config.runtime.environment.cloudflare?.warp ? {
           warpOrganization: config.runtime.environment.cloudflare.warp.organization,

package/dist/cli/agent-install.d.ts

@@ -56,6 +56,9 @@ export interface InstallOptions {
     runnerLoopbackPorts?: readonly number[];
     runnerPublicTcpPorts?: readonly number[];
     pullMigrations?: boolean;
+    pullBootstrap?: boolean;
+    bootstrapSshCredentialPath?: string;
+    bootstrapTargetTelemetryEndpoint?: string;
     lifecycleProfilePath?: string;
     lifecycleHelperSocketPath?: string;
     warpOrganization?: string;

package/dist/definition.js

@@ -1,5 +1,6 @@
 // src/software.ts
 import { readFileSync } from "node:fs";
+var PINNED_BUN_VERSION = "1.3.14";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -11,7 +12,8 @@ var SOFTWARE_CATALOG = [
   { 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" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -38,6 +40,11 @@ var UBUNTU_2604_X64 = [
     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"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -62,7 +69,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", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "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/deploy-file.js

@@ -1,5 +1,6 @@
 // src/software.ts
 import { readFileSync } from "node:fs";
+var PINNED_BUN_VERSION = "1.3.14";
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
 var ARANGO_SHA256 = "b5a9197b4343f2ed554e1ebc1ef8e6529c7c39cde0035cdc311a4747a3355066";
 var CLOUDFLARED_SHA256 = "9d71c677db00134c1bd4144b7783486b654ad281b1ea62b4972098d19f770f17";
@@ -11,7 +12,8 @@ var SOFTWARE_CATALOG = [
   { 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" },
-  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
+  { id: "ufw", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" },
+  { id: "openssh-client", version: "ubuntu-26.04", status: "active", os: "ubuntu", osVersion: "26.04", architecture: "x64", evidence: "reviewed-strategy-and-tests" }
 ];
 var UBUNTU_2604_X64 = [
   {
@@ -38,6 +40,11 @@ var UBUNTU_2604_X64 = [
     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"
+  },
+  {
+    requirement: { id: "openssh-client", version: "ubuntu-26.04" },
+    check: "command -v ssh >/dev/null && command -v scp >/dev/null && command -v ssh-keyscan >/dev/null && command -v ssh-keygen >/dev/null",
+    install: "DEBIAN_FRONTEND=noninteractive apt-get update -qq && apt-get install -y openssh-client"
   }
 ];
 function observeSoftwareHost(osRelease = readFileSync("/etc/os-release", "utf8"), architecture = process.arch) {
@@ -62,7 +69,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", "ufw"].includes(String(row.id)) || typeof row.version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,31}$/.test(row.version)) {
+    if (!["bun", "nginx", "arangodb", "cloudflared", "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 };