@forgezero/agent 0.1.10 → 0.1.12

package/dist/fz.js

@@ -101,7 +101,7 @@ async function spawnWith(command, env, report = () => {}) {
 }
 
 // src/cli/index.ts
-import { readFileSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { DEFAULT_SOCKET } from "@forgezero/vault";
 
@@ -148,6 +148,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 \u2014 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";
@@ -317,7 +318,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]
@@ -328,7 +329,7 @@ ${deploymentDependency}
 [Service]
 Type=simple
 User=${user}
-Group=${user}
+Group=${VAULT_GROUP}
 ${deploymentGroup}
 LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
 ${gitCredential}${projectCredentials}${projectCredentials ? `
@@ -347,8 +348,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.
@@ -415,6 +416,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}`
@@ -427,6 +432,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}`
@@ -771,10 +780,12 @@ async function resolveIdentity(selector, socketPath) {
   return chosen;
 }
 
+// src/version.ts
+var VERSION = "0.1.12";
+
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;
 var RECOMMENDED_MODE = (THRESHOLD_MODES.find((mode) => mode.recommended) ?? THRESHOLD_MODES[0]).id;
-var VERSION = "0.1.10";
 var PACKAGED_AGENT_BIN = fileURLToPath(new URL("./fz-agent.js", import.meta.url));
 function parseOptions(argv) {
   const options = {
@@ -1033,13 +1044,24 @@ async function cmdAgent(options, args) {
       out.ok(`Wrote ${auxiliary.path}`);
     }
     if (options.enrol) {
-      const prompt = Bun.spawn(["systemd-ask-password", "--timeout=0", "--echo=no", "ForgeZero one-time enrolment token:"], { stdin: "inherit", stdout: "pipe", stderr: "inherit" });
-      const token = (await new Response(prompt.stdout).text()).trim();
-      if (await prompt.exited !== 0 || !/^fze_[A-Za-z0-9_-]{40,100}$/.test(token)) {
-        throw new Error("A valid fze_ enrolment token was not provided.");
-      }
-      writeFileSync(enrolTokenSourcePath, `${token}
+      if (existsSync(enrolTokenSourcePath)) {
+        const source = statSync(enrolTokenSourcePath);
+        const token = readFileSync(enrolTokenSourcePath, "utf8").trim();
+        if (!source.isFile() || (source.mode & 511) !== 384 || source.uid !== 0) {
+          throw new Error("The preloaded enrolment token must be a root-owned 0600 file in /run.");
+        }
+        if (!/^fze_[A-Za-z0-9_-]{40,100}$/.test(token)) {
+          throw new Error("The preloaded enrolment token is malformed.");
+        }
+      } else {
+        const prompt = Bun.spawn(["systemd-ask-password", "--timeout=0", "--echo=no", "ForgeZero one-time enrolment token:"], { stdin: "inherit", stdout: "pipe", stderr: "inherit" });
+        const token = (await new Response(prompt.stdout).text()).trim();
+        if (await prompt.exited !== 0 || !/^fze_[A-Za-z0-9_-]{40,100}$/.test(token)) {
+          throw new Error("A valid fze_ enrolment token was not provided.");
+        }
+        writeFileSync(enrolTokenSourcePath, `${token}
 `, { mode: 384, flag: "wx" });
+      }
     }
     const transcript = await applyPlan(plan, localRunner);
     for (const step of transcript)

package/dist/guest-enrolment.d.ts

