@entespotify/express-token-verifier

Beta Release - This library is currently in beta. Use with caution in production environments.

🧩 Overview

@entespotify/express-token-verifier is an Express middleware and utility library for validating JSON Web Tokens (JWTs) using JSON Web Key Sets (JWKS) with caching support.
It simplifies the process of securing your Express APIs by verifying JWTs against a trusted JWKS endpoint.

✨ Features

• 🚀 Express Middleware — Easily integrate JWT validation into your Express routes.
• 🧠 JWKS Caching — Reduces network overhead by caching JWKS responses.
• ⚙️ Customizable — Supports issuer, audience validation, and configurable cache TTL.
• 🧑‍💻 TypeScript Support — Fully typed for a great developer experience.

📦 Installation

npm install @entespotify/express-token-verifier

🧱 Usage

Middleware Example

import express from 'express';
import { createAuthMiddleware } from '@entespotify/express-token-verifier';

const app = express();

const authConfig = {
  issuer: 'https://example.com',
  jwksUri: 'https://example.com/.well-known/jwks.json',
  audience: 'your-audience',
};

const authMiddleware = createAuthMiddleware(authConfig);

app.use(authMiddleware);

app.get('/protected', (req, res) => {
  res.json({ message: 'You have access!', user: (req as any).user });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Verifying JWTs Manually

If you need to verify JWTs outside of middleware, you can use the verifyJwt function:

import { verifyJwt } from '@entespotify/express-token-verifier';

const token = 'your-jwt-token';
const config = {
  issuer: 'https://example.com',
  jwksUri: 'https://example.com/.well-known/jwks.json',
  audience: 'your-audience',
};

verifyJwt(token, config)
  .then((payload) => {
    console.log('Token payload:', payload);
  })
  .catch((err) => {
    console.error('Token verification failed:', err.message);
  });

📘 API Reference

createAuthMiddleware(config: AuthConfig)

Creates an Express middleware for JWT validation.

Parameters:

• config (AuthConfig): Configuration object for JWT validation.

Returns:
Express middleware function.

verifyJwt(token: string, config: AuthConfig)

Verifies a JWT against the provided configuration.

Parameters:

• token (string): The JWT to verify.
• config (AuthConfig): Configuration object for JWT validation.

Returns:
A promise that resolves with the decoded token payload.

JwksCache

A utility class for managing JWKS caching.

Methods:

• getKeyByKid(kid: string): Retrieves a JWK by its key ID (kid).
• refresh(): Refreshes the JWKS cache.

AuthConfig

Configuration interface for JWT validation.

⚙️ Implementation Details

• JWKS Caching: The JwksCache class fetches and caches JWKS responses to minimize network requests.
• JWT Validation: The verifyJwt function uses the jose library to validate JWTs against the cached JWKs.
• Error Handling: Middleware and utilities throw meaningful errors for invalid or expired tokens.

🧾 License

This library is licensed under the MIT License.
See the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome!
Feel free to check the issues page.

💬 Support

If you find this library helpful, please ⭐️ the repository to show support!
For questions or suggestions, open an issue or start a discussion on GitHub.