jsonwebtoken

jsonwebtoken is the most widely used Node.js implementation of the JSON Web Token (JWT) standard (RFC 7519), providing simple sign, verify, and decode functions for issuing and validating tokens. It supports HMAC (HS256/384/512), RSA (RS256/384/512), RSA-PSS (PS256/384/512), and ECDSA (ES256/384/512) algorithms, plus claim validation for expiration, audience, issuer, subject, and not-before.

Maintained by Auth0 and used across countless authentication and API-authorization flows, the library exposes both synchronous and callback-based asynchronous APIs, ships built-in protections against algorithm-confusion attacks, and keeps its dependency surface to a handful of small, focused helper packages.

What You Get

• jwt.sign() for creating tokens synchronously or via callback, with support for HMAC, RSA, RSA-PSS, and ECDSA algorithms
• jwt.verify() for validating signature, expiration (exp), not-before (nbf), audience, issuer, subject, and JWT ID claims in one call
• jwt.decode() for reading a token’s payload/header without verifying its signature
• Built-in algorithm allowlisting to guard against algorithm-confusion/downgrade attacks
• Typed error classes (JsonWebTokenError, TokenExpiredError, NotBeforeError) for precise failure handling

Common Use Cases

• Issuing session tokens for stateless API authentication
• Signing and verifying access/refresh tokens in an OAuth2 or OpenID Connect flow
• Generating short-lived tokens for password-reset or email-verification links
• Validating service-to-service tokens signed with RSA/ECDSA key pairs

Under The Hood

Architecture — The package is a thin, function-oriented wrapper rather than a class hierarchy: sign.js (253 lines), verify.js (263 lines), and decode.js (30 lines) sit at the repo root as the three public entry points, each importing shared validators from lib/ (validateAsymmetricKey.js, timespan.js, psSupported.js) and three typed error classes (JsonWebTokenError, NotBeforeError, TokenExpiredError). index.js simply re-exports these five symbols, so the whole module surface is deliberately small and traceable end-to-end from a single file per operation.

Tech Stack — Pure JavaScript (CommonJS, no TypeScript source) targeting Node >=12. Runtime dependencies are minimal and split into single-purpose micro-packages (lodash.includes, lodash.isboolean, lodash.isinteger, lodash.isnumber, lodash.isplainobject, lodash.isstring, lodash.once instead of full lodash), plus jws for the underlying signature format, ms for human-readable time spans, and semver for internal version checks. Node’s built-in crypto module (KeyObject, createSecretKey, createPrivateKey) is used directly for key handling rather than a third-party crypto wrapper.

Code Quality — The project enforces strict coverage via nyc (95% lines/statements/branches, 100% functions) and ships 34 test files under test/ covering claim-by-claim behavior (claim-aud, claim-exp, claim-iat, claim-iss, claim-jti, claim-nbf, plus dedicated encoding, decoding, and async-sign suites) using mocha, chai, and sinon. ESLint and Husky pre-commit hooks are configured, and semantic-release/commitlint enforce conventional commits, indicating a mature, process-driven maintenance workflow for a small codebase.

API Design — The public API is deliberately minimal: three top-level functions (sign, verify, decode) each accepting a plain options object, with every function usable either synchronously (return value or thrown error) or asynchronously (Node-style callback). Options schemas (sign_options_schema, registered_claims_schema) are validated defensively with descriptive error messages before any cryptographic work happens, and verify() requires an explicit algorithms allowlist — a deliberate ergonomic trade-off that adds one required option in exchange for closing a well-known JWT vulnerability class.