Build Status

User management module for Nxus apps. Users provides a complete framework for managing users, authenticating routes and sessions.


> npm install nxus-users --save


Once Users is installed in your app, you are ready to go. It includes the following components:

  • user/team models
  • login/logout routes
  • authentication/session middleware


Uses defines a set of common models you can use to build your application, using the @nxus/storage module (which uses Waterline to provide common ORM functionality).


Accessing the user model:

storage.getModel('users-user').then((User) => {


  • email: string
  • password: string
  • nameFirst: string
  • nameLast: string
  • position: string
  • enabled: boolean
  • admin: boolean
  • lastLogin: datetime
  • metadata: JSON
  • team: relation to Team model

Convenience Methods

  • name(): first + last name
  • isAdmin(): boolean if user is an Admin
  • validPassword(pass): returns true if the password is valid


Users defines a set of common templates you can use in your app


A login form preconfigured to work with the login/logout routes. Markup supports basic Bootstrap 3 CSS.

templater.render('users-login').then((content) => {


The Users module defines some convience routes for handling basic user functionality.


Params Expects to recieve a POSTed form with the values username, password and redirect. redirect should be a url to redirect the user to on success. On login failure, the user will be redirected back to /login.


Params Expects to recieve a GET request with the param redirect, which is a url where the user will be redirected on successful logout.


The Users Module provides a complete user authentication and authorization system.

new Users()

Extends HasModels

Permissions system

This module provides a role & permission list approach to managing user access in Nxus. Routes (or other guarded functionality) is associated with a Permission name, and permissions are assigned to Roles. A User may have multiple roles, and a permission may belong to multiple roles.

Permissions and roles can also be scoped to specific model objects, allowing users access to just those objects they own or have been given a role in managing.


`import {permissions} from 'nxus-users'

Registering permissions and roles

`permissions.register('permission-name', ['Default Role'])

Guarding routes and handlers

`permissions.guard('/my/route', 'permission-name')

`permissions.guardHandler(::this._myRoute, 'permission-name').then((handler) => { router.route('/my/route', handler) })

Checking for user permissions in handlers/templates

req.user.permissions.allows('permission-name')req.user.permissions.allows('permission-name', object)

Object-level permissions

Object role assignments need a collection object that subclasses ObjectRoleModel and overrides the object attribute:

import {ObjectRoleModel} from 'nxus-users'
export default ObjectRoleModel.extend{{
identity: 'my-object-roles',
attributes: { object: { model: 'my-object'}}

The permissions should be registered with an extra argument naming this model collection:

`permissions.register('my-object-permission', ['Object Editor'], 'my-object-roles')

Alternatively, this may be a function that accepts (objectId, user) and returns the roles assigned - This can implement traversing the object model to reach a parent with the permissions, or entirely override how and where role assignments are stored.

Guards should be set with the extra argument naming the URL param to use as objectId to lookup.

`permissions.guard('/edit/:id', 'my-object-permission', 'id')

new UsersPermissions(opts: any)

Extends HasModels

opts (any = {})