passport-jwt

passport-jwt is a strategy module for Passport, the widely-used Node.js authentication middleware, that lets applications authenticate HTTP requests using JSON Web Tokens instead of cookies or sessions. It parses a JWT out of an incoming request via a pluggable extractor function, verifies its signature and claims (issuer, audience, algorithms, expiration) using the jsonwebtoken library, and hands the decoded payload to a user-supplied verify callback that resolves the associated user record.

Because it plugs directly into Passport’s strategy interface, teams already using Passport for other authentication schemes (local, OAuth, etc.) can add stateless, token-based auth to specific routes with minimal additional code, making it a common choice for securing RESTful APIs consumed by single-page apps and mobile clients.

What You Get

• A JwtStrategy class that plugs into any existing Passport.js authentication setup
• A library of built-in token extractors (header, bearer auth header, body field, URL query parameter, or a custom composed extractor chain)
• Signature and claim verification (issuer, audience, algorithms, expiration) delegated to the battle-tested jsonwebtoken library
• Support for both static secrets/keys and dynamic secretOrKeyProvider callbacks for per-request key resolution
• An option to pass the full request into the verify callback for request-aware user lookups

Common Use Cases

• Securing RESTful API endpoints consumed by single-page applications or mobile clients without maintaining server-side sessions
• Adding stateless bearer-token authentication alongside existing Passport strategies like passport-local or OAuth providers
• Verifying tokens issued by a separate auth service or identity provider before allowing access to protected routes
• Supporting key rotation scenarios via secretOrKeyProvider, where the verification key depends on the token or request

Under The Hood

Architecture: passport-jwt is a thin adapter layer over two dependencies: passport-strategy (for the Strategy base class and pass/fail/error request lifecycle) and jsonwebtoken (for actual signature/claims verification). lib/strategy.js defines JwtStrategy, whose authenticate() method pulls a raw token string from the request via a caller-supplied jwtFromRequest function, resolves a secret/key via secretOrKeyProvider (a normalized wrapper around the simpler secretOrKey option), and delegates cryptographic verification to JwtStrategy.JwtVerifier (lib/verify_jwt.js, itself a wrapper around jsonwebtoken.verify). On success the decoded payload is handed to the user’s verify callback, whose done(err, user, info) result drives Passport’s success/fail/error branching. Tech Stack: Plain CommonJS JavaScript with no build step; runtime dependencies are just jsonwebtoken and passport-strategy, and dev dependencies (mocha, chai, chai-passport-strategy, sinon, nyc) support a classic Mocha/Chai unit-test suite with coverage reporting. Code Quality: The test/ directory has one spec file per concern (initialization, request extraction, validation, verify-callback behavior) with mocked requests (mock_request.js) and fixture data (testdata.js), giving reasonably thorough coverage of the strategy’s branching logic; the production code itself is small (a few hundred lines across strategy.js, extract_jwt.js, auth_header.js, verify_jwt.js) and uses util.inherits-style prototypal inheritance rather than ES6 classes, reflecting its 2014-era origins. API Design: The public surface is deliberately minimal — a Strategy constructor plus an ExtractJwt namespace of extractor factories — and the extractor-function convention (any (req) => token|null function is valid) makes it trivial to compose custom token sources (e.g. cookies) without modifying the library, keeping the integration surface small for consumers already familiar with Passport’s strategy pattern.