nodulator
Version:
Complete NodeJS Framework for Restfull APIs
259 lines (180 loc) • 6.84 kB
Markdown
Nodulator-Account
=================
Master : [](https://travis-ci.org/Champii/Nodulator-Account)
Develop: [](https://travis-ci.org/Champii/Nodulator-Account)
NPM: [](http://badge.fury.io/js/nodulator-account)
Released under [GPLv2](https://github.com/Champii/Nodulator-Account/blob/master/LICENSE.txt)
##### Under heavy development
___
## Concept
Provides ability to [Nodulator](https://github.com/Champii/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](https://github.com/Champii/Nodulator-Angular)
- File generation for Server side `AccountResource`
- Permission system
___
## JumpTo
- [Installation](#installation)
- [Basics](#basics)
- [AccountResource](#accountresource)
- [Permissions](#permissions)
- [Project Generation](#project-generation)
- [TODO](#todo)
- [Changelog](#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
```coffeescript
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
```coffeescript
class PlayerResource extends Nodulator.AccountResource 'player'
```
Defaults fields for authentication are `'username'` and `'password'`
You can change them (optional) :
```coffeescript
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:
```coffeescript
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.
```coffeescript
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
```coffeescript
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
```coffeescript
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](https://github.com/Champii/Nodulator#project-generation)
When calling `$> Nodulator init`, it will automaticaly create following structure if non-existant:
```
/
└─ server/
└─ resources/
└─ ClientResource.coffee
```
If [Nodulator-Angular](https://github.com/Champii/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](https://github.com/Champii/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)
- Fixed error in package generation, when Init, it never add support for angular or raw client
- Login and Logout callbacks now take req instead of req.user
03/05/15: v0.0.7
- Fixed bad 403 when `IsOwn(key)` is used on a route without the given key in params
- Fixed req.user undefined when used in a Resource defined before AccountResource
- Tests
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