@bedrock/kms-http 23.1.0 → 23.3.0

package/README.md

@@ -11,7 +11,10 @@
 
 ## Install
 
-- Node.js 18+ is required.
+This software requires and supports maintained recent versions of Node.js.
+Updates may remove support for older unmaintained platform versions. Please use
+dependency version lock files and testing to ensure compatibility with this
+software.
 
 ### NPM
 
@@ -36,7 +39,7 @@ npm install
 In `lib/index.js` (or `main.js`, as appropriate):
 
 ```js
-import 'bedrock-kms-http';
+import '@bedrock/kms-http';
 ```
 
 ### KMS HTTP API

package/lib/BedrockKeystoreConfigStorage.js

@@ -27,7 +27,7 @@ export class BedrockKeystoreConfigStorage extends KeystoreConfigStorage {
       throw new BedrockError(
         'Permission denied. Source IP is not allowed.', 'NotAllowedError', {
           httpStatusCode: 403,
-          public: true,
+          public: true
         });
     }
 
@@ -51,7 +51,7 @@ export class BedrockKeystoreConfigStorage extends KeystoreConfigStorage {
         throw new BedrockError(
           'Permission denied. Source IP is not allowed.', 'NotAllowedError', {
             httpStatusCode: 403,
-            public: true,
+            public: true
           });
       }
     }

package/lib/config.js

@@ -1,8 +1,9 @@
 /*!
- * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
  */
 import {config} from '@bedrock/core';
 import '@bedrock/app-identity';
+import '@bedrock/express';
 import '@bedrock/meter-usage-reporter';
 import '@bedrock/validation';
 
@@ -35,3 +36,47 @@ cfg.kmsOperationOptions = {
   // 1000 year max TTL by default
   maxDelegationTtl: 1000 * 60 * 60 * 24 * 365 * 1000
 };
+
+/* Optional proxy feature: An application running bedrock-kms-http can use
+these configuration options to redirect KMS operations to another
+bedrock-kms-http application, called a "proxy target". The proxy target must
+shares the same database and be configured with the same public address
+(domain / origin) but it is expected to be run behind a firewall (with
+restricted access) and inside of an isolated environment, such as a secure
+enclave, to add an additional layer of security during the processing of
+KMS operations.
+
+The proxying application will not have access to secret key material or to
+secrets that can decrypt/unseal/unwrap other secrets, only the proxy target
+will have access to some or all of these (or be capable of using some or all
+of these via authz credentials only it can access). Both applications will
+have access to the same database and will be expected to run compatible
+versions of software to ensure database record compatibility. The proxy
+target MUST properly check authz on all incoming requests; authz is is NOT
+checked by the proxy.
+
+Proxy entries are defined by KMS module, i.e., at most one proxy target can
+be configured per KMS module. When requests for a particular KMS module arrive,
+they are forwarded in their entirety to the related proxy target. */
+cfg.kmsModuleProxy = {
+  /*
+  <kms-module-name>: {
+    proxyTarget: <address (base URL) for kms proxy target>
+  }
+  */
+};
+
+// require raw JSON payloads for proxied routes to preserve specific content
+// expression as it is used in signed digests
+const createRawBodyParserOptions = () => ({
+  raw: {
+    type: ['json', '+json']
+  }
+});
+const bodyParserRoutes = config.express.bodyParser.routes;
+// for generating a new key
+bodyParserRoutes['/kms/keystores/:keystoreId/keys'] =
+  createRawBodyParserOptions();
+// for running a key operation on an existing key
+bodyParserRoutes['/kms/keystores/:keystoreId/keys/:keyId'] =
+  createRawBodyParserOptions();

package/lib/http.js

