@n0zer0d4y/vulcan-file-ops 1.2.13 → 1.3.0

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`;

package/dist/tools/shell-tool.js

@@ -1,21 +1,28 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import { ShellCommandArgsSchema, } from "../types/index.js";
-import { validateCommand, extractRootCommands, isDangerousCommand, getShellConfig, } from "../utils/command-validation.js";
+import { validateCommand, getDangerousRoots, getShellConfig, } from "../utils/command-validation.js";
 import { executeShellCommand, } from "../utils/shell-execution.js";
 import { validatePath, getAllowedDirectories } from "../utils/lib.js";
-import { extractPathsFromCommand } from "../utils/command-path-extraction.js";
-import { isPathWithinAllowedDirectories } from "../utils/path-validation.js";
+import { findDisallowedCommandPaths } from "../utils/command-path-extraction.js";
+import { parseShellCommand, getRootCommands } from "../utils/shell-parser.js";
 import { sanitizeToolInputSchema } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 // Global state for approved commands
 let approvedCommands = new Set();
 let alwaysApprovedCommands = new Set();
+// Root commands the operator allows to match dangerous patterns
+let dangerousCommandAllowlist = new Set();
 /**
- * Initialize the shell tool with approved commands
+ * Initialize the shell tool with approved commands and (optionally) the root
+ * commands that may run even when they match a dangerous pattern.
  */
-export function initializeShellTool(commands) {
+export function initializeShellTool(commands, dangerousCommands = []) {
     approvedCommands = new Set(commands);
+    dangerousCommandAllowlist = new Set(dangerousCommands);
+}
+export function getDangerousCommandAllowlist() {
+    return Array.from(dangerousCommandAllowlist);
 }
 /**
  * Get the list of approved commands
@@ -57,8 +64,13 @@ export function getShellTools() {
                 `\n\n⚠️  SECURITY REQUIREMENTS:\n` +
                 `- At least ONE approved directory must be configured before executing any shell commands\n` +
                 `- Working directory (workdir parameter or process.cwd()) MUST be within allowed directories\n` +
-                `- All file/directory paths in command arguments are validated against allowed directories\n` +
-                `- Command substitution and dangerous patterns may be restricted\n` +
+                `- All file/directory paths in arguments and redirections are validated against allowed directories (symlinks are resolved)\n` +
+                `- Every command in a chain must be approved; chain with ';', '&&', '||' or '|' on a single line` +
+                (shellConfig.platform === "Windows"
+                    ? ` (on Windows use ';' or '|': Windows PowerShell 5.1 does not support '&&' or '||')\n`
+                    : `\n`) +
+                `- Not allowed: newlines, command substitution, backticks, a lone '&', ( ) { } grouping or script blocks, heredocs, escaped quotes (\\" \\')\n` +
+                `- Commands matching dangerous patterns are blocked unless the server operator allowed them\n` +
                 `\n` +
                 `If no workdir is specified, the server's current working directory will be used and validated.` +
                 approvedCommandsText +
@@ -107,19 +119,16 @@ export async function handleShellTool(name, args) {
     }
     // Validate arguments
     const validatedArgs = ShellCommandArgsSchema.parse(args);
-    // Validate command security
+    // Validate command security (substitution, control characters, grammar)
     const commandValidation = validateCommand(validatedArgs.command, false);
     if (!commandValidation.allowed) {
-        throw new Error(`Command validation failed: ${commandValidation.reason}`);
-    }
-    // Extract root commands for approval checking
-    const rootCommands = extractRootCommands(validatedArgs.command);
-    const allApproved = rootCommands.every((cmd) => approvedCommands.has(cmd) || alwaysApprovedCommands.has(cmd));
-    // SECURITY FIX: Block ALL unapproved commands immediately
-    // Previously, commands were only blocked if (!allApproved && (requiresApproval || isDangerous))
-    // This allowed unapproved non-dangerous commands to execute by default
-    if (!allApproved) {
-        const unapprovedCommands = rootCommands.filter((cmd) => !approvedCommands.has(cmd) && !alwaysApprovedCommands.has(cmd));
+        throw new Error(`Access denied: Command validation failed: ${commandValidation.reason}`);
+    }
+    const parsed = parseShellCommand(validatedArgs.command);
+    // Every command in the chain must be approved
+    const rootCommands = getRootCommands(parsed);
+    const unapprovedCommands = rootCommands.filter((cmd) => !approvedCommands.has(cmd) && !alwaysApprovedCommands.has(cmd));
+    if (rootCommands.length === 0 || unapprovedCommands.length > 0) {
         const approvedList = Array.from(approvedCommands).join(", ");
         throw new Error(`Access denied: Command not in approved list.\n` +
             `Unapproved commands: ${unapprovedCommands.join(", ")}\n` +
@@ -127,19 +136,18 @@ export async function handleShellTool(name, args) {
             `Approved commands: ${approvedList || "(none configured)"}\n\n` +
             `To execute this command, add it to --approved-commands configuration.`);
     }
-    // SECURITY: Check dangerous patterns even for approved commands
-    // This provides defense-in-depth against accidentally approving dangerous commands
-    const isDangerous = isDangerousCommand(validatedArgs.command);
-    if (isDangerous && !validatedArgs.requiresApproval) {
-        throw new Error(`⚠️  Dangerous command pattern detected.\n` +
+    // Dangerous patterns are blocked even for approved commands unless the
+    // server operator explicitly allowed that root command. The caller cannot
+    // opt in: requiresApproval is ignored.
+    const blockedDangerousRoots = getDangerousRoots(parsed).filter((cmd) => !dangerousCommandAllowlist.has(cmd));
+    if (blockedDangerousRoots.length > 0) {
+        throw new Error(`Access denied: Dangerous command pattern detected.\n` +
             `Command: ${validatedArgs.command}\n` +
-            `This command requires explicit approval.\n` +
-            `Set requiresApproval: true in the command arguments to proceed.`);
+            `Blocked commands: ${blockedDangerousRoots.join(", ")}\n` +
+            `The server operator can allow these with --allow-dangerous-commands.`);
     }
-    // SECURITY FIX: Validate working directory ALWAYS (not just if provided)
-    // This prevents bypass via process.cwd() when workdir is omitted
+    // Validate working directory ALWAYS (not just if provided)
     const allowedDirs = getAllowedDirectories();
-    // Require at least one approved directory for shell execution
     if (allowedDirs.length === 0) {
         throw new Error(`Access denied: Shell execution requires at least one approved directory.\n` +
             `No allowed directories are currently configured.\n` +
@@ -150,7 +158,6 @@ export async function handleShellTool(name, args) {
             `\n` +
             `Example: register_directory with path "C:/path/to/your/project"`);
     }
-    // Always validate working directory against allowed directories
     let workdir = validatedArgs.workdir || process.cwd();
     try {
         workdir = await validatePath(workdir);
@@ -167,44 +174,23 @@ export async function handleShellTool(name, args) {
             `  1. Register the directory using register_directory tool, OR\n` +
             `  2. Specify a workdir parameter within an approved directory`);
     }
-    // Extract and validate paths from command arguments
+    // Validate every file system operand (arguments and redirection targets),
+    // resolving symlinks/junctions
+    let deniedPaths;
     try {
-        const extractedPaths = extractPathsFromCommand(validatedArgs.command, workdir);
-        if (extractedPaths.length > 0) {
-            const allowedDirs = getAllowedDirectories();
-            // If no allowed directories are configured, block all paths for security
-            if (allowedDirs.length === 0) {
-                throw new Error(`Access denied: Command contains paths but no allowed directories are configured.\n` +
-                    `Extracted paths:\n` +
-                    extractedPaths.map((p) => `  - ${p}`).join("\n") +
-                    `\n\nPlease configure allowed directories using --approved-folders or register_directory tool.`);
-            }
-            // Validate each extracted path
-            const invalidPaths = [];
-            for (const extractedPath of extractedPaths) {
-                if (!isPathWithinAllowedDirectories(extractedPath, allowedDirs)) {
-                    invalidPaths.push(extractedPath);
-                }
-            }
-            if (invalidPaths.length > 0) {
-                throw new Error(`Access denied: Command contains paths outside allowed directories:\n` +
-                    invalidPaths.map((p) => `  - ${p}`).join("\n") +
-                    `\n\nAllowed directories:\n` +
-                    allowedDirs.map((d) => `  - ${d}`).join("\n") +
-                    `\n\nTo access these paths, register their parent directories using register_directory tool.`);
-            }
-        }
+        deniedPaths = await findDisallowedCommandPaths(parsed, workdir);
     }
     catch (error) {
-        // If path extraction fails, be conservative and block
-        // (better to block than allow potentially unsafe commands)
-        if (error instanceof Error && error.message.includes("Access denied")) {
-            throw error;
-        }
-        // For extraction errors, block the command to be safe
-        throw new Error(`Path validation failed: ${error instanceof Error ? error.message : String(error)}\n` +
+        throw new Error(`Access denied: Path validation failed: ${error instanceof Error ? error.message : String(error)}\n` +
             `Command blocked for security. Please ensure all paths in the command are within allowed directories.`);
     }
+    if (deniedPaths.length > 0) {
+        throw new Error(`Access denied: Command contains paths outside allowed directories:\n` +
+            deniedPaths.map((p) => `  - ${p}`).join("\n") +
+            `\n\nAllowed directories:\n` +
+            allowedDirs.map((d) => `  - ${d}`).join("\n") +
+            `\n\nTo access these paths, register their parent directories using register_directory tool.`);
+    }
     // Execute command
     try {
         const result = await executeShellCommand(validatedArgs.command, {

package/dist/tools/write-tools.js

@@ -1,9 +1,8 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import path from "path";
-import { promises as fs } from "fs";
 import { WriteFileArgsSchema, WriteMultipleFilesArgsSchema, EditFileArgsSchema, } from "../types/index.js";
-import { validatePath, writeFileContent, readFileContent, applyFileEdits, } from "../utils/lib.js";
+import { validatePath, writeFileContent, writeBinaryFileAtomic, readFileContent, applyFileEdits, getFileStats, } from "../utils/lib.js";
 import { isHTMLContent, convertHTMLToPDF, convertHTMLToDOCX, } from "../utils/html-to-document.js";
 import { sanitizeToolInputSchema } from "../utils/tool-schema.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
@@ -28,15 +27,15 @@ async function writeFileBasedOnExtension(validPath, content) {
                 title: fileTitle,
                 author: "vulcan-file-ops",
             });
-            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
-            await fs.writeFile(validPath, pdfBuffer);
+            // SECURITY: validPath pre-validated by validatePath(); atomic, symlink-safe write (VFO-17)
+            await writeBinaryFileAtomic(validPath, pdfBuffer);
         }
         else {
             // Fallback to simple text PDF for plain text
             const { createSimpleTextPDF } = await import("../utils/pdf-writer.js");
             const pdfBuffer = await createSimpleTextPDF(content);
-            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
-            await fs.writeFile(validPath, pdfBuffer);
+            // SECURITY: validPath pre-validated by validatePath(); atomic, symlink-safe write (VFO-17)
+            await writeBinaryFileAtomic(validPath, pdfBuffer);
         }
     }
     else if (ext === ".docx") {
@@ -46,15 +45,15 @@ async function writeFileBasedOnExtension(validPath, content) {
                 title: fileTitle,
                 author: "vulcan-file-ops",
             });
-            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
-            await fs.writeFile(validPath, docxBuffer);
+            // SECURITY: validPath pre-validated by validatePath(); atomic, symlink-safe write (VFO-17)
+            await writeBinaryFileAtomic(validPath, docxBuffer);
         }
         else {
             // Fallback to simple text DOCX for plain text
             const { createSimpleDOCX } = await import("../utils/docx-writer.js");
             const docxBuffer = await createSimpleDOCX(content);
-            // SECURITY: validPath pre-validated by validatePath() - safe from path traversal (CWE-23)
-            await fs.writeFile(validPath, docxBuffer);
+            // SECURITY: validPath pre-validated by validatePath(); atomic, symlink-safe write (VFO-17)
+            await writeBinaryFileAtomic(validPath, docxBuffer);
         }
     }
     else {
@@ -391,25 +390,25 @@ export async function handleWriteTool(name, args) {
                         createParentIfMissing: true,
                     });
                     return {
+                        success: true,
                         path: file.path,
                         validPath,
                         content: file.content,
-                        success: true,
                     };
                 }
                 catch (error) {
                     return {
-                        path: file.path,
-                        content: file.content,
                         success: false,
+                        path: file.path,
                         error: error instanceof Error ? error.message : String(error),
                     };
                 }
             });
             const validatedFiles = await Promise.all(validationPromises);
