mastoose

#Mastoose

Mastoose (Master of Mongoose) is a utility that helps to deal with exposition and modification rules for Mongoose documents.

It allows to declare models access/modification logic in one place and not to worry of creating security issues when using them.

It's designed to be part of a resource reflection library.

Unlike some other libs, it does not require to define rules directly in the model schema.

It supports nested schemas, sub-models and aggregated/populated documents.


---

##Initialisation
You need to pass the mongoose instance you use.

``javascript
var mastoose = new Mastoose(mongoose);
`


##Defining rules

Given this model

`javascript
var Model = mongoose.model('Model', new mongoose.Schema({
ppte : String,
ppte2 : String,
nested : {
ppte : String,
ppte2 : String
},
to : [{
type : mongoose.Schema.Types.ObjectId,
ref : User.modelName
}]
}));
`

We define rules for Model and User


`javascript
mastoose.addRule(Model, {

// define if this model can be accessed
access : true/false/function(ctx, callback) {
// this is the current model instance
callback(err, true/false);
},

// define if a property should be exposed (by default all properties are exposed)
exposes : {
// boolean
ppte : false/true,

// or a function with a callback
'nested.ppte' : function(ctx, callback) {
// this is the current model instance
callback(err, true/false);
}
},

// define which paths can be modified (by default all can)
allowsModification : {
ppte : false/true,

'nested.ppte' : function(ctx, callback) {
// this is the current model instance
callback(err, true/false);
}
},

// define authorizations for calling methods (by default all can be called)
allows : {
method1 : true/false,
method2 : function(ctx, callback) {
// this is the current model instance
callback(err, true/false);
}
});

mastoose.addRule(User, {...});
`

Using Mastoose

- Exposing a document

You can pass any kind of documents/objects. Mastoose will apply the exposes rules accordingly.

`javascript
var ctx = {user : user, ... };
mastoose.expose(ctx, data, function(err, data_clean) {
res.json(data_clean);
});
`

internally it uses the rule access. it will raise an error if a document in data should not be accessed.


- Protecting a document modification/creation

You can check if pending modifications of a document (new or not) are allowed by the rules. Based on Mongoose isModified property.

`javascript
mastoose.allowsModification(ctx, doc, function(err, allowed) {
if (allowed) {
model.save();
}
})
`

- Protecting a document method

You can check if a method can be used

`javascript
mastoose.allows(ctx, doc, 'method', function(err, allowed) {
if (allowed) {
model.save();
}
})
`

Use with Expoose

- link them

`javascript
var expoose = new Expoose(mongoose);

// command checker

expoose.on('command', function(method, req, model, callback) {
if (method !== 'save') {
mastoose.allows(req.user, model, method, function(err, allows) {
callback(err || (!allows && new restify.NotAuthorizedError()));
});
return;
}

mastoose.allowsModification(req.user, model, function(err, allows) {
callback(err || (!allows && new restify.NotAuthorizedError()));
});
});

// data filtering

expoose.on('expose', function(req, data, callback) {
mastoose.expose(req.user, data, function(err, filtered_data) {
callback(err, filtered_data);
});
});

// error management

expoose.on('error', function(err, res) {
if (err instanceof Mastoose.errors.CanNotAccess) {
err = new restify.NotAuthorizedError();
}

if (!(err instanceof restify.HttpError)) {
switch (err.type) {
case 'InvalidArgument':
err = new restify.InvalidArgumentError(err.message);
break;
default :
err = new restify.InternalError(err.message);
}
}

res.json(err);
});
`

- use Expoose without worrying to make security mistakes

`javascript
server
.get(
'/users/:user_id',
middlewares.get('me'),
expoose.detail(User, {id : 'user_id'})
);

server
.post(
'users',
expoose.insert(User)
);

server.get(
'/users',
expoose.list(User)
);

server
.del(
'users/:user_id',
expoose.remove(User, {id : 'user_id'})
);

server
.get(
'/users/:user_id/discussions',
middlewares.get('me'),
expoose.method(User, 'discussions', {id : 'user_id'})
);

``

**The idea is that all validations and eventual reactions to models changes are handled thanks to mongoose hooks and/or plugins.
It allows to make a nice model/event driven API.**

Expoose has currently not been open sourced. Some work is still needed.