@crewhaus/secrets-manager 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/secrets-manager",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Pluggable secrets backend with rotation + audit-log integration: env-var, file, vault",
   "main": "src/index.ts",
@@ -12,15 +12,15 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.1",
-    "@crewhaus/errors": "0.1.1",
-    "@crewhaus/logging": "0.1.1"
+    "@crewhaus/audit-log": "0.1.3",
+    "@crewhaus/errors": "0.1.3",
+    "@crewhaus/logging": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -32,12 +32,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

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

@@ -0,0 +1,125 @@
+/**
+ * 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/file.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Section 27 — `file` backend coverage.
+ *
+ * `node:fs` is fully mocked with an in-memory store so no real disk I/O
+ * occurs (no tmp dirs, no leaked handles, deterministic). `crypto` is the
+ * real WebCrypto for the auto-generate path, but we only assert its shape
+ * (64 hex chars), so it stays deterministic in intent. `mock.restore()` does
+ * NOT undo `mock.module`, and Bun shares one module registry across all test
+ * files (nondeterministic order) — so the `afterAll` below reinstalls the
+ * real `node:fs`, keeping the in-memory fake from leaking into sibling files.
+ */
+import { afterAll, afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Captured BEFORE the mock below so afterAll can reinstall the real module.
+const realFs = require("node:fs") as typeof import("node:fs");
+
+/** In-memory filesystem state shared with the node:fs mock. */
+type FsState = {
+  files: Map<string, { content: string; mode?: number }>;
+  dirs: Set<string>;
+  writes: Array<{ path: string; content: string; mode?: number }>;
+  renames: Array<{ from: string; to: string }>;
+};
+
+let fsState: FsState;
+
+function freshState(): FsState {
+  return { files: new Map(), dirs: new Set(), writes: [], renames: [] };
+}
+
+// Initialise before the module under test is imported.
+fsState = freshState();
+
+mock.module("node:fs", () => ({
+  existsSync: (p: string) => fsState.files.has(p) || fsState.dirs.has(p),
+  readFileSync: (p: string, _enc?: string) => {
+    const f = fsState.files.get(p);
+    if (!f) {
+      const err = new Error(`ENOENT: no such file ${p}`) as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      throw err;
+    }
+    return f.content;
+  },
+  writeFileSync: (p: string, data: string, opts?: { mode?: number }) => {
+    fsState.files.set(p, { content: data, mode: opts?.mode });
+    fsState.writes.push({ path: p, content: data, mode: opts?.mode });
+  },
+  renameSync: (from: string, to: string) => {
+    const f = fsState.files.get(from);
+    if (f) {
+      fsState.files.set(to, f);
+      fsState.files.delete(from);
+    }
+    fsState.renames.push({ from, to });
+  },
+  readdirSync: (p: string) => {
+    if (!fsState.dirs.has(p)) {
+      const err = new Error(`ENOENT: no such dir ${p}`) as NodeJS.ErrnoException;
+      err.code = "ENOENT";
+      throw err;
+    }
+    const prefix = `${p}/`;
+    const out: string[] = [];
+    for (const key of fsState.files.keys()) {
+      if (key.startsWith(prefix)) out.push(key.slice(prefix.length));
+    }
+    return out;
+  },
+}));
+
+// Import AFTER the mock is registered so the SUT binds to the fake fs.
+const { createFileBackend } = await import("../backends/file");
+const { SecretsError } = await import("../index");
+
+const ROOT = "/fake/secrets";
+
+beforeEach(() => {
+  fsState = freshState();
+  fsState.dirs.add(ROOT);
+});
+
+afterEach(() => {
+  // Reset the in-memory store so each test starts from a clean slate.
+  fsState = freshState();
+});
+
+afterAll(() => {
+  // Reinstall the real module so the in-memory fake cannot outlive this file.
+  mock.module("node:fs", () => realFs);
+});
+
+describe("file backend — get()", () => {
+  test("returns file contents (utf8, whitespace preserved)", async () => {
+    fsState.files.set(`${ROOT}/API_KEY`, { content: "  secret with spaces \n" });
+    const backend = createFileBackend({ rootDir: ROOT });
+    expect(await backend.get("API_KEY")).toBe("  secret with spaces \n");
+  });
+
+  test("throws SecretsError when the file is missing, leaking neither name nor path", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+    expect(backend.get("MISSING")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("MISSING").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      expect(msg).toBe("secret file read failed (not found)");
+      // the secret name and the on-disk path must not appear in the message.
+      expect(msg).not.toContain("MISSING");
+      expect(msg).not.toContain(ROOT);
+    });
+  });
+
+  test("rejects path-traversal names before touching fs, without echoing the name", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+    expect(backend.get("../../etc/passwd")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("../../etc/passwd").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      expect(msg).toContain("invalid secret name");
+      expect(msg).not.toContain("../../etc/passwd");
+    });
+  });
+});
+
+describe("file backend — rotate()", () => {
+  test("writes to a .tmp file (mode 0o600) then renames atomically", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+
+    const v = await backend.rotate("TOKEN", { newValue: "fresh-token" });
+
+    expect(v).toBe("fresh-token");
+    // The committed file holds the new value...
+    expect(fsState.files.get(`${ROOT}/TOKEN`)?.content).toBe("fresh-token");
+    // ...written first to the tmp path with restrictive mode...
+    const tmpWrite = fsState.writes.find((w) => w.path === `${ROOT}/TOKEN.tmp`);
+    expect(tmpWrite).toBeDefined();
+    expect(tmpWrite?.mode).toBe(0o600);
+    // ...and committed via rename(tmp -> final).
+    expect(fsState.renames).toContainEqual({
+      from: `${ROOT}/TOKEN.tmp`,
+      to: `${ROOT}/TOKEN`,
+    });
+  });
+
+  test("auto-generates a 64-char hex secret when newValue is omitted", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+    const v = await backend.rotate("AUTO");
+    expect(v).toMatch(/^[a-f0-9]{64}$/);
+    expect(fsState.files.get(`${ROOT}/AUTO`)?.content).toBe(v);
+  });
+
+  test("rejects malformed names without writing", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+    expect(backend.rotate("path/with/slash")).rejects.toBeInstanceOf(SecretsError);
+    expect(fsState.writes.length).toBe(0);
+  });
+});
+
+describe("file backend — list()", () => {
+  test("lists committed secrets, skipping .tmp and dotfiles", async () => {
+    fsState.files.set(`${ROOT}/A`, { content: "1" });
+    fsState.files.set(`${ROOT}/B`, { content: "2" });
+    fsState.files.set(`${ROOT}/C.tmp`, { content: "x" });
+    fsState.files.set(`${ROOT}/.hidden`, { content: "y" });
+    const backend = createFileBackend({ rootDir: ROOT });
+
+    const names = await backend.list?.();
+
+    expect([...(names ?? [])].sort()).toEqual(["A", "B"]);
+  });
+
+  test("returns [] when the root dir does not exist", async () => {
+    const backend = createFileBackend({ rootDir: "/fake/does-not-exist" });
+    expect(await backend.list?.()).toEqual([]);
+  });
+
+  test("returns [] when the root dir exists but is empty", async () => {
+    const backend = createFileBackend({ rootDir: ROOT });
+    expect(await backend.list?.()).toEqual([]);
+  });
+});

