next-server-session

Functions to handle serverside session data and csrf tokens for nextJS 10.x

They can be used both in getServerSideProps as well as in API routes.

Heads up!
This module provides a simple and effective mechanism to protect your application against cross site request forgery attacks.

API

• configure()
• getSessionData()
• setSessionData()
• replaceSessionData()
• pluckSessionProperty()
• destroySession()
• getCSRFToken()
• validateCSRFToken()

Additional API

• createMemorySessionStore()
• createRedisSessionStore()
• createCookieHandler()

configure()

In order to be able to use the session mechanism, it needs to be initialized once on server startup. The most basic example is this:

const { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_SERVER } = require("next/constants");

module.exports = (phase, { defaultConfig }) => {
    if(phase === PHASE_PRODUCTION_SERVER || phase === PHASE_DEVELOPMENT_SERVER){
        require("next-server-session").configure();
    }

    return defaultConfig;
}

By calling configure() without providing any probs, you default to a in-memory session management with a default session lifetime of 30 minutes. If you want to modify the session lifetime, pass a session duration as sessionMaxAgeMS.

You should monitor your servers RAM consumption carefully when using this. If you notice a high load, you can swith to an external session storage like redis, memcached, a mySQL database or just the harddrive.

If you want to host your application on multiple servers behind a load balancer, you need to have a central external session store as well.

Typescript tip:
You can tell TS about the interface of your returned session object: getSessionData<T>(...): Promise<T>

Example usage in getServerSideProps()

Fetching the currently logged in user - if any.

export async function getServerSideProps(context: GetServerSidePropsContext){
    const {user = null} = await getSessionData(context);
    return {
        props: {
            user    
        }    
    }
}

Example usage in API routes

Return user data from an API endpoint, when logged in.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    const {user = null} = await getSessionData(req, res);
    if(!user){
        res.status(403).end("Forbidden");
        return;        
    }
    res.json(fetchUserData(user));
    res.end();        
}

Example usage in getServerSideProps()

Log some actions of the user to modify the experience in other places.

export async function getServerSideProps(context: GetServerSidePropsContext){
    await setSessionData({viewedPricingPage: true});    

    return {
        props: {
            data: getPricingData()        
        }    
    }
}

Example usage in API routes

Place products in a cart and persist it in the session.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    const {cart = {}} = await getSessionData(req, res);
    const {article, amount} = req.body;
    if(validateArticle(article)){
        cart[article] = (cart[article] || 0) + parseInt(amount, 10);
        await setSessionData(req, res, {cart});   
    }    
    res.end("ok");      
}

Example usage in getServerSideProps()

Resets a multi-step form and all helper data. Still be careful with this!

export async function getServerSideProps(context: GetServerSidePropsContext){
    await replaceSessionData({step: 1});    

    return {
        props: {
        }    
    }
}

Example usage in API routes

A login example where any stale data from previous user sessions is reset.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    const {username, password} = req.body;
    let result = login(username, password);
    if(result.user){
        await replaceSessionData({user: result.user});
        res.end("ok");
        return;
    }
    res.end(result.error);
}

Typescript tip:
You can tell TS about the type of the returned value: pluckSessionProperty<T>(...): Promise<T | null>

Example usage in getServerSideProps()

An API handler might store any errors in the session and redirect back to the form. The errors are plucked from the session and displayed in the form once.

export async function getServerSideProps(context: GetServerSidePropsContext){
    const formErrors = await pluckSessionProperty(context, "formErrors");

    return {
        props: {
            formErrors        
        }    
    }
}

Example usage in API routes

A user came from a referral link to a shop. The referral ID is applied ONCE to a purchase, then removed from the session.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
      const referrer = pluckSessionProperty(req, res, "refId");
      res.end(processPurchase(referrer));
}

Example usage in getServerSideProps()

This will logout the current user, if a valid CSRF token has been passed. Will render the page, if the logout failed.

export async function getServerSideProps(context: GetServerSidePropsContext){
    if(await validateCSRFToken(context.params.csrf)){
        await destroySession();
        return {
            redirect: {
                to: "/"
            }    
        }        
    }

    return {
        props: {    
        }    
    }
}

Example usage in API routes

Same logout example, but with a pure API route.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    const {csrf} = req.body;
    if(await validateCSRFToken(csrf)){
        destroySession();
        res.redirect("/");
        return;
    }
    res.redirect("/");      
}

Example usage in getServerSideProps()

This generates a CSRF token that can be passed with any forms or requests to the API.

export async function getServerSideProps(context: GetServerSidePropsContext){
    return {
        props: {    
            csrfToken: await getCSRFToken(context)
        }    
    }
}

Example usage in API routes

A single page application might automatically receive new tokens from each API call to sign the next request.

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    const {action, csrfToken} = req.body;
    if(await validateCSRFToken(csrfToken)){
        res.json({
            result: performAction(action),
            nextToken: await getCSRFToken(req, res)
        });
        res.end();
        return;
    }
    res.status(400).end("Bad request"); 
}

Example usage in getServerSideProps()

Any page or request that performs an action for a user needs to be protected by a CSRF token.

export async function getServerSideProps(context: GetServerSidePropsContext){
    if(await validateCSRFToken(context, context.param.csrf)){
        const {user = null} = getSessionData(context);
        performSomeAction(user);    
    }
        
    return {
        props: {    
        }    
    }
}

Example usage in API routes

export default async function handler(req: NextApiRequest, res: NextApiResponse){
    if(await validateCSRFToken(req, res, req.body.csrfToken)){
        performSomeAction();
        res.end("ok");    
    }
    res.status(400).end("Bad request");   
}

The following methods are internal factory functions for the default store and cookie handler.

createMemorySessionStore(maxSessionAgeMS: number): SessionStore

Returns a new session store for in-memory storage of session objects. By default, it will keep session objects for 30 minutes after they have been interacted with the last time (by getting or setting).

In case you want to modify the default max session age, you need to call this method and pass the result to the configure() method:

const { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_SERVER } = require("next/constants");

module.exports = (phase, { defaultConfig }) => {
    if(phase === PHASE_PRODUCTION_SERVER || phase === PHASE_DEVELOPMENT_SERVER){
        require("next-server-session").configure({
            sessionStore: createMemorySessionStore(10 * 60 * 1000) // 10 Minutes
        });
    }

    return defaultConfig;
}

I recomment that you implement your own session store when you want to keep your session data any place else than in the memory of your current machine.

To create a compatible session store, you need to implement its TS interface:

interface SessionStore {
    id: () => Promise<string>;
    get: (sessionId: string) => Promise<any | null>;
    set: (sessionId: string, data: any) => Promise<void>;
    merge: (sessionId: string, data: any) => Promise<void>;
    destroy: (sessionId: string) => Promise<any>
}

When implementing your own session store, you can resort to the tests I wrote for the memory session store.

createCookieHandler(cookieName: string = "nextSession", cookieConfig: any)

This factory function creates a new cookie handler based on the cookie package.

If you want to change the used cookie name or update any configuration, call the method and pass the result to the configure() method.

The default cookie config is:

{
    "httpOnly": true,
    "sameSite": true,
    "path": "/",
    "secure": false
}

You can pass any options, the cookie module can understand.

const { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_SERVER } = require("next/constants");

module.exports = (phase, { defaultConfig }) => {
    if(phase === PHASE_PRODUCTION_SERVER || phase === PHASE_DEVELOPMENT_SERVER){
        require("next-server-session").configure({
            cookieHandler: createCookieHandler("sId", {
              "httpOnly": true,
              "sameSite": true,
              "path": "/basedir",
              "secure": true
          })
        });
    }

    return defaultConfig;
}

createRedisSessionStore(maxSessionAgeMS: number, host?: string, port?: number, db?: number): SessionStore

In version 1.2, I added a redis session store that works if you have the redis module from npm installed in your project.

It works like the memory session store, but connects and saves all session data on a given redis server.

const { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_SERVER } = require("next/constants");
const { createRedisSessionStore } = require("next-server-session/dist/redisSessionStore");

module.exports = (phase, { defaultConfig }) => {
    if(phase === PHASE_PRODUCTION_SERVER || phase === PHASE_DEVELOPMENT_SERVER){
        require("next-server-session").configure({
            sessionStore: createRedisSessionStore(
                10 * 60 * 1000, // 10 Minutes
                "192.168.178.1",
                6379
            )
        });
    }

    return defaultConfig;
}