@n0zer0d4y/vulcan-file-ops 1.2.13 → 1.3.0

package/dist/server/index.js

@@ -16,7 +16,7 @@ if (_isMCP) {
 }
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, PingRequestSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, PingRequestSchema, RootsListChangedNotificationSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs/promises";
 import { readFileSync } from "fs";
 import path from "path";
@@ -34,16 +34,19 @@ const VERSION = packageJson.version;
 // Import tool handlers
 import { getReadTools } from "../tools/read-tools.js";
 import { getWriteTools } from "../tools/write-tools.js";
-import { getFileSystemTools } from "../tools/filesystem-tools.js";
+import { getFileSystemTools, isRuntimeRegistrationPolicy, setRuntimeRegistrationPolicy, setDirectoryRegistrationConsentHandler, RUNTIME_REGISTRATION_POLICIES, } from "../tools/filesystem-tools.js";
 import { getSearchTools } from "../tools/search-tools.js";
 import { initializeShellTool, getShellTools } from "../tools/shell-tool.js";
 // Configuration storage
 let allowedDirectories = [];
 let approvedFoldersFromArgs = [];
 let approvedCommandsFromArgs = [];
+let dangerousCommandsFromArgs = [];
 let ignoredFolders = [];
 let enabledToolCategories = [];
 let enabledTools = [];
+let runtimeRegistrationPolicy = "confirm";
+let envFileFromArgs = null;
 // Command line argument parsing
 function parseArguments() {
     const args = process.argv.slice(2);
@@ -65,6 +68,12 @@ function parseArguments() {
         console.error("  --enabled-tool-categories <cats...>  Enable specific tool categories (comma-separated)");
         console.error("  --enabled-tools <tools...>      Enable specific tools (comma-separated)");
         console.error("  --approved-commands <cmds...>   Allow specific shell commands (comma-separated)");
+        console.error("  --allow-dangerous-commands <cmds...>  Approved commands that may run even when they match");
+        console.error("                                  a dangerous pattern (e.g. rm -rf); comma-separated");
+        console.error("  --commands-env-file <path>      Read APPROVED_COMMANDS from this .env-format file (only");
+        console.error("                                  that key is used; nothing is added to the environment)");
+        console.error("  --runtime-registration <mode>   register_directory policy: confirm (default; user must");
+        console.error("                                  approve via the MCP client), allow (no prompt), deny");
         console.error("  --help, -h                     Show this help message");
         console.error("  --version, -v                  Show version information");
         console.error("");
@@ -157,6 +166,59 @@ function parseArguments() {
                 .filter((tool) => tool.length > 0));
             continue;
         }
+        if (arg === "--runtime-registration" ||
+            arg.startsWith("--runtime-registration=")) {
+            let value;
+            if (arg.includes("=")) {
+                value = arg.slice(arg.indexOf("=") + 1);
+            }
+            else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+                value = args[++i];
+            }
+            if (!value || !isRuntimeRegistrationPolicy(value.trim())) {
+                console.error(`Error: Invalid value for --runtime-registration: '${value ?? ""}'. ` +
+                    `Expected one of: ${RUNTIME_REGISTRATION_POLICIES.join(", ")}`);
+                console.error("Run with --help for usage information.");
+                process.exit(1);
+            }
+            runtimeRegistrationPolicy = value.trim();
+            parsingIgnoredFolders = false;
+            parsingApprovedFolders = false;
+            parsingEnabledToolCategories = false;
+            parsingEnabledTools = false;
+            parsingApprovedCommands = false;
+            continue;
+        }
+        // Node.js itself scans ALL argv entries (even after the script) for
+        // --env-file and applies NODE_OPTIONS from that file to this process,
+        // so the server must not use that name.
+        if (arg === "--env-file" || arg.startsWith("--env-file=")) {
+            console.error("Error: --env-file is reserved by Node.js. Use --commands-env-file <path> instead.");
+            console.error("Run with --help for usage information.");
+            process.exit(1);
+        }
+        if (arg === "--commands-env-file" ||
+            arg.startsWith("--commands-env-file=")) {
+            let value;
+            if (arg.includes("=")) {
+                value = arg.slice(arg.indexOf("=") + 1);
+            }
+            else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+                value = args[++i];
+            }
+            if (!value || value.trim().length === 0) {
+                console.error("Error: --commands-env-file requires a file path");
+                console.error("Run with --help for usage information.");
+                process.exit(1);
+            }
+            envFileFromArgs = value.trim();
+            parsingIgnoredFolders = false;
+            parsingApprovedFolders = false;
+            parsingEnabledToolCategories = false;
+            parsingEnabledTools = false;
+            parsingApprovedCommands = false;
+            continue;
+        }
         if (arg === "--approved-commands") {
             parsingApprovedCommands = true;
             parsingIgnoredFolders = false;
@@ -176,6 +238,23 @@ function parseArguments() {
                 .filter((cmd) => cmd.length > 0));
             continue;
         }
