@frontmcp/guard 0.0.1

package/index.js

@@ -0,0 +1,600 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/guard/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConcurrencyLimitError: () => ConcurrencyLimitError,
+  DistributedSemaphore: () => DistributedSemaphore,
+  ExecutionTimeoutError: () => ExecutionTimeoutError,
+  GuardError: () => GuardError,
+  GuardManager: () => GuardManager,
+  IpBlockedError: () => IpBlockedError,
+  IpFilter: () => IpFilter,
+  IpNotAllowedError: () => IpNotAllowedError,
+  QueueTimeoutError: () => QueueTimeoutError,
+  SlidingWindowRateLimiter: () => SlidingWindowRateLimiter,
+  buildStorageKey: () => buildStorageKey,
+  concurrencyConfigSchema: () => concurrencyConfigSchema,
+  createGuardManager: () => createGuardManager,
+  guardConfigSchema: () => guardConfigSchema,
+  ipFilterConfigSchema: () => ipFilterConfigSchema,
+  partitionKeySchema: () => partitionKeySchema,
+  rateLimitConfigSchema: () => rateLimitConfigSchema,
+  resolvePartitionKey: () => resolvePartitionKey,
+  timeoutConfigSchema: () => timeoutConfigSchema,
+  withTimeout: () => withTimeout
+});
+module.exports = __toCommonJS(index_exports);
+
+// libs/guard/src/errors/errors.ts
+var GuardError = class extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+};
+var ExecutionTimeoutError = class extends GuardError {
+  constructor(entityName, timeoutMs) {
+    super(`Execution of "${entityName}" timed out after ${timeoutMs}ms`, "EXECUTION_TIMEOUT", 408);
+    this.entityName = entityName;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var ConcurrencyLimitError = class extends GuardError {
+  constructor(entityName, maxConcurrent) {
+    super(`Concurrency limit reached for "${entityName}" (max: ${maxConcurrent})`, "CONCURRENCY_LIMIT", 429);
+    this.entityName = entityName;
+    this.maxConcurrent = maxConcurrent;
+  }
+};
+var QueueTimeoutError = class extends GuardError {
+  constructor(entityName, queueTimeoutMs) {
+    super(
+      `Queue timeout for "${entityName}" after waiting ${queueTimeoutMs}ms for a concurrency slot`,
+      "QUEUE_TIMEOUT",
+      429
+    );
+    this.entityName = entityName;
+    this.queueTimeoutMs = queueTimeoutMs;
+  }
+};
+var IpBlockedError = class extends GuardError {
+  constructor(clientIp) {
+    super(`IP address "${clientIp}" is blocked`, "IP_BLOCKED", 403);
+    this.clientIp = clientIp;
+  }
+};
+var IpNotAllowedError = class extends GuardError {
+  constructor(clientIp) {
+    super(`IP address "${clientIp}" is not allowed`, "IP_NOT_ALLOWED", 403);
+    this.clientIp = clientIp;
+  }
+};
+
+// libs/guard/src/schemas/schemas.ts
+var import_zod = require("zod");
+var partitionKeySchema = import_zod.z.union([
+  import_zod.z.enum(["ip", "session", "userId", "global"]),
+  import_zod.z.custom(
+    (val) => typeof val === "function"
+  )
+]);
+var rateLimitConfigSchema = import_zod.z.object({
+  maxRequests: import_zod.z.number().int().positive(),
+  windowMs: import_zod.z.number().int().positive().optional().default(6e4),
+  partitionBy: partitionKeySchema.optional().default("global")
+});
+var concurrencyConfigSchema = import_zod.z.object({
+  maxConcurrent: import_zod.z.number().int().positive(),
+  queueTimeoutMs: import_zod.z.number().int().nonnegative().optional().default(0),
+  partitionBy: partitionKeySchema.optional().default("global")
+});
+var timeoutConfigSchema = import_zod.z.object({
+  executeMs: import_zod.z.number().int().positive()
+});
+var ipFilterConfigSchema = import_zod.z.object({
+  allowList: import_zod.z.array(import_zod.z.string()).optional(),
+  denyList: import_zod.z.array(import_zod.z.string()).optional(),
+  defaultAction: import_zod.z.enum(["allow", "deny"]).optional().default("allow"),
+  trustProxy: import_zod.z.boolean().optional().default(false),
+  trustedProxyDepth: import_zod.z.number().int().positive().optional().default(1)
+});
+var guardConfigSchema = import_zod.z.object({
+  enabled: import_zod.z.boolean(),
+  storage: import_zod.z.looseObject({}).optional(),
+  keyPrefix: import_zod.z.string().optional().default("mcp:guard:"),
+  global: rateLimitConfigSchema.optional(),
+  globalConcurrency: concurrencyConfigSchema.optional(),
+  defaultRateLimit: rateLimitConfigSchema.optional(),
+  defaultConcurrency: concurrencyConfigSchema.optional(),
+  defaultTimeout: timeoutConfigSchema.optional(),
+  ipFilter: ipFilterConfigSchema.optional()
+});
+
+// libs/guard/src/partition-key/partition-key.resolver.ts
+function resolvePartitionKey(partitionBy, context) {
+  if (!partitionBy || partitionBy === "global") {
+    return "global";
+  }
+  const ctx = context ?? { sessionId: "anonymous" };
+  if (typeof partitionBy === "function") {
+    return partitionBy(ctx);
+  }
+  switch (partitionBy) {
+    case "ip":
+      return ctx.clientIp ?? "unknown-ip";
+    case "session":
+      return ctx.sessionId;
+    case "userId":
+      return ctx.userId ?? ctx.sessionId;
+    default:
+      return "global";
+  }
+}
+function buildStorageKey(entityName, partitionKey, suffix) {
+  const parts = [entityName, partitionKey];
+  if (suffix) {
+    parts.push(suffix);
+  }
+  return parts.join(":");
+}
+
+// libs/guard/src/rate-limit/rate-limiter.ts
+var SlidingWindowRateLimiter = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  /**
+   * Check whether a request is allowed under the rate limit.
+   * If allowed, the counter is atomically incremented.
+   */
+  async check(key, maxRequests, windowMs) {
+    const now = Date.now();
+    const currentWindowStart = Math.floor(now / windowMs) * windowMs;
+    const previousWindowStart = currentWindowStart - windowMs;
+    const currentKey = `${key}:${currentWindowStart}`;
+    const previousKey = `${key}:${previousWindowStart}`;
+    const [currentRaw, previousRaw] = await this.storage.mget([currentKey, previousKey]);
+    const currentCount = parseInt(currentRaw ?? "0", 10) || 0;
+    const previousCount = parseInt(previousRaw ?? "0", 10) || 0;
+    const elapsed = now - currentWindowStart;
+    const weight = 1 - elapsed / windowMs;
+    const estimatedCount = previousCount * weight + currentCount;
+    if (estimatedCount >= maxRequests) {
+      return {
+        allowed: false,
+        remaining: 0,
+        resetMs: windowMs - elapsed,
+        retryAfterMs: windowMs - elapsed
+      };
+    }
+    await this.storage.incr(currentKey);
+    const ttlSeconds = Math.ceil(windowMs * 2 / 1e3);
+    await this.storage.expire(currentKey, ttlSeconds);
+    const remaining = Math.max(0, Math.floor(maxRequests - estimatedCount - 1));
+    return {
+      allowed: true,
+      remaining,
+      resetMs: windowMs - elapsed
+    };
+  }
+  /**
+   * Reset the rate limit counters for a key.
+   */
+  async reset(key, windowMs) {
+    const now = Date.now();
+    const currentWindowStart = Math.floor(now / windowMs) * windowMs;
+    const previousWindowStart = currentWindowStart - windowMs;
+    await this.storage.mdelete([`${key}:${currentWindowStart}`, `${key}:${previousWindowStart}`]);
+  }
+};
+
+// libs/guard/src/concurrency/semaphore.ts
+var import_utils = require("@frontmcp/utils");
+var DEFAULT_TICKET_TTL_SECONDS = 300;
+var MIN_POLL_INTERVAL_MS = 100;
+var MAX_POLL_INTERVAL_MS = 1e3;
+var DistributedSemaphore = class {
+  constructor(storage, ticketTtlSeconds = DEFAULT_TICKET_TTL_SECONDS) {
+    this.storage = storage;
+    this.ticketTtlSeconds = ticketTtlSeconds;
+  }
+  /**
+   * Attempt to acquire a concurrency slot.
+   *
+   * @returns A SemaphoreTicket if acquired, or null if rejected
+   * @throws QueueTimeoutError if queued and timeout expires
+   */
+  async acquire(key, maxConcurrent, queueTimeoutMs, entityName) {
+    const ticket = await this.tryAcquire(key, maxConcurrent);
+    if (ticket) return ticket;
+    if (queueTimeoutMs <= 0) return null;
+    return this.waitForSlot(key, maxConcurrent, queueTimeoutMs, entityName);
+  }
+  async tryAcquire(key, maxConcurrent) {
+    const countKey = `${key}:count`;
+    const newCount = await this.storage.incr(countKey);
+    if (newCount <= maxConcurrent) {
+      const ticketId = (0, import_utils.randomUUID)();
+      const ticketKey = `${key}:ticket:${ticketId}`;
+      await this.storage.set(ticketKey, String(Date.now()), {
+        ttlSeconds: this.ticketTtlSeconds
+      });
+      return {
+        ticket: ticketId,
+        release: () => this.release(key, ticketId)
+      };
+    }
+    await this.storage.decr(countKey);
+    return null;
+  }
+  async release(key, ticketId) {
+    const countKey = `${key}:count`;
+    const ticketKey = `${key}:ticket:${ticketId}`;
+    await this.storage.delete(ticketKey);
+    const newCount = await this.storage.decr(countKey);
+    if (newCount < 0) {
+      await this.storage.set(countKey, "0");
+    }
+    if (this.storage.supportsPubSub()) {
+      try {
+        await this.storage.publish(`${key}:released`, ticketId);
+      } catch {
+      }
+    }
+  }
+  async waitForSlot(key, maxConcurrent, queueTimeoutMs, entityName) {
+    const deadline = Date.now() + queueTimeoutMs;
+    let pollInterval = MIN_POLL_INTERVAL_MS;
+    let unsubscribe;
+    let notified = false;
+    if (this.storage.supportsPubSub()) {
+      try {
+        unsubscribe = await this.storage.subscribe(`${key}:released`, () => {
+          notified = true;
+        });
+      } catch {
+      }
+    }
+    try {
+      while (Date.now() < deadline) {
+        const ticket = await this.tryAcquire(key, maxConcurrent);
+        if (ticket) return ticket;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) break;
+        const waitMs = Math.min(pollInterval, remainingMs);
+        if (notified) {
+          notified = false;
+          continue;
+        }
+        await sleep(waitMs);
+        pollInterval = Math.min(pollInterval * 2, MAX_POLL_INTERVAL_MS);
+      }
+    } finally {
+      if (unsubscribe) {
+        try {
+          await unsubscribe();
+        } catch {
+        }
+      }
+    }
+    throw new QueueTimeoutError(entityName, queueTimeoutMs);
+  }
+  async getActiveCount(key) {
+    const countKey = `${key}:count`;
+    const raw = await this.storage.get(countKey);
+    return Math.max(0, parseInt(raw ?? "0", 10) || 0);
+  }
+  async forceReset(key) {
+    const countKey = `${key}:count`;
+    await this.storage.delete(countKey);
+    const ticketKeys = await this.storage.keys(`${key}:ticket:*`);
+    if (ticketKeys.length > 0) {
+      await this.storage.mdelete(ticketKeys);
+    }
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// libs/guard/src/timeout/timeout.ts
+async function withTimeout(fn, timeoutMs, entityName) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await Promise.race([
+      fn(),
+      new Promise((_, reject) => {
+        controller.signal.addEventListener("abort", () => {
+          reject(new ExecutionTimeoutError(entityName, timeoutMs));
+        });
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// libs/guard/src/ip-filter/ip-filter.ts
+var IpFilter = class {
+  constructor(config) {
+    this.allowRules = (config.allowList ?? []).map(parseCidr);
+    this.denyRules = (config.denyList ?? []).map(parseCidr);
+    this.defaultAction = config.defaultAction ?? "allow";
+  }
+  /**
+   * Check if a client IP is allowed.
+   */
+  check(clientIp) {
+    const parsed = parseIp(clientIp);
+    if (parsed === null) {
+      return { allowed: this.defaultAction === "allow", reason: "default" };
+    }
+    for (const rule of this.denyRules) {
+      if (matchesCidr(parsed, rule)) {
+        return { allowed: false, reason: "denylisted", matchedRule: rule.raw };
+      }
+    }
+    if (this.allowRules.length > 0) {
+      for (const rule of this.allowRules) {
+        if (matchesCidr(parsed, rule)) {
+          return { allowed: true, reason: "allowlisted", matchedRule: rule.raw };
+        }
+      }
+      if (this.defaultAction === "deny") {
+        return { allowed: false, reason: "default" };
+      }
+    }
+    return { allowed: this.defaultAction === "allow", reason: "default" };
+  }
+  /**
+   * Check if an IP is on the allow list (bypasses rate limiting).
+   */
+  isAllowListed(clientIp) {
+    const parsed = parseIp(clientIp);
+    if (parsed === null) return false;
+    return this.allowRules.some((rule) => matchesCidr(parsed, rule));
+  }
+};
+function parseIp(ip) {
+  const trimmed = ip.trim();
+  if (trimmed.includes(".") && !trimmed.includes(":")) {
+    const value = parseIpv4(trimmed);
+    if (value === null) return null;
+    return { value, isV6: false };
+  }
+  if (trimmed.includes(":")) {
+    const value = parseIpv6(trimmed);
+    if (value === null) return null;
+    return { value, isV6: true };
+  }
+  return null;
+}
+function parseIpv4(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let result = 0n;
+  for (const part of parts) {
+    const num = parseInt(part, 10);
+    if (isNaN(num) || num < 0 || num > 255) return null;
+    result = result << 8n | BigInt(num);
+  }
+  return result;
+}
+function parseIpv6(ip) {
+  const v4MappedMatch = ip.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (v4MappedMatch) {
+    const v4 = parseIpv4(v4MappedMatch[1]);
+    if (v4 === null) return null;
+    return 0xffff00000000n | v4;
+  }
+  let expanded = ip;
+  if (expanded.includes("::")) {
+    const halves = expanded.split("::");
+    if (halves.length > 2) return null;
+    const left = halves[0] ? halves[0].split(":") : [];
+    const right = halves[1] ? halves[1].split(":") : [];
+    const missing = 8 - left.length - right.length;
+    if (missing < 0) return null;
+    const middle = Array(missing).fill("0");
+    expanded = [...left, ...middle, ...right].join(":");
+  }
+  const groups = expanded.split(":");
+  if (groups.length !== 8) return null;
+  let result = 0n;
+  for (const group of groups) {
+    const num = parseInt(group, 16);
+    if (isNaN(num) || num < 0 || num > 65535) return null;
+    result = result << 16n | BigInt(num);
+  }
+  return result;
+}
+function parseCidr(cidr) {
+  const [ipPart, prefixPart] = cidr.split("/");
+  const parsed = parseIp(ipPart);
+  if (parsed === null) {
+    return { raw: cidr, ip: 0n, mask: 0n, isV6: false, valid: false };
+  }
+  const maxBits = parsed.isV6 ? 128 : 32;
+  const prefixLen = prefixPart !== void 0 ? parseInt(prefixPart, 10) : maxBits;
+  if (isNaN(prefixLen) || prefixLen < 0 || prefixLen > maxBits) {
+    return { raw: cidr, ip: 0n, mask: 0n, isV6: parsed.isV6, valid: false };
+  }
+  const mask = prefixLen === 0 ? 0n : (1n << BigInt(maxBits)) - 1n << BigInt(maxBits - prefixLen);
+  return {
+    raw: cidr,
+    ip: parsed.value & mask,
+    mask,
+    isV6: parsed.isV6,
+    valid: true
+  };
+}
+function matchesCidr(ip, rule) {
+  if (!rule.valid) return false;
+  if (ip.isV6 !== rule.isV6) return false;
+  return (ip.value & rule.mask) === rule.ip;
+}
+
+// libs/guard/src/manager/guard.manager.ts
+var DEFAULT_WINDOW_MS = 6e4;
+var GuardManager = class {
+  constructor(storage, config) {
+    this.storage = storage;
+    this.config = config;
+    this.rateLimiter = new SlidingWindowRateLimiter(storage);
+    this.semaphore = new DistributedSemaphore(storage);
+    if (config.ipFilter) {
+      this.ipFilter = new IpFilter(config.ipFilter);
+    }
+  }
+  // ============================================
+  // IP Filtering
+  // ============================================
+  /**
+   * Check if a client IP is allowed by the IP filter.
+   * Returns undefined if no IP filter is configured.
+   */
+  checkIpFilter(clientIp) {
+    if (!this.ipFilter || !clientIp) return void 0;
+    return this.ipFilter.check(clientIp);
+  }
+  /**
+   * Check if a client IP is on the allow list (bypasses rate limiting).
+   */
+  isIpAllowListed(clientIp) {
+    if (!this.ipFilter || !clientIp) return false;
+    return this.ipFilter.isAllowListed(clientIp);
+  }
+  // ============================================
+  // Rate Limiting
+  // ============================================
+  /**
+   * Check per-entity rate limit.
+   * Merges entity config with app-level defaults (entity takes precedence).
+   */
+  async checkRateLimit(entityName, entityConfig, context) {
+    const config = entityConfig ?? this.config.defaultRateLimit;
+    if (!config) {
+      return { allowed: true, remaining: Infinity, resetMs: 0 };
+    }
+    const partitionKey = resolvePartitionKey(config.partitionBy, context);
+    const storageKey = buildStorageKey(entityName, partitionKey, "rl");
+    const windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    return this.rateLimiter.check(storageKey, config.maxRequests, windowMs);
+  }
+  /**
+   * Check global rate limit.
+   */
+  async checkGlobalRateLimit(context) {
+    const config = this.config.global;
+    if (!config) {
+      return { allowed: true, remaining: Infinity, resetMs: 0 };
+    }
+    const partitionKey = resolvePartitionKey(config.partitionBy, context);
+    const storageKey = buildStorageKey("__global__", partitionKey, "rl");
+    const windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    return this.rateLimiter.check(storageKey, config.maxRequests, windowMs);
+  }
+  // ============================================
+  // Concurrency Control
+  // ============================================
+  /**
+   * Acquire a concurrency slot for an entity.
+   */
+  async acquireSemaphore(entityName, entityConfig, context) {
+    const config = entityConfig ?? this.config.defaultConcurrency;
+    if (!config) return null;
+    const partitionKey = resolvePartitionKey(config.partitionBy, context);
+    const storageKey = buildStorageKey(entityName, partitionKey, "sem");
+    const queueTimeoutMs = config.queueTimeoutMs ?? 0;
+    return this.semaphore.acquire(storageKey, config.maxConcurrent, queueTimeoutMs, entityName);
+  }
+  /**
+   * Acquire a global concurrency slot.
+   */
+  async acquireGlobalSemaphore(context) {
+    const config = this.config.globalConcurrency;
+    if (!config) return null;
+    const partitionKey = resolvePartitionKey(config.partitionBy, context);
+    const storageKey = buildStorageKey("__global__", partitionKey, "sem");
+    const queueTimeoutMs = config.queueTimeoutMs ?? 0;
+    return this.semaphore.acquire(storageKey, config.maxConcurrent, queueTimeoutMs, "__global__");
+  }
+  // ============================================
+  // Lifecycle
+  // ============================================
+  async destroy() {
+    await this.storage.disconnect();
+  }
+};
+
+// libs/guard/src/manager/guard.factory.ts
+var import_utils2 = require("@frontmcp/utils");
+async function createGuardManager(args) {
+  const { config, logger } = args;
+  const keyPrefix = config.keyPrefix ?? "mcp:guard:";
+  let storage;
+  if (config.storage) {
+    storage = await (0, import_utils2.createStorage)(config.storage);
+  } else {
+    logger?.warn(
+      "GuardManager: No storage config provided, using in-memory storage (not suitable for distributed deployments)"
+    );
+    storage = (0, import_utils2.createMemoryStorage)();
+  }
+  await storage.connect();
+  const namespacedStorage = storage.namespace(keyPrefix);
+  logger?.info("GuardManager initialized", {
+    keyPrefix,
+    hasGlobalRateLimit: !!config.global,
+    hasGlobalConcurrency: !!config.globalConcurrency,
+    hasDefaultRateLimit: !!config.defaultRateLimit,
+    hasDefaultConcurrency: !!config.defaultConcurrency,
+    hasDefaultTimeout: !!config.defaultTimeout,
+    hasIpFilter: !!config.ipFilter
+  });
+  return new GuardManager(namespacedStorage, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConcurrencyLimitError,
+  DistributedSemaphore,
+  ExecutionTimeoutError,
+  GuardError,
+  GuardManager,
+  IpBlockedError,
+  IpFilter,
+  IpNotAllowedError,
+  QueueTimeoutError,
+  SlidingWindowRateLimiter,
+  buildStorageKey,
+  concurrencyConfigSchema,
+  createGuardManager,
+  guardConfigSchema,
+  ipFilterConfigSchema,
+  partitionKeySchema,
+  rateLimitConfigSchema,
+  resolvePartitionKey,
+  timeoutConfigSchema,
+  withTimeout
+});

package/ip-filter/index.d.ts

@@ -0,0 +1,2 @@
+export type { IpFilterConfig, IpFilterResult } from './types';
+export { IpFilter } from './ip-filter';

package/ip-filter/ip-filter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * IP Filter
+ *
+ * Allow/deny list with CIDR support for IPv4 and IPv6.
+ * Pure computation — no storage or external dependencies.
+ */
+import type { IpFilterConfig, IpFilterResult } from './types';
+export declare class IpFilter {
+    private readonly allowRules;
+    private readonly denyRules;
+    private readonly defaultAction;
+    constructor(config: IpFilterConfig);
+    /**
+     * Check if a client IP is allowed.
+     */
+    check(clientIp: string): IpFilterResult;
+    /**
+     * Check if an IP is on the allow list (bypasses rate limiting).
+     */
+    isAllowListed(clientIp: string): boolean;
+}

package/ip-filter/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * IP Filter Types
+ */
+/**
+ * IP filtering configuration.
+ */
+export interface IpFilterConfig {
+    /** IP addresses or CIDR ranges to always allow (bypass rate limiting). */
+    allowList?: string[];
+    /** IP addresses or CIDR ranges to always block. */
+    denyList?: string[];
+    /** Default action when IP matches neither list. @default 'allow' */
+    defaultAction?: 'allow' | 'deny';
+    /** Trust X-Forwarded-For header. @default false */
+    trustProxy?: boolean;
+    /** Max number of proxies to trust from X-Forwarded-For. @default 1 */
+    trustedProxyDepth?: number;
+}
+/**
+ * Result of an IP filter check.
+ */
+export interface IpFilterResult {
+    /** Whether the request is allowed to proceed. */
+    allowed: boolean;
+    /** Reason for the decision. */
+    reason?: 'allowlisted' | 'denylisted' | 'default';
+    /** The specific rule that matched (IP or CIDR). */
+    matchedRule?: string;
+}

package/manager/guard.factory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Guard Factory
+ *
+ * SDK-agnostic factory for creating GuardManager instances.
+ * Accepts a StorageConfig from @frontmcp/utils.
+ */
+import type { CreateGuardManagerArgs } from './types';
+import { GuardManager } from './guard.manager';
+/**
+ * Create and initialize a GuardManager with the appropriate storage backend.
+ *
+ * If config.storage is set, uses that directly.
+ * Otherwise falls back to in-memory storage.
+ */
+export declare function createGuardManager(args: CreateGuardManagerArgs): Promise<GuardManager>;