@n0zer0d4y/vulcan-file-ops 1.2.13 → 1.3.0

package/CHANGELOG.md

@@ -8,33 +8,105 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-
-## [1.2.13] - 2026-04-23
-
-### Fixed
-
-- Resolved the remaining MCP client tool discovery failure introduced after the SDK upgrade.
-  - Tool schemas exposed through `tools/list` are now normalized for stricter MCP clients.
-  - Removed client-hostile schema constructs from published tool input schemas, including `$schema`, `$ref`, `anyOf`, `oneOf`, and `allOf`.
-  - Replaced the highest-risk wire schemas with explicit compatibility-first object schemas for `attach_image` and `make_directory`.
-  - Preserved runtime backward compatibility while tightening the schemas advertised to clients.
-- Fixed residual MCP mode detection drift so stdio mode is triggered reliably in local and `npx` execution paths.
-- Added `zod` as a direct runtime dependency to avoid install-time fragility in clean environments and `npx` usage.
-- Synchronized package metadata so published registry metadata and local package metadata report the same release version.
-- Re-enabled and stabilized the previously skipped PDF-related Jest coverage.
-  - Enabled the 10 skipped document tests for PDF read, HTML-to-PDF write, mixed document batches, and PDF round-trip paths.
-  - Updated Jest PDF mocks so document tests exercise meaningful content paths instead of placeholder-only buffers.
-  - Suppressed expected negative-path test diagnostics inside tests so successful runs no longer look like runtime failures.
-- Added a regression test to prevent incompatible tool schema shapes from reappearing in future releases.
-
-### Changed
-
-- Documented the Codex-specific MCP configuration format in the README alongside the JSON-based client examples.
-- Updated `npx` examples to use `-y` explicitly for non-interactive client execution.
-
-## [1.2.12] - 2026-02-21
-
-### Fixed
+
+## [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
+
+- **CRITICAL**: Fixed initialization deadlock with `claude-ai` v0.1.0 client (Claude Desktop web client, protocol `2025-11-25`).
+  - **Root Cause**: A custom `setRequestHandler(InitializeRequestSchema, ...)` was overriding the SDK's internal `_oninitialize` handler. This broke the SDK's state machine: `_clientCapabilities` and `_clientVersion` were never set, and protocol version negotiation was bypassed — the server echoed back the client's requested version verbatim rather than responding with the highest version it actually supports. The new client's stricter handshake exposed this latent defect.
+  - **Fix**: Removed the custom initialize handler and restored the SDK's built-in `_oninitialize`. The server now correctly negotiates `2025-06-18` when a client requests `2025-11-25`, which the client accepts per the MCP spec.
+  - **Instructions**: Server instructions (`generateServerDescription()`) are now injected into the SDK's `_instructions` field after directory initialization in `runServer()`, so they remain present in the initialize response without requiring a custom handler.
+- Fixed `oninitialized` callback blocking the MCP handshake. The `listRoots()` call inside `oninitialized` was previously awaited, creating a potential deadlock (client won't respond to `roots/list` until after `initialized` is acknowledged, but the callback blocked acknowledgement). Changed to a detached fire-and-forget promise.
+
+## [1.2.13] - 2026-04-23
+
+### Fixed
+
+- Resolved the remaining MCP client tool discovery failure introduced after the SDK upgrade.
+  - Tool schemas exposed through `tools/list` are now normalized for stricter MCP clients.
+  - Removed client-hostile schema constructs from published tool input schemas, including `$schema`, `$ref`, `anyOf`, `oneOf`, and `allOf`.
+  - Replaced the highest-risk wire schemas with explicit compatibility-first object schemas for `attach_image` and `make_directory`.
+  - Preserved runtime backward compatibility while tightening the schemas advertised to clients.
+- Fixed residual MCP mode detection drift so stdio mode is triggered reliably in local and `npx` execution paths.
+- Added `zod` as a direct runtime dependency to avoid install-time fragility in clean environments and `npx` usage.
+- Synchronized package metadata so published registry metadata and local package metadata report the same release version.
+- Re-enabled and stabilized the previously skipped PDF-related Jest coverage.
+  - Enabled the 10 skipped document tests for PDF read, HTML-to-PDF write, mixed document batches, and PDF round-trip paths.
+  - Updated Jest PDF mocks so document tests exercise meaningful content paths instead of placeholder-only buffers.
+  - Suppressed expected negative-path test diagnostics inside tests so successful runs no longer look like runtime failures.
+- Added a regression test to prevent incompatible tool schema shapes from reappearing in future releases.
+
+### Changed
+
+- Documented the Codex-specific MCP configuration format in the README alongside the JSON-based client examples.
+- Updated `npx` examples to use `-y` explicitly for non-interactive client execution.
+
+## [1.2.12] - 2026-02-21
+
+### Fixed
 
 - **CRITICAL**: Fixed MCP server toggle failure and "no tools configured" error caused by Node.js version incompatibility and restrictive MCP detection.
   - **Node.js Compatibility**: Replaced `import ... with { type: "json" }` with manual `fs.readFileSync` for `package.json` to support Node.js versions earlier than 20.10.0 and 18.20.0 (including Node 14/16).

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`
@@ -124,10 +124,10 @@ This server can be used directly with npx (recommended) or installed globally/lo
 
 ### Basic Configuration
 
-Add to your MCP client configuration.
-
-For JSON-based clients such as Claude Desktop and Cursor, use their `mcpServers` JSON format.
-For Codex, use `C:\Users\<username>\.codex\config.toml` and the `mcp_servers` TOML table format shown below.
+Add to your MCP client configuration.
+
+For JSON-based clients such as Claude Desktop and Cursor, use their `mcpServers` JSON format.
+For Codex, use `C:\Users\<username>\.codex\config.toml` and the `mcp_servers` TOML table format shown below.
 
 #### Option 1: Using npx (Recommended - No Installation Required)
 
@@ -135,22 +135,22 @@ For Codex, use `C:\Users\<username>\.codex\config.toml` and the `mcp_servers` TO
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "args": ["-y", "@n0zer0d4y/vulcan-file-ops"]
-    }
-  }
-}
-```
-
-**Codex (`config.toml`)**
-
-```toml
-[mcp_servers.vulcan_file_ops]
-command = "npx"
-args = ["-y", "@n0zer0d4y/vulcan-file-ops"]
-enabled = true
-startup_timeout_sec = 120.0
-```
+      "command": "npx",
+      "args": ["-y", "@n0zer0d4y/vulcan-file-ops"]
+    }
+  }
+}
+```
+
+**Codex (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "npx"
+args = ["-y", "@n0zer0d4y/vulcan-file-ops"]
+enabled = true
+startup_timeout_sec = 120.0
+```
 
 #### Option 2: Using Global Installation
 
