@luanpdd/kit-mcp 1.13.0 → 1.14.0

package/src/core/manifest-verify.js

@@ -0,0 +1,103 @@
+// SEC-14-05: verify kit/file-manifest.json against actual file contents.
+// Called by syncTo() in install path, before any write — refuses to project
+// a tampered kit. Opt-out via KIT_MCP_SKIP_MANIFEST_CHECK=1 (warn on stderr).
+//
+// Manifest format (kit/file-manifest.json):
+//   { version, timestamp, files: { "<rel-to-kitRoot>": "<sha256-hex>", ... } }
+//
+// Returns:
+//   { ok: true } when all listed files exist + match.
+//   { ok: true, skipped: true } when KIT_MCP_SKIP_MANIFEST_CHECK=1.
+//   { ok: false, reason, mismatches, missing } otherwise.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+
+const SKIP_ENV = 'KIT_MCP_SKIP_MANIFEST_CHECK';
+
+export async function verifyManifest(kitRoot) {
+  if (process.env[SKIP_ENV] === '1') {
+    process.stderr.write(
+      '[kit-mcp] WARNING: ' + SKIP_ENV + '=1 set — skipping kit/file-manifest.json verification (dev mode).\n'
+    );
+    return { ok: true, skipped: true };
+  }
+
+  const manifestPath = path.join(kitRoot, 'file-manifest.json');
+  let manifest;
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    manifest = JSON.parse(raw);
+  } catch (e) {
+    return {
+      ok: false,
+      reason: 'kit manifest unreadable at ' + manifestPath + ': ' + e.message,
+      mismatches: [],
+      missing: [],
+    };
+  }
+
+  if (!manifest.files || typeof manifest.files !== 'object') {
+    return {
+      ok: false,
+      reason: "kit manifest malformed at " + manifestPath + ": missing 'files' object",
+      mismatches: [],
+      missing: [],
+    };
+  }
+
+  const mismatches = [];
+  const missing = [];
+
+  for (const [rel, expected] of Object.entries(manifest.files)) {
+    const abs = path.join(kitRoot, rel);
+    let buf;
+    try {
+      buf = await fs.readFile(abs);
+    } catch {
+      missing.push(rel);
+      continue;
+    }
+    const actual = crypto.createHash('sha256').update(buf).digest('hex');
+    if (actual !== expected) {
+      mismatches.push({ path: rel, expected: expected.slice(0, 16), actual: actual.slice(0, 16) });
+    }
+  }
+
+  if (mismatches.length === 0 && missing.length === 0) {
+    return { ok: true };
+  }
+
+  // Build a concise reason — first 3 mismatches, plus counts.
+  const sample = mismatches
+    .slice(0, 3)
+    .map((m) => m.path + ' (expected ' + m.expected + ', got ' + m.actual + ')')
+    .join('; ');
+  const missingSample = missing.slice(0, 3).join(', ');
+  const reasonParts = [];
+  if (mismatches.length > 0) {
+    reasonParts.push(
+      mismatches.length +
+        ' file(s) tampered: ' +
+        sample +
+        (mismatches.length > 3 ? ', +' + (mismatches.length - 3) + ' more' : '')
+    );
+  }
+  if (missing.length > 0) {
+    reasonParts.push(
+      missing.length +
+        ' file(s) missing: ' +
+        missingSample +
+        (missing.length > 3 ? ', +' + (missing.length - 3) + ' more' : '')
+    );
+  }
+  reasonParts.push('set ' + SKIP_ENV + '=1 to bypass (dev only)');
+
+  return {
+    ok: false,
+    reason: 'kit manifest mismatch — ' + reasonParts.join('; '),
+    mismatches,
+    missing,
+  };
+}

package/src/core/path-safety.js

@@ -0,0 +1,111 @@
+// 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';
+
+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/reflect.js

@@ -19,6 +19,7 @@ import fs from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output, stderr } from 'node:process';
 import { resolveKitRoot } from './kit.js';
+import { redactSecrets } from './error-redaction.js';
 
 const DEFAULT_MODEL      = process.env.KIT_REFLECT_MODEL ?? 'claude-sonnet-4-5-20250929';
 const DEFAULT_MAX_TOKENS = parseInt(process.env.KIT_REFLECT_MAX_TOKENS ?? '8000', 10);
