@forgezero/vault 0.1.9 → 0.1.11

package/README.md

@@ -1,90 +1,200 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  and commit the generator and rendered files together.
+-->
+
 # @forgezero/vault
 
-**Read your secrets at runtime instead of shipping them in a file.**
+One scoped contract over platform-direct, managed-agent and external API-key trust paths.
+
+## Global package root and supported runtimes
+
+The scoped vault facade. A tenant application uses its local agent or an API key; trusted platform code injects a direct realm backend instead of calling itself. The one package that ends up in somebody else's production dependency tree, which is why it stays alone and stays small. Supported runtimes: bun, node, workers, deno. The global base/root import is @forgezero/vault. Every public import or command is listed below; the documentation inventory is checked in both directions against package.json exports.
 
-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.
+```text
+import * as root from '@forgezero/vault';
+```
+
+## Commands
 
-This one talks to a ForgeZero vault, so it needs an account. The other three
-packages do not.
+bun add @forgezero/vault — Install the scoped Vault client and its public subpaths.
 
-```bash
+```text
 bun add @forgezero/vault
 ```
 
-```ts
+## @forgezero/vault
+
+One scoped contract over an explicitly injected platform backend, a managed tenant socket or an automatically derived external API-key signer.
+
+```text
+import * as api from '@forgezero/vault';
+```
+
+## @forgezero/vault/schema
+
+Where an entry’s shape comes from: pulled from the platform when ForgeZero has to render it, declared locally when only the tenant needs it.
+
+```text
+import * as api from '@forgezero/vault/schema';
+```
+
+## @forgezero/vault/config
+
+Read `.fz/config.json` — which project, which environment, which secrets, and what to call them.
+
+```text
+import * as api from '@forgezero/vault/config';
+```
+
+## @forgezero/vault/env
+
+Envless: fill `process.env` from the vault at boot, refusing to run during a build.
+
+```text
+import * as api from '@forgezero/vault/env';
+```
+
+## @forgezero/vault/frameworks
+
+SvelteKit and Next.js wiring, attached at the one place that runs once, on the server, before any request.
+
+```text
+import * as api from '@forgezero/vault/frameworks';
+```
+
+## @forgezero/vault/providers
+
+Adapters that make Vault a provider-configuration and credential source without coupling the providers package to ForgeZero.
+
+```text
+import * as api from '@forgezero/vault/providers';
+```
+
+## Read a scoped secret
+
+The same client discovers the managed Agent socket or uses an external API-key signer. Project and environment remain explicit.
+
+```text
+import { createVault } from '@forgezero/vault';
+
+const vault = createVault({ project: 'payments', environment: 'production' });
+const token = await vault.get('STRIPE_KEY');
+```
+
+## Three paths, and why they stay explicit
+
+Platform API logic already holds the requested realm master seed, so it opens the scoped envelope directly through an injected internal backend — no HTTP call, API key or local replica. A tenant on managed compute uses the local agent and its memory-only project scope. A tenant elsewhere signs HTTPS with an API-key seed. These share vault semantics and never silently fall through from a stronger posture to a weaker one.
+
+```text
+PLATFORM API      resident realm seed -> direct scoped envelope
+MANAGED TENANT   local unix socket    -> agent RAM scope
+EXTERNAL TENANT  scoped API-key seed  -> signed HTTPS
+```
+
+## Current implementation boundary
+
+All three trust paths now have code: the platform opens its resident realm seed directly, an enrolled tenant agent derives its project binding and keeps every environment in that project in RAM, and createVault automatically uses either the local socket or a hybrid signer derived from an API-key seed. Live SEV-SNP report acquisition and an end-to-end production deployment are still gates; installation alone is not presented as proof.
+
+## 1. Install
+
+One ForgeZero identity dependency plus its required audited Noble crypto peers. The HTTPS path works anywhere fetch and Web Crypto exist; managed socket discovery requires a Bun or Node server runtime.
+
+```text
+bun add @forgezero/vault
+```
+
+## 2. Read a secret
+
+The project and environment are explicit application scope. Managed compute uses the local Agent socket; external runtimes use the stable API origin and their scoped key.
+
+```text
 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; remote reads also include metadata
+const names = await fz.list();      // names; HTTPS reads also carry metadata
 ```
 
