Minimal authorization for Node.js inspired by Pundit
npm install --save panditPandit uses policy classes to apply authorization logic. Policy constructors receive a user and resource instance (or "record") for which authorization should be applied. Policy class methods (or "queries") define the authorization logic:
module.exports = WidgetPolicy
function WidgetPolicy (user, widget) {
this.user = user
this.widget = widget
}
WidgetPolicy.prototype.edit = function (done) {
if (!this.user || !this.widget) return done(undefined, false)
if (this.user.admin) return done(undefined, true)
done(undefined, this.user.id === this.widget.owner)
}Query methods should pass true or false to the callback to indicate whether an action is authorized for the given user and record.
Pandit provides express/connect middleware for app integration:
var pandit = require('pandit')
var express = require('express')
var app = express()
// Load the pandit middleware
app.use(pandit())By default, pandit loads policies from ./lib/policies. This may be changed by passing the policyDir option:
app.use(pandit({policyDir: './app/policies'}))The middleware adds a pandit Context instance at req.pandit. The context is responsible for loading the user and record from the request and response objects. By default, the user is loaded from req.user and the record is loaded from res.locals.<name>. The pandit.Context class may be extended to alter the default behaviour.
To require authorization for a particular route, use the pandit.authorize() helper:
app.get('/widgets/:id/edit', pandit.authorize('widget', 'edit'), function (req, res) {
res.render('widgets/edit')
})In this example, the edit query of the widget policy is applied to the request. If denied, a NotAuthorizedError will be passed to the first error-handling middleware, which should respond appropriately:
app.use(function (err, req, res, next) {
if (!(err instanceof pandit.errors.NotAuthorizedError)) return next(err)
res.render('errors/403')
})If a particular authorization check doesn't require a record instance, or the instance is known before the route is created, the record class or record instance may be passed to pandit.authorize() rather than the name:
var Widget = require('./models/widget.js')
app.get('/widgets/new', pandit.authorize(Widget, 'new'), function (req, res) {
res.render('widgets/new')
})
// or
var widget = new Widget()
app.get('/widgets/global', pandit.authorize(widget, 'show'), function (req, res) {
res.render('widgets/show', {widget: widget})
})You may authorize multiple policy queries at once by passing an array to pandit.authorize():
app.get('/widgets/:id/toggle', pandit.authorize('widget', ['disable', 'enable']), function (req, res) {
res.render('widgets/toggle')
})A policy scope filters a list of records to only include those with which the user is authorized to interact. A scope is a class whose constructor receives a user and a list of records. The resolve() method on the scope should pass the filtered list of records to the callback. The default policy finder looks for the scope class as a Scope property on the policy class:
function WidgetScope (user, widgets) {
this.user = user
this.widgets = widgets
}
WidgetScope.prototype.resolve = function (done) {
if (!this.user) return done(undefined, [])
done(undefined, this.widgets.filter(function (widget) {
return this.user.id === widget.owner
}.bind(this)))
}
WidgetPolicy.Scope = WidgetScopeThe pandit.scope() helper filters the records using a given scope:
app.get('/widgets', pandit.scope('widgets'), function (req, res) {
res.render('widgets/index')
})Policies may specify which record attributes a user is allowed to manipulate by defining a permittedAttributes() method, which should pass a list of authorized record attributes to the callback.
WidgetPolicy.permittedAttributes = function (done) {
if (!this.user) return done(undefined, [])
if (this.user.admin) return done(undefined, ['name', 'gears', 'owner', 'deleted'])
done(undefined, ['name', 'gears'])
}The pandit context instance provides a permittedAttributes() method that filters the request body to only contain keys for which the user is authorized:
app.put('/widgets/:id', function (req, res, next) {
// Get authorized attributes from request body
req.pandit.permittedAttributes(res.locals.widget, function (err, attrs) {
if (err) return next(err)
// Update the widget with the filtered attributes and save
res.locals.widget.update(attrs, function (err) {
if (err) return next(err)
res.redirect('/widgets')
})
})
})The request body is retreived from req.body by default, which can be altered by extending the pandit context.
If a policy requires a user in all cases, it's inconvenient to check for the user in each query method. Instead, a policy's constructor may throw a pandit.errors.NotAuthorizedError directly:
function WidgetPolicy (user, widget) {
if (!user) throw new pandit.errors.NotAuthorizedError()
this.user = user
this.widget = widget
}A policy instance may be retrieved by calling the policy() method on the pandit request context:
app.get('/widgets/:id', function (req, res, next) {
req.pandit.policy(Widget, function (err, policy) {
if (err) return next(err)
policy.edit(function (err, allowed) {
if (err) return next(err)
res.render('widgets/show', {canEdit: allowed})
})
})
})A policy scope may be similarly retrieved using the policyScope() context method:
var widgets = [new Widget(), new Widget(), new Widget()]
app.get('/widgets', function (req, res, next) {
req.pandit.policyScope(widgets, function (err, scope) {
if (err) return next(err)
res.render('widgets/index', {widgets: scope})
})
})To ensure at least one policy has been applied to a request, the pandit.verifyAuthorized() helper may be used:
app.get('/widgets/:id', pandit.verifyAuthorized(), function (req, res) {
res.render('widgets/show')
})If authorization has not yet been performed for a request when the pandit.verifyAuthorized() handler is called, a pandit.errors.AuthorizationNotPerformedError is passed to the error-handling middleware.
Policy scopes may be enforced with the pandit.verifyPolicyScoped() helper:
app.get('/widgets', pandit.verifyPolicyScoped(), function (req, res) {
res.render('widgets/index')
})A pandit.errors.PolicyScopingNotPerformedError will be passed to the error-handling middleware if a scope has not yet been applied for a request.
The verification methods are also available on the request context:
app.get('/widgets/:id', function (req, res, next) {
req.pandit.verifyAuthorized(function (err) {
if (err) return next(err)
res.render('widgets/show')
})
})
// and
app.get('/widgets', function (req, res, next) {
req.pandit.verifyPolicyScoped(function (err) {
if (err) return next(err)
res.render('widgets/index')
})
})Both verification methods may be skipped for a particular request, allowing global authorization requirements that should be bypassed in certain cases:
app.get('/widgets/:id', function (req, res, next) {
if (process.env.NODE_ENV === 'test') req.pandit.skipAuthorization()
next()
}, pandit.verifyAuthorized(), function (req, res) {
res.render('widgets/show')
})
// and
app.get('/widgets', function (req, res, next) {
if (process.env.NODE_ENV === 'test') req.pandit.skipPolicyScope()
next()
}, pandit.verifyPolicyScoped(), function (req, res)
res.render('widgets/index')
})Pandit context methods may be overridden to customize behaviour. To globally override the context, add a custom context class to the pandit.Pandit class:
var util = require('util')
var User = require('./models/user.js')
var Context = pandit.Context
function CustomContext () {
Context.apply(this, arguments)
}
util.inherits(CustomContext, Context)
CustomContext.prototype.policyUser = function (done) {
// Find the user from a session rather than `req.user`
User.findById(req.session.userId, done)
}
CustomContext.prototype.policyRecord = function (name, done) {
// Allow passing a record or record class directly rather than a name
if (typeof name !== 'string') return done(undefined, name)
// Load the record from `req.models` rather than `res.locals`
done(undefined, this.req.models[name])
}
CustomContext.prototype.policyBody = function (done) {
// Load the request body from `req.query` rather than `req.body`
done(undefined, this.req.query)
}
// Set the global pandit context class
pandit.Pandit.Context = CustomContext
// Add middleware *after* setting the context class
app.use(pandit())The context class may be overridden per-request by using a custom middleware:
app.use(function (req, res, next) {
if (req.pandit) return next(new pandit.errors.MiddlewareAlreadyUsedError())
req.pandit = new CustomContext(new pandit.Pandit(), req, res)
next()
})To determine the appropriate policy for a record, record class or scope, the default policy finder attempts to find the name of the record type by looking in a few predefined places:
object.policyClass- Explicitly set policy for a record classobject.constructor.policyClass- Explicitly set policy for a record instanceobject.modelName- For Mongoose modelsobject.model.modelName- For Mongoose queriesobject.constructor.modelName- For Mongoose document instances
If the object is a list of records, the first object in the list is used for name lookup. If the name is found and it is not a string, the name itself is assumed to be the policy class. If the name is a string, the policy finder converts it from camel/Pascal case into a lowercase hyphenated filename, ie WidgetCategory becomes widget-category.js. The file is then loaded from the policy dir.
The policy finder logic may altered by using a custom policy finder class:
var util = require('util')
var PolicyFinder = pandit.PolicyFinder
function CustomPolicyFinder () {
PolicyFinder.apply(this, arguments)
}
util.inherits(CustomPolicyFinder, PolicyFinder)
CustomPolicyFinder.prototype.find = function () {
// Find the policy via `_pandit` property on the record
return this.object._pandit
}
CustomPolicyFinder.prototype.loadPolicy = function (name, done) {
// Load policy from custom location
try {
var policy = require('./policies/' + name + '/policy.js')
} catch (err) {
if (err && err.code === 'MODULE_NOT_FOUND') {
return done(new pandit.errors.NotDefinedError('Unable to find policy'))
}
return done(err)
}
done(undefined, policy)
}
// Set the global pandit policy finder class
pandit.Pandit.PolicyFinder = CustomPolicyFinder
// Add middleware *after* setting the policy finder class
app.use(pandit())
Developed at BKON