Rate Limiting

The IAM service uses rate-limiter-flexible for all rate limiting. Every sensitive endpoint has its own named limiter group built at startup from the rate_limiters section of the service configuration. The built-in limiters store state in MySQL, via a dedicated callback-based pool separate from the main auth pool, and maintain in-memory mirrors for fast lookups.

The system layers multiple limiters per endpoint. A typical endpoint has a union limiter combining a burst and slow limiter into a single gate, an IP limiter, and an identity limiter (keyed on email, OAuth subject, token hash, or user ID). All layers must pass for a request to proceed. If any layer rejects, the service returns 429 Too Many Requests with a Retry-After header.

On top of the limiter layer, a strike system tracks consecutive failures per key in an LRU cache. When a key accumulates enough strikes (the maxBans threshold), the guard function permanently blocks the key via the limiter's block() method and adds it to a global block cache. Blocked keys are rejected immediately on subsequent requests without consuming limiter points.

Overview

Dual-Layer Design

Each rate limiter in the system operates on two storage layers simultaneously:

The in-memory layer acts as an insurance mechanism. If the MySQL connection fails, the in-memory limiter continues to enforce rate limits. If both layers are healthy, the in-memory layer short-circuits obvious violations before they reach the database.

Storage Pool

The rate limiter pool is separate from the main authentication pool. It uses the callback-based mysql API because rate-limiter-flexible requires a callback-style connection. Configure it in the store.rate_limiters_pool section:

See Database for more details.

Core Utilities

The rate limiting system is built from four composable functions. When using the IAM service as a library, all four are exported from @riavzon/auth.

makeRateLimiter

Creates a single rate limiter instance. The sql parameter controls whether the limiter persists state in MySQL or runs purely in memory. The BlackWhiteList parameter wraps the limiter with an allow/deny list layer.

import { makeRateLimiter } from '@riavzon/auth'

const limiter = makeRateLimiter(true, false, {
  dbName: 'rate_limiters',
  storeClient: pool,
  storeType: 'mysql2',
  tableName: 'login',
  keyPrefix: 'login_burst',
  points: 1,
  duration: 1,
  blockDuration: 1800,
  inMemoryBlockOnConsumed: 2,
  inMemoryBlockDuration: 1800,
})

Settings Fields

unionLimiter

Combines two or more individual limiters into a single gate. Both limiters in the union are consumed on every attempt. If either limiter rejects, the request is blocked.

import { makeRateLimiter, unionLimiter } from '@riavzon/auth'

const burst = makeRateLimiter(true, false, {
  keyPrefix: 'login_burst',
  points: 1,
  duration: 1,
  blockDuration: 1800,
  // ... other fields
})

const slow = makeRateLimiter(true, false, {
  keyPrefix: 'login_slow',
  points: 5,
  duration: 3600,
  blockDuration: 1800,
  // ... other fields
})

const loginUnion = unionLimiter([burst, slow], false)

The returned object extends RateLimiterUnion with two additional methods:

guard

The primary entry point for applying rate limiting in a controller. It combines limiter consumption, consecutive failure tracking, and permanent blocking into a single call. Returns true if the request is allowed, false if rate limited.

import { guard, makeConsecutiveCache } from '@riavzon/auth'

const consecutiveCache = makeConsecutiveCache<{ countData: number }>(500, 60_000)

const allowed = await guard(
  limiter,                // Any limiter: Memory, MySQL, or BlockableUnion
  req.ip!,                // The key to rate limit on
  consecutiveCache,       // LRU cache tracking consecutive failures
  2,                      // maxBans: strikes before permanent block
  'ip',                   // Label for log messages
  log,                    // Pino logger
  res,                    // Express response (guard sends 429 automatically)
  3600                    // Optional: block duration in seconds (0 = permanent)
)

if (!allowed) return      // Response already sent

How the Guard Works

consumeOrReject

Low-level function that attempts to consume one point from a limiter. If consumption fails, it sends the 429 response and returns null. If consumption succeeds, it returns the RateLimiterRes object with remaining points and timing data.

import { consumeOrReject } from '@riavzon/auth'

const result = await consumeOrReject(limiter, key, res, log)

if (result === null) {
  // Request already rejected with 429
  return
}

// result.remainingPoints — how many attempts the key has left
// result.consumedPoints  — how many attempts the key has used
// result.msBeforeNext    — milliseconds until the window resets

