@digitalbazaar/vc 6.0.2 → 6.2.0

package/README.md

@@ -116,6 +116,140 @@ 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`
+* 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
+
+```js
+import * as vc from '@digitalbazaar/vc';
+import * as ecdsaSd2023Cryptosuite from
+  '@digitalbazaar/ecdsa-sd-2023-cryptosuite';
+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 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));
+```
+
+### 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
+  supports selective disclosure, such as `ecdsa-sd-2023`
+* If you're using a custom `@context`, make sure it's resolvable
+
+```js
+import * as vc from '@digitalbazaar/vc';
+import * as ecdsaSd2023Cryptosuite from
+  '@digitalbazaar/ecdsa-sd-2023-cryptosuite';
+import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
+
+const {
+  createDiscloseCryptosuite,
+  createSignCryptosuite,
+  createVerifyCryptosuite
+} = ecdsaSd2023Cryptosuite;
+
+// sample signed credential
+const credential = {
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://www.w3.org/2018/credentials/examples/v1",
+    "https://w3id.org/security/data-integrity/v2"
+  ],
+  "id": "http://example.edu/credentials/1872",
+  "type": [
+    "VerifiableCredential",
+    "AlumniCredential"
+  ],
+  "issuer": "https://example.edu/issuers/565049",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "alumniOf": "<span lang=\"en\">Example University</span>"
+  },
+  "proof": {
+    "id": "urn:uuid:2ef8c7ce-a4da-44b4-ba7f-3d43eaf1e50c",
+    "type": "DataIntegrityProof",
+    "created": "2023-11-13T22:58:06Z",
+    "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"
+  }
+};
+
+// 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({
+    // the ID of the base proof to convert to a disclosure proof
+    proofId: 'urn:uuid:da088899-3439-41ea-a580-af3f1cf98cd3',
+    // 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));
+```
+
 ### Creating a Verifiable Presentation
 
 Pre-requisites:
@@ -355,6 +489,27 @@ const result = await vc.verifyCredential({credential, suite, documentLoader});
 // {valid: true}
 ```
 
