@heroku/js-blanket 0.0.0

package/docs/examples/logging-integration.md

@@ -0,0 +1,736 @@
+# Generic Logging Adapter - Integration Examples
+
+This guide provides comprehensive examples for integrating `@heroku/js-blanket`
+with popular logging libraries.
+
+## Table of Contents
+
+- [Winston Integration](#winston-integration)
+- [Pino Integration](#pino-integration)
+- [Bunyan Integration](#bunyan-integration)
+- [Custom Logger Integration](#custom-logger-integration)
+- [oauth-provider-adapters Migration](#oauth-provider-adapters-migration)
+
+---
+
+## Winston Integration
+
+[Winston](https://github.com/winstonjs/winston) is a versatile logging library
+with support for multiple transports.
+
+### Basic Integration
+
+```typescript
+import winston from 'winston';
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+// Create the redactor
+const redactor = createRedactor({
+  fields: HEROKU_FIELDS,
+  paths: ['request.headers.authorization'],
+});
+
+// Custom format that scrubs sensitive data
+const scrubFormat = winston.format((info) => {
+  const scrubbed = redactor.scrub(info);
+  return scrubbed.data;
+});
+
+// Create Winston logger with scrubbing
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    scrubFormat(), // Scrub sensitive data first
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'app.log' }),
+  ],
+});
+
+// Usage
+logger.info('User login', {
+  user: 'john',
+  email: 'john@example.com',
+  password: 'secret123', // Will be scrubbed
+  apiToken: 'token123', // Will be scrubbed
+});
+```
+
+### Advanced Winston Integration with Metadata
+
+```typescript
+import winston from 'winston';
+import { createRedactor, HEROKU_FIELDS, GDPR_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: [...HEROKU_FIELDS, ...GDPR_FIELDS],
+});
+
+// Helper function to scrub metadata
+function scrubMetadata(info: winston.Logform.TransformableInfo) {
+  // Extract non-symbol properties (Winston uses Symbols for internal data)
+  const data: Record<string, unknown> = {};
+  for (const key in info) {
+    if (typeof key === 'string' && !key.startsWith('Symbol(')) {
+      data[key] = info[key];
+    }
+  }
+
+  const scrubbed = redactor.scrub(data);
+
+  // Replace info properties with scrubbed versions
+  Object.assign(info, scrubbed.data);
+  return info;
+}
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    winston.format((info) => scrubMetadata(info))(),
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [new winston.transports.Console()],
+});
+
+// Usage with rich metadata
+logger.info('API request completed', {
+  request: {
+    method: 'POST',
+    url: '/api/users',
+    headers: {
+      authorization: 'Bearer secret', // Scrubbed
+      'user-agent': 'Mozilla/5.0',
+    },
+  },
+  user: {
+    id: 'user-123',
+    email: 'user@example.com', // Scrubbed (GDPR_FIELDS)
+  },
+  duration: 145,
+});
+```
+
+### Winston with Child Loggers
+
+```typescript
+import winston from 'winston';
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({ fields: HEROKU_FIELDS });
+
+const scrubFormat = winston.format((info) => {
+  const scrubbed = redactor.scrub(info);
+  return scrubbed.data;
+});
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.combine(
+    scrubFormat(),
+    winston.format.timestamp(),
+    winston.format.json()
+  ),
+  transports: [new winston.transports.Console()],
+});
+
+// Create child logger with default metadata
+const requestLogger = logger.child({ requestId: 'req-123' });
+
+// All logs from child logger are scrubbed
+requestLogger.info('User authenticated', {
+  userId: 'user-456',
+  password: 'secret', // Scrubbed
+});
+```
+
+---
+
+## Pino Integration
+
+[Pino](https://github.com/pinojs/pino) is a fast, low-overhead logging library.
+
+### Basic Integration
+
+```typescript
+import pino from 'pino';
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: HEROKU_FIELDS,
+});
+
+// Custom serializer that scrubs sensitive data
+const scrubSerializer = (obj: unknown) => {
+  const scrubbed = redactor.scrub(obj);
+  return scrubbed.data;
+};
+
+// Create Pino logger with scrubbing
+const logger = pino({
+  level: 'info',
+  serializers: {
+    // Scrub the entire log object
+    log: scrubSerializer,
+    // Or scrub specific fields
+    user: scrubSerializer,
+    request: scrubSerializer,
+  },
+  hooks: {
+    // Scrub all log objects before they're written
+    logMethod(args, method) {
+      if (args.length >= 2) {
+        const [obj, msg, ...rest] = args;
+        const scrubbed = redactor.scrub(obj);
+        method.apply(this, [scrubbed.data, msg, ...rest]);
+      } else {
+        method.apply(this, args);
+      }
+    },
+  },
+});
+
+// Usage
+logger.info({
+  user: 'john',
+  password: 'secret123', // Will be scrubbed
+  apiToken: 'token123', // Will be scrubbed
+  msg: 'User login',
+});
+```
+
+### Advanced Pino Integration with Redaction
+
+```typescript
+import pino from 'pino';
+import { createRedactor, HEROKU_FIELDS, GDPR_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: [...HEROKU_FIELDS, ...GDPR_FIELDS],
+  paths: ['request.headers.authorization', 'request.body.password'],
+});
+
+// Create Pino logger with comprehensive scrubbing
+const logger = pino({
+  level: 'info',
+  hooks: {
+    logMethod(args, method) {
+      if (args.length >= 1) {
+        const [first, ...rest] = args;
+
+        // Handle both obj-msg and msg-only formats
+        if (typeof first === 'object' && first !== null) {
+          const scrubbed = redactor.scrub(first);
+          method.apply(this, [scrubbed.data, ...rest]);
+        } else {
+          method.apply(this, args);
+        }
+      } else {
+        method.apply(this, args);
+      }
+    },
+  },
+});
+
+// Usage with nested data
+logger.info({
+  request: {
+    method: 'POST',
+    url: '/api/login',
+    headers: {
+      authorization: 'Bearer token123', // Scrubbed by path
+      'content-type': 'application/json',
+    },
+    body: {
+      username: 'john',
+      password: 'secret123', // Scrubbed by path
+    },
+  },
+  user: {
+    id: 'user-123',
+    email: 'john@example.com', // Scrubbed by GDPR_FIELDS
+  },
+  msg: 'Login attempt',
+});
+```
+
+### Pino with Child Loggers and Bindings
+
+```typescript
+import pino from 'pino';
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({ fields: HEROKU_FIELDS });
+
+const logger = pino({
+  hooks: {
+    logMethod(args, method) {
+      if (args.length >= 1 && typeof args[0] === 'object') {
+        const scrubbed = redactor.scrub(args[0]);
+        method.apply(this, [scrubbed.data, ...args.slice(1)]);
+      } else {
+        method.apply(this, args);
+      }
+    },
+  },
+});
+
+// Create child logger with bindings
+const childLogger = logger.child({
+  requestId: 'req-456',
+  userId: 'user-789',
+});
+
+// Bindings are also scrubbed
+childLogger.info({
+  password: 'secret', // Scrubbed
+  action: 'update-profile',
+});
+```
+
+---
+
+## Bunyan Integration
+
+[Bunyan](https://github.com/trentm/node-bunyan) is a JSON logging library for
+Node.js.
+
+### Basic Integration
+
+```typescript
+import bunyan from 'bunyan';
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: HEROKU_FIELDS,
+});
+
+// Custom stream that scrubs logs before writing
+class ScrubStream {
+  write(rec: bunyan.LogRecord) {
+    const scrubbed = redactor.scrub(rec);
+    console.log(JSON.stringify(scrubbed.data));
+  }
+}
+
+// Create Bunyan logger with scrubbing stream
+const logger = bunyan.createLogger({
+  name: 'myapp',
+  streams: [
+    {
+      level: 'info',
+      stream: new ScrubStream(),
+    },
+  ],
+  serializers: bunyan.stdSerializers, // Include standard serializers
+});
+
+// Usage
+logger.info(
+  {
+    user: 'john',
+    password: 'secret123', // Will be scrubbed
+    apiToken: 'token123', // Will be scrubbed
+  },
+  'User login'
+);
+```
+
+### Advanced Bunyan Integration
+
+```typescript
+import bunyan from 'bunyan';
+import {
+  createRedactor,
+  HEROKU_FIELDS,
+  GDPR_FIELDS,
+  PCI_FIELDS,
+} from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: [...HEROKU_FIELDS, ...GDPR_FIELDS, ...PCI_FIELDS],
+});
+
+// Custom serializers that scrub sensitive data
+const scrubSerializers = {
+  ...bunyan.stdSerializers,
+  // Scrub request data
+  req: (req: Record<string, unknown>) => {
+    const serialized = bunyan.stdSerializers.req(req);
+    const scrubbed = redactor.scrub(serialized);
+    return scrubbed.data;
+  },
+  // Scrub response data
+  res: (res: Record<string, unknown>) => {
+    const serialized = bunyan.stdSerializers.res(res);
+    const scrubbed = redactor.scrub(serialized);
+    return scrubbed.data;
+  },
+  // Scrub error data
+  err: (err: Error) => {
+    const serialized = bunyan.stdSerializers.err(err);
+    const scrubbed = redactor.scrub(serialized);
+    return scrubbed.data;
+  },
+  // Custom user serializer
+  user: (user: Record<string, unknown>) => {
+    const scrubbed = redactor.scrub(user);
+    return scrubbed.data;
+  },
+};
+
+class ScrubStream {
+  write(rec: bunyan.LogRecord) {
+    const scrubbed = redactor.scrub(rec);
+    process.stdout.write(JSON.stringify(scrubbed.data) + '\n');
+  }
+}
+
+const logger = bunyan.createLogger({
+  name: 'myapp',
+  streams: [
+    {
+      level: 'info',
+      stream: new ScrubStream(),
+    },
+  ],
+  serializers: scrubSerializers,
+});
+
+// Usage with serializers
+logger.info(
+  {
+    req: {
+      method: 'POST',
+      url: '/api/users',
+      headers: { authorization: 'Bearer token' },
+    },
+    user: { id: 'user-123', email: 'user@example.com', password: 'secret' },
+  },
+  'API request'
+);
+```
+
+---
+
+## Custom Logger Integration
+
+### Simple Custom Logger
+
+```typescript
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: HEROKU_FIELDS,
+});
+
+class SimpleLogger {
+  private redactor = redactor;
+
+  info(message: string, data?: Record<string, unknown>) {
+    this.log('INFO', message, data);
+  }
+
+  error(message: string, data?: Record<string, unknown>) {
+    this.log('ERROR', message, data);
+  }
+
+  warn(message: string, data?: Record<string, unknown>) {
+    this.log('WARN', message, data);
+  }
+
+  private log(level: string, message: string, data?: Record<string, unknown>) {
+    const timestamp = new Date().toISOString();
+
+    const logEntry = {
+      timestamp,
+      level,
+      message,
+      ...data,
+    };
+
+    const scrubbed = this.redactor.scrub(logEntry);
+    console.log(JSON.stringify(scrubbed.data));
+  }
+}
+
+// Usage
+const logger = new SimpleLogger();
+logger.info('User login', {
+  user: 'john',
+  password: 'secret123', // Scrubbed
+  apiToken: 'token123', // Scrubbed
+});
+```
+
+### Advanced Custom Logger with Formatting
+
+```typescript
+import { createRedactor, HEROKU_FIELDS, GDPR_FIELDS } from '@heroku/js-blanket';
+
+interface LoggerConfig {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  format: 'json' | 'pretty';
+  scrubConfig: Parameters<typeof createRedactor>[0];
+}
+
+class AdvancedLogger {
+  private config: LoggerConfig;
+  private redactor: ReturnType<typeof createRedactor>;
+
+  constructor(config: LoggerConfig) {
+    this.config = config;
+    this.redactor = createRedactor(config.scrubConfig);
+  }
+
+  debug(message: string, meta?: Record<string, unknown>) {
+    if (this.shouldLog('debug')) {
+      this.log('DEBUG', message, meta);
+    }
+  }
+
+  info(message: string, meta?: Record<string, unknown>) {
+    if (this.shouldLog('info')) {
+      this.log('INFO', message, meta);
+    }
+  }
+
+  warn(message: string, meta?: Record<string, unknown>) {
+    if (this.shouldLog('warn')) {
+      this.log('WARN', message, meta);
+    }
+  }
+
+  error(message: string, meta?: Record<string, unknown>) {
+    if (this.shouldLog('error')) {
+      this.log('ERROR', message, meta);
+    }
+  }
+
+  private shouldLog(level: string): boolean {
+    const levels = ['debug', 'info', 'warn', 'error'];
+    return levels.indexOf(level) >= levels.indexOf(this.config.level);
+  }
+
+  private log(level: string, message: string, meta?: Record<string, unknown>) {
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...meta,
+    };
+
+    const scrubbed = this.redactor.scrub(logEntry);
+
+    if (this.config.format === 'json') {
+      console.log(JSON.stringify(scrubbed.data));
+    } else {
+      this.prettyPrint(scrubbed.data);
+    }
+  }
+
+  private prettyPrint(data: Record<string, unknown>) {
+    const { timestamp, level, message, ...rest } = data;
+    console.log(`[${timestamp}] ${level}: ${message}`);
+    if (Object.keys(rest).length > 0) {
+      console.log('  ', JSON.stringify(rest, null, 2));
+    }
+  }
+}
+
+// Usage
+const logger = new AdvancedLogger({
+  level: 'info',
+  format: 'pretty',
+  scrubConfig: {
+    fields: [...HEROKU_FIELDS, ...GDPR_FIELDS],
+    paths: ['request.headers.authorization'],
+  },
+});
+
+logger.info('User authenticated', {
+  user: {
+    id: 'user-123',
+    email: 'john@example.com', // Scrubbed by GDPR_FIELDS
+    password: 'secret', // Scrubbed by HEROKU_FIELDS
+  },
+  request: {
+    method: 'POST',
+    headers: {
+      authorization: 'Bearer token', // Scrubbed by path
+    },
+  },
+});
+```
+
+---
+
+## oauth-provider-adapters Migration Example
+
+If you're migrating from `oauth-provider-adapters-for-mcp`, this is a drop-in
+replacement for the `redaction.ts` utility.
+
+### Before (oauth-provider-adapters)
+
+```typescript
+// Old implementation in oauth-provider-adapters-for-mcp
+import { redactSensitiveData } from './utils/redaction';
+
+const logger = DefaultLogger.child();
+const sensitiveData = {
+  client_id: 'my-client',
+  client_secret: 'secret123',
+  refresh_token: 'refresh123',
+};
+
+const redacted = redactSensitiveData(sensitiveData, [
+  'client_secret',
+  'refresh_token',
+  'access_token',
+]);
+
+logger.info('OAuth data:', redacted);
+```
+
+### After (@heroku/js-blanket)
+
+```typescript
+// New implementation with @heroku/js-blanket
+import { createRedactor } from '@heroku/js-blanket';
+import { DefaultLogger } from 'your-logger';
+
+const redactor = createRedactor({
+  fields: ['client_secret', 'refresh_token', 'access_token'],
+});
+
+const logger = DefaultLogger.child();
+const sensitiveData = {
+  client_id: 'my-client',
+  client_secret: 'secret123',
+  refresh_token: 'refresh123',
+};
+
+const { data: redacted } = redactor.scrub(sensitiveData);
+
+logger.info('OAuth data:', redacted);
+```
+
+### Migration Benefits
+
+1. **More powerful scrubbing**: Field-based, path-based, and pattern-based modes
+2. **Better performance**: 194k+ logs/sec average throughput
+3. **Type safety**: Full TypeScript support with generic type preservation
+4. **Presets available**: `HEROKU_FIELDS`, `GDPR_FIELDS`, `PCI_FIELDS`
+5. **Metadata tracking**: Know what was scrubbed with `scrubbedPaths`
+
+### Complete Migration Example
+
+```typescript
+import { createRedactor, HEROKU_FIELDS } from '@heroku/js-blanket';
+
+// Create a global redactor instance
+const redactor = createRedactor({
+  fields: [...HEROKU_FIELDS, 'client_secret', 'refresh_token', 'access_token'],
+  paths: ['oauth.credentials.secret'],
+});
+
+// Replace all redactSensitiveData() calls
+function redactSensitiveData<T>(data: T): T {
+  const result = redactor.scrub(data);
+  return result.data;
+}
+
+// Usage remains the same
+const scrubbed = redactSensitiveData({
+  client_id: 'my-client',
+  client_secret: 'secret123',
+  oauth: {
+    credentials: {
+      access_token: 'access123',
+      secret: 'hidden',
+    },
+  },
+});
+```
+
+---
+
+## Best Practices
+
+### 1. Create Redactor Once
+
+```typescript
+// ✅ Good: Create redactor once at module level
+const redactor = createRedactor({ fields: HEROKU_FIELDS });
+
+function logUserAction(data: Record<string, unknown>) {
+  const { data: scrubbed } = redactor.scrub(data);
+  logger.info(scrubbed);
+}
+
+// ❌ Bad: Creating redactor on every log
+function logUserAction(data: Record<string, unknown>) {
+  const redactor = createRedactor({ fields: HEROKU_FIELDS }); // Inefficient!
+  const { data: scrubbed } = redactor.scrub(data);
+  logger.info(scrubbed);
+}
+```
+
+### 2. Use Presets
+
+```typescript
+// ✅ Good: Use presets for common scenarios
+import { HEROKU_FIELDS, GDPR_FIELDS, PCI_FIELDS } from '@heroku/js-blanket';
+
+const redactor = createRedactor({
+  fields: [...HEROKU_FIELDS, ...GDPR_FIELDS, ...PCI_FIELDS],
+});
+
+// ❌ Okay but verbose: Manually listing all fields
+const redactor = createRedactor({
+  fields: ['password', 'apiToken', 'email', 'phone', 'cvv', ...],
+});
+```
+
+### 3. Combine Scrubbing Modes
+
+```typescript
+// ✅ Good: Use multiple modes for comprehensive scrubbing
+const redactor = createRedactor({
+  fields: HEROKU_FIELDS, // Scrub by field name
+  paths: ['request.headers.authorization'], // Scrub specific paths
+  patterns: [/\b\d{3}-\d{2}-\d{4}\b/g], // Scrub SSN patterns in text
+});
+```
+
+### 4. Monitor Scrubbing Activity
+
+```typescript
+// ✅ Good: Track what was scrubbed for debugging
+const result = redactor.scrub(data);
+
+if (result.scrubbed) {
+  console.log('Scrubbed paths:', result.scrubbedPaths);
+}
+
+logger.info(result.data);
+```
+
+---
+
+## Performance Considerations
+
+- **Overhead**: <0.02ms p95 for typical log entries
+- **Throughput**: 194k+ logs/sec average
+- **Memory**: Scrubbing is immutable (creates new objects)
+- **Caching**: Redactor instances cache path lookups for O(1) performance
+
+## Additional Resources
+
+- [API Documentation](../api/README.md)
+- [Core Scrubber Guide](../core/scrubber.md)
+- [Presets Reference](../core/presets.md)
+- [Performance Benchmarks](../benchmarks.md)