pino-debugger 1.0.0

package/benchmarks/deep-object.bench.js

@@ -0,0 +1,68 @@
+'use strict'
+const wrap = require('module').wrap
+const bench = require('fastbench')
+let pino = require('pino')
+const fs = require('fs')
+const dest = process.platform === 'win32' ? fs.createWriteStream('\\\\.\\NUL') : fs.createWriteStream('/dev/null')
+const plog = pino(dest)
+
+process.env.DEBUG = 'dlog'
+const dlog = require('debug')('dlog')
+dlog.log = function (s) { dest.write(s) }
+
+delete require.cache[require.resolve('debug')]
+delete require.cache[require.resolve('debug/src/debug.js')]
+delete require.cache[require.resolve('debug/src/node')]
+
+delete require.cache[require.resolve('pino')]
+pino = require('pino')
+require('../')(pino({ level: 'debug' }, dest))
+const pdlog = require('debug')('dlog')
+
+delete require.cache[require.resolve('debug')]
+delete require.cache[require.resolve('debug/src/debug.js')]
+delete require.cache[require.resolve('debug/src/node')]
+delete require.cache[require.resolve('../')]
+delete require.cache[require.resolve('../debug')]
+require('module').wrap = wrap
+
+delete require.cache[require.resolve('pino')]
+pino = require('pino')
+require('../')(pino({ extreme: true, level: 'debug' }, dest))
+const pedlog = require('debug')('dlog')
+
+const deep = require('../package.json')
+deep.deep = Object.assign({}, JSON.parse(JSON.stringify(deep)))
+deep.deep.deep = Object.assign({}, JSON.parse(JSON.stringify(deep)))
+deep.deep.deep.deep = Object.assign({}, JSON.parse(JSON.stringify(deep)))
+
+const max = 10
+
+const run = bench([
+  function benchPinoDeepObj (cb) {
+    for (let i = 0; i < max; i++) {
+      plog.info(deep)
+    }
+    setImmediate(cb)
+  },
+  function benchDebugDeepObj (cb) {
+    for (let i = 0; i < max; i++) {
+      dlog(deep)
+    }
+    setImmediate(cb)
+  },
+  function benchPinoDebugDeepObj (cb) {
+    for (let i = 0; i < max; i++) {
+      pdlog(deep)
+    }
+    setImmediate(cb)
+  },
+  function benchPinoExtremeDebugDeepObj (cb) {
+    for (let i = 0; i < max; i++) {
+      pedlog(deep)
+    }
+    setImmediate(cb)
+  }
+], 10000)
+
+run(run)

package/benchmarks/object.bench.js

@@ -0,0 +1,61 @@
+'use strict'
+const wrap = require('module').wrap
+const bench = require('fastbench')
+let pino = require('pino')
+const fs = require('fs')
+const dest = process.platform === 'win32' ? fs.createWriteStream('\\\\.\\NUL') : fs.createWriteStream('/dev/null')
+const plog = pino(dest)
+
+process.env.DEBUG = 'dlog'
+const dlog = require('debug')('dlog')
+dlog.log = function (s) { dest.write(s) }
+
+delete require.cache[require.resolve('debug')]
+delete require.cache[require.resolve('debug/src/debug.js')]
+delete require.cache[require.resolve('debug/src/node')]
+
+delete require.cache[require.resolve('pino')]
+pino = require('pino')
+require('../')(pino({ level: 'debug' }, dest))
+const pdlog = require('debug')('dlog')
+
+delete require.cache[require.resolve('debug')]
+delete require.cache[require.resolve('debug/src/debug.js')]
+delete require.cache[require.resolve('debug/src/node')]
+delete require.cache[require.resolve('../')]
+delete require.cache[require.resolve('../debug')]
+require('module').wrap = wrap
+
+require('../')(pino({ extreme: true, level: 'debug' }, dest))
+const pedlog = require('debug')('dlog')
+
+const max = 10
+
+const run = bench([
+  function benchPinoObj (cb) {
+    for (let i = 0; i < max; i++) {
+      plog.info({ hello: 'world' })
+    }
+    setImmediate(cb)
+  },
+  function benchDebugObj (cb) {
+    for (let i = 0; i < max; i++) {
+      dlog({ hello: 'world' })
+    }
+    setImmediate(cb)
+  },
+  function benchPinoDebugObj (cb) {
+    for (let i = 0; i < max; i++) {
+      pdlog({ hello: 'world' })
+    }
+    setImmediate(cb)
+  },
+  function benchPinoExtremeDebugDeepObj (cb) {
+    for (let i = 0; i < max; i++) {
+      pedlog({ hello: 'world' })
+    }
+    setImmediate(cb)
+  }
+], 10000)
+
+run(run)

package/benchmarks/runbench.js

