Simple role-based outhorization library that makes no assumptions.
bash
$ npm install user-is
```javascript var UserIs = require('user-is')
// Define what it means to have your given roles. Here we have a role called 'admin'. var roleFuncs = { 'admin': function isAdmin(user, cb) { cb(null, user && user.isAdmin) } }
// Name the actions you care about, and state what roles are needed for them var actionDefs = { 'add new user': ['admin'] , 'do something else': ['admin', 'user'] }
// Get your authorization instance var authorization = UserIs(roleFuncs, actionDefs)
// Find out if a given user has a certain role var user = {} //... You've somehow retrieved this already var userIs = authorization(user)
if (userIs.a('admin')) { // user is an 'admin', so do something with that }
// Find out if a user can perform a certain action if (userIs.ableTo('add new user')) { // user can do that action, so do something with that } ```
Or some other routing layer that uses function(req, res, next)
-style functions for a middleware layer? user-is
has you covered.
```javascript // How do you extract the user from a request? function retrieveUserFromRequest(req, cb) { // <---- async in case you need to go to the DB or something cb(null, req.user) }
var options = { retrieveUserFromRequest: retrieveUserFromRequest }
// resusing our definitions from above var authorization = require('user-id')(roleFuncs, actionDefs, options)
// Now, wherever you have your routes var router = require('express').Router
router.route('/addnewuser') .post(authorization.ensureAuthorizedTo('add new user')) ```
user-is
will introduce an Error
object into the queue. The error will have a member code
that depends on what the error is.
There error codes are accessible directly off the user-is
module, e.g.:
UserIs.notAuthorizedErrorCode
So you'd want to also have an error-handling middleware for each possibility, e.g.:
```javascript function notAuthorizedError(err, req, res, next) { if (err.code !== UserIs.notAuthorizedError) return next(err)
res.status(403).send('You are not authorized to do that!') }
router.route('/addnewuser') .post(authorization.ensureAuthorizedTo('add new user'), actualHandler, notAuthorizedError) ```
The modules returns a function with the following signature:
javascript
function UserIs(roleFuncs, actionDefinitions, options)
You've aleady seen the option for how to transform a request into a user object. There is another option though.
If you ask a question about a role or action that you haven't defined, by default, user-is
will introduce an error with code 'E_MISSINGDEFINITION'
. This error is also accessible directly off the module:
UserIs.missingDefinitionErrorCode
If you'd rather it just return false in your checks, use the following option:
```javascript var options = { errorOnMissingDefinitions: true }
var authorization = UserIs(roleFuncs, actionDefs, options)
var userIs = authorization.forUser(/some user object/)
userIs.a('role I have not mentioned before', function(err, isRole) { // isRole is now false }) ```
./node_modules/mocha/bin/mocha test/theTests.js
Fork this repo, make your change, and submit a pull request. It's worth checking the issues first to see if someone else has reported the issue. If you're unsure if a given feature is desired, open up an issue on it, and let's discuss!
A big thanks to the fine folks who wrote authorized
. Your library heavily inspried this one.