@riceawa/dsh-lan-gateway 0.5.3 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +47 -40
  2. package/lib/index.d.ts +13 -2
  3. package/lib/index.js +375 -74
  4. package/package.json +1 -1
  5. package/skills/lan-gateway.md +8 -4
  6. package/src/auth.ts +98 -26
  7. package/src/gateway.ts +238 -28
  8. package/src/index.ts +42 -13
  9. package/src/state.ts +77 -7
  10. package/src/tls.ts +33 -0
  11. package/src/upstream-session.ts +17 -2
package/README.md CHANGED
@@ -6,35 +6,35 @@
6
6
 
7
7
  <p align="center">
8
8
  <img src="https://img.shields.io/badge/DeepSeek%20Harness-4d6bfe?logo=deepseek&logoColor=fff&style=flat-square" alt="DeepSeek Harness" />
9
- <img src="https://img.shields.io/badge/version-0.5.3-2b7fff?style=flat-square" alt="version 0.5.3" />
9
+ <img src="https://img.shields.io/badge/version-0.5.4-2b7fff?style=flat-square" alt="version 0.5.4" />
10
10
  <img src="https://img.shields.io/badge/TLS-8b5cf6?logo=lock&logoColor=fff&style=flat-square" alt="TLS" />
11
11
  <img src="https://img.shields.io/github/license/rice-awa/dsh-lan-gateway?style=flat-square" alt="MIT license" />
12
12
  <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="awesome · DSH plugin" /></a>
13
13
  </p>
14
14
 
15
- `dsh web` 硬拒绝 `--host 0.0.0.0`，怕把远程代码执行暴露到网络。这个插件的做法是让 dsh 继续只绑 `127.0.0.1`，另起一个监听 `0.0.0.0` 的反向代理，转发到 loopback 端口并改写 `Host` / `Origin`。
15
+ `dsh web` 明确拒绝 `--host 0.0.0.0`，以免把远程代码执行暴露到网络。本插件的做法是让 dsh 继续只绑 `127.0.0.1`，另起一个反向代理监听未指定地址（双栈，IPv4 与 IPv6 客户端都可接入），转发到 loopback 端口并改写 `Host` / `Origin`。
16
16
 
17
- 默认拒绝：loopback、LAN、公网三种来源都要先在网关登录页拿到 HMAC 会话 cookie，LAN 免密需要显式打开 `lanPasswordless`，默认关闭。底座是 dsh ≥ 0.1.2-rc.1 时（含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自己的授权仍然把关每个请求，网关只决定谁能骑上这条会话。
17
+ 默认拒绝：loopback、LAN、公网三种来源都要先在网关登录页取得 HMAC 会话 cookie，LAN 免密需要显式打开 `lanPasswordless`，默认关闭。底座为 dsh ≥ 0.1.2-rc.1 时（含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自身的授权仍然把关每个请求，网关只决定谁可以使用这条会话。
18
18
 
19
- 插件还捎带两件事：
19
+ 插件另外提供两项功能：
20
20
 
21
- - **不安全源 UUID shim**：网关以纯 HTTP 的局域网地址服务页面，浏览器视其为不安全源，不提供 `crypto.randomUUID`。client bundle 在页面加载早期补一个基于 `getRandomValues` 的实现，工作区才打得开。
22
- - **TLS**：自动生成并持久化的自签名证书，或者挂载你自己签发的 PEM。自签名证书首次访问会有浏览器警告，正常现象。
21
+ - **不安全源 UUID shim**：网关以纯 HTTP 的局域网地址服务页面，浏览器视其为不安全源，不提供 `crypto.randomUUID`。client bundle 在页面加载早期补一个基于 `getRandomValues` 的实现，工作区才能正常打开。
22
+ - **TLS**：自动生成并持久化的自签名证书，或者挂载自行签发的 PEM。自签名证书首次访问会有浏览器警告，属预期行为。
23
23
 
24
24
  ## 安装
25
25
 
26
- 已发布到 npm，装的是预构建产物，不需要 `allowBuilds` 授权。把这段话丢给你的 agent 就行：
26
+ 已发布到 npm，安装的是预构建产物，不需要 `allowBuilds` 授权。可将下面这段话交给你的 agent：
27
27
 
