### 六项顺序检查（在首次失败时停止）

| # | 检查项 | 阻塞条件 |
|---|-------|-------------|
| 1 | 收据签名 | ECDSA P-256 签名无效或收据被篡改 |
| 2 | 撤销 | 收据已通过 `RevocationRegistry` 撤销 |
| 3 | 时间窗口 | 收据已过期或尚未生效（日志时间戳预言机，非客户端时钟） |
| 4 | 作用域 | 操作不在 `ScopeSchema.allowedActions` 中或基于文本的作用域匹配失败 |
| 5 | 操作指令 | 当前指令与签发时锁定在收据中的哈希不匹配 |
| 6 | 程序哈希 | 提供的 `programHash` 与提交的 `executes` 哈希不匹配（防止代码替换） |

每个检查结果——通过或失败——都会自动记录到由验证者自己的密钥签名的不可变 `ActionLog` 中。

### 中间件集成

常见框架的即插即用封装器。每个封装器在包装的代码执行之前，通过 `PreExecutionVerifier` 对每次调用进行门控。

- **[LangChain](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/langchain.js)** — 包装任何具有 `invoke()` 方法的代理
- **[Express/HTTP](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/express.js)** — 适用于任何兼容 Express 的框架的请求中间件
- **[通用函数封装器](https://github.com/commonguy25/authproof-sdk/blob/HEAD/src/middleware/generic.js)** — 包装任何异步函数```js
// LangChain
import { authproofMiddleware } from 'authproof-sdk/middleware/langchain'
const guardedAgent = authproofMiddleware(agent, { receiptHash, verifier })

// Express
import { authproofMiddleware } from 'authproof-sdk/middleware/express'
app.use(authproofMiddleware({ verifier, getReceiptHash: (req) => req.headers['x-receipt-hash'] }))

// Any function
import { guardFunction } from 'authproof-sdk/middleware/generic'
const guardedExecute = guardFunction(executeAction, { receiptHash, verifier, action })

用户指示操作员。操作员指示代理。但在委托时刻，不存在用户原始意图的加密记录。操作员成为拥有不受制约权力的可信第三方，可以在指令到达代理之前对其进行扩展、扭曲或省略。

后果：

- 用户无法证明他们授权了什么。
- 监管者没有审计追踪。
- 法院没有证据链。
- 代理无法区分合法的操作员指令与受损害或恶意的操作员指令。

AuthProof 填补了这一空白。

---

## 核心原语：委托收据（Delegation Receipt）

**委托收据**是一个已签名的授权对象，在任何代理行为开始之前，它被锚定到去中心化的仅追加日志中。它包含四个必填字段：

### Scope

允许操作的显式白名单。未列出的一切默认被拒绝。以结构化格式表达——而非自然语言。操作类别：

| 类别 | 描述 |
|---|---|
| `reads` | 对指定资源的读取权限 |
| `writes` | 对指定资源的写入权限 |
| `deletes` | 删除指定资源 |
| `executes` | 执行特定程序，通过其**静态能力签名哈希**引用 |

`executes` 是最危险的类别。它必须引用 Safescript 程序静态能力 DAG 的加密哈希——而非名称、URI 或描述。哈希不匹配意味着不能执行。

### Boundaries

在任何情况下都不能被操作员指令覆盖的显式禁止项。由用户定义的硬性限制，在后续任何操作员指令中依然生效。

### Time Window

授权有效期。**日志时间戳**是时间神谕——而非客户端时钟。客户端时钟被明确排除在时间验证之外。

### Operator Instruction Hash

委托时操作员所述指令的加密哈希。如果操作员随后以不同方式指示代理，则差异可从日志中检测，无需任何额外的信任假设。

用户通过 **WebAuthn/FIDO2 使用设备安全飞地**，用其私钥签署此对象。签名在任何代理行为之前发布到日志中。每个后续代理行为都引用该收据的哈希。超出 scope 的行为在密码学上无效。

---

## 信任栈架构

三个协议层消除了三个可信第三方：

### 第 1 层——已签名的能力清单（*消除对注册中心的信任*）

在当前的 MCP 生态系统中，不存在密码学证明来确保工具服务器的描述与其实际行为一致。操作员可以呈现任意的模式。

修复方法：工具服务器在任何用户授权发生之前，发布**密码学签名的能力清单**。委托收据的 `scope` 字段引用该**清单的哈希**——而非操作员自报的模式。服务器行为与清单之间的偏差可在日志层检测到。

### 第 2 层——委托收据（*消除对操作员的信任*）

用户的原始意图在操作员指令到达代理之前被不可篡改地记录。操作员偏离是可证明的。

### 第 3 层——Safescript 执行（*消除对代码的信任*）

[Safescript](https://github.com/safescript) 是一个用于 AI 代理执行的开源沙盒语言。其静态 DAG 结构意味着每个程序的完整能力签名可在运行前计算——没有动态分发，没有运行时能力扩展。

`executes` scope 类别引用特定的 Safescript 能力签名哈希。如果操作员提供的程序不匹配已提交的哈希，则执行被阻止。委托后，代理不能替换为另一个程序。

---

## 快速开始

---```js
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,
  });
}

### 操作日志 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` 数组定义范围。基于文本的范围匹配仅适用于开发环境，不适合生产或合规场景。

---

## 机密部署

在硬件认证的可信执行环境（TEE）中运行 AuthProof 代理。`ConfidentialRuntime` 类将委托收据绑定到飞地度量，因此在执行前可以检测到模型权重、验证器代码或平台的任何替换。

### 硬件要求

- **Intel TDX** — Intel Ice Lake Xeon 或更新（第四代 Xeon Scalable）。Azure DCdsv3 系列，GCP C3 机密虚拟机。
- **AMD SEV-SNP** — AMD EPYC 第三代（Milan）或更新。Azure DCasv5 系列，带有 Nitro Enclaves 的 AWS m6a。

### 创建带有 TEE 度量绑定的收据```javascript
import { AuthProofClient } from 'authproof-sdk';

const client = new AuthProofClient();
const { receipt } = await client.delegate({
  scope: 'Summarize calendar events',
  operatorInstructions: 'Stay within scope.',
  expiresIn: '2h',
  privateKey,
  publicJwk,
  teeConfig: {
    platform:     'intel-tdx',
    verifierHash: verifierCodeHash,   // SHA-256 of your verifier binary
    modelHash:    modelWeightsHash,   // SHA-256 of model weights
  },
});
// receipt.teeMeasurement.expectedMrenclave is now bound to the receipt

Azure SKU 要求：`Standard_DC4ds_v3` 或更大规格的 DCdsv3 系列。启用机密操作系统磁盘加密。使用 Microsoft Azure Attestation (MAA) 共享终结点验证引用。

### 部署于 AWS Nitro Enclaves```javascript
const config = ConfidentialRuntime.awsNitroConfig({
  receiptHash,
  verifierHash,
  modelHash,
  region: 'us-east-1',
});
// config.instanceType === 'c6a.xlarge'
// config.enclaveOptions.enabled === true
// config.pcr0 is the combined receipt+verifier+model measurement

Apply with `kubectl apply -f` after serializing to YAML. The node selector `intel.feature.node.kubernetes.io/tdx: "true"` requires the Intel Device Plugin for Kubernetes.

### eBPF kernel module — help wanted

TEE 强制层在用户空间侧已经完成（`ConfidentialRuntime`、`TokenPreparer`）。最后一步强制措施——通过 eBPF LSM 钩子验证每个系统调用上的签名能力令牌——需要一个内核模块，该模块已开放供贡献。

特别欢迎具有 eBPF LSM 经验的工程师（Isovalent、Red Canary 或类似）。请在此处打开 issue 或 PR：https://github.com/Commonguy25/authproof-sdk/issues

---

## Examples

两个可运行的示例位于 `examples/` 目录中。

**[`examples/langchain-example.js`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/langchain-example.js)** — 展示了完整的 LangChain 集成路径：生成密钥对，颁发委托收据，初始化 `PreExecutionVerifier`，并使用 `authproofMiddleware` 包装任何代理，使得每个 `invoke()` 调用在代理运行时获得控制权之前被门控。包括一个可以立即运行的模拟代理以及真实 `AgentExecutor` 的精确代码模式。使用 `npm run example:langchain` 运行。

**[`examples/webauthn-example.html`](https://github.com/commonguy25/authproof-sdk/blob/HEAD/examples/webauthn-example.html)** — 一个自包含的三卡片浏览器演示，展示了完整的委托流程。卡片1允许您定义范围、边界和操作指令，然后使用本地密钥签署收据（替换为 `navigator.credentials` 以实现真正的 WebAuthn）。卡片2显示收据 ID、过期时间、系统提示和原始 JSON。卡片3允许您输入任何提议的操作并实时对照收据进行验证，显示每个检查结果。直接在浏览器中打开 — 无需构建步骤。

---

## Installation```bash
npm install authproof-sdk