@forgezero/agent 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,6 @@
 # @forgezero/agent
 
-**`fz-agent` — so the application beside it holds no credential at all.**
+**`fz` controls the machine; `fz-agent` runs its managed work.**
 
 The agent keeps a project-scoped copy of your vault in RAM and answers over a
 unix socket. `@forgezero/vault` prefers that socket over an API key whenever it
@@ -10,9 +10,24 @@ from it.
 
 ```bash
 bun add -g @forgezero/agent      # or let `fz agent install` do it
+fz --help
 ```
 
-Most people never install this directly:
+The one public package installs both commands. Keeping bootstrap and the daemon
+in one version prevents a newly installed `fz` from provisioning a different
+agent protocol.
+
+The operator command launches a platform, runs custody ceremonies, inspects
+status, wraps processes, and installs the daemon:
+
+```bash
+fz keys
+fz status
+fz genesis --mode 2-of-3
+fz unlock
+```
+
+Install the service explicitly:
 
 ```bash
 fz agent install --apply         # writes a hardened systemd unit
@@ -104,6 +119,14 @@ to the keyed queue. A restart in either state resumes the exact commit; only an
 awaited successful pipeline writes `deployed`. Tenant nodes receive the same
 exact-commit request from the signed API claim path.
 
+Repository read authorization is explicit per pipeline: public HTTPS, the
+compute's systemd-sealed SSH deploy key, or a fine-grained HTTPS token selected
+by a project-vault secret name. A signed claim contains the mode and secret name
+only. The agent resolves the value from its scoped memory cache, limits the Git
+header to the repository origin, never writes the token into a command, and
+never exposes it to tenant pipeline steps. Automatic GitHub App token minting
+can feed the same short-lived token mode later; it is not implemented today.
+
 An operator may also force a deployment and await the complete result over the
 private control socket:
 

package/dist/cli/agent-install.d.ts

@@ -0,0 +1,82 @@
+import { type Capabilities, type ProvisionPlan } from '../provision';
+/**
+ * `fz agent install` — run the provision plan on THIS machine.
+ *
+ * The plan itself is the agent's public `provision` subpath, with no transport, and
+ * that is the whole point: the platform runs the same steps over SSH when it
+ * enrols a compute. This file is the local executor and nothing else — it
+ * decides how to run a command here, never what the commands are.
+ *
+ * It was briefly the other thing. This module had its own machine detection
+ * calling `existsSync` directly and its own unit renderer, while the API had a
+ * `Check`-based preflight designed to run remotely. Two answers to "is this box
+ * ready" is one answer nobody can trust, and the local one drifts first because
+ * it is the one somebody runs while debugging.
+ */
+export type { ProvisionPlan };
+/** Parse NAME=value pairs used only for non-secret unit coordinates and credential paths. */
+export declare function parseAssignments(value: string | undefined): Record<string, string> | undefined;
+/**
+ * Answer the capability checks by running their commands.
+ *
+ * Running the command rather than calling `existsSync` is deliberate even
+ * though this is the local path: it means the answer here and the answer over
+ * SSH come from the same test, so a box that reports `attested` to an operator
+ * cannot report `enrolled` to the platform.
+ */
+export declare function readCapabilities(run: (command: string) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>): Promise<Capabilities>;
+/** Run a command locally. The SSH executor is the platform's half. */
+export declare function localRunner(command: string): Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+export interface InstallOptions {
+    capabilities: Capabilities;
+    socketPath: string;
+    seedPath: string;
+    seedCredentialPath?: string;
+    gitCredentialPath?: string;
+    gitPublicKeyPath?: string;
+    generateGitIdentity?: boolean;
+    controlSocketPath?: string;
+    repository?: string;
+    branch?: string;
+    role?: string;
+    deployRoot?: string;
+    publicApiUrl?: string;
+    deploymentEnvironment?: Record<string, string>;
+    deploymentCredentials?: Record<string, string>;
+    pullDeployments?: boolean;
+    binPath?: string;
+    sourceBinPath?: string;
+    user?: string;
+    apiUrl?: string;
+    project?: string;
+    environment?: string;
+    enrolTokenSourcePath?: string;
+    enrolTokenCredentialPath?: string;
+    enrolStatePath?: string;
+    nodeLabel?: string;
+}
+export declare function planInstall(options: InstallOptions): ProvisionPlan;
+/** Execute the same ordered plan the control plane executes over SSH. */
+export declare function applyPlan(plan: ProvisionPlan, run: (command: string) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>): Promise<readonly {
+    label: string;
+    command: string;
+    exitCode: number;
+}[]>;
+/**
+ * What a reader needs to see before running any of it.
+ *
+ * Printed rather than executed by default. Installing a system service that
+ * holds key material should not happen because somebody typed a subcommand, and
+ * an operator who reads the unit first is one who can notice it is about to run
+ * as the wrong user.
+ */
+export declare function renderPlan(plan: ProvisionPlan): string;

package/dist/cli/agent-install.test.d.ts

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

package/dist/cli/custody.d.ts

@@ -0,0 +1,35 @@
+import { type AgentIdentity } from '@forgezero/runtime/ssh-agent';
+/**
+ * Choosing an SSH key for custody, safely.
+ *
+ * A real agent is not a clean room. It commonly holds forwarded keys whose
+ * upstream connection is gone, and confirm-on-use keys that wait for a human at
+ * a terminal nobody is sitting at. Neither fails — both **hang**, which during a
+ * genesis ceremony looks exactly like the platform being broken.
+ *
+ * So every key is probed under a timeout before it is offered, and the one
+ * actually chosen is proved deterministic before it is trusted with a share. An
+ * agent that signs differently twice would seal a share that can never be
+ * reopened, and that failure would surface only during recovery.
+ */
+export declare const PROBE_TIMEOUT_MS = 2000;
+export interface UsableIdentity extends AgentIdentity {
+    /** Milliseconds the agent took to sign. Slow keys are usually forwarded. */
+    responseMs: number;
+}
+/**
+ * Every Ed25519 key in the agent that actually responds.
+ *
+ * Returns an empty array rather than throwing when the agent holds nothing
+ * usable — the caller has a better error to give than this function does.
+ */
+export declare function usableIdentities(socketPath?: string): Promise<UsableIdentity[]>;
+/**
+ * Derive the custody key for a chosen identity, having proved it reproduces.
+ *
+ * `assertDeterministic` signs twice and compares. It costs one extra signature
+ * and removes the only failure mode that is invisible until recovery.
+ */
+export declare function custodyKeyFor(identity: AgentIdentity, socketPath?: string): Promise<Uint8Array>;
+/** Match a key by fingerprint prefix, comment, or 1-based index. */
+export declare function selectIdentity(identities: UsableIdentity[], selector: string): UsableIdentity | null;

package/dist/cli/genesis.d.ts

@@ -0,0 +1,79 @@
+import { type SealedShare } from '@forgezero/runtime/custody-share';
+import type { UsableIdentity } from './custody';
+/**
+ * The genesis ceremony, driven from a terminal.
+ *
+ * Every value that matters is produced HERE and only sealed material crosses
+ * the wire:
+ *
+ *   phrase   generated locally, printed once, never transmitted or stored
+ *   ssh key  derived locally from an agent signature, never transmitted
+ *
+ * The API receives the derived 32-byte keys because that is what seals a share,
+ * and it holds them for exactly the length of one request. Nothing here gives
+ * the CLI a privileged path — it calls the same endpoints the browser does, and
+ * a bypass that existed for bootstrapping would exist for an attacker too.
+ */
+export interface Transport {
+    (path: string, init?: {
+        method?: string;
+        body?: unknown;
+    }): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export interface GenesisResult {
+    ceremonyKey: string;
+    phrase: string[];
+    fingerprint: string;
+    activated: boolean;
+}
+/**
+ * Run a single-custodian genesis.
+ *
+ * Deliberately limited to the operator running the command. A multi-custodian
+ * genesis needs each person at their own terminal with their own agent, which
+ * is a coordination problem rather than a code one — and pretending to do it
+ * from one shell would mean one machine briefly holding every share.
+ */
+export declare function runGenesis(args: {
+    api: Transport;
+    modeId: string;
+    userKey: string;
+    email: string;
+    identity: UsableIdentity;
+    /** The `plt_` token setup.sh wrote. Required — see below. */
+    token: string;
+    displayName?: string;
+    socketPath?: string;
+    onStep?: (message: string) => void;
+}): Promise<GenesisResult>;
+/**
+ * Reconstruct the seed and unlock.
+ *
+ * A restart genuinely locks the vault — residency is derived from memory, never
+ * a stored flag — so this is the routine every reboot needs, not an exceptional
+ * recovery path.
+ */
+export declare function runUnlock(args: {
+    api: Transport;
+    userKey: string;
+    identity?: UsableIdentity;
+    phrase?: string[];
+    socketPath?: string;
+    /**
+     * This custodian's sealed envelope, read from the ceremony.
+     *
+     * Supplied by the caller because only they know which ceremony they are
+     * unlocking. Opening it is a local step now, so no factor travels.
+     */
+    sealed?: SealedShare;
+    /** The salt the phrase wrapping key was derived over. */
+    phraseSalt?: string;
+    onStep?: (message: string) => void;
+}): Promise<{
+    fingerprint: string;
+}>;
+/** Resolve `--key` to a usable identity, with an actionable error if it cannot. */
+export declare function resolveIdentity(selector: string | undefined, socketPath?: string): Promise<UsableIdentity>;

package/dist/cli/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import { type AgentIdentity } from '@forgezero/runtime/ssh-agent';
+/**
+ * What every CLI request carries.
+ *
+ * Extracted and exported because the `origin` header below is load-bearing and
+ * was invisible: `fz --help` proved the binary starts, and every command that
+ * CHANGED anything was answered 403 by the CSRF rule with nothing in between to
+ * notice. A header nobody can see is a header nobody maintains.
+ */
+export declare function requestHeaders(apiBase: string, cookie: string | null): Record<string, string>;
+export declare function useCustodyIdentity(identity: AgentIdentity, socketPath?: string): void;

package/dist/cli/options.test.d.ts

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

package/dist/cli/run.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Operator process injection, shipped beside the agent command.
+ *
+ * `fz run -- <command>` — hand secrets to a process that cannot ask for them.
+ *
+ * This is the FALLBACK, and it is worth saying so at the top of the file. The
+ * agent serves secrets over a unix socket and anything using `@forgezero/vault`
+ * reads them there, which means a rotation reaches a running process. An
+ * injected environment cannot rotate: a process started before a rotation runs
+ * on the old value until somebody restarts it, and nothing tells them.
+ *
+ * It exists because a great deal of software will never read a socket, and
+ * "rewrite your build tool" is not an adoption path.
+ *
+ * ## What an environment variable costs
+ *
+ * On Linux `/proc/<pid>/environ` is readable by the same user, and any child
+ * inherits everything. That is the standard trade and it is not hidden here:
+ * the whole point of the socket path is that it does not make that trade.
+ *
+ * Values never reach argv, because argv is world-readable in `ps` — which is a
+ * different and much worse exposure than the environment.
+ */
+export declare class RunError extends Error {
+    readonly code: 'NO_COMMAND' | 'NO_SEPARATOR' | 'BAD_NAME';
+    constructor(code: 'NO_COMMAND' | 'NO_SEPARATOR' | 'BAD_NAME', message: string);
+}
+/**
+ * Split fz's own arguments from the child's.
+ *
+ * `--` is the boundary and it is not optional. Without it `fz run node --watch`
+ * would have fz eat `--watch`, and the failure is a flag that silently does not
+ * reach the program somebody is debugging.
+ *
+ * Everything after the FIRST separator belongs to the child, separators
+ * included: `fz run -- sh -c 'x -- y'` has to pass the inner one through.
+ */
+export declare function splitAtSeparator(argv: readonly string[]): {
+    own: string[];
+    command: string[];
+};
+export interface MergeOptions {
+    /** Keep an existing value when both sides have the name. Default false. */
+    preserveEnv?: boolean;
+}
+export interface MergeResult {
+    env: Record<string, string>;
+    /** Names present in both. Reported so a collision is never silent. */
+    collisions: string[];
+    /** Names the shell cannot express, refused rather than mangled. */
+    refused: string[];
+}
+/**
+ * Merge vault values into an environment.
+ *
+ * The vault wins by default: a caller running `fz run` is asking for vault
+ * values, and quietly preferring a stale variable already in the shell is how
+ * somebody debugs a wrong credential for an hour.
+ *
+ * `--preserve-env` inverts it for the case where a wrapper genuinely wants to
+ * override. Either way the COLLISIONS are returned so the caller can say which
+ * names were affected. Silence is what makes this confusing, not the direction.
+ */
+export declare function mergeEnvironment(base: Record<string, string | undefined>, secrets: Record<string, string>, options?: MergeOptions): MergeResult;
+/**
+ * What to print before handing over.
+ *
+ * Names only. A wrapper that echoed values would put every secret into whatever
+ * captured the build log, which is usually the one place they are kept longest.
+ */
+export declare function describeInjection(result: MergeResult, count: number): string;
+/**
+ * Turn a child's exit into this process's exit.
+ *
+ * A wrapper that always exits 0 breaks every CI pipeline it is put in front of,
+ * silently, by turning a failed build into a passing one. A signal death is
+ * reported the way a shell reports it — 128 plus the signal number — so
+ * `fz run -- make` behaves like `make` for anything reading the code.
+ */
+export declare function exitCodeFor(status: {
+    code: number | null;
+    signal: string | null;
+}): number;
+/**
+ * Start the child and become its exit code.
+ *
+ * Separated from the command handler so it can be driven by a test with real
+ * processes. The interesting behaviour is entirely here — inherited stdio,
+ * forwarded signals, propagated status — and none of it is provable against a
+ * mock.
+ */
+export declare function spawnWith(command: readonly string[], env: Record<string, string>, report?: (line: string) => void): Promise<number>;

package/dist/cli/run.test.d.ts

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

package/dist/deployment-pull.d.ts

@@ -1,5 +1,5 @@
 import type { NodeKeyPair } from '@forgezero/runtime/identity';
-import type { DeploymentManager, DeploymentResult } from './deployment';
+import type { DeploymentManager, DeploymentResult, GitSourceAuth } from './deployment';
 export interface RemoteDeploymentClaim {
     runKey: string;
     pipelineKey: string;
@@ -12,6 +12,7 @@ export interface RemoteDeploymentClaim {
         branch: string;
         role: string;
         knownHosts?: string;
+        auth?: GitSourceAuth;
     };
 }
 export interface DeploymentPullOptions {

package/dist/deployment.d.ts

@@ -27,6 +27,19 @@ export interface DeploymentResult {
     ok: boolean;
     phases: readonly RunResult[];
 }
+/**
+ * How the credential-bearing agent may read one server-owned Git source.
+ * Secret values never appear in a deployment claim or checked-in pipeline.
+ */
+export type GitSourceAuth = {
+    kind: 'public';
+} | {
+    kind: 'node-ssh';
+} | {
+    kind: 'vault-token';
+    secret: string;
+    username?: string;
+};
 export interface DeploymentOptions {
     /** Queue key. Same project/environment is serial; other managers may run in parallel. */
     key: string;
@@ -35,6 +48,7 @@ export interface DeploymentOptions {
     role: string;
     root: string;
     publicApiUrl?: string;
+    sourceAuth?: GitSourceAuth;
     gitCredentialPath?: string;
     knownHostsPath?: string;
     /** Server-owned, operator-pinned host keys for a dynamically assigned source. */

package/dist/fz-agent.js

@@ -448,10 +448,39 @@ function createDeploymentManager(options) {
     renameSync(next, knownHostsPath);
     chmodSync2(knownHostsPath, 384);
   };
-  const gitEnvironment = () => {
-    if (/^https:\/\//i.test(options.repository)) {
+  const gitEnvironment = async () => {
+    const https = /^https:\/\//i.test(options.repository);
+    const auth = options.sourceAuth ?? (https ? { kind: "public" } : { kind: "node-ssh" });
+    if (auth.kind === "public") {
+      if (!https)
+        throw new DeploymentError("SOURCE_FAILED", "Public Git sources must use HTTPS.");
       return { GIT_TERMINAL_PROMPT: "0" };
     }
+    if (auth.kind === "vault-token") {
+      if (!https)
+        throw new DeploymentError("SOURCE_FAILED", "Vault Git tokens may only be sent to HTTPS sources.");
+      if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(auth.secret)) {
+        throw new DeploymentError("SOURCE_FAILED", "The Git token secret name is invalid.");
+      }
+      if (!options.cache) {
+        throw new DeploymentError("SECRET_MISSING", `Git source credential ${auth.secret} is unavailable.`);
+      }
+      const username = auth.username ?? "x-access-token";
+      if (!/^[A-Za-z0-9._@+-]{1,128}$/.test(username)) {
+        throw new DeploymentError("SOURCE_FAILED", "The Git token username is invalid.");
+      }
+      const token = await options.cache.get(auth.secret);
+      if (!token || token.length > 8192 || /[\r\n\0]/.test(token)) {
+        throw new DeploymentError("SOURCE_FAILED", `Git source credential ${auth.secret} is malformed.`);
+      }
+      const origin = new URL(options.repository).origin;
+      return {
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: `http.${origin}/.extraHeader`,
+        GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`${username}:${token}`).toString("base64")}`
+      };
+    }
     if (!gitCredentialPath) {
       throw new DeploymentError("SOURCE_FAILED", "No Git deploy-key credential was loaded for the agent.");
     }
