@forgezero/agent 0.1.37 → 0.1.39

package/dist/bootstrap.js

@@ -411,6 +411,22 @@ import { dirname, join, resolve } from "path";
 import { tmpdir } from "os";
 import { randomUUID } from "crypto";
 import { isIP as isIP2 } from "net";
+var acceptanceFetch = async (url, label, fetcher, headers) => {
+  let response;
+  try {
+    response = await fetcher(url, {
+      method: "GET",
+      headers,
+      redirect: "manual",
+      signal: AbortSignal.timeout(5000)
+    });
+  } catch {
+    throw new Error(`${label} is unreachable`);
+  }
+  if (!response.ok)
+    throw new Error(`${label} returned HTTP ${response.status}`);
+  return response.status;
+};
 var ownerUid = () => typeof process.getuid === "function" ? process.getuid() : undefined;
 async function assertOwnerOnlyHandle(path, handle, maximumBytes) {
   const metadata = await handle.stat();
@@ -739,6 +755,12 @@ async function readExistingOutput(path) {
   }
   return output;
 }
+function cloudflareHostHandoffPath(checkpointPath, nodeName) {
+  const normalized = nodeName.trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(normalized))
+    throw new Error("Cloudflare host handoff node name is invalid");
+  return join(`${resolve(checkpointPath)}.hosts`, `${normalized}.json`);
+}
 async function readCloudflareConnectorHandoff(checkpointPath, nodeName) {
   const output = await readExistingOutput(resolve(checkpointPath));
   if (!output || output.phase !== "complete") {
@@ -766,40 +788,66 @@ async function readCloudflareConnectorHandoff(checkpointPath, nodeName) {
     connectorToken: resource.connectorToken
   };
 }
-async function readCloudflareHostHandoff(checkpointPath, nodeName) {
-  const connector = await readCloudflareConnectorHandoff(checkpointPath, nodeName);
-  const output = await readExistingOutput(resolve(checkpointPath));
-  const kv = output?.resources.runtimeTokens?.kv;
-  if (!output || output.phase !== "complete" || !/^[a-f0-9]{32}$/i.test(output.coordinates.accountId) || !/^[a-f0-9]{32}$/i.test(output.coordinates.zoneId) || !/^[a-f0-9]{32}$/i.test(output.resources.kvNamespaceId) || !kv || !/^[A-Za-z0-9._-]{40,80}$/.test(kv.value)) {
-    throw new Error("Cloudflare host handoff is missing the exact-account KV runtime capability");
+async function readCloudflareHostHandoff(handoffPath, nodeName) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readOwnerOnlyFile(handoffPath, 65536));
+  } catch (cause) {
+    if (cause instanceof SyntaxError)
+      throw new Error("Cloudflare host handoff is not valid JSON");
+    throw cause;
   }
-  const network = output.resources.runtimeTokens?.privateNetwork?.value;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new Error("Cloudflare host handoff is malformed");
+  const output = parsed;
+  const unknown = Object.keys(output).filter((key) => ![
+    "format",
+    "kind",
+    "nodeName",
+    "hostname",
+    "service",
+    "tunnelId",
+    "connectorToken",
+    "accountId",
+    "zoneId",
+    "kvNamespaceId",
+    "kvRuntimeToken",
+    "privateNetworkRuntimeToken",
+    "warp"
+  ].includes(key));
+  if (unknown.length)
+    throw new Error(`Cloudflare host handoff contains unsupported field ${unknown[0]}`);
+  if (output.warp) {
+    const unknownWarp = Object.keys(output.warp).filter((key) => ![
+      "organization",
+      "clientId",
+      "clientSecret",
+      "virtualNetworkId",
+      "deviceProfileId"
+    ].includes(key));
+    if (unknownWarp.length)
+      throw new Error(`Cloudflare host handoff WARP contains unsupported field ${unknownWarp[0]}`);
+  }
+  const normalizedNodeName = nodeName.trim().toLowerCase();
+  let service;
+  try {
+    service = new URL(output.service ?? "");
+  } catch {}
+  if (output.format !== 1 || output.kind !== "forgezero-cloudflare-host-handoff" || output.nodeName !== normalizedNodeName || !/^[a-f0-9]{32}$/i.test(output.accountId ?? "") || !/^[a-f0-9]{32}$/i.test(output.zoneId ?? "") || !/^[a-f0-9]{32}$/i.test(output.kvNamespaceId ?? "") || !/^[A-Za-z0-9._-]{40,80}$/.test(output.kvRuntimeToken ?? "") || !output.hostname || !/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(output.hostname) || !service || service.protocol !== "http:" || service.hostname !== "127.0.0.1" || !service.port || service.pathname !== "/" || service.username || service.password || service.search || service.hash || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(output.tunnelId ?? "") || !/^[A-Za-z0-9._-]{40,16384}$/.test(output.connectorToken ?? "")) {
+    throw new Error("Cloudflare host handoff is malformed or belongs to another node");
+  }
+  const network = output.privateNetworkRuntimeToken;
   if (network !== undefined && !/^[A-Za-z0-9._-]{40,80}$/.test(network)) {
     throw new Error("Cloudflare host handoff private-network capability is malformed");
   }
-  const privateNetwork = output.resources.privateNetwork;
-  const access = output.resources.access;
-  if (Boolean(privateNetwork) !== Boolean(network)) {
+  if (Boolean(output.warp) !== Boolean(network)) {
     throw new Error("Cloudflare host handoff private-network resources and capability disagree");
   }
-  if (privateNetwork && (!access?.clientId || !access.clientSecret || !/^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/.test(privateNetwork.warpOrganization) || !/^[0-9a-f-]{36}$/i.test(privateNetwork.virtualNetworkId) || !privateNetwork.deviceProfileId)) {
+  if (output.warp && (!output.warp.clientId || !output.warp.clientSecret || !/^[A-Za-z0-9][A-Za-z0-9-]{0,62}$/.test(output.warp.organization) || !/^[0-9a-f-]{36}$/i.test(output.warp.virtualNetworkId) || !output.warp.deviceProfileId)) {
     throw new Error("Cloudflare host handoff WARP enrollment is malformed");
   }
-  return {
-    ...connector,
-    accountId: output.coordinates.accountId,
-    zoneId: output.coordinates.zoneId,
-    kvNamespaceId: output.resources.kvNamespaceId,
-    kvRuntimeToken: kv.value,
-    ...network ? { privateNetworkRuntimeToken: network } : {},
-    ...privateNetwork && access ? { warp: {
-      organization: privateNetwork.warpOrganization,
-      clientId: access.clientId,
-      clientSecret: access.clientSecret,
-      virtualNetworkId: privateNetwork.virtualNetworkId,
-      deviceProfileId: privateNetwork.deviceProfileId
-    } } : {}
-  };
+  const { format: _format, kind: _kind, ...handoff } = output;
+  return handoff;
 }
 async function prepareOwnerOutputDirectory(absolutePath) {
   const directory = dirname(absolutePath);
@@ -811,7 +859,7 @@ async function prepareOwnerOutputDirectory(absolutePath) {
   }
   return directory;
 }
-async function writeOwnerBootstrapOutput(path, output) {
+async function writeOwnerJson(path, output) {
   const absolute = resolve(path);
   const directory = await prepareOwnerOutputDirectory(absolute);
   const temporary = `${absolute}.${randomUUID()}.tmp`;
@@ -839,6 +887,42 @@ async function writeOwnerBootstrapOutput(path, output) {
     });
   }
 }
+async function writeOwnerBootstrapOutput(path, output) {
+  await writeOwnerJson(path, output);
+}
+async function writeCloudflareHostHandoffs(checkpointPath, output) {
+  const kv = output.resources.runtimeTokens?.kv?.value;
+  if (!kv || !/^[A-Za-z0-9._-]{40,80}$/.test(kv)) {
+    return;
+  }
+  const network = output.resources.runtimeTokens?.privateNetwork?.value;
+  const privateNetwork = output.resources.privateNetwork;
+  const access = output.resources.access;
+  for (const node of output.resources.nodes) {
+    const handoff = {
+      format: 1,
+      kind: "forgezero-cloudflare-host-handoff",
+      nodeName: node.nodeName,
+      hostname: node.hostname,
+      service: node.service,
+      tunnelId: node.tunnelId,
+      connectorToken: node.connectorToken,
+      accountId: output.coordinates.accountId,
+      zoneId: output.coordinates.zoneId,
+      kvNamespaceId: output.resources.kvNamespaceId,
+      kvRuntimeToken: kv,
+      ...network ? { privateNetworkRuntimeToken: network } : {},
+      ...privateNetwork && access ? { warp: {
+        organization: privateNetwork.warpOrganization,
+        clientId: access.clientId,
+        clientSecret: access.clientSecret,
+        virtualNetworkId: privateNetwork.virtualNetworkId,
+        deviceProfileId: privateNetwork.deviceProfileId
+      } } : {}
+    };
+    await writeOwnerJson(cloudflareHostHandoffPath(checkpointPath, node.nodeName), handoff);
+  }
+}
 var tokenFor = (tokens, key) => {
   const token = tokens[key]?.trim() || tokens.apiToken?.trim();
   if (!token)
@@ -1139,6 +1223,7 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
     }
   };
   await writeOwnerBootstrapOutput(absoluteOutput, output);
