Build a Session Management System

Introduction

Session management is essential for web applications that need to maintain user state across requests. Whether it's keeping users logged in, storing shopping cart contents, or tracking user preferences, sessions are the foundation of personalized web experiences.

In this tutorial, we'll build a complete session management system for Node.js/Express applications with support for multiple storage backends, security features, and distributed session handling.

Core Concepts

How Sessions Work

When a user visits a website for the first time, the server creates a unique session and sends a session identifier (usually as a cookie) to the client. On subsequent requests, the client sends this identifier, allowing the server to retrieve the associated session data.

Session Storage

Sessions can be stored in various backends:

• In-Memory - Fast but not persistent across restarts
• Redis - Fast, persistent, supports distributed systems
• Database - Persistent but slower
• Cookie-Based - All data stored client-side (signed)

Session Security

Key security considerations:

• Session ID Entropy - Use cryptographically random IDs
• Secure Cookies - Use HttpOnly, Secure, SameSite flags
• Session Regeneration - Regenerate ID after login
• Session Expiration - Automatic timeout for inactivity
• Secure Storage - Encrypt sensitive session data

Project Overview

Our session management system will include:

Prerequisites

• Node.js 14+ - Installed on your system
• Express - Install with npm
• Redis - Optional, for distributed sessions

Session Store Interface

Create session/store.js - the abstract session store:

class SessionStore {
    async get(sessionId) {
        throw new Error('Method not implemented');
    }

    async set(sessionId, session, maxAge) {
        throw new Error('Method not implemented');
    }

    async destroy(sessionId) {
        throw new Error('Method not implemented');
    }

    async touch(sessionId, session) {
        throw new Error('Method not implemented');
    }

    async all() {
        throw new Error('Method not implemented');
    }

    async length() {
        throw new Error('Method not implemented');
    }

    async clear() {
        throw new Error('Method not implemented');
    }
}

module.exports = SessionStore;

Create session/memory-store.js - in-memory storage:

const SessionStore = require('./store');

class MemoryStore extends SessionStore {
    constructor() {
        super();
        this.sessions = new Map();
    }

    get(sessionId) {
        const session = this.sessions.get(sessionId);
        if (!session) return null;
        
        if (session.expires && new Date(session.expires) < new Date()) {
            this.sessions.delete(sessionId);
            return null;
        }
        
        return session;
    }

    set(sessionId, session, maxAge) {
        const expires = maxAge 
            ? new Date(Date.now() + maxAge)
            : new Date(Date.now() + 86400000);
        
        this.sessions.set(sessionId, {
            ...session,
            expires: expires.toISOString()
        });
    }

    destroy(sessionId) {
        this.sessions.delete(sessionId);
    }

    touch(sessionId, session) {
        if (this.sessions.has(sessionId)) {
            const existing = this.sessions.get(sessionId);
            this.sessions.set(sessionId, {
                ...existing,
                ...session,
                expires: new Date(Date.now() + 86400000).toISOString()
            });
        }
    }

    all() {
        return Array.from(this.sessions.values());
    }

    length() {
        return this.sessions.size;
    }

    clear() {
        this.sessions.clear();
    }

    prune() {
        const now = new Date();
        for (const [id, session] of this.sessions) {
            if (session.expires && new Date(session.expires) < now) {
                this.sessions.delete(id);
            }
        }
    }
}

module.exports = MemoryStore;

Session Manager

Create session/manager.js - the core session manager:

const crypto = require('crypto');
const MemoryStore = require('./memory-store');

class SessionManager {
    constructor(options = {}) {
        this.store = options.store || new MemoryStore();
        this.cookieName = options.cookieName || 'session_id';
        this.cookieOptions = {
            httpOnly: options.httpOnly !== false,
            secure: options.secure || false,
            sameSite: options.sameSite || 'lax',
            path: options.cookiePath || '/',
            maxAge: options.cookieMaxAge || 86400000,
            domain: options.cookieDomain || null
        };
        this.secret = options.secret || this._generateSecret();
        this.genid = options.genid || this._generateId;
        this.resave = options.resave !== false;
        this.saveUninitialized = options.saveUninitialized !== false;
        this rolling = options.rolling || false;
        
        this._pruneInterval = setInterval(() => {
            if (this.store.prune) {
                this.store.prune();
            }
        }, 60000);
    }

    _generateSecret() {
        return crypto.randomBytes(32).toString('hex');
    }

    _generateId() {
        return crypto.randomBytes(32).toString('hex');
    }

    getSession(req) {
        return req._session;
    }

