@bedrock/kms-http 13.0.0

package/README.md

@@ -0,0 +1,292 @@
+# Bedrock Key Management System API module _(bedrock-kms-http)_
+> HTTP APIs for Bedrock Key Management.
+
+## Table of Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Contribute](#contribute)
+- [Commercial Support](#commercial-support)
+- [License](#license)
+
+## Install
+
+- Node.js 12+ is required.
+
+### NPM
+
+To install via NPM:
+
+```
+npm install --save bedrock-kms-http
+```
+
+### Development
+
+To install locally (for development):
+
+```
+git clone https://github.com/digitalbazaar/bedrock-kms-http.git
+cd bedrock-kms-http
+npm install
+```
+
+## Usage
+
+In `lib/index.js` (or `main.js`, as appropriate):
+
+```js
+import 'bedrock-kms-http';
+```
+
+### KMS HTTP API
+
+This module exposes the following API endpoints.
+
+#### Create a Keystore - `POST /kms/keystores`
+
+#### Request Example:
+```
+{
+  sequence: 0,
+  controller: 'did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54',
+  meterId: 'https://localhost:18443/meters/z3pYurSyUQ5BTBcahRKuzri',
+  kmsModule: 'ssm-v1'
+}
+```
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores",action="write"',
+  digest: 'mh=uEiAWwH_YYtljJn-tba5XZ_s5k9lcFoJW9Mg8EdPY3ShEvQ',
+  'content-type': 'application/json',
+  authorization: 'Signature keyId="did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54#z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54",headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",signature="hTFuyAyfdwmTRJ1DmK2AVgDZ+RCQYsc5n9YF///5t4QY3VaTtUGWRDWQHRTSMGHybda782fCW9XczmIJEMfFDQ==",created="1638504433",expires="1638505033"'
+}
+```
+
+#### Response Example:
+```
+{
+  id: 'https://localhost:18443/kms/keystores/z1AByGXEmfZnyG8rgM3aVpYxG',
+  meterId: 'https://localhost:18443/meters/z3pYurSyUQ5BTBcahRKuzri',
+  sequence: 0,
+  controller: 'did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54',
+  kmsModule: 'ssm-v1'
+}
+```
+
+#### Update Keystore Config - `POST /kms/keystores/:keystoreId`
+
+#### Request Example:
+```
+{
+  controller: 'did:key:z6MknP29cPcQ7G76MWmnsuEEdeFya8ij3fXvJcTJYLXadmp9',
+  id: 'https://localhost:18443/kms/keystores/z19xPXyqB3dnqKZ7BtVFvqSLH',
+  sequence: 1
+}
+```
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz19xPXyqB3dnqKZ7BtVFvqSLH",action="write"',
+  digest: 'mh=uEiDiFdv-C0VNNIvltnoIxwqUA5crG1H42OyvQtPRa7mjvw',
+  'content-type': 'application/json',
+  authorization: 'Signature keyId="did:key:z6MkqnGN2jgckeejguN28RE1SM5a1rwu9nigkY5PhSQuTybX#z6MkqnGN2jgckeejguN28RE1SM5a1rwu9nigkY5PhSQuTybX",headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",signature="6i3yXShQMQ8H+XFJpUEi0WcO7hcrcpdApuyU2WrSAm0bMuAby+pZKSt+ACBWRrpocEaxAa6lwefvtGVYVXO7BQ==",created="1638505029",expires="1638505629"'
+}
+```
+
+#### Response Example:
+```
+{
+  success: true,
+  config: {
+    controller: 'did:key:z6MknP29cPcQ7G76MWmnsuEEdeFya8ij3fXvJcTJYLXadmp9',
+    id: 'https://localhost:18443/kms/keystores/z19xPXyqB3dnqKZ7BtVFvqSLH',
+    sequence: 1,
+    meterId: 'https://localhost:18443/meters/zD3E9XJxyUUuJ5ZW14EhCFy',
+    kmsModule: 'ssm-v1'
+  }
+}
+```
+
+#### Get Keystore Config - `GET /kms/keystores/:keystoreId`
+
+#### Request Example:
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz1A2Dahs56An4rttS3t2QKi69",action="read"',
+  authorization: 'Signature keyId="did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54#z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54",headers="(key-id) (created) (expires) (request-target) host capability-invocation",signature="P8ZYsAO/oQPllqRCW4GJdKwHhGfk53li88pzySd2jJVhNJCkxwPVNTGS0CsK/tK1cLvwjUABUqO2VUlP//T3DA==",created="1638505290",expires="1638505890"'
+}
+```
+
+#### Response Example:
+```
+{
+  id: 'https://localhost:18443/kms/keystores/z1A2Dahs56An4rttS3t2QKi69',
+  meterId: 'https://localhost:18443/meters/zC3vXcEbC3iYEntNVZxvq6E',
+  sequence: 0,
+  controller: 'did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54',
+  kmsModule: 'ssm-v1'
+}
+```
+
+#### Generate a new Key - `POST /kms/keystores/:keystoreId/keys`
+
+#### Request Example:
+```
+{
+  '@context': [
+    'https://w3id.org/webkms/v1',
+    'https://w3id.org/security/suites/ed25519-2020/v1'
+  ],
+  type: 'GenerateKeyOperation',
+  invocationTarget: { type: 'Ed25519VerificationKey2020' }
+}
+```
+
+#### Headers:
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz19mH7zKauTKBWS3831MyWM2f",action="generateKey"',
+  digest: 'mh=uEiC4fs8V2JzjgB25wxRhyKGc17b0yu-JvjnYF6IutYMEzQ',
+  'content-type': 'application/json',
+  authorization: 'Signature keyId="did:key:z6MkoSN3SbRHZAFdYwphhgHhuLXdBCMu7Yoam5H436b1PZAp#z6MkoSN3SbRHZAFdYwphhgHhuLXdBCMu7Yoam5H436b1PZAp",headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",signature="fntyQjEsGMIOwh7OftKS76yJ/1wpx+3eVWJjIToqcfJPOlmuU3DZmbag4bZ3cw3weLg4kDYQNxsJ8nNVtpd4DQ==",created="1638506601",expires="1638507201"'
+}
+```
+#### Response Example:
+```
+{
+  id: 'https://localhost:18443/kms/keystores/z19mH7zKauTKBWS3831MyWM2f/keys/z1A3XvbwPFZ5WceoeXcQMzBZ5',
+  type: 'Ed25519VerificationKey2020',
+  '@context': 'https://w3id.org/security/suites/ed25519-2020/v1',
+  publicKeyMultibase: 'z6MknYsXcwi19ohJKGu5RHzxAkyVDGCP3ggpHY2FqxNFFyZb'
+}
+```
+
+#### Invoke KMS Operation on Existing Key - `POST /kms/keystores/:keystoreId/keys/:keyId`
+
+#### Request Example:
+```
+{
+  '@context': 'https://w3id.org/webkms/v1',
+  type: 'SignOperation',
+  invocationTarget: 'https://localhost:18443/kms/keystores/z19zhh4xhWEeBn7u5NXQaeU2e/keys/z1A4nmgJS9XkDAsDDHFhAEba3',
+  verifyData: 'aGVsbG8'
+}
+```
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz19zhh4xhWEeBn7u5NXQaeU2e",action="sign"',
+  digest: 'mh=uEiADFF5OnUq5SCTrVVBSAMP5DpXfSF7f1bIH-SrX6S9Fdw',
+  'content-type': 'application/json',
+  authorization: 'Signature keyId="did:key:z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54#z6MkoyZVQSetDxU66AsfinUPzgSEu5N9Jf1anHEY4YCzcE54",headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",signature="upDUCqfbaIqixWmFjnHq/NIY2/r5TserYAQMOEkiwoUIyHgww/auN+cMYqH7x23cmymfmDIlDqqoE+Pi06j+AQ==",created="1638508033",expires="1638508633"'
+}
+```
+
+
+#### Response Example:
+```
+{ signatureValue: 'qtL549jF562rlea6oQBzIKYCZeOPFX9OBzmn3iSzOpI' }
+```
+
+#### Get Public Key Description - `GET /kms/keystores/:keystoreId/keys/:keyId`
+
+#### Request Example:
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz1AEdRUJm7Ld4xBNBKkAGHjzZ%2Fkeys%2Fz1A5vBtppSSaS1svFyQb6Ezwj",action="read"',
+  authorization: 'Signature keyId="did:key:z6MkhRjrvpEAxh8oSWsPgMdP28xvrotsDBCvcwTtbUuUEp38#z6MkhRjrvpEAxh8oSWsPgMdP28xvrotsDBCvcwTtbUuUEp38",headers="(key-id) (created) (expires) (request-target) host capability-invocation",signature="gmB9DXTu29QKO4FlHXcEJGHMjaRpvXosRw+KeShiDB9YU2kwjMdd7eMT15TgeKzN3K5eqbEyEWh0NCgT/ULFAA==",created="1638539438",expires="1638540038"'
+}
+```
+
+#### Response Example:
+```
+{
+  '@context': 'https://w3id.org/security/suites/ed25519-2020/v1',
+  id: 'https://localhost:18443/kms/keystores/z1AEdRUJm7Ld4xBNBKkAGHjzZ/keys/z1A5vBtppSSaS1svFyQb6Ezwj',
+  type: 'Ed25519VerificationKey2020',
+  publicKeyMultibase: 'z6MkuP4PkTPZy2KvictPAsAHAbH6Umw9tsRJzmpGR65brddP'
+}
+```
+
+#### Insert a Revocation - `POST /kms/keystores/:keystoreId/revocations/:zcapId`
+
+#### Request Example:
+```
+{
+  '@context': [
+    'https://w3id.org/zcap/v1',
+    'https://w3id.org/security/suites/ed25519-2020/v1'
+  ],
+  id: 'urn:zcap:38c42aff-76e0-4624-88dc-0341fe3f9ccd',
+  invoker: 'did:key:z6MkootHWoSfwsPz1E3pE3aALJCEiawN1XNf4CPoUNeUEgY8#z6MkootHWoSfwsPz1E3pE3aALJCEiawN1XNf4CPoUNeUEgY8',
+  parentCapability: 'urn:zcap:45bbf83c-bb97-474d-9a54-f4dac1e257ad',
+  allowedAction: 'sign',
+  invocationTarget: {
+    publicAlias: 'did:key:z6Mkf8beJEDMQM77i12Siuw8UwuidEin6qvUQH65EBs3VqcW#z6Mkf8beJEDMQM77i12Siuw8UwuidEin6qvUQH65EBs3VqcW',
+    id: 'https://localhost:18443/kms/keystores/z19zzGxGeo6Z4FhqhP1ZJZhNp/keys/z19qdYFKqymy8BoPpdfSkeRrZ',
+    type: 'Ed25519VerificationKey2020'
+  },
+  proof: {
+    type: 'Ed25519Signature2020',
+    created: '2021-12-03T00:54:36Z',
+    verificationMethod: 'did:key:z6MkfrMHgiLotA5tX5JqtmQw1WmtmHCay7eY651TQzKdHAcB#z6MkfrMHgiLotA5tX5JqtmQw1WmtmHCay7eY651TQzKdHAcB',
+    proofPurpose: 'capabilityDelegation',
+    capabilityChain: [
+      'urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz19zzGxGeo6Z4FhqhP1ZJZhNp',
+      [Object]
+    ],
+    proofValue: 'z5UMPNnR2sXv5tZ4XVrRjGqwh6zPchrcNBgedXDS4XEnSgeQAFEuiAx89nUcxDZV2e2Tb17cZKoLvyvSdRorKHoHw'
+  }
+}
+```
+
+#### Headers
+```
+{
+  accept: 'application/ld+json, application/json',
+  host: 'localhost:18443',
+  'capability-invocation': 'zcap id="urn:zcap:root:https%3A%2F%2Flocalhost%3A18443%2Fkms%2Fkeystores%2Fz1ADWeUn1vp2oTr33SaSoiiDj%2Frevocations%2Furn%253Azcap%253A61f9fce0-595d-4763-9854-c5db561e6981",action="write"',
+  digest: 'mh=uEiCQYBu8dlESvD_MO4VxN3FcJMuSRg1HRh3B-ciaEHpsxQ',
+  'content-type': 'application/json',
+  authorization: 'Signature keyId="did:key:z6MkprpMfcYbjbCmhb84TWwhkwevqTX67EQvd7bdLTJ3DkA6#z6MkprpMfcYbjbCmhb84TWwhkwevqTX67EQvd7bdLTJ3DkA6",headers="(key-id) (created) (expires) (request-target) host capability-invocation content-type digest",signature="Z5DUpumlZYK3UplUDjz4szzWf+XO3zHd/Y6/wPMtUQn+7ZxNoLRa7Ny589CNASxYS7kg9Hv9KDF+R8wtiCJhAg==",created="1638492060",expires="1638492660"'
+}
+```
+
+## Contribute
+
+See [the contribute file](https://github.com/digitalbazaar/bedrock/blob/master/CONTRIBUTING.md)!
+
+PRs accepted.
+
+If editing the Readme, please conform to the
+[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
+## Commercial Support
+
+Commercial support for this library is available upon request from
+Digital Bazaar: support@digitalbazaar.com
+
+## License
+
+[Bedrock Non-Commercial License v1.0](LICENSE.md) © Digital Bazaar

package/lib/BedrockKeystoreConfigStorage.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import * as helpers from './helpers.js';
+import {createRequire} from 'module';
+import {keystores} from '@bedrock/kms';
+const require = createRequire(import.meta.url);
+const {KeystoreConfigStorage} = require('@digitalbazaar/webkms-switch');
+
+const {util: {BedrockError}} = bedrock;
+
+// load config defaults
+import './config.js';
+
+export class BedrockKeystoreConfigStorage extends KeystoreConfigStorage {
+  async get({id, req} = {}) {
+    const {config: keystoreConfig} = await keystores.get({id});
+
+    // skip request checks if specifically requested
+    if(req === false) {
+      return keystoreConfig;
+    }
+
+    // verify that request is from an IP that is allowed to access the config
+    const {verified} = helpers.verifyRequestIp({keystoreConfig, req});
+    if(!verified) {
+      throw new BedrockError(
+        'Permission denied. Source IP is not allowed.', 'NotAllowedError', {
+          httpStatusCode: 403,
+          public: true,
+        });
+    }
+
+    return keystoreConfig;
+  }
+}

package/lib/config.js

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import {config} from '@bedrock/core';
+import '@bedrock/app-identity';
+import '@bedrock/meter-usage-reporter';
+import '@bedrock/validation';
+
+const namespace = 'kms-http';
+const cfg = config[namespace] = {};
+
+const basePath = '/kms';
+cfg.routes = {
+  basePath
+};
+
+// storage size to report to meter service
+cfg.storageCost = {
+  revocation: 1
+};
+
+// create dev application key for webkms (must be overridden in deployments)
+// ...and `ensureConfigOverride` has already been set via
+// `bedrock-app-identity` so it doesn't have to be set here
+config['app-identity'].seeds.services.webkms = {
+  id: 'did:key:z6MkwZ7AXrDpuVi5duY2qvVSx1tBkGmVnmRjDvvwzoVnAzC4',
+  seedMultibase: 'z1AWrfBoQx1mbiWBfWT7eksbtJf91v2pvEpwhoHDzezfaiH',
+  serviceType: 'webkms'
+};
+
+cfg.kmsOperationOptions = {
+  maxChainLength: 10,
+  // 300 second clock skew permitted by default
+  maxClockSkew: 300,
+  // 1000 year max TTL by default
+  maxDelegationTtl: 1000 * 60 * 60 * 24 * 365 * 1000
+};

package/lib/helpers.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import forwarded from 'forwarded';
+import {Netmask} from 'netmask';
+
+export function getKeystoreId({host, req, localId, routes}) {
+  if(!host) {
+    host = req.get('host');
+  }
+  return `https://${host}${routes.keystores}/${localId}`;
+}
+
+export function verifyRequestIp({keystoreConfig, req}) {
+  const {ipAllowList} = keystoreConfig;
+  if(!ipAllowList) {
+    return {verified: true};
+  }
+
+  // the first IP in the sourceAddresses array will *always* be the IP
+  // reported by Express.js via `req.connection.remoteAddress`. Any additional
+  // IPs will be from the `x-forwarded-for` header.
+  const sourceAddresses = forwarded(req);
+
+  // ipAllowList is an array of CIDRs
+  for(const cidr of ipAllowList) {
+    const netmask = new Netmask(cidr);
+    for(const address of sourceAddresses) {
+      if(netmask.contains(address)) {
+        return {verified: true};
+      }
+    }
+  }
+
+  return {verified: false};
+}

package/lib/http.js

@@ -0,0 +1,263 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import * as brZCapStorage from '@bedrock/zcap-storage';
+import * as helpers from './helpers.js';
+import * as middleware from './middleware.js';
+import {asyncHandler} from '@bedrock/express';
+import cors from 'cors';
+import {createRequire} from 'module';
+import {createValidateMiddleware as validate} from '@bedrock/validation';
+import {
+  defaultModuleManager as moduleManager,
+  keystores
+} from '@bedrock/kms';
+import {meters} from '@bedrock/meter-usage-reporter';
+import {
+  postKeystoreBody,
+  updateKeystoreConfigBody,
+  postRevocationBody
+} from '../schemas/bedrock-kms-http.js';
+import {reportOperationUsage, SERVICE_TYPE} from './metering.js';
+const require = createRequire(import.meta.url);
+const {generateRandom} = require('@digitalbazaar/webkms-switch');
+
+const {config, util: {BedrockError}} = bedrock;
+
+bedrock.events.on('bedrock-express.configure.routes', app => {
+  const cfg = config['kms-http'];
+
+  // get storage cost for low-level primitives of keystores and keys as well
+  // as higher-level revoked zcaps
+  const storageCost = {
+    ...config.kms.storageCost,
+    ...cfg.storageCost
+  };
+
+  // WebKMS paths are fixed off of the base path per the spec
+  const routes = {...cfg.routes};
+  routes.keystores = `${routes.basePath}/keystores`;
+  routes.keystore = `${routes.keystores}/:keystoreId`;
+  routes.keys = `${routes.keystore}/keys`;
+  routes.key = `${routes.keys}/:keyId`;
+  routes.revocations = `${routes.keystore}/zcaps/revocations/:revocationId`;
+
+  // create middleware for handling KMS operations
+  const handleOperation = middleware.createKmsOperationMiddleware();
+
+  // create middleware for getting consistent view of the keystore config
+  // associated with a request
+  const getKeystoreConfig = middleware.createGetKeystoreConfig({routes});
+
+  /* Note: CORS is used on all endpoints. This is safe because authorization
+  uses HTTP signatures + capabilities, not cookies; CSRF is not possible. */
+
+  // create a new keystore
+  app.options(routes.keystores, cors());
+  app.post(
+    routes.keystores,
+    cors(),
+    validate({bodySchema: postKeystoreBody}),
+    // meter must be checked for available usage and to obtain the meter's
+    // controller prior to checking the zcap invocation (as the invocation
+    // will use the meter's controller as the root controller for keystore
+    // creation)
+    asyncHandler(async (req, res, next) => {
+      const {body: {meterId: id}} = req;
+      const {meter, hasAvailable} = await meters.hasAvailable({
+        id, serviceType: SERVICE_TYPE,
+        resources: {storage: storageCost.keystore}
+      });
+      // store meter information on `req` and call next middleware
+      req.meterCheck = {meter, hasAvailable};
+      next();
+    }),
+    // now that meter information has been obtained, authorize zcap invocation
+    middleware.authorizeZcapInvocation({
+      async getExpectedValues() {
+        const expectedHost = config.server.host;
+        return {
+          host: expectedHost,
+          // expect root invocation target to match this route; the root zcap
+          // will have its controller dynamically set to the controller of the
+          // meter used as below in `getRootController`
+          rootInvocationTarget: `https://${expectedHost}${routes.keystores}`
+        };
+      },
+      async getRootController({req}) {
+        // use meter's controller as the root controller for the keystore
+        // creation endpoint
+        return req.meterCheck.meter.controller;
+      }
+    }),
+    asyncHandler(async (req, res) => {
+      const {body: {meterId}, meterCheck: {hasAvailable}} = req;
+      if(!hasAvailable) {
+        // insufficient remaining storage
+        throw new BedrockError('Permission denied.', 'NotAllowedError', {
+          httpStatusCode: 403,
+          public: true,
+        });
+      }
+
+      // FIXME: this is a high-latency call -- consider adding the meter
+      // in parallel with inserting the keystore, optimistically presuming it
+      // will be added; we could decide that the case of a missing/invalid
+      // meter is a possible state we have to deal in other cases anyway
+      // https://github.com/digitalbazaar/bedrock-kms-http/issues/57
+
+      // add meter
+      await meters.upsert({id: meterId, serviceType: SERVICE_TYPE});
+
+      // create a keystore for the controller
+      const random = await generateRandom();
+      const id = helpers.getKeystoreId({req, localId: random, routes});
+      const config = {id, meterId, ...req.body};
+      const record = await keystores.insert({config});
+      res.status(201).location(id).json(record.config);
+    }));
+
+  // update keystore config
+  app.options(routes.keystore, cors());
+  app.post(
+    routes.keystore,
+    cors(),
+    validate({bodySchema: updateKeystoreConfigBody}),
+    getKeystoreConfig,
+    // FIXME: if a new meter is sent, set the root controller to be that of
+    // the meter; otherwise set it to be that of the keystore
+    middleware.authorizeKeystoreZcapInvocation(),
+    asyncHandler(async (req, res) => {
+      const {body: config} = req;
+      const {keystore: existingConfig} = req.webkms;
+      if(existingConfig.id !== config.id) {
+        throw new BedrockError(
+          'Configuration "id" does not match request URL.',
+          'URLMismatchError', {
+            httpStatusCode: 400,
+            public: true,
+            requestUrl: existingConfig.id,
+            configId: config.id,
+            expected: existingConfig.id,
+            actual: config.id
+          });
+      }
+
+      // add meter if a new one was given
+      let {meterId} = config;
+      if(meterId && meterId !== existingConfig.meterId) {
+        // FIXME: only enable once root controller FIXME is addressed above
+        // for the case where a new meter is sent
+        throw new Error('Not implemented; meter cannot be changed.');
+        // await meters.upsert({id: meterId, serviceType: SERVICE_TYPE});
+      } else {
+        ({meterId} = existingConfig);
+      }
+
+      // ensure `meterId` is set on config (using either existing one or new
+      // one)
+      config.meterId = meterId;
+
+      // ensure `kmsModule` is set; if already set, allow `update` to proceed
+      // as it will throw an error if it does not match the existing config
+      if(!config.kmsModule) {
+        config.kmsModule = existingConfig.kmsModule;
+      }
+
+      // the `update` API will not apply the change and will throw if
+      // `config.sequence` is not valid, no need to check it here
+      await keystores.update({config});
+
+      // return new config
+      res.json({config});
+
+      // report updating config as operation usage
+      reportOperationUsage({req});
+    }));
+
+  // get a keystore config
+  app.get(
+    routes.keystore,
+    cors(),
+    getKeystoreConfig,
+    middleware.authorizeKeystoreZcapInvocation(),
+    asyncHandler(async (req, res) => {
+      res.json(req.webkms.keystore);
+    }));
+
+  // invoke a generate key KMS operation to generate a new key
+  app.options(routes.keys, cors());
+  app.post(
+    routes.keys,
+    cors(),
+    handleOperation);
+
+  // invoke KMS operation on an existing key
+  app.options(routes.key, cors());
+  app.post(
+    routes.key,
+    cors(),
+    handleOperation);
+
+  // TODO: consider whether this should be exposed w/o authorization
+  // https://github.com/digitalbazaar/bedrock-kms-http/issues/56
+
+  // return a (public) key description
+  app.get(
+    routes.key,
+    cors(),
+    getKeystoreConfig,
+    asyncHandler(async (req, res) => {
+      const {webkms: {keystore}} = req;
+      const keyId = `${keystore.id}/keys/${req.params.keyId}`;
+      const moduleApi = await moduleManager.get({id: keystore.kmsModule});
+      const keyDescription = await moduleApi.getKeyDescription({
+        keyId, controller: keystore.controller
+      });
+      res.json(keyDescription);
+    }));
+
+  // insert a revocation
+  app.options(routes.revocations, cors());
+  app.post(
+    routes.revocations,
+    cors(),
+    validate({bodySchema: postRevocationBody}),
+    getKeystoreConfig,
+    middleware.authorizeZcapRevocation(),
+    asyncHandler(async (req, res) => {
+      const {
+        body: capability,
+        webkms: {keystore},
+        zcapRevocation: {delegator}
+      } = req;
+
+      // check meter revocation usage; but only check to see if the meter
+      // is disabled or not; allow storage overflow with revocations to
+      // ensure security can be locked down; presumption is this endpoint
+      // will be heavily rate limited
+      const {meterId} = keystore;
+      const {meter: {disabled}} = await meters.hasAvailable({
+        id: meterId, serviceType: SERVICE_TYPE,
+        resources: {storage: cfg.storageCost.revocation}
+      });
+      if(disabled) {
+        // meter is disabled, do not allow storage
+        throw new BedrockError('Permission denied.', 'NotAllowedError', {
+          httpStatusCode: 403,
+          public: true,
+        });
+      }
+
+      // record revocation
+      await brZCapStorage.revocations.insert(
+        {delegator, rootTarget: keystore.id, capability});
+
+      // success, no response body
+      res.status(204).end();
+
+      // report revocation usage as operation usage
+      reportOperationUsage({req});
+    }));
+});

package/lib/index.js

@@ -0,0 +1,9 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import '@bedrock/express';
+
+import './http.js';
+
+// load config defaults
+import './config.js';

package/lib/logger.js

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import {loggers} from '@bedrock/core';
+
+export const logger = loggers.get('app').child('bedrock-kms-http');