@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/src/core/path-safety.js

@@ -1,141 +1,141 @@
-// SEC-14-03: validate that a projectRoot supplied via MCP message points to a
-// real git workspace before any handler that writes to disk dispatches into
-// sync.js / reverse-sync.js.
-//
-// The helper is intentionally pure (no throw): MCP handlers package errors as
-// `{ error: <string> }` envelopes (see src/mcp-server/index.js handleSync,
-// handleGates, handleForensics — all use the same shape). Returning a discriminated
-// `{ ok, ...}` lets each caller decide between an envelope error or a CLI exit
-// without try/catch boilerplate.
-//
-// Why a directory-existence + walk-up `.git/` check (and not, say, spawning
-// `git rev-parse --show-toplevel`):
-//   - Heuristic is good enough for our threat model. The attacker we are blocking
-//     is "MCP message says projectRoot=\\evil-host\share or %APPDATA%". Both fail
-//     the existence-or-`.git`-ancestor test trivially.
-//   - No child_process means no dependency on `git` being on PATH at runtime, no
-//     spawn latency on the hot path of every tool call, and no risk of the spawned
-//     git itself reading config from an attacker-influenced cwd.
-//   - The walk-up loop is bounded — Windows roots terminate at `D:\`, POSIX at
-//     `/`, and `path.dirname(cur) === cur` is the universal fixed point. Typical
-//     workspaces have <8 levels to a `.git/`, so a stat per level is fine.
-//
-// CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same trust
-// model as Phase 79.01's gates.run guard).
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-
-// All rejection reasons embed the literal "git workspace" — MCP clients (and
-// our own regression tests) match on that single sentinel regardless of which
-// check fired. Keeping the wording uniform means callers don't have to maintain
-// six regexes; one suffices.
-const SENTINEL = 'MCP sync requires projectRoot to be a git workspace';
-
-/**
- * SEC-14-03: validate that a `projectRoot` supplied via MCP message points to
- * a real git workspace before any handler dispatches into sync.js / reverse-sync.js.
- *
- * Pure function — never throws. Returns a discriminated union so MCP handlers
- * can wrap rejections in `{ error }` envelopes without try/catch boilerplate
- * (matches handleSync/handleGates/handleForensics in src/mcp-server/index.js).
- *
- * Validation chain (each step short-circuits on rejection):
- *   1. `projectRoot` is non-empty string (rejects nullish, empty, non-string types).
- *   2. `path.resolve()` collapses `..` segments and produces an absolute path.
- *   3. The resolved path exists and is a directory (UNC failures bubble up here).
- *   4. A `.git` entry exists somewhere in the ancestor chain (file or directory —
- *      `git worktree` uses a file). Walk-up bounded by `path.dirname()` fixed point.
- *
- * The CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same
- * trust model as Phase 79.01's gates.run guard). Only MCP-message-sourced paths
- * need this check.
- *
- * Rejection reasons all embed the literal `"git workspace"` string — public
- * contract relied on by test/unit/mcp-projectroot-guard.test.js and downstream
- * MCP clients. Don't rephrase without coordinating callers.
- *
- * @param {unknown} projectRoot - the candidate path supplied by an MCP client.
- *   Expected to be an absolute filesystem path; any other shape is rejected.
- * @returns {Promise<{ok: true, resolvedPath: string} | {ok: false, reason: string}>}
- *   On success, `resolvedPath` is the path-resolved absolute form of `projectRoot`
- *   (callers should use it instead of the raw input). On failure, `reason` is a
- *   human-readable string suitable for MCP `{error}` envelopes.
- */
-export async function validateProjectRoot(projectRoot) {
-  // Reject empty / nullish up-front. We require an explicit projectRoot from
-  // MCP messages — falling back to `process.cwd()` of the MCP server would let
-  // an attacker probe wherever the server happened to be launched.
-  if (projectRoot === undefined || projectRoot === null || projectRoot === '') {
-    return {
-      ok: false,
-      reason: SENTINEL + '; got <empty> (pass an absolute path to a git workspace)',
-    };
-  }
-  if (typeof projectRoot !== 'string') {
-    return {
-      ok: false,
-      reason: SENTINEL + '; got non-string projectRoot of type ' + typeof projectRoot,
-    };
-  }
-
-  // path.resolve normalises separators and collapses `..` segments so a later
-  // attacker payload like `C:\Users\\..\evil` is reduced before the existence
-  // check happens. resolve() is also a no-op on already-absolute paths.
-  const resolved = path.resolve(projectRoot);
-
-  // Defensive — path.resolve should always return absolute, but if a future
-  // Node version changes that we still want to reject.
-  if (!path.isAbsolute(resolved)) {
-    return {
-      ok: false,
-      reason: SENTINEL + '; projectRoot did not resolve to an absolute path: ' + projectRoot,
-    };
-  }
-
-  // The stat doubles as an existence + reachability check. UNC paths to
-  // unreachable hosts (`\\evil-host\share`) reject here on Windows with ENOENT
-  // / EHOSTUNREACH within milliseconds; Node treats both as a rejection so we
-  // never proceed to write a single byte.
-  let stat;
-  try {
-    stat = await fs.stat(resolved);
-  } catch {
-    return {
-      ok: false,
-      reason: SENTINEL + '; projectRoot does not exist or is unreachable: ' + resolved,
-    };
-  }
-
-  if (!stat.isDirectory()) {
-    return {
-      ok: false,
-      reason: SENTINEL + '; projectRoot must be a directory: ' + resolved,
-    };
-  }
-
-  // Walk up looking for `.git` (file or directory — `git worktree` uses a file).
-  // Bounded by the dirname fixed-point check so this terminates on every OS.
-  let cur = resolved;
-  // eslint-disable-next-line no-constant-condition
-  while (true) {
-    try {
-      await fs.stat(path.join(cur, '.git'));
-      return { ok: true, resolvedPath: resolved };
-    } catch {
-      // not here — keep walking up
-    }
-    const parent = path.dirname(cur);
-    if (parent === cur) break;
-    cur = parent;
-  }
-
-  // No .git/ found anywhere in the chain — the canonical reject. The literal
-  // "git workspace" string is part of the public contract — tests
-  // (test/unit/mcp-projectroot-guard.test.js) and downstream MCP clients match
-  // on it. Don't rephrase without coordinating callers.
-  return {
-    ok: false,
-    reason: SENTINEL + '; got ' + projectRoot,
-  };
-}
+// SEC-14-03: validate that a projectRoot supplied via MCP message points to a
+// real git workspace before any handler that writes to disk dispatches into
+// sync.js / reverse-sync.js.
+//
+// The helper is intentionally pure (no throw): MCP handlers package errors as
+// `{ error: <string> }` envelopes (see src/mcp-server/index.js handleSync,
+// handleGates, handleForensics — all use the same shape). Returning a discriminated
+// `{ ok, ...}` lets each caller decide between an envelope error or a CLI exit
+// without try/catch boilerplate.
+//
+// Why a directory-existence + walk-up `.git/` check (and not, say, spawning
+// `git rev-parse --show-toplevel`):
+//   - Heuristic is good enough for our threat model. The attacker we are blocking
+//     is "MCP message says projectRoot=\\evil-host\share or %APPDATA%". Both fail
+//     the existence-or-`.git`-ancestor test trivially.
+//   - No child_process means no dependency on `git` being on PATH at runtime, no
+//     spawn latency on the hot path of every tool call, and no risk of the spawned
+//     git itself reading config from an attacker-influenced cwd.
+//   - The walk-up loop is bounded — Windows roots terminate at `D:\`, POSIX at
+//     `/`, and `path.dirname(cur) === cur` is the universal fixed point. Typical
+//     workspaces have <8 levels to a `.git/`, so a stat per level is fine.
+//
+// CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same trust
+// model as Phase 79.01's gates.run guard).
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+// All rejection reasons embed the literal "git workspace" — MCP clients (and
+// our own regression tests) match on that single sentinel regardless of which
+// check fired. Keeping the wording uniform means callers don't have to maintain
+// six regexes; one suffices.
+const SENTINEL = 'MCP sync requires projectRoot to be a git workspace';
+
+/**
+ * SEC-14-03: validate that a `projectRoot` supplied via MCP message points to
+ * a real git workspace before any handler dispatches into sync.js / reverse-sync.js.
+ *
+ * Pure function — never throws. Returns a discriminated union so MCP handlers
+ * can wrap rejections in `{ error }` envelopes without try/catch boilerplate
+ * (matches handleSync/handleGates/handleForensics in src/mcp-server/index.js).
+ *
+ * Validation chain (each step short-circuits on rejection):
+ *   1. `projectRoot` is non-empty string (rejects nullish, empty, non-string types).
+ *   2. `path.resolve()` collapses `..` segments and produces an absolute path.
+ *   3. The resolved path exists and is a directory (UNC failures bubble up here).
+ *   4. A `.git` entry exists somewhere in the ancestor chain (file or directory —
+ *      `git worktree` uses a file). Walk-up bounded by `path.dirname()` fixed point.
+ *
+ * The CLI does NOT call this — `bin/cli.js` trusts whoever invoked it (same
+ * trust model as Phase 79.01's gates.run guard). Only MCP-message-sourced paths
+ * need this check.
+ *
+ * Rejection reasons all embed the literal `"git workspace"` string — public
+ * contract relied on by test/unit/mcp-projectroot-guard.test.js and downstream
+ * MCP clients. Don't rephrase without coordinating callers.
+ *
+ * @param {unknown} projectRoot - the candidate path supplied by an MCP client.
+ *   Expected to be an absolute filesystem path; any other shape is rejected.
+ * @returns {Promise<{ok: true, resolvedPath: string} | {ok: false, reason: string}>}
+ *   On success, `resolvedPath` is the path-resolved absolute form of `projectRoot`
+ *   (callers should use it instead of the raw input). On failure, `reason` is a
+ *   human-readable string suitable for MCP `{error}` envelopes.
+ */
+export async function validateProjectRoot(projectRoot) {
+  // Reject empty / nullish up-front. We require an explicit projectRoot from
+  // MCP messages — falling back to `process.cwd()` of the MCP server would let
+  // an attacker probe wherever the server happened to be launched.
+  if (projectRoot === undefined || projectRoot === null || projectRoot === '') {
+    return {
+      ok: false,
+      reason: SENTINEL + '; got <empty> (pass an absolute path to a git workspace)',
+    };
+  }
+  if (typeof projectRoot !== 'string') {
+    return {
+      ok: false,
+      reason: SENTINEL + '; got non-string projectRoot of type ' + typeof projectRoot,
+    };
+  }
+
+  // path.resolve normalises separators and collapses `..` segments so a later
+  // attacker payload like `C:\Users\\..\evil` is reduced before the existence
+  // check happens. resolve() is also a no-op on already-absolute paths.
+  const resolved = path.resolve(projectRoot);
+
+  // Defensive — path.resolve should always return absolute, but if a future
+  // Node version changes that we still want to reject.
+  if (!path.isAbsolute(resolved)) {
+    return {
+      ok: false,
+      reason: SENTINEL + '; projectRoot did not resolve to an absolute path: ' + projectRoot,
+    };
+  }
+
+  // The stat doubles as an existence + reachability check. UNC paths to
+  // unreachable hosts (`\\evil-host\share`) reject here on Windows with ENOENT
+  // / EHOSTUNREACH within milliseconds; Node treats both as a rejection so we
+  // never proceed to write a single byte.
+  let stat;
+  try {
+    stat = await fs.stat(resolved);
+  } catch {
+    return {
+      ok: false,
+      reason: SENTINEL + '; projectRoot does not exist or is unreachable: ' + resolved,
+    };
+  }
+
+  if (!stat.isDirectory()) {
+    return {
+      ok: false,
+      reason: SENTINEL + '; projectRoot must be a directory: ' + resolved,
+    };
+  }
+
+  // Walk up looking for `.git` (file or directory — `git worktree` uses a file).
+  // Bounded by the dirname fixed-point check so this terminates on every OS.
+  let cur = resolved;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      await fs.stat(path.join(cur, '.git'));
+      return { ok: true, resolvedPath: resolved };
+    } catch {
+      // not here — keep walking up
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+
+  // No .git/ found anywhere in the chain — the canonical reject. The literal
+  // "git workspace" string is part of the public contract — tests
+  // (test/unit/mcp-projectroot-guard.test.js) and downstream MCP clients match
+  // on it. Don't rephrase without coordinating callers.
+  return {
+    ok: false,
+    reason: SENTINEL + '; got ' + projectRoot,
+  };
+}

