@super-repo/envx 0.4.0 → 0.4.1-b.2

package/dist/plugins/azure.d.ts

@@ -0,0 +1,46 @@
+import { SecretProvider } from './types.js';
+export interface AzureKeyVaultOptions {
+    /** Vault URL (e.g. "https://my-vault.vault.azure.net"). */
+    readonly vaultUrl: string;
+    /**
+     * Custom credential. Defaults to `new DefaultAzureCredential()` from
+     * `@azure/identity` — which walks env vars, managed identity, Azure
+     * CLI, etc. Override for tests or specialized credential chains.
+     */
+    readonly credential?: unknown;
+    /** Pre-built SecretClient for tests. */
+    readonly client?: {
+        getSecret: (name: string, opts?: {
+            version?: string;
+        }) => Promise<{
+            value?: string | null;
+        }>;
+    };
+    /** Provider name, defaults to `"azure-keyvault"`. */
+    readonly name?: string;
+}
+/**
+ * Azure Key Vault provider.
+ *
+ * ```ts
+ * import { azureKeyVault } from "@super-repo/envx/plugins/azure";
+ *
+ * const az = azureKeyVault({ vaultUrl: "https://my-vault.vault.azure.net" });
+ * await az.preload(["prod-db", "prod-api"]);
+ *
+ * envx({ resolvers: { [az.name]: az.resolve } });
+ * ```
+ *
+ * Reference shape:
+ *
+ * ```
+ * DB_URL=${azure-keyvault:prod-db}
+ * API_KEY=${azure-keyvault:prod-api@<version>}
+ * ```
+ *
+ * Uses `@azure/keyvault-secrets` + `@azure/identity` (lazy-loaded):
+ *
+ *     pnpm add @azure/keyvault-secrets @azure/identity
+ */
+export declare function azureKeyVault(opts: AzureKeyVaultOptions): SecretProvider;
+//# sourceMappingURL=azure.d.ts.map

package/dist/plugins/azure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"azure.d.ts","sourceRoot":"","sources":["../../src/plugins/azure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjF,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC;YAChE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SACvB,CAAC,CAAC;KACJ,CAAC;IACF,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,cAAc,CAgDxE"}

package/dist/plugins/azure.js

@@ -0,0 +1,2 @@
+import { t as azureKeyVault } from "../chunks/azure-Cmh5-dPn.js";
+export { azureKeyVault };

package/dist/plugins/doppler.d.ts

@@ -0,0 +1,36 @@
+import { SecretProvider } from './types.js';
+export interface DopplerOptions {
+    /** Doppler service token (per-config). Required. */
+    readonly token: string;
+    /** Override Doppler's REST endpoint (testing / self-hosted). */
+    readonly endpoint?: string;
+    /** Override the global fetch (testing). */
+    readonly fetchImpl?: typeof fetch;
+    /** Provider name, defaults to `"doppler"`. */
+    readonly name?: string;
+}
+/**
+ * Doppler provider — fetches secrets via the REST API using a service
+ * token. No SDK install required (uses native `fetch`).
+ *
+ * ```ts
+ * import { doppler } from "@super-repo/envx/plugins/doppler";
+ *
+ * const dop = doppler({ token: process.env.DOPPLER_TOKEN! });
+ * await dop.preload(["DATABASE_URL", "API_KEY"]);
+ *
+ * envx({ resolvers: { [dop.name]: dop.resolve } });
+ * ```
+ *
+ * Reference shape — IDs are Doppler secret names:
+ *
+ * ```
+ * DATABASE_URL=${doppler:DATABASE_URL}
+ * API_KEY=${doppler:API_KEY}
+ * ```
+ *
+ * Service-account tokens scope to one config (project + environment),
+ * so you typically don't need to specify project/config explicitly.
+ */
+export declare function doppler(opts: DopplerOptions): SecretProvider;
+//# sourceMappingURL=doppler.d.ts.map

package/dist/plugins/doppler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doppler.d.ts","sourceRoot":"","sources":["../../src/plugins/doppler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIhE,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CA0B5D"}

package/dist/plugins/doppler.js

@@ -0,0 +1,2 @@
+import { t as doppler } from "../chunks/doppler-BkQsajIp.js";
+export { doppler };

package/dist/plugins/gcp.d.ts

