@zhangfengshun/dsh-remote-ssh 2.4.9 → 2.4.10

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.10] — 非 loopback 访问不再全线 403：信任判定改用宿主 webRuntime.trustedHosts（issue #12）
+### 修复
+- **信任判定与 `/api` 网关、better-sidebar 同源**（感谢 @Linhaojing 的验证矩阵与自我更正后的方案）：此前 `isTrusted()` 硬编码 loopback 白名单（`localhost` / `127.0.0.1` / `::1` / `0.0.0.0`），从局域网（例如经配对设备或反向代理访问）打开 GUI 时，本插件的 **5 类路由全部 403** —— `/remote-ssh/api/*` 全部 RPC、6 个被拦截的 `fs.*`、`git.*`、文件上传、`/sidebar/file`，也就是文件树 / 读写 / 搜索 / 重命名 / 删除 / git / 上传全线失效，插件几乎等于没装。而同一 Host 下 DSH 官方路由正常，说明是本插件单方面比宿主更严。
+  - 现在改为读宿主官方运行时能力 **`ctx.webRuntime.trustedHosts`**（启动时采样的局域网 IP 字面量 + `--trusted-host` 指定的 authority）——与 `/api` 网关的 fence 及 better-sidebar 的 `src/trust-fence.ts` 完全一致（后者是 `@deepseek-ai/dsh-client-connection` 的 `api-request-trust.ts` 的拷贝，上游未导出这些 helper，故按同样方式复刻并在注释中标注来源）；
+  - **按请求实时读取** `trustedHosts`：用户改动信任列表无需重启插件；
+  - **软注入 `webRuntime`**（`ctx.inject(["webRuntime"])` 而非硬 `inject`）：万一宿主将来改名/移除该服务，插件仍能挂载，只是远程访问退回 loopback-only，行为与 2.4.10 之前一致——**零回归**；
+  - 安全性不降低：`sec-fetch-site: cross-site` 与新增的 **Origin 围栏**（带 Origin 时必须与本请求 hostname 一致；`Origin: null` 拒绝）都在，Host 白名单依旧存在，只是信任源从硬编码换成宿主权威列表；用户未配置信任列表时 `trustedHosts` 只含 loopback，行为与之前完全相同。
+- **403 文案不再误导**：此前无论何种拒绝原因都回 `missing x-requested-with header`，把排查方向带偏（提问者一开始就在查客户端是否漏带头）。现在按原因区分：缺头 → `missing x-requested-with header`（错误码仍为 `csrf`，保持兼容）、Host 不可信 → 明确提示 `untrusted host: … start DSH with --trusted-host <host[:port]> …`、跨站 → `cross-site request refused`、Origin 不符 → `origin does not match the request host`；`/sidebar/file` 的纯文本 403 也带准确原因。
+
+### 测试
+- 新增 `tests/trust-fence.test.mjs`（**61 条断言**）：loopback 判定（`localhost` / `[::1]` / `127.x.x.x` 整段 / 越界段拒绝 / `0.0.0.0` 历史放行）、authority 端口语义（条目带端口精确匹配、不带端口按主机名、无效条目跳过）、**逐条复现 issue #12 的验证矩阵**（`127.0.0.1:3080` ✅ / `localhost:3080` ✅ / 局域网 IP 无信任列表 ❌ / 局域网 IP + `trustedHosts` ✅）、cross-site 与 Origin 围栏（含 Edge 151 的「Origin 缺端口」特例与 `Origin: null` 拒绝）、文案区分（Host 被拒不再报缺头、并给出 `--trusted-host` 指引）、以及**组合行为**（提取真实 `requestTrust` + 桩 `trustedHosts`：可信局域网 + 缺头 → 报 `header`；信任列表被替换后立即生效）与接线断言（5 处调用点、软注入、实时读取、错误码兼容）。
+
 ## [2.4.9] — 「添加工作区」目录选择器支持新建目录（issue #11）
 ### 新增
 - **「添加工作区」弹窗的目录选择器新增「新建目录」**（感谢 @Linhaojing 的定位与接线建议）：此前本地 / 远程两个 tab 都只有「打开 / 上级 / 选择此目录」，要把**尚不存在**的目录加为工作区（例如远端起新项目 `~/lhj/new-project`）必须先跳出 DSH 用别的终端 `mkdir`。现在底部操作区多一个「📁 新建目录」按钮：点开输入行 → 填名字（回车即提交）→ 在当前 `path` 下创建 → **自动进入新目录**，紧接着点「选择此目录」即可成为工作区，全程不离开 DSH（对齐 VSCode「新建文件夹」的交互预期）。

package/README.md

@@ -46,7 +46,7 @@
 **一条命令安装**（无需 token、API Key 或额外配置）：
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.9
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.10
 ```
 
 安装后**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
@@ -202,6 +202,7 @@ dsh plugin --profile <name> remove @zhangfengshun/dsh-remote-ssh
 | `@` 补全只搜到镜像里那几个文件 | 2.4.7 起已修复：远程工作区会话的 `@` 补全改列远端文件（索引缓存 60s + 900ms 查询预算）；若仍只有镜像文件，确认 2.4.7 已装入并重启 DSH |
 | 大仓里 `@` 搜不到真实文件（如根目录 `AGENTS.md`、`src/**`） | 2.4.8 起已修复：此前排除目录发生在截断之后，`node_modules/` 这类目录会吃光索引配额；现在排除由远端 `grep`/`-prune` 在截断前完成，并会在索引达上限时打 warn 提示 |
 | 想加的远程目录还不存在，「添加工作区」里没法创建 | 2.4.9 起「目录选择器」底部有「📁 新建目录」（本地 / 远程 tab 均有）：输入名字即可就地创建并自动进入 |
+| 从局域网 / 另一台设备访问时插件文件能力全部报 403 | 2.4.10 起已修复：信任判定改用宿主 `ctx.webRuntime.trustedHosts`（与 `/api` 网关同源）。把访问地址加进 DSH 信任列表即可：启动时加 `--trusted-host <host[:port]>`（或经配对设备访问）；未配置时行为与之前一致（仅本机 loopback） |
 | 安装时提示 `minimumReleaseAge` 或「No matching version」（刚发布） | npm 供应链新鲜度策略，等 1–5 分钟后重试即可 |
 | 命令卡住不返回 | 默认 120s 超时后自动丢弃会话；长时任务用 `timeoutMs: 0`，随时可用 `remote_ssh_kill` 强杀 |
 | 大文件读取被截断 | 单文件读取上限 4MB、下载池化路径约 6.29MB（更大自动回落一次性连接）；用 `remote_ssh_exec` + `head`/`tail` 分段处理 |

package/README_EN.md

@@ -46,7 +46,7 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 **One command** (no token, API key or extra configuration needed):
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.9
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.10
 ```
 
 **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
@@ -202,6 +202,7 @@ The plugin never patches DSH sources or injects into the profile dependency tree
 | `@` completion only finds the few files in the mirror | Fixed in 2.4.7: in a remote-workspace session `@` now lists remote files (60s index cache + 900ms query budget); if only mirror files show up, make sure 2.4.7 is installed and DSH restarted |
 | In a large repo `@` cannot find real files (e.g. root `AGENTS.md`, `src/**`) | Fixed in 2.4.8: exclusion used to run *after* truncation, so a `node_modules/` tree could exhaust the index quota; exclusion now happens remotely (`grep`/`-prune`) before truncation, and hitting the cap logs a warning |
 | The remote directory you want does not exist yet and "Add Workspace" cannot create it | Fixed in 2.4.9: the directory picker has a "📁 New folder" button (both tabs) — type a name to create it in place and enter it automatically |
+| Accessing from the LAN / another device makes every file capability return 403 | Fixed in 2.4.10: the trust fence now reads the host's `ctx.webRuntime.trustedHosts` (same source as the `/api` gateway). Add the address to the DSH trust list — start with `--trusted-host <host[:port]>`, or access through your paired remote-access setup; with nothing configured the behaviour is unchanged (loopback only) |
 | Install fails with `minimumReleaseAge` or "No matching version" right after a release | npm supply-chain freshness policy — retry after 1–5 minutes |
 | A command hangs forever | The 120s timeout discards the pooled session automatically; use `timeoutMs: 0` for long jobs and `remote_ssh_kill` at any time |
 | Large files are truncated | 4MB per read, ≈6.29MB on the pooled download path (larger files fall back to a one-shot connection); use `remote_ssh_exec` with `head`/`tail` to page through |

package/lib/index.js

@@ -1003,19 +1003,90 @@ function normExec(r) {
 // HTTP 工具
 // ---------------------------------------------------------------------------
 
-function isTrusted(req, requireRequestedWith) {
-  const secFetchSite = req.headers["sec-fetch-site"];
-  if (secFetchSite === "cross-site") return false;
+// ---------------------------------------------------------------------------
+// 浏览器信任判定（DNS-rebinding / 跨站防线，**不是**认证）
+//
+// 与 /api 网关、better-sidebar 的 fence 同源：Host 头为 loopback，或命中宿主
+// ctx.webRuntime.trustedHosts（启动时采样的局域网 IP 字面量 + `--trusted-host`）。
+// 实现逐条对照 @deepseek-ai/dsh-client-connection 的 api-request-trust.ts
+// （better-sidebar 的 src/trust-fence.ts 是同一份拷贝，BSD-3-Clause —— 上游未导出这些
+// helper，故按同样方式在此复刻），差异只有：本插件额外要求 x-requested-with（PR #4 的
+// CSRF 加固），且把拒绝原因回传给调用方以便给出准确文案（issue #12：此前无论何种原因都
+// 报 "missing x-requested-with header"，把排查方向带偏）。
+// ---------------------------------------------------------------------------
+
+/** Host 头 authority 的规范化 URL；不可解析时返回 undefined。 */
+function parseAuthority(authority) {
+  try {
+    return new URL("http://" + String(authority));
+  } catch (e) {
+    return undefined;
+  }
+}
+
+/** hostname 是否指向本机 loopback（localhost / [::1] / 127.x.x.x）。
+ *  额外放行 0.0.0.0：它是本插件历史行为，且浏览器实际不会把它当目的地址发送。 */
+function isLoopbackHostname(hostname) {
+  if (hostname === "localhost" || hostname === "[::1]" || hostname === "0.0.0.0") return true;
+  const parts = String(hostname).split(".");
+  return parts.length === 4
+    && parts[0] === "127"
+    && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+
+/** authority 的规范形式：写了端口则 hostname:port，否则仅 hostname。 */
+function canonicalAuthority(entry, entryUrl) {
+  const port = entryUrl.port !== "" ? entryUrl.port : new URL("https://" + String(entry)).port;
+  return port === "" ? entryUrl.hostname : entryUrl.hostname + ":" + port;
+}
+
+/** 请求 authority 是否命中 trustedHosts（条目带端口则精确比对 host，否则只比 hostname）。 */
+function isTrustedAuthority(hostUrl, trustedHosts) {
+  return (trustedHosts || []).some((entry) => {
+    const entryUrl = parseAuthority(entry);
+    if (entryUrl === undefined) return false;
+    return canonicalAuthority(entry, entryUrl) === entryUrl.hostname
+      ? entryUrl.hostname === hostUrl.hostname
+      : entryUrl.host === hostUrl.host;
+  });
+}
+
+/** 本插件额外要求的非简单头（PR #4 的 CSRF 加固）。 */
+function hasRequestedWithHeader(req) {
+  return String(req.headers["x-requested-with"] || "").trim() === "XMLHttpRequest";
+}
+
+/** 判定一次请求是否可信：返回 "ok" 或具体拒绝原因（供调用方给出准确文案）。 */
+function trustVerdict(req, trustedHosts) {
   const host = req.headers["host"];
-  if (!host) return false;
-  const hostname = String(host).split(":")[0].replace(/^\[/, "").replace(/\]$/, "");
-  if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "0.0.0.0") {
-    // CSRF 加固（PR #4 的服务端半边）：/remote-ssh/api/* 仅由本插件客户端调用，
-    // 其请求必带 x-requested-with；跨站 no-cors POST 无法携带非简单头，预检也会被拒。
-    if (requireRequestedWith && String(req.headers["x-requested-with"] || "").trim() !== "XMLHttpRequest") return false;
-    return true;
+  if (!host) return "no-host";
+  const hostUrl = parseAuthority(host);
+  if (hostUrl === undefined) return "bad-host";
+  if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return "bad-host";
+  if (req.headers["sec-fetch-site"] === "cross-site") return "cross-site";
+  // Origin 围栏：浏览器带 Origin 时必须与本请求 hostname 一致（比较 hostname 而非 host ——
+  // 部分 Chromium（Edge 151）对非默认端口的 loopback 页面会把 Origin 序列化成不带端口）。
+  // 无 Origin 视为通过（Host 围栏已限定 authority）；字面量 "null"（沙箱 iframe / file:）拒绝。
+  const origin = req.headers["origin"];
+  if (origin === undefined) return "ok";
+  try {
+    return new URL(origin).hostname === hostUrl.hostname ? "ok" : "bad-origin";
+  } catch (e) {
+    return "bad-origin";
+  }
+}
+
+/** 拒绝原因 → 面向用户/模型的文案（issue #12：区分「缺头」与「Host 不可信」）。 */
+function trustErrorMessage(reason) {
+  switch (reason) {
+    case "header": return "missing x-requested-with header";
+    case "cross-site": return "cross-site request refused";
+    case "bad-origin": return "origin does not match the request host";
+    case "no-host": return "missing Host header";
+    default:
+      return "untrusted host: this deployment only serves loopback or hosts trusted by the DSH web runtime "
+        + "(start DSH with --trusted-host <host[:port]>, or expose it through your remote-access setup)";
   }
-  return false;
 }
 
 async function readJsonBody(req) {
@@ -1285,6 +1356,38 @@ function apply(ctx, config) {
   const terminals = new Map();
   let nextTerminalId = 1;
 
+  // ---- 宿主信任源（issue #12）----
+  // ctx.webRuntime.trustedHosts 是 DSH 官方运行时能力：启动时采样的局域网 IP 字面量
+  // 加 `--trusted-host` 指定的 authority，`/api` 网关的 fence 正以它为准。
+  // 按请求实时读取（服务值可被替换，无需重启插件）；服务缺失时保持 loopback-only，
+  // 行为与 2.4.9 完全一致 —— 因此用软注入（ctx.inject）而非硬 inject：万一将来宿主
+  // 改名/移除该服务，插件仍能挂载，只是远程访问退回本机可用。
+  let webRuntimeFace = null;
+  ctx.inject(["webRuntime"], (sctx) => {
+    try { webRuntimeFace = (sctx && sctx.webRuntime) || (sctx && typeof sctx.get === "function" ? sctx.get("webRuntime") : null) || null; } catch (e) { webRuntimeFace = null; }
+  });
+  function trustedHostsNow() {
+    try {
+      const list = webRuntimeFace && webRuntimeFace.trustedHosts;
+      return Array.isArray(list) ? list : [];
+    } catch (e) {
+      return [];
+    }
+  }
+
+  /** 一次请求的信任判定：返回 "ok" 或拒绝原因（"header" / "bad-host" / …）。 */
+  function requestTrust(req, requireRequestedWith) {
+    const verdict = trustVerdict(req, trustedHostsNow());
+    if (verdict !== "ok") return verdict;
+    if (requireRequestedWith && !hasRequestedWithHeader(req)) return "header";
+    return "ok";
+  }
+
+  /** 统一的 403 输出（带准确原因，避免把 Host 不可信误报成缺头）。 */
+  function denyRequest(res, reason) {
+    writeJson(res, 403, { ok: false, error: { code: reason === "header" ? "csrf" : "forbidden", message: trustErrorMessage(reason) } });
+  }
+
   // ---- 持久 SSH 会话池（连接复用，避免每次操作都做完整 SSH 握手）----
   const sessions = new Map(); // profileKey -> CommandSession
   const SESSION_IDLE_MS = 10 * 60 * 1000;
@@ -1757,7 +1860,9 @@ function apply(ctx, config) {
     handler: async (req, res) => {
       // CSRF 加固：/remote-ssh/api/* 仅由本插件客户端调用，强制校验其必带的
       // x-requested-with 头（跨站攻击者无法在 no-cors POST 中携带非简单头）。
-      if (!isTrusted(req, true)) { writeJson(res, 403, { ok: false, error: { code: "csrf", message: "missing x-requested-with header" } }); return; }
+      // 信任判定走宿主 webRuntime.trustedHosts（issue #12），失败时回传具体原因。
+      const apiTrust = requestTrust(req, true);
+      if (apiTrust !== "ok") { denyRequest(res, apiTrust); return; }
       if (req.method !== "POST") { writeError(res, new Error("method not allowed"), 405); return; }
       const pathname = new URL(req.url || "/", "http://dsh.internal").pathname;
       if (!pathname.startsWith(API_BASE)) { writeError(res, new Error("not-found"), 404); return; }
@@ -2412,7 +2517,8 @@ function apply(ctx, config) {
   // webServer prefix 匹配要求 pathname 以 prefix+"/" 开头，但 fs.tree 用的是点分隔符，
   // 所以无法用 prefix 拦截，必须用 exact。
   async function interceptFsHandler(req, res, method) {
-    if (!isTrusted(req)) { writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } }); return; }
+    const fsTrust = requestTrust(req, false);
+    if (fsTrust !== "ok") { denyRequest(res, fsTrust); return; }
     if (req.method !== "POST") { writeJson(res, 405, { ok: false, error: { code: "method-error", message: "method not allowed" } }); return; }
     let payload;
     try { payload = await readJsonBody(req); }
@@ -2667,7 +2773,8 @@ function apply(ctx, config) {
   }
 
   async function interceptGitHandler(req, res, method) {
-    if (!isTrusted(req)) { writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } }); return; }
+    const gitTrust = requestTrust(req, false);
+    if (gitTrust !== "ok") { denyRequest(res, gitTrust); return; }
     if (req.method !== "POST") { writeJson(res, 405, { ok: false, error: { code: "method-error", message: "method not allowed" } }); return; }
     let payload;
     try { payload = await readJsonBody(req); }
@@ -2849,7 +2956,8 @@ function apply(ctx, config) {
   }
 
   async function handleRemoteUpload(req, res) {
-    if (!isTrusted(req)) { writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } }); return; }
+    const upTrust = requestTrust(req, false);
+    if (upTrust !== "ok") { denyRequest(res, upTrust); return; }
     if (req.method !== "POST") { writeJson(res, 405, { ok: false, error: { code: "method-error", message: "method not allowed" } }); return; }
     try {
       const url = new URL(req.url || "/", "http://dsh.internal");
@@ -2930,7 +3038,8 @@ function apply(ctx, config) {
   }
 
   async function handleSidebarFile(req, res) {
-    if (!isTrusted(req)) { res.writeHead(403); res.end("forbidden"); return; }
+    const fileTrust = requestTrust(req, false);
+    if (fileTrust !== "ok") { res.writeHead(403, { "content-type": "text/plain; charset=utf-8" }); res.end(trustErrorMessage(fileTrust)); return; }
     if (req.method !== "GET") { res.writeHead(405); res.end(); return; }
     try {
       const url = new URL(req.url || "/", "http://dsh.internal");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.4.9",
+  "version": "2.4.10",
   "description": "DSH web plugin: VSCode Remote-SSH-like remote development (SSH to supercomputers/servers, remote workspace, file explorer, integrated terminal), integrated with dsh-better-sidebar and DSH settings.",
   "keywords": [
     "dsh",