Repository navigation
Releases
WinHelm v1.4.4
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. /healthexample 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.4No configuration or migration steps.
Links
- npm: https://www.npmjs.com/package/winhelm-mcp
- Repository: https://github.com/incognitums/winhelm-mcp
- Changelog:
CHANGELOG.md
WinHelm v1.4.3
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 →
incognitumspackage.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.tsusesSERVER_VERSIONinstead 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.3No configuration or migration steps.
Verification
npm test— full suite green on the release candidatepackage.json,package-lock.json,manifest.json,server.jsonall report1.4.3- npm publish verified: metadata on the registry points at
incognitums/winhelm-mcp
Links
- npm: https://www.npmjs.com/package/winhelm-mcp
- Repository: https://github.com/incognitums/winhelm-mcp
- Changelog:
CHANGELOG.md
WinHelm v1.4.2
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 report1.4.2. - Published as official package
winhelm-mcp@1.4.2on the npm registry.
3. Setup Assistant Companion Asset
- Shipped
WinHelm-Setup-Assistant-v1.4.1.zipas 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
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, orWINHELM_FROZEN_CORE_ROOTenvironment 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.1in 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
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.0Then:
winhelm --helpThe 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
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 ofMCP_AUTH_TOKEN,WINHELM_AUTH_TOKEN,AUTH_TOKEN, andSECRETto 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
allowedDirectorieswhen no explicitcwdis supplied. - Command path checker verifies all absolute path tokens against
allowedDirectories. - Terminal security warning emitted immediately when CLI flags enable system execution.
- Validates effective working directory against
- 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/messageauthenticated via query token do not generate browser cookies or triggerSet-Cookieheaders.
- Enforced a 12-hour absolute maximum lifetime cap (
- 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.
- Applied
- 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.
- Added
- Repository Hygiene & Version Centralization:
- Untracked
winhelm.config.jsonand added priority loading forwinhelm.local.json. - Centralized server version reporting to
src/utils/version.tsdynamically sourced frompackage.json.
- Untracked
- 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 /Fprior to SIGKILL. - Restricted
/previewto files ≤ 5 MB to prevent memory exhaustion. - Explicitly blocked
Host: 0.0.0.0inisHostAllowed().
- Capped stdout and stderr at 1 MB per stream and limited task output buffers to 1 MB in
- 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
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):allowSystemExecutionis nowfalseby default.- Access to execute system runtime binaries located on drive
C:(such asC:\Windows\System32) is blocked by default unless explicitly allowed. - To enable system binaries, opt in via CLI
--system-exec, environment variableWINHELM_ALLOW_SYSTEM_EXEC=1, or set"allowSystemExecution": trueinwinhelm.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>orPOST /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.
- Browser login URLs and remote access utilize short-lived single-use exchange tokens (
- 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; Secureattributes with throttled refresh (>50% TTL elapsed) to prevent cookie churn. - Stale or invalid session cookies are immediately invalidated and purged (
Max-Age=0).
- Web Monitor Dashboard and Previewer issue an ephemeral session cookie (
- 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
corsOriginsis set to"*"alongsidecredentials: true, adhering to the W3C CORS specification.
- Dynamic Origin Reflection is used when
- Unicode Path Traversal Defense (NFKC):
- Added NFKC normalization to
isPathAllowed()before resolving paths, preventing traversal escapes via full-width Unicode characters (\uFF0E\uFF0E/).
- Added NFKC normalization to
- Request URL Log Sanitization:
- Automatically sanitizes query parameters (
?token=...,?exchange=...) inreq.originalUrlbefore passing requests to terminal and file loggers.
- Automatically sanitizes query parameters (
- Dedicated Append-Only JSONL Audit Logger:
- Introduces
logs/audit.logwith append-only structured JSONL logging, automatic 10MB file rotation, and 5-backup retention.
- Introduces
📚 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
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()forchrome-extension://(Chrome, Edge, Brave, Arc),moz-extension://(Firefox),safari-web-extension://(Safari), andvscode-webview://(VS Code / Cursor). Resolves HTTP 405 Method Not Allowed errors when connecting via browser extensions. - CORS
Access-Control-Expose-HeadersforMcp-Session-Id: Configured CORS middleware to explicitly exposeMcp-Session-Id,Mcp-Protocol-Version, andLast-Event-ID. Prevents browsers from hiding the session ID header from client-side JavaScript, resolving400 Bad Request: Server not initializederrors on subsequent requests. - Session ID Query Parameter Fallback: Added fallback parsing in
StreamableGatewayfor?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/10e.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-Originheader (callback(null, false)) instead of throwing an unhandledError, 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) inisHostAllowed(), 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) onGET /mcpand redirects to the Web Monitor Dashboard (/?token=...), eliminating confusing406 Not Acceptableerrors 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 ofallowedDirectories: []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 syntaxallowedDirectories: ["*"]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 forgedHostheaders are rejected with 403 Forbidden. Configurable viaallowedHostsin config orMCP_ALLOWED_HOSTSenvironment variable. - Unauthenticated Remote Proxy / Tunnel Gate: Enforced an immediate fail-closed 403 Forbidden gate when requests are proxied via
X-Forwarded-FororForwardedheaders while noauthTokenis configured, preventing accidental public access without authentication. - Strict Read-Only Mode Enforcement: Extended
isReadOnly()enforcement toterminal_runandterminal_task_startin terminal tools, and blocked state-mutating HTTP methods (POST,PUT,DELETE,PATCH) inhttp_request. - Fail-Closed on Corrupt Configuration: Changed
ConfigManager.loadConfigSync()andinit()to throw fatal errors upon JSON parsing syntax errors instead of silently falling back to defaults. - Markdown Code Block Language Tag Sanitization: Sanitized
codeBlockLangin PDF generator against regex/[^\w\-]/gand 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/previewand enforced globalX-Content-Type-Options: nosniffandX-Frame-Options: DENYon all HTTP responses. - Cookie Security Hardening: Enhanced
Set-CookiewithMax-Age=2592000(30 days),SameSite=Lax, and conditionalSecureflag when served over HTTPS. - Default Network Interface Hardening: Changed default HTTP binding host from
0.0.0.0to127.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
/previewand/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
allowedDirectoriespath confinement checks forsourcePathincopyFileOrDir,sourceDirincreateZip, andzipPathinextractZipto prevent exfiltration or copying of files outside allowed boundaries. - Dangerous Command Blocklist Enforcement (Option A): Integrated
DEFAULT_BLOCKED_PATTERNSregex blocklist inConfigManager.isCommandAllowed()blocking destructive system manipulation commands includingreg delete HKLM,diskpart,mimikatz,procdump,bcdedit,net user /add,takeown /f, andicacls /grant. - Symlink & Junction Traversal Guard: Integrated
fs.realpathSyncpath canonicalization inConfigManager.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()andsanitizeObject()to automatically mask quoted JSON credential fields ("authToken","password","x-api-key", etc.) and AWS access keys (AKIA...) with asterisks (***). Applied sanitization acrossLogger.toolStartandLogger.toolDoneto prevent secret leakage in console stdout and log streams. - Hardened
start.ps1& Host Safety Gate: Changed default$HostAddrparameter instart.ps1from0.0.0.0to127.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 Expresstrust proxyto"loopback"so rate limiting and request logging receive client's real IP viaX-Forwarded-Forthrough Tailscale Funnel and local tunnel reverse proxies. - Timing Attack Mitigation: Replaced standard string equality comparison for Bearer token and browser authentication with
crypto.timingSafeEqualwith 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
/previewendpoint from internal polling filter so document preview access is captured in terminal and file request logs. - Local Personal Config Isolation: Added
.gitignorepattern for*.local.jsonandwinhelm.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 withprofile: core, exampleallowedDirectories, andallowedHosts. - Browser Session Cookie Persistence: Gateway automatically issues a secure
Set-Cookie: authToken=...; Path=/; HttpOnly; SameSite=Laxheader 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 evictedmcp-session-idon/mcp. Configuredonsessioninitializedsession registration, placedtransport.onclosebeforeconnect()to preserve SDK teardown, and ensured uninitialized/rejected transports are immediately closed to prevent memory leaks. - NPM Package & Executable Readiness: Added
#!/usr/bin/env nodeshebang in CLI entrypoint for global npm/npx execution (winhelm), formal ESMexportsmap, standard package metadata (repository,homepage,bugs,keywords), and automatedprepublishOnlylifecycle validation (npm run build && npm test). - Runtime Engine Alignment: Standardized Node.js minimum requirement to
Node.js >= 20.0.0across 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--persistflag for opt-in disk persistence. - **Enhanced `start.p...
v1.1.1 - Tailscale CORS & Browser UX Fixes
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/10e.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-Originheader (callback(null, false)) instead of throwing an unhandledError, 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) inisHostAllowed(), 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) onGET /mcpand redirects to the Web Monitor Dashboard (/?token=...), eliminating confusing406 Not Acceptableerrors 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 ofallowedDirectories: []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 syntaxallowedDirectories: ["*"]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 forgedHostheaders are rejected with 403 Forbidden. Configurable viaallowedHostsin config orMCP_ALLOWED_HOSTSenvironment variable. - Unauthenticated Remote Proxy / Tunnel Gate: Enforced an immediate fail-closed 403 Forbidden gate when requests are proxied via
X-Forwarded-FororForwardedheaders while noauthTokenis configured, preventing accidental public access without authentication. - Strict Read-Only Mode Enforcement: Extended
isReadOnly()enforcement toterminal_runandterminal_task_startin terminal tools, and blocked state-mutating HTTP methods (POST,PUT,DELETE,PATCH) inhttp_request. - Fail-Closed on Corrupt Configuration: Changed
ConfigManager.loadConfigSync()andinit()to throw fatal errors upon JSON parsing syntax errors instead of silently falling back to defaults. - Markdown Code Block Language Tag Sanitization: Sanitized
codeBlockLangin PDF generator against regex/[^\w\-]/gand 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/previewand enforced globalX-Content-Type-Options: nosniffandX-Frame-Options: DENYon all HTTP responses. - Cookie Security Hardening: Enhanced
Set-CookiewithMax-Age=2592000(30 days),SameSite=Lax, and conditionalSecureflag when served over HTTPS. - Default Network Interface Hardening: Changed default HTTP binding host from
0.0.0.0to127.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
/previewand/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
allowedDirectoriespath confinement checks forsourcePathincopyFileOrDir,sourceDirincreateZip, andzipPathinextractZipto prevent exfiltration or copying of files outside allowed boundaries. - Dangerous Command Blocklist Enforcement (Option A): Integrated
DEFAULT_BLOCKED_PATTERNSregex blocklist inConfigManager.isCommandAllowed()blocking destructive system manipulation commands includingreg delete HKLM,diskpart,mimikatz,procdump,bcdedit,net user /add,takeown /f, andicacls /grant. - Symlink & Junction Traversal Guard: Integrated
fs.realpathSyncpath canonicalization inConfigManager.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()andsanitizeObject()to automatically mask quoted JSON credential fields ("authToken","password","x-api-key", etc.) and AWS access keys (AKIA...) with asterisks (***). Applied sanitization acrossLogger.toolStartandLogger.toolDoneto prevent secret leakage in console stdout and log streams. - Hardened
start.ps1& Host Safety Gate: Changed default$HostAddrparameter instart.ps1from0.0.0.0to127.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 Expresstrust proxyto"loopback"so rate limiting and request logging receive client's real IP viaX-Forwarded-Forthrough Tailscale Funnel and local tunnel reverse proxies. - Timing Attack Mitigation: Replaced standard string equality comparison for Bearer token and browser authentication with
crypto.timingSafeEqualwith 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
/previewendpoint from internal polling filter so document preview access is captured in terminal and file request logs. - Local Personal Config Isolation: Added
.gitignorepattern for*.local.jsonandwinhelm.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 withprofile: core, exampleallowedDirectories, andallowedHosts. - Browser Session Cookie Persistence: Gateway automatically issues a secure
Set-Cookie: authToken=...; Path=/; HttpOnly; SameSite=Laxheader 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 evictedmcp-session-idon/mcp. Configuredonsessioninitializedsession registration, placedtransport.onclosebeforeconnect()to preserve SDK teardown, and ensured uninitialized/rejected transports are immediately closed to prevent memory leaks. - NPM Package & Executable Readiness: Added
#!/usr/bin/env nodeshebang in CLI entrypoint for global npm/npx execution (winhelm), formal ESMexportsmap, standard package metadata (repository,homepage,bugs,keywords), and automatedprepublishOnlylifecycle validation (npm run build && npm test). - Runtime Engine Alignment: Standardized Node.js minimum requirement to
Node.js >= 20.0.0across 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--persistflag for opt-in disk persistence. - Enhanced
start.ps1Parameters: Added-Config,-Tools,-ReadOnly, and-NoPersistswitches for complete parity with CLI options. - PowerShell 7+ (
pwsh) Fast Fallback: Automatically detects and leveragespwsh.exefor reduced process spawn overhead while preserving 100% backward compatibility via cached fallback to Windows PowerShell (powershell.exe). Configurable viapreferPwshconfig option. - Build & Log Artifact Search Exclusion: Automatically excludes
dist/,logs/,build/,out/, and dot-folders (.serena/,.git/) fromfile_searchand recursive directory scans, with configurable override viasearchExcludeDirs. - 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 ...
WinHelm v1.1.0 — Security Hardening + npm Ready
🚨 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 viaMCP_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.realpathSyncto 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
winhelmvianpm install -g winhelm-mcpornpx 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 ofpwsh.exewith transparent fallback topowershell.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
--toolsmodifier - Security Model — In-depth trust boundaries, defense layers, and network protections
- Agent Examples — Production workflows for Claude Desktop, Cursor, ChatGPT, and AI agents