Agreement Claim

The Agreement Claim is a powerful tool for obtaining explicit user consent for documents like Terms of Service, Privacy Policies, or any other formal agreement. Instead of a simple checkbox, this claim requires the user to cryptographically sign a hash (digest) of the document, creating a verifiable and non-repudiable record of their consent.

This process ensures that the user agrees to the exact version of the document you presented, as the DID Wallet independently verifies the document's integrity before requesting the user's signature.

How It Works

The workflow for an Agreement Claim is designed for security and transparency:

1. Application Side

   Your application provides the wallet with a URL (uri) where the document is hosted and a pre-calculated cryptographic hash (digest) of that document's content.

2. Wallet Side

   The user's DID Wallet receives the request.

3. Verification

   The wallet fetches the document from the provided uri, calculates its hash using the same method (e.g., SHA256), and compares it to the digest sent by your application.

4. User Consent

   If the hashes match, the wallet displays the document and a confirmation prompt to the user. If they don't match, the wallet warns the user of a potential discrepancy, protecting them from bait-and-switch attacks.

5. Signature

   Upon user approval, the wallet signs the verified digest with the user's private key.

6. Response

   The resulting signature is sent back to your application as proof of agreement.

Parameters

The agreement claim object accepts the following parameters:

Example: Requesting Agreement to Terms of Service

Here's how you can configure WalletHandlers to request a user's agreement to a Terms of Service document. You would first need to generate a SHA256 hash of your terms.txt file.

Requesting User Agreement

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

// You can generate this digest using a command like:
// 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 }) => {
    // The claims array will contain the agreement claim response
    const agreementClaim = claims.find(c => c.type === 'agreement');
    console.log(`${userDid} agreed and signed with digest:`, agreementClaim.sig);

    // You can now verify the signature against the user's DID and the original digest
  },
});

In the onAuth callback, you receive the sig field, which is the user's signature over the document digest. You can store this signature along with the user's DID as a durable, verifiable record of their consent.

Next Steps

After securing user agreement, you might need to verify specific attributes or qualifications they possess. Learn how to do this by requesting a Verifiable Credential.