nexakit 0.0.0-stage → 0.2.0

package/src/memory-connection-descriptor.js

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+import { copyInertJson } from "./client-output-json.js";
+import { MEMORY_READ_TOOLS } from "./memory-mcp-policy.js";
+import { containsSensitiveData, isCredentialPath } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_VERSION = "1.0.0";
+export const MEMORY_CONNECTION_LIMITS = Object.freeze({
+  inputBytes: 131072,
+  reportBytes: 131072,
+  pathChars: 4096
+});
+export const MEMORY_CONNECTION_FACTS = Object.freeze({
+  evidence: "declared",
+  physicalPathsVerified: false,
+  localReadVerified: false,
+  nativeReadVerified: false,
+  runtimeVerified: false,
+  authorizationGranted: false,
+  executable: false,
+  applied: false,
+  wrote: false,
+  sent: false,
+  executed: false,
+  humanReviewRequired: true
+});
+
+const INPUT_KEYS = [
+  "agent", "mcpName", "skillName", "nodePath", "toolkitRoot",
+  "manifestPath", "vaultPath", "sourcePath", "homeDirectory"
+];
+const ROOT_KEYS = ["toolkitRoot", "vaultPath", "sourcePath", "homeDirectory"];
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const PRIVATE_PATH = /(?:^|\/)(?:\.git|\.obsidian|\.codex|\.claude|\.gemini|\.agents|\.secrets|\.credentials|\.npmrc|\.netrc|\.envrc)(?:\/|$)/i;
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+
+export class MemoryConnectionInputError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "MemoryConnectionInputError";
+    this.code = code;
+  }
+}
+
+const reject = (code) => { throw new MemoryConnectionInputError(code); };
+
+/** Reject conversion hooks before interpreting caller-supplied declarations. */
+export function copyMemoryConnectionData(input) {
+  let data;
+  try { data = copyInertJson(input); }
+  catch { reject("MC_DATA_INVALID"); }
+  if (Buffer.byteLength(JSON.stringify(data)) > MEMORY_CONNECTION_LIMITS.inputBytes) {
+    reject("MC_INPUT_LIMIT");
+  }
+  return data;
+}
+
+export function freezeMemoryConnectionData(data) {
+  const owned = copyMemoryConnectionData(data);
+  function freeze(value) {
+    if (value !== null && typeof value === "object") {
+      for (const child of Object.values(value)) freeze(child);
+      Object.freeze(value);
+    }
+    return value;
+  }
+  return freeze(owned);
+}
+
+/** Stable pin over inert declarations only; this does not verify their truth. */
+export function memoryConnectionHash(input) {
+  const data = copyMemoryConnectionData(input);
+  const canonical = (value) => {
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+    return "{" + Object.keys(value).sort().map((key) =>
+      JSON.stringify(key) + ":" + canonical(value[key])).join(",") + "}";
+  };
+  return createHash("sha256").update(canonical(data)).digest("hex");
+}
+
+export function hasMemoryConnectionKeys(value, required, optional = []) {
+  let data, keys;
+  try {
+    data = copyMemoryConnectionData(value);
+    keys = copyMemoryConnectionData({ required, optional });
+  } catch { return false; }
+  return data !== null && typeof data === "object" && !Array.isArray(data) &&
+    Array.isArray(keys.required) && Array.isArray(keys.optional) &&
+    [...keys.required, ...keys.optional].every((key) => typeof key === "string") &&
+    keys.required.every((key) => Object.hasOwn(data, key)) &&
+    Object.keys(data).every((key) => keys.required.includes(key) || keys.optional.includes(key));
+}
+
+function isPath(value, allowClientDirectory = false) {
+  return typeof value === "string" && value.length > 0 &&
+    value.length <= MEMORY_CONNECTION_LIMITS.pathChars && value === value.trim() &&
+    Buffer.from(value, "utf8").toString("utf8") === value &&
+    !CONTROL.test(value) && !value.includes("\\") &&
+    path.posix.isAbsolute(value) && path.posix.normalize(value) === value &&
+    value.split("/").slice(1).every((part) => part && part !== "." && part !== "..") &&
+    !containsSensitiveData(value) && !isCredentialPath(value) &&
+    (allowClientDirectory || !PRIVATE_PATH.test(value));
+}
+
+function isName(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9-]{0,63}$/.test(value) &&
+    !RESERVED_NAMES.has(value);
+}
+
+const within = (parent, child) => child === parent || child.startsWith(parent + "/");
+
+/**
+ * Builds a disabled protected invocation from explicit POSIX path declarations.
+ * No discovery, realpath, file inspection, runtime admission or execution occurs.
+ * A collector must independently verify paths and bytes before operational use.
+ */
+export function createMemoryConnectionDescriptor(input) {
+  const data = copyMemoryConnectionData(input);
+  if (!hasMemoryConnectionKeys(data, INPUT_KEYS)) reject("MC_DESCRIPTOR_INVALID");
+  if (data.agent !== "codex") reject("MC_AGENT_UNSUPPORTED");
+  if (!isName(data.mcpName) || !isName(data.skillName)) reject("MC_NAME_INVALID");
+  for (const key of ["nodePath", "manifestPath", ...ROOT_KEYS]) {
+    if (!isPath(data[key])) reject("MC_PATH_INVALID");
+  }
+  if (data.vaultPath === data.homeDirectory ||
+      within(data.sourcePath, data.vaultPath) || within(data.vaultPath, data.sourcePath)) {
+    reject("MC_PATH_OVERLAP");
+  }
+
+  const binPath = path.posix.join(data.toolkitRoot, "bin", "project-memory-mcp.js");
+  const source = path.posix.join(data.vaultPath, "07-AGENTES", "skills", data.skillName);
+  const target = path.posix.join(data.homeDirectory, ".agents", "skills", data.skillName);
+  const configurationPath = path.posix.join(data.homeDirectory, ".codex", "config.toml");
+  if (!isPath(binPath) || !isPath(source) ||
+      !isPath(target, true) || !isPath(configurationPath, true)) {
+    reject("MC_PATH_INVALID");
+  }
+  const descriptor = {
+    schemaVersion: MEMORY_CONNECTION_VERSION,
+    identity: data,
+    server: {
+      command: data.nodePath,
+      args: [binPath, "--manifest", data.manifestPath],
+      cwd: data.toolkitRoot,
+      enabled_tools: [...MEMORY_READ_TOOLS],
+      enabled: false
+    },
+    skill: { source, target },
+    configurationPath,
+    facts: { ...MEMORY_CONNECTION_FACTS }
+  };
+  if (Buffer.byteLength(JSON.stringify(descriptor)) > MEMORY_CONNECTION_LIMITS.reportBytes) {
+    reject("MC_REPORT_LIMIT");
+  }
+  return freezeMemoryConnectionData(descriptor);
+}