@@ -0,0 +1,48 @@
+import { SecretProvider } from './types.js';
+export interface GcpSecretsOptions {
+    /** Google Cloud project ID (e.g. "acme-prod"). */
+    readonly projectId: string;
+    /**
+     * Default version alias. `"latest"` (the default) reads the most
+     * recent enabled version. Override per-id by including `@<version>`
+     * in the reference: `${gcp-secrets:my-secret@3}`.
+     */
+    readonly version?: string;
+    /** Optional pre-built SecretManagerServiceClient (e.g. for tests). */
+    readonly client?: {
+        accessSecretVersion: (req: {
+            name: string;
+        }) => Promise<[{
+            payload?: {
+                data?: Buffer | string | null;
+            };
+        } | null, ...unknown[]]>;
+    };
+    /** Provider name, defaults to `"gcp-secrets"`. */
+    readonly name?: string;
+}
+/**
+ * GCP Secret Manager provider.
+ *
+ * ```ts
+ * import { gcpSecrets } from "@super-repo/envx/plugins/gcp";
+ *
+ * const gcp = gcpSecrets({ projectId: "acme-prod" });
+ * await gcp.preload(["prod-db-url", "prod-api-key"]);
+ *
+ * envx({ resolvers: { [gcp.name]: gcp.resolve } });
+ * ```
+ *
+ * Reference shape:
+ *
+ * ```
+ * DB_URL=${gcp-secrets:prod-db-url}            # uses default version (latest)
+ * API_KEY=${gcp-secrets:prod-api-key@3}        # pin to version 3
+ * ```
+ *
+ * Uses `@google-cloud/secret-manager` (lazy-loaded). Install:
+ *
+ *     pnpm add @google-cloud/secret-manager
+ */
+export declare function gcpSecrets(opts: GcpSecretsOptions): SecretProvider;
+//# sourceMappingURL=gcp.d.ts.map

package/dist/plugins/gcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp.d.ts","sourceRoot":"","sources":["../../src/plugins/gcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjF,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,mBAAmB,EAAE,CAAC,GAAG,EAAE;YACzB,IAAI,EAAE,MAAM,CAAC;SACd,KAAK,OAAO,CAAC,CAAC;YAAE,OAAO,CAAC,EAAE;gBAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;aAAE,CAAA;SAAE,GAAG,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC;KACvF,CAAC;IACF,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAgClE"}

package/dist/plugins/gcp.js

@@ -0,0 +1,2 @@
+import { t as gcpSecrets } from "../chunks/gcp-Dq7QncPS.js";
+export { gcpSecrets };

package/dist/plugins/index.d.ts

@@ -0,0 +1,11 @@
+export { buildProvider, MissingSdkError, type SecretProvider, } from './types.js';
+export { autoPreload, asResolvers, type AutoPreloadOptions } from './auto-preload.js';
+export { createSecretRuntime, type SecretRuntime, type SecretRuntimeOptions, type SecretRuntimeStats, } from './runtime.js';
+export { awsSecrets, type AwsSecretsOptions } from './aws.js';
+export { gcpSecrets, type GcpSecretsOptions } from './gcp.js';
+export { azureKeyVault, type AzureKeyVaultOptions } from './azure.js';
+export { hcVault, type HcVaultOptions } from './vault.js';
+export { onePassword, type OnePasswordOptions } from './op.js';
+export { doppler, type DopplerOptions } from './doppler.js';
+export { infisical, type InfisicalOptions } from './infisical.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EACb,eAAe,EACf,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMtF,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,11 @@
+import { n as buildProvider, t as MissingSdkError } from "../chunks/types-COrFYR0z.js";
+import { n as autoPreload, t as asResolvers } from "../chunks/auto-preload-CrSuZDg1.js";
+import { t as createSecretRuntime } from "../chunks/runtime-BIEf_Dgo.js";
+import { t as awsSecrets } from "../chunks/aws-DgcXfw-Y.js";
+import { t as gcpSecrets } from "../chunks/gcp-Dq7QncPS.js";
+import { t as azureKeyVault } from "../chunks/azure-Cmh5-dPn.js";
+import { t as hcVault } from "../chunks/vault-BWdO9DFO.js";
+import { t as onePassword } from "../chunks/op-CG9UWJIj.js";
+import { t as doppler } from "../chunks/doppler-BkQsajIp.js";
+import { t as infisical } from "../chunks/infisical-CO073rdx.js";
+export { MissingSdkError, asResolvers, autoPreload, awsSecrets, azureKeyVault, buildProvider, createSecretRuntime, doppler, gcpSecrets, hcVault, infisical, onePassword };

package/dist/plugins/infisical.d.ts

