No Partying Mariachis

    suspicious-session

    0.1.2 • Public • Published

    Suspicious Session

    This is a package to manage sessions stored in encrypted files (with AES), using UUIDv4 for client identification for Express.js. This package it's a newer version writted from zero based of session-crossover package (now deprecated). This package is developed with typescript and contains all required *.d.ts definitions inside it.

    Implementation

    • First install this package in your project:
    npm install --save suspicious-session
    • Then create a new express(); instance, and use the middleware as follows:
    import express from 'express';
    import { suspiciousSession } from 'suspicious-session';
    
    // Create the express instance
    const app = express();
    
    // Use the middleware
    app.use(suspiciousSession({
        path: './data',           // Where the sessions will be stored
        name: 'i-see-you',        // [ default = 'session-id' ] Name of the cookie to create
        maxAge: 15,               // [ default = 30 ] Time of session duration (in minutes)
        algorithm: 'aes-256-ccm', // [ default = 'aes-128-ccm' ] AES algorithm do you want to use
        
        /** An optional object in case if you want to change the way
         * of the library creates the cookies.
         */
        cookieOptions: {
            secure: false
        }
    }));

    Basic Usage

    The core of the package resides in req.session, which contains the necessary methods to manage the current sessions. All operations about sessions are available in that object. These are some examples of usage:

    • Create a new session, and save inside an object:
    app.get('/create', async (req, res) => {
        // Create a new session
        await req.session.create();
    
        // Add inside an object
        await req.session.current().save({
            id: 543,
            nick: 'nadja',
            typeUser: 4
        });
    
        // Ends the request
        res.end();
    });
    • Rewind the expiration time of the current session:
    app.get('/rewind', async (req, res) => {
        // Get if this connection has an active sesion
        const exist = !!req.session.current();
    
        // Rewind the expiration time
        if (exist) {
            req.session.rewind();
        }
    
        // Ends the request
        res.end();
    });
    • Destroy the current session:
    app.get('/destroy', async (req, res) => {
        // Get if this connection has an active sesion
        const exist = !!req.session.current();
    
        // Destroy the current session
        if (exist) {
            await req.session.destroy();
        }
    
        // Ends the request
        res.end();
    });
    • Read data from a session:
    app.get('/read', async (req, res) => {
        // Get the current active session
        const current = req.session.current();
    
        if (current) {
            // Read the session content
            const data = await current.load();
            res.json(data);
        } else {
            // Return null
            res.json(null);
        }
    });

    Configuration

    The configuration of the library it's simple, but quite flexible. As you see at the top, the parameters are just the necesary for simple implementations, but considerates some cases when you could need an specific behavior. The options are according to this interface:

    export interface Options {
        /**
         * The path of the folder in where `session-crossover` will adds the new sessions to be created.
         * If the folder doesn't exists, the library will be create the folder while implements the
         * middleware in the `express` instance.
         */
        path: string;
    
        /**
         * The name of the cookie which the session's encrypted UUID will be stored in the client. By default
         * the name it's `"session-id"`.
         */
        name?: string;
    
        /**
         * The lifetime duration (in minutes) of every session created. By default it's setted to
         * 30 mins of duration.
         */
        maxAge?: number;
    
        /**
         * The AES-Algorithm to be used for encrypt the data and the cookie value. By default, the algorithm
         * used is `"aes-128-ccm"`.
         */
        algorithm?: AESAlgorithm;
    
        /**
         * An optional object with a custom configuration of the cookie generated, in case if you need to
         * set an specific parameter. 
         */
        cookieOptions?: CookieOptions;
    }

    About this.algorithm:

    This parameter tells to the library which AES encryption algorithm do you want to use for encrypt the sessions. By default, use "aes-128-ccm", but if you want to use another algorithm, these are the available:

    • "aes-128-ccm"
    • "aes-128-gcm"
    • "aes-192-ccm"
    • "aes-192-gcm"
    • "aes-256-ccm"
    • "aes-256-gcm"
    • "chacha20-poly1305"

    About this.cookieOptions:

    In certain cases, it's probably that you want to create the cookies with a different settings than the default used by the library. The default values are:

    const cookieOptions = {
        httpOnly: true,
        sameSite: 'strict',
        secure: true,
        path: '/',
    };

    If you want to override some values, simply you can add only the parameter do you want to change (keeping the default values intact). For example, in case when you only need to change the "secure" parameter to false, then:

    app.use(suspiciousSession({
        path: './data',
        maxAge: 15,
        cookieOptions: {
            /**
             * This override the default value
             * "secure: true" to "false".
             */
            secure: false
        }
    }));

    ...or in other cases when you need to add a parameter without a default value, simply you can add that value as follows:

    app.use(suspiciousSession({
        path: './data',
        maxAge: 15,
        cookieOptions: {
            /**
             * The parameter "signed" doesn't has a
             * default value assigned.
             */
            signed: true
        }
    }));

    The available values to set are (see the express.js for details):

    Property Type Description
    domain string Domain name for the cookie. Defaults to the domain name of the app.
    encode function A synchronous function used for cookie value encoding. Defaults to encodeURIComponent.
    httpOnly boolean Flags the cookie to be accessible only by the web server.
    path string Path for the cookie. Defaults to "/".
    secure boolean Marks the cookie to be used with HTTPS only.
    signed boolean Indicates if the cookie should be signed.
    sameSite boolean or string Value of the “SameSite” Set-Cookie attribute. More information at here

    Install

    npm i suspicious-session

    DownloadsWeekly Downloads

    6

    Version

    0.1.2

    License

    MIT

    Unpacked Size

    165 kB

    Total Files

    206

    Last publish

    Collaborators

    • sleep-written