本章规定资源从客户端进入 OpenAgenet (OAN) 的注册流程。客户端形成资源 DID、DID文档、资源元数据、资源包和资源控制证明后，提交给注册服务节点；注册服务节点执行入口校验和授权域校验，再以签名的上游请求调用根平台的资源验证与发布接口。当前参考实现使用 /resources/register 和兼容的 /resources/submit 入口，成功路径包括根平台请求成功、注册 VC 签发、登记记录写入和响应返回。

注册服务节点返回 status: submitted 只表示本次登记流程已获得该节点及其上游调用的成功结果，不等于资源已经完成全网发布、内容分发或发现索引。客户端应把登记结果、根平台可信发布证明和发现服务节点的索引状态分开保存和展示。

注册链路可以概括为“客户端准备材料，注册服务节点受理并校验，根平台验证并发布，注册服务节点返回登记结果”。客户端不应直接根据页面上的成功提示推断发现可见性；应以资源登记记录、根平台返回内容和发现服务节点查询结果分别判断三个阶段。注册服务节点的公开接口是资源提交入口，节点之间的上游调用属于受保护的服务间协议，二者的请求格式和签名主体不能混用。

sequenceDiagram
    participant Client as 客户端
    participant Registrar as 注册服务节点
    participant Root as 根平台
    participant CDN as 内容分发平台
    participant Discovery as 发现服务节点

    Client->>Registrar: 提交资源材料与控制证明
    Registrar->>Registrar: 校验 DID、元数据、授权域和请求
    Registrar->>Root: 提交带签名的上游请求
    Root->>Root: 验证控制证明、资源包和节点授权
    Root-->>Registrar: 返回验证结果与发布任务状态
    Registrar-->>Client: 返回登记结果与注册 VC（如有）
    Root->>CDN: 创建或推进资源包发布任务
    CDN-->>Discovery: 提供资源包与根平台可信发布证明
    Discovery->>Discovery: 校验材料并建立索引
    Client->>Discovery: 查询资源
    Discovery-->>Client: 返回资源及新鲜度、状态信息

上图中的根平台验证、内容分发和发现索引是连续但可异步完成的阶段。resource-verified-and-queued 或注册服务节点返回的 status: submitted 只代表相应登记或排队事实，不能推导内容分发平台已经完成托管，也不能推导发现服务节点已经建立可查询索引。

8.1 注册目标与状态

注册状态应区分客户端本地状态、注册服务节点处理状态和根平台发布状态。推荐使用以下逻辑状态：

stateDiagram-v2
    [*] --> Draft
    Draft --> LocallyValidated: 本地校验通过
    LocallyValidated --> Submitting: 发送注册请求
    Submitting --> Registered: 节点与根平台返回成功
    Submitting --> Failed: 校验、授权或网络失败
    Registered --> CredentialReturned: 返回注册 VC
    Registered --> CredentialPending: VC 暂缺
    CredentialPending --> CredentialReturned: 后续取得 VC
    Registered --> Updating: 新版本提交
    Updating --> Registered: 更新被接受

浏览器预览或本地校验通过不创建注册记录；网络超时也不应直接生成新的 DID 或新版本。相同业务材料的重试应沿用原资源 DID、版本和哈希，并由服务端或查询接口确认真实结果。

8.2 注册请求结构

注册入口的核心载荷是 ResourceRegistrationSubmission。主要字段与用途如下：

这些字段可按验证顺序分为四组：

说明性请求片段如下：

{
  "resourceDid": "did:oan:SKFI:...",
  "resourceType": "skill",
  "didDocument": {"id": "did:oan:SKFI:...", "verificationMethod": []},
  "didDocumentHash": "sha256:...",
  "metadata": {"resourceType": "skill", "authorizedDomains": ["software"]},
  "packageVersion": "1.0.0",
  "packageHash": "sha256:...",
  "metadataHash": "sha256:...",
  "hashAlgorithm": "sha256",
  "registrationCredential": null,
  "subjectControlProof": {"challenge": {}, "proof": {}}
}

注册服务节点应在调用根平台前拒绝资源 DID、DID文档标识、challenge 目标或哈希不一致的请求。未知扩展字段是否保留由协议版本决定；未知核心字段、错误类型或无法解析的结构不得被当作合法请求。

