data-sanitization-log-providers 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Mark Jubenville
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# data-sanitization-log-providers
+
+Pre-built log provider adapters for [`data-sanitization`](https://github.com/ioncache/data-sanitization).
+Each adapter wires `sanitizeData` into the logger's native hook or transport API so you don't
+have to write the glue yourself.
+
+## Installation
+
+```bash
+npm install data-sanitization data-sanitization-log-providers
+```
+
+npm is used as an example — yarn, pnpm, and bun work the same way.
+
+Install only the peer dependency for the logger you use:
+
+```bash
+npm install pino                          # for /pino-hook
+npm install pino pino-abstract-transport  # for /pino-transport
+npm install winston                       # for /winston
+```
+
+## Pino — stream write hook (`/pino-hook`)
+
+Runs synchronously in the main thread. Sanitizes each log line and optionally prepends a
+structured warning entry when sensitive fields are found.
+
+```typescript
+import pino from 'pino';
+import { createSanitizeLogLine } from 'data-sanitization-log-providers/pino-hook';
+
+const logger = pino({
+  hooks: {
+    streamWrite: createSanitizeLogLine({
+      // Any DataSanitizationReplacerOptions:
+      customPatterns: ['email', 'health_card'],
+      // Fields to carry into the warning entry (default: ['time', 'pid', 'hostname']):
+      allowedFields: ['time', 'pid', 'hostname'],
+    }),
+  },
+});
+```
+
+The hook function signature is `(s: string) => string`, matching pino's `hooks.streamWrite`
+contract. When a field is sanitized, a `level: 40` warning line is prepended:
+
+```json
+{"time":1716667200000,"pid":1234,"hostname":"api-1","level":40,"msg":"sensitive data found in log entry","fields":["password"]}
+{"time":1716667200000,"pid":1234,"hostname":"api-1","level":30,"msg":"user login","password":"**********"}
+```
+
+### Error handling
+
+When `sanitizeData` throws, the default behaviour is to emit an error-level (50) JSON
+placeholder preserving `time`, `pid`, and `hostname` — the original line is not emitted.
+Override this with `onError`:
+
+```typescript
+createSanitizeLogLine({
+  onError: (err, original) => {
+    myErrorTracker.capture(err);
+    return '{"level":50,"msg":"sanitization failed"}\n';
+  },
+});
+```
+
+## Pino — worker thread transport (`/pino-transport`)
+
+Runs in a `pino.transport()` worker thread via `pino-abstract-transport`. Use this when you
+want process isolation or need to fan out to multiple destinations.
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  transport: {
+    target: 'data-sanitization-log-providers/pino-transport',
+    options: {
+      customPatterns: ['email'],
+      allowedFields: ['time', 'pid', 'hostname'],
+    },
+  },
+});
+```
+
+**Note:** `customMatchers` (custom matcher functions) is not supported via the transport
+because functions cannot be serialized across the worker-thread boundary. Use the
+`/pino-hook` adapter when custom matcher functions are required.
+
+## Winston (`/winston`)
+
+A `TransportStream` subclass that sanitizes each log entry before writing. Compose it with
+`winston.format.json()` (or equivalent) so that `info[Symbol.for('message')]` is populated
+before the transport runs.
+
+```typescript
+import winston from 'winston';
+import { createSanitizingTransport } from 'data-sanitization-log-providers/winston';
+
+const logger = winston.createLogger({
+  format: winston.format.json(),
+  transports: [
+    createSanitizingTransport({
+      sanitize: { customPatterns: ['email'] },
+    }),
+  ],
+});
+```
+
+### Warning lines (`emitWarning`)
+
+The `emitWarning` option is disabled by default. When enabled, a structured warning entry is
+written to the output stream immediately before the sanitized line:
+
+```typescript
+createSanitizingTransport({
+  emitWarning: true,
+  allowedFields: ['timestamp', 'service'],
+});
+```
+
+**Why `emitWarning` is opt-in:** Winston formats are 1-to-1 — one `info` object produces one
+serialized `MESSAGE` string. There is no built-in way to emit a second log line from a format
+transform. This transport subclass owns the write path directly, which makes the two-line
+pattern possible. However, structured log aggregators that expect exactly one JSON object per
+write call may not handle the extra line correctly. Enable this option only when writing to a
+file or stream where embedded newlines are safe.
+
+### Error handling (`onError`)
+
+When `sanitizeData` throws, an error-level placeholder is written in place of the original
+line. Provide `onError` to be notified:
+
+```typescript
+createSanitizingTransport({
+  onError: (err) => myErrorTracker.capture(err),
+});
+```

package/dist/pino-hook.d.ts

@@ -0,0 +1,23 @@
+import type { PinoHookOptions } from './types.js';
+/**
+ * Creates a sanitizing function for pino's `hooks.streamWrite` option.
+ *
+ * The returned function sanitizes each log line synchronously in the main
+ * thread. When sensitive fields are found, a structured warning entry is
+ * prepended so the sanitization event is visible in log aggregators. On
+ * error, the default handler emits an error-level (50) JSON placeholder
+ * preserving `time`, `pid`, and `hostname` for traceability.
+ *
+ * @param options - Sanitization and hook options.
+ * @returns A `(s: string) => string` function for `pino({ hooks: { streamWrite: fn } })`.
+ *
+ * @example
+ * import pino from 'pino';
+ * import { createSanitizeLogLine } from 'data-sanitization-log-providers/pino-hook';
+ *
+ * const logger = pino({
+ *   hooks: { streamWrite: createSanitizeLogLine({ customPatterns: ['email'] }) },
+ * });
+ */
+declare function createSanitizeLogLine(options?: PinoHookOptions): (s: string) => string;
+export { createSanitizeLogLine };

package/dist/pino-hook.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSanitizeLogLine = createSanitizeLogLine;
+const shared_js_1 = require("./shared.js");
+/**
+ * Creates a sanitizing function for pino's `hooks.streamWrite` option.
+ *
+ * The returned function sanitizes each log line synchronously in the main
+ * thread. When sensitive fields are found, a structured warning entry is
+ * prepended so the sanitization event is visible in log aggregators. On
+ * error, the default handler emits an error-level (50) JSON placeholder
+ * preserving `time`, `pid`, and `hostname` for traceability.
+ *
+ * @param options - Sanitization and hook options.
+ * @returns A `(s: string) => string` function for `pino({ hooks: { streamWrite: fn } })`.
+ *
+ * @example
+ * import pino from 'pino';
+ * import { createSanitizeLogLine } from 'data-sanitization-log-providers/pino-hook';
+ *
+ * const logger = pino({
+ *   hooks: { streamWrite: createSanitizeLogLine({ customPatterns: ['email'] }) },
+ * });
+ */
+function createSanitizeLogLine(options = {}) {
+    const { onError, allowedFields = shared_js_1.PINO_DEFAULT_ALLOWED_FIELDS, ...sanitizeOptions } = options;
+    return function sanitizeLogLine(s) {
+        let result;
+        try {
+            result = (0, shared_js_1.sanitizeLine)(s, sanitizeOptions, allowedFields);
+        }
+        catch (err) {
+            if (onError) {
+                return onError(err, s);
+            }
+            return (0, shared_js_1.buildErrorPlaceholder)(s) + '\n';
+        }
+        const { sanitized, warning } = result;
+        if (warning) {
+            return warning + '\n' + sanitized;
+        }
+        return sanitized;
+    };
+}
+//# sourceMappingURL=pino-hook.js.map

package/dist/pino-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino-hook.js","sourceRoot":"","sources":["../src/pino-hook.ts"],"names":[],"mappings":";;AAuDS,sDAAqB;AAvD9B,2CAIqB;AAGrB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,qBAAqB,CAC5B,UAA2B,EAAE;IAE7B,MAAM,EACJ,OAAO,EACP,aAAa,GAAG,uCAA2B,EAC3C,GAAG,eAAe,EACnB,GAAG,OAAO,CAAC;IAEZ,OAAO,SAAS,eAAe,CAAC,CAAS;QACvC,IAAI,MAAuC,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,GAAG,IAAA,wBAAY,EAAC,CAAC,EAAE,eAAe,EAAE,aAAa,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACzB,CAAC;YACD,OAAO,IAAA,iCAAqB,EAAC,CAAC,CAAC,GAAG,IAAI,CAAC;QACzC,CAAC;QAED,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACtC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;QACpC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/pino-transport.d.ts

@@ -0,0 +1,27 @@
+import type { PinoTransportOptions } from './types.js';
+/**
+ * Pino `pino-abstract-transport` worker module.
+ *
+ * Use as the `target` for `pino.transport()`. Sanitizes each log line and
+ * writes the result to `process.stdout`. When sensitive fields are found, a
+ * structured warning entry is written first so the sanitization event is
+ * visible in log aggregators. On error, an error-level (50) JSON placeholder
+ * is written in place of the original line.
+ *
+ * Note: `customMatchers` is not supported because functions cannot be
+ * serialized across the worker-thread boundary. Use the `/pino-hook` adapter
+ * when custom matcher functions are required.
+ *
+ * @param opts - Serializable sanitization options passed via `pino.transport({ options: ... })`.
+ *
+ * @example
+ * import pino from 'pino';
+ *
+ * const logger = pino({
+ *   transport: {
+ *     target: 'data-sanitization-log-providers/pino-transport',
+ *     options: { customPatterns: ['email'] },
+ *   },
+ * });
+ */
+export default function pinoTransport(opts?: PinoTransportOptions): Promise<unknown>;

package/dist/pino-transport.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = pinoTransport;
+const node_events_1 = require("node:events");
+const pino_abstract_transport_1 = __importDefault(require("pino-abstract-transport"));
+const writeLine = async (line) => {
+    if (!process.stdout.write(line + '\n')) {
+        await (0, node_events_1.once)(process.stdout, 'drain');
+    }
+};
+const shared_js_1 = require("./shared.js");
+/**
+ * Pino `pino-abstract-transport` worker module.
+ *
+ * Use as the `target` for `pino.transport()`. Sanitizes each log line and
+ * writes the result to `process.stdout`. When sensitive fields are found, a
+ * structured warning entry is written first so the sanitization event is
+ * visible in log aggregators. On error, an error-level (50) JSON placeholder
+ * is written in place of the original line.
+ *
+ * Note: `customMatchers` is not supported because functions cannot be
+ * serialized across the worker-thread boundary. Use the `/pino-hook` adapter
+ * when custom matcher functions are required.
+ *
+ * @param opts - Serializable sanitization options passed via `pino.transport({ options: ... })`.
+ *
+ * @example
+ * import pino from 'pino';
+ *
+ * const logger = pino({
+ *   transport: {
+ *     target: 'data-sanitization-log-providers/pino-transport',
+ *     options: { customPatterns: ['email'] },
+ *   },
+ * });
+ */
+async function pinoTransport(opts = {}) {
+    const { allowedFields = shared_js_1.PINO_DEFAULT_ALLOWED_FIELDS, ...sanitizeOptions } = opts;
+    return (0, pino_abstract_transport_1.default)(async function (source) {
+        for await (const line of source) {
+            try {
+                const { sanitized, warning } = (0, shared_js_1.sanitizeLine)(line, sanitizeOptions, allowedFields);
+                if (warning) {
+                    await writeLine(warning);
+                }
+                await writeLine(sanitized);
+            }
+            catch {
+                await writeLine((0, shared_js_1.buildErrorPlaceholder)(line));
+            }
+        }
+    }, { parse: 'lines' });
+}
+//# sourceMappingURL=pino-transport.js.map

package/dist/pino-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pino-transport.js","sourceRoot":"","sources":["../src/pino-transport.ts"],"names":[],"mappings":";;;;;AAwCA,gCA0BC;AAlED,6CAAmC;AACnC,sFAA4C;AAE5C,MAAM,SAAS,GAAG,KAAK,EAAE,IAAY,EAAiB,EAAE;IACtD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAA,kBAAI,EAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;AACH,CAAC,CAAC;AACF,2CAIqB;AAGrB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACY,KAAK,UAAU,aAAa,CACzC,OAA6B,EAAE;IAE/B,MAAM,EAAE,aAAa,GAAG,uCAA2B,EAAE,GAAG,eAAe,EAAE,GACvE,IAAI,CAAC;IAEP,OAAO,IAAA,iCAAK,EACV,KAAK,WAAW,MAA6B;QAC3C,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAA,wBAAY,EACzC,IAAI,EACJ,eAAe,EACf,aAAa,CACd,CAAC;gBACF,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;gBAC3B,CAAC;gBACD,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,SAAS,CAAC,IAAA,iCAAqB,EAAC,IAAI,CAAC,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC,EACD,EAAE,KAAK,EAAE,OAAO,EAAE,CACnB,CAAC;AACJ,CAAC"}

package/dist/shared.d.ts

@@ -0,0 +1,27 @@
+import { type DataSanitizationReplacerOptions } from 'data-sanitization';
+declare const PINO_DEFAULT_ALLOWED_FIELDS: readonly ["time", "pid", "hostname"];
+interface SanitizeLineResult {
+    sanitized: string;
+    warning: string | null;
+}
+/**
+ * Sanitizes a JSON log line and returns the sanitized string plus an optional
+ * warning line.
+ *
+ * @param line - Raw log line to sanitize (with or without trailing newline).
+ * @param sanitizeOptions - Options forwarded to `sanitizeData`.
+ * @param allowedFields - Fields to carry into the warning entry.
+ * @returns Object with `sanitized` and `warning` (`null` when no fields changed).
+ */
+declare function sanitizeLine(line: string, sanitizeOptions: DataSanitizationReplacerOptions, allowedFields: readonly string[]): SanitizeLineResult;
+/**
+ * Builds a JSON error-level placeholder from a raw log line, preserving
+ * `time`, `pid`, and `hostname` for traceability without re-emitting
+ * potentially unsanitized content.
+ *
+ * @param original - Original log line before sanitization.
+ * @returns A JSON string at level 50 indicating sanitization failure.
+ */
+declare function buildErrorPlaceholder(original: string): string;
+export { sanitizeLine, buildErrorPlaceholder, PINO_DEFAULT_ALLOWED_FIELDS };
+export type { SanitizeLineResult };

package/dist/shared.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PINO_DEFAULT_ALLOWED_FIELDS = void 0;
+exports.sanitizeLine = sanitizeLine;
+exports.buildErrorPlaceholder = buildErrorPlaceholder;
+const data_sanitization_1 = require("data-sanitization");
+const utils_1 = require("data-sanitization/utils");
+const ERROR_LEVEL = 50;
+const ERROR_MSG = 'log entry dropped: sanitization failed';
+const PINO_DEFAULT_ALLOWED_FIELDS = Object.freeze([
+    'time',
+    'pid',
+    'hostname',
+]);
+exports.PINO_DEFAULT_ALLOWED_FIELDS = PINO_DEFAULT_ALLOWED_FIELDS;
+/**
+ * Sanitizes a JSON log line and returns the sanitized string plus an optional
+ * warning line.
+ *
+ * @param line - Raw log line to sanitize (with or without trailing newline).
+ * @param sanitizeOptions - Options forwarded to `sanitizeData`.
+ * @param allowedFields - Fields to carry into the warning entry.
+ * @returns Object with `sanitized` and `warning` (`null` when no fields changed).
+ */
+function sanitizeLine(line, sanitizeOptions, allowedFields) {
+    const sanitized = (0, data_sanitization_1.sanitizeData)(line, sanitizeOptions);
+    const warning = sanitized !== line
+        ? (0, utils_1.buildSanitizedWarning)(line, sanitized, { allowedFields })
+        : null;
+    return { sanitized, warning };
+}
+/**
+ * Builds a JSON error-level placeholder from a raw log line, preserving
+ * `time`, `pid`, and `hostname` for traceability without re-emitting
+ * potentially unsanitized content.
+ *
+ * @param original - Original log line before sanitization.
+ * @returns A JSON string at level 50 indicating sanitization failure.
+ */
+function buildErrorPlaceholder(original) {
+    try {
+        const parsed = JSON.parse(original);
+        const { time, pid, hostname } = parsed;
+        return JSON.stringify({
+            level: ERROR_LEVEL,
+            ...(time !== undefined && { time }),
+            ...(pid !== undefined && { pid }),
+            ...(hostname !== undefined && { hostname }),
+            msg: ERROR_MSG,
+        });
+    }
+    catch {
+        /* istanbul ignore next -- only reached when original is not valid JSON */
+        return JSON.stringify({ level: ERROR_LEVEL, msg: ERROR_MSG });
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":";;;AAkES,oCAAY;AAAE,sDAAqB;AAlE5C,yDAG2B;AAC3B,mDAAgE;AAEhE,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,SAAS,GAAG,wCAAwC,CAAC;AAC3D,MAAM,2BAA2B,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,MAAM;IACN,KAAK;IACL,UAAU;CACF,CAAC,CAAC;AAsDkC,kEAA2B;AA/CzE;;;;;;;;GAQG;AACH,SAAS,YAAY,CACnB,IAAY,EACZ,eAAgD,EAChD,aAAgC;IAEhC,MAAM,SAAS,GAAG,IAAA,gCAAY,EAAC,IAAI,EAAE,eAAe,CAAW,CAAC;IAChE,MAAM,OAAO,GACX,SAAS,KAAK,IAAI;QAChB,CAAC,CAAC,IAAA,6BAAqB,EAAC,IAAI,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,CAAC;QAC3D,CAAC,CAAC,IAAI,CAAC;IACX,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,qBAAqB,CAAC,QAAgB;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAA4B,CAAC;QAC/D,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;QACvC,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,WAAW;YAClB,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;YACnC,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC3C,GAAG,EAAE,SAAS;SACf,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+import type { DataSanitizationReplacerOptions } from 'data-sanitization';
+/**
+ * Options for {@link createSanitizeLogLine}.
+ */
+interface PinoHookOptions extends DataSanitizationReplacerOptions {
+    /**
+     * Fields from the sanitized log object to carry into the warning entry.
+     *
+     * Default: `['time', 'pid', 'hostname']`.
+     */
+    allowedFields?: readonly string[];
+    /**
+     * Called when `sanitizeData` throws. Must return a string to write in place
+     * of the original log line. Default: emits an error-level (50) JSON
+     * placeholder preserving `time`, `pid`, and `hostname` from the original.
+     */
+    onError?: (err: unknown, original: string) => string;
+}
+/**
+ * Options for the pino transport default export.
+ *
+ * Extends {@link DataSanitizationReplacerOptions} except for `customMatchers`,
+ * which cannot be serialized across the worker-thread boundary. Use the
+ * `/pino-hook` adapter when custom matcher functions are required.
+ */
+type PinoTransportOptions = Omit<DataSanitizationReplacerOptions, 'customMatchers'> & {
+    /**
+     * Fields from the sanitized log object to carry into the warning entry.
+     *
+     * Default: `['time', 'pid', 'hostname']`.
+     */
+    allowedFields?: readonly string[];
+};
+/**
+ * Options for {@link createSanitizingTransport}.
+ */
+interface WinstonSanitizationOptions {
+    /** Standard winston transport options (level, silent, handleExceptions). */
+    level?: string;
+    silent?: boolean;
+    handleExceptions?: boolean;
+    handleRejections?: boolean;
+    /**
+     * Sanitization options forwarded to `sanitizeData`.
+     */
+    sanitize?: DataSanitizationReplacerOptions;
+    /**
+     * Fields from the sanitized log object to carry into the warning entry.
+     *
+     * Default: `[]` — no fields carry through unless explicitly listed. Winston
+     * has no standardized correlation-field convention, so callers opt in
+     * explicitly (e.g. `['timestamp', 'service']`).
+     */
+    allowedFields?: readonly string[];
+    /**
+     * When `true`, a structured warning line is written to the output stream
+     * immediately before the sanitized line as a separate `stream.write()` call.
+     *
+     * Winston formats are 1-to-1 (one `info` object → one serialized `MESSAGE`
+     * string), so there is no built-in way to emit a second log line from a
+     * format transform. This transport subclass owns the write path, which makes
+     * the two-line pattern possible. Enable only when writing to a file or
+     * stream — structured aggregators that expect exactly one JSON object per
+     * write call may not handle the extra line correctly.
+     *
+     * Default: `false`.
+     */
+    emitWarning?: boolean;
+    /**
+     * Output stream. Default: `process.stdout`.
+     */
+    stream?: NodeJS.WritableStream;
+    /**
+     * Called when `sanitizeData` throws. Default: emits an error-level
+     * placeholder to the output stream and continues processing.
+     */
+    onError?: (err: unknown) => void;
+}
+export type { PinoHookOptions, PinoTransportOptions, WinstonSanitizationOptions, };

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/winston.d.ts

@@ -0,0 +1,45 @@
+import TransportStream from 'winston-transport';
+import type { WinstonSanitizationOptions } from './types.js';
+/**
+ * A winston `TransportStream` that sanitizes log entries before writing them.
+ *
+ * Reads `info[Symbol.for('message')]` (the final serialized string produced by
+ * upstream formats such as `format.json()`), sanitizes it, and writes the
+ * result to the configured output stream. When `emitWarning` is enabled, a
+ * structured warning line is written first as a separate `stream.write()` call.
+ *
+ * Add this transport after a serializing format in the format chain so that
+ * `info[MESSAGE]` is already a JSON string when `log()` is called.
+ */
+declare class SanitizingTransport extends TransportStream {
+    #private;
+    constructor(opts?: WinstonSanitizationOptions);
+    log(info: any, callback: () => void): void;
+}
+/**
+ * Creates a sanitizing winston transport.
+ *
+ * Sanitizes each log entry's serialized `MESSAGE` string before writing it to
+ * the output stream. Compose with `winston.format.json()` (or equivalent) so
+ * that the `MESSAGE` symbol is populated before sanitization runs.
+ *
+ * @param options - Transport and sanitization options.
+ * @returns A configured {@link SanitizingTransport} instance.
+ *
+ * @example
+ * import winston from 'winston';
+ * import { createSanitizingTransport } from 'data-sanitization-log-providers/winston';
+ *
+ * const logger = winston.createLogger({
+ *   format: winston.format.json(),
+ *   transports: [
+ *     createSanitizingTransport({
+ *       sanitize: { customPatterns: ['email'] },
+ *       allowedFields: ['timestamp', 'service'],
+ *       emitWarning: true,
+ *     }),
+ *   ],
+ * });
+ */
+declare function createSanitizingTransport(options?: WinstonSanitizationOptions): SanitizingTransport;
+export { createSanitizingTransport, SanitizingTransport };

package/dist/winston.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SanitizingTransport = void 0;
+exports.createSanitizingTransport = createSanitizingTransport;
+const winston_transport_1 = __importDefault(require("winston-transport"));
+const shared_js_1 = require("./shared.js");
+const MESSAGE = Symbol.for('message');
+/**
+ * A winston `TransportStream` that sanitizes log entries before writing them.
+ *
+ * Reads `info[Symbol.for('message')]` (the final serialized string produced by
+ * upstream formats such as `format.json()`), sanitizes it, and writes the
+ * result to the configured output stream. When `emitWarning` is enabled, a
+ * structured warning line is written first as a separate `stream.write()` call.
+ *
+ * Add this transport after a serializing format in the format chain so that
+ * `info[MESSAGE]` is already a JSON string when `log()` is called.
+ */
+class SanitizingTransport extends winston_transport_1.default {
+    #sanitizeOptions;
+    #allowedFields;
+    #emitWarning;
+    #dest;
+    #onError;
+    constructor(opts = {}) {
+        const { sanitize = {}, allowedFields = [], emitWarning = false, stream: dest = process.stdout, onError, ...rest } = opts;
+        super(rest);
+        this.#sanitizeOptions = sanitize;
+        this.#allowedFields = allowedFields;
+        this.#emitWarning = emitWarning;
+        this.#dest = dest;
+        this.#onError = onError ?? (() => undefined);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    log(info, callback) {
+        const raw = info[MESSAGE];
+        let sanitized;
+        let warning = null;
+        try {
+            const input = typeof raw === 'string' ? raw : JSON.stringify(info);
+            ({ sanitized, warning } = (0, shared_js_1.sanitizeLine)(input, this.#sanitizeOptions, this.#allowedFields));
+        }
+        catch (err) {
+            this.#onError(err);
+            this.#dest.write((0, shared_js_1.buildErrorPlaceholder)(raw ?? '') + '\n');
+            this.emit('logged', info);
+            callback();
+            return;
+        }
+        if (this.#emitWarning && warning) {
+            this.#dest.write(warning + '\n');
+        }
+        this.#dest.write(sanitized + '\n');
+        this.emit('logged', info);
+        callback();
+    }
+}
+exports.SanitizingTransport = SanitizingTransport;
+/**
+ * Creates a sanitizing winston transport.
+ *
+ * Sanitizes each log entry's serialized `MESSAGE` string before writing it to
+ * the output stream. Compose with `winston.format.json()` (or equivalent) so
+ * that the `MESSAGE` symbol is populated before sanitization runs.
+ *
+ * @param options - Transport and sanitization options.
+ * @returns A configured {@link SanitizingTransport} instance.
+ *
+ * @example
+ * import winston from 'winston';
+ * import { createSanitizingTransport } from 'data-sanitization-log-providers/winston';
+ *
+ * const logger = winston.createLogger({
+ *   format: winston.format.json(),
+ *   transports: [
+ *     createSanitizingTransport({
+ *       sanitize: { customPatterns: ['email'] },
+ *       allowedFields: ['timestamp', 'service'],
+ *       emitWarning: true,
+ *     }),
+ *   ],
+ * });
+ */
+function createSanitizingTransport(options = {}) {
+    return new SanitizingTransport(options);
+}
+//# sourceMappingURL=winston.js.map

package/dist/winston.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"winston.js","sourceRoot":"","sources":["../src/winston.ts"],"names":[],"mappings":";;;;;;AA0GS,8DAAyB;AA1GlC,0EAAgD;AAChD,2CAAkE;AAIlE,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,MAAM,mBAAoB,SAAQ,2BAAe;IACtC,gBAAgB,CAAkC;IAClD,cAAc,CAAoB;IAClC,YAAY,CAAU;IACtB,KAAK,CAAwB;IAC7B,QAAQ,CAAyB;IAE1C,YAAY,OAAmC,EAAE;QAC/C,MAAM,EACJ,QAAQ,GAAG,EAAE,EACb,aAAa,GAAG,EAAE,EAClB,WAAW,GAAG,KAAK,EACnB,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAC7B,OAAO,EACP,GAAG,IAAI,EACR,GAAG,IAAI,CAAC;QACT,KAAK,CAAC,IAAwD,CAAC,CAAC;QAChE,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC;QACjC,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;QACpC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,8DAA8D;IACrD,GAAG,CAAC,IAAS,EAAE,QAAoB;QAC1C,MAAM,GAAG,GAAI,IAAgC,CAAC,OAAO,CAExC,CAAC;QAEd,IAAI,SAAiB,CAAC;QACtB,IAAI,OAAO,GAAkB,IAAI,CAAC;QAElC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACnE,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,IAAA,wBAAY,EACpC,KAAK,EACL,IAAI,CAAC,gBAAgB,EACrB,IAAI,CAAC,cAAc,CACpB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAA,iCAAqB,EAAC,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YAC1D,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC1B,QAAQ,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,IAAI,OAAO,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC1B,QAAQ,EAAE,CAAC;IACb,CAAC;CACF;AAiCmC,kDAAmB;AA/BvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAS,yBAAyB,CAChC,UAAsC,EAAE;IAExC,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "data-sanitization-log-providers",
+  "version": "1.1.0",
+  "description": "Pre-built log provider adapters for data-sanitization (pino, winston).",
+  "keywords": [
+    "data-sanitization",
+    "logging",
+    "pino",
+    "redact",
+    "sanitization",
+    "sanitize",
+    "sensitive-data",
+    "typescript",
+    "winston"
+  ],
+  "homepage": "https://github.com/ioncache/data-sanitization/tree/main/packages/data-sanitization-log-providers",
+  "bugs": {
+    "url": "https://github.com/ioncache/data-sanitization/issues"
+  },
+  "license": "MIT",
+  "author": "Mark Jubenville <ioncache@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ioncache/data-sanitization.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./pino-hook": {
+      "types": "./dist/pino-hook.d.ts",
+      "default": "./dist/pino-hook.js"
+    },
+    "./pino-transport": {
+      "types": "./dist/pino-transport.d.ts",
+      "default": "./dist/pino-transport.js"
+    },
+    "./winston": {
+      "types": "./dist/winston.d.ts",
+      "default": "./dist/winston.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "yarn clean && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist coverage && find . -maxdepth 1 -name '*.tsbuildinfo' -delete",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "prepack": "yarn build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.0",
+    "@vitest/coverage-v8": "^4.1.6",
+    "data-sanitization": "1.5.0",
+    "oxfmt": "^0.51.0",
+    "oxlint": "^1.66.0",
+    "pino": "^9.0.0",
+    "pino-abstract-transport": "^2.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "winston": "^3.19.0",
+    "winston-transport": "^4.9.0"
+  },
+  "peerDependencies": {
+    "data-sanitization": ">=1.5.0",
+    "pino": ">=9.0.0",
+    "pino-abstract-transport": ">=2.0.0",
+    "winston": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pino": {
+      "optional": true
+    },
+    "pino-abstract-transport": {
+      "optional": true
+    },
+    "winston": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.22.1"
+  },
+  "volta": {
+    "node": "22.22.3",
+    "yarn": "4.15.0"
+  }
+}