@agentunion/fastaun-browser 0.5.19 → 0.5.20

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.
Files changed (114) hide show
  1. package/CHANGELOG.md +129 -78
  2. package/_packed_docs/CHANGELOG.md +129 -78
  3. package/_packed_docs/INDEX.md +201 -195
  4. package/_packed_docs/KITE_DOCS_GUIDE.md +93 -90
  5. package/_packed_docs/agent.md/SCHEMA.md +7 -7
  6. package/_packed_docs/agent.md//350/277/234/347/250/213agent.md/347/274/223/345/255/230/344/270/216etag/351/200/217/344/274/240/346/226/271/346/241/210.md +11 -11
  7. package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md +1072 -1072
  8. package/_packed_docs/protocol/10-Group-/345/255/220/345/215/217/350/256/256.md +676 -676
  9. package/_packed_docs/protocol/11-Storage-/345/255/220/345/215/217/350/256/256.md +8 -12
  10. package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/211.md +443 -0
  11. package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/2112.0.md +161 -0
  12. package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/2112.1.md +658 -0
  13. package/_packed_docs/protocol/Ownership/345/215/217/350/256/256/345/256/232/344/271/2113.0.md +233 -0
  14. package/_packed_docs/protocol/agent.md/SCHEMA.md +1 -1
  15. package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md +1 -1
  16. package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +67 -63
  17. package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md +1 -1
  18. package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +35 -8
  19. package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md +3 -3
  20. package/_packed_docs/sdk/09-group-rpc-manual.md +258 -254
  21. package/_packed_docs/sdk/09-message-rpc-manual.md +7 -4
  22. package/_packed_docs/sdk/09-storage-rpc-manual.md +18 -26
  23. package/_packed_docs/sdk/AUN_DOCS_GUIDE.md +61 -52
  24. package/_packed_docs/sdk/INDEX.md +92 -80
  25. package/_packed_docs/sdk/Ownership-SDK/345/256/236/347/216/260/346/214/207/345/215/227.md +169 -0
  26. package/_packed_docs/sdk/Ownership-SDK/347/274/226/346/216/222/346/214/207/345/215/227.md +349 -0
  27. package/_packed_docs/sdk/Ownership-SDK/347/274/226/346/216/222/346/214/207/345/215/2272.1.md +922 -0
  28. package/_packed_docs/sdk/Ownership-SDK/351/233/206/346/210/220/346/214/207/345/215/227.md +270 -0
  29. 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 +300 -0
  30. 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 +382 -0
  31. 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 -0
  32. package/_packed_docs/sdk/Ownership2.1/350/257/246/347/273/206/350/256/276/350/256/241.md +476 -0
  33. package/_packed_docs/sdk/Ownership/347/256/241/347/220/206/344/270/223/351/242/230.md +559 -0
  34. package/_packed_docs/sdk/ProtectedHeaders/347/224/250/346/263/225/344/270/223/351/242/230.md +299 -0
  35. 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 +173 -0
  36. 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 +211 -0
  37. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273SDK/345/256/236/347/216/260/347/247/273/346/244/215/346/214/207/345/215/227.md +331 -0
  38. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273SDK/351/233/206/346/210/220/346/214/207/345/215/227.md +207 -0
  39. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273/344/273/243/347/240/201/345/256/241/346/237/245/346/212/245/345/221/212.md +252 -0
  40. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273/345/256/236/346/226/275/350/256/241/345/210/222.md +156 -0
  41. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273/346/226/271/346/241/210.md +273 -0
  42. package/_packed_docs//350/267/250/350/256/276/345/244/207/345/267/262/350/257/273/346/234/252/350/257/273/350/257/246/347/273/206/350/256/276/350/256/241.md +211 -0
  43. package/dist/agent-md-schema.d.ts +15 -4
  44. package/dist/agent-md-schema.d.ts.map +1 -1
  45. package/dist/agent-md-schema.js +64 -30
  46. package/dist/agent-md-schema.js.map +1 -1
  47. package/dist/agent-md.d.ts +10 -2
  48. package/dist/agent-md.d.ts.map +1 -1
  49. package/dist/agent-md.js +278 -121
  50. package/dist/agent-md.js.map +1 -1
  51. package/dist/aid-store.d.ts +46 -0
  52. package/dist/aid-store.d.ts.map +1 -1
  53. package/dist/aid-store.js +149 -10
  54. package/dist/aid-store.js.map +1 -1
  55. package/dist/aid.d.ts +4 -1
  56. package/dist/aid.d.ts.map +1 -1
  57. package/dist/aid.js +23 -42
  58. package/dist/aid.js.map +1 -1
  59. package/dist/auth.d.ts +1 -1
  60. package/dist/auth.d.ts.map +1 -1
  61. package/dist/auth.js +85 -18
  62. package/dist/auth.js.map +1 -1
  63. package/dist/bundle.js +1581 -781
  64. package/dist/cert-utils.d.ts +49 -1
  65. package/dist/cert-utils.d.ts.map +1 -1
  66. package/dist/cert-utils.js +102 -56
  67. package/dist/cert-utils.js.map +1 -1
  68. package/dist/client/delivery.d.ts +7 -0
  69. package/dist/client/delivery.d.ts.map +1 -1
  70. package/dist/client/delivery.js +243 -28
  71. package/dist/client/delivery.js.map +1 -1
  72. package/dist/client/rpc-pipeline.d.ts.map +1 -1
  73. package/dist/client/rpc-pipeline.js +89 -77
  74. package/dist/client/rpc-pipeline.js.map +1 -1
  75. package/dist/client/v2-e2ee.d.ts.map +1 -1
  76. package/dist/client/v2-e2ee.js +99 -80
  77. package/dist/client/v2-e2ee.js.map +1 -1
  78. package/dist/client.d.ts.map +1 -1
  79. package/dist/client.js +31 -17
  80. package/dist/client.js.map +1 -1
  81. package/dist/crypto.d.ts.map +1 -1
  82. package/dist/crypto.js +8 -6
  83. package/dist/crypto.js.map +1 -1
  84. package/dist/events.d.ts +5 -2
  85. package/dist/events.d.ts.map +1 -1
  86. package/dist/events.js +33 -14
  87. package/dist/events.js.map +1 -1
  88. package/dist/facades.js +5 -5
  89. package/dist/facades.js.map +1 -1
  90. package/dist/index.d.ts +1 -1
  91. package/dist/index.d.ts.map +1 -1
  92. package/dist/index.js.map +1 -1
  93. package/dist/org-protocol.d.ts.map +1 -1
  94. package/dist/org-protocol.js +72 -12
  95. package/dist/org-protocol.js.map +1 -1
  96. package/dist/ownership-v21.d.ts +25 -8
  97. package/dist/ownership-v21.d.ts.map +1 -1
  98. package/dist/ownership-v21.js +142 -73
  99. package/dist/ownership-v21.js.map +1 -1
  100. package/dist/ownership-workflow.d.ts +6 -1
  101. package/dist/ownership-workflow.d.ts.map +1 -1
  102. package/dist/ownership-workflow.js +221 -58
  103. package/dist/ownership-workflow.js.map +1 -1
  104. package/dist/tools/cross-sdk-agent.d.ts +2 -1
  105. package/dist/tools/cross-sdk-agent.d.ts.map +1 -1
  106. package/dist/tools/cross-sdk-agent.js +91 -8
  107. package/dist/tools/cross-sdk-agent.js.map +1 -1
  108. package/dist/transport.d.ts +1 -0
  109. package/dist/transport.d.ts.map +1 -1
  110. package/dist/transport.js +2 -0
  111. package/dist/transport.js.map +1 -1
  112. package/dist/version.d.ts +1 -1
  113. package/dist/version.js +1 -1
  114. package/package.json +1 -1
