@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/security/rateLimiter.d.ts

@@ -0,0 +1,109 @@
+import { RequestContext } from "../index.js";
+/**
+ * Defines configuration options for the {@link RateLimiter}.
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds. */
+    windowMs: number;
+    /** Maximum number of requests allowed in the window. */
+    maxRequests: number;
+    /** Custom error message template. Can include `{waitTime}` placeholder. */
+    errorMessage?: string;
+    /** If true, skip rate limiting in development. */
+    skipInDevelopment?: boolean;
+    /** Optional function to generate a custom key for rate limiting. */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /** How often, in milliseconds, to clean up expired entries. */
+    cleanupInterval?: number;
+}
+/**
+ * Represents an individual entry for tracking requests against a rate limit key.
+ */
+export interface RateLimitEntry {
+    /** Current request count. */
+    count: number;
+    /** When the window resets (timestamp in milliseconds). */
+    resetTime: number;
+}
+/**
+ * A generic rate limiter class using an in-memory store.
+ * Controls frequency of operations based on unique keys.
+ */
+export declare class RateLimiter {
+    private config;
+    /**
+     * Stores current request counts and reset times for each key.
+     * @private
+     */
+    private limits;
+    /**
+     * Timer ID for periodic cleanup.
+     * @private
+     */
+    private cleanupTimer;
+    /**
+     * Default configuration values.
+     * @private
+     */
+    private static DEFAULT_CONFIG;
+    /**
+     * Creates a new `RateLimiter` instance.
+     * @param config - Configuration options, merged with defaults.
+     */
+    constructor(config: RateLimitConfig);
+    /**
+     * Starts the periodic timer to clean up expired rate limit entries.
+     * @private
+     */
+    private startCleanupTimer;
+    /**
+     * Removes expired rate limit entries from the store.
+     * @private
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Updates the configuration of the rate limiter instance.
+     * @param config - New configuration options to merge.
+     */
+    configure(config: Partial<RateLimitConfig>): void;
+    /**
+     * Retrieves a copy of the current rate limiter configuration.
+     * @returns The current configuration.
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Resets all rate limits by clearing the internal store.
+     */
+    reset(): void;
+    /**
+     * Checks if a request exceeds the configured rate limit.
+     * Throws an `McpError` if the limit is exceeded.
+     *
+     * @param key - A unique identifier for the request source.
+     * @param context - Optional request context for custom key generation.
+     * @throws {McpError} If the rate limit is exceeded.
+     */
+    check(key: string, context?: RequestContext): void;
+    /**
+     * Retrieves the current rate limit status for a specific key.
+     * @param key - The rate limit key.
+     * @returns Status object or `null` if no entry exists.
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stops the cleanup timer and clears all rate limit entries.
+     * Call when the rate limiter is no longer needed.
+     */
+    dispose(): void;
+}
+/**
+ * Default singleton instance of the `RateLimiter`.
+ * Initialized with default configuration. Use `rateLimiter.configure({})` to customize.
+ */
+export declare const rateLimiter: RateLimiter;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/utils/security/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../src/utils/security/rateLimiter.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,MAAM,CAAC;IACxE,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,WAAW;IA6BV,OAAO,CAAC,MAAM;IA5B1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA8B;IAC5C;;;OAGG;IACH,OAAO,CAAC,YAAY,CAA+B;IAEnD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc,CAO3B;IAEF;;;OAGG;gBACiB,MAAM,EAAE,eAAe;IAM3C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAwB7B;;;OAGG;IACI,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI;IAOxD;;;OAGG;IACI,SAAS,IAAI,eAAe;IAInC;;OAEG;IACI,KAAK,IAAI,IAAI;IAQpB;;;;;;;OAOG;IACI,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI;IAqDzD;;;;OAIG;IACI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;QAC7B,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAaR;;;OAGG;IACI,OAAO,IAAI,IAAI;CAOvB;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,aAGtB,CAAC"}

