前言¶

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