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: [email protected] }, function(err, user) { ..});
MyUserModel.register('tom', 'my secret passphrase', { email: [email protected] }).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: [email protected] }, function(err, user) {...}); // Uses `_id` for the username
MyUserModel.register('my secret passphrase', { email: [email protected] }).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: [email protected] }, function(err, user) {...});
MyUserModel.setPassphrase('tom', 'my secret passphrase', 'my new secret passphrase', { email: [email protected] }).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: [email protected] }, function(err, user) {...});
user.setPassphrase('my new secret passphrase', { email: [email protected] }).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