@forgezero/vault 0.1.0 → 0.1.2

package/README.md

@@ -2,9 +2,10 @@
 
 **Read your secrets at runtime instead of shipping them in a file.**
 
-The client discovers its own credential and asks a directory which node to talk
-to. There is no endpoint to configure and no `.env` to leak — the same code runs
-on a laptop and in production, and the laptop holds nothing worth stealing.
+The client discovers its own credential and, for an API key, asks a directory
+which node to talk to. There is no endpoint to configure. The same code runs on
+a laptop and in production: outside managed compute the key is a local signing
+seed; on managed compute there is no remote credential in the application.
 
 This one talks to a ForgeZero vault, so it needs an account. The other three
 packages do not.
@@ -19,7 +20,7 @@ import { ForgeZero } from '@forgezero/vault';
 const fz = new ForgeZero({ project: 'altpilot', environment: 'production' });
 
 const key   = await fz.get('STRIPE_KEY');
-const names = await fz.list();          // names and metadata, never values
+const names = await fz.list();          // names; remote reads also include metadata
 ```
 
 ## Envless
@@ -33,12 +34,12 @@ import '@forgezero/vault/env';          // refuses to run during a build
 Rotation stops being a project. A new version is written, readers pick it up on
 their next fetch, and nothing is redeployed.
 
-## Two transports, and the socket wins
+## Two application transports, and the socket wins
 
-On a ForgeZero compute the client speaks to a unix socket held by the local
-agent, which is attested and never leaves the machine. Anywhere else it uses an
-API key over HTTPS. When both are present the socket wins, because the one that
-never crosses a network is the one to prefer.
+On a ForgeZero compute the client reads the environment's in-memory replica over
+a Unix socket held by the local agent. Anywhere else it derives a hybrid signer
+from an API key and reads over HTTPS. When both are present the socket wins,
+because the application then holds no reusable remote credential.
 
 ## The API key is a seed, not a password
 
@@ -55,14 +56,14 @@ An entry can declare fields the tenant never holds. Two custody modes:
   exists in plaintext only inside a signing call.
 - **supplied** — you generate it, the vault seals it.
 
-Either way there is no call that returns a private key. `derived()` gives you an
-address or a public key; `sign()` gives you a signature.
+Either way there is no call that returns a private key. Custody operations stay
+on the authenticated platform surface; the application credential is read-only.
 
 ## Subpaths
 
 | import | what it is |
 |---|---|
-| `@forgezero/vault` | the client — get, list, write, rotate, `derived`, `sign` |
+| `@forgezero/vault` | the read-only application client — get, list and watch rotation |
 | `/env` | envless: fill `process.env` at boot |
 | `/config` | read `.fz/config.json` — project, environment, which secrets |
 | `/schema` | where an entry's shape comes from: pulled from the platform, or local |
@@ -74,9 +75,9 @@ address or a public key; `sign()` gives you a signature.
 help. `BLOCKED` — access was cut deliberately and lifts just as fast.
 `NO_CREDENTIAL` — neither a socket nor an API key was found.
 
-Full documentation: **https://forgezero.net/docs/vault-package**
+Full documentation: **https://www.forgezero.net/docs/vault-package**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys.

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 /**
  * @forgezero/vault — the client.
  *
- * Zero runtime dependencies. Credential discovery, versioned reads and writes,
- * rotation via `watch`.
+ * One audited ForgeZero identity dependency. Credential discovery, current and
+ * versioned reads, and rotation via `watch`.
  *
  * ## Discovery, and why it matters more than it looks
  *
- *   /run/forgezero.sock exists   → MANAGED: the agent signs, the app holds
- *                                   nothing at all
+ *   /run/forgezero/vault.sock exists → MANAGED: read the agent's RAM replica;
+ *                                   the app holds no remote credential
  *   FORGEZERO_API_KEY present    → EXTERNAL: derive a keypair locally, sign here
  *   neither                      → throw, naming BOTH so the fix is obvious
  *
@@ -16,12 +16,13 @@
  * places, and the stronger posture is the one requiring less configuration
  * rather than more.
  *
- * ## Node assignment
+ * ## Stable API origin
  *
- * A directory answers which node to use; the client then talks to it directly
- * for a short window. Reassignment includes 530 — a node whose TUNNEL is down
- * returns Cloudflare 1033, not an application status, so a retry list of only
- * 5xx misses it entirely.
+ * External clients always call one API origin. Node selection and failover are
+ * edge responsibilities; exposing node hostnames here would couple every SDK
+ * to platform topology and can route a tenant to a process that does not hold
+ * its realm seed. Managed applications continue to use the local agent socket
+ * and make no remote request at all.
  *
  * This package must not import `@forgezero/providers` either. `vaultCredentials`
  * returns the shape structurally, because a dependency edge in either direction
@@ -34,7 +35,7 @@ export declare class VaultError extends Error {
 export type CredentialMode = 'managed' | 'external';
 export interface Credential {
     mode: CredentialMode;
-    /** MANAGED only — the agent socket that signs on our behalf. */
+    /** MANAGED only — the agent socket serving the environment's RAM replica. */
     socketPath?: string;
     /** EXTERNAL only — a seed, never transmitted; a keypair derives from it. */
     apiKey?: string;
@@ -44,7 +45,14 @@ export interface DiscoveryEnvironment {
     socketPath?: string;
     socketExists?: (path: string) => boolean;
 }
-export declare const DEFAULT_SOCKET = "/run/forgezero.sock";
+/**
+ * Inside the RuntimeDirectory created by the agent's systemd unit.
+ *
+ * The old path was `/run/forgezero.sock`, directly under `/run`. The hardened
+ * unit runs as an unprivileged user and only receives `/run/forgezero`, so a
+ * fresh service could never create the socket its client was looking for.
+ */
+export declare const DEFAULT_SOCKET = "/run/forgezero/vault.sock";
 /**
  * Find a credential, preferring the stronger posture.
  *
@@ -53,60 +61,88 @@ export declare const DEFAULT_SOCKET = "/run/forgezero.sock";
  * machine that holds nothing into one holding a signing seed.
  */
 export declare function discover(environment?: DiscoveryEnvironment): Credential;
-/** Signs a request. Supplied by the host, so this package holds no crypto. */
+export interface SignRequest {
+    method: string;
+    path: string;
+    query: string;
+    body: string;
+}
+/** Hybrid-signs one exact HTTP request. */
 export interface Signer {
     readonly keyId: string;
-    sign(payload: string): Promise<string>;
+    sign(request: SignRequest): Promise<string>;
 }
-export interface Assignment {
-    node: string;
-    ttl: number;
-    expiresAt: number;
-}
-/**
- * Statuses meaning "ask for a different node", not "this failed".
- *
- * 530 is the one people miss: a node whose tunnel is down never reaches the
- * application, so Cloudflare answers 1033 with 530.
- */
-export declare const REASSIGN_ON: Set<number>;
+/** Derive both private halves locally; only the public key id crosses the wire. */
+export declare function signerFromApiKey(secret: string): Signer;
+export type AgentRequest = {
+    op: 'get';
+    name: string;
+} | {
+    op: 'held';
+} | {
+    op: 'sync';
+};
+export type AgentResponse = {
+    ok: true;
+    op: 'get';
+    value: string;
+} | {
+    ok: true;
+    op: 'held';
+    names: string[];
+    staleForMs: number;
+} | {
+    ok: true;
+    op: 'sync';
+    invalidated: string[];
+    cursor: number;
+    resync: boolean;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type AgentTransport = (socketPath: string, request: AgentRequest) => Promise<AgentResponse>;
 export interface VaultOptions {
-    /** Directory endpoint. Unauthenticated — a node hostname is not a secret. */
-    assignUrl?: string;
+    /** Stable public API origin. Node topology is never exposed to the client. */
+    apiUrl?: string;
+    requestTimeoutMs?: number;
     project?: string;
     environment?: string;
     fetch?: typeof globalThis.fetch;
     signer?: Signer;
+    agentTransport?: AgentTransport;
     credential?: Credential;
     discovery?: DiscoveryEnvironment;
-    now?: () => number;
 }
 export interface EntryMeta {
     name: string;
-    version: number;
-    updatedAtTs: number;
+    /** Present on remote API-key reads; the local RAM replica exposes names only. */
+    version?: number;
+    /** Present on remote API-key reads; the local RAM replica exposes names only. */
+    updatedAtTs?: number;
 }
 export interface Change {
     name: string;
     version: number;
 }
-export declare const DEFAULT_ASSIGN_URL = "https://api.forgezero.net/v1/assign";
+export declare const DEFAULT_API_URL = "https://api.forgezero.net";
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
 export declare class ForgeZero {
     readonly credential: Credential;
-    private assignment;
-    private readonly assignUrl;
+    private readonly apiUrl;
     private readonly doFetch;
-    private readonly now;
     private readonly signer?;
+    private readonly agentTransport;
+    private readonly requestTimeoutMs;
     private readonly project;
     private readonly environment;
     constructor(options?: VaultOptions);
-    /** The node to talk to, asking the directory only when the lease expired. */
-    node(): Promise<string>;
-    /** Drop the lease so the next call asks the directory again. */
-    reassign(): void;
     private scope;
     private request;
+    private managedRequest;
     /** One value, current version unless asked otherwise. */
     get(name: string, options?: {
         version?: number;
@@ -161,7 +197,10 @@ export declare class ForgeZero {
     }[]>;
     /** Names and metadata. Never values. */
     list(): Promise<readonly EntryMeta[]>;
-    /** Write a new version. Nothing is overwritten; the previous stays readable. */
+    /**
+     * Application credentials are read-only. Secret writes require a human
+     * session, step-up proof and a named audit actor on the platform surface.
+     */
     set(name: string, value: string): Promise<number>;
     remove(name: string): Promise<void>;
     /**
@@ -200,4 +239,38 @@ export declare function vaultCredentials(vault: ForgeZero): {
     readonly name: string;
     get(reference: string, field: string): Promise<string>;
 };
-export declare const VERSION = "0.1.0";
+/**
+ * Trusted platform code injects its realm-scoped reader here.
+ *
+ * The package does not import a database or a master-seed implementation: that
+ * would force every tenant application to depend on ForgeZero internals. The
+ * API already has the unlocked realm seed and supplies a function that opens
+ * exactly the requested provider field in-process, without calling itself over
+ * HTTP or replicating plaintext beside itself.
+ */
+export declare function directCredentials(read: (reference: string, field: string) => Promise<string>): {
+    readonly name: 'platform-direct';
+    get(reference: string, field: string): Promise<string>;
+};
+export interface SystemdCredentialOptions {
+    /** Defaults to the private tmpfs directory PID 1 gives this unit. */
+    directory?: string;
+    /** Map a provider reference/field to the credential name declared by the unit. */
+    nameFor?: (reference: string, field: string) => string;
+    /** Test/runtime injection; returns undefined when absent. */
+    read?: (path: string) => string | undefined;
+}
+/**
+ * Bootstrap/recovery credentials loaded by systemd into read-only tmpfs.
+ *
+ * Explicit rather than part of `discover()`: an application must never
+ * downgrade from an attested agent to whatever unrelated credential files its
+ * unit happens to expose. Callers compose this behind the direct vault source
+ * with `chainCredentials()` only for values deliberately declared as bootstrap
+ * roots.
+ */
+export declare function systemdCredentials(options?: SystemdCredentialOptions): {
+    readonly name: 'systemd';
+    get(reference: string, field: string): Promise<string>;
+};
+export declare const VERSION = "0.1.2";

package/dist/index.js

@@ -1,4 +1,6 @@
 // src/index.ts
+import { deriveKeysFromSeed, signRequest } from "@forgezero/runtime/identity";
+
 class VaultError extends Error {
   code;
   constructor(code, message) {
@@ -7,76 +9,171 @@ 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 REASSIGN_ON = new Set([410, 421, 502, 503, 504, 530]);
-var DEFAULT_ASSIGN_URL = "https://api.forgezero.net/v1/assign";
+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 DEFAULT_API_URL = "https://api.forgezero.net";
+var DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+function apiOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new VaultError("API_URL_INVALID", "apiUrl must be an absolute HTTPS origin.");
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1";
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:") || url.username || url.password || url.search || url.hash || url.pathname !== "/" && url.pathname !== "")
+    throw new VaultError("API_URL_INVALID", "apiUrl must be an HTTPS origin without credentials, path, query or fragment.");
+  return url;
+}
 
 class ForgeZero {
   credential;
-  assignment;
-  assignUrl;
+  apiUrl;
   doFetch;
-  now;
   signer;
+  agentTransport;
+  requestTimeoutMs;
   project;
   environment;
   constructor(options = {}) {
-    this.credential = options.credential ?? discover(options.discovery);
-    this.assignUrl = options.assignUrl ?? DEFAULT_ASSIGN_URL;
+    const credential = options.credential ?? discover(options.discovery);
+    this.credential = credential.mode === "managed" && !credential.socketPath ? { ...credential, socketPath: DEFAULT_SOCKET } : credential;
+    this.apiUrl = apiOrigin(options.apiUrl ?? DEFAULT_API_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.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";
   }
-  async node() {
-    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 })
-    });
-    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;
-  }
-  reassign() {
-    this.assignment = undefined;
-  }
   scope() {
     return `${encodeURIComponent(this.project)}/${encodeURIComponent(this.environment)}`;
   }
-  async request(path, init = {}, retried = false) {
-    const node = await this.node();
+  async request(path, init = {}) {
+    if (this.credential.mode === "managed")
+      return this.managedRequest(path, init);
     const body = typeof init.body === "string" ? init.body : "";
+    const target = new URL(path, this.apiUrl);
     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}`);
-    }
-    const response = await this.doFetch(`https://${node}${path}`, { ...init, headers });
-    if (REASSIGN_ON.has(response.status) && !retried) {
-      this.reassign();
-      return this.request(path, init, true);
+      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(target, {
+      ...init,
+      headers,
+      signal: init.signal ?? AbortSignal.timeout(this.requestTimeoutMs)
+    });
     const payload = await response.json().catch(() => {
       return;
     });
@@ -85,7 +182,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 +268,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,15 +296,54 @@ 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.2";
 export {
   vaultCredentials,
+  systemdCredentials,
+  signerFromApiKey,
   discover,
+  directCredentials,
   createVault,
   VaultError,
   VERSION,
-  REASSIGN_ON,
   ForgeZero,
   DEFAULT_SOCKET,
-  DEFAULT_ASSIGN_URL
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  DEFAULT_API_URL
 };