@agentunion/fastaun-browser 0.5.19 → 0.5.21

package/_packed_docs/sdk/Ownership-SDK/351/233/206/346/210/220/346/214/207/345/215/227.md

@@ -0,0 +1,270 @@
+# Ownership SDK集成指南
+
+本文是 legacy 集成记录，实现基准为 2026-10-09 工作区代码，不代表当前 Ownership 2.1。当前应用接入、审批及新鲜共识见 [Ownership 2.1 SDK 应用集成指南](Ownership2.1-SDK应用集成指南.md)；下文旧 proof、自动 escrow 和代上传流程不能作为 2.1 接入方式。
+
+## 1. TypeScript快速集成
+
+### 1.1 加载双方身份
+
+示例使用Node.js SDK `@agentunion/fastaun`，当前源码要求Node.js >= 22.16.0。owner与subject已经注册，分别持有自己的证书和私钥；将示例AID、数据目录及密钥保护种子替换为应用已有配置。两端通常运行在不同进程，下面并列展示各自的接入代码。
+
+```bash
+npm install @agentunion/fastaun
+```
+
+```ts
+import { AIDStore, AUNClient } from '@agentunion/fastaun';
+
+function loadClient(store: AIDStore, aid: string): AUNClient {
+  const loaded = store.load(aid);
+  if (!loaded.ok) throw new Error(loaded.error.message);
+  return new AUNClient(loaded.data.aid);
+}
+```
+
+```ts
+const ownerStore = new AIDStore({ aunPath: './.aun-owner', encryptionSeed: process.env.OWNER_KEY_SEED ?? '', verifySsl: true });
+const subjectStore = new AIDStore({ aunPath: './.aun-subject', encryptionSeed: process.env.SUBJECT_KEY_SEED ?? '', verifySsl: true });
+const owner = loadClient(ownerStore, 'owner.agentid.pub');
+const subject = loadClient(subjectStore, 'subject.agentid.pub');
+```
+
+`OWNER_KEY_SEED`、`SUBJECT_KEY_SEED`是本示例的应用环境变量，用于读取已有身份的保护种子。`AUNClient`接收`AID`对象；`store.load()`是同步方法，返回`Result`，联网的绑定方法则是异步方法。
+
+### 1.2 接入应用审批，再连接
+
+接收方订阅`ownership.request`。SDK已经验证申请声明，事件直接传入请求字段；应用将它接入确认界面或自己的审批逻辑。接受关系会继续自动托管subject的完整identity，其中包含私钥，审批界面应让使用者理解这项授权。
+
+```ts
+function subscribeRequests(client: AUNClient): void {
+  client.on('ownership.request', (payload) => {
+    const request = payload as { request_id: string; requester_aid: string };
+    console.log('待审批的ownership申请', request);
+  });
+}
+subscribeRequests(owner);
+subscribeRequests(subject);
+```
+
+以下函数供应用的接受/拒绝操作调用。`requestId`取自对应客户端收到的事件；`extensions`写入接受方自己的签名声明。
+
+```ts
+async function decideOwnership(client: AUNClient, requestId: string, accepted: boolean) {
+  if (accepted) return client.acceptOwnershipRequest(requestId, {
+    extensions: { application: 'clinic-app' },
+  });
+  return client.rejectOwnershipRequest(requestId);
+}
+await Promise.all([owner.connect(), subject.connect()]);
+```
+
+监听器在`connect()`前注册，便于接收连接恢复时重新发布的待审批申请。应用回调收到的是请求对象，不需要再读取一层`payload`。
+
+### 1.3 owner发起绑定
+
+owner应用执行：
+
+```ts
+const sent = await owner.bindAid('subject.agentid.pub', {
+  subjectType: 'agent',
+  requestId: 'clinic-bind-001',
+  extensions: { department: 'clinic' },
+});
+console.log('绑定申请发送结果', sent);
+```
+
+subject应用收到事件后，使用事件中的`request_id`调用`decideOwnership(subject, request_id, true)`或`decideOwnership(subject, request_id, false)`。接受后，SDK自动回复、发布关系名片、托管identity并推进owner代上传；应用只需完成一次审批。
+
+`await bindAid()`表示申请的消息发送调用结束，双方关系的完成需要等待接受方确认。这个区别与IM系统的“消息发送成功”和“对方已处理”相同。
+
+### 1.4 subject发起绑定
+
+也可以由subject应用发起，作为上一节的另一种入口：
+
+```ts
+await subject.bindOwner('owner.agentid.pub', {
+  subjectType: 'agent',
+  extensions: { application: 'clinic-app' },
+});
+```
+
+这时由owner应用处理`ownership.request`，调用`decideOwnership(owner, request_id, accepted)`。subject SDK会先尝试上传只有subject签名的关系名片，然后等待owner确认。`subjectType`是本次关系记录的类型信息；SDK修改已有名片时保留原有`type`、其它frontmatter和正文，它不是通用的类型修改入口。
+
+### 1.5 查询本地关系与公开名片
+
+```ts
+const state = subject.getOwnershipStatus();
+console.log('本地关系状态', state.status, state.proof_id);
+console.log('本地owner与类型', subject.getOwner(), subject.getType());
+
+const published = await subjectStore.downloadAgentMd('subject.agentid.pub');
+if (!published.ok) throw new Error(published.error.message);
+console.log('文件与关系验签', published.data.verification);
+```
+
+按三个结果分别判断：
+
+| 需要判断的结果 | 观察方式 | 含义 |
+| --- | --- | --- |
+| 双方是否已签署 | 本地`status === 'active'`，并核对双方AID及`proof_id` | 本端已保存完整关系；self-owner为subject单签 |
+| owner代上传及通知是否结束 | owner侧的`agent_md_uploaded`、`agent_md_notified` | owner本地编排进度，不是subject同步回执 |
+| subject是否已同步名片 | subject侧的`agent_md_synced`；公开名片的`verification` | 文件验签结果与ownership结果分别检查；完整公开关系为`ownership_status === 'complete'` |
+
+`getOwner()`优先返回active关系，也可能返回pending等尚未释放的记录，因此仅有owner值不足以确认绑定完成。`getOwnershipStatus()`选择一条涉及当前AID的关系并优先active；owner管理多个subject时，它不返回全量列表，应用应同时核对目标subject。
+
+当前进度字段来自本地metadata，字段未出现通常表示该步骤尚未记录。完整proof可以先于托管和owner代上传公开；托管失败不会撤销双方已完成的签名关系。
+
+### 1.6 self-owner与解绑
+
+self-owner在subject本地完成：
+
+```ts
+await subject.bindOwner(subject.aid!);
+```
+
+该入口只生成subject签名、上传本端名片，不发送绑定申请、不托管identity，也不需要应用审批。`human`名片不允许声明owner，包括self-owner。
+
+外部owner释放关系：
+
+```ts
+await owner.releaseOwnership('subject.agentid.pub');
+```
+
+subject SDK验证原关系后自动rekey、保留名片业务内容、删除`owner`和`ownership_proof`、写入`ownership_release`并上传。subject侧最终为`status: released`、`release_status: released`，公开名片的关系验签状态为`released`。
+
+解绑方法返回的是释放消息发送结果。owner本地的`release_status: notified`表示已发起通知；当前没有释放完成的P2P回执，确认最终结果应查看subject状态或下载其公开名片。换owner时先完成释放，再重新绑定；subject没有单方解除入口。
+
+应用业务结束、后续编排已经完成时关闭客户端：
+
+```ts
+await Promise.all([owner.close(), subject.close()]);
+```
+
+## 2. 应用需要使用的SDK方法
+
+| TypeScript方法 | 调用方 | 返回与边界 |
+| --- | --- | --- |
+| `bindAid(subjectAid, options?)` | owner | 异步；创建owner声明并发送申请 |
+| `bindOwner(ownerAid, options?)` | subject | 异步；创建subject声明；self-owner在本地完成 |
+| `acceptOwnershipRequest(requestId, { extensions }?)` | 申请接收方 | 异步；只处理本端待审批申请，签署本端声明并推进后续流程 |
+| `rejectOwnershipRequest(requestId)` | 申请接收方 | 异步；拒绝申请并发送`bind.reject` |
+| `releaseOwnership(subjectAid)` | 原owner | 异步；要求本地active关系，发送释放声明 |
+| `getOwner()` / `getType()` / `getOwnershipStatus()` | 双方 | 同步；读取本地摘要，排除identity、托管密码和下载地址 |
+
+绑定选项为`subjectType`、`requestId`、`extensions`，前两项也接受`subject_type`、`request_id`。默认类型为`agent`，未传请求ID时SDK生成ID；每次调用绑定方法都会创建新`proof_id`，复用`requestId`不构成整个绑定API的幂等保证。发送中断后的恢复应保留原数据目录，由SDK续跑原记录。
+
+## 3. SDK层面的绑定编排
+
+### 3.1 owner发起
+
+```mermaid
+sequenceDiagram
+    participant OA as owner应用
+    participant O as owner SDK
+    participant M as 加密P2P
+    participant S as subject SDK
+    participant SA as subject应用
+    OA->>O: bindAid(subjectAid)
+    O->>O: 签署owner声明，持久化pending
+    O->>M: bind.request
+    M->>S: 解密后拦截并验证申请
+    S->>S: 保存待审批记录
+    S->>SA: ownership.request
+    alt 应用接受
+        SA->>S: acceptOwnershipRequest(request_id)
+        S->>S: 签署subject声明，持久化active
+        S->>M: bind.response
+        M->>O: 验证subject声明，持久化active
+        S->>S: 立即发布完整proof名片，之后独立尝试identity托管
+    else 应用拒绝
+        SA->>S: rejectOwnershipRequest(request_id)
+        S->>M: bind.reject
+        M->>O: 记录rejected
+    end
+```
+
+### 3.2 subject发起
+
+```mermaid
+sequenceDiagram
+    participant SA as subject应用
+    participant S as subject SDK
+    participant N as subject Name Service
+    participant O as owner SDK
+    participant OA as owner应用
+    SA->>S: bindOwner(ownerAid)
+    S->>S: 签署subject声明，持久化pending
+    S->>N: 尝试上传不完整proof名片
+    S->>O: 加密P2P bind.request
+    O->>O: 验证并保存待审批记录
+    O->>OA: ownership.request
+    alt 应用接受
+        OA->>O: acceptOwnershipRequest(request_id)
+        O->>O: 签署owner声明，持久化active
+        O->>S: 加密P2P bind.response
+        S->>S: 验证并保存完整proof，标记active并立即发布名片
+    else 应用拒绝
+        OA->>O: rejectOwnershipRequest(request_id)
+        O->>S: 加密P2P bind.reject
+        S->>S: 记录rejected
+    end
+```
+
+双方分别签署自己的声明；`proof_id`和双方AID相同，`signed_at`和`extensions`可以不同。`ownership.request`是SDK本地应用事件，原始`aun.ownership.v1`控制消息由SDK消费。
+
+## 4. SDK自动托管、代上传和同步
+
+两个绑定方向在subject取得完整proof后立即发布关系名片，再独立尝试托管；发布和托管分别记录进度：
+
+```mermaid
+sequenceDiagram
+    participant S as subject SDK
+    participant T as subject Storage
+    participant O as owner SDK
+    participant K as owner身份存储
+    participant N as subject Name Service
+    S->>N: subject立即尝试发布完整proof名片
+    Note over S,N: 发布失败保留pending上传，不阻止托管
+    S->>S: 打包identity，生成密码并加密
+    S->>T: 上传envelope，写owner的r ACL，申请下载票据
+    S->>O: 加密P2P escrow.ready
+    O->>T: 使用票据下载加密envelope
+    O->>O: 解密，校验subject身份与密钥
+    O->>K: 导入subject identity并加密保存私钥
+    O->>O: 用subject私钥签名片，用owner私钥签上传授权
+    O->>N: PUT /agent.md，携带owner授权头
+    N->>N: 验证完整proof、上传者与subject文件签名
+    N-->>O: 上传结果与ETag
+    O->>S: 加密P2P agent_md.updated
+    S->>N: 下载、验签并保存本地名片
+```
+
+subject自行上传名片和identity托管分别尝试；一个步骤失败不会阻止另一项尝试。owner得到的是能代表subject签名的identity。名片内容签名者始终是subject，HTTP上传授权者可以是owner。
+
+当前SDK仅为该escrow对象写入owner读取ACL；其它业务目录的授权、备份策略与清理不属于这段自动编排。跨issuer下载使用资源所在域签发的票据；同issuer下载可携带当前access token。
+
+## 5. SDK自动解绑与中断恢复
+
+```mermaid
+flowchart TD
+    A[原owner签署并发送release.request] --> B[subject验证sender、release和当前关系证据]
+    B --> C[持久化release_status为pending_rekey]
+    C --> D[恢复或完成rekey并载入新身份]
+    D --> E[进入pending_agent_md]
+    E --> F[比较本地与远端尾部签名时间，选择较新名片]
+    F --> G[移除owner和proof，保留release及业务内容]
+    G --> H[持久化pending_upload及待上传内容]
+    H --> I[用新subject证书签名并上传]
+    I --> J[上传成功，标记released]
+```
+
+rekey阶段可能断开并重新连接；待处理记录和待上传名片跨重启保存。名片时间相同优先使用远端版本。若远端已经保存同一份有效release，SDK可直接收敛到released。
+
+绑定恢复遵循已有IM消息的异步处理方式：保存待发控制消息，重连后重发；待审批申请重新发布给应用；subject重试名片发布和托管；owner从本地身份存储恢复subject signer。若owner尚未获得材料，会重发自己的绑定响应，让subject重新发送托管通知。恢复依赖同一AID的数据目录及密钥保护配置。
+
+## 6. 实现与协议入口
+
+- SDK移植、持久化与验收：[Ownership SDK实现指南](Ownership-SDK实现指南.md)。
+- 消息schema、proof、agent.md和现有RPC：[Ownership协议定义](../protocol/Ownership协议定义.md)。
+- 原专题与完整消息样例：[Ownership管理专题](Ownership管理专题.md)。
+- 示例对应源码：[client.ts](../../ts/src/client.ts)、[aid-store.ts](../../ts/src/aid-store.ts)、[ownership-proof.ts](../../ts/src/ownership-proof.ts)、[agent-md.ts](../../ts/src/agent-md.ts)。