penthera 1.2.0 → 1.4.0

package/lib/install/policy.js

@@ -0,0 +1,117 @@
+/**
+ * `penthera.policy.json`: what an install may bring in without a human.
+ *
+ *   {
+ *     "allow": ["@acme/*", "esbuild", "sharp@0.33.5"],
+ *     "deny": ["ai-cli-invoke", "token-harvest"],
+ *     "requireApproval": ["install-scripts", "obfuscated", "typosquat"]
+ *   }
+ *
+ * `deny` and `requireApproval` list capability ids from lib/deps/capabilities.js,
+ * plus two of the firewall's own: `typosquat` (a new name close to a popular
+ * package) and `unscanned` (a new package whose files could not be read).
+ * `allow` lists package names or globs (`*` matches any run of characters),
+ * optionally pinned to one version with `@x.y.z`; an allowed package passes
+ * both lists. A field left out keeps its default; a field given replaces it.
+ * Everything here is pure: no files are read except the policy itself.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CAPABILITY_ORDER, CAPABILITIES } from "../deps/capabilities.js";
+
+export const POLICY_FILE = "penthera.policy.json";
+
+export const RULE_IDS = [...CAPABILITY_ORDER, "typosquat", "unscanned"];
+
+export const RULE_LABELS = {
+  ...Object.fromEntries(CAPABILITY_ORDER.map((id) => [id, CAPABILITIES[id].label])),
+  typosquat: "looks like a popular package",
+  unscanned: "could not be scanned",
+};
+
+export const DEFAULT_POLICY = Object.freeze({
+  allow: [],
+  deny: [],
+  requireApproval: ["install-scripts", "ai-config-write", "ai-cli-invoke", "token-harvest", "obfuscated", "typosquat", "unscanned"],
+});
+
+/**
+ * Validate and complete a policy object. Throws with a readable message on
+ * unknown fields, unknown rule ids, or non-string entries.
+ */
+export function normalizePolicy(raw, label = POLICY_FILE) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${label}: expected a JSON object`);
+  const known = ["allow", "deny", "requireApproval", "$schema", "description"];
+  const extra = Object.keys(raw).filter((k) => !known.includes(k));
+  if (extra.length) throw new Error(`${label}: unknown field(s) ${extra.join(", ")} (expected allow, deny, requireApproval)`);
+  const out = {};
+  for (const field of ["allow", "deny", "requireApproval"]) {
+    const v = raw[field] ?? DEFAULT_POLICY[field];
+    if (!Array.isArray(v) || v.some((x) => typeof x !== "string" || !x.trim())) {
+      throw new Error(`${label}: "${field}" must be an array of non-empty strings`);
+    }
+    out[field] = [...new Set(v.map((x) => x.trim()))];
+  }
+  for (const field of ["deny", "requireApproval"]) {
+    const bad = out[field].filter((id) => !RULE_IDS.includes(id));
+    if (bad.length) throw new Error(`${label}: unknown capability in "${field}": ${bad.join(", ")}. Known: ${RULE_IDS.join(", ")}`);
+  }
+  return out;
+}
+
+/**
+ * Load the policy: an explicit path, else penthera.policy.json in the project,
+ * else the defaults. Returns { policy, path } (path null for defaults).
+ */
+export function loadPolicy(root, explicitPath = null) {
+  const path = explicitPath || join(root, POLICY_FILE);
+  if (!existsSync(path)) {
+    if (explicitPath) throw new Error(`Policy file not found: ${explicitPath}`);
+    return { policy: normalizePolicy({}), path: null };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (e) {
+    throw new Error(`${path}: ${e.message}`);
+  }
+  return { policy: normalizePolicy(raw, path), path };
+}
+
+const escapeRe = (s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+
+/** Split "name@1.2.3" / "@scope/name@1.2.3" into { name, version }. */
+function splitEntry(entry) {
+  const at = entry.lastIndexOf("@");
+  if (at > 0) return { name: entry.slice(0, at), version: entry.slice(at + 1) };
+  return { name: entry, version: null };
+}
+
+/** The first allow entry matching name@version, or null. */
+export function matchAllow(allow, name, version) {
+  for (const entry of allow) {
+    const e = splitEntry(entry);
+    const re = new RegExp(`^${e.name.split("*").map(escapeRe).join(".*")}$`);
+    if (!re.test(name)) continue;
+    if (e.version && e.version !== "*" && e.version !== version) continue;
+    return entry;
+  }
+  return null;
+}
+
+/**
+ * Apply the policy to the changes an install would make.
+ * @param {{ name, version, flags: string[] }[]} changes flags: the rule ids this change raises
+ * @returns {{ items: object[], denied: object[], needsApproval: object[], clean: boolean }}
+ */
+export function evaluatePolicy(changes, policy) {
+  const items = changes.map((c) => {
+    const allowedBy = matchAllow(policy.allow, c.name, c.version);
+    const deny = allowedBy ? [] : c.flags.filter((id) => policy.deny.includes(id));
+    const approval = allowedBy ? [] : c.flags.filter((id) => policy.requireApproval.includes(id) && !deny.includes(id));
+    return { ...c, allowedBy, deny, approval };
+  });
+  const denied = items.filter((i) => i.deny.length);
+  const needsApproval = items.filter((i) => i.approval.length);
+  return { items, denied, needsApproval, clean: denied.length === 0 && needsApproval.length === 0 };
+}

package/lib/memory/history.js

@@ -0,0 +1,52 @@
+/**
+ * Report-side view over memory events: the scan trend (counts per scan) and
+ * the fix history per finding id (first seen → fix applied → verified or
+ * failed). Like views.js it only reads, and every field is type-checked.
+ */
+
+const MAX_STR = 500;
+const str = (x) => (typeof x === "string" && x.length > 0 && x.length <= MAX_STR ? x : null);
+const int = (x) => (Number.isInteger(x) && x >= 0 ? x : 0);
+const iso = (x) => (str(x) && !Number.isNaN(Date.parse(x)) ? x : null);
+
+/**
+ * @param {object[]} events  verified events from openMemory().events()
+ * @param {{ maxScans?: number }} opts  how many recent scans the trend keeps
+ * @returns {{ trend: object[], fixes: object[] }}
+ */
+export function buildHistory(events, { maxScans = 12 } = {}) {
+  const trend = [];
+  const fixes = new Map();
+  const fix = (id) => {
+    if (!fixes.has(id)) fixes.set(id, { id, firstSeen: null, applied: null, recipe: null, verified: null, failed: null });
+    return fixes.get(id);
+  };
+  const firstSeen = new Map();
+
+  for (const ev of events || []) {
+    const d = ev?.data;
+    const ts = iso(ev?.ts);
+    if (!d || typeof d !== "object" || !ts) continue;
+    if (ev.type === "scan") {
+      const c = d.counts && typeof d.counts === "object" ? d.counts : {};
+      trend.push({
+        ts, critical: int(c.critical), high: int(c.high), medium: int(c.medium), low: int(c.low),
+        total: int(c.total), suppressed: int(c.suppressed),
+      });
+      for (const id of Array.isArray(d.ids) ? d.ids : []) if (str(id) && !firstSeen.has(id)) firstSeen.set(id, ts);
+    } else if (ev.type === "fix_applied" || ev.type === "fix_verified" || ev.type === "fix_failed") {
+      const id = str(d.id);
+      if (!id) continue;
+      const f = fix(id);
+      if (ev.type === "fix_applied") {
+        f.applied = ts;
+        f.recipe = str(d.recipe) || f.recipe;
+        f.verified = null;
+        f.failed = null;
+      } else if (ev.type === "fix_verified") f.verified = ts;
+      else f.failed = ts;
+    }
+  }
+  for (const f of fixes.values()) f.firstSeen = firstSeen.get(f.id) || f.applied;
+  return { trend: trend.slice(-maxScans), fixes: [...fixes.values()] };
+}

package/lib/memory/index.js

@@ -0,0 +1,111 @@
+/**
+ * Local learning store (v1.4 "local loop", workstream W2). Public API:
+ *
+ *   openMemory(projectId)      -> { append(event), verify(), events(), forget() }
+ *   views(memory)              -> recipe success, suppressions, probe ranking, time-to-fix
+ *   rankFindings(findings, v)  -> same findings, re-ordered
+ *   isSuppressed(finding, v)   -> suppression record or null
+ *
+ * See docs/local-loop.md for the threat model.
+ */
+import { openMemory, projectIdFor, memoryRoot, forgetAll, EVENT_TYPES } from "./store.js";
+import { buildViews, rankFindings, isSuppressed, withRepoSuppressions, findingId } from "./views.js";
+import { loadRepoSuppressions, REPO_SUPPRESS_FILE } from "./repo-suppress.js";
+import { buildHistory } from "./history.js";
+
+export {
+  openMemory, projectIdFor, memoryRoot, forgetAll, EVENT_TYPES,
+  buildViews, rankFindings, isSuppressed, withRepoSuppressions, findingId,
+  loadRepoSuppressions, REPO_SUPPRESS_FILE, buildHistory,
+};
+
+/**
+ * Views for an opened memory. Returns null when the chain does not verify:
+ * a tampered log must not steer a scan, so callers fall back to no memory.
+ */
+export function views(memory, opts = {}) {
+  if (!memory.verify().ok) return null;
+  return buildViews(memory.events(), opts);
+}
+
+/** Lower-cased framework name for the scanned target, or "unknown". */
+export function detectStack(result) {
+  const fw = result?.fingerprint?.framework || result?.attackSurface?.find?.((r) => r?.framework)?.framework;
+  return typeof fw === "string" && fw ? fw.toLowerCase().slice(0, 64) : "unknown";
+}
+
+/** Findings per probe: executed probes count from 0, finding sources add to them. */
+export function probeYields(result) {
+  const counts = new Map();
+  for (const p of result?.executedProbes || []) if (typeof p === "string") counts.set(p, 0);
+  for (const f of result?.findings || []) {
+    const probe = typeof f.source === "string" && f.source ? f.source : "unknown";
+    counts.set(probe, (counts.get(probe) || 0) + 1);
+  }
+  return [...counts].map(([probe, findings]) => ({ probe, findings }));
+}
+
+/**
+ * The `--memory` scan hook. Mutates `merged`:
+ *   merged.findings   -> unsuppressed findings, ranked
+ *   merged.suppressed -> suppressed findings, each with .suppression { source, reason, actor }
+ *   merged.memory     -> { projectId, chain: "ok" | "broken", ... }
+ * then appends `scan` and `probe_yield` events. Returns { warnings }.
+ *
+ * Fail-closed: if the chain is broken, memory suppressions and ranking are not
+ * applied and nothing is appended (the repo file, which is labelled, still is).
+ */
+export function applyMemoryToScan(merged, { repo = null, url = null, now = new Date().toISOString(), root } = {}) {
+  const warnings = [];
+  const { id: projectId, label } = projectIdFor({ repo, url });
+  const mem = openMemory(projectId, { root, label, now: () => now });
+  const check = mem.verify();
+  const stack = detectStack(merged);
+
+  let v = { suppressions: [], recipeSuccess: [], seen: {} };
+  if (check.ok) {
+    v = buildViews(mem.events(), { now });
+  } else {
+    warnings.push(`memory chain broken at line ${check.brokenAt} (${check.reason}); memory not applied. Run \`penthera memory verify\`.`);
+  }
+
+  if (repo) {
+    const rs = loadRepoSuppressions(repo, { now });
+    warnings.push(...rs.warnings);
+    v = withRepoSuppressions(v, rs.entries);
+  }
+
+  const all = merged.findings || [];
+  const kept = [];
+  const suppressed = [];
+  for (const f of all) {
+    const fid = findingId(f);
+    const s = isSuppressed(f, v);
+    if (s) suppressed.push({ ...f, fid, suppression: { source: s.source, reason: s.reason, actor: s.actor, expires: s.expires || null } });
+    else kept.push({ ...f, fid });
+  }
+  merged.findings = check.ok ? rankFindings(kept, v, { framework: stack }) : kept;
+  merged.suppressed = suppressed;
+  merged.memory = { projectId, stack, chain: check.ok ? "ok" : "broken", events: check.count };
+
+  if (check.ok) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of all) if (counts[f.severity] != null) counts[f.severity]++;
+    mem.append({
+      type: "scan",
+      ts: now,
+      data: {
+        stack,
+        modes: merged.modes || (merged.mode ? [merged.mode] : []),
+        counts: { ...counts, total: all.length, suppressed: suppressed.length },
+        ids: all.filter((f) => f.severity !== "info").map(findingId),
+      },
+    });
+    for (const p of probeYields({ executedProbes: merged.executedProbes, findings: all })) {
+      mem.append({ type: "probe_yield", ts: now, data: { probe: p.probe, stack, findings: p.findings } });
+    }
+    merged.memory.events = mem.verify().count;
+    merged.memory.history = buildHistory(mem.events());
+  }
+  return { warnings, projectId };
+}

