@riceawa/dsh-lan-gateway 0.5.4 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 
 <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.4-2b7fff?style=flat-square" alt="version 0.5.4" />
+  <img src="https://img.shields.io/badge/version-0.6.0-2b7fff?style=flat-square" alt="version 0.6.0" />
   <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>
@@ -14,7 +14,7 @@
 
 `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.7（本插件按该版本的 settings API 写入配置；含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自身的授权仍然把关每个请求，网关只决定谁可以使用这条会话。
 
 插件另外提供两项功能：
 
@@ -70,7 +70,7 @@ lan_gateway disable           # 关闭
 
 ## 配置
 
-所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片即可修改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
+所有可调项都写在本插件自己的 profile 条目里（dsh ≥ 0.1.7 起，设置写入按**条目 id** 寻址；此前的 `lan-gateway` 用户设置命名空间已随 `settingsScope` 一起移除）。打开侧边栏的 **Plugins** 页，在官方插件列表里点开「LAN 网关」卡片即可修改，保存即生效，监听器会按新配置自动重启。卡片挂在 Plugins 页的 `plugins.item` 槽上，且只在底座确实 served 本插件条目时注册——没有 Loader 条目（写入必然 409）时卡片不会出现。下表既是卡片字段，也是配置键：
 
 | 键 | 默认值 | 说明 |
 | --- | --- | --- |
@@ -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` | 自签名证书有效期（天），见下「证书有效期」 |
 | `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。
@@ -131,7 +131,7 @@ 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`，它会换掉密钥并热重启监听器。已到期的证书在启动时自动换发并记一条 warning。
+自签名证书在首次启用 TLS 时生成一次，写入 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。更换证书使用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。已到期的证书在启动时自动换发并记一条 warning。修改 `tlsSelfSignedHosts` 或 `tlsCertMaxAgeDays` 只影响**下次换发**：已有证书沿用至到期，不会在保存时被悄悄替换。
 
 ### 证书有效期
 
@@ -158,13 +158,19 @@ lan_gateway disable           # 关闭
 
 `lan_gateway status` 会如实报告实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
 
+### 登录限流
+
+登录尝试以 TCP 源地址为键限流，每分钟 5 次。`X-Forwarded-For` 与 `Forwarded` 在转发前一律删除，也不参与限流取键——它们可由客户端任意伪造，用它们作为键等于把限流关掉。
+
+代价是声明 `trustedTerminator` 之后，所有浏览器请求都来自代理这一个地址，5 次/分钟变成**整个部署共享**的额度，而非每客户端 5 次。这一耦合没有便宜的修法：要么接受它（把上限视为抗暴力破解的下限而非每用户配额），要么让代理直连、由网关自己面对客户端。当前不接受按 `X-Forwarded-For` 分桶。
+
 注意 `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 的来源跳过网关自己的登录页；受支持的底座（dsh ≥ 0.1.7）上游会话仍把关每个请求。底座没有浏览器会话认证时这个开关拒绝启用，否则等同于把 QVD-2026-57410 原样恢复。
+- **共享上游会话中继**（dsh ≥ 0.1.7）。dsh 不再信任回环 Host，要求出示 HMAC 签名的 `dsh-auth-*` cookie。插件经 `connection` 服务拿到启动令牌，在回环传输上做一次浏览器等价的令牌换取，取得 cookie 后中继到每个转发请求；上游一旦 401 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的用户共用同一条上游会话，持钥的上游才是真正的授权主体。
 - **登录页**。`/__login` 由网关独占、不转发。密码以 scrypt 校验，每写一次重新加盐；登录尝试按来源限流（5 次 / 分钟）。
 - **会话 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` 工具。
@@ -193,17 +199,23 @@ pnpm typecheck   # tsc 双端（host + client）
 ```
 
 ```
