nexakit 0.0.0-stage → 0.2.0

package/src/memory-connection-toml.js

@@ -0,0 +1,153 @@
+import { createHash } from "node:crypto";
+import { parseTOML } from "toml-eslint-parser";
+
+import { copyBytes, copyInertJson, decode } from "./client-output-json.js";
+import {
+  MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION, freezeMemoryConnectionData
+} from "./memory-connection-descriptor.js";
+import { containsSensitiveData } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_TOML_LIMITS = Object.freeze({
+  inputBytes: 1048576, astNodes: 30000, astDepth: 64,
+  stringBytes: 4096, args: 16, tools: 256, reportBytes: 65536
+});
+const FIELDS = new Set(["command", "args", "cwd", "enabled_tools", "enabled"]);
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+class Rejected extends Error {
+  constructor(code, state = "blocked") { super(code); this.code = code; this.state = state; }
+}
+const reject = (code, state) => { throw new Rejected(code, state); };
+const keys = (key) => key.keys.map((part) => part.type === "TOMLBare" ? part.name : part.value);
+
+// Traverse semantic nodes, not cyclic parent links, token text or comments.
+// These bounds apply AFTER parsing; they do not sandbox the parser itself.
+function boundAst(ast) {
+  const stack = [[ast, 0]]; let count = 0;
+  while (stack.length) {
+    const [node, depth] = stack.pop();
+    if (++count > MEMORY_CONNECTION_TOML_LIMITS.astNodes || depth > MEMORY_CONNECTION_TOML_LIMITS.astDepth) {
+      reject("MC_TOML_AST_LIMIT");
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (["parent", "tokens", "comments", "loc", "range"].includes(key)) continue;
+      if (Array.isArray(value)) {
+        for (const child of value) if (child && typeof child === "object" && typeof child.type === "string") {
+          stack.push([child, depth + 1]);
+        }
+      } else if (value && typeof value === "object" && typeof value.type === "string") {
+        stack.push([value, depth + 1]);
+      }
+    }
+  }
+}
+
+function ownTable(ast, name) {
+  const matches = [];
+  for (const item of ast.body[0].body) {
+    if (item.type === "TOMLKeyValue") {
+      const path = keys(item.key);
+      if (path[0] !== "mcp_servers") continue;
+      // A sealed inline/scalar namespace cannot safely accept a future table.
+      if (path.length === 1) reject("MC_TOML_NAMESPACE");
+      if (path[1] === name) reject("MC_TOML_LAYOUT");
+      continue;
+    }
+    if (item.type !== "TOMLTable" || item.resolvedKey[0] !== "mcp_servers") continue;
+    const path = item.resolvedKey;
+    if (typeof path[1] === "number") reject("MC_TOML_NAMESPACE");
+    if (path.length === 1) {
+      if (item.body.some((field) => keys(field.key)[0] === name)) reject("MC_TOML_LAYOUT");
+    } else if (path[1] === name) {
+      if (path.length !== 2 || item.kind !== "standard") reject("MC_TOML_LAYOUT");
+      matches.push(item);
+    }
+  }
+  if (matches.length > 1) reject("MC_TOML_LAYOUT");
+  return matches[0] ?? null;
+}
+
+function textValue(node) {
+  if (node.type !== "TOMLValue" || node.kind !== "string" || typeof node.value !== "string") {
+    reject("MC_TOML_FIELD_TYPE");
+  }
+  const value = node.value;
+  if (Buffer.byteLength(value) > MEMORY_CONNECTION_TOML_LIMITS.stringBytes) reject("MC_TOML_STRING_LIMIT");
+  if (Buffer.from(value, "utf8").toString("utf8") !== value || CONTROL.test(value)) reject("MC_TOML_FIELD_VALUE");
+  if (containsSensitiveData(value)) reject("MC_TOML_SENSITIVE");
+  return value;
+}
+
+function fieldValue(name, node) {
+  if (name === "enabled") {
+    if (node.type !== "TOMLValue" || node.kind !== "boolean" || typeof node.value !== "boolean") {
+      reject("MC_TOML_FIELD_TYPE");
+    }
+    return node.value;
+  }
+  if (name === "args" || name === "enabled_tools") {
+    if (node.type !== "TOMLArray") reject("MC_TOML_FIELD_TYPE");
+    if (node.elements.length > MEMORY_CONNECTION_TOML_LIMITS[name === "args" ? "args" : "tools"]) {
+      reject("MC_TOML_ARRAY_LIMIT");
+    }
+    return node.elements.map(textValue);
+  }
+  return textValue(node);
+}
+
+/**
+ * Inspect caller-provided TOML bytes for one explicit standard MCP table.
+ * No file discovery, reads, writes, client launch or public CLI integration.
+ * Hash/ranges attest these bytes only, never their origin or a live connection.
+ */
+export function readMemoryConnectionToml(input, options) {
+  let mcpName = null, configurationSha256 = null, byteSyntaxVerified = false;
+  const report = (state, server = null, ranges = null, reasons = []) => {
+    const result = {
+      schemaVersion: MEMORY_CONNECTION_VERSION, state, mcpName, configurationSha256,
+      server, ranges, reasons,
+      facts: { ...MEMORY_CONNECTION_FACTS, evidence: "provided-bytes", byteSyntaxVerified,
+        configurationSourceVerified: false }
+    };
+    if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_TOML_LIMITS.reportBytes) {
+      reject("MC_TOML_REPORT_LIMIT");
+    }
+    return freezeMemoryConnectionData(result);
+  };
+  try {
+    let opts;
+    try { opts = copyInertJson(options); } catch { reject("MC_TOML_OPTIONS", "invalid"); }
+    if (!opts || Array.isArray(opts) || Object.keys(opts).length !== 1 || !Object.hasOwn(opts, "mcpName") ||
+        typeof opts.mcpName !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(opts.mcpName) ||
+        ["constructor", "prototype", "__proto__"].includes(opts.mcpName)) reject("MC_TOML_OPTIONS", "invalid");
+    mcpName = opts.mcpName;
+    let bytes;
+    try { bytes = copyBytes(input, MEMORY_CONNECTION_TOML_LIMITS.inputBytes); }
+    catch (error) {
+      reject(error?.code === "byte-limit" ? "MC_TOML_INPUT_LIMIT" : "MC_TOML_BYTES", "invalid");
+    }
+    configurationSha256 = createHash("sha256").update(bytes).digest("hex");
+    let source;
+    try { source = decode(bytes); } catch { reject("MC_TOML_UTF8", "invalid"); }
+    if (source.startsWith("\ufeff")) reject("MC_TOML_BOM", "invalid");
+    let ast;
+    try { ast = parseTOML(source, { tomlVersion: "1.0.0" }); }
+    catch { reject("MC_TOML_SYNTAX", "invalid"); }
+    byteSyntaxVerified = true;
+    boundAst(ast);
+    const table = ownTable(ast, mcpName);
+    if (!table) return report("absent");
+    const server = {}, fields = {};
+    for (const field of table.body) {
+      const path = keys(field.key);
+      if (path.length !== 1 || !FIELDS.has(path[0])) reject("MC_TOML_FIELD");
+      const name = path[0];
+      server[name] = fieldValue(name, field.value);
+      fields[name] = { key: [...field.key.range], value: [...field.value.range] };
+    }
+    return report("observed", server, { table: [...table.range], fields });
+  } catch (error) {
+    // Never return parser diagnostics, arbitrary exception messages or source.
+    return report(error instanceof Rejected ? error.state : "invalid", null, null,
+      [error instanceof Rejected ? error.code : "MC_TOML_INVALID"]);
+  }
+}