-## Envless
+## 3. Ship it unchanged — target discovery
 
-Fill `process.env` at boot and change nothing else in your application:
+On managed tenant compute the Agent holds the node identity and the complete project RAM replica; the application holds no reusable remote credential and selects its environment in each client instance. The client finds the group-scoped socket instead of the environment variable. Outside managed compute it automatically derives the exact hybrid request signer from FORGEZERO_API_KEY.
 
-```ts
-import '@forgezero/vault/env';          // refuses to run during a build
+```text
+new ForgeZero()
+  |- /run/forgezero/vault.sock exists -> MANAGED, app holds nothing
+  |- FORGEZERO_API_KEY present        -> EXTERNAL, derive and sign locally
+  `- neither                          -> throws, naming BOTH remedies
 ```
 
-Rotation stops being a project. A new version is written, readers pick it up on
-their next fetch, and nothing is redeployed.
+## When both are present, the socket wins
 
-## Two application transports, and the socket wins
+On managed compute an API key in the environment is a leftover. Honouring it would silently downgrade a machine that holds nothing into one holding a signing seed, so discovery always prefers the stronger posture.
 
-On a ForgeZero compute the Agent keeps the enrolled project's environments in
-RAM and the client selects one environment over its group-scoped Unix socket.
-Anywhere else it derives the same hybrid request identity from an API-key seed
-and reads over HTTPS. Each remote request also carries a signed one-use hybrid
-ML-KEM-768 + X25519 response key; the API seals the JSON value to that key with
-AES-256-GCM, so a TLS-terminating edge can route the call but cannot read its
-secret response. When both are present the socket wins, because the
-application then holds no reusable remote credential.
+## Rotation is human-authorised and application-observed
 
-## The API key is a seed, not a password
+Writes stay on the authenticated platform surface with a human session, step-up proof and named audit actor. The application credential is read-only. External API-key reads may request a historical version; the managed RAM replica intentionally serves only the current value.
 
-The key handed to you **is** the seed for a hybrid Ed25519 + ML-DSA-65 key pair.
-The client re-derives that pair on every start; the platform stores only the
-public halves. A dump of the key table yields nothing that can sign — which is
-not true of any scheme where the server holds something it compares against.
-
-## Schema-declared secrets
+```text
+// after an authorised rotation in the platform UI
+for await (const change of fz.watch()) {
+  console.log(change.name, change.version);
+}
+```
 
-An entry can declare fields the tenant never holds. Two custody modes:
+## getAll is managed-only, deliberately
 
-- **derived** — the vault generates the key material from the master seed and it
-  exists in plaintext only inside a signing call.
-- **supplied** — you generate it, the vault seals it.
+One compromised API key should not hand over an entire environment in a single call, so a key holder gets list() plus reads by name. On managed compute there is no key to compromise, which is why the bulk read is allowed there and only there.
 
-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.
+## One stable API origin
 
-## Subpaths
+The client always calls api.forgezero.net. Cloudflare owns routing and node health behind that name; the SDK never receives a node hostname, polls an assignment endpoint or replays a state-changing request against a different process.
 
