@cohortapp/agent-sdk 2.3.0

package/lib/secrets/broker.mjs

@@ -0,0 +1,315 @@
+/**
+ * lib/secrets/broker.mjs — the secret lifecycle broker (gaps-enterprise-ops
+ * G12 + G16 DR-config).
+ *
+ * Sits above lib/secrets/providers.mjs and turns "where does this secret live"
+ * into a resolution policy plus two fleet operations: pull (sync) and rotate.
+ *
+ *   • resolveSecret(name, {cfg, …})
+ *       Chain precedence: explicit override > broker > file > env.
+ *       The first provider that returns a non-null value wins; every read in
+ *       the chain fails OPEN (a provider error is treated as "not here, keep
+ *       going"), matching the project audit's fail-open posture.
+ *
+ *   • syncSecrets({cfg, names, …})
+ *       Pull a set of secrets from the broker into the local provider (the
+ *       backing store of `maestro secrets sync`). Each pull is a `set` on the
+ *       local provider, so it fails CLOSED per secret — a secret that the
+ *       broker can't supply is reported, not silently skipped.
+ *
+ *   • rotateSecret(name, newValue, {cfg, …})
+ *       Write the new value to the AUTHORITATIVE provider (broker if a broker
+ *       is configured, else the local provider) and record names-only rotation
+ *       metadata. Fail-closed on the write.
+ *
+ * Audit: every rotation appends one line to logs/audit/secrets.jsonl recording
+ * WHO (the agent identity), WHAT (the secret name + a name fingerprint), WHEN,
+ * and the target provider — and NEVER the value. One identity per agent: the
+ * agent token, surfaced via getAgentIdentity().
+ *
+ * Pure node:* + the providers module. The broker's network identity (fetch,
+ * baseUrl, token) is injected through cfg/ctx so the whole module is testable
+ * with a stub fetch and no live calls.
+ *
+ * @module lib/secrets/broker
+ */
+
+"use strict";
+
+import { join } from "node:path";
+
+import { appendJsonl } from "../fs-atomic.mjs";
+import {
+  selectProvider,
+  BrokerProvider,
+  nameFingerprint,
+} from "./providers.mjs";
+
+/** Relative path of the names-only rotation audit log under the agent root. */
+const AUDIT_REL = join("logs", "audit", "secrets.jsonl");
+
+/**
+ * The single agent identity used for broker auth + audit attribution. One
+ * identity per agent (the agent token). Resolution order, all injectable:
+ *   ctx.identity > ctx.env.MAESTRO_AGENT_ID > cfg.broker.identity > "agent".
+ *
+ * @param {object} cfg
+ * @param {object} ctx
+ * @returns {string}
+ */
+export function getAgentIdentity(cfg, ctx = {}) {
+  const env = ctx.env || process.env;
+  return (
+    ctx.identity ||
+    env.MAESTRO_AGENT_ID ||
+    (cfg && cfg.broker && cfg.broker.identity) ||
+    "agent"
+  );
+}
+
+/**
+ * The agent token used as the broker Bearer credential. Injectable so tests
+ * never read a real secret: ctx.token > ctx.env.MAESTRO_AGENT_TOKEN >
+ * cfg.broker.token_env-named env var.
+ *
+ * @param {object} cfg
+ * @param {object} ctx
+ * @returns {string}
+ */
+export function getAgentToken(cfg, ctx = {}) {
+  const env = ctx.env || process.env;
+  if (ctx.token) return ctx.token;
+  const tokenEnv = cfg && cfg.broker && cfg.broker.token_env;
+  if (tokenEnv && env[tokenEnv]) return env[tokenEnv];
+  return env.MAESTRO_AGENT_TOKEN || "";
+}
+
+/**
+ * Construct the broker provider from config, or null when no broker is
+ * configured / no fetch is available. The fetch is INJECTED (ctx.fetch) — we
+ * never reach for the global so tests stay offline by construction.
+ *
+ * @param {object} cfg parsed config/secrets.yaml
+ * @param {object} ctx @param {typeof fetch} [ctx.fetch] @param {string} [ctx.token]
+ * @returns {BrokerProvider|null}
+ */
+export function makeBroker(cfg, ctx = {}) {
+  const bcfg = (cfg && cfg.broker) || {};
+  const enabled = bcfg.enabled !== false; // default-on when a broker block exists
+  const baseUrl = ctx.baseUrl || bcfg.base_url || bcfg.baseUrl;
+  const fetchImpl = ctx.fetch; // required — no implicit global fetch
+  if (!enabled || !baseUrl || !fetchImpl) return null;
+  return new BrokerProvider({
+    baseUrl,
+    token: getAgentToken(cfg, ctx),
+    fetch: fetchImpl,
+  });
+}
+
+/**
+ * Whether a broker is the authoritative writer for this agent. A broker is
+ * authoritative when one is configured AND constructible (fetch present).
+ *
+ * @param {object} cfg
+ * @param {object} ctx
+ * @returns {boolean}
+ */
+export function brokerIsAuthoritative(cfg, ctx = {}) {
+  return makeBroker(cfg, ctx) != null;
+}
+
+/**
+ * Resolve one secret by walking the provider chain in precedence order:
+ *   explicit override > broker > file (local provider) > env.
+ *
+ * `explicit` lets a caller pin one provider (used by tooling that already
+ * knows where a value lives). Every read fails open: a provider that throws
+ * or returns null is skipped and the chain continues. Returns the first
+ * non-null value, or null if nothing in the chain has it.
+ *
+ * @param {string} name
+ * @param {object} args
+ * @param {object} args.cfg parsed config/secrets.yaml
+ * @param {string} [args.agentRoot]
+ * @param {Record<string,string>} [args.env]
+ * @param {typeof fetch} [args.fetch] injected fetch for the broker link
+ * @param {string} [args.token] injected agent token
+ * @param {{get:(n:string)=>any}} [args.explicit] an explicit provider to try first
+ * @returns {Promise<string|null>}
+ */
+export async function resolveSecret(name, args = {}) {
+  const { cfg, agentRoot = ".", env, explicit } = args;
+  const ctx = { agentRoot, env, fetch: args.fetch, token: args.token, baseUrl: args.baseUrl };
+
+  const chain = [];
+  if (explicit) chain.push(explicit);
+
+  const broker = makeBroker(cfg, ctx);
+  if (broker) chain.push(broker);
+
+  // Local provider (file by default). If config explicitly selects `env`, the
+  // local provider IS env — we still add an env provider below, but a duplicate
+  // read is harmless (both fail open) and keeps the precedence comment honest.
+  const local = selectProvider(cfg, { agentRoot, env });
+  chain.push(local);
+
+  // Env is the final fallback so process-injected secrets always resolve even
+  // when nothing else is configured.
+  if (local.name !== "env") {
+    const { EnvProvider } = await import("./providers.mjs");
+    chain.push(new EnvProvider({ env }));
+  }
+
+  for (const provider of chain) {
+    try {
+      const v = await provider.get(name);
+      if (v != null && v !== "") return v;
+    } catch {
+      // fail open — try the next link
+    }
+  }
+  return null;
+}
+
+/**
+ * Pull a set of secrets from the broker into the local provider. This is the
+ * engine behind `maestro secrets sync`: it makes the local encrypted store the
+ * cached, offline-readable mirror of the org's broker.
+ *
+ * Per-secret semantics: fetch from the broker (fail-open read), then `set` on
+ * the local provider (fail-CLOSED write). A secret the broker doesn't have is
+ * recorded as `missing`; a local write that throws is recorded as `failed`.
+ * The caller (CLI) decides how loudly to surface those.
+ *
+ * @param {object} args
+ * @param {object} args.cfg
+ * @param {string[]} args.names secret names to pull (required)
+ * @param {string} [args.agentRoot]
+ * @param {Record<string,string>} [args.env]
+ * @param {typeof fetch} args.fetch injected broker fetch (required for a real pull)
+ * @param {string} [args.token]
+ * @returns {Promise<{synced:string[], missing:string[], failed:{name:string,error:string}[]}>}
+ */
+export async function syncSecrets(args = {}) {
+  const { cfg, agentRoot = ".", env, names } = args;
+  if (!Array.isArray(names)) {
+    throw new Error("syncSecrets: { names: string[] } is required");
+  }
+  const ctx = { agentRoot, env, fetch: args.fetch, token: args.token, baseUrl: args.baseUrl };
+  const broker = makeBroker(cfg, ctx);
+  if (!broker) {
+    throw new Error("syncSecrets: no broker configured (need config.broker + an injected fetch)");
+  }
+  const local = selectProvider(cfg, { agentRoot, env });
+  if (local.readonly) {
+    throw new Error(`syncSecrets: local provider "${local.name}" is read-only — cannot cache pulled secrets`);
+  }
+
+  const result = { synced: [], missing: [], failed: [] };
+  for (const name of names) {
+    let value = null;
+    try {
+      value = await broker.get(name); // fail-open read
+    } catch {
+      value = null;
+    }
+    if (value == null) {
+      result.missing.push(name);
+      continue;
+    }
+    try {
+      await local.set(name, value); // fail-closed write
+      result.synced.push(name);
+    } catch (err) {
+      result.failed.push({ name, error: err.message });
+    }
+  }
+  return result;
+}
+
+/**
+ * Rotate a secret: write `newValue` to the authoritative provider and record
+ * names-only rotation metadata. Authoritative = broker when configured, else
+ * the local provider. The write is fail-CLOSED (a throw propagates) so a
+ * botched rotation never looks like success.
+ *
+ * The audit line records who/what/when/where — never the value. On a broker
+ * rotation we also `set` the local mirror best-effort so the agent can keep
+ * reading the new value offline; a mirror failure does NOT fail the rotation
+ * (the authoritative write already succeeded) but is noted in the return.
+ *
+ * @param {string} name
+ * @param {string} newValue
+ * @param {object} args
+ * @param {object} args.cfg
+ * @param {string} [args.agentRoot]
+ * @param {Record<string,string>} [args.env]
+ * @param {typeof fetch} [args.fetch]
+ * @param {string} [args.token]
+ * @param {string} [args.identity] override the audited agent identity
+ * @param {(p:string,r:object)=>boolean} [args.appendAudit] injected audit sink (tests)
+ * @returns {Promise<{name:string, provider:string, identity:string, at:string, mirrored:boolean}>}
+ */
+export async function rotateSecret(name, newValue, args = {}) {
+  const { cfg, agentRoot = ".", env } = args;
+  if (!name || typeof name !== "string") {
+    throw new Error("rotateSecret: a secret name is required");
+  }
+  if (newValue == null || newValue === "") {
+    throw new Error(`rotateSecret: a non-empty value is required for "${name}"`);
+  }
+  const ctx = { agentRoot, env, fetch: args.fetch, token: args.token, baseUrl: args.baseUrl };
+  const broker = makeBroker(cfg, ctx);
+  const local = selectProvider(cfg, { agentRoot, env });
+
+  let authoritative;
+  if (broker) authoritative = broker;
+  else if (!local.readonly) authoritative = local;
+  else {
+    throw new Error(
+      `rotateSecret: no writable authoritative provider (local "${local.name}" is read-only and no broker is configured)`
+    );
+  }
+
+  // Fail-closed authoritative write.
+  await authoritative.set(name, newValue);
+
+  // Best-effort local mirror when the broker is authoritative so reads stay
+  // offline-fast. Never overrides the success of the authoritative write.
+  let mirrored = false;
+  if (authoritative === broker && !local.readonly) {
+    try {
+      await local.set(name, newValue);
+      mirrored = true;
+    } catch {
+      mirrored = false;
+    }
+  }
+
+  const identity = getAgentIdentity(cfg, { ...ctx, identity: args.identity });
+  const at = new Date().toISOString();
+  const record = {
+    event: "secret-rotated",
+    at,
+    identity,
+    name, // the NAME is operational metadata; the VALUE is never logged
+    name_fingerprint: nameFingerprint(name),
+    provider: authoritative.name,
+    mirrored,
+  };
+  const sink = args.appendAudit || appendJsonl;
+  sink(join(String(agentRoot), AUDIT_REL), record);
+
+  return { name, provider: authoritative.name, identity, at, mirrored };
+}
+
+/**
+ * Resolve the path of the names-only rotation audit log for an agent root.
+ * Exported so the CLI / doctor can point at it without duplicating the const.
+ *
+ * @param {string} agentRoot
+ * @returns {string}
+ */
+export function auditLogPath(agentRoot) {
+  return join(String(agentRoot || "."), AUDIT_REL);
+}