+  await writeCloudflareHostHandoffs(absoluteOutput, output);
   return output;
 }
 async function runAttendedCloudflareBootstrap(request, dependencies = {}) {
@@ -1177,14 +1262,68 @@ async function runAttendedCloudflareBootstrap(request, dependencies = {}) {
     nodes: output.resources.nodes.map(({ nodeName, hostname, tunnelId, applicationId }) => ({
       nodeName,
       hostname,
+      ...output.resources.runtimeTokens?.kv ? {
+        handoffFile: cloudflareHostHandoffPath(plan.outputFile, nodeName)
+      } : {},
       tunnelId,
       applicationId
     }))
   };
 }
+async function verifyCloudflareBootstrapAcceptance(checkpointPath, fetcher = fetch) {
+  const absolute = resolve(checkpointPath);
+  const output = await readExistingOutput(absolute);
+  if (!output || output.phase !== "complete")
+    throw new Error("Cloudflare acceptance requires a completed owner checkpoint");
+  const coordinates = validateCloudflareBootstrapCoordinates(output.coordinates);
+  const access = output.resources.access;
+  if (!access?.clientId?.trim() || !access.clientSecret?.trim()) {
+    throw new Error("Cloudflare acceptance checkpoint is missing the Access service credential");
+  }
+  if (!output.resources.worker?.deployed || output.resources.worker.scriptName !== coordinates.workerScriptName || JSON.stringify(output.resources.worker.publicDomains) !== JSON.stringify(coordinates.publicDomains)) {
+    throw new Error("Cloudflare acceptance checkpoint does not prove the expected Worker deployment");
+  }
+  if (output.resources.nodes.length !== coordinates.nodes.length) {
+    throw new Error("Cloudflare acceptance checkpoint does not cover the declared node fleet");
+  }
+  const nodeNames = new Set;
+  const hostnames = new Set;
+  for (const node of output.resources.nodes) {
+    const expected = coordinates.nodes.find((candidate) => candidate.nodeName === node.nodeName);
+    if (!expected || node.hostname !== expected.hostname || node.service !== expected.service || node.tunnelName !== expected.tunnelName || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(node.tunnelId)) {
+      throw new Error("Cloudflare acceptance checkpoint has an unbound node resource");
+    }
+    if (nodeNames.has(node.nodeName) || hostnames.has(node.hostname)) {
+      throw new Error("Cloudflare acceptance checkpoint has duplicate node coordinates");
+    }
+    nodeNames.add(node.nodeName);
+    hostnames.add(node.hostname);
+  }
+  const accessHeaders = {
+    "CF-Access-Client-Id": access.clientId,
+    "CF-Access-Client-Secret": access.clientSecret
+  };
+  const nodes = await Promise.all(output.resources.nodes.map(async ({ nodeName, hostname }) => ({
+    nodeName,
+    hostname,
+    status: await acceptanceFetch(`https://${hostname}/api/health`, `Cloudflare origin ${nodeName}`, fetcher, accessHeaders)
+  })));
+  const publicDomains = await Promise.all(output.resources.worker.publicDomains.map(async (hostname) => ({
+    hostname,
+    status: await acceptanceFetch(`https://${hostname}/api/health`, `Cloudflare public domain ${hostname}`, fetcher)
+  })));
+  return {
+    format: 1,
+    kind: "forgezero-cloudflare-bootstrap-acceptance",
+    checkpointFile: absolute,
+    verifiedAt: new Date().toISOString(),
+    nodes,
+    publicDomains
+  };
+}
 
 // src/bootstrap.ts
