@forgezero/agent 0.1.26 → 0.1.28

package/dist/guest-enrolment.js

@@ -28,8 +28,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";

package/dist/index.d.ts

@@ -27,6 +27,15 @@ export { DEFAULT_METAL_HELPER_SOCKET, requestMetalProvision, startMetalHelper }
 export { DEFAULT_LIFECYCLE_HELPER_SOCKET, executeLifecycleAction, loadLifecycleProfile, requestLifecycleAction, startLifecycleHelper, validateLifecycleProfile } from './lifecycle-helper';
 export type { LifecycleCommandResult, LifecycleExec, LifecycleProfile } from './lifecycle-helper';
 export { materializeWarpMdm, renderWarpMdm } from './warp-config';
+export { compareVersions, restoreAgentRelease, selectAgentRelease, stageAgentRelease, validateAgentRelease, DEFAULT_AGENT_RELEASE_ROOT, DEFAULT_AGENT_UPDATE_SOCKET, MAX_AGENT_TARBALL_BYTES } from './agent-update';
+export type { AgentRelease, StagedAgentRelease, UpdateCommand, UpdateCommandResult } from './agent-update';
+export { activateAgentRelease, probeAgentSocket, requestAgentUpdate, startAgentUpdateHelper, AGENT_UPDATE_GROUP, AGENT_UPDATE_HELPER_UNIT_PATH, AGENT_UPDATE_RECEIPT } from './agent-update-helper';
+export type { AgentUpdateRequest, AgentUpdateResponse } from './agent-update-helper';
+export { DEFAULT_SOFTWARE_HELPER_SOCKET, requestSoftware, startSoftwareHelper, SOFTWARE_HELPER_GROUP, SOFTWARE_HELPER_UNIT_PATH } from './software-helper';
+export { ensureSoftwareRequirements, observeSoftwareHost, validateSoftwareRequirements } from './software';
+export type { SoftwareCommandResult, SoftwareExec, SoftwareObservation, SoftwareRequirement } from './software';
+export { heartbeatAgentOnce, observeAgentHost, startAgentHeartbeat } from './agent-heartbeat';
+export type { AgentHeartbeatOptions, AgentHeartbeatResponse, AgentObservation } from './agent-heartbeat';
 export { DEFAULT_DEPLOYMENT_RUNNER_SOCKET, requestDeploymentCommand, startDeploymentRunner } from './deployment-runner';
 export { createSnpAttestationSource } from './snp-attestation';
 export type { SnpAttestationOptions } from './snp-attestation';
