ntfy-mcp-server 1.0.0

package/dist/utils/idGenerator.js

@@ -0,0 +1,149 @@
+import { randomBytes } from 'crypto';
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { logger } from './logger.js';
+/**
+ * Generic ID Generator class for creating and managing unique identifiers
+ */
+export class IdGenerator {
+    /**
+     * Constructor that accepts entity prefix configuration
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    constructor(entityPrefixes = {}) {
+        // Entity prefixes
+        this.entityPrefixes = {};
+        // Reverse mapping for prefix to entity type lookup
+        this.prefixToEntityType = {};
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Set or update entity prefixes and rebuild the reverse lookup
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    setEntityPrefixes(entityPrefixes) {
+        this.entityPrefixes = { ...entityPrefixes };
+        // Rebuild reverse mapping
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix] = type;
+            acc[prefix.toLowerCase()] = type;
+            return acc;
+        }, {});
+        logger.debug('Entity prefixes updated', { entityPrefixes: this.entityPrefixes });
+    }
+    /**
+     * Get all registered entity prefixes
+     * @returns The entity prefix configuration
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random alphanumeric string
+     * @param length The length of the random string to generate
+     * @param charset Optional custom character set
+     * @returns Random alphanumeric 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 with an optional prefix
+     * @param prefix Optional prefix to add to the ID
+     * @param options Optional generation options
+     * @returns A unique identifier string
+     */
+    generate(prefix, options = {}) {
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        return prefix
+            ? `${prefix}${separator}${randomPart}`
+            : randomPart;
+    }
+    /**
+     * Generates a custom ID for an entity with format PREFIX_XXXXXX
+     * @param entityType The type of entity to generate an ID for
+     * @param options Optional generation options
+     * @returns A unique identifier string (e.g., "PROJ_A6B3J0")
+     * @throws {McpError} If the entity type is not registered
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type: ${entityType}`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if a given ID matches the expected format for an entity type
+     * @param id The ID to validate
+     * @param entityType The expected entity type
+     * @param options Optional validation options
+     * @returns boolean indicating if the ID is valid
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR } = options;
+        if (!prefix) {
+            return false;
+        }
+        const pattern = new RegExp(`^${prefix}${separator}[A-Z0-9]{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Strips the prefix from an ID
+     * @param id The ID to strip
+     * @param separator Optional custom separator
+     * @returns The ID without the prefix
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        return id.split(separator)[1] || id;
+    }
+    /**
+     * Determines the entity type from an ID
+     * @param id The ID to get the entity type for
+     * @param separator Optional custom separator
+     * @returns The entity type
+     * @throws {McpError} If the ID format is invalid or entity type 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: PREFIX${separator}XXXXXX`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix];
+        if (!entityType) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure consistent uppercase format
+     * @param id The ID to normalize
+     * @param separator Optional custom separator
+     * @returns The normalized ID in uppercase format
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const idParts = id.split(separator);
+        return `${this.entityPrefixes[entityType]}${separator}${idParts[1].toUpperCase()}`;
+    }
+}
+// Default charset
+IdGenerator.DEFAULT_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+// Default separator
+IdGenerator.DEFAULT_SEPARATOR = '_';
+// Default random part length
+IdGenerator.DEFAULT_LENGTH = 6;
+// Create and export a default instance with an empty entity prefix configuration
+export const idGenerator = new IdGenerator();
+// For standalone use as a UUID generator
+export const generateUUID = () => {
+    return crypto.randomUUID();
+};
+export default idGenerator;

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+export * from './requestContext.js';
+export * from './errorHandler.js';
+export * from './idGenerator.js';
+export * from './logger.js';
+export * from './rateLimiter.js';
+export * from './sanitization.js';
+import { default as requestContext } from './requestContext.js';
+import { default as errorHandler } from './errorHandler.js';
+import { default as idGenerator } from './idGenerator.js';
+import { logger } from './logger.js';
+import { default as rateLimiter } from './rateLimiter.js';
+import { default as sanitization } from './sanitization.js';
+export { requestContext, errorHandler, idGenerator, logger, rateLimiter, sanitization };

package/dist/utils/index.js

@@ -0,0 +1,16 @@
+// Re-export all utilities
+export * from './requestContext.js';
+export * from './errorHandler.js';
+export * from './idGenerator.js';
+export * from './logger.js';
+export * from './rateLimiter.js';
+export * from './sanitization.js';
+// Import named exports to re-export
+import { default as requestContext } from './requestContext.js';
+import { default as errorHandler } from './errorHandler.js';
+import { default as idGenerator } from './idGenerator.js';
+import { logger } from './logger.js';
+import { default as rateLimiter } from './rateLimiter.js';
+import { default as sanitization } from './sanitization.js';
+// Export frequently used utilities directly
+export { requestContext, errorHandler, idGenerator, logger, rateLimiter, sanitization };

package/dist/utils/logger.d.ts

@@ -0,0 +1,36 @@
+export type ChildLogger = {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+};
+declare class Logger {
+    private static instance;
+    private logger;
+    private constructor();
+    static getInstance(): Logger;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+    createChildLogger(metadata: {
+        module: string;
+        service?: string;
+        serviceId?: string;
+        componentName?: string;
+        subscriberId?: string;
+        component?: string;
+        requestId?: string;
+        subscriptionTime?: string;
+        environment?: string;
+        serverId?: string;
+        [key: string]: any;
+    }): {
+        debug: (message: string, context?: Record<string, unknown>) => void;
+        info: (message: string, context?: Record<string, unknown>) => void;
+        warn: (message: string, context?: Record<string, unknown>) => void;
+        error: (message: string, context?: Record<string, unknown>) => void;
+    };
+}
+export declare const logger: Logger;
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,92 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import winston from "winston";
+// Handle ESM module dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Resolve logs directory relative to project root (2 levels up from utils/)
+const projectRoot = path.resolve(__dirname, '..', '..');
+const logsDir = path.join(projectRoot, 'logs');
+class Logger {
+    constructor() {
+        const logLevel = process.env.LOG_LEVEL || "info";
+        // Ensure logs directory exists
+        if (!fs.existsSync(logsDir)) {
+            fs.mkdirSync(logsDir, { recursive: true });
+        }
+        // Common format for all transports
+        const commonFormat = winston.format.combine(winston.format.timestamp(), winston.format.errors({ stack: true }), winston.format.printf(({ timestamp, level, message, context, stack }) => {
+            const contextStr = context ? `\n  Context: ${JSON.stringify(context, null, 2)}` : "";
+            const stackStr = stack ? `\n  Stack: ${stack}` : "";
+            return `[${timestamp}] ${level}: ${message}${contextStr}${stackStr}`;
+        }));
+        this.logger = winston.createLogger({
+            level: logLevel,
+            format: winston.format.json(),
+            transports: [
+                // Combined log file for all levels
+                new winston.transports.File({
+                    filename: path.join(logsDir, 'combined.log'),
+                    format: commonFormat
+                }),
+                // Separate log files for each level
+                new winston.transports.File({
+                    filename: path.join(logsDir, 'error.log'),
+                    level: 'error',
+                    format: commonFormat
+                }),
+                new winston.transports.File({
+                    filename: path.join(logsDir, 'warn.log'),
+                    level: 'warn',
+                    format: commonFormat
+                }),
+                new winston.transports.File({
+                    filename: path.join(logsDir, 'info.log'),
+                    level: 'info',
+                    format: commonFormat
+                }),
+                new winston.transports.File({
+                    filename: path.join(logsDir, 'debug.log'),
+                    level: 'debug',
+                    format: commonFormat
+                })
+            ]
+        });
+    }
+    static getInstance() {
+        if (!Logger.instance) {
+            Logger.instance = new Logger();
+        }
+        return Logger.instance;
+    }
+    debug(message, context) {
+        this.logger.debug(message, { context });
+    }
+    info(message, context) {
+        this.logger.info(message, { context });
+    }
+    warn(message, context) {
+        this.logger.warn(message, { context });
+    }
+    error(message, context) {
+        this.logger.error(message, { context });
+    }
+    createChildLogger(metadata) {
+        return {
+            debug: (message, context) => {
+                this.debug(`[${metadata.module}] ${message}`, context);
+            },
+            info: (message, context) => {
+                this.info(`[${metadata.module}] ${message}`, context);
+            },
+            warn: (message, context) => {
+                this.warn(`[${metadata.module}] ${message}`, context);
+            },
+            error: (message, context) => {
+                this.error(`[${metadata.module}] ${message}`, context);
+            }
+        };
+    }
+}
+export const logger = Logger.getInstance();

package/dist/utils/rateLimiter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Request context interface
+ */
+export interface RequestContext {
+    /** Unique request identifier */
+    requestId: string;
+    /** Request timestamp */
+    timestamp: string;
+    /** Request path/endpoint */
+    path?: string;
+    /** HTTP method */
+    method?: string;
+    /** Request source IP */
+    ip?: string;
+    /** Custom request properties */
+    [key: string]: unknown;
+}
+/**
+ * Rate limiting configuration options
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds */
+    windowMs: number;
+    /** Maximum number of requests allowed in the window */
+    maxRequests: number;
+    /** Custom error message template */
+    errorMessage?: string;
+    /** Whether to skip rate limiting in certain environments (e.g. development) */
+    skipInDevelopment?: boolean;
+    /** Custom key generator function */
+    keyGenerator?: (identifier: string, context?: RequestContext) => string;
+    /** How often to run cleanup of expired entries (in milliseconds) */
+    cleanupInterval?: number;
+}
+/**
+ * Individual rate limit entry
+ */
+export interface RateLimitEntry {
+    /** Current request count */
+    count: number;
+    /** When the window resets (timestamp) */
+    resetTime: number;
+    /** Key for this entry, stored for faster deletion */
+    key: string;
+}
+/**
+ * Generic rate limiter that can be used across the application
+ */
+export declare class RateLimiter {
+    private config;
+    /** Map storing rate limit data */
+    private limits;
+    /** Cleanup interval timer */
+    private cleanupTimer;
+    /** Default configuration */
+    private static DEFAULT_CONFIG;
+    /**
+     * Create a new rate limiter
+     * @param config Rate limiting configuration
+     */
+    constructor(config: RateLimitConfig);
+    /**
+     * Start the cleanup timer to periodically remove expired entries
+     */
+    private startCleanupTimer;
+    /**
+     * Clean up expired rate limit entries to prevent memory leaks
+     */
+    private cleanupExpiredEntries;
+    /**
+     * Update rate limiter configuration
+     * @param config New configuration options
+     */
+    configure(config: Partial<RateLimitConfig>): void;
+    /**
+     * Get current configuration
+     * @returns Current rate limit configuration
+     */
+    getConfig(): RateLimitConfig;
+    /**
+     * Reset all rate limits
+     */
+    reset(): void;
+    /**
+     * Check if a request exceeds the rate limit
+     * @param key Unique identifier for the request source
+     * @param context Optional request context
+     * @throws {McpError} If rate limit is exceeded
+     */
+    check(key: string, context?: RequestContext): void;
+    /**
+     * Get rate limit information for a key
+     * @param key The rate limit key
+     * @returns Current rate limit status or null if no record exists
+     */
+    getStatus(key: string): {
+        current: number;
+        limit: number;
+        remaining: number;
+        resetTime: number;
+    } | null;
+    /**
+     * Stop the cleanup timer when the limiter is no longer needed
+     */
+    dispose(): void;
+}
+/**
+ * Create and export a default rate limiter instance
+ */
+export declare const rateLimiter: RateLimiter;
+declare const _default: {
+    RateLimiter: typeof RateLimiter;
+    rateLimiter: RateLimiter;
+};
+export default _default;

