零信任认证网关lijx122/dsh-plugin-auth-guard

dsh-plugin-auth-guard

面向 DeepSeek Harness (DSH) 的企业级零信任身份认证、局域网/公网访问控制与安全网关插件

=20">

英文文档 | 简体中文文档 (README_CN.md)

📖 背景与问题陈述

DeepSeek Harness (DSH) 是一款强大的 AI 编程智能体运行时，原生为本地桌面工作流（127.0.0.1）而设计。当开发者尝试将 DSH 通过局域网（LAN）暴露给移动设备（iOS/Android），或将其托管在远程云服务器上时，会遇到以下关键障碍：

1. 特权接口 403 拦截：DSH 原生强制执行硬编码的环回地址防护。任何非 localhost 请求调用 settings.describe 或 llm.providers 都会被 403 Forbidden 拦截，导致远程模型切换无法进行。
2. 移动端 RPC 崩溃：移动端浏览器（iOS Safari / Chrome Android）在纯 HTTP 下缺乏安全上下文（Secure Context），导致 crypto.randomUUID 为 undefined，进而破坏所有 RPC。
3. 严重的远程代码执行（RCE）风险：DSH 缺乏内置身份认证。将 3080 端口开放至局域网或广域网，会让网络上的任何人都能创建会话，并通过编程智能体执行任意 shell 命令。
4. 第三方插件逃逸：侧边栏插件（dsh-better-sidebar）和包管理器暴露了 PTY 终端套接字（/sidebar/ws/terminal）以及任意文件访问，且无任何身份认证。

dsh-plugin-auth-guard 是零侵入、生产就绪的解决方案。 它解除远程访问限制，动态注入移动端 polyfill，并建立起一套全栈默认拒绝的零信任安全网关，配备加密凭据生命周期管理。

🏗️ 架构概览

flowchart TD
Client[Client Device Phone/Tablet/PC] -->|HTTP / WebSocket| Ingress[Node.js http.Server: 3080]
Ingress --> L1[L1: Physical Socket Origin Check isPhysicalLoopback]
L1 --> L2[L2: Enterprise Security Headers nosniff / SAMEORIGIN / Referrer / no-store]
L2 --> L3[L3：64KB 载荷 OOM 保护]
L3 --> L4[L4：CSRF 与 CSWSH 严格主机名比对]
L4 --> L5{L5：公开白名单严格正则匹配}

L5 -->|已列入白名单：静态文件 / 登录 API| PassPublic[提供静态资源]
L5 -->|未列入白名单：核心 RPC / 插件路由 / 终端 WS| L6{L6：密码指纹 HMAC-SHA256 验证}

L6 -->|已认证 / 物理回环| Router[转发至核心应用 / 代理特权 RPC]
L6 -->|未认证 / 令牌已撤销| Block[以 HTTP 401 阻止 / 销毁 WebSocket]

🌟 亮点与技术规格

1. 🌐 自适应网络暴露与特权 RPC 桥接
- 0.0.0.0 自动绑定：将 Web GUI 绑定至 0.0.0.0:3080，并动态枚举所有活跃的局域网 IPv4 接口。
- 特权 RPC 代理：为已认证客户端安全代理 settings.describe、llm.providers、credentials.，彻底消除 403 Forbidden 错误。
- 动态移动端 Polyfill 注入：通过 tapIndex 即时向  注入加密 UUID polyfill，确保移动端在 HTTP 下流畅运行。

2. 🛡️ 默认拒绝零信任网关
- 套接字级拦截：在最底层 TCP 服务器级别拦截 HTTP request 与 WebSocket upgrade 事件。
- 严格白名单验证：阻止未认证访问所有核心 RPC（/api/）、插件管理器（/api2/）及侧边栏路由（/sidebar/）。

3. 🔑 加密安全与凭据生命周期
- 加盐 Scrypt 密码哈希：32 字节 Scrypt 哈希配合随机盐。配置字段以 .role('secret') 声明，防止线上泄露。
- 常量时间验证：crypto.timingSafeEqual 防止时序侧信道攻击。
- 密码指纹绑定：HMAC-SHA256 令牌内嵌当前密码指纹。更改密码可在毫秒内全局即时撤销所有令牌。
- 主动 WebSocket 清除：密码更改或登出时自动终止所有活跃的远程终端/事件 WebSocket。

4. 🚫 防欺骗与 DoS 防护
- 物理套接字验证：验证 req.socket.remoteAddress，防止 Host: 127.0.0.1 欺骗及代理回环反转。
- IP 滑动窗口限流：连续 5 次失败尝试后封禁 IP 15 分钟（HTTP 429），并自动垃圾回收（GC）。
- 全局突发节流：将所有 IP 的总登录频率限制为 40 次请求/分钟，以抵御分布式僵尸网络。
- 64KB 请求体截断：中止超过 64KB 的载荷，防止基于流的 OOM 拒绝服务攻击。
- CSRF 与 CSWSH 防护：严格主机名比对阻止跨源请求伪造与跨站 WebSocket 劫持。

