dsh-app-updater 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.3.1] — 2026-11-01
+
+### 安全
+
+- **「仅凭回环地址放行」改为默认拒绝**（插件市场 dshopen.org 对 1.3.0 的复核意见）：
+  1.3.0 接入 `connection` 准入后仍留了一条退回路径 —— 宿主没有 `connection` 服务，或请求
+  不带任何连接凭据且来自回环地址时，直接按「本机信任」放行。在没有准入服务的旧宿主上，
+  任何本机进程（以及能向回环发起请求的页面）都能借此调用 `/update`、`/settings` 等安装接口，
+  等于绕过认证。1.3.1 起这条路径**默认关闭**：
+  - 宿主有 `connection`：一律以 `admit()` 的结果为准，`401` / `403` / `409` 原样返回
+    （响应头 `X-DSH-Admission: denied`）。只有「401 + 回环 + 无凭据 + 用户显式开启兼容模式」
+    这一种例外，且必须在下面第 2 条的前提下才成立。
+  - 宿主没有 `connection`：**默认 403**，不再自动相信回环地址。
+- **兼容模式必须由用户显式开启**（保留给确实跑在旧宿主上的用户）：插件配置
+  `allowLegacyLoopback: true`（`cordis.patch.yml` 覆盖同名条目）或环境变量
+  `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`，两者默认都没有。开启后：
+  - 放行的请求带 `X-DSH-Admission: loopback-legacy-optin` 与 `X-DSH-Admission-Warning`；
+  - `state.json` / `health.json` 新增 `admission` 字段（`mode` / `service` /
+    `allowLegacyLoopback` / `warning`），复核时不必读代码就能确认当前路径；
+  - 设置页顶部显示红色警示条，日志写一条 `warn`。
+- **准入拒绝统一返回 JSON**：`401`/`403`/`409` 带 `{ ok:false, error, admission:"denied" }`，
+  不再用纯文本，排障时能直接看出是被准入挡掉的。
+
+### 测试
+
+- `test/unit.mjs`：准入用例从 6 项扩到 25 项，覆盖兼容模式开关（配置 / 环境变量 / 缺省关闭）、
+  无 `connection` 服务默认拒绝、显式开启后放行、非回环仍拒绝、`409`、带凭据未认证不放行等。
+- 新增 `test/deny.mjs`：起真实 HTTP 服务，验证无 `connection` 且未开兼容模式时**每一条路由**
+  都是 `403 + X-DSH-Admission: denied`；再验证显式开启后放行并标注 opt-in 响应头。
+- `test/render.mjs`：新增兼容模式警示条 4 项（开启显示、样式、文案、默认不显示）。
+- 自测命令更新为 `node test/unit.mjs && node test/render.mjs && node test/deny.mjs`。
+
 ## [1.3.0] — 2026-10-31
 
 ### 修复

package/CONTRACT.md

@@ -41,10 +41,14 @@ dsh-app-updater/
 
 全部 `kind: "exact"`，前缀 `/dsh-app-updater/`。每个请求先过 **connection 准入**：
 `ctx.connection.admit(req)`（DSH 的 Host/Origin 信任校验 + 浏览器会话 / API 认证，
-宿主自己的 `/api` 路由用的同一套），被拒即返回 `401`（未认证）/ `403`（不可信来源）；
-写操作再要求 `confirm: true`。
-宿主没有 `connection` 服务、或请求不带任何连接凭据且来自回环地址时，退回旧的「回环」检查，
-并在响应头标注 `X-DSH-Admission: loopback-legacy`（`lib/index.js` 的 `admissionGate`）。
+宿主自己的 `/api` 路由用的同一套），被拒即返回 `401`（未认证）/ `403`（不可信来源）/
+`409`（连接被占用），响应头带 `X-DSH-Admission: denied`；写操作再要求 `confirm: true`。
+
+**默认拒绝**（1.3.1 起）：宿主没有 `connection` 服务时不再「仅凭回环地址放行」，而是 `403`。
+只有用户显式开启兼容模式（插件配置 `allowLegacyLoopback: true` 或环境变量
+`DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`）时，回环请求才放行，并带
+`X-DSH-Admission: loopback-legacy-optin` 与 `X-DSH-Admission-Warning`（见 `lib/index.js` 的
+`admissionGate` / `resolveLegacyLoopbackOptIn`）。
 
 ### GET /dsh-app-updater/state.json
 
@@ -62,7 +66,9 @@ dsh-app-updater/
   "update": { "running": false, "total": 0, "done": 0, "current": null, "error": null },
   "apps": { "scannedAt": 0, "stats": { "total": 0, "upgradable": 0, "unsupported": 0 }, "items": [], "engine": "winget" },
   "log": [ { "at": 0, "level": "info|warn|error|success", "text": "..." } ],
