@vs-org/session v0.0.4

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

Session object in Express request

Session helper function signatures

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.