@@ -169,7 +170,11 @@ async function callClaude(prompt) {
   });
   if (!res.ok) {
     const errBody = await res.text();
-    throw new Error(`Anthropic API ${res.status}: ${errBody}`);
+    // SEC-14-06: Anthropic error responses can echo the supplied API key
+    // (rare but observed in 401s). Strip secrets/paths before propagating
+    // to caller — the central MCP catch will sanitize again, but doing it
+    // here means CLI callers (which bypass the MCP catch) are also protected.
+    throw new Error(`Anthropic API ${res.status}: ${redactSecrets(errBody)}`);
   }
   const j = await res.json();
   return {

package/src/core/replays.js

@@ -14,6 +14,7 @@
 
 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');
 
@@ -68,7 +69,15 @@ export async function recordReplay(payload, opts = {}) {
   assertPathInside(file, dir);
 
   const record = { id, recorded_at: new Date().toISOString(), ...payload };
-  await fs.writeFile(file, JSON.stringify(record, null, 2), 'utf8');
+  // 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 };
 }
 

package/src/core/sync.js

@@ -13,6 +13,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { getTarget } from './registry.js';
 import { listKit, resolveKitRoot } from './kit.js';
+import { verifyManifest } from './manifest-verify.js';
 
 const STUB_MARKER = '<!-- kit-mcp:reference -->';
 const MANAGED_MARKER_FILE = '.kit-mcp-managed';
@@ -26,6 +27,18 @@ export async function syncTo(targetId, opts = {}) {
   const dryRun      = !!opts.dryRun;
   const onProgress  = opts.onProgress ?? (() => {});
 
+  // SEC-14-05: verify kit integrity before projecting. Refuses tampered kit/.
+  // Opt-out via KIT_MCP_SKIP_MANIFEST_CHECK=1 (handled inside verifyManifest).
+  // Only runs on install path (syncTo); removeFrom/statusOf/applyReverse don't
+  // call this — see plan 83-03 for rationale (apply path is the introduction
+  // vector, not the trust point; stale-but-intact kits in dev are skipped).
+  const manifestCheck = await verifyManifest(kitRoot);
+  if (!manifestCheck.ok) {
+    const err = new Error(manifestCheck.reason);
+    err.code = 'EMANIFESTMISMATCH';
+    throw err;
+  }
+
   // PERF-03: accept a pre-loaded kit to avoid re-walking the disk when callers
   // already have one in hand (CLI sync that follows reverse-sync detect, etc).
   // PERF-S1: in mode=reference (default), read just frontmatter — body/content

package/src/mcp-server/index.js

@@ -20,6 +20,8 @@ import { listKit, searchKit, findItem } from '../core/kit.js';
 import { listTargets } from '../core/registry.js';
 import { syncTo, statusOf, removeFrom, summarize } from '../core/sync.js';
 import { detectReverse, applyReverse } from '../core/reverse-sync.js';
+import { validateProjectRoot } from '../core/path-safety.js';
+import { sanitizeMcpError } from '../core/error-redaction.js';
 import { listGates, getGate, gatesForStage } from '../core/gates.js';
 import { runGate } from '../core/gate-runner.js';
 import { collectFailures, summarizeByAgent, writeLearnings } from '../core/failures.js';
@@ -192,25 +194,45 @@ async function withAutoSpawn(args, tool, run) {
 async function handleSync(args) {
   switch (args.action) {
     case 'targets': return listTargets();
-    case 'status':  return statusOf(args.target, { projectRoot: args.projectRoot });
+    case 'status':
     case 'install':
-      return withAutoSpawn(args, 'sync.install', (onProgress) =>
-        syncTo(args.target, { projectRoot: args.projectRoot, mode: args.mode, dryRun: args.dryRun, onProgress }));
-    case 'remove':  return removeFrom(args.target, { projectRoot: args.projectRoot });
+    case 'remove': {
+      // SEC-14-03: MCP message must specify a path inside a git workspace.
+      // CLI bypasses this — bin/cli.js trusts whoever invoked it (same trust
+      // model as Phase 79.01's gates.run guard). status is read-only but
+      // included for defense-in-depth and a single uniform error surface.
+      const guard = await validateProjectRoot(args.projectRoot);
+      if (!guard.ok) return { error: guard.reason };
+      const projectRoot = guard.resolvedPath;
+      if (args.action === 'status') return statusOf(args.target, { projectRoot });
+      if (args.action === 'install')
+        return withAutoSpawn({ ...args, projectRoot }, 'sync.install', (onProgress) =>
+          syncTo(args.target, { projectRoot, mode: args.mode, dryRun: args.dryRun, onProgress }));
+      // action === 'remove'
+      return removeFrom(args.target, { projectRoot });
+    }
     default: return { error: `Unknown action: ${args.action}` };
   }
 }
 
 async function handleReverseSync(args) {
   switch (args.action) {
-    case 'detect': return detectReverse(args.target, { projectRoot: args.projectRoot });
-    case 'apply':
-      return withAutoSpawn(args, 'reverse-sync.apply', (onProgress) =>
+    case 'detect':
+    case 'apply': {
+      // SEC-14-03: same guard as handleSync — reverse-sync apply also writes
+      // to disk (kit/<file>) so it must be on the same allowlist as sync.
+      const guard = await validateProjectRoot(args.projectRoot);
+      if (!guard.ok) return { error: guard.reason };
+      const projectRoot = guard.resolvedPath;
+      if (args.action === 'detect') return detectReverse(args.target, { projectRoot });
+      // action === 'apply'
+      return withAutoSpawn({ ...args, projectRoot }, 'reverse-sync.apply', (onProgress) =>
         applyReverse(args.target, {
-          projectRoot: args.projectRoot,
+          projectRoot,
           strategy: args.strategy, only: args.only, dryRun: args.dryRun,
           onProgress,
         }));
+    }
     default: return { error: `Unknown action: ${args.action}` };
   }
 }
@@ -303,8 +325,12 @@ export async function createServer() {
       const result = await handler(args ?? {});
       return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     } catch (e) {
+      // SEC-14-06: full stack stays in stderr for operator debug; client envelope is sanitized.
+      // sanitizeMcpError redacts secrets/paths from e.message, preserves e.code (Phase 83
+      // EMANIFESTMISMATCH invariant), and emits NO stack field.
+      console.error('[mcp-server] error in handler:', e?.stack ?? e);
       return {
-        content: [{ type: 'text', text: JSON.stringify({ error: e.message, stack: e.stack }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify(sanitizeMcpError(e), null, 2) }],
         isError: true,
       };
     }

package/src/ui/auto-spawn.js

@@ -97,7 +97,12 @@ export async function ensureSidecar({ projectRoot, openBrowserOnSpawn = true } =
 
   let opened = false;
   if (openBrowserOnSpawn) {
-    const url = `http://127.0.0.1:${lock.port}/`;
+    // SEC-14-02: propagate auth token via query param so browser can self-authenticate
+    // without user interaction. EventSource cannot send custom headers; ?t= is the
+    // canonical pattern. The browser scrubs ?t= from the address bar via
+    // history.replaceState immediately on boot to avoid leak via screenshare.
+    const tokenSuffix = lock.token ? `?t=${encodeURIComponent(lock.token)}` : '';
+    const url = `http://127.0.0.1:${lock.port}/${tokenSuffix}`;
     const r = await openBrowser(url);
     opened = r.opened === true;
   }

package/src/ui/client.js

@@ -8,34 +8,43 @@ import http from 'node:http';
 import { readLock } from './lockfile.js';
 import { validateEvent } from './events.js';
 
-// Cache the resolved port across calls in a single process.
-const portCache = new Map(); // projectRoot -> port (or 0 = no sidecar)
-const PORT_CACHE_TTL_MS = 5_000;
+// Cache the resolved sidecar (port + token) across calls in a single process.
+// SEC-14-02: token is needed for Authorization on every publish() — read from
+// the same lockfile read as port to avoid double I/O.
+const sidecarCache = new Map(); // projectRoot -> { port, token } | { port: 0, token: null }
+const SIDECAR_CACHE_TTL_MS = 5_000;
 const cacheTimestamps = new Map();
 
-function readCachedPort(projectRoot) {
+function readCachedSidecar(projectRoot) {
   const ts = cacheTimestamps.get(projectRoot);
-  if (!ts || Date.now() - ts > PORT_CACHE_TTL_MS) return undefined;
-  return portCache.get(projectRoot);
+  if (!ts || Date.now() - ts > SIDECAR_CACHE_TTL_MS) return undefined;
+  return sidecarCache.get(projectRoot);
 }
 
-function writeCachedPort(projectRoot, port) {
-  portCache.set(projectRoot, port);
+function writeCachedSidecar(projectRoot, sidecar) {
+  sidecarCache.set(projectRoot, sidecar);
   cacheTimestamps.set(projectRoot, Date.now());
 }
 
+// Backward-compat name; clears port + token cache. Tests + callers using
+// clearPortCache continue to work without code change.
 export function clearPortCache() {
-  portCache.clear();
+  sidecarCache.clear();
   cacheTimestamps.clear();
 }
 
-function resolvePort(projectRoot) {
-  const cached = readCachedPort(projectRoot);
+function resolveSidecar(projectRoot) {
+  const cached = readCachedSidecar(projectRoot);
   if (cached !== undefined) return cached;
   const lock = readLock(projectRoot);
-  const port = lock?.port ?? 0;
-  writeCachedPort(projectRoot, port);
-  return port;
+  const sidecar = {
+    port: lock?.port ?? 0,
+    // SEC-14-02: null if missing (lockfile from older sidecar version pre-v1.14).
+    // Triggers degraded path: no Authorization header → server 401 → soft-fail.
+    token: typeof lock?.token === 'string' ? lock.token : null,
+  };
+  writeCachedSidecar(projectRoot, sidecar);
+  return sidecar;
 }
 
 // publish(event, { projectRoot, timeoutMs }): always resolves. Returns
@@ -47,7 +56,7 @@ export async function publish(event, { projectRoot, timeoutMs = 1500 } = {}) {
   const validationErr = validateEvent(event);
   if (validationErr) return { sent: false, reason: `invalid_event: ${validationErr.message}` };
 
-  const port = resolvePort(projectRoot);
+  const { port, token } = resolveSidecar(projectRoot);
   if (!port) return { sent: false, reason: 'no_sidecar' };
 
   const body = JSON.stringify(event);
@@ -65,6 +74,10 @@ export async function publish(event, { projectRoot, timeoutMs = 1500 } = {}) {
         'content-length': Buffer.byteLength(body, 'utf8'),
         'origin': `http://127.0.0.1:${port}`,
         'connection': 'close',
+        // SEC-14-02: attach Bearer token if lockfile has one. If not (older
+        // sidecar pre-v1.14), server returns 401 → resolves as { sent: false,
+        // reason: 'http_401' } via the soft-fail flow below.
+        ...(token ? { 'authorization': `Bearer ${token}` } : {}),
       },
     }, (res) => {
       // Drain — we don't actually care about the body, just the status.
@@ -73,9 +86,11 @@ export async function publish(event, { projectRoot, timeoutMs = 1500 } = {}) {
         if (res.statusCode >= 200 && res.statusCode < 300) {
           resolve({ sent: true, status: res.statusCode });
         } else {
-          // Stale lockfile? Drop the cache so the next call re-reads.
-          if (res.statusCode === 403 || res.statusCode === 404) {
-            portCache.delete(projectRoot);
+          // Stale lockfile or rotated token? Drop cache so next call re-reads.
+          // SEC-14-02: invalidate on 401 too — token may have rotated after
+          // sidecar restart; cache TTL of 5s would otherwise prolong recovery.
+          if (res.statusCode === 401 || res.statusCode === 403 || res.statusCode === 404) {
+            sidecarCache.delete(projectRoot);
             cacheTimestamps.delete(projectRoot);
           }
           resolve({ sent: false, reason: `http_${res.statusCode}` });
@@ -86,7 +101,7 @@ export async function publish(event, { projectRoot, timeoutMs = 1500 } = {}) {
     req.on('error', (err) => {
       // Most common: ECONNREFUSED (lockfile points at a dead port).
       if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET') {
-        portCache.delete(projectRoot);
+        sidecarCache.delete(projectRoot);
         cacheTimestamps.delete(projectRoot);
       }
       resolve({ sent: false, reason: `error: ${err.code || err.message}` });

package/src/ui/lockfile.js

@@ -6,7 +6,7 @@
 //   1. process.kill(pid, 0) — ESRCH/EPERM means the holder is gone
 //   2. optional HTTP healthz probe (injected by caller; keeps this module pure of net)
 
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -55,6 +55,10 @@ export function acquireLock({ projectRoot, port, version, startedAt }) {
     version: version ?? null,
     startedAt: startedAt ?? Date.now(),
     lockSchema: LOCK_VERSION,
+    // SEC-14-02: per-process auth token. 32 random bytes hex-encoded = 64 chars.
+    // Required by /publish, /shutdown, /events, /state. Lifetime = process lifetime;
+    // not logged, not telemetered. See docs/sidecar-security.md.
+    token: randomBytes(32).toString('hex'),
   };
   let fd;
   try {