@bedrock/kms-module-core 1.0.0

package/LICENSE.md

@@ -0,0 +1,115 @@
+Bedrock Non-Commercial License v1.0
+===================================
+
+Copyright (c) 2011-2016 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,3 @@
+# bedrock-kms-module-core
+
+WebKMS module core for Bedrock WebKMS modules

package/lib/KmsModule.js

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+
+// provides main common interface to be called by a WebKMS system
+export class KmsModule {
+  constructor({core, keyStorage} = {}) {
+    this.core = core;
+    this.keyStorage = keyStorage;
+  }
+
+  /**
+   * Generates a new key.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {string} options.controller - The key controller.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} Key information `{keyId, keyDescription}`.
+   */
+  async generateKey({keyId, controller, operation} = {}) {
+    const {core, keyStorage} = this;
+    const {key, keyDescription} = await core.generateKey({
+      keyId, controller, operation
+    });
+    await keyStorage.insert({key});
+
+    return {keyId, keyDescription};
+  }
+
+  /**
+   * Gets the number of keys in a given keystore.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keystoreId - The ID of the keystore.
+   *
+   * @returns {Promise<object>} Key count information.
+   */
+  async getKeyCount({keystoreId} = {}) {
+    const {keyStorage} = this;
+    return keyStorage.getCount({keystoreId});
+  }
+
+  /**
+   * Gets the key description (no private key material) for the given key.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {string} options.controller - The key controller.
+   *
+   * @returns {Promise<object>} Key information.
+   */
+  async getKeyDescription({keyId, controller} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    return core.getKeyDescription({key, controller});
+  }
+
+  /**
+   * Wraps a cryptographic key using a key encryption key (KEK).
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {object} options.operation - The KMS operation.
+   * @param {object} [options.zcapInvocation] - The zcap invocation used to
+   *   run the KMS operation; if the KMS operation was invoked via zcap.
+   *
+   * @returns {Promise<object>} An object containing `{wrappedKey}`.
+   */
+  async wrapKey({keyId, operation, zcapInvocation} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    _checkZcapInvocationRules({key, zcapInvocation});
+    return core.wrapKey({key, operation});
+  }
+
+  /**
+   * Unwraps a cryptographic key using a key encryption key (KEK).
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {object} options.operation - The KMS operation.
+   * @param {object} [options.zcapInvocation] - The zcap invocation used to
+   *   run the KMS operation; if the KMS operation was invoked via zcap.
+   *
+   * @returns {Promise<object>} An object containing `{unwrappedKey}`.
+   */
+  async unwrapKey({keyId, operation, zcapInvocation} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    _checkZcapInvocationRules({key, zcapInvocation});
+    return core.unwrapKey({key, operation});
+  }
+
+  /**
+   * Signs some data. Note that the data will be sent to the server, so if
+   * this data is intended to be secret it should be hashed first. However,
+   * hashing the data first may present interoperability issues so choose
+   * wisely.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {object} options.operation - The KMS operation.
+   * @param {object} [options.zcapInvocation] - The zcap invocation used to
+   *   run the KMS operation; if the KMS operation was invoked via zcap.
+   *
+   * @returns {Promise<object>} An object containing `{signatureValue}`.
+   */
+  async sign({keyId, operation, zcapInvocation} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    _checkZcapInvocationRules({key, zcapInvocation});
+    return core.sign({key, operation});
+  }
+
+  /**
+   * Verifies some data. Note that the data will be sent to the server, so if
+   * this data is intended to be secret it should be hashed first. However,
+   * hashing the data first may present interoperability issues so choose
+   * wisely.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {object} options.operation - The KMS operation.
+   * @param {object} [options.zcapInvocation] - The zcap invocation used to
+   *   run the KMS operation; if the KMS operation was invoked via zcap.
+   *
+   * @returns {Promise<object>} An object containing `{verified}`.
+   */
+  async verify({keyId, operation, zcapInvocation} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    _checkZcapInvocationRules({key, zcapInvocation});
+    return core.verify({key, operation});
+  }
+
+  /**
+  * Derives a shared secret via the given peer public key, typically for use
+  * as one parameter for computing a shared key. It should not be used as
+  * a shared key itself, but rather input into a key derivation function (KDF)
+  * to produce a shared key.
+  *
+  * @param {object} options - The options to use.
+  * @param {string} options.keyId - The key ID to use.
+  * @param {object} options.operation - The KMS operation.
+  * @param {object} [options.zcapInvocation] - The zcap invocation used to
+  *   run the KMS operation; if the KMS operation was invoked via zcap.
+  *
+  * @returns {Promise<object>} An object containing `{secret}`.
+  */
+  async deriveSecret({keyId, operation, zcapInvocation} = {}) {
+    const {core, keyStorage} = this;
+    const {key} = await keyStorage.get({id: keyId});
+    _checkZcapInvocationRules({key, zcapInvocation});
+    return core.deriveSecret({key, operation});
+  }
+}
+
+function _checkZcapInvocationRules({key, zcapInvocation}) {
+  // operation not invoked via zcap
+  if(!zcapInvocation) {
+    return;
+  }
+  // no extra zcap invocation restrictions on the key
+  if(key.maxCapabilityChainLength === undefined) {
+    return;
+  }
+  // ensure zcap invocation capability change length does not exceed the
+  // rules from the key record
+  if(zcapInvocation.dereferencedChain.length > key.maxCapabilityChainLength) {
+    throw new Error(
+      'Maximum zcap invocation capability chain length ' +
+      `(${key.maxCapabilityChainLength}) exceeded.`);
+  }
+}

