vs-session

This is simple express session management middleware. Mongo DB is used as session store.

Usage

1. Create sessions

// CJS
import VsSession from "@vs-org/session";

// Module
const VsSession =  require("@vs-org/session").default;

const vsSession = VsSession({
    url: "mongodb://localhost:27017/vs-rate-limiter",
    collectionName: "login-session",
    secret: "This is session secret",
    cookie: {
      domain: "",
      maxAge: 86400,
      httpOnly: false,
      name: "vs-session",
      path: "/",
      secure: false
    }
  });

  app.get("/path1", vsSession, async (req: Request, resp: Response) => {
    return resp.send("Login success response");
  });

2. Only update sessions

   a) If use case is only to check session and update it. Then onlyCheckSessionRoutes option can be used b) onlyCheckSessionRoutes does not contain present route then new session will be created for the request as it is used as middlware. c) Now we can check if session is there in express request, if yes then update sessionContext and to save it back to session store call updateSession on session.

// CJS
import VsSession from "@vs-org/session";

// Module
const VsSession =  require("@vs-org/session").default;

const vsSession = VsSession({
    url: "mongodb://localhost:27017/vs-rate-limiter",
    collectionName: "login-session",
    secret: "This is session secret",
    cookie: {
      domain: "",
      maxAge: 86400,
      httpOnly: false,
      name: "vs-session",
      path: "/",
      secure: false
    },
    onlyCheckSessionRoutesRoutes: ["/update-session", "/logout"]
  });

  app.get(
    "/update-session",
    vsSession,
    async (req: Request, resp: Response) => {
      if (req.session) {
        req.session.sessionContext.user = {
          username: "user1-username",
          name: "John Doe"
        };
        await req.session.updateSession();
      }
      return resp.send("Update session success response");
    }
  );

3. Update session if present, or else create and update session

   a) If use case is to get current session or create new session then onlyCheckSessionRoutes option can be skipped or route can be removed from onlyCheckSessionRoutes array, VsSession will check if session cookie is present. b) If it is present express request will be enriched with current session and session context. c) Now we can update session and to save it back to session store call updateSession on session.

// CJS
import VsSession from "@vs-org/session";

// Module
const VsSession =  require("@vs-org/session").default;

const vsSession = VsSession({
    url: "mongodb://localhost:27017/vs-rate-limiter",
    collectionName: "login-session",
    secret: "This is session secret",
    cookie: {
      domain: "",
      maxAge: 86400,
      httpOnly: false,
      name: "vs-session",
      path: "/",
      secure: false
    },
    onlyCheckSessionRoutesRoutes: ["/logout"]
  });

  app.get(
    "/update-session",
    vsSession,
    async (req: Request, resp: Response) => {
      if (req.session) {
        req.session.sessionContext.user = {
          username: "user1-username",
          name: "John Doe"
        };
        await req.session.updateSession();
      }
      return resp.send("Update session success response");
    }
  );

4. Delete session

// CJS
import VsSession from "@vs-org/session";

// Module
const VsSession =  require("@vs-org/session").default;

const vsSession = VsSession({
    url: "mongodb://localhost:27017/vs-rate-limiter",
    collectionName: "login-session",
    secret: "This is session secret",
    cookie: {
      domain: "",
      maxAge: 86400,
      httpOnly: false,
      name: "vs-session",
      path: "/",
      secure: false
    },
    onlyCheckSessionRoutesRoutes: ["/logout"]
  });

  app.get("/logout", vsSession, async (req: Request, resp: Response) => {
    if (req.session) {
      await req.session.destroySession();
    }
    return resp.send("Logout session success response");
  });

Examples

1. Standard OIDC flow /authorize request

   a) If user is already logged in /authorize should redirect user to callback with response type from /authorize call. b) If user is not logged in (sesion is not present) then user should be redirected to login page.

// CJS
import VsSession from "@vs-org/session";

// Module
const VsSession =  require("@vs-org/session").default;

const vsSession = VsSession({
    url: "mongodb://localhost:27017/vs-rate-limiter",
    collectionName: "login-session",
    secret: "This is session secret",
    cookie: {
      domain: "",
      maxAge: 86400,
      httpOnly: false,
      name: "vs-session",
      path: "/",
      secure: false
    },
    onlyCheckSessionRoutesRoutes: ["/authorize"]
  });

/**
* As here VsSession is used as middlware current route is not present in `onlyCheckSessionRoutesRoutes`.
*/
 app.get("/authorize", vsSession, async (req: Request, resp: Response) => {
    if (req.session) {
      return resp.send("Callback redirect");
    }
    return resp.send("Login page redirect");
  });

/**
* As here VsSession is used as middlware current route is not present in `onlyCheckSessionRoutesRoutes`.
* So package will create session.
*/
app.get("/login", vsSession, async (req: Request, resp: Response) => {
    return resp.send("Login page response");
});


