@frontmcp/guard 0.0.1

package/manager/guard.manager.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Guard Manager
+ *
+ * Central coordinator for rate limiting, concurrency control, IP filtering,
+ * and timeout within a scope. SDK-agnostic — built on StorageAdapter.
+ */
+import type { NamespacedStorage } from '@frontmcp/utils';
+import type { GuardConfig } from './types';
+import type { RateLimitConfig, RateLimitResult } from '../rate-limit/types';
+import type { ConcurrencyConfig, SemaphoreTicket } from '../concurrency/types';
+import type { PartitionKeyContext } from '../partition-key/types';
+import type { IpFilterResult } from '../ip-filter/types';
+export declare class GuardManager {
+    private readonly storage;
+    private readonly rateLimiter;
+    private readonly semaphore;
+    private readonly ipFilter?;
+    readonly config: GuardConfig;
+    constructor(storage: NamespacedStorage, config: GuardConfig);
+    /**
+     * Check if a client IP is allowed by the IP filter.
+     * Returns undefined if no IP filter is configured.
+     */
+    checkIpFilter(clientIp: string | undefined): IpFilterResult | undefined;
+    /**
+     * Check if a client IP is on the allow list (bypasses rate limiting).
+     */
+    isIpAllowListed(clientIp: string | undefined): boolean;
+    /**
+     * Check per-entity rate limit.
+     * Merges entity config with app-level defaults (entity takes precedence).
+     */
+    checkRateLimit(entityName: string, entityConfig: RateLimitConfig | undefined, context: PartitionKeyContext | undefined): Promise<RateLimitResult>;
+    /**
+     * Check global rate limit.
+     */
+    checkGlobalRateLimit(context: PartitionKeyContext | undefined): Promise<RateLimitResult>;
+    /**
+     * Acquire a concurrency slot for an entity.
+     */
+    acquireSemaphore(entityName: string, entityConfig: ConcurrencyConfig | undefined, context: PartitionKeyContext | undefined): Promise<SemaphoreTicket | null>;
+    /**
+     * Acquire a global concurrency slot.
+     */
+    acquireGlobalSemaphore(context: PartitionKeyContext | undefined): Promise<SemaphoreTicket | null>;
+    destroy(): Promise<void>;
+}

package/manager/index.d.ts

@@ -0,0 +1,3 @@
+export type { GuardConfig, GuardLogger, CreateGuardManagerArgs } from './types';
+export { GuardManager } from './guard.manager';
+export { createGuardManager } from './guard.factory';

package/manager/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Guard Manager Types
+ */
+import type { StorageConfig } from '@frontmcp/utils';
+import type { RateLimitConfig } from '../rate-limit/types';
+import type { ConcurrencyConfig } from '../concurrency/types';
+import type { TimeoutConfig } from '../timeout/types';
+import type { IpFilterConfig } from '../ip-filter/types';
+/**
+ * Full guard configuration — SDK-agnostic.
+ */
+export interface GuardConfig {
+    /** Whether the guard system is enabled. */
+    enabled: boolean;
+    /** Storage backend. */
+    storage?: StorageConfig;
+    /** Key prefix for all storage keys. @default 'mcp:guard:' */
+    keyPrefix?: string;
+    /** Global rate limit applied to ALL requests. */
+    global?: RateLimitConfig;
+    /** Global concurrency limit. */
+    globalConcurrency?: ConcurrencyConfig;
+    /** Default rate limit for entities without explicit config. */
+    defaultRateLimit?: RateLimitConfig;
+    /** Default concurrency for entities without explicit config. */
+    defaultConcurrency?: ConcurrencyConfig;
+    /** Default timeout for entity execution. */
+    defaultTimeout?: TimeoutConfig;
+    /** IP filtering configuration. */
+    ipFilter?: IpFilterConfig;
+}
+/**
+ * Minimal logger interface — any logger that has info/warn methods.
+ */
+export interface GuardLogger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+}
+/**
+ * Arguments for createGuardManager factory.
+ */
+export interface CreateGuardManagerArgs {
+    config: GuardConfig;
+    logger?: GuardLogger;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@frontmcp/guard",
+  "version": "0.0.1",
+  "description": "Rate limiting, concurrency control, timeout, IP filtering, and traffic guard utilities for FrontMCP",
+  "author": "AgentFront <info@agentfront.dev>",
+  "license": "Apache-2.0",
+  "keywords": [
+    "rate-limiting",
+    "concurrency",
+    "semaphore",
+    "timeout",
+    "ip-filter",
+    "guard",
+    "throttle",
+    "distributed",
+    "redis",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "libs/guard"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/libs/guard/README.md",
+  "type": "commonjs",
+  "main": "./index.js",
+  "module": "./esm/index.mjs",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./esm/index.mjs"
+      }
+    },
+    "./esm": null
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@frontmcp/utils": "1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "zod": "^4.0.0"
+  }
+}