package/lib/core/Core.js

@@ -0,0 +1,226 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+*/
+import assert from 'assert-plus';
+import {getKeyOp} from './operations.js';
+import {parseTemplate} from 'url-template';
+
+export class Core {
+  constructor() {}
+
+  /**
+   * Generates a new key.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} options.keyId - The key ID to use.
+   * @param {string} options.controller - The key controller.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} Key information.
+   */
+  async generateKey({keyId, controller, operation}) {
+    assert.string(keyId, 'options.keyId');
+    assert.string(controller, 'options.controller');
+    assert.object(operation, 'options.operation');
+
+    const {
+      invocationTarget: {
+        // specific key type
+        type,
+        // max acceptable length of the capability chain used in a capability
+        // invocation to invoke a KMS operation with the key
+        maxCapabilityChainLength,
+        // any public alias for the key
+        publicAlias,
+        // any public alias template for the key
+        publicAliasTemplate
+      }
+    } = operation;
+    assert.string(type, 'options.operation.invocationTarget.type');
+    assert.optionalNumber(
+      maxCapabilityChainLength,
+      'options.operation.invocationTarget.maxCapabilityChainLength');
+    assert.optionalString(
+      publicAlias, 'options.operation.invocationTarget.publicAlias');
+    assert.optionalString(
+      publicAliasTemplate,
+      'options.operation.invocationTarget.publicAliasTemplate');
+
+    if(publicAlias && publicAliasTemplate) {
+      throw new Error(
+        'Only one of "publicAlias" or "publicAliasTemplate" may be given.');
+    }
+
+    // if `publicAliasTemplate` was given, ensure it can be parsed prior to
+    // attempting key generation
+    let template;
+    if(publicAliasTemplate) {
+      template = parseTemplate(publicAliasTemplate);
+    }
+
+    // perform key generation
+    const op = getKeyOp({name: 'generateKey', type});
+    const {key, keyDescription} = await op({
+      keyId, type, controller,
+      maxCapabilityChainLength, publicAlias, publicAliasTemplate
+    });
+
+    // add any extra key restrictions
+    if(maxCapabilityChainLength !== undefined) {
+      key.maxCapabilityChainLength = maxCapabilityChainLength;
+    }
+
+    // add any public alias or template
+    if(publicAlias) {
+      key.publicAlias = publicAlias;
+      // override public key `id` with `publicAlias`
+      keyDescription.id = publicAlias;
+    } else if(publicAliasTemplate) {
+      key.publicAliasTemplate = publicAliasTemplate;
+      // compute public alias from template
+      keyDescription.id = template.expand(keyDescription);
+    }
+
+    return {keyId, key, keyDescription};
+  }
+
+  /**
+   * Gets the key description (no private key material) for the given key.
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.key - The key object to use.
+   * @param {string} options.controller - The key controller.
+   *
+   * @returns {Promise<object>} Key information.
+   */
+  async getKeyDescription({key, controller} = {}) {
+    let type;
+    if(key.type.startsWith('urn:webkms:multikey:')) {
+      type = 'Multikey';
+    } else {
+      type = key.type;
+    }
+    const description = {
+      '@context': key['@context'],
+      id: key.id,
+      type,
+      controller
+    };
+    if(key.publicKeyMultibase) {
+      description.publicKeyMultibase = key.publicKeyMultibase;
+    }
+    if(key.publicKeyBase58) {
+      description.publicKeyBase58 = key.publicKeyBase58;
+    }
+
+    // override `id` with `publicAlias` / `publicAliasTemplate` if available
+    if(key.publicAlias) {
+      description.id = key.publicAlias;
+    } else if(key.publicAliasTemplate) {
+      // compute public alias from template
+      const template = parseTemplate(key.publicAliasTemplate);
+      description.id = template.expand(description);
+    }
+
+    return description;
+  }
+
+  /**
+   * Wraps a cryptographic key using a key encryption key (KEK).
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.key - The key object to use.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} An object containing `{wrappedKey}`.
+   */
+  async wrapKey({key, operation}) {
+    assert.object(key, 'options.key');
+    assert.object(operation, 'options.operation');
+
+    const {type} = key;
+    const op = getKeyOp({name: 'wrapKey', type});
+    return op({kek: key, operation});
+  }
+
+  /**
+   * Unwraps a cryptographic key using a key encryption key (KEK).
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.key - The key object to use.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} An object containing `{unwrappedKey}`.
+   */
+  async unwrapKey({key, operation}) {
+    assert.object(key, 'options.key');
+    assert.object(operation, 'options.operation');
+
+    const {type} = key;
+    const op = getKeyOp({name: 'unwrapKey', type});
+    return op({kek: key, operation});
+  }
+
+  /**
+   * Signs some data. Note that the data will be sent to the server, so if
+   * this data is intended to be secret it should be hashed first. However,
+   * hashing the data first may present interoperability issues so choose
+   * wisely.
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.key - The key to use.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} An object containing `{signatureValue}`.
+   */
+  async sign({key, operation}) {
+    assert.object(key, 'options.key');
+    assert.object(operation, 'options.operation');
+
+    const {type} = key;
+    const op = getKeyOp({name: 'sign', type});
+    return op({key, operation});
+  }
+
+  /**
+   * Verifies some data. Note that the data will be sent to the server, so if
+   * this data is intended to be secret it should be hashed first. However,
+   * hashing the data first may present interoperability issues so choose
+   * wisely.
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.key - The key to use.
+   * @param {object} options.operation - The KMS operation.
+   *
+   * @returns {Promise<object>} An object containing `{verified}`.
+   */
+  async verify({key, operation}) {
+    assert.object(key, 'options.key');
+    assert.object(operation, 'options.operation');
+
+    const {type} = key;
+    const op = getKeyOp({name: 'verify', type});
+    return op({key, operation});
+  }
+
+  /**
+  * Derives a shared secret via the given peer public key, typically for use
+  * as one parameter for computing a shared key. It should not be used as
+  * a shared key itself, but rather input into a key derivation function (KDF)
+  * to produce a shared key.
+  *
+  * @param {object} options - The options to use.
+  * @param {object} options.key - The key to use.
+  * @param {object} options.operation - The KMS operation.
+  *
+  * @returns {Promise<object>} An object containing `{secret}`.
+  */
+  async deriveSecret({key, operation}) {
+    assert.object(key, 'options.key');
+    assert.object(operation, 'options.operation');
+
+    const {type} = key;
+    const op = getKeyOp({name: 'deriveSecret', type});
+    return op({key, operation});
+  }
+}

