@n0zer0d4y/vulcan-file-ops 1.2.14 → 1.3.0

package/CHANGELOG.md

@@ -9,6 +9,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+## [1.3.0] - 2026-10-04
+
+Security hardening release. Upgrading is strongly recommended. See **Breaking Changes** before upgrading.
+
+### Security
+
+- **execute_shell: commands could bypass the approved-command list.** Newline-separated commands were not seen by the allowlist check. Commands are now parsed with a conservative, quote-aware parser that accepts only a grammar bash and PowerShell interpret the same way; newlines and control characters, backticks, escaped quotes (`\"`, `\'`), a lone `&`, `( )`/`{ }` grouping and script blocks, heredocs, Unicode quotes and PowerShell's `--%` are rejected. Separators inside quotes are now correctly treated as data.
+- **execute_shell: path validation gaps.** Slash-prefixed absolute paths (`/etc/passwd`, `/Windows/...`) were treated as command switches and never validated; redirection targets written without a space (`>C:\outside\file`) were not validated; paths through symlinks/junctions were checked only lexically (GitHub issue #3). Every operand, option value (`--out=...`, `-C:\x`), redirection target and `cd` target is now validated lexically, after `realpath`, and with physical resolution (symlinks followed before `..`). Relative operands are checked against every directory a `cd` could leave the command in. Arguments with unresolvable variables and PowerShell provider paths (`env:`, `HKLM:`, ...) are refused.
+- **execute_shell: dangerous-command check could be self-approved.** The `requiresApproval` argument let the caller (the AI) bypass the dangerous-pattern check. It is now ignored; the server operator can allow specific commands with `--allow-dangerous-commands`. The over-broad `format` pattern no longer matches `Get-Date -Format`.
+- **make_directory could create directories outside approved folders** through a symlink or junction (GitHub issue #3). Paths are now validated canonically and created segment by segment with a `realpath` check after each segment.
+- **register_directory let the AI widen its own access without user involvement.** Registration now requires user confirmation through the MCP client by default (see `--runtime-registration`). The real path is registered; filesystem roots and the home directory require `allow`.
+- **`.env` in the server's working directory controlled the shell allowlist** and was injected into the environment of executed commands. The working-directory `.env` is no longer read (see `--commands-env-file`).
+- **PDF generation could crash the server.** Any `<img>` that was not an inline `data:` image caused an unhandled promise rejection that terminated the process; corrupt PNG data could also crash it. Images are now sanitized (only `data:image/...` images up to 10 MB are embedded; others are replaced by their alt text), PDF rendering errors are returned as tool errors with a 30 s timeout, and unhandled rejections are logged to stderr instead of terminating the server.
+- **DOCX generation fetched remote image URLs** (server-side HTTP request with the response embedded in the document). Remote images are no longer fetched.
+- **grep_files regular expressions could freeze the server** (catastrophic backtracking). Matching now runs in a worker thread with a 5 s per-file and 30 s per-search budget; regex and glob patterns are limited to 1,000 characters.
+- **Unbounded reads and decompression.** Full-mode text reads are capped at 10 MB (use `head`/`tail`/`range` for larger files), `attach_image` at 10 MB per image and 20 MB per call, and Office/ODF documents are checked for zip bombs (size, entry count, compression ratio, ZIP64) before parsing.
+- **Directory copies dereferenced symlinks**, copying files from outside approved folders into them. Copying a directory that contains symlinks or junctions is now refused.
+- **PDF/DOCX output is written atomically** and never through a symlink, like text files.
+- **Dependencies refreshed** with a 14-day release quarantine (`npm --before`), including `@modelcontextprotocol/sdk` 1.20.0 → 1.30.0 (fixes GHSA-345p-7cg4-v4c7, GHSA-w48q-cv73-mx4w, GHSA-8r9q-7v3j-jr4g), `axios` (via `@turbodocx/html-to-docx`), `@xmldom/xmldom`, `minimatch`, `mammoth` and `officeparser` 5.2 → 7.8 (fixes a `file-type` infinite loop on crafted files). Snyk Open Source runtime findings went from 89 to 0 open; one `pdfjs-dist` advisory is ignored with justification because it is unreachable (PDFs are never parsed with `officeparser`, and the issue requires browser rendering). All packages pass `npm audit signatures`.
+- **Office/ODF spreadsheet expansion is bounded.** `officeparser` 7.x caps ODF "repeated cells" at 1,000,000 cells, so a tiny file that claims billions of cells can no longer expand without limit; its ZIP decompression limits are aligned with the zip-bomb pre-check (200 MB, 10,000 entries).
+
+### Breaking Changes
+
+- `register_directory` asks the user to confirm each directory by default. Clients without MCP elicitation support get a refusal; use `--approved-folders`, or start the server with `--runtime-registration allow` to restore the previous behavior.
+- The server no longer reads `.env` from its working directory. Pass `--approved-commands`, or `--commands-env-file <path>` (only `APPROVED_COMMANDS` is read). `APPROVED_COMMANDS` set as a process environment variable is no longer used. `--env-file` is rejected because Node.js reserves it.
+- `execute_shell` rejects commands outside the supported grammar (see Security above), and `requiresApproval` no longer bypasses dangerous-pattern blocking.
+- Node.js 20.19+ (or 22.12+) is required (already required by `jsdom` 27; now declared in `engines`).
+- Copying directories that contain symlinks or junctions is refused.
+- Full-mode reads of text files over 10 MB are refused.
+- `officeparser` 7.x (used for PPTX, XLSX and OpenDocument files) adds about 46 MB to the install, mostly the `tesseract.js` OCR engine it depends on. OCR is disabled and the engine is never loaded, but it is downloaded with the package.
+- `move_file` refuses to overwrite an existing destination (previously it replaced it silently). Use `file_operations` with `onConflict: "overwrite"` to replace files.
+- `attach_image` returns SVG files as markup text and rejects BMP files; only PNG, JPEG, GIF and WebP are returned as images.
+- `grep_files` `glob` without a slash now matches at any depth (`*.md` also matches `docs/guide.md`).
+
+### Added
+
+- `--runtime-registration <confirm|allow|deny>`, `--allow-dangerous-commands <cmds>`, `--commands-env-file <path>`.
+- `SECURITY.md` with private vulnerability reporting instructions.
+- GitHub Actions CI: runs the test suite and the build on Windows with Node 22.
+- Dependabot version updates for npm and GitHub Actions with a 14-day cooldown.
+- `engines` field in `package.json` (`^20.19.0 || >=22.12.0`).
+- Regression test suites for the fixes above.
+
+### Changed
+
+- Blocked `execute_shell` commands now report errors starting with `Access denied:` (validation, approval, dangerous-pattern and path checks).
+- The `.snyk` policy, which was invalid and suppressed nothing, is replaced by a minimal policy with one justified, time-boxed ignore.
+- Test tooling is pinned to `jest` / `@jest/globals` 30.2.0 and `ts-jest` 29.4.6; newer versions hang on several suites in this project.
+- Documentation corrected: Node.js requirement (was "14 or higher"), README security claims that the 1.3.0 audit disproved, and dated notes on the earlier audit reports in `docs/`.
+
+### Fixed
+
+- DOCX generation no longer mangles quoted HTML attributes (inline images and `style` attributes work again).
+- Shell path-validation tests that passed for the wrong reason (missing `workdir`) now assert the actual path denial.
+- `move_file` no longer silently overwrites an existing destination, matching its description; case-only renames (e.g. `readme.md` → `README.md`) now take effect.
+- `read_file` / `read_multiple_files` `tail` mode no longer counts the newline at the end of a file as an extra empty line.
+- `grep_files` `glob` without a slash (e.g. `*.md`) now matches files at any depth, like ripgrep; patterns with a slash still match the path from the search root.
+- `write_multiple_files` reports the size of the written file; for PDF/DOCX this was previously the length of the HTML input.
+- `attach_image` no longer sends SVG or BMP as images (vision models reject them): SVG is returned as markup text and BMP returns an error asking for PNG/JPEG.
+- A destination that resolves outside the allowed directories is reported as "Access denied" instead of "Parent directory does not exist".
+- The `execute_shell` description recommends `;` on Windows, where Windows PowerShell 5.1 does not support `&&` or `||`.
+
 ## [1.2.14] - 2026-05-16
 
 ### Fixed

package/README.md

@@ -72,7 +72,7 @@ This enhanced implementation provides:
 This server supports multiple flexible approaches to directory access:
 
 1. **Pre-configured Access**: Use `--approved-folders` to specify directories on server start for immediate access
-2. **Runtime Registration**: Users can instruct AI agents to register directories during conversation via `register_directory` tool
+2. **Runtime Registration**: Users can instruct AI agents to register directories during conversation via `register_directory` tool. By default you are asked to confirm each new directory through your MCP client (see [Runtime Registration Policy](#runtime-registration-policy))
 3. **MCP Roots Protocol**: Client applications can provide workspace directories dynamically
 4. **Flexible Permissions**: Combine multiple approaches - start with approved folders, add more at runtime
 5. **Secure Boundaries**: All operations validate against registered directories regardless of access method
@@ -109,7 +109,7 @@ npm install @n0zer0d4y/vulcan-file-ops
 
 ### Prerequisites
 
-**Node.js** (version 14 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.
+**Node.js** (version 20.19 or higher, or 22.12 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.
 
 - **Download Node.js**: https://nodejs.org/
 - **Check installation**: Run `node --version` and `npm --version`
@@ -399,6 +399,28 @@ Or enable individual tools:
 }
 ```
 
+#### Shell Commands
+
+`execute_shell` only runs commands whose root command is approved:
+
+- `--approved-commands npm,node,git` — comma-separated allowlist of root commands. Every command in a chain (`;`, `&&`, `||`, `|`) must be approved.
+- `--allow-dangerous-commands rm` — approved commands that may also run when they match a dangerous pattern (for example `rm -rf`, `del /s`, `Remove-Item -Recurse`, `sudo`). Without this flag such commands are always blocked; the AI cannot override it.
+- `--commands-env-file <path>` — read `APPROVED_COMMANDS` from a `.env`-format file. Only that key is used and nothing is added to the server's environment. `--approved-commands` takes priority.
+
+> **Changed in 1.3.0:** the server no longer reads a `.env` file from its working directory. Use `--approved-commands` or `--commands-env-file`. Do not use `--env-file`: Node.js reserves that flag and would apply the file to the server process itself.
+
+> **Note:** `execute_shell` is not a sandbox. An approved interpreter or code-running tool (`node`, `python`, `bash`, `npm`, `git`, `find -exec`, ...) can do anything your user account can do. Only approve commands you are comfortable letting the AI run.
+
+#### Runtime Registration Policy
+
+`--runtime-registration <confirm|allow|deny>` controls the `register_directory` tool:
+
+- `confirm` (default) — you are asked to approve each new directory through your MCP client's confirmation prompt (MCP elicitation). If the client does not support confirmation prompts, registration is refused; add the folder with `--approved-folders` instead, or use `allow`.
+- `allow` — directories are registered without a prompt (the behavior before 1.3.0).
+- `deny` — runtime registration is disabled; only `--approved-folders` and MCP Roots grant access.
+
+Filesystem roots (such as `C:\` or `/`) and your home directory itself can only be registered with `allow`.
+
 #### Combined Configuration
 
 All configuration options can be combined:
@@ -490,7 +512,7 @@ To access a specific directory, instruct the AI agent:
 "Please register the directory C:\path\to\your\folder for access, then list its contents."
 ```
 
-The AI will use the `register_directory` tool to gain access, then perform operations within that directory.
+The AI will use the `register_directory` tool to gain access, then perform operations within that directory. With the default `--runtime-registration confirm` policy your MCP client asks you to approve the directory first.
 
 ## API
 
@@ -526,7 +548,7 @@ Attach images for AI vision analysis
 
 - `path` (string | string[]): Path to image file, or array of paths to attach multiple images at once
 
-**Output:** Image content in MCP format for vision model processing. Supports PNG, JPEG, GIF, WebP, BMP, SVG
+**Output:** Image content in MCP format for vision model processing. Supports PNG, JPEG, GIF and WebP (the formats vision models accept). SVG files are returned as their markup text; BMP is not supported (convert to PNG)
 
 ##### read_multiple_files
 
@@ -708,7 +730,7 @@ Enable runtime access to new directories
 
 - `path` (string): Directory path to register
 
-**Output:** Success confirmation. Directory becomes accessible for operations
+**Output:** Success confirmation. Directory becomes accessible for operations. The directory's real path (symlinks resolved) is registered. Subject to `--runtime-registration` (default: user confirmation via the MCP client).
 
 ##### list_allowed_directories
 
@@ -730,7 +752,7 @@ Find files using glob pattern matching
 - `pattern` (string): Glob pattern (e.g., `**/*.ts`)
 - `excludePatterns` (array, optional): Patterns to exclude
 
-**Output:** List of matching file paths
+**Output:** List of matching file paths. Patterns are limited to 1,000 characters.
 
 ##### grep_files
 
@@ -751,6 +773,8 @@ Search for text patterns within files
 
 **Output:** Matching lines with context, file paths, or match counts
 
+Regex matching runs in a worker thread with a time budget (5 s per file, 30 s per search), so a pathological pattern fails with a timeout error instead of freezing the server. Patterns are limited to 1,000 characters.
+
 #### Shell Operations
 
 ##### execute_shell
@@ -763,6 +787,7 @@ Execute shell commands with security controls
 - `description` (string, optional): Command purpose
 - `workdir` (string, optional): Working directory (must be within allowed directories). If not provided, process.cwd() is used and validated
 - `timeout` (number, optional): Timeout in milliseconds (default: 30000)
+- `requiresApproval` (boolean, optional): Deprecated and ignored (kept for compatibility)
 
 **Output:** Exit code, stdout, stderr, and execution metadata
 
@@ -770,8 +795,11 @@ Execute shell commands with security controls
 
 - At least one approved directory must be configured before executing shell commands
 - Working directory (whether explicit or default process.cwd()) is always validated against allowed directories
-- All file/directory paths in command arguments are automatically extracted and validated against allowed directories
-- Commands referencing paths outside approved directories are blocked, preventing directory restriction bypasses
+- Every command in a chain (`;`, `&&`, `||`, `|`) must be in `--approved-commands`
+- File and directory operands (arguments, option values such as `--out=...`, and redirection targets) are validated against allowed directories after resolving symlinks and junctions; operands with variables that cannot be resolved are refused
+- Commands must be a single line. Not allowed: newlines, command substitution, backticks, a lone `&`, `( )`/`{ }` grouping or script blocks, heredocs, and escaped quotes (`\"`, `\'`)
+- Commands matching dangerous patterns are blocked unless the operator allowed them with `--allow-dangerous-commands`
+- `execute_shell` is not a sandbox: approved interpreters and code-running tools can still do anything your account can do
 
 ### Multi-File Edit Examples
 
@@ -849,7 +877,7 @@ For detailed usage examples, see [Tool Usage Guide](docs/TOOL_USAGE_GUIDE.md)
 
 ## Security
 
-This MCP server implements enterprise-grade security controls to protect against common filesystem vulnerabilities. All security measures are based on industry best practices and address known CVE patterns.
+This MCP server implements security controls to protect against common filesystem vulnerabilities, based on known CVE patterns. To report a vulnerability, please follow [SECURITY.md](SECURITY.md) (private reporting; do not open a public issue).
 
 ### Protected Against
 
@@ -863,17 +891,17 @@ This MCP server implements enterprise-grade security controls to protect against
 #### Command Injection (CWE-78)
 
 - **Protected Pattern**: CVE-2025-54795
-- **Mitigation**: Multi-layer validation including command substitution detection, root command extraction, and dangerous pattern matching
-- **Implementation**: Blocks `$()`, `` ` ` ``, `>()`, `<()` patterns; validates all commands in chains; requires approval for dangerous operations
-- **Example**: Prevents `echo "; malicious_cmd; echo"` injection attempts
+- **Mitigation**: Commands are parsed with a conservative, quote-aware parser; only a small grammar that bash and PowerShell interpret the same way is accepted, and every command in a chain must be approved
+- **Implementation**: Rejects newlines and control characters, command substitution, backticks, escaped quotes, a lone `&`, grouping/script blocks and heredocs; dangerous patterns are blocked unless the operator allows them (`--allow-dangerous-commands`)
+- **Example**: `echo "\"; malicious_cmd; echo \""` and newline-separated commands are rejected
 
 #### Shell Command Directory Bypass (CWE-22)
 
-- **Protected Pattern**: Path restriction bypass via absolute paths in shell commands
-- **Mitigation**: Path extraction and validation for all file/directory paths embedded in command arguments
-- **Implementation**: Extracts paths from command strings (handles Windows/Unix paths, quotes, relative paths, environment variables), validates each path against allowed directories before execution
-- **Example**: Blocks `type C:\Windows\System32\drivers\etc\hosts` and `cat /etc/passwd` when these paths are outside approved directories
-- **Scope**: Applies to all shell commands executed via `execute_shell` tool - paths in arguments are validated just like filesystem operations
+- **Protected Pattern**: Path restriction bypass via paths in shell commands
+- **Mitigation**: Every file operand (arguments, option values such as `--out=...`, redirection targets, `cd` targets) is validated against allowed directories after resolving symlinks and junctions
+- **Implementation**: Operands are checked lexically, after `realpath`, and with physical resolution (symlinks followed before `..`, as a POSIX kernel does); relative operands are checked against every directory a `cd` could leave the command in; unresolvable variables and PowerShell provider paths (`env:`, `HKLM:`, ...) are refused
+- **Example**: Blocks `cat /etc/passwd`, `type C:\Windows\System32\drivers\etc\hosts`, `echo x >C:\outside\file` and `cat link/secret` (where `link` points outside) when the targets are outside approved directories
+- **Scope**: `execute_shell` is not a sandbox. An approved interpreter or code-running tool can still do anything your account can do, so approve commands sparingly
 
 #### Symlink Attacks (CWE-59 / CWE-61)
 
@@ -899,16 +927,17 @@ This MCP server implements enterprise-grade security controls to protect against
 
 #### Command Execution
 
-- **Command Whitelisting**: Only pre-approved commands execute without confirmation
-- **Pattern Detection**: Blocks dangerous patterns (destructive, privilege escalation, network execution)
-- **Command Substitution Blocking**: Prevents `$()`, backticks, process substitution
+- **Command Allowlist**: Only commands listed in `--approved-commands` execute; everything else is blocked
+- **Pattern Detection**: Blocks dangerous patterns (destructive, privilege escalation, network execution) unless the operator allows the command with `--allow-dangerous-commands`
+- **Structural Parsing**: Rejects command substitution, backticks, newlines, grouping and other constructs that could hide commands from validation
 - **Root Command Extraction**: Analyzes all commands in chained operations for approval
-- **Path Argument Validation**: Extracts and validates all file/directory paths in command arguments against allowed directories (prevents bypass via absolute paths in commands)
+- **Path Operand Validation**: Validates all file/directory operands, including redirection targets, against allowed directories with symlink resolution
 
 #### Access Controls
 
 - **Directory Whitelisting**: Operations restricted to explicitly approved directories
-- **Runtime Registration**: Additional directories require explicit registration via `register_directory` tool
+- **Runtime Registration**: Additional directories require registration via `register_directory`, which asks the user to confirm by default (`--runtime-registration`)
+- **Resource Limits**: Full-file text reads are capped at 10 MB, `attach_image` at 10 MB per image and 20 MB per call, and Office/ODF documents are checked for zip bombs before parsing
 - **Atomic Validation**: Paths validated before any file operations begin
 - **Cross-Platform Safety**: Proper handling of Windows/Unix path differences and UNC paths
 
@@ -917,7 +946,7 @@ This MCP server implements enterprise-grade security controls to protect against
 1. **Minimize Approved Directories**: Only approve directories that require AI access
 2. **Use Directory Filtering**: Exclude sensitive folders (e.g., `.git`, `node_modules`) from listings
 3. **Limit Tool Access**: Enable only necessary tools via `--enabled-tools` or `--enabled-tool-categories`
-4. **Command Approval**: Pre-approve safe commands via `--approved-commands`; require approval for others
+4. **Command Approval**: Approve only the commands you need via `--approved-commands`; avoid shells and interpreters (`bash`, `sh`, `powershell`, `node`, `python`, `eval`), which can run arbitrary code
 5. **Monitor Operations**: Review MCP client logs for unexpected access attempts
 6. **Regular Updates**: Keep the server updated to receive security patches
 
@@ -928,13 +957,19 @@ This server has been comprehensively audited against known vulnerabilities and s
 **CVE Protection Status:**
 
 - ✅ CVE-2025-54794 (Path Restriction Bypass) - **FIXED**
-- ✅ CVE-2025-54795 (Command Injection) - **PROTECTED**
-- ✅ CVE-2025-53109 (Symlink Attacks) - **PROTECTED**
+- ✅ CVE-2025-54795 (Command Injection) - **PROTECTED** (escaped-quote and newline variants closed in 1.3.0)
+- ✅ CVE-2025-53109 (Symlink Attacks) - **PROTECTED** (`make_directory` and `execute_shell` gaps closed in 1.3.0)
 - ✅ CVE-2025-53110 (Directory Containment Bypass) - **PROTECTED**
-- ✅ Shell Execution Directory Bypass - **FIXED** (November 2024)
+- ✅ Shell Execution Directory Bypass - **FIXED** in 1.3.0. The November 2024 fix was incomplete: slash-prefixed paths, attached redirections and symlinked paths could still escape
 
 **Latest Security Audits:**
 
+- 📋 Security hardening release 1.3.0 - October 2026
+  - **Scope**: Independent audit of GitHub issue #3 plus a Snyk Open Source / Snyk Code / container scan and manual review
+  - **Fixed**: newline command chaining past the allowlist, shell path validation gaps (slash paths, redirections, symlinks), self-approved dangerous commands, `make_directory` symlink escape, AI-initiated directory registration without consent, `.env` loading from the working directory, PDF image handling that could crash the server or fetch remote URLs, unbounded regex/read/decompression resource use, symlink dereferencing in directory copies
+  - **Dependencies**: refreshed with a 14-day release quarantine; all packages pass `npm audit signatures`
+  - See [CHANGELOG.md](CHANGELOG.md) for details
+
 - 📋 [Snyk Vulnerability Audit Report - November 2025](docs/SNYK_VULNERABILITY_AUDIT_2025.md)
   - **Status**: 5/6 Snyk findings validated as false positives, 1 finding fixed
   - **Risk Level**: LOW - Comprehensive path traversal protection verified
@@ -945,10 +980,10 @@ This server has been comprehensively audited against known vulnerabilities and s
   - **Focus**: CVE-2025-54794/54795 pattern analysis and mitigation strategies
   - **Date**: November 4, 2025 (Manual CVE Research)
 - 📋 [Shell Command Directory Bypass Audit - November 2025](docs/SHELL_COMMAND_AUDIT_2025-11-04.md)
-  - **Status**: ✅ Fixed November 2024 (Retrospective documentation)
+  - **Status**: Partially fixed November 2024; completed in 1.3.0 (October 2026)
   - **Issue**: Shell commands previously could access files outside approved directories via absolute paths
   - **Severity**: HIGH (CVSS ~7.5) - Path traversal via command arguments
-  - **Fix Status**: ✅ FIXED - Path extraction and validation implemented
+  - **Fix Status**: ✅ FIXED in 1.3.0 - symlink-aware validation of all operands, including redirections
   - **Test Coverage**: 419 lines of comprehensive tests, all passing
 - 📋 [Security Test Coverage Summary](docs/SECURITY_TEST_SUMMARY.md)
   - **Test Suite**: 2000+ lines of security-focused tests in `src/tests/`
@@ -999,7 +1034,7 @@ This server has been comprehensively audited against known vulnerabilities and s
 **Attach Image Tool** (`attach_image`):
 
 - Attaches images for AI vision analysis (requires vision-capable MCP client)
-- **Supported formats**: PNG, JPEG, GIF, WebP, BMP, SVG
+- **Supported formats**: PNG, JPEG, GIF, WebP (SVG is returned as markup text; BMP is not supported)
 - **Batch support**: Can attach single image or multiple images in one call
 - Images are presented to the AI as if uploaded directly by the user
 - Enables visual analysis: reading text in images, analyzing diagrams, describing scenes

package/dist/cli.js

@@ -18,6 +18,22 @@ if (isMCP) {
     // as the MCP SDK uses those for JSON-RPC protocol communication
 }
 import { runServer } from "./server/index.js";
+// Defense in depth (VFO-13): a promise rejection that a third-party library
+// fails to handle must not terminate the stdio server (Node's default for
+// unhandled rejections is to crash). Log one line to STDERR - console.* is
+// a no-op in MCP mode and stdout carries the JSON-RPC stream - and keep
+// running. uncaughtException keeps Node's default (fatal) behavior.
+process.on("unhandledRejection", (reason) => {
+    try {
+        const detail = reason instanceof Error
+            ? `${reason.name}: ${reason.message}`
+            : String(reason);
+        process.stderr.write(`[vulcan-file-ops] unhandledRejection (ignored): ${detail.replace(/\s+/g, " ").slice(0, 2000)}\n`);
+    }
+    catch {
+        // Never let diagnostics throw.
+    }
+});
 // Run the server and handle any fatal errors
 runServer().catch((error) => {
     // Only show errors when not running under MCP (to avoid protocol corruption)

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, 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)`);
         }
@@ -404,6 +489,42 @@ const server = new Server({
 // _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"],
+            },
+        }, { 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 () => {
     return {};