chainlesschain 0.165.5 → 0.165.6

package/src/lib/background-session-transport.js

@@ -33,6 +33,10 @@ import {
 
 const HELLO_TIMEOUT_MS = 5000;
 const MAX_LINE_BYTES = 1024 * 1024;
+export const BACKGROUND_SESSION_BACKLOG_LIMITS = Object.freeze({
+  messages: 256,
+  bytes: 1024 * 1024,
+});
 
 /** Pipe endpoint for a session id (Windows named pipe / POSIX socket file). */
 export function transportPipePath(id, dir, options = {}) {
@@ -70,14 +74,128 @@ export function createNdjsonReader(onMessage, onError = () => {}) {
   };
 }
 
-function writeMessage(socket, message) {
-  if (!socket || socket.destroyed) return false;
-  try {
-    socket.write(`${JSON.stringify(message)}\n`);
-    return true;
-  } catch {
+/**
+ * A socket writer with an application-level queue above Node's native write
+ * buffer. Once `socket.write()` reports backpressure, later messages wait for
+ * `drain`; a consumer that exceeds either cap is disconnected instead of
+ * retaining an unbounded event history in the worker.
+ */
+export function createBoundedSocketWriter(socket, configured = {}) {
+  const maxMessages = Math.max(
+    1,
+    Number.isFinite(configured.messages)
+      ? Math.floor(configured.messages)
+      : BACKGROUND_SESSION_BACKLOG_LIMITS.messages,
+  );
+  const maxBytes = Math.max(
+    1024,
+    Number.isFinite(configured.bytes)
+      ? Math.floor(configured.bytes)
+      : BACKGROUND_SESSION_BACKLOG_LIMITS.bytes,
+  );
+  const queue = [];
+  let queuedBytes = 0;
+  let waitingForDrain = false;
+  let closed = false;
+  let overflowed = false;
+
+  const nativeBufferedBytes = () =>
+    Number.isFinite(socket?.writableLength)
+      ? Math.max(0, socket.writableLength)
+      : 0;
+  const clear = () => {
+    queue.length = 0;
+    queuedBytes = 0;
+    waitingForDrain = false;
+  };
+  const overflow = () => {
+    if (overflowed) return false;
+    overflowed = true;
+    closed = true;
+    clear();
+    try {
+      configured.onOverflow?.({ maxMessages, maxBytes });
+    } catch {
+      /* observer errors do not change the fail-closed outcome */
+    }
+    try {
+      socket?.destroy();
+    } catch {
+      /* already closed */
+    }
     return false;
-  }
+  };
+  const writePayload = (payload) => {
+    try {
+      if (socket.write(payload) === false) waitingForDrain = true;
+      return true;
+    } catch {
+      closed = true;
+      clear();
+      return false;
+    }
+  };
+  const flush = () => {
+    if (closed || socket?.destroyed) {
+      closed = true;
+      clear();
+      return;
+    }
+    waitingForDrain = false;
+    while (queue.length > 0 && !waitingForDrain) {
+      const next = queue.shift();
+      queuedBytes -= next.bytes;
+      if (!writePayload(next.payload)) break;
+    }
+  };
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    clear();
+    socket?.removeListener?.("drain", flush);
+  };
+
+  socket?.on?.("drain", flush);
+  socket?.once?.("close", close);
+  socket?.once?.("error", close);
+
+  return Object.freeze({
+    write(message) {
+      if (closed || !socket || socket.destroyed) return false;
+      let payload;
+      try {
+        payload = `${JSON.stringify(message)}\n`;
+      } catch {
+        return false;
+      }
+      const bytes = Buffer.byteLength(payload, "utf8");
+      if (bytes > maxBytes) return overflow();
+      if (waitingForDrain || queue.length > 0) {
+        if (
+          queue.length + 1 > maxMessages ||
+          nativeBufferedBytes() + queuedBytes + bytes > maxBytes
+        ) {
+          return overflow();
+        }
+        queue.push({ payload, bytes });
+        queuedBytes += bytes;
+        return true;
+      }
+      if (nativeBufferedBytes() + bytes > maxBytes) return overflow();
+      return writePayload(payload);
+    },
+    close,
+    state: () => ({
+      queuedMessages: queue.length,
+      queuedBytes,
+      nativeBufferedBytes: nativeBufferedBytes(),
+      waitingForDrain,
+      overflowed,
+      closed,
+      maxMessages,
+      maxBytes,
+    }),
+  });
 }
 
 /**
@@ -117,7 +235,7 @@ export function startBackgroundSessionServer(opts) {
       /* fine — usually ENOENT */
     }
   }
