@n0zer0d4y/vulcan-file-ops 1.2.14 → 1.3.0

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

package/dist/tools/read-tools.js

@@ -1,29 +1,72 @@
-import { createReadStream } from "fs";
+import { createReadStream, promises as fs } from "fs";
 import path from "path";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { ReadFileArgsSchema, AttachImageArgsSchema, ReadMultipleFilesArgsSchema, } from "../types/index.js";
-import { validatePath, readFileContent, tailFile, headFile, rangeFile, } from "../utils/lib.js";
+import { validatePath, tailFile, headFile, rangeFile, } from "../utils/lib.js";
 import { isDocumentFile, parseDocument } from "../utils/document-parser.js";
+import { MAX_IMAGE_ATTACH_BYTES, MAX_IMAGE_ATTACH_TOTAL_BYTES, MAX_TEXT_READ_BYTES, } from "../utils/limits.js";
 import { createPathArraySchema, sanitizeToolInputSchema, } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
+const formatMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 // Reads a file as a stream of buffers, concatenates them, and then encodes
-// the result to a Base64 string. This is a memory-efficient way to handle
-// binary data from a stream before the final encoding.
-async function readFileAsBase64Stream(filePath) {
+// the result to a Base64 string. At most `maxBytes` are read: a file that
+// grew past the limit after it was checked is rejected rather than read.
+async function readFileAsBase64Stream(filePath, maxBytes) {
     return new Promise((resolve, reject) => {
-        const stream = createReadStream(filePath);
+        const stream = createReadStream(filePath, { start: 0, end: maxBytes });
         const chunks = [];
+        let total = 0;
         stream.on("data", (chunk) => {
+            total += chunk.length;
             chunks.push(chunk);
         });
         stream.on("end", () => {
+            if (total > maxBytes) {
+                reject(new Error(`Image ${path.basename(filePath)} exceeds the ${formatMB(maxBytes)} limit`));
+                return;
+            }
             const finalBuffer = Buffer.concat(chunks);
             resolve(finalBuffer.toString("base64"));
         });
         stream.on("error", (err) => reject(err));
     });
 }
+/**
+ * Read a whole text file ("full" mode), refusing files larger than
+ * MAX_TEXT_READ_BYTES (VFO-15). The read itself is bounded too, so a file
+ * that grows after the size check (or a device/FIFO that reports size 0)
+ * cannot exhaust memory.
+ */
+async function readFullTextFile(filePath) {
+    const tooLarge = (size) => new Error(`File is too large to read in full mode (${size}; limit ` +
+        `${formatMB(MAX_TEXT_READ_BYTES)}). Use mode "head", "tail" or "range" ` +
+        `to read part of it.`);
+    const handle = await fs.open(filePath, "r");
+    try {
+        const { size } = await handle.stat();
+        if (size > MAX_TEXT_READ_BYTES) {
+            throw tooLarge(formatMB(size));
+        }
+        const buffer = Buffer.alloc(64 * 1024);
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > MAX_TEXT_READ_BYTES) {
+                throw tooLarge(`more than ${formatMB(MAX_TEXT_READ_BYTES)}`);
+            }
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+        return Buffer.concat(chunks).toString("utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
 export function getReadTools() {
     return [
         {
@@ -43,7 +86,8 @@ export function getReadTools() {
                 "to the AI model as if uploaded directly by the user, enabling the AI to see " +
                 "and describe visual content, read text in images, analyze diagrams, etc. " +
                 "Supports attaching a single image or multiple images at once. " +
-                "Supports PNG, JPEG, GIF, WebP, BMP, and SVG formats. " +
+                "Supports PNG, JPEG, GIF and WebP (the formats vision models accept). " +
+                "SVG files are returned as their XML markup text; BMP is not supported (convert to PNG). " +
                 "Note: This requires the MCP client to support vision capabilities. " +
                 "Only works within allowed directories.",
             inputSchema: {
@@ -122,7 +166,7 @@ export async function handleReadTool(name, args) {
                 }
                 case "full":
                 default: {
-                    const content = await readFileContent(validPath);
+                    const content = await readFullTextFile(validPath);
                     return {
                         content: [{ type: "text", text: content }],
                     };
@@ -138,29 +182,58 @@ export async function handleReadTool(name, args) {
             const paths = Array.isArray(parsed.data.path)
                 ? parsed.data.path
                 : [parsed.data.path];
-            // Supported image formats only (no audio)
+            // Raster formats accepted by vision models. SVG is vector markup (XML),
+            // which vision APIs reject as an image, so it is returned as text.
             const mimeTypes = {
                 ".png": "image/png",
                 ".jpg": "image/jpeg",
                 ".jpeg": "image/jpeg",
                 ".gif": "image/gif",
                 ".webp": "image/webp",
-                ".bmp": "image/bmp",
                 ".svg": "image/svg+xml",
             };
-            // Process all images
-            const imageContents = await Promise.all(paths.map(async (imagePath) => {
+            // Validate all images and check sizes before reading any of them
+            const images = await Promise.all(paths.map(async (imagePath) => {
                 const validPath = await validatePath(imagePath);
                 const extension = path.extname(validPath).toLowerCase();
                 const mimeType = mimeTypes[extension];
+                if (extension === ".bmp") {
+                    throw new Error(`BMP images are not accepted by vision models: ${imagePath}. ` +
+                        `Convert it to PNG or JPEG first.`);
+                }
                 if (!mimeType) {
                     throw new Error(`Unsupported image format: ${extension}. ` +
-                        `Supported formats: PNG, JPEG, GIF, WebP, BMP, SVG`);
+                        `Supported formats: PNG, JPEG, GIF, WebP (SVG is returned as markup text)`);
+                }
+                const { size } = await fs.stat(validPath);
+                return { imagePath, validPath, mimeType, size };
+            }));
+            // Size caps (VFO-15): per image and per call
+            const oversized = images.filter((i) => i.size > MAX_IMAGE_ATTACH_BYTES);
+            if (oversized.length > 0) {
+                throw new Error(`Image(s) exceed the ${formatMB(MAX_IMAGE_ATTACH_BYTES)} per-image limit: ` +
+                    oversized
+                        .map((i) => `${i.imagePath} (${formatMB(i.size)})`)
+                        .join(", "));
+            }
+            const totalSize = images.reduce((sum, i) => sum + i.size, 0);
+            if (totalSize > MAX_IMAGE_ATTACH_TOTAL_BYTES) {
+                throw new Error(`Images total ${formatMB(totalSize)}, which exceeds the ` +
+                    `${formatMB(MAX_IMAGE_ATTACH_TOTAL_BYTES)} limit per attach_image call. ` +
+                    `Attach fewer images per call.`);
+            }
+            const imageContents = await Promise.all(images.map(async ({ imagePath, validPath, mimeType }) => {
+                if (mimeType === "image/svg+xml") {
+                    const markup = await fs.readFile(validPath, "utf-8");
+                    return {
+                        type: "text",
+                        text: `SVG image ${imagePath} (vector markup; vision models accept only PNG, JPEG, GIF and WebP, so the SVG source is provided as text):\n` +
+                            markup,
+                    };
                 }
-                const data = await readFileAsBase64Stream(validPath);
                 return {
                     type: "image",
-                    data: data,
+                    data: await readFileAsBase64Stream(validPath, MAX_IMAGE_ATTACH_BYTES),
                     mimeType: mimeType,
                 };
             }));
@@ -219,7 +292,7 @@ export async function handleReadTool(name, args) {
                             break;
                         case "full":
                         default:
-                            content = await readFileContent(validPath);
+                            content = await readFullTextFile(validPath);
                             break;
                     }
                     return `${fileRequest.path}:\n${content}\n`;