@forgezero/agent 0.1.56 → 0.1.58

package/README.md

@@ -359,13 +359,14 @@ import type { CloudflareBootstrapTokens, CloudflareConnectorHandoff, CloudflareH
 <a id="forgezero-agent-cloudflare-edge"></a>
 ## @forgezero/agent/cloudflare-edge
 
-Strict Cloudflare REST operations used by the attended bootstrap controller. Named value imports: configureCloudflareEdge, configureCloudflareRealtimeSecrets, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute, ensureCloudflareTunnel, ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude, verifyCloudflareWorkerDurableObjects. Named type imports: CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig, CloudflareTunnel, CloudflareWarpIncludeConfig. Import only the names used by this file.
+Strict Cloudflare REST operations used by the attended bootstrap controller. Named value imports: configureCloudflareEdge, configureCloudflareRealtimeSecrets, discoverCloudflareBootstrapResources, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute, ensureCloudflareTunnel, ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude, verifyCloudflareWorkerDurableObjects. Named type imports: CloudflareBootstrapDiscovery, CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig, CloudflareTunnel, CloudflareWarpIncludeConfig. Import only the names used by this file.
 
 ```text
-import { configureCloudflareEdge, configureCloudflareRealtimeSecrets, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute, ensureCloudflareTunnel } from '@forgezero/agent/cloudflare-edge';
-import { ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude, verifyCloudflareWorkerDurableObjects } from '@forgezero/agent/cloudflare-edge';
-import type { CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig, CloudflareTunnel } from '@forgezero/agent/cloudflare-edge';
-import type { CloudflareWarpIncludeConfig } from '@forgezero/agent/cloudflare-edge';
+import { configureCloudflareEdge, configureCloudflareRealtimeSecrets, discoverCloudflareBootstrapResources, ensureCloudflareMeshConnector, ensureCloudflarePrivateDatabaseRoute, ensureCloudflarePrivateRoute } from '@forgezero/agent/cloudflare-edge';
+import { ensureCloudflareTunnel, ensureCloudflareWarpDatabaseInclude, ensureCloudflareWarpNetworkIncludes, removeCloudflarePrivateDatabaseRoute, removeCloudflarePrivateRoute, removeCloudflareWarpDatabaseInclude } from '@forgezero/agent/cloudflare-edge';
+import { verifyCloudflareWorkerDurableObjects } from '@forgezero/agent/cloudflare-edge';
+import type { CloudflareBootstrapDiscovery, CloudflareDurableObjectNamespace, CloudflareEdgeConfig, CloudflareMeshConnector, CloudflarePrivateRoute, CloudflarePrivateRouteConfig } from '@forgezero/agent/cloudflare-edge';
+import type { CloudflareTunnel, CloudflareWarpIncludeConfig } from '@forgezero/agent/cloudflare-edge';
 ```
 
 <a id="forgezero-agent-mesh-connector"></a>

package/dist/agent-heartbeat.js

@@ -749,7 +749,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.56";
+var VERSION3 = "0.1.58";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap.js

@@ -22,7 +22,7 @@ function privateDatabaseHostRoute(value) {
   return `${address}/${isIP(address) === 4 ? 32 : 128}`;
 }
 var endpoint = "https://api.cloudflare.com/client/v4";
-async function cf(config, path, init = {}, fetcher = fetch) {
+async function cfEnvelope(config, path, init = {}, fetcher = fetch) {
   const response = await fetcher(`${endpoint}${path}`, {
     ...init,
     headers: {
@@ -35,7 +35,68 @@ async function cf(config, path, init = {}, fetcher = fetch) {
   if (!response.ok || body.success !== true) {
     throw new Error(body.errors?.map(({ message }) => message).filter(Boolean).join("; ") || `Cloudflare returned HTTP ${response.status}`);
   }
-  return body.result;
+  return body;
+}
+async function cf(config, path, init = {}, fetcher = fetch) {
+  return (await cfEnvelope(config, path, init, fetcher)).result;
+}
+async function cfPages(config, path, perPage, fetcher) {
+  const output = [];
+  for (let page = 1;page <= 100; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const envelope = await cfEnvelope(config, `${path}${separator}page=${page}&per_page=${perPage}`, {}, fetcher);
+    const result = Array.isArray(envelope.result) ? envelope.result : [];
+    output.push(...result);
+    const totalPages = envelope.result_info?.total_pages;
+    if (Number.isInteger(totalPages) ? page >= totalPages : result.length < perPage)
+      return output;
+  }
+  throw new Error("Cloudflare pagination exceeded the reviewed 100-page bound");
+}
+var exactHexId = (value, label) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32}$/.test(normalized))
+    throw new Error(`${label} is malformed`);
+  return normalized;
+};
+async function discoverCloudflareBootstrapResources(config, fetcher = fetch) {
+  const zoneName = config.zoneName.trim().toLowerCase().replace(/\.$/, "");
+  const kvNamespaceTitle = config.kvNamespaceTitle.trim();
+  if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(zoneName)) {
+    throw new Error("Cloudflare zone name is invalid");
+  }
+  if (!kvNamespaceTitle || kvNamespaceTitle.length > 512) {
+    throw new Error("Cloudflare KV namespace title is invalid");
+  }
+  const [managementStatus, runtimeStatus] = await Promise.all([
+    cf({ apiToken: config.tunnelToken }, "/user/tokens/verify", {}, fetcher),
+    cf({ apiToken: config.apiToken }, "/user/tokens/verify", {}, fetcher)
+  ]);
+  if (managementStatus.status !== "active")
+    throw new Error("CF_TUNNEL_TOKEN is not active");
+  if (runtimeStatus.status !== "active")
+    throw new Error("CF_API_TOKEN is not active");
+  const zones = await cfPages({ apiToken: config.tunnelToken }, `/zones?name=${encodeURIComponent(zoneName)}&match=all&status=active`, 50, fetcher);
+  const matchingZones = zones.filter(({ name }) => name?.trim().toLowerCase() === zoneName);
+  if (matchingZones.length !== 1) {
+    throw new Error(`Cloudflare zone ${zoneName} must resolve to exactly one active zone`);
+  }
+  const zoneId = exactHexId(matchingZones[0].id, "Cloudflare zone id");
+  const accountId = exactHexId(matchingZones[0].account?.id, "Cloudflare account id");
+  const namespaces = await cfPages({ apiToken: config.apiToken }, `/accounts/${accountId}/storage/kv/namespaces?order=title&direction=asc`, 1000, fetcher);
+  const matchingNamespaces = namespaces.filter(({ title }) => title === kvNamespaceTitle);
+  if (matchingNamespaces.length !== 1) {
+    throw new Error(`Cloudflare KV namespace ${kvNamespaceTitle} must resolve to exactly one namespace`);
+  }
+  const kvNamespaceId = exactHexId(matchingNamespaces[0].id, "Cloudflare KV namespace id");
+  if (config.workerScriptName) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId,
+      scriptName: config.workerScriptName,
+      apiToken: config.apiToken
+    }, fetcher);
+  }
+  return { accountId, zoneId, kvNamespaceId };
 }
 async function ensureCloudflarePrivateRoute(config, fetcher = fetch) {
   const [address, prefixText, ...extra] = config.network.split("/");
@@ -211,7 +272,7 @@ async function verifyCloudflareWorkerDurableObjects(config, fetcher = fetch) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName)) {
     throw new Error("Cloudflare Worker script name is invalid");
   }
