Skip to content

Releases

WinHelm v1.4.4

Choose a tag to compare

@incognitums incognitums released this 18 Nov 21:26

WinHelm v1.4.4 — Release Notes

Release date: 2026-11-19
Type: documentation patch published so the npm page shows the current README.

Why this release exists

npm renders the README from the published tarball, and metadata for a published version
cannot be edited afterwards. v1.4.3 was published before its README was updated, so the
npm page kept showing "Product Status: v1.4.2". v1.4.4 republishes the same code with
the corrected documentation.

Changed (docs only)

  • README now reports v1.4.4 as the current status/identity and links the v1.4.4
    release notes.
  • /health example shows "version": "1.4.4".
  • npm page now matches the repository README.

Unchanged

  • No source, tool, schema, gateway, or security change.
  • Canonical MCP surface remains 56 tools.

Upgrade

npm install -g winhelm-mcp@1.4.4

No configuration or migration steps.

Links

WinHelm v1.4.3

Choose a tag to compare

@incognitums incognitums released this 18 Nov 20:40

WinHelm v1.4.3 — Release Notes

Release date: 2026-11-19
Type: metadata and test-robustness patch. No tool, schema, or runtime behaviour changes.

Summary

v1.4.3 transfers project ownership metadata to the incognitums GitHub account and
removes an assumption in the integration tests that the runtime version is 1.4.2.
The canonical MCP surface stays at 56 tools.

Changed

  • Project metadata → incognitums
    • package.json (author, repository, bugs, homepage)
    • manifest.json, server.json, public/.well-known/security.txt
    • npm package page now points at github.com/incognitums/winhelm-mcp
  • Tests read the runtime version dynamically
    • test/integration/server.test.ts uses SERVER_VERSION instead of the hardcoded
      1.4.2, so future version bumps no longer break the suite.

Unchanged

  • 56 canonical tools, Schema-v2 governance, dynamic profiles
  • Approval UX, dashboard, gateway (/mcp, /sse), health endpoint shape
  • All security posture defaults (conservative ingress, Manual service, no dangerous mode)

Upgrade

npm install -g winhelm-mcp@1.4.3

No configuration or migration steps.

Verification

  • npm test — full suite green on the release candidate
  • package.json, package-lock.json, manifest.json, server.json all report 1.4.3
  • npm publish verified: metadata on the registry points at incognitums/winhelm-mcp

Links

WinHelm v1.4.2

Choose a tag to compare

@incognitums incognitums released this 05 Nov 05:07

WinHelm v1.4.2 — Release Notes

Status: OFFICIAL_RELEASE

WinHelm v1.4.2 is a maintenance and documentation sanitization patch following the v1.4.1 operational usability release. It synchronizes release identity across npm and GitHub, sanitizes public repository documentation, and packages the companion Setup Assistant asset for streamlined deployment.

Key Changes in v1.4.2

1. Repository & Documentation Sanitization

  • Removed internal sprint work orders, implementation contracts, draft plans, and raw local test traces from the public repository and distribution tarball.
  • All internal filesystem paths and developer-specific references have been cleansed.
  • Kept documentation focused on operational, architectural, reference, and security guides (ARCHITECTURE_V1_4.md, TOOLS.md, PROFILES.md, SECURITY.md, THREAT_MODEL.md, TROUBLESHOOTING.md, etc.).

2. Synchronized Version Identity

  • Package, manifest, and runtime identities are fully synchronized at 1.4.2.
  • Endpoints (/health) and version commands (winhelm --version) authoritatively report 1.4.2.
  • Published as official package winhelm-mcp@1.4.2 on the npm registry.

3. Setup Assistant Companion Asset

  • Shipped WinHelm-Setup-Assistant-v1.4.1.zip as an official companion asset attached to the GitHub release.
  • Provides a turnkey local workspace configuration and setup experience for Windows workstations.

4. Preserved Runtime & Security Capabilities

  • Retains all 56 canonical public tools with single source of truth registry validation.
  • Retains Dynamic Internal Ports capability with automatic OS port allocation and fixed-port backward compatibility.
  • Retains Native Approval UX with Windows toast notifications and live-state-authoritative installer integration.
  • Retains the refreshed Product Web Dashboard with real-time approval mirror and connection metrics.
  • Preserves all security invariants: Absolute Deny, Explicit Confirmation, Mandatory Confirmation, protected path isolation (~/.winhelm), and fail-closed security posture.

Release Metadata

  • npm Package: winhelm-mcp@1.4.2
  • Git Tag: v1.4.2
  • Tarball: winhelm-mcp-1.4.2.tgz
  • Canonical Tools Count: 56
  • Minimum Node.js Version: >=20.0.0

WinHelm v1.4.1

Choose a tag to compare

@incognitums incognitums released this 05 Nov 03:40

WinHelm v1.4.1 — Release Notes

Status: RELEASE_CANDIDATE__PUBLICATION_AND_PRODUCTION_CUTOVER_GATED

