npm.io
4.0.0 • Published 2 years ago

token2session

Licence
ISC
Version
4.0.0
Deps
4
Size
18 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

Token to Session (token2session)

This is an Express middleware that adds a session provided by a JSON Web Token (JWT) to the request object. It can also be used as a security overlay by rejecting invalid tokens.

Installation

npm i token2session

Usage in ESM and Typescript:


import express from "express";
import tokenToSession from "token2session";

const app = express();
 ...
app.use(
  tokenToSession({
    secret: "your_jwt_secret",
    routeToOmit: ['/home', '/login', '/opened-route*'],
  })
);

Usage in commonJs:


const express = require("express");
const tokenToSession = require("token2session").default;

const app = express();
 ...
app.use(
  tokenToSession({
    secret: "your_jwt_secret",
    routeToOmit: ['/home', '/login', '/opened-route*'],
  })
);

Usage with jwksEndpoint and customKeySetHandler:


 ...
app.use(
  tokenToSession({
    jwksEndpoint: "https://your-jwks-endpoint-url",
    customKeySetHandler: (kid, keySet) => {
      /* eg with custom keySet: keySet = { kid1: "public_key..", kid2: "public_key.."  } */
      return keySet?.[kid];
    },
    routeToOmit: ['/home', '/login', '/opened-route*'],
  })
);

Usage with customKeySetHandler asynchronus:


 ...
app.use(
  tokenToSession({
    customKeySetHandler: async (kid) => {
      ...do something async
      return result (public_key or secret);
    },
    routeToOmit: ['/home', '/login', '/opened-route*'],
  })
);

Options

* = look at the Notes

Option Type Default Description
secret * (optional) string Secret used to sign the JWT.
jwksEndpoint * (optional) string JWKS endpoint url to fetch public keys from (simple get).
customKeySetHandler * (optional) function Custom handler to return the public key, which can be synchronous or asynchronous. If you're using jwksEnpoint, this function receives 2 parameters 'kid of token' and 'the return of enpoint', otherwise it will only take 'kid'.
jwtOptions (optional) object Options to pass to the jwt.verify function.
headerKey * (optional) undifined or string "authorization" Header key used to pass the token.
cookieKey * (optional) string Cookie name used to pass the token.
cookieSecret (optional) string Cookie secret used to sign the cookie.
session (optional) string "session" Session name used to store in the req object.
sessionInTokenKey (optional) string Key if the session is in a sub-object of the decoded token.
useBearer (optional) boolean true Set to false if you aren't using a bearer token.
rejectOnError (optional) boolean true reject all requests if the token is not valid. Set to false if you want to pass even in case of error.
rejectMessage (optional) string "Unauthorized" Sentence to return on reject.
routeToOmit * (optional) array [] Array of routes that should not be rejected.

Notes

  • The secret option is required if you're not using a jwksEndpoint or customKeySetHandler function.
  • If you use jwksEndpoint or customKeySetHandler function or both, the secret is useless.
  • If no headerKey or cookieKey is provided and useBearer aren't set to false, the middleware will use the authorization header and assume a bearer token.
  • If no headerKey or cookieKey is provided and useBearer is set to false, an error will be thrown.
  • The routeToOmit option accepts an array of routes that should not be rejected. A route pattern can include a * wildcard to match multiple routes.

Keywords

jwtsessionauthdecode