-  const clients = new Set();
+  const clients = new Map();
   const notifyClients = () => {
     try {
       onClientChange?.(clients.size);
@@ -128,6 +246,8 @@ export function startBackgroundSessionServer(opts) {
 
   const server = net.createServer((socket) => {
     let authed = false;
+    const writer = createBoundedSocketWriter(socket);
+    const send = (message) => writer.write(message);
     const helloTimer = setTimeout(() => {
       if (!authed) socket.destroy();
     }, HELLO_TIMEOUT_MS);
@@ -141,8 +261,8 @@ export function startBackgroundSessionServer(opts) {
             if (message.type === "hello" && message.token === token) {
               authed = true;
               clearTimeout(helloTimer);
-              clients.add(socket);
-              writeMessage(socket, {
+              clients.set(socket, writer);
+              send({
                 type: "hello",
                 ...(getStatus ? getStatus() : { id }),
               });
@@ -156,7 +276,7 @@ export function startBackgroundSessionServer(opts) {
             case "prompt": {
               const text = String(message.text || "").trim();
               if (!text) {
-                writeMessage(socket, {
+                send({
                   type: "error",
                   message: "prompt text is empty",
                 });
@@ -164,12 +284,12 @@ export function startBackgroundSessionServer(opts) {
               }
               try {
                 const result = onPrompt(text);
-                writeMessage(socket, {
+                send({
                   type: "accepted",
                   queued: result?.queued ?? 1,
                 });
               } catch (error) {
-                writeMessage(socket, {
+                send({
                   type: "error",
                   message: error?.message || String(error),
                 });
@@ -177,7 +297,7 @@ export function startBackgroundSessionServer(opts) {
               return;
             }
             case "status": {
-              writeMessage(socket, {
+              send({
                 type: "status",
                 ...(getStatus ? getStatus() : { id }),
               });
@@ -186,9 +306,9 @@ export function startBackgroundSessionServer(opts) {
             case "stop": {
               try {
                 onStop?.();
-                writeMessage(socket, { type: "stopping" });
+                send({ type: "stopping" });
               } catch (error) {
-                writeMessage(socket, {
+                send({
                   type: "error",
                   message: error?.message || String(error),
                 });
@@ -206,7 +326,7 @@ export function startBackgroundSessionServer(opts) {
                   message;
                 const resolvedId = requestId || intId;
                 if (!resolvedId) {
-                  writeMessage(socket, {
+                  send({
                     type: "error",
                     message: "interaction_response requires requestId or intId",
                   });
@@ -219,7 +339,7 @@ export function startBackgroundSessionServer(opts) {
                   answer: answer ?? result,
                   error,
                 });
-                writeMessage(socket, {
+                send({
                   type: "received",
                   requestId: resolvedId,
                   accepted:
@@ -232,7 +352,7 @@ export function startBackgroundSessionServer(opts) {
                       : false,
                 });
               } catch (err) {
-                writeMessage(socket, {
+                send({
                   type: "error",
                   message: err?.message || String(err),
                 });
@@ -240,7 +360,7 @@ export function startBackgroundSessionServer(opts) {
               return;
             }
             default:
-              writeMessage(socket, {
+              send({
                 type: "error",
                 message: `unknown message type: ${message.type}`,
               });
@@ -256,6 +376,7 @@ export function startBackgroundSessionServer(opts) {
 
     const drop = () => {
       clearTimeout(helloTimer);
+      writer.close();
       if (clients.delete(socket)) notifyClients();
     };
     socket.on("close", drop);
@@ -281,11 +402,11 @@ export function startBackgroundSessionServer(opts) {
         pipePath,
         clientCount: () => clients.size,
         broadcast: (message) => {
-          for (const socket of clients) writeMessage(socket, message);
+          for (const writer of clients.values()) writer.write(message);
         },
         broadcastInteractionRequest: (intId, payload, binding = null) => {
-          for (const socket of clients)
-            writeMessage(socket, {
+          for (const writer of clients.values())
+            writer.write({
               type: "interaction_request",
               intId,
               requestId: intId,
@@ -302,7 +423,10 @@ export function startBackgroundSessionServer(opts) {
         },
         close: () =>
           new Promise((done) => {
-            for (const socket of clients) socket.destroy();
+            for (const [socket, writer] of clients) {
+              writer.close();
+              socket.destroy();
+            }
             clients.clear();
             server.close(() => {
               if (process.platform !== "win32") {
@@ -341,6 +465,7 @@ export function connectBackgroundSession(opts) {
   return new Promise((resolve, reject) => {
     let settled = false;
     const socket = net.connect(pipePath);
+    const writer = createBoundedSocketWriter(socket);
     const timer = setTimeout(() => {
       if (!settled) {
         settled = true;
@@ -367,7 +492,7 @@ export function connectBackgroundSession(opts) {
             socket.unref?.();
             resolve({
               hello: message,
-              send: (msg) => writeMessage(socket, msg),
+              send: (msg) => writer.write(msg),
               close: () => {
                 // Best-effort graceful detach, then HARD destroy so the client
                 // handle is released synchronously. `socket.end()` alone leaves
@@ -380,10 +505,11 @@ export function connectBackgroundSession(opts) {
                 // the worker sees the socket close and finalizes the same as it
                 // would on an explicit detach.
                 try {
-                  writeMessage(socket, { type: "detach" });
+                  writer.write({ type: "detach" });
                 } catch {
                   /* peer already gone */
                 }
+                writer.close();
                 socket.destroy();
               },
             });
@@ -398,7 +524,7 @@ export function connectBackgroundSession(opts) {
       }),
     );
     socket.on("connect", () => {
-      writeMessage(socket, { type: "hello", token });
+      writer.write({ type: "hello", token });
     });
     socket.on("error", (error) => {
       if (!settled) {

package/src/lib/mcp-client.js

@@ -23,5 +23,7 @@ export {
   isMcpAuthenticationError,
   isMcpRpcError,
   isTransientMcpError,
+  SUPPORTED_MCP_PROTOCOL_VERSIONS,
+  assertSupportedMcpProtocolVersion,
   _deps,
 } from "../harness/mcp-client.js";

package/src/lib/mcp-headers-helper.js

@@ -17,8 +17,8 @@ const { buildExplicitHookShellInvocation } = hookShellCommand;
 export const MCP_HEADERS_HELPER_TIMEOUT_MS = 10_000;
 export const MCP_HEADERS_HELPER_MAX_OUTPUT_BYTES = 64 * 1024;
 const MAX_HELPER_COMMAND_BYTES = 32 * 1024;
-const MAX_HEADER_COUNT = 128;
-const MAX_HEADER_VALUE_BYTES = 16 * 1024;
+export const MCP_HEADERS_HELPER_MAX_HEADER_COUNT = 128;
+export const MCP_HEADERS_HELPER_MAX_HEADER_VALUE_BYTES = 16 * 1024;
 const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
 const TRANSPORT_OWNED_HEADERS = new Set([
   "accept",
@@ -37,6 +37,25 @@ const TRANSPORT_OWNED_HEADERS = new Set([
   "upgrade",
 ]);
 const PUBLIC_CONFIG_SCOPES = new Set(["local", "project", "user", "managed"]);
+const HELPER_ENVIRONMENT_ALLOWLIST = new Set([
+  "COMSPEC",
+  "HOME",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "NODE_EXTRA_CA_CERTS",
+  "PATH",
+  "PATHEXT",
+  "SSL_CERT_DIR",
+  "SSL_CERT_FILE",
+  "SYSTEMROOT",
+  "TEMP",
+  "TMP",
+  "TMPDIR",
+  "USERPROFILE",
+  "WINDIR",
+  "XDG_CONFIG_HOME",
+]);
 
 function helperError(code, message) {
   const error = new Error(message);
@@ -98,6 +117,28 @@ function normalizeHelperCommand(value) {
   return value;
 }
 
+export function sanitizeMcpHeadersHelperEnvironment(environment = process.env) {
+  if (!environment || typeof environment !== "object" || isProxy(environment)) {
+    throw helperError(
+      "CC_MCP_HEADERS_HELPER_ENV_INVALID",
+      "MCP headersHelper environment must be a non-Proxy object",
+    );
+  }
+  const sanitized = {};
+  for (const key of Object.keys(environment)) {
+    if (!HELPER_ENVIRONMENT_ALLOWLIST.has(key.toUpperCase())) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(environment, key);
+    if (!descriptor || !("value" in descriptor)) {
+      throw helperError(
+        "CC_MCP_HEADERS_HELPER_ENV_INVALID",
+        "MCP headersHelper environment values must be own data properties",
+      );
+    }
+    if (typeof descriptor.value === "string") sanitized[key] = descriptor.value;
+  }
+  return sanitized;
+}
+
 function canonicalHelperCwd(value, realpath = fs.realpathSync.native) {
   if (
     typeof value !== "string" ||
@@ -148,7 +189,7 @@ function normalizeHeaderMap(value, source) {
     );
   }
   const entries = Object.entries(value);
-  if (entries.length > MAX_HEADER_COUNT) {
+  if (entries.length > MCP_HEADERS_HELPER_MAX_HEADER_COUNT) {
     throw helperError(
       "CC_MCP_HEADERS_HELPER_OUTPUT_INVALID",
       `MCP ${source} headers exceed the allowed entry count`,
@@ -160,7 +201,8 @@ function normalizeHeaderMap(value, source) {
       !HEADER_NAME.test(name) ||
       typeof headerValue !== "string" ||
       hasInvalidHeaderValueCharacter(headerValue) ||
-      Buffer.byteLength(headerValue, "utf8") > MAX_HEADER_VALUE_BYTES ||
+      Buffer.byteLength(headerValue, "utf8") >
+        MCP_HEADERS_HELPER_MAX_HEADER_VALUE_BYTES ||
       (source === "dynamic" && TRANSPORT_OWNED_HEADERS.has(name.toLowerCase()))
     ) {
       throw helperError(
@@ -486,7 +528,7 @@ export function runMcpHeadersHelper(spec, deps = {}) {
     ),
   );
   const env = {
-    ...(spec?.env || process.env),
+    ...sanitizeMcpHeadersHelperEnvironment(spec?.env || process.env),
     CLAUDE_CODE_MCP_SERVER_NAME: String(spec?.serverName || ""),
     CLAUDE_CODE_MCP_SERVER_URL: String(spec?.serverUrl || ""),
     ...(spec?.pluginRoot

package/src/lib/mcp-oauth.js

@@ -52,6 +52,56 @@ export const _deps = {
   withStoreLock,
 };
 
+/**
+ * Resolve the exact IPv4-loopback redirect used by both the listener and the
+ * OAuth wire exchange. Pre-registered clients need byte-for-byte redirect URI
+ * stability, so explicit values are accepted only in canonical form.
+ */
+export function resolveOAuthLoopbackRedirect({
+  redirectUri,
+  host = "127.0.0.1",
+  port = 53682,
+  redirectPath = "/callback",
+} = {}) {
+  if (redirectUri != null && typeof redirectUri !== "string") {
+    throw new Error("OAuth redirectUri must be a string");
+  }
+  const candidate =
+    redirectUri == null ? `http://${host}:${port}${redirectPath}` : redirectUri;
+  let parsed;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new Error("OAuth redirectUri must be a valid loopback URL");
+  }
+  const parsedPort = Number(parsed.port);
+  const canonical = `http://127.0.0.1:${parsed.port}${parsed.pathname}`;
+  if (
+    parsed.protocol !== "http:" ||
+    parsed.hostname !== "127.0.0.1" ||
+    !parsed.port ||
+    !Number.isInteger(parsedPort) ||
+    parsedPort < 1 ||
+    parsedPort > 65535 ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash ||
+    !parsed.pathname.startsWith("/") ||
+    candidate !== canonical
+  ) {
+    throw new Error(
+      "OAuth redirectUri must be an exact canonical http://127.0.0.1:<port>/<path> URL",
+    );
+  }
+  return {
+    redirectUri: candidate,
+    host: "127.0.0.1",
+    port: parsedPort,
+    redirectPath: parsed.pathname,
+  };
+}
+
 /** Discovery/token requests retry ONCE after a transient error (CC 2.1.191). */
 const MCP_OAUTH_RETRY_BACKOFF_MS = 300;
 
@@ -794,23 +844,22 @@ export function waitForCallback({
  * Run the full interactive Authorization Code + PKCE flow and persist the token.
  *
  * @param {string} serverUrl
- * @param {object} [opts] { scope, clientId, port=53682, host, redirectPath,
- *                          timeout, writeOut }
+ * @param {object} [opts] { scope, clientId, redirectUri, port=53682, host,
+ *                          redirectPath, timeout, writeOut }
  * @returns {Promise<{server, access_token, ...}>}  the stored record
  */
 export async function authorizeInteractive(serverUrl, opts = {}) {
   const {
     scope,
     clientId: cfgClientId,
-    port = 53682,
-    host = "127.0.0.1",
-    redirectPath = "/callback",
     timeout = 300_000,
     writeOut = (s) => process.stdout.write(s),
   } = opts;
 
+  const { redirectUri, host, port, redirectPath } =
+    resolveOAuthLoopbackRedirect(opts);
+
   const metadata = await discoverAuthMetadata(serverUrl);
-  const redirectUri = `http://${host}:${port}${redirectPath}`;
 
   let clientId = cfgClientId;
   let clientSecret = null;