@riceawa/dsh-lan-gateway 0.5.1 → 0.5.3

package/README.md

@@ -6,167 +6,112 @@
 
 <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.1-2b7fff?style=flat-square" alt="version 0.5.1" />
+  <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/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>
 
-> 把 DeepSeek Harness 的 Web GUI 安全地开放到局域网 / 公网。
-> 附带**不安全源 UUID shim**：网关以纯 HTTP 局域网地址服务页面时，浏览器不提供
-> `crypto.randomUUID`，本插件的 client bundle 会在页面加载早期自动补上
-> `getRandomValues` 版实现，让工作区（含其他设备打开的工作区）在网关下正常打开。
-> 附带**TLS 支持**：可用自动生成并持久化的**自签名证书**，或挂载**自己申请/签发的
-> PEM 证书**，让网关以 HTTPS 服务（自签名证书首次访问会看到浏览器警告，属预期行为）。
-
-`dsh` 的 web CLI 会硬拒绝 `--host 0.0.0.0`（避免把远程代码执行暴露到网络），所以本插件
-让 dsh 继续只绑 `127.0.0.1`，自己另起一个 `0.0.0.0` 反向代理网关转发到 loopback 端口，
-改写 `Host`/`Origin`。**默认拒绝（fail-closed）：所有来源——loopback、LAN、公网——都必须
-先通过网关的登录页并出示 HMAC 会话 cookie**；“LAN 免密”改为显式 `lanPasswordless` opt-in
-且默认关闭。对 dsh ≥ 0.1.2-rc.1（修复了 QVD-2026-57410 的浏览器会话认证底座），网关在进程内
-中继**一条共享的上游会话**，上游自身的授权仍然把关每个请求——网关只决定谁能骑上这条
-共享会话。
-
-## 特性
-
-- **双端一体**：host 端是反向代理网关（登录 / HMAC cookie / 会话撤销 / Origin 围栏 /
-  TLS / 上游会话中继）；client 端是不安全源 UUID shim + **官方设置页卡片**（DSH Settings
-  → Plugins → 可配置插件，网关的端口 / 网段 / 认证 / TLS 全部可视化调整，保存即热生效）。
-- **默认全来源登录（QVD-2026-57410 加固）**：不再“只对公网来源认证”；loopback/LAN 同样
-  要求会话。唯一豁免是显式 `lanPasswordless: true`（仅豁免网关登录，上游会话中继仍生效）。
-- **共享上游会话中继**：dsh 0.1.2 起不再信任 loopback Host，要求出示绑定权威来源的
-  `dsh-auth-*` cookie；插件在进程内用启动令牌走一遍浏览器等价换取，把这一条会话中继到
-  每个转发请求上（“单密码 = 单操作者”语义不变）。底座不支持时自动降级为无中继转发。
-- **fail-closed 启动守卫**：未设密码拒启；`authRequired:false`（v0.4 及更早）拒启并给迁移
-  文案；明文监听需显式 `allowInsecurePlaintext:true`（或 TLS / 声明 `trustedTerminator`）。
-- **TLS 双模式**：`self-signed` 自动生成自签名证书（首次启动生成并持久化到
-  `~/.dsh/lan-gateway/tls/`，重启复用；`lan_gateway tls-regenerate` 可换新证书），或
-  `custom` 直接挂载你自己的 PEM 证书与私钥（如 Let's Encrypt / 自建 CA 签发）。
-- **会话撤销**：cookie 携带撤销 epoch；改密 / 清密 / `rotate-secret` 都会递增 epoch，使
-  所有已签发 cookie **与已建立的 WebSocket** 立即失效。清空密码会直接停止监听。
-- **默认关闭（安全）**：bundle patch 里 `enabled: false`，只有运行 `lan_gateway enable`
-  后才监听网络端口。
-- **密钥不进配置**：密码哈希、cookie secret 存 `~/.dsh/lan-gateway/state.json`。
-
-## 快速安装（推荐）
-
-已发布到 npm（预构建，安装无需 `allowBuilds` 授权）。请把下面这段话发送给你的 agent：
+`dsh web` 硬拒绝 `--host 0.0.0.0`，怕把远程代码执行暴露到网络。这个插件的做法是让 dsh 继续只绑 `127.0.0.1`，另起一个监听 `0.0.0.0` 的反向代理，转发到 loopback 端口并改写 `Host` / `Origin`。
 
