dsh-plugin-auth-guard

DeepSeek Fish Logo

DeepSeek Harness (DSH) 原生企业级零信任安全访问控制与账号密码防护插件

📖 痛点与背景（为什么需要此插件？）

DeepSeek Harness (DSH) 是一款出色的本地 AI Coding Agent 框架。由于原生定位主要面向单机桌面开发（127.0.0.1 本机环境），当开发者尝试在局域网多设备（如手机/平板/办公室电脑）或云服务器公网部署时，会面临四大核心痛点与重大安全隐患：

特权接口 403 拦截：DSH 核心源码中硬编码了回环安全栅栏，只要非 127.0.0.1 访问，模型配置读取（settings.describe）和提供商列表（llm.providers）一律被服务端强制返回 403 Forbidden，导致跨设备无法切换或配置模型。
移动端非 HTTPS 运行崩溃：iOS Safari 和 Android 移动端浏览器在非 HTTPS 局域网环境下，因缺少安全上下文（Secure Context）导致 crypto.randomUUID 为空，前端 RPC 通信全线瘫痪。
远程暴露等同于全网开放 RCE（远程代码执行）：原生 DSH 缺乏身份鉴权机制。只要将端口开放到局域网或公网，任何扫描到端口的访客均可直接调用 session.create / session.append 让 Agent 在你的主机上执行任意 Shell / PowerShell 命令。
第三方生态插件特权逃逸：侧边栏插件（如 dsh-better-sidebar）直接暴露了 /sidebar/ws/terminal 交互式 PTY 终端与文件读写接口，外部人员可直接直连终端接管机器。

dsh-plugin-auth-guard 正是为此而生：它在零侵入 DSH 核心源码的前提下，一键解除网络访问限制、动态注水移动端 Polyfill，并构建起一套全站 Default-Deny 零信任安全网关与密码凭据全生命周期管理系统。

🏗️ 架构设计与防护机理

