Agreement Claim
The Agreement Claim is used to obtain a user's verifiable consent to a document, such as Terms of Service, a privacy policy, or a user agreement. It works by having the user sign a cryptographic hash (digest) of the document, ensuring that they agree to the exact content you specify.
This process provides a high level of integrity. The wallet fetches the document from the provided URI, calculates its digest, and compares it to the digest you supplied. If they match, the wallet prompts the user for their signature. If they don't, the process fails, protecting the user from agreeing to altered or fraudulent content.
Workflow#
The interaction follows a clear, verifiable sequence where the wallet acts as a trusted intermediary to ensure the document's integrity before requesting the user's signature.
Parameters#
The agreement claim object is configured with the following parameters:
Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| string | Yes | The public URL pointing to the full text of the document the user must agree to. | |
| string | Yes | The cryptographic hash of the document content at the | |
| string | No |
| The hashing algorithm used to generate the |
| string | No |
| A custom message displayed to the user in the wallet, explaining what they are agreeing to. |
Example Usage#
First, you need to generate a digest of the document you want the user to agree to. This must be done on your server to ensure its integrity.
Step 1: Generate the Document Digest (Node.js)
const crypto = require('crypto');
const fs = require('fs');
// Read your terms of service file
const termsContent = fs.readFileSync('public/terms-of-service.txt', 'utf8');
// Calculate its SHA256 digest
const digest = crypto.createHash('sha2').update(termsContent).digest('hex');
console.log('Document Digest:', digest);Step 2: Request the Agreement Claim
Use the generated digest in your DID Connect session configuration. The application requests the claim, and the onAuth callback processes the wallet's response.
// In your DID Connect route handler
const handlers = new WalletHandlers({
authenticator,
// ... other handlers
});
app.get('/api/auth/agreement', handlers.createAuthUrl({
claims: {
agreement: {
uri: 'https://yourapp.com/terms-of-service.txt',
digest: digest, // Use the digest generated in Step 1
method: 'sha2',
description: 'Please read and agree to our Terms of Service to proceed.',
},
},
onAuth: async ({ claims, session }) => {
// The claims array will contain the signed agreement
const agreementClaim = claims[0];
console.log('Agreement claim result:', agreementClaim);
// Store proof of agreement
session.set('userDid', agreementClaim.did);
session.set('agreedToTerms', true);
session.set('agreementSignature', agreementClaim.sig);
await session.save();
// Respond to the user
},
}));Wallet Response#
After the user approves the request in their wallet, the onAuth callback will receive an array of claims. The agreement claim result includes the user's signature over the digest, which serves as a non-repudiable proof of their consent.
// Sample claim object received in the onAuth callback
[
{
"type": "agreement",
"uri": "https://yourapp.com/terms-of-service.txt",
"digest": "...",
"method": "sha2",
"meta": {},
"sig": "...",
"pk": "...",
"did": "..."
}
]You should store the sig, pk, and digest to maintain a verifiable and auditable record of the user's agreement.
The Agreement Claim provides a robust way to capture user consent in a cryptographically verifiable manner. For scenarios requiring a signature on arbitrary data rather than a document, see the Signature Claim. To see all available claims, return to the Claims Reference.