package/lib/secrets/broker.test.mjs

@@ -0,0 +1,280 @@
+/**
+ * lib/secrets/broker.test.mjs — resolution chain, sync, rotate, names-only audit.
+ *
+ * Covers:
+ *   • resolveSecret chain precedence: explicit > broker > file > env
+ *   • resolveSecret fails open through a throwing provider
+ *   • syncSecrets pulls a set from an INJECTED broker fetch into the local store
+ *   • syncSecrets reports missing + write failures
+ *   • rotateSecret writes to the authoritative provider (broker > local)
+ *   • rotateSecret audits names-only (never the value), with identity + fingerprint
+ *   • getAgentIdentity / getAgentToken resolution
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  resolveSecret,
+  syncSecrets,
+  rotateSecret,
+  getAgentIdentity,
+  getAgentToken,
+  makeBroker,
+  brokerIsAuthoritative,
+  auditLogPath,
+} from "./broker.mjs";
+import { FileProvider, nameFingerprint } from "./providers.mjs";
+
+async function tmpRoot(prefix = "secrets-broker") {
+  const path = join(tmpdir(), `${prefix}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+
+/** A fetch stub backed by an in-memory secrets object (offline). */
+function brokerFetchStub(secrets) {
+  return async (url, opts = {}) => {
+    const u = new URL(url);
+    const m = u.pathname.match(/\/secrets\/(.+)$/);
+    if (opts.method === "GET" && u.pathname === "/secrets") {
+      return { ok: true, status: 200, json: async () => ({ secrets: Object.keys(secrets).map((name) => ({ name })) }) };
+    }
+    if (opts.method === "GET" && m) {
+      const name = decodeURIComponent(m[1]);
+      if (!(name in secrets)) return { ok: false, status: 404, json: async () => ({}) };
+      return { ok: true, status: 200, json: async () => ({ value: secrets[name] }) };
+    }
+    if (opts.method === "PUT" && m) {
+      secrets[decodeURIComponent(m[1])] = JSON.parse(opts.body).value;
+      return { ok: true, status: 200, json: async () => ({}) };
+    }
+    return { ok: false, status: 400, json: async () => ({}) };
+  };
+}
+
+const BROKER_CFG = { provider: "file", broker: { base_url: "https://broker.example", token_env: "MAESTRO_AGENT_TOKEN" } };
+
+// ---------------------------------------------------------------------------
+// identity + token
+// ---------------------------------------------------------------------------
+
+test("getAgentIdentity / getAgentToken resolve from ctx then env then cfg", () => {
+  assert.equal(getAgentIdentity({}, { identity: "explicit" }), "explicit");
+  assert.equal(getAgentIdentity({}, { env: { MAESTRO_AGENT_ID: "robin" } }), "robin");
+  assert.equal(getAgentIdentity({ broker: { identity: "cfg-id" } }, { env: {} }), "cfg-id");
+  assert.equal(getAgentIdentity({}, { env: {} }), "agent");
+
+  assert.equal(getAgentToken({}, { token: "tok" }), "tok");
+  assert.equal(getAgentToken(BROKER_CFG, { env: { MAESTRO_AGENT_TOKEN: "from-env" } }), "from-env");
+  assert.equal(getAgentToken({}, { env: {} }), "");
+});
+
+test("makeBroker / brokerIsAuthoritative require config + an injected fetch", () => {
+  assert.equal(makeBroker({}, {}), null, "no broker block → null");
+  assert.equal(makeBroker(BROKER_CFG, {}), null, "no fetch → null (stay offline)");
+  const b = makeBroker(BROKER_CFG, { fetch: async () => ({ ok: true, status: 200, json: async () => ({}) }), token: "t" });
+  assert.ok(b && b.name === "broker");
+  assert.equal(brokerIsAuthoritative(BROKER_CFG, { fetch: b._fetch }), true);
+  assert.equal(brokerIsAuthoritative({}, {}), false);
+});
+
+// ---------------------------------------------------------------------------
+// resolveSecret — chain precedence
+// ---------------------------------------------------------------------------
+
+test("resolveSecret precedence: explicit > broker > file > env", async () => {
+  const root = await tmpRoot();
+  try {
+    // Seed the file store with FILE_KEY; broker has BROKER_KEY + a shadowed key.
+    const file = new FileProvider({ agentRoot: root });
+    file.set("FILE_KEY", "from-file");
+    file.set("SHADOW", "file-shadow");
+    const secrets = { BROKER_KEY: "from-broker", SHADOW: "broker-shadow" };
+    const fetch = brokerFetchStub(secrets);
+    const env = { ENV_KEY: "from-env", SHADOW: "env-shadow" };
+
+    const base = { cfg: BROKER_CFG, agentRoot: root, env, fetch, token: "t" };
+
+    // explicit wins over everything
+    const explicit = { get: () => "from-explicit" };
+    assert.equal(await resolveSecret("SHADOW", { ...base, explicit }), "from-explicit");
+
+    // broker beats file beats env on the same name
+    assert.equal(await resolveSecret("SHADOW", base), "broker-shadow");
+
+    // broker-only key resolves from the broker
+    assert.equal(await resolveSecret("BROKER_KEY", base), "from-broker");
+    // file-only key resolves from the file store
+    assert.equal(await resolveSecret("FILE_KEY", base), "from-file");
+    // env-only key resolves from env (final fallback)
+    assert.equal(await resolveSecret("ENV_KEY", base), "from-env");
+    // nothing has it
+    assert.equal(await resolveSecret("ABSENT", base), null);
+  } finally { await rmRoot(root); }
+});
+
+test("resolveSecret fails open through a throwing provider in the chain", async () => {
+  const root = await tmpRoot();
+  try {
+    const file = new FileProvider({ agentRoot: root });
+    file.set("K", "from-file");
+    const explicit = { get: () => { throw new Error("boom"); } };
+    // Explicit throws → chain continues to the file store.
+    assert.equal(await resolveSecret("K", { cfg: { provider: "file" }, agentRoot: root, env: {}, explicit }), "from-file");
+  } finally { await rmRoot(root); }
+});
+
+test("resolveSecret with no broker config still reads file then env", async () => {
+  const root = await tmpRoot();
+  try {
+    const file = new FileProvider({ agentRoot: root });
+    file.set("ONLY_FILE", "f");
+    const args = { cfg: { provider: "file" }, agentRoot: root, env: { ONLY_ENV: "e" } };
+    assert.equal(await resolveSecret("ONLY_FILE", args), "f");
+    assert.equal(await resolveSecret("ONLY_ENV", args), "e");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// syncSecrets — pull from injected broker into local store
+// ---------------------------------------------------------------------------
+
+test("syncSecrets pulls a set from the broker into the local file store", async () => {
+  const root = await tmpRoot();
+  try {
+    const secrets = { A: "alpha", B: "bravo", C: "charlie" };
+    const fetch = brokerFetchStub(secrets);
+    const res = await syncSecrets({
+      cfg: BROKER_CFG, agentRoot: root, env: {}, fetch, token: "t",
+      names: ["A", "B", "MISSING"],
+    });
+    assert.deepEqual(res.synced.sort(), ["A", "B"]);
+    assert.deepEqual(res.missing, ["MISSING"]);
+    assert.deepEqual(res.failed, []);
+
+    // The local store now holds the pulled values, sealed.
+    const file = new FileProvider({ agentRoot: root });
+    assert.equal(file.get("A"), "alpha");
+    assert.equal(file.get("B"), "bravo");
+    assert.equal(file.get("MISSING"), null);
+
+    // And the value never appears in plaintext on disk.
+    const raw = readFileSync(join(root, "state/secrets/.secrets.json"), "utf-8");
+    assert.ok(!raw.includes("alpha") && !raw.includes("bravo"), "sealed at rest");
+  } finally { await rmRoot(root); }
+});
+
+test("syncSecrets throws when no broker is configured", async () => {
+  const root = await tmpRoot();
+  try {
+    await assert.rejects(
+      () => syncSecrets({ cfg: { provider: "file" }, agentRoot: root, names: ["A"] }),
+      /no broker configured/
+    );
+  } finally { await rmRoot(root); }
+});
+
+test("syncSecrets requires names array", async () => {
+  await assert.rejects(() => syncSecrets({ cfg: BROKER_CFG }), /names: string\[\] \} is required/);
+});
+
+// ---------------------------------------------------------------------------
+// rotateSecret — authoritative write + names-only audit
+// ---------------------------------------------------------------------------
+
+test("rotateSecret writes to the local provider and audits names-only", async () => {
+  const root = await tmpRoot();
+  try {
+    const res = await rotateSecret("DB_PASSWORD", "p@ss-NEW", {
+      cfg: { provider: "file" }, agentRoot: root, env: { MAESTRO_AGENT_ID: "alex" },
+    });
+    assert.equal(res.provider, "file");
+    assert.equal(res.identity, "alex");
+    assert.match(res.at, /^\d{4}-\d{2}-\d{2}T/);
+
+    // The new value is readable.
+    const file = new FileProvider({ agentRoot: root });
+    assert.equal(file.get("DB_PASSWORD"), "p@ss-NEW");
+
+    // Audit line: names + identity + fingerprint, NEVER the value.
+    const logPath = auditLogPath(root);
+    assert.ok(existsSync(logPath), "audit log written");
+    const raw = readFileSync(logPath, "utf-8").trim();
+    assert.ok(!raw.includes("p@ss-NEW"), "audit must never contain the secret value");
+    const rec = JSON.parse(raw.split("\n").pop());
+    assert.equal(rec.event, "secret-rotated");
+    assert.equal(rec.name, "DB_PASSWORD");
+    assert.equal(rec.identity, "alex");
+    assert.equal(rec.provider, "file");
+    assert.equal(rec.name_fingerprint, nameFingerprint("DB_PASSWORD"));
+  } finally { await rmRoot(root); }
+});
+
+test("rotateSecret writes to the broker (authoritative) and mirrors locally", async () => {
+  const root = await tmpRoot();
+  try {
+    const secrets = {};
+    const fetch = brokerFetchStub(secrets);
+    const res = await rotateSecret("API_TOKEN", "tok-rotated", {
+      cfg: BROKER_CFG, agentRoot: root, env: {}, fetch, token: "agent-tok", identity: "robin",
+    });
+    assert.equal(res.provider, "broker", "broker is authoritative when configured");
+    assert.equal(res.mirrored, true, "local mirror written for offline reads");
+    assert.equal(secrets.API_TOKEN, "tok-rotated", "broker received the rotation");
+    // Local mirror holds it too.
+    assert.equal(new FileProvider({ agentRoot: root }).get("API_TOKEN"), "tok-rotated");
+  } finally { await rmRoot(root); }
+});
+
+test("rotateSecret fails closed on an empty value or missing name", async () => {
+  const root = await tmpRoot();
+  try {
+    await assert.rejects(() => rotateSecret("", "v", { cfg: { provider: "file" }, agentRoot: root }), /name is required/);
+    await assert.rejects(() => rotateSecret("K", "", { cfg: { provider: "file" }, agentRoot: root }), /non-empty value/);
+  } finally { await rmRoot(root); }
+});
+
+test("rotateSecret fails closed when the broker write rejects", async () => {
+  const root = await tmpRoot();
+  try {
+    const fetch = async (url, opts) => {
+      if (opts.method === "PUT") return { ok: false, status: 503, json: async () => ({}) };
+      return { ok: false, status: 404, json: async () => ({}) };
+    };
+    await assert.rejects(
+      () => rotateSecret("K", "v", { cfg: BROKER_CFG, agentRoot: root, env: {}, fetch, token: "t" }),
+      /failed \(status 503\)/
+    );
+    // No audit line on a failed rotation.
+    assert.ok(!existsSync(auditLogPath(root)), "no audit on failed authoritative write");
+  } finally { await rmRoot(root); }
+});
+
+test("rotateSecret fails closed when the local provider is read-only (env) and no broker", async () => {
+  const root = await tmpRoot();
+  try {
+    await assert.rejects(
+      () => rotateSecret("K", "v", { cfg: { provider: "env" }, agentRoot: root, env: {} }),
+      /no writable authoritative provider/
+    );
+  } finally { await rmRoot(root); }
+});
+
+test("rotateSecret uses an injected audit sink when provided", async () => {
+  const root = await tmpRoot();
+  try {
+    const lines = [];
+    await rotateSecret("K", "v", {
+      cfg: { provider: "file" }, agentRoot: root, env: {},
+      appendAudit: (p, rec) => { lines.push({ p, rec }); return true; },
+    });
+    assert.equal(lines.length, 1);
+    assert.equal(lines[0].rec.name, "K");
+    assert.ok(lines[0].p.endsWith("logs/audit/secrets.jsonl"));
+  } finally { await rmRoot(root); }
+});