@crimsonsunset/jsg-logger 1.7.14 → 1.8.0

package/README.md

@@ -26,6 +26,7 @@ A sophisticated, fully generic logging system that automatically detects its env
 - 📁 **File-Level Overrides** - Per-file and pattern-based control
 - ⏰ **Timestamp Modes** - Absolute, readable, relative, or disabled
 - 🎛️ **Display Toggles** - Control every aspect of log output
+- 🔒 **Automatic Redaction** - Protect sensitive data in logs (passwords, API keys, tokens)
 - 🎯 **Smart Level Resolution** - Hierarchical level determination
 
 ## 🚀 Quick Start
@@ -290,6 +291,121 @@ logger.controls.setDisplayOption('jsonPayload', false);
 logger.controls.toggleDisplayOption('level');
 ```
 
+## 🔒 **Redaction (Sensitive Data Protection)**
+
+Automatically redact sensitive keys in logged objects to prevent accidental exposure of passwords, API keys, tokens, and other sensitive data.
+
+### **Basic Configuration**
+
+```javascript
+const logger = JSGLogger.getInstanceSync({
+  redact: {
+    paths: ['password', 'token', '*key', '*secret'],
+    censor: '[REDACTED]'
+  }
+});
+
+logger.api.info('User login', {
+  username: 'john',
+  password: 'secret123',      // → [REDACTED]
+  apiKey: 'abc123xyz',        // → [REDACTED] (matches *key)
+  googleApiKey: 'key123',     // → [REDACTED] (matches *key)
+  email: 'john@example.com'  // → visible
+});
+```
+
+### **Pattern Matching**
+
+Redaction supports two pattern types:
+
+- **Exact match**: `'password'`, `'token'` - matches keys exactly
+- **Wildcard suffix**: `'*key'`, `'*secret'` - matches any key ending with the suffix (case-insensitive)
+
+```javascript
+// Wildcard patterns match:
+'*key'     → apiKey, googleApiKey, secretKey, publicKey, API_KEY, api_key
+'*secret'  → secret, secretKey, mySecret, SECRET
+'*apiKey'  → apiKey, googleApiKey, customApiKey
+'*api_key' → api_key, GOOGLE_API_KEY
+```
+
+### **Nested Objects & Arrays**
+
+Redaction works recursively through nested objects and arrays:
+
+```javascript
+logger.info('Config loaded', {
+  user: {
+    name: 'John',
+    password: 'secret',     // → [REDACTED]
+    apiKey: 'key123'        // → [REDACTED]
+  },
+  services: [
+    { name: 'API', token: 'abc' },  // → token: [REDACTED]
+    { name: 'DB', token: 'xyz' }    // → token: [REDACTED]
+  ]
+});
+```
+
+### **Custom Censor Text**
+
+```javascript
+const logger = JSGLogger.getInstanceSync({
+  redact: {
+    paths: ['password'],
+    censor: '***HIDDEN***'  // Custom replacement text
+  }
+});
+```
+
+### **File-Specific Redaction**
+
+Override redaction per file or pattern:
+
+```json
+{
+  "redact": {
+    "paths": ["password", "*key"],
+    "censor": "[REDACTED]"
+  },
+  "fileOverrides": {
+    "src/auth/*.js": {
+      "redact": {
+        "paths": ["password", "token", "*key", "*secret"],
+        "censor": "***"
+      }
+    }
+  }
+}
+```
+
+### **Default Configuration**
+
+Default redaction patterns (if not configured):
+- `password`
+- `token`
+- `*key` (matches any key ending in "key")
+- `*secret` (matches any key ending in "secret")
+- `*apiKey`
+- `*api_key`
+
+Default censor: `[REDACTED]`
+
+### **Disable Redaction**
+
+Set empty paths array to disable:
+
+```javascript
+const logger = JSGLogger.getInstanceSync({
+  redact: {
+    paths: [],  // No redaction
+    censor: '[REDACTED]'
+  }
+});
+```
+
+**Note**: Redaction applies to all formatters (browser, CLI, and server) automatically.
+
 ## 🏗️ Architecture
 
 ```