28
28
  > 帮我安装 dsh 插件 `@riceawa/dsh-lan-gateway`，遵循
29
29
  > `https://github.com/rice-awa/dsh-lan-gateway/blob/main/INSTALL.md`
30
30
 
31
- 也可以自己敲：
31
+ 也可以手动执行：
32
32
 
33
33
  ```bash
34
34
  dsh plugin --profile web add @riceawa/dsh-lan-gateway
35
35
  ```
36
36
 
37
- `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完整安装流程)。
37
+ `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完整安装流程)。
38
38
 
39
39
  从源码构建：
40
40
 
@@ -44,12 +44,12 @@ cd dsh-lan-gateway
44
44
  pnpm install
45
45
  pnpm build # host → lib/index.js
46
46
  pnpm build:client # client → lib/client.js
47
- pnpm test # 93 项
47
+ pnpm test # 117 项
48
48
  ```
49
49
 
50
- 仓库里还有一个 [lan-gateway](skills/lan-gateway.md) 技能，装上之后可以直接在 dsh 对话里说「设置网关密码为 …」「开启远程访问」，agent 会调用 `lan_gateway` 工具完成，密码以参数传入，不写配置也不回显。安装方式见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
50
+ 仓库里还有一个 [lan-gateway](skills/lan-gateway.md) 技能，安装后可直接在 dsh 对话里说「设置网关密码为 …」「开启远程访问」，agent 会调用 `lan_gateway` 工具完成，密码以参数传入，不写入配置，也不回显。安装方式见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
51
51
 
52
- 手机 / 平板上访问的话，再搭一个 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) 做移动端 UI 适配：
52
+ 如需在手机 / 平板上访问，可另外安装 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) 做移动端 UI 适配：
53
53
 
54
54
  ```bash
55
55
  dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
@@ -59,23 +59,23 @@ dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
59
59
 
60
60
  ```bash
61
61
  lan_gateway enable # 开启网关（需先满足启动条件，否则给出迁移文案）
62
- lan_gateway status # 端口 / 目标 / 密码 / 会话 epoch / 中继状态 / 入口加密方式 / 上次错误
62
+ lan_gateway status # 端口 / 目标 / 密码 / 会话 epoch / 已登出会话数 / 中继状态 / 入口加密方式 / 上次错误
63
63
  lan_gateway set-password # 设置登录密码（≥8 位，改动会让所有已签发会话立即失效）
64
64
  lan_gateway rotate-secret # 轮换会话密钥，作废全部登录 cookie 与已建立的 WebSocket
65
65
  lan_gateway tls-regenerate # 换发自签名证书（tlsMode=self-signed 时）
66
66
  lan_gateway disable # 关闭
67
67
  ```
68
68
 
69
- `lan_gateway` 是模型可调用的工具，上面这些命令不必自己敲。直接在对话里说「查看网关状态」「设置网关密码为 ……」即可，密码以参数传给模型，不会落进任何配置文件。
69
+ `lan_gateway` 是模型可调用的工具，上述命令无需手动执行。直接在对话里说「查看网关状态」「设置网关密码为 ……」即可，密码以参数传给模型，不会写入任何配置文件。
70
70
 
71
71
  ## 配置
72
72
 
73
- 所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片就能改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
73
+ 所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片即可修改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
74
74
 
75
75
  | 键 | 默认值 | 说明 |
76
76
  | --- | --- | --- |
77
77
  | `enabled` | `false` | 是否在启动时监听网络端口 |
78
- | `gatewayPort` | `3081` | 网关监听端口（`0.0.0.0`） |
78
+ | `gatewayPort` | `3081` | 网关监听端口（未指定地址 / 双栈） |
79
79
  | `dshTargetPort` | 跟随 `ctx.webServer.port` | 转发到的 dsh loopback 端口 |
80
80
  | `lanCidrs` | RFC1918 + link-local（见下） | 视为 LAN 的网段，仅在 `lanPasswordless` 开启时用作豁免匹配集 |
81
81
  | `lanPasswordless` | `false` | LAN/loopback 来源跳过网关登录页（上游会话中继仍把关） |
@@ -86,7 +86,7 @@ lan_gateway disable # 关闭
86
86
  | `tlsSelfSignedHosts` | `localhost` | 自签名证书的 SAN（逗号分隔的域名 / IP） |
