前言¶
DeepSeek Harness（DSH）的 Web 界面默认通过 dsh web 打印的带 ?token=... 的 URL 完成鉴权。对长期在本机或内网使用 Web UI 的开发者来说，每次依赖终端里的链接并不直观；若把端口暴露到非本机环境，仅靠 launch token 也缺少可轮换、可锁定的账号层。社区插件 dsh-web-password-auth（维护者 Lstions，分类 admin-security）在 Host 原有 launch token 机制之上，为 Web UI 增加用户名与密码登录、持久会话，以及可选的 TOTP 双因素认证，并在应用内提供安全设置页。
这是什么¶
dsh-web-password-auth 是面向 dsh --profile web 的 Cordis 插件（当前版本 0.7.1，MIT 许可证）。它不改变「Host 仍负责 Web 服务与 launch token 交换」这一模型，而是在访问 / 与 /index.html 时先校验会话，通过后再把请求交给 Host 已注册的 fallback，从而在未登录时不放行未受保护的 Shell。
简要对照默认行为：
| 方面 | 默认 launch token | 本插件 |
|---|---|---|
| 首次访问 | 依赖 ?token=... URL |
可引导创建本地账号（或 token 登录后在设置里创建） |
| 后续访问 | 依赖 token 或 Host cookie 策略 | 签名 cookie 保持登录，直至主动登出 |
| 找回入口 | 终端重新打印 URL | launch token 仍为本地 fallback；亦可删除凭证记录重来 |
插件仓库：GitHub — Lstions/dsh-web-password-auth。社区目录页：skillhub.cn/plugins/Lstions/dsh-web-password-auth（独立社区站点，与 DeepSeek / 幻方无官方从属关系）。
核心功能¶
以下能力均来自插件 README 与 package.json 说明。
密码登录与持久会话。 首次访问（无账号时）出现创建账号流程；之后访问要求输入密码。服务端通过签名 cookie（HttpOnly）维持会话，浏览器重启后仍保持登录，直到在设置中登出或会话被撤销。
登出。 服务端清除会话 cookie；因 cookie 为 HttpOnly，仅 Host 侧可正确作废。
可选 TOTP 双因素。 与常见 Authenticator 应用兼容；注册时在设置页展示 QR 码（服务端 SVG）与 base32 密钥，减少手工抄写导致的注册失败。
保留 launch token 路径。 dsh web 打印的带 token URL 仍可登录，作为忘记密码时的本地恢复手段；插件追加 set-cookie 而非覆盖，避免破坏 token 交换返回的其他 cookie。
应用内安全设置。 登录后可在 Settings → Security（安全） 修改用户名、修改密码（会撤销全部会话）、开关双因素、登出。同一区块也会出现在 Plugins → Web Password Auth 插件页；无独立 /account 路由。Host 侧仅渲染必须存在的 /login 与首次 /setup 页。
失败关闭与 Host 兼容。 未认证请求不会放行 Shell；若无 fallback，已认证请求会收到可读的 500。插件兼容 Host 0.2.1 及更早的 (req, res) fallback，以及 0.2.2+ 的 { resource(request, peer) } 形态。
凭证存储。 明文密码不写入磁盘。用户名与 scrypt 哈希（N=32768, r=8, p=1）保存在 $DSH_HOME/.credentials.yaml 的 web-auth/password；TOTP 相关在 web-auth/totp。文件权限 0600，写入时使用跨进程文件锁。会话签名密钥读取 client-connection/browser-session，插件不修改该 Host 记录格式。
连续失败锁定。 可配置失败次数与锁定时长（见下文配置表）。
安装与启用¶
DSH 生态里插件通过 profile 安装；本插件针对 web profile。官方 README 给出的安装方式为本地路径（需先将仓库放到本机，路径改为你的绝对路径）：
dsh plugin --profile web add /absolute/path/to/dsh-web-password-auth
安装后重启 dsh --profile web 并打开 UI。若尚无账号，首次访问会显示 Create your account。
客户端设置页依赖 lib/client.js，并在启动时注入 settings 区块；修改插件或首次启用后需重启 dsh web，浏览器插件 roster 在进程启动时组装。
运行环境要求 Node.js >=20；peer 依赖 @deepseek-ai/cordis ^4.0.2。
配置与会话时长¶
插件在启动时会读取 Host Loader 上有效的 cookieMaxAgeDays，并与自身 sessionDays 取较小值，避免 Host 拒绝 cookie 导致「看似登录成功、后续请求全 401」。
默认配置项（README 配置表）：
| 字段 | 默认值 | 含义 |
|---|---|---|
sessionDays |
365 |
浏览器会话天数；须 ≤ connection.cookieMaxAgeDays |
bootstrapLoopbackOnly |
true |
尚无账号时，仅本机可创建账号 |
maxAttempts |
5 |
同一来源地址连续失败次数上限 |
lockoutMs |
300000 |
锁定时长（毫秒） |
minPasswordLength |
8 |
最短密码长度 |
totpIssuer |
'DSH' |
Authenticator 中显示的发行方名称 |
totpAvailable |
true |
是否在账号页提供双因素注册 |
若希望会话接近「登出前一直有效」，需同时提高 Host 与插件上限。Host 默认 connection.cookieMaxAgeDays 为 30。README 示例在 $DSH_HOME/profiles/web/cordis.patch.yml 中 patch connection（注意 patch 会替换整段 config，需写全所需键）：
- id: connection
config:
# A patch replaces the whole config, so restate every key the row needs.
trustedHosts: !!js ctx.webStartup.trustedHosts
cookieMaxAgeDays: 365
同时将插件侧 sessionDays 保持在不超过该 cap 的范围内。
典型用法¶
路径一：纯 URL 首次建号（无 token）。 在尚无账号时，用不带 ?token= 的地址打开 Web UI（例如 http://127.0.0.1:3080/），提交创建账号表单后写入凭证并登录。在默认 bootstrapLoopbackOnly: true 下，仅本机可完成此步骤；账号已存在后该入口关闭。
路径二：先用 launch token，再在应用内建号。 常见情况是直接打开 dsh web 打印的 ?token=... URL，此时已登录，无法弹出 setup 页。转到 Settings → Security，使用 Create a password account 完成密码账号创建。
日常管理。 在 Settings → Security 或 Plugins → Web Password Auth 中改密、开关 TOTP、登出。开启双因素时扫描 QR 并输入一次验证码确认；关闭双因素需当前 TOTP 码。
忘记密码。 README 说明的恢复步骤为：
- 在运行
dsh web的终端查看带?token=...的 URL； - 在浏览器打开该 URL，由 Host 交换 token 并登录；
- 进入 Settings → Security 设置新密码（改密会撤销既有会话，需重新登录）。
若进程 stdout 不可见，可删除 $DSH_HOME/.credentials.yaml 中的 web-auth/password 记录并重启，下次访问会再次出现 setup 页（等同于重新开始，需重新建号）。
彻底重来。 删除 .credentials.yaml 里 web-auth/password 记录即可；下次访问重新提供账号创建。
适用场景与注意¶
适合谁。 长期用 dsh --profile web 在本机或受控内网操作 Harness、希望用密码与可选 2FA 替代反复复制 launch token 的开发者；分类 admin-security，面向管理面加固而非业务逻辑插件。
权限与信任边界。 插件与当前 dsh 进程同权限运行；在常见 danger-full-access 组合下，通过 Web 登录等价于在该权限模型下远程驱动 Harness。安装前应阅读源码与 MIT 许可证，确认符合你的安全策略。
传输层。 README 明确：若除 loopback 外还有其他主体可访问该端口，应使用 TLS（--tls-cert / --tls-key 或反向代理终结 TLS）。明文 HTTP 上密码与 token 可被嗅探；launch token 也会出现在终端日志与进程列表中。
双因素与暴露面。 端口若对非本机可达，README 建议启用 TOTP（原文在截断处继续强调 TLS 与 2FA，此处不展开未抓取段落）。
社区与星标。 截至撰写时 GitHub 星标为 0；功能描述以仓库 README 与发布包 metadata 为准，使用前自行核对版本 CHANGELOG。
结尾¶
dsh-web-password-auth 在保留 DSH launch token 本地 fallback 的前提下，为 Web UI 补上账号密码、持久会话与应用内安全设置，并可选 TOTP。安装使用 README 中的 profile 本地路径命令，注意 sessionDays 与 Host cookieMaxAgeDays 对齐，并在非本机访问时配合 TLS 与 2FA。