+To verify a selective disclosure verifiable credential ensure the suite
+supports it, for example:
+
+```js
+import * as ecdsaSd2023Cryptosuite from
+  '@digitalbazaar/ecdsa-sd-2023-cryptosuite';
+import {DataIntegrityProof} from '@digitalbazaar/data-integrity';
+
+const {
+  createDiscloseCryptosuite,
+  createSignCryptosuite,
+  createVerifyCryptosuite
+} = ecdsaSd2023Cryptosuite;
+
+const suite = new DataIntegrityProof({
+  cryptosuite: createVerifyCryptosuite()
+});
+const result = await vc.verifyCredential({credential, suite, documentLoader});
+// {valid: true}
+```
+
 To verify a verifiable credential with a custom `@context` field use a
 [custom documentLoader](#custom-documentLoader)
 

package/lib/index.js

@@ -42,7 +42,7 @@ export const defaultDocumentLoader =
   jsigs.extendContextLoader(_documentLoader);
 import * as credentialsContext from 'credentials-context';
 
-const {AuthenticationProofPurpose} = jsigs.purposes;
+const {AssertionProofPurpose, AuthenticationProofPurpose} = jsigs.purposes;
 const {constants: {CREDENTIALS_CONTEXT_V1_URL}} = credentialsContext;
 
 export {CredentialIssuancePurpose};
@@ -99,7 +99,7 @@ export const dateRegex = new RegExp('^(\\d{4})-(0[1-9]|1[0-2])-' +
  *
  * @param {object} options.credential - Base credential document.
  * @param {LinkedDataSignature} options.suite - Signature suite (with private
- *   key material), passed in to sign().
+ *   key material or an API to use it), passed in to sign().
  *
  * @param {ProofPurpose} [options.purpose] - A ProofPurpose. If not specified,
  *   a default purpose will be created.
@@ -135,7 +135,7 @@ export async function issue({
   // Set the issuance date to now(), if missing
   if(!credential.issuanceDate) {
     const now = (new Date()).toJSON();
-    credential.issuanceDate = `${now.substr(0, now.length - 5)}Z`;
+    credential.issuanceDate = `${now.slice(0, now.length - 5)}Z`;
   }
 
   // run common credential checks
@@ -144,6 +144,45 @@ export async function issue({
   return jsigs.sign(credential, {purpose, documentLoader, suite});
 }
 
+/**
+ * Derives a proof from the given verifiable credential, resulting in a new
+ * verifiable credential. This method is usually used to generate selective
+ * disclosure and / or unlinkable proofs.
+ *
+ * @param {object} [options={}] - The options to use.
+ *
+ * @param {object} options.verifiableCredential - The verifiable credential
+ *   containing a base proof to derive another proof from.
+ * @param {LinkedDataSignature} options.suite - Derived proof signature suite.
+ *
+ * Other optional params passed to `derive()`:
+ * @param {object} [options.documentLoader] - A document loader.
+ *
+ * @throws {Error} If missing required properties.
+ *
+ * @returns {Promise<VerifiableCredential>} Resolves on completion.
+ */
+export async function derive({
+  verifiableCredential, suite,
+  documentLoader = defaultDocumentLoader
+} = {}) {
+  if(!verifiableCredential) {
+    throw new TypeError('"credential" parameter is required for deriving.');
+  }
+  if(!suite) {
+    throw new TypeError('"suite" parameter is required for deriving.');
+  }
+
+  // run common credential checks
+  _checkCredential({credential: verifiableCredential, mode: 'issue'});
+
+  return jsigs.derive(verifiableCredential, {
+    purpose: new AssertionProofPurpose(),
+    documentLoader,
+    suite
+  });
+}
+
 /**
  * Verifies a verifiable presentation:
  *   - Checks that the presentation is well-formed
@@ -484,7 +523,6 @@ async function _verifyPresentation(options = {}) {
  *   or a string that is an id.
  * @returns {string|undefined} Either an id or undefined.
  * @private
- *
  */
 function _getId(obj) {
   if(typeof obj === 'string') {
@@ -532,11 +570,15 @@ export function _checkPresentation(presentation) {
  *   VerifiableCredential.
  * @param {string|Date} [options.now] - A string representing date time in
  *   ISO 8601 format or an instance of Date. Defaults to current date time.
+ * @param {string} [options.mode] - The mode of operation for this
+ *   validation function, either `issue` or `verify`.
  *
  * @throws {Error}
  * @private
  */
-export function _checkCredential({credential, now = new Date(), mode = 'verify'}) {
+export function _checkCredential({
+  credential, now = new Date(), mode = 'verify'
+} = {}) {
   if(typeof now === 'string') {
     now = new Date(now);
   }
@@ -612,10 +654,10 @@ export function _checkCredential({credential, now = new Date(), mode = 'verify'}
   }
 
   if('credentialStatus' in credential) {
-    if(!credential.credentialStatus.id) {
+    if(Array.isArray(credential.credentialStatus) ? credential.credentialStatus.some(cs => !cs.id) : !credential.credentialStatus.id) {
       throw new Error('"credentialStatus" must include an id.');
     }
-    if(!credential.credentialStatus.type) {
+    if(Array.isArray(credential.credentialStatus) ? credential.credentialStatus.some(cs => !cs.type) : !credential.credentialStatus.type) {
       throw new Error('"credentialStatus" must include a type.');
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/vc",
-  "version": "6.0.2",
+  "version": "6.2.0",
   "description": "Verifiable Credentials JavaScript library.",
   "homepage": "https://github.com/digitalbazaar/vc",
   "author": {
@@ -29,29 +29,34 @@
   ],
   "dependencies": {
     "credentials-context": "^2.0.0",
-    "jsonld": "^8.1.0",
-    "jsonld-signatures": "^11.0.0"
+    "jsonld": "^8.3.1",
+    "jsonld-signatures": "^11.2.1"
   },
   "devDependencies": {
+    "@digitalbazaar/credentials-examples-context": "^1.0.0",
+    "@digitalbazaar/data-integrity": "^2.0.0",
+    "@digitalbazaar/data-integrity-context": "^2.0.0",
+    "@digitalbazaar/ecdsa-multikey": "^1.6.0",
+    "@digitalbazaar/ecdsa-sd-2023-cryptosuite": "^3.0.0",
     "@digitalbazaar/ed25519-signature-2018": "^4.0.0",
     "@digitalbazaar/ed25519-verification-key-2018": "^4.0.0",
-    "@digitalbazaar/credentials-examples-context": "^1.0.0",
+    "@digitalbazaar/multikey-context": "^1.0.0",
     "@digitalbazaar/odrl-context": "^1.0.0",
-    "c8": "^7.12.0",
+    "c8": "^8.0.1",
     "chai": "^4.3.7",
     "cross-env": "^7.0.3",
     "did-context": "^3.1.1",
     "did-veres-one": "^16.0.0",
-    "eslint": "^8.32.0",
-    "eslint-config-digitalbazaar": "^4.2.0",
-    "eslint-plugin-jsdoc": "^39.6.4",
-    "eslint-plugin-unicorn": "^45.0.2",
+    "eslint": "^8.53.0",
+    "eslint-config-digitalbazaar": "^5.0.1",
+    "eslint-plugin-jsdoc": "^46.9.0",
+    "eslint-plugin-unicorn": "^49.0.0",
     "karma": "^6.4.1",
     "karma-chai": "^0.1.0",
     "karma-chrome-launcher": "^3.1.1",
     "karma-mocha": "^2.0.1",
     "karma-mocha-reporter": "^2.2.5",
-    "karma-sourcemap-loader": "^0.3.8",
+    "karma-sourcemap-loader": "^0.4.0",
     "karma-webpack": "^5.0.0",
     "mocha": "^10.2.0",
     "mocha-lcov-reporter": "^1.3.0",