@luckystack/secret-manager 0.1.9 → 0.2.0

package/CHANGELOG.md

@@ -1,14 +1,14 @@
-# Changelog
-
-All notable changes to `@luckystack/secret-manager` are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.0]
-
-### Added
-
-- Initial release. Rotation-aware secret resolver client: scans `process.env` for pointer-shaped values (`<BASE>_V<n>`), resolves them in one `POST /resolve` request against an external secret-manager server, and overwrites `process.env` with the real values. Supports `local` / `remote` / `hybrid` modes and opt-in dev hot reload (`.env` watch + interval poll). The companion append-only secret-manager server lives in its own repository (see `docs/architecture.md`).
+# Changelog
+
+All notable changes to `@luckystack/secret-manager` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial release. Rotation-aware secret resolver client: scans `process.env` for pointer-shaped values (`<BASE>_V<n>`), resolves them in one `POST /resolve` request against an external secret-manager server, and overwrites `process.env` with the real values. Supports `local` / `remote` / `hybrid` modes and opt-in dev hot reload (`.env` watch + interval poll). The companion append-only secret-manager server lives in its own repository (see `docs/architecture.md`).

package/CLAUDE.md

@@ -1,81 +1,104 @@
-# @luckystack/secret-manager
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-`@luckystack/secret-manager` is the **client** half of a rotation-aware secret system. The app commits a `.env` containing **pointers** (`OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5`), not real secrets. At boot this client scans `process.env`, collects every pointer-shaped value (`<BASE>_V<n>`), resolves them in ONE `POST /resolve` request against an external append-only secret-manager server, and overwrites each `process.env` entry with the real value — so downstream code reads `process.env.OPENAI_KEY` and gets the resolved secret. The companion server (storage, versioning, admin UI, one shared bearer token) lives in its own repository.
-
-Three modes: `'remote'` (default — missing pointer / unreachable server throws), `'local'` (no network; pointers untouched; tests + offline dev), `'hybrid'` (try server, warn + keep local env on failure). Optional opt-in dev hot reload re-resolves on `.env` change and/or on an interval (no-op in production).
-
-## When to USE this package
-
-- You want to keep `.env` committed (safe, shareable) while real secrets live on a central server.
-- You need rotation that doesn't break old branches: bump `..._V5` to `..._V6`, old branches keep resolving their pinned version.
-- You are wiring a LuckyStack app at boot and want resolved secrets in `process.env` before any framework code runs.
-
-## When to NOT suggest this (yet)
-
-- Plain local dev with real values in `.env.local`: just use `process.env.FOO` directly — non-pointer values are left untouched, so you don't even need to call this.
-- Per-request secret rotation with zero staleness: this resolves at boot (+ optional dev poll). Use a dedicated SDK at the call site for sub-second rotation guarantees.
-- Validating env-key shapes / required-key enforcement: out of scope. Validate in your config layer (e.g. `@luckystack/core` `projectConfig`) after `initSecretManager` has populated `process.env`.
-
-## Function Index
-
-| Function / Export | One-liner | Deep doc |
-| --- | --- | --- |
-| `initSecretManager(config)` | Boot-time entry. Scans `process.env` for pointer-shaped values, `POST /resolve`s them, overwrites `process.env` with real values. No-op in `'local'`. Starts dev hot reload when `config.dev` is set. | -> docs/architecture.md |
-| `refreshSecretManager()` | Re-resolve the captured pointers against the server (the dev **poll** channel). Call manually after an admin rotates a secret on a long-running process. | -> docs/architecture.md |
-| `reloadSecretManagerFromFiles()` | Re-parse the configured env files (`dev.envFiles`, default `.env` + `.env.local`) and apply them: plain values injected into `process.env` (live config reload), pointer-shaped values re-resolved. The dev **file-watch** channel; callable manually. | -> docs/architecture.md |
-| `getCachedResolution()` | Returns the last `{ fetchedAt, values }` (pointer -> value) for diagnostics, or `null`. | -> docs/architecture.md |
-| `resetSecretManagerForTests()` | Test-only — clears module state and tears down dev watchers / timers. | -> docs/architecture.md |
-| Type `SecretManagerConfig` | `{ url; token; source?; pointerPattern?; fetchImpl?; dev? }` where `dev` is `{ watch?; pollIntervalMs?; envFiles? }`. | -> docs/architecture.md |
-| Type `SecretManagerToken` | `string \| { fromFile: string }`. | -> docs/architecture.md |
-| Type `CachedResolution` | `{ fetchedAt: number; values: Record<string, string> }`. | -> docs/architecture.md |
-
-### Internal helpers (not exported, listed for AI context)
-
-| Helper | Role |
-| --- | --- |
-| `capturePointers(pattern)` | Scan `process.env` once, return `{ envName -> pointer }` for every value matching the pointer pattern. Captured once because the first resolve overwrites the value with the real secret (no longer pointer-shaped). |
-| `resolveToken(token)` | Return the literal token, or read+trim the `{ fromFile }` file (read at resolve time so file rotation is picked up). |
-| `fetchResolve(config, pointers)` | `POST ${url}/resolve` with `{ keys: pointers }` and `Authorization: Bearer <token>`. Throws on non-2xx or a missing `values` object. Honors `fetchImpl`. |
-| `applyResolved(map, values, source)` | Overwrite `process.env[envName]` with the resolved value. In `'remote'` mode, fail fast (throw) if any pointer is unresolved BEFORE mutating; in `'hybrid'` warn per missing pointer and leave it as-is. |
-| `parseEnvFile(content)` | In-package minimal `.env` parser (KEY=VALUE, full-line + inline comments, quoted values). Keeps the package dependency-free; used by the file-reload path. |
-| `startDevReload(config)` | Opt-in (`config.dev` set) + non-production. Starts a debounced `fs.watch` on `dev.envFiles` (-> `reloadSecretManagerFromFiles`) and/or an interval poll (-> `refreshSecretManager`). Both channels swallow + warn on error so a transient failure never crashes dev. |
-
-## Boot-time contract (authoritative)
-
-1. Call `initSecretManager(...)` as the very first line of `server.ts`, before any other framework code reads `process.env`.
-2. `'local'` mode short-circuits — no network, no writes, no watchers.
-3. Otherwise it captures the pointer map once, `POST /resolve`s the unique pointers, and overwrites `process.env`.
-4. `'remote'`: a missing pointer or fetch error throws (hard boot stop). `'hybrid'`: warn and leave `process.env` as-is.
-5. When `config.dev` is set and not production, dev hot reload starts: a debounced watch on `dev.envFiles` re-parses the files (plain values injected, pointers re-resolved) and an optional interval poll re-resolves the current pointers.
-6. Only after `initSecretManager` resolves should other framework code read `process.env`.
-
-## Config keys
-
-This package reads **no** env vars itself — it consumes `SecretManagerConfig` (typically built in `config.ts` and passed in `server.ts`). The values you commonly source from env / a file:
-
-| Source | Purpose |
-| --- | --- |
-| `config.url` | Base URL of the secret-manager server (trailing slash optional). |
-| `config.token` | Shared bearer token: literal string or `{ fromFile }` (gitignored single-line file). |
-| `config.source` | `'remote'` (default) / `'local'` / `'hybrid'`. |
-| `config.dev` | Opt-in dev hot reload: `{ watch?, pollIntervalMs? }`. Ignored in production. |
-
-`process.env` values matching `pointerPattern` (default `/^(.+)_V(\d+)$/`) are the pointers this client resolves and overwrites.
-
-## Peer dependencies
-
-- **None required.** Speaks plain HTTP via global `fetch`; reads the token file with Node's built-in `fs`.
-- **Optional**: any `fetch` polyfill (e.g. `undici`) for non-Node-20 hosts — pass via `SecretManagerConfig.fetchImpl`.
-
-Node `>= 20` is required because the default code path uses global `fetch`.
-
-## Related
-
-- Concept overview + external-server wire contract: `./docs/architecture.md`.
-- Consumer quickstart: `./README.md`.
-- Framework-wide packaging map: `/docs/PACKAGE_OVERVIEW.md`.
-- Architecture deep-dive: `/docs/ARCHITECTURE_SECRET_MANAGER.md`.
+# @luckystack/secret-manager
+
+> AI summary + function INDEX. For deep specs see `docs/` next to this file.
+
+## What this package does
+
+`@luckystack/secret-manager` is the **client** half of a rotation-aware secret system. The app commits a `.env` containing **pointers** (`OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5`), not real secrets. At boot this client scans `process.env`, collects every pointer-shaped value (`<BASE>_V<n>`), resolves them in ONE `POST /resolve` request against an external append-only secret-manager server, and overwrites each `process.env` entry with the real value — so downstream code reads `process.env.OPENAI_KEY` and gets the resolved secret. The companion server (storage, versioning, admin UI, one shared bearer token) lives in its own repository.
+
+Three modes: `'remote'` (default — missing pointer / unreachable server throws), `'local'` (no network; pointers untouched; tests + offline dev), `'hybrid'` (try server, warn + keep local env on failure). Optional opt-in dev hot reload re-resolves on `.env` change and/or on an interval (no-op in production).
+
+## When to USE this package
+
+- You want to keep `.env` committed (safe, shareable) while real secrets live on a central server.
+- You need rotation that doesn't break old branches: bump `..._V5` to `..._V6`, old branches keep resolving their pinned version.
+- You are wiring a LuckyStack app at boot and want resolved secrets in `process.env` before any framework code runs.
+
+## When to NOT suggest this (yet)
+
+- Plain local dev with real values in `.env.local`: just use `process.env.FOO` directly — non-pointer values are left untouched, so you don't even need to call this.
+- Per-request secret rotation with zero staleness: this resolves at boot (+ optional dev poll). Use a dedicated SDK at the call site for sub-second rotation guarantees.
+- Validating env-key shapes / required-key enforcement: out of scope. Validate in your config layer (e.g. `@luckystack/core` `projectConfig`) after `initSecretManager` has populated `process.env`.
+
+## Function Index
+
+| Function / Export | One-liner | Deep doc |
+| --- | --- | --- |
+| `initSecretManager(config)` | Boot-time entry. Scans `process.env` for pointer-shaped values, `POST /resolve`s them, overwrites `process.env` with real values. No-op in `'local'`. Starts dev hot reload when `config.dev` is set. Starts the production rotation poll when `config.pollIntervalMs` is set. | -> docs/architecture.md |
+| `refreshSecretManager()` | Re-resolve the captured pointers against the server (the production rotation poll channel). Call manually after an admin rotates a secret on a long-running process. No-op in `'local'` mode. | -> docs/architecture.md |
+| `reloadSecretManagerFromFiles()` | Re-parse the configured env files (`dev.envFiles`, default `.env` + `.env.local`) and apply them: plain values injected into `process.env` (live config reload), pointer-shaped values re-resolved. The dev **file-watch** channel; callable manually. No-op before init or in `'local'` mode. | -> docs/architecture.md |
+| `stopSecretManager()` | Tear down all dev watchers, debounce timers, and rotation-poll intervals started by `initSecretManager`. Call on process shutdown if you need deterministic cleanup; otherwise timers are `unref`'d and won't block exit. | -> docs/architecture.md |
+| `getCachedResolution()` | Returns a shallow copy of the last `{ fetchedAt, values }` (pointer -> resolved secret) for diagnostics, or `null`. **Sensitive** — never serialize into HTTP responses, health payloads, or logs. | -> docs/architecture.md |
+| `getCachedResolutionMeta()` | Values-free diagnostic view: `{ fetchedAt, pointerNames, pointerCount }` — the resolved pointer names only, never the secret values. Safe for logs and health endpoints. | -> docs/architecture.md |
+| `resetSecretManagerForTests()` | Test-only — clears all module state and tears down dev watchers / timers. | -> docs/architecture.md |
+| Type `SecretManagerConfig` | `{ url; token; source?; pointerPattern?; envNames?; allowInsecureHttp?; timeoutMs?; retries?; resolvePath?; headers?; onApplied?; onResolveError?; fetchImpl?; pollIntervalMs?; dev? }` where `dev` is `{ watch?; pollIntervalMs?; envFiles? }`. | -> docs/architecture.md |
+| Type `SecretManagerToken` | `string \| { fromFile: string }`. | -> docs/architecture.md |
+| Type `CachedResolution` | `{ fetchedAt: number; values: Record<string, string> }`. | -> docs/architecture.md |
+| Type `CachedResolutionMeta` | `{ fetchedAt: number; pointerNames: string[]; pointerCount: number }`. | -> docs/architecture.md |
+
+### Internal helpers (not exported, listed for AI context)
+
+| Helper | Role |
+| --- | --- |
+| `capturePointers(pattern)` | Scan `process.env` once, return `{ envName -> pointer }` for every value matching the pointer pattern. Captured once because the first resolve overwrites the value with the real secret (no longer pointer-shaped). |
+| `resolveToken(token)` | Return the literal token, or read+trim the `{ fromFile }` file (read at resolve time so file rotation is picked up). |
+| `fetchResolve(config, pointers)` | `POST ${url}/resolve` with `{ keys: pointers }` and `Authorization: Bearer <token>`. Throws on non-2xx or a missing `values` object. Honors `fetchImpl`. |
+| `applyResolved(map, values, source)` | Overwrite `process.env[envName]` with the resolved value. In `'remote'` mode, fail fast (throw) if any pointer is unresolved BEFORE mutating; in `'hybrid'` warn per missing pointer and leave it as-is. |
+| `parseEnvFile(content)` | In-package minimal `.env` parser (KEY=VALUE, full-line + inline comments, quoted values). Keeps the package dependency-free; used by the file-reload path. |
+| `startDevReload(config)` | Opt-in (`config.dev` set) + non-production. Starts a debounced `fs.watch` on `dev.envFiles` (-> `reloadSecretManagerFromFiles`) and/or an interval poll (-> `refreshSecretManager`). Both channels swallow + warn on error so a transient failure never crashes dev. |
+
+## Boot-time contract (authoritative)
+
+1. Call `initSecretManager(...)` as the very first line of `server.ts`, before any other framework code reads `process.env`.
+2. `'local'` mode short-circuits — no network, no writes, no watchers.
+3. Otherwise it captures the pointer map once, `POST /resolve`s the unique pointers, and overwrites `process.env`.
+4. `'remote'`: a missing pointer or fetch error throws (hard boot stop). `'hybrid'`: warn and leave `process.env` as-is.
+5. When `config.dev` is set and not production, dev hot reload starts: a debounced watch on `dev.envFiles` re-parses the files (plain values injected, pointers re-resolved) and an optional interval poll re-resolves the current pointers.
+6. Only after `initSecretManager` resolves should other framework code read `process.env`.
+
+## Config keys
+
+This package reads **no** env vars itself — it consumes `SecretManagerConfig` (typically built in `config.ts` and passed in `server.ts`). The values you commonly source from env / a file:
+
+| Key | Purpose | Notes |
+| --- | --- | --- |
+| `url` | Base URL of the secret-manager server (trailing slash optional). | Required (except `source:'local'`). |
+| `token` | Shared bearer token: literal string or `{ fromFile }` (gitignored single-line file). | Read at resolve time — file rotation picked up on next poll. A `Bearer ` prefix is stripped + warned. |
+| `source` | `'remote'` (default) / `'local'` / `'hybrid'`. | `'remote'` = hard boot stop on failure; `'hybrid'` = warn + keep local env. |
+| `envNames` | Allowlist of env-var NAMES eligible for resolution: `string[]` or `(name) => boolean`. **Secure default: unset resolves NOTHING off-host** (a boot warning is emitted so the deny-all is never silent). Pass `() => true` to scan every name deliberately. | Required to actually resolve anything. |
+| `dev` | Opt-in dev hot reload: `{ watch?, pollIntervalMs?, envFiles? }`. Ignored in production (`NODE_ENV !== 'development'|'test'`). | — |
+
+### Advanced keys (direct-call-only — not needed for typical boot wiring)
+
+| Key | Purpose |
+| --- | --- |
+| `pointerPattern` | Override the pointer-shape detector (default `/^(.+)_V(\d+)$/`). Stateful `g`/`y` flags are stripped automatically. |
+| `allowInsecureHttp` | Permit `http:` to a non-loopback host. A loud warning is still emitted. Loopback is always permitted. |
+| `timeoutMs` | Abort a black-hole server after N ms (default `10_000`). Set `0` to disable. |
+| `retries` | `{ count, delayMs? }` — retry on transport error / non-2xx before giving up. Default `{ count: 0 }`. |
+| `resolvePath` | Override the resolve endpoint path (default `'/resolve'`). |
+| `headers` | Extra request headers merged onto every resolve request (cannot override `Authorization`). |
+| `onApplied` | Called after secrets are written to `process.env` — receives changed env NAMES only (never the values). Use to re-create pools/SDK clients on rotation. |
+| `onResolveError` | Called on resolve failure (alongside the existing `console.warn`). Route to Sentry/metrics; useful for `'hybrid'` where a silent warn is the default. |
+| `fetchImpl` | Override the global `fetch`. For non-Node-20 hosts or test injection. |
+| `pollIntervalMs` | Production rotation poll interval in ms (re-resolves in ALL environments). Default `0` (disabled). Timers are `unref`'d. |
+
+`process.env` values matching `pointerPattern` (default `/^(.+)_V(\d+)$/`) are the pointers this client resolves and overwrites.
+
+## Design note — single resolver per process
+
+`@luckystack/secret-manager` uses module-level state (`activeConfig`, `pointerMap`, `cachedResolution`, `resolveChain`). This is intentional: there is one canonical view of `process.env`, so a second parallel resolver would race against the first. If you need to resolve different configs separately (e.g. a multi-stage bootstrap), call `stopSecretManager()` + `resetSecretManagerForTests()` between them (the latter is exported but named for test clarity — it is safe to call in non-test bootstrap code too). Running two resolvers concurrently against the same `process.env` is unsupported.
+
+## Peer dependencies
+
+- **None required.** Speaks plain HTTP via global `fetch`; reads the token file with Node's built-in `fs`.
+- **Optional**: any `fetch` polyfill (e.g. `undici`) for non-Node-20 hosts — pass via `SecretManagerConfig.fetchImpl`.
+
+Node `>= 20` is required because the default code path uses global `fetch`.
+
+## Related
+
+- Concept overview + external-server wire contract: `./docs/architecture.md`.
+- Consumer quickstart: `./README.md`.
+- Framework-wide packaging map: `/docs/PACKAGE_OVERVIEW.md`.
+- Architecture deep-dive: `/docs/ARCHITECTURE_SECRET_MANAGER.md`.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Mathijs van Melick
-
-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.
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+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

