relations
entity relationship, role, and permissions API for Node.js
relations is a simple permissions API which uses a natural language approach.
Contexts
First, you'll create a context, which contains a list of roles which map to
actions. Here we'll create a context called repos
, to model Github repositories.
var relations = ; relations;
Defining the context makes available a method on relations
that matches the
context name, in this case, relations.repos()
. For permission checks, this is
the only method we'll need to call.
Dynamic roles
To add or modify roles at runtime, you can also use the following methods:
// add a role dynamicallyrelationsrepos;// update the actions for a rolerelationsrepos;// remove a rolerelationsrepos;
Please note that the role -> action map is defined exclusively in the code,
and not stored. If you run a cluster of servers, and choose to use dynamic roles,
you must call addRole()
etc on ALL servers in the cluster (I suggest using
pub/sub).
Declarations
Now, we need to tell our app who has those roles for which repos.
relations;
This assigns the role owner
to the subject Carlos
for the object buffet
.
Token replacements
Note that the API has multiple syntaxes, and this is functionally equivalent:
relations;
As is this:
relations;
To assign a role which should apply to all objects, simply leave the object out of the sentence:
relations;
Note: Using token replacements is recommended, to prevent injection attacks!
Syntax
The syntax for a declaration consists of:
<subject> is [ a / an / the ] <role> [ [ of / to / from / in / with ] <object> ] [.]
Verb question
To ask if a user can perform an action:
relations;
We can also check if an action can be performed on a specific object:
relations;
Syntax
The syntax for an verb question consists of:
( Can | can ) <subject> <verb> [ [ of / to / from / in / with ] <object> ] [?]
Role question
To check if a user has a role:
relations;
We can also leave the object out to check for a global role:
relations;
Syntax
The syntax for a role question consists of:
( Is | is ) <subject> [ a / an / the ] <role> [ [ of / to / from / in / with ] <object> ] [?]
Verb request
In addition to true/false checks, relations can return an array of objects which match certain criteria. For example:
relations;
Syntax
The syntax for a verb request consists of:
( What | what ) can <subject> <verb> [ of / to / from / in / with ] [?]
Role request
Also, we can ask for an array of objects a user has a role for:
relations;
Syntax
The syntax for a role request consists of:
( What | what ) is <subject> [ a / an / the ] <role> [ of / to / from / in / with ] [?]
Verb subject request
To request an array of subjects who can perform an action on an object:
relations;
Syntax
( Who | who ) can <verb> [ of / to / from / in / with ] <object> [?]
Role subject request
To request an array of subjects who have a role for an object:
relations;
Syntax
( Who | who ) is [ a / an / the ] <role> [ of / to / from / in / with ] <object> [?]
Object verb request
To request an array of verbs a subject can perform on an object:
relations;
Syntax
What actions can <subject> do [ of / to / from / in / with ] <object> [?]
Object-Role map request
To get a map of object->role pairs for a subject:
relations;
Syntax
[ Describe / detail / explain / get ] what <subject> can do [.]
Subject-Role map request
To get a map of subject->role pairs, optionally pertaining to an object:
relations;
relations;
Syntax
[ Describe / detail / explain / get ] who can act [ on <object> ] [.]
Revocation
To revoke a role:
relations;
Syntax
<subject> ( is not | isn't ) [ a / an / the ] <role> [ [ of / to / from / in / with ] <object> ] [.]
Persistence
Data can be persisted through database plugins or a flat
file. To use a flat file, initialize relations
like this:
var relations = ;relations;
relations
will store and load data, as a JSON blob, in the specified file.
Pluggable data store
Two additional data stores are provided: Redis and MySQL.
Redis store
To use the redis store, your app must make a node_redis client and pass it like so:
var relations = redis = relations;
MySQL store
To use the MySQL store, your app must make a node-mysql client and pass it like so:
var relations = mysql = relations;
Make your own store
A relations store is simply a node module that exports an event emitter and responds to the following events:
init
(options, cb)
Initialize the store with options
(from relations.use()
) and call cb(err)
when done.
declaration
(cmd, cb)
Respond to a declaration and call cb()
when done. cmd
will be an object
containing the properties:
- ctx - context object
- subject
- role
- object (optional)
revocation
(cmd, cb)
Respond to a revocation and call cb()
when done. cmd
will be an object
containing the properties:
- ctx - context object
- subject
- role
- object (optional)
verb-question
(cmd, cb)
Respond to a verb question and call cb(err, /* boolean */ can)
with the result.
cmd
will be an object containing the properties:
- ctx - context object
- subject
- verb
- object (optional)
role-question
(cmd, cb)
Respond to a role question and call cb(err, /* boolean */ is)
with the result.
cmd
will be an object containing the properties:
- ctx - context object
- subject
- role
- object (optional)
verb-request
(cmd, cb)
Respond to a verb request and call cb(err, /* array */ objects)
with the result.
cmd
will be an object containing the properties:
- ctx - context object
- subject
- verb
role-request
(cmd, cb)
Respond to a role request and call cb(err, /* array */ objects)
with the result.
cmd
will be an object containing the properties:
- ctx - context object
- subject
- role
verb-subject-request
(cmd, cb)
Respond to a verb subject request and call cb(err, /* array */ subjects)
with
the result. cmd
will be an object containing the properties:
- ctx - context object
- verb
- object
role-subject-request
(cmd, cb)
Respond to a role subject request and call cb(err, /* array */ subjects)
with
the result. cmd
will be an object containing the properties:
- ctx - context object
- role
- object
object-verb-request
(cmd, cb)
Respond to an object verb request and call cb(err, /* array */ verbs)
with
the result. cmd
will be an object containing the properties:
- ctx - context object
- object
- subject
object-role-map-request
(cmd, cb)
Respond to an object-role map request and call cb(err, /* object */ map)
with
the result. cmd
will be an object containing the properties:
- ctx - context object
- subject
subject-role-map-request
(cmd, cb)
Respond to a subject-role map request and call cb(err, /* object */ map)
with
the result. cmd
will be an object containing the properties:
- ctx - context object
- object (optional)
reset
(cb)
Reset the store, dumping all storage and structure, calling cb(err)
when done.
Terra Eclipse
Developed byTerra Eclipse, Inc. is a nationally recognized political technology and strategy firm located in Aptos, CA and Washington, D.C.
License: MIT
- Copyright (C) 2012 Carlos Rodriguez (http://s8f.org/)
- Copyright (C) 2012 Terra Eclipse, Inc. (http://www.terraeclipse.com/)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.