@digitalbazaar/vc 6.1.0 → 6.3.0

package/README.md

@@ -48,7 +48,7 @@ the following:
 
 ## Install
 
-- Browsers and Node.js 14+ are supported.
+- Browsers and Node.js 18+ are supported.
 
 To install from NPM:
 
@@ -116,18 +116,161 @@ const signedVC = await vc.issue({credential, suite, documentLoader});
 console.log(JSON.stringify(signedVC, null, 2));
 ```
 
+### Issuing a Selective Disclosure Verifiable Credential
+
+Pre-requisites:
+
+* You have a private key (with id and controller) and corresponding suite
+* You have are using a cryptosuite that supports selective disclosure, such
+  as `ecdsa-sd-2023` or `bbs-2023`
+* If you're using a custom `@context`, make sure it's resolvable
+* (Recommended) You have a strategy for where to publish your Controller
+  Document and Public Key
+
+Issuing using `ecdsa-sd-2023`:
+
+```js
+import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
+import * as ecdsaSd2023Cryptosuite from
+  '@digitalbazaar/ecdsa-sd-2023-cryptosuite';
+import * as vc from '@digitalbazaar/vc';
+import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
+
+const ecdsaKeyPair = await EcdsaMultikey.generate({
+  curve: 'P-256',
+  id: 'https://example.edu/issuers/keys/2',
+  controller: 'https://example.edu/issuers/565049'
+});
+
+// sample exported key pair
+/*
+{
+  "@context": "https://w3id.org/security/multikey/v1",
+  "id": "https://example.edu/issuers/keys/2",
+  "type": "Multikey",
+  "controller": "https://example.edu/issuers/565049",
+  "publicKeyMultibase": "zDnaeWJjGpXnQAbEpRur3kSWFapGZbwGnFCkzyhiq7nDeXXrM",
+  "secretKeyMultibase": "z42trzSpncjWFaB9cKE2Gg5hxtbuAQa5mVJgGwjrugHMacdM"
+}
+*/
+
+// sample unsigned credential
+const credential = {
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1"
+  ],
+  "id": "https://example.com/credentials/1872",
+  "type": ["VerifiableCredential", "AlumniCredential"],
+  "issuer": "https://example.edu/issuers/565049",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "alumniOf": "Example University"
+  }
+};
+
+// setup ecdsa-sd-2023 suite for signing selective disclosure VCs
+const suite = new DataIntegrityProof({
+  signer: ecdsaKeyPair.signer(),
+  cryptosuite: createSignCryptosuite({
+    // require the `issuer` and `issuanceDate` fields to always be disclosed
+    // by the holder (presenter)
+    mandatoryPointers: [
+      '/issuanceDate',
+      '/issuer'
+    ]
+  })
+});
+// use a proof ID to enable it to be found and transformed into a disclosure
+// proof by the holder later
+const proofId = `urn:uuid:${uuid()}`;
+suite.proof = {id: proofId};
+
+const signedVC = await vc.issue({credential, suite, documentLoader});
+console.log(JSON.stringify(signedVC, null, 2));
+```
+
+Issuing using `bbs-2023`:
+
+```js
+import * as bbs2023Cryptosuite from '@digitalbazaar/bbs-2023-cryptosuite';
+import * as bls12381Multikey from '@digitalbazaar/bls12-381-multikey';
+import * as vc from '@digitalbazaar/vc';
+import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
+
+const bbsKeyPair = await bls12381Multikey.generate({
+  algorithm: 'BBS-BLS12-381-SHA-256';
+  id: 'https://example.edu/issuers/keys/3',
+  controller: 'https://example.edu/issuers/565049'
+});
+
+// sample exported key pair
+/*
+{
+  "@context": "https://w3id.org/security/multikey/v1",
+  "id": "https://example.edu/issuers/keys/3",
+  "type": "Multikey",
+  "controller": "https://example.edu/issuers/565049",
+  "publicKeyMultibase": "zUC72jQrt2BfyE57AVgHgThKCsH6HNo85X9SLNpAJaHb42cNDXhsRWL2KkrFtaiztPbbZjfDVQnQQMw2nMqAPUHnaQ3xEr7kUmcnBgv7S2wQSbRbr7mqsP153nU7yMh3ZN4ZryL",
+  "secretKeyMultibase": "z488y1niFCWnaV2i86q1raaa7qwBWZ6WTLeS1W1PrsbcsoNg"
+}
+*/
+
+// sample unsigned credential
+const credential = {
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1"
+  ],
+  // omit `id` to enable unlinkable disclosure
+  "type": ["VerifiableCredential", "AlumniCredential"],
+  "issuer": "https://example.edu/issuers/565049",
+  // use less precise date that is shared by a sufficiently large group
+  // of VCs to enable unlinkable disclosure
+  "issuanceDate": "2010-01-01T01:00:00Z",
+  "credentialSubject": {
+    // omit `id` to enable unlinkable disclosure
+    "alumniOf": "Example University"
+  }
+};
+
+// setup bbs-2023 suite for signing unlinkable selective disclosure VCs
+const suite = new DataIntegrityProof({
+  signer: bbsKeyPair.signer(),
+  cryptosuite: createSignCryptosuite({
+    // require the `issuer` and `issuanceDate` fields to always be disclosed
+    // by the holder (presenter)
+    mandatoryPointers: [
+      '/issuanceDate',
+      '/issuer'
+    ]
+  })
+});
+// note: do not include a proof ID to enable unlinkable selective disclosure
+
+const signedVC = await vc.issue({credential, suite, documentLoader});
+console.log(JSON.stringify(signedVC, null, 2));
+```
+
 ### Deriving a Selective Disclosure Verifiable Credential
 
+Note: This step is performed as a holder of a verifiable credential, not as
+an issuer.
+
 Pre-requisites:
 
 * You have a verifiable credential that was issued using a cryptosuite that
-  support selective disclosure, such as `ecdsa-sd-2023`
+  supports selective disclosure, such as `ecdsa-sd-2023` or `bbs-2023`
 * If you're using a custom `@context`, make sure it's resolvable
 
+Deriving using `ecdsa-sd-2023`:
+
 ```js