package/lib/core/aeskw.js

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import crypto from 'node:crypto';
+
+const AES_KW_ALGORITHM = 'id-aes256-wrap';
+const AES_KW_RFC3394_IV = Buffer.from('A6A6A6A6A6A6A6A6', 'hex');
+
+export async function unwrapKey({secretKey, wrapped} = {}) {
+  const decipher = crypto.createDecipheriv(
+    AES_KW_ALGORITHM, secretKey, AES_KW_RFC3394_IV);
+  return Buffer.concat([decipher.update(wrapped), decipher.final()]);
+}
+
+export async function wrapKey({secretKey, unwrapped} = {}) {
+  const cipher = crypto.createCipheriv(
+    AES_KW_ALGORITHM, secretKey, AES_KW_RFC3394_IV);
+  return Buffer.concat([cipher.update(unwrapped), cipher.final()]);
+}

package/lib/core/asymmetricKey.js

@@ -0,0 +1,145 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import * as base58 from 'base58-universal';
+import * as bedrock from '@bedrock/core';
+import * as Bls12381Multikey from '@digitalbazaar/bls12-381-multikey';
+import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
+import * as Ed25519Multikey from '@digitalbazaar/ed25519-multikey';
+
+const {util: {BedrockError}} = bedrock;
+
+const ED25519_2018_V1_URL =
+  'https://w3id.org/security/suites/ed25519-2018/v1';
+const ED25519_2020_V1_URL =
+  'https://w3id.org/security/suites/ed25519-2020/v1';
+
+/**
+ * Generates a new asymmetric key pair.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.keyId - The key ID to use.
+ * @param {object} options.type - The key type.
+ * @param {string} options.controller - The key controller.
+ *
+ * @returns {Promise<object>} An object containing `{key, keyDescription}`.
+ */
+export async function generateKey({keyId, type, controller} = {}) {
+  let keyPair;
+  if(type.includes('Ed25519')) {
+    keyPair = await Ed25519Multikey.generate({id: keyId});
+  } else if(type.startsWith('urn:webkms:multikey:P-')) {
+    const curve = type.slice('urn:webkms:multikey:'.length);
+    keyPair = await EcdsaMultikey.generate({id: keyId, curve});
+  } else if(type.startsWith('urn:webkms:multikey:BBS-') ||
+    type === 'urn:webkms:multikey:Bls12381G2') {
+    let algorithm = type.slice('urn:webkms:multikey:'.length);
+    if(algorithm === 'Bls12381G2') {
+      // default curve-as-algorithm to:
+      algorithm = 'BBS-BLS12-381-SHA-256';
+    }
+    keyPair = await Bls12381Multikey.generateBbsKeyPair(
+      {id: keyId, algorithm});
+  } else {
+    throw new BedrockError(`Unsupported key type "${type}".`, {
+      name: 'NotSupportedError',
+      details: {public: true, httpStatusCode: 400}
+    });
+  }
+
+  // generate full key portion for internal record
+  let key = await keyPair.export(
+    {publicKey: true, secretKey: true, includeContext: true});
+  key.type = type;
+
+  // generate public key description
+  let keyDescription = await keyPair.export({
+    publicKey: true, includeContext: true
+  });
+
+  // perform transform for legacy key types
+  if(type === 'Ed25519VerificationKey2020') {
+    key = {
+      '@context': ED25519_2020_V1_URL,
+      id: key.id,
+      type,
+      privateKeyMultibase: key.secretKeyMultibase,
+      publicKeyMultibase: key.publicKeyMultibase
+    };
+    keyDescription['@context'] = ED25519_2020_V1_URL;
+    keyDescription.type = type;
+  } else if(type === 'Ed25519VerificationKey2018') {
+    key = {
+      '@context': ED25519_2018_V1_URL,
+      id: key.id,
+      type,
+      privateKeyBase58: _multibaseMultikeyToBase58(key.secretKeyMultibase),
+      publicKeyBase58: _multibaseMultikeyToBase58(key.publicKeyMultibase)
+    };
+    keyDescription = {
+      '@context': ED25519_2018_V1_URL,
+      id: key.id,
+      type,
+      publicKeyBase58: key.publicKeyBase58,
+      controller
+    };
+  }
+
+  // consistently order key description properties
+  {
+    const {
+      ['@context']: context, id, type, ...rest
+    } = keyDescription;
+    keyDescription = {
+      '@context': context, id, type, ...rest, controller
+    };
+  }
+
+  return {key, keyDescription};
+}
+
+/**
+ * Signs some data. Note that the data will be sent to the server, so if
+ * this data is intended to be secret it should be hashed first. However,
+ * hashing the data first may present interoperability issues so choose
+ * wisely.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {object} options.key - The key to use.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<object>} Contains `{signatureValue}`.
+ */
+export async function sign({key, operation}) {
+  // prepare `key` for import
+  const {type} = key;
+  if(type.startsWith('urn:webkms:multikey:')) {
+    // import key as a `Multikey`
+    key = {...key, type: 'Multikey'};
+  }
+
+  let keyPair;
+  if(type.startsWith('urn:webkms:multikey:P-')) {
+    keyPair = await EcdsaMultikey.from(key);
+  } else if(type.startsWith('urn:webkms:multikey:BBS-') ||
+    type === 'urn:webkms:multikey:Bls12381G2') {
+    keyPair = await Bls12381Multikey.from(key);
+  } else {
+    keyPair = await Ed25519Multikey.from(key);
+  }
+
+  const {sign} = keyPair.signer();
+  const {verifyData} = operation;
+  const signatureBytes = await sign({
+    data: Buffer.from(verifyData, 'base64url')
+  });
+  return {signatureValue: Buffer.from(signatureBytes).toString('base64url')};
+}
+
+function _multibaseMultikeyToBase58(mb) {
+  // special transform for Ed25519 secret or public multibase multikey values
+  const mk = base58.decode(mb.slice(1));
+  return base58.encode(mk.slice(2));
+}

