@bedrock/kms-http 14.1.0 → 14.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # bedrock-kms-http ChangeLog
 
+## 14.3.0 - 2022-05-16
+
+### Added
+- Add debug logging for keystore config cache busting.
+
+## 14.2.1 - 2022-05-13
+
+### Fixed
+- Fix cache busting for invoked delegated zcap cases.
+
+## 14.2.0 - 2022-05-13
+
+### Changed
+- Be more resilient to keystore config controller changes. When a keystore
+  is new and KMS operations are performed on it that could cause false-positive
+  fail authz errors, fetch a fresh version of the config to ensure that the
+  controller has not changed.
+
 ## 14.1.0 - 2022-05-12
 
 ### Added

package/lib/BedrockKeystoreConfigStorage.js

@@ -14,12 +14,13 @@ const {util: {BedrockError}} = bedrock;
 import './config.js';
 
 export class BedrockKeystoreConfigStorage extends KeystoreConfigStorage {
-  async get({id, req} = {}) {
-    const {config: keystoreConfig} = await keystores.get({id});
+  async get({id, req, returnRecord = false, fresh = false} = {}) {
+    const record = await keystores.get({id, fresh});
+    const {config: keystoreConfig} = record;
 
     // skip request checks if specifically requested
     if(req === false) {
-      return keystoreConfig;
+      return returnRecord ? record : keystoreConfig;
     }
 
     // verify that request is from an IP that is allowed to access the config
@@ -32,6 +33,6 @@ export class BedrockKeystoreConfigStorage extends KeystoreConfigStorage {
         });
     }
 
-    return keystoreConfig;
+    return returnRecord ? record : keystoreConfig;
   }
 }

package/lib/middleware.js

@@ -11,6 +11,7 @@ import {
   defaultDocumentLoader as documentLoader,
   defaultModuleManager as moduleManager
 } from '@bedrock/kms';
+import {logger} from './logger.js';
 import {reportOperationUsage} from './metering.js';
 const require = createRequire(import.meta.url);
 const {
@@ -26,6 +27,8 @@ const {Ed25519VerificationKey2020} =
 
 const {config, util: {BedrockError}} = bedrock;
 
+const FIVE_MINUTES = 1000 * 60 * 5;
+
 const storage = new BedrockKeystoreConfigStorage();
 
 // create `getVerifier` hook for verifying zcap invocation HTTP signatures
@@ -39,8 +42,11 @@ export function createGetKeystoreConfig({routes}) {
     if(!req.webkms) {
       const keystoreId = helpers.getKeystoreId(
         {req, localId: req.params.keystoreId, routes});
-      const keystore = await storage.get({id: keystoreId, req});
-      req.webkms = {keystore};
+      const configRecord = await storage.get({
+        id: keystoreId, req, returnRecord: true
+      });
+      const {config: keystore} = configRecord;
+      req.webkms = {keystore, configRecord};
     }
     next();
   });
@@ -81,10 +87,7 @@ export function authorizeKeystoreZcapInvocation() {
         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;
-    }
+    getRootController: getKeystoreController,
   });
 }
 
@@ -93,10 +96,7 @@ 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;
-    },
+    getRootController: getKeystoreController,
     getVerifier,
     inspectCapabilityChain,
     onError,
@@ -104,6 +104,94 @@ export function authorizeZcapRevocation() {
   });
 }
 