-> 帮我安装 dsh 插件 `@riceawa/dsh-lan-gateway`，遵循
-> `https://github.com/rice-awa/dsh-lan-gateway/blob/main/INSTALL.md`
-
-## 配套 skill
+默认拒绝：loopback、LAN、公网三种来源都要先在网关登录页拿到 HMAC 会话 cookie，LAN 免密需要显式打开 `lanPasswordless`，默认关闭。底座是 dsh ≥ 0.1.2-rc.1 时（含 QVD-2026-57410 的上游修复），网关在进程内中继一条共享上游会话，上游自己的授权仍然把关每个请求，网关只决定谁能骑上这条会话。
 
-仓库还带一个 [lan-gateway](skills/lan-gateway.md) 技能：让 dsh 的 agent 在对话中
-自动管理网关——开/关监听、设置或更换远程访问密码、轮换会话密钥、查看状态。装上后
-直接说「设置网关密码为 …」「开启远程访问」即可，agent 会调用 `lan_gateway` 工具
-完成（密码以参数传入，不写入配置、不回显）。安装方式见
-[INSTALL.md](INSTALL.md#for-agents完整安装流程)。
+插件还捎带两件事：
 
-## 移动端访问（推荐）
+- **不安全源 UUID shim**：网关以纯 HTTP 的局域网地址服务页面，浏览器视其为不安全源，不提供 `crypto.randomUUID`。client bundle 在页面加载早期补一个基于 `getRandomValues` 的实现，工作区才打得开。
+- **TLS**：自动生成并持久化的自签名证书，或者挂载你自己签发的 PEM。自签名证书首次访问会有浏览器警告，正常现象。
 
-在手机 / 平板上通过网关访问 GUI 时，桌面布局体验不佳。推荐同时安装
-[dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)（移动端 UI 适配），
-与本插件配合使用：
-
-```bash
-dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
-```
+## 安装
 
-## 手动安装
+已发布到 npm，装的是预构建产物，不需要 `allowBuilds` 授权。把这段话丢给你的 agent 就行：
 
-### 方式 A：npm 包（推荐，免 allowBuilds）
+> 帮我安装 dsh 插件 `@riceawa/dsh-lan-gateway`，遵循
+> `https://github.com/rice-awa/dsh-lan-gateway/blob/main/INSTALL.md`
 
-已发布预构建产物到 npm，安装时**不需要**批准构建脚本：
+也可以自己敲：
 
 ```bash
-# 官方装配（重启后由 bundles 列表接管，生产态）
 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完整安装流程)。
 
-### 方式 B：从源码构建
+从源码构建：
 
 ```bash
 git clone https://github.com/rice-awa/dsh-lan-gateway.git
 cd dsh-lan-gateway
 pnpm install
-pnpm build          # host（lib/index.js）
-pnpm build:client   # client（lib/client.js，window.__ModuleLoader__ 格式）
-pnpm test           # 72 项（网关单元 27 + start-guard 12 + 集成 17 + UUID shim 3 + x509 6 + TLS 7）
+pnpm build          # host → lib/index.js
+pnpm build:client   # client → lib/client.js
+pnpm test           # 93 项
 ```
 
-## 使用
-
-```bash
-# 开启网关。先满足启动条件（已设密码 + 加密入口），否则 enable 会给出迁移文案
-lan_gateway enable
-
-# 查看状态（端口 / 目标 / 密码 / 会话 epoch / 中继状态 / 入口加密方式 / 上次错误）
-lan_gateway status
+仓库里还有一个 [lan-gateway](skills/lan-gateway.md) 技能，装上之后可以直接在 dsh 对话里说「设置网关密码为 …」「开启远程访问」，agent 会调用 `lan_gateway` 工具完成，密码以参数传入，不写配置也不回显。安装方式见 [INSTALL.md](INSTALL.md#for-agents完整安装流程)。
 
-# 设置登录密码（≥8 位；改动会让所有已签发会话立即失效）
-lan_gateway set-password
+手机 / 平板上访问的话，再搭一个 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) 做移动端 UI 适配：
 
-# 轮换会话密钥（作废全部登录 cookie 与已建立的 WebSocket）
-lan_gateway rotate-secret
+```bash
+dsh plugin --profile web add github:mexiaosqwq/dsh-web-mobile
+```
 
-# 换发自签名 TLS 证书（tlsMode=self-signed 时；换新密钥并热重启监听器）
-lan_gateway tls-regenerate
+## 用法
 
-# 关闭
-lan_gateway disable
+```bash
+lan_gateway enable            # 开启网关（需先满足启动条件，否则给出迁移文案）
+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` 是一个模型可调用的工具，上面的命令不必由你手动敲——**直接在 dsh 对话
-> 里说即可**，例如“设置网关密码为 ……”（模型会调用 `lan_gateway set-password`，密码以
-> 参数传入、不会回显）、“查看网关状态”、“开启 / 关闭网关”。在对话中设置密码时请直接
-> 把密码说给模型，它不会把密码写进任何配置文件。
+`lan_gateway` 是模型可调用的工具，上面这些命令不必自己敲。直接在对话里说「查看网关状态」「设置网关密码为 ……」即可，密码以参数传给模型，不会落进任何配置文件。
 
-## 配置项（bundle patch / `--patch` 覆盖，或官方设置页）
+## 配置
 
-所有可调项都同时暴露为 `lan-gateway` 用户设置命名空间：打开 **DSH 的 Settings → Plugins
-→ 可配置插件**，展开「LAN 网关」卡片即可修改，保存即生效（监听器会按新配置自动重启）。
-下表即卡片字段 / 配置键：
+所有可调项都暴露为 `lan-gateway` 用户设置命名空间。打开 **DSH 的 Settings → Plugins → 可配置插件**，展开「LAN 网关」卡片就能改，保存即生效，监听器会按新配置自动重启。下表既是卡片字段，也是配置键：
 
 | 键 | 默认值 | 说明 |
 | --- | --- | --- |
 | `enabled` | `false` | 是否在启动时监听网络端口 |
 | `gatewayPort` | `3081` | 网关监听端口（`0.0.0.0`） |
 | `dshTargetPort` | 跟随 `ctx.webServer.port` | 转发到的 dsh loopback 端口 |
-| `lanCidrs` | RFC1918 + link-local（见下） | 视为 LAN 的网段；仅在 `lanPasswordless` 开启时用作豁免匹配集 |
-| `lanPasswordless` | `false` | 显式 opt-in：LAN/loopback 来源跳过网关登录页（上游会话中继仍把关） |
+| `lanCidrs` | RFC1918 + link-local（见下） | 视为 LAN 的网段，仅在 `lanPasswordless` 开启时用作豁免匹配集 |
+| `lanPasswordless` | `false` | LAN/loopback 来源跳过网关登录页（上游会话中继仍把关） |
 | `cookieMaxAgeDays` | `7` | 会话 cookie 有效期（天） |
-| `cookieName` | `dsh_gw_auth` | 会话 cookie 名（不进卡片） |
-| `tlsEnabled` | `false` | 是否以 HTTPS（TLS）提供服务 |
-| `tlsMode` | `self-signed` | 证书来源：`self-signed` 自动生成 / `custom` 用自己的证书 |
+| `cookieName` | `dsh_gw_auth` | 会话 cookie 名，不进卡片 |
+| `tlsEnabled` | `false` | 是否以 HTTPS 提供服务 |
+| `tlsMode` | `self-signed` | `self-signed` 自动生成 / `custom` 用自己的证书 |
 | `tlsSelfSignedHosts` | `localhost` | 自签名证书的 SAN（逗号分隔的域名 / IP） |
 | `tlsCertPath` | — | `custom` 模式：PEM 证书（或证书链）绝对路径 |
 | `tlsKeyPath` | — | `custom` 模式：PEM 私钥绝对路径 |
 | `tlsCertMaxAgeDays` | `825` | 自签名证书有效期（天） |
-| `allowInsecurePlaintext` | `false` | 显式 opt-in：允许明文 HTTP 监听（见下「入口加密」） |
+| `allowInsecurePlaintext` | `false` | 允许明文 HTTP 监听（见下「入口加密」） |
 | `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。
+
+配置里残留 `authRequired: false`（v0.4 及更早的写法）会被启停守卫拒绝并提示迁移，不会静默降级成免密。
 
-> v0.5.0 起 `authRequired` 被移除：认证恒为必需。若配置里残留 `authRequired: false`
-> （v0.4 及更早的写法），启停守卫会拒绝并提示迁移——不会静默降级回“免密”。
+### 入口加密
 
-### 入口加密（防明文）
+网关默认拒绝纯明文监听，下面三条路任选一条才能启动：
 
-网关默认**拒绝纯明文监听**，三种方式任选其一即可启动：
+1. 启用 TLS，`tlsEnabled: true`。推荐，自签名或 custom 证书都行。
+2. 声明由可信反向代理终止 TLS：
 
-1. 启用 TLS：`tlsEnabled: true`（推荐，自签名或 custom 证书均可）；
-2. 声明由可信反向代理（nginx 等）终止 TLS：
    ```yaml
    - id: dsh-lan-gateway
      config:
        enabled: true
        gatewayPort: 8080
-       trustedTerminator: nginx   # 由 nginx 以 HTTPS 对外，再转发回本端口
+       trustedTerminator: nginx   # nginx 以 HTTPS 对外，再转发回本端口
    ```
-3. 显式接受明文（风险自担，密码与会话将明文在网内传输）：
+
+3. 显式接受明文，风险自担，密码与会话会在网内明文传输：
+
    ```yaml
    - id: dsh-lan-gateway
      config:
@@ -175,11 +120,7 @@ lan_gateway disable
        allowInsecurePlaintext: true
    ```
 
-自签名证书在**首次启用 TLS 时生成一次**，持久化于 `~/.dsh/lan-gateway/tls/`
-（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用同一张证书；
-`lan_gateway tls-regenerate` 可随时换发新证书（新密钥）并热重启监听器。
-
-或用自己的证书（例如 `/etc/letsencrypt/live/example.com/` 下签发的 PEM）：
+用自己的证书（比如 Let's Encrypt 签发的 PEM）：
 
 ```yaml
 - id: dsh-lan-gateway
@@ -190,140 +131,110 @@ lan_gateway disable
     tlsKeyPath: /etc/letsencrypt/live/example.com/privkey.pem
 ```
 
-启用 TLS（或声明受信终止代理）后，登录 cookie 自动带 `Secure`；监听器自身是 HTTPS 时，
-网关响应（登录页 / 重定向 / 拒绝）带 HSTS。自签名证书首次访问会看到浏览器警告，属预期行为。
-
-默认 `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。
-
-## 安全模型
-
-- **来源分级**：仅依据 `socket.remoteAddress`（IPv4-mapped IPv6 会先解包）把请求分为
-  loopback / lan / internet 三档，绝不信任 `X-Forwarded-For`。**分级本身不授予任何访问**
-  ——默认每一档都必须出示有效网关会话，否则 302 到 `/__login`。
-- **LAN 免密是显式 opt-in**：`lanPasswordless: true` 只让命中 `lanCidrs`（或 loopback）的
-  来源跳过**网关自己的登录页**；上游 dsh 若 ≥ 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 且同源的请求应答（本地用户 / 本机能读 `~/.dsh` 的进程）。远程管理走
-  `lan_gateway` 工具。
-- **CSRF / 跨站围栏（HTTP 与 WebSocket）**：因为网关把 Origin 改写回 loopback、会蒙蔽
-  dsh 自身的 CSRF 防线，网关在改写前对每个转发请求自检：`sec-fetch-site: cross-site`
-  直接拒绝；Origin 必须匹配访问者实际使用的网关权威来源；状态变更方法与 WebSocket
-  升级请求**必须携带同源 Origin**，否则 403。
-- **密码未设置时拒启**：无论来源如何，未设密码一律拒绝监听——杜绝把远程代码执行门户
-  开放给任何非本机来源。
-- **WebSocket**：`/api` 升级请求同样过登录校验、同源 Origin 校验，再拼接转发给 dsh，
-  并纳入会话撤销（epoch 变化即断开）。
-
-## 版本兼容（0.5.0 的加载失败与修复）
-
-0.5.0 及更早版本装在 **dsh ≥ 0.1.2-rc.1** 上会让整个 plugin tree 起不来：
-
-```
-Error: dsh: plugin tree failed to load: ...
-SyntaxError: The requested module '@deepseek-ai/dsh-settings' does not provide an export named 'settingsNamespace'
-```
-
-`@deepseek-ai/dsh-settings` 自 `0.1.2-rc.1` 起删掉了 `settingsNamespace()` 这个品牌化辅助
-函数（命名空间改为 `register()` 内部校验的普通字符串字面量），旧版插件在 ESM 链接期就失败；
-cordis 的 include 一旦失败会连坐整棵树，所以表现是**所有插件都起不来**，而报错点看着像隔壁
-插件的名字。0.5.1 移除了该导入——运行时行为不变（新旧版本的 `register()` 都按同一个
-`NAMESPACE_PATTERN` 校验并原样接受这个字面量），因此 0.5.1 在 `0.1.0-rc.6` 到 `0.1.5-rc.2`
-的底座上都能加载。
+自签名证书在首次启用 TLS 时生成一次，落到 `~/.dsh/lan-gateway/tls/`（`selfsigned.crt` / `selfsigned.key`，0600），之后重启复用。要换新证书用 `lan_gateway tls-regenerate`，它会换掉密钥并热重启监听器。
 
-升级：`pnpm add @riceawa/dsh-lan-gateway@0.5.1`（或重新 `pnpm install` 走 link/github 安装）。
+监听器自身是 HTTPS 时，网关的响应（登录页 / 重定向 / 拒绝）带 HSTS。
 
-## 从 v0.4（及更早）升级
+### 关于 `Secure` cookie
 
-1. **把底座升级到 dsh ≥ 0.1.2-rc.1**（含 QVD-2026-57410 上游修复）。低于该版本时本插件
-   仍可运行，但 `lanPasswordless` 会拒绝启用（fail-closed）。
-2. 若配置里写过 `authRequired: false`：删除它。现在认证恒为必需；LAN 想免密改为显式
-   `lanPasswordless: true`。
-3. 若以明文（无 TLS）运行且从未设置过密码：升级后 `enable` 会拒绝。请启用 TLS /
-   声明 `trustedTerminator` / 显式 `allowInsecurePlaintext: true` 之一，并先
-   `lan_gateway set-password`。
-4. 曾以“免密 + 伪造 Host”形态暴露过受影响的 dsh 实例：按“可能已失陷”处置——轮换模型 /
-   系统凭据，并检查是否有未知登录会话。
+启用 TLS 或声明受信终止代理后，登录 cookie 自动带 `Secure`。但「声明了受信代理」只说明前面有个代理，不说明浏览器到代理这一段是加密的。
 
-一步到位迁移示例（HTTPS 自签名 + LAN 免密，本机已跑通）：
+如果那个代理只做明文鉴权、浏览器以 `http://` 访问（代理再以明文转发回本端口），自动推断会把 `Secure` 加上，而浏览器拒收明文 http 上的 Secure cookie。结果是密码校验通过、cookie 存不下，每次都被弹回 `/__login`，无限循环。这种部署要显式关掉：
 
 ```yaml
 - id: dsh-lan-gateway
   config:
     enabled: true
-    tlsEnabled: true
-    tlsMode: self-signed
-    # 证书 SAN 覆盖所有接入方式：回环 / 主机名 / LAN IP / Tailscale IP。
-    # Tailscale 走 100.64.0.0/10（CGNAT），按默认 lanCidrs 归为 internet，
-    # 仍需密码登录，不会因 lanPasswordless 而豁免。
-    tlsSelfSignedHosts: localhost,my-host,192.168.1.20,100.99.1.2
-    lanPasswordless: true   # LAN/loopback 免登录；需 dsh ≥ 0.1.2-rc.1 上游会话底座
+    gatewayPort: 8080
+    trustedTerminator: nginx
+    secureCookies: false   # 浏览器 → nginx 是明文 http，不能带 Secure
 ```
 
-首次以 `https://<主机名|LAN-IP|Tailscale-IP>:3081` 访问会看到自签名证书警告（预期）。
-证书在首次启用 TLS 时生成一次并持久化到 `~/.dsh/lan-gateway/tls/`；若已有一张旧证书，
-**必须用 `lan_gateway tls-regenerate` 重新签发**，新的 `tlsSelfSignedHosts` 才会进入 SAN。
+`lan_gateway status` 会如实报出实际生效的属性，以及声明的代理属于 TLS 还是明文入口。设置页里对应「自动 / 始终 Secure / 不加 Secure」三档。
+
+注意 `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 就丢弃这条会话并重新换取。这仍是「单密码 = 单操作者」：通过网关登录的人骑同一条上游会话，持钥的上游才是真正的授权主体。
+- **登录页**。`/__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` 工具。
+- **CSRF 围栏**（HTTP 与 WebSocket）。网关把 Origin 改写回 loopback，会蒙蔽 dsh 自身的 CSRF 防线，所以在改写前对每个转发请求自检：`sec-fetch-site: cross-site` 直接拒；Origin 必须匹配访问者实际使用的网关权威来源；状态变更方法与 WebSocket 升级请求必须携带同源 Origin，否则 403。
+- **没设密码就拒绝监听**，跟来源无关。
 
-## 登录页截图（预期）
+## 登录页
 
-远程来源打开 `http://<主机>:3081/` 时，先看到网关自带的登录表单（`/__login`），
-输入正确密码后签发会话 cookie 并跳回 `/`。
+远程来源打开 `http://<主机>:3081/` 时先看到网关自带的登录表单，输入正确密码后签发会话 cookie 并跳回 `/`。
 
 <p align="center">
   <img src="assets/login-screenshot.webp" alt="网关登录页截图" width="320" />
 </p>
 
-## UUID shim 说明（v0.2.0 新增）
+## UUID shim
 
-**问题**：网关以 `http://<LAN-IP>:3081` 服务页面，浏览器视其为不安全源，
-`crypto.randomUUID()`（secure-context-only）为 `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 在**模块级**（一被浏览器求值、早于任何官方代码铸造 id）给
-`Crypto` 原型补一个 `crypto.getRandomValues()` 版 `randomUUID`（RFC 4122 v4；
-`getRandomValues` 在所有源都可用）。安全源 / Node ≥19 下为 no-op，不影响任何行为。
+client bundle 在模块级给 `Crypto` 原型补一个基于 `crypto.getRandomValues()` 的 `randomUUID`（RFC 4122 v4，`getRandomValues` 在所有源都可用）。它在浏览器求值时就执行，早于任何官方代码铸造 id，所以对官方所有调用点（含以后新增的）一律生效，不用改 DSH 源码。安全源和 Node ≥ 19 下是 no-op，不影响任何行为。
 
-**覆盖范围**：对官方所有 `crypto.randomUUID()` 调用点（含未来新增）一律生效，
-无需改动 DSH 源码。
+## 开发
 
-## 测试
+```bash
+pnpm test        # 93 项
+pnpm typecheck   # tsc 双端（host + client）
+```
+
+```
+✓ tests/gateway.test.ts               (27) 分类 / 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/uuid-shim.test.ts             ( 3) 不安全源补丁 / 安全源 no-op / v4 正确性
+✓ tests/x509.test.ts                  ( 6) 自签名证书 DER/SAN/签名/TLS 握手
+✓ tests/tls.test.ts                   ( 7) 证书持久化 / 重生成 / 自定义证书加载
+✓ tests/upstream-session.test.ts      ( 8) 真实回环令牌换取：cookie 名匹配 / 拒绝后重换 /
+                                           invalidate 重获取 / 日志播报 / 保住已持有会话
+✓ tests/settings-card.test.ts         ( 6) 设置页字段编解码：三态 auto ↔ false 不可混淆
+```
+
+### 发布
+
+推 `v*` tag 触发 [`.github/workflows/release.yml`](.github/workflows/release.yml)：校验 tag 与 `package.json` 版本一致，跑 typecheck 和 test，发 npm，然后建 GitHub Release 并附上 `pnpm pack` 的 tgz。npm 侧走 Trusted Publishing（GitHub OIDC），仓库里不需要 `NPM_TOKEN` secret。`lib/` 被 gitignore，但 `prepack` 会构建，所以发布产物里始终有编译结果。
+
+首次启用要在 npm 包页面的 Settings → Trusted Publisher 配一次：
+
+| 字段 | 值 |
+| --- | --- |
+| Organization or user | `rice-awa` |
+| Repository | `dsh-lan-gateway` |
+| Workflow filename | `release.yml` |
+| Environment | 留空 |
+
+配好之前 tag 推送会在 `npm publish` 一步以 403 失败（fail-closed，不会留下半个 Release）。改完不用重新打 tag，重跑那次 run 即可。
+
+本地手动发布走 checkout 里的 `.npmrc` token（该文件不入库）：
 
 ```bash
-pnpm test
-# ✓ tests/gateway.test.ts               (27) 分类 / HMAC cookie / epoch / 密码状态 / 限流
-# ✓ tests/start-guard.test.ts           (12) fail-closed 启动守卫 / 配置路由回环围栏
-# ✓ tests/integration/gateway.test.ts   (17) 真实网关端到端：全来源登录 / LAN 豁免 /
-#                                            跨站 403 / 升级拒绝 / cookie 属性 / epoch 撤销 / 会话中继
-# ✓ tests/uuid-shim.test.ts             ( 3) 不安全源补丁 / 安全源 no-op / v4 正确性
-# ✓ tests/x509.test.ts                  ( 6) 自签名证书 DER/SAN/签名/TLS 握手
-# ✓ tests/tls.test.ts                   ( 7) 证书持久化 / 重生成 / 自定义证书加载
+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 附件
 ```
 
-## 安全评估与修复记录
+## 安全评估
 
-0.5.0 的默认拒绝模型源自针对 QVD-2026-57410（DSH Web API 的 Host 信任缺陷）的加固，
-相关文档收在 [docs/security/](docs/security/)：
+0.5.0 的默认拒绝模型源自针对 QVD-2026-57410（DSH Web API 的 Host 信任缺陷）的加固，相关文档在 [docs/security/](docs/security/)：
 
-- [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
-  实施状态（0.5.0 落地差异）。
-- [上游研究](docs/security/qvd-2026-57410-research.md)——公开通告 / 上游提交与版本核对。
+- [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)：公开通告、上游提交与版本核对。
 
 ## 许可
 
 [MIT](./LICENSE)
+
+各版本改了什么见 [CHANGELOG.md](CHANGELOG.md)。

package/lib/client.js

@@ -50,6 +50,11 @@ window.__ModuleLoader__.load({
 				"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）",
@@ -96,6 +101,11 @@ window.__ModuleLoader__.load({
 				"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)",
@@ -115,6 +125,12 @@ window.__ModuleLoader__.load({
 		function labels() {
 			return (typeof navigator !== "undefined" ? navigator.language : "en").toLowerCase().startsWith("zh") ? LABELS.zh : LABELS.en;
 		}
+		/** The three states of a tri-state field, in display order. */
+		const TRISTATE_OPTIONS = [
+			"auto",
+			"true",
+			"false"
+		];
 		const FIELDS = [
 			{
 				field: "enabled",
@@ -176,6 +192,10 @@ window.__ModuleLoader__.load({
 				field: "trustedTerminator",
 				kind: "text",
 				optional: true
+			},
+			{
+				field: "secureCookies",
+				kind: "tristate"
 			}
 		];
 		function formatValue(def, value) {
@@ -184,6 +204,7 @@ window.__ModuleLoader__.load({
 				case "number": return typeof value === "number" ? String(value) : "";
 				case "cidrs": return Array.isArray(value) ? value.join(", ") : "";
 				case "select": return typeof value === "string" ? value : def.options?.[0] ?? "";
+				case "tristate": return value === true ? "true" : value === false ? "false" : "auto";
 				case "text": return typeof value === "string" ? value : "";
 			}
 		}
@@ -219,6 +240,17 @@ window.__ModuleLoader__.load({
 					kind: "set",
 					value: trimmed
 				} : void 0;
+				case "tristate":
+					if (trimmed === "auto") return { kind: "clear" };
+					if (trimmed === "true") return {
+						kind: "set",
+						value: true
+					};
+					if (trimmed === "false") return {
+						kind: "set",
+						value: false
+					};
+					return;
 				case "text": return trimmed === "" ? def.optional ? { kind: "clear" } : void 0 : {
 					kind: "set",
 					value: trimmed
@@ -348,38 +380,42 @@ window.__ModuleLoader__.load({
 							children: hint
 						})]
 					});
-					case "select": return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-						style: styles.field,
-						children: [
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
-								style: styles.label,
-								htmlFor: `lan-gw-${field}`,
-								children: label
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("select", {
-								id: `lan-gw-${field}`,
-								style: styles.input,
-								value: text,
-								disabled: saving,
-								onChange: (e) => stage(field, e.target.value),
-								children: def.options?.map((option) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
-									value: option,
-									children: option
-								}, option))
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-								style: styles.hint,
-								children: hint
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-								type: "button",
-								style: styles.reset,
-								disabled: saving || !drafts[field],
-								onClick: () => resetField(def),
-								children: t.reset
-							})
-						]
-					});
+					case "select":
+					case "tristate": {
+						const options = def.kind === "tristate" ? TRISTATE_OPTIONS : def.options ?? [];
+						return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							style: styles.field,
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("label", {
+									style: styles.label,
+									htmlFor: `lan-gw-${field}`,
+									children: label
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("select", {
+									id: `lan-gw-${field}`,
+									style: styles.input,
+									value: text,
+									disabled: saving,
+									onChange: (e) => stage(field, e.target.value),
+									children: options.map((option) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+										value: option,
+										children: def.kind === "tristate" ? t[`opt.${option}`] : option
+									}, option))
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									style: styles.hint,
+									children: hint
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									style: styles.reset,
+									disabled: saving || !drafts[field],
+									onClick: () => resetField(def),
+									children: t.reset
+								})
+							]
+						});
+					}
 					default: return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						style: styles.field,
 						children: [