WinHelm v1.4.1 focuses on operational usability without weakening the v1.4 security floor. The accepted source candidate removes routine internal-port selection from clean/automatic topology, adds Windows-native approval activation, refreshes the Product Dashboard, and wires product status to authoritative runtime classifiers.

Dynamic Internal Ports

  • Clean/automatic topology can obtain internal listeners from the operating system without asking the user to select numeric ports.
  • Existing fixed deployments remain fixed unless explicitly migrated.
  • Public HTTPS identity remains stable at HTTPS/443 when the accepted R8 route is explicitly active.
  • Internal-port hints are not authority; active state is derived from verified live runtime identity.

Native Approval UX

  • Windows toast activation opens the approval flow without requiring routine terminal commands.
  • Approval activation tokens are transient and are not persisted in plaintext.
  • Exact live Registry/Shortcut state controls installer repair/update/uninstall authorization.
  • Persisted installer receipts are advisory metadata only and cannot authorize destructive restoration.
  • Foreign Registry/Shortcut state is preserved fail-closed.

Product Dashboard

  • The refreshed Dashboard presents factual Dynamic Port, Native Approval, and Setup Assistant state through authoritative adapters.
  • Fake/fallback port presentation was removed from the accepted integration path.
  • The standalone Setup Assistant companion remains unavailable; its launch action is disabled rather than pretending a companion exists.

Security and authority

  • Safe / Balanced / Power capability profiles remain separate from Manual / Smart / Trusted Approval Modes.
  • Approval Mode never expands capability.
  • Absolute Deny, Explicit Confirmation, Mandatory Confirmation, protected-path controls, OAuth/TLS boundaries, and secret redaction remain non-bypassable release floors.
  • Native Approval live-state authority prevents forged receipt history from redefining destructive ownership.

Production adoption

The accepted v1.4.1 source candidate is not the same thing as completed production cutover.

  • Initial production adoption remains Fixed-first.
  • Existing fixed production topology is not silently converted to Automatic.
  • Live active-backend marker mutation remains blocked until a separately qualified guarded-commit primitive protects expected-current authority through commit.
  • R7/R8/Funnel/OAuth state is not silently changed by Core adoption.

Compatibility

  • The canonical public tool count remains 56.
  • Schema-v2 governance remains compatible with the v1.4 profile/approval model.
  • Existing fixed port configurations remain supported.
  • D1 live mode/port 18791 remains outside active production scope unless separately re-adjudicated.

Known limitations / deferred items

  • Standalone Setup Assistant companion executable: unavailable/not shipped.
  • Setup Assistant frozen-consumption lane: consumes frozen Core runtime modules read-only via dynamic discovery (node_modules/winhelm-mcp, Program Files, or WINHELM_FROZEN_CORE_ROOT environment override); strictly fails closed on checksum mismatch.
  • Rich native tray/desktop lifecycle controls: deferred.
  • MCP Harbor: separate future control-plane/gateway product.
  • Marker guarded-commit primitive: required before live production cutover.

Release identity

  • Package/runtime version: 1.4.1.
  • Health/version surfaces derive from the package version and report 1.4.1 in the accepted candidate.
  • Historical v1.4.0 release notes and evidence remain historical and are intentionally not rewritten.

Publication status

No Git tag, npm publication, GitHub release, or live production cutover is implied by these notes. Those actions require their own final Owner authorization after the remaining gates close.

WinHelm v1.4.0

Choose a tag to compare

@incognitums incognitums released this 18 Oct 02:33

WinHelm v1.4.0

WinHelm v1.4.0 is the first stable release of the v1.4 line, focused on safer day-to-day Windows MCP operation, clearer capability boundaries, stronger approval controls, and a validated 56-tool public surface.

Highlights

  • 56 canonical public tools across local file, process, network, system, and governed execution workflows.
  • Safe / Balanced / Power capability profiles.
  • Manual / Smart / Trusted Approval Modes, separated from capability profiles.
  • Local-Control registry for coordinating local HTTP and stdio instances.
  • Hardened hosted/public MCP ingress with OAuth compatibility.
  • Validated client connectivity for ChatGPT, Notion, Claude Desktop, Cursor, and Gemini workflows.
  • A complete manual install / upgrade / rollback path in the core package.
  • Windows native boundary included in the npm package for governed file/process operations.

Security model

v1.4.0 preserves several non-bypassable safety boundaries:

  • Approval Mode does not expand capability.
  • Absolute deny remains stronger than approval policy.
  • Mandatory and explicit confirmation remain stronger than Approval Mode.
  • Protected-path and native-boundary checks remain fail-closed.
  • Public exposure is inactive by default and must be explicitly enabled.
  • Secret values and credential material are excluded from release documentation and package metadata.

Profiles and approvals

Safe

Read-only exploration with terminal execution unavailable.

Balanced

Recommended daily engineering profile. Local read/write work is available within configured authority, while higher-risk actions remain bounded or denied.

Power

Broader capability for trusted automation. Product presets still default to Smart Approval Mode, so higher-impact operations may still require approval.

Approval Modes:

  • Manual — permitted state-changing actions normally require confirmation.
  • Smart — low-risk bounded work can proceed automatically; higher-impact actions ask.
  • Trusted — routine permitted actions can proceed without routine prompts.

