@forgezero/agent 0.1.11 → 0.1.13

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.13";
+
 // 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.11";
+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;
 };