@agentunion/fastaun-browser 0.5.20 → 0.5.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +47 -0
- package/_packed_docs/CHANGELOG.md +47 -0
- package/_packed_docs/INDEX.md +453 -440
- package/_packed_docs/KITE_DOCS_GUIDE.md +164 -161
- package/_packed_docs/agent.md/working/AID/347/261/273/345/236/213-owner/345/205/263/347/263/273/344/270/216/346/215/242owner/347/274/226/346/216/222/346/226/271/346/241/210.md +530 -0
- package/_packed_docs/agent.md/working/AID/347/261/273/345/236/213-owner/345/205/263/347/263/273/345/256/214/346/225/264/350/256/276/350/256/241/344/270/216/345/256/236/346/226/275/350/256/241/345/210/222.md +685 -0
- package/_packed_docs/agent.md/working/agent.md-schema/344/270/216/347/255/276/345/217/221/351/252/214/347/255/276/346/265/201/347/250/213/346/276/204/346/270/205.md +349 -0
- package/_packed_docs/agent.md/working//346/234/254/345/234/260Docker/346/265/213/350/257/225Bug/346/270/205/345/215/225.md +40 -0
- package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md +1433 -1392
- package/_packed_docs/protocol/08-AUN-E2EE.md +17 -12
- package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/211.md +2 -0
- package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/2112.1.md +666 -658
- package/_packed_docs/sdk/0.5.21-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md +368 -0
- package/_packed_docs/sdk/0.5.21-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md +350 -0
- package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md +1 -1
- package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md +5 -1
- package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md +64 -64
- package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +4 -1
- package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md +42 -39
- package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +147 -14
- package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md +48 -47
- package/_packed_docs/sdk/09-group-rpc-manual.md +5 -2
- package/_packed_docs/sdk/09-message-rpc-manual.md +250 -160
- package/_packed_docs/sdk/09-/345/207/255/350/257/201/346/234/215/345/212/241RPC/346/211/213/345/206/214.md +71 -0
- package/_packed_docs/sdk/09-/347/273/204/347/273/207/346/234/215/345/212/241RPC/346/211/213/345/206/214.md +88 -0
- package/_packed_docs/sdk/AUN_DOCS_GUIDE.md +134 -130
- package/_packed_docs/sdk/INDEX.md +239 -221
- package/_packed_docs/sdk/Ownership-SDK/347/274/226/346/216/222/346/214/207/345/215/2272.1.md +930 -922
- package/_packed_docs/sdk/Ownership2.1-SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md +106 -43
- package/_packed_docs/sdk/Ownership2.1-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md +180 -9
- package/_packed_docs/sdk/Ownership2.1-TDD/345/210/206/351/230/266/346/256/265/345/256/236/346/226/275/350/256/241/345/210/222.md +708 -708
- package/_packed_docs/sdk/Ownership2.1/350/257/246/347/273/206/350/256/276/350/256/241.md +480 -476
- package/_packed_docs/sdk//345/207/255/350/257/201/344/270/216/347/273/204/347/273/207/346/234/215/345/212/241SDK/345/272/224/347/224/250/351/233/206/346/210/220/346/214/207/345/215/227.md +1 -1
- package/_packed_docs/sdk//345/207/255/350/257/201/344/270/216/347/273/204/347/273/207/346/234/215/345/212/241SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md +2 -2
- package/dist/agent-md-schema.d.ts +1 -0
- package/dist/agent-md-schema.d.ts.map +1 -1
- package/dist/agent-md-schema.js +5 -4
- package/dist/agent-md-schema.js.map +1 -1
- package/dist/agent-md.d.ts +25 -1
- package/dist/agent-md.d.ts.map +1 -1
- package/dist/agent-md.js +148 -71
- package/dist/agent-md.js.map +1 -1
- package/dist/aid-store.d.ts +13 -0
- package/dist/aid-store.d.ts.map +1 -1
- package/dist/aid-store.js +55 -8
- package/dist/aid-store.js.map +1 -1
- package/dist/aid.d.ts.map +1 -1
- package/dist/aid.js +2 -1
- package/dist/aid.js.map +1 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +4 -0
- package/dist/auth.js.map +1 -1
- package/dist/bundle.js +4981 -1219
- package/dist/cert-utils.d.ts +1 -0
- package/dist/cert-utils.d.ts.map +1 -1
- package/dist/cert-utils.js +21 -0
- package/dist/cert-utils.js.map +1 -1
- package/dist/client/delivery.d.ts +101 -16
- package/dist/client/delivery.d.ts.map +1 -1
- package/dist/client/delivery.js +1172 -160
- package/dist/client/delivery.js.map +1 -1
- package/dist/client/rpc-pipeline.d.ts +4 -1
- package/dist/client/rpc-pipeline.d.ts.map +1 -1
- package/dist/client/rpc-pipeline.js +122 -48
- package/dist/client/rpc-pipeline.js.map +1 -1
- package/dist/client/v2-e2ee.d.ts +22 -3
- package/dist/client/v2-e2ee.d.ts.map +1 -1
- package/dist/client/v2-e2ee.js +1258 -649
- package/dist/client/v2-e2ee.js.map +1 -1
- package/dist/client.d.ts +23 -2
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +391 -87
- package/dist/client.js.map +1 -1
- package/dist/config.d.ts +4 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +1 -0
- package/dist/config.js.map +1 -1
- package/dist/events.d.ts +19 -1
- package/dist/events.d.ts.map +1 -1
- package/dist/events.js +146 -23
- package/dist/events.js.map +1 -1
- package/dist/facades.d.ts +42 -1
- package/dist/facades.d.ts.map +1 -1
- package/dist/facades.js +363 -7
- package/dist/facades.js.map +1 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/keystore/index.d.ts +14 -1
- package/dist/keystore/index.d.ts.map +1 -1
- package/dist/keystore/indexeddb-identity-store.d.ts +4 -0
- package/dist/keystore/indexeddb-identity-store.d.ts.map +1 -1
- package/dist/keystore/indexeddb-identity-store.js +30 -13
- package/dist/keystore/indexeddb-identity-store.js.map +1 -1
- package/dist/keystore/indexeddb-shared.d.ts +19 -2
- package/dist/keystore/indexeddb-shared.d.ts.map +1 -1
- package/dist/keystore/indexeddb-shared.js +193 -6
- package/dist/keystore/indexeddb-shared.js.map +1 -1
- package/dist/keystore/indexeddb-token-store.d.ts +15 -2
- package/dist/keystore/indexeddb-token-store.d.ts.map +1 -1
- package/dist/keystore/indexeddb-token-store.js +308 -27
- package/dist/keystore/indexeddb-token-store.js.map +1 -1
- package/dist/org-protocol.d.ts +45 -0
- package/dist/org-protocol.d.ts.map +1 -1
- package/dist/org-protocol.js +757 -11
- package/dist/org-protocol.js.map +1 -1
- package/dist/ownership-v21.d.ts +21 -4
- package/dist/ownership-v21.d.ts.map +1 -1
- package/dist/ownership-v21.js +49 -16
- package/dist/ownership-v21.js.map +1 -1
- package/dist/ownership-workflow.d.ts +30 -0
- package/dist/ownership-workflow.d.ts.map +1 -1
- package/dist/ownership-workflow.js +412 -54
- package/dist/ownership-workflow.js.map +1 -1
- package/dist/seq-tracker.d.ts +2 -0
- package/dist/seq-tracker.d.ts.map +1 -1
- package/dist/seq-tracker.js +3 -2
- package/dist/seq-tracker.js.map +1 -1
- package/dist/tools/cross-sdk-agent.d.ts +60 -3
- package/dist/tools/cross-sdk-agent.d.ts.map +1 -1
- package/dist/tools/cross-sdk-agent.js +433 -37
- package/dist/tools/cross-sdk-agent.js.map +1 -1
- package/dist/transport.d.ts +3 -0
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +62 -30
- package/dist/transport.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,530 @@
|
|
|
1
|
+
# AID 类型、owner 关系与换 owner 编排方案
|
|
2
|
+
|
|
3
|
+
本文为历史 working 草案;现行字段与验证规则以 [Ownership 协议定义 2.1](../../protocol/Ownership协议定义2.1.md) 为准。当前 Group/Org 的 owner 来自专属生命周期,名片由 owner 本人尾签并以 V2 授权代上传,可没有 ownership;本草案中的通用 proof、目标身份代签和注册/换 owner 流程不作为当前实现依据。
|
|
4
|
+
|
|
5
|
+
> 状态:working 方案草案;Phase 0 策略已确认,RPC 名称和正式 wire 契约仍需落稿冻结
|
|
6
|
+
>
|
|
7
|
+
> 记录日期:2026-10-02
|
|
8
|
+
>
|
|
9
|
+
> 关联讨论:[agent.md Schema 与签发/验签流程澄清记录](agent.md-schema与签发验签流程澄清.md)
|
|
10
|
+
|
|
11
|
+
## 1. 结论摘要
|
|
12
|
+
|
|
13
|
+
### 1.1 `type` / `owner` 是高层 SDK 的编排输入
|
|
14
|
+
|
|
15
|
+
创建 AID 时,应用将 `type`、`owner` 和可选的 agent.md 内容传给 SDK。SDK 负责:
|
|
16
|
+
|
|
17
|
+
- 生成和保存 subject AID 的密钥;
|
|
18
|
+
- 根据 `type` / `owner` 选择 human、外部 owner 或自主 agent 流程;
|
|
19
|
+
- 获取服务端生成的关系声明并让相关主体签名;
|
|
20
|
+
- 在远端 owner 场景等待审批;
|
|
21
|
+
- 生成带关系字段的 agent.md、签署并上传;
|
|
22
|
+
- 持久化 pending 状态,支持超时、重试和崩溃恢复。
|
|
23
|
+
|
|
24
|
+
SDK 不是信任根。Auth 是 owner 关系的唯一权威台账和关系操作协调入口;Auth 必须重新验证类型、owner、证书、两方或三方签名、agent.md 和当前关系版本,并以单一数据库事务结果为准。每个 subject 最多一条 active owner 关系,且最多一个未完成的 owner-change operation。低层 `auth.create_aid` 只负责兼容旧客户端且不得改关系;新注册和所有关系变更使用 Auth prepare/commit 流程。
|
|
25
|
+
|
|
26
|
+
`agent.md` 中的 owner 与关系证明对公众可验证;大多数读取、展示和普通验签场景可直接信任验签通过的声明,不依赖 Auth。只有创建、替换或撤销权威 owner 关系的写入必须经过 Auth 验证和提交;Name Service、Storage 等不得绕过 Auth 改写关系台账。只改名片正文等不改变 owner 关系的内容,不触发 owner 关系审批,仍按 agent.md 自身签名和发布规则处理。公开验签不能单独证明关系仍是最新/active;只有依赖最新关系状态的具体场景才需满足相应新鲜度要求。Auth 对并发、版本和 operation 等协议冲突作裁定;owner 失联、丢失或疑似泄露不在本版 recovery 范围内,关系按可验证状态报告为 `unusable`。
|
|
27
|
+
|
|
28
|
+
Auth 可以类比为 AUN 信任域内的登记机构:双方签署共同事实,Auth 验证双方签名和策略后登记 proof,托管原始声明、签名材料、证书引用和审计证据,并签发登记回执。回执证明“这些证据已按 Auth 策略登记”,不替代 subject/owner 的关系签名,也不意味着 Auth 持有任何一方私钥。Auth 不必在线见证双方离线交换,只需在最终提交时完成登记;公开 proof 仍可独立验签,登记状态/当前性由 Auth 回执和台账提供。
|
|
29
|
+
|
|
30
|
+
### 1.2 换 owner 是独立的多方编排流程
|
|
31
|
+
|
|
32
|
+
换 owner 不能通过上传一个新的 `agent.md` 或直接改 `owner` 字段完成,且必须由 Auth 当前 active owner 发起:
|
|
33
|
+
|
|
34
|
+
1. Auth 验证请求者是当前 owner,为该 subject 创建唯一 pending operation,并生成绑定指定 new owner 和当前 relation version 的转移 challenge;
|
|
35
|
+
2. 当前 owner 对 challenge 签署转移授权,subject 与 new owner 分别对新关系声明独立签名;
|
|
36
|
+
3. subject SDK 使用新的关系证明重新签署 agent.md;
|
|
37
|
+
4. Auth 验证所有签名并以 expected relation version 做 CAS,在一个事务中废止旧证明、激活新证明并更新权威关系;Name Service 只公开与 Auth active registry 一致的 agent.md 快照。
|
|
38
|
+
|
|
39
|
+
这样可以拒绝 subject 自行改绑、非当前 owner 发起、旧授权重放和并发换 owner 覆盖。密码学证明可独立验证各主体对具体声明的同意;Auth 的唯一台账、单一 pending operation 与原子 CAS 保证权威记录中只有一个 active owner。关系变更写入必须由 Auth 校验并提交;读取方如需判断当前/最新状态,则还要取得足够新鲜的 Auth 已验证状态。Auth 外部的冲突文件不会改变 AUN 内权威关系。
|
|
40
|
+
|
|
41
|
+
Auth 的自动仲裁只覆盖台账、签名、operation 和 CAS 规则内的协议冲突。old owner 失联、丢失或疑似泄露时,本版不启动专门 recovery、争议恢复或自动换绑;owner 验证材料失效时关系报告为 `unusable`,基本登录和通信仍按证书/AID 状态处理。解绑经 Auth 进入 `unbound`,非 human AID 也可以处于该关系状态,具体 owner 依赖场景由应用层决定。
|
|
42
|
+
|
|
43
|
+
### 1.3 从属关系的 owner-side 备份空间
|
|
44
|
+
|
|
45
|
+
delegated 从属关系激活后,owner 的 AID storage 自动获得一个统一的关系备份命名空间:`<owner_aid>:/.aun/subjects/<canonical_subject_aid>/`。每个 owner/subject 对应一个确定的子目录,subject 通过关系 ACL 获得 `rw` 备份权限;关系撤销只撤销 ACL 和访问票据,不清理目录或其中的数据。该命名空间属于协议保留路径,不能由普通应用自行创建、改 ACL 或变更可见性。
|
|
46
|
+
|
|
47
|
+
### 1.4 签名顺序与传递边界
|
|
48
|
+
|
|
49
|
+
关系声明采用“subject 先签、owner 后签”的交换顺序,但双方独立签署**同一份冻结声明**。签署顺序是流程要求,不是 owner 在 subject 签名上追加一层签名:
|
|
50
|
+
|
|
51
|
+
1. 构造自包含双方 AID 与 `proof_id` 的独立声明,声明的角色、签署时间和扩展字段以当前 SCHEMA.md 为准;
|
|
52
|
+
2. subject 先签署该 statement,并将原始 statement 和签名交给 owner;
|
|
53
|
+
3. owner 验证 subject 签名后,对完全相同的 canonical 字节独立签名,经 pending inbox 或离线文件/二维码回传;
|
|
54
|
+
4. subject 验证 owner 的原始声明与实际签名;self-owner 只保留 subject 签名,外部 owner 放入双方签名;随后组装并签署 agent.md。
|
|
55
|
+
|
|
56
|
+
owner 永远不接收 subject 私钥,也不需要获得 subject agent.md 的写权限;owner 的签名传递的是关系审批材料,不是对 agent.md 文件的修改。双方不要求同时在线,服务端只负责保存、转发和最终验签。
|
|
57
|
+
|
|
58
|
+
## 2. 关系模型
|
|
59
|
+
|
|
60
|
+
### 2.1 八种 AID 类型
|
|
61
|
+
|
|
62
|
+
当前预设类型为:
|
|
63
|
+
|
|
64
|
+
`human`、`agent`、`group`、`service`、`device`、`host`、`org`、`custom`。
|
|
65
|
+
|
|
66
|
+
`type` 是注册表中的身份属性,不只是 agent.md 展示文本。agent.md 的 `type` 必须与注册表一致;普通 agent.md 内容更新不能改变注册表 type。CA 维护类型到证书用途的映射:`group -> aid_type=group/key_purpose=group_identity`、`org -> aid_type=org/key_purpose=org_identity`,`human/agent/service/device/host/custom -> aid_type=normal/key_purpose=signing`;未来 group-like 类型只能通过映射表扩展。
|
|
67
|
+
|
|
68
|
+
### 2.2 owner 规则
|
|
69
|
+
|
|
70
|
+
| subject type | 新建时 owner | owner 允许的 agent.md type | 关系证明 |
|
|
71
|
+
| --- | --- | --- | --- |
|
|
72
|
+
| `human` | 禁止指定,默认无 owner | 不适用 | 不要求 |
|
|
73
|
+
| `agent` | 必须;可等于 subject AID 表示自主 | `human` 或 `agent`;自主模式跳过 owner agent.md 回源 | 外部 owner 双签;self-owner 仅 subject 单签 |
|
|
74
|
+
| `group` | 必须 | `human` 或 `agent` | group identity subject + owner |
|
|
75
|
+
| `service` | 必须 | `human` 或 `agent` | subject + owner |
|
|
76
|
+
| `device` | 必须 | `human` 或 `agent` | subject + owner |
|
|
77
|
+
| `host` | 必须 | `human` 或 `agent` | subject + owner |
|
|
78
|
+
| `org` | 必须 | `human` 或 `agent` | org identity subject + owner |
|
|
79
|
+
| `custom` | 必须 | `human` 或 `agent` | subject + owner |
|
|
80
|
+
|
|
81
|
+
Schema 层的 `owner` 与 `ownership_proof` 均可选,以兼容旧 agent.md;两者同时缺省时可读取为无 proof 的旧/未绑定文档,但字段一旦出现必须完整、合法且相互匹配。`human` AID 不得出现任一关系字段。兼容旧客户端时,`owner` 和 `type` 可以缺失,但服务端必须把这种记录标记为 `legacy_unbound`,不能把它当成已证明的非 human 所有关系。新 SDK 不应默认创建这种状态。
|
|
82
|
+
|
|
83
|
+
约束如下:
|
|
84
|
+
|
|
85
|
+
- `owner` 必须是有效 AID;不存在、证书无效或 agent.md 无法验证的 owner 均不能建立新关系。Auth 不同步调用 Name Service;未注册 AID 查询返回 `registered=false`/`unbound`,需要 owner verified 的写入仍拒绝;收到签名 profile 证据时可懒注册最小台账;
|
|
86
|
+
- 外部 owner 的已验证 agent.md `type` 只能是 `human` 或 `agent`;
|
|
87
|
+
- 只验证直接 owner,不递归验证 owner 的 owner,避免验证链递归和网络放大;
|
|
88
|
+
- 允许 `agent.owner == agent.aid`,表示自主 agent;此模式不读取或验证 owner agent.md,但仍验证 subject 证书、subject agent.md 和自主关系证明;
|
|
89
|
+
- 只允许自主 `agent` 使用 self-owner;其它类型不能用 self-owner 绕过 owner 约束;
|
|
90
|
+
- Auth 写入关系前检查 owner 图,除允许的 agent self-edge 外不得形成环;这与只验证直接 owner 的 profile 规则分开执行;
|
|
91
|
+
- 新建关系必须有明确的 `relation_version`,换 owner 时单调递增。
|
|
92
|
+
|
|
93
|
+
这里使用 `subject_aid` 表示“被拥有的 AID”。“sub-aid”只是关系角色,不是另一种 AID 格式,也不应引入第二套名称解析规则。
|
|
94
|
+
|
|
95
|
+
### 2.3 owner-side subject storage 命名空间
|
|
96
|
+
|
|
97
|
+
外部 owner 关系激活后,服务端必须在 owner AID 的 Storage 命名空间中创建或复用一个关系目录,并授予 subject 最小备份权限。统一路径约定为:
|
|
98
|
+
|
|
99
|
+
```text
|
|
100
|
+
<owner_aid>:/.aun/subjects/<canonical_subject_aid>/
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
其中:
|
|
104
|
+
|
|
105
|
+
- bucket 固定为 `default`,应用不能通过参数改成另一 bucket;
|
|
106
|
+
- `canonical_subject_aid` 为按 AUN AID 规范归一化后的全小写 AID,AID 不作为路径查询参数或可变别名;
|
|
107
|
+
- `/.aun/subjects/` 是 Storage 保留根,下面每个 subject AID 只有一个确定的子目录;目录映射由服务端从 active relation 推导,客户端不得自行创建同名替代目录;
|
|
108
|
+
- 目录内容是不透明的备份材料,服务端不解释文件名、格式或密钥用途;关系元数据保存在服务端关系台账,不要求写入用户可修改的标记文件。
|
|
109
|
+
|
|
110
|
+
权限基线如下:
|
|
111
|
+
|
|
112
|
+
| 主体 | 权限 |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| owner AID | 对该目录及内容保留 Storage owner 的完整控制权 |
|
|
115
|
+
| 当前 active subject AID | 关系 ACL `rw`:可列出、读取、创建、覆盖、删除、移动和重命名目录内部对象;不得移动/删除 subject 根目录本身,也不得修改 ACL、公开可见性、签发 token 或挂载该目录 |
|
|
116
|
+
| 其它 AID | 无访问权;不能通过列目录、前缀查询或分享链接枚举该命名空间 |
|
|
117
|
+
|
|
118
|
+
这里的关系 ACL `rw` 是该保留命名空间的协议语义,明确包含 subject 的直接读权限;不能把普通 Storage 应用 ACL“读访问使用分享链接”的建议直接套用到此处。目录默认 private,禁止通过普通 `storage.set_visibility`、分享链接或 token 把它变成公共或第三方可读资源。subject 的备份数据访问必须经过服务端关系 ACL/状态检查和该固定路径,不能只依赖客户端携带的 `owner_aid`;Storage 可基于 Auth 已验证并下发的 ACL 状态处理普通数据访问,无须每次访问都实时调用 Auth。关系 ACL 的创建、变更和撤销仍须由 Auth 验证的关系操作触发。
|
|
119
|
+
|
|
120
|
+
关系 ACL 的 `acl_source` 为 `ownership_relation`,是受保护的系统授权:owner 和 subject 都不能通过普通 `storage.set_acl` / `storage.remove_acl` 修改、复制或恢复该授权;owner 如需撤销 subject 访问,必须发起关系撤销或换 owner 流程,由关系服务统一更新 ACL。owner 仍可按 Storage owner 权限读取、覆盖或清理目录数据,但这些数据操作不等同于改变关系 ACL。
|
|
121
|
+
|
|
122
|
+
关键材料默认应由 subject SDK 在上传前加密,目录只保存不透明字节;owner storage 的读权限不表示 owner 能理解或解密材料。协议只定义目录访问与保留,不把备份内容格式或密钥托管方式写死。
|
|
123
|
+
|
|
124
|
+
从属关系只适用于外部 owner 的 delegated proof。human 无 owner、agent 的 self-owner 和 `legacy_unbound` 不创建跨 AID 备份目录;self-owner 的材料直接属于自身 Storage。目录根和 `/.aun/subjects/` 由服务端保护,普通 Storage 客户端不能删除、移动、重命名或改变其 ACL。
|
|
125
|
+
|
|
126
|
+
这里的 `rw` 允许 subject 管理目录内部对象,包括删除、移动和重命名;但不等于把普通 Storage 的所有者权限复制给 subject。subject 不能移动或删除 subject 根目录本身,也不能修改关系 ACL;关系撤销仍只撤 ACL、不删数据。
|
|
127
|
+
|
|
128
|
+
关系命名空间的服务端元数据采用以下协议对象(不写入 subject 可修改的备份文件):
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"schema": "aun.relation-backup-namespace.v1",
|
|
133
|
+
"owner_aid": "alice.agentid.pub",
|
|
134
|
+
"subject_aid": "sensor.agentid.pub",
|
|
135
|
+
"proof_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
136
|
+
"relation_version": 1,
|
|
137
|
+
"bucket": "default",
|
|
138
|
+
"path": "/.aun/subjects/sensor.agentid.pub/",
|
|
139
|
+
"acl_source": "ownership_relation",
|
|
140
|
+
"acl_generation": 1,
|
|
141
|
+
"status": "ready",
|
|
142
|
+
"on_revoke": "retain_data_revoke_acl"
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`status` 至少取 `pending`、`ready`、`revoked`、`retained`;`acl_generation` 在授予和撤销时单调递增。subject 访问时必须命中 `owner_aid + subject_aid + active proof/relation_version + path` 的服务端组合键,不能只提交 path 或伪造 `owner_aid`。subject 可以访问精确子目录及其后代,但不能列举 `/.aun/subjects/` 的其它 subject 子目录。
|
|
147
|
+
|
|
148
|
+
## 3. agent.md Schema 调整
|
|
149
|
+
|
|
150
|
+
推荐新增两个 frontmatter 字段;下方 proof 外层结构是已确认的 Phase 0 业务基线,正式 wire schema 仍需按既有 RPC/Schema 文档落稿:
|
|
151
|
+
|
|
152
|
+
```yaml
|
|
153
|
+
owner: "alice.agentid.pub"
|
|
154
|
+
ownership_proof:
|
|
155
|
+
proof_id: "550e8400-e29b-41d4-a716-446655440000"
|
|
156
|
+
subject_aid: "sensor.agentid.pub"
|
|
157
|
+
owner_aid: "alice.agentid.pub"
|
|
158
|
+
subject_signature:
|
|
159
|
+
cert_fingerprint: "sha256:..."
|
|
160
|
+
signature: "..."
|
|
161
|
+
owner_signature:
|
|
162
|
+
cert_fingerprint: "sha256:..."
|
|
163
|
+
signature: "..."
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
字段语义:
|
|
167
|
+
|
|
168
|
+
- `owner` 是当前关系指针;Schema 中可省略,旧文档可以缺失;但 human 不得出现该字段;
|
|
169
|
+
- `ownership_proof` 是独立于 Markdown 内容的关系证明;
|
|
170
|
+
- `proof_id` 用于关联双方针对同一关系的声明;`self` / `delegated` 可由 `subject_aid == owner_aid` 推导;
|
|
171
|
+
- `subject_aid` 和 `owner_aid` 表达关系事实;`relation_version` 是服务端台账中的关系代次并与 proof ID 绑定,不进入共同签署声明;若需要在 proof 外层镜像,应明确其为服务端关系元数据;完整 agent.md 仍由 subject 自己签名,`group`/`org` 文件主体例外使用对应 identity 证书;
|
|
172
|
+
- `subject_signature` 和 `owner_signature` 保存各自独立声明、证书指纹与签名;self-owner 只保留 `subject_signature`;
|
|
173
|
+
- 编排关联使用 request/proof 标识,关系验证直接使用原始声明和签名;
|
|
174
|
+
- 不在双方签名封套里放签名者各自填写的时间戳。服务端在 prepare 时记录统一 operation 创建/过期时间,在收到每份签名时记录可信接收时间;签名必须在 operation 有效期间提交。需要延长审批窗口时由双方对新 `proof_id` 的声明重新签名;
|
|
175
|
+
- 证明签名沿用 ECDSA P-256 / SHA-256、DER + Base64 和证书指纹格式,但不复用 agent.md 尾部签名块。
|
|
176
|
+
|
|
177
|
+
owner 只产生并传递 `owner_signature`,不接收 subject 的可写 agent.md,也不替 subject 组装或签署 agent.md。subject 按关系模式收齐所需签名后,将声明和签名封套放入同一个 `ownership_proof` 对象,再用自己的 `active_signing` 证书签署完整 agent.md;`group`/`org` 文件主体改由对应 identity 证书签署。
|
|
178
|
+
|
|
179
|
+
`ownership_proof.owner_aid` 必须与 `owner` 相等,`subject_aid` 必须与 agent.md 的 `aid` 相等;`type` 由 agent.md 与 Auth registry 交叉校验,不进入共同签署声明。服务端还必须把证明中的 `proof_id` 和台账中的关系版本与当前注册状态逐一比对。
|
|
180
|
+
|
|
181
|
+
## 4. 关系证明签名内容
|
|
182
|
+
|
|
183
|
+
关系证明不能签整个 agent.md,否则 description、avatar、tags 或 Markdown 任意变化都会要求 owner 重新签名。已确认 subject 与 owner 独立签署同一份最小关系声明,语义字段恰为 `proof_id`、`subject_aid`、`owner_aid`,不签任何展示内容:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{
|
|
187
|
+
"proof_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
188
|
+
"subject_aid": "sensor.agentid.pub",
|
|
189
|
+
"owner_aid": "alice.agentid.pub"
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
双方共同确认同一对 subject/owner AID 与同一 proof,分别签署自己的自包含声明;签署时间和扩展字段允许不同。当前字段集合见 SCHEMA.md。
|
|
194
|
+
|
|
195
|
+
```text
|
|
196
|
+
"AUN-AID-OWNER-RELATION-V1;" + canonical_json(statement)
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
编码规则为:AID 按现有规则规范为小写,`canonical_json` 复用四端 `v2` 实现。签名沿用 ECDSA-P256-SHA256、ASN.1 DER 和标准 Base64,域分隔符固定为可见的 `AUN-AID-OWNER-RELATION-V1;`。跨端验收声明字段及签名互验,不要求签名字符串相同。
|
|
200
|
+
|
|
201
|
+
subject 先签并把自己的声明与签名交给 owner。owner 验证后独立签署自己的声明,双方确认 subject AID 的 owner 是 owner AID。self-owner 只保留 subject 签名。
|
|
202
|
+
|
|
203
|
+
双方分别填写 `signed_at` 并纳入各自签名;接收方直接验证声明和签名,并检查签署时证书有效性。当前方案不由 Auth 编排 operation,不做关系防重放。
|
|
204
|
+
|
|
205
|
+
`subject_type`、`relation_version`、operation ID、签名字段、证书指纹和 agent.md 内容不进入共同 statement。AID 规范化、`canonical_json`、可见分号域分隔符、哈希算法和 DER/Base64 编码按上述 Phase 0 结论执行,并提供四端共享测试向量。
|
|
206
|
+
|
|
207
|
+
### 4.1 为什么普通内容变化不需要重签 owner proof
|
|
208
|
+
|
|
209
|
+
agent.md 仍然需要重新生成**主体自己的文件签名**,因为当前尾部签名覆盖整个 payload;但只要以下关系字段不变,就直接复用原 `ownership_proof`:
|
|
210
|
+
|
|
211
|
+
- `owner`;
|
|
212
|
+
- `subject_aid`;
|
|
213
|
+
- `subject_type`;
|
|
214
|
+
- `relation_version`;
|
|
215
|
+
- `proof_id`。
|
|
216
|
+
|
|
217
|
+
因此修改 `name`、`description`、`avatar`、`tags`、Skills 或 Markdown 时:
|
|
218
|
+
|
|
219
|
+
1. SDK 保留原 `ownership_proof` 字节语义;
|
|
220
|
+
2. SDK 只用 subject 当前 `active_signing` 证书重新签 agent.md 尾部签名;`group`/`org` 文件主体使用对应 identity 证书;
|
|
221
|
+
3. Name Service 验证新的 agent.md 签名,并验证其中的 proof 仍等于当前 active proof;
|
|
222
|
+
4. 不调用 owner,也不产生新的 owner proof。
|
|
223
|
+
|
|
224
|
+
如果修改 `owner` 或 `type`,则关系声明已变化,必须走关系变更流程并生成新的 proof。不能让普通 `PUT /agent.md` 隐式改变关系。
|
|
225
|
+
|
|
226
|
+
## 5. 创建 AID 的编排流程
|
|
227
|
+
|
|
228
|
+
### 5.1 SDK 输入
|
|
229
|
+
|
|
230
|
+
新 SDK 提供高层注册入口,示意参数为:
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
register(aid, {
|
|
234
|
+
type,
|
|
235
|
+
owner?,
|
|
236
|
+
agent_md?,
|
|
237
|
+
owner_approval?,
|
|
238
|
+
idempotency_key?
|
|
239
|
+
})
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
缺失 `type` 时,新入口直接拒绝;旧的 `register(aid)` 保留为兼容入口并明确产生 `legacy_unbound`,不得悄悄推断为 `agent`。
|
|
243
|
+
|
|
244
|
+
### 5.2 服务端状态机
|
|
245
|
+
|
|
246
|
+
```text
|
|
247
|
+
reserved
|
|
248
|
+
-> proof_pending
|
|
249
|
+
-> agent_md_pending
|
|
250
|
+
-> active
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`proof_pending` 内部用 `awaiting_subject_signature`/`awaiting_owner_signature` 表示签名等待;证书状态独立维护,签发后即为正常可认证证书,不创建 `certificate_issued`、`owner_signature_pending` 或 `proof_ready` 生命周期状态。
|
|
254
|
+
|
|
255
|
+
任一阶段失败都保留带过期时间的 operation 记录;operation 尚未完成不代表 owner 关系已 active,但已签发且未吊销的证书及 AID 不因此变为不可登录。重试必须使用同一个 `idempotency_key`,返回同一个 operation 结果。
|
|
256
|
+
|
|
257
|
+
### 5.3 推荐流程
|
|
258
|
+
|
|
259
|
+
1. **本地预检**:SDK 校验 AID、八种 type、owner 格式、self-owner 规则和本地 agent.md Schema,生成 subject 密钥并写入 pending keystore。
|
|
260
|
+
2. **prepare**:SDK 调用服务端注册准备方法,提交 `aid`、subject 公钥、`type`、`owner`、客户端幂等键。服务端检查命名冲突、owner 直接类型、关系环和策略,预留 AID 并签发正常可用的 subject 证书,返回 `operation_id`、`proof_id`、`relation_version`、过期时间以及 canonical statement。证书签发后即可按现有规则登录和收发基本消息;尚未登记的 owner 关系不能用于 owner 授权、换 owner 或 owner-side 备份目录等 owner-sensitive 场景。
|
|
261
|
+
3. **owner 证明**:
|
|
262
|
+
- human:不需要 owner 签名;
|
|
263
|
+
- agent self-owner:subject 对最小关系 statement 签名,不回源验证自己的 agent.md;self/delegated 可由 subject 与 owner AID 是否相同推导,proof 只保存一份 `subject_signature`;
|
|
264
|
+
- 外部 owner:subject 先对 statement 签名,生成 detached `subject_signature` 请求包;owner SDK 验证 statement 和 subject 签名后,对同一 statement 独立签名,生成 detached `owner_signature`。owner 不修改 subject agent.md,也不接触 subject 私钥。group/org subject 的 agent.md 文件签名必须使用对应 identity 证书,群主/组织管理者仅提供上传授权。
|
|
265
|
+
4. **commit proof**:SDK 提交该模式所需签名,或让服务端从 pending operation 取回 owner 签名。外部 owner 关系须确认 subject/owner 两份签名对应完全相同的 canonical statement;self-owner 只验一份 `subject_signature`。新提交必须使用 `active_signing` 证书;服务端按指纹解析证书,校验证书链、主体、用途、proof/version 和 operation 有效期,并把 owner proof 写入不可变关系台账;通过后状态进入 `agent_md_pending`。
|
|
266
|
+
5. **构造 agent.md**:subject SDK 验证 owner 回执后,将 `type`、`owner`、服务端返回的完整 `ownership_proof` 写入 frontmatter,用 subject 当前 `active_signing` 证书签署整个 agent.md;`group`/`org` 文件主体签名分别使用对应的 group/org identity 证书,群主/组织管理者只提供上传授权。
|
|
267
|
+
6. **发布 agent.md**:subject SDK 调用 `PUT /agent.md`。Name Service 必须同时校验 agent.md 文件签名(写链路仅 `active_signing`)、type/owner 与注册表一致、proof_id/版本一致、owner agent.md 类型和签名状态;proof 内部历史签名按证书指纹和签名时有效性验签;通过后只保存 pending 快照并将内容摘要/持久化回执提交 Auth。Auth 原子登记关系并写入状态 outbox,Name Service 消费激活状态后再更新对外快照和 ETag,owner 关系/注册 operation 才进入 `active`,不改变证书和基本登录通信状态。
|
|
268
|
+
7. **本地提交**:SDK 在收到 active/成功上传结果后将关系和注册 operation 标记为完成;证书签发后已有的登录通信能力不依赖这一步。进程崩溃时根据 operation_id 查询状态并从证书/证明阶段恢复。
|
|
269
|
+
|
|
270
|
+
### 5.4 外部 owner 的远端审批
|
|
271
|
+
|
|
272
|
+
创建者不应持有或上传 owner 私钥。服务端保存 pending operation,但不要求双方同时在线:
|
|
273
|
+
|
|
274
|
+
1. subject SDK 创建 `operation_id`,取得服务端冻结的 canonical statement;
|
|
275
|
+
2. subject SDK 先签自己的 statement,签名请求包含 request_id、proof_id、statement 原文、双方 AID 和 subject 签名;
|
|
276
|
+
3. owner 在线时,owner SDK 从 pending inbox 取请求;离线时,owner 在本地导入文件或二维码请求包。owner SDK 验证 statement、目标 AID、有效期和 subject 签名后,用 owner 私钥生成 `owner_signature`;
|
|
277
|
+
4. owner SDK 在应用确认后返回自己的 statement 与签名,接收方确认双方 AID/proof 匹配并验证签名;
|
|
278
|
+
5. subject SDK 验证 owner 回执与原请求完全匹配,组装 `ownership_proof`,签署并上传 agent.md,最后完成 commit。
|
|
279
|
+
|
|
280
|
+
服务端可接受任意一方转交的 owner 签名回执,但必须重新验证 owner 证书、owner agent.md 类型、同一 canonical statement、operation 状态和过期时间;“提交回执”不等于 owner 在线。拒绝、超时和撤回都应使 operation 失效;旧 statement 不可再次用于另一 operation。
|
|
281
|
+
|
|
282
|
+
## 6. 自主 agent 流程
|
|
283
|
+
|
|
284
|
+
`agent` 可以设置 `owner` 等于自身 AID:
|
|
285
|
+
|
|
286
|
+
- self-owner(由 `owner == aid` 推导);
|
|
287
|
+
- 只验证 subject AID 的公钥、证书和 subject agent.md;
|
|
288
|
+
- 不下载自身 agent.md 作为“owner agent.md”再次验证;
|
|
289
|
+
- 不允许把 self-owner 规则扩展到 device、service、group 等类型;
|
|
290
|
+
- 仍然产生 proof_id 和 subject 自签名 proof,便于服务端记录明确的自主状态;
|
|
291
|
+
- 后续转为外部 owner 时必须走换 owner 流程,而不是直接改字段。
|
|
292
|
+
|
|
293
|
+
## 7. 换 owner 编排流程
|
|
294
|
+
|
|
295
|
+
### 7.1 必须签名的主体
|
|
296
|
+
|
|
297
|
+
外部 owner 转移必须要求三方授权,但不是三方签署同一声明:old owner 发起并签署指定目标的转移授权,subject 与 new owner 对新关系事实独立双签。
|
|
298
|
+
|
|
299
|
+
- **old owner**:必须是 Auth 台账中的当前 owner;由其发起操作并签署绑定 subject、指定 new owner、当前 relation version、operation nonce 和有效期的转移授权;
|
|
300
|
+
- **subject AID**:确认新的 owner 关系;
|
|
301
|
+
- **new owner**:接受成为 owner。
|
|
302
|
+
|
|
303
|
+
三方是不同主体时不得由服务端代签。自主 agent 转给外部 owner 时,old owner 和 subject 是同一 AID,仍需该 AID 的 subject/old-owner 证明和 new owner 接受证明。
|
|
304
|
+
|
|
305
|
+
### 7.2 准备和提交
|
|
306
|
+
|
|
307
|
+
1. 只有 Auth 台账中的 active owner 可以调用 `owner_change_prepare(subject_aid, new_owner_aid, expected_relation_version, idempotency_key)`;self-owner 时 subject 与 current owner 是同一 AID,允许该主体按 current owner 身份发起;其它 subject 或 new owner 发起必须拒绝。Auth 对每个 subject 只允许一个未完成的转移 operation。
|
|
308
|
+
2. Auth 锁定当前 active proof/version,生成唯一 `operation_id`、`new_proof_id`、服务端一次性 `challenge_nonce` 和 `expires_at`,并校验 new owner agent.md 已验证且类型为 human/agent。
|
|
309
|
+
3. Auth 返回冻结的 owner-transfer challenge。old owner 对绑定 subject AID、old owner AID、指定 new owner AID、当前 relation version、operation ID、服务端 `challenge_nonce` 和 `expires_at` 的转移授权独立签名。nonce/有效期由 Auth 生成并纳入授权,不能由客户端自报或复用;该授权不同于 ownership relation statement。
|
|
310
|
+
4. Auth 验证 old owner 转移授权后,subject 对包含 subject AID、new owner AID 和唯一 proof ID 的最小新关系 statement 签名;new owner 对完全相同的字节独立签名。各签名均 detached,异步 inbox/离线文件流程一致,不签整个 agent.md。
|
|
311
|
+
5. subject SDK 验证 subject/new owner 对新关系 statement 的两份签名,生成新的 `ownership_proof`,更新 agent.md 并用 subject 当前 `active_signing` 证书重新签署完整文件;`group`/`org` 文件主体使用对应 identity 证书。subject 不能用自己的签名替代 old owner 转移授权。
|
|
312
|
+
6. `owner_change_submit` 分批提交 old owner 转移授权、新关系双签和新 agent.md 发布材料;Auth 持久化签名并在未齐全时保持 pending。
|
|
313
|
+
7. `owner_change_activate` 在同一事务中验证当前 owner 仍匹配、relation version/operation 未变化、所有签名有效、new owner 仍满足规则且 agent.md 与新 proof 一致;随后旧 proof 标记 `superseded`,新 proof 标记 `active`,更新唯一 owner 关系快照、agent.md/ETag 和审计记录,relation version 加一,并发出 `aid.owner_changed` 事件。第二个 pending operation、并发 CAS、重放或普通 PUT 绕过均拒绝。
|
|
314
|
+
|
|
315
|
+
### 7.3 并发、失败和恢复
|
|
316
|
+
|
|
317
|
+
- 同一 subject 已有 pending 转移时,新的不同 operation 返回 `pending_operation_exists`;幂等重试返回原 operation。并发 CAS 确保每个 subject 最多一个 active owner;
|
|
318
|
+
- operation 超时、任一签名拒绝或新 owner agent.md 无效时,不改变当前 active owner;
|
|
319
|
+
- commit 成功但 SDK 崩溃时,SDK 用 operation_id 查询并重建本地缓存;
|
|
320
|
+
- 不能把旧 proof 重新用于另一个 new owner;proof_id、operation_id 和 relation version 都必须唯一;
|
|
321
|
+
- old owner 发起并签署授权后可离线;subject/new owner 不要求同时在线,离线签名回执必须绑定对应 transfer operation、唯一 proof ID/relation version 和有效期;
|
|
322
|
+
- 解绑经 Auth 进入 `unbound`;非 human AID 也可以处于该关系状态。若自主 agent 需要建立自主关系,可另走 self-owner 流程;不允许通过普通 PUT 绕过 Auth 清空或改写 owner。
|
|
323
|
+
|
|
324
|
+
### 7.4 从属备份目录的生命周期
|
|
325
|
+
|
|
326
|
+
关系创建、换 owner 和撤销都必须驱动 owner-side subject storage 的生命周期操作:
|
|
327
|
+
|
|
328
|
+
1. **创建关系**:关系证明完成后,关系编排器以幂等方式创建 `<owner_aid>:/.aun/subjects/<subject_aid>/`,写入受保护目录标记,并建立只面向该 subject 的内部 `rw` ACL。目录创建和 ACL 建立成功前,关系返回 `backup_namespace_status=pending`,subject 不得写入;服务端通过 durable operation/outbox 重试,不要求 owner 在线。
|
|
329
|
+
2. **目录可用**:Storage 返回 `ready` 后,关系元数据记录 `backup_namespace_path`、bucket、ACL 版本和 proof/relation version;subject 只能访问自己的固定路径,不能用任意 `owner_aid` 或路径别名绕过关系检查。
|
|
330
|
+
3. **撤销关系**:关系进入 `unbound`、`unusable`、`revoked`、`superseded`、`expired` 或其它非 active 终态时,服务端先撤销该关系 ACL,并使该关系下发的访问票据/分享能力失效;随后保留目录及全部数据,不执行递归删除、对象 GC、改名或转移。即使 ACL outbox 暂未完成,reserved namespace 鉴权也必须立即按 active relation 拒绝 subject 访问。撤销操作必须幂等,重复撤销返回同一终态。
|
|
331
|
+
4. **换 owner**:旧 owner 下的目录只撤销 subject ACL,数据留在旧 owner Storage;新 owner 下创建一个新的同构目录并授予 subject `rw`。不自动跨 owner 复制旧备份,避免未经明确授权把关键材料转移给新 owner;如需迁移,另行设计显式的多方批准和数据复制流程。
|
|
332
|
+
|
|
333
|
+
关系 ACL 是服务端管理的保留授权,不允许 subject 通过普通 `storage.set_acl`、`storage.remove_acl` 或其它路径操作自行恢复已撤销权限。目录数据保留不等于访问保留:Storage 必须在 reserved namespace 鉴权时检查服务端已验证的关系授权状态;Auth 验证并提交关系状态变更,普通访问使用已验证 ACL,不要求逐次查询 Auth。需要确认最新撤销状态的场景另按状态分发/新鲜度契约处理。
|
|
334
|
+
|
|
335
|
+
路径按 `owner_aid + subject_aid` 唯一,而不是按 `proof_id` 或每个 relation version 创建新目录。同一对 AID 以后重新建立关系时可以复用原目录,但必须先完成新的 proof/active relation,再重新建立 ACL 并递增 `acl_generation`;在此之前目录数据保持保留但不可由 subject 访问。若换 owner,旧 owner 和新 owner 的路径天然不同,旧目录数据不自动复制到新 owner。
|
|
336
|
+
|
|
337
|
+
## 8. 服务端数据和校验边界
|
|
338
|
+
|
|
339
|
+
关系唯一性检查按以下矩阵执行;检查必须锁定同一 subject 的 Auth 台账记录并与状态写入处于同一事务/CAS:
|
|
340
|
+
|
|
341
|
+
| 入口 | 必须检查 | 允许结果 |
|
|
342
|
+
| --- | --- | --- |
|
|
343
|
+
| 绑定 `prepare` | subject 是否已有 active proof、未完成 pending operation;type/owner 是否符合矩阵 | 无未解除关系时创建 pending;完全相同的幂等键/proof 返回原 operation;不同 owner/proof/operation 返回关系冲突 |
|
|
344
|
+
| 绑定 `commit` | operation、proof、statement、签名和当前 subject 记录是否一致;是否出现并发 active/pending | 验证通过后只激活当前 operation;重复提交返回原结果;其它 operation 拒绝 |
|
|
345
|
+
| pending `agent.md` 激活 | 一次性凭据是否绑定同一 AID、operation、proof 和 owner;台账是否仍为该 pending | 只保存不可见 pending 快照;关系检查通过后才能转 active;缺省或改写关系字段拒绝 |
|
|
346
|
+
| 普通 `agent.md` 更新 | 当前 active proof 是否与文件中的 owner/proof 完全相同 | 只更新展示内容,不创建关系;缺 proof、换 owner 或伪造新 proof 转专用关系错误 |
|
|
347
|
+
| `owner_change_prepare` | 调用者是否为当前 active owner;subject 是否已有其它 pending;expected relation version 是否匹配 | 创建唯一转移 operation;同一幂等请求返回原 operation;其它请求返回 pending/version conflict |
|
|
348
|
+
| `owner_change_submit` | old owner 转移授权、新关系签名、当前 owner/proof/version 和 operation 是否仍有效 | 持久化分批签名;未齐全时保持 pending,重复提交幂等 |
|
|
349
|
+
| `owner_change_activate` | operation、pending agent.md、Name Service 回执和当前 owner/proof/version | 同一事务 CAS 废止旧 proof、激活新 proof;并发或旧版本只允许一个成功 |
|
|
350
|
+
| 终态关系后重新绑定 | 原记录是否已为 `superseded`、`revoked`、`expired` 或 `cancelled` | 终态不再阻塞新关系,但必须使用新的 proof/version;不得复用旧 proof |
|
|
351
|
+
|
|
352
|
+
因此,“提交 `agent.md`”与“绑定 owner”都要检查是否存在未解除关系,但两者语义不同:绑定/换绑是在检查通过后写入关系;普通内容更新只确认文件仍指向当前 active proof,不会借 PUT 创建第二条关系。SDK、Name Service 或客户端自报的“已验证”标记不能替代这次 Auth 台账检查。
|
|
353
|
+
|
|
354
|
+
服务端至少需要维护:
|
|
355
|
+
|
|
356
|
+
```text
|
|
357
|
+
aid_registry
|
|
358
|
+
aid, type, owner_aid, ownership_mode, relation_version,
|
|
359
|
+
active_proof_id, state, agent_md_etag, backup_namespace_status,
|
|
360
|
+
backup_namespace_path, backup_namespace_acl_version, created_at, updated_at
|
|
361
|
+
|
|
362
|
+
ownership_proofs
|
|
363
|
+
proof_id, statement_bytes, subject_signature, owner_signature?,
|
|
364
|
+
status, issued_at, superseded_by, revoked_at, audit metadata
|
|
365
|
+
|
|
366
|
+
aid_operations
|
|
367
|
+
operation_id, kind, idempotency_key, subject_aid, expected_version,
|
|
368
|
+
state, expires_at, subject request, collected detached signatures
|
|
369
|
+
|
|
370
|
+
relation_backup_namespaces
|
|
371
|
+
owner_aid, subject_aid, relation_version, proof_id,
|
|
372
|
+
bucket, path, acl_version, status, revoked_at, retained_until,
|
|
373
|
+
created_at, updated_at
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
`PUT /agent.md` 只能更新内容快照,不得更新 `aid_registry.owner_aid`、`type` 或 active proof。服务端验收顺序建议为:
|
|
377
|
+
|
|
378
|
+
1. 请求身份、Host、Bearer 和目标 AID 一致;
|
|
379
|
+
2. UTF-8、大小、frontmatter 和尾部 agent.md 签名;写链路必须使用 `active_signing`,只读 proof/历史文件验签按签名中的证书指纹定位证书并按签名时有效性判断;
|
|
380
|
+
3. agent.md 的 `aid/type/owner` 与注册表一致;
|
|
381
|
+
4. proof 字段与 active proof 的 canonical statement、proof_id 和 relation version 一致;
|
|
382
|
+
5. 外部 owner 的证书和已签名 agent.md 有效,且 owner type 为 human/agent;self-owner 跳过 owner agent.md 回源;group/org subject 文件必须分别使用 group/org identity 证书;
|
|
383
|
+
6. 对 `/.aun/subjects/<subject_aid>/` 的读写请求,检查请求 AID 是 owner 或该目录 ACL 中的 subject,并检查服务端维护的关系版本、proof 状态和保留命名空间 ACL;普通访问不要求逐次调用 Auth;
|
|
384
|
+
7. 全部通过后再写数据库、缓存和 ETag。关系撤销必须先由 Auth 验证并提交,再通过同一事务/outbox 更新 ACL、状态版本和相关票据;各服务如何在关系状态更新到达前处理缓存及访问凭据,按新鲜度契约冻结。数据删除不属于撤销副作用。
|
|
385
|
+
|
|
386
|
+
服务端必须拒绝仅凭 frontmatter `owner`、仅凭调用连接身份或仅凭 SDK 返回的“已验证”布尔值建立关系。
|
|
387
|
+
|
|
388
|
+
服务依赖固定为 CA -> Auth -> Name Service;Auth 不调用 Name Service。Name Service 发布或查询遇到尚未登记的 AID 时允许懒注册,返回 `registered=false` 与 `unbound`/`legacy_unbound`,而不是把未知身份当作服务不可用;只有需要 owner verified 的写入才返回 `owner_not_verified`。
|
|
389
|
+
|
|
390
|
+
## 9. SDK 调整范围
|
|
391
|
+
|
|
392
|
+
### 9.1 AIDStore / AID 高层能力
|
|
393
|
+
|
|
394
|
+
四端 SDK 都需要对齐以下能力:
|
|
395
|
+
|
|
396
|
+
- `register/create` 接收 `type`、`owner`、agent.md 和幂等键;
|
|
397
|
+
- `prepare/approve/commit` 的 pending operation 和崩溃恢复;
|
|
398
|
+
- canonical owner statement 生成/验签;
|
|
399
|
+
- `signOwnershipProof` / `verifyOwnershipProof`;
|
|
400
|
+
- `changeOwner`、owner 远端审批和状态查询;
|
|
401
|
+
- owner 签名请求/回执的导出、导入和 pending inbox 传递;
|
|
402
|
+
- delegated 关系的 `backupNamespace` 状态查询、固定路径访问和撤销后的数据保留语义;
|
|
403
|
+
- `resolve` 返回 `type`、`owner`、`ownership_status`、`proof_id`、`relation_version`;
|
|
404
|
+
- agent.md 普通内容更新只重新签 subject 文件,不重新请求 owner 签名;
|
|
405
|
+
- 新增结构化错误码和 relation version conflict 处理。
|
|
406
|
+
|
|
407
|
+
Python、TypeScript、JavaScript 和 Go 必须共享同一组 canonical statement 测试向量,不能各自拼接 JSON。
|
|
408
|
+
|
|
409
|
+
### 9.2 本地存储
|
|
410
|
+
|
|
411
|
+
现有 pending identity 机制扩展保存 `operation_id`、type、owner、proof、relation version 和 agent.md 上传状态。私钥仍只保存在 subject/owner 各自的 keystore 中;SDK 不接收或转存远端 owner 私钥。
|
|
412
|
+
|
|
413
|
+
## 10. 兼容和绑定
|
|
414
|
+
|
|
415
|
+
### 10.1 旧 AID
|
|
416
|
+
|
|
417
|
+
- 旧 `auth.create_aid(aid, public_key)` 继续可用一段兼容期,创建结果标记 `legacy_unbound`;
|
|
418
|
+
- 旧 `auth.create_aid` 保留原证书签发、登录和基本通信语义,不把证书标记为 pending;`legacy_unbound` 只表示没有经 Auth 登记的 owner 关系。
|
|
419
|
+
- 旧 agent.md 无 owner 字段可以读取和缓存,但验签结果应额外暴露 `ownership_status=legacy_unbound`;
|
|
420
|
+
- 旧 AID 若要登记 `type` 和 owner 关系,走一次显式 `aid_bind` 编排;该 operation 只建立绑定,不改变 AID、密钥、证书或登录通信身份。
|
|
421
|
+
- 旧 AID 缺少 `type` 时,绑定请求必须明确提交 `type`;旧 AID 缺少 owner 时,非 `human` 必须明确提交 `owner`,`agent` 可以提交自身 AID 表示 self-owner,`human` 不得提交 owner。Auth 不根据 AID 名称、证书 CN、旧 agent.md 文本或客户端配置推断缺失值。
|
|
422
|
+
- 如果旧登记中已有 `type` 或 owner,绑定请求只能写入缺失项或提交完全相同的值;试图借绑定改变已登记的 `type`/owner 必须转入对应的 type-change 或换 owner 流程。
|
|
423
|
+
- 绑定 operation 未完成、过期、取消或失败时,AID 仍保持原有证书和基本登录、Gateway 连接、消息通信能力;应用层根据 `legacy_unbound`/`pending` 状态限制需要已验证 owner 的场景。
|
|
424
|
+
- 不从历史聊天、证书 CN 或客户端配置自动推断 owner;
|
|
425
|
+
- 新 SDK 默认不创建 legacy 状态,除非调用方显式选择兼容模式。
|
|
426
|
+
|
|
427
|
+
#### 10.1.1 旧 AID 绑定流程
|
|
428
|
+
|
|
429
|
+
1. subject SDK 读取 Auth 的 AID 元数据和当前 agent.md,确认是否为 `legacy_unbound`;本地校验输入 `type`、owner、self-owner 规则和现有 AID 签名。读取失败不改变现有登录通信能力。
|
|
430
|
+
2. SDK 调用 `auth.aid_bind_prepare`。Auth 在同一事务中检查 AID 存在、证书有效、当前没有未完成绑定/换 owner operation,并将显式 `type`/owner 与已有登记做缺失项写入或一致性校验;成功后生成唯一 `operation_id`、必要时生成 `proof_id` 和冻结 statement。绑定不重新签发证书。
|
|
431
|
+
3. `human` 只登记 type,不生成 owner proof;`agent` self-owner 由 subject 单签;外部 owner 由 subject 和 owner 对同一 statement 独立签名。双方可在线或离线交换,签名包不包含任何私钥。
|
|
432
|
+
4. SDK 通过 `auth.aid_bind_submit` 分批提交所需签名。Auth 重算 canonical bytes/hash,验证证书主体、签名和 operation 有效期;部分签名只保留 pending,不改变当前关系。
|
|
433
|
+
5. subject SDK 将明确的 `type`、可选 owner 和 Auth 返回的 proof 写入新的 agent.md,并用 subject 当前 `active_signing` 证书重新签署文件;`group`/`org` 文件主体使用对应 identity 证书。旧 AID 的展示内容、AID 和密钥保持不变。
|
|
434
|
+
6. SDK 使用绑定 operation 的一次性发布凭据上传 agent.md。Name Service 只接受与 operation、AID、type、owner/proof 完全匹配的快照;Auth 通过 `auth.aid_bind_activate` 原子登记元数据/关系、签发 receipt,并发布状态事件。
|
|
435
|
+
7. SDK 持久化 operation 和 receipt;崩溃后用 `auth.aid_bind_status` 查询并恢复。绑定成功后状态为 `not_applicable`(human)或 `active`(有 owner proof);失败保持 `legacy_unbound`,不吊销证书。
|
|
436
|
+
|
|
437
|
+
#### 10.1.2 SDK Facade
|
|
438
|
+
|
|
439
|
+
四端 SDK 对外提供同一组语义入口,语言命名按既有风格映射:
|
|
440
|
+
|
|
441
|
+
| Facade | 作用 |
|
|
442
|
+
| --- | --- |
|
|
443
|
+
| `bindAid({ aid, type, owner?, agentMd?, idempotencyKey? })` | 为已有 AID 登记缺失的 type/owner,编排 prepare、签名、agent.md 发布和恢复;不创建新 AID、不更换已登记 owner |
|
|
444
|
+
| `getAidBindingStatus(aid)` | 返回 certificate/AID 生命周期、`owner_relation_status`、type/owner、operation 和 capability 状态;不把关系状态当作登录准入 |
|
|
445
|
+
| `resumeAidBinding(operationId)` | 进程重启后查询并继续原绑定 operation,幂等复用 proof/凭据 |
|
|
446
|
+
| `createBindingRequest(operationId)` / `acceptBindingRequest(request)` | 外部 owner 离线签名包导出/导入;只传 statement、hash、签名和证书引用 |
|
|
447
|
+
| `verifyAgentMdOwnership(agentMd)` | 本地独立验证公开 proof;需要判断当前 active 时再使用 Auth 状态 |
|
|
448
|
+
|
|
449
|
+
旧的低层 `createAid`/`auth.create_aid` Facade 保持原参数和返回语义;它不会隐式调用 `bindAid`,也不会因缺少 type/owner 阻断证书、登录或消息通信。新建 AID 仍使用 `register` 高层编排,不能用 `bindAid` 代替创建。
|
|
450
|
+
|
|
451
|
+
### 10.2 普通 agent.md 更新
|
|
452
|
+
|
|
453
|
+
只修改展示内容时允许继续使用当前 `PUT /agent.md`,但必须携带原 active proof;缺 proof、改 owner 或改 type 都转为专用关系变更错误,不自动降级。
|
|
454
|
+
|
|
455
|
+
## 11. 安全和审计要求
|
|
456
|
+
|
|
457
|
+
- 关系 statement 必须有域分隔符,防止与其它签名用途混用;
|
|
458
|
+
- prepare 返回的 statement 由服务端生成,SDK 不可自行改变字段顺序、数字或大小写后再签;
|
|
459
|
+
- owner、subject 和 new owner 的签名都按证书指纹回源,校验证书主体、链、用途、有效期和签名时间;
|
|
460
|
+
- proof 保存原始 canonical bytes 和签名,支持离线审计和跨语言复验;
|
|
461
|
+
- 证书自然过期不自动抹掉已经接受的历史 proof;owner 证书/profile 失效、key compromise、失联、丢失或疑似泄露时,关系报告为 `unusable`,本版不启动专门 recovery 或自动换绑;基本登录和通信仍按证书/AID 状态处理。
|
|
462
|
+
- owner 变更、proof supersede/revoke、agent.md relation mismatch 都写入不可变审计日志;
|
|
463
|
+
- 关系备份目录创建、ACL 授予、ACL 撤销、访问拒绝和数据保留都写入不可变审计日志;日志记录 owner、subject、relation/proof version、固定路径、ACL 版本和决定,但不记录备份材料内容;
|
|
464
|
+
- 大多数消息、群组和 Storage 场景可从公开可验证的 agent.md 读取 owner;确实要求最新/active 状态的 owner-sensitive 决策,才使用满足新鲜度要求的 Auth 已验证状态。未依赖目标 owner 关系的既有登录、通信和业务权限不因 owner 未绑定而整体关闭。不能信任未验签的 owner 文本或客户端自报关系。
|
|
465
|
+
|
|
466
|
+
## 12. RPC / HTTP 调整建议
|
|
467
|
+
|
|
468
|
+
以下名称是方案建议,最终名称需在协议评审后冻结:
|
|
469
|
+
|
|
470
|
+
| 接口 | 作用 |
|
|
471
|
+
| --- | --- |
|
|
472
|
+
| `auth.aid_register_prepare` | 预留 AID,校验 type/owner,生成 statement;返回正常可用证书和 operation |
|
|
473
|
+
| `auth.aid_register_submit` | 分批保存并验证 subject/owner detached 签名;同一 operation 幂等 |
|
|
474
|
+
| `auth.aid_register_activate`(服务间) | 校验 Name Service pending receipt,原子激活关系/快照;证书状态不随之切换 |
|
|
475
|
+
| `auth.aid_bind_prepare` | 为已存在的 legacy AID 建立显式 type/owner 绑定;只允许写入缺失值或提交与现有值一致的值,不重新签发证书 |
|
|
476
|
+
| `auth.aid_bind_submit` | 接收绑定所需的 subject/owner detached 签名,可分批、离线提交并幂等保存 |
|
|
477
|
+
| `auth.aid_bind_activate`(服务间) | 校验绑定 operation 对应的 agent.md 发布回执,在 Auth 事务中登记 type/owner/proof 并返回 receipt |
|
|
478
|
+
| `auth.aid_bind_status` | 查询 legacy/pending/not_applicable/active 等绑定状态,供 SDK 恢复;不改变基本登录通信准入 |
|
|
479
|
+
| `auth.owner_change_prepare` | 仅允许当前 owner 发起;锁定 proof/version 并生成绑定目标的转移 challenge;同一 subject 仅一个 pending operation |
|
|
480
|
+
| `auth.owner_change_submit` | 分批提交 old owner transfer authorization、subject/new owner 新关系签名 |
|
|
481
|
+
| `auth.owner_change_activate`(服务间) | Auth 原子提交关系/proof 并写 activation outbox;Name Service 只公开与 Auth active relation version 一致的 agent.md 快照/ETag |
|
|
482
|
+
| `auth.owner_relation_unbind` | Auth 原子解绑关系,进入 `unbound`,撤销 ACL/outbox 但不删除目录或数据;不限制基本登录通信 |
|
|
483
|
+
| `auth.aid_type_change` | Auth 在确认该 AID 不是其它 AID 的未解绑 owner 后更新 type,并提供 operation-bound agent.md 发布凭据 |
|
|
484
|
+
| `auth.aid_operation_get` | 查询 pending、成功、过期或冲突状态,支持 SDK 恢复 |
|
|
485
|
+
| `auth.owner_relation_status` | 返回当前 state、注册表 type、owner、proof 状态、relation version 和 receipt/新鲜度信息 |
|
|
486
|
+
| `storage.relation_backup_status` | 查询 delegated 关系备份目录的固定路径、状态、ACL 版本和数据保留标志;不返回目录内容 |
|
|
487
|
+
|
|
488
|
+
现有 `PUT /agent.md` 继续用于内容发布和缓存更新;关系创建、绑定、换 owner 不通过普通 PUT 完成。
|
|
489
|
+
|
|
490
|
+
## 13. 测试与验收矩阵
|
|
491
|
+
|
|
492
|
+
至少覆盖:
|
|
493
|
+
|
|
494
|
+
- 八种 type 的 owner 必填/省略策略;
|
|
495
|
+
- human 无 owner、agent self-owner、外部 owner;
|
|
496
|
+
- owner AID 不存在、证书无效、agent.md 未签名、type 非 human/agent;
|
|
497
|
+
- delegated 关系激活后自动创建固定 owner-side 备份目录、重复 prepare/commit 不重复创建目录且 ACL 建立幂等;
|
|
498
|
+
- subject 只能访问自己的 `<owner_aid>/.aun/subjects/<subject_aid>/` 及后代,不能枚举其它 subject 目录、修改 ACL、公开分享、签发 token 或挂载;
|
|
499
|
+
- 关系撤销撤 ACL、使已有票据失效但保留目录和数据;换 owner 不跨 owner 自动复制;同一对 AID 重建关系时须新 proof 后再恢复 ACL;
|
|
500
|
+
- AID/type/owner/proof 任一字段篡改;
|
|
501
|
+
- subject 与 owner 对不同 canonical statement 签名、签名无效、proof/version 不匹配、operation 过期或证明重放时必须拒绝;
|
|
502
|
+
- owner 只返回 detached 签名,subject 才能组装并签署 agent.md(`group`/`org` 文件主体使用对应 identity 证书);在线 pending inbox、离线文件/二维码导入导出得到相同验签结果;
|
|
503
|
+
- 修改 description/avatar/Markdown 只需 subject 重签,原 proof 仍有效;
|
|
504
|
+
- owner/type 修改必须进入关系编排,普通 PUT 被拒绝;
|
|
505
|
+
- owner 环检测、过期 statement、重复 proof_id、重复幂等键和 CAS 冲突;
|
|
506
|
+
- 三方换 owner 的拒绝、超时、并发和崩溃恢复;
|
|
507
|
+
- 证书轮换、自然过期、后来吊销但签名时有效的历史证书 proof 状态;新写入使用 `active_signing`,读链路按证书指纹验签并报告当前状态;
|
|
508
|
+
- Python/TypeScript/JavaScript/Go 共享 canonical statement 签名向量;
|
|
509
|
+
- 旧客户端 legacy_unbound 的读取、正常登录通信、owner-sensitive 降级和显式 `aid_bind`;新 SDK 在首次绑定完成前及 operation 失败后保持同样的基本能力。
|
|
510
|
+
|
|
511
|
+
## 14. 实施顺序
|
|
512
|
+
|
|
513
|
+
1. 冻结八种 type、owner 必填矩阵、self-owner 和 legacy 状态定义;
|
|
514
|
+
2. 冻结 `owner` / `ownership_proof` Schema 与 canonical statement 测试向量;
|
|
515
|
+
3. 服务端先实现 registry、proof ledger、prepare/commit、CAS、关系备份命名空间/ACL outbox 和审计;
|
|
516
|
+
4. Python SDK 实现高层编排和恢复,作为行为基准;
|
|
517
|
+
5. TypeScript、JavaScript、Go 对齐同一 wire contract 和签名向量;
|
|
518
|
+
6. 更新 agent.md Name Service 校验、resolve 返回值、事件和错误码;
|
|
519
|
+
7. 完成 legacy `aid_bind`、单域/双域和跨语言 E2E 后,再将新注册默认切换到强制关系流程;
|
|
520
|
+
8. 最后冻结正式协议和 SDK 手册,保留旧 `auth.create_aid` 兼容入口直到兼容窗口结束。
|
|
521
|
+
|
|
522
|
+
## 15. Phase 0 后的正式化工作
|
|
523
|
+
|
|
524
|
+
本方案中的业务策略已经按本轮确认收敛。进入实现前仍需完成以下协议化工作,但不得借此重新引入未确认的业务分支:
|
|
525
|
+
|
|
526
|
+
1. 把已确认的字段、状态、TTL、可见分号域分隔符、签名封套和 Storage 路径写入正式 Schema/RPC 文档;
|
|
527
|
+
2. 按既有 RPC 惯例冻结公开方法的参数、结果、错误码、事件和封套字段,并明确 `unbound`、`unusable`、`legacy_unbound`、`pending`、`active` 的报告格式;
|
|
528
|
+
3. 生成四 SDK 与 Name Service 共用的 canonical bytes、独立声明和签名互验正反例向量;
|
|
529
|
+
4. 将 type-change 的“仍是其它 AID 未解绑 owner 时拒绝、下属关系全部 `unbound` 后允许”、目录内部对象可删除/移动/重命名且 subject 根目录不可移动/删除、以及关系失效后不清理数据写入验收矩阵;
|
|
530
|
+
5. owner 失联、丢失或疑似泄露不启动专门 recovery;关系进入 `unusable` 后的基本登录通信和应用层降级行为只按本版状态契约实现。
|