@ijfw/memory-server 1.4.3 → 1.5.0

package/src/cross-project-search.js

@@ -1,50 +1,236 @@
 // --- cross-project-search: BM25 search across every registered IJFW project ---
 //
-// Complements the existing naive keyword-count searchAcrossProjects in
-// server.js. Builds a corpus of (project, source, line) docs from each
+// Canonical cross-project search surface. The legacy naive-keyword-count
+// `searchAcrossProjects` in server.js was removed in v1.5.1 H1.5 (audit
+// finding memory-engine.md F-FUN-4) — `scope:'all'` on the MCP search tool
+// now routes here. Builds a corpus of (project, source, line) docs from each
 // registered project's memory files, hands it to the BM25 ranker in
 // search-bm25.js, and returns hits tagged with [project:<basename>].
 //
 // Pure + injectable. The caller supplies the registry reader and the
 // per-project memory reader so this module can be unit-tested without
 // touching the home directory.
+//
+// v1.5.0 audit-H3.4 (memory-engine.md F-SEC-1): registry entries are
+// treated as UNTRUSTED. Each entry.path is:
+//   1. realpath-resolved (symlinks resolved against the filesystem)
+//   2. containment-checked against `allowedRoots` (default: $HOME)
+//   3. silently skipped if it escapes the allowed roots OR fails realpath
+//   4. logged to stderr ONCE per unique offending raw-path (Set dedup)
+// Threat model: a compromised dep / malicious project that writes a
+// registry entry pointing at /etc/passwd via a symlink in the user's
+// home directory will be caught by step 1+2. Plain `isAbsolute()` was
+// the only prior validation and was insufficient.
 
-import { basename } from 'node:path';
+import { basename, resolve, join } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { searchCorpus } from './search-bm25.js';
 
+// v1.5.0 audit MED #10 (memory-engine.md F-SPD-2): per-project corpus
+// cache keyed on (canonicalProjectPath, signature) where `signature` is
+// the joined mtimes of the project's memory files. As long as nothing
+// has changed under .ijfw/memory the cache hits and we skip the
+// readProjectMemory() call entirely. Cache is module-local; tests can
+// reset via _resetCorpusCache(). Cap at 64 entries (LRU-ish via Map
+// insertion order) so a long-lived dashboard process can't OOM the cache.
+const CORPUS_CACHE = new Map();
+const CORPUS_CACHE_CAP = 64;
+
+/** Reset the corpus mtime cache. Test-only. */
+export function _resetCorpusCache() {
+  CORPUS_CACHE.clear();
+}
+
+// Files that participate in the cache signature. Match the readers used
+// by readProjectMemory in server.js so an edit to any of them busts the
+// cache. Missing files contribute "0" -- creation of a previously-missing
+// file is a cache-bust on its own.
+const CACHE_SIGNATURE_FILES = [
+  ['.ijfw', 'memory', 'knowledge.md'],
+  ['.ijfw', 'memory', 'project-journal.md'],
+  ['.ijfw', 'memory', 'handoff.md'],
+  ['.ijfw', 'memory', 'team-knowledge.md'],
+];
+
+function computeProjectSignature(canonicalProjectPath) {
+  let sig = '';
+  for (const parts of CACHE_SIGNATURE_FILES) {
+    const p = join(canonicalProjectPath, ...parts);
+    try {
+      const s = statSync(p);
+      sig += `${s.mtimeMs.toFixed(3)}:${s.size}|`;
+    } catch {
+      sig += '0|';
+    }
+  }
+  return sig;
+}
+
+function getCachedDocs(canonicalProjectPath) {
+  const sig = computeProjectSignature(canonicalProjectPath);
+  const cached = CORPUS_CACHE.get(canonicalProjectPath);
+  if (cached && cached.sig === sig) {
+    // LRU touch: re-insert at the end of the Map iteration order.
+    CORPUS_CACHE.delete(canonicalProjectPath);
+    CORPUS_CACHE.set(canonicalProjectPath, cached);
+    return cached.docs;
+  }
+  return null;
+}
+
+function setCachedDocs(canonicalProjectPath, docs) {
+  const sig = computeProjectSignature(canonicalProjectPath);
+  CORPUS_CACHE.set(canonicalProjectPath, { sig, docs });
+  // Trim oldest entry if we're over the cap. Map iteration is insertion
+  // order so the first key is the oldest.
+  if (CORPUS_CACHE.size > CORPUS_CACHE_CAP) {
+    const oldestKey = CORPUS_CACHE.keys().next().value;
+    if (oldestKey !== undefined) CORPUS_CACHE.delete(oldestKey);
+  }
+}
+
+// Module-level dedup set for "skipped offender" stderr noise control.
+// Keyed by the raw entry.path (the attacker-controlled string) so the same
+// malicious entry is reported only once per process lifetime. Exported for
+// test reset via `_resetSkipLog()`.
+const SKIP_LOG = new Set();
+
+/** Reset the skip-log dedup set. Test-only. */
+export function _resetSkipLog() {
+  SKIP_LOG.clear();
+}
+
+/** Default allowed roots: just the user's home directory.
+ *  Tests can pass `opts.allowedRoots` to constrain or widen.
+ *  Returned as resolved (realpath'd) absolute paths so containment
+ *  comparison is apples-to-apples with the realpath'd entry. */
+function defaultAllowedRoots() {
+  const roots = [];
+  try {
+    const home = homedir();
+    if (home && typeof home === 'string') {
+      // realpath the root itself so /var/root on macOS resolves to
+      // /private/var/root (same canonicalization as the entry side).
+      try { roots.push(realpathSync(home)); } catch { roots.push(resolve(home)); }
+    }
+  } catch { /* ignore */ }
+  return roots;
+}
+
+/** True iff `child` is `root` or a path nested under `root`.
+ *  Both inputs are expected to be already-canonical absolute paths.
+ *  We compare with a trailing-separator guard so `/home/alice-evil`
+ *  is NOT considered inside `/home/alice`. */
+function isUnder(child, root) {
+  if (!child || !root) return false;
+  if (child === root) return true;
+  // Use both POSIX and Windows separators defensively. Path normalization
+  // has already happened via realpathSync; we just need the boundary check.
+  const withPosixSep   = root.endsWith('/')  ? root : root + '/';
+  const withWindowsSep = root.endsWith('\\') ? root : root + '\\';
+  return child.startsWith(withPosixSep) || child.startsWith(withWindowsSep);
+}
+
+/** Resolve + containment check.
+ *  Returns the canonical path on success, or null if the entry must be
+ *  skipped. On skip, logs to stderr once per unique raw path. */
+function safeResolveProjectPath(rawPath, allowedRoots) {
+  if (!rawPath || typeof rawPath !== 'string') {
+    return _skip(rawPath, 'not-a-string');
+  }
+  let canonical;
+  try {
+    // realpathSync resolves symlinks. If the entry points to a symlink
+    // chain whose target escapes allowedRoots, this is where we catch it.
+    canonical = realpathSync(rawPath);
+  } catch {
+    // ENOENT / EACCES / ELOOP — entry path doesn't exist or is unreadable.
+    // Graceful skip; don't throw (a stale registry shouldn't crash search).
+    return _skip(rawPath, 'realpath-failed');
+  }
+  if (!allowedRoots.some(root => isUnder(canonical, root))) {
+    return _skip(rawPath, `escapes-allowed-roots (realpath=${canonical})`);
+  }
+  return canonical;
+}
+
+function _skip(rawPath, reason) {
+  const key = String(rawPath || '<null>');
+  if (!SKIP_LOG.has(key)) {
+    SKIP_LOG.add(key);
+    try {
+      // Single-line, stderr-only — same posture as the rest of the engine's
+      // advisory warnings. Production callers (Claude Code) capture stderr
+      // and surface in the dashboard's diagnostics tab.
+      process.stderr.write(
+        `[ijfw cross-project-search] skipped registry entry: ${reason}: ${key}\n`
+      );
+    } catch { /* never let a logging failure break search */ }
+  }
+  return null;
+}
+
 // Build a corpus of line-level docs from the provided projects.
 //   projects: [{ path, hash?, iso? }]
 //   readProjectMemory(path) -> { knowledge, journal, handoff }  (strings)
+//   opts.allowedRoots: optional array of canonical absolute roots; entries
+//                      whose realpath escapes ALL of them are skipped.
+//                      Default: [realpath(homedir())].
 // Returns [{ id, text, meta }] where meta carries project + source + lineNo.
-export function buildCorpus(projects, readProjectMemory) {
+export function buildCorpus(projects, readProjectMemory, opts = {}) {
+  const allowedRoots = Array.isArray(opts.allowedRoots) && opts.allowedRoots.length
+    ? opts.allowedRoots
+    : defaultAllowedRoots();
   const docs = [];
   for (const entry of projects) {
-    const tag = basename(entry.path);
-    const mem = readProjectMemory(entry.path) || {};
+    if (!entry || typeof entry !== 'object') continue;
+    const canonical = safeResolveProjectPath(entry.path, allowedRoots);
+    if (canonical === null) continue;  // skipped (symlink-escape or missing)
+
+    // v1.5.0 audit MED #10: try the mtime cache before re-reading.
+    // The cache is opt-out via opts.useCache=false (tests / consistency runs).
+    const useCache = opts.useCache !== false;
+    let projectDocs = useCache ? getCachedDocs(canonical) : null;
+    if (projectDocs) {
+      for (const d of projectDocs) docs.push(d);
+      continue;
+    }
+
+    const tag = basename(canonical);
+    // Pass the CANONICAL path to the reader, not the raw one — so a reader
+    // that joins with `.ijfw/memory/...` walks the canonical tree, not a
+    // possibly-spoofed symlink chain.
+    const mem = readProjectMemory(canonical) || {};
+    projectDocs = [];
     for (const [source, content] of Object.entries(mem)) {
       if (typeof content !== 'string' || content.length === 0) continue;
       const lines = content.split('\n');
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (line.trim().length === 0) continue;
-        docs.push({
+        projectDocs.push({
           id: `${tag}:${source}:${i + 1}`,
           text: line,
-          meta: { project: tag, projectPath: entry.path, source, lineNo: i + 1 },
+          meta: { project: tag, projectPath: canonical, source, lineNo: i + 1 },
         });
       }
     }
+    if (useCache) setCachedDocs(canonical, projectDocs);
+    for (const d of projectDocs) docs.push(d);
   }
   return docs;
 }
 
 // Run a BM25-ranked search across the corpus produced from `projects`.
 // Returns [{ content, source, line, project, score, snippet }], capped at limit.
+//   opts.allowedRoots: forwarded to buildCorpus (see above).
+//   opts.limit: 1..50, default 10.
 export function crossProjectSearch(query, projects, readProjectMemory, opts = {}) {
   const limit = clamp(opts.limit, 1, 50, 10);
   if (!query || typeof query !== 'string') return [];
 
-  const docs = buildCorpus(projects, readProjectMemory);
+  const docs = buildCorpus(projects, readProjectMemory, opts);
   if (docs.length === 0) return [];
 
   const hits = searchCorpus(query, docs, { limit });

package/src/dashboard-client-planning.html

@@ -0,0 +1,273 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>IJFW · Planning Docs</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #fafafa; color: #222; }
+  header { padding: 12px 20px; border-bottom: 1px solid #ddd; background: #fff; }
+  header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+  header .sub { color: #777; font-size: 12px; margin-top: 4px; }
+  main { padding: 20px; max-width: 900px; margin: 0 auto; }
+  .path-input { width: 100%; padding: 8px 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; border: 1px solid #ccc; border-radius: 4px; }
+  .roots { color: #777; font-size: 12px; margin: 8px 0 16px; }
+  .roots code { background: #eee; padding: 1px 5px; border-radius: 3px; }
+  .doc { background: #fff; padding: 24px 28px; border: 1px solid #ddd; border-radius: 6px; min-height: 300px; }
+  .doc h1 { font-size: 22px; margin: 0 0 12px; }
+  .doc h2 { font-size: 18px; margin: 24px 0 10px; padding-bottom: 4px; border-bottom: 1px solid #eee; }
+  .doc h3 { font-size: 15px; margin: 20px 0 8px; }
+  .doc pre { background: #f4f4f4; padding: 12px; border-radius: 4px; overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc code { background: #f4f4f4; padding: 1px 4px; border-radius: 3px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc pre code { background: transparent; padding: 0; }
+  .doc table { border-collapse: collapse; margin: 12px 0; }
+  .doc th, .doc td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; font-size: 13px; }
+  .doc th { background: #f4f4f4; }
+  .doc blockquote { border-left: 3px solid #ccc; padding-left: 12px; color: #666; margin: 12px 0; }
+  .err { color: #c00; font-style: italic; }
+  .hint { color: #777; font-style: italic; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #1a1a1a; color: #ddd; }
+    header { background: #222; border-color: #333; }
+    .doc, .path-input { background: #222; border-color: #333; color: #ddd; }
+    .doc pre, .doc code, .roots code, .doc th { background: #2a2a2a; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>IJFW · Planning Docs</h1>
+  <div class="sub">Browse .planning/, .ijfw/memory/, and .ijfw/wave-*/ docs from this project.</div>
+</header>
+<main>
+  <input type="text" id="path" class="path-input" placeholder=".planning/1.4.4/HANDOFF-1.4.4.md" autofocus>
+  <div class="roots">Allowed roots: .planning/ · .ijfw/memory/ · .ijfw/wave-*/STATE.md · .ijfw/wave-*/SUMMARY.md</div>
+  <div id="doc" class="doc"></div>
+</main>
+<script>
+  // Tiny markdown shim — produces a safe DOMFragment via DOMParser, no innerHTML.
+  // Renders the subset used in IJFW planning docs: headings, paragraphs, code blocks,
+  // inline code/bold/italic, links, lists, blockquotes, tables. Not a full CommonMark.
+
+  function setText(el, text) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    el.appendChild(document.createTextNode(text));
+  }
+  function setStatus(el, text, cls) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    const div = document.createElement('div');
+    div.className = cls;
+    div.textContent = text;
+    el.appendChild(div);
+  }
+
+  function makeNode(tag, text) {
+    const el = document.createElement(tag);
+    if (text !== undefined) el.appendChild(document.createTextNode(text));
+    return el;
+  }
+
+  // Renders a single line of markdown-inline content into an array of DOM nodes.
+  // Handles `code`, **bold**, *italic*, [text](url). All text is added via
+  // createTextNode — no HTML parsing of user content.
+  function renderInlineToNodes(s) {
+    const nodes = [];
+    let i = 0;
+    while (i < s.length) {
+      // Code span: `...`
+      if (s[i] === '`') {
+        const end = s.indexOf('`', i + 1);
+        if (end !== -1) {
+          nodes.push(makeNode('code', s.slice(i + 1, end)));
+          i = end + 1;
+          continue;
+        }
+      }
+      // Bold: **...**
+      if (s[i] === '*' && s[i + 1] === '*') {
+        const end = s.indexOf('**', i + 2);
+        if (end !== -1) {
+          nodes.push(makeNode('strong', s.slice(i + 2, end)));
+          i = end + 2;
+          continue;
+        }
+      }
+      // Italic: *...*
+      if (s[i] === '*') {
+        const end = s.indexOf('*', i + 1);
+        if (end !== -1 && end - i > 1) {
+          nodes.push(makeNode('em', s.slice(i + 1, end)));
+          i = end + 1;
+          continue;
+        }
+      }
+      // Link: [text](url)
+      if (s[i] === '[') {
+        const close = s.indexOf(']', i + 1);
+        if (close !== -1 && s[close + 1] === '(') {
+          const urlEnd = s.indexOf(')', close + 2);
+          if (urlEnd !== -1) {
+            const a = document.createElement('a');
+            a.textContent = s.slice(i + 1, close);
+            // r13-L-01: tightened URL guard.
+            // ALLOW: http://, https://, and same-origin relative paths (no protocol).
+            // BLOCK: javascript:, data:, mailto:, vbscript:, file:, AND protocol-relative
+            //        URLs starting with `//` (would open cross-origin without scheme).
+            const url = s.slice(close + 2, urlEnd);
+            const isAllowed = (
+              /^https?:\/\//.test(url) ||                  // explicit http/https
+              (!url.startsWith('//') && !/^[^:/?#]+:/.test(url))   // relative, no protocol, no `//`
+            );
+            if (isAllowed) {
+              a.href = url;
+              a.target = '_blank';
+              a.rel = 'noopener';
+            }
+            nodes.push(a);
+            i = urlEnd + 1;
+            continue;
+          }
+        }
+      }
+      // Plain text — accumulate until next special marker
+      let j = i;
+      while (j < s.length && !'`*['.includes(s[j])) j++;
+      if (j === i) j = i + 1;
+      nodes.push(document.createTextNode(s.slice(i, j)));
+      i = j;
+    }
+    return nodes;
+  }
+
+  function renderMarkdownToFragment(md) {
+    const frag = document.createDocumentFragment();
+    const lines = md.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+      const line = lines[i];
+      // Fenced code block
+      if (/^```/.test(line)) {
+        const buf = [];
+        i++;
+        while (i < lines.length && !/^```/.test(lines[i])) { buf.push(lines[i]); i++; }
+        i++;
+        const pre = document.createElement('pre');
+        const code = document.createElement('code');
+        code.textContent = buf.join('\n');
+        pre.appendChild(code);
+        frag.appendChild(pre);
+        continue;
+      }
+      // Headings
+      const h = line.match(/^(#{1,6})\s+(.*)$/);
+      if (h) {
+        const tag = 'h' + h[1].length;
+        const el = document.createElement(tag);
+        for (const n of renderInlineToNodes(h[2])) el.appendChild(n);
+        frag.appendChild(el);
+        i++;
+        continue;
+      }
+      // Table: header row + separator row + rows
+      if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*-/.test(lines[i + 1])) {
+        const tbl = document.createElement('table');
+        const head = line.split('|').slice(1, -1).map((c) => c.trim());
+        const tr = document.createElement('tr');
+        for (const c of head) {
+          const th = document.createElement('th');
+          for (const n of renderInlineToNodes(c)) th.appendChild(n);
+          tr.appendChild(th);
+        }
+        tbl.appendChild(tr);
+        i += 2;
+        while (i < lines.length && /^\s*\|/.test(lines[i])) {
+          const cells = lines[i].split('|').slice(1, -1).map((c) => c.trim());
+          const row = document.createElement('tr');
+          for (const c of cells) {
+            const td = document.createElement('td');
+            for (const n of renderInlineToNodes(c)) td.appendChild(n);
+            row.appendChild(td);
+          }
+          tbl.appendChild(row);
+          i++;
+        }
+        frag.appendChild(tbl);
+        continue;
+      }
+      // Bullet list
+      if (/^\s*[-*]\s+/.test(line)) {
+        const ul = document.createElement('ul');
+        while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+          const li = document.createElement('li');
+          for (const n of renderInlineToNodes(lines[i].replace(/^\s*[-*]\s+/, ''))) li.appendChild(n);
+          ul.appendChild(li);
+          i++;
+        }
+        frag.appendChild(ul);
+        continue;
+      }
+      // Blockquote
+      if (/^>\s?/.test(line)) {
+        const bq = document.createElement('blockquote');
+        let first = true;
+        while (i < lines.length && /^>\s?/.test(lines[i])) {
+          if (!first) bq.appendChild(document.createElement('br'));
+          for (const n of renderInlineToNodes(lines[i].replace(/^>\s?/, ''))) bq.appendChild(n);
+          first = false;
+          i++;
+        }
+        frag.appendChild(bq);
+        continue;
+      }
+      // Blank
+      if (line.trim() === '') { i++; continue; }
+      // Paragraph
+      const p = document.createElement('p');
+      const buf = [line];
+      i++;
+      while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|>|\s*[-*]\s|\s*\|)/.test(lines[i])) {
+        buf.push(lines[i]);
+        i++;
+      }
+      for (const n of renderInlineToNodes(buf.join(' '))) p.appendChild(n);
+      frag.appendChild(p);
+    }
+    return frag;
+  }
+
+  async function load(path) {
+    const doc = document.getElementById('doc');
+    setStatus(doc, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/planning?path=' + encodeURIComponent(path));
+      if (!r.ok) {
+        const err = await r.json().catch(() => ({ error: 'unknown' }));
+        setStatus(doc, r.status + ': ' + (err.error || 'failed'), 'err');
+        return;
+      }
+      const j = await r.json();
+      while (doc.firstChild) doc.removeChild(doc.firstChild);
+      doc.appendChild(renderMarkdownToFragment(j.body || ''));
+    } catch (e) {
+      setStatus(doc, e.message, 'err');
+    }
+  }
+
+  // Initial hint
+  setStatus(document.getElementById('doc'),
+    'Enter a relative path above (e.g. .planning/1.4.4/HANDOFF-1.4.4.md) and press Enter.',
+    'hint');
+
+  const input = document.getElementById('path');
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && input.value.trim()) load(input.value.trim());
+  });
+  // Auto-load if ?path= in URL
+  const params = new URLSearchParams(location.search);
+  const init = params.get('path');
+  if (init) { input.value = init; load(init); }
+</script>
+</body>
+</html>