package/src/memory-connection-diagnostic.js

@@ -0,0 +1,177 @@
+import { copyInertJson } from "./client-output-json.js";
+import {
+  createMemoryConnectionDescriptor, freezeMemoryConnectionData, memoryConnectionHash,
+  MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+import { containsSensitiveData } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_DIAGNOSTIC_LIMITS = Object.freeze({
+  inputBytes: 128 * 1024, reportBytes: 128 * 1024,
+  depth: 64, nodes: 30000, arrayItems: 256, stringChars: 4096, serverItems: 16
+});
+const ROLES = ["configuration", "skill", "artifacts", "manifest", "package"];
+const ARTIFACT_KEYS = ["nodeSha256", "binSha256", "manifestSha256", "packageJsonSha256", "packageLockSha256"];
+const PIN_KEYS = ["configurationSha256", "skillSha256", ...ARTIFACT_KEYS];
+const FIELDS = {
+  configuration: ["state", "mcpName", "fileState", "entryState", "configurationSha256", "metadataSha256", "server"],
+  skill: ["state", "skillName", "sourceSha256", "metadataSha256", "resolvedSource"],
+  artifacts: ["state", "hashes", "metadataSha256"],
+  manifest: ["state", "descriptorSha256", "manifestSha256"],
+  package: ["state", "descriptorSha256", "packageJsonSha256", "packageLockSha256"]
+};
+const STATES = {
+  configuration: ["observed", "absent", "blocked", "invalid"],
+  skill: ["matched", "absent", "conflict", "blocked", "invalid"],
+  artifacts: ["matched", "blocked", "invalid"],
+  manifest: ["validated", "blocked", "invalid"], package: ["consistent", "blocked", "invalid"]
+};
+const HASH = /^[a-f0-9]{64}$/;
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const code = name => "MC_DIAGNOSTIC_" + name;
+const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+const hash = value => typeof value === "string" && HASH.test(value);
+const exact = (value, keys) => object(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const within = (root, full) => full === root || full.startsWith(root + "/");
+class Rejected extends Error {
+  constructor(reason, state = "invalid") { super(reason); this.reason = reason; this.state = state; }
+}
+const requireInput = condition => { if (!condition) throw new Rejected(code("INPUT")); };
+
+function captured(input) {
+  let data;
+  try { data = copyInertJson(input); }
+  catch (error) {
+    if (error?.code === "metadata-limit") throw new Rejected(code("LIMIT"), "blocked");
+    throw new Rejected(code("INPUT"));
+  }
+  if (Buffer.byteLength(JSON.stringify(data)) > MEMORY_CONNECTION_DIAGNOSTIC_LIMITS.inputBytes) {
+    throw new Rejected(code("LIMIT"), "blocked");
+  }
+  requireInput(exact(data, ["schemaVersion", "descriptor", "reviewedPins", "components"]));
+  requireInput(data.schemaVersion === MEMORY_CONNECTION_VERSION);
+  let descriptor;
+  try {
+    descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    requireInput(memoryConnectionHash(descriptor) === memoryConnectionHash(data.descriptor));
+    const { toolkitRoot, vaultPath, manifestPath } = descriptor.identity;
+    requireInput(!within(toolkitRoot, vaultPath) && !within(vaultPath, toolkitRoot) && manifestPath.startsWith(vaultPath + "/"));
+  } catch { throw new Rejected(code("INPUT")); }
+  requireInput(exact(data.reviewedPins, PIN_KEYS));
+  for (const key of PIN_KEYS) requireInput(hash(data.reviewedPins[key]) || key === "configurationSha256" && data.reviewedPins[key] === null);
+  requireInput(exact(data.components, ROLES));
+  // Every projection is checked before any partial classification is published.
+  for (const role of ROLES) projection(role, data.components[role], descriptor);
+  return { data, descriptor };
+}
+
+function strings(value) {
+  if (typeof value === "string") {
+    requireInput(value.length <= MEMORY_CONNECTION_DIAGNOSTIC_LIMITS.stringChars && value === value.trim() &&
+      !CONTROL.test(value) && Buffer.from(value, "utf8").toString("utf8") === value);
+  } else if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) strings(child);
+  }
+}
+
+function projection(role, item, descriptor) {
+  if (item === null) return;
+  requireInput(exact(item, ["bindingSha256", ...FIELDS[role]]) && hash(item.bindingSha256) && STATES[role].includes(item.state));
+  const negative = ["blocked", "invalid"].includes(item.state);
+  if (role === "configuration") {
+    requireInput(typeof item.mcpName === "string" || negative && item.mcpName === null);
+    if (negative) requireInput(item.mcpName === null || item.mcpName === descriptor.identity.mcpName);
+    if (item.state === "observed") {
+      requireInput(item.fileState === "present" && hash(item.configurationSha256) && hash(item.metadataSha256));
+      requireInput(item.entryState === "observed" && object(item.server) || item.entryState === "absent" && item.server === null);
+      strings(item.server);
+    } else if (item.state === "absent") {
+      requireInput(item.fileState === "absent" && item.entryState === null && item.server === null && item.configurationSha256 === null && hash(item.metadataSha256));
+    } else {
+      requireInput(item.fileState === "unknown" && item.entryState === null && item.server === null && item.configurationSha256 === null && item.metadataSha256 === null);
+    }
+  } else if (role === "skill") {
+    requireInput(typeof item.skillName === "string" || negative && item.skillName === null);
+    if (negative) requireInput(item.skillName === null || item.skillName === descriptor.identity.skillName);
+    if (["matched", "absent"].includes(item.state)) {
+      requireInput(hash(item.sourceSha256) && hash(item.metadataSha256));
+      requireInput(item.state === "matched" ? typeof item.resolvedSource === "string" : item.resolvedSource === null);
+      strings(item.resolvedSource);
+    } else requireInput(item.sourceSha256 === null && item.metadataSha256 === null && item.resolvedSource === null);
+  } else if (role === "artifacts") {
+    requireInput(item.state === "matched" ? exact(item.hashes, ARTIFACT_KEYS) && ARTIFACT_KEYS.every(key => hash(item.hashes[key])) && hash(item.metadataSha256) :
+      item.hashes === null && item.metadataSha256 === null);
+  } else {
+    const hashes = role === "manifest" ? ["descriptorSha256", "manifestSha256"] : ["descriptorSha256", "packageJsonSha256", "packageLockSha256"];
+    requireInput(hashes.every(key => negative ? item[key] === null : hash(item[key])));
+  }
+}
+
+function serverMatches(server, expected) {
+  if (!exact(server, ["command", "args", "cwd", "enabled_tools", "enabled"]) ||
+      typeof server.command !== "string" || typeof server.cwd !== "string" || typeof server.enabled !== "boolean" ||
+      !Array.isArray(server.args) || !Array.isArray(server.enabled_tools) ||
+      server.args.length > MEMORY_CONNECTION_DIAGNOSTIC_LIMITS.serverItems || server.enabled_tools.length > MEMORY_CONNECTION_DIAGNOSTIC_LIMITS.serverItems ||
+      !server.args.every(arg => typeof arg === "string") || !server.enabled_tools.every(tool => typeof tool === "string")) return false;
+  return server.command === expected.command && server.cwd === expected.cwd &&
+    server.args.length === expected.args.length && server.args.every((arg, i) => arg === expected.args[i]) &&
+    server.enabled_tools.length === expected.enabled_tools.length && new Set(server.enabled_tools).size === server.enabled_tools.length &&
+    expected.enabled_tools.every(tool => server.enabled_tools.includes(tool));
+}
+
+function component(role, item, descriptor, binding, pins) {
+  const output = (status, reason) => ({ id: role, status, code: code(reason) });
+  if (item === null) return output("not-provided", "MISSING");
+  if (item.bindingSha256 !== binding || ["manifest", "package"].includes(role) && item.descriptorSha256 !== null && item.descriptorSha256 !== binding) {
+    return output("blocked", "BINDING");
+  }
+  if (role === "configuration" && ["observed", "absent"].includes(item.state) && item.configurationSha256 !== pins.configurationSha256 ||
+      role === "skill" && ["matched", "absent"].includes(item.state) && item.sourceSha256 !== pins.skillSha256 ||
+      role === "artifacts" && item.state === "matched" && ARTIFACT_KEYS.some(key => item.hashes[key] !== pins[key]) ||
+      role === "manifest" && item.state === "validated" && item.manifestSha256 !== pins.manifestSha256 ||
+      role === "package" && item.state === "consistent" && ["packageJsonSha256", "packageLockSha256"].some(key => item[key] !== pins[key])) {
+    return output("blocked", "PINS");
+  }
+  if (["blocked", "invalid"].includes(item.state)) return output("blocked", role.toUpperCase());
+  if (role === "configuration") {
+    if (item.mcpName !== descriptor.identity.mcpName) return output("conflict", "CONFIGURATION");
+    if (item.state === "absent" || item.entryState === "absent") return output("missing", "MISSING");
+    if (!serverMatches(item.server, descriptor.server)) return output("conflict", "CONFIGURATION");
+    if (!item.server.enabled) return output("disabled", "DISABLED");
+  }
+  if (role === "skill") {
+    if (item.skillName !== descriptor.identity.skillName || item.state === "conflict" ||
+        item.state === "matched" && item.resolvedSource !== descriptor.skill.source) return output("conflict", "SKILL");
+    if (item.state === "absent") return output("missing", "MISSING");
+  }
+  return output("declared-matched", "MATCH");
+}
+
+function report(state, reasons, components = [], hashes = {}) {
+  const result = {
+    schemaVersion: MEMORY_CONNECTION_VERSION, state, components, reasons: [...new Set(reasons)].sort(),
+    descriptorSha256: null, bundleHash: null, ...hashes,
+    facts: {
+      ...MEMORY_CONNECTION_FACTS, evidence: "declared-reports", verificationScope: "cross-report-declarations-only",
+      declarationsLinked: state === "coherent", provenanceVerified: false, snapshotAtomicVerified: false, freshnessVerified: false,
+      skillLoadedVerified: false, runtimeVersionVerified: false, runtimeCompatibilityVerified: false, installedDependenciesVerified: false
+    }
+  };
+  if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_DIAGNOSTIC_LIMITS.reportBytes) throw new Rejected(code("LIMIT"), "blocked");
+  return freezeMemoryConnectionData(result);
+}
+
+/** Compare caller-declared projections, never authenticate origin or admit a runtime. */
+export function summarizeMemoryConnectionEvidence(input) {
+  try {
+    const { data, descriptor } = captured(input);
+    if (containsSensitiveData(JSON.stringify(data))) return report("blocked", [code("SENSITIVE")]);
+    const binding = memoryConnectionHash(descriptor);
+    const components = ROLES.map(role => component(role, data.components[role], descriptor, binding, data.reviewedPins));
+    const state = components.some(c => ["blocked", "conflict"].includes(c.status)) ? "blocked" :
+      components.some(c => ["missing", "disabled", "not-provided"].includes(c.status)) ? "incomplete" : "coherent";
+    if (state !== "coherent") return report(state, components.filter(c => c.status !== "declared-matched").map(c => c.code), components);
+    return report("coherent", [code("COHERENT")], components, { descriptorSha256: binding, bundleHash: memoryConnectionHash(data) });
+  } catch (error) {
+    return report(error instanceof Rejected ? error.state : "blocked", [error instanceof Rejected ? error.reason : code("VALIDATION")]);
+  }
+}