package/lib/memory/repo-suppress.js

@@ -0,0 +1,64 @@
+/**
+ * Optional repo file `penthera.suppress.json`. This is the ONLY thing Penthera
+ * reads from a scanned repo that changes what a report shows, so it is held to
+ * a strict, data-only shape and every effect is labelled in the report as
+ * "suppressed by repo file" with its reason. A PR that adds an entry is visible
+ * in review, and so is the suppressed finding in the report.
+ *
+ *   {
+ *     "version": 1,
+ *     "suppress": [
+ *       { "id": "3f9a0c1d2b4e5f60", "reason": "test fixture key", "expires": "2027-01-01" },
+ *       { "fingerprint": "repo-secret|secret|...|...", "reason": "..." }
+ *     ]
+ *   }
+ */
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const REPO_SUPPRESS_FILE = "penthera.suppress.json";
+const MAX_BYTES = 64 * 1024;
+const MAX_ENTRIES = 500;
+
+/**
+ * Load and validate the repo file. Returns { entries, warnings }. Invalid
+ * entries are dropped with a warning, never guessed at.
+ */
+export function loadRepoSuppressions(repoPath, { now = new Date().toISOString() } = {}) {
+  const warnings = [];
+  const path = join(repoPath, REPO_SUPPRESS_FILE);
+  if (!existsSync(path)) return { entries: [], warnings, path: null };
+  const st = statSync(path);
+  if (!st.isFile()) return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is not a regular file, ignored`], path };
+  if (st.size > MAX_BYTES) return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is larger than 64 KB, ignored`], path };
+
+  let doc;
+  try { doc = JSON.parse(readFileSync(path, "utf-8")); } catch (e) {
+    return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} is not valid JSON (${e.message}), ignored`], path };
+  }
+  if (!doc || typeof doc !== "object" || doc.version !== 1 || !Array.isArray(doc.suppress)) {
+    return { entries: [], warnings: [`${REPO_SUPPRESS_FILE} needs { "version": 1, "suppress": [...] }, ignored`], path };
+  }
+
+  const nowMs = Date.parse(now);
+  const entries = [];
+  doc.suppress.slice(0, MAX_ENTRIES).forEach((e, i) => {
+    const where = `${REPO_SUPPRESS_FILE} entry ${i + 1}`;
+    if (!e || typeof e !== "object") { warnings.push(`${where}: not an object, ignored`); return; }
+    const id = typeof e.id === "string" && /^[0-9a-f]{16}$/.test(e.id) ? e.id : null;
+    const fingerprint = typeof e.fingerprint === "string" && e.fingerprint.length <= 2000 ? e.fingerprint : null;
+    if (!id && !fingerprint) { warnings.push(`${where}: needs "id" (16 hex chars) or "fingerprint", ignored`); return; }
+    const reason = typeof e.reason === "string" ? e.reason.trim() : "";
+    if (!reason || reason.length > 500) { warnings.push(`${where}: needs a "reason" (1-500 chars), ignored`); return; }
+    let expires = null;
+    if (e.expires != null) {
+      const t = Date.parse(e.expires);
+      if (typeof e.expires !== "string" || Number.isNaN(t)) { warnings.push(`${where}: "expires" is not a date, ignored`); return; }
+      if (t <= nowMs) { warnings.push(`${where}: expired on ${e.expires}, not applied`); return; }
+      expires = e.expires;
+    }
+    entries.push({ id, fingerprint, reason, expires, actor: "repo" });
+  });
+  if (doc.suppress.length > MAX_ENTRIES) warnings.push(`${REPO_SUPPRESS_FILE}: only the first ${MAX_ENTRIES} entries are read`);
+  return { entries, warnings, path };
+}

package/lib/memory/store.js

@@ -0,0 +1,325 @@
+/**
+ * Local learning store: an append-only, hash-chained event log per project.
+ *
+ *   ~/.penthera/memory/<project-id>/events.jsonl   one event per line
+ *   ~/.penthera/memory/<project-id>/head.json      { count, hash } of the tip
+ *   ~/.penthera/memory/<project-id>/meta.json      human label for `memory show`
+ *
+ * Each line is { v, ts, type, data, prev, hash } with
+ *   hash = sha256(prev + canonicalJson({ v, ts, type, data }))
+ * and the first event's prev bound to the project id, so a log copied from
+ * another project does not verify either.
+ *
+ * Safety rules (see docs/local-loop.md):
+ * - Memory is data. Nothing read from it is executed, evaluated, imported, or
+ *   used as a file path or shell command. Views only re-order and suppress.
+ * - Memory lives under the user's home (or PENTHERA_HOME), never in the
+ *   scanned repo, so a repo cannot ship pre-poisoned memory.
+ * - Writes take an exclusive lock file, then append one line with a single
+ *   O_APPEND write, so concurrent scans neither interleave nor fork the chain.
+ */
+import { createHash } from "node:crypto";
+import {
+  openSync, writeSync, closeSync, readFileSync, writeFileSync, renameSync,
+  mkdirSync, existsSync, rmSync, statSync, unlinkSync, constants as FS,
+} from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+
+export const EVENT_VERSION = 1;
+export const EVENT_TYPES = Object.freeze([
+  "scan", "fix_applied", "fix_verified", "fix_failed", "fp_suppressed", "probe_yield", "loop_run",
+]);
+const MAX_LINE_BYTES = 256 * 1024;
+const LOCK_STALE_MS = 30_000;
+const LOCK_TIMEOUT_MS = 10_000;
+
+export function sha256(s) {
+  return createHash("sha256").update(s).digest("hex");
+}
+
+/**
+ * Deterministic JSON: object keys sorted, no whitespace. Only plain JSON values
+ * are accepted (no functions, symbols, undefined, NaN, class instances), so the
+ * same event always hashes the same way.
+ */
+export function canonicalJson(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string": return JSON.stringify(value);
+    case "boolean": return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) throw new TypeError("canonicalJson: non-finite number");
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new TypeError("canonicalJson: only plain objects are allowed");
+      }
+      const keys = Object.keys(value).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    }
+    default:
+      throw new TypeError(`canonicalJson: unsupported type ${typeof value}`);
+  }
+}
+
+export function hashEvent(prev, { v, ts, type, data }) {
+  return sha256(prev + canonicalJson({ v, ts, type, data }));
+}
+
+/** The chain's genesis value: binds line 1 to this project. */
+export function genesisHash(projectId) {
+  return sha256(`penthera-memory-v1:${projectId}`);
+}
+
+/** Memory root: $PENTHERA_HOME/memory, else ~/.penthera/memory. */
+export function memoryRoot(env = process.env) {
+  const base = env.PENTHERA_HOME ? resolve(env.PENTHERA_HOME) : join(homedir(), ".penthera");
+  return join(base, "memory");
+}
+
+/** Remove credentials from a URL-ish string before it is hashed or shown. */
+export function stripCredentials(u) {
+  const s = String(u || "").trim();
+  try {
+    const url = new URL(s);
+    url.username = "";
+    url.password = "";
+    return url.toString();
+  } catch {
+    return s.replace(/\/\/[^@/]+@/, "//"); // scp-like or odd remotes
+  }
+}
+
+/**
+ * Read the origin remote URL from .git/config without running git. Running git
+ * inside an untrusted repo can execute its hooks or core.fsmonitor, so we parse
+ * the config text ourselves. Worktrees (.git is a file) follow gitdir/commondir.
+ */
+export function readGitRemote(repoPath) {
+  try {
+    let gitDir = join(repoPath, ".git");
+    if (!existsSync(gitDir)) return null;
+    if (statSync(gitDir).isFile()) {
+      const m = readFileSync(gitDir, "utf-8").match(/^gitdir:\s*(.+)$/m);
+      if (!m) return null;
+      gitDir = resolve(repoPath, m[1].trim());
+      const common = join(gitDir, "commondir");
+      if (existsSync(common)) gitDir = resolve(gitDir, readFileSync(common, "utf-8").trim());
+    }
+    const cfg = readFileSync(join(gitDir, "config"), "utf-8");
+    let section = null;
+    let first = null;
+    for (const raw of cfg.split(/\r?\n/)) {
+      const line = raw.trim();
+      const sec = line.match(/^\[\s*remote\s+"([^"]+)"\s*\]$/);
+      if (sec) { section = sec[1]; continue; }
+      if (line.startsWith("[")) { section = null; continue; }
+      const kv = section && line.match(/^url\s*=\s*(.+)$/);
+      if (kv) {
+        if (section === "origin") return stripCredentials(kv[1]);
+        first ??= stripCredentials(kv[1]);
+      }
+    }
+    return first;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Project id: sha256 of the repo's absolute path + git remote, or of the
+ * target origin for URL-only scans. Returns { id, label }.
+ */
+export function projectIdFor({ repo, url } = {}) {
+  if (repo) {
+    const abs = resolve(repo);
+    const remote = readGitRemote(abs) || "";
+    return { id: sha256(`repo\n${abs}\n${remote}`), label: remote ? `${abs} (${remote})` : abs };
+  }
+  if (url) {
+    const origin = new URL(stripCredentials(url)).origin;
+    return { id: sha256(`url\n${origin}`), label: origin };
+  }
+  throw new Error("projectIdFor: need a repo path or a URL");
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function withLock(dir, fn) {
+  const lock = join(dir, "events.lock");
+  const started = Date.now();
+  let fd;
+  for (;;) {
+    try {
+      fd = openSync(lock, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY, 0o600);
+      break;
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { unlinkSync(lock); continue; }
+      } catch { continue; } // lock vanished between calls: retry
+      if (Date.now() - started > LOCK_TIMEOUT_MS) throw new Error(`memory: lock busy (${lock})`);
+      sleepMs(5 + Math.floor(Math.random() * 20));
+    }
+  }
+  try {
+    writeSync(fd, String(process.pid));
+    return fn();
+  } finally {
+    closeSync(fd);
+    try { unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf-8")); } catch { return null; }
+}
+
+function writeJsonAtomic(path, obj) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** Split the log into lines, keeping a trailing partial line visible to verify(). */
+function readLines(file) {
+  if (!existsSync(file)) return [];
+  const text = readFileSync(file, "utf-8");
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+function isPlainObject(x) {
+  return x !== null && typeof x === "object" && !Array.isArray(x)
+    && (Object.getPrototypeOf(x) === Object.prototype || Object.getPrototypeOf(x) === null);
+}
+
+/** Walk a list of raw lines and check every link. */
+export function verifyLines(lines, projectId) {
+  let prev = genesisHash(projectId);
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    let ev;
+    try { ev = JSON.parse(lines[i]); } catch {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "line is not valid JSON" };
+    }
+    if (!isPlainObject(ev) || ev.v !== EVENT_VERSION || typeof ev.ts !== "string"
+      || !EVENT_TYPES.includes(ev.type) || !isPlainObject(ev.data)
+      || typeof ev.prev !== "string" || typeof ev.hash !== "string") {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "malformed event" };
+    }
+    if (ev.prev !== prev) {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "prev does not match the previous line's hash (line removed, reordered, or inserted)" };
+    }
+    let expect;
+    try { expect = hashEvent(prev, ev); } catch {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "event is not canonical JSON" };
+    }
+    if (ev.hash !== expect) {
+      return { ok: false, count: i, brokenAt: lineNo, reason: "hash mismatch (line edited)" };
+    }
+    prev = ev.hash;
+  }
+  return { ok: true, count: lines.length, tip: prev };
+}
+
+/**
+ * Open (lazily create) the memory for a project. Nothing touches disk until the
+ * first append, so read-only commands on an unknown project leave no trace.
+ */
+export function openMemory(projectId, { root = memoryRoot(), label = null, now = () => new Date().toISOString() } = {}) {
+  if (!/^[0-9a-f]{64}$/.test(String(projectId))) throw new Error("openMemory: project id must be a sha256 hex string");
+  const dir = join(root, projectId);
+  const file = join(dir, "events.jsonl");
+  const headFile = join(dir, "head.json");
+  const metaFile = join(dir, "meta.json");
+
+  function ensureDir() {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeJsonAtomic(metaFile, { projectId, label, createdAt: now() });
+    }
+  }
+
+  /** Validated, parsed events (only call after verify() says ok). */
+  function events() {
+    return readLines(file).map((l) => JSON.parse(l));
+  }
+
+  function verify() {
+    const lines = readLines(file);
+    const res = verifyLines(lines, projectId);
+    if (!res.ok) return res;
+    // The chain alone cannot see the tail being cut off; head.json can.
+    const head = readJson(headFile);
+    if (lines.length === 0) {
+      if (head && head.count > 0) return { ok: false, count: 0, brokenAt: 1, reason: `log is empty but head.json records ${head.count} events (lines deleted)` };
+      return res;
+    }
+    if (!head || !Number.isInteger(head.count) || head.count < 1 || typeof head.hash !== "string") {
+      return { ok: false, count: lines.length, brokenAt: lines.length, reason: "head.json missing or malformed" };
+    }
+    if (head.count > lines.length) {
+      return { ok: false, count: lines.length, brokenAt: lines.length + 1, reason: `head.json records ${head.count} events, log has ${lines.length} (lines deleted from the end)` };
+    }
+    const atHead = JSON.parse(lines[head.count - 1]).hash;
+    if (atHead !== head.hash) {
+      return { ok: false, count: lines.length, brokenAt: head.count, reason: "head.json hash does not match the log (log rewritten)" };
+    }
+    return { ...res, headStale: head.count < lines.length };
+  }
+
+  /**
+   * Append one event. `event` is { type, data, ts? }. Returns the stored line
+   * object. Refuses unknown types, non-plain data, and oversized lines.
+   */
+  function append(event) {
+    const type = event?.type;
+    if (!EVENT_TYPES.includes(type)) throw new Error(`memory: unknown event type "${type}"`);
+    const data = event.data ?? {};
+    if (!isPlainObject(data)) throw new Error("memory: event data must be a plain object");
+    const ts = typeof event.ts === "string" ? event.ts : now();
+    canonicalJson(data); // throws on anything that is not plain JSON
+    ensureDir();
+    return withLock(dir, () => {
+      const lines = readLines(file);
+      const prev = lines.length ? JSON.parse(lines[lines.length - 1]).hash : genesisHash(projectId);
+      const body = { v: EVENT_VERSION, ts, type, data };
+      const rec = { ...body, prev, hash: hashEvent(prev, body) };
+      const line = JSON.stringify(rec) + "\n";
+      if (Buffer.byteLength(line) > MAX_LINE_BYTES) throw new Error("memory: event too large");
+      const fd = openSync(file, FS.O_CREAT | FS.O_APPEND | FS.O_WRONLY, 0o600);
+      try { writeSync(fd, line); } finally { closeSync(fd); }
+      writeJsonAtomic(headFile, { count: lines.length + 1, hash: rec.hash });
+      return rec;
+    });
+  }
+
+  function meta() {
+    return readJson(metaFile);
+  }
+
+  /** Delete this project's memory. */
+  function forget() {
+    const existed = existsSync(dir);
+    rmSync(dir, { recursive: true, force: true });
+    return existed;
+  }
+
+  return { projectId, dir, file, append, verify, events, meta, forget, exists: () => existsSync(file) };
+}
+
+/** Delete every project's memory under the root. */
+export function forgetAll({ root = memoryRoot() } = {}) {
+  const existed = existsSync(root);
+  // Only ever remove the memory/ directory itself, never its parent.
+  if (dirname(root) === root) throw new Error("refusing to remove a filesystem root");
+  rmSync(root, { recursive: true, force: true });
+  return existed;
+}