KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

nuxt-api-shield

★ 56 Open GitHub ↗

Nuxt API Rate Limiter / Brute Force Protection

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nuxt API Shield

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

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

- [✨ &nbsp;Release Notes](/CHANGELOG.md)
  
  - [📖 &nbsp;Documentation](https://github.com/rrd108/nuxt-api-shield)

## 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.
- **Bundled cleanup tasks**
  - Registers Nitro tasks `shield:cleanBans` and `shield:cleanIpData` so you can schedule maintenance without adding task files (see setup step 4).
- **Clear Error Handling**
  - Returns a standardized 429 "Too Many Requests" error response when rate limits are exceeded or when a user is banned.
  - The 429 body is JSON (`{ error, retryAfter }`) for predictable client-side handling.
  - Facilitates proper error handling in client-side applications for a smooth user experience.
- **Standard Rate-Limit Headers**
  - Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers so clients and CDNs can track usage without parsing response bodies.

## Quick Setup

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

```bash
# Using pnpm
pnpm add nuxt-api-shield

# Using yarn
yarn add nuxt-api-shield

# Using npm
npm 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.

```js
export default defineNuxtConfig({
  modules: ["nuxt-api-shield"],
  nuxtApiShield: {
    /*limit: {
      max: 12,        // maximum requests per duration time, default is 12/duration
      duration: 108,   // duration time in seconds, default is 108 seconds
      ban: 3600,      // ban time in seconds, default is 3600 seconds = 1 hour
      // If the request limit is exceeded, the user is banned for this period. During the ban, all requests are blocked with 429.
    },
    delayOnBan: true  // delay every response with +1sec when the user is banned, default is true
    errorMessage: "Too Many Requests",  // error message when the user is banned, default is "Too Many Requests"
    retryAfterHeader: false, // when the user is banned add the Retry-After header to the response, default is false
    log: {
      path: "", // path to the log file, every day a new log file will be created, use "" to disable logging
      attempts: 0,    // if an IP reach 0 requests (disabled), all the requests will be logged, can be used for further analysis or blocking for example with fail2ban, use 0 to disable logging
      fail2ban: false, // enable fail2ban-compatible log format for ban events (see fail2ban section)
    },
    routes: [], // specify routes to apply rate limiting to, default is an empty array meaning all routes are protected.
    // Example:
    // routes: ["/api/v2/", "/api/v3/"], // /api/v1 will not be protected, /api/v2/ and /api/v3/ will be protected */
    skipRoutes: [], // specify routes to skip/exempt from rate limiting, supports wildcard patterns (*/**)
    // Example:
    // skipRoutes: ["/api/health", "/api/_nuxt/**", "/api/webhooks/stripe"],
    ipTTL: 604800, // Optional: Time-to-live in seconds for IP tracking entries (default: 7 days). Set to 0 or negative to disable this specific cleanup.
    security: {
      // Optional: Security-related configurations
      trustXForwardedFor: false, // Default: false. Whether to trust X-Forwarded-For headers. See warning below.
    },
  },
});
```

**Default Configuration Values:**
(These are applied by the module if not specified in your `nuxtApiShield` config)

```js
{
  limit: {
    max: 12,
    duration: 108, // seconds
    ban: 3600,     // seconds
  },
  delayOnBan: true,
  errorMessage: "Too Many Requests",
  retryAfterHeader: false,
  log: {
    path: "", // Logging is disabled if path is empty
    attempts: 0, // Logging per IP is disabled if attempts is 0
    fail2ban: false,
  },
  routes: [],
  skipRoutes: [],
  ipTTL: 7 * 24 * 60 * 60, // 7 days in seconds
  security: {
    trustXForwardedFor: false,
  }
}
```

**Security Warning: `trustXForwardedFor`**

The `security.trustXForwardedFor` option (default is `false`, set by the module) determines if the module uses the `X-Forwarded-For` HTTP header to identify the client's IP address.

- If set to `true`: The module will use the IP address provided in the `X-Forwarded-For` header. This is common when your Nuxt application is behind a trusted reverse proxy, load balancer, or CDN (like Nginx, Cloudflare, AWS ELB/ALB) that correctly sets this header with the real client IP.
- **WARNING:** If `trustXForwardedFor` is `true` and your application is directly internet-facing OR your proxy is not configured to strip incoming `X-Forwarded-For` headers from clients, malicious users can spoof their IP address by sending a fake `X-Forwarded-For` header. This would allow them to bypass rate limits or cause other users to be incorrectly rate-limited.
- If set to `false`: The module will use the direct IP address of the incoming connection (i.e., `event.node.req.socket.remoteAddress`). Use this setting if your application is directly internet-facing or if you are unsure about your proxy's configuration.
- **Recommendation:** Only enable `trustXForwardedFor: true` if you are certain your reverse proxy is correctly configured to set this header and strip any client-sent versions of it. Otherwise, set it to `false`.

### 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.

```json
{
  "nitro": {
    "storage": {
      "shield": {
        // storage name, you **must** use "shield" as the name
        "driver": "memory"
      }
    }
  }
}
```

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

```json
{
  "nitro": {
    "storage": {
      "shield": {
        "driver": "redis",
        "host": "localhost",
        "port": 6379
      }
    }
  }
}
```

### 4. Schedule bundled cleanup tasks in `nuxt.config.ts`

The module registers two Nitro tasks for you: `shield:cleanBans` (removes expired `ban:*` keys) and `shield:cleanIpData` (removes stale `ip:*` keys using `ipTTL`). Turn on Nitro tasks and add `scheduledTasks` so they run on a cadence you choose. You do **not** need files under `server/tasks/` for this default setup.

```json
{
  "nitro": {
    "experimental": {
      "tasks": true
    },
    "scheduledTasks": {
      "*/15 * * * *": ["shield:cleanBans"],
      "0 0 * * *": ["shield:cleanIpData"]
    }
  }
}
```

Cron expressions are examples only: for instance, clean expired bans every 15 minutes and IP tracking data daily at midnight.

### 5. Optional: custom cleanup task implementations

Skip this unless you need behavior different from the bundled handlers (for example extra logging, metrics, or storage layout). The snippets below mirror what the module already ships; they are useful as a reference or if you define **another** task name and point `scheduledTasks` at that name instead.

#### a) Task for cleaning expired bans

Removes ban entries (`ban:xxx.xxx.xxx.xxx`) after the ban timestamp has passed.

Example `server/tasks/shield/cleanBans.ts` (task name must match what you schedule):

```ts
import { isActualBanTimestampExpired } from "#imports"; // Auto-imported utility from nuxt-api-shield

export default defineTask({
  meta: {
    name: "shield:cleanBans", // Match the name in scheduledTasks
    description: "Clean expired bans from nuxt-api-shield storage.",
  },
  async run() {
    const shieldStorage = useStorage("shield"); // Use your configured storage name

// Only fetch keys that start with the 'ban:' prefix
    const banKeys = await shieldStorage.getKeys("ban:");

The `isActualBanTimestampExpired` utility is provided by `nuxt-api-shield` and should be available via `#imports`.

#### b) Task for cleaning old IP tracking data

Cleans IP tracking entries (`ip:xxx.xxx.xxx.xxx`) whose `time` is older than `nuxtApiShield.ipTTL` (default 7 days), and drops malformed entries. That keeps storage from growing with one-off IPs that were never banned.

Example `server/tasks/shield/cleanIpData.ts`:

```ts
import type { RateLimit } from "nuxt-api-shield";
import { useRuntimeConfig } from "#imports";

export default defineTask({
  meta: {
    name: "shield:cleanIpData", // Match the name in scheduledTasks
    description: "Clean old IP tracking data from nuxt-api-shield storage.",
  },
  async run() {
    const shieldStorage = useStorage("shield");
    const config = useRuntimeConfig().public.nuxtApiShield;

// ipTTL is expected to be in seconds from config (module applies default if not set by user)
    const ipTTLseconds = config.ipTTL;

if (!ipTTLseconds || ipTTLseconds <= 0) {
      console.log(
        "[nuxt-api-shield] IP data cleanup (ipTTL) is disabled or invalid."
      );
      return { result: { cleanedCount: 0 }, status: "disabled_or_invalid_ttl" };
    }
    const ipTTLms = ipTTLseconds * 1000;

const ipKeys = await shieldStorage.getKeys("ip:");
    const currentTime = Date.now();
    let cleanedCount = 0;

for (const key of ipKeys) {
      const entry = (await shieldStorage.getItem(key)) as RateLimit | null;

// Check if entry exists and has a numeric 'time' property
      if (entry && typeof entry.time === "number") {
        if (currentTime - entry.time > ipTTLms) {
          await shieldStorage.removeItem(key);
          cleanedCount++;
        }
      } else {
        // Clean up entries that are null, not an object, or missing a numeric 'time'
        await shieldStorage.removeItem(key);
        cleanedCount++;
      }
    }

console.log(
      `[nuxt-api-shield] Cleaned ${cleanedCount} old/malformed IP data entries.`
    );
    return { result: { cleanedCount } };
  },
});
```

Configure `ipTTL` under `nuxtApiShield` if you want a TTL other than the default. Setting `ipTTL` to `0` (or any non-positive value) makes the bundled `shield:cleanIpData` task skip IP cleanup (it logs and exits).

If you add your own task file with the same `meta.name` as a bundled task (`shield:cleanBans` or `shield:cleanIpData`), Nitro may prefer your project file over the module—avoid duplicate names unless you intend to override.

## Production Deployment

### Use Redis as the storage driver

For production deployments — especially with multiple server instances or significant traffic — **Redis is the recommended storage driver**. The `memory` and `fs` drivers have important limitations:

| Area | `memory` / `fs` | Redis |
|------|----------------|-------|
| **Multi-instance** | Each process has its own isolated state. Rate limits reset per instance, allowing bypass. | Shared state across all instances. |
| **Atomic operations** | Read → increment → write is not atomic. Concurrent requests can both read the same count and exceed the limit simultaneously. | Single-threaded — reads and writes are naturally atomic. No race conditions. |
| **Cleanup** | Cleanup tasks (`shield:cleanBans`, `shield:cleanIpData`) must scan all keys with `getKeys()`. At scale this blocks the event loop. | Use `EXPIRE` or `TTL` natively — expired keys are reclaimed automatically without scanning. |

To use Redis, configure the `shield` storage with the `redis` driver:

```json
{
  "nitro": {
    "storage": {
      "shield": {
        "driver": "redis",
        "host": "localhost",
        "port": 6379
      }
    }
  }
}
```

See the [unstorage Redis driver docs](https://unstorage.unjs.io/drivers/redis) for all available options.

### When `memory` / `fs` is acceptable

The `memory` and `fs` drivers are fine for:
- Single-instance deployments
- Development environments
- Low-traffic applications where occasional race conditions are acceptable

For everything else, use Redis.

## Fail2ban Integration

When a user exceeds the rate limit and gets banned, `nuxt-api-shield` can write ban events to the log file in a `fail2ban`-compatible format. You can then configure fail2ban to watch these logs and automatically block the IP at the firewall level.

### Setup

Enable fail2ban logging by setting `log.fail2ban` to `true` and configuring the `log.path`:

```js
export default defineNuxtConfig({
  modules: ["nuxt-api-shield"],
  nuxtApiShield: {
    log: {
      path: "/var/log/nuxt-api-shield", // required — must be set
      attempts: 1,                       // optional — threshold for regular request logging
      fail2ban: true,                     // enable fail2ban format
    },
  },
})
```

When enabled, every ban event writes a line like:

```
2026-06-21 12:34:56,789 nuxt-api-shield ban 192.168.1.100 — /api/v3/login exceeded limit (12 requests in 108s)
```

### Fail2ban filter configuration

Create `/etc/fail2ban/filter.d/nuxt-api-shield.conf`:

```ini
[Definition]
failregex = ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3} nuxt-api-shield ban <HOST>
```

### Jail configuration

Add a jail entry in `/etc/fail2ban/jail.local`:

```ini
[nuxt-api-shield]
enabled  = true
filter   = nuxt-api-shield
logpath  = /var/log/nuxt-api-shield/shield-*.log
port     = http,https
banaction = iptables-multiport
maxretry = 1
findtime = 1
bantime  = 3600
```

Since `nuxt-api-shield` already applies its own ban logic (configurable via `limit.ban`), set `maxretry = 1` and `findtime = 1` so fail2ban acts immediately on each ban log entry. Adjust `bantime` to match or extend your module-level ban duration.

Restart fail2ban after adding the config:

```bash
sudo systemctl restart fail2ban
```

> **Note:** The `log.path` directory must be readable by the fail2ban service. Ensure permissions are set accordingly.

## TypeScript Types

The module exports TypeScript types that you can use in your application:

### `RateLimit` Type

The `RateLimit` type represents the structure of rate limit data stored for each IP address:

```ts
import type { RateLimit } from "nuxt-api-shield";

// RateLimit structure:
// {
//   count: number  // Number of requests made
//   time: number   // Timestamp of the last request
// }
```

**Usage Example:**

```ts
import type { RateLimit } from "nuxt-api-shield";
import { useStorage } from "#imports";

const shieldStorage = useStorage("shield");
const ipKey = "ip:192.168.1.1";
const entry = (await shieldStorage.getItem(ipKey)) as RateLimit | null;

if (entry) {
  console.log(`IP has made ${entry.count} requests`);
  console.log(`Last request at: ${new Date(entry.time).toISOString()}`);
}
```

### `ModuleOptions` Type

You can also import the module configuration type:

```ts
import type { ModuleOptions } from "nuxt-api-shield";
```

## Per-Route Rate Limiting

`nuxt-api-shield` supports **per-route rate limiting**, allowing you to define custom limits for specific API endpoints while keeping a global default configuration for all other routes.

This is useful when certain endpoints (such as `/api/login`, `/api/auth`, or `/api/payment`) require stricter protection.

---

### Configuration Example

The `routes` option accepts a mixed array of strings (exact matches) and objects (custom limits or patterns).

```ts
export default defineNuxtConfig({
  modules: ["nuxt-api-shield"],

nuxtApiShield: {
    limit: {
      max: 12,
      duration: 108,
      ban: 3600,
    },

routes: [
      // 1. String: uses the global default limit (exact match)
      "/api/example",

// 2. Object: custom rate limit for a specific route (exact match)
      {
        path: "/api/example-per-route",
        max: 5,
        duration: 10,
        // "ban" can also be overridden per route
      },

// 3. Object: Wildcard pattern
      {
        path: "/api/users/*/profile",
        pattern: true,
        max: 10,
        duration: 60
      }
    ],
  },
});
```

### Wildcard Route Support

Wildcard patterns allow you to apply the same limits to groups of related API endpoints. Enable them by setting `pattern: true` in your route configuration.

#### Wildcard Pattern Syntax

- **Single-Segment Wildcard (`*`)**: Matches exactly one path segment.
  - `/api/users/*/profile` matches `/api/users/123/profile` or `/api/users/admin/profile`.
- **Multi-Segment Wildcard (`**`)**: Matches zero or more path segments.
  - `/api/reports/**/summary` matches `/api/reports/monthly/2023/summary` or `/api/reports/summary`.

#### Pattern Precedence
1. **Exact matches** always take precedence over wildcard patterns.
2. **More specific wildcards** take precedence over less specific ones.
3. When multiple wildcard patterns match, the most specific one is used.

#### Important Notes
- **Shared Rate Limits:** All requests that match the same wildcard pattern share the same rate limit counter.
- **Security:** Broad or dangerous patterns like `/**` or `/*` are automatically rejected to prevent accidental global blocking.

## Skipping Routes

The `skipRoutes` option lets you exempt specific paths from all shield processing (ban check, rate limit counter, and logging) without needing to list every protected route in the `routes` array.

This is useful for health checks, webhook endpoints, monitoring probes, or internal status routes that should always respond regardless of traffic.

### Configuration Example

```ts
export default defineNuxtConfig({
  modules: ["nuxt-api-shield"],

nuxtApiShield: {
    limit: {
      max: 12,
      duration: 108,
      ban: 3600,
    },

skipRoutes: [
      "/api/health",          // exact match
      "/api/_nuxt/**",        // multi-segment wildcard
      "/api/webhooks/stripe", // exact match
    ],
  },
})
```

### How It Works

- Routes in `skipRoutes` bypass the middleware entirely — no ban check, no rate limit counter, no log entry.
- The rest of your API routes (those matching the global defaults or the `routes` option) continue to be rate limited normally.
- Supports the same wildcard syntax as per-route patterns: `*` for single segment, `**` for multi-segment.

## Important Considerations

### Data Privacy (IP Address Storage)

`nuxt-api-shield` functions by tracking IP addresses to monitor request rates and apply bans. This means IP addresses, which can be considered Personally Identifiable Information (PII) under regulations like GDPR, are stored by the module.

- **Data Stored:**
  - `ip:<IP_ADDRESS>`: Stores `{ count: number, time: number }` for tracking request rates.
  - `ban:<IP_ADDRESS>`: Stores a timestamp indicating when a ban on an IP address expires.
- **Compliance:** Ensure your usage complies with any applicable data privacy regulations. This may involve updating your privacy policy to inform users about this data processing.
- **Data Retention:**
  - Ban entries are cleaned up by the `shield:cleanBans` task after expiry.
  - IP tracking entries are cleaned up by the `shield:cleanIpData` task based on the `ipTTL` setting.

### Storage Security

- **Filesystem Driver (`driver: 'fs'`):** If you use the filesystem driver for `unstorage` (e.g., `driver: 'fs'`, `base: '.shield'`), ensure that the storage directory (and the `logs` directory if logging is enabled via `log.path`) is:
  - **Not web-accessible:** Your web server should not be configured to serve files from these directories.
  - **Properly permissioned:** The directories should have appropriate server-side file permissions to prevent unauthorized reading or writing.
- **Other Drivers (Redis, etc.):** If using database drivers like Redis, ensure your database server itself is secured (e.g., authentication, network access controls).

### Error Message (`errorMessage`)

The `errorMessage` option in the module configuration is returned in the body of a 429 response.

- It's recommended to use a plain text message.
- If you choose to use HTML in your `errorMessage`, ensure your client-side application correctly sanitizes it or renders it in a way that prevents XSS vulnerabilities. The module itself does not sanitize this user-configured message.

## Development

```bash
# Install dependencies
yarn

# Generate type stubs
yarn dev:prepare

# Develop with the playground
yarn dev

# Build the playground
yarn dev:build

# Run ESLint
yarn lint

# Run Vitest
yarn test
yarn test:watch

# Release new version
yarn release:patch
yarn release:minor
```

[npm-version-src]: https://img.shields.io/npm/v/nuxt-api-shield/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/nuxt-api-shield
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-api-shield.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npmjs.com/package/nuxt-api-shield
[license-src]: https://img.shields.io/npm/l/nuxt-api-shield.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://npmjs.com/package/nuxt-api-shield
[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com

nuxt-api-shield

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README