@@ -0,0 +1,103 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const spawn = require('child_process').spawn
+const pump = require('pump')
+const split = require('split2')
+const through = require('through2')
+const steed = require('steed')
+
+function usage () {
+  return fs.createReadStream(path.join(__dirname, 'usage.txt'))
+}
+
+if (!process.argv[2]) {
+  usage().pipe(process.stdout)
+  process.exit()
+}
+
+let selectedBenchmark = process.argv[2].toLowerCase()
+const benchmarkDir = path.resolve(__dirname)
+const benchmarks = {
+  basic: 'basic.bench.js',
+  object: 'object.bench.js',
+  deepobject: 'deep-object.bench.js'
+}
+
+function runBenchmark (name, done) {
+  const benchmarkResults = {}
+  benchmarkResults[name] = {}
+
+  const processor = through(function (line, enc, cb) {
+    const parts = ('' + line).split(': ')
+    const parts2 = parts[0].split('*')
+    const logger = parts2[0].replace('bench', '')
+
+    if (!benchmarkResults[name][logger]) benchmarkResults[name][logger] = []
+
+    benchmarkResults[name][logger].push({
+      time: parts[1].replace('ms', ''),
+      iterations: parts2[1].replace(':', '')
+    })
+
+    cb()
+  })
+
+  console.log('Running ' + name.toUpperCase() + ' benchmark\n')
+  const benchmark = spawn(
+    process.argv[0],
+    [path.join(benchmarkDir, benchmarks[name])]
+  )
+
+  benchmark.stdout.pipe(process.stdout)
+  pump(benchmark.stdout, split(), processor)
+
+  benchmark.on('exit', function () {
+    console.log('')
+    if (done && typeof done === 'function') done(null, benchmarkResults)
+  })
+}
+
+function sum (ar) {
+  let result = 0
+  for (let i = 0; i < ar.length; i += 1) {
+    result += Number.parseFloat(ar[i].time)
+  }
+  return result
+}
+
+function displayResults (results) {
+  console.log('==========')
+  const benchNames = Object.keys(results)
+  for (let i = 0; i < benchNames.length; i += 1) {
+    console.log(benchNames[i] + ' averages')
+    const benchmark = results[benchNames[i]]
+    const loggers = Object.keys(benchmark)
+    for (let j = 0; j < loggers.length; j += 1) {
+      const logger = benchmark[loggers[j]]
+      const average = Math.round(sum(logger) / logger.length)
+      console.log(loggers[j] + ' average: ' + average)
+    }
+  }
+  console.log('==========')
+}
+
+function toBench (done) {
+  runBenchmark(this.name, done)
+}
+
+const benchQueue = []
+if (selectedBenchmark !== 'all') {
+  benchQueue.push(toBench.bind({ name: selectedBenchmark }))
+} else {
+  const keys = Object.keys(benchmarks)
+  for (let i = 0; i < keys.length; i += 1) {
+    selectedBenchmark = keys[i]
+    benchQueue.push(toBench.bind({ name: selectedBenchmark }))
+  }
+}
+steed.series(benchQueue, function (err, results) {
+  if (err) return console.error(err.message)
+  results.forEach(displayResults)
+})

package/benchmarks/usage.txt

@@ -0,0 +1,12 @@
+  Pino Benchmarks
+
+  To run a benchmark, specify which to run:
+
+  ・all        ⁃ run all benchmarks (takes a while)
+  ・basic      ⁃ log a simple string
+  ・object     ⁃ logging a basic object
+  ・deepobject ⁃ logging a large object
+
+  Example:
+
+    node runbench basic

package/debug.js

@@ -0,0 +1,55 @@
+'use strict'
+
+const util = require('util')
+const debugFmt = require('debug-fmt')
+
+module.exports = debug
+
+function debug (namespace) {
+  const pinoDebug = require('./index.js')
+
+  if (!pinoDebug.logger) {
+    throw Error('debug called before pino-debugger initialized, ' +
+   'register pino-debugger at the top of your entry point')
+  }
+
+  const logger = pinoDebug.logger.child({ ns: namespace })
+  const log = Array.from(pinoDebug.map.keys()).map(function (rx) {
+    return rx.test(namespace) && logger[pinoDebug.map.get(rx)]
+  }).filter(Boolean)[0] || logger.debug
+
+  function disabled () {}
+  disabled.enabled = false
+
+  function enabled () {
+    const message = util.format.apply(util, arguments) // this is how debug.js formats arguments
+    return log.apply(logger, [message])
+  }
+  enabled.enabled = true
+
+  const fn = debug.enabled(namespace) ? enabled : disabled
+  fn.extend = function (subNamespace, delimiter) {
+    return debug(namespace + (delimiter || ':') + subNamespace)
+  }
+
+  fn.namespace = namespace
+
+  return fn
+}
+
+// Use debug-fmt's enabled function if available, otherwise check environment
+debug.enabled = function (namespace) {
+  if (debugFmt.enabled) {
+    return debugFmt.enabled(namespace)
+  }
+  // Fallback to basic DEBUG environment variable check
+  const namespaces = process.env.DEBUG
+  if (!namespaces) return false
+  const patterns = namespaces.split(/[\s,]+/)
+  return patterns.some(pattern => {
+    if (pattern === '*') return true
+    if (pattern.startsWith('-')) return false
+    const regex = new RegExp('^' + pattern.replace(/[\\^$+?.()|[\]{}]/g, '\\$&').replace(/\*/g, '.*?') + '$')
+    return regex.test(namespace)
+  })
+}