Client compatibility

The v1.4 release line includes qualified connectivity for:

  • Claude Desktop
  • Cursor
  • ChatGPT
  • Notion
  • Gemini Static OAuth

The real Gemini client flow completed OAuth authorization, connector discovery of all 56 actions, and an authenticated read-only system_info call during release qualification.

Install

From npm:

npm install --global winhelm-mcp@1.4.0

Then:

winhelm --help

The package also includes manual installation, migration, troubleshooting, and rollback documentation.

Operational defaults

  • Public ingress remains manual / opt-in and inactive by default.
  • D1 live mode is not part of the active v1.4.0 production scope.
  • Approval UX remains web/CLI-centric in v1.4.0.
  • Windows toast approval and additional desktop UX are planned for later releases.
  • WinHelm Setup Assistant is a separate optional companion and is not required to install or operate v1.4.0.
  • MCP Harbor is a separate future control-plane/gateway product.

Release integrity

Git tag:

v1.4.0

Release commit:

f0b1e0d0fc06d2760e0d7bd2e08fb88ee4f454a6

Exact npm artifact:

winhelm-mcp-1.4.0.tgz

SHA-256:

47397F23AF5892C1916D4DAC748EE09E59E2123BAFD285105EE12E56EF5FF4E1

The uploaded GitHub release asset is the same sealed package artifact verified against the npm registry publication.

Upgrade note

Users upgrading from v1.2.1 should review the migration guidance before applying Schema-v2 configuration changes. v1.4.0 does not silently increase authority during migration.


Full details are available in the repository README, CHANGELOG, SECURITY guidance, manual install guide, migration guide, and known-limitations documentation.

v1.2.1 - Security Hardening & Robustness

Choose a tag to compare

@incognitums incognitums released this 29 Sep 08:09

WinHelm v1.2.1: Security Hardening & Robustness

WinHelm v1.2.1 introduces comprehensive security hardening, injection defense, child process environment scrubbing, audit log protection, strict HTML encoding, and robustness caps.

🛡️ Security & Hardening (Tasks 1–10)

  • PowerShell Injection Defense (Unicode Smart Quotes): Escaped Unicode smart quotes (\u2018, \u2019, \u201A, \u201B), blocked null bytes (\0) and unescaped newlines. Engine parameters in filesystem and system tools are now passed via isolated environment variables ($env:WH_ARG_*).
  • Child Process Environment Scrubbing: Sanitized inherited environment variables in child processes (getCleanChildEnv()), preventing leakage of MCP_AUTH_TOKEN, WINHELM_AUTH_TOKEN, AUTH_TOKEN, and SECRET to subshells or child tools.
  • Audit Log & Sanitizer Hardening:
    • Hashed session IDs with SHA-256 (first 12 characters) in audit logs to prevent token persistence.
    • Hardened credential masking regexes for quoted tokens, Bearer headers, and query parameters (exchange=, winhelm_session=, session=).
    • Terminal logs enforce a 500-char cap on tool inputs and a 200-char cap on outputs/errors.
  • Fail-Closed Boundary Consistency (allowSystemExecution: false):
    • Validates effective working directory against allowedDirectories when no explicit cwd is supplied.
    • Command path checker verifies all absolute path tokens against allowedDirectories.
    • Terminal security warning emitted immediately when CLI flags enable system execution.
  • Session Absolute Lifetime & MCP Protocol Token Isolation:
    • Enforced a 12-hour absolute maximum lifetime cap (maxLifetimeMs) on ephemeral sessions in addition to the 15-minute sliding window.
    • Requests to /mcp, /sse, and /message authenticated via query token do not generate browser cookies or trigger Set-Cookie headers.
  • Dashboard HTML Encoding & Strict CSP:
    • Applied escapeHtml() across all dynamic monitor fields (log titles, details, statuses, drive names, GPU metadata).
    • Enforced strict Content-Security-Policy headers on / and /dashboard.
  • Startup Gate for Network Exposure:
    • Added validateNetworkExposure(): fails fast with exit code 1 if configured with a non-loopback host interface without an active authentication token.
  • Repository Hygiene & Version Centralization:
    • Untracked winhelm.config.json and added priority loading for winhelm.local.json.
    • Centralized server version reporting to src/utils/version.ts dynamically sourced from package.json.
  • Robustness Caps & Safe Process Cleanup:
    • Capped stdout and stderr at 1 MB per stream and limited task output buffers to 1 MB in TaskManager.
    • Implemented Windows process tree termination on timeout using taskkill /PID <pid> /T /F prior to SIGKILL.
    • Restricted /preview to files ≤ 5 MB to prevent memory exhaustion.
    • Explicitly blocked Host: 0.0.0.0 in isHostAllowed().
  • Documentation Accuracy & Complete Test Verification:
    • Full suite verification: 219/219 tests passing across 62 suites (0 failures).
    • Updated all security and architectural documentation (README.md, SECURITY.md, docs/SECURITY.md, docs/THREAT_MODEL.md, TERMS_OF_USE.md, CHANGELOG.md).

