# dsh-credential-handoff

[English](README.md) | 中文

**状态：功能插件，已在 DeepSeek Harness 0.1.0-rc.6 上测试。**

`dsh-credential-handoff` 让 agent 向用户索要一个指定名称的凭据，而无须把秘密放进模型上下文。浏览器会弹出会话局部的密码对话框，把值写入 DSH 的凭据服务，最后只向工具调用返回固定的状态元数据。

## 问题

agent 能发现某个凭据缺失，但让用户把密钥粘进普通聊天，密钥就会落进对话记录和模型上下文。本插件为这个时刻提供一条只写的交接路径。

## 行为

`request_credential` 工具接受一个凭据引用（如 `TAVILY_API_KEY`）、可选的标签和原因。每个会话同一时刻只允许一个待处理的请求；对话框十分钟后过期。工具结果只报告该引用，以及它是新建的还是替换的。

HTTPS 下允许提交凭据；明文 HTTP 下只对精确的回环主机（`localhost`、`127.0.0.1` 和 IPv6 回环）放行。非回环的明文 HTTP 提交，界面控件和提交处理都会拦下。

## 非目标

本包不是保险库、加密提供者、凭据查看器，也不为子进程注入凭据，更不是 DSH 凭据 provider 的替代品。它无法保护被攻陷的浏览器、宿主进程或 DSH 凭据后端。

## 机制

- Host：注册 `request_credential`，等待一个带标签的 `userQuestions` 请求。
- Client：只处理这个带标签的问题，直接调用 `credentials.set`。
- 结果：用固定文本回答待处理的问题，返回不含值的元数据。

秘密不会出现在本插件产生的问题回答、工具结果、常规日志或会话事件负载里。

## 兼容性

已在 DeepSeek Harness `0.1.0-rc.6`、Node.js `^22.19.0 || >=24`、pnpm `>=10` 上测试。DSH 仍是发布候选版本，后续版本可能改动 question、credential 或 client-slot 的约定。

## 安装

```sh
dsh plugin --profile web add "github:xiaohj233/dsh-credential-handoff#v0.1.0"
```

安装后重启 Web profile。

## 配置

无需任何插件设置，模型直接调用：

```json
{"ref":"TAVILY_API_KEY","label":"Tavily API key","reason":"Required for Tavily search"}
```

凭据引用采用 shell 风格命名：以字母或下划线开头，后面跟字母、数字或下划线。

## 卸载

```sh
dsh plugin --profile web remove dsh-credential-handoff
```

移除插件会一并移除工具和对话框，但不会删除 DSH 凭据 provider 里已存好的凭据。

## 安全

不要把 DSH Web 控制面暴露给不可信网络。拦下明文非回环提交，只保证本插件不会经由这条通道把秘密发出去，并不会给 DSH 加上认证；配置的凭据 provider 自身的存储特性需要另行审查。

## 测试

```sh
npm test
npm run check:syntax
npm run scan:secrets -- synthetic-test-value lib/index.js lib/client.js test/validate.test.js
npm pack --dry-run
```

测试覆盖：引用校验、秘密形态处理、传输分类、问题/结果映射和包语法。

## 局限性与上游现状

DSH 已提供 `resolve`、`describe`、`set`、`unset` 凭据服务，本插件只是补了一个会话局部的交接 UI 和模型工具，不会把凭据值读回浏览器或模型。

rc.6 的通用问题 UI 总会提供一个 `Other` 文本答案；若客户端的接管 bundle 加载失败，回退问题会提醒用户不要粘贴秘密、直接取消，但宿主无法去掉那个通用字段。直接客户端也可以绕过本插件调用 DSH 自己的凭据 API；更广的 Web 控制面的传输与认证仍是上游的职责。

## License

MIT。详见 `LICENSE`。