+        if (arg === "--allow-dangerous-commands") {
+            parsingApprovedCommands = false;
+            parsingIgnoredFolders = false;
+            parsingApprovedFolders = false;
+            parsingEnabledToolCategories = false;
+            parsingEnabledTools = false;
+            const commands = [];
+            while (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+                commands.push(args[i + 1]);
+                i++;
+            }
+            dangerousCommandsFromArgs = commands.flatMap((c) => c
+                .split(",")
+                .map((cmd) => cmd.trim())
+                .filter((cmd) => cmd.length > 0));
+            continue;
+        }
         // If we're not parsing a flag value, this might be an unrecognized argument
         if (!parsingIgnoredFolders &&
             !parsingApprovedFolders &&
@@ -328,6 +407,7 @@ async function initializeDirectories() {
     setIgnoredFolders(ignoredFolders);
     // Set individual enabled tools (categories are combined dynamically in tool handlers)
     setEnabledTools(enabledTools);
+    setRuntimeRegistrationPolicy(runtimeRegistrationPolicy);
     // Load shell command configuration
     let finalApprovedCommands = [];
     // Priority 1: --approved-commands from CLI (supersedes .env)
@@ -337,29 +417,34 @@ async function initializeDirectories() {
             console.error(`  Approved commands (from CLI): ${finalApprovedCommands.join(", ")}`);
         }
     }
-    else {
-        // Priority 2: Load from .env file
+    else if (envFileFromArgs) {
+        // Priority 2: explicit --commands-env-file. Security (VFO-08): never load a .env
+        // implicitly from the working directory, and never inject its variables
+        // into process.env (shell commands inherit it). Only APPROVED_COMMANDS
+        // is read.
+        const envPath = path.resolve(process.cwd(), expandHome(envFileFromArgs));
         try {
-            const envPath = path.join(process.cwd(), ".env");
-            dotenv.config({ path: envPath, quiet: true });
-            if (process.env.APPROVED_COMMANDS) {
-                finalApprovedCommands = process.env.APPROVED_COMMANDS.split(",")
-                    .map((c) => c.trim())
-                    .filter((c) => c.length > 0);
-                if (!isMCP) {
-                    console.error(`  Approved commands (from .env): ${finalApprovedCommands.join(", ")}`);
-                }
+            const parsedEnv = dotenv.parse(readFileSync(envPath));
+            finalApprovedCommands = (parsedEnv.APPROVED_COMMANDS ?? "")
+                .split(",")
+                .map((c) => c.trim())
+                .filter((c) => c.length > 0);
+            if (!isMCP) {
+                console.error(`  Approved commands (from ${envPath}): ${finalApprovedCommands.join(", ")}`);
             }
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Error: Could not read --commands-env-file ${envPath}: ${message}`);
+            // In MCP mode, don't exit - continue with no approved commands
             if (!isMCP) {
-                console.error("  Note: Could not load .env file (this is okay if using CLI args)");
+                process.exit(1);
             }
         }
     }
     // Initialize shell tool with approved commands
     if (finalApprovedCommands.length > 0) {
-        initializeShellTool(finalApprovedCommands);
+        initializeShellTool(finalApprovedCommands, dangerousCommandsFromArgs);
         if (!isMCP) {
             console.error(`Initialized shell tool with ${finalApprovedCommands.length} approved command(s)`);
         }
@@ -399,25 +484,46 @@ const server = new Server({
         // receive "Method not found" errors, and fail to enable the toggle
     },
 });
-// Initialize handler - required for MCP protocol
-server.setRequestHandler(InitializeRequestSchema, async (request) => {
-    const clientCapabilities = request.params.capabilities;
-    return {
-        // CRITICAL: Return the protocol version the CLIENT requested, not LATEST
-        // Claude Desktop only supports 2025-06-18 and will disconnect if we return 2025-11-25
-        protocolVersion: request.params.protocolVersion,
-        capabilities: {
-            tools: {
-                listChanged: true,
+// The SDK's built-in initialize handler (_oninitialize) is left in place.
+// Overriding it via setRequestHandler breaks the SDK's internal state machine:
+// _clientCapabilities and _clientVersion never get set, and protocol version
+// negotiation is bypassed (should respond with max supported ≤ client's requested).
+// Instructions are injected at runtime in runServer() after directories initialize.
+// Security (VFO-07): under the default "confirm" policy, register_directory
+// asks the human through MCP elicitation before widening the sandbox.
+// Clients without elicitation support get "unsupported" (registration refused).
+const REGISTRATION_CONSENT_TIMEOUT_MS = 5 * 60 * 1000;
+setDirectoryRegistrationConsentHandler(async (realPath) => {
+    if (!server.getClientCapabilities()?.elicitation) {
+        return "unsupported";
+    }
+    try {
+        const result = await server.elicitInput({
+            message: `Allow the AI assistant to read and modify files in:\n${realPath}\n\n` +
+                "Only approve directories you trust it to change.",
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    allow: {
+                        type: "boolean",
+                        title: "Allow access",
+                        description: "Grant read/write access to this directory for this session",
+                    },
+                },
+                required: ["allow"],
             },
-            // CRITICAL: Do NOT declare resources or prompts - we don't implement them
-        },
-        serverInfo: {
-            name: "vulcan-file-ops",
-            version: VERSION,
-        },
-        instructions: generateServerDescription(),
-    };
+        }, { timeout: REGISTRATION_CONSENT_TIMEOUT_MS });
+        return result.action === "accept" && result.content?.allow === true
+            ? "accepted"
+            : "declined";
+    }
+    catch (error) {
+        if (error instanceof McpError && error.code === ErrorCode.MethodNotFound) {
+            return "unsupported";
+        }
+        // Timeouts, invalid responses, transport errors: fail closed
+        return "declined";
+    }
 });
 // Ping handler - for health checks
 server.setRequestHandler(PingRequestSchema, async () => {
@@ -623,18 +729,19 @@ server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
     }
 });
 // Handles post-initialization setup, specifically checking for and fetching MCP roots.
-server.oninitialized = async () => {
+// listRoots() is fired detached (no await) so it doesn't block the initialize handshake.
+// Blocking here deadlocks: the client won't respond to roots/list until after initialize
+// completes, but initialize won't complete until this callback returns.
+server.oninitialized = () => {
     const clientCapabilities = server.getClientCapabilities();
     if (clientCapabilities?.roots) {
-        try {
-            const response = await server.listRoots();
+        server.listRoots().then(async (response) => {
             if (response && "roots" in response) {
                 await updateAllowedDirectoriesFromRoots(response.roots);
             }
-        }
-        catch (error) {
+        }).catch(() => {
             // Silently handle errors - dynamic access will work via register_directory tool
-        }
+        });
     }
 };
 // Start server
@@ -658,6 +765,10 @@ export async function runServer() {
         }
         // In MCP mode, silently continue - server can work without approved folders
     }
+    // Inject instructions now that directories are known. The SDK's built-in
+    // _oninitialize reads this._instructions when building the initialize response.
+    server._instructions =
+        generateServerDescription();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Minimal logging to avoid issues with MCP clients

package/dist/tools/filesystem-tools.js

@@ -1,14 +1,67 @@
 import fs from "fs/promises";
+import os from "os";
 import path from "path";
 import { minimatch } from "minimatch";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { expandHome, normalizePath } from "../utils/path-utils.js";
-import { isPathWithinAllowedDirectories } from "../utils/path-validation.js";
 import { MakeDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, GetFileInfoArgsSchema, RegisterDirectoryArgsSchema, FileOperationsArgsSchema, DeleteFilesArgsSchema, } from "../types/index.js";
-import { validatePath, getFileStats, formatSize, getAllowedDirectories, setAllowedDirectories, shouldIgnoreFolder, } from "../utils/lib.js";
+import { validatePath, getFileStats, formatSize, getAllowedDirectories, setAllowedDirectories, shouldIgnoreFolder, isPathCanonicallyAllowed, ensureDirectoryWithinAllowed, } from "../utils/lib.js";
 import { createEmptyObjectSchema, createPathArraySchema, sanitizeToolInputSchema, } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
+// ============================================================================
+// RUNTIME DIRECTORY REGISTRATION POLICY (register_directory)
+// ============================================================================
+//
+// Security (VFO-07): register_directory widens the sandbox, so by default it
+// requires a human to confirm each registration through the MCP client
+// (elicitation). The server entry point installs the consent handler; when
+// none is installed (or the client cannot prompt), registration is refused.
+export const RUNTIME_REGISTRATION_POLICIES = [
+    "confirm",
+    "allow",
+    "deny",
+];
+let runtimeRegistrationPolicy = "confirm";
+let directoryRegistrationConsentHandler = null;
+export function isRuntimeRegistrationPolicy(value) {
+    return RUNTIME_REGISTRATION_POLICIES.includes(value);
+}
+export function setRuntimeRegistrationPolicy(policy) {
+    if (!isRuntimeRegistrationPolicy(policy)) {
+        throw new Error(`Invalid runtime registration policy: ${policy}. Expected one of: ${RUNTIME_REGISTRATION_POLICIES.join(", ")}`);
+    }
+    runtimeRegistrationPolicy = policy;
+}
+export function getRuntimeRegistrationPolicy() {
+    return runtimeRegistrationPolicy;
+}
+export function setDirectoryRegistrationConsentHandler(handler) {
+    directoryRegistrationConsentHandler = handler;
+}
+function samePath(a, b) {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    return process.platform === "win32"
+        ? left.toLowerCase() === right.toLowerCase()
+        : left === right;
+}
+async function describeSensitiveDirectory(realPath) {
+    if (path.parse(realPath).root === realPath) {
+        return "a filesystem root";
+    }
+    let home = os.homedir();
+    try {
+        home = await fs.realpath(home);
+    }
+    catch {
+        // Fall back to the lexical home directory
+    }
+    if (home && samePath(realPath, home)) {
+        return "the user's home directory";
+    }
+    return null;
+}
 export function getFileSystemTools() {
     // Get current allowed directories for dynamic descriptions
     const currentAllowedDirs = getAllowedDirectories();
@@ -65,7 +118,10 @@ export function getFileSystemTools() {
             name: "register_directory",
             description: "Register a directory for access. This allows the AI to dynamically gain access " +
                 "to directories specified by the human user during conversation. The directory " +
-                "and all its subdirectories will become accessible for all filesystem operations." +
+                "and all its subdirectories will become accessible for all filesystem operations. " +
+                "By default the user must confirm each registration in their MCP client " +
+                "(registration is refused if the client cannot show a confirmation prompt); " +
+                "filesystem roots and the home directory cannot be registered at runtime." +
                 generateApprovedDirsText(),
             inputSchema: sanitizeToolInputSchema(zodToJsonSchema(RegisterDirectoryArgsSchema)),
         },
@@ -456,25 +512,26 @@ export async function handleFileSystemTool(name, args) {
             const pathsToCreate = Array.isArray(pathsInput)
                 ? pathsInput
                 : [pathsInput];
-            // Validate all paths first (atomic - fail before any creation)
-            const allowedDirs = getAllowedDirectories();
-            const validatedPaths = pathsToCreate.map((dirPath) => {
+            // Validate all paths first (atomic - fail before any creation).
+            // Security: the check is canonical (lexical + realpath + physical), so a
+            // symlink or junction inside an allowed directory that points outside it
+            // is rejected here instead of being followed by mkdir (VFO-05).
+            const validatedPaths = [];
+            for (const dirPath of pathsToCreate) {
                 const expandedPath = expandHome(dirPath);
-                // Resolve to absolute path - required by isPathWithinAllowedDirectories
                 const absolutePath = path.isAbsolute(expandedPath)
                     ? path.resolve(expandedPath)
                     : path.resolve(process.cwd(), expandedPath);
-                const normalized = normalizePath(absolutePath);
-                // Use secure path validation function to prevent prefix collision attacks
-                // (CVE-2025-54794 pattern: ensures path separator is required, not just prefix match)
-                if (!isPathWithinAllowedDirectories(normalized, allowedDirs)) {
+                if (!(await isPathCanonicallyAllowed(absolutePath, process.cwd()))) {
                     throw new Error(`Access denied: Path ${dirPath} is not within allowed directories`);
                 }
-                return { original: dirPath, normalized };
-            });
-            // All validated - now create them concurrently
-            const results = await Promise.all(validatedPaths.map(async ({ original, normalized }) => {
-                await fs.mkdir(normalized, { recursive: true });
+                validatedPaths.push({ original: dirPath, absolutePath });
+            }
+            // All validated - now create them. ensureDirectoryWithinAllowed creates
+            // missing segments one at a time and re-checks the realpath of each, so
+            // a link swapped in after validation cannot redirect creation.
+            const results = await Promise.all(validatedPaths.map(async ({ original, absolutePath }) => {
+                await ensureDirectoryWithinAllowed(absolutePath);
                 return original;
             }));
             // Format response based on single vs batch
@@ -506,6 +563,35 @@ export async function handleFileSystemTool(name, args) {
             }
             const validSourcePath = await validatePath(parsed.data.source);
             const validDestPath = await validatePath(parsed.data.destination);
+            // fs.rename silently replaces an existing destination; move_file is
+            // documented to never overwrite.
+            try {
+                const destStats = await fs.lstat(validDestPath, { bigint: true });
+                const sourceStats = await fs.lstat(validSourcePath, { bigint: true });
+                const sameFile = destStats.ino === sourceStats.ino && destStats.dev === sourceStats.dev;
+                // A case-only rename on a case-insensitive file system "finds" the
+                // source itself at the destination; that is not an overwrite.
+                // validatePath returns the existing (old-case) real path, so rename to
+                // the requested name inside the same, already-validated directory.
+                if (sameFile) {
+                    await fs.rename(validSourcePath, path.join(path.dirname(validDestPath), path.basename(parsed.data.destination)));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Successfully moved ${parsed.data.source} to ${parsed.data.destination}`,
+                            },
+                        ],
+                    };
+                }
+                throw new Error(`Destination already exists: ${parsed.data.destination}. ` +
+                    `move_file never overwrites; use file_operations with onConflict: "overwrite" to replace it.`);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
             await fs.rename(validSourcePath, validDestPath);
             return {
                 content: [
@@ -541,43 +627,82 @@ export async function handleFileSystemTool(name, args) {
             }
             const expandedPath = expandHome(parsed.data.path);
             const absolutePath = path.resolve(expandedPath);
-            const normalizedPath = normalizePath(absolutePath);
-            // Validate that the path exists and is a directory
+            // Resolve links so the directory that is shown to the user and stored
+            // in the allowed list is the one that will actually be accessed.
+            let realPath;
             try {
-                const stats = await fs.stat(absolutePath);
+                realPath = await fs.realpath(absolutePath);
+                const stats = await fs.stat(realPath);
                 if (!stats.isDirectory()) {
                     throw new Error(`Path ${absolutePath} is not a directory`);
                 }
             }
             catch (error) {
-                if (error.code === "ENOENT") {
+                const code = error.code;
+                if (code === "ENOENT" || code === "ENOTDIR") {
                     throw new Error(`Directory ${absolutePath} does not exist`);
                 }
                 throw error;
             }
-            // Add to allowed directories
-            const currentDirs = getAllowedDirectories();
-            if (!currentDirs.includes(normalizedPath)) {
-                setAllowedDirectories([...currentDirs, normalizedPath]);
+            const normalizedPath = normalizePath(realPath) || realPath;
+            // Already accessible: nothing to widen, so no prompt is needed
+            if (getAllowedDirectories().includes(normalizedPath)) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Successfully registered directory: ${parsed.data.path} (${normalizedPath})`,
+                            text: `Directory already registered: ${parsed.data.path} (${normalizedPath})`,
                         },
                     ],
                 };
             }
-            else {
+            if (await isPathCanonicallyAllowed(realPath, process.cwd())) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `Directory already registered: ${parsed.data.path} (${normalizedPath})`,
+                            text: `Directory already accessible: ${parsed.data.path} (${normalizedPath}) is inside an allowed directory`,
                         },
                     ],
                 };
             }
+            const policy = getRuntimeRegistrationPolicy();
+            if (policy === "deny") {
+                throw new Error(`Runtime directory registration is disabled on this server (--runtime-registration deny). ` +
+                    `To grant access to ${normalizedPath}, add it to --approved-folders in the MCP server configuration.`);
+            }
+            if (policy !== "allow") {
+                const sensitive = await describeSensitiveDirectory(realPath);
+                if (sensitive) {
+                    throw new Error(`Refusing to register ${normalizedPath}: it is ${sensitive}. ` +
+                        `Register a more specific folder, add it to --approved-folders, ` +
+                        `or start the server with --runtime-registration allow.`);
+                }
+                const consent = directoryRegistrationConsentHandler
+                    ? await directoryRegistrationConsentHandler(normalizedPath)
+                    : "unsupported";
+                if (consent === "unsupported") {
+                    throw new Error(`Cannot register ${normalizedPath}: registering directories at runtime requires user confirmation, ` +
+                        `but this MCP client does not support confirmation prompts (MCP elicitation). ` +
+                        `Add the folder via --approved-folders, or start the server with --runtime-registration allow.`);
+                }
+                if (consent !== "accepted") {
+                    throw new Error(`User declined access to ${normalizedPath}`);
+                }
+            }
+            // Re-read: the list may have changed while waiting for the user
+            const currentDirs = getAllowedDirectories();
+            if (!currentDirs.includes(normalizedPath)) {
+                setAllowedDirectories([...currentDirs, normalizedPath]);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Successfully registered directory: ${parsed.data.path} (${normalizedPath})`,
+                    },
+                ],
+            };
         }
         case "list_allowed_directories": {
             return {
@@ -666,6 +791,11 @@ export async function handleFileSystemTool(name, args) {
                             await fs.rename(file.validSource, file.validDest);
                             break;
                         case "copy":
+                            // validSource is the realpath returned by validatePath, so a
+                            // top-level source that is itself a symlink/junction has already
+                            // been resolved and its real target checked against the allowed
+                            // directories. Links *inside* a copied directory are refused by
+                            // copyDirectoryRecursive.
                             const stats = await fs.stat(file.validSource);
                             if (stats.isDirectory()) {
                                 await copyDirectoryRecursive(file.validSource, file.validDest);
@@ -903,22 +1033,75 @@ export async function handleFileSystemTool(name, args) {
             throw new Error(`Unknown filesystem tool: ${name}`);
     }
 }
-// Helper function for recursive directory copying
-async function copyDirectoryRecursive(source, destination) {
-    // Create destination directory
-    await fs.mkdir(destination, { recursive: true });
-    // Read source directory
-    const entries = await fs.readdir(source, { withFileTypes: true });
-    // Copy all entries
+function symlinkCopyError(entryPath) {
+    return new Error(`Refusing to copy symbolic link inside directory: ${entryPath} ` +
+        `(symbolic links are not copied for security reasons)`);
+}
+async function collectDirectoryCopyPlan(root, relativeDir = "", plan = []) {
+    const entries = await fs.readdir(path.join(root, relativeDir), {
+        withFileTypes: true,
+    });
     for (const entry of entries) {
-        const sourcePath = path.join(source, entry.name);
-        const destPath = path.join(destination, entry.name);
-        if (entry.isDirectory()) {
-            await copyDirectoryRecursive(sourcePath, destPath);
+        const relativePath = path.join(relativeDir, entry.name);
+        const entryPath = path.join(root, relativePath);
+        // lstat never follows links; Node reports junctions as symbolic links too
+        const stats = await fs.lstat(entryPath);
+        if (entry.isSymbolicLink() || stats.isSymbolicLink()) {
+            throw symlinkCopyError(entryPath);
+        }
+        if (stats.isDirectory()) {
+            plan.push({ relativePath, type: "directory" });
+            await collectDirectoryCopyPlan(root, relativePath, plan);
+        }
+        else if (stats.isFile()) {
+            plan.push({ relativePath, type: "file" });
         }
         else {
-            await fs.copyFile(sourcePath, destPath);
+            throw new Error(`Refusing to copy special file inside directory: ${entryPath} ` +
+                `(only regular files and directories are copied)`);
+        }
+    }
+    return plan;
+}
+async function copyDirectoryRecursive(source, destination) {
+    const relativeDest = path.relative(source, destination);
+    if (relativeDest === "" ||
+        (!relativeDest.startsWith("..") && !path.isAbsolute(relativeDest))) {
+        throw new Error(`Cannot copy a directory into itself: ${source} to ${destination}`);
+    }
+    // Validate the entire source tree before creating or copying anything
+    const plan = await collectDirectoryCopyPlan(source);
+    // Destination directories are created segment by segment with their
+    // realpath re-checked, so an existing link at the destination cannot
+    // redirect the copy outside the allowed directories.
+    await ensureDirectoryWithinAllowed(destination);
+    for (const entry of plan) {
+        const sourcePath = path.join(source, entry.relativePath);
+        const destPath = path.join(destination, entry.relativePath);
+        if (entry.type === "directory") {
+            await ensureDirectoryWithinAllowed(destPath);
+            continue;
+        }
+        // Re-check the source right before copying in case it was swapped for a
+        // link after the tree was validated.
+        const sourceStats = await fs.lstat(sourcePath);
+        if (sourceStats.isSymbolicLink() || !sourceStats.isFile()) {
+            throw symlinkCopyError(sourcePath);
+        }
+        // Never write through an existing link at the destination
+        let destIsLink = false;
+        try {
+            destIsLink = (await fs.lstat(destPath)).isSymbolicLink();
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        if (destIsLink) {
+            throw new Error(`Refusing to overwrite symbolic link at destination: ${destPath}`);
         }
+        await fs.copyFile(sourcePath, destPath);
     }
 }
 //# sourceMappingURL=filesystem-tools.js.map