    async getSessionData(sessionId) {
        if (!sessionId) return null;
        
        const session = await this.store.get(sessionId);
        return session ? session.data : null;
    }

    async createSession(req) {
        const sessionId = this.genid();
        const session = new Session(sessionId, {}, this);
        
        req._session = session;
        req.session = session;
        
        return session;
    }

    async loadSession(req) {
        const sessionId = this._getCookie(req);
        
        if (sessionId) {
            const sessionData = await this.getSessionData(sessionId);
            
            if (sessionData) {
                const session = new Session(sessionId, sessionData, this);
                req._session = session;
                req.session = session;
                return session;
            }
        }
        
        return this.createSession(req);
    }

    _getCookie(req) {
        const cookies = require('url').parse(req.url, true).query;
        return req.headers.cookie 
            ? this._parseCookies(req.headers.cookie)[this.cookieName]
            : null;
    }

    _parseCookies(cookieHeader) {
        const cookies = {};
        if (!cookieHeader) return cookies;
        
        cookieHeader.split(';').forEach(cookie => {
            const [name, value] = cookie.split('=');
            if (name && value) {
                cookies[name.trim()] = value.trim();
            }
        });
        
        return cookies;
    }

    setCookie(res, sessionId) {
        let cookieValue = `${this.cookieName}=${sessionId}`;
        
        if (this.cookieOptions.httpOnly) cookieValue += '; HttpOnly';
        if (this.cookieOptions.secure) cookieValue += '; Secure';
        if (this.cookieOptions.sameSite) cookieValue += `; SameSite=${this.cookieOptions.sameSite}`;
        if (this.cookieOptions.path) cookieValue += `; Path=${this.cookieOptions.path}`;
        if (this.cookieOptions.maxAge) cookieValue += `; Max-Age=${Math.floor(this.cookieOptions.maxAge / 1000)}`;
        if (this.cookieOptions.domain) cookieValue += `; Domain=${this.cookieOptions.domain}`;
        
        res.setHeader('Set-Cookie', cookieValue);
    }

    destroyCookie(res) {
        res.setHeader('Set-Cookie', 
            `${this.cookieName}=; HttpOnly; Path=/; Max-Age=0`
        );
    }

    destroy(req, callback) {
        const session = req._session;
        
        if (session) {
            this.store.destroy(session.id, (err) => {
                this.destroyCookie(res);
                if (callback) callback(err);
            });
        } else if (callback) {
            callback();
        }
    }

    close() {
        if (this._pruneInterval) {
            clearInterval(this._pruneInterval);
        }
    }
}

class Session {
    constructor(id, data, manager) {
        this.id = id;
        this.data = data;
        this._manager = manager;
        this._isNew = !Object.keys(data).length;
        this._dirty = false;
    }

    get(key) {
        return this.data[key];
    }

    set(key, value) {
        this.data[key] = value;
        this._dirty = true;
    }

    delete(key) {
        delete this.data[key];
        this._dirty = true;
    }

    has(key) {
        return key in this.data;
    }

    regenerate(callback) {
        const newId = this._manager.genid();
        this._manager.store.destroy(this.id);
        this.id = newId;
        this._isNew = true;
        this._dirty = true;
        
        if (callback) callback();
    }

    save(callback) {
        if (!this._dirty && this._manager.resave === false) {
            if (callback) callback();
            return;
        }
        
        this._manager.store.set(
            this.id, 
            { data: this.data },
            this._manager.cookieOptions.maxAge,
            (err) => {
                this._dirty = false;
                if (callback) callback(err);
            }
        );
    }

    touch(callback) {
        this._manager.store.touch(this.id, { data: this.data }, callback);
    }

    destroy(callback) {
        this._manager.store.destroy(this.id, callback);
    }
}

module.exports = SessionManager;

Express Middleware

Create session/middleware.js:

const SessionManager = require('./manager');
const MemoryStore = require('./memory-store');