v1.2.0 - Comprehensive Security Hardening & Enterprise Controls

Choose a tag to compare

@incognitums incognitums released this 29 Sep 01:46

WinHelm v1.2.0 — Production-Grade Security Hardening & Enterprise Controls 🛡️

This release brings enterprise-grade security hardening to WinHelm MCP, implementing a fail-closed execution model, one-time exchange token architecture with replay attack defense, dynamic origin reflection for W3C CORS compliance, and extensive security documentation.


⚠️ Breaking Changes

  • Fail-Closed System Execution Confinement (allowSystemExecution: false):
    • allowSystemExecution is now false by default.
    • Access to execute system runtime binaries located on drive C: (such as C:\Windows\System32) is blocked by default unless explicitly allowed.
    • To enable system binaries, opt in via CLI --system-exec, environment variable WINHELM_ALLOW_SYSTEM_EXEC=1, or set "allowSystemExecution": true in winhelm.config.json.
    • A prominent security warning log is displayed on terminal startup whenever system execution is active.

🔒 Security & Architecture Enhancements

  • One-Time Exchange Token Architecture:
    • Browser login URLs and remote access utilize short-lived single-use exchange tokens (?exchange=<token> or POST /auth/exchange) with a strict 5-minute TTL.
    • Exchange tokens are invalidated and pruned immediately upon first use, permanently eliminating Replay Attacks from browser history, shoulder surfing, or proxies.
  • Ephemeral Sliding Session Cookies:
    • Web Monitor Dashboard and Previewer issue an ephemeral session cookie (winhelm_session) with a 15-minute sliding inactivity TTL.
    • Enforces SameSite=Strict; HttpOnly; Secure attributes with throttled refresh (>50% TTL elapsed) to prevent cookie churn.
    • Stale or invalid session cookies are immediately invalidated and purged (Max-Age=0).
  • Browser Address Bar Token Stripping (HTTP 302 Redirect):
    • Visiting the dashboard via URL token triggers an automatic HTTP 302 redirect that sets the session cookie and strips the token from the browser address bar and history.
  • W3C CORS Spec Compliance:
    • Dynamic Origin Reflection is used when corsOrigins is set to "*" alongside credentials: true, adhering to the W3C CORS specification.
  • Unicode Path Traversal Defense (NFKC):
    • Added NFKC normalization to isPathAllowed() before resolving paths, preventing traversal escapes via full-width Unicode characters (\uFF0E\uFF0E/).
  • Request URL Log Sanitization:
    • Automatically sanitizes query parameters (?token=..., ?exchange=...) in req.originalUrl before passing requests to terminal and file loggers.
  • Dedicated Append-Only JSONL Audit Logger:
    • Introduces logs/audit.log with append-only structured JSONL logging, automatic 10MB file rotation, and 5-backup retention.

📚 Governance, Documentation & Policies

  • STRIDE Threat Model (docs/THREAT_MODEL.md): Complete STRIDE analysis, Mermaid architecture diagrams, trust boundaries, and residual risk assessment.
  • Terms of Use (TERMS_OF_USE.md): Bilingual (Thai / English) Shared Responsibility Model and acceptable use policy.
  • Vulnerability Disclosure Policy (SECURITY.md): Coordinated vulnerability disclosure guidelines and response timeline.
  • Security Contact Metadata (public/.well-known/security.txt): RFC 9116 compliant security contact metadata.
  • GitHub Security Workflow (.github/workflows/security.yml): Continuous automated security scanning with CodeQL and npm audit.

🧪 Automated Testing

  • 154 / 154 automated tests passing across 36 suites (0 failures).
  • Includes 30-case dedicated Security Boundary unit test suite (test/unit/security-boundary.test.ts).
  • Clean npm audit: 0 vulnerabilities found.

📦 Artifacts

  • winhelm.exe: Portable standalone Windows executable (~80 MB with embedded Node.js SEA runtime). Requires zero installation or external dependencies.

v1.1.2 - Browser Extensions CORS & Mcp-Session-Id Fixes

Choose a tag to compare

@incognitums incognitums released this 28 Sep 14:15

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.


[1.1.2] - 2026-09-28

Fixed

  • Browser Extension & IDE Webview CORS Support: Added native whitelist support in isOriginAllowed() for chrome-extension:// (Chrome, Edge, Brave, Arc), moz-extension:// (Firefox), safari-web-extension:// (Safari), and vscode-webview:// (VS Code / Cursor). Resolves HTTP 405 Method Not Allowed errors when connecting via browser extensions.
  • CORS Access-Control-Expose-Headers for Mcp-Session-Id: Configured CORS middleware to explicitly expose Mcp-Session-Id, Mcp-Protocol-Version, and Last-Event-ID. Prevents browsers from hiding the session ID header from client-side JavaScript, resolving 400 Bad Request: Server not initialized errors on subsequent requests.
  • Session ID Query Parameter Fallback: Added fallback parsing in StreamableGateway for ?sessionId=... and ?mcp-session-id=... query parameters alongside standard headers with optional chaining support.