package/lib/core/hmacKey.js

@@ -0,0 +1,99 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import crypto from 'node:crypto';
+
+const SUPPORTED_KEY_TYPES = new Map([
+  ['Sha256HmacKey2019', 'https://w3id.org/security/suites/hmac-2019/v1']
+]);
+
+/**
+ * Generates a new HMAC key.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.keyId - The key ID to use.
+ * @param {string} options.type - A KEY_TYPE.
+ * @param {string} options.controller - The key controller.
+ *
+ * @returns {Promise<object>} An object containing `{key, keyDescription}`.
+ */
+export async function generateKey({keyId, type, controller} = {}) {
+  const keyContextUrl = SUPPORTED_KEY_TYPES.get(type);
+  if(!keyContextUrl) {
+    throw new Error(`Unknown key type "${type}".`);
+  }
+
+  const key = {
+    '@context': keyContextUrl,
+    id: keyId,
+    type,
+    secret: Buffer.from(crypto.randomBytes(32)).toString('base64url')
+  };
+
+  const keyDescription = {
+    '@context': keyContextUrl,
+    id: keyId,
+    type,
+    controller
+  };
+
+  return {key, keyDescription};
+}
+
+/**
+ * Signs some data. Note that the data will be sent to the server, so if
+ * this data is intended to be secret it should be hashed first. However,
+ * hashing the data first may present interoperability issues so choose
+ * wisely.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {object} options.key - The key to use.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<object>} Contains `{signatureValue}`.
+ */
+export async function sign({key, operation}) {
+  if(key.type !== 'Sha256HmacKey2019') {
+    throw new Error(`Unknown key type "${key.type}".`);
+  }
+  const {verifyData} = operation;
+  const signatureValue = await _hs256Sign({key, verifyData});
+  return {signatureValue: Buffer.from(signatureValue).toString('base64url')};
+}
+
+/**
+ * Verifies some data. Note that the data will be sent to the server, so if
+ * this data is intended to be secret it should be hashed first. However,
+ * hashing the data first may present interoperability issues so choose
+ * wisely.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {object} options.key - The key to use.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<object>} An object containing `{verified}`.
+ */
+export async function verify({key, operation}) {
+  if(key.type !== 'Sha256HmacKey2019') {
+    throw new Error(`Unknown key type "${key.type}".`);
+  }
+  const {signatureValue, verifyData} = operation;
+  const verified = await _hs256Verify({key, verifyData, signatureValue});
+  return {verified};
+}
+
+async function _hs256Sign({key, verifyData}) {
+  const secret = Buffer.from(key.secret, 'base64url');
+  const hmac = crypto.createHmac('sha256', secret);
+  hmac.update(Buffer.from(verifyData, 'base64url'));
+  return hmac.digest();
+}
+
+async function _hs256Verify({key, verifyData, signatureValue}) {
+  signatureValue = Buffer.from(signatureValue, 'base64url');
+  const signatureCheck = await _hs256Sign({key, verifyData});
+  return crypto.timingSafeEqual(signatureValue, signatureCheck);
+}