+async function getKeystoreController({req}) {
+  /* The following code is to prevent false-negative authz errors that are the
+  result of stale cached keystore configs.
+
+  It is a common pattern for keystore configs to have their root controllers
+  updated immediately after creation based on the value of a key that is in the
+  keystore itself. When this happens, decentralized caches may hold a stale
+  config with the old controller value. A client that uses a zcap that is
+  delegated / controlled by the root controller would see a false negative
+  authz error if the authz check used the cached value.
+
+  Therefore, this code will check whether keystore configs are reasonably new
+  and whether a failure is likely to occur on account of a mismatched root
+  controller. If this seems likely, a fresh copy of the keystore config record
+  is retrieved.
+
+  Algorithm: If the keystore config is less than five minutes old, then inspect
+  `req.ezcap.invocationParameters.capability` or `req.ezcap.capabilityToRevoke`
+  to ensure that:
+
+  1. The `capability` is the root zcap and the ID or the controller of the
+    invoking verification method matches the keystore controller (note: can't
+    revoke a root zcap so this is an invoke-only case).
+  2. The `capability` (being invoked or revoked) is delegated and the
+    ID or controller of the delegating verification method for the first
+    delegated zcap in the chain matches the keystore controller.
+
+  If neither condition is true, fetch a fresh version of the keystore config
+  record and update `req.webkms`. */
+  const now = Date.now();
+  if((now - req.webkms.configRecord.meta.created) > FIVE_MINUTES ||
+    (req.ezcap.capabilityToRevoke && req.ezcap.invocationParameters)) {
+    // config is either older than five minutes or we've already been through
+    // this code path for the current request to run the checks against a
+    // zcap that is to be revoked (in which case we must not update again to
+    // ensure the keystore config used is consistent)
+    return req.webkms.keystore.controller;
+  }
+
+  // check for a zcap from the invocation params or for one to be revoked; the
+  // same rules above will be used to check if we need a fresh config record
+  const capability = req.ezcap?.invocationParameters?.capability ||
+    req.ezcap.capabilityToRevoke;
+
+  // capability is root if it is a string; and it must be invoked because you
+  // can't revoke a root zcap
+  const isRoot = typeof capability === 'string';
+  let keyId;
+  if(isRoot && req.ezcap.invocationParameters) {
+    // get verification method (key) ID from invocation params
+    ({signature: {params: {keyId}}} = req.ezcap);
+  } else {
+    // get verification method (key) ID from first delegation proof
+    if(capability?.proof?.capabilityChain.length === 1) {
+      // capability *is* the delegated zcap
+      keyId = capability.proof?.verificationMethod;
+    } else {
+      // capability is delegated further down the chain
+      keyId = capability?.proof?.capabilityChain[1]?.proof?.verificationMethod;
+    }
+  }
+
+  if(!keyId) {
+    logger.debug(
+      'No verification method found in zcap when trying to bust keystore ' +
+      'config cache.');
+
+    // no verification method to check, use cached keystore controller
+    return req.webkms.keystore.controller;
+  }
+
+  // fetch verification method early to compare against keystore controller
+  const {verificationMethod} = await getVerifier({keyId, documentLoader});
+
+  // get fresh record if VM ID nor controller matches keystore controller
+  if(!(verificationMethod.controller === req.webkms.keystore.controller ||
+    verificationMethod.id === req.webkms.keystore.controller)) {
+    const configRecord = await storage.get({
+      id: req.webkms.keystore.id, req, returnRecord: true, fresh: true
+    });
+    const {config: keystore} = configRecord;
+    req.webkms = {keystore, configRecord};
+    logger.debug('Forced fresh keystore config retrieval during zcap check.');
+  }
+
+  return req.webkms.keystore.controller;
+}
+
 // hook used to verify zcap invocation HTTP signatures
 async function getVerifier({keyId, documentLoader}) {
   const key = await cryptoLd.fromKeyId({id: keyId, documentLoader});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bedrock/kms-http",
-  "version": "14.1.0",
+  "version": "14.3.0",
   "type": "module",
   "description": "Bedrock KMS HTTP API",
   "main": "./lib/index.js",
@@ -26,7 +26,7 @@
   "dependencies": {
     "@digitalbazaar/ed25519-signature-2020": "^3.0.0",
     "@digitalbazaar/ed25519-verification-key-2020": "^3.2.0",
-    "@digitalbazaar/ezcap-express": "^6.0.0",
+    "@digitalbazaar/ezcap-express": "^6.2.0",
     "@digitalbazaar/webkms-switch": "^10.0.0",
     "cidr-regex": "^3.1.1",
     "cors": "^2.8.5",
@@ -38,7 +38,7 @@
     "@bedrock/app-identity": "^3.0.0",
     "@bedrock/core": "^6.0.0",
     "@bedrock/express": "^8.0.0",
-    "@bedrock/kms": "^10.0.0",
+    "@bedrock/kms": "^10.2.0",
     "@bedrock/meter-usage-reporter": "^7.0.0",
     "@bedrock/validation": "^7.0.0",
     "@bedrock/zcap-storage": "^7.0.0"

package/test/mocha/11-keystore-kms-client.js

@@ -3,11 +3,14 @@
  */
 import * as helpers from './helpers.js';
 import {httpsAgent} from '@bedrock/https-agent';
+import {keystores} from '@bedrock/kms';
 import {createRequire} from 'node:module';
 const require = createRequire(import.meta.url);
 const {CapabilityAgent, KmsClient, KeystoreAgent} =
   require('@digitalbazaar/webkms-client');
 
+const ZCAP_ROOT_PREFIX = 'urn:zcap:root:';
+
 describe('keystore API interactions using webkms-client', () => {
   let aliceCapabilityAgent;
   let aliceKeystoreConfig;
@@ -63,4 +66,108 @@ describe('keystore API interactions using webkms-client', () => {
     err.data.details.expected.should.equal(
       bobKeystoreAgent.keystoreId);
   });
+
+  it('updates config controller twice proving cache busting', async () => {
+    const keystoreId = aliceKeystoreConfig.id;
+    const kmsClient = new KmsClient({httpsAgent});
+
+    // create zcap agents to take over the keystore
+    const agent1 = await CapabilityAgent.fromSecret(
+      {secret: 'bd926f4c-38e4-4c3a-9a17-0e2608ee0a01', handle: 'primary'});
+    const agent2 = await CapabilityAgent.fromSecret(
+      {secret: 'd830baa9-02a6-4bd3-9072-de256b0b6c2d', handle: 'primary'});
+    const agent3 = await CapabilityAgent.fromSecret(
+      {secret: '37224754-647e-469a-9639-193a2833c69a', handle: 'primary'});
+
+    const aliceKeystoreAgent = new KeystoreAgent(
+      {capabilityAgent: aliceCapabilityAgent, keystoreId, kmsClient});
+    const agent1KeystoreAgent = new KeystoreAgent(
+      {capabilityAgent: agent1, keystoreId, kmsClient});
+    // const agent2KeystoreAgent = new KeystoreAgent(
+    //   {capabilityAgent: agent2, keystoreId, kmsClient});
+    const agent3KeystoreAgent = new KeystoreAgent(
+      {capabilityAgent: agent3, keystoreId, kmsClient});
+
+    // delegate zcap for updating config from agent2 to agent3 to test
+    // cache busting with delegated zcap
+    const rootCapability = ZCAP_ROOT_PREFIX + encodeURIComponent(keystoreId);
+    const agent3Zcap = await helpers.delegate({
+      parentCapability: rootCapability,
+      controller: agent3.id,
+      invocationTarget: keystoreId,
+      delegator: agent2
+    });
+
+    // delegate zcap for updating config from agent3 to agent2 to agent1 to
+    // test cache busting with deep delegated zcap
+    const agent2Zcap = await helpers.delegate({
+      parentCapability: rootCapability,
+      controller: agent2.id,
+      invocationTarget: keystoreId,
+      delegator: agent3
+    });
+    const agent1Zcap = await helpers.delegate({
+      parentCapability: agent2Zcap,
+      controller: agent1.id,
+      invocationTarget: keystoreId,
+      delegator: agent2
+    });
+
+    // update Alice's keystore config controller to agent1
+    let config = {...aliceKeystoreConfig};
+
+    try {
+      // disable cache delete functionality on update
+      keystores._disableClearCacheOnUpdate(true);
+
+      // update controller alice => agent1 (no cache busting required
+      {
+        config.sequence++;
+        config.controller = agent1.id;
+        const result = await aliceKeystoreAgent.updateConfig({config});
+        result.config.id.should.eql(config.id);
+        result.config.controller.should.eql(agent1.id);
+        ({config} = result);
+      }
+
+      // update controller agent1 => agent2 (requires cache busting by
+      // inspecting the root zcap)
+      {
+        config.sequence++;
+        config.controller = agent2.id;
+        const result = await agent1KeystoreAgent.updateConfig({config});
+        result.config.id.should.eql(config.id);
+        result.config.controller.should.eql(agent2.id);
+        ({config} = result);
+      }
+
+      // update controller agent2 => agent3 (requires cache busting by
+      // inspecting a delegated zcap)
+      {
+        config.sequence++;
+        config.controller = agent3.id;
+        const result = await agent3KeystoreAgent.updateConfig(
+          {capability: agent3Zcap, config});
+        result.config.id.should.eql(config.id);
+        result.config.controller.should.eql(agent3.id);
+        ({config} = result);
+      }
+
+      // update controller agent3 => agent1 (requires cache busting by
+      // inspecting a deep delegated zcap)
+      {
+        config.sequence++;
+        config.controller = agent1.id;
+        const result = await agent1KeystoreAgent.updateConfig(
+          {capability: agent1Zcap, config});
+        result.config.id.should.eql(config.id);
+        result.config.controller.should.eql(agent1.id);
+        ({config} = result);
+      }
+    } catch(e) {
+      assertNoError(e);
+    } finally {
+      keystores._disableClearCacheOnUpdate(false);
+    }
+  });
 });