@cyanheads/pubchem-mcp-server 1.0.1

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,215 @@
+/**
+ * @fileoverview Provides a utility class `IdGenerator` for creating customizable, prefixed unique identifiers,
+ * and a standalone `generateUUID` function for generating standard UUIDs.
+ * The `IdGenerator` supports entity-specific prefixes, custom character sets, and lengths.
+ *
+ * Note: Logging has been removed from this module to prevent circular dependencies
+ * with the `requestContextService`, which itself uses `generateUUID` from this module.
+ * This was causing `ReferenceError: Cannot access 'generateUUID' before initialization`
+ * during application startup.
+ * @module src/utils/security/idGenerator
+ */
+import { randomUUID as cryptoRandomUUID, randomBytes } from "crypto";
+import { BaseErrorCode, McpError } from "../../types-global/errors.js";
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export class IdGenerator {
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes = {}) {
+        /**
+         * Stores the mapping of entity types to their prefixes.
+         * @private
+         */
+        this.entityPrefixes = {};
+        /**
+         * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+         * @private
+         */
+        this.prefixToEntityType = {};
+        // Logging removed to prevent circular dependency with requestContextService.
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Sets or updates the entity prefix configuration and rebuilds the internal reverse lookup map.
+     * @param entityPrefixes - A map where keys are entity type names and values are their desired ID prefixes.
+     */
+    setEntityPrefixes(entityPrefixes) {
+        // Logging removed.
+        this.entityPrefixes = { ...entityPrefixes };
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix.toLowerCase()] = type; // Store lowercase for case-insensitive lookup
+            return acc;
+        }, {});
+    }
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random string.
+     * @param length - The desired length of the random string. Defaults to `IdGenerator.DEFAULT_LENGTH`.
+     * @param charset - The character set to use. Defaults to `IdGenerator.DEFAULT_CHARSET`.
+     * @returns The generated random string.
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        let result = "";
+        // Determine the largest multiple of charset.length that is less than or equal to 256
+        // This is the threshold for rejection sampling to avoid bias.
+        const maxValidByteValue = Math.floor(256 / charset.length) * charset.length;
+        while (result.length < length) {
+            const byteBuffer = randomBytes(1); // Get one random byte
+            const byte = byteBuffer[0];
+            // If the byte is within the valid range (i.e., it won't introduce bias),
+            // use it to select a character from the charset. Otherwise, discard and try again.
+            if (byte < maxValidByteValue) {
+                result += charset[byte % charset.length];
+            }
+        }
+        return result;
+    }
+    /**
+     * Generates a unique ID, optionally prepended with a prefix.
+     * @param prefix - An optional prefix for the ID.
+     * @param options - Optional parameters for ID generation (length, separator, charset).
+     * @returns A unique identifier string.
+     */
+    generate(prefix, options = {}) {
+        // Logging removed.
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        const generatedId = prefix
+            ? `${prefix}${separator}${randomPart}`
+            : randomPart;
+        return generatedId;
+    }
+    /**
+     * Generates a unique ID for a specified entity type, using its configured prefix.
+     * @param entityType - The type of entity (must be registered).
+     * @param options - Optional parameters for ID generation.
+     * @returns A unique identifier string for the entity (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the `entityType` is not registered.
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type: ${entityType}. No prefix registered.`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if an ID conforms to the expected format for a specific entity type.
+     * @param id - The ID string to validate.
+     * @param entityType - The expected entity type of the ID.
+     * @param options - Optional parameters used during generation for validation consistency.
+     *                  The `charset` from these options will be used for validation.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET, // Use charset from options or default
+         } = options;
+        if (!prefix) {
+            return false;
+        }
+        // Build regex character class from the charset
+        // Escape characters that have special meaning inside a regex character class `[]`
+        const escapedCharsetForClass = charset.replace(/[[\]\\^-]/g, "\\$&");
+        const charsetRegexPart = `[${escapedCharsetForClass}]`;
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}${charsetRegexPart}{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    escapeRegex(str) {
+        return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    /**
+     * Strips the prefix and separator from an ID string.
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The ID part without the prefix, or the original ID if separator not found.
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        return parts.length > 1 ? parts.slice(1).join(separator) : id; // Handle separators in random part
+    }
+    /**
+     * Determines the entity type from an ID string by its prefix (case-insensitive).
+     * @param id - The ID string (e.g., "PROJ_A6B3J0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The determined entity type.
+     * @throws {McpError} If ID format is invalid or prefix is unknown.
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length < 2 || !parts[0]) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid ID format: ${id}. Expected format like: PREFIX${separator}RANDOMLPART`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix.toLowerCase()];
+        if (!entityType) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type for prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the registered case
+     * and the random part is uppercase. Note: This assumes the charset characters
+     * have a meaningful uppercase version if case-insensitivity is desired for the random part.
+     * For default charset (A-Z0-9), this is fine. For custom charsets, behavior might vary.
+     * @param id - The ID to normalize (e.g., "proj_a6b3j0").
+     * @param separator - The separator used in the ID. Defaults to `IdGenerator.DEFAULT_SEPARATOR`.
+     * @returns The normalized ID (e.g., "PROJ_A6B3J0").
+     * @throws {McpError} If the entity type cannot be determined from the ID.
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const registeredPrefix = this.entityPrefixes[entityType];
+        const idParts = id.split(separator);
+        const randomPart = idParts.slice(1).join(separator);
+        // Consider if randomPart.toUpperCase() is always correct for custom charsets.
+        // For now, maintaining existing behavior.
+        return `${registeredPrefix}${separator}${randomPart.toUpperCase()}`;
+    }
+}
+/**
+ * Default character set for the random part of the ID.
+ * @private
+ */
+IdGenerator.DEFAULT_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+/**
+ * Default separator character between prefix and random part.
+ * @private
+ */
+IdGenerator.DEFAULT_SEPARATOR = "_";
+/**
+ * Default length for the random part of the ID.
+ * @private
+ */
+IdGenerator.DEFAULT_LENGTH = 6;
+/**
+ * Default singleton instance of the `IdGenerator`.
+ * Initialize with `idGenerator.setEntityPrefixes({})` to configure.
+ */
+export const idGenerator = new IdGenerator();
+/**
+ * Generates a standard Version 4 UUID (Universally Unique Identifier).
+ * Uses the Node.js `crypto` module. This function is independent of the IdGenerator instance
+ * to prevent circular dependencies when used by other utilities like requestContextService.
+ * @returns A new UUID string.
+ */
+export const generateUUID = () => {
+    return cryptoRandomUUID();
+};

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for security-related utility modules.
+ * This file re-exports utilities for input sanitization, rate limiting,
+ * and ID generation.
+ * @module src/utils/security
+ */
+export * from "./idGenerator.js";
+export * from "./rateLimiter.js";
+export * from "./sanitization.js";