package/dist/utils/security/rateLimiter.js

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Provides a generic `RateLimiter` class for implementing rate limiting logic.
+ * It supports configurable time windows, request limits, and automatic cleanup of expired entries.
+ * @module src/utils/security/rateLimiter
+ */
+import { trace } from "@opentelemetry/api";
+import { environment } from "../../config/index.js";
+import { JsonRpcErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService, } from "../index.js";
+/**
+ * A generic rate limiter class using an in-memory store.
+ * Controls frequency of operations based on unique keys.
+ */
+export class RateLimiter {
+    config;
+    /**
+     * Stores current request counts and reset times for each key.
+     * @private
+     */
+    limits;
+    /**
+     * Timer ID for periodic cleanup.
+     * @private
+     */
+    cleanupTimer = null;
+    /**
+     * Default configuration values.
+     * @private
+     */
+    static DEFAULT_CONFIG = {
+        windowMs: 15 * 60 * 1000, // 15 minutes
+        maxRequests: 100,
+        errorMessage: "Rate limit exceeded. Please try again in {waitTime} seconds.",
+        skipInDevelopment: false,
+        cleanupInterval: 5 * 60 * 1000, // 5 minutes
+    };
+    /**
+     * Creates a new `RateLimiter` instance.
+     * @param config - Configuration options, merged with defaults.
+     */
+    constructor(config) {
+        this.config = config;
+        this.config = { ...RateLimiter.DEFAULT_CONFIG, ...config };
+        this.limits = new Map();
+        this.startCleanupTimer();
+    }
+    /**
+     * Starts the periodic timer to clean up expired rate limit entries.
+     * @private
+     */
+    startCleanupTimer() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        const interval = this.config.cleanupInterval ?? RateLimiter.DEFAULT_CONFIG.cleanupInterval;
+        if (interval && interval > 0) {
+            this.cleanupTimer = setInterval(() => {
+                this.cleanupExpiredEntries();
+            }, interval);
+            if (this.cleanupTimer.unref) {
+                this.cleanupTimer.unref(); // Allow Node.js process to exit if only timer active
+            }
+        }
+    }
+    /**
+     * Removes expired rate limit entries from the store.
+     * @private
+     */
+    cleanupExpiredEntries() {
+        const now = Date.now();
+        let expiredCount = 0;
+        for (const [key, entry] of this.limits.entries()) {
+            if (now >= entry.resetTime) {
+                this.limits.delete(key);
+                expiredCount++;
+            }
+        }
+        if (expiredCount > 0) {
+            const logContext = requestContextService.createRequestContext({
+                operation: "RateLimiter.cleanupExpiredEntries",
+                cleanedCount: expiredCount,
+                totalRemainingAfterClean: this.limits.size,
+            });
+            logger.debug(logContext, `Cleaned up ${expiredCount} expired rate limit entries`);
+        }
+    }
+    /**
+     * Updates the configuration of the rate limiter instance.
+     * @param config - New configuration options to merge.
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+        if (config.cleanupInterval !== undefined) {
+            this.startCleanupTimer();
+        }
+    }
+    /**
+     * Retrieves a copy of the current rate limiter configuration.
+     * @returns The current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Resets all rate limits by clearing the internal store.
+     */
+    reset() {
+        this.limits.clear();
+        const logContext = requestContextService.createRequestContext({
+            operation: "RateLimiter.reset",
+        });
+        logger.debug(logContext, "Rate limiter reset, all limits cleared");
+    }
+    /**
+     * Checks if a request exceeds the configured rate limit.
+     * Throws an `McpError` if the limit is exceeded.
+     *
+     * @param key - A unique identifier for the request source.
+     * @param context - Optional request context for custom key generation.
+     * @throws {McpError} If the rate limit is exceeded.
+     */
+    check(key, context) {
+        const activeSpan = trace.getActiveSpan();
+        activeSpan?.setAttribute("mcp.rate_limit.checked", true);
+        if (this.config.skipInDevelopment && environment === "development") {
+            activeSpan?.setAttribute("mcp.rate_limit.skipped", "development");
+            return;
+        }
+        const limitKey = this.config.keyGenerator
+            ? this.config.keyGenerator(key, context)
+            : key;
+        activeSpan?.setAttribute("mcp.rate_limit.key", limitKey);
+        const now = Date.now();
+        let entry = this.limits.get(limitKey);
+        if (!entry || now >= entry.resetTime) {
+            entry = {
+                count: 1,
+                resetTime: now + this.config.windowMs,
+            };
+            this.limits.set(limitKey, entry);
+        }
+        else {
+            entry.count++;
+        }
+        const remaining = Math.max(0, this.config.maxRequests - entry.count);
+        activeSpan?.setAttributes({
+            "mcp.rate_limit.limit": this.config.maxRequests,
+            "mcp.rate_limit.count": entry.count,
+            "mcp.rate_limit.remaining": remaining,
+        });
+        if (entry.count > this.config.maxRequests) {
+            const waitTime = Math.ceil((entry.resetTime - now) / 1000);
+            const errorMessage = (this.config.errorMessage || RateLimiter.DEFAULT_CONFIG.errorMessage).replace("{waitTime}", waitTime.toString());
+            activeSpan?.addEvent("rate_limit_exceeded", {
+                "mcp.rate_limit.wait_time_seconds": waitTime,
+            });
+            throw new McpError(JsonRpcErrorCode.RateLimited, errorMessage, {
+                waitTimeSeconds: waitTime,
+                key: limitKey,
+                limit: this.config.maxRequests,
+                windowMs: this.config.windowMs,
+            });
+        }
+    }
+    /**
+     * Retrieves the current rate limit status for a specific key.
+     * @param key - The rate limit key.
+     * @returns Status object or `null` if no entry exists.
+     */
+    getStatus(key) {
+        const entry = this.limits.get(key);
+        if (!entry) {
+            return null;
+        }
+        return {
+            current: entry.count,
+            limit: this.config.maxRequests,
+            remaining: Math.max(0, this.config.maxRequests - entry.count),
+            resetTime: entry.resetTime,
+        };
+    }
+    /**
+     * Stops the cleanup timer and clears all rate limit entries.
+     * Call when the rate limiter is no longer needed.
+     */
+    dispose() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.limits.clear();
+    }
+}
+/**
+ * Default singleton instance of the `RateLimiter`.
+ * Initialized with default configuration. Use `rateLimiter.configure({})` to customize.
+ */
+export const rateLimiter = new RateLimiter({
+    windowMs: 15 * 60 * 1000, // Default: 15 minutes
+    maxRequests: 100, // Default: 100 requests per window
+});
+//# sourceMappingURL=rateLimiter.js.map

