dsh-gateway-plugin
DeepSeek Harness Web 的访问密码网关插件：网关端口上不存在任何未认证可达的内容面——除登录/首次设置页外，一切请求（页面、静态资源、/api、WebSocket 升级）必须先通过验证；首次使用在登录页直接设置密码；密码可在设置页独立的"安全"页中修改。
为什么要用网关，而不是改 harness
DeepSeek Harness 的 Web 应用有意不提供鉴权（webserver 与 client-connection 包的已知限制里明确写出）：官方 web 启动器甚至拒绝 --host 0.0.0.0，/api 的 browser-trust fence 只是防 DNS 重绑（注释白纸黑字：explicitly not authentication）。官方推荐的加固方式就是在前方放置真正的反向代理。
本插件把这道"反向代理"以 harness 插件形式实现，直接装进 profile：
浏览器 ──> dsh-gateway（自己的监听端口，唯一对外入口）── 反代 ──> harness webserver（保持 127.0.0.1 回环绑定）
├─ 未认证的任何请求（页面/静态/API/WS）──> 拒绝：页面 302 到 /gateway/login，/api 401
├─ /gateway/login GET ──> 唯一未认证放行面：已配置密码 → 登录页；未配置 → 首次设置密码页
├─ /gateway/login POST ──> 密码校验（常量时间）→ 签发 HttpOnly 签名会话 cookie
├─ /api/* + /api/events.* WebSocket ──> 会话 cookie 或 Authorization: Bearer <密码>
└─ 认证后全部反代到 harness（改写 Host/Origin 使内部信任围栏放行）
安全要点：
- 绝对门禁：网关监听端口上只有
/gateway/login（GET 页面 + POST 登录/设密）是未认证可达的；没有 health 端点、没有其他例外。未通过验证的请求什么内容都拿不到（页面与静态资源 302 到登录页，/api 直接 401，WebSocket 升级拒绝）。
- 首次设置密码：部署还没有密码时，登录页呈现"设置访问密码"表单（两次输入），首个访问者设置成功后立即获得会话——这是唯一的引导信任路径。之后所有人用该密码登录。
- 修改密码：设置 → 安全（独立页面，不在"插件配置"里）→ 当前密码 + 新密码 ×2；旧密码在 Host 侧校验。修改成功后所有已登录会话立即失效（会话签名密钥轮换）。
- 防爆破：密码比对为 SHA-256 后
timingSafeEqual（恒定时间）；登录失败按来源地址限流（默认连续 5 次失败冷却 30 秒）。
- 会话令牌：HMAC-SHA256 签名的无状态 cookie（
HttpOnly、SameSite=Lax），签名密钥每次进程启动随机生成——重启即全员重新登录，有意 fail-closed。
- 信任边界：代理改写 Host/Origin 为回环上游，harness 内部围栏与其回环受限特权方法（
settings.*、credentials.* 等）接受请求；harness 本身应保持绑 127.0.0.1（默认如此，且官方禁止 0.0.0.0）。边界说明：dsh 本机回环端口上的直连等同于本机管理员（他们本就能读磁盘、改配置），不属于远程攻击面。
从 GitHub 安装
前提：dsh CLI 已安装（或用源码检出，从仓库根执行 pnpm dsh ...）。
dsh plugin --profile web add github:laoin114514/dsh-gateway
推荐固定到具体 commit（防止仓库后续推送悄悄改变安装时拿到的代码）：
dsh plugin --profile web add github:laoin114514/dsh-gateway#<commit-sha>
构建产物已经随仓库提交（lib/ 目录），git 安装拉取后无需运行任何构建脚本、无需放行 build 权限，安装即用。首次安装/升级后启动 dsh web：
dsh-gateway: http://127.0.0.1:3088 (gateway, password required) -> harness http://127.0.0.1:3080
打开网关地址（而不是 harness 地址）使用。首次访问时登录页会引导你设置访问密码；之后每次访问输入该密码。
安装失败排查
如果 dsh plugin add github:... 报 ERR_PNPM_ENOENT ... importPackage ..._tmp_...（常见于之前失败安装留下的半装目录），先清理再重装：
dsh plugin --profile web remove dsh-gateway-plugin # 或手动删除
# 删除 $DSH_HOME/profiles/web/node_modules/dsh-gateway-plugin 后：
rm -rf "$DSH_HOME/profiles/web/node_modules/dsh-gateway-plugin"
dsh plugin --profile web add github:laoin114514/dsh-gateway
暴露到网络
默认网关只绑本机（gatewayHost: '127.0.0.1'）。在 profile 的 cordis.patch.yml（$DSH_HOME/profiles/web/cordis.patch.yml）里覆盖：
- id: dsh-gateway
config:
gatewayHost: '0.0.0.0'
源码检出下的本地开发
依赖本仓库源码联动时（改 harness 本地包），在仓库根执行 pnpm dsh web --patch <dsh-gateway>/cordis.dev.yml --no-open --port 3082（注意：该 overlay 方式下浏览器侧的"安全"页不会加载——只有 profile 行才能被客户端模块系统发现）。
配置（cordis.patch.yml 中 dsh-gateway 行）
| 字段 | 默认 | 说明 |
|---|
gatewayHost | '127.0.0.1' | 网关监听地址；对外暴露设为 '0.0.0.0'（harness 本体仍保持回环） |
gatewayPort | 0 | 网关监听端口；0 由系统分配（启动日志打印实际地址） |
sessionTtlHours | 24 | 会话 cookie 有效期（小时）；密码修改或进程重启也会使所有会话失效 |
minKeyLength | 8 | 密码最短长度 |
maxLoginFailures | 5 | 连续失败多少次后进入冷却 |
loginCooldownSeconds | 30 | 冷却窗口（秒） |
accessKey | （空） | 初始密码；为空即进入"首次设置"模式（此时配置此字段等价于预先指定密码）。设置服务就绪时该值作为组合 base 层，可被安全页覆盖 |
密码本身存放在设置命名空间 dsh-gateway（字段 accessKey，用户设置文件），声明为 role('secret')，任何 wire 响应都不会携带它。
已知取舍
- 不提供 TLS：如需公网/跨网段传输，请在网关前再放一个终结 TLS 的反向代理，或把网络限制在内网。
- 密码以明文存于用户设置文件（与 harness 其他
role('secret') 字段一致）；请按机密文件的权限管理该文件。
- 会话在进程重启后全部失效（签名密钥随机生成），属有意行为。
开发
pnpm install && pnpm run build # esbuild 打包 + 两个 tsc 声明产物
pnpm test # node:test 集成冒烟（真实 Cordis Context + 假上游）
pnpm run typecheck
产物：
lib/index.js — Host 侧网关插件（ESM，仅 @deepseek-ai/* 保持外部解析）lib/client.js — 浏览器侧"安全"设置页（dsh 客户端模块系统的 lazy-CJS factory 格式）lib/types/ — 两侧的声明文件
结构
| 文件 | 职责 |
|---|
src/index.ts | 网关插件本体：独立监听、反代、WebSocket 隧道、登录/设密/改密端点、设置命名空间接线 |
src/session.ts | 签名会话 cookie（签发/校验/轮换签名密钥） |
src/key.ts | 恒定时间密码比对 |
src/lockout.ts | 登录失败的按地址限流 |
src/pages.ts | 登录/首次设置页 HTML（零外部资源、内联 CSS/JS） |
src/client/ | "安全"设置页（settings.section 槽位，id security） |
cordis.patch.yml | bundle 层：插入 dsh-gateway 行（Host 插件 + dsh.client 浏览器贡献） |
cordis.dev.yml | 本地开发 overlay（file:// 行，直接 --patch 使用） |
tests/gateway.smoke.mjs | 集成冒烟：首次设密、无认证面断言、302/401、cookie 会话、Bearer、限流、密码轮换 |