function session(options = {}) {
    const manager = new SessionManager({
        store: options.store || new MemoryStore(),
        cookieName: options.name || 'session_id',
        secret: options.secret,
        cookie: options.cookie || {},
        genid: options.genid,
        resave: options.resave,
        saveUninitialized: options.saveUninitialized,
        rolling: options.rolling
    });

    return async function sessionMiddleware(req, res, next) {
        if (req.method === 'OPTIONS') {
            return next();
        }

        try {
            await manager.loadSession(req);
            
            const originalSave = req.session.save;
            req.session.save = function(callback) {
                manager.setCookie(res, req.session.id);
                originalSave.call(this, callback);
            };

            if (manager.rolling && req.session) {
                const originalSetCookie = res.setHeader;
                res.setHeader = function(name, value) {
                    if (name === 'Set-Cookie') {
                        const cookie = Array.isArray(value) ? value[0] : value;
                        if (cookie && !cookie.includes('Max-Age')) {
                            value = `${cookie}; Max-Age=${Math.floor(manager.cookieOptions.maxAge / 1000)}`;
                        }
                    }
                    return originalSetCookie.call(this, name, value);
                };
            }

            req.sessionManager = manager;
            
            const originalEnd = res.end;
            res.end = function(chunk, encoding, callback) {
                if (req.session && (req.session._dirty || manager.saveUninitialized)) {
                    req.session.save((err) => {
                        if (!err) {
                            manager.setCookie(res, req.session.id);
                        }
                        return originalEnd.call(res, chunk, encoding, callback);
                    });
                } else {
                    return originalEnd.call(res, chunk, encoding, callback);
                }
            };

            next();
        } catch (err) {
            next(err);
        }
    };
}

module.exports = session;

Security Features

Create session/security.js for enhanced security:

const crypto = require('crypto');

function secureSession(options = {}) {
    const {
        enableCSRF = true,
        enableClickJacking = true,
        enableHSTS = false,
        maxAge = 86400000
    } = options;

    return function secureMiddleware(req, res, next) {
        if (enableClickJacking) {
            res.setHeader('X-Frame-Options', 'DENY');
        }
        
        res.setHeader('X-Content-Type-Options', 'nosniff');
        res.setHeader('X-XSS-Protection', '1; mode=block');
        
        if (enableHSTS) {
            res.setHeader('Strict-Transport-Security', 
                `max-age=${maxAge}; includeSubDomains`
            );
        }

        if (enableCSRF && req.session) {
            const csrfToken = req.session.get('_csrf') || 
                crypto.randomBytes(32).toString('hex');
            req.session.set('_csrf', csrfToken);
            req.csrfToken = csrfToken;
            
            res.locals.csrfToken = csrfToken;
        }

        next();
    };
}

function csrfProtection() {
    return function csrfMiddleware(req, res, next) {
        if (['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
            return next();
        }

        const csrfToken = req.body._csrf || 
            req.headers['x-csrf-token'];
        
        const sessionToken = req.session ? req.session.get('_csrf') : null;

        if (!csrfToken || csrfToken !== sessionToken) {
            return res.status(403).json({ 
                error: 'Invalid CSRF token' 
            });
        }

        next();
    };
}

function sessionProtection(options = {}) {
    const {
        enableFingerprint = true,
        enableIPBinding = false,
        maxAge = 300000
    } = options;

    let fingerprint;

    try {
        const { createHash } = require('crypto');
        fingerprint = createHash('sha256');
    } catch (e) {
        fingerprint = null;
    }

    return function protectMiddleware(req, res, next) {
        if (!req.session || !req.session.get('_initialized')) {
            req.session.set('_initialized', true);
            req.session.set('_created', Date.now());
            
            if (enableFingerprint && fingerprint) {
                const fp = [
                    req.headers['user-agent'],
                    req.headers['accept-language'],
                    req.ip
                ].join('|');
                req.session.set('_fingerprint', fingerprint.update(fp).digest('hex'));
            }
            
            if (enableIPBinding) {
                req.session.set('_ip', req.ip);
            }
        }

        if (enableFingerprint && fingerprint && req.session.get('_fingerprint')) {
            const currentFP = [
                req.headers['user-agent'],
                req.headers['accept-language'],
                req.ip
            ].join('|');
            const currentHash = fingerprint.update(currentFP).digest('hex');
            
            if (currentHash !== req.session.get('_fingerprint')) {
                req.session.destroy();
                return res.status(403).json({
                    error: 'Session fingerprint mismatch'
                });
            }
        }

        if (enableIPBinding && req.session.get('_ip')) {
            if (req.ip !== req.session.get('_ip')) {
                req.session.destroy();
                return res.status(403).json({
                    error: 'IP address changed'
                });
            }
        }

        next();
    };
}

module.exports = {
    secureSession,
    csrfProtection,
    sessionProtection
};

Distributed Session Support

Create session/redis-store.js for Redis-backed sessions:

const SessionStore = require('./store');
const Redis = require('redis');

class RedisStore extends SessionStore {
    constructor(options = {}) {
        super();
        
        this.prefix = options.prefix || 'session:';
        this.client = options.client || this._createClient(options);
        this.serializer = options.serializer || JSON;
        this.ttl = options.ttl || 86400;
    }

    _createClient(options) {
        const client = Redis.createClient({
            socket: {
                host: options.host || 'localhost',
                port: options.port || 6379
            },
            password: options.password,
            database: options.db || 0
        });
        
        client.on('error', (err) => console.error('Redis error:', err));
        return client;
    }

    async connect() {
        if (!this.client.isOpen) {
            await this.client.connect();
        }
    }

    _getKey(sessionId) {
        return `${this.prefix}${sessionId}`;
    }

    async get(sessionId) {
        await this.connect();
        
        const data = await this.client.get(this._getKey(sessionId));
        if (!data) return null;
        
        try {
            return this.serializer.parse(data);
        } catch (e) {
            return null;
        }
    }

    async set(sessionId, session, maxAge) {
        await this.connect();
        
        const key = this._getKey(sessionId);
        const data = this.serializer.stringify({
            ...session,
            expires: maxAge ? Date.now() + maxAge : null
        });
        
        const ttl = maxAge ? Math.floor(maxAge / 1000) : this.ttl;
        await this.client.setEx(key, ttl, data);
    }

    async destroy(sessionId) {
        await this.connect();
        await this.client.del(this._getKey(sessionId));
    }

    async touch(sessionId, session) {
        await this.connect();
        await this.client.expire(this._getKey(sessionId), this.ttl);
    }

    async all() {
        await this.connect();
        
        const keys = await this.client.keys(`${this.prefix}*`);
        const sessions = [];
        
        for (const key of keys) {
            const data = await this.client.get(key);
            if (data) {
                sessions.push(this.serializer.parse(data));
            }
        }
        
        return sessions;
    }

    async length() {
        await this.connect();
        const keys = await this.client.keys(`${this.prefix}*`);
        return keys.length;
    }

    async clear() {
        await this.connect();
        const keys = await this.client.keys(`${this.prefix}*`);
        
        if (keys.length > 0) {
            await this.client.del(keys);
        }
    }

    async prune() {
        await this.connect();
        
        const keys = await this.client.keys(`${this.prefix}*`);
        const now = Date.now();
        
        for (const key of keys) {
            const data = await this.client.get(key);
            if (data) {
                const session = this.serializer.parse(data);
                if (session.expires && session.expires < now) {
                    await this.client.del(key);
                }
            }
        }
    }
}

module.exports = RedisStore;

Testing the Session System

Create a test application:

// app.js
const express = require('express');
const session = require('./session/middleware');
const MemoryStore = require('./session/memory-store');
const { secureSession, csrfProtection } = require('./session/security');

const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true }));