package/src/memory-locator.js

@@ -0,0 +1,118 @@
+// Finds the project memories this person already has, from the memory MCP servers registered in Claude Code, Codex
+// and Antigravity, so a repository reuses its memory and a new one goes next to the others. Read-only. No new
+// registry: the clients' own configuration is the source of truth.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getStaticTOMLValue, parseTOML } from 'toml-eslint-parser';
+
+const MAX_CONFIG_BYTES = 2 * 1024 * 1024;
+const MAX_MANIFEST_BYTES = 512 * 1024;
+const CLIENT_ORDER = ['claude', 'codex', 'antigravity'];
+const FILESYSTEM_PACKAGE = /^@modelcontextprotocol\/server-filesystem(?:@[^/]+)?$/u;
+const MEMORY_SCRIPT = 'project-memory-mcp.js';
+
+async function readBounded(file, maxBytes) {
+  try {
+    const info = await fs.lstat(file);
+    if (!info.isFile() || info.size > maxBytes) return null;
+    return await fs.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function serversOf(client, { homeDirectory, codexHome }) {
+  try {
+    if (client === 'claude') {
+      const config = JSON.parse(await readBounded(path.join(homeDirectory, '.claude.json'), MAX_CONFIG_BYTES) ?? 'null');
+      const projects = Object.values(config?.projects ?? {}).map(project => project?.mcpServers ?? {});
+      return [config?.mcpServers ?? {}, ...projects].flatMap(Object.entries);
+    }
+    if (client === 'codex') {
+      const text = await readBounded(path.join(codexHome, 'config.toml'), MAX_CONFIG_BYTES);
+      return text ? Object.entries(getStaticTOMLValue(parseTOML(text, { tomlVersion: '1.0.0' }))?.mcp_servers ?? {}) : [];
+    }
+    const config = JSON.parse(await readBounded(path.join(homeDirectory, '.gemini', 'config', 'mcp_config.json'), MAX_CONFIG_BYTES) ?? 'null');
+    return Object.entries(config?.mcpServers ?? {});
+  } catch {
+    return []; // An unreadable configuration means no known memories from that client, never an error.
+  }
+}
+
+// The manifest a server points at: the last argument of server-filesystem, or the --manifest of project-memory-mcp.
+function manifestCandidate(server) {
+  const args = Array.isArray(server?.args) ? server.args.filter(arg => typeof arg === 'string') : [];
+  const script = args.findIndex(arg => arg.replaceAll('\\', '/').endsWith(`/${MEMORY_SCRIPT}`));
+  if (script >= 0 && args[script + 1] === '--manifest' && path.isAbsolute(args[script + 2] ?? '')) return args[script + 2];
+  if (args.some(arg => FILESYSTEM_PACKAGE.test(arg))) {
+    const last = args.at(-1);
+    if (last && path.isAbsolute(last)) return path.join(last, 'project-memory.json');
+  }
+  return null;
+}
+
+async function readManifest(manifestPath) {
+  const text = await readBounded(manifestPath, MAX_MANIFEST_BYTES); // lstat: a linked manifest is not accepted.
+  if (text === null) return null;
+  try {
+    const manifest = JSON.parse(text);
+    const id = manifest?.project?.id;
+    const repositoryPath = manifest?.source?.repositoryPath;
+    if (typeof id !== 'string' || typeof repositoryPath !== 'string') return null;
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+// Every MCP server name registered in each agent, with the vault it serves when it is a memory (else null).
+export async function registeredServers({ homeDirectory, codexHome = path.join(homeDirectory, '.codex') } = {}) {
+  const result = {};
+  for (const client of CLIENT_ORDER) {
+    result[client] = {};
+    for (const [name, server] of await serversOf(client, { homeDirectory, codexHome })) {
+      const candidate = manifestCandidate(server);
+      const vault = candidate ? await fs.realpath(path.dirname(candidate)).catch(() => null) : null;
+      const kind = !candidate ? null : (server.args ?? []).some(arg => typeof arg === 'string' && arg.replaceAll('\\', '/').endsWith(`/${MEMORY_SCRIPT}`)) ? 'guard' : 'filesystem';
+      result[client][name] = vault && { vault, kind };
+    }
+  }
+  return result;
+}
+
+export async function findKnownMemories({ homeDirectory, codexHome = path.join(homeDirectory, '.codex') } = {}) {
+  const byVault = new Map();
+  for (const client of CLIENT_ORDER) {
+    for (const [name, server] of await serversOf(client, { homeDirectory, codexHome })) {
+      const candidate = manifestCandidate(server);
+      if (!candidate) continue;
+      const manifest = await readManifest(candidate);
+      if (!manifest) continue;
+      const vaultPath = await fs.realpath(path.dirname(candidate)).catch(() => null);
+      if (!vaultPath) continue;
+      const entry = byVault.get(vaultPath) ?? {
+        vaultPath,
+        manifestPath: path.join(vaultPath, 'project-memory.json'),
+        projectId: manifest.project.id,
+        repositoryPath: manifest.source.repositoryPath,
+        mcpName: typeof manifest.memory?.mcpServerName === 'string' ? manifest.memory.mcpServerName : name,
+        clients: []
+      };
+      if (!entry.clients.includes(client)) entry.clients.push(client);
+      byVault.set(vaultPath, entry);
+    }
+  }
+  return [...byVault.values()].sort((a, b) => (a.vaultPath < b.vaultPath ? -1 : a.vaultPath > b.vaultPath ? 1 : 0));
+}
+
+export function memoryForRepository(known, root) {
+  return known.find(entry => path.resolve(entry.repositoryPath) === path.resolve(root)) ?? null;
+}
+
+// Next to the memories already known when they share one parent folder; otherwise a folder of its own.
+export function suggestMemoryLocation(known, { id, homeDirectory }) {
+  const parents = [...new Set(known.map(entry => path.dirname(entry.vaultPath)))];
+  return parents.length === 1
+    ? path.join(parents[0], `${id.toUpperCase()}-MEMORY`)
+    : path.join(homeDirectory, 'nexakit-memorias', id);
+}

package/src/memory-mcp-policy.js

@@ -0,0 +1,181 @@
+import { IS_WINDOWS, warnPlatformPermissions, toGitPath } from './platform.js';
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import { parseTaskDocument } from "./task-prepare-files.js";
+import { containsSensitiveData, isCredentialPath } from "./sensitive-data.js";
+
+export const MEMORY_READ_TOOLS = Object.freeze([
+  "read_text_file", "read_media_file", "read_multiple_files", "list_directory",
+  "list_directory_with_sizes", "directory_tree", "search_files", "get_file_info",
+  "list_allowed_directories"
+]);
+export const MEMORY_MCP_LIMITS = Object.freeze({
+  requestBytes: 1024 * 1024, responseBytes: 16 * 1024 * 1024,
+  fileBytes: 8 * 1024 * 1024, totalBytes: 12 * 1024 * 1024,
+  files: 100, pathChars: 4096, timeoutMs: 10000, manifestBytes: 512 * 1024
+});
+export class MemoryMcpError extends Error {
+  constructor(code, fatal = false) { super(code); this.code = code; this.fatal = fatal; }
+}
+const fail = (code, fatal = false) => { throw new MemoryMcpError(code, fatal); };
+const control = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const forbidden = input => { const value = toGitPath(input); return isCredentialPath(value) ||
+  /(?:^|\/)(?:\.git|\.obsidian|\.codex|\.claude|\.gemini|\.agents|\.secrets|\.credentials|\.npmrc|\.netrc|\.envrc)(?:\/|$)/i.test(value) || /\.(?:keychain(?:-db)?|kdbx)$/i.test(value); };
+const globCase = value => value.replace(/[a-z]/g, c => `[${c}${c.toUpperCase()}]`);
+const recursiveExclusions = Object.freeze([
+  ".git", ".obsidian", ".codex", ".claude", ".gemini", ".agents", ".secrets", ".credentials",
+  ".env", ".env.*", ".envrc", ".npmrc", ".netrc", "secret", "secrets", "credential", "credentials", "id_rsa", "id_ed25519"
+].flatMap(name => [`**/${globCase(name)}`, `**/${globCase(name)}/**`]).concat(
+  ["pem", "key", "p12", "pfx", "keychain", "keychain-db", "kdbx"].map(ext => `**/*.${globCase(ext)}`)));
+const text = { type: "string", minLength: 1, maxLength: MEMORY_MCP_LIMITS.pathChars };
+const list = { type: "array", maxItems: MEMORY_MCP_LIMITS.files, items: text };
+const object = (properties, required = []) => ({ type: "object", additionalProperties: false, properties, required });
+export const MEMORY_TOOL_SCHEMAS = Object.freeze({
+  read_text_file: object({ path: text, head: { type: "integer", minimum: 1 }, tail: { type: "integer", minimum: 1 } }, ["path"]),
+  read_media_file: object({ path: text }, ["path"]),
+  read_multiple_files: object({ paths: { ...list, minItems: 1 } }, ["paths"]),
+  list_directory: object({ path: text }, ["path"]),
+  list_directory_with_sizes: object({ path: text, sortBy: { enum: ["name", "size"] } }, ["path"]),
+  directory_tree: object({ path: text, excludePatterns: list }, ["path"]),
+  search_files: object({ path: text, pattern: text, excludePatterns: list }, ["path", "pattern"]),
+  get_file_info: object({ path: text }, ["path"]),
+  list_allowed_directories: object({})
+});
+const ajv = new Ajv2020({ strict: true, allErrors: true, ownProperties: true });
+const inputs = new Map(MEMORY_READ_TOOLS.map(name => [name, ajv.compile(MEMORY_TOOL_SCHEMAS[name])]));
+let manifestValidator;
+const getManifestValidator = () => manifestValidator ??= fs.readFile(new URL("../schemas/project-memory.schema.json", import.meta.url), "utf8")
+  .then(JSON.parse).then(schema => ajv.compile(schema));
+const identity = s => JSON.stringify([s.dev, s.ino, s.uid, s.mode]);
+const fileIdentity = s => JSON.stringify([s.dev, s.ino, s.uid, s.mode, s.nlink, s.size, s.mtimeMs, s.ctimeMs]);
+const inside = (root, target) => { const rel = path.relative(root, target); return rel === "" || (!path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep)); };
+const canonical = value => typeof value === "string" && value.length > 0 && value.length <= MEMORY_MCP_LIMITS.pathChars &&
+  value === value.trim() && !control.test(value) && (!IS_WINDOWS || !value.slice(path.parse(value).root.length).includes(':') && !/^\\\\[?.]\\/u.test(value)) && path.isAbsolute(value) && path.normalize(value) === value &&
+  value.split(path.sep).every(part => part !== "." && part !== "..");
+
+async function physical(io, full) {
+  let current = path.parse(full).root, last;
+  const parts = full.slice(current.length).split(path.sep).filter(Boolean);
+  if (!parts.length || parts.length > 64) fail("RG_PATH_DENIED");
+  for (const [i, part] of parts.entries()) {
+    current = path.join(current, part); last = await io.lstat(current);
+    if (last.isSymbolicLink() || i < parts.length - 1 && !last.isDirectory()) fail("RG_PATH_DENIED");
+  }
+  return last;
+}
+function safe(s, uid, directory) {
+  if ((!IS_WINDOWS && (s.uid !== uid || (s.mode & 0o7022))) || s.isSymbolicLink() ||
+    (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1)) fail("RG_PATH_DENIED");
+}
+
+/** The only file content read here is the explicitly supplied manifest. */
+export async function loadMemoryPolicy(manifestPath, context = {}) {
+  const io = { ...fs, ...context.io }, uid = context.uid ?? process.getuid?.();
+  const platform = context.platform ?? process.platform;
+  if (!["darwin", "linux", "win32"].includes(platform) || platform !== "win32" && typeof uid !== "number") fail("RG_PLATFORM_UNSUPPORTED");
+  warnPlatformPermissions();
+  if (!canonical(manifestPath) || forbidden(manifestPath)) fail("RG_MANIFEST_INVALID");
+  let manifest;
+  try {
+    const before = await physical(io, manifestPath); safe(before, uid, false);
+    if (!before.size || before.size > MEMORY_MCP_LIMITS.manifestBytes) fail("RG_MANIFEST_INVALID");
+    const handle = await io.open(manifestPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      if (fileIdentity(await handle.stat()) !== fileIdentity(before)) fail("RG_MANIFEST_INVALID");
+      const bytes = Buffer.alloc(before.size); let offset = 0;
+      while (offset < bytes.length) {
+        const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (!Number.isSafeInteger(bytesRead) || bytesRead <= 0 || bytesRead > bytes.length - offset) fail("RG_MANIFEST_INVALID");
+        offset += bytesRead;
+      }
+      if (fileIdentity(await handle.stat()) !== fileIdentity(before) || fileIdentity(await physical(io, manifestPath)) !== fileIdentity(before)) fail("RG_MANIFEST_INVALID");
+      manifest = parseTaskDocument(bytes);
+    } finally { await handle.close(); }
+    if (!(await getManifestValidator())(manifest) || manifest.security.mcpAccess !== "read-only" || containsSensitiveData(JSON.stringify(manifest))) fail("RG_MANIFEST_INVALID");
+    const root = path.resolve(path.dirname(manifestPath), manifest.memory.vaultPath);
+    const source = await io.realpath(path.resolve(path.dirname(manifestPath), manifest.source.repositoryPath));
+    if (!canonical(root) || forbidden(root) || root === path.parse(root).root || path.relative(root, context.home ?? os.homedir()) === "" ||
+      inside(root, source) || inside(source, root)) fail("RG_ROOT_DENIED");
+    if (!(await io.lstat(source)).isDirectory()) fail("RG_ROOT_DENIED");
+    const stat = await physical(io, root); safe(stat, uid, true);
+    return Object.freeze({ root, uid, rootIdentity: identity(stat) });
+  } catch (error) { if (error instanceof MemoryMcpError) throw error; fail("RG_MANIFEST_INVALID"); }
+}
+
+export async function recheckMemoryRoot(policy, context = {}) {
+  try {
+    const s = await physical({ ...fs, ...context.io }, policy.root);
+    safe(s, policy.uid, true);
+    if (identity(s) !== policy.rootIdentity) fail("RG_ROOT_CHANGED", true);
+  } catch { fail("RG_ROOT_CHANGED", true); }
+}
+
+/** Validate the whole batch before a backend is allowed to read any listed file. */
+export async function validateMemoryCall(policy, name, args, context = {}) {
+  if (!inputs.has(name)) fail("RG_TOOL_DENIED");
+  if (!inputs.get(name)(args) || name === "read_text_file" && args.head !== undefined && args.tail !== undefined) fail("RG_INPUT_INVALID");
+  const io = { ...fs, ...context.io }, paths = args.paths ?? (args.path !== undefined ? [args.path] : []);
+  if ([args.pattern, ...(args.excludePatterns ?? [])].some(v => v !== undefined && control.test(v))) fail("RG_INPUT_INVALID");
+  const fileRead = ["read_text_file", "read_media_file", "read_multiple_files"].includes(name);
+  const snapshots = []; let total = 0;
+  for (const full of paths) {
+    if (!canonical(full) || forbidden(full) || !inside(policy.root, full)) fail("RG_PATH_DENIED");
+    try {
+      const s = await physical(io, full), directory = !fileRead && name !== "get_file_info" || s.isDirectory();
+      safe(s, policy.uid, directory);
+      if (fileRead && (!s.isFile() || !IS_WINDOWS && !(s.mode & 0o400))) fail("RG_PATH_DENIED");
+      if (fileRead) { total += s.size; if (s.size > MEMORY_MCP_LIMITS.fileBytes || total > MEMORY_MCP_LIMITS.totalBytes) fail("RG_READ_LIMIT"); }
+      snapshots.push({ path: full, signature: fileIdentity(s) });
+    } catch (error) { if (error instanceof MemoryMcpError) throw error; fail("RG_PATH_DENIED"); }
+  }
+  const forwarded = structuredClone(args);
+  if (["directory_tree", "search_files"].includes(name))
+    forwarded.excludePatterns = [...new Set([...(args.excludePatterns ?? []), ...recursiveExclusions])];
+  return { args: forwarded, snapshots };
+}
+
+export async function recheckMemoryEntries(snapshots, context = {}) {
+  try { for (const entry of snapshots) if (fileIdentity(await physical({ ...fs, ...context.io }, entry.path)) !== entry.signature) fail("RG_ENTRY_CHANGED"); }
+  catch { fail("RG_ENTRY_CHANGED"); }
+}
+
+export function checkMemoryResult(result, mediaPaths = []) {
+  if (!result || !Array.isArray(result.content) || result.isError) fail("RG_BACKEND_ERROR");
+  if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_MCP_LIMITS.responseBytes - 1024) fail("RG_RESPONSE_LIMIT", true);
+  const checkBlob = data => {
+    if (typeof data !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(data) || data.length % 4) fail("RG_BACKEND_PROTOCOL", true);
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.toString("base64") !== data) fail("RG_BACKEND_PROTOCOL", true);
+    if (bytes.length > MEMORY_MCP_LIMITS.fileBytes) fail("RG_RESPONSE_LIMIT", true);
+    if (containsSensitiveData(bytes.toString("utf8"))) fail("RG_CONTENT_DENIED");
+  };
+  const content = result.content.map(block => {
+    if (block.type === "text" && typeof block.text === "string") {
+      if (containsSensitiveData(block.text)) fail("RG_CONTENT_DENIED");
+      return { type: "text", text: block.text };
+    }
+    if (["image", "audio"].includes(block.type) && mediaPaths.length && typeof block.data === "string" && typeof block.mimeType === "string") {
+      checkBlob(block.data);
+      return { type: block.type, data: block.data, mimeType: block.mimeType };
+    }
+    if (block.type === "resource" && mediaPaths.length && typeof block.resource?.blob === "string") {
+      let file; try { file = fileURLToPath(block.resource.uri); } catch { fail("RG_BACKEND_PROTOCOL", true); }
+      if (!mediaPaths.includes(file) || pathToFileURL(file).href !== block.resource.uri || typeof block.resource.mimeType !== "string") fail("RG_BACKEND_PROTOCOL", true);
+      checkBlob(block.resource.blob);
+      return { type: "resource", resource: { uri: block.resource.uri, mimeType: block.resource.mimeType, blob: block.resource.blob } };
+    }
+    fail("RG_BACKEND_PROTOCOL", true);
+  });
+  if (result.structuredContent !== undefined) {
+    if (Array.isArray(result.structuredContent?.content) && mediaPaths.length &&
+      JSON.stringify(result.structuredContent.content) === JSON.stringify(result.content))
+      return { content, structuredContent: { content } };
+    if (typeof result.structuredContent?.content !== "string" || containsSensitiveData(result.structuredContent.content)) fail("RG_CONTENT_DENIED");
+    return { content, structuredContent: { content: result.structuredContent.content } };
+  }
+  return { content };
+}

package/src/memory-mcp-server.js

@@ -0,0 +1,166 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { InitializeRequestSchema, ListToolsRequestSchema, CallToolRequestSchema, McpError, SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/sdk/types.js";
+import {
+  MEMORY_READ_TOOLS, MEMORY_TOOL_SCHEMAS, MEMORY_MCP_LIMITS, MemoryMcpError,
+  loadMemoryPolicy, recheckMemoryRoot, validateMemoryCall, recheckMemoryEntries, checkMemoryResult
+} from "./memory-mcp-policy.js";
+import { MemoryMcpTransport } from "./memory-mcp-transport.js";
+
+const require = createRequire(import.meta.url);
+const codeOf = error => error instanceof MemoryMcpError ? error.code : "RG_BACKEND_ERROR";
+const resultText = r => r?.structuredContent?.content ?? r?.content?.filter(b => b.type === "text").map(b => b.text).join("\n");
+
+/** Runtime never resolves a package from npx, cwd, the manifest or client input. */
+export function createFilesystemBackend(root, onFatal) {
+  const manifest = require.resolve("@modelcontextprotocol/server-filesystem/package.json");
+  const pkg = JSON.parse(fs.readFileSync(manifest, "utf8"));
+  if (pkg.version !== "2026.8.31" || pkg.bin?.["mcp-server-filesystem"] !== "dist/index.js") throw new MemoryMcpError("RG_BACKEND_VERSION", true);
+  const client = new Client({ name: "project-memory-guard-backend", version: "0.1.0" }, { capabilities: {} });
+  const transport = new StdioClientTransport({ command: process.execPath,
+    args: [path.join(path.dirname(manifest), "dist/index.js"), root], cwd: path.dirname(manifest),
+    stderr: "pipe", maxBufferSize: MEMORY_MCP_LIMITS.responseBytes });
+  // Drain, never print the child's paths, stack traces or payloads.
+  transport.stderr.resume();
+  let closing = false;
+  client.onerror = () => { if (!closing) onFatal("RG_BACKEND_PROTOCOL"); };
+  client.onclose = () => { if (!closing) onFatal("RG_BACKEND_CLOSED"); };
+  client.fallbackRequestHandler = async () => { onFatal("RG_BACKEND_CALLBACK"); throw new McpError(-32601, "RG_BACKEND_CALLBACK"); };
+  client.fallbackNotificationHandler = async () => { onFatal("RG_BACKEND_PROTOCOL"); };
+  return {
+    start: () => client.connect(transport, { timeout: MEMORY_MCP_LIMITS.timeoutMs }),
+    listTools: () => client.listTools(undefined, { timeout: MEMORY_MCP_LIMITS.timeoutMs }),
+    call: (name, args) => client.callTool({ name, arguments: args }, undefined, { timeout: MEMORY_MCP_LIMITS.timeoutMs }),
+    async close() { closing = true; try { await client.close(); } finally { await transport.close(); } },
+    get pid() { return transport.pid; }
+  };
+}
+
+/** Only the trusted programmatic test context can replace a backend. No CLI/RPC selector exists. */
+export async function createMemoryGateway(manifestPath, context = {}) {
+  const policy = await loadMemoryPolicy(manifestPath, context);
+  let closed = false, busy = false, closePromise, cleanupError, backend;
+  const timeout = context.timeoutMs ?? MEMORY_MCP_LIMITS.timeoutMs;
+  const requestClose = () => {
+    closed = true;
+    return closePromise ??= Promise.resolve().then(() => backend?.close())
+      .catch(() => { cleanupError = new MemoryMcpError("RG_CLOSE_FAILED", true); });
+  };
+  const close = async () => { await requestClose(); if (cleanupError) throw cleanupError; };
+  const fatal = () => { void requestClose(); };
+  backend = (context.backendFactory ?? createFilesystemBackend)(policy.root, fatal);
+  const active = () => { if (closed) throw new MemoryMcpError("RG_SESSION_CLOSED", true); };
+  async function deadline(work, signal) {
+    active(); let timer, aborted;
+    const stop = code => { fatal(); return new MemoryMcpError(code, true); };
+    if (signal?.aborted) throw stop("RG_CANCELLED");
+    try {
+      const limit = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(stop("RG_TIMEOUT")), timeout);
+        aborted = () => reject(stop("RG_CANCELLED"));
+        if (signal?.aborted) aborted(); else signal?.addEventListener("abort", aborted, { once: true });
+      });
+      const value = await Promise.race([Promise.resolve().then(() => {
+        if (signal?.aborted) throw stop("RG_CANCELLED"); active(); return work();
+      }), limit]); active(); return value;
+    } finally { clearTimeout(timer); signal?.removeEventListener("abort", aborted); }
+  }
+  async function scope() {
+    await recheckMemoryRoot(policy, context);
+    const r = await backend.call("list_allowed_directories", {});
+    if (r?.isError || resultText(r) !== "Allowed directories:\n" + policy.root) throw new MemoryMcpError("RG_BACKEND_SCOPE", true);
+  }
+  let tools;
+  try {
+    await deadline(async () => {
+      await backend.start(); await scope();
+      const catalog = await backend.listTools();
+      const map = new Map(catalog.tools?.map(t => [t.name, t]));
+      if (!Array.isArray(catalog.tools) || map.size !== catalog.tools.length) throw new MemoryMcpError("RG_BACKEND_CATALOG", true);
+      tools = MEMORY_READ_TOOLS.map(name => {
+        const tool = map.get(name), expected = MEMORY_TOOL_SCHEMAS[name];
+        if (tool?.annotations?.readOnlyHint !== true || tool.inputSchema?.type !== "object" ||
+          (expected.required ?? []).some(key => !tool.inputSchema?.properties?.[key]) ||
+          (tool.inputSchema?.required ?? []).some(key => !(expected.required ?? []).includes(key)))
+          throw new MemoryMcpError("RG_BACKEND_CATALOG", true);
+        for (const [key, schema] of Object.entries(expected.properties)) {
+          const upstream = tool.inputSchema.properties?.[key];
+          if (!upstream || schema.type && !(upstream.type === schema.type || schema.type === "integer" && upstream.type === "number") ||
+            schema.items && upstream.items?.type !== "string" ||
+            schema.enum && upstream.enum && schema.enum.some(value => !upstream.enum.includes(value)))
+            throw new MemoryMcpError("RG_BACKEND_CATALOG", true);
+        }
+        return { name, description: `Lectura limitada: ${name}. Raíz fijada por el manifiesto.`,
+          inputSchema: structuredClone(expected), annotations: { readOnlyHint: true, openWorldHint: false } };
+      });
+      await recheckMemoryRoot(policy, context);
+    }, context.signal);
+  } catch (error) { await close(); throw error instanceof MemoryMcpError ? error : new MemoryMcpError("RG_BACKEND_START", true); }
+  async function operation(work, signal) {
+    active(); if (busy) throw new MemoryMcpError("RG_BUSY"); busy = true;
+    try { return await deadline(work, signal); }
+    catch (error) { if (!(error instanceof MemoryMcpError) || error.fatal) await close(); throw error instanceof MemoryMcpError ? error : new MemoryMcpError("RG_BACKEND_ERROR", true); }
+    finally { busy = false; }
+  }
+  return Object.freeze({
+    root: policy.root,
+    get closed() { return closed; },
+    get backendPid() { return backend.pid; },
+    close,
+    listTools: signal => operation(async () => { await scope(); return structuredClone(tools); }, signal),
+    call: (name, args, signal) => operation(async () => {
+      await recheckMemoryRoot(policy, context);
+      const checked = await validateMemoryCall(policy, name, args, context);
+      await scope();
+      const raw = name === "list_allowed_directories"
+        ? { content: [{ type: "text", text: "Allowed directories:\n" + policy.root }] }
+        : await backend.call(name, checked.args);
+      // Filesystem encodes per-file failures as text in a successful batch.
+      // Do not report that partial result as a successful read or relay its raw errors.
+      if (name === "read_multiple_files" && checked.args.paths.some(file => resultText(raw)?.includes(file + ": Error -")))
+        throw new MemoryMcpError("RG_BACKEND_ERROR");
+      const result = checkMemoryResult(raw, name === "read_media_file" ? checked.snapshots.map(s => s.path) : []);
+      await recheckMemoryEntries(checked.snapshots, context); await recheckMemoryRoot(policy, context);
+      return result;
+    }, signal)
+  });
+}
+
+export async function runMemoryMcp(manifestPath, context = {}) {
+  const gateway = await createMemoryGateway(manifestPath, context);
+  let resolveEnd, initialized = false;
+  const ended = new Promise(resolve => { resolveEnd = resolve; });
+  const server = new Server({ name: "project-memory-guard", version: "0.1.0" }, { capabilities: { tools: {} } });
+  const transport = new MemoryMcpTransport(context.stdin ?? process.stdin, context.stdout ?? process.stdout,
+    { onClose: resolveEnd, onFatal: () => { void gateway.close().catch(() => {}); } });
+  const protocolError = code => new McpError(-32602, code);
+  server.setRequestHandler(InitializeRequestSchema, request => {
+    if (initialized) throw protocolError("RG_ALREADY_INITIALIZED");
+    if (!SUPPORTED_PROTOCOL_VERSIONS.includes(request.params.protocolVersion)) throw protocolError("RG_PROTOCOL_UNSUPPORTED");
+    initialized = true;
+    return { protocolVersion: request.params.protocolVersion, capabilities: { tools: {} }, serverInfo: { name: "project-memory-guard", version: "0.1.0" } };
+  });
+  server.setRequestHandler(ListToolsRequestSchema, async (_, extra) => {
+    if (!initialized) throw protocolError("RG_NOT_INITIALIZED");
+    try { return { tools: await gateway.listTools(extra.signal) }; }
+    catch (error) { throw protocolError(codeOf(error)); }
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    if (!initialized) throw protocolError("RG_NOT_INITIALIZED");
+    if (request.params.task) throw protocolError("RG_INPUT_INVALID");
+    try { return await gateway.call(request.params.name, request.params.arguments ?? {}, extra.signal); }
+    catch (error) { return { isError: true, content: [{ type: "text", text: codeOf(error) }] }; }
+  });
+  server.onerror = () => { void transport.close(); };
+  server.onclose = () => { void gateway.close().catch(() => {}); };
+  const abort = () => { void transport.close(); };
+  context.signal?.addEventListener("abort", abort, { once: true });
+  try {
+    if (context.signal?.aborted) throw new MemoryMcpError("RG_CANCELLED");
+    await server.connect(transport); await ended;
+  } finally { context.signal?.removeEventListener("abort", abort); await gateway.close(); await server.close(); }
+}