@crewhaus/secrets-manager 0.1.4 → 0.1.5

package/dist/backends/env-var.d.ts

@@ -0,0 +1,13 @@
+/**
+ * env-var backend — the default. `rotate()` is a no-op (the OS owns the
+ * env, not us); a logger warning is emitted when one is supplied so the
+ * caller knows the rotation didn't really happen.
+ */
+import type { Logger } from "@crewhaus/logging";
+import { type SecretsBackend } from "../index";
+export type EnvVarBackendOptions = {
+    /** Default: `process.env`. Override for tests. */
+    readonly env?: NodeJS.ProcessEnv;
+    readonly logger?: Logger;
+};
+export declare function createEnvVarBackend(opts?: EnvVarBackendOptions): SecretsBackend;

package/dist/backends/env-var.js

@@ -0,0 +1,37 @@
+import { SecretsError } from "../index";
+export function createEnvVarBackend(opts = {}) {
+    const env = opts.env ?? process.env;
+    return {
+        id: "env-var",
+        async get(name) {
+            const value = env[name];
+            if (value === undefined || value === "") {
+                throw new SecretsError(`secret "${name}" not found in env (env-var backend)`);
+            }
+            return value;
+        },
+        async rotate(name, rotateOpts) {
+            // env-var is read-only at the secrets layer; rotation requires
+            // restarting the process with new env. We accept an explicit
+            // newValue so callers can model "I just exported $NAME" — but we
+            // can't actually mutate the parent process's env.
+            if (rotateOpts?.newValue !== undefined) {
+                env[name] = rotateOpts.newValue;
+            }
+            if (opts.logger) {
+                opts.logger.warn("secrets.rotate.env-var.no-op", {
+                    name,
+                    msg: "env-var backend does not own rotation; rotate at the orchestrator instead",
+                });
+            }
+            const v = env[name];
+            if (v === undefined) {
+                throw new SecretsError(`secret "${name}" cannot be rotated via env-var backend without a newValue`);
+            }
+            return v;
+        },
+        async list() {
+            return Object.keys(env).filter((k) => env[k] !== undefined && env[k] !== "");
+        },
+    };
+}

package/dist/backends/file.d.ts

@@ -0,0 +1,6 @@
+import { type SecretsBackend } from "../index";
+export type FileBackendOptions = {
+    /** Default: `.crewhaus/secrets`. */
+    readonly rootDir: string;
+};
+export declare function createFileBackend(opts: FileBackendOptions): SecretsBackend;

package/dist/backends/file.js

@@ -0,0 +1,54 @@
+/**
+ * file backend — reads `<rootDir>/<name>` (mode 0o600 enforced on write).
+ * Rotation is an atomic rewrite: write to `.<name>.tmp`, then rename.
+ *
+ * The file content is the raw secret value (no JSON wrapper, no
+ * trailing newline-stripping ambiguity). Whitespace is preserved as-is
+ * for tokens that may legitimately contain it.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { SecretsError } from "../index";
+export function createFileBackend(opts) {
+    const rootDir = opts.rootDir;
+    function pathFor(name) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name)) {
+            throw new SecretsError("invalid secret name (must match [A-Za-z0-9_.-]+)");
+        }
+        return join(rootDir, name);
+    }
+    return {
+        id: "file",
+        async get(name) {
+            const p = pathFor(name);
+            if (!existsSync(p)) {
+                throw new SecretsError("secret file read failed (not found)");
+            }
+            return readFileSync(p, "utf8");
+        },
+        async rotate(name, rotateOpts) {
+            const p = pathFor(name);
+            const newValue = rotateOpts?.newValue ?? generateRandomSecret();
+            // Create the secrets root on first use so a fresh checkout can rotate a
+            // secret without a raw ENOENT — recursive mkdir is a no-op when it
+            // already exists. 0o700 keeps the directory owner-only, consistent with
+            // the 0o600 secret files written into it.
+            mkdirSync(rootDir, { recursive: true, mode: 0o700 });
+            const tmp = `${p}.tmp`;
+            writeFileSync(tmp, newValue, { encoding: "utf8", mode: 0o600 });
+            renameSync(tmp, p);
+            return newValue;
+        },
+        async list() {
+            if (!existsSync(rootDir))
+                return [];
+            return readdirSync(rootDir).filter((f) => !f.endsWith(".tmp") && !f.startsWith("."));
+        },
+    };
+}
+function generateRandomSecret() {
+    // 32 bytes hex → 64 chars; sufficient for tokens.
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/backends/vault.d.ts

@@ -0,0 +1,19 @@
+/**
+ * vault backend — HashiCorp Vault KV v2 over HTTP. Reads
+ * `<addr>/v1/<mount>/data/<name>` and writes via PUT to the same path.
+ *
+ * Auth: token via `VAULT_TOKEN` (or constructor option). The simplest
+ * path that doesn't need approles or k8s service accounts.
+ */
+import { type SecretsBackend } from "../index";
+export type VaultBackendOptions = {
+    /** Vault address (e.g. `http://127.0.0.1:8200`). */
+    readonly addr: string;
+    /** KV v2 mount point (default: `secret`). */
+    readonly mount?: string;
+    /** Vault token. Falls back to `VAULT_TOKEN` env. */
+    readonly token?: string;
+    /** Optional fetch override for tests. */
+    readonly fetchImpl?: typeof fetch;
+};
+export declare function createVaultBackend(opts: VaultBackendOptions): SecretsBackend;

