@super-repo/envx-plugins 0.2.3-b.5 → 0.2.3-b.6

package/README.md

@@ -1,380 +1,96 @@
 # @super-repo/envx-plugins
 
-Secret-provider plugins for [envx](https://www.npmjs.com/package/@super-repo/envx). Each plugin returns a `SecretProvider` you wire into envx's `resolvers:` config so values like `${aws-secrets:my-db}` and `${vault:prod/api}` resolve at load time from the matching backend.
+> Secret-provider plugins for envx — `${aws-secrets:my-db}` and `${vault:prod/api}` style refs that resolve at load time from real backends.
 
-```sh
-pnpm add @super-repo/envx-plugins
-```
-
-The plugins package itself has zero runtime SDK dependencies. Each plugin lazy-loads its provider's SDK on first use; install only the SDKs you actually need:
+[![NPM](https://nodei.co/npm/@super-repo/envx-plugins.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/@super-repo/envx-plugins)
 
-| provider           | install                                                                     |
-| ------------------ | --------------------------------------------------------------------------- |
-| AWS Secrets Manager | `pnpm add @aws-sdk/client-secrets-manager`                                  |
-| GCP Secret Manager  | `pnpm add @google-cloud/secret-manager`                                     |
-| Azure Key Vault     | `pnpm add @azure/keyvault-secrets @azure/identity`                          |
-| HashiCorp Vault     | _(no SDK — uses native `fetch`)_                                            |
-| 1Password (SDK)     | `pnpm add @1password/sdk`                                                   |
-| 1Password (CLI)     | install `op` via [1Password's docs](https://developer.1password.com/docs/cli) |
-| Doppler             | _(no SDK — uses native `fetch`)_                                            |
-| Infisical           | _(no SDK — uses native `fetch`)_                                            |
+[![npm version](https://img.shields.io/npm/v/@super-repo/envx-plugins.svg)](https://www.npmjs.com/package/@super-repo/envx-plugins)
+[![npm downloads](https://img.shields.io/npm/dm/@super-repo/envx-plugins.svg)](https://www.npmjs.com/package/@super-repo/envx-plugins)
+[![license](https://img.shields.io/npm/l/@super-repo/envx-plugins.svg)](./LICENSE)
 
-## How it composes with envx
+`.env*` files are great until the secrets in them shouldn't sit on disk. envx-plugins lets you write `${aws-secrets:prod/db}` (or vault, 1Password, Doppler, …) directly in `.env*` and have envx resolve those refs against the real backend at load time. Each plugin returns a `SecretProvider` you wire into [envx's](https://www.npmjs.com/package/@super-repo/envx) `resolvers:` config.
 
-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:
+The package itself has zero runtime SDK dependencies. Each plugin lazy-loads its provider's SDK on first use, so you only install the SDKs you actually reference.
 
-1. **`preload(ids)`** — async batch fetch, populates an in-memory cache.
-2. **`resolve(id)`** — sync cache read. This is what envx calls during load.
+## Getting started
 
-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.
-
-## One-shot example — all 7 providers
+```sh
+pnpm add @super-repo/envx-plugins
+```
 
 ```ts
 // bootstrap.ts
 import envx from "@super-repo/envx";
-import {
-  awsSecrets,
-  gcpSecrets,
-  azureKeyVault,
-  hcVault,
-  onePassword,
-  doppler,
-  infisical,
-  autoPreload,
-  asResolvers,
-} from "@super-repo/envx-plugins";
+import { awsSecrets, autoPreload, asResolvers } from "@super-repo/envx-plugins";
 
 const aws = awsSecrets({ region: "us-east-1" });
-const gcp = gcpSecrets({ projectId: "acme-prod" });
-const azure = azureKeyVault({ vaultUrl: "https://acme.vault.azure.net" });
-const vault = hcVault({
-  endpoint: process.env.VAULT_ADDR!,
-  token: process.env.VAULT_TOKEN!,
-});
-const op = onePassword({ token: process.env.OP_SERVICE_ACCOUNT_TOKEN });
-const dop = doppler({ token: process.env.DOPPLER_TOKEN! });
-const inf = infisical({
-  token: process.env.INFISICAL_TOKEN!,
-  projectId: "proj-1",
-  environment: "prod",
-});
 
-// One call, per-file scan, parallel resolution.
-await autoPreload([aws, gcp, azure, vault, op, dop, inf], {
-  envFiles: [".env", "vault/.env.prod"],
-});
+await autoPreload([aws], { envFiles: [".env"] });
 
 envx({
-  // `asResolvers([...])` builds the { name → resolve } map for you.
-  resolvers: asResolvers([aws, gcp, azure, vault, op, dop, inf]),
+  resolvers: asResolvers([aws]),
 });
 ```
 
-In your `.env*` files:
-
-```
-DATABASE_URL=${aws-secrets:prod/db}
-CACHE_URL=${gcp-secrets:cache-host}
-JWT_SECRET=${azure-keyvault:prod-jwt-signing@v3}
-ROOT_TOKEN=${vault:prod/admin#token}
-GITHUB_PAT=${op:op://prod/GitHub/personal-access-token}
-SENDGRID_KEY=${doppler:SENDGRID_KEY}
-STRIPE_KEY=${infisical:STRIPE_LIVE_KEY}
-```
-
-Only the providers actually referenced in those files get pre-loaded — `autoPreload` scans the files first and skips providers with zero hits.
-
-## Per-provider usage
-
-### AWS Secrets Manager
-
-```ts
-import { awsSecrets } from "@super-repo/envx-plugins/aws";
-
-const aws = awsSecrets({ region: "us-east-1" });
-await aws.preload(["prod/db", "prod/api-key"]);
-```
-
 ```
+# .env
 DATABASE_URL=${aws-secrets:prod/db}
 API_KEY=${aws-secrets:prod/api-key}
 ```
 
-Multiple regions? Give each its own provider name and reference accordingly:
-
-```ts
-const awsUs = awsSecrets({ region: "us-east-1", name: "aws-us" });
-const awsEu = awsSecrets({ region: "eu-west-1", name: "aws-eu" });
-```
-
-```
-DB_US=${aws-us:prod/db}
-DB_EU=${aws-eu:prod/db}
-```
-
-### GCP Secret Manager
-
-```ts
-import { gcpSecrets } from "@super-repo/envx-plugins/gcp";
-
-const gcp = gcpSecrets({ projectId: "acme-prod" });
-await gcp.preload(["prod-db", "prod-api"]);
-```
-
-```
-DB_URL=${gcp-secrets:prod-db}
-API_KEY=${gcp-secrets:prod-api@3}    # pin to version 3
-```
-
-### Azure Key Vault
-
-```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-jwt-signing"]);
-```
-
-```
-DB_URL=${azure-keyvault:prod-db}
-JWT_SECRET=${azure-keyvault:prod-jwt-signing@<version>}
-```
-
-Credentials come from `DefaultAzureCredential` by default (env vars → managed identity → Azure CLI → VS Code, in that order). Pass `credential:` to override.
-
-### HashiCorp Vault (KV v1 / v2)
-
-```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"]);
-```
-
-```
-DB_URL=${vault:prod/db}             # reads `data.value` field by default
-USERNAME=${vault:prod/db#username}  # specific JSON field
-```
-
-KV v1? Pass `kvVersion: 1`.
-
-### 1Password — CLI mode (developer machines)
-
-If `op` is signed in on your machine, no token / SDK is required:
-
-```ts
-import { onePassword } from "@super-repo/envx-plugins/op";
-
-const op = onePassword();
-await op.preload([
-  "op://prod/Database/url",
-  "op://prod/API/key",
-]);
-```
-
-```
-DB_URL=${op:op://prod/Database/url}
-API_KEY=${op:op://prod/API/key}
-```
-
-### 1Password — SDK mode (CI / containers)
-
-Use a service-account token in environments without an interactive `op signin`:
-
-```ts
-const op = onePassword({
-  token: process.env.OP_SERVICE_ACCOUNT_TOKEN!,
-});
-```
-
-The plugin lazy-loads `@1password/sdk` only in this mode.
-
-### Doppler
-
-```ts
-import { doppler } from "@super-repo/envx-plugins/doppler";
-
-const dop = doppler({ token: process.env.DOPPLER_TOKEN! });
-await dop.preload(["DATABASE_URL", "API_KEY"]);
-```
-
-```
-DATABASE_URL=${doppler:DATABASE_URL}
-API_KEY=${doppler:API_KEY}
-```
-
-Service tokens scope to one project + config, so you typically don't pass project/config explicitly.
+For the all-seven-providers wiring, per-provider auth, edge-runtime usage, and custom backends, see [Docs](#docs).
 
-### Infisical
-
-```ts
-import { infisical } from "@super-repo/envx-plugins/infisical";
-
-const inf = infisical({
-  token: process.env.INFISICAL_TOKEN!,
-  projectId: "proj-1",
-  environment: "prod",
-  secretPath: "/services/api",   // optional
-});
-await inf.preload(["DATABASE_URL", "API_KEY"]);
-```
+## Features
 
-```
-DATABASE_URL=${infisical:DATABASE_URL}
-API_KEY=${infisical:API_KEY}
-```
+| provider               | edge-runtime | reference syntax                                  |
+| ---------------------- | :----------: | ------------------------------------------------- |
+| **AWS Secrets Manager** | ⚠            | `${aws-secrets:<name>}` (`@v3` for version pin)   |
+| **GCP Secret Manager**  | ⚠            | `${gcp-secrets:<name>}` (`@3` for version pin)    |
+| **Azure Key Vault**     | ⚠            | `${azure-keyvault:<name>}` (`@<version>` for pin) |
+| **HashiCorp Vault**     | ✓            | `${vault:<path>}` (`#<field>` for JSON field)     |
+| **1Password (CLI)**     | ✗            | `${op:op://vault/item/field}`                     |
+| **1Password (SDK)**     | depends      | `${op:op://vault/item/field}`                     |
+| **Doppler**             | ✓            | `${doppler:<NAME>}`                               |
+| **Infisical**           | ✓            | `${infisical:<NAME>}`                             |
 
-Self-hosted? Pass `endpoint: "https://infisical.example.com"`.
+✓ = native `fetch`, runs in Workers / Edge / Deno. ⚠ = needs Node-compatible runtime (Lambda, Cloud Run, Node). ✗ = spawns a child process. Full table with caveats: [docs/runtime.md](./docs/runtime.md#edge-runtime-compatibility-per-provider).
 
-## Runtime / edge — secrets that never leave the source
+Beyond the per-provider plugins:
 
-For the "secrets never touch disk, fetched on demand" model, use `createSecretRuntime` from the `/runtime` subpath. Async-first, TTL-cached, V8-isolate-safe — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
+- **`autoPreload`** — scans your `envFiles` first, only invokes providers that actually appear, and runs them in parallel.
+- **`asResolvers`** — turns a provider list into the `{ name → resolve }` map envx expects.
+- **`buildProvider`** — wrap any async `(id) => Promise<string>` fetcher into a first-class `SecretProvider` for in-house backends.
+- **`createSecretRuntime`** (`/runtime` subpath) — V8-isolate-safe, TTL-cached, single-flight async fetch for edge / serverless.
 
-```ts
-// src/secrets.ts — module-level singleton, one instance per worker / process
-import { createSecretRuntime } from "@super-repo/envx-plugins/runtime";
-import { hcVault } from "@super-repo/envx-plugins/vault";
+## Comparison
 
-export const secrets = createSecretRuntime({
-  providers: [
-    hcVault({
-      endpoint: env.VAULT_ADDR,
-      token: env.VAULT_TOKEN,
-    }),
-  ],
-  ttl: 300,                 // refresh after 5 min
-  onFailure: "cache-stale", // serve stale on transient backend failures
-});
-```
+| feature                                | `@super-repo/envx-plugins` | `dotenv-vault`     | direct vendor SDKs |
+| -------------------------------------- | :------------------------: | :----------------: | :----------------: |
+| `${ref}` interpolation in `.env*`      | ✓                          | ✗                  | ✗                  |
+| Pluggable, multi-vendor in one config  | ✓                          | ✗ (one backend)    | n/a                |
+| Lazy SDK install per provider          | ✓                          | n/a                | ✗                  |
+| Edge-runtime entry (V8-isolate-safe)   | ✓                          | ✗                  | varies             |
+| Works without leaving envx's pipeline  | ✓                          | replaces dotenv    | replaces dotenv    |
 
-```ts
-// Cloudflare Worker, Vercel Edge, Lambda, Deno Deploy — same handler shape
-import { secrets } from "./secrets";
+`dotenv-vault` and the official Doppler / Infisical CLIs each take over the entire env story. envx-plugins keeps envx as the loader and adds vendor-backed `${ref}` resolution as a layer on top — so one repo can mix AWS for DB credentials, Vault for service tokens, and 1Password for developer secrets without three different bootstrap shapes.
 
-export default async function handler(req: Request): Promise<Response> {
-  const dbUrl = await secrets.get("vault:prod/db");
-  const apiKey = await secrets.get("vault:prod/api");
-  return new Response(JSON.stringify({ dbUrl, apiKey }));
-}
-```
+## Docs
 
-### Behavior
+Deep references and worked examples live alongside this package in [./docs/](./docs/):
 
-- **Lazy fetch** — first read triggers the network call. Subsequent reads inside the TTL window hit the in-memory cache.
-- **Single-flight** — N concurrent reads of the same ref coalesce to one fetch. Edge functions handling a request burst don't fan out N parallel calls to your secret store.
-- **TTL refresh** — values older than `ttl` seconds are refetched on next read.
-- **Failure modes** — `"throw"` (default), `"cache-stale"` (serve previous value, log warn), `"cache-error"` (cache the failure for `errorTtl` seconds so a flaky backend doesn't get hammered).
-- **No fs / child_process imports** — the runtime entry is V8-isolate-safe.
+- **[providers.md](./docs/providers.md)** — per-provider auth, options, and `${ref}` syntax for AWS, GCP, Azure, Vault, 1Password (CLI + SDK), Doppler, Infisical.
+- **[recipes.md](./docs/recipes.md)** — the all-seven-providers bootstrap, plus the SDK install matrix.
+- **[runtime.md](./docs/runtime.md)** — `createSecretRuntime` for edge / serverless: TTL caching, single-flight, failure modes, edge-compat table.
+- **[custom-providers.md](./docs/custom-providers.md)** — wrap any backend with `buildProvider`.
+- **[library-api.md](./docs/library-api.md)** — `SecretProvider` shape, `autoPreload`, `asResolvers`, `buildProvider`, `MissingSdkError`, subpath imports.
 
-### API
+## References
 
-```ts
-interface SecretRuntime {
-  get(ref: string): Promise<string>;             // throws on miss / unknown provider / failed fetch
-  tryGet(ref: string): Promise<string | undefined>; // never throws
-  invalidate(ref: string): Promise<string>;      // force-refresh a specific ref
-  clear(): void;                                  // drop all cached entries
-  readonly stats: () => { cached: number; inflight: number; errors: number };
-}
-
-interface SecretRuntimeOptions {
-  readonly providers: readonly SecretProvider[];
-  readonly ttl?: number;                          // default 300 (5min). 0 = no cache. Infinity = forever.
-  readonly onFailure?: "throw" | "cache-stale" | "cache-error";
-  readonly errorTtl?: number;                     // for "cache-error" mode. default 30
-  readonly logger?: { warn(msg: string): void };
-}
-```
-
-### Edge-runtime compatibility per provider
-
-| provider              | Cloudflare Workers / Vercel Edge / Deno | Lambda / Cloud Run / Node | reason                       |
-| --------------------- | --------------------------------------- | ------------------------- | ---------------------------- |
-| `hcVault`             | ✓                                       | ✓                         | native `fetch`                |
-| `doppler`             | ✓                                       | ✓                         | native `fetch`                |
-| `infisical`           | ✓                                       | ✓                         | native `fetch`                |
-| `awsSecrets`          | ⚠                                       | ✓                         | Node streams in the SDK       |
-| `gcpSecrets`          | ⚠                                       | ✓                         | gRPC in the SDK               |
-| `azureKeyVault`       | ⚠                                       | ✓                         | `@azure/identity` token chain |
-| `onePassword` (CLI)   | ✗                                       | ✓ (with `op` on PATH)      | spawns a child process        |
-| `onePassword` (SDK)   | depends on `@1password/sdk`              | ✓                         | SDK's own constraints         |
-| custom `buildProvider`| depends on what your fetcher does        | ✓                         | usually fine if you use `fetch` |
-
-For maximum portability across edges, prefer Vault / Doppler / Infisical, or write your own provider with `buildProvider`:
-
-```ts
-import { buildProvider } from "@super-repo/envx-plugins";
-
-const myProvider = buildProvider("internal", async (id) => {
-  const r = await fetch(`https://internal.example.com/secrets/${id}`, {
-    headers: { Authorization: `Bearer ${env.MY_TOKEN}` },
-  });
-  return (await r.json()).value;
-});
-```
-
-That single-file plugin works in every JS runtime that has `fetch`.
-
-## Custom providers
-
-The same `SecretProvider` shape works for any backend — wrap it with `buildProvider`:
-
-```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}
-```
-
-## API
-
-```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 { /* … */ }
-```
+- [`@super-repo/envx`](../core) — the loader these plugins plug into. envx-plugins has no purpose without it; the two are designed to be used together.
+- [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/) · [GCP Secret Manager](https://cloud.google.com/secret-manager/docs) · [Azure Key Vault](https://learn.microsoft.com/azure/key-vault/) · [HashiCorp Vault KV](https://developer.hashicorp.com/vault/docs/secrets/kv)
+- [1Password Service Accounts](https://developer.1password.com/docs/service-accounts) · [Doppler API](https://docs.doppler.com/reference) · [Infisical API](https://infisical.com/docs/api-reference/overview/introduction)
+- [Project README](../../../README.md)
 
 ## License
 
-MIT
+MIT © Super-Repo contributors. See [LICENSE](./LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-repo/envx-plugins",
   "description": "Collections of plugins for envx — AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, 1Password, Doppler, Infisical. Each plugin returns a SecretProvider compatible with envx's `resolvers:` config.",
-  "version": "0.2.3-b.5",
+  "version": "0.2.3-b.6",
   "type": "module",
   "exports": {
     ".": {
@@ -65,15 +65,15 @@
     "config": "../../../config/rune-envx.config.ts"
   },
   "peerDependencies": {
-    "@super-repo/envx": "0.2.3-b.5"
+    "@super-repo/envx": "0.2.3-b.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsc-alias": "^1.8.16",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@super-repo/envx": "0.2.3-b.5",
-    "@super-repo/cli": "0.2.3-b.5",
+    "@super-repo/cli": "0.2.3-b.6",
+    "@super-repo/envx": "0.2.3-b.6",
     "@super-repo/envx-libs": "0.0.1"
   }
 }