-import { createHmac, randomBytes } from "crypto";
+import { createHash, createHmac, randomBytes } from "crypto";
 import {
   chmodSync,
   existsSync,
@@ -1214,7 +1353,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.37";
+var VERSION = "0.1.39";
 
 // src/software.ts
 var BUN_INSTALLER_SHA256 = "bab8acfb046aac8c72407bdcce903957665d655d7acaa3e11c7c4616beae68dd";
@@ -2617,7 +2756,15 @@ var PLATFORM_BOOTSTRAP_PROFILES = [
   "platform-db-api",
   "platform-api"
 ];
-var STATE_PATH = "/var/lib/forgezero/bootstrap.json";
+function resolveInstalledBootstrapKind(states) {
+  if (states.compute && states.metal) {
+    throw new Error("host has both metal and compute bootstrap state; refusing an ambiguous operation");
+  }
+  return states.metal ? "metal" : states.compute ? "compute" : undefined;
+}
+var BOOTSTRAP_STATE_PATH = "/var/lib/forgezero/bootstrap.json";
+var STATE_PATH = BOOTSTRAP_STATE_PATH;
+var INTENT_PATH = "/var/lib/forgezero/bootstrap.intent.json";
 var CREDS = "/etc/forgezero/creds";
 var JWT_CREDENTIAL = `${CREDS}/arangodb-jwt.cred`;
 var ENROL_CREDENTIAL = `${CREDS}/enrol-token.cred`;
@@ -2627,9 +2774,13 @@ var BACKUP_RECOVERY_CREDENTIAL = `${CREDS}/backup-recovery-root.cred`;
 var WARP_CLIENT_ID_CREDENTIAL = `${CREDS}/warp-auth-client-id.cred`;
 var WARP_CLIENT_SECRET_CREDENTIAL = `${CREDS}/warp-auth-client-secret.cred`;
 var BOOTSTRAP_SSH_CREDENTIAL = `${CREDS}/bootstrap-ssh-key.cred`;
+var GIT_PUBLIC_KEY = "/etc/forgezero/git/deploy.pub";
 var PLATFORM_ENROL_SOURCE = "/run/forgezero-platform-enrol-token";
 var DB_MODE_EVIDENCE = "/var/lib/forgezero-cluster/server-mode.json";
 var LIFECYCLE_PROFILE = "/etc/forgezero/lifecycle.json";
+var CONTROL_SOCKET = "/run/forgezero/control.sock";
+var CLOUDFLARED_METRICS_ADDRESS = "127.0.0.1:20241";
+var CLOUDFLARED_DIAGNOSTICS_URL = `http://${CLOUDFLARED_METRICS_ADDRESS}/diag/tunnel`;
 var PACKAGED_AGENT_BIN = fileURLToPath(new URL("./fz-agent.js", import.meta.url));
 var privateOrigin = (value) => {
   let url;
@@ -2722,12 +2873,16 @@ function validateBootstrapConfig(value) {
   if (expected.role && value.database.role !== expected.role || value.database.serverMode !== expected.mode || value.profile === "platform-db-api" && !["master", "joiner"].includes(value.database.role)) {
     throw new Error("platform profile, database role and Coordinator mode disagree");
   }
+  if (!["member", "none"].includes(value.database.agency) || value.database.role === "master" && value.database.agency !== "member" || value.database.role === "none" && value.database.agency !== "none") {
+    throw new Error("database role and Agency participation disagree");
+  }
   if (value.database.role !== "none" && !value.database.address)
     throw new Error("database nodes require a private address");
   if (value.database.role === "joiner" && !value.database.master)
     throw new Error("database joiners require the master starter address");
-  if (!/^(?:dev-)?fz-n[1-9][0-9]{0,2}$/.test(value.computeReference))
+  if (!/^[a-z0-9](?:[a-z0-9:_-]{0,126}[a-z0-9])?$/.test(value.computeReference)) {
     throw new Error("platform compute reference is malformed");
+  }
   if (!value.database.bootstrapSecretFile)
     throw new Error("platform bootstrap requires the shared cluster bootstrap-code file");
   const write = value.database.coordinators.map(privateOrigin);
@@ -2753,10 +2908,10 @@ function validateBootstrapConfig(value) {
   if (value.firewall.enabled && (value.firewall.privateCidrs.length < 1 || new Set(value.firewall.privateCidrs).size !== value.firewall.privateCidrs.length)) {
     throw new Error("enabled firewall requires unique private cluster CIDRs");
   }
-  if (Number(value.computeReference.match(/n(\d+)$/)?.[1]) > 3 && !value.platformEnrolTokenFile) {
-    throw new Error("post-genesis platform computes require an API-issued enrolment token file");
+  if (!["genesis-derived", "api-token"].includes(value.enrolment.source) || value.enrolment.source === "api-token" && !value.enrolment.tokenFile || value.enrolment.source === "genesis-derived" && value.enrolment.tokenFile) {
+    throw new Error("platform enrolment source and token file disagree");
   }
-  if (value.cloudflareHandoff && (!value.installCloudflared || !value.cloudflareHandoff.checkpointFile || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.cloudflareHandoff.nodeName))) {
+  if (value.cloudflareHandoff && (!value.installCloudflared || !value.cloudflareHandoff.handoffFile || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(value.cloudflareHandoff.nodeName))) {
     throw new Error("Cloudflare handoff requires cloudflared installation, a checkpoint and a valid node name");
   }
   value.runtime.environment = runtime;
@@ -2812,8 +2967,9 @@ var unitEscape = (value) => {
 function databaseUnit(config) {
   const db = config.database;
   const join2 = db.role === "joiner" ? ` --starter.join=${unitEscape(db.master)}` : "";
+  const agency = db.agency === "none" ? " --cluster.start-agent=false --cluster.start-coordinator=true --cluster.start-dbserver=true" : "";
   return `[Unit]
-Description=ForgeZero ArangoDB Community 3.11.14 cluster (${db.role})
+Description=ForgeZero ArangoDB Community 3.11.14 cluster (${db.role}; agency=${db.agency})
 After=network-online.target
 Wants=network-online.target
 
@@ -2822,7 +2978,7 @@ Type=simple
 User=arangodb
 Group=arangodb
 LoadCredentialEncrypted=arangodb-jwt:${JWT_CREDENTIAL}
-ExecStart=/usr/bin/arangodb --starter.mode=cluster --starter.address=${unitEscape(db.address)} --starter.host=${unitEscape(db.address)} --starter.data-dir=/var/lib/forgezero-cluster --auth.jwt-secret=%d/arangodb-jwt${join2}
+ExecStart=/usr/bin/arangodb --starter.mode=cluster --starter.address=${unitEscape(db.address)} --starter.host=${unitEscape(db.address)} --starter.data-dir=/var/lib/forgezero-cluster --auth.jwt-secret=%d/arangodb-jwt${join2}${agency}
 Restart=always
 RestartSec=5
 UMask=0077
@@ -2878,7 +3034,7 @@ Wants=network-online.target
 Type=simple
 DynamicUser=yes
 LoadCredentialEncrypted=cloudflared-token:${TUNNEL_CREDENTIAL}
-ExecStart=/usr/local/bin/cloudflared tunnel --no-autoupdate run --token-file %d/cloudflared-token
+ExecStart=/usr/local/bin/cloudflared tunnel --no-autoupdate --metrics ${CLOUDFLARED_METRICS_ADDRESS} run --token-file %d/cloudflared-token
 Restart=always
 RestartSec=5
 NoNewPrivileges=true
@@ -2890,6 +3046,60 @@ ProtectHome=true
 WantedBy=multi-user.target
 `;
 }
+function parseCloudflaredTunnelDiagnostics(raw, expectedTunnelId) {
+  if (raw.length > 64 * 1024)
+    throw new Error("cloudflared tunnel diagnostics exceed 64 KiB");
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("cloudflared tunnel diagnostics are not JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("cloudflared tunnel diagnostics are malformed");
+  }
+  const diagnostics = value;
+  if (diagnostics.tunnelID !== expectedTunnelId)
+    throw new Error("cloudflared is connected to the wrong tunnel");
+  if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(diagnostics.connectorID ?? "")) {
+    throw new Error("cloudflared connector identity is missing");
+  }
+  if (!Array.isArray(diagnostics.connections) || diagnostics.connections.length !== 4 || diagnostics.connections.some((connection) => !connection || typeof connection !== "object" || connection.isConnected !== true)) {
+    throw new Error("cloudflared does not have four connected edge sessions");
+  }
+  return diagnostics;
+}
+async function inspectCloudflaredTunnel(host, expectedTunnelId) {
+  const result = await host.exec([
+    "curl",
+    "--fail",
+    "--silent",
+    "--show-error",
+    "--max-time",
+    "5",
+    CLOUDFLARED_DIAGNOSTICS_URL
+  ]);
+  if (result.exitCode !== 0)
+    return { healthy: false, problem: "cloudflared diagnostics endpoint is unreachable" };
+  try {
+    parseCloudflaredTunnelDiagnostics(result.output, expectedTunnelId);
+    return { healthy: true };
+  } catch (cause) {
+    return { healthy: false, problem: cause.message };
+  }
+}
+async function waitForCloudflaredTunnel(host, expectedTunnelId) {
+  let lastProblem = "cloudflared tunnel is not ready";
+  for (let attempt = 0;attempt < 30; attempt += 1) {
+    const evidence = await inspectCloudflaredTunnel(host, expectedTunnelId);
+    if (evidence.healthy)
+      return;
+    lastProblem = evidence.problem;
+    if (attempt < 29)
+      await (host.sleep?.(1000) ?? Bun.sleep(1000));
+  }
+  throw new Error(`cloudflared connector readiness failed: ${lastProblem}`);
+}
 var derive = (root, label) => {
   if (!/^[a-f0-9]{64}$/i.test(root))
     throw new Error("cluster bootstrap code must contain exactly 64 hexadecimal characters");
@@ -2902,21 +3112,157 @@ async function seal(host, name, destination, value) {
   if (result.exitCode !== 0)
     throw new Error(`could not seal ${name}: ${result.output.trim()}`);
 }
+function bootstrapIdentity(config) {
+  if (config.kind === "tenant")
+    return {
+      kind: config.kind,
+      apiUrl: config.apiUrl,
+      realm: config.realm,
+      nodeHostname: config.nodeHostname,
+      telemetryEndpoint: config.telemetryEndpoint,
+      repository: config.repository ?? null,
+      branch: config.branch ?? null,
+      profile: config.profile ?? "tenant-managed",
+      deployRoot: config.deployRoot ?? "/opt/forgezero",
+      software: (config.software ?? []).map(({ id, version }) => ({ id, version })),
+      installCloudflared: Boolean(config.installCloudflared),
+      bootstrapRunner: config.bootstrapRunner ? { targetTelemetryEndpoint: config.bootstrapRunner.targetTelemetryEndpoint } : null
+    };
+  const environment = config.runtime.environment;
+  return {
+    kind: config.kind,
+    environment: config.environment,
+    profile: config.profile,
+    computeReference: config.computeReference,
+    nodeHostname: config.nodeHostname,
+    apiUrl: config.apiUrl,
+    repository: config.repository,
+    branch: config.branch,
+    deployRoot: config.deployRoot ?? "/opt/forgezero",
+    telemetryEndpoint: config.telemetryEndpoint,
+    database: {
+      role: config.database.role,
+      serverMode: config.database.serverMode,
+      agency: config.database.agency,
+      address: config.database.address ?? null,
+      master: config.database.master ?? null,
+      coordinators: config.database.coordinators
+    },
+    enrolment: { source: config.enrolment.source },
+    runtime: {
+      serviceUser: config.runtime.serviceUser,
+      sharedDirectory: environment.sharedDirectory,
+      slotsDirectory: config.runtime.slotsDirectory,
+      bluePort: config.runtime.bluePort,
+      greenPort: config.runtime.greenPort,
+      publicApiPort: environment.publicApiPort,
+      healthPath: config.runtime.healthPath,
+      keepReleases: config.runtime.keepReleases,
+      environment
+    },
+    firewall: config.firewall,
+    installCloudflared: Boolean(config.installCloudflared)
+  };
+}
+function bootstrapIdentityDigest(config) {
+  return createHash("sha256").update(JSON.stringify(bootstrapIdentity(config))).digest("hex");
+}
+function parseStoredState(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("bootstrap state is malformed");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("bootstrap state is malformed");
+  const state = value;
+  if (state.format !== 2 || !["platform", "tenant"].includes(state.kind ?? "") || !/^[a-f0-9]{64}$/.test(state.identityDigest ?? "") || typeof state.profile !== "string" || typeof state.nodeHostname !== "string" || typeof state.apiUrl !== "string" || state.kind === "platform" && !["member", "none"].includes(state.databaseAgency ?? "")) {
+    throw new Error("bootstrap state is legacy or incomplete; refusing an unbound repair");
+  }
+  return state;
+}
+function parseStoredIntent(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("bootstrap intent is malformed");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("bootstrap intent is malformed");
+  const intent = value;
+  if (intent.format !== 1 || !["platform", "tenant"].includes(intent.kind ?? "") || !/^[a-f0-9]{64}$/.test(intent.identityDigest ?? "") || Number.isNaN(Date.parse(intent.createdAt ?? ""))) {
+    throw new Error("bootstrap intent is incomplete; refusing an unbound resume");
+  }
+  return intent;
+}
+function bindBootstrapIntent(host, config) {
+  const identityDigest = bootstrapIdentityDigest(config);
+  if (host.exists(INTENT_PATH)) {
+    const intent = parseStoredIntent(host.read(INTENT_PATH));
+    if (intent.kind !== config.kind || intent.identityDigest !== identityDigest) {
+      throw new Error("bootstrap resume coordinates do not match the interrupted host intent");
+    }
+  } else if (!host.exists(STATE_PATH)) {
+    host.write(INTENT_PATH, `${JSON.stringify({
+      format: 1,
+      kind: config.kind,
+      identityDigest,
+      createdAt: new Date().toISOString()
+    }, null, 2)}
+`, 384);
+  }
+  return identityDigest;
+}
+async function preparePlatformBootstrap(input, host = localBootstrapHost()) {
+  const config = validateBootstrapConfig(structuredClone(input));
+  if (config.kind !== "platform")
+    throw new Error("platform preparation requires a platform bootstrap config");
+  if (host.uid() !== 0)
+    throw new Error("fz bootstrap platform prepare --apply must run as root");
+  if (host.exists(STATE_PATH)) {
+    const installed = parseStoredState(host.read(STATE_PATH));
+    if (installed.kind !== "platform" || installed.identityDigest !== bootstrapIdentityDigest(config)) {
+      throw new Error("platform preparation coordinates do not match the installed host identity");
+    }
+  }
+  const identityDigest = bindBootstrapIntent(host, config);
+  await host.installAgent(config);
+  if (!host.exists(GIT_PUBLIC_KEY))
+    throw new Error("Agent installation did not produce its public Git deploy key");
+  const gitPublicKey = host.read(GIT_PUBLIC_KEY).trim();
+  if (!/^ssh-(?:ed25519|rsa) [A-Za-z0-9+/]+={0,3}(?: [^\r\n]+)?$/.test(gitPublicKey)) {
+    throw new Error("Agent public Git deploy key is malformed");
+  }
+  return {
+    kind: "platform",
+    prepared: true,
+    identityDigest,
+    gitPublicKey,
+    next: "register this read-only deploy key, then run --apply concurrently on all three genesis Agency members"
+  };
+}
 function stateFor(config) {
   return `${JSON.stringify({
-    format: 1,
+    format: 2,
     kind: config.kind,
     profile: config.kind === "platform" ? config.profile : config.profile ?? "tenant-managed",
     nodeHostname: config.nodeHostname,
     apiUrl: config.apiUrl,
+    identityDigest: bootstrapIdentityDigest(config),
     ...config.kind === "platform" ? {
       environment: config.environment,
       databaseRole: config.database.role,
+      databaseAgency: config.database.agency,
       databaseServerMode: config.database.serverMode,
       databaseAddress: config.database.address,
       databaseCoordinators: config.database.coordinators,
       databaseModeEvidence: config.database.role === "none" ? undefined : DB_MODE_EVIDENCE,
       collectorUnit: config.runtime.environment.otlpCollectorUnit,
+      publicApiPort: config.runtime.environment.publicApiPort,
+      healthPath: config.runtime.healthPath,
+      cloudflare: config.runtime.environment.cloudflare,
       cloudflared: Boolean(config.cloudflareHandoff)
     } : { realm: config.realm }
   }, null, 2)}
@@ -2927,9 +3273,9 @@ async function bootstrapStatus(host = localBootstrapHost()) {
     return { initialized: false, services: {}, problems: ["bootstrap state is missing"] };
   let state;
   try {
-    state = JSON.parse(host.read(STATE_PATH));
-  } catch {
-    return { initialized: false, services: {}, problems: ["bootstrap state is malformed"] };
+    state = parseStoredState(host.read(STATE_PATH));
+  } catch (cause) {
+    return { initialized: false, services: {}, problems: [cause.message] };
   }
   const units = ["forgezero-agent.service", "forgezero-agent.socket"];
   if (state.kind === "platform")
@@ -2948,7 +3294,39 @@ async function bootstrapStatus(host = localBootstrapHost()) {
     if (result.exitCode !== 0)
       problems.push(`${unit} is not active`);
   }
+  for (const socket of [DEFAULT_SOCKET2, CONTROL_SOCKET]) {
+    services[socket] = host.exists(socket);
+    if (!services[socket])
+      problems.push(`${socket} is missing`);
+  }
   if (state.kind === "platform") {
+    if (state.cloudflared) {
+      for (const credential of [TUNNEL_CREDENTIAL, `${CREDS}/cloudflare-kv-token.cred`]) {
+        services[credential] = host.exists(credential);
+        if (!services[credential])
+          problems.push(`${credential} is missing`);
+      }
+      if (state.cloudflare?.warp) {
+        for (const credential of [
+          `${CREDS}/cloudflare-network-token.cred`,
+          WARP_CLIENT_ID_CREDENTIAL,
+          WARP_CLIENT_SECRET_CREDENTIAL
+        ]) {
+          services[credential] = host.exists(credential);
+          if (!services[credential])
+            problems.push(`${credential} is missing`);
+        }
+      }
+      if (!state.cloudflare?.tunnelId) {
+        services["cloudflared-tunnel"] = false;
+        problems.push("Cloudflare tunnel identity is missing from bootstrap state");
+      } else {
+        const evidence = await inspectCloudflaredTunnel(host, state.cloudflare.tunnelId);
+        services["cloudflared-tunnel"] = evidence.healthy;
+        if (!evidence.healthy)
+          problems.push(evidence.problem);
+      }
+    }
     const [blue, green] = await Promise.all([
       host.exec(["systemctl", "is-active", "--quiet", "forgezero@blue.service"]),
       host.exec(["systemctl", "is-active", "--quiet", "forgezero@green.service"])
@@ -2956,6 +3334,48 @@ async function bootstrapStatus(host = localBootstrapHost()) {
     services["forgezero@active.service"] = blue.exitCode === 0 || green.exitCode === 0;
     if (!services["forgezero@active.service"])
       problems.push("neither API slot is active");
+    if (!Number.isSafeInteger(state.publicApiPort) || !state.healthPath) {
+      problems.push("platform health coordinates are missing from bootstrap state");
+    } else {
+      const health = await host.exec([
+        "curl",
+        "--fail",
+        "--silent",
+        "--show-error",
+        "--max-time",
+        "5",
+        `http://127.0.0.1:${state.publicApiPort}${state.healthPath}`
+      ]);
+      services["platform-api-health"] = health.exitCode === 0;
+      if (health.exitCode !== 0)
+        problems.push("platform API health check failed");
+    }
+    const nginx = await host.exec(["nginx", "-t"]);
+    services["nginx-config"] = nginx.exitCode === 0;
+    if (nginx.exitCode !== 0)
+      problems.push("nginx configuration is invalid");
+    if (state.databaseRole !== "none") {
+      const unitPath = "/etc/systemd/system/forgezero-db.service";
+      const expectsNoAgency = state.databaseAgency === "none";
+      const unitHasNoAgency = host.exists(unitPath) && host.read(unitPath).includes("--cluster.start-agent=false");
+      services["database-agency-profile"] = expectsNoAgency === unitHasNoAgency;
+      if (!services["database-agency-profile"])
+        problems.push("database Agency participation disagrees with the installed unit");
+      if (!state.databaseModeEvidence || !host.exists(state.databaseModeEvidence)) {
+        problems.push("database Coordinator-mode evidence is missing");
+      } else {
+        try {
+          const evidence = JSON.parse(host.read(state.databaseModeEvidence));
+          if (evidence.expectedMode !== "default" || evidence.role !== "COORDINATOR" || evidence.agency !== state.databaseAgency || evidence.unit !== "forgezero-db-verify.service" || Number.isNaN(Date.parse(String(evidence.verifiedAt)))) {
+            throw new Error("invalid evidence");
+          }
+          services["database-mode-evidence"] = true;
+        } catch {
+          services["database-mode-evidence"] = false;
+          problems.push("database Coordinator-mode evidence is malformed");
+        }
+      }
+    }
   }
   if (!host.exists("/var/lib/forgezero/enrolment.json"))
     problems.push("durable Agent enrolment state is missing");
@@ -2970,14 +3390,26 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
     if (!/^fze_[A-Za-z0-9_-]{32,128}$/.test(token))
       throw new Error("tenant enrolment token is malformed");
   }
+  let installed;
+  if (host.exists(STATE_PATH))
+    installed = parseStoredState(host.read(STATE_PATH));
   let cloudflare;
   if (config.kind === "platform" && config.cloudflareHandoff) {
-    cloudflare = await readCloudflareHostHandoff(config.cloudflareHandoff.checkpointFile, config.cloudflareHandoff.nodeName);
+    if (host.exists(config.cloudflareHandoff.handoffFile)) {
+      cloudflare = await readCloudflareHostHandoff(config.cloudflareHandoff.handoffFile, config.cloudflareHandoff.nodeName);
+    } else if (installed?.cloudflare) {
+      config.runtime.environment.cloudflare = installed.cloudflare;
+      config.runtime.environment = validatePlatformSharedEnvironment(config.runtime.environment);
+    } else {
+      throw new Error("node-specific Cloudflare host handoff is missing before credential sealing");
+    }
+  }
+  if (cloudflare && config.kind === "platform") {
     const expected = config.runtime.environment.cloudflare;
     if (cloudflare.hostname !== config.nodeHostname)
-      throw new Error("Cloudflare checkpoint hostname disagrees with platform node hostname");
+      throw new Error("Cloudflare handoff hostname disagrees with platform node hostname");
     if (expected && (cloudflare.service !== expected.tunnelService || cloudflare.accountId !== expected.accountId || cloudflare.zoneId !== expected.zoneId || cloudflare.kvNamespaceId !== expected.kvNamespaceId || cloudflare.tunnelId !== expected.tunnelId)) {
-      throw new Error("Cloudflare checkpoint disagrees with immutable platform runtime coordinates");
+      throw new Error("Cloudflare handoff disagrees with immutable platform runtime coordinates");
     }
     const discovered = {
       accountId: cloudflare.accountId,
@@ -2992,13 +3424,19 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
       } } : {}
     };
     if (expected && JSON.stringify(expected) !== JSON.stringify(discovered)) {
-      throw new Error("Cloudflare checkpoint disagrees with immutable WARP/runtime coordinates");
+      throw new Error("Cloudflare handoff disagrees with immutable WARP/runtime coordinates");
     }
     config.runtime.environment.cloudflare = expected ?? discovered;
     if (config.runtime.environment.databaseNetworkMode === "cloudflare-warp" !== Boolean(cloudflare.warp)) {
-      throw new Error("Cloudflare checkpoint private-network mode disagrees with the platform database network mode");
+      throw new Error("Cloudflare handoff private-network mode disagrees with the platform database network mode");
     }
   }