package/dist/backends/vault.js

@@ -0,0 +1,67 @@
+/**
+ * vault backend — HashiCorp Vault KV v2 over HTTP. Reads
+ * `<addr>/v1/<mount>/data/<name>` and writes via PUT to the same path.
+ *
+ * Auth: token via `VAULT_TOKEN` (or constructor option). The simplest
+ * path that doesn't need approles or k8s service accounts.
+ */
+import { SecretsError } from "../index";
+export function createVaultBackend(opts) {
+    const mount = opts.mount ?? "secret";
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    function getToken() {
+        const t = opts.token ?? process.env["VAULT_TOKEN"];
+        if (!t) {
+            throw new SecretsError("vault backend requires a token (constructor opts.token or VAULT_TOKEN env)");
+        }
+        return t;
+    }
+    function dataUrl(name) {
+        if (!/^[A-Za-z0-9_/.-]+$/.test(name)) {
+            throw new SecretsError("invalid secret name for vault backend");
+        }
+        return `${opts.addr}/v1/${encodeURIComponent(mount)}/data/${name}`;
+    }
+    return {
+        id: "vault",
+        async get(name) {
+            const url = dataUrl(name);
+            const res = await fetchImpl(url, {
+                headers: { "X-Vault-Token": getToken() },
+            });
+            if (res.status === 404) {
+                throw new SecretsError("secret not found in vault (status 404)");
+            }
+            if (!res.ok) {
+                throw new SecretsError(`vault request failed (status ${res.status})`);
+            }
+            const body = (await res.json());
+            const v = body?.data?.data?.value;
+            if (typeof v !== "string") {
+                throw new SecretsError("vault response missing data.data.value (KV v2 expected)");
+            }
+            return v;
+        },
+        async rotate(name, rotateOpts) {
+            const url = dataUrl(name);
+            const newValue = rotateOpts?.newValue ?? generateRandomSecret();
+            const res = await fetchImpl(url, {
+                method: "PUT",
+                headers: {
+                    "X-Vault-Token": getToken(),
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ data: { value: newValue } }),
+            });
+            if (!res.ok) {
+                throw new SecretsError(`vault request failed (status ${res.status})`);
+            }
+            return newValue;
+        },
+    };
+}
+function generateRandomSecret() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import type { AuditLog } from "@crewhaus/audit-log";
+/**
+ * Section 27 — `secrets-manager`. Pluggable secret storage with rotation
+ * callbacks and audit-log integration. Three backends:
+ *  - **env-var** (default; rotation is a no-op + warning)
+ *  - **file** (reads from `.crewhaus/secrets/<name>`; rotation = atomic rewrite)
+ *  - **vault** (HashiCorp Vault HTTP API, KV v2 backend)
+ *
+ * Long-running daemons (CHN gateway, MGD gateway, RES daemon) subscribe to
+ * `onRotation(handler)` so they refresh in-flight credentials without
+ * restart. Every `get` and `rotate` is audit-logged when a tenant id is
+ * configured.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { createEnvVarBackend } from "./backends/env-var";
+import { createFileBackend } from "./backends/file";
+import { createVaultBackend } from "./backends/vault";
+export declare class SecretsError extends CrewhausError {
+    readonly name = "SecretsError";
+    constructor(message: string, cause?: unknown);
+}
+export type SecretValue = string;
+export type RotationHandler = (event: {
+    readonly name: string;
+    readonly newValue: SecretValue;
+    readonly rotatedAt: number;
+}) => void | Promise<void>;
+export interface SecretsBackend {
+    readonly id: "env-var" | "file" | "vault";
+    /** Returns the current value, or throws SecretsError if missing. */
+    get(name: string): Promise<SecretValue>;
+    /**
+     * Rotate the named secret. Implementations may generate a new value or
+     * accept an externally-supplied one via `opts.newValue`. Returns the
+     * new value so callers can verify the rotation took.
+     */
+    rotate(name: string, opts?: {
+        readonly newValue?: SecretValue;
+    }): Promise<SecretValue>;
+    /** Optional health check. Returns the names this backend can resolve. */
+    list?(): Promise<ReadonlyArray<string>>;
+}
+export interface Secrets {
+    /** Resolve the named secret. Audit-logs the access when tenantId is set. */
+    get(name: string): Promise<SecretValue>;
+    /**
+     * Rotate the named secret, fire all `onRotation` handlers, and audit-log
+     * the rotation when tenantId is set. Returns the new value.
+     */
+    rotate(name: string, opts?: {
+        readonly newValue?: SecretValue;
+    }): Promise<SecretValue>;
+    /** Subscribe to rotation events. Returns an unsubscribe function. */
+    onRotation(handler: RotationHandler): () => void;
+    /** Switch to a fresh backend. Used by tests + the doctor command. */
+    doctor(): Promise<DoctorReport>;
+    /** Backend identifier for diagnostics. */
+    readonly backendId: SecretsBackend["id"];
+}
+export type DoctorReport = {
+    readonly backend: SecretsBackend["id"];
+    readonly available: ReadonlyArray<string>;
+    readonly missing: ReadonlyArray<string>;
+    /** Rotation TTLs known to be due (file/vault track this; env-var returns []). */
+    readonly rotationDue: ReadonlyArray<string>;
+};
+export type CreateSecretsOptions = {
+    readonly backend: SecretsBackend;
+    readonly auditLog?: AuditLog;
+    readonly tenantId?: string;
+    /** Names to validate in `doctor()`. */
+    readonly knownSecrets?: ReadonlyArray<string>;
+};
+export declare function createSecrets(opts: CreateSecretsOptions): Secrets;
+export { createEnvVarBackend, createFileBackend, createVaultBackend };

