@bouncingpixel/mongoose-acl

mongoose-acl

A Mongoose plugin for access control protection in models. The plugin offers the ability to define functions which can return whether a user has access to perform an action or query. The plugin does provide Express middleware, but Express is not required for use with the plugin.

Working With

Requirements

• NodeJS 6 LTS
• other requirements

Installing

Install the package using your JS package manager of choice, such as npm or yarn.

For example, with npm or yarn:

$ npm install --save @bouncingpixel/mongoose-acl

$ yarn add @bouncingpixel/mongoose-acl

Using mongoose-acl

The plugin requires an options object with the four required functions: canCreate, canRead, canUpdate, and canDelete. Each function is called with this context set to the Model.

In general, the return of each function can be a boolean or the fields which the user may access or manipulate. When referring to a create or update action, the term access will also mean ability to set or alter.

• If the return is falsey (false, null, undefined), then no access is allowed.
• If the return is exactly true, all access is allowed.
• If the return is an array of field names, then only those fields can be accessed.
• If the return is an object with the key allow set to an array of field names, then only those fields can be accessed.
• If the return is an object with the key disallow set to an array of field names, then all other fields except these can be accessed.
• If the return is an object with both keys allow and disallow set to arrays of field names, then any item within disallow is removed from allow, and the resulting set is the fields which may be accessed.
• In the event an empty array is specified, then the user has no access.

There are two deviations from these rules:

• canRead also allows a query key in the returned object. This key must be a function which receives one parameter, the query from Mongoose. This allows the ACL rule to automatically add to the query to enhance security.

• canDelete is only a true or false situation. You cannot delete some fields and not others. Any falsey value (false, null, undefined) will prevent the deletion. Any non-falsey value, including an array whether empty or non-empty, will be assumed to be true and allow the delete to continue.

canCreate(req: Request, document: MongooseDocument<Model>): RuleSpec
canRead(req: Request, query: MongooseQuery): ReadRuleSpec
canUpdate(req: Request, document: MongooseDocument<Model>): RuleSpec
canDelete(req: Request, document: MongooseDocument<Model>): DeleteRuleSpec

The rules will be enforced using hooks, thus it is possible to bypass a security rule by ignoring hooks for a specific action. Note: At this time, there are some functions which do not cause hooks to be called. For example, Model.remove in Mongoose does not call the remove hook.

The canCreate and canUpdate rely on the pre-validation hook. For the use case where a rule limits which fields a user may access, but the system should auto-generate values for the field, one may use a pre-validation or a pre-save hook that must be added to the Schema after the plugin. If you require your pre-validation hook to perform actions that must also be ACL protected, then define your pre-validation hook before the plugin is added.

By default, the hooks will not permit any action which generates hooks until a protected instance of the model is created. To create a protected instance, you must pass in a request object, which can actually be any object which will be passed to the rule definitions to test the access level of a request.

A static method on the Model, .protect(req) exists to generate a protected instance. In the current version, protect will modify the req object to set req.protectedModels and uses that as a cache for all protected models. Calling .protect(req) with the same req object multiple times will use the cached protected-model, unless req cannot be modified.

Express Middlewares

There are also a number of Express middleware which can optionally be utilized.

The protect method is also a middleware, .protect(req, res, next), and can mounted to automatically add a protected model to the req object.

Read middlewares

makeReadMany(options) and makeReadOne(options) will create a middleware for reading. The two are separate middlewares as fetching a list and fetching a single instance are different actions and generally are attached to different routes.

makeReadOne(options) can make use of req.params.id to read one document based on the ObjectID. Otherwise, this may use the same where, sort, and offset. Any limits set will be ignored and only one document will be returned.

All options are optional. The options which can be passed in are as follows:

initialWhere: any // the where clause which is appended to any specified by the used
initialSort: any // the sort clause which is appended to any specified by the used

initialLimit: Number // the default limit to use
initialOffset: Number // the default offset to use

// all of the next ones default to false
canExtendWhere: Boolean // if the user may use req.query.where to set the query
canExtendSort: Boolean // if the user may use req.query.sort to set the sort
canSetLimit: Boolean // if the user may set req.query.limit to set the limit
canSetOffset: Boolean // if the user may set req.query.offset to set the offset

resLocalsField: String // what field to set the data to in res.locals, defaults to data

Create middleware

makeCreate(options) creates the middleware for document creation. The middleware expects the data to use for creation will be in req.body[incomingDataField] where incomingDataField is either the option set or the model name used when creating the model: mongoose.model('modelName', MySchema).

All options are optional. The options which can be passed in are as follows:

resLocalsField: String // what field to set the data to in res.locals, defaults to data

incomingDataField: String // what field in req.body the updated data will be in

If the model defines an static method deserializeForm(originalDocument?), that function will be used to manipulate the data at req.body[incomingDataField]. There is no originalDocument for create, unlike update. The function can return a Promise or run synchronously. The middleware will expect req.body[incomingDataField] to contain the final data used to perform the create.

Update middlewares

makeUpdate(options) creates the middleware for document updates based on ID. The middleware expects the _id of the item to be updated to be in req.params.id. The middleware expects the data to use for creation will be in req.body[incomingDataField] where incomingDataField is either the option set or the model name used when creating the model: mongoose.model('modelName', MySchema).

The default updater currently uses a shallow merge method. Any field not defined or set to undefined will not be merged, thus keeping the original value. Any objects or arrays will be set as-is and will not be merged with their counterparts in the document. The updater can be changed with the option mergeUpdates.

If the model defines an static method deserializeForm(originalDocument?), that function will be used to manipulate the data at req.body[incomingDataField]. The original document before updates is provided. The function can return a Promise or run synchronously. The middleware will expect req.body[incomingDataField] to contain the final data used to perform the update. When using the default updater, this function can set fields to undefined in order to preserve the original value.

All options are optional. The options which can be passed in are as follows:

mergeUpdates(document: MongooseDocument<Model>, updates: any, req: Request): Promise?

resLocalsField: String // what field to set the data to in res.locals, defaults to data

incomingDataField: String // what field in req.body the updated data will be in

Delete middlewares

makeDelete(options) creates the middleware for deleting documents by ID. The middleware expects the _id of the item to be deleted to be in req.params.id. The only option available is resLocalsField which defines the field in res.locals that will contain the deleted instance.