bamboostrip/dsh-access-gate

dsh-access-gate

DSH 远程访问认证门禁 · Remote access authentication gate for DeepSeek Harness

English · 中文

dsh plugin --profile web add dsh-access-gate

dsh-access-gate（中文）

DSH（DeepSeek Harness）远程访问认证门禁插件：解决“经 nginx 公网域名转发访问时，/api/ 全部 403”的问题 —— 认证通过后所有被浏览器信任护栏拦截的接口（含 settings.、credentials. 等 loopback 钉死的特权接口）全部可用；本机 127.0.0.1 访问不受影响；卸载插件一切还原，零残留、不污染用户配置。

同时是 dsh-lan-access 的完整替代品（0.0.0.0 绑定 + crypto.randomUUID polyfill + 远程认证 + 本机原生目录选择，一个包全包）。

功能

| 功能 | 说明 |
|---|---|
| 🔐 远程认证门禁 | 配置密码后，除本机直连外的访问（公网域名 / 局域网 IP / 同机 nginx 反代）需密码登录（HttpOnly Cookie，默认 7 天有效） |
| 🔓 默认无密码 | 未配置密码时远程直接放行（等价纯 lan-access），配置密码即启用门禁，设置界面实时生效、无需重启 |
| 🗂 本机原生目录选择 | 本机添加工作区弹官方原生目录对话框（Windows IFileOpenDialog / macOS choose folder / Linux zenity-kdialog，跨平台）；远程自动降级官方应用内浏览器 |
| 🌐 替代 dsh-lan-access | webserver 0.0.0.0 绑定 + crypto.randomUUID polyfill（幂等注入），卸载 lan-access 后无需额外配置 |
| 🧹 零残留 | 所有副作用随 ctx.effect 清理回调还原；不修改 DSH 源码、不写入用户配置文件 |
| 🛡 安全细节 | sha256 + timingSafeEqual 密码比较、防开放重定向、Host 欺骗封死、认证后 sec-fetch-site: cross-site 不再误杀 |
| 📐 TypeScript | 源码 TS + 编译产物，外部 API 契约集中在 src/types.ts（DSH 是测试版，升级可快速定位 API 变化） |

安装

方式一：npm 发布后（推荐）
dsh plugin --profile web add dsh-access-gate

方式二：GitHub 直装（lib/ 已提交，装上即用）
dsh plugin --profile web add github:bamboostrip/dsh-access-gate

方式三：本地开发（link: 符号链接，改代码只需 build + 重启）
npm run build
dsh plugin --profile web add link:E:/ALLCODE/project/dsh-auth-gate

兼容性：v0.6.0 起要求 DSH 0.1.0-rc.7+（设置卡片注册适配 keyed slot；rc.6 请用 v0.5.0）。

重启 DSH 生效。默认无密码：远程直接可访问。设置访问密码（二选一）：

① 推荐：DSH 设置界面 → 插件配置 → 访问认证 卡片
写入 ~/.dsh/.credentials.yaml；保存后实时生效，无需重启
② 环境变量（优先于文件层，适合脚本/CI）：
$env:DSH_GATE_PASSWORD='你的密码'   # PowerShell；重启 DSH 生效

npm 刚发布的新版本在官方 registry 立即可见，但国内镜像（如 npmmirror）同步可能有几分钟到数小时延迟 —— 如果 dsh plugin add 报找不到包，改用 GitHub 方式安装即可（见上）。

密码来源优先级：config.password > 环境变量 DSH_GATE_PASSWORD > ~/.dsh/.credentials.yaml > .env。

使用

- 默认无密码：远程（公网域名 / 局域网 IP）直接访问。
- 设置密码后：本机 http://127.0.0.1:3080 免密；远程首次访问 302 到登录页，登录后 7 天内免登录（有效期可配）。
- DSH 0.1.2-rc.1 起启动带 ?token=（每进程随机浏览器会话）：远程用户无需知道它 —— 密码登录成功后服务端自动把当前 token 注入重定向（浏览器随后自动完成 DSH 交换；进程重启后书签里的旧 token 下次登录时自动刷新）。
- nginx 与 DSH 同机时（remote 恒为 127.0.0.1 但 Host 是域名）同样需要密码 —— 公网流量无法绕过认证。
- 登录态在内存：DSH 进程重启后需重新登录。

