@forgezero/agent 0.1.85 → 0.1.87

package/dist/guest-enrolment.js

@@ -22,9 +22,11 @@ import {
 
 class SignedNodeHttpError extends Error {
   status;
-  constructor(status, message) {
+  code;
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "SignedNodeHttpError";
   }
 }
@@ -71,7 +73,7 @@ async function postSignedNode(options, path, body) {
   if (!response.ok) {
     const failure = payload;
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
-    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`, failure?.error?.code);
   }
   try {
     return await openResponse(recipient.secretKey, signature, payload);

package/dist/metal-bootstrap.js

@@ -366,7 +366,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.85";
+var VERSION = "0.1.87";
 
 // src/otel-collector.ts
 var FORGEZERO_OTEL_COLLECTOR_UNIT = "forgezero-otel-collector.service";
@@ -705,6 +705,7 @@ function planMetalBootstrap(config) {
       "forgezero-metal-helper.service",
       "forgezero-agent-update-helper.service",
       "forgezero-metal-agent-egress.service",
+      "forgezero-metal-agent-candidate.service",
       "forgezero-metal-agent.service"
     ],
     steps: [
@@ -846,6 +847,44 @@ RestrictAddressFamilies=AF_UNIX AF_NETLINK
 
 [Install]
 WantedBy=multi-user.target
+`,
+    "forgezero-metal-agent-candidate.service": `[Unit]
+Description=ForgeZero candidate physical-host Agent
+After=network-online.target ${config.hostTelemetryUnit} forgezero-agent-update-helper.service forgezero-metal-agent-egress.service
+Requires=forgezero-agent-update-helper.service 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_AGENT_HANDOVER_CANDIDATE=true
+Environment=FZ_AGENT_HANDOVER_READY_SOCKET=/run/forgezero/candidate-ready.sock
+Environment=FZ_METAL_HOSTNAME=${config.metalHostname}
+Environment=FZ_API=${config.profile.apiUrl}
+Environment=NODE_ENV=production
+Environment=OTEL_EXPORTER_OTLP_ENDPOINT=${config.hostTelemetryEndpoint}
+Environment=OTEL_SERVICE_NAME=forgezero-metal-agent-candidate
+ExecStart=/opt/forgezero/agent/candidate/dist/fz-agent.js
+Restart=on-failure
+RestartSec=2
+RuntimeDirectory=forgezero
+RuntimeDirectoryMode=0750
+RuntimeDirectoryPreserve=yes
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+${egress}
 `,
     "forgezero-metal-agent.service": `[Unit]
 Description=ForgeZero identity-only physical-host Agent

package/dist/migration-pull.js

@@ -9,9 +9,11 @@ import {
 
 class SignedNodeHttpError extends Error {
   status;
-  constructor(status, message) {
+  code;
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "SignedNodeHttpError";
   }
 }
@@ -58,7 +60,7 @@ async function postSignedNode(options, path, body) {
   if (!response.ok) {
     const failure = payload;
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
-    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`, failure?.error?.code);
   }
   try {
     return await openResponse(recipient.secretKey, signature, payload);

package/dist/node-vault.js

@@ -129,9 +129,11 @@ import {
 
 class SignedNodeHttpError extends Error {
   status;
-  constructor(status, message) {
+  code;
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code;
     this.name = "SignedNodeHttpError";
   }
 }
@@ -178,7 +180,7 @@ async function postSignedNode(options, path, body) {
   if (!response.ok) {
     const failure = payload;
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
-    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`, failure?.error?.code);
   }
   try {
     return await openResponse(recipient.secretKey, signature, payload);
@@ -216,8 +218,17 @@ function tenantNodeApiUrl(apiUrl, tenantSlug) {
   return url.toString().replace(/\/$/, "");
 }
 function createNodeVaultCache(options) {
-  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
-  return createSecretCache({
+  let cache;
+  const post = async (operation, body) => {
+    try {
+      return await postSignedNode(options, `v1/node/vault/${operation}`, body);
+    } catch (cause) {
+      if (cause instanceof SignedNodeHttpError && cause.code === "VAULT_API_ONLY")
+        cache?.clear();
+      throw cause;
+    }
+  };
+  cache = createSecretCache({
     ttlMs: options.ttlMs,
     maxStaleMs: options.maxStaleMs,
     list: async () => {
@@ -246,6 +257,7 @@ function createNodeVaultCache(options) {
       };
     }
   });
+  return cache;
 }
 function startNodeVaultSync(cache, options = {}) {
   const interval = Math.max(1000, options.intervalMs ?? 30000);

package/dist/operator-bootstrap.js

@@ -1405,9 +1405,13 @@ import { DEFAULT_SOCKET } from "@forgezero/vault";
 
 // src/agent-update.ts
 var DEFAULT_AGENT_RELEASE_ROOT = "/opt/forgezero/agent";
+var DEFAULT_AGENT_CANDIDATE_LINK = `${DEFAULT_AGENT_RELEASE_ROOT}/candidate`;
 var DEFAULT_AGENT_UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
 var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
 
+// src/agent-handover.ts
+var DEFAULT_AGENT_CANDIDATE_READY_SOCKET = "/run/forgezero/candidate-ready.sock";
+
 // src/agent-update-helper.ts
 var AGENT_UPDATE_GROUP = "forgezero-update";
 var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
@@ -1416,7 +1420,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.85";
+var VERSION = "0.1.87";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -1674,6 +1678,7 @@ var LIFECYCLE_GROUP = "forgezero-lifecycle";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 var AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
 var AGENT_SOCKET_PROXY_UNIT_PATH = "/etc/systemd/system/forgezero-agent-proxy.service";
+var AGENT_CANDIDATE_UNIT_PATH = "/etc/systemd/system/forgezero-agent-candidate.service";
 var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 var LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
@@ -1785,6 +1790,7 @@ Type=simple
 User=root
 Group=${AGENT_UPDATE_GROUP}
 Environment=FZ_AGENT_UPDATE_SOCKET=${DEFAULT_AGENT_UPDATE_SOCKET}
+Environment=FZ_AGENT_PUBLIC_SOCKET=${systemdPath(options.socketPath, "agent socket")}
 ExecStart=${bin} update-helper
 Restart=always
 RestartSec=2
@@ -1829,13 +1835,11 @@ WantedBy=sockets.target
 `;
 }
 function agentSocketProxyUnit(options) {
-  const backend = agentBackendSocketPath(options.socketPath);
+  const backend = agentRoutingSocketPath(options.socketPath);
   const user = options.user ?? "forgezero";
   return `[Unit]
 Description=ForgeZero application Vault socket proxy
 Documentation=https://www.forgezero.net/docs/agent
-Requires=forgezero-agent.service
-After=forgezero-agent.service
 
 [Service]
 User=${user}
@@ -1856,12 +1860,26 @@ RestrictAddressFamilies=AF_UNIX
 `;
 }
 function agentBackendSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend.active`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
+function agentRoutingSocketPath(publicSocketPath) {
   const socket = systemdPath(publicSocketPath, "agent socket");
   const backend = `${socket}.backend`;
   if (Buffer.byteLength(backend) > 100)
     throw new Error("agent socket path is too long for a Unix socket");
   return backend;
 }
+function agentCandidateSocketPath(publicSocketPath) {
+  const socket = systemdPath(publicSocketPath, "agent socket");
+  const backend = `${socket}.backend.candidate`;
+  if (Buffer.byteLength(backend) > 100)
+    throw new Error("agent socket path is too long for a Unix socket");
+  return backend;
+}
 var systemdPath = (value, label) => {
   if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
     throw new Error(`invalid ${label} path`);
@@ -2145,7 +2163,11 @@ function agentUnit(options) {
   }
   const environment = [
     "NODE_ENV=production",
-    `FZ_SOCKET_PATH=${agentBackendSocketPath(options.socketPath)}`,
+    `FZ_SOCKET_PATH=${options.backendSocketPath ?? agentBackendSocketPath(options.socketPath)}`,
+    `FZ_AGENT_PUBLIC_SOCKET=${options.socketPath}`,
+    `FZ_AGENT_ROUTE_SOCKET=${agentRoutingSocketPath(options.socketPath)}`,
+    options.handoverCandidate ? "FZ_AGENT_HANDOVER_CANDIDATE=true" : null,
+    options.handoverCandidate ? `FZ_AGENT_HANDOVER_READY_SOCKET=${DEFAULT_AGENT_CANDIDATE_READY_SOCKET}` : null,
     `FZ_CONTROL_SOCKET=${controlSocketPath}`,
     `FZ_SEED_CREDENTIAL=agent-seed`,
     `FZ_AGENT_MODE=${options.mode}`,
@@ -2282,6 +2304,26 @@ ${deploymentWrites}
 WantedBy=multi-user.target
 `;
 }
+function agentCandidateUnit(options) {
+  return agentUnit({
+    ...options,
+    binPath: `${DEFAULT_AGENT_RELEASE_ROOT}/candidate/dist/fz-agent.js`,
+    backendSocketPath: agentCandidateSocketPath(options.socketPath),
+    handoverCandidate: true,
+    gitCredentialPath: undefined,
+    deploymentCredentials: {},
+    bootstrapSshCredentialPath: undefined,
+    bootstrapSshPublicKeyPath: undefined,
+    pullBootstrap: false,
+    pullDeployments: false,
+    pullMigrations: false,
+    lifecycleProfilePath: undefined,
+    bootstrapTargetTelemetryEndpoint: undefined,
+    repository: undefined,
+    bootstrapBundlePath: undefined,
+    bootstrapBundleManifestPath: undefined
+  }).replace("Description=ForgeZero node agent", "Description=ForgeZero candidate node agent");
+}
 var renderOperation = (operation) => {
   if (operation.kind === "commands")
     return operation.commands.map(({ argv }) => argv.join(" ")).join(`
@@ -2417,6 +2459,7 @@ function planProvision(options) {
     auxiliaryUnits: [
       { path: AGENT_SOCKET_UNIT_PATH, unit: agentSocketUnit(options) },
       { path: AGENT_SOCKET_PROXY_UNIT_PATH, unit: agentSocketProxyUnit(options) },
+      { path: AGENT_CANDIDATE_UNIT_PATH, unit: agentCandidateUnit(options) },
       { path: AGENT_UPDATE_HELPER_UNIT_PATH, unit: agentUpdateHelperUnit(options) },
       ...options.enforceEgress ? [
         { path: AGENT_EGRESS_UNIT_PATH, unit: agentEgressUnit(options) }
@@ -3002,12 +3045,14 @@ var httpsOrigin = (name, raw) => {
   return value.origin;
 };
 function validatePlatformInitialInventory(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["metalHostname", "region", "computes"].includes(key)) || !/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(value.metalHostname) || !value.region || typeof value.region !== "object" || Array.isArray(value.region) || Object.keys(value.region).some((key) => !["key", "label", "country", "city", "confidentialCapable"].includes(key)) || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.region.key) || !/^[A-Z]{2}$/.test(value.region.country) || value.region.confidentialCapable !== true || !Array.isArray(value.computes)) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["metalHostname", "region", "computes", "deployment"].includes(key)) || !/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(value.metalHostname) || !value.region || typeof value.region !== "object" || Array.isArray(value.region) || Object.keys(value.region).some((key) => !["key", "label", "country", "city", "confidentialCapable"].includes(key)) || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.region.key) || !/^[A-Z]{2}$/.test(value.region.country) || value.region.confidentialCapable !== true || !Array.isArray(value.computes)) {
     throw new Error("initial platform inventory coordinates are invalid");
   }
   safeAtom("initialInventory.region.label", value.region.label);
   if (value.region.city !== undefined)
     safeAtom("initialInventory.region.city", value.region.city);
+  if (value.deployment !== undefined && (!value.deployment || typeof value.deployment !== "object" || Array.isArray(value.deployment) || Object.keys(value.deployment).some((key) => !["source", "branch", "revision", "bundleSha256"].includes(key)) || value.deployment.source !== "bootstrap-bundle" || !["dev", "main"].includes(value.deployment.branch) || !/^[a-f0-9]{40}$/.test(value.deployment.revision) || !/^[a-f0-9]{64}$/.test(value.deployment.bundleSha256)))
+    throw new Error("initial platform deployment evidence is invalid");
   const computes = validatePlatformGenesisGuests(value.computes.map((compute) => {
     if (!compute || typeof compute !== "object" || Array.isArray(compute) || Object.keys(compute).some((key) => ![
       "name",
@@ -3042,7 +3087,8 @@ function validatePlatformInitialInventory(value) {
       databaseRole: compute.databaseRole,
       databaseAgency: compute.databaseAgency,
       confidential: true
-    }))
+    })),
+    ...value.deployment ? { deployment: { ...value.deployment } } : {}
   };
 }
 var systemdValue = (name, raw) => {
@@ -4770,8 +4816,10 @@ function strictBootstrapDocument(value) {
     ], "runtime environment");
     const environment = runtime.environment;
     if (environment.initialInventory !== undefined) {
-      const inventory = exactKeys(environment.initialInventory, ["metalHostname", "region", "computes"], "initial inventory");
+      const inventory = exactKeys(environment.initialInventory, ["metalHostname", "region", "computes", "deployment"], "initial inventory");
       exactKeys(inventory.region, ["key", "label", "country", "city", "confidentialCapable"], "initial inventory region");
+      if (inventory.deployment !== undefined)
+        exactKeys(inventory.deployment, ["source", "branch", "revision", "bundleSha256"], "initial deployment evidence");
       if (!Array.isArray(inventory.computes))
         throw new Error("initial inventory computes must be an array");
       for (const compute of inventory.computes)
@@ -5392,6 +5440,7 @@ function planMetalBootstrap(config) {
       "forgezero-metal-helper.service",
       "forgezero-agent-update-helper.service",
       "forgezero-metal-agent-egress.service",
+      "forgezero-metal-agent-candidate.service",
       "forgezero-metal-agent.service"
     ],
     steps: [
@@ -5533,6 +5582,44 @@ RestrictAddressFamilies=AF_UNIX AF_NETLINK
 
 [Install]
 WantedBy=multi-user.target
+`,
+    "forgezero-metal-agent-candidate.service": `[Unit]
+Description=ForgeZero candidate physical-host Agent
+After=network-online.target ${config.hostTelemetryUnit} forgezero-agent-update-helper.service forgezero-metal-agent-egress.service
+Requires=forgezero-agent-update-helper.service 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_AGENT_HANDOVER_CANDIDATE=true
+Environment=FZ_AGENT_HANDOVER_READY_SOCKET=/run/forgezero/candidate-ready.sock
+Environment=FZ_METAL_HOSTNAME=${config.metalHostname}
+Environment=FZ_API=${config.profile.apiUrl}
+Environment=NODE_ENV=production
+Environment=OTEL_EXPORTER_OTLP_ENDPOINT=${config.hostTelemetryEndpoint}
+Environment=OTEL_SERVICE_NAME=forgezero-metal-agent-candidate
+ExecStart=/opt/forgezero/agent/candidate/dist/fz-agent.js
+Restart=on-failure
+RestartSec=2
+RuntimeDirectory=forgezero
+RuntimeDirectoryMode=0750
+RuntimeDirectoryPreserve=yes
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+${egress}
 `,
     "forgezero-metal-agent.service": `[Unit]
 Description=ForgeZero identity-only physical-host Agent

package/dist/platform-bootstrap-runtime.d.ts

@@ -31,6 +31,13 @@ export interface PlatformInitialInventory {
         PlatformInitialInventoryCompute,
         PlatformInitialInventoryCompute
     ];
+    /** Generation-one release evidence; external Git automation is connected after custody opens Vault. */
+    deployment?: {
+        source: 'bootstrap-bundle';
+        branch: 'dev' | 'main';
+        revision: string;
+        bundleSha256: string;
+    };
 }
 export type PlatformBootstrapEmail = {
     provider: 'smtp';

package/dist/platform-bootstrap-runtime.js

@@ -724,12 +724,14 @@ var httpsOrigin = (name, raw) => {
   return value.origin;
 };
 function validatePlatformInitialInventory(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["metalHostname", "region", "computes"].includes(key)) || !/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(value.metalHostname) || !value.region || typeof value.region !== "object" || Array.isArray(value.region) || Object.keys(value.region).some((key) => !["key", "label", "country", "city", "confidentialCapable"].includes(key)) || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.region.key) || !/^[A-Z]{2}$/.test(value.region.country) || value.region.confidentialCapable !== true || !Array.isArray(value.computes)) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["metalHostname", "region", "computes", "deployment"].includes(key)) || !/^[A-Za-z0-9][A-Za-z0-9.-]{1,252}$/.test(value.metalHostname) || !value.region || typeof value.region !== "object" || Array.isArray(value.region) || Object.keys(value.region).some((key) => !["key", "label", "country", "city", "confidentialCapable"].includes(key)) || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.region.key) || !/^[A-Z]{2}$/.test(value.region.country) || value.region.confidentialCapable !== true || !Array.isArray(value.computes)) {
     throw new Error("initial platform inventory coordinates are invalid");
   }
   safeAtom("initialInventory.region.label", value.region.label);
   if (value.region.city !== undefined)
     safeAtom("initialInventory.region.city", value.region.city);
+  if (value.deployment !== undefined && (!value.deployment || typeof value.deployment !== "object" || Array.isArray(value.deployment) || Object.keys(value.deployment).some((key) => !["source", "branch", "revision", "bundleSha256"].includes(key)) || value.deployment.source !== "bootstrap-bundle" || !["dev", "main"].includes(value.deployment.branch) || !/^[a-f0-9]{40}$/.test(value.deployment.revision) || !/^[a-f0-9]{64}$/.test(value.deployment.bundleSha256)))
+    throw new Error("initial platform deployment evidence is invalid");
   const computes = validatePlatformGenesisGuests(value.computes.map((compute) => {
     if (!compute || typeof compute !== "object" || Array.isArray(compute) || Object.keys(compute).some((key) => ![
       "name",
@@ -764,7 +766,8 @@ function validatePlatformInitialInventory(value) {
       databaseRole: compute.databaseRole,
       databaseAgency: compute.databaseAgency,
       confidential: true
-    }))
+    })),
+    ...value.deployment ? { deployment: { ...value.deployment } } : {}
   };
 }
 var systemdValue = (name, raw) => {