@forgezero/agent 0.1.62 → 0.1.63

package/README.md

@@ -51,6 +51,7 @@ Every row links to the detailed explanation and named-import/example area below.
 | @forgezero/agent/agent-update | Verified Agent update planning against the platform release coordinate. | Bun/Node host | [Details + example](#forgezero-agent-agent-update) |
 | @forgezero/agent/agent-update-helper | Root-owned fixed update operations with registry origin and integrity validation. | Bun/Node host | [Details + example](#forgezero-agent-agent-update-helper) |
 | @forgezero/agent/bootstrap | Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. | Bun/Node host | [Details + example](#forgezero-agent-bootstrap) |
+| @forgezero/agent/bootstrap-bundle | Owner-only exact-revision Git bundle and SHA-256 manifest for credential-free release generation one. | Bun/Node host | [Details + example](#forgezero-agent-bootstrap-bundle) |
 | @forgezero/agent/operator-bootstrap | Pinned-host operator transport that stages owner-only handoffs and invokes the same typed platform bootstrap through the caller-approved SSH agent. | Bun/Node host | [Details + example](#forgezero-agent-operator-bootstrap) |
 | @forgezero/agent/host-maintenance | Closed host maintenance plans for staging transaction rehearsal and fleet-fenced schema consolidation through fixed transient systemd units. | Bun/Node host | [Details + example](#forgezero-agent-host-maintenance) |
 | @forgezero/agent/capacity-calibration | One-time target-local safe-concurrency calibration with private evidence. | Bun/Node host | [Details + example](#forgezero-agent-capacity-calibration) |
@@ -82,7 +83,8 @@ bun add -g @forgezero/agent — Install the version-matched fz operator CLI and
 fz deploy init — Create a typed forgezero.deploy.ts and its canonical inert execution plan.
 fz deploy compile — Compile and validate TypeScript deployment intent into .fz/deploy.plan.json.
 fz deploy check — Refuse stale plans, unsafe provider/action coordinates and unresolved deployment blockers.
-fz bootstrap platform remote prepare --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json — Dry-plan one pinned operator-to-guest bootstrap; add --apply only after review.
+fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle — Build one verified release-generation-one source bundle without a Git credential.
+fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json — Dry-plan one pinned operator-to-guest bootstrap; add --apply only after review.
 fz bootstrap platform --help — Inspect attended platform bootstrap inputs before applying them.
 fz bootstrap metal --help — Inspect the identity-only physical provisioner bootstrap.
 fz host transactions|schema-plan|schema-apply — Plan fixed supervised database maintenance; add --apply only after reviewing the exact argv and credential names.
@@ -93,7 +95,8 @@ bun add -g @forgezero/agent
 fz deploy init
 fz deploy compile
 fz deploy check
-fz bootstrap platform remote prepare --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
+fz bootstrap platform bundle --root /absolute/api --branch dev --output /secure/forgezero/development/api.bundle
+fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
 fz bootstrap platform --help
 fz bootstrap metal --help
 fz host transactions|schema-plan|schema-apply
@@ -278,15 +281,39 @@ import type { AgentUpdateOutcome, AgentUpdateReceipt, AgentUpdateRequest, AgentU
 <a id="forgezero-agent-bootstrap"></a>
 ## @forgezero/agent/bootstrap
 
-Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. Named value imports: BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost, planBootstrap, preparePlatformBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets. Named type imports: BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapPreparation, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource. Import only the names used by this file.
+Typed one-time platform bootstrap and internal API-driven enrolled-compute activation contracts. Named value imports: BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost, planBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets. Named type imports: BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets, BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets, InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource. Import only the names used by this file.
 
 ```text
 import { BOOTSTRAP_STATE_PATH, PLATFORM_BOOTSTRAP_PROFILES, applyBootstrap, bootstrapIdentityDigest, bootstrapStatus, localBootstrapHost } from '@forgezero/agent/bootstrap';
-import { planBootstrap, preparePlatformBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets } from '@forgezero/agent/bootstrap';
-import { validatePlatformBootstrapSecrets } from '@forgezero/agent/bootstrap';
+import { planBootstrap, readBootstrapConfig, resolveInstalledBootstrapKind, validateBootstrapConfig, validateEnrolledComputeBootstrapSecrets, validatePlatformBootstrapSecrets } from '@forgezero/agent/bootstrap';
 import type { BootstrapConfig, BootstrapEnvironment, BootstrapHost, BootstrapPlan, BootstrapResult, BootstrapSecrets } from '@forgezero/agent/bootstrap';
 import type { BootstrapStatus, BootstrapStep, DatabaseAgencyParticipation, DatabaseBootstrapRole, EnrolledComputeActivationConfig, EnrolledComputeBootstrapSecrets } from '@forgezero/agent/bootstrap';
-import type { InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapPreparation, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource } from '@forgezero/agent/bootstrap';
+import type { InstalledBootstrapKind, PlatformBootstrapConfig, PlatformBootstrapProfile, PlatformBootstrapSecrets, PlatformEnrolmentSource } from '@forgezero/agent/bootstrap';
+```
+
+<a id="forgezero-agent-bootstrap-bundle"></a>
+## @forgezero/agent/bootstrap-bundle
+
+Owner-only exact-revision Git bundle and SHA-256 manifest for credential-free release generation one. Named value imports: BOOTSTRAP_BUNDLE_FORMAT, BOOTSTRAP_BUNDLE_KIND, MAX_BOOTSTRAP_BUNDLE_BYTES, buildBootstrapBundle, parseBootstrapBundleManifest, readBootstrapBundle, sha256File. Named type imports: BootstrapBundleBuildInput, BootstrapBundleBuildResult, BootstrapBundleCommand, BootstrapBundleCommandResult, BootstrapBundleManifest. Import only the names used by this file.
+
+```text
+import { BOOTSTRAP_BUNDLE_FORMAT, BOOTSTRAP_BUNDLE_KIND, MAX_BOOTSTRAP_BUNDLE_BYTES, buildBootstrapBundle, parseBootstrapBundleManifest, readBootstrapBundle } from '@forgezero/agent/bootstrap-bundle';
+import { sha256File } from '@forgezero/agent/bootstrap-bundle';
+import type { BootstrapBundleBuildInput, BootstrapBundleBuildResult, BootstrapBundleCommand, BootstrapBundleCommandResult, BootstrapBundleManifest } from '@forgezero/agent/bootstrap-bundle';
+```
+
+## @forgezero/agent/bootstrap-bundle — Build release generation one without a deploy key
+
+The builder refuses tracked drift, resolves one exact commit, creates an owner-only Git bundle and writes a byte-count/SHA-256 manifest. Bootstrap consumes the artifact after activation.
+
+```text
+import { buildBootstrapBundle, readBootstrapBundle } from '@forgezero/agent/bootstrap-bundle';
+
+const built = await buildBootstrapBundle({
+  repositoryRoot: '/work/forgezero-api', branch: 'main',
+  outputPath: '/secure/forgezero/production/api.bundle'
+});
+await readBootstrapBundle(built.bundlePath, built.manifestPath);
 ```
 
 <a id="forgezero-agent-operator-bootstrap"></a>
@@ -302,14 +329,12 @@ import type { OperatorPlatformBootstrapOptions, OperatorPlatformBootstrapPlan, O
 
 ## @forgezero/agent/operator-bootstrap — Run the same typed platform bootstrap from an operator laptop
 
-The request contains only an explicit target IP, pinned host public key/fingerprint, the caller public-key file, SSH-agent socket and a path to the reviewed secret-free platform config. Credential values come from hidden prompts or authenticated SSH stdin and are sealed immediately as systemd credentials; the private SSH key stays in the operator agent, and the default command is a non-contacting plan.
+The request contains the pinned SSH transport, reviewed platform config, and one verified local Git bundle copied identically to every genesis compute. No repository key is created. Hidden credential values are sealed immediately as systemd credentials.
 
 ```text
-fz bootstrap platform remote prepare \
-  --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
+fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json
 # Review, then allow the SSH-agent approval prompt:
-fz bootstrap platform remote prepare \
-  --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json --apply
+fz bootstrap platform remote apply --bootstrap-config /secure/forgezero/development/dev-fz-n1-remote.json --apply
 ```
 
 <a id="forgezero-agent-host-maintenance"></a>

package/dist/agent-heartbeat.js

@@ -749,7 +749,7 @@ async function postSignedNode(options, path, body) {
 }
 
 // src/version.ts
-var VERSION3 = "0.1.62";
+var VERSION3 = "0.1.63";
 
 // src/agent-heartbeat.ts
 var unquote = (value) => value.replace(/^['"]|['"]$/g, "");

package/dist/bootstrap-bundle.d.ts

@@ -0,0 +1,31 @@
+export declare const BOOTSTRAP_BUNDLE_FORMAT: 1;
+export declare const BOOTSTRAP_BUNDLE_KIND: "forgezero-api-git-bundle";
+export declare const MAX_BOOTSTRAP_BUNDLE_BYTES: number;
+export interface BootstrapBundleManifest {
+    format: typeof BOOTSTRAP_BUNDLE_FORMAT;
+    kind: typeof BOOTSTRAP_BUNDLE_KIND;
+    branch: string;
+    revision: string;
+    sha256: string;
+    bytes: number;
+    createdAt: string;
+}
+export interface BootstrapBundleBuildInput {
+    repositoryRoot: string;
+    outputPath: string;
+    branch: string;
+}
+export interface BootstrapBundleBuildResult {
+    bundlePath: string;
+    manifestPath: string;
+    manifest: BootstrapBundleManifest;
+}
+export interface BootstrapBundleCommandResult {
+    exitCode: number;
+    output: string;
+}
+export type BootstrapBundleCommand = (argv: readonly string[]) => Promise<BootstrapBundleCommandResult>;
+export declare function sha256File(path: string): Promise<string>;
+export declare function parseBootstrapBundleManifest(value: unknown): BootstrapBundleManifest;
+export declare function readBootstrapBundle(bundlePath: string, manifestPath?: string): Promise<BootstrapBundleBuildResult>;
+export declare function buildBootstrapBundle(input: BootstrapBundleBuildInput, exec?: BootstrapBundleCommand): Promise<BootstrapBundleBuildResult>;

package/dist/bootstrap-bundle.js

@@ -0,0 +1,165 @@
+// @bun
+// src/bootstrap-bundle.ts
+import { createHash, randomBytes } from "crypto";
+import {
+  chmodSync,
+  createReadStream,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { dirname, isAbsolute, resolve } from "path";
+var BOOTSTRAP_BUNDLE_FORMAT = 1;
+var BOOTSTRAP_BUNDLE_KIND = "forgezero-api-git-bundle";
+var MAX_BOOTSTRAP_BUNDLE_BYTES = 512 * 1024 * 1024;
+var run = async (argv) => {
+  const child = Bun.spawn([...argv], { stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}`.slice(0, 65536) };
+};
+var checked = async (exec, argv, label) => {
+  const result = await exec(argv);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed${result.output.trim() ? `: ${result.output.trim()}` : ""}`);
+  return result.output.trim();
+};
+async function sha256File(path) {
+  const hash = createHash("sha256");
+  await new Promise((resolveDone, reject) => {
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", resolveDone);
+  });
+  return hash.digest("hex");
+}
+var branchName = (value) => {
+  if (typeof value !== "string" || !/^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,126}[A-Za-z0-9])?$/.test(value) || value.includes("..") || value.includes("//") || value.startsWith("-")) {
+    throw new Error("bootstrap bundle branch is malformed");
+  }
+  return value;
+};
+function parseBootstrapBundleManifest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("bootstrap bundle manifest must be an object");
+  const source = value;
+  const allowed = ["format", "kind", "branch", "revision", "sha256", "bytes", "createdAt"];
+  const unknown = Object.keys(source).filter((key) => !allowed.includes(key));
+  if (unknown.length)
+    throw new Error(`bootstrap bundle manifest contains unknown field ${unknown[0]}`);
+  if (source.format !== BOOTSTRAP_BUNDLE_FORMAT || source.kind !== BOOTSTRAP_BUNDLE_KIND) {
+    throw new Error("bootstrap bundle manifest format is unsupported");
+  }
+  branchName(source.branch);
+  if (typeof source.revision !== "string" || !/^[a-f0-9]{40}$/.test(source.revision)) {
+    throw new Error("bootstrap bundle revision must be an exact lowercase Git commit");
+  }
+  if (typeof source.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(source.sha256)) {
+    throw new Error("bootstrap bundle digest is malformed");
+  }
+  if (!Number.isSafeInteger(source.bytes) || Number(source.bytes) < 1 || Number(source.bytes) > MAX_BOOTSTRAP_BUNDLE_BYTES) {
+    throw new Error("bootstrap bundle size is outside the supported boundary");
+  }
+  if (typeof source.createdAt !== "string" || Number.isNaN(Date.parse(source.createdAt))) {
+    throw new Error("bootstrap bundle creation time is malformed");
+  }
+  return source;
+}
+function ownerRegularFile(path, maximum, label) {
+  if (!isAbsolute(path) || resolve(path) !== path || /[\r\n\0]/.test(path)) {
+    throw new Error(`${label} path must be canonical and absolute`);
+  }
+  const value = lstatSync(path);
+  const uid = process.getuid?.() ?? value.uid;
+  if (!value.isFile() || value.isSymbolicLink() || value.uid !== uid || value.nlink !== 1 || (value.mode & 63) !== 0 || value.size < 1 || value.size > maximum) {
+    throw new Error(`${label} must be an owner-only regular file with one link and at most ${maximum} bytes`);
+  }
+}
+async function readBootstrapBundle(bundlePath, manifestPath = `${bundlePath}.json`) {
+  ownerRegularFile(bundlePath, MAX_BOOTSTRAP_BUNDLE_BYTES, "bootstrap bundle");
+  ownerRegularFile(manifestPath, 16 * 1024, "bootstrap bundle manifest");
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    throw new Error("bootstrap bundle manifest is not valid JSON");
+  }
+  const manifest = parseBootstrapBundleManifest(parsed);
+  const size = lstatSync(bundlePath).size;
+  if (size !== manifest.bytes || await sha256File(bundlePath) !== manifest.sha256) {
+    throw new Error("bootstrap bundle bytes do not match their manifest");
+  }
+  return { bundlePath, manifestPath, manifest };
+}
+async function buildBootstrapBundle(input, exec = run) {
+  const repositoryRoot = resolve(input.repositoryRoot);
+  const outputPath = resolve(input.outputPath);
+  const manifestPath = `${outputPath}.json`;
+  const branch = branchName(input.branch);
+  if (!isAbsolute(input.outputPath) || outputPath !== input.outputPath) {
+    throw new Error("bootstrap bundle output must be a canonical absolute path");
+  }
+  if (existsSync(outputPath) || existsSync(manifestPath)) {
+    throw new Error("bootstrap bundle output already exists");
+  }
+  const root = lstatSync(repositoryRoot);
+  if (!root.isDirectory() || root.isSymbolicLink())
+    throw new Error("bootstrap bundle source must be a real directory");
+  mkdirSync(dirname(outputPath), { recursive: true, mode: 448 });
+  const parent = lstatSync(dirname(outputPath));
+  const uid = process.getuid?.() ?? parent.uid;
+  if (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== uid || (parent.mode & 63) !== 0) {
+    throw new Error("bootstrap bundle output directory must be caller-owned and owner-only");
+  }
+  const dirty = await checked(exec, ["git", "-C", repositoryRoot, "status", "--porcelain=v1", "--untracked-files=no"], "Git worktree check");
+  if (dirty)
+    throw new Error("bootstrap bundle source has tracked changes; commit the reviewed API release first");
+  const revision = (await checked(exec, ["git", "-C", repositoryRoot, "rev-parse", "--verify", `refs/heads/${branch}^{commit}`], "Git branch resolution")).toLowerCase();
+  if (!/^[a-f0-9]{40}$/.test(revision))
+    throw new Error("bootstrap bundle branch did not resolve to one exact commit");
+  const temporary = `${outputPath}.next.${process.pid}.${randomBytes(6).toString("hex")}`;
+  try {
+    await checked(exec, ["git", "-C", repositoryRoot, "bundle", "create", temporary, `refs/heads/${branch}`], "Git bundle creation");
+    chmodSync(temporary, 384);
+    const file = lstatSync(temporary);
+    if (!file.isFile() || file.isSymbolicLink() || file.size < 1 || file.size > MAX_BOOTSTRAP_BUNDLE_BYTES) {
+      throw new Error("created bootstrap bundle is outside the supported boundary");
+    }
+    await checked(exec, ["git", "bundle", "verify", temporary], "Git bundle verification");
+    const manifest = {
+      format: BOOTSTRAP_BUNDLE_FORMAT,
+      kind: BOOTSTRAP_BUNDLE_KIND,
+      branch,
+      revision,
+      sha256: await sha256File(temporary),
+      bytes: file.size,
+      createdAt: new Date().toISOString()
+    };
+    const manifestTemporary = `${manifestPath}.next.${process.pid}.${randomBytes(6).toString("hex")}`;
+    writeFileSync(manifestTemporary, `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384, flag: "wx" });
+    renameSync(temporary, outputPath);
+    renameSync(manifestTemporary, manifestPath);
+    return { bundlePath: outputPath, manifestPath, manifest };
+  } catch (cause) {
+    rmSync(temporary, { force: true });
+    throw cause;
+  }
+}
+export {
+  sha256File,
+  readBootstrapBundle,
+  parseBootstrapBundleManifest,
+  buildBootstrapBundle,
+  MAX_BOOTSTRAP_BUNDLE_BYTES,
+  BOOTSTRAP_BUNDLE_KIND,
+  BOOTSTRAP_BUNDLE_FORMAT
+};

package/dist/bootstrap.d.ts

@@ -15,8 +15,11 @@ export interface PlatformBootstrapConfig {
     computeReference: string;
     nodeHostname: string;
     apiUrl: string;
-    repository: string;
-    branch: string;
+    /** One attended local source used only for release generation one. */
+    bootstrapBundle: {
+        bundleFile: string;
+        manifestFile: string;
+    };
     deployRoot?: string;
     telemetryEndpoint: string;
     /**
@@ -76,6 +79,8 @@ export interface EnrolledComputeActivationConfig {
     profile?: string;
     deployRoot?: string;
     software?: SoftwareRequirement[];
+    /** Compatibility-only per-node SSH deploy key. GitHub App is the scalable default. */
+    gitDeployKey?: boolean;
     installCloudflared?: boolean;
     installWarp?: boolean;
     /** Optional node-specific attended Tunnel/KV/Mesh handoff, identical to platform hosts. */
@@ -136,13 +141,6 @@ export interface BootstrapResult {
         inviteUrl: string;
     };
 }
-export interface PlatformBootstrapPreparation {
-    kind: 'platform';
-    prepared: true;
-    identityDigest: string;
-    gitPublicKey: string;
-    next: 'register this read-only deploy key, then run --apply concurrently on all three genesis Agency members';
-}
 export interface BootstrapStatus {
     initialized: boolean;
     kind?: BootstrapConfig['kind'];
@@ -182,14 +180,6 @@ export declare const BOOTSTRAP_STATE_PATH = "/var/lib/forgezero/bootstrap.json";
 export declare function validateBootstrapConfig(value: BootstrapConfig): BootstrapConfig;
 export declare function planBootstrap(input: BootstrapConfig, initialized?: boolean): BootstrapPlan;
 export declare function bootstrapIdentityDigest(config: BootstrapConfig): string;
-/**
- * Install only the common Agent boundary and generate its machine-local Git
- * identity. Private repositories cannot be deployed until the owner registers
- * this public key, so pretending one monolithic first command can do both is a
- * sequencing bug. The bound intent makes the later apply resumable and refuses
- * a different config after this first privileged mutation.
- */
-export declare function preparePlatformBootstrap(input: PlatformBootstrapConfig, host?: BootstrapHost): Promise<PlatformBootstrapPreparation>;
 export declare function bootstrapStatus(host?: BootstrapHost): Promise<BootstrapStatus>;
 export declare function applyBootstrap(input: BootstrapConfig, host?: BootstrapHost, secrets?: BootstrapSecrets, dependencies?: {
     fetcher?: typeof fetch;