README.md

VC

TypeScript types, JSON schemas, and signing and verifying functions for Verifiable Credentials and Presentations.

Installation

npm i @bloomprotocol/vc

OR

yarn add @bloomprotocol/vc

Usage

Signing

signVC

signVC takes a single parameter with the following properties:

Name	Description	Type
unsigned	The unsigned VC to be signed	Omit<VC, 'proof'>
suite	Signing suite that is compatible with jsonld-signatures	Class that is compatible with LinkedDataSignature
documentLoader	Function that resolves context URLs and DIDs	(url: string) => Promise<{document: null | Record<string, unknown>, documentUrl: string}> | {document: null | Record<string, unknown>, documentUrl: string}
proofPurposeOptions	Additional options to pass to the proof purpose class	undefined | Record<string, unknown>

import { signVC, VC } from '@bloomprotocol/vc'

const { Ed25519VerificationKey2020 } = require('@digitalbazaar/ed25519-verification-key-2020')
const { Ed25519Signature2020 } = require('@digitalbazaar/ed25519-signature-2020')

const unsignedVC: Omit<VC, 'proof'> = {
  '@context': ['https://www.w3.org/2018/credentials/v1', 'https://w3id.org/security/suites/ed25519-2020/v1'],
  id: 'urn:uuid:9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
  type: ['VerifiableCredential'],
  issuanceDate: new Date().toISOString(),
  issuer: 'did:example:issuer',
  credentialSubject: {},
}

const suite = new Ed25519Signature2020({
  key: new Ed25519VerificationKey2020(keyPair),
})

const vc = await signVC({
  unsigned: unsigngedVC,
  suite,
  documentLoader: (url: string) => {
    //...
  },
})

signVP

signVP takes a single parameter with the following properties:

Name	Description	Type
unsigned	The unsigned VP to be signed	Omit<VP, 'proof'>
suite	Signing suite that is compatible with jsonld-signatures	Class that is compatible with LinkedDataSignature
documentLoader	Function that resolves context URLs and DIDs	(url: string) => Promise<{document: null | Record<string, unknown>, documentUrl: string}> | {document: null | Record<string, unknown>, documentUrl: string}
proofPurposeOptions	Additional options to pass to the proof purpose class	{challenge: string, domain: string, [k: string]?: unknown}

import { signVC, VC } from '@bloomprotocol/vc'

const { Ed25519VerificationKey2020 } = require('@digitalbazaar/ed25519-verification-key-2020')
const { Ed25519Signature2020 } = require('@digitalbazaar/ed25519-signature-2020')

const unsignedVP: Omit<VP, 'proof'> = {
  '@context': ['https://www.w3.org/2018/credentials/v1', 'https://w3id.org/security/suites/ed25519-2020/v1'],
  id: 'urn:uuid:9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
  type: ['VerifiablePresentation'],
  holder: 'did:example:holder',
  verifiableCredential: [vc]
}

const suite = new Ed25519Signature2020({
  key: new Ed25519VerificationKey2020(keyPair),
})

const vp = await signVP({
  unsigned: unsigngedVP,
  suite,
  proofPurposeOptions: {
    challenge: '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed',
    domain: 'https://example.com'
  },
  documentLoader: (url: string) => {
    //...
  },
})

Verifying

verifyVC

verifyVC takes a single parameter with the following properties:

Name	Description	Type	Required	Default
vc	The VC to be verified	unknown	Yes	-
getSuite	Function that returns a signing suite that is compatible with jsonld-signatures	(options: { verificationMethod: string, controller: string, proofType: string }) => any | Promise<any>	Yes	-
documentLoader	Function that resolves context URLs and DIDs	(url: string) => Promise<{document: null | Record<string, unknown>, documentUrl: string}> | {document: null | Record<string, unknown>, documentUrl: string}	Yes	-
getProofPurposeOptions	Function that returns additional options to pass to the proof purpose class	(options: { proofPurpose: string, verificationMethod: string, controller: string }) => Record<string, unknown> | Promise<Record<string, unknown>>	No	-
schema	Custom json schema to validate the vc against	JSONSchema	No	vcSchema
ajv	Custom Ajv instance to use when validating the vc	Ajv	No	-
schemaKey	Custom key to use for Ajv caching of schemas	string	No	"vcSchema"

On success verifyVC returns:

type VerifyVCResponseSuccess<VCType extends VC> = {
  success: true
  vc: VCType
}

And on failure returns:

type VerifyVCResposeFailure = {
  success: false
  schemaErrors?: ErrorObject[]
  proofErrors?: ProofError[]
  issuanceErrors?: IssuanceError[]
}

• schemaErrors are errors returned from Ajv
• proofErrors are errors returned from jsonld-signatures
• issuanceErrors are errors about the VC's issuance and expiration date

verifyVP

verifyVP takes a single parameter with the following properties:

Name	Description	Type	Required	Default
vp	The VP to be verified	unknown	Yes	-
getSuite	Function that returns a signing suite that is compatible with jsonld-signatures	(options: { verificationMethod: string, controller: string, proofType: string }) => any | Promise<any>	Yes	-
documentLoader	Function that resolves context URLs and DIDs	(url: string) => Promise<{document: null | Record<string, unknown>, documentUrl: string}> | {document: null | Record<string, unknown>, documentUrl: string}	Yes	-
getProofPurposeOptions	Function that returns additional options to pass to the proof purpose class	(options: { proofPurpose: string, verificationMethod: string, controller: string }) => Record<string, unknown> | Promise<Record<string, unknown>>	No	-
schema	Custom json schema to validate the vp against	JSONSchema	No	vpSchema
ajv	Custom Ajv instance to use when validating the vp	Ajv	No	-
schemaKey	Custom key to use for Ajv caching of schemas	string	No	"vpSchema"

On success verifyVC returns:

type VerifyVPResponseSuccess<VPType extends VP> = {
  success: true
  vp: VPType
}

And on failure returns:

type VerifyVPResposeFailure = {
  success: false
  schemaErrors?: ErrorObject[]
  proofErrors?: ProofError[]
  credentialProofErrors?: {id: string, errors: ProofError[]}[]
  credentialiIssuanceErrors?: {id: string, errors: IssuanceError[]}[]
}

• schemaErrors are errors returned from Ajv
• proofErrors are errors returned from jsonld-signatures for the VP
• credentialProofErrors are errors returned from jsonld-signatures for the VCs within the VP
• credentialIssuanceErrors are errors about the issuance and expiration date for the VCs within the VP