@geml/geml 1.1.1 → 1.4.2

package/codemap/mcp-server.mjs

@@ -1,143 +1,172 @@
-#!/usr/bin/env node
-// geml-code-graph MCP server — the thin consumption wrapper of DESIGN §8 (P2).
-// Three navigation tools over a built graph/ directory, each "give an
-// identifier, get readable text back" (the original proposal's 2.6):
-//   resolve_name   name -> candidate anchors (doc + block id)
-//   open_symbol    doc + id -> that symbol's block, verbatim
-//   get_backlinks  doc + id -> the symbol's backlink block (who calls it)
-//
-// Zero dependencies: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio
-// transport). Register e.g.:
-//   claude mcp add geml-code-graph -e GEML_GRAPH_DIR=/abs/path/to/graph \
-//     -- geml codemap mcp
-// The graph dir comes from GEML_GRAPH_DIR or a per-call `graph_dir` argument.
-import { readFileSync, existsSync } from "node:fs";
-import { join, resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline";
-
-// blockSpans from the reference parser (its CLI entry is guarded, so importing
-// is side-effect free). Falls back with a clear error if the parser isn't built.
-const parserPath = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
-if (!existsSync(parserPath)) {
-  console.error("geml-code-graph mcp: build the parser first (cd geml-parser && npm install && npm run build)");
-  process.exit(1);
-}
-const { blockSpans } = await import(`file://${parserPath.replace(/\\/g, "/")}`);
-const splitLines = (s) => s.split(/(?<=\n)/);
-
-const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
-
-const readBlock = (graphDir, doc, id) => {
-  const p = join(graphDir, doc);
-  if (!existsSync(p)) throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`);
-  const source = readFileSync(p, "utf8");
-  const span = blockSpans(source).get(id.replace(/^#/, ""));
-  if (!span) throw new Error(`no block with id \`${id}\` in ${doc}`);
-  return splitLines(source).slice(span.start, span.end).join("");
-};
-
-const TOOLS = [
-  {
-    name: "resolve_name",
-    description: "Find a function/class by name in the code graph. Returns candidate anchors with the document and block id to open. Multiple candidates = real ambiguity (overloads/same name) — inspect each, never assume.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        name: { type: "string", description: "Exact symbol name (function/class short name)" },
-        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
-      },
-      required: ["name"],
-    },
-    run: (args) => {
-      const lookupPath = join(graphDirOf(args), "_index/name-lookup.json");
-      if (!existsSync(lookupPath)) throw new Error(`no name-lookup at ${lookupPath} — build the graph first`);
-      const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
-      const hits = lookup[args.name];
-      if (!hits?.length) return `no symbol named \`${args.name}\` in the graph`;
-      return JSON.stringify(hits, null, 1);
-    },
-  },
-  {
-    name: "open_symbol",
-    description: "Open ONE symbol's block from the code graph (its callees as checked references, confidence annotations, called-by pointer). Equivalent to following a link. Get doc+id from resolve_name.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        doc: { type: "string", description: "Document path relative to the codemap dir, e.g. hashtable.c.geml" },
-        id: { type: "string", description: "Block id, e.g. hashtableFind (or #calls / #called-by for the edge tables)" },
-        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
-      },
-      required: ["doc", "id"],
-    },
-    run: (args) => readBlock(graphDirOf(args), args.doc, args.id),
-  },
-  {
-    name: "get_backlinks",
-    description: "Who calls this symbol: opens its backlink block (callers with file:line sites, each a followable reference). Absence means no RESOLVED callers — never proof of none.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        doc: { type: "string", description: "The symbol's document path, e.g. hashtable.c.geml" },
-        id: { type: "string", description: "The symbol's block id (e.g. hashtableFind); omit to get the whole #called-by table" },
-        graph_dir: { type: "string", description: "Codemap directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
-      },
-      required: ["doc"],
-    },
-    run: (args) => {
-      // codemap profile: in-edges live in the SAME document's #called-by table.
-      let table;
-      try {
-        table = readBlock(graphDirOf(args), args.doc, "called-by");
-      } catch {
-        return `no #called-by table in ${args.doc} — no resolved callers recorded (under heuristic extraction this is a blind spot, not proof of none)`;
-      }
-      if (!args.id) return table;
-      const id = args.id.replace(/^#/, "");
-      const lines = table.split("\n");
-      const hits = lines.filter((l, i) => i < 2 || new RegExp(`,\\s*#${id}\\s*,`).test(l));
-      return hits.length > 2 ? hits.join("\n")
-        : `no resolved callers of #${id} in ${args.doc} (blind spots live in the #unresolved table)`;
-    },
-  },
-];
-
-// ---- newline-delimited JSON-RPC 2.0 over stdio ----
-const reply = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
-const replyError = (id, code, message) =>
-  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
-
-createInterface({ input: process.stdin }).on("line", (line) => {
-  line = line.trim();
-  if (!line) return;
-  let msg;
-  try { msg = JSON.parse(line); } catch { return; }
-  const { id, method, params } = msg;
-  try {
-    if (method === "initialize") {
-      reply(id, {
-        protocolVersion: params?.protocolVersion ?? "2024-11-05",
-        capabilities: { tools: {} },
-        serverInfo: { name: "geml-code-graph", version: "0.2.0" },
-      });
-    } else if (method === "notifications/initialized" || method?.startsWith("notifications/")) {
-      // notifications get no response
-    } else if (method === "ping") {
-      reply(id, {});
-    } else if (method === "tools/list") {
-      reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
-    } else if (method === "tools/call") {
-      const tool = TOOLS.find((t) => t.name === params?.name);
-      if (!tool) { replyError(id, -32602, `unknown tool: ${params?.name}`); return; }
-      try {
-        reply(id, { content: [{ type: "text", text: tool.run(params?.arguments ?? {}) }] });
-      } catch (e) {
-        reply(id, { content: [{ type: "text", text: `error: ${e.message}` }], isError: true });
-      }
-    } else if (id !== undefined) {
-      replyError(id, -32601, `method not found: ${method}`);
-    }
-  } catch (e) {
-    if (id !== undefined) replyError(id, -32603, String(e?.message ?? e));
-  }
-});
+#!/usr/bin/env node
+// geml-code-graph MCP server — the thin consumption wrapper of DESIGN §8 (P2).
+// Three navigation tools over a built graph/ directory, each "give an
+// identifier, get readable text back" (the original proposal's 2.6):
+//   resolve_name   name -> candidate anchors (doc + block id)
+//   open_symbol    doc + id -> that symbol's block, verbatim
+//   get_backlinks  doc + id -> the symbol's backlink block (who calls it)
+//
+// Zero dependencies: newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio
+// transport). Register e.g.:
+//   claude mcp add geml-code-graph -e GEML_GRAPH_DIR=/abs/path/to/graph \
+//     -- geml codemap mcp
+// The graph dir comes from GEML_GRAPH_DIR or a per-call `graph_dir` argument.
+//
+// The dispatch is exported (and the stdio wiring below is main-module guarded)
+// so the test suite can drive it in-process; the CLI dispatcher always runs
+// this file as a child's MAIN module, where nothing changes.
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { join, resolve, dirname, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createInterface } from "node:readline";
+
+// blockSpans from the reference parser (its CLI entry is guarded, so importing
+// is side-effect free). Falls back with a clear error if the parser isn't built.
+const parserPath = resolve(dirname(fileURLToPath(import.meta.url)), "../dist/geml.js");
+if (!existsSync(parserPath)) {
+  console.error("geml-code-graph mcp: build the parser first (cd geml-parser && npm install && npm run build)");
+  process.exit(1);
+}
+const { blockSpans } = await import(`file://${parserPath.replace(/\\/g, "/")}`);
+const splitLines = (s) => s.split(/(?<=\n)/);
+
+export const graphDirOf = (args) => resolve(args?.graph_dir ?? process.env.GEML_GRAPH_DIR ?? ".geml-code-graph");
+
+export const readBlock = (graphDir, doc, id) => {
+  const p = join(graphDir, doc);
+  // Confine `doc` to the graph dir. `doc` is client-supplied, so a value like
+  // ../../../etc/hosts joins OUT of the dir; realpathSync canonicalizes both
+  // sides (also defeating symlink escapes and normalizing Windows casing) and
+  // we verify the real doc path stays within the real graph dir. A missing
+  // file makes realpathSync throw — that is the normal "no such document"
+  // miss. (graph_dir itself is intentionally client-chosen — the server is
+  // pointed at a graph — so only the doc path is confined, to that dir.)
+  let realDir;
+  try { realDir = realpathSync(graphDir); } catch { realDir = resolve(graphDir); }
+  let realP;
+  try { realP = realpathSync(p); } catch { throw new Error(`no such document: ${doc} (graph dir: ${graphDir})`); }
+  if (realP !== realDir && !realP.startsWith(realDir + sep)) {
+    throw new Error(`document escapes the graph dir: ${doc} (graph dir: ${graphDir})`);
+  }
+  const source = readFileSync(realP, "utf8");
+  const span = blockSpans(source).get(id.replace(/^#/, ""));
+  if (!span) throw new Error(`no block with id \`${id}\` in ${doc}`);
+  return splitLines(source).slice(span.start, span.end).join("");
+};
+
+export const TOOLS = [
+  {
+    name: "resolve_name",
+    description: "Find a function/class by name in the code graph. Returns candidate anchors with the document and block id to open. Multiple candidates = real ambiguity (overloads/same name) — inspect each, never assume.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Exact symbol name (function/class short name)" },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["name"],
+    },
+    run: (args) => {
+      const lookupPath = join(graphDirOf(args), "_index/name-lookup.json");
+      if (!existsSync(lookupPath)) throw new Error(`no name-lookup at ${lookupPath} — build the graph first`);
+      const lookup = JSON.parse(readFileSync(lookupPath, "utf8"));
+      const hits = lookup[args.name];
+      if (!hits?.length) return `no symbol named \`${args.name}\` in the graph`;
+      return JSON.stringify(hits, null, 1);
+    },
+  },
+  {
+    name: "open_symbol",
+    description: "Open ONE symbol's block from the code graph (its callees as checked references, confidence annotations, called-by pointer). Equivalent to following a link. Get doc+id from resolve_name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        doc: { type: "string", description: "Document path relative to the codemap dir, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "Block id, e.g. hashtableFind (or #calls / #called-by for the edge tables)" },
+        graph_dir: { type: "string", description: "Graph directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["doc", "id"],
+    },
+    run: (args) => readBlock(graphDirOf(args), args.doc, args.id),
+  },
+  {
+    name: "get_backlinks",
+    description: "Who calls this symbol: opens its backlink block (callers with file:line sites, each a followable reference). Absence means no RESOLVED callers — never proof of none.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        doc: { type: "string", description: "The symbol's document path, e.g. hashtable.c.geml" },
+        id: { type: "string", description: "The symbol's block id (e.g. hashtableFind); omit to get the whole #called-by table" },
+        graph_dir: { type: "string", description: "Codemap directory (default: $GEML_GRAPH_DIR or ./.geml-code-graph)" },
+      },
+      required: ["doc"],
+    },
+    run: (args) => {
+      // codemap profile: in-edges live in the SAME document's #called-by table.
+      let table;
+      try {
+        table = readBlock(graphDirOf(args), args.doc, "called-by");
+      } catch {
+        return `no #called-by table in ${args.doc} — no resolved callers recorded (under heuristic extraction this is a blind spot, not proof of none)`;
+      }
+      if (!args.id) return table;
+      const id = args.id.replace(/^#/, "");
+      // `id` is client-supplied and goes straight into a RegExp: escape every
+      // regex metacharacter so it matches LITERALLY (an id like `.*` or a
+      // catastrophic-backtracking pattern can neither widen the match nor cause
+      // ReDoS — the pattern is a fixed string wrapped in `,\s*#…\s*,`).
+      const escId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const re = new RegExp(`,\\s*#${escId}\\s*,`);
+      const lines = table.split("\n");
+      const hits = lines.filter((l, i) => i < 2 || re.test(l));
+      return hits.length > 2 ? hits.join("\n")
+        : `no resolved callers of #${id} in ${args.doc} (blind spots live in the #unresolved table)`;
+    },
+  },
+];
+
+// ---- newline-delimited JSON-RPC 2.0 over stdio ----
+// One frame in, zero or one frame out via `write` (stdout in production).
+export function handleLine(line, write = (s) => process.stdout.write(s)) {
+  const reply = (id, result) => write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n");
+  const replyError = (id, code, message) =>
+    write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } }) + "\n");
+  line = line.trim();
+  if (!line) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  const { id, method, params } = msg;
+  try {
+    if (method === "initialize") {
+      reply(id, {
+        protocolVersion: params?.protocolVersion ?? "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "geml-code-graph", version: "0.2.0" },
+      });
+    } else if (method === "notifications/initialized" || method?.startsWith("notifications/")) {
+      // notifications get no response
+    } else if (method === "ping") {
+      reply(id, {});
+    } else if (method === "tools/list") {
+      reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    } else if (method === "tools/call") {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) { replyError(id, -32602, `unknown tool: ${params?.name}`); return; }
+      try {
+        reply(id, { content: [{ type: "text", text: tool.run(params?.arguments ?? {}) }] });
+      } catch (e) {
+        reply(id, { content: [{ type: "text", text: `error: ${e.message}` }], isError: true });
+      }
+    } else if (id !== undefined) {
+      replyError(id, -32601, `method not found: ${method}`);
+    }
+  } catch (e) {
+    if (id !== undefined) replyError(id, -32603, String(e?.message ?? e));
+  }
+}
+
+// Auto-run only as a MAIN module (the CLI dispatcher spawns this file as a
+// child's entry script) — an in-process `import` stays inert.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  createInterface({ input: process.stdin }).on("line", (line) => handleLine(line));
+}

