Re: The ezcap library

The one thing you know is that any invoker of a resource must understand
the API.  In Zebra Copy we took advantage of that fact by representing each
method of the API being authorized as a string included in the
authorization certificate.  I don't think that would be much harder for
developers to understand.  In the case of RESTful services, you could allow
all 4 CRUD methods instead of just Read and Update.

--------------
Alan Karp


On Sun, Apr 4, 2021 at 6:42 AM Manu Sporny <msporny@digitalbazaar.com>
wrote:

> 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
>
>
>