@bedrock/kms 9.0.0

package/lib/keystores.js

@@ -0,0 +1,330 @@
+/*!
+ * Copyright (c) 2019-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 pAll from 'p-all';
+import {createRequire} from 'module';
+const require = createRequire(import.meta.url);
+const {LruCache} = require('@digitalbazaar/lru-memoize');
+
+const {util: {BedrockError}} = bedrock;
+
+// load config defaults
+import './config.js';
+
+const USAGE_COUNTER_MAX_CONCURRENCY = 100;
+let KEYSTORE_CONFIG_CACHE;
+
+bedrock.events.on('bedrock.init', async () => {
+  const cfg = bedrock.config.kms;
+  KEYSTORE_CONFIG_CACHE = new LruCache({
+    max: cfg.keystoreConfigCache.maxSize,
+    maxAge: cfg.keystoreConfigCache.maxAge
+  });
+});
+
+bedrock.events.on('bedrock-mongodb.ready', async () => {
+  await database.openCollections(['kms-keystore']);
+
+  await database.createIndexes([{
+    // cover queries keystore by ID
+    collection: 'kms-keystore',
+    fields: {'config.id': 1},
+    options: {unique: true, background: false}
+  }, {
+    // cover config queries by controller
+    collection: 'kms-keystore',
+    fields: {'config.controller': 1},
+    options: {unique: false, background: false}
+  }, {
+    // ensure config uniqueness of reference ID per controller
+    collection: 'kms-keystore',
+    fields: {'config.controller': 1, 'config.referenceId': 1},
+    options: {
+      partialFilterExpression: {
+        'config.referenceId': {$exists: true}
+      },
+      unique: true,
+      background: false
+    }
+  }, {
+    // cover counting keystores in use by meter ID, if present
+    collection: 'kms-keystore',
+    fields: {'config.meterId': 1},
+    options: {
+      partialFilterExpression: {
+        'config.meterId': {$exists: true}
+      },
+      unique: false, background: false
+    }
+  }]);
+});
+
+/**
+ * An object containing information on the query plan.
+ *
+ * @typedef {object} ExplainObject
+ */
+
+/**
+ * Establishes a new keystore by inserting its configuration into storage.
+ *
+ * @param {object} options - The options to use.
+ * @param {object} options.config - The keystore configuration.
+ *
+ * @returns {Promise<object>} The database record.
+ */
+export async function insert({config} = {}) {
+  assert.object(config, 'config');
+  assert.string(config.id, 'config.id');
+  assert.string(config.controller, 'config.controller');
+  assert.string(config.kmsModule, 'config.kmsModule');
+
+  // require starting sequence to be 0
+  if(config.sequence !== 0) {
+    throw new BedrockError(
+      'Keystore config sequence must be "0".',
+      'DataError', {
+        public: true,
+        httpStatusCode: 400
+      });
+  }
+
+  // insert the configuration and get the updated record
+  const now = Date.now();
+  const meta = {created: now, updated: now};
+  const record = {
+    meta,
+    config
+  };
+  try {
+    const result = await database.collections['kms-keystore'].insertOne(
+      record, database.writeOptions);
+    return result.ops[0];
+  } catch(e) {
+    if(!database.isDuplicateError(e)) {
+      throw e;
+    }
+    throw new BedrockError(
+      'Duplicate keystore configuration.',
+      'DuplicateError', {
+        public: true,
+        httpStatusCode: 409
+      }, e);
+  }
+}
+
+/**
+ * Retrieves all keystore configs matching the given query.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.controller - The controller for the keystores to
+ *   retrieve.
+ * @param {object} [options.query={}] - The query to use.
+ * @param {object} [options.options={}] - The query options (eg: 'sort').
+ * @param {boolean} [options.explain=false] - An optional explain boolean.
+ *
+ * @returns {Promise<Array | ExplainObject>} Resolves with the records that
+ *   matched the query or an ExplainObject if `explain=true`.
+ */
+export async function find({
+  controller, query = {}, options = {}, explain = false
+} = {}) {
+  assert.string(controller, 'options.controller');
+  const collection = database.collections['kms-keystore'];
+
+  // force controller ID
+  query['config.controller'] = controller;
+  const cursor = await collection.find(query, options);
+
+  if(explain) {
+    return cursor.explain('executionStats');
+  }
+
+  return cursor.toArray();
+}
+
+/**
+ * Updates a keystore config if its sequence number is next.
+ *
+ * @param {object} options - The options to use.
+ * @param {object} options.config - The keystore configuration.
+ * @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({config, explain = false} = {}) {
+  assert.object(config, 'config');
+
+  const collection = database.collections['kms-keystore'];
+  const query = {
+    'config.id': config.id,
+    'config.sequence': config.sequence - 1,
+    // it is illegal to change the `kmsModule`, so it must match
+    'config.kmsModule': config.kmsModule
+  };
+
+  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');
+  }
+
+  // updates the keystore configuration
+  const result = await collection.updateOne(query, {
+    $set: {
+      config,
+      'meta.updated': Date.now()
+    }
+  }, database.writeOptions);
+
+  if(result.result.n === 0) {
+    // no records changed...
+    throw new BedrockError(
+      'Could not update keystore configuration. ' +
+      'Record sequence and "kmsModule" do not match or keystore does ' +
+      'not exist.',
+      'InvalidStateError', {
+        id: config.id,
+        sequence: config.sequence,
+        httpStatusCode: 409,
+        public: true
+      });
+  }
+
+  // delete record from cache
+  KEYSTORE_CONFIG_CACHE.delete(config.id);
+
+  return true;
+}
+
+/**
+ * Gets a keystore configuration.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.id - The ID of the keystore.
+ *
+ * @returns {Promise<object>} Resolves to `{config, meta}`.
+ */
+export async function get({id} = {}) {
+  assert.string(id, 'id');
+  const fn = () => _getUncachedRecord({id});
+  return KEYSTORE_CONFIG_CACHE.memoize({key: id, fn});
+}
+
+/**
+ * Gets storage statistics for the given meter. This includes the total number
+ * of keystores and keys associated with a meter ID, represented as storage
+ * units according to this module's configuration.
+ *
+ * @param {object} options - The options to use.
+ * @param {string} options.meterId - The ID of the meter to get.
+ * @param {object} options.moduleManager - The KMS module manager to use.
+ * @param {AbortSignal} [options.signal] - An abort signal to check.
+ * @param {Function} [options.aggregate] - An aggregate function that will
+ *   receive each keystore config that matches the `meterId` and the current
+ *   usage; this function may be called to add custom additional usage
+ *   associated with a keystore.
+ * @param {boolean} [options.explain=false] - An optional explain boolean.
+ *
+ * @returns {Promise<object | ExplainObject>} Resolves with the storage usage
+ *   for the meter or an ExplainObject if `explain=true`.
+ */
+export async function getStorageUsage({
+  meterId, moduleManager, signal, aggregate, explain = false
+} = {}) {
+  // find all keystores with the given meter ID
+  const cursor = await database.collections['kms-keystore'].find(
+    {'config.meterId': meterId},
+    {projection: {_id: 0, config: 1}});
+
+  if(explain) {
+    return cursor.explain('executionStats');
+  }
+
+  const {storageCost} = bedrock.config.kms;
+  const usage = {storage: 0};
+  const counters = [];
+  while(await cursor.hasNext()) {
+    // get next keystore config
+    const {config} = await cursor.next();
+
+    // add storage units for keystore
+    usage.storage += storageCost.keystore;
+
+    // if custom aggregator has been given, call it
+    if(aggregate) {
+      counters.push(() => {
+        _checkComputeStorageSignal({signal, meterId});
+        return aggregate({meterId, config, usage});
+      });
+    }
+
+    // add storage units for keys in keystore
+    const {id: keystoreId, kmsModule} = config;
+
+    // get KMS module API and ensure its keys can be counted
+    const moduleApi = await moduleManager.get({id: kmsModule});
+    if(!(moduleApi && typeof moduleApi.getKeyCount === 'function')) {
+      throw new BedrockError(
+        'Bedrock KMS Module API is missing "getKeyCount()".',
+        'NotFoundError',
+        {kmsModule, httpStatusCode: 404, public: true});
+    }
+
+    // start counting keys in keystore
+    counters.push(() => {
+      _checkComputeStorageSignal({signal, meterId});
+      return _addKeyCount({usage, moduleApi, keystoreId, signal});
+    });
+
+    _checkComputeStorageSignal({signal, meterId});
+  }
+
+  // await any counters that didn't complete
+  await pAll(counters, {concurrency: USAGE_COUNTER_MAX_CONCURRENCY});
+
+  return usage;
+}
+
+function _checkComputeStorageSignal({signal, meterId}) {
+  if(signal && signal.abort) {
+    throw new BedrockError(
+      'Computing metered storage aborted.',
+      'AbortError',
+      {meterId, httpStatusCode: 503, public: true});
+  }
+}
+
+async function _addKeyCount({usage, moduleApi, keystoreId}) {
+  const {storageCost} = bedrock.config.kms;
+  const {count} = await moduleApi.getKeyCount({keystoreId});
+  usage.storage += count * storageCost.key;
+}
+
+// exported for testing purposes
+export async function _getUncachedRecord({id, explain = false} = {}) {
+  const collection = database.collections['kms-keystore'];
+  const query = {'config.id': id};
+  const projection = {_id: 0, config: 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(
+      'Keystore configuration not found.',
+      'NotFoundError',
+      {keystoreId: id, httpStatusCode: 404, public: true});
+  }
+  return record;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@bedrock/kms",
+  "version": "9.0.0",
+  "type": "module",
+  "description": "Key management for Bedrock applications",
+  "main": "./lib/index.js",
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitalbazaar/bedrock-kms"
+  },
+  "keywords": [
+    "bedrock"
+  ],
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "https://digitalbazaar.com"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/bedrock-kms/issues"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "homepage": "https://github.com/digitalbazaar/bedrock-kms",
+  "dependencies": {
+    "@digitalbazaar/lru-memoize": "^2.0.0",
+    "p-all": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@bedrock/core": "^5.0.0",
+    "@bedrock/did-context": "^3.0.0",
+    "@bedrock/did-io": "^7.0.0",
+    "@bedrock/jsonld-document-loader": "^2.0.0",
+    "@bedrock/mongodb": "^9.0.0",
+    "@bedrock/package-manager": "^2.0.0",
+    "@bedrock/security-context": "^6.0.0",
+    "@bedrock/veres-one-context": "^13.0.0"
+  },
+  "directories": {
+    "lib": "./lib"
+  },
+  "devDependencies": {
+    "eslint": "^7.32.0",
+    "eslint-config-digitalbazaar": "^2.8.0",
+    "eslint-plugin-jsdoc": "^37.9.7",
+    "jsdoc-to-markdown": "^7.1.1"
+  }
+}