合法请求至少需要同时满足以下关系：didDocument.id == resourceDid；DID文档声明的资源类型与 resourceType 一致；三个哈希字段能够按 hashAlgorithm 解释；控制 challenge 的主体和文档哈希分别对应资源 DID和 didDocumentHash。例如，只有把 resourceType 从 skill 改成 agent_service 而不同时更新 DID文档和元数据的请求，应在注册节点本地校验阶段被拒绝。registrationCredential 保留在共享请求模型中用于兼容和记录，但注册节点向根平台构造上游请求时会将其清空，避免把注册节点此前签发的凭证当成根平台验证依据。

注册服务节点向根平台转发的关键交互可以概括为：

sequenceDiagram
    participant Registrar as 注册服务节点
    participant Root as 根平台

    Registrar->>Registrar: 生成请求体哈希和 SignedRequestEnvelope
    Registrar->>Root: POST /root/resources/verify-and-publish
    Root->>Root: 验证节点 DID、授权 VC、受众、路径、时间和 nonce
    Root->>Root: 验证资源控制证明与三类哈希
    alt 验证失败
        Root-->>Registrar: 错误代码与拒绝原因
    else 验证通过
        Root-->>Registrar: resource-verified-and-queued
    end

这段交互只描述注册服务节点与根平台之间的受保护上游调用。客户端提交入口、注册 VC 签发和后续内容分发仍按本章其它小节分别处理；根平台返回成功也不改变发现服务节点尚未完成索引这一事实。

8.3 本地身份初始化与导入

本地身份是客户端保存主体配置、资源控制密钥和必要凭证的材料集合，不是注册服务节点上的用户账户。它用于生成或恢复控制关系，并为具体注册操作签发控制证明。注册节点只能接收验证所需的 DID文档、公钥、证明和登记材料，不应接收主体或资源控制私钥。

资源控制关系可表示为“本地身份持有控制密钥，资源 DID文档发布验证方法，控制证明把一次具体操作绑定到该资源和该文档版本”。因此，本地身份与资源不是同一个对象：一个主体配置可以控制多个资源，但每次注册请求仍应明确一个 resourceDid，并使用与该资源 DID文档匹配的证明。注册节点验证的是公开材料和签名结果，而不是客户端声称“这是我的资源”。

8.3.1 新建本地身份

客户端生成主体控制密钥和主体 DID，保存公开验证材料及本地配置；随后可为每个资源创建独立的资源 DID 和资源控制材料。新建本地身份本身不产生注册节点记录，也不代表资源已获得网络发布状态。

8.3.2 导入本地身份

客户端解析本地身份备份，校验主体 DID、公钥、私钥、资源配置和凭证之间的对应关系。导入成功后可以继续控制已有资源，但本次注册、更新或重试仍应针对目标 DID、版本、哈希和操作目的生成新的证明。

8.3.3 私钥与主体配置

私钥只在客户端签发控制证明或其它受保护签名时使用；主体配置描述主体 DID 与资源的关联。服务端请求和日志可包含公开 DID、公钥、签名、哈希和凭证，但不得包含私钥或可恢复私钥的明文材料。

8.3.4 身份备份与恢复

身份备份应包含恢复控制关系所需的结构化信息，并标明敏感性和版本。恢复后应重新检查密钥对应关系和 DID文档一致性；备份文件存在不等于资源已经登记，恢复失败也不应覆盖客户端已有的有效身份。

8.4 DID Document 草稿生成

客户端根据资源类型、名称和描述、能力标签、授权域、端点、版本、本地身份和控制密钥生成 DID文档。id 必须与 resourceDid 相同，oanMetadata.resourceType 和 subjectType 必须与请求一致，验证方法必须提供可解析公钥，服务端点和资源包信息必须与资源元数据绑定。

预览按钮可以生成或复用本地 DID文档并展示校验结果，但不得因为展开预览而发起注册网络请求。若表单、本地身份、高级访问或资源包信息未变化，客户端可以复用已生成文档；影响 DID、文档哈希、版本或控制证明的输入发生变化后，必须重新生成并重新签名。

为避免用户在未改变材料时反复得到不同资源身份，客户端应把生成 DID文档所依赖的表单值、本地身份主体 DID、资源控制配置、端点、授权域、版本和资源包摘要形成内部快照。快照相同且已有预览文档时，点击按钮只切换预览区域的展开状态；快照变化时才重新生成文档和相关哈希。该缓存只属于客户端体验优化，不能替代注册节点对请求材料的再次校验。

8.5 提交前本地校验

