@bedrock/vc-delivery 7.15.0 → 7.16.0

package/lib/ExchangeProcessor.js

@@ -168,7 +168,7 @@ export class ExchangeProcessor {
       if(exchange.state === 'complete') {
         await exchanges.complete({workflowId: workflow.id, exchange});
       } else {
-        await exchanges.update({workflowId: workflow.id, exchange});
+        await exchanges.update({workflowId: workflow.id, exchange, meta});
       }
       meta.updated = Date.now();
       await emitExchangeUpdated({workflow, exchange, step});

package/lib/config.js

@@ -1,7 +1,8 @@
 /*!
- * Copyright (c) 2022-2024 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2026 Digital Bazaar, Inc.
  */
 import * as bedrock from '@bedrock/core';
+import '@bedrock/express';
 
 const c = bedrock.util.config.main;
 const cc = c.computer();
@@ -11,6 +12,15 @@ const {config} = bedrock;
 const namespace = 'vc-workflow';
 config[namespace] = {};
 
+config[namespace].exchanges = {
+  variablesGarbageCollector: {
+    // collect expired externalized exchange "variables" every 5 minutes; may
+    // be slightly randomized
+    // default: 5 minutes
+    interval: 5 * 60 * 1000
+  }
+};
+
 // 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
@@ -29,3 +39,26 @@ 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);
+
+// set body parser limits for workflow endpoints (and deprecated `/exchangers`)
+const routePrefixes = ['/workflows', '/exchangers'];
+const createBodyParserOptions = ({limit}) => ({
+  json: {
+    strict: false,
+    limit,
+    type: ['json', '+json']
+  }
+});
+const bodyParserRoutes = config.express.bodyParser.routes;
+for(const routePrefix of routePrefixes) {
+  // exchange clients POST to this route to execute exchanges; limit indicates
+  // how large submitted VPs can be
+  bodyParserRoutes[
+    `${routePrefix}/:localWorkflowId/exchanges/:localExchangeId`
+  ] = createBodyParserOptions({limit: '10MB'});
+  // exchanges are created using this route; limit indicates how large
+  // variables can be (in total)
+  bodyParserRoutes[
+    `${routePrefix}/:localWorkflowId/exchanges`
+  ] = createBodyParserOptions({limit: '10MB'});
+}

package/lib/constants.js

@@ -1,6 +1,15 @@
 /*!
- * Copyright (c) 2024-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2024-2026 Digital Bazaar, Inc.
  */
+// allow up to 3 days to resolve invalid exchange issues (which also more than
+// covers large exchange `variables` download and decoding times, etc.)
+// (86400 seconds in 24 hours)
+export const EXCHANGE_EXPIRY_GRACE_PERIOD = 86400 * 3 * 1000;
+// TTL is measured in minutes, default is 15 minutes
+export const EXCHANGE_TTL_DEFAULT = 60 * 15;
+// 48 hours
+export const EXCHANGE_TTL_MAX_IN_MS = 1000 * 60 * 60 * 24 * 2;
+
 // maximum # of issuer instances that can be associated with a workflow
 export const MAX_ISSUER_INSTANCES = 10;
 // maximum # of OID4VP client profiles that can be associated with a workflow

package/lib/http.js

@@ -1,5 +1,5 @@
 /*!
- * Copyright (c) 2018-2026 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2018-2026 Digital Bazaar, Inc.
  */
 import * as bedrock from '@bedrock/core';
 import * as exchanges from './storage/exchanges.js';
@@ -11,7 +11,6 @@ import {
 } from '../schemas/bedrock-vc-workflow.js';
 import {metering, middleware} from '@bedrock/service-core';
 import {asyncHandler} from '@bedrock/express';
-import bodyParser from 'body-parser';
 import cors from 'cors';
 import {getWorkflowId} from './helpers.js';
 import {logger} from './logger.js';
@@ -19,17 +18,6 @@ import {createValidateMiddleware as validate} from '@bedrock/validation';
 
 const {util: {BedrockError}} = bedrock;
 
