W3C home > Mailing lists > Public > public-credentials@w3.org > April 2021

The ezcap library

From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 4 Apr 2021 09:40:15 -0400
To: W3C Credentials CG <public-credentials@w3.org>
Message-ID: <6bbe778f-8f83-cb23-03f0-63f4c918332d@digitalbazaar.com>
Hi all,

The challenges that Nikos came across are familiar to most of us that try to
learn about zcaps. It's (understandably) difficult for most developers to get
their mind wrapped around the technology, largely due to a lack of good
articles and documentation.

Now might be a good time to announce some open source tooling a few of us have
been working on related to zcaps that is being created to simplify the
developer experience when developing with zcaps.

ezcap (pronounced "Easy Cap") - An easy to use, opinionated Authorization
Capabilities (zcap) client library for the browser and Node.js.

## Background

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.

## Security

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.

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
[zcapld](https://github.com/digitalbazaar/zcapld) 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:
`/<root-namespace>/<collection-id>/<item-id>`. In practice,
this tends to manifest itself as URLs that look like
`/my-account/things/1`. The ezcap approach maps the authorization model
in a 1-to-1 way to the URL. Following along with the example, the root
capability would then be `/my-account`, which you will typically create and
have access to. You can then take that root capability and delegate access
to things like `/my-account/things` to let entities you trust modify the
`things` collection. You can also choose to be more specific and only
delegate to `/my-account/things/1` 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.

You can read more about the API and how to use it here:

https://github.com/digitalbazaar/ezcap

-- manu

-- 
Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
blog: Veres One Decentralized Identifier Blockchain Launches
https://tinyurl.com/veres-one-launches
Received on Sunday, 4 April 2021 13:40:32 UTC

This archive was generated by hypermail 2.4.0 : Sunday, 4 April 2021 13:40:33 UTC