提交前至少检查以下条件：本地身份已创建或导入；资源类型已选择；名称、描述、端点、授权域、能力标签和版本等必填项完整；DID 语法和资源类型匹配；DID文档、元数据、资源包及哈希一致；控制 challenge 的目标、用途、文档哈希和 verification method 正确；控制证明可由 DID文档中的公钥验证。错误提示应指出具体缺失项，例如“缺少本地身份”“缺少资源端点”“未选择授权域”或“DID文档哈希不一致”。

预览按钮只执行本地生成和校验，提交按钮在发起请求前复用校验结果；两者都不应在页面打开时自动提交。校验失败不得写入注册节点记录、根平台发布记录或成功注册 VC。

本地校验结果宜按字段返回，便于界面和 SDK 采取确定动作：

{
  "valid": false,
  "errors": [
    {"field": "localIdentity", "code": "required", "message": "缺少本地身份"},
    {"field": "serviceEndpoint", "code": "required", "message": "缺少资源端点"}
  ]
}

valid: false 时不得进入提交请求；网络不可用属于提交阶段错误，不应被伪装成本地字段错误。预览成功只证明当前浏览器能够生成并核验草稿，不能证明注册节点或根平台已经接受该材料。

8.6 资源控制证明验证

注册服务节点应同时验证证明载荷、签名和业务上下文。目标资源 DID、DID文档哈希、验证方法、操作目的、challenge 中的注册服务节点、时间窗口和 nonce 必须与当前请求一致；公钥和签名算法必须可解析。证明缺失、过期、用途不符、目标不符、哈希不符或重复使用时，应在调用根平台前拒绝。

控制证明失败不得产生成功登记状态或注册 VC。可保存挑战 ID、资源 DID、文档哈希、验证方法、验证时间和错误代码用于审计，但不得保存签名私钥。

验证顺序应先检查结构和上下文，再验证签名，最后进入发布调用：

请求可解析
  -> challenge.subjectDid == resourceDid
  -> challenge.didDocumentHash == request.didDocumentHash
  -> challenge.registrarDid == 当前注册服务节点 DID
  -> purpose、issuedAt、expiresAt 和 nonce 合法
  -> verificationMethod 位于 DID文档的 assertionMethod
  -> 解析公钥并验签
  -> 允许继续执行注册流程

任一步失败都应停止后续根平台调用。验签成功只说明签名者掌握对应私钥且签名内容未被修改；节点授权域、资源类型、版本和根平台发布条件仍需分别验证。

8.7 注册节点授权与范围验证

当前注册服务节点会读取自身 DID文档中的授权域，将资源 DID文档中的授权域与请求元数据中的授权域进行一致性检查，再判断节点授权域是否覆盖资源域。授权域必须非空、格式合法、顺序稳定且没有越权；不一致或越权时，应在根平台调用前返回错误。

节点签名密钥只证明请求来自该节点运行边界，节点授权 VC 才证明该节点具有相应角色和范围；资源控制证明则是另一个独立条件。

注册节点向根平台发送的请求由 SignedRequestEnvelope 绑定请求 ID、协议版本、用途、HTTP 方法、路径、受众、时间戳、随机数、请求体哈希和节点 proof。根平台可以据此核对哪个注册服务节点在什么时间、以什么用途提交了哪一份材料。这层节点间签名不替代资源控制证明，也不把注册节点自动变成资源控制者。

8.8 资源类型、元数据、端点与资源包校验

资源类型、DID 语义编码、DID文档元数据、资源元数据和资源包应形成一条一致性链。资源 DID、资源类型、版本、DID文档哈希、元数据哈希和资源包哈希必须相互引用；端点应符合声明协议和格式；能力标签应能由能力标签树或允许的扩展规则解释；授权域不能由自由文本绕过。

当前 validate_shape() 已覆盖 DID 语法、资源类型关系、DID文档标识、资源结构、资源包版本、哈希算法、三类哈希引用、challenge 目标 DID、文档哈希和操作目的。端点是否可达、业务是否安全和资源质量是否满足调用需求，属于后续发布或调用前判断，不能由形状校验替代。

8.9 重复注册与幂等性

业务幂等应以资源 DID、资源类型、版本、DID文档哈希、元数据哈希和资源包哈希判断，而不能以提交时间或 VC 的签发时间判断。请求 ID 和 nonce 用于请求关联、新鲜度和重放防护，不能单独决定两个请求是否属于同一资源版本。

8.9.1 同 DID 重复注册