-  const namespaces = await cf(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces?per_page=1000`, {}, fetcher);
+  const namespaces = await cfPages(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces`, 1000, fetcher);
   const owned = namespaces.filter(({ script }) => script === config.scriptName);
   if (!owned.length)
     throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);
@@ -1207,7 +1268,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.56";
+var VERSION = "0.1.58";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";

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

@@ -1,14 +1,40 @@
-import { finalizeCloudflareBootstrapAcceptance, verifyCloudflareBootstrapAcceptance, type AttendedCloudflareBootstrapRequest, type CloudflareBootstrapEvidence, type CloudflareBootstrapAcceptanceEvidence, type CloudflareBootstrapFinalizeRequest, type CloudflareBootstrapPhaseRunner } from '../cloudflare-bootstrap';
+import { finalizeCloudflareBootstrapAcceptance, verifyCloudflareBootstrapAcceptance, type AttendedCloudflareBootstrapRequest, type CloudflareBootstrapEvidence, type CloudflareBootstrapAcceptanceEvidence, type CloudflareBootstrapFinalizeRequest, type CloudflareBootstrapPhaseRunner, type CloudflareBootstrapTokenFiles } from '../cloudflare-bootstrap';
+import { discoverCloudflareBootstrapResources, type CloudflareBootstrapDiscovery } from '../cloudflare-edge';
+export interface CloudflareBootstrapCommandConfig {
+    format: 1;
+    kind: 'forgezero-cloudflare-bootstrap-request';
+    checkpointPath: string;
+    coordinates: AttendedCloudflareBootstrapRequest['coordinates'];
+    tokenFiles: CloudflareBootstrapTokenFiles;
+}
 export interface CloudflareBootstrapCommandDependencies {
     run?: CloudflareBootstrapPhaseRunner;
     write?: (text: string) => void;
 }
+export declare function discoverCloudflareBootstrapCommandResources(input: {
+    zoneName: string;
+    kvNamespaceTitle: string;
+    workerScriptName?: string;
+    tokenFiles: CloudflareBootstrapTokenFiles;
+}, dependencies?: {
+    fetcher?: typeof fetch;
+    discover?: typeof discoverCloudflareBootstrapResources;
+}): Promise<CloudflareBootstrapDiscovery>;
 export interface CloudflareBootstrapFinalizeConfig {
     format: 1;
     kind: 'forgezero-cloudflare-bootstrap-finalize';
     checkpointPath: string;
     acceptancePath: string;
 }