@@ -45,6 +54,8 @@ export { assertSupportedGuestImage, SUPPORTED_GUEST_IMAGE } from './ubuntu';
 export declare function loadOrCreateSeed(path: string): Uint8Array;
 export interface AgentConfig {
     socketPath?: string;
+    /** systemd-owned listener fd; preserves the application endpoint across replacement. */
+    listenFd?: number;
     seedPath?: string;
     /** Prefer this already-unsealed systemd credential over a persistent file. */
     seedCredential?: string;
@@ -82,6 +93,8 @@ export declare const DEFAULT_SOCKET_PATH = "/run/forgezero/vault.sock";
 export declare const DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
 export declare const DEFAULT_SEED_CREDENTIAL = "agent-seed";
 export declare const DEFAULT_ENROLMENT_STATE_PATH = "/var/lib/forgezero/enrolment.json";
+/** Resolve the one descriptor systemd passes for the application Vault socket. */
+export declare function systemdListenFd(environment?: Record<string, string | undefined>, pid?: number): number | undefined;
 /**
  * Read a systemd credential made available only to this unit.
  *

package/dist/metal-helper-socket.js

@@ -552,16 +552,36 @@ async function removeMetalGuest(profile, claim, exec) {
     throw new MetalProvisionError("create claim cannot remove a guest");
   const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
   const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
-  if (!manifest)
+  if (!manifest) {
+    const seedBase = join(profile.seedDir, name);
+    const localArtifacts = [
+      unitPath,
+      `${seedBase}-seed.iso`,
+      `${seedBase}-user-data`,
+      `${seedBase}-meta-data`,
+      `${seedBase}-network-config`
+    ];
+    if (localArtifacts.some(existsSync)) {
+      throw new MetalProvisionError("guest artifacts exist without owned inventory");
+    }
+    const [volume, active] = await Promise.all([
+      exec(["lvs", "--noheadings", lv]),
+      exec(["systemctl", "is-active", service])
+    ]);
+    if (volume.exitCode === 0 || active.exitCode === 0) {
+      throw new MetalProvisionError("guest runtime exists without owned inventory");
+    }
     return {};
+  }
   const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
   const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
   if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
-  const service = `forgezero-guest@${name}.service`;
-  const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
   else if (legacyPlatformIdentity)
@@ -569,7 +589,6 @@ async function removeMetalGuest(profile, claim, exec) {
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
-  const lv = `/dev/${profile.volumeGroup}/${name}`;
   if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
     await checked(exec, ["lvremove", "-fy", lv]);
   for (const path of [

package/dist/metal-provision.js

@@ -552,16 +552,36 @@ async function removeMetalGuest(profile, claim, exec) {
     throw new MetalProvisionError("create claim cannot remove a guest");
   const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
+  const service = `forgezero-guest@${name}.service`;
+  const unitPath = join(profile.unitDir, service);
+  const lv = `/dev/${profile.volumeGroup}/${name}`;
   const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : legacyPlatformManifest(profile, claim, name);
-  if (!manifest)
+  if (!manifest) {
+    const seedBase = join(profile.seedDir, name);
+    const localArtifacts = [
+      unitPath,
+      `${seedBase}-seed.iso`,
+      `${seedBase}-user-data`,
+      `${seedBase}-meta-data`,
+      `${seedBase}-network-config`
+    ];
+    if (localArtifacts.some(existsSync)) {
+      throw new MetalProvisionError("guest artifacts exist without owned inventory");
+    }
+    const [volume, active] = await Promise.all([
+      exec(["lvs", "--noheadings", lv]),
+      exec(["systemctl", "is-active", service])
+    ]);
+    if (volume.exitCode === 0 || active.exitCode === 0) {
+      throw new MetalProvisionError("guest runtime exists without owned inventory");
+    }
     return {};
+  }
   const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
   const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
   if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
-  const service = `forgezero-guest@${name}.service`;
-  const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
   else if (legacyPlatformIdentity)
@@ -569,7 +589,6 @@ async function removeMetalGuest(profile, claim, exec) {
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
-  const lv = `/dev/${profile.volumeGroup}/${name}`;
   if ((await exec(["lvs", "--noheadings", lv])).exitCode === 0)
     await checked(exec, ["lvremove", "-fy", lv]);
   for (const path of [

package/dist/migration-pull.js

@@ -15,8 +15,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";

package/dist/node-vault.js

@@ -135,8 +135,21 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
+function signedNodeApiUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Agent API URL must be an absolute HTTPS URL.");
+  }
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(loopback && url.protocol === "http:") || url.username || url.password || url.search || url.hash) {
+    throw new Error("Agent API URL must be HTTPS without credentials, query or fragment.");
+  }
+  return url;
+}
 async function postSignedNode(options, path, body) {
-  const url = new URL(options.apiUrl);
+  const url = signedNodeApiUrl(options.apiUrl);
   url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
   url.search = "";
   url.hash = "";
@@ -196,7 +209,7 @@ function projectVaultCoordinate(key) {
 function tenantNodeApiUrl(apiUrl, tenantSlug) {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
     throw new Error("tenant slug is malformed");
-  const url = new URL(apiUrl);
+  const url = signedNodeApiUrl(apiUrl);
   url.pathname = `/api/t/${encodeURIComponent(tenantSlug)}`;
   url.search = "";
   url.hash = "";

package/dist/provision.d.ts

@@ -127,12 +127,25 @@ export declare const DEPLOYMENT_GROUP = "forgezero-deploy";
 export declare const VAULT_GROUP = "forgezero-vault";
 export declare const LIFECYCLE_GROUP = "forgezero-lifecycle";
 export declare const DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
+export declare const AGENT_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-agent.socket";
 export declare const DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
 export declare const ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
 export declare const LIFECYCLE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-lifecycle-helper.service";
 export declare const LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
 export declare const WARP_CONFIG_UNIT_PATH = "/etc/systemd/system/forgezero-warp-config.service";
 export declare const WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.service.d/forgezero.conf";
+/** Root may execute only package-owned OS strategies selected by id + version. */
+export declare function softwareHelperUnit(options: Pick<UnitOptions, 'binPath'>): string;
+/** Fixed root boundary for verified, health-gated Agent replacement. */
+export declare function agentUpdateHelperUnit(options: Pick<UnitOptions, 'binPath'>): string;
+/**
+ * PID 1 owns the stable application endpoint.
+ *
+ * New connections wait in the kernel while the credential-bearing Agent drains
+ * and a health-gated replacement starts. This is supervision, not a background
+ * terminal, and it works identically on platform and tenant computes.
+ */
+export declare function agentSocketUnit(options: Pick<UnitOptions, 'socketPath'>): string;
 export declare function warpConfigUnit(options: Pick<UnitOptions, 'binPath' | 'warpOrganization' | 'warpClientIdCredentialPath' | 'warpClientSecretCredentialPath'>): string;
 export declare function warpServiceDropIn(): string;
 export declare function lifecycleHelperUnit(options: Pick<UnitOptions, 'binPath' | 'lifecycleProfilePath' | 'lifecycleHelperSocketPath'>): string;