package/src/memory-connection-files.js

@@ -0,0 +1,191 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+import {
+  copyMemoryConnectionData, freezeMemoryConnectionData,
+  MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+import { readMemoryConnectionToml, MEMORY_CONNECTION_TOML_LIMITS } from "./memory-connection-toml.js";
+import { containsSensitiveData, isCredentialPath } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_FILE_LIMITS = Object.freeze({
+  fileBytes: MEMORY_CONNECTION_TOML_LIMITS.inputBytes, chunkBytes: 65536,
+  pathChars: 4096, components: 64, reportBytes: 131072
+});
+export const MEMORY_CONNECTION_OPEN_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const PRIVATE_ROOT = /(?:^|\/)(?:\.git|\.obsidian|\.codex|\.claude|\.gemini|\.agents|\.credentials|\.secrets)(?:\/|$)/i;
+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 errno = (error) => error instanceof Error && typeof error.code === "string" ? error.code : "";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const directorySignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode]);
+const fileSignature = (s) => JSON.stringify([s.dev, s.ino, s.uid, s.gid, s.mode, s.nlink, s.size, s.mtimeMs, s.ctimeMs]);
+
+function validPath(value) {
+  return typeof value === "string" && value.length > 1 && value.length <= MEMORY_CONNECTION_FILE_LIMITS.pathChars &&
+    value === value.trim() && Buffer.from(value, "utf8").toString("utf8") === value &&
+    !CONTROL.test(value) && !value.includes("\\") && path.posix.isAbsolute(value) &&
+    path.posix.normalize(value) === value && !value.endsWith("/") &&
+    value.split("/").slice(1).every((part) => part && part !== "." && part !== "..") &&
+    value.split("/").length - 1 <= MEMORY_CONNECTION_FILE_LIMITS.components &&
+    !containsSensitiveData(value) && !isCredentialPath(value);
+}
+function inputData(input) {
+  let data;
+  try { data = copyMemoryConnectionData(input); } catch { reject("MC_FILES_INPUT", "invalid"); }
+  const required = ["homeDirectory", "configurationPath", "mcpName"];
+  if (!data || Array.isArray(data) || Object.keys(data).length !== required.length ||
+      !required.every((key) => Object.hasOwn(data, key)) ||
+      !validPath(data.homeDirectory) || PRIVATE_ROOT.test(data.homeDirectory) ||
+      !validPath(data.configurationPath) || data.configurationPath !== data.homeDirectory + "/.codex/config.toml" ||
+      typeof data.mcpName !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(data.mcpName) ||
+      ["constructor", "prototype", "__proto__"].includes(data.mcpName)) reject("MC_FILES_INPUT", "invalid");
+  return data;
+}
+
+function safeDirectory(s, uid, insideHome) {
+  if (!s.isDirectory() || s.isSymbolicLink() || !(s.mode & 0o100)) reject("MC_FILES_PARENT_UNSAFE");
+  if (insideHome) {
+    if (s.uid !== uid || s.mode & 0o7022) reject("MC_FILES_PARENT_UNSAFE");
+  } else {
+    // Root-owned sticky temporary ancestors are allowed ONLY before the owned home.
+    const sharedTemporary = s.uid === 0 && (s.mode & 0o7777) === 0o1777;
+    if (![0, uid].includes(s.uid) || !sharedTemporary && s.mode & 0o7022) reject("MC_FILES_PARENT_UNSAFE");
+  }
+}
+function safeFile(s, uid) {
+  if (!s.isFile() || s.isSymbolicLink() || s.uid !== uid || s.nlink !== 1 || (s.mode & 0o7777) !== 0o600) {
+    reject("MC_FILES_FILE_UNSAFE");
+  }
+  if (!Number.isSafeInteger(s.size) || s.size < 0 || s.size > MEMORY_CONNECTION_FILE_LIMITS.fileBytes) {
+    reject("MC_FILES_LIMIT");
+  }
+}
+async function inspect(io, data, uid) {
+  const parents = [];
+  let current = "/";
+  const root = await io.lstat(current); safeDirectory(root, uid, false);
+  parents.push({ path: current, signature: directorySignature(root) });
+  const parts = data.configurationPath.slice(1).split("/");
+  for (let index = 0; index < parts.length; index++) {
+    current = path.posix.join(current, parts[index]);
+    let s;
+    try { s = await io.lstat(current); }
+    catch (error) {
+      if (errno(error) === "ENOENT" && [data.homeDirectory + "/.codex", data.configurationPath].includes(current)) {
+        return { parents, file: null, missing: current };
+      }
+      reject("MC_FILES_UNREADABLE");
+    }
+    if (index === parts.length - 1) { safeFile(s, uid); return { parents, file: s, missing: null }; }
+    safeDirectory(s, uid, current === data.homeDirectory || current.startsWith(data.homeDirectory + "/"));
+    parents.push({ path: current, signature: directorySignature(s) });
+  }
+  reject("MC_FILES_INPUT", "invalid");
+}
+async function recheck(io, data, snapshot, uid) {
+  for (const parent of snapshot.parents) {
+    let s;
+    try { s = await io.lstat(parent.path); } catch { reject("MC_FILES_CHANGED"); }
+    safeDirectory(s, uid, parent.path === data.homeDirectory || parent.path.startsWith(data.homeDirectory + "/"));
+    if (directorySignature(s) !== parent.signature) reject("MC_FILES_CHANGED");
+  }
+  if (snapshot.missing) {
+    try { await io.lstat(snapshot.missing); }
+    catch (error) { if (errno(error) === "ENOENT") return; reject("MC_FILES_CHANGED"); }
+    reject("MC_FILES_CHANGED");
+  }
+  let named;
+  try { named = await io.lstat(data.configurationPath); } catch { reject("MC_FILES_CHANGED"); }
+  safeFile(named, uid);
+  if (fileSignature(named) !== fileSignature(snapshot.file)) reject("MC_FILES_CHANGED");
+}
+
+/**
+ * Reads one explicit configuration in a verified POSIX path; never discovers,
+ * writes, repairs or launches anything. IO overrides are TRUSTED test doubles,
+ * not an authorization/sandbox boundary and never evidence of native local IO.
+ * Name/descriptor checks detect observable races, not atomic openat/ABA isolation.
+ */
+export async function collectMemoryConnectionConfiguration(input, dependencies = {}) {
+  let data = null;
+  let nativeIO = false, io;
+  const result = (state, details = {}) => {
+    const success = state === "observed" || state === "absent";
+    const read = state === "observed";
+    const report = {
+      schemaVersion: MEMORY_CONNECTION_VERSION, state, mcpName: data?.mcpName ?? null,
+      fileState: read ? "present" : state === "absent" ? "absent" : "unknown",
+      entryState: null, configurationSha256: null, metadataSha256: null,
+      server: null, ranges: null, reasons: [], ...details,
+      facts: {
+        ...MEMORY_CONNECTION_FACTS, verificationScope: "configuration-only",
+        evidence: success ? nativeIO ? read ? "local-file" : "local-metadata" : "simulated-local-file" : "none",
+        configurationPathVerified: success && nativeIO,
+        configurationSourceVerified: read && nativeIO,
+        localReadVerified: read && nativeIO,
+        byteSyntaxVerified: read
+      }
+    };
+    if (Buffer.byteLength(JSON.stringify(report)) > MEMORY_CONNECTION_FILE_LIMITS.reportBytes) reject("MC_FILES_REPORT_LIMIT");
+    return freezeMemoryConnectionData(report);
+  };
+  try {
+    data = inputData(input);
+    nativeIO = dependencies.io === undefined;
+    io = dependencies.io ?? fs;
+    const uid = process.getuid?.();
+    if (!["darwin", "linux"].includes(process.platform) || !Number.isSafeInteger(uid) || constants.O_NOFOLLOW === undefined) {
+      reject("MC_FILES_PLATFORM");
+    }
+    const snapshot = await inspect(io, data, uid);
+    const metadataHash = () => digest(JSON.stringify({
+      parents: snapshot.parents, path: data.configurationPath,
+      file: snapshot.file ? fileSignature(snapshot.file) : null, missing: snapshot.missing
+    }));
+    await recheck(io, data, snapshot, uid);
+    if (snapshot.missing) return result("absent", { metadataSha256: metadataHash(), reasons: ["MC_FILES_MISSING"] });
+    let handle;
+    try { handle = await io.open(data.configurationPath, MEMORY_CONNECTION_OPEN_FLAGS); }
+    catch (error) { reject(errno(error) === "ELOOP" ? "MC_FILES_FILE_UNSAFE" : "MC_FILES_UNREADABLE"); }
+    let bytes;
+    try {
+      const opened = await handle.stat(); safeFile(opened, uid);
+      if (fileSignature(opened) !== fileSignature(snapshot.file)) reject("MC_FILES_CHANGED");
+      // Recheck the whole named chain BEFORE the first content read, too.
+      await recheck(io, data, snapshot, uid);
+      bytes = Buffer.alloc(snapshot.file.size);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const request = Math.min(MEMORY_CONNECTION_FILE_LIMITS.chunkBytes, bytes.length - offset);
+        const { bytesRead } = await handle.read(bytes, offset, request, offset);
+        if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > request) reject("MC_FILES_READ");
+        if (bytesRead === 0) reject("MC_FILES_CHANGED");
+        offset += bytesRead;
+      }
+      const after = await handle.stat(); safeFile(after, uid);
+      if (fileSignature(after) !== fileSignature(snapshot.file)) reject("MC_FILES_CHANGED");
+      await recheck(io, data, snapshot, uid);
+    } finally {
+      try { await handle.close(); } catch { reject("MC_FILES_CLOSE"); }
+    }
+    await recheck(io, data, snapshot, uid);
+    const parsed = readMemoryConnectionToml(bytes, { mcpName: data.mcpName });
+    if (!["observed", "absent"].includes(parsed.state)) {
+      return result("blocked", { reasons: ["MC_FILES_TOML", ...parsed.reasons] });
+    }
+    return result("observed", {
+      entryState: parsed.state, configurationSha256: parsed.configurationSha256,
+      metadataSha256: metadataHash(), server: parsed.server, ranges: parsed.ranges
+    });
+  } catch (error) {
+    return result(error instanceof Rejected ? error.state : "blocked", {
+      reasons: [error instanceof Rejected ? error.code : "MC_FILES_IO"]
+    });
+  }
+}

