@bedrock/vc-delivery 5.2.0 → 5.3.1

package/lib/exchanges.js

@@ -3,18 +3,16 @@
  */
 import * as bedrock from '@bedrock/core';
 import * as database from '@bedrock/mongodb';
+import {parseLocalId, stripStacktrace} from './helpers.js';
 import assert from 'assert-plus';
 import {logger} from './logger.js';
-import {parseLocalId} from './helpers.js';
+import {serializeError} from 'serialize-error';
 
 const {util: {BedrockError}} = bedrock;
 
-/* Note: Exchanges either have TTLs and can be "completed" or they persist
-and never "complete" nor expire.
-
-Exchanges are always in one of three states: `pending`, `complete`, or
-`invalid`. They can only transistion from `pending` to `complete` or from
-`complete` to `invalid`.
+/* Note: Exchanges have default TTLs of 15 minutes and are always in one of
+four states: `pending`, `active`, `complete`, or `invalid`. They can only
+transition from `pending` to `complete` or from `complete` to `invalid`.
 
 If an exchange is marked as complete, any attempt to mark it complete again
 will result in an action, as specified in the exchange record, being taken
@@ -28,6 +26,15 @@ provided during the exchange a capability to verify them must be provided. */
 
 const COLLECTION_NAME = 'vc-exchange';
 
