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

package/src/local/git-service.mjs

@@ -1,77 +1,203 @@
+import { randomBytes } from "node:crypto";
 import { stat } from "node:fs/promises";
-import { dirname, isAbsolute, relative, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { BridgeError } from "./errors.mjs";
+import { STRUCTURED_GIT_FIXED_ENVIRONMENT } from "./fixed-process-environment.mjs";
+import { createStructuredGitCommit } from "./git-commit.mjs";
+import { assertStructuredGitConfigSafe } from "./git-config-safety.mjs";
+import { resolveGitMetadataBoundary } from "./git-metadata-boundary.mjs";
+import { assertGitMetadataTreesSafe } from "./git-metadata-tree-safety.mjs";
+import { parseStructuredGitLog } from "./git-log-parser.mjs";
 import { clampInteger } from "./numbers.mjs";
+import { pathEntryIfExists } from "./path-inspection.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+export const MAX_GIT_COMMIT_MESSAGE_BYTES = 64 * 1024;
+const STRUCTURED_GIT_ENVIRONMENT = STRUCTURED_GIT_FIXED_ENVIRONMENT;
 
 export class GitService {
-  constructor({ resolveExistingPath, displayPath, runProcess, maximumBytes }) {
+  constructor({ resolveExistingPath, resolveWritePath, displayPath, runInternalProcess, gitExecutable, maximumBytes, disabledHooksPath = "" }) {
     this.resolveExistingPath = resolveExistingPath;
+    this.resolveWritePath = typeof resolveWritePath === "function" ? resolveWritePath : resolveExistingPath;
     this.displayPath = displayPath;
-    this.runProcess = runProcess;
+    this.runInternalProcess = runInternalProcess;
+    this.gitExecutable = typeof gitExecutable === "function" ? gitExecutable : () => String(gitExecutable || "");
     this.maximumBytes = maximumBytes;
+    this.disabledHooksPath = String(disabledHooksPath || "");
   }
 
   async status(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
     if (!git.ok) return git.result;
-    const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "status", "--short", "--branch"];
+    await this.assertSafeConfig(git, context, true);
+    const commandArgs = [...gitCommandPrefix(git), "-c", "status.submoduleSummary=false", "status", "--short", "--branch", "--ignore-submodules=all"];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 30_000, true, 512 * 1024, context);
-    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    const result = await this.runInternalProcess(
+      this.gitExecutable(), commandArgs, 30_000, true, 512 * 1024, context, git.root, null, STRUCTURED_GIT_ENVIRONMENT,
+    );
+    return { ...result, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
   }
 
   async diff(args = {}, context = {}) {
     const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
-    const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "diff", "--no-ext-diff", "--no-textconv"];
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
+    await this.assertSafeConfig(git, context, args.staged !== true);
+    const commandArgs = [...gitCommandPrefix(git), "-c", "diff.external=", "diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=all"];
     if (args.staged) commandArgs.push("--cached");
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
-    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root), staged: args.staged === true };
+    const result = await this.runInternalProcess(
+      this.gitExecutable(), commandArgs, 60_000, true, maxBytes, context, git.root, null, STRUCTURED_GIT_ENVIRONMENT,
+    );
+    return { ...result, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context), staged: args.staged === true };
   }
 
   async log(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
+    await this.assertSafeConfig(git, context, false);
     const maxCount = clampInteger(args.max_count, 20, 1, 100);
     const format = "%H%x1f%h%x1f%aI%x1f%an%x1f%ae%x1f%s%x1e";
-    const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "log", `--max-count=${maxCount}`, `--format=${format}`];
+    const commandArgs = [...gitCommandPrefix(git), "-c", "log.showSignature=false", "log", "--no-show-signature", `--max-count=${maxCount}`, `--format=${format}`];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 30_000, true, 1024 * 1024, context);
-    const commits = result.stdout.split("\x1e").map((record) => record.trim()).filter(Boolean).map((record) => {
-      const [hash, short, authored_at, author_name, author_email, subject] = record.split("\x1f");
-      const commit = { hash, short, authored_at, author_name, subject };
-      if (args.include_author_email === true) commit.author_email = author_email;
-      return commit;
-    });
-    return { code: result.code, stderr: result.stderr, commits, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    const result = await this.runInternalProcess(
+      this.gitExecutable(), commandArgs, 30_000, true, 1024 * 1024, context, git.root, null, STRUCTURED_GIT_ENVIRONMENT,
+    );
+    const commits = parseStructuredGitLog(result.stdout, args.include_author_email === true);
+    return { code: result.code, stderr: result.stderr, commits, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
   }
 
   async show(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
+    await this.assertSafeConfig(git, context, false);
     const revision = validateRevision(args.revision || "HEAD");
     const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
-    const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "show", "--no-ext-diff", "--no-textconv", "--decorate=no", revision];
+    const commandArgs = [...gitCommandPrefix(git), "-c", "diff.external=", "-c", "log.showSignature=false", "show", "--no-ext-diff", "--no-textconv", "--no-show-signature", "--ignore-submodules=all", "--decorate=no", revision];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
-    return { ...result, revision, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    const result = await this.runInternalProcess(
+      this.gitExecutable(), commandArgs, 60_000, true, maxBytes, context, git.root, null, STRUCTURED_GIT_ENVIRONMENT,
+    );
+    return { ...result, revision, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
+  }
+
+  async commit(args = {}, context = {}) {
+    const message = validateCommitMessage(args.message);
+    const git = await this.context(args.path || ".", context);
+    if (!git.ok) throw new BridgeError("execution_failed", "Git commit requires a repository path");
+    await this.assertSafeConfig(git, context, true);
+    for (const target of new Set([git.root, git.gitDir, git.commonDir, git.objectDir, ...git.metadataPaths])) {
+      await this.resolveWritePath(target, context);
+    }
+    const disabledHooksPath = this.disabledHooksPath || join(tmpdir(), `machine-bridge-mcp-disabled-hooks-${randomBytes(16).toString("hex")}`);
+    if (!isAbsolute(disabledHooksPath)) throw new BridgeError("integrity_error", "Git commit hook isolation path is unavailable");
+    await createStructuredGitCommit({
+      git,
+      message,
+      disabledHooksPath,
+      runInternalProcess: this.runInternalProcess,
+      gitExecutable: this.gitExecutable,
+      context,
+      environment: STRUCTURED_GIT_ENVIRONMENT,
+    });
+    return { code: 0, committed: true, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
+  }
+
+  assertSafeConfig(git, context, inspectWorkingTree) {
+    return assertStructuredGitConfigSafe({
+      git,
+      inspectWorkingTree,
+      resolveExistingPath: this.resolveExistingPath,
+      runInternalProcess: this.runInternalProcess,
+      gitExecutable: this.gitExecutable,
+      context,
+      environment: STRUCTURED_GIT_ENVIRONMENT,
+    });
   }
 
   async context(inputPath, context = {}) {
-    const target = await this.resolveExistingPath(inputPath);
+    const target = await this.resolveExistingPath(inputPath, context);
     const info = await stat(target);
     const cwd = info.isDirectory() ? target : dirname(target);
-    const result = await this.runProcess("git", ["-c", "core.fsmonitor=false", "-C", cwd, "rev-parse", "--show-toplevel"], 10_000, true, 512 * 1024, context);
-    if (result.code !== 0) return { ok: false, result, target };
-    const root = result.stdout.trim();
-    const repoRelative = relative(root, target);
+    const repository = await this.discoverRepository(cwd, context);
+    if (!repository) return { ok: false, target, result: { code: 128, stdout: "", stderr: "not a Git repository within the permitted path boundary" } };
+    const repoRelative = relative(repository.root, target);
     if (repoRelative.startsWith(`..${sep}`) || repoRelative === ".." || isAbsolute(repoRelative)) {
       return { ok: false, target, result: { code: 128, stdout: "", stderr: "target is outside the detected git repository" } };
     }
-    return { ok: true, target, root, pathspec: repoRelative || "" };
+    return { ok: true, target, ...repository, pathspec: repoRelative || "" };
   }
+
+  async discoverRepository(start, context = {}) {
+    let root = await this.resolveExistingPath(start, context);
+    while (true) {
+      const marker = join(root, ".git");
+      const entry = await pathEntryIfExists(marker);
+      if (entry) {
+        if (entry.isSymbolicLink()) throw new BridgeError("path_boundary", "Git metadata marker must not be a symbolic link");
+        let gitDir;
+        if (entry.isDirectory()) gitDir = await this.resolveExistingPath(marker, context);
+        else if (entry.isFile()) {
+          const value = readGitPathFile(marker, "Git metadata pointer", true);
+          gitDir = await this.resolveExistingPath(isAbsolute(value) ? value : resolve(root, value), context);
+        } else throw new BridgeError("invalid_request", "Git metadata marker must be a directory or regular pointer file");
+        const gitInfo = await stat(gitDir);
+        if (!gitInfo.isDirectory()) throw new BridgeError("invalid_request", "Git metadata directory is unavailable");
+        const commonDir = await this.resolveCommonDirectory(gitDir, context);
+        const metadata = await resolveGitMetadataBoundary({
+          gitDir,
+          commonDir,
+          resolveExistingPath: this.resolveExistingPath,
+          context,
+        });
+        if (requiresMetadataTreeScan(context)) {
+          await assertGitMetadataTreesSafe([metadata.objectDir, ...metadata.alternateObjectDirs, ...metadata.metadataPaths], { signal: context.signal });
+        }
+        return { root, gitDir, commonDir, ...metadata };
+      }
+      const parent = dirname(root);
+      if (parent === root) return null;
+      try { root = await this.resolveExistingPath(parent, context); }
+      catch (error) { if (error?.code === "path_boundary") return null; throw error; }
+    }
+  }
+
+  async resolveCommonDirectory(gitDir, context = {}) {
+    const marker = join(gitDir, "commondir");
+    const entry = await pathEntryIfExists(marker);
+    if (!entry) return gitDir;
+    if (entry.isSymbolicLink() || !entry.isFile()) throw new BridgeError("path_boundary", "Git common-directory pointer must be a regular file");
+    const value = readGitPathFile(marker, "Git common-directory pointer", false);
+    const commonDir = await this.resolveExistingPath(isAbsolute(value) ? value : resolve(gitDir, value), context);
+    const info = await stat(commonDir);
+    if (!info.isDirectory()) throw new BridgeError("invalid_request", "Git common directory is unavailable");
+    return commonDir;
+  }
+}
+
+function gitCommandPrefix(git) {
+  return [
+    "--no-pager",
+    "--literal-pathspecs",
+    `--git-dir=${git.gitDir}`,
+    `--work-tree=${git.root}`,
+    "-c", "core.fsmonitor=false",
+    "-c", "color.ui=false",
+  ];
+}
+function requiresMetadataTreeScan(context) {
+  return Boolean(context?.authority) && context.authority.effectivePolicy?.unrestrictedPaths !== true;
+}
+function readGitPathFile(file, label, gitdirPrefix) {
+  const buffer = readBoundedRegularFileSync(file, 4096, label, {
+    verifyPathIdentity: true,
+    rejectMultipleLinks: true,
+  });
+  const text = buffer.toString("utf8");
+  const pattern = gitdirPrefix ? /^gitdir: ([^\r\n\0]+)\r?\n?$/ : /^([^\r\n\0]+)\r?\n?$/;
+  const match = pattern.exec(text);
+  if (!match || !match[1]) throw new BridgeError("invalid_request", `${label} is invalid`);
+  return match[1];
 }
 
 function validateRevision(value) {
@@ -81,3 +207,12 @@ function validateRevision(value) {
   }
   return revision;
 }
+
+function validateCommitMessage(value) {
+  if (typeof value !== "string" || !value.trim()) throw new BridgeError("invalid_request", "Git commit message is required");
+  if (value.includes("\0")) throw new BridgeError("invalid_request", "Git commit message contains a NUL byte");
+  if (Buffer.byteLength(value, "utf8") > MAX_GIT_COMMIT_MESSAGE_BYTES) {
+    throw new BridgeError("limit_exceeded", `Git commit message exceeds ${MAX_GIT_COMMIT_MESSAGE_BYTES} bytes`);
+  }
+  return value;
+}

package/src/local/hardened-npm-download-timeout.mjs

@@ -0,0 +1,46 @@
+const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+const DEFAULT_MAXIMUM_DURATION_MS = 300_000;
+
+export function createHardenedDownloadTimeout(artifactName, request, options = {}) {
+  const schedule = typeof options.schedule === "function" ? options.schedule : setTimeout;
+  const cancel = typeof options.cancel === "function" ? options.cancel : clearTimeout;
+  const idleMs = boundedDuration(options.idleMs, DEFAULT_IDLE_TIMEOUT_MS, 1, DEFAULT_IDLE_TIMEOUT_MS);
+  const maximumMs = boundedDuration(options.maximumMs, DEFAULT_MAXIMUM_DURATION_MS, idleMs, DEFAULT_MAXIMUM_DURATION_MS);
+  let idleTimer = null;
+  let maximumTimer = null;
+  let finished = false;
+
+  const cancelTimers = () => {
+    if (idleTimer !== null) cancel(idleTimer);
+    if (maximumTimer !== null) cancel(maximumTimer);
+    idleTimer = null;
+    maximumTimer = null;
+  };
+  const fail = (message) => {
+    if (finished) return;
+    finished = true;
+    cancelTimers();
+    request.destroy(Object.assign(new Error(`${artifactName} tarball ${message}`), { code: "ETIMEDOUT" }));
+  };
+  const armIdle = () => {
+    if (finished) return;
+    if (idleTimer !== null) cancel(idleTimer);
+    idleTimer = schedule(() => fail("download stalled"), idleMs);
+  };
+
+  maximumTimer = schedule(() => fail("download exceeded its maximum duration"), maximumMs);
+  armIdle();
+  return Object.freeze({
+    progress: armIdle,
+    clear() {
+      finished = true;
+      cancelTimers();
+    },
+  });
+}
+
+function boundedDuration(value, fallback, minimum, maximum) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(maximum, Math.max(minimum, Math.floor(number)));
+}

package/src/local/hardened-npm-download.mjs

@@ -0,0 +1,109 @@
+import https from "node:https";
+import { createHardenedDownloadTimeout } from "./hardened-npm-download-timeout.mjs";
+const MAX_DOWNLOAD_BYTES = 24 * 1024 * 1024;
+const DOWNLOAD_ATTEMPTS = 3; const RETRY_BASE_MS = 750;
+const HTTP_PROTOCOLS = new Set(["http:", "https:"]); const CONTROL_CHARACTERS = /[\0\r\n]/;
+const PROXY_URL_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"]; const NO_PROXY_KEYS = ["NO_PROXY", "no_proxy"];
+const TRANSIENT_NETWORK_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ENETUNREACH", "ECONNREFUSED", "ECONNABORTED", "EPIPE"]);
+export async function downloadHardenedNpmArtifact(artifact, options = {}) {
+  for (let attempt = 1; attempt <= DOWNLOAD_ATTEMPTS; attempt += 1) {
+    try { return await downloadAttempt(artifact, options); }
+    catch (error) {
+      if (attempt === DOWNLOAD_ATTEMPTS || !retryableDownloadError(error)) throw error;
+      await retryDelay(attempt, options);
+    }
+  }
+  throw new Error(`${artifact.name} tarball download exhausted retries`);
+}
+function downloadAttempt(artifact, options) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const target = new URL(artifact.url);
+    if (target.protocol !== "https:" || target.username || target.password || target.port || target.search || target.hash) {
+      rejectPromise(new Error(`${artifact.name} tarball URL is not an exact HTTPS registry URL`)); return;
+    }
+    let context = null;
+    let request;
+    try {
+      context = prepareRequestAgent(target, options);
+      const requestFn = typeof options.request === "function" ? options.request : https.request;
+      request = requestFn({
+        protocol: target.protocol, hostname: target.hostname, method: "GET", path: target.pathname,
+        headers: { Accept: "application/octet-stream", "User-Agent": "machine-bridge-mcp-hardened-npm" },
+        ...(context.agent ? { agent: context.agent } : {}),
+      });
+    } catch (error) { rejectPromise(cleanupResult(context, error, `${artifact.name} tarball download setup failed`)); return; }
+    let settled = false;
+    const timeout = createHardenedDownloadTimeout(artifact.name, request, options.downloadTimeout);
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true; timeout.clear();
+      const outcome = cleanupResult(context, error, `${artifact.name} tarball download failed`);
+      if (outcome) rejectPromise(outcome); else resolvePromise(value);
+    };
+    request.once("error", (error) => finish(error));
+    request.once("response", (response) => {
+      timeout.progress(); const status = Number(response.statusCode || 0);
+      if (status !== 200) {
+        response.resume();
+        finish(Object.assign(new Error(`failed to download ${artifact.name} ${artifact.version}: HTTP ${status || "unknown"}`), { statusCode: status })); return;
+      }
+      const declaredBytes = Number(response.headers["content-length"]);
+      if (Number.isFinite(declaredBytes) && declaredBytes > artifact.maximumBytes) {
+        response.destroy(); finish(new Error(`${artifact.name} tarball exceeds its byte limit`)); return;
+      }
+      const chunks = []; let total = 0;
+      response.on("data", (chunk) => {
+        timeout.progress(); const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); total += buffer.length;
+        if (total > artifact.maximumBytes || total > MAX_DOWNLOAD_BYTES) {
+          response.destroy(Object.assign(new Error(`${artifact.name} tarball exceeds its byte limit`), { code: "ERR_RESPONSE_TOO_LARGE" })); return;
+        }
+        chunks.push(buffer);
+      });
+      response.once("error", (error) => finish(error)); response.once("aborted", () => finish(Object.assign(new Error(`${artifact.name} tarball response aborted`), { code: "ECONNRESET" })));
+      response.once("end", () => finish(null, Buffer.concat(chunks, total)));
+    });
+    try { request.end(); } catch (error) { finish(error); }
+  });
+}
+function prepareRequestAgent(target, options) {
+  if (typeof options.proxyAgentForUrl === "function") return { agent: options.proxyAgentForUrl(target.href, options.proxyResolver)?.agent || null };
+  if (Object.hasOwn(options, "agent")) return { agent: options.agent || null };
+  const proxyEnv = normalizeProxyEnvironment(options.proxyEnv ?? process.env);
+  const agent = (typeof options.createAgent === "function" ? options.createAgent : proxyAgentForHttp)(proxyEnv);
+  if (!agent || typeof agent !== "object") throw new Error("hardened npm proxy agent could not be initialized");
+  return { agent, dispose: typeof agent.destroy === "function" ? () => agent.destroy() : null };
+}
+function normalizeProxyEnvironment(source) {
+  if (!source || typeof source !== "object") throw proxyConfigurationError("HTTP proxy environment must be an object");
+  const normalized = {};
+  for (const key of PROXY_URL_KEYS) {
+    if (source[key] === undefined || source[key] === null) continue;
+    const value = String(source[key]).trim();
+    if (!value) { normalized[key] = ""; continue; }
+    if (CONTROL_CHARACTERS.test(value)) throw proxyConfigurationError("HTTP proxy configuration contains a prohibited control character");
+    let proxyUrl; try { proxyUrl = new URL(value); } catch { throw proxyConfigurationError("HTTP proxy configuration is not a valid URL"); }
+    if (!HTTP_PROTOCOLS.has(proxyUrl.protocol)) throw proxyConfigurationError("HTTP proxy configuration must use HTTP or HTTPS");
+    normalized[key] = proxyUrl.href;
+  }
+  for (const key of NO_PROXY_KEYS) {
+    if (source[key] === undefined || source[key] === null) continue;
+    const value = String(source[key]);
+    if (CONTROL_CHARACTERS.test(value)) throw proxyConfigurationError("NO_PROXY configuration contains a prohibited control character");
+    normalized[key] = value;
+  }
+  return normalized;
+}
+function retryableDownloadError(error) {
+  const status = Number(error?.statusCode || 0);
+  return TRANSIENT_NETWORK_CODES.has(String(error?.code || "")) || String(error?.message || "").trim().toLowerCase() === "aborted" || status === 429 || (status >= 500 && status <= 599);
+}
+function retryDelay(attempt, options) {
+  const milliseconds = Math.min(RETRY_BASE_MS * attempt, 3_000);
+  return typeof options.sleep === "function" ? Promise.resolve(options.sleep(milliseconds)) : new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); });
+}
+function proxyAgentForHttp(proxyEnv) { return new https.Agent({ proxyEnv }); }
+function proxyConfigurationError(message) { return Object.assign(new Error(message), { code: "http_proxy_configuration" }); }
+function cleanupResult(context, primary, message) {
+  try { context?.dispose?.(); return primary; }
+  catch (cleanup) { return primary ? new AggregateError([primary, cleanup], `${message} and proxy-agent cleanup was incomplete`) : cleanup; }
+}