package/lib/core/index.js

@@ -0,0 +1,4 @@
+/*!
+ * Copyright (c) 2021-2026 Digital Bazaar, Inc.
+ */
+export {Core} from './Core.js';

package/lib/core/keyAgreementKey.js

@@ -0,0 +1,148 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import * as base58 from 'base58-universal';
+import * as bedrock from '@bedrock/core';
+import * as EcdsaMultikey from '@digitalbazaar/ecdsa-multikey';
+import {
+  X25519KeyAgreementKey2020
+} from '@digitalbazaar/x25519-key-agreement-key-2020';
+
+const {util: {BedrockError}} = bedrock;
+
+const MULTIKEY_CONTEXT_V1_URL = 'https://w3id.org/security/multikey/v1';
+
+const SUPPORTED_MULTIKEY_TYPES = new Map([
+  ['ec01', 'urn:webkms:multikey:X25519'],
+  ['8024', 'urn:webkms:multikey:ECDH-P-256'],
+  ['8124', 'urn:webkms:multikey:ECDH-P-384'],
+  ['8224', 'urn:webkms:multikey:ECDH-P-521']
+]);
+
+/**
+ * Generates a new key agreement key pair.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.keyId - The key ID to use.
+ * @param {object} options.type - The key type.
+ * @param {string} options.controller - The key controller.
+ *
+ * @returns {Promise<object>} An object containing `{key, keyDescription}`.
+ */
+export async function generateKey({keyId, type, controller} = {}) {
+  let keyPair;
+  if(type.startsWith('urn:webkms:multikey:ECDH-P-')) {
+    const curve = type.slice('urn:webkms:multikey:ECDH-'.length);
+    keyPair = await EcdsaMultikey.generate({
+      id: keyId, curve, keyAgreement: true
+    });
+  } else if(type.includes('X25519')) {
+    keyPair = await X25519KeyAgreementKey2020.generate({id: keyId});
+  } else {
+    throw new BedrockError(`Unsupported key type "${type}".`, {
+      name: 'NotSupportedError',
+      details: {public: true, httpStatusCode: 400}
+    });
+  }
+
+  // generate full key portion for internal record
+  const key = await keyPair.export(
+    {publicKey: true, privateKey: true, secretKey: true, includeContext: true});
+  key.type = type;
+
+  // generate public key description
+  let keyDescription = await keyPair.export({
+    publicKey: true, includeContext: true
+  });
+
+  // special handling for `X25519` Multikey
+  if(type == 'urn:webkms:multikey:X25519') {
+    key['@context'] = MULTIKEY_CONTEXT_V1_URL;
+    key.secretKeyMultibase = key.privateKeyMultibase;
+    delete key.privateKeyMultibase;
+    keyDescription['@context'] = MULTIKEY_CONTEXT_V1_URL;
+    keyDescription.type = 'Multikey';
+  }
+
+  // consistently order key description properties
+  {
+    const {
+      ['@context']: context, id, type, ...rest
+    } = keyDescription;
+    keyDescription = {
+      '@context': context, id, type, ...rest, controller
+    };
+  }
+
+  return {key, keyDescription};
+}
+
+/**
+ * Signs some data. Note that the data will be sent to the server, so if
+ * this data is intended to be secret it should be hashed first. However,
+ * hashing the data first may present interoperability issues so choose
+ * wisely.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {object} options.key - Exported key pair record, loaded from storage.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<{secret: string}>} Resolves with the derived secret.
+ */
+export async function deriveSecret({key, operation}) {
+  const {publicKey} = operation;
+  const type = publicKey.type === 'Multikey' ?
+    _parseMultikey(publicKey.publicKeyMultibase) : publicKey.type;
+  if(type !== key.type) {
+    throw Error(
+      `The given public key type "${type}" does not match the ` +
+      `key agreement key's type "${key.type}".`);
+  }
+
+  let keyPair;
+  if(key.type.includes('X25519')) {
+    // special handling for `X25519` Multikey
+    if(type === 'urn:webkms:multikey:X25519') {
+      key = {
+        ...key,
+        privateKeyMultibase: key.secretKeyMultibase
+      };
+    }
+    keyPair = await X25519KeyAgreementKey2020.from(key);
+  } else {
+    // import `key` as a `Multikey`
+    keyPair = await EcdsaMultikey.from(
+      {...key, type: 'Multikey'}, {keyAgreement: true});
+  }
+
+  const secret = await keyPair.deriveSecret({publicKey});
+  return {secret: Buffer.from(secret).toString('base64url')};
+}
+
+function _parseMultikey(mb) {
+  let multikey;
+  const mbHeader = mb?.[0];
+  if(mbHeader === 'z') {
+    multikey = base58.decode(mb.slice(1));
+  } else if(mbHeader === 'u') {
+    multikey = Buffer.from(mb.slice(1), 'base64url');
+  } else {
+    throw new BedrockError(`Unsupported multibase header "${mbHeader}".`, {
+      name: 'NotSupportedError',
+      details: {public: true, httpStatusCode: 400}
+    });
+  }
+
+  const header = Buffer.from(multikey.subarray(0, 2)).toString('hex');
+  const type = SUPPORTED_MULTIKEY_TYPES.get(header);
+  if(!type) {
+    throw new BedrockError(`Unsupported multikey header "${header}".`, {
+      name: 'NotSupportedError',
+      details: {public: true, httpStatusCode: 400}
+    });
+  }
+
+  return type;
+}