@@ -0,0 +1,51 @@
+import { SecretProvider } from './types.js';
+export interface InfisicalOptions {
+    /**
+     * Service token or universal-auth access token. Required. Pass a
+     * universal-auth token from your machine identity flow, or a project
+     * service token for simpler setups.
+     */
+    readonly token: string;
+    /** Project ID (workspace ID, "workspaceId"). */
+    readonly projectId: string;
+    /** Environment slug — `dev`, `staging`, `prod`, etc. */
+    readonly environment: string;
+    /**
+     * Folder path inside the environment. Defaults to `/`.
+     */
+    readonly secretPath?: string;
+    /** Self-hosted Infisical endpoint. Defaults to the SaaS host. */
+    readonly endpoint?: string;
+    /** Override the global fetch (testing). */
+    readonly fetchImpl?: typeof fetch;
+    /** Provider name, defaults to `"infisical"`. */
+    readonly name?: string;
+}
+/**
+ * Infisical provider — uses the v3 REST API with a service / machine
+ * identity token. No SDK install required (uses native `fetch`).
+ *
+ * ```ts
+ * import { infisical } from "@super-repo/envx/plugins/infisical";
+ *
+ * const inf = infisical({
+ *   token: process.env.INFISICAL_TOKEN!,
+ *   projectId: process.env.INFISICAL_PROJECT_ID!,
+ *   environment: "prod",
+ * });
+ * await inf.preload(["DATABASE_URL", "API_KEY"]);
+ *
+ * envx({ resolvers: { [inf.name]: inf.resolve } });
+ * ```
+ *
+ * Reference shape — IDs are Infisical secret names:
+ *
+ * ```
+ * DATABASE_URL=${infisical:DATABASE_URL}
+ * API_KEY=${infisical:API_KEY}
+ * ```
+ *
+ * Self-hosted? Pass `endpoint: "https://infisical.example.com"`.
+ */
+export declare function infisical(opts: InfisicalOptions): SecretProvider;
+//# sourceMappingURL=infisical.d.ts.map

package/dist/plugins/infisical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infisical.d.ts","sourceRoot":"","sources":["../../src/plugins/infisical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIhE,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAkChE"}

package/dist/plugins/infisical.js

@@ -0,0 +1,2 @@
+import { t as infisical } from "../chunks/infisical-CO073rdx.js";
+export { infisical };

package/dist/plugins/op.d.ts

@@ -0,0 +1,52 @@
+import { SecretProvider } from './types.js';
+export interface OnePasswordOptions {
+    /**
+     * Service account token. When set, the plugin uses the @1password/sdk
+     * directly. When unset, it falls back to spawning the local `op` CLI
+     * (which gets credentials from your signed-in session).
+     */
+    readonly token?: string;
+    /**
+     * Override the SDK / CLI loader. Useful for tests — pass a function
+     * that returns the secret value for a given reference.
+     */
+    readonly fetcher?: (ref: string) => Promise<string>;
+    /** Provider name, defaults to `"op"` (matches the conventional `op://` URI scheme). */
+    readonly name?: string;
+}
+/**
+ * 1Password provider.
+ *
+ * Two execution modes:
+ *   - **SDK mode** (when `token` is set): uses `@1password/sdk`, no CLI needed.
+ *   - **CLI mode** (when `token` is unset): exec's the `op` binary,
+ *     reads creds from your signed-in session. No SDK install required.
+ *
+ * ```ts
+ * import { onePassword } from "@super-repo/envx/plugins/op";
+ *
+ * // CLI mode — works on developer machines that ran `op signin` once.
+ * const op = onePassword();
+ *
+ * // SDK mode — for CI / containers.
+ * const op = onePassword({ token: process.env.OP_SERVICE_ACCOUNT_TOKEN! });
+ *
+ * await op.preload([
+ *   "op://prod/Database/url",
+ *   "op://prod/API/key",
+ * ]);
+ *
+ * envx({ resolvers: { [op.name]: op.resolve } });
+ * ```
+ *
+ * Reference shape — pass the full `op://vault/item/field` URI:
+ *
+ * ```
+ * DB_URL=${op:op://prod/Database/url}
+ * API_KEY=${op:op://prod/API/key}
+ * ```
+ *
+ * SDK install (only if you set `token`): `pnpm add @1password/sdk`
+ */
+export declare function onePassword(opts?: OnePasswordOptions): SecretProvider;
+//# sourceMappingURL=op.d.ts.map

