obsidian-mcp-server 2.0.7 → 3.1.0

package/dist/utils/security/rateLimiter.js

@@ -1,235 +0,0 @@
-/**
- * @fileoverview Provides a generic rate limiter class to manage request rates
- * based on configurable time windows and request counts. It supports custom
- * key generation, periodic cleanup of expired entries, and skipping rate
- * limiting in development environments.
- * @module src/utils/security/rateLimiter
- */
-import { BaseErrorCode, McpError } from "../../types-global/errors.js";
-import { environment } from "../../config/index.js";
-import { logger, requestContextService, } from "../internal/index.js"; // Use internal index for RequestContext
-/**
- * A generic rate limiter class that can be used to control the frequency of
- * operations or requests from various sources. It stores request counts in memory.
- */
-export class RateLimiter {
-    /**
-     * Creates a new `RateLimiter` instance.
-     * @param {Partial<RateLimitConfig>} [initialConfig={}] - Optional initial configuration
-     *   to override default settings.
-     */
-    constructor(initialConfig = {}) {
-        this.cleanupTimer = null;
-        this.currentConfig = { ...RateLimiter.DEFAULT_CONFIG, ...initialConfig };
-        this.limits = new Map();
-        this.startCleanupTimer();
-        // Initial log message about instantiation can be done by the code that creates the singleton instance,
-        // after logger itself is fully initialized.
-    }
-    /**
-     * Starts the periodic cleanup timer for expired rate limit entries.
-     * If a timer already exists, it's cleared and restarted.
-     * @private
-     */
-    startCleanupTimer() {
-        if (this.cleanupTimer) {
-            clearInterval(this.cleanupTimer);
-            this.cleanupTimer = null;
-        }
-        const interval = this.currentConfig.cleanupInterval;
-        if (interval && interval > 0) {
-            this.cleanupTimer = setInterval(() => {
-                this.cleanupExpiredEntries();
-            }, interval);
-            // Allow Node.js to exit if this timer is the only thing running.
-            if (this.cleanupTimer.unref) {
-                this.cleanupTimer.unref();
-            }
-        }
-    }
-    /**
-     * Removes expired entries from the rate limit store to free up memory.
-     * This method is called periodically by the cleanup timer.
-     * @private
-     */
-    cleanupExpiredEntries() {
-        const now = Date.now();
-        let expiredCount = 0;
-        const internalContext = requestContextService.createRequestContext({
-            operation: "RateLimiter.cleanupExpiredEntries",
-        });
-        for (const [key, entry] of this.limits.entries()) {
-            if (now >= entry.resetTime) {
-                this.limits.delete(key);
-                expiredCount++;
-            }
-        }
-        if (expiredCount > 0) {
-            logger.debug(`Cleaned up ${expiredCount} expired rate limit entries.`, {
-                ...internalContext,
-                totalRemaining: this.limits.size,
-            });
-        }
-    }
-    /**
-     * Updates the rate limiter's configuration.
-     * @param {Partial<RateLimitConfig>} newConfig - Partial configuration object
-     *   with new settings to apply.
-     */
-    configure(newConfig) {
-        const oldCleanupInterval = this.currentConfig.cleanupInterval;
-        this.currentConfig = { ...this.currentConfig, ...newConfig };
-        if (newConfig.cleanupInterval !== undefined &&
-            newConfig.cleanupInterval !== oldCleanupInterval) {
-            this.startCleanupTimer(); // Restart timer if interval changed
-        }
-        // Consider logging configuration changes if needed, using a RequestContext.
-    }
-    /**
-     * Retrieves a copy of the current rate limiter configuration.
-     * @returns {RateLimitConfig} The current configuration.
-     */
-    getConfig() {
-        return { ...this.currentConfig };
-    }
-    /**
-     * Resets all rate limits, clearing all tracked keys and their counts.
-     * @param {RequestContext} [context] - Optional context for logging the reset operation.
-     */
-    reset(context) {
-        this.limits.clear();
-        const opContext = context ||
-            requestContextService.createRequestContext({
-                operation: "RateLimiter.reset",
-            });
-        logger.info("Rate limiter has been reset. All limits cleared.", opContext);
-    }
-    /**
-     * Checks if a request identified by a key exceeds the configured rate limit.
-     * If the limit is exceeded, an `McpError` is thrown.
-     *
-     * @param {string} identifier - A unique string identifying the source of the request
-     *   (e.g., IP address, user ID, session ID).
-     * @param {RequestContext} [context] - Optional request context for logging and potentially
-     *   for use by a custom `keyGenerator`.
-     * @throws {McpError} If the rate limit is exceeded for the given key.
-     *   The error will have `BaseErrorCode.RATE_LIMITED`.
-     */
-    check(identifier, context) {
-        const opContext = context ||
-            requestContextService.createRequestContext({
-                operation: "RateLimiter.check",
-                identifier,
-            });
-        if (this.currentConfig.skipInDevelopment && environment === "development") {
-            logger.debug(`Rate limiting skipped for key "${identifier}" in development environment.`, opContext);
-            return;
-        }
-        const limitKey = this.currentConfig.keyGenerator
-            ? this.currentConfig.keyGenerator(identifier, opContext)
-            : identifier;
-        const now = Date.now();
-        const entry = this.limits.get(limitKey);
-        if (!entry || now >= entry.resetTime) {
-            // New entry or expired window
-            this.limits.set(limitKey, {
-                count: 1,
-                resetTime: now + this.currentConfig.windowMs,
-            });
-            return; // First request in window, allow
-        }
-        // Window is active, check count
-        if (entry.count >= this.currentConfig.maxRequests) {
-            const waitTimeSeconds = Math.ceil((entry.resetTime - now) / 1000);
-            const errorMessageTemplate = this.currentConfig.errorMessage ||
-                RateLimiter.DEFAULT_CONFIG.errorMessage;
-            const errorMessage = errorMessageTemplate.replace("{waitTime}", waitTimeSeconds.toString());
-            logger.warning(`Rate limit exceeded for key "${limitKey}".`, {
-                ...opContext,
-                limitKey,
-                count: entry.count,
-                maxRequests: this.currentConfig.maxRequests,
-                resetTime: new Date(entry.resetTime).toISOString(),
-                waitTimeSeconds,
-            });
-            throw new McpError(BaseErrorCode.RATE_LIMITED, errorMessage, { ...opContext, keyUsed: limitKey, waitTime: waitTimeSeconds });
-        }
-        // Increment count and update entry
-        entry.count++;
-        // No need to this.limits.set(limitKey, entry) again if entry is a reference to the object in the map.
-    }
-    /**
-     * Retrieves the current rate limit status for a given key.
-     * @param {string} key - The rate limit key (as generated by `keyGenerator` or the raw identifier).
-     * @returns {{ current: number; limit: number; remaining: number; resetTime: number } | null}
-     *   An object with current status, or `null` if the key is not currently tracked (or has expired).
-     *   `resetTime` is a Unix timestamp (milliseconds).
-     */
-    getStatus(key) {
-        const entry = this.limits.get(key);
-        if (!entry || Date.now() >= entry.resetTime) {
-            // Also consider expired as not found for status
-            return null;
-        }
-        return {
-            current: entry.count,
-            limit: this.currentConfig.maxRequests,
-            remaining: Math.max(0, this.currentConfig.maxRequests - entry.count),
-            resetTime: entry.resetTime,
-        };
-    }
-    /**
-     * Stops the cleanup timer and clears all rate limit entries.
-     * This should be called if the rate limiter instance is no longer needed,
-     * to prevent resource leaks (though `unref` on the timer helps).
-     * @param {RequestContext} [context] - Optional context for logging the disposal.
-     */
-    dispose(context) {
-        if (this.cleanupTimer) {
-            clearInterval(this.cleanupTimer);
-            this.cleanupTimer = null;
-        }
-        this.limits.clear();
-        const opContext = context ||
-            requestContextService.createRequestContext({
-                operation: "RateLimiter.dispose",
-            });
-        logger.info("Rate limiter disposed, cleanup timer stopped and limits cleared.", opContext);
-    }
-}
-/**
- * Default configuration values for the rate limiter.
- */
-RateLimiter.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
-};
-/**
- * A default, shared instance of the `RateLimiter`.
- * This instance is configured with default settings (e.g., 100 requests per 15 minutes).
- * It can be reconfigured using `rateLimiter.configure()`.
- *
- * Example:
- * ```typescript
- * import { rateLimiter, RequestContext } from './rateLimiter';
- * import { requestContextService } from '../internal';
- *
- * const context: RequestContext = requestContextService.createRequestContext({ operation: 'MyApiCall' });
- * const userIp = '123.45.67.89';
- *
- * try {
- *   rateLimiter.check(userIp, context);
- *   // Proceed with operation
- * } catch (e) {
- *   if (e instanceof McpError && e.code === BaseErrorCode.RATE_LIMITED) {
- *     console.error("Rate limit hit:", e.message);
- *   } else {
- *     // Handle other errors
- *   }
- * }
- * ```
- */
-export const rateLimiter = new RateLimiter({}); // Initialize with default or empty to use class defaults

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

