@imenam/mcp-gui-interface 1.0.12 → 1.0.13

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Matthieu Pesnot-Pin
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @imenam/mcp-gui-interface
 
-Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, and logging.
+Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging, and network exposure rules.
 
 This package encapsulates the boilerplate many MCP servers need when they run a companion GUI: spawning a child process safely, communicating over IPC, registering with the central HTTP proxy, and logging without polluting **stdout** (reserved for MCP JSON-RPC on the parent process).
 
@@ -279,12 +279,50 @@ logger.info("Server started");
 
 ---
 
+### Network exposure: `GUI_LISTEN_HOST` and the request guard
+
+A GUI worker must listen on the loopback interface only. Other machines reach it through the proxy or the gateway manager, which authenticate the user and relay to `localhost:<port>` / `127.0.0.1:<port>`.
+
+```typescript
+import { GUI_LISTEN_HOST, honoGuiGuard, expressGuiGuard } from "@imenam/mcp-gui-interface";
+
+// Hono
+app.use("*", honoGuiGuard());
+serve({ fetch: app.fetch, port, hostname: GUI_LISTEN_HOST });
+
+// Express — register the guard before any route or body parser
+app.use(expressGuiGuard());
+app.listen(port, GUI_LISTEN_HOST);
+```
+
+Never pass `"localhost"` as the listen host: depending on the system it resolves to `::1` or `127.0.0.1`. Never omit the host either: Node then listens on every interface.
+
+The guard refuses with a `403` JSON body `{ error }`:
+
+| Rule | Refused request | Protects against |
+|------|-----------------|------------------|
+| **Host** | a `Host` header other than `localhost`, `127.0.0.1` or `::1` | DNS rebinding: a hostile domain resolving to 127.0.0.1 |
+| **Cross-site modification** | a method other than GET/HEAD/OPTIONS with `Sec-Fetch-Site` other than `same-origin`/`none`; when that header is absent, an `Origin` whose hostname is neither this machine's (hostname, interface addresses, loopback), nor the proxy's, nor in `trustedOrigins` | CSRF: a web page submitting a form or a `fetch` to the GUI |
+
+Requests carrying neither `Sec-Fetch-Site` nor `Origin` (curl, scripts) pass the second rule. Reads are never refused on their origin: without CORS headers, the browser does not let another site read the responses. Do not add a CORS middleware to a GUI worker.
+
+**`GuiRequestGuardOptions`**
+
+| Property         | Type       | Default             | Description |
+|------------------|------------|---------------------|-------------|
+| `proxyUrl`       | `string`   | `process.env.PROXY_URL` | Its hostname is a trusted origin |
+| `trustedOrigins` | `string[]` | `[]`                | Other origins whose hostname is trusted, e.g. a gateway manager served over plain HTTP under a domain name |
+
+`checkGuiRequest(info, trustedOriginHostnames(options))` applies the same rules to any other server (for instance an `upgrade` handler).
+
+---
+
 ## Full-stack usage sketch
 
 Typical split:
 
 1. **Master:** `setupLogging`, optional `GuiLauncher` + `start()` when `PROXY_URL` (or your policy) allows.
-2. **GUI worker:** `setupLogging`, `ProxyClient.register`, bind HTTP server to returned port, `unregister` on shutdown.
+2. **GUI worker:** `setupLogging`, request guard, `ProxyClient.register`, bind HTTP server to returned port on `GUI_LISTEN_HOST`, `unregister` on shutdown.
 
 The master example in older docs that called `ProxyClient` in the same process as `GuiLauncher` is valid for simple layouts; **Hono-based** MCPs (e.g. MCP Documentor) often register the proxy **only** in the worker.
 
@@ -301,6 +339,9 @@ import type {
   ProxyConfig,
   Logger,
   SetupLoggingOptions,
+  GuiRequestGuardOptions,
+  GuiRequestInfo,
+  GuiRequestRejection,
 } from "@imenam/mcp-gui-interface";
 ```
 
@@ -311,6 +352,7 @@ import type {
 ```bash
 npm run build        # tsc → dist/
 npm run build:watch
