本章统一描述 OpenAgenet (OAN) 身份材料和密码学证明的语义边界。身份材料回答对象是谁以及谁能够代表对象作出声明；签名回答指定内容是否由相应私钥产生；可验证凭证（VC）回答签发者对哪些事实作出可验证声明；可验证呈现（VP）回答持有者为特定验证目的呈现哪些凭证。四者相互关联，但不能互相替代。

资源注册通常同时涉及主体 DID、资源 DID、资源控制密钥、注册服务节点密钥、节点授权 VC、资源控制证明、注册 VC 和根平台可信发布证明。客户端可以生成和保管私钥，节点可以验证公开公钥和证明，根平台可以验证节点授权及发布条件；上述验证能力不意味着节点或根平台取得资源控制私钥，也不意味着资源已经获得业务调用许可。

7.1 主体身份与资源身份

主体是能够管理一个或多个资源控制关系的身份对象，资源身份是可以独立注册、发布、发现、更新和撤销的对象边界。主体 DID、资源 DID、注册服务节点 DID、发现服务节点 DID 和根平台 DID 都可以采用 did:oan 方法，但对象类别、密钥用途和信任来源不同，不能仅因方法相同而混用。

注册时应披露完成验证所需的最小公开材料，例如资源 DID文档、公开公钥、资源元数据、哈希和控制证明。主体姓名、联系方式、本地身份备份和私钥不是资源发现所必需的公开字段，不能因提交登记而默认进入节点日志、索引或公开响应。

同一注册请求中的身份材料可以按其作用分成三层：

验证方应从身份层开始，逐层核对控制层和网络事实层。把资源 DID 文本、注册 VC 或某个节点的签名单独拿出来，都不能还原完整的控制与发布关系。

7.2 密钥生成、保管、备份与恢复

密钥应在控制者可管理的客户端或节点安全运行环境中生成、导入和使用。当前 oan-crypto 提供 Ed25519 及 SM2/SM3 相关密钥处理，并支持多重编码公钥和 JWK 公钥表示。密码套件、公开密钥表示和证明类型必须能够被接收方识别；遇到未知、截断或不兼容材料时，应明确失败，不得静默改用另一套算法。

本地身份备份可能同时包含主体配置、资源配置、公钥、私钥和凭证，属于敏感材料。导入或恢复时应检查文件结构、DID、公钥与私钥对应关系、资源类型及控制关系；恢复成功只表示客户端重新取得本地控制材料，不表示资源已经登记、发布或重新索引。

本地身份备份与公开 DID文档的边界可以用最小结构表示：

{
  "publicIdentity": {
    "did": "did:oan:DVFI:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
    "verificationMethod": "did:oan:DVFI:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz#key-1",
    "publicKey": "public-key-material"
  },
  "localSecret": {
    "privateKey": "private-key-material",
    "storage": "browser-local-backup"
  },
  "controlledResources": ["did:oan:SKFI:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu"]
}

该结构仅用于说明边界，实际备份字段以客户端实现为准。公开身份材料可以发送给验证方，localSecret 只能留在控制者管理的本地安全边界内；服务器取得公钥并不能反推出私钥。

7.3 资源控制签名

资源控制签名必须绑定具体操作，而不是对任意文本作孤立签名。DidControlChallenge 将挑战标识、草稿标识、目标资源 DID、DID文档哈希、注册服务节点 DID、操作目的、验证方法、随机数和有效时间组合起来；SubjectControlProofBundle 再关联控制证明、验证时间、实际验证方法和证明哈希。注册服务节点和根平台均应检查这些绑定。

至少应检查以下条件：

1. subjectDid 与提交资源 DID 一致。
2. didDocumentHash 与提交的 DID文档一致。
3. verificationMethod 属于目标 DID文档，并且用途允许当前操作。
4. purpose 与当前注册、更新或发布操作一致。
5. nonce、签发时间和失效时间满足新鲜度和防重放要求。

证明验签成功只能说明相应私钥签署了指定载荷；资源提供方是否有权代表某组织、端点是否安全、调用方是否获得业务授权，仍须由委托材料、治理状态和业务策略分别判断。

控制证明的核心不是签名值本身，而是签名所覆盖的上下文。验证方可以按照下面的关系检查一次注册操作：

