@forgezero/agent 0.1.22 → 0.1.23

package/dist/migration-pull.js

@@ -0,0 +1,185 @@
+// src/signed-node-http.ts
+import {
+  encodeSignatureHeader,
+  generateResponseRecipient,
+  openResponse,
+  RESPONSE_KEY_HEADER,
+  signRequest
+} from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+async function postSignedNode(options, path, body) {
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const raw = JSON.stringify(body);
+  const recipient = generateResponseRecipient();
+  const envelope = signRequest(options.keys, options.nodeKey, {
+    method: "POST",
+    path: url.pathname,
+    query: "",
+    body: raw,
+    responseKey: recipient.publicKey
+  });
+  const signature = encodeSignatureHeader(envelope);
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-fz-node": options.nodeKey,
+      "x-fz-signature": signature,
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
+    },
+    body: raw,
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  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}`);
+  }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
+  }
+}
+
+// src/migration-pull.ts
+class MigrationClaimLostError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MigrationClaimLostError";
+  }
+}
+var post = (options, operation, body) => postSignedNode(options, `v1/node/migrations/${operation}`, body);
+async function complete(options, body) {
+  const attempts = Math.max(1, Math.min(options.completionAttempts ?? 5, 10));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let last;
+  for (let attempt = 1;attempt <= attempts; attempt += 1) {
+    try {
+      await post(options, "complete", body);
+      return;
+    } catch (cause) {
+      last = cause;
+      if (cause instanceof SignedNodeHttpError && cause.status < 500)
+        throw cause;
+      if (attempt < attempts)
+        await sleep(Math.min(2000, 250 * 2 ** (attempt - 1)));
+    }
+  }
+  throw last;
+}
+async function pullMigrationOnce(options) {
+  const response = await post(options, "claim", {});
+  if (!response.claim)
+    return { status: "idle" };
+  const claim = response.claim;
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const now = options.now ?? Date.now;
+  let expires = claim.claimExpiresAtTs;
+  let stopped = false;
+  let timer;
+  let renewal = null;
+  let lost = null;
+  const schedule = (override) => {
+    if (stopped)
+      return;
+    const delay = override ?? Math.max(1000, Math.min(5 * 60000, Math.floor(Math.max(0, expires - now()) / 3)));
+    timer = setTimer(() => {
+      if (stopped || renewal)
+        return;
+      let retry;
+      renewal = post(options, "renew", {
+        migrationKey: claim.migrationKey,
+        claimToken: claim.claimToken
+      }).then((value) => {
+        expires = value.claimExpiresAtTs;
+      }).catch((cause) => {
+        if (cause instanceof SignedNodeHttpError && cause.status < 500) {
+          lost = new MigrationClaimLostError(cause.message);
+          stopped = true;
+        } else
+          retry = Math.max(1000, options.renewRetryMs ?? 5000);
+      }).finally(() => {
+        renewal = null;
+        if (!stopped)
+          schedule(retry);
+      });
+    }, delay);
+  };
+  schedule();
+  let evidence;
+  try {
+    evidence = await options.run(claim);
+  } catch (cause) {
+    stopped = true;
+    clearTimer(timer);
+    await renewal;
+    if (lost)
+      throw lost;
+    const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
+    await complete(options, {
+      migrationKey: claim.migrationKey,
+      claimToken: claim.claimToken,
+      ok: false,
+      detail: reason
+    });
+    return { status: "failed", claim, reason };
+  }
+  stopped = true;
+  clearTimer(timer);
+  await renewal;
+  if (lost)
+    throw lost;
+  await complete(options, {
+    migrationKey: claim.migrationKey,
+    claimToken: claim.claimToken,
+    ok: true,
+    evidence
+  });
+  return { status: "completed", claim, evidence };
+}
+function startMigrationPull(options) {
+  const interval = Math.max(1000, options.intervalMs ?? 5000);
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  let stopped = false;
+  let timer;
+  let active = null;
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = pullMigrationOnce(options).then((result) => options.onEvent?.(result.status, result)).catch((cause) => options.onEvent?.("poll-failed", cause)).finally(() => {
+      active = null;
+      if (!stopped)
+        timer = setTimer(tick, interval);
+    });
+  };
+  tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+export {
+  startMigrationPull,
+  pullMigrationOnce
+};

package/dist/provision.d.ts

@@ -92,6 +92,15 @@ export interface UnitOptions {
     deploymentCredentials?: Record<string, string>;
     /** Enable authenticated outbound deployment claims after enrolment. */
     pullDeployments?: boolean;
+    /** Enable PQ-authenticated lifecycle claims through a constrained root helper. */
+    pullMigrations?: boolean;
+    /** Root-owned declarative lifecycle profile; never supplied by a migration claim. */
+    lifecycleProfilePath?: string;
+    lifecycleHelperSocketPath?: string;
+    /** Optional cross-network overlay. All three values are required together. */
+    warpOrganization?: string;
+    warpClientIdCredentialPath?: string;
+    warpClientSecretCredentialPath?: string;
     /** Where `fz-agent` ended up. `bun add -g` puts it on PATH. */
     binPath?: string;
     /** Package-owned binary copied to binPath before hardened units start. */
@@ -109,9 +118,17 @@ export interface UnitOptions {
 export declare const DEPLOYMENT_RUNNER_USER = "forgezero-runner";
 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 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";
+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;
 /**
  * Exchange a tenant-issued one-time capability before the durable agent starts.
  *

package/dist/provision.js

@@ -42,9 +42,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");
@@ -139,6 +234,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 ?? {};
@@ -173,7 +281,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`);
@@ -183,14 +293,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 = [
@@ -262,37 +380,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,
@@ -306,10 +450,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`
@@ -318,6 +470,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}`
@@ -363,6 +519,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(" ")}`
@@ -377,6 +535,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"}`
@@ -385,15 +551,23 @@ function planProvision(options) {
   };
 }
 export {
+  warpServiceDropIn,
+  warpConfigUnit,
   reasonFor,
   planProvision,
   modeFor,
+  lifecycleHelperUnit,
   deploymentRunnerUnit,
   atLeast,
   agentUnit,
   agentEnrolmentUnit,
+  WARP_SERVICE_DROP_IN_PATH,
+  WARP_CONFIG_UNIT_PATH,
   VAULT_GROUP,
   UNIT_PATH,
+  LIFECYCLE_HELPER_UNIT_PATH,
+  LIFECYCLE_HELPER_SOCKET,
+  LIFECYCLE_GROUP,
   ENROLMENT_UNIT_PATH,
   DEPLOYMENT_RUNNER_USER,
   DEPLOYMENT_RUNNER_UNIT_PATH,

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.22";
+export declare const VERSION = "0.1.23";

package/dist/warp-config.d.ts

@@ -0,0 +1,20 @@
+/** Cloudflare One MDM document; callers keep both token values out of argv/env. */
+export declare function renderWarpMdm(options: {
+    organization: string;
+    clientId: string;
+    clientSecret: string;
+}): string;
+/**
+ * Materialize enrollment only in /run. The durable /var/lib path is a symlink,
+ * so neither service-token half is left as plaintext on the filesystem.
+ */
+export declare function materializeWarpMdm(options: {
+    organization: string;
+    clientId: string;
+    clientSecret: string;
+    runtimePath?: string;
+    servicePath?: string;
+}): {
+    runtimePath: string;
+    servicePath: string;
+};

package/package.json

@@ -1,12 +1,12 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.22",
+	"version": "0.1.23",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm --packages external && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm --packages external && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/deployment-runner.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm --packages external && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm --packages external && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/ubuntu.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"devDependencies": {
@@ -88,6 +88,14 @@
 			"types": "./dist/provisioning-pull.d.ts",
 			"default": "./dist/provisioning-pull.js"
 		},
+		"./migration-pull": {
+			"types": "./dist/migration-pull.d.ts",
+			"default": "./dist/migration-pull.js"
+		},
+		"./lifecycle-helper": {
+			"types": "./dist/lifecycle-helper.d.ts",
+			"default": "./dist/lifecycle-helper.js"
+		},
 		"./metal-provision": {
 			"types": "./dist/metal-provision.d.ts",
 			"default": "./dist/metal-provision.js"