SummerSec/dsh-web-auth

dsh-web-auth

npm
Node.js
License: MIT
topic: dsh-plugin

DeepSeek Harness（DSH）Web GUI 的传输层登录门。

官方 webserver 会直接暴露 GUI、插件 bundle、/api、SSE 与 WebSocket，没有统一的身份边界。本插件会禁用未鉴权的官方载体，并替换为兼容 ctx.webServer 契约的服务：在请求进入业务路由之前完成会话校验。

English: README.md

登录页面

DeepSeek Harness 登录页面

为什么需要它

DSH 自带 Web 宿主适合本地调试，但不是产品级访问控制：

- 监听 0.0.0.0 或挂到反向代理后，控制面可能被整站暴露。
- 仅靠前端“登录页”挡不住 /api、静态插件资源、SSE 与 WebSocket upgrade。
- 会话与口令校验必须落在 HTTP 载体本身。

@summersec/dsh-web-auth 做的事：

1. 禁用 @deepseek-ai/dsh-host-webserver。
2. 插入 webserver-auth，继续提供相同的 ctx.webServer 接口（register / registerUpgrade / registerFallback / tapIndex / host / port）。
3. 用服务端会话 Cookie 拦截 HTTP 与 upgrade 流量。

其他插件仍按原方式注册路由，无需感知鉴权实现。

功能一览

| 方面 | 行为 |
| --- | --- |
| 保护范围 | HTTP 路由 与 WebSocket / HTTP upgrade |
| 默认模式 | always：即使绑定 127.0.0.1 也要登录 |
| 可选模式 | non-loopback：仅非 loopback 绑定时启用鉴权 |
| 口令 | scrypt 散列（scrypt$N$r$p$salt$key）；明文环境变量仅作临时用途 |
| 会话 | 32 字节随机 token、内存存储、滑动过期 |
| Cookie | HttpOnly、SameSite=Strict，按需 Secure |
| 防爆破 | 按客户端 IP 限制登录失败次数，返回 Retry-After |
| 登录体验 | 内置 /auth/login 页面（浅色/深色），支持表单与 JSON |
| 加固 | 登录/登出 Origin 校验、回跳路径净化、鉴权响应 CSP 与防嵌套 |

环境要求

- Node.js >= 22
- 已配置 web profile 的 DeepSeek Harness（peer：@deepseek-ai/cordis ^4.0.1）
- 进程环境中的口令散列（推荐），或临时明文口令

快速开始

1) 生成随机口令与 scrypt 散列（请离线妥善保存口令）
npx --yes @summersec/dsh-web-auth generate

2) 仅在当前 shell 导出散列（不要提交到仓库）
$env:WEB_AUTH_PASSWORD_HASH = 'scrypt$...'
$env:WEB_AUTH_USERNAME = 'admin'

3) 安装到 web profile
dsh plugin --profile web add @summersec/dsh-web-auth

4) 启动 GUI
dsh web

访问原来的 DSH 地址。未登录的浏览器导航会跳转到 /auth/login；API 等非 HTML 客户端收到 401 JSON：

{ "error": "authentication_required" }

登录成功后写入会话 Cookie，并跳回原路径。页面注入的浏览器引导会让同源 API、SSE 和第三方插件请求明确携带该 Cookie；如果内存会话过期或服务重启导致旧会话失效，收到 authentication_required 时会自动回到登录页，避免插件停留在无提示的传输失败状态。

不要把口令或散列写进会共享/提交的项目 .env。优先使用进程环境、密钥管理系统，或仓库外的主机级环境文件。

从源码安装

git clone https://github.com/SummerSec/dsh-web-auth.git
cd dsh-web-auth
npm install

node .\bin\dsh-web-auth.js generate
$env:WEB_AUTH_PASSWORD_HASH = 'scrypt$...'

在 DSH 工作区侧，或使用本地路径安装：
dsh plugin --profile web add
dsh web

