guhanfei-ai/dsh-human-intent

dsh-human-intent

面向 AI 智能体的人类意图验证与加密操作授权。

AI 可以提出一个操作。
只有人类才能授权它。

Agent proposes Action
↓
Canonicalize Action
↓
Hash Exact Intent
↓
Human sees exact Action
↓
Human verifies (WebAuthn: Touch ID / Windows Hello / passkey)
↓
Cryptographically sign Intent
↓
Generate Intent Receipt
↓
Verify exact Action binding
↓
Execute

为什么

AI 智能体越来越能够执行现实世界的操作：删除数据、部署服务、花钱、发送消息。一个智能体拥有运行某个工具的能力，并不意味着人类授予了运行它的权限。

Capability != Authority.

现有的人在回路机制通常验证的是一个模糊的事实——“有人触碰了传感器”——然后交给智能体一个笼统的 verified = true，往往在一段时间窗口内有效。没有任何东西把批准绑定到确切的操作上。为 rm -rf ./test-data 获得的批准会悄无声息地授权 rm -rf ./production-data。

dsh-human-intent 填补了这一空白。每一次授权都是：

- 绑定到确切操作——批准是针对精确的工具、目标和参数进行哈希和签名的；任何改动都会使其失效。
- 加密签名——WebAuthn（平台认证器、passkey 或安全密钥），并带有完整的服务端验证。
- 一次性——一次授权只授权一次执行。
- 会过期——请求和回执都带有较短的有效期窗口。
- 可审计——每一次状态转换都记录在本地仅追加日志中。

本项目不是指纹识别系统，也不识别特定的自然人。WebAuthn 平台认证器（Touch ID / Windows Hello / passkey）证明的是已注册凭据的持有者执行了用户验证手势。这一证明会被绑定到操作上。参见安全模型。

工作原理

1. 智能体（或 tools/pre-execute 策略钩子）提出一个 IntentRequest：工具、操作、目标、参数、风险、原因。
2. 该请求被规范化序列化（RFC 8785 JCS）并哈希：
intentHash = SHA-256(canonical intent)。
3. 人类打开批准页面，看到确切的操作。
4. 批准会触发一次 WebAuthn 仪式，其挑战就是 intentHash 本身——认证器对操作的字节进行签名。
5. 服务端完整验证断言（挑战、来源、RP ID、公钥签名、计数器、用户验证标志）并签发一个 IntentReceipt。
6. 在执行之前，回执会被消费：操作会被重新哈希并且必须匹配，签名会针对存储的凭据重新验证，并且会检查一次性消费标记。只有到这时，工具才会运行——恰好一次，且仅针对那一个操作。

快速开始

要求：Node.js ≥ 20.11。

npm installbash
npm run verify        # 构建 + lint + 测试 + http 冒烟测试
npm run demo          # 交互式验收场景 A–E

演示演练（你向人们展示的部分）：
bash
npm run demo

- 还没有通行密钥？浏览器会打开，你注册一个（macOS 上使用 Touch ID，
Windows 上使用 Windows Hello）。
- 选择一个场景；代理提出一条破坏性命令，浏览器
显示确切的操作，你批准或拒绝，终端打印
加密结果——包括被拒绝的篡改、重放和过期攻击。

单独运行审批服务器：
bash
npm run serve                       # http://localhost:8787
node bin/dsh-human-intent.js serve --port 9000 --data-dir ./data

检查收据（验证结构、完整性和签名）：
bash
node bin/dsh-human-intent.js inspect receipt.json

读取审计日志：
bash
node bin/dsh-human-intent.js audit

DSH 插件

在 DeepSeek Harness (DSH) 中，该插件提供：

- human_intent_request — 提出一个操作，等待人类，接收
一个 IntentReceipt（或明确的拒绝）。
- human_intent_verify — 在执行前验证收据授权了一个确切的操作。
- human_intent_status — 执行状态。
- 针对 protectedTools 的 tools/pre-execute 策略执行。
- 一个设置槽位和一个 Better Sidebar 审批面板（DSH
Web UI 中的 WebAuthn），以及 /human-intent/api 下的回环 API。
json
{
"protectedTools": ["shell.exec", "kubectl."],
"rules": [{ "tool": "shell.exec", "risk": "high" }]
}

Glob 语义：shell. 匹配一个点分段（shell.exec，而非
shell.exec.sub）；shell.* 跨分段。精确名称始终有效。

本地开发：
bash
npm install
npm run build:client
dsh plugin --profile web add link:/Users/you/dsh-human-intent

DSH 客户端 UI 必须从 localhost 提供服务，WebAuthn 才能
可用，并且 DSH 主机源必须列在 allowedOrigins 中。

配置

| 选项 | 默认值 | 含义 |
| --- | --- | --- |
| enabled | true | 对受保护工具强制执行人类意图。 |
| protectedTools | [] | 需要授权的工具名称 / 点 glob。 |
| rules | [] | 结合保护与风险级别的 { tool, risk } 规则。 |
| rpID | localhost | WebAuthn 依赖方 ID。 |
| allowedOrigins | http://localhost: | WebAuthn 源允许列表。 |
| requestTtlMs | 120000 | 人类决策窗口。 |
| dataDir | (memory) | credentials.json + audit.jsonl 的目录。 |

IntentRequest
ts
interface IntentRequest {
version: "0.1"
requestId: string          // 每个请求唯一
intentHash: string         // 对规范意图的 SHA-256
nonce: string              // 256 位不可猜测，每个请求一个
action: {
tool: string             // 例如 "shell.exec"
operation?: string
target?: string          // 例如 "namespace/prod/pod/foo"
arguments: object        // 确切参数
}
context?: {
description?: string
reason?: string
risk?: "low" | "medium" | "high" | "critical"
}
agent?: { id?: string; name?: string }
session?: { id?: string }
issuedAt: string           // ISO 8601
expiresAt: string          // ISO 8601
}

