loopctl-mcp-server 2.91.0 → 2.91.1

package/index.js

@@ -43,6 +43,7 @@ import {
   GENERATED_TOOL_PREFIX,
 } from "./lib/generated-tools.js";
 import { createHandoff } from "./lib/handoff.js";
+import { readPayloadFile } from "./lib/payload-path.js";
 
 // Single source of truth for the server version: the package.json this file
 // ships with (npm always includes package.json in the published tarball).
@@ -967,13 +968,7 @@ async function importStories({ project_id, payload, payload_path, merge }) {
 
 // Reads JSON payload from either an inline object or an absolute file path.
 // Returns the object on success, or an { error, body } shape on failure.
-//
-// Security: `payload_path` is read with the MCP process's filesystem
-// privileges. Because agents can set this argument via prompt injection,
-// we validate aggressively:
-//   * require absolute path
-//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
-//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+// The file path is validated in lib/payload-path.js (see its security notes).
 async function resolvePayload(inline, payloadPath) {
   if (inline && typeof inline === "object") return inline;
   if (!payloadPath) {
@@ -983,53 +978,7 @@ async function resolvePayload(inline, payloadPath) {
       body: "Must provide either `payload` (object) or `payload_path` (absolute JSON file path).",
     };
   }
-
-  const nodePath = await import("node:path");
-  if (!nodePath.isAbsolute(payloadPath)) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path must be absolute (got '${payloadPath}').`,
-    };
-  }
-
-  const blockedPrefixes = ["/proc/", "/dev/", "/sys/", "/proc", "/dev", "/sys"];
-  if (blockedPrefixes.some((p) => payloadPath === p.replace(/\/$/, "") || payloadPath.startsWith(p))) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`,
-    };
-  }
-
-  const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
-  const fs = await import("node:fs/promises");
-
-  try {
-    const stat = await fs.stat(payloadPath);
-    if (!stat.isFile()) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is not a regular file.`,
-      };
-    }
-    if (stat.size > MAX_PAYLOAD_BYTES) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is ${stat.size} bytes, exceeds max ${MAX_PAYLOAD_BYTES}.`,
-      };
-    }
-    const raw = await fs.readFile(payloadPath, "utf8");
-    return JSON.parse(raw);
-  } catch (err) {
-    return {
-      error: true,
-      status: 0,
-      body: `Could not read payload_path '${payloadPath}': ${err.message}`,
-    };
-  }
+  return readPayloadFile(payloadPath);
 }
 
 // --- Story Tools ---
@@ -3927,7 +3876,7 @@ const TOOLS = [
         payload_path: {
           type: "string",
           description:
-            "Absolute path to a JSON file with the import payload. Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
+            "Absolute path to a .json file holding the import payload (an object with an `epics` array). Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
         },
         merge: {
           type: "boolean",

package/lib/payload-path.js

@@ -0,0 +1,96 @@
+// Reads an import_stories payload from an absolute file path.
+//
+// Security: `payload_path` is read with the MCP process's filesystem privileges and an
+// agent can set it via prompt injection, so no file CONTENT is ever returned, and a file
+// that is not an import payload is never uploaded. The refusals still say which check
+// failed (missing, not a file, too large, not JSON, wrong shape) for a .json path; that
+// is metadata an agent needs to fix its own call, not content:
+//   * require an absolute path ending in .json, checked on the path AND on its realpath,
+//     so a symlink named x.json cannot point at /etc/passwd or /proc
+//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
+//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+//   * never echo a JSON.parse or fs error message: V8's SyntaxError quotes the file's
+//     content ("root:x:0:0"... is not valid JSON), so only err.code is reported
+//   * require the Epic 12 import shape (an object with an `epics` array) before returning,
+//     so a valid JSON file that is not a payload (a credentials file) is never POSTed
+//
+// Returns the parsed payload on success, or an { error, status, body } shape on failure.
+
+import nodePath from "node:path";
+import defaultFs from "node:fs/promises";
+
+export const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+const BLOCKED_ROOTS = ["/proc", "/dev", "/sys"];
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+function isBlocked(p) {
+  return BLOCKED_ROOTS.some((root) => p === root || p.startsWith(root + "/"));
+}
+
+function hasJsonExtension(p) {
+  return nodePath.extname(p).toLowerCase() === ".json";
+}
+
+export async function readPayloadFile(payloadPath, { fs = defaultFs } = {}) {
+  if (typeof payloadPath !== "string" || !nodePath.isAbsolute(payloadPath)) {
+    return refuse(`payload_path must be absolute (got '${payloadPath}').`);
+  }
+
+  if (isBlocked(nodePath.resolve(payloadPath))) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(payloadPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let realPath;
+  try {
+    realPath = await fs.realpath(payloadPath);
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  if (isBlocked(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let raw;
+  try {
+    const stat = await fs.stat(realPath);
+    if (!stat.isFile()) {
+      return refuse(`payload_path '${payloadPath}' is not a regular file.`);
+    }
+    if (stat.size > MAX_PAYLOAD_BYTES) {
+      return refuse(
+        `payload_path '${payloadPath}' exceeds max ${MAX_PAYLOAD_BYTES} bytes.`,
+      );
+    }
+    raw = await fs.readFile(realPath, "utf8");
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return refuse(`payload_path '${payloadPath}' is not valid JSON.`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Array.isArray(parsed.epics)) {
+    return refuse(
+      `payload_path '${payloadPath}' is not an import payload (expected an object with an "epics" array).`,
+    );
+  }
+
+  return parsed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.91.0",
+  "version": "2.91.1",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",