package/dist/plugins/op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.d.ts","sourceRoot":"","sources":["../../src/plugins/op.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkC,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjF,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,uFAAuF;IACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,cAAc,CAuDzE"}

package/dist/plugins/op.js

@@ -0,0 +1,2 @@
+import { t as onePassword } from "../chunks/op-CG9UWJIj.js";
+export { onePassword };

package/dist/plugins/runtime.d.ts

@@ -0,0 +1,95 @@
+import { SecretProvider } from './types.js';
+/**
+ * Async-first secret accessor for runtime / edge code.
+ *
+ * Use this when the security model is "secrets never leave the source"
+ * — the app references secrets like `${vault:prod/db}` (or by structured
+ * key), and the values are fetched on first read, cached for `ttl`
+ * seconds, then refreshed. Nothing plaintext touches disk; nothing is
+ * baked into the build artifact.
+ *
+ * Designed to run in any V8 isolate — Cloudflare Workers, Vercel Edge,
+ * Deno Deploy, AWS Lambda, Bun, Node. No `fs`, no `child_process`, no
+ * dynamic require. Plugin compatibility is the only constraint:
+ * fetch-only providers (Vault, Doppler, Infisical, custom HTTP) work
+ * everywhere; SDK-backed providers (AWS, GCP, Azure, 1Password SDK)
+ * work in Node-compatible runtimes only.
+ *
+ * ```ts
+ * // src/secrets.ts — module-level singleton, one per worker
+ * import { createSecretRuntime } from "@super-repo/envx/plugins/runtime";
+ * import { hcVault } from "@super-repo/envx/plugins/vault";
+ *
+ * export const secrets = createSecretRuntime({
+ *   providers: [
+ *     hcVault({ endpoint: env.VAULT_ADDR, token: env.VAULT_TOKEN }),
+ *   ],
+ *   ttl: 300, // refresh every 5 minutes
+ * });
+ *
+ * // src/handler.ts
+ * export default async function handler(req: Request): Promise<Response> {
+ *   const dbUrl = await secrets.get("vault:prod/db");
+ *   return new Response(...);
+ * }
+ * ```
+ *
+ * Cold starts: each worker instance fetches lazily on first reference.
+ * Subsequent reads within the TTL window hit the in-memory cache.
+ */
+export interface SecretRuntimeOptions {
+    /** Providers to dispatch references to. Identified by their `name`. */
+    readonly providers: readonly SecretProvider[];
+    /**
+     * Cache TTL in seconds. After this window, the next `get()` triggers a
+     * fresh fetch. `0` = no caching (fetch every read — only sensible
+     * for very-low-traffic edges). `Infinity` = cache forever.
+     *
+     * Default: 300 (5 minutes).
+     */
+    readonly ttl?: number;
+    /**
+     * Cache mode for fetch failures.
+     *
+     * - `"throw"` (default): rethrow the error from `get()`. Caller decides.
+     * - `"cache-stale"`: when a refresh fails, return the previously cached
+     *   value (if any) and log a warning. Useful when intermittent
+     *   network blips shouldn't take the whole request down.
+     * - `"cache-error"`: cache the error for `errorTtl` seconds so we don't
+     *   hammer a failing backend. The error is rethrown until expiry.
+     */
+    readonly onFailure?: "throw" | "cache-stale" | "cache-error";
+    /** Seconds to cache a failed lookup when `onFailure: "cache-error"`. Default 30. */
+    readonly errorTtl?: number;
+    /** Optional `console`-like sink for warnings. Defaults to `console`. */
+    readonly logger?: {
+        warn(msg: string): void;
+    };
+}
+export interface SecretRuntime {
+    /**
+     * Resolve `${provider:id}` (or `provider:id` without braces) to the
+     * current value. Async — triggers a network fetch on cache miss /
+     * stale read. Throws on missing provider. Behavior on fetch failure
+     * is governed by `onFailure`.
+     */
+    get(ref: string): Promise<string>;
+    /** Same as `get`, but returns `undefined` instead of throwing on miss. */
+    tryGet(ref: string): Promise<string | undefined>;
+    /**
+     * Force-refresh a specific ref now, ignoring the TTL. Useful for
+     * post-rotation cache busts or webhook-driven invalidation.
+     */
+    invalidate(ref: string): Promise<string>;
+    /** Drop everything. Next reads will fetch fresh. */
+    clear(): void;
+    /** Shape inspection — useful in tests / dashboards. */
+    readonly stats: () => SecretRuntimeStats;
+}
+export interface SecretRuntimeStats {
+    readonly cached: number;
+    readonly inflight: number;
+    readonly errors: number;
+}
+export declare function createSecretRuntime(opts: SecretRuntimeOptions): SecretRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/plugins/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/plugins/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;IAC7D,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElC,0EAA0E;IAC1E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAEjD;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC,oDAAoD;IACpD,KAAK,IAAI,IAAI,CAAC;IAEd,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,kBAAkB,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAoBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAgI7E"}