{
  "operation": "register_resource",
  "subjectDid": "did:oan:SKFI:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "registrarDid": "did:oan:INRG:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
  "didDocumentHash": "sha256:example-did-document",
  "challengeId": "challenge-example",
  "nonce": "nonce-example",
  "proofPurpose": "assertionMethod",
  "signature": "signature-example"
}

其中 DID、目标注册服务节点、文档哈希、用途和随机数都属于待核对的绑定关系，示例值不代表真实请求。任何一个绑定字段与当前请求不一致，都不能仅因签名算法验证成功而接受注册或更新。

7.4 节点身份密钥与节点签名密钥

节点 DID文档表达节点身份，通信签名密钥证明请求来自相应节点运行边界，节点授权 VC 证明节点角色和授权域，运行凭据支撑服务启动、密钥加载或受控基础设施访问。实际部署可以由同一安全边界托管多类材料，但协议语义仍应按用途分开。

向根平台发送资源验证请求时，SignedRequestEnvelope 将 requestId、协议版本、用途、HTTP 方法、路径、受众、请求时间、请求随机数、请求体哈希和 proof 绑定。接收方应检查受众、路径、时间窗口、nonce 是否重放、节点 DID文档、公钥和节点授权，再处理业务内容。

SignedRequestEnvelope 的验证顺序可概括为：

1. 读取请求中的节点 DID、受众、HTTP 方法、路径和请求体哈希。
2. 解析节点 DID文档，定位请求使用的验证方法和公开公钥。
3. 校验 proof 的用途、创建时间、请求 ID、随机数和签名载荷。
4. 检查节点授权 VC 的角色、授权域和当前状态。
5. 通过后才处理资源验证、登记或发布业务。

这样可以把“请求来自某个节点”与“该节点有权执行当前动作”分开判断。

7.5 基础设施节点的根平台授权 VC

节点授权 VC 的核心关系是：issuer 是根平台或治理认可的签发者，subject 是被授权节点 DID，role 表示节点角色，claims 承载授权域和能力范围，status、issuedAt、expiresAt 描述状态和时间窗口。NodeAuthorizationCredential 的 proof 必须由 issuer 对无 proof 凭证内容签发，验证方应从 issuer DID文档取得公钥并验证。

节点 DID文档 -> 取得节点验证公钥
      -> 验证授权 VC proof
      -> 检查 issuer、subject、role、status、issuedAt、expiresAt
      -> 检查授权域和能力范围
      -> 决定当前节点动作是否获准

缺少 proof、issuer 无法解析、subject 不匹配、角色不允许、授权已过期、状态不是 active 或授权域不覆盖请求范围时，受限动作必须拒绝。节点授权 VC 证明基础设施资格，不证明资源控制权。

节点授权 VC 的字段关系可以用如下示例核对：

{
  "type": "NodeAuthorizationCredential",
  "issuer": "did:oan:INRT:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
  "subject": "did:oan:INRG:8LcR3Vn5YpQw2Tx7Mb9Zd4Fa6GhKsEuJ",
  "role": "registrar",
  "status": "active",
  "issuedAt": "2026-09-09T08:30:00Z",
  "expiresAt": null,
  "claims": {
    "authorizedDomains": ["public"],
    "capabilities": ["resource_registration"]
  },
  "proof": {
    "type": "DataIntegrityProof",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:oan:INRT:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz#key-1",
    "proofValue": "signature-example"
  }
}

该示例中的角色、授权域和能力值用于说明校验关系。验证方需要确认 issuer、subject、proof 和治理状态相互匹配，再将授权范围与当前请求比较；授权 VC 的有效性不改变资源 DID 的控制者。

7.6 向资源控制方签发的注册 VC

当前注册服务节点流程先调用根平台的资源验证与发布接口；上游成功后，由注册服务节点签发注册 VC，并将登记记录写入存储。凭证包含 OAN 凭证上下文、凭证类型、issuer、资源 credential subject、资源 DID、资源类型、DID文档哈希、元数据哈希、资源包哈希、资源包版本、哈希算法、授权域、生命周期状态和 credential status。

说明性结构如下，字段顺序不构成额外语义：

{
  "type": ["VerifiableCredential", "OANResourceRegistrationCredential"],
  "issuer": "did:oan:...",
  "issuanceDate": "2026-09-06T00:00:00Z",
  "credentialSubject": {
    "id": "did:oan:SKFI:...",
    "resourceDid": "did:oan:SKFI:...",
    "resourceType": "skill",
    "didDocumentHash": "sha256:...",
    "metadataHash": "sha256:...",
    "packageHash": "sha256:...",
    "packageVersion": "1.0.0",
    "hashAlgorithm": "sha256",
    "lifecycleState": "active"
  },
  "credentialStatus": {"status": "active"},
  "proof": {"type": "DataIntegrityProof", "proofValue": "..."}
}

