kczx-user-management 1.0.0

package/CUTOVER-RUNBOOK.md

@@ -0,0 +1,73 @@
+# Cutover runbook: retiring dsh-passwords
+
+Everything below is reversible. Read the whole page before starting; the switch
+takes a few minutes and the rollback takes one command.
+
+## What is already true
+
+- Accounts, permissions, quotas, upload/git switches and admin CRUD live in
+  `kczx-user-management` (see MERGED-DEPLOYMENT.md for how the two plugins
+  currently cooperate).
+- The enforcement layer (workspace scope, folder gate, sandbox floor, upload/git
+  and ops-surface gates, session-history clamp, hidden-Unicode strip, token and
+  duration quotas) is implemented here and covered by the test suite.
+- This plugin's own login door still works: the dry run
+  (`C:\Users\95232\mxz\um-ui\door-dryrun.mjs`) exercises TLS, the login page,
+  sessions, role scoping, an imported bcrypt account signing in, and the gates
+  behind the door — 13/13.
+
+## Decisions that must be made first
+
+1. **Password collision on `mxz`.** The account exists in BOTH stores with
+   different password hashes. If the door moves without deciding this, sign-in
+   needs the OLD user-management password, not the one used today.
+   - keep today's password: `node scripts/import-from-dsh-passwords.mjs --from E:\code\dsh\dsh-passwords --overwrite-credentials`
+   - or reset it afterwards from the accounts page as an admin.
+2. **Which dsh-passwords capabilities must survive.** Not yet answered: automatic
+   HTTPS (ACME), encrypted audit storage, user-to-user chat, dsh auto-update,
+   login/IP throttling, workspace ownership tracking. Anything not named here is
+   dropped when the plugin is removed.
+
+## The switch
+
+```powershell
+# 0. stop the door that is being retired
+#    (dsh-passwords' gateway is a child of dsh; stopping dsh web stops it too)
+
+# 1. turn this plugin back into the door:
+#    ~/.dsh/settings.yaml
+#    user-management:
+#      listenHost: '0.0.0.0'    # was 127.0.0.1 (observer mode)
+#      plaintext: false         # was true: the door terminates TLS again
+#      port: 19843
+#      trustedSecret: ''        # no signing gateway in front of it any more
+
+# 2. remove dsh-passwords from the profile
+dsh plugin --profile web remove dsh-passwords
+
+# 3. restart dsh web
+```
+
+## Verification after the switch
+
+1. `https://<host>:19843/login` renders, a wrong password is refused, a correct
+   one lands on the SPA.
+2. The settings page shows 用户管理 with the accounts that were migrated
+   (`mxz`, `mxz1`) and their permissions intact.
+3. As a restricted account: the workspace list is filtered, a session outside the
+   allow-list is refused, an upload or git action is refused, and the history of a
+   shared session does not raise the sandbox.
+4. `~/.dsh/user-management/` still grows: `activity.jsonl` on sign-in, `audit.jsonl`
+   on API calls, `usage.json` on reported tokens.
+
+## Rollback
+
+```powershell
+# restore the observer arrangement
+dsh plugin --profile web add link:E:\code\dsh\dsh-passwords
+#   settings.yaml: listenHost 127.0.0.1, plaintext true, trustedSecret <the 64-hex key>
+# restart dsh web
+```
+
+The dsh-passwords checkout, its SQLite database and its `.env` are never touched
+by any of this, so its accounts and audit log remain intact either way.

package/MERGED-DEPLOYMENT.md