package/lib/core/operations.js

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+*/
+import * as _asymmetricKey from './asymmetricKey.js';
+import * as _hmacKey from './hmacKey.js';
+import * as _keyAgreementKey from './keyAgreementKey.js';
+import * as _wrapKey from './wrapKey.js';
+
+const OPERATIONS = new Map([
+  // asymmetric keys
+  ['Ed25519VerificationKey2018', _asymmetricKey],
+  ['Ed25519VerificationKey2020', _asymmetricKey],
+  ['urn:webkms:multikey:Ed25519', _asymmetricKey],
+  ['urn:webkms:multikey:P-256', _asymmetricKey],
+  ['urn:webkms:multikey:P-384', _asymmetricKey],
+  ['urn:webkms:multikey:P-521', _asymmetricKey],
+  ['urn:webkms:multikey:BBS-BLS12-381-SHA-256', _asymmetricKey],
+  ['urn:webkms:multikey:BBS-BLS12-381-SHAKE-256', _asymmetricKey],
+  ['urn:webkms:multikey:Bls12381G2', _asymmetricKey],
+  // key agreement keys
+  ['X25519KeyAgreementKey2020', _keyAgreementKey],
+  ['urn:webkms:multikey:X25519', _keyAgreementKey],
+  ['urn:webkms:multikey:ECDH-P-256', _keyAgreementKey],
+  ['urn:webkms:multikey:ECDH-P-384', _keyAgreementKey],
+  ['urn:webkms:multikey:ECDH-P-521', _keyAgreementKey],
+  // wrapping keys
+  ['AesKeyWrappingKey2019', _wrapKey],
+  // hmac keys
+  ['Sha256HmacKey2019', _hmacKey],
+]);
+
+export function getKeyOp({name, type}) {
+  const ops = OPERATIONS.get(type);
+  if(!ops) {
+    throw new Error(`Unknown key type "${type}".`);
+  }
+  const op = ops[name];
+  if(!op) {
+    throw new Error(`Unsupported operation "${name}" for key type "${type}".`);
+  }
+  return op;
+}

