Ensure exchanges are updated w/step results.

Author: dlongley

CHANGELOG.md

@@ -4,7 +4,11 @@
 
 ### Added
 - Add GET endpoint for getting exchange information from any existing
-  exchange, particularly useful for obtaining its current state.
+  exchange, particularly useful for obtaining its current state and
+  any user-submitted data.
+
+### Fixed
+- Ensure exchanges are updated when steps are completed.
 
 ## 3.0.2 - 2023-06-26
 

README.md

@@ -1 +1 @@
-# bedrock-module-template-http
+# bedrock-vc-delivery

lib/exchanges.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as bedrock from '@bedrock/core';
 import * as database from '@bedrock/mongodb';
@@ -156,21 +156,123 @@ export async function get({exchangerId, id, explain = false} = {}) {
   return record;
 }
 
+/**
+ * Updates a pending exchange with new variables, step, and TTL information.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.exchangerId - The ID of the exchanger the exchange
+ *   is associated with.
+ * @param {object} options.exchange - The exchange to update.
+ * @param {string} [options.expectedStep] - The expected current step in the
+ *   exchange.
+ * @param {boolean} [options.explain=false] - An optional explain boolean.
+ *
+ * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
+ *   success or an ExplainObject if `explain=true`.
+ */
+export async function update({
+  exchangerId, exchange, expectedStep, explain = false
+} = {}) {
+  assert.string(exchangerId, 'exchangerId');
+  assert.object(exchange, 'exchange');
+  assert.optionalString(expectedStep, expectedStep);
+  const {id} = exchange;
+
+  // build update
+  const now = Date.now();
+  const update = {
+    $set: {'meta.updated': now}
+  };
+  // update exchange `variables.results[step]`, `step`, and `ttl`
+  if(exchange.variables?.results) {
+    update.$set['exchange.variables.results'] = exchange.variables.results;
+  }
+  if(exchange.step !== undefined) {
+    update.$set['exchange.step'] = exchange.step;
+  }
+  if(exchange.ttl !== undefined) {
+    update.$set['exchange.ttl'] = exchange.ttl;
+  }
+
+  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+
+  const collection = database.collections[COLLECTION_NAME];
+  const query = {
+    localExchangerId,
+    'exchange.id': id,
+    // previous state must be `pending` in order to update it
+    'exchange.state': 'pending'
+  };
+  // current step must match previous step
+  if(expectedStep === undefined) {
+    query['exchange.step'] = null;
+  } else {
+    query['exchange.step'] = expectedStep;
+  }
+
+  if(explain) {
+    // 'find().limit(1)' is used here because 'updateOne()' doesn't return a
+    // cursor which allows the use of the explain function.
+    const cursor = await collection.find(query).limit(1);
+    return cursor.explain('executionStats');
+  }
+
+  try {
+    const result = await collection.updateOne(query, update);
+    if(result.result.n > 0) {
+      // document modified: success
+      return true;
+    }
+  } catch(e) {
+    throw new BedrockError('Could not update exchange.', {
+      name: 'OperationError',
+      details: {
+        public: true,
+        httpStatusCode: 500
+      },
+      cause: e
+    });
+  }
+
+  // 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});
+
+  /* Note: Here the exchange *does* exist, but the step or state did not
+  match which is a conflict error. */
+
+  // throw duplicate completed exchange error
+  throw new BedrockError('Could not update exchange; conflict error.', {
+    name: 'InvalidStateError',
+    details: {
+      public: true,
+      // this is a client-side conflict error
+      httpStatusCode: 409
+    }
+  });
+}
+
 /**
  * Marks an exchange as complete.
  *
  * @param {object} options - The options to use.
  * @param {string} options.exchangerId - The ID of the exchanger the exchange
  *   is associated with.
- * @param {object} options.id - The ID of the exchange to mark as complete.
+ * @param {object} options.exchange - The exchange to mark as complete.
+ * @param {string} [options.expectedStep] - The expected current step in the
+ *   exchange.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
  *
  * @returns {Promise<boolean | ExplainObject>} Resolves with `true` on update
  *   success or an ExplainObject if `explain=true`.
  */