[1.1.1] - 2026-09-28

Fixed

  • Tailscale & Remote Origin CORS Support: Extended CORS origin validation (isOriginAllowed) to permit Tailscale CGNAT IP addresses (100.64.0.0/10 e.g. 100.78.131.83), MagicDNS (*.ts.net), and remote Web MCP AI clients (claude.ai, chatgpt.com).
  • Graceful CORS Error Handling: Changed origin rejection to omit the Access-Control-Allow-Origin header (callback(null, false)) instead of throwing an unhandled Error, preventing Express from dumping 500 error stack traces in terminal output on unrecognized origins.
  • Tailscale IP in Host Validation: Added automatic permission for the Tailscale CGNAT subnet (100.64.0.0/10) in isHostAllowed(), enabling seamless direct connection via Tailscale IP alongside MagicDNS domains.
  • Smart Browser Redirect for /mcp: Added automatic detection for human web browser visits (Accept: text/html) on GET /mcp and redirects to the Web Monitor Dashboard (/?token=...), eliminating confusing 406 Not Acceptable errors when URLs are pasted into a browser.

[1.1.0] - 2026-09-28

Breaking Changes

  • Fail-Closed by Default Filesystem Confinement (allowedDirectories): Changed the default security semantic of allowedDirectories: [] or empty/unconfigured. Previously, an empty array permitted full filesystem access ("fail-open"). It now strictly blocks all filesystem operations ("fail-closed") with a descriptive security error. To restore full-drive access, you must explicitly opt-in using wildcard syntax allowedDirectories: ["*"] or ["all"]. Existing configurations that relied on [] for open access must update to ["*"].

