@forgezero/vault 0.1.0 → 0.1.1

package/dist/schema.js

@@ -1,4 +1,6 @@
 // src/index.ts
+import { deriveKeysFromSeed, signRequest } from "@forgezero/runtime/identity";
+
 class VaultError extends Error {
   code;
   constructor(code, message) {
@@ -7,19 +9,111 @@ class VaultError extends Error {
     this.name = "VaultError";
   }
 }
-var DEFAULT_SOCKET = "/run/forgezero.sock";
+var runtimeEnvironment = () => typeof process !== "undefined" && process.env ? process.env : {};
+var runtimeSocketExists = (path) => {
+  if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function")
+    return false;
+  try {
+    const fs = process.getBuiltinModule("node:fs");
+    return fs.existsSync(path);
+  } catch {
+    return false;
+  }
+};
+var DEFAULT_SOCKET = "/run/forgezero/vault.sock";
 function discover(environment = {}) {
-  const env = environment.env ?? {};
+  const env = environment.env ?? runtimeEnvironment();
   const socketPath = environment.socketPath ?? env.FORGEZERO_SOCKET ?? DEFAULT_SOCKET;
-  if (environment.socketExists?.(socketPath))
+  if ((environment.socketExists ?? runtimeSocketExists)(socketPath))
     return { mode: "managed", socketPath };
   const apiKey = env.FORGEZERO_API_KEY;
   if (apiKey)
     return { mode: "external", apiKey };
   throw new VaultError("NO_CREDENTIAL", `No credential found. On managed compute the agent socket at ${socketPath} provides one; ` + "elsewhere set FORGEZERO_API_KEY.");
 }
+var unbase64url = (encoded) => {
+  const padded = encoded.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - encoded.length % 4) % 4);
+  let binary;
+  try {
+    binary = atob(padded);
+  } catch {
+    throw new VaultError("API_KEY_MALFORMED", "FORGEZERO_API_KEY is malformed.");
+  }
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+};
+var base64url = (value) => {
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+};
+function signerFromApiKey(secret) {
+  const parts = secret.split(".");
+  const legacy = parts.length === 3 && parts[0] === "fz";
+  const current = parts.length === 4 && parts[0] === "fz" && (parts[1] === "live" || parts[1] === "test");
+  if (!legacy && !current)
+    throw new VaultError("API_KEY_MALFORMED", "FORGEZERO_API_KEY is malformed.");
+  const keyId = parts[current ? 2 : 1];
+  const encodedSeed = parts[current ? 3 : 2];
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(keyId) || !/^[A-Za-z0-9_-]{43}$/.test(encodedSeed)) {
+    throw new VaultError("API_KEY_MALFORMED", "FORGEZERO_API_KEY is malformed.");
+  }
+  const seed = unbase64url(encodedSeed);
+  if (seed.length !== 32)
+    throw new VaultError("API_KEY_MALFORMED", "FORGEZERO_API_KEY is malformed.");
+  const keys = deriveKeysFromSeed(seed);
+  seed.fill(0);
+  return {
+    keyId,
+    async sign(request) {
+      const envelope = signRequest(keys, keyId, request);
+      return base64url(JSON.stringify({
+        timestamp: envelope.timestamp,
+        nonce: envelope.nonce,
+        edSignature: envelope.edSignature,
+        mlDsaSignature: envelope.mlDsaSignature
+      }));
+    }
+  };
+}
+var requestAgent = (socketPath, request) => new Promise((resolveRequest, reject) => {
+  if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function") {
+    reject(new VaultError("MANAGED_RUNTIME_UNAVAILABLE", "The managed agent socket needs a Node or Bun server runtime."));
+    return;
+  }
+  const net = process.getBuiltinModule("node:net");
+  const socket = net.connect(socketPath, () => socket.write(`${JSON.stringify(request)}
+`));
+  let buffer = "";
+  socket.setTimeout(15000, () => {
+    socket.destroy();
+    reject(new VaultError("AGENT_TIMEOUT", "The local ForgeZero agent did not answer."));
+  });
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString("utf8");
+    if (new TextEncoder().encode(buffer).byteLength > 256 * 1024) {
+      socket.destroy();
+      reject(new VaultError("AGENT_RESPONSE_TOO_LARGE", "The local ForgeZero agent response was too large."));
+      return;
+    }
+    const newline = buffer.indexOf(`
+`);
+    if (newline < 0)
+      return;
+    socket.end();
+    try {
+      resolveRequest(JSON.parse(buffer.slice(0, newline)));
+    } catch {
+      reject(new VaultError("AGENT_RESPONSE_MALFORMED", "The local ForgeZero agent response was malformed."));
+    }
+  });
+  socket.on("error", (cause) => reject(new VaultError("AGENT_UNAVAILABLE", cause.message)));
+});
 var REASSIGN_ON = new Set([410, 421, 502, 503, 504, 530]);
