@bedrock/kms-http 13.0.0

package/lib/metering.js

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) 2019-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as bedrock from '@bedrock/core';
+import * as brZCapStorage from '@bedrock/zcap-storage';
+import {
+  defaultModuleManager as moduleManager,
+  keystores
+} from '@bedrock/kms';
+import {meters} from '@bedrock/meter-usage-reporter';
+import {logger} from './logger.js';
+
+// configure usage aggregator for webkms meters
+export const SERVICE_TYPE = 'webkms';
+meters.setAggregator({serviceType: SERVICE_TYPE, handler: _aggregateUsage});
+
+export function reportOperationUsage({req}) {
+  // do not wait for usage to be reported
+  const {keystore, keystore: {meterId: id}} = req.webkms;
+  meters.use({id, operations: 1}).catch(
+    error => logger.error(
+      `Keystore (${keystore.id}) meter (${id}) usage error.`, {error}));
+}
+
+async function _aggregateUsage({meter, signal} = {}) {
+  const {id: meterId} = meter;
+  return keystores.getStorageUsage({
+    meterId, moduleManager, aggregate: _addRevocationUsage, signal
+  });
+}
+
+async function _addRevocationUsage({config, usage}) {
+  // add storage units for revocations associated with the keystore
+  const {id: keystoreId} = config;
+  const {storageCost} = bedrock.config.kms;
+  // if `count` is available, use it to count stored revocations
+  if(brZCapStorage.revocations.count) {
+    const {count} = await brZCapStorage.revocations.count(
+      {rootTarget: keystoreId});
+    usage.storage += count * storageCost.revocation;
+  }
+}

package/lib/middleware.js

