@forgezero/agent 0.1.19 → 0.1.21

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
@@ -135,13 +136,20 @@ 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
 SSH is an operator-only platform-genesis/recovery path, not the normal tenant
 dispatch mechanism.
 
+Shutdown has one process-wide deadline. New deployment claims and background
+sync stop first, claimed work drains under its lease fence, and only then do the
+queues and application socket close. Vault/attestation calls or a stale local
+socket cannot consume systemd's longer stop timeout: exceeding the Agent deadline
+is reported and exits non-zero instead of being silently killed midway by PID 1.
+
 Repository read authorization is explicit per pipeline: public HTTPS, the
 compute's systemd-sealed SSH deploy key, or a fine-grained HTTPS token selected
 by a project-vault secret name. A signed claim contains the mode and secret name

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,
@@ -1216,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");
   }
@@ -2717,8 +2714,31 @@ async function applyMetalIsolation(profile, exec = defaultExec) {
   }
 }
 
+// src/shutdown.ts
+async function settleWithin(work, timeoutMs, setTimer = setTimeout, clearTimer = clearTimeout) {
+  let timer;
+  try {
+    return await Promise.race([
+      work.then(() => true),
+      new Promise((resolve2) => {
+        timer = setTimer(() => resolve2(false), Math.max(1, timeoutMs));
+        timer.unref?.();
+      })
+    ]);
+  } finally {
+    if (timer)
+      clearTimer(timer);
+  }
+}
+async function closeServerWithin(server, timeoutMs) {
+  const closed = await settleWithin(new Promise((resolve2) => server.close(() => resolve2())), timeoutMs);
+  if (!closed)
+    server.unref();
+  return closed;
+}
+
 // src/version.ts
-var VERSION = "0.1.19";
+var VERSION = "0.1.21";
 
 // src/index.ts
 function loadOrCreateSeed(path) {
@@ -3153,24 +3173,26 @@ if (import.meta.main) {
         return;
       stopping = true;
       console.log(`[agent] ${signal}: stopping deployment intake and draining`);
-      if (control)
-        await new Promise((resolve2) => control.close(() => resolve2()));
       const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
       const deadline = Date.now() + deadlineMs;
+      const remaining = () => Math.max(1, deadline - Date.now());
+      const controlClosed = control ? await settleWithin(new Promise((resolve2) => control.close(() => resolve2())), remaining()) : true;
       const pullDrain = pull?.stop() ?? Promise.resolve();
       const vaultDrain = vaultSync?.stop() ?? Promise.resolve();
       const attestationDrain = attestationLoop?.stop() ?? Promise.resolve();
-      const pullWithinDeadline = pull ? Promise.race([
-        pullDrain.then(() => true),
-        new Promise((resolve2) => setTimeout(() => resolve2(false), deadlineMs))
-      ]) : Promise.resolve(true);
-      const pullDrained = await pullWithinDeadline;
-      await Promise.all([vaultDrain, attestationDrain]);
-      const managerReports = await Promise.all([...new Set(managers.values())].map((manager) => manager.stop(Math.max(1, deadline - Date.now()))));
-      await new Promise((resolve2) => server.close(() => resolve2()));
+      const pullDrained = pull ? await settleWithin(pullDrain, remaining()) : true;
+      const backgroundDrained = await settleWithin(Promise.all([vaultDrain, attestationDrain]), remaining());
+      const managerReports = await Promise.all([...new Set(managers.values())].map((manager) => manager.stop(remaining())));
+      const socketClosed = await closeServerWithin(server, remaining());
       const timedOut = managerReports.some((report) => report.timedOut);
-      console.log(`[agent] drain ${JSON.stringify({ managers: managerReports, pullDrained })}`);
-      process.exit(timedOut || !pullDrained ? 1 : 0);
+      console.log(`[agent] drain ${JSON.stringify({
+        managers: managerReports,
+        controlClosed,
+        pullDrained,
+        backgroundDrained,
+        socketClosed
+      })}`);
+      process.exit(timedOut || !controlClosed || !pullDrained || !backgroundDrained || !socketClosed ? 1 : 0);
     };
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
     process.on("SIGINT", () => void shutdown("SIGINT"));
@@ -3178,19 +3200,24 @@ if (import.meta.main) {
     console.log("[agent] signing/vault mode only; deployment root and pull are not configured");
     if (vaultSync || attestationLoop) {
       let stopping = false;
-      const stop = async () => {
+      const stop = async (signal) => {
         if (stopping)
           return;
         stopping = true;
-        await Promise.all([
+        const deadlineMs = Math.max(1, Number(process.env.FZ_DRAIN_DEADLINE_MS ?? 30000));
+        const deadline = Date.now() + deadlineMs;
+        const remaining = () => Math.max(1, deadline - Date.now());
+        console.log(`[agent] ${signal}: stopping background intake and draining`);
+        const backgroundDrained = await settleWithin(Promise.all([
           vaultSync?.stop() ?? Promise.resolve(),
           attestationLoop?.stop() ?? Promise.resolve()
-        ]);
-        await new Promise((resolve2) => server.close(() => resolve2()));
-        process.exit(0);
+        ]), remaining());
+        const socketClosed = await closeServerWithin(server, remaining());
+        console.log(`[agent] drain ${JSON.stringify({ backgroundDrained, socketClosed })}`);
+        process.exit(backgroundDrained && socketClosed ? 0 : 1);
       };
-      process.on("SIGTERM", () => void stop());
-      process.on("SIGINT", () => void stop());
+      process.on("SIGTERM", () => void stop("SIGTERM"));
+      process.on("SIGINT", () => void stop("SIGINT"));
     }
   }
 }

package/dist/fz.js

@@ -774,7 +774,7 @@ async function resolveIdentity(selector, socketPath) {
 }
 
 // src/version.ts
-var VERSION = "0.1.19";
+var VERSION = "0.1.21";
 
 // 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/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/shutdown.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from 'node:net';
+/**
+ * Wait for one shutdown stage without allowing it to consume systemd's entire
+ * stop timeout. The work is not cancelled: deployment/lease code retains its
+ * own fencing rules, while the caller decides whether an expired global drain
+ * deadline must terminate the process non-zero.
+ */
+export declare function settleWithin(work: Promise<unknown>, timeoutMs: number, setTimer?: typeof setTimeout, clearTimer?: typeof clearTimeout): Promise<boolean>;
+/** Stop accepting local Vault clients, but never let one stale socket defeat shutdown. */
+export declare function closeServerWithin(server: Server, timeoutMs: number): Promise<boolean>;

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/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.19";
+export declare const VERSION = "0.1.21";

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.19",
+	"version": "0.1.21",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",