nodulator-account

Nodulator-Account

Master :

Develop:

NPM:

Released under GPLv2

Under heavy development

---

Concept

Provides ability to Nodulator to manage authentication, sessions and route permissions.

---

Features

• Basic mail authentication
• Session management over Redis
• File generation for login/signup views/directive for Nodulator-Angular
• File generation for Server side AccountResource
• Permission system

---

JumpTo

• Installation
• Basics
• AccountResource
• Permissions
• Project Generation
• TODO
• Changelog

---

Installation

You can automaticaly install Nodulator and Nodulator-Account by running

$> sudo npm install -g Nodulator
$> Nodulator install account

Or you can just run npm :

$> npm install nodulator nodulator-account

---

Basics

Nodulator = require 'nodulator'
Account = require 'nodulator-account'

Nodulator.Use Account

---

AccountResource

This module provides Nodulator.AccountResource that extends Nodulator.Resource and deals with every parts of app authentication.

Authentication is based on Passport

class PlayerResource extends Nodulator.AccountResource 'player'

Defaults fields for authentication are 'username' and 'password'

You can change them (optional) :

config =
  fields:
    usernameField: 'login'
    passwordField: 'pass'

class PlayerManager extends Nodulator.AccountResource 'player', config

The passwordField of an AccountResource is never returned by the .ToJSON() method for evident security reasons.

It creates a custom method from usernameField

*FetchByUsername(username, done)

  or here if customized

*FetchByLogin(login, done)

* Class methods

It defines 2 routes (here when attached to a PlayerResource) :

POST   => /api/1/players/login
POST   => /api/1/players/logout

It setup session system, and thanks to Passport,

It fills req.user variable to handle public/authenticated routes

You have to extend yourself the post default route (for exemple) of your AccountResource to use it as a signup route.

---

Permissions

There is two ways to deal with permissions: You can restrict a whole object:

config =
  restrict: Nodulator.Route.Auth()

class TestResource extends Nodulator.Resource 'test', Nodulator.Route, config

And/or a single API call (see exemples below)

The Route object exposes 3 middleware to manage permissions :

Nodulator.Route.Auth()

This middleware checks if the current user is logged in, or returns a 403 forbidden if not.

class TestRoute extends Nodulator.Route
  Config: ->
    super()

    #You have shorcuts for every perission call
    #made inside a Route. (here: @Auth())
    @Get @Auth(), (req, res) =>
      [...]
      # This call will be executed only if user is logged

Nodulator.Route.HasProperty(object)

This middleware checks if the current user is logged in and have the specified properties set

class TestRoute extends Nodulator.Route
  Config: ->
    super()

    @Get @HasProperty({group_id: 2}), (req, res) =>
      [...]
      # This call will be executed only if user is logged
      # and have the property group_id set to '2'

Nodulator.Route.IsOwn(string)

This middleware checks if the current user is logged in and the route param specified is own user.id

class TestRoute extends Nodulator.Route
  Config: ->
    super()

    @Get '/:player_id', @IsOwn('player_id'), (req, res) =>
      [...]
      # This call will be executed only if user is logged
      # and have (user.id === req.params.player_id)

SelfMade permissions

You can make your own permissions using the express middleware system. Your function must take (req, res, next) ->, or return a function that takes these parameters. Please refer to the express documentation if you don't know what a middleware is.

---

Project Generation

See Nodulator's project generation

When calling $> Nodulator init, it will automaticaly create following structure if non-existant:

/
└─ server/
   └─ resources/
      └─ ClientResource.coffee

If Nodulator-Angular is installed, it also create this structure :

/
└─ client/
   ├─ auth.jade
   ├─ directives/
   │  └─ AuthDirective.coffee
   ├─ services/
   │  └─ UserService.coffee
   └─ views/
      └─ auth.jade

This structure contains a directive/view pair for asking user to login/signup, a UserService to manage client-side session, and a global auth.jade view to render.

If no Nodulator-Angular module is found, but a Nodulator-Assets is, a simple client/auth.jade file is added to handle basic authentication.

---

TODO

• Better test suite
• Social signup

---

Changelog

XX/XX/XX: current (not released yet)

• Nothing

14/04/15: v0.0.6

• Adding Nodulator.Route.Auth() permission call
• Adding Nodulator.Route.HasProperty(object) permission call
• Adding Nodulator.Route.IsOwn(string) permission call
• You can add permissions on certains api call or on a whole Route object (config.restrict)
• Added unit tests for basic auth and permissions

10/04/15: v0.0.5

• The userField.passwordField of .ToJSON() is not returned anymore
• Fixed generation problem with no nodulator-assets included
• Different generation if Nodulator-Angular, Nodulator-Assets, both or none of them

20/01/15: v0.0.4

• Fixed bugs about @_table

20/01/15: v0.0.3

• Fixed bugs

03/01/15: v0.0.2

• Fixed bug on auth when custom userFields

03/01/15: v0.0.1

• Initial release