json-web-token

JSON Web Token (JWT) encode/decode for Node. Zero runtime dependencies, timing-safe signature verification, synchronous result-object API.

Install

npm install json-web-token
# or
pnpm add json-web-token
# or
yarn add json-web-token

Quick start

import { encode, decode } from "json-web-token";        // ESM
// const { encode, decode } = require("json-web-token"); // CJS

const secret = "TOPSECRETTTTT";
const payload = { iss: "me", aud: "you", iat: Date.now() };

const { error, value: token } = encode(secret, payload);
if (error) throw error;

const { error: e2, value: decoded, header } = decode(secret, token);
if (e2) throw e2;
console.log(decoded, header);

The library is synchronous — both encode and decode return their result immediately. If you want async ergonomics, wrap them yourself:

const tokenP = Promise.resolve(encode(secret, payload));

Custom headers

const { value: token } = encode(secret, {
  payload: { iss: "me", aud: "you" },
  header: { kid: "my-key-id" },
}, "HS512");

Header keys you provide are merged with the defaults — typ and alg are always set by the library and cannot be overridden through this surface.

Locking decode to a specific algorithm

const { error, value } = decode(publicKey, token, { algorithms: ["RS256"] });

Any token whose header.alg is outside the list is rejected before any signature work happens.

API

function encode(
  key: string | Buffer,
  data: unknown,
  algorithm?: string,           // defaults to "HS256"
): EncodeResult;

function decode(
  key: string | Buffer,
  token: string,
  options?: DecodeOptions,
): DecodeResult;

interface DecodeOptions {
  algorithms?: string[];        // optional allowlist; rejects header.alg outside the list
}

function getAlgorithms(): string[];   // ["HS256","HS384","HS512","RS256"]
class    JWTError extends Error { }

EncodeResult is { error: JWTError | null; value: string | null }. DecodeResult is { error: JWTError | null; value: unknown; header?: JWTHeader }.

Security notes

• CVE-2023-48238 (algorithm confusion) is fixed. v4 refuses to verify any token whose algorithm family does not match the key handed to decode. PEM-encoded keys (anything starting with -----BEGIN) can only be paired with the asymmetric algorithms (RS*); plain secrets (string or Buffer without PEM markers) can only be paired with the HMAC algorithms (HS*). This blocks the classic RS256→HS256 swap where an attacker re-signs a token with HMAC using the server's RSA public key as the HMAC secret.
• Optional algorithm allowlist. Safety-conscious callers can pass { algorithms: ["RS256"] } (or any subset) to decode to reject any token whose header.alg is outside that list, in addition to the key-type guard above.
• Timing-safe HMAC verify — v4 compares signatures with crypto.timingSafeEqual on length-checked Buffers, removing the timing side-channel that was present in v3's string === compare.
• alg: 'none' is rejected in both encode and decode.
• Claim validation is out of scope. exp, nbf, iat, iss, aud, sub are not validated automatically. Check them in your own code on the decoded payload.

Supported algorithms

HS256, HS384, HS512, RS256.

Migrating from v3

The { error, value, [header] } return shape and getAlgorithms() / JWTError are unchanged. Callback overloads have been removed — v4 is sync-only. If you used the callback form in v3:

// v3
jwt.encode(secret, payload, (err, token) => { ... });

// v4 — just inline it
const { error, value: token } = jwt.encode(secret, payload);
if (error) { /* ... */ }

Other changes worth knowing:

| Topic | v3 | v4 | | --- | --- | --- | | Min Node | >=8 | >=18 | | Runtime deps | 4 (base64-url, is.object, json-parse-safe, xtend) | none | | Call style | callback OR result-object | result-object only | | HMAC verify | string === (timing-leaky) | crypto.timingSafeEqual | | Algorithm confusion | vulnerable (CVE-2023-48238) | fixed — key-type / alg-family guard on encode + decode | | Algorithm allowlist | none | optional algorithms in decode options | | Module formats | CJS only | ESM + CJS via exports map | | Types | hand-written index.d.ts (loose any) | TS source, generated .d.mts / .d.cts | | Base64url | base64-url package | Node native Buffer | | Build | hand-edited index.js | tsup from TS | | Test runner | mocha + nyc | vitest with v8 coverage | | Linter | standard | biome | | CI | Travis (Node 8/10/12) | GitHub Actions (Node 20/22/24) |

Size

Zero runtime dependencies. What ships in the npm tarball:

| What | Raw | Gzipped | | ------------------------------------- | -------- | -------- | | ESM runtime (index.mjs) | 4 880 B | 1 599 B | | CJS runtime (index.cjs) | 4 941 B | 1 609 B | | Types (.d.mts / .d.cts) | 5 238 B | 1 167 B | | Sourcemaps (debug-only, not loaded) | 27 610 B | 4 511 B |

Only one of the two runtime files is loaded by your bundler / Node, so the real cost in your app is ~1.6 kB gzipped.

License

ISC © @joaquimserafim