@frontmcp/guard

Rate limiting, concurrency control, timeout enforcement, and IP filtering for FrontMCP applications. Built on the StorageAdapter interface from @frontmcp/utils, so it works with Memory, Redis, Vercel KV, and Upstash backends out of the box.

Installation

npm install @frontmcp/guard
# or
yarn add @frontmcp/guard

Peer dependency:

npm install zod@^4

Quick Start

import { createGuardManager } from '@frontmcp/guard';

const guard = await createGuardManager({
  config: {
    enabled: true,
    global: { maxRequests: 100, windowMs: 60_000 },
    defaultTimeout: { executeMs: 30_000 },
    ipFilter: {
      denyList: ['10.0.0.0/8'],
      defaultAction: 'allow',
    },
  },
});

// Check IP filter
const ipResult = guard.checkIpFilter('203.0.113.5');

// Check rate limit
const rlResult = await guard.checkRateLimit('my-tool', undefined, {
  sessionId: 'sess-123',
});

// Acquire concurrency slot
const ticket = await guard.acquireSemaphore(
  'my-tool',
  { maxConcurrent: 5 },
  {
    sessionId: 'sess-123',
  },
);
try {
  // ... do work ...
} finally {
  await ticket?.release();
}

Modules

| Module | Main Export | Purpose | | ---------------- | ------------------------------------- | --------------------------------------------------------------------- | | errors/ | GuardError + subclasses | Error hierarchy with machine-readable codes and HTTP status codes | | schemas/ | guardConfigSchema | Zod validation schemas for all configuration objects | | partition-key/ | resolvePartitionKey | Resolves request partition keys (ip, session, userId, global, custom) | | rate-limit/ | SlidingWindowRateLimiter | Sliding window counter rate limiter | | concurrency/ | DistributedSemaphore | Distributed semaphore for concurrency control | | timeout/ | withTimeout | Async execution timeout wrapper | | ip-filter/ | IpFilter | IP allow/deny list filtering with CIDR support | | manager/ | GuardManager + createGuardManager | Orchestrator combining all guard modules |

Rate Limiting

Uses the sliding window counter algorithm. Two adjacent fixed-window counters are maintained; their counts are combined with a time-weighted interpolation to approximate a true sliding window. This provides O(1) storage per key while avoiding the burst edges of simple fixed-window counters.

import { SlidingWindowRateLimiter } from '@frontmcp/guard';

const limiter = new SlidingWindowRateLimiter(storageAdapter);

const result = await limiter.check(
  'user:42', // partition key
  100, // max requests
  60_000, // window in ms
);

if (!result.allowed) {
  console.log(`Rate limited. Retry after ${result.retryAfterMs}ms`);
}

The RateLimitResult includes:

• allowed -- whether the request can proceed
• remaining -- approximate remaining requests in this window
• resetMs -- milliseconds until the current window resets
• retryAfterMs -- (only when blocked) suggested retry delay

Concurrency Control

The DistributedSemaphore limits the number of concurrent executions for a given key. Each execution acquires a "ticket" via atomic incr on a counter key. Individual ticket keys are stored with a TTL for crash safety -- if a process dies without releasing, the ticket TTL expires and the counter self-corrects.

When all slots are full, callers can optionally wait in a queue with exponential backoff polling. If the storage backend supports pub/sub, slot releases trigger immediate wakeup of waiting callers.

import { DistributedSemaphore } from '@frontmcp/guard';

const semaphore = new DistributedSemaphore(storageAdapter, 300 /* ticket TTL seconds */);

const ticket = await semaphore.acquire(
  'my-tool:global', // key
  5, // max concurrent
  10_000, // queue timeout ms (0 = no wait)
  'my-tool', // entity name (for error messages)
);

if (!ticket) {
  // Rejected (queueTimeoutMs was 0 and all slots full)
  return;
}

try {
  await doWork();
} finally {
  await ticket.release();
}

Additional methods:

• getActiveCount(key) -- returns the current number of active tickets
• forceReset(key) -- resets the counter and removes all ticket keys

Timeout

The withTimeout utility wraps an async function with a deadline using AbortController + Promise.race. Throws ExecutionTimeoutError if the function does not complete within the specified duration.

import { withTimeout } from '@frontmcp/guard';

const result = await withTimeout(
  () => fetchData(),
  5_000, // timeout in ms
  'fetch-data', // entity name (for error messages)
);

IP Filtering

The IpFilter class checks client IP addresses against allow and deny lists. Supports individual IP addresses and CIDR notation for both IPv4 and IPv6. IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1) are also handled.

Precedence: the deny list is always checked first. If an IP matches the deny list, it is blocked regardless of the allow list. If an allow list is configured and the IP does not match any allow rule, the defaultAction determines the outcome.

All matching is performed using bigint arithmetic for correctness across the full IPv6 address space.

import { IpFilter } from '@frontmcp/guard';