/**
* Create new session and udpate user information.
* Note `/login` page session should be destroyed.
* And new session should be created for logged in user to avoid session fixation attacks.
*/
app.get(
    "/post-login",
    vsSession,
    async (req: Request, resp: Response) => {
      if (req.session) {
        req.session.sessionContext.user = {
          username: "user1-username",
          name: "John Doe"
        };
        await req.session.updateSession();
      }
      return resp.send("Callback redirect");
    }
);

Options

| option | required | default | Description | | -------------------------------------- | -------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | url | true | NA | Mongo db connection URL. This package does not accept instance of mongo, it will establish seperate connection | | username | false | NA | Mongo DB username | | password | false | NA | Mongo DB password | | loggerLevel | false | NA | Logger level for mongodb packages. Only debug value is accepted. | | collectionName | false | session_{DB_NAME} | Collection name for session store | | secret | true | NA | Session secret, this will be used to sign cookies and verify signature. So make sure it will be same and strong as if it is changed all past sessions will be invalid by default | | sessionIdGenerator | false | @vs-org/random.random({ length: 72, charset: DEFAULTS.randomCharSet }) | This option can be used to generate custom session id's. Make sure this function always returns unique strings of length 24 or else there will be unexpected errors or behaviours. Default key is generated with @vs-org/random package with custom char set ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 | | expiresInSeconds | false | 30 days = 30 * 24 * 60 * 60 | This will be used for both Mongo store as well as cookie expiry (Max-Age). If cookie.maxAge and expiresInSeconds both options are provided then expiresInSeconds takes precedence for session expiry. As ideally session should be destroyed from client side and server side. | | onlyCheckSessionRoutes | false | NA | Use this option if there is need to just check session through middleware. If some routes only needs to check session then add it to onlyCheckSessionRoutes array then if session cookies are missing package will not create new session. | | onlyCheckSessionRoutesWithHTTPMethod | false | NA | Use this option if there is need to just check session through middleware. If some routes only needs to check session then add it to onlyCheckSessionRoutes array but if same route is used with different HTTP methods and needs to check session only for sepecific method then use this option. Eg: { "POST": ["/login"], "GET": ["/logout"] } | | mongoDbOperationHandlerPackage | true | mongoose | This package is dependent on mongodb or mongoose package to connect and handle mongo db operations. But if application is already using one of these packages then instead of installing peer dependecy there is possibility to use this option to inform VsSession package to use either mongodb or mongoose package. There is no difference between the functionalities | | cookie | true | Default cookie values look at below cookie otions | Cookie options are for session cookies. | | cookie.name | true | vs-sess | Session cookie name. | | cookie.domain | true | "" | Session cookie domain. | | cookie.header | false | "cookie" | Custom cookie header. If application is using proxy servers and processing and forwarding cookies in different header (eg: x-forwared-cookies). Then this option can be used so that VsSession can extract proper cookies from request. | | cookie.maxAge | true | 30 days = 30 * 24 * 60 * 60 | Session cookie expiry, if expiresInSeconds option present then expiresInSeconds will take precedence. And if is not present then this option will be used for session expiry. | | cookie.httpOnly | true | false | Session cookie httpOnly attribute will determine if JS should have access to session cookie. Recommended way is to set it as always true | | cookie.secure | true | false | Session cookie secure attribute only send cookies with HTTPS and not HTTP | | cookie.sameSite | false | None | Cookies used for storing sensetive information like authentication / authenticated session should have short lifetime with SameSite as "Strict" or "Lax" |

Session object in Express request

| session attribute | type | Description | | -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | request.sessionId | string | Session id | | request.session.sessionContext | object | Session context object to keep application required data in session in key value format. | | request.session.updateSession | Function | Function to update parameters session. Follow above examples to use it with express request. This function can also accept sessionId and sessionContext as parameters to update, if session id is not from current session then package will throw error | | request.session.destroySession | Function | Function to delete current session. Follow above examples to use it with express request. This function can also accept sessionId as parameters to delete session, if session id is not from current session then package will throw error | | request.session.getSession | Function | Function to getSession session. This function can also accept sessionId as parameters to get session, if session id is not from current session then package will throw error. |

Session helper function signatures

| Name | Function signature | | ---------------- | ----------------------------------------------------------------------- | | updateSession | (sessionId?: string,sessionContext?: SessionContext) => Promise<void> | | destroySession | (sessionId?: string) => Promise<boolean \| never> | | getSession | (sessionId?: string) => Promise<SessionContext> |

License

MIT (see LICENSE)

Note

This package is not tested with concurrent requests and heavy load (Not production ready). This is experimental package and not actively maintened, only use for development and POC's.