kczx-user-management

本包是本地扩展版（1.0.0），已把 dsh-passwords 的账号 / 权限 / 配额 / 台账能力并入，不再是上游 0.9.5 的功能集。 上游同名包（npm 上的 @weibaohui/user-management）仅提供登录门禁与两步验证；本版额外提供工作区白名单与归属跟踪、 token 与时长配额、沙盒档位下限、上传 / git / 运维面门控、历史沙盒降级与隐藏字符清洗。 为便于从 registry 安装，本版以独立包名 kczx-user-management 发布，与上游互不覆盖。

给 dsh web 装一扇门：HTTPS 登录网关 + 账号管理 + 权限与配额执行 + 三本审计台账，一个插件完成。

安装

# 从 registry（发布之后；-w = pnpm 的 --workspace-root）
dsh plugin --profile web add kczx-user-management -w

# 从 tarball（离线 / 内网部署）
dsh plugin --profile web add ./kczx-user-management-1.0.0.tgz -w

# 或直接从目录 / 仓库（相对路径以你执行命令的目录为锚）
dsh plugin --profile web add link:E:\path\to\dsh-user-management -w
dsh plugin --profile web add github:you/dsh-user-management -w

# 装完重启 dsh web 生效

dsh plugin --profile <name> <args...> 就是在 ~/.dsh/profiles/<name> 里转发 pnpm <args...>；退出码 0 时按已安装状态 对账 dsh.profile.bundles——凡是声明了 dsh.bundle.patch 的依赖会自动进 layer 列表（本包含），所以不必手工改 bundles。

用 pnpm 直接安装

包内自带 dsh.bundle.patch，运行期依赖（@deepseek-ai/schemastery、bcryptjs、selfsigned）都在公共 registry 上，因此也可以当普通 npm 包装：

pnpm add kczx-user-management                      # 已发布到 registry 时
pnpm add ./kczx-user-management-1.0.0.tgz          # 从 tarball
pnpm add /abs/path/to/dsh-user-management          # 从目录

装进 dsh profile（把下面几行加进 ~/.dsh/profiles/web/package.json，再在该目录 pnpm install，然后重启 dsh web）：

{
  "dependencies": { "kczx-user-management": "file:./kczx-user-management-1.0.0.tgz" },
  "dsh": { "profile": { "bundles": ["kczx-user-management"] } }
}

本包不依赖安装期脚本：postinstall 已移除（pnpm ≥10 默认拦截依赖构建脚本，留着只会让安装以 ERR_PNPM_IGNORED_BUILDS 退出码 1 收场），ensure:deps 保留为手动脚本，仅供「内网无 registry 且以 link: 挂载」的场景，从宿主补齐 @deepseek-ai/schemastery：

pnpm add ./kczx-user-management-1.0.0.tgz        # 正常路径：依赖从 registry 装齐
node scripts/ensure-deps.mjs                     # 仅当上述解析不到 schemastery 时才需要

它做什么

一扇门

独立的 node:https 监听器（默认 0.0.0.0:19843），自签证书（SAN 覆盖本机全部 IP + sslip.io / nip.io 别名）， 未登录的页面访问跳转 /login、API 请求 401；登录页自带深浅色。设置页提供证书下载（PEM/DER）、指纹核对与 各系统导入向导。

账号与权限（管理员）

能力	说明
用户增删改查	新增 / 删除 / 角色调整 / 禁用启用 / 重置密码（一次性临时密码）/ 重置两步验证
工作区白名单	留空 = 允许全部；填写后只允许这些目录（Windows 路径折叠大小写，末尾斜杠自动忽略）
工作区归属跟踪	谁创建的工作区归谁：别人看不到、也不能删改；删除后释放，账号删除后清理
每小时 token 配额	由浏览器上报 dsh 自身的用量投影增量，服务端按小时窗口累计并拦截
每日时长配额	按真实活跃时间累计（不是请求数），限流不因轮询膨胀
沙盒档位下限	read-only / workspace-write / danger-full-access：AI 无法通过设置、slash 命令或审批把自己提权
上传 / git 开关	上传与「把数据带走」的通道分别控制（git RPC、会话导出、SSH 下载等）
策略封禁	与「禁用」不同：执行层每次请求都读，封禁即刻踢出会话

三本台账