@@ -1,100 +1,100 @@
-# @luckystack/secret-manager
-
-> Rotation-aware secret resolver client. Commit `.env` **pointers** instead of real secrets; resolve them against an external secret-manager server at boot. Part of [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2).
-
-`@luckystack/secret-manager` is the thin client that lives inside a LuckyStack app. Your committed `.env` holds pointers like `OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5` — never the real secret. At boot the client collects every pointer-shaped value, asks the server to resolve them in one request, and overwrites `process.env` with the real values. Rotating a secret means publishing a new version (`..._V6`) on the server; old git branches that still point at `..._V5` keep booting.
-
-For the full design (pointer model, append-only versioning, the external server's wire contract), read [`docs/architecture.md`](./docs/architecture.md).
-
-## Install
-
-```bash
-npm install @luckystack/secret-manager
-```
-
-Requires Node `>= 20` (uses global `fetch`). For older Node, inject a polyfill via `fetchImpl`.
-
-## Quickstart
-
-Call `initSecretManager` as the very first line of your `server.ts`, before any other framework code reads `process.env`.
-
-```ts
-import { initSecretManager } from '@luckystack/secret-manager';
-import { bootstrapLuckyStack } from '@luckystack/server';
-
-await initSecretManager({
-  url: process.env.LUCKYSTACK_SECRET_MANAGER_URL!,
-  token: { fromFile: '.secret-manager-token' }, // gitignored file, one line = the token
-  source: 'hybrid', // try the server, keep local env on failure
-});
-
-const server = await bootstrapLuckyStack({ /* ... */ });
-await server.listen();
-```
-
-In your committed `.env`:
-
-```
-OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5
-STRIPE_KEY=STRIPE_SECRET_KEY_V2
-```
-
-After `initSecretManager` resolves, `process.env.OPENAI_KEY` holds the real `sk-...` value.
-
-## Modes
-
-| `source` | Behavior |
-| --- | --- |
-| `'remote'` (default) | Resolve from the server. A missing pointer or an unreachable server **throws** — production hard-stop. |
-| `'local'` | No network. Pointers are left untouched. Use in tests + offline dev. |
-| `'hybrid'` | Try the server; on failure warn and leave whatever `process.env` already holds. |
-
-A value that is **not** pointer-shaped (e.g. `NODE_ENV=production`, or a real secret you pasted locally) is treated as a literal and never sent to the server — so local overrides win automatically.
-
-## Dev hot reload (opt-in)
-
-Pass a `dev` object to live-reload while a long-running dev process is up. Ignored when `NODE_ENV === 'production'`.
-
-```ts
-await initSecretManager({
-  url: process.env.LUCKYSTACK_SECRET_MANAGER_URL!,
-  token: { fromFile: '.secret-manager-token' },
-  dev: {
-    watch: true,          // re-read .env / .env.local on change (default true)
-    pollIntervalMs: 5000, // also re-resolve every 5s (default off)
-    // envFiles: ['.env', '.env.local'], // override which files are watched
-  },
-});
-```
-
-- **On file change** (`watch`): the env files are re-parsed and applied — plain values (e.g. `ENVIRONMENT=production`, `PORT=123`) are injected straight into `process.env` (live config reload), and pointer-shaped values are re-resolved against the server. A pointer added or bumped after boot is picked up here — no restart.
-- **On the poll interval** (`pollIntervalMs`): the current pointers are re-resolved, catching server-side rotations. The interval lives in your `config.ts`, so it's changeable in one place.
-
-So `.env` (plain config) and `.env.local` (pointers/secrets) both live-reload — `.env` values are injected as-is, `.env.local` pointers are resolved from the server.
-
-## Public API
-
-| Export | Purpose |
-| --- | --- |
-| `initSecretManager(config)` | Boot-time entry point. Resolves pointer-shaped env values and writes the real values into `process.env`. |
-| `refreshSecretManager()` | Re-resolve the captured pointers against the server (the poll channel; call manually after an admin rotates a secret). |
-| `reloadSecretManagerFromFiles()` | Re-parse the configured env files and apply them — plain values injected, pointers resolved. The file-watch channel; callable manually. |
-| `getCachedResolution()` | Returns the last `{ fetchedAt, values }` resolution (pointer -> value) for diagnostics, or `null`. |
-| `resetSecretManagerForTests()` | Test-only — clears module state and tears down dev watchers / timers. |
-
-## The token file
-
-The shared bearer token is the only real secret on the developer machine. Keep it in a single-line file (e.g. `.secret-manager-token`) that is **gitignored**, and reference it with `token: { fromFile: '.secret-manager-token' }`. CI runners can inject the file from their secret store. You may also pass the token as a literal string if you read it from your own secret source.
-
-## Peer dependencies
-
-- **None.** This package speaks plain HTTP via global `fetch` and reads the token file with Node's built-in `fs`.
-- **Optional**: any `fetch` polyfill (e.g. `undici`) for non-Node-20 hosts — pass via `SecretManagerConfig.fetchImpl`.
-
-## Documentation
-
-- [`docs/architecture.md`](./docs/architecture.md) — pointer model, append-only versioning, the external server's `POST /resolve` wire contract, and what this package does NOT do.
-
-## License
-
-MIT — see [LICENSE](./LICENSE).
+# @luckystack/secret-manager
+
+> Rotation-aware secret resolver client. Commit `.env` **pointers** instead of real secrets; resolve them against an external secret-manager server at boot. Part of [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2).
+
+`@luckystack/secret-manager` is the thin client that lives inside a LuckyStack app. Your committed `.env` holds pointers like `OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5` — never the real secret. At boot the client collects every pointer-shaped value, asks the server to resolve them in one request, and overwrites `process.env` with the real values. Rotating a secret means publishing a new version (`..._V6`) on the server; old git branches that still point at `..._V5` keep booting.
+
+For the full design (pointer model, append-only versioning, the external server's wire contract), read [`docs/architecture.md`](./docs/architecture.md).
+
+## Install
+
+```bash
+npm install @luckystack/secret-manager
+```
+
+Requires Node `>= 20` (uses global `fetch`). For older Node, inject a polyfill via `fetchImpl`.
+
+## Quickstart
+
+Call `initSecretManager` as the very first line of your `server.ts`, before any other framework code reads `process.env`.
+
+```ts
+import { initSecretManager } from '@luckystack/secret-manager';
+import { bootstrapLuckyStack } from '@luckystack/server';
+
+await initSecretManager({
+  url: process.env.LUCKYSTACK_SECRET_MANAGER_URL!,
+  token: { fromFile: '.secret-manager-token' }, // gitignored file, one line = the token
+  source: 'hybrid', // try the server, keep local env on failure
+});
+
+const server = await bootstrapLuckyStack({ /* ... */ });
+await server.listen();
+```
+
+In your committed `.env`:
+
+```
+OPENAI_KEY=OPENAI_AUTHORIZATION_KEY_V5
+STRIPE_KEY=STRIPE_SECRET_KEY_V2
+```
+
+After `initSecretManager` resolves, `process.env.OPENAI_KEY` holds the real `sk-...` value.
+
+## Modes
+
+| `source` | Behavior |
+| --- | --- |
+| `'remote'` (default) | Resolve from the server. A missing pointer or an unreachable server **throws** — production hard-stop. |
+| `'local'` | No network. Pointers are left untouched. Use in tests + offline dev. |
+| `'hybrid'` | Try the server; on failure warn and leave whatever `process.env` already holds. |
+
+A value that is **not** pointer-shaped (e.g. `NODE_ENV=production`, or a real secret you pasted locally) is treated as a literal and never sent to the server — so local overrides win automatically.
+
+## Dev hot reload (opt-in)
+
+Pass a `dev` object to live-reload while a long-running dev process is up. Ignored when `NODE_ENV === 'production'`.
+
+```ts
+await initSecretManager({
+  url: process.env.LUCKYSTACK_SECRET_MANAGER_URL!,
+  token: { fromFile: '.secret-manager-token' },
+  dev: {
+    watch: true,          // re-read .env / .env.local on change (default true)
+    pollIntervalMs: 5000, // also re-resolve every 5s (default off)
+    // envFiles: ['.env', '.env.local'], // override which files are watched
+  },
+});
+```
+
+- **On file change** (`watch`): the env files are re-parsed and applied — plain values (e.g. `ENVIRONMENT=production`, `PORT=123`) are injected straight into `process.env` (live config reload), and pointer-shaped values are re-resolved against the server. A pointer added or bumped after boot is picked up here — no restart.
+- **On the poll interval** (`pollIntervalMs`): the current pointers are re-resolved, catching server-side rotations. The interval lives in your `config.ts`, so it's changeable in one place.
+
+So `.env` (plain config) and `.env.local` (pointers/secrets) both live-reload — `.env` values are injected as-is, `.env.local` pointers are resolved from the server.
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `initSecretManager(config)` | Boot-time entry point. Resolves pointer-shaped env values and writes the real values into `process.env`. |
+| `refreshSecretManager()` | Re-resolve the captured pointers against the server (the poll channel; call manually after an admin rotates a secret). |
+| `reloadSecretManagerFromFiles()` | Re-parse the configured env files and apply them — plain values injected, pointers resolved. The file-watch channel; callable manually. |
+| `getCachedResolution()` | Returns the last `{ fetchedAt, values }` resolution (pointer -> value) for diagnostics, or `null`. |
+| `resetSecretManagerForTests()` | Test-only — clears module state and tears down dev watchers / timers. |
+
+## The token file
+
+The shared bearer token is the only real secret on the developer machine. Keep it in a single-line file (e.g. `.secret-manager-token`) that is **gitignored**, and reference it with `token: { fromFile: '.secret-manager-token' }`. CI runners can inject the file from their secret store. You may also pass the token as a literal string if you read it from your own secret source.
+
+## Peer dependencies
+
+- **None.** This package speaks plain HTTP via global `fetch` and reads the token file with Node's built-in `fs`.
+- **Optional**: any `fetch` polyfill (e.g. `undici`) for non-Node-20 hosts — pass via `SecretManagerConfig.fetchImpl`.
+
+## Documentation
+
+- [`docs/architecture.md`](./docs/architecture.md) — pointer model, append-only versioning, the external server's `POST /resolve` wire contract, and what this package does NOT do.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -16,11 +16,75 @@ interface SecretManagerConfig {
     /**
      * Override the pointer-shape detector. Any `process.env` value matching this
      * is treated as a pointer; anything else is a literal and left untouched.
-     * Default `/^(.+)_V(\d+)$/`.
+     * Default `/^(.+)_V(\d+)$/`. A `g`/`y` flag is stripped (a stateful regex would
+     * misclassify alternating entries).
      */
     pointerPattern?: RegExp;
+    /**
+     * Scope which `process.env` entries are pointer-eligible by NAME. This allowlist
+     * is REQUIRED to resolve anything off-host: an array of names or a predicate.
+     *
+     * SECURE DEFAULT: when unset, NOTHING is resolved off-host (a clear boot warning
+     * is emitted instead). Scanning the entire inherited environment would POST any
+     * unrelated, pointer-shaped inherited value (`RELEASE_TAG=build_2024_V2`) to the
+     * secret-manager server — so an explicit allowlist is mandatory. To opt back into
+     * scanning every name, pass `() => true` as a deliberate, auditable choice.
+     */
+    envNames?: string[] | ((name: string) => boolean);
+    /**
+     * Allow a plain-`http:` server `url`. By default only `https:` is accepted for
+     * non-loopback hosts (the channel carries the bearer token + plaintext secrets);
+     * loopback (`localhost`/`127.0.0.1`/`[::1]`) is always permitted. Set `true` to
+     * permit `http:` to any host — a loud warning is still emitted.
+     */
+    allowInsecureHttp?: boolean;
+    /**
+     * Abort a resolve request that has not responded within this many ms. Prevents a
+     * black-hole server (accepts the TCP connection, never responds) from hanging boot
+     * until undici's ~300s default — and, in `'hybrid'`, from never reaching the
+     * warn-and-keep-local fallback (a hang never rejects). Default `10_000`. Set `0`
+     * to disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry a failed resolve before giving up (transport error or non-2xx). Default
+     * `{ count: 0 }` (no retry). After exhaustion `'remote'` still throws and
+     * `'hybrid'` still warns-and-keeps-local.
+     */
+    retries?: {
+        count: number;
+        delayMs?: number;
+    };
+    /** Override the resolve path appended to `url`. Default `'/resolve'`. */
+    resolvePath?: string;
+    /** Extra request headers merged onto every resolve request (cannot override `Authorization`). */
+    headers?: Record<string, string>;
+    /**
+     * Called after a resolve writes new values into `process.env`, with ONLY the env
+     * NAMES whose value actually changed (never the secret values). A client that
+     * captured a secret at construction time (Prisma from `DATABASE_URL`, a Redis /
+     * Stripe / OpenAI SDK) can re-create its pool/client here so a rotation lands.
+     */
+    onApplied?: (changes: {
+        name: string;
+        pointer: string;
+    }[]) => void | Promise<void>;
+    /**
+     * Called when a resolve fails, alongside the existing `console.warn` (current
+     * behavior is unchanged when unset). Route the failure to Sentry/metrics —
+     * useful for `'hybrid'`/dev where a failure otherwise silently keeps stale env.
+     */
+    onResolveError?: (error: unknown, context: {
+        phase: 'boot' | 'refresh' | 'file-reload';
+    }) => void;
     /** Override the global `fetch` (tests / non-Node-20 hosts). */
     fetchImpl?: typeof fetch;
+    /**
+     * Re-resolve the current pointers every N ms in ALL environments (the production
+     * rotation poll), distinct from the dev-only `dev.pollIntervalMs` file-watch
+     * channel. Default `0` (disabled). Unref'd, so it never blocks process exit.
+     */
+    pollIntervalMs?: number;
     /**
      * Opt-in dev-only hot reload. Ignored when `NODE_ENV === 'production'`.
      * Provide an (even empty) object to enable it.
@@ -30,8 +94,7 @@ interface SecretManagerConfig {
          * Watch the env files and hot-reload on change. Default `true`. On change
          * the files are re-parsed and applied: plain (non-pointer) values are
          * injected straight into `process.env` (live config reload), and
-         * pointer-shaped values are re-resolved against the server. Requires the
-         * optional `dotenv` peer to parse the files.
+         * pointer-shaped values are re-resolved against the server.
          */
         watch?: boolean;
         /** Re-resolve the current pointers every N ms (server-rotation poll). Default `0` (disabled). */
@@ -67,9 +130,41 @@ declare const refreshSecretManager: () => Promise<void>;
  * `.env` / `.env.local` file watch; also callable manually.
  */
 declare const reloadSecretManagerFromFiles: () => Promise<void>;
-/** Read the last `{ fetchedAt, values }` resolution (pointer -> value), or `null`. */
+/**
+ * Read the last `{ fetchedAt, values }` resolution (pointer -> value), or `null`.
+ *
+ * ⚠️ SENSITIVE: `values` maps each pointer to its RAW resolved secret. The result
+ * is a shallow copy (values are flat strings, so mutating the returned object does
+ * not corrupt the cache), but the values are still the real secrets — NEVER
+ * serialize the result into an HTTP response, a `/health` payload, or a log line.
+ * For a safe diagnostic use {@link getCachedResolutionMeta}, which never exposes
+ * the values.
+ */
 declare const getCachedResolution: () => CachedResolution | null;
+/** Values-free view of {@link getCachedResolution}: the timestamp + resolved pointer NAMES only. */
+interface CachedResolutionMeta {
+    /** `Date.now()` of the last successful resolve. */
+    fetchedAt: number;
+    /** The resolved pointer strings (never the secret values). */
+    pointerNames: string[];
+    /** How many pointers were resolved. */
+    pointerCount: number;
+}
+/**
+ * Safe diagnostic accessor: the last resolution's timestamp + resolved pointer
+ * NAMES, with the secret values stripped. Use this on any surface that might be
+ * logged or served (`/health`, metrics) so the convenient path is also the safe
+ * one — {@link getCachedResolution} is the values-carrying escape hatch.
+ */
+declare const getCachedResolutionMeta: () => CachedResolutionMeta | null;
+/**
+ * Tear down the dev file watchers, the dev poll, the rotation poll, and the
+ * debounce timer WITHOUT wiping the resolved cache / active config. Use for a
+ * graceful shutdown of an embedded resolver (worker / CLI) so no timers keep
+ * firing; the last resolved `process.env` values stay in place.
+ */
+declare const stopSecretManager: () => void;
 /** Test-only — clear module state and tear down any dev watchers / timers. */
 declare const resetSecretManagerForTests: () => void;
 
-export { type CachedResolution, type SecretManagerConfig, type SecretManagerToken, getCachedResolution, initSecretManager, refreshSecretManager, reloadSecretManagerFromFiles, resetSecretManagerForTests };
+export { type CachedResolution, type CachedResolutionMeta, type SecretManagerConfig, type SecretManagerToken, getCachedResolution, getCachedResolutionMeta, initSecretManager, refreshSecretManager, reloadSecretManagerFromFiles, resetSecretManagerForTests, stopSecretManager };