Koajs 2 Rate Limit (Bruteforce)

Rate-limiting middleware for Koa2 with async await. Use to limit repeated requests to APIs and/or endpoints such as password reset.

Note: This module is based on express-rate-limit and adapted to koa2 ES6 with the async await capabilities.

Summary

• Install
• Usage
  • Use with RedisStore
  • Use with SequelizeStore
  • Use with MongooseStore (Mongodb)
• Configuration
• Time Type
• Upgrade
• 0.9.1 to 1.0.0

Install

1$ npm install --save koa2-ratelimit

Usage

For an API-only server where the rate-limiter should be applied to all requests:

1const RateLimit = require('koa2-ratelimit').RateLimit;
2
3const limiter = RateLimit.middleware({
4  interval: { min: 15 }, // 15 minutes = 15*60*1000
5  max: 100, // limit each IP to 100 requests per interval
6});
7
8//  apply to all requests
9app.use(limiter);

Create multiple instances to apply different rules to different routes:

1const RateLimit = require('koa2-ratelimit').RateLimit;
2const KoaRouter = require('koa-router');
3const router = new KoaRouter();
4
5const getUserLimiter = RateLimit.middleware({
6  interval: 15*60*1000, // 15 minutes
7  max: 100,
8  prefixKey: 'get/user/:id' // to allow the bdd to Differentiate the endpoint 
9});
10// add route with getUserLimiter middleware
11router.get('/user/:id', getUserLimiter, (ctx) => {
12  // Do your job
13});
14
15const createAccountLimiter = RateLimit.middleware({
16  interval: { hour: 1, min: 30 }, // 1h30 window
17  delayAfter: 1, // begin slowing down responses after the first request
18  timeWait: 3*1000, // slow down subsequent responses by 3 seconds per request
19  max: 5, // start blocking after 5 requests
20  prefixKey: 'post/user', // to allow the bdd to Differentiate the endpoint 
21  message: "Too many accounts created from this IP, please try again after an hour",
22  messageKey: "message"
23});
24// add route  with createAccountLimiter middleware
25router.post('/user', createAccountLimiter, (ctx) => {
26  // Do your job
27});
28
29// mount routes
30app.use(router.middleware())
31

Set default options to all your middleware:

1const RateLimit = require('koa2-ratelimit').RateLimit;
2
3RateLimit.defaultOptions({
4    message: 'Get out.',
5    // ...
6});
7
8const getUserLimiter = RateLimit.middleware({
9  max: 100,
10  // message: 'Get out.', will be added
11});
12
13const createAccountLimiter = RateLimit.middleware({
14  max: 5, // start blocking after 5 requests
15  // message: 'Get out.', will be added
16});

Use with RedisStore

1npm install redis@4

1const RateLimit = require('koa2-ratelimit').RateLimit;
2const Stores = require('koa2-ratelimit').Stores;
3//Detailed Redis Configuration Reference: https://github.com/redis/node-redis/blob/master/docs/client-configuration.md
4RateLimit.defaultOptions({
5    message: 'Get out.',
6    store: new Stores.Redis({
7        socket: {
8            host: 'redis_host',
9            port: 'redis_port',
10        },
11        password: 'redis_password',
12        database: 1
13    })
14});
15
16const getUserLimiter = RateLimit.middleware({
17    prefixKey: 'get/user/:id',
18});
19router.get('/user/:id', getUserLimiter, (ctx) => {});
20
21const createAccountLimiter = RateLimit.middleware.middleware({
22    prefixKey: 'post/user',
23});
24router.post('/user', createAccountLimiter, (ctx) => {});
25
26// mount routes
27app.use(router.middleware())

Use with SequelizeStore

1npm install sequelize@5

1const Sequelize = require('sequelize');
2const RateLimit = require('koa2-ratelimit').RateLimit;
3const Stores = require('koa2-ratelimit').Stores;
4
5const sequelize = new Sequelize(/*your config to connected to bdd*/);
6
7RateLimit.defaultOptions({
8    message: 'Get out.',
9    store: new Stores.Sequelize(sequelize, {
10        tableName: 'ratelimits', // table to manage the middleware
11        tableAbuseName: 'ratelimitsabuses', // table to store the history of abuses in.
12    })
13});
14
15const getUserLimiter = RateLimit.middleware({
16    prefixKey: 'get/user/:id',
17});
18router.get('/user/:id', getUserLimiter, (ctx) => {});
19
20const createAccountLimiter = RateLimit.middleware.middleware({
21    prefixKey: 'post/user',
22});
23router.post('/user', createAccountLimiter, (ctx) => {});
24
25// mount routes
26app.use(router.middleware())

Use with MongooseStore (Mongodb)

1npm install mongoose@5

1const mongoose = require('mongoose');
2const RateLimit = require('koa2-ratelimit').RateLimit;
3const Stores = require('koa2-ratelimit').Stores;
4
5await mongoose.connect(/*your config to connected to bdd*/);
6
7RateLimit.defaultOptions({
8    message: 'Get out.',
9    store: new Stores.Mongodb(mongoose.connection, {
10        collectionName: 'ratelimits', // table to manage the middleware
11        collectionAbuseName: 'ratelimitsabuses', // table to store the history of abuses in.
12    }),
13});
14