When the limiter rejects:

resetLimiters

Resets all accumulated points for a key across an array of limiters. Typically called after a successful authentication to clear penalties that accumulated during failed attempts.

import { resetLimiters } from '@riavzon/auth'

resetLimiters(log, compositeKey, [burst, slow, ipLimiter, emailLimiter])

makeConsecutiveCache

Factory function that creates an LRU cache for tracking consecutive failures. Each cache instance is scoped to a specific key type (IP, email, composite, etc.) and has its own TTL.

import { makeConsecutiveCache } from '@riavzon/auth'

const cache = makeConsecutiveCache<{ countData: number }>(
  500,       // Maximum entries the cache can hold
  60_000     // TTL per entry in milliseconds
)

The consecutive cache is separate from the limiter store. Limiter points reset on their own schedule (based on duration). The consecutive cache tracks how many times a key has been caught by the limiter, regardless of when the limiter's window resets.

Key Strategies

Rate limiters are identified by the key they track. The IAM service uses four key strategies across its endpoint groups.

IP Key

The simplest strategy. Uses req.ip as the limiter key. Protects against a single source flooding an endpoint.

await guard(ipLimiter, req.ip!, consecutiveForIp, 2, 'ip', log, res)

Identity Key

Uses the user's identity (email, OAuth subject, user ID, or token hash) as the key. Protects against attacks targeting a specific account from rotating IPs.

await guard(emailLimiter, email, consecutiveForEmail, 2, 'email', log, res)

Composite Key

Combines the IP and identity into a single key with an underscore separator. Protects against a single source targeting a specific account. More precise than either key alone.

const compositeKey = `${req.ip!}_${email}`
await guard(uniLimiter, compositeKey, consecutive429, 3, 'ip+email', log, res)

Global Key

Uses a fixed string as the key. Protects against system-wide abuse by capping total requests across all users. The email MFA and password reset flows use 'global_emails' to cap the total number of outbound emails the system sends per day.

await guard(globalEmailLimiter, 'global_emails', consecutiveForGlobal, 1, 'globalEmailLimiter', log, res)

Guard Patterns in Controllers

Every endpoint that uses rate limiting follows the same pattern: call guard() one or more times at the top of the controller, each with a different limiter and key. If any guard rejects, the controller returns immediately (the 429 response was already sent by the guard).

Login

The login controller applies three guard layers before attempting authentication:

On successful login, the controller resets all limiters and clears all consecutive caches for the IP, email, and composite key:

consecutiveForIp.delete(req.ip!)
consecutive429.delete(compositeKey)
consecutiveForEmail.delete(email)
await resetLimitersUni(compositeKey)

Token Rotation

The rotation controller applies three guards but uses a different strategy than login. It does not key on email (the rotation endpoint does not accept email input). Instead, it keys on the SHA-256 hash of the refresh token.

After successful rotation, the controller does not reset limiters. Instead, it blocks the old token hash and composite key for 3 days:

await refreshTokenLimiter.block(hashedToken, 60 * 60 * 24 * 3)
await refreshAccessTokenLimiter.block(compositeKey, 60 * 60 * 24 * 3)

This prevents the old token from being used again even if it has not yet been revoked in the database. The block acts as a fast-path denial layer in front of the database revocation check.

Signup

The signup controller applies three guards:

OAuth

The OAuth controller applies three guards:

Password Reset Initiation

The password reset initiation controller (POST /auth/forgot-password) applies four guards:

Email MFA Initiation

The email MFA flow controller applies four guards:

Link Verification

Magic link verification (MFA, password reset, custom MFA) applies a single IP union guard. The union limiter contains a burst limiter (2 points per second) and a slow limiter (30 points per 30 minutes). maxBans: 1.

Temporary Post Routes

The password change and MFA code submission endpoints apply three guards:

Built-In Limiter Reference

All limiter groups are configured in the rate_limiters section of the service configuration. Every group is optional. Omitting a group disables rate limiting for those endpoints and uses hardcoded defaults instead.

Each limiter within a group accepts the same five fields:

loginLimiters

Protects POST /login against credential-stuffing attacks.

signupLimiters

Protects POST /signup against mass-registration bots. This group uses two union limiters instead of one.

oauthLimiters

Protects POST /auth/OAuth/:providerName.

tokenLimiters