package/lib/core/wrapKey.js

@@ -0,0 +1,89 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import {unwrapKey as aesUnwrapKey, wrapKey as aesWrapKey} from './aeskw.js';
+import crypto from 'node:crypto';
+
+const SUPPORTED_KEY_TYPES = new Map([
+  ['AesKeyWrappingKey2019', 'https://w3id.org/security/suites/aes-2019/v1']
+]);
+
+/**
+ * Generates a new wraping key.
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.keyId - The key ID to use.
+ * @param {string} options.type - A KEY_TYPE.
+ * @param {string} options.controller - The key controller.
+ *
+ * @returns {Promise<object>} An object containing `{key, keyDescription}`.
+ */
+export async function generateKey({keyId, type, controller} = {}) {
+  const keyContextUrl = SUPPORTED_KEY_TYPES.get(type);
+  if(!keyContextUrl) {
+    throw new Error(`Unknown key type "${type}".`);
+  }
+
+  const key = {
+    '@context': keyContextUrl,
+    id: keyId,
+    type,
+    secret: Buffer.from(crypto.randomBytes(32)).toString('base64url')
+  };
+
+  const keyDescription = {
+    '@context': keyContextUrl,
+    id: keyId,
+    type,
+    controller
+  };
+
+  return {key, keyDescription};
+}
+
+/**
+ * Wraps a cryptographic key using a key encryption key (KEK).
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.kek - The key encryption key to use.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<object>} An object containing `{wrappedKey}`.
+ */
+export async function wrapKey({kek, operation}) {
+  const {unwrappedKey} = operation;
+  const wrappedKey = await _aesWrapKey({kek, unwrappedKey});
+  return {wrappedKey};
+}
+
+/**
+ * Unwraps a cryptographic key using a key encryption key (KEK).
+ *
+ * @ignore
+ * @param {object} options - The options to use.
+ * @param {string} options.kek - The key encryption key to use.
+ * @param {object} options.operation - The KMS operation.
+ *
+ * @returns {Promise<object>} An object containing `{unwrappedKey}`.
+ */
+export async function unwrapKey({kek, operation}) {
+  const {wrappedKey} = operation;
+  const unwrappedKey = await _aesUnwrapKey({kek, wrappedKey});
+  return {unwrappedKey};
+}
+
+async function _aesWrapKey({kek, unwrappedKey}) {
+  const unwrapped = Buffer.from(unwrappedKey, 'base64url');
+  const secretKey = Buffer.from(kek.secret, 'base64url');
+  const output = await aesWrapKey({secretKey, unwrapped});
+  return Buffer.from(output).toString('base64url');
+}
+
+async function _aesUnwrapKey({kek, wrappedKey}) {
+  const wrapped = Buffer.from(wrappedKey, 'base64url');
+  const secretKey = Buffer.from(kek.secret, 'base64url');
+  const output = await aesUnwrapKey({secretKey, wrapped});
+  return Buffer.from(output).toString('base64url');
+}

