timonel 3.1.1 → 3.1.2

package/dist/lib/utils/logger.d.ts

@@ -1,49 +1,202 @@
+/**
+ * @fileoverview High-performance structured logging system for Timonel using Pino
+ * Provides centralized, type-safe logging with performance optimizations and security features
+ * @since 2.10.3
+ */
+/**
+ * Standard log levels following syslog conventions
+ * @since 2.10.3
+ */
 export declare enum LogLevel {
+    /** System is unusable - immediate action required */
     FATAL = 60,
+    /** Error conditions that need immediate attention */
     ERROR = 50,
+    /** Warning conditions that should be monitored */
     WARN = 40,
+    /** General informational messages */
     INFO = 30,
+    /** Debug information for troubleshooting */
     DEBUG = 20,
+    /** Detailed trace information */
     TRACE = 10
 }
+/**
+ * Configuration options for the logging system
+ * @since 2.10.3
+ */
 export interface LoggerConfig {
+    /** Minimum log level to output */
     level: LogLevel;
+    /** Whether to suppress all log output */
     silent: boolean;
+    /** Service name for structured logging */
     service: string;
+    /** Environment (development, staging, production) */
     environment: string;
+    /** Whether to enable pretty printing in development */
     prettyPrint: boolean;
+    /** Additional base fields to include in all logs */
     base?: Record<string, unknown>;
 }
+/**
+ * Contextual information to include with log entries
+ * @since 2.10.3
+ */
 export interface LogContext {
+    /** Unique identifier for request tracing */
     correlationId?: string;
+    /** User identifier for audit trails */
     userId?: string;
+    /** Operation being performed */
     operation?: string;
+    /** Component or module name */
     component?: string;
+    /** Chart or resource name */
     chartName?: string;
+    /** Additional structured data */
     [key: string]: unknown;
 }
+/**
+ * High-performance structured logger implementation using Pino
+ * Provides type-safe logging with security features and performance optimization
+ * @since 2.10.3
+ */
 export declare class TimonelLogger {
     private readonly logger;
     private readonly config;
     private static readonly SENSITIVE_FIELDS;
     constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Maps internal log levels to Pino log levels
+     * @param level - Internal log level
+     * @returns Pino-compatible log level string
+     * @since 2.10.3
+     */
     private mapLogLevel;
+    /**
+     * Safe request serializer that removes sensitive data
+     * @param req - HTTP request object
+     * @returns Sanitized request data
+     * @since 2.10.3
+     */
     private requestSerializer;
+    /**
+     * Safe response serializer
+     * @param res - HTTP response object
+     * @returns Sanitized response data
+     * @since 2.10.3
+     */
     private responseSerializer;
+    /**
+     * Log a fatal error - system is unusable
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     fatal(message: string, context?: LogContext): void;
+    /**
+     * Log an error that needs immediate attention
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     error(message: string, context?: LogContext): void;
+    /**
+     * Log a warning condition
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     warn(message: string, context?: LogContext): void;
+    /**
+     * Log general informational message
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     info(message: string, context?: LogContext): void;
+    /**
+     * Log debug information
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     debug(message: string, context?: LogContext): void;
+    /**
+     * Log detailed trace information
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     trace(message: string, context?: LogContext): void;
+    /**
+     * Internal logging method with security sanitization
+     * @param level - Log level
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     private log;
+    /**
+     * Sanitizes context object to prevent data leaks
+     * @param context - Context object to sanitize
+     * @returns Sanitized context object
+     * @since 2.10.3
+     */
     private sanitizeContext;
+    /**
+     * Sanitizes nested objects with depth limiting
+     * @param obj - Object to sanitize
+     * @param depth - Maximum recursion depth
+     * @returns Sanitized object
+     * @since 2.10.3
+     */
     private sanitizeNestedObject;
+    /**
+     * Creates a child logger with additional context
+     * This is highly optimized in Pino for performance
+     * @param context - Additional context to bind to child logger
+     * @returns New logger instance with bound context
+     * @since 2.10.3
+     */
     child(context: LogContext): TimonelLogger;
+    /**
+     * Measures operation duration for performance monitoring
+     * @param operation - Operation name
+     * @returns Function to call when operation completes
+     * @since 2.10.3
+     */
     time(operation: string): () => void;
+    /**
+     * Updates the log level at runtime
+     * @param level - New log level
+     * @since 2.10.3
+     */
     setLevel(level: LogLevel): void;
+    /**
+     * Enables or disables silent mode
+     * @param silent - Whether to suppress all output
+     * @since 2.10.3
+     */
     setSilent(silent: boolean): void;
+    /**
+     * Flushes any pending log entries (important for async logging)
+     * @since 2.10.3
+     */
     flush(): Promise<void>;
 }
