@forgezero/vault 0.1.0

package/dist/providers.d.ts

@@ -0,0 +1,66 @@
+import { ForgeZero } from './index';
+/** Mirrors `ProviderConfig` in `@forgezero/providers`, matched structurally. */
+export interface StoredProvider {
+    providerId: string;
+    /** Names one instance when a provider is configured more than once. */
+    instanceKey?: string;
+    /** 1 is tried first. */
+    priority: number;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    /** Names the vault entry holding the secret. Never the secret. */
+    secretRef: string;
+    health?: {
+        strikes: number;
+        status: 'ok' | 'degraded' | 'offline';
+        lastFailureAtTs?: number;
+    };
+}
+export interface VaultConfigOptions {
+    /**
+     * Entry name for a service's provider list. `email` → `providers.email`.
+     *
+     * Overridable because a tenant already using `providers.*` for something else
+     * should not have to rename it to adopt this.
+     */
+    entryFor?: (serviceKey: string) => string;
+    /**
+     * Persist health back to the vault.
+     *
+     * Off by default, and the default is the load-bearing choice. Health is
+     * written on every failure, and a vault write per failed send turns one dead
+     * relay into a write storm against the store you need most when things are
+     * already going wrong. Most deployments want strikes in memory and the list
+     * in the vault; turn this on when several processes must agree that a
+     * provider is dead.
+     */
+    persistHealth?: boolean;
+}
+/**
+ * Read the ordered provider list for a service out of the vault.
+ *
+ * A missing entry is an EMPTY LIST, not an error. A service nobody has
+ * configured yet is a normal state — the registry then falls through to
+ * whatever else is chained behind it, which is how bootstrap works before the
+ * first provider is ever added.
+ *
+ * A malformed entry is NOT empty. Silently treating unparseable JSON as "no
+ * providers" turns a typo into a service that appears configured and quietly
+ * sends nothing.
+ */
+export declare function vaultConfig(vault: ForgeZero, options?: VaultConfigOptions): {
+    name: string;
+    list(serviceKey: string): Promise<readonly StoredProvider[]>;
+    recordHealth(serviceKey: string, providerId: string, health: NonNullable<StoredProvider["health"]>): Promise<void>;
+};
+/**
+ * Credentials out of the vault, by the reference a provider config names.
+ *
+ * `secretRef: 'jetemail'` plus field `token` reads the entry `jetemail.token`.
+ * The reference is stored on the provider row and the secret is not, so a dump
+ * of the configuration yields the NAMES of secrets and none of their values.
+ */
+export declare function vaultCredentials(vault: ForgeZero): {
+    name: string;
+    get: (reference: string, field: string) => Promise<string>;
+};

package/dist/providers.js

