@digitalbazaar/ezcap-express 4.1.1 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @digitalbazaar/ezcap-express Changelog
 
+## 4.4.0 - 2021-12-15
+
+### Added
+- Add additional tests.
+
+## 4.3.1 - 2021-12-13
+
+### Fixed
+- Fix `expectedAction` to be `write` for `DELETE` method.
+- Throw error when no `expectedAction` is given for a given HTTP method and
+  provide defaults for all common HTTP methods.
+
+## 4.3.0 - 2021-12-10
+
+### Added
+- Allow any controller in a delegated zcap's chain to revoke it. This authority
+  is inherent in delegation and is now reflected in code. This feature gives
+  delegators more fine-grained control to revoke zcaps that they did not
+  delegate directly but one of their delegates did, allowing them to stop
+  specific zcap usage without having to revoke more of the chain. It also
+  gives zcap controllers the ability to revoke their own zcaps (if desired)
+  and adds a sanity check to prevent the revocation of root zcaps that use
+  the `urn:zcap:root:` ID scheme.
+
+## 4.2.0 - 2021-08-26
+
+### Added
+- Add `suiteFactory` parameter to middleware creation functions. A
+  `suiteFactory` function should be passed and return the supported LD proof
+  suite (or an array of supported LD proof suites) that is supported for
+  authorizing zcap invocations and verifying capability chains.
+- Add `authorizeZcapRevocation` middleware that can be attached to root
+  container/object endpoints to enable revocation of zcaps that have been
+  delegated to use them. This version assumes that the revocations endpoint
+  will follow this RESTful format: `<rootObjectUrl>/revocations/<zcapId>`
+  and that the body will be JSON and include a `capability` member with
+  the zcap to revoke. Future versions may allow for greater flexibility.
+
+### Changed
+- Deprecate passing a `suite` to any middleware creation functions. Instead,
+  `suiteFactory` should be passed. The next major version will remove `suite`.
+  This approach allows this library to remove npm dependencies that provide
+  cryptographic suites preventing this library from being affected when those
+  dependencies need to change.
+
 ## 4.1.1 - 2021-07-21
 
 ### Changed

package/lib/authorize.js

@@ -4,13 +4,9 @@
 import assert from 'assert-plus';
 import asyncHandler from 'express-async-handler';
 import {Ed25519Signature2020} from '@digitalbazaar/ed25519-signature-2020';
-import {parseSignatureHeader} from 'http-signature-header';
-import {verifyHeaderValue} from '@digitalbazaar/http-digest-header';
-import * as sec from 'security-context';
+import * as helpers from './helpers.js';
 import {verifyCapabilityInvocation} from 'http-signature-zcap-verify';
 
