fastify-jwt-simple - A simple JWT manager

A simple JWT manager with automatic access and refresh token support (over cookies too)

Features

• ✅ Automatic management of access and refresh tokens.
• 🔒 Secure cookie support for token storage.
• ⚙️ Configurable token expiration and paths.
• 🚫 Built-in support for banning tokens.
• 🤝 Easy integration with Fastify.

Installation

Install the plugin using your package manager:

npm install fastify-jwt-simple

Usage

Registering the Plugin

To use the plugin, register it with your Fastify instance. You need to provide a secret and an authUser function to handle user authentication.

import Fastify from 'fastify';
import plugin from 'fastify-jwt-simple';

const app = Fastify();

await app.register(plugin, {
    secret: 'your-secret-key',
    authUser: async (request) => {
        const { user, pass } = request.body;
        if (user === 'test' && pass === 'test') {
            return { id: '123' }; // Return user data
        }
        throw new Error('Invalid credentials');
    }
});

Routes

The plugin automatically registers the following routes:

• /auth/token: Obtain an access token.
• /auth/refresh: Refresh an access token using a refresh token.
• /auth/logout: Logout and ban the current tokens.

Example

Here is an example of how to use the plugin:

import Fastify from 'fastify';
import plugin from 'fastify-jwt-simple';

const app = Fastify();

await app.register(plugin, {
    secret: 'mysecret',
    authUser: async (request) => {
        const { user, pass } = request.body;
        if (user === 'test' && pass === 'test') {
            return { id: '123' };
        }
        throw new Error('Invalid credentials');
    }
});

app.get('/', async () => {
    return { message: 'Hello, world!' };
});

await app.listen({ port: 3000 });

Testing

You can find usage examples in the tests directory. Below are some key scenarios covered:

• Login and Token Retrieval: See test/020-login.test.ts.
• Token Refresh: See test/030-access.test.ts.
• Logout: See test/040-logout.test.ts.
• Plugin Loading: See test/010-load.test.ts.

Configuration Options

The plugin accepts following options:

• secret: The secret key used for signing tokens (Required).
• authUser: A function to authenticate users (not required but default is deny access to all restricted endproints).
• path: Customizable paths for token, refresh, and logout routes.
• expiration: Token expiration times (in seconds).
• cookieConfig: Configuration for secure cookies.
• isRestricted: A function to filter which endpoints are protected or not (by default, all endproints are protected excluding the login page path.token and refresh page path.refreshToken)

Default Configuration

{
    path: {
        token: '/auth/token',
        refreshToken: '/auth/refresh',
        logout: '/auth/logout'
    },
    expiration: {
        token: 1200, // 20 minutes
        refreshToken: 604800 // 7 days
    },
    cookieConfig: {
        name: 'jwtToken'
    },
    isRestricted: async () => true,
    authUser: () => Promise.reject(...)
}

This plugin extends @fastify/jwt so all other configurations will be passed to this plugin too.

This plugin automatically loads these other plugins

• @fastify/jwt
• @fastify/cookie
• @fastify/sensible

Avoid to manually register these plugins.

TypeScript Support

fastify-jwt-simple is written in Typescript and so is fully typed and works seamlessly with TypeScript.

Links

• Report Bugs: GitHub Issues
• Feature Requests: GitHub Issues
• Help and Support: GitHub Discussions
• Contributing: Contributing Guidelines

Contributing

We welcome contributions!

Author

Emiliano Bruni

License

This project is licensed under the MIT License.