@jablum/weather-mcp 1.7.0

package/dist/analytics/anonymizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Data anonymization utilities for privacy-first analytics
+ * Ensures no PII is collected as per docs/ANALYTICS_MCP_PLAN.md
+ */
+import { AnalyticsEvent, AnalyticsLevel } from './types.js';
+/**
+ * Raw event data before anonymization
+ * Includes all possible fields that might be collected
+ */
+interface RawEventData {
+    version: string;
+    tool: string;
+    status: 'success' | 'error';
+    timestamp_hour: string;
+    analytics_level?: AnalyticsLevel;
+    error_type?: string;
+    response_time_ms?: number;
+    service?: string;
+    cache_hit?: boolean;
+    retry_count?: number;
+    country?: string;
+    parameters?: Record<string, unknown>;
+    session_id?: string;
+    sequence_number?: number;
+}
+/**
+ * Anonymize event data based on analytics level
+ * Strips sensitive information and ensures privacy compliance
+ */
+export declare function anonymizeEvent(rawData: RawEventData, level: AnalyticsLevel, salt?: string): AnalyticsEvent;
+/**
+ * Round timestamp to nearest hour for privacy
+ * Prevents precise user tracking
+ */
+export declare function roundToHour(date: Date): string;
+export {};
+//# sourceMappingURL=anonymizer.d.ts.map

package/dist/analytics/anonymizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymizer.d.ts","sourceRoot":"","sources":["../../src/analytics/anonymizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA0ChB;AAiED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI9C"}

package/dist/analytics/anonymizer.js

@@ -0,0 +1,112 @@
+/**
+ * Data anonymization utilities for privacy-first analytics
+ * Ensures no PII is collected as per docs/ANALYTICS_MCP_PLAN.md
+ */
+import crypto from 'crypto';
+/**
+ * Anonymize event data based on analytics level
+ * Strips sensitive information and ensures privacy compliance
+ */
+export function anonymizeEvent(rawData, level, salt) {
+    // Base event (minimal level) - always included
+    const baseEvent = {
+        version: rawData.version,
+        tool: rawData.tool,
+        status: rawData.status,
+        timestamp_hour: rawData.timestamp_hour,
+        analytics_level: 'minimal',
+        ...(rawData.status === 'error' && rawData.error_type ? { error_type: rawData.error_type } : {}),
+    };
+    // Return minimal level (no additional data)
+    if (level === 'minimal') {
+        return baseEvent;
+    }
+    // Standard level - add performance metrics
+    const standardEvent = {
+        ...baseEvent,
+        analytics_level: 'standard',
+        ...(rawData.response_time_ms !== undefined && { response_time_ms: rawData.response_time_ms }),
+        ...(rawData.service && { service: rawData.service }),
+        ...(rawData.cache_hit !== undefined && { cache_hit: rawData.cache_hit }),
+        ...(rawData.retry_count !== undefined && { retry_count: rawData.retry_count }),
+        ...(rawData.country && { country: rawData.country }),
+    };
+    // Return standard level
+    if (level === 'standard') {
+        return standardEvent;
+    }
+    // Detailed level - add anonymized workflow data
+    const detailedEvent = {
+        ...standardEvent,
+        analytics_level: 'detailed',
+        ...(rawData.parameters && { parameters: sanitizeParameters(rawData.parameters) }),
+        ...(rawData.session_id && { session_id: hashSessionId(rawData.session_id, salt) }),
+        ...(rawData.sequence_number !== undefined && { sequence_number: rawData.sequence_number }),
+    };
+    return detailedEvent;
+}
+/**
+ * Sanitize tool parameters - ONLY keep safe, non-identifying values
+ * NEVER include: coordinates, location names, user input
+ */
+function sanitizeParameters(params) {
+    const safe = {};
+    // Allowlist of safe parameters that don't contain PII
+    const allowedParams = [
+        'days',
+        'granularity',
+        'source',
+        'forecast_type',
+        'include_normals',
+        'include_fire_weather',
+        'include_severe_weather',
+        'active_only',
+        'limit',
+        'radius',
+        'units',
+        'hourly',
+        'daily',
+    ];
+    for (const key of allowedParams) {
+        if (params[key] !== undefined) {
+            // Only include primitive values (no objects/arrays that might contain PII)
+            const value = params[key];
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                safe[key] = value;
+            }
+        }
+    }
+    // NEVER include these (blocklist for extra safety):
+    // - latitude, longitude, lat, lon
+    // - location, address, city, state, zip, postal_code
+    // - user, name, email, phone
+    // - any user-provided strings
+    return safe;
+}
+/**
+ * Create one-way hash of session ID
+ * Cannot be reversed to identify users
+ */
+function hashSessionId(sessionId, salt) {
+    // Salt should always be provided by config (auto-generated)
+    // Fallback to environment variable if somehow not provided
+    const sessionSalt = salt || process.env.ANALYTICS_SALT || '';
+    if (!sessionSalt) {
+        throw new Error('Analytics salt must be provided for session ID hashing');
+    }
+    return crypto
+        .createHash('sha256')
+        .update(sessionId + sessionSalt)
+        .digest('hex')
+        .substring(0, 16); // Shortened for storage efficiency
+}
+/**
+ * Round timestamp to nearest hour for privacy
+ * Prevents precise user tracking
+ */
+export function roundToHour(date) {
+    const rounded = new Date(date);
+    rounded.setMinutes(0, 0, 0);
+    return rounded.toISOString();
+}
+//# sourceMappingURL=anonymizer.js.map

