@forgezero/agent 0.1.41 → 0.1.42

package/dist/cloudflare-bootstrap.js

@@ -94,6 +94,39 @@ async function removeCloudflarePrivateDatabaseRoute(config, fetcher = fetch) {
     network: privateDatabaseHostRoute(config.privateAddress)
   }, fetcher);
 }
+var privateNetworkCidr = (value) => {
+  const [address, prefixText, ...extra] = value.trim().toLowerCase().split("/");
+  const family = isIP(address ?? "");
+  const prefix = Number(prefixText);
+  if (extra.length || !family || !Number.isInteger(prefix) || prefix < 0 || prefix > (family === 4 ? 32 : 128) || !isPrivateDatabaseAddress(address)) {
+    throw new Error("Cloudflare WARP include must be an explicit private IPv4 or IPv6 CIDR");
+  }
+  return `${address}/${prefix}`;
+};
+async function ensureCloudflareWarpNetworkIncludes(config, fetcher = fetch) {
+  if (!/^[A-Za-z0-9-]{1,64}$/.test(config.policyId))
+    throw new Error("Cloudflare WARP policy id is invalid");
+  if (!Array.isArray(config.networks) || config.networks.length < 1 || config.networks.length > 256) {
+    throw new Error("Cloudflare WARP networks must contain 1-256 explicit CIDRs");
+  }
+  const networks = config.networks.map(privateNetworkCidr);
+  if (new Set(networks).size !== networks.length)
+    throw new Error("Cloudflare WARP networks must be unique");
+  const path = `/accounts/${config.accountId}/devices/policy/${config.policyId}/include`;
+  const entries = await cf(config, path, {}, fetcher);
+  const present = new Set(entries.flatMap(({ address }) => address ? [address.toLowerCase()] : []));
+  const additions = networks.filter((network) => !present.has(network)).map((address) => ({
+    address,
+    description: `${config.descriptionPrefix}:${address}`.slice(0, 100)
+  }));
+  if (!additions.length)
+    return { entries, created: 0 };
+  const updated = await cf(config, path, {
+    method: "PUT",
+    body: JSON.stringify([...entries, ...additions])
+  }, fetcher);
+  return { entries: updated, created: additions.length };
+}
 async function ensureCloudflareWarpDatabaseInclude(config, fetcher = fetch) {
   if (config.policyId && !/^[A-Za-z0-9-]{1,64}$/.test(config.policyId))
     throw new Error("Cloudflare WARP policy id is invalid");
@@ -127,13 +160,11 @@ async function removeCloudflareWarpDatabaseInclude(config, fetcher = fetch) {
   return { entries: updated, removed: true };
 }
 async function configureCloudflareEdge(config, fetcher = fetch) {
-  const tunnelAuth = { apiToken: config.tunnelApiToken?.trim() || config.apiToken };
-  const dnsAuth = { apiToken: config.dnsApiToken?.trim() || config.apiToken };
   const tunnelPath = `/accounts/${config.accountId}/cfd_tunnel/${config.tunnelId}/configurations`;
   const dnsPath = `/zones/${config.zoneId}/dns_records`;
   const [current, records] = await Promise.all([
-    cf(tunnelAuth, tunnelPath, {}, fetcher),
-    cf(dnsAuth, `${dnsPath}?name=${encodeURIComponent(config.hostname)}&per_page=1000`, {}, fetcher)
+    cf(config, tunnelPath, {}, fetcher),
+    cf(config, `${dnsPath}?name=${encodeURIComponent(config.hostname)}&per_page=1000`, {}, fetcher)
   ]);
   if (records.length > 1) {
     throw new Error(`Cloudflare DNS record for ${config.hostname} is ambiguous`);
@@ -151,7 +182,7 @@ async function configureCloudflareEdge(config, fetcher = fetch) {
     ...catchAll.length > 0 ? catchAll : [{ service: "http_status:404" }]
   ];
   if (JSON.stringify(existing) !== JSON.stringify(desiredIngress)) {
-    await cf(tunnelAuth, tunnelPath, {
+    await cf(config, tunnelPath, {
       method: "PUT",
       body: JSON.stringify({ config: { ingress: desiredIngress } })
     }, fetcher);
@@ -165,12 +196,72 @@ async function configureCloudflareEdge(config, fetcher = fetch) {
   };
   const dnsAlreadyCorrect = existingRecord?.type === record.type && existingRecord.name?.toLowerCase() === record.name.toLowerCase() && existingRecord.content?.toLowerCase() === record.content.toLowerCase() && existingRecord.proxied === true && existingRecord.ttl === 1;
   if (!dnsAlreadyCorrect) {
-    await cf(dnsAuth, existingRecord ? `${dnsPath}/${encodeURIComponent(existingRecord.id)}` : dnsPath, {
-      method: existingRecord ? "PUT" : "POST",
-      body: JSON.stringify(record)
+    await cf(config, existingRecord ? `${dnsPath}/${encodeURIComponent(existingRecord.id)}` : dnsPath, {
+      method: existingRecord ? "PATCH" : "POST",
+      body: JSON.stringify(existingRecord ? {
+        ...record,
+        ...existingRecord.comment === undefined ? {} : { comment: existingRecord.comment },
+        ...existingRecord.tags === undefined ? {} : { tags: existingRecord.tags },
+        ...existingRecord.settings === undefined ? {} : { settings: existingRecord.settings }
+      } : record)
     }, fetcher);
   }
 }
+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 owned = namespaces.filter(({ script }) => script === config.scriptName);
+  if (!owned.length)
+    throw new Error(`Cloudflare Worker ${config.scriptName} has no Durable Object namespace`);
+  return owned;
+}
+async function configureCloudflareRealtimeSecrets(config, fetcher = fetch) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(config.scriptName) || ![config.publishSecret, config.ticketSecret].every((value) => /^[A-Za-z0-9_-]{64,128}$/.test(value)) || config.publishSecret === config.ticketSecret) {
+    throw new Error("Cloudflare realtime secret coordinates are invalid");
+  }
+  await cf(config, `/accounts/${config.accountId}/workers/scripts/${encodeURIComponent(config.scriptName)}/secrets-bulk`, {
+    method: "PATCH",
+    body: JSON.stringify({
+      secrets: {
+        REALTIME_PUBLISH_SECRET: {
+          name: "REALTIME_PUBLISH_SECRET",
+          text: config.publishSecret,
+          type: "secret_text"
+        },
+        REALTIME_TICKET_SECRET: {
+          name: "REALTIME_TICKET_SECRET",
+          text: config.ticketSecret,
+          type: "secret_text"
+        }
+      }
+    })
+  }, fetcher);
+}
+async function ensureCloudflareMeshConnector(config, fetcher = fetch) {
+  const name = config.name.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(name)) {
+    throw new Error("Cloudflare Mesh connector name is invalid");
+  }
+  const path = `/accounts/${config.accountId}/warp_connector`;
+  const connectors = await cf(config, `${path}?is_deleted=false&name=${encodeURIComponent(name)}&per_page=1000`, {}, fetcher);
+  const matches = connectors.filter((connector2) => connector2.name === name && !connector2.deleted_at);
+  if (matches.length > 1)
+    throw new Error(`Cloudflare Mesh connector ${name} is ambiguous`);
+  const created = !matches[0];
+  const connector = matches[0] ?? await cf(config, path, {
+    method: "POST",
+    body: JSON.stringify({ name, ha: config.highAvailability })
+  }, fetcher);
+  if (!connector.id)
+    throw new Error("Cloudflare returned an invalid Mesh connector");
+  const connectorToken = await cf(config, `${path}/${encodeURIComponent(connector.id)}/token`, {}, fetcher);
+  if (!connectorToken || connectorToken.length > 16384) {
+    throw new Error("Cloudflare returned an invalid Mesh connector token");
+  }
+  return { connector, connectorToken, created };
+}
 async function ensureCloudflareTunnel(config, fetcher = fetch) {
   const name = config.name.trim();
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(name)) {
@@ -195,13 +286,15 @@ async function ensureCloudflareTunnel(config, fetcher = fetch) {
 
 // src/cloudflare-bootstrap.ts
 import { constants } from "fs";
-import { randomUUID } from "crypto";
-import { chmod, lstat, mkdir, open, rename, stat, unlink } from "fs/promises";
+import { randomBytes, randomUUID } from "crypto";
+import { chmod, lstat, mkdir, open, readdir, rename, rmdir, stat, unlink } from "fs/promises";
 import { dirname, join, resolve } from "path";
+import { isIP as isIP2 } from "net";
 var TOKEN = /^[A-Za-z0-9._-]{40,80}$/;
 var CONNECTOR_TOKEN = /^[A-Za-z0-9._-]{40,16384}$/;
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+var REALTIME_SECRET = /^[A-Za-z0-9_-]{64,128}$/;
 var ownerUid = () => typeof process.getuid === "function" ? process.getuid() : undefined;
 async function assertOwnerOnlyHandle(path, handle, maximumBytes) {
   const metadata = await handle.stat();
@@ -242,33 +335,23 @@ async function readOwnerApiToken(path) {
   return token;
 }
 async function readCloudflareBootstrapTokens(files) {
-  const entries = await Promise.all([
-    ["apiToken", files.apiTokenFile],
-    ["managementApiToken", files.managementApiTokenFile],
-    ["runtimeApiToken", files.runtimeApiTokenFile],
-    ["tunnelApiToken", files.tunnelApiTokenFile],
-    ["dnsApiToken", files.dnsApiTokenFile],
-    ["kvApiToken", files.kvApiTokenFile]
-  ].map(async ([key, path]) => [key, path ? await readOwnerApiToken(path) : undefined]));
-  const supplied = Object.fromEntries(entries.filter(([, value]) => value !== undefined));
-  const tokens = {
-    ...supplied.apiToken ? { apiToken: supplied.apiToken } : {},
-    ...supplied.tunnelApiToken || supplied.managementApiToken ? {
-      tunnelApiToken: supplied.tunnelApiToken ?? supplied.managementApiToken
-    } : {},
-    ...supplied.dnsApiToken || supplied.managementApiToken ? {
-      dnsApiToken: supplied.dnsApiToken ?? supplied.managementApiToken
-    } : {},
-    ...supplied.kvApiToken || supplied.runtimeApiToken ? {
-      kvApiToken: supplied.kvApiToken ?? supplied.runtimeApiToken
-    } : {}
-  };
-  for (const key of ["tunnelApiToken", "dnsApiToken", "kvApiToken"]) {
-    if (!tokens[key] && !tokens.apiToken) {
-      throw new Error(`Cloudflare ${key} file is required when apiTokenFile is omitted`);
-    }
+  const unsupported = Object.keys(files).filter((key) => ![
+    "tunnelTokenFile",
+    "apiTokenFile"
+  ].includes(key));
+  if (unsupported.length)
+    throw new Error(`Cloudflare bootstrap token files contain unsupported field ${unsupported[0]}`);
+  if (!files.tunnelTokenFile?.trim() || !files.apiTokenFile?.trim()) {
+    throw new Error("Cloudflare bootstrap requires exactly tunnelTokenFile and apiTokenFile");
   }
-  return tokens;
+  const [tunnelToken, apiToken] = await Promise.all([
+    readOwnerApiToken(files.tunnelTokenFile),
+    readOwnerApiToken(files.apiTokenFile)
+  ]);
+  if (tunnelToken === apiToken) {
+    throw new Error("CF_TUNNEL_TOKEN and CF_API_TOKEN must be distinct least-privilege tokens");
+  }
+  return { tunnelToken, apiToken };
 }
 var validateId = (value, label) => {
   const normalized = value.trim().toLowerCase();
@@ -294,28 +377,89 @@ var normalizeService = (value) => {
   }
   return service.toString().replace(/\/$/, "");
 };
+var privateMeshCidr = (value) => {
+  const [address, prefixText, ...extra] = value.trim().toLowerCase().split("/");
+  const family = isIP2(address ?? "");
+  const prefix = Number(prefixText);
+  const v4 = family === 4 ? address.split(".").map(Number) : undefined;
+  const privateAddress = family === 4 ? Boolean(v4 && (v4[0] === 10 || v4[0] === 172 && v4[1] >= 16 && v4[1] <= 31 || v4[0] === 192 && v4[1] === 168)) : family === 6 && /^f[cd][0-9a-f]:/i.test(address);
+  if (extra.length || !family || !privateAddress || !Number.isInteger(prefix) || prefix < 0 || prefix > (family === 4 ? 32 : 128)) {
+    throw new Error("Cloudflare Mesh route must be an explicit private IPv4 or IPv6 CIDR");
+  }
+  return `${address}/${prefix}`;
+};
 function validateCloudflareBootstrapCoordinates(input) {
-  const nodeInputs = input.nodes?.length ? input.nodes : [{
-    nodeName: input.tunnelName,
-    hostname: input.hostname,
-    service: input.service,
-    tunnelName: input.tunnelName
-  }];
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Cloudflare bootstrap coordinates must be an object");
+  }
+  const unsupported = Object.keys(input).filter((key) => ![
+    "accountId",
+    "zoneId",
+    "kvNamespaceId",
+    "meshDevicePolicyId",
+    "realtime",
+    "nodes"
+  ].includes(key));
+  if (unsupported.length)
+    throw new Error(`Cloudflare bootstrap coordinates contain unsupported field ${unsupported[0]}`);
+  const nodeInputs = input.nodes;
+  if (!Array.isArray(nodeInputs))
+    throw new Error("Cloudflare bootstrap requires an explicit nodes array");
   if (nodeInputs.length < 1 || nodeInputs.length > 32) {
     throw new Error("Cloudflare bootstrap requires between 1 and 32 explicit nodes");
   }
   const nodes = nodeInputs.map((node) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) {
+      throw new Error("Cloudflare bootstrap node must be an object");
+    }
+    const unknownNode = Object.keys(node).filter((key) => ![
+      "nodeName",
+      "hostname",
+      "service",
+      "tunnelName",
+      "mesh"
+    ].includes(key));
+    if (unknownNode.length)
+      throw new Error(`Cloudflare bootstrap node contains unsupported field ${unknownNode[0]}`);
     const nodeName = node.nodeName.trim().toLowerCase();
     if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(nodeName))
       throw new Error("Cloudflare node name is invalid");
     const hostname = node.hostname.trim().toLowerCase();
     if (!HOSTNAME.test(hostname))
       throw new Error("Cloudflare public node hostname is invalid");
+    let mesh;
+    if (node.mesh !== undefined) {
+      if (!node.mesh || typeof node.mesh !== "object" || Array.isArray(node.mesh)) {
+        throw new Error("Cloudflare Mesh coordinates must be an object");
+      }
+      const unknownMesh = Object.keys(node.mesh).filter((key) => ![
+        "connectorName",
+        "routes",
+        "highAvailability"
+      ].includes(key));
+      if (unknownMesh.length)
+        throw new Error(`Cloudflare Mesh contains unsupported field ${unknownMesh[0]}`);
+      if (!Array.isArray(node.mesh.routes) || node.mesh.routes.length < 1 || node.mesh.routes.length > 64) {
+        throw new Error("Cloudflare Mesh node requires 1-64 private routes");
+      }
+      const routes = node.mesh.routes.map(privateMeshCidr);
+      if (new Set(routes).size !== routes.length)
+        throw new Error("Cloudflare Mesh routes must be unique per node");
+      if (node.mesh.highAvailability !== undefined && typeof node.mesh.highAvailability !== "boolean") {
+        throw new Error("Cloudflare Mesh highAvailability must be a boolean");
+      }
+      mesh = {
+        connectorName: validateName(node.mesh.connectorName, "Cloudflare Mesh connector name"),
+        routes,
+        highAvailability: node.mesh.highAvailability === true
+      };
+    }
     return {
       nodeName,
       hostname,
       service: normalizeService(node.service),
-      tunnelName: validateName(node.tunnelName, "Cloudflare Tunnel name")
+      tunnelName: validateName(node.tunnelName, "Cloudflare Tunnel name"),
+      ...mesh ? { mesh } : {}
     };
   });
   for (const [label, values] of [
@@ -326,14 +470,51 @@ function validateCloudflareBootstrapCoordinates(input) {
     if (new Set(values).size !== values.length)
       throw new Error(`Cloudflare fleet ${label} must be unique`);
   }
-  const first = nodes[0];
+  const meshNodes = nodes.filter(({ mesh }) => mesh);
+  if (meshNodes.length && !input.meshDevicePolicyId?.trim()) {
+    throw new Error("Cloudflare Mesh requires an explicit dedicated device policy id");
+  }
+  if (!meshNodes.length && input.meshDevicePolicyId !== undefined) {
+    throw new Error("Cloudflare Mesh device policy is not allowed without Mesh nodes");
+  }
+  const connectorNames = meshNodes.map(({ mesh }) => mesh.connectorName);
+  if (new Set(connectorNames).size !== connectorNames.length) {
+    throw new Error("Cloudflare Mesh connector names must be unique");
+  }
+  const routeOwners = new Map;
+  for (const node of meshNodes)
+    for (const route of node.mesh.routes) {
+      const owner = routeOwners.get(route);
+      if (owner)
+        throw new Error(`Cloudflare Mesh route ${route} is declared by both ${owner} and ${node.nodeName}`);
+      routeOwners.set(route, node.nodeName);
+    }
+  let realtime;
+  if (input.realtime !== undefined) {
+    if (!input.realtime || typeof input.realtime !== "object" || Array.isArray(input.realtime) || Object.keys(input.realtime).some((key) => !["workerScriptName", "endpoint", "producer"].includes(key))) {
+      throw new Error("Cloudflare realtime coordinates are malformed");
+    }
+    const workerScriptName = input.realtime.workerScriptName.trim();
+    const producer = input.realtime.producer.trim();
+    let endpoint2;
+    try {
+      endpoint2 = new URL(input.realtime.endpoint);
+    } catch {
+      throw new Error("Cloudflare realtime endpoint is malformed");
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/.test(workerScriptName) || !/^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,127}$/.test(producer) || endpoint2.protocol !== "https:" || endpoint2.username || endpoint2.password || endpoint2.pathname !== "/" || endpoint2.search || endpoint2.hash) {
+      throw new Error("Cloudflare realtime Worker, endpoint, or producer is invalid");
+    }
+    realtime = { workerScriptName, endpoint: endpoint2.origin, producer };
+  }
   return {
     accountId: validateId(input.accountId, "Cloudflare account id"),
     zoneId: validateId(input.zoneId, "Cloudflare zone id"),
-    hostname: first.hostname,
-    service: first.service,
-    tunnelName: first.tunnelName,
     kvNamespaceId: validateId(input.kvNamespaceId, "Cloudflare KV namespace id"),
+    ...input.meshDevicePolicyId ? {
+      meshDevicePolicyId: validateName(input.meshDevicePolicyId, "Cloudflare Mesh device policy id")
+    } : {},
+    ...realtime ? { realtime } : {},
     nodes
   };
 }
@@ -346,18 +527,50 @@ function planCloudflareBootstrap(input, outputPath) {
     outputFile: resolve(outputPath),
     coordinates,
     operations: [
+      "prove CF_API_TOKEN can write, read and remove one namespaced nonce in the existing KV namespace",
+      ...coordinates.realtime ? [
+        "prove the existing Worker owns a Durable Object namespace and install its publish/ticket secrets with CF_API_TOKEN"
+      ] : [],
       "create or reuse one remotely-managed Tunnel per node and checkpoint every connector token",
+      ...coordinates.nodes.some(({ mesh }) => mesh) ? [
+        "create or reuse one Mesh/WARP Connector per declared private-network node and checkpoint its registration token",
+        "reconcile every unique private CIDR to its Mesh connector and include all declared CIDRs in the dedicated Mesh device profile"
+      ] : [],
       "preflight each exact DNS hostname, refuse ambiguous or incompatible records, and update its existing CNAME or create it only when absent",
       "reconcile each Tunnel public-hostname ingress rule to the declared loopback API service",
-      "write one node-specific handoff containing the connector token and owner-supplied KV-write token"
+      "write one node-specific handoff containing the connector token and owner-supplied KV/Worker runtime token"
     ],
     secrets: [
       "API tokens are read only from owner-only files and are never placed in argv or stdout",
-      "the management token is never persisted; connector and KV runtime capabilities are atomically checkpointed with mode 0600",
-      "the normal API process receives only its KV-write token and never Tunnel or DNS management authority"
+      "CF_TUNNEL_TOKEN is never persisted; cloudflared, Mesh, CF_API_TOKEN and generated realtime capabilities are atomically checkpointed with mode 0600",
+      "the normal API process receives only CF_API_TOKEN and never Tunnel, DNS or Mesh management authority"
     ]
   };
 }
+async function preflightCloudflareKvRuntime(coordinates, apiToken, fetcher) {
+  const nonce = randomUUID();
+  const key = `forgezero/bootstrap-preflight/${nonce}`;
+  const url = `https://api.cloudflare.com/client/v4/accounts/${coordinates.accountId}` + `/storage/kv/namespaces/${coordinates.kvNamespaceId}/values/${encodeURIComponent(key)}`;
+  const headers = { authorization: `Bearer ${apiToken}`, "content-type": "text/plain" };
+  let written = false;
+  try {
+    const put = await fetcher(url, { method: "PUT", headers, body: nonce });
+    if (!put.ok)
+      throw new Error(`Cloudflare KV runtime preflight write returned HTTP ${put.status}`);
+    written = true;
+    const get = await fetcher(url, { method: "GET", headers: { authorization: `Bearer ${apiToken}` } });
+    if (!get.ok)
+      throw new Error(`Cloudflare KV runtime preflight read returned HTTP ${get.status}`);
+    if (await get.text() !== nonce)
+      throw new Error("Cloudflare KV runtime preflight read returned unexpected data");
+  } finally {
+    if (written) {
+      const removed = await fetcher(url, { method: "DELETE", headers: { authorization: `Bearer ${apiToken}` } });
+      if (!removed.ok)
+        throw new Error(`Cloudflare KV runtime preflight cleanup returned HTTP ${removed.status}`);
+    }
+  }
+}
 async function readExistingOutput(path) {
   try {
     await lstat(path);
@@ -374,10 +587,84 @@ async function readExistingOutput(path) {
       throw new Error(`${resolve(path)} is not valid bootstrap JSON`);
     throw cause;
   }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${resolve(path)} is not a ForgeZero Cloudflare bootstrap output`);
+  }
   const output = parsed;
-  if (output.format !== 1 || output.kind !== "forgezero-cloudflare-bootstrap" || !output.resources) {
+  const unsupported = Object.keys(output).filter((key) => ![
+    "format",
+    "kind",
+    "phase",
+    "updatedAt",
+    "coordinates",
+    "resources",
+    "created"
+  ].includes(key));
+  if (unsupported.length)
+    throw new Error(`${resolve(path)} contains unsupported field ${unsupported[0]}`);
+  if (output.format !== 1 || output.kind !== "forgezero-cloudflare-bootstrap" || !["edge-resources-provisioned", "complete"].includes(String(output.phase)) || typeof output.updatedAt !== "string" || Number.isNaN(Date.parse(output.updatedAt)) || !output.resources || typeof output.resources !== "object" || Array.isArray(output.resources)) {
     throw new Error(`${resolve(path)} is not a ForgeZero Cloudflare bootstrap output`);
   }
+  const resources = output.resources;
+  const unsupportedResource = Object.keys(resources).filter((key) => ![
+    "kvNamespaceId",
+    "apiToken",
+    "realtime",
+    "nodes"
+  ].includes(key));
+  if (unsupportedResource.length) {
+    throw new Error(`${resolve(path)} resources contain unsupported field ${unsupportedResource[0]}`);
+  }
+  const coordinates = validateCloudflareBootstrapCoordinates(output.coordinates);
+  if (resources.kvNamespaceId !== coordinates.kvNamespaceId || !TOKEN.test(String(resources.apiToken ?? "")) || !Array.isArray(resources.nodes) || resources.nodes.length > coordinates.nodes.length) {
+    throw new Error(`${resolve(path)} has malformed Cloudflare bootstrap resources`);
+  }
+  if (coordinates.realtime) {
+    const realtime = resources.realtime;
+    if (!realtime || !REALTIME_SECRET.test(String(realtime.publishSecret ?? "")) || !REALTIME_SECRET.test(String(realtime.ticketSecret ?? "")) || realtime.publishSecret === realtime.ticketSecret) {
+      throw new Error(`${resolve(path)} has malformed Cloudflare realtime resources`);
+    }
+  } else if (resources.realtime !== undefined) {
+    throw new Error(`${resolve(path)} contains undeclared Cloudflare realtime resources`);
+  }
+  const seen = new Set;
+  for (const item of resources.nodes) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error(`${resolve(path)} has a malformed Cloudflare node resource`);
+    }
+    const node = item;
+    const unknownNode = Object.keys(node).filter((key) => ![
+      "nodeName",
+      "hostname",
+      "service",
+      "tunnelName",
+      "tunnelId",
+      "connectorToken",
+      "mesh"
+    ].includes(key));
+    const expected = coordinates.nodes.find((candidate) => candidate.nodeName === node.nodeName);
+    if (unknownNode.length || !expected || seen.has(expected.nodeName) || node.hostname !== expected.hostname || node.service !== expected.service || node.tunnelName !== expected.tunnelName || !UUID.test(String(node.tunnelId ?? "")) || !CONNECTOR_TOKEN.test(String(node.connectorToken ?? ""))) {
+      throw new Error(`${resolve(path)} has a malformed or unbound Cloudflare node resource`);
+    }
+    if (expected.mesh) {
+      const mesh = node.mesh;
+      if (!mesh || mesh.connectorName !== expected.mesh.connectorName || JSON.stringify(mesh.routes) !== JSON.stringify(expected.mesh.routes) || mesh.highAvailability !== expected.mesh.highAvailability || !UUID.test(String(mesh.connectorId ?? "")) || !CONNECTOR_TOKEN.test(String(mesh.connectorToken ?? ""))) {
+        throw new Error(`${resolve(path)} has a malformed or unbound Cloudflare Mesh resource`);
+      }
+    } else if (node.mesh !== undefined) {
+      throw new Error(`${resolve(path)} contains an undeclared Cloudflare Mesh resource`);
+    }
+    seen.add(expected.nodeName);
+  }
+  if (output.phase === "complete" && resources.nodes.length !== coordinates.nodes.length) {
+    throw new Error(`${resolve(path)} completed output does not cover the declared node fleet`);
+  }
+  if (output.created !== undefined) {
+    if (!output.created || typeof output.created !== "object" || Array.isArray(output.created) || Object.keys(output.created).some((key) => key !== "nodes") || !Array.isArray(output.created.nodes) || output.created.nodes.some((node) => !node || typeof node !== "object" || Array.isArray(node) || Object.keys(node).some((key) => !["nodeName", "tunnel", "mesh"].includes(key)) || typeof node.nodeName !== "string" || typeof node.tunnel !== "boolean" || typeof node.mesh !== "boolean")) {
+      throw new Error(`${resolve(path)} has malformed Cloudflare creation evidence`);
+    }
+  }
+  output.coordinates = coordinates;
   return output;
 }
 function cloudflareHostHandoffPath(checkpointPath, nodeName) {
@@ -410,7 +697,12 @@ async function readCloudflareConnectorHandoff(checkpointPath, nodeName) {
     hostname: resource.hostname,
     service: resource.service,
     tunnelId: resource.tunnelId,
-    connectorToken: resource.connectorToken
+    connectorToken: resource.connectorToken,
+    ...resource.mesh ? { mesh: {
+      connectorId: resource.mesh.connectorId,
+      connectorToken: resource.mesh.connectorToken,
+      routes: resource.mesh.routes
+    } } : {}
   };
 }
 async function readCloudflareHostHandoff(handoffPath, nodeName) {
@@ -436,9 +728,9 @@ async function readCloudflareHostHandoff(handoffPath, nodeName) {
     "accountId",
     "zoneId",
     "kvNamespaceId",
-    "kvRuntimeToken",
-    "privateNetworkRuntimeToken",
-    "warp"
+    "apiToken",
+    "mesh",
+    "realtime"
   ].includes(key));
   if (unknown.length)
     throw new Error(`Cloudflare host handoff contains unsupported field ${unknown[0]}`);
@@ -447,17 +739,53 @@ async function readCloudflareHostHandoff(handoffPath, nodeName) {
   try {
     service = normalizeService(output.service ?? "");
   } catch {}
-  if (output.format !== 1 || output.kind !== "forgezero-cloudflare-host-handoff" || output.nodeName !== normalizedNodeName || !HOSTNAME.test(output.hostname ?? "") || !service || !UUID.test(output.tunnelId ?? "") || !CONNECTOR_TOKEN.test(output.connectorToken ?? "") || !TOKEN.test(output.kvRuntimeToken ?? "") || !/^[a-f0-9]{32}$/i.test(output.accountId ?? "") || !/^[a-f0-9]{32}$/i.test(output.zoneId ?? "") || !/^[a-f0-9]{32}$/i.test(output.kvNamespaceId ?? "")) {
+  if (output.format !== 1 || output.kind !== "forgezero-cloudflare-host-handoff" || output.nodeName !== normalizedNodeName || !HOSTNAME.test(output.hostname ?? "") || !service || !UUID.test(output.tunnelId ?? "") || !CONNECTOR_TOKEN.test(output.connectorToken ?? "") || !TOKEN.test(output.apiToken ?? "") || !/^[a-f0-9]{32}$/i.test(output.accountId ?? "") || !/^[a-f0-9]{32}$/i.test(output.zoneId ?? "") || !/^[a-f0-9]{32}$/i.test(output.kvNamespaceId ?? "")) {
     throw new Error("Cloudflare host handoff is malformed or belongs to another node");
   }
-  if (output.privateNetworkRuntimeToken !== undefined && !TOKEN.test(output.privateNetworkRuntimeToken)) {
-    throw new Error("Cloudflare host handoff private-network capability is malformed");
+  if (output.mesh !== undefined) {
+    if (!output.mesh || typeof output.mesh !== "object" || !UUID.test(output.mesh.connectorId) || !CONNECTOR_TOKEN.test(output.mesh.connectorToken) || !Array.isArray(output.mesh.routes) || output.mesh.routes.length < 1 || output.mesh.routes.length > 64 || output.mesh.routes.some((route) => {
+      try {
+        return privateMeshCidr(route) !== route;
+      } catch {
+        return true;
+      }
+    })) {
+      throw new Error("Cloudflare host handoff contains malformed Mesh coordinates");
+    }
   }
-  if (Boolean(output.warp) !== Boolean(output.privateNetworkRuntimeToken)) {
-    throw new Error("Cloudflare host handoff private-network resources and capability disagree");
+  if (output.realtime !== undefined) {
+    let realtime;
+    try {
+      const { workerScriptName, endpoint: endpoint2, producer } = output.realtime;
+      realtime = validateCloudflareBootstrapCoordinates({
+        accountId: output.accountId,
+        zoneId: output.zoneId,
+        kvNamespaceId: output.kvNamespaceId,
+        realtime: { workerScriptName, endpoint: endpoint2, producer },
+        nodes: [{
+          nodeName: output.nodeName,
+          hostname: output.hostname,
+          service: output.service,
+          tunnelName: "handoff"
+        }]
+      }).realtime;
+    } catch {
+      throw new Error("Cloudflare host handoff contains malformed realtime coordinates");
+    }
+    if (!REALTIME_SECRET.test(output.realtime.publishSecret) || !REALTIME_SECRET.test(output.realtime.ticketSecret) || output.realtime.publishSecret === output.realtime.ticketSecret || realtime.workerScriptName !== output.realtime.workerScriptName || realtime.endpoint !== output.realtime.endpoint || realtime.producer !== output.realtime.producer) {
+      throw new Error("Cloudflare host handoff contains malformed realtime credentials");
+    }
   }
   const { format: _format, kind: _kind, ...handoff } = output;
-  return handoff;
+  return {
+    ...handoff,
+    nodeName: normalizedNodeName,
+    hostname: handoff.hostname.toLowerCase(),
+    service,
+    accountId: handoff.accountId.toLowerCase(),
+    zoneId: handoff.zoneId.toLowerCase(),
+    kvNamespaceId: handoff.kvNamespaceId.toLowerCase()
+  };
 }
 async function prepareOwnerOutputDirectory(absolutePath) {
   const directory = dirname(absolutePath);
@@ -513,18 +841,22 @@ async function writeCloudflareHostHandoffs(checkpointPath, output) {
       accountId: output.coordinates.accountId,
       zoneId: output.coordinates.zoneId,
       kvNamespaceId: output.resources.kvNamespaceId,
-      kvRuntimeToken: output.resources.kvRuntimeToken
+      apiToken: output.resources.apiToken,
+      ...output.coordinates.realtime && output.resources.realtime ? { realtime: {
+        ...output.coordinates.realtime,
+        ...output.resources.realtime
+      } } : {},
+      ...node.mesh ? { mesh: {
+        connectorId: node.mesh.connectorId,
+        connectorToken: node.mesh.connectorToken,
+        routes: node.mesh.routes
+      } } : {}
     };
     await writeOwnerJson(cloudflareHostHandoffPath(checkpointPath, node.nodeName), handoff);
   }
 }
-var tokenFor = (tokens, key) => {
-  const token = tokens[key]?.trim() || tokens.apiToken?.trim();
-  if (!token || !TOKEN.test(token))
-    throw new Error(`Cloudflare ${key} is not configured`);
-  return token;
-};
 var sameCoordinates = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+var newRealtimeSecret = () => randomBytes(48).toString("base64url");
 async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fetch) {
   const coordinates = validateCloudflareBootstrapCoordinates(input);
   const absoluteOutput = resolve(outputPath);
@@ -533,7 +865,46 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
     throw new Error("bootstrap output belongs to different Cloudflare coordinates; choose a different output file");
   }
   await prepareOwnerOutputDirectory(absoluteOutput);
-  const kvRuntimeToken = tokenFor(tokens, "kvApiToken");
+  const tunnelToken = tokens.tunnelToken.trim();
+  const apiToken = tokens.apiToken.trim();
+  if (!TOKEN.test(tunnelToken) || !TOKEN.test(apiToken)) {
+    throw new Error("Cloudflare bootstrap tokens are malformed");
+  }
+  if (tunnelToken === apiToken) {
+    throw new Error("CF_TUNNEL_TOKEN and CF_API_TOKEN must be distinct least-privilege capabilities");
+  }
+  await preflightCloudflareKvRuntime(coordinates, apiToken, fetcher);
+  const realtime = coordinates.realtime ? existing?.resources.realtime ?? {
+    publishSecret: newRealtimeSecret(),
+    ticketSecret: newRealtimeSecret()
+  } : undefined;
+  if (coordinates.realtime && realtime) {
+    await verifyCloudflareWorkerDurableObjects({
+      accountId: coordinates.accountId,
+      scriptName: coordinates.realtime.workerScriptName,
+      apiToken
+    }, fetcher);
+    await writeOwnerBootstrapOutput(absoluteOutput, {
+      format: 1,
+      kind: "forgezero-cloudflare-bootstrap",
+      phase: "edge-resources-provisioned",
+      updatedAt: new Date().toISOString(),
+      coordinates,
+      resources: {
+        kvNamespaceId: coordinates.kvNamespaceId,
+        apiToken,
+        realtime,
+        nodes: existing?.resources.nodes ?? []
+      }
+    });
+    await configureCloudflareRealtimeSecrets({
+      accountId: coordinates.accountId,
+      scriptName: coordinates.realtime.workerScriptName,
+      publishSecret: realtime.publishSecret,
+      ticketSecret: realtime.ticketSecret,
+      apiToken
+    }, fetcher);
+  }
   const nodeResources = [];
   const createdNodes = [];
   for (const node of coordinates.nodes) {
@@ -549,14 +920,33 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
       const tunnel = await ensureCloudflareTunnel({
         accountId: coordinates.accountId,
         name: node.tunnelName,
-        apiToken: tokenFor(tokens, "tunnelApiToken")
+        apiToken: tunnelToken
       }, fetcher);
       created = tunnel.created;
-      resource = { ...node, tunnelId: tunnel.tunnel.id, connectorToken: tunnel.connectorToken };
+      let mesh;
+      if (node.mesh) {
+        const ensured = await ensureCloudflareMeshConnector({
+          accountId: coordinates.accountId,
+          name: node.mesh.connectorName,
+          highAvailability: node.mesh.highAvailability === true,
+          apiToken: tunnelToken
+        }, fetcher);
+        mesh = {
+          ...node.mesh,
+          connectorId: ensured.connector.id,
+          connectorToken: ensured.connectorToken
+        };
+      }
+      const { mesh: _declaredMesh, ...publicNode } = node;
+      resource = {
+        ...publicNode,
+        tunnelId: tunnel.tunnel.id,
+        connectorToken: tunnel.connectorToken,
+        ...mesh ? { mesh } : {}
+      };
     }
     nodeResources.push(resource);
-    createdNodes.push({ nodeName: node.nodeName, tunnel: created });
-    const first2 = nodeResources[0];
+    createdNodes.push({ nodeName: node.nodeName, tunnel: created, mesh: Boolean(resource.mesh) });
     await writeOwnerBootstrapOutput(absoluteOutput, {
       format: 1,
       kind: "forgezero-cloudflare-bootstrap",
@@ -564,16 +954,34 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
       updatedAt: new Date().toISOString(),
       coordinates,
       resources: {
-        tunnelId: first2.tunnelId,
         kvNamespaceId: coordinates.kvNamespaceId,
-        hostname: first2.hostname,
-        service: first2.service,
-        connectorToken: first2.connectorToken,
-        kvRuntimeToken,
+        apiToken,
+        ...realtime ? { realtime } : {},
         nodes: [...nodeResources]
       }
     });
   }
+  const meshResources = nodeResources.filter((node) => node.mesh);
+  for (const node of meshResources) {
+    for (const network of node.mesh.routes) {
+      await ensureCloudflarePrivateRoute({
+        accountId: coordinates.accountId,
+        tunnelId: node.mesh.connectorId,
+        network,
+        comment: `ForgeZero Mesh ${node.nodeName}`,
+        apiToken: tunnelToken
+      }, fetcher);
+    }
+  }
+  if (meshResources.length) {
+    await ensureCloudflareWarpNetworkIncludes({
+      accountId: coordinates.accountId,
+      policyId: coordinates.meshDevicePolicyId,
+      networks: meshResources.flatMap((node) => node.mesh.routes),
+      descriptionPrefix: "ForgeZero Mesh",
+      apiToken: tunnelToken
+    }, fetcher);
+  }
   for (const node of nodeResources) {
     await configureCloudflareEdge({
       accountId: coordinates.accountId,
@@ -581,12 +989,9 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
       tunnelId: node.tunnelId,
       hostname: node.hostname,
       service: node.service,
-      apiToken: tokenFor(tokens, "tunnelApiToken"),
-      tunnelApiToken: tokenFor(tokens, "tunnelApiToken"),
-      dnsApiToken: tokenFor(tokens, "dnsApiToken")
+      apiToken: tunnelToken
     }, fetcher);
   }
-  const first = nodeResources[0];
   const output = {
     format: 1,
     kind: "forgezero-cloudflare-bootstrap",
@@ -594,16 +999,12 @@ async function applyCloudflareBootstrap(input, tokens, outputPath, fetcher = fet
     updatedAt: new Date().toISOString(),
     coordinates,
     resources: {
-      tunnelId: first.tunnelId,
       kvNamespaceId: coordinates.kvNamespaceId,
-      hostname: first.hostname,
-      service: first.service,
-      connectorToken: first.connectorToken,
-      kvRuntimeToken,
+      apiToken,
+      ...realtime ? { realtime } : {},
       nodes: nodeResources
     },
     created: {
-      tunnel: createdNodes.some(({ tunnel }) => tunnel),
       nodes: createdNodes
     }
   };
@@ -622,8 +1023,8 @@ async function runAttendedCloudflareBootstrap(request, dependencies = {}) {
       nodes: plan.coordinates.nodes.map(({ nodeName, hostname }) => ({ nodeName, hostname }))
     };
   }
-  if (!request.tokenFiles || !Object.values(request.tokenFiles).some(Boolean)) {
-    throw new Error("Cloudflare apply requires owner-only management token file paths");
+  if (!request.tokenFiles) {
+    throw new Error("Cloudflare apply requires exactly two owner-only token file paths");
   }
   const tokens = await readCloudflareBootstrapTokens(request.tokenFiles);
   const output = await applyCloudflareBootstrap(plan.coordinates, tokens, plan.outputFile, dependencies.fetcher ?? fetch);
@@ -680,6 +1081,100 @@ async function verifyCloudflareBootstrapAcceptance(checkpointPath, fetcher = fet
     nodes
   };
 }
+async function readCloudflareBootstrapAcceptanceEvidence(acceptancePath, expectedNodes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readOwnerOnlyFile(acceptancePath, 65536));
+  } catch (cause) {
+    if (cause instanceof SyntaxError)
+      throw new Error("Cloudflare acceptance evidence is not valid JSON");
+    throw cause;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Cloudflare acceptance evidence is malformed");
+  }
+  const evidence = parsed;
+  if (Object.keys(evidence).some((key) => ![
+    "format",
+    "kind",
+    "checkpointFile",
+    "verifiedAt",
+    "nodes"
+  ].includes(key)) || evidence.format !== 1 || evidence.kind !== "forgezero-cloudflare-bootstrap-acceptance" || typeof evidence.checkpointFile !== "string" || !evidence.checkpointFile || typeof evidence.verifiedAt !== "string" || Number.isNaN(Date.parse(evidence.verifiedAt)) || !Array.isArray(evidence.nodes) || evidence.nodes.length < 1 || evidence.nodes.length > 32) {
+    throw new Error("Cloudflare acceptance evidence is malformed");
+  }
+  const nodes = evidence.nodes.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item) || Object.keys(item).some((key) => !["nodeName", "hostname", "status"].includes(key))) {
+      throw new Error("Cloudflare acceptance evidence contains a malformed node");
+    }
+    const node = item;
+    const nodeName = node.nodeName?.trim().toLowerCase();
+    const hostname = node.hostname?.trim().toLowerCase();
+    if (!nodeName || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(nodeName) || !hostname || !HOSTNAME.test(hostname) || !Number.isInteger(node.status) || node.status < 200 || node.status > 299) {
+      throw new Error("Cloudflare acceptance evidence contains a malformed node");
+    }
+    return { nodeName, hostname, status: node.status };
+  });
+  if (new Set(nodes.map(({ nodeName }) => nodeName)).size !== nodes.length || new Set(nodes.map(({ hostname }) => hostname)).size !== nodes.length) {
+    throw new Error("Cloudflare acceptance evidence contains duplicate nodes");
+  }
+  if (expectedNodes) {
+    const expected = expectedNodes.map(({ nodeName, hostname }) => ({
+      nodeName: nodeName.trim().toLowerCase(),
+      hostname: hostname.trim().toLowerCase()
+    })).sort((left, right) => left.nodeName.localeCompare(right.nodeName));
+    const observed = nodes.map(({ nodeName, hostname }) => ({ nodeName, hostname })).sort((left, right) => left.nodeName.localeCompare(right.nodeName));
+    if (JSON.stringify(observed) !== JSON.stringify(expected)) {
+      throw new Error("Cloudflare acceptance evidence does not cover the declared platform fleet");
+    }
+  }
+  return {
+    format: 1,
+    kind: "forgezero-cloudflare-bootstrap-acceptance",
+    checkpointFile: evidence.checkpointFile,
+    verifiedAt: evidence.verifiedAt,
+    nodes
+  };
+}
+async function removeCloudflareBootstrapSecrets(checkpointPath, output) {
+  const directory = `${resolve(checkpointPath)}.hosts`;
+  let entries;
+  try {
+    const metadata = await lstat(directory);
+    const uid = ownerUid();
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || uid !== undefined && metadata.uid !== uid || (metadata.mode & 63) !== 0) {
+      throw new Error(`Cloudflare host handoff directory ${directory} is not owner-only`);
+    }
+    entries = await readdir(directory);
+  } catch (cause) {
+    if (cause.code !== "ENOENT")
+      throw cause;
+  }
+  if (entries) {
+    const expected = output.coordinates.nodes.map(({ nodeName }) => `${nodeName}.json`).sort();
+    if (JSON.stringify([...entries].sort()) !== JSON.stringify(expected)) {
+      throw new Error("Cloudflare host handoff directory contains unexpected files; refusing secret cleanup");
+    }
+    for (const name of expected)
+      await unlink(join(directory, name));
+    await rmdir(directory);
+  }
+  await unlink(resolve(checkpointPath));
+}
+async function finalizeCloudflareBootstrapAcceptance(request, fetcher = fetch) {
+  const checkpointPath = resolve(request.checkpointPath);
+  const acceptancePath = resolve(request.acceptancePath);
+  if (acceptancePath === checkpointPath || acceptancePath.startsWith(`${checkpointPath}.hosts/`)) {
+    throw new Error("Cloudflare acceptance evidence must be outside the secret checkpoint and handoff directory");
+  }
+  const output = await readExistingOutput(checkpointPath);
+  if (!output || output.phase !== "complete")
+    throw new Error("Cloudflare finalization requires a completed owner checkpoint");
+  const evidence = await verifyCloudflareBootstrapAcceptance(checkpointPath, fetcher);
+  await writeOwnerJson(acceptancePath, evidence);
+  await removeCloudflareBootstrapSecrets(checkpointPath, output);
+  return evidence;
+}
 export {
   writeOwnerBootstrapOutput,
   verifyCloudflareBootstrapAcceptance,
@@ -689,7 +1184,9 @@ export {
   readCloudflareHostHandoff,
   readCloudflareConnectorHandoff,
   readCloudflareBootstrapTokens,
+  readCloudflareBootstrapAcceptanceEvidence,
   planCloudflareBootstrap,
+  finalizeCloudflareBootstrapAcceptance,
   cloudflareHostHandoffPath,
   applyCloudflareBootstrap
 };