@forgezero/agent 0.1.21 → 0.1.23

package/dist/fz.js

@@ -101,7 +101,8 @@ async function spawnWith(command, env, report = () => {}) {
 }
 
 // src/cli/index.ts
-import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
+import { dirname } from "path";
 import { fileURLToPath } from "url";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
 
@@ -149,9 +150,104 @@ var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, s
 var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
 var DEPLOYMENT_GROUP = "forgezero-deploy";
 var VAULT_GROUP = "forgezero-vault";
+var LIFECYCLE_GROUP = "forgezero-lifecycle";
 var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.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";
+var LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
+var WARP_CONFIG_UNIT_PATH = "/etc/systemd/system/forgezero-warp-config.service";
+var WARP_SERVICE_DROP_IN_PATH = "/etc/systemd/system/warp-svc.service.d/forgezero.conf";
+var systemdPath = (value, label) => {
+  if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
+    throw new Error(`invalid ${label} path`);
+  return value;
+};
+function warpConfigUnit(options) {
+  if (!options.warpOrganization || !/^[a-z0-9][a-z0-9-]{0,62}$/i.test(options.warpOrganization)) {
+    throw new Error("WARP organization is invalid");
+  }
+  if (!options.warpClientIdCredentialPath || !options.warpClientSecretCredentialPath) {
+    throw new Error("WARP service-token credential paths are required");
+  }
+  const clientIdPath = systemdPath(options.warpClientIdCredentialPath, "WARP client-id credential");
+  const clientSecretPath = systemdPath(options.warpClientSecretCredentialPath, "WARP client-secret credential");
+  const bin = options.binPath ?? "fz-agent";
+  return `[Unit]
+Description=Materialize Cloudflare One enrollment in tmpfs
+Documentation=https://www.forgezero.net/docs/agent
+Before=warp-svc.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+LoadCredentialEncrypted=warp-auth-client-id:${clientIdPath}
+LoadCredentialEncrypted=warp-auth-client-secret:${clientSecretPath}
+Environment=FZ_WARP_CLIENT_ID_CREDENTIAL=warp-auth-client-id
+Environment=FZ_WARP_CLIENT_SECRET_CREDENTIAL=warp-auth-client-secret
+ExecStart=${bin} warp-config --organization=${options.warpOrganization}
+RuntimeDirectory=forgezero-warp
+RuntimeDirectoryMode=0700
+RuntimeDirectoryPreserve=yes
+UMask=0077
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/cloudflare-warp
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function warpServiceDropIn() {
+  return `[Unit]
+Requires=forgezero-warp-config.service
+After=forgezero-warp-config.service
+`;
+}
+function lifecycleHelperUnit(options) {
+  if (!options.lifecycleProfilePath)
+    throw new Error("lifecycle helper needs a root-owned profile");
+  const bin = options.binPath ?? "fz-agent";
+  const profile = systemdPath(options.lifecycleProfilePath, "lifecycle profile");
+  const socket = systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket");
+  return `[Unit]
+Description=ForgeZero fixed-operation compute lifecycle helper
+Documentation=https://www.forgezero.net/docs/agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+Group=${LIFECYCLE_GROUP}
+Environment=FZ_LIFECYCLE_HELPER_SOCKET=${socket}
+ExecStart=${bin} lifecycle-helper --profile=${profile}
+Restart=always
+RestartSec=2
+RuntimeDirectory=forgezero-lifecycle
+RuntimeDirectoryMode=0750
+UMask=0007
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
 function agentEnrolmentUnit(options) {
   if (!options.apiUrl || !options.enrolTokenCredentialPath || !options.enrolStatePath) {
     throw new Error("direct enrolment needs API, credential and state paths");
@@ -246,6 +342,19 @@ function agentUnit(options) {
   const controlSocketPath = options.controlSocketPath ?? "/run/forgezero/control.sock";
   const deployRoot = options.deployRoot ?? "/opt/forgezero";
   const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const lifecycleEnabled = Boolean(options.pullMigrations && options.lifecycleProfilePath);
+  if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
+    throw new Error("migration pull and lifecycle profile must be supplied together");
+  }
+  const lifecycleHelperSocketPath = lifecycleEnabled ? systemdPath(options.lifecycleHelperSocketPath ?? LIFECYCLE_HELPER_SOCKET, "lifecycle helper socket") : undefined;
+  const warpValues = [
+    options.warpOrganization,
+    options.warpClientIdCredentialPath,
+    options.warpClientSecretCredentialPath
+  ];
+  const warpEnabled = warpValues.every(Boolean);
+  if (warpValues.some(Boolean) && !warpEnabled)
+    throw new Error("WARP configuration must be supplied together");
   const enrolmentEnabled = Boolean(options.enrolTokenCredentialPath && options.enrolStatePath);
   const deploymentEnvironment = options.deploymentEnvironment ?? {};
   const deploymentCredentials = options.deploymentCredentials ?? {};
@@ -280,7 +389,9 @@ function agentUnit(options) {
     Object.keys(deploymentEnvironment).length > 0 ? `FZ_DEPLOY_ENV_NAMES=${Object.keys(deploymentEnvironment).join(",")}` : null,
     ...Object.entries(deploymentEnvironment).map(([name, value]) => `${name}=${value}`),
     options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
-    options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null
+    options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null,
+    options.pullMigrations ? "FZ_MIGRATION_PULL=true" : null,
+    options.pullMigrations ? `FZ_LIFECYCLE_HELPER_SOCKET=${lifecycleHelperSocketPath}` : null
   ].filter((line) => line !== null);
   if (deploymentEnabled) {
     environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
@@ -290,14 +401,22 @@ function agentUnit(options) {
   const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
 `);
   const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache` : "";
-  const deploymentGroup = deploymentEnabled ? `SupplementaryGroups=${DEPLOYMENT_GROUP}` : "";
+  const supplementaryGroups = [
+    deploymentEnabled ? DEPLOYMENT_GROUP : null,
+    lifecycleEnabled ? LIFECYCLE_GROUP : null
+  ].filter((value) => value !== null);
+  const deploymentGroup = supplementaryGroups.length > 0 ? `SupplementaryGroups=${supplementaryGroups.join(" ")}` : "";
   const after = [
     "network-online.target",
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
+    warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
   ].filter((value) => value !== null);
   const requires = [
     deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    lifecycleEnabled ? "forgezero-lifecycle-helper.service" : null,
+    warpEnabled ? "warp-svc.service" : null,
     enrolmentEnabled ? "forgezero-agent-enrol.service" : null
   ].filter((value) => value !== null);
   const deploymentDependency = [
@@ -369,37 +488,63 @@ function planProvision(options) {
   const credentialDir = seedCredentialPath.replace(/\/[^/]+$/, "");
   const deployRoot = options.deployRoot ?? "/opt/forgezero";
   const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const lifecycleEnabled = Boolean(options.pullMigrations && options.lifecycleProfilePath);
+  if (Boolean(options.pullMigrations) !== Boolean(options.lifecycleProfilePath)) {
+    throw new Error("migration pull and lifecycle profile must be supplied together");
+  }
+  const warpValues = [
+    options.warpOrganization,
+    options.warpClientIdCredentialPath,
+    options.warpClientSecretCredentialPath
+  ];
+  const warpEnabled = warpValues.every(Boolean);
+  if (warpValues.some(Boolean) && !warpEnabled)
+    throw new Error("WARP configuration must be supplied together");
   const enrolmentEnabled = Boolean(options.enrolTokenSourcePath && options.enrolTokenCredentialPath && options.enrolStatePath);
   if (Boolean(options.enrolTokenSourcePath) !== Boolean(options.enrolTokenCredentialPath) || Boolean(options.enrolTokenCredentialPath) !== Boolean(options.enrolStatePath))
     throw new Error("direct enrolment paths must be supplied together");
-  const safePath = (value, label) => {
-    if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
-      throw new Error(`invalid ${label} path`);
-    return value;
-  };
-  const enrolTokenSourcePath = enrolmentEnabled ? safePath(options.enrolTokenSourcePath, "enrolment source") : undefined;
-  const enrolTokenCredentialPath = enrolmentEnabled ? safePath(options.enrolTokenCredentialPath, "enrolment credential") : undefined;
-  const enrolStatePath = enrolmentEnabled ? safePath(options.enrolStatePath, "enrolment state") : undefined;
+  const enrolTokenSourcePath = enrolmentEnabled ? systemdPath(options.enrolTokenSourcePath, "enrolment source") : undefined;
+  const enrolTokenCredentialPath = enrolmentEnabled ? systemdPath(options.enrolTokenCredentialPath, "enrolment credential") : undefined;
+  const enrolStatePath = enrolmentEnabled ? systemdPath(options.enrolStatePath, "enrolment state") : undefined;
   const enrolStateDir = enrolStatePath?.replace(/\/[^/]+$/, "");
-  const sourceBinPath = options.sourceBinPath ? safePath(options.sourceBinPath, "agent source binary") : undefined;
-  const binPath = options.binPath ? safePath(options.binPath, "agent binary") : undefined;
-  const gitCredentialPath = options.gitCredentialPath ? safePath(options.gitCredentialPath, "Git credential") : undefined;
-  const gitPublicKeyPath = options.gitPublicKeyPath ? safePath(options.gitPublicKeyPath, "Git public key") : undefined;
+  const sourceBinPath = options.sourceBinPath ? systemdPath(options.sourceBinPath, "agent source binary") : undefined;
+  const binPath = options.binPath ? systemdPath(options.binPath, "agent binary") : undefined;
+  const gitCredentialPath = options.gitCredentialPath ? systemdPath(options.gitCredentialPath, "Git credential") : undefined;
+  const gitPublicKeyPath = options.gitPublicKeyPath ? systemdPath(options.gitPublicKeyPath, "Git public key") : undefined;
   if (options.generateGitIdentity && (!gitCredentialPath || !gitPublicKeyPath)) {
     throw new Error("generated Git identity needs credential and public-key paths");
   }
   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 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 }),
+    unit: agentUnit({ ...options, mode, lifecycleProfilePath, lifecycleHelperSocketPath }),
     auxiliaryUnits: [
       ...deploymentEnabled ? [
         { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) }
       ] : [],
       ...enrolmentEnabled ? [
         { path: ENROLMENT_UNIT_PATH, unit: agentEnrolmentUnit(options) }
+      ] : [],
+      ...lifecycleEnabled ? [
+        { path: LIFECYCLE_HELPER_UNIT_PATH, unit: lifecycleHelperUnit({
+          ...options,
+          lifecycleProfilePath,
+          lifecycleHelperSocketPath
+        }) }
+      ] : [],
+      ...warpEnabled ? [
+        { path: WARP_CONFIG_UNIT_PATH, unit: warpConfigUnit({
+          ...options,
+          warpClientIdCredentialPath,
+          warpClientSecretCredentialPath
+        }) },
+        { path: WARP_SERVICE_DROP_IN_PATH, unit: warpServiceDropIn() }
       ] : []
     ],
     socketPath: options.socketPath,
@@ -413,10 +558,18 @@ function planProvision(options) {
         label: "root-owned agent runtime",
         command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")}; ` + `install -o root -g root -m 0755 ${sourceBinPath} ${binPath}`
       }] : [],
+      ...warpEnabled ? [{
+        label: "Cloudflare One client for Ubuntu 26.04",
+        command: `. /etc/os-release; test "$ID" = ubuntu && test "$VERSION_ID" = 26.04; ` + `install -d -m 0755 /usr/share/keyrings /etc/apt/sources.list.d /etc/systemd/system/warp-svc.service.d; ` + `curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg -o /run/cloudflare-warp-key.gpg; ` + `gpg --batch --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg /run/cloudflare-warp-key.gpg; ` + `rm -f /run/cloudflare-warp-key.gpg; ` + `printf 'deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ %s main\\n' "$VERSION_CODENAME" > /etc/apt/sources.list.d/cloudflare-client.list; ` + `apt-get update -qq; DEBIAN_FRONTEND=noninteractive apt-get install -y cloudflare-warp`
+      }] : [],
       ...deploymentEnabled ? [{
         label: "deployment isolation group",
         command: `groupadd --system ${DEPLOYMENT_GROUP} || true`
       }] : [],
+      ...lifecycleEnabled ? [{
+        label: "lifecycle helper access group",
+        command: `groupadd --system ${LIFECYCLE_GROUP} || true`
+      }] : [],
       {
         label: "service account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
@@ -425,6 +578,10 @@ function planProvision(options) {
         label: "bind service account to vault group",
         command: `usermod -g ${VAULT_GROUP} ${user}`
       },
+      ...lifecycleEnabled ? [{
+        label: "grant lifecycle helper socket access",
+        command: `usermod -a -G ${LIFECYCLE_GROUP} ${user}`
+      }] : [],
       ...deploymentEnabled ? [{
         label: "credential-free deployment account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} || true; ` + `usermod -a -G ${DEPLOYMENT_GROUP} ${user}`
@@ -470,6 +627,8 @@ function planProvision(options) {
         label: "enable and start",
         command: `systemctl enable --now ${[
           ...deploymentEnabled ? ["forgezero-deploy-runner.service"] : [],
+          ...lifecycleEnabled ? ["forgezero-lifecycle-helper.service"] : [],
+          ...warpEnabled ? ["forgezero-warp-config.service", "warp-svc.service"] : [],
           ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
           "forgezero-agent.service"
         ].join(" ")}`
@@ -484,6 +643,14 @@ function planProvision(options) {
         label: "prove the deployment runner socket exists",
         command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
       }] : [],
+      ...lifecycleEnabled ? [{
+        label: "prove the lifecycle helper socket exists",
+        command: `test -S ${lifecycleHelperSocketPath}`
+      }] : [],
+      ...warpEnabled ? [{
+        label: "prove Cloudflare WARP is connected",
+        command: `warp-cli --accept-tos status | grep -Eiq '(^|[[:space:]])Connected([[:space:]]|$)'`
+      }] : [],
       ...options.repository ? [{
         label: "prove the deployment control socket exists",
         command: `test -S ${options.controlSocketPath ?? "/run/forgezero/control.sock"}`
@@ -774,7 +941,7 @@ async function resolveIdentity(selector, socketPath) {
 }
 
 // src/version.ts
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
@@ -997,6 +1164,12 @@ async function cmdAgent(options, args) {
     deploymentEnvironment: parseAssignments(process.env.FZ_DEPLOY_ENV),
     deploymentCredentials: parseAssignments(process.env.FZ_DEPLOY_CREDENTIALS),
     pullDeployments: process.env.FZ_DEPLOY_PULL === "true",
+    pullMigrations: process.env.FZ_MIGRATION_PULL === "true",
+    lifecycleProfilePath: process.env.FZ_LIFECYCLE_PROFILE,
+    lifecycleHelperSocketPath: process.env.FZ_LIFECYCLE_HELPER_SOCKET,
+    warpOrganization: process.env.FZ_WARP_ORGANIZATION,
+    warpClientIdCredentialPath: process.env.FZ_WARP_CLIENT_ID_CREDENTIAL_PATH,
+    warpClientSecretCredentialPath: process.env.FZ_WARP_CLIENT_SECRET_CREDENTIAL_PATH,
     ...options.enrol ? {
       pullDeployments: true,
       enrolTokenSourcePath,
@@ -1033,6 +1206,7 @@ async function cmdAgent(options, args) {
     writeFileSync(plan.unitPath, plan.unit, { mode: 420 });
     out.ok(`Wrote ${plan.unitPath}`);
     for (const auxiliary of plan.auxiliaryUnits) {
+      mkdirSync(dirname(auxiliary.path), { recursive: true, mode: 493 });
       writeFileSync(auxiliary.path, auxiliary.unit, { mode: 420 });
       out.ok(`Wrote ${auxiliary.path}`);
     }

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { pullDeploymentOnce, startDeploymentPull } from './deployment-pull';
 export type { DeploymentPullOptions, RemoteDeploymentClaim, PullResult } from './deployment-pull';
 export { pullProvisioningOnce, startProvisioningPull } from './provisioning-pull';
 export type { CreateRemoteProvisionClaim, ProvisioningPullOptions, RemoteProvisionClaim, GuestAccess, ProvisionPullResult, ProvisionRunner, ProvisionResult } from './provisioning-pull';
+export { pullMigrationOnce, startMigrationPull } from './migration-pull';
+export type { MigrationAction, MigrationEvidence, MigrationNetwork, MigrationPullOptions, MigrationPullResult, RemoteMigrationClaim } from './migration-pull';
 export { enrolGuestIdentity, loadGuestBinding } from './guest-enrolment';
 export type { GuestBinding, GuestEnrolmentOptions } from './guest-enrolment';
 export { createNodeVaultCache, projectVaultCacheKey, projectVaultCoordinate, startNodeVaultSync, tenantNodeApiUrl } from './node-vault';
@@ -22,6 +24,9 @@ export { allocateAddress, allocateCpuPool, cloudInit, guestNameFor, provisionMet
 export { validateMetalProfile } from './metal-provision';
 export type { GuestManifest, MetalCommandResult, MetalCpuPool, MetalExec, MetalProvisionProfile } from './metal-provision';
 export { DEFAULT_METAL_HELPER_SOCKET, requestMetalProvision, startMetalHelper } from './metal-helper-socket';
+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 { DEFAULT_DEPLOYMENT_RUNNER_SOCKET, requestDeploymentCommand, startDeploymentRunner } from './deployment-runner';
 export { createSnpAttestationSource } from './snp-attestation';
 export type { SnpAttestationOptions } from './snp-attestation';

package/dist/lifecycle-helper.d.ts

@@ -0,0 +1,36 @@
+import { type Server } from 'node:net';
+import type { MigrationEvidence, RemoteMigrationClaim } from './migration-pull';
+export declare const DEFAULT_LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
+export interface LifecycleProfile {
+    /** Root-owned systemd units whose normal stop path performs application drain. */
+    apiUnits: readonly string[];
+    /** Root-owned database service stopped only at the final retirement stage. */
+    databaseUnit: string;
+    /** Loopback health endpoint for the API on this compute. */
+    apiHealthUrl: string;
+    /** Loopback health endpoint for the database member on this compute. */
+    databaseHealthUrl: string;
+    /** Ports that must be reachable on every signed controller-provided private peer. */
+    databasePorts: readonly number[];
+}
+export interface LifecycleCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type LifecycleExec = (argv: readonly string[]) => Promise<LifecycleCommandResult>;
+export declare function validateLifecycleProfile(profile: LifecycleProfile): void;
+export declare function loadLifecycleProfile(path: string): LifecycleProfile;
+export declare const spawnLifecycleCommand: LifecycleExec;
+export declare function executeLifecycleAction(profile: LifecycleProfile, claim: RemoteMigrationClaim, exec?: LifecycleExec, tcpProbe?: (host: string, port: number) => Promise<void>, fetcher?: typeof fetch): Promise<MigrationEvidence>;
+export declare function startLifecycleHelper(options: {
+    profile: LifecycleProfile;
+    socketPath?: string;
+    exec?: LifecycleExec;
+    tcpProbe?: (host: string, port: number) => Promise<void>;
+    fetch?: typeof fetch;
+}): {
+    server: Server;
+    stop(): Promise<void>;
+};
+export declare function requestLifecycleAction(claim: RemoteMigrationClaim, socketPath?: string): Promise<MigrationEvidence>;

package/dist/lifecycle-helper.js

@@ -0,0 +1,216 @@
+// src/lifecycle-helper.ts
+import { chmodSync, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { connect, createConnection, createServer, isIP } from "node:net";
+var DEFAULT_LIFECYCLE_HELPER_SOCKET = "/run/forgezero-lifecycle/helper.sock";
+var MAX_REQUEST_BYTES = 16 * 1024;
+var REQUEST_TIMEOUT_MS = 5000;
+var ACTION_TIMEOUT_MS = 10 * 60000;
+var unitPattern = /^[A-Za-z0-9_.@-]+\.service$/;
+var privateIp = (value) => {
+  const address = value.replace(/^\[|\]$/g, "").toLowerCase();
+  if (isIP(address) === 4) {
+    const [a, b] = address.split(".").map(Number);
+    return a === 10 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+  }
+  if (isIP(address) === 6) {
+    const first = Number.parseInt(address.split(":", 1)[0], 16);
+    return Number.isFinite(first) && (first & 65024) === 64512;
+  }
+  return false;
+};
+function validateLifecycleProfile(profile) {
+  if (!Array.isArray(profile.apiUnits) || profile.apiUnits.length < 1 || profile.apiUnits.some((unit) => !unitPattern.test(unit))) {
+    throw new Error("lifecycle profile needs one or more valid API service units");
+  }
+  if (!unitPattern.test(profile.databaseUnit))
+    throw new Error("lifecycle profile database unit is invalid");
+  const apiUrl = new URL(profile.apiHealthUrl);
+  if (apiUrl.protocol !== "http:" || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(apiUrl.hostname)) {
+    throw new Error("API health URL must be loopback HTTP");
+  }
+  const databaseUrl = new URL(profile.databaseHealthUrl);
+  if (databaseUrl.protocol !== "http:" || !(["127.0.0.1", "[::1]", "::1", "localhost"].includes(databaseUrl.hostname) || privateIp(databaseUrl.hostname))) {
+    throw new Error("database health URL must be loopback or private HTTP");
+  }
+  if (!Array.isArray(profile.databasePorts) || profile.databasePorts.length < 1 || profile.databasePorts.some((port) => !Number.isInteger(port) || port < 1 || port > 65535)) {
+    throw new Error("lifecycle profile database ports are invalid");
+  }
+}
+function loadLifecycleProfile(path) {
+  const profile = JSON.parse(readFileSync(path, "utf8"));
+  validateLifecycleProfile(profile);
+  return profile;
+}
+var spawnLifecycleCommand = async (argv) => {
+  const child = Bun.spawn([...argv], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+  }, ACTION_TIMEOUT_MS);
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  clearTimeout(timer);
+  return { exitCode: timedOut ? 124 : exitCode, stdout, stderr };
+};
+var requireSuccess = async (exec, argv, label) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.exitCode}`}`);
+  return result.stdout;
+};
+var probeTcp = (host, port, timeoutMs = 5000) => new Promise((resolve, reject) => {
+  const socket = createConnection({ host, port });
+  socket.setTimeout(timeoutMs);
+  socket.once("connect", () => {
+    socket.destroy();
+    resolve();
+  });
+  socket.once("timeout", () => {
+    socket.destroy();
+    reject(new Error(`private peer ${host}:${port} timed out`));
+  });
+  socket.once("error", reject);
+});
+async function executeLifecycleAction(profile, claim, exec = spawnLifecycleCommand, tcpProbe = probeTcp, fetcher = fetch) {
+  validateLifecycleProfile(profile);
+  switch (claim.action) {
+    case "network-ready": {
+      if (!claim.peerPrivateAddresses?.length)
+        throw new Error("network claim has no private peers");
+      if (claim.network === "cloudflare-warp") {
+        const status = await requireSuccess(exec, ["/usr/bin/warp-cli", "--accept-tos", "status"], "WARP status");
+        if (!/\bconnected\b/i.test(status) || /\bdisconnected\b/i.test(status))
+          throw new Error("WARP is not connected");
+      }
+      for (const address of claim.peerPrivateAddresses) {
+        for (const port of profile.databasePorts)
+          await tcpProbe(address, port);
+      }
+      return {
+        targetAgentReady: true,
+        privateNetworkReady: true,
+        ...claim.network === "cloudflare-warp" ? { warpConnected: true } : {}
+      };
+    }
+    case "database-member-ready": {
+      await requireSuccess(exec, ["/usr/bin/systemctl", "is-active", profile.databaseUnit], "database service check");
+      const response = await fetcher(profile.databaseHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok && response.status !== 401)
+        throw new Error(`database health returned HTTP ${response.status}`);
+      return { databaseMemberHealthy: true };
+    }
+    case "api-ready": {
+      const response = await fetcher(profile.apiHealthUrl, { signal: AbortSignal.timeout(5000) });
+      if (!response.ok)
+        throw new Error(`API health returned HTTP ${response.status}`);
+      return { apiHealthy: true };
+    }
+    case "source-drained":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits], "API drain");
+      return { sourceDrained: true };
+    case "source-stopped":
+      await requireSuccess(exec, ["/usr/bin/systemctl", "stop", ...profile.apiUnits, profile.databaseUnit], "source retirement");
+      return { sourceStopped: true };
+    default:
+      throw new Error("unknown lifecycle action");
+  }
+}
+function startLifecycleHelper(options) {
+  validateLifecycleProfile(options.profile);
+  const socketPath = options.socketPath ?? DEFAULT_LIFECYCLE_HELPER_SOCKET;
+  if (existsSync(socketPath))
+    unlinkSync(socketPath);
+  let tail = Promise.resolve();
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.setTimeout(REQUEST_TIMEOUT_MS, () => socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request timed out" } })}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > MAX_REQUEST_BYTES)
+        return void socket.end(`${JSON.stringify({ ok: false, error: { code: "REFUSED", message: "request too large" } })}
+`);
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.setTimeout(0);
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      const work = async () => {
+        let request;
+        try {
+          request = JSON.parse(line);
+        } catch {
+          return { ok: false, error: { code: "REFUSED", message: "invalid request" } };
+        }
+        if (request?.op !== "apply" || !request.claim)
+          return { ok: false, error: { code: "REFUSED", message: "unknown operation" } };
+        try {
+          return { ok: true, evidence: await executeLifecycleAction(options.profile, request.claim, options.exec, options.tcpProbe, options.fetch) };
+        } catch (cause) {
+          return { ok: false, error: { code: "FAILED", message: cause instanceof Error ? cause.message : "lifecycle action failed" } };
+        }
+      };
+      const response = tail.then(work, work);
+      tail = response;
+      response.then((value) => socket.end(`${JSON.stringify(value)}
+`));
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync(socketPath, 432));
+  return {
+    server,
+    async stop() {
+      await new Promise((resolve) => server.close(() => resolve()));
+      await tail;
+    }
+  };
+}
+function requestLifecycleAction(claim, socketPath = DEFAULT_LIFECYCLE_HELPER_SOCKET) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify({ op: "apply", claim })}
+`));
+    socket.setTimeout(ACTION_TIMEOUT_MS + 1e4, () => {
+      socket.destroy();
+      reject(new Error("lifecycle helper response timed out"));
+    });
+    let buffer = "";
+    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)
+          resolve(response.evidence);
+        else
+          reject(new Error(response.error.message));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+export {
+  validateLifecycleProfile,
+  startLifecycleHelper,
+  spawnLifecycleCommand,
+  requestLifecycleAction,
+  loadLifecycleProfile,
+  executeLifecycleAction,
+  DEFAULT_LIFECYCLE_HELPER_SOCKET
+};