-  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true }
+  "settings": { "includeStoreApps": true, "includeRegistryOnly": true, "downloadDir": "", "keepInstallers": true, "hashFallbackUpgrade": true, "dryRun": false, "matchSystemArch": true, "autoElevate": true },
+  // 准入现状，供界面与复核确认当前走哪条路径（默认 "deny" 不会出现在能读到响应的地方）
+  "admission": { "mode": "connection|connection+loopback-legacy|loopback-legacy-optin|deny", "service": true, "allowLegacyLoopback": false, "warning": null }
 }
 ```
 

package/README.en.md

@@ -110,8 +110,25 @@ curl -X POST -H "Content-Type: application/json" \
 
 ## Safety boundaries
 
-- **Every write requires loopback + explicit confirmation**: `scan` / `update` / `cancel` /
-  `settings` / `open-downloads` accept only requests from loopback with `confirm:true`.
+- **Every route is deny-by-default**: each request first goes through `ctx.connection.admit(request)`
+  — DSH's Host/Origin fence plus browser-session / API authentication, the same gate the host uses for
+  its own `/api` routes. Rejected requests get `401` / `403` / `409` with `X-DSH-Admission: denied`.
+- **Legacy loopback mode is off by default** (since 1.3.1): when the host has no `connection`
+  service, requests are no longer trusted just because they come from loopback — they get `403`.
+  If you really need it on an old host, opt in explicitly, either via plugin config:
+
+  ```yaml
+  - id: dsh-app-updater
+    config:
+      allowLegacyLoopback: true
+  ```
+
+  or by exporting `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1` before starting DSH. Once enabled, allowed
+  requests carry `X-DSH-Admission: loopback-legacy-optin` and `X-DSH-Admission-Warning`, the
+  `admission` field in `state.json` / `health.json` reports `mode: "loopback-legacy-optin"`, the
+  settings page shows a red banner, and a `warn` line is written to the log.
+- **Every write still requires explicit confirmation**: `scan` / `update` / `cancel` /
+  `settings` / `open-downloads` require `confirm:true`.
 - **No guessed silent switches**: the publisher's declared `Silent` switches are preferred;
   generic defaults are used only when a manifest is unavailable.
 - **Elevation only for installs, and on demand**: install commands that need administrator rights

package/README.md

@@ -113,14 +113,32 @@ curl -X POST -H "Content-Type: application/json" \
 `downloadDir` 会被校验：必须留空（用默认目录）或是绝对路径（`D:\Apps`）／UNC 路径（`\\server\share`），
 否则返回 `400` 并在面板里显示红字提示，不会把安装包写到意料之外的位置。
 
+> 这些路由**默认拒绝**：请求必须通过宿主的 `connection` 准入（浏览器里就是带上 DSH 页面的会话
+> Cookie），或在**没有 `connection` 服务的旧宿主**上由你显式开启兼容模式（见「安全边界」）。
+> 仅凭「来自 127.0.0.1」不再放行 —— 1.3.1 已把这条路径改成默认拒绝。
+
 ---
 
 ## 安全边界
 
-- **接入宿主 connection 准入**：每个请求先过 `ctx.connection.admit(request)` —— DSH 用来做
+- **路由默认拒绝**：每个请求先过 `ctx.connection.admit(request)` —— DSH 用来做
   Host/Origin 信任校验与浏览器会话 / API 认证的那套边界（宿主自己的 `/api` 路由用的就是它），
-  未通过的请求直接得到 `401`/`403`。宿主没有 `connection` 服务、或请求不带任何连接凭据且来自
-  回环地址时，退回旧的「回环」规则，并在响应头标注 `X-DSH-Admission: loopback-legacy`。
+  未通过的请求直接得到 `401` / `403` / `409`，响应头带 `X-DSH-Admission: denied`。
+- **兼容模式默认关闭**（1.3.1 起）：宿主没有 `connection` 服务时**不再**「仅凭回环地址放行」，
+  一律 `403`。旧宿主上确实需要时，必须由你**显式**开启，二选一：
+  - 插件配置（`cordis.patch.yml` 里覆盖同名条目）：
+
+    ```yaml
+    - id: dsh-app-updater
+      config:
+        allowLegacyLoopback: true
+    ```
+
+  - 或启动 DSH 前设置环境变量 `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`。
+
+  开启后：放行的回环请求带 `X-DSH-Admission: loopback-legacy-optin` 与
+  `X-DSH-Admission-Warning`，`state.json` / `health.json` 的 `admission` 字段会标明
+  `mode: "loopback-legacy-optin"`，设置页顶部也会出现红色提示条；日志里记一条 `warn`。
 - **写操作还要显式确认**：`scan` / `update` / `cancel` / `settings` / `open-downloads` 必须带 `confirm:true`。
 - **不猜测静默参数**：优先用发布方在清单里声明的 `Silent` 参数；清单缺失时才按安装包类型用保守的默认开关。
 - **需要管理员时自动提权**：机器级安装包（MSI、写入 `Program Files`）交给

package/lib/client.js

@@ -200,6 +200,8 @@ window.__ModuleLoader__.load({
 
       /* 演练模式警示条 */
       ".appupd-banner{display:flex;align-items:center;gap:8px;padding:6px 10px;border-radius:8px;border:1px solid rgba(251,191,36,.5);background:rgba(251,191,36,.12);color:#fbbf24;font-size:12px;}",
+      /* 兼容模式（仅回环放行）警示条：默认关闭，开启时用红色提醒 */
+      ".appupd-banner-warn{border-color:rgba(239,68,68,.55);background:rgba(239,68,68,.12);color:#f87171;}",
 
       /* 插件设置面板 */
       ".appupd-panel{border:1px solid var(--dsw-alias-border-l1,#4b5563);border-radius:8px;overflow:hidden;}",
@@ -927,6 +929,21 @@ window.__ModuleLoader__.load({
           )
         : null;
 
+      /* 兼容模式：只有用户显式开启（插件配置 / 环境变量）才会出现，默认不显示 */
+      const admission = (state && state.admission) || null;
+      const legacyOn = Boolean(admission && admission.allowLegacyLoopback);
+      const legacyBanner = legacyOn
+        ? h(
+            "div",
+            { className: "appupd-banner appupd-banner-warn", role: "alert" },
+            h(
+              "span",
+              null,
+              "兼容模式已开启：没有连接凭据的本机回环请求会被放行（旧宿主没有 connection 准入时才会用到）。非必要请关闭，见 README 的「安全」一节。"
+            )
+          )
+        : null;
+
       const switchEl = (key) => {
         const on = Boolean(settings[key]);
         return h("button", {
@@ -1195,6 +1212,9 @@ window.__ModuleLoader__.load({
         /* 3. 演练模式提示 */
         dryRunBanner,
 
+        /* 3b. 兼容模式（仅回环放行）提示：默认不出现 */
+        legacyBanner,
+
         /* 4. 进度 */
         progress,
 

package/lib/index.js

@@ -2,7 +2,8 @@
  * dsh-app-updater 宿主半身。
  *
  * 职责：暴露 HTTP 路由给设置页 UI，串行调度「扫描」与「更新」两条后台任务，
- * 把进度写进持久化状态。所有写操作都要求 loopback 来源 + confirm:true。
+ * 把进度写进持久化状态。所有路由默认拒绝：先过宿主 connection 准入；写操作另需
+ * confirm:true。仅在用户显式开启兼容模式时，才按「回环地址」放行（默认关闭）。
  *
  * 设计上不依赖宿主内部服务（不用 llm / tools / agent），只依赖 webServer，
  * 因此在没有 Web 的 composition 里它会安静地不挂载任何路由。
@@ -86,46 +87,110 @@ export function hasConnectionCredentials(req) {
 }
 
 /**
- * connection 准入（宿主信任边界）。
+ * 兼容模式开关：只允许在用户**显式开启**时按「回环地址」放行。
+ *
+ * 1.3.0 在 `connection` 不可用（或没有凭据可核验）时会直接按回环放行，旧宿主上
+ * 等于绕过了认证就能调用安装接口 —— 市场复核要求这条路径改为默认拒绝。
+ * 因此 1.3.1 起默认关闭，只有下面两种显式动作之一才恢复（并会在响应头、状态接口
+ * 与日志里标注，方便复核）：
+ *   - 插件配置 `allowLegacyLoopback: true`（cordis patch 的 `config`）
+ *   - 环境变量 `DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK=1`
+ */
+export const LEGACY_LOOPBACK_ENV = "DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK";
+
+function truthyFlag(value) {
+  if (value === true || value === 1) return true;
+  if (typeof value !== "string") return false;
+  return /^(1|true|yes|on)$/i.test(value.trim());
+}
+
+/** 解析兼容模式开关：插件配置优先，其次环境变量；默认（两者都没有）为 false。 */
+export function resolveLegacyLoopbackOptIn(config, env = process.env) {
+  if (config && truthyFlag(config.allowLegacyLoopback)) return true;
+  return truthyFlag((env || {})[LEGACY_LOOPBACK_ENV]);
+}
+
+/** 兼容模式放行时打标记，便于复核与排障：正常准入不会出现这两个头。 */
+function markLegacyAdmission(res) {
+  if (typeof res.setHeader !== "function") return;
+  res.setHeader("X-DSH-Admission", "loopback-legacy-optin");
+  res.setHeader("X-DSH-Admission-Warning", "legacy-loopback-compatibility-enabled");
+}
+
+/** 统一写出拒绝响应，并标明是「被拒绝」而不是「未经过闸门」。 */
+function denyAdmission(res, status, error) {
+  if (typeof res.setHeader === "function") res.setHeader("X-DSH-Admission", "denied");
+  json(res, status, { ok: false, error, admission: "denied" });
+}
+
+/**
+ * connection 准入（宿主信任边界）。**默认拒绝**。
  *
  * DSH 的 `connection` 服务负责插件 HTTP 路由的信任校验：`admit(request)` 先做
  * Host/Origin 校验，再做浏览器会话 / API 认证，返回本次调用对应的 Peer，或用
- * `401`（未认证）/`403`（不可信来源）拒绝 —— 宿主自己的 `/api` 路由用的就是它。
+ * `401`（未认证）/`403`（不可信来源）/`409`（连接已被占用）拒绝 —— 宿主自己的
+ * `/api` 路由用的就是它。
  *
- * 退回策略（只有一条，且完全不涉及凭据）：宿主没有 `connection` 服务，
- * 或者请求**没有携带任何连接凭据**、来自回环地址时，按旧的「回环」规则放行，
- * 并在响应头标注 `X-DSH-Admission: loopback-legacy`。
- * 带凭据的请求一律以 admission 的结果为准；非回环请求一律拒绝。
+ * 规则（按顺序）：
+ * 1. 宿主有 `connection`：一律以 `admit()` 为准，通过就放行；
+ *    只有「401 + 回环 + 没有任何凭据 + 用户显式开启兼容模式」这一种情况例外，
+ *    否则按 `admit()` 给出的状态码拒绝。
+ * 2. 宿主没有 `connection`：**默认拒绝**（403）。只有用户显式开启兼容模式、
+ *    且请求来自回环地址时才放行。
  *
  * @returns {boolean} 已放行 true；已写出拒绝响应 false
  */
-export function admissionGate(req, res, connection) {
+export function admissionGate(req, res, connection, options = {}) {
   const loopback = isLoopback(req);
+  const optIn = options.allowLegacyLoopback === true;
   if (connection && typeof connection.admit === "function") {
     let admission;
     try {
       admission = connection.admit(req);
     } catch (err) {
-      json(res, 500, { ok: false, error: `连接准入失败：${String((err && err.message) || err)}` });
+      denyAdmission(res, 500, `连接准入失败：${String((err && err.message) || err)}`);
+      return false;
+    }
+    if (!admission || typeof admission !== "object") {
+      // 宿主实现异常时宁可拒绝，也不要把「看不懂的结果」当成放行
+      denyAdmission(res, 500, "连接准入返回了无法识别的结果，按默认拒绝处理");
       return false;
     }
-    if (!admission || typeof admission.rejection !== "number") return true;
-    if (admission.rejection === 401 && loopback && !hasConnectionCredentials(req)) {
-      // 宿主自己的载体（Electron 经 IPC 桥接的 fetch）与本机脚本都不带 Cookie，
-      // 没有可核验的凭据，只能按回环信任放行 —— 与接入准入之前的行为一致。
-      if (typeof res.setHeader === "function") res.setHeader("X-DSH-Admission", "loopback-legacy");
+    if (!("rejection" in admission)) return true;
+    if (typeof admission.rejection !== "number") {
+      denyAdmission(res, 403, "连接准入返回了无法识别的拒绝码，按默认拒绝处理");
+      return false;
+    }
+    if (admission.rejection === 401 && loopback && !hasConnectionCredentials(req) && optIn) {
+      // 例外路径：宿主自己的载体（Electron 经 IPC 桥接的 fetch）与本机脚本都不带
+      // Cookie，没有可核验的凭据。只有用户显式开启兼容模式才退回回环信任。
+      markLegacyAdmission(res);
       return true;
     }
-    res.writeHead(admission.rejection, { "Content-Type": "text/plain; charset=utf-8" });
-    res.end(admission.rejection === 401 ? "unauthorized" : "forbidden");
+    const status = admission.rejection === 403 ? 403 : admission.rejection === 409 ? 409 : 401;
+    denyAdmission(
+      res,
+      status,
+      status === 401
+        ? "请求未通过 DSH connection 认证：缺少有效的会话 Cookie / API 凭据"
+        : status === 409
+          ? "请求对应的连接已被占用"
+          : "请求来源不受信任：Host/Origin 校验未通过"
+    );
     return false;
   }
-  if (!loopback) {
-    json(res, 403, { ok: false, error: "只接受本机请求（loopback）：当前宿主没有可用的 connection 准入服务" });
-    return false;
+  if (optIn && loopback) {
+    markLegacyAdmission(res);
+    return true;
   }
-  if (typeof res.setHeader === "function") res.setHeader("X-DSH-Admission", "loopback-legacy");
-  return true;
+  denyAdmission(
+    res,
+    403,
+    optIn
+      ? "只接受本机（loopback）请求：当前宿主没有可用的 connection 准入服务"
+      : "拒绝访问：当前宿主没有 connection 准入服务，兼容模式（仅回环放行）未开启，按默认拒绝处理"
+  );
+  return false;
 }
 
 /**
@@ -343,16 +408,30 @@ function openFolder(path) {
 
 export default {
   name: "dsh-app-updater",
-  apply(ctx) {
+  apply(ctx, config) {
+    // 兼容模式：默认关闭。只有用户显式写进插件配置或环境变量才开启（见 LEGACY_LOOPBACK_ENV）。
+    const allowLegacyLoopback = resolveLegacyLoopbackOptIn(config);
+
     ctx.effect(() => {
-      store.load().catch(() => {});
+      store
+        .load()
+        .then(() => {
+          if (allowLegacyLoopback) {
+            store.log(
+              "warn",
+              "兼容模式（allowLegacyLoopback）已开启：没有连接凭据的回环请求会按本机信任放行；" +
+                "建议只在旧宿主（没有 connection 服务）上临时使用"
+            );
+          }
+        })
+        .catch(() => {});
     }, "dsh-app-updater: load state");
 
     ctx.inject(["webServer"], (webCtx) => {
       const webServer = webCtx.webServer;
 
       // connection 准入：宿主提供的信任边界（Host/Origin 校验 + 浏览器/API 认证）。
-      // 它在宿主没有 Web 载体时不存在，此时 admissionGate 退回旧的「回环」检查。
+      // 它在宿主没有 Web 载体时不存在，此时 admissionGate 默认拒绝，除非兼容模式显式开启。
       let connection = null;
       ctx.inject(["connection"], (connCtx) => {
         connection = connCtx.connection;
@@ -362,6 +441,22 @@ export default {
       });
       const routes = [];
 
+      /** 准入现状：写进状态接口，界面/复核者不必读代码就知道当前走的是哪条路径。 */
+      const admissionInfo = () => ({
+        mode: connection
+          ? allowLegacyLoopback
+            ? "connection+loopback-legacy"
+            : "connection"
+          : allowLegacyLoopback
+            ? "loopback-legacy-optin"
+            : "deny",
+        service: Boolean(connection),
+        allowLegacyLoopback,
+        warning: allowLegacyLoopback
+          ? "兼容模式已开启：没有连接凭据的本机回环请求会被放行，仅应在旧宿主上临时使用"
+          : null,
+      });
+
       /**
        * 注册一条路由：请求先过 connection 准入（见 admissionGate），再进业务处理。
        * 写接口另有 `confirm:true` 闸门（writeGate）。
@@ -372,7 +467,7 @@ export default {
             kind: "exact",
             path: `${PREFIX}${path}`,
             handler: (req, res) => {
-              if (!admissionGate(req, res, connection)) return;
+              if (!admissionGate(req, res, connection, { allowLegacyLoopback })) return;
               return handler(req, res);
             },
           })
@@ -382,7 +477,7 @@ export default {
       register("/state.json", async (req, res) => {
         try {
           await store.load();
-          json(res, 200, buildStatePayload());
+          json(res, 200, { ...buildStatePayload(), admission: admissionInfo() });
         } catch (err) {
           json(res, 500, { ok: false, error: String((err && err.message) || err) });
         }
@@ -479,6 +574,7 @@ export default {
           envSummary: describeEnvironment(env),
           engine,
           capabilities: capabilitiesFor(env, Boolean(engine.available)),
+          admission: admissionInfo(),
           routes: routes.length,
           dataDir: join(process.env.DSH_HOME || join(homedir(), ".dsh"), "dsh-app-updater"),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-app-updater",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "type": "module",
   "description": "App Updater for DeepSeek Harness: detect every installed app that has a newer version and update it with one click by downloading the vendor's full installer from its official website and installing it silently — without launching the app. Windows (winget) and macOS (Homebrew), architecture-aware (ARM64 / x64). · 检测本机所有已安装应用是否有新版本，并从各自官网下载全量安装包一键静默更新（不需要打开被检测的软件）；自动识别 Windows / macOS 与 ARM64 / x64 架构，按架构下载对应安装包。",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "dsh": ">=0.1.5-rc.1 <0.2.0-0 || >=0.2.0-rc.2 <0.3.0-0"
   },
   "scripts": {
-    "test": "node test/unit.mjs && node test/render.mjs"
+    "test": "node test/unit.mjs && node test/render.mjs && node test/deny.mjs"
   },
   "dsh": {
     "bundle": {

package/test/deny.mjs

@@ -0,0 +1,149 @@
+/**
+ * 默认拒绝的端到端自测：宿主没有 connection 服务、且用户没有显式开启兼容模式时，
+ * `/dsh-app-updater/*` 的每一条路由都必须 403（1.3.0 的「仅凭回环放行」已移除）。
+ * 反方向再验证一次：显式开启兼容模式后，回环请求才会被放行并带上 opt-in 响应头。
+ *
+ * 运行：node test/deny.mjs
+ */
+
+import http from "node:http";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+process.env.DSH_HOME = process.env.DSH_HOME || join(here, "..", ".test-home");
+delete process.env.DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK;
+
+const plugin = (await import("../lib/index.js")).default;
+
+let checks = 0;
+let failures = 0;
+function ok(cond, label, extra) {
+  checks += 1;
+  if (cond) console.log(`  ✓ ${label}`);
+  else {
+    failures += 1;
+    console.log(`  ✗ ${label}${extra === undefined ? "" : ` — ${JSON.stringify(extra)}`}`);
+  }
+}
+
+/** 起一个假宿主（没有 connection 服务），返回服务地址与路由表。 */
+function mount(config) {
+  const routes = [];
+  const webServer = {
+    register(spec) {
+      routes.push(spec);
+      return () => {};
+    },
+  };
+  const ctx = {
+    effect(fn) {
+      const dispose = fn();
+      return () => {
+        if (typeof dispose === "function") dispose();
+      };
+    },
+    inject(deps, fn) {
+      // 只提供 webServer，不提供 connection —— 等价于旧宿主
+      fn({ webServer });
+    },
+  };
+  plugin.apply(ctx, config);
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, "http://127.0.0.1");
+    const route = routes.find((r) => r.path === url.pathname);
+    if (!route) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: false, error: "no route" }));
+      return;
+    }
+    Promise.resolve(route.handler(req, res)).catch((err) => {
+      if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: false, error: String((err && err.message) || err) }));
+    });
+  });
+  return { routes, server };
+}
+
+async function serve(server) {
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  return `http://127.0.0.1:${server.address().port}`;
+}
+
+const ROUTES = [
+  "/dsh-app-updater/state.json",
+  "/dsh-app-updater/apps.json",
+  "/dsh-app-updater/scan",
+  "/dsh-app-updater/update",
+  "/dsh-app-updater/cancel",
+  "/dsh-app-updater/settings",
+  "/dsh-app-updater/open-downloads",
+  "/dsh-app-updater/health.json",
+];
+
+/* ------------------------------------------------------------------ *
+ * 1. 默认拒绝：没有 connection + 没有兼容模式
+ * ------------------------------------------------------------------ */
+console.log("\n默认拒绝（没有 connection 服务、未开启兼容模式）");
+const denied = mount(undefined);
+const deniedBase = await serve(denied.server);
+for (const p of ROUTES) {
+  const isWrite = ["/scan", "/update", "/cancel", "/settings", "/open-downloads"].includes(
+    p.replace("/dsh-app-updater", "")
+  );
+  const res = await fetch(deniedBase + p, isWrite
+    ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ confirm: true }) }
+    : undefined);
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  ok(
+    res.status === 403 && res.headers.get("x-dsh-admission") === "denied" && body && body.ok === false,
+    `${p} → 403 + X-DSH-Admission: denied`,
+    { status: res.status, admission: res.headers.get("x-dsh-admission"), body }
+  );
+}
+denied.server.close();
+
+/* ------------------------------------------------------------------ *
+ * 2. 显式开启兼容模式：同一套路由才放行（且只在回环地址上）
+ * ------------------------------------------------------------------ */
+console.log("\n显式开启兼容模式（配置 allowLegacyLoopback: true）");
+const legacy = mount({ allowLegacyLoopback: true });
+const legacyBase = await serve(legacy.server);
+
+const stateRes = await fetch(legacyBase + "/dsh-app-updater/state.json");
+const state = await stateRes.json();
+ok(
+  stateRes.status === 200 && stateRes.headers.get("x-dsh-admission") === "loopback-legacy-optin",
+  "state.json → 200 + X-DSH-Admission: loopback-legacy-optin"
+);
+ok(
+  state && state.admission && state.admission.mode === "loopback-legacy-optin" && state.admission.allowLegacyLoopback === true,
+  "状态接口暴露 admission 现状（供复核）",
+  state && state.admission
+);
+
+const health = await (await fetch(legacyBase + "/dsh-app-updater/health.json")).json();
+ok(
+  health && health.admission && health.admission.mode === "loopback-legacy-optin",
+  "health.json 同样标注兼容模式",
+  health && health.admission
+);
+
+const badWrite = await (await fetch(legacyBase + "/dsh-app-updater/scan", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({}),
+})).json();
+ok(badWrite && badWrite.ok === false && String(badWrite.error).includes("confirm"), "兼容模式下写接口仍要求 confirm:true");
+
+legacy.server.close();
+
+/* ------------------------------------------------------------------ */
+console.log(`\n${failures === 0 ? "全部通过" : "存在失败"}：${checks - failures}/${checks}`);
+process.exit(failures === 0 ? 0 : 1);