-| import | what it is |
-|---|---|
-| `@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 |
-| `/frameworks` | SvelteKit and Next.js wiring, at the one place that runs once |
+```text
+410 421 502 503 504 530  ->  ask for a different node, retry once
+401 403                  ->  an answer, not a routing problem
+```
 
 ## Errors you will actually hit
 
-`VAULT_LOCKED` (423) — a custodian quorum must unlock it; retrying will not
-help. `BLOCKED` — access was cut deliberately and lifts just as fast.
-`NO_CREDENTIAL` — neither a socket nor an API key was found.
+Each names what to do next.
+
+```text
+NO_CREDENTIAL   neither the socket nor FORGEZERO_API_KEY was found
+VAULT_LOCKED    the realm has no seed in memory; a custodian must unlock
+MANAGED_ONLY    getAll needs the agent socket
+NO_NODE         no vault node is currently available
+```
+
+## API keys — the key is a seed, not a password
+
+The SDK derives an Ed25519 + ML-DSA-65 keypair from it and signs every request, including a one-use hybrid ML-KEM-768 + X25519 response key. The API AES-256-GCM seals the result to that request before it crosses the edge. The seed itself is never transmitted, and ForgeZero stores only public halves.
+
+```text
+fz.live.<keyId>.<seed>     fz.test.<keyId>.<seed>
+```
+
+## Scope every key to one project and only the environments it needs
+
+An API key is fixed to one project, optionally narrowed to named environments, and issued with exact route grants or project-owned API-key roles. Single-entry read, metadata listing and change following are the least-privilege default; bulk environment read and exact pipeline release are separate opt-ins.
+
+```text
+project: payments
+environments: production, staging
+routes: read one, list metadata, follow changes
+bulk read: explicit opt-in
+pipeline release: explicit live-key role
+```
+
+## Controls, and what each is actually worth
+
+Project, environment, exact route grants and revocation are real: status is read fresh on every call, so a revoked key stops working on the next request. API keys do not currently expire automatically; rotate or revoke them deliberately. An origin header is not treated as server authentication because any server-side caller can set it.
 
-Full documentation: **https://www.forgezero.net/docs/vault-package**
+## Vault read-only; release intent is the narrow machine write
 
-## Licence
+The external Vault SDK has no secret write endpoint. A live API key may separately receive pipeline:release:create: it queues one full Git commit on an existing enabled pipeline, requires a stable idempotency key, and cannot edit a pipeline, target, secret or compute. Sandbox and legacy keys never inherit it, and the bound Agent still claims execution.
 
-MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
-deploys.
+Full rendered documentation: https://www.forgezero.net/docs/vault-package

package/dist/index.d.ts

@@ -282,4 +282,4 @@ export declare function systemdCredentials(options?: SystemdCredentialOptions):
     readonly name: 'systemd';
     get(reference: string, field: string): Promise<string>;
 };
-export declare const VERSION = "0.1.9";
+export declare const VERSION = "0.1.11";

package/dist/index.js

@@ -382,7 +382,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.9";
+var VERSION = "0.1.11";
 export {
   vaultCredentials,
   systemdCredentials,

package/dist/providers.d.ts

@@ -68,5 +68,9 @@ export declare function vaultConfig(vault: ForgeZero, options?: VaultConfigOptio
  */
 export declare function vaultCredentials(vault: ForgeZero): {
     name: string;
-    get: (reference: string, field: string) => Promise<string>;
+    get(reference: string, field: string): Promise<string>;
+};
+export declare function vaultCredentials(vault: ForgeZero, reference: string): {
+    name: string;
+    get(field: string): Promise<string>;
 };

package/dist/providers.js

@@ -382,7 +382,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.9";
+var VERSION = "0.1.11";
 
 // src/providers.ts
 var MISSING = new Set(["ENTRY_NOT_FOUND", "VERSION_NOT_FOUND"]);
@@ -428,10 +428,16 @@ function vaultConfig(vault, options = {}) {
     }
   };
 }
-function vaultCredentials2(vault) {
+function vaultCredentials2(vault, reference) {
+  if (reference !== undefined) {
+    return {
+      name: `vault:${reference}`,
+      get: (field) => vault.get(`${reference}.${field}`)
+    };
+  }
   return {
     name: "vault",
-    get: (reference, field) => vault.get(`${reference}.${field}`)
+    get: (reference2, field) => vault.get(`${reference2}.${field}`)
   };
 }
 export {

package/dist/schema.js

@@ -382,7 +382,7 @@ function systemdCredentials(options = {}) {
     }
   };
 }
-var VERSION = "0.1.9";
+var VERSION = "0.1.11";
 
 // src/schema.ts
 function managedSchemas(vault, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/vault",
-  "version": "0.1.9",
+	"version": "0.1.11",
   "type": "module",
 	"publishConfig": {
 		"access": "public",
@@ -43,7 +43,7 @@
     "@types/bun": "latest"
   },
   "dependencies": {
-	"@forgezero/runtime": "^0.1.6"
+	"@forgezero/runtime": "^0.1.7"
   },
   "peerDependencies": {
     "@noble/curves": "^2.2.0",