@bedrock/vc-delivery 5.1.0 → 5.3.0

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/http.js

@@ -54,6 +54,7 @@ export async function createRoutes({
     ciMetadata2: `${exchangeRoute}/.well-known/openid-credential-issuer`,
     batchCredential: `${openIdRoute}/batch_credential`,
     credential: `${openIdRoute}/credential`,
+    credentialOffer: `${openIdRoute}/credential-offer`,
     token: `${openIdRoute}/token`,
     jwks: `${openIdRoute}/jwks`,
     // OID4VP routes
@@ -217,6 +218,18 @@ export async function createRoutes({
       });
     }));
 
+  // a credential delivery server endpoint
+  // serves the credential offer for all possible credentials in the exchange
+  app.get(
+    routes.credentialOffer,
+    cors(),
+    getConfigMiddleware,
+    getExchange,
+    asyncHandler(async (req, res) => {
+      const offer = await oid4vci.getCredentialOffer({req});
+      res.json(offer);
+    }));
+
   // a batch credential delivery server endpoint
   // receives N credential requests and returns N VCs
   app.options(routes.batchCredential, cors());