Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@futurestudio/hapi-jwt

Package Overview
Dependencies
Maintainers
4
Versions
4
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@futurestudio/hapi-jwt

hapi plugin to sign, decode, and invalidate/blacklist JWTs

  • 2.1.1
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
2
Maintainers
4
Weekly downloads
 
Created
Source
hapi-jwt logo

Seamless JWT signing, decoding, and blacklisting in your hapi app.


Installation · Plugin Options · Usage



Build Status hapi-jwt Version

Follow @marcuspoehls for updates!


The Future Studio University supports development of this hapi plugin 🚀
Join the Future Studio University and Skyrocket in Node.js


Introduction

hapi-jwt is a hapi plugin to create (sign) and access (decode) JSON web tokens (JWT).

Create a token via request.jwt.for(user) and retrieve the payload of an existing token via request.jwt.payload()

Requirements

This plugin requires Node.js v12 or newer.

Compatibility

Major Releasehapi.js versionNode.js version
v2>=18 hapi>=12
v1>=18 hapi>=8

Installation

Install hapi-jwt as a dependency to your project:

npm i @futurestudio/hapi-jwt

Register the Plugin

Register hapi-jwt as a plugin to your hapi server.

await server.register({
  plugin: require('@futurestudio/hapi-jwt'),
  options: {
    secret: 'your-secret' // this is the minimum required configuration to sign/decode JWTs
  }
})

// went smooth like hot chocolate :)

Plugin Options

This plugin ships with a comprehensive default configuration. Please have a look at all available keys and related comments.

The following list outlines all options:

  • secret: (string) the secret key used to sign and decode a JWT (with a symmetric algorithm). The secret is required if you don’t use a keypair provided in keys
  • keys: (object) describing a key pair when using asymmetric algorithms
    • public: (string) the path to the public key. The public key must be in PEM format
    • private: (string) the path to the private key. The private key can be in PEM format, OpenSSH format works as well.
  • algorithm: (string, default: HS256) the JWT signing algorithm
  • ttl: (number, default: 15) the JWT lifetime in minutes
  • blacklist: (object) configurating the blacklist
    • enabled: (boolean, default: false) enables the blacklist
    • cache: (object) configures a hapi cache instance for the JWT blacklist. These options are used to create a cache via server.cache
      • name: (string) identifies both, the blacklisting cache name and segment
      • provider: (string) defines the catbox caching client, like @hapi/catbox-redis

Usage

hapi-jwt decorates hapi’s request object with a JWT instance: request.jwt.

Request Decorations

This decoration provides a convenient interface to interact with JWTs:

  • await request.jwt.for(user): creates a signed JWT
  • await request.jwt.payload(): returns the decoded JWT payload. This expects a valid JWT as a bearer token in the authorization header.
  • await request.jwt.invalidate(): decodes the JWT on the request (see payload method) and adds it to to the blacklist
  • await request.jwt.invalidate('forever'): blacklists a JWT indefinitely

Create a JWT

Creating a (signed) JWT is as simple as await request.jwt.for({ id: 1, name: 'Marcus' }):

When creating the JWT, hapi-jwt creates a handful of claims besides your provided data. It generates the following claims:

  • jti: a token identifier
  • iat: issued at date in seconds
  • nbf: validity start date in seconds
  • exp: expiration date in seconds, based on the TTL
  • iss: retrieves the token issuer from the request domain
  • sub: if the given user object contains an id field, it will be used for the sub claim
server.route({
  method: 'POST',
  path: '/login',
  options: {
    auth: 'basic', // assume the login route requires basic authentication
    handler: async request => {
      const token = await request.jwt.for(request.auth.credentials)

      return token
    }
  }
})

You can debug a created JWT on jwt.io and have a look at the token headers and payload.

A sample token payload looks like this:

{
  jti: 'babf5099a4561173c91f2cdc6c61c1aa',
  iss: 'http://localhost',
  iat: 1574094111,
  nbf: 1574094111,
  exp: 1574095011,
  sub: 1
}

Decode a JWT and access the payload

You can access the JWT payload via await request.jwt.payload(). Accessing the payload expects a valid JWT in the authorization request header. The authorization header must be in a format like Bearer <your-jwt>.

Calling request.jwt.payload() returns a Payload instance containing the JWT claims set:

server.route({
  method: 'GET',
  path: '/me',
  options: {
    auth: 'jwt',
    handler: async request => {
      const payload = await request.jwt.payload()

      const user = payload.has('sub')
        ? await User.findbyId(payload.get('sub'))
        : await User.findOne({ email: payload.get('email') })

      return user
    }
  }
})
Payload

A payload instance returned from await request.jwt.payload() has the following methods:

  • toObject: returns a plain JavaScript object
  • get(key): returns the value identified by key
  • has(key): returns a boolean, true if the payload contains the claim identified by key, otherwise false
  • missing(key): returns a boolean, true if the payload does not contain the claim identified by key, otherwise false

JWT Blacklist

Activating the JWT blacklist requires a cache. hapi-jwt uses hapi’s server.cache method to provision a blacklist storage.

When using the blacklist, please ensure a persistent caching store, like Redis via @hapi/catbox-redis or Memcached via @hapi/catbox-memcached. Using hapi’s default internal caching instance stores the blacklist in-memory and will be gone when restarting the server.

Contributing

  1. Create a fork
  2. Create your feature branch: git checkout -b my-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request 🚀

License

MIT © Future Studio


futurestud.io  ·  GitHub @futurestudio  ·  Twitter @futurestud_io

Keywords

FAQs

Package last updated on 20 Apr 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc