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

package/Dockerfile

@@ -56,6 +56,7 @@ COPY --from=builder --chown=ces:ces /app /app
 COPY --chown=ces:ces packages/service-contracts /app/packages/service-contracts
 COPY --chown=ces:ces packages/credential-storage /app/packages/credential-storage
 COPY --chown=ces:ces packages/egress-proxy /app/packages/egress-proxy
+COPY --chown=ces:ces packages/ipc-server-utils /app/packages/ipc-server-utils
 COPY --chown=ces:ces credential-executor ./
 
 # Pre-create /ces-data so the non-root ces user can write to it

package/knip.json

@@ -4,6 +4,7 @@
   "ignoreDependencies": [
     "@vellumai/service-contracts",
     "@vellumai/credential-storage",
-    "@vellumai/egress-proxy"
+    "@vellumai/egress-proxy",
+    "@vellumai/ipc-server-utils"
   ]
 }

package/node_modules/@vellumai/ipc-server-utils/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/ipc-server-utils",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+const windowsEndpoint = (name: string, workspaceDir: string) => resolveIpcEndpoint(name, { workspaceDir, platform: "win32" });
+describe("resolveIpcEndpoint", () => {
+  test("keeps long POSIX fallbacks deterministic and bounded", () => {
+    const options = {
+      workspaceDir: `/tmp/${"a".repeat(120)}`,
+      platform: "darwin" as const,
+    };
+    const endpoint = resolveIpcEndpoint("assistant", options);
+    expect(resolveIpcEndpoint("assistant", options)).toEqual(endpoint);
+    expect(Buffer.byteLength(endpoint.path)).toBeLessThanOrEqual(103);
+  });
+  test("returns normalized, isolated, bounded Windows pipes", () => {
+    const first = windowsEndpoint("assistant", "C:\\one");
+    expect(resolveIpcEndpoint("assistant", { workspaceDir: "c:\\ONE\\", platform: "win32", env: { ASSISTANT_IPC_SOCKET_DIR: "C:\\ignored" } })).toEqual(first);
+    expect(first.path.length).toBeLessThanOrEqual(256);
+    expect(windowsEndpoint("assistant", "C:\\two").path).not.toBe(first.path);
+    expect(windowsEndpoint("gateway", "C:\\one").path).not.toBe(first.path);
+  });
+  test("cleans socket files but skips named pipes", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vellum-ipc-cleanup-"));
+    const socketPath = join(dir, "assistant.sock");
+    try {
+      writeFileSync(socketPath, "stale");
+      removeIpcEndpointFile(socketPath);
+      expect(existsSync(socketPath)).toBe(false);
+      removeIpcEndpointFile("\\\\.\\pipe\\vellum-assistant-test");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/node_modules/@vellumai/ipc-server-utils/src/endpoint.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { posix, win32 } from "node:path";
+
+const DARWIN_UNIX_SOCKET_MAX_PATH_BYTES = 103;
+const DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES = 107;
+const IPC_TMP_DIR_NAME = "vellum-ipc";
+const join = posix.join;
+
+export type IpcSocketPathSource =
+  | "env-override"
+  | "workspace"
+  | "tmp-hash"
+  | "tmp-short-hash"
+  | "windows-named-pipe";
+
+export interface IpcSocketPathResolution {
+  path: string;
+  source: IpcSocketPathSource;
+}
+
+export interface IpcEndpointOptions {
+  workspaceDir: string;
+  env?: Record<string, string | undefined>;
+  platform?: NodeJS.Platform;
+}
+
+function getUnixSocketMaxPathBytes(platform: NodeJS.Platform): number {
+  return platform === "darwin"
+    ? DARWIN_UNIX_SOCKET_MAX_PATH_BYTES
+    : DEFAULT_UNIX_SOCKET_MAX_PATH_BYTES;
+}
+
+function isPathWithinSocketLimit(path: string, maxPathBytes: number): boolean {
+  return Buffer.byteLength(path, "utf8") <= maxPathBytes;
+}
+
+/**
+ * Derive the env var name and socket filename from a socket name.
+ *
+ * Examples (hyphens in the name become underscores in the env var):
+ */
+function deriveSocketNames(socketName: string): {
+  envVar: string;
+  fileName: string;
+} {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(socketName)) {
+    throw new Error(`Invalid IPC endpoint name: ${socketName}`);
+  }
+  const envVar = `${socketName.toUpperCase().replace(/-/g, "_")}_IPC_SOCKET_DIR`;
+  const fileName = `${socketName}.sock`;
+  return { envVar, fileName };
+}
+
+function resolveWindowsNamedPipe(
+  socketName: string,
+  workspaceDir: string,
+): IpcSocketPathResolution {
+  const workspaceIdentity = win32
+    .normalize(workspaceDir)
+    .replace(/\\+$/, "")
+    .toLowerCase();
+  const hash = createHash("sha256")
+    .update(`${workspaceIdentity}\0${socketName}`)
+    .digest("hex")
+    .slice(0, 24);
+  return {
+    path: `\\\\.\\pipe\\vellum-${socketName}-${hash}`,
+    source: "windows-named-pipe",
+  };
+}
+
+export function isNamedPipePath(endpointPath: string): boolean {
+  return /^\\\\[.?]\\pipe\\/.test(endpointPath);
+}
+
+export function removeIpcEndpointFile(endpointPath: string): void {
+  if (isNamedPipePath(endpointPath)) {
+    return;
+  }
+  try {
+    unlinkSync(endpointPath);
+  } catch {
+    // Already absent.
+  }
+}
+
+/**
+ * Resolve the path to an IPC socket file.
+ *
+ * Resolution order:
+ * POSIX uses overrides, workspace paths, then bounded temporary paths.
+ * Windows uses deterministic named pipes.
+ */
+export function resolveIpcEndpoint(
+  socketName: string,
+  options: IpcEndpointOptions,
+): IpcSocketPathResolution {
+  const { envVar, fileName } = deriveSocketNames(socketName);
+  const platform = options.platform ?? process.platform;
+  if (platform === "win32") {
+    return resolveWindowsNamedPipe(socketName, options.workspaceDir);
+  }
+
+  // Explicit override via env var.
+  const envSocketDir = (options.env ?? process.env)[envVar]?.trim();
+  if (envSocketDir) {
+    return {
+      path: join(envSocketDir, fileName),
+      source: "env-override",
+    };
+  }
+
+  const maxPathBytes = getUnixSocketMaxPathBytes(platform);
+  const workspacePath = join(options.workspaceDir, fileName);
+
+  if (isPathWithinSocketLimit(workspacePath, maxPathBytes)) {
+    return {
+      path: workspacePath,
+      source: "workspace",
+    };
+  }
+
+  // Workspace path exceeds AF_UNIX limit - fall back to tmpdir.
+  const hash = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 12);
+  const hashedPath = join(tmpdir(), IPC_TMP_DIR_NAME, `${hash}-${fileName}`);
+  if (isPathWithinSocketLimit(hashedPath, maxPathBytes)) {
+    return {
+      path: hashedPath,
+      source: "tmp-hash",
+    };
+  }
+
+  return {
+    path: join(tmpdir(), `v-${hash}.sock`),
+    source: "tmp-short-hash",
+  };
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -0,0 +1,18 @@
+export {
+  SocketWatchdog,
+  ensureSocketDir,
+  type SocketWatchdogOptions,
+  type SocketWatchdogLogger,
+} from "./socket-watchdog.js";
+export { isNamedPipePath, removeIpcEndpointFile, resolveIpcEndpoint } from "./endpoint.js";
+export { ipcListenOptions } from "./listen-options.js";
+export {
+  IpcFrameReader,
+  writeLegacyMessage,
+  writeMessage,
+  writeStreamChunk,
+  writeStreamEnd,
+  type IpcEnvelope,
+  type OnMessageCallback,
+  type StreamCallbacks,
+} from "./ipc-framing.js";

package/node_modules/@vellumai/ipc-server-utils/src/ipc-framing.ts

@@ -0,0 +1,295 @@
+/**
+ * Length-prefixed binary framing for the IPC protocol.
+ *
+ * Wire format: [4-byte big-endian length][payload bytes]
+ *
+ * Messages use a JSON envelope. When the envelope's `headers` map contains
+ * a `content-length` key, a single binary data frame immediately follows
+ * the JSON frame.
+ *
+ * Chunked streaming: when `headers["transfer-encoding"]` is `"chunked"`,
+ * multiple binary data frames follow the JSON envelope. A zero-length
+ * frame (4 bytes of 0x00) terminates the stream. This enables streaming
+ * responses (e.g. audio, SSE) over IPC without buffering the full payload.
+ *
+ * Backward compatibility: the reader detects legacy newline-delimited JSON
+ * by checking if the first byte is `{` (0x7B). New-format frames always
+ * start with a 4-byte length prefix whose first byte is < 0x7B for any
+ * realistic message size (< 2 GB).
+ */
+
+import type { Socket } from "node:net";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface IpcEnvelope {
+  id: string;
+  // Request fields
+  method?: string;
+  params?: Record<string, unknown>;
+  // Response fields
+  result?: unknown;
+  error?: string;
+  // Shared — when headers["content-length"] is present, a binary frame follows.
+  // When headers["transfer-encoding"] is "chunked", multiple binary frames
+  // follow until a zero-length terminator.
+  headers?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Writing
+// ---------------------------------------------------------------------------
+
+/** Write a length-prefixed frame to a socket. */
+function writeFrame(socket: Socket, data: Buffer | Uint8Array): void {
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(data.length, 0);
+  socket.write(header);
+  socket.write(data);
+}
+
+/**
+ * Write an IPC envelope, optionally followed by a binary data frame.
+ * If `binary` is provided, the envelope's headers must include content-length.
+ */
+export function writeMessage(
+  socket: Socket,
+  envelope: IpcEnvelope,
+  binary?: Uint8Array,
+): void {
+  const json = Buffer.from(JSON.stringify(envelope), "utf-8");
+  writeFrame(socket, json);
+  if (binary) {
+    writeFrame(socket, binary);
+  }
+}
+
+/**
+ * Write a legacy newline-delimited JSON message.
+ * Used when the client connected with the legacy protocol.
+ */
+export function writeLegacyMessage(
+  socket: Socket,
+  envelope: IpcEnvelope,
+): void {
+  socket.write(JSON.stringify(envelope) + "\n");
+}
+
+/**
+ * Write a single chunk in a chunked transfer stream.
+ * The envelope must have already been sent with transfer-encoding: chunked.
+ */
+export function writeStreamChunk(socket: Socket, chunk: Uint8Array): void {
+  writeFrame(socket, chunk);
+}
+
+/**
+ * Write a zero-length frame to signal the end of a chunked transfer stream.
+ */
+export function writeStreamEnd(socket: Socket): void {
+  const terminator = Buffer.alloc(4); // 4 bytes of 0x00 = length 0
+  socket.write(terminator);
+}
+
+// ---------------------------------------------------------------------------
+// Reading
+// ---------------------------------------------------------------------------
+
+/** Callback for complete messages (non-streaming). */
+export type OnMessageCallback = (
+  envelope: IpcEnvelope,
+  binary: Uint8Array | undefined,
+) => void;
+
+/** Callbacks for chunked streaming responses. */
+export interface StreamCallbacks {
+  onStreamStart: (envelope: IpcEnvelope) => void;
+  onStreamChunk: (chunk: Uint8Array) => void;
+  onStreamEnd: () => void;
+}
+
+/**
+ * Streaming reader that accumulates socket data and emits parsed messages.
+ * Handles both legacy newline-delimited JSON and new length-prefixed frames.
+ *
+ * Supports three response modes:
+ * 1. JSON-only: envelope with no binary follow-up
+ * 2. Binary: envelope with content-length → single binary frame
+ * 3. Chunked: envelope with transfer-encoding: chunked → multiple binary
+ *    frames terminated by a zero-length frame
+ */
+export class IpcFrameReader {
+  private buffer = Buffer.alloc(0);
+  private onMessage: OnMessageCallback;
+  private onError: (err: Error) => void;
+  private streamCallbacks: StreamCallbacks | undefined;
+
+  // State machine for length-prefixed reading
+  private state:
+    | "detect"
+    | "read-length"
+    | "read-payload"
+    | "read-binary"
+    | "read-stream-chunk-length"
+    | "read-stream-chunk" = "detect";
+  private pendingLength = 0;
+  private pendingEnvelope: IpcEnvelope | null = null;
+  private expectBinary = false;
+
+  /** Whether this connection uses the legacy newline-delimited protocol. */
+  isLegacy = false;
+
+  constructor(
+    onMessage: OnMessageCallback,
+    onError?: (err: Error) => void,
+    streamCallbacks?: StreamCallbacks,
+  ) {
+    this.onMessage = onMessage;
+    this.onError = onError ?? (() => {});
+    this.streamCallbacks = streamCallbacks;
+  }
+
+  /** Feed incoming socket data into the reader. */
+  push(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    this.drain();
+  }
+
+  private drain(): void {
+    while (true) {
+      if (this.state === "detect") {
+        if (this.buffer.length === 0) {
+          return;
+        }
+        // Legacy detection: first byte is '{' (0x7B)
+        if (this.buffer[0] === 0x7b) {
+          this.isLegacy = true;
+          this.drainLegacy();
+          return;
+        }
+        // New format — fall through to read-length
+        this.state = "read-length";
+      }
+
+      if (this.state === "read-length") {
+        if (this.buffer.length < 4) {
+          return;
+        }
+        this.pendingLength = this.buffer.readUInt32BE(0);
+        this.buffer = this.buffer.subarray(4);
+        this.state = this.expectBinary ? "read-binary" : "read-payload";
+      }
+
+      if (this.state === "read-payload") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const payload = this.buffer.subarray(0, this.pendingLength);
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        let envelope: IpcEnvelope;
+        try {
+          envelope = JSON.parse(payload.toString("utf-8")) as IpcEnvelope;
+        } catch {
+          this.onError(new Error("Invalid JSON in IPC frame"));
+          this.state = "detect";
+          continue;
+        }
+
+        const transferEncoding = envelope.headers?.["transfer-encoding"];
+        if (transferEncoding === "chunked") {
+          // Chunked streaming — emit start, then read chunks until terminator
+          this.pendingEnvelope = envelope;
+          this.streamCallbacks?.onStreamStart(envelope);
+          this.state = "read-stream-chunk-length";
+          continue;
+        }
+
+        const contentLength = envelope.headers?.["content-length"];
+        if (contentLength != null) {
+          // Binary frame follows
+          this.pendingEnvelope = envelope;
+          this.expectBinary = true;
+          this.state = "read-length";
+        } else {
+          this.onMessage(envelope, undefined);
+          this.expectBinary = false;
+          this.state = "detect";
+        }
+        continue;
+      }
+
+      if (this.state === "read-binary") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const binary = new Uint8Array(
+          this.buffer.subarray(0, this.pendingLength),
+        );
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        this.onMessage(this.pendingEnvelope!, binary);
+        this.pendingEnvelope = null;
+        this.expectBinary = false;
+        this.state = "detect";
+        continue;
+      }
+
+      // Chunked streaming states
+      if (this.state === "read-stream-chunk-length") {
+        if (this.buffer.length < 4) {
+          return;
+        }
+        this.pendingLength = this.buffer.readUInt32BE(0);
+        this.buffer = this.buffer.subarray(4);
+
+        if (this.pendingLength === 0) {
+          // Zero-length frame = end of stream
+          this.streamCallbacks?.onStreamEnd();
+          this.pendingEnvelope = null;
+          this.state = "detect";
+          continue;
+        }
+
+        this.state = "read-stream-chunk";
+      }
+
+      if (this.state === "read-stream-chunk") {
+        if (this.buffer.length < this.pendingLength) {
+          return;
+        }
+        const chunk = new Uint8Array(
+          this.buffer.subarray(0, this.pendingLength),
+        );
+        this.buffer = this.buffer.subarray(this.pendingLength);
+
+        this.streamCallbacks?.onStreamChunk(chunk);
+        this.state = "read-stream-chunk-length";
+        continue;
+      }
+    }
+  }
+
+  /**
+   * Legacy mode: parse newline-delimited JSON lines.
+   * Once we enter legacy mode, we stay in it for the lifetime of the connection.
+   */
+  private drainLegacy(): void {
+    let newlineIdx: number;
+    while ((newlineIdx = this.buffer.indexOf(0x0a)) !== -1) {
+      const line = this.buffer.subarray(0, newlineIdx).toString("utf-8").trim();
+      this.buffer = this.buffer.subarray(newlineIdx + 1);
+      if (!line) {
+        continue;
+      }
+      try {
+        const envelope = JSON.parse(line) as IpcEnvelope;
+        this.onMessage(envelope, undefined);
+      } catch {
+        this.onError(new Error("Invalid JSON in legacy IPC line"));
+      }
+    }
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/listen-options.ts

@@ -0,0 +1,3 @@
+export function ipcListenOptions(path: string) {
+  return { path, readableAll: false, writableAll: false } as const;
+}