!Seneca
> A Seneca.js User Management Plugin

seneca-user

[![npm version][npm-badge]][npm-url]
[![Build Status][travis-badge]][travis-url]
[![Coverage Status][coveralls-badge]][coveralls-url]
[![Dependency Status][david-badge]][david-url]
[![Gitter chat][gitter-badge]][gitter-url]

Lead Maintainers: Mircea Alexandru and Mihai Dima

A user management plugin for the Seneca toolkit

This module is a plugin for the Seneca framework. It provides business logic for user management, such as:

* login
* logout
* registration
* password handling, incl. resets

This plugin needs [seneca-basic][seneca-basic-url] and [seneca-entity][seneca-entity-url] plugins to function properly.

There are two core concepts: user and login. A _user_, storing the user account details and encrypted passwords,
and a _login_, representing an instance of a user that has been authenticated. A user can have multiple logins.

This module does not make any assumptions about the context it runs in.
Use the seneca-auth plugin to handle web and social media authentication.

For a working example, see the Seneca user accounts example

Support

If you're using this module, feel free to contact me on Twitter if you
have any questions! :) @rjrodger

Code examples

For code samples, please see the tests for this plugin.

$3

Supports Seneca versions 1.x - 3.x

Install

``sh
npm install seneca
npm install seneca-user
`

You'll need the seneca module to use this module - it's just a plugin.

Quick example

`js
var seneca = require('seneca')()
seneca.use(require('seneca-basic'))
seneca.use(require('seneca-entity'))
seneca.use(require('seneca-user'))