@@ -4,7 +4,8 @@ export interface GuestBinding {
     computeReference: string;
     projectKey: string;
     environmentKey: string;
-    tenantSlug: string;
+    realm: 'platform' | 'tenant';
+    tenantSlug?: string;
 }
 export interface GuestEnrolmentOptions {
     apiUrl: string;

package/dist/guest-enrolment.js

@@ -10,11 +10,72 @@ import {
   writeFileSync
 } from "node:fs";
 import { dirname } from "node:path";
+
+// src/signed-node-http.ts
+import {
+  encodeSignatureHeader,
+  generateResponseRecipient,
+  openResponse,
+  RESPONSE_KEY_HEADER,
+  signRequest
+} from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+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,
+    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": signature,
+      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
+    },
+    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}`);
+  }
+  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/guest-enrolment.ts
 var validBinding = (value, expectedNodeKey) => {
   if (!value || typeof value !== "object")
     return false;
   const row = value;
-  return ["nodeKey", "computeReference", "projectKey", "environmentKey", "tenantSlug"].every((key) => typeof row[key] === "string" && row[key].length > 0) && (!expectedNodeKey || row.nodeKey === expectedNodeKey);
+  return ["nodeKey", "computeReference", "projectKey", "environmentKey"].every((key) => typeof row[key] === "string" && row[key].length > 0) && (row.realm === "platform" || row.realm === "tenant" && typeof row.tenantSlug === "string" && row.tenantSlug.length > 0) && (!expectedNodeKey || row.nodeKey === expectedNodeKey);
 };
 function loadGuestBinding(path, expectedNodeKey) {
   if (!existsSync(path))
@@ -46,34 +107,31 @@ async function enrolGuestIdentity(options) {
   const token = options.token?.trim() ?? (options.tokenPath ? readFileSync(options.tokenPath, "utf8").trim() : "");
   if (!token.startsWith("fze_"))
     throw new Error("guest enrolment credential is malformed");
-  const url = new URL(options.apiUrl);
-  url.pathname = `${url.pathname.replace(/\/$/, "")}/v1/compute/enrol`.replace(/\/+/g, "/");
-  url.search = "";
-  url.hash = "";
-  const response = await (options.fetch ?? globalThis.fetch)(url, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      token,
-      label: options.label,
-      gitDeployPublicKey: options.gitDeployPublicKey,
-      publicKeys: {
-        ed25519: options.keys.ed25519.publicKey,
-        mlDsa: options.keys.mlDsa.publicKey
-      }
-    }),
-    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
-  });
-  const payload = await response.json().catch(() => null);
-  if (!response.ok || !payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || !payload.tenantSlug) {
-    throw new Error(payload?.error?.message || `guest enrolment returned HTTP ${response.status}`);
+  const payload = await postSignedNode({
+    apiUrl: options.apiUrl,
+    nodeKey: options.nodeKey,
+    keys: options.keys,
+    fetch: options.fetch,
+    requestTimeoutMs: options.requestTimeoutMs
+  }, "v1/compute/enrol", {
+    token,
+    label: options.label,
+    gitDeployPublicKey: options.gitDeployPublicKey,
+    publicKeys: {
+      ed25519: options.keys.ed25519.publicKey,
+      mlDsa: options.keys.mlDsa.publicKey
+    }
+  }, true);
+  if (!payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || payload.realm !== "platform" && (payload.realm !== "tenant" || !payload.tenantSlug)) {
+    throw new Error(payload?.error?.message || "guest enrolment response was not accepted");
   }
   const binding = {
     nodeKey: payload.nodeKey,
     computeReference: payload.computeReference,
     projectKey: payload.projectKey,
     environmentKey: payload.environmentKey,
-    tenantSlug: payload.tenantSlug
+    realm: payload.realm,
+    ...payload.tenantSlug ? { tenantSlug: payload.tenantSlug } : {}
   };
   persistGuestBinding(options.statePath, binding);
   if (options.consume)

package/dist/index.d.ts

@@ -2,30 +2,7 @@
 import { type NodeKeyPair } from '@forgezero/runtime/identity';
 import { startAgent, type AgentOptions, type AttestationSource } from './socket';
 import type { SecretCache } from './cache';
-/**
- * fz-agent — runs inside managed compute, driven locally before the platform exists and
- * over HTTPS after it does. One implementation, two front doors: bootstrap is
- * not a special case, it is the general case run first, because a tenant's own
- * bare metal has no ForgeZero on it either.
- *
- * Everything it does is recorded in a hash-chained journal from its first
- * command — before there is a database to log into. A flat log written then is
- * a log anyone could have edited afterwards; the chain either verifies or
- * visibly does not, and it is replayed into `audit_log` once the platform is
- * operational.
- *
- * ## What it serves
- *
- * A unix socket that SIGNS and never surrenders the key. `@forgezero/vault`
- * discovers `/run/forgezero/vault.sock` and prefers it over `FORGEZERO_API_KEY`, so
- * moving an application onto managed compute means deleting an environment
- * variable rather than changing a line of code — and a machine that used to hold
- * a signing seed now holds nothing an attacker can take.
- *
- * That preference was implemented in the client long before anything listened.
- * See `socket.ts` for why it signs rather than handing back a token.
- */
-export declare const VERSION = "0.1.10";
+export { VERSION } from './version';
 export { startAgent, handleRequest } from './socket';
 export type { AgentOptions, AttestationSource, Request, Response } from './socket';
 export { createSecretCache, CacheError } from './cache';
@@ -35,13 +12,11 @@ export type { DeploymentManager, DeploymentOptions, DeploymentRequest, Deploymen
 export { DEFAULT_CONTROL_SOCKET, requestControl, startControlServer } from './control';
 export { pullDeploymentOnce, startDeploymentPull } from './deployment-pull';
 export type { DeploymentPullOptions, RemoteDeploymentClaim, PullResult } from './deployment-pull';
-export { readStaticDeploymentState, writeStaticDeploymentState, startStaticDeploymentWatch } from './deployment-watch';
-export type { StaticDeploymentState, StaticDeploymentWatchOptions } from './deployment-watch';
 export { pullProvisioningOnce, startProvisioningPull } from './provisioning-pull';
-export type { CreateRemoteProvisionClaim, ProvisioningPullOptions, RemoteProvisionClaim, ProvisionPullResult, ProvisionRunner, ProvisionResult } from './provisioning-pull';
+export type { CreateRemoteProvisionClaim, ProvisioningPullOptions, RemoteProvisionClaim, GuestAccess, ProvisionPullResult, ProvisionRunner, ProvisionResult } from './provisioning-pull';
 export { enrolGuestIdentity, loadGuestBinding } from './guest-enrolment';
 export type { GuestBinding, GuestEnrolmentOptions } from './guest-enrolment';
-export { createNodeVaultCache, startNodeVaultSync, tenantNodeApiUrl } from './node-vault';
+export { createNodeVaultCache, projectVaultCacheKey, projectVaultCoordinate, startNodeVaultSync, tenantNodeApiUrl } from './node-vault';
 export type { NodeVaultOptions, NodeVaultSyncOptions } from './node-vault';
 export { allocateAddress, allocateCpuPool, cloudInit, guestNameFor, provisionMetalGuest, removeMetalGuest } from './metal-provision';
 export { validateMetalProfile } from './metal-provision';
@@ -53,6 +28,7 @@ export type { SnpAttestationOptions } from './snp-attestation';
 export { attestNodeOnce, startNodeAttestation } from './attestation-client';
 export type { NodeAttestationOptions } from './attestation-client';
 export { applyMetalIsolation, metalGuestSliceUnit, metalHousekeepingDropIn } from './metal-isolation';
+export { assertSupportedGuestImage, SUPPORTED_GUEST_IMAGE } from './ubuntu';
 /**
  * The node seed, on disk, owner-only.
  *
@@ -128,5 +104,5 @@ export declare function runAgent(config?: AgentConfig): {
     server: ReturnType<typeof startAgent>;
     keys: NodeKeyPair;
     nodeKey: string;
-    setCache(cache: SecretCache): void;
+    setVault(cache: SecretCache, projectKey: string): void;
 };

package/dist/metal-helper-socket.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 {};
 }