+/**
+ * Global logger instance for the Timonel application
+ * Configured based on environment variables
+ * @since 2.10.3
+ */
 export declare const logger: TimonelLogger;
+/**
+ * Factory function for creating component-specific loggers
+ * @param component - Component name
+ * @param additionalConfig - Additional configuration
+ * @returns Configured logger instance
+ * @since 2.10.3
+ */
 export declare function createLogger(component: string, additionalConfig?: Partial<LoggerConfig>): TimonelLogger;

package/dist/lib/utils/logger.js

@@ -1,14 +1,34 @@
+/**
+ * @fileoverview High-performance structured logging system for Timonel using Pino
+ * Provides centralized, type-safe logging with performance optimizations and security features
+ * @since 2.10.3
+ */
 import pino from 'pino';
 import { SecurityUtils } from '../security.js';
+/**
+ * Standard log levels following syslog conventions
+ * @since 2.10.3
+ */
 export var LogLevel;
 (function (LogLevel) {
+    /** System is unusable - immediate action required */
     LogLevel[LogLevel["FATAL"] = 60] = "FATAL";
+    /** Error conditions that need immediate attention */
     LogLevel[LogLevel["ERROR"] = 50] = "ERROR";
+    /** Warning conditions that should be monitored */
     LogLevel[LogLevel["WARN"] = 40] = "WARN";
+    /** General informational messages */
     LogLevel[LogLevel["INFO"] = 30] = "INFO";
+    /** Debug information for troubleshooting */
     LogLevel[LogLevel["DEBUG"] = 20] = "DEBUG";
+    /** Detailed trace information */
     LogLevel[LogLevel["TRACE"] = 10] = "TRACE";
 })(LogLevel || (LogLevel = {}));