注册 VC 证明注册服务节点对指定登记材料完成了处理以及凭证中明确列出的登记事实；它不单独证明根平台已完成全网发布、发现服务节点已完成索引或调用方已经获得业务许可。

注册 VC 中最重要的绑定关系是 issuer、subject、资源版本和三类哈希。验证方应把凭证声明与收到的 DID文档、资源元数据和资源包重新比较：

{
  "type": "AgentRegistrationCredential",
  "issuer": "did:oan:INRG:8LcR3Vn5YpQw2Tx7Mb9Zd4Fa6GhKsEuJ",
  "subject": "did:oan:SKFI:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "status": "active",
  "issuedAt": "2026-09-09T08:31:00Z",
  "claims": {
    "resourceDid": "did:oan:SKFI:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
    "resourceType": "skill",
    "packageVersion": "1.0.0",
    "didDocumentHash": "sha256:example-did-document",
    "metadataHash": "sha256:example-metadata",
    "packageHash": "sha256:example-package",
    "hashAlgorithm": "sha256",
    "lifecycleState": "active"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "proofPurpose": "assertionMethod",
    "proofValue": "signature-example"
  }
}

示例值不代表真实凭证。若 subject、resourceDid、版本或任一哈希与当前材料不一致，注册 VC 不能用于证明当前材料已经登记；即使凭证签名本身有效，也只能说明签发者签署了另一组声明。

7.7 治理与授权证据

验证方必须按事实类型组合证据。注册 VC 有效只能说明登记处理完成；根平台可信发布证明缺失时，不能把登记结果写成全网可发现；资源控制证明不匹配时，不能因节点授权有效而接受资源更新。

7.8 VC 与 VP 结构要求

VC 是签发者对声明事实的可验证表达，VP 是持有者围绕一次验证目的组织的呈现。当前核心代码直接建模节点授权 VC 和资源注册 VC；采用 VP 时应补充 holder、呈现目的、challenge、有效期和呈现 proof，不能把任意 VC JSON 集合直接称为 VP。

7.8.1 VC 基本结构

VC 应至少能定位上下文、类型、issuer、credentialSubject、签发时间、可选失效时间、状态和 proof。OAN 的 Rust 凭证结构使用 type、issuer、subject、status、issuedAt、expiresAt、claims 和 proof；HTTP JSON 结构可使用 credentialSubject、issuanceDate 等互操作命名，但序列化映射必须稳定，且不能改变声明语义。

7.8.2 VP 基本结构

VP 应包含呈现类型、holder、一个或多个 verifiableCredential、呈现目的和针对本次验证的 proof。需要防重放时，还应绑定验证方提供的 challenge 或 nonce。没有 holder 证明、用途绑定或本次验证上下文的凭证集合，不应作为新鲜 VP 接受。

VP 的最小示例可以表示为：

{
  "type": ["VerifiablePresentation"],
  "holder": "did:oan:DVFI:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
  "verifiableCredential": [
    {
      "type": ["VerifiableCredential", "AgentRegistrationCredential"],
      "issuer": "did:oan:INRG:8LcR3Vn5YpQw2Tx7Mb9Zd4Fa6GhKsEuJ",
      "subject": "did:oan:SKFI:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
      "status": "active",
      "claims": { "packageVersion": "1.0.0" },
      "proof": { "proofValue": "credential-signature-example" }
    }
  ],
  "purpose": "resource_verification",
  "challenge": "verifier-challenge-example",
  "proof": {
    "proofPurpose": "authentication",
    "proofValue": "presentation-signature-example"
  }
}

该示例用于区分 VC 的签发证明和 VP 的持有者呈现证明。验证方仍需按实际凭证结构校验 issuer、subject、VC proof、holder、VP proof、challenge 和状态，不能把示例中的凭证对象直接作为可用凭证。

7.8.3 签发者、持有者与主体

issuer 对 VC 声明负责，credentialSubject 是声明所描述的对象，holder 是当前控制呈现材料的一方，controller 是 DID文档中控制验证方法的主体。四者可以相同，也可以不同；注册服务节点可以是注册 VC 的 issuer，资源 DID 是 credentialSubject，资源控制方可以是 holder，而节点运营者不会因此自动成为资源 controller。

