@bedrock/vc-delivery 1.0.0

package/LICENSE.md

@@ -0,0 +1,115 @@
+Bedrock Non-Commercial License v1.0
+===================================
+
+Copyright (c) 2011-2021 Digital Bazaar, Inc.
+All rights reserved.
+
+Summary
+=======
+
+This license allows the licensee to use Bedrock and its software modules
+for non-commercial purposes such as self-study, research, personal
+projects, or for evaluation purposes. If the licensee uses Bedrock
+directly or indirectly to generate revenue, or to provide products or
+services to more than 500 people (users), the licensee must immediately
+obtain a non-profit or commercial license.
+
+Examples
+========
+
+These are examples of cases that are allowed by this license:
+
+* The licensee is an individual that creates Bedrock-dependent software for
+  personal use only.
+* The licensee is an individual or group of students/researchers that uses
+  Bedrock to experiment with an idea for a non-commercial project.
+* The licensee is a startup company that prototypes a Bedrock-dependent
+  product before they have cash flow and will be testing the prototype
+  software with less than 500 users. The service will not generate revenue
+  of any kind.
+* The licensee is a for-profit organization that creates a product or
+  service that is used by less than 500 users and is built with or
+  integrates with Bedrock. The service must be exclusively provided for free
+  and no parent, subsidiary, agent, or affiliate organization may profit
+  from its use.
+
+These cases require a non-profit or commercial license:
+
+* The licensee is a non-profit that receives funding to create and/or run a
+  Bedrock-dependent service.
+* The licensee is a startup company with Bedrock-dependent software that is
+  funded by another organization.
+* The licensee is a startup company that is going into production with
+  Bedrock-dependent software.
+* The licensee has more than 500 users using a Bedrock-dependent service
+  either directly or indirectly.
+* The licensee is a medium to large organization that builds or integrates a
+  commercial product or service with Bedrock.
+
+THE LICENSE
+===========
+
+This section and all subsequent sections of this document constitute the
+agreement between the licensee and Digital Bazaar, Inc.
+
+DEFINITIONS
+===========
+
+* Product - The Bedrock software and any modules associated with Bedrock
+where Digital Bazaar, Inc. owns the copyright.
+
+CONDITIONS
+==========
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted for NON-COMMERCIAL PURPOSES as long as the
+following conditions are met:
+
+1. Any use of the Product must not generate revenue for the licensee or
+   any parent, subsidiary, agent, or affiliate of the licensee. Use of
+   Product includes, but is not limited to, interacting with any of the
+   licensee's Product-dependent products or services over a network.
+
+2. The aggregate number of individual people (users) of the licensee's
+   products or services that use Product must be less than 500.
+
+3. Redistributions of source code must retain the above copyright notice
+   intact, this list of conditions and the following disclaimer.
+
+4. Redistributions in binary form must reproduce the above copyright
+   notice, this license and the following disclaimer in the documentation and
+   on a web page available via interactive use and/or other materials
+   provided with the distribution.
+
+5. Neither the name of the copyright holder, the names of its
+   contributors, nor any trademarks held by the copyright holder may be used
+   to endorse or promote products or services built using the Product without
+   specific prior written permission.
+
+6. Any modifications are clearly outlined in release documentation and are
+   specifically mentioned as not being a part of an official Product release.
+   No additional restrictions to this license may be made when distributing
+   modifications.
+
+7. For the avoidance of doubt, this license prohibits sublicensing of the
+   Product.
+
+8. Any breach of this license by licensee must be resolved within 30 days.
+   Failure to do so results in the termination of this license.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+To obtain a non-profit or commercial license for Product, please contact
+Digital Bazaar, Inc. at the following email address:
+
+Digital Bazaar <support@digitalbazaar.com>

package/README.md

@@ -0,0 +1 @@
+# bedrock-module-template-http

package/lib/config.js

