@digitalbazaar/ezcap-express 5.1.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @digitalbazaar/ezcap-express Changelog
 
+## 6.0.0 - 2022-03-01
+
+### Changed
+- **BREAKING**: Better future proof conventional zcap API endpoints by
+  prefixing `/revocations` route with `/zcaps`.
+
 ## 5.1.0 - 2022-01-14
 
 ### Added

package/lib/revoke.js

@@ -12,9 +12,9 @@ import {CapabilityDelegation} from '@digitalbazaar/zcap';
  * Authorizes a request to submit a zcap revocation.
  *
  * This middleware is opinionated; it MUST be attached to an endpoint that
- * terminates in `/revocations/:revocationId`. This to enable the middleware to
- * automatically generate expected values for running zcap checks and to
- * support a common, conventional revocation API pattern.
+ * terminates in `/zcaps/revocations/:revocationId`. This to enable the
+ * middleware to automatically generate expected values for running zcap checks
+ * and to support a common, conventional revocation API pattern.
  *
  * The pattern is in support of controlled objects on a service, aka
  * "service objects". Each object's controller is used to populate the root
@@ -25,17 +25,17 @@ import {CapabilityDelegation} from '@digitalbazaar/zcap';
  * Therefore, any route that matches an invocation target for a root zcap for
  * a service SHOULD attach this middleware to:
  *
- * `<serviceObjectId>/revocations/:revocationId`.
+ * `<serviceObjectId>/zcaps/revocations/:revocationId`.
  *
  * This middleware will compute `serviceObjectId` by combining the expected
  * host with the subpath from the request URL that occurs before
- * `/revocations/`. It assumes that the request URL will have this pattern
- * if the middleware code has been reached. IOW, `serviceObjectId` will
+ * `/zcaps/revocations/`. It assumes that the request URL will have this
+ * pattern if the middleware code has been reached. IOW, `serviceObjectId` will
  * be set using:
  *
- * `https://<expectedHost>/<URL subpath before "/revocations/">`.
+ * `https://<expectedHost>/<URL subpath before "/zcaps/revocations/">`.
  *
- * Note: This middleware does NOT support having `/revocations/` appear
+ * Note: This middleware does NOT support having `/zcaps/revocations/` appear
  * multiple places in the request URL.
  *
  * Attaching this middleware will enable any zcaps delegated from the service
@@ -44,7 +44,7 @@ import {CapabilityDelegation} from '@digitalbazaar/zcap';
  * supporting the invocation of a dynamically generated root zcap with an
  * invocation target of:
  *
- * `<serviceObjectId>/revocations/:revocationId`.
+ * `<serviceObjectId>/zcaps/revocations/:revocationId`.
  *
  * This middleware will set the `controller` of this root zcap to all
  * controllers in the to-be-revoked zcap's delegation chain, permitting any
@@ -53,9 +53,9 @@ import {CapabilityDelegation} from '@digitalbazaar/zcap';
  * not have `<serviceObjectId>` as its invocation target (or a prefix of it).
  * This ensures that the only zcaps that have been delegated from a root zcap
  * using the service object's ID as part of its invocation target can be
- * revoked at its `/revocations` route, i.e., other zcaps intended for other
- * service objects -- or entirely other services -- cannot be revoked via this
- * middleware.
+ * revoked at its `/zcaps/revocations` route, i.e., other zcaps intended for
+ * other service objects -- or entirely other services -- cannot be revoked via
+ * this middleware.
  *
  * This middleware will automatically generate two sets of expects values: one
  * for checking the invocation to revoke a capability and one for verifying the
@@ -74,7 +74,7 @@ import {CapabilityDelegation} from '@digitalbazaar/zcap';
  *   // with an "id" of `revocationId`; RZ2's controller will be populated
  *   // using all controllers from Z2's chain, enabling any controller in that
  *   // zcap's chain to invoke RZ2 to revoke Z2
- *   `<serviceObjectId>/revocations/<revocationId>`,
+ *   `<serviceObjectId>/zcaps/revocations/<revocationId>`,
  * ],
  * action: 'write'
  * .
@@ -124,7 +124,8 @@ export function authorizeZcapRevocation({
       host: expectedHost,
       rootInvocationTarget: [
         serviceObjectId,
-        `${serviceObjectId}/revocations/${encodeURIComponent(revocationId)}`
+        `${serviceObjectId}/zcaps/revocations/` +
+          encodeURIComponent(revocationId)
       ]
     };
   }
@@ -150,11 +151,11 @@ export function authorizeZcapRevocation({
   return [
     asyncHandler(async function(req, res, next) {
       // ensure middleware is attached to opinionated route
-      if(!req.originalUrl.includes('/revocations/') ||
+      if(!req.originalUrl.includes('/zcaps/revocations/') ||
         !req.params.revocationId) {
         const error = new Error(
           'Revocation middleware must be attached to a route ending in ' +
-          '"/revocations/:revocationId".');
+          '"/zcaps/revocations/:revocationId".');
         error.httpStatusCode = 500;
         return helpers.handleError({res, error, onError});
       }
@@ -266,8 +267,8 @@ function _wrapGetRootController({expectedHost, getRootController}) {
   }) {
     const serviceObjectId = _parseServiceObjectId({req, expectedHost});
     const {revocationId} = req.params;
-    const zcapSpecificRootTarget =
-      `${serviceObjectId}/revocations/${encodeURIComponent(revocationId)}`;
+    const zcapSpecificRootTarget = `${serviceObjectId}/zcaps/revocations/` +
+      encodeURIComponent(revocationId);
 
     // if `rootInvocationTarget` doesn't match the zcap-specific root
     // invocation target, then use user-provided `getRootController` to provide
@@ -294,9 +295,9 @@ function _wrapGetRootController({expectedHost, getRootController}) {
     root -> A -> B
 
     Any zcap controller in the chain of B may invoke a root zcap with an
-    `invocationTarget` 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`.
+    `invocationTarget` of `<baseUrl>/zcaps/revocations/<ID of B>` (and an ID of
+    `urn:zcap:root:encodeURIComponent(<baseUrl>/zcaps/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 (storage must
@@ -328,8 +329,8 @@ function _getCapabilityControllers({capability}) {
 }
 
 function _parseServiceObjectId({req, expectedHost}) {
-  // `serviceObjectId` is full URL prior to `/revocations/`
-  const idx = req.originalUrl.indexOf('/revocations/');
+  // `serviceObjectId` is full URL prior to `/zcaps/revocations/`
+  const idx = req.originalUrl.indexOf('/zcaps/revocations/');
   const path = req.originalUrl.substring(0, idx);
   return `https://${expectedHost}${path}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalbazaar/ezcap-express",
-  "version": "5.1.0",
+  "version": "6.0.0",
   "main": "lib",
   "module": "main.js",
   "repository": {