package/test/mocha/.eslintrc

@@ -0,0 +1,9 @@
+{
+  "env": {
+    "mocha": true
+  },
+  "globals": {
+    "assertNoError": true,
+    "should": true
+  }
+}

package/test/mocha/10-keystores-insert-api.js

@@ -0,0 +1,275 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import {keystores} from '@bedrock/kms';
+
+describe('keystores APIs', () => {
+  describe('insert API', () => {
+    it('throws error on missing config', async () => {
+      let err;
+      let result;
+      try {
+        result = await keystores.insert();
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config (object) is required');
+    });
+    it('throws error on missing config.id', async () => {
+      let err;
+      let result;
+      const config = {};
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config.id (string) is required');
+    });
+    it('throws error on missing config.controller', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config.controller (string) is required');
+    });
+    it('throws error on missing config.kmsModule', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config.kmsModule (string) is required');
+    });
+    it('throws error on missing config.sequence', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1'
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('Keystore config sequence must be "0".');
+    });
+    it('throws error on negative config.sequence', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: -1,
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('Keystore config sequence must be "0".');
+    });
+    it('throws error on float config.sequence', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: 1.1,
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('Keystore config sequence must be "0".');
+    });
+    it('throws error on non-zero config.sequence', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: 1,
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('Keystore config sequence must be "0".');
+    });
+    it('throws error on string config.sequence', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: '0',
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('Keystore config sequence must be "0".');
+    });
+    it('throws error on non-string config.id', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 1,
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: '0',
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config.id (string) is required');
+    });
+    it('throws error on non-string config.controller', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 1,
+        kmsModule: 'ssm-v1',
+        sequence: '0',
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.not.exist(result);
+      should.exist(err);
+      err.message.should.contain('config.controller (string) is required');
+    });
+    it('successfully creates a keystore', async () => {
+      let err;
+      let result;
+      const config = {
+        id: 'https://example.com/keystores/foo',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: 0,
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      assertNoError(err);
+      should.exist(result);
+      result.should.be.an('object');
+      result.should.have.property('config');
+      result.config.should.eql(config);
+    });
+    it('throws DuplicateError on duplicate keystore config', async () => {
+      let err;
+      let result;
+      const config = {
+        id:
+          'https://example.com/keystores/fbea027c-ecc4-4562-b3dc-392db7b7c7c6',
+        controller: 'bar',
+        kmsModule: 'ssm-v1',
+        sequence: 0,
+      };
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      assertNoError(err);
+      should.exist(result);
+      result = undefined;
+      err = undefined;
+      try {
+        result = await keystores.insert({config});
+      } catch(e) {
+        err = e;
+      }
+      should.exist(err);
+      err.name.should.equal('DuplicateError');
+    });
+    it('throws DuplicateError on config with same controller and referenceId',
+      async () => {
+        // configs have unique IDs, but the same controller and referenceId
+        let err;
+        let result;
+        const keystoreConfig1 = {
+          id: 'https://example.com/keystores/fbea027c',
+          controller: 'bar',
+          kmsModule: 'ssm-v1',
+          referenceId: 'urn:uuid:72b89236-7bb7-4d00-8930-9c74c4a7a4a8',
+          sequence: 0,
+        };
+        try {
+          result = await keystores.insert({config: keystoreConfig1});
+        } catch(e) {
+          err = e;
+        }
+        assertNoError(err);
+        should.exist(result);
+
+        const keystoreConfig2 = {
+          id: 'https://example.com/keystores/4f398f8f',
+          controller: 'bar',
+          kmsModule: 'ssm-v1',
+          referenceId: 'urn:uuid:72b89236-7bb7-4d00-8930-9c74c4a7a4a8',
+          sequence: 0,
+        };
+
+        result = undefined;
+        err = undefined;
+        try {
+          result = await keystores.insert({config: keystoreConfig2});
+        } catch(e) {
+          err = e;
+        }
+        should.exist(err);
+        err.name.should.equal('DuplicateError');
+      });
+  }); // end insert API
+}); // end keystore APIs