@wgtechlabs/log-engine
Version:
A lightweight, security-first logging utility with automatic data redaction for Node.js applications - the first logging library with built-in PII protection.
159 lines • 5.92 kB
TypeScript
/**
* Advanced output handlers for log-engine
* Provides file, HTTP, and other production-ready output handlers
*/
import * as fs from 'fs';
import type { FileOutputConfig, HttpOutputConfig } from '../types';
/**
* Secure filesystem operations for logging operations
*
* SECURITY NOTE: These functions implement comprehensive path validation and access controls
* to prevent path traversal attacks, directory injection, and unauthorized file access.
* ESLint security rules are disabled for specific fs operations because:
*
* 1. All paths are validated through validatePath() which:
* - Prevents directory traversal (../)
* - Restricts access to predefined safe directories
* - Blocks access to system directories
* - Normalizes and resolves paths securely
*
* 2. The logging library requires dynamic file paths by design (user-configurable log files)
* 3. All operations are wrapped in try-catch with comprehensive error handling
* 4. File operations are restricted to log and temp directories only
*/
/**
* Predefined safe base directories for different operation types
* Restricted to specific subdirectories to prevent unauthorized access
*/
declare const SAFE_BASE_DIRS: {
readonly LOG_FILES: readonly [string, string, string];
readonly TEMP_FILES: readonly [string, string, string, string];
readonly CONFIG_FILES: readonly [string, string, string];
};
/**
* Validates file path with comprehensive security checks
* Prevents path traversal, restricts to safe directories, blocks system paths
*/
declare function validatePath(filePath: string): string;
/**
* Secure file existence check
* Uses fs.accessSync instead of fs.existsSync for better security practices
*/
declare function secureExistsSync(filePath: string): boolean;
/**
* Secure directory creation with recursive option support
* Restricted to log and temp directories only
*/
declare function secureMkdirSync(dirPath: string, options?: {
recursive?: boolean;
}): void;
/**
* Secure file stat operation
* Returns file system statistics for validated paths only
*/
declare function secureStatSync(filePath: string): fs.Stats;
/**
* Secure file write operation
* Validates path and data before writing to prevent injection attacks
*/
declare function secureWriteFileSync(filePath: string, data: string, options?: {
flag?: string;
}): void;
/**
* Secure file deletion
* Restricted to log and temp files only for safety
*/
declare function secureUnlinkSync(filePath: string): void;
/**
* Secure file rename/move operation
* Both source and destination must be in safe directories
*/
declare function secureRenameSync(oldPath: string, newPath: string): void;
/**
* File output handler with rotation support and concurrency protection
* Implements atomic file operations and write queuing to prevent corruption
*/
export declare class FileOutputHandler {
private config;
private currentFileSize;
private rotationInProgress;
private writeQueue;
constructor(config: FileOutputConfig);
/**
* Default formatter for file output
*/
private defaultFormatter;
/**
* Write log to file with rotation support and concurrency protection
* Queues writes during rotation to prevent file corruption
*/
write: (level: string, message: string, data?: unknown) => void;
/**
* Write to file with concurrency protection and rotation check
* If rotation is in progress, messages are queued to prevent corruption
*/
private writeToFile;
/**
* Process queued writes after rotation completes
*/
private processWriteQueue;
/**
* Rotate log files when size limit is reached
* Implements concurrency protection to prevent corruption during rotation
*/
private rotateFile;
/**
* Clean up resources and process any remaining queued writes
*/
destroy(): void;
}
/**
* HTTP output handler for sending logs to remote endpoints
*/
export declare class HttpOutputHandler {
private config;
private logBuffer;
private flushTimeout;
constructor(config: HttpOutputConfig);
/**
* Default formatter for HTTP output
*/
private defaultFormatter;
/**
* Write log to HTTP endpoint with batching support
*/
write: (level: string, message: string, data?: unknown) => void;
/**
* Flush buffered logs to HTTP endpoint
*/
private flush;
/**
* Send HTTP request with appropriate method based on environment
*/
private sendHttpRequest;
/**
* Fallback HTTP implementation for Node.js environments without fetch
*/
private sendHttpRequestNodeJS;
/**
* Cleanup method to prevent memory leaks
*/
destroy(): void;
}
/**
* Returns a logging handler function based on the specified type and configuration.
*
* Supported types are:
* - `'console'`: Logs to the console using the appropriate method for the log level.
* - `'silent'`: Returns a no-op handler that discards all logs.
* - `'file'`: Writes logs to a file with optional rotation; requires `filePath` in config.
* - `'http'`: Sends logs to a remote HTTP endpoint; requires `url` in config.
*
* If required configuration is missing or initialization fails, logs an error and returns either a fallback handler or `null`.
*
* @param type - The type of output handler to create (`'console'`, `'silent'`, `'file'`, or `'http'`)
* @returns A log handler function or `null` if the handler cannot be created
*/
export declare function createBuiltInHandler(type: string, config?: Record<string, unknown>): ((level: string, message: string, data?: unknown) => void) | null;
export { secureExistsSync, secureMkdirSync, secureStatSync, secureWriteFileSync, secureUnlinkSync, secureRenameSync, validatePath, SAFE_BASE_DIRS };
//# sourceMappingURL=advanced-outputs.d.ts.map