package/src/backends/file.ts

@@ -20,7 +20,7 @@ export function createFileBackend(opts: FileBackendOptions): SecretsBackend {
 
   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_.-]+)`);
+      throw new SecretsError("invalid secret name (must match [A-Za-z0-9_.-]+)");
     }
     return join(rootDir, name);
   }
@@ -30,7 +30,7 @@ export function createFileBackend(opts: FileBackendOptions): SecretsBackend {
     async get(name: string): Promise<SecretValue> {
       const p = pathFor(name);
       if (!existsSync(p)) {
-        throw new SecretsError(`secret "${name}" not found at ${p}`);
+        throw new SecretsError("secret file read failed (not found)");
       }
       return readFileSync(p, "utf8");
     },

package/src/backends/vault.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Section 27 — `vault` backend coverage.
+ *
+ * No real network: every test injects a deterministic `fetchImpl` that
+ * returns canned `Response`s. `VAULT_TOKEN` is saved in beforeEach and
+ * restored in afterEach so the surrounding process env is never mutated
+ * across tests. No real clock, no leaked handles.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createVaultBackend } from "../backends/vault";
+import { SecretsError } from "../index";
+
+const ADDR = "http://127.0.0.1:8200";
+
+/** Build a fetch stub plus a record of the calls it observed. */
+function stubFetch(responder: (url: string, init?: RequestInit) => Response) {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  const fetchImpl = (async (url: string, init?: RequestInit) => {
+    calls.push({ url, init });
+    return responder(url, init);
+  }) as unknown as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+let savedToken: string | undefined;
+
+beforeEach(() => {
+  savedToken = process.env["VAULT_TOKEN"];
+  Reflect.deleteProperty(process.env, "VAULT_TOKEN");
+});
+
+afterEach(() => {
+  if (savedToken === undefined) {
+    Reflect.deleteProperty(process.env, "VAULT_TOKEN");
+  } else {
+    process.env["VAULT_TOKEN"] = savedToken;
+  }
+});
+
+describe("vault backend — id + token resolution", () => {
+  test("exposes the vault id", () => {
+    const backend = createVaultBackend({
+      addr: ADDR,
+      token: "t",
+      fetchImpl: (async () => new Response("{}")) as unknown as typeof fetch,
+    });
+    expect(backend.id).toBe("vault");
+  });
+
+  test("falls back to VAULT_TOKEN env when no constructor token is given", async () => {
+    process.env["VAULT_TOKEN"] = "env-token";
+    const { fetchImpl, calls } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: { value: "v" } } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, fetchImpl });
+
+    await backend.get("K");
+
+    const sentToken = (calls[0]?.init?.headers as Record<string, string>)?.["X-Vault-Token"];
+    expect(sentToken).toBe("env-token");
+  });
+
+  test("constructor token wins over VAULT_TOKEN env", async () => {
+    process.env["VAULT_TOKEN"] = "env-token";
+    const { fetchImpl, calls } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: { value: "v" } } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, token: "ctor-token", fetchImpl });
+
+    await backend.get("K");
+
+    const sentToken = (calls[0]?.init?.headers as Record<string, string>)?.["X-Vault-Token"];
+    expect(sentToken).toBe("ctor-token");
+  });
+
+  test("throws when neither constructor token nor VAULT_TOKEN is set", async () => {
+    const { fetchImpl } = stubFetch(() => new Response("{}"));
+    const backend = createVaultBackend({ addr: ADDR, fetchImpl });
+    expect(backend.get("K")).rejects.toBeInstanceOf(SecretsError);
+  });
+});
+
+describe("vault backend — dataUrl name validation", () => {
+  test("get rejects names with illegal characters (no fetch issued)", async () => {
+    const { fetchImpl, calls } = stubFetch(() => new Response("{}"));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("bad name!")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("bad name!").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      expect(msg).toContain("invalid secret name");
+      expect(msg).not.toContain("bad name!");
+    });
+    expect(calls.length).toBe(0);
+  });
+
+  test("rotate rejects names with illegal characters (no fetch issued)", async () => {
+    const { fetchImpl, calls } = stubFetch(() => new Response("{}"));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.rotate("space here")).rejects.toBeInstanceOf(SecretsError);
+    await backend.rotate("space here").catch(() => {});
+    expect(calls.length).toBe(0);
+  });
+
+  test("allows KV-v2 nested paths (slashes are legal)", async () => {
+    const { fetchImpl, calls } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: { value: "nested" } } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(await backend.get("app/db/password")).toBe("nested");
+    expect(calls[0]?.url).toBe(`${ADDR}/v1/secret/data/app/db/password`);
+  });
+
+  test("uses a custom mount point when provided", async () => {
+    const { fetchImpl, calls } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: { value: "v" } } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, mount: "kv2", token: "t", fetchImpl });
+    await backend.get("K");
+    expect(calls[0]?.url).toBe(`${ADDR}/v1/kv2/data/K`);
+  });
+});
+
+describe("vault backend — get() response handling", () => {
+  test("returns the KV-v2 value on 200", async () => {
+    const { fetchImpl } = stubFetch(
+      () =>
+        new Response(JSON.stringify({ data: { data: { value: "vault-secret" } } }), {
+          status: 200,
+        }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(await backend.get("K")).toBe("vault-secret");
+  });
+
+  test("throws SecretsError on 404 (missing secret) without leaking name or url", async () => {
+    const { fetchImpl } = stubFetch(() => new Response("not found", { status: 404 }));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("SENSITIVE_NAME")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("SENSITIVE_NAME").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      expect(msg).toContain("404");
+      expect(msg).not.toContain("SENSITIVE_NAME");
+      // the url embeds the name + addr; it must not appear either.
+      expect(msg).not.toContain(ADDR);
+    });
+  });
+
+  test("throws SecretsError on a non-ok, non-404 status (e.g. 500) with status but no name/body", async () => {
+    const { fetchImpl } = stubFetch(() => new Response("permission denied", { status: 500 }));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("SENSITIVE_NAME")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("SENSITIVE_NAME").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      // status is retained for debugging...
+      expect(msg).toContain("500");
+      // ...but the raw response body and the secret name are redacted.
+      expect(msg).not.toContain("permission denied");
+      expect(msg).not.toContain("SENSITIVE_NAME");
+    });
+  });
+
+  test("throws when KV-v2 body is missing data.data.value", async () => {
+    const { fetchImpl } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: {} } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("SENSITIVE_NAME")).rejects.toBeInstanceOf(SecretsError);
+    await backend.get("SENSITIVE_NAME").catch((e: unknown) => {
+      const msg = (e as Error).message;
+      expect(msg).toContain("missing data.data.value");
+      expect(msg).not.toContain("SENSITIVE_NAME");
+    });
+  });
+
+  test("throws when the value is present but not a string", async () => {
+    const { fetchImpl } = stubFetch(
+      () => new Response(JSON.stringify({ data: { data: { value: 42 } } }), { status: 200 }),
+    );
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("K")).rejects.toBeInstanceOf(SecretsError);
+  });
+
+  test("throws when the response is an empty object (no data key)", async () => {
+    const { fetchImpl } = stubFetch(() => new Response(JSON.stringify({}), { status: 200 }));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.get("K")).rejects.toBeInstanceOf(SecretsError);
+  });
+});
+
+describe("vault backend — rotate()", () => {
+  test("PUTs the supplied newValue and returns it", async () => {
+    let putBody = "";
+    const { fetchImpl, calls } = stubFetch((_url, init) => {
+      if (init?.method === "PUT") {
+        putBody = init.body as string;
+        return new Response("{}", { status: 204 });
+      }
+      return new Response("not found", { status: 404 });
+    });
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+
+    const v = await backend.rotate("KEY", { newValue: "fresh" });
+
+    expect(v).toBe("fresh");
+    expect(JSON.parse(putBody)).toEqual({ data: { value: "fresh" } });
+    const putCall = calls.find((c) => c.init?.method === "PUT");
+    const headers = putCall?.init?.headers as Record<string, string>;
+    expect(headers?.["X-Vault-Token"]).toBe("t");
+    expect(headers?.["Content-Type"]).toBe("application/json");
+  });
+
+  test("auto-generates a 64-char hex secret when newValue is omitted", async () => {
+    let putBody = "";
+    const { fetchImpl } = stubFetch((_url, init) => {
+      putBody = (init?.body as string) ?? "";
+      return new Response("{}", { status: 200 });
+    });
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+
+    const v = await backend.rotate("KEY");
+
+    expect(v).toMatch(/^[a-f0-9]{64}$/);
+    // the generated value is what got PUT to vault
+    expect(JSON.parse(putBody)).toEqual({ data: { value: v } });
+  });
+
+  test("throws SecretsError when the PUT is not ok, with status but no name/body", async () => {
+    const { fetchImpl } = stubFetch(() => new Response("sealed", { status: 503 }));
+    const backend = createVaultBackend({ addr: ADDR, token: "t", fetchImpl });
+    expect(backend.rotate("SENSITIVE_NAME", { newValue: "x" })).rejects.toBeInstanceOf(
+      SecretsError,
+    );
+    await backend.rotate("SENSITIVE_NAME", { newValue: "x" }).catch((e: unknown) => {
+      const msg = (e as Error).message;
+      // status is retained for debugging...
+      expect(msg).toContain("503");
+      // ...but the raw response body and the secret name are redacted.
+      expect(msg).not.toContain("sealed");
+      expect(msg).not.toContain("SENSITIVE_NAME");
+    });
+  });
+});

package/src/backends/vault.ts

@@ -34,7 +34,7 @@ export function createVaultBackend(opts: VaultBackendOptions): SecretsBackend {
 
   function dataUrl(name: string): string {
     if (!/^[A-Za-z0-9_/.-]+$/.test(name)) {
-      throw new SecretsError(`invalid secret name "${name}" for vault backend`);
+      throw new SecretsError("invalid secret name for vault backend");
     }
     return `${opts.addr}/v1/${encodeURIComponent(mount)}/data/${name}`;
   }
@@ -47,17 +47,15 @@ export function createVaultBackend(opts: VaultBackendOptions): SecretsBackend {
         headers: { "X-Vault-Token": getToken() },
       });
       if (res.status === 404) {
-        throw new SecretsError(`secret "${name}" not found in vault at ${url}`);
+        throw new SecretsError("secret not found in vault (status 404)");
       }
       if (!res.ok) {
-        throw new SecretsError(`vault GET ${name} returned ${res.status}: ${await res.text()}`);
+        throw new SecretsError(`vault request failed (status ${res.status})`);
       }
       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)`,
