@agentunion/fastaun-browser 0.5.18 → 0.5.20

package/_packed_docs/sdk/Ownership-SDK/347/274/226/346/216/222/346/214/207/345/215/227.md

@@ -0,0 +1,349 @@
+# Ownership SDK编排指南（3.0）
+
+本文定义 [Ownership 协议3.0](../protocol/Ownership协议定义3.0.md) 的主要应用场景与 SDK 编排契约。TypeScript 方法是拟定接口，用于说明调用和返回语义，不表示当前发布的 SDK 已提供这些方法。
+
+参考基线为 Git 提交 `1f03bf2d` 中的 0.5.18：复用 Auth operation、幂等键、关系版本 CAS、证书校验和可恢复任务；保留2.0的各方独立文件声明，删除旧 SDK 的自动 identity 导入、代签、代上传和 ownership 专用 P2P 编排。当前工作区与该基线可能不同，实现时须按3.0契约核对。
+
+## 1. 应用层快速接入
+
+示例假设 `sub`、`owner`、`nextOwner` 分别是持有自己身份的 SDK 实例，已连接相应服务；托管关闭，服务能力完整。各方调用并列展示，实际由各自应用在独立进程中执行。应用通过自己的审批界面和已有消息传递 operation_id，各 SDK 都从关系权威重新读取上下文，不能把通知当作授权。
+
+### 1.1 绑定
+
+```ts
+const op = await sub.declareOwneraid('owner.agentid.pub', { idempotencyKey: 'bind-001' });
+const id = op.operation_id;
+await owner.declareSubaid('subject.agentid.pub', { operationId: id });
+await sub.approveOwnershipOperation(id);
+await owner.approveOwnershipOperation(id);
+await sub.resumeOwnershipOperation(id);
+await owner.resumeOwnershipOperation(id);
+const checked = await sub.checkOwnershipConsensus('subject.agentid.pub');
+```
+
+`declare*` 生成本端签名文件证据；证据齐全后上下文冻结，应用确认后才调用 `approveOwnershipOperation`。两方授权齐全后，任一参与方可通过 resume 推进提交；提交后双方各自 resume 发布自己的文件。SDK 不用一方身份上传另一方文件。
+
+应用记录稳定的幂等键和 operation_id，不以“方法返回成功”判断关系全部完成。只有 `checked.authorized === true` 才开放需要完整 owner 共识的功能。
+
+### 1.2 转移
+
+`currentVersion` 来自当前权威关系查询。转移由当前 owner 创建，sub_aid 与新 owner 参与同一 operation：
+
+```ts
+const op = await owner.transferSubaid('subject.agentid.pub', 'next-owner.agentid.pub', {
+  expectedRelationVersion: currentVersion, idempotencyKey: 'transfer-001',
+});
+await sub.declareOwneraid('next-owner.agentid.pub', { operationId: op.operation_id });
+await nextOwner.declareSubaid('subject.agentid.pub', { operationId: op.operation_id });
+await owner.approveOwnershipOperation(op.operation_id);
+await sub.approveOwnershipOperation(op.operation_id);
+await nextOwner.approveOwnershipOperation(op.operation_id);
+```
+
+之后各方用该 operation_id 调用 resume。当前 owner 的同意、sub_aid 的同意和新 owner 的接受缺一不可。版本冲突时重新读取关系并重新审批，SDK 不自动用最新版本覆盖原 expected version。
+
+### 1.3 解绑
+
+当前 owner 发起释放：
+
+```ts
+const op = await owner.revokeSubaid('subject.agentid.pub', { idempotencyKey: 'release-001' });
+await owner.approveOwnershipOperation(op.operation_id);
+await owner.resumeOwnershipOperation(op.operation_id);
+```
+
+sub_aid 也可以调用 `revokeOwneraid({ idempotencyKey })` 发起解绑意向，但仍等待当前 owner 的 approval。未获授权时原关系保持 active，不能改文件后绑定别的 owner。解绑提交后，sub_aid 恢复在线时自行 resume，清除自己的 owner 字段并上传。
+
+若旧 owner 曾拿到可解密身份材料，转移和解绑会先等待第5节的凭据隔离，不能直接按以上无托管示例提交。
+
+## 2. SDK契约与职责
+
+### 2.1 主要方法
+
+| 方法 | 调用者 | 行为 |
+| --- | --- | --- |
+| `declareOwneraid(owner_aid, options)` | sub_aid | unbound 时创建 bind 并提交本端文件证据；给定 operationId 时加入对应 bind/transfer，不能替换当前 owner。 |
+| `declareSubaid(sub_aid, { operationId })` | 拟绑定/新 owner | 加入已有操作，提交自己 owner.md 的签名证据。 |
+| `transferSubaid(sub_aid, new_owner_aid, options)` | 当前 owner | 创建 transfer，固定当前 owner 与 expectedRelationVersion，不直接解绑。 |
+| `revokeSubaid(sub_aid, options)` | 当前 owner | 创建 release，使用当前关系证据，不直接删除文件代替解绑。 |
+| `revokeOwneraid(options)` | sub_aid | 创建 release 意向，不能替当前 owner 授权。 |
+| `approveOwnershipOperation(operation_id)` | 该操作的批准者 | 校验完整固定上下文，显式签署并提交本端角色的 approval；不自动批准其它意向。 |
+| `resumeOwnershipOperation(operation_id)` | 参与方 | 先查询权威阶段，继续本端任务；ready 时尝试幂等提交，committed 时只做发布/清理。 |
+| `cancelOwnershipOperation(operation_id)` | 发起者或必须授权的参与方 | 仅取消未提交操作，不回滚已完成的 rekey，不释放当前关系。 |
+| `checkOwnershipConsensus(sub_aid)` | 校验方 | 读取权威与双方文件，返回授权结论和可持久化证据。 |
+
+TypeScript options 使用 camelCase，协议数据使用 snake_case；其它语言采用自己的命名约定。SDK 的既有 Result/异常封装可以保留，但必须暴露下列分离的结果：
+
+| 返回信息 | 含义 |
+| --- | --- |
+| `operation_id`、`stage`、`waiting_for` | 意向已保存以及尚缺的参与方/任务。 |
+| `committed`、`commit_receipt`、`relation_version` | 权威关系是否已提交及不可变提交结果。 |
+| `publication_state`、`cleanup_state` | 必需文件是否公开收敛，旧文件与元数据是否清理。 |
+| `custody_state` | 可选托管自己的进度，不决定关系提交成功与否。 |
+| `authorized`、`document_state` | 当前完整共识检查结果，不能用本地缓存替代。 |
+
+默认调用只推进目前具备条件的阶段，返回等待原因，不无限等待另一方或文件服务。恢复可以由应用显式调用，也可以由 SDK 重连调度；重连只重试已经批准的任务，不代用户批准新操作。
+
+### 2.2 托管方法
+
+托管能力独立提供启用、查询、撤销和显式恢复入口。启用只能由 sub_aid 发起，应用提供 custodian、加密秘密或自己的密钥包装方式；默认 custodian 只拿密文。恢复在 sub_aid 自己的设备中显式解密、验证并导入，owner 客户端不装载 sub_aid 身份。
+
+无托管能力时，上述绑定、转移、解绑仍可使用；历史私钥外发带来的凭据隔离要求不能一起关闭。
+
+### 2.3 编排边界
+
+| 执行者 | 职责 |
+| --- | --- |
+| 应用 | 发起意向、通知参与方、确认审批、管理恢复秘密和业务审计。 |
+| 各方 SDK | 本端签名、证据提交、自有文件发布、任务持久化、能力判断与恢复。 |
+| sub_aid 的关系权威 | 验证参与者与证据、保存 operation、CAS 提交关系及审计回执。 |
+| Name Service / Storage | 校验当前版本与上传者、条件写入/删除、存储文件和可选密文。 |
+| Auth/CA | 证书、身份代际、必要的 rekey 与旧凭据失效确认。 |
+
+SDK不能把整个流程包装成一个必须全部成功才能返回的跨服务事务。稳定阶段为：
+
+```mermaid
+flowchart LR
+    P[prepared<br/>参数及准备任务已保存] --> A[awaiting_approvals<br/>证据与上下文已冻结]
+    A --> R[ready<br/>授权及安全条件齐全]
+    R --> C[committed<br/>权威关系与回执已保存]
+    C --> D[completed<br/>投影及清理已收敛]
+    P --> X[取消或过期<br/>原关系保留]
+    A --> X
+    R --> X
+```
+
+只有 ready→committed 是关系权威内部的小事务。可选托管另外计进度；completed 不等待可选托管服务恢复。
+
+## 3. 绑定与转移流程
+
+### 3.1 绑定
+
+```mermaid
+sequenceDiagram
+    participant S as sub_aid SDK
+    participant O as owner_aid SDK
+    participant R as sub_aid关系权威
+    participant N as Name Service
+    participant T as owner_aid Storage
+    S->>S: 保存intent与幂等键
+    S->>R: prepare bind，匹配unbound当前版本
+    R-->>S: operation_id、目标版本
+    S->>R: 本端签名agent.md证据
+    O->>R: 本端签名owner.md证据
+    R->>R: 验证证据，冻结操作上下文
+    S->>R: 应用确认后的sub_approval
+    O->>R: 应用确认后的owner_approval
+    R->>R: 授权齐全，持久化ready
+    S->>R: commit同一operation
+    R->>R: CAS关系、保存回执与审计
+    R-->>S: committed，新版本
+    par 各方自行发布
+        S->>N: 本端签名、本端认证上传agent.md
+    and
+        O->>R: 查询提交回执
+        O->>T: 本端签名、本端认证写owner.md
+    end
+    S->>R: 发布状态与当前关系复核
+    Note over S,T: 发布失败保留committed；共识功能等待完整投影
+```
+
+初始绑定为版本0→1；解绑后重绑使用保留的当前版本，例如5→6。SDK不能写死 expected version=0。self-owner 复用这条流程，由同一 AID 完成重合角色，仍创建两种文档投影，不启用自动托管。
+
+owner应用希望发起绑定时，先通过已有消息邀请sub_aid创建上述operation，再由owner加入；不允许拟绑定owner单方面抢占一个尚未同意的sub_aid操作。
+
+新注册场景先完成可独立使用的 AID 身份，再执行 bind；关系待审批不能锁死登录和普通消息通信。已有 owner 的 AID 不能被当作新注册身份重新初始化为 unbound。
+
+### 3.2 三方转移
+
+```mermaid
+sequenceDiagram
+    participant O as 当前owner SDK
+    participant S as sub_aid SDK
+    participant W as 新owner SDK
+    participant R as sub_aid关系权威
+    participant F as 各方文件服务
+    O->>R: prepare transfer，旧owner与版本v
+    R-->>O: operation_id，目标版本v+1
+    Note over O,R: 旧owner关系保持active；新owner尚无权限
+    opt 旧身份材料或权限需要隔离
+        S->>S: 完成持久化的凭据隔离任务
+        S->>R: 提交身份权威与资源服务确认回执
+    end
+    S->>R: 新owner关系的agent.md签名证据
+    W->>R: 新owner的owner.md签名证据
+    R->>R: 固定证据摘要与上下文
+    O->>R: old_owner_approval
+    S->>R: sub_approval
+    W->>R: new_owner_approval
+    R->>R: 全部验证通过，进入ready
+    O->>R: commit
+    R->>R: CAS直接切换owner，版本v+1
+    R-->>O: 不可变提交回执
+    Note over O,F: v的关系权限已失效，不等待文件删除
+    S->>F: 自签自传agent.md
+    W->>R: 查询回执
+    W->>F: 自签自写owner.md
+    O->>F: 条件删除自己的旧owner.md
+```
+
+一方拒绝或离线时停留在 awaiting_approvals；过期或取消不改变当前关系。提交响应丢失时先查询 operation，不能重新转移一次。提交后文件缺失只影响完整共识，不让旧 owner 权限复活。
+
+## 4. 解绑流程
+
+```mermaid
+flowchart TD
+    S[sub_aid发起release意向] --> P[准备release<br/>保存当前owner、版本与旧声明证据]
+    O[当前owner发起release] --> P
+    P --> G{需要凭据或旧权限隔离?}
+    G -->|是| I[完成各项隔离并保存回执]
+    G -->|否| A[等待当前owner签署approval]
+    I --> A
+    A --> R[ready<br/>复核当前owner与版本]
+    R --> C[小事务提交unbound<br/>保留relation_id、版本加一]
+    C --> D[旧版本管理权限立即失效]
+    D --> OS[owner自行条件删除旧owner.md]
+    D --> SS[sub_aid自行移除owner及ownership<br/>重新签名上传agent.md]
+    OS --> Q[分别记录完成；失败各自续跑]
+    SS --> Q
+```
+
+当前 owner 授权足以提交 release；sub_aid 离线时不会要求代签或代上传，而是保留该端发布任务。必须由 sub_aid 执行的私钥隔离尚未完成时，owner也只能等待，不能以离线为由绕过。
+
+release使用已归档的旧关系声明及原提交回执；sub_aid完成rekey后旧证书虽然失去实时签名资格，仍可用于验证当时已验收的精确历史文件，不必让离线sub_aid重签旧声明。
+
+release 后允许再绑定，新 bind 必须由 sub_aid 与拟绑定 owner 重新授权，并使用最新版本。主动转移优先使用 transfer，避免把计划中的转移拆成 release+bind 暴露 unbound 窗口。
+
+## 5. 可选托管与凭据隔离
+
+### 5.1 独立启用与恢复
+
+```mermaid
+sequenceDiagram
+    participant A as sub_aid应用
+    participant S as sub_aid SDK
+    participant T as Storage或托管服务
+    participant K as custodian
+    participant D as sub_aid恢复设备
+    A->>S: 显式启用托管，提供密钥管理方式
+    S->>S: 加密身份材料，绑定AID与代际
+    S->>T: 幂等写入密文封套
+    S->>T: 以当前关系版本设置custodian读取授权
+    T-->>S: 对象与授权回执
+    S-->>A: custody状态；关系保持不变
+    K->>T: 验证版本后下载密文
+    K->>D: 应用安排交付密文
+    A->>D: 在恢复设备显式提供解密材料
+    D->>D: 检查代际、证书、私钥匹配后导入本端身份
+    Note over K,D: custodian不自动解密、导入或代sub_aid执行操作
+```
+
+密文上传失败、ACL失败、恢复失败分别保存进度；不能撤销已提交的 owner 关系。需要重建新 owner 托管时，先依据新关系重新授予权限，不复用旧 owner 的下载凭证。
+
+### 5.2 旧 owner 曾持有可解密私钥
+
+这是 transfer/release 的强制安全前置步骤，不属于可忽略的后台清理：
+
+```mermaid
+flowchart TD
+    H[权威外发记录显示私钥可能已交旧owner] --> F[持久化冻结新的身份材料外发<br/>确认旧授权不能继续续发]
+    F --> K[sub_aid本地生成并加密保存新密钥<br/>保存独立rekey幂等键]
+    K --> C[调用Auth/CA完成rekey]
+    C --> V[确认旧证书、token、会话、恢复凭据失效]
+    V --> G[保存新credential generation<br/>与隔离回执]
+    G --> E[使用新身份生成目标签名证据]
+    E --> A[冻结上下文，收集本次操作授权]
+```
+
+崩溃后先查询 rekey 状态和凭据代际，再使用已保存的新私钥续跑，不盲目再生成密钥；CA已完成而本地未记完成时，以远端证书与本地候选密钥匹配确认。旧授权已撤销、身份已轮换都是稳定事实，后续操作取消也不回滚这些事实。
+
+旧关系此时仍保留，托管及需完整共识的功能可以暂时降级。关系准备失败不恢复旧私钥，也不把新的密钥再次交给旧 owner。身份恢复或资源服务缺少可查询的幂等确认能力时，SDK返回能力不足并停止在提交前。
+
+不支持权限版本检查的服务，还须在提交前撤销旧ACL/票据并阻断继续签发；支持版本检查的服务在关系CAS提交后立即拒绝旧版本，ACL元数据可以异步清理。
+
+## 6. 持久化与崩溃恢复
+
+SDK本地至少持久化：intent、幂等键、operation_id、authority issuer、操作角色与参数、期望/目标版本、冻结上下文、本端签名证据和approval、各准备/发布/清理任务进度及回执。密钥候选与解密秘密使用既有安全身份存储，不能放入公开状态或日志。
+
+每个外部副作用遵循“先保存任务输入→幂等执行→查询或保存回执”。收到回执后才能更新本端完成标志；重试沿用原始内容和幂等键。服务端回执必须在对应阶段持久化后返回。
+
+服务端重启恢复失败时，SDK将权威判为不可用，不把查不到数据解释成unbound，也不根据本地文件重建一条未经授权的关系。
+
+```mermaid
+flowchart TD
+    B[启动、重连或应用resume] --> Q[按operation_id查询权威阶段和当前关系]
+    Q --> U{权威可用?}
+    U -->|否| W[保留本地任务<br/>只读或离线等待]
+    U -->|是| T{操作阶段}
+    T -->|prepared| P[继续本端证据和安全准备]
+    T -->|awaiting_approvals| A[重发已批准的本端授权<br/>等待缺失参与方]
+    T -->|ready| C[重试同一operation的CAS提交]
+    T -->|committed| D[读取原回执<br/>只续跑本端发布与清理]
+    T -->|completed| F[返回原结果]
+    T -->|取消、失败或过期| X[保留权威当前关系与审计<br/>停止旧操作的发布]
+    P --> Q
+    A --> Q
+    C --> Q
+    D --> Q
+```
+
+| 中断点 | 恢复规则 |
+| --- | --- |
+| prepare已完成但响应丢失 | 用原幂等键查询/重发，取回同一operation_id。 |
+| 证据或approval已验收但响应丢失 | 查询已接收字段；原字节重发，不替换上下文。 |
+| rekey完成但本地尚未更新 | 查询身份代际，匹配已保存候选密钥，再确认旧凭据隔离。 |
+| ready之后、提交之前 | 重新检查期限、版本、当前owner、凭据代际；冲突不自动重签。 |
+| CAS提交成功但响应丢失 | 查询operation得到committed回执，不能当成失败创建另一次提交。 |
+| 关系提交后某一份文件未上传 | 各方补发自己的文件；缺少该方不能由其它方补签/代上传。 |
+| 文件上传或删除成功但本地未记完成 | HEAD/GET核对关系字段、签名、版本或条件删除结果，再记录任务完成。 |
+| 更晚的关系操作已经提交 | 原回执永久保留；旧发布/删除任务标为superseded，不覆盖新owner文件。 |
+| 可选托管失败 | 独立重试托管任务，不改变committed关系，不阻塞基本通信。 |
+
+公开发布使用最新文档与ETag条件，合并关系字段时保留最新业务正文；必要时由文件所属AID重新签名，不替换operation中已冻结的原始证据。删除旧owner.md同时比较旧关系版本及文档ETag，避免旧清理任务删除后续重新绑定产生的新文件。
+
+权威比本地状态优先：本地active不证明当前关系；已committed操作不会因TTL到期变回expired。发生网络不确定性时返回“结果待查询”，不能猜测提交失败。
+
+## 7. 功能降级与审计接入
+
+### 7.1 降级处理
+
+| 场景 | SDK返回/处理 | 可继续的功能 |
+| --- | --- | --- |
+| 未启用托管或托管临时不可用 | `custody_state=disabled/pending` | 未外发私钥前提下的关系操作及普通通信。 |
+| 参与方离线或未授权 | `waiting_for`指明缺失方 | 保留旧关系，等待同一operation；普通通信继续。 |
+| 关系权威不可用 | `authority_unavailable`或本地intent待提交 | 历史声明展示与普通通信；需owner授权的操作暂停。 |
+| 提交后文件发布不完整 | `committed=true`，`document_state=pending`，`authorized=false` | 重试投影与普通通信，不能声称完整共识。 |
+| 服务仅支持旧协议 | `legacy_read`、`unsupported_capability` | 只读旧关系；升级后显式迁移，禁止自动走2.0绑定。 |
+| 必需的隔离/撤权能力缺失 | 保留prepared，返回具体缺失能力 | 不涉及owner权限的业务；转移/解绑不提交。 |
+
+SDK应分别探测控制面、文件服务、托管和凭据隔离能力，不以一个“支持ownership”布尔值掩盖缺项。升级迁移要导入真实的当前owner和既有私钥外发风险；迁移旧已托管身份时先完成隔离，不能只换schema版本。
+
+### 7.2 需要owner关系的业务操作
+
+应用先调用check，保存双方完整声明与签名文件、权威版本/回执和业务操作标识，再发起业务调用。服务端核对认证调用者、目标sub_aid和相同关系版本，重新授权并记录实际执行结果；如果期间发生转移/解绑，拒绝旧版本请求。审计不能只引用将来可能消失的owner.md URL。
+
+SDK不得把“文件互相匹配”“当前权威active”“所有文件已发布”“业务操作已被授权”合并成一个本地active标志。审计存储失败时，受管理操作不继续执行。
+
+## 8. 实现验收场景
+
+| 场景 | 必须观察到的结果 |
+| --- | --- |
+| sub_aid自行改owner、删除声明、改类型或重注册 | 不能改变权威关系；普通公开上传不得绕过当前owner。 |
+| sub_aid先发起解绑再绑定新owner | 未获旧owner release授权，解绑不提交，新bind被拒绝。 |
+| 转移缺少任意一方签名，或复用其它operation签名 | 不进入committed。 |
+| 并发转移/解绑或同请求重试 | CAS至多一个成功；同operation重试不重复递增版本。 |
+| 未提交时SDK或服务崩溃 | 已批准事实可查询并续跑，原owner保持不变。 |
+| 权威持久化数据恢复失败 | 返回unavailable，不能重置版本或以空unbound允许新绑定。 |
+| 提交后进程崩溃或上传失败 | 新关系保持稳定，只补发各自文件，旧版本权限不能继续使用。 |
+| 已托管身份只删除ACL，没有撤销旧token/证书 | 不得作为已完成的凭据隔离，阻止转移/解绑提交。 |
+| 关闭托管配置或旧协议迁移 | 不能抹除历史外发记录并绕过rekey。 |
+| 旧cleanup在新一轮绑定后到达 | 条件删除/版本检查保护新文件，旧任务收敛为superseded。 |
+| 权威不可用但两份旧文件完全匹配 | 只能返回document_consensus，authorized=false。 |
+| 共识检查后关系被更改 | 服务端拒绝原版本的管理请求。 |
+| 后续删除双方声明 | 已保存的原始签名文件、授权与回执仍能证明历史操作。 |
+
+## 9. 参考实现位置
+
+Git基线中的可复用实现为 `1f03bf2d:extensions/services/auth/go/internal/service/service.go`（operation、关系与CAS）、同目录 `owner_relation_test.go`（状态、期限和重启恢复）及 `1f03bf2d:aun-sdk-core/ts/src/aid-store.ts`（注册/绑定/转移编排）。这些是Git版本位置，不能把当前工作区中的同名实现直接认定为0.5.18。
+
+本端签名、身份存储与文件原语可参考 [AIDStore](../../ts/src/aid-store.ts)、[AID](../../ts/src/aid.ts)、[agent.md](../../ts/src/agent-md.ts)。旧P2P流程见[原SDK实现指南](Ownership-SDK实现指南.md)，只复用其持久化和恢复经验，不复用自动托管、代签、代上传行为。