package/config/config-manager.js

@@ -198,8 +198,6 @@ export class ConfigManager {
         
         // Handle environment-specific configurations 
         if (config.environments) {
-            // For now, just log that environment configs exist
-            // TODO: Implement environment-based config selection
             metaLog(`[JSG-LOGGER] Found environment configs for: ${Object.keys(config.environments).join(', ')}`);
         }
         
@@ -207,6 +205,11 @@ export class ConfigManager {
         if (config.components) {
             normalized.components = this._normalizeComponents(config.components);
         }
+
+        // Transports are live object instances — pass through as-is, no normalization
+        if (config.transports) {
+            normalized.transports = config.transports;
+        }
         
         return normalized;
     }
@@ -339,10 +342,11 @@ export class ConfigManager {
 
         for (const key in override) {
             if (override.hasOwnProperty(key)) {
-                // Special case: 'components' should be replaced, not merged
-                // This allows users to define their own components without getting defaults
                 if (key === 'components' && typeof override[key] === 'object') {
                     merged[key] = override[key];
+                } else if (key === 'transports') {
+                    // Transports are live object instances — always replace, never deep-merge
+                    merged[key] = override[key];
                 } else if (typeof override[key] === 'object' && !Array.isArray(override[key])) {
                     merged[key] = this.mergeConfigs(merged[key] || {}, override[key]);
                 } else {
@@ -533,6 +537,32 @@ export class ConfigManager {
         return baseDisplay;
     }
 
+    /**
+     * Get redact configuration with file override support
+     * @param {string} filePath - Optional file path for override checking
+     * @returns {Object} Redact configuration with paths array and censor string
+     */
+    getRedactConfig(filePath = null) {
+        const baseRedact = this.config.redact || {
+            paths: [],
+            censor: '[REDACTED]'
+        };
+
+        // Check for file-specific redact overrides
+        const checkFile = filePath || this.currentFile;
+        if (checkFile) {
+            const fileOverride = this.getFileOverride(checkFile);
+            if (fileOverride && fileOverride.redact) {
+                return {
+                    ...baseRedact,
+                    ...fileOverride.redact
+                };
+            }
+        }
+
+        return baseRedact;
+    }
+
     /**
      * Get project name
      * @returns {string} Project name

package/config/default-config.json

@@ -18,6 +18,10 @@
     "jsonPayload": true,
     "stackTrace": true
   },
+  "redact": {
+    "paths": ["password", "token", "*key", "*secret", "*apiKey", "*api_key"],
+    "censor": "[REDACTED]"
+  },
   "levels": {
     "10": { "name": "TRACE", "emoji": "🔍", "color": "#6C7B7F" },
     "20": { "name": "DEBUG", "emoji": "🐛", "color": "#74B9FF" },

package/examples/advanced-config.json

@@ -16,6 +16,10 @@
     "jsonPayload": true,
     "stackTrace": true
   },
+  "redact": {
+    "paths": ["password", "token", "*key", "*secret", "*apiKey", "*api_key"],
+    "censor": "[REDACTED]"
+  },
   "components": {
     "core": { 
       "emoji": "🎯", 
@@ -116,6 +120,10 @@
       "display": {
         "jsonPayload": true,
         "stackTrace": true
+      },
+      "redact": {
+        "paths": ["password", "token", "*key", "*secret"],
+        "censor": "***"
       }
     },
     "src/database/*.js": {

package/formatters/browser-formatter.js

@@ -5,6 +5,7 @@
  */
 
 import {configManager} from '../config/config-manager.js';
+import {redactValue} from '../utils/redaction.js';
 
 /**
  * Create browser console formatter for a specific component
@@ -28,6 +29,7 @@ export const createBrowserFormatter = (componentName, logStore = null) => {
                 const component = configManager.getComponentConfig(componentName, filePath);
                 const level = configManager.getLevelConfig(logData.level);
                 const displayConfig = configManager.getDisplayConfig(filePath);
+                const redactConfig = configManager.getRedactConfig(filePath);
 
                 // Check if this log should be displayed based on effective level
                 const effectiveLevel = configManager.getEffectiveLevel(componentName, filePath);
@@ -84,7 +86,8 @@ export const createBrowserFormatter = (componentName, logStore = null) => {
                 if (displayConfig.jsonPayload) {
                     const contextData = extractContextData(logData);
                     if (Object.keys(contextData).length > 0) {
-                        displayContextData(contextData);
+                        const redactedData = redactValue(contextData, redactConfig);
+                        displayContextData(redactedData);
                     }
                 }
 
@@ -158,6 +161,7 @@ function extractContextData(logData) {
     return contextData;
 }
 
+
 /**
  * Display context data with tree-like structure
  * @param {Object} contextData - Context data to display

package/formatters/cli-formatter.js

@@ -5,6 +5,7 @@
 
 import { LEVEL_SCHEME } from '../config/component-schemes.js';
 import { configManager } from '../config/config-manager.js';
+import { redactValue } from '../utils/redaction.js';
 
 /**
  * Format a value for display in context tree
@@ -27,6 +28,7 @@ const formatValue = (value) => {
   return String(value);
 };
 
+
 /**
  * Create CLI formatter with context data support
  * @returns {Object} Stream-like object for Pino
@@ -62,10 +64,14 @@ export const createCLIFormatter = () => {
         const contextKeys = Object.keys(log).filter(key => !internalFields.includes(key));
         
         if (contextKeys.length > 0) {
+          // Get redact config and apply redaction
+          const redactConfig = configManager.getRedactConfig();
+          const redactedLog = redactValue(log, redactConfig);
+          
           contextKeys.forEach((key, index) => {
             const isLast = index === contextKeys.length - 1;
             const prefix = isLast ? '   └─' : '   ├─';
-            const value = formatValue(log[key]);
+            const value = formatValue(redactedLog[key]);
             console.log(`${prefix} ${key}: ${value}`);
           });
         }

package/formatters/server-formatter.js

@@ -3,6 +3,8 @@
  * Structured JSON output for production logging and log aggregation
  */
 
+import {configManager} from '../config/config-manager.js';
+
 /**
  * Create server formatter (structured JSON)
  * @returns {null} No custom formatter - uses Pino's default JSON output
@@ -18,6 +20,8 @@ export const createServerFormatter = () => {
  * @returns {Object} Pino configuration for server environments
  */
 export const getServerConfig = () => {
+  const redactConfig = configManager.getRedactConfig();
+  
   return {
     level: 'info', // More conservative logging in production
     formatters: {
@@ -33,10 +37,10 @@ export const getServerConfig = () => {
         };
       }
     },
-    // Redact sensitive information in production
+    // Redact sensitive information in production (configurable)
     redact: {
-      paths: ['password', 'token', 'key', 'secret'],
-      censor: '[REDACTED]'
+      paths: redactConfig.paths.length > 0 ? redactConfig.paths : ['password', 'token', 'key', 'secret'],
+      censor: redactConfig.censor || '[REDACTED]'
     }
   };
 };

package/index.d.ts

@@ -2,6 +2,52 @@
  * TypeScript definitions for @crimsonsunset/jsg-logger
  */
 
+// ---------------------------------------------------------------------------
+// Transport system
+// ---------------------------------------------------------------------------
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * Structured log entry passed to transports.
+ * Built automatically by the logger — consumers never create these directly.
+ */
+export interface LogEntry {
+  level: LogLevel;
+  levelNum: number;
+  message: string;
+  component: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+  /** true when levelNum >= 50 (error / fatal) */
+  isError: boolean;
+  /** Extracted Error instance from data (data itself, data.err, or data.error) */
+  error?: Error;
+}
+
+/**
+ * Thin interface that any external log service must implement.
+ * The library calls `send()` for every log that passes the transport's level gate.
+ *
+ * @example
+ * ```ts
+ * class DatadogTransport implements LogTransport {
+ *   level = 'warn' as const;
+ *   send(entry: LogEntry) { datadogClient.log(entry.message, entry.data); }
+ * }
+ * ```
+ */
+export interface LogTransport {
+  /** Minimum level this transport cares about. Logs below this are skipped. */
+  level?: LogLevel;
+  /** Called for each qualifying log entry. May return a Promise (fire-and-forget). */
+  send(entry: LogEntry): void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Logger core
+// ---------------------------------------------------------------------------
+
 export interface LoggerInstance {
   info: (message: string, data?: any) => void;
   debug: (message: string, data?: any) => void;
@@ -56,6 +102,8 @@ export interface JSGLoggerConfig {
   devtools?: {
     enabled?: boolean;
   };
+  /** External log service transports. Each receives qualifying LogEntry objects. */
+  transports?: LogTransport[];
   [key: string]: any;
 }
 

package/index.js

@@ -13,6 +13,7 @@ import {createCLIFormatter} from './formatters/cli-formatter.js';
 import {createServerFormatter, getServerConfig} from './formatters/server-formatter.js';
 import {LogStore} from './stores/log-store.js';
 import {metaLog, metaWarn, metaError} from './utils/meta-logger.js';
+import {buildLogEntry, dispatchToTransports} from './utils/transport-dispatcher.js';
 import packageJson from './package.json' with {type: 'json'};
 
 // Check default config for devtools at module load time
@@ -54,10 +55,11 @@ class JSGLogger {
     constructor() {
         this.loggers = {};
         this.logStore = new LogStore();
-        this.environment = null; // Will be set after config loads
+        this.environment = null;
         this.initialized = false;
-        this.components = {}; // Auto-discovery getters
-        this.componentSubscribers = []; // Subscribers for component change events
+        this.components = {};
+        this.componentSubscribers = [];
+        this.transports = [];
     }
 
     /**
@@ -192,6 +194,9 @@ class JSGLogger {
             // NOW determine environment (after config is loaded and forceEnvironment is applied)
             this.environment = getEnvironment();
 
+            // Pick up transports from config (live objects — not deep-merged)
+            this.transports = configManager.config.transports ?? [];
+
             // Create loggers for all available components
             const components = configManager.getAvailableComponents();
 
@@ -199,11 +204,6 @@ class JSGLogger {
                 this.loggers[componentName] = this.createLogger(componentName);
             });
 
-            // Create legacy compatibility aliases
-            // Removed: camelCase aliases no longer added to this.loggers
-            // Use logger.components.camelCase() or logger.getComponent('kebab-case') instead
-            // this.createAliases();
-
             // Add utility methods
             this.addUtilityMethods();
 
@@ -303,27 +303,20 @@ class JSGLogger {
             // NOW determine environment (after config is loaded and forceEnvironment is applied)
             this.environment = getEnvironment();
 
+            // Pick up transports from config (live objects — not deep-merged)
+            this.transports = configManager.config.transports ?? [];
+
             // Clear existing loggers for clean reinitialization
             this.loggers = {};
             this.components = {};
 
             // Create loggers for all available components using default config
             const components = configManager.getAvailableComponents();
-            
-            // Debug: Log components being created during initialization
-            // Note: Using console.log because this.loggers is empty at this point
-            if (components.length > 0) {
-                console.log(`[JSG-LOGGER] Creating ${components.length} loggers during initSync:`, components);
-            }
 
             components.forEach(componentName => {
-                // Use original createLogger to bypass utility method caching
                 const createFn = this._createLoggerOriginal || this.createLogger.bind(this);
                 this.loggers[componentName] = createFn(componentName);
             });
-
-            // Create legacy compatibility aliases
-            // Removed: camelCase aliases no longer added to this.loggers
             // Use logger.components.camelCase() or logger.getComponent('kebab-case') instead
             // this.createAliases();
 
@@ -341,7 +334,7 @@ class JSGLogger {
                     try {
                         callback(currentComponents);
                     } catch (error) {
-                        console.error('Component subscriber error:', error);
+                        metaError('Component subscriber error:', error);
                     }
                 });
             }
@@ -438,28 +431,37 @@ class JSGLogger {
      */
     _wrapPinoLogger(pinoLogger) {
         const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+        const levelNums = {trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60};
         const wrapped = {};
+        const self = this;
 
         levels.forEach(level => {
             wrapped[level] = (first, ...args) => {
+                let message = '';
+                let data;
+
                 // Handle different argument patterns
                 if (typeof first === 'string') {
-                    // Pattern: logger.info('message', {context})
-                    const message = first;
+                    message = first;
                     if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null) {
-                        // Has context object
+                        data = args[0];
                         pinoLogger[level](args[0], message);
                     } else {
-                        // Just message
                         pinoLogger[level](message);
                     }
                 } else if (typeof first === 'object' && first !== null) {
-                    // Pattern: logger.info({context}, 'message') - already pino format
+                    data = first;
+                    message = (args.length > 0 && typeof args[0] === 'string') ? args[0] : '';
                     pinoLogger[level](first, ...args);
                 } else {
-                    // Fallback: just pass through
                     pinoLogger[level](first, ...args);
                 }
+
+                // Dispatch to transports
+                if (self.transports && self.transports.length > 0) {
+                    const entry = buildLogEntry(level, levelNums[level], pinoLogger._componentName, message, data);
+                    dispatchToTransports(entry, self.transports);
+                }
             };
         });
 
@@ -566,7 +568,7 @@ class JSGLogger {
                     try {
                         callback(currentComponents);
                     } catch (error) {
-                        console.error('Component subscriber error (initial call):', error);
+                        this.loggers.core?.error('Component subscriber error (initial call):', error);
                     }
                     // Return unsubscribe function
                     return () => {
@@ -745,6 +747,7 @@ class JSGLogger {
         const formatter = createBrowserFormatter(componentName, this.logStore);
         const levels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
         const levelMap = {trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60};
+        const self = this;
 
         const logger = {};
 
@@ -757,7 +760,6 @@ class JSGLogger {
                 const minLevel = levelMap[effectiveLevel] || 30;
                 if (logLevel < minLevel) return;
 
-                // Create log data object
                 let logData = {
                     level: logLevel,
                     time: Date.now(),
@@ -765,24 +767,35 @@ class JSGLogger {
                     v: 1
                 };
 
+                let message = '';
+                let data;
+
                 // Handle different argument patterns
                 if (typeof first === 'string') {
+                    message = first;
                     logData.msg = first;
-                    // Add additional args as context
                     if (args.length === 1 && typeof args[0] === 'object') {
+                        data = args[0];
                         Object.assign(logData, args[0]);
                     } else if (args.length > 0) {
                         logData.args = args;
                     }
                 } else if (typeof first === 'object') {
+                    data = first;
                     Object.assign(logData, first);
                     if (args.length > 0 && typeof args[0] === 'string') {
+                        message = args[0];
                         logData.msg = args[0];
                     }
                 }
 
-                // Use our beautiful formatter
                 formatter.write(JSON.stringify(logData));
+
+                // Dispatch to transports
+                if (self.transports && self.transports.length > 0) {
+                    const entry = buildLogEntry(level, logLevel, componentName, message, data);
+                    dispatchToTransports(entry, self.transports);
+                }
             };
         });
 
@@ -899,7 +912,7 @@ class JSGLogger {
                 try {
                     callback(currentComponents);
                 } catch (error) {
-                    console.error('Component subscriber error:', error);
+                    this.loggers.core?.error('Component subscriber error:', error);
                 }
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.7.14",
+  "version": "1.8.0",
   "type": "module",
   "description": "Multi-environment logger with smart detection, file-level overrides, and beautiful console formatting. Test it live: https://logger.joesangiorgio.com/",
   "main": "index.js",

package/utils/redaction.js

@@ -0,0 +1,54 @@
+/**
+ * Redaction utility functions for sensitive data protection
+ * Used by browser, CLI, and server formatters
+ */
+
+/**
+ * Check if a key should be redacted based on patterns
+ * @param {string} key - Key to check
+ * @param {string[]} paths - Array of patterns (exact match or wildcard like *key)
+ * @returns {boolean} Whether key should be redacted
+ */
+export function shouldRedactKey(key, paths) {
+  return paths.some(pattern => {
+    if (pattern.startsWith('*')) {
+      const suffix = pattern.slice(1).toLowerCase();
+      return key.toLowerCase().endsWith(suffix);
+    }
+    return key.toLowerCase() === pattern.toLowerCase();
+  });
+}
+
+/**
+ * Redact sensitive values from an object based on key patterns
+ * @param {*} value - Value to redact (object, array, or primitive)
+ * @param {Object} redactConfig - Redaction configuration with paths and censor
+ * @returns {*} Redacted value
+ */
+export function redactValue(value, redactConfig) {
+  if (!redactConfig || !redactConfig.paths || redactConfig.paths.length === 0) {
+    return value;
+  }
+
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const redacted = {};
+    for (const [key, val] of Object.entries(value)) {
+      if (shouldRedactKey(key, redactConfig.paths)) {
+        redacted[key] = redactConfig.censor || '[REDACTED]';
+      } else {
+        redacted[key] = redactValue(val, redactConfig);
+      }
+    }
+    return redacted;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => redactValue(item, redactConfig));
+  }
+
+  return value;
+}
+
+
+
+

package/utils/transport-dispatcher.js

@@ -0,0 +1,86 @@
+/**
+ * Transport Dispatcher for JSG Logger
+ * Builds log entries and dispatches them to registered transports.
+ * Transports are consumer-provided objects implementing the LogTransport interface.
+ */
+
+import { metaError } from './meta-logger.js';
+
+const LEVEL_NAMES = {
+    10: 'trace',
+    20: 'debug',
+    30: 'info',
+    40: 'warn',
+    50: 'error',
+    60: 'fatal',
+};
+
+const LEVEL_NUMS = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+};
+
+/**
+ * Extract an Error instance from log data if one is present.
+ * Checks the value itself, then common keys: `err`, `error`.
+ * @param {*} data - The data argument passed to the log method
+ * @returns {Error|undefined}
+ */
+function extractError(data) {
+    if (data instanceof Error) return data;
+    if (data && typeof data === 'object') {
+        if (data.err instanceof Error) return data.err;
+        if (data.error instanceof Error) return data.error;
+    }
+    return undefined;
+}
+
+/**
+ * Build a structured LogEntry from raw log call arguments.
+ * @param {string} level - Level name ('info', 'warn', 'error', etc.)
+ * @param {number} levelNum - Numeric level (10–60)
+ * @param {string} component - Component name
+ * @param {string} message - Log message
+ * @param {Record<string, unknown>} [data] - Optional context/data object
+ * @returns {Object} LogEntry
+ */
+export function buildLogEntry(level, levelNum, component, message, data) {
+    return {
+        level,
+        levelNum,
+        message: message ?? '',
+        component,
+        data,
+        timestamp: Date.now(),
+        isError: levelNum >= 50,
+        error: extractError(data),
+    };
+}
+
+/**
+ * Dispatch a LogEntry to all registered transports.
+ * Each transport is called independently — a failing transport never
+ * blocks or crashes the others (or the app).
+ * @param {Object} entry - LogEntry object
+ * @param {Array} transports - Array of LogTransport instances
+ */
+export function dispatchToTransports(entry, transports) {
+    if (!transports || transports.length === 0) return;
+
+    const entryLevelNum = entry.levelNum;
+
+    for (const transport of transports) {
+        try {
+            const minLevel = transport.level ? (LEVEL_NUMS[transport.level] ?? 0) : 0;
+            if (entryLevelNum < minLevel) continue;
+
+            transport.send(entry);
+        } catch (err) {
+            metaError('[JSG-LOGGER] Transport dispatch error:', err);
+        }
+    }
+}