Security

  • Host Header Validation & DNS Rebinding Defense (allowedHosts): Added strict Host header validation middleware restricting incoming HTTP requests to configured hosts (default: localhost, 127.0.0.1, [::1], and *.ts.net). Requests with unrecognized or forged Host headers are rejected with 403 Forbidden. Configurable via allowedHosts in config or MCP_ALLOWED_HOSTS environment variable.
  • Unauthenticated Remote Proxy / Tunnel Gate: Enforced an immediate fail-closed 403 Forbidden gate when requests are proxied via X-Forwarded-For or Forwarded headers while no authToken is configured, preventing accidental public access without authentication.
  • Strict Read-Only Mode Enforcement: Extended isReadOnly() enforcement to terminal_run and terminal_task_start in terminal tools, and blocked state-mutating HTTP methods (POST, PUT, DELETE, PATCH) in http_request.
  • Fail-Closed on Corrupt Configuration: Changed ConfigManager.loadConfigSync() and init() to throw fatal errors upon JSON parsing syntax errors instead of silently falling back to defaults.
  • Markdown Code Block Language Tag Sanitization: Sanitized codeBlockLang in PDF generator against regex /[^\w\-]/g and escaped HTML to prevent markup and attribute injection.
  • Preview Content-Security-Policy & Global Security Headers: Added strict CSP (default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; frame-src data:; connect-src 'none'; form-action 'none'; frame-ancestors 'none';) to /preview and enforced global X-Content-Type-Options: nosniff and X-Frame-Options: DENY on all HTTP responses.
  • Cookie Security Hardening: Enhanced Set-Cookie with Max-Age=2592000 (30 days), SameSite=Lax, and conditional Secure flag when served over HTTPS.
  • Default Network Interface Hardening: Changed default HTTP binding host from 0.0.0.0 to 127.0.0.1 (loopback only) to prevent unintentional exposure to the local network or public internet. Added a prominent console warning when binding to non-loopback addresses without authentication.
  • Closed Auth Bypass for Dashboard & Preview: Enforced authentication on /preview and /api/monitor/* endpoints. Added support for token authentication via query parameter (?token=... or ?auth=...) and HTTP cookie fallback for browser dashboard and markdown previewer access.
  • Filesystem Source-Path Confinement: Added strict allowedDirectories path confinement checks for sourcePath in copyFileOrDir, sourceDir in createZip, and zipPath in extractZip to prevent exfiltration or copying of files outside allowed boundaries.
  • Dangerous Command Blocklist Enforcement (Option A): Integrated DEFAULT_BLOCKED_PATTERNS regex blocklist in ConfigManager.isCommandAllowed() blocking destructive system manipulation commands including reg delete HKLM, diskpart, mimikatz, procdump, bcdedit, net user /add, takeown /f, and icacls /grant.
  • Symlink & Junction Traversal Guard: Integrated fs.realpathSync path canonicalization in ConfigManager.isPathAllowed() to resolve symlinks and NTFS directory junctions before boundary evaluation.
  • CORS Hardening: Restricted CORS default origins to localhost / loopback interfaces (127.0.0.1, [::1], and active port origins) instead of wildcard *.
  • Console Request Log & Output Sanitization: Enhanced sanitizeText() and sanitizeObject() to automatically mask quoted JSON credential fields ("authToken", "password", "x-api-key", etc.) and AWS access keys (AKIA...) with asterisks (***). Applied sanitization across Logger.toolStart and Logger.toolDone to prevent secret leakage in console stdout and log streams.
  • Hardened start.ps1 & Host Safety Gate: Changed default $HostAddr parameter in start.ps1 from 0.0.0.0 to 127.0.0.1. Added a mandatory security validation gate that blocks execution with exit code 1 if a non-loopback interface (e.g. 0.0.0.0) is requested without an authentication token (via -Auth, environment variable, or config file).
  • Reverse Proxy Support (trust proxy: loopback): Configured Express trust proxy to "loopback" so rate limiting and request logging receive client's real IP via X-Forwarded-For through Tailscale Funnel and local tunnel reverse proxies.
  • Timing Attack Mitigation: Replaced standard string equality comparison for Bearer token and browser authentication with crypto.timingSafeEqual with buffer length validation (safeCompare) to eliminate timing side-channel attacks.
  • Markdown Link & XSS Sanitization: Hardened formatInline() across PDF generation and interactive file preview by sanitizing and neutralizing dangerous link schemes (javascript:, vbscript:, data:).
  • Request Logger Ingestion for Document Previews: Removed /preview endpoint from internal polling filter so document preview access is captured in terminal and file request logs.
  • Local Personal Config Isolation: Added .gitignore pattern for *.local.json and winhelm.local.json, allowing machines to configure full-drive access without risking accidental commits to public repositories.

Added

  • Production Configuration Template (winhelm.config.example.json): Added an out-of-the-box configuration template with profile: core, example allowedDirectories, and allowedHosts.
  • Browser Session Cookie Persistence: Gateway automatically issues a secure Set-Cookie: authToken=...; Path=/; HttpOnly; SameSite=Lax header upon validating a URL query token (?token=...), ensuring seamless persistent authentication on the Web Monitor Dashboard and Previewer across page reloads and link clicks.
  • Streamable HTTP Session 404 & Lifecycle Cleanup: Added strict HTTP 404 (Session not found, JSON-RPC code -32001) response for unknown or evicted mcp-session-id on /mcp. Configured onsessioninitialized session registration, placed transport.onclose before connect() to preserve SDK teardown, and ensured uninitialized/rejected transports are immediately closed to prevent memory leaks.
  • NPM Package & Executable Readiness: Added #!/usr/bin/env node shebang in CLI entrypoint for global npm/npx execution (winhelm), formal ESM exports map, standard package metadata (repository, homepage, bugs, keywords), and automated prepublishOnly lifecycle validation (npm run build && npm test).
  • Runtime Engine Alignment: Standardized Node.js minimum requirement to Node.js >= 20.0.0 across package configuration and documentation.
  • --config <path> Flag: Added ability to load configuration directly from any specified JSON path, bypassing default search candidates for multi-project isolation. Includes automatic UTF-8 BOM stripping.
  • Session Non-Persistence Mode: CLI overrides (--allowed-dirs, --auth, --profile, --tools, --read-only) now default to in-memory application without mutating configuration files on disk (persist = false). Added --persist flag for opt-in disk persistence.
  • **Enhanced `start.p...
Read more

v1.1.1 - Tailscale CORS & Browser UX Fixes

Choose a tag to compare

@incognitums incognitums released this 28 Sep 13:35

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.


[1.1.1] - 2026-09-28

Fixed

  • Tailscale & Remote Origin CORS Support: Extended CORS origin validation (isOriginAllowed) to permit Tailscale CGNAT IP addresses (100.64.0.0/10 e.g. 100.78.131.83), MagicDNS (*.ts.net), and remote Web MCP AI clients (claude.ai, chatgpt.com).
  • Graceful CORS Error Handling: Changed origin rejection to omit the Access-Control-Allow-Origin header (callback(null, false)) instead of throwing an unhandled Error, preventing Express from dumping 500 error stack traces in terminal output on unrecognized origins.
  • Tailscale IP in Host Validation: Added automatic permission for the Tailscale CGNAT subnet (100.64.0.0/10) in isHostAllowed(), enabling seamless direct connection via Tailscale IP alongside MagicDNS domains.
  • Smart Browser Redirect for /mcp: Added automatic detection for human web browser visits (Accept: text/html) on GET /mcp and redirects to the Web Monitor Dashboard (/?token=...), eliminating confusing 406 Not Acceptable errors when URLs are pasted into a browser.

[1.1.0] - 2026-09-28

Breaking Changes

  • Fail-Closed by Default Filesystem Confinement (allowedDirectories): Changed the default security semantic of allowedDirectories: [] or empty/unconfigured. Previously, an empty array permitted full filesystem access ("fail-open"). It now strictly blocks all filesystem operations ("fail-closed") with a descriptive security error. To restore full-drive access, you must explicitly opt-in using wildcard syntax allowedDirectories: ["*"] or ["all"]. Existing configurations that relied on [] for open access must update to ["*"].

Security

  • Host Header Validation & DNS Rebinding Defense (allowedHosts): Added strict Host header validation middleware restricting incoming HTTP requests to configured hosts (default: localhost, 127.0.0.1, [::1], and *.ts.net). Requests with unrecognized or forged Host headers are rejected with 403 Forbidden. Configurable via allowedHosts in config or MCP_ALLOWED_HOSTS environment variable.
  • Unauthenticated Remote Proxy / Tunnel Gate: Enforced an immediate fail-closed 403 Forbidden gate when requests are proxied via X-Forwarded-For or Forwarded headers while no authToken is configured, preventing accidental public access without authentication.
  • Strict Read-Only Mode Enforcement: Extended isReadOnly() enforcement to terminal_run and terminal_task_start in terminal tools, and blocked state-mutating HTTP methods (POST, PUT, DELETE, PATCH) in http_request.
  • Fail-Closed on Corrupt Configuration: Changed ConfigManager.loadConfigSync() and init() to throw fatal errors upon JSON parsing syntax errors instead of silently falling back to defaults.
  • Markdown Code Block Language Tag Sanitization: Sanitized codeBlockLang in PDF generator against regex /[^\w\-]/g and escaped HTML to prevent markup and attribute injection.
  • Preview Content-Security-Policy & Global Security Headers: Added strict CSP (default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; frame-src data:; connect-src 'none'; form-action 'none'; frame-ancestors 'none';) to /preview and enforced global X-Content-Type-Options: nosniff and X-Frame-Options: DENY on all HTTP responses.
  • Cookie Security Hardening: Enhanced Set-Cookie with Max-Age=2592000 (30 days), SameSite=Lax, and conditional Secure flag when served over HTTPS.
  • Default Network Interface Hardening: Changed default HTTP binding host from 0.0.0.0 to 127.0.0.1 (loopback only) to prevent unintentional exposure to the local network or public internet. Added a prominent console warning when binding to non-loopback addresses without authentication.
  • Closed Auth Bypass for Dashboard & Preview: Enforced authentication on /preview and /api/monitor/* endpoints. Added support for token authentication via query parameter (?token=... or ?auth=...) and HTTP cookie fallback for browser dashboard and markdown previewer access.
  • Filesystem Source-Path Confinement: Added strict allowedDirectories path confinement checks for sourcePath in copyFileOrDir, sourceDir in createZip, and zipPath in extractZip to prevent exfiltration or copying of files outside allowed boundaries.
  • Dangerous Command Blocklist Enforcement (Option A): Integrated DEFAULT_BLOCKED_PATTERNS regex blocklist in ConfigManager.isCommandAllowed() blocking destructive system manipulation commands including reg delete HKLM, diskpart, mimikatz, procdump, bcdedit, net user /add, takeown /f, and icacls /grant.
  • Symlink & Junction Traversal Guard: Integrated fs.realpathSync path canonicalization in ConfigManager.isPathAllowed() to resolve symlinks and NTFS directory junctions before boundary evaluation.
  • CORS Hardening: Restricted CORS default origins to localhost / loopback interfaces (127.0.0.1, [::1], and active port origins) instead of wildcard *.
  • Console Request Log & Output Sanitization: Enhanced sanitizeText() and sanitizeObject() to automatically mask quoted JSON credential fields ("authToken", "password", "x-api-key", etc.) and AWS access keys (AKIA...) with asterisks (***). Applied sanitization across Logger.toolStart and Logger.toolDone to prevent secret leakage in console stdout and log streams.
  • Hardened start.ps1 & Host Safety Gate: Changed default $HostAddr parameter in start.ps1 from 0.0.0.0 to 127.0.0.1. Added a mandatory security validation gate that blocks execution with exit code 1 if a non-loopback interface (e.g. 0.0.0.0) is requested without an authentication token (via -Auth, environment variable, or config file).
  • Reverse Proxy Support (trust proxy: loopback): Configured Express trust proxy to "loopback" so rate limiting and request logging receive client's real IP via X-Forwarded-For through Tailscale Funnel and local tunnel reverse proxies.
  • Timing Attack Mitigation: Replaced standard string equality comparison for Bearer token and browser authentication with crypto.timingSafeEqual with buffer length validation (safeCompare) to eliminate timing side-channel attacks.
  • Markdown Link & XSS Sanitization: Hardened formatInline() across PDF generation and interactive file preview by sanitizing and neutralizing dangerous link schemes (javascript:, vbscript:, data:).
  • Request Logger Ingestion for Document Previews: Removed /preview endpoint from internal polling filter so document preview access is captured in terminal and file request logs.
  • Local Personal Config Isolation: Added .gitignore pattern for *.local.json and winhelm.local.json, allowing machines to configure full-drive access without risking accidental commits to public repositories.

Added

  • Production Configuration Template (winhelm.config.example.json): Added an out-of-the-box configuration template with profile: core, example allowedDirectories, and allowedHosts.
  • Browser Session Cookie Persistence: Gateway automatically issues a secure Set-Cookie: authToken=...; Path=/; HttpOnly; SameSite=Lax header upon validating a URL query token (?token=...), ensuring seamless persistent authentication on the Web Monitor Dashboard and Previewer across page reloads and link clicks.
  • Streamable HTTP Session 404 & Lifecycle Cleanup: Added strict HTTP 404 (Session not found, JSON-RPC code -32001) response for unknown or evicted mcp-session-id on /mcp. Configured onsessioninitialized session registration, placed transport.onclose before connect() to preserve SDK teardown, and ensured uninitialized/rejected transports are immediately closed to prevent memory leaks.
  • NPM Package & Executable Readiness: Added #!/usr/bin/env node shebang in CLI entrypoint for global npm/npx execution (winhelm), formal ESM exports map, standard package metadata (repository, homepage, bugs, keywords), and automated prepublishOnly lifecycle validation (npm run build && npm test).
  • Runtime Engine Alignment: Standardized Node.js minimum requirement to Node.js >= 20.0.0 across package configuration and documentation.
  • --config <path> Flag: Added ability to load configuration directly from any specified JSON path, bypassing default search candidates for multi-project isolation. Includes automatic UTF-8 BOM stripping.
  • Session Non-Persistence Mode: CLI overrides (--allowed-dirs, --auth, --profile, --tools, --read-only) now default to in-memory application without mutating configuration files on disk (persist = false). Added --persist flag for opt-in disk persistence.
  • Enhanced start.ps1 Parameters: Added -Config, -Tools, -ReadOnly, and -NoPersist switches for complete parity with CLI options.
  • PowerShell 7+ (pwsh) Fast Fallback: Automatically detects and leverages pwsh.exe for reduced process spawn overhead while preserving 100% backward compatibility via cached fallback to Windows PowerShell (powershell.exe). Configurable via preferPwsh config option.
  • Build & Log Artifact Search Exclusion: Automatically excludes dist/, logs/, build/, out/, and dot-folders (.serena/, .git/) from file_search and recursive directory scans, with configurable override via searchExcludeDirs.
  • Gateway Session Lifecycle & LRU Eviction: Added idle session eviction (sessionIdleTimeoutMs, default 45m) and maximum concurrent session cap (maxConcurrentSessions, default 100) with least-recently-used (LRU) pruning in both Streamable HTTP and SSE gateways.

Changed

  • **NPM Distribution ...
Read more

WinHelm v1.1.0 — Security Hardening + npm Ready

Choose a tag to compare

@incognitums incognitums released this 28 Sep 07:50

🚨 Breaking Changes

  • Fail-Closed Filesystem: allowedDirectories: [] now blocks all filesystem access by default. To restore full-drive access, explicitly configure ["*"] or ["all"].

🔒 Security

  • Default Loopback Interface: Changed default host to 127.0.0.1 (loopback-only) — binding to non-loopback interfaces requires --auth.
  • DNS Rebinding Defense: Strict Host header validation middleware against whitelist (localhost, 127.0.0.1, [::1], *.ts.net), configurable via MCP_ALLOWED_HOSTS.
  • Remote Tunnel Gate: Fail-closed gate returning HTTP 403 Forbidden on unauthenticated reverse proxy/tunnel requests.
  • Strict Read-Only Mode: Enforcement extended to block terminal execution (terminal_run, terminal_task_start) and state-mutating HTTP methods (POST, PUT, DELETE, PATCH).
  • Timing-Safe Authentication: Bearer and dashboard token verification using crypto.timingSafeEqual.
  • Symlink & Junction Confinement: Path canonicalization using fs.realpathSync to prevent boundary traversal escapes.
  • Corrupt Config Fail-Closed: Immediate fatal error on corrupt config JSON, preventing silent fallback to insecure defaults.
  • XSS & Injection Protection: Content-Security-Policy on /preview, global security headers (nosniff, DENY), and sanitization for markdown code block language tags.
  • Automatic Secret Masking: Comprehensive redaction of Bearer tokens, API keys, JSON credential fields, and AWS access keys in console and file logs.

✨ Added

  • NPM Package Ready: Global executable CLI winhelm via npm install -g winhelm-mcp or npx winhelm-mcp.
  • --config <path> Flag: Multi-project isolated configuration support with automatic UTF-8 BOM stripping.
  • Session Non-Persistence: CLI runtime overrides default to in-memory application without mutating disk configuration.
  • Browser Session Cookie: Secure, persistent session cookie for seamless Web Monitor Dashboard and Markdown Preview access.
  • Streamable HTTP Session Lifecycle: Strict HTTP 404 on evicted/unknown session IDs, LRU pruning, and idle session eviction.
  • PowerShell 7+ (pwsh) Fast Fallback: Automatic detection and prioritization of pwsh.exe with transparent fallback to powershell.exe.
  • Production Config Template: Added out-of-the-box winhelm.config.example.json.

📊 Test Suite

  • 114 automated tests across 29 suites (100% passing, 0 failures)

📖 Documentation

  • Tools Reference — All 38 Windows-native tools
  • Tool Profiles — 5 tailored profiles + custom --tools modifier
  • Security Model — In-depth trust boundaries, defense layers, and network protections
  • Agent Examples — Production workflows for Claude Desktop, Cursor, ChatGPT, and AI agents