sparda-mcp 0.5.0 → 0.5.1

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "sparda-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",
   "bin": {
     "sparda": "./src/index.js"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:router": "node tests/router-selftest.cjs",
+    "test:all": "vitest run && node tests/router-selftest.cjs"
   },
   "files": [
     "src",
     "templates",
+    "!templates/*.bak",
     "README.md",
     "LICENSE"
   ],
@@ -36,7 +39,7 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
-    "express": "4.21.2",
+    "express": "^4.21.0",
     "vitest": "^3.2.6"
   }
 }

package/templates/express-router.txt

@@ -62,6 +62,20 @@ function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, m
 // observe-only: uncaughtExceptionMonitor never changes the host app's crash behavior
 process.on('uncaughtExceptionMonitor', (err__ANY_TYPE__) => spardaEvent('process', null, null, err && err.message ? err.message : err));
 
+// two-phase commit: a write/delete flagged require_human is NOT executed on /invoke.
+// It mints a single-use nonce + a preview contract; the host route is touched only after
+// an explicit /invoke/confirm replays the token. This is the gate the proof always described
+// but never enforced — the difference between a receipt and a contract.
+const SPARDA_PENDING__STATS_TYPE__ = {};
+const SPARDA_CONFIRM_TTL_MS = Number(process.env.SPARDA_CONFIRM_TTL_MS ?? 120000);
+function spardaNonce() {
+  return 'cfm_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+function spardaSweepPending() {
+  const now = Date.now();
+  for (const k of Object.keys(SPARDA_PENDING)) if (now > SPARDA_PENDING[k].expiresAt) delete SPARDA_PENDING[k];
+}
+
 function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
   const checks = {
     knownTool: spec !== undefined,
@@ -190,6 +204,53 @@ function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
   };
 }
 
+// captured once so the JSON-middleware placeholder appears a single time in the template
+// (the generator's replace is non-global).
+const SPARDA_JSON_MW__ANY_TYPE__ = __JSON_MW__;
+// SPARDA owns its own endpoints' body parsing AND the parse error: a malformed JSON body
+// returns JSON 400 locally instead of bubbling up to Express' HTML error page (stack leak).
+function SPARDA_JSON(req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) {
+  SPARDA_JSON_MW(req, res, (err__ANY_TYPE__) => {
+    if (err) { spardaEvent('router', null, 400, 'invalid JSON body'); return res.status(400).json({ error: 'invalid JSON body' }); }
+    next();
+  });
+}
+
+// the actual host-route call, shared by the allow-path and the confirm-path so a
+// confirmed write runs through the exact same execution + observation as a direct one.
+async function spardaExecute(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__, proof__ANY_TYPE__, t0__ANY_TYPE__, res__RES_TYPE__) {
+  try {
+    let url = spec.path.replace(/:(\w+)/g, (_, name) => encodeURIComponent(String(args[name])));
+    const query = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (k === 'body' || (spec.pathParams ?? []).includes(k) || v === undefined) continue;
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    if (query.length) url += `?${query.join('&')}`;
+
+    const init = { method: spec.method, headers: {} };
+    if (spec.method !== 'GET' && args.body !== undefined) {
+      init.headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(args.body);
+    }
+    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
+    const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
+    const text = await upstream.text();
+    let data; try { data = JSON.parse(text); } catch { data = text; }
+    spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (spec.method === 'GET' && upstream.status === 200) {
+      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
+      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
+    }
+    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
+    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
+  } catch (err__ANY_TYPE__) {
+    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
+    spardaEvent('invoke', tool, err.status ?? 502, err.message);
+    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
+  }
+}
+
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
@@ -208,9 +269,17 @@ spardaRouter.get('/events', (req__REQ_TYPE__, res__RES_TYPE__) => {
   res.json({ seq: SPARDA_SEQ, events: SPARDA_EVENTS.filter((e__ANY_TYPE__) => e.seq > since) });
 });
 
-spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE__) => {
-  const { tool, args = {} } = req.body ?? {};
+spardaRouter.post('/invoke', SPARDA_JSON, async (req__REQ_TYPE__, res__RES_TYPE__) => {
   const t0 = Date.now();
+  const reqBody = req.body ?? {};
+  const tool = reqBody.tool;
+  // type confusion guard: the old `args = {}` default only caught `undefined`. A `null`
+  // (or array/scalar) slipped through and crashed spardaProof on null[name] → Express HTML
+  // 500 with a full stack trace. We reject non-objects with clean JSON instead.
+  if (reqBody.args !== undefined && (reqBody.args === null || typeof reqBody.args !== 'object' || Array.isArray(reqBody.args))) {
+    return res.status(400).json({ error: 'args must be a JSON object', got: reqBody.args === null ? 'null' : Array.isArray(reqBody.args) ? 'array' : typeof reqBody.args });
+  }
+  const args = reqBody.args ?? {};
   const spec = SPARDA_TOOLS[tool];
 
   const proof = spardaProof(tool, spec, args);
@@ -249,41 +318,69 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
     return res.status(status).json({ error, spardingProof: proof });
   }
 
-  try {
-    let url = spec.path.replace(/:(\w+)/g, (_, name) => {
-      const v = args[name];
-      return encodeURIComponent(String(v));
+  if (proof.decision === 'require_human') {
+    // THE GATE THE PROOF ALWAYS LACKED.
+    // v0.5.0 had no branch here, so a require_human decision fell straight through to the
+    // host route below: the write happened, THEN the proof said "confirmation required".
+    // We stop here. The host route is not touched. We mint a single-use nonce and a preview
+    // the LLM reads in its tool-result, and only /invoke/confirm replays it.
+    spardaSweepPending();
+    const confirm = spardaNonce();
+    SPARDA_PENDING[confirm] = { tool, args, expiresAt: Date.now() + SPARDA_CONFIRM_TTL_MS, createdAt: new Date().toISOString() };
+    let siblingName = null;
+    for (const [n, t] of Object.entries(SPARDA_TOOLS)) { if (t.method === 'GET' && t.path === spec.path) { siblingName = n; break; } }
+    spardaEvent('confirm', tool, 202, `gated, awaiting confirmation (risk: ${proof.risk})`);
+    return res.status(202).json({
+      status: 'awaiting_confirmation',
+      confirm,
+      expiresInMs: SPARDA_CONFIRM_TTL_MS,
+      preview: {
+        tool,
+        method: spec.method,
+        path: spec.path,
+        willSendBody: spec.method !== 'GET' && args.body !== undefined,
+        reversibleHint: proof.checks.reversibleHint,
+        inspectFirst: siblingName ? { tool: siblingName, why: 'GET on the same path — read current state before committing this write' } : null,
+      },
+      // this string is what the LLM reads: the security decision IS the instruction.
+      instruction: `NOT EXECUTED. ${spec.method} ${spec.path} is gated by policy (${proof.reasons[0] || 'require_human'}); the host route was not touched.${siblingName ? ` First call "${siblingName}" to inspect current state, then` : ' To'} confirm via POST /invoke/confirm { "confirm": "${confirm}" }. Single-use, expires in ${Math.round(SPARDA_CONFIRM_TTL_MS / 1000)}s.`,
+      spardingProof: proof,
     });
-    const query = [];
-    for (const [k, v] of Object.entries(args)) {
-      if (k === 'body' || spec.pathParams.includes(k) || v === undefined) continue;
-      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
-    }
-    if (query.length) url += `?${query.join('&')}`;
+  }
 
-    const init = { method: spec.method, headers: {} };
-    if (spec.method !== 'GET' && args.body !== undefined) {
-      init.headers['content-type'] = 'application/json';
-      init.body = JSON.stringify(args.body);
-    }
-    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
-    const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
-    const text = await upstream.text();
-    let data; try { data = JSON.parse(text); } catch { data = text; }
-    spardaRecord(tool, upstream.status, Date.now() - t0);
-    if (spec.method === 'GET' && upstream.status === 200) {
-      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
-      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
-    }
-    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
-    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
-  } catch (err__ANY_TYPE__) {
-    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
-    spardaEvent('invoke', tool, err.status ?? 502, err.message);
-    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
+  // proof.decision === 'allow' — exercise the host route
+  return spardaExecute(tool, spec, args, proof, t0, res);
+});
+
+spardaRouter.post('/invoke/confirm', SPARDA_JSON, async (req__REQ_TYPE__, res__RES_TYPE__) => {
+  const t0 = Date.now();
+  const confirm = (req.body ?? {}).confirm;
+  if (typeof confirm !== 'string' || !confirm) {
+    return res.status(400).json({ error: 'missing confirm token (expected { confirm: "..." })' });
+  }
+  spardaSweepPending();
+  const pending = SPARDA_PENDING[confirm];
+  if (pending) delete SPARDA_PENDING[confirm]; // consume first — a token can never replay
+  if (!pending) {
+    return res.status(409).json({ error: 'unknown or expired confirmation token', hint: 're-issue the write via /invoke to mint a fresh token' });
+  }
+  if (Date.now() > pending.expiresAt) {
+    return res.status(409).json({ error: 'confirmation token expired', hint: 're-issue the write via /invoke' });
+  }
+  const spec = SPARDA_TOOLS[pending.tool];
+  // re-judge at commit time: the tool may have been quarantined or disabled since minting
+  const proof = spardaProof(pending.tool, spec, pending.args);
+  if (proof.decision === 'block') {
+    return res.status(403).json({ error: 'confirmation no longer valid', reason: proof.reasons[0] || 'blocked', spardingProof: proof });
   }
+  spardaEvent('confirm', pending.tool, 200, 'confirmed -> executing');
+  return spardaExecute(pending.tool, spec, pending.args, proof, t0, res);
 });
 
+// verb safety: any non-POST on the invoke endpoints returns JSON 405 (was bare Express HTML — bug #5)
+spardaRouter.all('/invoke', (req__REQ_TYPE__, res__RES_TYPE__) => res.status(405).json({ error: 'method not allowed', allow: 'POST' }));
+spardaRouter.all('/invoke/confirm', (req__REQ_TYPE__, res__RES_TYPE__) => res.status(405).json({ error: 'method not allowed', allow: 'POST' }));
+
 function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
   const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, clientErrors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
   // innate immunity: latency far beyond the learned baseline is an antigen
@@ -304,3 +401,17 @@ function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
     spardaEvent('immune', tool, 503, `quarantined after ${st.consecutive5xx} consecutive 5xx (cooldown ${SPARDA_QUARANTINE_MS}ms)`);
   }
 }
+
+// anything unmatched under the router → JSON 404, never bare Express HTML
+spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__) => res.status(404).json({ error: 'not found', path: req.path }));
+
+// error envelope (must stay last). body-parser throws SyntaxError on malformed JSON, and
+// anything thrown downstream used to fall through to Express' HTML error page — leaking the
+// internal stack trace. Every response stays JSON; the stack stays server-side, correlated
+// to /events by errorId.
+spardaRouter.use((err__ANY_TYPE__, req__REQ_TYPE__, res__RES_TYPE__, _next__NEXT_TYPE__) => {
+  const errorId = 'err_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+  spardaEvent('router', null, (err && err.status) || 500, `[${errorId}] ${err && err.message ? err.message : err}`);
+  const status = err && (err.type === 'entity.parse.failed' || err instanceof SyntaxError) ? 400 : (err && err.status) || 500;
+  res.status(status).json({ error: status === 400 ? 'invalid JSON body' : 'internal error', errorId });
+});