7.8.4 凭证状态与验证

验证不能止于 proof 验签，还应检查凭证类型、issuer 与 DID文档、公钥、subject、用途、有效期、状态和必要 claims。状态源不可用时，应依据凭证用途采取明确的失败或降级策略；“暂时无法查询”不能被解释为 active。

对于不同材料，验证结果应保留“签名有效”和“业务事实有效”两个层次：

7.9 签发者、持有者、控制者与凭证主体关系

这些字段表达的是不同关系，不能根据字段出现就推导完整的所有权和授权链。验证时应同时检查字段关系、DID文档、公钥、证明用途以及治理和业务策略。

7.9.1 签发者

issuer 使用签发密钥对无 proof 的凭证内容签名，并对声明承担可追溯责任。验证方应从 issuer DID文档取得验证方法，检查 proof creator、verification method 与 issuer 的一致性。

7.9.2 持有者

holder 是当前控制凭证呈现材料的一方，可以是资源控制方、客户端或受委托的用户助手智能体。持有公开 VC 不等于取得 credentialSubject 的控制权，代表关系仍需由控制证明、委托或业务授权支撑。

7.9.3 资源控制者

资源控制者控制资源 DID 对应的注册、更新或其它受保护操作。控制者可以与资源提供方、注册 VC holder 或端点运营方不同，其权限判断依赖目标 DID、验证方法、操作绑定证明和当前版本规则。

7.9.4 凭证主体

credentialSubject 是 VC 所描述的对象。节点授权 VC 的主体通常是基础设施节点 DID，注册 VC 的主体通常是资源 DID；主体被替换、DID文档不匹配或 claims 与主体类型冲突时，凭证不得用于相应决策。

7.10 签名验证与状态验证

验证服务接收到 JSON 后，应先按接口声明的类型或字段结构解析，再分别验证签名覆盖范围和状态来源。节点间请求的 upstreamAuth 用于证明请求来自具备相应授权的节点；资源登记中的 subjectControlProof 用于证明资源控制方授权本次登记或更新；注册 VC 用于说明注册服务节点产生的登记事实；根平台可信发布证明用于说明特定资源版本通过根平台验证。它们可能在同一 HTTP 业务链路中连续出现，但不能混为一个凭证对象。

请求可解析
  -> 请求签名与受众有效
  -> 资源控制证明有效
  -> 注册 VC 的签发者和主体匹配
  -> 根平台发布证明与版本、哈希匹配
  -> 治理状态和新鲜度可接受

flowchart TD
    A[解析 DID、VC 或 VP] --> B[检查类型和必需字段]
    B --> C[解析 issuer 或 controller DID文档]
    C --> D[定位 verificationMethod 和公钥]
    D --> E[规范化无 proof 载荷并验签]
    E --> F[检查目标 DID、用途和声明关系]
    F --> G[检查时间、新鲜度和有效期]
    G --> H[检查凭证状态和治理状态]
    H --> I[按授权域和业务策略决策]

任何一步失败都应在发布、授权或调用等副作用动作前终止，并返回可定位的失败原因。验证记录可以保存验证对象、proof 类型、verification method、验证时间、状态来源和错误代码，但不得保存私钥或可恢复私钥的材料。

7.11 凭证隐私与披露边界

资源发现所需的资源 DID、公钥、能力标签、资源描述、端点、版本、哈希和根平台发布证据可以进入公开资源包或发现响应。主体个人信息、私钥、本地身份备份、未公开委托材料和不必要的内部配置应保持在受控边界内。

最小披露不能删除验证所需的绑定字段。若隐藏字段会使验证方无法确认 issuer、subject、版本、哈希或 proof，应采用受控呈现或可验证摘要，而不是不可核验的展示文本。

7.12 密钥轮换与失陷响应

轮换应先建立新公钥与既有 DID 的可验证控制关系，再使旧公钥退出新操作。资源 DID 更新应在新 DID文档中说明新验证方法、用途和生效版本；节点密钥轮换还应同步节点授权 VC、节点配置和上游信任材料；根平台密钥轮换则必须考虑下游缓存、历史证明和验证窗口。

密钥失陷时，应暂停受影响密钥，保留验证历史材料所需的旧公钥和状态，并通过新的控制关系发布撤销、替换或恢复事实。若控制私钥完全丢失且没有恢复密钥或转移机制，系统不能仅凭 DID 字符串恢复控制权，应进入治理介入或重新注册流程。

