@digitalbazaar/ezcap-express 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @digitalbazaar/ezcap-express Changelog
 
+## 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

package/lib/revoke.js

@@ -48,32 +48,18 @@ export function authorizeZcapRevocation({
       expectedHost, expectedAction, getExpectedTarget,
       getExpectedRootCapabilityId, onError
     }),
-    getDelegator({
+    verifyCapabilityDelegation({
       documentLoader, getRootController, suiteFactory, inspectCapabilityChain,
       onError
     }),
     authorizeZcapInvocationAfterParse({
       documentLoader, getRootController: _getRevocationRootController,
       suiteFactory, allowTargetAttenuation, inspectCapabilityChain, onError
-    }),
-    function(req, res, next) {
-      // ensure that the invoker of the write capability is the delegator
-      // of the capability to be revoked
-      const {zcapRevocation: {delegator}} = req;
-      const invoker = req.zcap.controller || req.zcap.invoker;
-      if(delegator !== invoker) {
-        const error = new Error(
-          'Permission denied; the zcap invoker must be the delegator of the ' +
-          'zcap that is to be revoked.');
-        error.name = 'NotAllowedError';
-        return next(error);
-      }
-      next();
-    }
+    })
   ];
 }
 
-function getDelegator({
+function verifyCapabilityDelegation({
   documentLoader, getRootController, inspectCapabilityChain, suiteFactory,
   onError
 }) {
@@ -82,9 +68,18 @@ function getDelegator({
       expectedAction, expectedHost, expectedTarget, expectedRootCapability
     } = req.ezcap;
 
-    // verify CapabilityDelegation
     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,
@@ -93,7 +88,10 @@ function getDelegator({
           getRootController
         }),
         expectedRootCapability,
-        inspectCapabilityChain,
+        inspectCapabilityChain: _captureChainControllers({
+          inspectCapabilityChain,
+          chainControllers
+        }),
         suiteFactory
       });
       ({delegator} = results[0].purposeResult);
@@ -105,7 +103,7 @@ function getDelegator({
       return helpers.handleError({error, onError});
     }
 
-    req.zcapRevocation = {delegator};
+    req.zcapRevocation = {delegator, chainControllers};
 
     // proceed to next middleware on next tick to prevent subsequent
     // middleware from potentially throwing here
@@ -144,39 +142,48 @@ async function _getRevocationRootController({
   }
 
   /* Note: If the invocation target is a zcap-specific revocation endpoint,
-  we use the delegator of the zcap as the root controller for the target.
+  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 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.
+  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
 
-  Then the delegator of B may invoke a root zcap: `urn:zcap:root:<ID of B>`
-  with a target of `<baseUrl>/revocations/<ID of B>`. As long as `A` has not
-  also been revoked, then `B` will be revoked and stored as a revocation until
-  `B` expires. */
-
-  // ensure the `rootInvocationTarget` matches the request URL (i.e., that
-  // the caller POSTed a zcap with an ID that matches up with the URL to
-  // which they POSTed); this is not a security issue if this check is not
-  // performed, however, it can help clients debug errors on their end
-  const requestUrl = `${req.protocol}://${req.get('host')}${req.url}`;
-  if(rootInvocationTarget !== requestUrl) {
-    const error = new Error(
-      'The request URL does not match the root invocation target. Ensure ' +
-      'that the capability is sent to a URL that includes its ID.');
-    error.name = 'URLMismatchError';
-    error.details = {
-      rootInvocationTarget,
-      requestUrl
-    };
-    throw error;
-  }
+  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;
+}
 
-  // presumes `getDelegator` middleware already called
-  return req.zcapRevocation.delegator;
+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.2.0",
+  "version": "4.3.0",
   "main": "lib",
   "module": "main.js",
   "repository": {