jsonwebtoken — JSON Web Token Implementation for Node.js

Introduction

jsonwebtoken is the reference JWT library for Node.js, implementing RFC 7519 for creating and validating tokens. It handles HMAC and RSA/ECDSA signing out of the box and is the backbone of stateless authentication in Express, Fastify, and NestJS applications.

What jsonwebtoken Does

• Signs payloads into compact JWT strings using HS256, RS256, ES256, and other algorithms
• Verifies token signatures and expiration, returning the decoded payload or throwing specific errors
• Supports asymmetric keys (RSA, EC, Ed25519) for distributed verification without sharing secrets
• Allows custom claims, audience, issuer, and subject validation
• Provides a synchronous and callback-based API for flexibility

Architecture Overview

The library splits into three phases: header construction, payload serialization, and signature computation. It base64url-encodes the header and payload, concatenates them with a dot separator, then signs using Node.js's crypto module. Verification reverses the process: it splits the token, re-computes the signature, and performs timing-safe comparison before validating claims like exp, nbf, aud, and iss.

Self-Hosting & Configuration

• Install via npm with zero native dependencies
• Pass secrets as strings or Buffers; asymmetric keys as PEM strings or KeyObjects
• Set expiresIn as a human-readable string ('2h', '7d') or numeric seconds
• Use algorithms option in verify to restrict accepted signing methods and prevent algorithm confusion attacks
• Combine with Express middleware or Passport.js for route-level authentication

Key Features

• Full RFC 7519 compliance with support for all standard registered claims
• Algorithm allowlist in verify prevents none-algorithm and confusion attacks
• Over 18,000 GitHub stars and 50 million weekly npm downloads
• Synchronous API for simple scripts, callback API for async flows
• Maintained by Auth0 with regular security patches

Comparison with Similar Tools

• jose — modern, Web Crypto-based, supports JWE and JWK; jsonwebtoken is simpler and Node-only
• passport-jwt — a Passport strategy that wraps jsonwebtoken for Express integration
• fast-jwt — faster verification via caching; jsonwebtoken is more broadly tested and adopted
• express-jwt — middleware layer on top of jsonwebtoken for automatic token extraction
• Auth.js — full authentication framework; jsonwebtoken is a low-level primitive for custom flows

FAQ

Q: Is HS256 safe for production? A: Yes, if the secret is long (32+ bytes) and kept confidential. For microservices where verifiers should not hold the signing key, use RS256 or ES256 instead.

Q: How do I handle token expiration gracefully? A: Catch the TokenExpiredError from jwt.verify() and issue a refresh flow. The error includes the decoded payload via the expiredAt property.

Q: Can I store JWTs in cookies? A: Yes. Use HttpOnly, Secure, SameSite=Strict cookies to prevent XSS and CSRF when using JWTs for session management.

Q: Does it support Ed25519? A: Yes, via the EdDSA algorithm option when using Node.js 16+ with Ed25519 key pairs.

Sources

• https://github.com/auth0/node-jsonwebtoken
• https://jwt.io/