Protects POST /auth/user/refresh-session (full token rotation).

linkVerificationLimiter

Protects magic link verification endpoints: MFA email links, password reset links, and custom MFA flow links.

initPasswordResetLimiters

Protects POST /auth/forgot-password.

emailMfaLimiters

Protects MFA email sending endpoints.

tempPostRoutesLimiters

Protects password change submissions and MFA code submissions (the POST endpoints that consume temporary magic links).

Building a Custom Rate Limiter

When you need to protect additional endpoints in your own application, you can compose the same utilities the IAM service uses internally. All factory functions and helpers are exported from @riavzon/auth.

import {
  makeRateLimiter,
  unionLimiter,
  type BlockableUnion,
} from '@riavzon/auth'
import type { RateLimiterMySQL, RateLimiterMemory, RLWrapperBlackAndWhite } from 'rate-limiter-flexible'
import type { Pool } from 'mysql2'

interface LimiterBundle {
  uniLimiter: BlockableUnion | RLWrapperBlackAndWhite
  ipLimiter: RateLimiterMySQL | RateLimiterMemory
  resetAll(key: string): Promise<void>
}

let instance: LimiterBundle | null = null

function build(pool: Pool, dbName: string): LimiterBundle {
  const burst = makeRateLimiter(true, false, {
    dbName,
    storeClient: pool,
    storeType: 'mysql2',
    tableName: 'my_endpoint',
    keyPrefix: 'my_endpoint_burst',
    points: 2,
    duration: 1,
    blockDuration: 1800,
    inMemoryBlockOnConsumed: 3,
    inMemoryBlockDuration: 1800,
  })

  const slow = makeRateLimiter(true, false, {
    dbName,
    storeClient: pool,
    storeType: 'mysql2',
    tableName: 'my_endpoint',
    keyPrefix: 'my_endpoint_slow',
    points: 10,
    duration: 3600,
    blockDuration: 3600,
    inMemoryBlockOnConsumed: 11,
    inMemoryBlockDuration: 3600,
  })

  const ipLimiter = makeRateLimiter(true, false, {
    dbName,
    storeClient: pool,
    storeType: 'mysql2',
    tableName: 'my_endpoint',
    keyPrefix: 'my_endpoint_ip',
    points: 20,
    duration: 86400,
    blockDuration: 14400,
    inMemoryBlockOnConsumed: 21,
    inMemoryBlockDuration: 14400,
  })

  return {
    uniLimiter: unionLimiter([burst, slow], false),
    ipLimiter,
    resetAll: async (key: string) => {
      await Promise.all([
        burst.delete(key),
        slow.delete(key),
        ipLimiter.delete(key),
      ])
    },
  }
}

export function init(pool: Pool, dbName: string): void {
  if (!instance) instance = build(pool, dbName)
}

export function getLimiters(): LimiterBundle {
  if (!instance) throw new Error('Limiters not initialized. Call init() first.')
  return instance
}

import { makeConsecutiveCache } from '@riavzon/auth'

const consecutiveForIp = makeConsecutiveCache<{ countData: number }>(500, 60_000)
const consecutiveForComposite = makeConsecutiveCache<{ countData: number }>(500, 1800_000)

import { guard } from '@riavzon/auth'
import { getLimiters } from './myEndpointLimiter.js'

export async function myController(req: Request, res: Response) {
  const { uniLimiter, ipLimiter } = getLimiters()
  const log = getLogger().child({ service: 'myApp', branch: 'myEndpoint' })

  // Guard 1: IP
  if (!(await guard(ipLimiter, req.ip!, consecutiveForIp, 2, 'ip', log, res))) return

  // Guard 2: Composite (IP + identity)
  const compositeKey = `${req.ip!}_${email}`
  if (!(await guard(uniLimiter, compositeKey, consecutiveForComposite, 3, 'composite', log, res))) return

  // ... business logic ...

  // On success: clear strikes and reset limiter points
  consecutiveForIp.delete(req.ip!)
  consecutiveForComposite.delete(compositeKey)
  await getLimiters().resetAll(compositeKey)
}

Response Format

When any guard or limiter rejects a request, the service returns:

The Retry-After value is computed as Math.ceil(msBeforeNext / 1000) with a minimum of 1 second. For keys in the global block cache, the value is the block expiration timestamp or the string 'permanent'.

Summary