@forgezero/vault 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @forgezero/vault
+
+**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.
+
+This one talks to a ForgeZero vault, so it needs an account. The other three
+packages do not.
+
+```bash
+bun add @forgezero/vault
+```
+
+```ts
+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
+```
+
+## Envless
+
+Fill `process.env` at boot and change nothing else in your application:
+
+```ts
+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
+
+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.
+
+## The API key is a seed, not a password
+
+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
+
+An entry can declare fields the tenant never holds. Two custody modes:
+
+- **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.
+
+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.
+
+## Subpaths
+
+| import | what it is |
+|---|---|
+| `@forgezero/vault` | the client — get, list, write, rotate, `derived`, `sign` |
+| `/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 |
+
+## 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.
+
+Full documentation: **https://forgezero.net/docs/vault-package**
+
+## Licence
+
+MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+deploys.

package/dist/config.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `.fz/config.json` — what a project declares once, so nothing else needs flags.
+ *
+ * Every command that touches a project needs the same four facts: which project,
+ * which environment, which secrets, and what to call them in the process. Passed
+ * as flags they get typed differently by every person and every CI job; put in a
+ * file they are reviewed like code and diff like code.
+ *
+ * ## JSON, not YAML
+ *
+ * A YAML parser is a third-party dependency, and this package claims to have
+ * none — it ends up inside a tenant's production application, where every edge
+ * in its dependency graph is one they did not choose. JSON is in the runtime.
+ * (`.fz/deploy.yaml` is a different file read by a different tool on our side of
+ * the wire, where the dependency is ours to carry.)
+ *
+ * ## What is deliberately NOT in here
+ *
+ * No secrets, no API key, no endpoint. This file is committed. The credential
+ * comes from the agent socket or `FORGEZERO_API_KEY`, and the day somebody adds
+ * a `token` field here is the day the file starts leaking in pull requests.
+ * `assertNoSecrets` fails the load rather than trusting that nobody will.
+ */
+export declare class ConfigError extends Error {
+    readonly code: 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'CONFIG_HAS_SECRET' | 'UNKNOWN_ENVIRONMENT';
+    constructor(code: 'CONFIG_NOT_FOUND' | 'CONFIG_INVALID' | 'CONFIG_HAS_SECRET' | 'UNKNOWN_ENVIRONMENT', message: string);
+}
+/** How a secret is named in the process, when it differs from the entry key. */
+export interface SecretBinding {
+    /** Vault entry key. */
+    entry: string;
+    /** Environment variable name. Defaults to `entry`. */
+    as?: string;
+    /**
+     * Absent is a hard failure at boot rather than an undefined at first use.
+     *
+     * Default true, because the alternative is a service that starts, looks
+     * healthy, and fails on whichever request first touches the missing value.
+     */
+    required?: boolean;
+}
+export interface FzConfig {
+    /** Project slug in ForgeZero. */
+    project: string;
+    /** Default environment. Overridden by `FORGEZERO_ENVIRONMENT` or a flag. */
+    environment: string;
+    /**
+     * Which secrets to load, and what to call them.
+     *
+     * An explicit list rather than "everything in the project". A process that
+     * pulls every secret it can reach holds credentials it never uses, and the
+     * blast radius of a memory dump becomes the whole project rather than the
+     * five things this service actually needs.
+     */
+    secrets: readonly (string | SecretBinding)[];
+    /**
+     * Let the vault overwrite a variable that is already set.
+     *
+     * Default FALSE, matching dotenv: a value already in the environment wins, so
+     * a developer can override one thing for an afternoon without editing config.
+     * Anything shadowed is REPORTED at boot — a production secret silently losing
+     * to a stale export is otherwise the hardest class of bug in this area.
+     */
+    override?: boolean;
+    /** Prefix applied to every variable name. `FZ_` → `FZ_DATABASE_URL`. */
+    prefix?: string;
+    /** Per-environment overrides, merged over the top level. */
+    environments?: Record<string, Partial<Omit<FzConfig, 'environments'>>>;
+    /** Framework, when auto-setup needs to know. */
+    framework?: 'sveltekit' | 'nextjs' | 'node' | 'bun';
+}
+export declare const CONFIG_PATHS: readonly [".fz/config.json", "fz.config.json"];
+export declare function assertNoSecrets(raw: Record<string, unknown>, path?: string): void;
+export declare function parseConfig(text: string): FzConfig;
+/**
+ * Resolve for one environment.
+ *
+ * Environment blocks are merged over the top level rather than replacing it, so
+ * `production` can change one field without restating the list — restating it is
+ * how one environment ends up missing a secret the others have.
+ */
+export declare function resolveConfig(config: FzConfig, environment?: string): FzConfig;
+/** Normalise the two spellings into one, with the prefix applied. */
+export declare function bindingsOf(config: FzConfig): readonly Required<SecretBinding>[];
+export interface LoadOptions {
+    /** Where to start looking. Walks up to the filesystem root. */
+    cwd?: string;
+    readFile?: (path: string) => string | undefined;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Find the config by walking up from `cwd`.
+ *
+ * Walking up rather than requiring an exact path, because the same command is
+ * run from the repository root, from a workspace package and from a CI step with
+ * a different working directory — and a tool that only works from one of those
+ * gets wrapped in a script that hard-codes a path.
+ *
+ * `readFile` is injected so this stays runtime-agnostic: the same code has to
+ * work under Bun, Node and a bundler that has no `fs` at all.
+ */
+export declare function loadConfig(options?: LoadOptions): {
+    config: FzConfig;
+    path: string;
+};
+/** What `fz init` writes. Kept here so the tool and the reader agree on the shape. */
+export declare function exampleConfig(args: {
+    project: string;
+    framework?: FzConfig['framework'];
+}): string;

package/dist/config.js

@@ -0,0 +1,120 @@
+// src/config.ts
+class ConfigError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ConfigError";
+  }
+}
+var CONFIG_PATHS = [".fz/config.json", "fz.config.json"];
+var FORBIDDEN_KEYS = ["token", "apikey", "api_key", "secret", "password", "credential", "key"];
+function assertNoSecrets(raw, path = "") {
+  for (const [name, value] of Object.entries(raw)) {
+    const lowered = name.toLowerCase();
+    if (name !== "secrets" && FORBIDDEN_KEYS.some((word) => lowered.includes(word))) {
+      throw new ConfigError("CONFIG_HAS_SECRET", `"${path}${name}" looks like a credential. This file is committed — the credential comes from the agent socket or FORGEZERO_API_KEY, never from here.`);
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      assertNoSecrets(value, `${path}${name}.`);
+    }
+  }
+}
+function parseConfig(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (cause) {
+    throw new ConfigError("CONFIG_INVALID", `Not valid JSON: ${cause instanceof Error ? cause.message : "parse failed"}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ConfigError("CONFIG_INVALID", "The config must be a JSON object.");
+  }
+  const config = raw;
+  assertNoSecrets(config);
+  for (const field of ["project", "environment"]) {
+    if (typeof config[field] !== "string" || config[field].length === 0) {
+      throw new ConfigError("CONFIG_INVALID", `"${field}" is required and must be a non-empty string.`);
+    }
+  }
+  if (!Array.isArray(config.secrets)) {
+    throw new ConfigError("CONFIG_INVALID", '"secrets" is required. Naming what this service needs is the point — a process that pulls everything it can reach holds credentials it never uses.');
+  }
+  for (const entry of config.secrets) {
+    const key = typeof entry === "string" ? entry : entry?.entry;
+    if (typeof key !== "string" || key.length === 0) {
+      throw new ConfigError("CONFIG_INVALID", "Every secret must be a name, or an object with `entry`.");
+    }
+  }
+  return config;
+}
+function resolveConfig(config, environment) {
+  const target = environment ?? config.environment;
+  const overrides = config.environments?.[target];
+  if (environment && config.environments && !overrides) {
+    const known = Object.keys(config.environments).join(", ");
+    throw new ConfigError("UNKNOWN_ENVIRONMENT", `"${target}" is not declared in this config. Known environments: ${known || "none"}.`);
+  }
+  const { environments: _dropped, ...base } = config;
+  return { ...base, ...overrides, environment: target };
+}
+function bindingsOf(config) {
+  const prefix = config.prefix ?? "";
+  return config.secrets.map((entry) => {
+    const binding = typeof entry === "string" ? { entry } : entry;
+    return {
+      entry: binding.entry,
+      as: `${prefix}${binding.as ?? binding.entry}`,
+      required: binding.required ?? true
+    };
+  });
+}
+function loadConfig(options = {}) {
+  const read = options.readFile;
+  if (!read) {
+    throw new ConfigError("CONFIG_NOT_FOUND", "loadConfig needs a readFile implementation.");
+  }
+  let directory = options.cwd ?? ".";
+  const seen = [];
+  for (let depth = 0;depth < 32; depth += 1) {
+    for (const candidate of CONFIG_PATHS) {
+      const path = `${directory}/${candidate}`.replace(/\/+/g, "/");
+      seen.push(path);
+      const text = read(path);
+      if (text !== undefined) {
+        const parsed = parseConfig(text);
+        const environment = options.env?.FORGEZERO_ENVIRONMENT;
+        return { config: resolveConfig(parsed, environment), path };
+      }
+    }
+    const parent = directory.replace(/\/[^/]+\/?$/, "");
+    if (parent === directory || parent === "")
+      break;
+    directory = parent;
+  }
+  throw new ConfigError("CONFIG_NOT_FOUND", `No .fz/config.json found from ${options.cwd ?? "."} upwards. Run \`fz init\` to create one.`);
+}
+function exampleConfig(args) {
+  return `${JSON.stringify({
+    project: args.project,
+    environment: "development",
+    framework: args.framework ?? "node",
+    secrets: ["DATABASE_URL", { entry: "STRIPE_SECRET", as: "STRIPE_SECRET_KEY" }],
+    environments: {
+      development: {},
+      staging: {},
+      production: { override: true }
+    }
+  }, null, 2)}
+`;
+}
+export {
+  resolveConfig,
+  parseConfig,
+  loadConfig,
+  exampleConfig,
+  bindingsOf,
+  assertNoSecrets,
+  ConfigError,
+  CONFIG_PATHS
+};

package/dist/env.d.ts

@@ -0,0 +1,101 @@
+import { type FzConfig } from './config';
+/**
+ * Envless — `process.env` filled from the vault, and nothing written to disk.
+ *
+ * The point is that existing code does not change. A service reading
+ * `process.env.DATABASE_URL` keeps reading it; what changes is where the value
+ * came from and, crucially, that it never existed as a file. A `.env` on a box
+ * is the single most common way a credential leaves a building: it survives the
+ * process, it lands in backups, it gets copied to a laptop for debugging, and it
+ * is readable by every other process running as that user.
+ *
+ * ## Three rules, all of them the reason this is a module and not four lines
+ *
+ * **Fail at boot, never at first use.** Every required secret is fetched before
+ * the process is allowed to serve anything. The alternative is a container that
+ * starts, passes its health check, and fails on whichever request first touches
+ * the missing value — at 3am, on one endpoint, looking like an application bug.
+ *
+ * **Never at build time.** This is the rule that actually protects anything. A
+ * bundler that inlines `process.env.X` bakes the value into a JavaScript file
+ * that ships to a CDN. SvelteKit's `$env/static/private` and Next's
+ * `next.config.js` `env` block both do exactly that. So `hydrateEnv` refuses to
+ * run when it can tell it is inside a build, rather than trusting the caller to
+ * only wire it up in the right place.
+ *
+ * **Report what was shadowed.** By default an existing variable wins, matching
+ * dotenv, so a developer can override one value for an afternoon. The failure
+ * mode of that default is a stale `export DATABASE_URL` in a shell profile
+ * silently beating production — so anything shadowed is named in the result and
+ * logged. A quiet precedence rule is the hardest bug in this area.
+ */
+export declare class EnvError extends Error {
+    readonly code: 'MISSING_SECRET' | 'BUILD_TIME_REFUSED' | 'FETCH_FAILED';
+    readonly missing?: readonly string[] | undefined;
+    constructor(code: 'MISSING_SECRET' | 'BUILD_TIME_REFUSED' | 'FETCH_FAILED', message: string, missing?: readonly string[] | undefined);
+}
+/** Just enough of `ForgeZero` to fetch. Structural, so tests need no client. */
+export interface SecretReader {
+    get(entry: string, options?: {
+        environment?: string;
+    }): Promise<string | undefined>;
+}
+export interface HydrateOptions {
+    config: FzConfig;
+    vault: SecretReader;
+    /** Defaults to `globalThis.process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Escape hatch for a caller that genuinely knows better. See `isBuildTime`. */
+    allowDuringBuild?: boolean;
+    onReport?: (report: HydrateReport) => void;
+}
+export interface HydrateReport {
+    /** Names now set from the vault. */
+    loaded: readonly string[];
+    /**
+     * Names the vault had a value for, which an existing variable beat.
+     *
+     * Never empty silently — this is the list somebody needs when production is
+     * reading the wrong database.
+     */
+    shadowed: readonly string[];
+    /** Optional secrets that were absent. Required ones throw instead. */
+    skipped: readonly string[];
+    environment: string;
+    project: string;
+}
+/**
+ * Whether we are inside a build rather than a running server.
+ *
+ * Detected from the signals each framework actually sets, because the
+ * consequence of getting it wrong is a secret in a client bundle — a failure
+ * that is silent, permanent once published, and not fixed by rotating alone.
+ *
+ * Deliberately conservative: any one signal is enough to refuse. A false
+ * positive costs a developer one explicit flag; a false negative costs a
+ * credential.
+ */
+export declare function isBuildTime(env?: Record<string, string | undefined>): boolean;
+/**
+ * Fetch every declared secret and put it in the environment.
+ *
+ * Fetched in parallel and applied together: a partial application leaves the
+ * process holding half its configuration, which is strictly worse than holding
+ * none because it will start.
+ */
+export declare function hydrateEnv(options: HydrateOptions): Promise<HydrateReport>;
+/**
+ * The default boot line.
+ *
+ * Names counts and variable NAMES, never a value or any part of one. A log line
+ * that helpfully prints the first four characters of a secret is a log line that
+ * puts a secret in a log aggregator with weaker access rules than the vault.
+ */
+export declare function describeReport(report: HydrateReport): string;
+/**
+ * Remove what we set.
+ *
+ * For a test that must not leak state into the next one, and for a process
+ * dropping privileges before exec'ing a child that should not inherit them.
+ */
+export declare function clearEnv(report: HydrateReport, env?: Record<string, string | undefined>): void;

package/dist/env.js

@@ -0,0 +1,192 @@
+// src/config.ts
+class ConfigError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ConfigError";
+  }
+}
+var CONFIG_PATHS = [".fz/config.json", "fz.config.json"];
+var FORBIDDEN_KEYS = ["token", "apikey", "api_key", "secret", "password", "credential", "key"];
+function assertNoSecrets(raw, path = "") {
+  for (const [name, value] of Object.entries(raw)) {
+    const lowered = name.toLowerCase();
+    if (name !== "secrets" && FORBIDDEN_KEYS.some((word) => lowered.includes(word))) {
+      throw new ConfigError("CONFIG_HAS_SECRET", `"${path}${name}" looks like a credential. This file is committed — the credential comes from the agent socket or FORGEZERO_API_KEY, never from here.`);
+    }
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      assertNoSecrets(value, `${path}${name}.`);
+    }
+  }
+}
+function parseConfig(text) {
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (cause) {
+    throw new ConfigError("CONFIG_INVALID", `Not valid JSON: ${cause instanceof Error ? cause.message : "parse failed"}`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ConfigError("CONFIG_INVALID", "The config must be a JSON object.");
+  }
+  const config = raw;
+  assertNoSecrets(config);
+  for (const field of ["project", "environment"]) {
+    if (typeof config[field] !== "string" || config[field].length === 0) {
+      throw new ConfigError("CONFIG_INVALID", `"${field}" is required and must be a non-empty string.`);
+    }
+  }
+  if (!Array.isArray(config.secrets)) {
+    throw new ConfigError("CONFIG_INVALID", '"secrets" is required. Naming what this service needs is the point — a process that pulls everything it can reach holds credentials it never uses.');
+  }
+  for (const entry of config.secrets) {
+    const key = typeof entry === "string" ? entry : entry?.entry;
+    if (typeof key !== "string" || key.length === 0) {
+      throw new ConfigError("CONFIG_INVALID", "Every secret must be a name, or an object with `entry`.");
+    }
+  }
+  return config;
+}
+function resolveConfig(config, environment) {
+  const target = environment ?? config.environment;
+  const overrides = config.environments?.[target];
+  if (environment && config.environments && !overrides) {
+    const known = Object.keys(config.environments).join(", ");
+    throw new ConfigError("UNKNOWN_ENVIRONMENT", `"${target}" is not declared in this config. Known environments: ${known || "none"}.`);
+  }
+  const { environments: _dropped, ...base } = config;
+  return { ...base, ...overrides, environment: target };
+}
+function bindingsOf(config) {
+  const prefix = config.prefix ?? "";
+  return config.secrets.map((entry) => {
+    const binding = typeof entry === "string" ? { entry } : entry;
+    return {
+      entry: binding.entry,
+      as: `${prefix}${binding.as ?? binding.entry}`,
+      required: binding.required ?? true
+    };
+  });
+}
+function loadConfig(options = {}) {
+  const read = options.readFile;
+  if (!read) {
+    throw new ConfigError("CONFIG_NOT_FOUND", "loadConfig needs a readFile implementation.");
+  }
+  let directory = options.cwd ?? ".";
+  const seen = [];
+  for (let depth = 0;depth < 32; depth += 1) {
+    for (const candidate of CONFIG_PATHS) {
+      const path = `${directory}/${candidate}`.replace(/\/+/g, "/");
+      seen.push(path);
+      const text = read(path);
+      if (text !== undefined) {
+        const parsed = parseConfig(text);
+        const environment = options.env?.FORGEZERO_ENVIRONMENT;
+        return { config: resolveConfig(parsed, environment), path };
+      }
+    }
+    const parent = directory.replace(/\/[^/]+\/?$/, "");
+    if (parent === directory || parent === "")
+      break;
+    directory = parent;
+  }
+  throw new ConfigError("CONFIG_NOT_FOUND", `No .fz/config.json found from ${options.cwd ?? "."} upwards. Run \`fz init\` to create one.`);
+}
+function exampleConfig(args) {
+  return `${JSON.stringify({
+    project: args.project,
+    environment: "development",
+    framework: args.framework ?? "node",
+    secrets: ["DATABASE_URL", { entry: "STRIPE_SECRET", as: "STRIPE_SECRET_KEY" }],
+    environments: {
+      development: {},
+      staging: {},
+      production: { override: true }
+    }
+  }, null, 2)}
+`;
+}
+
+// src/env.ts
+class EnvError extends Error {
+  code;
+  missing;
+  constructor(code, message, missing) {
+    super(message);
+    this.code = code;
+    this.missing = missing;
+    this.name = "EnvError";
+  }
+}
+function isBuildTime(env = {}) {
+  return Boolean(env.SVELTEKIT_BUILD || env.NEXT_PHASE?.includes("build") || env.VITE_BUILD || env.npm_lifecycle_event === "build" || env.FORGEZERO_BUILD === "1");
+}
+async function hydrateEnv(options) {
+  const env = options.env ?? globalThis.process?.env ?? {};
+  if (!options.allowDuringBuild && isBuildTime(env)) {
+    throw new EnvError("BUILD_TIME_REFUSED", "Refusing to load secrets during a build. A bundler that inlines process.env writes the value into a JavaScript file that ships to a browser. Load them at RUNTIME — a SvelteKit `handle` hook, or Next.js `instrumentation.ts`.");
+  }
+  const bindings = bindingsOf(options.config);
+  const results = await Promise.all(bindings.map(async (binding) => {
+    try {
+      const value = await options.vault.get(binding.entry, {
+        environment: options.config.environment
+      });
+      return { binding, value };
+    } catch (cause) {
+      throw new EnvError("FETCH_FAILED", `Could not read "${binding.entry}": ${cause instanceof Error ? cause.message : "unknown error"}`);
+    }
+  }));
+  const missing = results.filter((result) => result.value === undefined && result.binding.required).map((result) => result.binding.entry);
+  if (missing.length > 0) {
+    throw new EnvError("MISSING_SECRET", `Missing in ${options.config.project}/${options.config.environment}: ${missing.join(", ")}. Add them, or mark them \`"required": false\` if the service can genuinely start without them.`, missing);
+  }
+  const loaded = [];
+  const shadowed = [];
+  const skipped = [];
+  for (const { binding, value } of results) {
+    if (value === undefined) {
+      skipped.push(binding.entry);
+      continue;
+    }
+    if (env[binding.as] !== undefined && !options.config.override) {
+      shadowed.push(binding.as);
+      continue;
+    }
+    env[binding.as] = value;
+    loaded.push(binding.as);
+  }
+  const report = {
+    loaded,
+    shadowed,
+    skipped,
+    environment: options.config.environment,
+    project: options.config.project
+  };
+  options.onReport?.(report);
+  return report;
+}
+function describeReport(report) {
+  const parts = [`[forgezero] ${report.loaded.length} secret(s) → env`];
+  parts.push(`${report.project}/${report.environment}`);
+  if (report.shadowed.length > 0) {
+    parts.push(`SHADOWED by existing env: ${report.shadowed.join(", ")}`);
+  }
+  if (report.skipped.length > 0) {
+    parts.push(`absent (optional): ${report.skipped.join(", ")}`);
+  }
+  return parts.join(" · ");
+}
+function clearEnv(report, env = globalThis.process?.env ?? {}) {
+  for (const name of report.loaded)
+    delete env[name];
+}
+export {
+  isBuildTime,
+  hydrateEnv,
+  describeReport,
+  clearEnv,
+  EnvError
+};