Validating Verifiable Credentials

This document describes how to verify Heima Verifiable Credentials using the client-sdk.

Before continuing, make sure you have completed all the steps from the Installation section.

For the code snippets below,

Parsing

The parsing functionality allows to safely parse a JSON string that may be a Verifiable Credential. If the parsing succeeds, the returned value will be a rich-typed object describing the Verifiable Credential.

While parsing doesn’t verify VC, it will ensure it is semantically correct and compliant with Heima Credential Definitions.

Use parsing to display information of the VC in your UI, or to extract a specific value from it.

Here is an example of parsing a VC JSON string.

import { parseVc } from '@heima/client-sdk';

const vcJson =
  '{"@context":["<https://www.w3.org/2018/credentials/v1","https://w3id.org/security/suites/ed25519-2020/v1"],"id":"0x417b9a7a1fbfc214f9865693c52a159020de90aeea5cce556b9ee7c52b7e5de5","type":["VerifiableCredential"],"credentialSubject":{"id":"did:heima:evm:0x0ace67628bd43213c1c41ca1daef47e63923c75c","description":"The> user is an early bird user of the IdentityHub EVM version and has generated at least 1 credential during 2023 Aug 14th ~ Aug 21st.","type":"IDHub EVM Version Early Bird","assertionText":"A20","assertions":[{"src":"$has_joined","op":"==","dst":"true"}],"values":[true],"endpoint":"wss://rpc.heima-parachain.heima.io"},"issuer":{"id":"did:heima:substrate:0xbf6ae6b420f26aae8717dcd7ccc7d0caf543a27dbd5f622ea666e2eff6d1ec77","name":"Heima TEE Worker","mrenclave":"C58kRb2Rcj2znMmjYD2cUcMxAQSuDbXkNRUXcS7GYzCt"},"issuanceDate":"2024-05-21T15:38:16.916733831+00:00","parachainBlockNumber":806966,"sidechainBlockNumber":3963686,"proof":{"created":"2024-05-21T15:38:16.917539903+00:00","type":"Ed25519Signature2020","proofPurpose":"assertionMethod","proofValue":"17ee44e66da56470c695b43341b4952896a5ce48bd6f8c1da814efec1b2cf143e7cbaf56b44708bbbc5f6aaa85068249fc42164ce118ea1355b48c022890f100","verificationMethod":"0xbf6ae6b420f26aae8717dcd7ccc7d0caf543a27dbd5f622ea666e2eff6d1ec77"},"credentialSchema":{"id":"<https://raw.githubusercontent.com/litentry/vc-jsonschema/main/dist/schemas/12-idhub-evm-version-early-bird/1-0-0.json","type":"JsonSchemaValidator2018>"}}';

try {
  // Parse the VC JSON string
  const parsedVc = parseVc(vcJson);

  // Use the parsed VerifiableCredential
  // Try it on TypeScript to see autocompletion.
  console.log('Parsed Verifiable Credential:', parsedVc);
} catch (error) {
  // Handle parsing errors
  console.error('Error parsing Verifiable Credential:', error);
}

Please refer to the Requesting a Verifiable Credential section to learn how to generate this VC using the Heima Protocol.

If you are looking for more ready-to-use verifiable credentials files for your tests, you can check the examples folder in the vc-jsonschema repository.

Validating

The Verifiable Credential validation consists of three stages:

1. The VC is semantically correct.

2. The self-contained proof checks-up

3. The issuer is a trusted Heima Enclave Worker.

Validating Verifiable Credential guarantees that the VC’s content hasn’t been tampered with and that it was issued by a trusted node of the Heima Protocol.

Example:

import { validateVc } from '@heima/client-sdk';

// Please refer to the installation documentation to learn how to
// properly instantiate Api.
import { api } from '../my-project/api'; 

// vc json string
const vcJson =
  '{"@context": "<https://www.w3.org/2018/credentials/v1>", "type": "VerifiableCredential", "issuer": "<https://example.com/issuer>", "subject": "did:example:123", "credentialStatus": "<https://example.com/status>"}';
const result = await validateVc(api, vcJson);

if (result.isValid) {
	console.log('✨ success. the VC is valid.');
} 
// isValid is false if any field value of the result.detail is not true
else {
  // true or error message
  console.log('vcSignature: ', result.detail.vcSignature);
  // true or error message
  console.log('enclaveRegistry: ', result.detail.enclaveRegistry);
}