dsh-lan-guard 0.3.4 → 0.3.5

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.3.5] — 2026-09-26(连接层可见性:明文请求 301 + 旧设备 cookie 不再锁死)
4
+
5
+ ### 修复 — 用 `http://` 打开 TLS 端口时只看到「无法访问」,日志里也什么都没有
6
+
7
+ **症状**(2026-09-26 用户报告):把 `http://<地址>:<端口>` 交给浏览器(二维码或地址栏写成 http),页面显示「无法访问」,浏览器报 `ERR_EMPTY_RESPONSE`(-324);**日志里没有任何记录**,完全看不出发生了什么。
8
+
9
+ **根因**:明文 HTTP 请求到达 TLS 监听端口时握手先失败,Node 在 `tlsClientError` 里默认**一个字节都不回**并直接销毁连接;而门禁运行在握手之后,所以这一层失败在门禁侧完全不可见。
10
+
11
+ **改动**(`src/proxy.ts`):
12
+ - 监听 `tlsClientError`,记录 `tls handshake failed code=… plaintextHttp=… ip=…`;
13
+ - 对 `ERR_SSL_HTTP_REQUEST`(明文请求)回一个 **301 到同地址的 `https://…/`**,浏览器自动切到正确协议。明文应答无法通过 `TLSSocket` 发出(实测客户端收到 0 字节),因此写在底层原始 socket(`_parent`)上——该私有字段在 Node 20/22/24 上验证;字段缺失时安全降级为原来的销毁行为,不会更糟;
14
+ - 补上 `clientError`:畸形请求同样记录 `malformed request code=… ip=…`,并**原样复现** Node 默认的 `400 Bad Request`(挂监听器会替换默认处理,不能把默认响应弄丢)。
15
+
16
+ ### 修复 — 删除设备记录后,这台浏览器被永久锁死
17
+
18
+ **症状**(2026-09-26 手机实测):一台曾经配对过的手机,在管理员**删除**它的设备记录后,永远只能看到「此设备已被移除访问权限」——换免密链接、输访问密码都进不去,只有清除本站数据才行。
19
+
20
+ **根因**:门禁把「带着设备 cookie、但记录已不存在」与「被吊销/拉黑」同等处理(都走移除页)。而移除页在读取 `?auth=` **之前**就产生了,所以任何链接都救不回来。记录被删属于**浏览器侧过期状态**,不是身份。
21
+
22
+ **改动**(`src/auth/gate.ts`):cookie 指向不存在的记录时不再拒绝,而是**按没有 cookie 继续正常认证流程**——访问密码或新链接都能恢复,配对流程会给它一条新身份。WebSocket 升级同样处理(回落到会话判定,而不是 403)。**吊销(revoke)与拉黑(block)仍然拒绝**:它们的记录还在,语义未变。
23
+
24
+ ### 变更 — 移除页文案随实现修正
25
+
26
+ 「若该记录已被删除,请清除本浏览器的本站数据」这条死路已不存在,文案改为只保留真正有效的一条:请联系管理员在「已授权设备」中「解除拉黑」,同一台设备会立即恢复。
27
+
28
+ ### 验证
29
+
30
+ - `pnpm run typecheck` ✓;`pnpm test` — **273 项全绿**(0.3.4 为 263 项,+10);
31
+ - 新增 `tests/proxy-tls-port.test.ts`(真实 socket:明文请求得到 301、真实 TLS 客户端不受影响、握手失败与畸形请求都进日志、畸形请求仍复现 Node 的 400)与 gate 的 5 条用例(旧 cookie 经免密链接/密码恢复、WebSocket 升级不再 403、吊销与拉黑仍拒绝、移除页文案不再提「清除本站数据」);
32
+ - **反证**(在隔离副本里回退修复后重跑,确认用例不是空测试):回退 `gate.ts` → 3 条恢复用例失败(3 failed / 41);回退 `proxy.ts` → 3 条连接层用例失败(3 failed / 5),而固定"未改行为"的用例仍通过。
33
+
3
34
  ## [0.3.4] — 2026-09-26(局域网设备可用官方设置页)
