@forgezero/agent 0.1.39 → 0.1.40

package/dist/index.d.ts

@@ -2,11 +2,14 @@
 import { type NodeKeyPair } from '@forgezero/runtime/identity';
 import { startAgent, type AgentOptions, type AttestationSource } from './socket';
 import type { SecretCache } from './cache';
+import { type DeploymentCredentialSchema } from './credential-schema';
 export { VERSION } from './version';
 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';
+export { AGENT_CREDENTIAL_LOCATIONS, AGENT_CREDENTIAL_POLICY, METAL_SYSTEMD_CREDENTIALS, credentialBinding, deploymentCredentialSchema } from './credential-schema';
+export type { AgentCredentialLocation, DeploymentCredentialBinding, DeploymentCredentialSchema } from './credential-schema';
 export { createDeploymentManager, DeploymentError } from './deployment';
 export type { DeploymentManager, DeploymentOptions, DeploymentRequest, DeploymentResult } from './deployment';
 export { DEFAULT_CONTROL_SOCKET, requestControl, startControlServer } from './control';
@@ -132,6 +135,36 @@ export declare function createSystemdDeploymentSecrets(names: string | undefined
     has(name: string): boolean;
     get(name: string): Promise<string>;
 } | undefined;
+/**
+ * Resolve deployment secrets from the project-scoped RAM Vault replica first,
+ * then from an explicitly allow-listed systemd credential with the same name.
+ * This is shared by platform and tenant deployment managers.
+ */
+export declare function createDeploymentSecretResolver(schema: DeploymentCredentialSchema, primary: Pick<SecretCache, 'get'> | undefined, fallback: {
+    has(name: string): boolean;
+    get(name: string): Promise<string>;
+} | undefined): Pick<SecretCache, 'get'> | undefined;
+export type InitialVaultReplicaStatus = {
+    state: 'ready';
+    loaded: number;
+    failed: readonly string[];
+} | {
+    state: 'partial';
+    loaded: number;
+    failed: readonly string[];
+} | {
+    state: 'unavailable';
+    loaded: 0;
+    failed: readonly [];
+};
+/**
+ * Attempt the in-memory Vault replica without turning a locked or restarting
+ * Vault into an Agent outage. Deployment reads still try this cache first and
+ * may fall back only through the explicit same-name systemd schema. The sync
+ * loop remains active and promotes the cache to a complete replica once Vault
+ * is available again.
+ */
+export declare function initializeVaultReplica(cache: Pick<SecretCache, 'load'>): Promise<InitialVaultReplicaStatus>;
 /**
  * Bring the agent up.
  *

package/dist/metal-bootstrap.js

@@ -293,7 +293,7 @@ function systemdAgentEgressDirectives(loopbackTcpPorts = []) {
 }
 
 // src/version.ts
-var VERSION = "0.1.39";
+var VERSION = "0.1.40";
 
 // src/metal-bootstrap.ts
 var PROFILE_PATH = "/etc/forgezero/metal.json";

package/dist/platform-bootstrap-runtime.d.ts

@@ -82,6 +82,8 @@ export interface ApiRuntimeRenderOptions {
     greenPort: number;
     collectorUnit: string;
     credentials: SystemdCredentialSpec[];
+    /** Root-owned calibration override, loaded after the ordinary shared environment. */
+    capacityEnvironmentFile?: string;
 }
 export declare function renderPlatformApiUnits(input: ApiRuntimeRenderOptions): {
     template: string;
@@ -90,6 +92,8 @@ export declare function renderPlatformApiUnits(input: ApiRuntimeRenderOptions):
 export declare function renderPlatformNginx(input: {
     publicPort: number;
     initialSlotPort: number;
+    concurrencyLimit?: number;
+    workerDrainSeconds?: number;
 }): {
     upstream: string;
     site: string;
@@ -109,6 +113,7 @@ export interface PlatformActivationConfig {
     greenPort: number;
     healthPath: string;
     keepReleases: number;
+    drainDeadlineMs?: number;
 }
 /**
  * Render the fixed privilege boundary used by the credential-free deployment

package/dist/platform-bootstrap-runtime.js

@@ -218,6 +218,8 @@ function renderPlatformApiUnits(input) {
     throw new Error("Blue and green ports must differ.");
   const credentials = input.credentials.map((credential) => `LoadCredentialEncrypted=${credential.name}:${credential.encryptedPath}`).join(`
 `);
+  const capacityEnvironment = input.capacityEnvironmentFile ? `EnvironmentFile=-${input.capacityEnvironmentFile}
+` : "";
   const template = `[Unit]
 Description=ForgeZero (%i slot)
 After=network-online.target ${input.collectorUnit}
@@ -230,7 +232,7 @@ WorkingDirectory=${input.slotsDirectory}/%i
 Environment=NODE_ENV=production
 Environment=FZ_SLOT=%i
 EnvironmentFile=${input.sharedEnvironmentFile}
-${credentials}
+${capacityEnvironment}${credentials}
 ExecStart=/usr/local/bin/bun run ${input.slotsDirectory}/%i/src/index.ts
 Restart=always
 RestartSec=2
@@ -266,16 +268,24 @@ Environment=PORT=${input.greenPort}
 function renderPlatformNginx(input) {
   boundedInteger("publicPort", input.publicPort, 1024, 65535);
   boundedInteger("initialSlotPort", input.initialSlotPort, 1024, 65535);
+  const concurrencyLimit = boundedInteger("concurrencyLimit", input.concurrencyLimit ?? 256, 1, 1e6);
+  boundedInteger("workerDrainSeconds", input.workerDrainSeconds ?? 35, 1, 300);
   if (input.publicPort === input.initialSlotPort)
     throw new Error("Edge and slot ports must differ.");
   return {
     upstream: `upstream forgezero { server 127.0.0.1:${input.initialSlotPort}; }
 `,
-    site: `server {
+    site: `limit_conn_zone $server_name zone=forgezero_admission:10m;
+map $http_upgrade $forgezero_connection { default upgrade; '' close; }
+map $limit_conn_status $forgezero_retry_after { default ''; REJECTED 1; REJECTED_DRY_RUN 1; }
+server {
   listen 127.0.0.1:${input.publicPort};
   server_name _;
-  location ^~ /api/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
-  location ^~ /v1/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }
+  limit_conn forgezero_admission ${concurrencyLimit};
+  limit_conn_status 503;
+  add_header Retry-After $forgezero_retry_after always;
+  location ^~ /api/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $forgezero_connection; proxy_read_timeout 3600s; }
+  location ^~ /v1/ { proxy_pass http://forgezero; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto https; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $forgezero_connection; proxy_read_timeout 3600s; }
   location / { return 404; }
 }
 `
@@ -301,6 +311,7 @@ function renderPlatformActivationFiles(input) {
   if (input.bluePort === input.greenPort)
     throw new Error("Activation slot ports must differ.");
   boundedInteger("keepReleases", input.keepReleases, 2, 100);
+  const drainDeadlineMs = boundedInteger("drainDeadlineMs", input.drainDeadlineMs ?? 35000, 1000, 300000);
   if (!/^\/[A-Za-z0-9/_-]{1,128}$/.test(input.healthPath) || input.healthPath.includes("..")) {
     throw new Error("Activation health path is malformed.");
   }
@@ -310,7 +321,8 @@ function renderPlatformActivationFiles(input) {
     `FZ_BLUE_PORT=${input.bluePort}`,
     `FZ_GREEN_PORT=${input.greenPort}`,
     `FZ_HEALTH_PATH=${input.healthPath}`,
-    `FZ_KEEP_RELEASES=${input.keepReleases}`
+    `FZ_KEEP_RELEASES=${input.keepReleases}`,
+    `FZ_DRAIN_DEADLINE_MS=${drainDeadlineMs}`
   ].join(`
 `) + `
 `;
@@ -332,7 +344,14 @@ if (( ! healthy )); then systemctl stop "forgezero@\${target}.service" || true;
 upstream=/etc/nginx/conf.d/forgezero-upstream.conf; backup="$(mktemp -p /run forgezero-upstream.XXXXXX)"; [[ -f "$upstream" ]] && cp "$upstream" "$backup" || : >"$backup"
 printf 'upstream forgezero { server 127.0.0.1:%s; }\\n' "$port" >"$upstream"
 if ! nginx -t || ! nginx -s reload; then [[ -s "$backup" ]] && cp "$backup" "$upstream" || rm -f "$upstream"; rm -f "$backup"; systemctl stop "forgezero@\${target}.service" || true; [[ -n "$previous_target_link" && -d "$previous_target_link" ]] && ln -sfn "$previous_target_link" "$target_link" || rm -f "$target_link"; nginx -t >/dev/null 2>&1 && nginx -s reload || true; exit 1; fi
-rm -f "$backup"; printf '%s\\n' "$target" >"$slot_file"; [[ -n "$previous_slot" && "$previous_slot" != "$target" ]] && systemctl stop "forgezero@\${previous_slot}.service" || true
+rm -f "$backup"; printf '%s\\n' "$target" >"$slot_file"
+# New nginx workers select the new slot after reload. Keep the old slot alive
+# while old workers drain in-flight requests and upgraded connections.
+if [[ -n "$previous_slot" && "$previous_slot" != "$target" ]]; then
+  sleep_seconds="$(( (FZ_DRAIN_DEADLINE_MS + 999) / 1000 ))"
+  sleep "$sleep_seconds"
+  systemctl stop "forgezero@\${previous_slot}.service" || true
+fi
 mapfile -t old < <(find "$releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -rn | tail -n "+$((FZ_KEEP_RELEASES + 1))" | cut -d' ' -f2-)
 for path in "\${old[@]}"; do [[ "$path" == "$release" ]] || rm -rf -- "$path"; done
 printf 'promoted %s on %s\\n' "$release" "$target"

package/dist/project-context.js

@@ -105,7 +105,7 @@ function defaultProjectContext(root = process.cwd()) {
       "Update a truth source instead of copying architecture or progress into another document.",
       "Never report a feature as complete without running its declared verification."
     ],
-    nonAuthoritative: ["audit/"]
+    nonAuthoritative: ["docs/audit/"]
   };
 }
 function renderProjectContext(manifest) {

package/dist/provision.js

@@ -93,6 +93,8 @@ var checked = async (run, input, label) => {
   return result;
 };
 async function validateReleaseDirectory(directory, release, run) {
+  chmodSync(directory, 493);
+  chmodSync(join(directory, "dist"), 493);
   const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
   if (manifest.name !== release.package || manifest.version !== release.version) {
     throw new Error("agent update manifest does not match the selected release");
@@ -143,19 +145,19 @@ async function stageAgentRelease(releaseInput, options) {
     if (!timingSafeEqual(actual, expected))
       throw new Error("agent update integrity mismatch");
     writeFileSync(archive, bytes, { mode: 384, flag: "wx" });
-    await checked(run, {
-      command: "/usr/bin/tar",
-      args: [
-        "-xzf",
-        archive,
-        "-C",
-        unpacked,
-        "--strip-components=1",
-        "package/package.json",
-        "package/dist/fz-agent.js",
-        "package/dist/fz.js"
-      ]
-    }, "agent update extraction");
+    for (const [member, relative] of [
+      ["package/package.json", "package.json"],
+      ["package/dist/fz-agent.js", "dist/fz-agent.js"],
+      ["package/dist/fz.js", "dist/fz.js"]
+    ]) {
+      const extracted = await checked(run, {
+        command: "/usr/bin/tar",
+        args: ["-xOzf", archive, member]
+      }, `agent update extraction of ${member}`);
+      const destination = join(unpacked, relative);
+      mkdirSync(dirname(destination), { recursive: true, mode: 448 });
+      writeFileSync(destination, extracted.output, { mode: 384, flag: "wx" });
+    }
     await validateReleaseDirectory(unpacked, release, run);
     if (!existsSync(finalDirectory)) {
       renameSync(unpacked, finalDirectory);
@@ -701,8 +703,8 @@ var UBUNTU_2604_X64 = [
   },
   {
     requirement: { id: "arangodb", version: "3.11.14" },
-    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14' && ` + `! systemctl is-active --quiet arangodb3.service && ` + `! systemctl is-enabled --quiet arangodb3.service`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install; ` + `systemctl disable --now arangodb3.service`
   },
   {
     requirement: { id: "cloudflared", version: "2026.7.3" },
@@ -891,7 +893,7 @@ function requestSoftware(requirements, socketPath = DEFAULT_SOFTWARE_HELPER_SOCK
 }
 
 // src/version.ts
-var VERSION3 = "0.1.39";
+var VERSION3 = "0.1.40";
 
 // src/egress-policy.ts
 import { realpathSync } from "node:fs";

package/dist/software-helper.js

@@ -28,8 +28,8 @@ var UBUNTU_2604_X64 = [
   },
   {
     requirement: { id: "arangodb", version: "3.11.14" },
-    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14' && ` + `! systemctl is-active --quiet arangodb3.service && ` + `! systemctl is-enabled --quiet arangodb3.service`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install; ` + `systemctl disable --now arangodb3.service`
   },
   {
     requirement: { id: "cloudflared", version: "2026.7.3" },

package/dist/software.js

@@ -28,8 +28,8 @@ var UBUNTU_2604_X64 = [
   },
   {
     requirement: { id: "arangodb", version: "3.11.14" },
-    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14'`,
-    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install`
+    check: `arangod --version 2>/dev/null | head -1 | grep -q '3.11.14' && ` + `! systemctl is-active --quiet arangodb3.service && ` + `! systemctl is-enabled --quiet arangodb3.service`,
+    install: `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT; ` + `curl -fsSL 'https://download.arangodb.com/arangodb311/DEBIAN/amd64/arangodb3_3.11.14-1_amd64.deb' -o "$tmp/arangodb.deb"; ` + `echo "${ARANGO_SHA256}  $tmp/arangodb.deb" | sha256sum -c -; ` + `DEBIAN_FRONTEND=noninteractive dpkg -i "$tmp/arangodb.deb" >/dev/null 2>&1 || ` + `DEBIAN_FRONTEND=noninteractive apt-get -y -f install; ` + `systemctl disable --now arangodb3.service`
   },
   {
     requirement: { id: "cloudflared", version: "2026.7.3" },

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.39";
+export declare const VERSION = "0.1.40";

package/package.json

@@ -1,23 +1,23 @@
 {
 	"name": "@forgezero/agent",
-	"version": "0.1.39",
+	"version": "0.1.40",
 	"type": "module",
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/deploy-file.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts src/capacity-calibration.ts src/platform-bootstrap-runtime.ts --root src --outdir dist --target browser --format esm --packages external && bun build src/project-context.ts src/bootstrap.ts src/metal-bootstrap.ts src/cloudflare-bootstrap.ts src/cloudflare-edge.ts --root src --outdir dist --target bun --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/index.ts --outfile dist/fz-agent.js --target bun --format esm && bun build src/cli/index.ts --outfile dist/fz.js --target bun --format esm && bun build src/compute.ts src/provision.ts src/subscribe.ts src/pipeline.ts src/definition.ts src/deploy-file.ts src/ssh-server.ts src/ssh-listen.ts src/provisioning-pull.ts src/migration-pull.ts src/guest-enrolment.ts src/node-vault.ts src/credential-schema.ts src/metal-provision.ts src/metal-helper-socket.ts src/lifecycle-helper.ts src/deployment-runner.ts src/agent-update.ts src/agent-update-helper.ts src/agent-heartbeat.ts src/software.ts src/software-helper.ts src/ubuntu.ts src/capacity-calibration.ts src/platform-bootstrap-runtime.ts --root src --outdir dist --target browser --format esm --packages external && bun build src/project-context.ts src/bootstrap.ts src/metal-bootstrap.ts src/cloudflare-bootstrap.ts src/cloudflare-edge.ts --root src --outdir dist --target bun --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"devDependencies": {
 		"typescript": "^5.6.0",
 		"@types/bun": "latest",
 		"@types/node": "^22.0.0",
-		"@forgezero/access": "0.1.1",
+		"@forgezero/access": "0.1.2",
 		"@noble/curves": "^2.2.0",
 		"@noble/post-quantum": "^0.6.1"
 	},
 	"dependencies": {
-		"@forgezero/runtime": "0.1.5",
+    "@forgezero/runtime": "0.1.6",
 		"@forgezero/vault": "0.1.8",
 		"@noble/curves": "2.2.0",
 		"@noble/hashes": "2.2.0",
@@ -150,6 +150,10 @@
 			"types": "./dist/bootstrap.d.ts",
 			"default": "./dist/bootstrap.js"
 		},
+		"./credential-schema": {
+			"types": "./dist/credential-schema.d.ts",
+			"default": "./dist/credential-schema.js"
+		},
 		"./platform-bootstrap-runtime": {
 			"types": "./dist/platform-bootstrap-runtime.d.ts",
 			"default": "./dist/platform-bootstrap-runtime.js"

package/dist/cli/custody.d.ts

@@ -1,35 +0,0 @@
-import { type AgentIdentity } from '@forgezero/runtime/ssh-agent';
-/**
- * Choosing an SSH key for custody, safely.
- *
- * A real agent is not a clean room. It commonly holds forwarded keys whose
- * upstream connection is gone, and confirm-on-use keys that wait for a human at
- * a terminal nobody is sitting at. Neither fails — both **hang**, which during a
- * genesis ceremony looks exactly like the platform being broken.
- *
- * So every key is probed under a timeout before it is offered, and the one
- * actually chosen is proved deterministic before it is trusted with a share. An
- * agent that signs differently twice would seal a share that can never be
- * reopened, and that failure would surface only during recovery.
- */
-export declare const PROBE_TIMEOUT_MS = 2000;
-export interface UsableIdentity extends AgentIdentity {
-    /** Milliseconds the agent took to sign. Slow keys are usually forwarded. */
-    responseMs: number;
-}
-/**
- * Every Ed25519 key in the agent that actually responds.
- *
- * Returns an empty array rather than throwing when the agent holds nothing
- * usable — the caller has a better error to give than this function does.
- */
-export declare function usableIdentities(socketPath?: string): Promise<UsableIdentity[]>;
-/**
- * Derive the custody key for a chosen identity, having proved it reproduces.
- *
- * `assertDeterministic` signs twice and compares. It costs one extra signature
- * and removes the only failure mode that is invisible until recovery.
- */
-export declare function custodyKeyFor(identity: AgentIdentity, socketPath?: string): Promise<Uint8Array>;
-/** Match a key by fingerprint prefix, comment, or 1-based index. */
-export declare function selectIdentity(identities: UsableIdentity[], selector: string): UsableIdentity | null;