package/dist/utils/security/rateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.js","sourceRoot":"","sources":["../../../src/utils/security/rateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EACL,MAAM,EAEN,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AA8B1B;;;GAGG;AACH,MAAM,OAAO,WAAW;IA6BF;IA5BpB;;;OAGG;IACK,MAAM,CAA8B;IAC5C;;;OAGG;IACK,YAAY,GAA0B,IAAI,CAAC;IAEnD;;;OAGG;IACK,MAAM,CAAC,cAAc,GAAoB;QAC/C,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;QACvC,WAAW,EAAE,GAAG;QAChB,YAAY,EACV,8DAA8D;QAChE,iBAAiB,EAAE,KAAK;QACxB,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,YAAY;KAC7C,CAAC;IAEF;;;OAGG;IACH,YAAoB,MAAuB;QAAvB,WAAM,GAAN,MAAM,CAAiB;QACzC,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,WAAW,CAAC,cAAc,EAAE,GAAG,MAAM,EAAE,CAAC;QAC3D,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,iBAAiB,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACK,iBAAiB;QACvB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,QAAQ,GACZ,IAAI,CAAC,MAAM,CAAC,eAAe,IAAI,WAAW,CAAC,cAAc,CAAC,eAAe,CAAC;QAE5E,IAAI,QAAQ,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE;gBACnC,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAC/B,CAAC,EAAE,QAAQ,CAAC,CAAC;YAEb,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;gBAC5B,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,qDAAqD;YAClF,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,qBAAqB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YACjD,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACxB,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,UAAU,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;gBAC5D,SAAS,EAAE,mCAAmC;gBAC9C,YAAY,EAAE,YAAY;gBAC1B,wBAAwB,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;aAC3C,CAAC,CAAC;YACH,MAAM,CAAC,KAAK,CACV,UAAU,EACV,cAAc,YAAY,6BAA6B,CACxD,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,MAAgC;QAC/C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;QAC5C,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAED;;;OAGG;IACI,SAAS;QACd,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,UAAU,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YAC5D,SAAS,EAAE,mBAAmB;SAC/B,CAAC,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,wCAAwC,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,GAAW,EAAE,OAAwB;QAChD,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC;QACzC,UAAU,EAAE,YAAY,CAAC,wBAAwB,EAAE,IAAI,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,MAAM,CAAC,iBAAiB,IAAI,WAAW,KAAK,aAAa,EAAE,CAAC;YACnE,UAAU,EAAE,YAAY,CAAC,wBAAwB,EAAE,aAAa,CAAC,CAAC;YAClE,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY;YACvC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC;YACxC,CAAC,CAAC,GAAG,CAAC;QACR,UAAU,EAAE,YAAY,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;QAEzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEtC,IAAI,CAAC,KAAK,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;YACrC,KAAK,GAAG;gBACN,KAAK,EAAE,CAAC;gBACR,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ;aACtC,CAAC;YACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACrE,UAAU,EAAE,aAAa,CAAC;YACxB,sBAAsB,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YAC/C,sBAAsB,EAAE,KAAK,CAAC,KAAK;YACnC,0BAA0B,EAAE,SAAS;SACtC,CAAC,CAAC;QAEH,IAAI,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YAC3D,MAAM,YAAY,GAAG,CACnB,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,WAAW,CAAC,cAAc,CAAC,YAAa,CACrE,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;YAE7C,UAAU,EAAE,QAAQ,CAAC,qBAAqB,EAAE;gBAC1C,kCAAkC,EAAE,QAAQ;aAC7C,CAAC,CAAC;YAEH,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,WAAW,EAAE,YAAY,EAAE;gBAC7D,eAAe,EAAE,QAAQ;gBACzB,GAAG,EAAE,QAAQ;gBACb,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBAC9B,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;aAC/B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,SAAS,CAAC,GAAW;QAM1B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,KAAK;YACpB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YAC9B,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;YAC7D,SAAS,EAAE,KAAK,CAAC,SAAS;SAC3B,CAAC;IACJ,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC;IACzC,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,sBAAsB;IAChD,WAAW,EAAE,GAAG,EAAE,mCAAmC;CACtD,CAAC,CAAC"}