台账	内容
登录记录	登录 / 失败 / 登出 / 改密 / 注册 / 角色变更 / 删号 / 权限变更（含紧凑差异串）
访问记录	页面级访问（保留真实客户端 IP）
操作日志	经过网关的每次 API 调用与 WebSocket 连接（方法 / 路径 / 状态 / 来源 IP）

另有 IP 封禁（回环与当前 IP 拒绝封禁，防自锁）与 TOTP 两步验证（默认关闭，可选开启）。

配置

走 ~/.dsh/settings.yaml 的 user-management: 段（改完要么热重载、要么重启）：

user-management:
  enabled: true
  listenHost: '0.0.0.0'   # 只本机可达就填 127.0.0.1
  port: 19843
  plaintext: false        # true 时只允许回环（明文服务观察层用，见 MERGED-DEPLOYMENT.md）
  sites: []               # 空 = 自动枚举本机 IP；配域名 + 证书则按 SNI 选择
  title: 'DSH 控制台'
  autoActivate: false     # false = 自助注册需管理员启用
  historyMaxBytes: 67108864   # 历史改写缓冲上限（字节，默认 64 MiB，最小 1 MiB）

数据文件

都在 $DSH_HOME/user-management/（默认 ~/.dsh/user-management/，0600，原子写）：

文件	内容
users.json	账号（scrypt 哈希；迁移进来的账号保留 bcrypt，首次登录成功后自动升级为 scrypt）
sessions.json	会话令牌（重启不掉线，7 天滑动过期）
activity.jsonl / audit.jsonl	登录与访问台账 / 操作日志（滚动保留最近若干条）
bans.json	IP 封禁
usage.json	按账号的当日活跃秒数与小时窗口 token（隔日自动清理）
workspaces.json	工作区归属（路径 → 账号）

从 dsh-passwords 迁移

账号、权限与配额可由 scripts/import-from-dsh-passwords.mjs 一次性导入（读取源库时复用 dsh-passwords 自己的模块， 因为它的用户名是 AES-GCM 密文 + HMAC 索引）：

node scripts/import-from-dsh-passwords.mjs --from E:\path\to\dsh-passwords --dry-run
node scripts/import-from-dsh-passwords.mjs --from E:\path\to\dsh-passwords
# 同名账号两边密码不同时，以源端为准（迁移期间通常正是你要的）
node scripts/import-from-dsh-passwords.mjs --from E:\path\to\dsh-passwords --overwrite-credentials

迁移是幂等的：重复运行只会更新权限，不会重复建号；默认不覆盖已有账号的密码。

测试

npm test          # 85 项：策略纯函数、store、API 层、以及真实网关的端到端用例
npm run check     # 全量语法检查

端到端用例会起真实网关（明文模式 + 假上游）验证：工作区过滤含 gzip、目录门与请求体重放、沙盒提权拦截与审批改写、 上传 / git / 运维面门控、历史降级与隐藏字符清洗、配额拦截、归属认领与释放。

卸载 / 回滚

dsh plugin --profile web remove kczx-user-management

数据文件不会被删除，重新装回即恢复。若在合并部署中回退到「观察层」形态，见 MERGED-DEPLOYMENT.md。

已知边界

• 执行只对本地存在的账号生效：签名身份 / 未知用户名按「不限制」处理，避免迁移期误锁人。
• 门只管走门的人：若另有插件把 dsh 宿主绑到 0.0.0.0（例如 dsh-lan-access），直连宿主端口即可绕过登录， 且绕过流量不会出现在任何一本台账里。要真正的强制约束，宿主端口必须保持回环。
• token 配额依赖客户端上报：浏览器侧被禁用或页面未加载时不计费（时长配额不受影响，它在服务端计时）。
• 会话历史要缓冲后才能改写：历史响应是一个 JSON 文档（长会话实测 9–16 MB），网关必须先缓冲才能做沙盒降级与隐藏字符 清洗，因此有 historyMaxBytes 上限（默认 64 MiB）。超过上限的会话会 fail-closed 返回 502，UI 显示「历史加载失败」—— 调大该值即可；1.0.0 之前用代理默认的 8 MiB，长会话必然踩中。
• 上游 @weibaohui/user-management（0.9.5）与本包 kczx-user-management 是两个不同的包，互不覆盖，pnpm update 不会把两者串在一起。

License

MIT（沿用上游许可）。