@forgezero/agent 0.1.74 → 0.1.75

package/dist/deployment-connectivity.js

@@ -0,0 +1,148 @@
+// src/deployment-connectivity.ts
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+var TOKEN = /^[A-Za-z0-9._-]{40,16384}$/;
+var UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+var HOSTNAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+var NAME = /^[a-z][a-z0-9._-]{0,99}$/;
+var idFor = (key) => createHash("sha256").update(key).digest("hex").slice(0, 20);
+var checked = async (host, argv, label) => {
+  const result = await host.exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${result.output.slice(0, 512)}`);
+  return result.output.trim();
+};
+async function sealWithSystemd(name, path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const next = `${path}.next`;
+  const child = Bun.spawn(["/usr/bin/systemd-creds", "encrypt", `--name=${name}`, "-", next], {
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/sbin:/usr/bin:/sbin:/bin", LANG: "C", LC_ALL: "C" }
+  });
+  child.stdin.write(value);
+  child.stdin.end();
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  if (exitCode !== 0)
+    throw new Error(`systemd credential sealing failed: ${`${stdout}${stderr}`.replaceAll(value, "[REDACTED]").slice(0, 512)}`);
+  renameSync(next, path);
+}
+var defaultHost = {
+  seal: sealWithSystemd,
+  write(path, content, mode) {
+    mkdirSync(dirname(path), { recursive: true, mode: 493 });
+    const next = `${path}.next`;
+    writeFileSync(next, content, { mode });
+    renameSync(next, path);
+  },
+  async exec(argv) {
+    const child = Bun.spawn([...argv], { stdout: "pipe", stderr: "pipe", env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", LANG: "C", LC_ALL: "C" } });
+    const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+    return { exitCode, output: `${stdout}${stderr}` };
+  },
+  sleep: (ms) => Bun.sleep(ms)
+};
+function validate(request) {
+  if (!request.key || request.key.length > 256)
+    throw new Error("deployment connectivity key is invalid");
+  const publicIntent = request.intent.public;
+  const privateIntent = request.intent.private;
+  if (publicIntent?.mode === "cloudflare-tunnel") {
+    if (!NAME.test(publicIntent.credential) || !HOSTNAME.test(publicIntent.hostname) || !NAME.test(publicIntent.tunnelKey) || publicIntent.service.protocol !== "http" || !Number.isInteger(publicIntent.service.port) || publicIntent.service.port < 1 || publicIntent.service.port > 65535 || !request.capabilities.public || !UUID.test(request.capabilities.public.tunnelId) || !TOKEN.test(request.capabilities.public.connectorToken)) {
+      throw new Error("public deployment connectivity is malformed");
+    }
+  } else if (request.capabilities.public)
+    throw new Error("unexpected public deployment capability");
+  if (privateIntent?.mode === "cloudflare-warp") {
+    if (!NAME.test(privateIntent.credential) || privateIntent.network.length < 1 || privateIntent.network.length > 128 || !request.capabilities.private || !UUID.test(request.capabilities.private.connectorId) || !TOKEN.test(request.capabilities.private.connectorToken)) {
+      throw new Error("private deployment connectivity is malformed");
+    }
+  } else if (request.capabilities.private)
+    throw new Error("unexpected private deployment capability");
+}
+async function applyDeploymentConnectivity(request, host = defaultHost) {
+  validate(request);
+  const id = idFor(request.key);
+  const evidence = { key: request.key };
+  if (request.intent.public?.mode === "cloudflare-tunnel") {
+    const capability = request.capabilities.public;
+    const credentialName = `FZ_TUNNEL_${id.toUpperCase()}`;
+    const credentialPath = `/etc/forgezero/creds/deployment-tunnel-${id}.cred`;
+    const unit = `forgezero-cloudflared-${id}.service`;
+    const unitPath = `/etc/systemd/system/${unit}`;
+    const metricsPort = 20000 + Number.parseInt(id.slice(0, 4), 16) % 20000;
+    await host.seal(credentialName, credentialPath, capability.connectorToken);
+    host.write(unitPath, `[Unit]
+Description=ForgeZero deployment Tunnel ${id}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+DynamicUser=yes
+LoadCredentialEncrypted=${credentialName}:${credentialPath}
+ExecStart=/usr/local/bin/cloudflared tunnel --no-autoupdate --metrics 127.0.0.1:${metricsPort} run --token-file %d/${credentialName}
+Restart=always
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+
+[Install]
+WantedBy=multi-user.target
+`, 420);
+    await checked(host, ["/usr/bin/systemctl", "daemon-reload"], "cloudflared daemon reload");
+    await checked(host, ["/usr/bin/systemctl", "enable", "--now", unit], "cloudflared start");
+    await checked(host, ["/usr/bin/systemctl", "is-active", "--quiet", unit], "cloudflared readiness");
+    evidence.public = { hostname: request.intent.public.hostname, tunnelId: capability.tunnelId, unit, active: true };
+  }
+  if (request.intent.private?.mode === "cloudflare-warp") {
+    const capability = request.capabilities.private;
+    const credentialPath = "/etc/forgezero/creds/CF_WARP_CONNECTOR_TOKEN.cred";
+    const unit = "forgezero-deployment-mesh.service";
+    await host.seal("CF_WARP_CONNECTOR_TOKEN", credentialPath, capability.connectorToken);
+    host.write(`/etc/systemd/system/${unit}`, `[Unit]
+Description=ForgeZero deployment Mesh/WARP connector
+Requires=warp-svc.service
+After=network-online.target warp-svc.service
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+LoadCredentialEncrypted=CF_WARP_CONNECTOR_TOKEN:${credentialPath}
+ExecStart=/usr/local/bin/fz-agent mesh-config
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/cloudflare-warp
+
+[Install]
+WantedBy=multi-user.target
+`, 420);
+    await checked(host, ["/usr/bin/systemctl", "daemon-reload"], "WARP daemon reload");
+    await checked(host, ["/usr/bin/systemctl", "enable", "--now", "warp-svc.service", unit], "WARP connector start");
+    for (let attempt = 0;attempt < 10; attempt += 1) {
+      const status = await host.exec(["/usr/bin/warp-cli", "--accept-tos", "status"]);
+      if (status.exitCode === 0 && /\bconnected\b/i.test(status.output) && !/\bdisconnected\b/i.test(status.output)) {
+        evidence.private = { network: request.intent.private.network, connectorId: capability.connectorId, unit, active: true };
+        break;
+      }
+      await host.sleep(1000);
+    }
+    if (!evidence.private)
+      throw new Error("WARP connector readiness failed");
+  }
+  return evidence;
+}
+export {
+  applyDeploymentConnectivity
+};

package/dist/deployment-pull.d.ts

@@ -10,6 +10,8 @@ export interface RemoteDeploymentClaim {
     attempt: number;
     /** True on the one target deterministically elected for this release. */
     releaseExecutor: boolean;
+    assignment?: NonNullable<import('./deployment').DeploymentRequest['assignment']>;
+    connectivityCapabilities?: import('./deployment-connectivity').DeploymentConnectivityCapabilities;
     source: {
         repository: string;
         branch: string;

package/dist/deployment-targets.d.ts

@@ -0,0 +1,9 @@
+import type { JsonPrimitive } from './deploy';
+import type { DeploymentPlan } from './deploy-plan';
+import type { ResolvedDeploymentTarget } from './deployment';
+export declare class DeploymentInputError extends Error {
+    constructor(message: string);
+}
+/** Resolve stable logical slots without selecting a hostname or mutating capacity. */
+export declare function resolveDeploymentTargets(plan: DeploymentPlan, supplied?: Readonly<Record<string, unknown>>): ResolvedDeploymentTarget[];
+export declare function resolveDeploymentInputs(plan: DeploymentPlan, supplied?: Readonly<Record<string, unknown>>): Record<string, JsonPrimitive>;

package/dist/deployment-targets.js

@@ -0,0 +1,141 @@
+// src/deployment-targets.ts
+class DeploymentInputError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DeploymentInputError";
+  }
+}
+var HOSTNAME = /^(?=.{1,253}$)[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/;
+function inputValue(name, definition, supplied) {
+  let value = supplied ?? definition.default;
+  if (value === undefined) {
+    if (definition.required)
+      throw new DeploymentInputError(`deployment input ${name} is required`);
+    return;
+  }
+  if (typeof value === "string") {
+    const text = value;
+    if (definition.type === "boolean" && (text === "true" || text === "false"))
+      value = text === "true";
+    if ((definition.type === "integer" || definition.type === "number") && text.trim() !== "")
+      value = Number(text);
+  }
+  if (definition.type === "boolean" && typeof value !== "boolean")
+    throw new DeploymentInputError(`deployment input ${name} must be boolean`);
+  if (definition.type === "integer" && (!Number.isSafeInteger(value) || Number(value) < (definition.minimum ?? Number.MIN_SAFE_INTEGER) || Number(value) > (definition.maximum ?? Number.MAX_SAFE_INTEGER)))
+    throw new DeploymentInputError(`deployment input ${name} must be a bounded integer`);
+  if (definition.type === "number" && (typeof value !== "number" || !Number.isFinite(value) || value < (definition.minimum ?? -Number.MAX_VALUE) || value > (definition.maximum ?? Number.MAX_VALUE)))
+    throw new DeploymentInputError(`deployment input ${name} must be a bounded number`);
+  if (definition.type === "enum" && (typeof value !== "string" || !definition.values.includes(value)))
+    throw new DeploymentInputError(`deployment input ${name} must be one of its declared values`);
+  if (definition.type === "hostname" && (typeof value !== "string" || !HOSTNAME.test(value)))
+    throw new DeploymentInputError(`deployment input ${name} must be a hostname`);
+  if (definition.type === "string") {
+    if (typeof value !== "string" || value.length < (definition.minimumLength ?? 0) || value.length > (definition.maximumLength ?? 4096))
+      throw new DeploymentInputError(`deployment input ${name} must be a bounded string`);
+    if (definition.pattern !== undefined && !new RegExp(definition.pattern).test(value))
+      throw new DeploymentInputError(`deployment input ${name} does not match its pattern`);
+  }
+  return value;
+}
+function resolveDeploymentTargets(plan, supplied = {}) {
+  const inputs = resolveDeploymentInputs(plan, supplied);
+  const stringCoordinate = (value, label) => {
+    const resolved = typeof value === "string" ? value : value.$ref.startsWith("inputs.") ? inputs[value.$ref.slice("inputs.".length)] : undefined;
+    if (typeof resolved !== "string" || resolved.length < 1 || resolved.length > 253) {
+      throw new DeploymentInputError(`${label} did not resolve to a bounded string`);
+    }
+    return resolved.toLowerCase();
+  };
+  const integerCoordinate = (value, label, minimum, maximum) => {
+    const resolved = typeof value === "number" ? value : value.$ref.startsWith("inputs.") ? inputs[value.$ref.slice("inputs.".length)] : undefined;
+    if (!Number.isSafeInteger(resolved) || Number(resolved) < minimum || Number(resolved) > maximum) {
+      throw new DeploymentInputError(`${label} did not resolve to a bounded integer`);
+    }
+    return Number(resolved);
+  };
+  const credentialSource = (alias, label) => {
+    const source = plan.spec.credentials?.[alias]?.source.name;
+    if (!source)
+      throw new DeploymentInputError(`${label} did not resolve to a declared Vault credential`);
+    return source;
+  };
+  return Object.entries(plan.spec.targets).map(([name, target]) => {
+    const desired = typeof target.cardinality.desired === "number" ? target.cardinality.desired : target.cardinality.desired.$ref.startsWith("inputs.") ? inputs[target.cardinality.desired.$ref.slice("inputs.".length)] : undefined;
+    if (!Number.isSafeInteger(desired) || Number(desired) < target.cardinality.minimum || Number(desired) > target.cardinality.maximum) {
+      throw new DeploymentInputError(`target ${name} desired cardinality did not resolve to a bounded integer`);
+    }
+    let connectivity;
+    if (target.connectivity) {
+      const privateNetwork = target.connectivity.private;
+      const publicNetwork = target.connectivity.public;
+      connectivity = {
+        ...privateNetwork ? { private: privateNetwork.mode === "cloudflare-warp" ? {
+          mode: "cloudflare-warp",
+          credential: credentialSource(privateNetwork.credential, `target ${name} WARP credential`),
+          network: stringCoordinate(privateNetwork.network, `target ${name} WARP network`)
+        } : { mode: privateNetwork.mode } } : {},
+        ...publicNetwork ? { public: publicNetwork.mode === "cloudflare-tunnel" ? {
+          mode: "cloudflare-tunnel",
+          credential: credentialSource(publicNetwork.credential, `target ${name} Tunnel credential`),
+          zone: stringCoordinate(publicNetwork.zone, `target ${name} Tunnel zone`),
+          hostname: publicNetwork.hostname.mode === "static" ? {
+            mode: "static",
+            label: stringCoordinate(publicNetwork.hostname.label, `target ${name} Tunnel label`)
+          } : {
+            mode: "indexed",
+            prefix: stringCoordinate(publicNetwork.hostname.prefix, `target ${name} Tunnel prefix`),
+            startAt: publicNetwork.hostname.startAt ?? 1
+          },
+          service: (() => {
+            const applications = Object.values(plan.spec.components).filter((component) => component.target === name && component.kind === "application" && component.network?.public?.mode === "cloudflare-tunnel");
+            if (applications.length !== 1)
+              throw new DeploymentInputError(`target ${name} Tunnel requires exactly one public application`);
+            const port = applications[0].network.ingress?.stablePort;
+            if (!Number.isInteger(port))
+              throw new DeploymentInputError(`target ${name} Tunnel application requires a stable ingress port`);
+            return { protocol: "http", port: Number(port) };
+          })()
+        } : { mode: "disabled" } } : {}
+      };
+    }
+    return {
+      name,
+      profiles: [...target.selector.profiles],
+      operatingSystem: { ...target.selector.operatingSystem },
+      confidentialCompute: target.selector.confidentialCompute ?? "disabled",
+      labels: { ...target.selector.labels ?? {} },
+      minimum: target.cardinality.minimum,
+      desired: Number(desired),
+      maximum: target.cardinality.maximum,
+      allocation: {
+        ...target.allocation,
+        resources: {
+          cpuCores: integerCoordinate(target.allocation.resources.cpuCores, `target ${name} cpuCores`, 1, 1024),
+          memoryMiB: integerCoordinate(target.allocation.resources.memoryMiB, `target ${name} memoryMiB`, 128, 4194304),
+          storageGiB: integerCoordinate(target.allocation.resources.storageGiB, `target ${name} storageGiB`, 1, 1048576)
+        }
+      },
+      ...target.provisioning ? { provisioning: { ...target.provisioning } } : {},
+      ...connectivity ? { connectivity } : {}
+    };
+  });
+}
+function resolveDeploymentInputs(plan, supplied = {}) {
+  for (const name of Object.keys(supplied))
+    if (!(name in (plan.spec.inputs ?? {}))) {
+      throw new DeploymentInputError(`deployment input ${name} is not declared`);
+    }
+  const inputs = {};
+  for (const [name, definition] of Object.entries(plan.spec.inputs ?? {})) {
+    const value = inputValue(name, definition, supplied[name]);
+    if (value !== undefined)
+      inputs[name] = value;
+  }
+  return inputs;
+}
+export {
+  resolveDeploymentTargets,
+  resolveDeploymentInputs,
+  DeploymentInputError
+};

package/dist/deployment.d.ts

@@ -9,6 +9,7 @@ import type { SecretCache } from './cache';
 import type { AttestationSource } from './socket';
 import { type CapacityCalibration, type CapacityCalibrationOptions } from './capacity-calibration';
 import { type BootstrapBundleManifest } from './bootstrap-bundle';
+import type { DeploymentConnectivityCapabilities, DeploymentConnectivityEvidence, DeploymentConnectivityIntent, DeploymentConnectivityRequest } from './deployment-connectivity';
 export interface CommandInput {
     argv: readonly string[];
     cwd?: string;
@@ -24,6 +25,20 @@ export interface DeploymentRequest {
     revision?: string;
     /** True only for the target deterministically elected for release-scoped steps. */
     releaseExecutor?: boolean;
+    /** Exact control-plane placement for this compute. Absence is allowed only for one unambiguous bootstrap target. */
+    assignment?: {
+        targetName: string;
+        slot: number;
+        definitionDigest: string;
+        operatingSystem: ResolvedDeploymentTarget['operatingSystem'];
+        confidentialCompute: ResolvedDeploymentTarget['confidentialCompute'];
+        execution: ResolvedDeploymentTarget['allocation']['execution'];
+        sharing: ResolvedDeploymentTarget['allocation']['sharing'];
+        resources: ResolvedDeploymentTarget['allocation']['resources'];
+        connectivity?: DeploymentConnectivityIntent;
+    };
+    /** Connector-scoped, one-claim capabilities. Never the project Cloudflare management token. */
+    connectivityCapabilities?: DeploymentConnectivityCapabilities;
 }
 export interface DeploymentResult {
     key: string;
@@ -49,11 +64,63 @@ export interface DeploymentResult {
 export interface ResolvedDeploymentTarget {
     name: string;
     profiles: readonly string[];
+    operatingSystem: {
+        id: 'ubuntu';
+        version: '24.04' | '26.04';
+        architecture: 'x64';
+    };
     confidentialCompute: 'required' | 'preferred' | 'disabled';
     labels: Readonly<Record<string, string>>;
     minimum: number;
     desired: number;
     maximum: number;
+    allocation: {
+        execution: 'native' | 'oci-runc' | 'oci-kata-qemu-snp';
+        sharing: 'exclusive' | 'shared';
+        resources: {
+            cpuCores: number;
+            memoryMiB: number;
+            storageGiB: number;
+        };
+        existing: 'prefer' | 'require';
+    };
+    provisioning?: {
+        planKey: string;
+        regionKey: string;
+        imageKey: string;
+        environmentKey: string;
+        ownership: 'platform' | 'tenant-metal';
+        metalHostname?: string;
+        maxMonthlySpendMinor: string;
+    };
+    connectivity?: {
+        private?: {
+            mode: 'disabled' | 'private-lan';
+        } | {
+            mode: 'cloudflare-warp';
+            credential: string;
+            network: string;
+        };
+        public?: {
+            mode: 'disabled';
+        } | {
+            mode: 'cloudflare-tunnel';
+            credential: string;
+            zone: string;
+            hostname: {
+                mode: 'static';
+                label: string;
+            } | {
+                mode: 'indexed';
+                prefix: string;
+                startAt: number;
+            };
+            service: {
+                protocol: 'http';
+                port: number;
+            };
+        };
+    };
 }
 /**
  * How the credential-bearing agent may read one server-owned Git source.
@@ -121,6 +188,8 @@ export interface DeploymentOptions {
     buildContainer?: (request: ContainerBuildRequest) => Promise<ContainerBuildResult>;
     /** Root-owned bounded container/Nginx blue-green activation. */
     activateContainer?: (request: ContainerActivateRequest) => Promise<ServiceActivationState>;
+    /** Root-owned Tunnel/WARP convergence using connector-scoped capabilities only. */
+    applyConnectivity?: (request: DeploymentConnectivityRequest) => Promise<DeploymentConnectivityEvidence>;
     /** Agent-owned directory; definitions cannot choose or overwrite this path. */
     capacityEvidenceDirectory?: string;
     /** Test/embedding seam. Production runs the bounded loopback GET calibrator. */