Commonguy25/authproof-sdk
GitHub: Commonguy25/authproof-sdk
AuthProof SDK 是一种面向 AI 智能体的密码学委托协议，通过签名的「委托收据」与不可篡改的操作日志填补用户与运营者间的信任空白，确保智能体行为完全符合用户意图且可审计。
Stars: 3 | Forks: 0
# AuthProof SDK
**一种面向智能体 AI 的密码学委托协议 —— 填补 IETF 框架遗留的用户与运营者之间的信任空白。**
## 问题所在
现有的每一个用于智能体身份的 IETF 框架——[AIP](https://identity.foundation/agent-identity-protocol/)、[draft-klrc-aiagent-auth](https://datatracker.ietf.org/)、[WIMSE](https://datatracker.ietf.org/wg/wimse/about/)——解决的均是服务与智能体之间的信任：即下游服务如何验证调用它的智能体是经过授权的。它们均未解决**用户与运营者之间的信任**。
当前智能体系统中的委托链如下：
```
User → Operator → Agent → Services
```
用户指令运营者。运营者指令智能体。但在委托发生的时刻，不存在用户原始意图的密码学记录。运营者因此成为受信任的第三方，拥有不受制约的权力，可以在指令到达智能体之前扩展、歪曲或省略用户的指令。
后果如下：
- 用户无法证明其授权了什么。
- 监管机构没有审计追踪记录。
- 法院没有证据链。
- 智能体无法区分合法的运营者指令与已被攻陷或恶意的指令。
AuthProof 填补了这一空白。
## 核心原语：委托收据
**委托收据**（Delegation Receipt）是一个已签名的授权对象，在任何智能体操作开始之前，它被锚定到去中心化仅追加日志中。它包含四个必填字段：
### 范围
允许操作的显式允许列表。未列出的操作均被默认拒绝。以结构化格式表示——而非自然语言。操作类别：
| 类别 | 描述 |
|---|---|
| `reads` | 对指定资源的读取访问 |
| `writes` | 对指定资源的写入访问 |
| `deletes` | 删除指定资源 |
| `executes` | 执行特定程序，通过其**静态能力签名哈希**引用 |
`executes` 是最危险的类别。它必须引用 Safescript 程序静态能力 DAG 的密码学哈希——而非名称、URI 或描述。哈希不匹配即意味着无法执行。
### 边界
显式禁止项，在任何情况下均不能被运营者指令覆盖。用户定义的硬性限制，在后续任何运营者指令下均保持有效。
### 时间窗口
授权的有效期。**日志时间戳**是时间预言机——而非客户端时钟。客户端时钟被明确排除在时间验证之外。
### 运营者指令哈希
委托时刻运营者声明的指令的密码学哈希。如果运营者随后向智能体发出不同指令，这种差异无需任何额外信任假设即可从日志中检测出来。
用户通过**使用设备安全飞地 的 WebAuthn/FIDO2** 用其私钥对此对象进行签名。签名在任何智能体操作之前发布到日志。随后的每一次智能体操作均引用收据哈希。超出范围的操作在密码学上是无效的。
## 信任栈架构
三个协议层消除了三个受信任的第三方：
### 第 1 层 — 签名能力清单 *(移除对注册表的信任)*
在当前的 MCP 生态系统中，不存在密码学证明能表明工具服务器的描述与其实际行为相符。运营者可以提交任意架构。
修复方案：工具服务器在任何用户授权发生之前发布一份**密码学签名的能力清单**。委托收据中的 `scope` 字段引用**此清单的哈希**——而非运营者自报的架构。服务器行为与清单之间的差异可在日志层被检测到。
### 第 2 层 — 委托收据 *(移除对运营者的信任)*
用户的原始意图在运营者指令到达智能体之前被不可变地记录。运营者的偏离是可证明的。
### 第 3 层 — Safescript 执行 *(移除对代码的信任)*
[Safescript](https://github.com/safescript) 是一种用于智能体 AI 执行的开源沙盒语言。其静态 DAG 结构意味着每个程序的完整能力签名均可在运行前计算得出——没有动态分发，没有运行时能力扩展。
`executes` 范围类别引用特定的 Safescript 能力签名哈希。如果运营者提供的程序与承诺的哈希不匹配，执行将被阻止。委托后无法用不同的程序替换智能体。
## 快速开始
```
import { AuthProof, Scope, KeyCustody } from 'authproof-sdk';
// Initialize with hardware-backed key custody (recommended)
const authproof = new AuthProof({
custody: KeyCustody.HARDWARE, // WebAuthn/FIDO2 via device secure enclave
log: 'https://log.authproof.dev',
});
// Define permitted operations — explicit allowlist, deny-by-default
const scope = new Scope()
.allow('reads', ['resource://calendar/events', 'resource://email/inbox'])
.allow('writes', ['resource://calendar/events'])
.deny('deletes', '*')
.execute('sha256:a3f1c9d8...', { program: 'scheduler-v1.sg' }); // Safescript hash
// Hard limits that survive any operator instruction
const boundaries = {
never: ['external-network', 'credential-store', 'payment-methods'],
};
// Issue the Delegation Receipt — anchored to log before any agent action
const receipt = await authproof.delegate({
scope,
boundaries,
window: { duration: '8h' }, // validated against log timestamp
operatorInstructions: instructionText, // hashed and committed
});
// receipt.id — unique receipt identifier
// receipt.hash — reference in every agent action
// receipt.log — append-only log anchor
// Agent-side: validate an action against the receipt
const check = await authproof.validate({
receiptHash: receipt.hash,
action: { class: 'writes', resource: 'resource://calendar/events' },
});
if (!check.authorized) {
// Out-of-scope action: surface a micro-receipt request to the user
const microReceipt = await authproof.requestMicroReceipt({
action: check.requestedAction,
parent: receipt.hash,
});
}
```
## 动态授权：微收据
对于未被原始委托收据覆盖的工具调用，智能体不能静默进行。协议规定：
1. 智能体识别出超出范围的能力需求。
2. 智能体向用户呈现一个**能力请求**，描述具体操作。
3. 用户签署一个**微收据**（micro-receipt），仅覆盖该操作。
4. 智能体继续进行，并引用微收据哈希。
未知操作需要新的明确用户授权。依赖解析遵循同样规则——依赖项会对照委托时承诺的依赖清单哈希进行检查。意外依赖属于范围违规。
## 并发智能体
每个委托事件均携带唯一的收据 ID。并发智能体各自引用其自己的收据哈希。它们通过收据区分，而非通过智能体身份。
## 密钥管理
| 模型 | 描述 | 推荐 |
|---|---|---|
| **硬件** | 通过设备安全飞地使用 WebAuthn/FIDO2。私钥永不离开硬件。 | **是 — 默认** |
| **委托** | 受信任的密钥管理器代表用户持有密钥。 | 不支持 FIDO2 的环境 |
| **自托管** | 用户自行持有并管理其私钥。 | 高级用户，气隙工作流 |
硬件托管是推荐的默认模式。私钥永不离开安全飞地；签名受设备生物识别或 PIN 保护。
## 操作日志
委托收据定义了 AI 智能体被授权执行的操作。**操作日志**记录了其实际执行的操作——并使任何偏离均可被立即验证。
智能体执行的每项操作都会生成一个已签名、带时间戳的条目，并链接到当前活动的收据。条目形成防篡改链：每个条目嵌入前一条目的 SHA-256 哈希，因此任何事后修改均可被检测到，无需依赖受信任的第三方。`diff()` 方法是审计原语——它将收据的授权范围与每条记录的操作进行比对，并返回任何偏差。
```
import AuthProof, { ActionLog } from 'authproof-sdk';
// 1. Issue a delegation receipt as normal
const { privateKey, publicJwk } = await AuthProof.generateKey();
const { receipt, receiptId } = await AuthProof.create({
scope: 'Search the web for competitor pricing. Read calendar events.',
boundaries: 'Do not send emails. Do not make purchases.',
instructions: 'Cite sources. Keep under 500 words.',
ttlHours: 4,
privateKey,
publicJwk,
});
// 2. Initialize the action log with the agent's signing key
const log = new ActionLog();
await log.init({ privateKey, publicJwk });
// Register the receipt so diff() knows what was authorized
log.registerReceipt(receiptId, receipt);
// 3. Record each action the agent takes
const e1 = await log.record(receiptId, {
operation: 'Search competitor pricing',
resource: 'web/search',
parameters: { query: 'rival.com pricing 2024' },
});
const e2 = await log.record(receiptId, {
operation: 'Read calendar events',
resource: 'calendar/events',
parameters: { range: 'this_week' },
});
// 4. Verify an individual entry (signature + chain integrity)
const check = await log.verify(e1.entryId);
// { valid: true, reason: 'Signature and chain integrity verified' }
// 5. Diff: authorized scope vs. everything that was done
const report = log.diff(receiptId);
// {
// clean: true,
// totalEntries: 2,
// compliant: [{ entry: {...}, reason: '"Search competitor pricing" matches authorized scope' }, ...],
// violations: [],
// }
// A scope violation surfaces immediately
await log.record(receiptId, { operation: 'Send email', resource: 'email/outbox' });
const auditReport = log.diff(receiptId);
// auditReport.violations[0].reason →
// '"Send email" outside authorized scope (0% scope match, 92% boundary overlap)'
```
### 操作日志 API
| 方法 | 描述 |
|---|---|
| `new ActionLog()` | 创建一个新的日志实例。状态保存在内存中。 |
| `log.init({ privateKey, publicJwk })` | 使用智能体的 ECDSA P-256 密钥初始化。在 `record()` 之前必须调用。 |
| `log.registerReceipt(receiptHash, receipt)` | 注册收据以进行范围比对。在 `diff()` 之前必须调用。 |
| `log.record(receiptHash, action)` | 追加一个已签名、链式链接的条目。返回已密封的条目。 |
| `log.verify(entryId)` | 验证单个条目的签名和链位置。返回 `{ valid, reason }`。 |
| `log.getEntries(receiptHash)` | 按时间顺序返回某个收据的所有条目。 |
| `log.diff(receiptHash)` | 将所有条目与收据范围进行比对。返回 `{ compliant, violations, clean }`。 |
### 生产环境警告
v1 中的时间戳使用客户端时钟。对于时间戳必须独立可验证的合规或法律场景，在生产环境部署前请替换为 RFC 3161 受信任时间戳权威机构。
### 重要提示
始终使用显式的 `allowedActions` 数组来定义范围。基于文本的范围匹配仅用于开发，不适用于生产环境或合规场景。
## 安装
```
npm install authproof-sdk
```
- npm: https://www.npmjs.com/package/authproof-sdk
- GitHub: https://github.com/Commonguy25/authproof-sdk
- 协议规范：[`WHITEPAPER.md`](WHITEPAPER.md)
标签：AI 代理, API安全, CVE, JSONLines, JSON输出, 不可篡改, 人工智能, 人工智能安全, 代码哈希, 加密协议, 区块链技术, 去中心化日志, 合规性, 后端开发, 委托凭证, 审计追踪, 密码学, 手动系统调用, 授权管理, 操作日志, 数字签名, 数据可视化, 智能体安全, 权限控制, 用户信任, 用户模式Hook绕过, 访问控制列表, 证据链, 运营者安全, 防篡改日志, 零信任, 静态能力