-✓ tests/gateway.test.ts               (40) 分类 / HMAC cookie / epoch / 逐会话撤销 / 密码状态 / 限流
-✓ tests/start-guard.test.ts           (19) fail-closed 启动守卫 / 配置路由回环围栏 /
-                                           Secure cookie 属性推断（含 null 清除路径）
-✓ 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                   ( 9) 证书持久化 / 到期换发 / 重生成 / 自定义证书加载
-✓ tests/upstream-session.test.ts      ( 8) 真实回环令牌换取：cookie 名匹配 / 拒绝后重换 /
-                                           invalidate 重获取 / 日志播报 / 保住已持有会话
-✓ tests/settings-card.test.ts         ( 6) 设置页字段编解码：三态 auto ↔ false 不可混淆
+✓ tests/gateway.test.ts                        (40) 分类 / HMAC cookie / epoch / 逐会话撤销 / 密码状态 / 限流
+✓ tests/start-guard.test.ts                    (19) fail-closed 启动守卫 / 配置路由回环围栏 /
+                                                    Secure cookie 属性推断（含 null 清除路径）
+✓ tests/request-policy.test.ts                 (46) 判定缝纯函数：路径归一化 / 归属前缀 / 同站与登录围栏 /
+                                                    两个方向的头部变换
+✓ tests/upstream-session.test.ts               ( 8) 真实回环令牌换取：cookie 名匹配 / 拒绝后重换 /
+                                                    invalidate 重获取 / 日志播报 / 保住已持有会话
+✓ tests/x509.test.ts                           ( 6) 自签名证书 DER/SAN/签名/TLS 握手
+✓ tests/tls.test.ts                            ( 9) 证书持久化 / 到期换发 / 重生成 / 自定义证书加载
+✓ tests/uuid-shim.test.ts                      ( 3) 不安全源补丁 / 安全源 no-op / v4 正确性
+✓ tests/settings-card.test.ts                  (10) 设置页字段编解码（三态 auto ↔ false 不可混淆）/
+                                                    卡片注册槽与条目 id 契约
+✓ tests/integration/gateway.test.ts            (26) 真实网关端到端：全来源登录 / LAN 豁免 / 跨站 403 / 升级拒绝 /
+                                                    cookie 属性 / epoch 撤销 / 逐会话登出 / 尾斜杠 / IPv6 / 会话中继
+✓ tests/integration/management-plane.test.ts   (15) 真实 apply()：工具与卡片交替启停 / 未编辑字段与未知键保留 /
+                                                    清空后继承 / 拒绝不可启动配置
+✓ tests/integration/session-races.test.ts      ( 8) 改密落在登录与握手途中的竞态 / 上游非 101 应答
 ```
 
 ### 发布
@@ -227,8 +239,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.4 -m "…" && git push origin v0.5.4
-gh release create v0.5.4 --generate-notes ./*.tgz # 可选：Release + tgz 附件
+git tag -a v0.6.0 -m "…" && git push origin v0.6.0
+gh release create v0.6.0 --generate-notes ./*.tgz # 可选：Release + tgz 附件
 ```
 
 ## 安全评估
@@ -240,6 +252,10 @@ gh release create v0.5.4 --generate-notes ./*.tgz # 可选：Release + tgz 附
 - [上游研究](docs/security/qvd-2026-57410-research.md)：公开通告、上游提交与版本核对。
 - [0.5.4 复审与修复清单](docs/security/audit-2026-09-19-fix-list.md)：0.5.3 的实现细节复审（G1–G12）与修复记录。
 
+架构层面的复审另见 [docs/review/](docs/review/)：
+
+- [架构复审（2026-09-19）](docs/review/architecture-review-2026-09-19.md)：针对 0.5.4 的 C1–C6 结构候选与 D1–D14 缺陷清单，0.5.5 已全部关闭。文档记录的是复审当时的状态，不是待办列表。
+
 ## 许可
 
 [MIT](./LICENSE)

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,13 +148,143 @@ window.__ModuleLoader__.load({
 				};
 			}
 		}
+		//#endregion
+		//#region src/client/lan-gateway-card.tsx
+		/**
+		* The lan-gateway settings card, rendered by the official DSH Plugins page
+		* through its `plugins.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 only platform service it needs is
+		* the `slots` service 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;
+		}
+		/**
+		* The card's title in the browser's language, for the Plugins page's list
+		* entry. A thunk so the label follows the page's locale without re-registering.
+		* @returns the localized card title.
+		*/
+		function cardTitle() {
+			return labels().title;
+		}
 		/**
 		* Render the LAN gateway card. Self-loading: fetches the config route on
 		* mount, posts the edited config on save.
-		* @param _props - unused; the card needs no injected face.
-		* @returns the card, or nothing while the route is unreachable.
+		*
+		* `view` swaps between the card's one-liner and its page body, so the branch
+		* sits after the hooks: the Plugins page re-renders one contribution under the
+		* other view when the card is opened.
+		* @param props - the view the Plugins page is asking for.
+		* @returns the one-liner, the card, or nothing while the route is unreachable.
 		*/