package/dist/index.js

@@ -0,0 +1,99 @@
+/**
+ * Section 27 — `secrets-manager`. Pluggable secret storage with rotation
+ * callbacks and audit-log integration. Three backends:
+ *  - **env-var** (default; rotation is a no-op + warning)
+ *  - **file** (reads from `.crewhaus/secrets/<name>`; rotation = atomic rewrite)
+ *  - **vault** (HashiCorp Vault HTTP API, KV v2 backend)
+ *
+ * Long-running daemons (CHN gateway, MGD gateway, RES daemon) subscribe to
+ * `onRotation(handler)` so they refresh in-flight credentials without
+ * restart. Every `get` and `rotate` is audit-logged when a tenant id is
+ * configured.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { createEnvVarBackend } from "./backends/env-var";
+import { createFileBackend } from "./backends/file";
+import { createVaultBackend } from "./backends/vault";
+export class SecretsError extends CrewhausError {
+    name = "SecretsError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+export function createSecrets(opts) {
+    const handlers = new Set();
+    return {
+        backendId: opts.backend.id,
+        async get(name) {
+            const value = await opts.backend.get(name);
+            if (opts.auditLog && opts.tenantId !== undefined) {
+                await opts.auditLog.append({
+                    kind: "secrets_access",
+                    payload: { tenantId: opts.tenantId, name, backend: opts.backend.id },
+                });
+            }
+            return value;
+        },
+        async rotate(name, rotateOpts) {
+            const newValue = await opts.backend.rotate(name, rotateOpts);
+            const rotatedAt = Date.now();
+            if (opts.auditLog && opts.tenantId !== undefined) {
+                await opts.auditLog.append({
+                    kind: "secrets_rotation",
+                    payload: {
+                        tenantId: opts.tenantId,
+                        name,
+                        backend: opts.backend.id,
+                        rotatedAt,
+                    },
+                });
+            }
+            // Fire handlers in order. A handler that throws does not block siblings.
+            const event = { name, newValue, rotatedAt };
+            const promises = [];
+            for (const h of handlers) {
+                try {
+                    const result = h(event);
+                    if (result && typeof result.then === "function") {
+                        promises.push(result.catch(() => {
+                            /* swallow per-handler errors */
+                        }));
+                    }
+                }
+                catch {
+                    /* swallow per-handler errors */
+                }
+            }
+            await Promise.all(promises);
+            return newValue;
+        },
+        onRotation(h) {
+            handlers.add(h);
+            return () => {
+                handlers.delete(h);
+            };
+        },
+        async doctor() {
+            const known = opts.knownSecrets ?? [];
+            const available = [];
+            const missing = [];
+            for (const name of known) {
+                try {
+                    await opts.backend.get(name);
+                    available.push(name);
+                }
+                catch {
+                    missing.push(name);
+                }
+            }
+            return {
+                backend: opts.backend.id,
+                available,
+                missing,
+                rotationDue: [],
+            };
+        },
+    };
+}
+// Re-export backends so callers can construct directly.
+export { createEnvVarBackend, createFileBackend, createVaultBackend };

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@crewhaus/secrets-manager",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Pluggable secrets backend with rotation + audit-log integration: env-var, file, vault",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.4",
-    "@crewhaus/errors": "0.1.4",
-    "@crewhaus/logging": "0.1.4"
+    "@crewhaus/audit-log": "0.1.5",
+    "@crewhaus/errors": "0.1.5",
+    "@crewhaus/logging": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -34,5 +37,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/backends/env-var.test.ts

@@ -1,125 +0,0 @@
-/**
- * Section 27 — `env-var` backend coverage.
- *
- * Targets the rotate() warning + missing-value paths and list().
- * No real `process.env` is touched: every test passes an explicit `env`
- * object, and the logger is a plain in-memory spy (no real clock, no
- * stderr writes, no leaked handles).
- */
-import { describe, expect, test } from "bun:test";
-import type { LogFields } from "@crewhaus/logging";
-import { createEnvVarBackend } from "../backends/env-var";
-import { SecretsError } from "../index";
-
-type WarnCall = { msg: string; fields?: LogFields };
-
-/** Minimal Logger spy — records warn() calls, ignores the rest. */
-function makeLogger() {
-  const warns: WarnCall[] = [];
-  const logger = {
-    debug() {},
-    info() {},
-    warn(msg: string, fields?: LogFields) {
-      warns.push({ msg, fields });
-    },
-    error() {},
-    child() {
-      return logger;
-    },
-  };
-  return { logger, warns };
-}
-
-describe("env-var backend — id", () => {
-  test("exposes the env-var id", () => {
-    const backend = createEnvVarBackend({ env: {} as NodeJS.ProcessEnv });
-    expect(backend.id).toBe("env-var");
-  });
-
-  test("defaults env to process.env when not supplied", () => {
-    // Construct without an `env` option to exercise the `?? process.env`
-    // fallback branch. We never read or mutate a real secret here — just
-    // assert the backend is constructed against the default env.
-    const backend = createEnvVarBackend();
-    expect(backend.id).toBe("env-var");
-  });
-});
-
-describe("env-var backend — rotate() warning + return paths", () => {
-  test("rotate(newValue) logs the no-op warning and returns the new value", async () => {
-    const { logger, warns } = makeLogger();
-    const env: NodeJS.ProcessEnv = { TOKEN: "old" };
-    const backend = createEnvVarBackend({ env, logger });
-
-    const v = await backend.rotate("TOKEN", { newValue: "new" });
-
-    expect(v).toBe("new");
-    expect(env["TOKEN"]).toBe("new");
-    expect(warns.length).toBe(1);
-    expect(warns[0]?.msg).toBe("secrets.rotate.env-var.no-op");
-    expect((warns[0]?.fields as { name: string }).name).toBe("TOKEN");
-  });
-
-  test("rotate without newValue returns the pre-existing env value (logs warning)", async () => {
-    const { logger, warns } = makeLogger();
-    const env: NodeJS.ProcessEnv = { TOKEN: "already-set" };
-    const backend = createEnvVarBackend({ env, logger });
-
-    const v = await backend.rotate("TOKEN");
-
-    expect(v).toBe("already-set");
-    // value must be untouched when no newValue is provided
-    expect(env["TOKEN"]).toBe("already-set");
-    expect(warns.length).toBe(1);
-  });
-
-  test("rotate without newValue on an unset name throws SecretsError", async () => {
-    const { logger, warns } = makeLogger();
-    const env: NodeJS.ProcessEnv = {};
-    const backend = createEnvVarBackend({ env, logger });
-
-    expect(backend.rotate("NOPE")).rejects.toBeInstanceOf(SecretsError);
-    // the warning still fires before the missing-value throw
-    await backend.rotate("NOPE").catch(() => {});
-    expect(warns.length).toBeGreaterThanOrEqual(1);
-  });
-
-  test("rotate without a logger still returns the new value (no-warn branch)", async () => {
-    const env: NodeJS.ProcessEnv = { TOKEN: "old" };
-    const backend = createEnvVarBackend({ env });
-
-    const v = await backend.rotate("TOKEN", { newValue: "fresh" });
-
-    expect(v).toBe("fresh");
-    expect(env["TOKEN"]).toBe("fresh");
-  });
-
-  test("rotate without a logger and without newValue throws when unset", async () => {
-    const env: NodeJS.ProcessEnv = {};
-    const backend = createEnvVarBackend({ env });
-    expect(backend.rotate("MISSING")).rejects.toBeInstanceOf(SecretsError);
-  });
-});
-
-describe("env-var backend — list()", () => {
-  test("returns only names with non-empty values", async () => {
-    const env: NodeJS.ProcessEnv = {
-      A: "1",
-      B: "2",
-      EMPTY: "",
-      UNDEF: undefined,
-    };
-    const backend = createEnvVarBackend({ env });
-
-    const names = await backend.list?.();
-
-    expect(names).toBeDefined();
-    expect([...(names ?? [])].sort()).toEqual(["A", "B"]);
-  });
-
-  test("returns an empty array when env has no usable entries", async () => {
-    const env: NodeJS.ProcessEnv = { EMPTY: "", UNDEF: undefined };
-    const backend = createEnvVarBackend({ env });
-    expect(await backend.list?.()).toEqual([]);
-  });
-});