@@ -0,0 +1,10 @@
+/*!
+ * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+
+const {config} = bedrock;
+
+// use `vc-exchanger` namespace
+const namespace = 'vc-exchanger';
+config[namespace] = {};

package/lib/exchanges.js

@@ -0,0 +1,295 @@
+/*!
+ * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import * as database from '@bedrock/mongodb';
+import assert from 'assert-plus';
+import {logger} from './logger.js';
+import {parseLocalId} from './helpers.js';
+
+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`.
+
+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
+such as auto-revocation or notification.
+
+Each pending exchange may include optionally encrypted VCs for pickup and / or
+VC templates and required variables (which may come from other VCs) that must
+be provided to populate those templates. If any templates are provided, then
+a capability to issue the VC must also be provided. If any VCs are to be
+provided during the exchange a capability to verify them must be provided. */
+
+const COLLECTION_NAME = 'vc-exchange';
+
+bedrock.events.on('bedrock-mongodb.ready', async () => {
+  await database.openCollections([COLLECTION_NAME]);
+
+  await database.createIndexes([{
+    // cover exchange queries by exchanger ID + exchange ID
+    collection: COLLECTION_NAME,
+    fields: {localExchangerId: 1, 'exchange.id': 1},
+    options: {unique: true, background: false}
+  }, {
+    // expire exchanges based on `expires` field
+    collection: COLLECTION_NAME,
+    fields: {'meta.expires': 1},
+    options: {
+      partialFilterExpression: {
+        'meta.expires': {$exists: true}
+      },
+      unique: false,
+      background: false,
+      expireAfterSeconds: 0
+    }
+  }]);
+});
+
+/**
+ * Inserts an exchange record.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.exchangerId - The ID of the exchanger that the
+ *   exchange is associated with.
+ * @param {object} options.exchange - The exchange to insert.
+ *
+ * @returns {Promise<object>} Resolves to the database record.
+ */
+export async function insert({exchangerId, exchange}) {
+  assert.string(exchangerId, 'exchangerId');
+  assert.object(exchange, 'exchange');
+  assert.string(exchange.id, 'exchange.id');
+  // optional time to live in seconds
+  assert.optionalNumber(exchange.ttl);
+  // optional variables to use in VC templates
+  assert.optionalObject(exchange.variables);
+  // optional current step in the exchange
+  assert.optionalString(exchange.step);
+
+  // build exchange record
+  const now = Date.now();
+  const meta = {created: now, updated: now};
+  if(exchange.ttl !== undefined) {
+    // TTL is in seconds
+    meta.expires = new Date(now + exchange.ttl * 1000);
+  }
+  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const record = {
+    localExchangerId,
+    meta,
+    // possible states are: `pending`, `complete`, or `invalid`
+    exchange: {...exchange, state: 'pending'}
+  };
+
+  // insert the exchange and get the updated record
+  try {
+    const collection = database.collections[COLLECTION_NAME];
+    const result = await collection.insertOne(record);
+    return result.ops[0];
+  } catch(e) {
+    if(!database.isDuplicateError(e)) {
+      throw e;
+    }
+    throw new BedrockError('Duplicate document.', {
+      name: 'DuplicateError',
+      details: {
+        public: true,
+        httpStatusCode: 409
+      },
+      cause: e
+    });
+  }
+}
+
+/**
+ * Gets an exchange record.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.exchangerId - The ID of the exchanger that the
+ *   exchange is associated with.
+ * @param {string} options.id - The ID of the exchange to retrieve.
+ * @param {boolean} [options.explain=false] - An optional explain boolean.
+ *
+ * @returns {Promise<object | ExplainObject>} Resolves with the record that
+ *   matches the query or an ExplainObject if `explain=true`.
+ */
+export async function get({exchangerId, id, explain = false} = {}) {
+  assert.string(exchangerId, 'exchangerId');
+  assert.string(id, 'id');
+
+  const {localId: localExchangerId} = parseLocalId({id: exchangerId});
+  const collection = database.collections[COLLECTION_NAME];
+  const query = {
+    localExchangerId,
+    'exchange.id': id,
+    // treat exchange as not found if invalid
+    'exchange.state': {$ne: 'invalid'}
+  };
+  const projection = {_id: 0, exchange: 1, meta: 1};
+
+  if(explain) {
+    // 'find().limit(1)' is used here because 'findOne()' doesn't return a
+    // cursor which allows the use of the explain function.
+    const cursor = await collection.find(query, {projection}).limit(1);
+    return cursor.explain('executionStats');
+  }
+
+  const record = await collection.findOne(query, {projection});
+  if(!record) {
+    throw new BedrockError('Exchange not found.', {
+      name: 'NotFoundError',
+      details: {
+        exchanger: exchangerId,
+        exchange: id,
+        httpStatusCode: 404,
+        public: true
+      }
+    });
+  }
+
+  return record;
+}
+
+/**
+ * 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 {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} = {}) {
+  assert.string(exchangerId, 'exchangerId');
+  assert.string(id, 'id');
+
+  // build update
+  const now = Date.now();
+  const update = {
+    $set: {
+      'exchange.state': 'complete',
+      'meta.updated': now
+    }
+  };
+
+  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 change to `complete`
+    'exchange.state': 'pending'
+  };
+
+  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 complete 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
+  const record = await get({exchangerId, id});
+
+  /* Note: Here the exchange *does* exist, but was already completed. This is
+  an error condition that must result in invalidating the exchange. */
+
+  // invalidate exchange, but do not throw any error to client; only log it
+  _invalidateExchange({record}).catch(
+    error => logger.error(`Could not invalidate exchange "${id}".`, {error}));
+
+  // throw duplicate completed exchange error
+  throw new BedrockError('Could not complete exchange; already completed.', {
+    name: 'DuplicateError',
+    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
+    await _markExchangeInvalid({record});
+  } catch(error) {
+    logger.error(
+      `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). */
+  // FIXME: handle auto-revocation / notification in background; do not throw
+  // errors to client
+}
+
+async function _markExchangeInvalid({record}) {
+  const now = Date.now();
+
+  // mark exchange invalid
+  try {
+    const query = {
+      localExchangerId: record.localExchangerId,
+      'exchange.id': record.exchange.id
+    };
+    const update = {
+      $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)
+      }
+    };
+    const collection = database.collections[COLLECTION_NAME];
+    const result = await collection.updateOne(query, update);
+    if(result.result.n > 0) {
+      // document modified: success
+      return true;
+    }
+  } catch(e) {
+    throw new BedrockError('Could not mark exchange invalid.', {
+      name: 'OperationError',
+      details: {
+        public: true,
+        httpStatusCode: 500
+      },
+      cause: e
+    });
+  }
+}
+
+/**
+ * An object containing information on the query plan.
+ *
+ * @typedef {object} ExplainObject
+ */

package/lib/helpers.js

@@ -0,0 +1,63 @@
+/*!
+ * Copyright (c) 2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import {decodeId, generateId} from 'bnid';
+import {Ed25519Signature2020} from '@digitalbazaar/ed25519-signature-2020';
+import {httpsAgent} from '@bedrock/https-agent';
+import {serviceAgents} from '@bedrock/service-agent';
+import {ZcapClient} from '@digitalbazaar/ezcap';
+
+const {config} = bedrock;
+
+export function getExchangerId({routePrefix, localId} = {}) {
+  return `${config.server.baseUri}${routePrefix}/${localId}`;
+}
+
+export async function generateRandom() {
+  // 128-bit random number, base58 multibase + multihash encoded
+  return generateId({
+    bitLength: 128,
+    encoding: 'base58',
+    multibase: true,
+    multihash: true
+  });
+}
+
+export async function getZcapClient({exchanger} = {}) {
+  // get service agent for communicating with the issuer instance
+  const {serviceAgent} = await serviceAgents.get(
+    {serviceType: 'vc-exchanger'});
+  const {capabilityAgent, zcaps} = await serviceAgents.getEphemeralAgent(
+    {config: exchanger, serviceAgent});
+
+  // create zcap client for issuing VCs
+  const zcapClient = new ZcapClient({
+    agent: httpsAgent,
+    invocationSigner: capabilityAgent.getSigner(),
+    SuiteClass: Ed25519Signature2020
+  });
+
+  return {zcapClient, zcaps};
+}
+
+export function parseLocalId({id}) {
+  // format: <base>/<localId>
+  const idx = id.lastIndexOf('/');
+  const localId = id.slice(idx + 1);
+  return {
+    base: id.slice(0, idx),
+    localId: decodeLocalId({localId})
+  };
+}
+
+export function decodeLocalId({localId} = {}) {
+  // convert to `Buffer` for database storage savings
+  return Buffer.from(decodeId({
+    id: localId,
+    encoding: 'base58',
+    multibase: true,
+    multihash: true,
+    expectedSize: 16
+  }));
+}

package/lib/http.js

@@ -0,0 +1,195 @@
+/*!
+ * Copyright (c) 2018-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import * as exchanges from './exchanges.js';
+import * as oidc4vci from './oidc4vci.js';
+import {createChallenge as _createChallenge, verify} from './verify.js';
+import {
+  createExchangeBody, useExchangeBody
+} from '../schemas/bedrock-vc-exchanger.js';
+import {metering, middleware} from '@bedrock/service-core';
+import {asyncHandler} from '@bedrock/express';
+import bodyParser from 'body-parser';
+import cors from 'cors';
+import {generateRandom} from './helpers.js';
+import {issue} from './issue.js';
+import {klona} from 'klona';
+import {logger} from './logger.js';
+import {createValidateMiddleware as validate} from '@bedrock/validation';
+
+const {util: {BedrockError}} = bedrock;
+
+// FIXME: remove and apply at top-level application
+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;
+
+  const baseUrl = `${routePrefix}/:localId`;
+  const routes = {
+    exchanges: `${baseUrl}/exchanges`,
+    exchange: `${baseUrl}/exchanges/:exchangeId`
+  };
+
+  // used to retrieve service object (exchanger) config
+  const getConfigMiddleware = middleware.createGetConfigMiddleware({service});
+
+  // used to fetch exchange record in parallel
+  const getExchange = asyncHandler(async (req, res, next) => {
+    const {localId, exchangeId: id} = req.params;
+    const {baseUri} = bedrock.config.server;
+    const exchangerId = `${baseUri}${routePrefix}/${localId}`;
+    // save promise in request, do not wait for it to settle
+    req.exchange = exchanges.get({exchangerId, id});
+    next();
+  });
+
+  /* Note: CORS is used on all endpoints. This is safe because authorization
+  uses HTTP signatures + capabilities or OAuth2, not cookies; CSRF is not
+  possible. */
+
+  // create an exchange
+  app.options(routes.exchanges, cors());
+  app.post(
+    routes.exchanges,
+    cors(),
+    validate({bodySchema: createExchangeBody}),
+    getConfigMiddleware,
+    middleware.authorizeServiceObjectRequest(),
+    asyncHandler(async (req, res) => {
+      // FIXME: check available storage via meter before allowing operation
+
+      try {
+        const {config} = req.serviceObject;
+        const {
+          ttl, oidc4vci, variables = {},
+          // allow steps to be skipped by creator as needed
+          step = config.initialStep
+        } = req.body;
+
+        // validate exchange step, if given
+        if(step && !(step in config.steps)) {
+          throw new BedrockError(`Undefined step "${step}".`, {
+            name: 'DataError',
+            details: {httpStatusCode: 400, public: true}
+          });
+        }
+
+        // insert exchange
+        const {id: exchangerId} = config;
+        const exchange = {
+          id: await generateRandom(),
+          ttl,
+          variables,
+          oidc4vci,
+          step
+        };
+        await exchanges.insert({exchangerId, exchange});
+        const location = `${exchangerId}/exchanges/${exchange.id}`;
+        res.status(204).location(location).send();
+      } catch(error) {
+        logger.error(error.message, {error});
+        throw error;
+      }
+
+      // meter operation usage
+      metering.reportOperationUsage({req});
+    }));
+
+  // VC-API exchange endpoint
+  app.options(routes.exchange, cors());
+  app.post(
+    routes.exchange,
+    cors(),
+    validate({bodySchema: useExchangeBody()}),
+    getExchange,
+    getConfigMiddleware,
+    asyncHandler(async (req, res) => {
+      const {config: exchanger} = req.serviceObject;
+      const {exchange} = await req.exchange;
+
+      // process exchange step if present
+      if(exchange.step) {
+        const step = exchanger.steps[exchange.step];
+
+        // 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) {
+            const verifiablePresentationRequest = klona(
+              step.verifiablePresentationRequest);
+            if(createChallenge) {
+              /* Note: When creating a challenge, the initial step always
+              uses the local exchange ID because the initial step itself
+              is one-time use. Subsequent steps, which only VC-API (as opposed
+              to other protocols) supports creating additional challenges via
+              the VC-API verifier API. */
+              let challenge;
+              if(isInitialStep) {
+                challenge = exchange.id;
+              } else {
+                // generate a new challenge using verifier API
+                ({challenge} = await _createChallenge({exchanger}));
+              }
+              verifiablePresentationRequest.challenge = challenge;
+            }
+            // send VPR
+            res.json({verifiablePresentationRequest});
+            return;
+          }
+
+          // verify the VP
+          const expectedChallenge = isInitialStep ? exchange.id : undefined;
+          const {verificationMethod} = await verify(
+            {exchanger, presentation, expectedChallenge});
+
+          // FIXME: ensure VP satisfies step VPR; implement templates (jsonata)
+          // to convert VPR responses to more exchange variables
+
+          // store VP in variables
+          exchange.variables[exchange.step] = {
+            did: verificationMethod.controller,
+            verifiablePresentation: presentation
+          };
+
+          // 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;
+          // }
+        }
+      }
+
+      // mark exchange complete
+      await exchanges.complete({exchangerId: exchanger.id, id: exchange.id});
+
+      // FIXME: decide what the best recovery path is if delivery fails (but no
+      // replay attack detected) after exchange has been marked complete
+
+      // issue VCs
+      const {verifiablePresentation} = await issue({exchanger, exchange});
+
+      // send VP
+      res.json({verifiablePresentation});
+    }));
+
+  // create OIDC4VCI routes to be used with each individual exchange
+  await oidc4vci.createRoutes(
+    {app, exchangeRoute: routes.exchange, getConfigMiddleware, getExchange});
+}