@crewhaus/secrets-manager 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/secrets-manager",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pluggable secrets backend with rotation + audit-log integration: env-var, file, vault",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/audit-log": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/logging": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/secrets-manager"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/secrets-manager#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/backends/env-var.ts

@@ -0,0 +1,52 @@
+/**
+ * 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] !== "");
+    },
+  };
+}

package/src/backends/file.ts

@@ -0,0 +1,57 @@
+/**
+ * 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, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type SecretValue, type SecretsBackend, SecretsError } from "../index";
+
+export type FileBackendOptions = {
+  /** Default: `.crewhaus/secrets`. */
+  readonly rootDir: string;
+};
+
+export function createFileBackend(opts: FileBackendOptions): SecretsBackend {
+  const rootDir = opts.rootDir;
+
+  function pathFor(name: string): string {
+    if (!/^[A-Za-z0-9_.-]+$/.test(name)) {
+      throw new SecretsError(`invalid secret name "${name}" (must match [A-Za-z0-9_.-]+)`);
+    }
+    return join(rootDir, name);
+  }
+
+  return {
+    id: "file",
+    async get(name: string): Promise<SecretValue> {
+      const p = pathFor(name);
+      if (!existsSync(p)) {
+        throw new SecretsError(`secret "${name}" not found at ${p}`);
+      }
+      return readFileSync(p, "utf8");
+    },
+    async rotate(name: string, rotateOpts): Promise<SecretValue> {
+      const p = pathFor(name);
+      const newValue = rotateOpts?.newValue ?? generateRandomSecret();
+      const tmp = `${p}.tmp`;
+      writeFileSync(tmp, newValue, { encoding: "utf8", mode: 0o600 });
+      renameSync(tmp, p);
+      return newValue;
+    },
+    async list(): Promise<ReadonlyArray<string>> {
+      if (!existsSync(rootDir)) return [];
+      return readdirSync(rootDir).filter((f) => !f.endsWith(".tmp") && !f.startsWith("."));
+    },
+  };
+}
+
+function generateRandomSecret(): string {
+  // 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/src/backends/vault.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 SecretValue, type SecretsBackend, SecretsError } 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 function createVaultBackend(opts: VaultBackendOptions): SecretsBackend {
+  const mount = opts.mount ?? "secret";
+  const fetchImpl = opts.fetchImpl ?? fetch;
+
+  function getToken(): string {
+    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: string): string {
+    if (!/^[A-Za-z0-9_/.-]+$/.test(name)) {
+      throw new SecretsError(`invalid secret name "${name}" for vault backend`);
+    }
+    return `${opts.addr}/v1/${encodeURIComponent(mount)}/data/${name}`;
+  }
+
+  return {
+    id: "vault",
+    async get(name: string): Promise<SecretValue> {
+      const url = dataUrl(name);
+      const res = await fetchImpl(url, {
+        headers: { "X-Vault-Token": getToken() },
+      });
+      if (res.status === 404) {
+        throw new SecretsError(`secret "${name}" not found in vault at ${url}`);
+      }
+      if (!res.ok) {
+        throw new SecretsError(`vault GET ${name} returned ${res.status}: ${await res.text()}`);
+      }
+      const body = (await res.json()) as { data?: { data?: { value?: string } } };
+      const v = body?.data?.data?.value;
+      if (typeof v !== "string") {
+        throw new SecretsError(
+          `vault response for "${name}" missing data.data.value (KV v2 expected)`,
+        );
+      }
+      return v;
+    },
+    async rotate(name: string, rotateOpts): Promise<SecretValue> {
+      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 PUT ${name} returned ${res.status}: ${await res.text()}`);
+      }
+      return newValue;
+    },
+  };
+}
+
+function generateRandomSecret(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/index.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Section 27 — `secrets-manager` tests:
+ *  - T1 per backend (env-var, file, vault)
+ *  - T8 cross-tenant secret isolation
+ *  - T3 rotation callback within 5s of rotate()
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type AuditRecord, openAuditLog } from "@crewhaus/audit-log";
+import {
+  SecretsError,
+  createEnvVarBackend,
+  createFileBackend,
+  createSecrets,
+  createVaultBackend,
+} from "./index";
+
+let tmpRoot = "";
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), "secrets-test-"));
+});
+
+afterEach(() => {
+  rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("env-var backend (T1)", () => {
+  test("get returns the env value", async () => {
+    const backend = createEnvVarBackend({
+      env: { MY_SECRET: "abc123" } as NodeJS.ProcessEnv,
+    });
+    expect(await backend.get("MY_SECRET")).toBe("abc123");
+  });
+
+  test("get throws when missing", async () => {
+    const backend = createEnvVarBackend({ env: {} as NodeJS.ProcessEnv });
+    expect(backend.get("MISSING")).rejects.toBeInstanceOf(SecretsError);
+  });
+
+  test("get throws on empty-string value", async () => {
+    const backend = createEnvVarBackend({
+      env: { EMPTY: "" } as NodeJS.ProcessEnv,
+    });
+    expect(backend.get("EMPTY")).rejects.toBeInstanceOf(SecretsError);
+  });
+
+  test("rotate(newValue) overwrites the env entry and returns it", async () => {
+    const env: NodeJS.ProcessEnv = { TOKEN: "old" };
+    const backend = createEnvVarBackend({ env });
+    const v = await backend.rotate("TOKEN", { newValue: "new" });
+    expect(v).toBe("new");
+    expect(env["TOKEN"]).toBe("new");
+  });
+});
+
+describe("file backend (T1)", () => {
+  test("get returns the file contents", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "API_KEY"), "secret-value");
+    const backend = createFileBackend({ rootDir: root });
+    expect(await backend.get("API_KEY")).toBe("secret-value");
+  });
+
+  test("get throws when file missing", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    const backend = createFileBackend({ rootDir: root });
+    expect(backend.get("MISSING")).rejects.toBeInstanceOf(SecretsError);
+  });
+
+  test("rotate writes atomically (mode 0o600) and returns the new value", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old", { mode: 0o600 });
+    const backend = createFileBackend({ rootDir: root });
+    const v = await backend.rotate("TOKEN", { newValue: "fresh-token-xyz" });
+    expect(v).toBe("fresh-token-xyz");
+    expect(readFileSync(join(root, "TOKEN"), "utf8")).toBe("fresh-token-xyz");
+  });
+
+  test("rotate generates a hex token when newValue is omitted", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    const backend = createFileBackend({ rootDir: root });
+    const v = await backend.rotate("AUTO");
+    expect(v).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  test("rejects malformed names (T8 path-traversal defense)", async () => {
+    const backend = createFileBackend({ rootDir: tmpRoot });
+    expect(backend.get("../../../etc/passwd")).rejects.toBeInstanceOf(SecretsError);
+    expect(backend.rotate("path/with/slash")).rejects.toBeInstanceOf(SecretsError);
+  });
+});
+
+describe("vault backend (T1)", () => {
+  test("get reads via KV v2 endpoint", async () => {
+    let observedUrl = "";
+    let observedToken = "";
+    const fetchImpl = (async (url: string, init?: RequestInit) => {
+      observedUrl = url;
+      observedToken = (init?.headers as Record<string, string>)?.["X-Vault-Token"] ?? "";
+      return new Response(JSON.stringify({ data: { data: { value: "vault-secret" } } }), {
+        status: 200,
+      });
+    }) as unknown as typeof fetch;
+    const backend = createVaultBackend({
+      addr: "http://127.0.0.1:8200",
+      token: "test-token",
+      fetchImpl,
+    });
+    const v = await backend.get("MY_KEY");
+    expect(v).toBe("vault-secret");
+    expect(observedUrl).toBe("http://127.0.0.1:8200/v1/secret/data/MY_KEY");
+    expect(observedToken).toBe("test-token");
+  });
+
+  test("get throws on 404", async () => {
+    const fetchImpl = (async () =>
+      new Response("not found", { status: 404 })) as unknown as typeof fetch;
+    const backend = createVaultBackend({
+      addr: "http://127.0.0.1:8200",
+      token: "t",
+      fetchImpl,
+    });
+    expect(backend.get("MISSING")).rejects.toBeInstanceOf(SecretsError);
+  });
+
+  test("rotate PUTs the new value", async () => {
+    let observedBody = "";
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      if (init?.method === "PUT") {
+        observedBody = init.body as string;
+        return new Response("{}", { status: 204 });
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+    const backend = createVaultBackend({
+      addr: "http://127.0.0.1:8200",
+      token: "t",
+      fetchImpl,
+    });
+    const v = await backend.rotate("KEY", { newValue: "fresh" });
+    expect(v).toBe("fresh");
+    expect(JSON.parse(observedBody)).toEqual({ data: { value: "fresh" } });
+  });
+
+  test("missing token throws", async () => {
+    const oldToken = process.env["VAULT_TOKEN"];
+    process.env["VAULT_TOKEN"] = undefined;
+    const backend = createVaultBackend({ addr: "http://127.0.0.1:8200" });
+    expect(backend.get("X")).rejects.toBeInstanceOf(SecretsError);
+    if (oldToken !== undefined) process.env["VAULT_TOKEN"] = oldToken;
+  });
+});
+
+describe("createSecrets — rotation handlers (T3)", () => {
+  test("onRotation handlers fire within 5s of rotate()", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old");
+    const secrets = createSecrets({
+      backend: createFileBackend({ rootDir: root }),
+    });
+
+    const events: Array<{ name: string; newValue: string; rotatedAt: number }> = [];
+    secrets.onRotation((e) => {
+      events.push({ name: e.name, newValue: e.newValue, rotatedAt: e.rotatedAt });
+    });
+
+    const t0 = Date.now();
+    await secrets.rotate("TOKEN", { newValue: "new-value" });
+    const elapsed = Date.now() - t0;
+
+    expect(elapsed).toBeLessThan(5_000);
+    expect(events.length).toBe(1);
+    expect(events[0]?.name).toBe("TOKEN");
+    expect(events[0]?.newValue).toBe("new-value");
+  });
+
+  test("multiple handlers fire in order; one throwing does not block others", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old");
+    const secrets = createSecrets({ backend: createFileBackend({ rootDir: root }) });
+
+    const calls: string[] = [];
+    secrets.onRotation(() => {
+      calls.push("first");
+      throw new Error("first handler boom");
+    });
+    secrets.onRotation(() => {
+      calls.push("second");
+    });
+
+    await secrets.rotate("TOKEN", { newValue: "new" });
+    expect(calls).toEqual(["first", "second"]);
+  });
+
+  test("unsubscribe stops further notifications", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old");
+    const secrets = createSecrets({ backend: createFileBackend({ rootDir: root }) });
+    let calls = 0;
+    const off = secrets.onRotation(() => {
+      calls++;
+    });
+    await secrets.rotate("TOKEN", { newValue: "v1" });
+    off();
+    await secrets.rotate("TOKEN", { newValue: "v2" });
+    expect(calls).toBe(1);
+  });
+});
+
+describe("createSecrets — audit-log integration (T8 tenant isolation)", () => {
+  async function readAuditRecords(rootDir: string): Promise<AuditRecord[]> {
+    const audit = await openAuditLog({ rootDir });
+    const out: AuditRecord[] = [];
+    for await (const rec of audit.read()) out.push(rec);
+    return out;
+  }
+
+  test("audit-log records secrets_access only when tenant scoped", async () => {
+    const root = join(tmpRoot, "secrets");
+    const auditRoot = join(tmpRoot, "audit");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "K"), "v");
+
+    const audit = await openAuditLog({ rootDir: auditRoot });
+    const secretsTenantA = createSecrets({
+      backend: createFileBackend({ rootDir: root }),
+      auditLog: audit,
+      tenantId: "tenant-a",
+    });
+    const secretsNoTenant = createSecrets({
+      backend: createFileBackend({ rootDir: root }),
+      auditLog: audit,
+    });
+
+    await secretsTenantA.get("K");
+    await secretsNoTenant.get("K");
+
+    const records = await readAuditRecords(auditRoot);
+    expect(records.length).toBe(1);
+    expect(records[0]?.kind).toBe("secrets_access");
+    expect((records[0]?.payload as { tenantId: string }).tenantId).toBe("tenant-a");
+  });
+
+  test("rotate also audit-logs and includes timestamp", async () => {
+    const root = join(tmpRoot, "secrets");
+    const auditRoot = join(tmpRoot, "audit");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "K"), "v");
+
+    const audit = await openAuditLog({ rootDir: auditRoot });
+    const secrets = createSecrets({
+      backend: createFileBackend({ rootDir: root }),
+      auditLog: audit,
+      tenantId: "tenant-a",
+    });
+
+    await secrets.rotate("K", { newValue: "v2" });
+    const records = await readAuditRecords(auditRoot);
+    expect(records.length).toBe(1);
+    expect(records[0]?.kind).toBe("secrets_rotation");
+    const payload = records[0]?.payload as {
+      tenantId: string;
+      name: string;
+      backend: string;
+      rotatedAt: number;
+    };
+    expect(payload.tenantId).toBe("tenant-a");
+    expect(payload.name).toBe("K");
+    expect(payload.backend).toBe("file");
+    expect(typeof payload.rotatedAt).toBe("number");
+  });
+});
+
+describe("createSecrets — doctor()", () => {
+  test("reports available + missing for known names", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "EXISTS"), "v");
+    const secrets = createSecrets({
+      backend: createFileBackend({ rootDir: root }),
+      knownSecrets: ["EXISTS", "MISSING"],
+    });
+    const report = await secrets.doctor();
+    expect(report.backend).toBe("file");
+    expect(report.available).toEqual(["EXISTS"]);
+    expect(report.missing).toEqual(["MISSING"]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,161 @@
+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 class SecretsError extends CrewhausError {
+  override readonly name = "SecretsError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+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 function createSecrets(opts: CreateSecretsOptions): Secrets {
+  const handlers = new Set<RotationHandler>();
+  return {
+    backendId: opts.backend.id,
+
+    async get(name): Promise<SecretValue> {
+      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): Promise<SecretValue> {
+      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: Array<Promise<void>> = [];
+      for (const h of handlers) {
+        try {
+          const result = h(event);
+          if (result && typeof (result as Promise<void>).then === "function") {
+            promises.push(
+              (result as Promise<void>).catch(() => {
+                /* swallow per-handler errors */
+              }),
+            );
+          }
+        } catch {
+          /* swallow per-handler errors */
+        }
+      }
+      await Promise.all(promises);
+      return newValue;
+    },
+
+    onRotation(h): () => void {
+      handlers.add(h);
+      return () => {
+        handlers.delete(h);
+      };
+    },
+
+    async doctor(): Promise<DoctorReport> {
+      const known = opts.knownSecrets ?? [];
+      const available: string[] = [];
+      const missing: string[] = [];
+      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 };