@@ -474,7 +503,7 @@ function createDeploymentManager(options) {
     }
     const stamp = `${new Date(now()).toISOString().replace(/[-:.TZ]/g, "")}-${process.pid}-${randomUUID().slice(0, 8)}`;
     const release = join(options.root, "releases", stamp);
-    const env = gitEnvironment();
+    const env = await gitEnvironment();
     await checked({
       command: `test -d ${quote(join(options.root, "releases"))} && test -w ${quote(join(options.root, "releases"))}`
     }, "SOURCE_FAILED");
@@ -565,7 +594,7 @@ function createDeploymentManager(options) {
     async latestRevision() {
       const result = await checked({
         command: `git ls-remote --exit-code ${quote(options.repository)} ${quote(`refs/heads/${options.branch}`)}`,
-        env: gitEnvironment()
+        env: await gitEnvironment()
       }, "SOURCE_FAILED");
       const revision = result.output.trim().split(/\s+/)[0] ?? "";
       if (!/^[a-f0-9]{40}$/i.test(revision)) {
@@ -1353,7 +1382,15 @@ async function pullProvisioningOnce(options) {
   if (options.metalPreflight) {
     const report = options.metalPreflight();
     const accepted = await postSignedNode(options, "v1/metal/preflight", report);
-    options.onEvent?.("preflight", { ...report, ready: accepted.ready, state: accepted.state });
+    if (options.metalHostname && accepted.hostname !== options.metalHostname) {
+      throw new Error(`metal agent: configured inventory hostname ${options.metalHostname} is bound as ${accepted.hostname}; refusing work.`);
+    }
+    options.onEvent?.("preflight", {
+      ...report,
+      hostname: accepted.hostname,
+      ready: accepted.ready,
+      state: accepted.state
+    });
     if (!accepted.ready)
       return { status: "idle" };
   }
@@ -2633,7 +2670,7 @@ async function applyMetalIsolation(profile, exec = defaultExec) {
 }
 
 // src/index.ts
-var VERSION = "0.1.9";
+var VERSION = "0.1.11";
 function loadOrCreateSeed(path) {
   if (existsSync9(path)) {
     const seed2 = new Uint8Array(Buffer.from(readFileSync5(path, "utf8").trim(), "base64url"));
@@ -2831,6 +2868,8 @@ if (import.meta.main) {
   if (process.env.FZ_AGENT_ROLE === "metal") {
     if (!process.env.FZ_API)
       throw new Error("metal agent requires FZ_API");
+    if (!process.env.FZ_METAL_HOSTNAME)
+      throw new Error("metal agent requires FZ_METAL_HOSTNAME");
     const seed = process.env.FZ_SEED_CREDENTIAL ? loadSeedCredential(process.env.FZ_SEED_CREDENTIAL) : loadOrCreateSeed(process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH);
     const keys2 = deriveKeysFromSeed(seed);
     const nodeKey2 = process.env.FZ_NODE_KEY ?? keys2.ed25519.publicKey;
@@ -2838,6 +2877,7 @@ if (import.meta.main) {
       apiUrl: process.env.FZ_API,
       nodeKey: nodeKey2,
       keys: keys2,
+      metalHostname: process.env.FZ_METAL_HOSTNAME,
       run: (claim) => requestMetalProvision(claim, process.env.FZ_METAL_HELPER_SOCKET ?? DEFAULT_METAL_HELPER_SOCKET),
       metalPreflight: () => ({
         snpHost: existsSync9("/dev/sev"),
@@ -2974,6 +3014,7 @@ if (import.meta.main) {
       repository: source.repository,
       branch: source.branch,
       role: source.role,
+      sourceAuth: source.auth,
       root,
       publicApiUrl: process.env.FZ_PUBLIC_API_URL,
       environment: Object.fromEntries((process.env.FZ_DEPLOY_ENV_NAMES ?? "").split(",").filter(Boolean).map((name) => {
@@ -3021,7 +3062,8 @@ if (import.meta.main) {
           claim.pipelineKey,
           claim.source.repository,
           claim.source.branch,
-          claim.source.role
+          claim.source.role,
+          JSON.stringify(claim.source.auth ?? null)
         ].join("\x00");
         const existing = managers.get(cacheKey);
         if (existing)