mongoose-plugin-auth

A mongoose.js plugin to add authorization methods to models and instances.

Installation

npm i --save mongoose-plugin-auth

API Reference

Example

const authPlugin = require('mongoose-plugin-auth');
const schema = Schema({...});
schema.plugin(authPlugin[, OPTIONS]);

mongoose-plugin-auth~options

Kind: inner property of mongoose-plugin-auth

Param	Type	Default	Description
[options]	object
[options.username]	object		options for configuring the username.
[options.username.path]	string	"username"	the path for storing the username. Value can be set to _id
[options.username.options]	object		options for configuring the username path in the schema.
[options.username.options.type]	object	String	object type for the username path. Specifying an existing username path ignores all options specified here.
[options.username.options.required]	boolean	true	spcifies wether the username path is required.
[options.username.options.unique]	boolean	true	spcifies wether the username path is required.
[options.username.options.sparse]	boolean	true	spcifies wether the username path is required.
[options.username.options.trim]	boolean	true	spcifies wether the username path is required.
[options.username.missingError]	string	"Username was not specified"	message returned via an error object for methods requiring a username.
[options.username.incorrectError]	string	"Unknown username"	message returned via an error object if username does not match a record.
[options.passphrase]	object		options for configuring the passphrase.
[options.passphrase.path]	string	"passphrase"	the path for storing the passphrase.
[options.passphrase.options]	object		options for configuring the passphrase path in the schema.
[options.passphrase.options.type]	object	String	object type for the passphrase path. Specifying an existing passphrase path ignores all options specified here.
[options.passphrase.options.required]	boolean	true	spcifies wether the passphrase path is required.
[options.passphrase.missingError]	string	"Passphrase was not specified"	message returned via an error object for methods requiring a passphrase.
[options.passphrase.incorrectError]	string	"Incorrect passphrase"	message returned via an error object if passphrase does not match the record.
[options.salt]	object		options for configuring the salt.
[options.salt.path]	string	"salt"	the path for storing the salt.
[options.salt.options]	object		options for configuring the salt path in the schema.
[options.salt.options.type]	object	String	object type for the salt path. Specifying an existing salt path ignores all options specified here.
[options.salt.options.required]	boolean	true	spcifies wether the salt path is required.
[options.salt.len]	number	32	the string length to use for the salt.
[options.hash]	object		options for configuring the hash using the crypto module.
[options.hash.iterations]	number	25000	number of iterations for generating the hash.
[options.hash.keylen.type]	number	512	the string length of the generated hash.
[options.hash.encoding]	string	"hex"	the encoding algorithm to use for the hash.
[options.hash.digest]	string	"sha512"	the HMAC digest algorithm to use for the hash. (Node v8+)
[options.Error]	object	Error	Error object to use for reporting errors. Must be of the type Error or inherites from it
[options.select]	string		Mongoose field selection to use for authenticate method/static.
[options.populate]	string		Mongoose populate selection to use for authenticate method/static.

mongoose-plugin-auth~register([username], passphrase, [extra], [cb]) ⇒ promise

The register static is a convenience function to add a new user document.

Kind: inner method of mongoose-plugin-auth

Param	Type	Description
[username]	string	Username value to use. Optional if using the _id value.
passphrase	string	Raw passphrase value. Hashed automatically before storing using crypto module.
[extra]	object	Any extra object properties that match the schema to be included in the new user document.
[cb]	function	A mongoose promise is returned if no callback is provided.

Example

MyUserModel.register('tom', 'my secret passphrase', { email: [e-mail] }, function(err, user) { ..});
MyUserModel.register('tom', 'my secret passphrase', { email: [e-mail] }).then(function(user) {...}).catch(function(err) {...}); // Uses promise
MyUserModel.register('tom', 'my secret passphrase', function(err, user) {...});
MyUserModel.register('tom', 'my secret passphrase').then(function(user) {...}).catch(function(err) {...}); // Uses promise
MyUserModel.register('my secret passphrase', { email: [e-mail] }, function(err, user) {...}); // Uses `_id` for the username
MyUserModel.register('my secret passphrase', { email: [e-mail] }).then(function(user) {...}).then(function(err) {...}); // Uses promise and `_id` for the username
MyUserModel.register('my secret passphrase', function(err, user) {...}); // Uses `_id` for the username
MyUserModel.register('my secret passphrase').then(function(user) {...}).then(function(err) {...}); // Uses promise and `_id` for the username