+/**
+ * Construct the exact reviewed JSON shape used by both the interactive CLI and
+ * the strict file reader. Token values are deliberately not accepted here.
+ */
+export declare function createCloudflareBootstrapCommandConfig(input: {
+    checkpointPath: string;
+    coordinates: AttendedCloudflareBootstrapRequest['coordinates'];
+    tokenFiles: CloudflareBootstrapTokenFiles;
+}): CloudflareBootstrapCommandConfig;
 /**
  * Read reviewed non-secret coordinates and token-file paths for the attended
  * operator phase. Raw token values and a persisted mode are not schema fields.

package/dist/cloudflare-bootstrap.js

@@ -22,7 +22,7 @@ function privateDatabaseHostRoute(value) {
   return `${address}/${isIP(address) === 4 ? 32 : 128}`;
 }
 var endpoint = "https://api.cloudflare.com/client/v4";
-async function cf(config, path, init = {}, fetcher = fetch) {
+async function cfEnvelope(config, path, init = {}, fetcher = fetch) {
   const response = await fetcher(`${endpoint}${path}`, {
     ...init,
     headers: {
@@ -35,7 +35,68 @@ async function cf(config, path, init = {}, fetcher = fetch) {
   if (!response.ok || body.success !== true) {
     throw new Error(body.errors?.map(({ message }) => message).filter(Boolean).join("; ") || `Cloudflare returned HTTP ${response.status}`);
   }
-  return body.result;
+  return body;
+}
+async function cf(config, path, init = {}, fetcher = fetch) {
+  return (await cfEnvelope(config, path, init, fetcher)).result;
+}
+async function cfPages(config, path, perPage, fetcher) {
+  const output = [];
+  for (let page = 1;page <= 100; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const envelope = await cfEnvelope(config, `${path}${separator}page=${page}&per_page=${perPage}`, {}, fetcher);
+    const result = Array.isArray(envelope.result) ? envelope.result : [];
+    output.push(...result);
+    const totalPages = envelope.result_info?.total_pages;
+    if (Number.isInteger(totalPages) ? page >= totalPages : result.length < perPage)
+      return output;
+  }
+  throw new Error("Cloudflare pagination exceeded the reviewed 100-page bound");
+}
+var exactHexId = (value, label) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32}$/.test(normalized))
+    throw new Error(`${label} is malformed`);
+  return normalized;
+};
+async function discoverCloudflareBootstrapResources(config, fetcher = fetch) {
+  const zoneName = config.zoneName.trim().toLowerCase().replace(/\.$/, "");
+  const kvNamespaceTitle = config.kvNamespaceTitle.trim();
+  if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(zoneName)) {
+    throw new Error("Cloudflare zone name is invalid");
+  }
+  if (!kvNamespaceTitle || kvNamespaceTitle.length > 512) {
+    throw new Error("Cloudflare KV namespace title is invalid");
+  }
+  const [managementStatus, runtimeStatus] = await Promise.all([
+    cf({ apiToken: config.tunnelToken }, "/user/tokens/verify", {}, fetcher),
+    cf({ apiToken: config.apiToken }, "/user/tokens/verify", {}, fetcher)
+  ]);
+  if (managementStatus.status !== "active")
+    throw new Error("CF_TUNNEL_TOKEN is not active");
+  if (runtimeStatus.status !== "active")
+    throw new Error("CF_API_TOKEN is not active");
+  const zones = await cfPages({ apiToken: config.tunnelToken }, `/zones?name=${encodeURIComponent(zoneName)}&match=all&status=active`, 50, fetcher);
+  const matchingZones = zones.filter(({ name }) => name?.trim().toLowerCase() === zoneName);
+  if (matchingZones.length !== 1) {
+    throw new Error(`Cloudflare zone ${zoneName} must resolve to exactly one active zone`);
+  }
+  const zoneId = exactHexId(matchingZones[0].id, "Cloudflare zone id");
+  const accountId = exactHexId(matchingZones[0].account?.id, "Cloudflare account id");
+  const namespaces = await cfPages({ apiToken: config.apiToken }, `/accounts/${accountId}/storage/kv/namespaces?order=title&direction=asc`, 1000, fetcher);
+  const matchingNamespaces = namespaces.filter(({ title }) => title === kvNamespaceTitle);
+  if (matchingNamespaces.length !== 1) {
+    throw new Error(`Cloudflare KV namespace ${kvNamespaceTitle} must resolve to exactly one namespace`);
+  }
+  const kvNamespaceId = exactHexId(matchingNamespaces[0].id, "Cloudflare KV namespace id");
+  if (config.workerScriptName) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId,
+      scriptName: config.workerScriptName,
+      apiToken: config.apiToken
+    }, fetcher);
+  }
+  return { accountId, zoneId, kvNamespaceId };
 }
 async function ensureCloudflarePrivateRoute(config, fetcher = fetch) {
   const [address, prefixText, ...extra] = config.network.split("/");
@@ -211,7 +272,7 @@ async function verifyCloudflareWorkerDurableObjects(config, fetcher = fetch) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName)) {
     throw new Error("Cloudflare Worker script name is invalid");
   }
-  const namespaces = await cf(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces?per_page=1000`, {}, fetcher);
+  const namespaces = await cfPages(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces`, 1000, fetcher);
   const owned = namespaces.filter(({ script }) => script === config.scriptName);
   if (!owned.length)
     throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);

package/dist/cloudflare-edge.d.ts

@@ -7,6 +7,24 @@ export interface CloudflareEdgeConfig {
     /** The single attended management capability used for both Tunnel and DNS writes. */
     apiToken: string;
 }