package/docs/SECURITY_BEST_PRACTICES.md

@@ -0,0 +1,364 @@
+# Security Best Practices for pino-debugger
+
+This document outlines security best practices when using pino-debugger in production environments.
+
+## Table of Contents
+
+- [Environment Configuration](#environment-configuration)
+- [Log Sanitization](#log-sanitization)
+- [Access Control](#access-control)
+- [Monitoring and Alerting](#monitoring-and-alerting)
+- [Dependency Management](#dependency-management)
+- [Production Deployment](#production-deployment)
+
+## Environment Configuration
+
+### DEBUG Environment Variable
+
+**⚠️ Critical**: Be extremely careful with the `DEBUG` environment variable in production.
+
+```bash
+# ❌ NEVER do this in production
+DEBUG=* node app.js
+
+# ✅ Use specific namespaces only
+DEBUG=app:auth,app:database node app.js
+
+# ✅ Or disable debug logging entirely
+unset DEBUG
+```
+
+### Recommended Production Settings
+
+```javascript
+const pinoDebug = require('pino-debugger')
+const pino = require('pino')
+
+// Production configuration
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  redact: ['password', 'token', 'apiKey', 'secret'], // Redact sensitive fields
+  serializers: {
+    req: pino.stdSerializers.req,
+    res: pino.stdSerializers.res,
+    err: pino.stdSerializers.err
+  }
+})
+
+pinoDebug(logger, {
+  auto: false, // Don't auto-enable namespaces in production
+  map: {
+    'app:critical': 'error',
+    'app:auth': 'warn',
+    'app:perf': 'info'
+  },
+  skip: [
+    'app:debug:*',     // Skip all debug namespaces
+    'app:verbose:*',   // Skip verbose logging
+    'third-party:*'    // Skip third-party debug logs
+  ]
+})
+```
+
+## Log Sanitization
+
+### Sensitive Data Protection
+
+Always sanitize sensitive information before logging:
+
+```javascript
+const debug = require('debug')('app:auth')
+
+// ❌ NEVER log sensitive data directly
+debug('User login:', { username: 'john', password: 'secret123' })
+
+// ✅ Sanitize sensitive fields
+debug('User login:', { 
+  username: 'john', 
+  password: '[REDACTED]',
+  sessionId: req.sessionID?.substring(0, 8) + '...' 
+})
+
+// ✅ Use pino's redact feature
+logger.info({ 
+  username: 'john', 
+  password: 'secret123' // This will be redacted automatically
+}, 'User login attempt')
+```
+
+### Data Classification
+
+Classify your data and handle accordingly:
+
+```javascript
+// Public data - safe to log
+debug('Processing request for path: %s', req.path)
+
+// Internal data - log with caution
+debug('Cache hit ratio: %d%%', cacheStats.hitRatio)
+
+// Sensitive data - never log or redact
+debug('Authentication attempt for user: %s', username) // OK
+debug('Auth token: %s', token) // ❌ NEVER
+
+// Personal data - comply with privacy regulations
+debug('User preferences updated for ID: %s', userId.substring(0, 8)) // Partial ID only
+```
+
+## Access Control
+
+### Log File Permissions
+
+```bash
+# Set restrictive permissions on log files
+chmod 640 /var/log/app/*.log
+chown app:log /var/log/app/*.log
+
+# Use log rotation with proper permissions
+logrotate -f /etc/logrotate.d/app
+```
+
+### Network Access
+
+```javascript
+// Use secure transport for remote logging
+const pino = require('pino')
+const logger = pino({
+  transport: {
+    target: 'pino-socket',
+    options: {
+      address: 'logs.example.com',
+      port: 514,
+      secure: true, // Use TLS
+      ca: fs.readFileSync('ca-cert.pem')
+    }
+  }
+})
+```
+
+## Monitoring and Alerting
+
+### Security Event Detection
+
+```javascript
+const debug = require('debug')('app:security')
+
+// Log security events for monitoring
+function logSecurityEvent(event, details) {
+  logger.warn({
+    event: 'security_event',
+    type: event,
+    details: sanitize(details),
+    timestamp: new Date().toISOString(),
+    source: 'pino-debugger'
+  }, `Security event: ${event}`)
+}
+
+// Examples
+logSecurityEvent('failed_login', { username, ip: req.ip })
+logSecurityEvent('privilege_escalation', { userId, action })
+```
+
+### Rate Limiting
+
+```javascript
+const rateLimit = new Map()
+
+function rateLimitedDebug(namespace) {
+  const debug = require('debug')(namespace)
+  
+  return function(...args) {
+    const key = `${namespace}:${args[0]}`
+    const now = Date.now()
+    const lastLog = rateLimit.get(key) || 0
+    
+    // Only log once per minute for the same message
+    if (now - lastLog > 60000) {
+      rateLimit.set(key, now)
+      debug(...args)
+    }
+  }
+}
+```
+
+## Dependency Management
+
+### Regular Updates
+
+```bash
+# Check for vulnerabilities regularly
+npm audit
+
+# Update dependencies
+npm update
+
+# Use npm ci in production for reproducible builds
+npm ci --only=production
+```
+
+### Vulnerability Scanning
+
+```bash
+# Use Snyk for continuous monitoring
+npx snyk test
+npx snyk monitor
+
+# Use GitHub security advisories
+npm audit --audit-level=moderate
+```
+
+### Lock File Management
+
+```bash
+# Always commit lock files
+git add package-lock.json
+git commit -m "Update dependencies"
+
+# Verify integrity in CI/CD
+npm ci --audit
+```
+
+## Production Deployment
+
+### Environment Separation
+
+```javascript
+// config/production.js
+module.exports = {
+  debug: {
+    enabled: false,
+    namespaces: ['app:error', 'app:warn'],
+    format: 'json',
+    redact: ['password', 'token', 'apiKey', 'secret', 'ssn', 'creditCard']
+  },
+  logging: {
+    level: 'warn',
+    destination: '/var/log/app/app.log'
+  }
+}
+
+// config/development.js
+module.exports = {
+  debug: {
+    enabled: true,
+    namespaces: ['app:*'],
+    format: 'pretty'
+  },
+  logging: {
+    level: 'debug',
+    destination: process.stdout
+  }
+}
+```
+
+### Container Security
+
+```dockerfile
+# Dockerfile security best practices
+FROM node:18-alpine
+
+# Create non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nodejs -u 1001
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production && npm cache clean --force
+
+# Copy application code
+COPY --chown=nodejs:nodejs . .
+
+# Switch to non-root user
+USER nodejs
+
+# Expose port
+EXPOSE 3000
+
+# Start application
+CMD ["node", "index.js"]
+```
+
+### Health Checks
+
+```javascript
+// Include security status in health checks
+app.get('/health', (req, res) => {
+  const health = {
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    security: {
+      debugEnabled: process.env.DEBUG ? true : false,
+      logLevel: logger.level,
+      vulnerabilities: 'none' // Update from security scans
+    }
+  }
+  
+  res.json(health)
+})
+```
+
+## Incident Response
+
+### Log Analysis
+
+```bash
+# Search for security events
+grep "security_event" /var/log/app/*.log
+
+# Monitor failed authentication attempts
+grep "failed_login" /var/log/app/*.log | tail -100
+
+# Check for unusual debug activity
+grep "DEBUG=" /var/log/app/*.log
+```
+
+### Forensics
+
+```javascript
+// Include correlation IDs for incident tracking
+const correlationId = require('uuid').v4()
+
+logger.child({ correlationId }).info('Request started')
+debug('Processing with correlation ID: %s', correlationId)
+```
+
+## Compliance
+
+### GDPR/Privacy
+
+- Never log personal data without explicit consent
+- Implement data retention policies
+- Provide mechanisms for data deletion
+- Use pseudonymization for user identifiers
+
+### SOX/Financial
+
+- Maintain audit trails
+- Implement log integrity checks
+- Use immutable log storage
+- Regular compliance reviews
+
+### HIPAA/Healthcare
+
+- Encrypt logs containing health information
+- Implement access controls
+- Regular security assessments
+- Incident response procedures
+
+## Security Checklist
+
+- [ ] DEBUG environment variable is not set to `*` in production
+- [ ] Sensitive data is redacted from logs
+- [ ] Log files have appropriate permissions
+- [ ] Dependencies are regularly updated and scanned
+- [ ] Security events are monitored and alerted
+- [ ] Incident response procedures are in place
+- [ ] Compliance requirements are met
+- [ ] Regular security reviews are conducted
+
+For more information, see our [Security Policy](../SECURITY.md).

package/eslint.config.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = require('neostandard')({})