4
35
 
5
36
  ### 新增 — 默认开启的 `settingsUnlock`:局域网设备也能用官方「模型」页
package/README.md CHANGED
@@ -137,10 +137,11 @@ The plugin reads its config from its Cordis entry. **Every key has a usable defa
137
137
 
138
138
  ## Compatibility
139
139
 
140
- Current version: plugin **`0.3.4`**; it adds one host-side switch and one index injection (verified on DeepSeek Harness **`0.1.7-rc.2`**).
140
+ Current version: plugin **`0.3.5`**; connection-level visibility and gate-recovery fixes (verified on DeepSeek Harness **`0.1.7-rc.2`**).
141
141
 
142
142
  | Plugin | Verified DeepSeek Harness | What this version is |
143
143
  | --- | --- | --- |
144
+ | **`0.3.5`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Connection-level visibility: an `http://` request to the TLS port goes from "blank page + no log" to a 301 onto `https` with a log line; a deleted device record no longer locks that browser out (revoked/blocked still refuse); the removal-page copy follows |
144
145
  | **`0.3.4`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Official settings page on the LAN: a new `settingsUnlock` switch (on by default) that injects the host-surface marker into the index; applies on page refresh; a UI unlock, not a new privilege |
145
146
  | **`0.3.3`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Gate UX fixes: the two first-visit steps are announced up front; an inert-link page can be logged into again; the blocking note now matches real behaviour (no host-facing change) |
146
147
  | **`0.3.2`** | **`0.1.7-rc.2`**, `0.1.7-rc.1` | Install and go: LAN-facing default + derived `dataDir`; Liquid Glass settings page at official sizes; single-line scrolling access URL |
@@ -153,6 +154,7 @@ Current version: plugin **`0.3.4`**; it adds one host-side switch and one index
153
154
  - Declared range `>=0.1.7-rc.1 <0.2.0` (`dsh.engines.dsh`); DSH versions not listed are **unverified** — verify them yourself before use.
154
155
  - Host/client interfaces this plugin uses: `webServer.register` / `webServer.tapIndex` (indexTaps), `connection.requestRejection`, `connection.authenticatedUrl`, the additive `settings.section` seat, `@deepseek-ai/schemastery`, and `profileContext` (for deriving the default data directory).
155
156
  - **Breaking default change (from `0.3.2`)**: `listenHost` now defaults to `0.0.0.0` instead of `127.0.0.1`, so one restart after install is enough; `0.3.1` and earlier default to loopback only. The gate and self-signed TLS defaults are unchanged (with no password the gate still refuses every device). See the [CHANGELOG](CHANGELOG.md).
157
+ - **`0.3.5` verification status**: the changes touch only the proxy's connection-level handling and the gate's verdict; no host/client interface changed; the suite is green at **273** specs (+10) and was falsified (reverting a fix fails its specs); the real-DSH install verification follows the release.
156
158
  - **`0.3.4` verification status**: the change adds one host-side switch, one index injection and a switch on the plugin's own settings page (`webServer.tapIndex` is a declared host interface); the suite is green at **263** specs; the injected script was exercised in a real Chrome over a non-loopback address in three states; the real-DSH install verification follows the release.
157
159
  - **`0.3.3` verification status**: the changes touch only the plugin's own pages, copy and gate-form availability; no host/client interface changed; the suite is green at **247** specs; the real-DSH install verification follows the release.
158
160
 
package/README.zh.md CHANGED
@@ -137,10 +137,11 @@ dsh plugin --profile web add "link:$(pwd)"
137
137
 
138
138
  ## 兼容性
139
139
 
140
- 当前版本:插件 **`0.3.4`**;新增一个宿主侧开关与一行 index 注入(已在 DeepSeek Harness **`0.1.7-rc.2`** 上验证)。
140
+ 当前版本:插件 **`0.3.5`**;连接层可见性与门禁恢复修复(已在 DeepSeek Harness **`0.1.7-rc.2`** 上验证)。
141
141
 