package/partition-key/index.d.ts

@@ -0,0 +1,2 @@
+export type { PartitionKeyStrategy, CustomPartitionKeyFn, PartitionKeyContext, PartitionKey } from './types';
+export { resolvePartitionKey, buildStorageKey } from './partition-key.resolver';

package/partition-key/partition-key.resolver.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Partition Key Resolver
+ *
+ * Resolves a partition key string from a PartitionKey config and context.
+ */
+import type { PartitionKey, PartitionKeyContext } from './types';
+/**
+ * Resolve a partition key string from the given strategy and context.
+ */
+export declare function resolvePartitionKey(partitionBy: PartitionKey | undefined, context: PartitionKeyContext | undefined): string;
+/**
+ * Build a full storage key combining entity name, partition key, and optional suffix.
+ */
+export declare function buildStorageKey(entityName: string, partitionKey: string, suffix?: string): string;

package/partition-key/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Partition Key Types
+ */
+/**
+ * Built-in partition key strategies.
+ * - 'ip': partition by client IP
+ * - 'session': partition by session ID
+ * - 'userId': partition by authenticated user ID
+ * - 'global': no partition — shared limit across all callers
+ */
+export type PartitionKeyStrategy = 'ip' | 'session' | 'userId' | 'global';
+/**
+ * Custom partition key resolver function.
+ */
+export type CustomPartitionKeyFn = (ctx: PartitionKeyContext) => string;
+/**
+ * Context provided to custom partition key resolvers.
+ */
+export interface PartitionKeyContext {
+    sessionId: string;
+    clientIp?: string;
+    userId?: string;
+}
+/**
+ * Partition key configuration — either a built-in strategy or a custom function.
+ */
+export type PartitionKey = PartitionKeyStrategy | CustomPartitionKeyFn;

package/rate-limit/index.d.ts

@@ -0,0 +1,2 @@
+export type { RateLimitConfig, RateLimitResult } from './types';
+export { SlidingWindowRateLimiter } from './rate-limiter';

package/rate-limit/rate-limiter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Sliding Window Rate Limiter
+ *
+ * Implements the sliding window counter algorithm for rate limiting.
+ * Uses two adjacent fixed-window counters with weighted interpolation
+ * to approximate a true sliding window with O(1) storage per check.
+ *
+ * Built entirely on StorageAdapter interface (incr, mget, expire) —
+ * works with Memory, Redis, Vercel KV, Upstash backends.
+ */
+import type { StorageAdapter } from '@frontmcp/utils';
+import type { RateLimitResult } from './types';
+export declare class SlidingWindowRateLimiter {
+    private readonly storage;
+    constructor(storage: StorageAdapter);
+    /**
+     * Check whether a request is allowed under the rate limit.
+     * If allowed, the counter is atomically incremented.
+     */
+    check(key: string, maxRequests: number, windowMs: number): Promise<RateLimitResult>;
+    /**
+     * Reset the rate limit counters for a key.
+     */
+    reset(key: string, windowMs: number): Promise<void>;
+}

package/rate-limit/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Rate Limiting Types
+ */
+import type { PartitionKey } from '../partition-key/types';
+/**
+ * Rate limiting configuration.
+ * Uses sliding window counter algorithm.
+ */
+export interface RateLimitConfig {
+    /** Maximum number of requests allowed within the window. */
+    maxRequests: number;
+    /** Time window in milliseconds. @default 60_000 */
+    windowMs?: number;
+    /** Partition key strategy. @default 'global' */
+    partitionBy?: PartitionKey;
+}
+/**
+ * Result from a rate limiter check.
+ */
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetMs: number;
+    retryAfterMs?: number;
+}

package/schemas/index.d.ts

@@ -0,0 +1 @@
+export { partitionKeySchema, rateLimitConfigSchema, concurrencyConfigSchema, timeoutConfigSchema, ipFilterConfigSchema, guardConfigSchema, } from './schemas';