seneca.ready(function (){
seneca.act( {role: 'user', cmd: 'register', name: "Flann O'Brien", email: 'nincompoop@deselby.com', password: 'blackair'},
function (err, out) {

seneca.act({role: 'user', cmd: 'login', email: 'nincompoop@deselby.com', password: 'bicycle'}, function (err, out) {
console.log('login success: ' + out.ok)

seneca.act({role: 'user', cmd: 'login', email: 'nincompoop@deselby.com', password: 'blackair'}, function (err,out) {
console.log('login success: ' + out.ok)
console.log('login instance: ' + out.login)
})
})
})
})
`

In the example code, a user is registered, and then two login attempts are made. The first with an incorrect password, the second with the correct
password. The successful login provides a login instance. The login.id property can be used to authenticate this login. For example,
the seneca-auth plugin uses this token as a HTTP authentication cookie.

To run this example (and the other code in this README), try:

`sh
node test/readme.js
`

Deeper example

Take a look at the user accounts example.

Usage

To load the plugin:

`js
seneca.use('user', { ... options ... })
`

The user and login data is persisted using Seneca entities. These have
names sys/user and sys/login.

Passwords are not stored in plaintext, but using an ~10k round salted SHA512 hash. In
the context of password reset functionality, this means you can
generate new passwords, but cannot recover old ones.
This is what you want.

There are separate actions to encrypt and verify passwords, so you can do things your own way if you like.

To support different use cases, users can be identified by either a
nick or their email address. The nick property is the traditional
'username', but does not need to be used in this fashion (hence the name 'nick').

All actions defined by this plugin return meta data objects containing the results of the action. The meta data object
contains an ok field that is either true or false, indicating the success or failure of the action. For example, a login attempt with an invalid password will result in an {ok:false,...}. When relevant, a why property is also provided, with a code that indicates the reason for the result. For example: {...,why:'user-not-found'}.

Options

* rounds: number of SHA512 rounds to use for password encryption, default: 11111
* autopass: automatically generate an (unrecoverable) password if none is supplied - mostly good for testing, default: true
* mustrepeat: you must provide a repeat argument (a repeat of the password) when setting a password
* resetperiod: duration in millis that a password reset token is valid, default: 24 hours
* pepper: used in addition to password salts, a pepper is very similar but is stored in code instead of a database.
* failedCount: number of failed attempts before the account is locked. Disabled by default.

To set options, do so when you load the plugin:

`js
seneca.use('user', { resetperiod: 3600*1000 })
`




Entities

$3

The user entity has a default type of -/sys/user and standard properties:

* nick: Username, mostly. If not provided, will be set to email value.
* email: Email address. At least one of nick or email is required.
* name: Name of user. Just a text field. Cultural imperialism damages your conversions, ya know...!
* active: if true, user can log in, if false, user can't. Default: true.
* when: creation time, ISO String, like 2013-03-21T17:32:24.039Z
* salt: salt for encrypted password
* pass: encrypted password

You can add your own properties, but be careful not to use the standard property names.




$3

The login entity has a default type of -/sys/login and standard properties:

* id: authentication token, UUID
* nick: copied from user
* user: user.id string
* when: creation time, ISO String, like 2013-03-21T17:32:24.039Z
* active: if true, login against this token will succeed, otherwise not

You can add your own properties, but be careful not to use the standard property names.




$3

The reset entity has a default type of -/sys/reset and standard properties:

* id: authentication token, UUID
* nick: copied from user
* user: user.id string
* when: creation time, ISO String, like 2013-03-21T17:32:24.039Z
* active: if true, reset against this token will succeed, otherwise not

You can add your own properties, but be careful not to use the standard property names.

Actions

All actions provide results via the standard callback format: function(error,data){ ... }.

To customize the behavior of the plugin, override these actions, and provide your own business logic. You can call this.prior
inside each custom action to perform the default behaviour - see the [Customization] section below.




$3

Login an existing user. Creates a new sys_login entry.

#### Arguments:

* nick: required if no email, identifies user, alias: username
* email: required if no nick, identifies user
* password: password as entered by user, optional if using _auto
* auto: automatic login without password, default: _false_. Use this to generate login tokens.
* user: specify user using a sys/user entity - for convenience use inside your own actions, when you already have a user entity loaded

#### Provides:

Object with properties:

* ok_: true if login succeeded, false if not
* login: login entity, id is the login token, used as cookie
* user_: user entity
* why: indicates reason login failed or succeeded, refer to source for codes.

$3

Logout a user. Update _sys/login_ entry to _active:false_. Adds _ended_ field with ISOString date time.

#### Arguments:

* token: existing login token, maybe from a cookie

#### Provides:

Same object format as login command result: {ok:true|false,user:,login:}

$3

Register a new user. You'll probably call this after a user fills out
a regstration form. Any additional action arguments are saved as user
properties. The nick and email fields will be checked for
uniqueness. The new user is not logged in, use the login action for
that.


#### Arguments:

* nick: Username, mostly. If not provided, will be set to args.username value, if defined, otherwise args.email value
* email: Email address. At least one of nick or email is required
* username: a convenience - just an alias for nick
* password: Plaintext password, supplied by user - will be stored encrypted and unrecoverable
* repeat: Password, repeated. Optional - if provided, must match password
* name: Name of user. Just a text field.
* active: if true, user can log in, if false, user can't. Default: true

#### Provides:

Object with properties:

* ok: true if registration succeeded, false if no
* user: new user entity
* why: indicates reason registration failed, refer to source for codes

$3

Authenticate a login token, returning the associated sys/login and sys/user if
the token is valid and active. Use this, for example, when handling
HTTP requests with an authentication cookie, to get the user.

#### Arguments:

* token: existing login token, maybe from a cookie

#### Provides:

Same object format as login command result: {ok:true|false,user:,login:}

$3

Create a reset token, valid for a 24 hours (use the resetperiod options to alter the validity period). This action
creates an entry in the sys/reset collection.

#### Arguments:

* nick: required if no email, identifies user, alias: username
* email: required if no nick, identifies user
* user: specify user using a sys/user entity - for convenience use inside your own actions, when you already have a user entity loaded

#### Provides:

Object with properties:

* ok: true if update succeeded, false if not
* user: sys/user entity
* reset: sys/reset entity

$3

Load a sys/reset entity using a reset token. Use this to load the details of a reset request, possible to confirm with user.

#### Arguments:

* token: reset token

#### Provides:

Object with properties:

* ok: true if reset found, false if not
* user: sys/user entity
* reset: sys/reset entity
* why: reason for failure

$3

Execute a password reset action. The user identified by the reset token is allowed to change their password. THe reset must be active, and the validity period must not be expired. On successful reset, the sys/reset is deactivated and cannot be reused.

#### Arguments:

* token: reset token
* password: new password
* repeat: optional, repeat of new password

#### Provides:

Object with properties:

* ok: true if reset found, false if not
* user: sys/user entity
* reset: sys/reset entity
* why: reason for failure

$3

Encrypts a plaintext password, providing the salt and ciphertext. The encyption is options.rounds (default:11111) rounds of SHA512.

#### Arguments:

* password: plaintext password.
* repeat: optional, repeat of password

#### Provides:

Object with properties:

* ok: true if succeeded
* salt: the salt string
* pass: the ciphertext string
* why: reason for failure

$3

Verifies that a password matches a given salt and ciphertext.

#### Arguments:

* salt: the salt string to use, find this in user.salt
* pass: the pass string to use, find this in user.pass
* proposed: the proposed plaintext password to verify

#### Provides:

Object with properties:

* ok: true if password matches

$3

Updates a user.

#### Arguments:

* nick: the nick of the user to be updated
* orig_nick: if nick will be changed on this update then orig_nick will be used to identify the user
* email: the email of the user to be updated
* orig_email: if email will be changed on this update then orig_email will be used to identify the user

At least one of these arguments must be present.

#### Provides:

Object with properties:

* ok: true if operation is OK

$3

Deletes an user and all relationed records.

#### Arguments:

* nick: the nick of the user to be updated

#### Provides:

Object with properties:

* ok: true if operation is OK

$3

Enables an user.

#### Arguments:

* nick: the nick of the user to be updated
* email: the email of the user to be updated

At least one of these arguments must be present

#### Provides:

Object with properties:

* ok: true if operation is OK

$3

Disables an user.

#### Arguments:

* nick: the nick of the user to be updated
* email: the email of the user to be updated

At least one of these arguments must be present

#### Provides:

Object with properties:

* ok: true if operation is OK

$3

Removes the lock form a user account

#### Arguments:

* id: the id of the user

#### Provides:

* ok: true if the account was unlocked

Logging

To see what this plugin is doing, try:

``sh
node your-app.js --seneca.log=plugin:user
`