-import * as vc from '@digitalbazaar/vc';
+import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
 import * as ecdsaSd2023Cryptosuite from
   '@digitalbazaar/ecdsa-sd-2023-cryptosuite';
+import * as vc from '@digitalbazaar/vc';
 import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
 
 const {
@@ -136,8 +279,8 @@ const {
   createVerifyCryptosuite
 } = ecdsaSd2023Cryptosuite;
 
-// Sample signed credential
-const credential = {
+// sample VC
+const verifiableCredential = {
   "@context": [
     "https://www.w3.org/2018/credentials/v1",
     "https://www.w3.org/2018/credentials/examples/v1",
@@ -155,19 +298,19 @@ const credential = {
     "alumniOf": "<span lang=\"en\">Example University</span>"
   },
   "proof": {
-    "id": "urn:uuid:2ef8c7ce-a4da-44b4-ba7f-3d43eaf1e50c",
+    "id": "urn:uuid:318d9dce-bc7b-40b9-a956-c9160bf910db",
     "type": "DataIntegrityProof",
-    "created": "2023-11-13T22:58:06Z",
+    "created": "2024-01-12T21:53:11Z",
     "verificationMethod": "https://example.edu/issuers/keys/2",
     "cryptosuite": "ecdsa-sd-2023",
     "proofPurpose": "assertionMethod",
-    "proofValue": "u2V0AhVhAtYPKUQxwULXzMdsAfqtipsiX6YEPURYSBFYxoFY-v0vCPyAs1Ckyy61Wtk3xZWyBGNaEr3w0wQiJHHd5B9uR-1gjgCQCVtFPMk-ECi0CJFYv_GTjCChf8St0FQjuExTAnwP0-ipYIOHSun3YqabOfNe2DYFkHBTZa0Csf1a7YUDW8hhsOHqTglhA8aqnyanT-Ybo2-aHBTcI-UmHX0iluGb2IxoHLLhQoOPm2rDW0eB04Fa2Dh6WMKoOl_Bz3wZZDGQ31XoGrQvgIlhAo8qspvC-QQ-xI3KADiA12sO5LRsZ7hl9ozoJEECVsDOKlxWd-dhices5b2ZQIiiRE9XxxJx8YuwCMoD2bRLbOIJtL2lzc3VhbmNlRGF0ZWcvaXNzdWVy"
+    "proofValue": "u2V0AhVhAsl6PQKYE15R0O5Qd267ntwHGNH6JRvZ1y8A-fTCQLUoupP8SCZzzmyc0a1AnabHEVKhpHtYV8j9Kapp-fHFBtFgjgCQCIMn2L1R7D5VPnNn_2foxdj8qvsuUTGFqA34YBkguzCpYILfJ-qNQpn6_dJGpkG24FynqbHpnzoHWVJc2kiLqEKHRglhAUmZtstR9MOLrZjcR8J303MXFvRiE6J3bbaPT1_I9-6578-Wj-eydv2TEGBq_dmsjxsOh4_2Va0etw8CXXMAzaVhA9fr7_Sl9D67AfvLhkJTZ0uJCAXcbL2MaS-DmoC7K-ABxroL1_wj119J8yTMlazxzYBwYkihrdp4ZWJZxraX9tIJtL2lzc3VhbmNlRGF0ZWcvaXNzdWVy"
   }
 };
 
 // note no `signer` needed; the selective disclosure credential will be
 // derived from the base proof already provided by the issuer
-const ecdsaSdDeriveSuite = new DataIntegrityProof({
+const suite = new DataIntegrityProof({
   cryptosuite: createDiscloseCryptosuite({
     // the ID of the base proof to convert to a disclosure proof
     proofId: 'urn:uuid:da088899-3439-41ea-a580-af3f1cf98cd3',
@@ -181,7 +324,68 @@ const ecdsaSdDeriveSuite = new DataIntegrityProof({
   })
 });
 
-const derivedVC = await vc.derive({credential, suite, documentLoader});
+const derivedVC = await vc.derive({
+  verifiableCredential, suite, documentLoader
+});
+console.log(JSON.stringify(derivedVC, null, 2));
+```
+
+Deriving using `bbs-2023`:
+
+```js
+import * as bbs2023Cryptosuite from '@digitalbazaar/bbs-2023-cryptosuite';
+import * as bls12381Multikey from '@digitalbazaar/bls12-381-multikey';
+import * as vc from '@digitalbazaar/vc';
+import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
+
+const {
+  createDiscloseCryptosuite,
+  createSignCryptosuite,
+  createVerifyCryptosuite
+} = bbs2023Cryptosuite;
+
+// sample VC
+const verifiableCredential = {
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1",
+    "https://w3id.org/security/data-integrity/v2"
+  ],
+  "type": [
+    "VerifiableCredential",
+    "AlumniCredential"
+  ],
+  "issuer": "https://example.edu/issuers/565049",
+  "issuanceDate": "2010-01-01T01:00:00Z",
+  "credentialSubject": {
+    "alumniOf": "<span lang=\"en\">Example University</span>"
+  },
+  "proof": {
+    "type": "DataIntegrityProof",
+    "verificationMethod": "https://example.edu/issuers/keys/3",
+    "cryptosuite": "bbs-2023",
+    "proofPurpose": "assertionMethod",
+    "proofValue": "u2V0ChVhQp1smqO-Qmc-1KpNkShjevTeylTdVlpH_RNXeJ_cNniErWPbEWILvsoH5mYjnun5ibZHq0m7BEIaLv8sfMtLfcmgPj6tbAFwDWvEcbRWg7CFYQGWqCAnvTpL_Aao3aVCg5svdzFuvKqnvneA0UwaN0lagvGpWT7fCDGgcYPyNPKaCX94Xo06aTcSwOXgyGUbtN1xYYIU6t5wv20lVdESfzkYOFXTxIZa1HSBAZYWDyEgQ3A3ajzWX5qeFc3cwmnnrGUfJYwawgGLQAY3vBi3LTM2i3jCOPvxCEJALPIjK4tEmWb6uFjT4PWLlIEeTtYj_0yEv91ggsm9vw1PPlK6q8wQiw2i2joZ-OKkvHz7rDSxPYfmQNrqCbS9pc3N1YW5jZURhdGVnL2lzc3Vlcg"
+  }
+};
+
+// note no `signer` needed; the selective disclosure credential will be
+// derived from the base proof already provided by the issuer
+const suite = new DataIntegrityProof({
+  cryptosuite: createDiscloseCryptosuite({
+    // selectively disclose the entire credential subject; different JSON
+    // pointers could be provided to selectively disclose different information;
+    // the issuer will have mandatory fields that will be automatically
+    // disclosed such as the `issuer` and `issuanceDate` fields
+    selectivePointers: [
+      '/credentialSubject'
+    ]
+  })
+});
+
+const derivedVC = await vc.derive({
+  verifiableCredential, suite, documentLoader
+});
 console.log(JSON.stringify(derivedVC, null, 2));
 ```
 

package/lib/index.js

@@ -167,7 +167,8 @@ export async function derive({
   documentLoader = defaultDocumentLoader
 } = {}) {
   if(!verifiableCredential) {
-    throw new TypeError('"credential" parameter is required for deriving.');
+    throw new TypeError(
+      '"verifiableCredential" parameter is required for deriving.');
   }
   if(!suite) {
     throw new TypeError('"suite" parameter is required for deriving.');
@@ -654,10 +655,13 @@ export function _checkCredential({
   }
 
   if('credentialStatus' in credential) {
-    if(!credential.credentialStatus.id) {
+    const {credentialStatus} = credential;
+    if(Array.isArray(credentialStatus) ?
+      credentialStatus.some(cs => !cs.id) : !credentialStatus.id) {
       throw new Error('"credentialStatus" must include an id.');
     }
-    if(!credential.credentialStatus.type) {
+    if(Array.isArray(credentialStatus) ?
+      credentialStatus.some(cs => !cs.type) : !credentialStatus.type) {
       throw new Error('"credentialStatus" must include a type.');
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/vc",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "description": "Verifiable Credentials JavaScript library.",
   "homepage": "https://github.com/digitalbazaar/vc",
   "author": {
@@ -33,6 +33,8 @@
     "jsonld-signatures": "^11.2.1"
   },
   "devDependencies": {
+    "@digitalbazaar/bbs-2023-cryptosuite": "^1.0.0",
+    "@digitalbazaar/bls12-381-multikey": "^1.1.1",
     "@digitalbazaar/credentials-examples-context": "^1.0.0",
     "@digitalbazaar/data-integrity": "^2.0.0",
     "@digitalbazaar/data-integrity-context": "^2.0.0",
@@ -72,7 +74,7 @@
     ]
   },
   "engines": {
-    "node": ">=14"
+    "node": ">=18"
   },
   "keywords": [
     "JSON",