package/schemas/schemas.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Zod validation schemas for guard configuration.
+ */
+import { z } from 'zod';
+export declare const partitionKeySchema: z.ZodUnion<readonly [z.ZodEnum<{
+    ip: "ip";
+    session: "session";
+    userId: "userId";
+    global: "global";
+}>, z.ZodCustom<(ctx: {
+    sessionId: string;
+    clientIp?: string;
+    userId?: string;
+}) => string, (ctx: {
+    sessionId: string;
+    clientIp?: string;
+    userId?: string;
+}) => string>]>;
+export declare const rateLimitConfigSchema: z.ZodObject<{
+    maxRequests: z.ZodNumber;
+    windowMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        ip: "ip";
+        session: "session";
+        userId: "userId";
+        global: "global";
+    }>, z.ZodCustom<(ctx: {
+        sessionId: string;
+        clientIp?: string;
+        userId?: string;
+    }) => string, (ctx: {
+        sessionId: string;
+        clientIp?: string;
+        userId?: string;
+    }) => string>]>>>;
+}, z.core.$strip>;
+export declare const concurrencyConfigSchema: z.ZodObject<{
+    maxConcurrent: z.ZodNumber;
+    queueTimeoutMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        ip: "ip";
+        session: "session";
+        userId: "userId";
+        global: "global";
+    }>, z.ZodCustom<(ctx: {
+        sessionId: string;
+        clientIp?: string;
+        userId?: string;
+    }) => string, (ctx: {
+        sessionId: string;
+        clientIp?: string;
+        userId?: string;
+    }) => string>]>>>;
+}, z.core.$strip>;
+export declare const timeoutConfigSchema: z.ZodObject<{
+    executeMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ipFilterConfigSchema: z.ZodObject<{
+    allowList: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denyList: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    defaultAction: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>>;
+    trustProxy: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    trustedProxyDepth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const guardConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    storage: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    keyPrefix: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    global: z.ZodOptional<z.ZodObject<{
+        maxRequests: z.ZodNumber;
+        windowMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            ip: "ip";
+            session: "session";
+            userId: "userId";
+            global: "global";
+        }>, z.ZodCustom<(ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string, (ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string>]>>>;
+    }, z.core.$strip>>;
+    globalConcurrency: z.ZodOptional<z.ZodObject<{
+        maxConcurrent: z.ZodNumber;
+        queueTimeoutMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            ip: "ip";
+            session: "session";
+            userId: "userId";
+            global: "global";
+        }>, z.ZodCustom<(ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string, (ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string>]>>>;
+    }, z.core.$strip>>;
+    defaultRateLimit: z.ZodOptional<z.ZodObject<{
+        maxRequests: z.ZodNumber;
+        windowMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            ip: "ip";
+            session: "session";
+            userId: "userId";
+            global: "global";
+        }>, z.ZodCustom<(ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string, (ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string>]>>>;
+    }, z.core.$strip>>;
+    defaultConcurrency: z.ZodOptional<z.ZodObject<{
+        maxConcurrent: z.ZodNumber;
+        queueTimeoutMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        partitionBy: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            ip: "ip";
+            session: "session";
+            userId: "userId";
+            global: "global";
+        }>, z.ZodCustom<(ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string, (ctx: {
+            sessionId: string;
+            clientIp?: string;
+            userId?: string;
+        }) => string>]>>>;
+    }, z.core.$strip>>;
+    defaultTimeout: z.ZodOptional<z.ZodObject<{
+        executeMs: z.ZodNumber;
+    }, z.core.$strip>>;
+    ipFilter: z.ZodOptional<z.ZodObject<{
+        allowList: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denyList: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        defaultAction: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>>;
+        trustProxy: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        trustedProxyDepth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/timeout/index.d.ts

@@ -0,0 +1,2 @@
+export type { TimeoutConfig } from './types';
+export { withTimeout } from './timeout';

package/timeout/timeout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Timeout Utility
+ *
+ * Wraps an async function with a deadline using AbortController + Promise.race.
+ */
+/**
+ * Execute a function with a timeout. Throws ExecutionTimeoutError if exceeded.
+ */
+export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, entityName: string): Promise<T>;

package/timeout/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Timeout Types
+ */
+/**
+ * Timeout configuration.
+ */
+export interface TimeoutConfig {
+    /** Maximum execution time in milliseconds. */
+    executeMs: number;
+}