app.use(session({
    name: 'my_session',
    store: new MemoryStore(),
    secret: 'my-secret-key-change-this',
    resave: false,
    saveUninitialized: true,
    cookie: {
        httpOnly: true,
        secure: false,
        maxAge: 3600000
    }
}));

app.get('/', (req, res) => {
    res.send(`
        <h1>Session Demo</h1>
        <p>Session ID: ${req.session.id}</p>
        <p>Visits: ${req.session.get('visits') || 0}</p>
        <form method="POST" action="/increment">
            <button type="submit">Increment Visit</button>
        </form>
        <form method="POST" action="/login">
            <button type="submit">Login (Regenerate Session)</button>
        </form>
        <form method="POST" action="/logout">
            <button type="submit">Logout (Destroy Session)</button>
        </form>
    `);
});

app.post('/increment', (req, res) => {
    const visits = (req.session.get('visits') || 0) + 1;
    req.session.set('visits', visits);
    res.redirect('/');
});

app.post('/login', (req, res) => {
    req.session.regenerate(() => {
        req.session.set('user', { id: 1, name: 'John Doe' });
        res.redirect('/');
    });
});

app.post('/logout', (req, res) => {
    req.session.destroy(() => {
        res.redirect('/');
    });
});

app.get('/api/session', (req, res) => {
    res.json({
        id: req.session.id,
        data: req.session.data,
        isNew: req.session._isNew
    });
});

app.listen(3000, () => {
    console.log('Session demo running on http://localhost:3000');
});

Run and test:

node app.js

# Visit http://localhost:3000
# Check the session ID and visit count

Summary

Congratulations! You've built a complete session management system. Here's what you learned:

• Session Store - How to create abstract storage interfaces
• Memory Store - In-memory session storage implementation
• Session Manager - Core session lifecycle management
• Express Integration - Middleware for Express.js
• Security - CSRF protection, session fixation prevention
• Distributed Sessions - Redis-backed session storage

Possible Extensions

• Add session clustering
• Implement database-backed storage
• Add session analytics
• Implement session locking
• Add compression for session data
• Build a session debugging tool