machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/owner-state-lock.mjs

@@ -0,0 +1,118 @@
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { createExclusiveFileSync, removeOwnedJsonFileSync } from "./exclusive-file.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync, retryTransientMultipleLinksSync } from "./secure-file.mjs";
+
+const MAX_LOCK_BYTES = 8 * 1024;
+const DEFAULT_WAIT_MS = 5_000;
+const DEFAULT_POLL_MS = 25;
+
+export async function withOwnerStateLock(root, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("owner-state lock requires a callback");
+  const requestedRoot = String(root || "").trim();
+  if (!requestedRoot) throw new Error("owner-state lock root is missing");
+  const purpose = boundedIdentifier(options.purpose, "state");
+  const fileName = boundedFileName(options.fileName, `${purpose}.lock`);
+  const label = String(options.label || purpose).replace(/[\r\n\t\u0000-\u001f\u007f]/g, " ").trim().slice(0, 80) || purpose;
+  const directory = path.resolve(requestedRoot);
+  ensureOwnerOnlyDirectorySync(directory);
+  const lockPath = path.join(directory, fileName);
+  const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_WAIT_MS);
+  const pollMs = positiveInteger(options.pollMs, DEFAULT_POLL_MS);
+  const maxAgeMs = Number.isFinite(Number(options.maxAgeMs)) ? Math.max(1, Number(options.maxAgeMs)) : Number.POSITIVE_INFINITY;
+  const deadline = createMonotonicDeadline(timeoutMs);
+  const owner = lockOwner(purpose);
+
+  while (true) {
+    try {
+      createExclusiveFileSync(lockPath, `${JSON.stringify(owner, null, 2)}\n`, { mode: 0o600 });
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const inspected = retryTransientMultipleLinksSync(() => readOwnerStateLock(lockPath, purpose));
+      if (inspected.kind === "missing") continue;
+      if (inspected.kind === "invalid") {
+        throw new Error(`${label} lock is malformed; inspect the owner-only state directory`);
+      }
+      const existing = inspected.owner;
+      const identity = inspectProcessInstance(existing, { maxAgeMs });
+      if (identity.reclaimable) {
+        if (removeOwnedJsonFileSync(lockPath, { token: existing.token, purpose }, { maxBytes: MAX_LOCK_BYTES })) continue;
+      }
+      if (deadline.expired()) {
+        const pid = Number.isInteger(existing.pid) ? `pid ${existing.pid}` : "unknown process";
+        throw new Error(`${label} state is busy (${pid}); retry after the current operation finishes`);
+      }
+      await delay(Math.min(pollMs, Math.max(1, deadline.remainingMs())));
+    }
+  }
+
+  let result;
+  let callbackError;
+  try {
+    result = await callback();
+  } catch (error) {
+    callbackError = error;
+  }
+  let releaseError;
+  try {
+    const released = removeOwnedJsonFileSync(lockPath, { token: owner.token, purpose }, { maxBytes: MAX_LOCK_BYTES });
+    if (!released) releaseError = new Error(`${label} lock changed before release; state may require inspection`);
+  } catch (error) {
+    releaseError = new Error(`${label} lock release failed; state may require inspection`, { cause: error });
+  }
+  if (callbackError && releaseError) {
+    throw new AggregateError([callbackError, releaseError], `${label} operation failed and lock release was incomplete`);
+  }
+  if (releaseError) throw releaseError;
+  if (callbackError) throw callbackError;
+  return result;
+}
+
+function lockOwner(purpose) {
+  return {
+    pid: process.pid,
+    token: randomBytes(16).toString("hex"),
+    purpose,
+    startedAt: new Date().toISOString(),
+    processStartedAt: new Date(currentProcessStartTimeMs()).toISOString(),
+    entryScript: String(process.argv[1] || "").slice(0, 4096),
+  };
+}
+
+export function readOwnerStateLock(file, purpose) {
+  let text;
+  try { text = readBoundedRegularFileSync(file, MAX_LOCK_BYTES, "owner-state lock", { verifyPathIdentity: true, rejectMultipleLinks: true }).toString("utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return { kind: "missing" }; throw error; }
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return { kind: "invalid" }; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "invalid" };
+  if (!Number.isInteger(parsed.pid) || parsed.pid <= 0) return { kind: "invalid" };
+  if (!/^[a-f0-9]{32}$/.test(String(parsed.token || ""))) return { kind: "invalid" };
+  if (parsed.purpose !== purpose) return { kind: "invalid" };
+  if (!Number.isFinite(Date.parse(String(parsed.startedAt || "")))) return { kind: "invalid" };
+  if (!Number.isFinite(Date.parse(String(parsed.processStartedAt || "")))) return { kind: "invalid" };
+  return { kind: "owner", owner: parsed };
+}
+
+function boundedIdentifier(value, fallback) {
+  const text = String(value || fallback).toLowerCase().replace(/[^a-z0-9._-]/g, "-").slice(0, 64);
+  return text || fallback;
+}
+
+function boundedFileName(value, fallback) {
+  const name = path.basename(String(value || fallback));
+  if (!/^[a-z0-9][a-z0-9._-]{0,95}\.lock$/.test(name)) throw new Error("owner-state lock filename is invalid");
+  return name;
+}
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+function delay(milliseconds) {
+  return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}

package/src/local/package-identity.mjs

@@ -0,0 +1,9 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import serverMetadata from "../shared/server-metadata.json" with { type: "json" };
+import packageManifest from "../../package.json" with { type: "json" };
+
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const packageName = String(packageManifest.name);
+export const packageVersion = String(packageManifest.version);
+export const appName = String(serverMetadata.name);

package/src/local/patch.mjs

@@ -1,3 +1,5 @@
+import { BridgeError } from "./errors.mjs";
+
 const BEGIN = "*** Begin Patch";
 const END = "*** End Patch";
 const SECTION_PREFIXES = ["*** Add File: ", "*** Update File: ", "*** Delete File: "];
@@ -5,10 +7,10 @@ const SECTION_PREFIXES = ["*** Add File: ", "*** Update File: ", "*** Delete Fil
 export function parsePatchEnvelope(input) {
   const text = String(input ?? "").replaceAll("\r\n", "\n");
   const lines = text.split("\n");
-  if (lines[0] !== BEGIN) throw new Error(`patch must start with ${BEGIN}`);
+  if (lines[0] !== BEGIN) throw new BridgeError("invalid_request", `patch must start with ${BEGIN}`, { details: { reason: "missing_begin_marker" } });
   const endIndex = lines.lastIndexOf(END);
-  if (endIndex < 1) throw new Error(`patch must end with ${END}`);
-  if (lines.slice(endIndex + 1).some((line) => line !== "")) throw new Error("unexpected content after patch envelope");
+  if (endIndex < 1) throw new BridgeError("invalid_request", `patch must end with ${END}`, { details: { reason: "missing_end_marker" } });
+  if (lines.slice(endIndex + 1).some((line) => line !== "")) throw new BridgeError("invalid_request", "unexpected content after patch envelope", { details: { reason: "trailing_content" } });
 
   const operations = [];
   let index = 1;
@@ -25,17 +27,17 @@ export function parsePatchEnvelope(input) {
         : header.startsWith(SECTION_PREFIXES[2])
           ? "delete"
           : "";
-    if (!kind) throw new Error(`invalid patch section header at line ${index + 1}`);
+    if (!kind) throw new BridgeError("invalid_request", `invalid patch section header at line ${index + 1}`, { details: { reason: "invalid_section_header", line: index + 1 } });
     const prefix = SECTION_PREFIXES[kind === "add" ? 0 : kind === "update" ? 1 : 2];
     const path = header.slice(prefix.length).trim();
-    if (!path) throw new Error(`patch ${kind} path is empty`);
+    if (!path) throw new BridgeError("invalid_request", `patch ${kind} path is empty`, { details: { reason: "empty_path", operation: kind } });
     index += 1;
 
     if (kind === "add") {
       const contentLines = [];
       while (index < endIndex && !isSectionHeader(lines[index])) {
         const line = lines[index];
-        if (!line.startsWith("+")) throw new Error(`added file content must start with + at line ${index + 1}`);
+        if (!line.startsWith("+")) throw new BridgeError("invalid_request", `added file content must start with + at line ${index + 1}`, { details: { reason: "invalid_add_line", line: index + 1 } });
         contentLines.push(line.slice(1));
         index += 1;
       }
@@ -45,7 +47,7 @@ export function parsePatchEnvelope(input) {
 
     if (kind === "delete") {
       if (index < endIndex && !isSectionHeader(lines[index]) && lines[index] !== "") {
-        throw new Error(`delete section must not contain patch body at line ${index + 1}`);
+        throw new BridgeError("invalid_request", `delete section must not contain patch body at line ${index + 1}`, { details: { reason: "unexpected_delete_body", line: index + 1 } });
       }
       operations.push({ kind, path });
       continue;
@@ -54,7 +56,7 @@ export function parsePatchEnvelope(input) {
     let moveTo = "";
     if (lines[index]?.startsWith("*** Move to: ")) {
       moveTo = lines[index].slice("*** Move to: ".length).trim();
-      if (!moveTo) throw new Error("move destination is empty");
+      if (!moveTo) throw new BridgeError("invalid_request", "move destination is empty", { details: { reason: "empty_move_destination" } });
       index += 1;
     }
     const hunks = [];
@@ -63,38 +65,38 @@ export function parsePatchEnvelope(input) {
         index += 1;
         continue;
       }
-      if (!lines[index].startsWith("@@")) throw new Error(`update hunk must start with @@ at line ${index + 1}`);
+      if (!lines[index].startsWith("@@")) throw new BridgeError("invalid_request", `update hunk must start with @@ at line ${index + 1}`, { details: { reason: "missing_hunk_header", line: index + 1 } });
       const headerText = lines[index].slice(2).trim();
       index += 1;
       const hunkLines = [];
       while (index < endIndex && !isSectionHeader(lines[index]) && !lines[index].startsWith("@@")) {
         const line = lines[index];
         if (!line || ![" ", "+", "-"].includes(line[0])) {
-          throw new Error(`invalid update line prefix at line ${index + 1}`);
+          throw new BridgeError("invalid_request", `invalid update line prefix at line ${index + 1}`, { details: { reason: "invalid_update_line", line: index + 1 } });
         }
         hunkLines.push({ type: line[0], text: line.slice(1) });
         index += 1;
       }
-      if (!hunkLines.length) throw new Error("empty update hunk");
-      if (!hunkLines.some((line) => line.type !== "+")) throw new Error("update hunk needs context or removed lines");
+      if (!hunkLines.length) throw new BridgeError("invalid_request", "empty update hunk", { details: { reason: "empty_hunk" } });
+      if (!hunkLines.some((line) => line.type !== "+")) throw new BridgeError("invalid_request", "update hunk needs context or removed lines", { details: { reason: "context_free_hunk" } });
       hunks.push({ header: headerText, lines: hunkLines });
     }
-    if (!hunks.length) throw new Error(`update section for ${path} contains no hunks`);
+    if (!hunks.length) throw new BridgeError("invalid_request", "update section contains no hunks", { details: { reason: "missing_hunks" } });
     operations.push({ kind, path, moveTo: moveTo || undefined, hunks });
   }
 
-  if (!operations.length) throw new Error("patch contains no file operations");
+  if (!operations.length) throw new BridgeError("invalid_request", "patch contains no file operations", { details: { reason: "empty_patch" } });
   const touched = new Set();
   for (const operation of operations) {
     for (const path of [operation.path, operation.moveTo].filter(Boolean)) {
-      if (touched.has(path)) throw new Error(`patch touches the same path more than once: ${path}`);
+      if (touched.has(path)) throw new BridgeError("conflict", "patch touches the same path more than once", { details: { reason: "duplicate_path" } });
       touched.add(path);
     }
   }
   return operations;
 }
 
-export function applyUpdateHunks(content, hunks, path = "file") {
+export function applyUpdateHunks(content, hunks) {
   const normalized = String(content).replaceAll("\r\n", "\n");
   const trailingNewline = normalized.endsWith("\n");
   let lines = normalized.split("\n");
@@ -106,10 +108,10 @@ export function applyUpdateHunks(content, hunks, path = "file") {
     const newLines = hunk.lines.filter((line) => line.type !== "-").map((line) => line.text);
     const matches = findSequenceMatches(lines, oldLines, searchFrom);
     if (matches.length === 0) {
-      throw new Error(`patch context not found for ${path} hunk ${hunkIndex + 1}`);
+      throw new BridgeError("conflict", "patch context did not match current file state", { details: { reason: "context_not_found", hunk: hunkIndex + 1 } });
     }
     if (matches.length > 1) {
-      throw new Error(`patch context is ambiguous for ${path} hunk ${hunkIndex + 1}`);
+      throw new BridgeError("conflict", "patch context matched more than once", { details: { reason: "context_ambiguous", hunk: hunkIndex + 1 } });
     }
     const at = matches[0];
     lines.splice(at, oldLines.length, ...newLines);

package/src/local/path-inspection.mjs

@@ -0,0 +1,23 @@
+import { lstat, opendir } from "node:fs/promises";
+
+export function isMissingPathError(error) {
+  return error?.code === "ENOENT";
+}
+
+export async function pathEntryIfExists(path, inspect = lstat) {
+  try {
+    return await inspect(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  }
+}
+
+export async function openDirectoryIfExists(path, openDirectory = opendir) {
+  try {
+    return await openDirectory(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  }
+}

package/src/local/policy.mjs

@@ -111,6 +111,25 @@ export function normalizePolicy(policy = {}) {
   return Object.freeze(normalized);
 }
 
+/** @param {PolicyInput} left @param {PolicyInput} right @param {{profile?: string, origin?: string}} [options] */
+export function intersectPolicies(left, right, options = {}) {
+  const a = normalizePolicy(left);
+  const b = normalizePolicy(right);
+  const rank = { off: 0, direct: 1, shell: 2 };
+  const execMode = rank[a.execMode] <= rank[b.execMode] ? a.execMode : b.execMode;
+  return Object.freeze({
+    profile: typeof options.profile === "string" && options.profile ? options.profile : "custom",
+    origin: typeof options.origin === "string" && options.origin ? options.origin : "custom",
+    revision: Math.max(a.revision, b.revision),
+    allowWrite: a.allowWrite && b.allowWrite,
+    allowExec: execMode !== "off",
+    execMode,
+    unrestrictedPaths: a.unrestrictedPaths && b.unrestrictedPaths,
+    minimalEnv: a.minimalEnv || b.minimalEnv,
+    exposeAbsolutePaths: a.exposeAbsolutePaths && b.exposeAbsolutePaths,
+  });
+}
+
 /** @param {PolicyCapabilities} left @param {PolicyCapabilities} right */
 export function policyCapabilitiesEqual(left, right) {
   return left.allowWrite === right.allowWrite

package/src/local/private-toolchain-integrity.mjs

@@ -0,0 +1,54 @@
+const OPERATIONAL_ERROR_CODES = new Set([
+  "EACCES",
+  "EPERM",
+  "EIO",
+  "ENOSPC",
+  "EDQUOT",
+  "ENOMEM",
+  "EROFS",
+  "EMFILE",
+  "ENFILE",
+  "EAGAIN",
+  "ENOBUFS",
+  "EINTR",
+  "ESTALE",
+  "EBUSY",
+  "ETIMEDOUT",
+]);
+
+export class PrivateToolchainIntegrityError extends Error {
+  constructor(message, options = {}) {
+    super(message, options);
+    this.name = "PrivateToolchainIntegrityError";
+    this.code = "private_toolchain_integrity_invalid";
+  }
+}
+
+export function privateToolchainIntegrityError(message, cause = undefined) {
+  return new PrivateToolchainIntegrityError(message, cause === undefined ? {} : { cause });
+}
+
+export function isPrivateToolchainIntegrityError(error) {
+  return error instanceof PrivateToolchainIntegrityError
+    || error?.code === "private_toolchain_integrity_invalid";
+}
+
+export function throwOperationalOrIntegrity(error, message) {
+  if (error instanceof TypeError || error instanceof RangeError || operationalErrorCode(error)) throw error;
+  throw privateToolchainIntegrityError(message, error);
+}
+
+export function operationalErrorCode(error) {
+  const pending = [error];
+  const seen = new Set();
+  while (pending.length) {
+    const current = pending.shift();
+    if (!current || typeof current !== "object" || seen.has(current)) continue;
+    seen.add(current);
+    const code = String(current.code || "");
+    if (OPERATIONAL_ERROR_CODES.has(code)) return code;
+    if (current.cause) pending.push(current.cause);
+    if (Array.isArray(current.errors)) pending.push(...current.errors);
+  }
+  return "";
+}