@linxin666/dsh-ssh 0.2.8 → 0.3.0

package/lib/index.js

@@ -2226,6 +2226,63 @@ var SshEngine = class {
 	}
 };
 //#endregion
+//#region src/http.ts
+/** Default body cap for readJsonBody: 64 KiB. */
+const DEFAULT_JSON_BODY_MAX_BYTES = 64 * 1024;
+/** Family-default JSON response headers; callers may append or override. */
+const JSON_HEADERS = {
+	"content-type": "application/json; charset=utf-8",
+	"referrer-policy": "no-referrer"
+};
+/**
+* Lenient bounded body reader: parse a request body as JSON, or null on an
+* empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+* Overflow destroys the request instead of draining the remainder (no drain
+* call, matching the current repo-wide behavior); callers must not keep
+* reading the request afterwards. With objectOnly, non-JSON-object payloads
+* also yield null.
+*/
+async function readJsonBody(req, opts = {}) {
+	const maxBytes = opts.maxBytes ?? DEFAULT_JSON_BODY_MAX_BYTES;
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of req) {
+		const buffer = chunk;
+		size += buffer.length;
+		if (size > maxBytes) {
+			req.destroy();
+			return null;
+		}
+		chunks.push(buffer);
+	}
+	const text = Buffer.concat(chunks).toString("utf8");
+	if (text === "") return null;
+	try {
+		const parsed = JSON.parse(text);
+		if (opts.objectOnly && !isJsonObject(parsed)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/** Whether a value is a JSON object: typeof object, not null, not an array. */
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Write one JSON response. Default headers are the family defaults
+* (content-type and referrer-policy); caller headers are appended or
+* override them.
+*/
+function writeJson(res, status, body, headers = {}) {
+	const payload = JSON.stringify(body);
+	res.writeHead(status, {
+		...JSON_HEADERS,
+		...headers
+	});
+	res.end(payload);
+}
+//#endregion
 //#region src/loopback.ts
 /** IPv4 127/8 predicate (four decimal octets, first == 127). */
 function isIPv4Loopback(v4) {
@@ -2294,8 +2351,6 @@ const SSH_API = {
 * these endpoints execute commands on remote servers, so LAN-exposed dsh web
 * deployments must not serve them.
 */
-/** Cap on JSON request bodies (host entries and exec payloads are small). */
-const MAX_JSON_BODY_BYTES = 64 * 1024;
 /** Cap on declared upload bodies (staged to disk before SFTP). */
 const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024;
 /**
@@ -2308,32 +2363,6 @@ const terminalWss = new WebSocketServer({ noServer: true });
 const BACKPRESSURE_HIGH_WATER = 1024 * 1024;
 /** …and resume once it drains below this. */
 const BACKPRESSURE_LOW_WATER = 512 * 1024;
-/** One JSON response. */
-function writeJson(res, status, body) {
-	const payload = JSON.stringify(body);
-	res.writeHead(status, {
-		"content-type": "application/json; charset=utf-8",
-		"referrer-policy": "no-referrer"
-	});
-	res.end(payload);
-}
-/** Read a JSON request body (undefined when too large or unparseable). */
-async function readJsonBody(req) {
-	const chunks = [];
-	let size = 0;
-	for await (const chunk of req) {
-		const buffer = chunk;
-		size += buffer.length;
-		if (size > MAX_JSON_BODY_BYTES) return void 0;
-		chunks.push(buffer);
-	}
-	try {
-		const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
-	} catch {
-		return;
-	}
-}
 /** URL query helper (first value, decoded). */
 function queryParam(url, name) {
 	const value = url.searchParams.get(name);
@@ -2382,7 +2411,7 @@ function makeRoutes(deps) {
 					}
 					if (method === "POST") {
 						const body = await readJsonBody(req);
-						if (body === void 0) {
+						if (body === null) {
 							writeJson(res, 400, { error: "invalid JSON body" });
 							return;
 						}
@@ -2405,7 +2434,7 @@ function makeRoutes(deps) {
 					}
 					if (method === "PATCH") {
 						const body = await readJsonBody(req);
-						if (body === void 0) {
+						if (body === null) {
 							writeJson(res, 400, { error: "invalid JSON body" });
 							return;
 						}
@@ -2982,7 +3011,7 @@ function sshListTool(engine) {
 function sshExecTool(engine) {
 	return defineTool({
 		name: "ssh_exec",
-		description: "Execute a command on a configured SSH host by alias. Prefer combining independent read-only queries into one command. Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.",
+		description: "Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command. Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3054,7 +3083,7 @@ function sshExecTool(engine) {
 function sshUploadTool(engine) {
 	return defineTool({
 		name: "ssh_upload",
-		description: "Upload a local file to a configured SSH host. The local path is on THIS machine (the dsh host). Triggers: upload file to server, deploy artifact, copy config to server.",
+		description: "Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload. Triggers: upload file to server, deploy artifact, copy config to server.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3064,12 +3093,12 @@ function sshUploadTool(engine) {
 			localPath: {
 				type: "string",
 				required: true,
-				description: "Absolute local file path on this machine."
+				description: "Absolute path of the source file on THIS machine (the dsh host) — not a path on the remote host."
 			},
 			remotePath: {
 				type: "string",
 				required: true,
-				description: "Destination path on the remote host (parent dirs are created)."
+				description: "Absolute destination path on the remote SSH host (parent dirs are created)."
 			}
 		},
 		output: {
@@ -3109,7 +3138,7 @@ function sshUploadTool(engine) {
 function sshDownloadTool(engine) {
 	return defineTool({
 		name: "ssh_download",
-		description: "Download a remote FILE from a configured SSH host to a local path on this machine. Directory download is not supported — download files individually. Triggers: download file from server, fetch remote log/artifact.",
+		description: "Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually. Triggers: download file from server, fetch remote log/artifact.",
 		parameters: {
 			alias: {
 				type: "string",
@@ -3119,12 +3148,12 @@ function sshDownloadTool(engine) {
 			remotePath: {
 				type: "string",
 				required: true,
-				description: "Remote file path."
+				description: "Absolute path of the source file on the remote SSH host."
 			},
 			localPath: {
 				type: "string",
 				required: true,
-				description: "Absolute destination path on this machine."
+				description: "Absolute destination path on THIS machine (the dsh host)."
 			}
 		},
 		output: {
@@ -3489,7 +3518,7 @@ const DEFAULT_ANNOUNCE = false;
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
+const SSH_GUIDANCE = "本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。";
 /**
 * Mount the SSH engine, routes, tools, and announcement.
 * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/lib/types/http.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
+ * family's route module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-ui-shared/host/http
+ */
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http';
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export declare function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown>;
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export declare function readJsonBody(req: IncomingMessage, opts?: {
+    maxBytes?: number;
+    objectOnly?: boolean;
+}): Promise<unknown | null>;
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export declare function asJsonObject(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown, headers?: OutgoingHttpHeaders): void;

package/lib/types/index.d.ts

@@ -38,7 +38,7 @@ export interface Config {
 }
 export declare const Config: z<Config>;
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 $DSH_HOME/dsh-ssh.json\uFF08\u9ED8\u8BA4 ~/.dsh\uFF09\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 $DSH_HOME/dsh-ssh.json\uFF08\u9ED8\u8BA4 ~/.dsh\uFF09\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801/ssh-agent \u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u8DEF\u5F84\u533A\u5206\uFF1A\u672C\u673A\uFF08dsh host\uFF09\u4E0A\u7684\u6587\u4EF6\u4E0E\u547D\u4EE4\u4E00\u5F8B\u7528\u672C\u5730\u5DE5\u5177\uFF08read / write / edit / bash\uFF09\uFF0Cssh_* \u5DE5\u5177\u53EA\u9488\u5BF9\u8FDC\u7A0B\u4E3B\u673A\u4E0A\u7684\u8DEF\u5F84\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 /**
  * Mount the SSH engine, routes, tools, and announcement.
  * @param ctx - host plugin context carrying webServer/tools/systemPrompt.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-ssh",
   "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/panel/SshPanel.tsx

@@ -55,12 +55,14 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
   }
 
   return (
-    <div className={css.panel}>
+    <div className={css.panel} data-dsh-plugin="ssh">
       <div className={css.panelHeader}>
+        {/* Shared hook: dsh-web-ui-all offsets center-view back controls beside the collapsed mobile sidebar. */}
         <button
           type="button"
           className={`${css.ghostButton} ${css.backButton}`}
           aria-label={tt('panel.backToConversation')}
+          data-dsh-center-view-back=""
           onClick={() => { controller.close() }}
         >
           <span aria-hidden="true">‹</span>
@@ -70,7 +72,7 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
       </div>
       <div className={css.tabBar} role="tablist" data-dsh-part="tab-bar">
         {TABS.map(tab => (
-          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
+          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
             {tab.label()}
           </button>
         ))}

package/src/client/panel/panel.module.css

@@ -66,12 +66,12 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
 }
 
 .entry:hover {
-  background: var(--dsw-specific-sidebar-nav-item-hover);
+  background: var(--dsw-alias-interactive-bg-hover);
   color: var(--dsw-alias-label-primary);
 }
 
 .entry[data-active] {
-  background: var(--dsw-specific-sidebar-nav-item-active);
+  background: var(--dsw-alias-interactive-bg-active);
   color: var(--dsw-alias-label-primary);
   font-weight: 600;
 }
@@ -100,9 +100,10 @@ html[data-dsh-ssh-active]:not([data-dsh-taskboard-active]) [class*='centerCol']
 [data-dsh-frame][data-sidebar-collapsed] .entry {
   justify-content: center;
   padding: 0;
-  width: 40px;
-  min-height: 40px;
-  margin-inline: auto;
+  width: 36px;
+  min-height: 36px;
+  margin: 0 auto 12px;
+  border-radius: 50%;
 }
 
 [data-dsh-frame][data-sidebar-collapsed] .entryLabel {

package/src/http.ts

@@ -0,0 +1,105 @@
+// Generated by scripts/sync-shared.mjs from shared/host/http.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
+ * family's route module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-ui-shared/host/http
+ */
+
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http'
+
+/** Default body cap for readJsonBody: 64 KiB. */
+const DEFAULT_JSON_BODY_MAX_BYTES = 64 * 1024
+
+/** Family-default JSON response headers; callers may append or override. */
+const JSON_HEADERS = {
+  'content-type': 'application/json; charset=utf-8',
+  'referrer-policy': 'no-referrer',
+} satisfies OutgoingHttpHeaders
+
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export async function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > maxBytes) throw new Error('body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export async function readJsonBody(
+  req: IncomingMessage,
+  opts: { maxBytes?: number; objectOnly?: boolean } = {},
+): Promise<unknown | null> {
+  const maxBytes = opts.maxBytes ?? DEFAULT_JSON_BODY_MAX_BYTES
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > maxBytes) {
+      req.destroy()
+      return null
+    }
+    chunks.push(buffer)
+  }
+  const text = Buffer.concat(chunks).toString('utf8')
+  if (text === '') return null
+  try {
+    const parsed: unknown = JSON.parse(text)
+    if (opts.objectOnly && !isJsonObject(parsed)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/** Whether a value is a JSON object: typeof object, not null, not an array. */
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export function asJsonObject(value: unknown): Record<string, unknown> | undefined {
+  return isJsonObject(value) ? value : undefined
+}
+
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export function writeJson(
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: OutgoingHttpHeaders = {},
+): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { ...JSON_HEADERS, ...headers })
+  res.end(payload)
+}

package/src/index.ts

@@ -64,7 +64,7 @@ const DEFAULT_ANNOUNCE = false
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 $DSH_HOME/dsh-ssh.json（默认 ~/.dsh）（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码/ssh-agent 认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。路径区分：本机（dsh host）上的文件与命令一律用本地工具（read / write / edit / bash），ssh_* 工具只针对远程主机上的路径。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
 
 /**
  * Mount the SSH engine, routes, tools, and announcement.

package/src/routes.ts

@@ -16,13 +16,11 @@ import { randomBytes } from 'node:crypto'
 import { WebSocket, WebSocketServer } from 'ws'
 import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { SshEngine, ShellSession } from './engine.ts'
+import { readJsonBody, writeJson } from './http.ts'
 import { isLoopbackRequest } from './loopback.ts'
 import { SSH_API, type HostPayload, type TerminalClientFrame, type TerminalServerFrame } from './protocol.ts'
 import type { HostStore } from './store.ts'
 
-/** Cap on JSON request bodies (host entries and exec payloads are small). */
-const MAX_JSON_BODY_BYTES = 64 * 1024
-
 /** Cap on declared upload bodies (staged to disk before SFTP). */
 const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024
 
@@ -39,31 +37,6 @@ const BACKPRESSURE_HIGH_WATER = 1024 * 1024
 /** …and resume once it drains below this. */
 const BACKPRESSURE_LOW_WATER = 512 * 1024
 
-/** One JSON response. */
-function writeJson(res: ServerResponse, status: number, body: unknown): void {
-  const payload = JSON.stringify(body)
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'referrer-policy': 'no-referrer' })
-  res.end(payload)
-}
-
-/** Read a JSON request body (undefined when too large or unparseable). */
-async function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown> | undefined> {
-  const chunks: Buffer[] = []
-  let size = 0
-  for await (const chunk of req) {
-    const buffer = chunk as Buffer
-    size += buffer.length
-    if (size > MAX_JSON_BODY_BYTES) return undefined
-    chunks.push(buffer)
-  }
-  try {
-    const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'))
-    return typeof parsed === 'object' && parsed !== null ? parsed as Record<string, unknown> : undefined
-  } catch {
-    return undefined
-  }
-}
-
 /** URL query helper (first value, decoded). */
 function queryParam(url: URL, name: string): string | undefined {
   const value = url.searchParams.get(name)
@@ -129,8 +102,8 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
           return
         }
         if (method === 'POST') {
-          const body = await readJsonBody(req)
-          if (body === undefined) {
+          const body = (await readJsonBody(req)) as Record<string, unknown> | null
+          if (body === null) {
             writeJson(res, 400, { error: 'invalid JSON body' })
             return
           }
@@ -152,8 +125,8 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
           return
         }
         if (method === 'PATCH') {
-          const body = await readJsonBody(req)
-          if (body === undefined) {
+          const body = (await readJsonBody(req)) as Record<string, unknown> | null
+          if (body === null) {
             writeJson(res, 400, { error: 'invalid JSON body' })
             return
           }
@@ -203,7 +176,7 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
       path: SSH_API.test,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
-        const body = await readJsonBody(req)
+        const body = (await readJsonBody(req)) as Record<string, unknown> | null
         const alias = typeof body?.alias === 'string' ? body.alias : ''
         if (alias === '') {
           writeJson(res, 400, { error: 'alias is required' })
@@ -221,7 +194,7 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
       path: SSH_API.exec,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
-        const body = await readJsonBody(req)
+        const body = (await readJsonBody(req)) as Record<string, unknown> | null
         const alias = typeof body?.alias === 'string' ? body.alias : ''
         const command = typeof body?.command === 'string' ? body.command : ''
         if (alias === '' || command === '') {
@@ -241,7 +214,7 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
       path: SSH_API.cluster,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
-        const body = await readJsonBody(req)
+        const body = (await readJsonBody(req)) as Record<string, unknown> | null
         const command = typeof body?.command === 'string' ? body.command : ''
         if (command === '') {
           writeJson(res, 400, { error: 'command is required' })
@@ -285,7 +258,7 @@ const maxUploadBytes = deps.maxUploadBytes ?? MAX_UPLOAD_BYTES
       path: SSH_API.tunnel,
       handler: async (req, res) => {
         if (!guard(req, res, 'POST')) return
-        const body = await readJsonBody(req)
+        const body = (await readJsonBody(req)) as Record<string, unknown> | null
         const action = typeof body?.action === 'string' ? body.action : ''
         if (action === 'list') {
           writeJson(res, 200, { tunnels: engine.listTunnels() })

package/src/tools.ts

@@ -109,7 +109,7 @@ export function sshListTool(engine: SshEngine) {
 export function sshExecTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_exec',
-    description: 'Execute a command on a configured SSH host by alias. Prefer combining independent read-only queries into one command. ' +
+    description: 'Execute a shell command on a REMOTE SSH host by alias; the command runs on the remote host, never on this machine. For commands on this machine, use the local bash tool. Prefer combining independent read-only queries into one command. ' +
       'Triggers: run command on server, deploy, check server/status, service control, view logs, any remote operation.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
@@ -154,12 +154,12 @@ export function sshExecTool(engine: SshEngine) {
 export function sshUploadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_upload',
-    description: 'Upload a local file to a configured SSH host. The local path is on THIS machine (the dsh host). ' +
+    description: 'Transfer a file FROM this machine (the dsh host) TO a remote SSH host. Use this only when the file must be copied to the remote host. Files that stay on this machine are handled with the local file tools (read / write / edit), not ssh_upload. ' +
       'Triggers: upload file to server, deploy artifact, copy config to server.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
-      localPath: { type: 'string', required: true, description: 'Absolute local file path on this machine.' },
-      remotePath: { type: 'string', required: true, description: 'Destination path on the remote host (parent dirs are created).' },
+      localPath: { type: 'string', required: true, description: 'Absolute path of the source file on THIS machine (the dsh host) — not a path on the remote host.' },
+      remotePath: { type: 'string', required: true, description: 'Absolute destination path on the remote SSH host (parent dirs are created).' },
     },
     output: {
       schema: {
@@ -191,12 +191,12 @@ export function sshUploadTool(engine: SshEngine) {
 export function sshDownloadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_download',
-    description: 'Download a remote FILE from a configured SSH host to a local path on this machine. Directory download is not supported — download files individually. ' +
+    description: 'Copy a remote FILE from a configured SSH host to this machine (the dsh host). Use this only when the source is on the remote host; files already on this machine are read with the local file tools (read / write / edit), not ssh_download. Directory download is not supported — download files individually. ' +
       'Triggers: download file from server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
-      remotePath: { type: 'string', required: true, description: 'Remote file path.' },
-      localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
+      remotePath: { type: 'string', required: true, description: 'Absolute path of the source file on the remote SSH host.' },
+      localPath: { type: 'string', required: true, description: 'Absolute destination path on THIS machine (the dsh host).' },
     },
     output: {
       schema: {