mongoose-plugin-auth~setPassphrase(username, passphrase, newPassphrase, [extra], [cb]) ⇒ promise

The setPassphrase static is a convenience function to set the passphrase for a user. Alternatively you can simply set the passphrase to a new value directly on the document object and save/update.

Kind: inner method of mongoose-plugin-auth

Param	Type	Description
username	string	Username value to use.
passphrase	string	Raw passphrase value. Hashed automatically before storing using crypto module.
newPassphrase	string	Raw new passphrase value. Hashed automatically before storing using crypto module.
[extra]	object	Any extra object properties that match the schema to be included in the update.
[cb]	function	A mongoose promise is returned if no callback is provided.

Example

MyUserModel.setPassphrase('tom', 'my secret passphrase', 'my new secret passphrase', { email: [e-mail] }, function(err, user) {...});
MyUserModel.setPassphrase('tom', 'my secret passphrase', 'my new secret passphrase', { email: [e-mail] }).then(function(user) {...}).then(function(err) {...}); // Uses promise
MyUserModel.setPassphrase('tom', 'my secret passphrase', 'my new secret passphrase', function(err, user) {...});
MyUserModel.setPassphrase('tom', 'my secret passphrase', 'my new secret passphrase').then(function(user) {...}).then(function(err) {...}); // Uses promise

mongoose-plugin-auth~setPassphrase(passphrase, [extra], [cb]) ⇒ promise

The setPassphrase method is a convenience function to set the passphrase for a user. Alternatively you can simply set the passphrase to a new value directly on the document object and save/update.

Kind: inner method of mongoose-plugin-auth

Param	Type	Description
passphrase	string	Raw new passphrase value. Hashed automatically before storing using crypto module.
[extra]	object	Any extra object properties that match the schema to be included in the update.
[cb]	function	A mongoose promise is returned if no callback is provided.

Example

user.setPassphrase('my new secret passphrase', { email: [e-mail] }, function(err, user) {...});
user.setPassphrase('my new secret passphrase', { email: [e-mail] }).then(function(user) {...}).then(function(err) {...}); // Uses promise
user.setPassphrase('my new secret passphrase', function(err, user) {...});
user.setPassphrase('my new secret passphrase').then(function(user) {...}).then(function(err) {...}); // Uses promise

mongoose-plugin-auth~authenticate(username, passphrase, [cb]) ⇒ promise

The authenticate static is a function to validate the passphrase for a user.

Kind: inner method of mongoose-plugin-auth

Param	Type	Description
username	string	Username value to use.
passphrase	string	Raw passphrase value. Hashed automatically before storing using crypto module.
[cb]	function	A mongoose promise is returned if no callback is provided.

Example

MyUserModel.authenticate('tom', 'my secret passphrase', function(err, user) {...});
MyUserModel.authenticate('tom', 'my secret passphrase').then(function(user) {...}).then(function(err) {...}); // Uses promise

mongoose-plugin-auth~authenticate(passphrase, [cb]) ⇒ promise

The authenticate method is a function to validate the passphrase for a user.

Kind: inner method of mongoose-plugin-auth

Param	Type	Description
passphrase	string	Raw passphrase value. Hashed automatically before storing using crypto module.
[cb]	function	A mongoose promise is returned if no callback is provided.

Example

user.authenticate('my secret passphrase', function(err, user) {...});
user.authenticate('my secret passphrase').then(function(user) {...}).then(function(err) {...}); // Uses promise

Examples

With Defaults

const authPlugin = require('mongoose-plugin-auth');
const schema = Schema({ foo: String });
schema.plugin(authPlugin);
 
const Foo = mongoose.model('Foo', schema);
Foo.register('tom', 'my new passphrase').then(function (user) {
  // user is a new document persisted to the database
});
 
// ...
 
Foo.authenticate('tom', 'my new passphrase').then(function (user) {
  // user is the authenticated user document
}).catch(function(err) {
  // err will report any authentication errors.
});

With Options (using _id as username)

const authPlugin = require('mongoose-plugin-auth');
const schema = Schema({ foo: String });
schema.plugin(authPlugin{
  username: { path: '_id' }
});
 
const Foo = mongoose.model('Foo', schema);
Foo.register('my new passphrase').then(function (user) {
  // user is a new document persisted to the database
});
 
// ...
 
Foo.authenticate('507f191e810c19729de970fb', 'my new passphrase').then(function (user) {
  // user is the authenticated user document
}).catch(function(err) {
  // err will report any authentication errors.
});

License

Apache 2.0