@vellumai/credential-executor 0.11.2-dev.202608060103.4220693 → 0.11.2-dev.202608060508.a7ab7f7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.11.2-dev.202608060103.4220693",
+  "version": "0.11.2-dev.202608060508.a7ab7f7",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/local-secure-key-backend.test.ts

@@ -6,23 +6,38 @@
  * tests in `local-materializers.test.ts`.
  */
 
-import { afterEach, describe, expect, test } from "bun:test";
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
+import { afterEach, describe, expect, spyOn, test } from "bun:test";
+import * as fs from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
 import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+import { CesRpcMethod } from "@vellumai/service-contracts/credential-rpc";
+import type { SecureKeyBackend } from "@vellumai/credential-storage";
+
 import {
   createLocalSecureKeyBackend,
   StoreUnavailableError,
 } from "../materializers/local-secure-key-backend.js";
+import { buildCrudHandlers } from "../main.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function makeTmpDir(): string {
-  const dir = join(tmpdir(), `ces-backend-test-${randomBytes(8).toString("hex")}`);
+  const dir = join(
+    tmpdir(),
+    `ces-backend-test-${randomBytes(8).toString("hex")}`,
+  );
   mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -100,7 +115,9 @@ describe("createLocalSecureKeyBackend — filesystem", () => {
     expect(Buffer.compare(keyAfterFirst, keyAfterSecond)).toBe(0);
 
     // keys.enc has exactly 2 entries
-    const store = JSON.parse(readFileSync(join(securityDir, "keys.enc"), "utf-8"));
+    const store = JSON.parse(
+      readFileSync(join(securityDir, "keys.enc"), "utf-8"),
+    );
     expect(Object.keys(store.entries).length).toBe(2);
 
     // Both values round-trip
@@ -114,16 +131,22 @@ describe("createLocalSecureKeyBackend — filesystem", () => {
     // Manually write a v1 store
     const salt = randomBytes(32).toString("hex");
     const v1Store = { version: 1, salt, entries: {} };
-    writeFileSync(join(securityDir, "keys.enc"), JSON.stringify(v1Store, null, 2), {
-      mode: 0o600,
-    });
+    writeFileSync(
+      join(securityDir, "keys.enc"),
+      JSON.stringify(v1Store, null, 2),
+      {
+        mode: 0o600,
+      },
+    );
 
     const backend = createLocalSecureKeyBackend(vellumRoot);
     const result = await backend.set("v1-key", "v1-value");
     expect(result).toBe(true);
 
     // Read back and verify format preserved
-    const storeAfter = JSON.parse(readFileSync(join(securityDir, "keys.enc"), "utf-8"));
+    const storeAfter = JSON.parse(
+      readFileSync(join(securityDir, "keys.enc"), "utf-8"),
+    );
     expect(storeAfter.version).toBe(1);
     expect(storeAfter.salt).toBe(salt);
     expect(Object.keys(storeAfter.entries)).toContain("v1-key");
@@ -173,7 +196,9 @@ describe("createLocalSecureKeyBackend — filesystem", () => {
       mode: 0o600,
     });
     const backend = createLocalSecureKeyBackend(vellumRoot);
-    await expect(backend.get("anything")).rejects.toThrow(StoreUnavailableError);
+    await expect(backend.get("anything")).rejects.toThrow(
+      StoreUnavailableError,
+    );
   });
 
   test("get() returns undefined when the store reads cleanly but the key is absent", async () => {
@@ -201,4 +226,119 @@ describe("createLocalSecureKeyBackend — filesystem", () => {
     const backend = createLocalSecureKeyBackend(vellumRoot);
     await expect(backend.list()).rejects.toThrow(StoreUnavailableError);
   });
+
+  // -------------------------------------------------------------------------
+  // Store-write durability: the store is written to a temp file with
+  // `flush: true` so the ack the assistant receives follows an fsync.
+  // -------------------------------------------------------------------------
+
+  test("writeStore fsyncs the temp file (flush: true) so the ack follows a durable write", async () => {
+    const { securityDir, vellumRoot } = setup();
+    const spy = spyOn(fs, "writeFileSync");
+    try {
+      const backend = createLocalSecureKeyBackend(vellumRoot);
+      await backend.set("durable/key", "v");
+
+      const keysEncTmpPrefix = join(securityDir, "keys.enc") + ".tmp.";
+      const flushedStoreWrite = spy.mock.calls.some((call) => {
+        const [path, , opts] = call as [
+          unknown,
+          unknown,
+          { flush?: boolean } | undefined,
+        ];
+        return (
+          typeof path === "string" &&
+          path.startsWith(keysEncTmpPrefix) &&
+          !!opts &&
+          typeof opts === "object" &&
+          opts.flush === true
+        );
+      });
+      expect(flushedStoreWrite).toBe(true);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("writeStore fsyncs the parent directory so the rename is durable", async () => {
+    const { vellumRoot } = setup();
+    const fsyncSpy = spyOn(fs, "fsyncSync");
+    try {
+      const backend = createLocalSecureKeyBackend(vellumRoot);
+      await backend.set("durable/key", "v");
+      // The directory fsync runs after the rename; at least one fsyncSync call
+      // must have happened for the store write.
+      expect(fsyncSpy.mock.calls.length).toBeGreaterThan(0);
+    } finally {
+      fsyncSpy.mockRestore();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CES CRUD audit logging (buildCrudHandlers)
+// ---------------------------------------------------------------------------
+
+describe("buildCrudHandlers audit logging", () => {
+  function fakeBackend(over: Partial<SecureKeyBackend> = {}): SecureKeyBackend {
+    return {
+      get: async () => undefined,
+      set: async () => true,
+      delete: async () => "deleted",
+      list: async () => [],
+      ...over,
+    };
+  }
+
+  const ctx = { sessionId: "test-session" };
+
+  test("SetCredential emits an audit line with account + outcome, never the value", async () => {
+    const calls: Array<{ obj: unknown; msg: string }> = [];
+    const audit = {
+      info: (obj: unknown, msg: string) => {
+        calls.push({ obj, msg });
+      },
+    };
+    const handlers = buildCrudHandlers(
+      fakeBackend(),
+      audit as unknown as Parameters<typeof buildCrudHandlers>[1],
+    );
+
+    const res = await handlers[CesRpcMethod.SetCredential]!(
+      { account: "vellum:assistant_api_key", value: "super-secret-value" },
+      ctx,
+    );
+
+    expect(res).toEqual({ ok: true });
+    expect(calls).toContainEqual({
+      obj: { account: "vellum:assistant_api_key", ok: true },
+      msg: "CES credential set",
+    });
+    // The audit line must never carry the credential value.
+    expect(JSON.stringify(calls)).not.toContain("super-secret-value");
+  });
+
+  test("DeleteCredential emits an audit line with account + result", async () => {
+    const calls: Array<{ obj: unknown; msg: string }> = [];
+    const audit = {
+      info: (obj: unknown, msg: string) => {
+        calls.push({ obj, msg });
+      },
+    };
+    const handlers = buildCrudHandlers(
+      fakeBackend({ delete: async () => "deleted" }),
+      audit as unknown as Parameters<typeof buildCrudHandlers>[1],
+    );
+
+    const res = await handlers[CesRpcMethod.DeleteCredential]!(
+      { account: "github:api_token" },
+      ctx,
+    );
+
+    expect(res).toEqual({ result: "deleted" });
+    expect(calls).toContainEqual({
+      obj: { account: "github:api_token", result: "deleted" },
+      msg: "CES credential delete",
+    });
+  });
 });

package/src/main.ts

@@ -75,8 +75,9 @@ function ensureDataDirs(mode: CesMode): void {
  * share the same registry — they differ only in where the secure key backend
  * reads from and whether the health server is started.
  */
-function buildCrudHandlers(
+export function buildCrudHandlers(
   secureKeyBackend: SecureKeyBackend,
+  audit: Pick<ReturnType<typeof getLogger>, "info"> = log,
 ): RpcHandlerRegistry {
   const handlers: RpcHandlerRegistry = {};
 
@@ -90,6 +91,8 @@ function buildCrudHandlers(
     value: string;
   }) => {
     const ok = await secureKeyBackend.set(req.account, req.value);
+    // Audit the mutation: account name and outcome only, never the value.
+    audit.info({ account: req.account, ok }, "CES credential set");
     return { ok };
   }) as (typeof handlers)[string];
 
@@ -97,6 +100,7 @@ function buildCrudHandlers(
     account: string;
   }) => {
     const result = await secureKeyBackend.delete(req.account);
+    audit.info({ account: req.account, result }, "CES credential delete");
     return { result };
   }) as (typeof handlers)[string];
 
@@ -111,6 +115,7 @@ function buildCrudHandlers(
     const results = [];
     for (const { account, value } of req.credentials) {
       const ok = await secureKeyBackend.set(account, value);
+      audit.info({ account, ok }, "CES credential set (bulk)");
       results.push({ account, ok });
     }
     return { results };
@@ -169,6 +174,7 @@ function serveStandaloneSocket(opts: {
 
   netServer.on("connection", (socket: Socket) => {
     connectionCount++;
+    log.info({ connections: connectionCount }, "CES client connected");
     const readable = new Readable({ read() {} });
     const writable = new Writable({
       write(chunk, _encoding, callback) {
@@ -205,6 +211,7 @@ function serveStandaloneSocket(opts: {
       })
       .then(() => {
         connectionCount = Math.max(0, connectionCount - 1);
+        log.info({ connections: connectionCount }, "CES client disconnected");
       });
   });
 
@@ -392,11 +399,19 @@ async function main(): Promise<void> {
     log,
     onApiKeyUpdate:
       mode === "managed"
-        ? (_newKey: string, newAssistantId?: string) => {
-            log.info("Assistant API key updated via RPC");
-            if (newAssistantId) {
-              log.info("Assistant ID updated via RPC");
-            }
+        ? (newKey: string, newAssistantId?: string) => {
+            // Ack-only. CES reads the durable assistant API key from the shared
+            // credential store via the CRUD handlers; this RPC just acknowledges
+            // the assistant's notification that the key rotated. The pushed
+            // value is intentionally not persisted here (length logged, never
+            // the value).
+            log.info(
+              {
+                keyBytes: newKey.length,
+                assistantIdUpdated: Boolean(newAssistantId),
+              },
+              "Acknowledged assistant API key update notification (ack only; value not stored by CES)",
+            );
           }
         : undefined,
   });
@@ -413,11 +428,13 @@ async function main(): Promise<void> {
   log.info("Server stopped.");
 }
 
-main().catch((err) => {
-  try {
-    getLogger("main").fatal({ err }, "Fatal error");
-  } catch {
-    process.stderr.write(`[ces-${getCesMode()}] Fatal: ${err}\n`);
-  }
-  process.exit(1);
-});
+if (import.meta.main) {
+  main().catch((err) => {
+    try {
+      getLogger("main").fatal({ err }, "Fatal error");
+    } catch {
+      process.stderr.write(`[ces-${getCesMode()}] Fatal: ${err}\n`);
+    }
+    process.exit(1);
+  });
+}

package/src/materializers/local-secure-key-backend.ts

@@ -38,7 +38,17 @@ import {
   pbkdf2Sync,
   randomBytes,
 } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
 import { hostname, userInfo } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -55,8 +65,7 @@ const ALGORITHM = "aes-256-gcm";
 const KEY_LENGTH = 32; // bytes (256 bits)
 const IV_LENGTH = 16; // bytes (128 bits)
 const AUTH_TAG_LENGTH = 16; // bytes
-const PBKDF2_ITERATIONS =
-  process.env.BUN_TEST === "1" ? 1 : 100_000;
+const PBKDF2_ITERATIONS = process.env.BUN_TEST === "1" ? 1 : 100_000;
 
 // ---------------------------------------------------------------------------
 // On-disk format (must match assistant/src/security/encrypted-store.ts)
@@ -250,10 +259,30 @@ function writeStore(store: StoreFile, storePath: string): void {
   const protectedDir = dirname(storePath);
   mkdirSync(protectedDir, { recursive: true });
   // Atomic write: write to temp file then rename to avoid partial/corrupt writes.
+  // `flush: true` fsyncs the temp file before we return, so the ack the caller
+  // receives follows a durable write and survives a crash within the window.
   const tmpPath = storePath + `.tmp.${process.pid}`;
-  writeFileSync(tmpPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+  writeFileSync(tmpPath, JSON.stringify(store, null, 2), {
+    mode: 0o600,
+    flush: true,
+  });
   chmodSync(tmpPath, 0o600);
   renameSync(tmpPath, storePath);
+
+  // Fsync the parent directory so the rename itself is durable. `{flush:true}`
+  // syncs the temp file's contents, not the directory entry the rename updates,
+  // so without this a host-level crash could still expose the previous keys.enc.
+  // Best-effort: a directory-fsync failure must not fail the write.
+  try {
+    const dirFd = openSync(protectedDir, "r");
+    try {
+      fsyncSync(dirFd);
+    } finally {
+      closeSync(dirFd);
+    }
+  } catch {
+    // Directory fsync is a durability nicety, not required for correctness.
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -330,7 +359,10 @@ export class StoreUnavailableError extends Error {
  */
 export function createLocalSecureKeyBackend(
   vellumRoot: string,
-  options?: { entropyOverride?: string; entropyGetter?: () => string | undefined },
+  options?: {
+    entropyOverride?: string;
+    entropyGetter?: () => string | undefined;
+  },
 ): SecureKeyBackend {
   const storePath = join(resolveSecurityDir(vellumRoot), KEYS_ENC_FILENAME);
   const staticEntropy = options?.entropyOverride;