@forgezero/vault 0.1.2 → 0.1.3

package/README.md

@@ -2,10 +2,11 @@
 
 **Read your secrets at runtime instead of shipping them in a file.**
 
-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.
+The client discovers its own credential and uses one stable API origin. Node
+routing and failover stay behind that edge contract; the SDK never discovers or
+stores a node hostname. 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.
@@ -56,8 +57,10 @@ 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. Custody operations stay
-on the authenticated platform surface; the application credential is read-only.
+Either way there is no call that returns a private key. Derivation and signing
+stay inside explicit trusted platform workflows; the general application
+credential remains a read-only secret client and is not a transaction-signing
+oracle.
 
 ## Subpaths
 

package/dist/index.d.ts

@@ -156,41 +156,35 @@ export declare class ForgeZero {
      */
     getAll(): Promise<Record<string, string>>;
     /**
-     * The PUBLIC half of a value ForgeZero derived from the realm master seed.
+     * Custody derivation is intentionally not a general application-key action.
      *
-     * There is no call that returns the private half, and that is the whole
-     * design rather than an omission. A tenant that can fetch a signing key holds
-     * the full risk of holding one: it lands in their backups, their logs, their
-     * heap dumps and their environment. Here they declare which chain they
-     * activated, the platform derives from the seed, and an ADDRESS is the only
-     * thing that crosses back.
+     * Kept as a typed refusal for compatibility with the early package preview,
+     * which exposed this method before a secured custody workflow existed. A
+     * compromised secret-reading process must not silently become a transaction
+     * signer merely because both operations happen to involve the vault.
      *
-     * Deterministic, so losing the row loses the metadata and not the money —
-     * re-declaring the same chain and index derives the same address.
+     * @deprecated Use an explicit platform custody workflow with its own policy,
+     * approval and audit contract.
      */
     derived(name: string, field: string): Promise<{
         address: string;
         path: string;
     }>;
     /**
-     * Sign a digest with a derived key, without the key ever leaving.
-     *
-     * The tenant builds the unsigned transaction, hashes it, and sends the
-     * digest. What comes back is a signature. A compromised tenant process can
-     * ASK for signatures — which is bounded, logged and revocable — and cannot
-     * take the key, which would be none of those things.
-     *
-     * A digest rather than a transaction on purpose: the platform is not a
-     * transaction builder for every chain a tenant might use, and pretending
-     * otherwise would make ForgeZero the thing that has to understand every
-     * chain format before a tenant can support one.
+     * @deprecated A general application vault credential is not a signing oracle.
      */
     sign(name: string, field: string, digest: string): Promise<{
         signature: string;
         recovery?: number;
         path: string;
     }>;
-    /** Schemas the platform holds, for a managed source. */
+    /**
+     * List schemas represented by reserved vault entries.
+     *
+     * Kept for compatibility; `managedSchemas(vault).list()` is the higher-level
+     * interface. It deliberately uses `list` and `get`, so both the local agent
+     * and signed HTTPS transports follow the same contract.
+     */
     schemas(): Promise<readonly {
         name: string;
         version: number;

package/dist/index.js

@@ -254,14 +254,28 @@ class ForgeZero {
     return result.values;
   }
   async derived(name, field) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/derived/${encodeURIComponent(field)}${this.scope()}`);
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Derived custody keys require an explicit platform custody workflow; an application vault credential cannot request them.");
   }
   async sign(name, field, digest) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/sign/${encodeURIComponent(field)}${this.scope()}`, { method: "POST", body: JSON.stringify({ digest }) });
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Signing requires an explicit platform custody workflow with its own policy, approval and audit contract.");
   }
   async schemas() {
-    const payload = await this.request(`/v1/schemas${this.scope()}`);
-    return payload.schemas ?? [];
+    const entries = await this.list();
+    const names = entries.map((entry) => entry.name).filter((name) => name.startsWith("__schema__")).map((name) => name.slice("__schema__".length)).filter(Boolean);
+    return Promise.all(names.map(async (name) => {
+      let value;
+      try {
+        value = JSON.parse(await this.get(`__schema__${name}`));
+      } catch (cause) {
+        if (cause instanceof VaultError)
+          throw cause;
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} is not JSON.`);
+      }
+      if (!Number.isInteger(value.version) || Number(value.version) < 1) {
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} has no valid version.`);
+      }
+      return { name, version: Number(value.version) };
+    }));
   }
   async list() {
     const result = await this.request(`/v1/vault/${this.scope()}/list`);

package/dist/providers.js

@@ -254,14 +254,28 @@ class ForgeZero {
     return result.values;
   }
   async derived(name, field) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/derived/${encodeURIComponent(field)}${this.scope()}`);
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Derived custody keys require an explicit platform custody workflow; an application vault credential cannot request them.");
   }
   async sign(name, field, digest) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/sign/${encodeURIComponent(field)}${this.scope()}`, { method: "POST", body: JSON.stringify({ digest }) });
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Signing requires an explicit platform custody workflow with its own policy, approval and audit contract.");
   }
   async schemas() {
-    const payload = await this.request(`/v1/schemas${this.scope()}`);
-    return payload.schemas ?? [];
+    const entries = await this.list();
+    const names = entries.map((entry) => entry.name).filter((name) => name.startsWith("__schema__")).map((name) => name.slice("__schema__".length)).filter(Boolean);
+    return Promise.all(names.map(async (name) => {
+      let value;
+      try {
+        value = JSON.parse(await this.get(`__schema__${name}`));
+      } catch (cause) {
+        if (cause instanceof VaultError)
+          throw cause;
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} is not JSON.`);
+      }
+      if (!Number.isInteger(value.version) || Number(value.version) < 1) {
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} has no valid version.`);
+      }
+      return { name, version: Number(value.version) };
+    }));
   }
   async list() {
     const result = await this.request(`/v1/vault/${this.scope()}/list`);

package/dist/schema.d.ts

@@ -49,9 +49,7 @@ export interface SchemaSource {
  * platform being up. `refresh` exists so a long-lived process can pick up a
  * change without restarting.
  */
-export declare function managedSchemas(vault: Pick<ForgeZero, 'get'> & {
-    schemas?: () => Promise<readonly SchemaRef[]>;
-}, options?: {
+export declare function managedSchemas(vault: Pick<ForgeZero, 'get' | 'list'>, options?: {
     ttlMs?: number;
     now?: () => number;
 }): SchemaSource & {

package/dist/schema.js

@@ -254,14 +254,28 @@ class ForgeZero {
     return result.values;
   }
   async derived(name, field) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/derived/${encodeURIComponent(field)}${this.scope()}`);
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Derived custody keys require an explicit platform custody workflow; an application vault credential cannot request them.");
   }
   async sign(name, field, digest) {
-    return this.request(`/v1/entries/${encodeURIComponent(name)}/sign/${encodeURIComponent(field)}${this.scope()}`, { method: "POST", body: JSON.stringify({ digest }) });
+    throw new VaultError("CUSTODY_WORKFLOW_REQUIRED", "Signing requires an explicit platform custody workflow with its own policy, approval and audit contract.");
   }
   async schemas() {
-    const payload = await this.request(`/v1/schemas${this.scope()}`);
-    return payload.schemas ?? [];
+    const entries = await this.list();
+    const names = entries.map((entry) => entry.name).filter((name) => name.startsWith("__schema__")).map((name) => name.slice("__schema__".length)).filter(Boolean);
+    return Promise.all(names.map(async (name) => {
+      let value;
+      try {
+        value = JSON.parse(await this.get(`__schema__${name}`));
+      } catch (cause) {
+        if (cause instanceof VaultError)
+          throw cause;
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} is not JSON.`);
+      }
+      if (!Number.isInteger(value.version) || Number(value.version) < 1) {
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} has no valid version.`);
+      }
+      return { name, version: Number(value.version) };
+    }));
   }
   async list() {
     const result = await this.request(`/v1/vault/${this.scope()}/list`);
@@ -362,7 +376,12 @@ function managedSchemas(vault, options = {}) {
       return value;
     },
     async list() {
-      return await vault.schemas?.() ?? [];
+      const entries = await vault.list();
+      const names = entries.map((entry) => entry.name).filter((name) => name.startsWith("__schema__")).map((name) => name.slice("__schema__".length)).filter(Boolean);
+      return Promise.all(names.map(async (name) => {
+        const resolved = await this.get(name);
+        return { name, version: resolved.version };
+      }));
     }
   };
 }

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.2",
+  "version": "0.1.3",
   "type": "module",
   "publishConfig": {
     "access": "public"