-var DEFAULT_ASSIGN_URL = "https://api.forgezero.net/v1/assign";
+var DEFAULT_ASSIGN_URL = "https://assign.forgezero.net/v1/assign";
+var DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+var isForgeZeroNode = (hostname) => /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+forgezero\.net$/.test(hostname);
 
 class ForgeZero {
   credential;
@@ -28,14 +122,24 @@ class ForgeZero {
   doFetch;
   now;
   signer;
+  agentTransport;
+  nodeAllowed;
+  requestTimeoutMs;
   project;
   environment;
   constructor(options = {}) {
-    this.credential = options.credential ?? discover(options.discovery);
+    const credential = options.credential ?? discover(options.discovery);
+    this.credential = credential.mode === "managed" && !credential.socketPath ? { ...credential, socketPath: DEFAULT_SOCKET } : credential;
     this.assignUrl = options.assignUrl ?? DEFAULT_ASSIGN_URL;
     this.doFetch = options.fetch ?? globalThis.fetch;
     this.now = options.now ?? Date.now;
-    this.signer = options.signer;
+    this.signer = options.signer ?? (this.credential.mode === "external" ? signerFromApiKey(this.credential.apiKey) : undefined);
+    this.agentTransport = options.agentTransport ?? requestAgent;
+    this.nodeAllowed = options.nodeAllowed ?? isForgeZeroNode;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs < 100 || this.requestTimeoutMs > 120000) {
+      throw new VaultError("INVALID_TIMEOUT", "requestTimeoutMs must be between 100 and 120000 milliseconds.");
+    }
     this.project = options.project ?? "default";
     this.environment = options.environment ?? "production";
   }
@@ -43,17 +147,28 @@ class ForgeZero {
     const now = this.now();
     if (this.assignment && this.assignment.expiresAt > now)
       return this.assignment.node;
-    const response = await this.doFetch(this.assignUrl, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ keyId: this.signer?.keyId })
+    const assignmentUrl = new URL(this.assignUrl);
+    if (this.signer?.keyId && !assignmentUrl.searchParams.has("client")) {
+      assignmentUrl.searchParams.set("client", this.signer.keyId);
+    }
+    const response = await this.doFetch(assignmentUrl, {
+      method: "GET",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(this.requestTimeoutMs)
     });
     if (!response.ok)
       throw new VaultError("NO_NODE", "No vault node is available right now.");
-    const payload = await response.json();
-    const ttl = payload.ttl ?? 60;
-    this.assignment = { node: payload.node, ttl, expiresAt: now + ttl * 1000 };
-    return payload.node;
+    const payload = await response.json().catch(() => null);
+    const hostname = typeof payload?.node === "string" ? payload.node : payload?.node && typeof payload.node === "object" && ("hostname" in payload.node) ? payload.node.hostname : undefined;
+    if (typeof hostname !== "string" || !this.nodeAllowed(hostname)) {
+      throw new VaultError("UNTRUSTED_NODE", "The directory returned an untrusted vault node hostname.");
+    }
+    const ttl = payload?.ttl ?? 60;
+    if (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl < 1 || ttl > 300) {
+      throw new VaultError("INVALID_ASSIGNMENT", "The directory returned an invalid vault-node lease.");
+    }
+    this.assignment = { node: hostname, ttl, expiresAt: now + ttl * 1000 };
+    return hostname;
   }
   reassign() {
     this.assignment = undefined;
@@ -62,17 +177,29 @@ class ForgeZero {
     return `${encodeURIComponent(this.project)}/${encodeURIComponent(this.environment)}`;
   }
   async request(path, init = {}, retried = false) {
+    if (this.credential.mode === "managed")
+      return this.managedRequest(path, init);
     const node = await this.node();
     const body = typeof init.body === "string" ? init.body : "";
+    const target = new URL(path, "https://vault.invalid");
     const headers = {
       "content-type": "application/json",
       ...init.headers
     };
     if (this.signer) {
       headers["x-fz-key"] = this.signer.keyId;
-      headers["x-fz-signature"] = await this.signer.sign(`${init.method ?? "GET"}:${path}:${body}`);
+      headers["x-fz-signature"] = await this.signer.sign({
+        method: init.method ?? "GET",
+        path: target.pathname,
+        query: target.search.replace(/^\?/, ""),
+        body
+      });
     }
-    const response = await this.doFetch(`https://${node}${path}`, { ...init, headers });
+    const response = await this.doFetch(`https://${node}${path}`, {
+      ...init,
+      headers,
+      signal: init.signal ?? AbortSignal.timeout(this.requestTimeoutMs)
+    });
     if (REASSIGN_ON.has(response.status) && !retried) {
       this.reassign();
       return this.request(path, init, true);
@@ -85,7 +212,66 @@ class ForgeZero {
     }
     return payload;
   }
+  async managedRequest(path, init) {
+    const socketPath = this.credential.socketPath;
+    const method = init.method ?? "GET";
+    const target = new URL(path, "https://vault.invalid");
+    const entry = /\/entries\/([^/]+)$/.exec(target.pathname);
+    let response;
+    if (method === "GET" && entry) {
+      response = await this.agentTransport(socketPath, {
+        op: "get",
+        name: decodeURIComponent(entry[1])
+      });
+      if (!response.ok)
+        throw new VaultError(response.error.code, response.error.message);
+      if (response.op !== "get")
+        throw new VaultError("AGENT_RESPONSE_MALFORMED", "The agent answered with the wrong operation.");
+      return { value: response.value };
+    }
+    if (method === "GET" && target.pathname.endsWith("/list")) {
+      response = await this.agentTransport(socketPath, { op: "held" });
+      if (!response.ok)
+        throw new VaultError(response.error.code, response.error.message);
+      if (response.op !== "held")
+        throw new VaultError("AGENT_RESPONSE_MALFORMED", "The agent answered with the wrong operation.");
+      return { entries: response.names.map((name) => ({ name })) };
+    }
+    if (method === "GET" && target.pathname.endsWith("/entries")) {
+      response = await this.agentTransport(socketPath, { op: "held" });
+      if (!response.ok)
+        throw new VaultError(response.error.code, response.error.message);
+      if (response.op !== "held")
+        throw new VaultError("AGENT_RESPONSE_MALFORMED", "The agent answered with the wrong operation.");
+      const values = {};
+      for (const name of response.names) {
+        const read = await this.agentTransport(socketPath, { op: "get", name });
+        if (!read.ok)
+          throw new VaultError(read.error.code, read.error.message);
+        if (read.op !== "get")
+          throw new VaultError("AGENT_RESPONSE_MALFORMED", "The agent answered with the wrong operation.");
+        values[name] = read.value;
+      }
+      return { values };
+    }
+    if (method === "GET" && target.pathname.endsWith("/changes")) {
+      response = await this.agentTransport(socketPath, { op: "sync" });
+      if (!response.ok)
+        throw new VaultError(response.error.code, response.error.message);
+      if (response.op !== "sync")
+        throw new VaultError("AGENT_RESPONSE_MALFORMED", "The agent answered with the wrong operation.");
+      return {
+        version: response.cursor,
+        changed: response.invalidated.map((name) => ({ name, version: 0 })),
+        resync: response.resync
+      };
+    }
+    throw new VaultError("MANAGED_READ_ONLY", "This operation is not exposed to an application through the managed agent socket.");
+  }
   async get(name, options = {}) {
+    if (this.credential.mode === "managed" && options.version !== undefined) {
+      throw new VaultError("MANAGED_CURRENT_ONLY", "The managed agent RAM replica serves the current value only; use an API key for a historical version.");
+    }
     const query = options.version ? `?version=${options.version}` : "";
     const result = await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}${query}`);
     return result.value;
@@ -112,16 +298,10 @@ class ForgeZero {
     return result.entries;
   }
   async set(name, value) {
-    const result = await this.request(`/v1/vault/${this.scope()}/entries`, {
-      method: "POST",
-      body: JSON.stringify({ name, value })
-    });
-    return result.version;
+    throw new VaultError("APPLICATION_READ_ONLY", "Application vault credentials cannot write secrets; use the authenticated platform vault UI.");
   }
   async remove(name) {
-    await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}`, {
-      method: "DELETE"
-    });
+    throw new VaultError("APPLICATION_READ_ONLY", "Application vault credentials cannot delete secrets; use the authenticated platform vault UI.");
   }
   async* watch(options = {}) {
     const interval = options.intervalMs ?? 15000;
@@ -146,7 +326,43 @@ function vaultCredentials(vault) {
     get: (reference, field) => vault.get(`${reference}.${field}`)
   };
 }
