From 490a683c43dedd891de64f224e0f05a5b05d4a05 Mon Sep 17 00:00:00 2001 From: Mathieu Colla <55652304+Math1987@users.noreply.github.com> Date: Mon, 17 Aug 2026 12:17:56 +0200 Subject: [PATCH 1/3] docs: align human authorization guidance with ANP-03 v1.1 Align the English white paper and ANP-03/ANP-07 guidance with the layered authorization model discussed in #90. --- ...ntnetworkprotocol-technical-white-paper.md | 22 ++++++++++++------- 03-did-wba-method-design-specification.md | 4 +++- ...gent-description-protocol-specification.md | 2 ++ 3 files changed, 19 insertions(+), 9 deletions(-) diff --git a/01-agentnetworkprotocol-technical-white-paper.md b/01-agentnetworkprotocol-technical-white-paper.md index c884f39..bc03822 100644 --- a/01-agentnetworkprotocol-technical-white-paper.md +++ b/01-agentnetworkprotocol-technical-white-paper.md @@ -260,21 +260,27 @@ This section systematically explains ANP's security and privacy design from thre ### 4.1 Distinction Between Human Authorization and Agent Authorization -To ensure human control over sensitive operations, ANP introduces a dedicated verification method called `humanAuthorization` in DID documents. -- **Low-risk operations** (such as querying public information, browsing data) allow agents to authorize automatically using their autonomous keys without human intervention. -- **High-risk operations** (such as fund transfers, important data submissions, privacy information disclosure) must be explicitly authorized by human users. +To keep sensitive operations under human control, ANP separates identity authentication from operation authorization. As specified by [ANP-03 v1.1](/03-did-wba-method-design-specification.md), a `did:wba` DID Document declares verification methods that can be used for `authentication`; it does not define a dedicated `humanAuthorization` verification relationship. -When executing high-risk requests, user agents must sign using the `humanAuthorization` method. This process requires agents to first initiate an authorization request to the human user, and only after explicit confirmation by the user (for example, through biometric verification, password verification, or hardware security module confirmation) can they call the private key bound to that method for signing and submission. +- **Low-risk operations** (such as querying public information or browsing data) may be initiated automatically by agents when permitted by the local authorization policy. +- **High-risk operations** (such as fund transfers, important data submissions, or private information disclosure) may require explicit human authorization before the operation proceeds. -This mechanism effectively ensures that **the final step of important decision operations must be driven by human will**, preventing agents from being misused or executing high-risk instructions without awareness. +The human-authorization requirement is expressed above the DID layer: + +- In [ANP-07](/07-anp-agent-description-protocol-specification.md), `humanAuthorization: true` on an interface declares that calling the interface requires human authorization. +- In the draft [ANP-06](/06-anp-agent-communication-meta-protocol-specification.md), `requiresHumanAuthorization: true` is a negotiation constraint and does not mean that human authorization has been completed. + +When human authorization is required, the user agent should first complete the confirmation process defined by the applicable authorization policy, and then sign and initiate the request with an `authentication` key allowed by that policy. The server verifies whether the request satisfies the agreed higher-level authorization policy. A request signature produced with an `authentication` verification method does not, by itself, prove that a human authorized the operation. + +This separation keeps identity proof distinct from operation authorization and allows higher-layer policies to require human control for sensitive actions. ANP-03 does not define how human authorization is obtained or evidenced; those details are defined by the applicable business protocol and authorization policies. ### 4.2 Private Key Management and Permission Isolation -Agent developers need to implement strict permission isolation and security management for various keys, especially the `humanAuthorization` key, including but not limited to: +Agent developers need to implement strict permission isolation and security management for `authentication` keys used in high-risk operations, including but not limited to: -- **Hierarchical management**: Separate ordinary request keys from highly sensitive keys, managing and using them separately. +- **Risk-based management**: Classify `authentication` keys according to the operations for which policy permits their use, and apply controls appropriate to the associated risk. - **Local encrypted storage**: Private keys should be stored in securely encrypted local devices (such as TEE, HSM) or protected key management systems. -- **Dynamic verification**: Accessing highly sensitive private keys requires additional dynamic verification (such as fingerprint, facial recognition, one-time passwords). +- **Additional confirmation**: When required by the applicable policy, obtain additional confirmation (such as fingerprint, facial recognition, one-time passwords, or secure hardware approval) before an `authentication` key is used for a high-risk operation. - **Operation logging**: Complete operation logs should be recorded for each sensitive signing operation to facilitate post-event auditing and tracking. These mechanisms maximize protection against risks of key leakage, theft, or misuse. diff --git a/03-did-wba-method-design-specification.md b/03-did-wba-method-design-specification.md index bf89b9e..54aea95 100644 --- a/03-did-wba-method-design-specification.md +++ b/03-did-wba-method-design-specification.md @@ -800,11 +800,13 @@ For requests that are not very important, the user agent can automatically autho For important requests, such as booking a hotel room, the hotel agent may require manual confirmation from a human. However, the semantics of "whether human confirmation is required" belong to an upper-layer authorization policy, not to an independent field in the DID Document. The `did:wba` DID Document only declares the verification methods that can be used for `authentication` and no longer defines the `humanAuthorization` field. -The agent can define the authorization type of the document or interface in the agent description document. By default, all ordinary authorizations are sufficient. If a request requires manual authorization by a human, this should be clearly defined in the documentation, for example: +An Agent Description can declare that an interface requires human authorization, while the applicable business protocol can define the requirement for a specific operation. The vocabulary used to express this requirement is defined at those upper layers. The following labels are non-normative examples of an application-defined policy vocabulary: - `authorizationLevel: normal` - `authorizationLevel: user-presence-required` +ANP-03 defines neither the `authorizationLevel` field nor these values. The current [ANP-07 Agent Description Protocol](/07-anp-agent-description-protocol-specification.md) declares the interface-level requirement with `humanAuthorization: true`. The draft [ANP-06 meta-protocol](/06-anp-agent-communication-meta-protocol-specification.md) can carry `requiresHumanAuthorization: true` as a negotiation constraint, but this does not prove that authorization has been completed. + When a request requires manual human authorization, the user agent should first complete the corresponding confirmation process locally (such as click confirmation, biometrics, secure hardware approval, etc.), and then use the `authentication` key allowed by the policy to sign and initiate the request. What the server verifies is: whether the request meets the agreed high-level authorization policy; rather than simply inferring from the DID document that "this signature must have been completed by a human being". diff --git a/07-anp-agent-description-protocol-specification.md b/07-anp-agent-description-protocol-specification.md index 2df20cc..158302b 100644 --- a/07-anp-agent-description-protocol-specification.md +++ b/07-anp-agent-description-protocol-specification.md @@ -633,6 +633,8 @@ When security appears at the top level of the AD document, it indicates that all If an interface requires human manual authorization when called, such as a purchase interface, the field humanAuthorization can be added to the interface definition. A value of true indicates that the interface call requires human manual authorization to access. +`humanAuthorization` indicates an interface-level human-authorization requirement. It is not a DID verification relationship, an authorization credential, or proof that authorization has been completed. DID-based request authentication continues to use the verification methods referenced by `authentication` in [ANP-03](/03-did-wba-method-design-specification.md). How human authorization is obtained or evidenced is outside the scope of this field and is determined by the applicable business protocol and authorization policies. + ### Proof (Integrity Verification) To prevent AD documents from being maliciously tampered with, forged, or replayed, we have added verification information Proof to the AD document. The Proof definition can refer to the specification: [https://www.w3.org/TR/vc-data-integrity/#defn-domain](https://www.w3.org/TR/vc-data-integrity/#defn-domain). From 225201ea011104bc6c79e77ca10a9e825c342f8c Mon Sep 17 00:00:00 2001 From: Mathieu Colla <55652304+Math1987@users.noreply.github.com> Date: Mon, 17 Aug 2026 12:23:09 +0200 Subject: [PATCH 2/3] docs: sync Chinese human authorization guidance Mirror the ANP-03 v1.1 authorization-layer clarification in the Chinese white paper and ANP-03/ANP-07 specifications. --- ...57\347\231\275\347\232\256\344\271\246.md" | 22 ++++++++++++------- ...71\346\263\225\350\247\204\350\214\203.md" | 4 +++- ...17\350\256\256\350\247\204\350\214\203.md" | 2 ++ 3 files changed, 19 insertions(+), 9 deletions(-) diff --git "a/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" "b/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" index 6319c9f..d60530d 100644 --- "a/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" +++ "b/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" @@ -262,21 +262,27 @@ DID 方法定义了如何创建、解析、更新和停用 DID 与 DID 文档， ### 4.1 人类授权与智能体授权的区分 -为实现敏感操作的人类可控性，ANP在DID文档中引入了专门的验证方法 `humanAuthorization`。 -- **低风险操作**（如查询公开信息、浏览数据等）允许智能体基于自主密钥进行自动授权，无需人类介入。 -- **高风险操作**（如资金转账、重要数据提交、隐私信息泄露等）必须由人类用户显式授权。 +为实现敏感操作的人类可控性，ANP 将身份认证与操作授权分离。根据 [ANP-03 v1.1](/chinese/03-did-wba方法规范.md)，`did:wba` DID Document 只声明可用于 `authentication` 的验证方法；它不定义专用的 `humanAuthorization` 验证关系。 -在执行高风险请求时，用户智能体需要使用`humanAuthorization`方法进行签名。这一过程要求智能体首先向人类用户发起授权请求，经用户明确确认（例如通过生物识别、密码验证或硬件安全模块确认）后，方可调用与该方法绑定的私钥进行签名和提交。 +- **低风险操作**（如查询公开信息或浏览数据等）可在本地授权策略允许的情况下由智能体自动发起。 +- **高风险操作**（如资金转账、重要数据提交或隐私信息披露等）可要求获得明确的人类授权后才能继续执行。 -该机制有效确保了**重要决策操作的最后一跳必须由人类意志主导**，防止智能体被滥用或在不知情情况下执行高风险指令。 +人类授权要求在 DID 层之上表达： + +- 在 [ANP-07](/chinese/07-ANP-智能体描述协议规范.md) 中，接口上的 `humanAuthorization: true` 声明调用该接口需要人类授权。 +- 在草案 [ANP-06](/chinese/06-ANP-智能体通信元协议规范.md) 中，`requiresHumanAuthorization: true` 只是协商约束，不表示人类授权已经完成。 + +当请求需要人类授权时，用户智能体应先按照适用的授权策略完成确认流程，再使用该策略允许的 `authentication` 密钥签名并发起请求。服务端验证的是请求是否满足约定的上层授权策略。使用 `authentication` 验证方法生成的请求签名本身不能证明该操作已获得人类授权。 + +这种职责分离使身份证明与操作授权保持独立，并允许上层策略对敏感操作提出人类授权要求。ANP-03 不定义如何取得或证明人类授权；这些细节由适用的业务协议和授权策略定义。 ### 4.2 私钥管理与权限隔离 -智能体开发者需对各类密钥，尤其是`humanAuthorization`密钥，实施严格的权限隔离与安全管理，包括但不限于： +智能体开发者需对用于高风险操作的 `authentication` 密钥实施严格的权限隔离与安全管理，包括但不限于： -- **分级管理**：将普通请求密钥与高敏感密钥分离，分别保管与使用。 +- **基于风险的管理**：按照策略允许其用于的操作对 `authentication` 密钥进行分类，并根据相关风险采取适当的控制措施。 - **本地加密存储**：私钥应存储于安全加密的本地设备（如TEE、HSM）或受保护的密钥管理系统中。 -- **动态验证**：访问高敏感私钥时需附加动态验证（如指纹、人脸识别、一次性密码等）。 +- **额外确认**：当适用策略要求时，在使用 `authentication` 密钥执行高风险操作前取得额外确认（如指纹、人脸识别、一次性密码或安全硬件批准等）。 - **操作日志记录**：每一次敏感签名操作需记录完整的操作日志，便于事后审计与追踪。 通过上述机制，可以最大限度防止密钥泄露、被盗用或被滥用的风险。 diff --git "a/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" "b/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" index 821eddf..b8beda7 100644 --- "a/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" +++ "b/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" @@ -801,11 +801,13 @@ sequenceDiagram 对于重要的请求，比如要预定酒店房间，这个时候酒店智能体可能需要人类的手动确认。但“是否需要人类确认”的语义属于上层授权策略，而不是 DID Document 的独立字段。did:wba DID 文档只声明可以用于 `authentication` 的验证方法，不再定义 `humanAuthorization` 字段。 -智能体可以在智能体描述文档中，定义文档或接口的授权类型，默认情况下所有普通授权即可。如果请求需要人类手动授权，应在文档中明确定义，例如： +智能体描述文档可以声明某个接口需要人类授权，而适用的业务协议可以定义特定操作的授权要求。用于表达这一要求的词汇由这些上层协议定义。以下标签仅是应用自定义策略词汇的非规范性示例： - `authorizationLevel: normal` - `authorizationLevel: user-presence-required` +ANP-03 既不定义 `authorizationLevel` 字段，也不定义这些取值。当前 [ANP-07 智能体描述协议](/chinese/07-ANP-智能体描述协议规范.md) 使用 `humanAuthorization: true` 声明接口级要求。草案 [ANP-06 元协议](/chinese/06-ANP-智能体通信元协议规范.md) 可以在协商中携带 `requiresHumanAuthorization: true` 约束，但这不能证明授权已经完成。 + 当请求需要人类手动授权时，用户智能体应先在本地完成相应的确认流程（如点击确认、生物识别、安全硬件批准等），然后再使用被该策略允许的 `authentication` 密钥进行签名并发起请求。 服务端验证的是：请求是否满足约定的高等级授权策略；而不是单纯从 DID 文档中推断“这个签名一定是人类本人完成的”。 diff --git "a/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" index 8f19791..625d8d1 100644 --- "a/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -633,6 +633,8 @@ AD中的安全配置是必需的。必须通过智能体级别的security成员 如果一个接口在调用的时候，必须经过人类的手动授权，比如购买接口。这个时候可以在接口定义中添加字段humanAuthorization。true表示接口调用需要经过人类的手动授权才能够访问。 +`humanAuthorization` 用于声明接口级的人类授权要求。它不是 DID 验证关系或授权凭证，也不能证明授权已经完成。基于 DID 的请求认证仍使用 [ANP-03](/chinese/03-did-wba方法规范.md) 中由 `authentication` 引用的验证方法。如何取得或证明人类授权不属于该字段的定义范围，应由适用的业务协议和授权策略确定。 + ### Proof（完整性校验） 为了防止AD文档被恶意篡改、假冒或重复使用，我们在AD文档中增加了校验信息Proof。Proof定义可以参考规范：[https://www.w3.org/TR/vc-data-integrity/#defn-domain](https://www.w3.org/TR/vc-data-integrity/#defn-domain)。 From 54f81a2f640ee254c3d737bab8e845e3e73f6e71 Mon Sep 17 00:00:00 2001 From: Mathieu Colla <55652304+Math1987@users.noreply.github.com> Date: Mon, 17 Aug 2026 12:23:26 +0200 Subject: [PATCH 3/3] docs: remove stale DID-level humanAuthorization guidance Correct only the human-authorization statement in the Chinese did:wba guide; a broader ANP-03 v1.1 guide refresh remains out of scope. --- ...did-wba\345\205\245\351\227\250\346\214\207\345\215\227.md" | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git "a/docs/did-wba\345\205\245\351\227\250\346\214\207\345\215\227.md" "b/docs/did-wba\345\205\245\351\227\250\346\214\207\345\215\227.md" index 1813de4..2f39b79 100644 --- "a/docs/did-wba\345\205\245\351\227\250\346\214\207\345\215\227.md" +++ "b/docs/did-wba\345\205\245\351\227\250\346\214\207\345\215\227.md" @@ -91,9 +91,10 @@ DID 文档的存放位置取决于 DID 的形式： 可选字段： - **keyAgreement**：用于密钥协商的公钥信息 -- **humanAuthorization**：用于人类授权的公钥信息 - **service**：与 DID 关联的服务列表，如智能体描述服务 +> 注意：根据 [ANP-03 v1.1](/chinese/03-did-wba方法规范.md)，`did:wba` DID 文档不定义 `humanAuthorization` 验证关系。接口级的人类授权要求由 [ANP-07](/chinese/07-ANP-智能体描述协议规范.md) 中的 `humanAuthorization` 字段声明；基于 DID 的请求认证仍使用由 `authentication` 引用的验证方法。具体操作如何取得或证明人类授权，由适用的业务协议和授权策略定义。 + ### 解析 DID:WBA 解析 did:wba 文档的步骤：