5. 🎨 原生 DSH UI 设计与多标签页同步
- DeepSeek 设计系统：遵循 DSH CSS 令牌（--dsw-*）、鱼形标志及标准排版。
- 顶层 Body Portal 锁定：将锁屏挂载到 document.body 层级（z-index: 2147483647），并带有背景模糊，以防止点击穿透。
- 多标签页同步：利用 BroadcastChannel 实现跨标签页状态的即时更新。

📦 安装与设置

方式 1：通过 DSH CLI（推荐）
dsh plugin --profile web add github:lijx122/dsh-plugin-auth-guard

方式 2：通过 DSH Web 市场
1. 在 DSH Web GUI 中，前往 Settings $
ightarrow$ Plugins $
ightarrow$ Marketplace。
2. 搜索 auth-guard 并点击 Install。

方式 3：本地链接（开发者模式）
1. 将此仓库克隆到 ~/.dsh/plugins/dsh-plugin-auth-guard。
2. 在 ~/.dsh/profiles/web/package.json 中，添加：
{
"dependencies": {
"dsh-plugin-auth-guard": "link:../../plugins/dsh-plugin-auth-guard"
}
}

3. 将 "dsh-plugin-auth-guard" 追加到 dsh.profile.bundles，然后重启 DSH。

⚙️ 配置指南

前往 Settings $
ightarrow$ Security & Access（安全与访问）：

| 设置 | 描述 | 默认值 |
| :--- | :--- | :---: |
| Require password for LAN/Remote access | 从非 localhost IP 访问时要求密码认证 | 已启用 |
| Enforce authentication globally | 即使在 127.0.0.1 localhost 上也强制密码认证 | 可选 |
| Administrator Credentials | 设置或更改管理员用户名和密码（$\ge 6$ 个字符） | 可自定义 |
| Active LAN IP Directory | 实时概览所有正在监听的 LAN 地址，并支持一键复制 | 自动检测 |

🚀 5 项必备反向代理设置（Nginx / Caddy / Cloudflare）

在反向代理后部署时，请配置以下 5 项设置，以确保大文件上传顺畅、流式响应无缓冲，以及准确的零信任边界防御：

1. 增大最大请求体大小（必须，以避免 413）
Nginx 默认的 client_max_body_size 为 1MB，会拒绝图片和文件上传。
- 设置：client_max_body_size 160M;（与 DSH 160MB 上传容量保持一致）。

2. 转发真实客户端 IP 和协议（对安全至关重要）
auth-guard 依赖这些请求头来区分本地流量与代理流量，并应用准确的速率限制：
- 设置：
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

3. 启用 WebSocket 协议升级（必须）
DSH 实时对话流和侧边栏 PTY 终端需要 WebSocket 支持。
- 设置：
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

4. 延长请求超时时间（用于长时间 AI 推理）
防止 Nginx 在长时间运行的 agent 工具运行期间断开连接。
- 设置：
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

5. 禁用响应缓冲（用于实时令牌流式传输）
确保令牌逐字符流式传输到浏览器，而不会出现代理级别的缓冲延迟。
- 设置：proxy_buffering off;

📑 生产就绪的 Nginx 配置模板

1. HTTP -> HTTPS 重定向
server {
listen 80;
server_name dsh.yourdomain.com;
return 301 https://$host$request_uri;
}

2. HTTPS 代理核心
server {
listen 443 ssl http2;
server_name dsh.yourdomain.com;

SSL 证书
ssl_certificate     /etc/nginx/ssl/dsh.yourdomain.com.crt;
ssl_certificate_key /etc/nginx/ssl/dsh.yourdomain.com.key;
ssl_protocols       TLSv1.2 TLSv1.3;
ssl_ciphers         HIGH:!aNULL:!MD5;

[关键点 1] 允许最大 160MB 的文件上传
client_max_body_size 160M;

location / {
proxy_pass http://127.0.0.1:3080;
proxy_http_version 1.1;

[关键点 2] WebSocket 升级支持
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

[关键点 3] 真实 IP 和协议转发
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

[关键点 4 和 5] 超时与无缓冲实时令牌流式传输
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}

❓ 常见问题与故障排除

Q1：如果我忘记了管理员密码，该怎么办？
1. 在主机上打开 ~/.dsh/settings.yaml。
2. 在 auth-guard: 下，清空 passwordHash 和 salt（设置为 ""）。
3. 重启 DSH，并在本地打开 http://127.0.0.1:3080 来初始化新密码。

Q2：为什么更改密码后其他设备会被登出？
这是设计使然。更改密码会更新令牌中的密码指纹，并触发主动 WebSocket 清除，以确保被盗用的凭据无法被重复使用。

Q3：为什么移动端 Safari 在没有 HTTPS 证书的情况下可以通过纯 HTTP 正常工作？
该插件在提供 HTML 服务时动态注入 crypto.randomUUID polyfill，从而无需本地 SSL 设置即可实现无缝的移动端操作。

📄 许可证

根据 MIT 许可证 分发。