package/dist/analytics/anonymizer.js.map

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

package/dist/analytics/collector.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Analytics event collector and batch manager
+ * Buffers events in memory and periodically flushes to analytics server
+ */
+import { AnalyticsConfig, ToolExecutionMetadata } from './types.js';
+/**
+ * AnalyticsCollector - Manages event buffering and batch sending
+ * Implements privacy-first analytics with automatic flushing
+ */
+export declare class AnalyticsCollector {
+    private buffer;
+    private config;
+    private flushTimer;
+    private sessionId;
+    private sequenceNumber;
+    private isShuttingDown;
+    private consecutiveFailures;
+    private circuitOpen;
+    private circuitOpenUntil;
+    private readonly MAX_CONSECUTIVE_FAILURES;
+    private readonly CIRCUIT_BREAKER_RESET_MS;
+    private errorCount;
+    private successCount;
+    private readonly ERROR_THRESHOLD;
+    private lastFlushTime;
+    private flushCount;
+    private readonly MIN_FLUSH_INTERVAL_MS;
+    private readonly MAX_FLUSHES_PER_HOUR;
+    private readonly MAX_EVENTS_PER_MINUTE;
+    private recentEventTimestamps;
+    private readonly MAX_BUFFER_SIZE;
+    private readonly FLUSH_INTERVAL_MS;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Track a tool execution event
+     * Fails silently - analytics should never break the application
+     */
+    trackToolCall(tool: string, status: 'success' | 'error', metadata?: ToolExecutionMetadata): Promise<void>;
+    /**
+     * Flush buffered events to analytics server
+     * Called automatically on timer or when buffer is full
+     * Implements circuit breaker pattern (3.7)
+     */
+    flush(): Promise<void>;
+    /**
+     * Start periodic flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop flush timer
+     */
+    private stopFlushTimer;
+    /**
+     * Generate unique session ID
+     * Used for tracking tool call sequences in detailed mode
+     */
+    private generateSessionId;
+    /**
+     * Public shutdown method called by main shutdown handler
+     * Ensures buffered events are sent before process exits
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current buffer size (for testing)
+     */
+    getBufferSize(): number;
+    /**
+     * Get session ID (for testing)
+     */
+    getSessionId(): string;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/analytics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/analytics/collector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,eAAe,EAAkB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEpF;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAiB;IAG1D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAM;IAGtC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAC3C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAM;IAC5C,OAAO,CAAC,qBAAqB,CAAgB;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAO;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEvC,MAAM,EAAE,eAAe;IAanC;;;OAGG;IACU,aAAa,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,GAAG,OAAO,EAC3B,QAAQ,GAAE,qBAA0B,GACnC,OAAO,CAAC,IAAI,CAAC;IA+GhB;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6EnC;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtC;;OAEG;IACI,aAAa,IAAI,MAAM;IAI9B;;OAEG;IACI,YAAY,IAAI,MAAM;CAG9B"}

package/dist/analytics/collector.js

@@ -0,0 +1,282 @@
+/**
+ * Analytics event collector and batch manager
+ * Buffers events in memory and periodically flushes to analytics server
+ */
+import crypto from 'crypto';
+import { logger } from '../utils/logger.js';
+import { anonymizeEvent, roundToHour } from './anonymizer.js';
+import { sendBatch } from './transport.js';
+/**
+ * AnalyticsCollector - Manages event buffering and batch sending
+ * Implements privacy-first analytics with automatic flushing
+ */
+export class AnalyticsCollector {
+    buffer = [];
+    config;
+    flushTimer = null;
+    sessionId;
+    sequenceNumber = 0;
+    isShuttingDown = false;
+    // Rate limiting state
+    consecutiveFailures = 0;
+    circuitOpen = false;
+    circuitOpenUntil = null;
+    MAX_CONSECUTIVE_FAILURES = 5;
+    CIRCUIT_BREAKER_RESET_MS = 5 * 60 * 1000; // 5 minutes
+    // Error tracking for health monitoring
+    errorCount = 0;
+    successCount = 0;
+    ERROR_THRESHOLD = 10; // Alert after 10 consecutive failures
+    // Rate limiting for event collection
+    lastFlushTime = 0;
+    flushCount = 0;
+    MIN_FLUSH_INTERVAL_MS = 30000; // 30 seconds minimum between flushes
+    MAX_FLUSHES_PER_HOUR = 20;
+    MAX_EVENTS_PER_MINUTE = 60;
+    recentEventTimestamps = [];
+    MAX_BUFFER_SIZE = 100;
+    FLUSH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+    constructor(config) {
+        this.config = config;
+        this.sessionId = this.generateSessionId();
+        if (this.config.enabled) {
+            this.startFlushTimer();
+            logger.debug('Analytics collector initialized', {
+                level: this.config.level,
+                endpoint: this.config.endpoint,
+            });
+        }
+    }
+    /**
+     * Track a tool execution event
+     * Fails silently - analytics should never break the application
+     */
+    async trackToolCall(tool, status, metadata = {}) {
+        if (!this.config.enabled || this.isShuttingDown) {
+            return;
+        }
+        try {
+            // SECURITY: Rate limit event collection (M-3)
+            const now = Date.now();
+            this.recentEventTimestamps.push(now);
+            // Remove timestamps older than 1 minute
+            this.recentEventTimestamps = this.recentEventTimestamps.filter(ts => now - ts < 60000);
+            // Check rate limit
+            if (this.recentEventTimestamps.length > this.MAX_EVENTS_PER_MINUTE) {
+                logger.warn('Analytics rate limit exceeded, dropping event', {
+                    tool,
+                    eventsPerMinute: this.recentEventTimestamps.length,
+                    securityEvent: true
+                });
+                return;
+            }
+            // Increment sequence number for detailed level
+            if (this.config.level === 'detailed') {
+                this.sequenceNumber++;
+            }
+            // Build raw event data
+            const rawData = {
+                version: this.config.version,
+                tool,
+                status,
+                timestamp_hour: roundToHour(new Date()),
+                analytics_level: this.config.level,
+                error_type: metadata.error_type,
+                response_time_ms: metadata.response_time_ms,
+                service: metadata.service,
+                cache_hit: metadata.cache_hit,
+                retry_count: metadata.retry_count,
+                country: metadata.country,
+                parameters: metadata.parameters,
+                session_id: undefined,
+                sequence_number: undefined,
+            };
+            // Add session tracking for detailed level
+            if (this.config.level === 'detailed') {
+                rawData.session_id = this.sessionId;
+                rawData.sequence_number = this.sequenceNumber;
+            }
+            // Anonymize event based on configured level (pass salt for session hashing)
+            const event = anonymizeEvent(rawData, this.config.level, this.config.salt);
+            // Add to buffer
+            this.buffer.push(event);
+            this.successCount++;
+            this.errorCount = 0; // Reset on success (L-2)
+            logger.debug('Analytics event tracked', {
+                tool,
+                status,
+                bufferSize: this.buffer.length,
+            });
+            // Flush if buffer is full (with rate limiting)
+            // Flush asynchronously to avoid blocking tool requests
+            if (this.buffer.length >= this.MAX_BUFFER_SIZE) {
+                const timeSinceLastFlush = now - this.lastFlushTime;
+                if (timeSinceLastFlush < this.MIN_FLUSH_INTERVAL_MS) {
+                    logger.warn('Analytics flush rate limit hit, delaying', {
+                        timeSinceLastFlush,
+                        bufferSize: this.buffer.length,
+                        securityEvent: true
+                    });
+                    return; // Don't flush, will be picked up by timer
+                }
+                // Schedule flush asynchronously to not block the tool request
+                setImmediate(() => {
+                    this.flush().catch((err) => {
+                        logger.warn('Async analytics flush error', {
+                            error: err instanceof Error ? err.message : 'Unknown error',
+                        });
+                    });
+                });
+            }
+        }
+        catch (error) {
+            // Fail silently - analytics should never break the application
+            this.errorCount++;
+            logger.warn('Analytics tracking error', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                tool,
+                consecutiveErrors: this.errorCount
+            });
+            // MONITORING: Alert on persistent failures (L-2)
+            if (this.errorCount >= this.ERROR_THRESHOLD) {
+                logger.error('Analytics system appears to be failing consistently', undefined, {
+                    consecutiveErrors: this.errorCount,
+                    successCount: this.successCount,
+                    securityEvent: true
+                });
+            }
+        }
+    }
+    /**
+     * Flush buffered events to analytics server
+     * Called automatically on timer or when buffer is full
+     * Implements circuit breaker pattern (3.7)
+     */
+    async flush() {
+        if (!this.config.enabled || this.buffer.length === 0) {
+            return;
+        }
+        // Check circuit breaker (3.7)
+        if (this.circuitOpen) {
+            if (this.circuitOpenUntil && new Date() < this.circuitOpenUntil) {
+                logger.debug('Analytics circuit breaker open, skipping flush', {
+                    resetAt: this.circuitOpenUntil.toISOString(),
+                });
+                this.buffer = []; // Drop buffered events to prevent memory leak
+                return;
+            }
+            else {
+                // Try to close circuit
+                logger.info('Analytics circuit breaker attempting reset');
+                this.circuitOpen = false;
+                this.circuitOpenUntil = null;
+                this.consecutiveFailures = 0;
+            }
+        }
+        const eventsToSend = [...this.buffer];
+        this.buffer = [];
+        // Track flush for rate limiting (M-3)
+        const now = Date.now();
+        this.lastFlushTime = now;
+        this.flushCount++;
+        // Reset counter every hour
+        if (this.flushCount > this.MAX_FLUSHES_PER_HOUR) {
+            logger.warn('Analytics flush count exceeded hourly limit', {
+                flushCount: this.flushCount,
+                securityEvent: true
+            });
+            // Continue but log for monitoring
+        }
+        try {
+            logger.debug('Flushing analytics batch', {
+                count: eventsToSend.length,
+            });
+            await sendBatch(eventsToSend, this.config.endpoint, this.config.version);
+            logger.debug('Analytics batch sent successfully', {
+                count: eventsToSend.length,
+            });
+            // Reset failure counter on success (3.7)
+            this.consecutiveFailures = 0;
+        }
+        catch (error) {
+            this.consecutiveFailures++;
+            logger.warn('Analytics batch send failed', {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                count: eventsToSend.length,
+                consecutiveFailures: this.consecutiveFailures,
+            });
+            // Open circuit if too many failures (3.7)
+            if (this.consecutiveFailures >= this.MAX_CONSECUTIVE_FAILURES) {
+                this.circuitOpen = true;
+                this.circuitOpenUntil = new Date(Date.now() + this.CIRCUIT_BREAKER_RESET_MS);
+                logger.error('Analytics circuit breaker opened', undefined, {
+                    consecutiveFailures: this.consecutiveFailures,
+                    resetAt: this.circuitOpenUntil.toISOString(),
+                    securityEvent: true,
+                });
+            }
+            // Don't re-queue events to avoid memory buildup
+        }
+    }
+    /**
+     * Start periodic flush timer
+     */
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => {
+            this.flush().catch((err) => {
+                logger.warn('Analytics flush timer error', {
+                    error: err instanceof Error ? err.message : 'Unknown error',
+                });
+            });
+        }, this.FLUSH_INTERVAL_MS);
+        // Don't prevent process exit
+        this.flushTimer.unref();
+    }
+    /**
+     * Stop flush timer
+     */
+    stopFlushTimer() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /**
+     * Generate unique session ID
+     * Used for tracking tool call sequences in detailed mode
+     */
+    generateSessionId() {
+        return crypto.randomBytes(16).toString('hex');
+    }
+    /**
+     * Public shutdown method called by main shutdown handler
+     * Ensures buffered events are sent before process exits
+     */
+    async shutdown() {
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        logger.debug('Analytics shutdown initiated', {
+            bufferSize: this.buffer.length,
+        });
+        this.stopFlushTimer();
+        // Flush remaining events
+        if (this.buffer.length > 0) {
+            await this.flush();
+        }
+    }
+    /**
+     * Get current buffer size (for testing)
+     */
+    getBufferSize() {
+        return this.buffer.length;
+    }
+    /**
+     * Get session ID (for testing)
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/analytics/collector.js.map

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

package/dist/analytics/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Analytics configuration and singleton collector instance
+ * Loads settings from environment variables with secure defaults
+ */
+import { AnalyticsCollector } from './collector.js';
+/**
+ * Singleton analytics collector instance
+ * Exported for use throughout the application
+ */
+export declare const analytics: AnalyticsCollector;
+/**
+ * Re-export types for convenience
+ */
+export type { AnalyticsLevel, ToolExecutionMetadata } from './types.js';
+//# sourceMappingURL=config.d.ts.map

package/dist/analytics/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/analytics/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AA+KpD;;;GAGG;AACH,eAAO,MAAM,SAAS,oBAAgD,CAAC;AAEvE;;GAEG;AACH,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}