-const ZCAP_ROOT_PREFIX = 'urn:zcap:root:';
-
 /**
  * Authorizes an incoming request.
  *
@@ -42,129 +38,56 @@ const ZCAP_ROOT_PREFIX = 'urn:zcap:root:';
  *   inspect a capability chain, e.g., to check for revocations.
  * @param {Function} [options.onError] - An error handler handler for
  *   customizable error handling.
- * @param {object} [options.suite] - The expected cryptography suite to use when
- *   verifying digital signatures.
+ * @param {object} [options.suite] - The expected cryptography suite to use
+ *   when verifying digital signatures (deprecated; use `suiteFactory`
+ *   instead).
+ * @param {object} [options.suiteFactory] - A factory for creating the
+ *   supported suite(s) to use when verifying digital signatures.
  *
- * @returns {Function} Returns an Express.js middleware route handler.
+ * @returns {Function} Returns an Express.js style middleware route handler.
  */
 export function authorizeZcapInvocation({
   documentLoader, expectedHost, getExpectedTarget, getRootController,
   allowTargetAttenuation = true, expectedAction, getExpectedAction,
   getExpectedRootCapabilityId, inspectCapabilityChain,
-  onError, suite = new Ed25519Signature2020()
+  onError, suite, suiteFactory
 } = {}) {
+  // `helpers.createExpectationMiddleware` handles type checks on other params
   assert.func(documentLoader, 'options.documentLoader');
-  assert.optionalString(expectedAction, 'options.expectedAction');
-  assert.optionalFunc(
-    getExpectedAction, 'options.getExpectedAction');
-  assert.string(expectedHost, 'options.expectedHost');
-  assert.func(getExpectedTarget, 'options.getExpectedTarget');
   assert.func(getRootController, 'options.getRootController');
-  assert.optionalFunc(
-    getExpectedRootCapabilityId, 'options.getExpectedRootCapabilityId');
   assert.optionalFunc(inspectCapabilityChain, 'options.inspectCapabilityChain');
-  assert.optionalFunc(onError, 'options.onError');
-
-  if(getExpectedAction && expectedAction !== undefined) {
-    throw new Error('Use "getExpectedAction" or "expectedAction", not both.');
+  assert.optionalFunc(suiteFactory, 'options.suiteFactory');
+
+  // this code block is to be removed the next major release (5.0); `suite`
+  // should be removed as a parameter
+  if(!(suite && suiteFactory)) {
+    suiteFactory = () => new Ed25519Signature2020();
+  } else if(!suiteFactory) {
+    // backwards compatibility
+    suiteFactory = () => suite;
   }
 
-  return asyncHandler(async (req, res, next) => {
-    // originalUrl must be used to support nested express routers
-    const {originalUrl: url, method, headers} = req;
-    let params;
-    try {
-      ({params} = parseSignatureHeader(headers.authorization));
-    } catch(e) {
-      const error = new Error('Missing or invalid "authorization" header.');
-      error.name = 'DataError';
-      error.cause = e;
-      return _handleError({error, onError});
-    }
-    const {keyId} = params;
-
-    // if body is present, ensure header digest value matches digest of body
-    if(_hasBody({req})) {
-      const {digest: expectedDigest} = headers;
-      if(!expectedDigest) {
-        const error = new Error(
-          'A "digest" header must be present when an HTTP body is present.');
-        error.name = 'DataError';
-        error.httpStatusCode = 400;
-        return _handleError({error, onError});
-      }
-      const {verified} = await verifyHeaderValue({
-        data: req.body, headerValue: expectedDigest});
-      if(!verified) {
-        const error = new Error(
-          'The "digest" header value does not match digest of body.');
-        error.name = 'DataError';
-        error.httpStatusCode = 400;
-        return _handleError({error, onError});
-      }
-    } else {
-      // prevent any unhandled `req.body` from being erroneously used
-      req.body = undefined;
-    }
-
-    // use `getExpectedAction` if provided
-    if(getExpectedAction) {
-      expectedAction = await getExpectedAction({req});
-    }
-
-    let expectedTarget;
-    try {
-      // getExpectedTarget may throw an error
-      ({expectedTarget} = await getExpectedTarget({req}));
-      if(!(typeof expectedTarget === 'string' ||
-        Array.isArray(expectedTarget))) {
-        throw new Error(
-          'Return value from "getExpectedTarget" must be an object with ' +
-          '"expectedTarget" set to a string or an array.');
-      }
-    } catch(error) {
-      return _handleError({error, onError});
-    }
-
-    let _expectedAction = expectedAction;
-
-    // set expected action if it has not been specified
-    /* Note: This is safe as long as the server's request handling
-    infrastructure differentiates based on HTTP method (as is typical practice
-    with express/connect routing. So, while the client specifies the HTTP
-    method, the server specifies the handler for that HTTP method. For example,
-    this middleware will ensure that if a client specifies "POST" then it
-    must be invoking a zcap that grants "write" action authority. Then, provided
-    that the server's router ensures that only the "POST" handler will be
-    executed (typical routing practice), all is well. If the handler code is
-    chosen via some other means, e.g., via the request body, then the caller
-    MUST provide the expected action and not rely on default behavior. */
-    if(_expectedAction === undefined) {
-      _expectedAction = 'read';
-      if(req.method === 'POST') {
-        _expectedAction = 'write';
-      }
-    }
+  return [
+    helpers.createExpectationMiddleware({
+      expectedHost, expectedAction, getExpectedAction, getExpectedTarget,
+      getExpectedRootCapabilityId, onError
+    }),
+    authorizeZcapInvocationAfterParse({
+      documentLoader, getRootController, suiteFactory,
+      allowTargetAttenuation, inspectCapabilityChain, onError
+    })
+  ];
+}
 
-    let expectedRootCapability;
-    try {
-      if(getExpectedRootCapabilityId) {
-        // retrieve the root capability given the request and expected params
-        // return value can be a string or an array of strings
-        expectedRootCapability = await getExpectedRootCapabilityId({
-          req, expectedHost, expectedTarget,
-          expectedAction: _expectedAction
-        });
-      } else if(Array.isArray(expectedTarget)) {
-        expectedRootCapability = expectedTarget.map(
-          t => `${ZCAP_ROOT_PREFIX}${encodeURIComponent(t)}`);
-      } else {
-        expectedRootCapability =
-          `${ZCAP_ROOT_PREFIX}${encodeURIComponent(expectedTarget)}`;
-      }
-    } catch(error) {
-      return _handleError({error, onError});
-    }
+export function authorizeZcapInvocationAfterParse({
+  documentLoader, getRootController, suiteFactory,
+  allowTargetAttenuation = true, inspectCapabilityChain, onError
+} = {}) {
+  return asyncHandler(async (req, res, next) => {
+    const {
+      expectedAction, expectedHost, expectedRootCapability, expectedTarget,
+      signature: {params: {keyId}}
+    } = req.ezcap;
 
     // retrieves the root capability that was invoked
     async function getInvokedCapability({id}) {
@@ -182,24 +105,26 @@ export function authorizeZcapInvocation({
           actual: id,
           expected: expectedRootCapability,
         };
-        return _handleError({error, onError});
+        return helpers.handleError({error, onError});
       }
-      return _getRootCapability({
+      return helpers.getRootCapability({
         getRootController, req, expectedHost, expectedTarget,
-        expectedAction: _expectedAction, rootCapabilityId
+        expectedAction, rootCapabilityId
       });
     }
 
-    // perform the capability invocation
+    // perform the capability invocation...
+    // `originalUrl` must be used to support nested express routers
+    const {originalUrl: url, method, headers} = req;
     const result = await verifyCapabilityInvocation({
       url,
       method,
-      suite,
+      suite: await suiteFactory({req}),
       headers,
       expectedHost,
-      documentLoader: _wrappedDocumentLoader({
+      documentLoader: helpers.wrappedDocumentLoader({
         documentLoader,
-        expectedAction: _expectedAction,
+        expectedAction,
         expectedHost,
         expectedTarget,
         getRootController,
@@ -207,7 +132,7 @@ export function authorizeZcapInvocation({
       }),
       getInvokedCapability,
       expectedTarget,
-      expectedAction: _expectedAction,
+      expectedAction,
       expectedRootCapability,
       inspectCapabilityChain,
       keyId,
@@ -216,7 +141,7 @@ export function authorizeZcapInvocation({
 
     // return HTTP 403 if verification fails
     if(!result.verified) {
-      _handleError({error: result.error, onError, throwError: false});
+      helpers.handleError({error: result.error, onError, throwError: false});
       return res.status(403).send();
     }
 
@@ -229,60 +154,3 @@ export function authorizeZcapInvocation({
     process.nextTick(next);
   });
 }
-
-function _handleError({error, onError, throwError = true}) {
-  if(onError) {
-    return onError({error});
-  }
-  if(throwError) {
-    throw error;
-  }
-}
-
-function _wrappedDocumentLoader({
-  req, documentLoader, expectedHost, expectedTarget, expectedAction,
-  getRootController
-}) {
-  return async url => {
-    if(url.startsWith(ZCAP_ROOT_PREFIX)) {
-      const document = await _getRootCapability({
-        getRootController, req, expectedHost, expectedTarget, expectedAction,
-        rootCapabilityId: url
-      });
-
-      return {
-        contextUrl: null,
-        documentUrl: url,
-        document,
-      };
-    }
-
-    return documentLoader(url);
-  };
-}
-
-async function _getRootCapability({
-  getRootController, req, expectedHost, expectedTarget, expectedAction,
-  rootCapabilityId
-}) {
-  const rootInvocationTarget = decodeURIComponent(
-    rootCapabilityId.substr(ZCAP_ROOT_PREFIX.length));
-  const controller = await getRootController({
-    req, expectedHost, expectedTarget, expectedAction,
-    rootCapabilityId, rootInvocationTarget
-  });
-  return {
-    '@context': sec.constants.SECURITY_CONTEXT_V2_URL,
-    id: rootCapabilityId,
-    invocationTarget: rootInvocationTarget,
-    controller
-  };
-}
-
-function _hasBody({req}) {
-  // a request has a body if `transfer-encoding` or `content-length` headers
-  // are set: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.3
-  return req.body &&
-    (req.get('transfer-encoding') !== undefined ||
-    req.get('content-length') !== undefined);
-}

package/lib/helpers.js

@@ -0,0 +1,225 @@
+/*!
+ * Copyright (c) 2021 Digital Bazaar, Inc. All rights reserved.
+ */
+import assert from 'assert-plus';
+import asyncHandler from 'express-async-handler';
+import {constants as zCapConstants} from '@digitalbazaar/zcapld';
+import * as helpers from './helpers.js';
+import {parseSignatureHeader} from 'http-signature-header';
+import {verifyHeaderValue} from '@digitalbazaar/http-digest-header';
+
+const {ZCAP_CONTEXT_URL} = zCapConstants;
+
+const DEFAULT_ACTION_FOR_METHOD = new Map([
+  ['GET', 'read'],
+  ['HEAD', 'read'],
+  ['OPTIONS', 'read'],
+  ['POST', 'write'],
+  ['PUT', 'write'],
+  ['PATCH', 'write'],
+  ['DELETE', 'write'],
+  ['CONNECT', 'write'],
+  ['TRACE', 'write'],
+  ['PATCH', 'write']
+]);
+
+export const ZCAP_ROOT_PREFIX = 'urn:zcap:root:';
+
+// middleware used to collect expected values for zcap authorization
+export function createExpectationMiddleware({
+  expectedHost, getExpectedTarget,
+  expectedAction, getExpectedAction,
+  getExpectedRootCapabilityId, onError
+}) {
+  assert.string(expectedHost, 'options.expectedHost');
+  assert.func(getExpectedTarget, 'options.getExpectedTarget');
+  assert.optionalString(expectedAction, 'options.expectedAction');
+  assert.optionalFunc(getExpectedAction, 'options.getExpectedAction');
+  assert.optionalFunc(
+    getExpectedRootCapabilityId, 'options.getExpectedRootCapabilityId');
+  assert.optionalFunc(onError, 'options.onError');
+
+  if(getExpectedAction && expectedAction !== undefined) {
+    throw new Error('Use "getExpectedAction" or "expectedAction", not both.');
+  }
+
+  return asyncHandler(async (req, res, next) => {
+    // cache ezcap express info
+    req.ezcap = {expectedHost};
+
+    const {headers} = req;
+    try {
+      const {params} = parseSignatureHeader(headers.authorization);
+      req.ezcap.signature = {params};
+    } catch(e) {
+      const error = new Error('Missing or invalid "authorization" header.');
+      error.name = 'DataError';
+      error.cause = e;
+      return helpers.handleError({error, onError});
+    }
+
+    // if body is present, ensure header digest value matches digest of body
+    if(helpers.hasBody({req})) {
+      const {digest: expectedDigest} = headers;
+      if(!expectedDigest) {
+        const error = new Error(
+          'A "digest" header must be present when an HTTP body is present.');
+        error.name = 'DataError';
+        error.httpStatusCode = 400;
+        return helpers.handleError({error, onError});
+      }
+      const {verified} = await verifyHeaderValue({
+        data: req.body, headerValue: expectedDigest});
+      if(!verified) {
+        const error = new Error(
+          'The "digest" header value does not match digest of body.');
+        error.name = 'DataError';
+        error.httpStatusCode = 400;
+        return helpers.handleError({error, onError});
+      }
+    } else {
+      // prevent any unhandled `req.body` from being erroneously used
+      req.body = undefined;
+    }
+
+    try {
+      // getExpectedTarget may throw an error
+      req.ezcap.expectedTarget = await helpers.getExpectedTarget(
+        {req, getExpectedTarget});
+    } catch(error) {
+      return helpers.handleError({error, onError});
+    }
+
+    // set expected action
+    req.ezcap.expectedAction = expectedAction;
+
+    // use `getExpectedAction` if provided
+    if(getExpectedAction) {
+      req.ezcap.expectedAction = await getExpectedAction({req});
+    }
+
+    /* Note: This is safe as long as the server's request handling
+    infrastructure differentiates based on HTTP method (as is typical practice
+    with express/connect routing). So, while the client specifies the HTTP
+    method, the server specifies the handler for that HTTP method. For example,
+    this middleware will ensure that if a client specifies "POST" then it
+    must be invoking a zcap that grants "write" action authority. Then,
+    provided that the server's router ensures that only the "POST" handler will
+    be executed (typical routing practice), all is well. If the handler code is
+    chosen via some other means, e.g., via the request body, then the caller
+    MUST provide the expected action and not rely on default behavior. */
+    if(req.ezcap.expectedAction === undefined) {
+      req.ezcap.expectedAction = DEFAULT_ACTION_FOR_METHOD.get(req.method);
+      if(req.ezcap.expectedAction === undefined) {
+        const error = new Error(
+          `The HTTP method ${req.method} has no expected capability action.`);
+        error.name = 'NotSupportedError';
+        error.httpStatusCode = 400;
+        return helpers.handleError({error, onError});
+      }
+    }
+
+    try {
+      req.ezcap.expectedRootCapability = await helpers
+        .getExpectedRootCapability({
+          req, expectedHost,
+          expectedTarget: req.ezcap.expectedTarget,
+          expectedAction: req.ezcap.expectedAction,
+          getExpectedRootCapabilityId
+        });
+    } catch(error) {
+      return helpers.handleError({error, onError});
+    }
+
+    // call `next` on the next tick to ensure the promise from this function
+    // resolves and does not reject because some subsequent middleware throws
+    // an error
+    process.nextTick(next);
+  });
+}
+
+export function handleError({error, onError, throwError = true}) {
+  if(onError) {
+    return onError({error});
+  }
+  if(throwError) {
+    throw error;
+  }
+}
+
+export function wrappedDocumentLoader({
+  req, documentLoader, expectedHost, expectedTarget, expectedAction,
+  getRootController
+}) {
+  return async url => {
+    if(url.startsWith(ZCAP_ROOT_PREFIX)) {
+      const document = await getRootCapability({
+        getRootController, req, expectedHost, expectedTarget, expectedAction,
+        rootCapabilityId: url
+      });
+
+      return {
+        contextUrl: null,
+        documentUrl: url,
+        document,
+      };
+    }
+
+    return documentLoader(url);
+  };
+}
+
+export async function getExpectedRootCapability({
+  req, expectedHost, expectedTarget, expectedAction,
+  getExpectedRootCapabilityId
+}) {
+  if(getExpectedRootCapabilityId) {
+    // retrieve the root capability given the request and expected params
+    // return value can be a string or an array of strings
+    return getExpectedRootCapabilityId({
+      req, expectedHost, expectedTarget, expectedAction
+    });
+  }
+  if(Array.isArray(expectedTarget)) {
+    return expectedTarget.map(
+      t => `${ZCAP_ROOT_PREFIX}${encodeURIComponent(t)}`);
+  }
+  return `${ZCAP_ROOT_PREFIX}${encodeURIComponent(expectedTarget)}`;
+}
+
+export async function getExpectedTarget({req, getExpectedTarget}) {
+  const {expectedTarget} = await getExpectedTarget({req});
+  if(!(typeof expectedTarget === 'string' ||
+    Array.isArray(expectedTarget))) {
+    throw new Error(
+      'Return value from "getExpectedTarget" must be an object with ' +
+      '"expectedTarget" set to a string or an array.');
+  }
+  return expectedTarget;
+}
+
+export async function getRootCapability({
+  getRootController, req, expectedHost, expectedTarget, expectedAction,
+  rootCapabilityId
+}) {
+  const rootInvocationTarget = decodeURIComponent(
+    rootCapabilityId.substr(ZCAP_ROOT_PREFIX.length));
+  const controller = await getRootController({
+    req, expectedHost, expectedTarget, expectedAction,
+    rootCapabilityId, rootInvocationTarget
+  });
+  return {
+    '@context': ZCAP_CONTEXT_URL,
+    id: rootCapabilityId,
+    invocationTarget: rootInvocationTarget,
+    controller
+  };
+}
+
+export function hasBody({req}) {
+  // a request has a body if `transfer-encoding` or `content-length` headers
+  // are set: http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.3
+  return req.body &&
+    (req.get('transfer-encoding') !== undefined ||
+    req.get('content-length') !== undefined);
+}

package/lib/main.js

@@ -2,3 +2,4 @@
  * Copyright (c) 2021 Digital Bazaar, Inc. All rights reserved.
  */
 export {authorizeZcapInvocation} from './authorize.js';
+export {authorizeZcapRevocation} from './revoke.js';

package/lib/revoke.js

@@ -0,0 +1,189 @@
+/*!
+ * Copyright (c) 2021 Digital Bazaar, Inc. All rights reserved.
+ */
+import assert from 'assert-plus';
+import asyncHandler from 'express-async-handler';
+import {CapabilityDelegation} from '@digitalbazaar/zcapld';
+import * as helpers from './helpers.js';
+import * as jsigs from 'jsonld-signatures';
+import {authorizeZcapInvocationAfterParse} from './authorize.js';
+
+/**
+ * Authorizes a request to submit a zcap revocation.
+ *
+ * @param {object} options - Options hashmap.
+ * @param {object} options.documentLoader - Document loader used to load
+ *   DID Documents, capability documents, and JSON-LD Contexts.
+ * @param {string} options.expectedHost - The expected host for the invoked
+ *   capability.
+ * @param {Function} options.getExpectedTarget - Used to return the expected
+ *   target(s) for the invoked capability.
+ * @param {Function} options.getRootController - Used to get the root
+ *   capability controller for the given root capability ID.
+ * @param {Function} options.suiteFactory - A factory for creating the
+ *   supported suite(s) to use when verifying digital signatures.
+ * @param {boolean} [options.allowTargetAttenuation=true] - Allow the
+ *   invocationTarget of a delegation chain to be increasingly restrictive
+ *   based on a hierarchical RESTful URL structure.
+ * @param {Function} [options.getExpectedRootCapabilityId] - Used to return the
+ *   expected root capability identifiers for the expected targets.
+ * @param {Function} [options.inspectCapabilityChain] - A function that can
+ *   inspect a capability chain, e.g., to check for revocations.
+ * @param {Function} [options.onError] - An error handler handler for
+ *   customizable error handling.
+ *
+ * @returns {Function} Returns an Express.js style middleware route handler.
+ */
+export function authorizeZcapRevocation({
+  documentLoader, expectedHost, getExpectedTarget, getRootController,
+  allowTargetAttenuation = true, getExpectedRootCapabilityId,
+  inspectCapabilityChain, onError, suiteFactory
+}) {
+  assert.func(suiteFactory, 'options.suiteFactory');
+
+  // expected action is always `write` for submitting a revocation
+  const expectedAction = 'write';
+  return [
+    helpers.createExpectationMiddleware({
+      expectedHost, expectedAction, getExpectedTarget,
+      getExpectedRootCapabilityId, onError
+    }),
+    verifyCapabilityDelegation({
+      documentLoader, getRootController, suiteFactory, inspectCapabilityChain,
+      onError
+    }),
+    authorizeZcapInvocationAfterParse({
+      documentLoader, getRootController: _getRevocationRootController,
+      suiteFactory, allowTargetAttenuation, inspectCapabilityChain, onError
+    })
+  ];
+}
+
+function verifyCapabilityDelegation({
+  documentLoader, getRootController, inspectCapabilityChain, suiteFactory,
+  onError
+}) {
+  return asyncHandler(async function getDelegator(req, res, next) {
+    const {
+      expectedAction, expectedHost, expectedTarget, expectedRootCapability
+    } = req.ezcap;
+
+    const {body: capability} = req;
+
+    // early-disallow revocation of root zcaps that follow ID convention
+    if(capability.id.startsWith(helpers.ZCAP_ROOT_PREFIX)) {
+      const error = new Error('A root capability cannot be revoked.');
+      error.name = 'NotAllowedError';
+      return helpers.handleError({error, onError});
+    }
+
+    // verify CapabilityDelegation
+    let delegator;
+    const chainControllers = [];
+    try {
+      const results = await _verifyDelegation({
+        capability,
+        documentLoader: helpers.wrappedDocumentLoader({
+          req, documentLoader, expectedHost, expectedTarget, expectedAction,
+          getRootController
+        }),
+        expectedRootCapability,
+        inspectCapabilityChain: _captureChainControllers({
+          inspectCapabilityChain,
+          chainControllers
+        }),
+        suiteFactory
+      });
+      ({delegator} = results[0].purposeResult);
+      delegator = delegator.id || delegator;
+    } catch(e) {
+      const error = new Error('The provided capability delegation is invalid.');
+      error.name = 'DataError';
+      error.cause = e;
+      return helpers.handleError({error, onError});
+    }
+
+    req.zcapRevocation = {delegator, chainControllers};
+
+    // proceed to next middleware on next tick to prevent subsequent
+    // middleware from potentially throwing here
+    process.nextTick(next);
+  });
+}
+
+async function _verifyDelegation({
+  req, capability, documentLoader,
+  expectedRootCapability, inspectCapabilityChain, suiteFactory
+}) {
+  const {verified, error, results} = await jsigs.verify(capability, {
+    suite: await suiteFactory({req}),
+    purpose: new CapabilityDelegation({
+      allowTargetAttenuation: true,
+      expectedRootCapability,
+      inspectCapabilityChain,
+      suite: await suiteFactory({req})
+    }),
+    documentLoader
+  });
+  if(!verified) {
+    throw error;
+  }
+  return results;
+}
+
+async function _getRevocationRootController({
+  req, rootCapabilityId, rootInvocationTarget, getRootController,
+  revocationsSubPath = '/revocations/'
+}) {
+  // if `revocations` is not in the root invocation target, then defer to
+  // `getRootController` to try and provide the root controller
+  if(!rootInvocationTarget.includes(revocationsSubPath)) {
+    return getRootController({req, rootCapabilityId, rootInvocationTarget});
+  }
+
+  /* Note: If the invocation target is a zcap-specific revocation endpoint,
+  we use all zcap controllers from the submitted zcap's chain as the root
+  controller value for the target.
+
+  This approach allows any party that has delegated a zcap or received one
+  to be able to send it for revocation. Subsequent code (in the revocation
+  route handler) will confirm that the delegation is proper and the zcap from
+  which it was delegated has not itself been revoked.
+
+  To be clear, if the delegation chain is:
+
+  root -> A -> B
+
+  Any zcap controller in the chain of B may invoke a root zcap with a
+  `target` of `<baseUrl>/revocations/<ID of B>` (and an ID of
+  `urn:zcap:root:encodeURIComponent(<baseUrl>/revocations/<ID of B>)`). This
+  means that `root`, `A`, or `B` may revoke `B`.
+
+  As long no other zcap in the chain of `B` (e.g., `A`) has already been
+  revoked, then `B` will be revoked and stored as a revocation until `B`
+  expires. */
+
+  // use all `chainControllers`
+  // presumes `verifyCapabilityDelegation` middleware already called
+  return req.zcapRevocation.chainControllers;
+}
+
+function _captureChainControllers({inspectCapabilityChain, chainControllers}) {
+  return async function _inspectCapabilityChain(chainDetails) {
+    // collect every controller in the chain
+    const {capabilityChain} = chainDetails;
+    for(const capability of capabilityChain.values()) {
+      chainControllers.push(..._getCapabilityControllers({capability}));
+    }
+    return inspectCapabilityChain(chainDetails);
+  };
+}
+
+function _getCapabilityControllers({capability}) {
+  const {controller, id} = capability;
+  const result = controller || id;
+  if(!result) {
+    return [];
+  }
+  return Array.isArray(result) ? result : [result];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/ezcap-express",
-  "version": "4.1.1",
+  "version": "4.4.0",
   "main": "lib",
   "module": "main.js",
   "repository": {
@@ -16,26 +16,40 @@
     "generate-readme": "jsdoc2md -t readme-template.hbs lib/*.js > README.md",
     "lint": "eslint .",
     "test": "npm run test-node",
-    "test-node": "cross-env NODE_ENV=test mocha -r esm --preserve-symlinks -t 30000 -A -R ${REPORTER:-spec} --require tests/test-mocha.js tests/*.spec.js"
+    "test-node": "cross-env NODE_ENV=test mocha -r esm --preserve-symlinks -t 30000 -A -R ${REPORTER:-spec} --require tests/test-mocha.js tests/*.spec.js",
+    "coverage": "cross-env NODE_ENV=test ESM_OPTIONS='{cache:false}' nyc --reporter=lcov --reporter=text-summary npm test",
+    "coverage-ci": "cross-env NODE_ENV=test ESM_OPTIONS='{cache:false}' nyc --reporter=lcovonly npm test",
+    "coverage-report": "nyc report"
   },
   "dependencies": {
     "@digitalbazaar/ed25519-signature-2020": "^3.0.0",
     "@digitalbazaar/http-digest-header": "^1.0.1",
+    "@digitalbazaar/zcapld": "^5.1.2",
     "assert-plus": "^1.0.0",
     "esm": "^3.2.25",
     "express-async-handler": "^1.1.4",
     "http-signature-header": "^2.0.2",
     "http-signature-zcap-verify": "^8.1.1",
-    "security-context": "^4.0.0"
+    "jsonld-signatures": "^9.3.0"
   },
   "devDependencies": {
+    "@digitalbazaar/did-method-key": "^2.0.0",
+    "@digitalbazaar/ezcap": "^1.0.0",
+    "@digitalbazaar/http-client": "^2.0.1",
+    "@digitalbazaar/security-document-loader": "^1.1.1",
+    "bnid": "^2.1.0",
     "chai": "^4.2.0",
+    "chai-http": "^4.3.0",
     "cross-env": "^7.0.2",
     "eslint": "^7.30.0",
     "eslint-config-digitalbazaar": "^2.6.1",
     "eslint-plugin-jsdoc": "^32.2.0",
+    "express": "^4.17.1",
+    "http-signature-zcap-invoke": "^3.1.0",
     "jsdoc-to-markdown": "^6.0.1",
-    "mocha": "^8.1.3"
+    "mocha": "^8.1.3",
+    "nyc": "^15.1.0",
+    "zcap-context": "^1.2.1"
   },
   "engines": {
     "node": ">=14.0.0"