dsh-auth-gateway

dsh plugin --profile web add dsh-auth-gateway

dsh-auth-gateway

<p align="center">

<img src="https://raw.githubusercontent.com/xbzbing/dsh-auth-gateway/main/docs/assets/banner.png" alt="dsh-auth-gateway banner" width="880">

</p>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-auth-gateway"><img src="https://img.shields.io/npm/v/dsh-auth-gateway.svg" alt="npm version"></a>

<a href="https://www.npmjs.com/package/dsh-auth-gateway"><img src="https://img.shields.io/npm/dt/dsh-auth-gateway.svg" alt="npm total downloads"></a>

<a href="LICENSE"><img src="https://img.shields.io/npm/l/dsh-auth-gateway.svg" alt="npm license"></a>

</p>

<p align="center"><b>Language: 简体中文 | <a href="README.en.md">English</a></b></p>

为 DeepSeek Harness Web 提供认证门禁的 Cordis 插件：密码认证 + TOTP 双因素认证 + 多层防爆破 + 会话管理 + 登录审计，并在网关层真实拦截每一个请求（HTTP 与 WebSocket），未认证流量无法触及后端。

dsh web 的官方认证只面向本机回环：dsh 0.1.2 起内部 webserver 启用内置浏览器认证（BrowserAuth），但它只是一枚绑定 authority 的 bearer cookie——设计说明写明「没有登出操作」（"There is no logout operation"），且「认证不配置 TLS、转发头解释或代理」（"Authentication does not configure TLS, forwarding-header interpretation, or proxies"）。dsh 0.2.1 虽为直连场景补上了原生 HTTPS（--tls-cert / --tls-key）与具体 IP 绑定（CLI 仅拒绝 0.0.0.0 等通配地址，接受具体地址字面量），但认证层本身依旧没有登出、没有密码 / 多因素、没有防爆破、没有登录审计，也没有为「前面再套一层认证网关」预留任何集成通道。本插件以进程内网关的形态补上这层缺失的远程访问认证：对外端口由网关独占，内部 webserver 由 bundle patch 绑定在本地回环，网关是唯一入口。

本项目支持 0.1.5-rc.2 <= dsh <= 0.2.1-rc.2，均已实测。

已知缺陷：远程访问（域名 / 反向代理 / 局域网 IP 等非回环 http 入口）下无法登录 DeepSeek 账号——点左下角「登录 DeepSeek 账号」会立即报「登录失败」，其余功能均正常（会话、模型、工具、设置面板等）。根因在 dsh 上游：账号登录要求浏览器 origin 是带显式非零端口的回环 http 地址，而回环地址只在浏览器所在机器上解析——本插件无法在服务端绕过它（远程访问正是本插件提供的形态，所以该限制在这个部署形态下必然遇到）。判别与证据见 [docs/zh/TROUBLESHOOTING.md](docs/zh/TROUBLESHOOTING.md) 第 10 节。

手动解决方式（详细操作见 [docs/zh/DEPLOYMENT.md](docs/zh/DEPLOYMENT.md) 的「远程访问下登录 DeepSeek 账号」一节）：

1. 本机回环访问：浏览器与 dsh 同机时，直接打开 http://127.0.0.1:<网关端口>；

2. SSH 本地端口转发：浏览器在异地时执行 ssh -L 8080:127.0.0.1:<网关 listenPort> <部署机>（冒号前是本机端口，任选空闲端口），再浏览 http://127.0.0.1:8080；

3. 其它回环转发方式：任何能把 http://127.0.0.1:<显式端口> 映射到远端网关的隧道 / 端口转发工具（VS Code、kubectl port-forward、gost 等）；

4. 改用 API Key 通道：在账号弹窗里点「添加 API Key」，纯域名 / 反代部署下的既定替代方案。

安装和卸载

# 安装（从 npm registry）
dsh plugin --profile web add dsh-auth-gateway

# 启动（对外端口 8080，内部 webserver 自动挪到 8081；--no-open 让 dsh 不自己开浏览器）
dsh web --port 8080 --no-open

# 卸载（先清凭据，再移除插件）
~/.dsh/profiles/web/node_modules/.bin/dsh-auth-gateway-uninstall
dsh plugin --profile web remove dsh-auth-gateway

• 支持从 GitHub / 本地目录安装，见 [docs/zh/INSTALL.md](docs/zh/INSTALL.md)；
• 忘记密码用 dsh-auth-gateway-reset 重置（重启后控制台打印新初始密码）；
• 部署指南：[docs/zh/DEPLOYMENT.md](docs/zh/DEPLOYMENT.md)

功能特性