IntentReceipt
ts
interface IntentReceipt {
kind: "IntentReceipt"
version: "0.1"
requestId: string
intentHash: string          // 此回执所授权的操作
decision: "approved" | "denied"
intent: IntentRequest       // 内嵌，经过完整性校验
authenticator: { type: "webauthn"; credentialId: string }
verification: { method: "webauthn"; userVerified: boolean }
signedAt: string
expiresAt: string           // 与请求相同的有效期窗口
nonce: string
assertion?: { / 用于重新验证的原始 WebAuthn 断言 / }
deniedReason?: string
}

回执的序列化、验证与审计（docs/PROTOCOL.md）。

安全模型

本项目精确保证的内容：

1. 操作绑定。 批准 tool=A, args=X 会生成一个回执，该回执无法授权
tool=A, args=Y 或 tool=B, args=X。intentHash
覆盖工具、操作、目标、参数、nonce、requestId 以及
有效期窗口。
2. 签名覆盖范围。 WebAuthn 挑战值就是* intentHash，因此
认证器的签名覆盖了确切的操作字节。
3. 完整的服务端验证。 挑战值、来源允许列表、RP ID、
凭据公钥（COSE/ES256 或 RS256）、签名、签名
计数器（克隆检测）以及用户验证标志均
使用 @simplewebauthn/server 进行验证。绝不信任客户端提供的
verified: true。
4. 一次性消费。 已消费的回执在重用时会被拒绝——在
内存中如此，当配置了数据目录时，跨重启也通过
审计日志实现。
5. 过期。 请求和回执共享一个短暂的窗口；超过该窗口后，只有
全新的人工授权才有效。
6. 显式拒绝。 拒绝是一等结果，代理可以读取。

本项目不声称的内容：

- 它不识别设备上注册的是哪个自然人。
WebAuthn 证明的是某个已注册凭据持有者通过了验证——完整模型见
docs/THREAT_MODEL.md。
- 如果参数是诚实的，它无法阻止人类批准一个具有误导性的原因字符串；
UI 显示原始参数和哈希值，而不仅仅是摘要。
- 本地审计日志是仅追加的 JSONL；面对主机被攻陷，它并非防篡改
（未来工作：签名日志）。

架构

Agent
↓ IntentRequest
Canonicalizer (RFC 8785 JCS)
↓ CanonicalIntent
Hasher (SHA-256)
↓ IntentHash
Human Intent UI (exact action, risk, arguments, expiry)
↓ WebAuthn ceremony (challenge = intentHash)
Verifier (@simplewebauthn/server: origin, RP, key, signature, counter, UV)
↓ IntentReceipt
Policy / Consumption Gate (action re-hash, one-shot, expiry)
↓
Tool Execution (exactly the authorized action)

详情：docs/ARCHITECTURE.md ·
协议：docs/PROTOCOL.md ·
威胁：docs/THREAT_MODEL.md

演示

npm run demo 运行五个验收场景：

| 场景 | 演示内容 |
| --- | --- |
| A | 破坏性命令 → 人工批准 → 精确操作执行一次。 |
| B | 人工批准 ./test-data；代理替换为 ./production-data → 被拒绝（action_mismatch）。 |
| C | 已批准的凭据被第二次重放 → 被拒绝（already_consumed）。 |
| D | 请求窗口过期 → 已过期，不执行任何操作。 |
| E | 人工按下拒绝 → 代理收到明确的 denied 决定。 |

从 dsh-fingerprint-signature 迁移

dsh-human-intent 由 dsh-fingerprint-signature 演化而来，后者将受保护的工具
置于平台用户验证弹窗之后，并授予 30 秒的一揽子通行权限。该设计验证了人类在场，
但未验证人类批准的是哪个操作。

本项目保留了在那里行之有效的插件结构和回环 API 模式，
并替换了安全模型：

| | dsh-fingerprint-signature | dsh-human-intent |
| --- | --- | --- |
| 验证的事实 | “有人在场” | “有人授权了这个精确操作” |
| 绑定 | 无（一揽子授权） | intentHash（工具 + 目标 + 参数） |
| 证明 | 辅助程序退出码 | WebAuthn 签名（服务器验证） |
| 有效期 | 30 秒窗口 | 一次性，受请求窗口限制 |
| 拒绝 | 仅超时 | 明确的拒绝凭据 |
| 审计 | 无 | 仅追加的审计日志 |

签名变量功能（名称、身份 ID、注入代理上下文的自定义变量）未迁移：
它属于不同的用例。请继续使用 dsh-fingerprint-signature 实现该功能；
两个插件可以并排安装。

参见 docs/MIGRATION.md。

路线图

- v0.1 — WebAuthn 人类意图、精确操作绑定、意图凭据、
受保护工具、审计日志、DSH 插件、CLI + 演示。
- v0.2 — 通行密钥同步/硬件密钥配置文件、更丰富的策略规则、MCP
适配器。
- v0.3 — 多方批准、组织策略、远程批准、
凭据透明度。
- 未来 — 跨代理人类意图协议、SDK、浏览器和
基础设施集成。

限制

- v0.1 将凭据存储在本地 JSON 文件中；目前尚无按用户
账户模型或加密密钥库。
- DSH 客户端批准面板需要由 localhost 提供服务的 UI 以及
支持 WebAuthn 的浏览器。
- 单主机强制执行：凭据在签发它们的主机上被消费
（没有分布式消费账本）。
- 测试使用带有真实 EC P-256 密钥的软件认证器；物理
认证器行为（常驻密钥、混合传输）在
演示中演练，而非在测试套件中。

许可证

MIT — 参见 LICENSE。