-var VERSION = "0.1.0";
+function directCredentials(read) {
+  return { name: "platform-direct", get: read };
+}
+var readRuntimeCredential = (path) => {
+  if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function")
+    return;
+  try {
+    const fs = process.getBuiltinModule("node:fs");
+    const stat = fs.statSync(path);
+    if (!stat.isFile() || stat.size > 1024 * 1024)
+      return;
+    return fs.readFileSync(path, "utf8");
+  } catch {
+    return;
+  }
+};
+function systemdCredentials(options = {}) {
+  return {
+    name: "systemd",
+    async get(reference, field) {
+      const directory = options.directory ?? (typeof process !== "undefined" ? process.env?.CREDENTIALS_DIRECTORY : undefined);
+      if (!directory) {
+        throw new VaultError("CREDENTIAL_MISSING", "systemd did not provide CREDENTIALS_DIRECTORY to this unit.");
+      }
+      const name = (options.nameFor ?? ((ref, key) => `${ref}.${key}`))(reference, field);
+      if (!/^[A-Za-z0-9_.-]{1,128}$/.test(name)) {
+        throw new VaultError("CREDENTIAL_NAME_INVALID", "A systemd credential name may contain only letters, digits, dot, underscore and hyphen.");
+      }
+      const value = (options.read ?? readRuntimeCredential)(`${directory}/${name}`);
+      if (value === undefined || value.length === 0) {
+        throw new VaultError("CREDENTIAL_MISSING", `The systemd credential ${name} is not available to this unit.`);
+      }
+      return value;
+    }
+  };
+}
+var VERSION = "0.1.1";
 
 // src/schema.ts
 function managedSchemas(vault, options = {}) {

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/vault",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -41,6 +41,14 @@
     "typescript": "^5.6.0",
     "@types/bun": "latest"
   },
+  "dependencies": {
+    "@forgezero/runtime": "^0.1.2"
+  },
+  "peerDependencies": {
+    "@noble/curves": "^2.2.0",
+    "@noble/post-quantum": "^0.6.1",
+    "@noble/hashes": "^2.2.0"
+  },
   "description": "ForgeZero vault client. Credential discovery, versioned secrets, node assignment.",
   "keywords": [
     "secrets",
@@ -55,7 +63,7 @@
     "nextjs"
   ],
   "license": "MIT",
-  "homepage": "https://forgezero.net/docs/vault-package",
+  "homepage": "https://www.forgezero.net/docs/vault-package",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/axxra/forgezero.git",