@forgezero/agent 0.1.10 → 0.1.12

package/dist/metal-provision.d.ts

@@ -68,8 +68,8 @@ export declare function validateMetalProfile(profile: MetalProvisionProfile): vo
 export declare function allocateAddress(profile: MetalProvisionProfile, computeKey: string, rows: GuestManifest[]): string;
 /** Stable tight-fit allocation of one exclusive CPU/NUMA pool. */
 export declare function allocateCpuPool(profile: MetalProvisionProfile, claim: Pick<RemoteProvisionClaim, 'computeKey' | 'spec'>, rows: GuestManifest[]): MetalCpuPool;
-export declare function guestBootstrapScript(profile: MetalProvisionProfile, attested?: boolean): string;
-export declare function guestAgentUnit(profile: MetalProvisionProfile, name: string, attested?: boolean): string;
+export declare function guestBootstrapScript(profile: MetalProvisionProfile, attested?: boolean, hasEnrolment?: boolean): string;
+export declare function guestAgentUnit(profile: MetalProvisionProfile, name: string, attested?: boolean, pull?: boolean): string;
 /** Removed by the root cleanup service once the non-secret binding is durable. */
 export declare function guestEnrolmentDropIn(): string;
 export declare function guestEnrolmentCleanupScript(): string;

package/dist/metal-provision.js

@@ -181,6 +181,7 @@ 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 VAULT_GROUP = "forgezero-vault";
 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";