@@ -1,10 +1,11 @@
 /*!
- * Copyright (c) 2019-2025 Digital Bazaar, Inc. All rights reserved.
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
  */
 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 * as zlib from 'node:zlib';
 import {
   getConfigsQuery,
   postKeystoreBody,
@@ -17,6 +18,7 @@ import {
 } from '@bedrock/kms';
 import {reportOperationUsage, SERVICE_TYPE} from './metering.js';
 import {asyncHandler} from '@bedrock/express';
+import {createProxyMiddleware} from 'http-proxy-middleware';
 import {generateRandom} from '@digitalbazaar/webkms-switch';
 import {meters} from '@bedrock/meter-usage-reporter';
 import {createValidateMiddleware as validate} from '@bedrock/validation';
@@ -49,6 +51,11 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
   // associated with a request
   const getKeystoreConfig = middleware.createGetKeystoreConfig({routes});
 
+  // create KMS module proxy middleware for use with KMS operations
+  const kmsModuleProxyMiddleware = _createKmsModuleProxyMiddleware();
+  // create raw => json parser for routes using KMS module proxy middleware
+  const rawBodyToJsonMiddleware = asyncHandler(_parseRawBodyAsJson);
+
   /* Note: CORS is used on all endpoints. This is safe because authorization
   uses HTTP signatures + capabilities, not cookies; CSRF is not possible. */
 
@@ -96,7 +103,7 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
         // insufficient remaining storage
         throw new BedrockError('Permission denied.', 'NotAllowedError', {
           httpStatusCode: 403,
-          public: true,
+          public: true
         });
       }
 
@@ -215,6 +222,8 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
     routes.keys,
     cors(),
     getKeystoreConfig,
+    kmsModuleProxyMiddleware,
+    rawBodyToJsonMiddleware,
     handleOperation);
 
   // invoke KMS operation on an existing key
@@ -223,6 +232,8 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
     routes.key,
     cors(),
     getKeystoreConfig,
+    kmsModuleProxyMiddleware,
+    rawBodyToJsonMiddleware,
     handleOperation);
 
   // TODO: consider whether this should be exposed w/o authorization
@@ -233,6 +244,8 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
     routes.key,
     cors(),
     getKeystoreConfig,
+    kmsModuleProxyMiddleware,
+    rawBodyToJsonMiddleware,
     asyncHandler(async (req, res) => {
       const {webkms: {keystore}} = req;
       const keyId = `${keystore.id}/keys/${req.params.keyId}`;
@@ -271,7 +284,7 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
         // meter is disabled, do not allow storage
         throw new BedrockError('Permission denied.', 'NotAllowedError', {
           httpStatusCode: 403,
-          public: true,
+          public: true
         });
       }
 
@@ -286,3 +299,101 @@ bedrock.events.on('bedrock-express.configure.routes', app => {
       reportOperationUsage({req});
     }));
 });
+
+function _createKmsModuleProxyMiddleware() {
+  const cfg = config['kms-http'];
+
+  const kmsModuleProxyEntries = Object.entries(cfg.kmsModuleProxy ?? {});
+  if(kmsModuleProxyEntries.length === 0) {
+    // nothing to proxy; no-op
+    return function kmsModuleProxyMiddleware(req, res, next) {
+      next();
+    };
+  }
+
+  const map = new Map();
+  for(const [kmsModule, {proxyTarget}] of kmsModuleProxyEntries) {
+    map.set(kmsModule, createProxyMiddleware({
+      target: proxyTarget,
+      // do not rewrite host header
+      changeOrigin: false,
+      // match TLS certificate checking expectations w/bedrock config
+      secure: config['https-agent'].rejectUnauthorized,
+      // include x-forward* headers
+      xfwd: true,
+      // do not forward websockets
+      ws: false,
+      on: {
+        // required to rewrite body since it has been parsed
+        proxyReq: _reserializeRequestBody
+      }
+    }));
+  }
+  return function kmsModuleProxyMiddleware(req, res, next) {
+    const {webkms: {keystore}} = req;
+    const {kmsModule} = keystore;
+    const mw = map.get(kmsModule);
+    if(!mw) {
+      return next();
+    }
+    mw(req, res, next);
+  };
+}
+
+// parses raw body to json
+function _parseRawBodyAsJson(req, res, next) {
+  try {
+    // special case empty body
+    req.body = req.body?.length > 0 ? JSON.parse(req.body.toString()) : {};
+    next();
+  } catch(cause) {
+    throw new BedrockError('Failed to parse expected JSON body.', {
+      name: 'DataError',
+      details: {httpStatusCode: 400, public: true},
+      cause
+    });
+  }
+}
+
+function _reserializeRequestBody(proxyReq, req) {
+  try {
+    if(!(req.body?.length > 0)) {
+      // nothing to send
+      return;
+    }
+
+    const contentType = proxyReq.getHeader('content-type');
+    if(!contentType) {
+      // nothing to send
+      return;
+    }
+
+    // reapply content-encoding
+    const contentEncoding = String(
+      proxyReq.getHeader('content-encoding')).toLowerCase();
+    let data = req.body;
+    if(contentEncoding === 'gzip') {
+      data = zlib.gzipSync(data);
+    } else if(contentEncoding === 'deflate') {
+      data = zlib.deflateSync(data);
+    } else if(contentEncoding === 'zstd') {
+      // note: not supported by body-parser, so unreachable
+      data = zlib.zstdCompressSync(data);
+    } else if(contentEncoding === 'br') {
+      // note: not supported by body-parser, so unreachable
+      data = zlib.brotliCompressSync(data);
+    } else {
+      proxyReq.removeHeader('content-encoding');
+    }
+
+    const transferEncoding = proxyReq.getHeader('transfer-encoding');
+    if(!transferEncoding) {
+      proxyReq.setHeader('content-length', Buffer.byteLength(data));
+    }
+    proxyReq.write(data);
+  } catch(e) {
+    // pass error through `proxyReq` processing channel
+    const error = e instanceof Error ? e : new Error(String(e));
+    proxyReq.destroy(error);
+  }
+}

