@digitalbazaar/ezcap-express 4.2.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @digitalbazaar/ezcap-express Changelog
 
+## 4.5.0 - 2021-12-17
+
+### Fixed
+- Add `_createGetRevocationRootController` wrapper around
+  `_getRevocationRootController` and pass `getRootController` to it.
+
+### Added
+- Add tests for `authorizeZcapRevocation`.
+
+## 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

package/lib/helpers.js

@@ -10,6 +10,19 @@ 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
@@ -87,16 +100,23 @@ export function createExpectationMiddleware({
 
     /* 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
+    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
+    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 = req.method === 'POST' ? 'write' : 'read';
+      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 {

package/lib/revoke.js

@@ -48,32 +48,20 @@ export function authorizeZcapRevocation({
       expectedHost, expectedAction, getExpectedTarget,
       getExpectedRootCapabilityId, onError
     }),
-    getDelegator({
+    verifyCapabilityDelegation({
       documentLoader, getRootController, suiteFactory, inspectCapabilityChain,
       onError
     }),
     authorizeZcapInvocationAfterParse({
-      documentLoader, getRootController: _getRevocationRootController,
+      documentLoader,
+      getRootController: _createGetRevocationRootController(
+        {getRootController}),
       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 +70,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 +90,10 @@ function getDelegator({
           getRootController
         }),
         expectedRootCapability,
-        inspectCapabilityChain,
+        inspectCapabilityChain: _captureChainControllers({
+          inspectCapabilityChain,
+          chainControllers
+        }),
         suiteFactory
       });
       ({delegator} = results[0].purposeResult);
@@ -105,7 +105,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
@@ -133,50 +133,57 @@ async function _verifyDelegation({
   return results;
 }
 
-async function _getRevocationRootController({
-  req, rootCapabilityId, rootInvocationTarget, getRootController,
-  revocationsSubPath = '/revocations/'
+function _createGetRevocationRootController({
+  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 the delegator of the zcap as the root controller 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.
+  return async function _getRevocationRootController({
+    req, rootCapabilityId, rootInvocationTarget
+  }) {
+    // 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});
+    }
 
-  To be clear, if the delegation chain is:
+    /* 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. */
 
-  root -> A -> B
+    // use all `chainControllers`
+    // presumes `verifyCapabilityDelegation` middleware already called
+    return req.zcapRevocation.chainControllers;
+  };
+}
 
-  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. */
+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);
+  };
+}
 
-  // 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;
+function _getCapabilityControllers({capability}) {
+  const {controller, id} = capability;
+  const result = controller || id;
+  if(!result) {
+    return [];
   }
-
-  // presumes `getDelegator` middleware already called
-  return req.zcapRevocation.delegator;
+  return Array.isArray(result) ? result : [result];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/ezcap-express",
-  "version": "4.2.0",
+  "version": "4.5.0",
   "main": "lib",
   "module": "main.js",
   "repository": {
@@ -16,7 +16,10 @@
     "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",
@@ -30,13 +33,23 @@
     "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"