const filter = new IpFilter({
  allowList: ['192.168.0.0/16'],
  denyList: ['192.168.1.100'],
  defaultAction: 'deny',
});

const result = filter.check('192.168.2.50');
// { allowed: true, reason: 'allowlisted', matchedRule: '192.168.0.0/16' }

const blocked = filter.check('192.168.1.100');
// { allowed: false, reason: 'denylisted', matchedRule: '192.168.1.100' }

The isAllowListed(ip) method provides a quick check for whether an IP is on the allow list, which can be used to bypass rate limiting for trusted addresses.

Partition Keys

Partition keys determine how rate limits and concurrency slots are bucketed. Built-in strategies:

| Strategy | Behavior | | ----------- | --------------------------------------------------------------- | | 'global' | Single shared bucket for all callers (default) | | 'ip' | One bucket per client IP address | | 'session' | One bucket per session ID | | 'userId' | One bucket per authenticated user ID (falls back to session ID) |

You can also pass a custom function:

const config: RateLimitConfig = {
  maxRequests: 100,
  windowMs: 60_000,
  partitionBy: (ctx) => `org:${ctx.userId?.split(':')[0]}`,
};

The PartitionKeyContext passed to custom functions contains sessionId (always present), plus optional clientIp and userId.

Guard Manager

GuardManager is the central orchestrator. It combines rate limiting, concurrency control, IP filtering, and timeout configuration into a single interface. The createGuardManager factory handles storage initialization.

The manager supports two levels of configuration:

• Global -- applied to every request (global, globalConcurrency)
• Default -- applied to entities that do not specify their own config (defaultRateLimit, defaultConcurrency, defaultTimeout)

Per-entity configuration takes precedence over defaults.

import { createGuardManager } from '@frontmcp/guard';

const guard = await createGuardManager({
  config: {
    enabled: true,
    storage: { provider: 'redis', host: 'localhost', port: 6379 },
    keyPrefix: 'myapp:guard:',
    global: { maxRequests: 1000, windowMs: 60_000, partitionBy: 'ip' },
    globalConcurrency: { maxConcurrent: 50, partitionBy: 'global' },
    defaultRateLimit: { maxRequests: 100, windowMs: 60_000, partitionBy: 'session' },
    defaultConcurrency: { maxConcurrent: 10, queueTimeoutMs: 5_000 },
    defaultTimeout: { executeMs: 30_000 },
    ipFilter: {
      denyList: ['10.0.0.0/8'],
      allowList: ['10.0.1.0/24'],
      defaultAction: 'allow',
      trustProxy: true,
      trustedProxyDepth: 2,
    },
  },
  logger: console,
});

// Use the manager
const globalRl = await guard.checkGlobalRateLimit({ sessionId: 'sess-1' });
const entityRl = await guard.checkRateLimit('my-tool', undefined, { sessionId: 'sess-1' });
const ticket = await guard.acquireSemaphore('my-tool', undefined, { sessionId: 'sess-1' });

// Cleanup
await guard.destroy();

Configuration Reference

GuardConfig

| Field | Type | Default | Description | | -------------------- | ------------------- | -------------- | -------------------------------------------------------- | | enabled | boolean | -- | Whether the guard system is active | | storage | StorageConfig | memory | Storage backend configuration | | keyPrefix | string | 'mcp:guard:' | Prefix for all storage keys | | global | RateLimitConfig | -- | Global rate limit for ALL requests | | globalConcurrency | ConcurrencyConfig | -- | Global concurrency limit | | defaultRateLimit | RateLimitConfig | -- | Default rate limit for entities without explicit config | | defaultConcurrency | ConcurrencyConfig | -- | Default concurrency for entities without explicit config | | defaultTimeout | TimeoutConfig | -- | Default timeout for entity execution | | ipFilter | IpFilterConfig | -- | IP filtering configuration |

RateLimitConfig

| Field | Type | Default | Description | | ------------- | -------------- | ---------- | ----------------------------------- | | maxRequests | number | -- | Maximum requests allowed per window | | windowMs | number | 60000 | Time window in milliseconds | | partitionBy | PartitionKey | 'global' | Partition key strategy |

ConcurrencyConfig

| Field | Type | Default | Description | | ---------------- | -------------- | ---------- | ----------------------------------------------- | | maxConcurrent | number | -- | Maximum concurrent executions | | queueTimeoutMs | number | 0 | Max wait time in queue (0 = reject immediately) | | partitionBy | PartitionKey | 'global' | Partition key strategy |

TimeoutConfig

| Field | Type | Default | Description | | ----------- | -------- | ------- | -------------------------------------- | | executeMs | number | -- | Maximum execution time in milliseconds |

IpFilterConfig

