npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

purejwt

v0.1.9

Published

PureJWT is a lightweight, standalone library for JSON Web Token (JWT) creation, verification, and manipulation. Designed with ease-of-use and security in mind, it removes reliance on third-party libraries, granting developers increased control and transpa

Downloads

20

Readme

PureJWT

PureJWT is a featherweight and independent library designed to facilitate the creation and verification of JSON Web Tokens (JWT). Removing any reliance on third-party libraries, it ensures simplicity, security, and provides complete control over JWT operations.

From key generation to token signature verification, PureJWT encompasses it all in a simple, straightforward manner. The library allows for the use of both symmetric (HMAC) and asymmetric (RSA, RSA-PSS, ECDSA) cryptographic algorithms.

Installation

Install PureJWT using npm:

npm install --save purejwt

Features

  • Supports for a wide range of algorithms. Including:

| Algorithm | Description | | --------- | -------------------- | | HS256 | HMAC with SHA-256 | | HS384 | HMAC with SHA-384 | | HS512 | HMAC with SHA-512 | | RS256 | RSA with SHA-256 | | RS384 | RSA with SHA-384 | | RS512 | RSA with SHA-512 | | ES256 | ECDSA with SHA-256 | | ES384 | ECDSA with SHA-384 | | ES512 | ECDSA with SHA-512 | | PS256 | RSA-PSS with SHA-256 | | PS384 | RSA-PSS with SHA-384 | | PS512 | RSA-PSS with SHA-512 |

  • Facilitates generation of a secret for HMAC algorithms.
  • Generates public and private keys for RSA, RSA-PSS, and ECDSA algorithms.
  • Encoding, decoding, signing, and verification of JWTs.
  • Automatic algorithm detection based on the provided keys.
  • Control over token expiration.
  • Flexibility in setting allowed issuers and audiences for token verification.
  • A custom error type, PureJWT.PureJWTError, for precise error handling.

Quick Start Guide

Begin by importing PureJWT:

const PureJWT = require("purejwt");

Create a secure secret for HMAC algorithms:

console.log(`SECRET="${PureJWT.generateSecret()}"`);

Use this secret to instantiate PureJWT:

const jwt = new PureJWT({
  secret: process.env.SECRET,
});

Generate and store private/public keys as secure environment variables. Use these keys to initialize PureJWT without needing to specify the algorithm (except for PS256, PS384, or PS512).

const jwt = new PureJWT({
  privateKey: process.env.PRIVATE_KEY,
  publicKey: process.env.PUBLIC_KEY,
});

During initialization, you can specify options such as token lifespan, and allowed issuers and audiences. These settings influence which tokens are accepted by PureJWT during verification.

const jwt = new PureJWT({
  secret: process.env.SECRET,
  algorithm: "HS384", // Default algorithm is HS256.
  durationInMinutes: 7 * 24 * 60, // Default token lifespan is 24 hours
  allowedIssuers: "securetoken.hostluxe.com", // Can also be an array of strings
  allowedAudiences: [
    "microservice.hostluxe.com",
    "premiumservice.hostluxe.com",
  ], // Can also be a string
});

Create a JWT token:

const payload = {
  sub: "1234567890", // 'Subject' - Traditionally it's the UserID
  role: "admin",
  exp: Date.now() + 1000 * 60 * 15, // Expiration 15 minutes
};
const token = jwt.createToken(payload);

Verify a JWT token:

try {
  const payload = jwt.verifyToken(token);
} catch (PureJWTError) {
  res.status(PureJWTError.statusCode).json({ message: PureJWTError.message });
}

For more detailed information on usage, please refer to the detailed API Reference section.

Key Creation

Use PureJWT to generate public/private keys in PEM format once during development. Store these keys as strings in your secure environment variables.

const { privateKey, publicKey } = PureJWT.generatePublicPrivateKeys("ec", {
  namedCurve: "prime256v1",
});
console.log(`PRIVATE_KEY="${privateKey}"`);
console.log(`PUBLIC_KEY="${publicKey}"`);

Verifying Third-Party Tokens

If your requirement is limited to verifying tokens created by a third-party service using their public key, you can instantiate PureJWT without providing a privateKey. However, it's important to note that in this configuration, you won't have the capability to generate tokens yourself. Here's an example of how you can instantiate PureJWT with only the publicKey:

const jwt = new PureJWT({
  publicKey: process.env.THIRD_PARTY_PUBLIC_KEY,
});

With this setup, you can securely verify tokens using the provided publicKey but won't have the ability to create new tokens within your application.

API Reference

  • PureJWT.generateSecret(): Creates a secure secret for HMAC algorithms.
  • PureJWT.generatePublicPrivateKeys(algorithm, options, singleLine): Produces private and public keys for RSA, RSA-PSS, and ECDSA algorithms. The boolean singleLine replaces newline characters allowing the key String to fit in a JSON file.
    • With the 'rsa' algorithm, options.modulusLength values of 2048, 3072, and 4096 match 256, 384, and 512 bit lengths respectively.
    • With the 'ec' algorithm, options.namedCurve values of 'prime256v1', 'secp384r1', and 'secp521r1' match ES256, ES384, and ES512 respectively.
  • PureJWT.extractJwtFromBearer(tokenWithPrefix): Retrieves the JWT token from a bearer, basic, jwt, or digest authentication scheme.
  • PureJWTError: A unique error class featuring a message and statusCode.

Example

Here's an example of PureJWT being used in an Express app:

const express = require("express");
const cookieParser = require("cookie-parser");
require("dotenv").config(); // Install with npm install --save dotenv

const app = express();

const jwt = new PureJWT({ secret: process.env.SECRET });
const sevenWeeksInMs = 7 * 24 * 60 * 60 * 1000;

// Login route to create a token
app.post("/login", (req, res) => {
  // Perform authentication logic, validate credentials, etc.
  // Assuming successful authentication, create a token
  const exp = Date.now() + sevenWeeksInMs;
  const access_token = jwt.createToken({ sub: "your_user_id", exp });

  res.json({
    access_token,
    token_type: "Bearer",
    expires_in: exp,
  });
});

app.get("/api/orders", async (req, res) => {
  try {
    const token = PureJWT.extractJwtFromBearer(req.headers.authorization);

    req.payload = jwt.verifyToken(token);

    const userID = req.payload.sub;

    // Fetch and verify user
    const user = await db.users.find(user => user.id === userID);

    if (user) {
      res.json({
        orderHistory: [
          /**...**/
        ],
      });
    } else {
      res.status(404).json({ message: "User not found." });
    }
  } catch (err) {
    return res.status(err.statusCode || 500).json({ message: err.message });
  }
});

Contributing

Contributions are always welcome! Please review the Contributing guidelines.

Disclaimer

This library, herein referred to as "this Software", is provided "as is", without any warranty of any kind, expressed or implied. The author(s) and maintainer(s) of this Software do not provide any guarantee as to its functionality, correctness, or suitability for any specific purpose.

Users of this Software are solely responsible for determining the appropriateness of its use, and assume all risks associated with its use, including but not limited to the risks of program errors, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

The author(s) and maintainer(s) of this Software will not be liable for any direct, indirect, consequential, incidental, special, punitive or other damages whatsoever, including without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss, arising out of the use or inability to use this Software, even if advised of the possibility of such damages.

By using this Software, you acknowledge and agree to this disclaimer and assume full responsibility for all risk associated with the use of this Software.

License

MIT License