-        );
+        throw new SecretsError("vault response missing data.data.value (KV v2 expected)");
       }
       return v;
     },
@@ -73,7 +71,7 @@ export function createVaultBackend(opts: VaultBackendOptions): SecretsBackend {
         body: JSON.stringify({ data: { value: newValue } }),
       });
       if (!res.ok) {
-        throw new SecretsError(`vault PUT ${name} returned ${res.status}: ${await res.text()}`);
+        throw new SecretsError(`vault request failed (status ${res.status})`);
       }
       return newValue;
     },

package/src/index.test.ts

@@ -215,6 +215,48 @@ describe("createSecrets — rotation handlers (T3)", () => {
     await secrets.rotate("TOKEN", { newValue: "v2" });
     expect(calls).toBe(1);
   });
+
+  test("async handler that resolves is awaited before rotate() returns", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old");
+    const secrets = createSecrets({ backend: createFileBackend({ rootDir: root }) });
+
+    let settled = false;
+    secrets.onRotation(async (e) => {
+      // microtask + macrotask hop to prove rotate() actually awaits us
+      await Promise.resolve();
+      expect(e.newValue).toBe("async-value");
+      settled = true;
+    });
+
+    await secrets.rotate("TOKEN", { newValue: "async-value" });
+    expect(settled).toBe(true);
+  });
+
+  test("async handler that rejects is swallowed and does not block siblings", async () => {
+    const root = join(tmpRoot, "secrets");
+    require("node:fs").mkdirSync(root);
+    writeFileSync(join(root, "TOKEN"), "old");
+    const secrets = createSecrets({ backend: createFileBackend({ rootDir: root }) });
+
+    const order: string[] = [];
+    // rejecting async handler -> exercises the promise .catch(() => {}) path
+    secrets.onRotation(async () => {
+      order.push("rejecting");
+      await Promise.resolve();
+      throw new Error("async handler boom");
+    });
+    // resolving async sibling -> still runs
+    secrets.onRotation(async () => {
+      order.push("resolving");
+    });
+
+    // rotate must resolve (not reject) despite the rejecting handler
+    const v = await secrets.rotate("TOKEN", { newValue: "v" });
+    expect(v).toBe("v");
+    expect(order).toEqual(["rejecting", "resolving"]);
+  });
 });
 
 describe("createSecrets — audit-log integration (T8 tenant isolation)", () => {