公网 nginx 参考配置

server {
listen 443 ssl;
server_name codsh.famlife.top;
ssl_certificate ...; ssl_certificate_key ...;

location / {
proxy_pass http://10.144.144.7:3080;   # 家里 DSH
proxy_http_version 1.1;                # ★ 必须（默认 1.0 会断 WS）
proxy_set_header Host $host;           # 域名原样转发
proxy_set_header Upgrade $http_upgrade;        # ★ WS 必需
proxy_set_header Connection "upgrade";         # ★ WS 必需
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}

公网 403 排查清单见 NOTES.md。

可选配置（profiles/web/cordis.patch.yml 覆盖 auth-gate 行）

- id: auth-gate
config:
password: 'xxx'                        # 可选：行配置密码（最高优先）
trustedRemotePrefixes: ['10.144.144.0/24']   # 内网网段免密（IPv4 CIDR）
tokenTtlMs: 604800000                  # 登录有效期，默认 7 天

卸载（零残留）

dsh plugin --profile web remove dsh-access-gate

卸载后：包与 bundle patch 一起移除（webserver 绑定还原 DSH 默认、polyfill 停止注入），server.emit 拦截器、原生选择器路由、客户端智能 flow 与设置卡片全部随 ctx.effect 清理回调还原，登录态随进程退出消失。完整审计见 NOTES.md。

安全提示

- 默认无密码时，远程访问等价于本机操作权限（DSH 本身是远程执行工具）—— 公网暴露前请务必配置强密码，并建议 nginx 层加 IP 白名单 / Basic Auth 双保险。
- 请配合 nginx HTTPS 使用，防止密码与 Cookie 明文传输。
- 登录接口无失败次数限制（已知边界，见 NOTES §5）。

开发

npm install            # 首次：typescript / @types/node
npm run typecheck      # 类型检查
npm run build          # 编译 src/ → lib/
npm run check:package  # 包组合验证（防安装后启动失败）
npm run test:e2e       # 真机级 E2E（50 项断言，使用本机真实 DSH 模块）

- 结构：src/（TypeScript 源码）+ lib/（tsc 产物，随包提交保证装上即用）+ src/client.js（浏览器半边：智能目录选择 flow + 访问认证设置卡片）
- 对 DSH 外部 API 的依赖形状集中在 src/types.ts（每处附源码出处）—— DSH 升级后改这一处，编译器标出所有受影响调用点
- 完整技术方案与验证记录见 NOTES.md

License

MIT

dsh-access-gate（英文）

一个用于 DeepSeek Harness Web 的访问认证网关。它修复了“在公网 nginx 域名后，/api/ 上的所有内容都返回 403”的问题：通过密码认证后，所有被浏览器信任围栏阻止的端点——包括绑定回环地址的特权方法（settings.、credentials.、host.openPath、host.pickDirectory、llm.discoverModels、agentPreset.*）——都将完全可用。本地 127.0.0.1 访问不受影响，卸载后可零残留地还原一切。

它也是 dsh-lan-access 的完整替代品：0.0.0.0 绑定、crypto.randomUUID polyfill、远程认证，以及用于本地工作区选择的原生文件夹选择器——一个包即可全部覆盖。

功能特性

| 功能 | 描述 |
|---|---|
| 🔐 远程认证网关 | 配置密码后，除本地直连（公网域名 / 局域网 IP / 同主机 nginx 反向代理）之外的所有访问都需要密码登录（HttpOnly cookie，默认有效期 7 天） |
| 🔓 默认无密码 | 未配置密码 → 远程客户端可自由连接（等同于普通 lan-access）；配置密码即可启用网关——从设置页面实时生效，无需重启 |
| 🗂 面向本地用户的原生文件夹选择器 | 从本地机器添加工作区时，会打开官方原生目录对话框（Windows IFileOpenDialog / macOS 选择文件夹 / Linux zenity-kdialog，跨平台）；远程客户端自动回退到官方应用内浏览器 |
| 🌐 替代 dsh-lan-access | webserver 0.0.0.0 绑定 + crypto.randomUUID polyfill（幂等注入）；移除 lan-access 后无需额外配置 |
| 🧹 零残留 | 每个副作用都通过 ctx.effect 清理回调还原；绝不修改 DSH 源码或用户配置文件 |
| 🛡 安全细节 | sha256 + timingSafeEqual 密码比较、开放重定向防护、Host 欺骗拦截、认证后不再有 sec-fetch-site: cross-site 误报 |
| 📐 TypeScript | TS 源码 + 编译输出；外部 API 契约集中在 src/types.ts（DSH 是开发者预览版——升级导致的破坏易于定位） |

安装

方式 1：从 npm 安装（发布后推荐）
dsh plugin --profile web add dsh-access-gate

方式 2：直接从 GitHub 安装（lib/ 已提交，开箱即用）
dsh plugin --profile web add github:bamboostrip/dsh-access-gate

方式 3：本地开发（link: 符号链接；更改后重新构建并重启 DSH）
npm run build
dsh plugin --profile web add link:E:/ALLCODE/project/dsh-auth-gate

兼容性：v0.6.0 需要 DSH 0.1.0-rc.7+（设置卡片键控槽位注册；rc.6 请使用 v0.5.0）。

重启 DSH 以生效。默认无密码——远程客户端直接连接。要设置访问密码：

① 推荐：DSH 设置 → 插件配置 → “访问认证”卡片
存储在 ~/.dsh/.credentials.yaml；立即生效，无需重启
② 环境变量（优先于文件层；便于脚本/CI 使用）：
export DSH_GATE_PASSWORD='your-password'

密码解析顺序：config.password > 环境变量 DSH_GATE_PASSWORD > ~/.dsh/.credentials.yaml > .env。

用法

- 默认无密码：远程访问（公网域名 / 局域网 IP）可直接使用。
- 设置密码后：本地 http://127.0.0.1:3080 保持免密码；远程首次访问会 302 重定向到登录页；已登录会话 7 天内跳过登录（可配置）。
- 当 nginx 与 DSH 运行在同一主机上时（远程始终是 127.0.0.1，但 Host 是域名），仍然需要密码——公网流量无法绕过认证。
- 登录状态保存在内存中：DSH 重启后需要重新登录。

公网 nginx 参考配置

server {
listen 443 ssl;
server_name codsh.famlife.top;
ssl_certificate ...; ssl_certificate_key ...;

location / {
proxy_pass http://10.144.144.7:3080;   # 你的 DSH 主机
proxy_http_version 1.1;                # ★ 必需（1.0 会破坏 WebSocket）
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;        # ★ WebSocket
proxy_set_header Connection "upgrade";         # ★ WebSocket
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}

公开 403 故障排查清单见 NOTES.md。

可选配置（覆盖 profiles/web/cordis.patch.yml 中的 auth-gate 行）

- id: auth-gate
config:
password: 'xxx'                        # 可选：行级密码（最高优先级）
trustedRemotePrefixes: ['10.144.144.0/24']   # 免密码的局域网 CIDR（IPv4）
tokenTtlMs: 604800000                  # 登录有效期，默认 7 天

卸载（零残留）

dsh plugin --profile web remove dsh-access-gate

该包及其 bundle 补丁会一并消失（webserver 绑定恢复为 DSH 默认值，polyfill 停止），并且 server.emit 拦截器、原生选择器路由、客户端智能流程以及设置卡片都会通过 ctx.effect 清理而全部还原。完整审计：NOTES.md。

安全说明

- 未设置密码时，远程访问等同于本机权限（DSH 是一个远程执行工具）——在公开暴露之前请配置强密码，并考虑在 nginx 层设置 IP 允许列表 / Basic Auth。
- 使用 nginx HTTPS 以防止密码和 cookie 在传输过程中被窃听。
- 登录端点目前尚无速率限制（已知限制，见 NOTES §5）。

开发

npm install            # 首次：typescript / @types/node
npm run typecheck      # 类型检查
npm run build          # 编译 src/ → lib/
npm run check:package  # 包组成检查（防止启动失败）
npm run test:e2e       # 机器级 E2E（针对真实 DSH 模块的 50 条断言）

- 布局：src/（TypeScript 源码）+ lib/（tsc 输出，已提交以便开箱即用安装）+ src/client.js（浏览器端：智能目录流程 + 访问认证设置卡片）
- 外部 DSH API 契约位于 src/types.ts（每个声明都标注了其来源位置）——当 DSH 升级时，只需修改该文件，编译器就会标记出所有受影响的调用点
- 完整技术说明和验证记录：NOTES.md

许可证

MIT