A fast, lightweight Node.js JWT library for generating, verifying, and managing JSON Web Tokens (JWTs). Supports authentication and token-based authorization for APIs built with Express, Fastify, Koa, Hapi, NestJS, and Next.js. Ideal for securing web applications, handling user authentication, and implementing role-based access control (RBAC).

---

JWT Utils is a fast, lightweight, and framework-agnostic Node.js library for generating, verifying, and managing JSON Web Tokens (JWTs). It simplifies authentication and token-based authorization for web applications and APIs.

🚀 Features

• ✅ Generate JWTs – Create signed JWTs with custom payloads and expiration times.
• ✅ Verify JWTs – Securely decode and verify tokens.
• ✅ Access & Refresh Tokens – Implement authentication with refresh token support.
• ✅ Framework-Agnostic Middleware – Works with Express, Fastify, Koa, Hapi, NestJS, and Next.js.
• ✅ RBAC Middleware – Control access based on user roles.
• ✅ TypeScript Support – Fully typed for safer development.
• ✅ Lightweight & Secure – Uses jsonwebtoken with best security practices.
• ✅ Generate and verify JWTs easily
• ✅ Support for Fastify, Koa, and Express middleware
• ✅ Framework-agnostic core utilities
• ✅ Lightweight and dependency-free
• ✅ Built-in security best practices

---

📦 Installation

1npm install @the-node-forge/jwt-utils

or

1yarn add @the-node-forge/jwt-utils

---

🔧 Usage

Generating Access & Refresh Tokens

1⃣ Generate a Token (no options)

1import { generateTokens } from '@the-node-forge/jwt-utils';
2
3const accessSecret = 'your-access-secret';
4const refreshSecret = 'your-refresh-secret';
5
6const { accessToken, refreshToken } = generateTokens(
7  { id: 'user123', role: 'admin' },
8  accessSecret,
9  refreshSecret,
10);
11console.log('Access Token:', accessToken);
12console.log('Refresh Token:', refreshToken);
13const token = generateTokens({ id: 'user123', role: 'admin' });
14
15console.log(token);

** Generate a Token (custom options)**

1const { accessToken, refreshToken } = generateTokens(
2  { id: 'user123', role: 'admin' },
3  accessSecret,
4  refreshSecret,
5  {
6    accessExpiresIn: '1h', // Custom access token expiry
7    refreshExpiresIn: '7d', // Custom refresh token expiry
8    algorithm: 'HS512', // Stronger algorithm
9    audience: 'my-app',
10    issuer: 'my-auth-service',
11  },
12);
13
14console.log('Access Token:', accessToken);
15console.log('Refresh Token:', refreshToken);

Verifying Tokens

2⃣ Verify a Token

1import { verifyToken, verifyRefreshToken } from '@the-node-forge/jwt-utils';
2
3// no options
4const decodedAccess = verifyToken(accessToken, accessSecret);
5const decodedRefresh = verifyRefreshToken(refreshToken, refreshSecret);
6
7// custom options
8const decodedAccess = verifyToken(accessToken, accessSecret, {
9  audience: 'my-app',
10  issuer: 'auth-service',
11});
12
13const decodedRefresh = verifyRefreshToken(refreshToken, refreshSecret, {
14  audience: 'my-app',
15  issuer: 'auth-service',
16});
17
18console.log('Decoded Access Token:', decodedAccess);
19console.log('Decoded Refresh Token:', decodedRefresh);

Verifying a Refresh Token

1import { verifyRefreshToken } from '@the-node-forge/jwt-utils';
2
3const refreshToken = 'your_refresh_jwt_token_here';
4const refreshSecret = 'your-refresh-secret';
5
6// no options
7const decoded = verifyRefreshToken(refreshToken, refreshSecret);
8
9// custom options
10const decoded = verifyRefreshToken(refreshToken, refreshSecret, {
11  audience: 'my-app',
12  issuer: 'auth-service',
13});
14
15if (decoded) {
16  console.log('Refresh token is valid:', decoded);
17} else {
18  console.log('Invalid or expired refresh token');
19}

---

🚀 Integration with Web Frameworks

Express Middleware

1import express from 'express';
2import {
3  authenticateToken,
4  authenticateRefreshToken,
5} from '@the-node-forge/jwt-utils/middleware/express';
6
7const app = express();
8app.use(express.json());
9
10const ACCESS_SECRET = 'your-access-secret';
11const REFRESH_SECRET = 'your-refresh-secret';
12
13const user = {
14  id: '123',
15  role: 'admin',
16};
17
18// Generate tokens
19app.post('/login', (req, res) => {
20  const tokens = generateTokens(user, ACCESS_SECRET, REFRESH_SECRET);
21  res.json(tokens);
22});
23
24// Protected route
25app.get('/protected', authenticateToken(ACCESS_SECRET), (req, res) => {
26  res.json({ message: 'Access granted', user: req.user });
27});
28
29// Refresh token route
30app.post('/refresh', authenticateRefreshToken(REFRESH_SECRET), (req, res) => {
31  const { exp, iat, ...userData } = req.user; // token returns exp, iat, id and role. You only want to pass in the users data for a refresh token
32
33  const newTokens = generateTokens(userData, ACCESS_SECRET, REFRESH_SECRET);
34  res.json(newTokens);
35});

Fastify Middleware

