mongoose-model-security

Data driven access control layer for mongoose.

• Define access rules to models based on the content of a document
• Define access rules as MongoDB query conditions
• Handle security globally and transparently
• Integrates seamlessly with the MEAN.JS stack.

Introduction

This node.js module for mongoose is
still under development.
Changes are documented in CHANGELOG.md.

If you are using this module and experiencing problems, please report them
here.

Install

npm install -save mongoose-model-security

Please note that this module does not automatically install mongoose.

Mongoose Security Made Easy

1. Define a policy for each of your models

   var security;
   security.buildPolicy('MyModel').
    read({someProperty: 'someValue'}).
    // only fields with final 'false' value are removed (or excluded) from select, query and ordering
    readFields({someProperty: false, otherField: false}).
    update(function(parameters) {
      // some complicated logic...
      if (satisfied) {
        return true;
      } else {
        return false;
      }
    }).
    update({someOtherProperty: {$in: ['value1', 'value2']}}).
    remove(false).
    create(true);

2. Initialize Security with mongoose

   var mongoose = require('mongoose'),
      Security = require('mongoose-model-security');
   // setup mongoose / connection
   // ...
   // initialize security
   var security = new Security(mongoose);
   // load your models
   // ...
   // load your policy
   security.loadPolicy(policyConfig);

3. Use mongoose like you’re used to

   var mongoose = require('mongoose'),
      myModel = mongoose.model('MyModel');
   myModel.find(someQueryObj).exec(function(err, myDocuments) {
    // only returns myDocuments that satisfy any of the read conditions 
    // defined in the policy file
    myDocuments[0].someProperty = 'someNewValue';
    myDocuments[0].save(function(err) {
      // will return with an error and not save the document, if none of the
      // update conditions from the policy file are met
    });
   });

Concept

Using this module in combination with mongoose
allows defining access permissions (create, read, update, remove) for all models.
It acts transparently on all interactions with mongoose, i.e. you should not have
to change already implemented business code, in order to have permissions checked.

Queries

Queries are automatically decorated with conditions as defined in the model’s
policy. Queries will always only return documents that the current user has
permission to read.

Create / Update / Remove

Each of these operations are automatically intercepted and permissions are tested
before the operation is executed. The provided callback is called with an error
if the current user has insufficient permissions.

Defining a Policy

A policy can be defined per model and per permission (create, read, update,
remove). This is done by providing rules. A rule might be any of the following:

• a boolean value (true if the permission is to be granted, false otherwise)
• a mongodb query object (see here)
• a promise resolving to any of the above
• a function returning any of the above

All provided rules for the same model and permission are or-combined when
evaluated, i.e. the permission is granted if any of the provided conditions
are met.

Parameters

When using functions to return rules (see above), a parameters object is passed
in as the only argument. The parameters object contains the following properties:

• target: the document that is being tested (for create, update and delete
  permissions only).

• user defined: user defined parameters can be provided using the following
  method:

  var security;
  security.addModelProvider(function() {
    var myValue;
    return {
      myParam: myValue
    };
  });

  All defined model providers will be called before the rules are evaluated.

Current Limitations

• Permissions are not checked for all #find[*]And[Remove|Update] methods on both
  model and query as well as Model.update. This is due to the fact that mongoose middleware is not
  called for these methods (see here).

License

Copyright (c) 2015 Thomas Forrer

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.