@@ -0,0 +1,181 @@
+/*!
+ * 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 {asyncHandler} from '@bedrock/express';
+import {BedrockKeystoreConfigStorage} from './BedrockKeystoreConfigStorage.js';
+import {createRequire} from 'module';
+import {
+  defaultDocumentLoader as documentLoader,
+  defaultModuleManager as moduleManager
+} from '@bedrock/kms';
+import {reportOperationUsage} from './metering.js';
+const require = createRequire(import.meta.url);
+const {
+  authorizeZcapInvocation: _authorizeZcapInvocation,
+  authorizeZcapRevocation: _authorizeZcapRevocation
+} = require('@digitalbazaar/ezcap-express');
+const {createOperationMiddleware} = require('@digitalbazaar/webkms-switch');
+const {CryptoLD} = require('crypto-ld');
+const {Ed25519Signature2020} =
+  require('@digitalbazaar/ed25519-signature-2020');
+const {Ed25519VerificationKey2020} =
+  require('@digitalbazaar/ed25519-verification-key-2020');
+
+const {config, util: {BedrockError}} = bedrock;
+
+const storage = new BedrockKeystoreConfigStorage();
+
+// create `getVerifier` hook for verifying zcap invocation HTTP signatures
+const cryptoLd = new CryptoLD();
+cryptoLd.use(Ed25519VerificationKey2020);
+
+// creates middleware to get the keystore config for the current request and
+// caches it in `req.webkms.keystore`
+export function createGetKeystoreConfig({routes}) {
+  return asyncHandler(async function _getKeystoreConfig(req, res, next) {
+    if(!req.webkms) {
+      const keystoreId = helpers.getKeystoreId(
+        {req, localId: req.params.keystoreId, routes});
+      const keystore = await storage.get({id: keystoreId, req});
+      req.webkms = {keystore};
+    }
+    next();
+  });
+}
+
+// creates middleware for handling KMS operations
+export function createKmsOperationMiddleware() {
+  const {kmsOperationOptions} = config['kms-http'];
+  return createOperationMiddleware({
+    ...kmsOperationOptions,
+    storage, moduleManager, documentLoader,
+    expectedHost: config.server.host, getVerifier,
+    inspectCapabilityChain,
+    onError, onSuccess: reportOperationUsage, suiteFactory
+  });
+}
+
+// calls ezcap-express's authorizeZcapInvocation w/constant params, exposing
+// only those params that change in this module
+export function authorizeZcapInvocation({
+  getExpectedValues, getRootController
+}) {
+  return _authorizeZcapInvocation({
+    documentLoader, getExpectedValues, getRootController,
+    getVerifier,
+    inspectCapabilityChain,
+    onError,
+    suiteFactory
+  });
+}
+
+// creates middleware for keystore route authz checks
+export function authorizeKeystoreZcapInvocation() {
+  return authorizeZcapInvocation({
+    async getExpectedValues({req}) {
+      return {
+        host: config.server.host,
+        rootInvocationTarget: req.webkms.keystore.id
+      };
+    },
+    async getRootController({req}) {
+      // this will always be present based on where this middleware is used
+      return req.webkms.keystore.controller;
+    }
+  });
+}
+
+// creates middleware for revocation of zcaps for keystores
+export function authorizeZcapRevocation() {
+  return _authorizeZcapRevocation({
+    documentLoader,
+    expectedHost: config.server.host,
+    async getRootController({req}) {
+      // this will always be present based on where this middleware is used
+      return req.webkms.keystore.controller;
+    },
+    getVerifier,
+    inspectCapabilityChain,
+    onError,
+    suiteFactory
+  });
+}
+
+// hook used to verify zcap invocation HTTP signatures
+async function getVerifier({keyId, documentLoader}) {
+  const key = await cryptoLd.fromKeyId({id: keyId, documentLoader});
+  const verificationMethod = await key.export(
+    {publicKey: true, includeContext: true});
+  const verifier = key.verifier();
+  return {verifier, verificationMethod};
+}
+
+async function inspectCapabilityChain({
+  capabilityChain, capabilityChainMeta
+}) {
+  // if capability chain has only root, there's nothing to check as root
+  // zcaps cannot be revoked
+  if(capabilityChain.length === 1) {
+    return {valid: true};
+  }
+
+  // collect capability IDs and delegators for all delegated capabilities in
+  // chain (skip root) so they can be checked for revocation
+  const capabilities = [];
+  for(const [i, capability] of capabilityChain.entries()) {
+    // skip root zcap, it cannot be revoked
+    if(i === 0) {
+      continue;
+    }
+    const [{purposeResult}] = capabilityChainMeta[i].verifyResult.results;
+    if(purposeResult && purposeResult.delegator) {
+      capabilities.push({
+        capabilityId: capability.id,
+        delegator: purposeResult.delegator.id,
+      });
+    }
+  }
+
+  const revoked = await brZCapStorage.revocations.isRevoked({capabilities});
+  if(revoked) {
+    return {
+      valid: false,
+      error: new Error(
+        'One or more capabilities in the chain have been revoked.')
+    };
+  }
+
+  return {valid: true};
+}
+
+function onError({error}) {
+  // cause must be a public BedrockError to be surfaced to the HTTP client
+  let cause;
+  if(error instanceof BedrockError) {
+    cause = error;
+  } else {
+    let details = {};
+    if(error.details && error.details.public) {
+      details = error.details;
+    }
+    cause = new BedrockError(
+      error.message,
+      error.name || 'NotAllowedError', {
+        ...details,
+        public: true,
+      });
+  }
+  throw new BedrockError(
+    'Authorization error.', 'NotAllowedError', {
+      httpStatusCode: 403,
+      public: true,
+    }, cause);
+}
+
+// hook used to create suites for verifying zcap delegation chains
+async function suiteFactory() {
+  return new Ed25519Signature2020();
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@bedrock/kms-http",
+  "version": "13.0.0",
+  "type": "module",
+  "description": "Bedrock KMS HTTP API",
+  "main": "./lib/index.js",
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitalbazaar/bedrock-kms-http"
+  },
+  "keywords": [
+    "bedrock"
+  ],
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "https://digitalbazaar.com"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/bedrock-kms-http/issues"
+  },
+  "homepage": "https://github.com/digitalbazaar/bedrock-kms-http",
+  "dependencies": {
+    "@digitalbazaar/ed25519-signature-2020": "^3.0.0",
+    "@digitalbazaar/ed25519-verification-key-2020": "^3.2.0",
+    "@digitalbazaar/ezcap-express": "^6.0.0",
+    "@digitalbazaar/webkms-switch": "^10.0.0",
+    "cidr-regex": "^3.1.1",
+    "cors": "^2.8.5",
+    "crypto-ld": "^6.0.0",
+    "forwarded": "^0.2.0",
+    "netmask": "^2.0.2"
+  },
+  "peerDependencies": {
+    "@bedrock/core": "^5.0.0",
+    "@bedrock/app-identity": "^2.0.0",
+    "@bedrock/express": "^7.0.0",
+    "@bedrock/kms": "^9.0.0",
+    "@bedrock/meter-usage-reporter": "^6.0.0",
+    "@bedrock/validation": "^6.0.0",
+    "@bedrock/zcap-storage": "^6.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"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/schemas/bedrock-kms-http.js

@@ -0,0 +1,176 @@
+/*!
+ * Copyright (c) 2020-2022 Digital Bazaar, Inc. All rights reserved.
+ */
+import cidrRegex from 'cidr-regex';
+
+const controller = {
+  title: 'controller',
+  type: 'string'
+};
+
+const id = {
+  title: 'id',
+  type: 'string'
+};
+
+const referenceId = {
+  title: 'referenceId',
+  type: 'string'
+};
+
+const delegatedZcap = {
+  title: 'delegatedZcap',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    '@context', 'controller', 'expires', 'id', 'invocationTarget',
+    'parentCapability', 'proof'
+  ],
+  properties: {
+    controller,
+    id,
+    allowedAction: {
+      anyOf: [{
+        type: 'string'
+      }, {
+        type: 'array',
+        minItems: 1,
+        items: {type: 'string'}
+      }]
+    },
+    expires: {
+      // FIXME: w3c datetime
+      title: 'expires',
+      type: 'string'
+    },
+    '@context': {
+      title: '@context',
+      anyOf: [{
+        type: 'string'
+      }, {
+        type: 'array',
+        minItems: 1,
+        items: {type: 'string'}
+      }]
+    },
+    invocationTarget: {
+      title: 'Invocation Target',
+      type: 'string'
+    },
+    parentCapability: {
+      title: 'Parent Capability',
+      type: 'string'
+    },
+    proof: {
+      title: 'Proof',
+      type: 'object',
+      additionalProperties: false,
+      required: [
+        'verificationMethod', 'type', 'created', 'proofPurpose',
+        'capabilityChain', 'proofValue'
+      ],
+      properties: {
+        verificationMethod: {
+          title: 'verificationMethod',
+          type: 'string'
+        },
+        type: {
+          title: 'type',
+          type: 'string'
+        },
+        created: {
+          title: 'created',
+          type: 'string'
+        },
+        proofPurpose: {
+          title: 'proofPurpose',
+          type: 'string'
+        },
+        capabilityChain: {
+          title: 'capabilityChain',
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: ['string', 'object']
+          }
+        },
+        proofValue: {
+          title: 'proofValue',
+          type: 'string'
+        },
+      }
+    }
+  }
+};
+
+const meterId = {
+  title: 'Meter ID',
+  type: 'string'
+};
+
+const ipAllowList = {
+  type: 'array',
+  minItems: 1,
+  items: {
+    type: 'string',
+    // leading and trailing slashes in regex must be removed
+    pattern: cidrRegex.v4({exact: true}).toString().slice(1, -1),
+  }
+};
+
+const sequence = {
+  title: 'sequence',
+  type: 'integer',
+  minimum: 0,
+  maximum: Number.MAX_SAFE_INTEGER - 1
+};
+
+const kmsModule = {
+  title: 'kmsModule',
+  type: 'string'
+};
+
+const postKeystoreBody = {
+  title: 'postKeystoreBody',
+  type: 'object',
+  additionalProperties: false,
+  required: ['sequence', 'controller', 'meterId'],
+  properties: {
+    controller,
+    ipAllowList,
+    referenceId,
+    sequence,
+    kmsModule,
+    meterId
+  }
+};
+
+const updateKeystoreConfigBody = {
+  title: 'updateKeystoreConfigBody',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'controller',
+    'id',
+    'sequence',
+  ],
+  properties: {
+    controller,
+    id,
+    ipAllowList,
+    referenceId,
+    sequence,
+    kmsModule,
+    meterId
+  }
+};
+
+const postRevocationBody = {
+  ...delegatedZcap
+};
+
+export {
+  postKeystoreBody,
+  postRevocationBody,
+  updateKeystoreConfigBody
+};

package/test/mocha/.eslintrc

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