@vellumai/credential-executor 0.11.2 → 0.11.3-staging.2

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -40,3 +40,42 @@ export function isChannelId(value: unknown): value is ChannelId {
     (CHANNEL_IDS as readonly string[]).includes(value)
   );
 }
+
+/**
+ * The provider key holding each channel's bot credential.
+ *
+ * Two senses of "connected" share the provider registry: a provider the user
+ * authorized so the assistant can act **as them** (`slack`, `discord`,
+ * `google`), and a bot credential letting people reach the assistant **as
+ * itself**. Nothing in a provider key says which, and the naming actively
+ * misleads: `slack` and `discord` name the user integration while their bots
+ * take a `_channel` suffix, yet `telegram` *is* the bot, because Telegram has
+ * no user-identity integration.
+ *
+ * That irregularity is why this is stated rather than derived from the key,
+ * and it is stated here because this file already owns what a channel is.
+ *
+ * Deliberately only the key. What fields each credential requires is declared
+ * once already, per service, in the gateway's credential specs; restating it
+ * here would be a second copy of a different fact.
+ *
+ * Channels absent from this map reach the assistant without a bot credential
+ * of their own: `phone` through the voice provider, `vellum` and `platform`
+ * internally.
+ */
+export const CHANNEL_BOT_PROVIDER = {
+  slack: "slack_channel",
+  discord: "discord_channel",
+  telegram: "telegram",
+} as const satisfies Partial<Record<ChannelId, string>>;
+
+/**
+ * Whether a provider key names a bot the assistant is reached through, rather
+ * than a grant letting it act as the user. This is the "which sense of
+ * connected" question, for any provider key.
+ */
+export function isChannelBotProvider(providerKey: string): boolean {
+  return (Object.values(CHANNEL_BOT_PROVIDER) as readonly string[]).includes(
+    providerKey,
+  );
+}

package/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -20,6 +20,16 @@ export function normalizePublicBaseUrl(value: unknown): string | undefined {
   return normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Application close code the gateway's velay bridge sends to proxied
+ * WebSockets when the tunnel itself is lost (velay disconnect, gateway
+ * shutdown). A dedicated code because the natural 1001 (going away) cannot
+ * be sent through the JS `close()` API (the bridge would remap it to a
+ * misleading 4001), and Bun's WebSocket client drops close reasons, so the
+ * code is the only signal that survives the relay to the daemon.
+ */
+export const GATEWAY_TUNNEL_LOST_WS_CLOSE_CODE = 4801;
+
 export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();

package/node_modules/@vellumai/service-contracts/src/remote-web-pairing.ts

@@ -21,6 +21,12 @@
  * `Date#toISOString()`.
  */
 
+/**
+ * Pairing-challenge TTL in milliseconds (10 minutes): the gateway's challenge
+ * store enforces it and the `vellum pair` CLI renders it in user-facing copy.
+ */
+export const REMOTE_WEB_PAIRING_CODE_TTL_MS = 10 * 60 * 1000;
+
 /** `POST /v1/remote-web/pairing-challenge` request body. */
 export interface RemoteWebPairingChallengeRequest {
   /** Public https base URL the scanning device can reach the assistant at. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.11.2",
+  "version": "0.11.3-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -21,6 +21,7 @@
   "dependencies": {
     "@vellumai/credential-storage": "file:../packages/credential-storage",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+    "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
     "pino": "9.14.0",
     "pino-pretty": "13.1.3"
@@ -28,7 +29,8 @@
   "bundledDependencies": [
     "@vellumai/service-contracts",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/egress-proxy",
+    "@vellumai/ipc-server-utils"
   ],
   "devDependencies": {
     "@types/bun": "1.3.10",

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

@@ -17,7 +17,7 @@
  * optional credential CRUD routes) for Kubernetes liveness/readiness probes.
  */
 
-import { mkdirSync, unlinkSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { createServer as createNetServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
 import { Readable, Writable } from "node:stream";
@@ -27,6 +27,11 @@ import {
   CesRpcMethod,
 } from "@vellumai/service-contracts/credential-rpc";
 import type { SecureKeyBackend } from "@vellumai/credential-storage";
+import {
+  ipcListenOptions,
+  isNamedPipePath,
+  removeIpcEndpointFile,
+} from "@vellumai/ipc-server-utils";
 
 import { createLocalSecureKeyBackend } from "./materializers/local-secure-key-backend.js";
 import { initLogger, getLogger } from "./logger.js";
@@ -75,8 +80,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 +96,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 +105,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 +120,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 };
@@ -154,12 +164,10 @@ function serveStandaloneSocket(opts: {
     onApiKeyUpdate,
   } = opts;
 
-  mkdirSync(dirname(socketPath), { recursive: true });
-  try {
-    unlinkSync(socketPath);
-  } catch {
-    // stale or absent — fine
+  if (!isNamedPipePath(socketPath)) {
+    mkdirSync(dirname(socketPath), { recursive: true });
   }
+  removeIpcEndpointFile(socketPath);
 
   const netServer = createNetServer();
 
@@ -169,6 +177,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,10 +214,11 @@ function serveStandaloneSocket(opts: {
       })
       .then(() => {
         connectionCount = Math.max(0, connectionCount - 1);
+        log.info({ connections: connectionCount }, "CES client disconnected");
       });
   });
 
-  netServer.listen(socketPath, () => {
+  netServer.listen(ipcListenOptions(socketPath), () => {
     log.info(`CES socket listening at ${socketPath}`);
   });
 
@@ -216,11 +226,7 @@ function serveStandaloneSocket(opts: {
     "abort",
     () => {
       netServer.close();
-      try {
-        unlinkSync(socketPath);
-      } catch {
-        // already removed
-      }
+      removeIpcEndpointFile(socketPath);
     },
     { once: true },
   );
@@ -392,11 +398,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 +427,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;