同 DID 再次提交时，服务端应先验证控制权，再比较版本和哈希。材料完全相同应返回既有登记结果或明确幂等结果；DID 相同但版本或任一哈希不同，应进入同 DID 更新决策；控制证明无效时不得覆盖已有记录。

8.9.2 幂等判断依据

幂等判断至少依赖资源 DID、资源类型、版本、DID文档哈希、元数据哈希和资源包哈希，并应保存请求 ID、处理时间和结果以区分业务重试与新版本。当前注册节点通过按资源 DID 的 upsert 方式写入 SQLite、PostgreSQL 或文件存储，这可以保持当前记录，但不足以单独证明已实现完整的版本级幂等历史。

8.9.3 VC 重发

同一业务版本的重试可以返回已保存注册 VC，也可以按明确策略重新签发内容等价但时间不同的 VC。客户端应依据资源 DID、版本、哈希和状态识别凭证对应版本，不能把新的签发时间当作资源版本更新。

8.9.4 根平台重复发布控制

根平台应使相同 DID、版本和哈希的重复发布产生单一业务结果；不同哈希或版本应进入更新、冲突或拒绝路径。注册服务节点收到上游 HTTP 成功并不足以证明根平台已完成重复发布去重，发布证明和序列记录才是判断依据。

8.10 资源更新与同 DID 版本更新

同 DID 更新保留资源身份，但必须产生新的版本、文档或资源包哈希，并通过 previousVersion 等字段表达前序关系。新版本必须使用当前控制关系生成新的控制证明；旧注册 VC 或旧资源包不能自动授权未来更新。版本递增、并发冲突、历史保留和回滚由注册节点与根平台共同执行，具体发布替换规则见第 9 章。

8.10.1 更新授权验证

验证方必须确认提交者仍由当前 DID 控制关系授权，并检查控制证明绑定新文档哈希、版本、用途和 challenge。只有旧凭证而没有新版本控制证明时，应拒绝更新。

8.10.2 DID Document 更新

更新后的 DID文档仍使用原资源 DID，文档哈希必须进入注册提交和资源包。新增、替换或停用验证方法都需要可验证控制链；无法证明更新由当前控制者授权时，不得替换当前文档。

8.10.3 资源元数据和端点更新

资源描述、能力标签、授权域、协议绑定或端点变化都应形成新的元数据哈希和资源包哈希。扩大授权域不能只修改文字字段，端点可达也不能替代业务安全和调用授权判断。

8.10.4 新版本发布与旧版本处理

新版本被接受后，根平台应明确当前版本、历史版本和旧版本状态，发现服务节点按发布序列同步。旧版本可用于审计或回滚，但不能在查询结果中与最新版本混淆。

8.11 注册 VC 签发与获取

当前参考实现只有在根平台资源验证与发布接口返回成功后，才调用注册凭证生成逻辑，并把注册 VC 写入登记记录和成功响应。注册 VC 的 issuer 是注册服务节点，credential subject 是资源 DID，声明包含资源类型、版本、哈希、授权域和生命周期等登记事实。

8.11.1 VC 签发条件

签发前应完成入口形状校验、资源授权域校验、控制证明处理和根平台请求。客户端本地预览通过、点击提交或注册节点收到请求，都不是单独的签发条件。

8.11.2 VC 返回方式

成功响应当前包含 status、resourceDid、resourceType、registrationCredential 和 rootResponse。客户端应保存 VC 原文并与 DID文档、版本和哈希关联；rootResponse 仍需按根平台证明和状态规则解析。

8.11.3 VC 缺失或为空的处理

若登记结果成功但 VC 缺失或为空，客户端应分开记录登记状态和凭证状态，明确提示凭证尚未取得，不能伪造空 VC，也不能把空值当作有效凭证。查询或重试应保留原 DID、版本和哈希。

8.11.4 VC 本地保存

注册 VC 应与资源 DID文档和资源版本建立文件关联。客户端打包下载 VC、DID文档和本地身份备份时，私钥仍属于敏感材料，只能由控制者保管，不得发送到节点或公共存储。

8.12 注册响应与错误处理

当前注册服务节点的处理函数接收 Json<ResourceRegistrationSubmission>，成功时返回动态 JSON。成功响应的稳定核心字段是 status、resourceDid、resourceType、registrationCredential 和 rootResponse；其中 rootResponse 保留根平台返回的动态内容，不能被客户端假定为固定的 VC 或全网发布完成标志。

下面的 handler 关系说明输入和输出的实际类型；它是接口契约的缩略表示，不是可直接替换的完整实现：