• 密码认证：首次部署自动生成初始密码（控制台打印，一次性），登录后引导设置个人密码（scrypt 哈希存储），之后每次访问需登录；
• 双因素认证（TOTP）：可选启用，兼容 Google Authenticator、Authy、1Password 等主流认证器；含一次性备份代码（scrypt 哈希存储、单次使用），设备丢失时可恢复访问；OTP 密钥以 AES-256-GCM 加密存储（主密钥来自环境变量 DSH_AUTH_GATEWAY_MASTER_KEY 或自动生成的 auth-gateway/otp-master.key），磁盘泄露不再直接暴露第二因素根密钥；
• 真实请求拦截：未认证 /api/* 返回 401、页面类路径 302 到登录页、WebSocket 升级直接拒绝；上游自有的一次性握手路径（publicPaths，默认 /oauth/callback）是唯一的匿名上游握手例外（公开静态资产本就匿名放行）——dsh 账号登录的回调由平台以跨站顶层导航回跳，浏览器必然不带会话 Cookie，见 [SECURITY.md](docs/zh/SECURITY.md#匿名可达的上游握手路径)；认证通过后请求透明转发（Host/Origin 规范化，兼容内部 trust fence）；
• 登录审计：登录成功 / 失败 / 登出 / 改密与暴力破解告警（锁定/限流）均输出审计日志（ctx.logger.info/warn，含来源 IP 与失败原因，不记录任何凭据），并持久化落盘 $DSH_HOME/auth-gateway/log/audit.log（JSONL，按天轮转、保留 90 天），形成完整可审计闭环；
• 多层防爆破：密码失败按来源锁定（默认 5 次/5 分钟）+ 全局速率限制（默认 60 次/分钟）+ OTP/备份码独立限流（默认 10 次/分钟），scrypt 在 libuv 线程池异步执行，登录洪峰不阻塞事件循环；
• 会话管理：内存 256-bit token（30 天），HttpOnly + SameSite=Strict Cookie，修改密码/禁用 OTP 吊销全部会话；
• 合规形态：host-only 插件（零构建、零运行时依赖）+ 可选 client 半（设置面板，源码构建），主体全部经 dsh 官方扩展点（ctx.effect、webServer.tapIndex、ctx.slots）；唯有一项记录在案的安全例外——LAN trust（为域名/反代访问下模型设置页可用而对 connection 注册做最小介入，见 [TROUBLESHOOTING §1](docs/zh/TROUBLESHOOTING.md)）。

本插件不做的事情

以下需求在"单实例"前提下无法真正实现——它们的前提是进程/OS 强制的执行与存储隔离（独立 OS 账号、容器或沙盒），而本插件只是运行在 dsh 进程内的认证网关，提供不了这层隔离。列出它们是为了明确预期、避免误导：

• 多账号登录 / 多租户：dsh 是单用户工具——一个 Home、一份模型凭据，全部会话与数据（sessions/、workspace/、.credentials.yaml）都以运行 dsh 的 OS 账号权限存放在本地。网关叠加"账号体系"只能区分谁在登录（访问控制 + 审计），无法隔离谁能看到什么：任何通过认证的用户都能经 dsh 的工具执行读取同一 Home 下的全部会话与凭据。没有 OS/容器/沙盒隔离就没有真正的多租户——本插件不做，也无法做到。
• 角色权限限制（用户/管理员）：同理，角色只能在网关自身的 HTTP 路由层生效（例如限制网关管理功能），挡不住 dsh 内部的能力面——普通用户一旦通过认证门，即拥有该实例的完整能力（工具执行、会话读写、配置与凭据访问）。需要"普通用户受限"的场景请用 OS 级隔离的多实例部署并自行管理账号。本插件的职责是：认证门禁（谁能进入）+ 拦截与审计（谁做了什么），不承担、也无法承担授权与隔离模型。

工作原理

flowchart LR
    B[浏览器] --> G["dsh-auth-gateway 网关<br/>对外端口 · 运行在 dsh 进程内"]
    G --> C{"认证检查<br/>会话表 O(1)"}
    C -->|未认证| U["/api/* → 401<br/>页面 → 302 /login<br/>WS 升级 → 拒绝"]
    C -->|未通过 2FA| O["/otp/verify"]
    C -->|已认证| F["转发<br/>Host/Origin 改写为回环"]
    F --> W["dsh webserver<br/>127.0.0.1:内部端口"]

• 网关生命周期与 dsh 绑定：随 dsh 启动/退出，无独立进程；
• bundle patch 将 webserver 移到回环端口（对外 = --port，内部 = 对外 + 1），远程无法绕过网关直连后端；
• 网关在 DSH 的 __ModuleLoader__ 加载 connection 模块时、Settings 等消费者启动前建立客户端 loopback trust——这是唯一记录在案的安全例外（仅拦截 connection 注册，其他插件原样通过）；该兼容层不替代登录、HTTP/WebSocket 门禁或服务端 fence，详见 [TROUBLESHOOTING §1](docs/zh/TROUBLESHOOTING.md)；
• 认证状态机：首次部署 → 初始密码登录 → 引导（设置个人密码）→ 登录 →（可选）OTP 验证 → 会话；未完成引导或 2FA 的会话仅能访问对应验证端点。

界面预览

<table>

<tr>

<td align="center"><img src="docs/assets/onboarding.png" width="480" alt="引导页（设置个人密码）"><br/>引导页（初始密码登录后）</td>

<td align="center"><img src="docs/assets/login.png" width="480" alt="登录（含 2FA 验证码）"><br/>登录（含 2FA 验证码）</td>

</tr>

<tr>

<td align="center"><img src="docs/assets/login-success.png" width="480" alt="2FA 登录成功"><br/>2FA 登录成功</td>

<td align="center"><img src="docs/assets/otp-setup.png" width="480" alt="OTP 设置（QR 码）"><br/>OTP 设置（QR 码）</td>

</tr>

<tr>

<td align="center"><img src="docs/assets/settings-menu.png" width="480" alt="设置菜单（含认证设置入口）"><br/>设置菜单（含"认证设置"入口）</td>

<td align="center"><img src="docs/assets/settings-auth.png" width="480" alt="认证设置面板"><br/>认证设置面板</td>

</tr>

</table>

快速开始

…(truncated)