@forgezero/agent 0.1.18 → 0.1.20

package/README.md

@@ -90,10 +90,11 @@ evidence: report acquisition and AMD-rooted measurement verification still have
 to cross the production fleet. Until then the node is honestly `enrolled`; the
 Agent never manufactures an attestation-shaped fallback.
 
-Every tenant Vault sync request uses the same hybrid signature codec as an
-external API key and signs its one-use hybrid ML-KEM-768 + X25519 response key.
-Vault values are AES-256-GCM sealed to that request before crossing the edge;
-there is no Ed25519-only or plaintext-response downgrade.
+Every Agent request uses the same hybrid signature codec as an external API key
+and signs its one-use hybrid ML-KEM-768 + X25519 response key. Vault replication,
+deployment claims, attestation and metal provisioning responses are AES-256-GCM
+sealed to that request before crossing the edge; there is no Ed25519-only or
+successful plaintext-response downgrade.
 
 The first guest enrolment uses the same contract before the identity exists in
 the database: the guest signs the exact token and public-key body with both keys
@@ -103,23 +104,19 @@ acknowledgement. The short-lived token is therefore not an unsigned Agent path.
 ## 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
 ```
 
-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.
+The application Vault socket never accepts identity, signing, attestation,
+commands or deployment definitions. The Agent signs and attests only inside its
+own outbound clients. Otherwise a compromised application could ask for a valid
+node signature over a deployment or whole-project sync request and impersonate
+the Agent without ever extracting its key. Deployment enters through the
+root-only control socket or signed outbound claim path, then the deployment
+manager validates the checked-in definition and submits it to the common keyed
+queue.
 
 ## Deployment definitions
 
@@ -139,7 +136,8 @@ code, and only an awaited successful pipeline writes `deployed`. An expired
 claim can be recovered; its stale token cannot renew or finish.
 
 The same package also runs the identity-only Metal Agent. It initiates outbound
-signed HTTPS to pull only claims assigned to its enrolled hostname, then passes
+hybrid-signed HTTPS and requires request-bound PQ-sealed responses while pulling
+only claims assigned to its enrolled hostname, then passes
 the fixed claim over a local Unix socket to a narrowly privileged root helper.
 The helper can materialize the audited QEMU profile; it cannot clone a project,
 read Vault data, accept arbitrary commands, or retain tenant credentials. Root

package/dist/cache.d.ts

@@ -60,7 +60,8 @@ export interface CacheOptions {
      * 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
+     * Present means the agent pulls the whole bound project across every
+     * environment at startup and
      * on every resync, so an application reads with no round trip and keeps
      * working while the platform is unreachable.
      *

package/dist/fz-agent.js

@@ -123,19 +123,19 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
-async function postSignedNode(options, path, body, sealedResponse = false) {
+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 recipient = sealedResponse ? generateResponseRecipient() : undefined;
+  const recipient = generateResponseRecipient();
   const envelope = signRequest(options.keys, options.nodeKey, {
     method: "POST",
     path: url.pathname,
     query: "",
     body: raw,
-    responseKey: recipient?.publicKey
+    responseKey: recipient.publicKey
   });
   const signature = encodeSignatureHeader(envelope);
   const response = await (options.fetch ?? globalThis.fetch)(url, {
@@ -144,7 +144,7 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
       "content-type": "application/json",
       "x-fz-node": options.nodeKey,
       "x-fz-signature": signature,
-      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
     },
     body: raw,
     signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
@@ -155,14 +155,11 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
     throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
   }
-  if (recipient) {
-    try {
-      return await openResponse(recipient.secretKey, signature, payload);
-    } catch {
-      throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
-    }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
   }
-  return payload;
 }
 
 // src/node-vault.ts
@@ -194,7 +191,7 @@ function tenantNodeApiUrl(apiUrl, tenantSlug) {
   return url.toString().replace(/\/$/, "");
 }
 function createNodeVaultCache(options) {
-  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body, true);
+  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
   return createSecretCache({
     ttlMs: options.ttlMs,
     maxStaleMs: options.maxStaleMs,
@@ -255,6 +252,13 @@ function startNodeVaultSync(cache, options = {}) {
 }
 
 // src/socket.ts
+var APPLICATION_VAULT_OPS = new Set(["get", "held", "sync"]);
+function handleApplicationRequest(options, request) {
+  if (!APPLICATION_VAULT_OPS.has(request?.op)) {
+    return Promise.resolve(refuse("APP_OPERATION_REFUSED", "The application Vault socket serves scoped replica reads only; node signing and attestation are internal."));
+  }
+  return handleRequest(options, request);
+}
 var MAX_LINE_BYTES = 64 * 1024;
 function handleRequest(options, request) {
   switch (request?.op) {
@@ -390,7 +394,7 @@ async function respond(options, socket, line) {
     return;
   let response;
   try {
-    response = await handleRequest(options, JSON.parse(line));
+    response = await handleApplicationRequest(options, JSON.parse(line));
   } catch (cause) {
     response = refuse("MALFORMED", cause instanceof Error ? cause.message : "Malformed request.");
   }
@@ -1209,7 +1213,7 @@ async function enrolGuestIdentity(options) {
       ed25519: options.keys.ed25519.publicKey,
       mlDsa: options.keys.mlDsa.publicKey
     }
-  }, true);
+  });
   if (!payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || payload.realm !== "platform" && (payload.realm !== "tenant" || !payload.tenantSlug)) {
     throw new Error(payload?.error?.message || "guest enrolment response was not accepted");
   }
@@ -2711,7 +2715,7 @@ async function applyMetalIsolation(profile, exec = defaultExec) {
 }
 
 // src/version.ts
-var VERSION = "0.1.18";
+var VERSION = "0.1.20";
 
 // src/index.ts
 function loadOrCreateSeed(path) {
@@ -3215,6 +3219,7 @@ export {
   loadOrCreateSeed,
   loadGuestBinding,
   handleRequest,
+  handleApplicationRequest,
   guestNameFor,
   enrolGuestIdentity,
   createSystemdDeploymentSecrets,

package/dist/fz.js

@@ -774,7 +774,7 @@ async function resolveIdentity(selector, socketPath) {
 }
 
 // src/version.ts
-var VERSION = "0.1.18";
+var VERSION = "0.1.20";
 
 // src/cli/index.ts
 var DEFAULT_MODE = THRESHOLD_MODES[0].id;

package/dist/guest-enrolment.js

@@ -28,19 +28,19 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
-async function postSignedNode(options, path, body, sealedResponse = false) {
+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 recipient = sealedResponse ? generateResponseRecipient() : undefined;
+  const recipient = generateResponseRecipient();
   const envelope = signRequest(options.keys, options.nodeKey, {
     method: "POST",
     path: url.pathname,
     query: "",
     body: raw,
-    responseKey: recipient?.publicKey
+    responseKey: recipient.publicKey
   });
   const signature = encodeSignatureHeader(envelope);
   const response = await (options.fetch ?? globalThis.fetch)(url, {
@@ -49,7 +49,7 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
       "content-type": "application/json",
       "x-fz-node": options.nodeKey,
       "x-fz-signature": signature,
-      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
     },
     body: raw,
     signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
@@ -60,14 +60,11 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
     throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
   }
-  if (recipient) {
-    try {
-      return await openResponse(recipient.secretKey, signature, payload);
-    } catch {
-      throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
-    }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
   }
-  return payload;
 }
 
 // src/guest-enrolment.ts
@@ -121,7 +118,7 @@ async function enrolGuestIdentity(options) {
       ed25519: options.keys.ed25519.publicKey,
       mlDsa: options.keys.mlDsa.publicKey
     }
-  }, true);
+  });
   if (!payload?.ok || payload.nodeKey !== options.nodeKey || !payload.computeReference || !payload.projectKey || !payload.environmentKey || payload.realm !== "platform" && (payload.realm !== "tenant" || !payload.tenantSlug)) {
     throw new Error(payload?.error?.message || "guest enrolment response was not accepted");
   }

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';
 export { VERSION } from './version';
-export { startAgent, handleRequest } from './socket';
+export { startAgent, handleRequest, handleApplicationRequest } from './socket';
 export type { AgentOptions, AttestationSource, Request, Response } from './socket';
 export { createSecretCache, CacheError } from './cache';
 export type { SecretCache, CacheOptions } from './cache';

package/dist/node-vault.js

@@ -108,19 +108,19 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
-async function postSignedNode(options, path, body, sealedResponse = false) {
+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 recipient = sealedResponse ? generateResponseRecipient() : undefined;
+  const recipient = generateResponseRecipient();
   const envelope = signRequest(options.keys, options.nodeKey, {
     method: "POST",
     path: url.pathname,
     query: "",
     body: raw,
-    responseKey: recipient?.publicKey
+    responseKey: recipient.publicKey
   });
   const signature = encodeSignatureHeader(envelope);
   const response = await (options.fetch ?? globalThis.fetch)(url, {
@@ -129,7 +129,7 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
       "content-type": "application/json",
       "x-fz-node": options.nodeKey,
       "x-fz-signature": signature,
-      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
     },
     body: raw,
     signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
@@ -140,14 +140,11 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
     throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
   }
-  if (recipient) {
-    try {
-      return await openResponse(recipient.secretKey, signature, payload);
-    } catch {
-      throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
-    }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
   }
-  return payload;
 }
 
 // src/node-vault.ts
@@ -179,7 +176,7 @@ function tenantNodeApiUrl(apiUrl, tenantSlug) {
   return url.toString().replace(/\/$/, "");
 }
 function createNodeVaultCache(options) {
-  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body, true);
+  const post = (operation, body) => postSignedNode(options, `v1/node/vault/${operation}`, body);
   return createSecretCache({
     ttlMs: options.ttlMs,
     maxStaleMs: options.maxStaleMs,

package/dist/provisioning-pull.js

@@ -15,19 +15,19 @@ class SignedNodeHttpError extends Error {
     this.name = "SignedNodeHttpError";
   }
 }
-async function postSignedNode(options, path, body, sealedResponse = false) {
+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 recipient = sealedResponse ? generateResponseRecipient() : undefined;
+  const recipient = generateResponseRecipient();
   const envelope = signRequest(options.keys, options.nodeKey, {
     method: "POST",
     path: url.pathname,
     query: "",
     body: raw,
-    responseKey: recipient?.publicKey
+    responseKey: recipient.publicKey
   });
   const signature = encodeSignatureHeader(envelope);
   const response = await (options.fetch ?? globalThis.fetch)(url, {
@@ -36,7 +36,7 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
       "content-type": "application/json",
       "x-fz-node": options.nodeKey,
       "x-fz-signature": signature,
-      ...recipient ? { [RESPONSE_KEY_HEADER]: recipient.publicKey } : {}
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
     },
     body: raw,
     signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
@@ -47,14 +47,11 @@ async function postSignedNode(options, path, body, sealedResponse = false) {
     const reason = failure ? failure.error?.message ?? failure.message : undefined;
     throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
   }
-  if (recipient) {
-    try {
-      return await openResponse(recipient.secretKey, signature, payload);
-    } catch {
-      throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
-    }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
   }
-  return payload;
 }
 
 // src/provisioning-pull.ts

package/dist/signed-node-http.d.ts

@@ -11,4 +11,4 @@ export declare class SignedNodeHttpError extends Error {
     constructor(status: number, message: string);
 }
 /** One implementation of the hybrid-signed machine HTTP contract. */
-export declare function postSignedNode<T>(options: SignedNodeHttpOptions, path: string, body: object, sealedResponse?: boolean): Promise<T>;
+export declare function postSignedNode<T>(options: SignedNodeHttpOptions, path: string, body: object): Promise<T>;

package/dist/socket.d.ts

@@ -2,7 +2,7 @@ import { type Server } from 'node:net';
 import { signRequest, type NodeKeyPair } from '@forgezero/runtime/identity';
 import type { SecretCache } from './cache';
 /**
- * The signing socket — why the application on managed compute holds nothing.
+ * The application Vault socket — why managed code holds no remote credential.
  *
  * `@forgezero/vault` discovers `/run/forgezero/vault.sock` and prefers it over
  * `FORGEZERO_API_KEY`, so moving an app onto managed compute is DELETING an
@@ -10,20 +10,14 @@ import type { SecretCache } from './cache';
  * for a long time nothing was: the client knew how to prefer the socket and the
  * agent was a version constant.
  *
- * ## The key never leaves
+ * ## The node identity never becomes an application signing oracle
  *
- * There is no `getKey` operation and there is deliberately no way to add one:
- * the socket signs, and signing is all it does. An application that could ask
- * for the key is an application that holds the key the moment it is compromised,
- * which is the entire difference between this and an API key in the environment.
- *
- * ## Why a signature and not a token
- *
- * A token would have to be handed to the caller, which puts it in a process we
- * do not control, in memory we do not own, for as long as the process lives. A
- * signature is bound to one method, one path and one body digest by
- * `canonicalString`, so a caller that captures one cannot reuse it for anything
- * else — and it expires with the clock-skew window rather than with the process.
+ * The Agent hybrid-signs its own outbound HTTPS requests internally. This
+ * socket never exposes `identity`, `sign` or `attest`: otherwise any tenant
+ * process admitted to the Vault group could ask the Agent to sign a deployment,
+ * heartbeat or whole-project replication request and act as the node without
+ * ever extracting its key. Applications receive only the environment they ask
+ * for from the already-bound, memory-only project replica.
  *
  * ## Peer credentials, not a shared secret
  *
@@ -99,6 +93,8 @@ export type Response = {
         message: string;
     };
 };
+/** The real Unix-socket boundary; privileged machine operations stay in-process. */
+export declare function handleApplicationRequest(options: AgentOptions, request: Request): Promise<Response>;
 /**
  * Produces a hardware attestation report for this guest.
  *

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** One package version shared by both public binaries. Pinned to package.json by tests. */
-export declare const VERSION = "0.1.18";
+export declare const VERSION = "0.1.20";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/agent",
-	"version": "0.1.18",
+	"version": "0.1.20",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",