已有口令生成散列（至少 12 个字符）：

$env:WEB_AUTH_PASSWORD = '至少十二个字符的强口令'
node .\bin\dsh-web-auth.js hash-password
Remove-Item Env:WEB_AUTH_PASSWORD

也可通过 stdin 传入（CLI 不会接受命令行参数形式的口令）：

'至少十二个字符的强口令' | node .\bin\dsh-web-auth.js hash-password

鉴权模式

| authMode / WEB_AUTH_MODE | 何时启用鉴权 |
| --- | --- |
| always（默认） | 始终启用，包括 host: 127.0.0.1 |
| non-loopback | 仅当 host 不是 127.0.0.1 时启用（例如 0.0.0.0） |

默认：永远需要登录
$env:WEB_AUTH_MODE = 'always'
dsh web

loopback 可不登录；绑定非 loopback 时自动开闸
$env:WEB_AUTH_MODE = 'non-loopback'
dsh web --host 0.0.0.0

当鉴权处于启用状态，且既未配置 passwordHash 也未配置 password 时，插件会在启动阶段直接抛错，避免误上线成“空门”服务。

环境变量

bundle（cordis.patch.yml）将这些变量映射到插件配置：

| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| WEB_AUTH_MODE | always | always 或 non-loopback |
| WEB_AUTH_USERNAME | admin | 登录用户名 |
| WEB_AUTH_PASSWORD_HASH | （无） | 推荐：由 generate / hash-password 生成的 scrypt 散列 |
| WEB_AUTH_PASSWORD | （无） | 明文口令，仅建议临时/实验环境使用 |

生产与长期部署请优先使用 WEB_AUTH_PASSWORD_HASH。

高级配置

bundle 会：

1. 将官方 webserver 行设为 disabled: true。
2. 插入名为 @summersec/dsh-web-auth 的 webserver-auth 行。

DSH 补丁对配置是整块替换。若要覆盖高级字段，请在 profile 的 cordis.patch.yml 中完整重写 webserver-auth：

- id: webserver-auth
name: '@summersec/dsh-web-auth'
inject: [webStartup]
config:
host: !!js ctx.webStartup.host ?? '127.0.0.1'
port: !!js ctx.webStartup.port ?? 3080
authMode: always
username: admin
passwordHash: !!js process.env.WEB_AUTH_PASSWORD_HASH
sessionTtlMinutes: 720
maxAttempts: 5
attemptWindowSeconds: 300
secureCookie: auto
trustProxy: false

配置项说明

| 字段 | 类型 / 取值 | 默认 | 说明 |
| --- | --- | --- | --- |
| host | 127.0.0.1 \| 0.0.0.0 | 127.0.0.1 | 监听地址（来自 web startup） |
| port | 0–65535 | 3080 | 监听端口；0 表示系统分配 |
| authMode | always \| non-loopback | always | 见鉴权模式 |
| username | string | admin | 单账号共享访问边界 |
| password | string | — | 明文；生产环境避免使用 |
| passwordHash | scrypt$... | — | 必须为 CLI 生成的格式 |
| sessionTtlMinutes | 1–43200 | 720（12 小时） | 滑动过期：每次鉴权成功访问会续期 |
| maxAttempts | 1–1000 | 5 | 同一 IP 在窗口内允许的失败次数 |
| attemptWindowSeconds | 1–86400 | 300 | 失败计数窗口长度 |
| secureCookie | auto \| always \| never | auto | 是否附加 Cookie Secure |
| trustProxy | boolean | false | 是否信任 X-Forwarded-（仅受控代理后开启） |

secureCookie 与 trustProxy

| 场景 | 建议 |
| --- | --- |
| 本机 loopback HTTP | secureCookie: auto，trustProxy: false |
| Node 进程直接终结 TLS | secureCookie: auto（加密 socket 时自动加 Secure） |
| nginx / Caddy / Cloudflare 终结 HTTPS | secureCookie: auto 或 always，trustProxy: true，并保证只有代理能访问 DSH 端口 |