@@ -0,0 +1,100 @@
+# （历史）合并部署：user-management 作为回环台账观察层
+
+> **已失效，仅作存档**：这份文件描述 dsh-passwords 与本插件并存的「观察层」形态。
+> 该插件已于 1.0.0 退役，当前部署形态见 README。下文保留是为了说明当时的信任模型与接线方式。
+
+本文件只描述**合并部署**——即 dsh-passwords 与 user-management 同机运行、由前者
+独占登录时，本插件的外部契约与接线方式。独立部署（本插件自己当登录门）的行为
+没有任何变化；不配置 `trustedSecret` 时，本文件描述的一切都是惰性的。
+
+## 架构
+
+```
+浏览器
+  │  http://<host>:8080        ← 唯一登录门（dsh-passwords，账号/权限/配额/审计）
+  ▼
+dsh-passwords 网关（独立子进程）
+  │  转发时注入签名身份头；入站同名头一律剥除（防伪造）
+  ▼
+user-management 网关（127.0.0.1 明文，只信签名）
+  │  三本台账在这里记录：访问记录 / 操作日志（登录记录由门回传）
+  ▼
+dsh 宿主 127.0.0.1:3080
+```
+
+为什么观察层必须留在链路里：三本台账全部由**本插件的网关钩子**写入
+（`onAccess` / `onApiRequest` / `onWsOpen`）。摘掉它的网关，台账立刻变空。
+所以它不是"被替代"，而是"退居为纯观察层"。
+
+## 信任模型
+
+`src/trusted-identity.js` 是唯一的信任入口，三个条件必须同时成立：
+
+1. **对端是回环**（默认 `127.0.0.1` / `::1` / `::ffff:127.0.0.1`）——监听器本身
+   只绑 127.0.0.1，所以只有同机的登录门能到达；
+2. **时间戳在 ±60 秒窗口内**——防重放；
+3. **HMAC-SHA256(secret, "username\nrole\nip\nts") 恒定时间比对通过**。
+
+签名覆盖 **role 和客户端 IP**：篡改角色提权、或篡改台账里的来源 IP，都会验签失败。
+
+## 配置
+
+```yaml
+user-management:
+  enabled: true
+  listenHost: '127.0.0.1'   # 明文模式会强制为回环，配别的会被拒绝并告警
+  port: 19843
+  plaintext: true           # 明文监听：登录门的 WS 升级走裸 TCP 隧道，无法对这一跳做 TLS
+  trustedSecret: '<64 hex>' # 与 dsh-passwords 的 MCP_IDENTITY_SECRET 必须逐字一致
+  # trustedPeers: []        # 默认即回环；仅在确有需要时覆盖
+```
+
+对端（dsh-passwords）需要：
+
+```
+MCP_IDENTITY_SECRET=<同一个 64 hex>     # 专用密钥，不复用 MCP_INTERNAL_SECRET
+MCP_GATEWAY_UPSTREAM=http://127.0.0.1:19843
+```
+
+两端密钥不一致是**静默失败**——观察层会拒绝全部请求，台账停止增长而没有任何报错。
+所以验证脚本把"两侧密钥一致"作为第一条断言。
+
+## 登录记录如何续上
+
+登录发生在门那一侧，观察层看不到 `login` 事件。门在登录成功 / 失败 / 登出时，
+把事件签名后 POST 到：
+
+```
+POST /user-management/api/internal/session-event
+{ "type": "login" | "login_failed" | "logout", "detail": "..." }
+```
+
+该路径列在 `PUBLIC_PATHS` 里（浏览器会话检查对它不适用），凭据就是签名头本身：
+没有有效签名一律 401。通知是 fire-and-forget——观察层不在时得到 404，静默忽略，
+**绝不影响登录本身**。
+
+## 客户端表现（observer 模式）
+
+`/user-management/api/session` 会带上 `observer: true`，客户端据此：
+
+- 页签只留 登录记录 / 访问记录 / 操作日志（账号表、IP 封禁、证书、2FA 属于"门"，隐藏）；
+- 去掉登出与改密入口（那属于门的职责，在这里点了没有意义）；
+- 直连 dsh 端口打开时（台账 API 在该端口是 404），提示改走网关地址，而不是
+  误导性的"会话已过期，请重新登录"。
+
+## 验证
+
+```bash
+node --test test/trusted-identity.test.mjs     # 信任条件单测
+node dist/verify-merge.mjs                     # 端到端：密钥一致性、签名放行、
+                                               # 篡改拒绝、台账归属与真实 IP
+```
+
+## 已知边界
+
+- **直连 dsh 端口可绕过整扇门**。本插件与门都无法阻止：谁能访问宿主端口，谁就
+  不需要登录。dsh-passwords 的设计前提是"dsh web 只监听 loopback"；若另有插件把
+  宿主绑到 0.0.0.0（例如 dsh-lan-access），门的约束力就只剩"愿意走门的人"。
+  此时台账仍只记录走门的流量，**绕过者的行为不会出现在任何一本账里**。
+- 观察层看到的 socket 对端恒为 127.0.0.1，真实来源 IP 来自签名头；因此
+  "IP 封禁"在合并部署下按真实 IP 生效，但只在门的链路上。