1import Fastify from 'fastify';
2import {
3  authenticateToken,
4  authenticateRefreshToken,
5} from '@the-node-forge/jwt-utils/middleware/fastify';
6import { generateTokens } from '@the-node-forge/jwt-utils';
7
8const app = Fastify();
9
10const ACCESS_SECRET = 'your-access-secret';
11const REFRESH_SECRET = 'your-refresh-secret';
12
13const user = {
14  id: '123',
15  role: 'admin',
16};
17
18// Generate tokens
19app.post('/login', async (req, reply) => {
20  const tokens = generateTokens(user, ACCESS_SECRET, REFRESH_SECRET);
21  reply.send(tokens);
22});
23
24// Protected route
25app.get(
26  '/protected',
27  { preHandler: authenticateToken(ACCESS_SECRET) },
28  async (req, reply) => {
29    reply.send({ message: 'Access granted', user: req.user });
30  },
31);
32
33// Refresh token route
34app.post(
35  '/refresh',
36  { preHandler: authenticateRefreshToken(REFRESH_SECRET) },
37  async (req, reply) => {
38    const { exp, iat, ...userData } = req.user; // Strip exp & iat before regenerating tokens
39
40    const newTokens = generateTokens(userData, ACCESS_SECRET, REFRESH_SECRET);
41    reply.send(newTokens);
42  },
43);

Koa Middleware

1import Koa from 'koa';
2import Router from '@koa/router';
3import bodyParser from 'koa-bodyparser';
4import {
5  authenticateToken,
6  authenticateRefreshToken,
7} from '@the-node-forge/jwt-utils/middleware/koa';
8import { generateTokens } from '@the-node-forge/jwt-utils';
9
10const app = new Koa();
11const router = new Router();
12
13const ACCESS_SECRET = 'your-access-secret';
14const REFRESH_SECRET = 'your-refresh-secret';
15
16const user = {
17  id: '123',
18  role: 'admin',
19};
20
21app.use(bodyParser()); // Parse JSON body
22
23// Generate tokens
24router.post('/login', async (ctx) => {
25  const tokens = generateTokens(user, ACCESS_SECRET, REFRESH_SECRET);
26  ctx.body = tokens;
27});
28
29// Protected route
30router.get('/protected', authenticateToken(ACCESS_SECRET), async (ctx) => {
31  ctx.body = { message: 'Access granted', user: ctx.state.user };
32});
33
34// Refresh token route
35router.post('/refresh', authenticateRefreshToken(REFRESH_SECRET), async (ctx) => {
36  const { exp, iat, ...userData } = ctx.state.user; // Strip exp & iat before regenerating tokens
37
38  const newTokens = generateTokens(userData, ACCESS_SECRET, REFRESH_SECRET);
39  ctx.body = newTokens;
40});

Hapi Middleware

1import Hapi from '@hapi/hapi';
2import {
3  authenticateToken,
4  authenticateRefreshToken,
5} from '@the-node-forge/jwt-utils/middleware/hapi';
6import { generateTokens } from '@the-node-forge/jwt-utils';
7
8const server = Hapi.server({
9  port: 3000,
10  host: 'localhost',
11});
12
13const ACCESS_SECRET = 'your-access-secret';
14const REFRESH_SECRET = 'your-refresh-secret';
15
16const user = {
17  id: '123',
18  role: 'admin',
19};
20
21// Generate tokens
22server.route({
23  method: 'POST',
24  path: '/login',
25  handler: (request, h) => {
26    const tokens = generateTokens(user, ACCESS_SECRET, REFRESH_SECRET);
27    return h.response(tokens).code(200);
28  },
29});
30
31// Protected route
32server.route({
33  method: 'GET',
34  path: '/protected',
35  options: { pre: [{ method: authenticateToken(ACCESS_SECRET) }] },
36  handler: (request, h) => {
37    return h.response({ message: 'Access granted', user: request.app.user });
38  },
39});
40
41// Refresh token route
42server.route({
43  method: 'POST',
44  path: '/refresh',
45  options: { pre: [{ method: authenticateRefreshToken(REFRESH_SECRET) }] },
46  handler: (request, h) => {
47    const { exp, iat, ...userData } = request.app.user; // Strip exp & iat before regenerating tokens
48
49    const newTokens = generateTokens(userData, ACCESS_SECRET, REFRESH_SECRET);
50    return h.response(newTokens).code(200);
51  },
52});
53
54// Start server
55const start = async () => {
56  await server.start();
57  console.log('Server running on http://localhost:3000');
58};
59
60start();

---

🛡 Role-Based Access Control (RBAC) using express

1import express from 'express';
2import { authenticateToken } from '@the-node-forge/jwt-utils/middleware/express';
3import { authorizeRoles } from '@the-node-forge/jwt-utils/middleware/rbac';
4
5const app = express();
6const ACCESS_SECRET = 'your-access-secret';
7
8// Admin route (requires authentication + admin role)
9app.get(
10  '/admin',
11  authenticateToken(ACCESS_SECRET), // Ensure user is authenticated
12  authorizeRoles('admin'), // Ensure user has the 'admin' role
13  (req, res) => {
14    res.json({ message: 'Welcome Admin', user: req.user });
15  },
16);

---

🔒 Security Best Practices

• Always use secure, long, randomly generated secret keys in production.
• Store tokens in HTTP-only cookies instead of local storage when possible.
• Implement refresh tokens for long-term authentication.

---

🌍 License

This project is licensed under the MIT License.

---

🤝 Contributing

Want to suggest a feature? Open an issue or contribute!

We welcome contributions!

1. Fork the repository
2. Create a feature branch (git checkout -b feature-name)
3. Commit your changes (git commit -m 'Add feature')
4. Push to the branch (git push origin feature-name)
5. Open a pull request

---

🌟 Support & Links

• NPM Package: @the-node-forge/jwt-utils
• GitHub Repo: The Node Forge / JWT Utils
• Issues & Feature Requests: Open an Issue