若在端口可被不可信客户端直连时开启 trustProxy，攻击者可伪造 X-Forwarded-For / X-Forwarded-Proto，削弱 IP 限流或 Cookie 安全语义。务必先锁死网络访问路径。

公网部署请在 DSH 前放置 HTTPS 反向代理。

登录失败限流

插件按客户端 IP 记录登录失败次数。默认配置下，同一 IP 在 300 秒内失败 5 次后，后续登录会收到 429 Too Many Requests 和 Retry-After，直到计数窗口过期。登录成功会清除该 IP 的失败记录。

阈值由以下配置控制：

maxAttempts: 5
attemptWindowSeconds: 300

这项防护有明确边界：

- 计数保存在进程内存中，服务重启后会清空，多实例之间也不会共享。
- 限制对象是 IP，不是账号。攻击者轮换来源 IP 时，可以绕过单 IP 阈值。
- trustProxy: false 时使用 socket 地址；开启 trustProxy 后会信任 X-Forwarded-For 的第一个值，因此 DSH 端口必须只允许受控代理访问。

公网部署时，建议同时在反向代理或防火墙设置限流。这项功能不能替代 HTTPS、网络隔离和强口令。

鉴权 HTTP 接口

| 方法 | 路径 | 作用 |
| --- | --- | --- |
| GET / HEAD | /auth/login | 登录页；?next=/path 控制登录后回跳 |
| POST | /auth/login | 登录（application/x-www-form-urlencoded 或 application/json） |
| POST | /auth/logout | 清除会话 Cookie 并跳转登录页 |
| GET | /auth/status | 返回 { authenticated, required, username? }，状态码 200 或 401 |

登录 JSON 示例

{
"username": "admin",
"password": "...",
"next": "/"
}

行为说明

- 表单登录成功：303 + Set-Cookie（dsh_web_auth）+ Location 为净化后的相对路径（拦截 //evil、绝对 URL、响应拆分字符）。
- 登录失败：带错误提示的登录页（401），或限流页（429 + Retry-After）。
- 登录/登出在存在 Origin 头时校验其 host 是否与请求 Host 一致。
- 无有效会话的 WebSocket upgrade 会被关闭，并返回 401 JSON。
- 鉴权相关 HTML 响应设置 Cache-Control: no-store、严格 CSP、X-Frame-Options: DENY 等安全头。

在 DSH 中的位置

浏览器 / 客户端
│
▼
┌──────────────────────┐
│  dsh-web-auth        │  ← 会话 Cookie / 登录路由
│  (Authenticated      │
│   WebServer service) │
└──────────┬───────────┘
│ 仅已认证请求
▼
GUI · 插件 bundle · /api · SSE · WS
（通过 ctx.webServer. 注册）

与官方 web 服务兼容的接口：

- register({ kind, path, handler })
- registerUpgrade({ path, handler })
- registerFallback(handler)
- tapIndex(transform)
- host / port 访问器

命令行工具

包内二进制：dsh-web-auth

dsh-web-auth generate
输出 WEB_AUTH_PASSWORD=... 与 WEB_AUTH_PASSWORD_HASH=...

dsh-web-auth hash-password
从 WEB_AUTH_PASSWORD 或 stdin 读取口令，只打印 scrypt 散列

口令散列算法

CLI 使用 Node.js 内置的 crypto.scryptSync，对应 RFC 7914 定义的 scrypt 口令派生函数。scrypt 属于内存困难算法，相比普通快速散列，批量猜测口令需要付出更多 CPU 和内存成本。

每次生成散列时，插件会：

1. 通过 crypto.randomBytes 生成新的 16 字节随机盐。
2. 使用 N=16384、r=8、p=1 派生 64 字节密钥。
3. 将算法名、参数、盐和派生密钥保存为一个字符串；盐与密钥使用无填充的 Base64URL 编码。
4. 登录校验时读取已保存的参数，重新派生密钥，再通过 crypto.timingSafeEqual 做恒定时间比较。

