@forgezero/agent 0.1.2 → 0.1.10

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
@@ -78,13 +93,64 @@ sync       what changed since a cursor
 held       what this guest is holding, by name only
 ```
 
+The vault socket never accepts commands or deployment definitions. Deployment
+enters through the root-only control socket or the signed outbound claim path,
+then the deployment manager validates the checked-in definition and submits it
+to the common keyed queue. Keeping execution off the vault socket prevents a
+compromised application from turning secret-read access into a local shell.
+
 `attest` **refuses** when no source is configured rather than returning
 something attestation-shaped. An operator who believes they have an attestation
 when nothing produced one is worse off than one told plainly it is unavailable.
 
-Full documentation: **https://forgezero.net/docs/agent**
+## Deployment definitions
+
+A repository may commit `.fz/deploy.yaml` with its own roles, prerequisite
+checks, commands, and the exact secret names each step needs. ForgeZero does not
+choose a tenant's database, framework, or deploy shape. The agent validates the
+file before executing any command, prepares only the selected role, and gives a
+step only the vault values it explicitly names. `await` returns the complete
+pipeline result; no polling service or persistent queue is required.
+
+The daemon owns source checkout and command execution. On a platform node it
+watches the configured branch after bootstrap, resolves every change to an
+exact commit, and writes `pending` then `running` before submitting that commit
+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:
+
+```bash
+fz-agent deploy --revision=<full-40-character-commit> --coordinator
+fz-agent status
+fz-agent pause
+fz-agent pause-key --key=project:production
+fz-agent stop-key --key=project:production   # running finishes; pending work is removed
+fz-agent start-key --key=project:production
+fz-agent cancel --id=q_42
+```
+
+The node seed and read-only Git private key are loaded with
+`LoadCredentialEncrypted=`. Their encrypted, host-bound blobs persist under
+`/etc/forgezero/creds`; decrypted values exist only in the service's private
+`$CREDENTIALS_DIRECTORY`. Platform bootstrap has no second clone/build path.
+Bootstrap records the forge's SSH host key during the attended access check;
+the daemon uses `StrictHostKeyChecking=yes` and never accepts a new host key by
+itself.
+
+Full documentation: **https://www.forgezero.net/docs/agent**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys.

package/dist/attestation-client.d.ts

@@ -0,0 +1,22 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import type { AttestationSource } from './socket';
+import { type SignedNodeHttpOptions } from './signed-node-http';
+export interface NodeAttestationOptions extends SignedNodeHttpOptions {
+    keys: NodeKeyPair;
+    source: AttestationSource;
+    intervalMs?: number;
+    /** Defaults to true. Set false after an explicitly awaited first attestation. */
+    immediate?: boolean;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+/** One challenge, one PSP report, one signed presentation. */
+export declare function attestNodeOnce(options: NodeAttestationOptions): Promise<{
+    measurement: string;
+    ageMs: number;
+}>;
+/** Re-attest without overlap; shutdown waits for the in-flight PSP/KDS round trip. */
+export declare function startNodeAttestation(options: NodeAttestationOptions): {
+    stop(): Promise<void>;
+};

package/dist/attestation-client.test.d.ts

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

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/compute.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Guest lifecycle on a machine — ours or a tenant's, identically.
+ *
+ * ## Why each guest is its own systemd unit
+ *
+ * The obvious shape is for the agent to launch qemu and keep track of it. That
+ * makes every guest a CHILD of the agent, and it means upgrading the agent —
+ * `systemctl restart fz-agent` — kills every tenant compute on the box. A host
+ * you cannot patch without an outage is a host that does not get patched.
+ *
+ * So the agent never owns a running guest. It writes a unit, asks systemd to
+ * start it, and walks away. systemd owns the process, restarts it after a host
+ * reboot, and survives the agent being replaced underneath it.
+ *
+ * ## Why the inventory lives on the root host
+ *
+ * The API is authoritative for what SHOULD exist. The host is authoritative for
+ * what DOES. Those disagree during an outage, a partial provision, or an
+ * operator's manual `kill` — and the host's answer is the one that matters when
+ * somebody is about to overwrite a disk.
+ *
+ * Persisting it here also means the host can bring its guests back with no
+ * control plane at all: the units are on disk, systemd starts them, and the
+ * platform reconciles later. A machine that needs the API to boot its tenants'
+ * computes is a machine that takes them down with it.
+ */
+export interface GuestSpec {
+    /** Stable name. Becomes the unit name, so it must be a valid identifier. */
+    name: string;
+    vcpu: number;
+    /** Exclusive host CPUs assigned to this guest's whole QEMU service. */
+    allowedCpus?: string;
+    /** NUMA memory nodes paired with allowedCpus, when the host exposes them. */
+    allowedMemoryNodes?: string;
+    memoryGib: number;
+    /** Block device or image path. Raw LVM on our metal; a file is allowed. */
+    disk: string;
+    /** cloud-init seed, attached read-only. */
+    seed: string;
+    bridge: string;
+    mac: string;
+    /** Stable tap owned by this unit. Required when egress is shaped. */
+    tap?: string;
+    /** Sustained guarantee and borrowable ceiling, in Mbit/s. */
+    egress?: {
+        guaranteedMbps: number;
+        burstMbps: number;
+    };
+    /**
+     * SEV-SNP, when the host can prove it.
+     *
+     * `cbitpos` is a property of the CPU, not a preference — it is read from the
+     * host at enrolment and carried here, because guessing it produces a guest
+     * that boots without memory encryption while claiming to have it.
+     */
+    confidential?: {
+        cbitpos: number;
+        reducedPhysBits: number;
+        policy: string;
+    };
+    consoleLog?: string;
+}
+export declare class ComputeError extends Error {
+    readonly code: 'BAD_NAME' | 'BAD_SPEC';
+    constructor(code: 'BAD_NAME' | 'BAD_SPEC', message: string);
+}
+export declare const unitName: (name: string) => string;
+/** The qemu command, as an argv array. Never a shell string. */
+export declare function qemuArgv(spec: GuestSpec): string[];
+/**
+ * The unit file.
+ *
+ * `Restart=always` is the point of using systemd at all: a guest that dies at
+ * 3am comes back without anybody being paged, and a host reboot brings every
+ * tenant's compute up in the same state it was in.
+ */
+export declare function guestUnit(spec: GuestSpec): string;
+export interface RunningGuest {
+    name: string;
+    pid: number;
+    disks: string[];
+}
+/**
+ * What is ACTUALLY running, read from process arguments.
+ *
+ * Not from libvirt, and not from the inventory. SEV-SNP guests are launched
+ * with raw qemu because libvirt on most hosts cannot express `sev-snp-guest`,
+ * so `virsh list` reports an empty machine while three confidential guests are
+ * running — and an operator who trusts it will overwrite their disks. That is
+ * not hypothetical; it is how this function came to exist.
+ */
+export declare function parseCensus(psOutput: string): RunningGuest[];
+/** Whether a device is in use by any running guest. */
+export declare const deviceInUse: (census: RunningGuest[], device: string) => boolean;
+/**
+ * Rate-limit a guest's egress on its tap device.
+ *
+ * Without this every guest can saturate the host's whole uplink — 25 Gb/s on
+ * our metal — so one tenant's runaway job starves the other guests and the
+ * hypervisor with them. It is also what makes bandwidth SELLABLE: a compute
+ * plan cannot state a number the machine does not enforce.
+ *
+ * Shaped on EGRESS only. Ingress arrives whether we want it or not; policing it
+ * at the tap drops packets that already crossed the expensive link, which costs
+ * the same and adds retransmits. Ingress belongs upstream, at the edge.
+ *
+ * The tap receives packets emitted by the guest, so the limiter belongs on the
+ * tap's INGRESS hook. A root qdisc there shapes traffic going into the guest and
+ * looks correct in `tc` while enforcing the opposite direction.
+ *
+ * The guaranteed rate is a placement promise: the host reserves enough uplink
+ * for every admitted guest. The per-tap policer enforces the burst ceiling.
+ */
+export declare function shapeEgressCommands(tap: string, mbps: number, burstMbps?: number): string[];
+/**
+ * The same contract as `shapeEgressCommands`, expressed without a shell for a
+ * systemd guest unit. Every argument is generated from validated numbers and a
+ * validated device name; no tenant-controlled command text is evaluated.
+ */
+export declare function shapeEgressUnitDirectives(tap: string, guaranteedMbps: number, burstMbps: number): string[];
+/** The tap a guest's NIC is attached to, from the census. */
+export declare const tapFor: (guestIndex: number) => string;