package/src/backends/env-var.ts

@@ -1,52 +0,0 @@
-/**
- * env-var backend — the default. `rotate()` is a no-op (the OS owns the
- * env, not us); a logger warning is emitted when one is supplied so the
- * caller knows the rotation didn't really happen.
- */
-import type { Logger } from "@crewhaus/logging";
-import { type SecretValue, type SecretsBackend, SecretsError } from "../index";
-
-export type EnvVarBackendOptions = {
-  /** Default: `process.env`. Override for tests. */
-  readonly env?: NodeJS.ProcessEnv;
-  readonly logger?: Logger;
-};
-
-export function createEnvVarBackend(opts: EnvVarBackendOptions = {}): SecretsBackend {
-  const env = opts.env ?? process.env;
-  return {
-    id: "env-var",
-    async get(name: string): Promise<SecretValue> {
-      const value = env[name];
-      if (value === undefined || value === "") {
-        throw new SecretsError(`secret "${name}" not found in env (env-var backend)`);
-      }
-      return value;
-    },
-    async rotate(name: string, rotateOpts): Promise<SecretValue> {
-      // env-var is read-only at the secrets layer; rotation requires
-      // restarting the process with new env. We accept an explicit
-      // newValue so callers can model "I just exported $NAME" — but we
-      // can't actually mutate the parent process's env.
-      if (rotateOpts?.newValue !== undefined) {
-        env[name] = rotateOpts.newValue;
-      }
-      if (opts.logger) {
-        opts.logger.warn("secrets.rotate.env-var.no-op", {
-          name,
-          msg: "env-var backend does not own rotation; rotate at the orchestrator instead",
-        });
-      }
-      const v = env[name];
-      if (v === undefined) {
-        throw new SecretsError(
-          `secret "${name}" cannot be rotated via env-var backend without a newValue`,
-        );
-      }
-      return v;
-    },
-    async list(): Promise<ReadonlyArray<string>> {
-      return Object.keys(env).filter((k) => env[k] !== undefined && env[k] !== "");
-    },
-  };
-}