User management plugin for Seneca
npm install @seneca/user> A [Seneca.js][] user management plugin.
| !Voxgig | This open source module is sponsored and supported by Voxgig. |
|---|---|
This module is a plugin for
the Seneca framework. It provides a set of
common user management actions (register, login etc.).
``sh`
npm install seneca
npm install seneca-promisify // dependency
npm install seneca-entity // dependency
npm install @seneca/user
Register a user and then create an automatic login for testing.
`js
const Seneca = require('seneca')
var seneca = Seneca()
.use('promisify')
.use('entity')
.use('user')
var out = await seneca.post('sys:user,register:user', {
handle: 'alice'
})
console.log('USER:', out.user)
out = await seneca.post('sys:user,login:user', {
handle: 'alice',
auto: true
})
console.log('LOGIN:', out.login)
`
Because Seneca treats messages as first-class citizens, 90% of unit
testing can be implemented with message scenarios that also provide
detailed usage examples:
* register_get
* password
* adjust
* verify
* login
* logout
* change
* final
* adjust:user,sys:user
* auth:user,sys:user
* change:pass,sys:user
* change:handle,sys:user
* change:email,sys:user
* change:password,sys:user
* check:verify,sys:user
* check:exists,sys:user
* cmd:encrypt,hook:password,sys:user
* cmd:pass,hook:password,sys:user
* get:user,sys:user
* list:user,sys:user
* list:login,sys:user
* list:verify,sys:user
* login:user,sys:user
* logout:user,sys:user
* make:verify,sys:user
* register:user,sys:user
* remove:user,sys:user
* sys:user,update:user
Adjust user status idempotently (activated, etc.).
#### Parameters
* _active_ : boolean {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
user: 'user entity'
}
----------
Authenticate a login using token
#### Parameters
* _token_ : string {presence:required}
* _user_fields_ : array {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if login is active',
user: 'user entity',
login: 'user entity'
}
----------
Change user password.
#### Parameters
* _pass_ : string
* _repeat_ : string {presence:optional}
* _verify_ : string {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if changed',
user: 'user entity'
}
----------
Change user handle.
#### Parameters
* _new_handle_ : string
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if changed',
user: 'user entity'
}
----------
Change user email.
#### Parameters
* _new_email_ : string
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if changed',
user: 'user entity'
}
----------
Change user password.
#### Parameters
* _pass_ : string
* _repeat_ : string {presence:optional}
* _verify_ : string {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if changed',
user: 'user entity'
}
----------
Check a verfication entry.
#### Parameters
* _kind_ : string {presence:optional}
* _code_ : string {presence:optional}
* _now_ : number {presence:optional}
* _expiry_ : boolean {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if valid',
why: 'string coded reason if not valid'
}
----------
Check user exists.
#### Parameters
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user exists',
user: 'user entity'
}
----------
Encrypt a plain text password string.
#### Examples
* cmd:encrypt,hook:password,sys:user,pass:foofoobarbar
* Result: {ok:true, pass:_encrypted-string_, salt:_string_}
#### Parameters
* _salt_ : string {presence:optional}
* _pass_ : string {presence:optional}
* _password_ : string {presence:optional}
* _rounds_ : number {presence:optional}
#### Replies With
`
{
ok: '_true_ if encryption succeeded',
pass: 'encrypted password string',
salt: 'salt value string'
}
----------
Validate a plain text password string.
#### Examples
* cmd:pass,hook:password,sys:user,pass:goodpassword
* Result: {ok:true}
#### Parameters
* _salt_ : string
* _pass_ : string
* _proposed_ : string
* _rounds_ : number {presence:optional}
#### Replies With
`
{
ok: '_true_ if password is valid',
why: 'string coded reason if not valid'
}
----------
Get user details
#### Parameters
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
user: 'user entity'
}
----------
List users
#### Parameters
* _active_ : boolean {presence:optional}
* _q_ : object {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
items: 'user entity item list'
}
----------
List logins for a user
#### Parameters
* _active_ : boolean {presence:optional}
* _login_q_ : object {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
items: 'user entity item list'
}
----------
Create a verification entry (multiple use cases).
#### Parameters
* _kind_ : string
* _code_ : string {presence:optional}
* _once_ : boolean {presence:optional}
* _valid_ : boolean {presence:optional}
* _custom_ : object {presence:optional}
* _expire_point_ : number {presence:optional}
* _expire_duration_ : number {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
verify: 'verify entity'
}
----------
Login user
#### Parameters
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
* _auto_ : boolean {presence:optional}
* _pass_ : string {presence:optional}
#### Replies With
`
{
ok: '_true_ if user logged in',
user: 'user entity',
login: 'login entity'
}
----------
Login user
#### Parameters
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
* _token_ : string {presence:optional}
* _login_in_ : string {presence:optional}
* _login_q_ : object {presence:optional,default:{}}
* _load_logins_ : boolean {presence:optional}
#### Replies With
`
{
ok: '_true_ if user logged in',
count: 'number of logouts'
}
----------
Create a verification entry (multiple use cases).
#### Parameters
* _kind_ : string
* _code_ : string {presence:optional}
* _once_ : boolean {presence:optional}
* _valid_ : boolean {presence:optional}
* _custom_ : object {presence:optional}
* _expire_point_ : number {presence:optional}
* _expire_duration_ : number {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user found',
verify: 'verify entity'
}
----------
Register a new user
#### Parameters
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _user_ : object {unknown:true}
* _user_data_ : object {unknown:true}
#### Replies With
`
{
ok: '_true_ if user registration succeeded',
user: 'user entity'
}
----------
Remove a user
#### Parameters
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user removed',
user: 'user entity'
}
----------
Update a user
#### Parameters
* _user_ : object {presence:optional}
* _id_ : string {presence:optional}
* _user_id_ : string {presence:optional}
* _email_ : string {presence:optional}
* _handle_ : string {presence:optional}
* _nick_ : string {presence:optional}
* _q_ : object {presence:optional}
* _fields_ : array {presence:optional}
#### Replies With
`
{
ok: '_true_ if user updated',
user: 'user entity'
}
----------
Copyright (c) 2010-2020, Richard Rodger and other contributors.
Licensed under [MIT][].
[MIT]: ./LICENSE
[Seneca.js]: https://www.npmjs.com/package/seneca
[coveralls-badge]: https://coveralls.io/repos/github/senecajs/seneca-user/badge.svg?branch=master
[coveralls-url]: https://coveralls.io/github/senecajs/seneca-user?branch=master
[codeclimate-badge]: https://api.codeclimate.com/v1/badges/404faaa89a95635ddfc0/maintainability
[codeclimate-url]: https://codeclimate.com/github/senecajs/seneca-user/maintainability
[npm-badge]: https://img.shields.io/npm/v/@seneca/user.svg
[npm-url]: https://npmjs.com/package/@seneca/user
[Senecajs org]: https://github.com/senecajs/