@agentunion/fastaun-browser 0.5.18 → 0.5.20

package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/2112.0.md

@@ -0,0 +1,161 @@
+# Ownership 协议定义 2.0
+
+本文定义 Ownership 2.0，与历史协议文档 [Ownership协议定义](Ownership协议定义.md) 并存。2.0 只定义双方声明、声明存放位置、共识检查和审计所需的关键概念。
+
+## 1. AID 和关系
+
+- **owner_aid**：声明并维护被管理关系的 AID。
+- **sub_aid**：被 owner_aid 管理的 AID。
+- **ownership 关系**：owner_aid 与 sub_aid 各自独立发布的声明。两份声明都存在且验证通过时，关系才是 `consensus`。
+
+2.0 不托管私钥或证书，不允许 owner_aid 代 sub_aid 签名或上传 `agent.md`。需要托管、备份或代理操作时，由应用层自行设计和授权。
+
+## 2. 声明结构
+
+两方使用同一 `statement` 结构；`declaration_id` 和 `declared_at` 可以不同。声明不包含独立签名，声明由所在文件的尾部 `AUN-SIGNATURE[-TAG]` 文件签名保护。声明方由文件位置和签名证书所属 AID 确定。
+
+```yaml
+statement:
+  version: 2
+  declaration_id: 550e8400-e29b-41d4-a716-446655440000
+  owner_aid: owner.agentid.pub
+  sub_aid: subject.agentid.pub
+  declared_at: 1791523200
+```
+
+字段定义：
+
+| 字段 | 定义 |
+| --- | --- |
+| `version` | 固定为 `2` |
+| `declaration_id` | 小写 UUID v4，用于审计中标识一份声明 |
+| `owner_aid` | 管理方的完整小写 AID |
+| `sub_aid` | 被管理方的完整小写 AID |
+| `declared_at` | 声明生成时的 Unix 秒正整数 |
+
+文件签名使用已有 agent.md 尾部签名规则，签名输入是签名块之前的全部原始 UTF-8 字节。签名块标识允许在 `AUN-SIGNATURE` 后追加大写 TAG；`agent.md` 可使用兼容的 `<!-- AUN-SIGNATURE` 或 `<!-- AUN-SIGNATURE-AGENTMD-V2`，`owner.md` 使用 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`。验证方通过签名块中的证书指纹取得公钥；2.0 不增加 ownership 专用证书或托管接口。
+
+## 3. sub_aid 的 `agent.md` 声明
+
+sub_aid 在自己的 `agent.md` frontmatter 中发布声明。`owner` 是可选字段；出现时必须与 `ownership.statement.owner_aid` 相同。
+
+```yaml
+aid: subject.agentid.pub
+name: Subject Agent
+type: agent
+version: 1.0.0
+owner: owner.agentid.pub
+ownership:
+  statement:
+    version: 2
+    declaration_id: 550e8400-e29b-41d4-a716-446655440000
+    owner_aid: owner.agentid.pub
+    sub_aid: subject.agentid.pub
+    declared_at: 1791523200
+```
+
+约束：
+
+1. `owner` 与 `ownership` 可以同时省略，表示 sub_aid 没有声明 owner_aid。
+2. 出现其中一个时，另一个必须出现；`owner_aid` 和 `sub_aid` 必须匹配。
+3. `agent.md` 的完整文件由 sub_aid 使用 `AUN-SIGNATURE` 或 `AUN-SIGNATURE-AGENTMD-V2` 尾部签名块签名，ownership 声明不再另设签名。
+4. `human` 类型不得声明 `owner` 或 `ownership`。
+
+## 4. owner_aid 的 `owner.md` 声明
+
+owner_aid 为每个 sub_aid 保存一份独立声明，路径约定为：
+
+```text
+owner_aid:/sub_aids/{sub_aid}/owner.md
+```
+
+`owner.md` 使用与 `agent.md` 相同的文件容器：YAML frontmatter、可选 Markdown 正文和文件尾部 `AUN-SIGNATURE-OWNERSHIP-V2` 签名块。
+
+```yaml
+---
+owner_aid: owner.agentid.pub
+sub_aid: subject.agentid.pub
+ownership:
+  statement:
+    version: 2
+    declaration_id: 660e8400-e29b-41d4-a716-446655440000
+    owner_aid: owner.agentid.pub
+    sub_aid: subject.agentid.pub
+    declared_at: 1791523260
+---
+
+Owner AID declaration.
+
+<!-- AUN-SIGNATURE-OWNERSHIP-V2
+cert_fingerprint: sha256:<64位hex>
+public_key_fingerprint: sha256:<64位hex>
+timestamp: 1791523260
+signature: <base64_der_signature>
+-->
+```
+
+`owner.md` 对外公开可读、可下载，不开放公共写权限。文件由 owner_aid 自己签名；创建、更新和删除由 owner_aid 或应用层明确授权的存储执行者完成。
+
+## 5. 声明、撤销和 SDK 方法
+
+2.0 不定义 ownership 绑定/解绑 RPC、ownership P2P 控制消息、申请事件、接受/拒绝方法或中间状态。声明和撤销只是双方对自己文档的写操作，使用已有的 `agent.md` 和 Storage 能力。
+
+SDK 向应用层提供以下五类方法，具体语言采用本端命名约定：
+
+| 方法 | 调用方 | 行为 |
+| --- | --- | --- |
+| `declareOwneraid(owner_aid)` | sub_aid | 生成声明，更新并上传自己的 `agent.md` |
+| `declareSubaid(sub_aid)` | owner_aid | 生成声明，写入自己的公开 `owner.md` |
+| `revokeOwneraid()` | sub_aid | 从自己的 `agent.md` 移除 `owner` 和 `ownership`，重新签名上传 |
+| `revokeSubaid(sub_aid)` | owner_aid | 删除自己的 `sub_aids/{sub_aid}/owner.md` |
+| `checkOwnershipConsensus(sub_aid?)` | 任一需要校验的一方 | 读取两份声明、验签并返回共识结果 |
+
+撤销是单方操作且可幂等执行。再次声明时生成新的 `declaration_id` 和文件签名。
+
+## 6. 共识检查和审计
+
+`checkOwnershipConsensus` 至少检查：
+
+1. sub_aid 当前 `agent.md` 中的 `owner`、`ownership.statement`、`owner_aid` 和 `sub_aid`。
+2. owner_aid 公开 `owner.md` 的路径、字段和文件尾部签名。
+3. 两个文件的签名证书分别属于 sub_aid 和 owner_aid，且声明中的 `owner_aid`、`sub_aid` 相同。
+4. 任一文件不存在、被撤销、字段不匹配或文件签名无效时，不返回 `consensus`。
+
+建议返回以下状态：
+
+| 条件 | 状态 |
+| --- | --- |
+| 两份声明和文件签名均有效 | `consensus` |
+| 两份声明均不存在 | `unbound` |
+| 只有一方声明存在 | `single_sided` |
+| 字段、路径或文件签名无效 | `invalid` |
+
+需要 owner 关系的业务操作必须先完成共识检查，再在应用层或审计服务中追加记录双方声明和文件签名。审计记录至少保存：
+
+```yaml
+audit_id: <uuid-v4>
+operation: <application-operation>
+checked_at: <unix-seconds>
+actor_aid: <caller-aid>
+owner_aid: owner.agentid.pub
+sub_aid: subject.agentid.pub
+result: consensus
+sub_aid_statement: <statement 快照>
+owner_aid_statement: <statement 快照>
+sub_aid_document_hash: <agent.md 摘要>
+owner_aid_document_hash: <owner.md 摘要>
+sub_aid_file_signature: <AUN-SIGNATURE-AGENTMD-V2 或兼容标识快照>
+owner_aid_file_signature: <AUN-SIGNATURE-OWNERSHIP-V2 快照>
+```
+
+审计记录由应用层或审计服务追加保存。之后任一方删除声明，不影响已经记录的历史事实。
+
+## 7. 接口边界
+
+- `agent.md`：由 sub_aid 使用已有 Name Service 接口写入；owner 与 ownership 声明由 sub_aid 负责。
+- `owner.md`：由 owner_aid 使用已有 Storage 写入或删除；公开读下载，拒绝公共写入。
+- Message/Gateway：不承载 ownership 控制消息；2.0 不新增 P2P payload。
+- Auth/CA：继续提供已有 token、证书和 AID 验证能力；不增加 ownership 专用 RPC。
+- Storage：承载 owner_aid 自己的 `owner.md` 及应用数据，不承载 sub_aid 私钥或证书。
+- 审计：由应用层或审计服务保存，不由 ownership 协议新增 RPC 管理。
+