+/**
+ * High-performance structured logger implementation using Pino
+ * Provides type-safe logging with security features and performance optimization
+ * @since 2.10.3
+ */
 export class TimonelLogger {
     constructor(config = {}) {
         this.config = {
@@ -28,8 +48,10 @@ export class TimonelLogger {
                 ...this.config.base,
             },
             timestamp: pino.stdTimeFunctions.isoTime,
+            // Security: redact sensitive fields (CWE-532 prevention)
             redact: {
                 paths: [
+                    // Generic secrets
                     'password',
                     'passphrase',
                     'secret',
@@ -70,6 +92,7 @@ export class TimonelLogger {
                     'pem',
                     'p12',
                     'pfx',
+                    // Nested (one level)
                     '*.password',
                     '*.passphrase',
                     '*.secret',
@@ -110,6 +133,7 @@ export class TimonelLogger {
                     '*.pem',
                     '*.p12',
                     '*.pfx',
+                    // HTTP specifics (request/response shapes)
                     'req.headers.authorization',
                     'req.headers.cookie',
                     'req.headers.cookies',
@@ -119,6 +143,7 @@ export class TimonelLogger {
                     'req.headers["x-auth-token"]',
                     'res.headers["set-cookie"]',
                     'res.headers["authorization"]',
+                    // Common payload locations
                     'body.password',
                     'body.token',
                     'body.apiKey',
@@ -128,6 +153,7 @@ export class TimonelLogger {
                     'query.token',
                     'query.apiKey',
                     'query.secret',
+                    // Configuration objects
                     'config.password',
                     'config.secret',
                     'config.clientSecret',
@@ -137,12 +163,15 @@ export class TimonelLogger {
                 censor: '[REDACTED]',
             },
             serializers: {
+                // Optimized error serialization
                 err: pino.stdSerializers.err,
                 error: pino.stdSerializers.err,
+                // Custom serializers for security
                 req: this.requestSerializer,
                 res: this.responseSerializer,
             },
         };
+        // Pretty printing for development
         if (this.config.prettyPrint && this.config.environment === 'development') {
             this.logger = pino({
                 ...pinoOptions,
@@ -161,6 +190,12 @@ export class TimonelLogger {
             this.logger = pino(pinoOptions);
         }
     }
+    /**
+     * Maps internal log levels to Pino log levels
+     * @param level - Internal log level
+     * @returns Pino-compatible log level string
+     * @since 2.10.3
+     */
     mapLogLevel(level) {
         switch (level) {
             case LogLevel.FATAL:
@@ -179,6 +214,12 @@ export class TimonelLogger {
                 return 'info';
         }
     }
+    /**
+     * Safe request serializer that removes sensitive data
+     * @param req - HTTP request object
+     * @returns Sanitized request data
+     * @since 2.10.3
+     */
     requestSerializer(req) {
         try {
             if (!req || typeof req !== 'object')
@@ -190,6 +231,7 @@ export class TimonelLogger {
                 headers: {
                     'user-agent': request.headers?.['user-agent'],
                     'content-type': request.headers?.['content-type'],
+                    // Exclude sensitive headers
                 },
                 remoteAddress: request.remoteAddress,
                 remotePort: request.remotePort,
@@ -199,6 +241,12 @@ export class TimonelLogger {
             return {};
         }
     }
+    /**
+     * Safe response serializer
+     * @param res - HTTP response object
+     * @returns Sanitized response data
+     * @since 2.10.3
+     */
     responseSerializer(res) {
         if (!res || typeof res !== 'object')
             return {};
@@ -211,34 +259,81 @@ export class TimonelLogger {
             },
         };
     }
+    /**
+     * Log a fatal error - system is unusable
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     fatal(message, context) {
         this.log(LogLevel.FATAL, message, context);
     }
+    /**
+     * Log an error that needs immediate attention
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     error(message, context) {
         this.log(LogLevel.ERROR, message, context);
     }
+    /**
+     * Log a warning condition
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     warn(message, context) {
         this.log(LogLevel.WARN, message, context);
     }
+    /**
+     * Log general informational message
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     info(message, context) {
         this.log(LogLevel.INFO, message, context);
     }
+    /**
+     * Log debug information
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     debug(message, context) {
         this.log(LogLevel.DEBUG, message, context);
     }
+    /**
+     * Log detailed trace information
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     trace(message, context) {
         this.log(LogLevel.TRACE, message, context);
     }
+    /**
+     * Internal logging method with security sanitization
+     * @param level - Log level
+     * @param message - Log message
+     * @param context - Additional context data
+     * @since 2.10.3
+     */
     log(level, message, context) {
         if (this.config.silent || level < this.config.level) {
             return;
         }
+        // Sanitize message for security
         const sanitizedMessage = SecurityUtils.sanitizeLogMessage(message);
+        // Sanitize and structure context
         const sanitizedContext = context ? this.sanitizeContext(context) : {};
+        // Add performance timing if available
         const logEntry = {
             ...sanitizedContext,
             timestamp: new Date().toISOString(),
         };
+        // Use appropriate Pino logging method
         switch (level) {
             case LogLevel.FATAL:
                 this.logger.fatal(logEntry, sanitizedMessage);
@@ -260,20 +355,32 @@ export class TimonelLogger {
                 break;
         }
     }
+    /**
+     * Sanitizes context object to prevent data leaks
+     * @param context - Context object to sanitize
+     * @returns Sanitized context object
+     * @since 2.10.3
+     */
     sanitizeContext(context) {
         try {
             const sanitized = {};
             for (const [key, value] of Object.entries(context)) {
                 if (TimonelLogger.SENSITIVE_FIELDS.has(key.toLowerCase())) {
+                    // eslint-disable-next-line security/detect-object-injection -- Safe: key from Object.entries
                     sanitized[key] = '[REDACTED]';
                 }
                 else if (typeof value === 'string') {
+                    // Safe assignment - key comes from Object.entries
+                    // eslint-disable-next-line security/detect-object-injection -- Safe: key from Object.entries
                     sanitized[key] = SecurityUtils.sanitizeLogMessage(value);
                 }
                 else if (value && typeof value === 'object') {
+                    // Recursively sanitize nested objects (limited depth)
+                    // eslint-disable-next-line security/detect-object-injection -- Safe: key from Object.entries
                     sanitized[key] = this.sanitizeNestedObject(value, 2);
                 }
                 else {
+                    // eslint-disable-next-line security/detect-object-injection -- Safe: key from Object.entries
                     sanitized[key] = value;
                 }
             }
@@ -283,6 +390,13 @@ export class TimonelLogger {
             return {};
         }
     }
+    /**
+     * Sanitizes nested objects with depth limiting
+     * @param obj - Object to sanitize
+     * @param depth - Maximum recursion depth
+     * @returns Sanitized object
+     * @since 2.10.3
+     */
     sanitizeNestedObject(obj, depth) {
         try {
             if (depth <= 0 || !obj || typeof obj !== 'object') {
@@ -291,12 +405,16 @@ export class TimonelLogger {
             const sanitized = {};
             for (const [key, value] of Object.entries(obj)) {
                 if (typeof value === 'string') {
+                    // Safe assignment - key comes from Object.entries
+                    // eslint-disable-next-line security/detect-object-injection
                     sanitized[key] = SecurityUtils.sanitizeLogMessage(value);
                 }
                 else if (value && typeof value === 'object') {
+                    // eslint-disable-next-line security/detect-object-injection
                     sanitized[key] = this.sanitizeNestedObject(value, depth - 1);
                 }
                 else {
+                    // eslint-disable-next-line security/detect-object-injection
                     sanitized[key] = value;
                 }
             }
@@ -306,9 +424,19 @@ export class TimonelLogger {
             return obj;
         }
     }
+    /**
+     * Creates a child logger with additional context
+     * This is highly optimized in Pino for performance
+     * @param context - Additional context to bind to child logger
+     * @returns New logger instance with bound context
+     * @since 2.10.3
+     */
     child(context) {
         const sanitizedContext = this.sanitizeContext(context);
+        // Create a new logger instance with the same config
         const childLogger = new TimonelLogger(this.config);
+        // Replace the internal logger with a Pino child logger using Object.defineProperty
+        // This is type-safe and prevents accidental modification
         Object.defineProperty(childLogger, 'logger', {
             value: this.logger.child(sanitizedContext),
             writable: false,
@@ -317,24 +445,41 @@ export class TimonelLogger {
         });
         return childLogger;
     }
+    /**
+     * Measures operation duration for performance monitoring
+     * @param operation - Operation name
+     * @returns Function to call when operation completes
+     * @since 2.10.3
+     */
     time(operation) {
         const start = process.hrtime.bigint();
         return () => {
             const end = process.hrtime.bigint();
-            const duration = Number(end - start) / 1000000;
+            const duration = Number(end - start) / 1000000; // Convert to milliseconds
             this.info('Operation completed', {
                 operation: SecurityUtils.sanitizeLogMessage(operation),
-                duration_ms: Math.round(duration * 100) / 100,
+                duration_ms: Math.round(duration * 100) / 100, // Round to 2 decimal places
                 performance: 'timing',
             });
         };
     }
+    /**
+     * Updates the log level at runtime
+     * @param level - New log level
+     * @since 2.10.3
+     */
     setLevel(level) {
         this.config.level = level;
         this.logger.level = this.mapLogLevel(level);
     }
+    /**
+     * Enables or disables silent mode
+     * @param silent - Whether to suppress all output
+     * @since 2.10.3
+     */
     setSilent(silent) {
         this.config.silent = silent;
+        // Pino doesn't have a direct silent property, we need to enable/disable the logger
         if (silent) {
             this.logger.level = 'silent';
         }
@@ -342,6 +487,10 @@ export class TimonelLogger {
             this.logger.level = this.mapLogLevel(this.config.level);
         }
     }
+    /**
+     * Flushes any pending log entries (important for async logging)
+     * @since 2.10.3
+     */
     async flush() {
         return new Promise((resolve) => {
             if (typeof this.logger.flush === 'function') {
@@ -353,6 +502,7 @@ export class TimonelLogger {
         });
     }
 }
+// Performance-optimized sensitive field detection using Set for O(1) lookups
 TimonelLogger.SENSITIVE_FIELDS = new Set([
     'password',
     'passphrase',
@@ -395,12 +545,24 @@ TimonelLogger.SENSITIVE_FIELDS = new Set([
     'p12',
     'pfx',
 ]);
+/**
+ * Global logger instance for the Timonel application
+ * Configured based on environment variables
+ * @since 2.10.3
+ */
 export const logger = new TimonelLogger({
     level: getLogLevelFromEnv(),
     silent: process.env.TIMONEL_SILENT === 'true',
     service: 'timonel',
     environment: process.env.NODE_ENV || 'development',
 });
+/**
+ * Factory function for creating component-specific loggers
+ * @param component - Component name
+ * @param additionalConfig - Additional configuration
+ * @returns Configured logger instance
+ * @since 2.10.3
+ */
 export function createLogger(component, additionalConfig) {
     return new TimonelLogger({
         ...additionalConfig,
@@ -411,6 +573,11 @@ export function createLogger(component, additionalConfig) {
         },
     });
 }
+/**
+ * Gets log level from environment variables
+ * @returns Log level based on environment
+ * @since 2.10.3
+ */
 function getLogLevelFromEnv() {
     const envLevel = process.env.LOG_LEVEL?.toUpperCase();
     switch (envLevel) {
@@ -428,6 +595,7 @@ function getLogLevelFromEnv() {
         case 'TRACE':
             return LogLevel.TRACE;
         default:
+            // Default to INFO in production, DEBUG in development
             return process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG;
     }
 }