package/README.md

@@ -0,0 +1,158 @@
+# kczx-user-management
+
+> **本包是本地扩展版（1.0.0），已把 dsh-passwords 的账号 / 权限 / 配额 / 台账能力并入，不再是上游 0.9.5 的功能集。**
+> 上游同名包（npm 上的 `@weibaohui/user-management`）仅提供登录门禁与两步验证；本版额外提供工作区白名单与归属跟踪、
+> token 与时长配额、沙盒档位下限、上传 / git / 运维面门控、历史沙盒降级与隐藏字符清洗。
+> 为便于从 registry 安装，本版以独立包名 **`kczx-user-management`** 发布，与上游互不覆盖。
+
+给 dsh web 装一扇门：**HTTPS 登录网关 + 账号管理 + 权限与配额执行 + 三本审计台账**，一个插件完成。
+
+## 安装
+
+```bash
+# 从 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 包装：
+
+```bash
+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`）：
+
+```json
+{
+  "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`：
+
+```bash
+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:` 段（改完要么热重载、要么重启）：
+
+```yaml
+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 = 自助注册需管理员启用
+```
+
+## 数据文件
+
+都在 `$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 索引）：
+
+```bash
+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
+```
+
+迁移是幂等的：重复运行只会更新权限，不会重复建号；**默认不覆盖已有账号的密码**。
+
+## 测试
+
+```bash
+npm test          # 83 项：策略纯函数、store、API 层、以及真实网关的端到端用例
+npm run check     # 全量语法检查
+```
+
+端到端用例会起真实网关（明文模式 + 假上游）验证：工作区过滤含 gzip、目录门与请求体重放、沙盒提权拦截与审批改写、
+上传 / git / 运维面门控、历史降级与隐藏字符清洗、配额拦截、归属认领与释放。
+
+## 卸载 / 回滚
+
+```bash
+dsh plugin --profile web remove kczx-user-management
+```
+
+数据文件不会被删除，重新装回即恢复。若在合并部署中回退到「观察层」形态，见 `MERGED-DEPLOYMENT.md`。
+
+## 已知边界
+
+- **执行只对本地存在的账号生效**：签名身份 / 未知用户名按「不限制」处理，避免迁移期误锁人。
+- **门只管走门的人**：若另有插件把 dsh 宿主绑到 `0.0.0.0`（例如 dsh-lan-access），直连宿主端口即可绕过登录，
+  且**绕过流量不会出现在任何一本台账里**。要真正的强制约束，宿主端口必须保持回环。
+- **token 配额依赖客户端上报**：浏览器侧被禁用或页面未加载时不计费（时长配额不受影响，它在服务端计时）。
+- 上游 `@weibaohui/user-management`（0.9.5）与本包 `kczx-user-management`（1.0.0）是两个不同的包，互不覆盖，`pnpm update` 不会把两者串在一起。
+
+## License
+
+MIT（沿用上游许可）。