dsh-web-startup-auth

中文 | English

DSH（DeepSeek Harness）远程 Web 启动 + 用户名/密码认证插件。

⚠️ 版本跟进声明：本项目只跟进官方 dsh 的正式发布通道（next dist-tag），不跟进 alpha 预览通道（当前基线：dsh 0.2.1-rc.2，依赖 5 个 @deepseek-ai/dsh-* 已 bump 到 ^0.2.1-rc.1（caret 在 0.2.1 线内自动解析到最新 rc）；适配审查与观察哨见 docs/upgrade-dsh-0.2.0-playbook.md）。0.2.1 线双时代兼容已落地并随 bump 生效（通配 --host 的 schema 拓窗、LAN 信任的官方消费路径、TLS/--public-url 透传；在 0.2.1 之前的 dsh 上这些新 flag 会明确报错而非静默忽略）。

原版 @deepseek-ai/dsh-web-app/startup 出于安全考虑硬拒绝 --host 0.0.0.0；本插件替换它，并配一个带登录/注册页的认证插件，让 dsh web 可以在局域网（或任何非回环接口）上安全暴露浏览器界面。

特性

• 远程启动：--host 0.0.0.0 可用，替代原版启动器的硬性拒绝；具体 IP 字面量（如 --host 192.168.1.5、--host ::1、--host fd00::1）与通配 :: 同样可用（#35；非规范 IPv6 拼写自动规范化，带 zone 的（%eth0）与 IPv4-mapped（::ffff:a.b.c.d）写法拒绝）。纯 IPv6 网络下 0.0.0.0 只绑 IPv4、界面不可达；:: 在 Linux 默认双栈（net.ipv6.bindv6only=0），同时监听 IPv6 与 IPv4-mapped，比 0.0.0.0 覆盖更全；bindv6only=1 的系统上 :: 仅 IPv6。另透传上游两个启动能力（需 dsh ≥ 0.2.1）：--public-url <url>（声明对外访问 URL）与 --tls-cert/--tls-key（直连 HTTPS，见「安全说明」）；在低于 0.2.1 的 dsh 上使用会明确报错提示需要 dsh ≥ 0.2.1，而不是静默忽略。
• 登录/注册页：远程访问首次会引导设置管理员账号密码，之后进入登录页；与 DSH 黑白蓝风格一致；颜色跟随系统明暗偏好（prefers-color-scheme）。
• 免登录的本地访问：判定依据是请求本身而非启动参数——TCP 对端地址与 Host 头都是回环时才免认证。所以本机浏览器直接访问 http://127.0.0.1:<端口>/ 无需注册或登录；局域网客户端、以及反向代理转发来的请求（Host 是公网域名）一律需要会话。免登录不等于已登录：本机没有会话 cookie，认证页显示的是「管理员账号」而不是「当前登录」，也不会给出退出登录入口（没有会话可退）。
• 可选的「本机登录校验」：默认本机免登录；管理员可在设置面板 → 认证 → 登录要求里把这个开关打开，之后连本机地址也要求会话（多人共享服务器时用它禁止同机其他账号免登录）。开关须先有管理员账号才能启用（未注册时后端会拒绝，设置页会先引导去注册）。
• 可选的人机验证（滑块拼图）：应网友要求加上了没什么用的防人机验证，有兴趣可以开启试试 XD —— 在设置面板 → 认证 → 人机验证里滑动开启，登录时会让你把一块拼图拖进缺口。每张图里画了两个缺口：拼图块和真缺口是同一种形状（凸块方向每张随机：右/左/上/下，也可能没有凸块，共 5 种），旁边的假缺口形状永远不同，拼图块只塞得进形状相同的那个（纯装饰，脚本照样秒过）。 说它没什么用是有实测依据的：拼图的答案必须画在图上（人要看着它拖），所以脚本几十行就能读出来——本插件按常规做法实现的三种变体，用约 30 行脚本攻击的命中率分别是 100%（缺口涂暗）、100%（只描边）、97%（撒噪点，但那一版连人也解不出来）。之前试过的 4 位数字图片题同样被模板匹配打到 96.7%。当个乐子，别当安全边界。 详见 docs/agent/human-verification.md。
• 登录限流硬化：每 IP 10 分钟内 5 次失败锁 30 秒，外加全局指数退避——所有来源累计失败超过 20 次后按台阶翻倍（5 秒 → 10 秒 → …封顶 5 分钟），用来挡住"一千个 IP 各试几次"的分布式撞库；429 带 Retry-After。本机（真回环且未开启「本机登录校验」）豁免全局退避，避免攻击者借此把管理员锁在自己机器外面。
• 会话认证：登录后下发签名 cookie（dsh_sid，默认 14 天有效、可在设置面板调节（3–180 天档位），HttpOnly + SameSite=Lax；TLS 监听下自动追加 ; Secure）。
• API 保护：所有注册路由（/api/* 及第三方插件的 RPC 路由，除 /api/auth/* 与 /login）必须携带有效会话，否则返回 401/拒绝握手。
• 设置面板「认证」标签页：向 DSH 设置面板注入"认证"页，提供退出登录（仅在持有会话时出现）、修改用户名、修改密码与会话有效期档位选择。标签在导航栏里显示盾牌+勾图标（上游不允许注册方指定图标，由本插件在前端替换默认的齿轮）。界面颜色全部使用 DSH 主题 token，跟随明/暗主题自动切换（#25）。
• 远程场景修复（局域网 HTTP 访问的坑）：
  • crypto.randomUUID polyfill —— 非安全上下文下该 API 缺失，会导致所有 RPC 失败。
  • 原生浏览器认证桥接 —— dsh 0.1.2 起（当前基线 0.2.1-rc.2）上游自带浏览器认证（dsh-auth-* 签名 cookie），/api 与 index.html 一律要求携带、连回环都不豁免（本机也得先换 token URL）。本插件为已通过自己认证（dsh_sid 会话，或 TCP 对端 + Host 双回环的本地请求）的访问者自动补发该 cookie：页面导航经一次 200 跳板（meta refresh 回原路径）即带上、登录响应直接下发（不用 3xx：重定向响应里新设的 cookie 不会带给重定向目标，补发会被逐跳重放成 ERR_TOO_MANY_REDIRECTS），全程无需接触启动打印的 token URL——「账号/密码 + 可撤销会话」仍是唯一认证入口，上游 cookie 只是通过上游闸门的凭据。

安装

本插件是一个 DSH bundle（package.json 的 dsh.bundle.patch 声明了随包分发的 cordis.patch.yml）。用 dsh plugin 安装后，包会被加入 profile 的 dsh.profile.bundles，补丁层自动生效，无需手动编辑任何配置文件。

…