Lockit

Lockit is an authentication solution for Express. Check out the demo.

It consists of multiple single purpose modules:

• lockit-login
• lockit-signup
• lockit-delete-account
• lockit-forgot-password
• lockit-sendmail
• lockit-couchdb-adapter
• lockit-mongodb-adapter
• lockit-sql-adapter
• lockit-utilities
• lockit-template-blank

Table of contents

• Quickstart
• Full Installation
• Configuration
  • Database connection
  • Sending emails
  • Custom views
• Events
  • signup
  • login
  • logout
  • delete
  • forgot::sent
  • forgot::success
• REST API
• Sample config
• Features
• Routes included

Quickstart

1. Create new Express app.

express

2. Install Lockit and sessions via npm.

npm install && npm install lockit cookie-session --save

3. Use lockit and cookie-session in your Express app.js.

var cookieSession = require('cookie-session');
var Lockit = require('lockit');
var lockit = new Lockit();

...
app.use(cookieSession({
  secret: 'my super secret String'
}));
app.use(lockit.router);

4. Go to localhost:3000/signup

By default Lockit uses an in-memory SQLite database. So you don't have to set up any db. Lockit will just work. Check out the default example.

For production use a persistent data store!

Full installation

1. Install and require

npm install lockit --save

var config = require('./config.js');
var Lockit = require('lockit');

var app = express();

// express middleware
// ...
// sessions are required
app.use(cookieParser());
app.use(cookieSession({
  secret: 'your secret here'
}));

var lockit = new Lockit(config);

app.use(lockit.router);

// you now have all the routes like /login, /signup, etc.
// and you can listen on events. For example 'signup'
lockit.on('signup', function(user, res) {
  console.log('a new user signed up');
  res.send('Welcome!');   // set signup.handleResponse to 'false' for this to work
});

2. Add styles

Views are built with bootstrap. You can use your own ones though! Use Bootstrap CDN and add the following line to your layout.jade

link(rel='stylesheet', href='//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css')

3. Install database adapter

npm install lockit-[DB]-adapter where [DB] can be

| Database | Command | | --- | --- | | CouchDB | npm install lockit-couchdb-adapter | | MongoDB | npm install lockit-mongodb-adapter | | SQL (PostgreSQL, MySQL, MariaDB or SQLite) | npm install lockit-sql-adapter |

If you use a SQL database you also have to install the connector.

npm install pg       # for postgres
npm install mysql    # for mysql
npm install sqlite3  # for sqlite
npm install mariasql # for mariasql

Configuration

You need a config.js somewhere in your app.

Database connection

Add the database connection string to your config.js.

// database settings for CouchDB
exports.db = 'http://127.0.0.1:5984/';        // connection string for database

// or if you want to use MongoDB
// exports.db = {
//   url: 'mongodb://127.0.0.1/',
//   name: 'test',
//   collection: 'users'  // collection name for MongoDB
// };

// PostgreSQL
// exports.db = {
//   url: 'postgres://127.0.0.1:5432/',
//   name: 'users',
//   collection: 'my_user_table'  // table name for SQL databases
// };

// MySQL
// exports.db = {
//   url: 'mysql://127.0.0.1:3306/',
//   name: 'users',
//   collection: 'my_user_table'
// };

// SQLite
// exports.db = {
//   url: 'sqlite://',
//   name: ':memory:',
//   collection: 'my_user_table'
// };

Sending emails

By default the email service is stubbed and no emails are sent. That means that you won't receive any signup and password reset tokens. You have to look them up in your database and call the routes manually (e.g. /signup/:token). To send emails you need an email server and you have to change the settings in your config.js:

• emailType - usually nodemailer-smtp-transport
• emailSettings - see nodemailer for more information

With mailgun you can send up to 10,000 emails per month for free.

exports.emailType = 'nodemailer-smtp-transport';
exports.emailSettings = {
  service: 'Mailgun',
  auth: {
    user: 'postmaster@username.mailgun.org',
    pass: 'secret-password'
  }
};

Custom views

Lockit comes with built-in views which are based on Bootstrap. If you want to use your own custom views you can. It is dead simple.

Put them into your views folder, for example views/lockit/myLogin.jade. Then edit your config.js and set the path to your custom view.

exports.login = {
  route: '/login',
  logoutRoute: '/logout',
  views: {
    login: 'lockit/myLogin.jade',
    loggedOut: 'lockit/myLogoutSuccess.jade'
  }
};

The only thing you have to keep in mind is the structure. The login.views.login view, for example, needs a form element with two input fields. The method has to be POST and action should point to your login.route. The input fields have to have the names login and password. If something went wrong during the login process you'll get an error variable that you can use in your template.

Here is a minimalistic example for an alternative myLogin.jade.

extend /layout

block content
  h1 Login
  form(action="/login", method="POST")
    div
      label(for="login") Email or Username
      input(type="text", id="login", name="login", placeholder="Your email or username")
    div
      label(for="password") Password
      input(type="password", id="password", name="password", placeholder="Your password")
    if error
      p #{error}
    input(type="submit", value="Login")

For more information about each view see the views folder inside the different repositories. Make sure your view extends /layout which is different to your normal views. They extend layout without the slash. This is required to find the view.

Events

Lockit emits the most important events for user authentication. Those are

• signup
• login
• logout
• delete

You can use these events to intercept requests and implement some custom logic, like getting the gravatar before sending a response to the client.

signup

A new user signed up. The callback function has two arguments.

• user is an object and contains information about the new user, like user.name or user.email.
• res is the standard Express.js res object with methods like res.render and res.send. If you've set signup.handleResponse to false Lockit will not handle the response for you. You therefore have to send the response back to the client manually or otherwise it will wait forever.

lockit.on('signup', function(user, res) {
  // ...
});

login

A user logged in. Callback function this time has three arguments.

• user is again the JSON object containing info about that particular user.
• res is the normal Express.js response object with all properties and methods.
• target is the redirect target route after a successful login, i.e. /settings

lockit.on('login', function(user, res, target) {
  // ...
});

forgot::sent

A user forgot the password and an email has been sent. Callback function has two arguments.

• user is again the JSON object containing info about that particular user.
• res is the normal Express.js response object with all properties and methods.

lockit.on('forgot::sent', function(user, res) {
  // ...
});

forgot::success

User has created a new password. Callback function has two arguments.

• user is again the JSON object containing info about that particular user.
• res is the normal Express.js response object with all properties and methods.

lockit.on('forgot::success', function(user, res) {
  // ...
});

logout

A user logged out. Same as above without the target string.

lockit.on('logout', function(user, res) {
  // ...
});

delete

A user deleted an account. Same callback as above.

lockit.on('delete', function(user, res) {
  // ...
});

REST API

In a single page application (SPA) all routing and template rendering is done on the client. Before version 0.5.0 Lockit caught relevant routes, like /login or /signup, and did the entire rendering on the server.

Starting with version 0.5.0 you're able to use Lockit as a REST API and communic