Authoritah is an unopinionated, tiny, library for node that provides a convenient API for scrutinizing an object against a set of rules. This is used internally at Coding Blocks for the authorization subsystems of various applications, but is unopinionated enough to be useful in any scenario.
Prajjwal Singh
Authoritah implements a rule based system, where a rule looks like this:
{
predicate: (x) => { ... },
test: (x) => { ... }
}
Here, both predicate()
and test()
are functions returning booleans. For each
rule where the predicate returns true
for the object under scrutiny(supplied
via respect()
, see below), Authoritah ensures that the corresponding test()
returns a truthy value as well. Note that predicate()
must always be
synchronous.
A sample rule used internally at Coding Blocks looks like this:
const onlyAdminsCanDeleteRecords = {
predicate: (request) => isDeleteRequest(request),
test: (request) => currentUserIsAdmin(),
httpErrorCode: 401,
errorCode: 006
})
First, create a context:
const A = new Authoritah()
To add the rule:
A.addRule(onlyAdminsCanDeleteRecords)
addRule()
also returns a boolean value indicating whether your rule was added
or not.
Finally, ensure every rule passes against object x
with:
// If all your tests are synchronous:
A.respect(x)
// In case you have one or more async tests:
A.respectAsync(x)
.then(...)
.catch(...)
This returns a boolean indicating whether every rule passed or not.
To check the number of rules that have been added, use A.ruleCount()
.
To clear all existing rules (useful for switching contexts), use
A.clearRules()
.
const Authoritah = require('cb-authoritah') ;
let manBearPig = {
species: "ManBearPig",
manFraction: 0.5,
bearFraction: 0.5,
pigFraction: 0.5
}
let fakeManBearPig = {
species: "ManBearPig",
manFraction: 0.1,
bearFraction: 0.1,
pigFraction: 0.8
}
let notManBearPig = {
species: "NotManBearPig"
}
// Instantiate a context. You can do this multiple times to create different
// contexts for different uses.
const A = new Authoritah()
// Create a Rule for only creatures whose species is "ManBearPig", asserting
// that all such creatures should be half man, half bear, and half pig.
//
// - You can add as many rules as you like.
// - A rule will not be added if it lacks the required properties, ie, either a
// predicate, a test, or both.
A.addRule({
// This function is used to decide whether or not to test an object against
// the rule. Use this to add rules for only certain kinds of objects. An
// example would be to limit a userIsAdmin() test to only DELETE requests in a
// web app.
predicate: (creature) => {
return (creature.species === "ManBearPig")
},
// This is the actual test. For all rules where the predicate returns 'true'
// for the object under scrutiny, this function is used to figure out whether
// the object is valid or not.
test: (creature) => {
return (
(creature.manFraction === 0.5) &&
(creature.bearFraction === 0.5) &&
(creature.pigFraction === 0.5)
)
},
// You can attach extra payload to your objects, with things like error codes
// and messages, etc. Just be sure to quack like a duck.
errorMessage: "That's no ManBearPig!"
})
// Test various objects against the registered rules. This only returns true if
// ALL rules attached to an object pass.
A.respect(manBearPig) // => true
A.respect(fakeManBearPig) // => false
A.respect(notManBearPig) // => true, because the rule is only for ManBearPigs
// A much more useful method is disrespectedRules(), which returns a list of all
// rules that were violated. Sorry about the naming, but the south park
// references are more important than code comprehension.
A.disrespectedRules(manBearPig) // => []
A.disrespectedRules(fakeManBearPig) // => [{ ... }]
A
.disrespectedRules(fakeManBearPig)[0]
.errorMessage // => "That's no ManBearPig!"
A.disrespectedRules(notManBearPig) // => []
// Get the number of registered rules.
A.ruleCount() // => 1
// Clear all rules, and return the cleared ones
A.clearRules() // => [{ ... }, ...]
A.ruleCount() // => 0
$> yarn test