87
87
  | `tlsCertPath` | — | `custom` 模式：PEM 证书（或证书链）绝对路径 |
88
88
  | `tlsKeyPath` | — | `custom` 模式：PEM 私钥绝对路径 |
89
- | `tlsCertMaxAgeDays` | `825` | 自签名证书有效期（天） |
89
+ | `tlsCertMaxAgeDays` | `825` | 自签名证书有效期（天），见下「证书有效期」 |
90
90
  | `allowInsecurePlaintext` | `false` | 允许明文 HTTP 监听（见下「入口加密」） |
91
91
  | `trustedTerminator` | — | 声明一个受信 TLS 终止代理标识，视为加密入口（如 `nginx`） |
92
92
  | `secureCookies` | 自动 | 会话 cookie 的 `Secure` 属性显式开关，默认按 `tlsEnabled` 或 `trustedTerminator` 推断（见下） |
@@ -97,9 +97,9 @@ lan_gateway disable # 关闭
97
97
 
98
98
  ### 入口加密
99
99
 
100
- 网关默认拒绝纯明文监听，下面三条路任选一条才能启动：
100
+ 网关默认拒绝纯明文监听，以下三种方式任选其一方可启动：
101
101
 
102
- 1. 启用 TLS，`tlsEnabled: true`。推荐，自签名或 custom 证书都行。
102
+ 1. 启用 TLS，`tlsEnabled: true`。推荐，自签名或 custom 证书均可。
103
103
  2. 声明由可信反向代理终止 TLS：
104
104
 
105
105
  ```yaml
@@ -120,7 +120,7 @@ lan_gateway disable # 关闭
120
120
  allowInsecurePlaintext: true
121
121
  ```
122
122
 
123
- 用自己的证书（比如 Let's Encrypt 签发的 PEM）：
123
+ 使用自有证书（例如 Let's Encrypt 签发的 PEM）：
124
124
 
125
125
  ```yaml
126
126
  - id: dsh-lan-gateway
@@ -131,15 +131,21 @@ lan_gateway disable # 关闭
131
131
  tlsKeyPath: /etc/letsencrypt/live/example.com/privkey.pem
132
132
  ```
133
133
 
134
- 自签名证书在首次启用 TLS 时生成一次，落到 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。要换新证书用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。
134
+ 自签名证书在首次启用 TLS 时生成一次，写入 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。更换证书使用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。已到期的证书在启动时自动换发并记一条 warning。
135
+
136
+ ### 证书有效期
137
+
138
+ 默认有效期 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)），默认值取在该上限之内。
139
+
140
+ 自签证书要么被点击通过、要么被手工信任，因此缩短有效期没有收益，每次到期反而要重新信任一次。需要更短的窗口时用 `tlsCertMaxAgeDays` 自行调整。
135
141
 
136
142
  监听器自身是 HTTPS 时，网关的响应（登录页 / 重定向 / 拒绝）带 HSTS。
137
143
 
138
144
  ### 关于 `Secure` cookie
139
145
 
140
- 启用 TLS 或声明受信终止代理后，登录 cookie 自动带 `Secure`。但「声明了受信代理」只说明前面有个代理，不说明浏览器到代理这一段是加密的。
146
+ 启用 TLS 或声明受信终止代理后，登录 cookie 自动带 `Secure`。但「声明了受信代理」只说明网关前方存在一个代理，不说明浏览器到代理这一段是加密的。
141
147
 
142
- 如果那个代理只做明文鉴权、浏览器以 `http://` 访问（代理再以明文转发回本端口），自动推断会把 `Secure` 加上，而浏览器拒收明文 http 上的 Secure cookie。结果是密码校验通过、cookie 存不下，每次都被弹回 `/__login`，无限循环。这种部署要显式关掉：
148
+ 如果该代理只做明文鉴权、浏览器以 `http://` 访问（代理再以明文转发回本端口），自动推断会把 `Secure` 加上，而浏览器拒收明文 http 上的 Secure cookie。结果是密码校验通过、cookie 无法保存，每次都被重定向回 `/__login`，无限循环。这种部署需要显式关闭：
143
149
 
