@agentunion/fastaun-browser 0.5.19 → 0.5.21

package/_packed_docs/sdk/Ownership/347/256/241/347/220/206/344/270/223/351/242/230.md

@@ -0,0 +1,559 @@
+# Ownership 管理专题
+
+本文保留 legacy `aun.ownership.v1` 的历史方案与实现记录，不代表当前 Ownership 2.1 契约。文中“当前”“实现差异”均指该历史基线；proof、自动托管、代签、代上传及自动 rekey 不能作为 2.1 接入方式。
+
+当前文件、锁和版本规则见 [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md)，SDK 接入见 [2.1 应用集成指南](Ownership2.1-SDK应用集成指南.md)，编排见 [SDK 编排指南 2.1](Ownership-SDK编排指南2.1.md)。[Ownership 2.0](../protocol/Ownership协议定义2.0.md) 及其 [SCHEMA](../agent.md/SCHEMA.md) 同为历史版本，各版本字段和流程不能混用。
+
+## 1. 关系模型
+
+- `subject_aid`：被 owner 管理、其 `agent.md` 可由 owner 代签名上传的 AID。
+- `owner_aid`：对 subject 承担所有权责任的 AID。
+- `type`：subject 的应用层类型，默认 `agent`。
+- `extensions`：应用层按需附加字段，由发起方传入，SDK 不解释其业务含义。
+
+双方签名只表示关系成立。两方签名的声明自包含双方 AID、`proof_id`、签名角色和各自扩展字段，因此 subject 与 owner 不要求签署完全相同的扩展字段。SDK 的状态查询返回关系摘要，不暴露私钥或 escrow 密码。
+
+关系建立完成前，SDK 只提供功能降级，不要求跨端事务；关系签名、托管和代上传分别持久化。消息或进程中断后，SDK 可依据本地 metadata 中的 pending 状态恢复托管、代上传和解绑后的 rekey/agent.md 上传。
+
+subject 取得双方签名后立即持久化完整 proof，并自行签名发布包含该 proof 的 `agent.md`，不等待托管。发布失败时保留待上传的签名版本，后续仍单独尝试托管；托管失败也不撤销 active 关系或已经公开的 proof。只有 owner 拿到并持久化 subject identity 后，才能推进代签和代上传。
+
+## 2. 对外 SDK 方法
+
+| 方向 | Python | TypeScript / JavaScript | Go |
+| --- | --- | --- | --- |
+| owner 发起绑定 subject | `bind_aid(subject_aid)`；`bindAid` 为别名 | `bindAid(subjectAid)` | `BindAID(ctx, subjectAID)`；`BindAid` 为别名 |
+| subject 发起绑定 owner | `bind_owner(owner_aid)`；`bindOwner` 为别名 | `bindOwner(ownerAid)` | `BindOwner(ctx, ownerAID)` |
+| 接受收到的绑定请求 | `accept_ownership_request(request_id)`；`acceptOwnershipRequest` 为别名 | `acceptOwnershipRequest(requestId)` | `AcceptOwnershipRequest(ctx, requestID)` |
+| 拒绝收到的绑定请求 | `reject_ownership_request(request_id)`；`rejectOwnershipRequest` 为别名 | `rejectOwnershipRequest(requestId)` | `RejectOwnershipRequest(ctx, requestID)` |
+| 查询 subject 类型 | `get_type()` / `getType()` | `getType()` | `GetType()` |
+| 查询 owner | `get_owner()` / `getOwner()` | `getOwner()` | `GetOwner()` |
+| 查询公开状态 | `get_ownership_status()` / `getOwnershipStatus()` | `getOwnershipStatus()` | `GetOwnershipStatus()` |
+
+绑定方法可传 `subject_type`/`subjectType`、`extensions` 和可选 `request_id`。话题、群或其它业务 key 属于应用层字段，若需要随关系声明保存，应放入 `extensions`；SDK 不生成或解释这些 key。
+
+## 3. P2P 消息协议
+
+ownership 消息的 payload `type` 固定为 `aun.ownership.v1`，公共字段如下：
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "bind.request",
+  "request_id": "...",
+  "proof_id": "...",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub"
+}
+```
+
+消息通过 `message.send` 发送并要求加密。SDK 在消息投递到应用层之前拦截该 payload；应用层不应直接处理 `aun.ownership.v1`。
+
+| action | 发送方向 | 主要字段与作用 |
+| --- | --- | --- |
+| `bind.request` | 发起方 → 对端 | 发起方的独立 `statement` / `signature`；接收 SDK 验证后发布 `ownership.request` 给应用层 |
+| `bind.response` | 接受方 → 发起方 | 应用接受请求后，由接受方签署自己的独立声明并回复；双方签名齐全时关系成立 |
+| `bind.reject` | 拒绝方 → 发起方 | 应用拒绝请求后发送；记录为 rejected，不执行托管和代上传 |
+| `escrow.ready` | subject → owner | 关系成立后发送加密 identity 的地址、密码和摘要；不表示 `agent.md` 已上传 |
+| `agent_md.updated` | owner → subject | owner 代上传成功后通知 subject 下载并同步 `agent.md` |
+| `release.request` | owner → subject | 原 owner 签署放弃声明；subject 验证当前关系后自动 rekey 并上传不带 owner 的 `agent.md` |
+
+`bind.confirm` 不属于当前分阶段流程。关系绑定、证书托管和 owner 代上传是三个独立结果；托管或代上传失败不撤销已完成的双方签名关系。
+
+以下是各 action 的完整 payload 示例；每个对象单独作为 `message.send` 的 `payload`，签名和密码仅通过加密 P2P 传送。`bind.reject` 是拒绝分支，与 `bind.response` 二选一。
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "bind.request",
+  "request_id": "request-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub",
+  "subject_type": "agent",
+  "statement": {
+    "version": 2,
+    "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+    "subject_aid": "subject.agentid.pub",
+    "owner_aid": "owner.agentid.pub",
+    "signer_aid": "owner.agentid.pub",
+    "role": "owner",
+    "signed_at": 1791446400,
+    "extensions": {"department": "clinic"}
+  },
+  "signature": {
+    "cert_fingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "signature": "BASE64_OWNER_SIGNATURE",
+    "signer_aid": "owner.agentid.pub",
+    "role": "owner",
+    "statement": {
+      "version": 2,
+      "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+      "subject_aid": "subject.agentid.pub",
+      "owner_aid": "owner.agentid.pub",
+      "signer_aid": "owner.agentid.pub",
+      "role": "owner",
+      "signed_at": 1791446400,
+      "extensions": {"department": "clinic"}
+    }
+  }
+}
+```
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "bind.response",
+  "request_id": "request-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub",
+  "subject_type": "agent",
+  "statement": {
+    "version": 2,
+    "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+    "subject_aid": "subject.agentid.pub",
+    "owner_aid": "owner.agentid.pub",
+    "signer_aid": "subject.agentid.pub",
+    "role": "subject",
+    "signed_at": 1791446460,
+    "extensions": {"managed_by": "clinic-app"}
+  },
+  "signature": {
+    "cert_fingerprint": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "signature": "BASE64_SUBJECT_SIGNATURE",
+    "signer_aid": "subject.agentid.pub",
+    "role": "subject",
+    "statement": {
+      "version": 2,
+      "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+      "subject_aid": "subject.agentid.pub",
+      "owner_aid": "owner.agentid.pub",
+      "signer_aid": "subject.agentid.pub",
+      "role": "subject",
+      "signed_at": 1791446460,
+      "extensions": {"managed_by": "clinic-app"}
+    }
+  }
+}
+```
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "bind.reject",
+  "request_id": "request-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub"
+}
+```
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "escrow.ready",
+  "request_id": "request-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub",
+  "subject_type": "agent",
+  "escrow_path": "/.aun/ownership/subject.agentid.pub/550e8400-e29b-41d4-a716-446655440000.json",
+  "escrow_download_url": "https://storage.agentid.pub/download/opaque-token",
+  "escrow_password": "BASE64URL_RANDOM_PASSWORD",
+  "escrow_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+}
+```
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "agent_md.updated",
+  "request_id": "request-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub"
+}
+```
+
+```json
+{
+  "type": "aun.ownership.v1",
+  "action": "release.request",
+  "request_id": "release-20261008-001",
+  "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub",
+  "ownership_release": {
+    "cert_fingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "signature": "BASE64_OWNER_RELEASE_SIGNATURE",
+    "signer_aid": "owner.agentid.pub",
+    "role": "owner",
+    "statement": {
+      "version": 1,
+      "action": "release",
+      "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+      "subject_aid": "subject.agentid.pub",
+      "owner_aid": "owner.agentid.pub",
+      "signer_aid": "owner.agentid.pub",
+      "role": "owner",
+      "signed_at": 1791446460
+    }
+  }
+}
+```
+
+### 3.1 应用层确认
+
+SDK 在收到 `aun.ownership.v1` 后先拦截原始 P2P 消息，检查消息发送者、双方 AID、proof id 和签名。有效的 `bind.request` 不会作为普通 `message.received` 投递，而会发布以下应用事件：
+
+```json
+{
+  "event": "ownership.request",
+  "payload": {
+    "request_id": "request-20261008-001",
+    "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+    "subject_aid": "subject.agentid.pub",
+    "owner_aid": "owner.agentid.pub",
+    "subject_type": "agent",
+    "requester_aid": "owner.agentid.pub",
+    "requester_role": "owner",
+    "statement": {
+      "version": 2,
+      "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+      "subject_aid": "subject.agentid.pub",
+      "owner_aid": "owner.agentid.pub",
+      "signer_aid": "owner.agentid.pub",
+      "role": "owner",
+      "signed_at": 1791446400,
+      "extensions": {"department": "clinic"}
+    },
+    "signature": {
+      "cert_fingerprint": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "signature": "BASE64_SIGNATURE",
+      "signer_aid": "owner.agentid.pub",
+      "role": "owner",
+      "statement": {
+        "version": 2,
+        "proof_id": "550e8400-e29b-41d4-a716-446655440000",
+        "subject_aid": "subject.agentid.pub",
+        "owner_aid": "owner.agentid.pub",
+        "signer_aid": "owner.agentid.pub",
+        "role": "owner",
+        "signed_at": 1791446400,
+        "extensions": {"department": "clinic"}
+      }
+    }
+  }
+}
+```
+
+应用收到事件后自行决定接受或拒绝，并调用 SDK 的对应方法。接受会签署本端角色的独立 ownership 声明并发送 `bind.response`；拒绝发送 `bind.reject`。SDK 在接受完成后自动推进托管和代上传，应用不需要再次确认这些后续步骤。
+
+### 3.2 owner 发起：`BindAID`
+
+1. owner 创建 role 为 `owner` 的声明并签名，发送 `bind.request`；subject SDK 验证后将该单方 proof 写入本地 metadata。
+2. subject SDK 向 subject 应用发布 `ownership.request`，等待应用决策；此时 subject 尚未签署，也没有完整 ownership proof。
+3. subject 应用调用 `acceptOwnershipRequest(request_id)`；SDK 创建 subject 声明、保存双方 proof，并发送 `bind.response`。应用拒绝时调用 `rejectOwnershipRequest(request_id)`，本流程结束。
+4. 关系签名完成后，subject SDK 先用自己的 AID 上传包含完整 proof 的 `agent.md`，再自动将加密 identity 上传到 subject 的 Storage 并授予 owner 读取 ACL；随后单独发送 `escrow.ready`。名片上传或托管失败不撤销关系，也不阻止另一项操作。
+5. owner SDK 收到 `escrow.ready` 后自动下载并解密 subject identity，以 subject 证书签署 `agent.md`，再使用 owner 签名的上传授权头上传到 subject 的 Name Service。
+6. owner 上传成功后发送 `agent_md.updated`；subject SDK 下载、验证并同步本地 `agent.md`。
+
+若第 4 或第 5 步失败，双方签名已成立的关系继续保持；只表示托管或名片更新尚未完成。
+
+```mermaid
+sequenceDiagram
+    participant O as owner SDK
+    participant M as AUN 加密 P2P
+    participant S as subject SDK
+    participant A as subject 应用
+    participant N as subject Name Service
+    O->>O: 独立签署 owner 声明
+    O->>M: bind.request（owner 声明和签名）
+    M->>S: SDK 拦截、验证 bind.request
+    S->>S: 将 owner 单方 proof 写入 subject 本地 metadata
+    S->>A: ownership.request（验证后的绑定申请）
+    A->>S: acceptOwnershipRequest 或 rejectOwnershipRequest
+    alt 应用接受
+        S->>S: 独立签署 subject 声明并保存 proof
+        S->>M: bind.response（subject 声明和签名）
+        M->>O: 验证 subject 声明并保存完整 proof
+        Note over S,O: 关系签署已完成，后续托管不影响该结果
+        S->>N: subject 立即尝试发布完整 proof 的 agent.md
+        Note over S,N: 发布失败保留 pending 上传，仍继续尝试托管
+        S->>S: 上传加密 identity 并授予 owner 读取权限
+        S->>M: escrow.ready（下载地址、密码、摘要）
+        M->>O: SDK 拦截、验证 escrow.ready
+        O->>S: 下载加密 identity
+        O->>O: 解密 identity，以 subject 证书签署 agent.md
+        O->>N: 携带 owner 签名授权头上传 agent.md
+        O->>M: agent_md.updated
+        M->>S: SDK 拦截并下载同步 agent.md
+    else 应用拒绝
+        S->>M: bind.reject
+        M->>O: SDK 记录拒绝结果
+    end
+```
+
+### 3.3 subject 发起：`BindOwner`
+
+1. subject 创建 role 为 `subject` 的声明并签名，将单方 proof 写入本地 metadata 和本地 `agent.md`，再上传这个带 owner 声明的不完整 `agent.md`，最后发送 `bind.request`。在 owner 确认前，外部可观察到这份单方声明，但关系状态仍不完整。
+2. owner SDK 验证请求并向 owner 应用发布 `ownership.request`，等待应用决策。
+3. owner 应用接受后调用 `acceptOwnershipRequest(request_id)`；SDK 创建 owner 声明并发送 `bind.response`。应用拒绝则发送 `bind.reject`。
+4. subject 收到双方 proof 完整的 `bind.response` 后保存并自行签名上传完整 proof 的 `agent.md`，随后自动上传加密 identity 并发送 `escrow.ready`。
+5. owner SDK 自动下载托管 identity，使用 subject 证书签署 `agent.md`，再使用 owner 签名的上传授权头上传。
+6. owner 上传成功后发送 `agent_md.updated`，subject SDK 自动下载、验证并同步。
+
+托管或代上传失败不会使第 3 步已经成立的关系失效，也不会触发应用层的第二次确认。
+
+```mermaid
+sequenceDiagram
+    participant S as subject SDK
+    participant M as AUN 加密 P2P
+    participant O as owner SDK
+    participant A as owner 应用
+    participant N as subject Name Service
+    S->>S: 独立签署 subject 声明并保存到 metadata 和本地 agent.md
+    S->>N: 上传 subject 自己签名的不完整 proof agent.md
+    S->>M: bind.request（subject 声明和签名）
+    M->>O: SDK 拦截、验证 bind.request
+    O->>A: ownership.request（验证后的绑定申请）
+    A->>O: acceptOwnershipRequest 或 rejectOwnershipRequest
+    alt 应用接受
+        O->>O: 独立签署 owner 声明并保存 proof
+        O->>M: bind.response（owner 声明和签名）
+        M->>S: SDK 拦截并验证 bind.response
+        Note over S,O: 关系签署已完成，后续托管不影响该结果
+        S->>N: subject 立即尝试发布完整 proof 的 agent.md
+        Note over S,N: 发布失败保留 pending 上传，仍继续尝试托管
+        S->>S: 上传加密 identity 并授予 owner 读取权限
+        S->>M: escrow.ready（下载地址、密码、摘要）
+        M->>O: SDK 拦截、验证 escrow.ready
+        O->>S: 下载加密 identity
+        O->>O: 解密 identity，以 subject 证书签署 agent.md
+        O->>N: 携带 owner 签名授权头上传 agent.md
+        O->>M: agent_md.updated
+        M->>S: SDK 拦截并下载同步 agent.md
+    else 应用拒绝
+        O->>M: bind.reject
+        M->>S: SDK 记录拒绝结果
+    end
+```
+
+### 3.4 self-owner
+
+self-owner 表示 `subject_aid == owner_aid`：只保留 subject 签名，不上传 escrow，不包含 `owner_signature`，并由本地 subject 签名和上传 `agent.md`。四个 SDK 的 `bindAid` / `bindOwner` 都在本地处理该分支，不发送绑定 P2P 消息。
+
+### 3.5 解绑：`release.request`
+
+解绑没有独立的服务端 RPC，也不支持 subject 发起。原 owner 调用 `releaseOwnership(subjectAid)`，使用当前关系的 `proof_id` 生成 `ownership_release`，并用 owner 证书签署带 `signed_at` 的 release statement，通过加密 P2P 发送给 subject。SDK 只接受来自原 owner 的请求，并要求本地 active 记录或本地 `agent.md` 中存在同一 `proof_id` 的完整双方 proof；缺少关系证据时消息被拦截，不执行 rekey。
+
+subject 收到并验证后自动执行以下步骤，应用层不需要再次确认：
+
+1. 持久化 `pending_rekey`、release 声明和本地 `agent.md` 快照。
+2. 参考创建 AID 的恢复机制执行 rekey；成功后进入 `pending_agent_md`。
+3. 比较本地与 Name Service 的 `agent.md` 尾部签名时间戳，选择较新版本作为基底；时间相同优先服务端版本。
+4. 删除 `owner`、`ownership_proof`，保留 `ownership_release`，用新 subject 证书签名并持久化待上传内容，进入 `pending_upload`。
+5. 上传成功后记录 `released`；若远端已经存在相同 release 的 `agent.md`，可直接收敛为 `released`。
+
+`ownership_release` 是旧 owner 的历史声明，服务端按声明的 `signed_at` 验证旧证书在签署时有效，不要求该证书当前仍为 `active_signing`。Name Service 同时把 release 的 subject、owner、proof_id 与服务端保存的当前 ownership 关系匹配；不匹配时拒绝上传。解绑完成后，新的 `agent.md` 不再包含 owner/proof，只有 `ownership_release` 用于说明原关系已释放。
+
+```mermaid
+sequenceDiagram
+    participant O as 原 owner SDK
+    participant M as AUN 加密 P2P
+    participant S as subject SDK
+    participant N as Name Service
+    O->>O: 读取 active 关系并签署 ownership_release
+    O->>M: release.request（owner 签名声明）
+    M->>S: SDK 拦截并验证 sender、proof_id、旧 owner 证书
+    S->>S: 校验本地 active metadata 或完整 agent.md proof
+    S->>S: 持久化 pending_rekey
+    S->>S: rekey，成功后进入 pending_agent_md
+    S->>N: 下载当前 agent.md
+    S->>S: 按尾部签名时间戳选择较新基底，移除 owner/proof，保留 ownership_release
+    S->>S: 持久化 pending_upload
+    S->>N: 上传新 subject 签名的 agent.md
+    N->>N: 验证 release 与已保存关系匹配，按 signed_at 验证旧 owner 证书
+    N-->>S: 上传成功
+    S->>S: 标记 released
+```
+
+## 4. ownership 声明与签名
+
+P2P 消息内的声明为 v2：
+
+```json
+{
+  "version": 2,
+  "proof_id": "uuid-v4-lowercase",
+  "subject_aid": "subject.agentid.pub",
+  "owner_aid": "owner.agentid.pub",
+  "signer_aid": "owner.agentid.pub",
+  "role": "owner"
+}
+```
+
+`extensions` 是可选字段；有值时进入各自签名的声明，双方不要求扩展字段相同。v2 声明包含 Unix 秒级 `signed_at`，签名输入覆盖该时间；各 SDK 下载端验签会检查证书在此时间有效。
+
+签名输入为：
+
+```text
+UTF-8("AUN-AID-OWNER-RELATION-V1;") || canonical_json(statement)
+```
+
+`canonical_json` 使用 UTF-8、字典序键、无空格；AID 使用小写规范形式。签名封套至少包含 `cert_fingerprint` 和严格 Base64 的 `signature`，可带 `signer_aid`、`role` 和签署时使用的 `statement`。`proof_id` 必须为小写 UUID v4。
+
+上传的关系版 `agent.md` 在 frontmatter 中同时包含 `owner` 和 `ownership_proof`：
+
+```yaml
+owner: owner.agentid.pub
+ownership_proof:
+  proof_id: ...
+  subject_aid: subject.agentid.pub
+  owner_aid: owner.agentid.pub
+  subject_signature:
+    cert_fingerprint: ...
+    signature: ...
+    statement: {version: 2, signer_aid: subject.agentid.pub, role: subject, ...}
+  owner_signature:
+    cert_fingerprint: ...
+    signature: ...
+    statement: {version: 2, signer_aid: owner.agentid.pub, role: owner, ...}
+```
+
+subject 与外部 owner 时必须有两份签名；self-owner 必须省略 `owner_signature`。`human` 类型不能携带 owner 或 ownership proof。
+
+## 5. identity escrow
+
+subject 上传的是包含 `aid`、`private_key_pem`、公钥和证书的完整 identity 包，不是明文证书。四端使用相同 envelope：
+
+- AES-256-GCM；
+- PBKDF2-SHA256，200000 次迭代；
+- 16 字节 salt、12 字节 nonce；
+- `sha256` 校验解密后的明文；
+- AAD 为 `AUN-CERT-ESCROW-V1`。
+
+对象路径约定为：
+
+```text
+/.aun/ownership/<lowercase_subject_aid>/<proof_id>.json
+```
+
+对象写入 subject 自己的 Storage。subject 只向 owner 授予 `r` 权限；密码和下载地址通过加密 P2P 消息发送。当前 escrow 包含 subject 私钥，因此 owner 获得的是可用于 subject 签名的完整 identity，而不只是证书。owner 下载解密后，SDK 将完整 identity 导入既有身份存储并加密保存私钥，再用于签署 subject 的 `agent.md`；内存中的 `subject_identity` 仅作 signer 缓存。公开 ownership 状态不会返回 identity 或 escrow 密码。
+
+下载票据有多个 URL 时，四端沿用 Storage 下载约定，按 `logical_url`、`download_url`、`url` 的顺序选择。`logical_url` 是 Storage 对外数据面地址，可避免公开 AID URL 重定向后丢失认证头。测试网络须能解析票据中的 subject AID 和 Storage 服务域名。
+
+### owner 本地托管材料的实际保存位置
+
+owner 下载并解密 escrow 后，四端都调用已有身份存储的导入能力持久化完整 subject identity；`subject_identity` 只作为运行时 signer 缓存，不作为公开 ownership metadata 保存：
+
+| SDK | 持久化位置 | 私钥保护 |
+| --- | --- | --- |
+| TypeScript / Go / Python | `{aunPath}/AIDs/{subjectAid}/private/key.json`（加密私钥）和 `{aunPath}/AIDs/{subjectAid}/public/cert.pem`（证书） | 沿用对应 `AIDStore`/`LocalIdentityStore` 的 `encryptionSeed`/`seed_password`；Go 同时保留历史证书缓存供按指纹验签 |
+| JavaScript 浏览器 | IndexedDB 数据库 `aun-keystore` 的 `key_pairs`、`certs` 对象仓库，键为 subject AID | 沿用 `IndexedDBIdentityStore` 的 `encryptionSeed` 对私钥 PEM 加密 |
+
+文件型 SDK 的 `{aunPath}` 是 client/AIDStore 配置的 AUN 数据根；目录不存在时由身份存储创建。导入会先校验证书所属 AID、公钥与私钥匹配，再写入上述位置并重新加载自检。进程重启后 owner 通过同一 AIDStore/IndexedDB 读取 subject identity，不依赖内存中的 `subject_identity` 字段。
+
+```mermaid
+sequenceDiagram
+    participant S as subject SDK
+    participant T as subject Storage
+    participant M as AUN 加密 P2P
+    participant O as owner SDK
+    S->>S: 打包 identity，生成密码并加密
+    S->>T: 上传加密 envelope 到 escrow_path
+    S->>T: 对该对象授予 owner 读取权限
+    T-->>S: 下载地址
+    S->>M: escrow.ready（地址、密码、摘要）
+    M->>O: SDK 拦截并校验关系声明和签名
+    O->>T: 以 owner 身份下载加密对象
+    T->>T: 校验 subject 授予的读取 ACL
+    T-->>O: 加密 envelope
+    O->>O: 解密并校验 subject 身份，导入身份存储并加密持久化私钥
+```
+
+proof 完整、owner 已拿到托管 identity、代上传成功是三个独立结果。关系签名本身不证明托管或上传已完成。各 SDK 将关系 proof 和编排进度写入本地 metadata；进程重启后恢复待发送消息、待应用确认的申请、active 关系的未完成步骤，以及解绑的 `pending_rekey`/`pending_agent_md`/`pending_upload`。owner 从本地身份存储重新加载已托管的 subject signer；尚未取得材料时重发绑定响应，让 subject 重新发出托管通知。托管密码和下载地址不写入公开状态。
+
+## 6. owner 代签名与上传 `agent.md`
+
+owner 只有在拿到 subject identity 后才执行代签名上传：
+
+1. 用解密得到的 subject 私钥对关系版完整内容签名；
+2. 使用 owner 私钥生成 `X-AUN-AgentMD-Owner-Authorization`，调用 Name Service 的 `PUT /agent.md`；该上传不使用 owner bearer token；
+3. 在本地记录上传结果；
+4. owner 上传成功后发送 `agent_md.updated`；subject SDK 收到后下载并同步本地缓存。
+
+因此 agent.md 的内容签名者是 subject，上传授权者是 owner。subject 自行上传时 Name Service 从 bearer token 取得上传者 AID；owner 代上传时 SDK 不使用 bearer token，而携带 `X-AUN-AgentMD-Owner-Authorization`。该授权将目标 AID、上传者、正文摘要、时间戳、nonce 和 owner 签名绑定；Name Service 从经验证的 owner 证书取得上传者 AID，并校验授权及 ownership proof，不能只相信 frontmatter。owner 或 subject 属于外域时，Name Service 通过 Gateway 的 `gateway.resolve_verified_aid_cert` 获取并校验证书链和 OCSP。
+
+服务端上传验证要求：
+
+- `agent.md` 的主体签名有效，签名证书属于 subject；
+- owner 代上传时要求 subject 与 owner 两份 ownership 签名都有效；self-owner 只要求 subject 签名；subject 自行上传时允许 proof 不完整；
+- `agent.md` 主体签名证书及 proof 中已提供的 ownership 签名证书在上传验证时必须为 `active_signing`；
+- AID、owner、proof、签名角色和证书指纹彼此匹配。
+
+下载端验证主体 `agent.md` 签名及其签名时间，并验证 proof 中每份 ownership 签名、签署者、证书指纹和证书在 `signed_at` 时的有效期；下载端不要求这些证书当前仍是 `active_signing`。Name Service 上传验证则要求文件签名证书及 proof 中已有的签名证书在上传时均为 `active_signing`，并检查各 ownership 签名的 `signed_at` 落在证书有效期内。
+
+```mermaid
+sequenceDiagram
+    participant O as owner SDK
+    participant N as subject Name Service
+    participant S as subject SDK
+    O->>O: 读取已托管的 subject 私钥和证书
+    O->>O: 用 subject identity 签署 agent.md
+    O->>O: 用 owner identity 签署上传授权
+    O->>N: PUT /agent.md（subject 内容签名、owner 签名的上传授权头）
+    N->>N: 验证上传者确为该 subject 的 owner
+    N->>N: 验证完整 ownership proof 和所有相关 active_signing 证书
+    N->>N: 验证 subject 文件签名，保存 agent.md
+    N-->>O: 上传结果和 ETag
+    O-->>S: agent_md.updated
+    S->>N: 下载 agent.md
+    N-->>S: agent.md
+    S->>S: 分别验证文件与 ownership，同步本地缓存
+```
+
+文件有效性与 ownership 完整有效性是两个层面：subject 可自行签名并上传带有 owner 声明或不完整 proof 的 `agent.md`；Name Service 会校验其中已提供的每一份 ownership 签名，但不因 proof 不完整而拒绝 subject 自身上传。owner 代上传必须同时具备托管 identity 和完整有效关系；不完整 proof 不授予该权限。
+
+## 7. SDK 消息拦截与状态
+
+SDK 收到 `aun.ownership.v1` 后先做以下检查：
+
+- 当前 AID 必须是 subject 或 owner；
+- sender 必须是关系另一方；
+- `request_id` 必须非空；除 `bind.request` 外，消息的 `request_id` 和 `proof_id` 必须匹配本地同一关系记录，且该记录不能仍待应用确认或已拒绝；
+- `proof_id`、双方 AID、role、signer_aid 必须匹配；
+- 用对端证书验证签名；
+- 验证失败时吞掉该 ownership 消息，不投递到应用层。
+
+本地状态仅用于展示和编排：`pending` 表示本地记录仍在绑定流程中，`active` 由 SDK 根据签名和协议消息在本地计算，`pending_rekey`、`pending_agent_md`、`pending_upload` 表示解绑恢复阶段，`released` 表示解绑后的名片已收敛，`legacy_unbound` 表示尚无本地关系记录。各 SDK 将 proof 和状态写入本地 AID metadata，但这不是服务端事务状态或上传成功回执；进程重启后 SDK 会自动恢复上述 pending 阶段。SDK 在 ownership 消息验证失败或处理失败时仍拦截该消息，不投递给应用层。
+
+## 8. 与其它服务的边界
+
+| 组件 | 责任 |
+| --- | --- |
+| SDK | 生成声明和签名、发送/拦截 P2P、上传/下载 escrow、owner 代签和本地同步 |
+| Message/Gateway | 按现有消息协议转发加密 P2P，不解析 ownership 业务 |
+| Storage | 保存 subject 加密 identity，执行 subject 授予 owner 的对象 ACL |
+| Name Service | 保存 `agent.md`，校验上传 token、主体签名和 ownership proof；不保存 ownership 关系台账 |
+| Auth/CA | 提供已有 AID、token 和证书验证能力；不新增 ownership RPC，不维护关系状态 |
+
+应用层只调用 SDK 的绑定方法和状态查询方法，不直接调用 Auth ownership RPC，也不直接消费 `aun.ownership.v1` 消息。
+
+## 9. 当前实现边界
+
+- 服务端不维护 ownership 台账，也不提供换 owner RPC。当前 owner 被服务端保存的 `agent.md` 锁定；清空或更换 owner 的普通上传会被拒绝，必须先由原 owner 发起 `release.request` 并上传带 `ownership_release` 的无 owner 文档。SDK 本地记录仍按 subject/owner AID 对保存，应用层应以 `getOwner()` 返回的 active 关系为当前关系。
+- 四端都允许绑定发起方通过 API 提供自己的 `extensions`；应用层接受绑定请求时也可通过 `acceptOwnershipRequest(request_id, { extensions })` 为本端声明提供扩展字段。双方扩展字段独立，不要求相同。
+- owner authorization 校验目标、上传者、正文摘要、时间窗、nonce 字段和 owner 签名；当前 Name Service 没有持久化 nonce 重放记录，因此时间窗内的重放防护不由该 nonce 单独保证。
+- owner 得到 subject 私钥后可代表 subject 生成签名。加密、subject Storage ACL 和加密 P2P 用于限制传输与读取对象，不改变该授权本身的能力范围。
+- 会话约定的其它 Storage ACL 或证书备份由 owner 授权、由 agent 自愿配合；当前 ownership 实现只为加密 identity escrow 对象写入 subject 授予 owner 的 `r` ACL，没有通用备份目录、备份 ACL 生命周期或额外备份 RPC。AID 已可由 SDK 加载/寻址后，应用层通过 `bindAid`/`bindOwner` 编排关系；Auth 注册流程不属于 ownership 协议，也不应通过裸 ownership RPC 完成绑定。
+
+## 10. 实现索引
+
+- Go：`go/ownership_client.go`、`go/ownership_protocol.go`、`go/ownership_proof.go`、`go/agent_md_manager.go`
+- Python：`python/src/aun_core/client.py`、`python/src/aun_core/ownership.py`、`python/src/aun_core/ownership_protocol.py`、`python/src/aun_core/agent_md.py`
+- TypeScript：`ts/src/client.ts`、`ts/src/ownership-proof.ts`、`ts/src/agent-md.ts`
+- JavaScript：`js/src/client.ts`、`js/src/ownership-proof.ts`、`js/src/agent-md.ts`
+- Name Service：`../extensions/services/nameservice/go/internal/httpserver/agentmd.go`、`agent_md_schema.go`
+- 测试：`python/tests/test_ownership_proof.py`、`python/tests/e2e_test_ownership.py`、`go/ownership_proof_test.go`、`ts/tests/unit/client-agent-md-api.test.ts`、`js/tests/unit/client-agent-md-api.test.ts`、`tests/cross-sdk/cases.single-domain.json`
+