dsh-ui-auth — DSH Web UI 认证网关插件

🔴 兼容性提示：legacy 版本（DSH 0.1.1-rc.2）的支持将于 v0.7.0 起结束

v0.7.0 起本插件只跟随 DSH 的新版本开发（当前为 0.1.2-rc.1 ~ 0.1.5-rc.1 及其后续版本）， 不再对 DSH 0.1.1-rc.2 这条旧传输线（dotted /api/<a>.<b> + apiProxy）做适配与验收。 若 DSH 后续架构有大变动，我会提前声明该版本的支持结束时间，不会突然中断。 仍在使用 0.1.1-rc.2 的部署请在此之前按 DSH 版本兼容性 一节规划升级。

给 DeepSeek Harness（DSH）的 Web UI 加一道用户名 / 密码登录门：未登录时无法访问任何页面、 API 或 WebSocket 通道；登录后可管理用户、邀请码、两步验证（TOTP）与通行密钥（Passkey）， 并按登录用户隔离会话数据。

适用场景：把 DSH 面板暴露到内网或公网时，需要一个前置认证层，并希望不同使用者之间互不可见。

特性一览

• 全接口拦截：在 DSH 路由分发之前包装其 HTTP 服务器，覆盖 /api/*、/plugins/*、HMR、 SPA fallback 与 WebSocket 升级通道，没有旁路。未登录时页面请求 302 跳登录页、API 返回 401、 WS 升级直接断开；登录后原请求原样透传。
• 登录页与注册页：中文界面，登录成功写入 dsh_auth Cookie（HttpOnly、SameSite=Strict、 12 小时滑动续期）；注册需邮箱 + 用户名 + 密码 + 有效邀请码，注册成功自动登录并引导绑定 TOTP。
• 用户管理：所有用户可改自己的昵称/邮箱/密码并管理自己的 TOTP 与通行密钥；管理员可增删用户、 重置密码、切换角色、生成/撤销邀请码、清除某人的通行密钥。任何人都无法查看他人的当前密码。
• 两步验证（TOTP）：RFC 6238，可用 Google / Microsoft Authenticator 扫码绑定，也支持手动输入密钥； 启用后登录需「密码 + 动态码」（账号未绑定 TOTP 时，第二步改用通行密钥）。
• 通行密钥（Passkey / WebAuthn）：用指纹、面容或设备 PIN 代替密码登录，一个账号可绑定多个 （本机密钥 + 手机密钥）。支持不输入用户名的一键登录；手机可用浏览器显示的二维码扫码绑定。 私钥永不离开用户设备，服务器只保存公钥。
• 模型与密钥仅管理员：设置面板的「模型」页对普通用户替换为提示页；服务端同样强制—— 普通用户对模型/密钥相关接口一律 403，绕过界面直调 API 也无法修改。
• 按用户隔离：会话与工作区在创建时记录归属；普通用户的会话/工作区列表只显示自己的， 直连他人会话返回 403，WebSocket 事件流按归属逐帧过滤（在网络层就收不到他人数据）。 管理员不受限。
• 登录防护：密码 PBKDF2-HMAC-SHA256（每用户随机盐、60000 轮、常量时间比较）、 密码策略「≥8 位且至少两种字符类型」、按来源 IP 的失败锁定、认证响应一律 Cache-Control: no-store； 通行密钥使用一次性短时挑战、严格的来源/RP ID 校验与签名计数器回退检测。
• 会话与审计：会话可跨重启恢复（磁盘只存 Token 的 SHA-256 哈希）；管理员操作与越权尝试 写入 JSONL 审计文件。

环境要求

项	要求
DSH	0.1.1-rc.2，或 0.1.2-rc.1 ~ 0.1.5-rc.1（web profile；两条传输线都支持，见「DSH 版本兼容性」）
Node.js	^22.19.0 || >=24.0.0（与 DSH 一致）
运行时依赖	qrcode（生成 TOTP 二维码）、ws（流式通道）与 @simplewebauthn/server（通行密钥服务端校验），安装时自动获取，无需手动构建
浏览器	通行密钥需要 Chrome / Edge / Safari / Firefox 等支持 WebAuthn 的现代浏览器；不支持时其余功能不受影响

通行密钥对访问地址有硬性要求（浏览器规则，插件无法绕过）：

访问地址	通行密钥	说明
https://你的域名	✅ 可用	推荐的生产部署方式（反代终止 TLS）
http://localhost:3080	✅ 可用	本机使用请用 localhost，不是 127.0.0.1
http://127.0.0.1:3080	❌ 不可用	Chrome 拒绝 IP 地址作为通行密钥域（RP ID）；面板会提示改用 http://localhost:3080
http://内网IP:3080	❌ 不可用	明文 HTTP 不是安全上下文，且 IP 不能作为 RP ID；需域名 + HTTPS

安装

本包是标准的 DSH profile bundle（声明了 dsh.bundle.patch 与 dsh.client）， dsh plugin 会自动把它加入 profile 的 bundle 名单：

# 从 npm 安装
dsh plugin --profile web add dsh-ui-auth

# 或固定到某个 GitHub 发行版本
dsh plugin --profile web add github:0QwQ0/dsh-ui-auth#v0.6.4

# 或从本地目录安装（离线 / 二次开发）
dsh plugin --profile web add <本插件目录的绝对路径>

安装完成后重启一次面板生效（bundle 层在启动时应用）。

首次登录

用户表为空时，插件会自动创建管理员 admin，随机密码同时输出到两处：

1. 面板控制台日志（以 [dsh-ui-auth] 开头）；
2. 面板进程工作目录下的 dsh-ui-auth-bootstrap.txt。

打开面板会跳转到 /auth/login，用 admin 与上述随机密码登录。 登录后请立即在【设置】→【用户管理】中修改密码；任意用户改密成功后，引导文件会自动删除。

使用指南

设置面板 → 用户管理

• 所有用户：修改自己的昵称、邮箱、密码；绑定/移除自己的 TOTP 令牌；添加/重命名/删除自己的 通行密钥；开关两步验证。
• 管理员：新增/删除用户、重置他人密码、切换角色、生成与撤销邀请码（可查看每个码的 已用次数与剩余次数）、移除任意用户的 TOTP、清除任意用户的通行密钥（设备丢失时救援）。
• 保护规则：不能删除或降级最后一个管理员，不能删除自己；改密或删除用户后，其其他会话立即失效。

注册与邀请码

注册入口在登录页的「注册账号」。新用户需要管理员事先在【用户管理】→【邀请码管理】中生成的有效邀请码； 每个码可设置 1–100 次的注册次数，可随时撤销。邮箱目前只做格式填写、不校验真实性，注册后可在用户管理中修改。

两步验证（TOTP）与通行密钥（Passkey）

两步验证可以用两种因子满足：TOTP 动态码或通行密钥。绑定任一种后即可在 【用户管理】→「两步验证」用开关启用；开关打开后，登录方式如下（通行密钥始终可直接登录， 与两步验证开关无关）：

账号状态	可用的登录方式
两步验证关闭	用户名 + 密码；通行密钥
两步验证开启，已绑定 TOTP	用户名 + 密码 + 动态码；通行密钥
两步验证开启，只绑定了通行密钥	用户名 + 密码 + 通行密钥；通行密钥（可不填用户名）

0.6.4 起移除了「免密 + 动态码」登录：只有动态码、没有密码的登录请求一律被拒绝。 免密入口统一收敛到通行密钥。

TOTP：在【用户管理】→「两步验证（TOTP）」生成密钥，用验证器 App 扫码（或手动输入密钥 / otpauth 链接）后输入 6 位动态码完成绑定。动态码错误同样计入失败锁定；移除令牌需要当前动态码， 管理员可移除任意用户的令牌。

通行密钥：在【用户管理】→「通行密钥（Passkey）」中添加，同一个账号可以绑定多个：

• ＋ 本机通行密钥：使用这台电脑的 Windows Hello / Touch ID / 设备 PIN；
• 📱 手机扫码添加：浏览器会显示二维码，用手机相机扫码后在本机完成绑定（手机无需与面板处于同一网络， 也不需要手机能访问面板）；
• 绑定后登录页会出现「🔑 使用通行密钥登录」，点击即可不输入用户名与密码直接登录； 也可以照常输入用户名密码，在第二步提示时用通行密钥完成验证。

安全约定：通行密钥的私钥永不离开设备，服务器只保存公钥与名称等公开信息；添加、重命名、删除 通行密钥都需要先确认当前密码（两步验证开启时还需动态码或一次已有通行密钥的确认）； 为避免账号被锁死，两步验证开启且只剩一个通行密钥时不允许删除它——请先绑定 TOTP 或先关闭两步验证。 设备丢失时，管理员可在【用户管理】中「清除通行密钥」救援。

模型页与密钥

【设置】→【模型】（含模型选择与 API Key 配置）仅管理员可用：

• 服务端强制：普通用户对模型/密钥相关接口（settings.* 的 LLM 命名空间、credentials.set/unset、 llm.discoverModels）一律返回 403，绕过 UI 直调 API 同样被拒；
• 客户端：普通用户的「模型」页显示「仅管理员可访问」，并隐藏出厂的「模型」导航行。

普通用户能看到什么（DSH 0.1.2+）

同一套权限策略在服务端逐端点生效，界面只是它的呈现：

设置页	普通用户
用户管理	✅ 完整可用（改自己的资料/密码、TOTP、通行密钥、两步验证；管理员额外有用户与邀请码管理）
Agent 预设	✅ 可查看预设清单、查看本会话所用预设、为自己会话选择预设；创建/删除预设仅管理员
插件	✅ 可查看本部署已安装插件的清单；安装/卸载/启停插件、单个插件的设置与密钥仅管理员
通用设置	可查看；写入部署级设置仅管理员
模型	仅管理员（普通用户看到提示页）

需要放开某项的部署，可由宿主插件通过 uiAuth.registerPolicy() 逐条登记，见 docs/DSH-0.1.5-COMPATIBILITY.md。

数据隔离

DSH 本身按单用户设计（会话、工作区是机器级数据）。本插件按登录用户隔离：

• 会话/工作区创建时记录归属；列表与搜索接口在响应侧过滤（含工作区内会话与归档会话）；
• 直接访问非属主对象（如他人的会话内容、重命名、提示词）返回 403；会话导出仅限属主；
• WebSocket 事件流按归属逐帧过滤——普通用户在网络层就收不到他人会话的事件帧，浏览器控制台同样看不到；
• 管理员可见全部数据；插件启用之前已存在的旧数据默认归管理员。

界面预览

登录页（含通行密钥入口）	注册页

通行密钥（Passkey）卡片	用户管理页

注册成功引导页（绑定第二个因子）

截图由 node test/shot.mjs 在一次性实例上生成（见该脚本头部的环境变量说明）， 因此图中不含任何真实账号数据。通行密钥相关界面必须在 localhost 或域名 + HTTPS 下才会完整渲染。

配置（可选环境变量）

变量	默认	说明
DSH_AUTH_MAX_FAILS	5	单来源连续登录失败锁定阈值（正整数；非法值回退默认）
DSH_AUTH_LOCK_MS	30000	锁定持续时间（毫秒）
DSH_AUTH_TRUST_PROXY	关	设为 1/true/yes 时信任 X-Forwarded-For（取最右，即最近一层受信代理追加的地址，客户端无法伪造）与 X-Forwarded-Proto（用于 Secure Cookie）。仅在 HTTPS 反向代理之后开启；默认不信任，避免未配置代理时伪造请求头绕过或污染限流
DSH_AUTH_RP_ID	自动	通行密钥域（WebAuthn RP ID）。默认按浏览器实际访问的主机名推导；只有在反向代理改写了 Host、或需要在子域间共享通行密钥时才需要显式设置（必须是访问域名的后缀）
DSH_AUTH_ORIGIN	自动	通行密钥校验的期望来源（如 https://panel.example.com）。反代终止 TLS 且插件看到的 Host/协议不是浏览器所见时设置
DSH_AUTH_RP_NAME	DeepSeek Harness	通行密钥在系统弹窗中显示的账号名

面板进程启动时读取，修改后需重启面板。示例：

$env:DSH_AUTH_MAX_FAILS = '10'; $env:DSH_AUTH_LOCK_MS = '60000'; $env:DSH_AUTH_TRUST_PROXY = '1'

export DSH_AUTH_MAX_FAILS=10 DSH_AUTH_LOCK_MS=60000 DSH_AUTH_TRUST_PROXY=1

数据与持久化

内容	位置	说明
用户、角色、资料、密码哈希、TOTP 密钥、通行密钥（公钥）、邀请码	DSH 凭据库 ~/.dsh/.credentials.yaml 中的 dsh-auth/* 记录	重启后保留；不保存明文密码，也不保存通行密钥私钥（私钥只存在于用户设备）
登录会话	面板进程工作目录下的 dsh-ui-auth-sessions.json	只存 Token 的 SHA-256 哈希；未过期会话重启后免登录恢复
审计日志	面板进程工作目录下的 dsh-ui-auth-audit.jsonl	JSONL，每行含时间、操作者、动作、目标等字段
首次启动引导文件	面板进程工作目录下的 dsh-ui-auth-bootstrap.txt	任一用户改密成功后自动删除

备份：备份 ~/.dsh/.credentials.yaml 即可保留全部账号数据。

彻底清空：删除 ~/.dsh/.credentials.yaml 中 dsh-auth: 下的记录，并删除上述工作目录里的 dsh-ui-auth-sessions.json、dsh-ui-auth-audit.jsonl 与 dsh-ui-auth-bootstrap.txt，然后重启面板 （用户表为空时会重新生成新的管理员与随机密码）。

卸载

dsh plugin --profile web remove dsh-ui-auth
# 重启面板后网关、设置面板与客户端模块全部消失；profile 的依赖与 bundle 名单自动还原

卸载不会删除账号数据（防误删）；如需一并清空，见上一节。

安全说明与已知边界

• 密码与会话：PBKDF2-HMAC-SHA256（随机盐、60000 轮、常量时间比较）；密码策略为 「≥8 位且至少两种字符类型」；会话 Token 仅以 SHA-256 哈希落盘，登出、改密或删除用户后相关会话立即失效。
• Cookie：dsh_auth 为 HttpOnly + SameSite=Strict；在 TLS 直连或（仅在信任反代时） X-Forwarded-Proto: https 的通道下自动追加 Secure。
• 公网部署建议：放在 HTTPS 反向代理之后，由代理终结 TLS 并保留 Host；DSH 自身可监听 127.0.0.1 或内网。反代场景请按上文开启 DSH_AUTH_TRUST_PROXY=1，否则限流会按代理 IP 聚合。
• 会话持久化带来「记住登录」：未过期的会话在面板重启后自动恢复；若你的安全要求是每次重启都必须重新登录， 可在停止面板后删除 dsh-ui-auth-sessions.json。
• 升级提示：从 0.5.1 之前的版本升级时，旧版明文会话记录不再恢复，所有用户需要重新登录一次。
• 与 DSH 自带机制的关系：DSH 对 /api 的 DNS-rebinding 信任栅栏明确不是认证； 本插件才是前置认证层，两者叠加使用。
• 隔离强度的上限：本插件按登录用户隔离 DSH 的会话/工作区数据；它不改变 DSH 自身的进程权限模型， 也不能隔离第三方插件自己的数据。多租户级别的强隔离需要 DSH 侧的支持。
• 更完整的安全分析（威胁模型、用例矩阵、残余风险与部署加固清单）见 SECURITY.md。

DSH 版本兼容性

同一份代码按能力探测自动选择传输适配，无需配置：

DSH 版本	传输线	说明
0.1.1-rc.2	legacy	dotted /api/<a>.<b> RPC 与 apiProxy 事件流，历史行为保持不变
0.1.2-rc.1 ~ 0.1.5-rc.1	modern	斜杠 RPC /api/<ns>/<method>、/api/remote.mux 流式通道与原生浏览器会话门

modern 传输线为安全起见对普通用户更严格：不能创建 workspace（工作区目录属部署方能力）， 也不能写入任何设置命名空间；需要放开时可由宿主插件通过 uiAuth 接口登记策略。 端点清单、收紧项与验证证据见 docs/DSH-0.1.5-COMPATIBILITY.md。

常见问题

忘记管理员密码怎么办？ 删除 ~/.dsh/.credentials.yaml 中 dsh-auth/admin（及其对应的哈希记录），重启面板后会重新生成 admin 与新的随机密码（原账号的 TOTP、通行密钥与资料会丢失）。其他用户的密码可由管理员在用户管理中重置。

删掉的用户想用同一个名字重建，提示「用户名已存在」？ 这是有意设计：被删除的用户名会写入永久墓碑，同名账号不能重建，避免新账号继承旧账号留下的 会话归属、邀请码记录等历史残留。请换一个用户名，或按上面的方法清空整张用户表后重新引导。

绑定的通行密钥设备丢了怎么办？ 两个办法：① 若该账号还绑定了 TOTP，用「密码 + 动态码」登录后在【用户管理】里删除丢失的通行密钥； ② 请管理员在【用户管理】→ 对应用户行点「清除通行密钥」。管理员自己的通行密钥若全部丢失且未绑定 TOTP， 只能按上一条重置 admin 记录（这也是「两步验证开启时不允许删除最后一个通行密钥」的原因）。

通行密钥按钮不可用 / 提示改用 localhost？ 浏览器不允许把 IP 地址当作通行密钥域。请用 http://localhost:3080 打开面板，或给面板配一个域名并走 HTTPS。 面板会直接给出应该使用的地址。

手机扫码绑定后，手机上也能直接登录面板吗？ 可以。手机通行密钥是「可同步/混合」凭据：手机浏览器打开同一地址（必须同样是域名或 localhost）即可用 指纹/面容直接登录；无需电脑在场。

重启面板后需要重新登录吗？ 不需要。未过期的会话会自动恢复；只有在从 0.5.1 之前的版本升级时，旧会话记录会失效一次。

普通用户看不到「模型」页，是故障吗？ 不是，这是设计：模型与 API Key 仅管理员可配置，服务端与界面同时强制。

登录限流把所有人都算成同一个来源？ 说明面板前面有反向代理。按上文开启 DSH_AUTH_TRUST_PROXY=1，限流将按真实客户端 IP 计数。

邀请码用完了 / 想关闭注册？ 注册必须持有效邀请码，因此不生成邀请码即等于关闭注册；管理员可随时生成或撤销。

可以只要认证、不做数据隔离吗？ 当前版本始终启用按用户隔离。需要自定义策略的部署可通过宿主插件调用 uiAuth 接口（见兼容性文档）。

开发

源码为 TypeScript，构建产物一并提交（DSH 直接读取仓库，因此运行与安装不需要构建）：

npm ci                 # 安装开发依赖（typescript / esbuild / @types/*）
npm run typecheck      # 宿主与客户端两套 tsconfig 的严格类型检查
npm run build          # src/*.ts → lib/*.js
npm test               # 构建 + 全链测试（安全套件、策略回归、冒烟与向量）
npm run verify:clean   # 校验 lib/ 与 src/ 一致（修改源码后需提交重新构建的产物）

源码	产物	说明
src/index.ts	lib/index.js	宿主：网关、认证、用户管理、审计、通行密钥端点
src/webauthn.ts	lib/webauthn.js	通行密钥：RP/来源解析、一次性挑战、注册与登录校验封装
src/modern-gateway.ts	lib/modern-gateway.js	DSH 0.1.2+ 传输适配
src/modern-policy.ts	lib/modern-policy.js	端点授权与数据过滤策略
src/client.ts	lib/client.js	设置面板客户端（由 build/client.mjs 打成 DSH 客户端契约）
src/passkey-browser.ts	lib/passkey-browser.js	登录页用的 WebAuthn 浏览器端 bundle（同一份社区库）

更多文档：兼容性与隔离策略 · 安全审计与测试证据 · 发布流程（维护者） · 变更记录 · MIT 许可证