Work with Verifiable Credentials

@arcblock/vc includes several utility functions to issue and verify verifiable credentials and their presentations.

Add Library to project

Add @arcblock/vc to your project before creating or verifying any verifiable credential.

npm install @arcblock/vc -S
# yarn add @arcblock/vc

Issue Verifiable Credential

Create a verifiable credential, the result can be sent and stored in DID Wallet.

Usage: create(params), the param should be like:

Param	Type	Description
params.type	`string`	The type of credential, can be an array
params.subject	`object`	The content of credential
params.issuer	`object`	The issuer name and wallet
params.issuanceDate	`Date`	Default to now
params.expirationDate	`Date`	Default to null, never expire
params.endpoint	`String`	Status endpoint url
params.endpointScope	`String`	Endpoint scope, either be public or private

Basic Credential

Example:

const { create } = require("@arcblock/vc");
const { fromRandom, fromSecretKey, fromAddress } = require("@ocap/wallet");

// the verifiable credential issuer,
// in real word applications, you should replace fromRandom with fromSecretKey
// const issuer = fromSecretKey(process.env.VC_ISSUER_SK);
const issuer = fromRandom();

// the verifiable credential holder
// in real word applications, you should replace fromRandom with fromAddress
// const holder = fromAddress(process.env.ENV_HOLDER);
const holder = fromRandom();

const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    // the only required field in subject, the id of the holder
    id: holder.address,
    // other fields can be customized
    completed: {
      course: "Developer Training Program",
    },
  },
});

console.log(vc);

Simple Verifiable Credential

Add Credential Display

const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    id: holder.address,
    completed: {
      course: "Developer Training Program",
    },
    display: {
      content: "https://www.example.com/api/vc/display",
      type: "url",
    },
  },
});

console.log(vc);

Verifiable Credential With Display

Add Credential Endpoint

const vc = create({
  type: "CourseCertificate",
  issuer: {
    name: "Online Course Platform",
    wallet: issuer,
  },
  subject: {
    id: holder.address,
    completed: {
      course: "Developer Training Program",
    },
  },
  endpoint: "https://www.example.com/api/vc/status",
});

console.log(vc);

Verifiable Credential With Endpoint

Verify Verifiable Credential

Verify that the verifiable credential is valid:

The credential is signed by a whitelist of issuers
The credential is owned by the holder
The credential has valid signature by the issuer
The credential is not expired

Usage: verify(vc, ownerDid, trustedIssuers)

Param	Type	Description
vc	`object`	the verifiable credential object
ownerDid	`string`	the holder/owner did
trustedIssuers	`Array`	the list of issuer did

Example:

const { verify } = require("@arcblock/vc");
const { fromSecretKey, fromAddress } = require("@ocap/wallet");

// the verifiable credential issuer,
const issuer = fromSecretKey(process.env.VC_ISSUER_SK);

// the verifiable credential holder
const holder = fromAddress(process.env.ENV_HOLDER);

// verify the credential just created or received from user
const isValid = verify({
  vc,
  ownerDid: holder.address,
  trustedIssuers: issuer.address,
});

Verify Credential Presentation

When your application requested and received a verifiable credential from the user, you must verify it before trust and use it.

The verifiable credential presentation is a special credential signed by the credential holder who claims to own the credential.
Usually a random challenge is generated and sent to user when requesting the presentation

The basic verification process:

Ensure the presentation is signed by the verifiable credential holder
Ensure the presentation contains the challenge
Ensure the verifiable credential has a valid signature by the issuer
Ensure the verifiable credential is not expired

Usage: verifyPresentation(presentation, trustedIssuers, challenge)

Param	Type	Description
presentation	`object`	the presentation object
trustedIssuers	`Array`	list of issuer did
challenge	`string`	Random byte you want

Example:

const presentation = {
  verifiableCredential: [
    '{"@context":"https://schema.arcblock.io/v0.1/context.jsonld","credentialSubject":{"emailDigest":"rDh76MCmM1tEPS8Qd1xGThFJfskGP2PSO8aNqv58IhQ","id":"z1QUxXyLNRWv18ubUdcuu7iPTQdWzRy294C","method":"SHA3"},"id":"z2iUJs3vdJnE1CkaYDPAm1EEWVbNPpcEm6QhL","issuanceDate":"2020-03-30T09:56:31.175Z","issuer":{"id":"zNKrLtPXN5ur9qMkwKWMYNzGi4D6XjWqTEjQ","name":"ArcBlock.KYC.Email","pk":"zDLTrgAHr33NyKx9eD9PFUqySHjGnXpHL7upNvCySx1s4"},"proof":{"created":"2020-03-30T09:56:31.180Z","jws":"EtT4SMpmPK5AhGBstJNnymJ9lwQVC2cI-1N5O3o3iGT8gVB0lfg9oGlCGpwsuK1Zn1lLiNEYBD7eKFjwcA0rCw","proofPurpose":"assertionMethod","type":"Ed25519Signature"},"type":"EmailVerificationCredential"}',
  ],
  type: "Ed25519Signature",
  proof: {
    type: "Ed25519Signature",
    proofPurpose: "assertionMethod",
    pk: "zJ5bH7Jy27jSDf3AE3ntoRwNBhPRX6RXaSwTUh272jwK5",
    jws: "ua-2kBFcn8rwNcd1BkckETnjQTW8nA5EcJ8PcXWirqB51SV9RaHvUChyFFUz_DLL_T-xlwcaQPaW0_q9Hkx3BQ",
    created: "2020-03-31T11:48:02Z",
  },
  challenge: "257A2EC62ED802304F65624C73A53CAA",
  "@context": ["https://schema.arcblock.io/v0.1/context.jsonld"],
};
const result = verifyPresentation({
  presentation,
  trustedIssuers: ["zNKrLtPXN5ur9qMkwKWMYNzGi4D6XjWqTEjQ"],
  challenge: "257A2EC62ED802304F65624C73A53CAA",
});
console.log(result);