@bedrock/vc-delivery 4.6.0 → 4.7.0

package/lib/constants.js

@@ -0,0 +1,5 @@
+/*!
+ * Copyright (c) 2024 Digital Bazaar, Inc. All rights reserved.
+ */
+// maximum number of issuer instances that can be associated with a workflow
+export const MAX_ISSUER_INSTANCES = 10;

package/lib/helpers.js

@@ -48,6 +48,20 @@ export async function generateRandom() {
   });
 }
 
+export function getWorkflowIssuerInstances({workflow} = {}) {
+  let {issuerInstances} = workflow;
+  if(!issuerInstances && workflow.zcaps.issue) {
+    // generate dynamic issuer instance config
+    issuerInstances = [{
+      supportedFormats: ['application/vc', 'ldp_vc'],
+      zcapReferenceIds: {
+        issue: 'issue'
+      }
+    }];
+  }
+  return issuerInstances;
+}
+
 export async function getZcapClient({workflow} = {}) {
   // get service agent for communicating with the issuer instance
   const {pathname} = new URL(workflow.id);

package/lib/http.js

@@ -88,31 +88,46 @@ export async function addRoutes({app, service} = {}) {
           });
         }
 
-        // perform key generation if requested
-        if(openId?.oauth2?.generateKeyPair) {
-          const {oauth2} = openId;
-          const {algorithm} = oauth2.generateKeyPair;
-          const kp = await generateKeyPair(algorithm, {extractable: true});
-          const [privateKeyJwk, publicKeyJwk] = await Promise.all([
-            exportJWK(kp.privateKey),
-            exportJWK(kp.publicKey),
-          ]);
-          oauth2.keyPair = {privateKeyJwk, publicKeyJwk};
-          delete oauth2.generateKeyPair;
-        } else if(openId) {
-          // ensure key pair can be imported
-          try {
-            const {oauth2: {keyPair}} = openId;
-            await Promise.all([
-              importJWK(keyPair.privateKeyJwk),
-              importJWK(keyPair.publicKeyJwk)
+        if(openId) {
+          // either issuer instances or a single issuer zcap be given if
+          // any expected credential requests are given
+          const {expectedCredentialRequests} = openId;
+          if(expectedCredentialRequests &&
+            !(config.issuerInstances || config.zcaps.issue)) {
+            throw new BedrockError(
+              'Credential requests are not supported by this workflow.', {
+                name: 'DataError',
+                details: {httpStatusCode: 400, public: true}
+              });
+          }
+
+          // perform key generation if requested
+          if(openId.oauth2?.generateKeyPair) {
+            const {oauth2} = openId;
+            const {algorithm} = oauth2.generateKeyPair;
+            const kp = await generateKeyPair(algorithm, {extractable: true});
+            const [privateKeyJwk, publicKeyJwk] = await Promise.all([
+              exportJWK(kp.privateKey),
+              exportJWK(kp.publicKey),
             ]);
-          } catch(e) {
-            throw new BedrockError('Could not import OpenID OAuth2 key pair.', {
-              name: 'DataError',
-              details: {httpStatusCode: 400, public: true},
-              cause: e
-            });
+            oauth2.keyPair = {privateKeyJwk, publicKeyJwk};
+            delete oauth2.generateKeyPair;
+          } else {
+            // ensure key pair can be imported
+            try {
+              const {oauth2: {keyPair}} = openId;
+              await Promise.all([
+                importJWK(keyPair.privateKeyJwk),
+                importJWK(keyPair.publicKeyJwk)
+              ]);
+            } catch(e) {
+              throw new BedrockError(
+                'Could not import OpenID OAuth2 key pair.', {
+                  name: 'DataError',
+                  details: {httpStatusCode: 400, public: true},
+                  cause: e
+                });
+            }
           }
         }
 

package/lib/index.js

@@ -7,6 +7,7 @@ import {createService, schemas} from '@bedrock/service-core';
 import {addRoutes} from './http.js';
 import {initializeServiceAgent} from '@bedrock/service-agent';
 import {klona} from 'klona';
+import {MAX_ISSUER_INSTANCES} from './constants.js';
 import {parseLocalId} from './helpers.js';
 import '@bedrock/express';
 
@@ -26,12 +27,20 @@ async function _initService({serviceType, routePrefix}) {
   const createConfigBody = klona(schemas.createConfigBody);
   const updateConfigBody = klona(schemas.updateConfigBody);
   const schemasToUpdate = [createConfigBody, updateConfigBody];
-  const {credentialTemplates, steps, initialStep} = workflowSchemas;
+  const {
+    credentialTemplates, steps, initialStep, issuerInstances
+  } = workflowSchemas;
   for(const schema of schemasToUpdate) {
     // add config requirements to workflow configs
     schema.properties.credentialTemplates = credentialTemplates;
     schema.properties.steps = steps;
     schema.properties.initialStep = initialStep;
+    schema.properties.issuerInstances = issuerInstances;
+    // allow zcaps by custom reference ID
+    schema.properties.zcaps = klona(schemas.zcaps);
+    // max of 4 basic zcaps + max issuer instances
+    schema.properties.zcaps.maxProperties = 4 + MAX_ISSUER_INSTANCES;
+    schema.properties.zcaps.additionalProperties = schemas.delegatedZcap;
     // note: credential templates are not required; if any other properties
     // become required, add them here
     // schema.required.push('credentialTemplates');
@@ -117,17 +126,36 @@ async function validateConfigFn({config, op, routePrefix} = {}) {
 
     // if credential templates are specified, then `zcaps` MUST include at
     // least `issue`
-    const {credentialTemplates = [], zcaps = {}} = config;
-    if(credentialTemplates.length > 0 && !zcaps.issue) {
-      throw new BedrockError(
-        'A capability to issue credentials is required when credential ' +
-        'templates are provided.', {
-          name: 'DataError',
-          details: {
-            httpStatusCode: 400,
-            public: true
-          }
-        });
+    const {credentialTemplates = [], zcaps = {}, issuerInstances} = config;
+    if(credentialTemplates.length > 0) {
+      if(!(zcaps.issue || issuerInstances)) {
+        throw new BedrockError(
+          'A capability to issue credentials is required when credential ' +
+          'templates are provided.', {
+            name: 'DataError',
+            details: {
+              httpStatusCode: 400,
+              public: true
+            }
+          });
+      }
+      // ensure that, if `issuerInstances` is given, that every zcap
+      // referenced in each issuer instance config's `zcapReferenceIds` can
+      // be found in `zcaps`
+      if(issuerInstances) {
+        if(!issuerInstances.every(
+          instance => !!zcaps[instance.zcapReferenceIds.issue])) {
+          throw new BedrockError(
+            'An issuer instance configuration zcap reference ID is not ' +
+            'present in "config.zcaps".', {
+              name: 'DataError',
+              details: {
+                httpStatusCode: 400,
+                public: true
+              }
+            });
+        }
+      }
     }
 
     // if `steps` are specified, then `initialStep` MUST be included

package/lib/issue.js

@@ -1,24 +1,30 @@
 /*!
  * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
  */
-import {evaluateTemplate, getZcapClient} from './helpers.js';
+import {
+  evaluateTemplate,
+  getWorkflowIssuerInstances,
+  getZcapClient
+} from './helpers.js';
 import {createPresentation} from '@digitalbazaar/vc';
 
-export async function issue({workflow, exchange} = {}) {
+export async function issue({
+  workflow, exchange, format = 'application/vc'
+} = {}) {
   // use any templates from workflow and variables from exchange to produce
   // credentials to be issued; issue via the configured issuer instance
   const verifiableCredential = [];
   const {credentialTemplates = []} = workflow;
   if(!credentialTemplates || credentialTemplates.length === 0) {
     // nothing to issue
-    return {};
+    return {response: {}};
   }
 
   // evaluate template
-  const credentialRequests = await Promise.all(credentialTemplates.map(
+  const issueRequests = await Promise.all(credentialTemplates.map(
     typedTemplate => evaluateTemplate({workflow, exchange, typedTemplate})));
   // issue all VCs
-  const vcs = await _issue({workflow, credentialRequests});
+  const vcs = await _issue({workflow, issueRequests, format});
   verifiableCredential.push(...vcs);
 
   // generate VP to return VCs
@@ -29,15 +35,16 @@ export async function issue({workflow, exchange} = {}) {
   if(verifiableCredential.length > 0) {
     verifiablePresentation.verifiableCredential = verifiableCredential;
   }
-  return {verifiablePresentation};
+  return {response: {verifiablePresentation}, format};
 }
 
-async function _issue({workflow, credentialRequests} = {}) {
+async function _issue({workflow, issueRequests, format} = {}) {
   // create zcap client for issuing VCs
   const {zcapClient, zcaps} = await getZcapClient({workflow});
 
-  // issue VCs in parallel
-  const capability = zcaps.issue;
+  // get the zcap to use for the issue requests
+  const capability = _getIssueZcap({workflow, zcaps, format});
+
   // specify URL to `/credentials/issue` to handle case that capability
   // is not specific to it
   let url = capability.invocationTarget;
@@ -45,15 +52,32 @@ async function _issue({workflow, credentialRequests} = {}) {
     url += capability.invocationTarget.endsWith('/credentials') ?
       '/issue' : '/credentials/issue';
   }
-  const results = await Promise.all(credentialRequests.map(request => {
-    // normalize credential templates that return full VC API issue credential
-    // requests and those that return only the `credential` param directly
-    const json = request.credential ? request : {credential: request};
-    return zcapClient.write({url, capability, json});
+
+  const issuedVCs = [];
+
+  // issue VCs in parallel
+  await Promise.all(issueRequests.map(async issueRequest => {
+    /* Note: Issue request formats can be any one of these:
+
+    1. `{credential, options?}`
+    2. `credential`
+
+    Normalize issue requests that use the full VC API issue request and those
+    that return only the `credential` param directly. */
+    const json = issueRequest.credential ?
+      issueRequest : {credential: issueRequest};
+    const {
+      data: {verifiableCredential}
+    } = await zcapClient.write({url, capability, json});
+    issuedVCs.push(verifiableCredential);
   }));
 
-  // parse VCs from results
-  const verifiableCredentials = results.map(
-    ({data: {verifiableCredential}}) => verifiableCredential);
-  return verifiableCredentials;
+  return issuedVCs;
+}
+
+function _getIssueZcap({workflow, zcaps, format}) {
+  const issuerInstances = getWorkflowIssuerInstances({workflow});
+  const {zcapReferenceIds: {issue: issueRefId}} = issuerInstances.find(
+    ({supportedFormats}) => supportedFormats.includes(format));
+  return zcaps[issueRefId];
 }

package/lib/openId.js

@@ -6,6 +6,7 @@ import * as exchanges from './exchanges.js';
 import {
   compile, schemas, createValidateMiddleware as validate
 } from '@bedrock/validation';
+import {evaluateTemplate, getWorkflowIssuerInstances} from './helpers.js';
 import {importJWK, SignJWT} from 'jose';
 import {
   openIdAuthorizationResponseBody,
@@ -19,7 +20,6 @@ import {asyncHandler} from '@bedrock/express';
 import bodyParser from 'body-parser';
 import {checkAccessToken} from '@bedrock/oauth2-verifier';
 import cors from 'cors';
-import {evaluateTemplate} from './helpers.js';
 import {issue} from './issue.js';
 import {klona} from 'klona';
 import {oid4vp} from '@digitalbazaar/oid4-client';
@@ -254,6 +254,7 @@ export async function createRoutes({
         }
       }
       */
+
       const result = await _processCredentialRequests(
         {req, res, isBatchRequest: false});
       if(!result) {
@@ -261,14 +262,27 @@ export async function createRoutes({
         return;
       }
 
-      // send VC
+      /* Note: The `/credential` route only supports sending a single VC;
+      assume here that this workflow is configured for a single VC and an
+      error code would have been sent to the client to use the batch
+      endpoint if there was more than one VC to deliver. */
+      const {response, format} = result;
+      const {verifiablePresentation: {verifiableCredential: [vc]}} = response;
+
+      // parse any enveloped VC
+      let credential;
+      if(vc.type === 'EnvelopedVerifiableCredential' &&
+        vc.id?.startsWith('data:application/jwt,')) {
+        credential = vc.id.slice('data:application/jwt,'.length);
+      } else {
+        credential = vc;
+      }
+
+      // send OID4VCI response
       res.json({
-        format: 'ldp_vc',
-        /* Note: The `/credential` route only supports sending a single VC;
-        assume here that this workflow is configured for a single VC and an
-        error code would have been sent to the client to use the batch
-        endpoint if there was more than one VC to deliver. */
-        credential: result.verifiablePresentation.verifiableCredential[0]
+        // FIXME: this doesn't seem to be in the spec anymore (draft 14+)...
+        format,
+        credential
       });
     }));
 
@@ -317,8 +331,19 @@ export async function createRoutes({
       }
 
       // send VCs
-      const responses = result.verifiablePresentation.verifiableCredential.map(
-        vc => ({format: 'ldp_vc', credential: vc}));
+      const {response: {verifiablePresentation}, format} = result;
+      // FIXME: "format" doesn't seem to be in the spec anymore (draft 14+)...
+      const responses = verifiablePresentation.verifiableCredential.map(vc => {
+        // parse any enveloped VC
+        let credential;
+        if(vc.type === 'EnvelopedVerifiableCredential' &&
+          vc.id?.startsWith('data:application/jwt,')) {
+          credential = vc.id.slice('data:application/jwt,'.length);
+        } else {
+          credential = vc;
+        }
+        return {format, credential};
+      });
       res.json({credential_responses: responses});
     }));
 
@@ -528,11 +553,12 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
   }
 
   // before asserting, normalize credential requests to use `type` instead of
-  // `types`; this is to allow for OID4VCI draft 20 implementers that followed
+  // `types`; this is to allow for OID4VCI draft implementers that followed
   // the non-normative examples
   _normalizeCredentialDefinitionTypes({credentialRequests});
-  _assertCredentialRequests(
-    {credentialRequests, expectedCredentialRequests});
+  const {format} = _assertCredentialRequests({
+    workflow, credentialRequests, expectedCredentialRequests
+  });
 
   // process exchange step if present
   const currentStep = exchange.step;
@@ -617,7 +643,7 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
   // replay attack detected) after exchange has been marked complete
 
   // issue VCs
-  return issue({workflow, exchange});
+  return issue({workflow, exchange, format});
 }
 
 async function _requestDidProof({res, exchangeRecord}) {
@@ -813,24 +839,66 @@ async function _getAuthorizationRequest({req}) {
 }
 
 function _assertCredentialRequests({
-  credentialRequests, expectedCredentialRequests
+  workflow, credentialRequests, expectedCredentialRequests
 }) {
+  // ensure that every credential request is for the same format
+  /* credential requests look like:
+  {
+    format: 'ldp_vc',
+    credential_definition: { '@context': [Array], type: [Array] }
+  }
+  */
+  let sharedFormat;
+  if(!credentialRequests.every(({format}) => {
+    if(sharedFormat === undefined) {
+      sharedFormat = format;
+    }
+    return sharedFormat === format;
+  })) {
+    throw new BedrockError(
+      'Credential requests must all use the same format in this workflow.', {
+        name: 'DataError',
+        details: {httpStatusCode: 400, public: true}
+      });
+  }
+
+  // get all supported formats from available issuer instances; for simple
+  // workflow configs, a single issuer instance is used with only
+  // ensure that every credential request uses a format supported by
+  // issuer instances
+  const supportedFormats = new Set();
+  const issuerInstances = getWorkflowIssuerInstances({workflow});
+  issuerInstances.forEach(
+    instance => instance.supportedFormats.forEach(
+      supportedFormats.add, supportedFormats));
+  if(!supportedFormats.has(sharedFormat)) {
+    throw new BedrockError(
+      `Credential request format "${sharedFormat}" is not supported ` +
+      'by this workflow.', {
+        name: 'DataError',
+        details: {httpStatusCode: 400, public: true}
+      });
+  }
+
   // ensure every credential request matches against an expected one and none
-  // are missing
+  // are missing; `expectedCredentialRequests` formats are ignored based on the
+  // issuer instance supported formats and have already been checked
   if(!(credentialRequests.length === expectedCredentialRequests.length &&
     credentialRequests.every(cr => expectedCredentialRequests.some(
-      ecr => _matchCredentialRequest(ecr, cr))))) {
-    // FIXME: improve error
-    throw new Error('unexpected credential request');
+      expected => _matchCredentialRequest(expected, cr))))) {
+    throw new BedrockError(
+      'Unexpected credential request.', {
+        name: 'DataError',
+        details: {httpStatusCode: 400, public: true}
+      });
   }
+
+  return {format: sharedFormat};
 }
 
-function _matchCredentialRequest(a, b) {
-  if(a.format !== b.format) {
-    return false;
-  }
-  const {credential_definition: {'@context': c1, type: t1}} = a;
-  const {credential_definition: {'@context': c2, type: t2}} = b;
+function _matchCredentialRequest(expected, cr) {
+  const {credential_definition: {'@context': c1, type: t1}} = expected;
+  const {credential_definition: {'@context': c2, type: t2}} = cr;
   // contexts must match exact order but types can have different order
   return (c1.length === c2.length && t1.length === t2.length &&
     c1.every((c, i) => c === c2[i]) && t1.every(t => t2.some(x => t === x)));

package/lib/vcapi.js

@@ -156,15 +156,15 @@ export async function processExchange({req, res, workflow, exchange}) {
   // FIXME: decide what the best recovery path is if delivery fails (but no
   // replay attack detected) after exchange has been marked complete
 
-  // issue any VCs; may return an empty result if the step defines no
+  // issue any VCs; may return an empty response if the step defines no
   // VCs to issue
-  const result = await issue({workflow, exchange});
+  const {response} = await issue({workflow, exchange});
 
   // if last `step` has a redirect URL, include it in the response
   if(step?.redirectUrl) {
-    result.redirectUrl = step.redirectUrl;
+    response.redirectUrl = step.redirectUrl;
   }
 
-  // send result
-  res.json(result);
+  // send response
+  res.json(response);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",

package/schemas/bedrock-vc-workflow.js

@@ -1,6 +1,7 @@
 /*!
  * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
  */
+import {MAX_ISSUER_INSTANCES} from '../lib/constants.js';
 import {schemas} from '@bedrock/validation';
 
 const credentialDefinition = {
@@ -34,6 +35,19 @@ const credentialDefinition = {
   }
 };
 
+const expectedCredentialRequest = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['credential_definition'],
+  properties: {
+    credential_definition: credentialDefinition,
+    format: {
+      type: 'string',
+      enum: ['ldp_vc', 'jwt_vc_json-ld']
+    }
+  }
+};
+
 const openIdExchangeOptions = {
   title: 'OpenID Exchange options',
   type: 'object',
@@ -44,18 +58,7 @@ const openIdExchangeOptions = {
       title: 'OpenID Expected Credential Requests',
       type: 'array',
       minItems: 1,
-      items: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['credential_definition', 'format'],
-        properties: {
-          credential_definition: credentialDefinition,
-          format: {
-            type: 'string',
-            enum: ['ldp_vc']
-          }
-        }
-      }
+      items: expectedCredentialRequest
     },
     preAuthorizedCode: {
       type: 'string'
@@ -123,6 +126,9 @@ const typedTemplate = {
   required: ['type', 'template'],
   additionalProperties: false,
   properties: {
+    id: {
+      type: 'string'
+    },
     type: {
       type: 'string',
       enum: ['jsonata']
@@ -140,6 +146,52 @@ export const credentialTemplates = {
   items: typedTemplate
 };
 
+// to be updated in specific locations with `properties` and `required`
+const zcapReferenceIds = {
+  title: 'Authorization Capability Reference IDs',
+  type: 'object',
+  additionalProperties: false
+};
+
+const vcFormats = {
+  title: 'Verifiable Credential formats',
+  type: 'array',
+  minItems: 1,
+  items: {
+    type: 'string'
+  }
+};
+
+const issuerInstance = {
+  title: 'Issuer Instance',
+  type: 'object',
+  required: ['zcapReferenceIds'],
+  additionalProperties: false,
+  properties: {
+    id: {
+      type: 'string'
+    },
+    supportedFormats: vcFormats,
+    zcapReferenceIds: {
+      ...zcapReferenceIds,
+      required: ['issue'],
+      properties: {
+        issue: {
+          type: 'string'
+        }
+      }
+    }
+  }
+};
+
+export const issuerInstances = {
+  title: 'Issuer Instances',
+  type: 'array',
+  minItems: 1,
+  maxItems: MAX_ISSUER_INSTANCES,
+  items: issuerInstance
+};
+
 const step = {
   title: 'Exchange Step',
   type: 'object',
@@ -276,7 +328,7 @@ const openIdCredentialRequest = {
     credential_definition: credentialDefinition,
     format: {
       type: 'string',
-      enum: ['ldp_vc']
+      enum: ['ldp_vc', 'jwt_vc_json-ld']
     },
     did: {
       type: 'string'