This will print action logs and plugin logs for the user plugin. To skip the action logs, use:

`sh
node your-app.js --seneca.log=type:plugin,plugin:user
`

You can also set up the logging programmatically:

var seneca = require('seneca')({
log:{
map:[
{plugin:'user',handler:'print'}
]
}
})

For more on logging, see the seneca logging example.




$3

As with all seneca plugins, you can customize behavior simply by overwriting actions.

For example, to add some custom fields when registering a user:


`js
// override by using the same action pattern
seneca.add({role:' user', cmd: 'register'},function (args, done) {

// assign user to one of 10 random "teams"
args.team = Math.floor(10 * Math.random())

// this calls the original action, as provided by the user plugin
this.prior(args,done)
})


userpin.register({name: "Brian O'Nolan", email: 'brian@swim-two-birds.com', password: 'na-gCopaleen'},
function (err, out) {
console.log('user has team: ' + out.user.team)
})
`

Contributing

The [Senecajs org][] encourages open participation. If you feel you
can help in any way, be it with documentation, examples, extra
testing, or new features please get in touch.

Test

`sh
npm test
``

License

Copyright (c) 2012-2016, Richard Rodger and other contributors.
Licensed under [MIT][].

[MIT]: ./LICENSE
[npm-badge]: https://badge.fury.io/js/seneca-user.svg
[npm-url]: https://badge.fury.io/js/seneca-user
[travis-badge]: https://api.travis-ci.org/senecajs/seneca-user.svg
[travis-url]: https://travis-ci.org/senecajs/seneca-user
[coveralls-badge]:https://coveralls.io/repos/senecajs/seneca-user/badge.svg?branch=master&service=github
[coveralls-url]: https://coveralls.io/github/senecajs/seneca-user?branch=master
[david-badge]: https://david-dm.org/senecajs/seneca-user.svg
[david-url]: https://david-dm.org/senecajs/seneca-user
[gitter-badge]: https://badges.gitter.im/senecajs/seneca.svg
[gitter-url]: https://gitter.im/senecajs/seneca
[Senecajs org]: https://github.com/senecajs/
[seneca-basic-url]: https://github.com/senecajs/seneca-basic
[seneca-entity-url]: https://github.com/senecajs/seneca-entity