142
142
  | 插件 | 已验证的 DeepSeek Harness | 这个版本是什么 |
143
143
  | --- | --- | --- |
144
+ | **`0.3.5`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 连接层可见性:`http://` 访问 TLS 端口由「空白页 + 无日志」改为 301 跳 `https` 并记日志;删除设备记录后旧 cookie 不再把浏览器锁死(吊销/拉黑仍拒绝);移除页文案同步修正 |
144
145
  | **`0.3.4`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 局域网设备可用官方设置页:新增默认开启的 `settingsUnlock` 开关(index 注入宿主界面标记,刷新页面生效;界面解锁而非新增权限) |
145
146
  | **`0.3.3`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 门禁体验修复:首次访问的两道关提前说明;失效链接页恢复可登录;拉黑说明改为与实现一致(未触碰宿主接口) |
146
147
  | **`0.3.2`** | **`0.1.7-rc.2`**、`0.1.7-rc.1` | 装完即用:默认对外监听 + `dataDir` 自动推导;设置页液体玻璃与官方尺寸;访问地址改为单行滚动 |
@@ -153,6 +154,7 @@ dsh plugin --profile web add "link:$(pwd)"
153
154
  - 声明范围 `>=0.1.7-rc.1 <0.2.0`(`dsh.engines.dsh`);未列入的 DSH 版本属**未验证**,请自行验证后再使用。
154
155
  - 本插件用到的宿主/客户端接口:`webServer.register` / `webServer.tapIndex`(indexTaps)、`connection.requestRejection`、`connection.authenticatedUrl`、追加型 `settings.section` seat、`@deepseek-ai/schemastery`,以及 `profileContext`(用于推导默认数据目录)。
155
156
  - **破坏性默认值变更(`0.3.2` 起)**:`listenHost` 默认由 `127.0.0.1` 改为 `0.0.0.0`,装完重启一次即可用;`0.3.1` 及更早默认仅回环。门禁与自签 TLS 的默认值未变(未设密码仍拒绝所有设备)。详见 [CHANGELOG](CHANGELOG.md)。
157
+ - **`0.3.5` 的验证状态**:改动只在代理的连接层处理与门禁判定,未改动任何宿主/客户端接口;测试套件 **273 项**全绿(+10),并做过反证(回退修复后对应用例失败);真实 DSH 上的装机验证在发布后进行。
156
158
  - **`0.3.4` 的验证状态**:改动只新增一个宿主侧开关、一行 index 注入与插件自己的设置页开关(`webServer.tapIndex` 是已声明的宿主接口);测试套件 **263 项**全绿;注入脚本已在真实 Chrome + 非回环地址实测三种状态;真实 DSH 上的装机验证在发布后进行。
157
159
  - **`0.3.3` 的验证状态**:改动只在插件自己的页面、文案与门禁表单可用性,未改动任何宿主/客户端接口;测试套件 **247 项**全绿;真实 DSH 上的装机验证在发布后进行。
158
160
 
