ntlogger 2.10.0 → 4.0.0

package/contract/redaction.json

@@ -0,0 +1,115 @@
+{
+  "version": 1,
+  "keys": [
+    "password",
+    "passwd",
+    "pass",
+    "pwd",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "x-api-key",
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-device-installation-secret",
+    "installationsecret",
+    "privatekey",
+    "private_key",
+    "clientsecret",
+    "client_secret",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "idtoken",
+    "id_token",
+    "sessiontoken",
+    "credential",
+    "credentials",
+    "webhookurl",
+    "snmpcommunity",
+    "community_string",
+    "community",
+    "authPassword",
+    "privPassword",
+    "passphrase"
+  ],
+  "patterns": [
+    {
+      "source": "-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----[\\s\\S]*?-----END (?:[A-Z]+ )*PRIVATE KEY-----",
+      "flags": "g"
+    },
+    {
+      "source": "\\bAKIA[0-9A-Z]{16}\\b",
+      "flags": "g"
+    },
+    {
+      "source": "\\beyJ[A-Za-z0-9_-]{5,}\\.[A-Za-z0-9_-]{5,}\\.[A-Za-z0-9_-]{5,}",
+      "flags": "g"
+    },
+    {
+      "source": "\\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})",
+      "flags": "g"
+    },
+    {
+      "source": "\\bxox[abpors]-[A-Za-z0-9-]{10,}",
+      "flags": "gi"
+    },
+    {
+      "source": "\\b(?:[sr]k_(?:live|test)_[A-Za-z0-9]{10,}|whsec_[A-Za-z0-9]{10,})",
+      "flags": "g"
+    },
+    {
+      "source": "(?<pre>\\bBearer\\s+)[A-Za-z0-9\\-._~+/]{8,}={0,2}",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\bBasic\\s+)(?=[A-Za-z0-9+/]*[A-Z0-9])[A-Za-z0-9+/]{16,}={0,2}",
+      "flags": "g"
+    },
+    {
+      "source": "(?<pre>https?:\\/\\/(?:[a-z]+\\.)?discord(?:app)?\\.com\\/api\\/(?:v\\d+\\/)?webhooks\\/\\d+\\/)[A-Za-z0-9_-]+",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>[\"']?\\b(?:snmp[_-]?community|community(?:[_-]?string)?|auth[_-]?password|priv[_-]?password|passphrase)[\"']?\\s*[:=]\\s*)(?:\"(?:\\\\.|[^\"\\\\])*(?:\"|$)|'(?:\\\\.|[^'\\\\])*(?:'|$)|[^\\s,;}]+)",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b(?:api[_-]?key|apikey|access[_-]?key|access[_-]?token|refresh[_-]?token|secret[_-]?key|client[_-]?secret|password|passwd|pwd|auth[_-]?token|private[_-]?key|token|secret)\\s*[:=]\\s*[\"']?)[^\\s'\",;]{4,}",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b(?:password|passwd|secret|token|api[_-]?key)\\s*[=:]\\s*)(?![\"'[])\\S+",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b[a-z][a-z0-9+.-]*:\\/\\/[^\\s:/?#@]*:)[^\\s/?#@]+(?<post>@)",
+      "flags": "gi"
+    }
+  ],
+  "pythonLevels": {
+    "5": 10,
+    "10": 20,
+    "20": 30,
+    "30": 40,
+    "40": 50,
+    "50": 60
+  },
+  "contextAliases": {
+    "agent_uuid": "agentUuid",
+    "tenant_id": "tenantId",
+    "command_id": "commandId",
+    "collection_cycle_id": "collectionCycleId",
+    "correlation_id": "correlationId",
+    "run_id": "runId",
+    "work_id": "workId",
+    "stage_id": "stageId",
+    "device_id": "deviceId",
+    "trace_id": "traceId",
+    "span_id": "spanId"
+  }
+}

package/eslint-rules/prefer-object-first.js

@@ -0,0 +1,53 @@
+'use strict';
+
+function receiverName(node) {
+    if (node.type === 'Identifier') return node.name;
+    if (node.type === 'ThisExpression') return 'this';
+    if (node.type === 'MemberExpression' && !node.computed) {
+        const prefix = receiverName(node.object);
+        return prefix && `${prefix}.${node.property.name}`;
+    }
+    return null;
+}
+module.exports = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Keep interpolated Pino log fields searchable with an object-first call.' },
+        fixable: 'code',
+        schema: [{ type: 'object', properties: {
+            loggerNames: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        }, additionalProperties: false }],
+        messages: { structured: 'Pass searchable fields as the first argument to this logger.' },
+    },
+    create(context) {
+        const names = new Set(context.options[0]?.loggerNames || ['log', 'logger', 'req.log', 'request.log', 'app.log', 'fastify.log']);
+        const methods = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+        const source = context.sourceCode;
+        function constantPrimitive(identifier) {
+            let scope = source.getScope(identifier);
+            let variable;
+            while (scope && !variable) { variable = scope.set.get(identifier.name); scope = scope.upper; }
+            const def = variable?.defs[0];
+            return variable?.defs.length === 1 && def?.parent?.kind === 'const'
+                && def.node.id.type === 'Identifier' && def.node.init?.type === 'Literal'
+                && !def.node.init.regex && typeof def.node.init.value !== 'object';
+        }
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression' || callee.computed
+                    || !methods.has(callee.property.name) || !names.has(receiverName(callee.object))) return;
+                const template = node.arguments[0];
+                if (template?.type !== 'TemplateLiteral' || !template.expressions.length) return;
+                const canFix = node.arguments.length === 1 && template.expressions.every(expr =>
+                    expr.type === 'Identifier' && expr.name !== '__proto__' && constantPrimitive(expr));
+                context.report({ node: template, messageId: 'structured',
+                    // Keep the original message and its formatting. Only duplicate reads
+                    // of known primitive consts; calls/getters/mutable bindings need review.
+                    fix: canFix ? fixer => fixer.insertTextBefore(template,
+                        `{ ${[...new Set(template.expressions.map(expr => expr.name))].join(', ')} }, `) : undefined,
+                });
+            },
+        };
+    },
+};

