@forgezero/agent 0.1.0 → 0.1.9

package/dist/provision.js

@@ -30,32 +30,202 @@ var CAPABILITY_CHECKS = {
     command: "bun --version 2>/dev/null || echo missing",
     satisfied: (stdout) => atLeast(stdout, "1.1.0"),
     remedy: "Install bun: curl -fsSL https://bun.sh/install | bash"
+  },
+  python: {
+    command: "python3 --version 2>/dev/null || echo missing",
+    satisfied: (stdout, exitCode) => exitCode === 0 && /^Python 3\./.test(stdout.trim()),
+    remedy: "Install Python 3. It supplies the standard-library ioctl boundary for SNP reports."
   }
 };
 var modeFor = (capabilities) => capabilities.snpGuest ? "attested" : "enrolled";
 var reasonFor = (mode) => mode === "attested" ? "SEV-SNP guest device present, so the agent can prove what it is running and the platform can refuse it if the measurement is wrong." : "No SEV-SNP guest device. The agent authenticates with its enrolment token and hybrid Ed25519 + ML-DSA signature — weaker than attestation, stronger than an API key in the application.";
+var DEPLOYMENT_RUNNER_USER = "forgezero-runner";
+var DEPLOYMENT_GROUP = "forgezero-deploy";
+var DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
+var DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.socket";
+var DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+var ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
+function agentEnrolmentUnit(options) {
+  if (!options.apiUrl || !options.enrolTokenCredentialPath || !options.enrolStatePath) {
+    throw new Error("direct enrolment needs API, credential and state paths");
+  }
+  const bin = options.binPath ?? "fz-agent";
+  const user = options.user ?? "forgezero";
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const label = options.nodeLabel ? `Environment=FZ_NODE_LABEL=${options.nodeLabel}
+` : "";
+  const gitPublicKey = options.gitPublicKeyPath ? `Environment=FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}
+` : "";
+  const stateDir = options.enrolStatePath.replace(/\/[^/]+$/, "");
+  return `[Unit]
+Description=Bind this machine to its ForgeZero compute
+After=network-online.target
+Wants=network-online.target
+Before=forgezero-agent.service
+ConditionPathExists=!${options.enrolStatePath}
+
+[Service]
+Type=oneshot
+User=${user}
+Group=${user}
+LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
+LoadCredentialEncrypted=enrol-token:${options.enrolTokenCredentialPath}
+Environment=FZ_SEED_CREDENTIAL=agent-seed
+Environment=FZ_ENROL_TOKEN_CREDENTIAL=enrol-token
+Environment=FZ_ENROL_STATE_FILE=${options.enrolStatePath}
+Environment=FZ_API=${options.apiUrl}
+${label}${gitPublicKey}ExecStart=${bin} enrol
+# A '+' fixed command runs as root solely to remove the host-bound one-time
+# ciphertext. Tenant code and the agent never receive a privilege boundary.
+ExecStartPost=+/usr/bin/rm -f ${options.enrolTokenCredentialPath}
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=${stateDir}
+LimitCORE=0
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function deploymentRunnerSocketUnit(agentUser) {
+  return `[Unit]
+Description=ForgeZero private project-command socket
+
+[Socket]
+ListenStream=${DEPLOYMENT_RUNNER_SOCKET}
+SocketUser=${agentUser}
+SocketGroup=${agentUser}
+SocketMode=0600
+DirectoryMode=0710
+RemoveOnStop=true
+
+[Install]
+WantedBy=sockets.target
+`;
+}
+function deploymentRunnerUnit(options) {
+  const bin = options.binPath ?? "fz-agent";
+  const root = options.deployRoot ?? "/opt/forgezero";
+  return `[Unit]
+Description=ForgeZero credential-free project command runner
+Documentation=https://www.forgezero.net/docs/agent
+After=forgezero-deploy-runner.socket
+Requires=forgezero-deploy-runner.socket
+
+[Service]
+Type=simple
+User=${DEPLOYMENT_RUNNER_USER}
+Group=${DEPLOYMENT_GROUP}
+Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
+Sockets=forgezero-deploy-runner.socket
+ExecStart=${bin} deploy-runner --root=${root} --home=${root}/runner-home
+Restart=always
+RestartSec=2
+UMask=0007
+LimitCORE=0
+NoNewPrivileges=false
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+ReadWritePaths=${root}/releases ${root}/runner-home
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
 function agentUnit(options) {
   const bin = options.binPath ?? "fz-agent";
   const user = options.user ?? "forgezero";
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const controlSocketPath = options.controlSocketPath ?? "/run/forgezero/control.sock";
+  const deployRoot = options.deployRoot ?? "/opt/forgezero";
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const enrolmentEnabled = Boolean(options.enrolTokenCredentialPath && options.enrolStatePath);
+  const deploymentEnvironment = options.deploymentEnvironment ?? {};
+  const deploymentCredentials = options.deploymentCredentials ?? {};
+  for (const [name, value] of Object.entries(deploymentEnvironment)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !/^[A-Za-z0-9._:\/@+-]+$/.test(value)) {
+      throw new Error(`invalid deployment environment entry: ${name}`);
+    }
+  }
+  for (const [name, path] of Object.entries(deploymentCredentials)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !path.startsWith("/") || /[\r\n:]/.test(path)) {
+      throw new Error(`invalid deployment credential entry: ${name}`);
+    }
+  }
   const environment = [
     `FZ_SOCKET_PATH=${options.socketPath}`,
-    `FZ_SEED_PATH=${options.seedPath}`,
+    `FZ_CONTROL_SOCKET=${controlSocketPath}`,
+    `FZ_SEED_CREDENTIAL=agent-seed`,
     `FZ_AGENT_MODE=${options.mode}`,
     options.apiUrl ? `FZ_API=${options.apiUrl}` : null,
     options.project ? `FZ_PROJECT=${options.project}` : null,
-    options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null
+    options.environment ? `FZ_ENVIRONMENT=${options.environment}` : null,
+    options.enrolStatePath ? `FZ_ENROL_STATE_FILE=${options.enrolStatePath}` : null,
+    options.nodeLabel ? `FZ_NODE_LABEL=${options.nodeLabel}` : null,
+    options.gitPublicKeyPath ? `FZ_GIT_PUBLIC_KEY_FILE=${options.gitPublicKeyPath}` : null,
+    options.repository ? `FZ_DEPLOY_REPO=${options.repository}` : null,
+    options.branch ? `FZ_DEPLOY_BRANCH=${options.branch}` : null,
+    options.role ? `FZ_DEPLOY_ROLE=${options.role}` : null,
+    options.repository && options.branch ? `FZ_DEPLOY_KEY=${options.project ?? "platform"}:${options.environment ?? "production"}` : null,
+    deploymentEnabled ? `FZ_DEPLOY_ROOT=${deployRoot}` : null,
+    deploymentEnabled ? `FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}` : null,
+    Object.keys(deploymentCredentials).length > 0 ? `FZ_DEPLOY_SYSTEMD_SECRETS=${Object.keys(deploymentCredentials).join(",")}` : null,
+    Object.keys(deploymentEnvironment).length > 0 ? `FZ_DEPLOY_ENV_NAMES=${Object.keys(deploymentEnvironment).join(",")}` : null,
+    ...Object.entries(deploymentEnvironment).map(([name, value]) => `${name}=${value}`),
+    options.publicApiUrl ? `FZ_PUBLIC_API_URL=${options.publicApiUrl}` : null,
+    options.pullDeployments ? "FZ_DEPLOY_PULL=true" : null
   ].filter((line) => line !== null);
+  if (deploymentEnabled) {
+    environment.push(`HOME=${deployRoot}/agent-home`, `XDG_CACHE_HOME=${deployRoot}/cache`);
+  }
+  const gitCredential = options.gitCredentialPath ? `LoadCredentialEncrypted=git-deploy-key:${options.gitCredentialPath}
+` : "";
+  const projectCredentials = Object.entries(deploymentCredentials).map(([name, path]) => `LoadCredentialEncrypted=${name}:${path}`).join(`
+`);
+  const deploymentWrites = deploymentEnabled ? `ReadWritePaths=${deployRoot}/releases ${deployRoot}/agent-home ${deployRoot}/cache` : "";
+  const deploymentGroup = deploymentEnabled ? `SupplementaryGroups=${DEPLOYMENT_GROUP}` : "";
+  const after = [
+    "network-online.target",
+    deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    enrolmentEnabled ? "forgezero-agent-enrol.service" : null
+  ].filter((value) => value !== null);
+  const requires = [
+    deploymentEnabled ? "forgezero-deploy-runner.service" : null,
+    enrolmentEnabled ? "forgezero-agent-enrol.service" : null
+  ].filter((value) => value !== null);
+  const deploymentDependency = [
+    `After=${after.join(" ")}`,
+    "Wants=network-online.target",
+    requires.length > 0 ? `Requires=${requires.join(" ")}` : null
+  ].filter((value) => value !== null).join(`
+`);
+  const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
+DeviceAllow=/dev/sev-guest rw` : "";
+  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${user} /dev/sev-guest
+ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
+` : "";
   return `[Unit]
 Description=ForgeZero node agent (${options.mode})
-Documentation=https://forgezero.net/docs/agent
-After=network-online.target
-Wants=network-online.target
+Documentation=https://www.forgezero.net/docs/agent
+${deploymentDependency}
 
 [Service]
 Type=simple
 User=${user}
 Group=${user}
-ExecStart=${bin}
+${deploymentGroup}
+LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
+${gitCredential}${projectCredentials}${projectCredentials ? `
+` : ""}${snpPrepare}ExecStart=${bin}
 Restart=always
 RestartSec=2
 
@@ -71,7 +241,10 @@ LimitCORE=0
 # than wherever the process happened to have write access.
 RuntimeDirectory=forgezero
 RuntimeDirectoryMode=0710
+UMask=0077
 
+# Tenant-controlled commands execute in forgezero-deploy-runner.service. This
+# credential-bearing process never needs to cross a privilege boundary.
 NoNewPrivileges=true
 PrivateTmp=true
 ProtectSystem=strict
@@ -83,7 +256,8 @@ RestrictSUIDSGID=true
 RestrictRealtime=true
 MemoryDenyWriteExecute=true
 LockPersonality=true
-ReadWritePaths=${options.seedPath.replace(/\/[^/]+$/, "")}
+${snpDevice}
+${deploymentWrites}
 
 [Install]
 WantedBy=multi-user.target
@@ -93,27 +267,118 @@ var UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
 function planProvision(options) {
   const mode = options.mode;
   const user = options.user ?? "forgezero";
-  const seedDir = options.seedPath.replace(/\/[^/]+$/, "");
+  const seedCredentialPath = options.seedCredentialPath ?? "/etc/forgezero/creds/agent-seed.cred";
+  const credentialDir = seedCredentialPath.replace(/\/[^/]+$/, "");
+  const deployRoot = options.deployRoot ?? "/opt/forgezero";
+  const deploymentEnabled = Boolean(options.repository || options.pullDeployments);
+  const enrolmentEnabled = Boolean(options.enrolTokenSourcePath && options.enrolTokenCredentialPath && options.enrolStatePath);
+  if (Boolean(options.enrolTokenSourcePath) !== Boolean(options.enrolTokenCredentialPath) || Boolean(options.enrolTokenCredentialPath) !== Boolean(options.enrolStatePath))
+    throw new Error("direct enrolment paths must be supplied together");
+  const safePath = (value, label) => {
+    if (!value || !/^\/[A-Za-z0-9._@/-]+$/.test(value))
+      throw new Error(`invalid ${label} path`);
+    return value;
+  };
+  const enrolTokenSourcePath = enrolmentEnabled ? safePath(options.enrolTokenSourcePath, "enrolment source") : undefined;
+  const enrolTokenCredentialPath = enrolmentEnabled ? safePath(options.enrolTokenCredentialPath, "enrolment credential") : undefined;
+  const enrolStatePath = enrolmentEnabled ? safePath(options.enrolStatePath, "enrolment state") : undefined;
+  const enrolStateDir = enrolStatePath?.replace(/\/[^/]+$/, "");
+  const sourceBinPath = options.sourceBinPath ? safePath(options.sourceBinPath, "agent source binary") : undefined;
+  const binPath = options.binPath ? safePath(options.binPath, "agent binary") : undefined;
+  const gitCredentialPath = options.gitCredentialPath ? safePath(options.gitCredentialPath, "Git credential") : undefined;
+  const gitPublicKeyPath = options.gitPublicKeyPath ? safePath(options.gitPublicKeyPath, "Git public key") : undefined;
+  if (options.generateGitIdentity && (!gitCredentialPath || !gitPublicKeyPath)) {
+    throw new Error("generated Git identity needs credential and public-key paths");
+  }
+  const gitPublicKeyDir = gitPublicKeyPath?.replace(/\/[^/]+$/, "");
   return {
     mode,
     reason: reasonFor(mode),
     unitPath: UNIT_PATH,
     unit: agentUnit({ ...options, mode }),
+    auxiliaryUnits: [
+      ...deploymentEnabled ? [
+        { path: DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH, unit: deploymentRunnerSocketUnit(user) },
+        { path: DEPLOYMENT_RUNNER_UNIT_PATH, unit: deploymentRunnerUnit(options) }
+      ] : [],
+      ...enrolmentEnabled ? [
+        { path: ENROLMENT_UNIT_PATH, unit: agentEnrolmentUnit(options) }
+      ] : []
+    ],
     socketPath: options.socketPath,
     user,
     steps: [
+      ...sourceBinPath && binPath ? [{
+        label: "root-owned agent runtime",
+        command: `install -d -o root -g root -m 0755 ${binPath.replace(/\/[^/]+$/, "")}; ` + `install -o root -g root -m 0755 ${sourceBinPath} ${binPath}`
+      }] : [],
+      ...deploymentEnabled ? [{
+        label: "deployment isolation group",
+        command: `groupadd --system ${DEPLOYMENT_GROUP} || true`
+      }] : [],
       {
         label: "service account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
       },
+      ...deploymentEnabled ? [{
+        label: "credential-free deployment account",
+        command: `useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} || true; ` + `usermod -a -G ${DEPLOYMENT_GROUP} ${user}`
+      }] : [],
       {
-        label: "seed directory",
-        command: `install -d -o ${user} -g ${user} -m 0700 ${seedDir}`
+        label: "credential directory",
+        command: `install -d -o root -g root -m 0700 ${credentialDir}`
       },
+      {
+        label: "encrypted node identity",
+        command: `test -s ${seedCredentialPath} || { ` + `openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\\n' | ` + `systemd-creds encrypt --name=agent-seed - ${seedCredentialPath}; ` + `chmod 0400 ${seedCredentialPath}; }`
+      },
+      ...options.generateGitIdentity && gitCredentialPath && gitPublicKeyPath ? [
+        {
+          label: "Git deploy identity directory",
+          command: `install -d -o root -g root -m 0755 ${gitPublicKeyDir}`
+        },
+        {
+          label: "unique encrypted Git deploy identity",
+          command: `test -s ${gitCredentialPath} || { ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `ssh-keygen -q -t ed25519 -N '' -C forgezero-compute -f /run/forgezero-git-deploy-key; ` + `systemd-creds encrypt --name=git-deploy-key /run/forgezero-git-deploy-key ${gitCredentialPath}; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; ` + `chmod 0400 ${gitCredentialPath}; }; ` + `test -s ${gitPublicKeyPath} || { ` + `systemd-creds decrypt --name=git-deploy-key ${gitCredentialPath} /run/forgezero-git-deploy-key; ` + `ssh-keygen -y -f /run/forgezero-git-deploy-key | ` + `sed 's/$/ forgezero-compute/' > /run/forgezero-git-deploy-key.pub; ` + `install -o root -g root -m 0444 /run/forgezero-git-deploy-key.pub ${gitPublicKeyPath}; ` + `rm -f /run/forgezero-git-deploy-key /run/forgezero-git-deploy-key.pub; }; ` + `test -s ${gitCredentialPath} && test -s ${gitPublicKeyPath}`
+        }
+      ] : [],
+      ...enrolmentEnabled ? [
+        {
+          label: "enrolment state directory",
+          command: `install -d -o ${user} -g ${user} -m 0700 ${enrolStateDir}`
+        },
+        {
+          label: "encrypted one-time enrolment capability",
+          command: `test -s ${enrolTokenCredentialPath} || { test -r ${enrolTokenSourcePath}; ` + `systemd-creds encrypt --name=enrol-token ${enrolTokenSourcePath} ${enrolTokenCredentialPath}; ` + `chmod 0400 ${enrolTokenCredentialPath}; rm -f ${enrolTokenSourcePath}; }`
+        }
+      ] : [],
+      ...deploymentEnabled ? [{
+        label: "deployment directories",
+        command: `install -d -o root -g root -m 0755 ${deployRoot} && ` + `install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 ${deployRoot}/releases && ` + `install -d -o ${user} -g ${user} -m 0750 ${deployRoot}/cache && ` + `install -d -o ${user} -g ${user} -m 0700 ${deployRoot}/agent-home && ` + `install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 ${deployRoot}/runner-home ${deployRoot}/runner-home/cache`
+      }] : [],
       { label: "reload units", command: "systemctl daemon-reload" },
-      { label: "enable and start", command: "systemctl enable --now forgezero-agent.service" },
+      {
+        label: "enable and start",
+        command: `systemctl enable --now ${[
+          ...deploymentEnabled ? ["forgezero-deploy-runner.socket", "forgezero-deploy-runner.service"] : [],
+          ...enrolmentEnabled ? ["forgezero-agent-enrol.service"] : [],
+          "forgezero-agent.service"
+        ].join(" ")}`
+      },
+      ...enrolmentEnabled ? [{
+        label: "prove the compute binding is durable",
+        command: `test -s ${enrolStatePath}`
+      }] : [],
       { label: "prove it is running", command: "systemctl is-active forgezero-agent.service" },
-      { label: "prove the socket exists", command: `test -S ${options.socketPath}` }
+      { label: "prove the vault socket exists", command: `test -S ${options.socketPath}` },
+      ...deploymentEnabled ? [{
+        label: "prove the deployment runner socket exists",
+        command: `test -S ${DEPLOYMENT_RUNNER_SOCKET}`
+      }] : [],
+      ...options.repository ? [{
+        label: "prove the deployment control socket exists",
+        command: `test -S ${options.controlSocketPath ?? "/run/forgezero/control.sock"}`
+      }] : []
     ]
   };
 }
@@ -121,8 +386,17 @@ export {
   reasonFor,
   planProvision,
   modeFor,
+  deploymentRunnerUnit,
+  deploymentRunnerSocketUnit,
   atLeast,
   agentUnit,
+  agentEnrolmentUnit,
   UNIT_PATH,
+  ENROLMENT_UNIT_PATH,
+  DEPLOYMENT_RUNNER_USER,
+  DEPLOYMENT_RUNNER_UNIT_PATH,
+  DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH,
+  DEPLOYMENT_RUNNER_SOCKET,
+  DEPLOYMENT_GROUP,
   CAPABILITY_CHECKS
 };

package/dist/provisioning-pull.d.ts

@@ -0,0 +1,75 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import { type SignedNodeHttpOptions } from './signed-node-http';
+interface RemoteProvisionClaimBase {
+    computeKey: string;
+    claimToken: string;
+    claimExpiresAtTs: number;
+    attempt: number;
+    spec: {
+        reference: string;
+        imageKey: string;
+        physicalCores: number;
+        vcpu: number;
+        memoryGib: number;
+        diskGib: number;
+        egressGuaranteedMbps: number;
+        egressBurstMbps: number;
+        confidential: boolean;
+    };
+}
+export type CreateRemoteProvisionClaim = RemoteProvisionClaimBase & {
+    action?: 'create';
+    enrolment: {
+        token: string;
+        tenantKey: string;
+        projectKey: string;
+        environmentKey: string;
+    };
+};
+export type RemoteProvisionClaim = CreateRemoteProvisionClaim | (RemoteProvisionClaimBase & {
+    action: 'delete';
+});
+export interface ProvisionResult {
+    guestAddress?: string;
+}
+export type ProvisionRunner = (claim: RemoteProvisionClaim) => Promise<ProvisionResult>;
+export interface ProvisioningPullOptions extends SignedNodeHttpOptions {
+    keys: NodeKeyPair;
+    run: ProvisionRunner;
+    intervalMs?: number;
+    completionAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    renewRetryMs?: number;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+    /** Fresh local facts, sent signed before this host may claim work. */
+    metalPreflight?: () => {
+        snpHost: boolean;
+        kvm: boolean;
+        helper: boolean;
+    };
+}
+export type ProvisionPullResult = {
+    status: 'idle';
+} | {
+    status: 'running';
+    claim: RemoteProvisionClaim;
+    result: ProvisionResult;
+} | {
+    status: 'terminated';
+    claim: RemoteProvisionClaim;
+    result: ProvisionResult;
+} | {
+    status: 'failed';
+    claim: RemoteProvisionClaim;
+    reason: string;
+};
+/** Claim one compute, await the local helper, then durably acknowledge it. */
+export declare function pullProvisioningOnce(options: ProvisioningPullOptions): Promise<ProvisionPullResult>;
+export declare function startProvisioningPull(options: ProvisioningPullOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};
+export {};

package/dist/provisioning-pull.js

@@ -0,0 +1,188 @@
+// src/signed-node-http.ts
+import { signRequest } from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+var signatureHeader = (envelope) => Buffer.from(JSON.stringify({
+  timestamp: envelope.timestamp,
+  nonce: envelope.nonce,
+  edSignature: envelope.edSignature,
+  mlDsaSignature: envelope.mlDsaSignature
+})).toString("base64url");
+async function postSignedNode(options, path, body) {
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const raw = JSON.stringify(body);
+  const envelope = signRequest(options.keys, options.nodeKey, {
+    method: "POST",
+    path: url.pathname,
+    query: "",
+    body: raw
+  });
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-fz-node": options.nodeKey,
+      "x-fz-signature": signatureHeader(envelope)
+    },
+    body: raw,
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    const failure = payload;
+    const reason = failure ? failure.error?.message ?? failure.message : undefined;
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+  }
+  return payload;
+}
+
+// src/provisioning-pull.ts
+class ProvisionClaimLostError extends Error {
+}
+var post = (options, operation, body) => postSignedNode(options, `v1/metal/computes/${operation}`, body);
+async function runClaim(options, claim) {
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  const now = options.now ?? Date.now;
+  let expires = claim.claimExpiresAtTs;
+  let stopped = false;
+  let timer;
+  let renewal = null;
+  let lost = null;
+  const schedule = (override) => {
+    if (stopped)
+      return;
+    const delay = override ?? Math.max(1000, Math.floor(Math.max(0, expires - now()) / 3));
+    timer = setTimer(() => {
+      if (stopped || renewal)
+        return;
+      let retry;
+      renewal = post(options, "renew", {
+        computeKey: claim.computeKey,
+        claimToken: claim.claimToken
+      }).then((response) => {
+        expires = response.claimExpiresAtTs;
+        options.onEvent?.("lease-renewed", { computeKey: claim.computeKey, claimExpiresAtTs: expires });
+      }).catch((cause) => {
+        if (cause instanceof SignedNodeHttpError && cause.status < 500) {
+          lost = new ProvisionClaimLostError(cause.message);
+          stopped = true;
+        } else {
+          retry = Math.max(1000, options.renewRetryMs ?? 5000);
+          options.onEvent?.("lease-renew-failed", cause);
+        }
+      }).finally(() => {
+        renewal = null;
+        if (!stopped)
+          schedule(retry);
+      });
+    }, delay);
+  };
+  schedule();
+  let result;
+  try {
+    result = await options.run(claim);
+  } finally {
+    stopped = true;
+    clearTimer(timer);
+    await renewal;
+  }
+  if (lost)
+    throw lost;
+  return result;
+}
+async function complete(options, body) {
+  const attempts = Math.max(1, Math.min(options.completionAttempts ?? 5, 10));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let last;
+  for (let attempt = 1;attempt <= attempts; attempt += 1) {
+    try {
+      await post(options, "complete", body);
+      return;
+    } catch (cause) {
+      last = cause;
+      if (cause instanceof SignedNodeHttpError && cause.status < 500)
+        throw cause;
+      if (attempt < attempts)
+        await sleep(Math.min(2000, 250 * 2 ** (attempt - 1)));
+    }
+  }
+  throw last;
+}
+async function pullProvisioningOnce(options) {
+  if (options.metalPreflight) {
+    const report = options.metalPreflight();
+    const accepted = await postSignedNode(options, "v1/metal/preflight", report);
+    options.onEvent?.("preflight", { ...report, ready: accepted.ready, state: accepted.state });
+    if (!accepted.ready)
+      return { status: "idle" };
+  }
+  const response = await post(options, "claim", {});
+  if (!response.claim)
+    return { status: "idle" };
+  const claim = response.claim;
+  let result;
+  try {
+    result = await runClaim(options, claim);
+  } catch (cause) {
+    if (cause instanceof ProvisionClaimLostError)
+      throw cause;
+    const reason = (cause instanceof Error ? cause.message : String(cause)).slice(0, 2000);
+    await complete(options, {
+      computeKey: claim.computeKey,
+      claimToken: claim.claimToken,
+      ok: false,
+      detail: reason
+    });
+    return { status: "failed", claim, reason };
+  }
+  await complete(options, {
+    computeKey: claim.computeKey,
+    claimToken: claim.claimToken,
+    ok: true,
+    ...result.guestAddress ? { guestAddress: result.guestAddress } : {}
+  });
+  return { status: claim.action === "delete" ? "terminated" : "running", claim, result };
+}
+function startProvisioningPull(options) {
+  const interval = Math.max(1000, options.intervalMs ?? 5000);
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  let stopped = false;
+  let timer;
+  let active = null;
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = pullProvisioningOnce(options).then((result) => options.onEvent?.(result.status, result)).catch((cause) => options.onEvent?.("poll-failed", cause)).finally(() => {
+      active = null;
+      if (!stopped)
+        timer = setTimer(tick, interval);
+    });
+  };
+  tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+export {
+  startProvisioningPull,
+  pullProvisioningOnce
+};

package/dist/provisioning-pull.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/signed-node-http.d.ts

@@ -0,0 +1,14 @@
+import { type NodeKeyPair } from '@forgezero/runtime/identity';
+export interface SignedNodeHttpOptions {
+    apiUrl: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    requestTimeoutMs?: number;
+}
+export declare class SignedNodeHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** One implementation of the hybrid-signed machine HTTP contract. */
+export declare function postSignedNode<T>(options: SignedNodeHttpOptions, path: string, body: object): Promise<T>;

package/dist/snp-attestation.d.ts

@@ -0,0 +1,18 @@
+import type { AttestationSource } from './socket';
+/**
+ * Minimal Linux SNP guest ioctl helper.
+ *
+ * Python is the native boundary because it is already required by the Ubuntu
+ * cloud image, `ctypes` is standard-library code, and Bun documents its own FFI
+ * as experimental. Arguments are passed directly, never through a shell.
+ */
+export declare const SNP_REPORT_HELPER: string;
+export interface SnpAttestationOptions {
+    device?: string;
+    python?: string;
+    timeoutMs?: number;
+    spawn?: typeof Bun.spawn;
+    exists?: (path: string) => boolean;
+}
+/** A real PSP report source. Device presence alone is never called attestation. */
+export declare function createSnpAttestationSource(options?: SnpAttestationOptions): AttestationSource;

package/dist/snp-attestation.test.d.ts

@@ -0,0 +1 @@
+export {};