@forgezero/agent 0.1.2 → 0.1.10

package/dist/guest-enrolment.d.ts

@@ -0,0 +1,29 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+export interface GuestBinding {
+    nodeKey: string;
+    computeReference: string;
+    projectKey: string;
+    environmentKey: string;
+    tenantSlug: string;
+}
+export interface GuestEnrolmentOptions {
+    apiUrl: string;
+    /** Already-unsealed systemd credential. Production uses this path. */
+    token?: string;
+    /** Legacy/dev input; removed after a successful exchange. */
+    tokenPath?: string;
+    /** Removes the encrypted one-time source after the binding is durable. */
+    consume?: () => void | Promise<void>;
+    /** Non-secret coordinates needed to recover the tenant route after restart. */
+    statePath: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    label?: string;
+    gitDeployPublicKey?: string;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    requestTimeoutMs?: number;
+}
+/** Load only routing coordinates. The node seed and enrolment token never enter this file. */
+export declare function loadGuestBinding(path: string, expectedNodeKey: string): GuestBinding | null;
+/** Exchange the cloud-init capability for the guest's permanent public identity. */
+export declare function enrolGuestIdentity(options: GuestEnrolmentOptions): Promise<GuestBinding>;

package/dist/guest-enrolment.js

@@ -0,0 +1,88 @@
+// src/guest-enrolment.ts
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname } from "node:path";
+var validBinding = (value, expectedNodeKey) => {
+  if (!value || typeof value !== "object")
+    return false;
+  const row = value;
+  return ["nodeKey", "computeReference", "projectKey", "environmentKey", "tenantSlug"].every((key) => typeof row[key] === "string" && row[key].length > 0) && (!expectedNodeKey || row.nodeKey === expectedNodeKey);
+};
+function loadGuestBinding(path, expectedNodeKey) {
+  if (!existsSync(path))
+    return null;
+  const mode = statSync(path).mode & 511;
+  if ((mode & 63) !== 0) {
+    throw new Error(`guest enrolment state at ${path} is not private`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new Error(`guest enrolment state at ${path} is malformed`);
+  }
+  if (!validBinding(parsed, expectedNodeKey)) {
+    throw new Error(`guest enrolment state at ${path} does not match this node identity`);
+  }
+  return parsed;
+}
+function persistGuestBinding(path, binding) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const temporary = `${path}.next`;
+  writeFileSync(temporary, `${JSON.stringify(binding)}
+`, { mode: 384 });
+  chmodSync(temporary, 384);
+  renameSync(temporary, path);
+}
+async function enrolGuestIdentity(options) {
+  const token = options.token?.trim() ?? (options.tokenPath ? readFileSync(options.tokenPath, "utf8").trim() : "");
+  if (!token.startsWith("fze_"))
+    throw new Error("guest enrolment credential is malformed");
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/v1/compute/enrol`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      token,
+      label: options.label,
+      gitDeployPublicKey: options.gitDeployPublicKey,
+      publicKeys: {
+        ed25519: options.keys.ed25519.publicKey,
+        mlDsa: options.keys.mlDsa.publicKey
+      }
+    }),
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || !payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || !payload.tenantSlug) {
+    throw new Error(payload?.error?.message || `guest enrolment returned HTTP ${response.status}`);
+  }
+  const binding = {
+    nodeKey: payload.nodeKey,
+    computeReference: payload.computeReference,
+    projectKey: payload.projectKey,
+    environmentKey: payload.environmentKey,
+    tenantSlug: payload.tenantSlug
+  };
+  persistGuestBinding(options.statePath, binding);
+  if (options.consume)
+    await options.consume();
+  else if (options.tokenPath)
+    unlinkSync(options.tokenPath);
+  return binding;
+}
+export {
+  loadGuestBinding,
+  enrolGuestIdentity
+};

package/dist/guest-enrolment.test.d.ts

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

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { type NodeKeyPair } from '@forgezero/runtime/identity';
 import { startAgent, type AgentOptions, type AttestationSource } from './socket';
 import type { SecretCache } from './cache';
 /**
- * fz-agent — runs on the metal, driven over SSH before the platform exists and
+ * fz-agent — runs inside managed compute, driven locally before the platform exists and
  * over HTTPS after it does. One implementation, two front doors: bootstrap is
  * not a special case, it is the general case run first, because a tenant's own
  * bare metal has no ForgeZero on it either.
@@ -17,7 +17,7 @@ import type { SecretCache } from './cache';
  * ## What it serves
  *
  * A unix socket that SIGNS and never surrenders the key. `@forgezero/vault`
- * discovers `/run/forgezero.sock` and prefers it over `FORGEZERO_API_KEY`, so
+ * discovers `/run/forgezero/vault.sock` and prefers it over `FORGEZERO_API_KEY`, so
  * moving an application onto managed compute means deleting an environment
  * variable rather than changing a line of code — and a machine that used to hold
  * a signing seed now holds nothing an attacker can take.
@@ -25,11 +25,34 @@ import type { SecretCache } from './cache';
  * That preference was implemented in the client long before anything listened.
  * See `socket.ts` for why it signs rather than handing back a token.
  */
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.1.10";
 export { startAgent, handleRequest } from './socket';
 export type { AgentOptions, AttestationSource, Request, Response } from './socket';
 export { createSecretCache, CacheError } from './cache';
 export type { SecretCache, CacheOptions } from './cache';
+export { createDeploymentManager, DeploymentError } from './deployment';
+export type { DeploymentManager, DeploymentOptions, DeploymentRequest, DeploymentResult } from './deployment';
+export { DEFAULT_CONTROL_SOCKET, requestControl, startControlServer } from './control';
+export { pullDeploymentOnce, startDeploymentPull } from './deployment-pull';
+export type { DeploymentPullOptions, RemoteDeploymentClaim, PullResult } from './deployment-pull';
+export { readStaticDeploymentState, writeStaticDeploymentState, startStaticDeploymentWatch } from './deployment-watch';
+export type { StaticDeploymentState, StaticDeploymentWatchOptions } from './deployment-watch';
+export { pullProvisioningOnce, startProvisioningPull } from './provisioning-pull';
+export type { CreateRemoteProvisionClaim, ProvisioningPullOptions, RemoteProvisionClaim, ProvisionPullResult, ProvisionRunner, ProvisionResult } from './provisioning-pull';
+export { enrolGuestIdentity, loadGuestBinding } from './guest-enrolment';
+export type { GuestBinding, GuestEnrolmentOptions } from './guest-enrolment';
+export { createNodeVaultCache, startNodeVaultSync, tenantNodeApiUrl } from './node-vault';
+export type { NodeVaultOptions, NodeVaultSyncOptions } from './node-vault';
+export { allocateAddress, allocateCpuPool, cloudInit, guestNameFor, provisionMetalGuest, removeMetalGuest } from './metal-provision';
+export { validateMetalProfile } from './metal-provision';
+export type { GuestManifest, MetalCommandResult, MetalCpuPool, MetalExec, MetalProvisionProfile } from './metal-provision';
+export { DEFAULT_METAL_HELPER_SOCKET, requestMetalProvision, startMetalHelper } from './metal-helper-socket';
+export { DEFAULT_DEPLOYMENT_RUNNER_SOCKET, requestDeploymentCommand, startDeploymentRunner } from './deployment-runner';
+export { createSnpAttestationSource } from './snp-attestation';
+export type { SnpAttestationOptions } from './snp-attestation';
+export { attestNodeOnce, startNodeAttestation } from './attestation-client';
+export type { NodeAttestationOptions } from './attestation-client';
+export { applyMetalIsolation, metalGuestSliceUnit, metalHousekeepingDropIn } from './metal-isolation';
 /**
  * The node seed, on disk, owner-only.
  *
@@ -42,6 +65,10 @@ export declare function loadOrCreateSeed(path: string): Uint8Array;
 export interface AgentConfig {
     socketPath?: string;
     seedPath?: string;
+    /** Prefer this already-unsealed systemd credential over a persistent file. */
+    seedCredential?: string;
+    /** Injected by tests or an embedding process; never persisted by the agent. */
+    seed?: Uint8Array;
     /** As the platform knows this node. Absent before enrolment. */
     nodeKey?: string;
     attestation?: AttestationSource;
@@ -70,8 +97,26 @@ export interface AgentConfig {
  * A tenant's application ships with `@forgezero/vault` and cannot be asked to
  * follow a path this repository moved.
  */
-export declare const DEFAULT_SOCKET_PATH = "/run/forgezero.sock";
+export declare const DEFAULT_SOCKET_PATH = "/run/forgezero/vault.sock";
 export declare const DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
+export declare const DEFAULT_SEED_CREDENTIAL = "agent-seed";
+export declare const DEFAULT_ENROLMENT_STATE_PATH = "/var/lib/forgezero/enrolment.json";
+/**
+ * Read a systemd credential made available only to this unit.
+ *
+ * `CREDENTIALS_DIRECTORY` is a private, read-only tmpfs populated by PID 1.
+ * The encrypted blob remains host-bound on disk and this plaintext disappears
+ * with the service. A configured credential never falls back to a disk file:
+ * doing so would turn a missing security control into a silent downgrade.
+ */
+export declare function loadSeedCredential(name?: string, directory?: string | undefined): Uint8Array;
+/** Read one text credential from PID 1's private tmpfs, never from an env value. */
+export declare function loadTextCredential(name: string, directory?: string | undefined): string;
+/** Explicit allow-list over systemd credentials exposed to checked-in pipeline steps. */
+export declare function createSystemdDeploymentSecrets(names: string | undefined, directory?: string | undefined): {
+    has(name: string): boolean;
+    get(name: string): Promise<string>;
+} | undefined;
 /**
  * Bring the agent up.
  *
@@ -83,4 +128,5 @@ export declare function runAgent(config?: AgentConfig): {
     server: ReturnType<typeof startAgent>;
     keys: NodeKeyPair;
     nodeKey: string;
+    setCache(cache: SecretCache): void;
 };

package/dist/metal-helper-socket.d.ts

@@ -0,0 +1,15 @@
+import { type Server } from 'node:net';
+import { type MetalExec, type MetalProvisionProfile } from './metal-provision';
+import type { ProvisionResult, RemoteProvisionClaim } from './provisioning-pull';
+export declare const DEFAULT_METAL_HELPER_SOCKET = "/run/forgezero-metal/helper.sock";
+export declare const spawnMetalCommand: MetalExec;
+/** Root-owned server. Its fixed profile is never selectable by the caller. */
+export declare function startMetalHelper(options: {
+    profile: MetalProvisionProfile;
+    socketPath?: string;
+    exec?: MetalExec;
+}): {
+    server: Server;
+    stop(): Promise<void>;
+};
+export declare function requestMetalProvision(claim: RemoteProvisionClaim, socketPath?: string): Promise<ProvisionResult>;