@forgezero/agent 0.1.2 → 0.1.10

package/dist/fz.js

@@ -0,0 +1,1270 @@
+#!/usr/bin/env bun
+// @bun
+var __require = import.meta.require;
+
+// src/cli/index.ts
+import { THRESHOLD_MODES, thresholdMode } from "@forgezero/access/ceremony-modes";
+import { signWithIdentity } from "@forgezero/runtime/ssh-agent";
+
+// src/cli/run.ts
+class RunError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "RunError";
+  }
+}
+function splitAtSeparator(argv) {
+  const at = argv.indexOf("--");
+  if (at === -1) {
+    throw new RunError("NO_SEPARATOR", "Put `--` before the command: fz run -- npm start. Without it the flags after it would be read as fz\u2019s own.");
+  }
+  const command = argv.slice(at + 1);
+  if (command.length === 0) {
+    throw new RunError("NO_COMMAND", "Nothing to run after `--`.");
+  }
+  return { own: argv.slice(0, at), command };
+}
+var NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function mergeEnvironment(base, secrets, options = {}) {
+  const env = {};
+  for (const [name, value] of Object.entries(base)) {
+    if (value !== undefined)
+      env[name] = value;
+  }
+  const collisions = [];
+  const refused = [];
+  for (const [name, value] of Object.entries(secrets)) {
+    if (!NAME.test(name)) {
+      refused.push(name);
+      continue;
+    }
+    if (name in env) {
+      collisions.push(name);
+      if (options.preserveEnv)
+        continue;
+    }
+    env[name] = value;
+  }
+  return { env, collisions: collisions.sort(), refused: refused.sort() };
+}
+function describeInjection(result, count) {
+  const lines = [`${count} secret${count === 1 ? "" : "s"} injected`];
+  if (result.collisions.length > 0) {
+    lines.push(`  overriding: ${result.collisions.join(", ")} (use --preserve-env to keep the existing values)`);
+  }
+  if (result.refused.length > 0) {
+    lines.push(`  skipped: ${result.refused.join(", ")} \u2014 not usable as environment variable names`);
+  }
+  return lines.join(`
+`);
+}
+function exitCodeFor(status) {
+  if (status.signal) {
+    const numbers = {
+      SIGHUP: 1,
+      SIGINT: 2,
+      SIGQUIT: 3,
+      SIGKILL: 9,
+      SIGTERM: 15
+    };
+    return 128 + (numbers[status.signal] ?? 0);
+  }
+  return status.code ?? 0;
+}
+async function spawnWith(command, env, report = () => {}) {
+  const { spawn } = await import("child_process");
+  const child = spawn(command[0], command.slice(1), {
+    env,
+    stdio: "inherit"
+  });
+  const forward = (signal) => () => {
+    child.kill(signal);
+  };
+  const onInt = forward("SIGINT");
+  const onTerm = forward("SIGTERM");
+  process.on("SIGINT", onInt);
+  process.on("SIGTERM", onTerm);
+  try {
+    return await new Promise((resolve) => {
+      child.on("error", (error) => {
+        report(`Could not start ${command[0]}: ${error.message}`);
+        resolve(127);
+      });
+      child.on("exit", (code, signal) => resolve(exitCodeFor({ code, signal })));
+    });
+  } finally {
+    process.off("SIGINT", onInt);
+    process.off("SIGTERM", onTerm);
+  }
+}
+
+// src/cli/index.ts
+import { readFileSync, unlinkSync, writeFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { DEFAULT_SOCKET } from "@forgezero/vault";
+
+// src/provision.ts
+function atLeast(version, floor) {
+  const parse = (value) => (value.trim().replace(/^v/, "").match(/\d+/g) ?? []).slice(0, 3).map(Number);
+  const got = parse(version);
+  const want = parse(floor);
+  if (got.length === 0)
+    return false;
+  for (let index = 0;index < want.length; index += 1) {
+    const a = got[index] ?? 0;
+    const b = want[index] ?? 0;
+    if (a > b)
+      return true;
+    if (a < b)
+      return false;
+  }
+  return true;
+}
+var CAPABILITY_CHECKS = {
+  snpGuest: {
+    command: "test -e /dev/sev-guest && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "Not a confidential guest. The agent will run in `enrolled` mode, which is still stronger than an API key in the application."
+  },
+  systemd: {
+    command: "test -d /run/systemd/system && echo yes || echo no",
+    satisfied: (stdout) => stdout.trim() === "yes",
+    remedy: "systemd is what supervises the agent. On a non-systemd host, run `fz-agent` under whatever supervises services there."
+  },
+  bun: {
+    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 \u2014 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_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.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://www.forgezero.net/docs/agent
+${deploymentDependency}
+
+[Service]
+Type=simple
+User=${user}
+Group=${user}
+${deploymentGroup}
+LoadCredentialEncrypted=agent-seed:${seedCredentialPath}
+${gitCredential}${projectCredentials}${projectCredentials ? `
+` : ""}${snpPrepare}ExecStart=${bin}
+Restart=always
+RestartSec=2
+
+${environment.map((line) => `Environment=${line}`).join(`
+`)}
+
+# The node seed and the vault replica live in this process's memory. A core dump
+# writes both to disk, which is the one artefact this design exists to remove.
+LimitCORE=0
+
+# The socket is the entire interface: anything that can read it can read the
+# 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
+
+# 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
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictRealtime=true
+MemoryDenyWriteExecute=true
+LockPersonality=true
+${snpDevice}
+${deploymentWrites}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+var UNIT_PATH = "/etc/systemd/system/forgezero-agent.service";
+function planProvision(options) {
+  const mode = options.mode;
+  const user = options.user ?? "forgezero";
+  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: "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 ${[
+          ...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 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"}`
+      }] : []
+    ]
+  };
+}
+
+// src/cli/agent-install.ts
+function parseAssignments(value) {
+  if (!value?.trim())
+    return;
+  const parsed = {};
+  for (const entry of value.split(",")) {
+    const separator = entry.indexOf("=");
+    if (separator < 1)
+      throw new Error(`invalid deployment assignment: ${entry}`);
+    const name = entry.slice(0, separator);
+    const item = entry.slice(separator + 1);
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(name) || !item || /[\r\n]/.test(item)) {
+      throw new Error(`invalid deployment assignment: ${name}`);
+    }
+    if (Object.hasOwn(parsed, name))
+      throw new Error(`duplicate deployment assignment: ${name}`);
+    parsed[name] = item;
+  }
+  return parsed;
+}
+async function readCapabilities(run) {
+  const answers = {};
+  const checks = Object.entries(CAPABILITY_CHECKS);
+  for (const [id, check] of checks) {
+    try {
+      const result = await run(check.command);
+      answers[id] = check.satisfied(result.stdout, result.exitCode);
+    } catch {
+      answers[id] = false;
+    }
+  }
+  return answers;
+}
+async function localRunner(command) {
+  const proc = Bun.spawn(["sh", "-c", command], { stdout: "pipe", stderr: "pipe" });
+  const stdout = await new Response(proc.stdout).text();
+  return { stdout, exitCode: await proc.exited };
+}
+function planInstall(options) {
+  const { capabilities, ...unit } = options;
+  return planProvision({ ...unit, mode: modeFor(capabilities) });
+}
+async function applyPlan(plan, run) {
+  const transcript = [];
+  for (const step of plan.steps) {
+    const result = await run(step.command);
+    transcript.push({ label: step.label, command: step.command, exitCode: result.exitCode });
+    if (result.exitCode !== 0 && !step.optional) {
+      throw new Error(`${step.label} failed (exit ${result.exitCode}): ${step.command}`);
+    }
+  }
+  return transcript;
+}
+function renderPlan(plan) {
+  return [
+    "",
+    `  Mode      ${plan.mode.toUpperCase()}`,
+    `  Reason    ${plan.reason}`,
+    "",
+    `  User      ${plan.user}`,
+    `  Socket    ${plan.socketPath}`,
+    `  Unit      ${plan.unitPath}`,
+    ...plan.auxiliaryUnits.map((unit) => `  Aux unit  ${unit.path}`),
+    "",
+    "  Applications on this machine will then read secrets through the socket.",
+    "  @forgezero/vault prefers it over FORGEZERO_API_KEY automatically, so no",
+    "  application code changes.",
+    "",
+    "  Run with --apply to write the unit and start the service.",
+    ""
+  ].join(`
+`);
+}
+
+// src/cli/custody.ts
+import {
+  listCustodyIdentities,
+  deriveCustodyKey,
+  assertDeterministic,
+  SshAgentError
+} from "@forgezero/runtime/ssh-agent";
+var PROBE_TIMEOUT_MS = 2000;
+function withTimeout(work, ms, label) {
+  return Promise.race([
+    work,
+    new Promise((_, reject) => setTimeout(() => reject(new SshAgentError(`SSH_AGENT_TIMEOUT:${label}`)), ms))
+  ]);
+}
+async function usableIdentities(socketPath) {
+  const candidates = await listCustodyIdentities(socketPath);
+  const usable = [];
+  for (const identity of candidates) {
+    const started = Date.now();
+    try {
+      await withTimeout(deriveCustodyKey(identity, socketPath), PROBE_TIMEOUT_MS, identity.fingerprint);
+      usable.push({ ...identity, responseMs: Date.now() - started });
+    } catch {}
+  }
+  return usable;
+}
+async function custodyKeyFor(identity, socketPath) {
+  return withTimeout(assertDeterministic(identity, socketPath), PROBE_TIMEOUT_MS * 2, identity.fingerprint);
+}
+function selectIdentity(identities, selector) {
+  const index = Number.parseInt(selector, 10);
+  if (Number.isInteger(index) && index >= 1 && index <= identities.length) {
+    return identities[index - 1];
+  }
+  return identities.find((id) => id.fingerprint === selector) ?? identities.find((id) => id.fingerprint.startsWith(selector)) ?? identities.find((id) => id.comment === selector) ?? null;
+}
+
+// src/cli/genesis.ts
+import { generatePhrase } from "@forgezero/runtime/phrase";
+import {
+  wrappingKeysFor,
+  openFactorEnvelope
+} from "@forgezero/runtime/custody-share";
+import { listCustodyIdentities as listCustodyIdentities2 } from "@forgezero/runtime/ssh-agent";
+var b64 = (bytes) => Buffer.from(bytes).toString("base64url");
+function fail(response, step) {
+  const body = response.body;
+  const raw = body?.error;
+  const detail = typeof raw === "string" ? raw : raw?.code ? `${raw.code}${raw.message ? ` \u2014 ${raw.message}` : ""}` : body?.message ?? `HTTP ${response.status}`;
+  throw new Error(`${step}: ${detail}`);
+}
+async function runGenesis(args) {
+  const step = args.onStep ?? (() => {});
+  step("Claiming the platform with the setup token");
+  const claimed = await args.api("/onboarding/platform/claim", {
+    method: "POST",
+    body: { token: args.token, email: args.email, displayName: args.displayName }
+  });
+  if (claimed.status !== 200) {
+    const code = claimed.body?.error;
+    if (code !== "ALREADY_CLAIMED")
+      fail(claimed, "claim");
+    step("Already claimed \u2014 continuing to the ceremony");
+  }
+  step(`Registering ${args.identity.fingerprint} as a custody key`);
+  const registered = await args.api("/security/ssh-identities", {
+    method: "POST",
+    body: {
+      authorizedKey: `${args.identity.type} ${Buffer.from(args.identity.blob).toString("base64")}`
+    }
+  });
+  if (registered.status !== 200)
+    fail(registered, "register-ssh-key");
+  step(`Deriving custody key from ${args.identity.fingerprint}`);
+  const sshKey = await custodyKeyFor(args.identity, args.socketPath);
+  step("Generating recovery phrase");
+  const phrase = generatePhrase();
+  step(`Proposing ${args.modeId} ceremony`);
+  const proposed = await args.api("/custody/ceremony/propose", {
+    method: "POST",
+    body: {
+      modeId: args.modeId,
+      custodians: [{ userKey: args.userKey, email: args.email }]
+    }
+  });
+  if (proposed.status !== 200)
+    fail(proposed, "propose");
+  const ceremonyKey = proposed.body?.ceremony?._key;
+  if (!ceremonyKey)
+    throw new Error("propose: no ceremony key returned");
+  step("Enrolling \u2014 the share is sealed to this machine, never sent in the clear");
+  const keys = wrappingKeysFor({
+    custodianKey: args.userKey,
+    passkeyPrfOutput: sshKey,
+    phraseWords: phrase
+  });
+  const enrolled = await args.api("/custody/ceremony/share", {
+    method: "POST",
+    body: { ceremonyKey, keys }
+  });
+  if (enrolled.status !== 200)
+    fail(enrolled, "enroll");
+  const sealed = enrolled.body?.ceremony?.custodians?.find((c) => c.userKey === args.userKey)?.sealed;
+  if (!sealed)
+    throw new Error("enroll: the server returned no sealed share");
+  for (const factor of ["passkey", "phrase"]) {
+    step(`Proving the ${factor === "passkey" ? "ssh" : "phrase"} route opens the share`);
+    const { probe } = openFactorEnvelope({
+      sealed,
+      custodianKey: args.userKey,
+      factor,
+      ...factor === "passkey" ? { passkeyPrfOutput: sshKey } : { phraseWords: phrase }
+    });
+    const tested = await args.api("/custody/ceremony/test", {
+      method: "POST",
+      body: { ceremonyKey, factor, openedProbe: b64(probe) }
+    });
+    if (tested.status !== 200)
+      fail(tested, `test:${factor}`);
+  }
+  step("Activating \u2014 the seed is split and the vault opens");
+  const activated = await args.api("/custody/ceremony/activate", {
+    method: "POST",
+    body: { ceremonyKey }
+  });
+  if (activated.status !== 200)
+    fail(activated, "activate");
+  sshKey.fill(0);
+  return {
+    ceremonyKey,
+    phrase,
+    fingerprint: activated.body?.ceremony?.masterSeedFingerprint ?? "",
+    activated: true
+  };
+}
+async function runUnlock(args) {
+  const step = args.onStep ?? (() => {});
+  const contributions = [];
+  const sealed = args.sealed;
+  if (args.identity && sealed) {
+    step(`Deriving custody key from ${args.identity.fingerprint}`);
+    const sshKey = await custodyKeyFor(args.identity, args.socketPath);
+    const { share } = openFactorEnvelope({
+      sealed,
+      custodianKey: args.userKey,
+      factor: "passkey",
+      passkeyPrfOutput: sshKey
+    });
+    contributions.push({
+      userKey: args.userKey,
+      factor: "passkey",
+      share: b64(share)
+    });
+    sshKey.fill(0);
+  }
+  if (args.phrase?.length && sealed) {
+    const { share } = openFactorEnvelope({
+      sealed,
+      custodianKey: args.userKey,
+      factor: "phrase",
+      phraseWords: args.phrase
+    });
+    contributions.push({
+      userKey: args.userKey,
+      factor: "phrase",
+      share: b64(share)
+    });
+  }
+  if (contributions.length === 0) {
+    throw new Error("unlock: supply an ssh key or a recovery phrase");
+  }
+  step(`Reconstructing the seed from ${contributions.length} contribution(s)`);
+  const unlocked = await args.api("/custody/ceremony/unlock", {
+    method: "POST",
+    body: { contributions }
+  });
+  if (unlocked.status !== 200)
+    fail(unlocked, "unlock");
+  return {
+    fingerprint: unlocked.body?.fingerprint ?? ""
+  };
+}
+async function resolveIdentity(selector, socketPath) {
+  if (selector && !/^\d+$/.test(selector)) {
+    const listed = await listCustodyIdentities2(socketPath);
+    const match = listed.find((id) => id.fingerprint === selector) ?? listed.find((id) => id.fingerprint.startsWith(selector)) ?? listed.find((id) => id.comment === selector);
+    if (match) {
+      await custodyKeyFor(match, socketPath);
+      return { ...match, responseMs: 0 };
+    }
+  }
+  const identities = await usableIdentities(socketPath);
+  if (identities.length === 0) {
+    throw new Error("No usable Ed25519 key in the agent. Add one with `ssh-add ~/.ssh/id_ed25519`, " + "then confirm with `fz keys`.");
+  }
+  if (!selector) {
+    if (identities.length > 1) {
+      throw new Error(`${identities.length} usable keys \u2014 choose one with --key <fingerprint|index>. ` + "Run `fz keys` to list them.");
+    }
+    return identities[0];
+  }
+  const chosen = selectIdentity(identities, selector);
+  if (!chosen)
+    throw new Error(`No usable key matches "${selector}". Run \`fz keys\`.`);
+  return chosen;
+}
+
+// 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 = {
+    api: process.env.FZ_API ?? "http://localhost:8787",
+    realm: process.env.FZ_REALM ?? "platform",
+    json: false,
+    apply: false,
+    enrol: false,
+    socket: process.env.SSH_AUTH_SOCK,
+    mode: DEFAULT_MODE,
+    user: process.env.FZ_USER ?? "operator",
+    email: process.env.FZ_EMAIL ?? "operator@localhost",
+    preserveEnv: false
+  };
+  const positional = [];
+  for (let index = 0;index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--api")
+      options.api = argv[++index] ?? options.api;
+    else if (token === "--realm")
+      options.realm = argv[++index] ?? options.realm;
+    else if (token === "--socket")
+      options.socket = argv[++index];
+    else if (token === "--json")
+      options.json = true;
+    else if (token === "--apply")
+      options.apply = true;
+    else if (token === "--enrol")
+      options.enrol = true;
+    else if (token === "--preserve-env")
+      options.preserveEnv = true;
+    else if (token === "--key")
+      options.key = argv[++index];
+    else if (token === "--mode")
+      options.mode = argv[++index] ?? options.mode;
+    else if (token === "--user")
+      options.user = argv[++index] ?? options.user;
+    else if (token === "--email")
+      options.email = argv[++index] ?? options.email;
+    else if (token === "--token")
+      options.token = argv[++index];
+    else if (token === "--phrase")
+      options.phrase = (argv[++index] ?? "").trim().split(/\s+/);
+    else
+      positional.push(token);
+  }
+  return { command: positional[0] ?? "help", args: positional.slice(1), options };
+}
+var out = {
+  line: (text = "") => process.stdout.write(`${text}
+`),
+  step: (text) => process.stdout.write(`  ${text}
+`),
+  warn: (text) => process.stderr.write(`  ! ${text}
+`),
+  fail: (text) => process.stderr.write(`  \u2717 ${text}
+`),
+  ok: (text) => process.stdout.write(`  \u2713 ${text}
+`)
+};
+var sessionCookie = null;
+function requestHeaders(apiBase, cookie) {
+  return {
+    "content-type": "application/json",
+    origin: new URL(apiBase).origin,
+    ...cookie ? { cookie } : {}
+  };
+}
+async function api(options, path, init) {
+  const base = options.realm === "platform" ? "/api" : `/api/t/${options.realm}`;
+  const response = await fetch(`${options.api}${base}${path}`, {
+    method: init?.method ?? "GET",
+    headers: requestHeaders(options.api, sessionCookie),
+    body: init?.body === undefined ? undefined : JSON.stringify(init.body)
+  });
+  const setCookie = response.headers.get("set-cookie");
+  if (setCookie)
+    sessionCookie = setCookie.split(";")[0];
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  const challenge = body?.security;
+  if (response.status === 428 && challenge?.scope === "action" && challenge.requestKey && custodyIdentity && !path.startsWith("/security/step-up/")) {
+    const proved = await proveWithAgent(options, challenge.requestKey);
+    if (proved) {
+      const replay = await fetch(`${options.api}${base}${path}`, {
+        method: init?.method ?? "GET",
+        headers: {
+          ...requestHeaders(options.api, sessionCookie),
+          "x-security-request-key": challenge.requestKey
+        },
+        body: init?.body === undefined ? undefined : JSON.stringify(init.body)
+      });
+      let replayed = null;
+      try {
+        replayed = await replay.json();
+      } catch {
+        replayed = null;
+      }
+      return { status: replay.status, body: replayed };
+    }
+  }
+  return { status: response.status, body };
+}
+var custodyIdentity = null;
+function useCustodyIdentity(identity, socketPath) {
+  custodyIdentity = { identity, socketPath };
+}
+async function proveWithAgent(options, requestKey) {
+  if (!custodyIdentity)
+    return false;
+  const begun = await api(options, "/security/step-up/ssh/begin", {
+    method: "POST",
+    body: { requestKey }
+  });
+  const nonce = begun.body?.nonce;
+  if (begun.status !== 200 || !nonce)
+    return false;
+  const signature = await signWithIdentity(custodyIdentity.identity, new Uint8Array(Buffer.from(nonce, "base64")), custodyIdentity.socketPath);
+  const proved = await api(options, "/security/step-up/ssh/prove", {
+    method: "POST",
+    body: { requestKey, signature: Buffer.from(signature).toString("base64") }
+  });
+  return proved.status === 200;
+}
+async function cmdKeys(options) {
+  const identities = await usableIdentities(options.socket);
+  if (options.json) {
+    out.line(JSON.stringify(identities.map(({ fingerprint, comment, responseMs }) => ({
+      fingerprint,
+      comment,
+      responseMs
+    })), null, 2));
+    return 0;
+  }
+  if (identities.length === 0) {
+    out.fail("No usable Ed25519 keys in the agent.");
+    out.line();
+    out.step("Custody needs a key that signs DETERMINISTICALLY, so Ed25519 only.");
+    out.step("Add one with:  ssh-add ~/.ssh/id_ed25519");
+    out.line();
+    out.step("Note that keys which hang \u2014 forwarded agents whose upstream is");
+    out.step("gone, or confirm-on-use keys with nobody at the terminal \u2014 are");
+    out.step("skipped here rather than listed, so this can be shorter than");
+    out.step("`ssh-add -l`.");
+    return 1;
+  }
+  out.line("Usable custody keys:");
+  out.line();
+  identities.forEach((identity, index) => {
+    out.line(`  ${index + 1}.  ${identity.fingerprint}`);
+    out.line(`      ${identity.comment || "(no comment)"}   ${identity.responseMs}ms`);
+  });
+  out.line();
+  return 0;
+}
+async function cmdStatus(options) {
+  try {
+    const health = await api(options, "/health");
+    const ceremony = await api(options, "/custody/ceremony");
+    if (options.json) {
+      out.line(JSON.stringify({ health: health.body, ceremony: ceremony.body }, null, 2));
+      return 0;
+    }
+    out.line();
+    out.line(`  API      ${options.api}`);
+    out.line(`  Realm    ${options.realm}`);
+    if (health.status !== 200) {
+      out.fail(`API unreachable or unhealthy (HTTP ${health.status}).`);
+      return 1;
+    }
+    out.ok("API reachable");
+    const state = ceremony.body;
+    if (!state?.active) {
+      out.warn("No active ceremony \u2014 the platform has not been launched.");
+      out.step(`Run:  fz genesis --mode ${RECOMMENDED_MODE}`);
+      return 0;
+    }
+    out.line(`  Vault    ${state.vaultUnlocked ? "UNLOCKED" : "LOCKED"}`);
+    if (!state.vaultUnlocked)
+      out.step("Run:  fz unlock");
+    out.line();
+    return 0;
+  } catch (cause) {
+    out.fail(`Cannot reach ${options.api}: ${cause.message}`);
+    return 1;
+  }
+}
+async function cmdAgent(options, args) {
+  if (args[0] !== "install") {
+    out.fail("Usage: fz agent install [--apply] [--enrol]");
+    return 1;
+  }
+  const enrolTokenSourcePath = "/run/forgezero-enrol-token";
+  const enrolTokenCredentialPath = "/etc/forgezero/creds/enrol-token.cred";
+  const enrolStatePath = "/var/lib/forgezero/enrolment.json";
+  const gitCredentialPath = process.env.FZ_GIT_CREDENTIAL_PATH ?? "/etc/forgezero/creds/git-deploy-key.cred";
+  const gitPublicKeyPath = process.env.FZ_GIT_PUBLIC_KEY_PATH ?? "/etc/forgezero/git/deploy.pub";
+  const plan = planInstall({
+    capabilities: await readCapabilities(localRunner),
+    socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET,
+    seedPath: process.env.FZ_SEED_PATH ?? "/var/lib/forgezero/node.seed",
+    seedCredentialPath: process.env.FZ_SEED_CREDENTIAL_PATH,
+    gitCredentialPath,
+    gitPublicKeyPath,
+    generateGitIdentity: true,
+    controlSocketPath: process.env.FZ_CONTROL_SOCKET,
+    repository: process.env.FZ_DEPLOY_REPO,
+    branch: process.env.FZ_DEPLOY_BRANCH,
+    role: process.env.FZ_DEPLOY_ROLE,
+    deployRoot: process.env.FZ_DEPLOY_ROOT,
+    publicApiUrl: process.env.FZ_PUBLIC_API_URL,
+    deploymentEnvironment: parseAssignments(process.env.FZ_DEPLOY_ENV),
+    deploymentCredentials: parseAssignments(process.env.FZ_DEPLOY_CREDENTIALS),
+    pullDeployments: process.env.FZ_DEPLOY_PULL === "true",
+    ...options.enrol ? {
+      pullDeployments: true,
+      enrolTokenSourcePath,
+      enrolTokenCredentialPath,
+      enrolStatePath,
+      nodeLabel: process.env.FZ_NODE_LABEL,
+      deployRoot: process.env.FZ_DEPLOY_ROOT ?? "/opt/forgezero"
+    } : {},
+    binPath: process.env.FZ_AGENT_BIN ?? "/usr/local/lib/forgezero/agent/fz-agent",
+    sourceBinPath: process.env.FZ_AGENT_SOURCE_BIN ?? PACKAGED_AGENT_BIN,
+    user: process.env.FZ_AGENT_USER,
+    apiUrl: options.api,
+    project: process.env.FZ_PROJECT,
+    environment: process.env.FZ_ENVIRONMENT
+  });
+  if (options.json) {
+    out.line(JSON.stringify(plan, null, 2));
+    return 0;
+  }
+  out.line(renderPlan(plan));
+  if (!options.apply) {
+    out.line("  --- unit ---");
+    out.line(plan.unit);
+    for (const auxiliary of plan.auxiliaryUnits) {
+      out.line(`  --- unit ${auxiliary.path} ---`);
+      out.line(auxiliary.unit);
+    }
+    out.line("  --- then ---");
+    for (const step of plan.steps)
+      out.step(`${step.command}`);
+    return 0;
+  }
+  try {
+    writeFileSync(plan.unitPath, plan.unit, { mode: 420 });
+    out.ok(`Wrote ${plan.unitPath}`);
+    for (const auxiliary of plan.auxiliaryUnits) {
+      writeFileSync(auxiliary.path, auxiliary.unit, { mode: 420 });
+      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}
+`, { mode: 384, flag: "wx" });
+    }
+    const transcript = await applyPlan(plan, localRunner);
+    for (const step of transcript)
+      out.ok(step.label);
+    out.ok("Agent service and socket verified");
+    out.line();
+    out.line("  Add this machine-specific PUBLIC key as a read-only deploy key:");
+    out.line();
+    out.line(`  ${readFileSync(gitPublicKeyPath, "utf8").trim()}`);
+    out.line();
+    return 0;
+  } catch (cause) {
+    if (options.enrol) {
+      try {
+        unlinkSync(enrolTokenSourcePath);
+      } catch {}
+    }
+    out.fail(`Could not write ${plan.unitPath}: ${cause.message}`);
+    out.step("Run this as root, or use --json and hand the unit to your provisioner.");
+    return 1;
+  }
+}
+async function cmdGenesis(options) {
+  try {
+    if (!thresholdMode(options.mode)) {
+      throw new Error(`"${options.mode}" is not a threshold mode. ` + `Use one of: ${THRESHOLD_MODES.map((mode) => mode.id).join(", ")}.`);
+    }
+    const identity = await resolveIdentity(options.key, options.socket);
+    let token = options.token;
+    if (!token) {
+      const path = `${process.env.FZ_SHARED_DIR ?? "/etc/forgezero"}/platform-invite.token`;
+      try {
+        token = (await Bun.file(path).text()).trim();
+      } catch {
+        throw new Error(`No --token given and ${path} is unreadable.
+
+` + `  On the server:   the token is read automatically, or set FZ_SHARED_DIR
+` + `  From a laptop:   fz genesis --api https://<your-host> --token plt_...
+
+` + "  The token is what setup.sh printed. It is single use.");
+      }
+    }
+    useCustodyIdentity(identity, options.socket);
+    const result = await runGenesis({
+      token,
+      api: (path, init) => api(options, path, init),
+      modeId: options.mode,
+      userKey: options.user,
+      email: options.email,
+      identity,
+      socketPath: options.socket,
+      onStep: (message) => out.step(message)
+    });
+    if (options.json) {
+      out.line(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    out.line();
+    out.ok("Platform launched. The vault is unlocked.");
+    out.line();
+    out.line("  RECOVERY PHRASE \u2014 written down now, or not at all.");
+    out.line("  It is not stored, not recoverable, and opens your share");
+    out.line("  on its own if the ssh key is ever lost.");
+    out.line();
+    result.phrase.forEach((word, index) => {
+      const column = index % 4;
+      process.stdout.write(`   ${String(index + 1).padStart(2)}. ${word.padEnd(12)}`);
+      if (column === 3)
+        out.line();
+    });
+    out.line();
+    out.line();
+    if (result.fingerprint)
+      out.line(`  Seed fingerprint  ${result.fingerprint}`);
+    out.line();
+    return 0;
+  } catch (cause) {
+    out.fail(cause.message);
+    return 1;
+  }
+}
+async function cmdUnlock(options) {
+  try {
+    const identity = options.phrase?.length ? undefined : await resolveIdentity(options.key, options.socket);
+    const result = await runUnlock({
+      api: (path, init) => api(options, path, init),
+      userKey: options.user,
+      identity,
+      phrase: options.phrase,
+      socketPath: options.socket,
+      onStep: (message) => out.step(message)
+    });
+    if (options.json) {
+      out.line(JSON.stringify(result, null, 2));
+      return 0;
+    }
+    out.ok(`Vault unlocked.  fingerprint ${result.fingerprint}`);
+    return 0;
+  } catch (cause) {
+    out.fail(cause.message);
+    return 1;
+  }
+}
+async function runCommand(argv, options) {
+  let command;
+  try {
+    ({ command } = splitAtSeparator(argv));
+  } catch (error) {
+    out.line(error instanceof RunError ? error.message : String(error));
+    return 2;
+  }
+  const { createVault } = await import("@forgezero/vault");
+  let secrets;
+  try {
+    secrets = await createVault().getAll();
+  } catch (error) {
+    out.line(`Could not read secrets: ${error instanceof Error ? error.message : String(error)}
+Is fz-agent running on this machine? \`fz agent install --apply\`.`);
+    return 1;
+  }
+  const merged = mergeEnvironment(process.env, secrets, { preserveEnv: options.preserveEnv });
+  if (!options.json)
+    out.line(describeInjection(merged, Object.keys(secrets).length));
+  return spawnWith(command, merged.env, (line) => out.line(line));
+}
+function usage() {
+  out.line(`
+  fz ${VERSION} \u2014 ForgeZero control surface
+
+  The platform is launched from here, not from the UI: a session needs a
+  passkey, and a passkey needs a platform to register against. This breaks
+  that circle using an SSH agent and a written recovery phrase.
+
+  COMMANDS
+    fz keys                 List agent keys usable for custody
+    fz status               Platform, ceremony and vault state
+    fz genesis              Run the first custodian ceremony and launch
+    fz unlock               Reconstruct the seed and unlock the vault
+    fz run -- <command>     Start a process with vault values in its
+                            environment. A FALLBACK: anything using
+                            @forgezero/vault reads the socket and sees a
+                            rotation immediately, while an injected environment
+                            is frozen at spawn
+    fz agent install        Install the node agent as a systemd service, so
+                            applications on this box read secrets through a
+                            local socket instead of holding an API key
+
+  CEREMONY OPTIONS
+    --key <fp|index>        Which agent key to use for custody
+    --mode <m-of-n>         Threshold mode        (default ${DEFAULT_MODE})
+                            one of: ${THRESHOLD_MODES.map((m) => m.id).join(", ")}
+    --user <key>            Custodian user key    (env FZ_USER)
+    --email <address>       Custodian email       (env FZ_EMAIL)
+    --phrase "<24 words>"   Unlock by phrase instead of the agent
+    --token <plt_...>       Platform invite from setup.sh; defaults to
+                            $FZ_SHARED_DIR/platform-invite.token
+
+  OPTIONS
+    --api <url>             API base URL          (env FZ_API)
+                            defaults to http://localhost:8787
+                            FROM A LAPTOP pass your public host:
+                              fz genesis --api https://fz.example --token plt_...
+    --realm <id>            Realm to act in       (env FZ_REALM, default platform)
+    --socket <path>         SSH agent socket      (env SSH_AUTH_SOCK)
+    --json                  Machine-readable output
+    --apply                 Write the unit rather than printing it (root)
+    --enrol                Bind this machine with a one-time token prompted
+                           securely by systemd (tenant-owned compute)
+
+  CUSTODY FACTORS
+    Every custodian share is sealed TWICE and either envelope alone opens it:
+
+      ssh     a key in your agent, Ed25519 only, signed deterministically
+      phrase  a BIP-39 recovery phrase, printed once and never stored
+
+    Ed25519 is not a preference. The derived key must reproduce on every
+    unlock, and RSA-PSS signatures are randomised \u2014 a share sealed under one
+    could never be opened again.
+`);
+}
+if (import.meta.main) {
+  await runCli();
+}
+async function runCli() {
+  const { command, args, options } = parseOptions(process.argv.slice(2));
+  let code = 0;
+  switch (command) {
+    case "keys":
+      code = await cmdKeys(options);
+      break;
+    case "status":
+      code = await cmdStatus(options);
+      break;
+    case "agent":
+      code = await cmdAgent(options, args);
+      break;
+    case "genesis":
+      code = await cmdGenesis(options);
+      break;
+    case "run":
+      process.exit(await runCommand(process.argv.slice(3), options));
+      break;
+    case "unlock":
+      code = await cmdUnlock(options);
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      usage();
+      break;
+    case "version":
+    case "--version":
+      out.line(VERSION);
+      break;
+    default:
+      out.fail(`Unknown command: ${command}`);
+      usage();
+      code = 1;
+  }
+  if (args.length > 0 && code === 0 && command !== "agent") {
+    out.warn(`Ignored: ${args.join(" ")}`);
+  }
+  process.exit(code);
+}
+export {
+  useCustodyIdentity,
+  requestHeaders
+};