-// FIXME: remove and apply to specific routes via
-// `bedrock.express.bodyParser.routes` + `@bedrock/express@8.4`
-bedrock.events.on('bedrock-express.configure.bodyParser', app => {
-  app.use(bodyParser.json({
-    // allow json values that are not just objects or arrays
-    strict: false,
-    limit: '10MB',
-    type: ['json', '+json']
-  }));
-});
-
 export async function addRoutes({app, service} = {}) {
   const {routePrefix} = service;
 

package/lib/storage/exchanges.js

@@ -1,13 +1,20 @@
 /*!
- * Copyright (c) 2022-2026 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2022-2026 Digital Bazaar, Inc.
  */
 import * as bedrock from '@bedrock/core';
 import * as database from '@bedrock/mongodb';
+import {decodeVariables, encodeVariables} from './variables.js';
+import {
+  EXCHANGE_EXPIRY_GRACE_PERIOD, EXCHANGE_TTL_DEFAULT
+} from '../constants.js';
 import {parseLocalId, stripStacktrace} from '../helpers.js';
 import assert from 'assert-plus';
 import {logger} from '../logger.js';
 import {serializeError} from 'serialize-error';
 
+// ensure externalized `variables` garbage collector runs
+import './variablesGarbageCollector.js';
+
 const {util: {BedrockError}} = bedrock;
 
 /* Note: Exchanges have default TTLs of 15 minutes and are always in one of
@@ -23,6 +30,7 @@ one or more steps, each that might issue, verify, or deliver VCs. Capabilities
 must be provided to issue or verify VCs. */
 
 const COLLECTION_NAME = 'vc-exchange';
+const BUCKET_NAME = 'vc-exchange-variables';
 
 // allow updates to the last error every 500ms
 const LAST_ERROR_UPDATE_CONSTRAINTS = {
@@ -33,10 +41,10 @@ const LAST_ERROR_UPDATE_CONSTRAINTS = {
   updateTimeLimit: 1000
 };
 
-const MONGODB_ILLEGAL_KEY_CHAR_REGEX = /[%$.]/;
-
 bedrock.events.on('bedrock-mongodb.ready', async () => {
-  await database.openCollections([COLLECTION_NAME]);
+  await database.openCollections([
+    COLLECTION_NAME, `${BUCKET_NAME}.files`
+  ]);
 
   await database.createIndexes([{
     // cover exchange queries by local workflow ID + exchange ID
@@ -84,32 +92,32 @@ export async function insert({workflowId, exchange}) {
   assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
   assert.string(exchange.id, 'exchange.id');
+  assert.string(exchange.expires, 'exchange.expires');
   // optional time to live in seconds
   assert.optionalNumber(exchange.ttl, 'exchange.ttl');
   // optional variables to use in VC templates
   assert.optionalObject(exchange.variables, 'exchange.variables');
   // optional current step in the exchange
   assert.optionalString(exchange.step, 'exchange.step');
-  // optional expires in exchange
-  assert.optionalString(exchange.expires, 'exchange.expires');
   // optional protocols in exchange
   assert.optionalObject(exchange.protocols, 'exchange.protocols');
 
   // build exchange record
   const now = Date.now();
-  const meta = {created: now, updated: now};
+  const meta = {
+    created: now,
+    updated: now,
+    expires: new Date(exchange.expires)
+  };
   // possible states are: `pending`, `active`, `complete`, or `invalid`
   exchange = {...exchange, sequence: 0, state: 'pending'};
-  if(exchange.expires !== undefined) {
-    meta.expires = new Date(exchange.expires);
-  }
   const {localId: localWorkflowId} = parseLocalId({id: workflowId});
   const record = {
     localWorkflowId,
     // backwards compatibility: enable existing systems to find record
     localExchangerId: localWorkflowId,
     meta,
-    exchange: _encodeVariables({exchange})
+    exchange: await encodeVariables({workflowId, exchange, meta})
   };
 
   // insert the exchange and get the updated record
@@ -175,11 +183,15 @@ export async function get({
   }
 
   let record = await collection.findOne(query, {projection});
-  if(record?.exchange.expires && !allowExpired) {
+  if(!allowExpired) {
     // ensure `expires` is enforced programmatically even if background job
-    // has not yet removed the record
+    // has not yet removed the record; force unexpiring exchanges to be not
+    // found via this code path -- any exchanges without an expiration date
+    // are from very old software and they will need to be manually cleaned up
+    // in the database
     const now = new Date();
-    const expires = new Date(record.exchange.expires);
+    // note: for undefined `expires`, this will be `NaN || now` => `now`
+    const expires = new Date(record.exchange.expires) || now;
     if(now >= expires) {
       record = null;
     }
@@ -198,7 +210,7 @@ export async function get({
     });
   }
 
-  record.exchange = _decodeVariables({exchange: record.exchange});
+  record.exchange = await decodeVariables({workflowId, record});
 
   // backwards compatibility; initialize `sequence`
   if(record.exchange.sequence === undefined) {
@@ -228,21 +240,36 @@ export async function get({
  * @param {string} options.workflowId - The ID of the workflow the exchange
  *   is associated with.
  * @param {object} options.exchange - The exchange to update.
+ * @param {object} options.meta - The exchange meta to update.
  * @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({workflowId, exchange, explain = false} = {}) {
+export async function update({
+  workflowId, exchange, meta, explain = false
+} = {}) {
   assert.string(workflowId, 'workflowId');
   assert.object(exchange, 'exchange');
   const {id} = exchange;
 
+  // force exchange to expire if this code has been called on an old exchange
+  // with no expiration date
+  let updateExpires = false;
+  if(exchange.expires === undefined) {
+    updateExpires = true;
+    const ttl = exchange.ttl ?? EXCHANGE_TTL_DEFAULT;
+    // TTL is in seconds, convert to milliseconds
+    const expires = new Date(Date.now() + ttl * 1000);
+    exchange.expires = expires.toISOString().replace(/\.\d+Z$/, 'Z');
+  }
+
   // encode variable content for storage in mongoDB
-  exchange = _encodeVariables({exchange});
+  meta = {...meta};
+  exchange = await encodeVariables({workflowId, exchange, meta});
 
   // build update
-  const update = _buildUpdate({exchange});
+  const update = _buildUpdate({exchange, meta, updateExpires});
 
   const {base, localId: localWorkflowId} = parseLocalId({id: workflowId});
 
@@ -516,10 +543,11 @@ async function _invalidateExchange({record}) {
       `Could not mark exchange "${record.exchange.id}" invalid.`, {error});
   }
 
-  /* Perform auto-revocation of the VCs or notification (the action to take
-  is specified in the exchange record). */
+  /* Consider perform auto-revocation of the VCs or notification (the action to
+  take is specified in the exchange record). */
   // FIXME: handle auto-revocation / notification in background; do not throw
-  // errors to client
+  // errors to client; consider removing invalidation state as well and rely
+  // solely on TTL to manage exchange secrecy/abuse
 }
 
 async function _markExchangeInvalid({record}) {
@@ -539,9 +567,7 @@ async function _markExchangeInvalid({record}) {
       $set: {
         'exchange.state': 'invalid',
         'meta.updated': now,
-        // allow up to 3 days to resolve invalid exchange issues
-        // (86400 seconds in 24 hours)
-        'meta.expires': new Date(now + 86400 * 3 * 1000)
+        'meta.expires': new Date(now + EXCHANGE_EXPIRY_GRACE_PERIOD)
       }
     };
     const collection = database.collections[COLLECTION_NAME];
@@ -562,7 +588,7 @@ async function _markExchangeInvalid({record}) {
   }
 }
 
-function _buildUpdate({exchange}) {
+function _buildUpdate({exchange, meta, updateExpires = false}) {
   // build update
   const now = Date.now();
   const update = {
@@ -579,15 +605,15 @@ function _buildUpdate({exchange}) {
   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`
+  // only update (fix) `expires` if it was not previously set (a very old
+  // exchange is being updated)
+  if(updateExpires) {
+    // TTL is in seconds, convert to milliseconds
+    const expires = new Date(exchange.expires);
+    // unset any previously set `ttl` and set `expires` instead
     update.$unset['exchange.ttl'] = true;
     update.$set['meta.expires'] = expires;
-    update.$set['exchange.expires'] =
-      expires.toISOString().replace(/\.\d+Z$/, 'Z');
+    update.$set['exchange.expires'] = exchange.expires;
   }
   if(exchange.lastError !== undefined) {
     update.$set['exchange.lastError'] =
@@ -595,43 +621,13 @@ function _buildUpdate({exchange}) {
   } else {
     update.$unset['exchange.lastError'] = true;
   }
-
-  return update;
-}
-
-function _encodeVariables({exchange}) {
-  // if any JSON object any variable uses a character that is not legal in
-  // a JSON key in mongoDB then stringify all the variables
-  if(_hasIllegalMongoDBKeyChar(exchange.variables)) {
-    return {...exchange, variables: JSON.stringify(exchange.variables)};
-  }
-  return exchange;
-}
-
-function _decodeVariables({exchange}) {
-  if(typeof exchange.variables === 'string') {
-    return {...exchange, variables: JSON.parse(exchange.variables)};
+  if(meta?.variablesFilename === false) {
+    update.$unset['meta.variablesFilename'] = true;
+  } else if(typeof meta?.variablesFilename === 'string') {
+    update.$set['meta.variablesFilename'] = meta.variablesFilename;
   }
-  return exchange;
-}
 
-function _hasIllegalMongoDBKeyChar(value) {
-  if(Array.isArray(value)) {
-    for(const e of value) {
-      if(_hasIllegalMongoDBKeyChar(e)) {
-        return true;
-      }
-    }
-  } else if(value && typeof value === 'object') {
-    const keys = Object.keys(value);
-    for(const key of keys) {
-      if(MONGODB_ILLEGAL_KEY_CHAR_REGEX.test(key) ||
-        _hasIllegalMongoDBKeyChar(value[key])) {
-        return true;
-      }
-    }
-  }
-  return false;
+  return update;
 }
 
 /**

package/lib/storage/variables.js

@@ -0,0 +1,225 @@
+/*!
+ * Copyright (c) 2022-2026 Digital Bazaar, Inc.
+ */
+import * as bedrock from '@bedrock/core';
+import * as database from '@bedrock/mongodb';
+import {createHash} from 'node:crypto';
+import {EXCHANGE_EXPIRY_GRACE_PERIOD} from '../constants.js';
+import {PassThrough} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import {buffer as readIntoBuffer} from 'node:stream/consumers';
+
+const {util: {BedrockError}} = bedrock;
+
+/* Note: If the total size for `exchange.variables` is less than
+`VARIABLES_SIZE_LIMIT` then the variables are stored in the exchange record.
+Otherwise, the variables must be converted to JSON and externally stored, in
+a gridfs bucket. Additionally, if the variables contain any JSON keys that
+contain an invalid MongoDB key character, the variables must be stored as
+JSON either within the exchange document or externally (where the JSON is
+stored is determined by size limit mentioned above).
+
+Importantly, all deployed workflow systems must be upgraded to enable reading
+externalized variables prior to writing any externalized variables. So the
+size limit must be at least 10MiB as old software prohibited submitting any
+payloads larger than this over HTTP. That 10MiB HTTP limit must not be raised
+until all systems have been upgraded to enable reading externalized variables,
+ensuring no externalized variables will be written before then.
+
+There still needs to be a cap on the maximum payload that will be accepted
+on various HTTP endpoints to prevent DoS, but once systems support externally
+stored variables, the limit can be raised beyond 10MiB. Additionally, a feature
+to enable different limits per workflow could be implemented if desired (but it
+will require different HTTP body parser setup). */
+
+// very generous 1 hour grace period before externalized variables are deleted
+// after an exchange expires to allow for various asynchronous behaviors
+const VARIABLES_EXPIRY_GRACE_PERIOD = 1000 * 60 * 60;
+
+// for gridfs storage of large exchange `variables`
+export const VARIABLES_STORAGE = {
+  name: 'vc-exchange-variables',
+  bucket: null
+};
+
+// limit to exchange `variables` size; at this size or larger, `variables`
+// must be externalized and stored in a gridfs bucket
+const VARIABLES_SIZE_LIMIT = 1024 * 1024 * 10;
+
+// used to determine whether `variables` can be stored parsed as BSON or must
+// be converted to JSON
+const MONGODB_ILLEGAL_KEY_CHAR_REGEX = /[%$.]/;
+
+bedrock.events.on('bedrock-mongodb.ready', async () => {
+  await database.openCollections([`${VARIABLES_STORAGE.name}.files`]);
+
+  VARIABLES_STORAGE.bucket = database.createGridFSBucket({
+    bucketName: VARIABLES_STORAGE.name
+  });
+
+  await database.createIndexes([{
+    // enables content-based ID lookups in `VARIABLES_STORAGE.name` bucket
+    collection: `${VARIABLES_STORAGE.name}.files`,
+    fields: {filename: 1},
+    options: {
+      unique: true
+    }
+  }, {
+    // enables an application worker (defined below) to find and delete expired
+    // `files` in the `VARIABLES_STORAGE.name` bucket; a TTL index is not used
+    // because `chunks` must also be removed and chunks do not contain a
+    // similar metadata field that would allow for robust atomic updates and
+    // clean up; so the GridFS file deletion API is used in the application
+    // worker
+    collection: `${VARIABLES_STORAGE.name}.files`,
+    // `metadata` is a built-in property for the `files` document schema; and
+    // `expires` will be added to it
+    fields: {'metadata.expires': 1},
+    options: {
+      partialFilterExpression: {
+        'metadata.expires': {$exists: true}
+      },
+      unique: false
+    }
+  }]);
+});
+
+export async function encodeVariables({workflowId, exchange, meta}) {
+  // express variables as JSON to determine total size; a future optimization
+  // might be able to avoid converting to JSON (in some cases)
+  const {variables, ...rest} = exchange;
+  const variablesJson = JSON.stringify(variables);
+
+  // any `variables` that are under the size limit can be stored in the
+  // exchange document itself
+  // FIXME: this version of the software includes `!meta.variablesFilename` in
+  // the conditional below to ensure that live updates can occur: it ensures
+  // this version of the software can run concurrently with either older
+  // versions of the software that have no understanding of externalized
+  // `variables` storage or with newer versions that do understand it (but not
+  // with both); this works because, until a new (likely major) release enables
+  // externalized `variables` storage (by setting `meta.variablesFilename`
+  // based on `variables` size), the following conditional will always execute;
+  // however, once such a release is made and this version encounters
+  // `meta.variablesFilename`, it will use externalized `variables` storage
+  // even if `variables` would fit in an exchange document, because this
+  // version defers the storage location decision to newer software; note that
+  // the new release will remove the `!meta.variablesFilename` check and simply
+  // use the size limit
+  if(!meta.variablesFilename || variablesJson.length < VARIABLES_SIZE_LIMIT) {
+    meta.variablesFilename = false;
+    // if any object has a key that uses a character that is not legal in
+    // a JSON key in mongoDB document, then stringify all the variables
+    return !_hasIllegalMongoDBKeyChar(variables) ?
+      exchange : {...rest, variables: variablesJson};
+  }
+
+  // generate content-based identifier for filename; noting that an local
+  // exchange ID MUST NOT (and currently does not) include a `_` character as
+  // it is used as a delimiter here
+  const buffer = Buffer.from(variablesJson, 'utf8');
+  const filename = `${exchange.id}_${_multibaseMultihashSha256(buffer)}`;
+  meta.variablesFilename = filename;
+
+  // create gridfs file metadata w/expiry; `exchange.expires` MUST be set
+  const expires = new Date(exchange.expires);
+  const metadata = {
+    // add exchange grace period to expiry to cover maximum exchange TTL and
+    // add a generous `variables` grace period as well
+    expires: new Date(
+      expires.getTime() +
+      EXCHANGE_EXPIRY_GRACE_PERIOD + VARIABLES_EXPIRY_GRACE_PERIOD)
+  };
+
+  // store variables; any duplicate content-based identifier will throw a
+  // duplicate error which can be safely ignored
+  const stream = new PassThrough();
+  stream.end(buffer);
+  try {
+    await pipeline(
+      stream,
+      VARIABLES_STORAGE.bucket.openUploadStream(filename, {metadata}));
+  } catch(e) {
+    if(!database.isDuplicateError(e)) {
+      throw new BedrockError(`Could not store exchange variables.`, {
+        name: 'OperationError',
+        details: {
+          workflow: workflowId,
+          exchange: exchange.id,
+          public: true,
+          httpStatusCode: 500
+        },
+        cause: e
+      });
+    }
+  }
+
+  return {...rest};
+}
+
+export async function decodeVariables({workflowId, record}) {
+  const {exchange, meta} = record;
+
+  // if `variables` are stored as a string, parse them from JSON
+  if(typeof exchange.variables === 'string') {
+    return {...exchange, variables: JSON.parse(exchange.variables)};
+  }
+
+  // if `meta` indicates that the variables are externalized, then read them
+  // from the gridfs variables bucket
+  if(meta.variablesFilename) {
+    try {
+      const {bucket} = VARIABLES_STORAGE;
+      const buffer = await readIntoBuffer(
+        bucket.openDownloadStreamByName(meta.variablesFilename));
+      exchange.variables = JSON.parse(buffer.toString('utf8'));
+    } catch(e) {
+      throw new BedrockError(`Could not load exchange variables.`, {
+        name: 'OperationError',
+        details: {
+          workflow: workflowId,
+          exchange: exchange.id,
+          public: true,
+          httpStatusCode: 500
+        },
+        cause: e
+      });
+    }
+  }
+
+  return exchange;
+}
+
+function _hasIllegalMongoDBKeyChar(value) {
+  if(Array.isArray(value)) {
+    for(const e of value) {
+      if(_hasIllegalMongoDBKeyChar(e)) {
+        return true;
+      }
+    }
+  } else if(value && typeof value === 'object') {
+    const keys = Object.keys(value);
+    for(const key of keys) {
+      if(MONGODB_ILLEGAL_KEY_CHAR_REGEX.test(key) ||
+        _hasIllegalMongoDBKeyChar(value[key])) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function _multibaseMultihashSha256(buffer) {
+  // compute SHA-256 hash
+  const digest = createHash('sha256').update(buffer).digest();
+
+  // format as multihash digest
+  // sha2-256: 0x12, length: 32 (0x20), digest value
+  const mh = new Uint8Array(34);
+  mh[0] = 0x12;
+  mh[1] = 0x20;
+  mh.set(digest, 2);
+
+  // return as multibase-base64url-encoded value
+  return 'u' + Buffer.from(mh).toString('base64url');
+}

package/lib/storage/variablesGarbageCollector.js

@@ -0,0 +1,83 @@
+/*!
+ * Copyright (c) 2022-2026 Digital Bazaar, Inc.
+ */
+import * as bedrock from '@bedrock/core';
+import {logger} from '../logger.js';
+import {rangeDelay} from 'delay';
+import {VARIABLES_STORAGE} from './variables.js';
+
+// state for running a garbage collector for expired externalized `variables`
+const VARIABLES_GARBAGE_COLLECTOR = {
+  // used to abort variables garbage collector
+  abortController: new AbortController(),
+  // a Promise that resolves after the `variables` garbage collector has
+  // shutdown cleanly after receiving an abort signal
+  shutdownPromise: null
+};
+
+bedrock.events.on('bedrock.ready', () => {
+  // start the `variables` garbage collector, which runs continuously
+  VARIABLES_GARBAGE_COLLECTOR.shutdownPromise = _startGarbageCollector();
+});
+
+bedrock.events.on('bedrock.exit', async () => {
+  try {
+    // abort variables garbage collector
+    VARIABLES_GARBAGE_COLLECTOR.abortController.abort();
+    logger.debug(
+      'Sent abort signal to "variables" garbage collector, ' +
+      'waiting for shutdown...');
+    await VARIABLES_GARBAGE_COLLECTOR.shutdownPromise;
+    logger.debug('"Variables" garbage collector shutdown was successful.');
+  } catch(error) {
+    logger.error(
+      'Error during "variables" garbage collector shutdown.', {error});
+  }
+});
+
+async function _deleteExpiredVariables({signal}) {
+  signal.throwIfAborted();
+
+  // delete all files found (limit=1000)
+  const {bucket} = VARIABLES_STORAGE;
+  const now = new Date(Date.now() + 86400 * 1000 * 365);
+  const projection = {_id: 1};
+  const cursor = bucket.find({
+    'metadata.expires': {$lte: now}
+  }, {projection}).limit(1000);
+  for await (const {_id} of cursor) {
+    try {
+      signal.throwIfAborted();
+      await bucket.delete(_id);
+    } catch(e) {
+      // ignore file not found errors and throw all others; note: there is
+      // currently not a better way to check for a `not found` error than to
+      // check the message text
+      if(!e.message.includes('not found')) {
+        throw e;
+      }
+    }
+  }
+}
+
+async function _startGarbageCollector() {
+  const {
+    exchanges: {
+      variablesGarbageCollector: {interval}
+    }
+  } = bedrock.config['vc-workflow'];
+  const {signal} = VARIABLES_GARBAGE_COLLECTOR.abortController;
+  while(!signal.aborted) {
+    try {
+      // collect expired externalized exchange "variables" then delay for
+      // `interval` plus some fuzzing (up to 1 minute) to spread load
+      await _deleteExpiredVariables({signal});
+      await rangeDelay(interval, interval + 60000, {signal});
+    } catch(e) {
+      if(e.name === 'AbortError') {
+        break;
+      }
+      logger.error('Error in "variables" garbage collector job.', {error: e});
+    }
+  }
+}

package/lib/vcapi.js

@@ -1,9 +1,10 @@
 /*!
- * Copyright (c) 2018-2026 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2018-2026 Digital Bazaar, Inc.
  */
 import * as bedrock from '@bedrock/core';
 import * as exchanges from './storage/exchanges.js';
 import {evaluateExchangeStep, generateRandom} from './helpers.js';
+import {EXCHANGE_TTL_DEFAULT, EXCHANGE_TTL_MAX_IN_MS} from './constants.js';
 import {exportJWK, generateKeyPair, importJWK} from 'jose';
 import {ExchangeProcessor} from './ExchangeProcessor.js';
 
@@ -14,15 +15,10 @@ import * as oid4vp from './oid4/oid4vp.js';
 
 const {util: {BedrockError}} = bedrock;
 
-const FIFTEEN_MINUTES = 60 * 15;
-
-// 48 hours; make configurable
-const MAX_TTL_IN_MS = 1000 * 60 * 60 * 24 * 2;
-
 export async function createExchange({workflow, exchange}) {
   const {
     expires,
-    ttl = FIFTEEN_MINUTES,
+    ttl = EXCHANGE_TTL_DEFAULT,
     variables = {},
     // allow steps to be skipped by creator as needed
     step: stepName = workflow.initialStep,
@@ -54,7 +50,7 @@ export async function createExchange({workflow, exchange}) {
   }
 
   // should expires isn't too far into the future
-  const maxExpires = new Date(Date.now() + MAX_TTL_IN_MS);
+  const maxExpires = new Date(Date.now() + EXCHANGE_TTL_MAX_IN_MS);
   if(new Date(exchange.expires) > maxExpires) {
     throw new BedrockError(
       'Maximum exchange expiration date is "' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/vc-delivery",
-  "version": "7.15.0",
+  "version": "7.16.0",
   "type": "module",
   "description": "Bedrock Verifiable Credential Delivery",
   "main": "./lib/index.js",
@@ -47,6 +47,7 @@
     "bnid": "^3.0.0",
     "body-parser": "^1.20.3",
     "cors": "^2.8.5",
+    "delay": "^7.0.0",
     "jose": "^6.1.0",
     "json-pointer": "^0.6.2",
     "jsonata": "^2.0.6",
@@ -56,7 +57,7 @@
     "@bedrock/app-identity": "^4.0.0",
     "@bedrock/core": "^6.3.0",
     "@bedrock/did-io": "^10.4.0",
-    "@bedrock/express": "^8.3.1",
+    "@bedrock/express": "^8.6.4",
     "@bedrock/https-agent": "^4.1.0",
     "@bedrock/mongodb": "^11.0.0",
     "@bedrock/oauth2-verifier": "^2.3.1",