package/dist/plugins/runtime.js

@@ -0,0 +1,2 @@
+import { t as createSecretRuntime } from "../chunks/runtime-BIEf_Dgo.js";
+export { createSecretRuntime };

package/dist/plugins/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The shape every plugin returns. envx's `resolvers:` config is sync
+ * (we don't want loadEnv to become async-everywhere), but every real
+ * secret-store SDK is async — so plugins split the concern in two:
+ *
+ *   1. `preload(ids)` — async batch fetch, populates an in-memory cache.
+ *   2. `resolve(id)`  — sync cache lookup. This is what envx wires into `resolvers`.
+ *
+ * Call `preload(...)` once during your bootstrap (top-level `await` in an
+ * async entry, or a small `await main()` wrapper), then hand `resolve` to
+ * envx. The cache is per-provider-instance — instantiate once and share.
+ */
+export interface SecretProvider {
+    /** Stable provider name. Matches the prefix in `${name:id}` env-file refs. */
+    readonly name: string;
+    /**
+     * Fetch and cache the named secrets. Safe to call multiple times — the
+     * implementation should de-duplicate and skip already-cached IDs.
+     * Errors fetching individual secrets are surfaced as exceptions so
+     * the bootstrap fails fast (rather than silently leaving secrets unset).
+     */
+    preload(ids: readonly string[]): Promise<void>;
+    /**
+     * Fetch a single secret directly from the backend, bypassing the
+     * plugin's cache. Used by the runtime/edge accessor (which owns its
+     * own TTL cache and can't accept a "stuck-forever" plugin cache).
+     */
+    fetch(id: string): Promise<string>;
+    /**
+     * Read a previously preloaded value. Returns `undefined` for unknown
+     * IDs so envx leaves the literal `${name:id}` in place — that way
+     * misconfigurations surface visibly instead of producing an empty
+     * string at runtime.
+     */
+    resolve(id: string): string | undefined;
+    /** Direct access to the cache for tooling (testing, debugging, snapshotting). */
+    readonly cache: ReadonlyMap<string, string>;
+}
+/**
+ * Internal factory used by every plugin to wire up the preload / resolve
+ * / cache trio. Plugin authors hand it a `fetchOne(id)` and we handle
+ * the cache + parallelism. Keeps the per-provider files focused on the
+ * SDK call.
+ */
+export declare function buildProvider(name: string, fetchOne: (id: string) => Promise<string>): SecretProvider;
+/**
+ * Thrown by every plugin's lazy SDK loader when the consumer hasn't
+ * installed the relevant SDK package. The message includes the
+ * `pnpm add <pkg>` line so users get the exact remediation.
+ */
+export declare class MissingSdkError extends Error {
+    constructor(plugin: string, sdk: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;;;OAIG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAExC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACxC,cAAc,CAwChB;AAMD;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAQxC"}

package/dist/plugins/vault.d.ts

@@ -0,0 +1,47 @@
+import { SecretProvider } from './types.js';
+export interface HcVaultOptions {
+    /** Vault server URL, e.g. "https://vault.example.com:8200". */
+    readonly endpoint: string;
+    /** Vault token (from `VAULT_TOKEN`, machine identity, etc.). */
+    readonly token: string;
+    /**
+     * KV v2 mount path (default: `"secret"`). KV v1 callers should set
+     * `kvVersion: 1`.
+     */
+    readonly mount?: string;
+    /** KV engine version. Default `2`. */
+    readonly kvVersion?: 1 | 2;
+    /** Override the global fetch (testing). */
+    readonly fetchImpl?: typeof fetch;
+    /** Provider name, defaults to `"vault"`. */
+    readonly name?: string;
+}
+/**
+ * HashiCorp Vault (KV v1 / v2) provider.
+ *
+ * ```ts
+ * import { hcVault } from "@super-repo/envx/plugins/vault";
+ *
+ * const vault = hcVault({
+ *   endpoint: process.env.VAULT_ADDR!,
+ *   token: process.env.VAULT_TOKEN!,
+ *   mount: "secret",
+ * });
+ * await vault.preload(["prod/db", "prod/api"]);
+ *
+ * envx({ resolvers: { [vault.name]: vault.resolve } });
+ * ```
+ *
+ * Reference shape:
+ *
+ * ```
+ * # KV v2 path: <mount>/data/<id>, returns the "value" field by default.
+ * # Or pin a specific JSON field:  ${vault:prod/db#username}
+ * DB_URL=${vault:prod/db}
+ * USER=${vault:prod/db#username}
+ * ```
+ *
+ * No SDK install required — uses native `fetch` (Node 20+).
+ */
+export declare function hcVault(opts: HcVaultOptions): SecretProvider;
+//# sourceMappingURL=vault.d.ts.map

package/dist/plugins/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/plugins/vault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIhE,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAuC5D"}

package/dist/plugins/vault.js

@@ -0,0 +1,2 @@
+import { t as hcVault } from "../chunks/vault-BWdO9DFO.js";
+export { hcVault };

package/docs/plugins/custom-providers.md

@@ -0,0 +1,26 @@
+# Custom providers
+
+The same `SecretProvider` shape works for any backend — wrap a fetcher with `buildProvider` and envx treats it like a first-party plugin.
+
+```ts
+import { buildProvider, type SecretProvider } from "@super-repo/envx/plugins";
+
+const myProvider: SecretProvider = buildProvider("my-backend", async (id) => {
+  const r = await fetch(`https://internal.example.com/secrets/${id}`, {
+    headers: { Authorization: `Bearer ${process.env.MY_TOKEN}` },
+  });
+  if (!r.ok) throw new Error(`fetch ${id}: ${r.status}`);
+  const body = await r.json() as { value: string };
+  return body.value;
+});
+
+await myProvider.preload(["a", "b"]);
+envx({ resolvers: { [myProvider.name]: myProvider.resolve } });
+```
+
+```
+SOMETHING=${my-backend:a}
+ELSE=${my-backend:b}
+```
+
+Because `buildProvider` only depends on what your `fetchOne` does, custom providers backed by `fetch` are the most portable option for edge runtimes — see the compatibility table in [runtime.md](./runtime.md#edge-runtime-compatibility-per-provider).

package/docs/plugins/library-api.md

@@ -0,0 +1,52 @@
+# Library API
+
+The shared shape every plugin returns, plus the helpers that wire them into envx.
+
+```ts
+interface SecretProvider {
+  readonly name: string;
+  preload(ids: readonly string[]): Promise<void>;        // batch fetch + cache
+  fetch(id: string): Promise<string>;                     // single fetch, bypasses cache (for runtime use)
+  resolve(id: string): string | undefined;                // sync cache read (for envx resolvers)
+  readonly cache: ReadonlyMap<string, string>;
+}
+
+function autoPreload(
+  providers: readonly SecretProvider[],
+  opts: { envFiles: string[]; cwd?: string },
+): Promise<{ preloaded: Record<string, string[]> }>;
+
+function asResolvers(
+  providers: readonly SecretProvider[],
+): Record<string, (id: string) => string | undefined>;
+
+function buildProvider(
+  name: string,
+  fetchOne: (id: string) => Promise<string>,
+): SecretProvider;
+
+class MissingSdkError extends Error { /* … */ }
+```
+
+## How it composes with envx
+
+envx's `resolvers:` config takes a **synchronous** function (`(id) => string | undefined`). All real secret-store SDKs are async, so plugins split the concern in two:
+
+1. **`preload(ids)`** — async batch fetch, populates an in-memory cache.
+2. **`resolve(id)`** — sync cache read. This is what envx calls during load.
+
+You call `preload` in your bootstrap (top-level `await` in an async entry, or inside a small `await main()` wrapper), then hand `resolve` to envx. The cache is per-provider-instance — one `awsSecrets({...})` call yields one shared cache.
+
+## Subpath imports vs. barrel
+
+Per-provider subpaths skip the other providers' dynamic-import code paths entirely, so they're preferred when bundle size matters:
+
+```ts
+// Preferred — only the AWS plugin's lazy-import lives in the bundle
+import { awsSecrets } from "@super-repo/envx/plugins/aws";
+
+// Convenience — barrel re-exports everything for one-line imports
+import { awsSecrets, gcpSecrets, asResolvers } from "@super-repo/envx/plugins";
+```
+
+The runtime entry has its own subpath: `@super-repo/envx/plugins/runtime` — see [runtime.md](./runtime.md).