144
150
  ```yaml
145
151
  - id: dsh-lan-gateway
@@ -150,24 +156,24 @@ lan_gateway disable # 关闭
150
156
  secureCookies: false # 浏览器 → nginx 是明文 http，不能带 Secure
151
157
  ```
152
158
 
153
- `lan_gateway status` 会如实报出实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
159
+ `lan_gateway status` 会如实报告实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
154
160
 
155
- 注意 `secureCookies: false` 说的是浏览器到入口那一段是明文，网关登录密码和会话 cookie 会在这一段明文传输。这跟 `allowInsecurePlaintext` 描述的不是同一段链路：后者指代理到网关之间不加密，前者指浏览器到代理之间不加密。只有当代理本身已经对用户完成鉴权、且你能接受这段明文时，才这么配。
161
+ 注意 `secureCookies: false` 说的是浏览器到入口这一段是明文，网关登录密码和会话 cookie 会在这一段明文传输。这与 `allowInsecurePlaintext` 描述的不是同一段链路：后者指代理到网关之间不加密，前者指浏览器到代理之间不加密。只有当代理本身已经对用户完成鉴权、且可以接受这段明文时，才应这样配置。
156
162
 
157
163
  ## 安全模型
158
164
 
159
165
  - **来源分级只认 `socket.remoteAddress`**（IPv4-mapped IPv6 会先解包），分 loopback / lan / internet 三档，绝不信任 `X-Forwarded-For`。分级本身不授予任何访问，每一档默认都要出示有效网关会话，否则 302 到 `/__login`。
160
- - **LAN 免密是显式 opt-in**。`lanPasswordless: true` 只让命中 `lanCidrs` 或 loopback 的来源跳过网关自己的登录页；底座 ≥ 0.1.2-rc.1 时上游会话仍把关每个请求。底座没有浏览器会话认证时这个开关拒绝启用，否则等于把 QVD-2026-57410 原样装回去。
161
- - **共享上游会话中继**（dsh ≥ 0.1.2-rc.1）。dsh 不再信任回环 Host，要求出示 HMAC 签名的 `dsh-auth-*` cookie。插件经 `connection` 服务拿到启动令牌，在回环传输上做一次浏览器等价的令牌换取，取得 cookie 后中继到每个转发请求；上游一旦 401 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的人骑同一条上游会话，持钥的上游才是真正的授权主体。
166
+ - **LAN 免密是显式 opt-in**。`lanPasswordless: true` 只让命中 `lanCidrs` 或 loopback 的来源跳过网关自己的登录页；底座 ≥ 0.1.2-rc.1 时上游会话仍把关每个请求。底座没有浏览器会话认证时这个开关拒绝启用，否则等同于把 QVD-2026-57410 原样恢复。
167
+ - **共享上游会话中继**（dsh ≥ 0.1.2-rc.1）。dsh 不再信任回环 Host，要求出示 HMAC 签名的 `dsh-auth-*` cookie。插件经 `connection` 服务拿到启动令牌，在回环传输上做一次浏览器等价的令牌换取，取得 cookie 后中继到每个转发请求；上游一旦 401 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的用户共用同一条上游会话，持钥的上游才是真正的授权主体。
162
168
  - **登录页**。`/__login` 由网关独占、不转发。密码以 scrypt 校验，每写一次重新加盐；登录尝试按来源限流（5 次 / 分钟）。
163
- - **会话 cookie** 是 `payload.signature` 结构（HMAC-SHA256），带撤销 epoch，`HttpOnly; SameSite=Strict`。改密、清密、`rotate-secret` 都会递增 epoch，作废全部已签发 cookie 并断开已建立的 WebSocket，客户端需要重新登录。清空密码会直接停止监听。
164
- - **管理面不外泄**。`/lan-gateway/*`（含配置路由）由网关独占、一律 403 不转发，远程访问者没法借网关改写 Host 去够到本机 loopback 的配置接口。原生 `/lan-gateway/config` 只应答回环 Host 且同源的请求。远程管理走 `lan_gateway` 工具。
169
+ - **会话 cookie** 是 `payload.signature` 结构（HMAC-SHA256），带撤销 epoch 与逐会话 id，`HttpOnly; SameSite=Strict`。登出撤销的是当前这条会话：它建立的 WebSocket 一并断开，其他设备不受影响。改密、清密、`rotate-secret` 递增 epoch，作废全部已签发 cookie 并断开全部已建立的 WebSocket，客户端需要重新登录。清空密码会直接停止监听。
170
+ - **管理面不外泄**。`/lan-gateway/*`（含配置路由）由网关独占、一律 403 不转发，远程访问者无法借网关改写 Host 触及本机 loopback 的配置接口。原生 `/lan-gateway/config` 只应答回环 Host 且同源的请求。远程管理走 `lan_gateway` 工具。
165
171
  - **CSRF 围栏**（HTTP 与 WebSocket）。网关把 Origin 改写回 loopback，会蒙蔽 dsh 自身的 CSRF 防线，所以在改写前对每个转发请求自检：`sec-fetch-site: cross-site` 直接拒；Origin 必须匹配访问者实际使用的网关权威来源；状态变更方法与 WebSocket 升级请求必须携带同源 Origin，否则 403。