package/dist/utils/security/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for security-related utility modules.
+ * This file re-exports utilities for input sanitization, rate limiting,
+ * and ID generation.
+ * @module src/utils/security
+ */
+export * from "./idGenerator.js";
+export * from "./rateLimiter.js";
+export * from "./sanitization.js";

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

@@ -0,0 +1,108 @@
+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;

package/dist/utils/security/rateLimiter.js

@@ -0,0 +1,179 @@
+/**
+ * @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 { environment } from "../../config/index.js";
+import { BaseErrorCode, 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 {
+    /**
+     * Creates a new `RateLimiter` instance.
+     * @param config - Configuration options, merged with defaults.
+     */
+    constructor(config) {
+        this.config = config;
+        /**
+         * Timer ID for periodic cleanup.
+         * @private
+         */
+        this.cleanupTimer = null;
+        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(`Cleaned up ${expiredCount} expired rate limit entries`, logContext);
+        }
+    }
+    /**
+     * 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("Rate limiter reset, all limits cleared", logContext);
+    }
+    /**
+     * 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) {
+        if (this.config.skipInDevelopment && environment === "development") {
+            return;
+        }
+        const limitKey = this.config.keyGenerator
+            ? this.config.keyGenerator(key, context)
+            : key;
+        const now = Date.now();
+        const entry = this.limits.get(limitKey);
+        if (!entry || now >= entry.resetTime) {
+            this.limits.set(limitKey, {
+                count: 1,
+                resetTime: now + this.config.windowMs,
+            });
+            return;
+        }
+        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());
+            throw new McpError(BaseErrorCode.RATE_LIMITED, errorMessage, {
+                waitTimeSeconds: waitTime,
+                key: limitKey,
+                limit: this.config.maxRequests,
+                windowMs: this.config.windowMs,
+            });
+        }
+        entry.count++;
+    }
+    /**
+     * 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 configuration values.
+ * @private
+ */
+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
+};
+/**
+ * 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
+});