+  if (installed) {
+    if (installed.kind !== config.kind || installed.identityDigest !== bootstrapIdentityDigest(config)) {
+      throw new Error("bootstrap repair coordinates do not match the installed host identity");
+    }
+  }
+  bindBootstrapIntent(host, config);
   const plan = planBootstrap(config, host.exists(STATE_PATH));
   const alreadyEnrolled = host.exists("/var/lib/forgezero/enrolment.json");
   host.mkdir(CREDS, 448);
@@ -3011,7 +3449,7 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
     await seal(host, "warp-auth-client-id", WARP_CLIENT_ID_CREDENTIAL, cloudflare.warp.clientId);
     await seal(host, "warp-auth-client-secret", WARP_CLIENT_SECRET_CREDENTIAL, cloudflare.warp.clientSecret);
   }
-  await host.installAgent(config, alreadyEnrolled && config.kind === "platform" ? PLATFORM_ENROL_SOURCE : undefined);
+  await host.installAgent(config);
   if (config.kind === "platform" && config.firewall.enabled) {
     await host.ensureSoftware(plan.software.filter(({ id }) => id === "ufw"));
   } else
@@ -3055,11 +3493,13 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
         await seal(host, "cloudflare-network-token", `${CREDS}/cloudflare-network-token.cred`, cloudflare.privateNetworkRuntimeToken);
     }
     const runtime = config.runtime;
