This week we added commenting functionality to our document editor, Chalk, as a proof of concept of more complicated application defined permissions that are possible with atproto spaces and our ReBAC API. 

An image showing a comment on the title of the document where we wrote this post, which says "This is a comment!"

For a bit of background context: the spaces proposal lays out a new atproto primitive for controlling access to private data. A cool feature of the proposal is that it leaves room for multiple "space management" implementations that define how spaces are created and permissioned. Since the protocol only says that the space host must grant a "space credential" to let a client access a space, the space host can define arbitrary policies around who it grants space credentials to.

PDSes will be required to ship with the simplespace API. The Open Social Working Group is iterating on a "group" host API (which Habitat organizations implement). Standardizing these will let apps remain interoperable for a good chunk of use cases. However, for collaborative apps required in a workplace setting, we think there's room for a more fine-grained permission system.

That's why we've developed a relationship-based access control API for managing spaces. There are a couple important considerations for our API:

  1. 1.

    The relationships need to be legible to client applications in order for them to enforce the permissions themselves.

  2. 2.

    The primitives need to be simple but powerful enough that applications can compose rules to represent arbitrary access control policies across users and spaces

Implementing comments for Chalk turned out to be a great showcase of this API's capabilities!

Defining roles for our application

Chalk now supports three application-defined roles on a document with increasing capabilities: viewer, commenter, editor. Viewers can only view a document and its comments; commenters can view and add comments; editors can view, add comments, and contribute changes to the doc. 

Putting comments in their own space

We've been thinking about spaces as abstractions for "permission boundaries". Any concept that has its own set of read or write permissions gets its own space. In Chalk, each document is a network.habitat.docs space since it has its own access boundary. Viewers can read from the document space and editors can write into it. 

Since commenters can't write into the network.habitat.docs space, we need a separate space to represent the new permission boundary. Hence, we give commenters write permission to network.habitat.docs.comments where the comment records will live. However, we don't want to have to copy permission grants across these 2 spaces (for example, if an editor is added to the doc, we don't want to have to duplicate them to the comments space as well). So, we create "space relations" between them, enabled by our ReBAC API. Three space relations can be used to represent the viewer, commenter, editor roles:

  1. 1.

    docs readers are also comments readers

  2. 2.

    docs writers are also comments writers

  3. 3.

    comments writers are also docs readers

A diagram showing how the document and document comments space relate to each other, via the relations laid out above.

You can explore these relations on our spaces page here.

When applications want to grant the commenter role, they simply add them as a user relation to the comment space. This automatically grants them reader permission on the doc contents in the network.habitat.docs space.

Space inheritance as a standard

We think inheriting permissions between spaces is a powerful primitive that can let applications represent exactly the role semantics needed for their use case while still being simple enough to remain legible to other apps. Others in the community like HappyView seem to agree. However, since this is not included in the proposed protocol, this functionality runs the risk of being fragmented across apps. To remain interoperable, we're hoping to standardize on a solution for this and we'll continue experimenting to figure out the right API. This is the Discourse post where we've kicked off discussion around this possible standard.

We'd love to hear what folks think about this approach and the commenting feature! Join our Discord to give feedback and ask questions! Our API documentation for this feature is here.

- Habitat team