[](https://github.com/digitalbazaar/ezcap/actions?query=workflow%3A%22Node.js+CI%22)
npm install @digitalcredentials/ezcap
> An easy to use, opinionated Authorization Capabilities (zcap) client library
> for the browser and Node.js.
- Background
- Security
- Install
- Usage
- API Reference
- Contribute
- Commercial Support
- License
This library provides a client that browser and node.js applications can use to
interact with HTTP servers protected by zcap-based authorization. The library
is configured with secure and sensible defaults to help developers get started
quickly and ensure that their client code is production-ready.
The security characteristics of this library are largely influenced by design
decisions made by client and server software. For clients, implementers should
pay particular attention to secure private key management. For servers, security
characteristics are largely dependent on how carefully the server manages zcap
registrations, zcap invocations, and zcap delegations. Bugs or failures related
to client key management, or server zcap validity checking will lead to security
failures. It is imperative that implementers audit their implementations,
preferably via parties other than the implementer.
- Browsers and Node.js 14+ are supported.
- [Web Crypto API][] required. Older browsers and Node.js 14 must use a
polyfill.
To install from NPM:
``
npm install @digitalcredentials/ezcap
To install locally (for development):
`
git clone https://github.com/digitalcredentials/ezcap.git
cd ezcap
npm install
* Creating a Client
* Reading with a Root Capability
* Writing with a Root Capability
* Delegating a Capability
* Reading with a Delegated Capability
* Writing with a Delegated Capability
* Requesting with a Root Capability
* Requesting with a Delegated Capability
Creating a zcap client involves generating cryptographic key material and then
using that key material to instantiate a client designed to operate on a
specific base URL.
`js
import {ZcapClient} from '@digitalcredentials/ezcap';
import * as didKey from '@digitalcredentials/did-method-key';
import {Ed25519Signature2020} from '@digitalcredentials/ed25519-signature-2020';
const didKeyDriver = didKey.driver();
// generate a DID Document and set of key pairs
const {didDocument, keyPairs} = await didKeyDriver.generate();
// create a new zcap client using the generated cryptographic material
const zcapClient = new ZcapClient({
didDocument, keyPairs, SuiteClass: Ed25519Signature2020
});
`
Reading data from a URL using a capability is performed in a way that is
very similar to using a regular HTTP client to perform an HTTP GET. Using
a root capability means that your client has been directly authorized to access
the URL, usually because it created the resource that is being accessed.
The term "root" means that your client is the "root of authority".
`js
const url = 'https://zcap.example/my-account/items';
// reading a URL using a zcap will result in an HTTP Response
const response = await zcapClient.read({url});
// retrieve the JSON data
const items = await response.json();
`
Writing data to URL using a capability is performed in a way that is
very similar to using a regular HTTP client to perform an HTTP POST. Using
a root capability means that your client has been directly authorized to
modify the resource at the URL, usually because it created the resource that is
being written to. The term "root" means that your client is the "root of
authority". In the example below, the server most likely registered the
client as being the root authority for the /my-account path on the server.
`js
const url = 'https://zcap.example/my-account/items';
const item = {label: 'Widget'};
// writing a URL using a zcap will result in an HTTP Response
const response = await zcapClient.write({url, json: item});
// process the response appropriately
const writtenItem = await response.json();
`
Delegating a capability consists of the client authorizing another entity to
use the capability. The example below uses a DID as the target for the
delegation. The returned delegatedCapability would need to be transmitted
to the entity identified by the delegation target so that they can use it
to access the resource.
`js`
const invocationTarget = 'https://zcap.example/my-account/items';
const controller =
'did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH';
const allowedActions = ['read'];
const delegatedCapability = zcapClient.delegate(
{invocationTarget, controller, allowedActions});
Reading with a delegated capability is similar to reading with a root
capability. The only difference is that the delegated capability needs to be
retrieved from somewhere using application-specific code and then passed
to the read method.
`js
const url = 'https://zcap.example/my-account/items/123';
// defined by your code
const capability = await getCapabilityFromDatabase({url});
// reading a URL using a zcap will result in an HTTP Response; the
// invocationTarget from the capability provides the URL if one is not
// specified; if a URL is specified, the capability's invocation target
// MUST be a RESTful prefix of or equivalent to the URL
const response = await zcapClient.read({capability});
// retrieve the JSON data
const items = await response.json();
`
Writing with a delegated capability is similar to writing with a root
capability. The only difference is that the delegated capability needs to be
retrieved from somewhere using application-specific code and then passed
to the write method.
`js
const item = {label: 'Widget'};
const url = 'https://zcap.example/my-account/items';
// defined by your code
const capability = await getCapabilityFromDatabase({url});
// writing a URL using a zcap will result in an HTTP Response; the
// invocationTarget from the capability provides the URL if one is not
// specified; if a URL is specified, the capability's invocation target
// MUST be a RESTful prefix of or equivalent to the URL
const response = await zcapClient.write({capability, json: item});
// process the response appropriately
const writtenItem = await response.json();
`
`js`
const body = new Blob(['line 1\nline2\n'], {type: 'text/plain'})
await zcapClient.request({
url, method: 'POST', body
})
In the event that the server API does not operate using HTTP GET and HTTP POST,
it is possible to create a zcap client request that uses other HTTP verbs. This
is done by specifying the HTTP method to use.
`js
const url = 'https://zcap.example/my-account/items';
const item = {count: 12};
// send a request to a URL by invoking a capability
const response = await zcapClient.request({url, method: 'patch', json: item});
// process the response appropriately
const updatedItem = await response.json();
`
Performing an HTTP request with a delegated capability is similar to
doing the same with a root capability. The only difference is that the
delegated capability needs to be retrieved from somewhere using application-specific code and then passed to the request method.
`js
const item = {count: 12};
const url = 'https://zcap.example/my-account/items/123';
// defined by your code
const capability = await getCapabilityFromDatabase({url});
// invoking a capability against a URL will result in an HTTP Response; the
// invocationTarget from the capability provides the URL if one is not
// specified; if a URL is specified, the capability's invocation target
// MUST be a RESTful prefix of or equivalent to the URL
const response = await zcapClient.request(
{capability, method: 'patch', json: item});
// process the response appropriately
const updatedItem = await response.json();
`
The ezcap approach is opinionated in order to make using zcaps a pleasant
experience for developers. To do this, it makes two fundamental assumptions
regarding the systems it interacts with:
* The systems are HTTP-based and REST-ful in nature.
* The REST-ful systems center around reading and writing resources.
If these assumptions do not apply to your system, the
zcap library might
be a better, albeit more complex, solution for you.
Looking at each of these core assumptions more closely will help explain how designing systems to these constraints make it much easier to think about
zcaps. Let's take a look at the first assumption:
> The systems are HTTP-based and REST-ful in nature.
Many modern systems tend to have HTTP-based interfaces that are REST-ful in
nature. That typically means that most resource URLs are organized by namespaces, collections, and items:
/. In practice,/my-account/things/1
this tends to manifest itself as URLs that look like. The ezcap approach maps the authorization model/my-account
in a 1-to-1 way to the URL. Following along with the example, the root
capability would then be , which you will typically create and/my-account/things
have access to. You can then take that root capability and delegate access
to things like to let entities you trust modify thethings collection. You can also choose to be more specific and only/my-account/things/1
delegate to to really lock down access. ezcap attempts
to keep things very simple by mapping URL hierarchy to authorization scope.
Now, let's examine the second assumption that makes things easier:
> The REST-ful systems center around reading and writing resources.
There is an incredible amount of flexibility that zcaps provide. You can
define a variety of actions: read, write, bounce, atomicSwap, start, etc.
However, all that flexibility adds complexity and one of the goals of ezcap
is to reduce complexity to the point where the solution is good enough for
80% of the use cases. A large amount of REST-ful interactions tend to
revolve around reading and writing collections and the items in those
collections. For this reason, there are only two actions that are exposed
by default in ezcap: read and write. Keeping the number of actions to a
bare minimum has allowed implementers to achieve very complex use cases with
very simple code.
These are the two assumptions that ezcap makes and with those two assumptions,
80% of all use cases we've encountered are covered.
objectRetrieves the first set of capability invocation and delegation signers
associated with the didDocument from the keyPairs.
stringGenerate a zcap URI given a root capability URL or a delegated flag.
objectAn object that manages connection persistence and reuse for HTTPS requests.
objectAn class that can be instantiated to create a suite capable of generating a
Linked Data Signature. Its constructor must receive a signer instance
that includes .sign() function and id and controller properties.
* ZcapClient
* new ZcapClient(options)
* .delegate(options) ⇒ Promise.<object>
* .request(options) ⇒ Promise.<object>
* .read(options) ⇒ Promise.<object>
* .write(options) ⇒ Promise.<object>
Returns: ZcapClient - - The new ZcapClient instance.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| options.SuiteClass | LinkedDataSignatureSuiteClass | The LD signature suite class to use to sign requests and delegations. |
| [options.didDocument] | object | A DID Document that contains capabilityInvocation and capabilityDelegation verification relationships; didDocument and keyPairs, or invocationSigner and delegationSigner must be provided in order to invoke or delegate zcaps, respectively. |didDocument
| [options.keyPairs] | Map | A map of key pairs associated with indexed by key pair; didDocument and keyPairs, or invocationSigner and delegationSigner must be provided in order to invoke or delegate zcaps, respectively. |.sign()
| [options.delegationSigner] | object | An object with a function and id and controller properties that will be used for delegating zcaps; delegationSigner or didDocument and keyPairs must be provided to delegate zcaps. |.sign()
| [options.invocationSigner] | object | An object with a function and id and controller properties that will be used for signing requests; invocationSigner or didDocument and keyPairs must be provided to invoke zcaps. |
| [options.agent] | HttpsAgent | An optional HttpsAgent to use to when performing HTTPS requests. |
| [options.defaultHeaders] | object | The optional default HTTP headers to include in every invocation request. |
| [options.documentLoader] | function | Optional document loader to load suite-related contexts. If none is provided, one will be auto-generated if the suite class expresses its required context. |
Kind: instance method of ZcapClient
Returns: Promise.<object> - - A promise that resolves to a delegated
capability.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| [options.capability] | object | The parent capability to delegate; must be an object if it is a delegated zcap, can be a string if it is a root zcap but then invocationTarget must be specified; if not specified, this will be auto-generated as a root zcap for the given invocationTarget. |capability
| options.controller | string | The URL identifying the entity to delegate to, i.e., the party that will control the new zcap. |
| [options.invocationTarget] | string | Optional invocation target to use when narrowing a 's existing invocationTarget. Default is to use capability.invocationTarget, provided that capability is an object. |Date.now()
| [options.expires] | string \| Date | Optional expiration value for the delegation. Default is 5 minutes after . |
| [options.allowedActions] | string \| Array | Optional list of allowed actions or string specifying allowed delegated action. Default: [] - delegate all actions. |
Kind: instance method of ZcapClient
Returns: Promise.<object> - - A promise that resolves to an HTTP response.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| [options.url] | string | The URL to invoke the Authorization Capability against; if not provided, a capability must be provided instead. |
| [options.capability] | string \| object | The capability to invoke at the given URL. Default: generate root capability from options.url. |
| [options.method] | string | The HTTP method to use when accessing the resource. Default: 'get'. |
| [options.action] | string | The capability action that is being invoked. Default: 'read'. |
| [options.headers] | object | The additional headers to sign and send along with the HTTP request. Default: {}. |
| options.json | object | The JSON object, if any, to send with the request. |
Kind: instance method of ZcapClient
Returns: Promise.<object> - - A promise that resolves to an HTTP response.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| options.url | string | The URL to invoke the Authorization Capability against. |
| options.headers | object | The additional headers to sign and send along with the HTTP request. |
| [options.capability] | string | The capability to invoke at the given URL. Default: generate root capability from options.url. |
Kind: instance method of ZcapClient
Returns: Promise.<object> - - A promise that resolves to an HTTP response.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| options.url | string | The URL to invoke the Authorization Capability against. |
| options.json | object | The JSON object, if any, to send with the request. |
| [options.headers] | object | The additional headers to sign and send along with the HTTP request. |
| [options.capability] | string | The capability to invoke at the given URL. Default: generate root capability from options.url. |
object from the keyPairs.Kind: global function
Returns: object - - A valid
invocationSigner and delegationSigner
associated with the didDocument. | Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| options.didDocument | string | A DID Document containing verification relationships for capability invocation and delegation. |
| options.keyPairs | string | A map containing keypairs indexed by key ID. |
generateZcapUri(options) ⇒ string
Generate a zcap URI given a root capability URL or a delegated flag.Kind: global function
Returns: string - - A zcap URI.
| Param | Type | Description |
| --- | --- | --- |
| options | object | The options to use. |
| [options.url] | string | Optional URL identifying the root capability. |
HttpsAgent : object
An object that manages connection persistence and reuse for HTTPS requests.Kind: global typedef
See: https://nodejs.org/api/https.html#https_class_https_agent
LinkedDataSignatureSuiteClass : object
An class that can be instantiated to create a suite capable of generating a
Linked Data Signature. Its constructor must receive a instance
that includes .sign() function and id and controller` properties.Kind: global typedef
[Web Crypto API]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API