+    const cloudflareConfigured = Boolean(runtime.environment.cloudflare);
+    const cloudflareNetworkConfigured = Boolean(runtime.environment.cloudflare?.warp);
     const envPath = `${runtime.environment.sharedDirectory}/.env`;
     const credentials = platformApiCredentialSpecs({
       smtp: Boolean(credentialFiles.smtpPassword),
-      cloudflareKv: Boolean(cloudflare),
-      cloudflareNetwork: Boolean(cloudflare?.privateNetworkRuntimeToken)
+      cloudflareKv: cloudflareConfigured,
+      cloudflareNetwork: cloudflareNetworkConfigured
     });
     const units = renderPlatformApiUnits({
       serviceUser: runtime.serviceUser,
@@ -3122,6 +3562,7 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
       const evidence = {
         expectedMode: "default",
         role: "COORDINATOR",
+        agency: config.database.agency,
         unit: "forgezero-db-verify.service",
         verifiedAt: new Date().toISOString()
       };
@@ -3129,7 +3570,7 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
 `, 384);
     }
     if (!alreadyEnrolled) {
-      const enrolToken = config.platformEnrolTokenFile ? privateFile(host, config.platformEnrolTokenFile, "platform enrolment token") : `fze_${derive(derive(root, "forgezero/cluster/arangodb-jwt/v1"), `forgezero/platform-enrolment/v1/${config.computeReference}`)}`;
+      const enrolToken = config.enrolment.source === "api-token" ? privateFile(host, config.enrolment.tokenFile, "platform enrolment token") : `fze_${derive(derive(root, "forgezero/cluster/arangodb-jwt/v1"), `forgezero/platform-enrolment/v1/${config.computeReference}`)}`;
       if (!/^fze_[A-Za-z0-9_-]{32,128}$/.test(enrolToken))
         throw new Error("platform enrolment token is malformed");
       host.write(PLATFORM_ENROL_SOURCE, `${enrolToken}
@@ -3146,22 +3587,32 @@ async function applyBootstrap(input, host = localBootstrapHost()) {
     ], "initial Agent deployment");
     if (!alreadyEnrolled) {
       await host.installAgent(config, PLATFORM_ENROL_SOURCE);
-      if (config.platformEnrolTokenFile)
-        host.remove(config.platformEnrolTokenFile);
+      if (config.enrolment.source === "api-token")
+        host.remove(config.enrolment.tokenFile);
     }
   }
