dsh-auth-gateway
Password login gateway plugin for dsh web: auto-generated initial password with forced onboarding, login, password change with real request interception, and OTP two-factor authentication.
The plugin will be installed here. Keep web if you are unsure.
npx -y @deepseek-ai/dsh plugin --profile web add dsh-auth-gateway@0.8.1
Auth Gateway is published as dsh-auth-gateway and currently resolves to version 0.8.1. The Hub verifies its manifest and preserves the exact installation source for reproducible installs.
Language: 简体中文 | English
为 DeepSeek Harness Web 提供认证门禁的 Cordis 插件：密码认证 + TOTP 双因素认证 + 多层防爆破 + 会话管理 + 登录审计，并在网关层真实拦截每一个请求（HTTP 与 WebSocket），未认证流量无法触及后端。
dsh web 的官方认证只面向本机回环：dsh 0.1.2 起内部 webserver 启用内置浏览器认证（BrowserAuth），但其设计说明明确写道「没有登出操作，也没有针对反向代理/网关的处理」（"There is no logout operation or reverse-proxy-specific handling"），CLI 依旧拒绝 --host 0.0.0.0——dsh 从未预想或支持远程访问，也没有为「前端再套一层网关」预留任何集成通道。本插件以进程内网关形态补齐官方未提供的远程访问认证面：对外端口由网关独占，内部 webserver 由 bundle patch 钉在回环地址，网关是唯一入口。
本项目已支持最新的 dsh 0.1.6-alpha.2 版本。dsh 0.1.2 起内部 webserver 新增了内置浏览器认证（BrowserAuth）：网关经官方 credentials 服务读取 upstream 会话密钥，为回环转发自动铸造 upstream cookie，对浏览器与部署方式透明（机制详见 docs/zh/SECURITY.md）。0.1.5 与 0.1.6 系列均已验证兼容：网关所依赖的全部扩展点（webServer.tapIndex、dsh.bundle patch、settings.section slot、credentials record 与 BrowserAuth cookie 格式）在 0.1.6-alpha.2 均未变动（settings 面板新增官方 section 至 order 25，本插件 100 依然严格最大），WS 无限重连与文件上传流式转发均可正常通过网关；0.1.6 起 profile 配置 HMR 默认开启（dsh-hmr），部署后插件自身变更仍按既有流程生效。
# 安装（从 npm registry）
dsh plugin --profile web add dsh-auth-gateway
# 启动（对外端口 8080，内部 webserver 自动挪到 8081）
dsh web --port 8080
# 卸载（先清凭据，再移除插件）
~/.dsh/profiles/web/node_modules/.bin/dsh-auth-gateway-uninstall
dsh plugin --profile web remove dsh-auth-gateway
dsh-auth-gateway-reset 重置（重启后控制台打印新初始密码）；DSH_AUTH_GATEWAY_MASTER_KEY 或自动生成的 auth-gateway/otp-master.key），磁盘泄露不再直接暴露第二因素根密钥；/api/* 返回 401、页面类路径 302 到登录页、WebSocket 升级直接拒绝；认证通过后请求透明转发（Host/Origin 规范化，兼容内部 trust fence）；ctx.logger.info/warn，含来源 IP 与失败原因，不记录任何凭据），并持久化落盘 $DSH_HOME/auth-gateway/log/audit.log（JSONL，按天轮转、保留 90 天），形成完整可审计闭环；package.json，离线可用），并可用「检查更新」按钮主动查询新版本——自动检查默认关闭，全新安装不会发起任何对外请求；点击按钮才会让网关向公共 npm registry 查询一次 latest 标签（这是本插件唯一的对外请求，见 安全模型）。registry 不可达时显示「暂时无法检查更新」，绝不干扰认证与转发；ctx.effect、webServer.tapIndex、ctx.slots）；唯有一项记录在案的安全例外——LAN trust（为域名/反代访问下模型设置页可用而对 connection 注册做最小介入，见 TROUBLESHOOTING §1）。以下需求在"单实例"前提下无法真正实现——它们的前提是进程/OS 强制的执行与存储隔离（独立 OS 账号、容器或沙盒），而本插件只是运行在 dsh 进程内的认证网关，提供不了这层隔离。列出它们是为了明确预期、避免误导：
sessions/、workspace/、.credentials.yaml）都以运行 dsh 的 OS 账号权限存放在本地。网关叠加"账号体系"只能区分谁在登录（访问控制 + 审计），无法隔离谁能看到什么：任何通过认证的用户都能经 dsh 的工具执行读取同一 Home 下的全部会话与凭据。没有 OS/容器/沙盒隔离就没有真正的多租户——本插件不做，也无法做到。浏览器 ──> dsh-auth-gateway 网关（对外端口，运行在 dsh 进程内）
│ 每个请求先过认证检查（会话表 O(1)）
├─ 未认证 ─> /api/*: 401 ｜ 页面: 302 /login ｜ WS: 拒绝
├─ 未通过 2FA ─> /otp/verify
└─ 已认证 ─> 转发（Host/Origin 改写为回环）──> dsh webserver（127.0.0.1:内部端口）
--port，内部 = 对外 + 1），远程无法绕过网关直连后端；__ModuleLoader__ 加载 connection 模块时、Settings 等消费者启动前建立客户端 loopback trust——这是唯一记录在案的安全例外（仅拦截 connection 注册，其他插件原样通过）；该兼容层不替代登录、HTTP/WebSocket 门禁或服务端 fence，详见 TROUBLESHOOTING §1；首次部署 → 初始密码登录 → 引导（设置个人密码）→ 登录 →（可选）OTP 验证 → 会话；未完成引导或 2FA 的会话仅能访问对应验证端点。| 引导页（设置个人密码） 引导页（初始密码登录后） | 登录（含 2FA 验证码） 登录（含 2FA 验证码） |
| 2FA 登录成功 2FA 登录成功 | OTP 设置（QR 码） OTP 设置（QR 码） |
| 设置菜单（含认证设置入口） 设置菜单（含"认证设置"入口） | 认证设置面板 认证设置面板 |
dsh web：首次部署自动生成初始密码并打印在控制台（醒目提示块）；请复制备用；/otp/setup 启用 TOTP（扫码或手动输入密钥，输入验证码确认；同时生成备份代码请妥善保存）；/login（已登录时显示改密表单），或经"认证设置"面板。以下字段为 bundle patch / profile patch 中 dsh-auth-gateway 行的 config（Standard Schema 校验）：
| 字段 | 默认 | 含义 |
|---|---|---|
listenHost / listenPort | 0.0.0.0 / 3080 | 网关对外监听地址与端口 |
upstreamHost / upstreamPort | 127.0.0.1 / 3081 | 内部 webserver 地址与端口 |
basePath | / | 反向代理子路径前缀（如 /dsh）；默认 /（根路径）。字符集限 A-Za-z0-9._~/-，拒绝 ..、//、引号、空白、尖括号（该值会内嵌进页面脚本与链接，故按白名单校验；不合规配置会在加载时被拒绝）。子路径部署时在部署方 profile patch 中配置，不随插件分发 |
cookieSecure | auto | 会话 Cookie 是否携带 Secure 属性。auto（默认，向后兼容）：请求经 TLS（反向代理终结并透传 X-Forwarded-Proto: https，或网关自身建立 TLS）时自动附加——前置 HTTPS 后无需改配置即启用；true：强制附加（反代已终结 TLS 但未透传协议头的部署）；false：显式关闭（仅建议可信内网）。注意：Secure 只在 HTTPS 链路生效——纯 HTTP 下强制开启会使浏览器拒绝保存 Cookie、登录立即失效（显式失败，而非静默降级）。面板可直接修改（「认证设置 → Cookie 安全 → 保存/恢复为部署配置」）：面板覆盖持久化于凭据记录（记录写接口实测于 dsh 0.1.5-rc.2+；更早版本缺失时面板自动降级为只读），优先于部署配置，直至恢复 |
minPasswordLength | 8 | 密码最小长度（4–128） |
requireMixedCase / requireSpecial | true / true | 密码复杂度：大小写混合或特殊字符二选一满足 |
maxLoginFailures / lockMinutes | 5 / 5 | 密码失败锁定阈值与时长 |
maxGlobalAuthAttemptsPerMinute | 60 | 全局登录尝试速率上限 |
maxOtpAttemptsPerMinute | 10 | 单来源 OTP/备份码验证速率上限 |
otpEnabled（已废弃） | false | 不再作为启用开关——2FA 由用户登录后在「认证设置」中绑定激活；字段保留仅为兼容旧配置 |
otpRequired | false | 2FA 激活后强制每次登录验证（无需任何配置） |
otpIssuer / otpPeriod / otpDigits / otpWindow | dsh-auth-gateway / / / |
认证状态变更（启用/禁用 OTP、修改密码）均要求完整验证：2FA 激活时禁用 OTP 需当前密码 + 验证码或备份代码；未完成 2FA 的会话不能访问敏感端点。OTP 验证防重放（记录已接受时间步）、防伪造（x-forwarded-for 不计入来源）。OTP 密钥在落盘前以 AES-256-GCM 密封，读取需主密钥——默认自动生成 auth-gateway/otp-master.key（0600），也可经环境变量 DSH_AUTH_GATEWAY_MASTER_KEY（hex/base64，32 字节）注入以隔离磁盘泄露。登录审计只记录事件种类、来源 IP 与失败原因，不落任何凭据。完整威胁模型、已知限制与恢复路径见 docs/zh/SECURITY.md。
| 文档 | 内容 |
|---|---|
| docs/zh/INSTALL.md（English） | 安装、更新、卸载、凭据重置的完整操作步骤 |
| docs/zh/NGINX-DEPLOYMENT.md（English） | 配合 nginx 部署：裸金属直连 / 子域名 / 子路径 / Docker nginx 容器四种拓扑与配置示例 |
| docs/zh/SECURITY.md（English） | 威胁模型、OTP 安全设计、已知限制与恢复路径 |
| docs/zh/DEPLOYMENT.md（English） | 端口与监听、LAN 部署、HTTPS 建议、nginx 反向代理、故障排查 |
| docs/zh/TROUBLESHOOTING.md（English） | 实机故障案例：域名下模型页不可用、原生依赖构建被拦、bundle 加载失败、版本线凭据格式、跨境超时优化 |
| docs/zh/TESTING.md（English） | 单元测试、端到端（Playwright）、API/WebSocket 门禁验证 |
| docs/DEVELOPMENT.md（English） | 架构说明、构建、开发统计 |
credentials 通道读取密钥并为回环一跳铸造同构 cookie，经评审补齐官方通道读取、轮换即时重铸、部署清单与双语文档后合入。npm test（覆盖 basePath 路由/重定向/转发、PWA 元数据放行、登录审计、审计日志轮转/清理、OTP 安全回归、client 契约、patch 端口推导）npm run deploy（语法检查 → 全量测试 → 同步到 DSH 安装目录 → 安装后验证）node scripts/e2e.mjs（Playwright，登录/2FA/改密全流程）./scripts/verify.sh（curl，401/302/WS 拒绝/锁定）None，本包是浏览器与内部 dsh webserver 之间的认证载体，不会进入任何模型请求。
None；本包既不组装也不发送 provider 请求。
MIT
3061| TOTP 参数（显示名、周期、位数、窗口） |
backupCodeCount / backupCodeLength | 10 / 8 | 备份代码数量与长度 |
updateCheck | false | 打开「认证设置 → 关于」时自动检查新版本。默认关闭：全新安装不发起任何对外请求。置 true 后在面板打开时自动查询一次公共 npm registry 的 latest（本插件唯一的对外请求，成功缓存 6h / 失败 15min，超时 3s，不含任何凭据）。无论此项如何，面板上的「检查更新」按钮都可手动发起一次检查 |