@yawlabs/caddy-mcp 2.1.0 → 2.2.0

package/bin/caddy-mcp.mjs

@@ -28,18 +28,46 @@
  * For an MCP host config, point straight at oam and skip this file:
  *   { "command": "oam", "args": ["run", "<abs>/dist/index.js"] }
  *
+ * THE `--permission` SANDBOX (oam 0.9.0+, opt-in)
+ * `CADDY_MCP_SANDBOX=1` runs the server under oam's permission model.
+ *
+ * The admin API endpoint is DERIVED from CADDY_ADMIN_URL (default
+ * http://127.0.0.1:2019), host and port both pinned -- grants are prefix-matched,
+ * so a bare host would also admit every other port on it. Filesystem AND
+ * child-process both stay denied: this server drives Caddy entirely over its
+ * admin HTTP API and never shells out to the `caddy` binary (the only
+ * execFileSync calls in the repo are in src/tests/).
+ *
+ * Opt-in, not default: a denied environment variable is ABSENT from process.env
+ * rather than throwing, so an under-granted CADDY_API_TOKEN reads as
+ * "unauthenticated". The env list is derived from the shipped bundle.
+ *
+ * MINIMUM OAM VERSION
+ * 0.9.0. Below it `child_process.execFile` ran its arguments through a SHELL,
+ * `exec` accepted `timeout` and ignored it, `spawnSync` truncated at
+ * `maxBuffer` while reporting success, and `stdio: 'inherit'`/`'ignore'` both
+ * behaved as `'pipe'`. This server spawns nothing, so the floor is
+ * enforced for consistency across @yawlabs/*-mcp rather than because this
+ * launcher was exposed.
+ * An older oam is not an error: the launcher falls back to Node and says so on
+ * stderr. Pinning the floor here is what makes that fallback automatic.
+ *
  * SELECTION
  *   CADDY_MCP_RUNTIME=oam    require oam; fail loudly if it is missing
  *   CADDY_MCP_RUNTIME=node   never use oam
  *   CADDY_MCP_RUNTIME=auto   prefer oam, silently fall back (default)
+ *   CADDY_MCP_SANDBOX=1      run oam under --permission (oam 0.9.0+)
  *   OAM_BIN=/path/to/oam     explicit binary, checked before any discovery
  */
 
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { constants, homedir } from "node:os";
 import { delimiter, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath } from "node:url";
+
+/** Oldest oam whose `child_process` matches Node. See MINIMUM OAM VERSION above. */
+const OAM_MIN = [0, 9, 0];
 
 // Two forms, deliberately. `import()` on Windows REJECTS a bare `C:\...` path
 // with ERR_UNSUPPORTED_ESM_URL_SCHEME (it reads `c:` as a protocol), so the
@@ -89,6 +117,72 @@ function findOam() {
   return null;
 }
 
+/**
+ * `oam --version` -> [major, minor, patch], or null when it cannot be read.
+ * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
+ */
+function oamVersion(cmd) {
+  try {
+    const out = execFileSync(cmd, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  } catch {
+    // Not executable, wrong arch, or deleted since the stat. Caller degrades.
+    return null;
+  }
+}
+
+/** True when `v` is at least `min`, comparing major/minor/patch in order. */
+function atLeast(v, min) {
+  if (!v) return false;
+  for (let i = 0; i < min.length; i++) {
+    if (v[i] > min[i]) return true;
+    if (v[i] < min[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * The `--permission` grant list, or [] when the sandbox is not requested.
+ *
+ * These are oam's PROCESS-level flags: they belong before the `run` subcommand,
+ * not after it. `oam run --permission file.js` is rejected outright, which is a
+ * good failure but only because it is loud -- ordering here is load-bearing.
+ *
+ * Net grants prefix-match `host` for fetch and `host:port` for sockets.
+ * A denied environment variable is ABSENT from process.env rather than throwing,
+ * so the env list below is derived from what the bundle actually reads; trimming
+ * it produces silent misbehaviour, not a clear denial.
+ */
+function sandboxFlags() {
+  if (process.env.CADDY_MCP_SANDBOX !== "1") return [];
+
+  // Derived, not hardcoded: the only endpoint this server may reach is the one
+  // it was configured to reach. Grants are prefix-matched against "host:port"
+  // for sockets, so host alone would also admit any other port on that host --
+  // pin both. A DSN we cannot parse falls back to a bare grant rather than a
+  // broken one, because a wrong narrow grant fails at connect time.
+  const dsn = process.env.CADDY_ADMIN_URL ?? "http://127.0.0.1:2019";
+  let netFlag = "--allow-net";
+  if (dsn) {
+    try {
+      const u = new URL(dsn);
+      if (u.hostname) netFlag = `--allow-net=${u.hostname}:${u.port || 2019}`;
+    } catch {
+      // Unparseable CADDY_ADMIN_URL: leave the grant open. The server will fail on
+      // its own connection error, which names the real problem.
+    }
+  }
+
+  const env = ["CADDY_ADMIN_URL","CADDY_API_TOKEN","CADDY_LOAD_TIMEOUT","CADDY_MAX_RETRIES","CADDY_TIMEOUT"];
+
+  const flags = ["--permission", netFlag, `--allow-env=${env.join(",")}`];
+  return flags;
+}
+
 /** Run the server in THIS process. The zero-overhead fallback. */
 async function runInProcess() {
   // A server may gate its bootstrap on being the process ENTRY POINT --
@@ -129,7 +223,7 @@ if (mode === "node") {
   } else {
     // `--` separates oam's own flags from the script's argv, so `caddy-mcp
     // --version` and any host-supplied flags survive the hop unchanged.
-    const child = spawn(oam, ["run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
+    const child = spawn(oam, [...sandboxFlags(), "run", SERVER_ENTRY, "--", ...process.argv.slice(2)], {
       // inherit keeps the SAME fds, so MCP's newline-delimited JSON framing on
       // stdin/stdout is untouched and the host's stdin-close still reaches the
       // server's shutdown path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/caddy-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "mcpName": "io.github.YawLabs/caddy-mcp",
   "description": "MCP server for managing Caddy web servers via the admin API",
   "license": "MIT",