Table of Contents

• Features
• Documentation
  • Installation
  • Node.js
  • Browser
  • Contributing
    • Linting
    • Testing
• Releases
• Credits

Features

• Convenient, universal utilities for handling JWTs
• JWTs generated by node-jsonwebtoken
• Runs on Node.js v8+

Documentation

Installation

npm install tokenpress

Node.js

Configure tokenpress before using it:

const tokenpress = require('tokenpress');

tokenpress.configure({
  // Required: string or buffer containing the secret for HMAC algorithms
  secret: 'CHANGE_THIS_SECRET',
  // Required: string describing a time span zeit/ms. Eg: 60, "2 days", "10h", "7d"
  expiresIn: '30 days',
  // Optional: Minimum and maximum token lengths for getURLSafeToken utility
  minTokenLength: 30,
  maxTokenLength: 50,
});

Sign a token:

const tokenpress = require('tokenpress');

const token = tokenpress.jwt.sign({
  username: 'clever_username_ftw',
  role: 'USER',
});

Verify a token using JWKS:

const tokenpress = require('tokenpress');

tokenpress.configure({
  algorithms: ['RS256'],
  audience: 'my audience',
  issuer: `https://my-app.com/`,
  jwksUri: `https://my-app.com/jwks.json`,
});

const someToken = 'blah.blah.blah';
tokenpress.jwt.verifyWithJWKS(someToken).then((decodedJWT) => {
  console.log(decodedJWT)
});

Use tokenpress middleware to require authentication for a route:

const tokenpress = require('tokenpress');
const { requireAuth } = tokenpress.middleware;

router.get('/user/account', requireAuth, (req, res) => {
  // req.jwt contains the decoded JWT
  const { username, role } = req.jwt;

  res.json({ username, role });
});

Note: If the authentication check fails, a 401 (unauthorized) response will be sent as JSON. The response will contain an error property that will equal either EXPIRED_TOKEN or INVALID_TOKEN. INVALID_TOKEN can be caused by any of the conditions listed in the jsonwebtoken docs.

Generate a random, variable-length, hexadecimal string using the crypto.randomBytes function. The minumum length defaults to 30, and the maximum length defaults to 50.

const tokenpress = require('tokenpress');

const randomToken = tokenpress.utils.getURLSafeToken();

Browser

Optionally configure whether to use sessionStorage as opposed to localStorage for storing tokens on the client. By default, localStorage will be used.

import tokenpress from 'tokenpress/browser';

tokenpress.configure({
  useSessionStorage: true,
});

Optionally configure the key used when saving to localStorage or sessionStorage. Defaults to token.

import tokenpress from 'tokenpress/browser';

tokenpress.configure({
  storageKey: 'custom-token-name',
});

Save a token to localStorage/sessionStorage:

import tokenpress from 'tokenpress/browser';

mockFunctionToGetTokenFromServer().then((token) => {
  tokenpress.save(token)
});

Retrieve a token from localStorage/sessionStorage:

import tokenpress from 'tokenpress/browser';

const token = tokenpress.get();

Delete a token from localStorage/sessionStorage:

import tokenpress from 'tokenpress/browser';

tokenpress.delete();

Determine if a token is expired:

import tokenpress from 'tokenpress/browser';

// Will fetch token from localStorage/sessionStorage by default
const isTokenExpired = tokenpress.isExpired();
console.log(isTokenExpired); // true or false

// Or, check a token you've previously retrieved
const token = tokenpress.get();
const isMyOtherTokenExpired = tokenpress.isExpired(token);
console.log(isMyOtherTokenExpired); // true or false

Contributing

Linting

Run ESLint with npm run lint.

Testing

Run unit tests with npm test.

Credits