+export interface CloudflareBootstrapDiscovery {
+    accountId: string;
+    zoneId: string;
+    kvNamespaceId: string;
+}
+/**
+ * Resolve stable Cloudflare ids from owner-recognizable names without ever
+ * persisting or printing either token. The management token is used only for
+ * the exact zone lookup; the runtime token is used only for the existing KV
+ * namespace and optional Worker/DO ownership proof.
+ */
+export declare function discoverCloudflareBootstrapResources(config: {
+    zoneName: string;
+    kvNamespaceTitle: string;
+    workerScriptName?: string;
+    tunnelToken: string;
+    apiToken: string;
+}, fetcher?: typeof fetch): Promise<CloudflareBootstrapDiscovery>;
 export interface CloudflarePrivateRouteConfig {
     accountId: string;
     tunnelId: string;

package/dist/cloudflare-edge.js

@@ -22,7 +22,7 @@ function privateDatabaseHostRoute(value) {
   return `${address}/${isIP(address) === 4 ? 32 : 128}`;
 }
 var endpoint = "https://api.cloudflare.com/client/v4";
-async function cf(config, path, init = {}, fetcher = fetch) {
+async function cfEnvelope(config, path, init = {}, fetcher = fetch) {
   const response = await fetcher(`${endpoint}${path}`, {
     ...init,
     headers: {
@@ -35,7 +35,68 @@ async function cf(config, path, init = {}, fetcher = fetch) {
   if (!response.ok || body.success !== true) {
     throw new Error(body.errors?.map(({ message }) => message).filter(Boolean).join("; ") || `Cloudflare returned HTTP ${response.status}`);
   }
-  return body.result;
+  return body;
+}
+async function cf(config, path, init = {}, fetcher = fetch) {
+  return (await cfEnvelope(config, path, init, fetcher)).result;
+}
+async function cfPages(config, path, perPage, fetcher) {
+  const output = [];
+  for (let page = 1;page <= 100; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const envelope = await cfEnvelope(config, `${path}${separator}page=${page}&per_page=${perPage}`, {}, fetcher);
+    const result = Array.isArray(envelope.result) ? envelope.result : [];
+    output.push(...result);
+    const totalPages = envelope.result_info?.total_pages;
+    if (Number.isInteger(totalPages) ? page >= totalPages : result.length < perPage)
+      return output;
+  }
+  throw new Error("Cloudflare pagination exceeded the reviewed 100-page bound");
+}
+var exactHexId = (value, label) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32}$/.test(normalized))
+    throw new Error(`${label} is malformed`);
+  return normalized;
+};
+async function discoverCloudflareBootstrapResources(config, fetcher = fetch) {
+  const zoneName = config.zoneName.trim().toLowerCase().replace(/\.$/, "");
+  const kvNamespaceTitle = config.kvNamespaceTitle.trim();
+  if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(zoneName)) {
+    throw new Error("Cloudflare zone name is invalid");
+  }
+  if (!kvNamespaceTitle || kvNamespaceTitle.length > 512) {
+    throw new Error("Cloudflare KV namespace title is invalid");
+  }
+  const [managementStatus, runtimeStatus] = await Promise.all([
+    cf({ apiToken: config.tunnelToken }, "/user/tokens/verify", {}, fetcher),
+    cf({ apiToken: config.apiToken }, "/user/tokens/verify", {}, fetcher)
+  ]);
+  if (managementStatus.status !== "active")
+    throw new Error("CF_TUNNEL_TOKEN is not active");
+  if (runtimeStatus.status !== "active")
+    throw new Error("CF_API_TOKEN is not active");
+  const zones = await cfPages({ apiToken: config.tunnelToken }, `/zones?name=${encodeURIComponent(zoneName)}&match=all&status=active`, 50, fetcher);
+  const matchingZones = zones.filter(({ name }) => name?.trim().toLowerCase() === zoneName);
+  if (matchingZones.length !== 1) {
+    throw new Error(`Cloudflare zone ${zoneName} must resolve to exactly one active zone`);
+  }
+  const zoneId = exactHexId(matchingZones[0].id, "Cloudflare zone id");
+  const accountId = exactHexId(matchingZones[0].account?.id, "Cloudflare account id");
+  const namespaces = await cfPages({ apiToken: config.apiToken }, `/accounts/${accountId}/storage/kv/namespaces?order=title&direction=asc`, 1000, fetcher);
+  const matchingNamespaces = namespaces.filter(({ title }) => title === kvNamespaceTitle);
+  if (matchingNamespaces.length !== 1) {
+    throw new Error(`Cloudflare KV namespace ${kvNamespaceTitle} must resolve to exactly one namespace`);
+  }
+  const kvNamespaceId = exactHexId(matchingNamespaces[0].id, "Cloudflare KV namespace id");
+  if (config.workerScriptName) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId,
+      scriptName: config.workerScriptName,
+      apiToken: config.apiToken
+    }, fetcher);
+  }
+  return { accountId, zoneId, kvNamespaceId };
 }
 async function ensureCloudflarePrivateRoute(config, fetcher = fetch) {
   const [address, prefixText, ...extra] = config.network.split("/");
@@ -211,7 +272,7 @@ async function verifyCloudflareWorkerDurableObjects(config, fetcher = fetch) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName)) {
     throw new Error("Cloudflare Worker script name is invalid");
   }
-  const namespaces = await cf(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces?per_page=1000`, {}, fetcher);
+  const namespaces = await cfPages(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces`, 1000, fetcher);
   const owned = namespaces.filter(({ script }) => script === config.scriptName);
   if (!owned.length)
     throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);
@@ -294,6 +355,7 @@ export {
   ensureCloudflarePrivateRoute,
   ensureCloudflarePrivateDatabaseRoute,
   ensureCloudflareMeshConnector,
+  discoverCloudflareBootstrapResources,
   configureCloudflareRealtimeSecrets,
   configureCloudflareEdge
 };

package/dist/fz-agent.js

@@ -8448,7 +8448,7 @@ function assertSupportedGuestImage(imageKey) {
 }
 
 // src/version.ts
-var VERSION2 = "0.1.56";
+var VERSION2 = "0.1.58";
 
 // src/ssh-bootstrap.ts
 class SshBootstrapError extends Error {

package/dist/fz.js

@@ -4830,7 +4830,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION2 = "0.1.56";
+var VERSION2 = "0.1.58";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";
@@ -11958,7 +11958,7 @@ function isPrivateDatabaseAddress(value) {
   return false;
 }
 var endpoint = "https://api.cloudflare.com/client/v4";
-async function cf(config, path, init = {}, fetcher = fetch) {
+async function cfEnvelope(config, path, init = {}, fetcher = fetch) {
   const response = await fetcher(`${endpoint}${path}`, {
     ...init,
     headers: {
@@ -11971,7 +11971,68 @@ async function cf(config, path, init = {}, fetcher = fetch) {
   if (!response.ok || body.success !== true) {
     throw new Error(body.errors?.map(({ message }) => message).filter(Boolean).join("; ") || `Cloudflare returned HTTP ${response.status}`);
   }
-  return body.result;
+  return body;
+}
+async function cf(config, path, init = {}, fetcher = fetch) {
+  return (await cfEnvelope(config, path, init, fetcher)).result;
+}
+async function cfPages(config, path, perPage, fetcher) {
+  const output = [];
+  for (let page = 1;page <= 100; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const envelope = await cfEnvelope(config, `${path}${separator}page=${page}&per_page=${perPage}`, {}, fetcher);
+    const result = Array.isArray(envelope.result) ? envelope.result : [];
+    output.push(...result);
+    const totalPages = envelope.result_info?.total_pages;
+    if (Number.isInteger(totalPages) ? page >= totalPages : result.length < perPage)
+      return output;
+  }
+  throw new Error("Cloudflare pagination exceeded the reviewed 100-page bound");
+}
+var exactHexId = (value, label) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32}$/.test(normalized))
+    throw new Error(`${label} is malformed`);
+  return normalized;
+};
+async function discoverCloudflareBootstrapResources(config, fetcher = fetch) {
+  const zoneName = config.zoneName.trim().toLowerCase().replace(/\.$/, "");
+  const kvNamespaceTitle = config.kvNamespaceTitle.trim();
+  if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(zoneName)) {
+    throw new Error("Cloudflare zone name is invalid");
+  }
+  if (!kvNamespaceTitle || kvNamespaceTitle.length > 512) {
+    throw new Error("Cloudflare KV namespace title is invalid");
+  }
+  const [managementStatus, runtimeStatus] = await Promise.all([
+    cf({ apiToken: config.tunnelToken }, "/user/tokens/verify", {}, fetcher),
+    cf({ apiToken: config.apiToken }, "/user/tokens/verify", {}, fetcher)
+  ]);
+  if (managementStatus.status !== "active")
+    throw new Error("CF_TUNNEL_TOKEN is not active");
+  if (runtimeStatus.status !== "active")
+    throw new Error("CF_API_TOKEN is not active");
+  const zones = await cfPages({ apiToken: config.tunnelToken }, `/zones?name=${encodeURIComponent(zoneName)}&match=all&status=active`, 50, fetcher);
+  const matchingZones = zones.filter(({ name }) => name?.trim().toLowerCase() === zoneName);
+  if (matchingZones.length !== 1) {
+    throw new Error(`Cloudflare zone ${zoneName} must resolve to exactly one active zone`);
+  }
+  const zoneId = exactHexId(matchingZones[0].id, "Cloudflare zone id");
+  const accountId = exactHexId(matchingZones[0].account?.id, "Cloudflare account id");
+  const namespaces = await cfPages({ apiToken: config.apiToken }, `/accounts/${accountId}/storage/kv/namespaces?order=title&direction=asc`, 1000, fetcher);
+  const matchingNamespaces = namespaces.filter(({ title }) => title === kvNamespaceTitle);
+  if (matchingNamespaces.length !== 1) {
+    throw new Error(`Cloudflare KV namespace ${kvNamespaceTitle} must resolve to exactly one namespace`);
+  }
+  const kvNamespaceId = exactHexId(matchingNamespaces[0].id, "Cloudflare KV namespace id");
+  if (config.workerScriptName) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId,
+      scriptName: config.workerScriptName,
+      apiToken: config.apiToken
+    }, fetcher);
+  }
+  return { accountId, zoneId, kvNamespaceId };
 }
 async function ensureCloudflarePrivateRoute(config, fetcher = fetch) {
   const [address, prefixText, ...extra] = config.network.split("/");
@@ -12085,7 +12146,7 @@ async function verifyCloudflareWorkerDurableObjects(config, fetcher = fetch) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName)) {
     throw new Error("Cloudflare Worker script name is invalid");
   }
-  const namespaces = await cf(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces?per_page=1000`, {}, fetcher);
+  const namespaces = await cfPages(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces`, 1000, fetcher);
   const owned = namespaces.filter(({ script }) => script === config.scriptName);
   if (!owned.length)
     throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);
@@ -14337,6 +14398,15 @@ function localBootstrapHost() {
 // src/cli/cloudflare-bootstrap.ts
 import { constants as constants2, closeSync, fstatSync, openSync, readFileSync as readFileSync9 } from "fs";
 import { dirname as dirname9, resolve as resolve6 } from "path";
+async function discoverCloudflareBootstrapCommandResources(input, dependencies = {}) {
+  const tokens = await readCloudflareBootstrapTokens(input.tokenFiles);
+  return (dependencies.discover ?? discoverCloudflareBootstrapResources)({
+    zoneName: input.zoneName,
+    kvNamespaceTitle: input.kvNamespaceTitle,
+    ...input.workerScriptName ? { workerScriptName: input.workerScriptName } : {},
+    ...tokens
+  }, dependencies.fetcher);
+}
 var exactKeys3 = (value, allowed, label) => {
   const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
   if (unknown.length)
@@ -14347,6 +14417,26 @@ var record2 = (value, label) => {
     throw new Error(`${label} must be an object`);
   return value;
 };
+function createCloudflareBootstrapCommandConfig(input) {
+  if (typeof input.checkpointPath !== "string" || !input.checkpointPath.trim()) {
+    throw new Error("Cloudflare bootstrap checkpointPath is required");
+  }
+  for (const key of ["tunnelTokenFile", "apiTokenFile"]) {
+    if (typeof input.tokenFiles?.[key] !== "string" || !input.tokenFiles[key].trim()) {
+      throw new Error(`Cloudflare bootstrap tokenFiles.${key} is required and must be a non-empty file path`);
+    }
+  }
+  return {
+    format: 1,
+    kind: "forgezero-cloudflare-bootstrap-request",
+    checkpointPath: input.checkpointPath.trim(),
+    coordinates: validateCloudflareBootstrapCoordinates(input.coordinates),
+    tokenFiles: {
+      tunnelTokenFile: input.tokenFiles.tunnelTokenFile.trim(),
+      apiTokenFile: input.tokenFiles.apiTokenFile.trim()
+    }
+  };
+}
 function readOwnerConfig(path) {
   const absolute2 = resolve6(path);
   let descriptor;
@@ -17118,6 +17208,63 @@ function writeBootstrapConfig(path, config) {
 `, { mode: 384, flag: "wx" });
   return path;
 }
+async function interactiveCloudflareBootstrap() {
+  if (!process.stdin.isTTY)
+    throw new Error("interactive Cloudflare config generation requires a terminal");
+  const tokenFiles = {
+    tunnelTokenFile: bootstrapAnswer("Owner-only CF_TUNNEL_TOKEN file", "./CF_TUNNEL_TOKEN"),
+    apiTokenFile: bootstrapAnswer("Owner-only CF_API_TOKEN file", "./CF_API_TOKEN")
+  };
+  const zoneName = bootstrapAnswer("Cloudflare DNS zone name", "forgezero.net");
+  const kvNamespaceTitle = bootstrapAnswer("Existing Worker-bound KV namespace title");
+  const realtimeEnabled = bootstrapAnswer("Configure existing Worker realtime fan-out? (yes/no)", "yes") === "yes";
+  const workerScriptName = realtimeEnabled ? bootstrapAnswer("Existing Worker script name") : undefined;
+  const discovered = await discoverCloudflareBootstrapCommandResources({
+    zoneName,
+    kvNamespaceTitle,
+    ...workerScriptName ? { workerScriptName } : {},
+    tokenFiles
+  });
+  const nodeCount = bootstrapNumber("Number of public API nodes", "3");
+  if (nodeCount < 1 || nodeCount > 32)
+    throw new Error("Number of public API nodes must be between 1 and 32");
+  const meshEnabled = bootstrapAnswer("Configure private Mesh/WARP routes? (yes/no)", "no") === "yes";
+  const meshDevicePolicyId = meshEnabled ? bootstrapAnswer("Existing Mesh device policy id") : undefined;
+  const nodes = Array.from({ length: nodeCount }, (_, index) => {
+    const ordinal = index + 1;
+    const nodeName = bootstrapAnswer(`Node ${ordinal} inventory name`);
+    const nodeMesh = meshEnabled && bootstrapAnswer(`Configure Mesh routes for ${nodeName}? (yes/no)`, "yes") === "yes";
+    return {
+      nodeName,
+      hostname: bootstrapAnswer(`${nodeName} public hostname`),
+      service: bootstrapAnswer(`${nodeName} loopback API service`, "http://127.0.0.1:3000"),
+      tunnelName: bootstrapAnswer(`${nodeName} Tunnel name`, nodeName),
+      ...nodeMesh ? {
+        mesh: {
+          connectorName: bootstrapAnswer(`${nodeName} Mesh connector name`, `${nodeName}-mesh`),
+          routes: bootstrapList(`${nodeName} private CIDR routes`),
+          highAvailability: bootstrapAnswer(`${nodeName} shares a highly available Mesh connector? (yes/no)`, "no") === "yes"
+        }
+      } : {}
+    };
+  });
+  return createCloudflareBootstrapCommandConfig({
+    checkpointPath: bootstrapAnswer("Owner-only resumable checkpoint path", "./cloudflare-handoff.json"),
+    coordinates: {
+      ...discovered,
+      ...meshDevicePolicyId ? { meshDevicePolicyId } : {},
+      ...realtimeEnabled ? {
+        realtime: {
+          workerScriptName,
+          endpoint: bootstrapAnswer("Stable public Worker HTTPS endpoint"),
+          producer: bootstrapAnswer("Realtime producer identity", "platform-api")
+        }
+      } : {},
+      nodes
+    },
+    tokenFiles
+  });
+}
 function genesisOutputDirectory(path) {
   if (!isAbsolute5(path) || resolve9(path) !== path)
     throw new Error("--output must be a canonical absolute directory");
@@ -17290,13 +17437,19 @@ async function cmdBootstrap(options, args) {
     const operation = args[0] ?? "status";
     if (operation === "config") {
       const kind = args[1];
-      if (kind !== "metal" && kind !== "platform" || args[2] !== undefined || !options.outputPath) {
-        throw new Error("Usage: fz bootstrap config metal --output <absolute-file> | fz bootstrap config platform --output <absolute-owner-only-directory>");
+      if (kind !== "metal" && kind !== "platform" && kind !== "cloudflare" || args[2] !== undefined || !options.outputPath) {
+        throw new Error("Usage: fz bootstrap config metal|cloudflare --output <absolute-file> | fz bootstrap config platform --output <absolute-owner-only-directory>");
       }
       if (kind === "platform") {
         out.line(JSON.stringify({ kind, ...writePlatformGenesisFleet(options.outputPath), mode: "0600" }, null, 2));
         return 0;
       }
+      if (kind === "cloudflare") {
+        const path = writeBootstrapConfig(options.outputPath, await interactiveCloudflareBootstrap());
+        readCloudflareBootstrapCommandConfig(path, "plan");
+        out.line(JSON.stringify({ kind, path, mode: "0600" }, null, 2));
+        return 0;
+      }
       const config2 = interactiveMetalBootstrap();
       out.line(JSON.stringify({ kind, path: writeBootstrapConfig(options.outputPath, config2), mode: "0600" }, null, 2));
       return 0;
@@ -17432,7 +17585,7 @@ async function cmdBootstrap(options, args) {
       return 0;
     }
     if (!["platform", "repair"].includes(operation)) {
-      throw new Error("Usage: fz bootstrap config <metal|platform>|platform [prepare|remote <prepare|apply|status>|cloudflare [verify|finalize]]|metal [remote <apply|genesis|status>]|status|repair [--bootstrap-config <path>] [--apply]");
+      throw new Error("Usage: fz bootstrap config <metal|platform|cloudflare>|platform [prepare|remote <prepare|apply|status>|cloudflare [verify|finalize]]|metal [remote <apply|genesis|rehearsal|status>]|status|repair [--bootstrap-config <path>] [--apply]");
     }
     const config = options.bootstrapConfigPath ? readBootstrapConfig(options.bootstrapConfigPath) : operation === "repair" ? (() => {
       throw new Error("repair requires --bootstrap-config so immutable coordinates are revalidated");
@@ -17997,9 +18150,9 @@ function usage() {
 	                         Run typed bootstrap from the operator laptop through
 	                         a pinned host and caller-approved SSH agent
 	 fz bootstrap platform   Install/repair a typed elastic platform compute
-	 fz bootstrap config <metal|platform>
-	                         Write a validated owner-only metal file or strict
-	                         three-node platform genesis directory; never apply locally
+	 fz bootstrap config <metal|platform|cloudflare>
+	                         Write a validated owner-only metal/Cloudflare file or
+	                         strict three-node platform genesis directory; never apply locally
 	 fz bootstrap platform cloudflare
 	                         Plan/apply attended Tunnel and DNS reconciliation
 	                         using supplied management and KV/Worker runtime token files

package/dist/metal-bootstrap.js

@@ -292,7 +292,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.56";
+var VERSION = "0.1.58";
 
 // src/otel-collector.ts
 var FORGEZERO_OTEL_COLLECTOR_UNIT = "forgezero-otel-collector.service";

package/dist/operator-bootstrap.js

@@ -22,7 +22,7 @@ function privateDatabaseHostRoute(value) {
   return `${address}/${isIP(address) === 4 ? 32 : 128}`;
 }
 var endpoint = "https://api.cloudflare.com/client/v4";
-async function cf(config, path, init = {}, fetcher = fetch) {
+async function cfEnvelope(config, path, init = {}, fetcher = fetch) {
   const response = await fetcher(`${endpoint}${path}`, {
     ...init,
     headers: {
@@ -35,7 +35,68 @@ async function cf(config, path, init = {}, fetcher = fetch) {
   if (!response.ok || body.success !== true) {
     throw new Error(body.errors?.map(({ message }) => message).filter(Boolean).join("; ") || `Cloudflare returned HTTP ${response.status}`);
   }
-  return body.result;
+  return body;
+}
+async function cf(config, path, init = {}, fetcher = fetch) {
+  return (await cfEnvelope(config, path, init, fetcher)).result;
+}
+async function cfPages(config, path, perPage, fetcher) {
+  const output = [];
+  for (let page = 1;page <= 100; page += 1) {
+    const separator = path.includes("?") ? "&" : "?";
+    const envelope = await cfEnvelope(config, `${path}${separator}page=${page}&per_page=${perPage}`, {}, fetcher);
+    const result = Array.isArray(envelope.result) ? envelope.result : [];
+    output.push(...result);
+    const totalPages = envelope.result_info?.total_pages;
+    if (Number.isInteger(totalPages) ? page >= totalPages : result.length < perPage)
+      return output;
+  }
+  throw new Error("Cloudflare pagination exceeded the reviewed 100-page bound");
+}
+var exactHexId = (value, label) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!/^[a-f0-9]{32}$/.test(normalized))
+    throw new Error(`${label} is malformed`);
+  return normalized;
+};
+async function discoverCloudflareBootstrapResources(config, fetcher = fetch) {
+  const zoneName = config.zoneName.trim().toLowerCase().replace(/\.$/, "");
+  const kvNamespaceTitle = config.kvNamespaceTitle.trim();
+  if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(zoneName)) {
+    throw new Error("Cloudflare zone name is invalid");
+  }
+  if (!kvNamespaceTitle || kvNamespaceTitle.length > 512) {
+    throw new Error("Cloudflare KV namespace title is invalid");
+  }
+  const [managementStatus, runtimeStatus] = await Promise.all([
+    cf({ apiToken: config.tunnelToken }, "/user/tokens/verify", {}, fetcher),
+    cf({ apiToken: config.apiToken }, "/user/tokens/verify", {}, fetcher)
+  ]);
+  if (managementStatus.status !== "active")
+    throw new Error("CF_TUNNEL_TOKEN is not active");
+  if (runtimeStatus.status !== "active")
+    throw new Error("CF_API_TOKEN is not active");
+  const zones = await cfPages({ apiToken: config.tunnelToken }, `/zones?name=${encodeURIComponent(zoneName)}&match=all&status=active`, 50, fetcher);
+  const matchingZones = zones.filter(({ name }) => name?.trim().toLowerCase() === zoneName);
+  if (matchingZones.length !== 1) {
+    throw new Error(`Cloudflare zone ${zoneName} must resolve to exactly one active zone`);
+  }
+  const zoneId = exactHexId(matchingZones[0].id, "Cloudflare zone id");
+  const accountId = exactHexId(matchingZones[0].account?.id, "Cloudflare account id");
+  const namespaces = await cfPages({ apiToken: config.apiToken }, `/accounts/${accountId}/storage/kv/namespaces?order=title&direction=asc`, 1000, fetcher);
+  const matchingNamespaces = namespaces.filter(({ title }) => title === kvNamespaceTitle);
+  if (matchingNamespaces.length !== 1) {
+    throw new Error(`Cloudflare KV namespace ${kvNamespaceTitle} must resolve to exactly one namespace`);
+  }
+  const kvNamespaceId = exactHexId(matchingNamespaces[0].id, "Cloudflare KV namespace id");
+  if (config.workerScriptName) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId,
+      scriptName: config.workerScriptName,
+      apiToken: config.apiToken
+    }, fetcher);
+  }
+  return { accountId, zoneId, kvNamespaceId };
 }
 async function ensureCloudflarePrivateRoute(config, fetcher = fetch) {
   const [address, prefixText, ...extra] = config.network.split("/");
@@ -211,7 +272,7 @@ async function verifyCloudflareWorkerDurableObjects(config, fetcher = fetch) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName)) {
     throw new Error("Cloudflare Worker script name is invalid");
   }
-  const namespaces = await cf(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces?per_page=1000`, {}, fetcher);
+  const namespaces = await cfPages(config, `/accounts/${config.accountId}/workers/durable_objects/namespaces`, 1000, fetcher);
   const owned = namespaces.filter(({ script }) => script === config.scriptName);
   if (!owned.length)
     throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);
@@ -1207,7 +1268,7 @@ var UPDATE_RETRY_BASE_MS = 5 * 60000;
 var UPDATE_RETRY_MAX_MS = 24 * 60 * 60000;
 
 // src/version.ts
-var VERSION = "0.1.56";
+var VERSION = "0.1.58";
 
 // src/software.ts
 var PINNED_BUN_VERSION = "1.3.14";

package/dist/platform-fleet-verification.js

@@ -2086,7 +2086,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.56";
+var VERSION3 = "0.1.58";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

package/dist/provision.js

@@ -2086,7 +2086,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.56";
+var VERSION3 = "0.1.58";
 
 // src/egress-policy.ts
 import { realpathSync as realpathSync3 } from "node:fs";

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.56";
+export declare const VERSION = "0.1.58";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/agent",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit",