@ijfw/memory-server 1.4.3 → 1.5.0

package/src/override-use-registry.js

@@ -36,6 +36,92 @@ import os from 'node:os';
 
 const SCHEMA_VERSION = '1.0';
 
+// Maximum path length the registry will accept. Practical limits across the
+// supported platforms are PATH_MAX=4096 (Linux), 1024 (macOS), 32767 (Windows
+// long-path). 4096 is a comfortable cap that won't reject any real path but
+// will reject a flood-of-bytes prompt-injection payload.
+const MAX_PROJECT_ROOT_LEN = 4096;
+
+// Unicode tag-block range (U+E0000–U+E007F) — invisible "ASCII Smuggler" code
+// points historically used to hide prompt-injection payloads inside text the
+// model sees but the human doesn't. Closed at the prelude in H1.4; we also
+// reject at registry-write time to prevent contamination at the source.
+// eslint-disable-next-line security/detect-unsafe-regex -- single-char Unicode range class; no quantifier; not backtrack-exploitable
+const UNICODE_TAG_BLOCK_RE = /[\u{E0000}-\u{E007F}]/u;
+
+// ASCII control characters (excluding nothing — \n \r \t \0 etc are ALL
+// rejected when present in a path key).
+// eslint-disable-next-line no-control-regex -- this regex EXISTS to reject control chars; lint hit is a false positive on the gate itself
+const CONTROL_CHAR_RE = /[\x00-\x1F\x7F]/;
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * F-SEC-4 (HIGH, update-install-trust audit v1.5.0):
+ * recordOverrideUse persisted any non-empty string as a project key and that
+ * value flows verbatim into the cross-project promote suggestion that lands
+ * in the prelude the model reads — a prompt-injection vector.
+ *
+ * Validate projectRoot is shaped like a real absolute filesystem path with
+ * no `..` segments, no control characters, no Unicode tag-block smuggling
+ * code points, and within a sane length cap. Returns `{ ok: true }` on pass
+ * or `{ ok: false, reason }` on fail. We do NOT throw — the caller in
+ * override-resolver.js wraps the registry write in a non-fatal try/catch
+ * and we want a structured signal instead of a thrown Error so future
+ * callers can surface a clean rejection without try/catch noise.
+ *
+ * @param {unknown} projectRoot
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function validateProjectRoot(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return { ok: false, reason: 'projectRoot must be a non-empty string' };
+  }
+  if (projectRoot.length > MAX_PROJECT_ROOT_LEN) {
+    return {
+      ok: false,
+      reason: `projectRoot exceeds max length ${MAX_PROJECT_ROOT_LEN}`,
+    };
+  }
+  if (!path.isAbsolute(projectRoot)) {
+    return { ok: false, reason: 'projectRoot must be an absolute path' };
+  }
+  // Reject any `..` segment in the RAW path before normalization. path.normalize
+  // would collapse interior `..` (e.g. `/a/../b` -> `/b`) and silently rewrite
+  // the registry key, defeating the validation. A real filesystem path passed
+  // by override-resolver.js is already canonical, so a `..` is a tampering
+  // signal. Split on both POSIX and Windows separators so /a/../b and \a\..\b
+  // are both caught regardless of host platform.
+  const rawSegments = projectRoot.split(/[\\/]/);
+  if (rawSegments.includes('..')) {
+    return { ok: false, reason: 'projectRoot must not contain `..` segments' };
+  }
+  if (CONTROL_CHAR_RE.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain control characters',
+    };
+  }
+  if (UNICODE_TAG_BLOCK_RE.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain Unicode tag-block characters',
+    };
+  }
+  // Reject prompt-injection / markdown / HTML tokens that are not meaningful
+  // in a real path but ARE meaningful when rendered into the prelude. These
+  // are not legal in any reasonable filesystem path.
+  if (/[<>`]/.test(projectRoot)) {
+    return {
+      ok: false,
+      reason: 'projectRoot must not contain `<`, `>`, or backtick',
+    };
+  }
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers — read os.homedir()/HOME at call time so tests can swap HOME
 // via process.env between calls.
@@ -111,21 +197,31 @@ async function readSettings() {
  * Idempotent — re-recording the same (project, preset) updates applied_at
  * rather than duplicating the entry.
  *
- * @param {string} projectRoot
+ * Returns `{ ok: true }` on success or `{ ok: false, reason }` on validation
+ * failure. Does NOT throw on bad input — the value flows into the prelude
+ * the model reads, so we want every untrusted projectRoot rejected loudly
+ * via the return contract instead of via an unhandled Error.
+ *
+ * @param {string} projectRoot     MUST be an absolute path, no `..`, no
+ *                                 control / Unicode tag-block / HTML chars.
  * @param {string} preset
  * @param {string} scope          'base' | 'user' | 'org' | 'project'
  * @param {string} [project_type] auto-detected project type, defaults to
  *                                whatever is already on file or 'unknown'.
+ * @returns {Promise<{ ok: true } | { ok: false, reason: string }>}
  */
 export async function recordOverrideUse(projectRoot, preset, scope, project_type) {
-  if (typeof projectRoot !== 'string' || !projectRoot) {
-    throw new Error('recordOverrideUse: projectRoot must be a non-empty string');
+  // F-SEC-4 (HIGH): full path validation on projectRoot before it enters the
+  // registry. See validateProjectRoot above for the threat-model rationale.
+  const pathCheck = validateProjectRoot(projectRoot);
+  if (!pathCheck.ok) {
+    return pathCheck;
   }
   if (typeof preset !== 'string' || !preset) {
-    throw new Error('recordOverrideUse: preset must be a non-empty string');
+    return { ok: false, reason: 'preset must be a non-empty string' };
   }
   if (typeof scope !== 'string' || !scope) {
-    throw new Error('recordOverrideUse: scope must be a non-empty string');
+    return { ok: false, reason: 'scope must be a non-empty string' };
   }
 
   const state = await readRegistry();
@@ -153,6 +249,7 @@ export async function recordOverrideUse(projectRoot, preset, scope, project_type
   }
   state.projects[projectRoot] = proj;
   await writeRegistry(state);
+  return { ok: true };
 }
 
 /**
@@ -186,6 +283,9 @@ export async function findProjectsWithOverride(preset) {
   const out = [];
   for (const [project, entry] of Object.entries(state.projects || {})) {
     if (!entry || !Array.isArray(entry.active_overrides)) continue;
+    // F-SEC-4 (HIGH) defense-in-depth: legacy registries written before
+    // v1.5.1 validation could contain unsafe keys. Refuse to surface them.
+    if (!validateProjectRoot(project).ok) continue;
     const hit = entry.active_overrides.find(
       (o) => o && o.preset === preset
     );
@@ -226,6 +326,10 @@ export async function findProjectsWithSimilarOverrideSet(
   for (const [project, entry] of Object.entries(state.projects || {})) {
     if (exclude && project === exclude) continue;
     if (!entry || !Array.isArray(entry.active_overrides)) continue;
+    // F-SEC-4 (HIGH) defense-in-depth: legacy registries written before
+    // v1.5.1 validation could contain unsafe keys that would flow into the
+    // promote suggestion text and the prelude. Refuse to surface them.
+    if (!validateProjectRoot(project).ok) continue;
     const theirs = new Set(
       entry.active_overrides
         .filter((o) => o && typeof o.preset === 'string')
@@ -304,4 +408,6 @@ export const __test = {
   settingsPath,
   readRegistry,
   writeRegistry,
+  validateProjectRoot,
+  MAX_PROJECT_ROOT_LEN,
 };

package/src/receipts.js

@@ -9,6 +9,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+// v1.5.0 N4.obs M1: tag every receipt with the orchestrator's trace_id so the
+// dashboard can roll up sessions->traces->observations like Langfuse / Helicone.
+import { getTraceId } from './observability/trace-id.js';
 
 export function RECEIPTS_FILE(projectDir) {
   return path.join(projectDir, '.ijfw', 'receipts', 'cross-runs.jsonl');
@@ -24,7 +27,13 @@ export function writeReceipt(projectDir, record) {
   const dest = RECEIPTS_FILE(projectDir);
   const dir = path.dirname(dest);
   fs.mkdirSync(dir, { recursive: true });
-  fs.appendFileSync(dest, JSON.stringify(record) + '\n');
+  // v1.5.0 N4.obs M1: tag with trace_id if one is set + caller hasn't supplied
+  // one. Never overwrite an explicit caller-supplied trace_id.
+  const traceId = getTraceId();
+  const enriched = (traceId && record && typeof record === 'object' && !record.trace_id)
+    ? { ...record, trace_id: traceId }
+    : record;
+  fs.appendFileSync(dest, JSON.stringify(enriched) + '\n');
   _pruneReceipts(dest);
 }
 
@@ -46,8 +55,27 @@ export function purgeReceipts(projectDir) {
   return count;
 }
 
-// Anthropic cache-read savings rate (mirrors hero-line.js constant).
-const CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+// v1.5.0 audit-LOW-obs-L2: per-tier cache-read savings rate.
+//
+// Anthropic prompt caching: a cached read costs ~10% of an uncached input
+// token. Savings are computed as (uncached_input_rate - cached_read_rate),
+// which collapses to (0.9 * input_rate) per cached-read token. Values are
+// derived from the canonical pricing table (mcp-server/src/cost/pricing.js).
+//
+// Default tier remains sonnet (matches the prior single-constant behaviour
+// and is the dominant model on the hero-line surface), but cache_stats
+// records that carry a `model` field now dispatch to the right rate.
+const SONNET_CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+const OPUS_CACHE_SAVINGS_PER_TOKEN   = 13.50 / 1_000_000;
+const HAIKU_CACHE_SAVINGS_PER_TOKEN  = 0.72 / 1_000_000;
+
+function cacheSavingsPerTokenFor(model) {
+  if (typeof model !== 'string' || !model) return SONNET_CACHE_SAVINGS_PER_TOKEN;
+  const m = model.toLowerCase();
+  if (m.includes('opus'))  return OPUS_CACHE_SAVINGS_PER_TOKEN;
+  if (m.includes('haiku')) return HAIKU_CACHE_SAVINGS_PER_TOKEN;
+  return SONNET_CACHE_SAVINGS_PER_TOKEN;
+}
 
 // renderReceipt(record, phaseWave?, stepNum?)
 //   phaseWave -- caller-supplied label for the narration header. Default is
@@ -101,7 +129,11 @@ export function renderReceipt(record, phaseWave = 'Trident', stepNum = 1) {
         lines.push(`Step ${stepNum}.4 -- cache created: ${cs.cache_creation_input_tokens} tokens`);
       }
       if (typeof cs.cache_read_input_tokens === 'number') {
-        const saved = cs.cache_read_input_tokens * CACHE_SAVINGS_PER_TOKEN;
+        // v1.5.0 audit-LOW-obs-L2: dispatch on cache_stats.model when set;
+        // fall back to receipt-level model; finally fall back to sonnet.
+        const modelForRate = cs.model || record.model || null;
+        const rate = cacheSavingsPerTokenFor(modelForRate);
+        const saved = cs.cache_read_input_tokens * rate;
         const savedStr = saved >= 0.01 ? ` (~$${saved.toFixed(2)} saved)` : '';
         lines.push(`Step ${stepNum}.5 -- cache read: ${cs.cache_read_input_tokens} tokens${savedStr}`);
       }

package/src/recovery/checkpoint.js

@@ -4,10 +4,15 @@
 // not a replacement for IJFW memory, but they make recovery possible when chat
 // context or a generated memory summary goes missing.
 
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { writeAtomic } from '../lib/atomic-io.js';
-import { appendBlackboardEvent, blackboardStatus, readBlackboard } from '../blackboard.js';
+import {
+  appendBlackboardEvent,
+  blackboardPaths,
+  blackboardStatus,
+  readBlackboard,
+} from '../blackboard.js';
 import { readTeamAssembly } from '../team/generator.js';
 import { buildSwarmPlan } from '../swarm/planner.js';
 
@@ -89,13 +94,43 @@ export function listCheckpoints(projectRoot = process.cwd()) {
     .map((file) => join(paths.dir, file));
 }
 
+// v1.5.0 audit-LOW-work-L2: memoise buildSnapshot per (projectRoot, ms).
+// Snapshot construction reads team + plan + blackboard, which are themselves
+// I/O-heavy reads. The bb mtime cache already shortcuts the inner reads, but
+// when a caller does back-to-back createCheckpoint() calls (e.g. on a wave
+// boundary) we still re-build the wrapper N times. Memo is keyed on the
+// project root + blackboard mtimes + ts so any state change invalidates;
+// hot-path cache size is capped at 8 entries to stay tiny.
+const SNAPSHOT_CACHE = new Map();
+const SNAPSHOT_CACHE_MAX = 8;
+
+function snapshotCacheKey(projectRoot, ts) {
+  const paths = blackboardPaths(projectRoot);
+  let tasksMtime = 0, claimsMtime = 0;
+  try { tasksMtime = statSync(paths.tasks).mtimeMs; } catch { /* default 0 */ }
+  try { claimsMtime = statSync(paths.claims).mtimeMs; } catch { /* default 0 */ }
+  return `${paths.root}::${ts}::${tasksMtime}::${claimsMtime}`;
+}
+
 function buildSnapshot(projectRoot, meta) {
+  const cacheKey = snapshotCacheKey(projectRoot, meta.ts);
+  const cached = SNAPSHOT_CACHE.get(cacheKey);
+  if (cached) {
+    // Cached body is independent of meta.id / meta.label / meta.message;
+    // those are reapplied from the current call.
+    return {
+      ...cached,
+      id: meta.id,
+      label: meta.label,
+      message: meta.message || null,
+    };
+  }
   const blackboard = readBlackboard(projectRoot);
   const team = readTeamAssembly(projectRoot);
   const plan = buildSwarmPlan(projectRoot);
   const status = blackboardStatus(projectRoot);
   const tasks = blackboard.tasks.data.tasks || [];
-  return {
+  const snapshot = {
     schema_version: 'ijfw-checkpoint/v1',
     id: meta.id,
     label: meta.label,
@@ -122,6 +157,24 @@ function buildSnapshot(projectRoot, meta) {
     recent: blackboard.recent,
     next: recommendedNext(team, plan, tasks),
   };
+  // Stash a meta-agnostic copy in the cache (id/label/message reapplied on hit).
+  SNAPSHOT_CACHE.set(cacheKey, {
+    ...snapshot,
+    id: null,
+    label: null,
+    message: null,
+  });
+  // Narrow LRU: cap the cache size and drop the oldest insertion when over.
+  if (SNAPSHOT_CACHE.size > SNAPSHOT_CACHE_MAX) {
+    const firstKey = SNAPSHOT_CACHE.keys().next().value;
+    if (firstKey !== undefined) SNAPSHOT_CACHE.delete(firstKey);
+  }
+  return snapshot;
+}
+
+// Exposed for tests / cache invalidation hooks.
+export function _resetSnapshotCache() {
+  SNAPSHOT_CACHE.clear();
 }
 
 function renderCheckpoint(snapshot) {