package/src/memory-connection-manifest.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { types } from "node:util";
+import Ajv2020 from "ajv/dist/2020.js";
+import ownSchema from "../schemas/project-memory.schema.json" with { type: "json" };
+import { copyBytes, copyInertJson, decode, parseEventJson } from "./client-output-json.js";
+import {
+  createMemoryConnectionDescriptor, copyMemoryConnectionData, freezeMemoryConnectionData,
+  memoryConnectionHash, MEMORY_CONNECTION_FACTS, MEMORY_CONNECTION_VERSION
+} from "./memory-connection-descriptor.js";
+import { containsSensitiveData, isCredentialPath } from "./sensitive-data.js";
+
+export const MEMORY_CONNECTION_MANIFEST_LIMITS = Object.freeze({
+  manifestBytes: 512 * 1024, reportBytes: 128 * 1024,
+  depth: 64, nodes: 30000, arrayItems: 256, pathChars: 4096, components: 64
+});
+// Trusted module/schema loading is distinct from evaluating caller-supplied bytes.
+const trustedSchema = freezeMemoryConnectionData(ownSchema);
+const validateSchema = new Ajv2020({
+  strict: true, allErrors: false, ownProperties: true,
+  coerceTypes: false, useDefaults: false, removeAdditional: false
+}).compile(trustedSchema);
+const KEYS = ["descriptor", "manifestBytes", "expectedManifestSha256"];
+const CONTROL = /[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u;
+const PRIVATE_PATH = /(?:^|\/)(?:\.git|\.obsidian|\.codex|\.claude|\.gemini|\.agents|\.secrets|\.credentials|\.npmrc|\.netrc|\.envrc)(?:\/|$)/i;
+const within = (root, full) => full === root || full.startsWith(root + "/");
+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); };
+
+function inputs(input) {
+  try {
+    if (!input || typeof input !== "object" || types.isProxy(input) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(input)) || Object.getOwnPropertySymbols(input).length) reject("MC_MANIFEST_INPUT", "invalid");
+    const fields = Object.getOwnPropertyDescriptors(input), names = Object.keys(fields);
+    if (names.length !== KEYS.length || !KEYS.every(k => Object.hasOwn(fields, k) && fields[k].enumerable && Object.hasOwn(fields[k], "value"))) reject("MC_MANIFEST_INPUT", "invalid");
+    const data = copyMemoryConnectionData({ descriptor: fields.descriptor.value, expectedManifestSha256: fields.expectedManifestSha256.value });
+    if (typeof data.expectedManifestSha256 !== "string" || !/^[a-f0-9]{64}$/.test(data.expectedManifestSha256)) reject("MC_MANIFEST_INPUT", "invalid");
+    const descriptor = createMemoryConnectionDescriptor(data.descriptor?.identity);
+    if (memoryConnectionHash(descriptor) !== memoryConnectionHash(data.descriptor)) reject("MC_MANIFEST_INPUT", "invalid");
+    const { toolkitRoot, vaultPath, manifestPath } = descriptor.identity;
+    if (within(toolkitRoot, vaultPath) || within(vaultPath, toolkitRoot) || !manifestPath.startsWith(vaultPath + "/")) reject("MC_MANIFEST_INPUT", "invalid");
+    return { descriptor, pin: data.expectedManifestSha256, bytes: fields.manifestBytes.value };
+  } catch { reject("MC_MANIFEST_INPUT", "invalid"); }
+}
+function capturedBytes(value) {
+  try {
+    if (value && typeof value === "object" && !types.isProxy(value) && types.isUint8Array(value)) {
+      const typed = Object.getPrototypeOf(Uint8Array.prototype);
+      const backing = Object.getOwnPropertyDescriptor(typed, "buffer").get.call(value);
+      if (types.isSharedArrayBuffer(backing)) reject("MC_MANIFEST_INPUT", "invalid");
+    }
+    return copyBytes(value, MEMORY_CONNECTION_MANIFEST_LIMITS.manifestBytes);
+  } catch (e) {
+    if (e instanceof Rejected) throw e;
+    if (e?.code === "byte-limit") reject("MC_MANIFEST_LIMIT");
+    if (["invalid-unicode", "invalid-utf8"].includes(e?.code)) reject("MC_MANIFEST_FORMAT");
+    reject("MC_MANIFEST_INPUT", "invalid");
+  }
+}
+function resolveDeclaration(base, value) {
+  if (typeof value !== "string" || !value || value !== value.trim() || value.length > MEMORY_CONNECTION_MANIFEST_LIMITS.pathChars ||
+      CONTROL.test(value) || value.includes("\\") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) || value.includes("//") || value.endsWith("/") ||
+      PRIVATE_PATH.test(value) || isCredentialPath(value) || containsSensitiveData(value)) reject("MC_MANIFEST_IDENTITY");
+  if (path.posix.isAbsolute(value) && path.posix.normalize(value) !== value) reject("MC_MANIFEST_IDENTITY");
+  const full = path.posix.resolve(base, value);
+  if (full === "/" || full.length > MEMORY_CONNECTION_MANIFEST_LIMITS.pathChars || full.split("/").length - 1 > MEMORY_CONNECTION_MANIFEST_LIMITS.components ||
+      PRIVATE_PATH.test(full) || isCredentialPath(full)) reject("MC_MANIFEST_IDENTITY");
+  return full;
+}
+
+/**
+ * Validate a captured, reviewed byte pin and declarations only. No target IO,
+ * discovery, runtime/dependency admission, client launch or plan application.
+ * Schema loading is trusted startup; $schema in the input never selects a schema.
+ */
+export function validateMemoryConnectionManifest(input) {
+  const report = (state, details = {}) => {
+    const validated = state === "validated";
+    const result = {
+      schemaVersion: MEMORY_CONNECTION_VERSION, state,
+      manifestSha256: null, descriptorSha256: null, reasons: [], ...details,
+      facts: {
+        ...MEMORY_CONNECTION_FACTS, evidence: "provided-bytes",
+        verificationScope: "manifest-declarations-only",
+        manifestSchemaValidated: validated, manifestSecurityValidated: validated,
+        manifestDescriptorMatched: validated, manifestSemanticsVerified: false,
+        installedDependenciesVerified: false, runtimeVersionVerified: false,
+        runtimeCompatibilityVerified: false
+      }
+    };
+    if (Buffer.byteLength(JSON.stringify(result)) > MEMORY_CONNECTION_MANIFEST_LIMITS.reportBytes) reject("MC_MANIFEST_REPORT_LIMIT");
+    return freezeMemoryConnectionData(result);
+  };
+  try {
+    const { descriptor, pin, bytes: value } = inputs(input), bytes = capturedBytes(value);
+    if (!bytes.length) reject("MC_MANIFEST_FORMAT");
+    if (createHash("sha256").update(bytes).digest("hex") !== pin) reject("MC_MANIFEST_PIN_MISMATCH");
+    let manifest;
+    try { manifest = copyInertJson(parseEventJson(decode(bytes))); }
+    catch (e) { reject(["event-json-limit", "metadata-limit"].includes(e?.code) ? "MC_MANIFEST_LIMIT" : "MC_MANIFEST_FORMAT"); }
+    if (containsSensitiveData(JSON.stringify(manifest))) reject("MC_MANIFEST_SENSITIVE");
+    if (!validateSchema(manifest)) reject("MC_MANIFEST_SCHEMA");
+    const identity = descriptor.identity, base = path.posix.dirname(identity.manifestPath);
+    if (resolveDeclaration(base, manifest.source.repositoryPath) !== identity.sourcePath ||
+        resolveDeclaration(base, manifest.memory.vaultPath) !== identity.vaultPath ||
+        manifest.memory.mcpServerName !== identity.mcpName) reject("MC_MANIFEST_IDENTITY");
+    if (new Set(manifest.agents.map(a => a.id)).size !== manifest.agents.length) reject("MC_MANIFEST_AGENTS");
+    const codex = manifest.agents.filter(a => a.id === "codex");
+    if (codex.length !== 1 || codex[0].enabled !== true || codex[0].skillName !== identity.skillName) reject("MC_MANIFEST_AGENTS");
+    return report("validated", {
+      manifestSha256: pin, descriptorSha256: memoryConnectionHash(descriptor), reasons: ["MC_MANIFEST_VALIDATED"]
+    });
+  } catch (e) {
+    return report(e instanceof Rejected ? e.state : "blocked", { reasons: [e instanceof Rejected ? e.code : "MC_MANIFEST_VALIDATION"] });
+  }
+}