package/eslint.d.ts

@@ -0,0 +1,3 @@
+import type { ESLint } from 'eslint';
+declare const plugin: ESLint.Plugin;
+export = plugin;

package/eslint.js

@@ -0,0 +1,5 @@
+'use strict';
+module.exports = {
+    meta: { name: 'ntlogger' },
+    rules: { 'prefer-object-first': require('./eslint-rules/prefer-object-first') },
+};

package/index.d.ts

@@ -3,214 +3,227 @@
  * @file index.d.ts
  */
 
-/**
- * Log levels supported by NightTimeLogger
- */
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'internal';
-
-/**
- * Sampling configuration for log levels
- */
-export interface SamplingConfig {
-    [level: string]: number; // 0.0 to 1.0, where 1.0 = log all, 0.1 = log 10%
-}
-
-/**
- * Rate limit configuration for a log level
- */
-export interface RateLimitConfig {
-    max: number;    // Maximum number of logs
-    window: number; // Time window in milliseconds
-}
-
-/**
- * Rate limiting configuration for log levels
- */
-export interface RateLimitConfigMap {
-    [level: string]: RateLimitConfig;
-}
-
-/**
- * Deduplication configuration
- */
-export interface DeduplicationConfig {
-    enabled: boolean;
-    threshold: number;  // Number of duplicates before squishing (default: 3)
-    window: number;     // Time window in milliseconds (default: 60000)
-}
-
-/**
- * Plugin configuration
- */
-export interface PluginConfig {
-    name: string;
-    enabled?: boolean;
-    config?: Record<string, any>;
-}
-
-/**
- * Logger configuration options
- */
-export interface LoggerConfig {
-    /** Minimum log level to be logged */
-    level?: LogLevel;
-    /** Enable console logging (default: true) */
-    console?: boolean;
-    /** Enable file logging (default: true) */
-    file?: boolean;
-    /** Filename for log file (default: `${location}.log`) */
-    filename?: string;
-    /** Directory path where log files will be saved (default: './logs') */
-    path?: string;
-    /** Maximum size of log file in bytes (default: 1048576 = 1MB) */
-    maxSize?: number;
-    /** Maximum number of log files to retain (default: 5) */
-    maxFiles?: number;
-    /** Include timestamp in log messages (default: true) */
-    timestamp?: boolean;
-    /** Skip cache and create new logger instance (default: false) */
-    skipCache?: boolean;
-    /** Enable call site path reporting (default: false) */
-    reportPath?: boolean;
-    /** Enable debug mode for logger itself (default: false) */
-    debug?: boolean;
-    /** Log sampling rates per level */
-    sampling?: SamplingConfig;
-    /** Rate limiting configuration per level */
-    rateLimit?: RateLimitConfigMap;
-    /** Log deduplication configuration */
-    deduplication?: DeduplicationConfig;
-    /** Enable performance metrics (default: NODE_ENV === 'development') */
-    performanceMetrics?: boolean;
-    /** Interval in milliseconds to log statistics (default: 0 = disabled) */
-    statsInterval?: number;
-    /** Plugin configurations */
-    plugins?: PluginConfig[];
-}
-
-/**
- * Statistics object returned by getStats()
- */
-export interface LoggerStats {
-    sampling: {
-        total: Record<string, number>;
-        sampled: Record<string, number>;
-        rateLimited: Record<string, number>;
-    } | null;
-    deduplication: {
-        totalDeduplicated: number;
-        uniqueMessages: number;
-        activeEntries: number;
-    } | null;
-    performance: {
-        enabled: boolean;
-        avgLogProcessingTime?: number;
-        avgTransportTime?: number;
-        logProcessingSamples?: number;
-        transportSamples?: number;
-    } | null;
-}
-
-/**
- * Logger instance interface
- */
-export interface Logger {
-    /**
-     * Log an informational message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
-     */
-    info(message: string, meta?: Record<string, any>): void;
-    info(message: Record<string, any>): void;
-
+declare namespace logger {
     /**
-     * Log a warning message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Log levels supported by NightTimeLogger
      */
-    warn(message: string, meta?: Record<string, any>): void;
-    warn(message: Record<string, any>): void;
+    export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'internal';
 
     /**
-     * Log an error message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Sampling configuration for log levels
      */
-    error(message: string, meta?: Record<string, any>): void;
-    error(message: Record<string, any>): void;
+    export interface SamplingConfig {
+        [level: string]: number; // 0.0 to 1.0, where 1.0 = log all, 0.1 = log 10%
+    }
 
     /**
-     * Log a debug message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Rate limit configuration for a log level
      */
-    debug(message: string, meta?: Record<string, any>): void;
-    debug(message: Record<string, any>): void;
+    export interface RateLimitConfig {
+        max: number;    // Maximum number of logs
+        window: number; // Time window in milliseconds
+    }
 
     /**
-     * Log a trace message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Rate limiting configuration for log levels
      */
-    trace(message: string, meta?: Record<string, any>): void;
-    trace(message: Record<string, any>): void;
+    export interface RateLimitConfigMap {
+        [level: string]: RateLimitConfig;
+    }
 
     /**
-     * Log a fatal message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Deduplication configuration
      */
-    fatal(message: string, meta?: Record<string, any>): void;
-    fatal(message: Record<string, any>): void;
-
-    /**
-     * Log an internal message (logger system messages)
-     * @param message - The message to log
-     * @param meta - Optional metadata object
-     */
-    internal(message: string, meta?: Record<string, any>): void;
-    internal(message: Record<string, any>): void;
-
-    /**
-     * Create a child logger with persistent context
-     * @param context - Context object to merge into all logs
-     * @returns Child logger instance
-     */
-    child(context: Record<string, any>): Logger;
-
-    /**
-     * Start a performance timer (development mode only)
-     * @param label - Timer label
-     */
-    time?(label: string): void;
+    export interface DeduplicationConfig {
+        enabled: boolean;
+        threshold: number;  // Number of duplicates before squishing (default: 3)
+        window: number;     // Time window in milliseconds (default: 60000)
+    }
 
     /**
-     * End a performance timer and log duration (development mode only)
-     * @param label - Timer label
-     * @returns Duration in milliseconds or null if timer not found
+     * Plugin configuration
      */
-    timeEnd?(label: string): number | null;
+    export interface PluginConfig {
+        name: string;
+        enabled?: boolean;
+        config?: Record<string, any>;
+    }
 
     /**
-     * Get logging statistics
-     * @returns Statistics object
+     * Logger configuration options
      */
-    getStats(): LoggerStats;
+    export interface LoggerConfig {
+        /** Maximum in-flight callback promises; overflow drops newest callback, not the primary log. */
+        onLogMaxPending?: number;
+        onLog?: (record: Record<string, any>) => void | Promise<void>;
+        otel?: boolean | { loggerProvider?: { getLogger(name: string): { emit(record: any): void }; forceFlush?(): Promise<void> }; name?: string };
+        redact?: false | { extraKeys?: string[]; patterns?: boolean; replacement?: string; maxDepth?: number; maxStringLength?: number };
+        /** Minimum log level to be logged */
+        level?: LogLevel;
+        /** Enable console logging (default: true) */
+        console?: boolean;
+        /** Enable file logging (default: true) */
+        file?: boolean;
+        /** Filename for combined log file (default: combined.log) */
+        filename?: string;
+        /** Directory path where log files will be saved (default: './logs') */
+        path?: string;
+        /** Maximum size of log file in bytes (default: 1048576 = 1MB) */
+        maxSize?: number;
+        /** Maximum number of log files to retain (default: 5) */
+        maxFiles?: number;
+        /** Include timestamp in log messages (default: true) */
+        timestamp?: boolean;
+        /** Skip cache and create new logger instance (default: false) */
+        skipCache?: boolean;
+        /** Enable call site path reporting (default: false) */
+        reportPath?: boolean;
+        /** Enable debug mode for logger itself (default: false) */
+        debug?: boolean;
+        /** Log sampling rates per level */
+        sampling?: SamplingConfig;
+        /** Rate limiting configuration per level */
+        rateLimit?: RateLimitConfigMap;
+        /** Log deduplication configuration */
+        deduplication?: DeduplicationConfig;
+        /** Enable performance metrics (default: NODE_ENV === 'development') */
+        performanceMetrics?: boolean;
+        /** Interval in milliseconds to log statistics (default: 0 = disabled) */
+        statsInterval?: number;
+        /** Maximum flush/stream shutdown wait in milliseconds (default: 30000). */
+        shutdownTimeout?: number;
+        /** Plugin configurations */
+        plugins?: PluginConfig[];
+    }
 
     /**
-     * Flush all pending logs (returns Promise)
-     * @returns Promise that resolves when all logs are flushed
+     * Statistics object returned by getStats()
      */
-    flush(): Promise<void>;
+    export interface LoggerStats {
+        levels: Record<string, number>;
+        hookErrors: number;
+        onLog: { pending: number; dropped: number; limit: number };
+        sampling: {
+            total: Record<string, number>;
+            sampled: Record<string, number>;
+            rateLimited: Record<string, number>;
+        } | null;
+        deduplication: {
+            totalDeduplicated: number;
+            uniqueMessages: number;
+            activeEntries: number;
+        } | null;
+        performance: {
+            enabled: boolean;
+            avgLogProcessingTime?: number;
+            avgTransportTime?: number;
+            logProcessingSamples?: number;
+            transportSamples?: number;
+        } | null;
+    }
 
     /**
-     * Close the logger and flush all pending logs (returns Promise)
-     * @returns Promise that resolves when logger is closed
+     * Logger instance interface
      */
-    close(): Promise<void>;
-
-    /** Current log level */
-    level: string;
+    export interface Logger {
+        /**
+         * Log an informational message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        info(message: string, meta?: Record<string, any>): void;
+        info(message: Record<string, any>): void;
+
+        /**
+         * Log a warning message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        warn(message: string, meta?: Record<string, any>): void;
+        warn(message: Record<string, any>): void;
+
+        /**
+         * Log an error message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        error(message: string, meta?: Record<string, any>): void;
+        error(message: Record<string, any>): void;
+
+        /**
+         * Log a debug message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        debug(message: string, meta?: Record<string, any>): void;
+        debug(message: Record<string, any>): void;
+
+        /**
+         * Log a trace message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        trace(message: string, meta?: Record<string, any>): void;
+        trace(message: Record<string, any>): void;
+
+        /**
+         * Log a fatal message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        fatal(message: string, meta?: Record<string, any>): void;
+        fatal(message: Record<string, any>): void;
+
+        /**
+         * Log an internal message (logger system messages)
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        internal(message: string, meta?: Record<string, any>): void;
+        internal(message: Record<string, any>): void;
+
+        /**
+         * Create a child logger with persistent context
+         * @param context - Context object to merge into all logs
+         * @returns Child logger instance
+         */
+        child(context: Record<string, any>): Logger;
+
+        /**
+         * Start a performance timer (development mode only)
+         * @param label - Timer label
+         */
+        time?(label: string): void;
+
+        /**
+         * End a performance timer and log duration (development mode only)
+         * @param label - Timer label
+         * @returns Duration in milliseconds or null if timer not found
+         */
+        timeEnd?(label: string): number | null;
+
+        /**
+         * Get logging statistics
+         * @returns Statistics object
+         */
+        getStats(): LoggerStats;
+        resetStats(): void;
+
+        /**
+         * Flush all pending logs (returns Promise)
+         * @returns Promise that resolves when all logs are flushed
+         */
+        flush(): Promise<void>;
+
+        /**
+         * Close the logger and flush all pending logs (returns Promise)
+         * @returns Promise that resolves when logger is closed
+         */
+        close(): Promise<void>;
+
+        /** Current log level */
+        level: string;
+    }
 }
 
 /**
@@ -219,7 +232,13 @@ export interface Logger {
  * @param config - Configuration options for the logger
  * @returns Logger instance
  */
-declare function logger(location?: string, config?: LoggerConfig): Logger;
+declare function logger(location?: string, config?: logger.LoggerConfig): logger.Logger;
+
+declare namespace logger {
+    /** Opt in to process-wide signal handlers; returns an unregister function. */
+    function withSecretValues<T>(values: string[], callback: () => T): T;
+    function setupSignalHandlers(options?: { timeout?: number }): () => void;
+}
 
 export = logger;
 

package/index.js

@@ -114,4 +114,21 @@
  * Initial release
  */
 
-module.exports = require('./lib/logger');
+// Only the Winston entry point resolves these peers. Pino consumers never load it.
+for (const peer of ['winston', 'winston-transport']) {
+    try {
+        require.resolve(peer);
+    } catch (cause) {
+        if (cause.code !== 'MODULE_NOT_FOUND') throw cause;
+        const error = new Error(
+            `ntlogger's Winston backend requires ${peer}. Run: npm install winston winston-transport. ` +
+            `For Pino, import 'ntlogger/pino' instead.`,
+            { cause },
+        );
+        error.code = 'MODULE_NOT_FOUND';
+        throw error;
+    }
+}
+
+module.exports = require('./lib/logger');
+module.exports.withSecretValues = require('./lib/secretScope').withSecretValues;

package/lib/lifecycle.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const delay = () => new Promise(resolve => setTimeout(resolve, 1));
+
+function withTimeout(operation, timeout, label) {
+    let timer;
+    return Promise.race([
+        operation,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeout}ms`)), timeout);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+
+// Winston uses readable-stream, so inspect both its buffers and file sinks.
+function busy(stream) {
+    return !!(stream && (stream._writableState?.length || stream._readableState?.length));
+}
+
+async function drain(logger, state, timeout = 5000) {
+    const deadline = Date.now() + timeout;
+    while (state.pending || busy(logger) || logger.transports.some(t =>
+        busy(t) || busy(t._stream) || busy(t._dest) || t._opening || t._rotate)) {
+        if (state.error) throw state.error;
+        if (Date.now() >= deadline) throw new Error('Logger drain timed out');
+        await delay();
+    }
+    if (state.error) throw state.error;
+}
+
+// Winston calls close on unpipe but doesn't await the result. Retain that promise.
+function trackClose(transport) {
+    if (transport._ntlClose) return;
+    const close = transport.close?.bind(transport);
+    let promise;
+    transport._ntlClose = () => {
+        if (!promise) {
+            // File._final already ended and drained this stream before unpipe.
+            // Calling File.close(callback) on that finished stream never calls back.
+            if (transport instanceof require('winston').transports.File && transport._stream?._writableState.finished) {
+                return (promise = Promise.resolve());
+            }
+            promise = close && close.length > 0
+                ? new Promise((resolve, reject) => close(err => err ? reject(err) : resolve()))
+                : Promise.resolve().then(() => close?.());
+            promise.catch(() => {}); // unpipe cannot consume a rejected promise
+        }
+        return promise;
+    };
+    transport.close = transport._ntlClose;
+}
+
+module.exports = { withTimeout, drain, trackClose };