登录认证网关 lzyuan549/dsh-plugin-auth

dsh-plugin-auth

面向 dsh（DeepSeek Harness）Web UI 的企业级用户名/密码认证网关。

树外插件 —— 不改核心。装进 web 配置档后，每个页面、API 路由、/plugins 资源、WebSocket 升级都要求已登录会话。未认证的页面跳转会被重定向到自带的登录页；未认证的 API/XHR 调用返回 401。登录页使用简体中文（zh-CN），跟随操作系统的浅色/深色偏好，配色与控制尺寸和 dsh Web UI 一致；CLI 与 JSON API 输出保持兼容。

原生 Web UI 只带一道防 DNS 重绑定的「浏览器信任围栏」（isTrustedApiRequest），源码里明确写了它不是认证层。本插件补上缺失的这道门。

工作原理

插件的默认导出是 class AuthWebServer extends WebServer。一份 bundle 组合补丁（cordis.patch.yml）禁用原生 webserver 行，插入一行，从该子类重新提供 webServer 服务 —— 于是插件成为唯一提供者，所有消费者的注册都流经它：

- register / registerFallback / registerUpgrade 被重写，把每个 handler 包进认证门，再委托给 super.。一个卡点就覆盖了 SPA fallback、/api、/plugins、升级，以及之后新增的任何路由。
- 插件自己的 /__auth/ 接口（登录页、登录/登出、状态）在构造函数里用 super.register 注册，所以登出状态下它保持不受门控、可访问。
- 子类真正重新提供了 webServer（继承 super(ctx, 'webServer')），插入行保留 inject: [webStartup] 和 {host, port} 配置，因此下游的 web-runtime 和 connection 行仍能解析。

要求

- Node ^22.19 || >=24（与 dsh 一致）。
- 一份 dsh checkout/配置档，其中 peer 能解析：@deepseek-ai/cordis 和 @deepseek-ai/dsh-host-webserver。两者已在 web 配置档的依赖闭包里，配置档的模块回退（healProfilesModuleFallback）会把它们链接到插件旁边。
- 插件刻意不把这些声明为 peerDependencies。它继承 harness 自己的 WebServer（webServer 服务的提供者），必须与 harness 共用完全相同的 WebServer 和 cordis 模块实例。声明 "" peer 会让 pnpm 从 registry 拉取一份过时的已发布副本，装进插件的依赖闭包，并遮蔽配置档回退 —— 子类于是继承了错误的构建（更旧的那份提供 httpServer 而非 webServer，还绑定到不同的 cordis），启动就会失败，每个 web 消费者都「pending (waiting for service: webServer)」。不声明 peer，Node 的父级向上查找就能把它们解析到回退 —— 与加载器用的是同一批实例。

从 npm 安装

公开发布之后，推荐通过公共 npm 包安装。dsh 会把包规格转发给 pnpm，并自动把该包加入配置档层列表，因为这个包声明了 dsh.bundle。

根据 dsh 的安装方式选择对应命令：

- 已安装 dsh 命令行（dsh 可执行文件在 PATH 上）：用 dsh ...。
- 源码检出（本仓库）：在 harness 根目录下用 pnpm dsh ...。

install the exact release into the web profile (installed CLI)
dsh plugin --profile web add -w dsh-plugin-auth@0.1.3

from a deepseek-harness source checkout, run the equivalent command instead:
pnpm dsh plugin --profile web add -w dsh-plugin-auth@0.1.3

create the first admin before first boot (writes $DSH_HOME/auth/users.json)
dsh plugin --profile web exec dsh-auth add-user admin
pnpm dsh plugin --profile web exec dsh-auth add-user admin # source checkout

confirm the auth-webserver layer resolved and the stock webserver is disabled
dsh --profile web --dump-config
pnpm dsh --profile web --dump-config # source checkout

dsh-plugin-auth 故意不声明 peerDependencies：子类所需的 @deepseek-ai/cordis 和 @deepseek-ai/dsh-host-webserver 实例由 dsh 配置档提供。

从 tarball 安装

本地开发时，或者包在 registry 上不可用时，用 tarball。tarball 的 realpath 落在配置档目录树内，这样它的 peer 导入能通过配置档模块回退解析；而指向外部目录的 link: 会把 realpath 放到目录树外，导致解析失败：

from the plugin directory
npm pack # → dsh-plugin-auth-<version>.tgz

create the first admin BEFORE first boot (writes $DSH_HOME/auth/users.json)
node bin/dsh-auth.js add-user admin

install into the web profile.
-w is REQUIRED: a dsh profile is a pnpm workspace root (packages: - .), and
adding a dependency to a workspace root without -w fails ERR_PNPM_ADDING_TO_ROOT.
pnpm dsh plugin --profile web add -w ./dsh-plugin-auth-<version>.tgz

启动前检查（go / no-go）

启动服务器之前，先确认组合已解析、peer 导入可用：

dsh --profile web --dump-config

输出里必须出现 webserver 行，其 disabled: true，并且恰好插入一行 auth-webserver —— 不能有「module resolution failed」错误。这里解析失败会直接报错；先修好安装（用 tarball，不要用目录链接）再启动。

启动

pnpm dsh web # binds 127.0.0.1:3080 by default
pnpm dsh web --port 8080 # if 3080 is taken (e.g. a stale dsh still running)

打开 http://127.0.0.1:3080 → 会重定向到 /__auth/login。登录后就能进入应用；/api 和 /plugins 照常工作。