@@ -180,7 +180,7 @@ After running `npm install @n0zer0d4y/vulcan-file-ops` in your project:
 }
 ```
 
-#### Option 4: Local Repository Execution (For Developers)
+#### Option 4: Local Repository Execution (For Developers)
 
 If you've cloned this repository and want to run from source:
 
@@ -191,39 +191,39 @@ npm install
 npm run build
 ```
 
-Then configure your MCP client:
-
-```json
-{
-  "mcpServers": {
-    "vulcan-file-ops": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
-        "--approved-folders",
-        "/path/to/your/allowed/directories"
-      ]
-    }
-  }
-}
-```
-
-**Codex (`config.toml`)**
-
-```toml
-[mcp_servers.vulcan_file_ops]
-command = "node"
-args = [
-  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
-  "--approved-folders",
-  'C:\path\to\your\allowed\directories'
-]
-cwd = 'C:\absolute\path\to\vulcan-file-ops'
-enabled = true
-startup_timeout_sec = 120.0
-```
-
-**Note:** For local repository execution, prefer `node dist/cli.js` with an absolute path. This works reliably in Codex and avoids PATH ambiguity.
+Then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
+        "--approved-folders",
+        "/path/to/your/allowed/directories"
+      ]
+    }
+  }
+}
+```
+
+**Codex (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "node"
+args = [
+  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
+  "--approved-folders",
+  'C:\path\to\your\allowed\directories'
+]
+cwd = 'C:\absolute\path\to\vulcan-file-ops'
+enabled = true
+startup_timeout_sec = 120.0
+```
+
+**Note:** For local repository execution, prefer `node dist/cli.js` with an absolute path. This works reliably in Codex and avoids PATH ambiguity.
 
 ### Advanced Configuration
 
@@ -237,12 +237,12 @@ Pre-configure specific directories for immediate access on server start:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@n0zer0d4y/vulcan-file-ops",
-        "--approved-folders",
-        "/Users/username/projects",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@n0zer0d4y/vulcan-file-ops",
+        "--approved-folders",
+        "/Users/username/projects",
         "/Users/username/documents"
       ]
     }
@@ -256,12 +256,12 @@ Pre-configure specific directories for immediate access on server start:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@n0zer0d4y/vulcan-file-ops",
-        "--approved-folders",
-        "C:/Users/username/projects",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@n0zer0d4y/vulcan-file-ops",
+        "--approved-folders",
+        "C:/Users/username/projects",
         "C:/Users/username/documents"
       ]
     }
@@ -269,7 +269,7 @@ Pre-configure specific directories for immediate access on server start:
 }
 ```
 
-**Alternative: Local Repository Execution**
+**Alternative: Local Repository Execution**
 
 For users running from a cloned repository (after `npm run build`):
 
@@ -277,32 +277,32 @@ For users running from a cloned repository (after `npm run build`):
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": [
-        "--approved-folders",
-        "/Users/username/projects",
-        "/Users/username/documents"
+      "command": "vulcan-file-ops",
+      "args": [
+        "--approved-folders",
+        "/Users/username/projects",
+        "/Users/username/documents"
       ]
     }
   }
 }
-```
-
-**Codex with Approved Folders (`config.toml`)**
-
-```toml
-[mcp_servers.vulcan_file_ops]
-command = "node"
-args = [
-  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
-  "--approved-folders",
-  'C:\Users\username\projects',
-  'C:\Users\username\documents'
-]
-cwd = 'C:\absolute\path\to\vulcan-file-ops'
-enabled = true
-startup_timeout_sec = 120.0
-```
+```
+
+**Codex with Approved Folders (`config.toml`)**
+
+```toml
+[mcp_servers.vulcan_file_ops]
+command = "node"
+args = [
+  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
+  "--approved-folders",
+  'C:\Users\username\projects',
+  'C:\Users\username\documents'
+]
+cwd = 'C:\absolute\path\to\vulcan-file-ops'
+enabled = true
+startup_timeout_sec = 120.0
+```
 
 **Path Format Note:**
 
@@ -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)