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/**']
}));