package/src/core/replays.js

@@ -1,120 +1,120 @@
-// Replays — capture Task() payloads so an agent can be re-run with the same
-// inputs but an updated prompt. Tight feedback loop for iterating on agent
-// definitions without re-running the whole workflow.
-//
-// Storage: .planning/replays/{phase}-{plan?}-{timestamp}-{agent}.json
-//
-// Payload shape:
-//   {
-//     id, agent, phase?, plan?, timestamp,
-//     subagent_type, model, isolation,
-//     prompt, files_to_read, agent_skills,
-//     outcome?: { status, notes }
-//   }
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { redactSecrets } from './error-redaction.js';
-
-const REPLAY_DIR_REL = path.join('.planning', 'replays');
-
-// SEC-13-02: replayId path traversal guard. The MCP forensics tool exposes
-// load-replay/annotate-replay/record-replay actions; without sanitization,
-// a malicious replayId like '../../../etc/passwd' would read/write files
-// outside .planning/replays/.
-//
-// Strategy: allowlist regex (no slashes, no '..', no NUL) + post-resolve assertion
-// that the final path stays inside REPLAY_DIR_REL.
-const REPLAY_ID_RE = /^[A-Za-z0-9_.-]+$/;
-
-function validateReplayId(id) {
-  if (typeof id !== 'string' || !id) {
-    throw new Error('invalid replay id: must be a non-empty string');
-  }
-  if (id === '.' || id === '..' || id.includes('..')) {
-    throw new Error('invalid replay id: traversal sequences not allowed');
-  }
-  if (!REPLAY_ID_RE.test(id)) {
-    throw new Error(`invalid replay id: only [A-Za-z0-9_.-] allowed, got ${JSON.stringify(id)}`);
-  }
-  return id;
-}
-
-function assertPathInside(filePath, baseDir) {
-  const resolved = path.resolve(filePath);
-  const base = path.resolve(baseDir);
-  // Ensure resolved is base or a child of base (handle trailing-sep edge case).
-  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
-    throw new Error('invalid replay id: resolved path escapes replay directory');
-  }
-  return resolved;
-}
-
-export async function recordReplay(payload, opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const dir = path.join(projectRoot, REPLAY_DIR_REL);
-  await fs.mkdir(dir, { recursive: true });
-
-  const ts   = new Date().toISOString().replace(/[:.]/g, '-');
-  // SEC-13-02: validate each slug component independently before concat
-  const slugParts = [payload.phase, payload.plan, payload.agent].filter(Boolean);
-  for (const part of slugParts) {
-    validateReplayId(String(part));
-  }
-  const slug = slugParts.join('-') || 'unknown';
-  const id   = `${ts}-${slug}`;
-  // Re-validate the full id (defense in depth — ts is well-formed but cheap to check)
-  validateReplayId(id);
-  const file = path.join(dir, `${id}.json`);
-  assertPathInside(file, dir);
-
-  const record = { id, recorded_at: new Date().toISOString(), ...payload };
-  // SEC-14-06: scrub the serialized form before writing. We redact AFTER
-  // JSON.stringify (rather than deep-mapping the payload tree) so the regex
-  // walks the entire structure including nested args/headers/env, and so
-  // the in-memory `record` returned to the caller stays unmutated. Only the
-  // on-disk artifact is scrubbed; readers of the file via loadReplay see
-  // the redacted form, which is the desired outcome — secrets must not be
-  // re-loaded into memory either.
-  const json = redactSecrets(JSON.stringify(record, null, 2));
-  await fs.writeFile(file, json, 'utf8');
-  return { id, file, record };
-}
-
-export async function listReplays(opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const dir = path.join(projectRoot, REPLAY_DIR_REL);
-  let entries;
-  try { entries = await fs.readdir(dir); } catch { return []; }
-  const items = [];
-  for (const e of entries) {
-    if (!e.endsWith('.json')) continue;
-    try {
-      const r = JSON.parse(await fs.readFile(path.join(dir, e), 'utf8'));
-      items.push({ id: r.id, agent: r.agent, phase: r.phase, plan: r.plan, recorded_at: r.recorded_at });
-    } catch {}
-  }
-  return items.sort((a, b) => (b.recorded_at ?? '').localeCompare(a.recorded_at ?? ''));
-}
-
-export async function loadReplay(id, opts = {}) {
-  validateReplayId(id);
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const dir = path.join(projectRoot, REPLAY_DIR_REL);
-  const file = path.join(dir, `${id}.json`);
-  assertPathInside(file, dir);
-  const raw  = await fs.readFile(file, 'utf8');
-  return JSON.parse(raw);
-}
-
-export async function annotateReplay(id, outcome, opts = {}) {
-  validateReplayId(id);
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const dir = path.join(projectRoot, REPLAY_DIR_REL);
-  const file = path.join(dir, `${id}.json`);
-  assertPathInside(file, dir);
-  const r = JSON.parse(await fs.readFile(file, 'utf8'));
-  r.outcome = { ...(r.outcome ?? {}), ...outcome, annotated_at: new Date().toISOString() };
-  await fs.writeFile(file, JSON.stringify(r, null, 2), 'utf8');
-  return r;
-}
+// Replays — capture Task() payloads so an agent can be re-run with the same
+// inputs but an updated prompt. Tight feedback loop for iterating on agent
+// definitions without re-running the whole workflow.
+//
+// Storage: .planning/replays/{phase}-{plan?}-{timestamp}-{agent}.json
+//
+// Payload shape:
+//   {
+//     id, agent, phase?, plan?, timestamp,
+//     subagent_type, model, isolation,
+//     prompt, files_to_read, agent_skills,
+//     outcome?: { status, notes }
+//   }
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { redactSecrets } from './error-redaction.js';
+
+const REPLAY_DIR_REL = path.join('.planning', 'replays');
+
+// SEC-13-02: replayId path traversal guard. The MCP forensics tool exposes
+// load-replay/annotate-replay/record-replay actions; without sanitization,
+// a malicious replayId like '../../../etc/passwd' would read/write files
+// outside .planning/replays/.
+//
+// Strategy: allowlist regex (no slashes, no '..', no NUL) + post-resolve assertion
+// that the final path stays inside REPLAY_DIR_REL.
+const REPLAY_ID_RE = /^[A-Za-z0-9_.-]+$/;
+
+function validateReplayId(id) {
+  if (typeof id !== 'string' || !id) {
+    throw new Error('invalid replay id: must be a non-empty string');
+  }
+  if (id === '.' || id === '..' || id.includes('..')) {
+    throw new Error('invalid replay id: traversal sequences not allowed');
+  }
+  if (!REPLAY_ID_RE.test(id)) {
+    throw new Error(`invalid replay id: only [A-Za-z0-9_.-] allowed, got ${JSON.stringify(id)}`);
+  }
+  return id;
+}
+
+function assertPathInside(filePath, baseDir) {
+  const resolved = path.resolve(filePath);
+  const base = path.resolve(baseDir);
+  // Ensure resolved is base or a child of base (handle trailing-sep edge case).
+  if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+    throw new Error('invalid replay id: resolved path escapes replay directory');
+  }
+  return resolved;
+}
+
+export async function recordReplay(payload, opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const dir = path.join(projectRoot, REPLAY_DIR_REL);
+  await fs.mkdir(dir, { recursive: true });
+
+  const ts   = new Date().toISOString().replace(/[:.]/g, '-');
+  // SEC-13-02: validate each slug component independently before concat
+  const slugParts = [payload.phase, payload.plan, payload.agent].filter(Boolean);
+  for (const part of slugParts) {
+    validateReplayId(String(part));
+  }
+  const slug = slugParts.join('-') || 'unknown';
+  const id   = `${ts}-${slug}`;
+  // Re-validate the full id (defense in depth — ts is well-formed but cheap to check)
+  validateReplayId(id);
+  const file = path.join(dir, `${id}.json`);
+  assertPathInside(file, dir);
+
+  const record = { id, recorded_at: new Date().toISOString(), ...payload };
+  // SEC-14-06: scrub the serialized form before writing. We redact AFTER
+  // JSON.stringify (rather than deep-mapping the payload tree) so the regex
+  // walks the entire structure including nested args/headers/env, and so
+  // the in-memory `record` returned to the caller stays unmutated. Only the
+  // on-disk artifact is scrubbed; readers of the file via loadReplay see
+  // the redacted form, which is the desired outcome — secrets must not be
+  // re-loaded into memory either.
+  const json = redactSecrets(JSON.stringify(record, null, 2));
+  await fs.writeFile(file, json, 'utf8');
+  return { id, file, record };
+}
+
+export async function listReplays(opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const dir = path.join(projectRoot, REPLAY_DIR_REL);
+  let entries;
+  try { entries = await fs.readdir(dir); } catch { return []; }
+  const items = [];
+  for (const e of entries) {
+    if (!e.endsWith('.json')) continue;
+    try {
+      const r = JSON.parse(await fs.readFile(path.join(dir, e), 'utf8'));
+      items.push({ id: r.id, agent: r.agent, phase: r.phase, plan: r.plan, recorded_at: r.recorded_at });
+    } catch {}
+  }
+  return items.sort((a, b) => (b.recorded_at ?? '').localeCompare(a.recorded_at ?? ''));
+}
+
+export async function loadReplay(id, opts = {}) {
+  validateReplayId(id);
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const dir = path.join(projectRoot, REPLAY_DIR_REL);
+  const file = path.join(dir, `${id}.json`);
+  assertPathInside(file, dir);
+  const raw  = await fs.readFile(file, 'utf8');
+  return JSON.parse(raw);
+}
+
+export async function annotateReplay(id, outcome, opts = {}) {
+  validateReplayId(id);
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const dir = path.join(projectRoot, REPLAY_DIR_REL);
+  const file = path.join(dir, `${id}.json`);
+  assertPathInside(file, dir);
+  const r = JSON.parse(await fs.readFile(file, 'utf8'));
+  r.outcome = { ...(r.outcome ?? {}), ...outcome, annotated_at: new Date().toISOString() };
+  await fs.writeFile(file, JSON.stringify(r, null, 2), 'utf8');
+  return r;
+}