package/codemap/recipe-trust.mjs

@@ -0,0 +1,103 @@
+// Shared TRUST GATE for codemap recipes (security fix C2 — RCE).
+//
+// A codemap's _index/refresh.json is COMMITTED DATA whose `steps[]` are run
+// through a shell by `geml codemap refresh` (spawnSync(step,{shell:true})).
+// Cloning a hostile repo and running `geml codemap refresh` — which the
+// geml-code-graph skill, `serve --watch`, and a PostToolUse hook all trigger —
+// would otherwise execute arbitrary commands. The old "up-to-date" guard is
+// bypassable and does not gate execution.
+//
+// The fix content-addresses each recipe (a stable fingerprint of its steps)
+// and records which fingerprints the user has EXPLICITLY approved in a store
+// kept OUTSIDE any repo (so a repo can never pre-approve itself). refresh
+// refuses to execute a recipe whose fingerprint is not in the store; build
+// auto-trusts the recipe it just authored (the user ran it locally).
+//
+// Trust gates WHO may run a recipe. Security fix R2-1 additionally changed HOW
+// steps are stored: a step is now a STRUCTURED object { cwd?, env?, argv:[...] }
+// so attacker-controllable paths are never interpolated into a shell string at
+// rest, and refresh executes them without an attacker-influenced command line.
+// The fingerprint below canonicalizes that structured form.
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+
+export const RECIPE_VERSION = 1;   // on-disk step schema; bump ONLY on a real format change
+
+// Canonicalize ONE recipe step for fingerprinting. Since security fix R2-1 a
+// step is a STRUCTURED object { cwd?, env?, argv:[...] } (no shell string is
+// ever stored). We emit a FIXED key order (cwd, env, argv), env keys SORTED so
+// the fingerprint is independent of how the env map was built, and every value
+// coerced to a string. Anything that is NOT a structured step (a legacy
+// pre-R2-1 shell string, or a malformed entry) coerces to its String() form, so
+// pre-existing string recipes keep the EXACT fingerprint they had before this
+// change (backward compatible), while structured recipes get a stable identity.
+function canonicalStep(step) {
+  if (step && typeof step === "object" && Array.isArray(step.argv)) {
+    const out = {};
+    if (step.cwd != null) out.cwd = String(step.cwd);
+    if (step.env && typeof step.env === "object") {
+      const env = {};
+      for (const k of Object.keys(step.env).sort()) env[k] = String(step.env[k]);
+      out.env = env;
+    }
+    out.argv = step.argv.map((a) => String(a));
+    return out;
+  }
+  return String(step);
+}
+
+// Fingerprint = sha256 over a canonical JSON of {root, steps}. build (when it
+// records refresh.json) and refresh (when it is about to run it) both call
+// this on the same parsed recipe object, so they agree exactly. `root` is
+// included because it is the base dir every step runs under — the same steps
+// under a different root are a different execution and deserve a different
+// identity. Deterministic: fixed key order, canonicalized steps, no timestamps.
+export function recipeFingerprint(recipe) {
+  const steps = Array.isArray(recipe?.steps) ? recipe.steps.map(canonicalStep) : [];
+  const root = recipe?.root == null ? "" : String(recipe.root);
+  const canonical = JSON.stringify({ root, steps });
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+
+// Where the trust store lives — NEVER inside a repo. GEML_TRUST_STORE is an
+// explicit override (test isolation / unusual homes). Otherwise it sits under
+// the XDG config dir, falling back to ~/.config/geml, which is a sane
+// cross-platform home (on Windows homedir() is C:\Users\<name>).
+export function trustStorePath() {
+  if (process.env.GEML_TRUST_STORE) return process.env.GEML_TRUST_STORE;
+  const cfgHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(cfgHome, "geml", "trusted-recipes.json");
+}
+
+// Read the store DEFENSIVELY: a missing, unreadable, or malformed store means
+// "nothing is trusted". A broken store must never silently trust a recipe.
+export function readTrustStore() {
+  try {
+    const obj = JSON.parse(readFileSync(trustStorePath(), "utf8"));
+    if (obj && typeof obj === "object" && obj.recipes && typeof obj.recipes === "object") {
+      return { version: obj.version || 1, recipes: obj.recipes };
+    }
+  } catch { /* missing / unreadable / malformed: treat as empty */ }
+  return { version: 1, recipes: {} };
+}
+
+// True only when this exact recipe fingerprint has been approved.
+export function isRecipeTrusted(fingerprint) {
+  const store = readTrustStore();
+  return Object.prototype.hasOwnProperty.call(store.recipes, fingerprint);
+}
+
+// Record a fingerprint as trusted, MERGING into any existing store (never
+// clobbering other approvals). Creates parent dirs. Returns the store path.
+// THROWS on write failure: a caller that meant to trust must learn it did NOT,
+// rather than proceed on the false belief that the recipe is now safe.
+export function trustRecipe(fingerprint, graphDir) {
+  const store = readTrustStore();
+  store.recipes[fingerprint] = { graphDir: graphDir ? String(graphDir) : undefined, addedAt: Date.now() };
+  const p = trustStorePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(store, null, 2) + "\n");
+  return p;
+}