166
- - **没设密码就拒绝监听**，跟来源无关。
172
+ - **未设置密码时拒绝监听**，与来源无关。
167
173
 
168
174
  ## 登录页
169
175
 
170
- 远程来源打开 `http://<主机>:3081/` 时先看到网关自带的登录表单，输入正确密码后签发会话 cookie 并跳回 `/`。
176
+ 远程来源打开 `http://<主机>:3081/` 时先看到网关自带的登录表单，输入正确密码后签发会话 cookie 并跳转回 `/`。
171
177
 
172
178
  <p align="center">
173
179
  <img src="assets/login-screenshot.webp" alt="网关登录页截图" width="320" />
@@ -175,26 +181,26 @@ lan_gateway disable # 关闭
175
181
 
176
182
  ## UUID shim
177
183
 
178
- 网关以 `http://<LAN-IP>:3081` 服务页面，浏览器视其为不安全源，`crypto.randomUUID()`（仅安全源可用）为 `undefined`，于是每次 RPC id 铸造都抛 `crypto.randomUUID is not a function`，工作区打不开。
184
+ 网关以 `http://<LAN-IP>:3081` 服务页面，浏览器视其为不安全源，`crypto.randomUUID()`（仅安全源可用）为 `undefined`，于是每次 RPC id 铸造都抛 `crypto.randomUUID is not a function`，工作区无法打开。
179
185
 
180
- client bundle 在模块级给 `Crypto` 原型补一个基于 `crypto.getRandomValues()` 的 `randomUUID`（RFC 4122 v4，`getRandomValues` 在所有源都可用）。它在浏览器求值时就执行，早于任何官方代码铸造 id，所以对官方所有调用点（含以后新增的）一律生效，不用改 DSH 源码。安全源和 Node ≥ 19 下是 no-op，不影响任何行为。
186
+ client bundle 在模块级给 `Crypto` 原型补一个基于 `crypto.getRandomValues()` 的 `randomUUID`（RFC 4122 v4，`getRandomValues` 在所有源都可用）。它在浏览器求值时就执行，早于任何官方代码铸造 id，所以对官方所有调用点（含以后新增的）一律生效，无需修改 DSH 源码。安全源和 Node ≥ 19 下是 no-op，不影响任何行为。
181
187
 
182
188
  ## 开发
183
189
 
184
190
  ```bash
185
- pnpm test # 93 项
191
+ pnpm test # 117 项
186
192
  pnpm typecheck # tsc 双端（host + client）
187
193
  ```
188
194
 