package/lib/index.js

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import {KmsModule} from './KmsModule.js';
+
+export {Core} from './core/index.js';
+
+/**
+ * Generates a KMS module interface that uses the given `Core` interface,
+ * `core`, and `KeyStorage` interface, `keyStorage`.
+ *
+ * @param {object} options - The options to use.
+ * @param {Core} options.core - The `Core` interface to use.
+ * @param {KeyStorage} options.keyStorage - The `KeyStorage` interface to use.
+ *
+ * @returns {Promise<object>} An object with `{kmsModule, api}`.
+ */
+export function createKmsModule({core, keyStorage} = {}) {
+  const kmsModule = new KmsModule({core, keyStorage});
+  const descriptors = Object.getOwnPropertyDescriptors(KmsModule.prototype);
+  const apiEntries = [];
+  for(const [name, descriptor] of Object.entries(descriptors)) {
+    if(typeof descriptor.value !== 'function' || name === 'constructor') {
+      continue;
+    }
+    apiEntries.push([name, descriptor.value.bind(kmsModule)]);
+  }
+  const api = Object.fromEntries(apiEntries);
+  return {kmsModule, api};
+}
+
+/**
+ * An interface with WebKMS core functions.
+ *
+ * @typedef {object} Core
+ * @property {Function} generateKey
+ * @property {Function} getKeyDescription
+ * @property {Function} wrapKey
+ * @property {Function} unwrapKey
+ * @property {Function} sign
+ * @property {Function} verify
+ * @property {Function} deriveSecret
+ */
+
+/**
+ * An interface for storing WebKMS keys.
+ *
+ * @typedef {object} KeyStorage
+ * @property {Function} insert
+ * @property {Function} getCount
+ * @property {Function} get
+ */

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@bedrock/kms-module-core",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Bedrock WebKMS module core",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "main": "./lib/index.js",
+  "files": [
+    "lib/**/*.js"
+  ],
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitalbazaar/bedrock-kms-module-core"
+  },
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "https://digitalbazaar.com"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/bedrock-kms-module-core/issues"
+  },
+  "homepage": "https://github.com/digitalbazaar/bedrock-kms-module-core",
+  "dependencies": {
+    "@digitalbazaar/bls12-381-multikey": "^2.1.0",
+    "@digitalbazaar/ecdsa-multikey": "^1.8.0",
+    "@digitalbazaar/ed25519-multikey": "^1.3.1",
+    "@digitalbazaar/x25519-key-agreement-key-2020": "^3.0.1",
+    "assert-plus": "^1.0.0",
+    "base58-universal": "^2.0.0",
+    "url-template": "^3.1.1"
+  },
+  "peerDependencies": {
+    "@bedrock/core": "^6.3.0",
+    "@bedrock/kms-module-key-storage": "^1.2.0",
+    "@bedrock/mongodb": "^11.0.1",
+    "@bedrock/record-cipher": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "eslint-config-digitalbazaar": "^5.2.0",
+    "eslint-plugin-jsdoc": "^50.6.3",
+    "eslint-plugin-unicorn": "^56.0.1",
+    "jsdoc": "^4.0.4",
+    "jsdoc-to-markdown": "^9.1.1"
+  }
+}