-            // Separate valid and invalid files
-            const validFiles = validatedFiles.filter((f) => f.success);
-            const invalidFiles = validatedFiles.filter((f) => !f.success);
+            // Separate valid and invalid files. The type guard (no cast) ensures
+            // only entries carrying a validatePath() result can reach the writer.
+            const validFiles = validatedFiles.flatMap((f) => (f.success ? [f] : []));
+            const invalidFiles = validatedFiles.flatMap((f) => f.success ? [] : [f]);
             // If any paths are invalid, fail the entire operation
             if (invalidFiles.length > 0) {
                 const errorMessages = invalidFiles
@@ -421,10 +420,13 @@ export async function handleWriteTool(name, args) {
             const writePromises = validFiles.map(async (file) => {
                 try {
                     await writeFileBasedOnExtension(file.validPath, file.content);
+                    // Report the size of the written file: for PDF/DOCX this is the
+                    // generated document, not the length of the HTML input.
+                    const { size } = await getFileStats(file.validPath);
                     return {
                         path: file.path,
                         success: true,
-                        size: Buffer.byteLength(file.content, "utf8"),
+                        size,
                     };
                 }
                 catch (error) {

package/dist/types/index.js

@@ -342,7 +342,10 @@ export const GrepArgsSchema = z.object({
     pattern: z.string().describe("Regex pattern to search for"),
     path: z.string().optional().describe("Directory/file to search (optional)"),
     type: z.string().optional().describe("File type filter: js, py, ts, etc"),
-    glob: z.string().optional().describe("Glob filter: *.js, **/*.test.ts"),
+    glob: z
+        .string()
+        .optional()
+        .describe("Glob filter. Without a slash it matches file names at any depth (*.md, *.test.ts); with a slash it matches the path relative to the search root (src/**/*.ts)"),
     "-i": z.boolean().optional().default(false).describe("Case insensitive"),
     "-A": z.number().optional().describe("Lines after match"),
     "-B": z.number().optional().describe("Lines before match"),
@@ -429,7 +432,7 @@ export const ShellCommandArgsSchema = z.object({
         .boolean()
         .optional()
         .default(false)
-        .describe("Indicates if this command requires explicit user approval. " +
-        "Set to true for potentially dangerous operations (installing packages, deleting files, etc.)."),
+        .describe("Deprecated and ignored. Kept for backward compatibility. " +
+        "Commands matching dangerous patterns can only be allowed by the server operator (--allow-dangerous-commands)."),
 });
 //# sourceMappingURL=index.js.map