async fn register_resource(
    State(state): State<AppState>,
    Json(submission): Json<ResourceRegistrationSubmission>,
) -> ApiResult<serde_json::Value>;

注册节点与根平台之间的 ResourceVerifyAndPublishRequest 还包含 registrarDid、原始登记提交和 upstreamAuth。客户端不应自行构造该内部转发对象，也不应把注册节点的 registrationCredential 当作根平台可信发布证明；错误响应中的 error、状态码和请求关联标识应共同用于判断修正、查询、重试或停止。

当前实现的错误主要通过 HTTP 状态和 error 文本返回；后续稳定协议应补充 request ID、错误码、登记状态、上游状态和可重试标志，使客户端不依赖自由文本猜测网络状态。

建议将响应处理归纳为以下确定性规则：

{
  "status": "submitted",
  "resourceDid": "did:oan:SKFI:...",
  "resourceType": "skill",
  "registrationCredential": null,
  "rootResponse": {"status": "published"}
}

当 HTTP 请求超时而没有响应时，客户端只能记录“结果未知”，保留原 DID、版本和哈希，并通过查询或相同材料重试，不能据此生成新 DID。收到非成功 HTTP 状态时，不得保存为登记成功；收到成功状态但 VC 为空时，应将登记状态与凭证状态分开显示，只有实际拿到并验证的凭证才能作为 VC 文件下载。

8.13 注册审计记录

登记记录至少应关联资源 DID、资源类型、版本、DID文档哈希、元数据哈希、资源包哈希、授权域、注册服务节点、登记 VC、根平台响应摘要、提交时间和处理结果。当前 write_resource_record() 按资源 DID 写入 SQLite、PostgreSQL 或文件存储，因此完整审计实现还应保留操作类型、请求 ID、前后版本和失败原因，避免覆盖记录丢失历史上下文。

审计记录不得保存资源控制私钥、本地身份备份或可恢复秘密。DID、公钥、哈希、挑战 ID、请求 ID、状态和错误代码可以作为追踪证据；审计读取权限必须与公开发现接口分开。

8.14 资源更新授权与同 DID 替换

服务端收到同 DID 新材料后，应依次确认控制证明、版本关系和哈希关系。相同版本同哈希属于幂等重试；相同版本不同哈希属于冲突；新版本带有效前序关系才可进入更新；版本倒退、前序缺失、授权变化未经批准或控制证明无效时应拒绝或转人工处理。注册节点可以保存受理记录，但根平台决定网络发布事实。

替换判断可用下表核对：

8.15 提交重试、幂等键与重复处理

节点到根平台的上游请求使用 SignedRequestEnvelope 绑定 request ID、协议版本、用途、方法、路径、受众、请求时间、请求随机数、请求体哈希和 proof；安全层通过 nonce 存储和时间窗口实施重放防护。业务幂等则依赖资源 DID、版本和内容哈希。客户端超时后应保留原材料，优先查询既有结果或使用相同业务材料重试，不能立即生成新 DID 来掩盖未知结果。

8.16 注册速率限制与滥用控制

公开注册入口应限制单位时间请求量、请求体和资源包大小、单来源失败次数、同 DID 冲突次数以及上游转发并发量。控制证明、节点授权和授权域检查应尽早执行，以减少伪造材料造成的存储、网络和计算压力。限流不能把合法的同 DID 幂等查询误判为新版本，也不能通过放宽控制证明换取吞吐量。

当前参考实现明确包含结构校验、授权域覆盖检查、上游请求签名和 nonce 重放防护；反向代理、WAF 或服务级限流若在部署中启用，应在部署文档中注明实际策略、响应码和恢复方式。

注册流程验收清单

• [ ] 空表单、缺少本地身份、缺少端点或缺少授权域时，客户端能指出具体条件。
• [ ] 注册服务节点在根平台调用前完成请求形状、资源授权域和控制证明校验。
• [ ] 根平台失败或网络超时时，客户端不会显示全网发布成功，也不会丢失原 DID 和版本材料。
• [ ] 成功响应中的注册 VC 能与资源 DID、版本和三个哈希建立对应关系。
• [ ] 相同 DID、版本和哈希的重试与不同哈希或版本的更新得到不同处理。
• [ ] 登记、根平台发布、内容分发和发现索引状态能够分别观察和验证。
• [ ] 审计记录可追踪请求而不包含私钥、本地身份备份或其它敏感秘密。

参考来源