you-shall-pass v2.0.3
You Shall Pass is yet another ACL module for Javascript applications designed to be used on ES6 or Typescript projects.
With its companion modules express-you-shall-pass, and koa-you-shall-pass, it aims to be able to replace both passport and node-acl on NodeJS APIs, but can also be used client side.
It was written while designing an API to manage a restaurant chain, which is consumed by clients with different and overlapping permissions: administration, digital signage, public smartphone apps, cash registers, ...
Like many others, it allows to check if a user has permissions to access resources and perform actions.
Unlike others:
- It does not need a storage backend to store permissions: they will come from your own persistence layer.
- Your permissions model will be easy to unit test.
- It can give your detailed information on why you got allowed or not to perform actions and access resources.
- It can be extended to load arbitrary restrictions associated with the permissions.
- Permissions are not only either "yes" or "no". You can say "yes but only for ..." without creating many different roles.
- It comes with two examples that allow to restrict models on collections, and fields on models.
- You can teach it to alter your database queries to enforce permissions on lists with your SQL database.
As this module is security related:
- No production dependencies: feel free to audit the code and pin a version in your
package.json. - Dev-dependencies are limited to compilation and test tools.
- It is strictly typed with Typescript.
- It is fully unit tested.
How does it work
With you-shall-pass, there are no roles and resources, all of your permissions are defined in a single "Permission Graph".
For instance for a blog API, the graph should look like this:
+-----------+
| is_anyone |
+-----+-----+
|
If token |
If author flag is valid | If moderator flag
is set in the database v is set in the database
+-----------+ +--------+---------+ +--------------+
| is_author +<--------------+ is_authenticated +---------->+ is_moderator |
+-----+-----+ +--------+---------+ +-------+------+
| | |
| If author | |
Always | of the | Always |
| article | +-------------------------+
v v v v
+----------+---------+ +--------+---+-----+ +----------+---------+
| can_create_article | | can_edit_article | | can_delete_article |
+--------------------+ +------------------+ +--------------------+Usage
The permission graph
Todo: write documentation
const acl = new Acl(
// Default permission
'is_anyone',
// Permission graph edges
[
{
explain: "User carries a basic authentication token",
from: 'is_anyone',
to: 'is_authenticated',
check: async ctx => {
// Decode basic auth token.
const [username, password] =
Buffer.from(ctx.token.split(' '), 'base64').toString().split(/:/);
// Load user **into context**.
// It will be available for all other check functions.
ctx.user = await getUser(username);
// true if allowed, false otherwise
return ctx.user && bcrypt.verify(password, ctx.user.password);
}
},
{
explain: "User is a moderator",
from: 'is_authenticated',
to: 'is_moderator',
check: async ctx => ctx.user.isModerator
},
{
explain: 'Moderators can edit and delete all articles'
from: 'is_moderator',
to: ['can_edit_article', 'can_delete_article'],
},
{
explain: "Authors can edit their own articles",
from: 'is_authenticated',
to: 'can_edit_article',
check: async ctx => ctx.article.createdBy == ctx.user.email
},
[...]
]
);Checking permissions
Todo: write documentation
// Can we reach the 'can_edit_article' permission **for this article and authentication token**
const result = await acl.check('can_edit_article', {
token: 'Basic ZWxsaW90QGUtY29ycC5jb206YW5hcmNoeV9mdHc=',
article: {id: 1, text: "I ❤ Javascript", createdBy: 'elliot@e-corp.com'}
});
if (result !== null) {
// User is allowed to edit the article (result contains the current user because it was
// loaded during the checks).
assert.isNotNull(result.user);
}
else {
// User does not have the 'can_edit_article' permission in this context.
}Customizing "Permission denied" messages
A user can be allowed to perform an action because of many reasons. In the previous example, the permission to edit a given article can be reached either by the article author or by any moderator.
The same happens when a user is denied a permission: if a user is not allowed to edit a particular article, it is both because he is not a moderator, and because he is not the article's author.
By providing all nodes in the permission graph that were checked for a particular query, and the result of each check, the .explain() method provides insight about why a permission was granted or denied.
// Ask `you-shall-pass` details about last example.
const explanation = await acl.explain('can_edit_article', {
token: 'Basic ZWxsaW90QGUtY29ycC5jb206YW5hcmNoeV9mdHc=',
article: {id: 1, text: "I ❤ anarchy", createdBy: 'elliot@e-corp.com'}
});
// We can check why we were allowed to edit the article in the previous example.
explanation
.filter(e => e.to == 'can_edit_article' && e.checkPassed)
.map(e => e.explain);
> ['Authenticated users can edit their own article']
// We can also check paths that the acl checker tried, but which failed to reach the requested permission.
explanation
.filter(e => !e.checkPassed)
.map(e => e.explain);
> ['User is a moderator']Using restrictions
Todo: write documentation
Code structure
When dealing with complex permission graphs, if can quickly become inconvenient to handle the list of edges in a single file.
Todo: write documentation
To do
- Have meaningful errors when data is missing in the parameters (ie: when forgetting parameters, or attaching permissions to wrong nodes).
- Write proper documentation.
- Cache the paths between permissions.
- More tests with restrictions examples.
- Tests with explain feature.
- Express and Koa middlewares, on others repos.
- Set-up greenkeeper to keep dev dependencies up to date.