A Seneca.js user management plugin.

@seneca/user

| | This open source module is sponsored and supported by Voxgig. | |---|---|

Description

This module is a plugin for the Seneca framework. It provides a set of common user management actions (register, login etc.).

Install

npm install seneca
npm install seneca-promisify // dependency
npm install seneca-entity // dependency
npm install @seneca/user

Quick example

Register a user and then create an automatic login for testing.

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)

Detailed Examples

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

Action Patterns

• 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

Action Descriptions

« adjust:user,sys: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'
}

« auth:user,sys:user »

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:pass,sys:user »

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:handle,sys:user »

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:email,sys:user »

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:password,sys:user »

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:verify,sys:user »

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:exists,sys:user »

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'
}

« cmd:encrypt,hook:password,sys:user »

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'
}

« cmd:pass,hook:password,sys:user »

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,sys:user »

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:user,sys:user »

List users

Parameters

• active : boolean {presence:optional}
• q : object {presence:optional}

Replies With

{
  ok: '_true_ if user found',
  items: 'user entity item list'
}

« list:login,sys:user »

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'
}

« list:verify,sys:user »

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,sys:user »

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'
}

« logout:user,sys:user »

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'
}

« make:verify,sys:user »

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:user,sys:user »

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:user,sys:user »

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'
}

« sys:user,update:user »

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'
}

License

Copyright (c) 2010-2020, Richard Rodger and other contributors. Licensed under MIT.