@@ -350,7 +351,7 @@ function agentUnit(options) {
 `);
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
 DeviceAllow=/dev/sev-guest rw` : "";
-  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${user} /dev/sev-guest
+  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
   return `[Unit]
@@ -361,7 +362,7 @@ ${deploymentDependency}
 [Service]
 Type=simple
 User=${user}
-Group=${user}
+Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
@@ -380,8 +381,8 @@ LimitCORE=0
 # scope. So it lives in a directory systemd creates with a known owner rather
 # than wherever the process happened to have write access.
 RuntimeDirectory=forgezero
-RuntimeDirectoryMode=0710
-UMask=0077
+RuntimeDirectoryMode=0750
+UMask=0007
 
 # Tenant-controlled commands execute in forgezero-deploy-runner.service. This
 # credential-bearing process never needs to cross a privilege boundary.
@@ -448,6 +449,10 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
+      {
+        label: "vault socket access group",
+        command: `groupadd --system ${VAULT_GROUP} || true`
+      },
       ...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}`
@@ -460,6 +465,10 @@ function planProvision(options) {
         label: "service account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
       },
+      {
+        label: "bind service account to vault group",
+        command: `usermod -g ${VAULT_GROUP} ${user}`
+      },
       ...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}`
@@ -523,6 +532,21 @@ function planProvision(options) {
   };
 }
 
+// src/ubuntu.ts
+var SUPPORTED_GUEST_IMAGE = Object.freeze({
+  key: "ubuntu-resolute-20260731",
+  family: "ubuntu-26.04",
+  version: "2026-07-31",
+  label: "Ubuntu 26.04 LTS Resolute",
+  url: "https://cloud-images.ubuntu.com/releases/resolute/release-20260731/ubuntu-26.04-server-cloudimg-amd64.img",
+  sha256: "9dc7c5363c0146a08ba0c9aa834d82c2c6dfbb1c471ad9a2f0aba1189e21be05"
+});
+function assertSupportedGuestImage(imageKey) {
+  if (imageKey !== SUPPORTED_GUEST_IMAGE.key) {
+    throw new Error(`unsupported guest image ${imageKey}; ForgeZero currently supports only ${SUPPORTED_GUEST_IMAGE.key}`);
+  }
+}
+
 // src/metal-provision.ts
 import { createHash } from "node:crypto";
 import {
@@ -530,6 +554,7 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  rmSync,
   statSync,
   unlinkSync,
   writeFileSync
@@ -584,6 +609,10 @@ function validateMetalProfile(profile) {
       throw new MetalProvisionError("metal paths must be absolute");
   }
   new URL(profile.apiUrl);
+  const imageKeys = Object.keys(profile.images);
+  if (imageKeys.length !== 1 || imageKeys[0] !== SUPPORTED_GUEST_IMAGE.key || profile.images[SUPPORTED_GUEST_IMAGE.key]?.sha256 !== SUPPORTED_GUEST_IMAGE.sha256) {
+    throw new MetalProvisionError(`metal profile must contain only the pinned ${SUPPORTED_GUEST_IMAGE.key} image contract`);
+  }
   if (!Array.isArray(profile.cpuPools) || profile.cpuPools.length === 0) {
     throw new MetalProvisionError("at least one exclusive CPU pool is required");
   }
@@ -649,6 +678,21 @@ function allocateAddress(profile, computeKey, rows) {
   }
   throw new MetalProvisionError("guest address range is full");
 }
+function requestedAddress(profile, claim, rows) {
+  if (!claim.spec.guestAddress)
+    return allocateAddress(profile, claim.computeKey, rows);
+  if (!claim.spec.guestAddress.startsWith(`${profile.subnetPrefix}.`)) {
+    throw new MetalProvisionError("requested guest address is outside the metal profile");
+  }
+  const last = Number(claim.spec.guestAddress.slice(profile.subnetPrefix.length + 1));
+  if (!Number.isInteger(last) || last < profile.addressStart || last > profile.addressEnd) {
+    throw new MetalProvisionError("requested guest address is outside the allocatable range");
+  }
+  const occupied = rows.find((row) => row.address === claim.spec.guestAddress && row.computeKey !== claim.computeKey);
+  if (occupied)
+    throw new MetalProvisionError("requested guest address is already allocated");
+  return claim.spec.guestAddress;
+}
 function allocateCpuPool(profile, claim, rows) {
   const prior = rows.find((row) => row.computeKey === claim.computeKey);
   if (prior) {
@@ -659,6 +703,15 @@ function allocateCpuPool(profile, claim, rows) {
     return retained;
   }
   const used = new Set(rows.map((row) => row.cpuPoolKey));
+  if (claim.spec.cpuPoolKey) {
+    const requested = profile.cpuPools.find((pool) => pool.key === claim.spec.cpuPoolKey);
+    if (!requested || used.has(requested.key)) {
+      throw new MetalProvisionError("requested CPU pool is unavailable");
+    }
+    if (requested.physicalCores < claim.spec.physicalCores || membersOfLinuxList(requested.cpus, "CPU").length < claim.spec.vcpu)
+      throw new MetalProvisionError("requested CPU pool cannot satisfy this guest");
+    return requested;
+  }
   const candidates = profile.cpuPools.filter((pool) => !used.has(pool.key) && pool.physicalCores >= claim.spec.physicalCores && membersOfLinuxList(pool.cpus, "CPU").length >= claim.spec.vcpu).sort((left, right) => left.physicalCores - right.physicalCores || membersOfLinuxList(left.cpus, "CPU").length - membersOfLinuxList(right.cpus, "CPU").length || left.key.localeCompare(right.key));
   const selected = candidates[0];
   if (!selected)
@@ -671,7 +724,7 @@ var yamlFile = (path, content, permissions) => `  - path: ${JSON.stringify(path)
     encoding: b64
     content: ${base64(content)}
 `;
-function guestBootstrapScript(profile, attested = Boolean(profile.confidential)) {
+function guestBootstrapScript(profile, attested = Boolean(profile.confidential), hasEnrolment = true) {
   const agentBun = "/usr/local/lib/forgezero/bun";
   const attestationSetup = attested ? `# The report device is not part of the encryption path, so a guest can appear
 # healthy and encrypted while attestation is silently impossible. Install and
@@ -684,7 +737,9 @@ test -c /dev/sev-guest
 ` : "";
   return `#!/usr/bin/env bash
 set -Eeuo pipefail
-${attestationSetup}useradd --system --no-create-home --shell /usr/sbin/nologin forgezero-agent 2>/dev/null || true
+${attestationSetup}groupadd --system ${VAULT_GROUP} 2>/dev/null || true
+useradd --system --no-create-home --shell /usr/sbin/nologin forgezero-agent 2>/dev/null || true
+usermod -g ${VAULT_GROUP} forgezero-agent
 groupadd --system ${DEPLOYMENT_GROUP} 2>/dev/null || true
 useradd --system --no-create-home --shell /usr/sbin/nologin --gid ${DEPLOYMENT_GROUP} ${DEPLOYMENT_RUNNER_USER} 2>/dev/null || true
 usermod -a -G ${DEPLOYMENT_GROUP} forgezero-agent
@@ -695,13 +750,13 @@ install -d -o root -g root -m 0755 /opt/forgezero
 install -d -o root -g ${DEPLOYMENT_GROUP} -m 3770 /opt/forgezero/releases
 install -d -o forgezero-agent -g forgezero-agent -m 0700 /opt/forgezero/cache /opt/forgezero/home
 install -d -o ${DEPLOYMENT_RUNNER_USER} -g ${DEPLOYMENT_GROUP} -m 0700 /opt/forgezero/runner-home /opt/forgezero/runner-home/cache
-if [[ -s /run/forgezero-enrol-token ]]; then
+${hasEnrolment ? `if [[ -s /run/forgezero-enrol-token ]]; then
   systemd-creds encrypt --name=enrol-token /run/forgezero-enrol-token /var/lib/forgezero/enrol-token.cred
   rm -f /run/forgezero-enrol-token
 fi
 chown root:root /var/lib/forgezero/enrol-token.cred
 chmod 0400 /var/lib/forgezero/enrol-token.cred
-if [[ ! -x /usr/local/bin/bun ]]; then
+` : ""}if [[ ! -x /usr/local/bin/bun ]]; then
   curl -fsSL https://bun.sh/install -o /run/fz-bun-install
   printf '%s  %s
 ' '${profile.bunInstallerSha256}' /run/fz-bun-install | sha256sum -c -
@@ -740,8 +795,8 @@ systemctl daemon-reload
 systemctl enable --now forgezero-deploy-runner.socket forgezero-deploy-runner.service forgezero-agent.service
 `;
 }
-function guestAgentUnit(profile, name, attested = Boolean(profile.confidential)) {
-  const attestationPrepare = attested ? `ExecStartPre=+/bin/chgrp forgezero-agent /dev/sev-guest
+function guestAgentUnit(profile, name, attested = Boolean(profile.confidential), pull = true) {
+  const attestationPrepare = attested ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
   const attestationDevice = attested ? `DevicePolicy=closed
@@ -756,7 +811,7 @@ Requires=forgezero-deploy-runner.service
 [Service]
 Type=simple
 User=forgezero-agent
-Group=forgezero-agent
+Group=${VAULT_GROUP}
 SupplementaryGroups=${DEPLOYMENT_GROUP}
 LoadCredentialEncrypted=agent-seed:/etc/forgezero/creds/agent-seed.cred
 LoadCredentialEncrypted=git-deploy-key:/etc/forgezero/creds/git-deploy-key.cred
@@ -767,15 +822,15 @@ Environment=FZ_ENROL_STATE_FILE=/var/lib/forgezero/enrolment.json
 Environment=FZ_NODE_LABEL=${name}
 Environment=FZ_SOCKET_PATH=/run/forgezero/vault.sock
 Environment=FZ_DEPLOY_ROOT=/opt/forgezero
-Environment=FZ_DEPLOY_PULL=true
+Environment=FZ_DEPLOY_PULL=${pull ? "true" : "false"}
 Environment=FZ_DEPLOY_RUNNER_SOCKET=${DEPLOYMENT_RUNNER_SOCKET}
 Environment=HOME=/opt/forgezero/home
 ${attestationPrepare}ExecStart=/usr/local/bin/fz-agent
 Restart=on-failure
 RestartSec=5
 RuntimeDirectory=forgezero
-RuntimeDirectoryMode=0710
-UMask=0077
+RuntimeDirectoryMode=0750
+UMask=0007
 LimitCORE=0
 NoNewPrivileges=true
 PrivateTmp=true
@@ -825,24 +880,39 @@ WantedBy=multi-user.target
 `;
 }
 function cloudInit(profile, claim, manifest) {
-  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential);
-  const agentUnit2 = guestAgentUnit(profile, manifest.name, claim.spec.confidential);
+  const enrolled = Boolean(claim.enrolment);
+  const bootstrap = guestBootstrapScript(profile, claim.spec.confidential, enrolled);
+  const agentUnit2 = guestAgentUnit(profile, manifest.name, claim.spec.confidential, enrolled);
   const enrolmentDropIn = guestEnrolmentDropIn();
   const cleanupScript = guestEnrolmentCleanupScript();
   const cleanupUnit = guestEnrolmentCleanupUnit();
   const runnerSocketUnit = deploymentRunnerSocketUnit("forgezero-agent");
   const runnerUnit = deploymentRunnerUnit({ binPath: "/usr/local/bin/fz-agent", deployRoot: "/opt/forgezero" });
+  const access = claim.access;
+  const users = access ? `users:
+  - default
+  - name: ${access.sshUser}
+    groups: [sudo]
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+${access.sshPublicKeys.map((key) => `      - ${JSON.stringify(key)}`).join(`
+`)}
+` : "";
+  const enrolmentFiles = enrolled ? `${yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
+`, "0600")}${yamlFile("/usr/local/sbin/forgezero-enrolment-cleanup", cleanupScript, "0700")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}` : "";
   return {
     userData: `#cloud-config
 package_update: true
