@remcp/runtime 0.2.154 → 0.2.156

package/src/tools/files-archive-actions.mjs

@@ -0,0 +1,166 @@
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, createReadStream } from 'node:fs';
+import { access, chmod, chown, copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { liveConfig, runtimeConfig } from '../config.mjs';
+import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
+import { diffStats, unifiedDiff } from '../diff.mjs';
+import { describeFilesystemFailure } from '../permissions.mjs';
+import { capturePortalScreenshot, isWaylandSession } from '../screenshot-portal.mjs';
+import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
+import { countEvent, recordEvent } from '../telemetry.mjs';
+import { clampInteger, decodeText, displayPath, fail, fitsOutput, globToRegExp, image, isInsideRoot, looksBinary, multi, pageLines, resolveSafePath, splitLines, text, throwIfCancelled } from '../util.mjs';
+
+
+import { ensureDirectoryPath } from './files-secure-paths.mjs';
+import { MAX_ARCHIVE_EXPANDED_BYTES, archiveExpandedSize, archiveTarExpandedSize, archiveTool, assertArchiveExpandedSize, assertExtractedTree, copyTreeContents, installExtractedTree, moveArchiveFile, recoverExtractionArtifacts, safeArchiveEntry, snapshotRegularFile } from './files-archive-safety.mjs';
+
+export async function createArchiveTool(args, extra = {}) {
+  const tools = archiveTool();
+  const sources = Array.isArray(args.paths) ? args.paths : [args.paths].filter(Boolean);
+  if (!sources.length) fail('paths must list at least one file or directory');
+  const resolved = [];
+  for (const entry of sources) {
+    throwIfCancelled(extra.signal);
+    resolved.push(await resolveSafePath(entry, 'paths[]'));
+  }
+  const destination = await resolveSafePath(args.destination, 'destination');
+  const existingDestination = await lstat(destination).catch(() => null);
+  if (existingDestination?.isSymbolicLink()) fail('Archive destination cannot be a symbolic link');
+  const format = String(args.format || (destination.endsWith('.zip') ? 'zip' : 'tar.gz')).toLowerCase();
+  const baseDir = path.dirname(resolved[0]);
+  const names = resolved.map(entry => path.relative(baseDir, entry));
+  if (names.some(name => !name || name.startsWith('..') || path.isAbsolute(name))) fail('Archive sources must share one parent directory');
+  const archiveNames = names.map(name => {
+    const portable = name.split(path.sep).join('/');
+    return portable.startsWith('-') ? `./${portable}` : portable;
+  });
+  const suffix = format === 'zip' ? '.zip' : format === 'tar' ? '.tar' : '.tar.gz';
+  const stagingDirectory = await mkdtemp(path.join(os.tmpdir(), 'remcp-archive-'));
+  if (resolved.some(entry => !path.relative(entry, stagingDirectory).startsWith('..') && !path.isAbsolute(path.relative(entry, stagingDirectory)))) {
+    await rm(stagingDirectory, { recursive: true, force: true });
+    fail('Archive source must not contain the system temporary directory');
+  }
+   const staging = path.join(stagingDirectory, `payload${suffix}`);
+   const snapshotRoot = path.join(stagingDirectory, 'source');
+   try {
+      await ensureDirectoryPath(snapshotRoot, { allowOutside:true });
+
+     const snapshotState = { entries: 0, bytes: 0, maxBytes: MAX_ARCHIVE_EXPANDED_BYTES, signal: extra.signal };
+     for (let index = 0; index < resolved.length; index += 1) {
+       throwIfCancelled(extra.signal);
+       const snapshotPath = path.join(snapshotRoot, names[index]);
+        await ensureDirectoryPath(path.dirname(snapshotPath), { allowOutside:true });
+
+       await copyTreeContents(resolved[index], snapshotPath, snapshotState);
+     }
+     if (format === 'zip') {
+       if (process.platform === 'win32') {
+         if (!tools.tar) fail('Windows archive backend is unavailable: tar.exe is required');
+         const result = spawnSync(tools.tar, ['-a', '-c', '-f', staging, '--', ...archiveNames], { cwd: snapshotRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+         if (result.status !== 0) fail(`tar.exe ZIP creation failed: ${(result.stderr || result.stdout || '').trim() || `exit ${result.status}`}`);
+       } else {
+         if (!tools.zip) fail('zip is not installed on this device; use format "tar.gz"');
+         const result = spawnSync(tools.zip, ['-r', '-q', '-y', staging, '--', ...archiveNames], { cwd: snapshotRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+         if (result.status !== 0) fail(`zip failed: ${(result.stderr || result.stdout || '').trim() || `exit ${result.status}`}`);
+       }
+    } else if (format === 'tar' || format === 'tar.gz' || format === 'tgz') {
+      if (!tools.tar) fail('tar is not installed on this device');
+      const flags = format === 'tar' ? '-cf' : '-czf';
+       const result = spawnSync(tools.tar, [flags, staging, '--', ...archiveNames], { cwd: snapshotRoot, encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+      if (result.status !== 0) fail(`tar failed: ${(result.stderr || result.stdout || '').trim() || `exit ${result.status}`}`);
+     } else {
+       fail('format must be tar, tar.gz, or zip');
+     }
+      const stagedInfo = await stat(staging);
+      assertArchiveExpandedSize(stagedInfo.size, 'archive output');
+
+      await moveArchiveFile(staging, destination);
+
+     const info = await stat(destination).catch(() => null);
+     const note = ' (built outside the tree in temporary staging and committed atomically)';
+
+    return text(`Created ${displayPath(destination)} (${format}, ${info?.size ?? 0} bytes) from ${resolved.length} path(s)${note}.`);
+  } finally {
+    if (stagingDirectory) await rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+
+export function archiveFormatForPath(value) {
+  if (/\.zip$/i.test(value)) return 'zip';
+  if (/\.(tar\.gz|tgz)$/i.test(value)) return 'tar.gz';
+  if (/\.(tar\.bz2|tbz2?)$/i.test(value)) return 'tar.bz2';
+  if (/\.tar\.xz$/i.test(value)) return 'tar.xz';
+  return 'tar';
+}
+
+export function archiveSnapshotSuffix(format) {
+  if (format === 'zip') return '.zip';
+  if (format === 'tar.bz2') return '.tar.bz2';
+  if (format === 'tar.xz') return '.tar.xz';
+  if (format === 'tar.gz') return '.tar.gz';
+  return '.tar';
+}
+
+export async function extractArchiveTool(args) {
+  const tools = archiveTool();
+  const archive = await resolveSafePath(args.archive, 'archive');
+  const destination = await resolveSafePath(args.destination || path.dirname(archive), 'destination');
+  if (destination === path.parse(destination).root) fail('Archive destination cannot be a filesystem root');
+  const parent = path.dirname(destination);
+  const backupPrefix = `.remcp-extract-backup-${createHash('sha256').update(destination).digest('hex').slice(0, 16)}-`;
+  const format = archiveFormatForPath(archive);
+  const stagingDirectory = await mkdtemp(path.join(os.tmpdir(), 'remcp-extract-'));
+  const archiveSnapshot = path.join(stagingDirectory, `source${archiveSnapshotSuffix(format)}`);
+  const staging = path.join(stagingDirectory, 'tree');
+  try {
+    await mkdir(staging, { mode: 0o700 });
+    await snapshotRegularFile(archive, archiveSnapshot, MAX_ARCHIVE_EXPANDED_BYTES);
+    await recoverExtractionArtifacts(parent, destination, backupPrefix);
+    const existingDestination = await lstat(destination).catch(() => null);
+    if (existingDestination?.isSymbolicLink() || (existingDestination && !existingDestination.isDirectory())) fail('Archive destination is not a safe directory');
+    if (format === 'zip' && process.platform !== 'win32') {
+      if (!tools.unzip) fail('unzip is not installed on this device');
+      const listing = spawnSync(tools.unzip, ['-Z', '-1', archiveSnapshot], { encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+      if (listing.error || listing.status !== 0) fail(`Could not inspect ZIP archive: ${(listing.stderr || listing.error?.message || `exit ${listing.status}`).trim()}`);
+      const names = String(listing.stdout || '').split(/\r?\n/).filter(Boolean);
+      if (names.length > 100_000 || names.some(name => !safeArchiveEntry(name))) fail('ZIP archive contains an unsafe path or too many entries');
+      const details = spawnSync(tools.unzip, ['-Z', '-v', archiveSnapshot], { encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+      if (details.error || details.status !== 0) fail(`Could not inspect ZIP sizes: ${(details.stderr || details.error?.message || `exit ${details.status}`).trim()}`);
+      const detailText = String(details.stdout || '');
+      if (/symbolic link|Unix file attributes \([^)]*\b12\d{4}/i.test(detailText)) fail('ZIP archive contains a symbolic link');
+      const expandedBytes = archiveExpandedSize(detailText.split(/\r?\n/), /uncompressed size:\s*(\d+)\s*bytes/i, 'ZIP archive', names.length);
+      assertArchiveExpandedSize(expandedBytes, 'ZIP archive');
+      const result = spawnSync(tools.unzip, ['-o', '-q', archiveSnapshot, '-d', staging], { encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+      if (result.status !== 0) fail(`unzip failed: ${(result.stderr || result.stdout || '').trim() || `exit ${result.status}`}`);
+    } else {
+      if (!tools.tar) fail(process.platform === 'win32' ? 'Windows archive backend is unavailable: tar.exe is required' : 'tar is not installed on this device');
+      const listFlags = format === 'tar.gz' ? '-tzf' : format === 'tar.bz2' ? '-tjf' : format === 'tar.xz' ? '-tJf' : '-tf';
+      const listing = spawnSync(tools.tar, [listFlags, archiveSnapshot], { encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+      if (listing.error || listing.status !== 0) fail(`Could not inspect archive: ${(listing.stderr || listing.error?.message || `exit ${listing.status}`).trim()}`);
+      const names = String(listing.stdout || '').split(/\r?\n/).filter(Boolean);
+      if (names.length > 100_000 || names.some(name => !safeArchiveEntry(name))) fail('Archive contains an unsafe path or too many entries');
+      const verboseFlags = format === 'tar.gz' ? '-tvzf' : format === 'tar.bz2' ? '-tvjf' : format === 'tar.xz' ? '-tvJf' : '-tvf';
+      const details = spawnSync(tools.tar, [verboseFlags, archiveSnapshot], { encoding: 'utf8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 });
+      if (details.error || details.status !== 0) fail(`Could not inspect archive sizes: ${(details.stderr || details.error?.message || `exit ${details.status}`).trim()}`);
+      const detailLines = String(details.stdout || '').split(/\r?\n/);
+      if (detailLines.some(line => /^[bclph]/.test(line))) fail('Archive contains a link or special file; archive destination is unsafe');
+      const expandedBytes = archiveTarExpandedSize(detailLines, 'archive', names.length);
+      assertArchiveExpandedSize(expandedBytes, 'archive');
+      const flags = format === 'tar.gz' ? '-xzf' : format === 'tar.bz2' ? '-xjf' : format === 'tar.xz' ? '-xJf' : '-xf';
+      const result = spawnSync(tools.tar, [flags, archiveSnapshot, '-C', staging], { encoding: 'utf8', timeout: 120_000, maxBuffer: 16 * 1024 * 1024 });
+      if (result.status !== 0) fail(`tar failed: ${(result.stderr || result.stdout || '').trim() || `exit ${result.status}`}`);
+    }
+    await assertExtractedTree(staging);
+    await installExtractedTree(staging, destination);
+    const entries = await readdir(destination).catch(() => []);
+    return text(`Extracted ${displayPath(archive)} into ${displayPath(destination)} (${entries.length} top-level entries).`);
+  } finally {
+    await rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+
+// --- screenshots ----------------------------------------------------------------------

package/src/tools/files-archive-safety.mjs

@@ -0,0 +1,395 @@
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, createReadStream } from 'node:fs';
+import { access, chmod, chown, copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { liveConfig, runtimeConfig } from '../config.mjs';
+import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
+import { diffStats, unifiedDiff } from '../diff.mjs';
+import { describeFilesystemFailure } from '../permissions.mjs';
+import { capturePortalScreenshot, isWaylandSession } from '../screenshot-portal.mjs';
+import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
+import { countEvent, recordEvent } from '../telemetry.mjs';
+import { clampInteger, decodeText, displayPath, fail, fitsOutput, globToRegExp, image, isInsideRoot, looksBinary, multi, pageLines, resolveSafePath, splitLines, text, throwIfCancelled } from '../util.mjs';
+
+
+import { READ_NOFOLLOW_NONBLOCK, WRITE_CREATE_NOFOLLOW, ensureDirectoryPath, openDirectoryPath, openRegularFile } from './files-secure-paths.mjs';
+
+export const MAX_ARCHIVE_EXPANDED_BYTES = Math.min(
+  4 * 1024 * 1024 * 1024,
+  Math.max(64 * 1024 * 1024, Number(process.env.REMCP_MAX_ARCHIVE_EXPANDED_BYTES) || 512 * 1024 * 1024),
+);
+
+export function safeArchiveEntry(name) {
+  const normalized = String(name || '').replace(/\\/g, '/');
+  return Boolean(normalized) && !normalized.startsWith('/') && !/^[A-Za-z]:\//.test(normalized) && !normalized.split('/').includes('..');
+}
+
+export function archiveExpandedSize(lines, pattern, label, expectedEntries = null) {
+  let total = 0;
+  let matched = 0;
+  for (const line of lines) {
+    const match = line.match(pattern);
+    if (!match) continue;
+    total += Number(match[1]);
+    matched += 1;
+    if (!Number.isSafeInteger(total) || total > MAX_ARCHIVE_EXPANDED_BYTES) fail(`${label} exceeds the ${MAX_ARCHIVE_EXPANDED_BYTES}-byte extraction limit`);
+  }
+  if ((!matched && expectedEntries !== 0) || (expectedEntries !== null && matched < expectedEntries)) fail(`Could not determine ${label} size safely`);
+  return total;
+}
+
+export function tarEntrySize(line) {
+  const tokens = String(line || '').trim().split(/\s+/);
+  for (const index of [2, 3, 4]) {
+    const size = Number(tokens[index]);
+    if (!Number.isSafeInteger(size) || size < 0) continue;
+    const tail = tokens.slice(index + 1);
+    const gnuDate = /^\d{4}-\d{2}-\d{2}$/.test(tail[0] || '');
+    const bsdMonthDay = /^[A-Z][a-z]{2}$/.test(tail[0] || '') && /^\d{1,2}$/.test(tail[1] || '');
+    const bsdTime = /^\d{2}:\d{2}(?::\d{2})?$/.test(tail[2] || '');
+    const bsdDate = bsdMonthDay && (bsdTime || /^\d{4}$/.test(tail[2] || ''));
+    if (gnuDate || bsdDate) return size;
+  }
+  return null;
+}
+
+export function archiveTarExpandedSize(lines, label, expectedEntries) {
+  let total = 0;
+  let matched = 0;
+  for (const line of lines) {
+    const size = tarEntrySize(line);
+    if (size === null) continue;
+    total += size;
+    matched += 1;
+    if (!Number.isSafeInteger(total) || total > MAX_ARCHIVE_EXPANDED_BYTES) fail(`${label} exceeds the ${MAX_ARCHIVE_EXPANDED_BYTES}-byte extraction limit`);
+  }
+  if (matched < expectedEntries) fail(`Could not determine ${label} size safely`);
+  return total;
+}
+
+export function assertArchiveExpandedSize(bytes, label) {
+  if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > MAX_ARCHIVE_EXPANDED_BYTES) {
+    fail(`${label} exceeds the ${MAX_ARCHIVE_EXPANDED_BYTES}-byte extraction limit`);
+  }
+}
+
+export async function assertExtractedTree(root, state = { entries: 0, bytes: 0 }) {
+  const info = await lstat(root);
+  if (info.isSymbolicLink()) fail('Archive extraction produced a symbolic link');
+  if (!info.isDirectory() && !info.isFile()) fail('Archive extraction produced a special file');
+  state.entries += 1;
+  state.bytes += info.isFile() ? info.size : 0;
+  if (state.entries > 100_000 || state.bytes > MAX_ARCHIVE_EXPANDED_BYTES) fail('Archive extraction exceeded the safety limit');
+  if (!info.isDirectory()) return;
+  for (const entry of await readdir(root, { withFileTypes: true })) await assertExtractedTree(path.join(root, entry.name), state);
+}
+
+export async function openArchiveSource(absolute) {
+  return openRegularFile(absolute, READ_NOFOLLOW_NONBLOCK);
+}
+
+export async function snapshotRegularFile(source, destination, maxBytes) {
+  const sourceInfo = await lstat(source);
+  if (sourceInfo.isSymbolicLink()) fail(`Archive source is a symbolic link: ${displayPath(source)}`);
+  if (!sourceInfo.isFile()) fail(`Archive source is not a regular file: ${displayPath(source)}`);
+  const opened = await openArchiveSource(source);
+  const { handle, info } = opened;
+  let output;
+  try {
+    if (info.size > maxBytes) fail(`Archive is ${info.size} bytes, above the ${maxBytes}-byte snapshot limit`);
+    output = await open(destination, WRITE_CREATE_NOFOLLOW, 0o400);
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let offset = 0;
+    for (;;) {
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+      if (!bytesRead) break;
+      if (!Number.isSafeInteger(offset + bytesRead) || offset + bytesRead > maxBytes) {
+        fail(`Archive grew beyond the ${maxBytes}-byte snapshot limit`);
+      }
+      let written = 0;
+      while (written < bytesRead) {
+        const result = await output.write(buffer, written, bytesRead - written, offset + written);
+        if (!result.bytesWritten) throw new Error('Could not finish writing the archive snapshot');
+        written += result.bytesWritten;
+      }
+      offset += bytesRead;
+    }
+    await output.truncate(offset);
+    await output.sync();
+    await output.chmod(0o400);
+    return offset;
+  } finally {
+    if (output) await output.close().catch(() => {});
+    await opened.close().catch(() => {});
+  }
+}
+
+export async function copyOpenRegularFile(sourceHandle, sourceInfo, destinationPath, state) {
+  const mode = sourceInfo.mode & 0o777;
+  const currentBytes = state.bytes || 0;
+  if (state.maxBytes !== undefined && sourceInfo.size > state.maxBytes - currentBytes) {
+    fail(`Archive contents exceed the ${state.maxBytes}-byte extraction limit`);
+  }
+  // Never validate a pathname and then truncate it: another local process could replace that entry
+  // between the check and open. Build a brand-new inode beside the destination and commit it with
+  // rename(), which replaces the directory entry atomically without following a raced symlink or
+  // truncating a hard-linked file.
+  const temporary = path.join(
+    path.dirname(destinationPath),
+    `.${path.basename(destinationPath)}.remcp-${randomUUID()}.tmp`,
+  );
+  let output;
+  try {
+    output = await open(temporary, WRITE_CREATE_NOFOLLOW, mode);
+    const outputInfo = await output.stat();
+    if (!outputInfo.isFile()) fail('Archive contains a link or special file; archive destination is unsafe');
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let offset = 0;
+    for (;;) {
+      const { bytesRead } = await sourceHandle.read(buffer, 0, buffer.length, offset);
+      if (!bytesRead) break;
+      if (!Number.isSafeInteger(offset + bytesRead) || (state.maxBytes !== undefined && currentBytes + offset + bytesRead > state.maxBytes)) {
+        fail(`Archive contents exceed the ${state.maxBytes}-byte extraction limit`);
+      }
+      let written = 0;
+      while (written < bytesRead) {
+        const result = await output.write(buffer, written, bytesRead - written, offset + written);
+        if (!result.bytesWritten) throw new Error('Could not finish copying archive contents');
+        written += result.bytesWritten;
+      }
+      offset += bytesRead;
+    }
+    await output.sync();
+    await output.chmod(mode);
+    await output.close();
+    output = null;
+    await rename(temporary, destinationPath);
+    state.bytes = currentBytes + offset;
+  } finally {
+    if (output) await output.close().catch(() => {});
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+export async function copyTreeContents(source, destination, state = { entries: 0, bytes: 0, maxBytes: MAX_ARCHIVE_EXPANDED_BYTES }) {
+  throwIfCancelled(state.signal);
+  const initial = await lstat(source);
+  if (initial.isSymbolicLink() || (!initial.isDirectory() && !initial.isFile())) fail('Archive contains symbolic links or special files; archive destination is unsafe');
+  state.entries += 1;
+  if (state.entries > 100_000) fail('Archive contains too many entries');
+  if (initial.isFile()) {
+    const opened = source.startsWith('/proc/self/fd/')
+      ? await openRegularFile(source, READ_NOFOLLOW_NONBLOCK)
+      : await openArchiveSource(source);
+    try { await copyOpenRegularFile(opened.handle, opened.info, destination, state); }
+    finally { if (opened.close) await opened.close(); else await opened.handle.close(); }
+    return;
+  }
+  let directoryHandle = null;
+  let sourcePath = source;
+  let info = initial;
+  try {
+    try {
+      directoryHandle = await openDirectoryPath(source, { allowOutside:state.allowOutsideSource === true });
+      info = await directoryHandle.handle.stat();
+      if (!info.isDirectory()) fail('Archive contains a link or special file; archive destination is unsafe');
+      sourcePath = directoryHandle.anchor;
+    } catch (error) {
+      if (['ELOOP', 'ENOTDIR'].includes(error?.code)) fail('Archive contains a link or special file; archive destination is unsafe');
+      throw error;
+    }
+    const mode = info.mode & 0o777;
+    const existing = await lstat(destination).catch(() => null);
+    if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) fail('Archive contains a link or special file; archive destination is unsafe');
+    try { await ensureDirectoryPath(destination, { allowOutside:true }); }
+    catch (error) { if (error?.code !== 'EEXIST') throw error; }
+    const destinationInfo = await lstat(destination);
+    if (!destinationInfo.isDirectory() || destinationInfo.isSymbolicLink()) fail('Archive contains a link or special file; archive destination is unsafe');
+    let destinationHandle;
+    try {
+      destinationHandle = await openDirectoryPath(destination, { allowOutside:true });
+      const openedDestination = await destinationHandle.handle.stat();
+      if (!openedDestination.isDirectory()) fail('Archive contains a link or special file; archive destination is unsafe');
+      await destinationHandle.handle.chmod(mode | 0o700);
+      const destinationAnchor = destinationHandle.anchor;
+      for (const name of await readdir(sourcePath)) {
+        await copyTreeContents(path.join(sourcePath, name), path.join(destinationAnchor, name), state);
+      }
+      await destinationHandle.handle.chmod(mode);
+    } finally {
+      if (destinationHandle) await destinationHandle.close().catch(() => {});
+    }
+  } finally {
+    if (directoryHandle) await directoryHandle.close().catch(() => {});
+  }
+}
+
+export async function removeExtractionArtifact(target) {
+  const info = await lstat(target).catch(() => null);
+  if (!info) return;
+  if (info.isDirectory() && !info.isSymbolicLink()) await rm(target, { recursive: true, force: true });
+  else await unlink(target).catch(error => { if (error?.code !== 'ENOENT') throw error; });
+}
+
+export async function recoverExtractionArtifacts(parent, destination, prefix) {
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const anchor = parentDirectory.anchor;
+  const destinationPath = path.join(anchor, path.basename(destination));
+  try {
+    const entries = await readdir(anchor, { withFileTypes: true });
+    const staleBefore = Date.now() - 60 * 60 * 1000;
+    for (const entry of entries) {
+      if (!entry.name.startsWith('.remcp-extract-txn-')) continue;
+      const candidate = path.join(anchor, entry.name);
+      const info = await lstat(candidate).catch(() => null);
+      if (info && info.mtimeMs < staleBefore) await removeExtractionArtifact(candidate);
+    }
+    const backups = entries.filter(entry => entry.name.startsWith(prefix)).map(entry => path.join(anchor, entry.name));
+    for (const backup of backups) {
+      const destinationInfo = await lstat(destinationPath).catch(() => null);
+      if (destinationInfo) {
+        await removeExtractionArtifact(backup);
+        continue;
+      }
+      const backupInfo = await lstat(backup).catch(() => null);
+      if (!backupInfo) continue;
+      if (backupInfo.isSymbolicLink() || !backupInfo.isDirectory()) {
+        await removeExtractionArtifact(backup);
+        continue;
+      }
+      try {
+        await rename(backup, destinationPath);
+      } catch {
+        continue;
+      }
+    }
+  } finally {
+    await parentDirectory.close().catch(() => {});
+  }
+}
+
+export async function restoreExtractionBackup(backup, destination) {
+  if (await lstat(destination).catch(() => null)) return false;
+  const info = await lstat(backup).catch(() => null);
+  if (!info) return false;
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    await removeExtractionArtifact(backup);
+    return false;
+  }
+  try {
+    await rename(backup, destination);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function installExtractedTree(source, destination) {
+  const parent = path.dirname(destination);
+  if (destination === path.parse(destination).root) fail('Archive destination cannot be a filesystem root');
+  const backupPrefix = `.remcp-extract-backup-${createHash('sha256').update(destination).digest('hex').slice(0, 16)}-`;
+  await recoverExtractionArtifacts(parent, destination, backupPrefix);
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const parentAnchor = parentDirectory.anchor;
+  const destinationPath = path.join(parentAnchor, path.basename(destination));
+  const existing = await lstat(destinationPath).catch(() => null);
+  const destinationMode = existing?.isDirectory() ? existing.mode & 0o777 : 0o700;
+  let transaction = '';
+  let backup = '';
+  let backupOwned = false;
+  let preserveBackup = false;
+  try {
+    transaction = await mkdtemp(path.join(parentAnchor, '.remcp-extract-txn-'));
+    if (existing) {
+      backup = path.join(parentAnchor, `${backupPrefix}${randomUUID()}`);
+      try {
+        await rename(destinationPath, backup);
+        backupOwned = true;
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        backup = '';
+      }
+    }
+    if (backupOwned) {
+      const backupInfo = await lstat(backup);
+      if (backupInfo.isSymbolicLink() || !backupInfo.isDirectory()) fail('Archive destination is not a safe directory');
+      await copyTreeContents(backup, transaction, { entries:0, bytes:0, maxBytes:MAX_ARCHIVE_EXPANDED_BYTES, allowOutsideSource:true });
+    }
+    await copyTreeContents(source, transaction, { entries:0, bytes:0, maxBytes:MAX_ARCHIVE_EXPANDED_BYTES, allowOutsideSource:true });
+    await chmod(transaction, destinationMode);
+    await rename(transaction, destinationPath);
+    if (backupOwned) {
+      await removeExtractionArtifact(backup);
+      backupOwned = false;
+    }
+  } catch (error) {
+    if (backupOwned) {
+      try {
+        await restoreExtractionBackup(backup, destinationPath);
+        if (!await lstat(backup).catch(() => null)) backupOwned = false;
+        else preserveBackup = true;
+      } catch (restoreError) {
+        preserveBackup = true;
+        throw new AggregateError([error, restoreError], 'Could not restore archive destination after extraction failure');
+      }
+    }
+    throw error;
+  } finally {
+    if (transaction) await rm(transaction, { recursive: true, force: true });
+    if (backupOwned && !preserveBackup) await removeExtractionArtifact(backup);
+    await parentDirectory.close().catch(() => {});
+  }
+}
+
+export async function moveArchiveFile(source, destination) {
+  const parent = path.dirname(destination);
+  const parentDirectory = await openDirectoryPath(parent, { create:true });
+  const destinationPath = path.join(parentDirectory.anchor, path.basename(destination));
+  try {
+    try {
+      await rename(source, destinationPath);
+    } catch (error) {
+      if (!['EXDEV', 'EPERM'].includes(error?.code)) throw error;
+      const temporary = path.join(parentDirectory.anchor, `.${path.basename(destination)}.remcp-${randomUUID()}.tmp`);
+      try {
+        await copyFile(source, temporary, constants.COPYFILE_EXCL);
+        await rename(temporary, destinationPath);
+      } finally {
+        await unlink(temporary).catch(() => {});
+      }
+      await unlink(source);
+    }
+  } finally {
+    await parentDirectory.close().catch(() => {});
+  }
+}
+
+export function archiveCommandProbe(name, versionArgs = ['--version']) {
+  const result = spawnSync(name, versionArgs, { encoding: 'utf8' });
+  return !result.error && result.status === 0 ? name : null;
+}
+
+export function archiveTool({ platform = process.platform, probe = archiveCommandProbe } = {}) {
+  const tarName = platform === 'win32' ? 'tar.exe' : 'tar';
+  // Windows ships libarchive/bsdtar as tar.exe. It can create/read ZIP as well as tar-family
+  // archives, so keeping one backend avoids introducing a second extraction/safety path.
+  if (platform === 'win32') return { tar: probe(tarName), zip:null, unzip:null };
+  // Info-ZIP unzip (the default on Debian/Ubuntu) treats --version as an invalid combination and
+  // exits 10 even though the binary is healthy. Its portable version probe is -v.
+  return { tar: probe(tarName), zip: probe('zip'), unzip: probe('unzip', ['-v']) };
+}
+
+export function archiveBackendAvailable({ platform = process.platform, probe = archiveCommandProbe } = {}) {
+  if (platform === 'win32') return Boolean(archiveTool({ platform, probe }).tar);
+  return platform === 'linux' || platform === 'darwin';
+}
+
+export function zipArchiveBackendAvailable({ platform = process.platform, probe = archiveCommandProbe } = {}) {
+  const tools = archiveTool({ platform, probe });
+  if (platform === 'win32') return Boolean(tools.tar);
+  if (platform === 'linux' || platform === 'darwin') return Boolean(tools.zip && tools.unzip);
+  return false;
+}