189
195
  ```
190
- ✓ tests/gateway.test.ts (27) 分类 / HMAC cookie / epoch / 密码状态 / 限流
196
+ ✓ tests/gateway.test.ts (40) 分类 / HMAC cookie / epoch / 逐会话撤销 / 密码状态 / 限流
191
197
  ✓ tests/start-guard.test.ts (19) fail-closed 启动守卫 / 配置路由回环围栏 /
192
198
  Secure cookie 属性推断（含 null 清除路径）
193
- ✓ tests/integration/gateway.test.ts (17) 真实网关端到端：全来源登录 / LAN 豁免 /
194
- 跨站 403 / 升级拒绝 / cookie 属性 / epoch 撤销 / 会话中继
199
+ ✓ tests/integration/gateway.test.ts (26) 真实网关端到端：全来源登录 / LAN 豁免 / 跨站 403 / 升级拒绝 /
200
+ cookie 属性 / epoch 撤销 / 逐会话登出 / 尾斜杠 / IPv6 / 会话中继
195
201
  ✓ tests/uuid-shim.test.ts ( 3) 不安全源补丁 / 安全源 no-op / v4 正确性
196
202
  ✓ tests/x509.test.ts ( 6) 自签名证书 DER/SAN/签名/TLS 握手
197
- ✓ tests/tls.test.ts ( 7) 证书持久化 / 重生成 / 自定义证书加载
203
+ ✓ tests/tls.test.ts ( 9) 证书持久化 / 到期换发 / 重生成 / 自定义证书加载
198
204
  ✓ tests/upstream-session.test.ts ( 8) 真实回环令牌换取：cookie 名匹配 / 拒绝后重换 /
199
205
  invalidate 重获取 / 日志播报 / 保住已持有会话
200
206
  ✓ tests/settings-card.test.ts ( 6) 设置页字段编解码：三态 auto ↔ false 不可混淆
@@ -221,8 +227,8 @@ pnpm typecheck # tsc 双端（host + client）
221
227
  pnpm install --frozen-lockfile
222
228
  pnpm typecheck && pnpm test
223
229
  npm publish --access public # prepack 自动构建 lib/
224
- git tag -a v0.5.3 -m "…" && git push origin v0.5.3
225
- gh release create v0.5.3 --generate-notes ./*.tgz # 可选：Release + tgz 附件
230
+ git tag -a v0.5.4 -m "…" && git push origin v0.5.4
231
+ gh release create v0.5.4 --generate-notes ./*.tgz # 可选：Release + tgz 附件
226
232
  ```
227
233
 
228
234
  ## 安全评估
@@ -232,6 +238,7 @@ gh release create v0.5.3 --generate-notes ./*.tgz # 可选：Release + tgz 附
232
238
  - [LAN 网关安全评估](docs/security/SECURITY-AUDIT.md)：0.4.0 时代的 F1–F5 审计快照与 13 个隔离观察，顶部标注了 0.5.0 的修复状态。
233
239
  - [QVD-2026-57410 修复方案](docs/security/qvd-2026-57410-fix-plan.md)：方案全文 + §15 实施状态。
234
240
  - [上游研究](docs/security/qvd-2026-57410-research.md)：公开通告、上游提交与版本核对。
241
+ - [0.5.4 复审与修复清单](docs/security/audit-2026-09-19-fix-list.md)：0.5.3 的实现细节复审（G1–G12）与修复记录。
235
242
 
236
243
  ## 许可
237
244
 
package/lib/index.d.ts CHANGED
@@ -45,7 +45,7 @@ interface GatewayController {
45
45
  interface Config {
46
46
  /** Whether the gateway listener is started at boot. Default false (safe). */
47
47
  enabled: boolean;
48
- /** Port to bind on 0.0.0.0. */
48
+ /** Port to bind on the unspecified address, both address families. */
49
49
  gatewayPort: number;
50
50
  /** Explicit dsh target port; defaults to the live `ctx.webServer.port`. */
51
51
  dshTargetPort?: number;
@@ -77,7 +77,18 @@ interface Config {
77
77
  tlsKeyPath?: string;
78
78
  /** Self-signed mode: comma/space separated DNS names and IPs for the SANs. */
79
79
  tlsSelfSignedHosts?: string;
80
- /** Self-signed certificate validity in days (default 825 ≈ 27 months). */
80
+ /**
81
+ * Self-signed certificate validity in days (default 825 ≈ 27 months).
82
+ *
83
+ * 825 is the ceiling Apple states for TLS server certificates, and the
84
+ * well-known 398-day limit — which this default is sometimes mistaken for
85
+ * exceeding — applies only to certificates chaining to a root preinstalled
86
+ * by the platform: Apple exempts user- and administrator-added roots
87
+ * outright, and a self-signed certificate is always one of those. Since a
88
+ * self-signed certificate is either clicked through or trusted by hand,
89
+ * there is nothing to gain from the shorter window and a re-trust to lose
90
+ * every time it lapses.
91
+ */
81
92
  tlsCertMaxAgeDays: number;
82
93
  /**
83
94
  * Escape hatch (default false): permit plaintext HTTP. Never derived from