前言¶

DSH 支持以插件方式扩展 web profile。当 DeepSeek Harness Web GUI 需要对外提供访问时，HTTP 路由和 WebSocket / HTTP upgrade 路径都需要有明确的认证边界。dsh-web-auth 是一个 DSH 插件，用于在请求到达应用路由前完成登录、会话和 cookie 控制。

这是什么¶

dsh-web-auth，npm 包名为 @summersec/dsh-web-auth，是 DeepSeek Harness Web GUI 的 transport-level authentication gate。它会禁用 stock webserver，并插入一个 auth-gated webServer service，让后续 Web GUI 访问先经过认证。

仓库地址为 https://github.com/SummerSec/dsh-web-auth，许可证为 MIT。

核心功能¶

• 认证 HTTP routes 和 WebSocket / HTTP upgrade paths。
• 默认 auth mode 为 always，包括 127.0.0.1。
• 可选 non-loopback mode：仅当绑定到 loopback 时跳过认证。
• 使用 scrypt$N$r$p$salt$key 形式的 scrypt password hashes。
• 会话保存为 32-byte random tokens，使用 in-memory store，并带 sliding TTL。
• 设置 HttpOnly 和 SameSite=Strict cookies，可选 Secure。
• 提供 per-client-IP login attempt limiting，并返回 Retry-After。
• 内置 /auth/login 页面，支持 light/dark theme，以及 form 或 JSON body。
• 在 auth responses 上应用 origin checks、open-redirect sanitization、CSP 和 frame denial。
• 禁用 stock webserver，并插入 auth-gated webServer service。

安装与启用¶

启用前需要满足以下条件：

• Node.js >= 22
• DeepSeek Harness 带有 web profile
• peer 依赖为 @deepseek-ai/cordis ^4.0.1

下面是基本的 PowerShell 使用流程。先离线生成 password 和 scrypt hash，再把 hash 导出到当前 shell，然后安装到 web profile：

npx --yes @summersec/dsh-web-auth generate

$env:WEB_AUTH_PASSWORD_HASH = 'scrypt$...'
$env:WEB_AUTH_USERNAME = 'admin'

dsh plugin --profile web add @summersec/dsh-web-auth

dsh web

generate 用于生成可保存到离线位置的 password 和 hash。后续运行时优先设置 WEB_AUTH_PASSWORD_HASH；WEB_AUTH_PASSWORD 只适合 temporary / lab use。

不要把 password 或 hash 放进共享或提交的 .env。如果认证 active，并且既没有配置 passwordHash，也没有配置 password，插件会在 startup 时抛出错误。

认证模式¶

默认模式是 always，即使服务绑定到 127.0.0.1 也会要求登录。

如果需要本地 loopback 访问时不触发认证，而在绑定非 loopback 地址时启用认证，可以设置 non-loopback：

$env:WEB_AUTH_MODE = 'non-loopback'
dsh web --host 0.0.0.0

这里需要注意：non-loopback 只会在绑定 loopback 时跳过认证；一旦绑定到 0.0.0.0 这类非 loopback 地址，认证会生效。

适用场景与注意¶

适合以下情况：

• DSH Web GUI 需要绑定非 loopback 地址。
• 希望同时保护 HTTP 路由和 WebSocket / HTTP upgrade 路径。
• 希望以 DSH 插件方式替换默认 webserver，而不是只加前端登录页。

使用注意：

• 该插件以当前 DSH 进程权限运行。安装前应检查源码与许可证。
• 会话保存在内存中；过期或 DSH 进程重启后，客户端会收到 authentication_required response。
• 优先使用 WEB_AUTH_PASSWORD_HASH，避免把明文 password 或 hash 放入共享 / committed .env。
• 认证 active 时，如果缺少 passwordHash 或 password，启动会失败，避免误开无认证服务。

结尾¶

dsh-web-auth 把登录边界放在 DSH Web GUI 的传输层，覆盖 HTTP 路由和 WebSocket / HTTP upgrade 路径，并提供 session、cookie、登录限流和基础安全响应处理。源码可查看：

https://github.com/SummerSec/dsh-web-auth