feat(core): add auto-redaction for PII protection (#271)

Author: HugoRCD

.changeset/auto-redaction-pii.md

@@ -0,0 +1,5 @@
+---
+'evlog': minor
+---
+
+Add auto-redaction (PII protection) with smart partial masking, enabled by default in production (`NODE_ENV === 'production'`). Built-in patterns (credit card, email, IPv4, phone, JWT, Bearer, IBAN) use context-preserving masks (e.g. `****1111`, `a***@***.com`) instead of flat `[REDACTED]`. Disabled in development for full debugging visibility. Fine-tune with `paths`, `patterns`, and `builtins`, or opt out with `redact: false`. Custom patterns use the configurable `replacement` string. Redaction runs before console output and before any drain sees the data.

AGENTS.md

@@ -979,6 +979,75 @@ export function maskCard(card: string): string {
 - [ ] PII is masked or omitted
 - [ ] Request bodies are selectively logged (not `log.set({ body })`)
 
+### Auto-Redaction (PII Protection)
+
+Built-in redaction scrubs sensitive data from wide events **before** console output and **before** any drain sees the data. **Enabled by default in production** (`NODE_ENV === 'production'`), disabled in development for full debugging visibility. Override with `redact: false` to disable or `redact: { ... }` for fine-grained control.
+
+**Built-in patterns** (enabled by default with `redact: true`) use **smart partial masking** — preserving enough context for debugging while protecting PII:
+
+| Name | Detects | Masked Output |
+|------|---------|---------------|
+| `creditCard` | Credit card numbers | `****1111` (last 4 digits) |
+| `email` | Email addresses | `a***@***.com` (first char + TLD) |
+| `ipv4` | IPv4 addresses (excludes 127.0.0.1, 0.0.0.0) | `***.***.***.1` (last octet) |
+| `phone` | International phone numbers | `+33 ****5678` (last 4 digits) |
+| `jwt` | JWT tokens (eyJhbG...) | `eyJ***.***` (prefix only) |
+| `bearer` | Bearer tokens (Bearer sk_live_...) | `Bearer ***` (type only) |
+| `iban` | International Bank Account Numbers | `FR76****189` (country + check + last 3) |
+
+Custom `patterns` still use the flat `replacement` string (default `[REDACTED]`).
+
+```typescript
+// Simplest: enable all built-in PII patterns
+evlog: { redact: true }
+
+// Add custom paths on top of built-ins
+evlog: {
+  redact: {
+    paths: ['user.password', 'headers.authorization'],
+  }
+}
+
+// Only specific built-ins
+evlog: {
+  redact: {
+    builtins: ['email', 'creditCard'],
+  }
+}
+
+// No built-ins, only custom
+evlog: {
+  redact: {
+    builtins: false,
+    paths: ['user.ssn'],
+    patterns: [/SECRET_\w+/g],
+  }
+}
+```
+
+```typescript
+// Standalone
+import { initLogger } from 'evlog'
+
+initLogger({ redact: true })
+```
+
+**Configuration:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `redact` | `boolean \| RedactConfig` | `true` in production | Enabled by default in production. `false` to disable. Object for fine-grained control |
+| `paths` | `string[]` | `undefined` | Dot-notation paths to redact (e.g. `user.email`) |
+| `patterns` | `RegExp[]` | `undefined` | Additional regex patterns applied to all string values recursively (uses flat `replacement`) |
+| `builtins` | `false \| BuiltinPatternName[]` | all enabled | `false` disables built-ins; array selects specific ones (`'creditCard'`, `'email'`, `'ipv4'`, `'phone'`, `'jwt'`, `'bearer'`, `'iban'`) |
+| `replacement` | `string` | `'[REDACTED]'` | Replacement string for path-based and custom pattern redaction. Built-in patterns use smart partial masking instead |
+
+**Architecture:** Redaction runs inside `emitWideEvent()` after the `WideEvent` is built but before console output and `globalDrain`. This is the single chokepoint for all events. Framework middleware (`BaseEvlogOptions.redact`) also applies redaction before enrich/drain as a safety net.
+
+**Source:** `packages/evlog/src/redact.ts` — `redactEvent()` (path-based + masker-based + pattern-based), `resolveRedactConfig()` (resolves `true`/object into concrete config with `_maskers` for built-in smart masking), `normalizeRedactConfig()` (deserializes from JSON for Nitro env bridge).
+
+**Serialization note:** RegExp patterns from Nuxt config are serialized to JSON via `process.env.__EVLOG_CONFIG`. The Nitro plugin uses `normalizeRedactConfig()` to reconstruct RegExp instances from `{ source, flags }` objects or plain strings.
+
 ### Client-Side Logging
 
 The `log` API also works on the client side (auto-imported in Nuxt):

apps/docs/content/3.core-concepts/1.configuration.md

@@ -47,6 +47,7 @@ initLogger({
 | `stringify` | `boolean` | `true` | Emit JSON strings when `pretty` is disabled. Set to `false` for Cloudflare Workers |
 | `minLevel` | `'debug' \| 'info' \| 'warn' \| 'error'` | `'debug'` | Minimum severity for the global `log` API only (not `createLogger` / request wide events). Order: debug < info < warn < error |
 | `sampling` | `SamplingConfig` | `undefined` | Head and tail sampling configuration. See [Sampling](/core-concepts/sampling) |
+| `redact` | `boolean \| RedactConfig` | `true` in production | Enabled by default in production. `false` to disable. Object for fine-grained control. See [Auto-Redaction](/core-concepts/redaction) |
 | `drain` | `(ctx: DrainContext) => void` | `undefined` | Drain callback for sending events to external services |
 
 ### `minLevel` vs sampling

apps/docs/content/3.core-concepts/4.best-practices.md

@@ -29,6 +29,22 @@ Wide events are powerful because they capture comprehensive context. However, th
 Logs are often accessible to your entire team and may be stored in third-party services. Treat them as semi-public.
 ::
 
+## Auto-Redaction
+
+The simplest way to protect PII is to enable built-in auto-redaction:
+
+```typescript [nuxt.config.ts]
+evlog: {
+  redact: true,
+}
+```
+
+This automatically masks credit cards (`****1111`), emails (`a***@***.com`), IPs, phone numbers, JWTs, Bearer tokens, and IBANs in all wide events — before console output and before any drain. See [Auto-Redaction](/core-concepts/redaction) for the full configuration reference.
+
+::callout{icon="i-lucide-shield-check" color="success"}
+Auto-redaction is a safety net, not a replacement for careful logging. Always prefer explicit field selection and combine with `redact: true` for defense in depth.
+::
+
 ## Sanitization Patterns
 
 ### Manual Field Selection
@@ -167,6 +183,7 @@ Before deploying to production, verify:
 
 ### Data Security
 
+- [ ] Auto-redaction is enabled (`redact: true`)
 - [ ] No passwords or secrets in logs
 - [ ] No full credit card numbers (only last 4 digits)
 - [ ] No API keys or tokens
@@ -243,5 +260,6 @@ Use `$production` override to keep full logging in development while sampling in
 
 ## Next Steps
 
+- [Auto-Redaction](/core-concepts/redaction) - Built-in PII protection with smart masking
 - [Wide Events](/logging/wide-events) - Design effective wide events
 - [Structured Errors](/logging/structured-errors) - Error handling patterns

apps/docs/content/3.core-concepts/7.redaction.md

@@ -0,0 +1,228 @@
+---
+title: Auto-Redaction
+description: Automatically scrub PII from wide events before console output and drains. Built-in smart masking for credit cards, emails, IPs, phone numbers, JWTs, and more.
+navigation:
+  icon: i-lucide-eye-off
+links:
+  - label: Best Practices
+    icon: i-lucide-shield-check
+    to: /core-concepts/best-practices
+    color: neutral
+    variant: subtle
+  - label: Configuration
+    icon: i-lucide-settings
+    to: /core-concepts/configuration
+    color: neutral
+    variant: subtle
+---
+
+Wide events capture comprehensive context, which makes it easy to accidentally log sensitive data. Auto-redaction scrubs PII from events **before** console output and **before** any drain sees the data.
+
+**Redaction is enabled by default in production** (`NODE_ENV === 'production'`). In development, it is off so you see full values for debugging. No configuration needed — just deploy.
+
+## Opting Out
+
+If you need to disable redaction in production:
+
+::code-group
+```typescript [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['evlog/nuxt'],
+  evlog: {
+    redact: false,
+  },
+})
+```
+```typescript [lib/evlog.ts (Next.js)]
+import { createEvlog } from 'evlog/next'
+
+export const { withEvlog, useLogger } = createEvlog({
+  service: 'my-app',
+  redact: false,
+})
+```
+```typescript [index.ts (Hono / Express / Fastify)]
+import { initLogger } from 'evlog'
+
+initLogger({
+  env: { service: 'my-app' },
+  redact: false,
+})
+```
+::
+
+You can also enable redaction explicitly in development with `redact: true`.
+
+## Smart Masking
+
+Built-in patterns use **partial masking** instead of flat `[REDACTED]` — preserving enough context for debugging while protecting the actual data.
+
+| Pattern | Example Input | Masked Output |
+|---------|---------------|---------------|
+| `creditCard` | `4111111111111111` | `****1111` |
+| `email` | `alice@example.com` | `a***@***.com` |
+| `ipv4` | `192.168.1.100` | `***.***.***.100` |
+| `phone` | `+33 6 12 34 56 78` | `+33 ****5678` |
+| `jwt` | `eyJhbGciOiJIUzI1NiIs...` | `eyJ***.***` |
+| `bearer` | `Bearer sk_live_abc123...` | `Bearer ***` |
+| `iban` | `FR76 3000 6000 0112 ...189` | `FR76****189` |
+
+::callout{icon="i-lucide-info" color="info"}
+`127.0.0.1` and `0.0.0.0` are excluded from IPv4 masking since they are not real client addresses.
+::
+
+## Configuration
+
+### Custom Paths
+
+Add dot-notation paths to redact specific fields with `[REDACTED]`, on top of the built-in patterns:
+
+```typescript
+evlog: {
+  redact: {
+    paths: ['user.password', 'headers.authorization'],
+  }
+}
+```
+
+Path-based redaction replaces the **entire value** with the `replacement` string (default `[REDACTED]`), regardless of content.
+
+### Selective Built-ins
+
+Pick only the patterns you need:
+
+```typescript
+evlog: {
+  redact: {
+    builtins: ['email', 'creditCard'],
+  }
+}
+```
+
+### Custom Patterns
+
+Add your own regex patterns. These use the flat `replacement` string, not smart masking:
+
+```typescript
+evlog: {
+  redact: {
+    patterns: [/SECRET_\w+/g, /sk_live_\w+/g],
+    replacement: '***',
+  }
+}
+```
+
+### Disable Built-ins
+
+If you only want custom redaction:
+
+```typescript
+evlog: {
+  redact: {
+    builtins: false,
+    paths: ['user.ssn'],
+    patterns: [/INTERNAL_\w+/g],
+  }
+}
+```
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `redact` | `boolean \| RedactConfig` | `true` in production | Enabled by default in production. `false` to disable. Object for fine-grained control |
+| `paths` | `string[]` | `undefined` | Dot-notation paths to redact entirely (e.g. `user.password`) |
+| `patterns` | `RegExp[]` | `undefined` | Custom regex patterns. Uses flat `replacement` string |
+| `builtins` | `false \| string[]` | All enabled | `false` disables built-ins. Array selects specific ones |
+| `replacement` | `string` | `'[REDACTED]'` | Replacement string for paths and custom patterns. Built-in patterns use smart masking instead |
+
+Available built-in names: `creditCard`, `email`, `ipv4`, `phone`, `jwt`, `bearer`, `iban`.
+
+## How It Works
+
+Redaction runs inside the emit pipeline, after the wide event is fully built but before any output:
+
+1. **Path redaction** — targeted fields replaced with `[REDACTED]`
+2. **Smart masking** — built-in patterns scan all string values recursively with partial masking
+3. **Pattern redaction** — custom regex patterns scan all string values with flat replacement
+4. **Console output** — masked event printed to stdout
+5. **Drain** — masked event sent to external services
+
+::callout{icon="i-lucide-zap" color="info"}
+Redaction runs **after** the HTTP response is sent, so it adds zero latency to your API responses.
+::
+
+## Production Example
+
+Redaction is already on by default in production. Combine with sampling for a typical setup:
+
+::code-group
+```typescript [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['evlog/nuxt'],
+  evlog: {
+    env: { service: 'my-app' },
+  },
+  $production: {
+    evlog: {
+      sampling: {
+        rates: { info: 10, debug: 0 },
+        keep: [{ status: 400 }, { duration: 1000 }],
+      },
+    },
+  },
+})
+```
+```typescript [lib/evlog.ts (Next.js)]
+import { createEvlog } from 'evlog/next'
+
+export const { withEvlog, useLogger } = createEvlog({
+  service: 'my-app',
+  sampling: {
+    rates: { info: 10, debug: 0 },
+    keep: [{ status: 400 }, { duration: 1000 }],
+  },
+})
+```
+```typescript [index.ts (Hono / Express / Fastify)]
+import { initLogger } from 'evlog'
+
+initLogger({
+  env: { service: 'my-app' },
+  sampling: {
+    rates: { info: 10, debug: 0 },
+    keep: [{ status: 400 }, { duration: 1000 }],
+  },
+})
+```
+::
+
+## Before / After
+
+Without redaction, sensitive data lands in your logs and drains:
+
+```json
+{
+  "user": { "email": "alice@example.com", "ip": "192.168.1.42" },
+  "payment": { "card": "4111111111111111" },
+  "auth": "Bearer sk_live_abc123def456"
+}
+```
+
+With `redact: true`:
+
+```json
+{
+  "user": { "email": "a***@***.com", "ip": "***.***.***.42" },
+  "payment": { "card": "****1111" },
+  "auth": "Bearer ***"
+}
+```
+
+Same debugging context, no PII in your Axiom/Datadog/Sentry.
+
+## Next Steps
+
+- [Best Practices](/core-concepts/best-practices) - Security guidelines and production checklist
+- [Sampling](/core-concepts/sampling) - Control log volume in production
+- [Configuration](/core-concepts/configuration) - Full configuration reference