package/test/harness.mjs

@@ -11,6 +11,9 @@ import { dirname, join } from "node:path";
 
 const here = dirname(fileURLToPath(import.meta.url));
 process.env.DSH_HOME = process.env.DSH_HOME || join(here, "..", ".test-home");
+// 这个假 ctx 没有 connection 服务，等价于旧宿主：默认拒绝下路由一律 403。
+// 所以自测里显式开启兼容模式（与用户在旧宿主上手动开启走的是同一段代码）。
+process.env.DSH_APP_UPDATER_ALLOW_LEGACY_LOOPBACK = "1";
 
 const plugin = (await import("../lib/index.js")).default;
 

package/test/render.mjs

@@ -394,6 +394,26 @@ await tick();
 tree = rt.render();
 ok(byClass(tree, "appupd-banner").length === 0, "关闭演练模式后警示条消失（宿主回读 state）");
 
+group("兼容模式（仅回环放行）警示条");
+statePayload = baseState({ admission: { mode: "loopback-legacy-optin", service: false, allowLegacyLoopback: true, warning: null } });
+rt.reset();
+await tick();
+tree = rt.render();
+await tick();
+tree = rt.render();
+ok(byClass(tree, "appupd-banner").length === 1, "兼容模式开启时显示警示条", byClass(tree, "appupd-banner").length);
+ok(byClass(tree, "appupd-banner-warn").length === 1, "兼容模式警示条用警示样式");
+ok(textOf(byClass(tree, "appupd-banner")[0]).includes("兼容模式已开启"), "警示条文案包含「兼容模式已开启」");
+
+statePayload = baseState({ admission: { mode: "deny", service: false, allowLegacyLoopback: false, warning: null } });
+rt.reset();
+await tick();
+tree = rt.render();
+await tick();
+tree = rt.render();
+ok(byClass(tree, "appupd-banner").length === 0, "默认（未开启兼容模式）不显示任何警示条");
+statePayload = baseState();
+
 group("下载目录校验");
 calls.length = 0;
 statePayload = baseState();

package/test/unit.mjs

@@ -20,7 +20,7 @@ import {
 import { compareVersions, isNewer, looksLikeVersion, splitVersion } from "../lib/version.js";
 import { parseInstallerManifest, splitSwitchArgs, defaultSilentArgs, resolveInstallArgs, parseBrewCaskVersions, parseBrewOutdated, findBrew, isArchNotFoundError, explainInstallerExitCode, evaluateUpdateResult, findEdgeUpdate, updateHintFor } from "../lib/engine.js";
 import { psQuote, ELEVATION_CANCELLED } from "../lib/elevate.js";
-import { admissionGate, hasConnectionCredentials } from "../lib/index.js";
+import { admissionGate, hasConnectionCredentials, resolveLegacyLoopbackOptIn, LEGACY_LOOPBACK_ENV } from "../lib/index.js";
 import {
   detectEnvironment,
   describeEnvironment,
@@ -300,25 +300,77 @@ function fakeReq({ loopback = true, headers = {} } = {}) {
   return { socket: { remoteAddress: loopback ? "127.0.0.1" : "10.0.0.5" }, headers };
 }
 
-group("connection 准入（市场审核要求）");
+group("connection 准入（市场审核要求：默认拒绝）");
 ok(hasConnectionCredentials({ headers: { cookie: "dsh=x" } }) === true, "识别浏览器会话 Cookie");
 ok(hasConnectionCredentials({ headers: { authorization: "Bearer x" } }) === true, "识别 API Cookie/Authorization");
 ok(hasConnectionCredentials({ headers: {} }) === false, "没有凭据时返回 false");
-ok(admissionGate(fakeReq(), fakeRes(), null) === true, "宿主没有 connection 服务时，回环请求放行");
+
+/* --- 兼容模式开关：默认关闭，必须是显式动作 --- */
+ok(resolveLegacyLoopbackOptIn(undefined, {}) === false, "没有任何显式开关 → 兼容模式关闭");
+ok(resolveLegacyLoopbackOptIn(null, {}) === false, "配置为 null → 兼容模式关闭");
+ok(resolveLegacyLoopbackOptIn({}, {}) === false, "配置里没有该字段 → 兼容模式关闭");
+ok(resolveLegacyLoopbackOptIn({ allowLegacyLoopback: false }, {}) === false, "配置显式 false → 关闭");
+ok(resolveLegacyLoopbackOptIn({ allowLegacyLoopback: true }, {}) === true, "插件配置 allowLegacyLoopback:true → 开启");
+ok(resolveLegacyLoopbackOptIn(undefined, { [LEGACY_LOOPBACK_ENV]: "1" }) === true, "环境变量 =1 → 开启");
+ok(resolveLegacyLoopbackOptIn(undefined, { [LEGACY_LOOPBACK_ENV]: "true" }) === true, "环境变量 =true → 开启");
+ok(resolveLegacyLoopbackOptIn(undefined, { [LEGACY_LOOPBACK_ENV]: "0" }) === false, "环境变量 =0 → 关闭");
+ok(resolveLegacyLoopbackOptIn(undefined, { [LEGACY_LOOPBACK_ENV]: "off" }) === false, "环境变量 =off → 关闭");
+
+/* --- 宿主没有 connection 服务：默认拒绝，只有显式开启兼容模式才放行 --- */
+{
+  const res = fakeRes();
+  ok(
+    admissionGate(fakeReq(), res, null) === false && res.statusCode === 403 && res.headers["X-DSH-Admission"] === "denied",
+    "没有 connection 服务 + 回环 + 未开兼容模式 → 403（默认拒绝）"
+  );
+}
 {
   const res = fakeRes();
   ok(admissionGate(fakeReq({ loopback: false }), res, null) === false && res.statusCode === 403, "没有 connection 服务时，非回环请求 403");
 }
+{
+  const res = fakeRes();
+  ok(
+    admissionGate(fakeReq(), res, null, { allowLegacyLoopback: true }) === true &&
+      res.headers["X-DSH-Admission"] === "loopback-legacy-optin" &&
+      res.headers["X-DSH-Admission-Warning"] === "legacy-loopback-compatibility-enabled",
+    "显式开启兼容模式 + 回环 → 放行并标注 opt-in 响应头"
+  );
+}
+{
+  const res = fakeRes();
+  ok(
+    admissionGate(fakeReq({ loopback: false }), res, null, { allowLegacyLoopback: true }) === false && res.statusCode === 403,
+    "即使开启兼容模式，非回环请求仍然 403"
+  );
+}
+
+/* --- 宿主有 connection 服务：一律以 admit() 为准 --- */
 {
   const res = fakeRes();
   const connection = { admit: () => ({ peer: { id: "peer-1" } }) };
   ok(admissionGate(fakeReq(), res, connection) === true && res.statusCode === 0, "准入通过 → 放行且不写响应");
 }
+{
+  const res = fakeRes();
+  const connection = { admit: () => undefined };
+  ok(admissionGate(fakeReq(), res, connection) === false && res.statusCode === 500, "准入返回空值 → 500（不把看不懂的结果放行）");
+}
+{
+  const res = fakeRes();
+  const connection = { admit: () => ({ rejection: "401" }) };
+  ok(admissionGate(fakeReq(), res, connection) === false && res.statusCode === 403, "准入返回非数字拒绝码 → 403（fail-closed）");
+}
 {
   const res = fakeRes();
   const connection = { admit: () => ({ rejection: 403 }) };
   ok(admissionGate(fakeReq({ loopback: false }), res, connection) === false && res.statusCode === 403, "准入拒绝 403（不可信来源）→ 403");
 }
+{
+  const res = fakeRes();
+  const connection = { admit: () => ({ rejection: 409 }) };
+  ok(admissionGate(fakeReq(), res, connection) === false && res.statusCode === 409, "准入拒绝 409（连接被占用）→ 409");
+}
 {
   const res = fakeRes();
   const connection = { admit: () => ({ rejection: 401 }) };
@@ -328,8 +380,34 @@ ok(admissionGate(fakeReq(), fakeRes(), null) === true, "宿主没有 connection
   const res = fakeRes();
   const connection = { admit: () => ({ rejection: 401 }) };
   ok(
-    admissionGate(fakeReq(), res, connection) === true && res.headers["X-DSH-Admission"] === "loopback-legacy",
-    "无凭据的回环请求退回旧规则并标注响应头"
+    admissionGate(fakeReq({ headers: { cookie: "dsh=x" } }), res, connection, { allowLegacyLoopback: true }) === false &&
+      res.statusCode === 401,
+    "带凭据未认证时，兼容模式也不放行"
+  );
+}
+{
+  const res = fakeRes();
+  const connection = { admit: () => ({ rejection: 401 }) };
+  ok(
+    admissionGate(fakeReq(), res, connection) === false && res.statusCode === 401 && res.headers["X-DSH-Admission"] === "denied",
+    "无凭据的回环请求默认拒绝（不再退回回环信任）"
+  );
+}
+{
+  const res = fakeRes();
+  const connection = { admit: () => ({ rejection: 401 }) };
+  ok(
+    admissionGate(fakeReq(), res, connection, { allowLegacyLoopback: true }) === true &&
+      res.headers["X-DSH-Admission"] === "loopback-legacy-optin",
+    "显式开启兼容模式后，无凭据的回环请求才按旧规则放行"
+  );
+}
+{
+  const res = fakeRes();
+  const connection = { admit: () => ({ rejection: 401 }) };
+  ok(
+    admissionGate(fakeReq({ loopback: false }), res, connection, { allowLegacyLoopback: true }) === false && res.statusCode === 401,
+    "兼容模式的例外只覆盖回环地址，非回环仍然 401"
   );
 }
 {