7.13 注册 VC 与资源发布证据

两类证明构成连续但独立的事实层。注册服务节点在根平台接口成功返回后生成注册 VC；根平台则对资源控制证明、元数据、资源包、版本、哈希和发布条件完成验证后产生根平台可信发布证明。HTTP 成功码或 rootResponse 只能作为传输结果，不能替代对证明内容和状态的验证。

资源控制证明 -> 注册服务节点受理
       -> 根平台验证资源、版本、哈希和发布条件
       -> 根平台可信发布证明
       -> 内容分发平台分发
       -> 发现服务节点验证和索引
       -> 调用方再次验证并按策略调用

登记受理、根平台接受、材料分发、发现节点索引和调用方授权必须分别表达。任何单一 VC 或发布证明都不得将这些状态压缩为“资源已经可信可用”。

7.14 节点授权 VC 与基础设施权限

节点动作由角色、授权域、能力范围和治理状态共同限定。注册服务节点只能处理授权域覆盖的资源，发现服务节点只能同步和返回获准范围；节点能够验证某份材料不等于节点被授权执行所有网络动作。授权域应检查格式、排序、重复、层级覆盖和与节点 VC 的一致性。

allow(action) = valid(node authorization VC)
             && active(governance status)
             && role permits(action)
             && granted domains cover(requested domains)
             && freshness is acceptable

该表达式表示判定关系而非固定实现代码。错误应区分节点授权失败、资源控制失败、资源内容失败和上游服务失败，便于审计、客户端处理和运维定位。

7.15 凭证吊销、暂停与状态传播

签名有效的凭证仍可能因治理事件、状态记录或 expiresAt 而不能用于新的授权决策。状态传播可能经过链上治理事件、根平台状态、链下信任索引器和节点缓存，因此验证结果应带有状态来源、观察时间和新鲜度信息。

7.15.1 凭证状态变更

状态变更应关联凭证标识、主体、旧状态、新状态、原因、事件序列和时间，并由有权主体产生。恢复 suspended 与重新签发新凭证不是同一操作；撤销后能否重新签发，应由治理和签发策略规定。

7.15.2 节点授权 VC 状态

节点授权 VC 被暂停或撤销后，注册服务节点和发现服务节点不得继续执行受限的新动作。已有材料是否继续提供，只能按缓存新鲜度和风险策略处理，不能以历史 VC 推导当前节点仍有权提交或索引新内容。

7.15.3 资源注册 VC 状态

资源注册 VC 状态变化影响登记证明的当前有效性，但不必然等同于删除资源 DID。历史文档和审计材料可以保留，同时将当前版本标记为暂停、撤销或不可发现；验证方应分别检查 VC 状态、资源生命周期和根平台发布状态。

7.15.4 状态传播与缓存更新

节点收到较新的治理事件或状态游标后，应验证序列连续性、事件完整性和证明，再更新本地缓存。游标落后、事件缺口、状态源不可用或缓存超过允许新鲜度时，敏感动作应暂停或返回状态不确定，而不是继续沿用旧的 active 判断。

7.16 签名格式、规范化与验证测试向量

跨语言实现必须统一待签名原文、字段命名、字段排序、空值处理、时间格式、哈希算法、公钥编码和 proof 字段。参考实现中的 signature_input、build_data_integrity_proof 和 verify_payload_with_proof 体现了载荷构造、证明生成和验证边界；其它语言实现应产生等价字节序列，而不能只比较内存对象。

测试向量应版本化，并覆盖 Rust 参考实现、TypeScript SDK 和节点 HTTP 层。测试私钥只能使用专用材料；生产私钥不得进入测试文件或日志。日志可保留公钥、哈希、请求 ID 和错误代码等非敏感证据。

本章验收清单

• [ ] 主体 DID、资源 DID、节点 DID 和根平台 DID 的控制关系能够分别解释。
• [ ] 私钥不会出现在 DID文档、注册请求、VC、VP、日志或发现响应中。
• [ ] 资源控制证明、节点授权 VC、注册 VC 和根平台可信发布证明可以分别验证。
• [ ] 验证流程同时检查签名、DID、公钥、用途、时间、状态和授权域。
• [ ] 合法、篡改、过期、撤销、重放和用途不匹配输入得到可区分结果。

参考来源