dsh-auth

面向 DeepSeek Harness Web UI 的 Cookie 鉴权 bundle，遵循官方 Web UI 快速入门 与 插件打包/安装约定。它提供：

• 绑定回环、0.0.0.0 或指定 IPv4 地址；
• 从 $DSH_HOME/token（默认 ~/.dsh/token）读取专用访问 token；
• token 不存在时生成 32 字节随机值并以 0600 保存；
• 内置 token 登录页，成功后写入 HttpOnly; SameSite=Strict Cookie；
• 在分发前统一保护 SPA、HTTP API 和 WebSocket upgrade；
• 登录后开放 Harness 的远程管理 API，并在交给下游前移除 auth Cookie；
• 为明文 LAN 来源补充基于 crypto.getRandomValues() 的 UUID v4 兼容层；
• 退出登录与全局 token 轮换。

本插件不会读取或复用 ~/.dsh/.credentials.yaml 中的模型 API 密钥。

为什么替换 Web 宿主

DeepSeek Harness 0.1.0-rc.6 的 webServer 只提供具名 route、upgrade route 和一个 SPA fallback，没有 HTTP middleware。旁挂一个 /login route 无法保护已有 /api、静态管理端或 WebSocket。

dsh-auth 因此以 bundle 的形式禁用内置 webserver 行，插入一个提供相同 webServer 服务面的认证宿主。现有 connection、modules、HMR 与 frontend-static 插件无需修改。

要求

• Node.js 22+
• DeepSeek Harness 0.1.0-rc.6（开发者预览版迭代很快，升级后请重新运行测试）
• pnpm 位于 PATH（dsh plugin 会调用它；Corepack 用户可先运行 corepack enable pnpm）

构建与安装

推荐用 tarball 安装，避免 profile 链接到开发目录：

cd /path/to/dsh-auth
npm install
npm test
npm pack
dsh plugin --profile web add ./dsh-auth-0.1.0.tgz

验证组合层：

dsh web --dump-config

输出中应同时看到禁用的 webserver 和新增的 auth-webserver。

卸载：

dsh plugin --profile web remove dsh-auth

使用

本机访问：

dsh web

打开命令打印的 URL。若 ~/.dsh/token 原先不存在，插件会自动创建。登录 token 可从该文件读取：

cat ~/.dsh/token

DSH_HOME 自定义时，token 位于对应目录的 token 文件。

绑定远程 IPv4

绑定所有 IPv4 网卡：

DSH_AUTH_HOST=0.0.0.0 dsh web

当前 Harness rc.6 的内置 Web 启动参数会主动拒绝 --host 0.0.0.0，所以该地址必须通过 DSH_AUTH_HOST 提供。指定某张网卡也可以：

DSH_AUTH_HOST=192.168.1.20 dsh web

随后访问 http://192.168.1.20:3080。host 必须是 IPv4 字面量，不接受主机名。

浏览器不会在非回环的明文 HTTP 来源暴露 crypto.randomUUID()，但 Harness 客户端会直接调用它。认证宿主会在客户端 bundle 之前注入一个基于 crypto.getRandomValues() 的 UUID v4 兼容实现；原生方法存在时不会覆盖。 这只修复 API 兼容性，不会把 HTTP 变成安全上下文，也不替代 HTTPS。

HTTPS 与 Secure Cookie

直接绑定 LAN 时仍是明文 HTTP，token 会随 Cookie 在网络中传输。跨不可信网络使用时，应让 dsh 只绑定回环地址，并在前方配置 HTTPS 反向代理。HTTPS 已就绪后再启用：

DSH_AUTH_SECURE_COOKIE=true dsh web

不要在直接访问 http://... 时开启它；浏览器不会回传带 Secure 的 Cookie。

配置

bundle 暴露以下环境变量：

如需修改其他字段，在 $DSH_HOME/profiles/web/cordis.patch.yml 中完整重述配置。Harness patch 会整体替换 config，不会逐键深度合并：

- id: auth-webserver
  config:
    host: 127.0.0.1
    port: 3080
    tokenFile: !!js dshHomePath('token')
    cookieName: dsh_auth
    cookieMaxAgeSeconds: 2592000
    secureCookie: false
    authPath: /auth
    apiPath: /api
    authorizeRemoteApi: true
    maxLoginBodyBytes: 4096
    protectTokenFile: true

authorizeRemoteApi: true 表示：Cookie 已通过恒定时间比较后，把 /api 请求交给 Harness 时按本机可信请求处理。这替代了上游在“尚无真实认证”情况下对设置与凭据方法保留的 loopback-only 占位栅栏。关闭该项会保留上游限制，远程登录者将无法使用部分管理功能。

Token 与会话语义

• token 文件会去掉首尾空白；空 token、控制字符或超过 4096 字节会使插件启动失败。
• POSIX 上已有 token 文件会被收紧为 0600；符号链接和非普通文件会被拒绝。
• Cookie 直接携带 percent-encoded token，只对当前 Host 生效，并始终带 HttpOnly、SameSite=Strict 和 Path=/。
• 退出登录只清除当前浏览器 Cookie。要撤销所有浏览器，替换 token 文件并重启 dsh web。
• 登录页为 /auth/login，退出地址为 /auth/logout。登录与未授权响应均为 Cache-Control: no-store。

开发验证

npm test
npm run typecheck
npm pack --dry-run

测试覆盖 token 生成/复用与权限、跳转清洗、Cookie 登录/退出、SPA/API 鉴权、远程 API 信任转换、auth Cookie 下游隔离、upgrade 鉴权、配置拒绝和生命周期清理。

安全边界

• 这是单一共享 token，不是多用户、权限分级或审计系统。
• 插件不终止 TLS；公网使用必须配置 HTTPS 反向代理和网络访问控制。
• Harness 本身可执行命令和修改文件。即使有 token，也只应暴露给受信任用户和网络。

License

MIT