package/lib/index.js CHANGED
@@ -1104,7 +1104,7 @@ function notice(state, lockedUntilMs, now) {
1104
1104
  if (state === "csrf") return "<p class=\"notice error\">请求来源校验未通过,请从本页重新登录。</p>";
1105
1105
  if (state === "link-inactive") return "<p class=\"notice error\">这条免密链接无效,或当前「仅密码」模式不使用免密链接。<br>请输入访问密码;若希望链接可用,请在运行本程序的电脑上把验证模式改为「令牌 + 密码」。</p>";
1106
1106
  if (state === "pending-approval") return "<p class=\"notice\">⏳ <strong>这台设备正在等待管理员批准。</strong><br>请在运行本程序的电脑上打开设置 → 局域网访问 → 已授权设备,点「批准」后刷新本页即可进入。</p>";
1107
- if (state === "device-removed") return "<p class=\"notice error\"><strong>此设备已被移除访问权限。</strong><br>请联系管理员在「已授权设备」中「解除拉黑」,同一台设备会立即恢复;若该记录已被删除,请清除本浏览器的本站数据后再访问。</p>";
1107
+ if (state === "device-removed") return "<p class=\"notice error\"><strong>此设备已被移除访问权限。</strong><br>请联系管理员在「已授权设备」中「解除拉黑」,同一台设备会立即恢复。</p>";
1108
1108
  if (state === "token-only") return "<p class=\"notice warn\">当前验证模式为<strong>仅安全 Token</strong>,不接受密码登录。请使用管理员提供的免密链接或二维码。</p>";
1109
1109
  if (state === "no-password") return "<p class=\"notice warn\"><strong>尚未设置访问密码。</strong><br>出于安全考虑,未设置密码时门禁不会放行任何设备。请在桌面 DSH 的「设置 → 局域网访问」中设置访问密码。</p>";
1110
1110
  return "";
@@ -1239,10 +1239,10 @@ var VisitorGate = class {
1239
1239
  return "handled";
1240
1240
  }
1241
1241
  const deviceToken = readCookie(req, DEVICE_COOKIE);
1242
- if (deviceToken !== void 0) {
1243
- const device = this.#devices?.lookup(deviceToken);
1244
- if (device === void 0 || device.revokedAtMs !== null || device.status === "blocked") {
1245
- this.#logger.warn("refused a revoked, blocked or unknown device ip=%s", clientIp(req));
1242
+ const device = deviceToken === void 0 ? void 0 : this.#devices?.lookup(deviceToken);
1243
+ if (device !== void 0) {
1244
+ if (device.revokedAtMs !== null || device.status === "blocked") {
1245
+ this.#logger.warn("refused a revoked or blocked device ip=%s", clientIp(req));
1246
1246
  this.#sendRemoved(req, res);
1247
1247
  return "handled";
1248
1248
  }
@@ -1255,6 +1255,7 @@ var VisitorGate = class {
1255
1255
  });
1256
1256
  return "allow";
1257
1257
  }
1258
+ if (deviceToken !== void 0) this.#logger.debug?.("device cookie matches no record; continuing to the auth flow ip=%s", clientIp(req));
1258
1259
  const link = url.searchParams.get("auth");
1259
1260
  if (link !== null) return await this.#handleAuthLink(req, res, url, link);
1260
1261
  const verdict = await this.#auth.verifyRequest(req);
@@ -1288,9 +1289,9 @@ var VisitorGate = class {
1288
1289
  */
1289
1290
  async verifyUpgrade(req) {
1290
1291
  const deviceToken = readCookie(req, DEVICE_COOKIE);
1291
- if (deviceToken !== void 0) {
1292
- const device = this.#devices?.lookup(deviceToken);
1293
- if (device === void 0 || device.revokedAtMs !== null || device.status === "blocked") {
1292
+ const device = deviceToken === void 0 ? void 0 : this.#devices?.lookup(deviceToken);
1293
+ if (device !== void 0) {
1294
+ if (device.revokedAtMs !== null || device.status === "blocked") {
1294
1295
  this.#logger.warn("upgrade refused: revoked or blocked device ip=%s", clientIp(req));
1295
1296
  return {
1296
1297
  status: 403,
@@ -2131,6 +2132,55 @@ function parseUpstream(origin) {
2131
2132
  function isSafeMethod(method) {
2132
2133
  return method === "GET" || method === "HEAD";
2133
2134
  }
2135
+ /** The peer address of a socket whose own typing does not carry one. */
2136
+ function peerOf(socket) {
2137
+ const address = socket.remoteAddress;
2138
+ return typeof address === "string" && address !== "" ? address : "unknown";
2139
+ }
2140
+ /**
2141
+ * Answer a plaintext HTTP request that reached the TLS port with a redirect to
2142
+ * the same address over `https`.
2143
+ *
2144
+ * Three facts shape this function:
2145
+ *
2146
+ * 1. it only ever runs for a connection whose handshake ALREADY failed, so it
2147
+ * cannot affect a working TLS session;
2148
+ * 2. the request line and headers are gone by then — the TLS parser consumed
2149
+ * and rejected them — so the redirect targets the root of the address the
2150
+ * client connected to, not the path it asked for;
2151
+ * 3. a plaintext reply cannot travel through the `TLSSocket` at all (writing to
2152
+ * it is encrypted into nothing — measured: the client receives zero bytes),
2153
+ * so only the raw socket underneath can carry it. Node exposes that as the
2154
+ * private `_parent`; the field is verified on Node 20, 22 and 24. When it is
2155
+ * absent — a future Node change — this returns false and the caller destroys
2156
+ * the socket, which is exactly the behaviour before this function existed.
2157
+ *
2158
+ * @param socket - the socket whose TLS handshake failed.
2159
+ * @param logger - logger, used only for the degraded path.
2160
+ * @returns whether the redirect was written.
2161
+ */
2162
+ function redirectPlaintextToHttps(socket, logger) {
2163
+ const raw = socket._parent;
2164
+ if (raw === void 0 || raw === null || raw.writable !== true || typeof raw.end !== "function") {
2165
+ logger.debug?.("plaintext redirect unavailable: no writable raw socket");
2166
+ return false;
2167
+ }
2168
+ const address = socket.localAddress;
2169
+ const port = socket.localPort;
2170
+ if (address === void 0 || address === "" || port === void 0) return false;
2171
+ const host = address.includes(":") ? `[${address}]` : address;
2172
+ try {
2173
+ raw.end.call(raw, `HTTP/1.1 301 Moved Permanently\r
2174
+ location: https://${host}:${String(port)}/\r\ncontent-length: 0\r
2175
+ connection: close\r
2176
+ \r
2177
+ `);
2178
+ return true;
2179
+ } catch (error) {
2180
+ logger.warn("plaintext redirect failed name=%s", error.name);
2181
+ return false;
2182
+ }
2183
+ }
2134
2184
  /**
2135
2185
  * Start the proxy listener.
2136
2186
  *
@@ -2210,14 +2260,30 @@ async function startProxy(options) {
2210
2260
  await forwardHttp(req, res, normalizeRequestTarget(req.url), true);
2211
2261
  })();
2212
2262
  };
2213
- const server = options.tls === void 0 ? createServer(handler) : createServer$1({
2263
+ const httpsServer = options.tls === void 0 ? void 0 : createServer$1({
2214
2264
  cert: options.tls.cert,
2215
2265
  key: options.tls.key
2216
2266
  }, handler);
2267
+ const server = httpsServer ?? createServer(handler);
2217
2268
  server.on("connection", (socket) => {
2218
2269
  sockets.add(socket);
2219
2270
  socket.on("close", () => sockets.delete(socket));
2220
2271
  });
2272
+ if (httpsServer !== void 0) httpsServer.on("tlsClientError", (error, socket) => {
2273
+ const code = error.code ?? error.name;
2274
+ const plaintext = code === "ERR_SSL_HTTP_REQUEST";
2275
+ logger.warn("tls handshake failed code=%s plaintextHttp=%s ip=%s", code, plaintext ? "yes" : "no", peerOf(socket));
2276
+ if (plaintext && redirectPlaintextToHttps(socket, logger)) return;
2277
+ socket.destroy();
2278
+ });
2279
+ server.on("clientError", (error, socket) => {
2280
+ logger.warn("malformed request code=%s ip=%s", error.code ?? error.name, peerOf(socket));
2281
+ if (error.code === "ECONNRESET" || socket.writable !== true) {
2282
+ socket.destroy();
2283
+ return;
2284
+ }
2285
+ socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
2286
+ });
2221
2287
  server.on("upgrade", (req, socket, head) => {
2222
2288
  guardUpgradeSocket(socket, logger);
2223
2289
  (async () => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-lan-guard",
3
- "version": "0.3.4",
3
+ "version": "0.3.5",
4
4
  "description": "DSH web plugin: expose the official desktop Web UI to the local network through a gated reverse proxy, without touching DSH's own loopback binding.",
5
5
  "license": "MIT",
6
6
  "type": "module",