@forgezero/agent 0.1.0 → 0.1.9

package/dist/metal-provision.test.d.ts

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

package/dist/node-vault.d.ts

@@ -0,0 +1,24 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import { type SecretCache } from './cache';
+import { type SignedNodeHttpOptions } from './signed-node-http';
+export interface NodeVaultOptions extends Omit<SignedNodeHttpOptions, 'apiUrl'> {
+    /** Tenant node base, for example https://api.example/api/t/acme. */
+    apiUrl: string;
+    keys: NodeKeyPair;
+    ttlMs?: number;
+    maxStaleMs?: number;
+}
+/** Turn the public API origin into the realm-selected node endpoint. */
+export declare function tenantNodeApiUrl(apiUrl: string, tenantSlug: string): string;
+/** Project/environment selection is server-owned through the compute binding. */
+export declare function createNodeVaultCache(options: NodeVaultOptions): SecretCache;
+export interface NodeVaultSyncOptions {
+    intervalMs?: number;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+/** Poll rotation cursors without overlapping calls; stop waits for the active sync. */
+export declare function startNodeVaultSync(cache: SecretCache, options?: NodeVaultSyncOptions): {
+    stop(): Promise<void>;
+};

package/dist/node-vault.js

@@ -0,0 +1,211 @@
+// src/cache.ts
+class CacheError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CacheError";
+  }
+}
+var DEFAULT_TTL_MS = 60000;
+var DEFAULT_MAX_STALE_MS = 300000;
+function createSecretCache(options) {
+  const entries = new Map;
+  const now = options.now ?? (() => Date.now());
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const maxStaleMs = options.maxStaleMs ?? DEFAULT_MAX_STALE_MS;
+  let cursor = 0;
+  let replicated = false;
+  let lastSyncOkMs = now();
+  const loadScope = async () => {
+    if (!options.list)
+      return { loaded: 0, failed: [] };
+    const names = await options.list();
+    const failed = [];
+    let loaded = 0;
+    for (const name of names) {
+      try {
+        const result = await options.fetch(name);
+        entries.set(name, { value: result.value, version: result.version, fetchedAtMs: now() });
+        loaded += 1;
+      } catch {
+        failed.push(name);
+      }
+    }
+    replicated = true;
+    return { loaded, failed };
+  };
+  return {
+    names: () => [...entries.keys()],
+    get replica() {
+      return replicated;
+    },
+    load: loadScope,
+    get cursor() {
+      return cursor;
+    },
+    async get(name) {
+      const staleFor = now() - lastSyncOkMs;
+      if (staleFor > maxStaleMs) {
+        throw new CacheError("STALE", `Synchronisation has not succeeded for ${Math.round(staleFor / 1000)}s, so this ` + "cache can no longer vouch for what it holds. Refusing rather than serving a value " + "that may already be revoked.");
+      }
+      const cached = entries.get(name);
+      if (cached && now() - cached.fetchedAtMs < ttlMs)
+        return cached.value;
+      let fetched;
+      try {
+        fetched = await options.fetch(name);
+      } catch (cause) {
+        if (cached)
+          return cached.value;
+        throw new CacheError("FETCH_FAILED", cause instanceof Error ? cause.message : `Could not fetch ${name}.`);
+      }
+      entries.set(name, { ...fetched, fetchedAtMs: now() });
+      return fetched.value;
+    },
+    async sync() {
+      const result = await options.changes(cursor);
+      if (result.resync) {
+        const dropped = [...entries.keys()];
+        entries.clear();
+        cursor = 0;
+        lastSyncOkMs = now();
+        if (options.list)
+          await loadScope();
+        return { invalidated: dropped, cursor: 0, resync: true };
+      }
+      const invalidated = [];
+      for (const name of result.changed) {
+        if (entries.delete(name))
+          invalidated.push(name);
+      }
+      cursor = result.version;
+      lastSyncOkMs = now();
+      return { invalidated, cursor, resync: false };
+    },
+    clear() {
+      entries.clear();
+      cursor = 0;
+    },
+    staleForMs: () => now() - lastSyncOkMs
+  };
+}
+
+// src/signed-node-http.ts
+import { signRequest } from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+var signatureHeader = (envelope) => Buffer.from(JSON.stringify({
+  timestamp: envelope.timestamp,
+  nonce: envelope.nonce,
+  edSignature: envelope.edSignature,
+  mlDsaSignature: envelope.mlDsaSignature
+})).toString("base64url");
+async function postSignedNode(options, path, body) {
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const raw = JSON.stringify(body);
+  const envelope = signRequest(options.keys, options.nodeKey, {
+    method: "POST",
+    path: url.pathname,
+    query: "",
+    body: raw
+  });
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-fz-node": options.nodeKey,
+      "x-fz-signature": signatureHeader(envelope)
+    },
+    body: raw,
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    const failure = payload;
+    const reason = failure ? failure.error?.message ?? failure.message : undefined;
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+  }
+  return payload;
+}
+
+// src/node-vault.ts
+function tenantNodeApiUrl(apiUrl, tenantSlug) {
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(tenantSlug))
+    throw new Error("tenant slug is malformed");
+  const url = new URL(apiUrl);
+  url.pathname = `/api/t/${encodeURIComponent(tenantSlug)}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function createNodeVaultCache(options) {
+  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
+  return createSecretCache({
+    ttlMs: options.ttlMs,
+    maxStaleMs: options.maxStaleMs,
+    list: async () => {
+      const payload = await post("list", {});
+      if (!Array.isArray(payload.names) || payload.names.some((name) => typeof name !== "string")) {
+        throw new Error("node vault list response is malformed");
+      }
+      return payload.names;
+    },
+    fetch: async (name) => {
+      const payload = await post("read", { name });
+      if (typeof payload.value !== "string" || !Number.isSafeInteger(payload.version)) {
+        throw new Error("node vault read response is malformed");
+      }
+      return { value: payload.value, version: payload.version };
+    },
+    changes: async (since) => {
+      const payload = await post("changes", { since });
+      if (!Number.isSafeInteger(payload.version) || !Array.isArray(payload.changed) || payload.changed.some((name) => typeof name !== "string"))
+        throw new Error("node vault changes response is malformed");
+      return { version: payload.version, changed: payload.changed, resync: payload.resync };
+    }
+  });
+}
+function startNodeVaultSync(cache, options = {}) {
+  const interval = Math.max(1000, options.intervalMs ?? 30000);
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  let stopped = false;
+  let timer;
+  let active = null;
+  const schedule = () => {
+    if (!stopped)
+      timer = setTimer(tick, interval);
+  };
+  const tick = () => {
+    if (stopped || active)
+      return;
+    active = cache.sync().then((result) => options.onEvent?.("synced", result)).catch((cause) => options.onEvent?.("sync-failed", cause)).finally(() => {
+      active = null;
+      schedule();
+    });
+  };
+  schedule();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    }
+  };
+}
+export {
+  tenantNodeApiUrl,
+  startNodeVaultSync,
+  createNodeVaultCache
+};

package/dist/node-vault.test.d.ts

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

package/dist/provision.d.ts

@@ -55,8 +55,9 @@ export declare const CAPABILITY_CHECKS: Record<string, Check> & {
     snpGuest: Check;
     systemd: Check;
     bun: Check;
+    python: Check;
 };
-export type CapabilityId = 'snpGuest' | 'systemd' | 'bun';
+export type CapabilityId = 'snpGuest' | 'systemd' | 'bun' | 'python';
 /** The answers, however they were gathered. */
 export type Capabilities = Record<CapabilityId, boolean>;
 /**
@@ -70,14 +71,57 @@ export declare const reasonFor: (mode: AgentMode) => string;
 export interface UnitOptions {
     mode: AgentMode;
     socketPath: string;
-    seedPath: string;
+    /** Legacy/dev fallback only. Production uses `seedCredentialPath`. */
+    seedPath?: string;
+    /** Host-bound encrypted credential loaded by systemd for this unit only. */
+    seedCredentialPath?: string;
+    gitCredentialPath?: string;
+    /** Non-secret OpenSSH public half reported during compute enrolment. */
+    gitPublicKeyPath?: string;
+    /** Generate a unique Ed25519 deploy identity on this machine when absent. */
+    generateGitIdentity?: boolean;
+    controlSocketPath?: string;
+    repository?: string;
+    branch?: string;
+    role?: string;
+    deployRoot?: string;
+    publicApiUrl?: string;
+    /** Non-secret phase values, named explicitly instead of inheriting the unit environment. */
+    deploymentEnvironment?: Record<string, string>;
+    /** Pipeline secret name -> encrypted systemd credential source. */
+    deploymentCredentials?: Record<string, string>;
+    /** Enable authenticated outbound deployment claims after enrolment. */
+    pullDeployments?: boolean;
     /** Where `fz-agent` ended up. `bun add -g` puts it on PATH. */
     binPath?: string;
+    /** Package-owned binary copied to binPath before hardened units start. */
+    sourceBinPath?: string;
     user?: string;
     apiUrl?: string;
     project?: string;
     environment?: string;
+    /** One-time direct-compute enrolment, consumed before the long-running agent. */
+    enrolTokenSourcePath?: string;
+    enrolTokenCredentialPath?: string;
+    enrolStatePath?: string;
+    nodeLabel?: string;
 }
+export declare const DEPLOYMENT_RUNNER_USER = "forgezero-runner";
+export declare const DEPLOYMENT_GROUP = "forgezero-deploy";
+export declare const DEPLOYMENT_RUNNER_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.service";
+export declare const DEPLOYMENT_RUNNER_SOCKET_UNIT_PATH = "/etc/systemd/system/forgezero-deploy-runner.socket";
+export declare const DEPLOYMENT_RUNNER_SOCKET = "/run/forgezero-deploy/runner.sock";
+export declare const ENROLMENT_UNIT_PATH = "/etc/systemd/system/forgezero-agent-enrol.service";
+/**
+ * Exchange a tenant-issued one-time capability before the durable agent starts.
+ *
+ * The main unit never names the capability, so deleting the encrypted blob
+ * after success cannot break a later reboot. A durable non-secret binding makes
+ * the oneshot skip; a failed exchange keeps the encrypted token for a retry.
+ */
+export declare function agentEnrolmentUnit(options: UnitOptions): string;
+export declare function deploymentRunnerSocketUnit(agentUser: string): string;
+export declare function deploymentRunnerUnit(options: Pick<UnitOptions, 'binPath' | 'deployRoot'>): string;
 /**
  * A systemd unit for the agent.
  *
@@ -100,6 +144,10 @@ export interface ProvisionPlan {
     reason: string;
     unitPath: string;
     unit: string;
+    auxiliaryUnits: readonly {
+        path: string;
+        unit: string;
+    }[];
     socketPath: string;
     user: string;
     steps: readonly Step[];