+npm test             # build, then node --test test/*.test.mjs
 npm run release      # version patch, build, publish, push tags
 ```
 

package/dist/src/index.d.ts

@@ -2,5 +2,6 @@ export { GuiLauncher, reconnectGuiToolDefinition, type GuiLauncherOptions, } fro
 export { ProxyClient, type RegisterOptions, type RegisterResult } from "./proxy-client.js";
 export { APP_GROUP_ENV_VAR, APP_NAME_ENV_VARS, APP_PATH_ENV_VARS, APP_PATH_PREFIX_ENV_VAR, applyAppPathPrefix, normalizeAppPath, normalizeAppPathPrefix, resolveAppGroup, resolveAppName, resolveAppPath, resolveAppPathDetailed, type ResolvedAppPath, } from "./app-config.js";
 export { IpcHub, type IpcMessage } from "./ipc-hub.js";
+export { GUI_LISTEN_HOST, checkGuiRequest, expressGuiGuard, honoGuiGuard, hostnameOf, trustedOriginHostnames, type GuiRequestGuardOptions, type GuiRequestInfo, type GuiRequestRejection, } from "./request-guard.js";
 export { setupLogging, createLogger } from "./logger.js";
 export type { ProxyConfig, Logger, SetupLoggingOptions, GuiRuntimeStatus, ReconnectResult, McpToolResult, } from "./types.js";

package/dist/src/index.js

@@ -2,4 +2,5 @@ export { GuiLauncher, reconnectGuiToolDefinition, } from "./gui-launcher.js";
 export { ProxyClient } from "./proxy-client.js";
 export { APP_GROUP_ENV_VAR, APP_NAME_ENV_VARS, APP_PATH_ENV_VARS, APP_PATH_PREFIX_ENV_VAR, applyAppPathPrefix, normalizeAppPath, normalizeAppPathPrefix, resolveAppGroup, resolveAppName, resolveAppPath, resolveAppPathDetailed, } from "./app-config.js";
 export { IpcHub } from "./ipc-hub.js";
+export { GUI_LISTEN_HOST, checkGuiRequest, expressGuiGuard, honoGuiGuard, hostnameOf, trustedOriginHostnames, } from "./request-guard.js";
 export { setupLogging, createLogger } from "./logger.js";

package/dist/src/request-guard.d.ts

@@ -0,0 +1,52 @@
+/** Interface every GUI worker binds to. */
+export declare const GUI_LISTEN_HOST = "127.0.0.1";
+/** The request headers {@link checkGuiRequest} looks at. */
+export interface GuiRequestInfo {
+    method: string;
+    host: string | undefined;
+    origin: string | undefined;
+    secFetchSite: string | undefined;
+}
+/** Why a request is refused, with the HTTP status to answer. */
+export interface GuiRequestRejection {
+    status: 403;
+    error: string;
+}
+export interface GuiRequestGuardOptions {
+    /** Proxy the GUI registers with; its hostname is trusted as an origin. Defaults to `process.env.PROXY_URL`. */
+    proxyUrl?: string;
+    /** Additional origins (e.g. `https://mcp.example.com`) whose hostname is trusted. */
+    trustedOrigins?: string[];
+}
+/** Lower-cased hostname of a `Host` header or URL authority, without port or IPv6 brackets. */
+export declare function hostnameOf(authority: string | undefined): string | null;
+/**
+ * Hostnames an `Origin` may carry: loopback names, this machine's hostname and
+ * interface addresses, the proxy's hostname and those of `trustedOrigins`.
+ */
+export declare function trustedOriginHostnames(options?: GuiRequestGuardOptions): Set<string>;
+/** Returns why the request must be refused, or `null` when it is accepted. */
+export declare function checkGuiRequest(request: GuiRequestInfo, trustedHostnames: ReadonlySet<string>): GuiRequestRejection | null;
+/** Minimal shape of a Hono context used by {@link honoGuiGuard}. */
+interface HonoLikeContext {
+    req: {
+        method: string;
+        header(name: string): string | undefined;
+    };
+    json(body: unknown, status: 403): Response;
+}
+/** Hono middleware applying {@link checkGuiRequest}: `app.use("*", honoGuiGuard())`. */
+export declare function honoGuiGuard(options?: GuiRequestGuardOptions): (c: HonoLikeContext, next: () => Promise<void>) => Promise<Response | void>;
+/** Minimal shapes of the Express request and response used by {@link expressGuiGuard}. */
+interface ExpressLikeRequest {
+    method: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface ExpressLikeResponse {
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+/** Express middleware applying {@link checkGuiRequest}: `app.use(expressGuiGuard())`, before any route. */
+export declare function expressGuiGuard(options?: GuiRequestGuardOptions): (req: ExpressLikeRequest, res: ExpressLikeResponse, next: () => void) => void;
+export {};

package/dist/src/request-guard.js

@@ -0,0 +1,129 @@
+/**
+ * Network exposure rules for a GUI worker's HTTP server.
+ *
+ * A GUI worker listens on {@link GUI_LISTEN_HOST} only: other machines reach
+ * it through the proxy or the gateway manager, which both relay to
+ * `localhost:<port>` / `127.0.0.1:<port>` and rewrite the `Host` header
+ * accordingly. The browser's `Origin` and `Sec-Fetch-Site` headers go through
+ * unchanged.
+ *
+ * {@link checkGuiRequest} enforces two rules:
+ *
+ * 1. **Host** — every request must carry a loopback `Host` (`localhost`,
+ *    `127.0.0.1`, `::1`). A page served from a hostile domain that resolves to
+ *    127.0.0.1 (DNS rebinding) sends its own domain as `Host` and is refused.
+ * 2. **Cross-site modifications** — a request with a method other than GET,
+ *    HEAD or OPTIONS is refused when the browser says it comes from another
+ *    site: `Sec-Fetch-Site` other than `same-origin` / `none` when the header
+ *    is present, otherwise an `Origin` whose hostname is neither a name or
+ *    address of this machine, nor the proxy's, nor listed in
+ *    `trustedOrigins`. Requests without either header (curl, scripts) pass.
+ */
+import os from "node:os";
+/** Interface every GUI worker binds to. */
+export const GUI_LISTEN_HOST = "127.0.0.1";
+const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "::1"];
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const SAME_ORIGIN_FETCH_SITES = new Set(["same-origin", "none"]);
+/** Lower-cased hostname of a `Host` header or URL authority, without port or IPv6 brackets. */
+export function hostnameOf(authority) {
+    const value = authority?.trim();
+    if (!value)
+        return null;
+    try {
+        return new URL(`http://${value}`).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function originHostname(origin) {
+    try {
+        const url = new URL(origin);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return null;
+        return url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hostnames an `Origin` may carry: loopback names, this machine's hostname and
+ * interface addresses, the proxy's hostname and those of `trustedOrigins`.
+ */
+export function trustedOriginHostnames(options = {}) {
+    const names = new Set(LOOPBACK_HOSTNAMES);
+    names.add(os.hostname().toLowerCase());
+    for (const addresses of Object.values(os.networkInterfaces())) {
+        for (const address of addresses ?? [])
+            names.add(address.address.toLowerCase());
+    }
+    const proxyUrl = options.proxyUrl ?? process.env.PROXY_URL;
+    for (const origin of [proxyUrl, ...(options.trustedOrigins ?? [])]) {
+        const hostname = origin ? originHostname(origin) : null;
+        if (hostname)
+            names.add(hostname);
+    }
+    return names;
+}
+/** Returns why the request must be refused, or `null` when it is accepted. */
+export function checkGuiRequest(request, trustedHostnames) {
+    const host = hostnameOf(request.host);
+    if (!host || !LOOPBACK_HOSTNAMES.includes(host)) {
+        return {
+            status: 403,
+            error: `Host "${request.host ?? ""}" is not allowed: open the GUI through the proxy or http://localhost.`,
+        };
+    }
+    if (SAFE_METHODS.has(request.method.toUpperCase()))
+        return null;
+    const fetchSite = request.secFetchSite?.trim().toLowerCase();
+    if (fetchSite) {
+        return SAME_ORIGIN_FETCH_SITES.has(fetchSite)
+            ? null
+            : { status: 403, error: `Cross-site request refused (Sec-Fetch-Site: ${fetchSite}).` };
+    }
+    if (request.origin === undefined)
+        return null;
+    const originHost = originHostname(request.origin);
+    if (!originHost || !trustedHostnames.has(originHost)) {
+        return { status: 403, error: `Cross-site request refused (Origin: ${request.origin}).` };
+    }
+    return null;
+}
+/** Hono middleware applying {@link checkGuiRequest}: `app.use("*", honoGuiGuard())`. */
+export function honoGuiGuard(options = {}) {
+    const trusted = trustedOriginHostnames(options);
+    return async (c, next) => {
+        const rejection = checkGuiRequest({
+            method: c.req.method,
+            host: c.req.header("host"),
+            origin: c.req.header("origin"),
+            secFetchSite: c.req.header("sec-fetch-site"),
+        }, trusted);
+        if (rejection)
+            return c.json({ error: rejection.error }, rejection.status);
+        await next();
+    };
+}
+function singleHeader(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/** Express middleware applying {@link checkGuiRequest}: `app.use(expressGuiGuard())`, before any route. */
+export function expressGuiGuard(options = {}) {
+    const trusted = trustedOriginHostnames(options);
+    return (req, res, next) => {
+        const rejection = checkGuiRequest({
+            method: req.method,
+            host: singleHeader(req.headers.host),
+            origin: singleHeader(req.headers.origin),
+            secFetchSite: singleHeader(req.headers["sec-fetch-site"]),
+        }, trusted);
+        if (rejection) {
+            res.status(rejection.status).json({ error: rejection.error });
+            return;
+        }
+        next();
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@imenam/mcp-gui-interface",
-  "version": "1.0.12",
-  "description": "Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging",
+  "version": "1.0.13",
+  "description": "Shared library for MCP GUI lifecycle management — spawning, IPC, proxy registration, logging, request guard",
   "type": "module",
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
@@ -13,12 +13,14 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
-    "release": "npm version patch && npm run build && npm publish --access public && git push origin master --follow-tags"
+    "release": "npm version patch && npm run build && npm publish --access public && git push origin master --follow-tags",
+    "test": "npm run build && node --test test/*.test.mjs"
   },
   "keywords": [
     "mcp",