package/dist/utils/rateLimiter.js

@@ -0,0 +1,180 @@
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { logger } from './logger.js';
+/**
+ * Generic rate limiter that can be used across the application
+ */
+export class RateLimiter {
+    /**
+     * Create a new rate limiter
+     * @param config Rate limiting configuration
+     */
+    constructor(config) {
+        this.config = config;
+        /** Cleanup interval timer */
+        this.cleanupTimer = null;
+        this.config = { ...RateLimiter.DEFAULT_CONFIG, ...config };
+        this.limits = new Map();
+        this.startCleanupTimer();
+        // Log initialization
+        logger.debug('RateLimiter initialized', {
+            windowMs: this.config.windowMs,
+            maxRequests: this.config.maxRequests,
+            cleanupInterval: this.config.cleanupInterval
+        });
+    }
+    /**
+     * Start the cleanup timer to periodically remove expired entries
+     */
+    startCleanupTimer() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        const interval = this.config.cleanupInterval ?? RateLimiter.DEFAULT_CONFIG.cleanupInterval;
+        if (interval) {
+            this.cleanupTimer = setInterval(() => {
+                this.cleanupExpiredEntries();
+            }, interval);
+            // Ensure the timer doesn't prevent the process from exiting
+            if (this.cleanupTimer.unref) {
+                this.cleanupTimer.unref();
+            }
+        }
+    }
+    /**
+     * Clean up expired rate limit entries to prevent memory leaks
+     */
+    cleanupExpiredEntries() {
+        const now = Date.now();
+        let expiredCount = 0;
+        // Use a synchronized approach to avoid race conditions during cleanup
+        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`, {
+                totalRemaining: this.limits.size
+            });
+        }
+    }
+    /**
+     * Update rate limiter configuration
+     * @param config New configuration options
+     */
+    configure(config) {
+        this.config = { ...this.config, ...config };
+        // Restart cleanup timer if interval changed
+        if (config.cleanupInterval !== undefined) {
+            this.startCleanupTimer();
+        }
+    }
+    /**
+     * Get current configuration
+     * @returns Current rate limit configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Reset all rate limits
+     */
+    reset() {
+        this.limits.clear();
+        logger.debug('Rate limiter reset, all limits cleared');
+    }
+    /**
+     * Check if a request exceeds the rate limit
+     * @param key Unique identifier for the request source
+     * @param context Optional request context
+     * @throws {McpError} If rate limit is exceeded
+     */
+    check(key, context) {
+        // Skip in development if configured
+        if (this.config.skipInDevelopment && process.env.NODE_ENV === 'development') {
+            return;
+        }
+        // Generate key using custom generator if provided
+        const limitKey = this.config.keyGenerator
+            ? this.config.keyGenerator(key, context)
+            : key;
+        const now = Date.now();
+        // Use a mutex-like approach for thread safety by safely getting and 
+        // manipulating the rate limit entry in an atomic operation
+        const limit = () => {
+            // Get current entry or create a new one if it doesn't exist or is expired
+            const entry = this.limits.get(limitKey);
+            // Create new entry or reset if expired
+            if (!entry || now >= entry.resetTime) {
+                const newEntry = {
+                    count: 1,
+                    resetTime: now + this.config.windowMs,
+                    key: limitKey
+                };
+                this.limits.set(limitKey, newEntry);
+                return newEntry;
+            }
+            // Check if limit exceeded
+            if (entry.count >= this.config.maxRequests) {
+                const waitTime = Math.ceil((entry.resetTime - now) / 1000);
+                const errorMessage = this.config.errorMessage?.replace('{waitTime}', waitTime.toString()) ||
+                    `Rate limit exceeded. Please try again in ${waitTime} seconds.`;
+                throw new McpError(BaseErrorCode.RATE_LIMITED, errorMessage, { waitTime, key: limitKey });
+            }
+            // Increment counter and return updated entry
+            entry.count++;
+            return entry;
+        };
+        // Execute the rate limiting logic
+        limit();
+    }
+    /**
+     * Get rate limit information for a key
+     * @param key The rate limit key
+     * @returns Current rate limit status or null if no record 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
+        };
+    }
+    /**
+     * Stop the cleanup timer when the limiter is no longer needed
+     */
+    dispose() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        // Clear all entries
+        this.limits.clear();
+    }
+}
+/** Default configuration */
+RateLimiter.DEFAULT_CONFIG = {
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 100, // 100 requests per window
+    errorMessage: 'Rate limit exceeded. Please try again in {waitTime} seconds.',
+    skipInDevelopment: false,
+    cleanupInterval: 5 * 60 * 1000 // 5 minutes
+};
+/**
+ * Create and export a default rate limiter instance
+ */
+export const rateLimiter = new RateLimiter({
+    windowMs: 15 * 60 * 1000, // 15 minutes
+    maxRequests: 100 // 100 requests per window
+});
+// Export default
+export default {
+    RateLimiter,
+    rateLimiter
+};

package/dist/utils/requestContext.d.ts

@@ -0,0 +1,68 @@
+import { RequestContext } from './rateLimiter.js';
+/**
+ * Configuration interface for request context utilities
+ */
+export interface ContextConfig {
+    /** Custom configuration properties */
+    [key: string]: unknown;
+}
+/**
+ * Operation context with request data
+ */
+export interface OperationContext {
+    /** Request context data */
+    requestContext?: RequestContext;
+    /** Custom context properties */
+    [key: string]: unknown;
+}
+/**
+ * Request context utilities class
+ */
+export declare class RequestContextService {
+    private static instance;
+    private config;
+    /**
+     * Private constructor to enforce singleton pattern
+     */
+    private constructor();
+    /**
+     * Get the singleton RequestContextService instance
+     * @returns RequestContextService instance
+     */
+    static getInstance(): RequestContextService;
+    /**
+     * Configure service settings
+     * @param config New configuration
+     * @returns Updated configuration
+     */
+    configure(config: Partial<ContextConfig>): ContextConfig;
+    /**
+     * Get current configuration
+     * @returns Current configuration
+     */
+    getConfig(): ContextConfig;
+    /**
+     * Create a request context with unique ID and timestamp
+     * @param additionalContext Additional context properties
+     * @returns Request context object
+     */
+    createRequestContext(additionalContext?: Record<string, unknown>): RequestContext;
+    /**
+     * Generate a secure random string
+     * @param length Length of the string
+     * @param chars Character set to use
+     * @returns Random string
+     */
+    generateSecureRandomString(length?: number, chars?: string): string;
+}
+export declare const requestContextService: RequestContextService;
+export declare const configureContext: (config: Partial<ContextConfig>) => ContextConfig;
+export declare const createRequestContext: (additionalContext?: Record<string, unknown>) => RequestContext;
+export declare const generateSecureRandomString: (length?: number, chars?: string) => string;
+declare const _default: {
+    requestContextService: RequestContextService;
+    configureContext: (config: Partial<ContextConfig>) => ContextConfig;
+    createRequestContext: (additionalContext?: Record<string, unknown>) => RequestContext;
+    generateSecureRandomString: (length?: number, chars?: string) => string;
+};
+export default _default;