package/dist/utils/security/sanitization.d.ts

@@ -0,0 +1,185 @@
+import sanitizeHtml from "sanitize-html";
+/**
+ * Defines options for path sanitization to control how file paths are processed and validated.
+ */
+export interface PathSanitizeOptions {
+    /** If provided, restricts sanitized paths to be relative to this directory. */
+    rootDir?: string;
+    /** If true, normalizes Windows backslashes to POSIX forward slashes. */
+    toPosix?: boolean;
+    /** If true, absolute paths are permitted (subject to `rootDir`). Default: false. */
+    allowAbsolute?: boolean;
+}
+/**
+ * Contains information about a path sanitization operation.
+ */
+export interface SanitizedPathInfo {
+    /** The final sanitized and normalized path string. */
+    sanitizedPath: string;
+    /** The original path string before any processing. */
+    originalInput: string;
+    /** True if the input path was absolute after initial normalization. */
+    wasAbsolute: boolean;
+    /** True if an absolute path was converted to relative due to `allowAbsolute: false`. */
+    convertedToRelative: boolean;
+    /** The effective options used for sanitization, including defaults. */
+    optionsUsed: PathSanitizeOptions;
+}
+/**
+ * Defines options for context-specific string sanitization.
+ */
+export interface SanitizeStringOptions {
+    /** The context in which the string will be used. 'javascript' is disallowed. */
+    context?: "text" | "html" | "attribute" | "url" | "javascript";
+    /** Custom allowed HTML tags if `context` is 'html'. */
+    allowedTags?: string[];
+    /** Custom allowed HTML attributes if `context` is 'html'. */
+    allowedAttributes?: Record<string, string[]>;
+}
+/**
+ * Configuration options for HTML sanitization, mirroring `sanitize-html` library options.
+ */
+export interface HtmlSanitizeConfig {
+    /** An array of allowed HTML tag names. */
+    allowedTags?: string[];
+    /** Specifies allowed attributes, either globally or per tag. */
+    allowedAttributes?: sanitizeHtml.IOptions["allowedAttributes"];
+    /** If true, HTML comments are preserved. */
+    preserveComments?: boolean;
+    /** Custom functions to transform tags during sanitization. */
+    transformTags?: sanitizeHtml.IOptions["transformTags"];
+}
+/**
+ * A singleton class providing various methods for input sanitization.
+ * Aims to protect against common vulnerabilities like XSS and path traversal.
+ */
+export declare class Sanitization {
+    /** @private */
+    private static instance;
+    /**
+     * Default list of field names considered sensitive for log redaction.
+     * Case-insensitive matching is applied.
+     * @private
+     */
+    private sensitiveFields;
+    /**
+     * Default configuration for HTML sanitization.
+     * @private
+     */
+    private defaultHtmlSanitizeConfig;
+    /** @private */
+    private constructor();
+    /**
+     * Retrieves the singleton instance of the `Sanitization` class.
+     * @returns The singleton `Sanitization` instance.
+     */
+    static getInstance(): Sanitization;
+    /**
+     * Sets or extends the list of sensitive field names for log sanitization.
+     * @param fields - An array of field names to add to the sensitive list.
+     */
+    setSensitiveFields(fields: string[]): void;
+    /**
+     * Gets a copy of the current list of sensitive field names.
+     * @returns An array of sensitive field names.
+     */
+    getSensitiveFields(): string[];
+    /**
+     * Sanitizes an HTML string by removing potentially malicious tags and attributes.
+     * @param input - The HTML string to sanitize.
+     * @param config - Optional custom configuration for `sanitize-html`.
+     * @returns The sanitized HTML string. Returns an empty string if input is falsy.
+     */
+    sanitizeHtml(input: string, config?: HtmlSanitizeConfig): string;
+    /**
+     * Sanitizes a string based on its intended context (e.g., HTML, URL, text).
+     * **Important:** `context: 'javascript'` is disallowed due to security risks.
+     *
+     * @param input - The string to sanitize.
+     * @param options - Options specifying the sanitization context.
+     * @returns The sanitized string. Returns an empty string if input is falsy.
+     * @throws {McpError} If `options.context` is 'javascript', or URL validation fails.
+     */
+    sanitizeString(input: string, options?: SanitizeStringOptions): string;
+    /**
+     * Converts attribute format for `sanitizeHtml`.
+     * @param attrs - Attributes in `{ tagName: ['attr1'] }` format.
+     * @returns Attributes in `sanitize-html` expected format.
+     * @private
+     */
+    private convertAttributesFormat;
+    /**
+     * Sanitizes a URL string by validating its format and protocol.
+     * @param input - The URL string to sanitize.
+     * @param allowedProtocols - Array of allowed URL protocols. Default: `['http', 'https']`.
+     * @returns The sanitized and trimmed URL string.
+     * @throws {McpError} If the URL is invalid or uses a disallowed protocol.
+     */
+    sanitizeUrl(input: string, allowedProtocols?: string[]): string;
+    /**
+     * Sanitizes a file path to prevent path traversal and normalize format.
+     * @param input - The file path string to sanitize.
+     * @param options - Options to control sanitization behavior.
+     * @returns An object with the sanitized path and sanitization metadata.
+     * @throws {McpError} If the path is invalid or unsafe.
+     */
+    sanitizePath(input: string, options?: PathSanitizeOptions): SanitizedPathInfo;
+    /**
+     * Sanitizes a JSON string by parsing it to validate its format.
+     * Optionally checks if the JSON string exceeds a maximum allowed size.
+     * @template T The expected type of the parsed JSON object. Defaults to `unknown`.
+     * @param input - The JSON string to sanitize/validate.
+     * @param maxSize - Optional maximum allowed size of the JSON string in bytes.
+     * @returns The parsed JavaScript object.
+     * @throws {McpError} If input is not a string, too large, or invalid JSON.
+     */
+    sanitizeJson<T = unknown>(input: string, maxSize?: number): T;
+    /**
+     * Validates and sanitizes a numeric input, converting strings to numbers.
+     * Clamps the number to `min`/`max` if provided.
+     * @param input - The number or string to validate and sanitize.
+     * @param min - Minimum allowed value (inclusive).
+     * @param max - Maximum allowed value (inclusive).
+     * @returns The sanitized (and potentially clamped) number.
+     * @throws {McpError} If input is not a valid number, NaN, or Infinity.
+     */
+    sanitizeNumber(input: number | string, min?: number, max?: number): number;
+    /**
+     * Sanitizes input for logging by redacting sensitive fields.
+     * Creates a deep clone and replaces values of fields matching `this.sensitiveFields`
+     * (case-insensitive substring match) with "[REDACTED]".
+     *
+     * It uses `structuredClone` if available for a high-fidelity deep clone.
+     * If `structuredClone` is not available (e.g., in older Node.js environments),
+     * it falls back to `JSON.parse(JSON.stringify(input))`. This fallback has limitations:
+     * - `Date` objects are converted to ISO date strings.
+     * - `undefined` values within objects are removed.
+     * - `Map`, `Set`, `RegExp` objects are converted to empty objects (`{}`).
+     * - Functions are removed.
+     * - `BigInt` values will throw an error during `JSON.stringify` unless a `toJSON` method is provided.
+     * - Circular references will cause `JSON.stringify` to throw an error.
+     *
+     * @param input - The input data to sanitize for logging.
+     * @returns A sanitized (deep cloned) version of the input, safe for logging.
+     *   Returns original input if not object/array, or "[Log Sanitization Failed]" on error.
+     */
+    sanitizeForLogging(input: unknown): unknown;
+    /**
+     * Recursively redacts sensitive fields in an object or array in place.
+     * @param obj - The object or array to redact.
+     * @private
+     */
+    private redactSensitiveFields;
+}
+/**
+ * Singleton instance of the `Sanitization` class.
+ * Use this for all input sanitization tasks.
+ */
+export declare const sanitization: Sanitization;
+/**
+ * Convenience function calling `sanitization.sanitizeForLogging`.
+ * @param input - The input data to sanitize.
+ * @returns A sanitized version of the input, safe for logging.
+ */
+export declare const sanitizeInputForLogging: (input: unknown) => unknown;
+//# sourceMappingURL=sanitization.d.ts.map

package/dist/utils/security/sanitization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitization.d.ts","sourceRoot":"","sources":["../../../src/utils/security/sanitization.ts"],"names":[],"mappings":"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"}