package/lib/middleware.js

@@ -81,7 +81,7 @@ export function authorizeKeystoreZcapInvocation() {
         rootInvocationTarget: req.webkms.keystore.id
       };
     },
-    getRootController: getKeystoreController,
+    getRootController: getKeystoreController
   });
 }
 
@@ -210,13 +210,13 @@ function onError({error}) {
       error.message,
       error.name || 'NotAllowedError', {
         ...details,
-        public: true,
+        public: true
       }, error);
   }
   throw new BedrockError(
     'Authorization error.', 'NotAllowedError', {
       httpStatusCode: 403,
-      public: true,
+      public: true
     }, error);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/kms-http",
-  "version": "23.1.0",
+  "version": "23.3.0",
   "type": "module",
   "description": "Bedrock KMS HTTP API",
   "main": "./lib/index.js",
@@ -30,12 +30,13 @@
   "dependencies": {
     "@digitalbazaar/ed25519-multikey": "^1.3.1",
     "@digitalbazaar/ed25519-signature-2020": "^5.4.0",
-    "@digitalbazaar/ezcap-express": "^7.1.0",
+    "@digitalbazaar/ezcap-express": "^7.3.0",
     "@digitalbazaar/webkms-switch": "^12.0.0",
-    "cidr-regex": "^4.1.3",
-    "cors": "^2.8.5",
+    "cidr-regex": "^7.1.2",
+    "cors": "^2.8.6",
     "forwarded": "^0.2.0",
-    "ipaddr.js": "^2.2.0"
+    "http-proxy-middleware": "^4.2.0",
+    "ipaddr.js": "^2.5.0"
   },
   "peerDependencies": {
     "@bedrock/app-identity": "^4.0.0",
@@ -55,12 +56,10 @@
     "lib": "./lib"
   },
   "devDependencies": {
-    "eslint": "^8.57.1",
-    "eslint-config-digitalbazaar": "^5.2.0",
-    "eslint-plugin-jsdoc": "^50.6.3",
-    "eslint-plugin-unicorn": "^56.0.1"
+    "@digitalbazaar/eslint-config": "^9.0.0",
+    "eslint": "^10.13.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   }
 }

package/schemas/bedrock-kms-http.js

@@ -92,7 +92,7 @@ const delegatedZcap = {
         proofValue: {
           title: 'proofValue',
           type: 'string'
-        },
+        }
       }
     }
   }
@@ -109,7 +109,7 @@ const ipAllowList = {
   items: {
     type: 'string',
     // leading and trailing slashes in regex must be removed
-    pattern: cidrRegex({exact: true}).toString().slice(1, -1),
+    pattern: cidrRegex({exact: true}).toString().slice(1, -1)
   }
 };
 
@@ -146,7 +146,7 @@ const updateKeystoreConfigBody = {
   required: [
     'controller',
     'id',
-    'sequence',
+    'sequence'
   ],
   properties: {
     controller,