keelapi/keel-permit
GitHub: keelapi/keel-permit
该项目定义了一种面向 AI Agent 执行前决策授权的标准化记录格式和离线验证证据规范，用于证明 AI 操作在被执行前已获得授权。
Stars: 4 | Forks: 0
# Permit 规范
[](LICENSE)
[](https://github.com/keelapi/keel-permit/releases)
一种用于 AI agent 系统的执行前决策记录。Permit 记录了某个操作已被评估和决定，并且对于已分发的允许执行，可以将其绑定到最终的 provider 或工具请求。仅凭 Permit JSON 对象本身无法进行自我认证；验证是通过已签名的导出产物以及相关的公钥或密钥清单执行的。当验证者拥有已签名的导出产物和相关的公钥/密钥清单时，无需联系颁发者即可对这些产物进行验证。
本代码库包含 **Permit v1** 的传输格式规范、JSON schema 和验证规则。
## 状态
| | |
|---|---|
| 规范文档版本 | 1.7.0 |
| Permit 传输格式 | `v1` |
| Permit 绑定版本 | `v1`-`v7`（`v6` 已冻结；`v7` 为附加/c7） |
| Closure record 格式 | `closure_v1`, `closure_v2` |
| Chain entry 哈希格式 | `v1` |
| 参考实现 | [keel-api](https://github.com/keelapi/keel-api) |
| 参考验证器 | [keel-verifier](https://github.com/keelapi/keel-verifier) (`pip install keel-verifier`) |
## 存在原因
AI agent 的行动速度日益超出人类逐步审查的能力。Permit 为系统提供了一种标准方式，用于记录在执行前授权了什么，并随后通过已签名、可离线验证的证据来证明它。
```
flowchart LR
Agent["Agent"] --> Policy["Policy evaluation"]
Policy --> Permit["Permit issued"]
Permit --> Dispatch["Dispatch"]
Dispatch --> Closure["Closure record"]
Closure --> Export["Signed export bundle"]
Export --> Verifier["Offline verifier"]
```
## 本规范的内容
- **Permit 对象** —— 字段、类型、生命周期、决策形态。
- **Closure record** —— 将 permit 链接到其执行结果的已签名产物（`closure_v1`, `closure_v2`）。
- **Chain entry** —— 当条目通过已签名的 bundle 或锚定检查点传递时，用于防篡改链的 record-hash 算法和连续性规则。
- **Audit export bundle** —— 用于可离线验证的 evidence pack 的文件格式和清单。
- **规范化 (Canonicalization)** —— 用于哈希计算的 JSON 规范化规则。
- **失败代码** —— 当完整性验证失败时，验证器发出的标准分类体系。
## 本规范不包含的内容
- 策略语言或评估引擎。Permit 证明决策；如何达成决策由具体实现决定。
- runtime、网关或代理。Permit 可以由任何希望生成它们的系统发出。
- 身份或 RBAC 模型。Subject 和 identity 字段是开放式的。
- 实时的 runtime API 封装、网络协议、传输或检索 API。Permit v1 指定了 audit-export 产物和证据语义。
- 存储、索引或查询语义。
## 规范
- [`spec/permit-v1.md`](spec/permit-v1.md) — Permit 对象
- [`spec/permit-v2.md`](spec/permit-v2.md) — Permit v2 多方签名槽
- [`spec/permit-co-signature-v1.md`](spec/permit-co-signature-v1.md) — WebAuthn 人工联签声明及策略/密钥契约
- [`spec/closure-v2.md`](spec/closure-v2.md) — 执行 closure record
- [`spec/chain-entry.md`](spec/chain-entry.md) — 防篡改 chain entry
- [`spec/audit-export-bundle.md`](spec/audit-export-bundle.md) — Evidence bundle 格式
- [`spec/canonical-json.md`](spec/canonical-json.md) — 规范化规则
- [`spec/failure-codes.md`](spec/failure-codes.md) — 验证失败分类体系
- [`spec/permit-chain-v1.md`](spec/permit-chain-v1.md) — 委托 Permit Chain 语义
- [`spec/verifier-claims-v0.md`](spec/verifier-claims-v0.md) — 验证器声明模型
- [`spec/verifier-pack-pinning-v0.md`](spec/verifier-pack-pinning-v0.md) — evidence pack 的固定语义
- [`spec/permit-revoked-event-v1.md`](spec/permit-revoked-event-v1.md) — 已签名的 permit 撤销事件
- [`spec/key-status-event-v1.md`](spec/key-status-event-v1.md) — 已签名的密钥状态事件
- [`spec/key-status-manifest-v1.md`](spec/key-status-manifest-v1.md) — 已签名的账户密钥状态清单
- [`spec/key-status-completeness-v1.md`](spec/key-status-completeness-v1.md) — 密钥状态完整性验证器声明
- [`spec/dispatch-absence-after-revocation-v1.md`](spec/dispatch-absence-after-revocation-v1.md) — 撤销后范围忠诚的缺失裁决
## Schema
[`schemas/`](schemas/) 中的大多数 JSON Schema (Draft 2020-12) 文件是根据参考实现的 Pydantic 模型生成的，然后使用公共传输格式约束进行后处理。使用 [`tools/export_schemas.py`](tools/export_schemas.py) 重新生成。`schemas/closure-v2.schema.json`、`schemas/audit-export-manifest.schema.json` 以及四个 WebAuthn 联签契约 schema 是手动维护的，因为它们定义的是代码库原生的协议封装，而不是生成的参考实现模型。
## 已发布产物
- [`claim_registry/`](claim_registry/) — 稳定的验证器声明注册表产物。
- [`comparator_registry/`](comparator_registry/) — 用于 Permit Chain 的权限封装比较器语义。
- [`semantics/`](semantics/) — 验证器为导出清单、治理链、closure record、检查点、工作流、Permit 绑定和 R4 预算账本声明所使用的固定语义产物。
## 能力清单
| 能力 | 公共契约 |
|---|---|
| Permit 绑定规范化 | `v1`-`v4` 使用传统的 Keel 配置；`v5`-`v7` 使用 RFC 8785 / JCS。 |
| 冻结的 v6 边界 | `v6` 保持字节级稳定，并保留其确切的 resource-attributes 契约。 |
| 附加的 v7/c7 绑定 | `v7` 对 v6 字段集加上 `authority_chain_digest`、`quota_reservation_id`、`subject_id`、`subject_type`、`account_id` 和 `org_id` 进行签名。 |
| Permit v2 槽密钥查找 | 对于 `v7` 及更高版本，账户和注册表分区选择来自已签名的 permit 字节；未签名的清单覆盖将被拒绝。 |
| R4 账本声明 | `quota.reservation_linkage.v1` 和 `budget.partition_ledger.v1` 定义了预算分配账本证据；未签名的配额链接分级依赖于锚点。 |
| Permit 联签契约 | `permit.co_signature.v1` 验证由 challenge 绑定到 Permit 规范哈希的 WebAuthn ES256 或 EdDSA 断言；保证和身份强制执行仍默认关闭。 |
| 参考验证器状态 | 参考验证器验证 `v7` permit 决策，并拒绝未签名的账户选择器漂移。 |
## 示例
[`examples/`](examples/) 中的参考产物 —— 符合 schema 的说明性 permit、closure record、chain entry 和说明性的 audit export bundle。除非示例被明确标记为可加密验证的参考 bundle，否则哈希、签名和密钥标识符均为占位符。
## 控制框架映射
[`mappings/control-frameworks.schema-mapping.json`](mappings/control-frameworks.schema-mapping.json) — 从 Permit v1 传输格式字段和 audit-export-bundle 产物到 14 个框架（CCPA §1798.105、CPPA ADMT 法规、欧盟 AI 法案、GDPR、AICPA SOC 2、NIST AI RMF、ISO/IEC 42001:2023、OWASP LLM Top 10 2025、MITRE ATLAS、OWASP API 安全 Top 10 2023、OWASP ASVS v5.0.0、FedRAMP / NIST SP 800-53 Rev 5、CIS Controls v8.1、PCI DSS v4.0.1）中特定控制 ID 的机器可读映射。
有关状态、范围、证据支持免责声明、schema 结构，以及记录 Keel 未涉及的控制项的明确非映射，请参阅 [`mappings/README.md`](mappings/README.md)。
## 一致性测试向量
[`test-vectors/`](test-vectors/) — 一组带有版本号的一致性测试夹具集，任何验证器（Keel 的参考验证器或独立的第三方实现）都可以对其进行测试。每个夹具都有一个定义所需结果的 `expected.json`；如果在任何夹具上存在分歧，则该验证器不符合要求。
当前的一致性产物包括 [`test-vectors/verifier_claims/`](test-vectors/verifier_claims/) 中的固定语义黄金语料库、[`test-vectors/semantics/`](test-vectors/semantics/) 中的语义产物一致性记录，以及位于 [`test-vectors/vectors/cat-08-permit-chains/`](test-vectors/vectors/cat-08-permit-chains/) 下的独立 Permit Chain 语义向量。请参阅 [`test-vectors/README.md`](test-vectors/README.md) 和 [`test-vectors/CONFORMANCE.md`](test-vectors/CONFORMANCE.md)。
WebAuthn 联签协议语料库及其无依赖的可执行参考验证器位于 [`test-vectors/permit_co_signature/v1/`](test-vectors/permit_co_signature/v1/) 下。
## 版本控制
三个正交的版本维度：
- **Permit 传输格式** (`v1`)：Permit 对象的线上传输结构。提升此版本将是一项破坏性变更。
- **Closure record 格式** (`closure_v1`, `closure_v2`)：用于执行 closure 的已签名封装。会新增格式；旧格式无限期保持有效。
- **Chain entry 哈希格式** (`v1`)：传递给 SHA-256 以生成 record hash 的输入字符串布局。提升此版本将是一项破坏性变更。
本**规范文档**使用与传输格式独立的 semver — 1.0.0 → 1.1.0 规范发布可能会澄清规范语言，而不会更改任何字节级别的格式。
## 一致性
当且仅当满足以下条件时，Permit 发射器才符合本规范：
1. 每个发出的 Permit 对象都能通过 `schemas/permit-v1.schema.json` 验证。
2. 以 `closure_v2` 形式发出的每个 closure record 都能通过 `schemas/closure-v2.schema.json` 验证，并满足 [`spec/closure-v2.md`](spec/closure-v2.md) §3 中的摘要存在矩阵。
3. 每个 chain entry 都符合 [`spec/chain-entry.md`](spec/chain-entry.md) 中的 record-hash 算法。
4. 每个 audit export bundle 都能通过 `schemas/audit-export-bundle.schema.json` 验证，并附带 [`spec/audit-export-bundle.md`](spec/audit-export-bundle.md) 中定义的伴随签名清单。
如果 Permit 验证器实现了 [`spec/failure-codes.md`](spec/failure-codes.md) 中的失败代码，并拒绝任何违反相应规范文档中规则的产物，则该验证器即符合规范。
## 稳定性
本规范中的传输格式和哈希算法是稳定的。对任何传输格式的破坏性变更都需要一个新的格式版本（`v2`、`closure_v3` 等）；先前的版本无限期保持有效，以便历史产物可以继续被验证。请参阅 [`CHANGELOG.md`](CHANGELOG.md)。
## 项目管理
Permit Spec 由 Keel API, Inc. 维护。
- 网站：https://keelapi.com
- 参考实现：https://github.com/keelapi/keel-api
- 参考验证器：https://github.com/keelapi/keel-verifier
## 许可证
Apache License 2.0。请参阅 [`LICENSE`](LICENSE)。
标签：AI智能体, CVE, Streamlit, 开源规范, 数字签名, 数据验证, 权限管理, 模型越狱, 访问控制