A ctx.state.rateLimit property is added to all requests with the limit, current, and remaining number of requests for usage in your application code.

Configuration

• interval: Time Type - how long should records of requests be kept in memory. Defaults to 60000 (1 minute).

• delayAfter: max number of connections during interval before starting to delay responses. Defaults to 1. Set to 0 to disable delaying.

• timeWait: Time Type - how long to delay the response, multiplied by (number of recent hits - delayAfter). Defaults to 1000 (1 second). Set to 0 to disable delaying.

• max: max number of connections during interval milliseconds before sending a 429 response code. Defaults to 5. Set to 0 to disable.

• message: Error message returned when max is exceeded. Defaults to 'Too many requests, please try again later.'

• statusCode: HTTP status code returned when max is exceeded. Defaults to 429.

• headers: Enable headers for request limit (X-RateLimit-Limit) and current usage (X-RateLimit-Remaining) on all responses and time to wait before retrying (Retry-After) when max is exceeded.

• skipFailedRequests: when true, failed requests (response status >= 400) won't be counted. Defaults to false.

• whitelist: Array of whitelisted IPs/UserIds to not be rate limited.

• getUserIdFromKey: Function that extracts from given key the userId. Defaults to (key) => key.split(options.prefixKeySeparator).

• prefixKeySeparator: Separator string between the prefixKey and the userId. Defaults to ::. (Set it to | if you want whitelist userIds)

• getUserId: Function used to get userId (if connected) to be added as key and saved in bdd, should an abuse case surface. Defaults:

  1async function (ctx) {
  2    const whereFinds = [ctx.state.user, ctx.user, ctx.state.User, 
  3      ctx.User, ctx.state, ctx];
  4    const toFinds = ['id', 'userId', 'user_id', 'idUser', 'id_user'];
  5    for (const whereFind of whereFinds) {
  6      if (whereFind) {
  7        for (const toFind of toFinds) {
  8          if (whereFind[toFind]) {
  9              return whereFind[toFind];
  10          }
  11        }
  12      }
  13    }
  14    return null;
  15},

• keyGenerator: Function used to generate keys. By default userID (if connected) or the user's IP address. Defaults:

  1async function (ctx) {
  2    const userId = await this.options.getUserId(ctx);
  3    if (userId) {
  4        return `${this.options.prefixKey}|${userId}`;
  5    }
  6    return `${this.options.prefixKey}|${ctx.request.ip}`;
  7}

• skip: Function used to skip requests. Returning true from the function will skip limiting for that request. Defaults:

  1async function (/*ctx*/) {
  2    return false;
  3}

• handler: The function to execute once the max limit has been exceeded. It receives the request and the response objects. The "next" param is available if you need to pass to the next middleware. Defaults:

  1async function (ctx/*, next*/) {
  2    ctx.status = this.options.statusCode;
  3    ctx.body = { message: this.options.message };
  4    if (this.options.headers) {
  5        ctx.set('Retry-After', Math.ceil(this.options.interval / 1000));
  6    }
  7}

• onLimitReached: Function to listen each time the limit is reached. It call the store to save abuse, You can use it to debug/log. Defaults:

  1async function (ctx) {
  2    this.store.saveAbuse({
  3        key: await this.options.keyGenerator(ctx),
  4        ip: ctx.request.ip,
  5        user_id: await this.options.getUserId(ctx),
  6    });
  7}

• weight: Function to set the incrementation of the counter depending on the request. Defaults:

  1async function (/*ctx*/) {
  2    return 1;
  3}

• store: The storage to use when persisting rate limit attempts. By default, the MemoryStore is used.

  Avaliable data stores are:

  • MemoryStore: (default)Simple in-memory option. Does not share state when app has multiple processes or servers.
  • SequelizeStore: more suitable for large or demanding deployments.

The delayAfter and timeWait options were written for human-facing pages such as login and password reset forms. For public APIs, setting these to 0 (disabled) and relying on only interval and max for rate-limiting usually makes the most sense.

Time Type

Time type can be milliseconds or an object

1    Times = {
2        ms ?: number,
3        sec ?: number,
4        min ?: number,
5        hour ?: number,
6        day ?: number,
7        week ?: number,
8        month ?: number,
9        year ?: number,
10    };

Examples

1    RateLimit.middleware({
2        interval: { hour: 1, min: 30 }, // 1h30 window
3        timeWait: { week: 2 }, // 2 weeks window
4    });
5    RateLimit.middleware({
6        interval: { ms: 2000 }, // 2000 ms = 2 sec
7        timeWait: 2000, // 2000 ms = 2 sec
8    });

Upgrade

0.9.1 to 1.0.0

1.0.0 moves sequelize, mongoose and redis from dependencies to peerDependencies.

Install the one you use (see Use with RedisStore, Use with SequelizeStore or Use with MongooseStore (Mongodb)).

The rest did not change.

License

MIT © YSO Corp