插件不会保存原始口令。散列结果也不是可解密的密文。传给散列 CLI 的口令至少需要 12 个字符。

存储格式：

scrypt$N$r$p$$

默认参数中，N=16384 控制 CPU/内存成本，r=8 是块大小，p=1 是并行度；派生密钥为 64 字节，盐为 16 字节。Node.js scrypt 调用的内存上限至少设置为 64 MiB。

验证

npm run check          # 语法检查 + 单元测试
npm pack --dry-run     # 检查发布文件集合
dsh --profile web --dump-config

在 dump 中确认：

- 官方 webserver 行为 disabled: true
- 存在名称为 @summersec/dsh-web-auth 的 webserver-auth 行
- 启动日志不出现 FAILED

手动冒烟：

1. 无 Cookie 打开 GUI → 跳转 /auth/login。
2. 登录成功 → 进入应用，存在 Cookie dsh_web_auth。
3. 带 Cookie 访问 GET /auth/status → authenticated: true。
4. POST /auth/logout → 会话清除。
5. 连续登录失败超过阈值 → 429，窗口过期后恢复。

发布到 npm

包名：@summersec/dsh-web-auth（public scope）。

发布仅通过仓库的 GitHub Actions 工作流完成。不要将本地 npm publish 作为发布路径。

首次发布前，请在仓库 Actions Secrets 中配置名为 NPM_TOKEN 的 secret。该 npm token 必须拥有发布 @summersec 包的权限，并且 npm 组织的 2FA 与 CI 发布策略必须允许 GitHub Actions 使用此 token。

通过以下任一工作流入口发布：

1. 创建 GitHub Release，并使用与 package.json 中 X.Y.Z 版本严格对应的 vX.Y.Z tag。
2. 手动运行 Publish Node.js Package（workflow_dispatch），并填写完全一致的包版本号。

工作流会验证版本、运行检查，然后发布到 npm 与 GitHub Packages。push 和 pull request 只运行验证 job，不能发布包。

如果 GitHub Packages 已发布成功但 npm 发布失败，请打开该工作流运行记录并选择 Re-run failed jobs。不要重新运行整个工作流，否则会再次尝试发布相同版本的 GitHub Packages。

限制

- 内存会话：进程重启后全部失效；多实例无共享会话存储。
- 单账号边界：共享用户名/口令，不提供多用户 RBAC 或审计角色。
- 只保护 DSH Web 载体：其他端口或旁路服务需自行防护。
- 不能替代 TLS：非 loopback / 多用户网络务必前置 HTTPS。
- trustProxy 配置错误风险高：仅在监听端口只对可信反向代理开放时启用。

安全建议

- 优先使用 scrypt 散列，避免长期依赖明文环境变量。
- 默认 always 可避免“以为 loopback 就够安全”的误判（尤其是共享机器）。
- Cookie 标志与 Origin 校验能降低常见会话窃取与 CSRF 面，但不能替代网络隔离与 HTTPS。
- 若发现安全问题，请私下报告，勿在公开 issue 中贴完整利用细节。

目录结构

dsh-web-auth/
├── bin/dsh-web-auth.js   # generate / hash-password CLI
├── cordis.patch.yml      # DSH bundle：禁用官方 webserver，插入 webserver-auth
├── src/
│   ├── auth.js           # scrypt、会话、限流、Cookie 工具
│   └── index.js          # AuthenticatedWebServer 服务与登录页
├── test/                 # node:test 单元测试
├── package.json
├── README.md
└── README.zh-CN.md

友情链接

- 仓库：github.com/SummerSec/dsh-web-auth
- npm：@summersec/dsh-web-auth
- Topic：dsh-plugin
- LINUX DO

许可证

MIT