@cyanheads/pubmed-mcp-server 1.0.12

package/dist/utils/parsing/ncbi-parsing/xmlGenericHelpers.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Generic helper functions for parsing XML data, particularly
+ * structures from fast-xml-parser.
+ * @module src/utils/parsing/ncbi-parsing/xmlGenericHelpers
+ */
+/**
+ * Ensures that the input is an array. If it's not an array, it wraps it in one.
+ * Handles undefined or null by returning an empty array.
+ * @param item - The item to ensure is an array.
+ * @returns An array containing the item, or an empty array if item is null/undefined.
+ * @template T - The type of the items in the array.
+ */
+export function ensureArray(item) {
+    if (item === undefined || item === null) {
+        return [];
+    }
+    return Array.isArray(item) ? item : [item];
+}
+/**
+ * Safely extracts text content from an XML element, which might be a string or an object with a "#text" property.
+ * Handles cases where #text might be a number or boolean by converting to string.
+ * @param element - The XML element (string, object with #text, or undefined).
+ * @param defaultValue - The value to return if text cannot be extracted. Defaults to an empty string.
+ * @returns The text content or the default value.
+ */
+export function getText(element, defaultValue = "") {
+    if (element === undefined || element === null) {
+        return defaultValue;
+    }
+    if (typeof element === "string") {
+        return element;
+    }
+    if (typeof element === "number" || typeof element === "boolean") {
+        return String(element); // Handle direct number/boolean elements
+    }
+    if (typeof element === "object" && element["#text"] !== undefined) {
+        // Check if #text exists and convert to string
+        if (typeof element["#text"] === "string") {
+            return element["#text"];
+        }
+        // Also handle #text being a number or boolean
+        if (typeof element["#text"] === "number" ||
+            typeof element["#text"] === "boolean") {
+            return String(element["#text"]);
+        }
+    }
+    return defaultValue;
+}
+/**
+ * Safely extracts an attribute value from an XML element.
+ * Assumes attributes are prefixed with "@_" by fast-xml-parser.
+ * @param element - The XML element object.
+ * @param attributeName - The name of the attribute (e.g., "_UI", "_MajorTopicYN", without the "@_" prefix).
+ * @param defaultValue - The value to return if the attribute is not found. Defaults to an empty string.
+ * @returns The attribute value or the default value.
+ */
+export function getAttribute(element, attributeName, // e.g., "UI", "MajorTopicYN"
+defaultValue = "") {
+    const fullAttributeName = `@_${attributeName}`; // As per fast-xml-parser config
+    if (element &&
+        typeof element === "object" &&
+        typeof element[fullAttributeName] === "string") {
+        return element[fullAttributeName];
+    }
+    if (element &&
+        typeof element === "object" &&
+        typeof element[fullAttributeName] === "boolean") {
+        return String(element[fullAttributeName]); // Convert boolean attributes to string
+    }
+    if (element &&
+        typeof element === "object" &&
+        typeof element[fullAttributeName] === "number") {
+        return String(element[fullAttributeName]); // Convert number attributes to string
+    }
+    return defaultValue;
+}

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

@@ -0,0 +1,134 @@
+/**
+ * Defines the structure for configuring entity prefixes.
+ * Keys are entity type names (e.g., "project", "task"), and values are their corresponding ID prefixes (e.g., "PROJ", "TASK").
+ */
+export interface EntityPrefixConfig {
+    [key: string]: string;
+}
+/**
+ * Defines options for customizing ID generation.
+ */
+export interface IdGenerationOptions {
+    length?: number;
+    separator?: string;
+    charset?: string;
+}
+/**
+ * A generic ID Generator class for creating and managing unique, prefixed identifiers.
+ * Allows defining custom prefixes, generating random strings, and validating/normalizing IDs.
+ */
+export declare class IdGenerator {
+    /**
+     * Default character set for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_CHARSET;
+    /**
+     * Default separator character between prefix and random part.
+     * @private
+     */
+    private static DEFAULT_SEPARATOR;
+    /**
+     * Default length for the random part of the ID.
+     * @private
+     */
+    private static DEFAULT_LENGTH;
+    /**
+     * Stores the mapping of entity types to their prefixes.
+     * @private
+     */
+    private entityPrefixes;
+    /**
+     * Stores a reverse mapping from prefixes (case-insensitive) to entity types.
+     * @private
+     */
+    private prefixToEntityType;
+    /**
+     * Constructs an `IdGenerator` instance.
+     * @param entityPrefixes - An initial map of entity types to their prefixes.
+     */
+    constructor(entityPrefixes?: EntityPrefixConfig);
+    /**
+     * 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: EntityPrefixConfig): void;
+    /**
+     * Retrieves a copy of the current entity prefix configuration.
+     * @returns The current entity prefix configuration.
+     */
+    getEntityPrefixes(): EntityPrefixConfig;
+    /**
+     * 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?: number, charset?: string): string;
+    /**
+     * 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?: string, options?: IdGenerationOptions): string;
+    /**
+     * 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: string, options?: IdGenerationOptions): string;
+    /**
+     * 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.
+     * @returns `true` if the ID is valid, `false` otherwise.
+     */
+    isValid(id: string, entityType: string, options?: IdGenerationOptions): boolean;
+    /**
+     * Escapes special characters in a string for use in a regular expression.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     * @private
+     */
+    private escapeRegex;
+    /**
+     * 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: string, separator?: string): string;
+    /**
+     * 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: string, separator?: string): string;
+    /**
+     * Normalizes an entity ID to ensure the prefix matches the registered case
+     * and the random part is uppercase.
+     * @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: string, separator?: string): string;
+}
+/**
+ * Default singleton instance of the `IdGenerator`.
+ * Initialize with `idGenerator.setEntityPrefixes({})` to configure.
+ */
+export declare const idGenerator: 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 declare const generateUUID: () => string;

package/dist/utils/security/idGenerator.js

@@ -0,0 +1,198 @@
+/**
+ * @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) {
+        const bytes = randomBytes(length);
+        let result = "";
+        for (let i = 0; i < length; i++) {
+            result += charset[bytes[i] % 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.
+     * @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, } = options;
+        if (!prefix) {
+            return false;
+        }
+        // Assumes default charset characters (uppercase letters and digits) for regex.
+        const pattern = new RegExp(`^${this.escapeRegex(prefix)}${this.escapeRegex(separator)}[A-Z0-9]{${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.
+     * @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);
+        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;