Solid ACL Utils [WIP]

A js library for working with acl files. It allows you to add/change/remove permissions of files and folders in solid pods.

Documentation

Due to a lack of time this is not as detailed as I'd like to and hasn't got that many examples. This will hopefully change in the future

Live example: https://otman.solid.community/public/solid-acl-utils/examples/

Installation

Currently this library is still in beta and not well tested. Therefore it isn't yet published on npm.

Via npm

WARNING: This is not really safe because it does not include a version and relies on the existence of this github repository

Install it from github

npm install otto-aa/solid-acl-utils

Import it in your code

const SolidAclUtils = require('solid-acl-utils')

// You could also use SolidAclUtils.Permissions.READ instead of following
// This is just more convenient
const { AclApi, AclDoc, AclParser, AclRule, Permissions, Agents } = SolidAclUtils
const { READ, WRITE, APPEND, CONTROL } = Permissions

Usage

Load the acl file

First of all we need to load the acl file. The library needs to do some authenticated http requests for that, so you will need to pass it a fetch method (e.g. from solid-auth-client)

// Passing it the fetch from solid-auth-client
const fetch = solid.auth.fetch.bind(solid.auth)

// Create an AclApi instance (one per acl file you want to load)
// If autoSave=true, the library will update the permissions with every change you make to the acl
// If autoSave=false you need to call acl.saveToPod() manually when you are ready
const aclApi = new AclApi(fetch, { autoSave: true })
const acl = await aclApi.loadFromFileUrl('https://pod.example.org/file.ttl')

// now we can make changes to acl and it will be automatically updated

Update permissions

This library is only a wrapper to solid-acl-parser. To get a better understanding of all the possibilities, please go to its documentation page.

The doc returned by loadFromFileUrl behaves exactly as the one from solid-acl-parser, except that it has a "saveToPod" method and if autoSave is enabled all methods which modify the document will store the changes in the pod and return a Promise.

const aclApi = new AclApi(fetch, { autoSave: true })
const acl = await aclApi.loadFromFileUrl('https://pod.example.org/file.ttl')

// The format for granting/checking/deleting permissions is
// acl.addRule([permissions], [webIds]/agents)
// For more granular control refer to the solid-acl-parser documentation

// Share the file/folder with another webId
await acl.addRule(READ, webId)

// Collaborate with another user
await acl.addRule([READ, WRITE], webId)

// Revoke permissions
await acl.deleteRule([READ, WRITE], webId)

// Give everyone read access
await acl.addRule(READ, Agents.PUBLIC)

// Check if someone else has writing access
const agents = acl.getAgentsWith(WRITE)
console.log([...agents.webIds]) // array containing all webIds which have write access
console.log([...agents.groups])
console.log(agents.hasPublic())
console.log(agents.hasAuthenticated()) // Authenticated means everyone who is logged in

// Get all permissions a specific user has
const permissions = acl.getPermissionsFor(webId)
permissions.has(READ) // true/false
permissions.has([READ, WRITE]) // true/false

Example using autoSave=false. Now the changes are made locally and only sent to the pod when saveToPod() is called. This is likely the better choice if you want to do more than one modification or want to preview changes before saving them.

const aclApi = new AclApi(fetch, { autoSave: false })
const acl = aclApi.loadFromFileUrl('https://pod.example.org/file.ttl')

acl.addRule([READ, WRITE], webId)
acl.addRule(READ, Agents.PUBLIC)

await acl.saveToPod()