如果启动时报 EADDRINUSE ... 127.0.0.1:3080，说明另一个进程（通常是残留的 dsh web）上一次运行）已经占用了端口。把它停掉，或者换一个 --port 启动。这和下面的组合错误是两回事——它说明门禁确实激活了，并且尝试绑定端口。

命令行：dsh-auth

凭据存放在 $DSH_HOME/auth/users.json（原子写入，在支持 POSIX 权限位的地方使用 0600 模式），并且离线管理——绝不通过 Web 设置界面。密码从 TTY 读取，回显被屏蔽；非交互式配置时也可以从 bootstrap 环境变量读取。

dsh-auth add-user <username> Create a user (prompts for a password).
dsh-auth passwd <username> Change a user's password.
dsh-auth list List users (with disabled flag + last-updated).
dsh-auth remove <username> Delete a user.
dsh-auth disable <username> Disable a user (keeps the record; blocks login).
dsh-auth enable <username> Re-enable a disabled user.

环境变量：

- DSH_HOME —— 认证数据根目录（默认 ~/.dsh）；数据位于 $DSH_HOME/auth。
- DSH_AUTH_BOOTSTRAP_USER —— 非交互式 add-user 使用的用户名。
- DSH_AUTH_BOOTSTRAP_PASSWORD —— 非交互式 add-user / passwd 使用的密码。

密码至少 12 个字符，并且至少包含以下 4 类中的 3 类：小写字母、大写字母、数字、符号。

配置（$DSH_HOME/auth/config.json，可选）

所有键都是可选的；超出范围或类型错误的值会静默回退到安全默认值，所以格式错误的文件绝不会把门禁削弱到合理边界之外。

| 键 | 默认值 | 含义 |
| sessionAbsoluteTtlMs | 43200000（12h） | 会话硬性存活上限。 |
| sessionIdleTtlMs | 7200000（2h） | 滑动空闲窗口。 |
| sweepIntervalMs | 300000（5m） | 后台清理过期会话的周期。 |
| lockoutThreshold | 5 | 触发锁定前允许的连续失败次数（按用户名+IP）。 |
| lockoutBaseMs | 30000 | 首次锁定时长。 |
| lockoutMaxMs | 900000（15m） | 指数退避上限。 |
| lockoutWindowMs | 900000（15m） | 空闲多久后重置失败计数器。 |
| minPasswordLength | 12 | 密码最小长度（下限 8）。 |
| secure | false | 在 TLS 后面设为 true：设置 Secure + __Host- cookie，并强制 Path=/。 |
| sameSite | "Strict" | Cookie 的 SameSite（Strict 或 Lax）。 |
| cookiePath | "/" | Cookie 的 Path。 |
| trustedOrigins | [] | 会改变状态的 POST 额外接受的 Origin 值。 |
| scrypt | {N:16384,r:8,p:1,keylen:64,maxmem:64MiB} | 密码哈希开销。 |

在 TLS 反向代理后面，设置 "secure": true，这样会话 cookie 会带上 Secure 和 __Host- 前缀。在纯回环 HTTP 上，cookie 不能是 Secure（浏览器会丢弃它）。

安全说明

- 密码： scrypt，每个用户一个随机盐，开销参数自描述，常量时间比较。未知或已禁用的用户会拿一条固定的假记录来校验，所以不存在时序或枚举侧信道。
- 会话： 256 位随机 token，HttpOnly; SameSite=Strict; Path=/ cookie，绝对过期 + 滑动过期，登录时轮换 token（防固定），登出即吊销，后台清扫。
- 暴力破解： 按（用户名, IP）锁定，退避时间指数增长；合法用户换一个 IP 登录，不受攻击者失败次数影响。
- CSRF： 会改变状态的 POST 必须带同源 Origin/Referer（或命中 trustedOrigins 条目）；两者都缺失时默认拒绝。这是对 SameSite=Strict 的兜底。
- 开放重定向： 登录后的 next 目标会被裁剪成安全的单斜杠本地路径。
- 审计： 登录成功/失败/锁定/登出都会经 ctx.logger 记录，带上用户名 + IP（绝不记录密码）。

范围与取舍（有意为之）

- 只支持本地用户名/密码 —— 没有 SSO，没有 2FA。
- 会话存在内存里：dsh 一重启，所有人都得重新登录。
- 没有单独的 CSRF token —— 选定的防线是 SameSite=Strict + Origin 校验。
- src/paths.js 是自包含的（自己重新实现 $DSH_HOME → ~/.dsh 的解析，而不是导入 @deepseek-ai/dsh-home-paths）。这样离线命令行在模块路径上没有 harness 时也能工作，同时把那个包从运行时 peer 集合里去掉；运行时只导入 @deepseek-ai/dsh-host-webserver。

组合顺序注意事项

这个 bundle 会禁用自带的 webserver 行。任何更晚*的组合层（配置档自己的 cordis.patch.yml、$DSH_HOME/cordis.patch.yml，或 --patch）如果把 webserver 翻回 disabled: false，就会产生两个 webServer 服务商，启动会大声失败（服务重复），而不是静默失败。装了这个插件，就别再重新启用自带的那一行。

开发 / 测试

node --test

单元测试套件（policy、passwords、sessions、lockout、gate、login-page、users）是纯的，可以独立运行。tests/integration.test.js 需要运行时 peer（@deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver）；没装时它会带原因跳过。想通过 HTTP 跑真实的子类，就在构建好的 harness 检出里运行它。

许可证

MIT