跳到主要内容

协议声明

协议声明 (Agreement Claim) 是一个强大的工具，用于获取用户对服务条款、隐私政策或任何其他正式协议的明确同意。此声明并非简单的复选框，而是要求用户对文档的哈希（摘要）进行加密签名，从而创建一个可验证且不可否认的同意记录。

此过程可确保用户同意你所提供的确切文档版本，因为 DID 钱包在请求用户签名之前会独立验证文档的完整性。

工作原理

协议声明的工作流程旨在确保安全性和透明度：

  1. 应用端

    你的应用程序向钱包提供一个托管文档的 URL (uri) 和一个预先计算好的该文档内容的加密哈希（digest）。

  2. 钱包端

    用户的 DID 钱包接收请求。

  3. 验证

    钱包从提供的 uri 获取文档，使用相同的 method（例如 SHA256）计算其哈希值，并将其与你的应用程序发送的 digest 进行比较。

  4. 用户同意

    如果哈希值匹配，钱包会向用户显示文档和确认提示。如果不匹配，钱包会警告用户可能存在差异，保护他们免受“偷梁换柱”式攻击。

  5. 签名

    用户批准后，钱包会使用用户的私钥对已验证的摘要进行签名。

  6. 响应

    生成的签名作为同意证明被发送回你的应用程序。

Agreement Claim

参数

agreement 声明对象接受以下参数：

ParameterTypeDescription
uristring必需。用户需要查看并同意的文档（例如，服务条款）的 URL。必须是 http 或 https URL。
digeststring必需。文档内容的加密哈希（摘要）。在请求签名之前，钱包将根据 uri 处的文档验证此摘要。
methodstring可选。用于创建摘要的哈希算法。默认为 sha2。支持的方法包括 sha2、sha3 和 keccak。
descriptionstring可选。在钱包中向用户显示的自定义消息，解释他们同意的内容。默认为“请确认您的协议以继续。”。

示例：请求同意服务条款

以下是如何配置 WalletHandlers 以请求用户同意服务条款文档。你首先需要为你的 terms.txt 文件生成一个 SHA256 哈希值。

请求用户同意

javascript
const { WalletHandlers } = require('@arcblock/did-connect');

// 你可以使用如下命令生成此摘要：
// shasum -a 256 path/to/your/terms.txt
const termsDigest = 'f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2';

const handlers = new WalletHandlers({
  chainInfo: { host: 'https://beta.abtnetwork.io/api' },
  appInfo: {
    name: 'My App',
    description: 'My App Description',
    icon: 'https://arcblock.oss-cn-beijing.aliyuncs.com/images/wallet-round.png',
    link: 'https://my-app.com',
  },
  claims: {
    agreement: {
      description: 'Please read and agree to our new Terms of Service to proceed.',
      uri: 'https://my-app.com/terms.txt',
      method: 'sha2',
      digest: termsDigest,
    },
  },
  onAuth: async ({ claims, userDid }) => {
    // claims 数组将包含协议声明的响应
    const agreementClaim = claims.find(c => c.type === 'agreement');
    console.log(`${userDid} agreed and signed with digest:`, agreementClaim.sig);

    // 现在你可以根据用户的 DID 和原始摘要验证签名
  },
});

在 onAuth 回调中，你会收到 sig 字段，这是用户对文档摘要的签名。你可以将此签名与用户的 DID 一起存储，作为其同意的持久且可验证的记录。

后续步骤

在获得用户同意后，你可能需要验证他们拥有的特定属性或资格。了解如何通过请求可验证凭证来实现这一点。

可验证凭证声明

请求用户出示可验证凭证（VC）以证明其某项属性或资格。

阅读更多