@digitalbazaar/zcapld

zcapld (@digitalbazaar/zcapld)

Javascript reference implementation for Authorization Capabilities for Linked Data.

Table of Contents

• Background
• Security
• Install
• Usage
• Contribute
• Commercial Support
• License

Background

TODO

Security

TBD

Install

• Node.js 12+ is required.

To install from NPM:

npm install @digitalbazaar/zcapld

To install locally (for development):

git clone https://github.com/digitalbazaar/zcapld.git
cd zcapld
npm install

Usage

TBD

Contribute

See the contribute file!

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: [e-mail]

License

New BSD License (3-clause) © Digital Bazaar

Changelog

6.0.0 - 2022-01-11

Added

• Add createRootCapability helper function to construct root zcaps from a root invocation target and a root controller.
• Add local validation during delegation to prevent accidental delegation of zcaps that violate delegation rules that a verifier would always reject.
• Add maxClockSkew param that defaults to 300 seconds. This parameter defines the maximum clock skew that will be accepted when comparing capability expiration date-times against the current date (or other specified date) and when comparing a capability invocation proof against the capability's delegation proof.

Changed

• BREAKING: Root zcaps MUST specify an invocationTarget. This eliminates optionality, simplifying implementations.
• BREAKING: Root zcaps MUST be passed by reference to their ID when invoking and they will be expressed by reference (just their ID) in a capability invocation proof. Delegated zcaps MUST be fully embedded (pass full object) when invoking and they will be fully embedded in a capability invocation proof.
• BREAKING: When creating a capability delegation proof, a new parameter parentCapability MUST be passed so that the chain can be auto-computed. Passing capabilityChain is no longer permitted.
• BREAKING: Require capabilityAction when creating capability invocation proofs and expectedAction when verifying proofs; removing previous optionality simplifies implementations.
• BREAKING: Changed default to check for chain date monotonicity and removed the option to do otherwise. This was an expected change for the next major breaking release.
• BREAKING: expires is not permitted on root capabilities and is required on delegated capabilities. Removing optionality here simplifies implementations and improves security by reducing surface and providing an "out" for zcaps that can not be easily revoked by causing them to always expire eventually.
• BREAKING: Combine currentDate and date parameters that were serving the same purpose. These params are only used for verification and the date parameter is used by the base class provided by jsonld-signatures, so the currentDate parameter has been removed; use date instead, it is only used for verification of proofs, not creation of proofs.
• BREAKING: invocationTarget MUST be specified in capability invocation proofs, it will not default to the invocationTarget specified in the capability. Removing this optionality removes complexity in implementations.
• BREAKING: capabilityChain and capabilityChainMeta that are passed to inspectCapabilityChain include entries for the root capability. The verifyResult is null for the root zcap.
• BREAKING: allowTargetAttenuation=true allows both path- or query-based invocation target attenuation. Turning this on means a verifier will allow accept delegations (and invocations) where a suffix has been added to the parent zcap's invocation target (invoked zcap's invocation target). The suffix must starts with / or ? if the invocation target prefix has no ? and & otherwise.

Removed

• BREAKING: Removed support for using invoker and delegator properties. Only controller is now permitted and it is required, i.e., a ZCAP MUST have a controller property, the value of the ZCAP's id property is not considered a default controller value for the ZCAP. This change simplifies ZCAP implementations and better reflects the fact that a delegation cannot actually be restricted -- a system can only force users to use data model and protocol-external mechanisms to delegate. This change keeps all delegation within the data model/protocol for improved auditability.
• BREAKING: Removed support for vocab-modeled custom caveats. Custom caveats should instead be modeled a combination of capability actions and path- or query-based attenuation of invocation targets. This approach provides the flexibility required to model custom caveats without the overhead of building and maintaining custom contexts and vocabularies. The common case is that custom caveats are specific to particular APIs rather than shared commonly across many different standardized APIs -- so it is unnecessarily burdensome to require the creation ofLinked Data vocabularies and contexts to represent them when using localized API-specific capability actions and invocation target paths will suffice. Common caveats such as expiration dates are provided as a part of the core model -- and should any other common caveats become evident, they can be added to the core model over time.
• BREAKING: Removed support for allowing the last delegated zcap in a capability chain to be expressed by reference. Instead, if the last zcap in the chain is delegated, it MUST be fully embedded. All other zcaps MUST be expressed via reference to their ID. Therefore, a capability chain MUST always consist of: the root zcap ID, any non-last delegated zcap IDs, and, for chains longer than 1 (excluding the final zcap or 2 if inclusive), the fully embedded last delegated zcap. This simplifies implementations, removes any concerns around mutability in dereferenced zcaps, and guarantees that all zcaps in a chain are available in an invocation. It does require that the invoker send the entire chain, however, this considered the best trade off.
• BREAKING: Removed ability to expire a root capability. There is no use case for this, so the complexity has been removed.
• BREAKING: Removed support for zcaps expressed using contexts other than the zcap-ld v1 context. The zcap spec will be updated to describe zcaps as JSON in a way that JSON-LD compatible, eliminating the need for supporting and JSON-LD context transformations beyond those used to create and verify proofs. This approach will not prohibit the future use of CBOR-LD to represent zcaps over the wire to greatly reduce size.