dsh-keyring

Readme

# dsh-keyring

DeepSeek Harness（dsh）密钥保险库插件：**密钥自动脱敏、自动收纳、密码本设置页、跨重启持久**。
以官方 profile bundle（npm 包）形态安装，重启 `dsh web` 后自动加载，数据不丢。

## 功能

1. **密钥自动脱敏（进模型上下文前）**
   - 覆盖常见敏感项（规则参照 Hermes redact.py）：
     - 厂商前缀 token：`ghp_` / `github_pat_` / `gho_`、`sk-` / `sk-ant-`、`AIza`(Google)、`AKIA`(AWS)、`xox*` / `xapp-`(Slack)、`hf_`、`glpat-` 等 GitLab 全家桶、`npm_`、`pypi-`、Stripe / Telegram / JWT / 私钥块等。
     - 赋值形态：`KEY=value` 环境变量、YAML/JSON 字段（`password: …`、`"apiKey":"…"`）、`Authorization:` / `x-api-key:` 请求头。
     - 其它：DB 连接串密码、URL 裸 token、E.164 手机号（手机号只脱敏、不收纳）。
   - 遮罩规则：短 token（<18 字符）整段 `***`；长 token 保留头 6 尾 4。
   - 生效位置：**进入模型上下文的用户消息**（`agent/pre-step`）与**工具输出**（`tools/post-execute`）。
   - 命中即把原文**自动收纳进全局密码本**（可恢复），并在上下文中替换为遮罩引用。

2. **双层存储**
   - **全局**（`scope=global`）：跨会话、跨重启持久；存放于 dsh 凭据文件（`.credentials.yaml`，0600 权限）。
   - **会话级**（`scope=session`）：只存在于当前会话内，随会话结束自动消失；不写入全局。
   - 同一个值重复出现不重复存储；不同值各自独立成条。

3. **模型工具**
   - `keyring_store`（新增；同名再次保存即覆盖/编辑）
   - `keyring_get`（取回原文，供当前操作使用）
   - `keyring_list`（列出键名+元数据，不返回值）
   - `keyring_unset`（删除，可删全局或会话级条目）

4. **设置页「密码本」（UI）**
   - 入口：dsh「设置 → 密码本」。
   - 功能：列表展示全局条目；新增/编辑/删除；显示/隐藏原文；一键复制；生成随机强密码。
   - 样式：跟随 dsh 主题（使用官方 alias token，如 `--dsw-alias-*`），自动适配深浅色。
   - 文案：中英双语，跟随 dsh 语言设置。

## 边界（明确不做）

- 不做真加密存储：凭据落盘为文件权限保护（0600），非 AES 加密。
- 不做密钥的自动失效/轮换。
- Web URL 查询参数里的 token 默认不脱敏（合法 OAuth 回调场景，与 Hermes 一致）。
- 不自动清理会话级条目（随会话生命周期自然消失）。

## 安装

以官方 profile bundle 形态安装：

```sh
dsh plugin --profile web add dsh-keyring
# 或本地目录：
dsh plugin --profile web add ./dsh-keyring
# 或 tarball：
dsh plugin --profile web add ./dsh-keyring-0.1.0.tgz
```

装完重启 `dsh web` 即生效（自动加入 `dsh.profile.bundles`）。

> 若从 git 安装，需要 `prepare` 脚本 + `pnpm-workspace.yaml` 的 `allowBuilds`（见官方 publish.md）。

## 开发与验证

本插件在克隆的 `deepseek-harness` 仓库内作为 workspace 成员开发（复用仓库依赖），
以**独立 `DSH_HOME` + 独立端口**跑隔离测试环境，绝不触碰生产 `~/.dsh`。

```sh
# 构建 host + client
pnpm --filter dsh-keyring run build
# 或直接：
../../node_modules/.bin/tsc -p tsconfig.json
node scripts/build-client.mjs

# 一键验收（类型检查 + 37 项功能验证）
bash verify-all.sh

# 隔离环境安装（独立 DSH_HOME）
DSH_HOME=$PWD/test-home pnpm dsh plugin --profile web add ./plugin-dev/dsh-keyring

# 隔离环境启动
DSH_HOME=$PWD/test-home pnpm dsh --profile web --no-open --port 3091
```

## 结构

```
src/redact.ts    脱敏引擎（Hermes 规则移植 TS，输出命中列表 + 遮罩文本）
src/store.ts     KeyringStore 服务：全局凭据持久 + 会话内存
src/bridge.ts    脱敏桥：agent/pre-step + tools/post-execute + agent/disposed 清理
src/tools.ts     keyring_store/get/list/unset 模型工具
src/remote.ts    keyring Remote（host 侧，供设置页 CRUD）
src/config.ts    Schemastery 配置 schema
client/          浏览器半：设置页「密码本」UI（remote.ts 描述符 + index.tsx）
cordis.patch.yml bundle patch（id: keyring, name: dsh-keyring）
scripts/build-client.mjs  client bundle 构建（esbuild + __ModuleLoader__ 外壳）
```

## 参考

- 官方 bundle/profile 机制：[docs/user/develop/basic/publish.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)
- Hermes 脱敏规则：[NousResearch/hermes-agent/agent/redact.py](https://github.com/NousResearch/hermes-agent/blob/main/agent/redact.py)
- 参考实现：[re-ITRT/dsh-file-fix](https://github.com/re-ITRT/dsh-file-fix)