+// allow updates to the last error every 500ms
+const LAST_ERROR_UPDATE_CONSTRAINTS = {
+  // if the exchange has been updated 5 or more times, apply the time limit
+  sequenceThreshold: 5,
+  // 1 second must expire before updating last error once sequence threshold
+  // has been hit
+  updateTimeLimit: 1000
+};
+
 bedrock.events.on('bedrock-mongodb.ready', async () => {
   await database.openCollections([COLLECTION_NAME]);
 
@@ -88,9 +95,14 @@ export async function insert({workflowId, exchange}) {
   // build exchange record
   const now = Date.now();
   const meta = {created: now, updated: now};
+  // possible states are: `pending`, `active`, `complete`, or `invalid`
+  exchange = {...exchange, sequence: 0, state: 'pending'};
   if(exchange.ttl !== undefined) {
-    // TTL is in seconds
-    meta.expires = new Date(now + exchange.ttl * 1000);
+    // TTL is in seconds, convert to `expires`
+    const expires = new Date(now + exchange.ttl * 1000);
+    meta.expires = expires;
+    exchange.expires = expires.toISOString().replace(/\.\d+Z$/, 'Z');
+    delete exchange.ttl;
   }
   const {localId: localWorkflowId} = parseLocalId({id: workflowId});
   const record = {
@@ -98,8 +110,7 @@ export async function insert({workflowId, exchange}) {
     // backwards compatibility: enable existing systems to find record
     localExchangerId: localWorkflowId,
     meta,
-    // possible states are: `pending`, `active`, `complete`, or `invalid`
-    exchange: {...exchange, sequence: 0, state: 'pending'}
+    exchange
   };
 
   // insert the exchange and get the updated record
@@ -129,12 +140,16 @@ export async function insert({workflowId, exchange}) {
  * @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.allowExpired=false] - Controls whether an expired
+ *   exchange that is still in the database can be retrieved or not.
  * @param {boolean} [options.explain=false] - An optional explain boolean.
  *
  * @returns {Promise<object | ExplainObject>} Resolves with the record that
  *   matches the query or an ExplainObject if `explain=true`.
  */
-export async function get({workflowId, id, explain = false} = {}) {
+export async function get({
+  workflowId, id, allowExpired = false, explain = false
+} = {}) {
   assert.string(workflowId, 'workflowId');
   assert.string(id, 'id');
 
@@ -160,7 +175,16 @@ export async function get({workflowId, id, explain = false} = {}) {
     return cursor.explain('executionStats');
   }
 
-  const record = await collection.findOne(query, {projection});
+  let record = await collection.findOne(query, {projection});
+  if(record?.exchange.expires && !allowExpired) {
+    // ensure `expires` is enforced programmatically even if background job
+    // has not yet removed the record
+    const now = new Date();
+    const expires = new Date(record.exchange.expires);
+    if(now >= expires) {
+      record = null;
+    }
+  }
   if(!record) {
     throw new BedrockError('Exchange not found.', {
       name: 'NotFoundError',
@@ -196,8 +220,8 @@ export async function get({workflowId, id, explain = false} = {}) {
 }
 
 /**
- * Updates a pending exchange with new state, variables, step, and TTL
- * information.
+ * Updates a pending or active exchange with new state, variables, step, and
+ * TTL, and error information.
  *
  * @param {object} options - The options to use.
  * @param {string} options.workflowId - The ID of the workflow the exchange
@@ -214,21 +238,7 @@ export async function update({workflowId, exchange, explain = false} = {}) {
   const {id} = exchange;
 
   // build update
-  const now = Date.now();
-  const update = {
-    $inc: {'exchange.sequence': 1},
-    $set: {'exchange.state': exchange.state, 'meta.updated': now}
-  };
-  // update exchange `variables`, `step`, and `ttl`
-  if(exchange.variables) {
-    update.$set['exchange.variables'] = exchange.variables;
-  }
-  if(exchange.step !== undefined) {
-    update.$set['exchange.step'] = exchange.step;
-  }
-  if(exchange.ttl !== undefined) {
-    update.$set['exchange.ttl'] = exchange.ttl;
-  }
+  const update = _buildUpdate({exchange, complete: false});
 
   const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
 
@@ -304,27 +314,13 @@ export async function update({workflowId, exchange, explain = false} = {}) {
 export async function complete({workflowId, exchange, explain = false} = {}) {
   assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
+  if(exchange.state !== 'complete') {
+    throw new Error('"exchange.state" must be set to "complete".');
+  }
   const {id} = exchange;
 
   // build update
-  const now = Date.now();
-  const update = {
-    $inc: {'exchange.sequence': 1},
-    $set: {
-      'exchange.state': 'complete',
-      '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 update = _buildUpdate({exchange, complete: true});
 
   const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
 
@@ -408,6 +404,105 @@ export async function complete({workflowId, exchange, explain = false} = {}) {
   });
 }
 
+/**
+ * Sets the last error associated with an exchange, provided that the exchange
+ * has not been recently or frequently updated.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.workflowId - The ID of the workflow the exchange
+ *   is associated with.
+ * @param {object} options.exchange - The exchange to update with `lastError`
+ *   set.
+ * @param {object} options.lastUpdated - The last update time (in milliseconds).
+ * @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 setLastError({
+  workflowId, exchange, lastUpdated, explain = false
+} = {}) {
+  assert.string(workflowId, 'workflowId');
+  assert.object(exchange, 'exchange');
+  assert.object(exchange.lastError, 'exchange.lastError');
+  assert.number(lastUpdated, 'lastUpdate');
+
+  // prevent too many updates to an exchange to write the last error to it
+  // by limiting to a few
+  const now = Date.now();
+  if(exchange.sequence > LAST_ERROR_UPDATE_CONSTRAINTS.sequenceThreshold &&
+    now < (lastUpdated + LAST_ERROR_UPDATE_CONSTRAINTS.updateTimeLimit)) {
+    // deny update, too many last error updates
+    return false;
+  }
+
+  // build update
+  const update = {
+    $inc: {'exchange.sequence': 1},
+    $set: {
+      'meta.updated': now,
+      'exchange.lastError': serializeError(stripStacktrace(exchange.lastError))
+    }
+  };
+
+  const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
+
+  const {id} = exchange;
+  const collection = database.collections[COLLECTION_NAME];
+  const query = {
+    localWorkflowId,
+    'exchange.id': id,
+    // exchange sequence must match previous sequence
+    'exchange.sequence': exchange.sequence - 1
+  };
+  // 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
+    // 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({workflowId, 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
+    }
+  });
+}
+
 async function _invalidateExchange({record}) {
   try {
     // mark exchange invalid, but do not throw any error to client; only log it
@@ -463,6 +558,48 @@ async function _markExchangeInvalid({record}) {
   }
 }
 
+function _buildUpdate({exchange, complete}) {
+  // build update
+  const now = Date.now();
+  const update = {
+    $inc: {'exchange.sequence': 1},
+    $set: {'exchange.state': exchange.state, 'meta.updated': now},
+    $unset: {}
+  };
+  if(complete) {
+    // exchange complete, only update results
+    if(exchange.variables?.results) {
+      update.$set['exchange.variables.results'] = exchange.variables.results;
+    }
+  } else {
+    // exchange not complete, update all variables
+    if(exchange.variables) {
+      update.$set['exchange.variables'] = exchange.variables;
+    }
+  }
+  if(exchange.step !== undefined) {
+    update.$set['exchange.step'] = exchange.step;
+  }
+  // only set `ttl` if expires not previously set / has been cleared
+  if(exchange.ttl !== undefined && exchange.expires === undefined) {
+    // TTL is in seconds, convert to expires
+    const expires = new Date(now + exchange.ttl * 1000);
+    // unset and previously set `ttl`
+    update.$unset['exchange.ttl'] = true;
+    update.$set['meta.expires'] = expires;
+    update.$set['exchange.expires'] =
+      expires.toISOString().replace(/\.\d+Z$/, 'Z');
+  }
+  if(exchange.lastError !== undefined) {
+    update.$set['exchange.lastError'] =
+      serializeError(stripStacktrace(exchange.lastError));
+  } else {
+    update.$unset['exchange.lastError'] = true;
+  }
+
+  return update;
+}
+
 /**
  * An object containing information on the query plan.
  *

package/lib/helpers.js

@@ -7,6 +7,7 @@ import {decodeId, generateId} from 'bnid';
 import {Ed25519Signature2020} from '@digitalbazaar/ed25519-signature-2020';
 import {httpsAgent} from '@bedrock/https-agent';
 import jsonata from 'jsonata';
+import {serializeError} from 'serialize-error';
 import {serviceAgents} from '@bedrock/service-agent';
 import {ZcapClient} from '@digitalbazaar/ezcap';
 
@@ -104,6 +105,21 @@ export function decodeLocalId({localId} = {}) {
   }));
 }
 
+export function stripStacktrace(error) {
+  error = serializeError(error);
+  delete error.stack;
+  if(error.errors) {
+    error.errors = error.errors.map(stripStacktrace);
+  }
+  if(Array.isArray(error.details?.errors)) {
+    error.details.errors = error.details.errors.map(stripStacktrace);
+  }
+  if(error.cause) {
+    error.cause = stripStacktrace(error.cause);
+  }
+  return error;
+}
+
 export async function unenvelopeCredential({
   envelopedCredential, format
 } = {}) {

package/lib/http.js

@@ -113,8 +113,8 @@ export async function addRoutes({app, service} = {}) {
     getConfigMiddleware,
     asyncHandler(async (req, res) => {
       const {config: workflow} = req.serviceObject;
-      const {exchange} = await req.getExchange();
-      await processExchange({req, res, workflow, exchange});
+      const exchangeRecord = await req.getExchange();
+      await processExchange({req, res, workflow, exchangeRecord});
     }));
 
   // create OID4* routes to be used with each individual exchange

package/lib/oid4/oid4vci.js

@@ -10,6 +10,7 @@ import {importJWK, SignJWT} from 'jose';
 import {checkAccessToken} from '@bedrock/oauth2-verifier';
 import {getAuthorizationRequest} from './oid4vp.js';
 import {issue} from '../issue.js';
+import {logger} from '../logger.js';
 import {timingSafeEqual} from 'node:crypto';
 import {verifyDidProofJwt} from '../verify.js';
 
@@ -145,118 +146,7 @@ export async function processCredentialRequests({req, res, isBatchRequest}) {
   // ensure oauth2 access token is valid
   await _checkAuthz({req, workflow, exchange});
 
-  // validate body against expected credential requests
-  const {openId: {expectedCredentialRequests}} = exchange;
-  let credentialRequests;
-  if(isBatchRequest) {
-    ({credential_requests: credentialRequests} = req.body);
-  } else {
-    if(expectedCredentialRequests.length > 1) {
-      // FIXME: it is no longer the case that the batch endpoint must be used
-      // for multiple requests; determine if the request has changed
-
-      // clients interacting with exchanges with more than one VC to be
-      // delivered must use the "batch credential" endpoint
-      // FIXME: improve error
-      throw new Error('batch_credential_endpoint must be used');
-    }
-    credentialRequests = [req.body];
-  }
-
-  // before asserting, normalize credential requests to use `type` instead of
-  // `types`; this is to allow for OID4VCI draft implementers that followed
-  // the non-normative examples
-  _normalizeCredentialDefinitionTypes({credentialRequests});
-  const {format} = _assertCredentialRequests({
-    workflow, credentialRequests, expectedCredentialRequests
-  });
-
-  // process exchange step if present
-  const currentStep = exchange.step;
-  if(currentStep) {
-    let step = workflow.steps[exchange.step];
-    if(step.stepTemplate) {
-      // generate step from the template; assume the template type is
-      // `jsonata` per the JSON schema
-      step = await evaluateTemplate(
-        {workflow, exchange, typedTemplate: step.stepTemplate});
-      if(Object.keys(step).length === 0) {
-        throw new BedrockError('Could not create exchange step.', {
-          name: 'DataError',
-          details: {httpStatusCode: 500, public: true}
-        });
-      }
-    }
-
-    // do late workflow configuration validation
-    const {jwtDidProofRequest, openId} = step;
-    // use of `jwtDidProofRequest` and `openId` together is prohibited
-    if(jwtDidProofRequest && openId) {
-      throw new BedrockError(
-        'Invalid workflow configuration; only one of ' +
-        '"jwtDidProofRequest" and "openId" is permitted in a step.', {
-          name: 'DataError',
-          details: {httpStatusCode: 500, public: true}
-        });
-    }
-
-    // check to see if step supports OID4VP during OID4VCI
-    if(step.openId) {
-      // if there is no `presentationSubmission`, request one
-      const {results} = exchange.variables;
-      if(!results?.[exchange.step]?.openId?.presentationSubmission) {
-        // FIXME: optimize away double step-template processing that currently
-        // occurs when calling `_getAuthorizationRequest`
-        const {
-          authorizationRequest
-        } = await getAuthorizationRequest({req});
-        return _requestOID4VP({authorizationRequest, res});
-      }
-      // otherwise drop down below to complete exchange...
-    } else if(jwtDidProofRequest) {
-      // handle OID4VCI specialized JWT DID Proof request...
-
-      // `proof` must be in every credential request; if any request is missing
-      // `proof` then request a DID proof
-      if(credentialRequests.some(cr => !cr.proof?.jwt)) {
-        return _requestDidProof({res, exchangeRecord});
-      }
-
-      // verify every DID proof and get resulting DIDs
-      const results = await Promise.all(
-        credentialRequests.map(async cr => {
-          const {proof: {jwt}} = cr;
-          const {did} = await verifyDidProofJwt({workflow, exchange, jwt});
-          return did;
-        }));
-      // require `did` to be the same for every proof
-      // FIXME: determine if this needs to be more flexible
-      const did = results[0];
-      if(results.some(d => did !== d)) {
-        // FIXME: improve error
-        throw new Error('every DID must be the same');
-      }
-      // 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
-  exchange.sequence++;
-  await exchanges.complete({workflowId: workflow.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 VCs
-  return issue({workflow, exchange, format});
+  return _processExchange({req, res, workflow, exchangeRecord, isBatchRequest});
 }
 
 function _assertCredentialRequests({
@@ -499,6 +389,147 @@ function _normalizeCredentialDefinitionTypes({credentialRequests}) {
   }
 }
 
+async function _processExchange({
+  req, res, workflow, exchangeRecord, isBatchRequest
+}) {
+  const {id: workflowId} = workflow;
+  const {exchange, meta} = exchangeRecord;
+  let {updated: lastUpdated} = meta;
+  try {
+    // validate body against expected credential requests
+    const {openId: {expectedCredentialRequests}} = exchange;
+    let credentialRequests;
+    if(isBatchRequest) {
+      ({credential_requests: credentialRequests} = req.body);
+    } else {
+      if(expectedCredentialRequests.length > 1) {
+        // FIXME: it is no longer the case that the batch endpoint must be used
+        // for multiple requests; determine if the request has changed
+
+        // clients interacting with exchanges with more than one VC to be
+        // delivered must use the "batch credential" endpoint
+        // FIXME: improve error
+        throw new Error('batch_credential_endpoint must be used');
+      }
+      credentialRequests = [req.body];
+    }
+
+    // before asserting, normalize credential requests to use `type` instead of
+    // `types`; this is to allow for OID4VCI draft implementers that followed
+    // the non-normative examples
+    _normalizeCredentialDefinitionTypes({credentialRequests});
+    const {format} = _assertCredentialRequests({
+      workflow, credentialRequests, expectedCredentialRequests
+    });
+
+    // process exchange step if present
+    const currentStep = exchange.step;
+    if(currentStep) {
+      let step = workflow.steps[exchange.step];
+      if(step.stepTemplate) {
+        // generate step from the template; assume the template type is
+        // `jsonata` per the JSON schema
+        step = await evaluateTemplate(
+          {workflow, exchange, typedTemplate: step.stepTemplate});
+        if(Object.keys(step).length === 0) {
+          throw new BedrockError('Could not create exchange step.', {
+            name: 'DataError',
+            details: {httpStatusCode: 500, public: true}
+          });
+        }
+      }
+
+      // do late workflow configuration validation
+      const {jwtDidProofRequest, openId} = step;
+      // use of `jwtDidProofRequest` and `openId` together is prohibited
+      if(jwtDidProofRequest && openId) {
+        throw new BedrockError(
+          'Invalid workflow configuration; only one of ' +
+          '"jwtDidProofRequest" and "openId" is permitted in a step.', {
+            name: 'DataError',
+            details: {httpStatusCode: 500, public: true}
+          });
+      }
+
+      // check to see if step supports OID4VP during OID4VCI
+      if(step.openId) {
+        // if there is no `presentationSubmission`, request one
+        const {results} = exchange.variables;
+        if(!results?.[exchange.step]?.openId?.presentationSubmission) {
+          // FIXME: optimize away double step-template processing that
+          // currently occurs when calling `_getAuthorizationRequest`
+          const {
+            authorizationRequest
+          } = await getAuthorizationRequest({req});
+          return _requestOID4VP({authorizationRequest, res});
+        }
+        // otherwise drop down below to complete exchange...
+      } else if(jwtDidProofRequest) {
+        // handle OID4VCI specialized JWT DID Proof request...
+
+        // `proof` must be in every credential request; if any request is
+        // missing `proof` then request a DID proof
+        if(credentialRequests.some(cr => !cr.proof?.jwt)) {
+          return _requestDidProof({res, exchangeRecord});
+        }
+
+        // verify every DID proof and get resulting DIDs
+        const results = await Promise.all(
+          credentialRequests.map(async cr => {
+            const {proof: {jwt}} = cr;
+            const {did} = await verifyDidProofJwt({workflow, exchange, jwt});
+            return did;
+          }));
+        // require `did` to be the same for every proof
+        // FIXME: determine if this needs to be more flexible
+        const did = results[0];
+        if(results.some(d => did !== d)) {
+          // FIXME: improve error
+          throw new Error('every DID must be the same');
+        }
+        // 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
+    exchange.state = 'complete';
+    try {
+      exchange.sequence++;
+      await exchanges.complete({workflowId, exchange});
+      lastUpdated = Date.now();
+    } catch(e) {
+      exchange.sequence--;
+      throw e;
+    }
+
+    // FIXME: decide what the best recovery path is if delivery fails (but no
+    // replay attack detected) after exchange has been marked complete
+
+    // issue VCs
+    return issue({workflow, exchange, format});
+  } catch(e) {
+    if(e.name === 'InvalidStateError') {
+      throw e;
+    }
+    // write last error if exchange hasn't been frequently updated
+    const copy = {...exchange};
+    copy.sequence++;
+    copy.lastError = e;
+    exchanges.setLastError({workflowId, exchange: copy, lastUpdated})
+      .catch(error => logger.error(
+        'Could not set last exchange error: ' + error.message, {error}));
+    throw e;
+  }
+}
+
 async function _requestDidProof({res, exchangeRecord}) {
   /* `9.4 Credential Issuer-provided nonce` allows the credential
   issuer infrastructure to provide the nonce via an error:

package/lib/oid4/oid4vp.js

@@ -10,6 +10,7 @@ import {
 } from '../../schemas/bedrock-vc-workflow.js';
 import {compile} from '@bedrock/validation';
 import {klona} from 'klona';
+import {logger} from '../logger.js';
 import {oid4vp} from '@digitalbazaar/oid4-client';
 import {verify} from '../verify.js';
 
@@ -139,10 +140,11 @@ export async function getAuthorizationRequest({req}) {
     }
 
     if(updateExchange) {
-      exchange.sequence++;
       try {
+        exchange.sequence++;
         await exchanges.update({workflowId: workflow.id, exchange});
       } catch(e) {
+        exchange.sequence--;
         if(e.name !== 'InvalidStateError') {
           // unrecoverable error
           throw e;
@@ -167,89 +169,111 @@ export async function processAuthorizationResponse({req}) {
   const {config: workflow} = req.serviceObject;
   const exchangeRecord = await req.getExchange();
   let {exchange} = exchangeRecord;
-
-  // get authorization request and updated exchange associated with exchange
-  const arRequest = await getAuthorizationRequest({req});
-  const {authorizationRequest, step} = arRequest;
-  ({exchange} = arRequest);
-
-  // FIXME: check the VP against the presentation submission if requested
-  // FIXME: check the VP against "trustedIssuer" in VPR, if provided
-  const {presentationSchema} = step;
-  if(presentationSchema) {
-    // if the VP is enveloped, validate the contents of the envelope
-    const toValidate = envelope ? envelope.contents : presentation;
-
-    // validate the received VP / envelope contents
-    const {jsonSchema: schema} = presentationSchema;
-    const validate = compile({schema});
-    const {valid, error} = validate(toValidate);
-    if(!valid) {
-      throw error;
+  let {meta: {updated: lastUpdated}} = exchangeRecord;
+  try {
+    // get authorization request and updated exchange associated with exchange
+    const arRequest = await getAuthorizationRequest({req});
+    const {authorizationRequest, step} = arRequest;
+    ({exchange} = arRequest);
+
+    // FIXME: check the VP against the presentation submission if requested
+    // FIXME: check the VP against "trustedIssuer" in VPR, if provided
+    const {presentationSchema} = step;
+    if(presentationSchema) {
+      // if the VP is enveloped, validate the contents of the envelope
+      const toValidate = envelope ? envelope.contents : presentation;
+
+      // validate the received VP / envelope contents
+      const {jsonSchema: schema} = presentationSchema;
+      const validate = compile({schema});
+      const {valid, error} = validate(toValidate);
+      if(!valid) {
+        throw error;
+      }
     }
-  }
 
-  // verify the received VP
-  const {verifiablePresentationRequest} = await oid4vp.toVpr(
-    {authorizationRequest});
-  const {allowUnprotectedPresentation = false} = step;
-  const verifyResult = await verify({
-    workflow,
-    verifiablePresentationRequest,
-    presentation,
-    allowUnprotectedPresentation,
-    expectedChallenge: authorizationRequest.nonce
-  });
-  const {verificationMethod} = verifyResult;
+    // verify the received VP
+    const {verifiablePresentationRequest} = await oid4vp.toVpr(
+      {authorizationRequest});
+    const {allowUnprotectedPresentation = false} = step;
+    const verifyResult = await verify({
+      workflow,
+      verifiablePresentationRequest,
+      presentation,
+      allowUnprotectedPresentation,
+      expectedChallenge: authorizationRequest.nonce
+    });
+    const {verificationMethod} = verifyResult;
 
-  // store VP results in variables associated with current step
-  const currentStep = exchange.step;
-  if(!exchange.variables.results) {
-    exchange.variables.results = {};
-  }
-  const results = {
-    // common use case of DID Authentication; provide `did` for ease
-    // of use in template
-    did: verificationMethod?.controller || null,
-    verificationMethod,
-    verifiablePresentation: presentation,
-    openId: {
-      authorizationRequest,
-      presentationSubmission
+    // store VP results in variables associated with current step
+    const currentStep = exchange.step;
+    if(!exchange.variables.results) {
+      exchange.variables.results = {};
+    }
+    const results = {
+      // common use case of DID Authentication; provide `did` for ease
+      // of use in template
+      did: verificationMethod?.controller || null,
+      verificationMethod,
+      verifiablePresentation: presentation,
+      openId: {
+        authorizationRequest,
+        presentationSubmission
+      }
+    };
+    if(envelope) {
+      // normalize VP from inside envelope to `verifiablePresentation`
+      results.envelopedPresentation = presentation;
+      results.verifiablePresentation = verifyResult
+        .presentationResult.presentation;
+    }
+    exchange.variables.results[currentStep] = results;
+    try {
+      exchange.sequence++;
+
+      // if there is something to issue, update exchange, do not complete it
+      const {credentialTemplates = []} = workflow;
+      if(credentialTemplates?.length > 0 &&
+        (exchange.state === 'pending' || exchange.state === 'active')) {
+        // ensure exchange state is set to `active` (will be rejected as a
+        // conflict if the state in database at update time isn't `pending` or
+        // `active`)
+        exchange.state = 'active';
+        await exchanges.update({workflowId: workflow.id, exchange});
+      } else {
+        // mark exchange complete
+        exchange.state = 'complete';
+        await exchanges.complete({workflowId: workflow.id, exchange});
+      }
+      lastUpdated = Date.now();
+    } catch(e) {
+      exchange.sequence--;
+      throw e;
     }
-  };
-  if(envelope) {
-    // normalize VP from inside envelope to `verifiablePresentation`
-    results.envelopedPresentation = presentation;
-    results.verifiablePresentation = verifyResult
-      .presentationResult.presentation;
-  }
-  exchange.variables.results[currentStep] = results;
-  exchange.sequence++;
-
-  // if there is something to issue, update exchange, do not complete it
-  const {credentialTemplates = []} = workflow;
-  if(credentialTemplates?.length > 0 &&
-    (exchange.state === 'pending' || exchange.state === 'active')) {
-    // ensure exchange state is set to `active` (will be rejected as a
-    // conflict if the state in database at update time isn't `pending` or
-    // `active`)
-    exchange.state = 'active';
-    await exchanges.update({workflowId: workflow.id, exchange});
-  } else {
-    // mark exchange complete
-    await exchanges.complete({workflowId: workflow.id, exchange});
-  }
 
-  const result = {};
+    const result = {};
 
-  // include `redirect_uri` if specified in step
-  const redirect_uri = step.openId?.redirect_uri;
-  if(redirect_uri) {
-    result.redirect_uri = redirect_uri;
-  }
+    // include `redirect_uri` if specified in step
+    const redirect_uri = step.openId?.redirect_uri;
+    if(redirect_uri) {
+      result.redirect_uri = redirect_uri;
+    }
 
-  return result;
+    return result;
+  } catch(e) {
+    if(e.name === 'InvalidStateError') {
+      throw e;
+    }
+    // write last error if exchange hasn't been frequently updated
+    const {id: workflowId} = workflow;
+    const copy = {...exchange};
+    copy.sequence++;
+    copy.lastError = e;
+    exchanges.setLastError({workflowId, exchange: copy, lastUpdated})
+      .catch(error => logger.error(
+        'Could not set last exchange error: ' + error.message, {error}));
+    throw e;
+  }
 }
 
 function _createClientMetaData() {

package/lib/vcapi.js

@@ -90,179 +90,209 @@ export async function createExchange({workflow, exchange}) {
   return exchange;
 }
 
-export async function processExchange({req, res, workflow, exchange}) {
-  // get any `verifiablePresentation` from the body...
-  let receivedPresentation = req?.body?.verifiablePresentation;
+export async function processExchange({req, res, workflow, exchangeRecord}) {
+  const {exchange, meta} = exchangeRecord;
+  let {updated: lastUpdated} = meta;
+  try {
+    // 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}
-      });
-    }
+    // 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;
-    }
+      // no step present, break out to complete exchange
+      if(!currentStep) {
+        break;
+      }
+
+      // get current step details
+      step = workflow.steps[currentStep];
+      if(step.stepTemplate) {
+        // generate step from the template; assume the template type is
+        // `jsonata` per the JSON schema
+        step = await evaluateTemplate(
+          {workflow, exchange, typedTemplate: step.stepTemplate});
+        if(Object.keys(step).length === 0) {
+          throw new BedrockError('Empty step detected.', {
+            name: 'DataError',
+            details: {httpStatusCode: 500, public: true}
+          });
+        }
+      }
 
-    // get current step details
-    step = workflow.steps[currentStep];
-    if(step.stepTemplate) {
-      // generate step from the template; assume the template type is
-      // `jsonata` per the JSON schema
-      step = await evaluateTemplate(
-        {workflow, exchange, typedTemplate: step.stepTemplate});
-      if(Object.keys(step).length === 0) {
-        throw new BedrockError('Empty step detected.', {
+      // 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}
         });
       }
-    }
 
-    // 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 === workflow.initialStep;
 
-    // handle VPR: if step requires it, then `verifiablePresentation` must
-    // be in the request
-    if(step.verifiablePresentationRequest) {
-      const {createChallenge} = step;
-      const isInitialStep = exchange.step === workflow.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({workflow}));
+            }
+            verifiablePresentationRequest.challenge = challenge;
+          }
+          // send VPR and return
+          res.json({verifiablePresentationRequest});
+          // if exchange is pending, mark it as active out-of-band
+          if(exchange.state === 'pending') {
+            exchange.state = 'active';
+            exchange.sequence++;
+            exchanges.update({workflowId: workflow.id, exchange}).catch(
+              error => logger.error(
+                'Could not mark exchange active: ' + error.message, {error}));
+          }
+          return;
+        }
 
-      // 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;
+        const {presentationSchema} = step;
+        if(presentationSchema) {
+          // if the VP is enveloped, get the presentation from the envelope
+          let presentation;
+          if(receivedPresentation?.type === 'EnvelopedVerifiablePresentation') {
+            ({presentation} = await unenvelopePresentation({
+              envelopedPresentation: receivedPresentation
+            }));
           } else {
-            // generate a new challenge using verifier API
-            ({challenge} = await _createChallenge({workflow}));
+            presentation = receivedPresentation;
           }
-          verifiablePresentationRequest.challenge = challenge;
-        }
-        // send VPR and return
-        res.json({verifiablePresentationRequest});
-        // if exchange is pending, mark it as active out-of-band
-        if(exchange.state === 'pending') {
-          exchange.state = 'active';
-          exchange.sequence++;
-          exchanges.update({workflowId: workflow.id, exchange}).catch(
-            error => logger.error(
-              'Could not mark exchange active: ' + error.message, {error}));
-        }
-        return;
-      }
 
-      const {presentationSchema} = step;
-      if(presentationSchema) {
-        // if the VP is enveloped, get the presentation from the envelope
-        let presentation;
-        if(receivedPresentation?.type === 'EnvelopedVerifiablePresentation') {
-          ({presentation} = await unenvelopePresentation({
-            envelopedPresentation: receivedPresentation
-          }));
-        } else {
-          presentation = receivedPresentation;
+          // validate the received VP
+          const {jsonSchema: schema} = presentationSchema;
+          const validate = compile({schema});
+          const {valid, error} = validate(presentation);
+          if(!valid) {
+            throw error;
+          }
         }
 
-        // validate the received VP
-        const {jsonSchema: schema} = presentationSchema;
-        const validate = compile({schema});
-        const {valid, error} = validate(presentation);
-        if(!valid) {
-          throw error;
+        // verify the received VP
+        const expectedChallenge = isInitialStep ? exchange.id : undefined;
+        const {allowUnprotectedPresentation = false} = step;
+        const {verificationMethod} = await verify({
+          workflow,
+          verifiablePresentationRequest: step.verifiablePresentationRequest,
+          presentation: receivedPresentation,
+          allowUnprotectedPresentation,
+          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 || null,
+          verificationMethod,
+          verifiablePresentation: receivedPresentation
+        };
 
-      // verify the received VP
-      const expectedChallenge = isInitialStep ? exchange.id : undefined;
-      const {allowUnprotectedPresentation = false} = step;
-      const {verificationMethod} = await verify({
-        workflow,
-        verifiablePresentationRequest: step.verifiablePresentationRequest,
-        presentation: receivedPresentation,
-        allowUnprotectedPresentation,
-        expectedChallenge
-      });
+        // clear received presentation as it has been processed
+        receivedPresentation = null;
 
-      // 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 || null,
-        verificationMethod,
-        verifiablePresentation: receivedPresentation
-      };
+        // if there is no next step, break out to complete exchange
+        if(!step.nextStep) {
+          break;
+        }
 
-      // clear received presentation as it has been processed
-      receivedPresentation = null;
+        // update the exchange to go to the next step, then loop to send
+        // next VPR
+        currentStep = exchange.step = step.nextStep;
+        // ensure exchange state is active
+        if(exchange.state === 'pending') {
+          exchange.state = 'active';
+        }
+        try {
+          exchange.sequence++;
+          await exchanges.update({workflowId: workflow.id, exchange});
+          lastUpdated = Date.now();
+        } catch(e) {
+          exchange.sequence--;
+          throw e;
+        }
 
-      // if there is no next step, break out to complete exchange
-      if(!step.nextStep) {
-        break;
+        // 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}
+          });
       }
+    }
 
-      // update the exchange to go to the next step, then loop to send
-      // next VPR
-      currentStep = exchange.step = step.nextStep;
-      // ensure exchange state is active
-      if(exchange.state === 'pending') {
-        exchange.state = 'active';
-      }
+    // mark exchange complete
+    exchange.state = 'complete';
+    try {
       exchange.sequence++;
-      await exchanges.update({workflowId: workflow.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}
-        });
+      await exchanges.complete({workflowId: workflow.id, exchange});
+    } catch(e) {
+      exchange.sequence--;
+      throw e;
     }
-  }
+    lastUpdated = Date.now();
 
-  // mark exchange complete
-  exchange.sequence++;
-  await exchanges.complete({workflowId: workflow.id, exchange});
+    // FIXME: decide what the best recovery path is if delivery fails (but no
+    // replay attack detected) after exchange has been marked complete
 
-  // 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 response if the step defines no
+    // VCs to issue
+    const {response} = await issue({workflow, exchange});
 
-  // issue any VCs; may return an empty response if the step defines no
-  // VCs to issue
-  const {response} = await issue({workflow, exchange});
+    // if last `step` has a redirect URL, include it in the response
+    if(step?.redirectUrl) {
+      response.redirectUrl = step.redirectUrl;
+    }
 
-  // if last `step` has a redirect URL, include it in the response
-  if(step?.redirectUrl) {
-    response.redirectUrl = step.redirectUrl;
+    // send response
+    res.json(response);
+  } catch(e) {
+    if(e.name === 'InvalidStateError') {
+      throw e;
+    }
+    // write last error if exchange hasn't been frequently updated
+    const {id: workflowId} = workflow;
+    const copy = {...exchange};
+    copy.sequence++;
+    copy.lastError = e;
+    exchanges.setLastError({workflowId, exchange: copy, lastUpdated})
+      .catch(error => logger.error(
+        'Could not set last exchange error: ' + error.message, {error}));
+    throw e;
   }
-
-  // send response
-  res.json(response);
 }

package/lib/verify.js

@@ -4,9 +4,9 @@
 import * as bedrock from '@bedrock/core';
 import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
 import * as Ed25519Multikey from '@digitalbazaar/ed25519-multikey';
+import {getZcapClient, stripStacktrace} from './helpers.js';
 import {importJWK, jwtVerify} from 'jose';
 import {didIo} from '@bedrock/did-io';
-import {getZcapClient} from './helpers.js';
 
 const {util: {BedrockError}} = bedrock;
 
@@ -77,17 +77,17 @@ export async function verify({
     if(credentialResults) {
       credentialResults.forEach(result => {
         if(result.error) {
-          result.error = _stripStacktrace(result.error);
+          result.error = stripStacktrace(result.error);
         }
       });
     }
     if(presentationResult.error) {
-      presentationResult.error = _stripStacktrace(presentationResult.error);
+      presentationResult.error = stripStacktrace(presentationResult.error);
     }
 
     // generate useful error to return to client
     const {name, errors, message} = cause.data.error;
-    const causeError = _stripStacktrace({...cause.data.error});
+    const causeError = stripStacktrace({...cause.data.error});
     delete causeError.errors;
     const error = new BedrockError(message ?? 'Verification error.', {
       name: (name === 'VerificationError' || name === 'DataError') ?
@@ -102,7 +102,7 @@ export async function verify({
       }
     });
     if(Array.isArray(errors)) {
-      error.details.errors = errors.map(_stripStacktrace);
+      error.details.errors = errors.map(stripStacktrace);
     }
     throw error;
   }
@@ -159,6 +159,18 @@ export async function verifyDidProofJwt({workflow, exchange, jwt} = {}) {
     }
 
     const vm = await didIo.get({url: kid});
+    if(!vm) {
+      throw new BedrockError(
+        `Verification method identified by "kid" (${kid}) could not be ` +
+        'retrieved.', {
+          name: 'DataError',
+          details: {
+            public: true,
+            httpStatusCode: 400
+          }
+        });
+    }
+
     // `vm.controller` must be the issuer of the DID JWT; also ensure that
     // the specified controller authorized `vm` for the purpose of
     // authentication
@@ -174,8 +186,13 @@ export async function verifyDidProofJwt({workflow, exchange, jwt} = {}) {
       match.controller === vm.controller)) {
       throw new BedrockError(
         `Verification method controller "${issuer}" did not authorize ` +
-        `verification method "${vm.id}" for the purpose of "authentication".`,
-        {name: 'NotAllowedError'});
+        `verification method "${vm.id}" for the purpose of "authentication".`, {
+          name: 'NotAllowedError',
+          details: {
+            public: true,
+            httpStatusCode: 400
+          }
+        });
     }
     let jwk;
     if(isEcdsa) {
@@ -251,15 +268,3 @@ export async function verifyDidProofJwt({workflow, exchange, jwt} = {}) {
 
   return {verified: true, did: issuer, verifyResult};
 }
-
-function _stripStacktrace(error) {
-  error = {...error};
-  delete error.stack;
-  if(error.errors) {
-    error.errors = error.errors.map(_stripStacktrace);
-  }
-  if(error.cause) {
-    error.cause = _stripStacktrace(error.cause);
-  }
-  return error;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",
@@ -47,7 +47,8 @@
     "cors": "^2.8.5",
     "jose": "^5.6.3",
     "jsonata": "^2.0.5",
-    "klona": "^2.0.6"
+    "klona": "^2.0.6",
+    "serialize-error": "^11.0.3"
   },
   "peerDependencies": {
     "@bedrock/app-identity": "4.0.0",