@@ -1,244 +0,0 @@
-/**
- * @fileoverview Provides a comprehensive sanitization utility class for various input types,
- * including HTML, strings, URLs, file paths, JSON, and numbers. It also includes
- * functionality for redacting sensitive information from objects for safe logging.
- * @module src/utils/security/sanitization
- */
-import sanitizeHtml from "sanitize-html";
-import { RequestContext } from "../internal/index.js";
-/**
- * Options for path sanitization, controlling how file paths are cleaned and validated.
- */
-export interface PathSanitizeOptions {
-    /**
-     * If provided, restricts sanitized paths to be relative to this root directory.
-     * Attempts to traverse above this root (e.g., using `../`) will result in an error.
-     * The final sanitized path will be relative to this `rootDir`.
-     */
-    rootDir?: string;
-    /**
-     * If `true`, normalizes Windows-style backslashes (`\\`) to POSIX-style forward slashes (`/`).
-     * Defaults to `false`.
-     */
-    toPosix?: boolean;
-    /**
-     * If `true`, allows absolute paths, subject to `rootDir` constraints if `rootDir` is also provided.
-     * If `false` (default), absolute paths are converted to relative paths by removing leading slashes or drive letters.
-     */
-    allowAbsolute?: boolean;
-}
-/**
- * Information returned by the `sanitizePath` method, providing details about
- * the sanitization process and its outcome.
- */
-export interface SanitizedPathInfo {
-    /** The final sanitized and normalized path string. */
-    sanitizedPath: string;
-    /** The original path string passed to the function before any normalization or sanitization. */
-    originalInput: string;
-    /** Indicates if the input path was determined to be absolute after initial `path.normalize()`. */
-    wasAbsolute: boolean;
-    /**
-     * Indicates if an initially absolute path was converted to a relative path
-     * (typically because `options.allowAbsolute` was `false`).
-     */
-    convertedToRelative: boolean;
-    /** The effective options (including defaults) that were used for sanitization. */
-    optionsUsed: PathSanitizeOptions;
-}
-/**
- * Options for context-specific string sanitization using `sanitizeString`.
- */
-export interface SanitizeStringOptions {
-    /**
-     * Specifies the context in which the string will be used, guiding the sanitization strategy.
-     * - `'text'`: (Default) Strips all HTML tags, suitable for plain text content.
-     * - `'html'`: Sanitizes for safe HTML embedding, using `allowedTags` and `allowedAttributes`.
-     * - `'attribute'`: Sanitizes for use within an HTML attribute value (strips all tags).
-     * - `'url'`: Validates and trims the string as a URL.
-     * - `'javascript'`: **Disallowed.** Throws an error to prevent unsafe JavaScript sanitization.
-     */
-    context?: "text" | "html" | "attribute" | "url" | "javascript";
-    /** Custom allowed HTML tags when `context` is `'html'`. Overrides default HTML sanitization tags. */
-    allowedTags?: string[];
-    /** Custom allowed HTML attributes per tag when `context` is `'html'`. Overrides default HTML sanitization attributes. */
-    allowedAttributes?: Record<string, string[]>;
-}
-/**
- * Configuration options for HTML sanitization using `sanitizeHtml`.
- */
-export interface HtmlSanitizeConfig {
-    /** An array of allowed HTML tag names (e.g., `['p', 'a', 'strong']`). */
-    allowedTags?: string[];
-    /**
-     * A map specifying allowed attributes for HTML tags.
-     * Keys can be tag names (e.g., `'a'`) or `'*'` for global attributes.
-     * Values are arrays of allowed attribute names (e.g., `{'a': ['href', 'title']}`).
-     */
-    allowedAttributes?: sanitizeHtml.IOptions["allowedAttributes"];
-    /** If `true`, HTML comments (`<!-- ... -->`) are preserved. Defaults to `false`. */
-    preserveComments?: boolean;
-    /**
-     * Custom rules for transforming tags during sanitization.
-     * See `sanitize-html` documentation for `transformTags` options.
-     */
-    transformTags?: sanitizeHtml.IOptions["transformTags"];
-}
-/**
- * A singleton utility class for performing various input sanitization tasks.
- * It provides methods to clean and validate strings, HTML, URLs, file paths, JSON,
- * and numbers, and to redact sensitive data for logging.
- */
-export declare class Sanitization {
-    private static instance;
-    private sensitiveFields;
-    private defaultHtmlSanitizeConfig;
-    private constructor();
-    /**
-     * Gets the singleton instance of the `Sanitization` class.
-     * @returns {Sanitization} The singleton instance.
-     */
-    static getInstance(): Sanitization;
-    /**
-     * Sets or extends the list of field names considered sensitive for log redaction.
-     * Field names are matched case-insensitively.
-     * @param {string[]} fields - An array of field names to add to the sensitive list.
-     * @param {RequestContext} [context] - Optional context for logging this configuration change.
-     */
-    setSensitiveFields(fields: string[], context?: RequestContext): void;
-    /**
-     * Retrieves a copy of the current list of sensitive field names used for log redaction.
-     * @returns {string[]} An array of sensitive field names (all lowercase).
-     */
-    getSensitiveFields(): string[];
-    /**
-     * Sanitizes an HTML string by removing potentially malicious tags and attributes,
-     * based on a configurable allow-list.
-     * @param {string} input - The HTML string to sanitize.
-     * @param {HtmlSanitizeConfig} [config] - Optional custom configuration for HTML sanitization.
-     *   Overrides defaults for `allowedTags`, `allowedAttributes`, etc.
-     * @returns {string} The sanitized HTML string. Returns an empty string if input is falsy.
-     */
-    sanitizeHtml(input: string, config?: HtmlSanitizeConfig): string;
-    /**
-     * Sanitizes a tag name by removing the leading '#' and replacing invalid characters.
-     * @param {string} input - The tag string to sanitize.
-     * @returns {string} The sanitized tag name.
-     */
-    sanitizeTagName(input: string): string;
-    /**
-  >>>>>>> REPLACE
-     * Sanitizes a string based on its intended usage context (e.g., HTML, URL, plain text).
-     *
-     * **Security Note:** Using `context: 'javascript'` is explicitly disallowed and will throw an `McpError`.
-     * This is to prevent accidental introduction of XSS vulnerabilities through ineffective sanitization
-     * of JavaScript code. Proper contextual encoding or safer methods should be used for JavaScript.
-     *
-     * @param {string} input - The string to sanitize.
-     * @param {SanitizeStringOptions} [options={}] - Options specifying the sanitization context
-     *   and any context-specific parameters (like `allowedTags` for HTML).
-     * @param {RequestContext} [contextForLogging] - Optional context for logging warnings or errors.
-     * @returns {string} The sanitized string. Returns an empty string if input is falsy.
-     * @throws {McpError} If `options.context` is `'javascript'`.
-     */
-    sanitizeString(input: string, options?: SanitizeStringOptions, contextForLogging?: RequestContext): string;
-    /**
-     * Sanitizes a URL string by validating its format and protocol.
-     * @param {string} input - The URL string to sanitize.
-     * @param {string[]} [allowedProtocols=['http', 'https']] - An array of allowed URL protocols (e.g., 'http', 'https', 'ftp').
-     * @param {RequestContext} [contextForLogging] - Optional context for logging errors.
-     * @returns {string} The sanitized and trimmed URL string.
-     * @throws {McpError} If the URL is invalid, uses a disallowed protocol, or contains 'javascript:'.
-     */
-    sanitizeUrl(input: string, allowedProtocols?: string[], contextForLogging?: RequestContext): string;
-    /**
-     * Sanitizes a file path to prevent path traversal attacks and normalize its format.
-     *
-     * @param {string} input - The file path string to sanitize.
-     * @param {PathSanitizeOptions} [options={}] - Options to control sanitization behavior (e.g., `rootDir`, `toPosix`).
-     * @param {RequestContext} [contextForLogging] - Optional context for logging warnings or errors.
-     * @returns {SanitizedPathInfo} An object containing the sanitized path and metadata about the sanitization.
-     * @throws {McpError} If the path is invalid (e.g., empty, contains null bytes) or determined to be unsafe
-     *   (e.g., attempts to traverse outside `rootDir` or current working directory if no `rootDir`).
-     */
-    sanitizePath(input: string, options?: PathSanitizeOptions, contextForLogging?: RequestContext): SanitizedPathInfo;
-    /**
-     * Sanitizes a JSON string by parsing it to validate its format.
-     * Optionally checks if the JSON string's byte size exceeds a maximum limit.
-     *
-     * @template T The expected type of the parsed JSON object. Defaults to `unknown`.
-     * @param {string} input - The JSON string to sanitize/validate.
-     * @param {number} [maxSizeBytes] - Optional maximum allowed size of the JSON string in bytes.
-     * @param {RequestContext} [contextForLogging] - Optional context for logging errors.
-     * @returns {T} The parsed JavaScript object.
-     * @throws {McpError} If the input is not a string, is not valid JSON, or exceeds `maxSizeBytes`.
-     */
-    sanitizeJson<T = unknown>(input: string, maxSizeBytes?: number, contextForLogging?: RequestContext): T;
-    /**
-     * Sanitizes a numeric input (number or string) by converting it to a number
-     * and optionally clamping it within a specified min/max range.
-     *
-     * @param {number | string} input - The numeric value or string representation of a number.
-     * @param {number} [min] - Optional minimum allowed value (inclusive).
-     * @param {number} [max] - Optional maximum allowed value (inclusive).
-     * @param {RequestContext} [contextForLogging] - Optional context for logging clamping or errors.
-     * @returns {number} The sanitized (and potentially clamped) number.
-     * @throws {McpError} If the input cannot be parsed into a valid, finite number.
-     */
-    sanitizeNumber(input: number | string, min?: number, max?: number, contextForLogging?: RequestContext): number;
-    /**
-     * Sanitizes an object or array for logging by deep cloning it and redacting fields
-     * whose names (case-insensitively) match any of the configured sensitive field names.
-     * Redacted fields are replaced with the string `'[REDACTED]'`.
-     *
-     * @param {unknown} input - The object, array, or other value to sanitize for logging.
-     *   If input is not an object or array, it's returned as is.
-     * @param {RequestContext} [contextForLogging] - Optional context for logging errors during sanitization.
-     * @returns {unknown} A sanitized copy of the input, safe for logging.
-     *   Returns `'[Log Sanitization Failed]'` if an unexpected error occurs during sanitization.
-     */
-    sanitizeForLogging(input: unknown, contextForLogging?: RequestContext): unknown;
-    /**
-     * Helper to convert attribute format for sanitize-html.
-     * `sanitize-html` expects `allowedAttributes` in a specific format.
-     * This method assumes the input `attrs` (from `SanitizeStringOptions`)
-     * is already in the correct format or a compatible one.
-     * @param {Record<string, string[]>} attrs - Attributes configuration.
-     * @returns {sanitizeHtml.IOptions['allowedAttributes']} Attributes in `sanitize-html` format.
-     * @private
-     */
-    private convertAttributesFormat;
-    /**
-     * Recursively redacts sensitive fields within an object or array.
-     * This method modifies the input object/array in place.
-     * @param {unknown} obj - The object or array to redact sensitive fields from.
-     * @private
-     */
-    private redactSensitiveFields;
-}
-/**
- * A default, shared instance of the `Sanitization` class.
- * Use this instance for all sanitization tasks.
- *
- * Example:
- * ```typescript
- * import { sanitization, sanitizeInputForLogging } from './sanitization';
- *
- * const unsafeHtml = "<script>alert('xss')</script><p>Safe</p>";
- * const safeHtml = sanitization.sanitizeHtml(unsafeHtml);
- *
- * const sensitiveData = { password: '123', username: 'user' };
- * const safeLogData = sanitizeInputForLogging(sensitiveData);
- * // safeLogData will be { password: '[REDACTED]', username: 'user' }
- * ```
- */
-export declare const sanitization: Sanitization;
-/**
- * A convenience function that wraps `sanitization.sanitizeForLogging`.
- * Sanitizes an object or array for logging by redacting sensitive fields.
- *
- * @param {unknown} input - The data to sanitize for logging.
- * @param {RequestContext} [contextForLogging] - Optional context for logging errors during sanitization.
- * @returns {unknown} A sanitized copy of the input, safe for logging.
- */
-export declare const sanitizeInputForLogging: (input: unknown, contextForLogging?: RequestContext) => unknown;