@@ -0,0 +1,658 @@
1
+ # Ownership 协议定义 2.1
2
+
3
+ 本文完整定义 Ownership 2.1 的 AID 关系、双方声明、文件格式、owner 锁、解绑、转移及审计。读者无需同时查阅旧版协议。Ownership 是 `agent.md` 上可选的关系属性;关系状态只决定依赖 Ownership 验证的功能是否可用,不改变 `agent.md` 本身的有效性。关系为 `unbound`、`single_sided`、`released`、`invalid` 或 `unavailable` 时,只有依赖该关系的功能需要停止或降级;符合自身身份、格式和签名规则的 `agent.md` 仍可按普通名片读取、验证和使用。SDK 编排场景见 [Ownership SDK编排指南2.1](../sdk/Ownership-SDK编排指南2.1.md)。本文规定协议契约;当前工作区的实现、验收结果及剩余项见 [实施账本第 13 节](../sdk/Ownership2.1-TDD分阶段实施计划.md#13-2026-10-10-实施账本),不以协议定义代替实现验收。
4
+
5
+ 本协议的通用关系流程适用于 `human`、`group`、`org` 以外的主体;`human` 禁止声明 owner,`group/org` 作为被管理的 subject 时使用第 1.3 节的专属生命周期,也可按普通规则作为 `owner_aid`。通用关系双方独立签名、上传自己的声明文件;本协议不定义 ownership 专用授权 RPC 或权威关系控制方法,也不提供代签名、代上传及协议层申请、接受、拒绝方法。SDK 可以用普通加密 P2P 载荷进行非权威的本地编排;这些载荷不构成关系授权或 NS 提交事实,不能替代双方文件及服务端验收。可选托管由应用层实现,不改变这两个文件的签署及上传身份。
6
+
7
+ 兼容方向为新服务端保留旧 SDK 的既有身份认证、普通名片、通信和 legacy owner 操作入口;新 SDK 的 2.1 关系操作不兼容旧服务端。兼容旧 SDK 所需的注册、绑定、转移、查询和解绑 RPC 使用隔离的 Auth JSONL 状态及 NS `ownership_proof`,只处理 legacy 关系;它们不生成 2.1 双文件声明,不构成 2.1 授权、owner 锁、关系版本或 `consensus`,也不得覆盖已存现代声明。Ownership 2.1 当前关系始终重新核对两份当前文件;不把新 SDK 源码调用形态兼容作为本契约要求。
8
+
9
+ ## 1. 权威文档与 owner 锁
10
+
11
+ | 概念 | 定义 |
12
+ | --- | --- |
13
+ | `sub_aid` | 被管理的完整小写 AID。 |
14
+ | `owner_aid` | 声明管理关系的完整小写 AID。 |
15
+ | `new_owner`(`new_owner_aid`) | 原 owner 在转移授权中指定的新管理方,其 AID 为完整小写 AID;独立签署、上传自己的目标 `owner.md`。 |
16
+ | NS(nameservice,名称服务) | 在数据库中保存 sub_aid 的当前权威 `agent.md` 及 ETag,依据该文件与 owner 当前 `owner.md` 验证关系,负责名片发布验收及同步。owner_aid 只标识声明签署者的 AID/证书身份。 |
17
+ | Storage(存储) | 保存 owner 的当前权威 `owner.md` 及 sub_aid 的已验收 `agent.md` 副本,提供公开读取、下载和权威对象查询;`owner.md` 仅 owner_aid 可写入、删除。 |
18
+ | self-owner | `owner_aid == sub_aid`,同一 AID 同时承担管理方与被管理方角色。 |
19
+ | `agent.md` | sub_aid 在 NS 上的当前权威版本;由 sub_aid 自己签名、上传。 |
20
+ | `owner.md` | owner_aid 的 Storage 上的当前权威版本,路径为 `owner_aid:/sub_aids/{sub_aid}/owner.md`。 |
21
+ | 稳定关系 | 两份当前文档的 AID、关系版本和文件签名均匹配,owner 未发布 release。 |
22
+ | owner 锁 | 稳定关系成立后,NS 拒绝 sub_aid 通过普通 `agent.md` 上传清除、替换或破坏该关系。 |
23
+
24
+ owner 锁是对两份当前签名材料的验证结果,不是另行持久化的关系事实。原 owner 发布有效 `release`,或者其 Storage 确认当前 `owner.md` 已被删除,均视为解绑。原 owner 发布有效 `transfer_owner` 时,只允许转移到指定的新 owner。
25
+
26
+ `owner.md` 公开可读、可下载;只有 owner_aid 可以写入、删除,不授予任何第三方写删权限。
27
+
28
+ `agent.md` 经 NS 验收并持久保存后,由 NS 将完整原始签名文件同步到 sub_aid 的 Storage:`{sub_aid}:/agent.md`,保持原始字节及签名。该副本使用受限的可信 nameservice 内部 `storage.put_object` 完整原子写入入口,无需采用新客户端的 HTTP 上传会话;它只能写入本域 sub 的 `default/agent.md`,不获得 `owner.md` 写删权限,也不代签。寻址和文件操作遵循 [Storage/FS 协议](11-Storage-子协议.md);关系验收和 owner 权限校验以 NS 当前 `agent.md` 与 owner 当前 `owner.md` 共同决定。同步队列只记录副本投递状态,Storage 名片副本不是 2.1 关系事实来源。
29
+
30
+ ### 1.1 self-owner
31
+
32
+ self-owner 仍使用双文件:`agent.md` 的 `owner` 等于自己的 `aid`,两份 statement 的 `owner_aid`、`sub_aid` 均为该 AID。`owner.md` 使用该 AID 自有 Storage 的规范路径;两份文件分别签署、提交。
33
+
34
+ NS 同样核验双文件、签名、路径和关系版本。稳定后为 `locked`,锁定的 owner 是 sub_aid,不增加 self-owner 字段、锁状态或 RPC。`human` 不能声明 owner,包括 self-owner。
35
+
36
+ self-owner 表示自主管理;省略 `owner`、`ownership` 表示未声明 owner。完整文件示例见第 4.5 节。
37
+
38
+ ### 1.2 owner.md 的发布和访问约束
39
+
40
+ Storage 必须原子发布完整 `owner.md`:读取者只能看到完整旧版本或完整新版本。更新声明、发布 release、发布或撤回转移授权均不得先删除旧文件再创建新文件;写入失败保留旧版本,避免中间的真实不存在被 NS 判定为解绑。
41
+
42
+ `agent.md` 发布保留原 ETag 条件:已有文件使用 `If-Match`,首次创建使用 `If-None-Match: *`。owner 发布前重新核对当前完整 `owner.md` 原文、摘要和存在性,使用规范上传会话原子写入完整文件,不先删除再创建;HTTP PUT 使用 create 返回的会话 URL,complete 携带同一 `session_id`,create/complete 沿用同一既有 `expected_version` 发布条件,不增加 Storage 路径修订或哈希条件接口。
43
+
44
+ 协议客户端发起删除前重新核对当前 NS `agent.md` 及本任务保存的 owner 完整原件;目标原文、摘要或当前关系已变化时停止旧清理。owner_aid 经其它存储入口执行的真实删除仍按第 4.2 节确认解绑。
45
+
46
+ Storage 须在文件、父目录、移动、重命名及自动清理等所有能改变规范路径对象的入口执行 owner 限制;ACL、token 或目录授权不得赋予第三方修改、删除 `owner.md` 的能力。
47
+
48
+ 旧文件清理须重新核对 NS 当前 `agent.md`、owner 当前 `owner.md` 及本任务原件;不删除已观察到的后续声明。sub 清理前保留当前 release,清理后的处理见第 4.2 节。Storage 无需新增关系终局记录。
49
+
50
+ ### 1.3 Group/Org 的专属 owner 生命周期
51
+
52
+ `type=group/org` 的 owner 是 Group/Org 服务的当前权威生命周期事实,创建时自动建立,解散时自动解除。它不由双方 Ownership 2.1 声明建立,不创建 `owner.md`、owner 锁、`relation_version`、通用编排任务或审批消息。通用绑定、释放、转移入口须在创建任务和写入文件之前直接返回 `not_applicable`、`retryable=false`,不自动调用其它生命周期方法;通用共识检查的 `status/code` 均为 `not_applicable`。本节排除仅针对 Group/Org 作为被管理的 subject/sub_aid;它们仍可按既有普通 owner 规则作为普通主体的 owner 参与关系,不扩大或改变 owner 类型规则。
53
+
54
+ Group 使用 `group.transfer_owner` → `group.complete_transfer` 的两阶段转移;Org 使用既有 `org.lifecycle.transfer` → `org.lifecycle.transferAccept`。两者都必须真正 rekey,使证书及公钥指纹变化,旧身份材料不再授权当前操作,新材料归新 owner 持有;Org 的 rekey 与 owner CAS 顺序保持其专属 0.8 契约。创建时实体身份公私钥及证书由初始 owner 持有,业务服务不保存实体私钥。解散后不再存在可用 owner 授权,旧身份材料和待上传文件不能继续鉴权或发布名片。
55
+
56
+ 新 SDK 发布的 Group/Org 名片必须含当前 `owner`,必须省略 `ownership`、`ownership_proof`、`ownership_release`。实体私钥生成主签,当前 owner 使用本人 token 上传,可选追加 owner 附签;Group 旧实体单签及实体身份上传持续兼容,Org 不开放该旧入口,见第 2.5 节。实体类型和当前 owner 必须以权威身份及生命周期记录校验,不能只相信上传文件中的 `type/owner`,也不能通过改类型绕过已有普通 Ownership 锁。
57
+
58
+ ## 2. 声明与文件签名
59
+
60
+ ### 2.1 文件容器与身份字段
61
+
62
+ 两份文件均由 YAML frontmatter、可选 Markdown 正文和连续一个或多个尾部文件签名块组成。frontmatter 前后使用独占一行的 `---`;签名之前的内容必须以换行结束。
63
+
64
+ | 项目 | 要求 |
65
+ | --- | --- |
66
+ | 编码 | UTF-8;按原始字节签名,不转换换行、空白或 Unicode 表示。 |
67
+ | payload | frontmatter、分隔符及 Markdown 正文合计最多 4096 字节。 |
68
+ | 尾部签名区 | 从第一块开始至文件结尾合计最多 2048 字节,含全部块、分隔和尾部空白;块间及末块后只允许空白。 |
69
+ | YAML 解析 | 顶层为 mapping;重复键、未知 ownership 字段、YAML 自定义 tag、锚点和别名必须拒绝。 |
70
+ | 通用 `agent.md` 身份 | frontmatter 的 `aid`、目标 AID、认证上传者和文件签名证书所属 AID 必须一致;Group/Org 见第 2.5 节。 |
71
+ | `owner.md` 身份 | 文件路径所属 owner、顶层 `owner_aid` 和文件签名证书所属 AID 必须一致。 |
72
+
73
+ `agent.md` 的核心字段如下;其它业务 frontmatter 和 Markdown 正文可以保留,不参与 owner 身份的选择:
74
+
75
+ | 字段 | 类型及要求 |
76
+ | --- | --- |
77
+ | `aid` | 必填字符串,当前 sub_aid 的完整小写 AID。 |
78
+ | `name` | 必填非空字符串。 |
79
+ | `type` | 必填非空字符串;允许应用扩展。预设值为 `human`、`agent`、`group`、`service`、`device`、`host`、`org`、`custom`。 |
80
+ | `version` | 必填字符串,格式为 `MAJOR.MINOR.PATCH`;这是名片版本,独立于协议及关系版本。 |
81
+ | `exttype` | 可选字符串,描述当前 type 的具体形态。 |
82
+ | `description` | 可选字符串,最多 100 个 Unicode 字符。 |
83
+ | `avatar` | 可选字符串,最多 256 个 Unicode 字符。 |
84
+ | `tags` | 可选字符串数组。 |
85
+ | `owner` | 通用主体可选字符串,出现时必须同时出现 `ownership`;Group/Org 必填当前 owner AID,独立存在合法。 |
86
+ | `ownership` | 通用主体可选对象,只允许包含 `statement`;Group/Org 禁止。 |
87
+
88
+ `owner.md` 的顶层只允许 `owner_aid`、`sub_aid`、`ownership`,三者均必填;不要求 `aid`、`name`、`type` 或名片版本字段。其 AID 必须与 statement 及规范路径一致。文件角色由资源位置确定,不能改用另一角色的规则接受不匹配文件。
89
+
90
+ 字段类型必须严格校验;`name`、`type` 不能只有空白,不得通过数字或字符串强制转换绕过类型要求。
91
+
92
+ ### 2.2 公共声明
93
+
94
+ 双方使用以下完整 `ownership.statement`:
95
+
96
+ ```yaml
97
+ statement:
98
+ version: 2
99
+ declaration_id: 550e8400-e29b-41d4-a716-446655440000
100
+ owner_aid: owner.agentid.pub
101
+ sub_aid: subject.agentid.pub
102
+ relation_version: 1
103
+ declared_at: 1791523200
104
+ ```
105
+
106
+ `version: 2` 是声明容器版本;2.1 通过必填的 `relation_version` 和 NS 的协议能力标识区分。两方的 `declaration_id`、`declared_at` 可以不同,其余关系字段必须一致。statement 中所有字段均必填,不允许增加独立签名或其它字段。
107
+
108
+ | 字段 | 要求 |
109
+ | --- | --- |
110
+ | `version` | 固定为整数 `2`。 |
111
+ | `declaration_id` | 本份声明的小写 UUID v4。 |
112
+ | `owner_aid`、`sub_aid` | 完整小写 AID,与文件位置及声明角色一致。 |
113
+ | `relation_version` | `1..9007199254740991` 的整数,只用于两份当前签名声明的匹配;由双方在声明中明确一致取值,SDK 默认取当前可见基数加一(无声明时为 `1`),转移目标使用当前匹配版本加一。NS 不单独维护版本上界。 |
114
+ | `declared_at` | 被文件签名覆盖的 Unix 秒整数,范围 `1..9007199254740991`。 |
115
+
116
+ 通用主体的 `agent.md` 出现 `owner` 时必须同时出现 `ownership.statement`;`owner` 等于声明中的 `owner_aid`,`aid` 等于 `sub_aid`。无 owner 时两者同时省略;`human` 类型不能声明这两个字段。Group/Org 的 owner 字段按第 1.3、2.5 节处理,不解释为本节声明。
117
+
118
+ 普通正文、名称等更新必须完整保留已锁定的 `owner` 和 `ownership.statement`。不能只保留 owner 字符串、删除声明,也不能将完整关系降级为单方声明。
119
+
120
+ ### 2.3 owner 的动作
121
+
122
+ `owner.md` 的 `ownership` 必须包含 `statement` 和 `action`;仅 `transfer_owner` 允许且要求包含 `transfer`:
123
+
124
+ | `action` | 含义 |
125
+ | --- | --- |
126
+ | `declare` | 声明管理当前关系版本的 sub_aid。 |
127
+ | `release` | 释放 statement 指定的当前关系版本。 |
128
+ | `transfer_owner` | 保留当前关系,同时授权转移到指定新 owner。 |
129
+
130
+ release 的 statement 指向被释放关系,owner_aid、sub_aid、relation_version 必须保持该关系的值。完整文件 YAML 见第 4.2 节。sub_aid 不能在自己的 `agent.md` 中加入 action 来授权解绑或转移。
131
+
132
+ 转移时,原 owner 的 `ownership.transfer` 必须且只能包含以下字段:
133
+
134
+ | 字段 | 要求 |
135
+ | --- | --- |
136
+ | `new_owner_aid` | 必填完整小写 AID,必须与当前 owner 不同。 |
137
+ | `target_relation_version` | 必填整数,固定为当前关系版本加一。 |
138
+ | `expires_at` | 必填 Unix 秒整数,范围 `1..9007199254740991`;NS 验收时必须尚未过期。 |
139
+
140
+ 转移授权绑定 statement 指定的当前关系、目标 owner、目标关系版本及有效期。原 owner 可独立签署、发布授权,无需预先取得另外两方的目标文件。授权到期只禁止执行转移,不释放 statement 中的旧 owner 关系。
141
+
142
+ ### 2.4 文件签名
143
+
144
+ 声明、release 和 transfer 字段由所在文件主签保护,不另设 ownership 签名。普通 agent.md 主签属于 sub,owner.md 主签属于 owner;附签不能替换主签身份或改变资源授权。
145
+
146
+ - `agent.md`:由 sub_aid 签名,兼容 `AUN-SIGNATURE`,也可用 `AUN-SIGNATURE-AGENTMD-V2`。
147
+ - `owner.md`:由 owner_aid 签名,使用 `AUN-SIGNATURE-OWNERSHIP-V2`,也兼容 `AUN-SIGNATURE`。
148
+
149
+ 尾部签名块示例如下,其中可选的 `public_key_fingerprint` 行可省略;签名值由文件所属 AID 运行时生成:
150
+
151
+ ```text
152
+ <!-- AUN-SIGNATURE-OWNERSHIP-V2
153
+ cert_fingerprint: sha256:<64位小写hex>
154
+ public_key_fingerprint: sha256:<64位小写hex>
155
+ timestamp: <Unix秒整数>
156
+ signature: <严格Base64编码的DER签名>
157
+ -->
158
+ ```
159
+
160
+ | 签名字段 | 要求 |
161
+ | --- | --- |
162
+ | `cert_fingerprint` | 必填;X.509 证书 DER 的 SHA-256,格式为 `sha256:` 加 64 位 hex。 |
163
+ | `public_key_fingerprint` | 可选;SubjectPublicKeyInfo DER 的 SHA-256,必须匹配证书公钥。 |
164
+ | `timestamp` | 必填 Unix 秒整数,范围 `1..9007199254740991`;落在签名证书有效期内,验收新文件时最多比服务端时间快 300 秒。 |
165
+ | `signature` | 必填;ECDSA P-256 / SHA-256,严格 Base64 编码的 DER 签名。 |
166
+
167
+ 每块标识为 `<!-- AUN-SIGNATURE` 或 `<!-- AUN-SIGNATURE-{TAG}`,TAG 只接受 `[A-Z0-9-]+`,为字面后缀:空 tag 无后缀,短 tag `AGENTMD-V2` 生成 `AUN-SIGNATURE-AGENTMD-V2`;`AUN-SIGNATURE` 不作特殊选项,标签不定义角色或权限。第一块保持旧裸签:输入为本块 `<` 之前的全部原始 UTF-8 字节,即 payload。第 i 块签署文件起点至本块 `<` 之前的完整 prefix,包含正文、全部前序完整块及块间空白,不含本块;不规范化换行、空白、Unicode 或字段顺序。
168
+
169
+ 仅向已有签名链末尾追加时,保持现有全部字节,并在末字节既非 LF 也非 CR 时补一个 LF;无旧块仍按首签要求正文以 CR/LF 结束,否则拒绝。该 LF 属于新块所签 prefix,不改变旧主签输入。修改、重排或删除前序块会令后续验签失败;删除末端块可形成有效短链,verify 只返回实际签名列表,不承诺检测末端截断。
170
+
171
+ 附签必填 `signer_aid`,须与该块证书 AID 一致;通用容器可解析主块的可选 signer_aid,但普通 agent.md 和 owner.md 主块不输出且业务拒绝该字段;实体主块显式 signer_aid=target。各块仅允许表中四字段及 `signer_aid`,重复或未知字段拒绝;相同签署者可多次追加,不据此增加授权。verify 必须逐块全验,任一块失败不能只采用主签结果。证书沿用可信 resolver 按 AID/指纹获取,不增加证书链字段。
172
+
173
+ `declared_at`、`expires_at`、`timestamp` 只接受无符号、无前导零的十进制正整数原词法;拒绝零、负数、布尔、字符串、浮点、科学计数、十六进制及越界值。先校验词法和范围,再转换数字或日期;无效输入归 `invalid`,不能因日期转换失败归 `unavailable`。表示范围不替代证书有效期、当前时钟和授权未过期校验,也不另设年份或最长授权期限上界。
174
+
175
+ 验收新声明或动作时检查证书链、所属 AID、指纹,并以服务端当前时间检查证书有效期、吊销及可签名状态;不能用尾部 timestamp 代替当前证书状态检查。历史文件验签依据原始文件及证书材料,不能要求历史证书当前仍可签名;可选审计记录不替代当前两份材料。尾部 `timestamp` 未被文件正文签名覆盖,不能单独作为历史授权时间证据。
176
+
177
+ 当前 OCSP 必须绑定本次验证链选定的直接 issuer:同时核对 CertID 的 serial、issuer name/key hash、ResponderID,并由该 issuer 亲签。内嵌证书只认可该 issuer 本身,不接受另一个或委派 responder 替代;网络获取后按当时的当前时间重新检查证书链有效期及 OCSP 新鲜度,不能固定使用请求开始时点。
178
+
179
+ ### 2.5 Group/Org 名片的实体主签与 owner 上传
180
+
181
+ 新 SDK 名片的 `aid` 是实体 AID,`type` 为 `group` 或 `org`,`owner` 是当前 owner;必需 `entity_cert_fingerprint: sha256:<64位小写hex>` 指向实体当前证书。必须省略通用 `ownership`、`ownership_proof`、`ownership_release`。第一尾签块由实体私钥签署,显式 signer_aid=实体 AID,证书属于实体且匹配该指纹;可追加一个或多个当前 owner 附签,每个附签都必须属于当前 owner,存在时逐块验证,不得失败后降级成单签成功。双签不自动证明当前 owner。
182
+
183
+ 现代上传使用当前 owner 的有效 token,无需实体登录;不再生成或强制实体专用 `AUN-AGENTMD-OWNER-AUTHORIZATION` V2 头。token 证明使用了该有效凭据,不证明本人操作,也不替代离线 owner 附签。普通 Ownership 既有 V1 兼容授权不因此变更。Group 始终兼容当前实体证书单签、实体身份上传的旧流程,仍执行生命周期、证书和文件 CAS 检查;Org 不开放该旧入口。
184
+
185
+ NS 新鲜核对权威类型、生命周期状态、当前 owner、实体当前证书及所有签名,再允许提交。沿用既有 PKI current HTTP 查询并绕过缓存,不新增 RPC、证书链字段或关系账本。`entity_cert_fingerprint` 绑定 owner/rekey 代际,不另建数字 epoch,也不是 `relation_version`。非当前 owner 的现代上传为 `forbidden`,确定非法签名或字段为 `invalid`,旧实体证书代际为 HTTP 409 / `conflict`;生命周期、数据库或证书依赖不可用为 HTTP 503 / `unavailable`。Group 旧入口按专属兼容授权检查,不能据此开放 Org。
186
+
187
+ 实体 fresh GET 必须同时携带 `X-AUN-Ownership-Check: 1`、`Cache-Control: no-cache`、`X-AUN-Signature-Format: multi-v1`;NS 仅凭 Check 头绕过 LRU 并新鲜验证全部签块,仍返回 not_applicable,不进入通用 Ownership 账本。GET/HEAD 按第 3.3 节协商表示,再返回 200 或按该表示 ETag 返回 304。响应保留 `X-AUN-Ownership-Status: not_applicable`、`X-AUN-Entity-Verification-Status: current|stale`、`X-AUN-Entity-Owner-AID` 和 `X-AUN-Entity-Cert-Fingerprint`;最终解散 owner 为空,无有效证书指纹为空。owner、状态或证书代际变化时为 `stale`,新 owner 可获取旧文件的表示 ETag 后按 CAS 替换;历史文件中的 owner 不作为当前权限。确实缺失时为 404,仍携带权威 owner/指纹及 stale,无 ETag;权威依赖失败为 503,不能伪装 404。
188
+
189
+ 新 SDK 首次发布用 `If-None-Match: *`,更新用原表示 `If-Match`;缺条件为 428,ETag 冲突为 412。实体 pending 保留完整签名原文、原 CAS、固定 owner 与实体证书指纹;显式重试先验证原件和当前生命周期代际,仅重传原字节。转移、rekey 或解散后停止旧代际待办,不换 owner、指纹或条件重签;连接恢复不隐式 PUT。取消 V2 后不再保存或检查额外上传授权及其 ±300 秒窗口;文件签名时间与当前证书校验仍按第 2.4 节执行。原条件完整且原文及对应 ETag 已证明提交时可仅观察完成。
190
+
191
+ 新 SDK 依据 NS fresh 权威 owner/指纹及独立 fresh PKI 查询交叉检查,不信 raw owner。Org 公共生命周期投影隐藏 owner,需 CAP 的 owner fields 不作为默认查询入口。公开 verified 下载逐块按签署者、尾签指纹和时间查询历史证书并验原始字节,不要求历史证书当前仍可签;不因 owner 或实体代际变化拒绝历史有效文件,历史验签不授予当前权限。确定坏签名或无效链为 `invalid`,依赖不可用为 `unavailable`。内部 fresh raw 可接收 stale 供条件替换,上传和当前授权仍执行当前生命周期及证书检查。
192
+
193
+ NS 对 Group/Org 实体上传与 legacy h.put 使用专用 Auditf 的 INFO event 绕过普通 level 过滤;普通 Ownership 独立 PUT 本轮不新增审计。日志记录 request_id、操作者、目标、权威类型、完整文件摘要、签名模式及转义字段;实际提交成功记 committed,拒绝记 rejected,操作失败记 failed。沿用 NS 日志,不新增审计服务或关系账本;数据库与日志非原子,不承诺无遗漏,Storage 副本失败不改写已提交结果。
194
+
195
+ ## 3. Name Service 的锁定规则
196
+
197
+ ### 3.1 当前签名材料与文件持久化
198
+
199
+ Ownership 2.1 关系事实只来自以下两份当前签名材料:
200
+
201
+ | 材料 | 要求 |
202
+ | --- | --- |
203
+ | sub_aid 的 `agent.md` | NS 数据库保存其当前完整原始签名文件及 ETag;sub 的 owner 声明由该文件签名保护。 |
204
+ | owner 的 `owner.md` | Storage 保存规范路径上的当前完整签名文件;以 owner_aid 对应证书核验签署身份。 |
205
+
206
+ NS 不为 2.1 另建关系事实表、不可变证据表、版本上界或释放历史账本。数据库事务和 ETag CAS 只保护当前 `agent.md` 的发布;同步队列可以保存副本投递状态,但不参与 2.1 关系是否成立的判断。开篇所述 Auth JSONL 仅保存 legacy 兼容状态,不参与本节判断。协议不要求 ownership journal、reserve/confirm 日志;owner_aid 是身份字段,不定义 `owner.aid` 文件。
207
+
208
+ `relation_version` 只用于匹配两份当前声明,不是 NS 持久维护的全局计数器。普通正文更新保持当前关系字段;release 保留被释放声明的版本,不递增独立版本。清理关系字段后没有当前关系版本,版本投影为 `0`;绑定由双方在新签名材料中明确一致版本,SDK 默认取当前可见基数加一,已清理时默认 `1`。转移仍按当前声明中的 `v` 与目标 `v+1` 核对。
209
+
210
+ 服务重启或数据库恢复后重新读取两份当前文件并验证,不从历史账本恢复关系。任一当前文件、签名或关系版本无法确证时,关系授权和关系变更返回不可用;符合自身格式、身份和签名规则的 `agent.md` 仍可普通读取、验签及使用。Storage 恢复未完成时不得将尚未恢复的命名空间报告为权威不存在。
211
+
212
+ ### 3.2 判定顺序
213
+
214
+ NS 处理关系检查或 `PUT /agent.md` 时,先读取数据库当前完整 `agent.md` 及 ETag,由其中的声明确定待验证的原 owner,再查询规范路径上的 owner 当前 `owner.md`,校验签署身份、AID、关系版本和动作。不能用待上传文件中的新 owner 判断旧关系,也不能只凭数据库派生字段授予权限。
215
+
216
+ 新声明为 self-owner 时也不得跳过原 owner 的保护;释放或转移仍须满足下表及第 4 节的条件。
217
+
218
+ | 原 owner 的当前 Storage 结果 | 关系及上传处理 |
219
+ | --- | --- |
220
+ | 有效 `declare`,匹配当前 `agent.md` 声明 | 保持本次 owner 锁判断;普通 PUT 只能完整保留关系字段。 |
221
+ | 有效 `transfer_owner`,匹配当前 `agent.md` 声明 | 本次原关系和锁保持;仅允许第 4.3 节指定新 owner 的关系转移。 |
222
+ | 有效 `release`,匹配当前 `agent.md` 声明 | 本次关系结果为 `released`;允许 sub_aid 自行清理关系字段,不保存额外释放事实。 |
223
+ | 权威 Storage 明确确认当前文件不存在 | 本次关系结果为 `released`;不能等待 release 才允许清理或重新绑定,不保存额外删除终局。 |
224
+ | 超时、5xx、权限错误、无法确认文件是否存在 | 返回不可用,保持关系保护;不能当作删除。 |
225
+ | 文件存在但签名无效、字段不匹配或版本异常 | 不授予 owner 权限,也不将其作为解锁授权;返回无效关系。 |
226
+
227
+ “确认不存在”必须是对 owner Storage 当前版本的权威查询结果,已核对服务身份、命名空间及路径,并绕过过期的正向、负向缓存。网关 404、错误路径、缓存中的 404 或下载失败均不能作为解绑依据。对象与元数据不一致、目录迁移或恢复未完成时属于无法确认,不得解释为删除。
228
+
229
+ 确认删除时核对 Storage 服务身份、规范路径及当前权威查询结果。该结果只描述本次当前文件不存在,不建立永久释放记录。删除即解绑使 Storage 成为受信任的授权参与方;恶意 Storage 伪造权威不存在不能由文件签名识别,不能宣称协议消除了这一信任边界。
230
+
231
+ 所有能改变权威名片的入口均须依据两份当前签名材料执行等效关系保护,包括删除 `agent.md`、改类型、删部分字段、覆盖旧版本、同 AID 重新注册、恢复导入和旧 SDK 上传。关系材料读取或解析失败时不能按无 owner 接受关系破坏;仅普通读取和验签不受该关系结果阻断。锁校验不能仅依赖 SDK 或请求头开启。
232
+
233
+ 请求缺少 2.1 字段、头部或来自旧 SDK 时,NS 仍依据当前材料保护已有现代声明;普通旧关系正文更新完整保留原有关系材料,不自动迁移、清空或改写关系。隔离的 legacy owner RPC 兼容流程可按旧 operation ID 激活旧 `ownership_proof`,不得通过该入口新增、替换或清除已存现代声明,也不得把旧 proof/台账结果作为 2.1 授权或共识。
234
+
235
+ ### 3.3 读取、并发与接口
236
+
237
+ 新 SDK 的全部 NS GET/HEAD/PUT(含 fresh 与重试)携带 `X-AUN-Signature-Format: multi-v1`。完整存储不变:该表示返回完整原文;无头时,多块文件返回 `raw[:first.End]`(首块 `-->` 后立即结束),单块文件保持首签原文;为兼容历史 SDK,投影中的首签 marker `<!-- AUN-SIGNATURE-<TAG>` 规范化为裸 `<!-- AUN-SIGNATURE`,并移除首签块中不参与签名摘要的 `signer_aid` 行。投影不改变正文、签名或证书指纹。HEAD、Content-Length、ETag 与 304 对应选定表示,响应 `Vary: X-AUN-Signature-Format`;两种表示分别计算 ETag,不得互用缓存或条件值。旧 PUT 的 If-Match 先匹配旧表示,再于同一提交检查中以完整存储快照 CAS;旧表示 ETag 不能直接作为完整文件摘要。无头投影只服务读取兼容,不删除已存附签或放宽授权;事件 agent_md_updated.etag 固定为完整存储 ETag,只有 HTTP 响应按表示区分。
238
+
239
+ 复用现有 `GET/HEAD/PUT /agent.md`。新 SDK 请求新鲜关系检查时携带 `X-AUN-Ownership-Check: 1` 和 `Cache-Control: no-cache`,禁止自动跟随重定向;NS 重新验证当前 `agent.md` 与 owner Storage 当前 `owner.md`,返回本次计算的关系元数据。旧客户端普通下载无需新请求头;响应头是本次结果的投影,不是额外权威事实:
240
+
241
+ ```text
242
+ X-AUN-Ownership-Protocol: 2.1
243
+ X-AUN-Ownership-Version: <当前agent.md声明的relation_version;无声明时为0>
244
+ X-AUN-Ownership-Lock: locked | unlocked
245
+ ```
246
+
247
+ 释放后,NS 可以保留仍含旧 owner 字段的原始 `agent.md`,等待 sub_aid 自己更新;当前 `owner.md` 的 release 或权威不存在使旧关系不可用于授权。NS 不替 sub_aid 修改、重签文件,也不单独递增或保存释放版本。
248
+
249
+ 同一 sub_aid 的最终关系检查与 NS 本地文件提交必须串行,并在提交时核对当前文档 ETag;冲突的写入必须拒绝。缓存不能作为关系授权的最终依据。SDK 共识检查的总窗口为 30 秒,从首次 NS GET 发出前开始计时,覆盖首读、Storage 和证书验证及末次 NS GET;前后重新读取 owner 完整原文、摘要和存在性,两份材料或 ETag 变化以及超时均返回可重试的 `unavailable`,不能返回成功共识。
250
+
251
+ NS 的数据库原子边界只包含当前 `agent.md` 文件、ETag 及可选同步投递待办;Storage 写入、CA 调用和 SDK 网络调用在边界之外。名片副本在本地持久提交后同步,失败不回滚已发布文件,恢复后按同步待办补齐副本;同步进度不证明 Ownership 关系。
252
+
253
+ 最终验收必须满足当前 `agent.md` ETag、上传条件、两份当前签名声明、转移期限及证书状态要求;期限及证书状态按服务端当前时间判定。材料须处于服务端本次验证时限内,文件变化或材料超时后,先前验收结果不得用于提交。
254
+
255
+ NS 与业务执行端均以本次最终授权验收时点裁决在途请求,并记录该时点及使用的材料。owner 发布 release 或撤回转移授权后,新鲜检查须使用当前材料;已在验收中的请求以 NS 实际提交结果为准。本协议不提供跨 Storage 的一致快照、全局事务或撤回瞬间使所有在途请求失效的保证。
256
+
257
+ 新 SDK 发布及 2.1 关系、现代实体格式写入均须携带条件:已有文件使用原 `If-Match`,首次创建使用 `If-None-Match: *`;缺少条件返回 428,声明关系版本不匹配或文档 ETag 冲突的写入必须拒绝。NS 兼容旧客户端普通及实体旧格式请求缺少新 Header/CAS,但必须在数据库事务内以服务端原子 CAS 核对当前文件快照,并验证适用的当前双文件关系,不得绕过 2.1 关系保护;Group 旧实体上传入口持续兼容,但不得绕过当前生命周期或存储 CAS。SDK 恢复须先确认本地持久保存的原上传条件完整,再核对远端完整文件;缺少原条件时保留原待办及错误,即使远端完整字节和 ETag 相同也不能自动清除待办。
258
+
259
+ ## 4. 关系操作与完整文件示例
260
+
261
+ 各方独立签署、提交自己的文件,顺序不限。NS 在本次提交或新鲜检查时验收当前材料,不维护跨方等待任务。图中各方分支之间不连线,虚线表示 NS 读取 Storage;编号用于定位示例,不规定跨方调用顺序。
262
+
263
+ 以下 YAML 完整列出每次写入的 frontmatter;文件容器及尾部签名按第 2 节。读取、确认和删除不生成新声明文件。
264
+
265
+ 示例初始未声明关系,双方绑定声明使用版本 `1`;release 仍指向版本 `1`,sub 清理后不再有关系版本。直接转移使用目标版本 `2`;清理后的新绑定由双方新声明决定,SDK 默认使用 `1`。
266
+
267
+ ### 4.1 建立关系
268
+
269
+ 建立关系要求当前双文件未构成需要保护的稳定关系,双方新声明的关系字段及版本一致,owner 的 `action` 为 `declare`。NS 验收 sub 上传时核对当前 owner 文件、上传文件及原 `agent.md`;成功后按 ETag CAS 原子保存 sub 的完整签名名片,不另建关系记录。
270
+
271
+ 材料未齐时不提交,当前权威状态保持。
272
+
273
+ 当前无 owner 的 `agent.md`:
274
+
275
+ ```yaml
276
+ aid: subject.agentid.pub
277
+ name: Subject AID
278
+ type: agent
279
+ version: 1.0.0
280
+ ```
281
+
282
+ owner 自签发布的 `owner.md`(`owner.agentid.pub:/sub_aids/subject.agentid.pub/owner.md`):
283
+
284
+ ```yaml
285
+ owner_aid: owner.agentid.pub
286
+ sub_aid: subject.agentid.pub
287
+ ownership:
288
+ statement:
289
+ version: 2
290
+ declaration_id: 660e8400-e29b-41d4-a716-446655440000
291
+ owner_aid: owner.agentid.pub
292
+ sub_aid: subject.agentid.pub
293
+ relation_version: 1
294
+ declared_at: 1791523200
295
+ action: declare
296
+ ```
297
+
298
+ sub 自签上传的目标 `agent.md`(关系版本 `1`):
299
+
300
+ ```yaml
301
+ aid: subject.agentid.pub
302
+ name: Subject AID
303
+ type: agent
304
+ version: 1.0.0
305
+ owner: owner.agentid.pub
306
+ ownership:
307
+ statement:
308
+ version: 2
309
+ declaration_id: 550e8400-e29b-41d4-a716-446655440000
310
+ owner_aid: owner.agentid.pub
311
+ sub_aid: subject.agentid.pub
312
+ relation_version: 1
313
+ declared_at: 1791523260
314
+ ```
315
+
316
+ ```mermaid
317
+ flowchart TB
318
+ subgraph P[各方独立执行:任意先后,可重复]
319
+ direction LR
320
+ S[sub 自签提交 agent.md]
321
+ O[owner 自签发布 declare owner.md]
322
+ end
323
+ S --> N[NS 验收本次提交]
324
+ O -. NS 读取 Storage 当前声明 .-> N
325
+ L[NS 当前签名 agent.md 与 ETag] --> N
326
+ N --> C{无锁、双方签名、AID、目标版本及 ETag 均匹配吗}
327
+ C -->|是| A[按 ETag CAS 保存签名 agent.md]
328
+ C -->|否| R[本次不提交,本端后续独立重试]
329
+ ```
330
+
331
+ ### 4.2 解绑
332
+
333
+ 原 owner 的有效 release 或权威删除使当前关系结果为 `released`。NS 不创建释放记录、不递增版本;sub 离线不妨碍当前校验方停止授予 owner 权限,sub 随后自行清理名片中的关系字段。
334
+
335
+ release 发布后,旧关系不能通过新鲜授权检查;当前结果只由 NS 当前 `agent.md` 与 owner 当前 `owner.md` 共同决定。sub 的旧声明清理前须保留 release;sub 清理或转入另一有效关系后,owner 可核对当前 NS 及本任务完整原件后清理旧文件,不能只等待固定时长。
336
+
337
+ 原 owner 自签发布的 release `owner.md`(原路径、被释放版本 `1`):
338
+
339
+ ```yaml
340
+ owner_aid: owner.agentid.pub
341
+ sub_aid: subject.agentid.pub
342
+ ownership:
343
+ statement:
344
+ version: 2
345
+ declaration_id: 770e8400-e29b-41d4-a716-446655440000
346
+ owner_aid: owner.agentid.pub
347
+ sub_aid: subject.agentid.pub
348
+ relation_version: 1
349
+ declared_at: 1791523800
350
+ action: release
351
+ ```
352
+
353
+ NS 不修改 sub 的签名文件,也不生成新关系版本。以下清理文件由 sub 自签上传,发布后无当前关系声明,响应版本投影为 `0`:
354
+
355
+ ```yaml
356
+ aid: subject.agentid.pub
357
+ name: Subject AID
358
+ type: agent
359
+ version: 1.0.0
360
+ ```
361
+
362
+ ```mermaid
363
+ flowchart TB
364
+ subgraph P[各方独立执行:任意先后,可重复]
365
+ direction LR
366
+ O[owner 自签发布 release]
367
+ S[sub 独立检查或提交自签清理文件]
368
+ Q[任一校验方独立请求新鲜检查]
369
+ end
370
+ S --> N[NS 验收本次检查或提交]
371
+ Q --> N
372
+ O -. NS 读取 Storage 当前声明 .-> N
373
+ L[NS 当前签名 agent.md 与 ETag] --> N
374
+ N --> C{当前 owner.md 为匹配 release 或已权威删除吗}
375
+ C -->|是| A[本次结果 released;不保存释放事实或新版本]
376
+ C -->|否| R[保留保护,本端后续独立重试]
377
+ A --> F[sub 清理文件单独验收,未提交则保留原签名名片]
378
+ ```
379
+
380
+ **直接删除也等同于解绑。** 按第 3.2 节确认当前 `owner.md` 权威不存在后,本次关系结果为 `released`,允许 sub 清理或重新绑定,不要求补发 release 或写入关系终局。
381
+
382
+ 不存在的路径不生成 `owner.md`;`action: delete`、空文件或 sub 签署的 release 均不能替代权威不存在结果。sub 清理使用上面的完整无 owner 文件。
383
+
384
+ 再次绑定必须由双方发布匹配的当前签名声明,并满足当前文件 CAS;版本由这两份声明决定。不同 owner 重新绑定时,SDK 默认从仍可见的旧声明版本加一,sub 已清理关系字段时默认 `1`;协议不保留历史版本上界。
385
+
386
+ 同一 owner 释放后重新绑定时,若 sub 的 `agent.md` 仍含旧声明,必须先由 sub 完成现有清理,再发布新 `declare`;SDK 在创建绑定任务或覆盖文件前返回 `conflict`/`action_required`。不得用新声明覆盖唯一的 release 材料,否则 NS 无法仅从两份当前文件确认旧关系已释放。
387
+
388
+ ### 4.3 `transfer_owner`
389
+
390
+ 转移要求当前稳定关系、原 owner 授权以及 sub、新 owner 各自签署的目标文件。NS 成功验收后直接从旧版本 `v` 切换到新版本 `v+1`,期间没有未绑定窗口。
391
+
392
+ 原 owner 授权保留旧版本 `v`,两份目标声明使用 `v+1`,新 owner 的 `action` 为 `declare`。三方可独立签署、提交;NS 在 sub 上传时验收原 owner 当前授权、新 owner Storage 当前声明及 sub 的目标签名文件,核对指定目标、关系版本、有效期和各方签名。
393
+
394
+ 新 owner 的目标 `owner.md`(`next-owner.agentid.pub:/sub_aids/subject.agentid.pub/owner.md`):
395
+
396
+ ```yaml
397
+ owner_aid: next-owner.agentid.pub
398
+ sub_aid: subject.agentid.pub
399
+ ownership:
400
+ statement:
401
+ version: 2
402
+ declaration_id: 880e8400-e29b-41d4-a716-446655440000
403
+ owner_aid: next-owner.agentid.pub
404
+ sub_aid: subject.agentid.pub
405
+ relation_version: 2
406
+ declared_at: 1791524100
407
+ action: declare
408
+ ```
409
+
410
+ sub 自签的目标 `agent.md`;准备此文件不改变 NS 当前旧关系:
411
+
412
+ ```yaml
413
+ aid: subject.agentid.pub
414
+ name: Subject AID
415
+ type: agent
416
+ version: 1.0.0
417
+ owner: next-owner.agentid.pub
418
+ ownership:
419
+ statement:
420
+ version: 2
421
+ declaration_id: 990e8400-e29b-41d4-a716-446655440000
422
+ owner_aid: next-owner.agentid.pub
423
+ sub_aid: subject.agentid.pub
424
+ relation_version: 2
425
+ declared_at: 1791524160
426
+ ```
427
+
428
+ 原 owner 自签发布的转移授权 `owner.md`(原路径、旧版本 `1`):
429
+
430
+ ```yaml
431
+ owner_aid: owner.agentid.pub
432
+ sub_aid: subject.agentid.pub
433
+ ownership:
434
+ statement:
435
+ version: 2
436
+ declaration_id: aa0e8400-e29b-41d4-a716-446655440000
437
+ owner_aid: owner.agentid.pub
438
+ sub_aid: subject.agentid.pub
439
+ relation_version: 1
440
+ declared_at: 1791524220
441
+ action: transfer_owner
442
+ transfer:
443
+ new_owner_aid: next-owner.agentid.pub
444
+ target_relation_version: 2
445
+ expires_at: 1791527820
446
+ ```
447
+
448
+ NS 保存本次验收的 sub 签名文件为权威名片,新 owner 的声明以其 Storage 当前版本为准。旧文件清理按第 1.2 节,不改变已提交的新关系。
449
+
450
+ ```mermaid
451
+ flowchart TB
452
+ subgraph P[三方独立执行:发布与提交可乱序,各自重试]
453
+ direction LR
454
+ S[sub 自签提交目标 agent.md]
455
+ O[原 owner 自签发布 transfer_owner]
456
+ U[新 owner 自签发布目标 owner.md]
457
+ end
458
+ S --> N[NS 验收本次目标提交]
459
+ O -. NS 读取原 owner Storage 当前授权 .-> N
460
+ U -. NS 读取新 owner Storage 当前声明 .-> N
461
+ L[NS 当前旧签名 agent.md 与 ETag] --> N
462
+ N --> C{原关系、三方签名、指定目标、版本、期限及 owner 文件原文和存在性条件均匹配吗}
463
+ C -->|是| A[按 ETag CAS 保存目标签名 agent.md,声明版本 v+1]
464
+ C -->|否| R[不提交目标文件;保护按当前权威事实处理]
465
+ ```
466
+
467
+ 材料不齐、授权过期或验收失败时不保存目标文件;原保护按当前 release、权威删除或稳定关系事实处理。转移授权过期不解绑旧关系,也不能自动改走先解绑再绑定。
468
+
469
+ 停止本端任务不撤回已发布授权;撤回及在途竞争见第 4.3.1 节。
470
+
471
+ #### 4.3.1 撤回尚未提交的转移授权
472
+
473
+ 撤回仅适用于当前两份材料仍指向原 owner、版本 `v` 的关系:原 owner 重新核对当前转移文件原文后原子发布同版本 `action: declare`,省略 `transfer`。不得删除文件表示取消,因为删除即解绑。当前材料已 release 或 sub 已发布后续声明时不得执行旧写入。
474
+
475
+ 撤回授权的完整 `owner.md` frontmatter(旧关系版本 `1`):
476
+
477
+ ```yaml
478
+ owner_aid: owner.agentid.pub
479
+ sub_aid: subject.agentid.pub
480
+ ownership:
481
+ statement:
482
+ version: 2
483
+ declaration_id: bc0e8400-e29b-41d4-a716-446655440000
484
+ owner_aid: owner.agentid.pub
485
+ sub_aid: subject.agentid.pub
486
+ relation_version: 1
487
+ declared_at: 1791524300
488
+ action: declare
489
+ ```
490
+
491
+ ```mermaid
492
+ flowchart TB
493
+ subgraph P[各方独立执行:撤回与目标提交可能竞争]
494
+ direction LR
495
+ O[原 owner 自签条件覆盖为 declare]
496
+ S[sub 可能已有目标提交在途]
497
+ end
498
+ O --> T[原 owner Storage 原子替换当前文件]
499
+ O -->|本端确认发布后| Q[请求 NS 新鲜检查]
500
+ S --> N[NS 串行验收提交或检查]
501
+ Q --> N
502
+ T -. NS 读取当前完整文件 .-> N
503
+ L[NS 当前签名 agent.md 与 ETag] --> N
504
+ N --> K{权威状态可确认吗}
505
+ K -->|否| R[保留材料,不认定撤回完成]
506
+ K -->|是| C{NS 已提交目标转移吗}
507
+ C -->|是| A[新关系保持;反向转移须新 owner 授权]
508
+ C -->|否| D{仍是原 owner 和版本且当前文件为 declare 吗}
509
+ D -->|是| B[原锁保持,本次旧目标已无授权]
510
+ D -->|否| V[停止旧任务,按最新权威结果处理]
511
+ ```
512
+
513
+ 撤回是否生效以 NS 当前 `agent.md` 与 owner 当前 `owner.md` 为准:仍为原关系且 owner 文件为 `declare` 时,本次目标已无当前转移授权;若在途转移已提交新签名名片,新关系按新 owner 当前声明校验,反向转移须新 owner 授权。本操作不新增动作、RPC 或锁状态,竞争边界按第 3.3 节。
514
+
515
+ ### 4.4 owner 锁下的普通更新
516
+
517
+ 普通更新完整保留锁定的 `owner`、`ownership.statement`;以下仅改变名称和名片版本,关系版本仍为 `1`:
518
+
519
+ ```yaml
520
+ aid: subject.agentid.pub
521
+ name: Updated Subject AID
522
+ type: agent
523
+ version: 1.0.1
524
+ owner: owner.agentid.pub
525
+ ownership:
526
+ statement:
527
+ version: 2
528
+ declaration_id: 550e8400-e29b-41d4-a716-446655440000
529
+ owner_aid: owner.agentid.pub
530
+ sub_aid: subject.agentid.pub
531
+ relation_version: 1
532
+ declared_at: 1791523260
533
+ ```
534
+
535
+ NS 保存新签名文件但不增加关系版本,原 owner 的 `owner.md` 不变;清除或替换稳定关系字段的普通上传按第 3.2 节拒绝。
536
+
537
+ ### 4.5 self-owner 的建立、解绑与转移
538
+
539
+ 本例从无 owner 声明开始,同一 AID 独立提交两个角色的文件;两份声明均使用版本 `1`,NS 按统一规则计算 owner 锁。
540
+
541
+ ```mermaid
542
+ flowchart TB
543
+ subgraph P[同一 AID 本端独立写入:任意先后,可重复]
544
+ direction LR
545
+ S[自签提交 owner 等于自身的 agent.md]
546
+ O[自签发布自有 Storage 的 owner.md]
547
+ end
548
+ S --> N[NS 验收本次提交]
549
+ O -. NS 读取自身 Storage 当前声明 .-> N
550
+ L[NS 当前签名 agent.md 与 ETag] --> N
551
+ N --> C{当前授权、两份文件签名、身份、版本及 ETag 均匹配吗}
552
+ C -->|是| A[按 ETag CAS 保存 self-owner 签名名片]
553
+ C -->|否| R[本次不提交,本端独立重试;外部 owner 锁仍须校验]
554
+ ```
555
+
556
+ 本端 owner 角色发布的 `owner.md`:
557
+
558
+ ```yaml
559
+ owner_aid: subject.agentid.pub
560
+ sub_aid: subject.agentid.pub
561
+ ownership:
562
+ statement:
563
+ version: 2
564
+ declaration_id: dd0e8400-e29b-41d4-a716-446655440000
565
+ owner_aid: subject.agentid.pub
566
+ sub_aid: subject.agentid.pub
567
+ relation_version: 1
568
+ declared_at: 1791523200
569
+ action: declare
570
+ ```
571
+
572
+ 本端 sub 角色提交的 `agent.md`:
573
+
574
+ ```yaml
575
+ aid: subject.agentid.pub
576
+ name: Self-owned AID
577
+ type: agent
578
+ version: 1.0.0
579
+ owner: subject.agentid.pub
580
+ ownership:
581
+ statement:
582
+ version: 2
583
+ declaration_id: ee0e8400-e29b-41d4-a716-446655440000
584
+ owner_aid: subject.agentid.pub
585
+ sub_aid: subject.agentid.pub
586
+ relation_version: 1
587
+ declared_at: 1791523260
588
+ ```
589
+
590
+ 本端 owner 角色发布的 release `owner.md`(被释放版本 `1`):
591
+
592
+ ```yaml
593
+ owner_aid: subject.agentid.pub
594
+ sub_aid: subject.agentid.pub
595
+ ownership:
596
+ statement:
597
+ version: 2
598
+ declaration_id: ff0e8400-e29b-41d4-a716-446655440000
599
+ owner_aid: subject.agentid.pub
600
+ sub_aid: subject.agentid.pub
601
+ relation_version: 1
602
+ declared_at: 1791523800
603
+ action: release
604
+ ```
605
+
606
+ 当前 `owner.md` 为 release 时,本次关系结果为 `released`,声明仍为版本 `1`。本端 sub 角色自签上传以下清理文件后无关系声明,响应版本投影为 `0`:
607
+
608
+ ```yaml
609
+ aid: subject.agentid.pub
610
+ name: Self-owned AID
611
+ type: agent
612
+ version: 1.0.0
613
+ ```
614
+
615
+ 仅清除 self-owner 名片字段不能绕过有效锁。直接删除、延迟清理、重放保护及再次绑定沿用第 4.2 节。
616
+
617
+ | 转移方向 | 必须保留的授权和文件 |
618
+ | --- | --- |
619
+ | self-owner → 外部 owner | 当前 AID 同时签署原 owner 转移授权和自己的目标 `agent.md`;外部新 owner 签署目标 `owner.md`。 |
620
+ | 外部 owner → self-owner | 原外部 owner 签署转移授权;sub_aid 同时以 sub 和新 owner 角色签署自己的两个目标文件。 |
621
+
622
+ 两种方向均按第 4.3 节验收三个角色的文件、指定目标、版本和期限,从 `v` 切换到 `v+1`;角色重合不减少材料,原、新 owner 相同不构成有效转移。原 owner 先释放后建立 self-owner 则按新绑定处理。
623
+
624
+ ## 5. 运行与降级约束
625
+
626
+ NS 拒绝持有陈旧 ETag 的 `agent.md` 写入;owner 文件通过当前完整原文、摘要和存在性再读核对。各方独立提交,不依赖跨方大事务;不保存路径历史状态,不提供全局一致快照或 ABA 检测保证,也不承诺识别完整文件回滚。关系结果每次从两份当前材料重新计算。
627
+
628
+ 功能降级不得放宽 owner 锁或授权条件。NS、Storage 或证书状态不确定时,不提交关系变更、不授予 owner 权限;双方材料未齐时不授予 owner 权限,普通身份认证、`agent.md` 读取/验签和通信可继续。NS 不支持 2.1 时,不执行 2.1 关系变更。
629
+
630
+ Storage 不满足第 1.2 节的完整原子发布要求时,不得发布 `owner.md` 或执行转移。既有关系及真实 release/删除仍按 NS 当前签名 `agent.md`、Storage 当前签名 `owner.md` 或权威不存在结果处理。
631
+
632
+ ## 6. 共识、审计与安全边界
633
+
634
+ 共识检查只依据 NS 当前签名 `agent.md` 与 owner 当前签名 `owner.md`。本次校验期间完整文件、存在性和 ETag须保持一致;返回 `consensus` 时,两份声明的关系版本和双方 AID 必须匹配,签名及证书校验须通过。owner 的 `declare`、尚未提交的 `transfer_owner` 均可证明当前旧关系;转移授权过期不影响该旧关系声明。当前 release 或权威删除不能返回 `consensus`。响应 Header 只投影本次两份材料的校验结果,不能替代材料或新增事实。
635
+
636
+ self-owner 验证通过同样返回 `consensus`,仅证明该 AID 的自主管理声明;校验依据与外部关系相同。
637
+
638
+ 下表六态仅用于通用主体;Group/Org 的通用共识入口直接返回 `status/code=not_applicable`、`retryable=false`,其 owner 授权另按第 1.3、2.5 节查询。
639
+
640
+ | 结果 | 含义 |
641
+ | --- | --- |
642
+ | `consensus` | 当前未释放的关系字段、版本及双方签名匹配。 |
643
+ | `released` | 原 owner 有效 release 或 Storage 已确认删除;sub 的旧字段可能尚未清理。 |
644
+ | `unbound` | 没有当前 owner 声明。 |
645
+ | `single_sided` | 只有一方准备或声明,尚未建立稳定关系。 |
646
+ | `invalid` | 字段、路径、角色、版本、签名或证书确定无效,包括完整原字节摘要匹配后的非法 UTF-8 或文件内容,不可按暂时故障重试。 |
647
+ | `unavailable` | 服务、网络或验证依赖不可用,无法确认 NS、Storage 或证书当前状态;权威元数据、正文摘要不一致,以及 Storage Base64 传输封装损坏均属无法取得可靠材料。保留待办及保护,不等于材料无效或解绑。 |
648
+
649
+ 需要 owner 权限的业务由执行端在实际授权时认证调用者,核对当前 owner、目标 sub_aid、权限范围及新鲜共识,确保两份当前声明的 AID、关系版本和签名匹配;不能信任客户端共识布尔值、响应 Header 或只看旧签名。要求外部 owner 时还须 `owner_aid != sub_aid`,要求指定 owner 时核对其 AID 或业务允许名单。
650
+
651
+ 如使用 token 或 ACL,授权必须绑定 owner_aid、sub_aid、当前完整关系声明(或其稳定摘要)、关系版本及权限范围,使用时新鲜核对当前声明、版本和共识;版本可在清理后重复,不能单独识别关系,短有效期不能代替释放、转移后的失效检查。旧 SDK、缺少检查头或功能降级均不得绕过业务执行端的校验。已通过本次最终授权验收的在途操作按该时点处理,后续独立敏感步骤需重新授权,不承诺跨服务即时撤回。
652
+
653
+ 执行端按自身业务审计要求记录授权与执行结果;关系授权时应校验两份当前完整签名文件、owner_aid 身份及证书和本次验签结果。审计记录只描述历史操作,不参与当前关系判断;普通 `agent.md` 读取和身份验签不依赖 Ownership 审计数据。
654
+
655
+ NS 不持久化独立关系事实、释放状态或关系版本上界。数据库只保存当前 `agent.md` 及其发布 ETag;owner 身份和声明依据 owner_aid 对应的证书及 Storage 当前 `owner.md`。无法从这两份当前材料确证关系或版本时,关系授权及关系变更 fail-closed,但不影响符合普通规则的 `agent.md` 读取、验签和使用。同步待办和应用审计均不能作为第三个事实来源。
656
+
657
+ 托管为应用层显式启用的可选能力,不改变各方签署及上传身份。外部 owner 若持有可解密的 sub 私钥,仍可冒用其身份,移除代理接口不能撤销该能力。关系变更不自动撤销旧凭据及其续签、恢复身份的能力;业务交接完成须另行确认凭据隔离,与 NS 关系提交是独立事实。
658
+