@forgezero/agent 0.1.40 → 0.1.42

package/dist/cloudflare-edge.d.ts

@@ -4,10 +4,8 @@ export interface CloudflareEdgeConfig {
     tunnelId: string;
     hostname: string;
     service: string;
+    /** The single attended management capability used for both Tunnel and DNS writes. */
     apiToken: string;
-    /** Optional least-privilege overrides. `apiToken` remains the single-token path. */
-    tunnelApiToken?: string;
-    dnsApiToken?: string;
 }
 export interface CloudflarePrivateRouteConfig {
     accountId: string;
@@ -73,6 +71,21 @@ interface CloudflareSplitTunnelEntry {
     host?: string;
     description?: string;
 }
+/**
+ * Reconcile the exact private networks that Mesh nodes must send through
+ * Cloudflare. Existing profile entries are preserved; only ForgeZero-owned
+ * descriptions are added. The caller must use a dedicated Mesh device profile.
+ */
+export declare function ensureCloudflareWarpNetworkIncludes(config: {
+    accountId: string;
+    policyId: string;
+    networks: readonly string[];
+    descriptionPrefix: string;
+    apiToken: string;
+}, fetcher?: typeof fetch): Promise<{
+    entries: readonly CloudflareSplitTunnelEntry[];
+    created: number;
+}>;
 /** Preserve the profile's existing entries while including one exact database host route. */
 export declare function ensureCloudflareWarpDatabaseInclude(config: CloudflareWarpIncludeConfig, fetcher?: typeof fetch): Promise<{
     entries: readonly CloudflareSplitTunnelEntry[];
@@ -85,21 +98,60 @@ export declare function removeCloudflareWarpDatabaseInclude(config: Omit<Cloudfl
 }>;
 /** Reconcile one remotely-managed tunnel route and its proxied DNS record. */
 export declare function configureCloudflareEdge(config: CloudflareEdgeConfig, fetcher?: typeof fetch): Promise<void>;
-export interface CloudflareApiTokens {
-    /** Backward-compatible single-token input; two scoped tokens are preferred. */
-    apiToken?: string;
-    /** Attended management token mapped to Tunnel and DNS operations. */
-    tunnelApiToken?: string;
-    dnsApiToken?: string;
-    /** Runtime token used only for KV node-directory writes. */
-    kvApiToken?: string;
-}
 export interface CloudflareTunnel {
     id: string;
     name: string;
     status?: string;
     deleted_at?: string | null;
 }
+export interface CloudflareMeshConnector {
+    id: string;
+    name: string;
+    status?: 'inactive' | 'degraded' | 'healthy' | 'down';
+    tun_type?: 'warp_connector';
+    deleted_at?: string | null;
+}
+export interface CloudflareDurableObjectNamespace {
+    id?: string;
+    name?: string;
+    class?: string;
+    script?: string;
+    use_sqlite?: boolean;
+}
+/**
+ * Prove that the separately deployed Worker already owns at least one Durable
+ * Object namespace. ForgeZero does not deploy or alter the Worker here; this is
+ * a read-only control-plane check before installing shared application secrets.
+ */
+export declare function verifyCloudflareWorkerDurableObjects(config: {
+    accountId: string;
+    scriptName: string;
+    apiToken: string;
+}, fetcher?: typeof fetch): Promise<readonly CloudflareDurableObjectNamespace[]>;
+/** Install only the two application secrets consumed by the existing Worker. */
+export declare function configureCloudflareRealtimeSecrets(config: {
+    accountId: string;
+    scriptName: string;
+    publishSecret: string;
+    ticketSecret: string;
+    apiToken: string;
+}, fetcher?: typeof fetch): Promise<void>;
+/**
+ * Create or adopt one Cloudflare Mesh node (the current WARP Connector
+ * product name) and retrieve the node-registration token. This is the
+ * bidirectional L3/L4 boundary for metal-to-metal traffic; it is deliberately
+ * separate from the public, inbound-only cloudflared Tunnel.
+ */
+export declare function ensureCloudflareMeshConnector(config: {
+    accountId: string;
+    name: string;
+    highAvailability: boolean;
+    apiToken: string;
+}, fetcher?: typeof fetch): Promise<{
+    connector: CloudflareMeshConnector;
+    connectorToken: string;
+    created: boolean;
+}>;
 /**
  * Create or reuse one remotely-managed Tunnel and obtain its connector token.
  * The token is returned once to the caller so it can be PQ-delivered to the

package/dist/cloudflare-edge.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)) {
@@ -193,12 +284,16 @@ async function ensureCloudflareTunnel(config, fetcher = fetch) {
   return { tunnel, connectorToken, created };
 }
 export {
+  verifyCloudflareWorkerDurableObjects,
   removeCloudflareWarpDatabaseInclude,
   removeCloudflarePrivateRoute,
   removeCloudflarePrivateDatabaseRoute,
+  ensureCloudflareWarpNetworkIncludes,
   ensureCloudflareWarpDatabaseInclude,
   ensureCloudflareTunnel,
   ensureCloudflarePrivateRoute,
   ensureCloudflarePrivateDatabaseRoute,
+  ensureCloudflareMeshConnector,
+  configureCloudflareRealtimeSecrets,
   configureCloudflareEdge
 };

package/dist/community-rehearsal-host.d.ts

@@ -0,0 +1,51 @@
+export declare const COMMUNITY_REHEARSAL_VERSION = "3.11.14";
+export declare const COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
+export declare const COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
+export declare const COMMUNITY_CREDENTIAL_ROOT = "/etc/forgezero-rehearsal/creds";
+export type CommunityRehearsalApiOperation = 'health' | 'init' | 'write' | 'read' | 'query' | 'cluster';
+export type CommunityRehearsalHostRequest = {
+    action: 'prepare';
+    node: string;
+    address: string;
+    agency: boolean;
+    release: string;
+    archivePath: string;
+    archiveSha256: string;
+    jwt: string;
+} | {
+    action: 'database-enable' | 'api-enable' | 'database-ready' | 'starter-ready' | 'api-ready' | 'database-status' | 'api-status';
+    node: string;
+} | {
+    action: 'api';
+    node: string;
+    operation: CommunityRehearsalApiOperation;
+    key?: string;
+    value?: string;
+};
+export type CommunityHostOperation = {
+    kind: 'remove-tree';
+    path: typeof COMMUNITY_DATABASE_ROOT;
+} | {
+    kind: 'write';
+    path: string;
+    content: string;
+    mode: number;
+} | {
+    kind: 'unlink';
+    path: string;
+} | {
+    kind: 'symlink';
+    target: string;
+    path: string;
+} | {
+    kind: 'exec';
+    argv: readonly string[];
+    stdin?: string;
+    accepted?: readonly number[];
+};
+export declare function parseCommunityRehearsalHostRequest(value: unknown): CommunityRehearsalHostRequest;
+export declare function planCommunityRehearsalPrepare(request: Extract<CommunityRehearsalHostRequest, {
+    action: 'prepare';
+}>): CommunityHostOperation[];
+/** Execute only the dedicated four-node rehearsal operation selected by a typed request. */
+export declare function runCommunityRehearsalHost(request: CommunityRehearsalHostRequest): Promise<Record<string, unknown>>;

package/dist/community-rehearsal-host.js

@@ -0,0 +1,272 @@
+// src/community-rehearsal-host.ts
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+var COMMUNITY_REHEARSAL_VERSION = "3.11.14";
+var COMMUNITY_REHEARSAL_ROOT = "/opt/forgezero-rehearsals/community-cluster-api";
+var COMMUNITY_DATABASE_ROOT = "/var/lib/forgezero-rehearsal-cluster";
+var COMMUNITY_CREDENTIAL_ROOT = "/etc/forgezero-rehearsal/creds";
+var NODES = new Map([
+  ["dev-fz-n1", { address: "10.42.0.21", agency: true }],
+  ["dev-fz-n2", { address: "10.42.0.22", agency: true }],
+  ["dev-fz-n3", { address: "10.42.0.23", agency: true }],
+  ["dev-fz-n4", { address: "10.42.0.24", agency: false }]
+]);
+var RELEASE = /^[a-f0-9]{64}$/;
+var exactObject = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("community rehearsal request must be an object");
+  return value;
+};
+var exactNode = (node) => {
+  if (typeof node !== "string")
+    throw new Error("community rehearsal node is invalid");
+  const expected = NODES.get(node);
+  if (!expected)
+    throw new Error("community rehearsal accepts only the dedicated dev-fz-n1..n4 fleet");
+  return { name: node, ...expected };
+};
+function parseCommunityRehearsalHostRequest(value) {
+  const row = exactObject(value);
+  const node = exactNode(row.node);
+  const action = row.action;
+  if (action === "prepare") {
+    const allowed = ["action", "node", "address", "agency", "release", "archivePath", "archiveSha256", "jwt"];
+    if (Object.keys(row).some((key) => !allowed.includes(key)) || row.address !== node.address || row.agency !== node.agency || typeof row.release !== "string" || !RELEASE.test(row.release) || row.archiveSha256 !== row.release || row.archivePath !== `/tmp/forgezero-community-${row.release}.tar.gz` || typeof row.jwt !== "string" || !/^[a-f0-9]{64}$/.test(row.jwt)) {
+      throw new Error("community rehearsal prepare request does not match the dedicated fleet contract");
+    }
+    return row;
+  }
+  if (["database-enable", "api-enable", "database-ready", "starter-ready", "api-ready", "database-status", "api-status"].includes(String(action))) {
+    if (Object.keys(row).some((key) => !["action", "node"].includes(key)))
+      throw new Error("community rehearsal host action has unknown fields");
+    return { action, node: node.name };
+  }
+  if (action === "api") {
+    if (Object.keys(row).some((key) => !["action", "node", "operation", "key", "value"].includes(key)) || !["health", "init", "write", "read", "query", "cluster"].includes(String(row.operation)) || row.key !== undefined && (typeof row.key !== "string" || !/^[A-Za-z0-9_.:-]{1,128}$/.test(row.key)) || row.value !== undefined && (typeof row.value !== "string" || row.value.length > 4096)) {
+      throw new Error("community rehearsal API request is invalid");
+    }
+    if ((row.operation === "write" || row.operation === "read") && typeof row.key !== "string")
+      throw new Error("community rehearsal API key is required");
+    if ((row.operation === "write" || row.operation === "query") && typeof row.value !== "string")
+      throw new Error("community rehearsal API value is required");
+    return row;
+  }
+  throw new Error("unsupported community rehearsal host action");
+}
+var databaseUnit = (node) => {
+  const join = node.name === "dev-fz-n1" ? "" : " --starter.join=10.42.0.21";
+  const role = node.agency ? "" : " --cluster.start-agent=false --cluster.start-coordinator=true --cluster.start-dbserver=true";
+  return `[Unit]
+Description=ForgeZero isolated Community ${COMMUNITY_REHEARSAL_VERSION} rehearsal cluster
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=arangodb
+Group=arangodb
+LoadCredentialEncrypted=arangodb-jwt:${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred
+ExecStart=/usr/bin/arangodb --starter.mode=cluster --starter.address=${node.address} --starter.host=${node.address} --starter.data-dir=${COMMUNITY_DATABASE_ROOT} --starter.disable-ipv6 --auth.jwt-secret=%d/arangodb-jwt${join}${role}
+Restart=always
+RestartSec=5
+LimitNOFILE=100000
+LimitCORE=0
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=${COMMUNITY_DATABASE_ROOT}
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+};
+var apiUnit = (node) => `[Unit]
+Description=ForgeZero typed Community cluster rehearsal API
+After=forgezero-rehearsal-db.service network-online.target
+Requires=forgezero-rehearsal-db.service
+
+[Service]
+Type=simple
+User=forgezero
+Group=forgezero
+WorkingDirectory=${COMMUNITY_REHEARSAL_ROOT}/current
+LoadCredentialEncrypted=arangodb-jwt:${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred
+Environment=HOST=127.0.0.1
+Environment=PORT=8787
+Environment=NODE_NAME=${node.name}
+Environment=ARANGO_URL=http://127.0.0.1:8529
+Environment=ARANGO_URLS=http://10.42.0.21:8529,http://10.42.0.22:8529,http://10.42.0.23:8529,http://10.42.0.24:8529
+Environment=ARANGO_READ_PREFERRED_URLS=http://10.42.0.24:8529
+Environment=ARANGO_READ_PREFERRED_FALLBACK=error
+ExecStart=/usr/local/bin/bun src/index.ts
+Restart=always
+RestartSec=2
+LimitCORE=0
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+LockPersonality=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+function planCommunityRehearsalPrepare(request) {
+  const node = exactNode(request.node);
+  const releaseRoot = `${COMMUNITY_REHEARSAL_ROOT}/releases/${request.release}`;
+  return [
+    { kind: "exec", argv: ["/usr/bin/arangod", "--version"] },
+    { kind: "exec", argv: ["/usr/bin/systemctl", "stop", "forgezero-community-api.service"], accepted: [0, 5] },
+    { kind: "exec", argv: ["/usr/bin/systemctl", "stop", "forgezero-rehearsal-db.service"], accepted: [0, 5] },
+    { kind: "remove-tree", path: COMMUNITY_DATABASE_ROOT },
+    { kind: "exec", argv: ["/usr/bin/install", "-d", "-m", "0700", "-o", "root", "-g", "root", COMMUNITY_CREDENTIAL_ROOT] },
+    { kind: "exec", argv: ["/usr/bin/install", "-d", "-m", "0700", "-o", "arangodb", "-g", "arangodb", COMMUNITY_DATABASE_ROOT] },
+    { kind: "exec", argv: ["/usr/bin/install", "-d", "-m", "0755", "-o", "root", "-g", "root", releaseRoot] },
+    { kind: "unlink", path: `${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred.next` },
+    { kind: "exec", argv: ["/usr/bin/systemd-creds", "encrypt", "--name=arangodb-jwt", "-", `${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred.next`], stdin: `${request.jwt}
+` },
+    { kind: "exec", argv: ["/usr/bin/chmod", "0400", `${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred.next`] },
+    { kind: "exec", argv: ["/usr/bin/mv", "-f", `${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred.next`, `${COMMUNITY_CREDENTIAL_ROOT}/arangodb-jwt.cred`] },
+    { kind: "write", path: "/etc/systemd/system/forgezero-rehearsal-db.service", content: databaseUnit(node), mode: 420 },
+    { kind: "exec", argv: ["/usr/bin/tar", "-xzf", request.archivePath, "-C", releaseRoot] },
+    { kind: "exec", argv: ["/usr/bin/chown", "-R", "forgezero:forgezero", releaseRoot] },
+    { kind: "exec", argv: ["/usr/sbin/runuser", "-u", "forgezero", "--", "/usr/local/bin/bun", "install", "--cwd", releaseRoot, "--frozen-lockfile", "--production"] },
+    { kind: "unlink", path: `${COMMUNITY_REHEARSAL_ROOT}/current` },
+    { kind: "symlink", target: releaseRoot, path: `${COMMUNITY_REHEARSAL_ROOT}/current` },
+    { kind: "write", path: "/etc/systemd/system/forgezero-community-api.service", content: apiUnit(node), mode: 420 },
+    { kind: "unlink", path: request.archivePath }
+  ];
+}
+async function exec(argv, stdin) {
+  const child = Bun.spawn([...argv], { stdin: stdin === undefined ? "ignore" : "pipe", stdout: "pipe", stderr: "pipe" });
+  if (stdin !== undefined && child.stdin && typeof child.stdin !== "number") {
+    child.stdin.write(stdin);
+    child.stdin.end();
+  }
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}`.slice(0, 256 * 1024) };
+}
+async function applyOperations(operations) {
+  for (const operation of operations) {
+    if (operation.kind === "remove-tree")
+      rmSync(operation.path, { recursive: true, force: true });
+    else if (operation.kind === "write") {
+      mkdirSync(dirname(operation.path), { recursive: true });
+      writeFileSync(operation.path, operation.content, { mode: operation.mode });
+    } else if (operation.kind === "unlink") {
+      try {
+        unlinkSync(operation.path);
+      } catch (cause) {
+        if (cause.code !== "ENOENT")
+          throw cause;
+      }
+    } else if (operation.kind === "symlink")
+      symlinkSync(operation.target, operation.path);
+    else {
+      const result = await exec(operation.argv, operation.stdin);
+      if (!(operation.accepted ?? [0]).includes(result.exitCode))
+        throw new Error(`${operation.argv[0]} failed (${result.exitCode}): ${result.output.trim()}`);
+      if (operation.argv[0] === "/usr/bin/arangod" && !result.output.split(/\r?\n/, 1)[0]?.includes(COMMUNITY_REHEARSAL_VERSION)) {
+        throw new Error(`community rehearsal requires ArangoDB ${COMMUNITY_REHEARSAL_VERSION}`);
+      }
+    }
+  }
+}
+var responseFor = async (request) => {
+  const base = "http://127.0.0.1:8787";
+  if (request.operation === "health")
+    return fetch(`${base}/health`, { signal: AbortSignal.timeout(15000) });
+  if (request.operation === "init")
+    return fetch(`${base}/init`, { method: "POST", signal: AbortSignal.timeout(15000) });
+  if (request.operation === "write")
+    return fetch(`${base}/documents`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ key: request.key, value: request.value }),
+      signal: AbortSignal.timeout(15000)
+    });
+  if (request.operation === "read")
+    return fetch(`${base}/documents/${encodeURIComponent(request.key)}`, { signal: AbortSignal.timeout(15000) });
+  if (request.operation === "query")
+    return fetch(`${base}/query?value=${encodeURIComponent(request.value)}`, { signal: AbortSignal.timeout(15000) });
+  return fetch(`${base}/cluster`, { signal: AbortSignal.timeout(15000) });
+};
+async function runCommunityRehearsalHost(request) {
+  if ((process.getuid?.() ?? -1) !== 0)
+    throw new Error("community-rehearsal must run as root");
+  const node = exactNode(request.node);
+  if (request.action === "prepare") {
+    const metadata = lstatSync(request.archivePath);
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size < 1 || metadata.size > 64 * 1024 * 1024 || createHash("sha256").update(readFileSync(request.archivePath)).digest("hex") !== request.archiveSha256) {
+      throw new Error("community rehearsal archive is not the declared bounded release");
+    }
+    await applyOperations(planCommunityRehearsalPrepare(request));
+    return { ok: true, action: request.action, node: node.name, release: request.release };
+  }
+  if (request.action === "database-enable") {
+    await applyOperations([
+      { kind: "exec", argv: ["/usr/bin/systemctl", "daemon-reload"] },
+      { kind: "exec", argv: ["/usr/bin/systemctl", "enable", "forgezero-rehearsal-db.service"] },
+      { kind: "exec", argv: ["/usr/bin/systemctl", "restart", "forgezero-rehearsal-db.service"] }
+    ]);
+    return { ok: true, action: request.action, node: node.name };
+  }
+  if (request.action === "api-enable") {
+    await applyOperations([
+      { kind: "exec", argv: ["/usr/bin/systemctl", "daemon-reload"] },
+      { kind: "exec", argv: ["/usr/bin/systemctl", "enable", "--now", "forgezero-community-api.service"] }
+    ]);
+    return { ok: true, action: request.action, node: node.name };
+  }
+  if (request.action === "database-status" || request.action === "api-status") {
+    const unit = request.action === "database-status" ? "forgezero-rehearsal-db.service" : "forgezero-community-api.service";
+    const result = await exec(["/usr/bin/systemctl", "is-active", "--quiet", unit]);
+    if (result.exitCode !== 0)
+      throw new Error(`${unit} is not active`);
+    return { ok: true, action: request.action, node: node.name };
+  }
+  if (request.action === "database-ready" || request.action === "starter-ready" || request.action === "api-ready") {
+    const url = request.action === "database-ready" ? "http://127.0.0.1:8529/_api/version" : request.action === "starter-ready" ? "http://10.42.0.21:8528/version" : "http://127.0.0.1:8787/health";
+    const response2 = await fetch(url, { signal: AbortSignal.timeout(2000) }).catch(() => {
+      return;
+    });
+    const ready = Boolean(response2 && (request.action === "database-ready" ? response2.status === 200 || response2.status === 401 : response2.ok));
+    await response2?.body?.cancel();
+    return { ok: true, action: request.action, node: node.name, ready };
+  }
+  if (request.action !== "api")
+    throw new Error("unsupported community rehearsal host action");
+  const response = await responseFor(request);
+  const body = await response.text();
+  if (!response.ok)
+    throw new Error(`community rehearsal API returned HTTP ${response.status}: ${body.slice(0, 4096)}`);
+  return { ok: true, action: request.action, node: node.name, operation: request.operation, status: response.status, body };
+}
+export {
+  runCommunityRehearsalHost,
+  planCommunityRehearsalPrepare,
+  parseCommunityRehearsalHostRequest,
+  COMMUNITY_REHEARSAL_VERSION,
+  COMMUNITY_REHEARSAL_ROOT,
+  COMMUNITY_DATABASE_ROOT,
+  COMMUNITY_CREDENTIAL_ROOT
+};

package/dist/credential-schema.d.ts

@@ -9,6 +9,60 @@
  */
 export declare const AGENT_CREDENTIAL_LOCATIONS: readonly ["operator", "metal", "platform-compute", "tenant-compute"];
 export type AgentCredentialLocation = (typeof AGENT_CREDENTIAL_LOCATIONS)[number];
+/**
+ * Stable logical names shared by operator input, Vault fields and systemd.
+ *
+ * `CF_TUNNEL_TOKEN` is the broad attended/tenant-control credential that may
+ * create Tunnels and reconcile one exact DNS hostname. It is attended input
+ * before custody and Vault-only for the post-operational platform controller;
+ * it is never loaded by cloudflared. cloudflared receives only the connector
+ * returned for its own Tunnel.
+ *
+ * `CF_API_TOKEN` is the exact-account runtime/control credential used for
+ * Workers KV and the existing Worker's secret bindings. Durable Object
+ * application messages still go through that Worker's binding and use the
+ * separate REALTIME_PUBLISH_SECRET; a Cloudflare REST token is not a Durable
+ * Object invocation credential.
+ */
+export declare const CLOUDFLARE_CREDENTIAL_NAMES: {
+    readonly api: "CF_API_TOKEN";
+    readonly tunnel: "CF_TUNNEL_TOKEN";
+    readonly connector: "CF_TUNNEL_CONNECTOR_TOKEN";
+    readonly realtimePublish: "REALTIME_PUBLISH_SECRET";
+    readonly realtimeTicket: "REALTIME_TICKET_SECRET";
+};
+export declare const CLOUDFLARE_CREDENTIAL_SCHEMA: {
+    readonly CF_TUNNEL_TOKEN: {
+        readonly permissions: readonly ["Account:Cloudflare Tunnel Write", "Account:Cloudflare One Connector: WARP Write", "Account:Cloudflare One Networks Write", "Account:Zero Trust Write", "Zone:DNS Write"];
+        readonly platformBootstrap: "attended-file";
+        readonly platformRuntime: "vault";
+        readonly tenantControl: "vault";
+    };
+    readonly CF_API_TOKEN: {
+        readonly permissions: readonly ["Account:Workers KV Storage Write", "Account:Workers Scripts Write"];
+        readonly platformBootstrap: "attended-file";
+        readonly platformRuntime: "vault-then-systemd";
+        readonly tenantControl: "vault";
+    };
+    readonly CF_TUNNEL_CONNECTOR_TOKEN: {
+        readonly permissions: readonly ["one named Tunnel connector"];
+        readonly platformBootstrap: "derived";
+        readonly platformRuntime: "systemd";
+        readonly tenantControl: "derived";
+    };
+    readonly REALTIME_PUBLISH_SECRET: {
+        readonly permissions: readonly ["Worker realtime publish endpoint"];
+        readonly platformBootstrap: "generated-and-installed-worker-secret";
+        readonly platformRuntime: "vault-then-systemd";
+        readonly tenantControl: "vault";
+    };
+    readonly REALTIME_TICKET_SECRET: {
+        readonly permissions: readonly ["Worker realtime subscription tickets"];
+        readonly platformBootstrap: "generated-and-installed-worker-secret";
+        readonly platformRuntime: "vault-then-systemd";
+        readonly tenantControl: "vault";
+    };
+};
 export declare const AGENT_CREDENTIAL_POLICY: {
     readonly operator: {
         readonly vault: false;