+${users}disable_root: true
 # Git is part of the deployment transport, not a tenant-selected prerequisite:
 # every dynamically claimed repository must be cloneable on a clean image.
 packages: [curl, ca-certificates, openssl, openssh-client, git${claim.spec.confidential ? ", python3" : ""}]
 write_files:
-${yamlFile("/run/forgezero-enrol-token", `${claim.enrolment.token}
-`, "0600")}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/usr/local/sbin/forgezero-enrolment-cleanup", cleanupScript, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.socket", runnerSocketUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit2, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service.d/enrolment.conf", enrolmentDropIn, "0644")}${yamlFile("/etc/systemd/system/forgezero-enrolment-cleanup.service", cleanupUnit, "0644")}runcmd:
+${enrolmentFiles}${yamlFile("/usr/local/sbin/forgezero-guest-bootstrap", bootstrap, "0700")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.socket", runnerSocketUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-deploy-runner.service", runnerUnit, "0644")}${yamlFile("/etc/systemd/system/forgezero-agent.service", agentUnit2, "0644")}runcmd:
   - [ bash, /usr/local/sbin/forgezero-guest-bootstrap ]
-  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+${enrolled ? `  - [ systemctl, enable, --now, forgezero-enrolment-cleanup.service ]
+` : ""}
 `,
     metaData: `instance-id: ${manifest.name}-${claim.attempt}
 local-hostname: ${manifest.name}
@@ -866,7 +936,8 @@ var checked = async (exec, argv) => {
 };
 async function provisionMetalGuest(profile, claim, exec) {
   validateMetalProfile(profile);
-  if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
+  assertSupportedGuestImage(claim.spec.imageKey);
+  if (!claim.computeKey || !claim.spec.reference || !SAFE_NAME.test(claim.spec.imageKey) || claim.spec.guestName !== undefined && !SAFE_NAME.test(claim.spec.guestName) || claim.spec.cpuPoolKey !== undefined && !SAFE_NAME.test(claim.spec.cpuPoolKey) || !Number.isInteger(claim.spec.physicalCores) || claim.spec.physicalCores < 1 || claim.spec.physicalCores > 256 || !Number.isInteger(claim.spec.vcpu) || claim.spec.vcpu < 1 || claim.spec.vcpu > 512 || !Number.isInteger(claim.spec.memoryGib) || claim.spec.memoryGib < 1 || claim.spec.memoryGib > 8192 || !Number.isInteger(claim.spec.diskGib) || claim.spec.diskGib < 8 || claim.spec.diskGib > 65536 || !Number.isInteger(claim.spec.egressGuaranteedMbps) || claim.spec.egressGuaranteedMbps < 0 || !Number.isInteger(claim.spec.egressBurstMbps) || claim.spec.egressBurstMbps < claim.spec.egressGuaranteedMbps)
     throw new MetalProvisionError("invalid compute claim");
   const image = profile.images[claim.spec.imageKey];
   if (!image || !isAbsolute(image.path) || !SHA256.test(image.sha256)) {
@@ -880,12 +951,22 @@ async function provisionMetalGuest(profile, claim, exec) {
   for (const path of [profile.stateDir, profile.seedDir, profile.unitDir])
     mkdirSync(path, { recursive: true, mode: 448 });
   const manifests = readManifests(profile.stateDir);
-  const name = guestNameFor(claim.computeKey);
+  if (claim.access) {
+    if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(claim.access.sshUser)) {
+      throw new MetalProvisionError("invalid SSH user");
+    }
+    if (claim.access.sshPublicKeys.length < 1 || claim.access.sshPublicKeys.length > 16 || claim.access.sshPublicKeys.some((key) => typeof key !== "string" || key.length > 16384 || !/^ssh-(?:ed25519|rsa)\s+[A-Za-z0-9+/]+={0,3}(?:\s+.*)?$/.test(key.trim())))
+      throw new MetalProvisionError("invalid SSH public key list");
+  }
+  const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
+  const conflictingName = manifests.find((row) => row.name === name && row.computeKey !== claim.computeKey);
+  if (conflictingName)
+    throw new MetalProvisionError("requested guest name is already allocated");
   const manifestPath = join(profile.stateDir, `${name}.json`);
   const prior = manifests.find((row) => row.computeKey === claim.computeKey);
   if (prior && prior.reference !== claim.spec.reference)
     throw new MetalProvisionError("compute identity conflicts with host inventory");
-  const address = allocateAddress(profile, claim.computeKey, manifests);
+  const address = requestedAddress(profile, claim, manifests);
   const cpuPool = allocateCpuPool(profile, claim, manifests);
   const manifest = prior ?? {
     computeKey: claim.computeKey,
@@ -964,18 +1045,22 @@ async function removeMetalGuest(profile, claim, exec) {
   validateMetalProfile(profile);
   if (claim.action !== "delete")
     throw new MetalProvisionError("create claim cannot remove a guest");
-  const name = guestNameFor(claim.computeKey);
+  const name = claim.spec.guestName ?? guestNameFor(claim.computeKey);
   const manifestPath = join(profile.stateDir, `${name}.json`);
   if (!existsSync(manifestPath))
     return {};
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-  if (manifest.computeKey !== claim.computeKey || manifest.reference !== claim.spec.reference || manifest.name !== name) {
+  const currentIdentity = manifest.computeKey === claim.computeKey && manifest.reference === claim.spec.reference && manifest.name === name;
+  const legacyPlatformIdentity = claim.bootstrap?.kind === "platform-genesis" && claim.computeKey === `platform:${name}` && claim.spec.reference === `platform:${name}` && manifest.name === name && manifest.disk === `/dev/${profile.volumeGroup}/${name}` && manifest.address === claim.spec.guestAddress && (manifest.unit === `fz-guest@${name}.service` || manifest.unit === `forgezero-guest@${name}.service`);
+  if (!currentIdentity && !legacyPlatformIdentity) {
     throw new MetalProvisionError("compute identity conflicts with host inventory");
   }
   const service = `forgezero-guest@${name}.service`;
   const unitPath = join(profile.unitDir, service);
   if (existsSync(unitPath))
     await checked(exec, ["systemctl", "disable", "--now", service]);
+  else if (legacyPlatformIdentity)
+    await checked(exec, ["systemctl", "disable", "--now", service]);
   else if ((await exec(["systemctl", "is-active", service])).exitCode === 0) {
     throw new MetalProvisionError("guest unit is active but its owned unit file is missing");
   }
@@ -992,6 +1077,14 @@ async function removeMetalGuest(profile, claim, exec) {
   ])
     if (existsSync(path))
       unlinkSync(path);
+  if (legacyPlatformIdentity) {
+    const legacyConfig = `/etc/forgezero/guests/${name}.conf`;
+    const legacyDropIn = join(profile.unitDir, `${service}.d`);
+    if (existsSync(legacyConfig))
+      unlinkSync(legacyConfig);
+    if (existsSync(legacyDropIn))
+      rmSync(legacyDropIn, { recursive: true });
+  }
   await checked(exec, ["systemctl", "daemon-reload"]);
   return {};
 }

package/dist/node-vault.d.ts

@@ -5,9 +5,18 @@ export interface NodeVaultOptions extends Omit<SignedNodeHttpOptions, 'apiUrl'>
     /** Tenant node base, for example https://api.example/api/t/acme. */
     apiUrl: string;
     keys: NodeKeyPair;
+    /** The sole tenant project this enrolled compute may replicate. */
+    projectKey: string;
     ttlMs?: number;
     maxStaleMs?: number;
 }
+export interface ProjectVaultCoordinate {
+    environment: string;
+    name: string;
+}
+/** Internal cache key. JSON avoids separator ambiguity in user-selected names. */
+export declare function projectVaultCacheKey(coordinate: ProjectVaultCoordinate): string;
+export declare function projectVaultCoordinate(key: string): ProjectVaultCoordinate;
 /** Turn the public API origin into the realm-selected node endpoint. */
 export declare function tenantNodeApiUrl(apiUrl: string, tenantSlug: string): string;
 /** Project/environment selection is server-owned through the compute binding. */

package/dist/node-vault.js

@@ -92,7 +92,13 @@ function createSecretCache(options) {
 }
 
 // src/signed-node-http.ts
-import { signRequest } from "@forgezero/runtime/identity";
+import {
+  encodeSignatureHeader,
+  generateResponseRecipient,
+  openResponse,
+  RESPONSE_KEY_HEADER,
+  signRequest
+} from "@forgezero/runtime/identity";
 
 class SignedNodeHttpError extends Error {
   status;
@@ -102,30 +108,28 @@ class SignedNodeHttpError extends Error {
     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) {
+async function postSignedNode(options, path, body, sealedResponse = false) {
   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 recipient = sealedResponse ? generateResponseRecipient() : undefined;
   const envelope = signRequest(options.keys, options.nodeKey, {
     method: "POST",
     path: url.pathname,
     query: "",
-    body: raw
+    body: raw,
+    responseKey: recipient?.publicKey
   });
+  const signature = encodeSignatureHeader(envelope);
   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)
+      "x-fz-signature": signature,
+      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
     },
     body: raw,
     signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
@@ -136,10 +140,35 @@ async function postSignedNode(options, path, body) {
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
     throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
   }
+  if (recipient) {
+    try {
+      return await openResponse(recipient.secretKey, signature, payload);
+    } catch {
+      throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
+    }
+  }
   return payload;
 }
 
 // src/node-vault.ts
+var SCOPE_PART = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+function projectVaultCacheKey(coordinate) {
+  if (!SCOPE_PART.test(coordinate.environment) || !SCOPE_PART.test(coordinate.name)) {
+    throw new Error("node vault coordinate is malformed");
+  }
+  return JSON.stringify([coordinate.environment, coordinate.name]);
+}
+function projectVaultCoordinate(key) {
+  let value;
+  try {
+    value = JSON.parse(key);
+  } catch {
+    throw new Error("node vault cache key is malformed");
+  }
+  if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "string" || typeof value[1] !== "string" || !SCOPE_PART.test(value[0]) || !SCOPE_PART.test(value[1]))
+    throw new Error("node vault cache key is malformed");
+  return { environment: value[0], name: value[1] };
+}
 function tenantNodeApiUrl(apiUrl, tenantSlug) {
   if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
     throw new Error("tenant slug is malformed");
@@ -150,19 +179,20 @@ function tenantNodeApiUrl(apiUrl, tenantSlug) {
   return url.toString().replace(/\/$/, "");
 }
 function createNodeVaultCache(options) {
-  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
+  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body, true);
   return createSecretCache({
     ttlMs: options.ttlMs,
     maxStaleMs: options.maxStaleMs,
     list: async () => {
       const payload = await post("list", {});
-      if (!Array.isArray(payload.names) || payload.names.some((name) => typeof name !== "string")) {
+      if (!Array.isArray(payload.entries) || payload.entries.some((entry) => !entry || typeof entry.environment !== "string" || typeof entry.name !== "string")) {
         throw new Error("node vault list response is malformed");
       }
-      return payload.names;
+      return payload.entries.map(projectVaultCacheKey);
     },
-    fetch: async (name) => {
-      const payload = await post("read", { name });
+    fetch: async (key) => {
+      const coordinate = projectVaultCoordinate(key);
+      const payload = await post("read", coordinate);
       if (typeof payload.value !== "string" || !Number.isSafeInteger(payload.version)) {
         throw new Error("node vault read response is malformed");
       }
@@ -170,9 +200,13 @@ function createNodeVaultCache(options) {
     },
     changes: async (since) => {
       const payload = await post("changes", { since });
-      if (!Number.isSafeInteger(payload.version) || !Array.isArray(payload.changed) || payload.changed.some((name) => typeof name !== "string"))
+      if (!Number.isSafeInteger(payload.version) || !Array.isArray(payload.changed) || payload.changed.some((entry) => !entry || typeof entry.environment !== "string" || typeof entry.name !== "string"))
         throw new Error("node vault changes response is malformed");
-      return { version: payload.version, changed: payload.changed, resync: payload.resync };
+      return {
+        version: payload.version,
+        changed: payload.changed.map(projectVaultCacheKey),
+        resync: payload.resync
+      };
     }
   });
 }
@@ -207,5 +241,7 @@ function startNodeVaultSync(cache, options = {}) {
 export {
   tenantNodeApiUrl,
   startNodeVaultSync,
+  projectVaultCoordinate,
+  projectVaultCacheKey,
   createNodeVaultCache
 };

package/dist/provision.d.ts

@@ -108,6 +108,7 @@ export interface UnitOptions {
 }
 export declare const DEPLOYMENT_RUNNER_USER = "forgezero-runner";
 export declare const DEPLOYMENT_GROUP = "forgezero-deploy";
+export declare const VAULT_GROUP = "forgezero-vault";
 export declare const DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
 export declare const DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.socket";
 export declare const DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";

package/dist/provision.js

@@ -41,6 +41,7 @@ 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 VAULT_GROUP = "forgezero-vault";
 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";
@@ -210,7 +211,7 @@ function agentUnit(options) {
 `);
   const snpDevice = options.mode === "attested" ? `DevicePolicy=closed
 DeviceAllow=/dev/sev-guest rw` : "";
-  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${user} /dev/sev-guest
+  const snpPrepare = options.mode === "attested" ? `ExecStartPre=+/bin/chgrp ${VAULT_GROUP} /dev/sev-guest
 ExecStartPre=+/bin/chmod 0640 /dev/sev-guest
 ` : "";
   return `[Unit]
@@ -221,7 +222,7 @@ ${deploymentDependency}
 [Service]
 Type=simple
 User=${user}
-Group=${user}
+Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
@@ -240,8 +241,8 @@ LimitCORE=0
 # scope. So it lives in a directory systemd creates with a known owner rather
 # than wherever the process happened to have write access.
 RuntimeDirectory=forgezero
-RuntimeDirectoryMode=0710
-UMask=0077
+RuntimeDirectoryMode=0750
+UMask=0007
 
 # Tenant-controlled commands execute in forgezero-deploy-runner.service. This
 # credential-bearing process never needs to cross a privilege boundary.
@@ -308,6 +309,10 @@ function planProvision(options) {
     socketPath: options.socketPath,
     user,
     steps: [
+      {
+        label: "vault socket access group",
+        command: `groupadd --system ${VAULT_GROUP} || true`
+      },
       ...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}`
@@ -320,6 +325,10 @@ function planProvision(options) {
         label: "service account",
         command: `useradd --system --no-create-home --shell /usr/sbin/nologin ${user} || true`
       },
+      {
+        label: "bind service account to vault group",
+        command: `usermod -g ${VAULT_GROUP} ${user}`
+      },
       ...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}`
@@ -391,6 +400,7 @@ export {
   atLeast,
   agentUnit,
   agentEnrolmentUnit,
+  VAULT_GROUP,
   UNIT_PATH,
   ENROLMENT_UNIT_PATH,
   DEPLOYMENT_RUNNER_USER,

package/dist/provisioning-pull.d.ts

@@ -8,6 +8,10 @@ interface RemoteProvisionClaimBase {
     spec: {
         reference: string;
         imageKey: string;
+        /** Stable bootstrap placement. Online tenant placement normally omits these. */
+        guestName?: string;
+        guestAddress?: string;
+        cpuPoolKey?: string;
         physicalCores: number;
         vcpu: number;
         memoryGib: number;
@@ -17,17 +21,34 @@ interface RemoteProvisionClaimBase {
         confidential: boolean;
     };
 }
+export interface GuestAccess {
+    sshUser: string;
+    /** Public keys only. Private SSH material is never part of a claim. */
+    sshPublicKeys: string[];
+}
 export type CreateRemoteProvisionClaim = RemoteProvisionClaimBase & {
     action?: 'create';
+    access?: GuestAccess;
+} & ({
     enrolment: {
         token: string;
         tenantKey: string;
         projectKey: string;
         environmentKey: string;
     };
-};
+    bootstrap?: never;
+} | {
+    bootstrap: {
+        kind: 'platform-genesis';
+    };
+    enrolment?: never;
+});
 export type RemoteProvisionClaim = CreateRemoteProvisionClaim | (RemoteProvisionClaimBase & {
     action: 'delete';
+    /** Present only for the operator-laptop authority before platform genesis. */
+    bootstrap?: {
+        kind: 'platform-genesis';
+    };
 });
 export interface ProvisionResult {
     guestAddress?: string;
@@ -36,6 +57,8 @@ export type ProvisionRunner = (claim: RemoteProvisionClaim) => Promise<Provision
 export interface ProvisioningPullOptions extends SignedNodeHttpOptions {
     keys: NodeKeyPair;
     run: ProvisionRunner;
+    /** Inventory record this physical host was deliberately configured to serve. */
+    metalHostname?: string;
     intervalMs?: number;
     completionAttempts?: number;
     sleep?: (ms: number) => Promise<void>;