@bedrock/vc-delivery 4.3.0 → 4.4.0

package/lib/config.js

@@ -1,19 +1,31 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 
+const c = bedrock.util.config.main;
+const cc = c.computer();
 const {config} = bedrock;
 
-// use `vc-exchanger` namespace
-const namespace = 'vc-exchanger';
+// use `vc-workflow` namespace
+const namespace = 'vc-workflow';
 config[namespace] = {};
 
-// create dev application identity for vc-exchanger (must be overridden in
+// create dev application identity for vc-workflow (must be overridden in
 // deployments) ...and `ensureConfigOverride` has already been set via
 // `bedrock-app-identity` so it doesn't have to be set here
-config['app-identity'].seeds.services['vc-exchanger'] = {
+config['app-identity'].seeds.services['vc-workflow'] = {
   id: 'did:key:z6MknmKKxYiYo6txxX2bCgzeuBDkPPb5SJ36p232XkVEk7mf',
   seedMultibase: 'z1Abgbd91bbZHPYakVA7EPvhY9NZ2EaTkEpmwdBCfifokDn',
+  serviceType: 'vc-workflow'
+};
+
+// backwards compatibility: `vc-exchanger` alias:
+cc('vc-exchanger', () => config[namespace]);
+config['app-identity'].seeds.services['vc-exchanger'] = {
   serviceType: 'vc-exchanger'
 };
+cc('app-identity.seeds.services.vc-exchanger.id', () =>
+  config['app-identity'].seeds.services['vc-workflow'].id);
+cc('app-identity.seeds.services.vc-exchanger.seedMultibase', () =>
+  config['app-identity'].seeds.services['vc-workflow'].seedMultibase);

package/lib/exchanges.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import * as database from '@bedrock/mongodb';
@@ -32,7 +32,20 @@ bedrock.events.on('bedrock-mongodb.ready', async () => {
   await database.openCollections([COLLECTION_NAME]);
 
   await database.createIndexes([{
-    // cover exchange queries by exchanger ID + exchange ID
+    // cover exchange queries by local workflow ID + exchange ID
+    collection: COLLECTION_NAME,
+    fields: {localWorkflowId: 1, 'exchange.id': 1},
+    options: {
+      partialFilterExpression: {
+        localWorkflowId: {$exists: true}
+      },
+      unique: true, background: false
+    }
+  }, {
+    // backwards compatibility: cover exchange queries by
+    // local exchanger ID + exchange ID; local exchanger ID is the same as
+    // local workflow ID and this index can be eventually dropped once no
+    // deployments use `localExchangerId`
     collection: COLLECTION_NAME,
     fields: {localExchangerId: 1, 'exchange.id': 1},
     options: {unique: true, background: false}
@@ -55,14 +68,14 @@ bedrock.events.on('bedrock-mongodb.ready', async () => {
  * Inserts an exchange record.
  *
  * @param {object} options - The options to use.
- * @param {string} options.exchangerId - The ID of the exchanger that the
+ * @param {string} options.workflowId - The ID of the workflow that the
  *   exchange is associated with.
  * @param {object} options.exchange - The exchange to insert.
  *
  * @returns {Promise<object>} Resolves to the database record.
  */
-export async function insert({exchangerId, exchange}) {
-  assert.string(exchangerId, 'exchangerId');
+export async function insert({workflowId, exchange}) {
+  assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
   assert.string(exchange.id, 'exchange.id');
   // optional time to live in seconds
@@ -79,11 +92,13 @@ export async function insert({exchangerId, exchange}) {
     // TTL is in seconds
     meta.expires = new Date(now + exchange.ttl * 1000);
   }
-  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const {localId: localWorkflowId} = parseLocalId({id: workflowId});
   const record = {
-    localExchangerId,
+    localWorkflowId,
+    // backwards compatibility: enable existing systems to find record
+    localExchangerId: localWorkflowId,
     meta,
-    // possible states are: `pending`, `complete`, or `invalid`
+    // possible states are: `pending`, `active`, `complete`, or `invalid`
     exchange: {...exchange, sequence: 0, state: 'pending'}
   };
 
@@ -111,7 +126,7 @@ export async function insert({exchangerId, exchange}) {
  * Gets an exchange record.
  *
  * @param {object} options - The options to use.
- * @param {string} options.exchangerId - The ID of the exchanger that the
+ * @param {string} options.workflowId - The ID of the workflow that the
  *   exchange is associated with.
  * @param {string} options.id - The ID of the exchange to retrieve.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
@@ -119,18 +134,23 @@ export async function insert({exchangerId, exchange}) {
  * @returns {Promise<object | ExplainObject>} Resolves with the record that
  *   matches the query or an ExplainObject if `explain=true`.
  */
-export async function get({exchangerId, id, explain = false} = {}) {
-  assert.string(exchangerId, 'exchangerId');
+export async function get({workflowId, id, explain = false} = {}) {
+  assert.string(workflowId, 'workflowId');
   assert.string(id, 'id');
 
-  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
   const collection = database.collections[COLLECTION_NAME];
   const query = {
-    localExchangerId,
+    localWorkflowId,
     'exchange.id': id,
     // treat exchange as not found if invalid
     'exchange.state': {$ne: 'invalid'}
   };
+  // backwards compatibility: query on `localExchangerId`
+  if(base.endsWith('/exchangers')) {
+    query.localWorkflowId = {$in: [null, localWorkflowId]};
+    query.localExchangerId = localWorkflowId;
+  }
   const projection = {_id: 0, exchange: 1, meta: 1};
 
   if(explain) {
@@ -145,7 +165,9 @@ export async function get({exchangerId, id, explain = false} = {}) {
     throw new BedrockError('Exchange not found.', {
       name: 'NotFoundError',
       details: {
-        exchanger: exchangerId,
+        workflow: workflowId,
+        // backwards compatibility
+        exchanger: workflowId,
         exchange: id,
         httpStatusCode: 404,
         public: true
@@ -155,11 +177,18 @@ export async function get({exchangerId, id, explain = false} = {}) {
 
   // backwards compatibility; initialize `sequence`
   if(record.exchange.sequence === undefined) {
-    await collection.updateOne({
-      localExchangerId,
+    const query = {
+      localWorkflowId,
       'exchange.id': id,
       'exchange.sequence': null
-    }, {$set: {'exchange.sequence': 0}});
+    };
+    // backwards compatibility: query on `localExchangerId`
+    if(base.endsWith('/exchangers')) {
+      query.localWorkflowId = {$in: [null, localWorkflowId]};
+      query.localExchangerId = localWorkflowId;
+    }
+
+    await collection.updateOne(query, {$set: {'exchange.sequence': 0}});
     record.exchange.sequence = 0;
   }
 
@@ -167,10 +196,11 @@ export async function get({exchangerId, id, explain = false} = {}) {
 }
 
 /**
- * Updates a pending exchange with new variables, step, and TTL information.
+ * Updates a pending exchange with new state, variables, step, and TTL
+ * information.
  *
  * @param {object} options - The options to use.
- * @param {string} options.exchangerId - The ID of the exchanger the exchange
+ * @param {string} options.workflowId - The ID of the workflow the exchange
  *   is associated with.
  * @param {object} options.exchange - The exchange to update.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
@@ -178,8 +208,8 @@ export async function get({exchangerId, id, explain = false} = {}) {
  * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
  *   success or an ExplainObject if `explain=true`.
  */
-export async function update({exchangerId, exchange, explain = false} = {}) {
-  assert.string(exchangerId, 'exchangerId');
+export async function update({workflowId, exchange, explain = false} = {}) {
+  assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
   const {id} = exchange;
 
@@ -187,7 +217,7 @@ export async function update({exchangerId, exchange, explain = false} = {}) {
   const now = Date.now();
   const update = {
     $inc: {'exchange.sequence': 1},
-    $set: {'meta.updated': now}
+    $set: {'exchange.state': exchange.state, 'meta.updated': now}
   };
   // update exchange `variables`, `step`, and `ttl`
   if(exchange.variables) {
@@ -200,17 +230,22 @@ export async function update({exchangerId, exchange, explain = false} = {}) {
     update.$set['exchange.ttl'] = exchange.ttl;
   }
 
-  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
 
   const collection = database.collections[COLLECTION_NAME];
   const query = {
-    localExchangerId,
+    localWorkflowId,
     'exchange.id': id,
     // exchange sequence must match previous sequence
     'exchange.sequence': exchange.sequence - 1,
-    // previous state must be `pending` in order to update it
-    'exchange.state': 'pending'
+    // previous state must be `pending` or `active` in order to update it
+    'exchange.state': {$in: ['pending', 'active']}
   };
+  // backwards compatibility: query on `localExchangerId`
+  if(base.endsWith('/exchangers')) {
+    query.localWorkflowId = {$in: [null, localWorkflowId]};
+    query.localExchangerId = localWorkflowId;
+  }
 
   if(explain) {
     // 'find().limit(1)' is used here because 'updateOne()' doesn't return a
@@ -238,7 +273,7 @@ export async function update({exchangerId, exchange, explain = false} = {}) {
 
   // if no document was matched, try to get an existing exchange; if the
   // exchange does not exist, a not found error will be automatically thrown
-  await get({exchangerId, id});
+  await get({workflowId, id});
 
   /* Note: Here the exchange *does* exist, but the step or state did not
   match which is a conflict error. */
@@ -258,7 +293,7 @@ export async function update({exchangerId, exchange, explain = false} = {}) {
  * Marks an exchange as complete.
  *
  * @param {object} options - The options to use.
- * @param {string} options.exchangerId - The ID of the exchanger the exchange
+ * @param {string} options.workflowId - The ID of the workflow the exchange
  *   is associated with.
  * @param {object} options.exchange - The exchange to mark as complete.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
@@ -266,8 +301,8 @@ export async function update({exchangerId, exchange, explain = false} = {}) {
  * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
  *   success or an ExplainObject if `explain=true`.
  */
-export async function complete({exchangerId, exchange, explain = false} = {}) {
-  assert.string(exchangerId, 'exchangerId');
+export async function complete({workflowId, exchange, explain = false} = {}) {
+  assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
   const {id} = exchange;
 
@@ -291,17 +326,23 @@ export async function complete({exchangerId, exchange, explain = false} = {}) {
     update.$set['exchange.ttl'] = exchange.ttl;
   }
 
-  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
 
   const collection = database.collections[COLLECTION_NAME];
   const query = {
-    localExchangerId,
+    localWorkflowId,
     'exchange.id': id,
     // exchange sequence must match previous sequence
     'exchange.sequence': exchange.sequence - 1,
-    // previous state must be `pending` in order to change to `complete`
-    'exchange.state': 'pending'
+    // previous state must be `pending` or `active` in order to change to
+    // `complete`
+    'exchange.state': {$in: ['pending', 'active']}
   };
+  // backwards compatibility: query on `localExchangerId`
+  if(base.endsWith('/exchangers')) {
+    query.localWorkflowId = {$in: [null, localWorkflowId]};
+    query.localExchangerId = localWorkflowId;
+  }
 
   if(explain) {
     // 'find().limit(1)' is used here because 'updateOne()' doesn't return a
@@ -329,13 +370,14 @@ export async function complete({exchangerId, exchange, explain = false} = {}) {
 
   // if no document was matched, try to get an existing exchange; if the
   // exchange does not exist, a not found error will be automatically thrown
-  const record = await get({exchangerId, id});
+  const record = await get({workflowId, id});
 
   /* Note: Here the exchange *does* exist, but couldn't be updated because
   another process changed it. That change either left it in a still pending
   state or it was already completed. If it was already completed, it is an
   error condition that must result in invalidating the exchange. */
-  if(record.state === 'pending') {
+  if(record.exchange.state === 'pending' ||
+    record.exchange.state === 'active') {
     // exchange still pending, another process updated it
     throw new BedrockError('Could not update exchange; conflict error.', {
       name: 'InvalidStateError',
@@ -350,7 +392,7 @@ export async function complete({exchangerId, exchange, explain = false} = {}) {
   // state is either `complete` or `invalid`, so throw duplicate completed
   // exchange error and invalidate exchange if needed, but do not throw any
   // error to client; only log it
-  if(record.state !== 'invalid') {
+  if(record.exchange.state !== 'invalid') {
     _invalidateExchange({record}).catch(
       error => logger.error(`Could not invalidate exchange "${id}".`, {error}));
   }
@@ -387,9 +429,13 @@ async function _markExchangeInvalid({record}) {
   // mark exchange invalid
   try {
     const query = {
-      localExchangerId: record.localExchangerId,
+      localWorkflowId: record.localWorkflowId,
       'exchange.id': record.exchange.id
     };
+    // backwards compatibility: query on `localExchangerId`
+    if(!record.localWorkflowId) {
+      query.localExchangerId = record.localExchangerId;
+    }
     const update = {
       $set: {
         'exchange.state': 'invalid',

package/lib/helpers.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import {decodeId, generateId} from 'bnid';
@@ -12,7 +12,7 @@ import {ZcapClient} from '@digitalbazaar/ezcap';
 const {config} = bedrock;
 
 export async function evaluateTemplate({
-  exchanger, exchange, typedTemplate
+  workflow, exchange, typedTemplate
 } = {}) {
   // run jsonata compiler; only `jsonata` template type is supported and this
   // assumes only this template type will be passed in
@@ -20,8 +20,12 @@ export async function evaluateTemplate({
   const {variables = {}} = exchange;
   // always include `globals` as keyword for self-referencing exchange info
   variables.globals = {
+    workflow: {
+      id: workflow.id
+    },
+    // backwards compatibility
     exchanger: {
-      id: exchanger.id
+      id: workflow.id
     },
     exchange: {
       id: exchange.id
@@ -30,7 +34,7 @@ export async function evaluateTemplate({
   return jsonata(template).evaluate(variables, variables);
 }
 
-export function getExchangerId({routePrefix, localId} = {}) {
+export function getWorkflowId({routePrefix, localId} = {}) {
   return `${config.server.baseUri}${routePrefix}/${localId}`;
 }
 
@@ -44,12 +48,15 @@ export async function generateRandom() {
   });
 }
 
-export async function getZcapClient({exchanger} = {}) {
+export async function getZcapClient({workflow} = {}) {
   // get service agent for communicating with the issuer instance
-  const {serviceAgent} = await serviceAgents.get(
-    {serviceType: 'vc-exchanger'});
+  const {pathname} = new URL(workflow.id);
+  // backwards-compatibility: support deprecated `vc-exchanger`
+  const serviceType = pathname.startsWith('/workflows/') ?
+    'vc-workflow' : 'vc-exchanger';
+  const {serviceAgent} = await serviceAgents.get({serviceType});
   const {capabilityAgent, zcaps} = await serviceAgents.getEphemeralAgent(
-    {config: exchanger, serviceAgent});
+    {config: workflow, serviceAgent});
 
   // create zcap client for issuing VCs
   const zcapClient = new ZcapClient({

package/lib/http.js

@@ -1,22 +1,20 @@
 /*!
- * Copyright (c) 2018-2023 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2018-2024 Digital Bazaar, Inc. All rights reserved.
  */
 import * as _openId from './openId.js';
 import * as bedrock from '@bedrock/core';
 import * as exchanges from './exchanges.js';
-import {createChallenge as _createChallenge, verify} from './verify.js';
 import {
   createExchangeBody, useExchangeBody
-} from '../schemas/bedrock-vc-exchanger.js';
-import {evaluateTemplate, generateRandom, getExchangerId} from './helpers.js';
+} from '../schemas/bedrock-vc-workflow.js';
 import {exportJWK, generateKeyPair, importJWK} from 'jose';
+import {generateRandom, getWorkflowId} from './helpers.js';
 import {metering, middleware} from '@bedrock/service-core';
 import {asyncHandler} from '@bedrock/express';
 import bodyParser from 'body-parser';
 import cors from 'cors';
-import {issue} from './issue.js';
-import {klona} from 'klona';
 import {logger} from './logger.js';
+import {processExchange} from './vcapi.js';
 import {createValidateMiddleware as validate} from '@bedrock/validation';
 
 const {util: {BedrockError}} = bedrock;
@@ -31,8 +29,6 @@ bedrock.events.on('bedrock-express.configure.bodyParser', app => {
   }));
 });
 
-const MAXIMUM_STEPS = 100;
-
 export async function addRoutes({app, service} = {}) {
   const {routePrefix} = service;
 
@@ -42,15 +38,15 @@ export async function addRoutes({app, service} = {}) {
     exchange: `${baseUrl}/exchanges/:exchangeId`
   };
 
-  // used to retrieve service object (exchanger) config
+  // used to retrieve service object (workflow) config
   const getConfigMiddleware = middleware.createGetConfigMiddleware({service});
 
   // used to fetch exchange record in parallel
   const getExchange = asyncHandler(async (req, res, next) => {
     const {localId, exchangeId: id} = req.params;
-    const exchangerId = getExchangerId({routePrefix, localId});
+    const workflowId = getWorkflowId({routePrefix, localId});
     // expose access to result via `req`; do not wait for it to settle here
-    const exchangePromise = exchanges.get({exchangerId, id}).catch(e => e);
+    const exchangePromise = exchanges.get({workflowId, id}).catch(e => e);
     req.getExchange = async () => {
       const record = await exchangePromise;
       if(record instanceof Error) {
@@ -121,7 +117,7 @@ export async function addRoutes({app, service} = {}) {
         }
 
         // insert exchange
-        const {id: exchangerId} = config;
+        const {id: workflowId} = config;
         const exchange = {
           id: await generateRandom(),
           ttl,
@@ -129,8 +125,8 @@ export async function addRoutes({app, service} = {}) {
           openId,
           step
         };
-        await exchanges.insert({exchangerId, exchange});
-        const location = `${exchangerId}/exchanges/${exchange.id}`;
+        await exchanges.insert({workflowId, exchange});
+        const location = `${workflowId}/exchanges/${exchange.id}`;
         res.status(204).location(location).send();
       } catch(error) {
         logger.error(error.message, {error});
@@ -164,147 +160,9 @@ export async function addRoutes({app, service} = {}) {
     getExchange,
     getConfigMiddleware,
     asyncHandler(async (req, res) => {
-      const {config: exchanger} = req.serviceObject;
+      const {config: workflow} = req.serviceObject;
       const {exchange} = await req.getExchange();
-
-      // get any `verifiablePresentation` from the body...
-      let receivedPresentation = req?.body?.verifiablePresentation;
-
-      // process exchange step(s)
-      let i = 0;
-      let currentStep = exchange.step;
-      let step;
-      while(true) {
-        if(i++ > MAXIMUM_STEPS) {
-          throw new BedrockError('Maximum steps exceeded.', {
-            name: 'DataError',
-            details: {httpStatusCode: 500, public: true}
-          });
-        }
-
-        // no step present, break out to complete exchange
-        if(!currentStep) {
-          break;
-        }
-
-        // get current step details
-        step = exchanger.steps[currentStep];
-        if(step.stepTemplate) {
-          // generate step from the template; assume the template type is
-          // `jsonata` per the JSON schema
-          step = await evaluateTemplate(
-            {exchanger, exchange, typedTemplate: step.stepTemplate});
-          if(Object.keys(step).length === 0) {
-            throw new BedrockError('Empty step detected.', {
-              name: 'DataError',
-              details: {httpStatusCode: 500, public: true}
-            });
-          }
-        }
-
-        // if next step is the same as the current step, throw an error
-        if(step.nextStep === currentStep) {
-          throw new BedrockError('Cyclical step detected.', {
-            name: 'DataError',
-            details: {httpStatusCode: 500, public: true}
-          });
-        }
-
-        // handle VPR: if step requires it, then `verifiablePresentation` must
-        // be in the request
-        if(step.verifiablePresentationRequest) {
-          const {createChallenge} = step;
-          const isInitialStep = exchange.step === exchanger.initialStep;
-
-          // if no presentation was received in the body...
-          if(!receivedPresentation) {
-            const verifiablePresentationRequest = klona(
-              step.verifiablePresentationRequest);
-            if(createChallenge) {
-              /* Note: When creating a challenge, the initial step always
-              uses the local exchange ID because the initial step itself
-              is one-time use. Subsequent steps, which only VC-API (as opposed
-              to other protocols) supports creating additional challenges via
-              the VC-API verifier API. */
-              let challenge;
-              if(isInitialStep) {
-                challenge = exchange.id;
-              } else {
-                // generate a new challenge using verifier API
-                ({challenge} = await _createChallenge({exchanger}));
-              }
-              verifiablePresentationRequest.challenge = challenge;
-            }
-            // send VPR and return
-            res.json({verifiablePresentationRequest});
-            return;
-          }
-
-          // verify the received VP
-          const expectedChallenge = isInitialStep ? exchange.id : undefined;
-          const {verificationMethod} = await verify({
-            exchanger,
-            verifiablePresentationRequest: step.verifiablePresentationRequest,
-            presentation: receivedPresentation, expectedChallenge
-          });
-
-          // store VP results in variables associated with current step
-          if(!exchange.variables.results) {
-            exchange.variables.results = {};
-          }
-          exchange.variables.results[currentStep] = {
-            // common use case of DID Authentication; provide `did` for ease
-            // of use in templates and consistency with OID4VCI which only
-            // receives `did` not verification method nor VP
-            did: verificationMethod.controller,
-            verificationMethod,
-            verifiablePresentation: receivedPresentation
-          };
-
-          // clear received presentation as it has been processed
-          receivedPresentation = null;
-
-          // if there is no next step, break out to complete exchange
-          if(!step.nextStep) {
-            break;
-          }
-
-          // update the exchange to go to the next step, then loop to send
-          // next VPR
-          currentStep = exchange.step = step.nextStep;
-          exchange.sequence++;
-          await exchanges.update({exchangerId: exchanger.id, exchange});
-
-          // FIXME: there may be VCs to issue during this step, do so before
-          // sending the VPR above
-        } else if(step.nextStep) {
-          // next steps without VPRs are prohibited
-          throw new BedrockError(
-            'Invalid step detected; continuing exchanges must include VPRs.', {
-              name: 'DataError',
-              details: {httpStatusCode: 500, public: true}
-            });
-        }
-      }
-
-      // mark exchange complete
-      exchange.sequence++;
-      await exchanges.complete({exchangerId: exchanger.id, 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
-      // VCs to issue
-      const result = await issue({exchanger, exchange});
-
-      // if last `step` has a redirect URL, include it in the response
-      if(step?.redirectUrl) {
-        result.redirectUrl = step.redirectUrl;
-      }
-
-      // send result
-      res.json(result);
+      await processExchange({req, res, workflow, exchange});
     }));
 
   // create OID4VCI routes to be used with each individual exchange