package/src/local/hardened-npm-extract.mjs

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { resolveTrustedExecutable } from "./trusted-executable.mjs";
+
+export function resolveHardenedNpmTarExecutable(stateRoot, options = {}) {
+  const windowsRoot = String(options.windowsRoot || process.env.SystemRoot || process.env.WINDIR || "C:\\Windows");
+  return resolveTrustedExecutable({
+    platform: options.platform,
+    candidates: [
+      options.tarExecutable,
+      path.join(windowsRoot, "System32", "tar.exe"),
+      "/usr/bin/tar",
+      "/bin/tar",
+      "/usr/local/bin/tar",
+    ].filter(Boolean),
+    stateRoot,
+    home: options.home,
+    label: "tar extractor",
+    reason: "trusted_tar_unavailable",
+  });
+}

package/src/local/hardened-npm-verification.mjs

@@ -0,0 +1,104 @@
+import { lstatSync } from "node:fs";
+import path from "node:path";
+import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import {
+  privateToolchainIntegrityError,
+  throwOperationalOrIntegrity,
+} from "./private-toolchain-integrity.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+
+const MAX_MARKER_BYTES = 16 * 1024;
+const HARDENED_NPM_MARKER = ".machine-bridge-mcp-hardened-npm.json";
+
+export function verifyHardenedNpmTree(root, artifacts, execute) {
+  const target = path.resolve(root);
+  ensureOwnerOnlyDirectorySync(target);
+  const npmRoot = path.join(target, "package");
+  const nodeModules = path.join(npmRoot, "node_modules");
+  requireRealDirectory(npmRoot, "hardened npm package root");
+  requireRealDirectory(nodeModules, "hardened npm node_modules");
+  verifyHardenedPackageIdentity(npmRoot, "npm", artifacts[0].version);
+  verifyHardenedPackageIdentity(path.join(nodeModules, "undici"), "undici", artifacts[1].version);
+  verifyHardenedPackageIdentity(path.join(nodeModules, "brace-expansion"), "brace-expansion", artifacts[2].version);
+  const binRoot = path.join(npmRoot, "bin");
+  requireRealDirectory(binRoot, "hardened npm bin directory");
+  const cli = path.join(binRoot, "npm-cli.js");
+  let info;
+  try { info = lstatSync(cli); }
+  catch (error) { throwOperationalOrIntegrity(error, "hardened npm CLI is missing or unreadable"); }
+  if (info.isSymbolicLink() || !info.isFile() || Number(info.nlink) !== 1 || (process.platform !== "win32" && (Number(info.mode) & 0o022) !== 0)) {
+    throw privateToolchainIntegrityError("hardened npm CLI is not a private real regular file");
+  }
+  const reported = String(execute(process.execPath, [cli, "--version"], { capture: true })).trim();
+  if (reported !== artifacts[0].version) {
+    throw privateToolchainIntegrityError(`hardened npm CLI reported ${reported || "no version"}`);
+  }
+  return Object.freeze({
+    cli,
+    version: artifacts[0].version,
+    undiciVersion: artifacts[1].version,
+    braceExpansionVersion: artifacts[2].version,
+  });
+}
+
+function requireRealDirectory(directory, label) {
+  let info;
+  try { info = lstatSync(directory); }
+  catch (error) { throwOperationalOrIntegrity(error, `${label} is missing or unreadable`); }
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw privateToolchainIntegrityError(`${label} is not a real directory`);
+  }
+}
+
+export function readHardenedNpmMarker(root) {
+  let bytes;
+  try {
+    bytes = readBoundedRegularFileSync(path.join(root, HARDENED_NPM_MARKER), MAX_MARKER_BYTES, "hardened npm marker", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throwOperationalOrIntegrity(error, "hardened npm marker is structurally invalid");
+  }
+  try { return JSON.parse(bytes.toString("utf8")); }
+  catch (error) { throw privateToolchainIntegrityError("hardened npm marker is not valid JSON", error); }
+}
+
+export function hardenedNpmMarkerMatches(marker, identity) {
+  return marker?.schema_version === 1
+    && marker.digest === identity.digest
+    && marker.npm === identity.npmVersion
+    && marker.undici === identity.undiciVersion
+    && marker.brace_expansion === identity.braceExpansionVersion;
+}
+
+export function writeHardenedNpmMarker(root, identity) {
+  replaceFileAtomicallySync(path.join(root, HARDENED_NPM_MARKER), `${JSON.stringify({
+    schema_version: 1,
+    digest: identity.digest,
+    npm: identity.npmVersion,
+    undici: identity.undiciVersion,
+    brace_expansion: identity.braceExpansionVersion,
+  }, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function verifyHardenedPackageIdentity(directory, name, version) {
+  requireRealDirectory(directory, `${name} package directory`);
+  const file = path.join(directory, "package.json");
+  let bytes;
+  try {
+    bytes = readBoundedRegularFileSync(file, 2 * 1024 * 1024, `${name} package manifest`, {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+  } catch (error) {
+    throwOperationalOrIntegrity(error, `${name} package manifest is missing or structurally invalid`);
+  }
+  let manifest;
+  try { manifest = JSON.parse(bytes.toString("utf8")); }
+  catch (error) { throw privateToolchainIntegrityError(`${name} package manifest is not valid JSON`, error); }
+  if (manifest?.name !== name || manifest?.version !== version) {
+    throw privateToolchainIntegrityError(`${name} package identity does not match ${version}`);
+  }
+}