-  if (config.kind === "platform" && cloudflare) {
-    if (!host.exists(TUNNEL_CREDENTIAL)) {
+  if (config.kind === "platform" && config.cloudflareHandoff) {
+    if (!host.exists(TUNNEL_CREDENTIAL) && cloudflare) {
       await seal(host, "cloudflared-token", TUNNEL_CREDENTIAL, cloudflare.connectorToken);
     }
+    if (!host.exists(TUNNEL_CREDENTIAL))
+      throw new Error("sealed cloudflared connector credential is missing");
     host.write("/etc/systemd/system/cloudflared.service", tunnelUnit(), 420);
     await checked(host, ["systemctl", "daemon-reload"], "cloudflared unit reload");
     await checked(host, ["systemctl", "enable", "--now", "cloudflared.service"], "cloudflared connector supervision");
+    const tunnelId = config.runtime.environment.cloudflare?.tunnelId;
+    if (!tunnelId)
+      throw new Error("Cloudflare tunnel identity is missing after handoff validation");
+    await waitForCloudflaredTunnel(host, tunnelId);
   }
   host.write(STATE_PATH, stateFor(config), 384);
   const status = await bootstrapStatus(host);
   if (!status.initialized)
     throw new Error(`bootstrap verification failed: ${status.problems.join("; ")}`);
+  host.remove(INTENT_PATH);
+  if (cloudflare && config.kind === "platform" && config.cloudflareHandoff) {
+    host.remove(config.cloudflareHandoff.handoffFile);
+  }
   let launch;
   if (config.kind === "platform" && config.database.role === "master") {
     const invitePath = `${config.runtime.environment.sharedDirectory}/platform-invite.token`;
@@ -3199,7 +3650,7 @@ function strictBootstrapDocument(value) {
     "deployRoot",
     "telemetryEndpoint",
     "database",
-    "platformEnrolTokenFile",
+    "enrolment",
     "runtime",
     "firewall",
     "installCloudflared",
@@ -3212,8 +3663,9 @@ function strictBootstrapDocument(value) {
   if (root.kind === "platform") {
     exactKeys(root.firewall, ["enabled", "sshPort", "privateCidrs"], "firewall config");
     if (root.cloudflareHandoff !== undefined)
-      exactKeys(root.cloudflareHandoff, ["checkpointFile", "nodeName"], "Cloudflare handoff");
-    exactKeys(root.database, ["role", "serverMode", "address", "master", "coordinators", "bootstrapSecretFile"], "database config");
+      exactKeys(root.cloudflareHandoff, ["handoffFile", "nodeName"], "Cloudflare handoff");
+    exactKeys(root.database, ["role", "agency", "serverMode", "address", "master", "coordinators", "bootstrapSecretFile"], "database config");
+    exactKeys(root.enrolment, ["source", "tokenFile"], "platform enrolment config");
     const runtime = exactKeys(root.runtime, [
       "environment",
       "serviceUser",
@@ -3274,7 +3726,7 @@ function strictBootstrapDocument(value) {
   } else if (root.kind === "tenant") {
     if (root.bootstrapRunner !== undefined)
       exactKeys(root.bootstrapRunner, ["sshPrivateKeyFile", "targetTelemetryEndpoint"], "bootstrap runner config");
-    for (const key of ["environment", "profile", "computeReference", "database", "platformEnrolTokenFile", "runtime", "cloudflareHandoff"]) {
+    for (const key of ["environment", "profile", "computeReference", "database", "enrolment", "runtime", "cloudflareHandoff"]) {
       if (root[key] !== undefined && key !== "profile")
         throw new Error(`tenant bootstrap cannot contain ${key}`);
     }
@@ -3321,6 +3773,7 @@ function localBootstrapHost() {
       return { regular: value.isFile(), symbolic: value.isSymbolicLink(), uid: value.uid, mode: value.mode, links: value.nlink, size: value.size };
     },
     exec: execute,
+    sleep: (milliseconds) => Bun.sleep(milliseconds),
     async ensureSoftware(requirements) {
       const result = await execute([
         "runuser",
@@ -3407,10 +3860,14 @@ function localBootstrapHost() {
 }
 export {
   validateBootstrapConfig,
+  resolveInstalledBootstrapKind,
   readBootstrapConfig,
+  preparePlatformBootstrap,
   planBootstrap,
   localBootstrapHost,
   bootstrapStatus,
+  bootstrapIdentityDigest,
   applyBootstrap,
-  PLATFORM_BOOTSTRAP_PROFILES
+  PLATFORM_BOOTSTRAP_PROFILES,
+  BOOTSTRAP_STATE_PATH
 };