@@ -0,0 +1,199 @@
+// src/index.ts
+class VaultError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultError";
+  }
+}
+var DEFAULT_SOCKET = "/run/forgezero.sock";
+function discover(environment = {}) {
+  const env = environment.env ?? {};
+  const socketPath = environment.socketPath ?? env.FORGEZERO_SOCKET ?? DEFAULT_SOCKET;
+  if (environment.socketExists?.(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";
+
+class ForgeZero {
+  credential;
+  assignment;
+  assignUrl;
+  doFetch;
+  now;
+  signer;
+  project;
+  environment;
+  constructor(options = {}) {
+    this.credential = options.credential ?? discover(options.discovery);
+    this.assignUrl = options.assignUrl ?? DEFAULT_ASSIGN_URL;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.now = options.now ?? Date.now;
+    this.signer = options.signer;
+    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();
+    const body = typeof init.body === "string" ? init.body : "";
+    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);
+    }
+    const payload = await response.json().catch(() => {
+      return;
+    });
+    if (!response.ok) {
+      throw new VaultError(payload?.error?.code ?? "REQUEST_FAILED", payload?.error?.message ?? `The vault refused with ${response.status}.`);
+    }
+    return payload;
+  }
+  async get(name, options = {}) {
+    const query = options.version ? `?version=${options.version}` : "";
+    const result = await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}${query}`);
+    return result.value;
+  }
+  async getAll() {
+    if (this.credential.mode !== "managed") {
+      throw new VaultError("MANAGED_ONLY", "getAll is available on managed compute only. Read entries by name with an API key.");
+    }
+    const result = await this.request(`/v1/vault/${this.scope()}/entries`);
+    return result.values;
+  }
+  async derived(name, field) {
+    return this.request(`/v1/entries/${encodeURIComponent(name)}/derived/${encodeURIComponent(field)}${this.scope()}`);
+  }
+  async sign(name, field, digest) {
+    return this.request(`/v1/entries/${encodeURIComponent(name)}/sign/${encodeURIComponent(field)}${this.scope()}`, { method: "POST", body: JSON.stringify({ digest }) });
+  }
+  async schemas() {
+    const payload = await this.request(`/v1/schemas${this.scope()}`);
+    return payload.schemas ?? [];
+  }
+  async list() {
+    const result = await this.request(`/v1/vault/${this.scope()}/list`);
+    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;
+  }
+  async remove(name) {
+    await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}`, {
+      method: "DELETE"
+    });
+  }
+  async* watch(options = {}) {
+    const interval = options.intervalMs ?? 15000;
+    let since = 0;
+    while (!options.signal?.aborted) {
+      const result = await this.request(`/v1/vault/${this.scope()}/changes?since=${since}`);
+      if (result.resync) {
+        since = 0;
+        continue;
+      }
+      for (const change of result.changed)
+        yield change;
+      since = result.version;
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}
+var createVault = (options = {}) => new ForgeZero(options);
+function vaultCredentials(vault) {
+  return {
+    name: "vault",
+    get: (reference, field) => vault.get(`${reference}.${field}`)
+  };
+}
+var VERSION = "0.1.0";
+
+// src/providers.ts
+var MISSING = new Set(["ENTRY_NOT_FOUND", "VERSION_NOT_FOUND"]);
+function vaultConfig(vault, options = {}) {
+  const entryFor = options.entryFor ?? ((serviceKey) => `providers.${serviceKey}`);
+  const read = async (serviceKey) => {
+    const name = entryFor(serviceKey);
+    let raw;
+    try {
+      raw = await vault.get(name);
+    } catch (error) {
+      if (error instanceof VaultError && MISSING.has(error.code))
+        return [];
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new VaultError("INVALID", `Vault entry "${name}" is not valid JSON.`);
+    }
+    if (!Array.isArray(parsed)) {
+      throw new VaultError("INVALID", `Vault entry "${name}" must be an array of providers.`);
+    }
+    return parsed;
+  };
+  return {
+    name: "vault",
+    async list(serviceKey) {
+      return (await read(serviceKey)).slice().sort((a, b) => a.priority - b.priority);
+    },
+    async recordHealth(serviceKey, providerId, health) {
+      if (!options.persistHealth)
+        return;
+      const providers = await read(serviceKey);
+      const next = providers.map((entry) => entry.providerId === providerId ? { ...entry, health } : entry);
+      await vault.set(entryFor(serviceKey), JSON.stringify(next));
+    }
+  };
+}
+function vaultCredentials2(vault) {
+  return {
+    name: "vault",
+    get: (reference, field) => vault.get(`${reference}.${field}`)
+  };
+}
+export {
+  vaultCredentials2 as vaultCredentials,
+  vaultConfig
+};

package/dist/schema.d.ts

@@ -0,0 +1,79 @@
+import { type ForgeZero } from './index';
+/**
+ * Where an entry's SHAPE comes from, and what a tenant may hold themselves.
+ *
+ * Two modes, and the choice is genuinely the tenant's:
+ *
+ *   managed   the schema lives in ForgeZero and is pulled at runtime. Pick this
+ *             when ForgeZero has to RENDER the thing — an admin screen cannot
+ *             draw a form for a shape it has never seen. Changing the schema is
+ *             then a platform operation and every tenant process picks it up
+ *             without deploying.
+ *
+ *   local     the tenant declares it in their own code. Pick this when nothing
+ *             on the platform needs to display it, which is most config. The
+ *             shape stays in their repository, reviewed with their code, and
+ *             ForgeZero stores values it never has to understand.
+ *
+ * The same pattern either way, which is the point. A tenant that starts local
+ * and later wants an admin screen changes where the schema is read from and
+ * nothing else — the validation, the derived fields and the signing calls are
+ * identical.
+ *
+ * ## Why this is not just "always managed"
+ *
+ * A schema held centrally is a shape the platform can change under a running
+ * tenant. That is exactly what you want for something the platform renders and
+ * exactly what you do not want for a tenant's private config, where a change
+ * they did not review is a deployment they did not make.
+ */
+export interface SchemaRef {
+    name: string;
+    version: number;
+}
+export interface SchemaSource {
+    readonly mode: 'managed' | 'local';
+    /** The JSON Schema for an entry name. */
+    get(name: string): Promise<{
+        schema: unknown;
+        version: number;
+    }>;
+    /** Names this source can describe. Managed sources answer from the platform. */
+    list(): Promise<readonly SchemaRef[]>;
+}
+/**
+ * Schemas pulled from ForgeZero, cached per process.
+ *
+ * Cached because an entry is read far more often than its shape changes, and a
+ * network round trip per read turns a config lookup into a dependency on the
+ * 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?: {
+    ttlMs?: number;
+    now?: () => number;
+}): SchemaSource & {
+    refresh(): void;
+};
+/**
+ * Schemas the tenant declares in their own code.
+ *
+ * No network, no cache, no failure mode. The shape is whatever they wrote, and
+ * an unknown name is an error at the call site rather than a lookup that
+ * returns nothing useful.
+ */
+export declare function localSchemas(schemas: Record<string, {
+    schema: unknown;
+    version?: number;
+}>): SchemaSource;
+/**
+ * Fall back to a local schema when the platform has none.
+ *
+ * The migration path, and the only combination that makes sense: managed FIRST,
+ * because if the platform has an opinion about a shape it renders, that opinion
+ * wins. The local copy is what keeps a tenant running while a schema is being
+ * moved, not a way to override one.
+ */
+export declare function preferManaged(managed: SchemaSource, local: SchemaSource): SchemaSource;

package/dist/schema.js

@@ -0,0 +1,222 @@
+// src/index.ts
+class VaultError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultError";
+  }
+}
+var DEFAULT_SOCKET = "/run/forgezero.sock";
+function discover(environment = {}) {
+  const env = environment.env ?? {};
+  const socketPath = environment.socketPath ?? env.FORGEZERO_SOCKET ?? DEFAULT_SOCKET;
+  if (environment.socketExists?.(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";
+
+class ForgeZero {
+  credential;
+  assignment;
+  assignUrl;
+  doFetch;
+  now;
+  signer;
+  project;
+  environment;
+  constructor(options = {}) {
+    this.credential = options.credential ?? discover(options.discovery);
+    this.assignUrl = options.assignUrl ?? DEFAULT_ASSIGN_URL;
+    this.doFetch = options.fetch ?? globalThis.fetch;
+    this.now = options.now ?? Date.now;
+    this.signer = options.signer;
+    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();
+    const body = typeof init.body === "string" ? init.body : "";
+    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);
+    }
+    const payload = await response.json().catch(() => {
+      return;
+    });
+    if (!response.ok) {
+      throw new VaultError(payload?.error?.code ?? "REQUEST_FAILED", payload?.error?.message ?? `The vault refused with ${response.status}.`);
+    }
+    return payload;
+  }
+  async get(name, options = {}) {
+    const query = options.version ? `?version=${options.version}` : "";
+    const result = await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}${query}`);
+    return result.value;
+  }
+  async getAll() {
+    if (this.credential.mode !== "managed") {
+      throw new VaultError("MANAGED_ONLY", "getAll is available on managed compute only. Read entries by name with an API key.");
+    }
+    const result = await this.request(`/v1/vault/${this.scope()}/entries`);
+    return result.values;
+  }
+  async derived(name, field) {
+    return this.request(`/v1/entries/${encodeURIComponent(name)}/derived/${encodeURIComponent(field)}${this.scope()}`);
+  }
+  async sign(name, field, digest) {
+    return this.request(`/v1/entries/${encodeURIComponent(name)}/sign/${encodeURIComponent(field)}${this.scope()}`, { method: "POST", body: JSON.stringify({ digest }) });
+  }
+  async schemas() {
+    const payload = await this.request(`/v1/schemas${this.scope()}`);
+    return payload.schemas ?? [];
+  }
+  async list() {
+    const result = await this.request(`/v1/vault/${this.scope()}/list`);
+    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;
+  }
+  async remove(name) {
+    await this.request(`/v1/vault/${this.scope()}/entries/${encodeURIComponent(name)}`, {
+      method: "DELETE"
+    });
+  }
+  async* watch(options = {}) {
+    const interval = options.intervalMs ?? 15000;
+    let since = 0;
+    while (!options.signal?.aborted) {
+      const result = await this.request(`/v1/vault/${this.scope()}/changes?since=${since}`);
+      if (result.resync) {
+        since = 0;
+        continue;
+      }
+      for (const change of result.changed)
+        yield change;
+      since = result.version;
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+}
+var createVault = (options = {}) => new ForgeZero(options);
+function vaultCredentials(vault) {
+  return {
+    name: "vault",
+    get: (reference, field) => vault.get(`${reference}.${field}`)
+  };
+}
+var VERSION = "0.1.0";
+
+// src/schema.ts
+function managedSchemas(vault, options = {}) {
+  const ttl = options.ttlMs ?? 300000;
+  const now = options.now ?? (() => Date.now());
+  const cache = new Map;
+  return {
+    mode: "managed",
+    refresh() {
+      cache.clear();
+    },
+    async get(name) {
+      const hit = cache.get(name);
+      if (hit && now() - hit.at < ttl)
+        return hit.value;
+      const raw = await vault.get(`__schema__${name}`);
+      let value;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} is not JSON.`);
+      }
+      if (!value?.schema) {
+        throw new VaultError("SCHEMA_MALFORMED", `The schema for ${name} has no shape.`);
+      }
+      cache.set(name, { at: now(), value });
+      return value;
+    },
+    async list() {
+      return await vault.schemas?.() ?? [];
+    }
+  };
+}
+function localSchemas(schemas) {
+  return {
+    mode: "local",
+    async get(name) {
+      const entry = schemas[name];
+      if (!entry) {
+        throw new VaultError("SCHEMA_UNKNOWN", `No local schema is declared for ${name}. Declare it, or use a managed source.`);
+      }
+      return { schema: entry.schema, version: entry.version ?? 1 };
+    },
+    async list() {
+      return Object.entries(schemas).map(([name, entry]) => ({
+        name,
+        version: entry.version ?? 1
+      }));
+    }
+  };
+}
+function preferManaged(managed, local) {
+  return {
+    mode: "managed",
+    async get(name) {
+      try {
+        return await managed.get(name);
+      } catch {
+        return local.get(name);
+      }
+    },
+    async list() {
+      const [a, b] = await Promise.all([managed.list().catch(() => []), local.list()]);
+      const seen = new Set(a.map((entry) => entry.name));
+      return [...a, ...b.filter((entry) => !seen.has(entry.name))];
+    }
+  };
+}
+export {
+  preferManaged,
+  managedSchemas,
+  localSchemas
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "//": "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",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    },
+    "./env": {
+      "types": "./dist/env.d.ts",
+      "default": "./dist/env.js"
+    },
+    "./frameworks": {
+      "types": "./dist/frameworks.d.ts",
+      "default": "./dist/frameworks.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "bun build src/index.ts src/config.ts src/schema.ts src/env.ts src/frameworks.ts src/providers.ts --root src --outdir dist --target browser --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"
+  },
+  "description": "ForgeZero vault client. Credential discovery, versioned secrets, node assignment.",
+  "keywords": [
+    "secrets",
+    "vault",
+    "secrets-management",
+    "env",
+    "post-quantum",
+    "sdk",
+    "envless",
+    "dotenv",
+    "sveltekit",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "homepage": "https://forgezero.net/docs/vault-package",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axxra/forgezero.git",
+    "directory": "packages/vault"
+  },
+  "bugs": "https://github.com/axxra/forgezero/issues",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}