@forgezero/agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @forgezero/agent
+
+**`fz-agent` — so the application beside it holds no credential at all.**
+
+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
+exists, so an application on a machine running the agent reads its secrets
+because of *where it is*, not because it holds something that could be stolen
+from it.
+
+```bash
+bun add -g @forgezero/agent      # or let `fz agent install` do it
+```
+
+Most people never install this directly:
+
+```bash
+fz agent install --apply         # writes a hardened systemd unit
+```
+
+## What changes for an application
+
+Nothing.
+
+```ts
+import { ForgeZero } from '@forgezero/vault';
+const fz = new ForgeZero({ project: 'altpilot', environment: 'production' });
+await fz.get('STRIPE_KEY');
+```
+
+With no agent, that needs `FORGEZERO_API_KEY` in the environment. With the
+agent, it does not — and the key that would have been in the environment does
+not exist on the box.
+
+## A local copy, not a cache
+
+The agent holds the **whole assigned project + environment**, not just what has
+already been read. That is the difference between surviving an outage and not: a
+cache only has what you fetched, so a secret you have never read is exactly the
+one you cannot get when the platform is unreachable.
+
+The cost, stated rather than buried: a compromised guest exposes everything in
+scope rather than only what was read. It is bounded by the scope the compute is
+assigned to, and by SEV-SNP keeping the host out of guest memory.
+
+**Never on disk.** A cache file would hand an attacker with filesystem access
+every secret this guest has ever held — the exact artefact the design exists to
+remove. A restart re-fetches.
+
+**Invalidated by cursor, not by a timer.** A TTL alone means a rotated secret
+keeps working for the length of the TTL, which is the window rotation exists to
+close. The agent polls a change cursor and drops what moved.
+
+**A stale read is refused, not served.** If sync has not succeeded within the
+staleness bound, `get` fails rather than returning a value it can no longer
+vouch for. An application that receives a revoked credential and succeeds with
+it is worse off than one that receives an error — the error is visible.
+
+## Two postures, decided by the hardware
+
+| | |
+|---|---|
+| `attested` | SEV-SNP guest. The credential is a hardware report, and the platform can refuse a node whose measurement is wrong. |
+| `enrolled` | No SNP. The credential is the enrolment token plus a hybrid Ed25519 + ML-DSA-65 signature. |
+
+Both are real. `enrolled` is still strictly better than an API key in the
+application: the key never leaves the agent, rotation reaches every process, and
+the socket is filesystem-scoped.
+
+## The socket interface
+
+```
+identity   who this node is
+sign       sign a request with the node key
+attest     a hardware report, or a refusal — never a fake
+get        one secret
+sync       what changed since a cursor
+held       what this guest is holding, by name only
+```
+
+`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**
+
+## Licence
+
+MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+deploys.

package/dist/cache.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The agent's secret cache, and why it never touches disk.
+ *
+ * An application on managed compute asks the agent for a value rather than the
+ * platform, so a rotation reaches every process on the box without any of them
+ * holding a credential to fetch it with. That only helps if the cache is
+ * cheaper than the call it replaces AND does not create the very artefact the
+ * design exists to remove.
+ *
+ * ## Memory only, deliberately
+ *
+ * Writing the cache to disk would give an attacker with filesystem access every
+ * secret this guest has ever read — which is precisely the file that does not
+ * exist today, and the entire reason a node holds a signing key instead of a
+ * `.env`. A restart re-fetches. That costs one round trip and removes a class of
+ * compromise; there is no version of "just persist it, it is encrypted" that
+ * survives the key also being on the box.
+ *
+ * ## Invalidation is driven by the cursor, not by a timer
+ *
+ * A TTL alone means a rotated secret keeps working for the length of the TTL —
+ * which is exactly the window rotation exists to close. `sync()` polls the
+ * platform's `/changes` cursor and drops what moved, so a rotation propagates at
+ * the poll interval regardless of TTL. The TTL is the backstop for the case
+ * where sync itself has stopped, and it is short for that reason.
+ *
+ * ## A stale read is refused, not served
+ *
+ * If sync has not succeeded within the staleness bound, `get` refuses rather
+ * than serving a value it can no longer vouch for. An application that receives
+ * a revoked credential and succeeds with it is worse off than one that receives
+ * an error: the error is visible, the success is not.
+ */
+export declare class CacheError extends Error {
+    readonly code: 'STALE' | 'NOT_CACHED' | 'FETCH_FAILED';
+    constructor(code: 'STALE' | 'NOT_CACHED' | 'FETCH_FAILED', message: string);
+}
+export interface CacheOptions {
+    /**
+     * Fetches one value from the platform. Injected so the cache holds no
+     * transport and a test needs no network.
+     */
+    fetch(name: string): Promise<{
+        value: string;
+        version: number;
+    }>;
+    /**
+     * Names changed since a cursor, and the new cursor.
+     *
+     * `resync` means the caller's cursor is unusable — a restored backup or a
+     * moved clock — and everything is dropped rather than a gap being left
+     * exactly where a rotation was.
+     */
+    changes(since: number): Promise<{
+        version: number;
+        changed: string[];
+        resync?: boolean;
+    }>;
+    /**
+     * Every name in the assigned scope. Present means REPLICA mode.
+     *
+     * Absent means the old behaviour — fetch on demand, hold what was asked for.
+     * Present means the agent pulls the whole project+environment at startup and
+     * on every resync, so an application reads with no round trip and keeps
+     * working while the platform is unreachable.
+     *
+     * That is a deliberate widening of what a compromised guest exposes: not
+     * "whatever this app read" but "everything in scope". It is bounded by the
+     * scope the compute is assigned and by SEV-SNP keeping the host out of guest
+     * memory, and it is the point of the agent — a local copy that survives the
+     * API being down is not a cache, and a cache that only has what you already
+     * fetched does not survive anything.
+     */
+    list?(): Promise<readonly string[]>;
+    /** Backstop for a sync that has stopped. Short on purpose. */
+    ttlMs?: number;
+    /** Refuse to serve anything if sync has not succeeded within this. */
+    maxStaleMs?: number;
+    now?: () => number;
+}
+export declare function createSecretCache(options: CacheOptions): {
+    /** For an operator asking what this guest is holding. Names, never values. */
+    names: () => string[];
+    /** True once the whole scope is resident. False in on-demand mode. */
+    readonly replica: boolean;
+    /**
+     * Load the whole assigned scope into memory.
+     *
+     * Called at startup and again after a `resync`. A resync means the cursor
+     * is unusable, so the alternative is an empty cache that refills lazily —
+     * which is exactly the availability the replica exists to provide, lost at
+     * the moment something already went wrong.
+     */
+    load: () => Promise<{
+        loaded: number;
+        failed: string[];
+    }>;
+    readonly cursor: number;
+    /**
+     * One value, from cache when it is fresh enough to vouch for.
+     *
+     * The staleness check runs BEFORE the cache lookup. Serving a cached value
+     * while sync is broken is the failure this guards, so checking after the
+     * lookup would mean the hit path — the common one — skipped the guard.
+     */
+    get(name: string): Promise<string>;
+    /**
+     * Poll for changes and drop what moved.
+     *
+     * Returns what it invalidated so a caller can log a rotation actually
+     * arriving — "sync ran" and "sync did something" are different facts, and
+     * only the second one tells you rotation works.
+     */
+    sync(): Promise<{
+        invalidated: string[];
+        cursor: number;
+        resync: boolean;
+    }>;
+    /** Drop everything. Used on revocation, and by tests. */
+    clear(): void;
+    /** For the journal: how long since sync last succeeded. */
+    staleForMs: () => number;
+};
+export type SecretCache = ReturnType<typeof createSecretCache>;

package/dist/cache.test.d.ts

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

package/dist/fz-agent.js

@@ -0,0 +1,392 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/index.ts
+import { randomBytes } from "crypto";
+import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync, chmodSync as chmodSync2 } from "fs";
+import { dirname } from "path";
+import { deriveKeysFromSeed } from "@forgezero/runtime/identity";
+import { DEFAULT_SOCKET } from "@forgezero/vault";
+
+// src/socket.ts
+import { createServer } from "net";
+import { chmodSync, existsSync, unlinkSync } from "fs";
+import { signRequest } from "@forgezero/runtime/identity";
+
+// src/pipeline.ts
+class PipelineError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PipelineError";
+  }
+}
+function redact(text, values) {
+  let out = text;
+  for (const value of [...values].sort((a, b) => b.length - a.length)) {
+    if (value.length < 8)
+      continue;
+    out = out.split(value).join("\u2022\u2022\u2022\u2022redacted\u2022\u2022\u2022\u2022");
+  }
+  return out;
+}
+async function runPipeline(options) {
+  const now = options.now ?? (() => Date.now());
+  const { pipeline } = options;
+  let assurance = "enrolled";
+  if (options.attest) {
+    try {
+      await options.attest();
+      assurance = "attested";
+    } catch (cause) {
+      if (pipeline.requireAttestation) {
+        throw new PipelineError("ATTESTATION_FAILED", `${pipeline.name} requires attestation and this machine could not produce one: ${cause.message}`);
+      }
+    }
+  } else if (pipeline.requireAttestation) {
+    throw new PipelineError("ATTESTATION_REQUIRED", `${pipeline.name} requires attestation. This agent has no attestation source, so it cannot run it.`);
+  }
+  const steps = [];
+  let failed = false;
+  for (const step of pipeline.steps) {
+    if (failed && !step.always) {
+      steps.push({ name: step.name, outcome: "skipped", exitCode: null, log: "", durationMs: 0 });
+      continue;
+    }
+    const env = {};
+    const values = [];
+    for (const name of step.secrets ?? []) {
+      try {
+        const value = await options.secret(name);
+        env[name] = value;
+        values.push(value);
+      } catch {
+        throw new PipelineError("SECRET_MISSING", `step "${step.name}" needs ${name}, which is not in this compute's scope.`);
+      }
+    }
+    const started = now();
+    let exitCode;
+    let output;
+    try {
+      const result = await options.exec({ command: step.run, env, timeoutMs: step.timeoutMs });
+      exitCode = result.exitCode;
+      output = result.output;
+    } catch (cause) {
+      exitCode = -1;
+      output = cause.message;
+    }
+    const outcome = exitCode === 0 ? "ok" : "failed";
+    if (outcome === "failed")
+      failed = true;
+    steps.push({
+      name: step.name,
+      outcome,
+      exitCode,
+      log: redact(output, values),
+      durationMs: now() - started
+    });
+  }
+  return { pipeline: pipeline.name, ok: !failed, assurance, steps };
+}
+
+// src/socket.ts
+var MAX_LINE_BYTES = 64 * 1024;
+function handleRequest(options, request) {
+  switch (request?.op) {
+    case "identity":
+      return Promise.resolve({
+        ok: true,
+        op: "identity",
+        nodeKey: options.nodeKey,
+        publicKeys: {
+          publicKey: options.keys.ed25519.publicKey,
+          secretKey: "",
+          mlDsa: options.keys.mlDsa.publicKey
+        }
+      });
+    case "sign": {
+      if (typeof request.method !== "string" || typeof request.path !== "string") {
+        return Promise.resolve(refuse("BAD_REQUEST", "A signature needs a method and a path."));
+      }
+      return Promise.resolve({
+        ok: true,
+        op: "sign",
+        envelope: signRequest(options.keys, options.nodeKey, {
+          method: request.method,
+          path: request.path,
+          query: request.query ?? "",
+          body: request.body ?? ""
+        })
+      });
+    }
+    case "get": {
+      if (!options.cache) {
+        return Promise.resolve(refuse("NO_CACHE", "This agent holds no secrets. It signs; it does not serve values."));
+      }
+      if (typeof request.name !== "string" || !request.name) {
+        return Promise.resolve(refuse("BAD_REQUEST", "A read needs a name."));
+      }
+      return options.cache.get(request.name).then((value) => ({ ok: true, op: "get", value })).catch((cause) => refuse(cause.code ?? "READ_FAILED", cause instanceof Error ? cause.message : "Could not read that value."));
+    }
+    case "sync": {
+      if (!options.cache) {
+        return Promise.resolve(refuse("NO_CACHE", "This agent holds no secrets to synchronise."));
+      }
+      return options.cache.sync().then((result) => ({ ok: true, op: "sync", ...result })).catch((cause) => refuse("SYNC_FAILED", cause instanceof Error ? cause.message : "Synchronisation failed."));
+    }
+    case "held": {
+      if (!options.cache) {
+        return Promise.resolve({
+          ok: true,
+          op: "held",
+          names: [],
+          staleForMs: 0
+        });
+      }
+      return Promise.resolve({
+        ok: true,
+        op: "held",
+        names: options.cache.names(),
+        staleForMs: options.cache.staleForMs()
+      });
+    }
+    case "run": {
+      if (!options.cache) {
+        return Promise.resolve(refuse("NO_SCOPE", "This agent holds no project scope, so it cannot run a pipeline."));
+      }
+      if (!options.exec) {
+        return Promise.resolve(refuse("PIPELINE_DISABLED", "This agent was not started with an executor, so it will not run pipelines."));
+      }
+      const cache = options.cache;
+      const attestation = options.attestation;
+      return runPipeline({
+        pipeline: request.pipeline,
+        secret: (name) => cache.get(name),
+        exec: options.exec,
+        attest: attestation ? async () => ({ report: await attestation.report(""), source: attestation.name }) : undefined
+      }).then((result) => ({ ok: true, op: "run", result })).catch((cause) => refuse(cause.code ?? "PIPELINE_FAILED", cause.message));
+    }
+    case "attest": {
+      if (!options.attestation) {
+        return Promise.resolve(refuse("ATTESTATION_UNAVAILABLE", "No attestation source is configured on this guest. Attestation is refused rather " + "than faked, because a caller that believes it verified one when nothing did is " + "worse off than one told plainly it is unavailable."));
+      }
+      const nonce = request.nonce ?? "";
+      if (!nonce) {
+        return Promise.resolve(refuse("NONCE_REQUIRED", "An attestation report needs a nonce."));
+      }
+      return options.attestation.report(nonce).then((report) => ({
+        ok: true,
+        op: "attest",
+        report,
+        source: options.attestation.name
+      })).catch((cause) => refuse("ATTESTATION_FAILED", cause instanceof Error ? cause.message : "Attestation failed."));
+    }
+    default:
+      return Promise.resolve(refuse("UNKNOWN_OP", `No such operation. The socket signs; it does not hand over keys.`));
+  }
+}
+var refuse = (code, message) => ({
+  ok: false,
+  error: { code, message }
+});
+function startAgent(options) {
+  if (existsSync(options.socketPath))
+    unlinkSync(options.socketPath);
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (buffer.length > MAX_LINE_BYTES) {
+        socket.end(`${JSON.stringify(refuse("TOO_LARGE", "Request too large."))}
+`);
+        buffer = "";
+        return;
+      }
+      let newline = buffer.indexOf(`
+`);
+      while (newline !== -1) {
+        const line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        respond(options, socket, line);
+        newline = buffer.indexOf(`
+`);
+      }
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(options.socketPath, () => {
+    chmodSync(options.socketPath, 384);
+  });
+  return server;
+}
+async function respond(options, socket, line) {
+  if (!line.trim())
+    return;
+  let response;
+  try {
+    response = await handleRequest(options, JSON.parse(line));
+  } catch (cause) {
+    response = refuse("MALFORMED", cause instanceof Error ? cause.message : "Malformed request.");
+  }
+  options.record?.({
+    op: JSON.parse(safeOp(line)).op ?? "unknown",
+    outcome: response.ok ? "ok" : "refused",
+    detail: response.ok ? undefined : response.error.code
+  });
+  socket.write(`${JSON.stringify(response)}
+`);
+}
+function safeOp(line) {
+  try {
+    const parsed = JSON.parse(line);
+    return JSON.stringify({ op: typeof parsed.op === "string" ? parsed.op : "unknown" });
+  } catch {
+    return JSON.stringify({ op: "unparseable" });
+  }
+}
+// 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/index.ts
+var VERSION = "0.1.0";
+function loadOrCreateSeed(path) {
+  if (existsSync2(path)) {
+    const seed2 = new Uint8Array(Buffer.from(readFileSync(path, "utf8").trim(), "base64url"));
+    if (seed2.length < 32) {
+      throw new Error(`agent: the seed at ${path} is too short to derive a key from.`);
+    }
+    return seed2;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const seed = new Uint8Array(randomBytes(32));
+  writeFileSync(path, Buffer.from(seed).toString("base64url"), { mode: 384 });
+  chmodSync2(path, 384);
+  return seed;
+}
+var DEFAULT_SOCKET_PATH = DEFAULT_SOCKET;
+var DEFAULT_SEED_PATH = "/var/lib/forgezero/node.seed";
+function runAgent(config = {}) {
+  const seedPath = config.seedPath ?? DEFAULT_SEED_PATH;
+  const keys = deriveKeysFromSeed(loadOrCreateSeed(seedPath));
+  const nodeKey = config.nodeKey ?? keys.ed25519.publicKey;
+  const server = startAgent({
+    socketPath: config.socketPath ?? DEFAULT_SOCKET_PATH,
+    keys,
+    nodeKey,
+    attestation: config.attestation,
+    cache: config.cache,
+    record: config.record
+  });
+  return { server, keys, nodeKey };
+}
+if (import.meta.main) {
+  const { nodeKey } = runAgent({
+    socketPath: process.env.FZ_SOCKET_PATH ?? DEFAULT_SOCKET_PATH,
+    seedPath: process.env.FZ_SEED_PATH ?? DEFAULT_SEED_PATH,
+    nodeKey: process.env.FZ_NODE_KEY,
+    record: (entry) => console.log(`[agent] ${entry.op} ${entry.outcome}${entry.detail ? ` ${entry.detail}` : ""}`)
+  });
+  console.log(`[agent] ${VERSION} signing as ${nodeKey}`);
+}
+export {
+  startAgent,
+  runAgent,
+  loadOrCreateSeed,
+  handleRequest,
+  createSecretCache,
+  VERSION,
+  DEFAULT_SOCKET_PATH,
+  DEFAULT_SEED_PATH,
+  CacheError
+};