-		function LanGatewayCard(_props) {
+		function LanGatewayCard(props) {
 			const t = labels();
 			const [open, setOpen] = (0, react.useState)(false);
 			const [route, setRoute] = (0, react.useState)(null);
@@ -284,7 +305,29 @@ window.__ModuleLoader__.load({
 					cancelled = true;
 				};
 			}, []);
-			if (loadFailed) return null;
+			if (props.view === "summary") return t.description;
+			if (loadFailed) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				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 +359,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) {
@@ -442,7 +487,7 @@ window.__ModuleLoader__.load({
 				}
 			};
 			const statusLine = `${route.running ? t.running : t.stopped} · ${t.tls}: ${route.tls} · :${route.port}`;
-			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: open ? {
 					...styles.card,
 					...styles.cardOpen
@@ -725,10 +770,9 @@ window.__ModuleLoader__.load({
 		*    installs a getRandomValues-backed `randomUUID` on the Crypto prototype at
 		*    module scope. With TLS enabled the origin is secure and the shim is a
 		*    no-op.
-		* 2. Settings card: registers the LAN gateway card into the official
-		*    Settings → Plugins page (`settings.plugin.item` slot), editing the
-		*    `lan-gateway` settings namespace so port, CIDRs, auth, and TLS are
-		*    adjustable from the GUI.
+		* 2. Settings card: registers the LAN gateway card into the official Plugins
+		*    page (`plugins.item` slot) so port, CIDRs, auth, and TLS stay adjustable
+		*    from the GUI.
 		*/
 		/** RFC 4122 v4 UUID from crypto.getRandomValues (available on insecure origins). */
 		function uuidFromRandomValues() {
@@ -771,25 +815,25 @@ window.__ModuleLoader__.load({
 		}
 		installRandomUuidShim();
 		const name = "dsh-lan-gateway";
-		/** Only the slots service: the card itself is self-loading (ModLens-style). */
-		const inject = ["slots"];
+		/**
+		* The profile entry id this plugin's bundle patch composes it under, and the
+		* settings namespace dsh ≥ 0.1.7 addresses every write by.
+		*/
+		const ENTRY_ID = "dsh-lan-gateway";
+		/** The slots service the card rides, and the settings mirror the gate reads. */
+		const inject = ["slots", "configForms"];
 		/**
 		* Mount the settings card and the UUID shim.
 		* @param ctx - the browser plugin context.
 		*/
 		function apply(ctx) {
 			installRandomUuidShim();
-			const legacyListOptions = {
-				id: "lan-gateway",
-				order: 30
-			};
-			ctx.slots.inject("settings.plugin.item", function* () {
-				yield ctx.slots.register({
-					name: "settings.plugin.item",
-					key: "lan-gateway",
-					...legacyListOptions
-				}, LanGatewayCard);
-			});
+			ctx.effect(() => ctx.configForms.whileServed([ENTRY_ID], () => ctx.slots.inject("plugins.item", () => ctx.slots.register({
+				name: "plugins.item",
+				id: ENTRY_ID,
+				order: 30,
+				label: () => cardTitle()
+			}, LanGatewayCard))));
 		}
 		//#endregion
 		exports.apply = apply;