flowchart TD
    Client[客户端设备 Phone/Tablet/PC] -->|HTTP / WebSocket| Ingress[Node.js http.Server: 3080]
    Ingress --> L1[L1: 物理套接字来源强校验 isPhysicalLoopback]
    L1 --> L2[L2: 响应头防御 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 -->|未认证 / Token已吊销| Block[全局 401 阻断 / 切断 WebSocket]

🌟 核心特性与技术指标

1. 🌐 局域网自适应与特权智能放行

0.0.0.0 自动绑定：通过 Cordis 补丁层无缝将 Web GUI 绑定至 0.0.0.0:3080，自动探测并列出本机所有活跃 IPv4 网卡地址。
特权接口安全代理：通过精确路由机制为已认证客户端智能代理 settings.describe、llm.providers、credentials.* 等特权接口，告别跨设备 403 错误。
移动端 Polyfill 动态注水：通过 ctx.webServer.tapIndex 动态向 HTML <head> 注入加密级 UUID 生成器，手机 Safari / Android 零报错秒开。

2. 🛡️ 全局零信任前置网关（Default-Deny Gateway）

全链路封锁：在 Node.js http.Server 最底层接管所有 request 和 upgrade 事件。
白名单严格准入：除静态资源（严格限定 .js、.css、.svg、.woff2 等合法后缀）及登录端点外，全站所有核心接口及第三方插件接口（如 /api2/* 插件管理器、/sidebar/* 侧边栏文件与终端）未认证一律物理掐断。

3. 🔑 企业级密码学与 Token 全生命周期

加盐 Scrypt 安全存储：密码采用加盐 Scrypt（32字节）算法单向哈希，配置在 settings.yaml 中标记为 role: secret，API 响应零机密泄露。
时序攻击防御：密码比对与 Token 验签均采用 crypto.timingSafeEqual，完全免疫时序侧信道攻击。
密码指纹绑定与即刻吊销：HMAC-SHA256 Token 载荷深度绑定当前密码指纹，管理员一旦修改密码，全网所有已登录设备的历史 Token 毫秒级即刻作废。
存量长连接强制熔断：管理员改密或注销时，服务端主动销毁所有现存的远程 WebSocket 套接字（/sidebar/ws/terminal），防止终端逃逸。

4. 🚫 网络防伪、防爆破与 DoS 熔断

防 Host / 代理冒充：物理 TCP Socket remoteAddress 强校验，严禁通过伪造 Host: 127.0.0.1 越权；在反代环境下自动识别代理头，防止公网访客冒充回环。
IP 滑动窗口防爆破：单 IP 连续输错 5 次密码自动锁定该 IP 15 分钟（HTTP 429），并具备 5000 记录自动垃圾回收（GC）。
全站并发熔断：全站每分钟最多处理 40 次登录尝试，防止分布式代理池并发撞库。
64KB 流量熔断：请求体限制在 64KB 内，超大垃圾流量立即断开连接，防御 OOM 内存耗尽攻击。
防 CSRF & CSWSH：严格全等比对 Hostname，防御跨站请求伪造与跨站 WebSocket 劫持。

5. 🎨 原生 DSH UI 美术风格与多端联动

品牌美术深度融合：全面适配 DSH 官方 CSS 变量（--dsw-*）、官方鲸鱼 Logo 及圆角设计。
Top-Level 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 插件市场安装

打开 DSH Web 界面 $ ightarrow$ 点击左下角 “设置 (Settings)” $ ightarrow$ “插件 (Plugins)” $ ightarrow$ “插件市场 (Marketplace)”。
搜索 auth-guard 或 安全，点击 “安装”。

方式 3：本地开发调试（源码软链接）

克隆本项目至 ~/.dsh/plugins/dsh-plugin-auth-guard。

在 ~/.dsh/profiles/web/package.json 中配置：

{
  "dependencies": {
    "dsh-plugin-auth-guard": "link:../../plugins/dsh-plugin-auth-guard"
  }
}

在 dsh.profile.bundles 中追加 "dsh-plugin-auth-guard"，重启 DSH 即可。

⚙️ 配置说明

浏览器打开 DSH，点击左下角 “设置 (Settings)” $ ightarrow$ “安全与访问” 专属卡片：

配置项	说明	默认推荐值
局域网/公网访问必须密码验证	开启后，非服务器本机设备访问时强制弹出全屏锁屏门禁，验证通过后方可使用	开启
全局强制密码认证 (包含本机)	开启后，即使在服务器本机 `127.0.0.1` 访问同样需要密码登录	可选
管理员账号与密码	支持随时修改用户名与新密码（长度需 $\ge 6$ 位，敏感变更需校验原密码）	自定义
局域网地址速查	自动枚举当前设备的所有局域网 IP 与端口，支持点击一键复制	自动展示

🚀 反向代理（如 Nginx）环境下必须做的 5 项关键设置

在反代（Nginx / Caddy / Traefik / Cloudflare）环境下，为了让大文件上传畅通、AI 流式打字不卡顿、同时让安全网关精准防御，必须做以下 5 项针对性配置：

1. 放开反代自身的文件上传大小（必配，否则报 413）

Nginx 默认的 client_max_body_size 只有 1MB。上传稍大一点的图片、代码仓库压缩包或附件就会被 Nginx 直接拦截。

设置：client_max_body_size 160M;（与 DSH 允许的最大体量 160MB 对齐）。

2. 透传客户端真实 IP 与协议（安全核心，必配）

auth-guard 在底层判断连接是“物理本机直连”还是“外部反代”依赖这些 Header：

如果不传 X-Real-IP 和 X-Forwarded-For，插件拿到的底层 TCP 地址全是 127.0.0.1（因为连接是 Nginx 发起的），会导致外网防爆破限流失效，或误将外网访客判定为本机。

设置：

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 思考时连接被切断）

AI 在进行复杂任务或长思考推理时，单次请求可能持续数分钟，Nginx 默认 60 秒无数据会自动切断连接。

设置：

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

5. 关闭响应缓冲（提升流式打字输出体验）

让 AI 的回复能够实时逐字推送到浏览器，而不是被 Nginx 缓存一块后批量卡顿输出。

设置：proxy_buffering off;

📑 生产级 Nginx 完整配置范例

如果使用 Nginx 进行 HTTPS 反向代理，可以直接使用以下配置模板：

# 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 / {
        # 转发到本地 DSH 端口
        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 与域名透传（供 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;

        # 【关键设置 4】超时与流式打字输出配置
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffering off;
    }
}

❓ 常见问题与排查 (FAQ)

Q1: 忘记了管理员密码，如何重置？

由于密码哈希保存在本地配置文件中，直接在服务器物理主机上编辑配置文件即可重置：

打开 ~/.dsh/settings.yaml。
找到 auth-guard: 分节，将 passwordHash 与 salt 清空（设为 ""）。
重启 DSH 后，在物理本机（127.0.0.1:3080）重新打开网页即可初始化新密码。

Q2: 为什么修改密码后，其他已登录的手机或电脑自动退出了？

这是本插件的 Token 密码指纹绑定与主动 WebSocket 熔断机制。管理员修改密码后，全网所有旧令牌会立即失效，存量长连接终端会被服务器主动切断，以确保密码泄露时能一键阻断所有潜在攻击者。

Q3: 为什么局域网普通 HTTP 访问也能在手机 Safari / Chrome 上正常工作？

插件内置了 tapIndex 动态注水引擎，在 HTML 渲染阶段自动下发 crypto.randomUUID Polyfill，无需在局域网自建复杂的 CA 证书即可畅享移动端 Web 访问。

📄 开源协议

本项目采用 MIT License 开源协议。

lijx122/dsh-plugin-auth-guard