| Field | Type | Default | Description | | ------------------- | ------------------- | --------- | ------------------------------------------- | | allowList | string[] | -- | IP addresses or CIDR ranges to always allow | | denyList | string[] | -- | IP addresses or CIDR ranges to always block | | defaultAction | 'allow' \| 'deny' | 'allow' | Action when IP matches neither list | | trustProxy | boolean | false | Trust X-Forwarded-For header | | trustedProxyDepth | number | 1 | Max proxies to trust from X-Forwarded-For |

Storage Backends

The guard library delegates all persistence to the StorageAdapter interface from @frontmcp/utils. Choose a backend based on your deployment:

| Backend | Use Case | | ------------- | ------------------------------------------------------------------------------------------------------------ | | Memory | Development, testing, single-process deployments. Not suitable for distributed setups. | | Redis | Production multi-instance deployments. Provides atomic operations and optional pub/sub for semaphore wakeup. | | Vercel KV | Vercel-hosted applications. Redis-compatible API. | | Upstash | Serverless environments. HTTP-based Redis compatible. |

If no storage config is provided, the factory falls back to in-memory storage and logs a warning.

Error Handling

All errors extend GuardError, which carries a machine-readable code and an HTTP statusCode.

| Error Class | Code | Status | When | | ----------------------- | ------------------- | ------ | ------------------------------------------------------ | | GuardError | (base) | -- | Base class for all guard errors | | ExecutionTimeoutError | EXECUTION_TIMEOUT | 408 | Execution exceeds configured timeout | | ConcurrencyLimitError | CONCURRENCY_LIMIT | 429 | Concurrency limit reached (no queue or queue disabled) | | QueueTimeoutError | QUEUE_TIMEOUT | 429 | Waited in concurrency queue but timed out | | IpBlockedError | IP_BLOCKED | 403 | Client IP is on the deny list | | IpNotAllowedError | IP_NOT_ALLOWED | 403 | Client IP is not on the allow list |

import { GuardError, ExecutionTimeoutError } from '@frontmcp/guard';

try {
  await withTimeout(() => slowOp(), 5_000, 'slow-op');
} catch (err) {
  if (err instanceof ExecutionTimeoutError) {
    console.log(err.code); // 'EXECUTION_TIMEOUT'
    console.log(err.statusCode); // 408
    console.log(err.timeoutMs); // 5000
  }
}

API Reference

Classes

| Export | Module | Description | | -------------------------- | ------------- | ------------------------------------------------ | | SlidingWindowRateLimiter | rate-limit | Sliding window counter rate limiter | | DistributedSemaphore | concurrency | Distributed semaphore with ticket-based tracking | | IpFilter | ip-filter | IP allow/deny list with CIDR support | | GuardManager | manager | Central orchestrator for all guard modules |

Functions

| Export | Module | Description | | --------------------- | --------------- | -------------------------------------------------------- | | withTimeout | timeout | Wrap an async function with a deadline | | resolvePartitionKey | partition-key | Resolve a partition key string from strategy and context | | buildStorageKey | partition-key | Build a namespaced storage key | | createGuardManager | manager | Factory to create and initialize a GuardManager |

Error Classes

| Export | Module | Description | | ----------------------- | -------- | ------------------------- | | GuardError | errors | Base error class | | ExecutionTimeoutError | errors | Timeout exceeded | | ConcurrencyLimitError | errors | Concurrency limit reached | | QueueTimeoutError | errors | Queue wait timed out | | IpBlockedError | errors | IP on deny list | | IpNotAllowedError | errors | IP not on allow list |

Zod Schemas

| Export | Module | Description | | ------------------------- | --------- | --------------------------------------------------- | | partitionKeySchema | schemas | Validates partition key strategy or custom function | | rateLimitConfigSchema | schemas | Validates RateLimitConfig | | concurrencyConfigSchema | schemas | Validates ConcurrencyConfig | | timeoutConfigSchema | schemas | Validates TimeoutConfig | | ipFilterConfigSchema | schemas | Validates IpFilterConfig | | guardConfigSchema | schemas | Validates the full GuardConfig |

Types

| Export | Module | Description | | ------------------------ | --------------- | ------------------------------------------- | | RateLimitConfig | rate-limit | Rate limit configuration | | RateLimitResult | rate-limit | Result from a rate limit check | | ConcurrencyConfig | concurrency | Concurrency control configuration | | SemaphoreTicket | concurrency | Acquired concurrency slot handle | | TimeoutConfig | timeout | Timeout configuration | | IpFilterConfig | ip-filter | IP filter configuration | | IpFilterResult | ip-filter | Result from an IP filter check | | PartitionKeyStrategy | partition-key | Built-in partition key strategies union | | CustomPartitionKeyFn | partition-key | Custom partition key resolver function | | PartitionKeyContext | partition-key | Context passed to partition key resolvers | | PartitionKey | partition-key | Union of strategy string or custom function | | GuardConfig | manager | Full guard configuration | | GuardLogger | manager | Minimal logger interface | | CreateGuardManagerArgs | manager | Arguments for createGuardManager |

License

Apache-2.0