feat(logging): add PII scrubbing middleware with custom Winston trans…

[habnark]

Closes #210

---

Log Redaction & PII Scrubbing Middleware — Full Description

Problem Being Solved

The existing logMasker.ts only patched console.* methods. The Winston logger itself — which writes to rotating log files (external storage) — had no scrubbing at all. Any secret, private IP, JWT, or webhook URL passed to logger.info() / logger.error() was written verbatim to disk and any downstream log aggregator. This is a data exposure risk for admin credentials, internal network topology, and third-party API keys.

---

Architecture: Two Independent Scrubbing Layers

Application code calls logger.info("...", meta)
        │
        ▼
┌─────────────────────────────────────────────────┐
│  Layer 1: redactFormat  (Winston format)        │
│  scrubLogInfo() runs on every entry             │
│  before any transport sees it                   │
└──────────────────┬──────────────────────────────┘
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
┌───────────────┐    ┌──────────────────────────────┐
│ Console       │    │ Layer 2: RedactingTransport  │
│ transport     │    │ scrubLogInfo() runs again     │
│ (+ console.*  │    │ (defense-in-depth)            │
│ monkey-patch  │    │         │                    │
│ from index.ts)│    │         ▼                    │
└───────────────┘    │  DailyRotateFile             │
                     │  → logs/application-DATE.log │
                     └──────────────────────────────┘

---

File 1: src/utils/logMasker.ts (expanded)

New regex patterns added:

Pattern | What it catches | Replacement -- | -- | -- 10.x.x.x | RFC 1918 class-A private IPs | [INTERNAL_IP] 172.16-31.x.x | RFC 1918 class-B private IPs | [INTERNAL_IP] 192.168.x.x | RFC 1918 class-C private IPs | [INTERNAL_IP] 127.x.x.x | Loopback addresses | [INTERNAL_IP] 169.254.x.x | Link-local addresses | [INTERNAL_IP] ::1 | IPv6 loopback | [INTERNAL_IP] fd00::/8 | IPv6 Unique Local Addresses | [INTERNAL_IP] eyXXX.XXX.XXX | JWT tokens (3 base64url segments) | [REDACTED] discord.com/api/webhooks/… | Discord webhook URLs | [REDACTED_URL] hooks.slack.com/services/… | Slack webhook URLs | [REDACTED_URL] api_key=xxxxx | Generic key=value assignments | [REDACTED] Object key admin, cluster, node_ip, server_ip | Admin/internal fields in objects | [REDACTED]

Fixed bugs in the existing code:

• All global regexes now reset lastIndex before each replace() call — previously, stateful regexes silently skipped every second match when called on different strings
• Stellar secret key pattern tightened from 48–56 chars to exactly 55 trailing chars (total 56)

New export — scrubLogInfo(info):

• Takes a raw Winston log info object
• Scrubs message and all string/object metadata fields
• Leaves level, timestamp, and all Symbol-keyed Winston internals (Symbol(level), Symbol(splat)) completely untouched — altering these breaks Winston's internal pipeline

---

File 2: src/utils/redactingTransport.ts (new file)

A custom Winston Transport class — the "transport layer for scrubbing" the spec requires.

RedactingTransport extends Transport (winston-transport)
  │
  ├─ constructor({ inner, label, ...opts })
  │    inner = the real transport to delegate to (DailyRotateFile)
  │
  ├─ log(info, callback)
  │    1. scrubLogInfo(info)       ← PII scrub
  │    2. inner.log(scrubbed, cb)  ← delegate to file transport
  │    3. emit('logged', scrubbed) ← notify Winston backpressure system
  │    4. callback()               ← signal ready for next entry
  │
  └─ close()
       propagates close() to the inner transport so file handles
       are released cleanly on SIGINT/SIGTERM shutdown

Key design decisions:

• Does not subclass DailyRotateFile — stays generic so any transport (HTTP, S3, Datadog, etc.) can be wrapped by passing it as inner
• Handles the case where inner.log doesn't exist (graceful fallback)
• Emits 'logged' after the inner transport confirms the write — correct backpressure handling so Winston doesn't fill its internal buffer under high log volume

---

File 3: src/utils/winstonLogger.ts (updated)

Changes:

• Added redactFormat — a format(info => scrubLogInfo(info))() custom Winston format applied at the logger level, meaning it runs before the entry reaches either transport
• DailyRotateFile is now instantiated privately and wrapped in new RedactingTransport({ inner: dailyRotateFileTransport }) — callers only ever interact with the scrubbing wrapper
• LOG_LEVEL environment variable now respected (process.env.LOG_LEVEL ?? 'info') so log verbosity can be adjusted per environment without code changes
• fetcherError convenience method now has correct TypeScript typing (was previously typed as any)
• File and console transports retain their own handleExceptions: true / handleRejections: true flags so unhandled errors and promise rejections continue to be captured

[drips-wave]

@habnark Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits