@riceawa/dsh-lan-gateway 0.5.3 → 0.5.5

package/README.md

@@ -6,35 +6,35 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/DeepSeek%20Harness-4d6bfe?logo=deepseek&logoColor=fff&style=flat-square" alt="DeepSeek Harness" />
-  <img src="https://img.shields.io/badge/version-0.5.3-2b7fff?style=flat-square" alt="version 0.5.3" />
+  <img src="https://img.shields.io/badge/version-0.5.5-2b7fff?style=flat-square" alt="version 0.5.5" />
   <img src="https://img.shields.io/badge/TLS-8b5cf6?logo=lock&logoColor=fff&style=flat-square" alt="TLS" />
   <img src="https://img.shields.io/github/license/rice-awa/dsh-lan-gateway?style=flat-square" alt="MIT license" />
   <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
 </p>
 
-`dsh web` 硬拒绝 `--host 0.0.0.0`，怕把远程代码执行暴露到网络。这个插件的做法是让 dsh 继续只绑 `127.0.0.1`，另起一个监听 `0.0.0.0` 的反向代理，转发到 loopback 端口并改写 `Host` / `Origin`。
+`dsh web` 明确拒绝 `--host 0.0.0.0`，以免把远程代码执行暴露到网络。本插件的做法是让 dsh 继续只绑 `127.0.0.1`，另起一个反向代理监听未指定地址（双栈，IPv4 与 IPv6 客户端都可接入），转发到 loopback 端口并改写 `Host` / `Origin`。
 
-默认拒绝：loopback、LAN、公网三种来源都要先在网关登录页拿到 HMAC 会话 cookie，LAN 免密需要显式打开 `lanPasswordless`，默认关闭。底座是 dsh ≥ 0.1.2-rc.1 时（含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自己的授权仍然把关每个请求，网关只决定谁能骑上这条会话。
+默认拒绝：loopback、LAN、公网三种来源都要先在网关登录页取得 HMAC 会话 cookie，LAN 免密需要显式打开 `lanPasswordless`，默认关闭。底座为 dsh ≥ 0.1.2-rc.1 时（含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自身的授权仍然把关每个请求，网关只决定谁可以使用这条会话。
 
-插件还捎带两件事：
+插件另外提供两项功能：
 
-- **不安全源 UUID shim**：网关以纯 HTTP 的局域网地址服务页面，浏览器视其为不安全源，不提供 `crypto.randomUUID`。client bundle 在页面加载早期补一个基于 `getRandomValues` 的实现，工作区才打得开。
-- **TLS**：自动生成并持久化的自签名证书，或者挂载你自己签发的 PEM。自签名证书首次访问会有浏览器警告，正常现象。
+- **不安全源 UUID shim**：网关以纯 HTTP 的局域网地址服务页面，浏览器视其为不安全源，不提供 `crypto.randomUUID`。client bundle 在页面加载早期补一个基于 `getRandomValues` 的实现，工作区才能正常打开。
+- **TLS**：自动生成并持久化的自签名证书，或者挂载自行签发的 PEM。自签名证书首次访问会有浏览器警告，属预期行为。
 
 ## 安装
 
-已发布到 npm，装的是预构建产物，不需要 `allowBuilds` 授权。把这段话丢给你的 agent 就行：
+已发布到 npm，安装的是预构建产物，不需要 `allowBuilds` 授权。可将下面这段话交给你的 agent：
 
 > 帮我安装 dsh 插件 `@riceawa/dsh-lan-gateway`，遵循
 > `https://github.com/rice-awa/dsh-lan-gateway/blob/main/INSTALL.md`
 
-也可以自己敲：
+也可以手动执行：
 
 ```bash
 dsh plugin --profile web add @riceawa/dsh-lan-gateway
 ```
 
-`dsh plugin ... add` 会把参数转发给 profile 目录里的 pnpm。npm 包自带 `lib/`，不会触发 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`。真报了错，就把报错条目写进 `~/.dsh/profiles/web/pnpm-workspace.yaml` 的 `allowBuilds` 重试，完整步骤见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
+`dsh plugin ... add` 会把参数转发给 profile 目录里的 pnpm。npm 包自带 `lib/`，不会触发 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`。如果仍然报错，把报错条目写进 `~/.dsh/profiles/web/pnpm-workspace.yaml` 的 `allowBuilds` 后重试，完整步骤见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
 
 从源码构建：
 
@@ -44,12 +44,12 @@ cd dsh-lan-gateway
 pnpm install
 pnpm build          # host → lib/index.js
 pnpm build:client   # client → lib/client.js
-pnpm test           # 93 项
+pnpm test           # 117 项
 ```
 
-仓库里还有一个 [lan-gateway](skills/lan-gateway.md) 技能，装上之后可以直接在 dsh 对话里说「设置网关密码为 …」「开启远程访问」，agent 会调用 `lan_gateway` 工具完成，密码以参数传入，不写配置也不回显。安装方式见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
+仓库里还有一个 [lan-gateway](skills/lan-gateway.md) 技能，安装后可直接在 dsh 对话里说「设置网关密码为 …」「开启远程访问」，agent 会调用 `lan_gateway` 工具完成，密码以参数传入，不写入配置，也不回显。安装方式见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
 
-手机 / 平板上访问的话，再搭一个 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) 做移动端 UI 适配：
+如需在手机 / 平板上访问，可另外安装 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) 做移动端 UI 适配：
 
 ```bash
 dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
@@ -59,23 +59,23 @@ dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
 
 ```bash
 lan_gateway enable            # 开启网关（需先满足启动条件，否则给出迁移文案）
-lan_gateway status            # 端口 / 目标 / 密码 / 会话 epoch / 中继状态 / 入口加密方式 / 上次错误
+lan_gateway status            # 端口 / 目标 / 密码 / 会话 epoch / 已登出会话数 / 中继状态 / 入口加密方式 / 上次错误
 lan_gateway set-password      # 设置登录密码（≥8 位，改动会让所有已签发会话立即失效）
 lan_gateway rotate-secret     # 轮换会话密钥，作废全部登录 cookie 与已建立的 WebSocket
 lan_gateway tls-regenerate    # 换发自签名证书（tlsMode=self-signed 时）
 lan_gateway disable           # 关闭
 ```
 
-`lan_gateway` 是模型可调用的工具，上面这些命令不必自己敲。直接在对话里说「查看网关状态」「设置网关密码为 ……」即可，密码以参数传给模型，不会落进任何配置文件。
+`lan_gateway` 是模型可调用的工具，上述命令无需手动执行。直接在对话里说「查看网关状态」「设置网关密码为 ……」即可，密码以参数传给模型，不会写入任何配置文件。
 
 ## 配置
 
-所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片就能改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
+所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片即可修改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
 
 | 键 | 默认值 | 说明 |
 | --- | --- | --- |
 | `enabled` | `false` | 是否在启动时监听网络端口 |
-| `gatewayPort` | `3081` | 网关监听端口（`0.0.0.0`） |
+| `gatewayPort` | `3081` | 网关监听端口（未指定地址 / 双栈） |
 | `dshTargetPort` | 跟随 `ctx.webServer.port` | 转发到的 dsh loopback 端口 |
 | `lanCidrs` | RFC1918 + link-local（见下） | 视为 LAN 的网段，仅在 `lanPasswordless` 开启时用作豁免匹配集 |
 | `lanPasswordless` | `false` | LAN/loopback 来源跳过网关登录页（上游会话中继仍把关） |
@@ -83,12 +83,12 @@ lan_gateway disable           # 关闭
 | `cookieName` | `dsh_gw_auth` | 会话 cookie 名，不进卡片 |
 | `tlsEnabled` | `false` | 是否以 HTTPS 提供服务 |
 | `tlsMode` | `self-signed` | `self-signed` 自动生成 / `custom` 用自己的证书 |
-| `tlsSelfSignedHosts` | `localhost` | 自签名证书的 SAN（逗号分隔的域名 / IP） |
+| `tlsSelfSignedHosts` | `localhost` | 自签名证书的 SAN（逗号分隔的域名 / IP）。仅影响下次换发，见下「证书有效期」 |
 | `tlsCertPath` | — | `custom` 模式：PEM 证书（或证书链）绝对路径 |
 | `tlsKeyPath` | — | `custom` 模式：PEM 私钥绝对路径 |
-| `tlsCertMaxAgeDays` | `825` | 自签名证书有效期（天） |
+| `tlsCertMaxAgeDays` | `825` | 自签名证书有效期（天），见下「证书有效期」 |
 | `allowInsecurePlaintext` | `false` | 允许明文 HTTP 监听（见下「入口加密」） |
-| `trustedTerminator` | — | 声明一个受信 TLS 终止代理标识，视为加密入口（如 `nginx`） |
+| `trustedTerminator` | — | 声明一个受信 TLS 终止代理标识，视为加密入口（如 `nginx`）。注意登录限流的键，见下「登录限流」 |
 | `secureCookies` | 自动 | 会话 cookie 的 `Secure` 属性显式开关，默认按 `tlsEnabled` 或 `trustedTerminator` 推断（见下） |
 
 默认 `lanCidrs`：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`169.254.0.0/16`。IPv6 的 `fe80::/10`（link-local）与 `127.0.0.0/8`、`::1` 归为 LAN/loopback。
@@ -97,9 +97,9 @@ lan_gateway disable           # 关闭
 
 ### 入口加密
 
-网关默认拒绝纯明文监听，下面三条路任选一条才能启动：
+网关默认拒绝纯明文监听，以下三种方式任选其一方可启动：
 
-1. 启用 TLS，`tlsEnabled: true`。推荐，自签名或 custom 证书都行。
+1. 启用 TLS，`tlsEnabled: true`。推荐，自签名或 custom 证书均可。
 2. 声明由可信反向代理终止 TLS：
 
    ```yaml
@@ -120,7 +120,7 @@ lan_gateway disable           # 关闭
        allowInsecurePlaintext: true
    ```
 
-用自己的证书（比如 Let's Encrypt 签发的 PEM）：
+使用自有证书（例如 Let's Encrypt 签发的 PEM）：
 
 ```yaml
 - id: dsh-lan-gateway
@@ -131,15 +131,21 @@ lan_gateway disable           # 关闭
     tlsKeyPath: /etc/letsencrypt/live/example.com/privkey.pem
 ```
 
-自签名证书在首次启用 TLS 时生成一次，落到 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。要换新证书用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。
+自签名证书在首次启用 TLS 时生成一次，写入 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。更换证书使用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。已到期的证书在启动时自动换发并记一条 warning。修改 `tlsSelfSignedHosts` 或 `tlsCertMaxAgeDays` 只影响**下次换发**：已有证书沿用至到期，不会在保存时被悄悄替换。
+
+### 证书有效期
+
+默认有效期 825 天。常见的 398 天上限只约束链到平台预装根 CA 的证书，Apple 明确豁免「由用户或管理员添加的根 CA」签发的证书（[support.apple.com/en-us/102028](https://support.apple.com/en-us/102028)），而自签证书必然是这样一条根——没有任何系统预装它。825 天则是 Apple 对 TLS 服务器证书给出的上限（[support.apple.com/en-us/103769](https://support.apple.com/en-us/103769)），默认值取在该上限之内。
+
+自签证书要么被点击通过、要么被手工信任，因此缩短有效期没有收益，每次到期反而要重新信任一次。需要更短的窗口时用 `tlsCertMaxAgeDays` 自行调整。
 
 监听器自身是 HTTPS 时，网关的响应（登录页 / 重定向 / 拒绝）带 HSTS。
 
 ### 关于 `Secure` cookie
 
-启用 TLS 或声明受信终止代理后，登录 cookie 自动带 `Secure`。但「声明了受信代理」只说明前面有个代理，不说明浏览器到代理这一段是加密的。
+启用 TLS 或声明受信终止代理后，登录 cookie 自动带 `Secure`。但「声明了受信代理」只说明网关前方存在一个代理，不说明浏览器到代理这一段是加密的。
 
-如果那个代理只做明文鉴权、浏览器以 `http://` 访问（代理再以明文转发回本端口），自动推断会把 `Secure` 加上，而浏览器拒收明文 http 上的 Secure cookie。结果是密码校验通过、cookie 存不下，每次都被弹回 `/__login`，无限循环。这种部署要显式关掉：
+如果该代理只做明文鉴权、浏览器以 `http://` 访问（代理再以明文转发回本端口），自动推断会把 `Secure` 加上，而浏览器拒收明文 http 上的 Secure cookie。结果是密码校验通过、cookie 无法保存，每次都被重定向回 `/__login`，无限循环。这种部署需要显式关闭：
 
 ```yaml
 - id: dsh-lan-gateway
@@ -150,24 +156,30 @@ lan_gateway disable           # 关闭
     secureCookies: false   # 浏览器 → nginx 是明文 http，不能带 Secure
 ```
 
-`lan_gateway status` 会如实报出实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
+`lan_gateway status` 会如实报告实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
+
+### 登录限流
+
+登录尝试以 TCP 源地址为键限流，每分钟 5 次。`X-Forwarded-For` 与 `Forwarded` 在转发前一律删除，也不参与限流取键——它们可由客户端任意伪造，用它们作为键等于把限流关掉。
+
+代价是声明 `trustedTerminator` 之后，所有浏览器请求都来自代理这一个地址，5 次/分钟变成**整个部署共享**的额度，而非每客户端 5 次。这一耦合没有便宜的修法：要么接受它（把上限视为抗暴力破解的下限而非每用户配额），要么让代理直连、由网关自己面对客户端。当前不接受按 `X-Forwarded-For` 分桶。
 
-注意 `secureCookies: false` 说的是浏览器到入口那一段是明文，网关登录密码和会话 cookie 会在这一段明文传输。这跟 `allowInsecurePlaintext` 描述的不是同一段链路：后者指代理到网关之间不加密，前者指浏览器到代理之间不加密。只有当代理本身已经对用户完成鉴权、且你能接受这段明文时，才这么配。
+注意 `secureCookies: false` 说的是浏览器到入口这一段是明文，网关登录密码和会话 cookie 会在这一段明文传输。这与 `allowInsecurePlaintext` 描述的不是同一段链路：后者指代理到网关之间不加密，前者指浏览器到代理之间不加密。只有当代理本身已经对用户完成鉴权、且可以接受这段明文时，才应这样配置。
 
 ## 安全模型
 
 - **来源分级只认 `socket.remoteAddress`**（IPv4-mapped IPv6 会先解包），分 loopback / lan / internet 三档，绝不信任 `X-Forwarded-For`。分级本身不授予任何访问，每一档默认都要出示有效网关会话，否则 302 到 `/__login`。
-- **LAN 免密是显式 opt-in**。`lanPasswordless: true` 只让命中 `lanCidrs` 或 loopback 的来源跳过网关自己的登录页；底座 ≥ 0.1.2-rc.1 时上游会话仍把关每个请求。底座没有浏览器会话认证时这个开关拒绝启用，否则等于把 QVD-2026-57410 原样装回去。
-- **共享上游会话中继**（dsh ≥ 0.1.2-rc.1）。dsh 不再信任回环 Host，要求出示 HMAC 签名的 `dsh-auth-*` cookie。插件经 `connection` 服务拿到启动令牌，在回环传输上做一次浏览器等价的令牌换取，取得 cookie 后中继到每个转发请求；上游一旦 401 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的人骑同一条上游会话，持钥的上游才是真正的授权主体。
+- **LAN 免密是显式 opt-in**。`lanPasswordless: true` 只让命中 `lanCidrs` 或 loopback 的来源跳过网关自己的登录页；底座 ≥ 0.1.2-rc.1 时上游会话仍把关每个请求。底座没有浏览器会话认证时这个开关拒绝启用，否则等同于把 QVD-2026-57410 原样恢复。
+- **共享上游会话中继**（dsh ≥ 0.1.2-rc.1）。dsh 不再信任回环 Host，要求出示 HMAC 签名的 `dsh-auth-*` cookie。插件经 `connection` 服务拿到启动令牌，在回环传输上做一次浏览器等价的令牌换取，取得 cookie 后中继到每个转发请求；上游一旦 401 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的用户共用同一条上游会话，持钥的上游才是真正的授权主体。
 - **登录页**。`/__login` 由网关独占、不转发。密码以 scrypt 校验，每写一次重新加盐；登录尝试按来源限流（5 次 / 分钟）。
-- **会话 cookie** 是 `payload.signature` 结构（HMAC-SHA256），带撤销 epoch，`HttpOnly; SameSite=Strict`。改密、清密、`rotate-secret` 都会递增 epoch，作废全部已签发 cookie 并断开已建立的 WebSocket，客户端需要重新登录。清空密码会直接停止监听。
-- **管理面不外泄**。`/lan-gateway/*`（含配置路由）由网关独占、一律 403 不转发，远程访问者没法借网关改写 Host 去够到本机 loopback 的配置接口。原生 `/lan-gateway/config` 只应答回环 Host 且同源的请求。远程管理走 `lan_gateway` 工具。
+- **会话 cookie** 是 `payload.signature` 结构（HMAC-SHA256），带撤销 epoch 与逐会话 id，`HttpOnly; SameSite=Strict`。登出撤销的是当前这条会话：它建立的 WebSocket 一并断开，其他设备不受影响。改密、清密、`rotate-secret` 递增 epoch，作废全部已签发 cookie 并断开全部已建立的 WebSocket，客户端需要重新登录。清空密码会直接停止监听。
+- **管理面不外泄**。`/lan-gateway/*`（含配置路由）由网关独占、一律 403 不转发，远程访问者无法借网关改写 Host 触及本机 loopback 的配置接口。原生 `/lan-gateway/config` 只应答回环 Host 且同源的请求。远程管理走 `lan_gateway` 工具。
 - **CSRF 围栏**（HTTP 与 WebSocket）。网关把 Origin 改写回 loopback，会蒙蔽 dsh 自身的 CSRF 防线，所以在改写前对每个转发请求自检：`sec-fetch-site: cross-site` 直接拒；Origin 必须匹配访问者实际使用的网关权威来源；状态变更方法与 WebSocket 升级请求必须携带同源 Origin，否则 403。
-- **没设密码就拒绝监听**，跟来源无关。
+- **未设置密码时拒绝监听**，与来源无关。
 
 ## 登录页
 
-远程来源打开 `http://<主机>:3081/` 时先看到网关自带的登录表单，输入正确密码后签发会话 cookie 并跳回 `/`。
+远程来源打开 `http://<主机>:3081/` 时先看到网关自带的登录表单，输入正确密码后签发会话 cookie 并跳转回 `/`。
 
 <p align="center">
   <img src="assets/login-screenshot.webp" alt="网关登录页截图" width="320" />
@@ -175,26 +187,26 @@ lan_gateway disable           # 关闭
 
 ## UUID shim
 
-网关以 `http://<LAN-IP>:3081` 服务页面，浏览器视其为不安全源，`crypto.randomUUID()`（仅安全源可用）为 `undefined`，于是每次 RPC id 铸造都抛 `crypto.randomUUID is not a function`，工作区打不开。
+网关以 `http://<LAN-IP>:3081` 服务页面，浏览器视其为不安全源，`crypto.randomUUID()`（仅安全源可用）为 `undefined`，于是每次 RPC id 铸造都抛 `crypto.randomUUID is not a function`，工作区无法打开。
 
-client bundle 在模块级给 `Crypto` 原型补一个基于 `crypto.getRandomValues()` 的 `randomUUID`（RFC 4122 v4，`getRandomValues` 在所有源都可用）。它在浏览器求值时就执行，早于任何官方代码铸造 id，所以对官方所有调用点（含以后新增的）一律生效，不用改 DSH 源码。安全源和 Node ≥ 19 下是 no-op，不影响任何行为。
+client bundle 在模块级给 `Crypto` 原型补一个基于 `crypto.getRandomValues()` 的 `randomUUID`（RFC 4122 v4，`getRandomValues` 在所有源都可用）。它在浏览器求值时就执行，早于任何官方代码铸造 id，所以对官方所有调用点（含以后新增的）一律生效，无需修改 DSH 源码。安全源和 Node ≥ 19 下是 no-op，不影响任何行为。
 
 ## 开发
 
 ```bash
-pnpm test        # 93 项
+pnpm test        # 117 项
 pnpm typecheck   # tsc 双端（host + client）
 ```
 
 ```
-✓ tests/gateway.test.ts               (27) 分类 / HMAC cookie / epoch / 密码状态 / 限流
+✓ tests/gateway.test.ts               (40) 分类 / HMAC cookie / epoch / 逐会话撤销 / 密码状态 / 限流
 ✓ tests/start-guard.test.ts           (19) fail-closed 启动守卫 / 配置路由回环围栏 /
                                            Secure cookie 属性推断（含 null 清除路径）
-✓ tests/integration/gateway.test.ts   (17) 真实网关端到端：全来源登录 / LAN 豁免 /
-                                           跨站 403 / 升级拒绝 / cookie 属性 / epoch 撤销 / 会话中继
+✓ tests/integration/gateway.test.ts   (26) 真实网关端到端：全来源登录 / LAN 豁免 / 跨站 403 / 升级拒绝 /
+                                           cookie 属性 / epoch 撤销 / 逐会话登出 / 尾斜杠 / IPv6 / 会话中继
 ✓ tests/uuid-shim.test.ts             ( 3) 不安全源补丁 / 安全源 no-op / v4 正确性
 ✓ tests/x509.test.ts                  ( 6) 自签名证书 DER/SAN/签名/TLS 握手
-✓ tests/tls.test.ts                   ( 7) 证书持久化 / 重生成 / 自定义证书加载
+✓ tests/tls.test.ts                   ( 9) 证书持久化 / 到期换发 / 重生成 / 自定义证书加载
 ✓ tests/upstream-session.test.ts      ( 8) 真实回环令牌换取：cookie 名匹配 / 拒绝后重换 /
                                            invalidate 重获取 / 日志播报 / 保住已持有会话
 ✓ tests/settings-card.test.ts         ( 6) 设置页字段编解码：三态 auto ↔ false 不可混淆
@@ -221,8 +233,8 @@ pnpm typecheck   # tsc 双端（host + client）
 pnpm install --frozen-lockfile
 pnpm typecheck && pnpm test
 npm publish --access public                       # prepack 自动构建 lib/
-git tag -a v0.5.3 -m "…" && git push origin v0.5.3
-gh release create v0.5.3 --generate-notes ./*.tgz # 可选：Release + tgz 附件
+git tag -a v0.5.5 -m "…" && git push origin v0.5.5
+gh release create v0.5.5 --generate-notes ./*.tgz # 可选：Release + tgz 附件
 ```
 
 ## 安全评估
@@ -232,6 +244,7 @@ gh release create v0.5.3 --generate-notes ./*.tgz # 可选：Release + tgz 附
 - [LAN 网关安全评估](docs/security/SECURITY-AUDIT.md)：0.4.0 时代的 F1–F5 审计快照与 13 个隔离观察，顶部标注了 0.5.0 的修复状态。
 - [QVD-2026-57410 修复方案](docs/security/qvd-2026-57410-fix-plan.md)：方案全文 + §15 实施状态。
 - [上游研究](docs/security/qvd-2026-57410-research.md)：公开通告、上游提交与版本核对。
+- [0.5.4 复审与修复清单](docs/security/audit-2026-09-19-fix-list.md)：0.5.3 的实现细节复审（G1–G12）与修复记录。
 
 ## 许可
 

package/lib/client.js

@@ -6,131 +6,19 @@ window.__ModuleLoader__.load({
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
-		//#region src/client/lan-gateway-card.tsx
-		/**
-		* The lan-gateway settings card shown in the official DSH Settings → Plugins
-		* page (the `settings.plugin.item` slot).
-		*
-		* ModLens-style: the card carries NO injected services. It reads and writes
-		* the loopback-only `/lan-gateway/config` host route (the browser never sees
-		* the settings seam or any secret), so the client bundle's only dependency is
-		* the `slots` service that every plugin already has.
-		*
-		* @module @riceawa/dsh-lan-gateway/client/card
-		*/
-		const LABELS = {
-			zh: {
-				title: "LAN 网关",
-				description: "远程访问开关、端口、TLS 证书、受信网段等网关设置",
-				unsaved: "未保存",
-				save: "保存",
-				saving: "保存中…",
-				discard: "放弃",
-				reset: "重置",
-				overridden: "已覆盖",
-				readOnly: "网关设置当前不可用（读不到配置路由）。",
-				saveFailed: "保存未生效，请检查输入后重试。",
-				loadFailed: "加载网关配置失败。",
-				emptyMeansClear: "留空 = 使用默认",
-				running: "运行中",
-				stopped: "已停止",
-				tls: "TLS",
-				lastError: "上次错误",
-				"field.enabled": "启用网关",
-				"hint.enabled": "启动时监听 0.0.0.0 网关端口",
-				"field.gatewayPort": "网关端口",
-				"hint.gatewayPort": "绑定到 0.0.0.0 的监听端口（默认 3081）",
-				"field.dshTargetPort": "dsh 目标端口",
-				"hint.dshTargetPort": "留空则自动跟随 dsh web 端口（默认 3080）",
-				"field.lanCidrs": "免密 LAN 网段",
-				"hint.lanCidrs": "逗号分隔的 CIDR，如 10.0.0.0/8, 192.168.0.0/16",
-				"field.lanPasswordless": "LAN 免登录",
-				"hint.lanPasswordless": "LAN/回环来源跳过网关登录页，但仍共用同一上游会话（需 dsh ≥ 0.1.2）",
-				"field.allowInsecurePlaintext": "允许明文 HTTP",
-				"hint.allowInsecurePlaintext": "危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输",
-				"field.trustedTerminator": "受信 TLS 终止代理",
-				"hint.trustedTerminator": "可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明",
-				"field.secureCookies": "会话 cookie 的 Secure 属性",
-				"hint.secureCookies": "自动 = TLS 或已声明受信终止代理时加 Secure。受信代理只做明文鉴权、浏览器走 http 访问时须设为 false，否则浏览器拒收 Secure cookie，登录会无限弹回登录页",
-				"opt.auto": "自动",
-				"opt.true": "始终 Secure",
-				"opt.false": "不加 Secure（明文浏览器入口）",
-				"field.cookieMaxAgeDays": "会话有效期（天）",
-				"hint.cookieMaxAgeDays": "登录 cookie 的存活天数（默认 7）",
-				"field.tlsEnabled": "启用 TLS（HTTPS）",
-				"hint.tlsEnabled": "以 HTTPS 提供网关服务",
-				"field.tlsMode": "证书来源",
-				"hint.tlsMode": "self-signed = 自动生成自签名证书；custom = 使用自己的证书",
-				"field.tlsSelfSignedHosts": "自签名证书域名/IP",
-				"hint.tlsSelfSignedHosts": "逗号分隔，写入证书 SAN，如 localhost, 192.168.1.5",
-				"field.tlsCertPath": "证书文件路径（custom）",
-				"hint.tlsCertPath": "PEM 格式证书（或证书链）的绝对路径",
-				"field.tlsKeyPath": "私钥文件路径（custom）",
-				"hint.tlsKeyPath": "与证书配套的 PEM 私钥绝对路径",
-				"field.tlsCertMaxAgeDays": "自签名证书有效期（天）",
-				"hint.tlsCertMaxAgeDays": "默认 825（约 27 个月）"
-			},
-			en: {
-				title: "LAN Gateway",
-				description: "Remote-access switch, port, TLS certificate, trusted CIDRs and more",
-				unsaved: "Unsaved",
-				save: "Save",
-				saving: "Saving…",
-				discard: "Discard",
-				reset: "Reset",
-				overridden: "overridden",
-				readOnly: "Gateway settings unavailable (config route unreachable).",
-				saveFailed: "The save did not land — check the inputs and retry.",
-				loadFailed: "Failed to load gateway configuration.",
-				emptyMeansClear: "Empty = default",
-				running: "Running",
-				stopped: "Stopped",
-				tls: "TLS",
-				lastError: "Last error",
-				"field.enabled": "Enable gateway",
-				"hint.enabled": "Listen on the gateway port at boot",
-				"field.gatewayPort": "Gateway port",
-				"hint.gatewayPort": "Port bound on 0.0.0.0 (default 3081)",
-				"field.dshTargetPort": "dsh target port",
-				"hint.dshTargetPort": "Leave empty to follow the dsh web port (default 3080)",
-				"field.lanCidrs": "Password-free LAN CIDRs",
-				"hint.lanCidrs": "Comma separated CIDRs, e.g. 10.0.0.0/8, 192.168.0.0/16",
-				"field.lanPasswordless": "LAN skip login",
-				"hint.lanPasswordless": "LAN/loopback sources skip the gateway login page but still ride one shared upstream session (needs dsh >= 0.1.2)",
-				"field.allowInsecurePlaintext": "Allow plaintext HTTP",
-				"hint.allowInsecurePlaintext": "Dangerous: start the listener even without TLS or a trusted terminator; passwords and sessions travel in clear",
-				"field.trustedTerminator": "Trusted TLS terminator",
-				"hint.trustedTerminator": "Optional identifier for a front proxy (e.g. nginx) treated as the encrypted ingress. Empty = none declared",
-				"field.secureCookies": "Session cookie Secure attribute",
-				"hint.secureCookies": "Auto = Secure when TLS or a trusted terminator is declared. Set false when the trusted proxy only authenticates over plaintext and browsers reach it over http — otherwise browsers drop the Secure cookie and every login bounces back to the login page",
-				"opt.auto": "Auto",
-				"opt.true": "Always Secure",
-				"opt.false": "No Secure (plaintext browser ingress)",
-				"field.cookieMaxAgeDays": "Session lifetime (days)",
-				"hint.cookieMaxAgeDays": "Login cookie lifetime (default 7)",
-				"field.tlsEnabled": "Enable TLS (HTTPS)",
-				"hint.tlsEnabled": "Serve the gateway over HTTPS",
-				"field.tlsMode": "Certificate source",
-				"hint.tlsMode": "self-signed = auto-generated certificate; custom = your own files",
-				"field.tlsSelfSignedHosts": "Self-signed hosts (SANs)",
-				"hint.tlsSelfSignedHosts": "Comma separated DNS/IP names, e.g. localhost, 192.168.1.5",
-				"field.tlsCertPath": "Certificate path (custom)",
-				"hint.tlsCertPath": "Absolute path to a PEM certificate (or chain)",
-				"field.tlsKeyPath": "Private key path (custom)",
-				"hint.tlsKeyPath": "Absolute path to the matching PEM private key",
-				"field.tlsCertMaxAgeDays": "Self-signed validity (days)",
-				"hint.tlsCertMaxAgeDays": "Default 825 (about 27 months)"
-			}
-		};
-		function labels() {
-			return (typeof navigator !== "undefined" ? navigator.language : "en").toLowerCase().startsWith("zh") ? LABELS.zh : LABELS.en;
-		}
+		//#region src/config-fields.ts
 		/** The three states of a tri-state field, in display order. */
 		const TRISTATE_OPTIONS = [
 			"auto",
 			"true",
 			"false"
 		];
+		/**
+		* The editable settings, in display order. Adding a config key means adding it
+		* here (the host whitelist and the card's controls both follow), to the
+		* `Config` schema in `index.ts`, and to `listenerKey` when it changes listener
+		* behavior.
+		*/
 		const FIELDS = [
 			{
 				field: "enabled",
@@ -198,6 +86,9 @@ window.__ModuleLoader__.load({
 				kind: "tristate"
 			}
 		];
+		new Set(FIELDS.map((def) => def.field));
+		new Set(FIELDS.filter((def) => def.optional === true).map((def) => def.field));
+		/** Render a stored value as draft text. */
 		function formatValue(def, value) {
 			switch (def.kind) {
 				case "boolean": return value === true ? "true" : "false";
@@ -257,6 +148,124 @@ window.__ModuleLoader__.load({
 				};
 			}
 		}
+		//#endregion
+		//#region src/client/lan-gateway-card.tsx
+		/**
+		* The lan-gateway settings card shown in the official DSH Settings → Plugins
+		* page (the `settings.plugin.item` slot).
+		*
+		* ModLens-style: the card carries NO injected services. It reads and writes
+		* the loopback-only `/lan-gateway/config` host route (the browser never sees
+		* the settings seam or any secret), so the client bundle's only dependency is
+		* the `slots` service that every plugin already has.
+		*
+		* @module @riceawa/dsh-lan-gateway/client/card
+		*/
+		const LABELS = {
+			zh: {
+				title: "LAN 网关",
+				description: "远程访问开关、端口、TLS 证书、受信网段等网关设置",
+				unsaved: "未保存",
+				save: "保存",
+				saving: "保存中…",
+				discard: "放弃",
+				reset: "重置",
+				readOnly: "网关设置只能在宿主机本机打开 dsh web 时修改：配置路由仅监听回环地址，经网关远程访问的浏览器会被拒绝。远程请改用 lan_gateway 工具。",
+				saveFailed: "保存未生效，请检查输入后重试。",
+				loadFailed: "无法读取网关配置",
+				emptyMeansClear: "留空 = 使用默认",
+				running: "运行中",
+				stopped: "已停止",
+				tls: "TLS",
+				lastError: "上次错误",
+				"field.enabled": "启用网关",
+				"hint.enabled": "启动时监听 0.0.0.0 网关端口",
+				"field.gatewayPort": "网关端口",
+				"hint.gatewayPort": "绑定到 0.0.0.0 的监听端口（默认 3081）",
+				"field.dshTargetPort": "dsh 目标端口",
+				"hint.dshTargetPort": "留空则自动跟随 dsh web 端口（默认 3080）",
+				"field.lanCidrs": "免密 LAN 网段",
+				"hint.lanCidrs": "逗号分隔的 CIDR，如 10.0.0.0/8, 192.168.0.0/16",
+				"field.lanPasswordless": "LAN 免登录",
+				"hint.lanPasswordless": "LAN/回环来源跳过网关登录页，但仍共用同一上游会话（需 dsh ≥ 0.1.2）",
+				"field.allowInsecurePlaintext": "允许明文 HTTP",
+				"hint.allowInsecurePlaintext": "危险：关闭 TLS 或受信终止代理时仍启动监听，密码与会话将以明文传输",
+				"field.trustedTerminator": "受信 TLS 终止代理",
+				"hint.trustedTerminator": "可选：声明前置代理标识，视为加密入口（如 nginx）。留空 = 未声明。注意：登录限流以 TCP 源地址为键，代理之后所有浏览器共用一个额度（5 次/分钟）",
+				"field.secureCookies": "会话 cookie 的 Secure 属性",
+				"hint.secureCookies": "自动 = TLS 或已声明受信终止代理时加 Secure。受信代理只做明文鉴权、浏览器走 http 访问时须设为 false，否则浏览器拒收 Secure cookie，登录会无限弹回登录页",
+				"opt.auto": "自动",
+				"opt.true": "始终 Secure",
+				"opt.false": "不加 Secure（明文浏览器入口）",
+				"field.cookieMaxAgeDays": "会话有效期（天）",
+				"hint.cookieMaxAgeDays": "登录 cookie 的存活天数（默认 7）",
+				"field.tlsEnabled": "启用 TLS（HTTPS）",
+				"hint.tlsEnabled": "以 HTTPS 提供网关服务",
+				"field.tlsMode": "证书来源",
+				"hint.tlsMode": "self-signed = 自动生成自签名证书；custom = 使用自己的证书",
+				"field.tlsSelfSignedHosts": "自签名证书域名/IP",
+				"hint.tlsSelfSignedHosts": "逗号分隔，写入证书 SAN，如 localhost, 192.168.1.5。仅影响下次换发：已有证书沿用至到期，改动不会立刻生效",
+				"field.tlsCertPath": "证书文件路径（custom）",
+				"hint.tlsCertPath": "PEM 格式证书（或证书链）的绝对路径",
+				"field.tlsKeyPath": "私钥文件路径（custom）",
+				"hint.tlsKeyPath": "与证书配套的 PEM 私钥绝对路径",
+				"field.tlsCertMaxAgeDays": "自签名证书有效期（天）",
+				"hint.tlsCertMaxAgeDays": "默认 825（约 27 个月）。仅影响下次换发：已有证书沿用至到期"
+			},
+			en: {
+				title: "LAN Gateway",
+				description: "Remote-access switch, port, TLS certificate, trusted CIDRs and more",
+				unsaved: "Unsaved",
+				save: "Save",
+				saving: "Saving…",
+				discard: "Discard",
+				reset: "Reset",
+				readOnly: "Gateway settings can only be changed where dsh web runs locally: the config route listens on loopback only, so a browser reaching dsh through the gateway is refused. Use the lan_gateway tool remotely.",
+				saveFailed: "The save did not land — check the inputs and retry.",
+				loadFailed: "Cannot read the gateway configuration",
+				emptyMeansClear: "Empty = default",
+				running: "Running",
+				stopped: "Stopped",
+				tls: "TLS",
+				lastError: "Last error",
+				"field.enabled": "Enable gateway",
+				"hint.enabled": "Listen on the gateway port at boot",
+				"field.gatewayPort": "Gateway port",
+				"hint.gatewayPort": "Port bound on 0.0.0.0 (default 3081)",
+				"field.dshTargetPort": "dsh target port",
+				"hint.dshTargetPort": "Leave empty to follow the dsh web port (default 3080)",
+				"field.lanCidrs": "Password-free LAN CIDRs",
+				"hint.lanCidrs": "Comma separated CIDRs, e.g. 10.0.0.0/8, 192.168.0.0/16",
+				"field.lanPasswordless": "LAN skip login",
+				"hint.lanPasswordless": "LAN/loopback sources skip the gateway login page but still ride one shared upstream session (needs dsh >= 0.1.2)",
+				"field.allowInsecurePlaintext": "Allow plaintext HTTP",
+				"hint.allowInsecurePlaintext": "Dangerous: start the listener even without TLS or a trusted terminator; passwords and sessions travel in clear",
+				"field.trustedTerminator": "Trusted TLS terminator",
+				"hint.trustedTerminator": "Optional identifier for a front proxy (e.g. nginx) treated as the encrypted ingress. Empty = none declared. Note: login rate limiting keys on the TCP source address, so behind a proxy every browser shares one budget (5/min)",
+				"field.secureCookies": "Session cookie Secure attribute",
+				"hint.secureCookies": "Auto = Secure when TLS or a trusted terminator is declared. Set false when the trusted proxy only authenticates over plaintext and browsers reach it over http — otherwise browsers drop the Secure cookie and every login bounces back to the login page",
+				"opt.auto": "Auto",
+				"opt.true": "Always Secure",
+				"opt.false": "No Secure (plaintext browser ingress)",
+				"field.cookieMaxAgeDays": "Session lifetime (days)",
+				"hint.cookieMaxAgeDays": "Login cookie lifetime (default 7)",
+				"field.tlsEnabled": "Enable TLS (HTTPS)",
+				"hint.tlsEnabled": "Serve the gateway over HTTPS",
+				"field.tlsMode": "Certificate source",
+				"hint.tlsMode": "self-signed = auto-generated certificate; custom = your own files",
+				"field.tlsSelfSignedHosts": "Self-signed hosts (SANs)",
+				"hint.tlsSelfSignedHosts": "Comma separated DNS/IP names, e.g. localhost, 192.168.1.5. Applies to the next issuance only: an existing certificate is reused until it expires",
+				"field.tlsCertPath": "Certificate path (custom)",
+				"hint.tlsCertPath": "Absolute path to a PEM certificate (or chain)",
+				"field.tlsKeyPath": "Private key path (custom)",
+				"hint.tlsKeyPath": "Absolute path to the matching PEM private key",
+				"field.tlsCertMaxAgeDays": "Self-signed validity (days)",
+				"hint.tlsCertMaxAgeDays": "Default 825 (about 27 months). Applies to the next issuance only: an existing certificate is reused until it expires"
+			}
+		};
+		function labels() {
+			return (typeof navigator !== "undefined" ? navigator.language : "en").toLowerCase().startsWith("zh") ? LABELS.zh : LABELS.en;
+		}
 		/**
 		* Render the LAN gateway card. Self-loading: fetches the config route on
 		* mount, posts the edited config on save.
@@ -284,7 +293,28 @@ window.__ModuleLoader__.load({
 					cancelled = true;
 				};
 			}, []);
-			if (loadFailed) return null;
+			if (loadFailed) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
+				style: styles.card,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					style: styles.header,
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						style: styles.headerTop,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							style: styles.name,
+							children: t.title
+						})
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						style: styles.description,
+						children: t.loadFailed
+					})]
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					style: styles.body,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						style: styles.hint,
+						children: t.readOnly
+					})
+				})]
+			});
 			if (route === null) return null;
 			const { config } = route;
 			const draftOf = (field) => drafts[field] ?? formatValue(FIELDS.find((f) => f.field === field), config[field]);
@@ -316,16 +346,18 @@ window.__ModuleLoader__.load({
 				setSaving(true);
 				setFailed(null);
 				try {
-					const next = {};
-					for (const def of FIELDS) {
-						const write = parseValue(def, drafts[def.field] ?? formatValue(def, config[def.field]));
+					const patch = {};
+					for (const [field, text] of Object.entries(drafts)) {
+						const def = FIELDS.find((f) => f.field === field);
+						if (def === void 0) continue;
+						const write = parseValue(def, text ?? "");
 						if (write === void 0) continue;
-						next[def.field] = write.kind === "clear" ? null : write.value;
+						patch[field] = write.kind === "clear" ? null : write.value;
 					}
 					const response = await fetch("/lan-gateway/config", {
 						method: "POST",
 						headers: { "content-type": "application/json" },
-						body: JSON.stringify(next)
+						body: JSON.stringify(patch)
 					});
 					const body = await response.json().catch(() => ({}));
 					if (!response.ok) {