@forgezero/agent 0.1.38 → 0.1.39

package/dist/cli/cloudflare-bootstrap.d.ts

@@ -1,4 +1,4 @@
-import { type AttendedCloudflareBootstrapRequest, type CloudflareBootstrapEvidence, type CloudflareBootstrapPhaseRunner } from '../cloudflare-bootstrap';
+import { verifyCloudflareBootstrapAcceptance, type AttendedCloudflareBootstrapRequest, type CloudflareBootstrapEvidence, type CloudflareBootstrapAcceptanceEvidence, type CloudflareBootstrapPhaseRunner } from '../cloudflare-bootstrap';
 export interface CloudflareBootstrapCommandDependencies {
     run?: CloudflareBootstrapPhaseRunner;
     write?: (text: string) => void;
@@ -9,3 +9,7 @@ export interface CloudflareBootstrapCommandDependencies {
  */
 export declare function readCloudflareBootstrapCommandConfig(path: string, mode: 'plan' | 'apply'): AttendedCloudflareBootstrapRequest;
 export declare function runCloudflareBootstrapCommand(configPath: string, apply: boolean, dependencies?: CloudflareBootstrapCommandDependencies): Promise<CloudflareBootstrapEvidence>;
+export declare function runCloudflareBootstrapVerificationCommand(checkpointPath: string, dependencies?: {
+    verify?: typeof verifyCloudflareBootstrapAcceptance;
+    write?: (text: string) => void;
+}): Promise<CloudflareBootstrapAcceptanceEvidence>;

package/dist/cloudflare-bootstrap.d.ts

@@ -144,10 +144,28 @@ export interface CloudflareBootstrapEvidence {
     nodes: ReadonlyArray<{
         nodeName: string;
         hostname: string;
+        /** Owner-only, node-specific input for `fz bootstrap platform`. */
+        handoffFile?: string;
         tunnelId?: string;
         applicationId?: string;
     }>;
 }
+/** Secret-free proof that the already-provisioned edge reaches live APIs. */
+export interface CloudflareBootstrapAcceptanceEvidence {
+    format: 1;
+    kind: 'forgezero-cloudflare-bootstrap-acceptance';
+    checkpointFile: string;
+    verifiedAt: string;
+    nodes: ReadonlyArray<{
+        nodeName: string;
+        hostname: string;
+        status: number;
+    }>;
+    publicDomains: ReadonlyArray<{
+        hostname: string;
+        status: number;
+    }>;
+}
 export interface CloudflareBootstrapDependencies {
     fetcher?: typeof fetch;
     workerRunner?: CloudflareWorkerCommandRunner;
@@ -191,6 +209,8 @@ export interface CloudflareHostHandoff extends CloudflareConnectorHandoff {
         deviceProfileId: string;
     };
 }
+/** Deterministic private output path; safe to include in secret-free evidence. */
+export declare function cloudflareHostHandoffPath(checkpointPath: string, nodeName: string): string;
 /**
  * Select one node's connector credential directly from the completed fleet
  * checkpoint. Host bootstrap can pipe this value into `systemd-creds` without
@@ -199,8 +219,7 @@ export interface CloudflareHostHandoff extends CloudflareConnectorHandoff {
  */
 export declare function readCloudflareConnectorHandoff(checkpointPath: string, nodeName: string): Promise<CloudflareConnectorHandoff>;
 /** Complete secret-bearing handoff consumed once by root host bootstrap. */
-export declare function readCloudflareHostHandoff(checkpointPath: string, nodeName: string): Promise<CloudflareHostHandoff>;
-/** Atomically persist sensitive bootstrap material without making it runtime configuration. */
+export declare function readCloudflareHostHandoff(handoffPath: string, nodeName: string): Promise<CloudflareHostHandoff>;
 export declare function writeOwnerBootstrapOutput(path: string, output: CloudflareBootstrapOutput): Promise<void>;
 /**
  * Attended, resumable Cloudflare bootstrap. The output is checkpointed after
@@ -215,4 +234,14 @@ export declare function applyCloudflareBootstrap(input: CloudflareBootstrapCoord
  * a deliberately secret-free evidence record to the outer bootstrap journal.
  */
 export declare function runAttendedCloudflareBootstrap(request: AttendedCloudflareBootstrapRequest, dependencies?: CloudflareBootstrapDependencies): Promise<CloudflareBootstrapEvidence>;
+/**
+ * Prove the post-bootstrap data path from an operator machine.
+ *
+ * This deliberately reads only the completed owner checkpoint. The Access
+ * service credential is used in request headers for each origin and is never
+ * returned, logged, copied to a host, or accepted on argv. Public Worker
+ * domains are then checked without privileged headers, proving the same route
+ * a client uses after KV heartbeats are active.
+ */
+export declare function verifyCloudflareBootstrapAcceptance(checkpointPath: string, fetcher?: typeof fetch): Promise<CloudflareBootstrapAcceptanceEvidence>;
 export {};

package/dist/cloudflare-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,13 +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
+  };
+}
 export {
   writeOwnerBootstrapOutput,
+  verifyCloudflareBootstrapAcceptance,
   validateCloudflareBootstrapCoordinates,
   runAttendedCloudflareBootstrap,
   readOwnerApiToken,
@@ -1192,5 +1332,6 @@ export {
   readCloudflareBootstrapTokens,
   planCloudflareBootstrap,
   deployCloudflareWorker,
+  cloudflareHostHandoffPath,
   applyCloudflareBootstrap
 };

package/dist/deployment-pull.d.ts

@@ -38,6 +38,8 @@ export interface DeploymentPullOptions {
     clearTimer?: (handle: unknown) => void;
     onEvent?: (event: string, detail?: unknown) => void;
     telemetry?: AgentOperationTelemetry;
+    /** Fail-closed desired-state gate. False means do not contact the claim route. */
+    canClaim?: () => boolean;
 }
 export type PullResult = {
     status: 'idle';