@bloomprotocol/vc NPM

VC

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

Installation

npm i @bloomprotocol/vc

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

ajv ajv-formats jest jest-environment-node json-schema-to-ts jsonld jsonld-signatures ts-jest

@infinitebrahmanuniverse/nolb-_bloo @everything-registry/sub-chunk-132 @bloomprotocol/vc-data

9 months ago

2 years ago

3 years ago

3 years ago

3 years ago

3 years ago