-export async function complete({exchangerId, id, explain = false} = {}) {
+export async function complete({
+  exchangerId, exchange, expectedStep, explain = false
+} = {}) {
   assert.string(exchangerId, 'exchangerId');
-  assert.string(id, 'id');
+  assert.object(exchange, 'exchange');
+  assert.optionalString(expectedStep, expectedStep);
+  const {id} = exchange;
 
   // build update
   const now = Date.now();
@@ -180,6 +282,16 @@ export async function complete({exchangerId, id, explain = false} = {}) {
       'meta.updated': now
     }
   };
+  // update exchange `variables.results[step]`, `step`, and `ttl`
+  if(exchange.variables?.results) {
+    update.$set['exchange.variables.results'] = exchange.variables.results;
+  }
+  if(exchange.step !== undefined) {
+    update.$set['exchange.step'] = exchange.step;
+  }
+  if(exchange.ttl !== undefined) {
+    update.$set['exchange.ttl'] = exchange.ttl;
+  }
 
   const {localId: localExchangerId} = parseLocalId({id: exchangerId});
 
@@ -190,6 +302,12 @@ export async function complete({exchangerId, id, explain = false} = {}) {
     // previous state must be `pending` in order to change to `complete`
     'exchange.state': 'pending'
   };
+  // current step must match previous step
+  if(expectedStep === undefined) {
+    query['exchange.step'] = null;
+  } else {
+    query['exchange.step'] = expectedStep;
+  }
 
   if(explain) {
     // 'find().limit(1)' is used here because 'updateOne()' doesn't return a

lib/http.js

@@ -159,19 +159,28 @@ export async function addRoutes({app, service} = {}) {
       const {config: exchanger} = req.serviceObject;
       const {exchange} = await req.exchange;
 
-      // process exchange step if present
-      if(exchange.step) {
-        const step = exchanger.steps[exchange.step];
+      // get any `verifiablePresentation` from the body...
+      let receivedPresentation = req?.body?.verifiablePresentation;
 
-        // handle VPR; if step requires it, then `verifiablePresentation` must
+      // process exchange step(s)
+      let currentStep = exchange.step;
+      while(true) {
+        // no step present, break out to complete exchange
+        if(!currentStep) {
+          break;
+        }
+
+        // get current step details
+        const step = exchanger.steps[currentStep];
+
+        // 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 `verifiablePresentation` is not in the body...
-          const presentation = req?.body?.verifiablePresentation;
-          if(!presentation) {
+          // if no presentation was received in the body...
+          if(!receivedPresentation) {
             const verifiablePresentationRequest = klona(
               step.verifiablePresentationRequest);
             if(createChallenge) {
@@ -189,38 +198,54 @@ export async function addRoutes({app, service} = {}) {
               }
               verifiablePresentationRequest.challenge = challenge;
             }
-            // send VPR
+            // send VPR and return
             res.json({verifiablePresentationRequest});
             return;
           }
 
-          // verify the VP
+          // verify the received VP
           const expectedChallenge = isInitialStep ? exchange.id : undefined;
-          const {verificationMethod} = await verify(
-            {exchanger, presentation, expectedChallenge});
+          const {verificationMethod} = await verify({
+            exchanger, presentation: receivedPresentation, expectedChallenge
+          });
 
-          // FIXME: ensure VP satisfies step VPR; implement templates (jsonata)
-          // to convert VPR responses to more exchange variables
+          // FIXME: ensure VP satisfies step VPR
 
-          // store VP in variables
-          exchange.variables[exchange.step] = {
+          // 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,
-            verifiablePresentation: presentation
+            verificationMethod,
+            verifiablePresentation: receivedPresentation
           };
 
-          // FIXME: update the exchange to go to the next step if there is one
-          // if(step.nextStep) {
-          //   exchange.step = step.nextStep;
-          //   // FIXME: break exchange step processor into its own local API;
-          //   // ensure VPR has been met, store VP in variables, and
-          //   // loop to send next VPR
-          //   return;
-          // }
+          // 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
+          exchange.step = step.nextStep;
+          await exchanges.update({
+            exchangerId: exchanger.id, exchange, expectedStep: currentStep
+          });
+          currentStep = exchange.step;
         }
       }
 
       // mark exchange complete
-      await exchanges.complete({exchangerId: exchanger.id, id: exchange.id});
+      await exchanges.complete({
+        exchangerId: exchanger.id, exchange, expectedStep: currentStep
+      });
 
       // FIXME: decide what the best recovery path is if delivery fails (but no
       // replay attack detected) after exchange has been marked complete

lib/index.js

@@ -100,8 +100,8 @@ async function validateConfigFn({config} = {}) {
     }
 
     // if `steps` are specified, then `initialStep` MUST be included
-    const {steps = [], initialStep} = config;
-    if(steps.length > 0 && initialStep === undefined) {
+    const {steps, initialStep} = config;
+    if(steps && initialStep === undefined) {
       throw new BedrockError(
         '"initialStep" is required when "steps" are provided.', {
           name: 'DataError',

lib/openId.js

@@ -394,7 +394,8 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
     {credentialRequests, expectedCredentialRequests});
 
   // process exchange step if present
-  if(exchange.step) {
+  const currentStep = exchange.step;
+  if(currentStep) {
     const step = exchanger.steps[exchange.step];
 
     // handle JWT DID Proof request; if step requires it, then `proof` must
@@ -418,13 +419,22 @@ async function _processCredentialRequests({req, res, isBatchRequest}) {
         // FIXME: improve error
         throw new Error('every DID must be the same');
       }
-      // add `did` to exchange variables
-      exchange.variables[exchange.step] = {did};
+      // store did 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
+        did
+      };
     }
   }
 
   // mark exchange complete
-  await exchanges.complete({exchangerId: exchanger.id, id: exchange.id});
+  await exchanges.complete({
+    exchangerId: exchanger.id, exchange, expectedStep: currentStep
+  });
 
   // FIXME: decide what the best recovery path is if delivery fails (but no
   // replay attack detected) after exchange has been marked complete

schemas/bedrock-vc-exchanger.js

@@ -172,13 +172,12 @@ const step = {
         }
       }
     },
+    nextStep: {
+      type: 'string'
+    }
     // FIXME: add jsonata template to convert VPR or
     // `jwtDidProofRequest` to more variables to be
     // used when issuing VCs
-    // FIXME: `nextStep` feature not yet implemented
-    // nextStep: {
-    //   type: 'string'
-    // }
   }
 };
 

test/mocha/20-vcapi.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as helpers from './helpers.js';
 import {agent} from '@bedrock/https-agent';

test/mocha/21-vcapi-did-authn.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2023 Digital Bazaar, Inc. All rights reserved.
  */
 import * as helpers from './helpers.js';
 import {agent} from '@bedrock/https-agent';

test/mocha/mock.data.js

@@ -112,7 +112,7 @@ mockData.didAuthnCredentialTemplate = `
     ],
     "issuanceDate": issuanceDate,
     "credentialSubject": {
-      "id": didAuthn.did,
+      "id": results.didAuthn.did,
       "degree": {
         "type": "BachelorDegree",
         "name": "Bachelor of Science and Arts"