dsh-web-pass
v0.3.7
Published
DSH web-password gate: multi-password multi-upstream reverse proxy (one password, one backend; add upstreams from the settings page) + forced first-time setup + Settings 'Web password' tab + 2-day sliding sessions + size-capped access log + non-loopback s
Readme
dsh-web-pass
v0.3.7
- 兼容 DSH v0.1.5-rc.1：设置页 RPC 改走 DSH Connection 的
/api/<endpoint>exact Fetch route，不再占用共享/apiinterceptor，会话列表等普通 API 恢复正常。 - 修复改密码失效：设置页「密码重设」与首次强制设密此前必抛
ReferenceError（调用了不存在的writePasswordFile）。 - 修复「删过的上游加不回来」：同一
host:port删除后再新增，现在复用原条目序号，不再报错。 - 远程 / LAN 访问更稳：在原有的
client-connection模块改写之外，另加__DSH_TRANSPORT__.ownsHost前置垫片双保险。
不改动已有密码、上游条目或会话数据。
简体中文 | English
一个零依赖的 DeepSeek Harness Web 插件：在 DSH 前面加一道网页密码门，并支持一密码一后端的多入口分流。
浏览器 → (TLS / 反向代理) → dsh-web-pass :3081 ┬→ 127.0.0.1:3080（主人 DSH，装本插件）
├→ 127.0.0.1:3085（访客干净 DSH，可选）
└→ 127.0.0.1:5101（openclaw、fnOS 等本地服务，可选）功能速览
认证与会话
- Cookie 会话认证跑在反向代理上（不是 nginx Basic Auth）。密码错误累计达上限（默认 3 次）→ 真锁定（401）：自最后一次失败起计时，连续触发按 2× 递增（至多 16 倍）；成功登录不清零失败计数。
- 首次访问强制设置密码（输入两次；须 ≥8 位且含大小写字母和数字）。
- 会话 2 天滑动（v0.3.2 起，原 24 小时固定）：每次鉴权时剩余不足 1 天即续到 2 天——天天用永不掉线，闲 2 天重登。
- 哪里都能退出（v0.3.3；v0.3.6 起仅 POST）：非主人条目的页面右下角自动出现「🚪 退出」浮标，点击即清会话回登录页；
/gate/logout只接受 POST（防 Logout CSRF）。
多密码多上游（访客模式，v0.3.2）
- 一个密码进一个后端：主人密码进老 DSH，访客密码进干净 DSH，还能再挂 openclaw、fnOS 等本地服务。登录还是同一个密码框；报错永远笼统，不透露是哪条。
- 设置页直接加上游（v0.3.3）：上游表里填「标签 + 上游」点「增加」即可，即时生效、无需重起；新条目默认停用、无密码；存数据目录
upstreams.json，重启保留，patch 行照旧可用。 - 详见下文多密码多上游。
对 DSH 的增强
- 自动代持 DSH 内置认证（v0.3.0）：与 DSH 同进程，自动换取并注入 DSH 的浏览器 cookie——浏览者只需过本密码门，无需再处理 DSH 的 token/cookie。
- 非 loopback 页面解锁 Host 设置（v0.3.1）：经 IP / 域名访问时，设置里的「插件配置」「模型」「常规」不再空白（见下文）。
日志与可观测
- 登录访问日志内嵌在
/dsh-logs/：只记录密码验证相关请求，按大小轮转（默认 1MB × 7 份），体积有硬上限；IP 用 HMAC-SHA256 假名化 + 网络前缀，不落原始 IP。
v0.3.4 修复
- 代理响应不再强加安全头：此前每个经门响应都被盖上
X-Frame-Options: DENY等安全头（本意是保护登录页），会把 fnOS 等后端用同源 iframe 嵌套件应用的页面整页挡成「拒绝连接」——Docker / 套件经门全空白即此因。现在这些头只作用于门自身页面（登录页 / 日志页），代理响应还原为上游原始响应头；上游自带的安全头照常生效。
v0.3.5 安全加固
- 防爆破改为真锁定：失败计数不再被成功登录清零（旧版「任一条目成功一次即清零」可被用来无限爆破其它条目——已实测复现）；超限后自最后一次失败起锁满
loginLockMs × 退避倍数，连续触发按 2× 递增（至多 16×）；退避倍数在锁到期后保留，静默 1 小时无失败才回到 1×；锁定期内的试探不计失败、不延长锁定。 - 注入/改写响应缓冲设 8MB 上限：超大
text/html自动降级为流式透传（放弃注入），客户端中途断开立即掐断上游——防把与 DSH 同进程的门拖 OOM。 - 转发统一剥离门会话 cookie：
dws_session不再随请求 / WebSocket 握手发给任何上游（旧版会原样转发给dsh:false上游）。 - 首次设密加一次性令牌：
/gate/setup必须携带 GET/gate-setup下发的 HttpOnly cookie，跨站自动提交表单无法抢注密码门。 - 会话绑定上游身份：会话同时校验条目序号与上游
host:port；patch 调整行序 / 改端口重启后旧会话自动作废（无需再手动清sessions.jsonl）。升级到 v0.3.5 后需重新登录一次。 - 重登轮换会话：已登录再登录会签发新 token 并吊销旧 token（旧版会残留孤儿会话）。
- 其它：上游空闲 2 分钟超时、请求侧中止、并发连接上限 512、502 不再泄漏内部地址与错误细节、落盘失败不再静默（记入错误日志）、
resolveEntries对 patch 行 host:port 查重。 - 同版模块化重构：
lib/按领域拆为 9 个内聚模块（proxy 转发核心 / index 装配+RPC / 条目表 / 会话存储 / 门页面 / 代持 / 日志 / 密码学 / 限速器 / 数据目录），合并重复实现；对外导出面不变，纯代码搬家零行为变更。
v0.3.6 安全加固（hardening，无新功能、无数据迁移）
- 上游回包不得写门保留 Cookie：
dws_session/dws_setup在透传、改写、WebSocket 握手三个出口统一过滤（sanitizeUpstreamSetCookie），上游只能写自己的业务 Cookie。 - 入向转发头清洗：客户端自带的
Forwarded/X-Forwarded-*/X-Real-IP等一律丢弃，由门按trustProxy重建规范值（默认只信 socket 直连地址；可信前代后取左端值）——上游看到的不再是可伪造的客户端断言。 - 登出仅 POST：
GET /gate/logout返回 405（防 Logout CSRF），退出浮标改走 POST。 - 会话吊销持久化重试：落盘失败立即全量压实重试一次，仍失败记 error（措辞：失败可观测，但吊销持久化不保证——磁盘异常期间吊销、随后重启，旧会话可能复活；属已知一致性边界，不 fail-closed）。
v0.3.7 修复与兼容（DSH v0.1.5-rc.1）
- 设置页 RPC 迁出共享
/apiinterceptor：原实现把处理函数注册成共享/api通道的唯一 interceptor，而 DSH 0.1.5 的 API Gateway 也依赖该入口——结果普通/api请求（尤其会话列表）无法落到 Gateway fallback。现在每个 endpoint 独占一条POST /api/<endpoint>exact Fetch route（ctx.connection.fetch.register），照常经过 Connection 的 Host/Origin 与浏览器认证，其余 API 不受影响。 - 修复改密码 / 首次设密失效：
setPasswordHash调用了从未定义也从未导入的writePasswordFile（v0.3.5 模块化拆分时漏改），因此设置页改密码与首次强制设密都会抛ReferenceError，被错误处理吞成一句提示。已修正为writePasswordHash。 - 修复「删过的上游加不回来」：软删的条目仍保留在条目表中（序号不动），而追加逻辑按
host:port去重，于是同一地址删除后再新增会被跳过并报「运行时上游未加入内存条目表」。现在改为复用原条目序号并解除软删——顺序、序号（会话绑定键）都不变；与 patch 行地址冲突时明确报错。 - 远程 / LAN 访问双保险：除原有的
client-connection模块定向改写外，另在页面<head>注入前置垫片把__DSH_TRANSPORT__.ownsHost置真（早于所有客户端模块求值）；改写匹配同时放宽到整条dsh-client-connection路径。 - 新增上游更可观测：服务端记录「新增上游请求 / 成功 / 失败」日志；设置页新增即刻显示新条目（乐观更新），8 秒无响应给出明确提示，便于对照 dsh 日志定位。
插件仓库里不落任何运行时数据——数据都在
$DSH_HOME/dsh-web-pass/（密码哈希、会话、日志）。
工作原理
插件在 dsh web 进程内部运行一个反向代理：把 Host/Origin 改写为回环地址，从而不改任何 DSH 配置就能通过 DSH 的浏览器信任检查，并在其上叠加 cookie 密码认证。TLS 通常由上游终止（反向代理 / 隧道 / nginx）。
- 门不转发压缩协商（v0.3.3）：转发请求一律剥掉
accept-encoding，上游以明文回（nginx 等默认开 gzip 会让注入整体跳过——polyfill / 模块改写 / 退出浮标全依赖明文），压缩交给门前面的反向代理做。 - 对
dsh: true的后端：代持 DSH 认证 + 定向改写client-connection模块（见下文两节）。 - 对
dsh: false的后端（fnOS、openclaw 等）：原样透传，不带 DSH cookie，也不强加安全头。
安装
方式一：从 npm 安装（推荐）
dsh plugin --profile web add dsh-web-pass
# 然后重启 dsh web方式二：从源码安装
git clone https://github.com/linz919/dsh-web-pass.git
dsh plugin --profile web add ./dsh-web-pass -w
# 然后重启 dsh web确认已加载：
ss -tln | grep -E ':3081|:3082'配置
所有选项都有内置默认值——完全不写任何配置也能正常工作（日志轮转默认即 1MB × 7 份）。即使 cordis.patch.yml 在安装其他插件时被覆盖、丢失自定义配置，功能也不受影响：日志轮转回落到内置默认，访问密码的环境变量名回落到内置的 DSH_WEB_PASS_PASSWORD。
来自插件配置（cordis.patch.yml 的 config 段，可选）：
| 选项 | 默认值 | 说明 |
|---|---|---|
| port | 3081 | 反向代理监听端口 |
| logViewerPort | 3082 | 内嵌日志查看器端口 |
| maxLoginAttempts | 3 | 锁定前允许的密码错误次数 |
| loginLockMs | 60000 | 真锁定基准时长（毫秒，自最后一次失败起计；连续触发按 2× 递增至 16×） |
| passwordEnv | DSH_WEB_PASS_PASSWORD | 提供密码的环境变量名 |
| trustProxy | false | 是否信任 X-Forwarded-For / CF-Connecting-IP 头（用于访客 IP 识别与登录限速） |
| clientHostTrust | true | 非 loopback 页面（IP/域名访问）也启用 Host 设置文档；false 恢复 DSH 原生行为（仅 localhost 可见设置内容） |
| logMaxBytes | 1048576 | 访问日志单文件大小上限（字节），达到即轮转，下限 64KB |
| logMaxFiles | 7 | 轮转后保留的历史文件份数（access.log.1 … access.log.N），超出自动删除 |
| upstreams | [] | 多密码多上游表（见下文）：每条含 label / passwordEnv / host / port / clientHostTrust / dsh / enabled；不配即单密码行为 |
关于
trustProxy：默认关闭时，访客 IP 与登录限速只依据 socket 直连地址——客户端伪造任何转发头都不被采纳。开启后取X-Forwarded-For/CF-Connecting-IP作为限速键，因此仅当网关前面部署了会覆写这些头的可信反代（nginx 配proxy_set_header X-Forwarded-For $remote_addr;、Cloudflare 隧道等）时才开启；反代若只是透传，伪造 XFF 等于给攻击者无限个限速键。
密码存储
- 默认为空。 首次访问 3081 会强制进入设置页（输入两次；须 ≥8 位且含大小写字母和数字）。
- 优先级（每条独立）：环境变量（如
DSH_WEB_PASS_PASSWORD，设到dsh web服务进程环境里）> 文件$DSH_HOME/dsh-web-pass/password（管理员条目）或password.<i>（第 i 条，scrypt 哈希）。 - 如果清空（删除环境变量 / 文件）→ 下次访问重新进入设置页。
cordis.patch.yml只引用环境变量名——绝不要把密码明文写进去（该文件会进 git / 仓库）。- 设置页改密码不用输原密码；保存后该条旧密码立即作废、其会话全部吊销（2 天滑动会话也一样）。主人忘密码：删文件（顺手把同目录
sessions.jsonl一起删更干净）即回强制设置页；用了环境变量的先unset再重起。
多密码多上游（访客模式）
添加与启停
- 加一行 = 加一个密码 + 一个后端：优先在设置页「上游表」里填标签 + 上游（host:port）点「增加」（即时生效、无需重起；新行默认停用、无密码）；也可改
cordis.patch.yml的upstreams加一条后重起dsh web。页面上新增的行保存在$DSH_HOME/dsh-web-pass/upstreams.json（0600，重启保留），与 patch 行共存、追加在其后；密码值可在设置页「网页密码」活改，不用重起。 - 停用某条即刻踢掉其会话（无需重起）；删除某条即刻失效（软删：行隐藏、序号不变），
patch里删行重起则彻底消失；管理员条目不可停用、不可删除。删除过的地址可以再次新增——会复用原条目序号并解除软删，不会重复占位，也不影响其它条目已绑定的会话；若与patch行地址相同则明确报错。
密码规则
- 访客密码只能主人设：没有注册页。设置页上游表里点对应行的「密码重设」，或下方统一框选条目再设（条目下拉点表行自动选中）。
- 各条密码必须不同：设置时若与其它条目的环境变量明文撞车会被拒绝。
登录行为
- 登录同一个框：输错统一报「密码错误，请重试」，不透露是哪条；限速按来源 IP 全局计（成功登录不清零）。某条后端没起来，该条登录提示「该入口暂未启用」，主人照常用。
- 同浏览器多身份：cookie 按浏览器共享（不分标签页），同一浏览器一次只能保持一个条目登录；要同时用多个身份（如 DSH 与 fnOS 并开），开多个隐身窗口分别登录对应条目即可（隐身窗 cookie 独立），无需互相退出。
隔离与管理
- 访客看不见主人：推荐访客后端跑个干净 DSH（新端口 + 新数据目录，不装本插件），天然空记录；访客条目
clientHostTrust保持false（默认），访客设置页空白、改不了模型。门只管转，不管起——后端自己跑起来、只绑127.0.0.1。 - DSH 类后端才代持/改写：
dsh: true的条目各持一份 DSH cookie 并可改写模块；反代 openclaw、fnOS 等非 DSH 服务请设dsh: false（默认），原样透传，免得把 DSH cookie 带过去。 - 管理面只在主人间：设置页（含上游表、日志入口
/dsh-logs/）只存在于装了本插件的主 DSH；访客干净间不装本插件，访客碰不到管理面。 - 日志带入口：访问日志末尾多一列条目名（老行无该列照常显示
-），可按条目筛选。
条目序号与会话绑定（升级注意）
- 条目序号 + 上游地址 = 会话绑定键（v0.3.5）：会话签发时同时记录条目序号与该条上游
host:port，校验时两者必须同时匹配——手工调整 patch 行序、改端口后重起，旧会话自动作废（各端重新登录即可，不再需要手动清sessions.jsonl）。顺序仍为「管理员 → patch 行 → 页面新增行」，只追加、软删保序。 - 升级注意：两台 DSH 共用同一份程序，升一次；先重起主的验主人登录 + 设置页，再重起访客的验干净。
DSH 内置认证代持
DSH Web 自带一层浏览器认证（进程 launch-token 换 30 天 cookie）。本插件运行在 dsh web 进程内部，可经 ctx.connection.authenticatedUrl() 拿到带 process-token 的 URL，内部换取 DSH 的持久 cookie 后，注入所有转发到上游的请求与 WebSocket 握手——因此经密码门进入的浏览者永远看不到 DSH 的 "authentication required"。
- 自动：启动预热 + 每 6 小时静默刷新，DSH 重启后自愈（失效时下一请求自动重取）。
- 安全：launch-token 不经过插件进程间的转发路径，也绝不会到达任何上游或浏览器；对外仍只暴露密码门。（注：DSH 平台自身会把含 token 的启动地址打到服务 stdout——那是 DSH 行为，与本插件无关，请按 DSH 运维惯例保护服务日志。）
- 状态可见：设置页「网页密码」标签页新增
dshAuthHolding字段（是否已代持 DSH cookie）。 - 无配置项：只要
dsh web提供ctx.connection即自动启用；不可用时回退为旧行为（浏览者仍需 DSH token）。
非 loopback 页面解锁 Host 设置
DSH 客户端只在页面地址为 localhost/127.x 时才挂载宿主设置文档；经局域网 IP 或域名访问（包括走本密码门）时，设置一律降级为内存模式——设置里的「插件配置」「模型」「常规」等标签页会整页空白（插件清单、聊天等纯 RPC 功能不受影响）。
本插件用两道措施把该判定补为恒真：① 在代理层对 DSH 下发的 client-connection 模块做一次定向改写；② 在页面 <head> 后注入前置垫片，把 __DSH_TRANSPORT__.ownsHost 置真（早于所有客户端模块求值）。设置页在 3081（LAN IP / 公网域名）下完整可用；浏览器地址不变，密码门仍是唯一入口，服务端 /api 的信任校验不受影响。
- 默认开启；不需要时配置
clientHostTrust: false恢复 DSH 原生行为。 - 改写后的模块以
cache-control: no-cache下发。从旧版本升级后每台设备需强刷一次（Ctrl+F5）——旧模块此前按immutable缓存一年，普通刷新不会回源；强刷一次后即自动保持最新。 - DSH 未来版本若变更了判定代码（两个措施都落空），日志会提示「未找到 isLoopback 表达式」，此时设置页回到空白，其余功能不受影响，请随插件更新同步锚点。
访问日志
- 页面入口
/dsh-logs/（也可从设置页「访问日志」按钮打开）：只记录/gate-login、/gate/setup、/gate/logout的请求，按「方法 + 路径 + 状态码」判定语义：- ✅ 验证成功（POST 登录 → 302）
- ❌ 密码错误（POST 登录 → 200）
- 🔒 超次锁定（POST 登录 → 401）
- 👁 打开登录页 / 设置页（GET 浏览）
- 🚪 登出（POST logout）
- 🔑 首次设置完成（POST setup → 302）
- 时间使用服务器本地时区渲染；5 秒自动刷新；支持按 IP / 请求关键字筛选。
- 文件：
$DSH_HOME/dsh-web-pass/access.log—— 按大小轮转：单文件达到logMaxBytes（默认 1MB）就滚动为access.log.1，更早的依次后移为access.log.2…，最多保留logMaxFiles份（默认 7 份），最旧的自动删除。日志总体积因此有硬上限（默认约 8MB），不会随时间无限增长。 - IP 假名化密钥存于同目录
.hmac-key（自动生成，0600 权限）；不要删除它，否则同一 IP 会产生新的假名，聚合分析断档。
安全说明
- 一密码一后端（多密码多上游），无账号 / 2FA。
- 务必经 HTTPS 暴露（上游 TLS）；不要把纯 HTTP 端口直接映射到公网。
- 门自身页面（登录页 / 日志页）带
X-Frame-Options: DENY等安全头；代理响应不额外加安全头（v0.3.4 起），上游自带的原样生效。 - 登录限速与日志 IP 默认取 socket 直连地址（伪造转发头无效）；
trustProxy开启后改取X-Forwarded-For/CF-Connecting-IP作为限速键——只在会覆写这些头的可信反代之后开启，否则等于给攻击者无限个限速键。
版本历史
| 版本 | 要点 |
|---|---|
| v0.3.7 | 兼容 DSH v0.1.5-rc.1：设置页 RPC 迁出共享 /api interceptor，改用 /api/<endpoint> exact Fetch route（会话列表等普通 API 恢复）。修复：改密码 / 首次设密失效（writePasswordFile 未定义）；软删过的上游无法再加回（改为复用原条目序号）。增强：__DSH_TRANSPORT__.ownsHost 前置垫片 + 改写匹配放宽；新增上游日志与设置页即时反馈 |
| v0.3.6 | 安全加固：上游回包过滤门保留 Cookie（三出口统一）；入向转发头清洗+按 trustProxy 重建；登出仅 POST；吊销落盘失败重试+loud log |
| v0.3.5 | 安全加固：防爆破真锁定+指数退避（成功登录不再清零；退避倍数跨锁保留、静默 1h 重置）；注入响应 8MB 缓冲上限+断连中止；转发剥离门会话 cookie；首设一次性令牌；会话绑定上游身份（升级后需重登一次）；重登轮换会话；上游超时/请求中止/落盘错误日志。同版完成模块化重构：按领域拆为 9 个内聚模块，纯代码搬家零行为变更 |
| v0.3.4 | 修复：代理响应不再强加安全头（XFO DENY 挡掉 fnOS 同源 iframe 套件页，经门 Docker/套件全空白） |
| v0.3.3 | 设置页直接加上游（即时生效）；「🚪 退出」浮标；门剥 accept-encoding 保注入 |
| v0.3.2 | 多密码多上游（访客模式）；会话 2 天滑动；日志带条目列 |
| v0.3.1 | 非 loopback 页面解锁 Host 设置 |
| v0.3.0 | DSH 内置认证代持 |