# jsonwebtoken — JSON Web Token Implementation for Node.js

> The standard library for signing, verifying, and decoding JWTs in Node.js applications, used by Auth0 and thousands of production APIs.

## Install

Save in your project root:

# jsonwebtoken — JSON Web Token Implementation for Node.js

## Quick Use
```bash
npm install jsonwebtoken
```
```js
const jwt = require('jsonwebtoken');
const token = jwt.sign({ userId: 42 }, 'secret', { expiresIn: '1h' });
const decoded = jwt.verify(token, 'secret');
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-8db5897e
Author: AI Open Source