gate-guard

gate-guard

Lightweight and configurable ExpressJS middleware to decode and verify jsonwebtoken JWTs that are sent via cookies.

Let the gate-guard protect your resources by deciding what calls make it through or not.

Installation

Requires Node 8 or later

npm i --save gate-guard
# or 
yarn add gate-guard

Minimum Setup

This example will protect all routes listed after the middleware behind the jwt verification.

import gateGuard from 'gate-guard';

// jwtSecret must match the secret used to sign the jwt 
app.use(gateGuard({ jwtSecret: 'shh' }))

// Routes here

Configurations

Option	Default Value	Required	Description
jwtSecret	undefined	Yes	The secret/cert that was used to sign/encode the JWT
whitelist	[]	Optional	Allow certain endpoints or endpoint groups to bypass jwt checking. Example registration, login, forgot password. Simply calls next() if req.path is whitelisted. Supports globbing patterns via picomatch.
missingTokenErrorStatus	401	Optional	HTTP status returned when the key for the jwt is missing from cookies.
missingTokenErrorMessage	'Missing token.'	Optional	Message to show when there is no cookie containing the JWT present at all.
verifyTokenErrorStatus	403	Optional	HTTP status returned when the provided JWT failed to verify.
verifyTokenErrorMessage	'Invalid jwt.'	Optional	HTTP Message returned when the provided JWT failed to verify.
cookieName	'token'	Optional	The key where the JWT can be found within the req.cookies object.
jwtVerifyOptions	{}	Optional	Pass-through for native configs of the jwt.verify method

Examples

Basic whitelist usage

app.use(gateGuard({
  jwtSecret,
  whitelist: [
    '/api/registration/verify',
    '/api/registration/create/account',
    '/api/registration/create/profile',
  ]
}));

Whitelist multiple routes with globs

Supports globbing via the picomatch library

// The same example above can be written as
app.use(gateGuard({
  jwtSecret,
  whitelist: ['/api/registration/**']
}));

// All common glob patterns supported
app.use(gateGuard({
  jwtSecret,
  whitelist: [
    '/api/*/create/account',
    '/api/**/profile/*',
  ]
}));

// Note on matching
app.use(gateGuard({
  jwtSecret,
  // This will whitelist any sub-routes of /api/registration/
  // But the base route /api/registration itself will not be whitelisted
  whitelist: ['/api/registration/**']
}));