auzy

Don't ever get confused when adding session middleware into your project!

Project features

• Modern ES6 syntax
• Promise and async/await ready
• Compatible with many middleware based frameworks (e.g. Express, Restify)
• Flexible to use any session storage (e.g. Redis, MongoDB)
• Well documented (JSDoc is in progress)
• Made as simple as possible
• Covered with unit tests
• Covered with functional tests for following frameworks:
  • Restify
  • Express
  • koa.js
  • Connect

It's all about auzy. The Node.js middleware library made to add sessions support.

The project is ready for use, but it is not tested well yet, so please be careful using it.

Quick start

For full usage examples with specific framework see the examples directory.

Install auzy and session storage (Redis in this example)

npm install --save auzy auzy-storage-redis
# or
yarn add auzy auzy-storage-redis

Add the middleware into your project

const auzyConfig = {
    session: {
        // Session name will be used as header name in this example.
        sessionName: 'X-Session-Token',

        // TTL is a session expiration time in milliseconds.
        ttl: 60 * 60 * 24 * 30 * 6 * 1000,

        // Contains a logic to fetch user data from database.
        // Promise is expected as return value, it has to resolve user data.
        // Resolved user data will be set as req.user for current request.
        // Or as ctx.state.user in case of Koa framework.
        loadUser: (sessionData) => {
            const query = {_id: new ObjectId(sessionData.userId)};
            return User.Model.findOne().exec();
        },
    },
};
const auzyEnvironment = {
    storage: 'redis',
    framework: 'express',
    transport: 'header',
};
app.use(auzy(auzyConfig, auzyEnvironment));

Login

Use session object inside your login route

async (req, res, next) => {
    const reqUser = req.body.user;
    const dbQuery = {
        email: reqUser.email,
    };
    const user = await User.Model.findOne(dbQuery).exec();
    if (!user) {
        return next();
    }
    await user.validatePassword(reqUser.password);
    await req.session.authenticate({userId: String(user._id)});
    res.send({user: req.user.name});
}

Logout

To logout and destroy current session you have to call destroy() method

async (req, res, next) => {
    const user = req.user;
    if (user) {
        // It is important to wait the destroying process
        // so after that line we will be sure that there is nothing
        // left from a previously authorized user.
        await req.session.destroy();
    }
    // User is already deleted from the request object
    // so we can safely use it in a general way, it will
    // be undefined here.
    res.send({user: req.user});
}

Configuration

There are two things you can specify in the configuration:

• Session handler configuration
• Environment hints

Session handler

Session handler is a core of auzy project, which has configuration options described in this section

function receiveSessionId(adapter, sessionName): string

The method describes how the sessionId will be fetched from the request.

function sendSessionId(adapter, sessionName, sessionId)

The method describes how the sessionId will be put into the response.

sessionName: string

Property specifies the session name, which will be passed to receiveSessionId or sendSessionId methods.

function loadUser(sessionData): Promise

The method describes how user will be loaded using sessionData. User object itself can be stored into your main application database, e.g. MongoDB. The returned promise should resolve user object fetched from DB. Fetched user will be stored in the request object (or something similar so you will be able to access it in any controller).

function generateSessionId(): string

The method describes how the new session ID will be generated. If not specified, the session ID will be Base64 encoded 20 bytes length cryptographically strong pseudo-random data. To generate it auzy uses node's module crypto.

ttl: string

Property specifies how long the session data will be valid until expiration. Value must be specified in milliseconds.

alwaysSave: boolean

If true the session data will be saved every time the session is loaded. Can be useful to resave the new user name if it is stored in the session data.

alwaysSend: boolean

If true the session ID will be send to client in the every response. If false the session ID will be send only when session.authenticate() is explicitly called.

Environment hints

Environment hints help auzy understand which kind of storage it should use or which framework context it is going to work in. So hint can describe framework or storage.

framework: string

Just a framework code. Following frameworks are supported for now:

• restify — Restify
• express — Express
• koa — koa.js
• connect — Connect

If the framework hint is specified, receiveSessionId and sendSessionId will get in their first argument adapter object, which actually just a unified way to modify request or response object for hinted framework.

storage: string

Storage hint specifies which kind of storage will be used to store session data. Following storages are supported now:

• redis — Redis alexey-detr/auzy-storage-redis

If not specified a native JS object storage will be used. It is non-persistent so any saved session data will be destroyed whenever the server will be restarted.

transport: string

Transport hint specifies how session ID will be transferred to client or from client. header is the only available transport for now. It passes session ID in the HTTP header named as session.sessionName (in the example above it was X-Session-Token).

Advanced config example

If your framework is not supported you can try to configure it with more complex config.

const auzyConfig = {
    session: {
        // Session name will appear as request and response header name below.
        sessionName: 'X-Session-Token',

        // TTL is the session expiration time in milliseconds.
        ttl: 60 * 60 * 24 * 30 * 6 * 1000,

        // Contains logic to fetch session ID from request object.
        // String with session ID must be returned.
        receiveSessionId: (req, sessionName) => req.header(sessionName),

        // Contains logic to send session ID to client via response object.
        sendSessionId: (res, sessionName, sessionId) => res.header(sessionName, sessionId),

        // Contains logic to fetch user data from database.
        // Promise is expected as return value, it should resolve user data.
        // Resolved user data will be set as req.user for current request.
        loadUser: (sessionData) => {
            const query = {_id: new ObjectId(sessionData.userId)};
            return User.Model.findOne().exec();
        }
    },
};
const auzyEnvironment = {storage: 'redis'};
app.use(auzy(auzyConfig, auzyEnvironment));

TODOs and ideas

• [ ] Allow to store any data in the session, not just authorization data.
• [ ] Various transports or ways to get / pass session IDs from / to client (header, cookie, body?)
• [ ] MongoDB session storage
• [ ] Authenticators support to validate credentials (e.g. email password pairs, any kind of tokens) with hashes or other verifiers. In other words it will provide easy to use Facebook login for example.
• [ ] Made project ready to support things like JWT which use client as a session storage.