DarkLord - JWT based stateless authentication

DarkLord is designed to work with Express and provides a configurable authentication solution. It will provide you with a set of API end points straight out of the box. It also has a default User model and Mongo connectivity, however you can easily provide your own.

Getting started

npm install darklord --save

Next:

var darklord = require('darklord')({ router: router });

This is the simplest way of getting DarkLord up and running.

Options

var darklord = require('darklord')({
  secret: <secret string>,
  cookie: <turn on token cookie>,
  user: <passport based user model>,
  passwordValidator: <regex condition>
  databaseSvc: <database logic controller>,
  router: <express router>
});

secret (optional) - provide the JWT generator a secret key that it will use to encrypt and decrypt auth tokens. Leave it blank and it will use an environment variable called JWT_SECRET

cookie (optional) - turn token cookie on. The token will be stored in a signed cookie based on your secret. Useful if you want to use DarkLord for normal webpages as well as APIs.

user (optional) - you can setup your own passport initialised User model, the default one is wrapped up as a passport mongoose model

passwordValidator (optional) - use a Regular Expression to password validity e.g. /^.{6,}$/ for minimum length of 6

databaseSvc (optional) - if you are building your own User model and you don't want to use Mongo as a database then you probably already have a database logic layer. That's cool, you can provide DarkLord a database service that has the following interface where each method must return a promise.:

{
  create: 
  update: 
  find: 
  findOne: 
  remove:
};

router (optional) - provide DarkLord with an express router and it will add all the routes you need. If you leave it blank you will need to configure your own routes, but that should be easy enough since require('darklord')() returns a list of authentication middleware methods you can execute:

register
authenticate,
isAuthenticated,
forgotPassword,
resetPassword,
changePassword,
verifyEmail,
extendToken,
closeAccount,
verifyClosure

If however you do supply DarkLord with a router then you'll get the following end points for free.

API

Remember to create a JWT token you'll need to set a secret to the JWT_SECRET env variable

POST /token

Generate an authentication token.

Request:

{
  "email": "[email protected]",
  "password": "123456"
}

Response:

{
  "token": "<authentication-token>",
  "expiresInMinutes": "<number-of-minutes-of-validity>"
}

POST /register

Create an account and generate an authentication token. Sets the verified flag to false and creates a verified token

Request:

{
  "email": "[email protected]",
  "password": "123456"
}

Response:

{
  "token": "<authentication-token>",
  "expiresInMinutes": "<number-of-minutes-of-validity>"
}

PUT /change

Change the password on the account.

Request:

{
  "email": "[email protected]",
  "password": "abcdef"
}
	Headers:
	Authorization: "<authentication-token>"

POST /forgot

Creates a forgot password token that can be emailed to the user as a link to reset.

Request:

{
  "email": "[email protected]"
}

POST /reset

Accepts a token and a password, the server then update the account password

Request:

{
  "token": "<forgotten-password-token>",
  "password": "654321"
}

GET /verify/:token

Accepts a token that can be emailed to the user, then sets the verified flag on the user to true and removes the verify token

POST /token/extend

Checks to see if the request is already authenticated, and if so responds with a new auth token that has an extended expiry date

Request:

Headers:
Authorization: "<authentication-token>"

POST /close

Request account clousre. Sets the closure verification token and expiry date

Request:

Headers:
Authorization: "<authentication-token>"

GET /close/:token

Accepts a token, deletes the users account from the database

POST /logout

Since the cookies are httpOnly to improve security you won't be able to remove them via JavaScript. Therefore call this end point to instruct the server to remove them.

Response:

Cookies are removed

Middleware

hasAccess

If you want to check if the current request has access, ie. they are authenticated, then you can use the hasAccess method which returns a promise.

router.get('/access', function (req, res) {
  authSvc
    .hasAccess(req, res)
    .then(function () {
      res.status(200).end();
    }, function () {
      res.status(401).end();
    });
  });

logout

To logout call the logout method, it will simply remove the cookies

router.post('/logout', function (req, res) {
  authSvc.logout(req, res);
  res.status(200).end();
});

Events

The following are events you can hook into for when certain actions happen, they all return the user

registered
authenticated
forgotpassword
resetpassword
changepassword
closeaccount
accountclosed

E.g.

var darklord = require('darklord')({ router: router });

darklord.events.on('registered', function (user) {
  ...
});

Technology Used

• NodeJS
• PassportJS
• MongoDB
• Mongoose
• JSONWebToken
• Cookies
• KeyGrip