Nuxt API Shield

This Nuxt module implements a rate limiting middleware to protect your API endpoints from excessive requests.

• ✨  Release Notes
  • 📖  Documentation

Features

• IP-Based Rate limiting and Brute Force Protection
  • Tracks and enforces rate limits for individual IP addresses.
  • Prevents malicious actors or excessive requests from a single source from overwhelming your API.
• Customizable Rate Limits
  • Configure maximum request count, duration within which the limit applies, and a ban period for exceeding the limit.
  • If the request limit is exceeded, the user is banned for the configured ban period. During the ban period, all requests are blocked with a 429 error, regardless of the rate limit window.
  • Add a delay to responses when a user is banned to discourage further abuse (optional).
  • Customize the error message for banned users.
  • Optionally include the Retry-After header in responses when a user is banned.
  • Tailor the rate-limiting behavior to align with your API's specific needs and usage patterns.
• Event-Driven Handling
  • Intercepts incoming API requests efficiently using Nuxt's event system.
  • Ensures seamless integration with your Nuxt application's request lifecycle.
• Flexible Storage
  • Utilizes Nuxt's unstorage abstraction for versatile storage options.
  • Store rate-limiting data in various storage providers (filesystem, memory, databases, etc.) based on your project's requirements.
• Configurable with Runtime Config
  • Easily adjust rate-limiting parameters without code changes.
  • Adapt to dynamic needs and maintain control over rate-limiting behavior through Nuxt's runtime configuration.
• Clear Error Handling
  • Returns a standardized 429 "Too Many Requests" error response when rate limits are exceeded or when a user is banned.
  • Facilitates proper error handling in client-side applications for a smooth user experience.

Quick Setup

1. Add nuxt-api-shield dependency to your project

1# Using pnpm
2pnpm add nuxt-api-shield
3
4# Using yarn
5yarn add nuxt-api-shield
6
7# Using npm
8npm install nuxt-api-shield

2. Add nuxt-api-shield to the modules section of nuxt.config.ts

You should add only the values you want to use differently from the default values.

1export default defineNuxtConfig({
2  modules: ["nuxt-api-shield"],
3  nuxtApiShield: {
4    /*limit: {
5      max: 12,        // maximum requests per duration time, default is 12/duration
6      duration: 108,   // duration time in seconds, default is 108 seconds
7      ban: 3600,      // ban time in seconds, default is 3600 seconds = 1 hour
8      // If the request limit is exceeded, the user is banned for this period. During the ban, all requests are blocked with 429.
9    },
10    delayOnBan: true  // delay every response with +1sec when the user is banned, default is true
11    errorMessage: "Too Many Requests",  // error message when the user is banned, default is "Too Many Requests"
12    retryAfterHeader: false, // when the user is banned add the Retry-After header to the response, default is false
13    log: {
14      path: "logs", // path to the log file, every day a new log file will be created, use "" to disable logging
15      attempts: 100,    // if an IP reach 100 requests, all the requests will be logged, can be used for further analysis or blocking for example with fail2ban, use 0 to disable logging
16    },
17    routes: [], // specify routes to apply rate limiting to, default is an empty array meaning all routes are protected.
18    // Example:
19    // routes: ["/api/v2/", "/api/v3/"], // /api/v1 will not be protected, /api/v2/ and /api/v3/ will be protected */
20  },
21});

3. Add nitro/storage to nuxt.config.ts

You can use any storage you want, but you have to use shield as the name of the storage.

1{
2  "nitro": {
3    "storage": {
4      "shield": {
5        // storage name, you **must** use "shield" as the name
6        "driver": "memory"
7      }
8    }
9  }
10}

If you use for example redis, you can use the following configuration, define the host and port.

1{
2  "nitro": {
3    "storage": {
4      "shield": {
5        "driver": "redis",
6        "host": "localhost",
7        "port": 6379,
8      }
9    }
10  }
11}

4. Add shield:clean to nuxt.config.ts

1{
2  "nitro": {
3    "experimental": {
4      "tasks": true
5    },
6    "scheduledTasks": {
7      "*/15 * * * *": ["shield:clean"] // clean the shield storage every 15 minutes
8    }
9  }
10}

5. Create your clean task

In server/tasks/shield/clean.ts you should have something like this.

1import type { RateLimit } from "#imports";
2
3export default defineTask({
4  meta: {
5    description: "Clean expired bans",
6  },
7  async run() {
8    const shieldStorage = useStorage("shield");
9
10    const keys = await shieldStorage.getKeys();
11    keys.forEach(async (key) => {
12      const rateLimit = (await shieldStorage.getItem(key)) as RateLimit;
13      if (isBanExpired(rateLimit)) {
14        await shieldStorage.removeItem(key);
15      }
16    });
17    return { result: keys };
18  },
19});

Development

1# Install dependencies
2yarn
3
4# Generate type stubs
5yarn dev:prepare
6
7# Develop with the playground
8yarn dev
9
10# Build the playground
11yarn dev:build
12
13# Run ESLint
14yarn lint
15
16# Run Vitest
17yarn test
18yarn test:watch
19
20# Release new version
21yarn release:patch
22yarn release:minor